@phnx-labs/agents-cli 1.22.60 → 1.22.61

package/dist/lib/reminders.d.ts

@@ -0,0 +1,29 @@
+export interface Reminder {
+    /** Succinct form shown in the statusline (a few words). */
+    short: string;
+    /** Full principle, shown by `agents reminders`. Falls back to `short`. */
+    full: string;
+}
+/**
+ * Point the reminders file at a fixture for tests, mirroring
+ * `setClaudeUsageCachePathForTest` in accounting/usage.ts. Returns the prior
+ * override so a test can restore it. Pass `null` to clear.
+ */
+export declare function setRemindersFilePathForTest(filePath: string | null): string | null;
+export declare function remindersFilePath(): string;
+/**
+ * Load reminders from disk.
+ *
+ * Returns `[]` when the file does not exist — the feature is simply not opted
+ * in. Throws on a present-but-malformed file so `agents reminders` can surface
+ * the problem; the statusline caller deliberately swallows that, because a
+ * broken prompt is worse than a missing reminder line.
+ */
+export declare function loadReminders(filePath?: string): Reminder[];
+/**
+ * Deterministically pick one reminder for a session. Same `sessionId` always
+ * maps to the same reminder, so it is stable within a session; different session
+ * ids spread across the list, so concurrent agents show different reminders.
+ * Returns `null` when there are no reminders.
+ */
+export declare function pickReminderForSession(reminders: Reminder[], sessionId?: string): Reminder | null;

package/dist/lib/reminders.js

@@ -0,0 +1,88 @@
+/**
+ * Personal operating reminders.
+ *
+ * A small, user-owned list of principles kept in
+ * `~/.agents/reminders/reminders.yaml` and surfaced succinctly in the Claude
+ * statusline — one per session, chosen deterministically from the session id so
+ * concurrent agents each show a different one and it stays stable within a
+ * session. Presence of the file with at least one entry is the opt-in; there is
+ * no separate flag. The file syncs across the fleet via `agents repo push/pull`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { getUserAgentsDir } from './state.js';
+let remindersFilePathOverride = null;
+/**
+ * Point the reminders file at a fixture for tests, mirroring
+ * `setClaudeUsageCachePathForTest` in accounting/usage.ts. Returns the prior
+ * override so a test can restore it. Pass `null` to clear.
+ */
+export function setRemindersFilePathForTest(filePath) {
+    const prev = remindersFilePathOverride;
+    remindersFilePathOverride = filePath;
+    return prev;
+}
+export function remindersFilePath() {
+    return remindersFilePathOverride ?? path.join(getUserAgentsDir(), 'reminders', 'reminders.yaml');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Load reminders from disk.
+ *
+ * Returns `[]` when the file does not exist — the feature is simply not opted
+ * in. Throws on a present-but-malformed file so `agents reminders` can surface
+ * the problem; the statusline caller deliberately swallows that, because a
+ * broken prompt is worse than a missing reminder line.
+ */
+export function loadReminders(filePath = remindersFilePath()) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const parsed = parseYaml(raw);
+    const list = isRecord(parsed) && Array.isArray(parsed.reminders) ? parsed.reminders : null;
+    if (!list) {
+        throw new Error(`reminders file has no 'reminders:' list: ${filePath}`);
+    }
+    const reminders = [];
+    for (const item of list) {
+        if (!isRecord(item))
+            continue;
+        const short = typeof item.short === 'string' ? item.short.trim() : '';
+        if (!short)
+            continue;
+        const full = typeof item.full === 'string' && item.full.trim() ? item.full.trim() : short;
+        reminders.push({ short, full });
+    }
+    return reminders;
+}
+/**
+ * Deterministically pick one reminder for a session. Same `sessionId` always
+ * maps to the same reminder, so it is stable within a session; different session
+ * ids spread across the list, so concurrent agents show different reminders.
+ * Returns `null` when there are no reminders.
+ */
+export function pickReminderForSession(reminders, sessionId) {
+    if (reminders.length === 0)
+        return null;
+    const key = sessionId?.trim();
+    const index = key ? hashString(key) % reminders.length : 0;
+    return reminders[index];
+}
+/** FNV-1a 32-bit — stable, dependency-free, well-distributed for short ids. */
+function hashString(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}

package/dist/lib/resource-content-diff.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared content comparison for the resource-diff engine.
+ *
+ * `agents doctor` (and the plugin-drift describer) reconcile a version home's
+ * copy of a resource against its resolved source by comparing bytes. Two shapes
+ * of resource need it: a single file (a command, a rule, a transformed subagent)
+ * and a whole directory tree (a skill, a plugin mirror, a copied workflow).
+ * Both live here so every kind's differ shares ONE normalize rule, ONE ignore
+ * set, and ONE symlink-skip policy instead of re-deriving them (the duplication
+ * `doctor-diff.ts`'s `dirsContentMatch` had before PHNX-3504; the parallel
+ * `skillDirsMatch` copies in `versions.ts` / `detectors/skills.ts` are a separate
+ * follow-up cleanup so this change stays inside the fast-lane CI impact budget).
+ *
+ * Normalize: CRLF → LF and trim, so a trailing-newline / line-ending difference
+ * between two independently-written trees is not reported as content drift. This
+ * mirrors the byte compare `diffCommands` / `diffRules` already apply per file.
+ */
+/** OS metadata / local tooling that is never synced into a version home. */
+export declare const RESOURCE_CONTENT_IGNORE: Set<string>;
+/** CRLF → LF and trim, so line-ending / trailing-newline skew is not drift. */
+export declare function normalizeResourceContent(content: string): string;
+/**
+ * True when two files exist and their normalized content is identical. A missing
+ * or unreadable file on either side is a mismatch (never a silent match).
+ */
+export declare function filesContentMatch(a: string, b: string): boolean;
+/**
+ * True when two directory trees hold the same set of names and every file under
+ * them matches by normalized content. Symlinks and ignored entries are skipped
+ * on both sides; a name present on one side only, or a file/dir type mismatch,
+ * is a mismatch. An unreadable directory on either side is a mismatch.
+ */
+export declare function dirsContentMatch(src: string, dst: string): boolean;

package/dist/lib/resource-content-diff.js

@@ -0,0 +1,103 @@
+/**
+ * Shared content comparison for the resource-diff engine.
+ *
+ * `agents doctor` (and the plugin-drift describer) reconcile a version home's
+ * copy of a resource against its resolved source by comparing bytes. Two shapes
+ * of resource need it: a single file (a command, a rule, a transformed subagent)
+ * and a whole directory tree (a skill, a plugin mirror, a copied workflow).
+ * Both live here so every kind's differ shares ONE normalize rule, ONE ignore
+ * set, and ONE symlink-skip policy instead of re-deriving them (the duplication
+ * `doctor-diff.ts`'s `dirsContentMatch` had before PHNX-3504; the parallel
+ * `skillDirsMatch` copies in `versions.ts` / `detectors/skills.ts` are a separate
+ * follow-up cleanup so this change stays inside the fast-lane CI impact budget).
+ *
+ * Normalize: CRLF → LF and trim, so a trailing-newline / line-ending difference
+ * between two independently-written trees is not reported as content drift. This
+ * mirrors the byte compare `diffCommands` / `diffRules` already apply per file.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/** OS metadata / local tooling that is never synced into a version home. */
+export const RESOURCE_CONTENT_IGNORE = new Set([
+    '.DS_Store',
+    '.git',
+    '.gitignore',
+    '.venv',
+    '__pycache__',
+    'node_modules',
+]);
+/** CRLF → LF and trim, so line-ending / trailing-newline skew is not drift. */
+export function normalizeResourceContent(content) {
+    return content.replace(/\r\n/g, '\n').trim();
+}
+function readSafe(file) {
+    try {
+        return fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when two files exist and their normalized content is identical. A missing
+ * or unreadable file on either side is a mismatch (never a silent match).
+ */
+export function filesContentMatch(a, b) {
+    const ac = readSafe(a);
+    const bc = readSafe(b);
+    if (ac == null || bc == null)
+        return false;
+    return normalizeResourceContent(ac) === normalizeResourceContent(bc);
+}
+/**
+ * True when two directory trees hold the same set of names and every file under
+ * them matches by normalized content. Symlinks and ignored entries are skipped
+ * on both sides; a name present on one side only, or a file/dir type mismatch,
+ * is a mismatch. An unreadable directory on either side is a mismatch.
+ */
+export function dirsContentMatch(src, dst) {
+    const srcEntries = (() => {
+        try {
+            return fs.readdirSync(src, { withFileTypes: true });
+        }
+        catch {
+            return null;
+        }
+    })();
+    const dstEntries = (() => {
+        try {
+            return fs.readdirSync(dst, { withFileTypes: true });
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (!srcEntries || !dstEntries)
+        return false;
+    const filter = (es) => es
+        .filter((e) => !e.isSymbolicLink() && !RESOURCE_CONTENT_IGNORE.has(e.name))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const srcF = filter(srcEntries);
+    const dstF = filter(dstEntries);
+    if (srcF.length !== dstF.length)
+        return false;
+    for (let i = 0; i < srcF.length; i++) {
+        if (srcF[i].name !== dstF[i].name)
+            return false;
+        const a = path.join(src, srcF[i].name);
+        const b = path.join(dst, dstF[i].name);
+        if (srcF[i].isDirectory()) {
+            if (!dstF[i].isDirectory())
+                return false;
+            if (!dirsContentMatch(a, b))
+                return false;
+        }
+        else if (srcF[i].isFile()) {
+            if (!dstF[i].isFile())
+                return false;
+            if (!filesContentMatch(a, b))
+                return false;
+        }
+    }
+    return true;
+}

package/dist/lib/rules/compile.d.ts

@@ -8,6 +8,13 @@
  */
 import type { AgentId } from '../types.js';
 import { type RulesLayer } from './compose.js';
+/**
+ * Header the non-@-import compile path (`agents refresh-rules` → compileRulesForAgent)
+ * prepends to a compiled instruction file. Exported so `doctor-diff` can strip it
+ * before content-comparing a home rules file against the raw preset composition —
+ * a header-compiled home must still reconcile (the header is not source content).
+ */
+export declare const COMPILED_HEADER: string;
 export declare const COMPILED_HEADER_PROJECT: string;
 /** Sidecar manifest recording source file hashes for staleness detection. */
 export interface CompileManifest {

package/dist/lib/rules/compile.js

@@ -18,7 +18,13 @@ import { composeRules, composeRulesFromState } from './compose.js';
 // whitespace (if any) is captured so we can preserve it in the output.
 const IMPORT_RE = /(^|\s)@(\S+)/g;
 const MAX_DEPTH = 5;
-const COMPILED_HEADER = '<!-- Auto-compiled by agents-cli from ~/.agents/rules/AGENTS.md + imports.\n' +
+/**
+ * Header the non-@-import compile path (`agents refresh-rules` → compileRulesForAgent)
+ * prepends to a compiled instruction file. Exported so `doctor-diff` can strip it
+ * before content-comparing a home rules file against the raw preset composition —
+ * a header-compiled home must still reconcile (the header is not source content).
+ */
+export const COMPILED_HEADER = '<!-- Auto-compiled by agents-cli from ~/.agents/rules/AGENTS.md + imports.\n' +
     '     Edit the source files under ~/.agents/rules/ — edits to this file will be overwritten on next sync. -->\n\n';
 export const COMPILED_HEADER_PROJECT = '<!-- Auto-compiled by agents-cli from .agents/rules/AGENTS.md + imports.\n' +
     '     Edit the source files under .agents/rules/ — edits to this file will be overwritten on next sync. -->\n\n';

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

@@ -93,6 +93,19 @@ export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required' | 'c
  | 'orphaned'
 /** The host window died and took the agent with it — an unclean exit, not a normal close. */
  | 'crashed' | 'unknown';
+/**
+ * Coarse lifecycle bucket a UI groups a row by, projected once at the source from
+ * {@link ActiveStatus} so consumers stop re-deriving it (PHNX-2484). The vocabulary
+ * is deliberately small — five terminal-agnostic buckets — so the AGI EXT Fleet panel
+ * reads `phase` straight off the `sessions watch --json` row instead of mirroring the
+ * CLI status word onto its own enum (the ext's `mapStatusToPhase`, now deleted):
+ *   `running` — dispatched or actively working;
+ *   `waiting` — blocked on the operator (needs-you);
+ *   `failed`  — dangling/dead and needing attention (crashed, orphaned, abandoned);
+ *   `done`    — the process exited cleanly;
+ *   `idle`    — alive but quiet, or an unclassified state.
+ */
+export type SessionPhase = 'running' | 'waiting' | 'failed' | 'done' | 'idle';
 /**
  * Which rung of the recap ladder produced a row's shown {@link ActiveSession.title}
  * (RUSH-3011), best-first:
@@ -221,6 +234,13 @@ export interface ActiveSession {
      */
     lastActivityMs?: number;
     status: ActiveStatus;
+    /**
+     * Coarse lifecycle bucket derived once from {@link status} (see {@link SessionPhase}).
+     * Folded on at the end of {@link getActiveSessions} by {@link foldPhase}, AFTER
+     * {@link foldHostLink} has finalized `status` — so `orphaned`/`crashed` land in the
+     * `failed` bucket rather than being re-derived (and mis-bucketed as `idle`) downstream.
+     */
+    phase?: SessionPhase;
     /** Indexed launch origin, backfilled by the sessions command for JSON consumers. */
     origin?: 'cli' | 'routine';
     /** Routine definition name when origin is `routine`. */
@@ -776,10 +796,15 @@ export declare function foldTmuxClients(rows: ActiveSession[]): Promise<void>;
  *   - `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.
@@ -845,6 +870,18 @@ export declare function deriveSessionRecap(row: Pick<ActiveSession, 'label' | 't
 };
 /** Fold the recap ladder onto every row (see {@link deriveSessionRecap}). */
 export declare function foldRecap(rows: ActiveSession[]): void;
+/**
+ * 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 declare function derivePhase(status: ActiveStatus | undefined): SessionPhase;
+/** Fold the coarse lifecycle {@link SessionPhase} onto every row (see {@link derivePhase}). */
+export declare function foldPhase(rows: ActiveSession[]): void;
 /** Reap only stale sessions with proven-dead pids; unknown or live processes remain recoverable. */
 export declare function isReapableOrphan(row: Pick<ActiveSession, 'status' | 'pidAlive'>): boolean;
 /**

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/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.
  *