@pentoshi/clai 4.11.7 → 4.11.9

package/dist/tools/jobs.js

@@ -1,373 +1,20 @@
-import { spawn, execFileSync } from "node:child_process";
-import { createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { mkdir, open, stat } from "node:fs/promises";
 import { basename, join, sep } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
-import { StringDecoder } from "node:string_decoder";
 import { redactSecrets } from "../llm/provider.js";
 import { safeCwd } from "../os/cwd.js";
 import { getJobsDir } from "../store/paths.js";
 import { resolveShell } from "./shell.js";
 import { terminateProcessTree } from "../os/process-tree.js";
-/**
- * Responder-owned jobs are push-delivered and must not be polled. Normal jobs
- * remain pollable, including mixed sessions with a visible terminal normal job.
- */
-const LIVE_JOB_STATUSES = new Set([
-    "starting",
-    "running",
-    "stopping",
-]);
-export function responderPollingPolicy(input) {
-    // Only a still-running Responder job can be polled in a loop. Once it is
-    // terminal its output is fixed, so reading it is a normal bounded read and
-    // blocking it would remove the only way to inspect the full result.
-    if (input.call.name === "shell.tail" &&
-        input.targetJob?.responder &&
-        LIVE_JOB_STATUSES.has(input.targetJob.status)) {
-        return {
-            blocked: true,
-            reason: `Responder owns job ${input.targetJob.id}; shell.tail was not dispatched. ` +
-                "This job is fire-and-continue: its terminal result will be delivered automatically. " +
-                "Continue other work, and call job.read only after analyzing that delivered completion.",
-        };
-    }
-    if (input.call.name === "shell.jobs") {
-        const recent = input.recentJobs ?? [];
-        const runningResponderJobs = recent.filter((job) => job.responder && LIVE_JOB_STATUSES.has(job.status));
-        const visibleNormalJobs = recent.filter((job) => !job.responder);
-        if (runningResponderJobs.length > 0 && visibleNormalJobs.length === 0) {
-            const ids = runningResponderJobs.map((job) => job.id).join(", ");
-            return {
-                blocked: true,
-                reason: `shell.jobs was not dispatched because the only running background job(s) (${ids}) are Responder-owned. ` +
-                    "They are fire-and-continue and their terminal results will be delivered automatically. " +
-                    "Continue other work; do not sleep or poll, and call job.read only after analyzing a delivered completion.",
-            };
-        }
-    }
-    return { blocked: false };
-}
-export function formatJobElapsed(job, now = Date.now()) {
-    const startedAt = Date.parse(job.startedAt);
-    const endedAt = job.endedAt ? Date.parse(job.endedAt) : now;
-    if (!Number.isFinite(startedAt) || !Number.isFinite(endedAt))
-        return "unknown";
-    const seconds = Math.max(0, Math.floor((endedAt - startedAt) / 1000));
-    if (seconds < 1)
-        return "<1s";
-    if (seconds < 60)
-        return `${seconds}s`;
-    const minutes = Math.floor(seconds / 60);
-    return `${minutes}m${seconds % 60}s`;
-}
-function displayArg(value) {
-    return /^[A-Za-z0-9_./:=@+-]+$/.test(value)
-        ? value
-        : JSON.stringify(value);
-}
-function commandDisplay(command) {
-    if (typeof command === "string")
-        return command;
-    return command.display ?? [command.command, ...command.argv].map(displayArg).join(" ");
-}
-function launchFollowUp(id, responder) {
-    return responder
-        ? "Responder owns completion tracking for this self-completing job. " +
-            "Do not poll it with shell.tail/shell.jobs, sleep, or read its artifact. " +
-            "Continue other work; if not already delivered, its terminal result will be delivered automatically."
-        : "OS launch does not prove application readiness or continued liveness. " +
-            `If this command is finite, block once with shell.wait {"id":"${id}"} rather than polling for status; ` +
-            "repeated identical polls return no new information and are refused. " +
-            `If it is a persistent server or watcher, run an application readiness probe and read new output with shell.tail {"id":"${id}"} using nextOffset. ` +
-            "Do not launch a duplicate.";
-}
-const PER_FILE_BYTES = 1024 * 1024;
-const MAX_STREAM_BYTES = 16 * 1024 * 1024;
-const DEFAULT_TAIL_BYTES = 8_000;
-const WAIT_JOB_DEFAULT_TIMEOUT_MS = 120_000;
-const WAIT_JOB_MAX_TIMEOUT_MS = 600_000;
-const WAIT_JOB_INTERVAL_MS = 500;
-const WAIT_JOB_TAIL_BYTES = 4_000;
-const REGISTRY_FILE = "registry-v1.json";
-const TRANSIENT_V2_REGISTRY_FILE = "registry-v2.json";
-/** Cap durable terminal jobs kept on disk/in memory (per process). */
-const MAX_DURABLE_TERMINAL_JOBS = 80;
-/** Drop terminal durable jobs older than this on load/list. */
-const TERMINAL_JOB_MAX_AGE_MS = 48 * 60 * 60 * 1000;
-const ARCHIVED_UNSETTLED_MAX_AGE_MS = 24 * 60 * 60 * 1000;
-const MAX_ARCHIVED_UNSETTLED_NOTIFICATIONS = 40;
-const MAX_SUPERSEDED_REVISIONS = 5;
-const SETTLEMENT_MAX_BACKOFF_MS = 30_000;
-const LIVENESS_WATCH_INTERVAL_MS = 2_000;
-const SETTLEMENT_DEAD_LETTER_MS = 10 * 60_000;
-/** Max lines shell.jobs returns to the model (running first, then recent). */
-const LIST_JOBS_MAX_LINES = 40;
-/** Coalesce window for chatty stdout/stderr progress persistence + UI events. */
-const PROGRESS_FLUSH_MS = 250;
-/** Durable registry cadence for running-job progress (UI updates stay at 250ms). */
-const DURABLE_PROGRESS_FLUSH_MS = 5_000;
-/**
- * A live job with no in-process ChildProcess handle (resumed session, or a
- * handle that was released) is only declared "lost" after failing the liveness
- * check continuously for this long. A single transient `ps`/`kill` hiccup — or
- * an identity read that momentarily fails — must never finalize a job that is
- * actually still running (which produced premature "result ready", a "<1s"
- * elapsed, and a ✗ status=lost that later flipped back to exit=0).
- */
-const LIVENESS_LOST_GRACE_MS = 8_000;
-/** Minimum spacing between liveness probes for the same job. */
-const LIVENESS_PROBE_INTERVAL_MS = 1_000;
-/**
- * Number of trailing bytes in `buf` that form an incomplete multi-byte UTF-8
- * sequence (a lead byte whose continuation bytes were cut off by the read
- * boundary). Returns 0 if the buffer already ends on a complete character.
- */
-function trailingIncompleteBytes(buf) {
-    const len = buf.length;
-    for (let back = 1; back <= 3 && back <= len; back++) {
-        const byte = buf[len - back];
-        if ((byte & 0xc0) === 0x80)
-            continue; // continuation byte, keep walking back
-        let expectedLen = 1;
-        if ((byte & 0xe0) === 0xc0)
-            expectedLen = 2;
-        else if ((byte & 0xf0) === 0xe0)
-            expectedLen = 3;
-        else if ((byte & 0xf8) === 0xf0)
-            expectedLen = 4;
-        return expectedLen > back ? back : 0;
-    }
-    return 0;
-}
-function processAlive(pid) {
-    if (!pid)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        // EPERM means the process EXISTS but we lack permission to signal it
-        // (common for detached jobs in another process group) — that is alive, not
-        // gone. Only ESRCH ("no such process") proves it is truly dead.
-        return error.code === "EPERM";
-    }
-}
-/** Identity is invariant for a pid's lifetime, so it caches safely. */
-const PROCESS_IDENTITY_TTL_MS = 15_000;
-const PROCESS_IDENTITY_CACHE_MAX = 512;
-const processIdentityCache = new Map();
-function readLinuxProcessStart(pid) {
-    try {
-        const raw = readFileSync(`/proc/${pid}/stat`, "utf8");
-        const commEnd = raw.lastIndexOf(")");
-        if (commEnd < 0)
-            return undefined;
-        const fields = raw.slice(commEnd + 2).trim().split(/\s+/);
-        const startTime = fields[19];
-        return startTime && startTime.length > 0 ? startTime : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function readPsProcessStart(pid) {
-    try {
-        // Start time only: the command line is deliberately excluded — `sh -c "cmd"`
-        // execs into `cmd`, mutating `ps command=` mid-run, which made a live job
-        // fail its OWN identity check.
-        return execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
-            encoding: "utf8",
-            timeout: 2_000,
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-    }
-    catch {
-        return undefined;
-    }
-}
-function computeProcessIdentity(pid) {
-    const raw = process.platform === "linux"
-        ? readLinuxProcessStart(pid)
-        : readPsProcessStart(pid);
-    return raw ? createHash("sha256").update(raw).digest("hex") : undefined;
-}
-function pruneProcessIdentityCache(now) {
-    if (processIdentityCache.size <= PROCESS_IDENTITY_CACHE_MAX)
-        return;
-    for (const [pid, entry] of processIdentityCache) {
-        if (now - entry.at >= PROCESS_IDENTITY_TTL_MS)
-            processIdentityCache.delete(pid);
-    }
-    if (processIdentityCache.size > PROCESS_IDENTITY_CACHE_MAX) {
-        processIdentityCache.clear();
-    }
-}
-function forgetProcessIdentity(pid) {
-    if (pid)
-        processIdentityCache.delete(pid);
-}
-function processIdentity(pid, options = {}) {
-    if (!pid || process.platform === "win32")
-        return undefined;
-    const now = Date.now();
-    const cached = processIdentityCache.get(pid);
-    if (cached &&
-        !options.refresh &&
-        now - cached.at < PROCESS_IDENTITY_TTL_MS) {
-        return cached.value;
-    }
-    const value = computeProcessIdentity(pid);
-    processIdentityCache.set(pid, { value, at: now });
-    pruneProcessIdentityCache(now);
-    return value;
-}
-/**
- * Heuristic for legacy registry rows that were actually agent tool-stall
- * trackers (commandDisplay = "fs.list /path", "shell.jobs {}", …), not real
- * shell.start / auto-backgrounded processes.
- */
-function looksLikeEphemeralToolTrack(job) {
-    if (job.kind === "ephemeral")
-        return true;
-    const cmd = (job.commandDisplay || job.command || "").trim();
-    // Real OS commands rarely look like "tool.name …" dotted tool registry names.
-    if (/^(fs|shell|tool|web|http|net|pdf|image|pkg|dns|whois|plan|task|pentest|sysinfo)\.[a-zA-Z]+(\s|$)/.test(cmd)) {
-        return true;
-    }
-    // Empty artifact paths = never a real background process capture.
-    if (!job.stdoutArtifact && !job.artifactPath && !job.pid)
-        return true;
-    return false;
-}
-class RotatingRedactedWriter {
-    receipt;
-    stream;
-    streamDone;
-    completedStreams = [];
-    index = 0;
-    currentBytes = 0;
-    hash = createHash("sha256");
-    decoder = new StringDecoder("utf8");
-    pending = "";
-    closePromise;
-    writeError;
-    closed = false;
-    acceptedBytes;
-    backpressuredStreams = new Set();
-    static REDACTION_OVERLAP_CHARS = 4096;
-    constructor(receipt) {
-        this.receipt = receipt;
-        this.acceptedBytes = receipt.bytes;
-    }
-    append(raw) {
-        if (this.closed)
-            throw new Error("Cannot append to a closed job artifact");
-        this.pending += Buffer.isBuffer(raw) ? this.decoder.write(raw) : raw;
-        let writable = true;
-        const lastNewline = this.pending.lastIndexOf("\n");
-        if (lastNewline >= 0) {
-            writable = this.writeRedacted(this.pending.slice(0, lastNewline + 1));
-            this.pending = this.pending.slice(lastNewline + 1);
-        }
-        if (this.pending.length <= RotatingRedactedWriter.REDACTION_OVERLAP_CHARS) {
-            return writable;
-        }
-        const flushLength = this.pending.length - RotatingRedactedWriter.REDACTION_OVERLAP_CHARS;
-        writable = this.writeRedacted(this.pending.slice(0, flushLength)) && writable;
-        this.pending = this.pending.slice(flushLength);
-        return writable;
-    }
-    waitForDrain() {
-        const blocked = [...this.backpressuredStreams].filter((stream) => stream.writableNeedDrain);
-        if (blocked.length === 0)
-            return Promise.resolve();
-        return Promise.all(blocked.map((stream) => new Promise((resolve) => {
-            const done = () => {
-                stream.off("drain", done);
-                stream.off("finish", done);
-                stream.off("error", done);
-                this.backpressuredStreams.delete(stream);
-                resolve();
-            };
-            stream.once("drain", done);
-            stream.once("finish", done);
-            stream.once("error", done);
-        }))).then(() => undefined);
-    }
-    close() {
-        if (this.closePromise)
-            return this.closePromise;
-        this.pending += this.decoder.end();
-        if (this.pending)
-            this.writeRedacted(this.pending);
-        this.pending = "";
-        this.closed = true;
-        this.finishCurrentStream();
-        this.closePromise = Promise.all(this.completedStreams).then(() => {
-            if (this.writeError)
-                throw this.writeError;
-        });
-        return this.closePromise;
-    }
-    writeRedacted(source) {
-        const safe = redactSecrets(source);
-        if (safe !== source)
-            this.receipt.redacted = true;
-        let data = Buffer.from(safe, "utf8");
-        const remaining = Math.max(0, MAX_STREAM_BYTES - this.acceptedBytes);
-        if (data.length > remaining) {
-            this.receipt.droppedBytes += data.length - remaining;
-            data = data.subarray(0, remaining);
-        }
-        this.acceptedBytes += data.length;
-        let writable = true;
-        while (data.length > 0) {
-            if (!this.stream || this.currentBytes >= PER_FILE_BYTES)
-                this.rotate();
-            const room = PER_FILE_BYTES - this.currentBytes;
-            const part = data.subarray(0, room);
-            const stream = this.stream;
-            const accepted = stream.write(part);
-            if (!accepted)
-                this.backpressuredStreams.add(stream);
-            writable = accepted && writable;
-            this.hash.update(part);
-            this.receipt.bytes += part.length;
-            this.receipt.sha256 = this.hash.copy().digest("hex");
-            this.currentBytes += part.length;
-            data = data.subarray(part.length);
-        }
-        return writable;
-    }
-    finishCurrentStream() {
-        if (!this.stream || !this.streamDone)
-            return;
-        const stream = this.stream;
-        const done = this.streamDone;
-        this.stream = undefined;
-        this.streamDone = undefined;
-        stream.end();
-        this.completedStreams.push(done);
-    }
-    rotate() {
-        this.finishCurrentStream();
-        const path = this.index === 0 ? this.receipt.path : `${this.receipt.path}.${this.index}`;
-        this.index += 1;
-        this.currentBytes = 0;
-        this.receipt.chunks.push(path);
-        const stream = createWriteStream(path, { flags: "w", mode: 0o600 });
-        this.stream = stream;
-        this.streamDone = new Promise((resolve) => {
-            stream.once("finish", resolve);
-            stream.once("error", (error) => {
-                this.writeError ??= error;
-                resolve();
-            });
-        });
-    }
-}
+import { forgetProcessIdentity, processAlive, processIdentity } from "./jobs/process-identity.js";
+import { RotatingRedactedWriter } from "./jobs/redacted-writer.js";
+import { responderPollingPolicy } from "./jobs/polling-policy.js";
+import { ARCHIVED_UNSETTLED_MAX_AGE_MS, DEFAULT_TAIL_BYTES, DURABLE_PROGRESS_FLUSH_MS, LIST_JOBS_MAX_LINES, LIVENESS_LOST_GRACE_MS, LIVENESS_PROBE_INTERVAL_MS, LIVENESS_WATCH_INTERVAL_MS, MAX_ARCHIVED_UNSETTLED_NOTIFICATIONS, MAX_DURABLE_TERMINAL_JOBS, MAX_SUPERSEDED_REVISIONS, PROGRESS_FLUSH_MS, REGISTRY_FILE, SETTLEMENT_DEAD_LETTER_MS, SETTLEMENT_MAX_BACKOFF_MS, TERMINAL_JOB_MAX_AGE_MS, TRANSIENT_V2_REGISTRY_FILE, WAIT_JOB_DEFAULT_TIMEOUT_MS, WAIT_JOB_INTERVAL_MS, WAIT_JOB_MAX_TIMEOUT_MS, WAIT_JOB_TAIL_BYTES } from "./jobs/limits.js";
+import { commandDisplay, formatJobElapsed, launchFollowUp, looksLikeEphemeralToolTrack, trailingIncompleteBytes } from "./jobs/helpers.js";
+export { formatJobElapsed };
+export { responderPollingPolicy };
 export class JobManager {
     jobsDir;
     jobs = new Map();
@@ -384,12 +31,6 @@ export class JobManager {
     livenessWatchTimer;
     finalizations = new Map();
     listeners = new Set();
-    /**
-     * Tracks the first time a live job (with no ChildProcess handle) failed the
-     * liveness check, so we only finalize it as "lost" after a sustained grace
-     * window instead of on a single transient miss. Cleared as soon as the job is
-     * observed alive again or finalized.
-     */
     livenessMisses = new Map();
     livenessCheckedAt = new Map();
     registryRetryTimer;
@@ -414,7 +55,6 @@ export class JobManager {
             ...(job.artifacts?.stderr.chunks ?? []),
         ].filter((path) => Boolean(path));
     }
-    /** Delete a dropped job's artifact chunks, never one still referenced. */
     removeJobArtifacts(job) {
         const paths = this.artifactPathsOf(job).filter((path) => path.startsWith(`${this.jobsDir}${sep}`));
         if (paths.length === 0)
@@ -431,11 +71,9 @@ export class JobManager {
                 rmSync(path, { force: true });
             }
             catch {
-                // Artifact cleanup is best-effort; a locked file is retried on boot.
             }
         }
     }
-    /** Drop a job row plus its per-job caches and artifacts. */
     forgetJob(id) {
         const job = this.jobs.get(id);
         this.jobs.delete(id);
@@ -451,7 +89,6 @@ export class JobManager {
         forgetProcessIdentity(job.pid);
         this.removeJobArtifacts(job);
     }
-    /** Remove artifact files whose job row no longer exists. */
     sweepOrphanArtifacts() {
         let names;
         try {
@@ -474,7 +111,6 @@ export class JobManager {
                 rmSync(path, { force: true });
             }
             catch {
-                // Ignore unreadable/locked leftovers.
             }
         }
     }
@@ -491,7 +127,7 @@ export class JobManager {
             try {
                 listener(change);
             }
-            catch { /* listeners cannot break job persistence */ }
+            catch { }
         }
     }
     subscribe(listener) {
@@ -550,8 +186,6 @@ export class JobManager {
                 continue;
             }
             this.claimedNotifications.delete(notification.id);
-            // Releasing a runtime lease must not discard an unread durable result;
-            // detach it so the next lease for this session adopts it.
             if (!notification.acknowledgedAt && !notification.archivedAt) {
                 delete notification.responderLeaseId;
                 changed = true;
@@ -604,9 +238,6 @@ export class JobManager {
         const correctsConsumed = Boolean(!existing && consumed && consumed.resultHash !== resultHash);
         if (correctsConsumed)
             this.consumedResponderResults.delete(job.id);
-        // A materially different authoritative result is a new revision: every
-        // delivery/read/analysis marker belonged to the superseded result and must
-        // not suppress review of the corrected one.
         const supersedes = Boolean(existing &&
             completionChanged &&
             (existing.resultHash === undefined || existing.resultHash !== resultHash));
@@ -763,15 +394,12 @@ export class JobManager {
             this.finalizations.delete(job.id);
         }
     }
-    /** Reconcile a restored process that no longer has a ChildProcess close event. */
     refreshJobLiveness(job, options = {}) {
         if (!this.isLive(job) || this.processes.has(job.id)) {
             this.livenessMisses.delete(job.id);
             this.livenessCheckedAt.delete(job.id);
             return;
         }
-        // Subscribers can ask for state many times per frame; one probe per job per
-        // interval is enough because the lost grace window is far longer.
         const checkedAt = this.livenessCheckedAt.get(job.id);
         const probeAt = Date.now();
         if (!options.force &&
@@ -780,11 +408,6 @@ export class JobManager {
             return;
         }
         this.livenessCheckedAt.set(job.id, probeAt);
-        // Primary signal is the pid itself. If the process is alive we keep the job
-        // running and only ever declare "lost" on a PROVEN pid reuse (both the
-        // stored and the current identity are present AND differ). An identity read
-        // that fails or returns nothing is "unknown", never "dead" — treating it as
-        // dead is exactly what flipped live jobs to lost mid-run.
         if (processAlive(job.pid)) {
             const identity = processIdentity(job.pid);
             const provenReuse = Boolean(identity && job.processIdentity && identity !== job.processIdentity);
@@ -796,9 +419,6 @@ export class JobManager {
         else {
             forgetProcessIdentity(job.pid);
         }
-        // The process looks gone (or is a proven pid reuse). Require the miss to
-        // persist across a grace window before finalizing — a single transient
-        // hiccup must not kill a job whose real close event is still in flight.
         const nowMs = Date.now();
         const firstMiss = this.livenessMisses.get(job.id);
         if (firstMiss === undefined) {
@@ -870,11 +490,6 @@ export class JobManager {
             notificationId: notification.id,
         });
     }
-    /**
-     * Retry until the projection lands. The marker is durable, so a crash or a
-     * long-lived plan-write conflict cannot silently strand a green child, and an
-     * unrecoverable case is dead-lettered with a visible reason.
-     */
     retrySettlement(job, resultRevision, reason) {
         const now = new Date().toISOString();
         const previous = this.pendingSettlements.get(job.id);
@@ -899,11 +514,6 @@ export class JobManager {
             return;
         this.scheduleTaskSettlement(job, Math.min(SETTLEMENT_MAX_BACKOFF_MS, 50 * 2 ** Math.min(attempts, 10)));
     }
-    /**
-     * One coalesced, unref'd watcher that reconciles restored live jobs without a
-     * UI read. Without it a headless session can leave a finished responder job
-     * "running" forever, because liveness was only refreshed by list/get calls.
-     */
     scheduleLivenessWatch() {
         if (this.livenessWatchTimer)
             return;
@@ -923,13 +533,11 @@ export class JobManager {
         timer.unref?.();
         this.livenessWatchTimer = timer;
     }
-    /** Ownership guard: a receipt may only be mutated by its owning session. */
     ownsNotification(notification, sessionId) {
         if (!notification)
             return false;
         return sessionId === undefined || notification.ownerSessionId === sessionId;
     }
-    /** Receipt for a launch that was deduplicated by its delegation key. */
     startJobReceipt(job, reason) {
         return {
             ok: true,
@@ -946,14 +554,9 @@ export class JobManager {
             },
         };
     }
-    /** Terminal results whose plan child could not be settled yet. */
     getPendingSettlements() {
         return [...this.pendingSettlements.values()];
     }
-    /**
-     * Register an in-flight tool for stall tracking only.
-     * Never appears in shell.jobs and never touches the durable registry.
-     */
     registerJob(id, job, ac, child) {
         const tracked = { ...job, kind: job.kind ?? "ephemeral" };
         this.jobs.set(id, tracked);
@@ -1001,8 +604,6 @@ export class JobManager {
             }
         }
         if (options?.delegationId) {
-            // A retried tool call must not spawn a second scanner: the delegation key
-            // identifies the work, so the existing job is returned unchanged.
             const existing = [...this.jobs.values()].find((candidate) => candidate.delegationId === options.delegationId &&
                 candidate.ownerSessionId === (options.ownerSessionId ?? "unknown"));
             if (existing)
@@ -1112,9 +713,6 @@ export class JobManager {
             const stderr = new RotatingRedactedWriter(job.artifacts.stderr);
             this.writers.set(id, { stdout, stderr });
             stdout.append(`$ ${job.commandDisplay}\n\n`);
-            // A ChildProcess object is returned before the OS confirms launch. Wait
-            // for `spawn` (or `error`) so shell.start never reports a phantom running
-            // job whose pid is absent and whose eventual status is opaque exit=-2.
             const waitForLaunch = (candidate) => new Promise((resolve) => {
                 const onSpawn = () => {
                     candidate.off("error", onError);
@@ -1133,8 +731,6 @@ export class JobManager {
                 typeof command === "string" &&
                 existsSync(shell) &&
                 existsSync(cwd)) {
-                // Safe: the first child never started, so no command side effects are
-                // duplicated. Own this transient retry in the runtime, not the model.
                 launchRetried = true;
                 await new Promise((resolve) => setTimeout(resolve, 75));
                 child = spawnChild();
@@ -1175,8 +771,6 @@ export class JobManager {
                 };
             }
             launchConfirmed = true;
-            // Sensitive input is never copied into the job record, display, logs, or
-            // artifacts. Write it once only after launch has been confirmed.
             if (typeof command !== "string" && command.stdinText !== undefined) {
                 child.stdin?.end(command.stdinText);
             }
@@ -1192,8 +786,6 @@ export class JobManager {
             let lastDurableFlush = Date.now();
             let progressDirty = false;
             let progressTimer;
-            // UI freshness is cheap; rewriting the whole registry is not. Terminal
-            // transitions always persist authoritatively below.
             const flushProgress = () => {
                 progressDirty = false;
                 lastProgressFlush = Date.now();
@@ -1203,11 +795,6 @@ export class JobManager {
                 }
                 this.emit({ type: "job", jobId: id });
             };
-            // Coalesce high-frequency stdout/stderr chunks: a chatty job (scanner,
-            // dev server) must not force a registry write + UI rerender per data
-            // event. Flush at most every PROGRESS_FLUSH_MS, with a trailing flush so
-            // the last chunk before a quiet gap is never dropped. Terminal
-            // finalize/close always persists authoritatively and clears the timer.
             const scheduleProgressFlush = () => {
                 const elapsed = Date.now() - lastProgressFlush;
                 if (elapsed >= PROGRESS_FLUSH_MS) {
@@ -1263,14 +850,11 @@ export class JobManager {
                 try {
                     stderr.append(`Background process error [${code}]: ${error.message}\n`);
                 }
-                catch { /* finalization already owns the writers */ }
+                catch { }
                 void this.finalizeJob(job, "failed", { exitCode: 127 });
             });
             this.persistSync();
             this.emit({ type: "job", jobId: id });
-            // Best-effort detection for shell-level failures such as command-not-found
-            // immediately after the command shell launches. This bounded window is
-            // not an application readiness guarantee; callers must tail/probe.
             let closedEarly = false;
             await new Promise((resolve) => {
                 if (!this.isLive(job)) {
@@ -1383,10 +967,6 @@ export class JobManager {
             };
         }
     }
-    /**
-     * List durable background jobs for this session only.
-     * Ephemeral tool-stall rows and other sessions' jobs are excluded.
-     */
     listJobs(sessionId) {
         this.pruneTerminalJobs();
         for (const job of this.jobs.values())
@@ -1408,8 +988,6 @@ export class JobManager {
             .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
         const ordered = [...live, ...done];
         const shown = ordered.slice(0, LIST_JOBS_MAX_LINES);
-        // Judge on every job in scope, not just the display window: a normal job
-        // pushed past the window must still keep shell.jobs answerable.
         const pollingPolicy = responderPollingPolicy({
             call: { name: "shell.jobs", args: {} },
             recentJobs: ordered,
@@ -1505,8 +1083,6 @@ export class JobManager {
             return undefined;
         let adopted = false;
         for (const notification of this.notifications.values()) {
-            // Receipts belong to the session, not to a runtime lease: a new lease
-            // adopts everything unread that an earlier lease left behind.
             if (notification.ownerSessionId === sessionId &&
                 !notification.acknowledgedAt &&
                 !notification.archivedAt &&
@@ -1535,10 +1111,6 @@ export class JobManager {
     releaseResponderNotificationClaim(notificationId) {
         this.claimedNotifications.delete(notificationId);
     }
-    /**
-     * Record that a delivery attempt started. This is deliberately weaker than
-     * `markDelivered`: an aborted or failed analysis turn must remain deliverable.
-     */
     markDeliveryStarted(notificationId, sessionId) {
         const notification = this.notifications.get(notificationId);
         if (!this.ownsNotification(notification, sessionId))
@@ -1824,10 +1396,7 @@ export class JobManager {
                 remaining -= localLength;
             }
             let combined = Buffer.concat(parts);
-            // A fixed byte window can land mid-character (e.g. inside the 3-byte
             // "•" redaction marker). Trim any dangling lead byte(s) off the end so
-            // decoding never mangles a character; the trimmed bytes are re-read
-            // (and land on a boundary) on the caller's next offset-based poll.
             const trim = start + combined.length < total ? trailingIncompleteBytes(combined) : 0;
             if (trim > 0)
                 combined = combined.subarray(0, combined.length - trim);
@@ -2101,7 +1670,6 @@ export class JobManager {
             .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
             .slice(0, limit);
     }
-    /** Drop stale terminal durable jobs and all leftover ephemeral rows. */
     pruneTerminalJobs() {
         const now = Date.now();
         const archivedUnsettled = [...this.notifications.values()]
@@ -2137,7 +1705,6 @@ export class JobManager {
         const durableTerminal = [];
         for (const [id, job] of this.jobs) {
             if (!this.isDurable(job)) {
-                // Safety: never keep ephemeral rows that are not live.
                 if (!this.isLive(job))
                     this.forgetJob(id);
                 continue;
@@ -2178,7 +1745,7 @@ export class JobManager {
                     parsed = candidate;
                 }
             }
-            catch { /* a corrupt current registry must not replay stale v1 state */ }
+            catch { }
             if (!parsed)
                 return;
             if (parsed.schemaVersion === 2 && Array.isArray(parsed.settlements)) {
@@ -2207,8 +1774,6 @@ export class JobManager {
                         continue;
                     notifiedJobs.add(notification.jobId);
                     if (!notification.acknowledgedAt && !notification.archivedAt) {
-                        // A durable receipt must survive the restart it exists for. Drop the
-                        // dead runtime lease so the next activated lease can adopt it.
                         delete notification.responderLeaseId;
                     }
                     this.notifications.set(notification.id, notification);
@@ -2221,10 +1786,6 @@ export class JobManager {
                 if (["starting", "running", "stopping"].includes(job.status)) {
                     const alive = processAlive(job.pid);
                     const identity = alive ? processIdentity(job.pid) : undefined;
-                    // Only declare lost when the process is truly gone, or when we can
-                    // PROVE a pid reuse (stored + current identity both known and
-                    // different). An alive pid whose identity is unknown/unreadable is
-                    // kept running — never kill a live process over a failed `ps` read.
                     const provenReuse = Boolean(identity && job.processIdentity && identity !== job.processIdentity);
                     if (!alive || provenReuse) {
                         job.status = "lost";
@@ -2250,9 +1811,8 @@ export class JobManager {
             this.pruneTerminalJobs();
             this.persistSync();
         }
-        catch { /* Corrupt registries are ignored, never trusted as running. */ }
+        catch { }
     }
-    /** Only durable jobs and responder notifications are written to disk. */
     registry() {
         return {
             schemaVersion: 2,