cool-workflow 0.1.95 → 0.1.97

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

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

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

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

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

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

package/docs/pipeline-verbs.7.md

@@ -0,0 +1,93 @@
+# PIPELINE-VERBS(7)
+
+## NAME
+
+`cw plan`, `cw dispatch`, `cw result` — the three core pipeline engine verbs
+
+## SYNOPSIS
+
+```text
+node dist/cli.js plan <workflow-id> [--question Q] [--repo PATH] [--sandbox PROFILE]
+node dist/cli.js dispatch <run-id> [--sandbox PROFILE]
+node dist/cli.js result <run-id> <task-id> <result-file>
+```
+
+## DESCRIPTION
+
+These three verbs are the engine that drives every CW run. A run goes through
+three stages: plan (get ready), dispatch (hand out work), and result (take work
+back). Together they make the CW pipeline loop — a worker gets a task, does it,
+and hands in a result file; CW checks the result and moves the run forward.
+
+None of these verbs starts or stops the agent host. They give the control-plane
+data that the host reads and acts on. The host keeps its own loop: call
+`dispatch`, give the task to an agent, get back a result file, call `result`.
+
+## PLAN
+
+`cw plan <workflow-id>` makes a new run and gives back its canonical plan
+summary in JSON. The plan has the run id, the first task (or tasks) to do,
+the sandbox profile, and the state of the run.
+
+The workflow id names a workflow app that gives the run its shape: inputs,
+steps, evidence gates, and sandbox policy. Use `cw list` to see the workflow
+apps you have.
+
+The plan output is stable JSON, good for scripts and the agent host.
+
+Options:
+: `--question`, `--repo`, `--sandbox` — the same inputs the workflow app
+expects. Different apps take different inputs; see `cw info <workflow-id>`
+for the list.
+
+## DISPATCH
+
+`cw dispatch <run-id>` makes the next task ready for a worker. It gives back
+a dispatch manifest in JSON: the task id, the prompt, the sandbox profile, and
+the input and output paths the worker should use.
+
+The dispatch picks the next runnable task in the pipeline. If no task is ready
+— for example, all tasks are done or waiting on evidence — the dispatch payload
+says so, and the host should wait or check the run status.
+
+Options:
+: `--sandbox PROFILE` — pick a sandbox profile for the worker. The default is
+the one the workflow app asked for.
+
+## RESULT
+
+`cw result <run-id> <task-id> <result-file>` records a worker's result against
+a task. The result file is a Markdown file the agent wrote — it must have a
+`cw:result` JSON fence with the agent's `findings` and `evidence`.
+
+CW accepts the result, checks it, and advances the run pipeline. If the result
+is bad (missing, broken, or the evidence does not check out), CW rejects it and
+gives back an error feedback record. The host can then try again or give the
+task a different agent.
+
+After `result`, the run may be done or have more tasks waiting. Check with
+`cw status <run-id>` or `cw next <run-id>`.
+
+## FILES
+
+```text
+.cw/runs/<run-id>/state.json
+.cw/runs/<run-id>/dispatches/<dispatch-id>.json
+.cw/runs/<run-id>/tasks/<task-id>.json
+.cw/runs/<run-id>/results/<task-id>.md
+.cw/runs/<run-id>/workers/<worker-id>/worker.json
+```
+
+## PIPELINE FLOW
+
+```text
+plan -> dispatch -> [agent does work] -> result -> [dispatch...] -> done
+                                        └─ rejected -> feedback -> retry
+```
+
+## SEE ALSO
+
+cw init — make a new workflow definition from nothing
+cw status — see the current state of a run
+cw next — find the next action for a run
+pipeline-runner.7.md — the full pipeline engine detail

package/docs/project-index.md

@@ -1,15 +1,15 @@
 # Cool Workflow Project Index
 
-Generated from the current repository code on 2026-06-27 by `npm run sync:project-index`.
+Generated from the current repository code on 2026-06-30 by `npm run sync:project-index`.
 
 ## Snapshot
 
 - Package: `cool-workflow`
-- Version: `0.1.95`
+- Version: `0.1.97`
 - Source modules: `68`
 - Workflow apps: `8`
-- Docs: `53`
-- Smoke tests: `154`
+- Docs: `59`
+- Smoke tests: `164`
 - Repository: https://github.com/coo1white/cool-workflow
 
 ## Architecture
@@ -145,14 +145,18 @@ multi-agent host -> topology -> blackboard/coordinator
 - [Contract Migration Tooling](contract-migration-tooling.7.md)
 - [Control-Plane Scheduling](control-plane-scheduling.7.md)
 - [Coordinator / Blackboard](coordinator-blackboard.7.md)
+- [DEMO(7)](demo.7.md)
+- [DOCTOR(7)](doctor.7.md)
 - [Dogfood One Real Repo](dogfood-one-real-repo.7.md)
 - [Durable State & Locking](durable-state-and-locking.7.md)
 - [End-to-End Golden Path](end-to-end-golden-path.7.md)
 - [ERROR-FEEDBACK(7)](error-feedback.7.md)
 - [Evidence Adoption Reasoning Chain](evidence-adoption-reasoning-chain.7.md)
 - [EXECUTION-BACKENDS(7)](execution-backends.7.md)
+- [FIX(7)](fix.7.md)
 - [Getting Started](getting-started.md)
 - [Cool Workflow Docs](index.md)
+- [INIT(7)](init.7.md)
 - [MCP App Surface](mcp-app-surface.7.md)
 - [Multi-Agent CLI + MCP Surface](multi-agent-cli-mcp-surface.7.md)
 - [Multi-Agent Eval & Replay Harness](multi-agent-eval-replay-harness.7.md)
@@ -164,6 +168,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [Observability + Cost Accounting](observability-cost-accounting.7.md)
 - [Operator UX](operator-ux.7.md)
 - [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)
@@ -172,6 +177,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [Release Tooling](release-tooling.7.md)
 - [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)
@@ -194,7 +200,9 @@ multi-agent host -> topology -> blackboard/coordinator
 
 Smoke tests mirror the public contracts. The high-signal suites are:
 
+- [agent-config-atomic-write-smoke.js](../test/agent-config-atomic-write-smoke.js)
 - [agent-delegation-drive-smoke.js](../test/agent-delegation-drive-smoke.js)
+- [agent-stream-gate-smoke.js](../test/agent-stream-gate-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-phase-cache-smoke.js](../test/architecture-review-fast-phase-cache-smoke.js)
@@ -224,6 +232,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [cli-render-smoke.js](../test/cli-render-smoke.js)
 - [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)
 - [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)
@@ -248,6 +257,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [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)
+- [feedback-ops-unit-smoke.js](../test/feedback-ops-unit-smoke.js)
 - [freebsd-audit-fixes-smoke.js](../test/freebsd-audit-fixes-smoke.js)
 - [gemini-agent-wrapper-smoke.js](../test/gemini-agent-wrapper-smoke.js)
 - [gemini-opencode-agent-wrapper-smoke.js](../test/gemini-opencode-agent-wrapper-smoke.js)
@@ -257,6 +267,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [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)
+- [mcp-tool-call-coverage-smoke.js](../test/mcp-tool-call-coverage-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)
@@ -278,6 +289,9 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [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)
+- [parse-guard-smoke.js](../test/parse-guard-smoke.js)
+- [parse-hardening-round2-smoke.js](../test/parse-hardening-round2-smoke.js)
+- [path-containment-smoke.js](../test/path-containment-smoke.js)
 - [pdca-blackboard-loop-smoke.js](../test/pdca-blackboard-loop-smoke.js)
 - [pii-redaction-smoke.js](../test/pii-redaction-smoke.js)
 - [pipeline-auto-advance-smoke.js](../test/pipeline-auto-advance-smoke.js)
@@ -296,6 +310,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [release-check-skip-smoke.js](../test/release-check-skip-smoke.js)
 - [release-flow-smoke.js](../test/release-flow-smoke.js)
 - [release-gate-smoke.js](../test/release-gate-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)
@@ -319,6 +334,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [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-env-batch-hardening-smoke.js](../test/sandbox-env-batch-hardening-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)

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

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

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

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

package/docs/release-tooling.7.md

@@ -85,6 +85,22 @@ The dogfood release smoke and the architecture-review dogfood smoke are separate
 test files. The split keeps the same release and agent-drive proof, but lets
 `test:ci` schedule the two long checks in parallel.
 
+## PR CI Merge Notes
+
+When a PR is ready, list open PRs by creation time and merge the oldest ready
+one first. After each merge, check the next PR again; a new main commit may make
+it need a rebase.
+
+If main moved after the PR branch was made, replay the PR commits on top of the
+new main in a clean worktree. Keep local unrelated changes out of the rebase and
+out of the PR.
+
+Treat CI as the source of truth for what blocks the merge. Read the failed step
+first, fix only that drift, then push again. A common drift is the npm README:
+when `readme-sync-smoke.js` says the package README is stale, run
+`npm run sync:readme`, add only `plugins/cool-workflow/README.md`, and let CI run
+again.
+
 ## Boundary
 
 Release Tooling touches only the build/release surfaces. It adds no runtime
@@ -270,3 +286,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.94
 
 0.1.95
+
+0.1.96
+
+0.1.97

package/docs/routine.7.md

@@ -0,0 +1,73 @@
+# ROUTINE(7)
+
+## NAME
+
+`cw routine` — make and manage trigger-based workflow routines
+
+## SYNOPSIS
+
+```text
+node dist/cli.js routine create --kind api|github --prompt PROMPT [--match JSON]
+node dist/cli.js routine list [--kind KIND]
+node dist/cli.js routine delete <trigger-id>
+node dist/cli.js routine fire <kind> <payload-file>
+node dist/cli.js routine events [<trigger-id>]
+```
+
+## DESCRIPTION
+
+`cw routine` is the local trigger bridge for CW. It lets you make named
+triggers that fire when something happens — an API event, a GitHub webhook, or
+another outside signal. Each trigger carries a prompt template; when fired,
+the prompt gets filled with the event data and handed to an agent host.
+
+CW keeps routine data in:
+
+```text
+.cw/routines/triggers.json
+.cw/routines/payloads/
+```
+
+CW itself does not run a web server or listen for webhooks. The routine bridge
+is a local data store that can be joined to GitHub Actions, webhooks, cron, or
+a small HTTP adapter.
+
+## COMMANDS
+
+**create**
+: Make a new trigger. `--kind` is `api` or `github`. `--prompt` is the prompt
+template the agent will see. `--match` is an optional JSON object that filters
+events (for example, `{"action":"opened"}` for GitHub pull requests).
+
+**list**
+: List all triggers, or filter by kind with `--kind`.
+
+**delete**
+: Remove a trigger by its id.
+
+**fire**
+: Record an event against a trigger. Give the trigger kind and a path to a
+JSON payload file. CW matches the payload against the trigger's match rules
+and fills out the prompt.
+
+**events**
+: List the events that have been recorded for a trigger.
+
+## FILES
+
+```text
+.cw/routines/triggers.json
+.cw/routines/payloads/<event-id>.json
+```
+
+## EXIT CODES
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Command done |
+| 1 | Error (bad arguments, missing trigger, etc.) |
+
+## SEE ALSO
+
+cw sched — durable run-queue scheduling for workflow runs
+control-plane-scheduling.7.md — the full scheduling and run management design

package/docs/routines.md

@@ -64,6 +64,36 @@ report path and digest.
 The `--metrics` flag is not required and it gives back foreground time used plus
 agent-spawn and result-cache-hit counts for the fast run.
 
+## PDCA Blackboard Development Lessons
+
+When a task asks for agents to work together, first try the parts CW already
+has:
+
+- workflow apps give the work shape
+- worker output gives checked facts
+- the blackboard gives shared state
+- MCP gives tool access to the same state
+- smoke tests prove the loop
+
+Do not make a new MCP server when the existing server can show the same run
+state. Add a workflow app first, then prove the app with one smoke that uses
+both CLI and MCP.
+
+For a three-agent loop, keep the order plain:
+
+```text
+plan -> build -> audit -> next action
+```
+
+Each agent should write one blackboard message and, when there is a result
+file, one artifact ref. Take a snapshot after the audit and after the next
+action. If audit evidence is missing, let the worker evidence gate refuse the
+result instead of adding a new policy layer.
+
+Before a PR, base the branch on `origin/main`, run the generated-doc checks,
+and sync generated docs when the gate says they are stale. This keeps unrelated
+local commits and generated README/index drift out of the work.
+
 ## Boundary
 
 CW v0.1.1 does not give managed cloud infrastructure. It gives a local

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

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

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

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

package/docs/sandbox-profiles.7.md

@@ -26,6 +26,21 @@ normalization, worker result acceptance, and durable feedback for denied worker
 output. The agent host has to do OS-level file access, process execution,
 network access, and environment filtering.
 
+**IMPORTANT**: Under the default `node` backend, a sandbox profile's
+`execute`, `network`, and `env` policy is **attested, not enforced**. CW
+validates the policy, records it in the worker manifest, and attests that
+these limits were declared — but the actual enforcement of command execution
+restrictions, network isolation, and environment variable filtering is
+DELEGATED to the host runtime. For full enforcement, use the `container`
+backend (`--backend container`) with Docker/Podman, or apply OS-level
+sandboxing to the agent process. Without OS enforcement, a worker under a
+`locked-down` profile can still run arbitrary commands and access the network.
+
+CW also now (v0.1.95) applies `buildChildEnv(policy)` as a baseline for agent
+spawns — only `PATH`, `HOME`, explicit `expose` entries, and well-known
+`CW_*` + LLM provider API key environment variables pass through. The
+operator's other process environment is not inherited by default.
+
 The design goal is simple:
 
 ```text

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

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

package/docs/team-collaboration.7.md

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

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

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

package/manifest/README.md

@@ -1,11 +1,12 @@
 # Vendor Manifest Source of Truth
 
 Every agent host scans a different, hard-coded manifest directory
-(`.claude-plugin/`, `.codex-plugin/`, `.agents/`) with a different JSON shape.
-You cannot unify the directory or the schema — so we do not try. Instead, all
-vendor manifests are **generated** from one neutral source and point at the same
-shared runtime (`skills/`, `dist/`, `apps/`, the MCP server). No vendor forks the
-logic; each manifest is a thin adapter.
+(`.claude-plugin/`, `.codex-plugin/`, `.agents/`, `.gemini-plugin/`,
+`.opencode-plugin/`) with a different JSON shape. You cannot unify the directory
+or the schema — so we do not try. Instead, all vendor manifests are **generated**
+from one neutral source and point at the same shared runtime (`skills/`, `dist/`,
+`apps/`, the MCP server). No vendor forks the logic; each manifest is a thin
+adapter.
 
 This is the mechanism/policy split: shared assets are mechanism, per-vendor
 manifests are policy.
@@ -25,13 +26,18 @@ npm run gen:manifests -- --check   # fail (exit 1) if any generated file drifted
 
 ## Generated outputs (do NOT hand-edit)
 
+Five vendors are generated today. Paths are repo-root-relative.
+
 | Vendor | Marketplace | Plugin manifest | MCP config | MCP path var |
 | --- | --- | --- | --- | --- |
-| Claude Code | `../../../.claude-plugin/marketplace.json` | `../.claude-plugin/plugin.json` | `../.mcp.json` (auto-discovered) | `${CLAUDE_PLUGIN_ROOT}/` |
-| Codex / `.agents` | `../../../.agents/plugins/marketplace.json` | `../.codex-plugin/plugin.json` | `../.codex-plugin/mcp.json` | `./` |
-
-The two vendors read **different** MCP files, so the plugin-root path variable
-never collides.
+| Claude Code | `.claude-plugin/marketplace.json` | `plugins/cool-workflow/.claude-plugin/plugin.json` | `plugins/cool-workflow/.mcp.json` (auto-discovered) | `${CLAUDE_PLUGIN_ROOT}/` |
+| Codex | `.agents/plugins/marketplace.json` | `plugins/cool-workflow/.codex-plugin/plugin.json` | `plugins/cool-workflow/.codex-plugin/mcp.json` | `./` |
+| `.agents` | — | `.agents/plugins/cool-workflow/plugin.json` | `.agents/plugins/cool-workflow/mcp.json` | `./` |
+| Gemini | — | `plugins/cool-workflow/.gemini-plugin/plugin.json` | `plugins/cool-workflow/.gemini-plugin/mcp.json` | `./` |
+| OpenCode | — | `plugins/cool-workflow/.opencode-plugin/plugin.json` | `plugins/cool-workflow/.opencode-plugin/mcp.json` | `./` |
+
+Each vendor reads its **own** MCP file, so the plugin-root path variable never
+collides.
 
 ## Adding a new vendor (Cursor, Windsurf, …)
 

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.1.95",
+    "version": "0.1.97",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.95",
+  "version": "0.1.97",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"
@@ -62,9 +62,11 @@
     "onramp:check": "node scripts/onramp-check.js --check",
     "version:sync": "node scripts/version-sync-check.js",
     "release:check": "node scripts/release-check.js",
-    "test": "node dist/cli.js version > /dev/null && node test/run-all.js",
+    "test": "node dist/cli.js version > /dev/null && node test/run-all.js --fast --sample 35",
+    "test:full": "node dist/cli.js version > /dev/null && node test/run-all.js --sample 55",
+    "test:gate": "node dist/cli.js version > /dev/null && node test/run-all.js",
     "test:fast": "npm run build --if-present && node dist/cli.js version > /dev/null && node test/run-all.js --concurrency auto",
-    "test:ci": "node dist/cli.js version > /dev/null && node test/run-all.js --concurrency auto",
+    "test:ci": "npm run build && node dist/cli.js version > /dev/null && node test/run-all.js --sample 55",
     "test:coverage": "node dist/cli.js version > /dev/null && node scripts/coverage-gate.js --concurrency auto",
     "eval:replay": "tsc -p tsconfig.json && node test/multi-agent-eval-replay-harness-smoke.js",
     "ci": "npm run build && npm run check && npm run test && npm run release:check",

package/scripts/agents/agent-adapter-core.js

@@ -2,6 +2,7 @@
 "use strict";
 
 const fs = require("node:fs");
+const path = require("node:path");
 
 const RESULT_CONTRACT = `
 === HOW TO RETURN YOUR ANSWER (overrides any 'write to result.md' instruction above) ===
@@ -448,6 +449,28 @@ function emitReport(model, usage, resultText) {
   process.stdout.write(JSON.stringify({ model, usage, result: resultText }));
 }
 
+// Drop the failed agent's stderr beside the worker's result.md so a `failed (exit
+// 1)` is readable AFTER the fact. CW core keeps only the child's stdout + exit
+// code (byte-stable evidence), so without this the real reason — a relay 5xx, an
+// auth error, a killed run — is lost. The worker dir already has a `logs/` folder
+// (src/worker-isolation.ts); resultPath is `<workerDir>/result.md`, so its
+// `logs/agent-stderr.log` sibling is the natural home. Advisory only: never throws,
+// never changes the exit code or the recorded evidence.
+function persistStderr(resultPath, text) {
+  let t = String(text || "").trim();
+  if (!t || !resultPath) return;
+  try {
+    t = String(t).replace(/\b(sk-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]{20,}|xox[bprs]-[A-Za-z0-9-]{20,}|Bearer\s+\S+|Authorization:\s*\S+|api[_-]?key[=:]\s*\S+|token[=:]\s*\S+)/gi, (match) => match.slice(0, 4) + "***[REDACTED]");
+    const cap = 4096;
+    if (t.length > cap) t = t.slice(0, cap) + `\n  [truncated from ${t.length} bytes]`;
+    const dir = path.join(path.dirname(resultPath), "logs");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "agent-stderr.log"), `${t}\n`, "utf8");
+  } catch {
+    /* advisory only — diagnostics must never break the run */
+  }
+}
+
 module.exports = {
   RESULT_CONTRACT,
   buildPrompt,
@@ -461,5 +484,6 @@ module.exports = {
   parseJsonLines,
   flushJsonLines,
   writeResult,
-  emitReport
+  emitReport,
+  persistStderr // save a failed agent's stderr to <workerDir>/logs/agent-stderr.log (shared by all wrappers)
 };

package/scripts/agents/claude-p-agent.js

@@ -34,7 +34,7 @@ const { spawn, spawnSync } = require("node:child_process");
 // wrappers instead of carrying a private copy. A drifted inline copy (ASCII
 // hyphens silently became em-dashes here) meant claude was sent a different
 // instruction text than the other providers for the same contract.
-const { buildPrompt, createRenderer, toolLabel, summarizeToolResult } = require("./agent-adapter-core");
+const { buildPrompt, createRenderer, persistStderr, toolLabel, summarizeToolResult } = require("./agent-adapter-core");
 
 const inputPath = process.argv[2];
 const resultPath = process.argv[3];
@@ -56,11 +56,14 @@ if (!streamEnabled) {
     shell: false
   });
   if (child.error) {
+    persistStderr(resultPath, `claude spawn failed: ${child.error.message}`);
     process.stderr.write(`claude spawn failed: ${child.error.message}\n`);
     process.exit(1);
   }
   if (child.status !== 0) {
-    process.stderr.write(String(child.stderr || `claude exited ${child.status}`));
+    const detail = String(child.stderr || `claude exited ${child.status}`);
+    persistStderr(resultPath, detail);
+    process.stderr.write(detail);
     process.exit(child.status === null ? 1 : child.status);
   }
 
@@ -69,6 +72,7 @@ if (!streamEnabled) {
   try {
     parsed = JSON.parse(out);
   } catch (error) {
+    persistStderr(resultPath, `claude output was not JSON: ${error.message}`);
     process.stderr.write(`claude output was not JSON: ${error.message}\n`);
     process.exit(1);
   }
@@ -166,6 +170,7 @@ function renderEvent(ev) {
 
 child.on("error", (err) => {
   render.finishLive(); // restore the terminal before exiting
+  persistStderr(resultPath, `claude spawn failed: ${err.message}`);
   process.stderr.write(`claude spawn failed: ${err.message}\n`);
   process.exit(1);
 });
@@ -174,12 +179,15 @@ child.on("close", (code) => {
   render.finishLive(); // stop the spinner + restore the cursor BEFORE any further output
   render.writeTranscript(transcriptPath); // full narration + tool I/O always saved
   if (code !== 0) {
+    const detail = childStderr.trim() || `claude exited ${code === null ? "(timeout/killed)" : code}`;
+    persistStderr(resultPath, detail);
     if (childStderr.trim()) process.stderr.write(`${childStderr.trim()}\n`);
     process.stderr.write(`claude exited ${code === null ? "(timeout/killed)" : code}\n`);
     process.exit(code === null ? 1 : code);
   }
   if (typeof resultText !== "string") {
     // Fail closed: no result event ⇒ no result.md ⇒ CW records a failed hop.
+    persistStderr(resultPath, childStderr.trim() || "claude produced no result event — refusing to fabricate a result");
     process.stderr.write("claude produced no result event — refusing to fabricate a result\n");
     process.exit(1);
   }