Drover: The Architecture

Three things exist at runtime. The worker is an unmodified harness (Claude Code today; Codex and Gemini on the observe-only lane) running a task inside a disposable container. The watcher is a path watch process injected into that same container, deriving the worker's session into Toolpath steps as they stabilize and streaming every emission out over the exec pipe. The orchestrator is drover on the host: it consumes the stream, checkpoints the sandbox on every step, and holds the fork, revert, resume, and select verbs. The trace is the contract between all three — the same document format whether it is growing live, being forked, or being read back next month.

Scope.start() creates the container from arena's image, forwards harness auth the way arena's runner does (Claude's OAuth token travels as an environment variable from the host keychain, so no credential ever lands in a file drover touches), injects the Linux path binary, and initializes /drover-snap: a bare shadow git repository whose work tree is /work, plus a directory for session-store tars. Scope.attach() does the same to a container arena already started, which is how the gates wrap live arena runs.

The design rule set here governs everything downstream: the worker must not be able to tell it is being observed or snapshotted. The shadow repo has its own GIT_DIR, so the agent's own git log, index, and git status never change when a checkpoint lands — an agent that saw phantom commits appear mid-run would reasonably start debugging its own repository. The container tests verify this invariant directly.

The watcher polls the session store and re-derives the full path on every poll with the same derive_path the import lane uses — live output cannot drift from post-hoc output because there is no second derivation to drift. Steps are withheld while they can still change (tool results attach to the trailing assistant turn; event steps re-parent as the session grows) and appended once stable, so the .path.jsonl is a valid document at every line boundary. Every emission — file lines verbatim, plus provisional tail steps — goes out on stdout, and drover's LiveTrace mirrors the file lines into a host-side copy.

Two contracts came out of the real runs rather than the plan. First, the transport is the exec pipe, not a shared filesystem: the watcher runs inside the sandbox, which behaves identically on remote VMs and ends every cross-VM coherence question. Second, sealing is completion-triggered: the orchestrator spawned the worker, so the orchestrator knows when it finished; inactivity is not a proxy for completion, because one long generation outlasts any reasonable idle window. The idle timeout survives only as a fallback against orphaned watchers.

On every live Step event, the orchestrator calls scope.checkpoint(step_id): a shadow commit of /work plus a tar of the session store, recorded in a sidecar keyed by the Toolpath step id and merged into the sealed document as step.meta.extra.snapshot. The step id is the join key across the whole system — the trace names the moment, the checkpoint names the state, and fork takes both.

One rule the fork gate encodes: checkpoints taken during the seal flush are discarded. At seal, withheld steps flush at once; snapshotting them would stamp final-state filesystems with mid-run step ids — a quiet lie that would surface later as a fork restoring the wrong world. Only live-streamed steps earn checkpoints. The git-shadow backend is the portable default everywhere, including Prime Intellect (whose gVisor blocks OverlayFS); the OverlayFS backend remains ahead for full-rootfs tasks and the paper-parity latency table.

Reverting is the small case: shadow-checkout the commit, clean what came after, untar the session store — the workdir digest afterwards equals the checkpoint's exactly, and the agent's own git never notices. Forking is the interesting case, and it happens at two layers at once. At the format layer, path fork truncates the document at the chosen step and rebases it: the new path keeps exactly the fork point's ancestry, heads at the fork step, and records lineage as base.uri = "toolpath:parent/step" — a representation the RFC had reserved before this project existed. At the sandbox layer, a sibling container is seeded from the shadow commit via git archive, and the native session JSONL is truncated after the fork step's line.

That native truncation is the same-harness fast lane: Claude Code names its JSONL entries by uuid, Toolpath preserves those uuids as step ids, so cutting the file after the fork step's uuid reconstructs the byte-exact prefix without any projection. Cross-harness forks — continue a Claude run in Codex — take the path fork + projector route instead.

The forked child resumes with plain claude --resume against its truncated session. Because the kept prefix is byte-identical to what the parent already sent, the provider's prompt cache recognizes it — the model's context is warm without reprocessing a single early step. This is the property the whole design funnels toward, and it is now a measured fact rather than a design hope:

A run's output is a proposal, not a side effect. The worker's changes exist as a diff against its baseline commit inside its own sandbox; Scope.diff() reads it, select() writes it out for application, and discard() throws the container away. Between held proposals and per-step checkpoints, the destructive verbs in this system all operate on copies — the only irreversible acts are the ones the worker performs against the outside world, which is exactly the class the phase-3 intent gate exists to catch before they fire.

The system so far has eyes (the live lane) and a time machine (scopes). What it grows next, in order: hands — the phase-3 control lane, where mid-run injection rides the worker's stdin, a PreToolUse hook turns every tool intent into an allow/deny decision, and denials land in the trace as dead-end steps; judgment — the phase-4 meta-agent tick loop and the phase-5/6 applications (compression first: its every mechanical dependency passed today, and it produces the demo artifact — a failed run forked, hinted, and passing in fewer steps); and receipts — the phase-7 Tree-GRPO leg feeding prime-rl, and the phase-8 benchmark tables lined up against the paper's.