cool-workflow 0.2.3 → 0.2.5

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

@@ -6,8 +6,8 @@
 // retyped).
 Object.defineProperty(exports, "__esModule", { value: true });
 const registry_core_1 = require("./registry-core");
-const io_1 = require("../../cli/io");
-const io_2 = require("../../cli/io");
+const cli_args_1 = require("../../core/util/cli-args");
+const cli_args_2 = require("../../core/util/cli-args");
 // MILESTONE 6+7 (combined; see docs/rebuild/PLAN.md Open risk 10) CLI bindings:
 // plan, quickstart, run --drive, run drive (preview), dispatch, result,
 // commit. Handler BODIES live in shell/pipeline-cli.ts (impure — they
@@ -28,7 +28,7 @@ function loadCommitSummary() {
     path: ["plan"],
     jsonMode: "default",
     handler: (args) => {
-        const workflowId = (0, io_2.optionalArg)(args.positionals[0]);
+        const workflowId = (0, cli_args_2.optionalArg)(args.positionals[0]);
         if (!workflowId) {
             throw new Error('Missing workflow id.\n  Tip: plan an architecture review with "cw plan architecture-review"');
         }
@@ -45,13 +45,20 @@ 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) => {
         const registrySubcommands = new Set(["drive", "search", "list", "show", "resume", "archive", "rerun", "export", "import", "verify-import", "inspect-archive", "restore"]);
         const target = args.positionals[0];
         if (args.options.drive && !registrySubcommands.has(String(target || ""))) {
-            const runId = (0, io_2.optionalArg)(args.options.run) || (0, io_2.optionalArg)(args.options.runId);
+            const runId = (0, cli_args_2.optionalArg)(args.options.run) || (0, cli_args_2.optionalArg)(args.options.runId);
             if (args.options.preview)
                 return { json: loadPipelineCli().runDrivePreview({ ...args.options, runId: runId || target }) };
             const driveArgs = { ...args.options };
@@ -69,29 +76,29 @@ function loadCommitSummary() {
                     driveArgs.runId = id;
                 return { json: await loadPipelineCli().runDriveStep(driveArgs) };
             }
-            return { json: loadPipelineCli().runDrivePreview({ ...args.options, runId: (0, io_1.required)(id, "run id") }) };
+            return { json: loadPipelineCli().runDrivePreview({ ...args.options, runId: (0, cli_args_1.required)(id, "run id") }) };
         }
         // MILESTONE 11 (reporting/run-export) — the archive family. Handler
         // bodies live in shell/run-export-cli.ts; this arm only wires argv
         // shape -> handler call.
         if (subcommand === "export") {
-            const result = loadRunExportCli().runExportCli((0, io_1.required)(id, "run id"), args.options);
+            const result = loadRunExportCli().runExportCli((0, cli_args_1.required)(id, "run id"), args.options);
             return { json: result };
         }
         if (subcommand === "import") {
-            const result = loadRunExportCli().runImportCli((0, io_1.required)(id, "archive path"), args.options);
+            const result = loadRunExportCli().runImportCli((0, cli_args_1.required)(id, "archive path"), args.options);
             return { json: result };
         }
         if (subcommand === "verify-import") {
-            const result = loadRunExportCli().runVerifyImportCli((0, io_1.required)(id, "run id"), args.options);
+            const result = loadRunExportCli().runVerifyImportCli((0, cli_args_1.required)(id, "run id"), args.options);
             return { json: result, exitCode: args.options.strict && !result.ok ? 1 : undefined };
         }
         if (subcommand === "inspect-archive") {
-            const result = loadRunExportCli().runInspectArchiveCli((0, io_1.required)(id, "archive path"), args.options);
+            const result = loadRunExportCli().runInspectArchiveCli((0, cli_args_1.required)(id, "archive path"), args.options);
             return { json: result, exitCode: result.ok ? undefined : 1 };
         }
         if (subcommand === "restore") {
-            const result = loadRunExportCli().runRestoreCli((0, io_1.required)(id, "archive path"), args.options);
+            const result = loadRunExportCli().runRestoreCli((0, cli_args_1.required)(id, "archive path"), args.options);
             return { json: result, exitCode: result.ok ? undefined : 1 };
         }
         throw new Error("Usage: cw run search|list|show|resume|archive|rerun|drive|export|import|verify-import|inspect-archive|restore [run-id|archive] [--scope repo|home] [--json]  |  cw run <app> --drive [--once] [--incremental] [--repo R --question Q]");
@@ -119,11 +126,24 @@ function loadCommitSummary() {
                 driveArgs.runId = id;
             return { json: await loadPipelineCli().runDriveStep(driveArgs) };
         }
-        return { json: loadPipelineCli().runDrivePreview({ ...args.options, runId: (0, io_1.required)(id, "run id") }) };
+        return { json: loadPipelineCli().runDrivePreview({ ...args.options, runId: (0, cli_args_1.required)(id, "run id") }) };
     },
 });
 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
@@ -180,11 +200,11 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("commit").reason =
 function loadRunExportCli() {
     return require("../../shell/run-export-cli");
 }
-registry_core_1.REGISTRY_BY_CAPABILITY.get("run.export").mcp.handler = (args) => loadRunExportCli().runExportCli((0, io_1.required)((0, io_2.optionalArg)(args.runId), "run id"), args);
-registry_core_1.REGISTRY_BY_CAPABILITY.get("run.import").mcp.handler = (args) => loadRunExportCli().runImportCli((0, io_1.required)((0, io_2.optionalArg)(args.archive || args.path || args.file), "archive path"), args);
-registry_core_1.REGISTRY_BY_CAPABILITY.get("run.verify-import").mcp.handler = (args) => loadRunExportCli().runVerifyImportCli((0, io_1.required)((0, io_2.optionalArg)(args.runId), "run id"), args);
-registry_core_1.REGISTRY_BY_CAPABILITY.get("run.inspect-archive").mcp.handler = (args) => loadRunExportCli().runInspectArchiveCli((0, io_1.required)((0, io_2.optionalArg)(args.archive || args.path || args.file), "archive path"), args);
-registry_core_1.REGISTRY_BY_CAPABILITY.get("run.restore").mcp.handler = (args) => loadRunExportCli().runRestoreCli((0, io_1.required)((0, io_2.optionalArg)(args.archive || args.path || args.file), "archive path"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("run.export").mcp.handler = (args) => loadRunExportCli().runExportCli((0, cli_args_1.required)((0, cli_args_2.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("run.import").mcp.handler = (args) => loadRunExportCli().runImportCli((0, cli_args_1.required)((0, cli_args_2.optionalArg)(args.archive || args.path || args.file), "archive path"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("run.verify-import").mcp.handler = (args) => loadRunExportCli().runVerifyImportCli((0, cli_args_1.required)((0, cli_args_2.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("run.inspect-archive").mcp.handler = (args) => loadRunExportCli().runInspectArchiveCli((0, cli_args_1.required)((0, cli_args_2.optionalArg)(args.archive || args.path || args.file), "archive path"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("run.restore").mcp.handler = (args) => loadRunExportCli().runRestoreCli((0, cli_args_1.required)((0, cli_args_2.optionalArg)(args.archive || args.path || args.file), "archive path"), args);
 // `run export|import|verify-import|inspect-archive|restore` each carry their
 // own two-token cli.path (found before the ["run"] run.drive.step catch-all
 // per the reversed candidate order), calling the same shell fns with the
@@ -195,20 +215,20 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("run.restore").mcp.handler = (args) =
     path: ["run", "export"],
     jsonMode: "default",
     hiddenFromHelp: true,
-    handler: (args) => ({ json: loadRunExportCli().runExportCli((0, io_1.required)(args.positionals[0], "run id"), args.options) }),
+    handler: (args) => ({ json: loadRunExportCli().runExportCli((0, cli_args_1.required)(args.positionals[0], "run id"), args.options) }),
 });
 (0, registry_core_1.attachCliBinding)("run.import", {
     path: ["run", "import"],
     jsonMode: "default",
     hiddenFromHelp: true,
-    handler: (args) => ({ json: loadRunExportCli().runImportCli((0, io_1.required)(args.positionals[0], "archive path"), args.options) }),
+    handler: (args) => ({ json: loadRunExportCli().runImportCli((0, cli_args_1.required)(args.positionals[0], "archive path"), args.options) }),
 });
 (0, registry_core_1.attachCliBinding)("run.verify-import", {
     path: ["run", "verify-import"],
     jsonMode: "default",
     hiddenFromHelp: true,
     handler: (args) => {
-        const result = loadRunExportCli().runVerifyImportCli((0, io_1.required)(args.positionals[0], "run id"), args.options);
+        const result = loadRunExportCli().runVerifyImportCli((0, cli_args_1.required)(args.positionals[0], "run id"), args.options);
         return { json: result, exitCode: args.options.strict && !result.ok ? 1 : undefined };
     },
 });
@@ -217,7 +237,7 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("run.restore").mcp.handler = (args) =
     jsonMode: "default",
     hiddenFromHelp: true,
     handler: (args) => {
-        const result = loadRunExportCli().runInspectArchiveCli((0, io_1.required)(args.positionals[0], "archive path"), args.options);
+        const result = loadRunExportCli().runInspectArchiveCli((0, cli_args_1.required)(args.positionals[0], "archive path"), args.options);
         return { json: result, exitCode: result.ok ? undefined : 1 };
     },
 });
@@ -226,7 +246,7 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("run.restore").mcp.handler = (args) =
     jsonMode: "default",
     hiddenFromHelp: true,
     handler: (args) => {
-        const result = loadRunExportCli().runRestoreCli((0, io_1.required)(args.positionals[0], "archive path"), args.options);
+        const result = loadRunExportCli().runRestoreCli((0, cli_args_1.required)(args.positionals[0], "archive path"), args.options);
         return { json: result, exitCode: result.ok ? undefined : 1 };
     },
 });
@@ -237,7 +257,7 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("run.restore").mcp.handler = (args) =
     caseTokens: ["quickstart", "audit-run"],
     jsonMode: "default",
     handler: async (args) => {
-        const appId = (0, io_2.optionalArg)(args.positionals[0]);
+        const appId = (0, cli_args_2.optionalArg)(args.positionals[0]);
         const result = (await loadPipelineCli().quickstartRun({ ...args.options, appId }));
         // Fail closed on both known bad outcomes: a --check preflight that
         // found a blocking gap, OR a --bundle that did not self-verify.
@@ -246,12 +266,24 @@ 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"],
     jsonMode: "default",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_2.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_2.optionalArg)(args.positionals[0]), "run id");
         return { json: loadPipelineCli().dispatchRun({ ...args.options, runId }) };
     },
 });
@@ -259,9 +291,9 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("run.restore").mcp.handler = (args) =
     path: ["result"],
     jsonMode: "default",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_2.optionalArg)(args.positionals[0]), "run id");
-        const taskId = (0, io_1.required)((0, io_2.optionalArg)(args.positionals[1]), "task id");
-        const resultPath = (0, io_1.required)((0, io_2.optionalArg)(args.positionals[2]), "result file path");
+        const runId = (0, cli_args_1.required)((0, cli_args_2.optionalArg)(args.positionals[0]), "run id");
+        const taskId = (0, cli_args_1.required)((0, cli_args_2.optionalArg)(args.positionals[1]), "task id");
+        const resultPath = (0, cli_args_1.required)((0, cli_args_2.optionalArg)(args.positionals[2]), "result file path");
         return { json: loadPipelineCli().recordResultRun({ ...args.options, runId, taskId, resultPath }) };
     },
 });
@@ -269,7 +301,7 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("run.restore").mcp.handler = (args) =
     path: ["commit"],
     jsonMode: "default",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_2.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_2.optionalArg)(args.positionals[0]), "run id");
         return { json: loadPipelineCli().commitRun({ ...args.options, runId }) };
     },
 });
@@ -284,7 +316,7 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("run.restore").mcp.handler = (args) =
     jsonMode: "flag",
     handler: (args) => {
         const commitSummary = loadCommitSummary();
-        const summary = commitSummary.commitSummaryCli({ ...args.options, runId: (0, io_1.required)(args.positionals[0], "run id") });
+        const summary = commitSummary.commitSummaryCli({ ...args.options, runId: (0, cli_args_1.required)(args.positionals[0], "run id") });
         return { json: summary, text: `${commitSummary.formatCommitSummaryText(summary)}\n` };
     },
 });

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

@@ -32,7 +32,7 @@ exports.mcpToolDefinitions = mcpToolDefinitions;
 exports.declaredMcpTools = declaredMcpTools;
 exports.findCapabilityByMcpTool = findCapabilityByMcpTool;
 const capability_data_1 = require("../../core/capability-data");
-const io_1 = require("../../cli/io");
+const cli_args_1 = require("../../core/util/cli-args");
 // Every capability-table module (this file plus each domain slice) is
 // required unconditionally at CLI/MCP startup, for every single command
 // (index.ts's whole point is to populate REGISTRY before dispatch can
@@ -65,8 +65,8 @@ const MCP_REAL_HANDLERS = {
     list: () => listBundledWorkflows(),
     "sandbox.list": () => listBundledSandboxProfiles(),
     status: (args) => statusPayload(optionalString(args.runId)),
-    "summary.refresh": (args) => loadStateExplosionCli().summaryRefreshCli((0, io_1.required)(optionalString(args.runId), "run id"), args),
-    "summary.show": (args) => loadStateExplosionCli().summaryShowCli((0, io_1.required)(optionalString(args.runId), "run id"), args),
+    "summary.refresh": (args) => loadStateExplosionCli().summaryRefreshCli((0, cli_args_1.required)(optionalString(args.runId), "run id"), args),
+    "summary.show": (args) => loadStateExplosionCli().summaryShowCli((0, cli_args_1.required)(optionalString(args.runId), "run id"), args),
 };
 function optionalString(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
@@ -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

@@ -39,7 +39,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 const registry_core_1 = require("./registry-core");
-const io_1 = require("../../cli/io");
+const cli_args_1 = require("../../core/util/cli-args");
 const state_explosion_text_1 = require("../../core/format/state-explosion-text");
 // This file is required at startup for every command. Loading these shell
 // modules only when their handler runs, not at import time, keeps that
@@ -67,7 +67,7 @@ function loadOperatorUxText() {
     path: ["report"],
     jsonMode: "flag",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id");
         const reportViewCli = loadReportViewCli();
         const result = reportViewCli.reportWriteCli(runId, args.options);
         if (args.options.show || args.options.summary) {
@@ -77,7 +77,7 @@ function loadOperatorUxText() {
         return { json: result, text: `${result.path}\n` };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("report").mcp.handler = (args) => loadReportViewCli().reportWriteCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("report").mcp.handler = (args) => loadReportViewCli().reportWriteCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 // `status` already carries a milestone-2 CLI binding (`attachCliBinding("status", ...)`
 // above); replace its handler here with the real run-id-aware body while
 // keeping the same row/path (no reshape needed — see byte-compat item 5).
@@ -89,7 +89,7 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("status").cli = {
         // resolve the same run — the flag form used to be silently ignored
         // (positionals[0] only), so a bogus id given via --run and a real one
         // looked identical ("No run selected" for both).
-        const runId = (0, io_1.optionalArg)(args.positionals[0]) || (0, io_1.optionalArg)(args.options.run) || (0, io_1.optionalArg)(args.options.runId);
+        const runId = (0, cli_args_1.optionalArg)(args.positionals[0]) || (0, cli_args_1.optionalArg)(args.options.run) || (0, cli_args_1.optionalArg)(args.options.runId);
         const reportViewCli = loadReportViewCli();
         if (!runId)
             return { json: reportViewCli.statusCli(undefined, args.options), text: `No run selected\n\nNext Action\n${adviseNoRunLines()}` };
@@ -99,7 +99,7 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("status").cli = {
         return { json: reportViewCli.statusCli(runId, args.options), text: `${reportViewCli.statusFullText(runId, args.options)}\n` };
     },
 };
-registry_core_1.REGISTRY_BY_CAPABILITY.get("status").mcp.handler = (args) => loadReportViewCli().statusCli((0, io_1.optionalArg)(args.runId), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("status").mcp.handler = (args) => loadReportViewCli().statusCli((0, cli_args_1.optionalArg)(args.runId), args);
 function adviseNoRunLines() {
     return "  cw plan <workflow-id> --repo <path>\n    reason: No run id is available yet; create a workflow run before dispatching or recording evidence.\n";
 }
@@ -107,17 +107,17 @@ function adviseNoRunLines() {
     path: ["graph"],
     jsonMode: "flag",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id");
         const reportViewCli = loadReportViewCli();
         return { json: reportViewCli.graphCli(runId, args.options), text: `${reportViewCli.graphText(runId, args.options)}\n` };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("graph").mcp.handler = (args) => loadReportViewCli().graphCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("graph").mcp.handler = (args) => loadReportViewCli().graphCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("operator.status", {
     path: ["operator", "status"],
     jsonMode: "flag",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id");
         const reportViewCli = loadReportViewCli();
         if (args.options.summary || args.options.brief) {
             return { json: reportViewCli.operatorStatusCli(runId, args.options), text: `${reportViewCli.statusSummaryText(runId, args.options)}\n` };
@@ -125,17 +125,17 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("graph").mcp.handler = (args) => load
         return { json: reportViewCli.operatorStatusCli(runId, args.options), text: `${reportViewCli.statusFullText(runId, args.options)}\n` };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("operator.status").mcp.handler = (args) => loadReportViewCli().operatorStatusCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("operator.status").mcp.handler = (args) => loadReportViewCli().operatorStatusCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("operator.report", {
     path: ["operator", "report"],
     jsonMode: "flag",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id");
         const reportViewCli = loadReportViewCli();
         return { json: reportViewCli.operatorReportCli(runId, args.options), text: `${reportViewCli.operatorReportText(runId, args.options)}\n` };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("operator.report").mcp.handler = (args) => loadReportViewCli().operatorReportCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("operator.report").mcp.handler = (args) => loadReportViewCli().operatorReportCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 // ---- metrics.show / metrics.summary -----------------------------------
 function loadMetricsCli() {
     return require("../../shell/metrics-cli");
@@ -147,12 +147,12 @@ function loadObservability() {
     path: ["metrics", "show"],
     jsonMode: "flag",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id");
         const report = loadMetricsCli().metricsShowCli(runId, args.options);
         return { json: report, text: `${loadObservability().formatMetricsReport(report)}\n` };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("metrics.show").mcp.handler = (args) => loadMetricsCli().metricsShowCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("metrics.show").mcp.handler = (args) => loadMetricsCli().metricsShowCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("metrics.summary", {
     path: ["metrics", "summary"],
     jsonMode: "flag",
@@ -168,12 +168,12 @@ function loadWorkerIsolation() {
 }
 const workerPath = __importStar(require("node:path"));
 function workerSummaryCli(args) {
-    const runId = (0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id");
+    const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id");
     const run = loadRunStore().loadRunFromCwd(runId, invocationCwdFor(args));
     return loadWorkerIsolation().summarizeWorkers(run);
 }
 function workerSummaryText(args) {
-    const runId = (0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id");
+    const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id");
     const run = loadRunStore().loadRunFromCwd(runId, invocationCwdFor(args));
     return loadWorkerIsolation().formatWorkerSummaryText(run);
 }
@@ -300,7 +300,7 @@ function loadWorkbenchHost() {
     path: ["workbench", "view"],
     jsonMode: "flag",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id");
         const view = loadWorkbench().buildWorkbenchRunView(runId, args.options);
         return { json: view, text: `${loadWorkbenchText().formatWorkbenchView(view)}\n` };
     },
@@ -308,14 +308,14 @@ function loadWorkbenchHost() {
 // The MCP path is CLI-facing byte-identical (buildWorkbenchRunView takes
 // the same args shape either way) — required here since `.cli` and
 // `.mcp` never share a handler object per byte-compat item 5.
-registry_core_1.REGISTRY_BY_CAPABILITY.get("workbench.view").mcp.handler = (args) => loadWorkbench().buildWorkbenchRunView((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("workbench.view").mcp.handler = (args) => loadWorkbench().buildWorkbenchRunView((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("workbench.serve", {
     path: ["workbench", "serve"],
     jsonMode: "flag",
     handler: (args) => {
         const { WorkbenchHost } = loadWorkbenchHost();
         const host = new WorkbenchHost(args.options);
-        if (args.options.once || (0, io_1.wantsJson)(args.options)) {
+        if (args.options.once || (0, cli_args_1.wantsJson)(args.options)) {
             return { json: host.descriptor(true) };
         }
         // The default (no --once, no --json) actually binds and blocks — this
@@ -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 };
     },
 });
@@ -355,36 +361,36 @@ function loadEvalText() {
 (0, registry_core_1.attachCliBinding)("audit.summary", {
     path: ["audit", "summary"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadAuditCli().auditSummaryCli((0, io_1.required)(args.positionals[0], "run id"), args.options) }),
+    handler: (args) => ({ json: loadAuditCli().auditSummaryCli((0, cli_args_1.required)(args.positionals[0], "run id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.summary").mcp.handler = (args) => loadAuditCli().auditSummaryCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.summary").mcp.handler = (args) => loadAuditCli().auditSummaryCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("audit.multi-agent", {
     path: ["audit", "multi-agent"],
     jsonMode: "flag",
     handler: (args) => {
-        const view = loadAuditCli().auditMultiAgentCli((0, io_1.required)(args.positionals[0], "run id"), args.options);
+        const view = loadAuditCli().auditMultiAgentCli((0, cli_args_1.required)(args.positionals[0], "run id"), args.options);
         return { json: view, text: loadOperatorUxText().formatMultiAgentTrustAudit(view) };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.multi-agent").mcp.handler = (args) => loadAuditCli().auditMultiAgentCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.multi-agent").mcp.handler = (args) => loadAuditCli().auditMultiAgentCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("audit.policy", {
     path: ["audit", "policy"],
     jsonMode: "flag",
     handler: (args) => {
-        const view = loadAuditCli().auditPolicyCli((0, io_1.required)(args.positionals[0], "run id"), args.options);
+        const view = loadAuditCli().auditPolicyCli((0, cli_args_1.required)(args.positionals[0], "run id"), args.options);
         return { json: view, text: loadOperatorUxText().formatMultiAgentTrustAudit(view) };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.policy").mcp.handler = (args) => loadAuditCli().auditPolicyCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.policy").mcp.handler = (args) => loadAuditCli().auditPolicyCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("audit.judge", {
     path: ["audit", "judge"],
     jsonMode: "flag",
     handler: (args) => {
-        const view = loadAuditCli().auditJudgeCli((0, io_1.required)(args.positionals[0], "run id"), args.options);
+        const view = loadAuditCli().auditJudgeCli((0, cli_args_1.required)(args.positionals[0], "run id"), args.options);
         return { json: view, text: loadOperatorUxText().formatMultiAgentTrustAudit(view) };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.judge").mcp.handler = (args) => loadAuditCli().auditJudgeCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.judge").mcp.handler = (args) => loadAuditCli().auditJudgeCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 // GAP: `cw audit worker|provenance|role|blackboard|attest|decision` — the MCP
 // tool rows (cw_audit_worker/provenance/role/blackboard/attest/decision) were
 // declared but had no CLI path binding and their mcp.handler was still
@@ -393,43 +399,43 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.judge").mcp.handler = (args) =
 (0, registry_core_1.attachCliBinding)("audit.worker", {
     path: ["audit", "worker"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadAuditCli().auditWorkerCli((0, io_1.required)(args.positionals[0], "run id"), (0, io_1.required)(args.positionals[1], "worker id"), args.options) }),
+    handler: (args) => ({ json: loadAuditCli().auditWorkerCli((0, cli_args_1.required)(args.positionals[0], "run id"), (0, cli_args_1.required)(args.positionals[1], "worker id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.worker").mcp.handler = (args) => loadAuditCli().auditWorkerCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), (0, io_1.required)((0, io_1.optionalArg)(args.workerId ?? args.worker), "worker id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.worker").mcp.handler = (args) => loadAuditCli().auditWorkerCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.workerId ?? args.worker), "worker id"), args);
 (0, registry_core_1.attachCliBinding)("audit.provenance", {
     path: ["audit", "provenance"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadAuditCli().auditProvenanceCli((0, io_1.required)(args.positionals[0], "run id"), args.options) }),
+    handler: (args) => ({ json: loadAuditCli().auditProvenanceCli((0, cli_args_1.required)(args.positionals[0], "run id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.provenance").mcp.handler = (args) => loadAuditCli().auditProvenanceCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.provenance").mcp.handler = (args) => loadAuditCli().auditProvenanceCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("audit.role", {
     path: ["audit", "role"],
     jsonMode: "flag",
     handler: (args) => {
-        const view = loadAuditCli().auditRoleCli((0, io_1.required)(args.positionals[0], "run id"), (0, io_1.required)(args.positionals[1], "role id"), args.options);
+        const view = loadAuditCli().auditRoleCli((0, cli_args_1.required)(args.positionals[0], "run id"), (0, cli_args_1.required)(args.positionals[1], "role id"), args.options);
         return { json: view, text: loadOperatorUxText().formatMultiAgentTrustAudit(view) };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.role").mcp.handler = (args) => loadAuditCli().auditRoleCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), (0, io_1.required)((0, io_1.optionalArg)(args.roleId ?? args.id), "role id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.role").mcp.handler = (args) => loadAuditCli().auditRoleCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.roleId ?? args.id), "role id"), args);
 (0, registry_core_1.attachCliBinding)("audit.blackboard", {
     path: ["audit", "blackboard"],
     jsonMode: "flag",
     handler: (args) => {
-        const view = loadAuditCli().auditBlackboardCli((0, io_1.required)(args.positionals[0], "run id"), args.options);
+        const view = loadAuditCli().auditBlackboardCli((0, cli_args_1.required)(args.positionals[0], "run id"), args.options);
         return { json: view, text: loadOperatorUxText().formatMultiAgentTrustAudit(view) };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.blackboard").mcp.handler = (args) => loadAuditCli().auditBlackboardCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.blackboard").mcp.handler = (args) => loadAuditCli().auditBlackboardCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("audit.attest", {
     path: ["audit", "attest"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadAuditCli().auditAttestCli((0, io_1.required)(args.positionals[0], "run id"), args.options) }),
+    handler: (args) => ({ json: loadAuditCli().auditAttestCli((0, cli_args_1.required)(args.positionals[0], "run id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.attest").mcp.handler = (args) => loadAuditCli().auditAttestCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.attest").mcp.handler = (args) => loadAuditCli().auditAttestCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("audit.decision", {
     path: ["audit", "decision"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadAuditCli().auditDecisionCli((0, io_1.required)(args.positionals[0], "run id"), (0, io_1.required)(args.positionals[1], "worker id"), args.options) }),
+    handler: (args) => ({ json: loadAuditCli().auditDecisionCli((0, cli_args_1.required)(args.positionals[0], "run id"), (0, cli_args_1.required)(args.positionals[1], "worker id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.decision").mcp.handler = (args) => loadAuditCli().auditDecisionCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), (0, io_1.required)((0, io_1.optionalArg)(args.workerId), "worker id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.decision").mcp.handler = (args) => loadAuditCli().auditDecisionCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.workerId), "worker id"), args);
 // ---- app.list / app.show / app.validate / app.init / app.package -------