cool-workflow 0.1.97 → 0.1.98

package/dist/orchestrator.js

@@ -114,15 +114,23 @@ class CoolWorkflowRunner {
     }
     /** Run fn with a per-request loadRun cache. All loadRun calls inside fn share
      *  the same cached run state, collapsing 18 reads into 1. Returns fn's result
-     *  and clears the cache afterwards (never leaks between requests). */
+     *  and clears the cache afterwards (never leaks between requests).
+     *
+     *  Reentrant: a nested call (e.g. a concurrent drive round whose sub-workflow
+     *  task recursively drives a child run on the SAME runner instance) saves and
+     *  restores the OUTER scope's cache rather than clobbering it to undefined —
+     *  otherwise the inner call's `finally` would wipe the outer round's still-in-
+     *  flight (not yet persisted) mutations, and the outer scope's next loadRun
+     *  would silently fall back to a stale disk read. */
     loadWithCache(fn) {
+        const previousCache = this._requestCache;
         this._requestCache = new Map();
         (0, trust_audit_1.setAuditEventCache)(new Map());
         try {
             return fn(this);
         }
         finally {
-            this._requestCache = undefined;
+            this._requestCache = previousCache;
             (0, trust_audit_1.clearAuditEventCache)();
         }
     }
@@ -818,7 +826,7 @@ function formatHelp() {
         "sandbox backend contract node feedback worker audit candidate review loop schedule " +
         "routine registry run queue clones history quickstart audit-run multi-agent topology summary " +
         "blackboard coordinator metrics operator sched gc telemetry migration demo workbench " +
-        "approve reject comment handoff graph eval man version update fix").split(" ");
+        "approve reject comment handoff ledger graph eval man version update fix").split(" ");
     // Wrap the command list into clean, indented, pipe-joined lines (<=76 cols) instead of
     // one 400-char line that wraps raggedly and merges with the next shell prompt. Pipe-joined
     // (no internal spaces) keeps it parseable by the CLI/MCP parity help-token check.

package/dist/remote-source.js

@@ -287,9 +287,13 @@ function fetchArchiveBytes(rawUrl, sanitizedUrl, dest, opts) {
         "if(!r.ok){process.stderr.write('HTTP '+r.status+' '+r.statusText);process.exit(2);}",
         "const len=Number(r.headers.get('content-length')||0);",
         "if(cap&&len>cap){process.stderr.write('archive too large');process.exit(3);}",
-        "const buf=Buffer.from(await r.arrayBuffer());",
-        "if(cap&&buf.length>cap){process.stderr.write('archive too large');process.exit(3);}",
-        "fs.writeFileSync(out,buf);return;}",
+        "if(!r.body||!r.body.getReader){process.stderr.write('response body is not streamable');process.exit(4);}",
+        "const fd=fs.openSync(out,'w');let total=0;",
+        "try{const reader=r.body.getReader();for(;;){const x=await reader.read();if(x.done)break;",
+        "const chunk=Buffer.from(x.value);total+=chunk.length;",
+        "if(cap&&total>cap){try{await reader.cancel();}catch{};fs.closeSync(fd);fs.rmSync(out,{force:true});process.stderr.write('archive too large');process.exit(3);}",
+        "fs.writeSync(fd,chunk,0,chunk.length);}fs.closeSync(fd);return;}",
+        "catch(e){try{fs.closeSync(fd);}catch{};fs.rmSync(out,{force:true});throw e;}}",
         "process.stderr.write('too many redirects');process.exit(6);",
         "})().catch(e=>{process.stderr.write(String((e&&e.message)||e));process.exit(4);});"
     ].join("");
@@ -315,6 +319,9 @@ function listArchive(file, isZip) {
         if (isZip && result.error?.code === "ENOENT") {
             throw new Error("unzip is required to review a .zip link but was not found on PATH (use a .tar.gz or a git URL)");
         }
+        if (!isZip && result.error?.code === "ENOENT") {
+            throw new Error("tar is required to review a .tar/.tgz link but was not found on PATH");
+        }
         throw new Error(`could not read archive: ${String(result.stderr || "").trim() || `exit ${result.status}`}`);
     }
     return String(result.stdout || "").split(/\r?\n/).filter(Boolean);

package/dist/run-export.js

@@ -108,7 +108,7 @@ function importRun(exportPath, targetDir) {
             throw new Error(`Archive file escapes restore directory: ${file.relativePath}`);
         }
         node_fs_1.default.mkdirSync(node_path_1.default.dirname(destination), { recursive: true });
-        node_fs_1.default.writeFileSync(destination, Buffer.from(file.contentBase64, "base64"));
+        node_fs_1.default.writeFileSync(destination, decodeBase64Strict(file.contentBase64, file.relativePath));
     }
     const externalPathMap = new Map();
     for (const file of files) {
@@ -364,8 +364,11 @@ function verifyReportBundle(archivePath, options = {}) {
         bundleKey = raw.trust?.publicKeyPem;
         if (options.extractReportTo) {
             const reportFile = (raw.files || []).find((file) => file.relativePath === "report.md");
-            if (reportFile)
-                reportContent = Buffer.from(reportFile.contentBase64, "base64").toString("utf8");
+            if (reportFile) {
+                const decoded = decodeBase64StrictResult(reportFile.contentBase64, reportFile.relativePath);
+                if (decoded.ok)
+                    reportContent = decoded.bytes.toString("utf8");
+            }
         }
     }
     catch {
@@ -647,6 +650,28 @@ function normalizeArchiveFiles(raw) {
         };
     });
 }
+function decodeBase64StrictResult(value, relativePath) {
+    if (typeof value !== "string") {
+        return { ok: false, check: { name: "archive-file", pass: false, code: "archive-bad-base64", path: relativePath, actual: "contentBase64 is not a string" } };
+    }
+    const compact = value.replace(/\s+/g, "");
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(compact)) {
+        return { ok: false, check: { name: "archive-file", pass: false, code: "archive-bad-base64", path: relativePath, actual: "invalid base64 encoding" } };
+    }
+    const bytes = Buffer.from(compact, "base64");
+    const expected = compact.replace(/=+$/, "");
+    const actual = bytes.toString("base64").replace(/=+$/, "");
+    if (actual !== expected) {
+        return { ok: false, check: { name: "archive-file", pass: false, code: "archive-bad-base64", path: relativePath, actual: "non-canonical base64 encoding" } };
+    }
+    return { ok: true, bytes };
+}
+function decodeBase64Strict(value, relativePath) {
+    const decoded = decodeBase64StrictResult(value, relativePath);
+    if (!decoded.ok)
+        throw new Error(archiveCheckMessage(decoded.check));
+    return decoded.bytes;
+}
 /** NON-throwing digest/size/count/manifest verification: one structured check per
  *  file (in import order), then the integrity file-count + manifest checks. Shared
  *  by the throwing import path (verifyArchiveFileDigests) and the read-only
@@ -654,7 +679,12 @@ function normalizeArchiveFiles(raw) {
 function collectArchiveDigestChecks(files, integrity) {
     const checks = [];
     for (const file of files) {
-        const bytes = Buffer.from(file.contentBase64, "base64");
+        const decoded = decodeBase64StrictResult(file.contentBase64, file.relativePath);
+        if (!decoded.ok) {
+            checks.push(decoded.check);
+            continue;
+        }
+        const bytes = decoded.bytes;
         const actual = sha256Bytes(bytes);
         const digestOk = actual === file.sha256;
         checks.push(digestOk
@@ -686,6 +716,7 @@ function archiveCheckMessage(check) {
         case "size-mismatch": return `Archive size mismatch for ${check.path}: expected ${check.expected}, got ${check.actual}`;
         case "file-count-mismatch": return `Archive file count mismatch: expected ${check.expected}, got ${check.actual}`;
         case "manifest-digest-mismatch": return `Archive manifest digest mismatch: expected ${check.expected}, got ${check.actual}`;
+        case "archive-bad-base64": return `Archive base64 invalid for ${check.path}: ${check.actual}`;
         default: return `Archive verification failed: ${check.name}`;
     }
 }

package/dist/version.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = exports.LEGACY_RUN_STATE_SCHEMA_VERSION = exports.CURRENT_RUN_STATE_SCHEMA_VERSION = exports.WORKFLOW_APP_SCHEMA_VERSION = exports.CURRENT_COOL_WORKFLOW_VERSION = void 0;
-exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.97";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.98";
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
 exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
 exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;

package/dist/workbench-host.js

@@ -103,7 +103,9 @@ class WorkbenchHost {
                     return this.send(res, 401, { error: "unauthorized: token mismatch" });
                 }
             }
-            const route = decodeURIComponent(url.pathname);
+            const route = decodeRoutePath(url.pathname);
+            if (!route)
+                return this.send(res, 400, { error: "bad request: malformed URL path" });
             if (route === "/" || route === "/index.html")
                 return this.sendAsset(res, "index.html");
             if (route.startsWith("/ui/"))
@@ -165,6 +167,14 @@ function isLocalHost(hostHeader) {
     const hostname = hostHeader.replace(/:\d+$/, "");
     return ALLOWED_HOSTNAMES.has(hostname);
 }
+function decodeRoutePath(pathname) {
+    try {
+        return decodeURIComponent(pathname);
+    }
+    catch {
+        return undefined;
+    }
+}
 function FALLBACK_HTML(uiRoot) {
     return [
         "<!doctype html><meta charset=utf-8><title>Cool Workflow Workbench</title>",

package/docs/agent-delegation-drive.7.md

@@ -411,3 +411,5 @@ The one-command `cw -q` headline now routes the question and defaults the repo t
 0.1.96
 
 0.1.97
+
+0.1.98

package/docs/cli-mcp-parity.7.md

@@ -82,7 +82,7 @@ relationship. `identical` means `cw <cmd> --json` is equal to the `cw_<tool>`
 payload; `projected` means a declared divergence with a reason; `cli-only` marks
 a surface-specific capability with a recorded reason. The matrix is
 <!-- gen:parity:count -->
-machine-complete by design: 202 capabilities, 189 MCP tools.
+machine-complete by design: 207 capabilities, 194 MCP tools.
 <!-- /gen:parity:count -->
 
 <!-- gen:parity:table -->
@@ -290,6 +290,11 @@ machine-complete by design: 202 capabilities, 189 MCP tools.
 | `handoff` | `cw handoff` | `cw_handoff` | `collaborationHandoff` | both | identical |
 | `review.status` | `cw review status` | `cw_review_status` | `reviewStatus` | both | identical |
 | `review.policy` | `cw review policy` | `cw_review_policy` | `reviewPolicy` | both | identical |
+| `ledger.propose` | `cw ledger propose` | `cw_ledger_propose` | `buildLedgerProposal` | both | projected |
+| `ledger.review` | `cw ledger review` | `cw_ledger_review` | `buildLedgerReview` | both | projected |
+| `ledger.verify` | `cw ledger verify` | `cw_ledger_verify` | `verifyLedgerEntry` | both | projected |
+| `ledger.apply` | `cw ledger apply` | `cw_ledger_apply` | `applyLedgerProposal` | both | projected |
+| `ledger.list` | `cw ledger list` | `cw_ledger_list` | `listLedgerEntries` | both | projected |
 <!-- /gen:parity:table -->
 
 v0.1.27 closed the old gaps. It added MCP peers `cw_init`, `cw_next`,
@@ -322,7 +327,7 @@ carry a recorded reason in the registry.
 <!-- /gen:parity:cliOnly -->
 
 <!-- gen:parity:projected -->
-Six capabilities are payload-divergent on purpose (`projected`):
+Eleven capabilities are payload-divergent on purpose (`projected`):
 
 - `commit` — Both surfaces route through the single core entry runner.commit. The CLI emits the raw StateCommitResult for scripting (commit.id, commit.evidence, commit.gate, commit.acceptanceRationale); cw_commit emits the operator commit envelope (commitId, verifierGated, checkpoint, evidenceCount, snapshotPath, nextActions, plus the raw result under `commit`). Declared projection via capability-core.commitEnvelope, not drift.
 - `backend.agent.config.set` — Mutating: persists $CW_HOME/agent-config.json (secret-stripped) before returning the effective config; both surfaces perform the same write — it is a surface-mutating verb, not a read probe.
@@ -330,6 +335,11 @@ Six capabilities are payload-divergent on purpose (`projected`):
 - `gc.run` — Mutating: frees disk and appends a tombstone; both surfaces perform the identical transaction but the payload reports now-derived bytesFreed/tombstone.
 - `clones.gc` — Mutating: removes cache directories and reports now-derived freedBytes/removed; both surfaces perform the identical reclamation.
 - `workbench.serve` — Both surfaces route through the single core entry buildWorkbenchServeDescriptor and return the IDENTICAL serve descriptor under `cw workbench serve --json`/`--once` and `cw_workbench_serve`. They diverge only in side effect, not payload: the CLI's default `cw workbench serve` (no --once) additionally STARTS the blocking localhost host (like `schedule daemon`), which an MCP stdio host cannot do, so cw_workbench_serve only ever returns the descriptor. Declared divergence, not drift.
+- `ledger.propose` — Mints a fresh entry each call: createdAt is the wall-clock instant and the id/digest are derived from it, so the output is inherently non-deterministic and a byte-identity probe does not apply. Both surfaces call the same buildLedgerProposal core; round-trip + fail-closed behavior is covered by ledger-verify-smoke.
+- `ledger.review` — Mints a fresh timestamped/digested verdict each call — non-deterministic output, same reasoning as ledger.propose. Both surfaces call the same buildLedgerReview core.
+- `ledger.verify` — The entry arrives by --file/stdin on the CLI and as an `entry` argument over MCP; there is no shared arg-bag the byte-identity probe can feed both. Both surfaces call the same verifyLedgerEntry core; ledger-verify-smoke proves the fail-closed contract.
+- `ledger.apply` — The entry arrives by --file/stdin on the CLI and as an `entry` argument over MCP; there is no shared arg-bag the byte-identity probe can feed both. Both surfaces call the same applyLedgerProposal core (a fail-closed wrapper over verifyLedgerEntry); ledger-apply-smoke proves the diff only escapes a verified proposal.
+- `ledger.list` — Output depends on the on-disk contents of the named ledger directory/directories, which the generic payload probe does not populate. Both surfaces call the same listLedgerEntries/unionLedgerEntries core; ledger-verify-smoke covers the fail-closed inbox and the multi-mirror union.
 <!-- /gen:parity:projected -->
 
 ## Fail-Closed Rules
@@ -553,3 +563,5 @@ CLI golden-path fixes: `cw -q "…"` routes the question (was read as an app id
 0.1.96
 
 0.1.97
+
+0.1.98

package/docs/contract-migration-tooling.7.md

@@ -171,3 +171,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98

package/docs/control-plane-scheduling.7.md

@@ -155,3 +155,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98

package/docs/cross-agent-ledger.7.md

@@ -0,0 +1,217 @@
+# Cross-Agent Handoff Ledger
+
+CW adds `cw ledger` — a way for two agents scoped to two separate repos to hand
+each other a CHANGE PROPOSAL or a REVIEW VERDICT as verifiable data, not chat.
+One side proposes or reviews; the other side verifies the entry fail-closed and
+turns a proposal into a real pull request. Design notes:
+[handoff-ledger](designs/handoff-ledger.md).
+
+Each entry is a self-contained JSON object that carries its own sha256 content
+digest. The producing side prints one; it reaches the other session by human
+relay or a shared git repo (below); the consuming side runs `cw ledger verify`
+(one entry) or `cw ledger list` (a whole directory) before acting. A tampered or
+malformed entry is refused with a non-zero exit, so
+`cw ledger verify <file> && open-pr` can never proceed on a lie.
+
+Every verb is on both surfaces: the CLI (`cw ledger ...`) and MCP
+(`cw_ledger_propose`, `cw_ledger_review`, `cw_ledger_verify`, `cw_ledger_list`),
+so an agent can mint and check entries in-process, not only from a shell.
+
+`cw ledger` is a NEW verb. It does not touch `cw handoff`, which is a separate
+collaboration primitive (ownership transfer of a run/task) — see
+[team-collaboration](team-collaboration.7.md).
+
+## Why a ledger, not a shared folder
+
+The two agents run as two separate cloud sessions. They share no filesystem, and
+each is scoped to one repo at launch, so a local folder cannot be the channel.
+The only medium both sides can durably reach is git/GitHub. `cw ledger` therefore
+produces and consumes portable, self-verifying entries; how an entry crosses
+(operator relay now, a shared handoff repo later) is transport, kept separate
+from the verb.
+
+## Mechanism vs policy
+
+The MECHANISM is small and lives in the kernel (`src/ledger.ts`): build a
+proposal or a review entry, seal it with a sha256 digest over its canonical
+content, and verify that digest fail-closed. No run state, no network, no new
+runtime dependency. The POLICY — which repos, who may propose, whether a verdict
+blocks a merge — stays outside, in the operator's hands and the transport.
+
+The digest is computed over a deterministic serialization (object keys sorted
+recursively) of every field except `id` and `digest`, which are derived from it.
+The `id` is content-addressed: `ldg-` + the first 16 hex chars of the digest.
+
+## Commands
+
+```
+cw ledger propose --from <a> --to <b> --title <t> --rationale <r> \
+                  [--files a.ts,b.ts] [--diff <patch>]
+cw ledger review  --from <a> --to <b> --target <proposal-id|pr-ref> \
+                  --verdict <approved|rejected> [--findings "a,b"]
+cw ledger verify  [--file <path>]        # else reads the entry from stdin
+cw ledger apply   [--file <path>]        # verify a proposal, then print its diff
+cw ledger list    --dir <ledger-dir> [--dir <mirror-2> ...]   # verify a dir (or union of mirrors)
+```
+
+All write JSON to stdout (stdout is data). `propose` and `review` print a sealed
+entry; `verify` prints a check report; `apply` prints a verify-plus-diff report;
+`list` prints a per-entry report over a directory.
+
+## Applying a proposal — fail-closed
+
+A proposal carries a `suggestedDiff`, but a proposal never mutates the target
+repo by itself: the write-capable side turns it into a real change. `cw ledger
+apply` is the fail-closed bridge — it verifies the entry FIRST and only then
+emits the diff, so an unverified patch can never reach `git`:
+
+```
+cw ledger apply --file proposal.json | jq -r 'select(.ok).diff' | git apply -
+```
+
+`apply` prints `{ ok, id, kind, diff }`. The `diff` is present **only** when
+`ok` is `true` — a tampered entry (`ok:false`, the `verify` failure codes), a
+review rather than a proposal (`ledger-not-a-proposal`), or a proposal with no
+`suggestedDiff` (`ledger-empty-diff`) all yield `diff:null` and exit `1`. The
+kernel never runs `git`; turning the verified diff into a commit stays the
+operator's (or a wrapper's) step — mechanism, not policy.
+
+## Git transport (T2a — shared handoff repo)
+
+The two agents cannot share a local folder, but they can share a git repo both
+are scoped to. The ledger rides on it with no git logic in the kernel — writing
+is composition through files, and `git` is the operator's (or a wrapper's) step:
+
+```
+# Producing side (cool-workflow), inside the shared repo's working tree:
+cw ledger propose --from cool-workflow --to chime \
+  --title "Add retry" --rationale "flaky net" --files src/net.ts \
+  > ledger/$(cw ledger propose ... | jq -r .id).json      # or any unique name
+git add ledger/ && git commit -m "propose: add retry" && git push
+
+# Consuming side (chime):
+git pull
+cw ledger list --dir ledger && echo "inbox verified — safe to act"
+```
+
+`cw ledger list` reads every `*.json` in the directory, verifies each entry, and
+reports `allOk`. It is a **fail-closed inbox**: if any single entry is tampered,
+malformed, or unreadable, `allOk` is `false` and the command exits `1`, so the
+receiving side refuses the whole batch rather than acting on a mixed one.
+
+### Inbox resolution — which proposals are still open
+
+`cw ledger list` also derives a `resolution` summary so the inbox is
+machine-actionable without opening each file. It pairs every proposal with the
+review(s) whose `target` is that proposal's id and reports one of four states:
+
+```json
+"resolution": {
+  "proposals": [
+    { "id": "ldg-1de7c92172af1871", "title": "Add retry", "resolution": "approved", "reviews": ["ldg-…"] },
+    { "id": "ldg-…", "title": "Rename thing", "resolution": "pending", "reviews": [] }
+  ],
+  "pending": 1, "approved": 1, "rejected": 0, "contested": 0
+}
+```
+
+- `pending` — no verified review targets the proposal yet.
+- `approved` / `rejected` — every verified review targeting it agrees.
+- `contested` — verified reviews targeting it disagree (both an APPROVED and a
+  REJECTED exist); the ledger REPORTS the disagreement, it does not pick a
+  winner (mechanism, not policy — whether a verdict blocks a merge stays
+  outside).
+
+Only **verified** entries take part: a tampered review can never resolve a
+proposal, so a proposal answered only by a failing review stays `pending`
+(fail-closed). The fields are additive — the existing `entries[]` / `allOk` /
+`count` output is byte-unchanged (POLA), with each entry now also carrying its
+`title` (proposals) or `target`/`verdict` (reviews). The same `resolution` rides
+on the mirror-union output and on the `cw_ledger_list` MCP tool.
+
+### Mirrors — union-verifying several directories
+
+`--dir` is repeatable. With two or more, `cw ledger list` **union-verifies** the
+directories as mirrors of one ledger (e.g. the same handoff repo cloned from a
+GitHub remote and one or more self-hosted Gitea remotes in different places):
+
+```
+cw ledger list --dir gh/ledger --dir gitea-eu/ledger --dir gitea-asia/ledger
+```
+
+The union is **conflict-free by construction**: entries are immutable and
+content-addressed, so the same entry mirrored to several hosts collapses to one
+result whose `dirs` records every mirror it was found in. It stays **fail-closed
+across mirrors** — a tampered entry in ANY mirror sets `allOk:false` and exits
+`1`. This is for redundancy and reachability, not load: the ledger's traffic is
+tiny; multiple hosts guard against one being down or unreachable.
+
+A single `--dir` keeps the original single-directory output (a `dir` field, no
+`dirs`); two or more switch to the union shape (`dirs` plus a per-entry `dirs`).
+The transport stays git-host-agnostic — adding a mirror is one more clone + one
+more `--dir`, no code change.
+
+## Entry shape
+
+A proposal:
+
+```json
+{
+  "kind": "proposal",
+  "schemaVersion": 1,
+  "from": "cool-workflow",
+  "to": "chime",
+  "title": "Add retry to the fetch path",
+  "rationale": "the network is flaky under load",
+  "targetFiles": ["src/net.ts"],
+  "suggestedDiff": "@@ ... @@",
+  "createdAt": "<iso>",
+  "id": "ldg-<16 hex>",
+  "digest": "sha256:<64 hex>"
+}
+```
+
+A review is the same envelope with `kind: "review"`, plus `target` (the proposal
+id or a PR ref), `verdict` (`APPROVED` | `REJECTED`), and `findings` (a list).
+
+## Verification contract
+
+`cw ledger verify` re-proves the entry and exits fail-closed:
+
+- Not a JSON object, or non-JSON bytes → `ok:false`, code `ledger-bad-json` /
+  `ledger-not-object`.
+- Unknown `kind`, wrong `schemaVersion`, missing digest, missing a required
+  field, or a bad `verdict` → `ok:false` with the matching code.
+- Stored digest does not match a fresh digest of the content →
+  `ok:false`, code `ledger-digest-mismatch`.
+- `id` is not the content-addressed id for the digest (spoofed or absent) →
+  `ok:false`, code `ledger-id-mismatch`. `id` is excluded from the digest, so it
+  is bound to the content by this check — a forged entry cannot set its `id` to
+  collide with a legitimate one and slip through the mirror-union de-duplication.
+
+Any `ok:false` exits `1`. An intact entry exits `0` with `ok:true`.
+
+## Example round-trip
+
+```
+# On the proposing side (cool-workflow):
+cw ledger propose --from cool-workflow --to chime \
+  --title "Add retry" --rationale "flaky net" \
+  --files src/net.ts --diff "$(git diff)" > proposal.json
+
+# The operator carries proposal.json to the chime session, which checks it:
+cw ledger verify --file proposal.json && echo "safe to open a PR"
+
+# The reviewing side hands a verdict back:
+cw ledger review --from chime --to cool-workflow \
+  --target ldg-1de7c92172af1871 --verdict approved \
+  --findings "tests pass,scope ok" > verdict.json
+cw ledger verify --file verdict.json
+```
+
+## Roadmap
+
+Stage 1 shipped the CLI verbs (human relay). Stage 2 adds the MCP surface and
+the git-as-ledger transport (`cw ledger list` over a shared repo). Still open:
+the operator creates the shared handoff repo and scopes both agent environments
+into it. See [handoff-ledger](designs/handoff-ledger.md).

package/docs/designs/handoff-ledger.md

@@ -0,0 +1,145 @@
+# Design — Cross-agent handoff ledger
+
+Status: DRAFT / proposal. Nothing here is built yet. This file ships no
+behavior, no new command, no man-page contract, and changes no existing
+output. It exists so two people (the operator and the reviewer agent) can
+agree on the shape before any code is written.
+
+North Star track: **Track B** (portable, verifiable state — the same
+`run export` → `run restore` recovery story, now used as the channel
+between two agents).
+
+## Goal
+
+Two agents work on two repositories:
+
+- one agent scoped to repo **A** (for example `cool-workflow`),
+- one agent scoped to repo **B** (for example `chime`).
+
+The operator wants them to "share data, review each other, and each be
+able to raise a pull request to the other". In plain terms:
+
+- each side can hand the other a **change proposal**, and
+- each side can hand the other a **review verdict** on a diff or PR,
+- with saved, inspectable, fail-closed state — never a fabricated hand-off.
+
+## The hard constraint (why the obvious design does not work)
+
+The first idea is a shared local folder (for example `~/.chime/handoff/`)
+that both agents read and append to. That only works when both agents run
+on **one machine** with **one filesystem**.
+
+In the operator's setup the two agents run as **two separate cloud
+sessions**. Each session is a fresh, throwaway VM. Two facts follow, and
+the design must respect both:
+
+1. **No shared filesystem.** A file the B-agent writes to `~/.chime/handoff/`
+   in its VM is invisible to the A-agent's VM, and is gone when the session
+   ends. A local folder cannot be the channel.
+2. **Single-repo scope.** Each session's GitHub reach is scoped to one repo
+   at launch (A-agent → repo A, B-agent → repo B). The A-agent cannot read
+   repo B through its GitHub tools, and the reverse is also true. Scope is
+   fixed at launch and cannot be widened mid-session.
+
+The only medium both sessions can durably reach is **git / GitHub**. So the
+ledger is a set of committed files, not a local folder — and the scope wall
+means the hand-off still needs either a shared repo or a human relay for the
+cross-repo step. This document is honest about that; it does not pretend the
+wall is not there.
+
+## What we reuse (no new trust machinery)
+
+CW already has the parts this needs. The design adds a thin verb layer over
+them; it invents no new crypto and no new state format.
+
+- `run export` produces a **verifiable bundle** (file digests, telemetry
+  ledger, trust-audit hash chains).
+- `run restore` **imports fail-closed**: it inspects first, refuses a corrupt
+  or tampered bundle without writing anything, and exits non-zero when the
+  chain does not verify. (`run import` is the exit-0 sibling; the hand-off
+  path must use the fail-closed `restore` contract.)
+- `report verify` checks a run's evidence and citations.
+
+A hand-off entry is therefore just a CW bundle. The receiving side trusts it
+the same way it trusts any restored run: by verification, not by good faith.
+
+## Two verbs
+
+Both live under a single new `cw ledger` verb, so the existing surface is
+untouched and the new behavior is opt-in (POLA). (The name `handoff` was already
+taken by an unrelated collaboration primitive — ownership transfer of a run/task
+— so the cross-agent verb is `ledger`, not `handoff`.) Stage 1 ships as
+`cw ledger propose|review|verify`; see
+[cross-agent-ledger](../cross-agent-ledger.7.md) for the contract.
+
+- **`propose`** — the read-only side writes a structured *change proposal*
+  (title, rationale, target files, suggested diff) as a ledger entry. It does
+  **not** mutate the other repo. The write-capable side picks the entry up,
+  verifies it, and turns it into a **real GitHub pull request**.
+- **`review`** — the reviewing side writes a structured *review verdict*
+  (`APPROVED` / `REJECTED`, findings, the diff or PR it judged) as a ledger
+  entry. The other side surfaces it and can act on it.
+
+This keeps a read-only agent honest: it emits proposals and verdicts as
+**data**, and the write-capable side is the only one that opens PRs. Neither
+side has to be trusted to have mutated the other's code.
+
+## Transports (how an entry actually crosses)
+
+The verbs above produce and consume entries; the transport is how an entry
+moves from one VM to the other. Two are in scope, smallest first.
+
+- **T1 — Human relay (MVP, works today, zero infra).** The producing side
+  prints the entry (a verifiable bundle, or its safe text form) to stdout;
+  the operator carries it to the other session; the consuming side verifies
+  it fail-closed and acts (opens the PR, or records the verdict). This is
+  exactly the loop the operator is already running by hand. It needs no new
+  code beyond a stable print/parse shape.
+- **T2 — Git-as-ledger.** Each entry is committed to a repo under a known
+  path (for example `handoff/<from>-<to>/<id>.bundle`). Because scope is
+  single-repo, this needs one of:
+  - **T2a — a shared handoff repo** both agents are scoped to (cleanest, but
+    the operator must create it and launch both sessions against it), or
+  - **T2b — each side writes to its own repo** and a bridge (the operator, or
+    a scheduled job that *is* scoped to both) moves entries across. The
+    cross-repo read cannot be automatic inside a single scoped session — this
+    is the scope wall, stated plainly, not a gap to be quietly filled.
+
+## Fail-closed rules (non-negotiable)
+
+- An entry that does not verify is **refused**, never acted on. No PR is
+  opened, no verdict is recorded, and the refusal is explicit on stderr with
+  a non-zero exit — the same contract as `run restore`.
+- A proposal is a **suggestion only**. It never edits the target repo by
+  itself; a human-or-agent on the write side always makes the real PR, so the
+  read-only vow of the proposing side holds.
+- stdout stays data (the entry / the machine result); stderr stays
+  diagnostics; a piped run is silent on success. `--json` is stable and
+  decoration-free.
+
+## Non-goals / POLA
+
+- No existing command, output byte, exit code, or file layout changes.
+- No new runtime dependency (zero-dependency red line holds).
+- No vendor-specific logic in core; the verbs move opaque bundles.
+- Nothing ships until its own cycle lands with a test that fails before and
+  passes after, and a `docs/*.7.md` contract page — this design file is not
+  that contract and claims no shipped behavior.
+
+## Suggested rollout (each stage its own reviewed cycle)
+
+0. **This design doc** (no behavior). ← you are here.
+1. **T1 human-relay shape** — a stable, documented print/parse form for a
+   proposal and a verdict, plus a smoke that round-trips one of each and
+   proves a tampered entry is refused.
+2. **`cw ledger propose` / `review`** over `run export` / `restore`, with the
+   fail-closed refusal test.
+3. **T2 git-ledger** (shared-repo first), then optionally a scoped bridge job
+   for T2b.
+
+## Open decisions for the operator
+
+- T2a (shared handoff repo) or T2b (own repos + bridge)? T2a is simpler and
+  should be the default unless a shared repo is not acceptable.
+- Should a verdict be able to **block** a PR merge on the other side, or only
+  advise? Advise-only is the safer default and matches "review as data".

package/docs/durable-state-and-locking.7.md

@@ -154,3 +154,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98

package/docs/evidence-adoption-reasoning-chain.7.md

@@ -315,3 +315,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98

package/docs/execution-backends.7.md

@@ -345,3 +345,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.96
 
 0.1.97
+
+0.1.98