cool-workflow 0.2.4 → 0.2.6

package/dist/shell/trust-audit.js

@@ -62,6 +62,7 @@ exports.trustAuditHead = trustAuditHead;
 exports.verifyTrustAudit = verifyTrustAudit;
 exports.repairTrustAuditTornTail = repairTrustAuditTornTail;
 exports.recordTrustAuditEvent = recordTrustAuditEvent;
+exports.withTrustAuditBatch = withTrustAuditBatch;
 exports.recordSandboxPathDecision = recordSandboxPathDecision;
 exports.normalizeEvidence = normalizeEvidence;
 exports.writeTrustAuditIndexPlaceholder = writeTrustAuditIndexPlaceholder;
@@ -85,8 +86,15 @@ function ensureTrustAudit(run) {
     run.paths.auditDir = dir;
     const audit = { schemaVersion: 1, ...trustAuditPaths(run) };
     run.audit = audit;
+    // Create-if-missing must NEVER truncate: this runs OUTSIDE the append
+    // lock, so between an existsSync(false) here and a plain create, another
+    // process may have already created the log AND appended real events —
+    // a truncating create then silently deletes them (one event lost, chain
+    // still verifies "clean" from genesis; seen once on CI under coverage
+    // I/O). Flag "a" is O_CREAT without O_TRUNC: it makes the file when
+    // missing and adds zero bytes when not, with no exists-check window.
     if (!fs.existsSync(audit.eventLogPath))
-        fs.writeFileSync(audit.eventLogPath, "", "utf8");
+        fs.writeFileSync(audit.eventLogPath, "", { encoding: "utf8", flag: "a" });
     return audit;
 }
 /** Genesis prevHash for a run's chain (no prior event). Exported so
@@ -107,6 +115,7 @@ function computeEventHash(event) {
     void eventHash;
     return (0, hash_1.sha256)((0, hash_1.eventHashInput)(rest));
 }
+const ACTIVE_AUDIT_BATCHES = new Map();
 function tailCachePathFor(eventLogPath) {
     return path.join(path.dirname(eventLogPath), "tail-cache.json");
 }
@@ -467,34 +476,90 @@ function recordTrustAuditEvent(run, input) {
         parentEventIds: unique(input.parentEventIds || []).sort(),
         metadata: scrubMetadata(input.metadata || {}),
     });
+    const batch = ACTIVE_AUDIT_BATCHES.get(path.resolve(audit.eventLogPath));
+    if (batch)
+        return appendTrustAuditEvent(run, input, event, batch);
     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;
+        const cached = readAuditTailCache(tailCachePathFor(audit.eventLogPath));
+        const prior = cached && cached.logBytes === currentBytes ? undefined : readEventsRaw(audit.eventLogPath);
+        const state = {
+            audit,
+            currentBytes,
+            count: cached && cached.logBytes === currentBytes ? cached.count : prior.length,
+            lastHash: cached && cached.logBytes === currentBytes ? cached.lastHash : (prior.length ? prior[prior.length - 1].eventHash || computeEventHash(prior[prior.length - 1]) : trustAuditGenesis(run.id)),
+            lines: [],
+        };
+        const result = appendTrustAuditEvent(run, input, event, state);
+        flushTrustAuditBatch(state);
+        return result;
+    });
+}
+function appendTrustAuditEvent(run, input, event, batch) {
+    // 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.
+    event.id = createEventId(input.kind, batch.count);
+    event.prevEventHash = batch.lastHash;
+    event.eventHash = computeEventHash(event);
+    // Newline-boundary safety (fail-closed). `durableAppendFileSync` only ever
+    // ADDS bytes at the end of file and never writes a separator of its own. A
+    // completed append always leaves the log ending in "\n"; if the last byte
+    // is NOT "\n", the previous append was torn by a crash (its bytes were
+    // never a confirmed event — the append never returned). Writing this new,
+    // already-cross-linked event straight onto that partial byte-run would
+    // MERGE the two into one line that no longer parses — losing THIS event and
+    // poisoning the forward chain (the next append's prevEventHash would point
+    // into an unparseable blob), with no repair for that shape. So put the new
+    // event on its own clean line: prepend a "\n" when the log does not already
+    // end in one, confining any crash artifact to its own now-orphaned line.
+    // (Reads only the last byte, so the O(1) tail-cache path is preserved.)
+    // An empty log (currentBytes === 0, e.g. the first append) has no tail to
+    // merge with, so it never needs a leading newline.
+    const leadingNewline = batch.currentBytes > 0 && batch.lines.length === 0 && !(0, fs_atomic_1.logEndsWithNewline)(batch.audit.eventLogPath, batch.currentBytes) ? "\n" : "";
+    const line = `${leadingNewline}${JSON.stringify(event)}\n`;
+    batch.lines.push(line);
+    batch.currentBytes += Buffer.byteLength(line, "utf8");
+    batch.count += 1;
+    batch.lastHash = event.eventHash;
+    return event;
+}
+function flushTrustAuditBatch(batch) {
+    if (!batch.lines.length)
+        return;
+    (0, fs_atomic_1.durableAppendFileSync)(batch.audit.eventLogPath, batch.lines.join(""));
+    writeAuditTailCache(tailCachePathFor(batch.audit.eventLogPath), { schemaVersion: 1, logBytes: batch.currentBytes, count: batch.count, lastHash: batch.lastHash });
+}
+/** Run a short, synchronous mutation group under one audit lock and append its
+ *  exact NDJSON lines with one durable write before the caller checkpoints. */
+function withTrustAuditBatch(run, fn) {
+    const audit = ensureTrustAudit(run);
+    const key = path.resolve(audit.eventLogPath);
+    if (ACTIVE_AUDIT_BATCHES.has(key))
+        return fn();
+    return (0, fs_atomic_1.withFileLock)(audit.eventLogPath, () => {
+        const currentBytes = fs.existsSync(audit.eventLogPath) ? fs.statSync(audit.eventLogPath).size : 0;
+        const cached = readAuditTailCache(tailCachePathFor(audit.eventLogPath));
+        const prior = cached && cached.logBytes === currentBytes ? undefined : readEventsRaw(audit.eventLogPath);
+        const batch = {
+            audit,
+            currentBytes,
+            count: cached && cached.logBytes === currentBytes ? cached.count : prior.length,
+            lastHash: cached && cached.logBytes === currentBytes ? cached.lastHash : (prior.length ? prior[prior.length - 1].eventHash || computeEventHash(prior[prior.length - 1]) : trustAuditGenesis(run.id)),
+            lines: [],
+        };
+        ACTIVE_AUDIT_BATCHES.set(key, batch);
+        try {
+            const result = fn();
+            flushTrustAuditBatch(batch);
+            return result;
         }
-        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);
+        finally {
+            ACTIVE_AUDIT_BATCHES.delete(key);
         }
-        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) {
@@ -634,9 +699,68 @@ function commitRows(events, run) {
         };
     });
 }
-function summarizeTrustAudit(run) {
-    const audit = ensureTrustAudit(run);
-    const events = readEventsRaw(audit.eventLogPath);
+// Perf cycle P1 (read side): every read command (`cw status`, each
+// `writeReport` call, multi-agent status) called `summarizeTrustAudit`,
+// which read+parsed the log via `readEventsRaw`, THEN called
+// `verifyTrustAudit(run)`, which read+parsed the SAME log AGAIN and
+// recomputed a sha256 for every event -- two full passes for one call.
+// It then durably (fsync) rewrote summary.json AND index.json on EVERY
+// call, even when nothing about the run or the log had changed since the
+// last call (a live audit reaches ~50k events, so `writeReport` alone --
+// which calls this once per pipeline step and per feedback op -- turned
+// into a real, repeated cost).
+//
+// Fix, in two parts:
+//  1. Read the log ONCE (`readEventsRawCounted`) and hand the SAME parsed
+//     array to `verifyEventsChain` directly -- the exact same check
+//     `verifyTrustAudit` runs with no anchor, so the integrity result is
+//     byte-identical to before. `verifyTrustAudit` itself is untouched and
+//     every OTHER caller (doctor.ts, `cw audit verify`, drive.ts,
+//     run-export.ts) still gets a real, independent, always-full check.
+//  2. Skip the durable rewrite of summary.json/index.json when the freshly
+//     and FULLY recomputed content is unchanged from last time. This is
+//     NOT a shortcut on verification -- the full parse+rehash+chain-walk
+//     above always runs, on every call, no exceptions. A cache that
+//     reused a stale "verified" verdict would be unsound here: this
+//     codebase's chain check is a sequential field-comparison walk, not a
+//     content-addressed (Merkle) chain, so tampering with an EARLY event
+//     can leave the file's total size and its LAST event's bytes fully
+//     unchanged while still flipping `verified` to false. So the cache
+//     below only ever gates the DISK WRITE of an already fully-verified
+//     result, never the verification itself, and the function's RETURN
+//     VALUE is always the fresh `summary` object either way.
+function summaryFingerprintPathFor(summaryPath) {
+    return path.join(path.dirname(summaryPath), "summary-fingerprint.json");
+}
+function readSummaryFingerprint(fingerprintPath) {
+    if (!fs.existsSync(fingerprintPath))
+        return undefined;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(fingerprintPath, "utf8"));
+        if (parsed && parsed.schemaVersion === 1 && typeof parsed.hash === "string")
+            return parsed.hash;
+    }
+    catch {
+        // Corrupt/unreadable fingerprint -- fall back to a real rewrite below.
+    }
+    return undefined;
+}
+function writeSummaryFingerprint(fingerprintPath, fingerprint) {
+    try {
+        (0, fs_atomic_1.writeJson)(fingerprintPath, fingerprint);
+    }
+    catch {
+        // Best-effort: a failed fingerprint write must never break the real call
+        // -- it just means the next call falls back to a real rewrite.
+    }
+}
+function summarizeTrustAudit(run, options = {}) {
+    const persist = options.persist !== false;
+    // A read-only projection must not call ensureTrustAudit(): that helper is
+    // deliberately for mutation paths and creates the audit directory and an
+    // empty event log when they are absent.
+    const audit = persist ? ensureTrustAudit(run) : { schemaVersion: 1, ...trustAuditPaths(run) };
+    const { events, corruptLines } = readEventsRawCounted(audit.eventLogPath);
     const ma = run.multiAgent;
     const bb = run.blackboard;
     const summary = {
@@ -644,7 +768,7 @@ function summarizeTrustAudit(run) {
         runId: run.id,
         generatedAt: new Date().toISOString(),
         eventCount: events.length,
-        integrity: verifyTrustAudit(run),
+        integrity: verifyEventsChain(run.id, events, corruptLines),
         eventLogPath: audit.eventLogPath,
         indexPath: audit.indexPath,
         summaryPath: audit.summaryPath,
@@ -688,11 +812,7 @@ function summarizeTrustAudit(run) {
             policyViolations: events.filter((e) => e.kind === "policy.violation").length,
         },
     };
-    // Durable: the summary/index are the read-side view of the audit log; persist
-    // them durably so a crash can't leave them pointing past the last durably-
-    // appended event. Byte-behavior port of the old build's summarizeTrustAudit.
-    (0, fs_atomic_1.writeJson)(audit.summaryPath, summary, { durable: true });
-    (0, fs_atomic_1.writeJson)(audit.indexPath, {
+    const index = {
         schemaVersion: exports.TRUST_AUDIT_SCHEMA_VERSION,
         runId: run.id,
         events: events.map((event) => ({
@@ -707,7 +827,29 @@ function summarizeTrustAudit(run) {
             sandboxProfileId: event.sandboxProfileId,
             policyRef: event.policyRef,
         })),
-    }, { durable: true });
-    run.audit = { schemaVersion: exports.TRUST_AUDIT_SCHEMA_VERSION, ...audit };
+    };
+    // Durable: the summary/index are the read-side view of the audit log; persist
+    // them durably so a crash can't leave them pointing past the last durably-
+    // appended event. Byte-behavior port of the old build's summarizeTrustAudit.
+    //
+    // Skip the rewrite only when the freshly, fully recomputed content is
+    // unchanged from last time (see the comment on `summaryFingerprintPathFor`
+    // above) -- `generatedAt` is dropped before fingerprinting since it is the
+    // one field that legitimately changes on every call. The RETURNED
+    // `summary` below always carries a real, fresh `generatedAt` either way;
+    // only the ON-DISK bytes may keep the previous call's `generatedAt` when
+    // nothing else changed.
+    const { generatedAt: _generatedAt, ...summaryForFingerprint } = summary;
+    void _generatedAt;
+    const fingerprintPath = summaryFingerprintPathFor(audit.summaryPath);
+    const freshFingerprint = (0, hash_1.stableHash)({ summary: summaryForFingerprint, index });
+    const priorFingerprint = readSummaryFingerprint(fingerprintPath);
+    if (persist && priorFingerprint !== freshFingerprint) {
+        (0, fs_atomic_1.writeJson)(audit.summaryPath, summary, { durable: true });
+        (0, fs_atomic_1.writeJson)(audit.indexPath, index, { durable: true });
+        writeSummaryFingerprint(fingerprintPath, { schemaVersion: 1, hash: freshFingerprint });
+    }
+    if (persist)
+        run.audit = { schemaVersion: exports.TRUST_AUDIT_SCHEMA_VERSION, ...audit };
     return summary;
 }

package/dist/shell/workbench-host.js

@@ -52,13 +52,55 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkbenchHost = void 0;
+exports.formatServeHint = formatServeHint;
+exports.printServeHint = printServeHint;
 const crypto = __importStar(require("node:crypto"));
 const fs = __importStar(require("node:fs"));
 const http = __importStar(require("node:http"));
 const path = __importStar(require("node:path"));
 const node_url_1 = require("node:url");
 const workbench_1 = require("./workbench");
+// `[::1]` is the form Node's URL parser returns for a bracketed IPv6
+// literal Host header (verified); the bare `::1` covers a non-bracketed
+// header that our fallback split still yields. `.split(":")[0]` alone could
+// never produce either (it returns `[` or ``), so those entries used to be
+// dead — parseHostname below fixes that.
 const ALLOWED_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+/** Extract the hostname from a Host header, correctly handling a bracketed
+ *  IPv6 literal (`[::1]:7717`) that a naive `split(":")[0]` mangles into
+ *  `"["`. Returns undefined when the header cannot be parsed at all. */
+function parseHostname(hostHeader) {
+    try {
+        return new node_url_1.URL(`http://${hostHeader}`).hostname;
+    }
+    catch {
+        // A non-bracketed IPv6 literal (`::1`) is not a valid URL authority, so
+        // URL() throws — fall back to the raw header for that one case; a
+        // hostname:port still trims the port.
+        if (hostHeader.includes("]") || hostHeader.split(":").length > 2)
+            return hostHeader;
+        return hostHeader.split(":")[0];
+    }
+}
+function isTTY(stream) {
+    return Boolean(stream.isTTY);
+}
+/** Pure text for the human-friendly serve hint line. Kept separate from
+ *  the TTY gate below so it is directly unit-testable with no fake stream
+ *  at all: just a port number in, one line of text out. */
+function formatServeHint(boundPort) {
+    return `workbench serving at http://127.0.0.1:${boundPort} (Ctrl-C to stop)`;
+}
+/** Prints the human hint line to STDERR only, and only on a real
+ *  interactive terminal — the same TTY-gated-nicety pattern as
+ *  term.ts's printSuccessSummary: silent when the stream is not a TTY, so
+ *  a piped/non-interactive run (and the existing STDOUT descriptor line)
+ *  never changes at all. */
+function printServeHint(boundPort, stream = process.stderr) {
+    if (!isTTY(stream))
+        return;
+    stream.write(`${formatServeHint(boundPort)}\n`);
+}
 function timingSafeEqual(a, b) {
     const bufA = Buffer.from(a, "utf8");
     const bufB = Buffer.from(b, "utf8");
@@ -72,6 +114,13 @@ function timingSafeEqual(a, b) {
     return crypto.timingSafeEqual(bufA, bufB);
 }
 function sendJson(res, status, body) {
+    // If a handler already began the response (e.g. an asset read threw AFTER
+    // writeHead), a second writeHead throws ERR_HTTP_HEADERS_SENT synchronously
+    // inside the request listener and kills the whole server. Guard against it.
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
     const text = `${JSON.stringify(body, null, 2)}\n`;
     res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
     res.end(text);
@@ -124,8 +173,8 @@ class WorkbenchHost {
         try {
             const hostHeader = req.headers.host;
             if (hostHeader) {
-                const hostname = hostHeader.split(":")[0];
-                if (!ALLOWED_HOSTNAMES.has(hostname)) {
+                const hostname = parseHostname(hostHeader);
+                if (hostname === undefined || !ALLOWED_HOSTNAMES.has(hostname)) {
                     sendJson(res, 403, { error: "forbidden: non-localhost Host header" });
                     return;
                 }
@@ -143,10 +192,6 @@ class WorkbenchHost {
                 sendJson(res, 400, { error: "bad request: invalid URL" });
                 return;
             }
-            if (!this.checkAuth(req, url)) {
-                sendJson(res, 401, { error: "unauthorized: token mismatch" });
-                return;
-            }
             // Decode the route path ONCE (old build's decodeRoutePath). Node's
             // `new URL()` does NOT throw on a malformed percent-escape like
             // `/%E0%A4%A`; only decodeURIComponent does — so this is where a
@@ -162,13 +207,36 @@ class WorkbenchHost {
                 sendJson(res, 400, { error: "bad request: malformed URL path" });
                 return;
             }
+            // Auth is checked AFTER the route is decoded, and only where run data
+            // (or environment data) can flow. Before this, a set token made the
+            // browser's own follow-up requests for /ui/app.css and /ui/app.js fail
+            // 401 — the page rendered as broken unstyled HTML with no explanation.
+            // The three shipped UI files are generic static code with no run data,
+            // so they are served without a token. Every /api/* route carries run
+            // data and stays behind the token. The "/" route is split: an
+            // INSTALLED index.html is the same generic static code (open), but the
+            // FALLBACK page embeds the serve descriptor — which carries the
+            // absolute repo root path — so a missing UI keeps "/" behind the token.
+            if (!this.checkAuth(req, url)) {
+                const uiIndexInstalled = fs.existsSync(path.resolve((0, workbench_1.workbenchUiRoot)(), "index.html"));
+                if (route.startsWith("/api/") || (route === "/" && !uiIndexInstalled)) {
+                    sendJson(res, 401, { error: "unauthorized: token mismatch" });
+                    return;
+                }
+            }
             if (route === "/api/serve") {
                 sendJson(res, 200, this.descriptor(false));
                 return;
             }
             if (route === "/api/index") {
                 const scope = this.args.scope === "home" ? "home" : "repo";
-                sendJson(res, 200, (0, workbench_1.buildWorkbenchIndex)({ ...this.args, scope, ...Object.fromEntries(url.searchParams.entries()) }));
+                // Only `text` may be driven by the query string — it is the sidebar
+                // filter. Spreading ALL query params (as before) let a request
+                // override the server's computed `scope` or inject an arbitrary
+                // `cwd`, reading run data from any directory the serving user can
+                // read, past the repo the operator chose to serve.
+                const text = url.searchParams.get("text") || undefined;
+                sendJson(res, 200, (0, workbench_1.buildWorkbenchIndex)({ ...this.args, scope, ...(text ? { text } : {}) }));
                 return;
             }
             const runMatch = route.match(/^\/api\/run\/([^/]+)$/);
@@ -204,15 +272,30 @@ class WorkbenchHost {
             sendJson(res, 404, { error: `UI asset not installed: ${relative}` });
             return;
         }
+        // Read the bytes BEFORE writeHead: if the asset vanished or became
+        // unreadable between the checks above and here (TOCTOU), the throw
+        // then lands on the sendJson(500) path with headers not yet sent,
+        // instead of a fatal double-writeHead.
+        const bytes = fs.readFileSync(resolved);
         res.writeHead(200, { "Content-Type": contentTypeFor(resolved), "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
-        res.end(fs.readFileSync(resolved));
+        res.end(bytes);
     }
     /** Binds the loopback server and resolves once listening. Returns the
      *  actually-bound port (useful for `--port 0`). */
     listen() {
         return new Promise((resolve, reject) => {
+            // Defense in depth: `run()` already validated the port before ever
+            // reaching here, but a direct caller of listen() still fails closed
+            // with the clear message rather than node's opaque ERR_SOCKET_BAD_PORT.
+            let requestedPort;
+            try {
+                requestedPort = (0, workbench_1.parseWorkbenchPort)(this.args.port);
+            }
+            catch (error) {
+                reject(error);
+                return;
+            }
             const server = http.createServer((req, res) => this.handleRequest(req, res));
-            const requestedPort = this.args.port !== undefined ? Number(this.args.port) : undefined;
             server.on("error", reject);
             server.listen(requestedPort ?? 7717, "127.0.0.1", () => {
                 this.server = server;
@@ -243,14 +326,42 @@ class WorkbenchHost {
             process.exitCode = 1;
             return;
         }
+        // Validate --port HERE, before any dispatch. The CLI binding calls this
+        // as `void host.run()` (not awaited), so a rejection from listen() would
+        // otherwise surface as an unhandled promise rejection stack dump on the
+        // real CLI. Fail closed the same clean way as --require-token: one `cw:`
+        // stderr line + exit 1 + return, never a crash and never a bound server.
+        try {
+            (0, workbench_1.parseWorkbenchPort)(this.args.port);
+        }
+        catch (error) {
+            process.stderr.write(`cw: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+            return;
+        }
         const once = Boolean(this.args.once || this.args.json);
         if (once) {
             process.stdout.write(`${JSON.stringify(this.descriptor(true))}\n`);
             return;
         }
-        const boundPort = await this.listen();
+        // The bind itself can still fail at runtime (EADDRINUSE when the port
+        // is taken, EACCES on a privileged port) — listen() rejects for those.
+        // The port-VALUE check above only covers a malformed --port. Fail
+        // closed the same clean way rather than an unhandled-rejection crash.
+        let boundPort;
+        try {
+            boundPort = await this.listen();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`cw: ${message}\n`);
+            process.stderr.write(`Try: pick another port with --port <n>, or stop whatever is already serving.\n`);
+            process.exitCode = 1;
+            return;
+        }
         const descriptor = this.descriptor(false, boundPort);
         process.stdout.write(`${JSON.stringify({ ...descriptor, boundPort })}\n`);
+        printServeHint(boundPort);
         // Block forever (until the process is killed) — a real serve.
         await new Promise(() => { });
     }

package/dist/shell/workbench.js

@@ -47,6 +47,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WORKBENCH_UI_RELATIVE = exports.WORKBENCH_DEFAULT_PORT = void 0;
+exports.parseWorkbenchPort = parseWorkbenchPort;
 exports.buildWorkbenchRunView = buildWorkbenchRunView;
 exports.workbenchUiRoot = workbenchUiRoot;
 exports.buildWorkbenchServeDescriptor = buildWorkbenchServeDescriptor;
@@ -56,6 +57,32 @@ const capability_table_1 = require("../core/capability-table");
 const run_store_1 = require("./run-store");
 exports.WORKBENCH_DEFAULT_PORT = 7717;
 exports.WORKBENCH_UI_RELATIVE = "ui/workbench";
+/** Parse and range-check a workbench `--port` value. Returns `undefined`
+ *  when no port was given (the caller then uses WORKBENCH_DEFAULT_PORT),
+ *  the validated integer otherwise. Throws a clear Error on a bad value —
+ *  a non-number (`NaN`), a float, a negative, or a number over 65535 — so
+ *  callers fail closed with an actionable line instead of node's opaque
+ *  ERR_SOCKET_BAD_PORT or a `"port": null` descriptor. A valid port is an
+ *  integer in [0, 65535]; 0 is the legitimately-supported ephemeral port. */
+function parseWorkbenchPort(raw) {
+    if (raw === undefined)
+        return undefined;
+    const reject = () => {
+        throw new Error(`workbench serve --port must be an integer 0-65535 (got ${JSON.stringify(raw)})`);
+    };
+    // Only a string (the argv form) or a number is a real port. A valueless
+    // `--port` flag parses to boolean `true`; reject it rather than let
+    // Number(true) === 1 silently bind to port 1. A blank string is bad input
+    // too — Number("") === 0 would otherwise pass as the ephemeral port.
+    if (typeof raw !== "string" && typeof raw !== "number")
+        reject();
+    if (typeof raw === "string" && raw.trim() === "")
+        reject();
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        reject();
+    return port;
+}
 /** Panel groups/members, in the SPEC's declared order. Each entry names
  *  the capability id whose MCP handler is called to fill the panel. */
 const PANEL_MAP = {
@@ -104,8 +131,26 @@ function buildWorkbenchRunView(runId, args = {}) {
         resolved = false;
         resolveError = error instanceof Error ? error.message : String(error);
     }
+    // The run's lifecycle, from the SAME `run.show` capability handler the
+    // CLI/MCP use (the buildWorkbenchIndex composition style — never a
+    // duplicate implementation). This function's contract is never-throws,
+    // so any failure here just leaves the key out.
+    let lifecycle;
+    try {
+        const showRow = (0, capability_table_1.findCapability)("run.show");
+        const shown = showRow?.mcp ? showRow.mcp.handler({ ...args, runId, cwd }) : undefined;
+        if (shown && shown.found === true && shown.record && typeof shown.record.lifecycle === "string") {
+            lifecycle = shown.record.lifecycle;
+        }
+    }
+    catch {
+        lifecycle = undefined;
+    }
     const panels = {};
-    const panelArgs = { ...args, runId, cwd };
+    // This is an internal mechanism flag, not a CLI/MCP option. The Workbench
+    // must use the same capability bodies as the other front doors, but its
+    // GET-only projection must not make derived audit or metrics files.
+    const panelArgs = { ...args, runId, cwd, __cwWorkbenchReadOnlyProjection: true };
     for (const [group, members] of Object.entries(PANEL_MAP)) {
         panels[group] = {};
         for (const [member, capability] of Object.entries(members)) {
@@ -114,7 +159,7 @@ function buildWorkbenchRunView(runId, args = {}) {
                 : { capability, cli: cliCommandFor(capability), mcp: mcpToolFor(capability), status: "absent", error: resolveError };
         }
     }
-    return { schemaVersion: 1, surface: "workbench", runId, resolved, ...(resolveError ? { error: resolveError } : {}), panels };
+    return { schemaVersion: 1, surface: "workbench", runId, resolved, ...(lifecycle ? { lifecycle } : {}), ...(resolveError ? { error: resolveError } : {}), panels };
 }
 /** Package-relative resolution only — never falls back to the invocation
  *  cwd. `ui/` ships as a sibling of `dist/` in the published package
@@ -143,7 +188,10 @@ function buildWorkbenchServeDescriptor(args = {}, boundPort) {
         surface: "workbench",
         command: "serve",
         host: "127.0.0.1",
-        port: boundPort ?? (args.port !== undefined ? Number(args.port) : exports.WORKBENCH_DEFAULT_PORT),
+        // `boundPort` (from a real listen()) is already a valid port. Otherwise
+        // validate the requested `--port` so the `--once`/`--json`/MCP descriptor
+        // path fails closed with a clear line instead of emitting `"port": null`.
+        port: boundPort ?? (parseWorkbenchPort(args.port) ?? exports.WORKBENCH_DEFAULT_PORT),
         once: Boolean(args.once),
         readOnly: true,
         scope: args.scope === "home" ? "home" : "repo",
@@ -158,13 +206,42 @@ function buildWorkbenchServeDescriptor(args = {}, boundPort) {
  *  list`), each embedded VERBATIM from its own already-declared capability
  *  handler — the Workbench adds no new source of truth. Composed the same
  *  way the panels are (findCapability(...).mcp.handler), so `/api/index`
- *  can never drift from the standalone `cw` commands. Read-only. */
+ *  can never drift from the standalone `cw` commands. Read-only.
+ *
+ *  When `args.text` names a non-blank filter (the Workbench UI's sidebar
+ *  filter box, `ui/workbench/app.js`'s `loadIndex`), the run list is filled
+ *  via the `run.search` capability instead of `run.list` — `run.list`'s own
+ *  handler (`runListCli` -> `RunRegistry.list()`) never reads a `text`
+ *  field, so calling it with a filter present would silently ignore it.
+ *  With no `text` filter the call is unchanged: `run.list`, byte-identical
+ *  to the payload before this branch existed. */
 function buildWorkbenchIndex(args = {}) {
     const scope = args.scope === "home" ? "home" : "repo";
     const scoped = { ...args, scope };
     const registryRow = (0, capability_table_1.findCapability)("registry.show");
-    const runListRow = (0, capability_table_1.findCapability)("run.list");
+    const text = typeof args.text === "string" ? args.text.trim() : "";
+    const runListRow = (0, capability_table_1.findCapability)(text ? "run.search" : "run.list");
     const registry = registryRow?.mcp ? registryRow.mcp.handler(scoped) : undefined;
-    const runs = runListRow?.mcp ? runListRow.mcp.handler(scoped) : [];
+    const runs = runListRow?.mcp ? newestRunPage(runListRow.mcp.handler, scoped) : [];
     return { schemaVersion: 1, surface: "workbench", command: "index", scope, registry, runs };
 }
+/** The run list/search handler sorts oldest-first and returns only the
+ *  first `limit` page — so the default page is the OLDEST runs, and a scope
+ *  with more runs than the page size never shows the newest run at all. The
+ *  Workbench wants the newest page: when the caller pinned no offset and the
+ *  total exceeds one page, re-fetch with the offset that lands on the last
+ *  page. The payload shape (total/offset/limit/records) is unchanged, so
+ *  the UI can still show "showing latest N of M". */
+function newestRunPage(handler, scoped) {
+    const first = handler(scoped);
+    if (scoped.offset !== undefined)
+        return first;
+    if (!first || typeof first !== "object")
+        return first;
+    const page = first;
+    const total = typeof page.total === "number" ? page.total : undefined;
+    const limit = typeof page.limit === "number" ? page.limit : undefined;
+    if (total === undefined || limit === undefined || total <= limit)
+        return first;
+    return handler({ ...scoped, offset: total - limit });
+}

package/dist/shell/worker-isolation.js

@@ -703,7 +703,7 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
         artifacts: [{ id: "result", kind: "markdown", path: destination }],
         evidence: resultNode.evidence.length ? resultNode.evidence : [{ id: "result:summary", source: "summary", summary: parsedResult.summary }],
         metadata: { taskId: task.id, workerId, resultNodeId: resultNode.id, sandboxProfileId: scope.sandboxProfileId },
-    }, { persist: false, persistNode: node_store_1.appendRunNode });
+    }, { persist: false, persistNode: node_store_1.appendRunNode, pathExists: fs.existsSync });
     task.verifierNodeId = verifierResult.outputNodeId;
     // Step 5: completion — persist the worker scope with the verify-derived status.
     const output = { workerId, taskId: task.id, resultPath: absoluteResultPath, recordedAt: new Date().toISOString(), stateNodeId: resultNode.id, verifierNodeId: task.verifierNodeId, auditEventIds: [pathAudit.id, acceptedAudit.id] };

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

@@ -78,6 +78,11 @@ function loadWorkflowAppLoader() {
     path: ["list"],
     jsonMode: "default",
     handler: () => ({ json: (0, registry_core_1.listBundledWorkflows)() }),
+    // UI/UX fix: a person at a real terminal used to get the raw JSON array.
+    // On a TTY (and only there — piped bytes stay the exact same JSON, see
+    // cli/dispatch.ts's shouldRenderHuman) render one "<id> — <title>" line
+    // per workflow plus the next-step footer.
+    humanRender: help_1.formatWorkflowList,
 });
 (0, registry_core_1.attachCliBinding)("status", {
     path: ["status"],