Module runner 

prepare → (skill executes) → finalize, plus abort and resume.

All filesystem state changes happen here; the agent only writes data files into the slots prepare carved out. Hash chaining and atomic writes are handled in hasher; concurrency in lock.

Structs

PendingRun

Pending run pointer: control id, run id, and the run dir.

PrepareOpts

Options for prepare. Only today is required; the rest are agent-supplied metadata.

Functions

abort

Tear down a pending run by sealing a failed manifest. Records the reason in manifest.failure_reason so the audit trail says why. Leaves any partial evidence on disk under the run dir.

finalize

Hash every artifact, link the manifest to the prior run, atomically write manifest.json, update state.json, and remove the pending sentinel. Returns the sealed manifest.

finalize_at

Like finalize, but with an injectable completion clock. The CLI path uses finalize (wall-clock); tests pin completed_at so the coverage math (on-time vs late) is deterministic instead of drifting with the calendar.

git_head

Resolve the registry repo’s HEAD commit hex via gix. Errors when root isn’t a git repo or HEAD can’t be peeled (no commits yet, detached weirdness, etc) — prepare requires a real git sha to pin what the registry said at run time.

git_is_dirty

True if the working tree at root has uncommitted changes to tracked files (index vs. worktree vs. HEAD). Untracked files are not considered. Errors only when root is not a usable git repo.

list_pending

Walk <root>/evidence/ looking for .run-pending sentinels. A sentinel sitting next to a sealed manifest.json is treated as crash-recovery debris from a finalize that died after the manifest landed but before sentinel removal: it’s silently swept rather than surfaced as a pending run (which would block fresh prepares for that control).

prepare

Allocate a run directory, snapshot scope, write prepare.json, drop the .run-pending sentinel, and return the prepare context. Holds the root lock for the duration so concurrent prepares serialise.

resume

Re-emit the prepare context for a pending run. No-op idempotent helper for resuming after an interrupted agent session.