cool-workflow 0.1.96 → 0.1.97

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cool-workflow",
   "description": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
-  "version": "0.1.96",
+  "version": "0.1.97",
   "author": {
     "name": "COOLWHITE LLC"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.96",
+  "version": "0.1.97",
   "description": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
   "author": {
     "name": "COOLWHITE LLC"

package/apps/architecture-review/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review",
   "title": "Architecture Review",
   "summary": "Map a repository architecture, assess risks, verify important findings, and synthesize an evidence-backed verdict.",
-  "version": "0.1.96",
+  "version": "0.1.97",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/architecture-review-fast/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review-fast",
   "title": "Architecture Review Fast",
   "summary": "Run a shorter architecture review with parallel map and assess phases for faster first results.",
-  "version": "0.1.96",
+  "version": "0.1.97",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/end-to-end-golden-path/app.json

@@ -3,7 +3,7 @@
   "id": "end-to-end-golden-path",
   "title": "End-to-End Golden Path",
   "summary": "Deterministic one-worker workflow app for proving the CW integration chain.",
-  "version": "0.1.96",
+  "version": "0.1.97",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/pr-review-fix-ci/app.json

@@ -3,7 +3,7 @@
   "id": "pr-review-fix-ci",
   "title": "PR Review Fix CI",
   "summary": "Review a pull request or branch, inspect CI failures, diagnose actionable issues, optionally patch, verify, and summarize with evidence.",
-  "version": "0.1.96",
+  "version": "0.1.97",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/release-cut/app.json

@@ -3,7 +3,7 @@
   "id": "release-cut",
   "title": "Release Cut",
   "summary": "Prepare a release with checklist discipline: version checks, changelog, tests, packaging, release notes, and final verification.",
-  "version": "0.1.96",
+  "version": "0.1.97",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/research-synthesis/app.json

@@ -3,7 +3,7 @@
   "id": "research-synthesis",
   "title": "Research Synthesis",
   "summary": "Split a research question into claims, investigate sources, cross-check evidence, verify claims, and synthesize a concise answer.",
-  "version": "0.1.96",
+  "version": "0.1.97",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/dist/candidate-scoring.js

@@ -115,7 +115,7 @@ function getCandidate(run, candidateId) {
     // Fail-closed integrity boundary (F4/F5): validate the parsed record against
     // its type def BEFORE upserting it as a trusted CandidateRecord. A corrupt or
     // forged candidate.json must throw here rather than flow into the run.
-    const candidate = (0, validation_1.validateCandidateRecord)(JSON.parse(node_fs_1.default.readFileSync(file, "utf8")));
+    const candidate = (0, validation_1.validateCandidateRecord)((0, state_1.readJson)(file));
     upsertCandidate(run, candidate);
     return candidate;
 }
@@ -537,7 +537,7 @@ function loadCandidatesFromDisk(run) {
         // Fail-closed integrity boundary (F4/F5): each candidate.json is validated
         // against CandidateRecord before it merges into the run; a corrupt record
         // throws rather than entering the candidate set as a trusted cast.
-        .map((file) => (0, validation_1.validateCandidateRecord)(JSON.parse(node_fs_1.default.readFileSync(file, "utf8"))));
+        .map((file) => (0, validation_1.validateCandidateRecord)((0, state_1.readJson)(file)));
 }
 function readScores(run, candidateId) {
     const dir = node_path_1.default.join(candidateDir(run, candidateId), "scores");
@@ -550,7 +550,7 @@ function readScores(run, candidateId) {
         // Fail-closed integrity boundary (F4/F5): a score file is validated against
         // CandidateScore before it can feed ranking/selection. A corrupt score must
         // throw, not silently widen the normalized/verdict surface the gate reads.
-        .map((file) => (0, validation_1.validateCandidateScore)(JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, file), "utf8"))));
+        .map((file) => (0, validation_1.validateCandidateScore)((0, state_1.readJson)(node_path_1.default.join(dir, file))));
 }
 function candidateArtifacts(run, candidate) {
     return [

package/dist/capability-core.js

@@ -288,7 +288,12 @@ function runExportArchive(runner, runId, args) {
     // offline. Default falls back to the same env the verify gate reads, so a single
     // configured key both attests at record-time and travels with the export.
     const trustPublicKey = optionalString(args["with-trust-key"] || args.withTrustKey || args.trustKey || args.pubkey) || process.env.CW_AGENT_ATTEST_PUBKEY;
-    return (0, run_export_1.exportRun)(runner.withBaseDir(optionalString(args.cwd)).loadRun(runId), node_path_1.default.resolve(base, output), { trustPublicKey });
+    const resolvedOutput = node_path_1.default.resolve(base, output);
+    const sysDirs = /^\/(etc|bin|sbin|usr|Library|System|Applications|boot|dev|proc|sys|root|var\/log|var\/run)\//;
+    if (sysDirs.test(resolvedOutput)) {
+        throw new Error(`Refusing to write archive to a system directory: ${output}`);
+    }
+    return (0, run_export_1.exportRun)(runner.withBaseDir(optionalString(args.cwd)).loadRun(runId), resolvedOutput, { trustPublicKey });
 }
 function runImportArchive(runner, args) {
     const base = invocationCwd(args);

package/dist/cli/handlers/scheduling.js

@@ -77,7 +77,13 @@ function handleRoutine(args, triggers) {
             return;
         case "fire": {
             const kind = (0, io_1.required)(idOrKind, "trigger kind");
-            const payload = payloadPath ? JSON.parse(node_fs_1.default.readFileSync(payloadPath, "utf8")) : args.options;
+            let payload;
+            try {
+                payload = payloadPath ? JSON.parse(node_fs_1.default.readFileSync(payloadPath, "utf8")) : args.options;
+            }
+            catch (e) {
+                throw new Error(`Failed to parse payload${payloadPath ? ` file "${payloadPath}"` : ""}: ${String(e && e.message || e)}`);
+            }
             (0, io_1.printJson)(triggers.fire(kind, payload));
             return;
         }

package/dist/drive.js

@@ -475,6 +475,16 @@ function prepareConcurrentOutcomes(ctx, batch) {
             continue;
         const job = (0, execution_backend_1.prepareAgentSpawn)(buildAgentRequest(ctx, run, task, manifest));
         if (job) {
+            const sandboxPolicy = manifest.sandboxPolicy;
+            if (sandboxPolicy) {
+                const filteredEnv = (0, execution_backend_1.buildChildEnv)(sandboxPolicy);
+                for (const key of Object.keys(process.env)) {
+                    if (/^(CW_|ANTHROPIC_|OPENAI_|GEMINI_|DEEPSEEK_|CODEX_|GOOGLE_|COHERE_|MISTRAL_|OLLAMA_|AZURE_|AWS_)/i.test(key)) {
+                        filteredEnv[key] = process.env[key];
+                    }
+                }
+                job.env = filteredEnv;
+            }
             jobs.push(job);
             jobTaskIds.push(taskId);
         }

package/dist/execution-backend/agent.js

@@ -276,7 +276,7 @@ function runAgentBatchOutcomes(jobs) {
     const child = (0, node_child_process_1.spawnSync)(process.execPath, [BATCH_DELEGATE_CHILD_SCRIPT], {
         input: JSON.stringify(jobs),
         encoding: "utf8",
-        maxBuffer: 33 * 1024 * 1024 * jobs.length,
+        maxBuffer: Math.min(33 * 1024 * 1024 * jobs.length, 512 * 1024 * 1024),
         timeout: maxTimeout + 30000
     });
     if (!child.error && typeof child.status === "number" && child.status === 0) {

package/dist/execution-backend.js

@@ -39,6 +39,7 @@ exports.attestSandbox = attestSandbox;
 exports.probeBackend = probeBackend;
 exports.runBackend = runBackend;
 exports.delegateChildScript = delegateChildScript;
+exports.shouldStreamAgentStderr = shouldStreamAgentStderr;
 exports.createExecutionBackend = createExecutionBackend;
 exports.backendListPayload = backendListPayload;
 exports.backendShowPayload = backendShowPayload;
@@ -410,7 +411,7 @@ function executeLocal(descriptor, policy, request, label, attestation) {
         // Shell injection guard: reject args that contain shell control characters
         // (beyond template placeholders). The command itself is operator-configured.
         const shellArg = [command, ...args].join(" ").replace(/\{\{[a-zA-Z0-9_.-]+\}\}/g, "");
-        if (/[;&|`$(){}<>!\n\r]/.test(shellArg)) {
+        if (/[;&|`$(){}<>!\n\r#*?~]/.test(shellArg)) {
             throw new Error(`Shell backend refused: args contain shell control characters. ` +
                 `Use the node, bun, or agent backend instead for untrusted inputs.`);
         }
@@ -675,6 +676,25 @@ function runHttpDelegation(descriptor, policy, request, label, handle, attestati
 // agentSubstitutions, substituteAgentArg, recordedAgentHandle, extractEndpointResult,
 // agentHandle) and the concurrent batch live in ./execution-backend/agent.ts; the
 // stateful runners below build the refusal/delegated envelopes and stay here.
+/** Decide whether cw FORWARDS the agent wrapper's live stderr view (stdio
+ *  "inherit") or captures it ("pipe"). Default follows isTTY — interactive shows
+ *  the live view, a pipe/CI stays silent (Rule of Silence). The two env knobs are
+ *  explicit opt-out/opt-in, honored regardless of isTTY so a piped/CI run can still
+ *  opt into the wrapper's plain append-only trace, exactly as the man page promises
+ *  (agent-delegation-drive.7.md "Live output"):
+ *    CW_NO_STREAM=1    — master off (wins over everything)
+ *    CW_AGENT_STREAM=0 — off
+ *    CW_AGENT_STREAM=1 — on, even without a TTY
+ *  With no env set this returns isTTY — byte-identical to the prior inline gate (POLA). */
+function shouldStreamAgentStderr(env, isTTY) {
+    if (env.CW_NO_STREAM === "1")
+        return false;
+    if (env.CW_AGENT_STREAM === "0")
+        return false;
+    if (env.CW_AGENT_STREAM === "1")
+        return true;
+    return isTTY;
+}
 function runAgentProcess(descriptor, policy, request, label, handle, attestation) {
     const resolved = (0, agent_1.resolveAgentInvocation)(request);
     const subst = (0, agent_1.agentSubstitutions)(request, resolved.model);
@@ -692,10 +712,10 @@ function runAgentProcess(descriptor, policy, request, label, handle, attestation
             outcome = request.preparedAgentOutcome;
         }
         else {
-            // Live output on by default when stderr is a TTY. stdout is always
-            // captured as data. CI/pipes stay silent. CW_AGENT_STREAM=0 or
-            // CW_NO_STREAM=1 forces off; CW_AGENT_STREAM=1 forces on.
-            const streamStderr = process.env.CW_AGENT_STREAM !== "0" && Boolean(process.stderr.isTTY) && process.env.CW_NO_STREAM !== "1";
+            // Live output on by default when stderr is a TTY. stdout is always captured
+            // as data. CI/pipes stay silent unless CW_AGENT_STREAM=1 opts them into the
+            // wrapper's plain append-only trace; CW_AGENT_STREAM=0 / CW_NO_STREAM=1 force off.
+            const streamStderr = shouldStreamAgentStderr(process.env, Boolean(process.stderr.isTTY));
             // Build child env from sandbox policy as baseline (respects env.inherit/expose/deny),
             // then re-allow CW_* + well-known API key env vars the agent needs.
             const childEnv = buildChildEnv(policy);

package/dist/mcp-server.js

@@ -35,6 +35,10 @@ function handleLine(line) {
         sendError(null, -32700, `Parse error: ${messageOf(error)}`);
         return;
     }
+    if (message === null || typeof message !== "object" || Array.isArray(message)) {
+        sendError(null, -32600, "Invalid Request: not a JSON-RPC object");
+        return;
+    }
     try {
         if (message.method === "initialize") {
             sendResult(message.id, {

package/dist/onramp.js

@@ -386,6 +386,8 @@ function resolveBaseRef(root, changedFrom, env) {
     return verifyRef(root, "HEAD");
 }
 function verifyRef(root, ref) {
+    if (ref.startsWith("-"))
+        throw new Error(`Invalid onramp base ref (must not start with '-'): ${ref}`);
     const resolved = gitOne(root, ["rev-parse", "--verify", `${ref}^{commit}`]);
     if (!resolved)
         throw new Error(`Unknown onramp base ref: ${ref}`);

package/dist/orchestrator/app-operations.js

@@ -169,6 +169,12 @@ function initApp(appsDir, appId, options, resolveFromBase, validateApp) {
         throw new Error("App id must include at least one letter or digit");
     const title = String(options.title || titleize(id));
     const destinationDir = resolveFromBase(String(options.directory || options.output || node_path_1.default.join(appsDir, id)));
+    // Reject writes to system-owned directories. The operator may provide any
+    // output path, but writing to /etc, /bin, /usr etc. is never valid.
+    const sysDirs = /^\/(etc|bin|sbin|usr|Library|System|Applications|boot|dev|proc|sys|root|var\/log|var\/run)\//;
+    if (sysDirs.test(node_path_1.default.resolve(destinationDir))) {
+        throw new Error(`Refusing to create app in a system directory: ${destinationDir}`);
+    }
     const manifestPath = node_path_1.default.join(destinationDir, "app.json");
     const entrypointPath = node_path_1.default.join(destinationDir, "workflow.js");
     if (!options.force && (node_fs_1.default.existsSync(manifestPath) || node_fs_1.default.existsSync(entrypointPath))) {

package/dist/orchestrator/cli-options.js

@@ -112,8 +112,14 @@ function metadataOption(options) {
     const raw = options.metadata;
     if (raw && typeof raw === "object" && !Array.isArray(raw))
         return raw;
-    if (typeof raw === "string")
-        return JSON.parse(raw);
+    if (typeof raw === "string") {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`Invalid JSON in --metadata: ${String(raw).slice(0, 80)}`);
+        }
+    }
     return undefined;
 }
 function withoutHostRunKeys(args) {

package/dist/orchestrator/lifecycle-operations.js

@@ -228,6 +228,9 @@ function recordResult(run, taskId, resultPath, options = {}) {
     try {
         (0, verifier_1.assertTaskCanComplete)(run, task);
         const absoluteResultPath = node_path_1.default.resolve(resultPath);
+        if (/^\/(etc|bin|sbin|usr|Library|System|Applications|boot|dev|proc|sys|root|var\/log|var\/run)\//.test(absoluteResultPath)) {
+            throw new Error(`Result path must not be a system directory: ${resultPath}`);
+        }
         if (!node_fs_1.default.existsSync(absoluteResultPath)) {
             throw new Error(`Result file does not exist: ${absoluteResultPath}`);
         }

package/dist/orchestrator/migration-operations.js

@@ -40,5 +40,5 @@ function loadMigrationSnapshot(target, options) {
         : node_path_1.default.join(process.cwd(), ".cw", "runs", target, "state.json");
     if (!node_fs_1.default.existsSync(file))
         throw new Error(`Migration target not found: ${target}`);
-    return { snapshot: JSON.parse(node_fs_1.default.readFileSync(file, "utf8")), contract, dir: node_path_1.default.dirname(file) };
+    return { snapshot: (0, state_1.readJson)(file), contract, dir: node_path_1.default.dirname(file) };
 }

package/dist/run-export.js

@@ -453,7 +453,16 @@ function verifyReportBundle(archivePath, options = {}) {
         }
         if (options.extractReportTo && reportContent !== undefined) {
             reportExtractedTo = node_path_1.default.resolve(options.extractReportTo);
-            node_fs_1.default.writeFileSync(reportExtractedTo, reportContent);
+            if (options.cwd) {
+                const baseCwd = node_path_1.default.resolve(options.cwd);
+                if (!(0, state_1.isContainedPath)(reportExtractedTo, baseCwd)) {
+                    failedChecks.push({ name: "extract-report", code: "path-outside-working-directory" });
+                    reportExtractedTo = undefined;
+                }
+            }
+            if (reportExtractedTo) {
+                node_fs_1.default.writeFileSync(reportExtractedTo, reportContent);
+            }
         }
     }
     catch (error) {

package/dist/sandbox-profile.js

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

package/dist/triggers.js

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

package/dist/version.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = exports.LEGACY_RUN_STATE_SCHEMA_VERSION = exports.CURRENT_RUN_STATE_SCHEMA_VERSION = exports.WORKFLOW_APP_SCHEMA_VERSION = exports.CURRENT_COOL_WORKFLOW_VERSION = void 0;
-exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.96";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.97";
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
 exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
 exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;

package/dist/workbench-host.js

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

package/docs/agent-delegation-drive.7.md

@@ -409,3 +409,5 @@ The one-command `cw -q` headline now routes the question and defaults the repo t
 0.1.95
 
 0.1.96
+
+0.1.97

package/docs/cli-mcp-parity.7.md

@@ -551,3 +551,5 @@ CLI golden-path fixes: `cw -q "…"` routes the question (was read as an app id
 0.1.95
 
 0.1.96
+
+0.1.97

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

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

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

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

package/docs/demo.7.md

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

package/docs/doctor.7.md

@@ -0,0 +1,97 @@
+# DOCTOR(7)
+
+## NAME
+
+`cw doctor` — check the setup and name all problems with their fixes
+
+## SYNOPSIS
+
+```text
+node dist/cli.js doctor
+node dist/cli.js doctor --json
+node dist/cli.js doctor --fix
+node dist/cli.js doctor --onramp
+node dist/cli.js doctor --onramp --changed-from origin/main
+```
+
+## DESCRIPTION
+
+`cw doctor` is a read-only check of your CW setup, based on `brew doctor`. It
+probes your machine and says what is wrong and what to do about it — before a
+run fails with a strange error.
+
+The command never makes any file; it only reads. Running it changes nothing on
+disk.
+
+It gives back a report with one line for every check. Each check has a status
+(`ok`, `warn`, or `fail`) and a clear note. Checks that are not `ok` carry a
+`fix` line with the right command or step to put things right.
+
+If any check has status `fail`, the command exits with code 1 (non-zero). A
+`warn` (for example, no agent yet — demos and previews still work) does not
+make the exit fail.
+
+## CHECKS
+
+The command runs six checks in order:
+
+**node**
+: The Node.js version. CW needs v18 or higher. A `fail` here stops everything.
+
+**agent**
+: The AI agent backend. CW can auto-detect agents (Claude, Codex, Gemini,
+OpenCode) or take one from `CW_AGENT_COMMAND` / `--agent-command`. Without one,
+real runs report `status: blocked`, but `demo` and `--preview` still work.
+
+**agent-binary**
+: When the agent is set by a command name (not auto or HTTP), this check sees if
+the binary is on `$PATH`. Missing here gives a `warn` — the run will get a clear
+error later, but CW will not guess at a different agent.
+
+**git**
+: The `git` command. CW uses it for commit place of origin. A `warn` here means
+commit roots will be recorded as absent; no other part of a run needs git.
+
+**home-registry**
+: The cross-repo run index at `$CW_HOME` (default `$HOME/.local/state/cool-workflow`).
+This location must be writable. A `fail` here blocks discovery across repos.
+
+**repo-state**
+: The per-repo run store under `<cwd>/.cw`. Must be writable. A `warn` here
+means runs stay in-memory only — you can use `--cwd PATH` to point at another
+writable root.
+
+## OPTIONS
+
+`--json`
+: Give back the full report as a stable JSON object. Good for scripts.
+
+`--fix`
+: Give back only the fix commands for every non-ok check. Same as running `cw fix`
+by itself.
+
+`--onramp`
+: Add a quick-start guide to the human output, with recommended checks and a
+three-step path to your first report.
+
+`--changed-from <ref>`
+: When used with `--onramp`, make the quick-start checks cover only files changed
+since `<ref>` (a Git branch, tag, or commit). Good for CI and code reading.
+
+## FILES
+
+```text
+src/doctor.ts
+dist/doctor.js
+```
+
+## EXIT CODES
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | All checks ok (may have warnings) |
+| 1 | One or more checks have status `fail` |
+
+## SEE ALSO
+
+cw fix — the same checks, but gives back only the fix commands

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

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

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

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

package/docs/execution-backends.7.md

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