cool-workflow 0.2.3 → 0.2.5

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)." },
@@ -257,8 +586,8 @@ exports.MCP_TOOL_DATA = [
     { tool: "cw_sched_reset", capability: "sched.reset", requiredArgs: [], properties: ["cwd", "id"], description: "Reset a parked entry to ready (operator recovery)." },
     { tool: "cw_sched_policy_show", capability: "sched.policy.show", requiredArgs: [], properties: ["cwd"], description: "Show the scheduling policy (file or default)." },
     { tool: "cw_sched_policy_set", capability: "sched.policy.set", requiredArgs: [], properties: ["cwd", "maxConcurrent", "maxAttempts", "leaseTtlMs", "backoffBaseMs", "backoffFactor", "backoffCapMs"], description: "Set scheduling policy fields (concurrency/attempts/backoff/TTL)." },
-    { tool: "cw_gc_plan", capability: "gc.plan", requiredArgs: [], properties: ["cwd", "scope", "runId", "reclaimAfterArchiveDays", "keepScratch", "keepSnapshots"], description: "Dry-run plan of run reclamation (per-kind bytes + capability downgrade); frees nothing." },
-    { tool: "cw_gc_run", capability: "gc.run", requiredArgs: [], properties: ["cwd", "scope", "runId", "reclaimAfterArchiveDays", "keepScratch", "keepSnapshots", "limit", "actor"], description: "Execute the write-ahead reclamation transaction (skeleton -> tombstone -> fsync -> free)." },
+    { tool: "cw_gc_plan", capability: "gc.plan", requiredArgs: [], properties: ["cwd", "scope", "runId", "reclaimAfterArchiveDays", "keepScratch", "keepSnapshots", "keepCommits"], description: "Dry-run plan of run reclamation (per-kind bytes + capability downgrade); frees nothing." },
+    { tool: "cw_gc_run", capability: "gc.run", requiredArgs: [], properties: ["cwd", "scope", "runId", "reclaimAfterArchiveDays", "keepScratch", "keepSnapshots", "keepCommits", "limit", "actor"], description: "Execute the write-ahead reclamation transaction (skeleton -> tombstone -> fsync -> free)." },
     { tool: "cw_gc_verify", capability: "gc.verify", requiredArgs: ["runId"], properties: ["cwd", "scope", "runId"], description: "Re-prove a reclaimed run: skeleton-complete, tombstone chain untampered, artifacts reconstructable." },
     { tool: "cw_clones_list", capability: "clones.list", requiredArgs: [], properties: [], description: "List the cached remote-source checkouts that --link/URL reviews populate (origin URL, kind, commit, age, bytes). Read-only." },
     { tool: "cw_clones_gc", capability: "clones.gc", requiredArgs: [], properties: ["olderThanDays", "all"], description: "Reclaim cached remote-source checkouts: a TTL sweep (--older-than-days, default 30) or --all. Deletes only inside the clones cache." },

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).
@@ -228,7 +229,12 @@ const COMMAND_HELP_ROWS = {
  *  capability-table rows that now support `--json`/`--format json`
  *  (io.ts's wantsJson) — the flag existed but was never documented here —
  *  and for a `--quiet` Flags row, a new CLI spelling of the existing
- *  CW_DRIVE_PROGRESS=0 env var (see cli/entry.ts). */
+ *  CW_DRIVE_PROGRESS=0 env var (see cli/entry.ts); and for a `--resume`
+ *  Flags row (architecture-review-driven fix), documenting the existing
+ *  `--resume --run <id>` continuation flag (shell/pipeline-cli.ts's
+ *  quickstartRun) that previously existed only in code comments and an
+ *  auto-generated continue hint — a user who never happened to type it
+ *  first had no way to discover it via `cw help`. */
 function formatHelp() {
     const moreCommandsLines = wrapPipeJoined(exports.MORE_COMMANDS_TOKENS, MORE_COMMANDS_WRAP_WIDTH);
     const lines = [
@@ -247,12 +253,14 @@ 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",
         "  --no-color             Disable ANSI color (also honors NO_COLOR / FORCE_COLOR)",
         "  --json                 Print JSON for commands that support it",
         "  --quiet                Suppress [drive] progress lines (not agent output)",
+        "  --resume --run <id>    Continue an interrupted run to completion",
         "",
         "More commands",
         ...moreCommandsLines,
@@ -270,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)
@@ -287,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
@@ -354,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;
+}