@phnx-labs/agents-cli 1.22.56 → 1.22.57

package/dist/lib/git.js

@@ -498,7 +498,7 @@ export async function getCurrentBranch(repoPath) {
  * repo" as a requested source before adopting it.
  */
 export function canonicalGitRemote(url) {
-    return url
+    const canonical = url
         .trim()
         .replace(/\/+$/, '') // trailing slashes first, so a trailing-slash-after-.git still strips
         .replace(/\.git$/i, '')
@@ -506,6 +506,36 @@ export function canonicalGitRemote(url) {
         .replace(/^[^@/]+@/, '') // strip user@ (git@, ssh user)
         .replace(':', '/') // scp-style host:owner/repo → host/owner/repo (first colon only)
         .toLowerCase();
+    // Fold a renamed repo's old name onto its new one so both compare equal
+    // everywhere (see RENAMED_REMOTE_ALIASES).
+    return RENAMED_REMOTE_ALIASES[canonical] ?? canonical;
+}
+/**
+ * Git remotes that denote the SAME repository under an old and a new name,
+ * keyed by canonical `host/owner/repo`. `phnx-labs/.agents-system` was renamed
+ * to `phnx-labs/.agents` on GitHub (PHNX-3394); {@link DEFAULT_SYSTEM_REPO}
+ * still points at the pre-rename slug (GitHub's own redirect makes that
+ * resolve fine), so folding the new name onto it here means both compare equal
+ * everywhere remotes are compared: {@link sameGitRemote} (repo adoption),
+ * {@link isSystemRepoRemote} (the system-origin check), and the
+ * DotAgents-layer classifier in state.ts.
+ */
+const RENAMED_REMOTE_ALIASES = {
+    'github.com/phnx-labs/.agents': 'github.com/phnx-labs/.agents-system',
+};
+/**
+ * True when a git remote URL (any transport form: ssh, https, scp-style) points
+ * at the system DotAgents repo — {@link DEFAULT_SYSTEM_REPO}'s current slug OR
+ * its `phnx-labs/.agents` rename target (PHNX-3394), which
+ * {@link canonicalGitRemote} folds onto it via {@link RENAMED_REMOTE_ALIASES}.
+ * Pure string check with no git spawn, so it is unit-testable off a live
+ * checkout; {@link isSystemRepoOrigin} reads a dir's origin and delegates here.
+ */
+export function isSystemRepoRemote(remote) {
+    if (!remote)
+        return false;
+    const c = canonicalGitRemote(remote);
+    return c === canonicalGitRemote(`https://github.com/${systemRepoSlug(DEFAULT_SYSTEM_REPO)}`);
 }
 /** True when two git remote URLs point at the same repo across transport forms. */
 export function sameGitRemote(a, b) {
@@ -1062,18 +1092,17 @@ export async function adoptUserRepoIfNeeded(dir, opts = {}) {
     return adoptRepoInPlace(dir, url);
 }
 /**
- * Check if the repo's origin points to the system repo.
+ * Check if the repo's origin points to the system repo — `phnx-labs/.agents-system`
+ * or its GitHub rename target `phnx-labs/.agents` (PHNX-3394), across any
+ * transport form. Reads the dir's origin and delegates the match to the pure
+ * {@link isSystemRepoRemote}.
  */
 export async function isSystemRepoOrigin(dir) {
     try {
         const git = simpleGit(dir);
         const remotes = await git.getRemotes(true);
         const origin = remotes.find(r => r.name === 'origin');
-        if (!origin?.refs?.fetch)
-            return false;
-        const url = origin.refs.fetch.toLowerCase();
-        const currentSlug = systemRepoSlug(DEFAULT_SYSTEM_REPO).toLowerCase();
-        return url.includes(currentSlug);
+        return isSystemRepoRemote(origin?.refs?.fetch);
     }
     catch {
         /* not a git repo or no remotes */

package/dist/lib/harness/adapter.d.ts

@@ -44,13 +44,13 @@ export interface ExecConfigEnvCtx {
     /** resolveInteractive(options) — computed once by the caller. */
     interactive: boolean;
     /**
-     * The role marked on THIS machine (worker | personal | undefined), resolved
-     * once by the caller from selfConfiguredDeviceRole(). A `personal` device is
-     * the user's own interactive box: it holds a real per-version login and the
-     * credential decision MUST defer to it for EVERY run — interactive OR headless
-     * — never the worker-only setup-token (RUSH-2395). Injected as a plain value
-     * (not imported) to keep the adapter import-leaf. Absent/undefined is treated
-     * as non-personal (worker-equivalent).
+     * The role marked on THIS machine (worker | personal | desktop | undefined),
+     * resolved once by the caller from selfConfiguredDeviceRole(). A headed device
+     * (`personal` or `desktop` — see isHeadedDeviceRole) holds a real per-version
+     * login and the credential decision MUST defer to it for EVERY run — interactive
+     * OR headless — never the worker-only setup-token (RUSH-2395). Injected as a
+     * plain value (not imported) to keep the adapter import-leaf. Absent/undefined
+     * is treated as non-headed (worker-equivalent).
      */
     deviceRole?: ConfiguredDeviceRole;
     /**

package/dist/lib/harness/adapters/claude.js

@@ -1,5 +1,6 @@
 import * as path from 'path';
 import { stripForeignConfigDir } from '../adapter.js';
+import { isHeadedDeviceRole } from '../../device-config.js';
 export const claudeAdapter = {
     id: 'claude',
     applyExecConfigEnv(result, ctx) {
@@ -47,8 +48,8 @@ export const claudeAdapter = {
         // path — agents.ts `isClaudeCredentialFileBlank`), so this path defers to
         // Claude Code, which reads its own ACL-trusted login item without a prompt and
         // asks a present human to log in only if the login is missing.
-        const personalDevice = ctx.deviceRole === 'personal';
-        if (ctx.interactive || personalDevice) {
+        const headedDevice = isHeadedDeviceRole(ctx.deviceRole);
+        if (ctx.interactive || headedDevice) {
             // Drop an INHERITED copy of OUR OWN setup-token: a launch from inside a
             // headless agent's shell inherits that agent's injected value via
             // sanitizeProcessEnv(process.env) and would keep authenticating as it,

package/dist/lib/hosts/remote-cmd.d.ts

@@ -177,6 +177,15 @@ export declare function buildWindowsAgentsCommand(cmd: WindowsAgentsCommand): st
  * (Credential Manager, or the headless file store when there's no logon
  * session), matching a local `agents secrets import`.
  */
+/**
+ * Run `agents <args> --from <tmp>` on a Windows peer, feeding the ssh-piped stdin
+ * through a temp file — the `agents.ps1` shim does not forward piped stdin to the
+ * node process, so a verb that reads stdin must be handed a file instead. The
+ * generic sibling of {@link buildWindowsStdinImportCommand}; the receiving verb
+ * MUST accept `--from <path>` (see `usage-ingest.ts`). The temp file is removed in
+ * a `finally` so a throw mid-run never leaves the payload behind.
+ */
+export declare function buildWindowsStdinAgentsCommand(args: string[]): string;
 export declare function buildWindowsStdinImportCommand(bundle: string, opts?: {
     force?: boolean;
     policyNever?: boolean;

package/dist/lib/hosts/remote-cmd.js

@@ -323,6 +323,28 @@ export function buildWindowsAgentsCommand(cmd) {
  * (Credential Manager, or the headless file store when there's no logon
  * session), matching a local `agents secrets import`.
  */
+/**
+ * Run `agents <args> --from <tmp>` on a Windows peer, feeding the ssh-piped stdin
+ * through a temp file — the `agents.ps1` shim does not forward piped stdin to the
+ * node process, so a verb that reads stdin must be handed a file instead. The
+ * generic sibling of {@link buildWindowsStdinImportCommand}; the receiving verb
+ * MUST accept `--from <path>` (see `usage-ingest.ts`). The temp file is removed in
+ * a `finally` so a throw mid-run never leaves the payload behind.
+ */
+export function buildWindowsStdinAgentsCommand(args) {
+    const forwarded = args.map(powershellQuote).join(' ');
+    const script = [
+        POWERSHELL_PROGRESS_SILENCE,
+        '$in = [Console]::In.ReadToEnd()',
+        '$tmp = $null',
+        `try { $tmp = [System.IO.Path]::GetTempFileName(); [System.IO.File]::WriteAllText($tmp, $in); ` +
+            `& agents ${forwarded} --from $tmp; $code = $LASTEXITCODE } ` +
+            `finally { if ($tmp) { Remove-Item -LiteralPath $tmp -Force -ErrorAction SilentlyContinue } }`,
+        'if ($null -eq $code) { $code = 1 }',
+        'exit $code',
+    ].join('; ');
+    return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
+}
 export function buildWindowsStdinImportCommand(bundle, opts = {}) {
     const force = opts.force ? ' --force' : '';
     const policy = opts.policyNever ? ' --policy never --i-understand' : '';

package/dist/lib/perf/db.d.ts

@@ -1,7 +1,7 @@
 /**
  * Disposable performance warehouse — SQLite under ~/.agents/.cache/perf/.
  *
- * Opened only by `agents perf` / `hooks profile` (read path). Writers use
+ * Opened only by `agents insights perf` / `hooks profile` (read path). Writers use
  * {@link recordSample} in `./spool.ts` (NDJSON, no SQLite).
  */
 import Database from '../sqlite.js';

package/dist/lib/perf/db.js

@@ -1,7 +1,7 @@
 /**
  * Disposable performance warehouse — SQLite under ~/.agents/.cache/perf/.
  *
- * Opened only by `agents perf` / `hooks profile` (read path). Writers use
+ * Opened only by `agents insights perf` / `hooks profile` (read path). Writers use
  * {@link recordSample} in `./spool.ts` (NDJSON, no SQLite).
  */
 import * as fs from 'fs';

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

@@ -8,14 +8,7 @@ import { type SessionProvenance } from './provenance.js';
 import { type DeviceRegistry } from '../devices/registry.js';
 import { type Presence } from './detached.js';
 import { type HostLink } from './host-link.js';
-/**
- * The owner (actor id) to show for a session in `--active`. Prefers the actor
- * recorded on the live-attribution source (the pid registry / teammate record),
- * but falls back to the durable per-session actor sidecar — written at spawn and,
- * unlike the pid entry, NOT overwritten by the SessionStart hook's own by-pid
- * write. Without this fallback a real `agents run` shows no owner whenever the
- * hook's actor-less entry wins the by-pid file (RUSH-2018 fix).
- */
+/** Prefer live actor attribution; the durable sidecar survives actor-less hook rewrites. */
 export declare function resolveOwner(pidActor: string | null | undefined, sessionId: string | undefined): string | undefined;
 /**
  * Per-PID `lsof` probes run bounded and staggered rather than as one parallel
@@ -830,18 +823,7 @@ export declare function sessionProcessIsLocal(s: Pick<ActiveSession, 'machine' |
  */
 export declare function sessionProcessHost(s: Pick<ActiveSession, 'machine' | 'offloadedFrom'>, self: string): string | undefined;
 export declare function foldHostLink(rows: ActiveSession[]): void;
-/**
- * The recap ladder (RUSH-3011): compute a row's shown {@link ActiveSession.title}
- * + {@link RecapSource} from the best available source, plus the cleaned first
- * prompt (`userPromptClean`/`userPromptKind`) and the `lastAgentLine`. Pure over
- * one row; exported for tests and folded in by {@link foldRecap}.
- *
- * Ladder, best-first: a `/rename`/harness `label` → the last assistant line →
- * the first-prompt topic. The `last` rung is agent-derived, so a session that
- * produced work stops showing its stale first prompt as the title. (`topic` is
- * the row's already-extracted first line, so image detection here is
- * path-based; a pure-attachment turn with no first-line text stays on `prompt`.)
- */
+/** Labels win, then the last assistant line, then the first-prompt topic. */
 export declare function deriveSessionRecap(row: Pick<ActiveSession, 'label' | 'topic' | 'tail'>): {
     title?: string;
     recapSource?: RecapSource;
@@ -851,17 +833,7 @@ 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;
-/**
- * True when a crash-leaked orphan is genuinely DEAD and should be reaped from the
- * reconnectable set rather than shown as resumable forever (RUSH-3011 / issue #3b).
- *
- * The gate is `abandoned` (no transcript write in {@link ABANDONED_STALE_MS}) AND
- * a dead pid — exactly "past the stale threshold whose pid is gone". A live pid
- * (an idle-but-unfinished session, the highest-risk state) is NEVER reaped, and
- * neither is a recently-`closed`/`crashed` session that just exited (still
- * resumable). `pidAlive` absent (a cloud row or an older peer that can't prove
- * death) also stays un-reaped — reaping is fail-safe, never a guess.
- */
+/** Reap only stale sessions with proven-dead pids; unknown or live processes remain recoverable. */
 export declare function isReapableOrphan(row: Pick<ActiveSession, 'status' | 'pidAlive'>): boolean;
 /**
  * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,

package/dist/lib/session/active.js

@@ -47,14 +47,7 @@ import { linearIssueUrl } from './linear.js';
 import { viewingInLabel } from './viewing-in.js';
 import { claudeProjectDirName } from '../project-key.js';
 const execFileAsync = promisify(execFile);
-/**
- * The owner (actor id) to show for a session in `--active`. Prefers the actor
- * recorded on the live-attribution source (the pid registry / teammate record),
- * but falls back to the durable per-session actor sidecar — written at spawn and,
- * unlike the pid entry, NOT overwritten by the SessionStart hook's own by-pid
- * write. Without this fallback a real `agents run` shows no owner whenever the
- * hook's actor-less entry wins the by-pid file (RUSH-2018 fix).
- */
+/** Prefer live actor attribution; the durable sidecar survives actor-less hook rewrites. */
 export function resolveOwner(pidActor, sessionId) {
     return pidActor ?? (sessionId ? readSessionActorRecord(sessionId)?.actor : undefined) ?? undefined;
 }
@@ -476,18 +469,8 @@ export function isPidAlive(pid, startedAtMs) {
     return true;
 }
 /**
- * Read the live-terminals registry, dedupe by sessionId.
- *
- * A pid-alive entry is a live session. A pid-DEAD entry is normally noise — a
- * terminal that closed a moment ago, before its window republished — and is
- * dropped. But a dead pid whose owning window ALSO stopped republishing is the
- * signature of a crash: the window went down hard and never ran the teardown that
- * would have removed this entry. Those are KEPT, so the session reaches the
- * listing at all — it used to vanish outright, a VS Code crash simply erasing its
- * agents from `--active`. Such a row arrives as `closed` (dead pid) carrying the
- * stale `windowHeartbeatMs`, which is what {@link foldHostLink} promotes to
- * `crashed`. `pidDead` is local to the dedupe below: a live entry must win a dead
- * one for the same session.
+ * Keep dead entries only when their window heartbeat also stopped, proving a crash;
+ * a live duplicate always wins.
  */
 function readLiveTerminals() {
     let raw;
@@ -541,20 +524,8 @@ function readLiveTerminals() {
 const CLAUDE_SESSION_FILE_CACHE_MAX = 256;
 const claudeSessionFileCache = new Map();
 /**
- * Locate the active Claude session file for a process. If we know the session
- * UUID (from terminal env or team parent), prefer the exact match. Otherwise
- * fall back to the most-recent-mtime .jsonl in the project's folder.
- *
- * Searches EVERY version-home project root, not just the live `~/.claude`
- * symlink. `~/.claude` points at the currently-installed agent version; a
- * session launched under an EARLIER version keeps its transcript under that
- * version's home (`…/.history/versions/claude/<ver>/home/.claude/projects/`).
- * Resolving only `~/.claude/projects` meant that the instant a newer version
- * was installed, every still-running older-version session lost its transcript
- * here — no `sessionFile`, so no start/activity time, so `agents sessions`
- * rendered it `unknown` and the watchdog skipped it as "no activity timestamp".
- * `getAgentSessionDirs('claude','projects')` is the same version-aware enumerator
- * the rest of the CLI uses, so this stays in lockstep with discovery.
+ * Search every version home because the live ~/.claude symlink moves after upgrades
+ * while older running sessions keep writing to their original home.
  */
 function findClaudeSessionFile(cwd, sessionId) {
     // Only memoize when the exact session UUID is known. Without an id the
@@ -2080,17 +2051,7 @@ export function foldHostLink(rows) {
         }
         if (link === 'host-gone' && s.status === 'closed')
             s.status = 'crashed';
-        // Only idle/input_required are promoted — a `running` session keeps its
-        // status (SES-18a). Extending this to a running agent with no client was
-        // tried and reverted: since RUSH-3125 wraps every remote interactive run in
-        // a detached tmux pane, "running with zero attached clients" is the NORMAL
-        // steady state between check-ins, and that path writes no detach record, so
-        // `deliberatelyDetached` is false for it. Promoting it would relabel every
-        // remote agent as orphaned whenever nobody is looking — the over-reporting
-        // this file's header calls worthless. Telling a stranded agent from a
-        // healthy unattended one needs to know a client was EXPECTED and LOST, which
-        // no signal available here carries; that belongs with the peer-side pane
-        // ownership work, not this function.
+        // A clientless running remote pane is normal; only stopped work can be called orphaned.
         else if (link === 'no-client' && (s.status === 'idle' || s.status === 'input_required')) {
             s.status = 'orphaned';
         }
@@ -2103,18 +2064,7 @@ function recapLine(s, max = 120) {
         return undefined;
     return t.length > max ? t.slice(0, max - 1).trimEnd() + '…' : t;
 }
-/**
- * The recap ladder (RUSH-3011): compute a row's shown {@link ActiveSession.title}
- * + {@link RecapSource} from the best available source, plus the cleaned first
- * prompt (`userPromptClean`/`userPromptKind`) and the `lastAgentLine`. Pure over
- * one row; exported for tests and folded in by {@link foldRecap}.
- *
- * Ladder, best-first: a `/rename`/harness `label` → the last assistant line →
- * the first-prompt topic. The `last` rung is agent-derived, so a session that
- * produced work stops showing its stale first prompt as the title. (`topic` is
- * the row's already-extracted first line, so image detection here is
- * path-based; a pure-attachment turn with no first-line text stays on `prompt`.)
- */
+/** Labels win, then the last assistant line, then the first-prompt topic. */
 export function deriveSessionRecap(row) {
     const lastAgentLine = recapLine(row.tail?.length ? row.tail[row.tail.length - 1] : undefined);
     const { clean: userPromptClean, kind: userPromptKind } = classifyUserPrompt(row.topic ?? '');
@@ -2147,17 +2097,7 @@ export function foldRecap(rows) {
         s.lastAgentLine = recap.lastAgentLine;
     }
 }
-/**
- * True when a crash-leaked orphan is genuinely DEAD and should be reaped from the
- * reconnectable set rather than shown as resumable forever (RUSH-3011 / issue #3b).
- *
- * The gate is `abandoned` (no transcript write in {@link ABANDONED_STALE_MS}) AND
- * a dead pid — exactly "past the stale threshold whose pid is gone". A live pid
- * (an idle-but-unfinished session, the highest-risk state) is NEVER reaped, and
- * neither is a recently-`closed`/`crashed` session that just exited (still
- * resumable). `pidAlive` absent (a cloud row or an older peer that can't prove
- * death) also stays un-reaped — reaping is fail-safe, never a guess.
- */
+/** 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/db.d.ts

@@ -567,46 +567,15 @@ interface TopCostSession {
  * vanished, mirroring querySessions' liveness filter.
  */
 export declare function topSessionsByCost(n: number, options?: QueryOptions): TopCostSession[];
-/** Look up a single session by its unique ID. */
 /**
- * Batch-resolve session ids to the machine each one runs on, in ONE indexed
- * query. `getActiveSessions` needs only this column for every live row, and
- * `getSessionById` would re-`prepare` a `SELECT *` and materialize a full
- * `SessionMeta` per id to read it — mirrors {@link findSessionsByShortIds}'s
- * single-round-trip pattern. Ids absent from the index are simply absent from
- * the map. Best-effort: an unavailable DB yields an empty map, so the live view
- * still renders (the caller then leaves rows attributed to this box).
+ * Read machine attribution in batches without materializing full sessions.
+ * Failure is best-effort so the live view can still render local attribution.
  */
 export declare function findSessionMachinesByIds(ids: string[]): Map<string, string>;
 export declare function getSessionById(id: string): SessionMeta | null;
-/**
- * Resolve a full-or-partial session id against the index, exact-first then
- * prefix — the DB-backed equivalent of resolveSessionById() that runs over the
- * SQLite table instead of a pre-loaded array. Matches both the full id and the
- * short id. An exact hit short-circuits so a complete id never also drags in its
- * prefix siblings. `scope` narrows by agent / version / project (cwd) so an
- * ambiguous prefix disambiguates against the caller's context.
- *
- * Routes through the full querySessions existence check (NOT skipExistenceCheck)
- * on purpose (RUSH-2436): that check now KEEPS a file-gone session whose user
- * turns still live in session_text (flagged archived) and only suppresses a
- * contentless phantom — so `agents sessions <id>` resolves an archived session
- * instead of failing with "No session found", while a phantom id still misses.
- */
+/** Exact ids win over prefixes; the normal existence check preserves archived content but excludes phantoms. */
 export declare function findSessionsById(idQuery: string, scope?: Pick<QueryOptions, 'agent' | 'version' | 'cwd' | 'project'>): SessionMeta[];
-/**
- * Batch-resolve many 8-char short ids to their sessions in ONE indexed query.
- * The live-scan path (listTmuxAgentSessions) turns every `ag-<agent>-<shortid>`
- * tmux pane name back into a full session id this way, so it pays a single
- * `short_id IN (…)` round-trip per scan instead of N per-pane lookups.
- *
- * Returns a map keyed by short_id (lowercased). Short ids are the first 8 chars
- * of the lowercase session UUID (deriveShortId), so a lowercased `IN` matches and
- * still uses idx_sessions_short_id. When several sessions share a short id — only
- * time-ordered ids (ULID/UUIDv7) ever collide; random UUIDv4 short ids are unique
- * in practice — the most-recently-active one wins (the caller can further
- * disambiguate by cwd).
- */
+/** Batch-resolve pane short ids; on collision the most recently active session wins. */
 export declare function findSessionsByShortIds(shortIds: string[]): Map<string, SessionMeta>;
 /** A single full-text search result with ranking score. */
 interface FtsHit {

package/dist/lib/session/db.js

@@ -3390,15 +3390,9 @@ export function topSessionsByCost(n, options = {}) {
         durationMs: r.duration_ms ?? 0,
     }));
 }
-/** Look up a single session by its unique ID. */
 /**
- * Batch-resolve session ids to the machine each one runs on, in ONE indexed
- * query. `getActiveSessions` needs only this column for every live row, and
- * `getSessionById` would re-`prepare` a `SELECT *` and materialize a full
- * `SessionMeta` per id to read it — mirrors {@link findSessionsByShortIds}'s
- * single-round-trip pattern. Ids absent from the index are simply absent from
- * the map. Best-effort: an unavailable DB yields an empty map, so the live view
- * still renders (the caller then leaves rows attributed to this box).
+ * Read machine attribution in batches without materializing full sessions.
+ * Failure is best-effort so the live view can still render local attribution.
  */
 export function findSessionMachinesByIds(ids) {
     const out = new Map();
@@ -3429,20 +3423,7 @@ export function getSessionById(id) {
     const row = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id);
     return row ? rowToMeta(row) : null;
 }
-/**
- * Resolve a full-or-partial session id against the index, exact-first then
- * prefix — the DB-backed equivalent of resolveSessionById() that runs over the
- * SQLite table instead of a pre-loaded array. Matches both the full id and the
- * short id. An exact hit short-circuits so a complete id never also drags in its
- * prefix siblings. `scope` narrows by agent / version / project (cwd) so an
- * ambiguous prefix disambiguates against the caller's context.
- *
- * Routes through the full querySessions existence check (NOT skipExistenceCheck)
- * on purpose (RUSH-2436): that check now KEEPS a file-gone session whose user
- * turns still live in session_text (flagged archived) and only suppresses a
- * contentless phantom — so `agents sessions <id>` resolves an archived session
- * instead of failing with "No session found", while a phantom id still misses.
- */
+/** Exact ids win over prefixes; the normal existence check preserves archived content but excludes phantoms. */
 export function findSessionsById(idQuery, scope = {}) {
     const q = idQuery.trim();
     if (!q)
@@ -3452,19 +3433,7 @@ export function findSessionsById(idQuery, scope = {}) {
         return exact;
     return querySessions({ ...scope, idPrefix: q });
 }
-/**
- * Batch-resolve many 8-char short ids to their sessions in ONE indexed query.
- * The live-scan path (listTmuxAgentSessions) turns every `ag-<agent>-<shortid>`
- * tmux pane name back into a full session id this way, so it pays a single
- * `short_id IN (…)` round-trip per scan instead of N per-pane lookups.
- *
- * Returns a map keyed by short_id (lowercased). Short ids are the first 8 chars
- * of the lowercase session UUID (deriveShortId), so a lowercased `IN` matches and
- * still uses idx_sessions_short_id. When several sessions share a short id — only
- * time-ordered ids (ULID/UUIDv7) ever collide; random UUIDv4 short ids are unique
- * in practice — the most-recently-active one wins (the caller can further
- * disambiguate by cwd).
- */
+/** Batch-resolve pane short ids; on collision the most recently active session wins. */
 export function findSessionsByShortIds(shortIds) {
     const out = new Map();
     const uniq = [...new Set(shortIds.map((s) => s.trim().toLowerCase()).filter(Boolean))];

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

@@ -54,14 +54,7 @@ export interface DiscoverOptions {
     idExact?: string;
     /** Session id prefix — a targeted indexed lookup with no scan (RUSH-2477). */
     idPrefix?: string;
-    /**
-     * Cold-miss repair: when another live process already holds the scan claim,
-     * wait (bounded) for that in-flight scan to finish before reading the index,
-     * instead of returning the pre-scan snapshot (RUSH-2682). A caller repairing a
-     * "not indexed yet" miss wants the fresh result the concurrent scan is about to
-     * write, not the stale read that just missed. Ignored when THIS process wins
-     * the claim (it scans itself) or no scan is in progress.
-     */
+    /** On a cold miss, briefly await the scan already holding the single-flight claim. */
     waitForScan?: boolean;
 }
 /** Progress report emitted during incremental scanning. */
@@ -181,41 +174,15 @@ export declare function discoverSessions(options?: DiscoverOptions): Promise<Ses
 interface IncrementalScanResult {
     /** True when this process won the single-flight claim and ran the scan. */
     claimed: boolean;
-    /**
-     * Transcripts parsed this scan — i.e. those whose (mtime, size) changed. Zero
-     * is the steady state on an idle box and does NOT mean the scan was skipped;
-     * read `claimed` for that.
-     *
-     * Twelve of the 13 SESSION_AGENTS contribute, including OpenCode, whose
-     * scanner filters to sessions whose own per-session stamp changed and reports
-     * that batch — so a tick whose only changed sessions live there no longer
-     * reports 0 (RUSH-2691). OpenClaw is the exception and contributes nothing:
-     * its scanner has no change detection to report (a TTL gate, a fresh stamp
-     * every run, and an entry list rebuilt as the current inventory), so counting
-     * it would overstate rather than measure. See `scanOpenClawIncremental`.
-     */
+    /** Changed transcripts parsed; zero with `claimed: true` is a successful no-op scan. */
     scanned: number;
 }
-/**
- * The write half of {@link discoverSessions}: claim the single-flight scan slot,
- * incrementally index this host's transcript dirs, and report what was parsed.
- *
- * Split out so a caller that only wants the index refreshed — the daemon's warm
- * tick — can run it WITHOUT the listing query `discoverSessions` ends with. That
- * query is not free: it applies a cwd filter, runs the `archived_at`-writing
- * existence check, and can issue a Linear fetch, none of which index anything
- * (RUSH-2691). Keeping one implementation here is also what stops the tick and
- * the foreground path from drifting apart.
- */
+/** Separate write half so daemon warming does not pay for listing or external enrichment. */
 export declare function scanSessionsIncremental(options?: {
     agent?: SessionAgentId;
     onProgress?: (p: ScanProgress) => void;
 }): Promise<IncrementalScanResult>;
-/**
- * Poll until no live process holds the scan claim, or the bound elapses
- * (RUSH-2682). Bounded so a wedged/slow scan can never hang a foreground preview.
- * Exported for the cold-miss repair test.
- */
+/** Bounded wait so a wedged scan cannot hang a foreground cold-miss repair. */
 export declare function waitForScanToSettle(timeoutMs?: number, pollMs?: number): Promise<boolean>;
 /** Read the current SQLite snapshot without scanning or parsing transcript files. */
 export declare function queryIndexedSessions(options?: DiscoverOptions, indexedOptions?: {
@@ -223,27 +190,8 @@ export declare function queryIndexedSessions(options?: DiscoverOptions, indexedO
     skipExistenceCheck?: boolean;
 }): Promise<SessionMeta[]>;
 /**
- * Resolve a full-or-partial session id against the LOCAL SQLite index only.
- *
- * A plain WAL read through `queryIndexedSessions` — same origin-machine
- * attribution and managed scoping every indexed read gets — with NO incremental
- * discovery scan (so none of `tryClaimScan`/`releaseScan`'s `BEGIN IMMEDIATE`
- * writer lock) and NO fleet SSH fan-out. This is the crash-restart storm path
- * (RUSH-2477): dozens of `sessions resume <id>` at once for a known local id must
- * each be a cheap read, never a writer-lock contender or a dial into the
- * not-yet-up tailnet. Exact id first, then prefix (matching `findSessionsById`),
- * so a complete id never also drags in its prefix siblings. Returns `[]` on a
- * genuine local miss, leaving the caller to fall back to the fleet resolver.
- *
- * The existence check is left ON (`skipExistenceCheck: false`), exactly as the old
- * `discoverSessions` path and `findSessionsById` do (RUSH-2436): it KEEPS a
- * file-gone session whose user turns still live in `session_text` (flagged
- * archived) and SUPPRESSES a contentless phantom — so a phantom id misses here and
- * falls through to the fleet resolver, instead of resolving to a row with no real
- * transcript to resume. For a present transcript — the storm's actual case, since
- * the crashed tabs' files are on disk — the check does no writes, so the lock-free
- * guarantee holds; it only writes to (un)archive a genuinely missing or resurrected
- * file, which is not the 20-at-once resume path.
+ * Resolve locally without scanning or fleet I/O, keeping concurrent crash recovery lock-light.
+ * The existence check preserves archived content while rejecting transcriptless phantoms.
  */
 export declare function resolveIndexedSessionById(idQuery: string): Promise<SessionMeta[]>;
 /**

package/dist/lib/session/discover.js

@@ -131,12 +131,7 @@ async function applyJsonlAppend(filePath, fromOffset, wasDroppingOversizedLine,
  * between `agents sessions` calls but is still being written to.
  */
 const HOT_FILE_WINDOW_MS = 600_000;
-/**
- * Kill-switch: set `AGENTS_SESSIONS_NO_DIR_LEDGER=1` to force the old full-walk
- * path (readdir + per-file stat every dir, every run — the pre-A-2 behavior),
- * skipping the dir_ledger short-circuit entirely. One env var reverts a field
- * regression to today's behavior.
- */
+/** Emergency kill-switch for the directory-ledger optimization. */
 function dirLedgerDisabled() {
     const v = process.env.AGENTS_SESSIONS_NO_DIR_LEDGER;
     return v === '1' || v === 'true';
@@ -175,17 +170,7 @@ export async function discoverSessions(options) {
         skipExistenceCheck: options?.skipExistenceCheck ?? false,
     });
 }
-/**
- * The write half of {@link discoverSessions}: claim the single-flight scan slot,
- * incrementally index this host's transcript dirs, and report what was parsed.
- *
- * Split out so a caller that only wants the index refreshed — the daemon's warm
- * tick — can run it WITHOUT the listing query `discoverSessions` ends with. That
- * query is not free: it applies a cwd filter, runs the `archived_at`-writing
- * existence check, and can issue a Linear fetch, none of which index anything
- * (RUSH-2691). Keeping one implementation here is also what stops the tick and
- * the foreground path from drifting apart.
- */
+/** Separate write half so daemon warming does not pay for listing or external enrichment. */
 export async function scanSessionsIncremental(options) {
     // Touch the DB so the schema is ready and connection is cached for this run.
     getDB();
@@ -222,11 +207,7 @@ export async function scanSessionsIncremental(options) {
         scanned += n;
     return { claimed: true, scanned };
 }
-/**
- * Poll until no live process holds the scan claim, or the bound elapses
- * (RUSH-2682). Bounded so a wedged/slow scan can never hang a foreground preview.
- * Exported for the cold-miss repair test.
- */
+/** Bounded wait so a wedged scan cannot hang a foreground cold-miss repair. */
 export async function waitForScanToSettle(timeoutMs = WAIT_FOR_SCAN_TIMEOUT_MS, pollMs = WAIT_FOR_SCAN_POLL_MS) {
     const deadline = Date.now() + timeoutMs;
     while (scanInProgressByLivePid()) {
@@ -259,27 +240,8 @@ export async function queryIndexedSessions(options, indexedOptions = {}) {
     return scopeToManaged(sessions, agents, options);
 }
 /**
- * Resolve a full-or-partial session id against the LOCAL SQLite index only.
- *
- * A plain WAL read through `queryIndexedSessions` — same origin-machine
- * attribution and managed scoping every indexed read gets — with NO incremental
- * discovery scan (so none of `tryClaimScan`/`releaseScan`'s `BEGIN IMMEDIATE`
- * writer lock) and NO fleet SSH fan-out. This is the crash-restart storm path
- * (RUSH-2477): dozens of `sessions resume <id>` at once for a known local id must
- * each be a cheap read, never a writer-lock contender or a dial into the
- * not-yet-up tailnet. Exact id first, then prefix (matching `findSessionsById`),
- * so a complete id never also drags in its prefix siblings. Returns `[]` on a
- * genuine local miss, leaving the caller to fall back to the fleet resolver.
- *
- * The existence check is left ON (`skipExistenceCheck: false`), exactly as the old
- * `discoverSessions` path and `findSessionsById` do (RUSH-2436): it KEEPS a
- * file-gone session whose user turns still live in `session_text` (flagged
- * archived) and SUPPRESSES a contentless phantom — so a phantom id misses here and
- * falls through to the fleet resolver, instead of resolving to a row with no real
- * transcript to resume. For a present transcript — the storm's actual case, since
- * the crashed tabs' files are on disk — the check does no writes, so the lock-free
- * guarantee holds; it only writes to (un)archive a genuinely missing or resurrected
- * file, which is not the 20-at-once resume path.
+ * Resolve locally without scanning or fleet I/O, keeping concurrent crash recovery lock-light.
+ * The existence check preserves archived content while rejecting transcriptless phantoms.
  */
 export async function resolveIndexedSessionById(idQuery) {
     const q = idQuery.trim();