Date: 2026-04-08
Source: docs/internal/ZEPTOVM-SPEC-v03-review.md (Codex design review)
Compared against: Current implementation (781 tests with --features cli, ~17k LOC)
| # | Critique | Status | Details |
|---|
| C1 | Soften "deterministic shell" claim | DONE | Reworded to "replay-safe shell" + HANDLER-CONVENTIONS.md |
| C2 | Turn atomicity — explicit commit protocol | DONE | TurnExecutor::open_in_memory() uses shared SQLite connection for atomic journal+snapshot commits |
| C3 | Separate scheduling fairness from economic fairness | DONE | Reduction counter separate from BudgetGate |
| C4 | Single-threaded scheduler — handler discipline | DONE | Watchdog: max_turn_wall_clock + turn_overrun_flag + tracing::warn on overrun |
| C5 | Collapse two behavior traits to one | DONE | Only StepBehavior exists |
| # | Addition | Status | Details |
|---|
| A1 | ObjectRef type | DONE | ObjectRef type + ArtifactBackend trait + SqliteArtifactStore + ObjectPut/ObjectFetch/ObjectDelete reactor handlers + TTL sweep |
| A2 | Behavior version in process metadata | DONE | BehaviorMeta struct + meta() trait method on StepBehavior |
| A3 | Effect state classification for recovery | DONE | Explicit EffectState enum (Pending/Dispatched/Retrying/Streaming/Completed) + ReactorMessage state reporting + journal transitions + RecoveryCoordinator replays last_state |
| A4 | Watchdog for handler overruns | DONE | Implemented with C4 — wall-clock timing in ProcessEntry::step() |
| # | Gap | Status | Notes |
|---|
| G1 | Multi-node clustering | NOT DONE | Design doc exists, no implementation |
| G2 | Object/artifact plane | DONE | ObjectRef + artifact plane implemented with trait-based backend (SQLite first) |
| G3 | Full policy engine | DONE | PolicyEngine with effect-kind rules, integrated into runtime |
| G4 | Behavior versioning + migration | DONE | Version in journal, migrate() callback, recovery-time check |
| G5 | OneForAll / RestForOne supervision | DONE | All three strategies implemented with shutdown coordination |
| G6 | Human approval UI/gateway | DONE | ApprovalStore + reactor handlers + HTTP endpoints + timeout enforcement |
| # | Gap | Status | Notes |
|---|
| X1 | Name-based process registry | DONE | NameRegistry + TurnIntent integration + auto-cleanup |
| X2 | Selective receive | DONE | Tag-based selective receive: pop_matching() + WaitForTag StepResult + selective_tag field + scheduler wiring |
| X3 | Per-message TTL | DONE | expires_at field + lazy TTL in pop() + reap_expired() + expired_count metrics path |
| X4 | Structured observability events | DONE | RuntimeEvent enum + EventBus ring buffer with tracing dual-write |
| X5 | CliExec/SandboxExec/BrowserAutomation workers | NOT DONE | Enum variants only |
- C1: Soften deterministic claim (doc change)
- C2: True atomic turn commit (SQLite transaction)
- C4/A4: Watchdog for handler overruns
- A2: Behavior version metadata
- G3: Policy engine (safety layer)
- G5: OneForAll/RestForOne supervision
- X1: Name-based registry
- X4: Structured observability
- X3: DONE — Per-message TTL (expiry field on messages, reap on receive)
- X2: DONE — Selective receive (end-to-end tag-based with control-lane bypass)
- A1/G2: DONE — ObjectRef + artifact plane (ObjectRef type, ArtifactBackend trait, SqliteArtifactStore, reactor handlers, TTL sweep)
- A3: DONE — Effect state machine for recovery (EffectState enum + ReactorMessage + journal + recovery)
- G6: DONE — Human approval gateway (ApprovalStore, reactor handlers, HTTP endpoints, timeout enforcement)
- G1: Multi-node clustering
| # | Feature | Status | Details |
|---|
| AVM1 | Content inspection (zeptoshield) | DONE | 39 patterns, RegexSet, block/redact/warn, Luhn validation |
| AVM2 | Hash-chained audit log | DONE | SHA-256 chain, verify(), atomic commit path, migration |
| AVM3 | Context-aware scanning | DONE | Per-EffectKind field extraction, user-role filter, typed redaction, TOML field_policy, field-path audit in journal (commit c1003e5) |
| AVM4 | CLI dashboard | DONE | zeptort top (one-shot + JSON + live TUI), zeptort audit |
The Agent VM lets zeptort wrap arbitrary external commands (e.g.
zeptort run zeptoclaw) under daemon supervision — separate from the
in-process StepBehavior actor model. Phase 1 is background-first: spawn,
log capture, restart, halt/kill, recovery sweep, HTTP + CLI control.
| # | Feature | Status | Details |
|---|
| AVM-P1.1 | Tokio process feature + libc dep | DONE | commit 12b6d8c |
| AVM-P1.2 | [external_agents] config section | DONE | commit 2b7fea1 |
| AVM-P1.3 | external_process.rs core types | DONE | commit 9de47fb (Spec, Record, State, RestartPolicy) |
| AVM-P1.4 | ExternalProcessRegistry (SQLite) | DONE | commit 9f14f18 (open + CRUD + sweep) |
| AVM-P1.5 | Spawn primitive + log redirection | DONE | commit cf9c129 (per-agent log file under log_dir) |
| AVM-P1.6 | Halt + kill primitives | DONE | commit 0a243e3 (libc SIGTERM grace + SIGKILL fallback, kill_all) |
| AVM-P1.7 | Restart loop with exponential backoff | DONE | commit bf69fba (100ms × 2ⁿ capped at 30s, max_restarts) |
| AVM-P1.8 | Journal integration | DONE | commit 25263fc (ProcessSpawned/Exited/ChildRestarted/MessageReceived via ExternalJournalSink) |
| AVM-P1.9 | Wire into Daemon lifecycle | DONE | commit b1c0e93 (separate *_external.db, recovery sweep on startup) |
| AVM-P1.10 | HTTP endpoints | DONE | commit 15f762f (POST/GET /agents/external, halt, kill, ping) |
| AVM-P1.11 | CLI subcommands | DONE | commit b425a59 (zeptort run/status/halt/kill/ping) |
| AVM-P1.12 | End-to-end integration tests | DONE | commit 8deb049 (tests/external_process_lifecycle.rs, 5 tests) |
Spec: docs/superpowers/specs/2026-04-08-zeptort-run-mvp-design.md
(commit 46b8d1c)
| # | Feature | Status | Effort | Notes |
|---|
| N1 | Per-process budget | NOT DONE | Medium | Refactor global BudgetGate → per-Pid tracking, expose in dashboard |
| N2 | Multi-node clustering | NOT DONE | Large | Phase 3 from original roadmap (G1) |
| N3 | /status/summary endpoint | NOT DONE | Medium | Tier 2 dashboard: per-process turns/effects/restarts |
| N4 | Web dashboard | NOT DONE | Medium | Browser-based alternative to zeptort top --live |
| N5 | CliExec/SandboxExec workers | NOT DONE | Medium | Wire ZeptoCapsule into reactor for real sandbox execution (X5) |
| N6 | Agent VM Phase 2: streaming attach | NOT DONE | Medium | PTY allocation, live stdout/stderr forwarding (zeptort attach <name>) |
| N7 | Agent VM Phase 2: per-agent gas budgets | NOT DONE | Medium | Budget tracking on external processes (CPU s, wall clock, mem-MB-s) |
| N8 | Agent VM Phase 2: privacy log per agent | NOT DONE | Small | Filter shield audit by external agent name in zeptort status |
| # | Feature | Status | Notes |
|---|
| R1 | ZK proofs of agent execution | NOT DONE | AVM claims 6 proof systems + 25 opcodes. No market demand yet — revisit when agent-to-agent trust is needed. Would use risc0/sp1. |
| R2 | External audit anchoring | NOT DONE | Periodic hash publish to immutable store (S3, blockchain). Upgrades hash chain from self-consistency to true tamper-evidence. |
| R3 | Signed audit logs | NOT DONE | Public key signatures on journal commits. Proves provenance, not just integrity. |