cool-workflow 0.2.4 → 0.2.6

package/dist/core/format/help.js

@@ -30,6 +30,7 @@ exports.formatHelp = formatHelp;
 exports.formatCommandHelp = formatCommandHelp;
 exports.formatInfo = formatInfo;
 exports.formatSearchResults = formatSearchResults;
+exports.formatWorkflowList = formatWorkflowList;
 const capability_table_1 = require("../capability-table");
 /** src/orchestrator.ts:934-951 — the "More commands" token set, in the old
  *  build's order (space-joined in the source, pipe-joined for display).
@@ -252,6 +253,7 @@ function formatHelp() {
         "  -claude                Use Claude agent",
         "  -codex                 Use Codex agent",
         "  -gemini                Use Gemini (via opencode)",
+        "  -opencode              Use OpenCode agent",
         "  -deepseek              Use DeepSeek (via opencode)",
         "  --verbose              Show full agent narration live (default: compact)",
         "  --full                 Verbose, plus the report printed inline at the end",
@@ -276,16 +278,44 @@ function formatHelp() {
 function cliCommandHelpRows(verb) {
     return (0, capability_table_1.cliCapabilities)()
         .filter((row) => row.cli.path[0] === verb && !row.cli.hiddenFromHelp)
-        .map((row) => ({ command: `cw ${(row.cli.helpPath ?? row.cli.path).join(" ")}`, summary: row.summary }));
+        .map((row) => ({
+        command: `cw ${(row.cli.helpPath ?? row.cli.path).join(" ")}`,
+        summary: row.summary,
+        ...(row.cli.flags ? { flags: row.cli.flags } : {}),
+    }));
+}
+/** A verb that is only a `caseTokens` alias of another verb's row (e.g.
+ *  `audit-run` -> `quickstart`) has NO row whose `cli.path[0]` matches it,
+ *  so `cliCommandHelpRows` above finds nothing for it. This looks the
+ *  alias up the same way the dispatcher does (registry-core.ts's
+ *  findCapabilityByCliPath alias branch: a row whose `caseTokens` holds
+ *  the token) and returns the verb the alias dispatches to. */
+function aliasTargetVerb(verb) {
+    for (const row of (0, capability_table_1.cliCapabilities)()) {
+        if (row.cli.caseTokens && row.cli.caseTokens.includes(verb) && row.cli.path[0] !== verb) {
+            return row.cli.path[0];
+        }
+    }
+    return undefined;
 }
 /** src/orchestrator.ts:988-1007 — `formatCommandHelp(verb)`. Unknown verb
  *  gives a SOFT text (never a throw); known verb lists its registry rows,
  *  sorted by command string, padded to the longest command column + 2
  *  (capped at 40, per the old registry's own cap; none of the milestone-1
- *  fixture rows exceed it). */
+ *  fixture rows exceed it). An alias verb (a `caseTokens` token like
+ *  `audit-run`) gets an alias header line plus its target verb's rows —
+ *  before this fix it fell into the unknown-verb text and, worse, the
+ *  Did-you-mean line suggested the very verb the user just typed. */
 function formatCommandHelp(verb, suggestCommand) {
     const rows = [...(COMMAND_HELP_ROWS[verb] ?? []), ...cliCommandHelpRows(verb)];
     if (rows.length === 0) {
+        const target = aliasTargetVerb(verb);
+        if (target) {
+            const targetRows = [...(COMMAND_HELP_ROWS[target] ?? []), ...cliCommandHelpRows(target)];
+            if (targetRows.length > 0) {
+                return renderCommandHelpRows(`cw ${verb} — alias of cw ${target}`, targetRows);
+            }
+        }
         const hint = suggestCommand(verb);
         const lines = [`Unknown command: ${verb}`];
         if (hint)
@@ -293,13 +323,40 @@ function formatCommandHelp(verb, suggestCommand) {
         lines.push("  Try:  cw help   (list all commands)");
         return `${lines.join("\n")}\n`;
     }
+    return renderCommandHelpRows(`cw ${verb}`, rows);
+}
+/** The row-list rendering `formatCommandHelp` has always done, extracted
+ *  so the alias page above can render its target's rows under its own
+ *  header line without a second copy of the sort/pad/Flags logic. */
+function renderCommandHelpRows(header, rows) {
     const sorted = [...rows].sort((a, b) => (a.command < b.command ? -1 : a.command > b.command ? 1 : 0));
     const longest = Math.min(40, Math.max(...sorted.map((row) => row.command.length)));
-    const lines = [`cw ${verb}`, ""];
+    const lines = [header, ""];
     for (const row of sorted) {
         const padded = row.command.padEnd(longest, " ");
         lines.push(`  ${padded}  ${row.summary}`);
     }
+    // Flags block(s): only for rows that declare at least one flag (most
+    // rows do not — see CliBinding.flags). Uses the SAME 4-space indent as
+    // formatHelp's own "Run cw help <command> ..." note above, on purpose:
+    // the CLI/MCP parity help-token parser reads only 2-space lines as
+    // command tokens, so any wider indent is a line it already knows to
+    // skip. One row's command name is only spelled out in the block's own
+    // header when more than one row on this page declares flags (e.g.
+    // "cw ledger" lists both propose and review); a single-row page (e.g.
+    // "cw doctor") just says "Flags".
+    const flaggedRows = sorted.filter((row) => row.flags && row.flags.length > 0);
+    if (flaggedRows.length > 0) {
+        const oneFlaggedRow = flaggedRows.length === 1;
+        for (const row of flaggedRows) {
+            const flags = row.flags;
+            const flagWidth = Math.min(40, Math.max(...flags.map((flag) => flag.name.length)));
+            lines.push("", oneFlaggedRow ? "    Flags" : `    Flags (${row.command})`);
+            for (const flag of flags) {
+                lines.push(`      ${flag.name.padEnd(flagWidth, " ")}  ${flag.summary}`);
+            }
+        }
+    }
     return `${lines.join("\n")}\n`;
 }
 /** `cw info <id>` human card — MILESTONE 12. Byte-exact in spirit to
@@ -360,3 +417,16 @@ function formatSearchResults(keyword, results) {
     lines.push("Use cw info <id> for full details.");
     return lines.join("\n");
 }
+/** `cw list`'s TTY-only human text (the `list` row's `humanRender`, see
+ *  core/capability-data.ts's CliBinding). Modeled on formatSearchResults
+ *  above: one "<id> — <title>" line per workflow, then the same short
+ *  next-step footer. NEVER printed to a pipe — the row's canonical JSON
+ *  stays the only piped output (SPEC/cli-surface.md's jsonMode contract:
+ *  "default" verbs are always JSON on a non-TTY stream). */
+function formatWorkflowList(workflows) {
+    const rows = (Array.isArray(workflows) ? workflows : []);
+    const lines = rows.map((w) => `${w.id} — ${w.title}`);
+    lines.push("");
+    lines.push("Use cw info <id> for full details.");
+    return lines.join("\n");
+}

package/dist/core/format/recovery-hint.js

@@ -0,0 +1,32 @@
+"use strict";
+// core/format/recovery-hint.ts — recoveryHint, a pure content-based lookup
+// from a thrown error's message to ONE copy-pasteable follow-up command.
+//
+// src/cli.ts:18-29 in the old build. Moved here (out of cli/entry.ts) so
+// mcp/server.ts can use the same lookup for its own error text without
+// crossing the mcp/-may-never-import-cli/ layer rule that
+// scripts/purity-gate.js enforces — core/ may be read by both cli/ and
+// mcp/. cli/entry.ts now just re-exports this function; its own call
+// site and behavior are unchanged.
+//
+// Content-based (reads the message text, not the call site), so it stays
+// correct no matter which command or tool threw. Returns `undefined`
+// rather than a wrong guess when no pattern matches.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recoveryHint = recoveryHint;
+function recoveryHint(message) {
+    const m = message.toLowerCase();
+    if (m.startsWith("unknown command"))
+        return "cw help";
+    if (m.includes("not configured") || m.includes("agent backend"))
+        return "cw doctor";
+    if (m.includes("missing") && m.includes("repo"))
+        return 'cw -q "<question>" -dir <project-folder>';
+    if (m.includes("app") && (m.includes("not found") || m.includes("not available")))
+        return "cw app list";
+    if (m.includes("run id") || m.includes("run not found"))
+        return "cw run list";
+    if (m.includes("missing required input") && m.includes("question"))
+        return 'cw -q "<question>"';
+    return undefined;
+}

package/dist/core/multi-agent/collaboration.js

@@ -36,6 +36,7 @@ exports.listComments = listComments;
 exports.distinctTargets = distinctTargets;
 exports.formatReviewStatus = formatReviewStatus;
 exports.formatCommentList = formatCommentList;
+const cli_args_1 = require("../util/cli-args");
 const collate_1 = require("../util/collate");
 exports.COLLABORATION_SCHEMA_VERSION = 1;
 /** The single, honest stand-in for an absent identity. */
@@ -166,10 +167,10 @@ function buildHandoff(input, handoffCount, runId, now, auditEventId) {
         auditEventIds: [auditEventId],
     });
 }
-/** Boolean-coerce a defined tri-state flag; leave `undefined` alone so the
+/** Parse a defined tri-state flag; leave `undefined` alone so the
  *  caller's `?? existing ?? default` chain still governs an unset flag. */
-function coerceFlag(value) {
-    return value === undefined ? undefined : Boolean(value);
+function coerceFlag(value, label) {
+    return (0, cli_args_1.parseBoolFlag)(value, label);
 }
 function toNumber(value, fallback) {
     if (value === undefined || value === null || value === "" || value === true)
@@ -201,8 +202,8 @@ function buildReviewPolicy(input, existing, now) {
         id: existing?.id || createCollabId("policy", 0),
         requiredApprovals: Math.max(0, Math.floor(toNumber(input.requiredApprovals, existing?.requiredApprovals ?? 0))),
         authorizedRoles: toStringList(input.authorizedRoles, existing?.authorizedRoles ?? ["*"]),
-        allowSelfApproval: coerceFlag(input.allowSelfApproval) ?? existing?.allowSelfApproval ?? false,
-        requireAttestedActor: coerceFlag(input.requireAttestedActor) ?? existing?.requireAttestedActor ?? false,
+        allowSelfApproval: coerceFlag(input.allowSelfApproval, "allowSelfApproval") ?? existing?.allowSelfApproval ?? false,
+        requireAttestedActor: coerceFlag(input.requireAttestedActor, "requireAttestedActor") ?? existing?.requireAttestedActor ?? false,
         appliesTo: toTargetKindList(input.appliesTo, existing?.appliesTo ?? ["commit"]),
         updatedAt: now,
     };
@@ -235,6 +236,17 @@ function roleAuthorized(roleId, authorizedRoles) {
         return false;
     return authorizedRoles.includes(roleId);
 }
+/** Whether `record` itself counts for anything at all (same eligibility a
+ *  record needs to be counted as an approval or a veto in the main loop
+ *  below). A record that fails this can't void another record either —
+ *  otherwise a disqualified self-approval could still cancel someone
+ *  else's veto via `supersedes`. */
+function recordCountsAtAll(record, policy, selfIds) {
+    const reason = disqualify(record, policy, selfIds);
+    if (record.decision === "reject")
+        return !reason || reason === "self-approval";
+    return !reason;
+}
 function deriveStatus(gated, required, recorded, rejectionCount, disqualified) {
     if (!gated)
         return "approved";
@@ -284,7 +296,24 @@ function deriveReviewState(runId, approvalsAll, target, options = {}) {
     const related = (options.relatedTargets && options.relatedTargets.length ? options.relatedTargets : [normalized]).map(normalizeTarget);
     const selfIds = new Set((options.selfActorIds || []).filter(Boolean));
     const approvals = approvalsAll.filter((record) => matchesAnyTarget(record.target, related));
-    const supersededIds = new Set(approvals.map((record) => record.supersedes).filter((id) => Boolean(id)));
+    // A record's `supersedes` only takes effect when the target is that SAME
+    // actor's own prior record (an actor may only supersede their own
+    // record, never someone else's) and the superseding record itself is
+    // eligible to count for something. Otherwise a disqualified record (e.g.
+    // a self-approval a policy forbids) could still void another actor's
+    // veto just by naming it in `supersedes`.
+    const byId = new Map(approvals.map((record) => [record.id, record]));
+    const supersededIds = new Set();
+    for (const record of approvals) {
+        if (!record.supersedes)
+            continue;
+        const target = byId.get(record.supersedes);
+        if (!target || target.actor.id !== record.actor.id)
+            continue;
+        if (!recordCountsAtAll(record, policy, selfIds))
+            continue;
+        supersededIds.add(record.supersedes);
+    }
     const gated = Boolean(policy && policy.requiredApprovals > 0 && policy.appliesTo.includes(normalized.kind));
     const required = gated ? policy.requiredApprovals : 0;
     const counted = [];

package/dist/core/multi-agent/runtime.js

@@ -651,6 +651,13 @@ function collectAgentFanin(run, input, now) {
         ...missingRoleIds.map((roleId) => `required role ${roleId} has no membership`),
         ...missingMembershipIds.map((membershipId) => `membership ${membershipId} has not reported required evidence`),
     ];
+    // An aggregation gate that observed zero members must not report itself
+    // ready: with no required roles and no memberships every per-item check
+    // above is vacuously empty, which used to yield verifierReady:true for a
+    // fan-in over nothing (fail-open).
+    if (!requiredRoleIds.length && !scopedMemberships.length) {
+        blockedReasons.push("fan-in has no memberships and no required roles — nothing to aggregate");
+    }
     const requiredMemberships = scopedMemberships.filter((membership) => requiredRoleIds.includes(membership.roleId));
     const blackboardId = input.blackboardId || group.blackboardId || multiAgentRun.blackboardId;
     const requiresBlackboardEvidence = Boolean(blackboardId || requiredMemberships.some((membership) => membership.blackboardId));

package/dist/core/multi-agent/trust-policy.js

@@ -168,9 +168,15 @@ function evaluatePolicy(policy, operation, topicId, evidenceRefs) {
     }
     const missing = missingEvidence(policy, operation, evidenceRefs);
     if (missing.length)
-        return `operation ${operation} requires evidence refs: ${missing.join(", ")}`;
+        return `operation ${operation} requires evidence refs (at least one; expected kinds: ${missing.join(", ")})`;
     return undefined;
 }
+/** The requiredEvidenceFor entries are prose descriptions ("judge
+ *  messages", "score evidence"), not machine-matchable ids — so this can
+ *  only check that SOME evidence ref was supplied, not that each named
+ *  kind is present. The denial message above says exactly that ("at least
+ *  one; expected kinds: ...") rather than promising a per-item match this
+ *  check cannot do. */
 function missingEvidence(policy, operation, evidenceRefs) {
     if (!policy)
         return [];

package/dist/core/pipeline/contract.js

@@ -71,6 +71,13 @@ function createDefaultPipelineContract() {
             },
         ],
         artifactPolicy: { root: ".cw/runs/<run-id>", requireReadablePaths: true },
+        // highPriorityRequiresEvidence is carried for byte-compat with the old
+        // build's default contract (pinned by SPEC/pipeline-run.md) but is NOT
+        // enforced anywhere — no gate reads it, and core has no task-priority
+        // concept to key it on. The enforced contract-wide flag is
+        // `requireEvidence` (state-node.ts assertRequiredEvidence, runner.ts
+        // evidenceSatisfied). The per-stage `requiredEvidence` lists are what
+        // actually gate evidence in the default contract.
         evidencePolicy: { highPriorityRequiresEvidence: true },
         failurePolicy: { preserveFailureNodes: true, retryableByDefault: false },
         commitPolicy: { requiresVerifierGate: true, acceptedVerifierStatuses: ["verified"] },

package/dist/core/pipeline/error-feedback.js

@@ -85,10 +85,10 @@ function sourceFor(classification) {
         return "contract";
     return "manual";
 }
-/** Feedback dedup key: joined with `` (runId, code, message, nodeId,
+/** Feedback dedup key: joined with the ASCII unit separator "\u001f" (runId, code, message, nodeId,
  *  stageId, contractId, path). */
 function feedbackKey(value) {
-    return [value.runId || "", value.code || "", value.message || "", value.nodeId || "", value.stageId || "", value.contractId || "", value.path || ""].join("");
+    return [value.runId || "", value.code || "", value.message || "", value.nodeId || "", value.stageId || "", value.contractId || "", value.path || ""].join("\u001f");
 }
 function compactMetadata(metadata) {
     const compacted = {};

package/dist/core/state/run-paths.js

@@ -1,10 +1,9 @@
 "use strict";
-// core/state/run-paths.ts — createRunPaths, ensureRunDirs.
+// core/state/run-paths.ts — pure RunPaths construction.
 //
 // MILESTONE 3. Byte-exact port of the old build's src/state.ts:10-50.
-// `createRunPaths` is pure path math (core/); `ensureRunDirs` touches disk
-// (mkdirSync) so it lives here but is called from shell/run-store.ts, the
-// only place that actually creates a run directory tree.
+// `createRunPaths` is pure path math. The directory write mechanism lives in
+// shell/run-store.ts.
 //
 // Evidence: SPEC/state-core.md "src/state.ts — persistence kernel" and "The
 // full .cw/runs/<run-id>/ layout".
@@ -43,8 +42,6 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRunPaths = createRunPaths;
-exports.ensureRunDirs = ensureRunDirs;
-const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 /** The 16-key RunPaths object, all joined under `runDir`. */
 function createRunPaths(runDir) {
@@ -67,27 +64,3 @@ function createRunPaths(runDir) {
         topologiesDir: path.join(runDir, "topologies"),
     };
 }
-/** `mkdirSync` (recursive) every dir this run needs. Missing optional dir
- *  fields fall back to `path.join(runDir, "<name>")`, matching the old
- *  build's defensive default (a RunPaths loaded from an old/partial
- *  state.json may be missing an optional key). */
-function ensureRunDirs(paths) {
-    const dirs = [
-        paths.runDir,
-        paths.tasksDir,
-        paths.resultsDir,
-        paths.dispatchesDir,
-        paths.artifactsDir,
-        paths.commitsDir,
-        paths.stateNodesDir,
-        paths.feedbackDir,
-        paths.auditDir || path.join(paths.runDir, "audit"),
-        paths.workersDir || path.join(paths.runDir, "workers"),
-        paths.candidatesDir || path.join(paths.runDir, "candidates"),
-        paths.multiAgentDir || path.join(paths.runDir, "multi-agent"),
-        paths.blackboardDir || path.join(paths.runDir, "blackboard"),
-        paths.topologiesDir || path.join(paths.runDir, "topologies"),
-    ];
-    for (const dir of dirs)
-        fs.mkdirSync(dir, { recursive: true });
-}

package/dist/core/trust/evidence-grounding.js

@@ -116,8 +116,13 @@ function extractEvidenceContent(locator, baseDirs, ops, readFile) {
     const shape = classify(locator);
     if (shape.kind !== "file" || !shape.pathPart)
         return undefined;
-    const lineMatch = locator.match(/:(\d+)$/);
+    // Match the same shapes LINE_SUFFIX_RE (classify) accepts: ":<n>" and
+    // ":<n>-<m>". A range that only matched classify used to fall through to
+    // the head-of-file slice below — returning bytes that had nothing to do
+    // with the cited lines.
+    const lineMatch = locator.match(/:(\d+)(?:-(\d+))?$/);
     const lineNum = lineMatch ? Number(lineMatch[1]) : undefined;
+    const lineEnd = lineMatch && lineMatch[2] ? Number(lineMatch[2]) : undefined;
     const candidatePath = ops.isAbsolute(shape.pathPart)
         ? shape.pathPart
         : baseDirs.filter(Boolean).map((base) => ops.resolve(base, shape.pathPart)).find((p) => ops.exists(p));
@@ -128,6 +133,13 @@ function extractEvidenceContent(locator, baseDirs, ops, readFile) {
         return undefined;
     if (lineNum && lineNum > 0) {
         const lines = content.split("\n");
+        if (lineEnd !== undefined) {
+            // Range: return exactly the cited lines; a backwards or out-of-range
+            // span returns undefined, never fabricated content.
+            if (lineEnd < lineNum || lineNum > lines.length)
+                return undefined;
+            return lines.slice(lineNum - 1, Math.min(lineEnd, lines.length)).join("\n") || undefined;
+        }
         return lines[lineNum - 1] || undefined;
     }
     return content.slice(0, 200);

package/dist/core/util/cli-args.js

@@ -16,6 +16,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.required = required;
 exports.optionalArg = optionalArg;
 exports.wantsJson = wantsJson;
+exports.parseBoolFlag = parseBoolFlag;
 /** Require a positional/option value or fail with a copy-pasteable recovery tip. */
 function required(value, label) {
     if (!value) {
@@ -31,3 +32,24 @@ function optionalArg(value) {
 function wantsJson(options) {
     return Boolean(options.json || options.format === "json");
 }
+/** Parse a boolean flag value that may arrive as a real boolean (bare
+ *  `--flag`) or as a CLI/MCP string (`--flag false`). `Boolean("false")` is
+ *  `true` in JS, so a plain Boolean() coercion silently ENABLES a flag the
+ *  operator asked to turn off — on a gate-policy flag like
+ *  `--allow-self-approval false` that is a fail-open. Recognized strings
+ *  (case-insensitive, trimmed): true/1/yes/on and false/0/no/off/"".
+ *  Anything else throws — fail closed, never guess. `undefined` and JSON
+ *  `null` (an MCP caller's "unset") stay `undefined` so a caller's
+ *  `?? existing ?? default` chain still governs an unset flag. */
+function parseBoolFlag(value, label) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "boolean")
+        return value;
+    const text = String(value).trim().toLowerCase();
+    if (text === "true" || text === "1" || text === "yes" || text === "on")
+        return true;
+    if (text === "false" || text === "0" || text === "no" || text === "off" || text === "")
+        return false;
+    throw new Error(`Invalid boolean value for ${label}: "${String(value)}" (use true or false)`);
+}

package/dist/core/version.js

@@ -7,7 +7,7 @@ exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = exports.LEGACY_RUN_STATE_SCHEMA
 // `cw version` output does not change bytes just because the code under it
 // was rebuilt. See SPEC/cli-surface.md "Exact outputs > Version" and
 // conformance/cases/version-basic.case.js (regex `/^\d+\.\d+\.\d+\n$/`).
-exports.CURRENT_COOL_WORKFLOW_VERSION = "0.2.4";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.2.6";
 // State-kernel schema version constants (SPEC/state-core.md "Version
 // constants"). Pinned to the old build's src/version.ts byte-for-byte.
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;

package/dist/mcp/dispatch.js

@@ -81,6 +81,22 @@ function requiredToolArguments(name, value) {
     }
     return args;
 }
+/** MCP clients send JSON, so an argument the CLI would receive as a string
+ *  can arrive as a number or boolean (e.g. `{"runId": 5}`). Every capability
+ *  handler coerces its args through optionalString/numberArg/boolArg, all of
+ *  which expect the CLI's string form — optionalString silently DROPS a
+ *  number, so `{"runId": 5}` used to look like "no runId given" and returned
+ *  a success-shaped WRONG answer (the "create a run first" payload). Coerce
+ *  top-level scalars to their string form so an MCP arg behaves exactly like
+ *  the CLI's argv, which is always strings. Arrays/objects (e.g.
+ *  authorizedRoles) pass through untouched; null/undefined stay absent. */
+function coerceScalarArgs(args) {
+    const out = {};
+    for (const [key, value] of Object.entries(args)) {
+        out[key] = typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" ? String(value) : value;
+    }
+    return out;
+}
 /** `callTool(name, args)` — resolves `cwd` (SPEC/mcp.md invariant 7),
  *  checks required args, then calls the row's `mcp.handler`. Throws
  *  `Unknown tool: <name>` for a name with no row (src/mcp/tool-call.ts:513
@@ -90,12 +106,16 @@ function callTool(name, rawArgs) {
     if (!row || !row.mcp) {
         throw new Error(`Unknown tool: ${name}`);
     }
-    const args = requiredToolArguments(name, rawArgs);
+    const args = coerceScalarArgs(requiredToolArguments(name, rawArgs));
     const resolvedArgs = { ...args };
     const cwdInput = args.cwd;
     if (typeof cwdInput === "string" && cwdInput.length > 0) {
         const resolved = path.resolve(cwdInput);
-        if (!fs.statSync(resolved).isDirectory()) {
+        // throwIfNoEntry:false so a MISSING cwd yields the same crafted
+        // "not a directory" message as a non-dir path — not a raw ENOENT that
+        // gives the recovery-hint matcher nothing to key on.
+        const stat = fs.statSync(resolved, { throwIfNoEntry: false });
+        if (!stat || !stat.isDirectory()) {
             throw new Error(`MCP cwd is not a directory: ${resolved}`);
         }
         resolvedArgs.cwd = resolved;