@phnx-labs/agents-cli 1.22.59 → 1.22.61

package/dist/lib/session/active.js

@@ -41,7 +41,7 @@ import { detectProvenance } from './provenance.js';
 import { loadDevices } from '../devices/registry.js';
 import { machineId, normalizeHost } from '../machine-id.js';
 import { presenceFromStore } from './detached.js';
-import { classifyHostLink, HOST_HEARTBEAT_STALE_MS } from './host-link.js';
+import { classifyHostLink, hostWindowLost, HOST_HEARTBEAT_STALE_MS } from './host-link.js';
 import { mapBounded } from '../concurrency.js';
 import { linearIssueUrl } from './linear.js';
 import { viewingInLabel } from './viewing-in.js';
@@ -1810,6 +1810,10 @@ export async function getActiveSessions(opts = {}) {
     // Last: derive the shown title (recap ladder) from label/tail/topic now that
     // every row's live tail + label are resolved (RUSH-3011).
     foldRecap(merged);
+    // Project the coarse lifecycle bucket once status is final (foldHostLink above may
+    // have promoted a row to orphaned/crashed) so consumers read `phase` off the row
+    // instead of re-deriving it (PHNX-2484).
+    foldPhase(merged);
     return merged;
 }
 /**
@@ -1923,10 +1927,15 @@ export async function foldTmuxClients(rows) {
  *   - `crashed` REPLACES `closed`. Both mean the process is gone, but `closed`
  *     reads as a normal exit; `crashed` says the host window went down with it
  *     and never cleaned up.
- *   - `orphaned` replaces only `idle` / `input_required`. A session still WORKING
- *     with nobody watching is a normal headless run, and flagging every one would
- *     bury the real signal. A session sitting idle — or worse, waiting on a
- *     question — with no client attached is the stranded case: nobody is coming.
+ *   - `orphaned` replaces `idle` / `input_required` on ANY `no-client`, and
+ *     `running` ONLY when the owning WINDOW was lost (`hostWindowLost`). A
+ *     session still working with merely zero tmux clients is a normal headless
+ *     run — since RUSH-3125 a detached remote pane is the steady state — so
+ *     flagging every one would bury the real signal (the false positive reverted
+ *     in 6d973b823). But a running agent whose IDE window stopped republishing
+ *     its heartbeat outlived an unclean host death and is genuinely stranded, so
+ *     it IS promoted. A session sitting idle — or worse, waiting on a question —
+ *     with no client attached is the same stranded case: nobody is coming.
  */
 /**
  * Attribute each live row to the machine the session actually EXECUTES on.
@@ -2032,12 +2041,13 @@ export function foldHostLink(rows) {
             continue;
         // `closed` IS the dead-pid status — `lifecycleStatus` assigns it from
         // `!pidAlive` and nothing else — so the status is the pid answer here.
-        const link = classifyHostLink({
+        const signals = {
             pidAlive: s.status !== 'closed',
             windowHeartbeatMs: s.windowHeartbeatMs,
             tmuxClients: s.tmuxClients,
             deliberatelyDetached: s.presence === 'background' || s.presence === 'parked',
-        });
+        };
+        const link = classifyHostLink(signals);
         s.hostLink = link;
         // `foldPresence` gives every terminal row a DERIVED `attached` — "a live
         // interactive TUI you're watching" — which is exactly the claim a lost host
@@ -2057,6 +2067,14 @@ export function foldHostLink(rows) {
         else if (link === 'no-client' && (s.status === 'idle' || s.status === 'input_required')) {
             s.status = 'orphaned';
         }
+        // A still-`running` agent is normally a healthy headless run, so 0 tmux
+        // clients (a detached remote pane) MUST NOT flag it — that false positive was
+        // reverted once already (6d973b823). The ONE exception is a lost WINDOW: its
+        // owning IDE window stopped republishing, so it died uncleanly and the agent
+        // outlived it — genuinely stranded (PHNX-3183, `hostWindowLost`, SES-18a).
+        else if (s.status === 'running' && hostWindowLost(signals)) {
+            s.status = 'orphaned';
+        }
     }
 }
 /** One display line, trimmed and capped, or undefined when empty. */
@@ -2099,6 +2117,39 @@ export function foldRecap(rows) {
         s.lastAgentLine = recap.lastAgentLine;
     }
 }
+/**
+ * Project a {@link SessionPhase} from the finalized {@link ActiveStatus} (PHNX-2484).
+ * This is the single source of truth the AGI EXT previously mirrored as
+ * `mapStatusToPhase` — the ext now reads the `phase` field instead of re-deriving it.
+ * `queued` counts as `running` (dispatched, in the pipeline); `abandoned`, `orphaned`,
+ * and `crashed` all bucket to `failed` (dangling/dead — needs attention), which is the
+ * drift this fixes: those three used to fall through a status-only map to `idle` and
+ * silently hide a dead agent.
+ */
+export function derivePhase(status) {
+    switch (status) {
+        case 'running':
+        case 'queued':
+            return 'running';
+        case 'input_required':
+            return 'waiting';
+        case 'abandoned':
+        case 'orphaned':
+        case 'crashed':
+            return 'failed';
+        case 'closed':
+            return 'done';
+        case 'idle':
+        case 'unknown':
+        default:
+            return 'idle';
+    }
+}
+/** Fold the coarse lifecycle {@link SessionPhase} onto every row (see {@link derivePhase}). */
+export function foldPhase(rows) {
+    for (const s of rows)
+        s.phase = derivePhase(s.status);
+}
 /** Reap only stale sessions with proven-dead pids; unknown or live processes remain recoverable. */
 export function isReapableOrphan(row) {
     return row.status === 'abandoned' && row.pidAlive === false;

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

@@ -80,3 +80,25 @@ export interface HostLinkInput {
  * or a running editor.
  */
 export declare function classifyHostLink(input: HostLinkInput): HostLink;
+/**
+ * Did the owning IDE window die while the agent kept RUNNING? This is the ONE
+ * host-link loss that promotes a still-`running` session to `orphaned`
+ * (PHNX-3183): a window that WAS republishing its heartbeat every 4 min went
+ * stale for {@link HOST_HEARTBEAT_STALE_MS}, so it died uncleanly (a crash,
+ * reboot, or dropped SSH) and the agent it hosted outlived it — genuinely
+ * stranded, the "my remote agent is still alive after the laptop rebooted" case.
+ *
+ * Deliberately NARROWER than `no-client`. A tmux attached-client count of zero
+ * is also `no-client`, but for a detached remote pane (`agents run --device`,
+ * which RUSH-3125 wraps in a detached tmux session) that is the NORMAL steady
+ * state between check-ins — launch, detach, return with `agents focus` — not a
+ * loss. Promoting on it would relabel every unattended remote agent as
+ * `orphaned`, the over-reporting that makes the word worthless. Only a lost
+ * WINDOW is a positive "a client was expected and is now gone" for a running
+ * agent; mere absence is not.
+ *
+ * A deliberately-backgrounded session is excluded exactly as
+ * {@link classifyHostLink} excludes it: no client is the point of detaching.
+ * Pure — same injected signals as the classifier.
+ */
+export declare function hostWindowLost(input: HostLinkInput): boolean;

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

@@ -33,22 +33,32 @@
  * the extension agree on when a window is dead.
  */
 export const HOST_HEARTBEAT_STALE_MS = 10 * 60_000;
+/**
+ * Did the session's owning IDE window stop republishing its registry slice? A
+ * window republishes every 4 minutes (`HOST_HEARTBEAT_STALE_MS` is 10), so a
+ * slice this old means the window is gone, not merely quiet. Shared by
+ * {@link classifyHostLink} and {@link hostWindowLost} so the staleness rule has
+ * exactly one definition.
+ */
+function windowGone(input) {
+    const now = input.nowMs ?? Date.now();
+    return input.windowHeartbeatMs !== undefined && now - input.windowHeartbeatMs >= HOST_HEARTBEAT_STALE_MS;
+}
 /**
  * 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;
+    const stale = windowGone(input);
     // 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)
+    if (stale && !input.pidAlive)
         return 'host-gone';
     if (!input.pidAlive)
         return 'connected'; // a plain dead pid is `closed`, not an orphan
@@ -58,7 +68,7 @@ export function classifyHostLink(input) {
         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)
+    if (stale)
         return 'no-client';
     // Positive evidence of a client: tmux counted at least one attached client, or
     // a window is refreshing its registry slice. Either is a real observation.
@@ -68,3 +78,29 @@ export function classifyHostLink(input) {
     // reporting the healthy answer by default — see {@link HostLink}'s `unknown`.
     return 'unknown';
 }
+/**
+ * Did the owning IDE window die while the agent kept RUNNING? This is the ONE
+ * host-link loss that promotes a still-`running` session to `orphaned`
+ * (PHNX-3183): a window that WAS republishing its heartbeat every 4 min went
+ * stale for {@link HOST_HEARTBEAT_STALE_MS}, so it died uncleanly (a crash,
+ * reboot, or dropped SSH) and the agent it hosted outlived it — genuinely
+ * stranded, the "my remote agent is still alive after the laptop rebooted" case.
+ *
+ * Deliberately NARROWER than `no-client`. A tmux attached-client count of zero
+ * is also `no-client`, but for a detached remote pane (`agents run --device`,
+ * which RUSH-3125 wraps in a detached tmux session) that is the NORMAL steady
+ * state between check-ins — launch, detach, return with `agents focus` — not a
+ * loss. Promoting on it would relabel every unattended remote agent as
+ * `orphaned`, the over-reporting that makes the word worthless. Only a lost
+ * WINDOW is a positive "a client was expected and is now gone" for a running
+ * agent; mere absence is not.
+ *
+ * A deliberately-backgrounded session is excluded exactly as
+ * {@link classifyHostLink} excludes it: no client is the point of detaching.
+ * Pure — same injected signals as the classifier.
+ */
+export function hostWindowLost(input) {
+    if (input.deliberatelyDetached)
+        return false;
+    return input.pidAlive && windowGone(input);
+}

package/dist/lib/session/live-metadata.js

@@ -15,7 +15,8 @@
 // exist. It parses no transcript and renders nothing — it only reshapes process
 // state the live registry already computed. When the transcript IS on disk, the
 // synthesized row carries its path, so the downstream `buildPreview` renders the
-// real digest; otherwise it renders the header + a "not indexed here" note.
+// real digest. Without a path, a peer-owned row fetches its digest from that peer;
+// a genuinely local row renders the header + a "not indexed here" note.
 import { deriveShortId } from '../text/short-id.js';
 import { isSessionTrackedAgent } from './types.js';
 /**
@@ -50,9 +51,8 @@ export function activeSessionToSessionMeta(active, self, nowMs) {
         topic: active.topic,
         version: active.version,
         messageCount: undefined,
-        // The row runs HERE — the local live registry is machine-local, so a match
-        // resolves without an SSH hop back to a peer.
         machine: active.machine ?? self,
+        _remote: (active.machine ?? self) !== self,
         ticketId: active.ticket?.id,
         prUrl: active.pr?.url,
         prNumber: active.pr?.number,

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

@@ -90,6 +90,48 @@ export interface BuildTrajectoryOptions {
     /** Cap on drawn steps; the tail is dropped and counted. Default 5000. */
     maxSteps?: number;
 }
+/**
+ * The effective program a shell command ran, via the shared shell parser
+ * (`extractShellPrograms` — which unwraps the wrappers it knows: `env`, `sudo`,
+ * `agents ssh`; note `timeout` is deliberately NOT a wrapper there, per SES-37,
+ * so `timeout 30 npm test` resolves to `timeout`). On top of that this skips
+ * bare builtins/assignments (`cd`, `export`, …) when a real program follows. For
+ * a pipeline it takes the LEFTMOST effective program (`cat f | grep x` → `cat`),
+ * matching how the parser orders occurrences. Undefined when nothing static is
+ * identifiable. Never executes anything.
+ */
+export declare function effectiveProgram(command: string | undefined): string | undefined;
+/**
+ * One paired step: the drawn {@link TrajectoryStep}, the index of its originating
+ * `tool_use`/`thinking` event, and — once pairing completes — the index of the
+ * `tool_result`/`error` event that answered it. `buildSessionDetailV2` reads these
+ * triples (step, useEvent, resultEvent) to populate the schema-2 per-tool shapes
+ * WITHOUT re-running the callId pairing loop.
+ */
+export interface StepDraft {
+    step: TrajectoryStep;
+    eventIndex: number;
+    callId?: string;
+    resultEventIndex?: number;
+}
+/** Absolute ms per event index (NaN when the timestamp is unparseable). */
+export declare function eventTimestampsMs(events: SessionEvent[]): number[];
+/**
+ * Draw a step for each thinking block and each non-local tool_use, in order, and
+ * pair each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
+ * reused id — never across ids, and never by arrival order for concurrent calls,
+ * matching `ToolCallCollector.takePending`'s refusal to guess, `tool-calls.ts:509`).
+ *
+ * `_local` tool calls (Claude `!`-prefixed shell) are excluded to match the
+ * header's tool count (`computeSummaryStats` skips them, `render.ts:224`).
+ *
+ * The single source of the pairing: both {@link buildTrajectory} and
+ * `buildSessionDetailV2` consume the returned drafts (each draft's `eventIndex` +
+ * `resultEventIndex` are the use/result event indices) so the schema-2 producer
+ * never re-implements the loop. Durations/outcomes are still resolved by the
+ * caller — this only draws and pairs.
+ */
+export declare function pairSteps(events: SessionEvent[], eventMs: number[], firstTs: number, redact: boolean, knownSecrets: readonly string[] | undefined): StepDraft[];
 /**
  * Build the derived trajectory for one session's normalized events.
  *

package/dist/lib/session/trajectory.js

@@ -45,7 +45,7 @@ const SHELL_NOISE_PROGRAMS = new Set(['export', 'cd', 'set', 'source', '.', 'uns
  * matching how the parser orders occurrences. Undefined when nothing static is
  * identifiable. Never executes anything.
  */
-function effectiveProgram(command) {
+export function effectiveProgram(command) {
     if (!command)
         return undefined;
     const { occurrences, programs } = extractShellPrograms(command);
@@ -174,36 +174,26 @@ function resultDetail(event, redact, knownSecrets) {
     const clipped = clip(text, DETAIL_MAX);
     return redact ? redactSecrets(clipped, knownSecrets) : clipped;
 }
+/** Absolute ms per event index (NaN when the timestamp is unparseable). */
+export function eventTimestampsMs(events) {
+    return events.map((e) => toMs(e.timestamp));
+}
 /**
- * Build the derived trajectory for one session's normalized events.
- *
- * Pairs each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
+ * Draw a step for each thinking block and each non-local tool_use, in order, and
+ * pair each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
  * reused id — never across ids, and never by arrival order for concurrent calls,
  * matching `ToolCallCollector.takePending`'s refusal to guess, `tool-calls.ts:509`).
- * A harness with no parseable transcript (OpenClaw, `parse.ts:186`) yields an empty
- * event array and therefore an empty trajectory — never a crash or a fabricated one.
+ *
+ * `_local` tool calls (Claude `!`-prefixed shell) are excluded to match the
+ * header's tool count (`computeSummaryStats` skips them, `render.ts:224`).
+ *
+ * The single source of the pairing: both {@link buildTrajectory} and
+ * `buildSessionDetailV2` consume the returned drafts (each draft's `eventIndex` +
+ * `resultEventIndex` are the use/result event indices) so the schema-2 producer
+ * never re-implements the loop. Durations/outcomes are still resolved by the
+ * caller — this only draws and pairs.
  */
-export function buildTrajectory(events, meta, options = {}) {
-    const redact = options.redact !== false;
-    const knownSecrets = options.knownSecrets;
-    const idleThreshold = options.idleThresholdMs ?? DEFAULT_IDLE_THRESHOLD_MS;
-    const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
-    const stats = computeSummaryStats(events);
-    const firstTs = stats.firstTs;
-    const spanMs = stats.lastTs > stats.firstTs ? stats.lastTs - stats.firstTs : 0;
-    // Absolute ms per event index (NaN when the timestamp is unparseable).
-    const eventMs = events.map((e) => toMs(e.timestamp));
-    // The next event index (after i) that carries a valid timestamp — the anchor
-    // for the next-event duration fallback and for idle-gap detection.
-    const nextValidTs = new Array(events.length).fill(NaN);
-    for (let i = events.length - 1, later = NaN; i >= 0; i--) {
-        nextValidTs[i] = later;
-        if (!Number.isNaN(eventMs[i]))
-            later = eventMs[i];
-    }
-    // Draw a step for each thinking block and each non-local tool_use, in order.
-    // `_local` tool calls (Claude `!`-prefixed shell) are excluded to match the
-    // header's tool count (`computeSummaryStats` skips them, `render.ts:224`).
+export function pairSteps(events, eventMs, firstTs, redact, knownSecrets) {
     const drafts = [];
     const pendingByCallId = new Map();
     for (let i = 0; i < events.length; i++) {
@@ -261,6 +251,35 @@ export function buildTrajectory(events, meta, options = {}) {
             }
         }
     }
+    return drafts;
+}
+/**
+ * Build the derived trajectory for one session's normalized events.
+ *
+ * Pairs each `tool_use` with its `tool_result`/`error` on `callId` (FIFO within a
+ * reused id — never across ids, and never by arrival order for concurrent calls,
+ * matching `ToolCallCollector.takePending`'s refusal to guess, `tool-calls.ts:509`).
+ * A harness with no parseable transcript (OpenClaw, `parse.ts:186`) yields an empty
+ * event array and therefore an empty trajectory — never a crash or a fabricated one.
+ */
+export function buildTrajectory(events, meta, options = {}) {
+    const redact = options.redact !== false;
+    const knownSecrets = options.knownSecrets;
+    const idleThreshold = options.idleThresholdMs ?? DEFAULT_IDLE_THRESHOLD_MS;
+    const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
+    const stats = computeSummaryStats(events);
+    const firstTs = stats.firstTs;
+    const spanMs = stats.lastTs > stats.firstTs ? stats.lastTs - stats.firstTs : 0;
+    const eventMs = eventTimestampsMs(events);
+    // The next event index (after i) that carries a valid timestamp — the anchor
+    // for the next-event duration fallback and for idle-gap detection.
+    const nextValidTs = new Array(events.length).fill(NaN);
+    for (let i = events.length - 1, later = NaN; i >= 0; i--) {
+        nextValidTs[i] = later;
+        if (!Number.isNaN(eventMs[i]))
+            later = eventMs[i];
+    }
+    const drafts = pairSteps(events, eventMs, firstTs, redact, knownSecrets);
     // Resolve durations, outcomes, and detail now that pairing is complete.
     for (const draft of drafts) {
         const { step } = draft;

package/dist/lib/ssh-exec.d.ts

@@ -61,6 +61,36 @@ export declare class RemoteUtf8Accumulator {
     end(): string;
     current(): string;
 }
+/**
+ * How long OpenSSH keeps a multiplex master alive after its last client exits
+ * (`ControlPersist`, in seconds).
+ *
+ * The master only survives while it stays IDLE under this window, so it helps
+ * exactly a *repeated* touch of the same host that arrives within the window; a
+ * touch that arrives after the master has expired pays the full cold TCP+auth
+ * handshake again (~100-300ms direct, up to ~500ms relayed; measured on the live
+ * fleet 2026-08-10, PHNX-2582).
+ *
+ * The repeated same-host touches are the ad-hoc `--device` and fleet fan-out
+ * calls — `sessions --active`, `fleet ping`/`status`, `doctor`, `teams`, a
+ * `--device <box>` command run a few times while working — which arrive in
+ * BURSTS spread over minutes, not on a fixed clock. (The one truly high-frequency
+ * caller, `followHostTask`'s ~1.5s follow poll, was already warm even at 60s and
+ * is not the target here.) At the old 60s window any two touches of the same box
+ * more than a minute apart were both cold, so a burst paid a fresh handshake
+ * almost every time.
+ *
+ * 10 minutes keeps a multi-minute burst warm (3-5ms per reuse) while still
+ * bounding how long an idle master lingers — an important limit, because a reused
+ * master to a box that has since slept costs a ~45s ServerAlive teardown on the
+ * first touch (`ServerAliveInterval=15 × ServerAliveCountMax=3`), and a wider
+ * window would only widen the chance of hitting that. The daemon's periodic
+ * SSH-touching services (`usage-sync`/`auth-sync`) tick every 15 minutes, longer
+ * than this window ON PURPOSE: warming them would need a wider window for a
+ * handshake that is negligible at that cadence. Fan-outs stay bounded regardless
+ * by their own per-peer `timeoutMs`.
+ */
+export declare const SSH_CONTROL_PERSIST_SECONDS: number;
 export declare function controlOpts(): string[];
 /**
  * Compose an ssh connection-option prefix.

package/dist/lib/ssh-exec.js

@@ -87,20 +87,52 @@ export class RemoteUtf8Accumulator {
         return this.value;
     }
 }
+/**
+ * How long OpenSSH keeps a multiplex master alive after its last client exits
+ * (`ControlPersist`, in seconds).
+ *
+ * The master only survives while it stays IDLE under this window, so it helps
+ * exactly a *repeated* touch of the same host that arrives within the window; a
+ * touch that arrives after the master has expired pays the full cold TCP+auth
+ * handshake again (~100-300ms direct, up to ~500ms relayed; measured on the live
+ * fleet 2026-08-10, PHNX-2582).
+ *
+ * The repeated same-host touches are the ad-hoc `--device` and fleet fan-out
+ * calls — `sessions --active`, `fleet ping`/`status`, `doctor`, `teams`, a
+ * `--device <box>` command run a few times while working — which arrive in
+ * BURSTS spread over minutes, not on a fixed clock. (The one truly high-frequency
+ * caller, `followHostTask`'s ~1.5s follow poll, was already warm even at 60s and
+ * is not the target here.) At the old 60s window any two touches of the same box
+ * more than a minute apart were both cold, so a burst paid a fresh handshake
+ * almost every time.
+ *
+ * 10 minutes keeps a multi-minute burst warm (3-5ms per reuse) while still
+ * bounding how long an idle master lingers — an important limit, because a reused
+ * master to a box that has since slept costs a ~45s ServerAlive teardown on the
+ * first touch (`ServerAliveInterval=15 × ServerAliveCountMax=3`), and a wider
+ * window would only widen the chance of hitting that. The daemon's periodic
+ * SSH-touching services (`usage-sync`/`auth-sync`) tick every 15 minutes, longer
+ * than this window ON PURPOSE: warming them would need a wider window for a
+ * handshake that is negligible at that cadence. Fan-outs stay bounded regardless
+ * by their own per-peer `timeoutMs`.
+ */
+export const SSH_CONTROL_PERSIST_SECONDS = 10 * 60;
 /**
  * OpenSSH connection-multiplexing options. The first connection to a host opens
  * a control socket; subsequent connections (even from a *separate* `agents`
  * invocation) reuse it, skipping the TCP+auth handshake — so repeated
  * `--device <name>` calls to the same box feel local instead of paying ~100-300ms
- * each. `ControlPersist=60s` keeps the master alive briefly after the last
- * client exits. `%C` (a short fixed-length hash of local-host/remote/port/user)
- * keeps the socket path well under macOS's 104-char `sun_path` limit.
+ * each. `ControlPersist` keeps the master alive after the last client exits, sized
+ * to span a multi-minute burst of repeated touches — see
+ * {@link SSH_CONTROL_PERSIST_SECONDS} for the value and the rationale. `%C` (a
+ * short fixed-length hash of local-host/remote/port/user) keeps the socket path
+ * well under macOS's 104-char `sun_path` limit.
  *
  * This is **on by default** for every `sshExec`/`sshStream` call: the poll loops
  * (`followHostTask`), readiness probes, and per-host fan-outs are exactly the
  * high-frequency callers that benefit most from socket reuse, and they should
  * never have to remember to opt in. A caller passes `multiplex: false` only for
- * a genuine one-shot where a lingering 60s master is pure overhead.
+ * a genuine one-shot where a lingering master is pure overhead.
  *
  * The socket directory is created lazily; if ssh can't open the control socket
  * it falls back to a normal connection (multiplexing is an optimisation, never a
@@ -126,7 +158,7 @@ export function controlOpts() {
     return [
         '-o', 'ControlMaster=auto',
         '-o', `ControlPath=${path.join(dir, 'cm-%C')}`,
-        '-o', 'ControlPersist=60s',
+        '-o', `ControlPersist=${SSH_CONTROL_PERSIST_SECONDS}s`,
     ];
 }
 /**

package/dist/lib/startup/command-registry.js

@@ -5,7 +5,7 @@ const LOADED_COMMAND_NAMES = [
     'routines', 'monitors', 'projects', 'run', 'open', 'reconnect', 'fork', 'config',
     'models', 'modes', 'trash', 'restore', 'doctor',
     'route', 'harness', 'harnesses', 'secrets', 'menubar', 'sync',
-    'refresh-rules', 'factory', 'insights', 'trace',
+    'refresh-rules', 'factory', 'insights', 'trace', 'reminders',
     'pty', 'tmux', 'watchdog', 'browser', 'computer', 'logs', 'events',
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
     'teams', 'cloud', 'message', 'send', 'notify', 'feed',

package/dist/lib/subagents-registry.d.ts

@@ -29,6 +29,17 @@ export interface SubagentTarget {
     occupied(dir: string, name: string): OccupiedEntry[];
     /** Rich metadata for `name`; `null` skips it from the listing. */
     read(dir: string, name: string): SubagentMeta | null;
+    /**
+     * True when the installed subagent `sub` in `dir` byte-matches what `write`
+     * would materialize from `sub.path` NOW — the content-drift check `agents
+     * doctor` uses. Re-renders the CURRENT source through the same transform the
+     * writer uses (never a stored hash), so a prompt-body edit to the source
+     * surfaces as drift even though the filename is unchanged.
+     */
+    matches(dir: string, sub: {
+        name: string;
+        path: string;
+    }): boolean;
 }
 /**
  * Copy every file in `src` into `dest` (created if missing), applying
@@ -55,6 +66,13 @@ export declare function writeSubagentToHome(agent: AgentId, home: string, sub: {
 }): boolean;
 /** Installed subagent names for `agent` under `home` (detector + orphan diff). */
 export declare function listInstalledSubagentNames(agent: AgentId, home: string): string[];
+/**
+ * True when subagent `name` installed for `agent` under `home` byte-matches what
+ * the writer would produce NOW from `sourceDir` — the content-drift predicate
+ * `agents doctor` uses. Returns false when the agent has no registry entry
+ * (nothing could have been written) so an unexpected home copy reads as drift.
+ */
+export declare function subagentContentMatches(agent: AgentId, home: string, name: string, sourceDir: string): boolean;
 /**
  * Rich listing of subagents installed for `agent` under `home`, with parsed
  * metadata. Enumerates names, then reads each -- entries whose metadata is

package/dist/lib/subagents-registry.js

@@ -34,7 +34,17 @@ import * as path from 'path';
 import * as TOML from 'smol-toml';
 import * as yaml from 'yaml';
 import { safeJoin } from './paths.js';
+import { filesContentMatch, normalizeResourceContent } from './resource-content-diff.js';
 import { parseSubagentFrontmatter, transformSubagentForClaude, transformSubagentForCodex, transformSubagentForCopilot, transformSubagentForCursor, transformSubagentForDroid, transformSubagentForGoose, transformSubagentForKiro, transformSubagentForOpenCode, transformSubagentForAntigravity, } from './subagents.js';
+/** Read a file's UTF-8 content, or null when it is missing/unreadable. */
+function readFileSafe(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
 // ── metadata readers (the per-format escape hatch) ───────────────────────────
 /** Frontmatter, skipping files that lack a valid block (claude/grok/droid). */
 function metaFrontmatterSkip(filePath) {
@@ -130,6 +140,13 @@ function flatFile(opts) {
                 return null;
             return { frontmatter, files: [`${name}${opts.ext}`], path: filePath };
         },
+        matches(dir, sub) {
+            const filePath = path.join(dir, `${sub.name}${opts.ext}`);
+            const installed = readFileSafe(filePath);
+            if (installed == null)
+                return false;
+            return normalizeResourceContent(installed) === normalizeResourceContent(opts.transform(sub.path));
+        },
     };
 }
 /** A `<name>/` directory holding one generated `<file>` per subagent. */
@@ -162,6 +179,13 @@ function dirFile(opts) {
                 return null;
             return { frontmatter, files: [opts.file], path: filePath };
         },
+        matches(dir, sub) {
+            const filePath = path.join(dir, sub.name, opts.file);
+            const installed = readFileSafe(filePath);
+            if (installed == null)
+                return false;
+            return normalizeResourceContent(installed) === normalizeResourceContent(opts.transform(sub.path));
+        },
     };
 }
 /** Copy the whole source directory to `<name>/`, detected by `marker`. */
@@ -204,6 +228,49 @@ function dirCopy(opts) {
                 .sort();
             return { frontmatter, files, path: subagentDir };
         },
+        matches(dir, sub) {
+            // dirCopy materializes every source file (with rename) into <dir>/<name>/.
+            // Re-derive the expected file set from source and byte-compare each, so an
+            // edit to any copied file — or an added/removed source file — is drift.
+            const dest = path.join(dir, sub.name);
+            let sourceFiles;
+            try {
+                sourceFiles = fs.readdirSync(sub.path).filter((f) => {
+                    try {
+                        return fs.statSync(path.join(sub.path, f)).isFile();
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            }
+            catch {
+                return false;
+            }
+            const expectedDestNames = new Set();
+            for (const file of sourceFiles) {
+                const destName = opts.rename?.[file] ?? file;
+                expectedDestNames.add(destName);
+                if (!filesContentMatch(path.join(sub.path, file), path.join(dest, destName)))
+                    return false;
+            }
+            // An extra file left in the installed dir (source file removed) is drift.
+            let destFiles;
+            try {
+                destFiles = fs.readdirSync(dest).filter((f) => {
+                    try {
+                        return fs.statSync(path.join(dest, f)).isFile();
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            }
+            catch {
+                return false;
+            }
+            return destFiles.every((f) => expectedDestNames.has(f));
+        },
     };
 }
 // ── the registry ─────────────────────────────────────────────────────────────
@@ -295,6 +362,18 @@ export function listInstalledSubagentNames(agent, home) {
         return [];
     return target.names(target.dir(home));
 }
+/**
+ * True when subagent `name` installed for `agent` under `home` byte-matches what
+ * the writer would produce NOW from `sourceDir` — the content-drift predicate
+ * `agents doctor` uses. Returns false when the agent has no registry entry
+ * (nothing could have been written) so an unexpected home copy reads as drift.
+ */
+export function subagentContentMatches(agent, home, name, sourceDir) {
+    const target = SUBAGENT_TARGETS[agent];
+    if (!target)
+        return false;
+    return target.matches(target.dir(home), { name, path: sourceDir });
+}
 /**
  * Rich listing of subagents installed for `agent` under `home`, with parsed
  * metadata. Enumerates names, then reads each -- entries whose metadata is