cool-workflow 0.2.2 → 0.2.3

package/dist/shell/trust-audit.js

@@ -60,6 +60,7 @@ exports.trustAuditGenesis = trustAuditGenesis;
 exports.listTrustAuditEvents = listTrustAuditEvents;
 exports.trustAuditHead = trustAuditHead;
 exports.verifyTrustAudit = verifyTrustAudit;
+exports.repairTrustAuditTornTail = repairTrustAuditTornTail;
 exports.recordTrustAuditEvent = recordTrustAuditEvent;
 exports.recordSandboxPathDecision = recordSandboxPathDecision;
 exports.normalizeEvidence = normalizeEvidence;
@@ -106,6 +107,43 @@ function computeEventHash(event) {
     void eventHash;
     return (0, hash_1.sha256)((0, hash_1.eventHashInput)(rest));
 }
+function tailCachePathFor(eventLogPath) {
+    return path.join(path.dirname(eventLogPath), "tail-cache.json");
+}
+function readAuditTailCache(tailCachePath) {
+    if (!fs.existsSync(tailCachePath))
+        return undefined;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(tailCachePath, "utf8"));
+        if (parsed && parsed.schemaVersion === 1 && typeof parsed.logBytes === "number" && typeof parsed.count === "number" && typeof parsed.lastHash === "string") {
+            return parsed;
+        }
+    }
+    catch {
+        // Corrupt/unreadable cache -- fall back to the full parse below.
+    }
+    return undefined;
+}
+function writeAuditTailCache(tailCachePath, cache) {
+    try {
+        (0, fs_atomic_1.writeJson)(tailCachePath, cache);
+    }
+    catch {
+        // Best-effort: a failed cache write must never break the real append.
+    }
+}
+/** Deletes the tail cache so the NEXT append always re-derives ground
+ *  truth from the real log, rather than trusting a byte-size coincidence.
+ *  Called whenever something OTHER than a plain append changes the log's
+ *  content (currently: repair). */
+function invalidateAuditTailCache(eventLogPath) {
+    try {
+        fs.unlinkSync(tailCachePathFor(eventLogPath));
+    }
+    catch {
+        // Nothing to invalidate (no cache existed yet) -- fine.
+    }
+}
 /** Read events in FILE (append) order, tolerating corrupt lines — one
  *  bad line must not brick the whole audit read surface (it is counted,
  *  not thrown). The chain links append order, so this is the order
@@ -170,16 +208,17 @@ function trustAuditHead(run) {
  *  the hash after each event) must contain `expectHead`, and the log
  *  must reach `expectCount` events; a shortfall fails closed with
  *  `trust-audit-truncated`. Without an anchor, behavior is unchanged. */
-function verifyTrustAudit(run, anchor) {
-    const audit = ensureTrustAudit(run);
-    const { events, corruptLines } = readEventsRawCounted(audit.eventLogPath);
+/** Chain-walk core shared by `verifyTrustAudit` (reads from disk) and
+ *  `repairTrustAuditTornTail` (re-checks an in-memory candidate result
+ *  BEFORE ever writing it to disk). Pure — no fs. */
+function verifyEventsChain(runId, events, corruptLines, anchor) {
     const checks = [];
     let verified = corruptLines === 0;
     if (corruptLines > 0)
         checks.push({ name: "parse", pass: false, code: "trust-audit-corrupt-line" });
     let chained = 0;
     let unchained = 0;
-    let expectedPrev = trustAuditGenesis(run.id);
+    let expectedPrev = trustAuditGenesis(runId);
     const headTrail = new Set([expectedPrev]);
     for (let i = 0; i < events.length; i++) {
         const event = events[i];
@@ -195,7 +234,11 @@ function verifyTrustAudit(run, anchor) {
             verified = false;
             checks.push({ name: `event-hash[${i}]`, pass: false, code: "trust-audit-digest-mismatch" });
         }
-        if (event.prevEventHash !== undefined && event.prevEventHash !== expectedPrev) {
+        // No `undefined` skip here: the writer ALWAYS sets prevEventHash (the
+        // first event gets the genesis hash), so a chained event without it is
+        // a forgery — dropping the field and re-making eventHash must NOT let a
+        // cut or re-ordered chain verify green. Fail closed on the mismatch.
+        if (event.prevEventHash !== expectedPrev) {
             verified = false;
             checks.push({ name: `chain-link[${i}]`, pass: false, code: "trust-audit-chain-broken" });
         }
@@ -223,6 +266,94 @@ function verifyTrustAudit(run, anchor) {
     }
     return { present: events.length > 0, verified, eventCount: events.length, chained, unchained, corruptLines, checks };
 }
+function verifyTrustAudit(run, anchor) {
+    const audit = ensureTrustAudit(run);
+    const { events, corruptLines } = readEventsRawCounted(audit.eventLogPath);
+    return verifyEventsChain(run.id, events, corruptLines, anchor);
+}
+/** Repairs a torn TRAILING write in the audit event log — the ONE
+ *  corruption shape a crash mid-append can produce (`durableAppendFileSync`
+ *  only ever adds bytes at the current end of file, so an interruption can
+ *  only ever leave the LAST append incomplete; it can never touch earlier,
+ *  already-flushed lines). Every line is always actually parsed — the
+ *  file's trailing-newline byte says only whether the LAST WRITE
+ *  completed, nothing about whether any line parses: if a run is RESUMED
+ *  after a torn write (another event appended right after the garbled
+ *  remnant, with no separating newline of its own), the two merge into one
+ *  unparseable line and the file ends in a newline again, even though
+ *  content is still corrupt. Refuses (`outcome: "refused"`) rather than
+ *  touching anything when:
+ *   - more than one line is unparseable, or the sole bad line is NOT the
+ *     last one (not a shape a crash can produce — treated as possible
+ *     tampering, not auto-repaired);
+ *   - removing the bad trailing line still leaves an unverifiable chain,
+ *     OR (when `anchor` is given) the repaired chain doesn't reach
+ *     `anchor.expectCount`/contain `anchor.expectHead` — an anchor
+ *     captured before the corruption is the ONLY way to catch an attacker
+ *     deleting real historical events and leaving a torn-looking fragment
+ *     behind (an empty/short chain otherwise "verifies" trivially — the
+ *     same documented blind spot `verifyTrustAudit` itself has without an
+ *     anchor; this function must never launder that shape into a
+ *     confidently-"repaired" empty log).
+ *  `write: false` (default) reports what WOULD happen without touching
+ *  disk, matching this codebase's `cw state check [--write]` convention.
+ *  Held under the SAME `withFileLock` as `recordTrustAuditEvent` (below),
+ *  so a repair can never interleave with a live append. */
+function repairTrustAuditTornTail(run, options = {}) {
+    const audit = ensureTrustAudit(run);
+    return (0, fs_atomic_1.withFileLock)(audit.eventLogPath, () => {
+        const raw = fs.readFileSync(audit.eventLogPath, "utf8");
+        const lines = raw.split("\n").filter((line) => line.trim() !== "");
+        const badIndexes = [];
+        const events = [];
+        lines.forEach((line, i) => {
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch {
+                badIndexes.push(i);
+            }
+        });
+        if (badIndexes.length === 0) {
+            return { outcome: "clean", reason: "every line parses — no torn trailing write to repair" };
+        }
+        if (badIndexes.length > 1 || badIndexes[0] !== lines.length - 1) {
+            return {
+                outcome: "refused",
+                reason: "corruption is not confined to exactly the trailing line — this is not a shape a crash mid-append can produce and will not be auto-repaired (looks like tampering)",
+            };
+        }
+        // `events` already holds every line EXCEPT the one bad trailing line
+        // (JSON.parse threw for it, so nothing was pushed) — exactly the "good"
+        // set, in file order.
+        const recheck = verifyEventsChain(run.id, events, 0, options.anchor);
+        if (!recheck.verified) {
+            return {
+                outcome: "refused",
+                reason: options.anchor
+                    ? "removing the torn trailing write still doesn't reach the given --expect-head/--expect-count anchor — refusing to repair (this looks like deleted history, not a crash)"
+                    : "removing the torn trailing write still leaves an unverifiable chain — refusing to repair (this looks like tampering, not a crash)",
+            };
+        }
+        const removedBytes = Buffer.byteLength(lines[lines.length - 1], "utf8");
+        const repairedContent = events.length > 0 ? `${lines.slice(0, -1).join("\n")}\n` : "";
+        if (options.write) {
+            (0, fs_atomic_1.writeTextDurable)(audit.eventLogPath, repairedContent, { durable: true });
+            // The log's bytes just changed out from under the append tail cache
+            // (perf cycle P1-2) -- invalidate rather than rely on the size check
+            // alone catching every case.
+            invalidateAuditTailCache(audit.eventLogPath);
+        }
+        return {
+            outcome: "repaired",
+            reason: options.write
+                ? `removed a torn trailing write (${removedBytes} bytes) and restored a verified chain of ${events.length} event(s)`
+                : `would remove a torn trailing write (${removedBytes} bytes) and restore a verified chain of ${events.length} event(s) — pass --write to apply`,
+            removedLines: 1,
+            removedBytes,
+        };
+    });
+}
 function unique(values) {
     return Array.from(new Set(values.filter(Boolean)));
 }
@@ -249,9 +380,14 @@ function scrubMetadata(value) {
 function compact(value) {
     return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
 }
-function createEventId(run, kind) {
-    const count = readEventsRaw(trustAuditPaths(run).eventLogPath).length + 1;
-    return `audit-${(0, fs_atomic_1.safeFileName)(kind)}-${String(count).padStart(4, "0")}`;
+/** `count` must be the number of PRIOR events, read under the SAME lock
+ *  the append itself happens under (see `recordTrustAuditEvent`) — an
+ *  earlier version read this count separately, outside any lock, so two
+ *  concurrent writers could mint the SAME id for two different events
+ *  (the hash chain still forked-proof, but the id — referenced elsewhere
+ *  as `auditEventIds`/`parentEventIds` for provenance — was not unique). */
+function createEventId(kind, count) {
+    return `audit-${(0, fs_atomic_1.safeFileName)(kind)}-${String(count + 1).padStart(4, "0")}`;
 }
 /** Correlation-id keys copied verbatim (and no others) — byte-exact list/
  *  order to the old build's CORRELATION_ID_FIELDS. */
@@ -294,11 +430,20 @@ function indexCorrelationIds(event) {
     }
     return picked;
 }
+/** Read-modify-append: computes `prevEventHash` from the CURRENT last event
+ *  and appends. Held under `withFileLock` (like every other read-modify-
+ *  write in this codebase) so two processes recording events for the same
+ *  run at once can never both read the same tail and compute the same
+ *  `prevEventHash` — that would fork the hash chain, and a forked chain
+ *  fails `verifyTrustAudit` for good, with no repair for THAT shape (unlike
+ *  a torn trailing write, a fork is not confined to the last line). */
 function recordTrustAuditEvent(run, input) {
     const audit = ensureTrustAudit(run);
+    // `id` is NOT set here — it depends on the prior event count, which (like
+    // prevEventHash) must be read under the lock below, or two concurrent
+    // writers could mint the same id for two different events.
     const event = compact({
         schemaVersion: exports.TRUST_AUDIT_SCHEMA_VERSION,
-        id: createEventId(run, input.kind),
         createdAt: new Date().toISOString(),
         runId: run.id,
         kind: input.kind,
@@ -322,11 +467,35 @@ function recordTrustAuditEvent(run, input) {
         parentEventIds: unique(input.parentEventIds || []).sort(),
         metadata: scrubMetadata(input.metadata || {}),
     });
-    const prior = readEventsRaw(audit.eventLogPath);
-    event.prevEventHash = prior.length ? prior[prior.length - 1].eventHash || computeEventHash(prior[prior.length - 1]) : trustAuditGenesis(run.id);
-    event.eventHash = computeEventHash(event);
-    (0, fs_atomic_1.durableAppendFileSync)(audit.eventLogPath, `${JSON.stringify(event)}\n`);
-    return event;
+    return (0, fs_atomic_1.withFileLock)(audit.eventLogPath, () => {
+        // The prior event count and last-event hash are the ONLY two things
+        // this append needs from the existing log. A tail cache (keyed on the
+        // log's own byte size) serves both without a full parse when nothing
+        // else has touched the log since it was written; any size mismatch
+        // (a repair, a torn write, this being the very first append) falls
+        // back to the full parse, same as before this cache existed.
+        const tailCachePath = tailCachePathFor(audit.eventLogPath);
+        const currentBytes = fs.existsSync(audit.eventLogPath) ? fs.statSync(audit.eventLogPath).size : 0;
+        const cached = readAuditTailCache(tailCachePath);
+        let count;
+        let prevHash;
+        if (cached && cached.logBytes === currentBytes) {
+            count = cached.count;
+            prevHash = cached.lastHash;
+        }
+        else {
+            const prior = readEventsRaw(audit.eventLogPath);
+            count = prior.length;
+            prevHash = prior.length ? prior[prior.length - 1].eventHash || computeEventHash(prior[prior.length - 1]) : trustAuditGenesis(run.id);
+        }
+        event.id = createEventId(input.kind, count);
+        event.prevEventHash = prevHash;
+        event.eventHash = computeEventHash(event);
+        const line = `${JSON.stringify(event)}\n`;
+        (0, fs_atomic_1.durableAppendFileSync)(audit.eventLogPath, line);
+        writeAuditTailCache(tailCachePath, { schemaVersion: 1, logBytes: currentBytes + Buffer.byteLength(line, "utf8"), count: count + 1, lastHash: event.eventHash });
+        return event;
+    });
 }
 function recordSandboxPathDecision(run, input) {
     return recordTrustAuditEvent(run, {
@@ -387,11 +556,32 @@ function countBy(values, key) {
  *  here — the old build's extra workers/candidates/commits/multiAgent/
  *  blackboard rollups are milestone 9's own summarizeMultiAgent/
  *  candidate-scoring-io/coordinator-io surfaces, not duplicated here. */
+/** Groups events by a key field once, so each row below is an O(1) Map
+ *  lookup instead of an O(events) `.filter()` re-scan per id -- found
+ *  alongside the id.find() version of this same shape while pinning perf
+ *  cycle P1-1's review-fix regression test (O(ids x events) otherwise). */
+function groupEventsBy(events, key) {
+    const groups = new Map();
+    for (const event of events) {
+        const k = key(event);
+        if (!k)
+            continue;
+        const list = groups.get(k);
+        if (list)
+            list.push(event);
+        else
+            groups.set(k, [event]);
+    }
+    return groups;
+}
 function workerRows(events, run) {
-    const workerIds = unique([...(run.workers || []).map((w) => w.id), ...events.map((e) => e.workerId || "")]).sort();
+    const workers = run.workers || [];
+    const workersById = new Map(workers.map((w) => [w.id, w]));
+    const eventsByWorkerId = groupEventsBy(events, (e) => e.workerId);
+    const workerIds = unique([...workers.map((w) => w.id), ...events.map((e) => e.workerId || "")]).sort();
     return workerIds.filter(Boolean).map((workerId) => {
-        const worker = (run.workers || []).find((w) => w.id === workerId);
-        const scoped = events.filter((e) => e.workerId === workerId);
+        const worker = workersById.get(workerId);
+        const scoped = eventsByWorkerId.get(workerId) || [];
         return {
             workerId,
             taskId: worker?.taskId || scoped.find((e) => e.taskId)?.taskId,
@@ -405,11 +595,21 @@ function workerRows(events, run) {
 function candidateRows(events, run) {
     const cands = run.candidates || [];
     const selectionsAll = run.candidateSelections || [];
+    const candsById = new Map(cands.map((c) => [c.id, c]));
+    const selectionsByCandidateId = new Map();
+    for (const selection of selectionsAll) {
+        const list = selectionsByCandidateId.get(selection.candidateId);
+        if (list)
+            list.push(selection);
+        else
+            selectionsByCandidateId.set(selection.candidateId, [selection]);
+    }
+    const eventsByCandidateId = groupEventsBy(events, (e) => e.candidateId);
     const ids = unique([...cands.map((c) => c.id), ...events.map((e) => e.candidateId || "")]).sort();
     return ids.filter(Boolean).map((candidateId) => {
-        const candidate = cands.find((c) => c.id === candidateId);
-        const selections = selectionsAll.filter((s) => s.candidateId === candidateId);
-        const scoped = events.filter((e) => e.candidateId === candidateId);
+        const candidate = candsById.get(candidateId);
+        const selections = selectionsByCandidateId.get(candidateId) || [];
+        const scoped = eventsByCandidateId.get(candidateId) || [];
         return {
             candidateId,
             scoreIds: unique([...(candidate?.scores || []), ...scoped.map((e) => e.scoreId || "")]).filter(Boolean).sort(),
@@ -419,9 +619,11 @@ function candidateRows(events, run) {
     });
 }
 function commitRows(events, run) {
-    const ids = unique([...(run.commits || []).map((c) => c.id), ...events.map((e) => e.commitId || "")]).sort();
+    const commits = run.commits || [];
+    const commitsById = new Map(commits.map((c) => [c.id, c]));
+    const ids = unique([...commits.map((c) => c.id), ...events.map((e) => e.commitId || "")]).sort();
     return ids.filter(Boolean).map((commitId) => {
-        const commit = (run.commits || []).find((c) => c.id === commitId);
+        const commit = commitsById.get(commitId);
         return {
             commitId,
             verifierGated: Boolean(commit?.verifierGated),

package/dist/shell/trust-policy-io.js

@@ -209,7 +209,7 @@ function summarizeMultiAgentTrust(run) {
         judgeRationales: byKind("judge.rationale"),
         panelDecisions: byKind("judge.panel-decision"),
         policyViolations,
-        nextAction: policyViolations.length ? `node scripts/cw.js audit policy ${run.id}` : `node scripts/cw.js audit multi-agent ${run.id} --json`,
+        nextAction: policyViolations.length ? `cw audit policy ${run.id}` : `cw audit multi-agent ${run.id} --json`,
     };
 }
 function hasAcceptedJudgeRationale(run, input = {}) {

package/dist/shell/worker-cli.js

@@ -77,13 +77,14 @@ function workerShowCli(args) {
     return scope;
 }
 function workerManifestCli(args) {
-    const run = (0, run_store_1.loadRunFromCwd)(req(args.runId, "run id"), cwdFor(args));
-    const scope = (0, worker_isolation_1.getWorkerScope)(run, req(args.workerId, "worker id"));
-    if (!scope)
-        throw new Error(`Unknown worker for run ${run.id}: ${args.workerId}`);
-    const manifest = (0, worker_isolation_1.writeWorkerManifest)(run, scope);
-    (0, run_store_1.saveCheckpoint)(run);
-    return manifest;
+    return (0, run_store_1.withRunStateLock)(req(args.runId, "run id"), cwdFor(args), (run) => {
+        const scope = (0, worker_isolation_1.getWorkerScope)(run, req(args.workerId, "worker id"));
+        if (!scope)
+            throw new Error(`Unknown worker for run ${run.id}: ${args.workerId}`);
+        const manifest = (0, worker_isolation_1.writeWorkerManifest)(run, scope);
+        (0, run_store_1.saveCheckpoint)(run);
+        return manifest;
+    });
 }
 /** `cw worker output <run> <worker> <result>` — records the worker's result
  *  and returns the full RunSummary, a byte-behavior port of the old build's
@@ -96,37 +97,40 @@ function workerManifestCli(args) {
  *  tasks.completed, workers.byStatus, and loopStage. The drive loop does these
  *  same steps itself around the bare accept, so it never routes through here. */
 function workerOutputCli(args) {
-    const run = (0, run_store_1.loadRunFromCwd)(req(args.runId, "run id"), cwdFor(args));
-    (0, worker_isolation_1.recordWorkerOutput)(run, req(args.workerId, "worker id"), req(args.resultPath, "result file"), {
-        requireAttestedTelemetry: (0, agent_config_1.resolveAgentConfig)(args).requireAttestedTelemetry,
-        allowUnattested: allowUnattestedOption(args),
+    return (0, run_store_1.withRunStateLock)(req(args.runId, "run id"), cwdFor(args), (run) => {
+        (0, worker_isolation_1.recordWorkerOutput)(run, req(args.workerId, "worker id"), req(args.resultPath, "result file"), {
+            requireAttestedTelemetry: (0, agent_config_1.resolveAgentConfig)(args).requireAttestedTelemetry,
+            allowUnattested: allowUnattestedOption(args),
+        });
+        run.loopStage = "observe";
+        (0, dispatch_1.updatePhaseStatuses)(run);
+        (0, drive_1.maybeExpandLoop)(run);
+        (0, commit_1.commitState)(run, `worker:${req(args.workerId, "worker id")}:result`);
+        (0, report_1.writeReport)(run);
+        (0, run_store_1.saveCheckpoint)(run);
+        return (0, operator_ux_1.summarizeRun)(run);
     });
-    run.loopStage = "observe";
-    (0, dispatch_1.updatePhaseStatuses)(run);
-    (0, drive_1.maybeExpandLoop)(run);
-    (0, commit_1.commitState)(run, `worker:${req(args.workerId, "worker id")}:result`);
-    (0, report_1.writeReport)(run);
-    (0, run_store_1.saveCheckpoint)(run);
-    return (0, operator_ux_1.summarizeRun)(run);
 }
 function workerFailCli(args) {
-    const run = (0, run_store_1.loadRunFromCwd)(req(args.runId, "run id"), cwdFor(args));
-    const message = String(args.message || req(args.resultPath, "failure message"));
-    const scope = (0, worker_isolation_1.recordWorkerFailure)(run, req(args.workerId, "worker id"), message, {
-        code: typeof args.code === "string" ? args.code : undefined,
-        path: typeof args.path === "string" ? args.path : undefined,
-        retryable: args.retryable !== undefined ? Boolean(args.retryable) : undefined,
+    return (0, run_store_1.withRunStateLock)(req(args.runId, "run id"), cwdFor(args), (run) => {
+        const message = String(args.message || req(args.resultPath, "failure message"));
+        const scope = (0, worker_isolation_1.recordWorkerFailure)(run, req(args.workerId, "worker id"), message, {
+            code: typeof args.code === "string" ? args.code : undefined,
+            path: typeof args.path === "string" ? args.path : undefined,
+            retryable: args.retryable !== undefined ? Boolean(args.retryable) : undefined,
+        });
+        (0, run_store_1.saveCheckpoint)(run);
+        return scope;
     });
-    (0, run_store_1.saveCheckpoint)(run);
-    return scope;
 }
 /** validate returns the boundary violation (null when the write path is
  *  allowed) and signals a violation through a non-zero exit code, not just
  *  stdout — a validate verb must report an invalid verdict via its exit code. */
 function workerValidateCli(args) {
-    const run = (0, run_store_1.loadRunFromCwd)(req(args.runId, "run id"), cwdFor(args));
-    const target = args.path || args.resultPath;
-    const violation = (0, worker_isolation_1.validateWorkerBoundary)(run, req(args.workerId, "worker id"), target ? { path: String(target) } : {});
-    (0, run_store_1.saveCheckpoint)(run);
-    return { violation, exitCode: violation ? 1 : undefined };
+    return (0, run_store_1.withRunStateLock)(req(args.runId, "run id"), cwdFor(args), (run) => {
+        const target = args.path || args.resultPath;
+        const violation = (0, worker_isolation_1.validateWorkerBoundary)(run, req(args.workerId, "worker id"), target ? { path: String(target) } : {});
+        (0, run_store_1.saveCheckpoint)(run);
+        return { violation, exitCode: violation ? 1 : undefined };
+    });
 }

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

@@ -16,32 +16,57 @@ const registry_core_1 = require("./registry-core");
 // cli/dispatch.ts's generic executor performs the actual write.
 // ---------------------------------------------------------------------
 const version_1 = require("../../core/version");
-const workflow_app_loader_1 = require("../../shell/workflow-app-loader");
 const help_1 = require("../../core/format/help");
+const completion_1 = require("../../core/format/completion");
+const io_1 = require("../../cli/io");
+// This whole module is required unconditionally at startup for EVERY
+// command (see wiring/capability-table/index.ts) — a top-level import of
+// `shell/workflow-app-loader` here means even `cw --version` pays its
+// load cost, though only `search`'s handler ever calls it.
+function loadWorkflowAppLoader() {
+    return require("../../shell/workflow-app-loader");
+}
 (0, registry_core_1.addCliOnlyCapability)("version", "Print the current cool-workflow version.", {
     path: ["version"],
     jsonMode: "default",
     handler: () => ({ text: `${version_1.CURRENT_COOL_WORKFLOW_VERSION}\n` }),
 }, "version is a local, no-run-state print; the old build never gave it an MCP peer.");
+/** `cw completion <bash|zsh|fish>` — a static shell-completion script for
+ *  the top-level command word list (core/format/completion.ts). CLI-only:
+ *  a shell-integration script is meaningless as an MCP tool result. */
+(0, registry_core_1.addCliOnlyCapability)("completion", "Print a shell-completion script for the top-level cw commands (bash, zsh, or fish).", {
+    path: ["completion"],
+    jsonMode: "human",
+    handler: (args) => {
+        const shell = (0, io_1.optionalArg)(args.positionals[0]);
+        if (!shell)
+            throw new Error('Missing shell name.\n  Try: cw completion bash|zsh|fish');
+        return { text: (0, completion_1.formatCompletionScript)(shell) };
+    },
+}, "shell-completion output is a script for the user's OWN shell to source, not data an MCP client could use — CLI-only, same reasoning as doctor/fix.");
 /** `cw search <keyword>` — filters the SAME real app discovery `cw list`
  *  shows, by id/title/summary (byte-behavior port of cli/dispatch.ts's
  *  milestone-1 carry-over `search` arm, moved here so the dispatchLegacy
- *  switch shrinks per its file header's rule). `hiddenFromHelp` keeps it
- *  out of the per-verb help listing exactly as before (it never had one —
- *  `search` only ever appeared in formatHelp's hard-coded "More commands"
- *  index line, which this row does not touch), so `cw help search` keeps
- *  its existing "Unknown command: search" text. */
+ *  switch shrinks per its file header's rule). The old v0.1.98 CLI DID
+ *  have its own `cw help search` row (`docs/rebuild/SPEC/cli-help/
+ *  search.txt`: "cw search  Search workflow apps by keyword (title,
+ *  description, id)."); `hiddenFromHelp` here was a rebuild regression
+ *  that hid it, not a preserved old-build quirk — removed so the row
+ *  shows again. The summary text below is intentionally NOT byte-matched
+ *  to that old capture: the old wording says "description," but the
+ *  filter below matches `summary` (there is no `description` field) — so
+ *  the summary text stays accurate to current fields rather than
+ *  reproducing the old capture's stale terminology. */
 (0, registry_core_1.addCliOnlyCapability)("search", "Search bundled workflows by id/title/summary keyword.", {
     path: ["search"],
     jsonMode: "flag",
-    hiddenFromHelp: true,
     handler: (args) => {
         const keyword = args.positionals.join(" ");
         if (!keyword.trim()) {
             throw new Error('Missing search keyword.\n  Tip: cw search architecture to find workflows about architecture.');
         }
         const lower = keyword.toLowerCase();
-        const results = (0, workflow_app_loader_1.listWorkflowApps)()
+        const results = loadWorkflowAppLoader().listWorkflowApps()
             .filter((a) => String(a.title).toLowerCase().includes(lower) ||
             String(a.summary).toLowerCase().includes(lower) ||
             String(a.id).toLowerCase().includes(lower))

package/dist/wiring/capability-table/exec-backend.js

@@ -17,9 +17,16 @@ const registry_core_1 = require("./registry-core");
 // as milestones 3/4 did for their own rows.
 // ---------------------------------------------------------------------
 const exec_backend_cli_1 = require("../../shell/exec-backend-cli");
-const doctor_1 = require("../../shell/doctor");
 const io_1 = require("../../cli/io");
-const app_run_cli_1 = require("../../shell/app-run-cli");
+// This slice is required unconditionally at startup for every command;
+// load doctor/app-run-cli lazily so only doctor/fix/sandbox.choose/
+// sandbox.resolve/app.run handlers pay their require cost.
+function loadDoctor() {
+    return require("../../shell/doctor");
+}
+function loadAppRunCli() {
+    return require("../../shell/app-run-cli");
+}
 (0, registry_core_1.attachCliBinding)("sandbox.list", {
     path: ["sandbox", "list"],
     jsonMode: "default",
@@ -29,9 +36,9 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.list").mcp.handler = (args)
 // GAP #24: cw_sandbox_choose / cw_sandbox_resolve + cw_app_run were declared
 // MCP-only rows with the notYetImplemented placeholder handler. Wire them to
 // the ported shell bodies (both are MCP-only in the old build — no CLI path).
-registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.choose").mcp.handler = (args) => (0, app_run_cli_1.sandboxChooseCli)(args);
-registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.resolve").mcp.handler = (args) => (0, app_run_cli_1.sandboxChooseCli)(args);
-registry_core_1.REGISTRY_BY_CAPABILITY.get("app.run").mcp.handler = (args) => (0, app_run_cli_1.appRunCli)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.choose").mcp.handler = (args) => loadAppRunCli().sandboxChooseCli(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.resolve").mcp.handler = (args) => loadAppRunCli().sandboxChooseCli(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("app.run").mcp.handler = (args) => loadAppRunCli().appRunCli(args);
 (0, registry_core_1.attachCliBinding)("sandbox.show", {
     path: ["sandbox", "show"],
     jsonMode: "default",
@@ -57,12 +64,12 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.validate").mcp.handler = (ar
 (0, registry_core_1.attachCliBinding)("sandbox.choose", {
     path: ["sandbox", "choose"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, app_run_cli_1.sandboxChooseCli)(args.options) }),
+    handler: (args) => ({ json: loadAppRunCli().sandboxChooseCli(args.options) }),
 });
 (0, registry_core_1.attachCliBinding)("sandbox.resolve", {
     path: ["sandbox", "resolve"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, app_run_cli_1.sandboxChooseCli)(args.options) }),
+    handler: (args) => ({ json: loadAppRunCli().sandboxChooseCli(args.options) }),
 });
 (0, registry_core_1.attachCliBinding)("backend.list", {
     path: ["backend", "list"],
@@ -134,7 +141,8 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.set").reason =
     path: ["doctor"],
     jsonMode: "flag",
     handler: (args) => {
-        const report = (0, doctor_1.runDoctor)(args.options, process.env, String(args.options.cwd || process.cwd()));
+        const doctor = loadDoctor();
+        const report = doctor.runDoctor(args.options, process.env, String(args.options.cwd || process.cwd()));
         // Byte-exact port of src/cli/command-surface.ts:170-176: both text
         // branches are written as `${formatX(report)}\n` UNCONDITIONALLY —
         // formatDoctorFixes already ends in its own "\n" (its last joined
@@ -143,7 +151,7 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.set").reason =
         // renderer only appends "\n" when the text does NOT already end in
         // one, so a bare `formatDoctorFixes(report)` here would silently
         // drop the old build's trailing blank line.
-        const text = (0, io_1.wantsJson)(args.options) ? undefined : args.options.fix ? `${(0, doctor_1.formatDoctorFixes)(report)}\n` : (0, doctor_1.formatDoctorReport)(report);
+        const text = (0, io_1.wantsJson)(args.options) ? undefined : args.options.fix ? `${doctor.formatDoctorFixes(report)}\n` : doctor.formatDoctorReport(report);
         return { json: report, text, exitCode: report.ok ? undefined : 1 };
     },
 }, "Environment diagnostics are inherently local to the CLI host — Node version, $PATH, $CW_HOME/cwd writability. An MCP client diagnosing the server process's environment is not meaningful; agents already receive the same readiness facts in their typed results (e.g. status: blocked, agentConfigured). Inspired by `brew doctor`.");
@@ -151,12 +159,13 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.set").reason =
     path: ["fix"],
     jsonMode: "human",
     handler: (args) => {
-        const report = (0, doctor_1.runDoctor)(args.options, process.env, String(args.options.cwd || process.cwd()));
+        const doctor = loadDoctor();
+        const report = doctor.runDoctor(args.options, process.env, String(args.options.cwd || process.cwd()));
         // See the "doctor" handler's comment above: formatDoctorFixes
         // already ends in "\n", so one more explicit "\n" here reproduces
         // src/cli/command-surface.ts:126-130's unconditional
         // `${formatDoctorFixes(report)}\n` write.
-        return { text: `${(0, doctor_1.formatDoctorFixes)(report)}\n`, exitCode: report.ok ? undefined : 1 };
+        return { text: `${doctor.formatDoctorFixes(report)}\n`, exitCode: report.ok ? undefined : 1 };
     },
 }, "Environment fix commands are local diagnostics, same reasoning as doctor.");
 // ---------------------------------------------------------------------