cool-workflow 0.1.86 → 0.1.88

package/dist/telemetry-attestation.js

@@ -53,7 +53,11 @@ function canonicalTelemetryPayload(usage, ctx) {
         usage: usage ?? null,
         runId: ctx.runId,
         taskId: ctx.taskId,
-        promptDigest: ctx.promptDigest
+        promptDigest: ctx.promptDigest,
+        // Present ONLY when the signer covered the result. Omitting the key keeps the
+        // canonical bytes byte-identical to the original 4-field payload, so every
+        // pre-result-coverage signature still verifies (POLA / back-compat).
+        ...(ctx.resultDigest !== undefined ? { resultDigest: ctx.resultDigest } : {})
     });
 }
 function messageOf(error) {
@@ -110,16 +114,26 @@ function verifyTelemetryAttestation(usage, signatureB64, trustPublicKeyPem, ctx)
     catch {
         return { status: "unattested", reason: "signature is not valid base64" };
     }
-    const payload = Buffer.from(canonicalTelemetryPayload(usage, ctx), "utf8");
+    const matches = (c) => node_crypto_1.default.verify(null, Buffer.from(canonicalTelemetryPayload(usage, c), "utf8"), publicKey, signature);
     let ok = false;
+    let coversResult = false;
     try {
-        ok = node_crypto_1.default.verify(null, payload, publicKey, signature);
+        ok = matches(ctx);
+        // A match on the first arm (which carries resultDigest when CW has one) means
+        // the signature covered the result — the findings — not just the usage.
+        coversResult = ok && ctx.resultDigest !== undefined;
+        // Back-compat: a signer that predates result coverage signed only the 4-field
+        // payload, so on a miss retry WITHOUT resultDigest. A NEW signer who covered
+        // the result fails BOTH arms when the result is edited (its resultDigest no
+        // longer matches), so result tampering is still caught.
+        if (!ok && ctx.resultDigest !== undefined)
+            ok = matches({ ...ctx, resultDigest: undefined });
     }
     catch (error) {
         return { status: "unattested", reason: `verification error: ${messageOf(error)}` };
     }
     return ok
-        ? { status: "attested", algorithm: "ed25519" }
+        ? { status: "attested", algorithm: "ed25519", ...(coversResult ? { coversResult: true } : {}) }
         : { status: "unattested", reason: "signature does not match reported usage (tampered, replayed, or wrong key)" };
 }
 /** Resolve a trust key from a config value that is EITHER an inline PEM or a path
@@ -160,6 +174,7 @@ function stableDigest(value) {
 }
 function verifyTelemetrySignatures(records, trustPublicKeyPem) {
     const checks = [];
+    const resultBound = [];
     let checked = 0;
     let reverified = 0;
     let failed = 0;
@@ -190,11 +205,20 @@ function verifyTelemetrySignatures(records, trustPublicKeyPem) {
         const result = verifyTelemetryAttestation(record.reportedUsage, record.usageSignature, trustPublicKeyPem, {
             runId: record.runId,
             taskId: record.taskId,
-            promptDigest: record.promptDigest
+            promptDigest: record.promptDigest,
+            // Result-bound records carry the signed digest; verifyTelemetryAttestation
+            // reconstructs the 5-field payload (and falls back to 4-field for old records).
+            resultDigest: record.resultDigest
         });
         if (result.status === "attested") {
             reverified += 1;
             checks.push({ name: `signature[${i}]`, pass: true });
+            // Only a signature that actually COVERED the result digest anchors it — a
+            // 4-field fallback (coversResult false) must not let an injected resultDigest
+            // be trusted downstream.
+            if (result.coversResult && record.resultDigest) {
+                resultBound.push({ taskId: record.taskId, resultDigest: record.resultDigest });
+            }
         }
         else {
             failed += 1;
@@ -207,5 +231,5 @@ function verifyTelemetrySignatures(records, trustPublicKeyPem) {
             });
         }
     }
-    return { keyProvided: Boolean(trustPublicKeyPem), checked, reverified, failed, checks };
+    return { keyProvided: Boolean(trustPublicKeyPem), checked, reverified, failed, resultBound, checks };
 }

package/dist/telemetry-demo.js

@@ -6,13 +6,17 @@
 // Fully hermetic + deterministic: generates an EPHEMERAL ed25519 keypair, builds
 // a REAL telemetry ledger through the production append API (appendTelemetryAttestation
 // + signTelemetry — byte-identical to what a live attested run writes), then
-// demonstrates BOTH tamper-evidence layers catching a forgery:
+// demonstrates all THREE tamper-evidence layers catching a forgery:
 //   A) LEDGER layer — flip a recorded verdict on disk (unattested -> attested, the
 //      canonical "forge a green record" attack) -> verifyTelemetryLedger recomputes
 //      every hash independently, so the edited record's hash mismatches AND every
 //      record after it breaks the chain (cascade).
 //   B) SIGNATURE layer — inflate the reported tokens but keep the original ed25519
 //      signature -> verifyTelemetryAttestation rejects it ("signature does not match").
+//   C) RESULT layer — edit the agent's SIGNED FINDING after signing. The executor
+//      binds sha256(result.md) into the ed25519 payload; CW re-derives the digest
+//      from the result file at verify time, so an edited finding no longer joins the
+//      signature. This is the threat a usage-only signature never covered.
 //
 // No model, no network, no API key, no second repo — runs in a private tmpdir.
 var __importDefault = (this && this.__importDefault) || function (mod) {
@@ -161,6 +165,30 @@ function runTamperDemo(options = {}) {
         after: { verified: sigCheck.status === "attested", detail: sigCheck.reason || sigCheck.status },
         failures: sigCheck.status === "attested" ? [] : [`signature: ${sigCheck.reason}`]
     });
+    // 3c. RESULT layer — the REAL threat the result-bound signature closes: the agent's
+    //     signed FINDING is edited after signing. The executor binds sha256(result.md)
+    //     into the ed25519 payload (a 5-field, result-COVERING signature); CW re-derives
+    //     the digest from the result file at verify time. An edited finding hashes to a
+    //     different digest, so the signature joins neither the 5-field nor the 4-field
+    //     payload and the verify rejects it. A usage-only signature never covered this.
+    const findingSigned = "Finding: auth bypass in login() — severity HIGH";
+    const findingEdited = findingSigned.replace("HIGH", "LOW");
+    const resultCtx = { runId, taskId: target.hop.taskId, promptDigest: target.hop.promptDigest };
+    const resultSignature = (0, telemetry_attestation_1.signTelemetry)(target.hop.usage, privateKeyPem, { ...resultCtx, resultDigest: (0, execution_backend_1.sha256)(findingSigned) });
+    // Baseline: the signed finding verifies, and the signature actually COVERED the result.
+    const resultClean = (0, telemetry_attestation_1.verifyTelemetryAttestation)(target.hop.usage, resultSignature, publicKeyPem, { ...resultCtx, resultDigest: (0, execution_backend_1.sha256)(findingSigned) });
+    // Tamper: CW re-derives the digest from the EDITED finding -> no longer the signed digest.
+    const resultCheck = (0, telemetry_attestation_1.verifyTelemetryAttestation)(target.hop.usage, resultSignature, publicKeyPem, { ...resultCtx, resultDigest: (0, execution_backend_1.sha256)(findingEdited) });
+    layers.push({
+        layer: "result",
+        tamper: `edited the agent's signed finding "severity HIGH" -> "severity LOW" after it was signed`,
+        before: {
+            verified: resultClean.status === "attested" && resultClean.coversResult === true,
+            detail: `the signed finding verifies — ed25519 binds usage + sha256(result), result-covering`
+        },
+        after: { verified: resultCheck.status === "attested", detail: resultCheck.reason || resultCheck.status },
+        failures: resultCheck.status === "attested" ? [] : [`result: ${resultCheck.reason}`]
+    });
     if (!options.keepDir && !options.dir)
         node_fs_1.default.rmSync(runDir, { recursive: true, force: true });
     const proven = baseline.ledgerVerified &&

package/dist/telemetry-ledger.js

@@ -94,6 +94,9 @@ function recordHashInput(record) {
         reportedUsageDigest: record.reportedUsageDigest,
         ...(record.reportedUsage !== undefined ? { reportedUsage: record.reportedUsage } : {}),
         usageSignature: record.usageSignature || null,
+        // Chain-bind resultDigest only when present, so a usage-only record's hash is
+        // byte-identical to a pre-result-coverage one (back-compat with old ledgers).
+        ...(record.resultDigest !== undefined ? { resultDigest: record.resultDigest } : {}),
         attestation: record.attestation,
         attestationReason: record.attestationReason || null,
         prevHash: record.prevHash
@@ -131,6 +134,9 @@ function appendTelemetryAttestation(run, input) {
         // signature can be independently re-verified offline at `telemetry verify`.
         ...(input.reportedUsage ? { reportedUsage: input.reportedUsage } : {}),
         usageSignature: input.usageSignature,
+        // Present only for a result-bound signature, so usage-only records are
+        // byte-identical (and their recordHash unchanged) — back-compat.
+        ...(input.resultDigest ? { resultDigest: input.resultDigest } : {}),
         attestation: input.attestation,
         attestationReason: input.attestationReason,
         prevHash

package/dist/term.js

@@ -0,0 +1,93 @@
+"use strict";
+// src/term.ts — zero-dependency terminal styling.
+//
+// Provides TTY-gated ANSI formatting for human-readable output. When output is
+// piped (non-TTY), styled calls return plain text. This keeps data channels
+// (stdout) and diagnostics (stderr) clean — never adds escape codes to pipes.
+//
+// Used by: doctor, help, error messages, status summaries.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bold = bold;
+exports.dim = dim;
+exports.green = green;
+exports.yellow = yellow;
+exports.red = red;
+exports.cyan = cyan;
+exports.doctorGlyph = doctorGlyph;
+exports.cwLabel = cwLabel;
+exports.indent = indent;
+exports.printSuccessSummary = printSuccessSummary;
+function isTTY(stream = process.stderr) {
+    return Boolean(stream.isTTY);
+}
+// ---- ansi codes ----
+const ansi = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    cyan: "\x1b[36m",
+};
+// ---- styled text ----
+function style(code, text, stream) {
+    if (!isTTY(stream))
+        return text;
+    return `${code}${text}${ansi.reset}`;
+}
+function bold(text, stream) {
+    return style(ansi.bold, text, stream);
+}
+function dim(text, stream) {
+    return style(ansi.dim, text, stream);
+}
+function green(text, stream) {
+    return style(ansi.green, text, stream);
+}
+function yellow(text, stream) {
+    return style(ansi.yellow, text, stream);
+}
+function red(text, stream) {
+    return style(ansi.red, text, stream);
+}
+function cyan(text, stream) {
+    return style(ansi.cyan, text, stream);
+}
+// ---- semantic helpers ----
+/** Returns the styled glyph + label for a doctor check severity. */
+function doctorGlyph(status, stream) {
+    const glyph = { ok: "✓", warn: "!", fail: "✗" };
+    const color = {
+        ok: green,
+        warn: yellow,
+        fail: red,
+    };
+    return color[status](`${glyph[status]}`, stream);
+}
+/** "cw:" prefix with bold and optional color. */
+function cwLabel(stream) {
+    return bold("cw:", stream);
+}
+/** Render a multi-line block with consistent 2-space indentation. */
+function indent(text, spaces = 2) {
+    const prefix = " ".repeat(spaces);
+    return text.split("\n").map((line) => `${prefix}${line}`).join("\n");
+}
+/** Print a success summary to stderr (TTY-gated). Shows the report path and a
+ *  suggested next command. Pipe-friendly: silent when stderr is not a TTY. */
+function printSuccessSummary(fields, stream) {
+    if (!isTTY(stream))
+        return;
+    const s = stream || process.stderr;
+    s.write(`\n${green("✓")} Report: ${fields.reportPath}\n`);
+    if (fields.status === "complete") {
+        s.write(`  Next: cw status ${fields.runId} --brief\n`);
+        if (fields.bundle !== false) {
+            s.write(`  Bundle: cw report bundle ${fields.runId}\n`);
+        }
+    }
+    else {
+        s.write(`  ${yellow("!")} Status: ${fields.status}. Next: cw status ${fields.runId}\n`);
+    }
+}

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.86";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.88";
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
 exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
 exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;

package/dist/worker-accept/telemetry-ledger.js

@@ -24,7 +24,12 @@ function attestWorkerDelegation(accept, deps) {
     // usage. Absent/invalid signature => `unattested`/`absent`, surfaced loudly,
     // NEVER silently recorded as trusted.
     const telemetry = options.agentDelegation
-        ? (0, telemetry_attestation_1.verifyTelemetryAttestation)(options.agentDelegation.reportedUsage, options.agentDelegation.usageSignature, (0, telemetry_attestation_1.resolveTrustPublicKey)(options.agentDelegation.usageTrustPublicKey), { runId: run.id, taskId: task.id, promptDigest: options.agentDelegation.promptDigest })
+        ? (0, telemetry_attestation_1.verifyTelemetryAttestation)(options.agentDelegation.reportedUsage, options.agentDelegation.usageSignature, (0, telemetry_attestation_1.resolveTrustPublicKey)(options.agentDelegation.usageTrustPublicKey), 
+        // resultDigest binds the agent's findings into the signature: CW recomputes
+        // the digest from the accepted result (the SAME raw bytes the executor
+        // signed) so a result edited after signing fails verification. A signer
+        // that did not cover the result still verifies (verifier back-compat).
+        { runId: run.id, taskId: task.id, promptDigest: options.agentDelegation.promptDigest, resultDigest: (0, execution_backend_1.sha256)(rawResult) })
         : undefined;
     // Track 1 fail-closed (Decision 2 — OPT-IN, off by default). When the operator
     // requires attested telemetry, a delegated hop whose verdict is not `attested`
@@ -59,7 +64,7 @@ function attestWorkerDelegation(accept, deps) {
  *  event can cross-link the record hash), then emits the worker.agent-delegation
  *  audit event. No-op for non-agent hops. */
 function recordWorkerDelegationLedger(accept, delegation) {
-    const { agentDelegation } = delegation;
+    const { agentDelegation, telemetry } = delegation;
     // The agent-hop attestation event — hung off worker.output, alongside
     // worker.backend. Recorded in trust-audit/provenance, NEVER in node evidence.
     if (!agentDelegation)
@@ -76,6 +81,11 @@ function recordWorkerDelegationLedger(accept, delegation) {
             promptDigest: agentDelegation.promptDigest,
             reportedUsage: agentDelegation.reportedUsage,
             usageSignature: agentDelegation.usageSignature,
+            // Store the signed result digest ONLY when the signature actually covered
+            // it, so the offline re-verifier (telemetry verify --pubkey / report verify)
+            // can reconstruct the 5-field payload. A usage-only signature stores none
+            // (its record stays byte-identical to a pre-result-coverage one).
+            resultDigest: telemetry?.coversResult ? agentDelegation.resultDigest : undefined,
             attestation: agentDelegation.usageAttestation,
             attestationReason: agentDelegation.usageAttestationReason
         })

package/dist/workflow-api.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.workflow = workflow;
 exports.phase = phase;
 exports.parallel = parallel;
+exports.loop = loop;
 exports.createWorkflowApi = createWorkflowApi;
 exports.agent = agent;
+exports.subWorkflow = subWorkflow;
 exports.artifact = artifact;
 exports.input = input;
 exports.slugify = slugify;
@@ -46,19 +48,50 @@ function phase(name, tasks, options = {}) {
 function parallel(name, tasks, options = {}) {
     return phase(name, tasks, { mode: "parallel", ...options });
 }
+/** A BOUNDED DYNAMIC LOOP phase: `tasks` are a per-round template. After each round
+ *  completes, the registered `until` predicate decides whether to run another round
+ *  (a fresh appended phase with the same tasks, round-suffixed ids) or stop; capped
+ *  at `maxRounds`. Sugar over phase() that sets `loop`; plain phases are unaffected. */
+function loop(name, tasks, spec, options = {}) {
+    if (!spec || typeof spec.maxRounds !== "number" || spec.maxRounds < 1) {
+        throw new Error(`loop ${name} requires a positive integer maxRounds`);
+    }
+    const until = spec.until;
+    const valid = until
+        && ((until.kind === "predicate" && Boolean(until.ref))
+            || (until.kind === "budget-target" && typeof until.target === "number" && until.target > 0));
+    if (!valid) {
+        throw new Error(`loop ${name} requires until: { kind: "predicate", ref } or { kind: "budget-target", target }`);
+    }
+    return phase(name, tasks, { loop: { maxRounds: Math.floor(spec.maxRounds), until }, ...options });
+}
 function createWorkflowApi() {
     return {
         workflow,
         phase,
         parallel,
+        loop,
         agent,
         artifact,
+        subWorkflow,
         input
     };
 }
 function agent(id, prompt, options = {}) {
     return task("agent", id, prompt, options);
 }
+/** A task fulfilled by an inline SUB-WORKFLOW: instead of spawning an agent, the
+ *  drive plans + drives the child `appId` and binds its report back as this task's
+ *  result. The prompt is recorded for provenance but is not sent to an agent. */
+function subWorkflow(id, appId, options = {}) {
+    if (!appId)
+        throw new Error(`subWorkflow task ${id} requires an appId`);
+    const { inputs, bindResult, prompt, ...rest } = options;
+    return task("agent", id, prompt || `Delegate to sub-workflow app: ${appId}`, {
+        ...rest,
+        subWorkflow: { appId, ...(inputs ? { inputs } : {}), ...(bindResult ? { bindResult } : {}) }
+    });
+}
 function artifact(id, prompt, options = {}) {
     return task("artifact", id, prompt, options);
 }

package/dist/workflow-app-framework.js

@@ -522,6 +522,26 @@ function validatePhase(phaseDefinition, issues, pathName, seenPhaseIds) {
     if (!Array.isArray(phaseValue.tasks) || !phaseValue.tasks.length) {
         issues.push(issue("workflow-phase-tasks", `Workflow phase ${String(phaseValue.id || phaseValue.name || "")} must have tasks`, joinPath(pathName, "tasks")));
     }
+    // Bounded dynamic loop spec (fail-closed shape check; the predicate ref need not be
+    // registered at validation time — the expander stops fail-closed if it is missing).
+    if (phaseValue.loop !== undefined) {
+        const loop = phaseValue.loop;
+        if (!isRecord(loop)) {
+            issues.push(issue("workflow-phase-loop", "Workflow phase loop must be an object", joinPath(pathName, "loop")));
+        }
+        else {
+            if (typeof loop.maxRounds !== "number" || !Number.isInteger(loop.maxRounds) || loop.maxRounds < 1) {
+                issues.push(issue("workflow-phase-loop-maxrounds", "loop.maxRounds must be a positive integer", joinPath(pathName, "loop.maxRounds")));
+            }
+            const until = loop.until;
+            const validUntil = isRecord(until)
+                && ((until.kind === "predicate" && isNonEmptyString(until.ref))
+                    || (until.kind === "budget-target" && typeof until.target === "number" && until.target > 0));
+            if (!validUntil) {
+                issues.push(issue("workflow-phase-loop-until", 'loop.until must be { kind: "predicate", ref } or { kind: "budget-target", target }', joinPath(pathName, "loop.until")));
+            }
+        }
+    }
 }
 function validateTask(taskDefinition, issues, pathName, seenTaskIds, options) {
     if (!isRecord(taskDefinition)) {

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

@@ -204,13 +204,15 @@ A drive can show the agent's activity live, without touching the evidence
 contract, when the operator opts in with `CW_AGENT_STREAM=1`:
 
 - **Default stays buffered.** Without `CW_AGENT_STREAM=1`, the bundled wrapper
-  keeps the legacy `--output-format json` path and forwards claude's JSON stdout
-  word for word after writing `result.md`.
+  keeps the buffered path and writes one JSON report to stdout after writing
+  `result.md`.
 - **The opt-in wrapper renders; stderr only.** With `CW_AGENT_STREAM=1`, the
-  bundled wrapper runs claude in `--output-format stream-json` and renders a short
-  human trace (tool uses, assistant text, per-turn summaries) to its
-  **stderr** — diagnostics, never data. It builds the single
-  `{model, usage, result}` object for stdout again only on that opt-in path.
+  bundled Claude wrapper runs claude in `--output-format stream-json`, and the
+  bundled Codex wrapper runs `codex exec --json --output-last-message`.
+  Each wrapper renders a short human trace (tool uses, assistant text, per-turn
+  summaries where present) to its **stderr** — diagnostics, never data. It builds
+  the single `{model, usage, result}` object for stdout after the final answer is
+  captured.
 - **Core forwards, never parses.** `runAgentProcess` passes the agent child's
   stderr straight through to the operator's terminal (`stdio` inherit) only when
   `CW_AGENT_STREAM=1`, CW's own stderr is a TTY, and `CW_NO_STREAM` is not set.
@@ -219,6 +221,18 @@ contract, when the operator opts in with `CW_AGENT_STREAM=1`:
 - **Determinism intact.** The backend evidence triple hashes stdout only, so
   the live stderr stream never changes recorded evidence or replay.
 
+The built-in templates are:
+
+```text
+--agent-command builtin:claude
+--agent-command builtin:codex
+```
+
+Gemini, OpenCode, DeepSeek, and GLM stay as external agent commands or HTTP
+endpoints until their stream format is proven by a local, deterministic wrapper
+smoke. DeepSeek and GLM are best reached through OpenCode or an HTTP agent
+adapter first; CW still imports no model SDK.
+
 ## Compatibility
 
 Agent Delegation Drive comes in first in CW v0.1.38. Adding the `agent` row leaves
@@ -291,3 +305,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)
+
+Orchestration-parity for the agent drive: `run --drive --incremental` step-level resume (unchanged-input tasks replay from a content-addressed cache, zero re-spawns), inline `subWorkflow()` nesting (a task runs a child app and binds its verified report back, bounded depth + cycle guard, no telemetry fabricated), bounded dynamic `loop()` phases that expand at runtime under a static replay-stable cap, and a `claude -p` wrapper now on the canonical result contract.

package/docs/capability-topology-registry.7.md

@@ -2,69 +2,92 @@
 
 ## Name
 
-`capability-dispatcher`, `registerCapabilityHandler`, `registerTopology` — open registries for agent-driven CW extension
+`capability-registry`, `registerTopology` — the declared capability contract and the open topology registry for agent-driven CW extension
 
 ## Description
 
-v0.1.53 adds two open registries. They let agents grow CW at runtime
-with no need to wire things by hand in many files. New capabilities put
-themselves in the registry and then work by themselves across CLI, MCP, and Workbench. New topologies put
-themselves in the registry too and then come up by themselves in `topology list`, `topology validate`, and `topology apply`.
-
-BSD way: keep **mechanism** (Map / pipe) apart from **policy** (entries).
-Fail-closed on unknown ids.
+CW keeps two layers here. The **capability registry**
+(`src/capability-registry.ts`) is the one declared source of truth for every
+capability CW exposes; it is read at build/check time, not written to at
+runtime. The **topology registry** (`src/topology.ts`) is an open runtime
+registry: new topologies put themselves in it with `registerTopology()` and
+then come up by themselves in `topology list`, `topology validate`, and
+`topology apply`.
+
+> History: v0.1.53 also shipped a dynamic *capability* dispatcher
+> (`capability-dispatcher.ts`, `registerCapabilityHandler`,
+> `dispatchCapability`, `resolveCliPath`, `resolveMcpTool`) meant to let
+> capabilities register handlers and be routed at runtime. It had zero call
+> sites — the handler map was always empty and every dispatch path was
+> unreachable — so it was removed as dead code in v0.1.81 (#131). Capabilities
+> are **declared**, not runtime-registered; see below. (The unrelated
+> `cw dispatch` command, which writes a subagent dispatch manifest, is a normal
+> declared capability, not that dispatcher.)
+
+BSD way: keep **mechanism** (the registry / the open Map) apart from **policy**
+(the entries). Fail-closed on unknown ids.
 
 ## Capability Registry
 
-### Interface
+The capability registry, `src/capability-registry.ts`, is the SINGLE declared
+source of truth for every capability CW exposes — and the contract both front
+doors (CLI and MCP) are checked against. It is a static, read-only array of
+descriptors, `CAPABILITY_REGISTRY`. There is no runtime "register a handler"
+seam and no dynamic dispatcher: capabilities are data here, not code that wires
+itself in.
 
-```typescript
-interface CapabilityHandler {
-  descriptor: CapabilityDescriptor;
-  run(args: Record<string, unknown>, ctx: CapabilityContext): unknown | Promise<unknown>;
-}
+### Descriptor
 
-interface CapabilityContext {
-  runner: CoolWorkflowRunner;
-  cwd: string;
+```typescript
+interface CapabilityDescriptor {
+  capability: string;   // canonical dot-namespaced id, e.g. "worker.list"
+  summary: string;      // one-line description
+  entry: string;        // the ONE shared core entry both surfaces route through
+  surface: "both" | "cli-only" | "mcp-only";
+  cli?: { path: string[]; jsonMode: "default" | "flag" | "human" };
+  mcp?: { tool: string; requiredArgs?: string[] };
+  payloadIdentical?: boolean;  // CLI --json === MCP result (default true for "both")
+  reason?: string;             // required when surface !== "both" or payloadIdentical === false
 }
 ```
 
-### Registering a new capability
+### Adding a capability
+
+A capability is declared once, as data, in `CAPABILITY_REGISTRY`, against one
+shared core `entry`:
 
 ```typescript
-import { registerCapabilityHandler } from "./capability-registry";
-
-registerCapabilityHandler({
-  descriptor: {
-    capability: "my.new.tool",          // canonical dot-namespaced id
-    summary: "Does something useful.",   // one-line description
-    entry: "myNewTool",                  // core entry name
-    surface: "both",                     // "both" | "cli-only" | "mcp-only"
-    cli: { path: ["my", "new-tool"], jsonMode: "default" },
-    mcp: { tool: "cw_my_new_tool" }
-  },
-  run: async (args, ctx) => {
-    // ctx.runner exposes all orchestrator methods
-    return ctx.runner.listWorkflows();
-  }
-});
+{
+  capability: "my.new.tool",
+  summary: "Does something useful.",
+  entry: "myNewTool",
+  surface: "both",
+  cli: { path: ["my", "new-tool"], jsonMode: "default" },
+  mcp: { tool: "cw_my_new_tool" }
+}
 ```
 
+`cli.ts` and `mcp-server.ts` each route their surface to the shared `entry` with
+their own explicit `switch` routing (plus a few `if (action === …)` branches).
+The registry is what those switches are validated against, not something they
+call into — there is no fallback dynamic dispatch.
+
 ### How it works
 
-1. `registerCapabilityHandler()` keeps the handler in a `Map<string, CapabilityHandler>`
-2. CLI: `resolveCliPath(["my", "new-tool"])` turns the CLI path into the capability id
-3. MCP: `resolveMcpTool("cw_my_new_tool")` turns the tool name into the capability id
-4. `dispatchCapability(id, args, ctx)` calls `handler.run(args, ctx)`
-5. Both the CLI and MCP surfaces drop through to the dynamic dispatcher when
-   their hardcoded switch statements do not match an unknown command/tool
+1. `CAPABILITY_REGISTRY` declares every capability once — one row per capability.
+2. CLI: `cli.ts` matches the command in its explicit `switch` and calls the core `entry`.
+3. MCP: `mcp-server.ts` matches the tool name in its explicit `switch` and calls the same `entry`.
+4. The parity gate (`scripts/parity-check.js --check`) fails closed on any drift:
+   a CLI command or MCP tool live on one surface but absent on the other or
+   undeclared, an undeclared payload divergence, or a surface-specific capability
+   with no recorded `reason`.
 
-### Existing capabilities
+### How many capabilities
 
-All 182 capabilities that are there now keep working through their hardcoded switch
-cases in `cli.ts` and `mcp-server.ts`. The dynamic dispatch is a **fallback**
-— it turns on only for commands/tools not found in the old switches.
+Run `node plugins/cool-workflow/scripts/parity-check.js --check` and read
+`registrySize` for the live count (199 at the time of writing). The full
+CLI <-> MCP matrix lives in `docs/cli-mcp-parity.7.md`, which is generated from
+the same registry.
 
 ## Topology Registry
 
@@ -160,8 +183,8 @@ expansion. Now it reads `role.count` on each role spec:
 
 ## See Also
 
-- `capability-registry.ts` — the one true source for all capabilities
-- `capability-dispatcher.ts` — the thin Map-based dispatch pipe
+- `capability-registry.ts` — the one declared source for all capabilities
+- `capability-core.ts` — the shared core entries both surfaces route through
 - `topology.ts` — topology definitions and the registry
 - `types/topology.ts` — topology type definitions
 - `docs/cli-mcp-parity.7.md` — CLI <-> MCP parity gate

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

@@ -82,14 +82,20 @@ relationship. `identical` means `cw <cmd> --json` is equal to the `cw_<tool>`
 payload; `projected` means a declared divergence with a reason; `cli-only` marks
 a surface-specific capability with a recorded reason. The matrix is
 <!-- gen:parity:count -->
-machine-complete by design: 193 capabilities, 186 MCP tools.
+machine-complete by design: 199 capabilities, 186 MCP tools.
 <!-- /gen:parity:count -->
 
 <!-- gen:parity:table -->
 | Capability | CLI command | MCP tool | Core entry | Surface | Payload |
 | --- | --- | --- | --- | --- | --- |
 | `help` | `cw help` | `—` | `formatHelp` | cli-only | cli-only |
+| `version` | `cw version` | `—` | `CURRENT_COOL_WORKFLOW_VERSION` | cli-only | cli-only |
+| `update` | `cw update` | `—` | `npmUpdate` | cli-only | cli-only |
+| `fix` | `cw fix` | `—` | `runDoctor` | cli-only | cli-only |
 | `list` | `cw list` | `cw_list` | `listWorkflows` | both | identical |
+| `info` | `cw info` | `—` | `showApp` | cli-only | cli-only |
+| `search` | `cw search` | `—` | `listApps` | cli-only | cli-only |
+| `man` | `cw man` | `—` | `n/a` | cli-only | cli-only |
 | `doctor` | `cw doctor` | `—` | `runDoctor` | cli-only | cli-only |
 | `init` | `cw init` | `cw_init` | `init` | both | identical |
 | `plan` | `cw plan` | `cw_plan` | `planSummary` | both | identical |
@@ -295,9 +301,15 @@ A capability may be on one surface only, but never without word of it — it mus
 carry a recorded reason in the registry.
 
 <!-- gen:parity:cliOnly -->
-Seven capabilities are CLI-only:
+13 capabilities are CLI-only:
 
 - `help` — Human help text. MCP hosts enumerate capabilities via tools/list, not a help command.
+- `version` — Version string — no structured data contract.
+- `update` — Self-update via npm — inherently local shell operation, no MCP surface.
+- `fix` — Environment fix commands are local diagnostics, same reasoning as doctor.
+- `info` — Human-focused workflow discovery tool (like Homebrew's `brew info`). MCP agents discover workflows via cw_list and cw_app_show tools.
+- `search` — Human-focused workflow discovery (like Homebrew's `brew search`). MCP agents discover workflows via cw_list tool.
+- `man` — Human documentation viewer. MCP agents read docs/ directly via file tools.
 - `doctor` — Environment diagnostics are inherently local to the CLI host — Node version, $PATH, $CW_HOME/cwd writability. An MCP client diagnosing the server process's environment is not meaningful; agents already receive the same readiness facts in their typed results (e.g. status: blocked, agentConfigured). Inspired by `brew doctor`.
 - `loop` — Convenience alias of `schedule create` with kind=loop. MCP hosts use cw_schedule_create with kind=loop.
 - `schedule daemon` — Long-running desktop daemon process, not a request/response tool. MCP hosts drive ticks via cw_schedule_due + cw_schedule_run_now.
@@ -497,3 +509,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)
+
+CLI surface simplified to 6 commands with agent stderr streaming on by default and vendor agent flags; the drive gains a `--incremental` flag (added to DRIVE_RUNTIME_KEYS so it never poisons run.inputs or the cache key). MCP tools stay the derived mirror of the same capabilities.

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

@@ -145,3 +145,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 schema-migration edge was added; the incremental result cache uses a self-contained schemaVersion:2 key that never collides with the opt-in v1 cache and is not a run-state or app-schema migration)._