@volter/supercode-terminal 0.2.30

package/substrate/session-lifecycle.js

@@ -0,0 +1,1344 @@
+export { clearRollHeadVerdict, createSessionRollTracker, scanTranscriptHead } from "./session-roll.js";
+// How long a cooperative signal stays trusted before the derivation falls
+// through to the next rung. Generous enough to span the gap between a hook's
+// own turn-start/turn-end pings across one long tool call; short enough that a
+// hook that's been removed (or a session the hook never covered) degrades to
+// the next rung within a couple of observe intervals rather than staying
+// pinned to a one-time snapshot forever.
+export const COOPERATIVE_SIGNAL_TTL_MS = 120_000;
+export function createCooperativeSignalStore() {
+    return new Map();
+}
+// The ONE place a raw hook event name becomes a stored signal — validates it so
+// a malformed/future hook payload can't corrupt the store, and stamps the
+// receipt time itself (the hook never gets to claim its own arrival time,
+// which would let a stale replay masquerade as fresh). A synchronous Map
+// `.set()` is O(1) with zero I/O, so calling this directly from an HTTP
+// handler never touches the event-loop-hot-path doctrine.
+export function recordCooperativeSignal(store, sessionId, event, nowMs) {
+    if (event !== "turn-end" && event !== "turn-start") {
+        throw new Error(`Unrecognized cooperative signal event: ${JSON.stringify(event)}`);
+    }
+    store.set(sessionId, { atMs: nowMs, event });
+}
+export function createAttentionRequestStore() {
+    return new Map();
+}
+export function isAttentionUrgency(value) {
+    return value === "now" || value === "soon" || value === "whenever";
+}
+// The ONE place a raw raise request becomes a stored AttentionRequest —
+// validates urgency/reason and stamps raisedAt itself (nowMs, ISO), mirroring
+// recordCooperativeSignal's "the store never lets the caller claim its own
+// arrival time" doctrine. A synchronous Map .set(), zero I/O.
+export function recordAttentionRequest(store, sessionId, request, nowMs) {
+    if (!request.reason || request.reason.length === 0) {
+        throw new Error("Attention request requires a non-empty reason.");
+    }
+    if (!isAttentionUrgency(request.urgency)) {
+        throw new Error(`Unrecognized attention urgency: ${JSON.stringify(request.urgency)}`);
+    }
+    const stored = {
+        ...(request.detail ? { detail: request.detail } : {}),
+        raisedAt: new Date(nowMs).toISOString(),
+        reason: request.reason,
+        urgency: request.urgency
+    };
+    store.set(sessionId, stored);
+    return stored;
+}
+// Clearing is idempotent (no error clearing an absent/already-cleared
+// session) — both the explicit clear verb and the session-keyed-send
+// auto-clear call this the same way.
+export function clearAttentionRequest(store, sessionId) {
+    store.delete(sessionId);
+}
+const KNOWN_AGENT_IDS = ["claude", "codex", "gemini", "grok", "supercode"];
+const PROCESS_SNAPSHOT_MAX_BUFFER = 16 * 1024 * 1024;
+// Async acquisition shared by tmux and native observers. The legacy sync
+// version remains for WezTerm; ordinary iTerm observations use the async gather.
+export async function snapshotProcessTreeAsync(rootPids, options = {}) {
+    const rows = parseProcessRows(await execFileAsync("ps", ["-axo", "pid=,ppid=,pgid=,stat=,lstart=,ucomm="], { maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER, timeout: 5000 }), true);
+    const relevantProcessIds = collectRelevantProcessIds(rows, [...(rootPids ?? []), ...(options.additionalPids ?? [])]);
+    const wholeHost = rootPids === undefined || (rootPids.length === 0 && options.additionalPids === undefined);
+    const [, listeners] = await Promise.all([
+        enrichProcessArgsAsync(rows, relevantProcessIds),
+        options.includeListeners === false ? new Map() : gatherProcessListeners(relevantProcessIds, wholeHost)
+    ]);
+    applyProcessListeners(rows, listeners);
+    return rows;
+}
+export function snapshotProcessTree(rootPids) {
+    const stdout = execFileSync("ps", ["-axo", "pid=,ppid=,pgid=,stat=,lstart=,ucomm="], { encoding: "utf8", maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER, timeout: 5000 });
+    const rows = parseProcessRows(stdout, true);
+    const relevantProcessIds = collectRelevantProcessIds(rows, rootPids ?? []);
+    enrichProcessArgs(rows, relevantProcessIds);
+    // Legacy synchronous observers have no pre-gathered lease/retained-PID
+    // context. Keep their full inventory until those callers adopt the gather.
+    applyProcessListeners(rows, gatherProcessListenersSync(relevantProcessIds, true));
+    return rows;
+}
+// ONLY the pids of rootPids and everything descended from them — never the whole
+// table. This is the sole safe input to a SIGKILL sweep: snapshotProcessTree
+// returns every process on the machine (the lifecycle observe loop wants that),
+// so SIGKILLing its keys would kill every process the user owns — terminals, the
+// tmux server, this console. A kill must walk DOWN from the pane pids only; the
+// tmux server is a parent, never a descendant, so it is correctly never returned.
+export function snapshotDescendantPids(rootPids) {
+    if (rootPids.length === 0) {
+        return [];
+    }
+    const stdout = execFileSync("ps", ["-axo", "pid=,ppid=,pgid=,stat=,ucomm="], { encoding: "utf8", maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER, timeout: 5000 });
+    return collectRelevantProcessIds(parseProcessRows(stdout), rootPids);
+}
+function parseProcessRows(stdout, includesStartTime = false) {
+    const rows = new Map();
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // `ps -axo` covers EVERY process on the host, including transient/kernel rows
+        // with an empty command. One unexpected row must not abort the whole observe
+        // cycle (that would flap the machine to degraded for an unrelated process) —
+        // skip rows we can't parse rather than throwing.
+        const match = trimmed.match(/^(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s*(.*)$/);
+        if (!match)
+            continue;
+        const [, pidRaw, ppidRaw, pgidRaw, stat, remainder] = match;
+        // lstart is five whitespace-separated fields, followed by the free-form
+        // command. Keep ps's internal spacing: lease files use that exact identity.
+        const started = includesStartTime ? remainder?.match(/^(\S+\s+\S+\s+\d+\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s*(.*)$/) : undefined;
+        if (includesStartTime && !started)
+            continue;
+        const command = includesStartTime ? started?.[2] : remainder;
+        const pid = Number(pidRaw);
+        const ppid = Number(ppidRaw);
+        const pgid = Number(pgidRaw);
+        if (!Number.isInteger(pid) || pid < 1 || !Number.isInteger(ppid) || ppid < 0 || !Number.isInteger(pgid)) {
+            continue;
+        }
+        rows.set(pid, {
+            args: command ?? "",
+            command: command ?? "",
+            pgid,
+            pid,
+            ppid,
+            ...(started?.[1] === undefined ? {} : { processStartTime: started[1] }),
+            stat
+        });
+    }
+    return rows;
+}
+function collectRelevantProcessIds(rows, rootPids) {
+    const relevant = new Set();
+    const childrenByParent = new Map();
+    for (const row of rows.values()) {
+        const children = childrenByParent.get(row.ppid) ?? [];
+        children.push(row);
+        childrenByParent.set(row.ppid, children);
+    }
+    const queue = rootPids.filter((pid) => rows.has(pid));
+    while (queue.length > 0) {
+        const pid = queue.shift();
+        if (pid === undefined || relevant.has(pid))
+            continue;
+        relevant.add(pid);
+        for (const child of childrenByParent.get(pid) ?? []) {
+            queue.push(child.pid);
+        }
+    }
+    return Array.from(relevant).sort((a, b) => a - b);
+}
+function processIdChunks(pids, chunkSize = 64) {
+    const chunks = [];
+    for (let index = 0; index < pids.length; index += chunkSize) {
+        const chunk = pids.slice(index, index + chunkSize);
+        if (chunk.length > 0)
+            chunks.push(chunk);
+    }
+    return chunks;
+}
+function applyEnrichedArgs(rows, stdout) {
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const match = trimmed.match(/^(\d+)\s*(.*)$/);
+        if (!match)
+            continue;
+        const [, pidRaw, argsRaw] = match;
+        const pid = Number(pidRaw);
+        const row = rows.get(pid);
+        if (!row)
+            continue;
+        row.args = argsRaw || row.command;
+    }
+}
+function enrichProcessArgs(rows, pids) {
+    for (const chunk of processIdChunks(pids)) {
+        // `ps -p` exits non-zero when none of the listed pids still exist — a pid can
+        // die in the gap between the snapshot and this enrichment. That is not a
+        // failure of the observe cycle: those rows simply keep their `command`.
+        try {
+            applyEnrichedArgs(rows, execFileSync("ps", ["-p", chunk.join(","), "-o", "pid=,args="], { encoding: "utf8", maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER, timeout: 5000 }));
+        }
+        catch {
+            // Best-effort enrichment; leave these rows with their `command` fallback.
+        }
+    }
+}
+async function enrichProcessArgsAsync(rows, pids) {
+    // Independent chunks run concurrently rather than blocking in sequence. A chunk
+    // whose pids all exited between the snapshot and now makes `ps -p` exit
+    // non-zero; tolerate it per-chunk so one dead pid can't reject the whole pass.
+    const outputs = await Promise.all(processIdChunks(pids).map((chunk) => execFileAsync("ps", ["-p", chunk.join(","), "-o", "pid=,args="], { maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER, timeout: 5000 }).then((stdout) => stdout).catch(() => "")));
+    for (const stdout of outputs)
+        applyEnrichedArgs(rows, stdout);
+}
+function parseListenerAddress(value) {
+    const match = value.match(/^(?:\[([^\]]+)\]|([^:]+)):(\d+)$/u);
+    const address = match?.[1] ?? match?.[2];
+    const port = Number(match?.[3]);
+    if (!address || !Number.isSafeInteger(port) || port < 1 || port > 65_535)
+        return undefined;
+    return { address, port };
+}
+function parseProcessListeners(stdout) {
+    const listeners = new Map();
+    let pid;
+    for (const line of stdout.split("\n")) {
+        const processMatch = line.match(/^p(\d+)$/u);
+        if (processMatch) {
+            pid = Number(processMatch[1]);
+            continue;
+        }
+        if (pid === undefined || !line.startsWith("n"))
+            continue;
+        const listener = parseListenerAddress(line.slice(1));
+        if (listener === undefined)
+            continue;
+        const current = listeners.get(pid) ?? [];
+        if (!current.some((candidate) => candidate.address === listener.address && candidate.port === listener.port))
+            current.push(listener);
+        listeners.set(pid, current);
+    }
+    for (const current of listeners.values())
+        current.sort((a, b) => a.port - b.port || a.address.localeCompare(b.address));
+    return listeners;
+}
+function applyProcessListeners(rows, listeners) {
+    for (const [pid, current] of listeners) {
+        const row = rows.get(pid);
+        if (row !== undefined)
+            row.listeners = current;
+    }
+}
+function parseProcNetListeners(tables) {
+    const listeners = new Map();
+    for (const table of tables) {
+        for (const row of table.split("\n")) {
+            const columns = row.trim().split(/\s+/u);
+            if (columns.length < 10 || columns[3] !== "0A")
+                continue;
+            const [addressHex, portHex] = columns[1]?.split(":") ?? [];
+            if (addressHex === undefined || portHex === undefined)
+                continue;
+            let address;
+            if (addressHex.length === 8) {
+                const value = Number.parseInt(addressHex, 16);
+                const ipv4 = `${value & 0xff}.${(value >>> 8) & 0xff}.${(value >>> 16) & 0xff}.${value >>> 24}`;
+                address = ipv4 === "0.0.0.0" ? "*" : ipv4;
+            }
+            else if (addressHex.length === 32) {
+                if (/^0+$/u.test(addressHex))
+                    address = "*";
+                else if (/^(?:0{24}01000000|0{30}01)$/iu.test(addressHex))
+                    address = "::1";
+            }
+            const port = Number.parseInt(portHex, 16);
+            const inode = columns[9];
+            if (address !== undefined && inode !== undefined && Number.isSafeInteger(port) && port > 0 && port <= 65_535)
+                listeners.set(inode, { address, port });
+        }
+    }
+    return listeners;
+}
+function listenersFromProcLinks(links, listenersByInode) {
+    const listeners = [];
+    for (const link of links) {
+        const inode = /^socket:\[(\d+)\]$/u.exec(link)?.[1];
+        const listener = inode === undefined ? undefined : listenersByInode.get(inode);
+        if (listener !== undefined && !listeners.some((candidate) => candidate.address === listener.address && candidate.port === listener.port))
+            listeners.push(listener);
+    }
+    return listeners.sort((left, right) => left.port - right.port || left.address.localeCompare(right.address));
+}
+async function mergeProcNetListeners(base, processIds) {
+    const tables = await Promise.all(["/proc/net/tcp", "/proc/net/tcp6"].map((path) => readFileAsync(path, "utf8").catch(() => "")));
+    const listenersByInode = parseProcNetListeners(tables);
+    await Promise.all(processIds.filter((pid) => !base.has(pid)).map(async (pid) => {
+        const directory = `/proc/${pid}/fd`;
+        const entries = await readdirAsync(directory).catch(() => []);
+        const links = await Promise.all(entries.map((entry) => readlinkAsync(join(directory, entry)).catch(() => "")));
+        const listeners = listenersFromProcLinks(links, listenersByInode);
+        if (listeners.length > 0)
+            base.set(pid, listeners);
+    }));
+    return base;
+}
+function mergeProcNetListenersSync(base, processIds) {
+    const tables = ["/proc/net/tcp", "/proc/net/tcp6"].map((path) => {
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch {
+            return "";
+        }
+    });
+    const listenersByInode = parseProcNetListeners(tables);
+    for (const pid of processIds) {
+        if (base.has(pid))
+            continue;
+        const directory = `/proc/${pid}/fd`;
+        let entries;
+        try {
+            entries = readdirSync(directory);
+        }
+        catch {
+            continue;
+        }
+        const links = entries.map((entry) => {
+            try {
+                return readlinkSync(join(directory, entry));
+            }
+            catch {
+                return "";
+            }
+        });
+        const listeners = listenersFromProcLinks(links, listenersByInode);
+        if (listeners.length > 0)
+            base.set(pid, listeners);
+    }
+    return base;
+}
+async function gatherProcessListeners(processIds, wholeHost = false) {
+    if (!wholeHost && processIds.length === 0)
+        return new Map();
+    const outputs = [];
+    // Bound argv without launching a concurrent fleet of expensive lsof children.
+    for (const chunk of wholeHost ? [undefined] : processIdChunks(processIds, 256)) {
+        try {
+            outputs.push(await execFileAsync("lsof", listenerArgs(chunk), { maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER, timeout: 5000 }));
+        }
+        catch (error) {
+            outputs.push(normalListenerExitOutput(error));
+        }
+    }
+    const listeners = wholeHost ? parseProcessListeners(outputs.join("\n")) : selectedProcessListeners(outputs.join("\n"), processIds);
+    return mergeProcNetListeners(listeners, processIds);
+}
+function gatherProcessListenersSync(processIds, wholeHost = false) {
+    if (!wholeHost && processIds.length === 0)
+        return new Map();
+    const outputs = (wholeHost ? [undefined] : processIdChunks(processIds, 256)).map((chunk) => {
+        try {
+            return execFileSync("lsof", listenerArgs(chunk), { encoding: "utf8", maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER, timeout: 5000 });
+        }
+        catch (error) {
+            return normalListenerExitOutput(error);
+        }
+    });
+    const listeners = wholeHost ? parseProcessListeners(outputs.join("\n")) : selectedProcessListeners(outputs.join("\n"), processIds);
+    return mergeProcNetListenersSync(listeners, processIds);
+}
+function normalListenerExitOutput(error) {
+    // lsof may exit 1 for a disappeared selected PID while still reporting other
+    // valid listeners. A timeout/signal/maxBuffer failure is not a complete scan.
+    const result = error;
+    return result && (result.code === 1 || result.status === 1) && !result.killed && !result.signal && typeof result.stdout === "string"
+        ? result.stdout
+        : "";
+}
+function listenerArgs(processIds) {
+    // lsof selections are OR-ed unless -a is supplied. Without it, -p still
+    // enumerates every listener on the host, defeating the host boundary.
+    return ["-nP", ...(processIds === undefined ? [] : ["-a", "-p", processIds.join(",")]), "-iTCP", "-sTCP:LISTEN", "-Fpn"];
+}
+function selectedProcessListeners(stdout, processIds) {
+    const selected = new Set(processIds);
+    return new Map([...parseProcessListeners(stdout)].filter(([pid]) => selected.has(pid)));
+}
+export function createLifecycleStore() {
+    return {
+        derivationUnknownCount: 0,
+        observeDurationMs: 0,
+        panes: new Map(),
+        sessions: new Map()
+    };
+}
+// One gather per observation, shared by the native and tmux drivers. Detached
+// work remains in scope even after its pane or original agent has disappeared.
+// No cross-tick cache: PID/start-time identities always come from this scan.
+export async function gatherLifecycleObservation(panes, store, rollTracker) {
+    const sessions = [...store.sessions.values()];
+    const leasesByDir = await gatherBackgroundLeases([
+        ...panes.map((pane) => pane.backgroundLeaseDir),
+        ...sessions.map((session) => session.backgroundLeaseDir)
+    ]);
+    const additionalPids = [
+        ...sessions.flatMap((session) => session.background.map((item) => item.pid)),
+        ...[...leasesByDir.values()].flatMap((leases) => leases.flatMap((lease) => Number.isInteger(lease.pid) && Number(lease.pid) > 0 ? [Number(lease.pid)] : []))
+    ];
+    const rootPids = panes.map((pane) => pane.rootPid);
+    const processRows = rootPids.length === 0 && additionalPids.length === 0
+        ? new Map()
+        : await snapshotProcessTreeAsync(rootPids, { additionalPids });
+    const startTimes = new Map();
+    for (const [pid, row] of processRows) {
+        if (row.processStartTime !== undefined)
+            startTimes.set(pid, row.processStartTime);
+    }
+    const detectedIds = [];
+    const detectedIdsByPane = new Map();
+    if (rollTracker) {
+        // The same pre-gathered IO context as the pure pass: detecting identity must
+        // not fall back to synchronous ps/lease reads before an asynchronous gather.
+        const previousIo = activeIo;
+        activeIo = { leasesByDir, startTimes };
+        try {
+            for (const pane of panes) {
+                const detected = detectCurrentSession(pane, processRows, Date.now());
+                if (detected) {
+                    detectedIds.push(detected.sessionId);
+                    detectedIdsByPane.set(pane.paneId, detected.sessionId);
+                }
+            }
+        }
+        finally {
+            activeIo = previousIo;
+        }
+    }
+    const sessionRolls = rollTracker ? await rollTracker.gather([
+        ...detectedIds,
+        ...panes.flatMap((pane) => {
+            const current = store.panes.get(pane.paneId)?.currentSessionId;
+            return current ? [current] : [];
+        }),
+    ], detectedIdsByPane) : undefined;
+    return { leasesByDir, processRows, startTimes, ...(sessionRolls ? { sessionRolls } : {}) };
+}
+// observeLifecycle runs synchronously start-to-finish (no awaits), so a module
+// scoped context is never interleaved across calls.
+let activeIo;
+export function observeLifecycle(options) {
+    activeIo = options.io;
+    // Store resolution happens ONCE, here — the one named place (no `??`
+    // fallback repeated at the inner pass) — so the wrapper always holds the
+    // same store object it times below, even when a caller (a fresh driver, a
+    // test) supplies none.
+    const store = options.store ?? createLifecycleStore();
+    const startedAt = performance.now();
+    try {
+        return observeLifecycleInner({ ...options, store });
+    }
+    finally {
+        // §I.1: observeDurationMs is a diagnostic for the event-loop-hot-
+        // path doctrine, surfaced at /healthz — measured around the WHOLE pure
+        // pass (this function runs synchronously start-to-finish, no awaits), not
+        // just a sub-step, so a future regression that slows any part of it shows
+        // up here.
+        store.observeDurationMs = performance.now() - startedAt;
+        activeIo = undefined;
+    }
+}
+function observeLifecycleInner(options) {
+    const store = options.store;
+    const observedAt = (options.now ?? new Date()).toISOString();
+    // Resolved once per pass (not re-derived per pane) — the single input the
+    // cooperative rung's freshness check (deriveSessionDerivation) reads.
+    const nowMs = Date.parse(observedAt);
+    const livePaneIds = new Set(options.panes.map((pane) => pane.paneId));
+    // Detect the entire current batch before mutating ownership. A newcomer may
+    // directly own a previously inferred successor; pane iteration order must
+    // never let an old mapping steal it before that new pane enters the store.
+    const detectedByPane = new Map(options.panes.map((pane) => [pane.paneId,
+        preserveSessionIdentityAcrossArgGap(detectCurrentSession(pane, options.processRows, nowMs), store.panes.get(pane.paneId), store),
+    ]));
+    const currentClaims = new Map();
+    for (const pane of options.panes) {
+        const claim = activeIo?.sessionRollClaims?.get(pane.paneId) ?? detectedByPane.get(pane.paneId)?.sessionId;
+        if (claim)
+            currentClaims.set(pane.paneId, claim);
+    }
+    for (const pane of options.panes) {
+        const existingPane = store.panes.get(pane.paneId);
+        const sessionIds = existingPane?.sessionIds ? [...existingPane.sessionIds] : [];
+        const stableDetected = detectedByPane.get(pane.paneId) ?? null;
+        const { rolledFrom, session: currentSession } = resolveSessionRoll(stableDetected, pane.paneId, store, currentClaims);
+        let currentSessionId = existingPane?.currentSessionId ?? null;
+        if (currentSession) {
+            if (currentSessionId && currentSessionId !== currentSession.sessionId) {
+                detachPreviousSession({
+                    backgroundLeaseDir: pane.backgroundLeaseDir,
+                    observedAt,
+                    paneId: pane.paneId,
+                    processRows: options.processRows,
+                    sessionId: currentSessionId,
+                    store
+                });
+            }
+            const previous = store.sessions.get(currentSession.sessionId);
+            recordDerivationDegradation(store, previous, currentSession);
+            currentSessionId = currentSession.sessionId;
+            // A rolled-away launch id stays in the pane's history (before its
+            // successor) — the roll re-attributes the pane, it never erases where the
+            // pane has been.
+            if (rolledFrom && !sessionIds.includes(rolledFrom)) {
+                sessionIds.push(rolledFrom);
+            }
+            if (!sessionIds.includes(currentSession.sessionId)) {
+                sessionIds.push(currentSession.sessionId);
+            }
+            store.sessions.set(currentSession.sessionId, {
+                sessionId: currentSession.sessionId,
+                ...(currentSession.agentSessionId ? { agentSessionId: currentSession.agentSessionId } : {}),
+                ...(currentSession.controlCwd ? { cwd: currentSession.controlCwd } : {}),
+                ...(currentSession.isControl ? { isControl: true } : {}),
+                attachedPaneId: pane.paneId,
+                background: currentSession.background,
+                backgroundLeaseDir: pane.backgroundLeaseDir,
+                derivation: currentSession.derivation,
+                firstSeenAt: previous?.firstSeenAt ?? observedAt,
+                lastPaneId: pane.paneId,
+                lastSeenAt: observedAt,
+                mainPid: currentSession.mainPid,
+                ...(currentSession.mainProcessStartTime ? { mainProcessStartTime: currentSession.mainProcessStartTime } : {}),
+                harness: currentSession.harness,
+                // Carried through from detectCurrentSession alongside `derivation`: both
+                // are populated from the same detection pass, so classifyAttentionSignal's
+                // "asking"/"errored" read reaches the stored session and every consumer
+                // downstream of it.
+                ...(currentSession.signal ? { signal: currentSession.signal } : {}),
+                state: currentSession.state
+            });
+        }
+        else if (currentSessionId) {
+            const session = store.sessions.get(currentSessionId);
+            if (session) {
+                // The bounded process-table read can return without this pane's agent
+                // row under severe host pressure even though kill(0) still proves the
+                // exact process is alive. Preserve the last exact identity for that
+                // degraded tick. When start-time evidence is available it must still
+                // match, preventing a reused PID from inheriting the conversation.
+                if (sameMainProcessAlive(session)) {
+                    store.sessions.set(currentSessionId, {
+                        ...session,
+                        lastSeenAt: observedAt
+                    });
+                }
+                else {
+                    const background = refreshBackground(session.background, options.processRows, pane.backgroundLeaseDir ?? session.backgroundLeaseDir);
+                    const hasBackground = background.length > 0;
+                    if (hasBackground) {
+                        store.sessions.set(currentSessionId, {
+                            ...session,
+                            attachedPaneId: null,
+                            background,
+                            backgroundLeaseDir: pane.backgroundLeaseDir ?? session.backgroundLeaseDir,
+                            derivation: BACKGROUND_DERIVATION,
+                            lastPaneId: pane.paneId,
+                            lastSeenAt: observedAt,
+                            mainPid: undefined,
+                            mainProcessStartTime: undefined,
+                            state: "session_stopped_background_running"
+                        });
+                        currentSessionId = null;
+                    }
+                    else {
+                        store.sessions.delete(currentSessionId);
+                        currentSessionId = null;
+                    }
+                }
+            }
+        }
+        store.panes.set(pane.paneId, {
+            currentSessionId,
+            paneId: pane.paneId,
+            processes: paneProcesses(pane.rootPid, options.processRows),
+            rootPid: pane.rootPid,
+            sessionIds,
+            target: pane.target
+        });
+    }
+    for (const session of store.sessions.values()) {
+        if (session.attachedPaneId && !livePaneIds.has(session.attachedPaneId)) {
+            const background = refreshBackground(session.background, options.processRows, session.backgroundLeaseDir);
+            if (background.length > 0) {
+                store.sessions.set(session.sessionId, {
+                    ...session,
+                    attachedPaneId: null,
+                    background,
+                    derivation: BACKGROUND_DERIVATION,
+                    lastSeenAt: observedAt,
+                    mainPid: undefined,
+                    mainProcessStartTime: undefined,
+                    state: "session_stopped_background_running"
+                });
+            }
+            else {
+                store.sessions.delete(session.sessionId);
+            }
+            const pane = store.panes.get(session.attachedPaneId);
+            if (pane) {
+                store.panes.set(session.attachedPaneId, {
+                    ...pane,
+                    currentSessionId: null
+                });
+            }
+        }
+        else if (!session.attachedPaneId && session.background.length > 0) {
+            const background = refreshBackground(session.background, options.processRows, session.backgroundLeaseDir);
+            const lastPaneIsLive = session.lastPaneId ? livePaneIds.has(session.lastPaneId) : false;
+            if (background.length === 0) {
+                if (lastPaneIsLive) {
+                    if (!session.lastPaneId) {
+                        throw new Error(`Session ${session.sessionId} has live last pane state without a last pane id.`);
+                    }
+                    const pane = store.panes.get(session.lastPaneId);
+                    if (pane) {
+                        store.panes.set(pane.paneId, {
+                            ...pane,
+                            currentSessionId: null
+                        });
+                    }
+                }
+                store.sessions.delete(session.sessionId);
+                continue;
+            }
+            store.sessions.set(session.sessionId, {
+                ...session,
+                attachedPaneId: background.length > 0 ? null : session.lastPaneId,
+                background,
+                // Mirrors the `state` ternary immediately below: background.length is
+                // always > 0 here (the ===0 case already `continue`d above), so this
+                // always resolves to BACKGROUND_DERIVATION in practice — kept as a
+                // ternary anyway so the two never drift if that guard ever changes.
+                derivation: background.length > 0 ? BACKGROUND_DERIVATION : { confidence: "high", source: "screen-heuristic", value: "session_waiting" },
+                lastSeenAt: observedAt,
+                mainPid: undefined,
+                mainProcessStartTime: undefined,
+                state: background.length > 0 ? "session_stopped_background_running" : "session_waiting"
+            });
+        }
+        else if (!session.attachedPaneId && session.background.length === 0) {
+            const lastPaneIsLive = session.lastPaneId ? livePaneIds.has(session.lastPaneId) : false;
+            if (!lastPaneIsLive) {
+                store.sessions.delete(session.sessionId);
+            }
+        }
+    }
+    // Prune dead panes that no surviving session still references. A pane absent
+    // from this observation is kept only while a backgrounded session points at it
+    // (attachedPaneId/lastPaneId) — once that session is pruned the pane entry is
+    // pure leak. Without this, store.panes grows one entry per closed window for the
+    // host's whole lifetime (sessions are pruned; panes were not).
+    const referencedPaneIds = new Set();
+    for (const session of store.sessions.values()) {
+        if (session.attachedPaneId)
+            referencedPaneIds.add(session.attachedPaneId);
+        if (session.lastPaneId)
+            referencedPaneIds.add(session.lastPaneId);
+    }
+    for (const paneId of store.panes.keys()) {
+        if (!livePaneIds.has(paneId) && !referencedPaneIds.has(paneId)) {
+            store.panes.delete(paneId);
+        }
+    }
+    return {
+        observedAt,
+        panes: Array.from(store.panes.values()).sort((a, b) => a.paneId.localeCompare(b.paneId)),
+        sessions: Array.from(store.sessions.values()).sort((a, b) => a.sessionId.localeCompare(b.sessionId))
+    };
+}
+function paneProcesses(rootPid, rows) {
+    const root = rows.get(rootPid);
+    return [
+        ...(root === undefined ? [] : [root]),
+        ...collectDescendants(rootPid, rows).map((node) => node.row)
+    ]
+        .filter((row) => !isInfrastructureProcess(row) && !isDefunctProcess(row))
+        .map((row) => {
+        const processStartTime = currentProcessStartTime(row.pid);
+        return {
+            args: row.args,
+            command: row.command,
+            ...(row.listeners === undefined ? {} : { listeners: row.listeners }),
+            ...(row.pgid === undefined ? {} : { pgid: row.pgid }),
+            pid: row.pid,
+            ppid: row.ppid,
+            ...(processStartTime === undefined ? {} : { processStartTime })
+        };
+    });
+}
+function detectCurrentSession(pane, rows, nowMs) {
+    const root = rows.get(pane.rootPid);
+    const observed = [
+        ...(root ? [{ depth: 0, row: root }] : []),
+        ...collectDescendants(pane.rootPid, rows)
+    ]
+        .filter((node) => !isInfrastructureProcess(node.row) && !isDefunctProcess(node.row));
+    const agent = observed
+        .filter((node) => agentIdForProcess(node.row) !== null)
+        .sort((a, b) => a.depth - b.depth || a.row.pid - b.row.pid)[0];
+    if (!agent)
+        return null;
+    const detected = agentIdForProcess(agent.row);
+    if (!detected)
+        return null;
+    // A harness-served kind (hermes) shows as a `supercode open supercode-live://…` process: the pane is
+    // the runtime's window, and the driver's stamp names the kind the attach serves. The stamp is
+    // that session's identity — the runtime id the engine minted — so the kind and the id are read
+    // from it, never from the attach process.
+    const harness = harnessServedKindForPane(detected, agent.row.args, pane.knownAgentSessionId) ?? detected;
+    // Explicit arg id (claude --session-id) wins; otherwise fall back to the id the
+    // driver stamped on the pane at launch (its prefix must match the detected
+    // harness, so a stale stamp from a different agent is never adopted).
+    const explicitAgentSessionId = explicitSessionIdForProcess(harness, agent.row.args)
+        ?? bareKnownSessionIdForHarness(harness, pane.knownAgentSessionId)
+        ?? undefined;
+    const background = observed
+        .filter((node) => node.depth > 0)
+        .filter((node) => node.row.pid !== agent.row.pid)
+        .filter((node) => agentIdForProcess(node.row) === null)
+        .map((node) => toBackgroundItem(node.row, "descendant"));
+    for (const lease of explicitBackgroundLeases(pane.backgroundLeaseDir, rows)) {
+        background.push(lease);
+    }
+    const sessionId = explicitAgentSessionId ? `${harness}:${explicitAgentSessionId}` : `${harness}:${agent.row.pid}`;
+    const signal = classifyAttentionSignal(pane.contents);
+    const derivation = deriveSessionDerivation(sessionId, classifyForegroundStatus(harness, pane.contents), background, nowMs);
+    const mainProcessStartTime = currentProcessStartTime(agent.row.pid);
+    return {
+        sessionId,
+        ...(explicitAgentSessionId ? { agentSessionId: explicitAgentSessionId } : {}),
+        ...(pane.controlCwd ? { controlCwd: pane.controlCwd } : {}),
+        derivation,
+        ...(pane.isControl ? { isControl: true } : {}),
+        mainPid: agent.row.pid,
+        ...(mainProcessStartTime ? { mainProcessStartTime } : {}),
+        harness,
+        state: derivation.value,
+        ...(signal ? { signal } : {}),
+        background
+    };
+}
+// Argument enrichment is deliberately best-effort: a saturated host can make
+// the bounded `ps ... args=` read time out while the cheap process-tree pass
+// still proves the same agent PID is alive. In that one degraded observation,
+// detectCurrentSession has only a synthetic `harness:<pid>` identity. Do not
+// replace an exact session id we already observed for that SAME harness and
+// PID; doing so makes every session-keyed consumer believe the live executor
+// disappeared. State/attention still come from this tick's fresh evidence —
+// only identity is carried across the temporary argv gap. A different PID is a
+// different process and is never inherited, so a later manually-started agent
+// cannot take over the prior conversation's identity.
+function preserveSessionIdentityAcrossArgGap(detected, existingPane, store) {
+    if (!detected || detected.agentSessionId || !existingPane?.currentSessionId)
+        return detected;
+    const previous = store.sessions.get(existingPane.currentSessionId);
+    if (!previous?.agentSessionId || previous.mainPid !== detected.mainPid || previous.harness !== detected.harness)
+        return detected;
+    return {
+        ...detected,
+        agentSessionId: previous.agentSessionId,
+        sessionId: previous.sessionId
+    };
+}
+function sameMainProcessAlive(session) {
+    if (session.mainPid === undefined || !pidAlive(session.mainPid))
+        return false;
+    if (session.mainProcessStartTime === undefined)
+        return true;
+    const observedStartTime = activeIo
+        ? activeIo.startTimes.get(session.mainPid)
+        : currentProcessStartTime(session.mainPid);
+    return observedStartTime === undefined || observedStartTime === session.mainProcessStartTime;
+}
+// A claude /clear rolls the live process to a NEW session id, but the argv pin
+// (`--session-id`/`--resume`) detectCurrentSession reads never changes — so
+// without correction the pane reports the launch-time id forever while the
+// transcript being written belongs to the successor. Follow the gathered roll
+// chain (io.sessionRolls, evidence built in agent-session-roll) to the session
+// the pane is actually writing. A successor already claimed by another pane is
+// never adopted: a session that is live elsewhere must not be stolen by a
+// mis-attributed roll.
+function resolveSessionRoll(detected, paneId, store, currentClaims) {
+    const rolls = activeIo?.sessionRolls;
+    if (!detected || !rolls || rolls.size === 0)
+        return { rolledFrom: null, session: detected };
+    const seen = new Set([detected.sessionId]);
+    let sessionId = detected.sessionId;
+    for (;;) {
+        const next = rolls.get(sessionId);
+        if (!next || seen.has(next)
+            || [...currentClaims].some(([owner, id]) => owner !== paneId && id === next)
+            || claimedByAnotherPane(next, paneId, store))
+            break;
+        seen.add(next);
+        sessionId = next;
+    }
+    if (sessionId === detected.sessionId)
+        return { rolledFrom: null, session: detected };
+    return {
+        rolledFrom: detected.sessionId,
+        session: {
+            ...detected,
+            agentSessionId: sessionId.slice(sessionId.indexOf(":") + 1),
+            sessionId
+        }
+    };
+}
+function claimedByAnotherPane(sessionId, paneId, store) {
+    for (const pane of store.panes.values()) {
+        if (pane.paneId !== paneId && pane.currentSessionId === sessionId)
+            return true;
+    }
+    const session = store.sessions.get(sessionId);
+    return Boolean(session?.attachedPaneId && session.attachedPaneId !== paneId);
+}
+// Conservative pane read for the finer attention signal. High-precision: a numbered
+// choice/permission selector on screen ⇒ "asking" (blocked on your answer); a strong
+// crash/API-error marker ⇒ "errored". Anything ambiguous returns undefined so it
+// degrades to the running/waiting state — a false positive would misroute attention.
+export function classifyAttentionSignal(contents) {
+    if (!contents)
+        return undefined;
+    const lines = visibleLines(contents.replace(/\u001b\[[0-9?;]*[ -/]*[@-~]/g, "").replace(/\r/g, ""));
+    // errored: only an *agent-level* API error (claude/codex/gemini show "API Error:
+    // NNN" when their own call fails). Deliberately NOT panic:/fatal:/Traceback — those
+    // are tool output (git, a failing test), not the agent crashing; a real agent crash
+    // already drops out of the lifecycle (-> ended).
+    if (lines.some((line) => /\bAPI Error:\s*\d{3}\b/i.test(line))) {
+        return "errored";
+    }
+    // A selector (❯ or ›) on a numbered option is a choice/permission prompt — distinct
+    // from the plain "❯" idle input line (no digit follows).
+    if (lines.some((line) => /^[❯›]\s*\d+[.)]\s/.test(line))) {
+        return "asking";
+    }
+    return undefined;
+}
+// The kinds supercode's harness protocol serves: the pane runs `supercode open supercode-live://…` for
+// them and the driver stamps `<kind>:<runtime id>` on it.
+const HARNESS_SERVED_KINDS = ["hermes"];
+function harnessServedKindForPane(detected, args, knownAgentSessionId) {
+    if (detected !== "supercode" || !/\bopen\s+supercode-live:\/\//.test(args) || !knownAgentSessionId)
+        return null;
+    const kind = HARNESS_SERVED_KINDS.find((candidate) => knownAgentSessionId.startsWith(`${candidate}:`));
+    return kind ?? null;
+}
+function explicitSessionIdForProcess(harness, args) {
+    // claude carries --session-id (create) or --resume (reattach); gemini carries
+    // --session-id only (buildAgentStartupCommand: gemini has no resume-by-uuid, see
+    // agent-launch.ts). codex has no session-id flag on a FRESH launch (it mints its
+    // own id), but a RESUME launch carries the session id as a bare positional after
+    // the `resume` subcommand token (`codex resume <uuid>`, not a flag) — extracted by
+    // codexResumeSessionId below. supercode takes no session-id flag at all (its id is
+    // driver-stamped on the pane instead) and correctly falls through to null here,
+    // recovered by bareKnownSessionIdForHarness or the synthetic pid-keyed id.
+    if (harness === "claude")
+        return valueAfterFlag(args, "--session-id") ?? valueAfterFlag(args, "--resume");
+    if (harness === "gemini")
+        return valueAfterFlag(args, "--session-id");
+    if (harness === "grok")
+        return valueAfterFlag(args, "--session-id") ?? valueAfterFlag(args, "--resume");
+    if (harness === "codex")
+        return codexResumeSessionId(args);
+    return null;
+}
+// codex flags that take a value as the FOLLOWING token (not `--flag=value`) —
+// the tokenizer below must skip both the flag AND its value token so it never
+// mistakes a flag's value for the `resume` subcommand or the id positional.
+// Keep in sync with every flag defaultAgentCommand's codex branch can emit
+// ahead of the subcommand (agent-launch.ts): `-c` (trust-table config) and
+// `--model`. `--dangerously-bypass-approvals-and-sandbox` /
+// `--dangerously-bypass-hook-trust` take no value.
+const CODEX_VALUE_FLAGS = new Set(["-c", "--model"]);
+// Split a shell-ish argv string into tokens, respecting single/double quotes
+// (so a `-c` value containing spaces — shellQuote wraps it in single quotes —
+// stays one token instead of fragmenting). Quote markers are stripped from
+// the returned token.
+function tokenizeArgs(args) {
+    const tokens = [];
+    const pattern = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let match;
+    while ((match = pattern.exec(args)) !== null) {
+        tokens.push(match[1] ?? match[2] ?? match[3] ?? "");
+    }
+    return tokens;
+}
+// The UUID positional codex's `resume` subcommand takes (`codex resume <uuid>`,
+// possibly followed by more flags/prompt) — never a `--flag value` pair, so
+// valueAfterFlag doesn't apply. Anchored to the SUBCOMMAND position (not a bare
+// substring search) so a FRESH launch's prompt can never be mistaken for a
+// resume: prompt text is a trailing positional after the agent binary and its
+// flags, so if it happens to contain the words "resume <uuid>" a naive
+// anywhere-in-argv search would misattribute the pane to that uuid (a hostile
+// or coincidental prompt hijack). Walk tokens past the codex binary, skipping
+// flag tokens and their values; the FIRST remaining token must be exactly
+// `resume`, and the NEXT token must pass the UUID check — anything else
+// (including `resume --last` or `resume <name>`, codex's picker/session-name
+// forms) returns null. If a `-c` value contains spaces, `ps` flattens argv and
+// this tokenizer can false-negative on the value-flag skip (rare, and the
+// codex resume launch stamps the id directly via noteAgentSessionId as a
+// belt-and-suspenders fallback at launch).
+//
+// KNOWN-ACCEPTED RESIDUAL (owner decision, not chased further): a FRESH
+// (non-resume) codex launch whose PROMPT is *itself* exactly `resume <uuid>
+// ...` — i.e. the prompt's first word is literally "resume" immediately
+// followed by a valid uuid, with nothing else between the flags and it — is
+// STILL misread as a genuine `codex resume <uuid>` invocation and adopted as
+// that session. This is irreducible at the `ps -o args` level: `ps` reports
+// only the flattened argv string, with no marker for where codex's own
+// subcommand parsing would have drawn the boundary between "subcommand
+// positional" and "prompt positional" — from this tokenizer's vantage point
+// `codex resume <uuid> and finish the migration` (a genuine resume with a
+// trailing prompt) and `codex <prompt starting with the literal text "resume
+// <uuid> ...">` are the exact same string shape. The non-initial hijack case
+// (prompt text starting with anything OTHER than the bare "resume <uuid>"
+// sequence, e.g. "please resume <uuid> …") IS caught — see the F2 test below —
+// because the first token after the binary+flags fails the `=== "resume"`
+// check. Only the prompt-INITIAL form survives. The managed-launch belt-stamp
+// (noteAgentSessionId) cannot help here either: it is written by the engine
+// only for a launch the engine itself knows is a resume (options.resume ===
+// true), and a fresh launch — by definition — carries no such stamp to fall
+// back on. Fixing this for real needs a non-flattened, argv-boundary-aware
+// read of the process (e.g. /proc/<pid>/cmdline's NUL-separated argv on
+// Linux, or an equivalent native read on macOS) — out of scope here; `ps`
+// gives us none of that. See the "known-accepted residual" test below, which
+// encodes today's actual (adopted) behavior so a future fix flips it
+// deliberately rather than by accident.
+function codexResumeSessionId(args) {
+    const tokens = tokenizeArgs(args);
+    const binaryIndex = tokens.findIndex((token) => /(?:^|\/)codex$/.test(token));
+    if (binaryIndex < 0)
+        return null;
+    let index = binaryIndex + 1;
+    for (let token = tokens[index]; token !== undefined && token.startsWith("-"); token = tokens[index]) {
+        if (CODEX_VALUE_FLAGS.has(token)) {
+            index += 1;
+        }
+        index += 1;
+    }
+    if (tokens[index] !== "resume")
+        return null;
+    const candidate = tokens[index + 1];
+    return candidate && isUuid(candidate) ? candidate : null;
+}
+// The bare id from a driver-stamped pane hint, but only if its prefix matches the
+// harness actually detected on the pane (e.g. "supercode:<uuid>" for a supercode
+// process). Guards against adopting a stale stamp left by a prior, different agent.
+function bareKnownSessionIdForHarness(harness, knownAgentSessionId) {
+    if (!knownAgentSessionId)
+        return null;
+    const prefix = `${harness}:`;
+    return knownAgentSessionId.startsWith(prefix) ? knownAgentSessionId.slice(prefix.length) : null;
+}
+function valueAfterFlag(args, flag) {
+    const pattern = new RegExp(`${escapeRegExp(flag)}(?:=|\\s+)(?:"([^"]+)"|'([^']+)'|(\\S+))`);
+    const match = args.match(pattern);
+    return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function detachPreviousSession(options) {
+    const session = options.store.sessions.get(options.sessionId);
+    if (!session)
+        return;
+    // A current-batch newcomer may already have claimed this session earlier in
+    // the iteration. Detaching our stale inferred identity must not delete it.
+    if (session.attachedPaneId && session.attachedPaneId !== options.paneId)
+        return;
+    const background = refreshBackground(session.background, options.processRows, options.backgroundLeaseDir ?? session.backgroundLeaseDir);
+    if (background.length > 0) {
+        options.store.sessions.set(options.sessionId, {
+            ...session,
+            attachedPaneId: null,
+            background,
+            backgroundLeaseDir: options.backgroundLeaseDir ?? session.backgroundLeaseDir,
+            derivation: BACKGROUND_DERIVATION,
+            lastPaneId: options.paneId,
+            lastSeenAt: options.observedAt,
+            mainPid: undefined,
+            mainProcessStartTime: undefined,
+            state: "session_stopped_background_running"
+        });
+        return;
+    }
+    options.store.sessions.delete(options.sessionId);
+}
+// Background work is process-tree evidence (rung 4, always-available) and
+// outranks a screen-scraping miss (rung 5, least trustworthy): a foreground
+// screen we can't read is still known to be doing something if a leased/
+// descendant process is alive, so background wins over "unrecognized" — but
+// never over an affirmatively-read "running" screen.
+//
+// One function producing BOTH `state` and its provenance together (rather
+// than a sibling function mirroring the same branches) so the two can never
+// drift apart — exactly the "silently resolved by branch order" failure mode
+// §I.1 warns about, just one layer up. Screen-matched states (running,
+// idle-prompt) are "high" confidence — a matched, specific pattern, not a
+// guess; the unmatched fall-through is the one "low"-confidence case (the
+// honest floor); background is process-tree evidence, directly observed via
+// `ps`/leases, so "high".
+//
+// The cooperative rung (A6, §I.1) is checked FIRST, unconditionally: it is the
+// new top of the ladder, so a fresh signal wins even over an affirmatively-
+// read screen or live background work — the hook reports the actual agent
+// process's own turn boundary, which is strictly more direct evidence than
+// anything read or inferred from the outside. A missing or stale (past
+// COOPERATIVE_SIGNAL_TTL_MS) entry is not a distinct case: it simply falls
+// through to the rungs below, unchanged from before this rung existed.
+function deriveSessionDerivation(sessionId, foreground, background, nowMs) {
+    const cooperative = activeIo?.cooperativeSignals?.get(sessionId);
+    if (cooperative && nowMs - cooperative.atMs <= COOPERATIVE_SIGNAL_TTL_MS) {
+        return { confidence: "high", source: "cooperative", value: cooperative.event === "turn-start" ? "session_running" : "session_waiting" };
+    }
+    if (foreground === "running")
+        return { confidence: "high", source: "screen-heuristic", value: "session_running" };
+    if (background.length > 0)
+        return BACKGROUND_DERIVATION;
+    if (foreground === "unrecognized")
+        return { confidence: "low", source: "screen-heuristic", value: "session_unrecognized" };
+    return { confidence: "high", source: "screen-heuristic", value: "session_waiting" };
+}
+// Shared by every "this session's foreground stopped but a background/leased
+// process is still alive" transition below — one named constant instead of
+// repeating the literal at each of those sites.
+const BACKGROUND_DERIVATION = { confidence: "high", source: "process-tree", value: "session_stopped_background_running" };
+// The tag every derivation-degraded transition logs under — one named literal
+// a host can grep verbatim, never re-typed at a second call site.
+export const DERIVATION_DEGRADED_LOG_TAG = "[substrate:lifecycle.derivation-degraded]";
+// Degradation transitions are observable events (§I.1): when a screen
+// pattern that used to match a session stops matching (or any other rung's
+// confidence otherwise drops), fire the tagged log line and bump the store's
+// cumulative counter — ONCE, on the drop edge, never on every tick the session
+// stays degraded. Compared against the session's OWN previously stored
+// derivation (not a side map — the stored session already holds the previous
+// value, so nothing else has to remember it) — a session that recovers to high
+// confidence and
+// later drops again re-fires exactly once for that NEW drop, because the
+// store already holds the fact "the last confidence we saw was high" the
+// moment before this call overwrites it.
+function recordDerivationDegradation(store, previous, current) {
+    if (previous?.derivation.confidence !== "high" || current.derivation.confidence !== "low")
+        return;
+    store.derivationUnknownCount += 1;
+    console.error(`${DERIVATION_DEGRADED_LOG_TAG} ${current.sessionId} derivation confidence dropped from high to low (source=${current.derivation.source}, value=${current.derivation.value})`);
+}
+function classifyForegroundStatus(harness, contents) {
+    if (!contents)
+        return "unrecognized";
+    const normalized = contents
+        .replace(/\u001b\[[0-9?;]*[ -/]*[@-~]/g, "")
+        .replace(/\r/g, "");
+    if (harness === "claude") {
+        if (isClaudeRunning(normalized)) {
+            return "running";
+        }
+        if (isClaudeIdle(normalized)) {
+            return "prompt";
+        }
+    }
+    if (harness === "codex" && isCodexIdle(normalized)) {
+        return "prompt";
+    }
+    if (harness === "gemini") {
+        if (isGeminiRunning(normalized)) {
+            return "running";
+        }
+        if (isGeminiIdle(normalized)) {
+            return "prompt";
+        }
+    }
+    return "unrecognized";
+}
+function isClaudeIdle(contents) {
+    const lines = visibleLines(contents);
+    return lines.some((line) => /^❯(?:\s|$)/.test(line));
+}
+function isClaudeRunning(contents) {
+    const lines = visibleLines(contents);
+    return lines.some((line) => /^●\s+Running\s+\d+\s+shell command/.test(line))
+        || lines.some((line) => /^✻\s+\S+.*\(\d+s\b/.test(line))
+        || lines.some((line) => /^✻\s+(?:Doodling|Thinking|Working|Baking|Cogitating|Herding|Musing|Pondering|Processing|Reading|Searching|Thinking)…/.test(line))
+        || lines.some((line) => /\besc to interrupt\b/i.test(line));
+}
+function isCodexIdle(contents) {
+    const lines = visibleLines(contents);
+    return lines.some((line) => /^›\s*(?:$|\/|\w|\S)/.test(line))
+        || lines.some((line) => /\bgpt-[\w.-]+.*·\s+~\//.test(line))
+        || lines.some((line) => /\bOpenAI Codex\b/.test(line) && !lines.some((candidate) => /\bRunning\b|\bThinking\b/i.test(candidate)));
+}
+// Derived from real `gemini` v0.49.0 captures (test/fixtures/gemini-screens/,
+// tmux `capture-pane -e` — the same preserveEscapes:true path the real driver
+// uses), never invented from memory (§I.1's whole point: a plausible-but-wrong
+// pattern is worse than no pattern). Gemini's idle input caret is a bare ASCII
+// `>` — distinct from claude's `❯` and codex's `›`, so there is no cross-harness
+// collision.
+function isGeminiIdle(contents) {
+    const lines = visibleLines(contents);
+    return lines.some((line) => /^>(?:\s|$)/.test(line));
+}
+// Gemini's busy indicator is a braille spinner glyph (observed frames ⠦ ⠧ ⠏ ⠙ ⠴
+// ⠼, all in the Braille Patterns block U+2800-U+28FF) followed by
+// "Thinking... (esc to cancel, Ns)". Checked BEFORE isGeminiIdle in
+// classifyForegroundStatus: a running screen still shows the just-submitted
+// message on an idle-shaped `>` line above the spinner AND a fresh empty `>`
+// input box below it, so idle-pattern lines coexist with the running one on a
+// real busy screen (both real-capture fixtures prove this) — running must win.
+function isGeminiRunning(contents) {
+    const lines = visibleLines(contents);
+    return lines.some((line) => /^[⠀-⣿]\s+Thinking\.\.\.\s*\(esc to cancel/.test(line));
+}
+function visibleLines(contents) {
+    return contents
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+function refreshBackground(previous, rows, backgroundLeaseDir) {
+    const active = new Map();
+    for (const item of previous) {
+        const row = rows.get(item.pid);
+        if (row) {
+            if (isDefunctProcess(row) || isInfrastructureProcess(row) || !processStartMatches(item.pid, item.processStartTime))
+                continue;
+            active.set(item.pid, {
+                ...toBackgroundItem(row, "leased-descendant"),
+                processStartTime: item.processStartTime ?? currentProcessStartTime(item.pid)
+            });
+        }
+        else if (pidAlive(item.pid) && processStartMatches(item.pid, item.processStartTime)) {
+            const { listeners: _listeners, ...withoutStaleListeners } = item;
+            active.set(item.pid, {
+                ...withoutStaleListeners,
+                source: "leased-descendant"
+            });
+        }
+    }
+    for (const item of explicitBackgroundLeases(backgroundLeaseDir, rows)) {
+        active.set(item.pid, item);
+    }
+    return Array.from(active.values()).sort((a, b) => a.pid - b.pid);
+}
+function explicitBackgroundLeases(backgroundLeaseDir, rows) {
+    if (!backgroundLeaseDir)
+        return [];
+    if (activeIo) {
+        return leaseItemsFromRaw(activeIo.leasesByDir.get(backgroundLeaseDir) ?? [], rows);
+    }
+    if (!existsSync(backgroundLeaseDir)) {
+        throw new Error(`Background lease directory does not exist: ${backgroundLeaseDir}`);
+    }
+    const leases = [];
+    for (const entry of readdirSync(backgroundLeaseDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        leases.push(JSON.parse(readFileSync(join(backgroundLeaseDir, entry.name), "utf8")));
+    }
+    return leaseItemsFromRaw(leases, rows);
+}
+function leaseItemsFromRaw(leases, rows) {
+    const items = [];
+    for (const lease of leases) {
+        if (!Number.isInteger(lease.pid) || Number(lease.pid) < 1) {
+            throw new Error(`Invalid background lease pid: ${JSON.stringify(lease.pid)}`);
+        }
+        if (typeof lease.processStartTime !== "string" || lease.processStartTime.length === 0) {
+            throw new Error(`Invalid background lease processStartTime: ${JSON.stringify(lease.processStartTime)}`);
+        }
+        const pid = Number(lease.pid);
+        if (!pidAlive(pid) || !processStartMatches(pid, lease.processStartTime))
+            continue;
+        const row = rows.get(pid);
+        if (row && (isDefunctProcess(row) || isInfrastructureProcess(row)))
+            continue;
+        const base = row ? toBackgroundItem(row, "explicit-lease") : {
+            pid,
+            source: "explicit-lease"
+        };
+        items.push({
+            ...base,
+            ...(typeof lease.args === "string" ? { args: lease.args } : {}),
+            ...(typeof lease.command === "string" ? { command: lease.command } : {}),
+            ...(typeof lease.description === "string" ? { description: lease.description } : {}),
+            processStartTime: lease.processStartTime
+        });
+    }
+    return items;
+}
+function collectDescendants(rootPid, rows) {
+    if (!rows.has(rootPid))
+        return [];
+    const childrenByParent = new Map();
+    for (const row of rows.values()) {
+        const children = childrenByParent.get(row.ppid);
+        if (children)
+            children.push(row);
+        else
+            childrenByParent.set(row.ppid, [row]);
+    }
+    const out = [];
+    const queue = [{ depth: 0, pid: rootPid }];
+    const seen = new Set();
+    while (queue.length > 0) {
+        const { depth, pid } = queue.shift();
+        if (seen.has(pid))
+            continue;
+        seen.add(pid);
+        const children = childrenByParent.get(pid) ?? [];
+        for (const child of children) {
+            out.push({ depth: depth + 1, row: child });
+            queue.push({ depth: depth + 1, pid: child.pid });
+        }
+    }
+    return out;
+}
+function toBackgroundItem(row, source) {
+    return {
+        ...(row.listeners !== undefined ? { listeners: row.listeners } : {}),
+        pid: row.pid,
+        ppid: row.ppid,
+        ...(row.pgid !== undefined ? { pgid: row.pgid } : {}),
+        args: row.args,
+        command: row.command,
+        processStartTime: currentProcessStartTime(row.pid),
+        source
+    };
+}
+function isInfrastructureProcess(row) {
+    const command = basename(row.command);
+    const args = row.args.trim();
+    return command === "tmux"
+        || command === "reattach-to-user-namespace"
+        // Claude Code spawns `caffeinate -i -t 300` as a keep-awake helper and re-spawns
+        // it on activity — it is never agent work. Counted as background, it pins a
+        // finished/idle session to session_stopped_background_running (→ attention
+        // "working") for up to its 300s lifetime, and indefinitely if anything pokes the
+        // session before then, so the parked prompt never surfaces as awaiting_me.
+        || command === "caffeinate"
+        || (command === "sleep" && /^sleep\s+3600(?:\s|$)/.test(args))
+        || args.includes("@playwright/mcp")
+        || command === "playwright-mcp"
+        || /(?:^|[/\s])playwright-mcp(?:\s|$)/.test(args);
+}
+function basename(command) {
+    return command.split("/").at(-1) ?? command;
+}
+function isDefunctProcess(row) {
+    return row.stat?.includes("Z") || row.command.startsWith("(") || row.args.startsWith("(");
+}
+function agentIdForProcess(row) {
+    for (const agentId of KNOWN_AGENT_IDS) {
+        const escaped = agentId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const re = new RegExp(`(?:^|[\\s/])${escaped}(?:\\.exe)?(?:\\s|$)`);
+        if (re.test(row.command) || re.test(row.args)) {
+            return agentId;
+        }
+    }
+    return null;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function processStartMatches(pid, expected) {
+    if (!expected)
+        return true;
+    return currentProcessStartTime(pid) === expected;
+}
+function currentProcessStartTime(pid) {
+    // Pre-gathered (async) start-times when running the pure observe path.
+    if (activeIo)
+        return activeIo.startTimes.get(pid);
+    try {
+        const stdout = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
+            encoding: "utf8",
+            maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER,
+            timeout: 1000
+        }).trim();
+        return stdout || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Batched async twin of currentProcessStartTime: one ps call yields start-times
+// for every live pid, gathered off the event loop and fed in via ObserveIo.
+export async function gatherProcessStartTimes() {
+    const startTimes = new Map();
+    let stdout;
+    try {
+        stdout = await execFileAsync("ps", ["-axo", "pid=,lstart="], { maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER, timeout: 5000 });
+    }
+    catch {
+        return startTimes;
+    }
+    for (const line of stdout.split("\n")) {
+        const match = line.trim().match(/^(\d+)\s+(.+)$/);
+        if (!match?.[2])
+            continue;
+        startTimes.set(Number(match[1]), match[2].trim());
+    }
+    return startTimes;
+}
+// Async twin of the lease file reads, gathered off the event loop. Returns the
+// parsed lease files per directory; observeLifecycle applies the same liveness
+// rules over them as the sync path.
+export async function gatherBackgroundLeases(dirs) {
+    const byDir = new Map();
+    const unique = [...new Set(dirs.filter((dir) => Boolean(dir)))];
+    await Promise.all(unique.map(async (dir) => {
+        const leases = [];
+        let entries;
+        try {
+            entries = await readdirAsync(dir, { withFileTypes: true });
+        }
+        catch {
+            byDir.set(dir, leases);
+            return;
+        }
+        await Promise.all(entries.map(async (entry) => {
+            if (!entry.isFile() || !entry.name.endsWith(".json"))
+                return;
+            try {
+                leases.push(JSON.parse(await readFileAsync(join(dir, entry.name), "utf8")));
+            }
+            catch {
+                // Skip unreadable/!corrupt lease files.
+            }
+        }));
+        byDir.set(dir, leases);
+    }));
+    return byDir;
+}
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, readlinkSync } from "node:fs";
+import { readdir as readdirAsync, readFile as readFileAsync, readlink as readlinkAsync } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+function isUuid(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(value);
+}
+const execFileRaw = promisify(execFile);
+async function execFileAsync(command, args, options) {
+    const { stdout } = await execFileRaw(command, args, { encoding: "utf8", ...options });
+    return stdout;
+}