@phnx-labs/agents-cli 1.22.60 → 1.22.62

package/dist/lib/permissions.js

@@ -776,7 +776,16 @@ export function convertToGrokFormat(set) {
 }
 function canonicalToGrokRule(perm, action) {
     if (BLANKET_BASH_FORMS.has(perm)) {
-        return { action, tool: 'bash', pattern: '*' };
+        // Grok's `*` is a SINGLE-LEVEL wildcard, so a `pattern: '*'` bash rule does
+        // NOT auto-approve a multi-token command like `ssh host cmd` or `scp a b`
+        // (PHNX-3294 — verified: two boxes carrying the identical `pattern="*"` rule
+        // differed only by `[ui].permission_mode`, and only the always-approve box
+        // ran ssh without prompting). Grok's documented "bare prefix matches all
+        // invocations" idiom is a rule with NO `pattern` key — the true allow-all
+        // shell form, matching how kimi (bare `Bash`), droid (`*`) and claude
+        // express a blanket Bash grant. This reads back as `Bash(*)` via the
+        // registry's pattern-less path, so the round-trip is unchanged.
+        return { action, tool: 'bash' };
     }
     const parsed = parseCanonicalPattern(perm);
     if (!parsed)
@@ -1885,3 +1894,149 @@ export function saveDefaultPermissionSet(set) {
     set.name = DEFAULT_PERMISSION_SET_NAME;
     return savePermissionSet(set);
 }
+// ============================================================================
+// Content-drift check (agents doctor, PHNX-3504)
+// ============================================================================
+/**
+ * Harnesses whose native permission file carries a per-rule allow/deny list the
+ * writer emits verbatim, so `agents doctor` can verify a group's rules survived
+ * into the version home rule-for-rule. The compare is done in the harness's OWN
+ * native vocabulary (Cursor `Shell(...)`, Droid command arrays, …) — NOT
+ * canonical — because every target's canonical round-trip is lossy
+ * (`lossyBecause` in `permissions-registry.ts`), so a canonical subset check
+ * would false-diff a correctly-synced home.
+ *
+ * Every other allowlist harness (codex/grok/kimi/kiro/antigravity/hermes/copilot)
+ * stores a lossy projection — a sandbox flag, whole-tool gate, per-directory
+ * approval, or a split/merged pattern — with no faithful per-group provenance, so
+ * doctor stays presence-only there and says so (`detail: 'format cannot verify
+ * content'`) rather than faking `ok`.
+ */
+export const PERMISSIONS_REPRESENTABLE = new Set([
+    'claude',
+    'opencode',
+    'cursor',
+    'droid',
+    'openclaw',
+]);
+function toStringSet(v) {
+    return new Set(Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+}
+function readJsonFileSafe(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** allow/deny rule strings in `agent`'s NATIVE vocabulary from its version home. */
+function homeNativePermissionRules(agent, versionHome) {
+    const target = PERMISSION_TARGETS[agent];
+    if (!target)
+        return null;
+    const configPath = target.home(versionHome);
+    if (!fs.existsSync(configPath))
+        return null;
+    switch (agent) {
+        case 'claude':
+        case 'cursor': {
+            const c = readJsonFileSafe(configPath);
+            const perms = (c?.permissions ?? {});
+            return { allow: toStringSet(perms.allow), deny: toStringSet(perms.deny) };
+        }
+        case 'droid': {
+            const c = readJsonFileSafe(configPath);
+            return { allow: toStringSet(c?.commandAllowlist), deny: toStringSet(c?.commandDenylist) };
+        }
+        case 'openclaw': {
+            const c = readJsonFileSafe(configPath);
+            const tools = (c?.tools ?? {});
+            return { allow: toStringSet(tools.alsoAllow), deny: toStringSet(tools.deny) };
+        }
+        case 'opencode': {
+            let c = null;
+            try {
+                c = JSON.parse(stripJsonComments(fs.readFileSync(configPath, 'utf-8')));
+            }
+            catch {
+                return null;
+            }
+            const bash = (c?.permission?.bash ?? {});
+            const allow = new Set();
+            const deny = new Set();
+            for (const [pattern, action] of Object.entries(bash)) {
+                if (action === 'allow')
+                    allow.add(pattern);
+                else if (action === 'deny')
+                    deny.add(pattern);
+            }
+            return { allow, deny };
+        }
+        default:
+            return null;
+    }
+}
+/** allow/deny rule strings in `agent`'s NATIVE vocabulary the writer WOULD emit. */
+function expectedNativePermissionRules(agent, set) {
+    switch (agent) {
+        case 'claude': {
+            const c = convertToClaudeFormat(set);
+            return { allow: new Set(c.permissions.allow), deny: new Set(c.permissions.deny) };
+        }
+        case 'cursor': {
+            const c = convertToCursorFormat(set);
+            return { allow: new Set(c.permissions.allow), deny: new Set(c.permissions.deny ?? []) };
+        }
+        case 'droid': {
+            const c = convertToDroidFormat(set);
+            return { allow: new Set(c.commandAllowlist), deny: new Set(c.commandDenylist) };
+        }
+        case 'openclaw': {
+            const c = convertToOpenClawFormat(set);
+            return { allow: new Set(c.alsoAllow), deny: new Set(c.deny) };
+        }
+        case 'opencode': {
+            const c = convertToOpenCodeFormat(set);
+            const allow = new Set();
+            const deny = new Set();
+            for (const [pattern, action] of Object.entries(c.permission.bash)) {
+                if (action === 'allow')
+                    allow.add(pattern);
+                else if (action === 'deny')
+                    deny.add(pattern);
+            }
+            return { allow, deny };
+        }
+        default:
+            return { allow: new Set(), deny: new Set() };
+    }
+}
+/**
+ * True when permission GROUP `groupName` is faithfully present in `agent`'s
+ * version home — every rule the group renders into that harness's native format
+ * is on disk. Only meaningful for {@link PERMISSIONS_REPRESENTABLE} agents (the
+ * caller keeps the lossy harnesses presence-only); returns true for a lossy
+ * harness or an empty/header group so the caller does not down-rank it.
+ *
+ * The expected rules are re-derived from the CURRENT source group every call
+ * (never a stored hash), so a rule edited/added in the source group surfaces as
+ * drift even though the group name is unchanged (PHNX-3504).
+ */
+export function permissionsGroupMatches(agent, versionHome, groupName) {
+    if (!PERMISSIONS_REPRESENTABLE.has(agent))
+        return true;
+    const expected = expectedNativePermissionRules(agent, buildPermissionsFromGroups([groupName]));
+    if (expected.allow.size === 0 && expected.deny.size === 0)
+        return true; // header / empty group
+    const home = homeNativePermissionRules(agent, versionHome);
+    if (!home)
+        return false;
+    for (const r of expected.allow)
+        if (!home.allow.has(r))
+            return false;
+    for (const r of expected.deny)
+        if (!home.deny.has(r))
+            return false;
+    return true;
+}

package/dist/lib/refresh.js

@@ -20,7 +20,7 @@ import { readManifest, MANIFEST_FILENAME } from './manifest.js';
 import { getUserAgentsDir } from './state.js';
 import { installVersion, listInstalledVersions, isVersionIsolated, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from './installations/versions.js';
 import { listCliStatus, installCli, describeMethod, describeCheck, selectInstallMethod, } from './cli-resources.js';
-import { ensureShimCurrent, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from './installations/shims.js';
+import { ensureShimCurrent, ensureGhOverloadShim, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from './installations/shims.js';
 import { parseHookManifest, registerHooksToSettings } from './hooks/install.js';
 import { isPromptCancelled } from './format.js';
 /**
@@ -240,6 +240,14 @@ export async function refresh(options = {}) {
         }
     }
     // 5. Auto-add shims to PATH
+    // Refresh the gh overload shim so `gh pr checks` escapes the GraphQL rate limit
+    // for every user, transparently (PHNX-3501). Idempotent; POSIX-only in v1.
+    try {
+        ensureGhOverloadShim();
+    }
+    catch {
+        // Never let a shim-write hiccup break sync — real gh stays fine without it.
+    }
     if (!isShimsInPath()) {
         const pathResult = addShimsToPath();
         if (pathResult.success && !pathResult.alreadyPresent) {

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;