cool-workflow 0.2.2 → 0.2.4

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/shell/workflow-app-loader.js

@@ -141,14 +141,37 @@ function candidateWorkflowsRoots() {
     roots.push(path.join(process.cwd(), "workflows"));
     return roots;
 }
+/** Whether `candidate` resolves to `root` itself or a real descendant of it
+ *  (not an ancestor, sibling, or anywhere reached only via `..` segments). */
+function isWithinRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
 function findAppDir(appId) {
     for (const root of candidateAppsRoots()) {
         const dir = path.join(root, appId);
+        // appId is caller-controlled (MCP app.run, `cw plan`/`run --drive`, a
+        // sub-workflow's spec.appId). Without this check a traversal id like
+        // "../../../tmp/evil-app" walks path.join right out of every trusted
+        // root and loadWorkflowApp below require()s whatever app.json it finds
+        // there with NO manifest/entrypoint validation — the fast path this
+        // function feeds skips validateWorkflowApp entirely (see loadWorkflowApp).
+        if (!isWithinRoot(root, dir))
+            continue;
         if (fs.existsSync(path.join(dir, "app.json")))
             return dir;
     }
     return undefined;
 }
+/** Every root candidateAppsRoots()/candidateWorkflowsRoots() would search:
+ *  bundled apps/workflows, an installed package's apps/workflows, an
+ *  operator-set CW_APPS_DIR/CW_WORKFLOWS_DIR, and the caller's cwd/apps +
+ *  cwd/workflows (the "cw app init" default — must stay unwarned, it is
+ *  the normal flow for a user's own local apps). */
+function isTrustedAppSourcePath(resolvedPath) {
+    const roots = [...candidateAppsRoots(), ...candidateWorkflowsRoots()];
+    return roots.some((root) => isWithinRoot(path.resolve(root), resolvedPath));
+}
 function validationContext() {
     return { bundledSandboxProfileIds: (0, sandbox_profile_1.bundledSandboxProfileIds)(), currentCoolWorkflowVersion: version_1.CURRENT_COOL_WORKFLOW_VERSION };
 }
@@ -451,6 +474,31 @@ function loadWorkflowAppRecordTarget(target) {
         throw new Error("Missing workflow app path or id");
     const resolved = path.resolve(target);
     if (fs.existsSync(resolved)) {
+        // `validate`/`show` on a real path is the one loader entrypoint whose
+        // whole point is to let a caller inspect an app BEFORE deciding to
+        // trust it — but inspecting it means require()-ing its workflow.js
+        // (validateWorkflowApp needs the returned WorkflowDefinition, which
+        // only exists after the factory runs). A path outside every root CW
+        // already trusts (bundled apps, an installed package, CW_APPS_DIR, or
+        // the caller's own cwd/apps from `cw app init`) gets arbitrary code
+        // executed by "validate", with no OS-level containment — a warning
+        // printed after that require() call would be too late to matter, so
+        // this fails closed instead: refuse by default, and only proceed
+        // (still with a visible warning) when the caller explicitly opts in.
+        // Mirrors the existing --allow-unattested precedent in
+        // worker-isolation.ts: unsafe-but-explicit, never silent.
+        if (!isTrustedAppSourcePath(resolved)) {
+            if (!process.env.CW_ALLOW_EXTERNAL_APP_CODE) {
+                throw new app_schema_1.WorkflowAppValidationError("Untrusted workflow app source", [
+                    {
+                        code: "workflow-app-untrusted-source",
+                        message: `Refusing to load workflow app code outside CW's trusted app roots: ${resolved}. Its workflow.js would run as ordinary Node.js code with full host privileges — CW does not sandbox app code, only delegated agent workers. Set CW_ALLOW_EXTERNAL_APP_CODE=1 to load and execute it anyway.`,
+                        path: resolved,
+                    },
+                ]);
+            }
+            process.stderr.write(`cw: loading external workflow app code from ${resolved} — its workflow.js runs as ordinary Node.js code with full host privileges, not sandboxed.\n`);
+        }
         const stat = fs.statSync(resolved);
         if (stat.isDirectory())
             return loadWorkflowAppFromManifest(path.join(resolved, "app.json"));
@@ -593,6 +641,24 @@ function renderManifestTemplate(id, title) {
 function renderEntrypointTemplate(id, title) {
     return `module.exports = ({ workflow, phase, agent, artifact, input }) => {\n  const inputs = [\n    input("question", { type: "string", required: true, description: "Question or task this workflow should answer." })\n  ];\n\n  return workflow({\n    id: ${JSON.stringify(id)},\n    title: ${JSON.stringify(title)},\n    summary: "Describe what this workflow app does.",\n    limits: {\n      maxAgents: 8,\n      maxConcurrentAgents: 4\n    },\n    inputs,\n    sandboxProfiles: ["readonly"],\n    phases: [\n      phase("Map", [\n        agent("map:context", "Map the task context, constraints, and evidence needed for {{question}}.", { sandboxProfileId: "readonly" })\n      ]),\n      phase("Assess", [\n        agent("assess:risks", "Assess risks, tradeoffs, and unknowns for {{question}}.", { sandboxProfileId: "readonly" })\n      ]),\n      phase("Synthesize", [\n        artifact("synthesis:report", "Synthesize the final answer for {{question}}.", { requiresEvidence: true, sandboxProfileId: "readonly" })\n      ])\n    ]\n  });\n};\n`;
 }
+/** Validates a manifest CW itself just wrote to disk (from `initWorkflowApp`
+ *  below) — deliberately bypasses `loadWorkflowAppRecordTarget`'s
+ *  untrusted-source gate. That gate exists for `cw app validate <path>`,
+ *  where the caller is inspecting code someone else wrote before deciding
+ *  whether to trust it; `app init --directory <anywhere>` is the opposite
+ *  case (the caller is authoring new code, from CW's own template, in a
+ *  location they chose on purpose) and must keep working regardless of
+ *  where `--directory` points. */
+function validateGeneratedManifest(manifestPath) {
+    try {
+        const record = loadWorkflowAppFromManifest(manifestPath);
+        const result = (0, app_schema_1.validateWorkflowApp)(record.app, validationContext(), { appPath: sourcePathOf(record) });
+        return { ...result, summary: summarizeWorkflowAppRecord(record) };
+    }
+    catch (error) {
+        return { valid: false, appId: manifestPath, appPath: path.resolve(manifestPath), issues: (0, app_schema_1.validationIssuesFromError)(error) };
+    }
+}
 /** `cw app init <id>` / `cw_app_init`. Writes `app.json` + `workflow.js`
  *  from the templates, refusing system directories and (without
  *  `--force`) an existing app. Ported from `initApp`. */
@@ -614,7 +680,7 @@ function initWorkflowApp(appId, options = {}) {
     fs.mkdirSync(destinationDir, { recursive: true });
     fs.writeFileSync(manifestPath, renderManifestTemplate(id, title), "utf8");
     fs.writeFileSync(entrypointPath, renderEntrypointTemplate(id, title), "utf8");
-    const validation = validateWorkflowAppTarget(manifestPath);
+    const validation = validateGeneratedManifest(manifestPath);
     if (!validation.valid) {
         throw new app_schema_1.WorkflowAppValidationError("Generated workflow app is invalid", validation.issues);
     }

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 cli_args_1 = require("../../core/util/cli-args");
+// 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, cli_args_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))