@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/session/presence.js

@@ -1,32 +1,8 @@
-/**
- * RUSH-2007 Layer C — per-session presence tracking, folded into the `agents
- * watchdog` tick (NOT a revived daemon).
- *
- * Each tick the watchdog observes the active sessions across the fleet
- * (`gatherRemoteActive` + the local scan). This module persists one record per
- * session — `{location, device, transport, lastSeen, status}` — and DERIVES
- * `connected` / `disconnected` by diffing consecutive observations: a session
- * present this tick is `connected`; one that was tracked but is now absent (its
- * peer went unreachable, or the interactive client dropped) flips to
- * `disconnected` while its record — and the transition — is surfaced so the tick
- * can act (an interactive drop is a reconnect-nudge candidate; a headless remote
- * is a keep-alive). The store is honest across a crash: it only reflects what the
- * last scan actually saw, never an asserted state.
- *
- * Store: `~/.agents/.cache/state/watchdog/presence.json` — sibling of the tick's
- * existing `nudges/flags/last-tick` files. Best-effort: an unreadable/corrupt
- * file degrades to an empty store, never throws into the tick loop.
- */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { getRuntimeStateDir } from '../state.js';
-/** A `disconnected` record older than this is pruned — the session is gone for
- *  good, not merely between clients. Kept generous so a long reconnect window
- *  (the reconnect loop's own bounded backoff) never drops a record mid-recovery. */
-export const PRESENCE_TTL_MS = 30 * 60_000; // 30 minutes
-/** `presence.json` under the watchdog state dir. `dir` is the watchdog state dir
- *  (the tick passes its own, overridable in tests); default is the real one. */
+export const PRESENCE_TTL_MS = 30 * 60_000;
 export function presenceFilePath(dir) {
     return path.join(dir ?? path.join(getRuntimeStateDir(), 'watchdog'), 'presence.json');
 }
@@ -45,7 +21,6 @@ export function loadPresence(dir) {
         }
     }
     catch {
-        /* corrupt — degrade to empty, never throw into the tick */
     }
     return {};
 }
@@ -56,16 +31,8 @@ export function savePresence(map, dir) {
         fs.writeFileSync(file, JSON.stringify(map), 'utf8');
     }
     catch {
-        /* best-effort; a failed write just re-derives next tick */
     }
 }
-/**
- * Map this tick's active sessions to presence observations. A session on a peer
- * carries `machine` (from the fleet fan-out) → `location: 'ssh'`; a local one →
- * `'local'`. `interactive` is true only for a `terminal` context (a tmux/terminal
- * session whose drop is reconnect-worthy) — headless/teams/cloud are not.
- * Sessions with no id are skipped (they can't be tracked or addressed).
- */
 export function observedFromActive(sessions, selfHost = os.hostname()) {
     const out = [];
     for (const s of sessions) {
@@ -83,9 +50,6 @@ export function observedFromActive(sessions, selfHost = os.hostname()) {
     }
     return out;
 }
-/** The action for a session that just flipped to `disconnected`: an interactive
- *  session wants a reconnect nudge; a headless remote wants keep-alive; a local
- *  headless that vanished is simply gone (no action). */
 export function actionFor(record) {
     if (record.status !== 'disconnected')
         return 'none';
@@ -95,23 +59,10 @@ export function actionFor(record) {
         return 'keep-alive';
     return 'none';
 }
-/**
- * Pure state machine. Given the prior store, the sessions observed THIS tick, and
- * `nowMs`, return the next store plus the set of status transitions.
- *
- * - observed now                 -> `connected`, lastSeen = now (record refreshed)
- * - tracked but absent now       -> `disconnected` (lastSeen kept from prior tick)
- * - `disconnected` older than TTL -> pruned (gone for good)
- *
- * `transitions` carries only sessions whose status actually changed, each with
- * the action the tick should take — so the caller never re-nudges a session that
- * was already disconnected last tick.
- */
 export function reconcilePresence(prev, observed, nowMs) {
     const next = {};
     const transitions = [];
     const observedIds = new Set(observed.map((o) => o.sessionId));
-    // 1. Everything observed this tick is connected.
     for (const o of observed) {
         const before = prev[o.sessionId];
         const record = {
@@ -129,12 +80,11 @@ export function reconcilePresence(prev, observed, nowMs) {
             transitions.push({ record, from: 'disconnected', to: 'connected', action: 'none' });
         }
     }
-    // 2. Tracked-but-absent sessions flip to disconnected (or prune past TTL).
     for (const [id, before] of Object.entries(prev)) {
         if (observedIds.has(id))
             continue;
         if (nowMs - before.lastSeenMs > PRESENCE_TTL_MS)
-            continue; // prune: gone for good
+            continue;
         const record = { ...before, status: 'disconnected' };
         next[id] = record;
         if (before.status === 'connected') {

package/dist/lib/session/process-view.d.ts

@@ -1,25 +1,14 @@
 export interface HostProcessView {
     bootId?: string;
     pidNamespace?: string;
-    /** Namespace inodes can be reused within one boot; its init identifies the incarnation. */
     initStartTicks?: string;
     ownerPid?: number;
     ownerStartTicks?: string;
 }
-/** Measure the calling process, never infer authority from a process name. */
 export declare function currentProcessView(): HostProcessView | undefined;
-/** Read-only ownership check. Observing a HOME never claims or migrates it. */
 export declare function hostProcessView(): HostProcessView | undefined;
-/** Explicit writers may enroll a fresh HOME in their measured namespace.
- * Foreign ownership remains protected even when the prior writer is invisible.
- * The initial host may enroll legacy state before daemon startup. */
 export declare function writerProcessView(): HostProcessView | undefined;
-/** Preflight BEFORE even the PID-keyed legacy lifecycle lock is inspected.
- * The same decision is repeated under that lock before daemon state changes. */
 export declare function daemonProcessViewAllowed(): boolean;
-/** Called by the canonical daemon writer before lifecycle mutation.
- * This is a writer statement, not an observer's guess about a numeric PID.
- * Existing same-boot ownership cannot be taken over from another namespace. */
 export declare function recordDaemonProcessView(): void;
 export declare function requireHostProcessView(): void;
 export declare function requireWriterProcessView(): void;

package/dist/lib/session/process-view.js

@@ -3,9 +3,6 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { getCacheDir, getTerminalsDir, getDaemonDir } from '../state.js';
 import { atomicWriteFileSync, withFileLock } from '../fs-atomic.js';
-// Linux UAPI PID_NS_INIT_INO (include/uapi/linux/nsfs.h; previously
-// PROC_PID_INIT_INO in include/linux/proc_ns.h). This is a kernel-defined
-// namespace identity, independent of PID 1's executable or command name.
 function isInitialPidNamespace(view) {
     return view.pidNamespace === 'pid:[4026531836]';
 }
@@ -13,9 +10,6 @@ function sameProcessView(owner, view) {
     return owner.bootId === view.bootId && owner.pidNamespace === view.pidNamespace
         && owner.initStartTicks === view.initStartTicks;
 }
-/** Authenticate the legacy singleton with kernel socket credentials. A host
- * daemon invisible in a nested namespace has peer PID 0, never a colliding PID.
- * No socket/PID/command-name guess grants migration authority. */
 function verifiedLegacyDaemon() {
     try {
         execFileSync('python3', ['-c', `import os,socket,struct,sys
@@ -38,13 +32,10 @@ assert os.readlink('/proc/%d/ns/pid'%pid)==os.readlink('/proc/self/ns/pid')
 function hasLegacyState() {
     return [path.join(getTerminalsDir(), 'by-pid'), path.join(getCacheDir(), 'state', 'sessions')]
         .some(dir => fs.existsSync(dir) && fs.readdirSync(dir).length > 0)
-        // Health/log output records attempted starts, not ownership. The ordinary
-        // start path writes health.json BEFORE spawning its first daemon.
         || ['daemon.pid', 'daemon.lifetime', 'heartbeat.json'].some(file => fs.existsSync(path.join(getDaemonDir(), file)))
         || fs.existsSync(path.join(getCacheDir(), 'helpers', 'browser', 'browser.sock'))
         || ['.active-sessions.json', '.active-session-immutable.json'].some(file => fs.existsSync(path.join(getCacheDir(), file)));
 }
-/** Measure the calling process, never infer authority from a process name. */
 export function currentProcessView() {
     if (process.platform !== 'linux')
         return {};
@@ -53,8 +44,6 @@ export function currentProcessView() {
             return undefined;
         const bootId = fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
         const pidNamespace = fs.readlinkSync('/proc/self/ns/pid');
-        // NSpid is relative to the procfs mount. Multiple coordinates mean this
-        // mount exposes an ancestor namespace, even if numeric PIDs happen to match.
         const procPids = fs.readFileSync('/proc/self/status', 'utf8').match(/^NSpid:\s+([^\n]+)$/m)?.[1].trim().split(/\s+/);
         if (procPids?.length !== 1 || Number(procPids[0]) !== process.pid)
             return undefined;
@@ -69,7 +58,6 @@ export function currentProcessView() {
         return undefined;
     }
 }
-/** Read-only ownership check. Observing a HOME never claims or migrates it. */
 export function hostProcessView() {
     const view = currentProcessView();
     if (!view || process.platform !== 'linux')
@@ -79,14 +67,9 @@ export function hostProcessView() {
         return sameProcessView(owner, view) ? view : undefined;
     }
     catch (error) {
-        // The initial kernel namespace is authoritative before any daemon has
-        // enrolled this HOME. This observation itself must remain read-only.
         return error.code === 'ENOENT' && isInitialPidNamespace(view) ? view : undefined;
     }
 }
-/** Explicit writers may enroll a fresh HOME in their measured namespace.
- * Foreign ownership remains protected even when the prior writer is invisible.
- * The initial host may enroll legacy state before daemon startup. */
 export function writerProcessView() {
     const view = currentProcessView();
     if (!view || process.platform !== 'linux')
@@ -97,8 +80,6 @@ export function writerProcessView() {
             const owner = JSON.parse(fs.readFileSync(file, 'utf8'));
             return sameProcessView(owner, view) ? view : undefined;
         }
-        // A foreign observer of legacy state must not even create a directory or
-        // claim lock. Repeat this preflight under the lock before enrollment.
         if (hasLegacyState() && !isInitialPidNamespace(view))
             return undefined;
         fs.mkdirSync(getTerminalsDir(), { recursive: true });
@@ -107,7 +88,6 @@ export function writerProcessView() {
                 const owner = JSON.parse(fs.readFileSync(file, 'utf8'));
                 return sameProcessView(owner, view) ? view : undefined;
             }
-            // Unowned nonempty registry is not evidence this caller owns the host.
             if (hasLegacyState() && !isInitialPidNamespace(view))
                 return undefined;
             atomicWriteFileSync(file, JSON.stringify(view), 'utf8');
@@ -118,8 +98,6 @@ export function writerProcessView() {
         return undefined;
     }
 }
-/** Preflight BEFORE even the PID-keyed legacy lifecycle lock is inspected.
- * The same decision is repeated under that lock before daemon state changes. */
 export function daemonProcessViewAllowed() {
     const view = currentProcessView();
     if (!view)
@@ -140,9 +118,6 @@ export function daemonProcessViewAllowed() {
         return false;
     }
 }
-/** Called by the canonical daemon writer before lifecycle mutation.
- * This is a writer statement, not an observer's guess about a numeric PID.
- * Existing same-boot ownership cannot be taken over from another namespace. */
 export function recordDaemonProcessView() {
     const view = currentProcessView();
     if (!view)

package/dist/lib/session/projection.d.ts

@@ -1,13 +1,10 @@
 import type { SessionWatchEnvelope, SessionWatchRow } from './watch.js';
-/** Device observations are not sessions: a launcher may observe a peer's run.
- * Keep those observations separately and publish execution-owned state once. */
 export declare class SessionProjection {
     private readonly observations;
     private projected;
     private selected;
     private sequence;
     private readonly streamId;
-    /** Only the selected observation may publish execution-owned attention. */
     rowForObservation(scope: string, rowKey: string): SessionWatchRow | undefined;
     apply(event: SessionWatchEnvelope): SessionWatchEnvelope[];
 }

package/dist/lib/session/projection.js

@@ -1,14 +1,11 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { normalizeHost } from '../machine-id.js';
-/** Device observations are not sessions: a launcher may observe a peer's run.
- * Keep those observations separately and publish execution-owned state once. */
 export class SessionProjection {
     observations = new Map();
     projected = new Map();
     selected = new Map();
     sequence = 0;
     streamId = randomUUID();
-    /** Only the selected observation may publish execution-owned attention. */
     rowForObservation(scope, rowKey) {
         const key = this.selected.get(`${normalizeHost(scope)}\0${rowKey}`);
         return key ? this.projected.get(key) : undefined;
@@ -26,11 +23,8 @@ export class SessionProjection {
             this.observations.get(scope)?.delete(event.rowKey);
         const stamp = () => ({ version: 1, streamId: this.streamId, sequence: ++this.sequence, capturedAt: event.capturedAt });
         if (event.type === 'scope' || event.type === 'heartbeat') {
-            // An unavailable owner retains its last observation until its next reset.
             return [{ ...event, ...stamp(), scope }];
         }
-        // A launch exists before a non-Claude harness mints its session id. Join an
-        // id-less placeholder only through an exact, unambiguous durable launch id.
         const launchSessions = new Map();
         for (const [observer, rows] of this.observations)
             for (const row of rows.values()) {
@@ -59,8 +53,6 @@ export class SessionProjection {
         for (const [rowKey, observations] of groups) {
             const owner = normalizeHost(observations[0].row.machine || observations[0].row.sourceDevice || observations[0].scope);
             const authoritative = observations.filter(item => item.scope === owner);
-            // Once the owner has answered, its absence is authoritative too. A stale
-            // launcher/history mirror cannot resurrect a removed execution.
             const candidates = authoritative.length ? authoritative : this.observations.has(owner) ? [] : observations;
             candidates.sort((a, b) => Number(a.row.previous) - Number(b.row.previous)
                 || (b.row.lastActivityMs ?? b.row.startedAtMs ?? 0) - (a.row.lastActivityMs ?? a.row.startedAtMs ?? 0)
@@ -82,8 +74,6 @@ export class SessionProjection {
             });
         }
         const result = [];
-        // A reset still replaces only its source scope. Cross-scope migrations are
-        // explicit removes/upserts, so existing clients converge without a new API.
         if (event.type === 'reset')
             result.push({ ...stamp(), type: 'reset', scope, rows: [...next.values()].filter(row => row.sourceDevice === scope) });
         for (const [key, row] of this.projected)

package/dist/lib/session/provenance.d.ts

@@ -6,70 +6,34 @@ export interface SshOrigin {
 }
 export interface MuxLocation {
     kind: 'tmux' | 'screen';
-    /** tmux server socket path (first comma-field of $TMUX). Undefined for screen. */
     socket?: string;
-    /** Exact pane id from $TMUX_PANE, e.g. '%3' — the send-keys target. */
     pane?: string;
-    /** screen session name from $STY, e.g. '12345.pts-0.host'. */
     session?: string;
 }
-/** How the feed can type back into a session, derived from env rails that exist today. */
 export type ReplyRail = {
     rail: 'tmux';
     target: string;
     socket?: string;
-}
-/** iTerm2 split addressed by its session UUID (the part of $ITERM_SESSION_ID after ':'). */
- | {
+} | {
     rail: 'iterm';
     session: string;
 } | null;
 export interface SessionProvenance {
-    /** Machine the process runs on — os.hostname(). Drives HOSTS grouping. */
     host: string;
-    /** 'ssh' when SSH_CONNECTION is present in the process env, else 'local'. */
     transport: 'local' | 'ssh';
-    /** Populated when transport === 'ssh'. */
     ssh?: SshOrigin;
-    /** TERM_PROGRAM: 'iTerm.app', 'vscode', 'WezTerm', 'tmux', 'Apple_Terminal', … */
     term?: string;
-    /** Multiplexer the process sits inside, from $TMUX / $STY. */
     mux?: MuxLocation;
-    /** Whether an existing rail can type back into this session (see module doc). */
     reply: ReplyRail;
-    /** The initiating device, resolved at query time from ssh.clientIp against the
-     * device registry (ssh transport only). Answers "who launched this and from
-     * where" without scraping ps/who/tailscale. */
     origin?: {
         device: string;
         user?: string;
     };
 }
-/** Env vars that carry provenance. Kept small so the macOS `ps` scan stays cheap. */
 export declare const PROVENANCE_ENV_KEYS: readonly ["SSH_CONNECTION", "SSH_TTY", "TMUX", "TMUX_PANE", "TERM_PROGRAM", "STY", "ITERM_SESSION_ID"];
-/**
- * Extract the iTerm2 session UUID from `$ITERM_SESSION_ID`, whose value is
- * `w<window>t<tab>p<pane>:<UUID>` — the `:`-suffix is exactly what iTerm2's
- * `id of session` returns, so it's the address for `tell session id …`. Returns
- * undefined for an empty/absent value; tolerates a bare value with no `:`.
- */
 export declare function parseItermSession(value?: string): string | undefined;
-/** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
 export declare function parseProcEnviron(buf: string): Record<string, string>;
-/**
- * Pull known env vars out of a macOS `ps eww` command+env line. For each
- * `KEY=` match we consume the declared number of tokens (default 1), so
- * SSH_CONNECTION's internal spaces survive while a following unknown var
- * (e.g. `PWD=…`) is not swallowed into the previous value.
- */
 export declare function extractKnownEnv(text: string, keys: readonly string[]): Record<string, string>;
-/** `<client_ip> <client_port> <server_ip> <server_port>` → structured origin. */
 export declare function parseSshConnection(value: string): SshOrigin | undefined;
-/** Build a SessionProvenance from a raw env map + the local hostname. Pure. */
 export declare function deriveProvenance(env: Record<string, string>, hostname: string): SessionProvenance;
-/**
- * Resolve provenance for a live pid. Returns undefined when the process env
- * can't be read (process gone, foreign uid, unsupported platform) — we never
- * fabricate a 'local' answer we can't back with the env.
- */
 export declare function detectProvenance(pid: number): Promise<SessionProvenance | undefined>;

package/dist/lib/session/provenance.js

@@ -1,43 +1,8 @@
-/**
- * Session provenance — where an active agent process actually lives.
- *
- * `detectHost()` in active.ts walks the ppid chain to name the *terminal app*
- * (iterm / code / tmux). That answers "what UI is above it" but not the three
- * things the Agent Feed needs to group and route:
- *
- *   1. Which machine    — os.hostname(), for the HOSTS sidebar.
- *   2. Local vs SSH     — is SSH_CONNECTION in the process env?
- *   3. Exact tmux pane  — TMUX_PANE ('%3'), the send-keys target.
- *
- * All three are inherited env vars, so we read them straight off the running
- * process (no cooperation from the agent needed): `/proc/<pid>/environ` on
- * Linux, `ps eww` on macOS. The read is best-effort — a process we can't stat
- * (gone, or owned by another uid) yields `undefined`, never a guess.
- *
- * `reply` is a read-only hint, not a send channel: it reports whether a rail
- * that can type back into this session exists today and, if so, the exact
- * address to type into. Two env-derived rails, in precedence order:
- *
- *   - tmux  — `$TMUX_PANE` (+ `$TMUX` socket): `tmux send-keys -t <pane>`. Works
- *             inside ANY host app (a tmux pane can live under iTerm/Ghostty/VS
- *             Code), so it wins whenever present.
- *   - iterm — `$ITERM_SESSION_ID` (`w<n>t<n>p<n>:<UUID>`): the exact iTerm2
- *             split, addressable by its session UUID via `tell session id …`
- *             (focus-safe, no `activate`). Used when there's no tmux above it.
- *
- * Both are inherited env vars, so the split the agent lives in is recovered with
- * zero cooperation from the agent. Inherited/ignored stdin with neither rail =>
- * null (not env-addressable — resolution may still find an IDE rail off disk,
- * see src/lib/terminal/resolve.ts). The feed uses `reply` to decide whether to
- * show a Send box; the resolver turns it into a concrete inject target (Gap 2,
- * src/lib/terminal/inject.ts).
- */
 import * as os from 'os';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { readFile } from 'fs/promises';
 const execFileAsync = promisify(execFile);
-/** Env vars that carry provenance. Kept small so the macOS `ps` scan stays cheap. */
 export const PROVENANCE_ENV_KEYS = [
     'SSH_CONNECTION',
     'SSH_TTY',
@@ -47,19 +12,12 @@ export const PROVENANCE_ENV_KEYS = [
     'STY',
     'ITERM_SESSION_ID',
 ];
-/**
- * Extract the iTerm2 session UUID from `$ITERM_SESSION_ID`, whose value is
- * `w<window>t<tab>p<pane>:<UUID>` — the `:`-suffix is exactly what iTerm2's
- * `id of session` returns, so it's the address for `tell session id …`. Returns
- * undefined for an empty/absent value; tolerates a bare value with no `:`.
- */
 export function parseItermSession(value) {
     if (!value)
         return undefined;
     const uuid = value.includes(':') ? value.slice(value.lastIndexOf(':') + 1) : value;
     return uuid.trim() || undefined;
 }
-/** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
 export function parseProcEnviron(buf) {
     const env = {};
     for (const pair of buf.split('\0')) {
@@ -72,20 +30,7 @@ export function parseProcEnviron(buf) {
     }
     return env;
 }
-/**
- * How many whitespace-separated tokens each key's value spans. macOS
- * `ps eww -o command=` space-joins the env after the command, so a value that
- * itself contains spaces (SSH_CONNECTION is four fields) can't be recovered by
- * boundary-guessing when the next token is an *unknown* var. Every provenance
- * key except SSH_CONNECTION is a single token, so we read exactly its arity.
- */
 const ENV_VALUE_TOKENS = { SSH_CONNECTION: 4 };
-/**
- * Pull known env vars out of a macOS `ps eww` command+env line. For each
- * `KEY=` match we consume the declared number of tokens (default 1), so
- * SSH_CONNECTION's internal spaces survive while a following unknown var
- * (e.g. `PWD=…`) is not swallowed into the previous value.
- */
 export function extractKnownEnv(text, keys) {
     const alt = keys.map((k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
     const boundary = new RegExp(`(?:^|\\s)(${alt})=`, 'g');
@@ -100,7 +45,6 @@ export function extractKnownEnv(text, keys) {
     }
     return env;
 }
-/** `<client_ip> <client_port> <server_ip> <server_port>` → structured origin. */
 export function parseSshConnection(value) {
     const parts = value.trim().split(/\s+/);
     if (parts.length < 4)
@@ -111,7 +55,6 @@ export function parseSshConnection(value) {
         return undefined;
     return { clientIp: parts[0], clientPort, serverIp: parts[2], serverPort };
 }
-/** Build a SessionProvenance from a raw env map + the local hostname. Pure. */
 export function deriveProvenance(env, hostname) {
     const ssh = env.SSH_CONNECTION ? parseSshConnection(env.SSH_CONNECTION) : undefined;
     let mux;
@@ -125,12 +68,6 @@ export function deriveProvenance(env, hostname) {
     else if (env.STY) {
         mux = { kind: 'screen', session: env.STY };
     }
-    // Env-addressable rails, in precedence order. A tmux pane wins because it can
-    // live inside any host app (`tmux send-keys -t <pane>` reaches it regardless of
-    // whether iTerm/Ghostty/VS Code is above it). Absent tmux, an iTerm2 split is
-    // addressable by its session UUID. Everything else (inherited stdin from
-    // `agents run`, ignored stdin from teams, a plain VS Code integrated terminal)
-    // is not env-addressable — the resolver may still find an IDE rail off disk.
     const itermSession = parseItermSession(env.ITERM_SESSION_ID);
     const reply = mux?.kind === 'tmux' && mux.pane
         ? { rail: 'tmux', target: mux.pane, socket: mux.socket }
@@ -146,7 +83,6 @@ export function deriveProvenance(env, hostname) {
         reply,
     };
 }
-/** Read a process's environment. Linux: /proc. macOS: `ps eww`. Best-effort. */
 async function readProcEnv(pid) {
     if (process.platform === 'linux') {
         try {
@@ -173,11 +109,6 @@ async function readProcEnv(pid) {
     }
     return undefined;
 }
-/**
- * Resolve provenance for a live pid. Returns undefined when the process env
- * can't be read (process gone, foreign uid, unsupported platform) — we never
- * fabricate a 'local' answer we can't back with the env.
- */
 export async function detectProvenance(pid) {
     if (!pid || pid < 1)
         return undefined;

package/dist/lib/session/recovery.d.ts

@@ -1,21 +1,16 @@
 import type { UnifiedAccount } from '../account-registry.js';
 import { type RotateCandidate } from '../accounting/rotate.js';
 import type { AgentId } from '../types.js';
-import type { SessionAgentId, SessionMeta } from './types.js';
-/** One capability boundary for every surface that advertises faithful Resume. */
+import type { SessionAgentId, SessionMeta } from '@phnx-labs/sessions-cli/reader';
 export declare function sessionAgentSupportsResume(agent: SessionAgentId): boolean;
-/** Injectable credentials can authenticate the existing native context. */
 export interface RecoveryAccount {
     providerAccount: string;
     label: string;
     email: string | null;
 }
 interface SessionRecoverySelection {
-    /** Installed binary only; account homes retain their own context label. */
     executableVersion?: string;
-    /** Explicit account selector resolved against the local candidate pool. */
     account?: string;
-    /** Effective model for readiness checks. */
     model?: string;
 }
 export type SessionRecoveryTarget = {
@@ -23,10 +18,8 @@ export type SessionRecoveryTarget = {
     agent: AgentId;
     version: string;
     cwd?: string;
-    /** The actual native context root used (a version home, or an account slot dir). */
     execHome?: string;
     configVersion?: string;
-    /** The exact account/version candidate recovery resolved to — never re-derive from `version` alone (PHNX-3940: several accounts can share one managed binary). */
     candidate: RotateCandidate;
     account?: RecoveryAccount;
     reason: string;
@@ -48,48 +41,16 @@ type NativeResumeInspection = {
 export declare class SessionRecoveryError extends Error {
     constructor(message: string);
 }
-/** Canonical origin-device label for every recovery consumer. */
 export declare function sessionOriginDevice(session: Pick<SessionMeta, 'machine'>, self?: string): string;
-/** The peer that must execute recovery, or undefined when this is the origin. */
 export declare function sessionRecoveryPeer(session: Pick<SessionMeta, 'machine'>, selfCheck?: (host: string) => boolean): string | undefined;
-/** Whether an explicit placement names the session's origin device. */
 export declare function sessionRecoveryDestinationMatches(session: Pick<SessionMeta, 'machine'>, requestedHost: string, self?: string): boolean;
-/** History filtering uses login identity, never an organization quota key. */
 export declare function sessionMatchesAccount(session: Pick<SessionMeta, 'agent' | 'filePath' | 'accountId'>, account: Pick<UnifiedAccount, 'id' | 'kind'> & {
     agent?: AgentId;
 }, home?: string): boolean;
-/**
- * Prove that the indexed transcript is reachable from the exact active
- * native context root that would receive native resume (a version home, or
- * an account slot dir). Retained trash/backup transcripts are intentionally
- * rejected here: they remain readable by `/continue`, but a new installation
- * or account slot must not native-resume an empty isolated home.
- */
 export declare function inspectNativeResumeSession(session: SessionMeta, versionHome: string): NativeResumeInspection;
-/** Keep the native conversation where possible; replay remains a separate choice. */
 export declare function resolveSessionRecoveryFromCandidates(session: SessionMeta, candidates: RotateCandidate[], supportsNative?: (agent: AgentId, version?: string) => boolean, nativeInspection?: NativeResumeInspection, options?: SessionRecoverySelection): SessionRecoveryTarget;
-/**
- * Whether recovery has conversation content to replay for this session: a
- * non-empty transcript file, or archived content in the index for a row this
- * device owns. A mirror digest or live registry entry is not conversation
- * content. The picker consults this before spending a terminal tab on a pick
- * that {@link assertRecoverableTranscript} would refuse one hop later.
- */
 export declare function sessionTranscriptReadable(session: SessionMeta): boolean;
-/** Refuse recovery for a session with nothing to replay (PHNX-4080). */
 export declare function assertRecoverableTranscript(session: SessionMeta): void;
-/**
- * Resolve recovery for a durable session, reading the live account pool.
- *
- * Uses {@link collectRunCandidatesForRun} (native version-home logins PLUS
- * durable provider accounts, RUSH-3182) rather than the native-only
- * {@link collectRunCandidates}, so an origin-account limit can rotate to a
- * healthy provider account and stay NATIVE (PHNX-3626). `collect` is injectable
- * for tests and for callers that must stay native-only.
- */
 export declare function resolveSessionRecovery(session: SessionMeta, collect?: (agent: AgentId) => Promise<RotateCandidate[]>, options?: SessionRecoverySelection): Promise<SessionRecoveryTarget>;
-/** Stable self-command used by focus, resume, and attach. The owning device runs
- * the recovery resolver above; callers must not native-resume another version's
- * isolated home themselves. */
 export declare function sessionRecoveryRunArgs(session: Pick<SessionMeta, 'id'>): string[];
 export {};