cool-workflow 0.1.96 → 0.1.98

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 {
@@ -453,7 +456,16 @@ function verifyReportBundle(archivePath, options = {}) {
         }
         if (options.extractReportTo && reportContent !== undefined) {
             reportExtractedTo = node_path_1.default.resolve(options.extractReportTo);
-            node_fs_1.default.writeFileSync(reportExtractedTo, reportContent);
+            if (options.cwd) {
+                const baseCwd = node_path_1.default.resolve(options.cwd);
+                if (!(0, state_1.isContainedPath)(reportExtractedTo, baseCwd)) {
+                    failedChecks.push({ name: "extract-report", code: "path-outside-working-directory" });
+                    reportExtractedTo = undefined;
+                }
+            }
+            if (reportExtractedTo) {
+                node_fs_1.default.writeFileSync(reportExtractedTo, reportContent);
+            }
         }
     }
     catch (error) {
@@ -638,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
@@ -645,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
@@ -677,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/sandbox-profile.js

@@ -132,7 +132,12 @@ function resolveSandboxProfileById(id, context = defaultSandboxContext()) {
     // This closes the gap where `sandbox validate` accepted a custom profile that
     // dispatch/worker-isolation then refused — validated but never enforceable.
     // A non-bundled, non-file id still fails closed via showBundledSandboxProfile.
-    const absolute = node_path_1.default.resolve(requested);
+    const absolute = node_path_1.default.resolve(context.cwd, requested);
+    if (!absolute.startsWith(node_path_1.default.resolve(context.cwd) + node_path_1.default.sep) && absolute !== node_path_1.default.resolve(context.cwd)) {
+        throw new SandboxProfileError("sandbox-profile-path-escape", `Custom profile path traversal denied: ${requested}`, {
+            details: { requested }
+        });
+    }
     if (node_fs_1.default.existsSync(absolute) && node_fs_1.default.statSync(absolute).isFile()) {
         const result = validateSandboxProfileFile(requested, context);
         if (!result.valid || !result.profile) {

package/dist/triggers.js

@@ -147,7 +147,13 @@ function parseJsonObject(value) {
         return undefined;
     if (typeof value === "object")
         return value;
-    const parsed = JSON.parse(String(value));
+    let parsed;
+    try {
+        parsed = JSON.parse(String(value));
+    }
+    catch {
+        throw new Error("Expected a JSON object, got invalid JSON");
+    }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new Error("Expected JSON object");
     }

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.96";
+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

@@ -24,6 +24,7 @@ exports.WorkbenchHost = void 0;
 const node_http_1 = __importDefault(require("node:http"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
 const workbench_1 = require("./workbench");
 const ALLOWED_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
 const CONTENT_TYPES = {
@@ -93,11 +94,18 @@ class WorkbenchHost {
             if (requiredToken) {
                 const bearer = (req.headers.authorization || "").replace(/^Bearer\s+/i, "").trim();
                 const queryToken = url.searchParams.get("token") || "";
-                if (bearer !== requiredToken && queryToken !== requiredToken) {
+                const tokenBuf = Buffer.from(requiredToken);
+                const bearerBuf = Buffer.from(bearer);
+                const queryBuf = Buffer.from(queryToken);
+                const tokenOk = bearerBuf.length === tokenBuf.length && node_crypto_1.default.timingSafeEqual(bearerBuf, tokenBuf);
+                const queryOk = queryBuf.length === tokenBuf.length && node_crypto_1.default.timingSafeEqual(queryBuf, tokenBuf);
+                if (!tokenOk && !queryOk) {
                     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/"))
@@ -159,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

@@ -409,3 +409,7 @@ The one-command `cw -q` headline now routes the question and defaults the repo t
 0.1.95
 
 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
@@ -551,3 +561,7 @@ CLI golden-path fixes: `cw -q "…"` routes the question (was read as an app id
 0.1.95
 
 0.1.96
+
+0.1.97
+
+0.1.98

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

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

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

@@ -153,3 +153,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.95
 
 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/demo.7.md

@@ -0,0 +1,80 @@
+# DEMO(7)
+
+## NAME
+
+`cw demo` — prove CW trust guarantees with one command
+
+## SYNOPSIS
+
+```text
+node dist/cli.js demo tamper [--json]
+node dist/cli.js demo bundle [--json]
+```
+
+## DESCRIPTION
+
+`cw demo` is a self-contained proof of CW's central trust claims. It works
+without an agent and without a network connection. Every run is hermetic
+(fully self-contained) — it builds its own state, tampers with it in known
+ways, and checks that the tampering is caught. Nothing is read from or
+written to the real file system outside a short-term temp directory.
+
+No agent is needed; both demos work when the setup has no agent at all.
+
+## DEMO TAMPER
+
+`cw demo tamper` proves that CW catches forged records offline — with only a
+public key, no server. It:
+
+1. Builds a signed telemetry ledger with three hops.
+2. Tampers with it in three layers:
+   - **Hashes**: Changes a record's data and recomputes the record hash to hide
+     it. The hash chain breaks — the next record's `previousHash` does not
+     match, so the chain is no longer valid.
+   - **Signatures**: Inflates token counts and keeps the old signature. The
+     signature does not match the new data — the verifier catches it.
+   - **Findings**: Edits a signed finding (severity HIGH → LOW) after it was
+     signed by the agent. The signature check on the ed25519 envelope fails
+     because the signed bytes changed.
+3. Verifies each tampered ledger with only the public key.
+
+If all three forgeries are caught, the proof holds and the demo exits 0.
+If any tamper goes undetected, the demo exits 1 — this is a regression in
+the integrity guarantee.
+
+## DEMO BUNDLE
+
+`cw demo bundle` proves that exported report bundles are verifiable offline. It:
+
+1. Builds a full telemetry chain, signs it, and exports a sealed portable
+   bundle (archive bytes + telemetry chain + trust-audit chain + embedded
+   public key).
+2. Tampers with the bundle in two ways:
+   - **Telemetry chain**: Forges a record in the chain. The archive's file
+     digests stay valid (the archive was built from the tampered bytes), but
+     `report verify-bundle` re-checks the chain and catches it.
+   - **Signature + usage**: Inflates token counts and reseals. The signature
+     check and hash chain both break.
+3. Verifies each tampered bundle with `report verify-bundle`.
+
+If all forgeries are caught with only the bundle's own public key, the proof
+holds. No repo, no server, no key handed over.
+
+## EXIT CODES
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | All tampering was caught — trust guarantees hold |
+| 1 | A tamper went undetected — integrity guarantee regression |
+
+## FILES
+
+```text
+src/telemetry-demo.ts
+```
+
+## SEE ALSO
+
+report-verifiable-bundle.7.md — offline bundle verification in detail
+trust-model.md — the trust model and its limits
+security-trust-hardening.7.md — security and trust hardening