clinkx 0.3.0 → 1.0.0

package/dist/run-dir.js

@@ -1,8 +1,22 @@
-import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, closeSync, lstatSync, mkdtempSync, mkdirSync, openSync, readdirSync, readSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { logger } from "./logger.js";
+/** Cap on retained (idle-killed) run dirs kept under the runs base dir. */
+const MAX_RETAINED_RUN_DIRS = 20;
+const RETAINED_MARKER = ".retained";
+const STDERR_LOG = "stderr.log";
+/** Payload cap on retained stderr.log bytes (head + tail slices only); the truncation marker line adds ~50 bytes on top. */
+export const RETAINED_STDERR_MAX_BYTES = 1_048_576; // 1 MiB
+export const RETAINED_STDERR_HEAD_BYTES = 524_288; // 512 KiB
+export const RETAINED_STDERR_TAIL_BYTES = 524_288; // 512 KiB
+function isEnoent(err) {
+    return err?.code === "ENOENT";
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 /**
  * Create a per-run temp directory under ${TMPDIR}/clinkx/runs/<run_id>.
  *
@@ -29,4 +43,189 @@ export function createRunDir() {
         },
     };
 }
+/**
+ * Retain an idle-killed run dir as diagnostic evidence:
+ * - keep ONLY stderr.log; delete everything else (PROMPT.txt must not persist
+ *   without explicit debug_keep_artifacts opt-in, RESULT.md is absent or
+ *   incomplete on an idle kill, and CLI-created files are unbounded)
+ * - cap stderr.log at RETAINED_STDERR_MAX_BYTES via a head+tail slice
+ * - drop a `.retained` marker so retained dirs are identifiable
+ * - prune the oldest retained dirs beyond MAX_RETAINED_RUN_DIRS
+ *
+ * Runs post-termination, so there are no live-fd concerns. Fails CLOSED: if
+ * sanitization cannot complete for any non-ENOENT reason, the whole dir is
+ * removed instead of retained.
+ *
+ * @returns "retained" when the sanitized dir survives on disk, "cleaned" when
+ * the dir is confirmed gone instead (fail-closed removal or a race that
+ * deleted it), "cleanup_failed" when fail-closed removal could not be
+ * confirmed and the dir may still exist unsanitized.
+ */
+export function retainRunDir(path) {
+    try {
+        for (const entry of readdirSync(path, { withFileTypes: true })) {
+            if (entry.name === STDERR_LOG) {
+                // Reserved-name type check: keep stderr.log ONLY as a regular,
+                // non-symlink file. A directory or symlink under that name would
+                // bypass sanitization and the byte cap (lstat: isFile() is false
+                // for symlinks), so any other type falls through to deletion.
+                const st = lstatSync(join(path, entry.name), { throwIfNoEntry: false });
+                if (st?.isFile())
+                    continue;
+            }
+            // Everything else is deleted — including a type-confused stderr.log
+            // and any pre-existing `.retained` entry; the marker is written fresh
+            // below so it is always a regular file created by us.
+            rmSync(join(path, entry.name), { recursive: true, force: true });
+        }
+        // Runs only on the lstat-verified regular file (or a no-op when absent)
+        capRetainedStderr(join(path, STDERR_LOG));
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            // Run dir raced away entirely — nothing to retain, nothing left on disk
+            logger.debug({ run_dir: path }, "run dir disappeared before retention");
+            return "cleaned";
+        }
+        return failClosed(path, "sanitize", err);
+    }
+    try {
+        writeFileSync(join(path, RETAINED_MARKER), "");
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            // Dir raced away — nothing retained, nothing to prune for
+            logger.debug({ run_dir: path }, "run dir disappeared before retention marker write");
+            return "cleaned";
+        }
+        // An unmarked dir would evade the pruner's accounting — fail closed too
+        return failClosed(path, "write_marker", err);
+    }
+    pruneRetainedRunDirs(dirname(path));
+    return "retained";
+}
+/**
+ * Remove the run dir instead of retaining it. Reports the verified outcome:
+ * "cleaned" only when the dir is confirmed gone, else "cleanup_failed".
+ */
+function failClosed(path, operation, err) {
+    logger.warn({ run_dir: path, operation, err: errMessage(err) }, "retention sanitization failed — cleaning run dir instead of retaining");
+    let lastRmErr;
+    try {
+        rmSync(path, { recursive: true, force: true });
+    }
+    catch (rmErr) {
+        lastRmErr = rmErr;
+        // Sanitization failures are often permission damage (e.g. a read-only
+        // run dir) — repair the dir mode and retry removal once.
+        try {
+            chmodSync(path, 0o700);
+            rmSync(path, { recursive: true, force: true });
+            lastRmErr = undefined;
+        }
+        catch (retryErr) {
+            lastRmErr = retryErr;
+        }
+    }
+    // Verify removal with lstat, not existsSync: existsSync returns false when
+    // the path is merely INACCESSIBLE (e.g. parent dir mode 000 → EACCES on
+    // traversal), which would misreport a surviving dir as "cleaned". Only a
+    // definitive ENOENT confirms the dir is gone; any successful lstat or any
+    // other error (EACCES, EPERM, ...) means removal is unconfirmed.
+    try {
+        lstatSync(path);
+    }
+    catch (verifyErr) {
+        if (isEnoent(verifyErr))
+            return "cleaned";
+        lastRmErr ??= verifyErr;
+    }
+    logger.warn({ run_dir: path, err: errMessage(lastRmErr ?? "run dir still present after rmSync") }, "failed to remove run dir after retention sanitization failure");
+    return "cleanup_failed";
+}
+/**
+ * Rewrite an oversized stderr.log as first RETAINED_STDERR_HEAD_BYTES +
+ * truncation marker + last RETAINED_STDERR_TAIL_BYTES. Missing file (ENOENT)
+ * is fine — the child may never have written stderr. Other errors propagate
+ * to the fail-closed path in retainRunDir.
+ */
+function capRetainedStderr(stderrPath) {
+    let size;
+    try {
+        size = statSync(stderrPath).size;
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return;
+        throw err;
+    }
+    if (size <= RETAINED_STDERR_MAX_BYTES)
+        return;
+    const fd = openSync(stderrPath, "r");
+    let head;
+    let tail;
+    try {
+        head = readSlice(fd, 0, RETAINED_STDERR_HEAD_BYTES);
+        tail = readSlice(fd, size - RETAINED_STDERR_TAIL_BYTES, RETAINED_STDERR_TAIL_BYTES);
+    }
+    finally {
+        closeSync(fd);
+    }
+    const dropped = size - head.length - tail.length;
+    const marker = `\n... [clinkx: truncated ${dropped} bytes for retention] ...\n`;
+    writeFileSync(stderrPath, Buffer.concat([head, Buffer.from(marker), tail]));
+}
+function readSlice(fd, position, length) {
+    const buf = Buffer.alloc(length);
+    let offset = 0;
+    while (offset < length) {
+        const n = readSync(fd, buf, offset, length - offset, position + offset);
+        if (n === 0)
+            break;
+        offset += n;
+    }
+    return buf.subarray(0, offset);
+}
+function pruneRetainedRunDirs(base) {
+    let entries;
+    try {
+        entries = readdirSync(base, { withFileTypes: true });
+    }
+    catch (err) {
+        if (!isEnoent(err)) {
+            logger.debug({ base, err: errMessage(err) }, "failed to list runs base for retention pruning");
+        }
+        return;
+    }
+    const retained = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const dirPath = join(base, entry.name);
+        try {
+            // Marker mtime = retention time — the pruning sort key
+            retained.push({ path: dirPath, mtimeMs: statSync(join(dirPath, RETAINED_MARKER)).mtimeMs });
+        }
+        catch (err) {
+            // Not a retained dir (ENOENT), or raced away — skip
+            if (!isEnoent(err)) {
+                logger.debug({ dir: dirPath, err: errMessage(err) }, "failed to stat retention marker during pruning");
+            }
+        }
+    }
+    if (retained.length <= MAX_RETAINED_RUN_DIRS)
+        return;
+    retained.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (const victim of retained.slice(MAX_RETAINED_RUN_DIRS)) {
+        try {
+            rmSync(victim.path, { recursive: true, force: true });
+        }
+        catch (err) {
+            // Raced with another prune (ENOENT) — fine
+            if (!isEnoent(err)) {
+                logger.debug({ dir: victim.path, err: errMessage(err) }, "failed to prune retained run dir");
+            }
+        }
+    }
+}
 //# sourceMappingURL=run-dir.js.map

package/dist/run-dir.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-dir.js","sourceRoot":"","sources":["../src/run-dir.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAQrC;;;;;GAKG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC;IAElD,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,uBAAuB,CAAC,CAAC;IAEvD,OAAO;QACL,IAAI;QACJ,KAAK;QACL,OAAO;YACL,IAAI,CAAC;gBACH,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC/C,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,0BAA0B,CAAC,CAAC;YACtD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,kCAAkC,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"run-dir.js","sourceRoot":"","sources":["../src/run-dir.ts"],"names":[],"mappings":"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"}

package/dist/runner.d.ts

@@ -1,7 +1,17 @@
 import { type ChildProcess } from "node:child_process";
 import type { CliAdapterConfig } from "./config.js";
+import type { SessionLogOwnerV1 } from "../clinkx-workflows/dist/dashboard/session-log-contract.js";
 /** Active subprocess registry for graceful shutdown. */
 export declare const activeProcesses: Set<ChildProcess>;
+/** Synchronously prevent every future generic subprocess admission. */
+export declare function latchSubprocessAdmissionForShutdown(): void;
+/**
+ * Test-only reset for the process-wide admission latch and deterministic race
+ * hook. Tests that call this own the cleanup and must leave no active child.
+ */
+export declare function resetSubprocessAdmissionForTest(): void;
+/** Test-only seam for forcing the post-spawn shutdown race deterministically. */
+export declare function setAfterSpawnRegisteredForTest(hook: ((child: ChildProcess) => void) | undefined): void;
 /** Kill all subprocesses tracked when shutdown begins. */
 export declare function killAllActive(): Promise<void>;
 export interface RunOptions {
@@ -12,6 +22,9 @@ export interface RunOptions {
     idleTimeoutSeconds?: number | undefined;
     idleTimeoutStartupSeconds?: number | undefined;
     signal?: AbortSignal | undefined;
+    sessionLogOwner?: SessionLogOwnerV1 | undefined;
+    /** Internal storage-root override for focused tests. */
+    sessionLogRootDir?: string | undefined;
 }
 export interface RunResult {
     exitCode: number | null;

package/dist/runner.js

@@ -3,44 +3,76 @@ import { openSync, closeSync, readSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { logger } from "./logger.js";
 import { ExecutionError } from "./errors.js";
+import { getStateDir } from "../clinkx-workflows/dist/config.js";
 import { buildEnv, redactSecrets } from "./env.js";
 import { preparePromptDelivery } from "./prompt-mode.js";
 import { assertNoTtyRequired, resolveArgs } from "./safety.js";
+import { createProviderSessionLogProducer } from "./session-log-stream.js";
 /** Active subprocess registry for graceful shutdown. */
 export const activeProcesses = new Set();
+let subprocessAdmissionClosed = false;
+let afterSpawnRegisteredForTest;
+/** Synchronously prevent every future generic subprocess admission. */
+export function latchSubprocessAdmissionForShutdown() {
+    subprocessAdmissionClosed = true;
+}
+/**
+ * Test-only reset for the process-wide admission latch and deterministic race
+ * hook. Tests that call this own the cleanup and must leave no active child.
+ */
+export function resetSubprocessAdmissionForTest() {
+    subprocessAdmissionClosed = false;
+    afterSpawnRegisteredForTest = undefined;
+}
+/** Test-only seam for forcing the post-spawn shutdown race deterministically. */
+export function setAfterSpawnRegisteredForTest(hook) {
+    afterSpawnRegisteredForTest = hook;
+}
+function shutdownAdmissionError() {
+    return new ExecutionError("Server is shutting down; subprocess admission is closed");
+}
 const ROOT_SHUTDOWN_GRACE_MS = 3_000;
 /** Kill all subprocesses tracked when shutdown begins. */
 export async function killAllActive() {
-    const snapshot = [...activeProcesses];
-    if (snapshot.length === 0)
+    const deadline = Date.now() + ROOT_SHUTDOWN_GRACE_MS;
+    const initialSnapshot = [...activeProcesses];
+    if (initialSnapshot.length === 0)
         return;
-    for (const child of snapshot) {
+    for (const child of initialSnapshot) {
         killProcessGroup(child, "SIGTERM");
     }
     // Wait for grace period, but resolve early if all children have exited
     await new Promise((resolve) => {
-        const timer = setTimeout(resolve, ROOT_SHUTDOWN_GRACE_MS);
+        const timer = setTimeout(resolve, Math.max(0, deadline - Date.now()));
         const interval = setInterval(() => {
-            if (snapshot.every((c) => !activeProcesses.has(c))) {
+            if (activeProcesses.size === 0) {
                 clearTimeout(timer);
                 clearInterval(interval);
                 resolve();
             }
         }, 50);
-        setTimeout(() => clearInterval(interval), ROOT_SHUTDOWN_GRACE_MS).unref();
+        setTimeout(() => clearInterval(interval), Math.max(0, deadline - Date.now())).unref();
     });
-    for (const child of snapshot) {
-        if (activeProcesses.has(child)) {
-            killProcessGroup(child, "SIGKILL");
-        }
+    // Drain the live registry, not the initial snapshot: a child registered
+    // during shutdown is still owned and must not survive the sweep.
+    // Escalate every group observed at shutdown entry as well as children still
+    // registered now. The direct child can exit after SIGTERM while a descendant
+    // forked at that boundary remains in its process group; dropping the initial
+    // handle here would orphan that descendant.
+    const escalationSnapshot = new Set([...initialSnapshot, ...activeProcesses]);
+    for (const child of escalationSnapshot) {
+        killProcessGroup(child, "SIGKILL");
     }
 }
 const DEFAULT_MAX_PROMPT_BYTES = 1_048_576; // 1 MB
 const DEFAULT_TIMEOUT_SECONDS = 600;
 const DEFAULT_MAX_CAPTURE_BYTES = 2_097_152; // 2 MB default capture retention
 const GRACE_PERIOD_MS = 5_000;
+const STDERR_POLL_INTERVAL_MS = 1_000;
 const DEFAULT_IDLE_TIMEOUT_SECONDS = 0;
 const DEFAULT_IDLE_TIMEOUT_STARTUP_SECONDS = 180;
+// Per-line cap for the provider session-log stream, in characters.
+const DEFAULT_SESSION_LOG_MAX_LINE_CHARS = 1024 * 1024;
 function safeParseInt(val, fallback) {
     if (val == null || val === "")
         return fallback;
@@ -132,22 +164,28 @@ function killProcessGroup(child, sig) {
  */
 export function runSubprocess(options) {
     const { adapter, prompt, runDirPath, signal } = options;
+    if (subprocessAdmissionClosed) {
+        return Promise.reject(shutdownAdmissionError());
+    }
     const timeoutSeconds = options.timeoutSeconds ??
         adapter.timeout_seconds ??
         safeParseInt(process.env["CLINKX_TIMEOUT_SECONDS"], DEFAULT_TIMEOUT_SECONDS);
     // Idle timeout resolution: RunOptions > adapter config > env var > default
-    // Suppress-stdout guard: when stdout is suppressed, CLI produces no stdout — disable idle
-    const suppressesStdout = adapter.suppress_stdout === true;
-    const idleTimeoutSeconds = suppressesStdout ? 0 :
+    // Suppress-stdout guard: when stdout is suppressed there is no stdout to
+    // observe, but stderr_to_file polling still provides a byte-activity
+    // channel — only zero the idle timeouts when no observable channel remains.
+    const noObservableChannel = adapter.suppress_stdout === true && adapter.stderr_to_file !== true;
+    const idleTimeoutSeconds = noObservableChannel ? 0 :
         (options.idleTimeoutSeconds ??
             adapter.idle_timeout_seconds ??
             safeParseIntNonNeg(process.env["CLINKX_IDLE_TIMEOUT_SECONDS"], DEFAULT_IDLE_TIMEOUT_SECONDS));
-    const idleStartupSeconds = suppressesStdout ? 0 :
+    const idleStartupSeconds = noObservableChannel ? 0 :
         (options.idleTimeoutStartupSeconds ??
             adapter.idle_timeout_startup_seconds ??
             safeParseIntNonNeg(process.env["CLINKX_IDLE_TIMEOUT_STARTUP_SECONDS"], DEFAULT_IDLE_TIMEOUT_STARTUP_SECONDS));
     const maxPromptBytes = safeParseInt(process.env["CLINKX_MAX_PROMPT_BYTES"], DEFAULT_MAX_PROMPT_BYTES);
     const maxCaptureBytes = safeParseInt(process.env["CLINKX_MAX_CAPTURE_BYTES"] ?? process.env["CLINKX_MAX_OUTPUT_BYTES"], DEFAULT_MAX_CAPTURE_BYTES);
+    const sessionLogMaxLineChars = safeParseInt(process.env["CLINKX_SESSION_LOG_MAX_LINE_CHARS"], DEFAULT_SESSION_LOG_MAX_LINE_CHARS);
     // Bound input size
     const promptBuf = Buffer.from(prompt, "utf-8");
     if (promptBuf.length > maxPromptBytes) {
@@ -160,7 +198,6 @@ export function runSubprocess(options) {
     catch (err) {
         return Promise.reject(err);
     }
-    // Build args
     const args = resolveArgs(adapter.args, adapter.unsafe_args);
     if (adapter.native_output_file_flag && adapter.result_contract.enabled) {
         args.push(adapter.native_output_file_flag, join(runDirPath, adapter.result_contract.filename));
@@ -191,6 +228,7 @@ export function runSubprocess(options) {
         let timeoutHandle;
         let graceHandle;
         let idleHandle;
+        let stderrPollHandle;
         let stderrFd;
         const stderrFilePath = adapter.stderr_to_file
             ? join(runDirPath, "stderr.log")
@@ -198,6 +236,14 @@ export function runSubprocess(options) {
         if (stderrFilePath != null) {
             stderrFd = openSync(stderrFilePath, "w");
         }
+        // Load-bearing second check: argument/env preparation can race shutdown.
+        // This is the final point before the OS process can be created.
+        if (subprocessAdmissionClosed) {
+            if (stderrFd != null)
+                closeSync(stderrFd);
+            reject(shutdownAdmissionError());
+            return;
+        }
         let child;
         try {
             child = spawn(adapter.command, args, {
@@ -224,6 +270,27 @@ export function runSubprocess(options) {
             stderrFd = undefined;
         }
         activeProcesses.add(child);
+        // Test-only synchronization point. Production has no callback here.
+        afterSpawnRegisteredForTest?.(child);
+        // Shutdown can latch in the narrow spawn->registration window. Kill the
+        // entire newly-created group, retain registry ownership until close/error,
+        // and reject the request instead of admitting work after the drain began.
+        if (subprocessAdmissionClosed) {
+            const releaseRacingChild = () => {
+                // Re-sweep after the direct child exits: a shell can fork a descendant
+                // at the same instant the first group signal selects its recipients.
+                killProcessGroup(child, "SIGKILL");
+                activeProcesses.delete(child);
+            };
+            child.once("error", releaseRacingChild);
+            child.once("close", releaseRacingChild);
+            killProcessGroup(child, "SIGKILL");
+            child.stdin?.destroy();
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            reject(shutdownAdmissionError());
+            return;
+        }
         // Shared kill guard — prevents double-SIGTERM races across wall/idle/cancel paths
         function initiateKill(reason) {
             if (killInitiated)
@@ -234,6 +301,7 @@ export function runSubprocess(options) {
             clearTimeout(timeoutHandle);
             clearTimeout(idleHandle);
             clearTimeout(graceHandle); // clear stale grace handle (killInitiated prevents re-entry)
+            clearInterval(stderrPollHandle);
             if (reason === "wall")
                 timedOut = true;
             if (reason === "idle")
@@ -247,6 +315,41 @@ export function runSubprocess(options) {
                 killProcessGroup(child, "SIGKILL");
             }, GRACE_PERIOD_MS);
         }
+        const stderrPollingEnabled = stderrFilePath != null && (idleStartupSeconds > 0 || idleTimeoutSeconds > 0);
+        let lastStderrSize = 0;
+        // Set when an idle-expiry stat failed once. Cleared ONLY by observed byte
+        // activity (any probe) or a successful stat AT expiry time — a quiet
+        // interval tick must not clear it, or an alternating expiry-failure /
+        // quiet-tick pattern would re-arm the idle timer forever. A second
+        // unresolved expiry failure proceeds with the kill so a permanently
+        // unreadable stderr file cannot make the child unkillable.
+        // Deferred regression coverage: deterministically proving the
+        // quiet-tick-must-NOT-clear semantics needs an injectable stat probe or
+        // fake timers; a revert of that semantics would pass the current suite.
+        let idleExpiryStatFailed = false;
+        // Shared by the poll tick and the idle-expiry last-chance check so the two
+        // activity detectors cannot drift. Any size change (growth or truncation)
+        // counts as byte activity.
+        function probeStderrFile() {
+            if (stderrFilePath == null)
+                return "quiet";
+            let size;
+            try {
+                size = statSync(stderrFilePath).size;
+            }
+            catch {
+                // stat failure this tick is non-fatal — try again next tick
+                return "stat_failed";
+            }
+            if (size !== lastStderrSize) {
+                lastStderrSize = size;
+                receivedFirstByte = true;
+                // Byte activity anywhere is conclusive — safe to disarm fail-open
+                idleExpiryStatFailed = false;
+                return "active";
+            }
+            return "quiet";
+        }
         // Idle timer: resets on any data from stdout or stderr
         function resetIdleTimer() {
             if (killInitiated)
@@ -260,6 +363,30 @@ export function runSubprocess(options) {
             idleHandle = setTimeout(() => {
                 if (killInitiated)
                     return;
+                // Last-chance re-check: with an idle timeout <= poll interval, the
+                // expiry can fire before the next poll tick observes fresh stderr
+                // bytes — never kill a child on a stale size reading.
+                if (stderrPollingEnabled) {
+                    const probe = probeStderrFile();
+                    if (probe === "active") {
+                        resetIdleTimer();
+                        return;
+                    }
+                    if (probe === "quiet") {
+                        // A successful stat AT expiry is conclusive (genuinely no
+                        // activity) — disarm the fail-open flag so it cannot linger and
+                        // be consumed by a later, unrelated expiry failure.
+                        idleExpiryStatFailed = false;
+                    }
+                    if (probe === "stat_failed" && !idleExpiryStatFailed) {
+                        // A transient stat failure is inconclusive, not "no activity" —
+                        // don't kill a possibly-active child on it. Give it exactly one
+                        // more idle window; a second consecutive failure proceeds.
+                        idleExpiryStatFailed = true;
+                        resetIdleTimer();
+                        return;
+                    }
+                }
                 idlePhase = receivedFirstByte ? "inter_byte" : "startup";
                 idleTimeoutEffective = receivedFirstByte ? idleTimeoutSeconds : idleStartupSeconds;
                 initiateKill("idle");
@@ -269,19 +396,42 @@ export function runSubprocess(options) {
             ? { capture: { head: Buffer.alloc(0), tail: Buffer.alloc(0), totalBytes: 0, truncated: false }, onData(_chunk) { } }
             : createStreamCapture(maxCaptureBytes);
         const stderrCapture = createStreamCapture(maxCaptureBytes);
+        let sessionLogProducer;
+        if (options.sessionLogOwner !== undefined &&
+            (adapter.parser === "codex_jsonl" || adapter.parser === "claude_stream_json")) {
+            try {
+                sessionLogProducer = createProviderSessionLogProducer({
+                    parser: adapter.parser,
+                    owner: options.sessionLogOwner,
+                    rootDir: options.sessionLogRootDir ?? join(getStateDir(), "session-logs"),
+                    prompt,
+                    maxPartialLineChars: sessionLogMaxLineChars,
+                });
+            }
+            catch {
+                logger.debug({ producerFamily: options.sessionLogOwner.family }, "provider session-log admission failed open");
+            }
+        }
         child.stdout?.on("data", (chunk) => {
             if (chunk.length === 0)
                 return;
             if (!receivedFirstByte)
                 receivedFirstByte = true;
+            // Pipe bytes are conclusive activity — restore the one-shot
+            // expiry-stat-failure grace window, matching probeStderrFile()
+            idleExpiryStatFailed = false;
             resetIdleTimer();
             stdoutCapture.onData(chunk);
+            sessionLogProducer?.onStdout(chunk);
         });
         child.stderr?.on("data", (chunk) => {
             if (chunk.length === 0)
                 return;
             if (!receivedFirstByte)
                 receivedFirstByte = true;
+            // Pipe bytes are conclusive activity — restore the one-shot
+            // expiry-stat-failure grace window, matching probeStderrFile()
+            idleExpiryStatFailed = false;
             resetIdleTimer();
             stderrCapture.onData(chunk);
         });
@@ -300,6 +450,17 @@ export function runSubprocess(options) {
         }, timeoutSeconds * 1_000);
         // Arm idle timer immediately after spawn
         resetIdleTimer();
+        // File-backed stderr produces no 'data' events, so the idle timer would
+        // only see stdout — for CLIs that write stdout at the very end, that makes
+        // startup-idle detection kill healthy turns. Poll stderr file size growth
+        // as the byte-activity signal instead (size only, contents never read).
+        if (stderrPollingEnabled) {
+            stderrPollHandle = setInterval(() => {
+                if (probeStderrFile() === "active")
+                    resetIdleTimer();
+            }, STDERR_POLL_INTERVAL_MS);
+            stderrPollHandle.unref();
+        }
         // Cancellation via AbortSignal
         const onAbort = () => {
             initiateKill("cancel");
@@ -316,16 +477,24 @@ export function runSubprocess(options) {
             clearTimeout(timeoutHandle);
             clearTimeout(idleHandle);
             clearTimeout(graceHandle);
+            clearInterval(stderrPollHandle);
             signal?.removeEventListener("abort", onAbort);
             activeProcesses.delete(child);
+            sessionLogProducer?.finish("failed");
             reject(new ExecutionError(`Failed to spawn "${adapter.command}": ${err.message}`));
         });
         child.on("close", (code, exitSignal) => {
             clearTimeout(timeoutHandle);
             clearTimeout(idleHandle);
             clearTimeout(graceHandle);
+            clearInterval(stderrPollHandle);
             signal?.removeEventListener("abort", onAbort);
             activeProcesses.delete(child);
+            sessionLogProducer?.finish(terminationReason === "cancel"
+                ? "cancelled"
+                : terminationReason === "wall" || terminationReason === "idle"
+                    ? "timeout"
+                    : code === 0 ? "completed" : "failed");
             // Post-mortem stderr hydration from file-backed capture
             if (stderrFilePath != null) {
                 try {