cool-workflow 0.1.78

package/docs/run-registry-control-plane.7.md

@@ -0,0 +1,312 @@
+# Run Registry / Control Plane
+
+CW v0.1.28 adds the Run Registry / Control Plane: a layer that manages MANY
+workflow runs across repositories. Before v0.1.28 a run lived only under its
+repo's `.cw/runs/<id>/` and was loaded from the current directory
+(`loadRunFromCwd`); there was no cross-repo index and no unified lifecycle
+management. This release adds search, resume, archive, a durable queue,
+cross-repo history, and failed-run rerun — without changing the run-state schema
+and without taking ownership of source truth.
+
+The design follows the same base-system observability philosophy as
+[State Explosion Management](state-explosion-management.7.md) and the
+[Evidence Adoption Reasoning Chain](evidence-adoption-reasoning-chain.7.md):
+
+- the per-run `.cw/runs/<id>/state.json` is the SINGLE source of truth
+- the registry is a DERIVED userland index, never a replacement for source records
+- plain files, stable JSON, deterministic output
+- small composable commands and readable console views with full
+  machine-readable output available
+- fail closed when the index is stale, a run's source changed, or its source is
+  missing — never fabricate run status from the cache
+- append-only history: resume continues a run, rerun creates a NEW linked run,
+  and archive marks rather than deletes
+- backward compatible; no hidden database; no daemon required to read state
+
+## Mechanism vs policy
+
+The registry is MECHANISM: a rebuildable cache over runs. POLICY — retention
+windows, queue ordering, and archive thresholds — is configurable and kept out
+of the index (`RunRegistryPolicy`, explicit flags). The index can be deleted and
+rebuilt from source at any time; it never holds authority a `state.json` does
+not.
+
+## Derived index model
+
+A `RunRecord` is derived per run and carries `schemaVersion`, `runId`, `appId`,
+`appVersion`, `workflowId`, `title`, `repo` (the owning repo root), `runDir`,
+`statePath`, `createdAt`, `updatedAt`, `loopStage`, a `lifecycle` and a
+`derivedLifecycle`, an `archived` flag with `archivedAt`/`archiveReason`, task
+counts, `commitCount`, `verifierGatedCommitCount`, `openFeedbackCount`, a bounded
+`inputsDigest` for free-text search, a deterministic `sourceFingerprint`, a
+per-record `freshness` (`valid`, `stale`, or `missing`), and optional
+`provenance`.
+
+A `RunRegistryIndex` aggregates records for a scope (`repo` or `home`) with its
+own `sourceFingerprint`, the covered `repos`, the `queue`, and lifecycle
+`counts`. A `RunRegistryReport` wraps the index with explicit freshness
+(`valid`, `stale`, or `absent`) plus the `staleRuns` and `missingRuns` lists and
+a `nextAction`. Every read re-derives records from source; the persisted index is
+only compared against, never trusted as the live status.
+
+## Lifecycle state machine
+
+Lifecycle is CLASSIFIED from existing state, never invented. `deriveLifecycle`
+applies the following rules to a run's source state — first match wins:
+
+```text
+1. running tasks > 0                              -> running
+2. open feedback > 0                              -> blocked   (failures under correction)
+3. failed tasks > 0                               -> failed
+4. tasks > 0 and all tasks completed              -> completed
+5. verifier-gated commits > 0 and nothing pending -> completed (commit-only runs)
+6. completed tasks > 0                            -> running   (mid-flight)
+7. otherwise                                      -> queued
+```
+
+`archived` is an OVERLAY disposition applied on top of this. The surfaced
+`lifecycle` becomes `archived`, but `derivedLifecycle` preserves the
+source-derived state so search and history can still match the underlying run.
+The classifier never reads the cache; it reads source `state.json`.
+
+## Cross-repo layout
+
+State is plain files, readable and diffable:
+
+```text
+<repo>/.cw/runs/<id>/state.json     source of truth (unchanged, never owned here)
+<repo>/.cw/registry/index.json      per-repo derived index (rebuildable)
+<repo>/.cw/registry/archive.json    archive overlay (mark; never deletes source)
+<repo>/.cw/registry/provenance.json rerun provenance links (derived metadata)
+
+$CW_HOME/registry/repos.json        registered repo roots (explicit discovery set)
+$CW_HOME/registry/index.json        cross-repo derived index (rebuildable)
+$CW_HOME/registry/queue.json        durable run queue (plain, ordered)
+```
+
+The home registry root resolves from `CW_HOME`, then
+`XDG_STATE_HOME/cool-workflow`, then `~/.local/state/cool-workflow`. A repo is
+registered into `repos.json` when it is refreshed (or when a queue entry names
+it). Reads never write: a search or show computes the repo set as the union of
+the registered repos and the current repo in memory, so reading the index never
+mutates discovery state.
+
+## Search
+
+`run search` queries runs by `--app`, `--status`, time range (`--since`,
+`--until`), `--repo`, and free-text (`--text`, matched over runId, app, workflow,
+title, repo, lifecycle, loop stage, and a bounded digest of run inputs).
+Results are deterministic (ordered by `createdAt`, then `runId`) and paginated
+(`--limit`, `--offset`). Search is cross-repo by default (`--scope home`); use
+`--scope repo` to restrict to the current repo. Archived runs are included by
+default and can be excluded with `--include-archived false`.
+
+## Resume
+
+`run resume <run-id>` resolves a run by id across the registry — not just the
+cwd — loads its durable state, and returns the next runnable tasks and next
+actions for the host to execute. Resume is read-only over source: it never
+mutates `state.json` and never un-archives a run.
+
+## Queue
+
+`queue add` appends a durable entry to `$CW_HOME/registry/queue.json` with an
+explicit `--priority` (lower drains first; ties break by enqueue time, then id).
+`queue list` prints the queue in policy order; `queue show <id>` shows one entry.
+`queue drain [--limit N]` marks the next ready entries drained and returns them —
+CW records order and readiness; the HOST still executes the workers. Nothing in
+the queue spawns work on its own.
+
+## Archive
+
+`run archive <run-id>` writes an overlay mark to the owning repo's
+`registry/archive.json`; the run's `state.json` is never moved or deleted, and
+the run stays searchable (its `derivedLifecycle` is preserved). `--unarchive`
+clears the mark. Retention is POLICY: `run archive --older-than-days N
+[--state completed --state failed]` archives eligible runs older than the window
+without touching source truth. The default policy archives nothing
+(`archiveOlderThanDays = 0`) until a window is given.
+
+## Rerun
+
+`run rerun <run-id>` re-runs a failed run as a NEW run: it reuses the original
+inputs and app, lands the new run beside the original (same repo), and records a
+provenance link (`rerunOf`, `rerunOfRepo`, `originRunId`, `generation`, `reason`)
+in the repo's `registry/provenance.json`. The original failed run is PRESERVED
+for audit — the past is never overwritten. Rerunning a rerun increments
+`generation` and keeps `originRunId` pinned to the chain root.
+
+## Cross-repo history
+
+`history` reads a unified timeline of runs across all registered repos
+(newest first), each entry carrying its repo, lifecycle, loop stage, timestamps,
+freshness, and provenance back to its `.cw/runs/<id>/`. Filter with `--app` and
+`--status`; paginate with `--limit` and `--offset`.
+
+## CLI
+
+```text
+node scripts/cw.js registry refresh [--scope repo|home] [--json]
+node scripts/cw.js registry show [--scope repo|home] [--json]
+node scripts/cw.js run search [--app ID] [--status STATE] [--text Q] [--repo PATH] [--since ISO] [--until ISO] [--limit N] [--offset N] [--scope repo|home] [--json]
+node scripts/cw.js run list [--scope repo|home] [--json]
+node scripts/cw.js run show <run-id> [--scope repo|home] [--json]
+node scripts/cw.js run resume <run-id> [--limit N] [--json]
+node scripts/cw.js run archive <run-id> [--reason TEXT] [--unarchive]
+node scripts/cw.js run archive --older-than-days N [--state completed --state failed]
+node scripts/cw.js run rerun <run-id> [--reason TEXT]
+node scripts/cw.js queue add [--app ID|--workflow ID|--runId ID] [--repo PATH] [--priority N] [--note TEXT]
+node scripts/cw.js queue list [--status STATE] [--repo PATH] [--json]
+node scripts/cw.js queue show <queue-id>
+node scripts/cw.js queue drain [--limit N] [--repo PATH]
+node scripts/cw.js history [--app ID] [--status STATE] [--limit N] [--offset N] [--scope repo|home] [--json]
+```
+
+Read commands print terse human panels by default (lifecycle, freshness, counts,
+and next action) and full machine output under `--json` or `--format json`.
+
+## MCP parity
+
+Every command above is declared once in the v0.1.28 capability registry
+(`src/capability-registry.ts`) and rendered on both surfaces, so `cw <cmd>
+--json` is schema-identical to the matching `cw_<tool>` result and the pair
+passes `npm run parity:check`:
+
+- `cw_registry_refresh`, `cw_registry_show`
+- `cw_run_search`, `cw_run_list`, `cw_run_show`, `cw_run_resume`,
+  `cw_run_archive`, `cw_run_rerun`
+- `cw_queue_add`, `cw_queue_list`, `cw_queue_drain`, `cw_queue_show`
+- `cw_history`
+
+See [cli-mcp-parity.7.md](cli-mcp-parity.7.md).
+
+## Freshness and fail-closed behavior
+
+`registry show` recomputes the current source fingerprint for every run and
+compares it to the persisted index. If a run's source changed, the report status
+is `stale` and the run is named in `staleRuns`. If a persisted run's source is
+gone, the run is named in `missingRuns`, it is NOT fabricated into the current
+records, and the next action is `registry refresh`. `run show` of a run whose
+source is missing returns `found: false` with `freshness: missing` and only the
+last-known persisted record, clearly flagged — never as a live status. An
+unreadable or unsupported run state is treated as missing, never as success.
+
+## Migration
+
+Pre-0.1.28 single-repo runs and existing `.cw/runs/` layouts keep working with
+an empty, rebuildable registry: `registry show` reports `absent` until the first
+`registry refresh`, and every pre-0.1.28 CLI command and MCP tool is unchanged.
+No run-state schema change ships in v0.1.28; newer unsupported run-state schemas
+still fail closed. The registry, archive overlay, provenance overlay, queue, and
+home discovery set are all derived files that can be deleted and rebuilt from
+source at any time.
+
+## CLI ↔ MCP Parity (v0.1.28)
+
+Every command and tool referenced above is declared in the capability registry
+(`src/capability-registry.ts`) and validated by `npm run parity:check`, so
+`cw <cmd> --json` and the matching `cw_<tool>` result render one data source.
+See [cli-mcp-parity.7.md](cli-mcp-parity.7.md).
+
+## Execution Backends (v0.1.29)
+
+v0.1.29 lifts execution into a pluggable driver layer: one narrow `ExecutionBackend`
+contract with interchangeable `node`/`bun`/`shell`/`container`/`remote`/`ci`
+drivers, selected by `--backend` (parallel to `--sandbox`) and inspected via
+`backend list|show|probe`. The result/evidence envelope is schema-identical across
+backends; the backend id + sandbox attestation are recorded as provenance, so this
+surface is unchanged regardless of which backend executed a run. See
+[execution-backends.7.md](execution-backends.7.md).
+## Web / Desktop Workbench (v0.1.30)
+
+v0.1.30 adds the Web / Desktop Workbench: a read-only, localhost-only human
+console that renders this surface (and the other four operator panels — run
+graph, blackboard, worker logs, candidate compare, audit timeline) for any run,
+reading the SAME capability `--json` payloads. It is a THIRD FRONT DOOR alongside
+the CLI and MCP that holds no authoritative state and forks no schema: each panel
+equals its `cw <cmd> --json` payload byte-for-byte (parity-gated), and refresh
+re-derives everything from disk. See
+[web-desktop-workbench.7.md](web-desktop-workbench.7.md).
+
+## Observability + Cost Accounting (v0.1.31)
+
+v0.1.31 adds Observability + Cost Accounting: `metrics show`/`metrics summary`
+derive durations, failure/verifier/acceptance rates (with sample counts and
+fail-closed `n/a`), and host-attested token/cost from existing durable run state
+— no metrics database, no collector daemon, no hidden counter. Usage is additive
+and optional (absent ⇒ `unreported`, never 0); cost is `attested` (attested usage
+× a recorded pricing policy) or clearly `estimated`, with pricing as policy. Both
+verbs are parity-gated and render read-only in the v0.1.30 Workbench. See
+[observability-cost-accounting.7.md](observability-cost-accounting.7.md).
+
+
+## Team Collaboration (v0.1.32)
+
+v0.1.32 adds Team Collaboration: a host-attested actor and append-only
+approvals/rejections/comments/handoffs provenance-linked to a durable target,
+plus a review gate that STACKS ON the verifier gate — required approvals from
+authorized roles, enforced inside `resolveCommitGate` AFTER the verifier checks
+and never instead of them, failing closed on quorum/authority/self-approval and
+recording who approved the very artifact that shipped. Policy (required approvals,
+authorized roles, self-approval) is data, default off (pre-v0.1.32 behavior
+unchanged). The verbs are parity-gated and render read-only in the v0.1.30
+Workbench. See [Team Collaboration](team-collaboration.7.md).
+
+## Release Tooling (v0.1.33)
+
+the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffold, and the forward-reference docs) become deterministic scripts, with a de-duplicated release gate. See release-tooling(7).
+
+## Real Execution Backend Integrations (v0.1.34)
+
+container/remote/ci backends really execute (docker/podman run, remote/CI POST-and-poll) under the sandbox contract, with byte-stable evidence vs node and fail-closed refusal when a runtime/endpoint is unavailable. See real-execution-backends(7).
+
+## Node Snapshot / Diff / Replay (v0.1.35)
+
+per-node snapshot, structural diff, and isolated deterministic replay over StateNode, reusing the v0.1.23 eval harness; fail-closed on source drift (valid|stale|absent). See node-snapshot-diff-replay(7).
+
+## Contract Migration Tooling (v0.1.36)
+
+first-class declared migration registry (run-state + workflow-app) with per-edge compatibility proofs, fail-closed reachability, and a round-trip/non-destruction prover. See contract-migration-tooling(7).
+
+## Control-Plane Scheduling (v0.1.37)
+
+priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed park over the v0.1.28 Run Registry queue; policy-as-data, deterministic. See control-plane-scheduling(7).
+
+## Agent Delegation Drive (v0.1.38)
+
+spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
+
+## Run Retention & Provable Reclamation (v0.1.39)
+
+tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, prove it
+
+## Durable State & Locking (v0.1.40)
+
+atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
+
+## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
+
+evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); orchestrator god-object decomposed into per-domain operation modules (pure loadRun->delegate router)
+
+## Robust Result Ingest (v0.1.42)
+
+capture findings/evidence from any reasonable agent shape (alt keys + prose), CW derives grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
+
+## No-False-Green Gate & Launch Prep (v0.1.43)
+
+Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
+
+## Release-Gate Determinism & Agents Vendor (v0.1.44)
+
+Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) instead of the mutable working tree — eliminating false-red/false-green from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter giving any non-Claude AI agent one common interface to CW.
+
+## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
+
+Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
+0.1.51
+
+0.1.76
+
+0.1.77
+
+0.1.78

package/docs/run-retention-reclamation.7.md

@@ -0,0 +1,191 @@
+# Run Retention & Provable Reclamation
+
+CW v0.1.39 adds Run Retention & Provable Reclamation: a tiered, append-only,
+cryptographically-verifiable way to **free disk WITHOUT violating the audit/replay
+moat**. A single day of dogfooding produced ~1 GB across 200+ runs under
+`.cw/runs/`, and before v0.1.39 there was **zero disk reclamation** — `run archive`
+only marked an overlay (it never freed bytes), `sched reclaim` reclaimed expired
+leases (not disk), and worker scratch dirs were never cleaned. Naive GC is
+forbidden: CW's entire value is "don't trust, verify." So reclamation is a
+**verifiable, append-only state transition** — freeing bytes leaves behind
+cryptographic proof that what was freed is reconstructable-or-worthless and that
+the audit-essential subset is sealed.
+
+This release builds directly on a precise lineage: v0.1.28's archive overlay
+(`run-registry.ts` — "Archive is an overlay mark, not a delete"), v0.1.35's
+per-node snapshot/diff/deterministic replay (`node-snapshot.ts`), v0.1.32's
+append-only collaboration log, and v0.1.37's policy-as-data scheduling. It EXTENDS
+them; it forks nothing.
+
+## The lifecycle tiers
+
+```
+live      full on disk              re-runnable + verifiable
+archived  overlay mark, full bytes  re-runnable + verifiable   (v0.1.28 ceiling)
+reclaimed tombstone + skeleton + digests  verify-only (or re-runnable-by-reconstruction)  (v0.1.39 ceiling)
+```
+
+`archived` keeps its mark-only semantics, untouched. `reclaimed` is the NEW
+disk-freeing tier above it. The lifecycle ceiling for this release is `reclaimed`;
+a future `forgotten` compliance tier (discarding even the skeleton, keeping only
+the chained tombstone hash) is out of scope — the `RunLifecycleState` union gains
+ONLY `reclaimed`, and the hash chain is designed to extend to it later.
+
+## The red line — never delete what is audit-essential AND irreproducible
+
+A byte is freeable ONLY if it is one of two classes:
+
+1. **reconstructable** — deterministically re-derivable from RETAINED inputs + a
+   recorded recipe + an `expectDigest`, or
+2. **pure scratch** — zero audit value,
+
+AND it is **referenced by no surviving evidence locator or audit/collaboration
+event.** Any path that is neither class defaults to **RETAINED** (fail closed).
+The hard ALLOW-LIST — never freed under any policy — is `state.json`, `audit/`,
+`commits/`, the collaboration log, the attestation chain, `report.md`, and the new
+`reclaimed.json` overlay.
+
+The **skeleton** is the machine-checkable contract for what must survive every
+reclamation (`SKELETON_REQUIRED_KEYS` + `validateSkeleton()`): the final verdict,
+every commit record, every evidence locator's content digest, the attestation
+chain, the cost record, and the append-only audit + collaboration logs. If a
+complete skeleton cannot be extracted, reclamation **refuses with
+`skeleton-incomplete` and frees zero bytes.**
+
+## Write-ahead, fail-closed sequencing — order is the safety property
+
+The reclamation transaction is four discrete, individually-callable steps:
+
+1. `extractSkeleton()` — extract + seal the audit-essential subset.
+2. `buildTombstone()` — write the full freed-manifest with a **pre-deletion
+   sha256 per path**, plus the hash chain.
+3. `commitTombstone()` — **fsync** the tombstone into the append-only
+   `reclaimed.json` overlay (temp → fsync → rename), and record the attestation
+   through the existing append-only trust-audit log.
+4. `freeBulk()` — ONLY THEN free the bulk bytes.
+
+A crash between any steps leaves **EITHER the full run OR a complete tombstone —
+never a half-deleted run with no proof.** This is testable by design:
+`runReclamation(run, policy, { faultAfter })` throws a synthetic `ReclamationAbort`
+after the named step (`skeleton` | `tombstone-write` | `tombstone-commit`) — never
+by killing the process.
+
+## Append-only — reclamation EXTENDS history, never rewrites it
+
+The tombstone is a NEW `reclaimed.json` overlay (a peer of `archive.json`'s role).
+Only the bulk DATA bytes are freed — no existing audit, state, or commit record is
+ever rewritten. It is itself a new audit record, **hash-chained**: `tombstoneHash`
+is recomputed from the freed-manifest + sealed skeleton + `prevTombstoneHash`
+(genesis = sha256 of the sealed skeleton). `gc verify` recomputes `tombstoneHash`
+**independently**, never trusting the stored value, so a tampered registry entry
+is caught — flipping a per-path sha256 fails with `tombstone-digest-mismatch`;
+editing a hash link fails with `tombstone-chain-broken`.
+
+## Capability downgrade is explicit and queryable — never silent
+
+Reclaiming a node snapshot downgrades a run from `re-runnable` to `verify-only`,
+or to `re-runnable-by-reconstruction` when the snapshot's inputs + `expectDigest`
+are retained. `cw run show <id>` reports `record.tier`, `record.capability`, and an
+enumerable `record.capabilityReason` (a closed set, e.g.
+`snapshot-reclaimed-no-reconstruction` | `inputs-and-expectdigest-retained` |
+`scratch-only-reclaimed`) — never free-text prose.
+
+**Reconstruction is a distinct code path, NOT live `verifyNodeReplay`.** A reclaimed
+artifact making `loadNodeSnapshot` return `absent` is the EXPECTED fail-closed
+signal. The reconstruction verifier re-runs the recorded recipe against the
+RETAINED inputs (keyed on the retained-inputs digest) and compares the result's
+sha256 to the tombstoned `expectDigest` — it never routes through the freed source
+bytes. Flipping one retained input byte fails with `reconstruction-digest-mismatch`.
+
+## The eager-scratch exception
+
+Worker scratch is the one class reclaimed eagerly. A worker's scratch dir is pure
+scratch with zero audit value, and its `result.md` is already copied to
+`results/<task-id>.md` and evidence-gated. Before the scratch is freed, the result
+node's `worker-result` artifact (set by `recordWorkerOutput` to a path INSIDE the
+scratch dir) is **re-pointed** to the retained `results/<task-id>.md` copy, and the
+result-node snapshot is proven to stay `valid` (not `absent`) — so no surviving
+node references a freed path. Opt out with `--keep-scratch`.
+
+## CLI
+
+```
+cw gc plan   [run-id] [--reclaimAfterArchiveDays N] [--keep-scratch] [--keep-snapshots] [--scope repo|home] [--json]
+cw gc run    [run-id] [--reclaimAfterArchiveDays N] [--keep-scratch] [--keep-snapshots] [--limit N] [--actor NAME] [--json]
+cw gc verify <run-id> [--scope repo|home] [--json]
+```
+
+- `gc plan` is a pure **dry-run**: it computes eligible runs, the exact bytes that
+  WOULD be freed per kind, and the per-run capability downgrade. It frees nothing
+  (`plan.bytesToFree` equals the summed per-path sizes it lists).
+- `gc run` executes the write-ahead transaction for eligible runs, bounded by
+  `maxReclaimRuns` / `maxReclaimBytes`, fail-closed on any incomplete skeleton.
+- `gc verify` re-proves a reclaimed run end-to-end.
+
+Eligibility is explicit and fail-closed: a run is reclaimable exactly when its
+**derived lifecycle is `completed` or `failed` AND it is archived AND it has no
+open feedback AND it is past `reclaimAfterArchiveDays`.** `running` / `blocked` /
+`queued` runs are NEVER reclaimable; the check reads live source state and fails
+closed (`non-terminal` | `not-archived` | `within-retention` | `open-feedback` |
+`unreadable` | `already-reclaimed`). **CW never reclaims by default** — every
+reclamation knob defaults to reclaim nothing, and `gc run` is an explicit operator
+action, never a daemon.
+
+## MCP
+
+`cw_gc_plan`, `cw_gc_run`, and `cw_gc_verify` are the peers of the CLI verbs,
+registered in the capability registry and validated by `parity:check` (fail-closed
+on drift). The read-only `gc plan` / `gc verify` payloads obey the now-derived-field
+rule: only ISO timestamps may be now-derived.
+
+## Policy-as-data
+
+Retention/reclamation thresholds extend `RunRegistryPolicy` (alongside
+`archiveOlderThanDays`), never a new policy file: `reclaimAfterArchiveDays`,
+`keepSnapshots`, `keepScratch`, `reclaimStates`, `maxReclaimRuns`, `maxReclaimBytes`.
+Back-compatible defaults reclaim nothing; pre-v0.1.39 runs load unchanged.
+
+## Compatibility
+
+Additive. The kernel `state.json` schema is unchanged beyond the new per-run
+`reclaimed.json` overlay + policy fields; pre-v0.1.39 runs load unchanged. The
+`RunLifecycleState` union gains only `reclaimed`. `run archive` keeps its mark-only
+semantics. Nothing in the original audit log is ever edited or erased.
+
+## See Also
+
+- `docs/run-registry-control-plane.7.md` — the v0.1.28 archive overlay this extends.
+- `docs/node-snapshot-diff-replay.7.md` — the v0.1.35 snapshot engine reconstruction layers beside.
+- `docs/control-plane-scheduling.7.md` — the v0.1.37 policy-as-data lineage.
+- `docs/team-collaboration.7.md` — the v0.1.32 append-only log sealed in the skeleton.
+
+## Durable State & Locking (v0.1.40)
+
+atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
+
+## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
+
+evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); orchestrator god-object decomposed into per-domain operation modules (pure loadRun->delegate router)
+
+## Robust Result Ingest (v0.1.42)
+
+capture findings/evidence from any reasonable agent shape (alt keys + prose), CW derives grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
+
+## No-False-Green Gate & Launch Prep (v0.1.43)
+
+Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
+
+## Release-Gate Determinism & Agents Vendor (v0.1.44)
+
+Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) instead of the mutable working tree — eliminating false-red/false-green from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter giving any non-Claude AI agent one common interface to CW.
+
+## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
+
+Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
+0.1.51
+
+0.1.76
+
+0.1.77
+
+0.1.78

package/docs/sandbox-profiles.7.md

@@ -0,0 +1,137 @@
+# SANDBOX-PROFILES(7)
+
+## NAME
+
+Sandbox Profiles - named, durable worker policy contracts for Cool Workflow
+
+## SYNOPSIS
+
+```text
+node dist/cli.js sandbox list
+node dist/cli.js sandbox show readonly
+node dist/cli.js sandbox validate ./site-sandbox.json
+node dist/cli.js dispatch <run-id> --sandbox readonly
+node dist/cli.js worker manifest <run-id> <worker-id>
+```
+
+## DESCRIPTION
+
+A sandbox profile is a CW policy contract. It tells the agent host what a
+worker may read, write, execute, access over the network, and receive through
+environment variables.
+
+It is not a container, jail, chroot, seatbelt profile, packet filter, or OS
+process sandbox by itself. CW enforces profile validation, deterministic path
+normalization, worker result acceptance, and durable feedback for denied worker
+output. The agent host must enforce OS-level file access, process execution,
+network access, and environment filtering.
+
+The design goal is simple:
+
+```text
+named policy -> resolved worker manifest -> host enforcement -> CW acceptance
+```
+
+Profiles are selected at dispatch time and stored in run state, worker records,
+dispatch manifests, worker manifests, feedback records, and reports.
+
+## BUNDLED PROFILES
+
+`default`
+: Preserves existing Worker Isolation behavior. Workers may read the workspace
+  and write only accepted worker output paths unless additional `allowedPaths`
+  are supplied by older APIs.
+
+`readonly`
+: Workers may read the workspace and write only worker-local output paths.
+  Network access is denied by profile. CW still relies on the host to enforce
+  read-only mounts or equivalent OS policy.
+
+`workspace-write`
+: Workers may read and write the workspace, plus worker-local output paths.
+  Use this only for workers expected to modify repository files.
+
+`locked-down`
+: Workers may read only `input.md` and write only `result.md`. Command,
+  network, and inherited environment access are denied by policy.
+
+## PROFILE SHAPE
+
+Profile files use schema version `1`:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "site-readonly",
+  "title": "Site Readonly",
+  "readPaths": ["$cwd"],
+  "writePaths": [],
+  "workerOutput": { "result": true, "artifacts": true, "logs": true },
+  "execute": { "mode": "none" },
+  "network": { "mode": "none" },
+  "env": { "inherit": false, "expose": ["PATH"] }
+}
+```
+
+Supported path tokens are `$cwd`, `$runDir`, `$workerDir`, `$inputPath`,
+`$resultPath`, `$artifactsDir`, and `$logsDir`. Relative paths are resolved
+from the run workspace. Empty paths, control characters, unknown tokens, and
+`..` traversal are rejected.
+
+`execute.mode` and `network.mode` are `none`, `allowlist`, or `any`.
+Allowlisted commands or network targets are exact strings. Environment variable
+names must use normal shell identifier syntax.
+
+## ENFORCEMENT
+
+CW-enforced:
+
+- profile existence and profile-file validation
+- deterministic path resolution
+- worker output acceptance against effective write paths
+- rejected worker scope, error StateNode, and ErrorFeedback on denied output
+
+Host-required:
+
+- preventing reads outside `readPaths`
+- preventing writes before CW accepts a result
+- command execution restrictions
+- network restrictions
+- environment variable filtering
+
+Worker manifests include both lists as `sandbox.enforcedByCW` and
+`sandbox.hostRequired`. Do not present CW Sandbox Profiles as OS-level
+sandboxing unless the agent host actually applies OS policy.
+
+## FILES
+
+```text
+.cw/runs/<run-id>/state.json
+.cw/runs/<run-id>/dispatches/<dispatch-id>.json
+.cw/runs/<run-id>/workers/<worker-id>/worker.json
+.cw/runs/<run-id>/workers/<worker-id>/manifest.json
+.cw/runs/<run-id>/feedback/
+.cw/runs/<run-id>/report.md
+```
+
+## FAILURE MODES
+
+Unknown requested profiles fail closed with `sandbox-profile-not-found`.
+
+Malformed profile files fail validation with `sandbox-profile-invalid`.
+
+Denied worker output writes create `sandbox-write-denied` feedback. Runtime
+helpers also provide `sandbox-read-denied`, `sandbox-network-denied`, and
+`sandbox-command-denied` for hosts that want to record those decisions through
+CW.
+
+CW never silently downgrades a requested profile to `default`.
+
+## COMPATIBILITY
+
+Sandbox Profiles are introduced in CW v0.1.8. The legacy `allowedPaths` field
+remains in worker scopes and manifests as the effective write-path alias for
+older callers. New hosts should read `sandboxPolicy.readPaths` and
+`sandboxPolicy.writePaths`, then apply worker output allowances from
+`sandboxPolicy.workerOutput`.
+0.1.51