@termfleet/core 0.1.0

package/dist/session-lifecycle.js

@@ -0,0 +1,658 @@
+const KNOWN_AGENT_IDS = ["claude", "codex"];
+const PROCESS_SNAPSHOT_MAX_BUFFER = 16 * 1024 * 1024;
+// Async twin of snapshotProcessTree used by the busy virtual-tmux observe loop
+// so the ps calls never block the event loop. The sync version stays for the
+// low-window iTerm/WezTerm drivers, which are not loop-saturating.
+export async function snapshotProcessTreeAsync(rootPids = []) {
+    const rows = parseProcessRows(await execFileAsync("ps", ["-axo", "pid=,ppid=,pgid=,stat=,ucomm="], { maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER, timeout: 5000 }));
+    await enrichProcessArgsAsync(rows, collectRelevantProcessIds(rows, rootPids));
+    return rows;
+}
+export function snapshotProcessTree(rootPids = []) {
+    const stdout = execFileSync("ps", ["-axo", "pid=,ppid=,pgid=,stat=,ucomm="], { encoding: "utf8", maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER, timeout: 5000 });
+    const rows = parseProcessRows(stdout);
+    enrichProcessArgs(rows, collectRelevantProcessIds(rows, rootPids));
+    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) {
+    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, command] = match;
+        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,
+            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) {
+    const 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);
+}
+export function createLifecycleStore() {
+    return {
+        panes: new Map(),
+        sessions: new Map()
+    };
+}
+// 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;
+    try {
+        return observeLifecycleInner(options);
+    }
+    finally {
+        activeIo = undefined;
+    }
+}
+function observeLifecycleInner(options) {
+    const store = options.store ?? createLifecycleStore();
+    const observedAt = (options.now ?? new Date()).toISOString();
+    const livePaneIds = new Set(options.panes.map((pane) => pane.paneId));
+    for (const pane of options.panes) {
+        const existingPane = store.panes.get(pane.paneId);
+        const sessionIds = existingPane?.sessionIds ? [...existingPane.sessionIds] : [];
+        const currentSession = detectCurrentSession(pane, options.processRows);
+        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);
+            currentSessionId = currentSession.sessionId;
+            if (!sessionIds.includes(currentSession.sessionId)) {
+                sessionIds.push(currentSession.sessionId);
+            }
+            store.sessions.set(currentSession.sessionId, {
+                sessionId: currentSession.sessionId,
+                ...(currentSession.agentSessionId ? { agentSessionId: currentSession.agentSessionId } : {}),
+                attachedPaneId: pane.paneId,
+                background: currentSession.background,
+                backgroundLeaseDir: pane.backgroundLeaseDir,
+                firstSeenAt: previous?.firstSeenAt ?? observedAt,
+                lastPaneId: pane.paneId,
+                lastSeenAt: observedAt,
+                mainPid: currentSession.mainPid,
+                provider: currentSession.provider,
+                state: currentSession.state
+            });
+        }
+        else if (currentSessionId) {
+            const session = store.sessions.get(currentSessionId);
+            if (session) {
+                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,
+                        lastPaneId: pane.paneId,
+                        lastSeenAt: observedAt,
+                        mainPid: undefined,
+                        state: "session_stopped_background_running"
+                    });
+                    currentSessionId = null;
+                }
+                else {
+                    store.sessions.delete(currentSessionId);
+                    currentSessionId = null;
+                }
+            }
+        }
+        store.panes.set(pane.paneId, {
+            currentSessionId,
+            paneId: pane.paneId,
+            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,
+                    lastSeenAt: observedAt,
+                    mainPid: 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,
+                lastSeenAt: observedAt,
+                mainPid: 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
+    // provider'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 detectCurrentSession(pane, rows) {
+    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 provider = agentIdForProcess(agent.row);
+    if (!provider)
+        return null;
+    const explicitAgentSessionId = explicitSessionIdForProcess(provider, agent.row.args) ?? 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 signal = classifyAttentionSignal(pane.contents);
+    return {
+        sessionId: explicitAgentSessionId ? `${provider}:${explicitAgentSessionId}` : `${provider}:${agent.row.pid}`,
+        ...(explicitAgentSessionId ? { agentSessionId: explicitAgentSessionId } : {}),
+        mainPid: agent.row.pid,
+        provider,
+        state: deriveSessionState(classifyForegroundStatus(provider, pane.contents), background),
+        ...(signal ? { signal } : {}),
+        background
+    };
+}
+// 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;
+}
+function explicitSessionIdForProcess(provider, args) {
+    if (provider !== "claude")
+        return null;
+    return valueAfterFlag(args, "--session-id") ?? valueAfterFlag(args, "--resume");
+}
+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;
+    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,
+            lastPaneId: options.paneId,
+            lastSeenAt: options.observedAt,
+            mainPid: undefined,
+            state: "session_stopped_background_running"
+        });
+        return;
+    }
+    options.store.sessions.delete(options.sessionId);
+}
+function deriveSessionState(foreground, background) {
+    if (foreground === "running")
+        return "session_running";
+    return background.length > 0 ? "session_stopped_background_running" : "session_waiting";
+}
+function classifyForegroundStatus(provider, contents) {
+    if (!contents)
+        return "running";
+    const normalized = contents
+        .replace(/\u001b\[[0-9?;]*[ -/]*[@-~]/g, "")
+        .replace(/\r/g, "");
+    if (provider === "claude") {
+        if (isClaudeRunning(normalized)) {
+            return "running";
+        }
+        if (isClaudeIdle(normalized)) {
+            return "prompt";
+        }
+    }
+    if (provider === "codex" && isCodexIdle(normalized)) {
+        return "prompt";
+    }
+    return "running";
+}
+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)));
+}
+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)) {
+            active.set(item.pid, {
+                ...item,
+                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 {
+        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"
+        || (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 } from "node:fs";
+import { readdir as readdirAsync, readFile as readFileAsync } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const execFileRaw = promisify(execFile);
+async function execFileAsync(command, args, options) {
+    const { stdout } = await execFileRaw(command, args, { encoding: "utf8", ...options });
+    return stdout;
+}

package/dist/session-window.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderWindow } from "./types.js";
+export declare function windowHostsSession(currentSessionId: string | null | undefined, agentSessionId: string): boolean;
+export declare function findSessionWindow(windows: ProviderWindow[], agentSessionId: string): ProviderWindow | undefined;

package/dist/session-window.js

@@ -0,0 +1,20 @@
+import { agentProviders, formatAgentSessionId } from "./agent-session-id.js";
+// The session→window→terminal descent, in ONE place. Acting on a session is
+// keyed by agentSessionId; this resolves the live window/terminal hosting it so
+// no caller (CLI, SDK, frontend, provider socket) has to descend the tiers by
+// hand. See the session-first principle in CLAUDE.md.
+// A window hosts `agentSessionId` when its live currentSessionId matches. Accept
+// the prefixed form (claude:uuid / codex:uuid / gemini:uuid) the index and
+// triage views emit, or a bare uuid (match any agent prefix).
+export function windowHostsSession(currentSessionId, agentSessionId) {
+    if (!currentSessionId)
+        return false;
+    if (currentSessionId === agentSessionId)
+        return true;
+    if (agentSessionId.includes(":"))
+        return false;
+    return agentProviders.some((agent) => currentSessionId === formatAgentSessionId(agent, agentSessionId));
+}
+export function findSessionWindow(windows, agentSessionId) {
+    return windows.find((windowInfo) => windowHostsSession(windowInfo.lifecycle?.currentSessionId, agentSessionId));
+}