cool-workflow 0.2.4 → 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

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

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

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

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

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

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

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

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

@@ -252,3 +252,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 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-11 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.4`
-- Source modules: `149`
+- Version: `0.2.5`
+- Source modules: `151`
 - Workflow apps: `8`
-- Docs: `62`
-- Smoke tests: `204`
+- 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)
@@ -218,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)
@@ -253,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)
@@ -261,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)
@@ -298,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)
@@ -323,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)
@@ -347,13 +353,17 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [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)
@@ -364,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)
@@ -393,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)
@@ -407,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)
@@ -419,14 +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)
@@ -449,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)
@@ -469,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)
@@ -476,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

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

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

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

package/docs/release-tooling.7.md

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

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

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

@@ -109,16 +109,20 @@ node points to a freed path. Opt out with `--keep-scratch`.
 
 ## Commit snapshots — never reconstructable, always downgrades to verify-only
 
-`commitState` embeds the FULL run into `commits/<id>.json` on every commit, so
-these grow unbounded in both count and per-file size with no cap. Reclaiming them
+`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. Unlike a node snapshot, a commit snapshot is
-a genuine point-in-time capture with no `ReconstructionRecipe` — reclaiming even
+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`.
@@ -288,3 +292,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.3
 
 0.2.4
+
+0.2.5

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

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

package/docs/team-collaboration.7.md

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

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

@@ -71,3 +71,5 @@ security-trust-hardening(7), cli-mcp-parity(7), report-verifiable-bundle(7)
 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.
@@ -282,3 +289,18 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 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

package/docs/workflow-app-framework.7.md

@@ -32,6 +32,37 @@ runner owns state transitions, dispatch, result recording, verifier gates,
 commits, and reports. A workflow app owns its own inputs, phases, task
 prompts, evidence needs, and sandbox profile hints.
 
+Every CW workflow keeps to one loop, and the loop maps to real framework
+operations:
+
+| Loop stage | framework operation | Responsibility |
+| --- | --- | --- |
+| Interpret | `plan()` | Load workflow, check inputs, make tasks |
+| Act | `dispatch()` | Move tasks that can run from pending to running |
+| Observe | `recordResult()` | Read Markdown/JSON-RPC result evidence |
+| Adjust | verifier gates | Check evidence and pick the next phase |
+| Checkpoint | `commitState()` | Take a snapshot of state after important changes |
+
+The language split is on purpose: the platform is TypeScript
+(`src/*.ts -> dist/*.js`, strongly typed so it is simple to keep up), while
+workflow apps are plain JavaScript modules (`apps/<app-id>/workflow.js`,
+legacy `workflows/*.workflow.js`) so workflow scripts run without `ts-node`.
+
+Verification and verdict tasks give back a `cw:result` JSON fence:
+
+````text
+```cw:result
+{
+  "summary": "short summary",
+  "findings": [],
+  "evidence": ["/absolute/path/file.ts:42"]
+}
+```
+````
+
+CW says no to high-priority findings without evidence. This keeps agent work
+nearer to engineering output you can look into than to free talk.
+
 The framework is kept small on purpose. The public app helpers are:
 
 - `defineWorkflowApp(definition)`

package/manifest/plugin.manifest.json

@@ -2,7 +2,7 @@
   "_comment": "SINGLE SOURCE OF TRUTH for every vendor manifest. Edit THIS file, then run `npm run gen:manifests`. Do NOT hand-edit the generated vendor manifests (.claude-plugin/, .codex-plugin/, .agents/, .mcp.json) — `npm run gen:manifests -- --check` (run by release:check) will fail if they drift from this source.",
   "identity": {
     "name": "cool-workflow",
-    "version": "0.2.4",
+    "version": "0.2.5",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {

package/manifest/source-context-profiles.json

@@ -3,7 +3,7 @@
   "profiles": {
     "core": {
       "description": "Default AI source context: runtime source, apps, package metadata, and agent wrappers; generated artifacts, tests, docs, release records, and long logs are manifest-only.",
-      "maxLines": 50000,
+      "maxLines": 52000,
       "include": [
         "plugins/cool-workflow/src/**",
         "plugins/cool-workflow/apps/**",
@@ -25,7 +25,7 @@
     },
     "runtime": {
       "description": "Runtime-kernel source context for state, orchestration, scheduling, execution, and shared types.",
-      "maxLines": 48000,
+      "maxLines": 49000,
       "include": [
         "plugins/cool-workflow/src/**",
         "plugins/cool-workflow/package.json",
@@ -95,7 +95,8 @@
       "include": [
         "AGENTS.md",
         "plugins/cool-workflow/scripts/release-flow.js",
-        "plugins/cool-workflow/scripts/release-gate.sh",
+        "plugins/cool-workflow/scripts/release-gate.js",
+        "plugins/cool-workflow/scripts/release-tags.js",
         "plugins/cool-workflow/scripts/dogfood-release.js",
         "plugins/cool-workflow/scripts/gen-manifests.js",
         "plugins/cool-workflow/scripts/version-sync-check.js",