cool-workflow 0.2.4 → 0.2.5

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/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.5";
 // 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;

package/dist/mcp/server.js

@@ -7,8 +7,11 @@
 // "Invariants and error behavior" #9 / "Edge cases" sections:
 //   - transport: stdin/stdout, ONE JSON object per line, no
 //     Content-Length headers (mcp.md:13);
-//   - `initialize` -> protocolVersion/capabilities/serverInfo, ignoring
-//     params (mcp.md:19,263-269);
+//   - `initialize` -> protocolVersion/capabilities/serverInfo (mcp.md:
+//     19,263-269); the reply's protocolVersion echoes the client's
+//     requested one when it is in SUPPORTED_PROTOCOL_VERSIONS below, and
+//     falls back to the newest supported entry otherwise (with today's
+//     one-entry list this is byte-identical to the old fixed reply);
 //   - `tools/list` -> { tools: [...] } from core/capability-table.ts via
 //     mcp/dispatch.ts, ignoring params (mcp.md:20,271-277);
 //   - `tools/call` -> { content: [{ type: "text", text: <2-space pretty
@@ -48,12 +51,40 @@
 //     blow V8's per-string limit) becomes a small overflow notice instead
 //     of a multi-hundred-MB payload — every result under the cap is
 //     untouched, so this never affects the parity gate's own fixtures.
+//   - `tools/call` FAILURE result shape (post-v0.2.4 robustness hardening,
+//     not in the original mcp.md): an unknown tool name, a missing
+//     required tool argument, or the tool's own handler throwing is a
+//     normal RESULT, not a bare -32000 JSON-RPC protocol error — many MCP
+//     hosts never surface a protocol error back to the calling model, so
+//     it could not read the message or try again. The result is shaped
+//     { content: [{ type: "text", text: <message, plus a "Try: <hint>"
+//     line when core/format/recovery-hint.ts's recoveryHint finds one>
+//     }], isError: true }, same `resultMessage` helper as the success
+//     path. The envelope-level "missing field: name" check (right above
+//     this bullet) is unchanged — it still answers -32000.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.negotiateProtocolVersion = negotiateProtocolVersion;
 exports.startServer = startServer;
 const version_1 = require("../core/version");
 const safe_json_1 = require("../core/format/safe-json");
+const recovery_hint_1 = require("../core/format/recovery-hint");
 const dispatch_1 = require("./dispatch");
 const MAX_LINE_BYTES = 16 * 1024 * 1024;
+/** Protocol versions this server can speak, oldest first. `initialize`
+ *  echoes the client's `params.protocolVersion` when it is in this list,
+ *  and answers with the newest entry (the last one) otherwise — the
+ *  standard MCP version-negotiation shape. With one entry this is
+ *  behavior-identical to the old hard-coded reply (mechanism first; a
+ *  second version is a one-line append here). */
+const SUPPORTED_PROTOCOL_VERSIONS = ["2024-11-05"];
+/** Picks the `initialize` reply's protocolVersion from the client's
+ *  requested one (see SUPPORTED_PROTOCOL_VERSIONS). Exported for the
+ *  protocol-version smoke; pure. */
+function negotiateProtocolVersion(requested) {
+    if (typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested))
+        return requested;
+    return SUPPORTED_PROTOCOL_VERSIONS[SUPPORTED_PROTOCOL_VERSIONS.length - 1];
+}
 // Tools whose result carries free-form text ORIGINALLY AUTHORED by a
 // worker/agent/operator/external caller — never computed or validated by
 // this codebase itself (a blackboard message body, a review comment, a
@@ -117,6 +148,11 @@ function resultMessage(id, result) {
     if (id !== undefined)
         message.id = id;
     return message;
+    // NOTE: a notification-shaped request (initialize/tools/list/tools/call
+    // with no `id`) still gets a reply here, just without an `id` key — a
+    // deliberate deviation from strict JSON-RPC (which says a notification
+    // MUST NOT be answered) pinned by SPEC/mcp.md's edge-cases. Revisit only
+    // as a deliberate spec change, not as a drive-by fix.
 }
 /** Handles one already-parsed JSON-RPC request object. May write zero or
  *  one reply line to stdout. `await`ing callTool's result is a no-op for
@@ -142,8 +178,9 @@ async function handleRequest(message) {
     try {
         switch (message.method) {
             case "initialize": {
+                const params = (message.params ?? {});
                 writeMessage(resultMessage(id, {
-                    protocolVersion: "2024-11-05",
+                    protocolVersion: negotiateProtocolVersion(params.protocolVersion),
                     capabilities: { tools: {} },
                     serverInfo: { name: "cool-workflow", version: version_1.CURRENT_COOL_WORKFLOW_VERSION },
                 }));
@@ -153,6 +190,17 @@ async function handleRequest(message) {
                 writeMessage(resultMessage(id, { tools: (0, dispatch_1.toolDefinitions)() }));
                 return;
             }
+            case "ping": {
+                // MCP (2024-11-05, the version negotiateProtocolVersion advertises)
+                // makes ping mandatory: reply promptly with an EMPTY result. Hosts
+                // ping for keep-alive and may drop a connection that never answers.
+                // Answered here in the fast protocol path (not the serial tool
+                // queue), so a ping during a long cw_run drive still gets a reply.
+                // A ping notification (no id) gets no reply, per JSON-RPC.
+                if (hasId)
+                    writeMessage(resultMessage(id, {}));
+                return;
+            }
             case "tools/call": {
                 const params = message.params ?? {};
                 const name = params.name;
@@ -160,12 +208,32 @@ async function handleRequest(message) {
                     throw new Error("MCP tools/call missing required field: name");
                 }
                 const args = params.arguments;
-                const coreResult = await (0, dispatch_1.callTool)(name, args ?? {});
-                const content = [{ type: "text", text: (0, safe_json_1.safeJsonStringify)(coreResult) }];
-                const advisory = untrustedContentAdvisory(name);
-                if (advisory)
-                    content.push({ type: "text", text: advisory });
-                writeMessage(resultMessage(id, { content }));
+                // A failure from HERE down (an unknown tool name, a missing
+                // required tool argument, or the tool's own handler throwing) is a
+                // normal call outcome, not a broken request — many MCP hosts never
+                // surface a bare JSON-RPC protocol error (-32000) back to the
+                // calling model at all, so it could not see the message and try
+                // again. Answer with a normal RESULT instead, shaped isError:
+                // true, so the model always sees the message (and, when one
+                // applies, a "Try: <hint>" recovery line) and can self-correct.
+                // The envelope-level "missing field: name" check above stays OUT
+                // of this inner try/catch — that one is a malformed request, not
+                // a tool-call outcome, and keeps going through the outer
+                // try/catch as a -32000 error, unchanged.
+                try {
+                    const coreResult = await (0, dispatch_1.callTool)(name, args ?? {});
+                    const content = [{ type: "text", text: (0, safe_json_1.safeJsonStringify)(coreResult) }];
+                    const advisory = untrustedContentAdvisory(name);
+                    if (advisory)
+                        content.push({ type: "text", text: advisory });
+                    writeMessage(resultMessage(id, { content }));
+                }
+                catch (error) {
+                    const text = error instanceof Error ? error.message : String(error);
+                    const hint = (0, recovery_hint_1.recoveryHint)(text);
+                    const errorText = hint ? `${text}\nTry: ${hint}` : text;
+                    writeMessage(resultMessage(id, { content: [{ type: "text", text: errorText }], isError: true }));
+                }
                 return;
             }
             default: {
@@ -205,14 +273,52 @@ async function handleLine(line) {
  *  tool but `cw_run` is still a plain synchronous handler), so this adds
  *  no real delay, but it keeps replies in the same order the requests
  *  arrived even now that one tool (`cw_run`'s live drive loop) can take
- *  many real event-loop turns to answer. */
+ *  many real event-loop turns to answer. The one exception is `ping`,
+ *  answered in handleRequest's fast path before any tool work, so a
+ *  keep-alive ping still gets a reply while a long drive holds the queue. */
 function startServer() {
     process.stdin.setEncoding("utf8");
     let buffer = "";
+    // True while the REST of an oversize line is still streaming in: emit one
+    // -32700 for the whole line and skip everything up to its terminating
+    // newline, instead of dropping the head and then re-parsing the tail as a
+    // fresh (also-failing) line — which produced a second, spurious parse
+    // error per 16MB crossed.
+    let discarding = false;
     let queue = Promise.resolve();
+    // Chain each task onto `queue` WITH a per-task `.catch`. The `.catch` is
+    // load-bearing, not decoration: a task here can reject — a raw
+    // `writeMessage` (`process.stdout.write`) that throws mid-reply because the
+    // client closed the pipe, or any other throw out of handleLine — and
+    // without a handler that one rejection would leave `queue` REJECTED for
+    // good, so every later `queue.then(...)` is skipped and the server goes
+    // silent and answers no more requests (finding: one bad write poisons the
+    // queue). The `.catch` swallows the single failure onto stderr
+    // (diagnostics, never stdout data) and hands back a RESOLVED promise, so
+    // the next request is still served. Order is still kept: the next task
+    // only runs after this one settles.
+    const enqueue = (task) => {
+        queue = queue.then(task).catch((error) => {
+            const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+            process.stderr.write(`cool-workflow mcp: a request failed and its reply was dropped; still serving: ${detail}\n`);
+        });
+    };
     process.stdin.on("data", (chunk) => {
         buffer += chunk;
         for (;;) {
+            if (discarding) {
+                // Skip the rest of an oversize line already reported. Until its
+                // terminating newline arrives, throw away what we have (so a huge
+                // line can't grow the buffer unboundedly); once found, resume
+                // normal parsing from the next line with no second error.
+                const nl = buffer.indexOf("\n");
+                if (nl === -1) {
+                    buffer = "";
+                    break;
+                }
+                buffer = buffer.slice(nl + 1);
+                discarding = false;
+            }
             const newlineIndex = buffer.indexOf("\n");
             if (newlineIndex === -1)
                 break;
@@ -220,11 +326,16 @@ function startServer() {
             buffer = buffer.slice(newlineIndex + 1);
             const trimmed = line.trim();
             if (trimmed)
-                queue = queue.then(() => handleLine(trimmed));
+                enqueue(() => handleLine(trimmed));
         }
-        if (buffer.length > MAX_LINE_BYTES) {
+        // No newline yet and the pending (unterminated) line already exceeds the
+        // cap: report ONCE, drop the head, and discard the rest of this line
+        // until its newline arrives (guarded by `discarding` so a >32MB line
+        // yields a single -32700, not one per 16MB crossed).
+        if (!discarding && buffer.length > MAX_LINE_BYTES) {
             buffer = "";
-            queue = queue.then(() => {
+            discarding = true;
+            enqueue(() => {
                 writeMessage(errorMessage(null, -32700, `Parse error: request line exceeds ${MAX_LINE_BYTES} bytes`));
             });
         }

package/dist/mcp-server.js

@@ -6,4 +6,24 @@
 // real MCP client launches it directly with `node`).
 Object.defineProperty(exports, "__esModule", { value: true });
 const server_1 = require("./mcp/server");
+/** Broken-pipe guard for the MCP stdio server, the same idea as
+ *  cli/entry.ts's `main()`. When an MCP client closes the read end of our
+ *  stdout part-way through a reply, the raw write gives an async 'error'
+ *  event that no promise `.catch` can see; with no listener Node comes down
+ *  hard with a `write EPIPE` stack and exit 1. One process-level listener
+ *  turns that into a quiet exit 0 — the reader has gone, there is nothing
+ *  left to say. Any other stream error is thrown again, same as before.
+ *
+ *  This is a small COPY of cli/entry.ts's helper, not an import: the purity
+ *  gate (scripts/purity-gate.js) forbids an mcp/ file from importing cli/,
+ *  and pulling in the whole CLI entry graph for five lines would be worse. */
+function exitQuietOnEpipe(stream) {
+    stream.on("error", (error) => {
+        if (error && error.code === "EPIPE")
+            process.exit(0);
+        throw error;
+    });
+}
+exitQuietOnEpipe(process.stdout);
+exitQuietOnEpipe(process.stderr);
 (0, server_1.startServer)();