@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/session/mirror.js

@@ -1,38 +1,11 @@
-/**
- * Fleet distribution of lightweight per-session preview/metadata (PHNX-3792).
- *
- * On the interactive/personal device, a session that originated on another host
- * used to render as a bare `[host/<peer>]` row with no topic, and its preview
- * pane fetched the peer's digest LIVE over SSH per row — slow, and blank when
- * the peer is asleep. This module mirrors each box's own session digests into
- * its own `~/.agents/devices/<device>/daemon-state.json`, which the usage-sync
- * SSH exchange (`accounting/usage-sync.ts`, PHNX-4116) carries to every peer:
- * a headed box's tick sends its envelope and stores each peer's reply, so both
- * directions land with no operator step and nothing rides the user repo. The consuming device folds peer
- * digests into its local `sessions` index as mirror rows, so the picker/list/
- * focus read a LOCAL row instead of dialing the peer. No transcript is shipped —
- * only topic/label, the peer's daemon-generated title (PHNX-3797), a
- * first-user-message snippet, last-activity, agent+version, cwd, ticket, and
- * PR — and the mirror is bounded and pruned by age.
- *
- * Direction is deliberately the inverse of usage-sync: EVERY box publishes its
- * own local sessions (workers are exactly where the remote sessions the personal
- * box lacks previews for are created), and every box EXCEPT a marked worker folds
- * peers' digests in (the picker is an interactive surface). A worker skips the
- * consume so its DB is not written with rows it never renders.
- */
 import { selfConfiguredDeviceRole } from '../device-config.js';
 import { readFleetSharedDeviceStates, updateFleetSharedDeviceStateAsync, } from '../fleet-shared-state.js';
 import { getUserAgentsDir } from '../state.js';
 import { machineId, normalizeHost } from './sync/config.js';
 import { pruneMirrorSessions, queryLocalOriginSessionsForMirror, upsertMirrorSession, } from './db.js';
-/** Cap on sessions published per device — the payload stays what a picker shows. */
 const SESSION_MIRROR_MAX_ROWS = 200;
-/** First-user-message snippet ceiling; the full turn stays on the owning box. */
 const SESSION_MIRROR_SNIPPET_MAX = 280;
-/** Mirror rows older than this since their last sync are pruned (staleness/size ceiling). */
 export const SESSION_MIRROR_MAX_AGE_MS = 14 * 24 * 60 * 60_000;
-/** Caps for the timeline block on a published mirror row. */
 export const SESSION_MIRROR_MAX_STEPS = 8;
 export const SESSION_MIRROR_STEP_TEXT_MAX = 160;
 export const SESSION_MIRROR_REQUEST_MAX = 2_000;
@@ -40,7 +13,6 @@ export const SESSION_MIRROR_MAX_FILES = 8;
 function cap(value, max) {
     return value.length > max ? value.slice(0, max) : value;
 }
-/** Bound the tidied request: prose capped, chips capped, never re-derived. */
 function boundedRequest(request) {
     return {
         ...request,
@@ -51,7 +23,6 @@ function boundedRequest(request) {
             .map((a) => ({ kind: a.kind, name: cap(a.name, 120) })),
     };
 }
-/** Bound the step list. Counters are kept exact — only text is truncated. */
 function boundedTimeline(timeline) {
     const steps = timeline.steps.slice(-SESSION_MIRROR_MAX_STEPS).map((step) => ({
         ...step,
@@ -61,7 +32,6 @@ function boundedTimeline(timeline) {
     }));
     return { ...timeline, steps, ...(timeline.reason ? { reason: cap(timeline.reason, 200) } : {}) };
 }
-/** Bound the file rows; `total` still reports the real count. */
 function boundedFiles(files) {
     return {
         ...files,
@@ -77,7 +47,6 @@ function snippet(value, max = SESSION_MIRROR_SNIPPET_MAX) {
         return undefined;
     return trimmed.length > max ? `${trimmed.slice(0, max - 1)}…` : trimmed;
 }
-/** Publish this device's most-recent local sessions into its owned shared-state file. */
 export async function publishSessionMirrorToSharedStore(options = {}) {
     const result = {
         published: false, changed: false, count: 0, skipped: null, error: null, path: null,
@@ -102,12 +71,7 @@ export async function publishSessionMirrorToSharedStore(options = {}) {
         timestamp: s.timestamp,
         ...(s.ticketId ? { ticketId: s.ticketId } : {}),
         ...(s.prUrl ? { prUrl: s.prUrl } : {}),
-        // Ride the daemon-computed summary (PHNX-3939) so a peer renders the goal /
-        // checkpoints / checklist inline — still no transcript, keeping the mirror light.
         ...(s.summary?.goal ? { goal: snippet(s.summary.goal, 400) } : {}),
-        // Bound on publish exactly as toMirrorSummary bounds on consume (50/100 items,
-        // 400-char text, 40-char `at`) so this box's own model output can't ride raw
-        // into the git-synced fleet state file — matching the snippet() cap on goal above.
         ...(s.summary?.checkpoints
             ? {
                 checkpoints: s.summary.checkpoints
@@ -123,9 +87,6 @@ export async function publishSessionMirrorToSharedStore(options = {}) {
             }
             : {}),
         ...(s.summary?.summaryState ? { summaryState: s.summary.summaryState } : {}),
-        // Same bound-on-publish discipline as the summary above: the fleet state file
-        // is git-synced, so the request text, the step list, and the file rows are
-        // capped here rather than shipped raw (PHNX-3939).
         ...(s.timeline?.request ? { request: boundedRequest(s.timeline.request) } : {}),
         ...(s.timeline?.timeline ? { timeline: boundedTimeline(s.timeline.timeline) } : {}),
         ...(s.timeline?.files ? { files: boundedFiles(s.timeline.files) } : {}),
@@ -146,13 +107,6 @@ export async function publishSessionMirrorToSharedStore(options = {}) {
 function isString(v) {
     return typeof v === 'string' && v.length > 0;
 }
-/**
- * Validate one untrusted peer-supplied row into a DB upsert (or null when it is
- * missing a load-bearing field). Terminal-escape scrubbing is NOT done here —
- * the render path (`sanitizeMeta` in sessions-picker) scrubs every meta string
- * before it reaches a TTY, exactly as it does for live fan-out rows — this only
- * enforces shape and bounds so a malformed/hostile peer can't poison the index.
- */
 function toUpsert(raw) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return null;
@@ -183,13 +137,6 @@ function toUpsert(raw) {
         timeline: toMirrorTimeline(r),
     };
 }
-/**
- * Validate an untrusted peer's published request/timeline/files into the bounded
- * projection the local cache stores (PHNX-3939). Bounds mirror the publish side,
- * so a hostile or oversized peer cannot bloat this box's cache. Only a row that
- * carries a well-formed timeline is kept; a malformed one is dropped whole
- * rather than partially trusted.
- */
 function toMirrorTimeline(r) {
     const timeline = toMirrorTimelineBlock(r.timeline);
     if (!timeline)
@@ -206,11 +153,9 @@ function isRecord(v) {
 function count(v) {
     return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
 }
-/** The verb keys a peer's `mix` may carry — anything else is dropped, not trusted. */
 const MIRROR_VERB_CLASSES = [
     'read', 'edit', 'run', 'git', 'test', 'browser', 'agent', 'other',
 ];
-/** A peer's per-verb breakdown, whitelisted by key and clamped by value. */
 function toMirrorMix(raw) {
     if (!isRecord(raw))
         return undefined;
@@ -242,10 +187,6 @@ function toMirrorTimelineBlock(raw) {
         failed: count(step.failed),
         blocked: count(step.blocked),
         ...(isString(step.now) ? { now: step.now.slice(0, SESSION_MIRROR_STEP_TEXT_MAX) } : {}),
-        // `mix` and `live` are what the sidebar renders a step WITH ("6 run ·
-        // 2 blocked", the amber now-line). Dropping them here made a remote row
-        // disagree with the local one about what a live step even is, while `now`
-        // survived — so they ride through, whitelisted like every other field.
         ...(step.live === true ? { live: true } : {}),
         ...(() => {
             const mix = toMirrorMix(step.mix);
@@ -305,16 +246,9 @@ function toMirrorFiles(raw) {
         return undefined;
     return { changes, total: count(raw.total) || changes.length, source: raw.source === 'harness' ? 'harness' : 'tools' };
 }
-/** One published summary state, validated back into the union or undefined. */
 function toSummaryState(v) {
     return v === 'pending' || v === 'ready' || v === 'skipped' ? v : undefined;
 }
-/**
- * Validate an untrusted peer's published summary fields into a bounded
- * {@link SessionSummaryEntry} (PHNX-3939), or undefined when it carries none.
- * Bounds mirror the publish side so a hostile/oversized peer can't bloat the
- * local cache. Only a row with a resolvable `summaryState` is kept.
- */
 function toMirrorSummary(r) {
     const summaryState = toSummaryState(r.summaryState);
     if (!summaryState)
@@ -341,22 +275,11 @@ function toMirrorSummary(r) {
         ...(summaryChecklist && summaryChecklist.length ? { summaryChecklist } : {}),
     };
 }
-/**
- * Fold peers' published session digests into this box's local `sessions` index
- * as mirror rows, then prune stale ones. Reads only the local user-repo checkout
- * (the daemon's Git transport already delivered peers' files) — no network. A
- * marked worker skips: the mirror feeds an interactive picker it never renders.
- */
 export function consumeSessionMirrorFromSharedStore(options = {}) {
     const result = { sources: [], merged: 0, pruned: 0, skipped: null, errors: [] };
     const role = options.role ?? selfConfiguredDeviceRole();
     const now = options.now ?? Date.now();
     if (role === 'worker') {
-        // A worker never renders the picker, so it does not consume peers' digests.
-        // But if this box was previously a non-worker it may still hold mirror rows,
-        // which it will never refresh or render — prune them all now (cutoff = now
-        // drops every row synced before this tick) rather than leave a demoted box's
-        // index permanently bloated with stale peer rows (PHNX-3792).
         result.pruned = pruneMirrorSessions(now);
         result.skipped = 'this device is a worker; the session mirror feeds the interactive picker';
         return result;

package/dist/lib/session/origin-machine.js

@@ -1,4 +1 @@
-// Moved to ../origin-machine.ts (move 1 of the core-module refactor — see
-// .agents/artifacts/2026-08-20/plan-*.md). Kept as a re-export shim so
-// existing importers don't break.
 export * from '../origin-machine.js';

package/dist/lib/session/pid-registry.d.ts

@@ -1,55 +1,15 @@
 export interface PidSessionEntry {
     pid: number;
     agent: string;
-    /**
-     * Custom harness / profile name when this pid was launched via
-     * `agents run <profile>` (e.g. `deepseek`). `agent` stays the HOST
-     * CLI (`claude`) so process matching and transcript discovery keep
-     * working. `sessions --active` displays this when set (PHNX-2935).
-     */
     harness?: string;
-    /** The launch session id. Present for agents launched with a known id (Claude). */
     sessionId?: string;
     cwd?: string;
-    /**
-     * Resolved actor id (`resolveActor().id`) stamped at spawn — who initiated this
-     * run. A tailnet login/email for a resolved human, or `UNRESOLVED@<host>` when
-     * it can't be determined. Read back by the active-sessions path to surface an
-     * `owner` per session (RUSH-2018), so a co-located fleet shows who launched what.
-     */
     actor?: string;
-    /**
-     * The actor's kind (`resolveActor().kind`): `'human'` for a person-initiated
-     * run, `'agent'` for one an agent spawned. Pairs with {@link actor} the same way
-     * `AGENTS_ACTOR` / `AGENTS_ACTOR_KIND` do on the exec env.
-     */
     initiatedBy?: 'human' | 'agent';
-    /**
-     * The launch id minted by `ag run` and exported to the child as
-     * `AGENT_LAUNCH_ID`. The agent's SessionStart hook records the SAME id in its
-     * own state file (`terminals/sessions/<pid>.json`, `launch_id`), so the two
-     * records reconcile by this key even when the hook runs under a DIFFERENT pid
-     * (tmux pane leaf, cmd.exe wrapper) — see resolveHookSessionId in
-     * session/hook-sessions.ts. This
-     * is how a non-Claude launch (whose id we don't know at spawn) gets an exact
-     * session id at listing time instead of the newest-jsonl heuristic.
-     */
     launchId?: string;
-    /**
-     * `AGENT_TERMINAL_ID` when the launch inherited one (a Factory VS Code tab).
-     * A secondary join key to the hook's `terminal_id`, for agents the extension
-     * spawned. Best-effort — undefined outside the extension.
-     */
     terminalId?: string;
-    /**
-     * `$TMUX_PANE` at launch — stored for diagnostics and possible future
-     * disambiguation. NOT currently consulted on read: the listing path keys
-     * purely on pid (stale entries are pruned when the pid dies), so this is
-     * metadata, not an anti-collision key.
-     */
     tmuxPane?: string;
     startedAtMs: number;
-    /** Kernel provenance, captured by the writer; absent on legacy records. */
     processIdentity?: {
         bootId?: string;
         pidNamespace?: string;
@@ -58,54 +18,14 @@ export interface PidSessionEntry {
         startTime?: string;
     };
 }
-/** ps lstart fields can differ in padding or date formatting between invocations. */
 export declare function processStartTimesMatch(recorded: string | undefined, observed: string | undefined): boolean | undefined;
-/** Read-only identity proof for exact joins. Unknown is never a positive match. */
 export declare function pidSessionEntryMatchesLiveProcess(entry: PidSessionEntry, startTime?: string): boolean | undefined;
 export declare function isSessionIdShape(value: string): boolean;
 export declare function extractSessionIdArg(args: string[]): string | undefined;
-/**
- * Read a live process's original argv (best-effort).
- *
- * Linux: NUL-separated `/proc/<pid>/cmdline`. Darwin: `ps -ww -o args=` then
- * whitespace-split (good enough for Claude's `--session-id <uuid>` tokens;
- * not a full shell-quote parser). Other platforms: undefined.
- *
- * RUSH-2384: the by-pid registry is often empty mid-run (launch pid was a
- * wrapper that exited, prune wiped it, or the agent was not launched via
- * `agents run`). The live process still carries `--session-id` on its argv —
- * the same signal the incident used to prove the session was alive — so the
- * active scan and `agents message` can recover identity without the registry.
- */
 export declare function readProcessArgv(pid: number): string[] | undefined;
-/**
- * Exact session id a live agent process was launched with, read from its
- * current argv. Undefined when the process is gone, the platform can't expose
- * argv, or the vector carries no `--session-id`.
- */
 export declare function sessionIdFromLivePid(pid: number): string | undefined;
-/** Record a launched agent process. Never throws — the registry is an optimization. */
 export declare function writePidSessionEntry(entry: PidSessionEntry): void;
-/** Look up a live pid's recorded session. Returns undefined if absent/corrupt. */
 export declare function readPidSessionEntry(pid: number): PidSessionEntry | undefined;
-/** Live consumers require identity proof; raw history is not a PID binding.
- * A shared process snapshot may supply lstart to avoid a per-pid ps probe. */
 export declare function readLivePidSessionEntry(pid: number, startTime?: string): PidSessionEntry | undefined;
-/**
- * Every recorded launch, one entry per live-or-dead pid. Used to index launches
- * by their `tmuxPane` so the authoritative tmux source can attribute a pane it did
- * NOT wrap (an agent bare-spawned into an existing pane) to its exact launch —
- * the caller filters to live pids. Best-effort: unreadable/corrupt files are
- * skipped, a missing dir yields `[]`.
- */
 export declare function listPidSessionEntries(): PidSessionEntry[];
-/**
- * Remove entries whose pid is no longer alive. Best-effort housekeeping.
- *
- * Linux deletion requires the writer's boot and PID namespace to match our own
- * trustworthy proc view. ESRCH in another namespace says nothing about the
- * recorded process. Legacy/corrupt/unreadable ownership is unknown, never dead.
- * Kernel start ticks reject PID reuse without wall-clock heuristics. Other
- * platforms retain the caller's start-time check after checking kernel liveness.
- */
 export declare function prunePidSessionRegistry(isAlive?: (pid: number, startedAtMs?: number) => boolean | undefined): void;

package/dist/lib/session/pid-registry.js

@@ -1,21 +1,3 @@
-/**
- * Per-PID session registry — the headless equivalent of the swarmify VS Code
- * extension's `live-terminals.json`.
- *
- * On a machine with no terminal extension (a bare SSH/tmux host), the only way
- * `ag sessions --active` can attribute a `ps`-discovered agent process to a
- * session is to guess "newest .jsonl in the cwd" — which collapses N agents
- * sharing one repo onto a single session (all rows show the same topic/id).
- *
- * `ag run` closes that gap by recording, at spawn time, one file per launched
- * agent process keyed by its OS pid: the exact session id it was launched with
- * (Claude is started with `--session-id <uuid>`, so the launcher knows it),
- * plus agent/cwd/tmux pane. The active-sessions headless path reads it back for
- * an exact pid -> session match instead of a heuristic.
- *
- * Best-effort throughout: a failed write or a corrupt file degrades to the old
- * heuristic, never throws into the launch or the listing path.
- */
 import fs from 'fs';
 import path from 'path';
 import { execFileSync } from 'child_process';
@@ -25,7 +7,6 @@ import { atomicWriteFileSync, withFileLock } from '../fs-atomic.js';
 function linuxStartTicks(pid) {
     try {
         const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
-        // comm (field 2) may contain spaces or parentheses; starttime is field 22.
         const value = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
         return value && /^\d+$/.test(value) ? value : undefined;
     }
@@ -58,13 +39,11 @@ function darwinStartTime(pid) {
 function processStartTimeMs(value) {
     return typeof value === 'string' ? Date.parse(value.trim().replace(/\s+/g, ' ')) : NaN;
 }
-/** ps lstart fields can differ in padding or date formatting between invocations. */
 export function processStartTimesMatch(recorded, observed) {
     const recordedMs = processStartTimeMs(recorded);
     const observedMs = processStartTimeMs(observed);
     return Number.isFinite(recordedMs) && Number.isFinite(observedMs) ? recordedMs === observedMs : undefined;
 }
-/** Read-only identity proof for exact joins. Unknown is never a positive match. */
 export function pidSessionEntryMatchesLiveProcess(entry, startTime) {
     if (!Number.isInteger(entry.pid) || entry.pid < 1)
         return undefined;
@@ -91,13 +70,6 @@ export function pidSessionEntryMatchesLiveProcess(entry, startTime) {
         return undefined;
     return start === recordedStart;
 }
-/**
- * Pull an explicit `--session-id <uuid>` (or `--session-id=<uuid>`) out of a
- * raw agent arg vector. The transparent shim forwards args untouched, but when
- * a launcher (Claude Code background jobs, IDE harnesses) already names the
- * session, recording it gives the same exact pid -> session mapping `ag run`
- * gets from generating the id itself.
- */
 const SESSION_ID_VALUE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export function isSessionIdShape(value) {
     return SESSION_ID_VALUE_RE.test(value);
@@ -118,19 +90,6 @@ export function extractSessionIdArg(args) {
     }
     return undefined;
 }
-/**
- * Read a live process's original argv (best-effort).
- *
- * Linux: NUL-separated `/proc/<pid>/cmdline`. Darwin: `ps -ww -o args=` then
- * whitespace-split (good enough for Claude's `--session-id <uuid>` tokens;
- * not a full shell-quote parser). Other platforms: undefined.
- *
- * RUSH-2384: the by-pid registry is often empty mid-run (launch pid was a
- * wrapper that exited, prune wiped it, or the agent was not launched via
- * `agents run`). The live process still carries `--session-id` on its argv —
- * the same signal the incident used to prove the session was alive — so the
- * active scan and `agents message` can recover identity without the registry.
- */
 export function readProcessArgv(pid) {
     if (!pid || pid < 1)
         return undefined;
@@ -160,11 +119,6 @@ export function readProcessArgv(pid) {
     }
     return undefined;
 }
-/**
- * Exact session id a live agent process was launched with, read from its
- * current argv. Undefined when the process is gone, the platform can't expose
- * argv, or the vector carries no `--session-id`.
- */
 export function sessionIdFromLivePid(pid) {
     const argv = readProcessArgv(pid);
     if (!argv)
@@ -177,8 +131,6 @@ function pidRegistryDir() {
 function entryPath(pid) {
     return path.join(pidRegistryDir(), `${pid}.json`);
 }
-// The deployed SessionStart hook reconstructs by-pid entries from an allowlist.
-// Keep launcher ownership separately, bound to the immutable launch coordinates.
 function ownershipPath(pid) {
     return path.join(getTerminalsDir(), 'by-pid-ownership', `${pid}.json`);
 }
@@ -195,10 +147,9 @@ function restoreOwnership(entry) {
             return { ...entry, processIdentity: owner.processIdentity };
         }
     }
-    catch { /* legacy launch */ }
+    catch { }
     return entry;
 }
-/** Record a launched agent process. Never throws — the registry is an optimization. */
 export function writePidSessionEntry(entry) {
     if (!Number.isInteger(entry.pid) || entry.pid < 1)
         return;
@@ -211,18 +162,14 @@ export function writePidSessionEntry(entry) {
             : process.platform === 'darwin' ? { startTime: darwinStartTime(entry.pid) } : undefined;
         const file = entryPath(entry.pid);
         withFileLock(file, () => {
-            // The host writer owns numeric PID slots. Old-boot and legacy records
-            // must not reserve a recycled slot; restricted namespaces never get here.
             const owned = { ...entry, processIdentity };
             persistOwnership(owned);
             atomicWriteFileSync(file, JSON.stringify(owned), 'utf8');
         }, { realpath: false, acquireTimeoutMs: 0 });
     }
     catch {
-        /* degrade to the newest-jsonl heuristic */
     }
 }
-/** Look up a live pid's recorded session. Returns undefined if absent/corrupt. */
 export function readPidSessionEntry(pid) {
     let raw;
     try {
@@ -238,12 +185,9 @@ export function readPidSessionEntry(pid) {
         }
     }
     catch {
-        /* unparseable */
     }
     return undefined;
 }
-/** Live consumers require identity proof; raw history is not a PID binding.
- * A shared process snapshot may supply lstart to avoid a per-pid ps probe. */
 export function readLivePidSessionEntry(pid, startTime) {
     const entry = readPidSessionEntry(pid);
     if (!entry || !hostProcessView())
@@ -251,9 +195,6 @@ export function readLivePidSessionEntry(pid, startTime) {
     if (process.platform === 'win32')
         return pidExists(pid) === true ? entry : undefined;
     if (!entry.processIdentity && pidExists(pid) === true) {
-        // Upgrade a native legacy launch only after the home namespace is proven,
-        // and the actual process start excludes a recycled PID. Hook timestamps may
-        // be later than process start, but cannot predate this process incarnation.
         const start = startTime ?? darwinStartTime(pid);
         const startMs = processStartTimeMs(start);
         if (Number.isFinite(startMs) && entry.startedAtMs >= startMs - 1000 && entry.startedAtMs <= Date.now()) {
@@ -264,18 +205,11 @@ export function readLivePidSessionEntry(pid, startTime) {
             try {
                 persistOwnership(entry);
             }
-            catch { /* read remains useful */ }
+            catch { }
         }
     }
     return pidSessionEntryMatchesLiveProcess(entry, startTime) === true ? entry : undefined;
 }
-/**
- * Every recorded launch, one entry per live-or-dead pid. Used to index launches
- * by their `tmuxPane` so the authoritative tmux source can attribute a pane it did
- * NOT wrap (an agent bare-spawned into an existing pane) to its exact launch —
- * the caller filters to live pids. Best-effort: unreadable/corrupt files are
- * skipped, a missing dir yields `[]`.
- */
 export function listPidSessionEntries() {
     let files;
     try {
@@ -293,20 +227,10 @@ export function listPidSessionEntries() {
             }
         }
         catch {
-            /* raced with a writer/pruner, or corrupt — skip */
         }
     }
     return out;
 }
-/**
- * Remove entries whose pid is no longer alive. Best-effort housekeeping.
- *
- * Linux deletion requires the writer's boot and PID namespace to match our own
- * trustworthy proc view. ESRCH in another namespace says nothing about the
- * recorded process. Legacy/corrupt/unreadable ownership is unknown, never dead.
- * Kernel start ticks reject PID reuse without wall-clock heuristics. Other
- * platforms retain the caller's start-time check after checking kernel liveness.
- */
 export function prunePidSessionRegistry(isAlive) {
     let files;
     try {
@@ -351,15 +275,12 @@ export function prunePidSessionRegistry(isAlive) {
         }
         try {
             const file = path.join(pidRegistryDir(), f);
-            // Share the writer's lock so comparison and deletion cannot remove a
-            // successor published after the liveness check.
             withFileLock(file, () => {
                 if (fs.readFileSync(file, 'utf8') === raw)
                     fs.unlinkSync(file);
             }, { realpath: false, acquireTimeoutMs: 0 });
         }
         catch {
-            /* raced with another writer/pruner */
         }
     }
 }

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

@@ -1,17 +1,11 @@
 export type PresenceStatus = 'connected' | 'disconnected';
 export type PresenceLocation = 'local' | 'ssh';
-/** A session as OBSERVED by one tick's active scan — the pure reconcile input. */
 export interface ObservedSession {
     sessionId: string;
     agent: string;
-    /** `local` when the session runs on this box, `ssh` when it's on a peer. */
     location: PresenceLocation;
-    /** The device/host the session runs on (this box's hostname, or the peer). */
     device: string;
-    /** Transport the session's provenance reports (`local` | `ssh` | ...). */
     transport: string;
-    /** True for an interactive (terminal/tmux) session — a drop is reconnect-worthy;
-     *  false for a headless remote continuation, where a drop means keep-alive. */
     interactive: boolean;
 }
 export interface PresenceRecord {
@@ -21,11 +15,9 @@ export interface PresenceRecord {
     device: string;
     transport: string;
     interactive: boolean;
-    /** ms of the last tick this session was observed active. */
     lastSeenMs: number;
     status: PresenceStatus;
 }
-/** What the tick should do about a session that just flipped `disconnected`. */
 export type PresenceAction = 'reconnect-nudge' | 'keep-alive' | 'none';
 export interface PresenceTransition {
     record: PresenceRecord;
@@ -33,52 +25,21 @@ export interface PresenceTransition {
     to: PresenceStatus;
     action: PresenceAction;
 }
-/** 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 declare const PRESENCE_TTL_MS: number;
-/** `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 declare function presenceFilePath(dir?: string): string;
 export declare function loadPresence(dir?: string): Record<string, PresenceRecord>;
 export declare function savePresence(map: Record<string, PresenceRecord>, dir?: string): void;
-/** The subset of an `ActiveSession` the presence adapter reads (structural, so
- *  this module doesn't import the heavy active-session graph). */
 interface ActiveSessionLike {
     sessionId?: string;
     kind: string;
-    /** 'terminal' (interactive) | 'headless' | 'teams' | 'cloud' | ... */
     context: string;
-    /** Set for a peer session by the fleet fan-out (`gatherRemoteActive`). */
     machine?: string;
     provenance?: {
         transport?: string;
     };
 }
-/**
- * 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 declare function observedFromActive(sessions: ActiveSessionLike[], selfHost?: string): ObservedSession[];
-/** 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 declare function actionFor(record: PresenceRecord): PresenceAction;
-/**
- * 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 declare function reconcilePresence(prev: Record<string, PresenceRecord>, observed: ObservedSession[], nowMs: number): {
     next: Record<string, PresenceRecord>;
     transitions: PresenceTransition[];