cool-workflow 0.2.3 → 0.2.5

package/docs/getting-started.md

@@ -1,14 +1,21 @@
 # Getting Started
 
+*This page is for people changing CW itself. To USE `cw`, see the wiki
+[Getting Started](https://github.com/coo1white/cool-workflow/wiki/Getting-Started).*
+
 Start from a new clone:
 
 ```bash
 cd plugins/cool-workflow
 npm install
 npm run build
+npm link         # puts the `cw` command on your PATH
 cw app list
 ```
 
+No `npm link`? Every `cw <args>` line on this page also works as
+`node scripts/cw.js <args>` from this directory.
+
 ## Check your setup first (`cw doctor`)
 
 Like `brew doctor`, this names any setup problem and the fix for it before you
@@ -44,53 +51,54 @@ small:
 Add `--changed-from origin/main` in a source checkout to get the nearest smoke
 tests and guard checks for your current change.
 
-Make a run with a canonical workflow app:
+## One run, end to end
+
+Plan a run with a canonical workflow app. `--dryRun true` keeps it safe;
+put real version numbers in place of `X.Y.Z` / `X.Y.W`:
 
 ```bash
 cw plan release-cut \
   --repo "$PWD" \
-  --version 0.1.25 \
-  --previousVersion 0.1.24 \
+  --version X.Y.Z \
+  --previousVersion X.Y.W \
   --releaseBranch main \
   --dryRun true
 ```
 
-Use the run id you get back:
+The plan prints a run id. See where that run is:
 
 ```bash
 cw status <run-id>
-cw graph <run-id>
+```
+
+Give the next ready task to your agent, one step at a time, in a
+read-only sandbox:
+
+```bash
 cw dispatch <run-id> --limit 1 --sandbox readonly
-cw worker summary <run-id>
-cw topology list
-cw topology apply <run-id> map-reduce --task <task-id>
-cw topology summary <run-id>
-cw multi-agent run <run-id> --topology judge-panel --task <task-id>
-cw multi-agent status <run-id>
-cw multi-agent graph <run-id>
-cw multi-agent dependencies <run-id>
-cw multi-agent failures <run-id>
-cw multi-agent evidence <run-id>
-cw multi-agent step <run-id> --sandbox readonly
-cw multi-agent blackboard <run-id> summary
-cw multi-agent score <run-id> <candidate-id> --criterion correctness=1 --evidence <ref>
-cw multi-agent select <run-id> <candidate-id> --reason "verified winner"
-cw multi-agent summary <run-id>
-cw blackboard summary <run-id>
-cw audit summary <run-id>
-cw audit multi-agent <run-id>
-cw audit policy <run-id>
-cw audit blackboard <run-id>
-cw audit judge <run-id>
-cw eval snapshot <run-id> --id <suite-id>
-cw eval replay .cw/evals/<suite-id>/snapshot.json
-cw eval compare .cw/evals/<suite-id>/snapshot.json .cw/evals/<suite-id>/replay-run.json
-cw eval score .cw/evals/<suite-id>/replay-run.json
-cw eval gate .cw/evals/<suite-id>
-cw eval report .cw/evals/<suite-id>/replay-run.json
+```
+
+When the run is complete, read the report, then prove its record chain
+offline:
+
+```bash
 cw report <run-id> --show
+cw telemetry verify <run-id>
+```
+
+If a run comes to a stop before the end — an agent error, a Ctrl-C, a
+lost session — take it up again from where it stopped:
+
+```bash
+cw run resume <run-id> --drive
 ```
 
+That is the whole loop: plan → status → dispatch → report → verify →
+resume. The common command shapes are on the wiki page
+[Commands or API](https://github.com/coo1white/cool-workflow/wiki/Commands-or-API);
+the complete, generated list of every command — topology, multi-agent,
+audit, eval, and the rest — is in [`cli-mcp-parity.7.md`](cli-mcp-parity.7.md).
+
 Run the smallest check that fits the change:
 
 ```bash

package/docs/index.md

@@ -52,6 +52,23 @@ advanced pages only when you need those parts.
 - [Trust Audit Anchor](trust-audit-anchor.7.md) - head anchor that makes a cut-off audit-log tail visible.
 - [State Explosion Management](state-explosion-management.7.md) - summaries, compact graph views, blackboard digests, and stale-aware compaction.
 - [Evidence Adoption Reasoning Chain](evidence-adoption-reasoning-chain.7.md) - why evidence was adopted or rejected.
+- [Pipeline Runner](pipeline-runner.7.md) - the plan/dispatch/result/commit state machine at the kernel's center.
+- [Pipeline Verbs](pipeline-verbs.7.md) - `cw plan|dispatch|result` and the worker result contract.
+- [Verifier-Gated Commit](verifier-gated-commit.7.md) - evidence checks that let a commit through or refuse it.
+- [Worker Isolation](worker-isolation.7.md) - worker-local state, write acceptance, and the isolation boundary.
+- [Candidate Scoring](candidate-scoring.7.md) - scoring and selection across worker candidates.
+- [Error Feedback](error-feedback.7.md) - structured error records fed back into the next attempt.
+- [State Node](state-node.7.md) - the durable node record every run is made of.
+- [Capability / Topology Registry](capability-topology-registry.7.md) - the one data source behind CLI, MCP, and help.
+- [Cross-Agent Ledger](cross-agent-ledger.7.md) - digest-sealed proposals and reviews between two agents (`cw ledger`).
+- [Routine Triggers](routine.7.md) - `cw routine` local trigger bridge for API/GitHub events.
+- [Remote Source Review](remote-source-review.7.md) - reviewing a repository the agent cannot clone.
+- [Vendor Manifest Loadability](vendor-manifest-loadability.7.md) - proving generated vendor manifests actually load.
+- [Canonical Workflow Apps](canonical-workflow-apps.7.md) - the official app matrix and its checks.
+- [Doctor](doctor.7.md) - environment and onramp diagnosis (`cw doctor`).
+- [Demo](demo.7.md) - the tamper-evidence demo (`cw demo`).
+- [Fix](fix.7.md) - `cw fix` guided recovery for a blocked run.
+- [Init](init.7.md) - `cw init` repository bootstrap.
 
 CW is the base system. Workflow apps are userland. Release and migration rules
 must keep that line clear: stable contracts, clear compatibility checks, and

package/docs/launch/demo.tape

@@ -5,9 +5,10 @@
 #
 #   vhs plugins/cool-workflow/docs/launch/demo.tape
 #
-# Output: docs/launch/demo-tamper.gif. Then in the root README, replace the
-# fenced demo output block under "See it in 30 seconds" with:
-#   ![cw demo tamper](plugins/cool-workflow/docs/launch/demo-tamper.gif)
+# Output: plugins/cool-workflow/docs/launch/demo-tamper.gif. The SHIPPED hero
+# GIF is docs/assets/demo.gif (README.md:18) — after a fresh capture, copy it
+# there so the README picks it up:
+#   cp plugins/cool-workflow/docs/launch/demo-tamper.gif docs/assets/demo.gif
 
 Output plugins/cool-workflow/docs/launch/demo-tamper.gif
 

package/docs/mcp-app-surface.7.md

@@ -14,6 +14,12 @@ The bridge keeps to CW's base-system rules:
   `criteria`
 - errors fail closed through JSON-RPC errors and lasting ErrorFeedback where the
   runtime already keeps feedback
+- a failed `tools/call` (a bad tool name, a missing needed value, or the
+  tool's own code failing) comes back as a normal result shaped
+  `{ content: [...], isError: true }`, with a `Try: <hint>` line when one
+  applies, not a bare JSON-RPC error — so a host that does not show
+  protocol errors to the model still lets it read the message and try
+  again
 
 ## App Run Flow
 

package/docs/multi-agent-cli-mcp-surface.7.md

@@ -331,3 +331,7 @@ The host-facing surface tracks the CLI golden-path fixes (`cw -q` routing + repo
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/multi-agent-eval-replay-harness.7.md

@@ -357,3 +357,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/multi-agent-operator-ux.7.md

@@ -369,3 +369,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/node-snapshot-diff-replay.7.md

@@ -190,3 +190,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/observability-cost-accounting.7.md

@@ -250,3 +250,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/project-index.md

@@ -1,15 +1,15 @@
 # Cool Workflow Project Index
 
-Generated from the current repository code on 2026-07-10 by `npm run sync:project-index`.
+Generated from the current repository code on 2026-07-13 by `npm run sync:project-index`.
 
 ## Snapshot
 
 - Package: `cool-workflow`
-- Version: `0.2.3`
-- Source modules: `148`
+- Version: `0.2.5`
+- Source modules: `151`
 - Workflow apps: `8`
-- Docs: `62`
-- Smoke tests: `201`
+- Docs: `58`
+- Smoke tests: `236`
 - Repository: https://github.com/coo1white/cool-workflow
 
 ## Architecture
@@ -80,12 +80,14 @@ multi-agent host -> topology -> blackboard/coordinator
 
 - [cli/dispatch.ts](../src/cli/dispatch.ts)
 - [cli/entry.ts](../src/cli/entry.ts)
+- [cli/global-flags.ts](../src/cli/global-flags.ts)
 - [cli/io.ts](../src/cli/io.ts)
 - [cli/parseargv.ts](../src/cli/parseargv.ts)
 - [core/capability-data.ts](../src/core/capability-data.ts)
 - [core/capability-table.ts](../src/core/capability-table.ts)
 - [core/format/completion.ts](../src/core/format/completion.ts)
 - [core/format/help.ts](../src/core/format/help.ts)
+- [core/format/recovery-hint.ts](../src/core/format/recovery-hint.ts)
 - [core/format/safe-json.ts](../src/core/format/safe-json.ts)
 - [core/format/state-explosion-text.ts](../src/core/format/state-explosion-text.ts)
 - [core/hash.ts](../src/core/hash.ts)
@@ -118,6 +120,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [core/types/boundary.ts](../src/core/types/boundary.ts)
 - [core/types/execution-backend.ts](../src/core/types/execution-backend.ts)
 - [core/types/observability.ts](../src/core/types/observability.ts)
+- [core/util/cli-args.ts](../src/core/util/cli-args.ts)
 - [core/util/collate.ts](../src/core/util/collate.ts)
 - [core/util/numeric-flag.ts](../src/core/util/numeric-flag.ts)
 - [mcp/dispatch.ts](../src/mcp/dispatch.ts)
@@ -217,7 +220,6 @@ multi-agent host -> topology -> blackboard/coordinator
 ## Documentation Map
 
 - [Agent Delegation Drive](agent-delegation-drive.7.md)
-- [Workflow App framework](agent-framework.md)
 - [CANDIDATE-SCORING(7)](candidate-scoring.7.md)
 - [Canonical Workflow Apps](canonical-workflow-apps.7.md)
 - [CAPABILITY-TOPOLOGY-REGISTRY(7) — Cool Workflow Agent-Driven Self-Evolution](capability-topology-registry.7.md)
@@ -252,7 +254,6 @@ multi-agent host -> topology -> blackboard/coordinator
 - [PIPELINE-RUNNER(7)](pipeline-runner.7.md)
 - [PIPELINE-VERBS(7)](pipeline-verbs.7.md)
 - [Cool Workflow Project Index](project-index.md)
-- [Cool Workflow](readme-v0.1.87-full.md)
 - [Real Execution Backend Integrations](real-execution-backends.7.md)
 - [Release And Migration Discipline](release-and-migration.7.md)
 - [Cool Workflow Release History](release-history.md)
@@ -260,11 +261,9 @@ multi-agent host -> topology -> blackboard/coordinator
 - [Remote-Source Review (`--link`)](remote-source-review.7.md)
 - [Verifiable Report Bundle](report-verifiable-bundle.7.md)
 - [ROUTINE(7)](routine.7.md)
-- [Routines](routines.md)
 - [Run Registry / Control Plane](run-registry-control-plane.7.md)
 - [Run Retention & Provable Reclamation](run-retention-reclamation.7.md)
 - [SANDBOX-PROFILES(7)](sandbox-profiles.7.md)
-- [Scheduled Tasks](scheduled-tasks.md)
 - [Security / Trust Hardening](security-trust-hardening.7.md)
 - [Source Context Profiles](source-context-profiles.7.md)
 - [State Explosion Management](state-explosion-management.7.md)
@@ -284,6 +283,7 @@ multi-agent host -> topology -> blackboard/coordinator
 Smoke tests mirror the public contracts. The high-signal suites are:
 
 - [agent-backend-concurrent-user-env-smoke.js](../test/agent-backend-concurrent-user-env-smoke.js)
+- [agent-backend-sandbox-deny-smoke.js](../test/agent-backend-sandbox-deny-smoke.js)
 - [agent-backend-user-env-smoke.js](../test/agent-backend-user-env-smoke.js)
 - [agent-config-atomic-write-smoke.js](../test/agent-config-atomic-write-smoke.js)
 - [agent-delegation-drive-smoke.js](../test/agent-delegation-drive-smoke.js)
@@ -296,7 +296,9 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [artifact-integrity-smoke.js](../test/artifact-integrity-smoke.js)
 - [audit-verify-smoke.js](../test/audit-verify-smoke.js)
 - [backend-registry-smoke.js](../test/backend-registry-smoke.js)
+- [batch-delegate-error-flush-smoke.js](../test/batch-delegate-error-flush-smoke.js)
 - [batch-output-overflow-smoke.js](../test/batch-output-overflow-smoke.js)
+- [bench-run-smoke.js](../test/bench-run-smoke.js)
 - [blackboard-state-explosion-management-smoke.js](../test/blackboard-state-explosion-management-smoke.js)
 - [block-unapproved-tag-smoke.js](../test/block-unapproved-tag-smoke.js)
 - [budget-scaling-loop-smoke.js](../test/budget-scaling-loop-smoke.js)
@@ -321,13 +323,19 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [clones-gc-smoke.js](../test/clones-gc-smoke.js)
 - [codex-agent-wrapper-smoke.js](../test/codex-agent-wrapper-smoke.js)
 - [collaboration-ops-unit-smoke.js](../test/collaboration-ops-unit-smoke.js)
+- [commit-snapshot-slim-smoke.js](../test/commit-snapshot-slim-smoke.js)
 - [concurrency-default-smoke.js](../test/concurrency-default-smoke.js)
 - [concurrent-failure-semantics-smoke.js](../test/concurrent-failure-semantics-smoke.js)
 - [concurrent-subworkflow-cache-nesting-smoke.js](../test/concurrent-subworkflow-cache-nesting-smoke.js)
+- [concurrent-subworkflow-no-wasted-spawn-smoke.js](../test/concurrent-subworkflow-no-wasted-spawn-smoke.js)
+- [concurrent-subworkflow-only-batch-sigkill-smoke.js](../test/concurrent-subworkflow-only-batch-sigkill-smoke.js)
 - [concurrent-workflow-dsl-smoke.js](../test/concurrent-workflow-dsl-smoke.js)
+- [container-backend-sandbox-deny-smoke.js](../test/container-backend-sandbox-deny-smoke.js)
 - [contract-migration-tooling-smoke.js](../test/contract-migration-tooling-smoke.js)
 - [control-plane-scheduling-smoke.js](../test/control-plane-scheduling-smoke.js)
 - [coordinator-blackboard-smoke.js](../test/coordinator-blackboard-smoke.js)
+- [coordinator-messages-jsonl-atomic-smoke.js](../test/coordinator-messages-jsonl-atomic-smoke.js)
+- [coordinator-messages-jsonl-dirty-append-smoke.js](../test/coordinator-messages-jsonl-dirty-append-smoke.js)
 - [coordinator-topology-persist-dirty-tracking-smoke.js](../test/coordinator-topology-persist-dirty-tracking-smoke.js)
 - [cw-help-per-command-smoke.js](../test/cw-help-per-command-smoke.js)
 - [dead-export-removal-guard-smoke.js](../test/dead-export-removal-guard-smoke.js)
@@ -342,15 +350,20 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [dogfood-release-smoke.js](../test/dogfood-release-smoke.js)
 - [drive-async-real-signal-smoke.js](../test/drive-async-real-signal-smoke.js)
 - [drive-concurrency-flag-smoke.js](../test/drive-concurrency-flag-smoke.js)
+- [drive-concurrent-round-sigkill-smoke.js](../test/drive-concurrent-round-sigkill-smoke.js)
 - [drive-exhaustion-blocked-smoke.js](../test/drive-exhaustion-blocked-smoke.js)
 - [drive-round-cache-serial-smoke.js](../test/drive-round-cache-serial-smoke.js)
+- [drive-run-mutex-smoke.js](../test/drive-run-mutex-smoke.js)
 - [durable-atomic-write-smoke.js](../test/durable-atomic-write-smoke.js)
 - [end-to-end-demo-smoke.js](../test/end-to-end-demo-smoke.js)
 - [end-to-end-golden-path-smoke.js](../test/end-to-end-golden-path-smoke.js)
+- [endpoint-concurrent-round-smoke.js](../test/endpoint-concurrent-round-smoke.js)
 - [error-feedback-resolution-smoke.js](../test/error-feedback-resolution-smoke.js)
 - [error-feedback-smoke.js](../test/error-feedback-smoke.js)
 - [evidence-adoption-reasoning-smoke.js](../test/evidence-adoption-reasoning-smoke.js)
 - [evidence-content-extraction-smoke.js](../test/evidence-content-extraction-smoke.js)
+- [exec-child-termination-smoke.js](../test/exec-child-termination-smoke.js)
+- [exec-vendor-reap-smoke.js](../test/exec-vendor-reap-smoke.js)
 - [execution-backend-agent-smoke.js](../test/execution-backend-agent-smoke.js)
 - [execution-backend-ci-smoke.js](../test/execution-backend-ci-smoke.js)
 - [execution-backends-smoke.js](../test/execution-backends-smoke.js)
@@ -361,17 +374,24 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [gemini-opencode-agent-wrapper-smoke.js](../test/gemini-opencode-agent-wrapper-smoke.js)
 - [h7-custom-profile-persist-smoke.js](../test/h7-custom-profile-persist-smoke.js)
 - [headline-commands-smoke.js](../test/headline-commands-smoke.js)
+- [http-delegate-child-multibyte-stdin-smoke.js](../test/http-delegate-child-multibyte-stdin-smoke.js)
 - [incremental-resume-smoke.js](../test/incremental-resume-smoke.js)
+- [lang-policy-check-smoke.js](../test/lang-policy-check-smoke.js)
 - [ledger-apply-smoke.js](../test/ledger-apply-smoke.js)
 - [ledger-resolution-smoke.js](../test/ledger-resolution-smoke.js)
 - [ledger-verify-smoke.js](../test/ledger-verify-smoke.js)
 - [loop-bounded-expansion-smoke.js](../test/loop-bounded-expansion-smoke.js)
 - [man-run-registry-traversal-smoke.js](../test/man-run-registry-traversal-smoke.js)
 - [mcp-app-surface-smoke.js](../test/mcp-app-surface-smoke.js)
+- [mcp-ping-and-arg-coercion-smoke.js](../test/mcp-ping-and-arg-coercion-smoke.js)
+- [mcp-protocol-version-smoke.js](../test/mcp-protocol-version-smoke.js)
+- [mcp-queue-epipe-smoke.js](../test/mcp-queue-epipe-smoke.js)
 - [mcp-surface-registry-smoke.js](../test/mcp-surface-registry-smoke.js)
 - [mcp-tool-call-coverage-smoke.js](../test/mcp-tool-call-coverage-smoke.js)
+- [mcp-tool-call-error-isresult-smoke.js](../test/mcp-tool-call-error-isresult-smoke.js)
 - [mcp-untrusted-content-advisory-smoke.js](../test/mcp-untrusted-content-advisory-smoke.js)
 - [metrics-summary-limit-smoke.js](../test/metrics-summary-limit-smoke.js)
+- [missing-artifact-gate-live-smoke.js](../test/missing-artifact-gate-live-smoke.js)
 - [multi-agent-cli-mcp-surface-smoke.js](../test/multi-agent-cli-mcp-surface-smoke.js)
 - [multi-agent-eval-determinism-regression-smoke.js](../test/multi-agent-eval-determinism-regression-smoke.js)
 - [multi-agent-eval-replay-harness-smoke.js](../test/multi-agent-eval-replay-harness-smoke.js)
@@ -390,6 +410,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [numeric-flag-parsing-smoke.js](../test/numeric-flag-parsing-smoke.js)
 - [observability-cost-accounting-smoke.js](../test/observability-cost-accounting-smoke.js)
 - [one-way-boundary-smoke.js](../test/one-way-boundary-smoke.js)
+- [onramp-baseref-failclosed-smoke.js](../test/onramp-baseref-failclosed-smoke.js)
 - [onramp-check-smoke.js](../test/onramp-check-smoke.js)
 - [opencode-agent-wrapper-smoke.js](../test/opencode-agent-wrapper-smoke.js)
 - [operator-ux-smoke.js](../test/operator-ux-smoke.js)
@@ -404,6 +425,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [pipeline-auto-advance-smoke.js](../test/pipeline-auto-advance-smoke.js)
 - [pipeline-runner-smoke.js](../test/pipeline-runner-smoke.js)
 - [project-index-sync-smoke.js](../test/project-index-sync-smoke.js)
+- [purity-gate-dynamic-import-smoke.js](../test/purity-gate-dynamic-import-smoke.js)
 - [quickstart-bundle-smoke.js](../test/quickstart-bundle-smoke.js)
 - [quickstart-check-smoke.js](../test/quickstart-check-smoke.js)
 - [quickstart-corpus-smoke.js](../test/quickstart-corpus-smoke.js)
@@ -416,13 +438,18 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [registry-corrupt-fail-closed-smoke.js](../test/registry-corrupt-fail-closed-smoke.js)
 - [registry-corrupt-state-distinct-error-smoke.js](../test/registry-corrupt-state-distinct-error-smoke.js)
 - [release-check-skip-smoke.js](../test/release-check-skip-smoke.js)
+- [release-flow-cut-hardening-smoke.js](../test/release-flow-cut-hardening-smoke.js)
 - [release-flow-smoke.js](../test/release-flow-smoke.js)
+- [release-gate-detached-head-smoke.js](../test/release-gate-detached-head-smoke.js)
 - [release-gate-smoke.js](../test/release-gate-smoke.js)
+- [release-oneclick-resume-repush-smoke.js](../test/release-oneclick-resume-repush-smoke.js)
+- [release-oneclick-smoke.js](../test/release-oneclick-smoke.js)
 - [release-pipeline-hygiene-smoke.js](../test/release-pipeline-hygiene-smoke.js)
 - [release-tooling-smoke.js](../test/release-tooling-smoke.js)
 - [remote-link-archive-smoke.js](../test/remote-link-archive-smoke.js)
 - [remote-link-git-smoke.js](../test/remote-link-git-smoke.js)
 - [report-bundle-smoke.js](../test/report-bundle-smoke.js)
+- [report-pubkey-pin-smoke.js](../test/report-pubkey-pin-smoke.js)
 - [report-verify-bundle-smoke.js](../test/report-verify-bundle-smoke.js)
 - [result-normalize-smoke.js](../test/result-normalize-smoke.js)
 - [robustness-failclosed-smoke.js](../test/robustness-failclosed-smoke.js)
@@ -445,6 +472,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [sample-determinism-smoke.js](../test/sample-determinism-smoke.js)
 - [sandbox-env-batch-hardening-smoke.js](../test/sandbox-env-batch-hardening-smoke.js)
 - [sandbox-profile-smoke.js](../test/sandbox-profile-smoke.js)
+- [sched-input-bounds-smoke.js](../test/sched-input-bounds-smoke.js)
 - [sched-policy-validation-smoke.js](../test/sched-policy-validation-smoke.js)
 - [schedule-routine-daemon-smoke.js](../test/schedule-routine-daemon-smoke.js)
 - [scheduling-routine-lock-concurrency-smoke.js](../test/scheduling-routine-lock-concurrency-smoke.js)
@@ -465,6 +493,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [telemetry-attest-wrap-smoke.js](../test/telemetry-attest-wrap-smoke.js)
 - [telemetry-attestation-smoke.js](../test/telemetry-attestation-smoke.js)
 - [telemetry-fail-closed-smoke.js](../test/telemetry-fail-closed-smoke.js)
+- [telemetry-ledger-append-lock-concurrency-smoke.js](../test/telemetry-ledger-append-lock-concurrency-smoke.js)
 - [telemetry-ledger-smoke.js](../test/telemetry-ledger-smoke.js)
 - [telemetry-metrics-coverage-smoke.js](../test/telemetry-metrics-coverage-smoke.js)
 - [telemetry-verify-signatures-smoke.js](../test/telemetry-verify-signatures-smoke.js)
@@ -472,14 +501,19 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [trust-audit-anchor-smoke.js](../test/trust-audit-anchor-smoke.js)
 - [trust-audit-append-lock-concurrency-smoke.js](../test/trust-audit-append-lock-concurrency-smoke.js)
 - [trust-audit-append-tail-cache-smoke.js](../test/trust-audit-append-tail-cache-smoke.js)
+- [trust-audit-ensure-create-no-truncate-smoke.js](../test/trust-audit-ensure-create-no-truncate-smoke.js)
+- [trust-audit-summary-durable-write-skip-smoke.js](../test/trust-audit-summary-durable-write-skip-smoke.js)
+- [trust-audit-torn-tail-append-smoke.js](../test/trust-audit-torn-tail-append-smoke.js)
 - [vendor-manifest-load-smoke.js](../test/vendor-manifest-load-smoke.js)
 - [vendor-preflight-smoke.js](../test/vendor-preflight-smoke.js)
 - [verdict-signing-workflow-smoke.js](../test/verdict-signing-workflow-smoke.js)
 - [verifier-gated-commit-smoke.js](../test/verifier-gated-commit-smoke.js)
+- [verify-audit-cites-smoke.js](../test/verify-audit-cites-smoke.js)
 - [verify-bump-reproduction-smoke.js](../test/verify-bump-reproduction-smoke.js)
 - [verify-import-audit-chain-smoke.js](../test/verify-import-audit-chain-smoke.js)
 - [web-desktop-workbench-smoke.js](../test/web-desktop-workbench-smoke.js)
 - [wiring-lazy-shell-imports-smoke.js](../test/wiring-lazy-shell-imports-smoke.js)
+- [workbench-port-range-smoke.js](../test/workbench-port-range-smoke.js)
 - [worker-accept-path-architecture-smoke.js](../test/worker-accept-path-architecture-smoke.js)
 - [worker-isolation-smoke.js](../test/worker-isolation-smoke.js)
 - [worker-retry-count-smoke.js](../test/worker-retry-count-smoke.js)

package/docs/real-execution-backends.7.md

@@ -197,3 +197,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/release-and-migration.7.md

@@ -337,3 +337,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/release-tooling.7.md

@@ -170,14 +170,32 @@ model you set up does the review. CW starts the agent argv-style (`shell:false`)
 takes on the agent's own credentials, and pulls in no model SDK — the red line.
 
 ```bash
+# the operator's one-command release (scripts/release-oneclick.js — preflight,
+# gated cut, tag-only push, CI wait, npm confirmation, verdict-record PR):
+npm run release -- 0.2.4
 # check only (gate + independent review, no mutation):
 node plugins/cool-workflow/scripts/release-flow.js --check
 # cut a tag once review is green (when --push, also creates the GitHub Release):
 node plugins/cool-workflow/scripts/release-flow.js --cut --version 0.1.77 [--push] [--no-release]
+# run ONLY the cut's fail-fast preflight (seconds; used by release-oneclick.js):
+node plugins/cool-workflow/scripts/release-flow.js --cut --version 0.1.77 --push --preflight-only
 # backfill / re-create the GitHub Release for an already-pushed tag (no gate/cut):
 node plugins/cool-workflow/scripts/release-flow.js --release --version 0.1.77 [--soft]
 ```
 
+A `--cut` starts with a fail-fast **preflight** (added after the v0.2.3 cut,
+where each of these fired only AFTER the gate/vendor/reviewer had already
+spent real time and tokens): the version flag, the signing key (present AND
+matching the committed `verdict-signing.pub` — once that pubkey is in the
+repo, an unsigned cut is refused up front instead of failing later in CI),
+no pre-existing `vX.Y.Z` tag (local or on origin), a `## X.Y.Z` CHANGELOG
+section, a clean tracked tree, and — for `--push` — HEAD equal to the
+`origin/main` tip (`--allow-stale-head` skips that one check for a
+deliberate re-cut). The push at the end moves ONLY `refs/tags/vX.Y.Z`: the
+verdict commit is a one-hop leaf on the reviewed commit, reachable through
+the tag alone, so main's branch protection is never in the path and no
+stray remote branch is created.
+
 The per-platform difference is config, not code — set the reviewer agent here:
 
 | Platform | Reviewer config |
@@ -300,3 +318,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/routine.7.md

@@ -67,6 +67,28 @@ and fills out the prompt.
 | 0 | Command done |
 | 1 | Error (bad arguments, missing trigger, etc.) |
 
+## EXAMPLES
+
+Long architecture reviews as background routines: use
+`architecture-review-fast` for the foreground user path, then put the full
+`architecture-review` app in line as background work so a deep look-over does
+not get in the way of a back-and-forth session:
+
+```bash
+node scripts/architecture-review-fast.js \
+  --repo /path/to/repo \
+  --question "Is this architecture sound?" \
+  --metrics \
+  --schedule-full
+```
+
+The wrapper makes a one-shot reminder schedule whose `workflowId` is
+`architecture-review`. The schedule prompt carries the foreground fast run id,
+fast report path, and source-context digest/profile, and asks the background
+agent to give back the full review report path and digest. `--metrics` is
+optional and reports foreground time plus agent-spawn and result-cache-hit
+counts for the fast run.
+
 ## SEE ALSO
 
 cw sched — durable run-queue scheduling for workflow runs

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

@@ -480,3 +480,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

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

@@ -107,6 +107,26 @@ scratch dir) is **re-pointed** to the retained `results/<task-id>.md` copy, and
 result-node snapshot is shown to stay `valid` (not `absent`) — so no surviving
 node points to a freed path. Opt out with `--keep-scratch`.
 
+## Commit snapshots — never reconstructable, always downgrades to verify-only
+
+`commitState` writes only the commit's own (small, bounded) record into
+`commits/<id>.json` on every commit — it no longer embeds the whole run, so
+these files stay small and do not grow with the run's size. Reclaiming them
+frees the run's superseded, non-`verifierGated` "checkpoint" commit snapshots —
+the run's LATEST commit and every `verifierGated` commit (the actual
+audit-significant milestones) are always kept. `run.commits`' own lightweight
+metadata (id, `verifierGated`, evidence digests, acceptance rationale — everything
+`extractSkeleton` seals) lives in `state.json`, not the snapshot file, so it stays
+fully intact and queryable regardless. A commit snapshot is treated as never
+reconstructable — there is no `ReconstructionRecipe` for it — so reclaiming even
+one downgrades capability to `verify-only`, never `re-runnable-by-reconstruction`.
+This is left conservative on purpose: even though the snapshot file's content is
+now a strict subset of what `state.json` already keeps durably, the reclaim
+classification does not (yet) treat that as a basis for reconstruction.
+Each reclaimed commit's own `StateNode` had its `snapshot` artifact stripped (not
+re-pointed — there is no retained alternative) before the free, so `prepareFree`'s
+dangling-reference proof covers this kind too. Opt out with `--keep-commits`.
+
 ## Orphan runs — a second pure-scratch case, OUTSIDE this transaction
 
 A run directory can also be pure scratch a different way: a process killed or
@@ -131,8 +151,8 @@ class of run; it is left `retained` indefinitely rather than guessed at.
 ## 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 plan   [run-id] [--reclaimAfterArchiveDays N] [--keep-scratch] [--keep-snapshots] [--keep-commits] [--scope repo|home] [--json]
+cw gc run    [run-id] [--reclaimAfterArchiveDays N] [--keep-scratch] [--keep-snapshots] [--keep-commits] [--limit N] [--actor NAME] [--json]
 cw gc verify <run-id> [--scope repo|home] [--json]
 ```
 
@@ -163,7 +183,8 @@ rule: only ISO timestamps may be now-derived.
 
 Retention/reclamation thresholds extend `RunRegistryPolicy` (alongside
 `archiveOlderThanDays`), never a new policy file: `reclaimAfterArchiveDays`,
-`keepSnapshots`, `keepScratch`, `reclaimStates`, `maxReclaimRuns`, `maxReclaimBytes`.
+`keepSnapshots`, `keepScratch`, `keepCommits`, `reclaimStates`, `maxReclaimRuns`,
+`maxReclaimBytes`.
 Back-compatible defaults reclaim nothing; pre-v0.1.39 runs load unchanged.
 
 ## Compatibility
@@ -269,3 +290,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/state-explosion-management.7.md

@@ -326,3 +326,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/team-collaboration.7.md

@@ -262,3 +262,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/trust-audit-anchor.7.md

@@ -69,3 +69,7 @@ security-trust-hardening(7), cli-mcp-parity(7), report-verifiable-bundle(7)
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/web-desktop-workbench.7.md

@@ -97,9 +97,16 @@ capability core entry that already exists — never a side code path — so it c
 CLI/MCP and is covered by the parity gate.
 
 Authentication is opt-in, not on by default: set `CW_WORKBENCH_TOKEN` and every
-request must carry it as `Authorization: Bearer <token>` or `?token=<token>`
+`/api/*` request must carry it as `Authorization: Bearer <token>` or `?token=<token>`
 (timing-safe compare); left unset, the loopback/read-only/GET-only controls
-above are the only defense and any local process can read. Pass
+above are the only defense and any local process can read. The static UI files
+(`/ui/*`, and `/` when the UI is installed) are served without the token: they
+are fixed code with no run data, and the browser needs them before the page can
+say anything at all. The fallback `/` page (used when the UI is not installed)
+stays behind the token, because it holds the serve descriptor with the repo
+root path. Open the page as `/?token=<token>`: the UI reads the token from the
+page address and adds it to every `/api/*` request; without it the page still
+loads and tells you to reopen it with the token. Pass
 `--require-token` to `cw workbench serve` to fail closed instead: the server
 refuses to start at all unless `CW_WORKBENCH_TOKEN` is already set. This is a
 strict opt-in — leaving it off keeps today's default behavior unchanged.
@@ -280,3 +287,20 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+## Workbench UI/host round 2 (Unreleased)
+
+- With `CW_WORKBENCH_TOKEN` set, the page now works: the static UI files are
+  open, and every `/api/*` request stays behind the token (see "Trust
+  boundary" above). The UI reads `?token=` from the page address, and a 401
+  answer tells you to reopen the page with the token.
+- `cw workbench view --json` (and `/api/run/:runId`) gains a `lifecycle` key:
+  the run registry's own state for the run
+  (queued|running|blocked|completed|failed|archived|reclaimed). The key is
+  left out when the run cannot be classified, so those payloads keep their
+  old bytes. The UI shows it as a badge in the run header, with one
+  next-step line when a run is blocked or failed.
+
+0.2.5