cool-workflow 0.2.4 → 0.2.5

package/dist/wiring/capability-table/exec-backend.js

@@ -16,23 +16,26 @@ const registry_core_1 = require("./registry-core");
 // their milestone-2 placeholder `mcp.handler` with the real body, exactly
 // as milestones 3/4 did for their own rows.
 // ---------------------------------------------------------------------
-const exec_backend_cli_1 = require("../../shell/exec-backend-cli");
 const cli_args_1 = require("../../core/util/cli-args");
-// This slice is required unconditionally at startup for every command;
-// load doctor/app-run-cli lazily so only doctor/fix/sandbox.choose/
-// sandbox.resolve/app.run handlers pay their require cost.
+// This slice is required unconditionally at startup for every command; every
+// shell import below is lazy (require()'d only inside the handler that
+// actually uses it), so a command that never touches doctor/fix/sandbox/
+// backend/app.run never pays any of these shell modules' require cost.
 function loadDoctor() {
     return require("../../shell/doctor");
 }
 function loadAppRunCli() {
     return require("../../shell/app-run-cli");
 }
+function loadExecBackendCli() {
+    return require("../../shell/exec-backend-cli");
+}
 (0, registry_core_1.attachCliBinding)("sandbox.list", {
     path: ["sandbox", "list"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, exec_backend_cli_1.listSandboxProfilesCli)(args.options) }),
+    handler: (args) => ({ json: loadExecBackendCli().listSandboxProfilesCli(args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.list").mcp.handler = (args) => (0, exec_backend_cli_1.listSandboxProfilesCli)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.list").mcp.handler = (args) => loadExecBackendCli().listSandboxProfilesCli(args);
 // GAP #24: cw_sandbox_choose / cw_sandbox_resolve + cw_app_run were declared
 // MCP-only rows with the notYetImplemented placeholder handler. Wire them to
 // the ported shell bodies (both are MCP-only in the old build — no CLI path).
@@ -42,18 +45,18 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("app.run").mcp.handler = (args) => lo
 (0, registry_core_1.attachCliBinding)("sandbox.show", {
     path: ["sandbox", "show"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, exec_backend_cli_1.showSandboxProfileCli)((0, cli_args_1.required)(args.positionals[0], "profile id"), args.options) }),
+    handler: (args) => ({ json: loadExecBackendCli().showSandboxProfileCli((0, cli_args_1.required)(args.positionals[0], "profile id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.show").mcp.handler = (args) => (0, exec_backend_cli_1.showSandboxProfileCli)((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.profileId), "profile id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.show").mcp.handler = (args) => loadExecBackendCli().showSandboxProfileCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.profileId), "profile id"), args);
 (0, registry_core_1.attachCliBinding)("sandbox.validate", {
     path: ["sandbox", "validate"],
     jsonMode: "default",
     handler: (args) => {
-        const result = (0, exec_backend_cli_1.validateSandboxProfileCli)((0, cli_args_1.required)(args.positionals[0], "profile file"), args.options);
+        const result = loadExecBackendCli().validateSandboxProfileCli((0, cli_args_1.required)(args.positionals[0], "profile file"), args.options);
         return { json: result, exitCode: result.valid ? undefined : 1 };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.validate").mcp.handler = (args) => (0, exec_backend_cli_1.validateSandboxProfileCli)((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.profileFile), "profile file"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.validate").mcp.handler = (args) => loadExecBackendCli().validateSandboxProfileCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.profileFile), "profile file"), args);
 // PARITY: `sandbox.choose`/`sandbox.resolve` are BOTH-surface capabilities
 // per SPEC/mcp.md (old build cli.path ["sandbox","choose"]/["sandbox",
 // "resolve"]) — they were left MCP-only at GAP #24 (see the comment
@@ -74,21 +77,21 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.validate").mcp.handler = (ar
 (0, registry_core_1.attachCliBinding)("backend.list", {
     path: ["backend", "list"],
     jsonMode: "default",
-    handler: () => ({ json: (0, exec_backend_cli_1.listBackendsCli)() }),
+    handler: () => ({ json: loadExecBackendCli().listBackendsCli() }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.list").mcp.handler = () => (0, exec_backend_cli_1.listBackendsCli)();
+registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.list").mcp.handler = () => loadExecBackendCli().listBackendsCli();
 (0, registry_core_1.attachCliBinding)("backend.show", {
     path: ["backend", "show"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, exec_backend_cli_1.showBackendCli)((0, cli_args_1.required)(args.positionals[0], "backend id")) }),
+    handler: (args) => ({ json: loadExecBackendCli().showBackendCli((0, cli_args_1.required)(args.positionals[0], "backend id")) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.show").mcp.handler = (args) => (0, exec_backend_cli_1.showBackendCli)((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.backendId), "backend id"));
+registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.show").mcp.handler = (args) => loadExecBackendCli().showBackendCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.backendId), "backend id"));
 (0, registry_core_1.attachCliBinding)("backend.probe", {
     path: ["backend", "probe"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, exec_backend_cli_1.probeBackendCli)(args.positionals[0], args.options) }),
+    handler: (args) => ({ json: loadExecBackendCli().probeBackendCli(args.positionals[0], args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.probe").mcp.handler = (args) => (0, exec_backend_cli_1.probeBackendCli)((0, cli_args_1.optionalArg)(args.backendId), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.probe").mcp.handler = (args) => loadExecBackendCli().probeBackendCli((0, cli_args_1.optionalArg)(args.backendId), args);
 // `backend agent config [show]` = read-only; `backend agent config set
 // ...` = mutating. CLI path is ["backend", "agent"] (2 tokens, matching
 // dispatchTable's supported path lengths); the remaining positionals
@@ -102,8 +105,8 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.probe").mcp.handler = (args)
     handler: (args) => {
         const action = args.positionals[1];
         if (action === "set")
-            return { json: (0, exec_backend_cli_1.backendAgentConfigSet)(args.options) };
-        return { json: (0, exec_backend_cli_1.backendAgentConfigShow)(args.options) };
+            return { json: loadExecBackendCli().backendAgentConfigSet(args.options) };
+        return { json: loadExecBackendCli().backendAgentConfigShow(args.options) };
     },
 });
 // `backend.agent.config.set` shares the SAME dispatch path/handler as
@@ -124,12 +127,12 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.probe").mcp.handler = (args)
     handler: (args) => {
         const action = args.positionals[1];
         if (action === "set")
-            return { json: (0, exec_backend_cli_1.backendAgentConfigSet)(args.options) };
-        return { json: (0, exec_backend_cli_1.backendAgentConfigShow)(args.options) };
+            return { json: loadExecBackendCli().backendAgentConfigSet(args.options) };
+        return { json: loadExecBackendCli().backendAgentConfigShow(args.options) };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.show").mcp.handler = (args) => (0, exec_backend_cli_1.backendAgentConfigShow)(args);
-registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.set").mcp.handler = (args) => (0, exec_backend_cli_1.backendAgentConfigSet)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.show").mcp.handler = (args) => loadExecBackendCli().backendAgentConfigShow(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.set").mcp.handler = (args) => loadExecBackendCli().backendAgentConfigSet(args);
 // PARITY: `backend.agent.config.set` mutates $CW_HOME/agent-config.json
 // (secret-stripped) before returning the effective config; both surfaces
 // perform the same write, so it is a documented opt-out from the
@@ -154,6 +157,21 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.set").reason =
         const text = (0, cli_args_1.wantsJson)(args.options) ? undefined : args.options.fix ? `${doctor.formatDoctorFixes(report)}\n` : doctor.formatDoctorReport(report);
         return { json: report, text, exitCode: report.ok ? undefined : 1 };
     },
+    // UI/UX fix: `cw help doctor` used to list only the one-line summary
+    // above, so a first-run user had no way to learn these flags without
+    // reading source. Real flag names verified against this handler and
+    // the `runDoctor(args.options, ...)` call it makes (shell/doctor.ts).
+    flags: [
+        { name: "--onramp", summary: "Run the extra onramp checks (3-step quick start)." },
+        { name: "--fix", summary: "Print fix commands instead of the full report." },
+        { name: "--changed-from REF", summary: "Check the onramp only for the change since REF." },
+        { name: "--json", summary: "Print the report as JSON." },
+    ],
+    // The handler above and runDoctor (shell/doctor.ts) read exactly
+    // onramp/fix/changed-from/json plus the shared globals (cwd, format)
+    // — the list above is complete, so the dispatcher may warn about an
+    // unknown flag (TTY-only; see cli/global-flags.ts).
+    flagsComplete: true,
 }, "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`.");
 (0, registry_core_1.addCliOnlyCapability)("fix", "Print consolidated fix commands for CW setup issues.", {
     path: ["fix"],

package/dist/wiring/capability-table/pipeline.js

@@ -45,6 +45,13 @@ function loadCommitSummary() {
 // only so `cw help run` lists both capabilities.
 (0, registry_core_1.attachCliBinding)("run.drive.step", {
     path: ["run"],
+    // NOTE: the doubled "cw run drive" command column (this row + run.drive's
+    // preview row below) is pinned by SPEC/cli-probe.md "Odd things" item 5
+    // ("run drive (preview + drive)" — "A rebuild's help printer must keep
+    // these doubled rows"), same as `cw sched policy`. So the UI/UX fix for
+    // the two look-alike rows lives in the SUMMARIES (each now names its own
+    // invocation spelling — see the summary edits where these capabilities
+    // are declared), never in the row count or the command column.
     helpPath: ["run", "drive"],
     jsonMode: "default",
     handler: async (args) => {
@@ -124,6 +131,19 @@ function loadCommitSummary() {
 });
 registry_core_1.REGISTRY_BY_CAPABILITY.get("run.drive").mcp.handler = (args) => loadPipelineCli().runDrivePreview(args);
 registry_core_1.REGISTRY_BY_CAPABILITY.get("run.drive.step").mcp.handler = (args) => loadPipelineCli().runDriveStep(args);
+// UI/UX fix: `cw help run` prints TWO "cw run drive" rows — the doubling
+// itself is pinned by SPEC/cli-probe.md "Odd things" item 5 ("run drive
+// (preview + drive)": a rebuild's help printer must keep these doubled
+// rows), so the command column and the row count must not change. What CAN
+// change is the summary text: it used to leave a reader no way to tell
+// which spelling gets which behavior. Each summary now ends with the exact
+// command form that reaches it. Help-page-only: `summary` is overridden on
+// the Capability row, `mcp.description` (the tools/list byte surface) is
+// already captured by buildMcpBinding and stays untouched.
+registry_core_1.REGISTRY_BY_CAPABILITY.get("run.drive").summary =
+    "Preview the next agent-delegation drive step for a run (read-only, deterministic). Use: cw run drive <run-id>.";
+registry_core_1.REGISTRY_BY_CAPABILITY.get("run.drive.step").summary =
+    "Drive a run by delegating each worker to the agent backend (plan->dispatch->fulfill->accept->commit; --once for one step). Use: cw run <app> --drive.";
 // PARITY: `run.drive.step` advances the run by spawning the external
 // agent per worker and recording attested output — not a read probe.
 // CLI (--drive/--step) and MCP route through the same drive() core; the
@@ -246,6 +266,18 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("run.restore").mcp.handler = (args) =
         const exitCode = (result.mode === "check" && result.ok === false) || bundleFailed ? 1 : undefined;
         return { json: result, exitCode };
     },
+    // UI/UX fix: `cw help quickstart` used to list only the one-line
+    // summary above, so a first-run user had no way to learn these flags
+    // without reading source. Real flag names verified against
+    // shell/pipeline-cli.ts's quickstartRun.
+    flags: [
+        { name: "--check", summary: "Check setup only; do not plan, run, or write anything." },
+        { name: "--preview", summary: "Show the next step, but do not run it." },
+        { name: "--bundle", summary: "Seal a finished run into a portable, self-checked bundle." },
+        { name: "--with-trust-key KEY", summary: "Add a public key to the bundle for a strict check." },
+        { name: "--resume", summary: "Move a stopped run forward one step, or to the end with --run ID." },
+        { name: "--link URL", summary: "Review a remote repo by its URL." },
+    ],
 }, "quickstart composes plan/runDrive/report; SPEC/mcp.md's declared cli-only list names it explicitly (no MCP peer). `audit-run` is a CLI-only alias of the same wrapper.", "quickstart");
 (0, registry_core_1.attachCliBinding)("dispatch", {
     path: ["dispatch"],

package/dist/wiring/capability-table/registry-core.js

@@ -113,11 +113,13 @@ function buildMcpBinding(row) {
     // into its separate AND-groups here (the one place the row shape is turned
     // into the runtime McpBinding.requiredArgs contract).
     const requiredArgs = row.requiredArgs.flatMap((group) => group.split(",").map((entry) => entry.trim()).filter(Boolean));
+    const annotations = capability_data_1.MCP_TOOL_ANNOTATIONS[row.tool];
     return {
         tool: row.tool,
         requiredArgs: requiredArgs.length ? requiredArgs : undefined,
         properties: row.properties,
         description: row.description,
+        ...(annotations ? { annotations } : {}),
         handler,
     };
 }
@@ -179,7 +181,19 @@ function findCapabilityByCliPath(path) {
 function cliCapabilities() {
     return exports.REGISTRY.filter((row) => Boolean(row.cli));
 }
-/** `tools/list`'s exact array, in the pinned source order. */
+/** `tools/list`'s exact array, in the pinned source order. Each
+ *  property's shape comes from the first hit, in order: a per-tool
+ *  `PROPERTY_OVERRIDES` entry, then the shared `COMMON_PROPERTY_TYPES`
+ *  entry for that property name, then the plain `stringProperty`
+ *  fallback for any name neither table covers.
+ *
+ *  `inputSchema.required` is built from `row.mcp.requiredArgs`, which
+ *  mcp/dispatch.ts's `requiredToolArguments` also reads: each array
+ *  entry is one AND-required group, already split from the transcript's
+ *  comma form (see `buildMcpBinding` above). A group holding `|` is an
+ *  OR-group — at least one of the named keys must be present, so no
+ *  single name from it can go into the flat, AND-only `required` list;
+ *  a group with no `|` is one plain required name. */
 function mcpToolDefinitions() {
     const definitions = [];
     for (const row of exports.REGISTRY) {
@@ -188,12 +202,21 @@ function mcpToolDefinitions() {
         const overrides = capability_data_1.PROPERTY_OVERRIDES[row.mcp.tool] ?? {};
         const properties = {};
         for (const propName of row.mcp.properties) {
-            properties[propName] = overrides[propName] ?? (0, capability_data_1.stringProperty)(propName);
+            properties[propName] = overrides[propName] ?? capability_data_1.COMMON_PROPERTY_TYPES[propName] ?? (0, capability_data_1.stringProperty)(propName);
         }
+        const required = (row.mcp.requiredArgs ?? []).filter((group) => !group.includes("|"));
         definitions.push({
             name: row.mcp.tool,
             description: row.mcp.description,
-            inputSchema: { type: "object", properties, additionalProperties: true },
+            // Additive behavior hints (MCP_TOOL_ANNOTATIONS): present only for
+            // tools whose handler was checked by hand; omitted otherwise.
+            ...(row.mcp.annotations ? { annotations: row.mcp.annotations } : {}),
+            inputSchema: {
+                type: "object",
+                properties,
+                additionalProperties: true,
+                ...(required.length ? { required } : {}),
+            },
         });
     }
     return definitions;

package/dist/wiring/capability-table/reporting.js

@@ -325,7 +325,13 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("workbench.view").mcp.handler = (args
         // renderCliResult: it is synchronous, so a genuinely blocking serve
         // must perform its own stdout write and keep the event loop alive
         // rather than returning a CliHandlerResult at all.
-        void host.run();
+        // run() already fails closed internally (a `cw:` line + exit 1) for the
+        // known bind failures; this .catch is a backstop so any future throw
+        // path can never surface as an unhandled-rejection stack dump.
+        void host.run().catch((error) => {
+            process.stderr.write(`cw: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        });
         return { json: undefined };
     },
 });

package/dist/wiring/capability-table/scheduling-registry.js

@@ -76,8 +76,14 @@ function firstPositionalArg(args, index = 0) {
                     return { json: registryCli.scheduleDaemonTickCli(args.options) };
                 // Never returns (matches the old build's forever daemon loop);
                 // the process stays alive via the DesktopSchedulerDaemon's own
-                // setInterval, printing one tick line per interval.
-                void registryCli.scheduleDaemonRunForever(args.options);
+                // setInterval, printing one tick line per interval. The daemon's
+                // run() already guards each tick and fails closed with a `cw:`
+                // line; this .catch is a backstop against any unguarded throw so
+                // it can never surface as an unhandled-rejection stack dump.
+                void registryCli.scheduleDaemonRunForever(args.options).catch((error) => {
+                    process.stderr.write(`cw: ${error instanceof Error ? error.message : String(error)}\n`);
+                    process.exitCode = 1;
+                });
                 return {};
             }
             default:

package/dist/wiring/capability-table/trust-ledger.js

@@ -18,10 +18,13 @@ const cli_args_1 = require("../../core/util/cli-args");
 // cli/parseargv.ts) even though dispatchTable now handles it as a real
 // row — a known, preserved wart.
 // ---------------------------------------------------------------------
-const ledger_cli_1 = require("../../shell/ledger-cli");
 // This file is required at startup for every command. Loading these shell
 // modules only when their handler runs, not at import time, keeps that
-// load cost out of commands that never touch telemetry/audit/demo/report.
+// load cost out of commands that never touch ledger/telemetry/audit/demo/
+// report.
+function loadLedgerCli() {
+    return require("../../shell/ledger-cli");
+}
 function loadTelemetryCli() {
     return require("../../shell/telemetry-cli");
 }
@@ -40,42 +43,81 @@ function loadReportCli() {
 (0, registry_core_1.attachCliBinding)("ledger.propose", {
     path: ["ledger", "propose"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, ledger_cli_1.ledgerProposeCli)(args.options) }),
+    handler: (args) => ({ json: loadLedgerCli().ledgerProposeCli(args.options) }),
+    // UI/UX fix: `cw help ledger` used to list only the one-line summary for
+    // each row, so a first-run user had no way to learn these flags without
+    // reading source. Real flag names verified against ledgerProposeCli's
+    // required()/stringOption() calls above.
+    flags: [
+        { name: "--from AGENT/REPO", summary: "Who is making the change." },
+        { name: "--to AGENT/REPO", summary: "Who should get the change." },
+        { name: "--title TEXT", summary: "A short name for the change." },
+        { name: "--rationale TEXT", summary: "Why the change should happen." },
+        { name: "--files LIST", summary: "The files the change touches, as a comma list." },
+        { name: "--diff PATCH", summary: "The change as one diff file." },
+    ],
+    // ledgerProposeCli reads exactly from/to/title/rationale/files/diff
+    // (shell/ledger-cli.ts) — the list above is complete, so the dispatcher
+    // may warn about an unknown flag (TTY-only; see cli/global-flags.ts).
+    flagsComplete: true,
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.propose").mcp.handler = (args) => (0, ledger_cli_1.ledgerProposeMcp)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.propose").mcp.handler = (args) => loadLedgerCli().ledgerProposeMcp(args);
 (0, registry_core_1.attachCliBinding)("ledger.review", {
     path: ["ledger", "review"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, ledger_cli_1.ledgerReviewCli)(args.options) }),
+    handler: (args) => ({ json: loadLedgerCli().ledgerReviewCli(args.options) }),
+    // Real flag names verified against ledgerReviewCli's required()/
+    // stringOption() calls above — NOT the same flag set as ledger propose
+    // (this row needs --target/--verdict/--findings, not --title/
+    // --rationale/--diff).
+    flags: [
+        { name: "--from AGENT/REPO", summary: "Who is doing the review." },
+        { name: "--to AGENT/REPO", summary: "Who made the change being reviewed." },
+        { name: "--target ID", summary: "The id of the proposal or PR to review." },
+        { name: "--verdict approved|rejected", summary: "The result of the review." },
+        { name: "--findings TEXT", summary: "Notes on what the review found." },
+    ],
+    // ledgerReviewCli reads exactly from/to/target/verdict/findings
+    // (shell/ledger-cli.ts) — the list above is complete, so the dispatcher
+    // may warn about an unknown flag (TTY-only; see cli/global-flags.ts).
+    flagsComplete: true,
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.review").mcp.handler = (args) => (0, ledger_cli_1.ledgerReviewMcp)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.review").mcp.handler = (args) => loadLedgerCli().ledgerReviewMcp(args);
 (0, registry_core_1.attachCliBinding)("ledger.verify", {
     path: ["ledger", "verify"],
     jsonMode: "default",
     handler: (args) => {
-        const result = (0, ledger_cli_1.ledgerVerifyCli)(args.options);
+        const result = loadLedgerCli().ledgerVerifyCli(args.options);
         return { json: result, exitCode: result.ok ? undefined : 1 };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.verify").mcp.handler = (args) => (0, ledger_cli_1.ledgerVerifyEntry)(args.entry);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.verify").mcp.handler = (args) => loadLedgerCli().ledgerVerifyEntry(args.entry);
 (0, registry_core_1.attachCliBinding)("ledger.apply", {
     path: ["ledger", "apply"],
     jsonMode: "default",
     handler: (args) => {
-        const result = (0, ledger_cli_1.ledgerApplyCli)(args.options);
+        const result = loadLedgerCli().ledgerApplyCli(args.options);
         return { json: result, exitCode: result.ok ? undefined : 1 };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.apply").mcp.handler = (args) => (0, ledger_cli_1.ledgerApplyEntry)(args.entry);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.apply").mcp.handler = (args) => loadLedgerCli().ledgerApplyEntry(args.entry);
 (0, registry_core_1.attachCliBinding)("ledger.list", {
     path: ["ledger", "list"],
     jsonMode: "default",
     handler: (args) => {
-        const result = (0, ledger_cli_1.ledgerListCli)(args.options);
+        const result = loadLedgerCli().ledgerListCli(args.options);
         return { json: result, exitCode: result.allOk ? undefined : 1 };
     },
+    // UI/UX fix: `--dir` here named the ledger directory, while the global
+    // front door (cli/entry.ts) treats `--dir` as an alias of `--repo` for
+    // every command — one flag, two meanings. `--ledger-dir` is the
+    // unambiguous spelling; `--dir` stays as the legacy alias, byte-compat.
+    flags: [
+        { name: "--ledger-dir DIR", summary: "The ledger directory to read. Give it more than once to union-verify mirrors." },
+        { name: "--dir DIR", summary: "Old name for --ledger-dir (also the global --repo alias; kept working)." },
+    ],
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.list").mcp.handler = (args) => (0, ledger_cli_1.ledgerListMcp)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.list").mcp.handler = (args) => loadLedgerCli().ledgerListMcp(args);
 (0, registry_core_1.attachCliBinding)("telemetry.verify", {
     path: ["telemetry", "verify"],
     jsonMode: "flag",

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

@@ -125,6 +125,19 @@ exactly one fixed step (injected `now`); bare `--drive` runs to the end or to a
 parked/blocked stop. `run drive <run-id>` (no `--step`) is the read-only, fixed
 preview of the next step.
 
+## Concurrent rounds (`--concurrency N`)
+
+`--drive --concurrency N` (or an auto-width parallel phase) runs a whole round's
+tasks in ONE window instead of one at a time. CW dispatches the round's tasks,
+collects every agent outcome concurrently, then settles + accepts them in
+DETERMINISTIC batch (task-id) order — so the wall-clock drops but the recorded
+state, reports, and exit codes are byte-identical to a serial run. Both agent
+shapes get real concurrency: a **CLI-binary** agent (`CW_AGENT_COMMAND`) runs
+all children at once through the batch delegate child, and an **HTTP-endpoint**
+agent (`CW_AGENT_ENDPOINT`) POSTs all N delegations at once through the HTTP
+batch delegate child. A cache-hit task still settles on the serial path inside
+the same round. An unconfigured agent still refuses (it is never a fake pass).
+
 ## Fail closed — probe vs refusal vs park
 
 - **Probe.** `backend probe agent` reports `readiness: "ready"` iff a
@@ -423,3 +436,5 @@ The one-command `cw -q` headline now routes the question and defaults the repo t
 0.2.3
 
 0.2.4
+
+0.2.5

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

@@ -74,6 +74,29 @@ show/validate/apply/summary/graph, sandbox show/validate/choose/resolve, state
 summary refresh/show, `plan`, `approve`, `reject`, `comment.add`, `handoff`, and
 `review.policy`.
 
+## MCP Tool Hints and Version Negotiation
+
+A `tools/list` entry may carry the standard MCP `annotations` field with
+two behavior hints:
+
+- `readOnlyHint: true` — the tool only reads; it makes no change on disk.
+- `destructiveHint: true` (with `readOnlyHint: false`) — the tool deletes
+  stored data (the gc / delete sweeps: `cw_gc_run`, `cw_orphans_gc`,
+  `cw_clones_gc`, `cw_schedule_delete`, `cw_routine_delete`).
+
+The hints come from one side table (`MCP_TOOL_ANNOTATIONS` in
+`src/core/capability-data.ts`), and a tool goes in only after its handler
+was read and checked by hand — a wrong "read-only" mark on a writing tool
+would be a safety bug, so a tool we are not certain about carries no
+`annotations` field at all. Absent beats wrong. The field is additive: a
+client that does not know it simply does not read it.
+
+The MCP `initialize` reply also negotiates the protocol version now: a
+client that asks for a supported version gets that version echoed back,
+and any other request falls back to the newest supported entry (see
+`SUPPORTED_PROTOCOL_VERSIONS` in `src/mcp/server.ts`). With today's
+one-entry list the reply bytes are unchanged.
+
 ## The Parity Matrix
 
 The matrix below is made from the live registry — one row per capability,
@@ -643,3 +666,5 @@ CLI golden-path fixes: `cw -q "…"` routes the question (was read as an app id
 0.2.3
 
 0.2.4
+
+0.2.5

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

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

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

@@ -66,6 +66,40 @@ Additive: `RunQueueEntry` gets the optional `attempts`/`leaseId`/`leaseExpiresAt
 `queue add|list|drain|show` verbs that are already there do not change. No new database, no
 daemon-owned state.
 
+## Scheduled Tasks In Practice
+
+CW scheduled tasks give looping prompts, cron-like schedules, one-shot
+reminders, expiration, jitter, and clear completion. Schedules live in
+`.cw/schedules/tasks.json`.
+
+```bash
+# a /loop-ready schedule (cw loop is the short form of schedule create --kind loop)
+cw loop --intervalMinutes 30 --prompt "Check this workflow and continue if work is due."
+
+# a cron schedule
+cw schedule create --kind cron --cron "*/15 * * * *" --prompt "Run the due workflow scan."
+
+# a one-shot reminder
+cw schedule create --kind reminder --delayMinutes 60 --prompt "Remind me to inspect the report."
+
+# list, inspect, and manage
+cw schedule list
+cw schedule due
+cw schedule complete <schedule-id>
+cw schedule pause <schedule-id> / resume <schedule-id> / run-now <schedule-id>
+cw schedule history <schedule-id>
+cw schedule delete <schedule-id>
+
+# the local daemon: one sweep, or a loop
+cw schedule daemon --once
+cw schedule daemon --intervalSeconds 60
+```
+
+Notes: time is measured to the minute; expiration defaults to 7 days;
+`jitterSeconds` can put space between runs. CW does not start the daemon by
+default — use `schedule daemon`, cron, or another overseer to call
+`schedule due` and run due prompts.
+
 ## See Also
 
 run-registry-control-plane(7), cli-mcp-parity(7), release-and-migration(7)
@@ -167,3 +201,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.3
 
 0.2.4
+
+0.2.5

package/docs/cross-agent-ledger.7.md

@@ -3,8 +3,15 @@
 CW adds `cw ledger` — a way for two agents scoped to two separate repos to hand
 each other a CHANGE PROPOSAL or a REVIEW VERDICT as verifiable data, not chat.
 One side proposes or reviews; the other side verifies the entry fail-closed and
-turns a proposal into a real pull request. Design notes:
-[handoff-ledger](designs/handoff-ledger.md).
+turns a proposal into a real pull request.
+
+Design note (why not a shared folder): the obvious first design — a shared
+local directory both agents read and append to — only works when both agents
+run on ONE machine with ONE filesystem. Two agents scoped to two repos (or two
+machines) need a transport both can already reach, with saved, inspectable,
+fail-closed state — never a fabricated hand-off. That is why an entry is a
+self-verifying file in a git repo both sides can push and pull, and why the
+kernel holds no git logic at all.
 
 Each entry is a self-contained JSON object that carries its own sha256 content
 digest. The producing side prints one; it reaches the other session by human
@@ -51,13 +58,18 @@ cw ledger review  --from <a> --to <b> --target <proposal-id|pr-ref> \
                   --verdict <approved|rejected> [--findings "a,b"]
 cw ledger verify  [--file <path>]        # else reads the entry from stdin
 cw ledger apply   [--file <path>]        # verify a proposal, then print its diff
-cw ledger list    --dir <ledger-dir> [--dir <mirror-2> ...]   # verify a dir (or union of mirrors)
+cw ledger list    --ledger-dir <ledger-dir> [--ledger-dir <mirror-2> ...]   # verify a dir (or union of mirrors)
 ```
 
 All write JSON to stdout (stdout is data). `propose` and `review` print a sealed
 entry; `verify` prints a check report; `apply` prints a verify-plus-diff report;
 `list` prints a per-entry report over a directory.
 
+`--ledger-dir` is the preferred spelling for `list`: the CLI front door
+treats `--dir` as a global alias of `--repo` on every command, so the old
+`--dir` made one flag mean two things here. `--dir` keeps working
+unchanged as the legacy alias; when both are given, `--ledger-dir` wins.
+
 ## Applying a proposal — fail-closed
 
 A proposal carries a `suggestedDiff`, but a proposal never mutates the target
@@ -131,12 +143,12 @@ on the mirror-union output and on the `cw_ledger_list` MCP tool.
 
 ### Mirrors — union-verifying several directories
 
-`--dir` is repeatable. With two or more, `cw ledger list` **union-verifies** the
+`--ledger-dir` (and the legacy `--dir`) is repeatable. With two or more, `cw ledger list` **union-verifies** the
 directories as mirrors of one ledger (e.g. the same handoff repo cloned from a
 GitHub remote and one or more self-hosted Gitea remotes in different places):
 
 ```
-cw ledger list --dir gh/ledger --dir gitea-eu/ledger --dir gitea-asia/ledger
+cw ledger list --ledger-dir gh/ledger --ledger-dir gitea-eu/ledger --ledger-dir gitea-asia/ledger
 ```
 
 The union is **conflict-free by construction**: entries are immutable and
@@ -146,10 +158,10 @@ across mirrors** — a tampered entry in ANY mirror sets `allOk:false` and exits
 `1`. This is for redundancy and reachability, not load: the ledger's traffic is
 tiny; multiple hosts guard against one being down or unreachable.
 
-A single `--dir` keeps the original single-directory output (a `dir` field, no
+A single directory flag keeps the original single-directory output (a `dir` field, no
 `dirs`); two or more switch to the union shape (`dirs` plus a per-entry `dirs`).
 The transport stays git-host-agnostic — adding a mirror is one more clone + one
-more `--dir`, no code change.
+more `--ledger-dir`, no code change.
 
 ## Entry shape
 
@@ -214,4 +226,4 @@ cw ledger verify --file verdict.json
 Stage 1 shipped the CLI verbs (human relay). Stage 2 adds the MCP surface and
 the git-as-ledger transport (`cw ledger list` over a shared repo). Still open:
 the operator creates the shared handoff repo and scopes both agent environments
-into it. See [handoff-ledger](designs/handoff-ledger.md).
+into it. Setup runbook: [handoff-setup](handoff-setup.md).

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

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

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

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

package/docs/execution-backends.7.md

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

package/docs/fix.7.md

@@ -8,7 +8,6 @@
 
 ```text
 node dist/cli.js fix
-node dist/cli.js fix --json
 ```
 
 ## DESCRIPTION
@@ -28,9 +27,10 @@ If any check has status `fail`, the command exits with code 1.
 
 ## OPTIONS
 
-`--json`
-: Give back the full doctor report as a stable JSON object, with the same shape
-as `cw doctor --json`. The `checks` array carries every fix string.
+`cw fix` takes no options of its own; its output is always the plain fix-command
+text (a `--json` flag is silently ignored — this byte behavior is pinned by
+`v2/conformance/cases/report-fix.case.js`). For a machine-readable report of the
+same checks, use `cw doctor --json`: its `checks` array carries every fix string.
 
 ## EXIT CODES