@phnx-labs/agents-cli 1.22.105 → 1.22.106

package/dist/session-tracker/dist/hook.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# Polyglot SessionStart hook.
+#
+# Registered as a SessionStart hook in each agent's native config file.
+# Each agent passes the hook payload differently:
+#   - claude/codex/cursor: JSON on stdin with session_id (+conversation_id for cursor)
+#   - grok: GROK_SESSION_ID and GROK_WORKSPACE_ROOT env vars
+#   - hermes: JSON on stdin (on_session_start payload); best-effort field probe
+#   - gemini/antigravity: best-effort stdin-JSON probe
+#
+# Writes ~/.agents/.cache/terminals/sessions/<PPID>.json with the canonical
+# SessionState schema from src/types.ts. Atomic via mktemp + mv.
+#
+# Invocation:
+#   hook.sh <agent>            # required; selects which payload format to parse
+#
+# Silent on success (SessionStart stdout leaks into the model context).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+TMP=""
+SID_TMP=""
+cleanup() {
+  [ -n "$TMP" ] && rm -f "$TMP"
+  [ -n "$SID_TMP" ] && rm -f "$SID_TMP"
+  return 0
+}
+trap cleanup EXIT
+
+AGENT="${1:-${AGENT_HINT:-}}"
+if [ -z "$AGENT" ]; then
+  exit 0
+fi
+
+# Read stdin if any (don't block forever).
+# Use `cat` only when stdin is not a TTY — and rely on hosts (claude, codex,
+# cursor) closing stdin promptly. macOS has no `timeout` in PATH by default,
+# so we don't use it.
+STDIN_JSON=""
+if [ ! -t 0 ]; then
+  STDIN_JSON="$(cat || true)"
+fi
+
+SID=""
+CWD=""
+METHOD="hook-stdin"
+
+extract_stdin_json() {
+  local field_priority="$1"  # space-separated list of JSON keys to try in order
+  python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    for k in '''$field_priority'''.split():
+        v = d.get(k)
+        if isinstance(v, str) and v:
+            print(v); sys.exit(0)
+        if isinstance(v, list) and v and isinstance(v[0], str):
+            print(v[0]); sys.exit(0)
+except Exception:
+    pass
+" 2>/dev/null || true
+}
+
+case "$AGENT" in
+  claude|codex|droid|kimi)
+    SID="$(printf '%s' "$STDIN_JSON" | extract_stdin_json 'session_id')"
+    CWD="$(printf '%s' "$STDIN_JSON" | extract_stdin_json 'cwd')"
+    ;;
+  cursor)
+    SID="$(printf '%s' "$STDIN_JSON" | extract_stdin_json 'session_id conversation_id')"
+    CWD="$(printf '%s' "$STDIN_JSON" | extract_stdin_json 'cwd workspace_roots')"
+    ;;
+  grok)
+    SID="${GROK_SESSION_ID:-}"
+    CWD="${GROK_WORKSPACE_ROOT:-$PWD}"
+    METHOD="hook-env"
+    ;;
+  hermes|gemini|antigravity)
+    # Best-effort stdin-JSON probe across the field names these harnesses use.
+    # A miss exits 0 below (no state file) — never a wrong write.
+    SID="$(printf '%s' "$STDIN_JSON" | extract_stdin_json 'session_id conversation_id sessionId')"
+    CWD="$(printf '%s' "$STDIN_JSON" | extract_stdin_json 'cwd workspace_roots')"
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+if [ -z "$SID" ]; then
+  exit 0
+fi
+
+# The session id becomes two filenames below. Reject path components before
+# either mktemp or mv sees the harness-provided value.
+case "$SID" in
+  *'/'*|*'\'*|'.'|'..') exit 0 ;;
+esac
+
+[ -z "$CWD" ] && CWD="$PWD"
+
+STATE_DIR="$HOME/.agents/.cache/terminals/sessions"
+mkdir -p "$STATE_DIR"
+
+TID="${AGENT_TERMINAL_ID:-}"
+LID="${AGENT_LAUNCH_ID:-}"
+
+TMP="$(mktemp "$STATE_DIR/.${PPID}.XXXXXX")"
+python3 - "$SID" "$CWD" "$PPID" "$AGENT" "$TID" "$LID" "$METHOD" > "$TMP" <<'PY'
+import json, sys, time
+sid, cwd, pid, agent, tid, lid, method = sys.argv[1:8]
+out = {
+    "session_id": sid,
+    "agent": agent,
+    "cwd": cwd,
+    "pid": int(pid),
+    "ts": int(time.time() * 1000),
+    "method": method,
+}
+if tid:
+    out["terminal_id"] = tid
+if lid:
+    out["launch_id"] = lid
+json.dump(out, sys.stdout)
+PY
+
+mv -f "$TMP" "$STATE_DIR/$PPID.json"
+
+# Prune dead-pid records, zero-byte files, and orphaned temp files left by
+# crashed atomic writes. Keep stdout/stderr silent — it leaks into the model.
+PRUNE_SCRIPT="$SCRIPT_DIR/../dist/prune-state.js"
+if [ -f "$PRUNE_SCRIPT" ]; then
+  node "$PRUNE_SCRIPT" >/dev/null 2>&1 || true
+fi
+
+# Persist launch metadata under the harness's real session id. `agents run`
+# exports the EFFECTIVE mode after capability/headless resolution, plus the
+# shared (non-version-home) history directory. Atomic replacement lets a native
+# resume with an explicit --mode become the new mode for the next resume.
+HISTORY_DIR="${AGENTS_HISTORY_DIR:-}"
+RUN_MODE="${AGENTS_RUN_MODE:-}"
+# The agents-cli version-home id this run launched under. Recorded here (not at
+# spawn) for the same reason as RUN_MODE: the harness coins its real session id
+# only after launch, so it must be joined to that id by this hook. A later native
+# resume pins the exact origin version off it, so a session whose transcript
+# carries no derivable version (codex's `.codex-homes/<version>/` home) still
+# resumes natively instead of degrading to `/continue` (PHNX-3626).
+RUN_VERSION="${AGENTS_RUN_VERSION:-}"
+RUN_ACCOUNT_ID="${AGENTS_RUN_ACCOUNT_ID:-}"
+TMUX_SESSION_NAME="${AGENT_TMUX_SESSION_NAME:-}"
+if [ -n "$HISTORY_DIR" ] && { [ -n "$RUN_MODE" ] || [ -n "$RUN_VERSION" ] || [ -n "$RUN_ACCOUNT_ID" ] || [ -n "$TMUX_SESSION_NAME" ]; }; then
+  BY_SESSION_DIR="$HISTORY_DIR/by-session"
+  mkdir -p "$BY_SESSION_DIR"
+  SID_TMP="$(mktemp "$BY_SESSION_DIR/.${SID}.XXXXXX")"
+  python3 - "$SID" "$RUN_MODE" "${AGENTS_ACTOR:-}" "${AGENTS_ACTOR_KIND:-}" "$TMUX_SESSION_NAME" "$BY_SESSION_DIR/$SID.json" "$RUN_VERSION" "$RUN_ACCOUNT_ID" > "$SID_TMP" <<'PY'
+import json, re, sys, time
+sid, mode, actor, initiated_by, tmux_name, existing_path, version, account_id = sys.argv[1:9]
+out = {}
+try:
+    with open(existing_path) as existing:
+        value = json.load(existing)
+        if isinstance(value, dict):
+            out = value
+except (OSError, ValueError):
+    pass
+out['sessionId'] = sid
+if mode in ('plan', 'edit', 'auto', 'skip'):
+    out['mode'] = mode
+if version:
+    out['version'] = version
+if account_id:
+    out.setdefault('accountId', account_id)
+out['startedAtMs'] = int(time.time() * 1000)
+if actor:
+    out['actor'] = actor
+if initiated_by in ('human', 'agent'):
+    out['initiatedBy'] = initiated_by
+if re.fullmatch(r'ag-[a-z][a-z0-9-]*-[0-9a-f]{8}', tmux_name, re.I):
+    aliases = out.get('aliases')
+    if not isinstance(aliases, list):
+        aliases = []
+    aliases = [alias.lower() for alias in aliases if isinstance(alias, str) and re.fullmatch(r'ag-[a-z][a-z0-9-]*-[0-9a-f]{8}', alias, re.I)]
+    aliases.append(tmux_name.lower())
+    out['aliases'] = list(dict.fromkeys(aliases))
+json.dump(out, sys.stdout)
+PY
+  mv -f "$SID_TMP" "$BY_SESSION_DIR/$SID.json"
+fi
+exit 0

package/dist/session-tracker/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { DetectionResult, LookupInput, SessionState, TrackSpawnInput } from './types.js';
+export * from './types.js';
+export * from './state-file.js';
+export * from './writer.js';
+export * from './install-hook.js';
+export { descendantPids, findStateByPid, findStateInTree, findStateByTerminalId, findStateByLaunchId, pruneStaleSessionState, } from './reader.js';
+export interface TrackSpawnOptions {
+    /** Max time to wait for the SessionStart hook to land the state file. Default 5000ms. */
+    timeoutMs?: number;
+    /** Poll interval. Default 50ms. */
+    pollIntervalMs?: number;
+}
+/**
+ * Wait for the polyglot SessionStart hook (src/hook.sh) to drop a state file
+ * at stateFilePath(input.agentPid). Resolves as soon as it appears.
+ * Returns confidence='low' / sessionId=null on timeout.
+ */
+export declare function trackSpawn(input: TrackSpawnInput, opts?: TrackSpawnOptions): Promise<DetectionResult>;
+export declare function getLiveSession(input: LookupInput): Promise<SessionState | null>;

package/dist/session-tracker/dist/index.js

@@ -0,0 +1,67 @@
+import * as fs from 'fs';
+import { parseState, stateFilePath } from './state-file.js';
+import { findStateByLaunchId, findStateByTerminalId, findStateInTree, } from './reader.js';
+export * from './types.js';
+export * from './state-file.js';
+export * from './writer.js';
+export * from './install-hook.js';
+export { descendantPids, findStateByPid, findStateInTree, findStateByTerminalId, findStateByLaunchId, pruneStaleSessionState, } from './reader.js';
+/**
+ * Wait for the polyglot SessionStart hook (src/hook.sh) to drop a state file
+ * at stateFilePath(input.agentPid). Resolves as soon as it appears.
+ * Returns confidence='low' / sessionId=null on timeout.
+ */
+export async function trackSpawn(input, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5000;
+    const pollIntervalMs = opts.pollIntervalMs ?? 50;
+    const start = Date.now();
+    const targetPath = stateFilePath(input.agentPid);
+    while (Date.now() - start < timeoutMs) {
+        const state = await readStateIfPresent(targetPath);
+        if (state) {
+            return {
+                sessionId: state.session_id,
+                method: state.method,
+                latencyMs: Date.now() - start,
+                confidence: 'high',
+            };
+        }
+        await sleep(pollIntervalMs);
+    }
+    return {
+        sessionId: null,
+        method: null,
+        latencyMs: Date.now() - start,
+        confidence: 'low',
+    };
+}
+export async function getLiveSession(input) {
+    if (input.launchId) {
+        const byLaunch = await findStateByLaunchId(input.launchId);
+        if (byLaunch)
+            return byLaunch;
+    }
+    if (input.terminalId) {
+        const byTerm = await findStateByTerminalId(input.terminalId);
+        if (byTerm)
+            return byTerm;
+    }
+    if (input.shellPid) {
+        return findStateInTree(input.shellPid);
+    }
+    return null;
+}
+async function readStateIfPresent(p) {
+    try {
+        const raw = await fs.promises.readFile(p, 'utf8');
+        return parseState(raw);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        return null;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/session-tracker/dist/install-hook.d.ts

@@ -0,0 +1,19 @@
+import type { AgentId } from './types.js';
+export interface InstallResult {
+    agent: AgentId;
+    installed: boolean;
+    configPath: string;
+    error?: string;
+}
+export interface InstallOptions {
+    dryRun?: boolean;
+    hookPathOverride?: string;
+    /** Home directory whose harness-native config should be written. Defaults to
+     *  `os.homedir()` so the live config (usually a symlink into the active
+     *  version home) is updated. */
+    home?: string;
+}
+/** Every agent id the hook installer knows — the keys of the compile-time-complete
+ *  {@link HOOK_SUPPORT} table (Record<AgentId, …>), so this can never drift from AgentId. */
+export declare const HOOK_AGENTS: AgentId[];
+export declare function installHookFor(agent: AgentId, opts?: InstallOptions): Promise<InstallResult>;

package/dist/session-tracker/dist/install-hook.js

@@ -0,0 +1,245 @@
+// Installs the polyglot src/hook.sh as a SessionStart hook in each agent's
+// native config file. Idempotent — running twice does not double-register.
+//
+// CLI usage:
+//   tsx src/install-hook.ts claude
+//   tsx src/install-hook.ts claude codex cursor
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import * as TOML from 'smol-toml';
+import * as YAML from 'yaml';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const HOOK_PATH = path.resolve(__dirname, 'hook.sh');
+function hookCommand(agent, opts) {
+    const hook = opts.hookPathOverride ?? HOOK_PATH;
+    return `${hook} ${agent}`;
+}
+/** True when a stored command string is a prior registration of this package's
+ *  `hook.sh` (src or dist). Used for idempotency when stripping old entries. */
+function isOwnHookCommand(command) {
+    const first = command.trim().split(/\s+/)[0];
+    return first.endsWith('hook.sh') && first.includes('session-tracker');
+}
+async function readJson(p) {
+    try {
+        const raw = await fs.promises.readFile(p, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return {};
+        throw err;
+    }
+}
+async function writeJsonAtomic(p, data) {
+    await fs.promises.mkdir(path.dirname(p), { recursive: true });
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await fs.promises.writeFile(tmp, JSON.stringify(data, null, 2), 'utf8');
+        await fs.promises.rename(tmp, p);
+    }
+    catch (err) {
+        try {
+            await fs.promises.unlink(tmp);
+        }
+        catch { /* best-effort */ }
+        throw err;
+    }
+}
+async function installClaude(opts) {
+    const configPath = path.join(opts.home ?? os.homedir(), '.claude', 'settings.json');
+    const command = hookCommand('claude', opts);
+    if (opts.dryRun) {
+        return { agent: 'claude', installed: false, configPath };
+    }
+    const cfg = await readJson(configPath);
+    cfg.hooks = cfg.hooks ?? {};
+    cfg.hooks.SessionStart = cfg.hooks.SessionStart ?? [];
+    // Remove any prior registration of THIS hook path (idempotency).
+    for (const entry of cfg.hooks.SessionStart) {
+        if (!entry || !Array.isArray(entry.hooks))
+            continue;
+        entry.hooks = entry.hooks.filter((h) => !(h && h.command && isOwnHookCommand(h.command)));
+    }
+    // Find or create the empty-matcher group and add our hook.
+    let group = cfg.hooks.SessionStart.find((e) => e && e.matcher === '');
+    if (!group) {
+        group = { matcher: '', hooks: [] };
+        cfg.hooks.SessionStart.push(group);
+    }
+    group.hooks.push({ type: 'command', command, timeout: 5 });
+    await writeJsonAtomic(configPath, cfg);
+    return { agent: 'claude', installed: true, configPath };
+}
+async function installCodex(opts) {
+    const configPath = path.join(opts.home ?? os.homedir(), '.codex', 'hooks.json');
+    const command = hookCommand('codex', opts);
+    if (opts.dryRun) {
+        return { agent: 'codex', installed: false, configPath };
+    }
+    const cfg = await readJson(configPath);
+    cfg.hooks = cfg.hooks ?? {};
+    cfg.hooks.SessionStart = cfg.hooks.SessionStart ?? [];
+    for (const entry of cfg.hooks.SessionStart) {
+        if (!entry || !Array.isArray(entry.hooks))
+            continue;
+        entry.hooks = entry.hooks.filter((h) => !(h && h.command && isOwnHookCommand(h.command)));
+    }
+    let group = cfg.hooks.SessionStart.find((e) => e && (e.matcher === '' || e.matcher === 'startup|resume'));
+    if (!group) {
+        group = { matcher: 'startup|resume', hooks: [] };
+        cfg.hooks.SessionStart.push(group);
+    }
+    group.hooks.push({ type: 'command', command, timeout: 5 });
+    await writeJsonAtomic(configPath, cfg);
+    return { agent: 'codex', installed: true, configPath };
+}
+async function installCursor(opts) {
+    const configPath = path.join(opts.home ?? os.homedir(), '.cursor', 'hooks.json');
+    const command = hookCommand('cursor', opts);
+    if (opts.dryRun) {
+        return { agent: 'cursor', installed: false, configPath };
+    }
+    const cfg = await readJson(configPath);
+    cfg.hooks = cfg.hooks ?? {};
+    cfg.hooks.sessionStart = cfg.hooks.sessionStart ?? [];
+    cfg.hooks.sessionStart = cfg.hooks.sessionStart.filter((h) => !(h && h.command && isOwnHookCommand(h.command)));
+    cfg.hooks.sessionStart.push({ type: 'command', command, timeout: 5 });
+    await writeJsonAtomic(configPath, cfg);
+    return { agent: 'cursor', installed: true, configPath };
+}
+async function installGrok(opts) {
+    const configPath = path.join(opts.home ?? os.homedir(), '.grok', 'hooks', 'session-start.json');
+    const command = hookCommand('grok', opts);
+    if (opts.dryRun) {
+        return { agent: 'grok', installed: false, configPath };
+    }
+    await writeJsonAtomic(configPath, { command, timeout: 5 });
+    return { agent: 'grok', installed: true, configPath };
+}
+async function installDroid(opts) {
+    const configPath = path.join(opts.home ?? os.homedir(), '.factory', 'settings.json');
+    const command = hookCommand('droid', opts);
+    if (opts.dryRun)
+        return { agent: 'droid', installed: false, configPath };
+    const cfg = await readJson(configPath);
+    cfg.hooks = cfg.hooks ?? {};
+    cfg.hooks.SessionStart = cfg.hooks.SessionStart ?? [];
+    for (const entry of cfg.hooks.SessionStart) {
+        if (!entry || !Array.isArray(entry.hooks))
+            continue;
+        entry.hooks = entry.hooks.filter((hook) => !(hook?.command && String(hook.command).includes('packages/session-tracker/src/hook.sh')));
+    }
+    let group = cfg.hooks.SessionStart.find((entry) => entry?.matcher === '');
+    if (!group) {
+        group = { matcher: '', hooks: [] };
+        cfg.hooks.SessionStart.push(group);
+    }
+    group.hooks.push({ type: 'command', command, timeout: 5 });
+    await writeJsonAtomic(configPath, cfg);
+    return { agent: 'droid', installed: true, configPath };
+}
+async function installKimi(opts) {
+    const configPath = path.join(opts.home ?? os.homedir(), '.kimi-code', 'config.toml');
+    const command = hookCommand('kimi', opts);
+    if (opts.dryRun)
+        return { agent: 'kimi', installed: false, configPath };
+    let cfg = {};
+    try {
+        cfg = TOML.parse(await fs.promises.readFile(configPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const hooks = (Array.isArray(cfg.hooks) ? cfg.hooks : []);
+    cfg.hooks = [
+        ...hooks.filter((hook) => !(typeof hook.command === 'string' && isOwnHookCommand(hook.command))),
+        { event: 'SessionStart', command, timeout: 5 },
+    ];
+    await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.promises.writeFile(configPath, TOML.stringify(cfg), 'utf8');
+    return { agent: 'kimi', installed: true, configPath };
+}
+async function installHermes(opts) {
+    const configPath = path.join(opts.home ?? os.homedir(), '.hermes', 'config.yaml');
+    const command = hookCommand('hermes', opts);
+    if (opts.dryRun)
+        return { agent: 'hermes', installed: false, configPath };
+    // Read-modify-write the YAML, preserving every sibling key (mcp_servers, …) —
+    // mirrors the CLI's registerHooksForHermes. Hermes maps SessionStart to the
+    // `on_session_start` event (HERMES_EVENT_MAP in cli/src/lib/hooks/install.ts).
+    let cfg = {};
+    try {
+        const parsed = YAML.parse(await fs.promises.readFile(configPath, 'utf8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            cfg = parsed;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const hooks = cfg.hooks && typeof cfg.hooks === 'object' && !Array.isArray(cfg.hooks)
+        ? cfg.hooks
+        : {};
+    const existing = Array.isArray(hooks.on_session_start) ? hooks.on_session_start : [];
+    hooks.on_session_start = [
+        ...existing.filter((h) => !(typeof h?.command === 'string' && isOwnHookCommand(h.command))),
+        { command, timeout: 5 },
+    ];
+    cfg.hooks = hooks;
+    await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.promises.writeFile(configPath, YAML.stringify(cfg), 'utf8');
+    return { agent: 'hermes', installed: true, configPath };
+}
+const HOOK_SUPPORT = {
+    claude: { install: installClaude },
+    codex: { install: installCodex },
+    cursor: { install: installCursor },
+    grok: { install: installGrok },
+    droid: { install: installDroid },
+    kimi: { install: installKimi },
+    hermes: { install: installHermes },
+    gemini: { unsupported: 'gemini is hard-deprecated (kept only for parsing old sessions)' },
+    antigravity: { unsupported: 'antigravity has no SessionStart hook event' },
+    opencode: { unsupported: 'opencode SessionStart is a generated plugin, not a shell-command hook' },
+};
+/** Every agent id the hook installer knows — the keys of the compile-time-complete
+ *  {@link HOOK_SUPPORT} table (Record<AgentId, …>), so this can never drift from AgentId. */
+export const HOOK_AGENTS = Object.keys(HOOK_SUPPORT);
+export async function installHookFor(agent, opts = {}) {
+    const support = HOOK_SUPPORT[agent];
+    if (!support) {
+        return { agent, installed: false, configPath: '', error: `unknown agent '${agent}'` };
+    }
+    if ('unsupported' in support) {
+        return { agent, installed: false, configPath: '', error: support.unsupported };
+    }
+    try {
+        return await support.install(opts);
+    }
+    catch (err) {
+        return {
+            agent,
+            installed: false,
+            configPath: '',
+            error: err.message,
+        };
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const agents = process.argv.slice(2);
+    if (agents.length === 0) {
+        console.error('usage: tsx src/install-hook.ts <agent> [<agent>...]');
+        process.exit(2);
+    }
+    for (const a of agents) {
+        const r = await installHookFor(a);
+        console.log(JSON.stringify(r));
+        if (r.error)
+            process.exitCode = 1;
+    }
+}

package/dist/session-tracker/dist/prune-state.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/session-tracker/dist/prune-state.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Prune stale entries from the SessionStart hook state directory.
+// Called by hook.sh after a successful write so the directory never accumulates
+// dead-pid records, zero-byte files, or orphaned temp files.
+import { cleanupOrphanedStateFiles } from './state-file.js';
+await cleanupOrphanedStateFiles();
+// Stay silent — stdout from SessionStart hooks leaks into the model context.

package/dist/session-tracker/dist/reader.d.ts

@@ -0,0 +1,7 @@
+import type { SessionState } from './types.js';
+export declare function descendantPids(rootPid: number): Promise<number[]>;
+export declare function findStateByPid(pid: number): Promise<SessionState | null>;
+export declare function findStateInTree(shellPid: number): Promise<SessionState | null>;
+export declare function findStateByTerminalId(terminalId: string): Promise<SessionState | null>;
+export declare function findStateByLaunchId(launchId: string): Promise<SessionState | null>;
+export declare function pruneStaleSessionState(): Promise<number>;