cool-workflow 0.1.86 → 0.1.88

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

@@ -129,3 +129,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+_No behavioral change in v0.1.88 (the `sched` priority/readiness selection, concurrency ceiling, leases, backoff retry, and fail-closed park state are unchanged)._

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

@@ -128,3 +128,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+_No behavioral change in v0.1.88 (atomic writes, fsync-durability for audit-essential state, and lock-serialized cross-process stores are unchanged; the in-place `appendRunNode` optimization keeps `writeRunNode` and the persisted bytes identical)._

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

@@ -289,3 +289,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+_No behavioral change in v0.1.88 (the evidence adoption reasoning chain and its fingerprinted, fail-closed derivation are unchanged)._

package/docs/execution-backends.7.md

@@ -319,3 +319,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+Agent stderr live-streaming is now on by default when stderr is a TTY (CW_AGENT_STREAM=0 / CW_NO_STREAM=1 force it off; CI and pipes stay silent); stdout is still always captured as data and the driver model / sandbox contract are unchanged.

package/docs/launch/launch-kit.md

@@ -41,9 +41,9 @@ to trust or breach.
 
   npx cool-workflow demo tamper
 
-It builds a real signed ledger, forges it two ways (flip a verdict + re-seal its
-hash; inflate reported tokens + reuse the signature), and catches both offline with
-only the public key. On a real run, `cw telemetry verify <run>` re-proves the
+It builds a real signed ledger, forges it three ways (flip a verdict + re-seal its
+hash; inflate reported tokens + reuse the signature; edit a signed finding), and
+catches all three offline with only the public key. On a real run, `cw telemetry verify <run>` re-proves the
 recorded ledger on disk — recomputing the chain so any later edit to a verdict or
 usage digest is caught; add `--pubkey <public.pem>` to re-run each attested hop's
 signature check offline too. I keep an
@@ -111,9 +111,9 @@ npm: https://www.npmjs.com/package/cool-workflow
 > npx cool-workflow demo tamper
 > ```
 >
-> It builds a real signed ledger, forges it two ways (flip a verdict + re-seal its
-> hash; inflate reported tokens + reuse the signature), and catches both offline with
-> only the public key. On a real run, `cw telemetry verify <run>` re-proves the
+> It builds a real signed ledger, forges it three ways (flip a verdict + re-seal its
+> hash; inflate reported tokens + reuse the signature; edit a signed finding), and
+> catches all three offline with only the public key. On a real run, `cw telemetry verify <run>` re-proves the
 > recorded ledger on disk — recomputing the chain so any later edit to a verdict or
 > usage digest is caught; add `--pubkey <public.pem>` to re-run each attested hop's
 > signature check offline too. I keep an
@@ -142,9 +142,9 @@ npm: https://www.npmjs.com/package/cool-workflow
 1/ Your agent pipeline trusts what the model *says* it did. Cool Workflow proves
 it instead. `npx cool-workflow demo tamper` — 30s, no install:
 
-2/ It builds a real ed25519-signed telemetry ledger, forges it two ways, and
-catches both offline with only the public key. A control-plane that delegates
-model execution but can still prove the bill is real.
+2/ It builds a real ed25519-signed telemetry ledger, forges it three ways (incl.
+editing a signed finding), and catches all three offline with only the public key.
+A control-plane that delegates model execution but can still prove the bill is real.
 
 3/ Also: concurrent batches that don't deadlock when an agent hangs, schema-gated
 outputs, token budgets vs the host's recorded usage (attested-telemetry gate is

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

@@ -287,3 +287,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+The host-facing surface tracks the CLI simplification to 6 commands (streaming on by default, vendor agent flags); the multi-agent control loop verbs and their MCP-tool mirrors are otherwise unchanged.

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

@@ -321,3 +321,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+_No change in behavior in v0.1.88 (no harness code changed; the new `loop-control` state node and loop result nodes replay byte-identically through the existing normalize/replay machinery, and pre-0.1.88 snapshots load unchanged)._

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

@@ -333,3 +333,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+_No behavioral change in v0.1.88 (no operator-view code changed; the new sub-workflow `subRunId`/`subRunDir` and `loopRound` run-state fields surface read-only through the existing derived graph/dependency/evidence views, which neither fabricate state nor guess success)._

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

@@ -154,3 +154,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+A new `loop-control` StateNodeKind now flows through per-node snapshot/diff/replay (loop decisions are recorded as deterministic, replay-stable nodes); `appendRunNode` was optimized to mutate `run.nodes` in place (O(1) per append vs O(N^2) churn) with byte-identical persisted state, so snapshot/replay digests are unchanged.

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

@@ -213,3 +213,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+Attestation now signs the agent's RESULT, not just its usage: `TelemetryAttestationRecord.resultDigest` hash-binds sha256(result.md) into the ed25519-signed, hash-chained ledger so an offline re-verifier reconstructs the exact signed payload. Budget-aware loop scaling reads the SAME recorded usage total (`deriveUsageTotals`) the fail-closed cost cap reads, so a `until:{kind:"budget-target"}` loop stops on a token target while the cap stays the absolute backstop.

package/docs/project-index.md

@@ -1,15 +1,15 @@
 # Cool Workflow Project Index
 
-Generated from the current repository code on 2026-06-19 by `npm run sync:project-index`.
+Generated from the current repository code on 2026-06-20 by `npm run sync:project-index`.
 
 ## Snapshot
 
 - Package: `cool-workflow`
-- Version: `0.1.86`
-- Source modules: `63`
+- Version: `0.1.88`
+- Source modules: `65`
 - Workflow apps: `7`
-- Docs: `51`
-- Smoke tests: `110`
+- Docs: `52`
+- Smoke tests: `128`
 - Repository: https://github.com/coo1white/cool-workflow
 
 ## Architecture
@@ -92,6 +92,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [evidence-reasoning.ts](../src/evidence-reasoning.ts)
 - [execution-backend.ts](../src/execution-backend.ts)
 - [gates.ts](../src/gates.ts)
+- [loop-expansion.ts](../src/loop-expansion.ts)
 - [mcp-surface.ts](../src/mcp-surface.ts)
 - [multi-agent-eval.ts](../src/multi-agent-eval.ts)
 - [multi-agent-operator-ux.ts](../src/multi-agent-operator-ux.ts)
@@ -112,6 +113,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [telemetry-attestation.ts](../src/telemetry-attestation.ts)
 - [telemetry-demo.ts](../src/telemetry-demo.ts)
 - [telemetry-ledger.ts](../src/telemetry-ledger.ts)
+- [term.ts](../src/term.ts)
 - [validation.ts](../src/validation.ts)
 - [workbench-host.ts](../src/workbench-host.ts)
 - [workbench.ts](../src/workbench.ts)
@@ -159,6 +161,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [Operator UX](operator-ux.7.md)
 - [PIPELINE-RUNNER(7)](pipeline-runner.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)
@@ -187,6 +190,7 @@ multi-agent host -> topology -> blackboard/coordinator
 Smoke tests mirror the public contracts. The high-signal suites are:
 
 - [agent-delegation-drive-smoke.js](../test/agent-delegation-drive-smoke.js)
+- [append-run-node-no-realloc-smoke.js](../test/append-run-node-no-realloc-smoke.js)
 - [architecture-review-fast-automation-smoke.js](../test/architecture-review-fast-automation-smoke.js)
 - [architecture-review-fast-smoke.js](../test/architecture-review-fast-smoke.js)
 - [artifact-integrity-smoke.js](../test/artifact-integrity-smoke.js)
@@ -194,6 +198,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [backend-registry-smoke.js](../test/backend-registry-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)
 - [bump-version-idempotent-smoke.js](../test/bump-version-idempotent-smoke.js)
 - [candidate-scoring-smoke.js](../test/candidate-scoring-smoke.js)
 - [canonical-workflow-apps-smoke.js](../test/canonical-workflow-apps-smoke.js)
@@ -201,6 +206,8 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [cli-command-surface-smoke.js](../test/cli-command-surface-smoke.js)
 - [cli-jsonmode-parity-smoke.js](../test/cli-jsonmode-parity-smoke.js)
 - [cli-mcp-parity-smoke.js](../test/cli-mcp-parity-smoke.js)
+- [codex-agent-wrapper-smoke.js](../test/codex-agent-wrapper-smoke.js)
+- [concurrency-default-smoke.js](../test/concurrency-default-smoke.js)
 - [concurrent-failure-semantics-smoke.js](../test/concurrent-failure-semantics-smoke.js)
 - [concurrent-workflow-dsl-smoke.js](../test/concurrent-workflow-dsl-smoke.js)
 - [contract-migration-tooling-smoke.js](../test/contract-migration-tooling-smoke.js)
@@ -218,9 +225,14 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [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)
+- [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)
 - [freebsd-audit-fixes-smoke.js](../test/freebsd-audit-fixes-smoke.js)
+- [gemini-agent-wrapper-smoke.js](../test/gemini-agent-wrapper-smoke.js)
 - [h7-custom-profile-persist-smoke.js](../test/h7-custom-profile-persist-smoke.js)
+- [incremental-resume-smoke.js](../test/incremental-resume-smoke.js)
+- [loop-bounded-expansion-smoke.js](../test/loop-bounded-expansion-smoke.js)
 - [mcp-app-surface-smoke.js](../test/mcp-app-surface-smoke.js)
 - [mcp-surface-registry-smoke.js](../test/mcp-surface-registry-smoke.js)
 - [multi-agent-cli-mcp-surface-smoke.js](../test/multi-agent-cli-mcp-surface-smoke.js)
@@ -235,9 +247,11 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [multi-agent-trust-policy-audit-smoke.js](../test/multi-agent-trust-policy-audit-smoke.js)
 - [no-false-green-smoke.js](../test/no-false-green-smoke.js)
 - [node-snapshot-diff-replay-smoke.js](../test/node-snapshot-diff-replay-smoke.js)
+- [npm-trusted-publish-smoke.js](../test/npm-trusted-publish-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-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)
 - [parallel-onramp-smoke.js](../test/parallel-onramp-smoke.js)
 - [parity-doc-sync-smoke.js](../test/parity-doc-sync-smoke.js)
@@ -247,8 +261,10 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [project-index-sync-smoke.js](../test/project-index-sync-smoke.js)
 - [quickstart-bundle-smoke.js](../test/quickstart-bundle-smoke.js)
 - [quickstart-check-smoke.js](../test/quickstart-check-smoke.js)
+- [quickstart-no-agent-smoke.js](../test/quickstart-no-agent-smoke.js)
 - [quickstart-readme-path-smoke.js](../test/quickstart-readme-path-smoke.js)
 - [quickstart-smoke.js](../test/quickstart-smoke.js)
+- [readme-trust-claim-smoke.js](../test/readme-trust-claim-smoke.js)
 - [real-execution-backends-smoke.js](../test/real-execution-backends-smoke.js)
 - [registry-corrupt-fail-closed-smoke.js](../test/registry-corrupt-fail-closed-smoke.js)
 - [release-flow-smoke.js](../test/release-flow-smoke.js)
@@ -259,16 +275,20 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [result-normalize-smoke.js](../test/result-normalize-smoke.js)
 - [robustness-failclosed-smoke.js](../test/robustness-failclosed-smoke.js)
 - [robustness-hardening-smoke.js](../test/robustness-hardening-smoke.js)
+- [run-all-agent-env-hermetic-smoke.js](../test/run-all-agent-env-hermetic-smoke.js)
 - [run-all-json-summary-smoke.js](../test/run-all-json-summary-smoke.js)
+- [run-export-cross-machine-smoke.js](../test/run-export-cross-machine-smoke.js)
 - [run-export-import-smoke.js](../test/run-export-import-smoke.js)
 - [run-export-restore-rerun-smoke.js](../test/run-export-restore-rerun-smoke.js)
 - [run-export-restore-resume-smoke.js](../test/run-export-restore-resume-smoke.js)
 - [run-fixture-compat-smoke.js](../test/run-fixture-compat-smoke.js)
+- [run-import-path-traversal-smoke.js](../test/run-import-path-traversal-smoke.js)
 - [run-import-tamper-failclosed-smoke.js](../test/run-import-tamper-failclosed-smoke.js)
 - [run-inspect-archive-smoke.js](../test/run-inspect-archive-smoke.js)
 - [run-registry-control-plane-smoke.js](../test/run-registry-control-plane-smoke.js)
 - [run-resume-drive-smoke.js](../test/run-resume-drive-smoke.js)
 - [run-retention-reclamation-smoke.js](../test/run-retention-reclamation-smoke.js)
+- [sample-determinism-smoke.js](../test/sample-determinism-smoke.js)
 - [sandbox-profile-smoke.js](../test/sandbox-profile-smoke.js)
 - [sched-policy-validation-smoke.js](../test/sched-policy-validation-smoke.js)
 - [schedule-routine-daemon-smoke.js](../test/schedule-routine-daemon-smoke.js)
@@ -278,6 +298,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [source-context-batch-smoke.js](../test/source-context-batch-smoke.js)
 - [source-context-profile-smoke.js](../test/source-context-profile-smoke.js)
 - [state-node-smoke.js](../test/state-node-smoke.js)
+- [sub-workflow-nesting-smoke.js](../test/sub-workflow-nesting-smoke.js)
 - [surface-explicit-cwd-smoke.js](../test/surface-explicit-cwd-smoke.js)
 - [tamper-evidence-demo-smoke.js](../test/tamper-evidence-demo-smoke.js)
 - [team-collaboration-smoke.js](../test/team-collaboration-smoke.js)

package/docs/readme-v0.1.87-full.md

@@ -0,0 +1,301 @@
+<div align="center">
+
+# Cool Workflow
+
+**Point an AI coding agent at a repo, get a saved report with real citations — not a chat message you lose.**
+
+[![CI](https://img.shields.io/github/actions/workflow/status/coo1white/cool-workflow/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/coo1white/cool-workflow/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/cool-workflow?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/cool-workflow)
+[![downloads](https://img.shields.io/npm/dm/cool-workflow?style=flat-square&label=downloads)](https://www.npmjs.com/package/cool-workflow)
+[![provenance](https://img.shields.io/badge/npm-provenance-3178C6?style=flat-square)](https://www.npmjs.com/package/cool-workflow)
+[![release](https://img.shields.io/github/v/tag/coo1white/cool-workflow?style=flat-square&label=release&color=brightgreen&sort=semver)](https://github.com/coo1white/cool-workflow/tags)
+[![license](https://img.shields.io/badge/license-BSD--2--Clause-blue?style=flat-square)](LICENSE)
+
+<img src="docs/assets/cool-workflow-readme-promo.png" alt="Cool Workflow turns AI agent repo questions into saved, cited, tamper-evident reports." width="100%">
+
+</div>
+
+## What is this, really?
+
+You put a question to an AI coding agent, it gives an answer in the chat, and
+then the answer is gone. Next week you put the same question and have to start
+all over again.
+
+**Cool Workflow (CW) makes that lost question into a kept job.** You point it at
+a code store with a question like *"what are the security risks here?"* It runs
+your AI agent over all the code in ordered steps and puts a **report file** on
+disk — every point backed by an exact `file.js:42` pointer to the line. You are
+able to run it again, give it to others, and even give proof that the report was
+not changed by anyone.
+
+```
+        you ask once                          CW gives you
+   "what are the risks in my repo?"     →   a saved report.md with
+                                              cited findings, repeatable
+```
+
+It does **not** run the AI model itself. You give your own agent (for one, the
+`claude` command line) and CW keeps it working, makes a record of what took
+place, and checks the answer. Take CW as the *project manager*, and your agent
+as the *worker*.
+
+> New to this? You're in the right place — this README is a step-by-step start.
+> Deeper/advanced docs live in the [wiki](https://github.com/coo1white/cool-workflow/wiki).
+
+---
+
+## Project rule
+
+CW should stay a small, trusted tool, not a platform.
+
+```text
+ask simple -> run simple -> verify simple -> resume simple
+```
+
+The engineering base is FreeBSD-like: POLA first, fail closed, no silent
+fallback, stdout as data, stderr as diagnostics, and documented stable
+surfaces. The user-facing spirit is close to Homebrew: a small command
+surface, a strong `doctor` check, and clear next steps when a run is
+blocked or a report does not verify.
+
+That means CW should hide orchestration detail behind clear commands,
+keep `.cw/` state open to check, make recovery boring, and prefer a
+small tool that can be trusted over a broad agent platform.
+
+---
+
+## What you need
+
+1. **Node.js** (v18+). Make a check with `node --version`.
+2. **An AI agent on the command line.** The most simple is **Claude Code** —
+   after you put it in you will have a `claude` command. Make a check with
+   `claude --version`. (CW also works with `codex`, or any command/HTTP agent —
+   but make your start with `claude`.)
+
+> No agent yet? You are still able to **see CW work** (next part, step 1)
+> without one. The full report needs an agent, because CW never makes a call to
+> a model itself.
+
+---
+
+## Quick start (3 steps)
+
+### 1. See it run — no install, no agent, no API key
+
+```bash
+npx cool-workflow demo tamper
+```
+
+This gives proof of CW's chief trick in 30 seconds (more on that
+[below](#can-i-trust-the-report)). If you see `VERDICT: tamper-evidence holds ✓`,
+all is working.
+
+Not sure what to run next?
+
+```bash
+npx cool-workflow doctor --onramp
+```
+
+This prints the short path for a first run, the fast checks for source work, and
+the full gate to use before a release.
+
+From a source checkout, use:
+
+```bash
+cd plugins/cool-workflow
+node scripts/cw.js doctor --onramp --changed-from origin/main
+```
+
+### 2. Check, then run a real review on your own repo
+
+First make a zero-write check. It does not make a run, write `.cw/`, or call
+your agent:
+
+```bash
+npx cool-workflow quickstart architecture-review --check \
+  --repo /path/to/your/project \
+  --question "What are the main risks in this codebase?" \
+  --agent-command builtin:claude
+```
+
+If the check is good, run the review:
+
+```bash
+npx cool-workflow quickstart architecture-review \
+  --repo /path/to/your/project \
+  --question "What are the main risks in this codebase?" \
+  --agent-command builtin:claude
+```
+
+If the report has to go to someone else, make the checked bundle in the same
+run:
+
+```bash
+npx cool-workflow quickstart architecture-review \
+  --repo /path/to/your/project \
+  --question "What are the main risks in this codebase?" \
+  --agent-command builtin:claude \
+  --bundle
+```
+
+- `--repo` — the folder you have a wish to get looked at.
+- `--question` — what you have a wish to be certain of.
+- `--agent-command builtin:claude` — make use of the Claude wrapper that comes
+  with it (read-only; it never makes changes to your code).
+- `--agent-command builtin:codex` — make use of the Codex wrapper that comes
+  with it (read-only; it never makes changes to your code).
+
+CW makes a plan of the work, keeps your agent working over your repo in steps,
+and gives out where it kept the report. For a living view in the window while
+every worker is at work, take it up with `CW_AGENT_STREAM=1`; the view goes to
+stderr only and the kept answer is not changed.
+
+> **No agent put in place?** CW comes to a safe stop and says so
+> (`status: blocked`) — it never makes up an answer. Put in `claude` and run it
+> again.
+
+### 3. Read the report
+
+```bash
+cat /path/to/your/project/.cw/runs/<run-id>/report.md
+```
+
+You get a short account, ordered points, and **clickable pointers** like
+`src/server.js:18` for every point made — so you are able to make a check of
+each one yourself.
+
+---
+
+## Install it (optional)
+
+`npx` is ever working with no need to put it in. To get the short `cw` command
+everywhere:
+
+```bash
+npm install -g cool-workflow      # then use:  cw …   instead of  npx cool-workflow …
+```
+
+---
+
+## What else can it do?
+
+CW comes with a number of ready-made "jobs" (run `cw list` to see them all):
+
+| Command | What it does |
+|---|---|
+| `architecture-review` | Make a map of a repo's structure and put its true risks in order, with facts. |
+| `pr-review-fix-ci` | Go over a pull request, put forward fixes, make a check of CI. |
+| `research-synthesis` | Get together and make into one a fact-backed answer to a question. |
+| `release-cut` | Keep a gated, gone-over release moving. |
+
+It also puts the same acts out over **MCP**, so editors like Claude Desktop /
+Cursor / VS Code are able to make a call to CW as a tool. See the
+[wiki](https://github.com/coo1white/cool-workflow/wiki) for that and for
+multi-agent runs.
+
+---
+
+## Can I trust the report?
+
+This is what makes CW not the same as the rest. Because CW only *gives the work
+over* to your agent, it keeps a record of every step that makes any false change
+come to light: every agent's given token use is signed by secret-key science and
+chained by hash, so **changing the record after the fact has the chain broken** —
+and anyone is able to make the check again offline with only a public key.
+
+See it for yourself — the `demo tamper` from step 1 makes a false record in two
+ways and gets both:
+
+```text
+▶ LEDGER tamper
+  after:  ✗ DETECTED — the hash chain caught it: chain-link[2]: telemetry-chain-broken
+▶ SIGNATURE tamper
+  after:  ✗ DETECTED — signature does not match reported usage
+VERDICT: tamper-evidence holds ✓ — every forgery caught offline, with only the public key.
+```
+
+On a true run, make a check of any run's record yourself:
+
+```bash
+cw telemetry verify <run-id>
+```
+
+CW makes use of this on its own code — see the kept living-run proof in
+[`plugins/cool-workflow/docs/dogfood/`](plugins/cool-workflow/docs/dogfood/).
+
+The plain point: *the thing that uses up the tokens is not the thing that keeps
+the books.* That keeping-apart is normal in account-keeping — CW gives it to AI
+agents.
+
+---
+
+## Hand the report to someone — they can check it on their own
+
+A report you keep on your own machine is one thing. A report you can **give to
+someone** who then makes the check themselves is what you are really after. Add
+`--bundle` to the one command and CW seals the finished run into a single,
+self-checking file:
+
+```bash
+npx cool-workflow quickstart architecture-review \
+  --repo /path/to/your/project --question "What are the main risks?" \
+  --agent-command builtin:claude --bundle --with-trust-key ./trust-pub.pem
+```
+
+This puts a `report.cwrun.json` file **where you are** (not in the looked-at
+repo). The one file holds the report, the `file.js:42` pointers, the signed and
+hash-chained record, **and the public key**.
+
+Give that file to anyone. With no need for your repo, your keys given over on the
+side, or a put-in past `npx`, they make the check on their own — offline, with
+only the file:
+
+```bash
+npx cool-workflow report verify-bundle report.cwrun.json
+```
+
+If the bundle was changed in any way after the fact — the record, a signature, or
+the bytes — the check says so and comes to a stop (it gives back `ok: false` and a
+non-zero code), so a bundle you send on can never be a quiet lie. CW still never
+runs the model itself; it only keeps the books and makes the check.
+
+Want to see the whole thing in 30 seconds, with no agent and no key of your own?
+
+```bash
+npx cool-workflow demo bundle
+```
+
+It makes a real sealed bundle, makes two false changes to it, and shows the check
+getting **both** — offline, with only the public key the bundle carries.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `status: blocked`, `agentConfigured: false` | No agent is in place. Put in `claude` (or give `--agent-command`). |
+| `claude: command not found` | Put in Claude Code so the `claude` command is there, then run again. |
+| Want to see the plan without running the AI | Put in `--preview` — it gives the steps and starts nothing. |
+| Want a live agent trace | Put `CW_AGENT_STREAM=1`. It is stderr-only, TTY-gated, and `CW_NO_STREAM=1` puts it off. |
+| Where did my report go? | The command gives out `reportPath`; it is under `<your-repo>/.cw/runs/<id>/report.md`. |
+
+---
+
+## How it works (one paragraph)
+
+CW is a small TypeScript/Node run-time that needs no other parts. It makes a
+record of the agent loop out in the open — *plan → dispatch → record → verify →
+commit → report* — as long-lasting files on disk, so a run is open to looking-at
+and able to be played again in place of a chat you let go. It never puts a model
+SDK inside and keeps no API key; your put-in-place agent does the thinking, CW
+does the book-keeping and the checking. For the structure, multi-agent
+working-together, execution backends, and the full CLI/MCP face, see the
+**[wiki](https://github.com/coo1white/cool-workflow/wiki)** and
+[`plugins/cool-workflow/docs/`](plugins/cool-workflow/docs/).
+
+---
+
+## License
+
+BSD-2-Clause. See [LICENSE](LICENSE). Built by COOLWHITE LLC.

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

@@ -161,3 +161,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+_No behavioral change in v0.1.88 (the container/remote/ci delegating integrations and their canonical evidence are unchanged; the streaming-default and incremental-resume work this release lives in the agent execution path and the drive, not in these backends)._

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

@@ -301,3 +301,11 @@ No other change to this page in v0.1.84.
 0.1.85
 
 0.1.86
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+## 0.1.88 (v0.1.88)
+
+_No behavioral change in v0.1.88 (`release:check` and the durable run-state compatibility/`state check` path are unchanged; this release's release-flow verdict-capture work lives in the Release Tooling scripts, not in the release-check or migration discipline)._

package/docs/release-history.md

@@ -323,6 +323,16 @@ The orchestration vision came in one release, all reviewer-gated:
 
 Set `CW_AGENT_STREAM=1` to see each worker's live agent trace. The bundled claude wrapper (`builtin:claude` / `scripts/agents/claude-p-agent.js`) keeps the legacy `--output-format json` path by default; only the opt-in path runs claude in `--output-format stream-json` and renders a short human trace (tool uses, assistant text, per-turn summaries) to **stderr**. CW core sends that stderr on to the operator's terminal only when `CW_AGENT_STREAM=1`, CW's own stderr is a TTY, and `CW_NO_STREAM` is not set; piped/CI runs stay quiet (Rule of Silence). Core only sends the stream on, never reads it — vendor-specific rendering is the wrapper's business (policy), not the kernel's (mechanism).
 
+## Builtin Codex agent wrapper (on main, ships next)
+
+`--agent-command builtin:codex` points to a bundled read-only Codex wrapper. It
+runs `codex exec --json --output-last-message`, sends the worker prompt on stdin,
+writes the final answer to `result.md`, and writes one `{model, usage, result}`
+JSON object to stdout for CW provenance. With `CW_AGENT_STREAM=1`, it renders a
+short stderr trace from Codex JSONL events. Gemini, OpenCode, DeepSeek, and GLM
+stay outside CW until their wrapper stream shape is proven by a local smoke; CW
+still imports no model SDK.
+
 v0.1.79
 
 ## Fast Architecture Review (v0.1.80)