cool-workflow 0.2.4 → 0.2.5

package/dist/cli/entry.js

@@ -15,7 +15,7 @@
 // so byte content there is unaffected; cli-color-env.case.js exercises
 // the FORCE_COLOR/NO_COLOR/CW_NO_COLOR branches explicitly.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.recoveryHint = recoveryHint;
+exports.recoveryHint = void 0;
 exports.runCli = runCli;
 exports.main = main;
 const parseargv_1 = require("./parseargv");
@@ -25,6 +25,13 @@ const parseargv_2 = require("./parseargv");
 const capability_table_1 = require("../core/capability-table");
 const term_1 = require("../shell/term");
 const io_1 = require("./io");
+const recovery_hint_1 = require("../core/format/recovery-hint");
+// recoveryHint now lives in core/format/recovery-hint.ts (a core/-layer
+// file, so mcp/server.ts can use it too without crossing the mcp/-may-
+// never-import-cli/ layer rule). Re-exported here so every existing
+// importer of `recoveryHint` from this file keeps working unchanged.
+var recovery_hint_2 = require("../core/format/recovery-hint");
+Object.defineProperty(exports, "recoveryHint", { enumerable: true, get: function () { return recovery_hint_2.recoveryHint; } });
 /** MILESTONE 2: `version` is now a pure projection of the capability
  *  table's `version` row — there is exactly one place its print text
  *  lives (core/capability-table.ts's cli handler), not a second
@@ -39,23 +46,6 @@ function printVersion() {
     const result = row?.cli?.handler({ positionals: [], options: {} });
     process.stdout.write(result?.text ?? "");
 }
-/** src/cli.ts:18-29 — map a top-level error message to ONE copy-pasteable
- *  recovery command. Content-based so it stays correct regardless of which
- *  call site threw; returns undefined rather than a wrong guess. */
-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";
-    return undefined;
-}
 async function runCli(argv = process.argv.slice(2)) {
     const args = (0, parseargv_1.parseArgv)(argv);
     // Top-level flags: accept --version / -v / --help / -h before command lookup.
@@ -77,6 +67,8 @@ async function runCli(argv = process.argv.slice(2)) {
         args.options["agent-command"] = "builtin:codex";
     if (args.options.gemini)
         args.options["agent-command"] = "builtin:gemini";
+    if (args.options.opencode)
+        args.options["agent-command"] = "builtin:opencode";
     if (args.options.deepseek)
         args.options["agent-command"] = "builtin:deepseek";
     // -dir / --dir / -d is a second name for --repo; an explicit --repo wins
@@ -152,7 +144,7 @@ function main(argv = process.argv.slice(2)) {
             return;
         const message = error instanceof Error ? error.message : String(error);
         process.stderr.write(`${(0, term_1.bold)("cw:", process.stderr)} ${(0, term_1.red)(message, process.stderr)}\n`);
-        const hint = recoveryHint(message);
+        const hint = (0, recovery_hint_1.recoveryHint)(message);
         if (hint)
             process.stderr.write(`  ${(0, term_1.dim)("Try:", process.stderr)} ${hint}\n`);
         process.exitCode = 1;

package/dist/cli/global-flags.js

@@ -0,0 +1,113 @@
+"use strict";
+// cli/global-flags.ts — the shared global CLI flag set, plus the TTY-gated
+// unknown-flag warning for capability rows that declare `flagsComplete`
+// (core/capability-data.ts's CliBinding).
+//
+// WHY: an unknown flag used to be dropped without a sound — `cw doctor
+// --jsno` ran fine, printed the human report, and exited 0, so a typo of
+// `--json` was easy to miss. A full allowlist check for EVERY command is
+// not safe (a missed name means a FALSE warning, and many scripted and
+// conformance callers assert stderr === ""), so the design here is
+// incremental and fail-open:
+//   - only a row that declares `flagsComplete: true` is ever checked, and
+//     a row earns that mark only after its handler's option reads have
+//     been checked against source, one by one;
+//   - the warning is ONE line to stderr, printed ONLY when stderr is a
+//     real interactive terminal (same injectable-stream gate as
+//     shell/workbench-host.ts's printServeHint) — a piped, scripted, or
+//     conformance run can never see it;
+//   - stdout bytes and the exit code never change.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GLOBAL_CLI_FLAGS = void 0;
+exports.unknownFlagKeys = unknownFlagKeys;
+exports.warnUnknownFlags = warnUnknownFlags;
+/** Every option key the shared CLI front door reads for ANY command, so a
+ *  `flagsComplete` row's check never flags them. Built by reading the
+ *  actual consumers:
+ *   - cli/entry.ts: `version`/`v`, `help`/`h`, the vendor shorthands
+ *     `claude`/`codex`/`gemini`/`deepseek` (each sets `agent-command`),
+ *     `repo`/`dir` (`--dir`/`-d` is a global alias for `--repo`),
+ *     `verbose`, `no-color`, `full`, `quiet`, `question` (`-q`), and the
+ *     `--resume --run <id>` continuation pair;
+ *   - cli/dispatch.ts + core/util/cli-args.ts's wantsJson: `json`,
+ *     `format`;
+ *   - cli/parseargv.ts's short-alias table: `link` (`-l`),
+ *     `agent-command` (`-a`) — the short spellings map to these long
+ *     names before any handler sees them;
+ *   - the doctor/fix handlers' shared working-dir override: `cwd`.
+ *  Keys are the POST-parse spellings (what lands in `args.options`). */
+exports.GLOBAL_CLI_FLAGS = [
+    "agent-command",
+    "claude",
+    "codex",
+    "cwd",
+    "deepseek",
+    "dir",
+    "format",
+    "full",
+    "gemini",
+    "h",
+    "help",
+    "json",
+    "link",
+    "no-color",
+    "question",
+    "quiet",
+    "repo",
+    "resume",
+    "run",
+    "v",
+    "verbose",
+    "version",
+];
+/** "changed-from" -> "changedFrom". A name with no dash comes back as-is. */
+function kebabToCamel(name) {
+    return name.replace(/-([a-z0-9])/g, (_, ch) => ch.toUpperCase());
+}
+/** "changedFrom" -> "changed-from". A name with no capitals comes back as-is. */
+function camelToKebab(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** The option key a declared flag help entry documents: the first token
+ *  of its display name, without the leading dashes ("--changed-from REF"
+ *  -> "changed-from"). */
+function flagNameToKey(name) {
+    return name.trim().split(/\s+/)[0].replace(/^-+/, "");
+}
+/** The full accepted-key set for one row: the row's declared flags plus
+ *  the global set, each in BOTH its kebab-case and camelCase spelling. */
+function knownKeysFor(cli) {
+    const known = new Set();
+    const add = (key) => {
+        known.add(key);
+        known.add(kebabToCamel(key));
+        known.add(camelToKebab(key));
+    };
+    for (const name of exports.GLOBAL_CLI_FLAGS)
+        add(name);
+    for (const flag of cli.flags ?? [])
+        add(flagNameToKey(flag.name));
+    return known;
+}
+/** The option keys this row does not know about (pure; exported for unit
+ *  tests). Empty unless the row declares `flagsComplete`. */
+function unknownFlagKeys(cli, options) {
+    if (!cli.flagsComplete)
+        return [];
+    const known = knownKeysFor(cli);
+    return Object.keys(options).filter((key) => !known.has(key));
+}
+/** Write ONE warning line to `stream` when a `flagsComplete` row got an
+ *  option it does not read — and only when the stream is a real TTY, so
+ *  no piped caller, script, or conformance case can ever see it. stdout
+ *  and the exit code are untouched either way. */
+function warnUnknownFlags(cli, options, stream = process.stderr) {
+    if (!stream.isTTY)
+        return;
+    const unknown = unknownFlagKeys(cli, options);
+    if (unknown.length === 0)
+        return;
+    const label = unknown.length === 1 ? "flag" : "flags";
+    const list = unknown.map((key) => `--${key}`).join(", ");
+    stream.write(`cw: warning: unknown ${label} ${list} (see: cw help ${cli.path[0]})\n`);
+}

package/dist/cli/parseargv.js

@@ -140,13 +140,19 @@ function levenshtein(a, b) {
 }
 /** src/orchestrator.ts:875-887 — nearest known command by edit distance.
  *  Gives `undefined` when the input is under 2 chars, or when the best
- *  distance is over 3 or over half the input length. */
+ *  distance is over 3 or over half the input length. Never gives back the
+ *  input itself: a caller only asks for a suggestion when the input did
+ *  NOT resolve, so a distance-0 self-match (an alias token like
+ *  `audit-run` that IS in KNOWN_COMMANDS but has no help rows of its own)
+ *  was a hint that pointed at the very thing the user just typed. */
 function suggestCommand(input) {
     if (!input || input.length < 2)
         return undefined;
     let best;
     let bestDistance = Infinity;
     for (const candidate of exports.KNOWN_COMMANDS) {
+        if (candidate === input)
+            continue;
         const distance = levenshtein(input, candidate);
         if (distance < bestDistance) {
             bestDistance = distance;

package/dist/core/capability-data.js

@@ -33,7 +33,7 @@
 // capability is APPENDED after the transcript's last row (never inserted),
 // so every existing position keeps its pinned order.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MCP_TOOL_DATA = exports.PROPERTY_OVERRIDES = exports.CapabilityNotImplementedError = void 0;
+exports.MCP_TOOL_DATA = exports.MCP_TOOL_ANNOTATIONS = exports.COMMON_PROPERTY_TYPES = exports.PROPERTY_OVERRIDES = exports.CapabilityNotImplementedError = void 0;
 exports.notYetImplemented = notYetImplemented;
 exports.stringProperty = stringProperty;
 /** Thrown by every not-yet-wired MCP tool handler. Never hit by this
@@ -55,8 +55,9 @@ function stringProperty(name) {
     return { type: "string", description: name };
 }
 /** SPEC/mcp.md's two hand-written property-shape exceptions (see that
- *  file's "All 196 MCP tools" section header note): every OTHER property
- *  on every OTHER tool is the plain string form above. */
+ *  file's "All 196 MCP tools" section header note): these two properties
+ *  win over `COMMON_PROPERTY_TYPES` below, since each is a one-off shape
+ *  tied to its own tool, not a shape shared by the property name at large. */
 exports.PROPERTY_OVERRIDES = {
     cw_commit: {
         allowUnverifiedCheckpoint: {
@@ -68,11 +69,339 @@ exports.PROPERTY_OVERRIDES = {
         payload: { type: "object", description: "Event payload" },
     },
 };
+/** A real type and a true, short, one-sentence description for every
+ *  property name used anywhere in `MCP_TOOL_DATA` below, keyed by the
+ *  PROPERTY NAME (not the tool name) — the same name means the same
+ *  thing on every tool that uses it. `mcpToolDefinitions()` in
+ *  wiring/capability-table/registry-core.ts looks a property up here
+ *  only when `PROPERTY_OVERRIDES` has no entry for it on that tool; a
+ *  name not found in either table falls back to the plain
+ *  `stringProperty` form (there should be very few of those — the two
+ *  names left out here, `allowUnverifiedCheckpoint` and `payload`, are
+ *  already covered by `PROPERTY_OVERRIDES` on their one tool each). */
+exports.COMMON_PROPERTY_TYPES = {
+    action: { type: "string", description: "which action to run" },
+    actor: { type: "string", description: "the name of the actor doing this" },
+    actorKind: { type: "string", description: "the kind of actor, such as agent or human" },
+    agentCommand: { type: "string", description: "the command template used to run the agent" },
+    agentEndpoint: { type: "string", description: "the network address of the agent service" },
+    agentModel: { type: "string", description: "the name of the agent model to use" },
+    all: { type: "boolean", description: "when true, act on every item, not only old ones" },
+    allowSelfApproval: { type: "boolean", description: "when true, let an actor approve their own work" },
+    allowUnverified: { type: "boolean", description: "when true, skip the check that needs a verifier" },
+    app: { type: "string", description: "the workflow app's id" },
+    appId: { type: "string", description: "the workflow app's id" },
+    appliesTo: { type: "string", description: "what this policy rule applies to" },
+    archive: { type: "string", description: "the path to the run archive file" },
+    artifact: { type: "object", description: "an artifact reference to attach as proof" },
+    attestation: { type: "string", description: "the attestation text or id for this actor" },
+    attested: { type: "boolean", description: "when true, mark the actor as host-attested" },
+    authorizedRoles: { type: "array", description: "the list of role names allowed to approve" },
+    backend: { type: "string", description: "the name of the execution backend" },
+    backendId: { type: "string", description: "the id of the execution backend" },
+    backoffBaseMs: { type: "number", description: "the starting wait time, in milliseconds, before a retry" },
+    backoffCapMs: { type: "number", description: "the largest wait time, in milliseconds, before a retry" },
+    backoffFactor: { type: "number", description: "the number the wait time is multiplied by after each retry" },
+    baseline: { type: "string", description: "the baseline snapshot's id" },
+    baselinePath: { type: "string", description: "the file path to the baseline snapshot" },
+    baselineSnapshotId: { type: "string", description: "the id of the baseline snapshot" },
+    blackboardId: { type: "string", description: "the id of the blackboard" },
+    body: { type: "string", description: "the text body of the message" },
+    bundle: { type: "string", description: "the path to the run bundle file" },
+    by: { type: "string", description: "the name of the actor who did this" },
+    candidate: { type: "string", description: "the candidate's id" },
+    candidateId: { type: "string", description: "the candidate's id" },
+    candidateSnapshotId: { type: "string", description: "the id of the candidate snapshot" },
+    code: { type: "string", description: "a short error or status code" },
+    collectInitialFanin: { type: "boolean", description: "when true, collect the first fan-in step right away" },
+    command: { type: "string", description: "the command that was run or checked" },
+    commit: { type: "string", description: "the commit's id" },
+    commitId: { type: "string", description: "the commit's id" },
+    concurrency: { type: "number", description: "the largest number of steps to run at once" },
+    contract: { type: "string", description: "the pipeline contract's id" },
+    contractId: { type: "string", description: "the pipeline contract's id" },
+    criteria: { type: "array", description: "the list of scoring criteria" },
+    criterion: { type: "string", description: "one scoring criterion's name" },
+    cron: { type: "string", description: "the cron schedule text" },
+    cwd: { type: "string", description: "the working directory to run in" },
+    debateRounds: { type: "number", description: "the number of debate rounds to run" },
+    delayMinutes: { type: "number", description: "the number of minutes to wait before the task runs" },
+    depth: { type: "number", description: "how many levels deep to read" },
+    description: { type: "string", description: "a short text that describes this item" },
+    diff: { type: "string", description: "the change text (diff) for this proposal" },
+    dir: { type: "string", description: "the path to one ledger directory" },
+    directory: { type: "string", description: "the directory path to write into" },
+    dirs: { type: "array", description: "the list of ledger directory paths" },
+    dispatchId: { type: "string", description: "the id of the dispatch record" },
+    displayName: { type: "string", description: "the actor's human-readable name" },
+    entry: { type: "string", description: "the ledger entry to check" },
+    env: { type: "object", description: "the environment variables for this step" },
+    evidence: { type: "array", description: "the list of evidence items backing this claim" },
+    expectCount: { type: "number", description: "the event count the chain must match" },
+    expectHead: { type: "string", description: "the head hash the chain must match" },
+    expectedArtifact: { type: "string", description: "the artifact this role is expected to produce" },
+    extractReport: { type: "boolean", description: "when true, also pull the plain report out of the bundle" },
+    failed: { type: "boolean", description: "when true, mark the lease as failed" },
+    faninId: { type: "string", description: "the id of the fan-in record" },
+    faninObligation: { type: "string", description: "what this role must supply at fan-in time" },
+    fanoutId: { type: "string", description: "the id of the fan-out record" },
+    feedbackId: { type: "string", description: "the id of the feedback record" },
+    file: { type: "string", description: "the path to the archive file" },
+    files: { type: "array", description: "the list of file paths this change touches" },
+    findings: { type: "array", description: "the list of review findings" },
+    focus: { type: "string", description: "the node id to center the view on" },
+    from: { type: "string", description: "the actor this comes from" },
+    groupId: { type: "string", description: "the id of the agent group" },
+    hostEnforced: { type: "boolean", description: "when true, the host, not the agent, enforced the sandbox rule" },
+    id: { type: "string", description: "the id of this item" },
+    includeArchived: { type: "boolean", description: "when true, also list archived runs" },
+    includeRejected: { type: "boolean", description: "when true, also list rejected candidates" },
+    inputs: { type: "object", description: "the structured input values for the app" },
+    intervalMinutes: { type: "number", description: "how often, in minutes, the task should repeat" },
+    judgeCount: { type: "number", description: "the number of judge agents to use" },
+    keepCommits: { type: "number", description: "the number of recent commits to keep" },
+    keepScratch: { type: "boolean", description: "when true, keep scratch files instead of freeing them" },
+    keepSnapshots: { type: "number", description: "the number of recent snapshots to keep" },
+    key: { type: "string", description: "the context frame's key" },
+    kind: { type: "string", description: "the kind of this item" },
+    leaseId: { type: "string", description: "the id of the queue lease" },
+    leaseTtlMs: { type: "number", description: "how long, in milliseconds, a lease stays valid" },
+    limit: { type: "number", description: "the largest number of items to return" },
+    locator: { type: "string", description: "where to find the artifact (a path or url)" },
+    mapperCount: { type: "number", description: "the number of mapper agents to use" },
+    match: { type: "string", description: "the text pattern used to match trigger events" },
+    max: { type: "number", description: "the largest allowed score" },
+    maxAttempts: { type: "number", description: "the largest number of retry attempts allowed" },
+    maxConcurrent: { type: "number", description: "the largest number of runs allowed at once" },
+    maxTotal: { type: "number", description: "the largest total score allowed" },
+    membershipId: { type: "string", description: "the id of the agent membership record" },
+    message: { type: "string", description: "the message text" },
+    minAgeMinutes: { type: "number", description: "the least age, in minutes, an item must have" },
+    minNormalized: { type: "number", description: "the least normalized score a candidate must have" },
+    multiAgentRun: { type: "string", description: "the multi-agent run's id" },
+    multiAgentRunId: { type: "string", description: "the multi-agent run's id" },
+    network: { type: "string", description: "the network access rule that was checked" },
+    node: { type: "string", description: "the state node's id" },
+    nodeId: { type: "string", description: "the state node's id" },
+    note: { type: "string", description: "a short free-text note" },
+    notes: { type: "string", description: "free-text notes about this score" },
+    now: { type: "string", description: "the time to treat as \"now\", for a stable, repeatable result" },
+    objective: { type: "string", description: "the goal text for this multi-agent run" },
+    offset: { type: "number", description: "how many items to skip before returning results" },
+    olderThanDays: { type: "number", description: "the least age, in days, an item must have" },
+    once: { type: "boolean", description: "when true, run only one step, then stop" },
+    outcome: { type: "string", description: "the decision's outcome" },
+    output: { type: "string", description: "the output file path to write" },
+    parent: { type: "string", description: "the id of the parent item this replies to" },
+    path: { type: "string", description: "a file path" },
+    phase: { type: "string", description: "the phase name for this agent group" },
+    port: { type: "number", description: "the network port to use" },
+    pricing: { type: "string", description: "the pricing table to use for cost figures" },
+    priority: { type: "number", description: "the queue order priority" },
+    profileFile: { type: "string", description: "the path to the sandbox profile file" },
+    profileId: { type: "string", description: "the id of the sandbox profile" },
+    prompt: { type: "string", description: "the prompt text for this task" },
+    pubkey: { type: "string", description: "the public key used to check a signature" },
+    question: { type: "string", description: "the question that starts the run" },
+    rationale: { type: "string", description: "the reason behind this decision" },
+    reason: { type: "string", description: "a short text that explains why" },
+    reclaimAfterArchiveDays: { type: "number", description: "how many days after archive before a run can be freed" },
+    refresh: { type: "boolean", description: "when true, rebuild the result instead of reading a cached one" },
+    replay: { type: "string", description: "the replay's id" },
+    replayId: { type: "string", description: "the replay's id" },
+    replayPath: { type: "string", description: "the file path to the replay" },
+    replyTo: { type: "string", description: "the id of the message this replies to" },
+    repo: { type: "string", description: "the path to the repo" },
+    requireAttestedActor: { type: "boolean", description: "when true, only let an attested actor approve" },
+    requireEvidence: { type: "boolean", description: "when true, require evidence before a candidate can rank" },
+    requireToken: { type: "boolean", description: "when true, require a token to reach the host" },
+    requireVerifierGate: { type: "boolean", description: "when true, require the verifier gate to pass first" },
+    requiredApprovals: { type: "number", description: "the number of approvals a target needs" },
+    requiredEvidence: { type: "array", description: "the list of evidence kinds this role must supply" },
+    requiredRole: { type: "string", description: "the role name that must be present at fan-in" },
+    responsibility: { type: "string", description: "what this role is responsible for" },
+    resultNode: { type: "string", description: "the id of the node holding the result" },
+    resultPath: { type: "string", description: "the file path to the result" },
+    retryable: { type: "boolean", description: "when true, mark this failure as safe to retry" },
+    role: { type: "string", description: "the actor's role name" },
+    roleId: { type: "string", description: "the agent role's id" },
+    runId: { type: "string", description: "the run's id" },
+    sandbox: { type: "string", description: "the sandbox profile choice" },
+    sandboxChoice: { type: "string", description: "the sandbox profile choice" },
+    sandboxProfile: { type: "string", description: "the sandbox profile's id" },
+    sandboxProfileHint: { type: "string", description: "a hint for which sandbox profile this role should use" },
+    sandboxProfileId: { type: "string", description: "the sandbox profile's id" },
+    scope: { type: "string", description: "which repos to search, such as this repo or all repos" },
+    score: { type: "string", description: "the score's id" },
+    scoreId: { type: "string", description: "the score's id" },
+    scorer: { type: "string", description: "the name of the actor giving this score" },
+    selectedBy: { type: "string", description: "the actor who made the selection" },
+    selection: { type: "string", description: "the selection's id" },
+    since: { type: "string", description: "the start of the time range to search" },
+    snapshot: { type: "string", description: "the snapshot's id" },
+    snapshotId: { type: "string", description: "the snapshot's id" },
+    source: { type: "string", description: "where this artifact came from" },
+    state: { type: "string", description: "the run state to check or set" },
+    status: { type: "string", description: "the status to filter or set" },
+    strategy: { type: "string", description: "the strategy used to collect fan-in" },
+    strictSignatures: { type: "boolean", description: "when true, fail closed if a signature cannot be checked" },
+    subject: { type: "string", description: "the subject of this decision" },
+    suite: { type: "string", description: "the eval suite's id" },
+    suiteId: { type: "string", description: "the eval suite's id" },
+    supersedes: { type: "string", description: "the id of the earlier item this replaces" },
+    tag: { type: "string", description: "a short label for this topic" },
+    target: { type: "string", description: "the id of the target this acts on" },
+    targetId: { type: "string", description: "the id of the target this acts on" },
+    targetKind: { type: "string", description: "the kind of the target, such as candidate or commit" },
+    task: { type: "string", description: "the task text or id" },
+    taskId: { type: "string", description: "the task's id" },
+    text: { type: "string", description: "free-text search terms" },
+    thread: { type: "string", description: "the id of the comment thread" },
+    tieBreaker: { type: "string", description: "the rule used to break a tie between candidates" },
+    title: { type: "string", description: "a short title for this item" },
+    to: { type: "string", description: "the actor this is handed to" },
+    toRole: { type: "string", description: "the role this is handed to" },
+    topic: { type: "string", description: "the blackboard topic's id" },
+    topicId: { type: "string", description: "the blackboard topic's id" },
+    topology: { type: "string", description: "the topology definition's id" },
+    topologyId: { type: "string", description: "the topology definition's id" },
+    topologyRunId: { type: "string", description: "the id of the topology run" },
+    trustKey: { type: "string", description: "the trust key used to seal the run" },
+    unarchive: { type: "boolean", description: "when true, undo an archive mark instead of setting one" },
+    until: { type: "string", description: "the end of the time range to search" },
+    value: { type: "string", description: "the value to store in this context frame" },
+    verdict: { type: "string", description: "the review verdict" },
+    verifier: { type: "string", description: "the name of the verifier" },
+    verifierNode: { type: "string", description: "the id of the node holding the verifier result" },
+    verify: { type: "boolean", description: "when true, also verify the result after this step" },
+    view: { type: "string", description: "which view of the data to return" },
+    visibility: { type: "string", description: "who can see this message" },
+    withTrustKey: { type: "boolean", description: "when true, seal the output with the trust key" },
+    worker: { type: "string", description: "the worker's id" },
+    workerId: { type: "string", description: "the worker's id" },
+    workflow: { type: "string", description: "the workflow definition's id" },
+    workflowId: { type: "string", description: "the workflow definition's id" },
+    write: { type: "boolean", description: "when true, save the result instead of only reading it" },
+};
+/** Behavior hints per MCP tool name, surfaced as the standard MCP
+ *  `annotations` field on each `tools/list` entry. A side table (like
+ *  `MCP_REAL_HANDLERS` in wiring/capability-table/registry-core.ts) so
+ *  `MCP_TOOL_DATA` below stays a pure transcript of the spec table.
+ *
+ *  The rule for this table is strict, because a wrong hint is a safety
+ *  bug (a client may skip its confirmation step for a "read-only" tool):
+ *   - `readOnlyHint: true` ONLY for a tool whose handler was read and
+ *     seen to do no write at all (no saveCheckpoint, no writeJson, no
+ *     writeReport, no fs write of any kind);
+ *   - `destructiveHint: true` for a tool whose handler was read and seen
+ *     to delete stored data (gc / delete sweeps);
+ *   - every other tool is ABSENT from this table and gets no
+ *     annotations. Absent beats wrong. Some absences that look like
+ *     reads are deliberate: cw_metrics_show persists its derived report,
+ *     cw_workbench_view calls the metrics.show handler for one panel,
+ *     cw_operator_report re-writes report.md, cw_schedule_due marks
+ *     expired tasks, cw_run_resume can take the opt-in --drive path, and
+ *     cw_multi_agent_reasoning can take the opt-in refresh path. */
+exports.MCP_TOOL_ANNOTATIONS = {
+    // pure reads, in MCP_TOOL_DATA order (each handler checked by hand)
+    cw_list: { readOnlyHint: true },
+    cw_status: { readOnlyHint: true },
+    cw_next: { readOnlyHint: true },
+    cw_contract_show: { readOnlyHint: true },
+    cw_node_list: { readOnlyHint: true },
+    cw_node_show: { readOnlyHint: true },
+    cw_node_graph: { readOnlyHint: true },
+    cw_migration_list: { readOnlyHint: true },
+    cw_operator_status: { readOnlyHint: true },
+    cw_operator_graph: { readOnlyHint: true },
+    cw_worker_summary: { readOnlyHint: true },
+    cw_candidate_summary: { readOnlyHint: true },
+    cw_feedback_summary: { readOnlyHint: true },
+    cw_commit_summary: { readOnlyHint: true },
+    cw_multi_agent_summary: { readOnlyHint: true },
+    cw_multi_agent_graph: { readOnlyHint: true },
+    cw_multi_agent_dependencies: { readOnlyHint: true },
+    cw_multi_agent_failures: { readOnlyHint: true },
+    cw_multi_agent_evidence: { readOnlyHint: true },
+    cw_summary_show: { readOnlyHint: true },
+    cw_blackboard_summarize: { readOnlyHint: true },
+    cw_multi_agent_summarize: { readOnlyHint: true },
+    cw_multi_agent_graph_compact: { readOnlyHint: true },
+    cw_multi_agent_status: { readOnlyHint: true },
+    cw_multi_agent_run_show: { readOnlyHint: true },
+    cw_topology_list: { readOnlyHint: true },
+    cw_topology_show: { readOnlyHint: true },
+    cw_topology_validate: { readOnlyHint: true },
+    cw_topology_summary: { readOnlyHint: true },
+    cw_topology_graph: { readOnlyHint: true },
+    cw_blackboard_summary: { readOnlyHint: true },
+    cw_blackboard_graph: { readOnlyHint: true },
+    cw_blackboard_message_list: { readOnlyHint: true },
+    cw_blackboard_artifact_list: { readOnlyHint: true },
+    cw_coordinator_summary: { readOnlyHint: true },
+    cw_audit_summary: { readOnlyHint: true },
+    cw_audit_verify: { readOnlyHint: true },
+    cw_audit_worker: { readOnlyHint: true },
+    cw_audit_provenance: { readOnlyHint: true },
+    cw_audit_multi_agent: { readOnlyHint: true },
+    cw_audit_policy: { readOnlyHint: true },
+    cw_audit_role: { readOnlyHint: true },
+    cw_audit_blackboard: { readOnlyHint: true },
+    cw_audit_judge: { readOnlyHint: true },
+    cw_sandbox_list: { readOnlyHint: true },
+    cw_sandbox_show: { readOnlyHint: true },
+    cw_sandbox_validate: { readOnlyHint: true },
+    cw_backend_list: { readOnlyHint: true },
+    cw_backend_show: { readOnlyHint: true },
+    cw_backend_agent_config_show: { readOnlyHint: true },
+    cw_app_list: { readOnlyHint: true },
+    cw_app_show: { readOnlyHint: true },
+    cw_app_validate: { readOnlyHint: true },
+    cw_worker_list: { readOnlyHint: true },
+    cw_worker_show: { readOnlyHint: true },
+    cw_candidate_list: { readOnlyHint: true },
+    cw_candidate_show: { readOnlyHint: true },
+    cw_comment_list: { readOnlyHint: true },
+    cw_review_status: { readOnlyHint: true },
+    cw_feedback_list: { readOnlyHint: true },
+    cw_feedback_show: { readOnlyHint: true },
+    cw_ledger_verify: { readOnlyHint: true },
+    cw_ledger_apply: { readOnlyHint: true },
+    cw_ledger_list: { readOnlyHint: true },
+    cw_schedule_list: { readOnlyHint: true },
+    cw_schedule_history: { readOnlyHint: true },
+    cw_routine_list: { readOnlyHint: true },
+    cw_routine_events: { readOnlyHint: true },
+    cw_registry_show: { readOnlyHint: true },
+    cw_metrics_summary: { readOnlyHint: true },
+    cw_run_search: { readOnlyHint: true },
+    cw_run_list: { readOnlyHint: true },
+    cw_run_show: { readOnlyHint: true },
+    cw_run_inspect_archive: { readOnlyHint: true },
+    cw_run_drive: { readOnlyHint: true },
+    cw_queue_list: { readOnlyHint: true },
+    cw_queue_show: { readOnlyHint: true },
+    cw_sched_plan: { readOnlyHint: true },
+    cw_sched_policy_show: { readOnlyHint: true },
+    cw_gc_plan: { readOnlyHint: true },
+    cw_gc_verify: { readOnlyHint: true },
+    cw_clones_list: { readOnlyHint: true },
+    cw_orphans_list: { readOnlyHint: true },
+    cw_telemetry_verify: { readOnlyHint: true },
+    cw_history: { readOnlyHint: true },
+    cw_audit_head: { readOnlyHint: true },
+    // delete sweeps (each handler checked by hand: all delete stored data)
+    cw_schedule_delete: { readOnlyHint: false, destructiveHint: true },
+    cw_routine_delete: { readOnlyHint: false, destructiveHint: true },
+    cw_gc_run: { readOnlyHint: false, destructiveHint: true },
+    cw_clones_gc: { readOnlyHint: false, destructiveHint: true },
+    cw_orphans_gc: { readOnlyHint: false, destructiveHint: true },
+};
 exports.MCP_TOOL_DATA = [
     { tool: "cw_list", capability: "list", requiredArgs: [], properties: [], description: "List bundled CW workflows." },
     { tool: "cw_plan", capability: "plan", requiredArgs: ["workflowId"], properties: ["workflowId", "repo", "question"], description: "Create a CW run and return its canonical plan summary." },
     { tool: "cw_app_run", capability: "app.run", requiredArgs: ["appId"], properties: ["cwd", "appId", "inputs", "sandbox", "sandboxProfile", "sandboxProfileId"], description: "Create a run from an app id + structured inputs." },
-    { tool: "cw_status", capability: "status", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read run checkpoint status." },
+    { tool: "cw_status", capability: "status", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read run checkpoint status. The quick first check on one run: lifecycle, task counts, and next actions. For the fuller operator view use cw_operator_status; for every panel in one call use cw_workbench_view." },
     { tool: "cw_init", capability: "init", requiredArgs: ["workflowId"], properties: ["workflowId", "title", "output"], description: "Scaffold a new workflow definition." },
     { tool: "cw_next", capability: "next", requiredArgs: ["runId"], properties: ["runId", "cwd", "limit"], description: "Read the next recommended tasks for a run." },
     { tool: "cw_state_check", capability: "state.check", requiredArgs: ["runId"], properties: ["runId", "cwd", "state", "write"], description: "Check run-state schema compatibility." },
@@ -87,11 +416,11 @@ exports.MCP_TOOL_DATA = [
     { tool: "cw_migration_list", capability: "migration.list", requiredArgs: [], properties: [], description: "List the declared migration registry." },
     { tool: "cw_migration_check", capability: "migration.check", requiredArgs: [], properties: ["target", "contract", "cwd"], description: "Dry-run migration verdict for a target." },
     { tool: "cw_migration_prove", capability: "migration.prove", requiredArgs: [], properties: ["target", "contract", "cwd"], description: "Round-trip / non-destruction migration proof for a target." },
-    { tool: "cw_operator_status", capability: "operator.status", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read the structured Operator UX run status." },
+    { tool: "cw_operator_status", capability: "operator.status", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read the structured Operator UX run status. Fuller than cw_status: workers, candidates, feedback, and commits in one operator view. For every panel in one call use cw_workbench_view; for agent-topology detail use cw_multi_agent_status." },
     { tool: "cw_operator_graph", capability: "graph", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read the structured Operator UX run graph." },
     { tool: "cw_operator_report", capability: "operator.report", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Refresh and read the structured Operator UX report summary." },
     { tool: "cw_worker_summary", capability: "worker.summary", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read the structured worker summary for a run." },
-    { tool: "cw_workbench_view", capability: "workbench.view", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read the read-only five-panel Workbench view of one run (graph, blackboard, worker, candidate, audit)." },
+    { tool: "cw_workbench_view", capability: "workbench.view", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read the read-only five-panel Workbench view of one run (graph, blackboard, worker, candidate, audit). The widest one-call overview; prefer it when you want everything at once. For one quick answer use cw_status or cw_operator_status instead." },
     { tool: "cw_workbench_serve", capability: "workbench.serve", requiredArgs: [], properties: ["cwd", "port", "scope", "requireToken"], description: "Describe/serve the optional localhost-only, read-only Workbench host. requireToken is a CLI-only opt-in (the MCP path never actually binds, so it is a no-op here)." },
     { tool: "cw_candidate_summary", capability: "candidate.summary", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read the structured candidate summary for a run." },
     { tool: "cw_feedback_summary", capability: "feedback.summary", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read the structured feedback summary for a run." },
@@ -109,7 +438,7 @@ exports.MCP_TOOL_DATA = [
     { tool: "cw_multi_agent_summarize", capability: "multi-agent.summarize", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read the combined state-explosion report." },
     { tool: "cw_multi_agent_graph_compact", capability: "multi-agent.graph.compact", requiredArgs: ["runId"], properties: ["runId", "cwd", "view", "focus", "depth"], description: "Read a compact/focused multi-agent graph view." },
     { tool: "cw_multi_agent_run", capability: "multi-agent.run", requiredArgs: [], properties: ["runId", "cwd", "app", "appId", "workflow", "workflowId", "topology", "topologyId", "task", "mapperCount", "judgeCount", "debateRounds"], description: "Create or attach a topology-backed multi-agent run." },
-    { tool: "cw_multi_agent_status", capability: "multi-agent.status", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read combined topology/blackboard/worker status." },
+    { tool: "cw_multi_agent_status", capability: "multi-agent.status", requiredArgs: ["runId"], properties: ["runId", "cwd"], description: "Read combined topology/blackboard/worker status. Best for a multi-agent run: what each agent group is doing and what is blocked. For a plain run use cw_status; for every panel in one call use cw_workbench_view." },
     { tool: "cw_multi_agent_step", capability: "multi-agent.step", requiredArgs: ["runId"], properties: ["runId", "cwd", "sandbox", "backend", "limit"], description: "Perform one safe deterministic host step." },
     { tool: "cw_multi_agent_blackboard", capability: "multi-agent.blackboard", requiredArgs: ["runId"], properties: ["runId", "cwd", "action", "blackboardId", "topicId", "body", "kind", "path", "evidence"], description: "Operate on the active multi-agent blackboard." },
     { tool: "cw_multi_agent_score", capability: "multi-agent.score", requiredArgs: ["runId"], properties: ["runId", "cwd", "candidate", "candidateId", "worker", "criterion", "criteria", "evidence", "maxTotal"], description: "Score a candidate with evidence." },
@@ -168,7 +497,7 @@ exports.MCP_TOOL_DATA = [
     { tool: "cw_sandbox_show", capability: "sandbox.show", requiredArgs: ["profileId"], properties: ["cwd", "profileId"], description: "Show a resolved sandbox profile." },
     { tool: "cw_sandbox_validate", capability: "sandbox.validate", requiredArgs: ["profileFile"], properties: ["cwd", "profileFile"], description: "Validate a sandbox profile JSON file." },
     { tool: "cw_sandbox_choose", capability: "sandbox.choose", requiredArgs: [], properties: ["cwd", "profileId", "sandbox", "sandboxProfile", "sandboxProfileId"], description: "Resolve and validate a sandbox profile choice." },
-    { tool: "cw_sandbox_resolve", capability: "sandbox.resolve", requiredArgs: [], properties: ["cwd", "profileId", "sandbox", "sandboxProfile", "sandboxProfileId"], description: "Alias of sandbox.choose." },
+    { tool: "cw_sandbox_resolve", capability: "sandbox.resolve", requiredArgs: [], properties: ["cwd", "profileId", "sandbox", "sandboxProfile", "sandboxProfileId"], description: "Alias of sandbox.choose: a pure alias with the same input and the same output. Prefer cw_sandbox_choose." },
     { tool: "cw_backend_list", capability: "backend.list", requiredArgs: [], properties: ["cwd"], description: "List available execution backends and their capabilities." },
     { tool: "cw_backend_show", capability: "backend.show", requiredArgs: [], properties: ["cwd", "backendId"], description: "Show one execution backend descriptor." },
     { tool: "cw_backend_probe", capability: "backend.probe", requiredArgs: [], properties: ["cwd", "backendId"], description: "Probe execution backend readiness (live, deterministic)." },