@phnx-labs/agents-cli 1.20.89 → 1.20.90

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

@@ -0,0 +1,39 @@
+/**
+ * Favorited (starred) sessions — the durable "keep this one handy" mark a human
+ * puts on a session, deliberately kept OUT of the session index.
+ *
+ * `sessions.db` is a rebuildable CACHE: a reindex or a schema bump throws its
+ * rows away and re-derives them from the transcripts on disk. A favorite is not
+ * derivable from a transcript — it is a human's choice — so a column there would
+ * be silently lost on the next rebuild. It lives in `~/.agents/.history/` instead,
+ * next to the actor sidecars, which is never pruned.
+ *
+ * One flat set of session ids. The id is the transcript's own uuid, so it is
+ * stable and machine-independent — but the file is NOT synced today: session sync
+ * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Favorites
+ * are therefore per-machine; carrying them across the fleet would mean adding
+ * them to the sync manifest, which this does not do.
+ *
+ * Reads are memoized against the file's mtime — the picker asks `isFavorite` once
+ * per rendered row, and re-reading a JSON file per row on every keystroke is the
+ * kind of cost that makes a TUI feel broken.
+ */
+export declare function favoritesFilePath(): string;
+/** Drop the memoized read. Tests that write the file directly need this; nothing
+ *  in the CLI does, because every mutation here refreshes the cache itself. */
+export declare function clearFavoritesCache(): void;
+/**
+ * Every favorited session id. Empty (never throws) when the file is absent,
+ * unreadable, or malformed — a corrupt favorites file must not take down
+ * `agents sessions`.
+ */
+export declare function listFavorites(): Set<string>;
+export declare function isFavorite(sessionId: string | undefined): boolean;
+/**
+ * Set (or clear) the favorite mark on a session. Returns the resulting state, so
+ * a caller can report it without a second read. A no-op write is skipped, which
+ * keeps the file's mtime — and every other process's memoized read — untouched.
+ */
+export declare function setFavorite(sessionId: string, on: boolean): boolean;
+/** Flip the mark; returns the new state (`true` = now favorited). */
+export declare function toggleFavorite(sessionId: string): boolean;

package/dist/lib/session/favorites.js

@@ -0,0 +1,101 @@
+/**
+ * Favorited (starred) sessions — the durable "keep this one handy" mark a human
+ * puts on a session, deliberately kept OUT of the session index.
+ *
+ * `sessions.db` is a rebuildable CACHE: a reindex or a schema bump throws its
+ * rows away and re-derives them from the transcripts on disk. A favorite is not
+ * derivable from a transcript — it is a human's choice — so a column there would
+ * be silently lost on the next rebuild. It lives in `~/.agents/.history/` instead,
+ * next to the actor sidecars, which is never pruned.
+ *
+ * One flat set of session ids. The id is the transcript's own uuid, so it is
+ * stable and machine-independent — but the file is NOT synced today: session sync
+ * carries `.history/backups/` (`lib/session/sync/agents.ts`), not this. Favorites
+ * are therefore per-machine; carrying them across the fleet would mean adding
+ * them to the sync manifest, which this does not do.
+ *
+ * Reads are memoized against the file's mtime — the picker asks `isFavorite` once
+ * per rendered row, and re-reading a JSON file per row on every keystroke is the
+ * kind of cost that makes a TUI feel broken.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getHistoryDir } from '../state.js';
+export function favoritesFilePath() {
+    return path.join(getHistoryDir(), 'favorites.json');
+}
+/** Memoized parse, invalidated by the file's mtime+size (another process — or
+ *  another machine's sync — can rewrite it under us). */
+let cache = null;
+function statKey(file) {
+    try {
+        const st = fs.statSync(file);
+        return `${st.mtimeMs}:${st.size}`;
+    }
+    catch {
+        return 'absent';
+    }
+}
+/** Drop the memoized read. Tests that write the file directly need this; nothing
+ *  in the CLI does, because every mutation here refreshes the cache itself. */
+export function clearFavoritesCache() {
+    cache = null;
+}
+/**
+ * Every favorited session id. Empty (never throws) when the file is absent,
+ * unreadable, or malformed — a corrupt favorites file must not take down
+ * `agents sessions`.
+ */
+export function listFavorites() {
+    const file = favoritesFilePath();
+    const key = statKey(file);
+    if (cache && cache.key === key)
+        return cache.ids;
+    let ids = new Set();
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (Array.isArray(parsed?.sessionIds)) {
+            ids = new Set(parsed.sessionIds.filter((id) => typeof id === 'string' && id.length > 0));
+        }
+    }
+    catch {
+        // absent / unreadable / malformed — an empty set is the honest answer
+    }
+    cache = { key, ids };
+    return ids;
+}
+export function isFavorite(sessionId) {
+    if (!sessionId)
+        return false;
+    return listFavorites().has(sessionId);
+}
+/** Atomic write (tmp + rename) so a concurrent reader never sees a half file. */
+function writeFavorites(ids) {
+    const file = favoritesFilePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const body = { version: 1, sessionIds: [...ids].sort() };
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(body, null, 2) + '\n');
+    fs.renameSync(tmp, file);
+    cache = { key: statKey(file), ids };
+}
+/**
+ * Set (or clear) the favorite mark on a session. Returns the resulting state, so
+ * a caller can report it without a second read. A no-op write is skipped, which
+ * keeps the file's mtime — and every other process's memoized read — untouched.
+ */
+export function setFavorite(sessionId, on) {
+    const ids = new Set(listFavorites());
+    if (ids.has(sessionId) === on)
+        return on;
+    if (on)
+        ids.add(sessionId);
+    else
+        ids.delete(sessionId);
+    writeFavorites(ids);
+    return on;
+}
+/** Flip the mark; returns the new state (`true` = now favorited). */
+export function toggleFavorite(sessionId) {
+    return setFavorite(sessionId, !isFavorite(sessionId));
+}

package/dist/lib/session/host-link.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Host link — whether anything is still on the other end of a live session.
+ *
+ * Every liveness signal the scan already has answers "is the AGENT process
+ * alive". None of them answer "is anyone still driving it", and those come apart
+ * in exactly the two ways a user notices:
+ *
+ *   - **The host program died and took the agent with it.** VS Code / the editor
+ *     window crashes or the SSH connection drops, so the agent process dies with
+ *     its parent, but the window never got to run its teardown — its slice of
+ *     `live-terminals.json` is left behind, stale, still naming a dead pid. Today
+ *     that entry is filtered out at read time, so the session simply VANISHES
+ *     from `--active` instead of reporting that it fell over. That is `host-gone`.
+ *
+ *   - **The host program died and the agent survived it.** The agent was hosted
+ *     in tmux (or otherwise reparented), so it keeps running with zero clients
+ *     attached: still burning tokens, or sitting on a question nobody will ever
+ *     answer, with no window anywhere showing it. That is `no-client`.
+ *
+ * Both are DERIVED, never asserted — from the agent pid, the owning window's
+ * keepalive, and tmux's own attached-client count. A deliberately backgrounded
+ * session (`agents sessions detach`) is excluded by construction: it is supposed
+ * to have no client, so calling it orphaned would be a false alarm on the one
+ * case the user asked for.
+ */
+/** How a session is connected to the client that should be driving it. */
+export type HostLink = 
+/** A client is attached, or nothing indicates otherwise. The normal case. */
+'connected'
+/** Alive, but nothing is viewing it — the host window is gone and the agent outlived it. */
+ | 'no-client'
+/** The host window is gone AND the agent process died with it — an unclean exit. */
+ | 'host-gone';
+/**
+ * How long an IDE window's registry slice may go without a refresh before we
+ * treat that window as gone. The Factory extension force-republishes its slice
+ * every 4 minutes (`KEEPALIVE_FORCE_MS` in `apps/factory/src/vscode/foreman.registry.ts`)
+ * and on every terminal open/close, so a slice this old means the window is no
+ * longer running — it is not merely quiet. Deliberately the same 10 minutes the
+ * extension itself uses to garbage-collect a peer window's slice, so the CLI and
+ * the extension agree on when a window is dead.
+ */
+export declare const HOST_HEARTBEAT_STALE_MS: number;
+export interface HostLinkInput {
+    /** The agent process is still alive (already pid-reuse-checked by the caller). */
+    pidAlive: boolean;
+    /**
+     * When the owning IDE window last refreshed its slice of the live-terminals
+     * registry. Absent for a session no IDE window owns (a bare terminal, a team
+     * spawn, a cloud task) — those have no window whose death we could observe.
+     */
+    windowHeartbeatMs?: number;
+    /**
+     * Clients attached to this session's tmux session (`#{session_attached}`).
+     * Absent when the session is not tmux-hosted, which is NOT the same as zero:
+     * zero is a positive "nobody is looking", absent is "we cannot tell".
+     */
+    tmuxClients?: number;
+    /** The session was deliberately backgrounded — `presence` is `background`/`parked`. */
+    deliberatelyDetached?: boolean;
+    nowMs?: number;
+}
+/**
+ * Classify a live row's host link. Pure — every signal is passed in, so the
+ * whole decision table is unit-testable without a process table, a tmux server,
+ * or a running editor.
+ */
+export declare function classifyHostLink(input: HostLinkInput): HostLink;

package/dist/lib/session/host-link.js

@@ -0,0 +1,64 @@
+/**
+ * Host link — whether anything is still on the other end of a live session.
+ *
+ * Every liveness signal the scan already has answers "is the AGENT process
+ * alive". None of them answer "is anyone still driving it", and those come apart
+ * in exactly the two ways a user notices:
+ *
+ *   - **The host program died and took the agent with it.** VS Code / the editor
+ *     window crashes or the SSH connection drops, so the agent process dies with
+ *     its parent, but the window never got to run its teardown — its slice of
+ *     `live-terminals.json` is left behind, stale, still naming a dead pid. Today
+ *     that entry is filtered out at read time, so the session simply VANISHES
+ *     from `--active` instead of reporting that it fell over. That is `host-gone`.
+ *
+ *   - **The host program died and the agent survived it.** The agent was hosted
+ *     in tmux (or otherwise reparented), so it keeps running with zero clients
+ *     attached: still burning tokens, or sitting on a question nobody will ever
+ *     answer, with no window anywhere showing it. That is `no-client`.
+ *
+ * Both are DERIVED, never asserted — from the agent pid, the owning window's
+ * keepalive, and tmux's own attached-client count. A deliberately backgrounded
+ * session (`agents sessions detach`) is excluded by construction: it is supposed
+ * to have no client, so calling it orphaned would be a false alarm on the one
+ * case the user asked for.
+ */
+/**
+ * How long an IDE window's registry slice may go without a refresh before we
+ * treat that window as gone. The Factory extension force-republishes its slice
+ * every 4 minutes (`KEEPALIVE_FORCE_MS` in `apps/factory/src/vscode/foreman.registry.ts`)
+ * and on every terminal open/close, so a slice this old means the window is no
+ * longer running — it is not merely quiet. Deliberately the same 10 minutes the
+ * extension itself uses to garbage-collect a peer window's slice, so the CLI and
+ * the extension agree on when a window is dead.
+ */
+export const HOST_HEARTBEAT_STALE_MS = 10 * 60_000;
+/**
+ * Classify a live row's host link. Pure — every signal is passed in, so the
+ * whole decision table is unit-testable without a process table, a tmux server,
+ * or a running editor.
+ */
+export function classifyHostLink(input) {
+    const now = input.nowMs ?? Date.now();
+    // A session detached on purpose has no client BY DESIGN. It is the one case
+    // that looks identical to an orphan from the outside, so it is excluded first —
+    // otherwise every `agents sessions detach` would raise a false alarm.
+    if (input.deliberatelyDetached)
+        return 'connected';
+    const windowGone = input.windowHeartbeatMs !== undefined && now - input.windowHeartbeatMs >= HOST_HEARTBEAT_STALE_MS;
+    // The host window stopped keeping its registry slice alive AND the agent it
+    // owned is dead: the pair went down together without teardown.
+    if (windowGone && !input.pidAlive)
+        return 'host-gone';
+    if (!input.pidAlive)
+        return 'connected'; // a plain dead pid is `closed`, not an orphan
+    // Alive with tmux reporting zero attached clients: nobody is watching it. This
+    // is the authoritative signal — tmux knows exactly how many clients it has.
+    if (input.tmuxClients === 0)
+        return 'no-client';
+    // Alive, not tmux-hosted (or tmux says someone is attached), but the window
+    // that owned it is gone. The agent outlived its editor.
+    if (windowGone)
+        return 'no-client';
+    return 'connected';
+}

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

@@ -0,0 +1,85 @@
+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 {
+    sessionId: string;
+    agent: string;
+    location: PresenceLocation;
+    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;
+    from: PresenceStatus;
+    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). */
+export 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[];
+};

package/dist/lib/session/presence.js

@@ -0,0 +1,150 @@
+/**
+ * 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 function presenceFilePath(dir) {
+    return path.join(dir ?? path.join(getRuntimeStateDir(), 'watchdog'), 'presence.json');
+}
+export function loadPresence(dir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(presenceFilePath(dir), 'utf8');
+    }
+    catch {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* corrupt — degrade to empty, never throw into the tick */
+    }
+    return {};
+}
+export function savePresence(map, dir) {
+    try {
+        const file = presenceFilePath(dir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        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) {
+        if (!s.sessionId)
+            continue;
+        const location = s.machine ? 'ssh' : 'local';
+        out.push({
+            sessionId: s.sessionId,
+            agent: s.kind,
+            location,
+            device: s.machine ?? selfHost,
+            transport: s.provenance?.transport ?? location,
+            interactive: s.context === 'terminal',
+        });
+    }
+    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';
+    if (record.interactive)
+        return 'reconnect-nudge';
+    if (record.location === 'ssh')
+        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 = {
+            sessionId: o.sessionId,
+            agent: o.agent,
+            location: o.location,
+            device: o.device,
+            transport: o.transport,
+            interactive: o.interactive,
+            lastSeenMs: nowMs,
+            status: 'connected',
+        };
+        next[o.sessionId] = record;
+        if (before && before.status === 'disconnected') {
+            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
+        const record = { ...before, status: 'disconnected' };
+        next[id] = record;
+        if (before.status === 'connected') {
+            transitions.push({
+                record,
+                from: 'connected',
+                to: 'disconnected',
+                action: actionFor(record),
+            });
+        }
+    }
+    return { next, transitions };
+}

package/dist/lib/session/remote-list.d.ts

@@ -16,6 +16,16 @@ export declare function remoteListCommand(forwardedArgs: string[], os?: string):
  * testing without a live tailnet.
  */
 export declare function parseRemoteList(stdout: string, machine: string): SessionMeta[];
+export declare function parseRemoteListPayload(stdout: string, machine: string, safeResolver?: boolean): {
+    sessions: SessionMeta[];
+    valid: boolean;
+};
+/** Convert one completed peer process into the exact aggregation result. This
+ * is the production parent/peer seam and is exercised with real child output. */
+export declare function remoteListCaptureResult(code: number | null, stdout: string, machine: string, display: string, safeResolver?: boolean): {
+    sessions: SessionMeta[];
+    unreachable?: string;
+};
 export interface RemoteListResult {
     sessions: SessionMeta[];
     /** How many peer machines we attempted to reach (drives the empty-fleet tip). */

package/dist/lib/session/remote-list.js

@@ -61,15 +61,52 @@ export function parseRemoteList(stdout, machine) {
     }
     if (!Array.isArray(parsed))
         return [];
+    return parsed.flatMap((value) => value && typeof value === 'object' && !Array.isArray(value)
+        ? [{ ...value, machine, _remote: true }]
+        : []);
+}
+/** Strict parser used at the live peer boundary. A successful process with
+ * malformed/non-array JSON is an incomplete source, not an empty machine. */
+const SAFE_RESOLVER_KEYS = new Set([
+    'id', 'shortId', 'agent', 'origin', 'timestamp', 'lastActivity', 'project',
+    'version', 'label', 'topic', 'machine',
+]);
+function isSafeResolverRow(value) {
+    if (typeof value.id !== 'string' || typeof value.shortId !== 'string'
+        || typeof value.agent !== 'string' || typeof value.timestamp !== 'string')
+        return false;
+    return Object.keys(value).every(key => SAFE_RESOLVER_KEYS.has(key));
+}
+export function parseRemoteListPayload(stdout, machine, safeResolver = false) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return { sessions: [], valid: false };
+    }
+    if (!Array.isArray(parsed))
+        return { sessions: [], valid: false };
     const out = [];
     for (const x of parsed) {
-        if (x && typeof x === 'object' && !Array.isArray(x)) {
-            // `_remote` marks these as living on the peer's disk (not a local mirror),
-            // so the picker routes read/resume back over SSH instead of the local FS.
-            out.push({ ...x, machine, _remote: true });
+        if (!x || typeof x !== 'object' || Array.isArray(x))
+            return { sessions: [], valid: false };
+        if (safeResolver && !isSafeResolverRow(x)) {
+            return { sessions: [], valid: false };
         }
+        // `_remote` marks these as living on the peer's disk (not a local mirror),
+        // so the picker routes read/resume back over SSH instead of the local FS.
+        out.push({ ...x, machine, _remote: true });
     }
-    return out;
+    return { sessions: out, valid: true };
+}
+/** Convert one completed peer process into the exact aggregation result. This
+ * is the production parent/peer seam and is exercised with real child output. */
+export function remoteListCaptureResult(code, stdout, machine, display, safeResolver = false) {
+    if (code !== 0)
+        return { sessions: [], unreachable: display };
+    const parsed = parseRemoteListPayload(stdout, machine, safeResolver);
+    return parsed.valid ? { sessions: parsed.sessions } : { sessions: [], unreachable: display };
 }
 /** Run one remote `agents sessions … --json` and capture stdout. Resolves
  * `{ code: null }` on spawn error or timeout (host treated as dead). */
@@ -95,11 +132,12 @@ function sshCapture(target, remoteCmd, timeoutMs) {
 }
 async function fetchByTarget(target, machine, display, forwardedArgs, os) {
     const { code, stdout } = await sshCapture(target, remoteListCommand(forwardedArgs, os), REMOTE_TIMEOUT_MS);
-    if (code !== 0) {
+    const safeResolver = forwardedArgs.includes('--resolve-safe-v1');
+    const result = remoteListCaptureResult(code, stdout, machine, display, safeResolver);
+    if (result.unreachable) {
         process.stderr.write(chalk.gray(`  ${display}: unreachable or no agents CLI — skipped\n`));
-        return { sessions: [], unreachable: display };
     }
-    return { sessions: parseRemoteList(stdout, machine) };
+    return result;
 }
 /**
  * Gather listing sessions from other machines. With an explicit `hosts` list
@@ -122,7 +160,7 @@ export async function gatherRemoteList(forwardedArgs, hosts) {
             reg = await loadDevices();
         }
         catch {
-            return { sessions: [], deviceCount: 0, unreachable: [] };
+            return { sessions: [], deviceCount: 0, unreachable: ['device registry'] };
         }
         for (const d of Object.values(reg)) {
             if (d.tailscale?.online !== true)

package/dist/lib/tmux/binary.d.ts

@@ -46,6 +46,13 @@ export interface RunTmuxOptions {
     throwOnError?: boolean;
     /** Child process env. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Kill the child and reject after this many ms. Unset = wait forever (the
+     * historical behavior). A wedged tmux server would otherwise hang the caller
+     * indefinitely — the active-session scan passes a bound so a bad server can't
+     * freeze `agents sessions --active`.
+     */
+    timeoutMs?: number;
 }
 /**
  * Run a tmux command and capture stdout/stderr. The socket arg is hoisted in

package/dist/lib/tmux/binary.js

@@ -131,10 +131,20 @@ export async function runTmux(opts) {
         });
         let stdout = '';
         let stderr = '';
+        let timer;
+        if (opts.timeoutMs && opts.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                child.kill();
+                reject(new Error(`tmux ${fullArgs.join(' ')} timed out after ${opts.timeoutMs}ms`));
+            }, opts.timeoutMs);
+        }
         child.stdout?.on('data', (b) => { stdout += b.toString('utf8'); });
         child.stderr?.on('data', (b) => { stderr += b.toString('utf8'); });
-        child.on('error', reject);
+        child.on('error', (err) => { if (timer)
+            clearTimeout(timer); reject(err); });
         child.on('close', (code) => {
+            if (timer)
+                clearTimeout(timer);
             const exitCode = code ?? -1;
             const throwOnError = opts.throwOnError !== false;
             if (throwOnError && exitCode !== 0) {

package/dist/lib/types.d.ts

@@ -737,9 +737,10 @@ export interface Meta {
         secretsBundle?: string;
     };
     /** macOS secrets-agent config. `policy` is the default prompt policy for
-     * bundles without an explicit per-bundle policy: `daily` (the default) asks
-     * once per ~7 days, `always` asks every time. `auto` (default on) lets the
-     * first real keychain read of a `daily` bundle populate the broker so
+     * bundles without an explicit per-bundle policy: `hold` (the default) asks
+     * once per hold window (7 days out of the box), `always` asks every time.
+     * `auto` (default on) lets the
+     * first real keychain read of a `hold` bundle populate the broker so
      * concurrent runs read silently — set it `false` to force a prompt on every read.
      * `holdMs` caps how long an unlocked/auto-cached bundle is held before the next
      * read re-prompts (default 7 days; e.g. 86400000 for a 24h cap). Clamped to