@volter/supercode-terminal 0.2.30

package/substrate/native-host.js

@@ -0,0 +1,529 @@
+import { readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runAsync } from "./internal/exec.js";
+import { openLocalTerminal, terminalShellCommand } from "./local-terminal.js";
+import { createSessionRollTracker } from "./session-roll.js";
+import { createLifecycleStore, gatherLifecycleObservation, observeLifecycle, } from "./session-lifecycle.js";
+const CODEX_ROLLOUT_ID = /\/rollout-[^/]*-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/iu;
+const CODEX_SESSION_ID = /\bSession:\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/giu;
+const APPLE_FIELD_SEPARATOR = String.fromCharCode(31);
+/**
+ * Host-only local terminal capability for embedders.
+ *
+ * The public surface contains durable agent session ids and semantic state only.
+ * Native window ids, tty paths, process ids, AppleScript references, and tmux
+ * handles remain private to this process.
+ */
+export class NativeTerminalSessionHost {
+    lifecycleStore = createLifecycleStore();
+    rollTracker;
+    observationPending = Promise.resolve();
+    claudeConfigDir;
+    resolvedSessionIds = new Map();
+    sessions = new Map();
+    constructor(options = {}) {
+        this.claudeConfigDir = options.claudeConfigDir
+            ?? (options.home === undefined ? process.env.CLAUDE_CONFIG_DIR : undefined)
+            ?? join(options.home ?? homedir(), ".claude");
+        this.rollTracker = createSessionRollTracker({ claudeConfigDir: this.claudeConfigDir });
+    }
+    async listSessions() {
+        const result = this.observationPending.then(() => this.observeSessions());
+        this.observationPending = result.catch(() => undefined);
+        return result;
+    }
+    async observeSessions() {
+        assertSupportedPlatform();
+        const [itermRunning, terminalRunning] = await Promise.all([
+            applicationRunning("iTerm2"),
+            applicationRunning("Terminal"),
+        ]);
+        const surfaces = (await Promise.all([
+            ...(itermRunning ? [listItermSurfaces()] : []),
+            ...(terminalRunning ? [listTerminalSurfaces()] : []),
+        ])).flat();
+        // Both applications share one ownership/evidence batch. A successor live
+        // in the other application is not available for adoption.
+        const observations = [await this.observeSurfaces(surfaces)];
+        const next = new Map();
+        const activeIdentityKeys = new Set();
+        for (const entries of observations) {
+            for (const entry of entries) {
+                activeIdentityKeys.add(entry.identityKey);
+                next.set(entry.session.agentSessionId, entry);
+            }
+        }
+        for (const key of this.resolvedSessionIds.keys()) {
+            if (!activeIdentityKeys.has(key))
+                this.resolvedSessionIds.delete(key);
+        }
+        this.sessions = next;
+        return [...next.values()].flatMap((entry) => /^(?:claude|codex):\d+$/u.test(entry.session.agentSessionId) ? [] : [entry.session]);
+    }
+    async captureSession(agentSessionId, options = {}) {
+        const entry = await this.requireSession(agentSessionId);
+        const content = await captureSurface(entry.address);
+        return options.lines === undefined ? content : content.split("\n").slice(-options.lines).join("\n");
+    }
+    async openSession(command, options) {
+        assertSupportedPlatform();
+        if (options.application === "terminal") {
+            await openLocalTerminal(command);
+            return;
+        }
+        await runAsync("osascript", ["-e", `
+tell application "iTerm"
+  activate
+  create window with default profile
+  tell current session of current window
+    write text ${appleString(terminalShellCommand(command))}
+  end tell
+end tell
+`], { timeoutMs: 5_000 });
+    }
+    hasSessionCandidate(agentSessionId, options) {
+        if (this.sessions.has(agentSessionId))
+            return true;
+        if (!/^codex:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(agentSessionId)) {
+            return false;
+        }
+        return [...this.sessions.values()].some((entry) => /^codex:\d+$/u.test(entry.observedSessionId) && entry.cwd === options.cwd);
+    }
+    async resolveSession(agentSessionId, options) {
+        if (!/^codex:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(agentSessionId)) {
+            return null;
+        }
+        await this.listSessions();
+        const candidates = [...this.sessions.values()].filter((entry) => {
+            if (entry.session.agentSessionId === agentSessionId)
+                return true;
+            return /^codex:\d+$/u.test(entry.session.agentSessionId);
+        });
+        for (const entry of candidates) {
+            const pid = pidKeyedAgentPid(entry.observedSessionId, "codex");
+            if (pid !== undefined && entry.cwd !== options.cwd)
+                continue;
+            const resolved = await probeCodexSessionId(entry.address);
+            if (`codex:${resolved}` !== agentSessionId)
+                continue;
+            this.resolvedSessionIds.set(entry.identityKey, agentSessionId);
+            const session = Object.freeze({ ...entry.session, agentSessionId });
+            this.sessions.delete(entry.session.agentSessionId);
+            this.sessions.set(agentSessionId, { ...entry, session });
+            return {
+                proof: { observedAtMs: Date.now(), source: "native_terminal_status", turn: "idle" },
+                session,
+            };
+        }
+        return null;
+    }
+    async relinquishSession(agentSessionId, proof) {
+        if (proof.turn !== "idle" ||
+            !proof.source ||
+            !Number.isFinite(proof.observedAtMs) ||
+            Date.now() - proof.observedAtMs > 3_000) {
+            throw new Error("Native session handoff requires a fresh external idle proof.");
+        }
+        const entry = await this.requireSession(agentSessionId);
+        if (entry.session.state === "session_running" || entry.session.state === "session_unrecognized") {
+            throw new Error(`Native terminal state for ${agentSessionId} is not quiescent; its writer was left untouched.`);
+        }
+        if (agentSessionId.startsWith("codex:")) {
+            const before = await captureSurface(entry.address);
+            if (/(?:^|\n)› \/exit[ \t]*(?:\n|$)/u.test(before)) {
+                await submitSurfaceLine(entry.address, "");
+            }
+            else {
+                await submitSurfaceLine(entry.address, "/exit");
+                await new Promise((resolve) => setTimeout(resolve, 100));
+                const content = await captureSurface(entry.address);
+                if (/(?:^|\n)› \/exit[ \t]*(?:\n|$)/u.test(content))
+                    await submitSurfaceLine(entry.address, "");
+            }
+        }
+        else {
+            await submitSurfaceLine(entry.address, "/exit");
+        }
+        const deadline = Date.now() + 5_000;
+        while (Date.now() < deadline) {
+            if (!(await this.listSessions()).some((session) => session.agentSessionId === agentSessionId)) {
+                return { agentSessionId, released: true };
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        throw new Error(`Native writer ${agentSessionId} did not exit; do not resume it elsewhere yet.`);
+    }
+    async requireSession(agentSessionId) {
+        await this.listSessions();
+        const entry = this.sessions.get(agentSessionId);
+        if (!entry)
+            throw new Error(`No user-owned native terminal currently owns ${agentSessionId}.`);
+        return entry;
+    }
+    async observeSurfaces(surfaces) {
+        const rootPidByTty = new Map();
+        for (const entry of await resolveTtyRootPids(surfaces.map((surface) => surface.tty))) {
+            rootPidByTty.set(entry.tty, entry.rootPid);
+        }
+        const panes = await Promise.all(surfaces.flatMap((surface) => {
+            const tty = normalizeTty(surface.tty);
+            const rootPid = rootPidByTty.get(tty);
+            if (!tty || rootPid === undefined)
+                return [];
+            return [(async () => ({
+                    contents: await captureSurface(surface),
+                    paneId: tty,
+                    rootPid,
+                    target: tty,
+                }))()];
+        }));
+        const store = this.lifecycleStore;
+        const claudeByPid = new Map();
+        const claudeCwdByPid = new Map();
+        const sessionRollClaims = new Map();
+        const { leasesByDir, processRows, startTimes, sessionRolls } = await gatherLifecycleObservation(panes, store, {
+            gather: async (ids, detectedIdsByPane) => {
+                // Reserve the existing bare-Claude heuristic's candidates before any
+                // rollover adoption, including on the first observation. Resolve each
+                // PID once and reuse the result below; no second cwd/project scan.
+                for (const id of ids) {
+                    const pid = pidKeyedAgentPid(id, "claude");
+                    if (pid === undefined || claudeByPid.has(pid))
+                        continue;
+                    const cwd = await resolveProcessCwd(pid);
+                    claudeCwdByPid.set(pid, cwd);
+                    claudeByPid.set(pid, cwd ? latestClaudeSessionIdForCwd(cwd, this.claudeConfigDir) : undefined);
+                }
+                for (const [paneId, id] of detectedIdsByPane ?? []) {
+                    const pid = pidKeyedAgentPid(id, "claude");
+                    const alias = pid === undefined ? undefined : claudeByPid.get(pid);
+                    if (alias)
+                        sessionRollClaims.set(paneId, `claude:${alias}`);
+                }
+                return this.rollTracker.gather([
+                    ...ids,
+                    ...[...claudeByPid.values()].flatMap((id) => id ? [`claude:${id}`] : []),
+                ]);
+            },
+        });
+        const lifecycle = observeLifecycle({ io: { leasesByDir, startTimes, sessionRolls, sessionRollClaims }, panes, processRows, store });
+        const overrideByTty = await resolvePidKeyedSessionIds(lifecycle.panes, surfaces, claudeByPid);
+        const cwdByObservedSession = new Map(await Promise.all(lifecycle.panes.flatMap((pane) => {
+            const pid = pidKeyedAgentPid(pane.currentSessionId, "codex")
+                ?? pidKeyedAgentPid(pane.currentSessionId, "claude");
+            return pane.currentSessionId && pid !== undefined
+                ? [(claudeCwdByPid.has(pid) ? Promise.resolve(claudeCwdByPid.get(pid)) : resolveProcessCwd(pid))
+                        .then((cwd) => [pane.currentSessionId, cwd])]
+                : [];
+        })));
+        const stateById = new Map(lifecycle.sessions.map((session) => [session.sessionId, session.state]));
+        const surfaceByTty = new Map(surfaces.map((surface) => [normalizeTty(surface.tty), surface]));
+        return lifecycle.panes.flatMap((pane) => {
+            if (!pane.currentSessionId)
+                return [];
+            const address = surfaceByTty.get(normalizeTty(pane.paneId));
+            if (!address)
+                return [];
+            const backend = address.backend;
+            const identityKey = `${backend}\0${normalizeTty(pane.paneId)}\0${pane.currentSessionId}`;
+            const agentSessionId = this.resolvedSessionIds.get(identityKey)
+                ?? overrideByTty.get(normalizeTty(pane.paneId))
+                ?? pane.currentSessionId;
+            const state = stateById.get(pane.currentSessionId);
+            if (!state)
+                return [];
+            return [{
+                    address,
+                    cwd: cwdByObservedSession.get(pane.currentSessionId),
+                    identityKey,
+                    observedSessionId: pane.currentSessionId,
+                    session: Object.freeze({ agentSessionId, backend, state }),
+                }];
+        });
+    }
+}
+async function probeCodexSessionId(surface) {
+    const before = await captureSurface(surface);
+    const visibleSessionId = [...before.matchAll(CODEX_SESSION_ID)].at(-1)?.[1];
+    if (visibleSessionId)
+        return visibleSessionId;
+    if (!before.includes("› Ask Codex to do anything"))
+        return null;
+    await submitSurfaceLine(surface, "/status");
+    const deadline = Date.now() + 3_000;
+    let submittedAutocomplete = false;
+    while (Date.now() < deadline) {
+        const content = await captureSurface(surface);
+        const matches = [...content.matchAll(CODEX_SESSION_ID)];
+        const sessionId = matches.at(-1)?.[1];
+        if (sessionId)
+            return sessionId;
+        if (!submittedAutocomplete && (content.includes("/status      show current session configuration") ||
+            /(?:^|\n)› \/status[ \t]*(?:\n|$)/u.test(content))) {
+            submittedAutocomplete = true;
+            await submitSurfaceLine(surface, "");
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return null;
+}
+async function resolvePidKeyedSessionIds(panes, surfaces, claudeByPid) {
+    const ttys = new Set(surfaces.map((surface) => normalizeTty(surface.tty)));
+    const overrides = new Map();
+    const unresolvedCodex = panes.flatMap((pane) => {
+        const pid = pidKeyedAgentPid(pane.currentSessionId, "codex");
+        return pid === undefined ? [] : [pid];
+    });
+    const codexByPid = await resolveCodexSessionIdsByRootPid(unresolvedCodex);
+    for (const pane of panes) {
+        const tty = normalizeTty(pane.paneId);
+        if (!ttys.has(tty))
+            continue;
+        const codexPid = pidKeyedAgentPid(pane.currentSessionId, "codex");
+        const codexId = codexPid === undefined ? undefined : codexByPid.get(codexPid);
+        if (codexId) {
+            overrides.set(tty, `codex:${codexId}`);
+            continue;
+        }
+        const claudePid = pidKeyedAgentPid(pane.currentSessionId, "claude");
+        if (claudePid === undefined)
+            continue;
+        const claudeId = claudeByPid.get(claudePid);
+        if (claudeId)
+            overrides.set(tty, `claude:${claudeId}`);
+    }
+    return overrides;
+}
+async function listTerminalSurfaces() {
+    const output = (await runAsync("osascript", ["-e", `
+set sep to ASCII character 31
+tell application "Terminal"
+  set output to ""
+  repeat with w in windows
+    try
+      set wname to name of w
+      repeat with t in tabs of w
+        try
+          set output to output & (tty of t) & sep & wname & (ASCII character 10)
+        end try
+      end repeat
+    end try
+  end repeat
+  return output
+end tell
+`], { timeoutMs: 5_000 })).trim();
+    return parseSurfaceLines(output, "native-terminal-app");
+}
+async function listItermSurfaces() {
+    const output = (await runAsync("osascript", ["-e", `
+set sep to ASCII character 31
+tell application "iTerm"
+  set output to ""
+  repeat with w in windows
+    try
+      set s to current session of current tab of w
+      set output to output & (tty of s as text) & sep & (name of w as text) & (ASCII character 10)
+    end try
+  end repeat
+  return output
+end tell
+`], { timeoutMs: 5_000 })).trim();
+    return parseSurfaceLines(output, "iterm");
+}
+function parseSurfaceLines(output, backend) {
+    if (!output)
+        return [];
+    return output.split(/\n/u).flatMap((line) => {
+        const [tty, name] = line.split(APPLE_FIELD_SEPARATOR);
+        return tty ? [{ backend, name: name ?? "", tty: tty.trim() }] : [];
+    });
+}
+async function captureSurface(surface) {
+    const application = surface.backend === "iterm" ? "iTerm" : "Terminal";
+    const contentExpression = surface.backend === "iterm" ? "contents of s" : "contents of tab ti of w";
+    return (await runAsync("osascript", ["-e", `
+tell application "${application}"
+  ${surface.backend === "iterm" ? `repeat with w in windows
+    try
+      set s to current session of current tab of w
+      if (tty of s as text) is ${appleString(surface.tty)} then return ${contentExpression}
+    end try
+  end repeat` : `repeat with wi from 1 to count windows
+    set w to window wi
+    repeat with ti from 1 to count tabs of w
+      if (tty of tab ti of w) is ${appleString(surface.tty)} then return ${contentExpression}
+    end repeat
+  end repeat`}
+  return ""
+end tell
+`], { timeoutMs: 5_000 })).replace(/\n+$/u, "");
+}
+async function submitSurfaceLine(surface, text) {
+    if (surface.backend === "iterm") {
+        await runAsync("osascript", ["-e", `
+tell application "iTerm"
+  repeat with w in windows
+    try
+      set s to current session of current tab of w
+      if (tty of s as text) is ${appleString(surface.tty)} then
+        tell s to write text ${appleString(text)}
+        return
+      end if
+    end try
+  end repeat
+end tell
+`], { timeoutMs: 5_000 });
+        return;
+    }
+    await runAsync("osascript", ["-e", `
+tell application "Terminal"
+  repeat with wi from 1 to count windows
+    set w to window wi
+    repeat with ti from 1 to count tabs of w
+      if (tty of tab ti of w) is ${appleString(surface.tty)} then
+        do script ${appleString(`${text}\n`)} in tab ti of w
+        return
+      end if
+    end repeat
+  end repeat
+end tell
+`], { timeoutMs: 5_000 });
+}
+async function resolveTtyRootPids(ttys) {
+    const bare = [...new Set(ttys.map(normalizeTty).filter(Boolean))];
+    if (bare.length === 0)
+        return [];
+    const output = await runAsync("ps", ["-t", bare.join(","), "-o", "pid=,ppid=,tty="], { timeoutMs: 5_000 }).catch(() => "");
+    const rowsByTty = new Map();
+    for (const line of output.split(/\n/u)) {
+        const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\S+)$/u);
+        if (!match?.[1] || !match[2] || !match[3])
+            continue;
+        const rowTty = normalizeTty(match[3]);
+        const key = bare.find((candidate) => candidate === rowTty || candidate.endsWith(rowTty) || rowTty.endsWith(candidate));
+        if (!key)
+            continue;
+        const rows = rowsByTty.get(key) ?? [];
+        rows.push({ pid: Number(match[1]), ppid: Number(match[2]), tty: key });
+        rowsByTty.set(key, rows);
+    }
+    return [...rowsByTty].flatMap(([tty, rows]) => {
+        const pids = new Set(rows.map((row) => row.pid));
+        const root = rows.filter((row) => !pids.has(row.ppid)).sort((left, right) => left.pid - right.pid)[0]
+            ?? [...rows].sort((left, right) => left.pid - right.pid)[0];
+        return root ? [{ rootPid: root.pid, tty }] : [];
+    });
+}
+async function resolveProcessCwd(pid) {
+    const output = await runAsync("lsof", ["-a", "-d", "cwd", "-p", String(pid), "-Fn"], { timeoutMs: 4_000 }).catch(() => "");
+    return output.split(/\n/u).find((line) => line.startsWith("n"))?.slice(1);
+}
+async function resolveCodexSessionIdsByRootPid(rootPids) {
+    const roots = [...new Set(rootPids.filter((pid) => Number.isInteger(pid) && pid > 0))];
+    if (roots.length === 0)
+        return new Map();
+    const rows = parseProcessRows(await runAsync("ps", ["-axo", "pid=,ppid=,comm="], { timeoutMs: 5_000 }).catch(() => ""));
+    const descendants = new Map(roots.map((root) => [root, collectDescendants(root, rows)]));
+    const candidates = rows.filter((row) => [...descendants.values()].some((pids) => pids.has(row.pid)) && /(?:^|\/)codex$/u.test(row.command));
+    if (candidates.length === 0)
+        return new Map();
+    const output = await runAsync("lsof", ["-Fn", "-a", "-p", candidates.map((row) => row.pid).join(",")], { timeoutMs: 5_000 }).catch(() => "");
+    const rolloutByPid = parseOpenCodexRollouts(output);
+    const resolved = new Map();
+    for (const [root, pids] of descendants) {
+        for (const pid of pids) {
+            const id = rolloutByPid.get(pid);
+            if (id) {
+                resolved.set(root, id);
+                break;
+            }
+        }
+    }
+    return resolved;
+}
+function parseOpenCodexRollouts(output) {
+    const result = new Map();
+    let pid;
+    for (const line of output.split("\n")) {
+        if (line.startsWith("p")) {
+            const value = Number(line.slice(1));
+            pid = Number.isInteger(value) && value > 0 ? value : undefined;
+        }
+        else if (pid !== undefined && line.startsWith("n")) {
+            const match = line.slice(1).match(CODEX_ROLLOUT_ID);
+            if (match?.[1])
+                result.set(pid, match[1]);
+        }
+    }
+    return result;
+}
+function parseProcessRows(output) {
+    return output.split("\n").flatMap((line) => {
+        const match = line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/u);
+        return match?.[1] && match[2] && match[3]
+            ? [{ command: match[3], pid: Number(match[1]), ppid: Number(match[2]) }]
+            : [];
+    });
+}
+function collectDescendants(root, rows) {
+    const children = new Map();
+    for (const row of rows)
+        children.set(row.ppid, [...(children.get(row.ppid) ?? []), row.pid]);
+    const result = new Set([root]);
+    const queue = [root];
+    while (queue.length > 0) {
+        const parent = queue.shift();
+        if (parent === undefined)
+            break;
+        for (const child of children.get(parent) ?? []) {
+            if (result.has(child))
+                continue;
+            result.add(child);
+            queue.push(child);
+        }
+    }
+    return result;
+}
+function latestClaudeSessionIdForCwd(cwd, claudeConfigDir) {
+    const directory = join(claudeConfigDir, "projects", cwd.replace(/[/. ]/gu, "-"));
+    let entries;
+    try {
+        entries = readdirSync(directory);
+    }
+    catch {
+        return undefined;
+    }
+    let newest;
+    for (const entry of entries) {
+        if (!entry.endsWith(".jsonl"))
+            continue;
+        try {
+            const mtimeMs = statSync(join(directory, entry)).mtimeMs;
+            if (!newest || mtimeMs > newest.mtimeMs)
+                newest = { id: entry.slice(0, -6), mtimeMs };
+        }
+        catch {
+            // The transcript may disappear between listing and stat.
+        }
+    }
+    return newest?.id;
+}
+function pidKeyedAgentPid(currentSessionId, agent) {
+    const match = currentSessionId?.match(new RegExp(`^${agent}:(\\d+)$`, "u"));
+    return match?.[1] ? Number(match[1]) : undefined;
+}
+function normalizeTty(tty) {
+    return tty?.trim().replace(/^\/dev\//u, "") ?? "";
+}
+async function applicationRunning(name) {
+    const output = await runAsync("pgrep", ["-a", "-x", name], { timeoutMs: 1_000 }).catch(() => "");
+    return output.trim().length > 0;
+}
+function appleString(value) {
+    return `"${String(value).replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+function assertSupportedPlatform() {
+    if (process.platform !== "darwin")
+        throw new Error(`Native macOS terminals are not supported on ${process.platform}.`);
+}

package/substrate/session-lifecycle.d.ts

@@ -0,0 +1,162 @@
+export { clearRollHeadVerdict, createSessionRollTracker, scanTranscriptHead } from "./session-roll.js";
+export type { HeadScan, SessionRollTracker } from "./session-roll.js";
+export type SessionLifecycleState = "session_running" | "session_stopped_background_running" | "session_unrecognized" | "session_waiting";
+export type PaneLifecycle = {
+    currentSessionId: string | null;
+    paneId: string;
+    processes?: PaneProcessLifecycle[];
+    rootPid: number;
+    sessionIds: string[];
+    target: string;
+};
+/** Exact live process inventory rooted at one host-owned pane. This is
+ * machine evidence, not an agent-session inference, so non-agent services can
+ * retain the same PID/start-time/listener authority as agent descendants. */
+export type PaneProcessLifecycle = {
+    args?: string;
+    command?: string;
+    listeners?: ProcessListener[];
+    pgid?: number;
+    pid: number;
+    ppid?: number;
+    processStartTime?: string;
+};
+export type SessionAttentionSignal = "asking" | "errored";
+export type DerivationSource = "agent-declared" | "cooperative" | "launch-context" | "process-tree" | "screen-heuristic" | "transcript";
+export type DerivationConfidence = "high" | "low";
+export type SessionDerivation<TValue = SessionLifecycleState> = {
+    confidence: DerivationConfidence;
+    disagrees?: DerivationSource[];
+    source: DerivationSource;
+    value: TValue;
+};
+export type CooperativeSignalEvent = "turn-end" | "turn-start";
+export type CooperativeSignal = {
+    atMs: number;
+    event: CooperativeSignalEvent;
+};
+export type CooperativeSignalStore = Map<string, CooperativeSignal>;
+export declare const COOPERATIVE_SIGNAL_TTL_MS = 120000;
+export declare function createCooperativeSignalStore(): CooperativeSignalStore;
+export declare function recordCooperativeSignal(store: CooperativeSignalStore, sessionId: string, event: string, nowMs: number): void;
+export type AttentionUrgency = "now" | "soon" | "whenever";
+export type AttentionRequest = {
+    detail?: string;
+    raisedAt: string;
+    reason: string;
+    urgency: AttentionUrgency;
+};
+export type AttentionRequestStore = Map<string, AttentionRequest>;
+export declare function createAttentionRequestStore(): AttentionRequestStore;
+export declare function isAttentionUrgency(value: unknown): value is AttentionUrgency;
+export declare function recordAttentionRequest(store: AttentionRequestStore, sessionId: string, request: {
+    detail?: string;
+    reason: string;
+    urgency: AttentionUrgency;
+}, nowMs: number): AttentionRequest;
+export declare function clearAttentionRequest(store: AttentionRequestStore, sessionId: string): void;
+export type SessionLifecycle = {
+    sessionId: string;
+    agentSessionId?: string;
+    harness: string;
+    cwd?: string;
+    isControl?: boolean;
+    attachedPaneId: string | null;
+    lastPaneId: string | null;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    state: SessionLifecycleState;
+    derivation: SessionDerivation;
+    signal?: SessionAttentionSignal;
+    mainPid?: number;
+    mainProcessStartTime?: string;
+    backgroundLeaseDir?: string;
+    background: BackgroundWorkItem[];
+    attentionRequest?: AttentionRequest;
+};
+export type LifecycleSnapshot = {
+    observedAt: string;
+    panes: PaneLifecycle[];
+    sessions: SessionLifecycle[];
+};
+export type LifecycleStore = {
+    derivationUnknownCount: number;
+    observeDurationMs: number;
+    panes: Map<string, PaneLifecycle>;
+    sessions: Map<string, SessionLifecycle>;
+};
+export type PaneProcessObservation = {
+    backgroundLeaseDir?: string;
+    contents?: string;
+    controlCwd?: string;
+    isControl?: boolean;
+    paneId: string;
+    target: string;
+    rootPid: number;
+    knownAgentSessionId?: string;
+};
+export type ProcessTreeRow = {
+    pid: number;
+    ppid: number;
+    pgid?: number;
+    stat?: string;
+    command: string;
+    args: string;
+    listeners?: ProcessListener[];
+    processStartTime?: string;
+};
+export type ProcessListener = {
+    address: string;
+    port: number;
+};
+export type BackgroundWorkItem = {
+    args?: string;
+    command?: string;
+    description?: string;
+    listeners?: ProcessListener[];
+    pid: number;
+    ppid?: number;
+    pgid?: number;
+    processStartTime?: string;
+    source: "descendant" | "explicit-lease" | "leased-descendant";
+};
+type BackgroundLeaseFile = {
+    args?: unknown;
+    command?: unknown;
+    description?: unknown;
+    pid?: unknown;
+    processStartTime?: unknown;
+};
+export declare function snapshotProcessTreeAsync(rootPids?: number[], options?: {
+    additionalPids?: number[];
+    includeListeners?: boolean;
+}): Promise<Map<number, ProcessTreeRow>>;
+export declare function snapshotProcessTree(rootPids?: number[]): Map<number, ProcessTreeRow>;
+export declare function snapshotDescendantPids(rootPids: number[]): number[];
+export declare function createLifecycleStore(): LifecycleStore;
+export type ObserveIo = {
+    cooperativeSignals?: CooperativeSignalStore;
+    leasesByDir: Map<string, BackgroundLeaseFile[]>;
+    sessionRolls?: Map<string, string>;
+    sessionRollClaims?: ReadonlyMap<string, string>;
+    startTimes: Map<number, string>;
+};
+export declare function gatherLifecycleObservation(panes: PaneProcessObservation[], store: LifecycleStore, rollTracker?: {
+    gather(sessionIds: string[], detectedIdsByPane?: ReadonlyMap<string, string>): Promise<Map<string, string>>;
+}): Promise<{
+    leasesByDir: ObserveIo["leasesByDir"];
+    processRows: Map<number, ProcessTreeRow>;
+    sessionRolls?: Map<string, string>;
+    startTimes: Map<number, string>;
+}>;
+export declare function observeLifecycle(options: {
+    io?: ObserveIo;
+    now?: Date;
+    panes: PaneProcessObservation[];
+    processRows: Map<number, ProcessTreeRow>;
+    store?: LifecycleStore;
+}): LifecycleSnapshot;
+export declare function classifyAttentionSignal(contents?: string): SessionAttentionSignal | undefined;
+export declare const DERIVATION_DEGRADED_LOG_TAG = "[substrate:lifecycle.derivation-degraded]";
+export declare function gatherProcessStartTimes(): Promise<Map<number, string>>;
+export declare function gatherBackgroundLeases(dirs: Array<string | undefined>): Promise<Map<string, BackgroundLeaseFile[]>>;