@phnx-labs/agents-cli 1.22.55 → 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/overdue.js

@@ -13,48 +13,18 @@
  */
 import * as fs from 'fs';
 import { Cron } from 'croner';
-import { listJobs, getLatestRun, resolveJobFilePath, isPastEndAt, isOneShotRoutine, jobRunsOnThisDevice } from './scheduling/routines.js';
+import { alignedSlotForFire, listJobs, getLatestRun, resolveJobFilePath, isPastEndAt, isOneShotRoutine, jobRunsOnThisDevice } from './scheduling/routines.js';
 import { notifyDesktop } from './menubar/notify-desktop.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
 const GRACE_MS = 60_000;
-const DAY_MS = 24 * 60 * 60 * 1000;
-/**
- * Lookback windows, narrowest first. A fixed one-week window silently blinded
- * detection to any cron whose gap exceeds it: `0 9 1,13,25 * *` has 12-day gaps,
- * so `nextRun(now - 7d)` jumped past `now`, the walk returned null, and the
- * routine was never flagged overdue on any device — no missed record, no
- * catch-up, permanently. Monthly, quarterly and annual routines were all in that
- * class.
- *
- * A wider window is only tried when the narrower one found nothing, so a dense
- * schedule (every minute, hourly, daily) never walks more than a week of
- * occurrences. A sparse schedule has few occurrences to walk by definition.
- */
-const LOOKBACK_WINDOWS_MS = [7 * DAY_MS, 32 * DAY_MS, 93 * DAY_MS, 400 * DAY_MS];
-/** Compute the most recent fire of `pattern` at or before `now`. Croner's
- *  `previousRun()` returns the cron instance's own last fire, which is null
- *  on a freshly-constructed instance — so we walk `nextRun(cursor)` forward
- *  from a week ago and keep the last fire still ≤ now. */
+/** Compute the most recent fire of `pattern` at or before `now`. Delegates to
+ *  {@link alignedSlotForFire} so overdue detection (`missedRunId`) and the live
+ *  forward-timer dispatch (`slotRunId`) key on the SAME occurrence identity — a
+ *  missed fire and its live twin for one UTC slot then collide by construction
+ *  (SING-15). */
 function previousExpectedFire(cron, now) {
-    for (const window of LOOKBACK_WINDOWS_MS) {
-        let cursor = new Date(now.getTime() - window);
-        let last = null;
-        // Cap iterations: an every-minute schedule yields ≤ 10080 steps over a week;
-        // 20k is a paranoia bound against pathological patterns. Only a schedule
-        // that found nothing in the narrower window reaches a wider one, and such a
-        // schedule is sparse, so the cap is never the binding constraint.
-        for (let i = 0; i < 20000; i++) {
-            const next = cron.nextRun(cursor);
-            if (!next || next.getTime() > now.getTime())
-                break;
-            last = next;
-            cursor = next;
-        }
-        if (last)
-            return last;
-    }
-    return null;
+    return alignedSlotForFire(cron, now);
 }
 /**
  * When a routine started existing, and therefore the earliest fire it can

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/scheduler.d.ts

@@ -5,13 +5,32 @@
  * process creates a single JobScheduler instance that loads enabled jobs
  * on startup and reloads them on SIGHUP.
  */
+import { Cron } from 'croner';
 import type { JobConfig } from './scheduling/routines.js';
 /** How a fire was triggered, carrying the scheduler's intended UTC slot time. */
 export interface TriggerContext {
-    /** The cron slot this callback fires for (croner `currentRun()`), for the
-     *  single-fire claim keyed on (routine, scheduledFor). */
+    /** The ALIGNED cron slot this callback fires for, for the single-fire claim
+     *  keyed on (routine, scheduledFor). Derived by {@link fireSlot} — NOT croner's
+     *  raw `currentRun()`, which carries wall-clock jitter. */
     scheduledFor?: Date;
 }
+/**
+ * The aligned occurrence boundary a fire callback belongs to — the value the
+ * single-fire `(routine, scheduledFor)` claim keys on.
+ *
+ * croner's `currentRun()` inside a fire callback is the JITTERED wall-clock
+ * trigger instant (it carries milliseconds — verified against croner 10.x), not
+ * the aligned schedule boundary. Keying `slotRunId` on it directly minted a
+ * distinct run id per delivery, so two callbacks for one occurrence each claimed
+ * a different run dir and both launched, and a live fire never collided with its
+ * catch-up twin (`missedRunId`, which keys on the aligned boundary). Flooring the
+ * fire to its schedule boundary via {@link alignedSlotForFire} makes the claim a
+ * structural claim on the occurrence identity (SING-15). Always returns a
+ * concrete Date — `currentRun()` falls back to now, and an unresolvable boundary
+ * falls back to the fire instant — so the forward path never dispatches without a
+ * durable slot key.
+ */
+export declare function fireSlot(cron: Cron): Date;
 /** In-memory cron scheduler that triggers a callback when jobs fire. */
 export declare class JobScheduler {
     private jobs;

package/dist/lib/scheduler.js

@@ -6,7 +6,27 @@
  * on startup and reloads them on SIGHUP.
  */
 import { Cron } from 'croner';
-import { listJobs, deleteJob, isPastEndAt, isPastOneShotRoutine, isOneShotRoutine, setJobEnabled, shouldPurgeCompletedOneShotRoutine, jobRunsOnThisDevice, hasAmbiguousDevicePin, routineOwnerDevice, } from './scheduling/routines.js';
+import { alignedSlotForFire, listJobs, deleteJob, isPastEndAt, isPastOneShotRoutine, isOneShotRoutine, setJobEnabled, shouldPurgeCompletedOneShotRoutine, jobRunsOnThisDevice, hasAmbiguousDevicePin, routineOwnerDevice, } from './scheduling/routines.js';
+/**
+ * The aligned occurrence boundary a fire callback belongs to — the value the
+ * single-fire `(routine, scheduledFor)` claim keys on.
+ *
+ * croner's `currentRun()` inside a fire callback is the JITTERED wall-clock
+ * trigger instant (it carries milliseconds — verified against croner 10.x), not
+ * the aligned schedule boundary. Keying `slotRunId` on it directly minted a
+ * distinct run id per delivery, so two callbacks for one occurrence each claimed
+ * a different run dir and both launched, and a live fire never collided with its
+ * catch-up twin (`missedRunId`, which keys on the aligned boundary). Flooring the
+ * fire to its schedule boundary via {@link alignedSlotForFire} makes the claim a
+ * structural claim on the occurrence identity (SING-15). Always returns a
+ * concrete Date — `currentRun()` falls back to now, and an unresolvable boundary
+ * falls back to the fire instant — so the forward path never dispatches without a
+ * durable slot key.
+ */
+export function fireSlot(cron) {
+    const fire = cron.currentRun() ?? new Date();
+    return alignedSlotForFire(cron, fire) ?? fire;
+}
 /** In-memory cron scheduler that triggers a callback when jobs fire. */
 export class JobScheduler {
     jobs = new Map();
@@ -75,10 +95,13 @@ export class JobScheduler {
                 return;
             }
             try {
-                // croner hands the callback its own Cron instance; `currentRun()` is the
-                // UTC time THIS invocation was scheduled for — the single-fire slot key.
-                // A duplicate delivery for the same slot resolves to one run downstream.
-                await this.onTrigger(config, { scheduledFor: self.currentRun() ?? undefined });
+                // scheduledFor is the ALIGNED occurrence boundary (fireSlot), not croner's
+                // jittered currentRun(): the single-fire claim keys on (routine,
+                // scheduledFor), so the key must be the occurrence identity or a live fire
+                // and its catch-up twin (missedRunId) won't collide and two deliveries of
+                // one slot each mint a distinct id. fireSlot always returns a Date, so the
+                // forward path always carries a durable claim (SING-15).
+                await this.onTrigger(config, { scheduledFor: fireSlot(self) });
             }
             catch (err) {
                 console.error(`Job '${config.name}' failed:`, err.message);

package/dist/lib/scheduling/routines.d.ts

@@ -6,6 +6,7 @@
  * run metadata persistence, prompt variable expansion, and one-shot "at" time
  * scheduling.
  */
+import { Cron } from 'croner';
 import { type ResolvedExecutionContext, type ProjectResolution, type PlacementMode, type RoutineKind, type ContextFsProbe } from '../routine-context.js';
 import type { AgentId, RunStrategy } from '../types.js';
 import type { LoopConfig } from '../loop.js';
@@ -837,6 +838,26 @@ export declare function getRunDir(jobName: string, runId: string): string;
  * for the same UTC slot are one record.
  */
 export declare function slotRunId(scheduledFor: Date | string): string;
+/**
+ * The aligned schedule boundary a fire belongs to: the most recent occurrence of
+ * `cron` at or before `at`.
+ *
+ * This is the occurrence IDENTITY that {@link slotRunId} (forward dispatch) and
+ * `missedRunId` (catchup.ts) must both key on. croner's `currentRun()` inside a
+ * fire callback is the JITTERED wall-clock trigger instant (it carries
+ * milliseconds — verified), not the aligned boundary, so keying `slotRunId`
+ * directly on it produced a distinct id per delivery: two callbacks for one
+ * occurrence each claimed a different run dir and both launched, and a live fire
+ * never collided with its catch-up twin (which keys on the aligned
+ * `previousExpectedFire`). Flooring both to this boundary is what makes the
+ * single-fire claim a structural claim on `(routine, scheduledFor)` (SING-15).
+ *
+ * croner's `previousRun()` takes no argument and returns null on a freshly
+ * constructed instance, so we walk `nextRun(cursor)` forward from a lookback
+ * window and keep the last fire still ≤ `at` — the same derivation catchup's
+ * overdue detection has always used.
+ */
+export declare function alignedSlotForFire(cron: Cron, at: Date): Date | null;
 /**
  * Atomically CLAIM a run directory. Returns true on a successful claim, false
  * when the directory already exists (another caller — even in a separate process

package/dist/lib/scheduling/routines.js

@@ -1518,6 +1518,62 @@ export function slotRunId(scheduledFor) {
     const iso = typeof scheduledFor === 'string' ? scheduledFor : scheduledFor.toISOString();
     return iso.replace(/[:.]/g, '-');
 }
+/**
+ * Lookback windows for {@link alignedSlotForFire}, narrowest first. A wider
+ * window is tried ONLY when the narrower one found no fire, so:
+ *  - a dense schedule (every-minute) resolves in the 1-hour window — ~60 steps,
+ *    not ~10080 — which matters because the forward-timer path now runs this on
+ *    every fire (a live fire is milliseconds past its boundary, so the narrowest
+ *    window always contains it);
+ *  - a sparse schedule (`0 9 1,13,25 * *` has 12-day gaps; monthly/quarterly/
+ *    annual) still resolves, because a fixed short window silently blinded
+ *    overdue detection to any cron whose gap exceeded it.
+ * A narrower window can only ever find the true most-recent fire ≤ `at` or
+ * nothing (never a wrong boundary), so prepending the cheap windows is
+ * behavior-preserving for the sparse-schedule overdue path.
+ */
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+const SLOT_LOOKBACK_WINDOWS_MS = [HOUR_MS, DAY_MS, 7 * DAY_MS, 32 * DAY_MS, 93 * DAY_MS, 400 * DAY_MS];
+/**
+ * The aligned schedule boundary a fire belongs to: the most recent occurrence of
+ * `cron` at or before `at`.
+ *
+ * This is the occurrence IDENTITY that {@link slotRunId} (forward dispatch) and
+ * `missedRunId` (catchup.ts) must both key on. croner's `currentRun()` inside a
+ * fire callback is the JITTERED wall-clock trigger instant (it carries
+ * milliseconds — verified), not the aligned boundary, so keying `slotRunId`
+ * directly on it produced a distinct id per delivery: two callbacks for one
+ * occurrence each claimed a different run dir and both launched, and a live fire
+ * never collided with its catch-up twin (which keys on the aligned
+ * `previousExpectedFire`). Flooring both to this boundary is what makes the
+ * single-fire claim a structural claim on `(routine, scheduledFor)` (SING-15).
+ *
+ * croner's `previousRun()` takes no argument and returns null on a freshly
+ * constructed instance, so we walk `nextRun(cursor)` forward from a lookback
+ * window and keep the last fire still ≤ `at` — the same derivation catchup's
+ * overdue detection has always used.
+ */
+export function alignedSlotForFire(cron, at) {
+    for (const window of SLOT_LOOKBACK_WINDOWS_MS) {
+        let cursor = new Date(at.getTime() - window);
+        let last = null;
+        // Cap iterations: an every-minute schedule yields ≤ 10080 steps over a week;
+        // 20k is a paranoia bound against pathological patterns. Only a schedule that
+        // found nothing in the narrower window reaches a wider one, and such a
+        // schedule is sparse, so the cap is never the binding constraint.
+        for (let i = 0; i < 20000; i++) {
+            const next = cron.nextRun(cursor);
+            if (!next || next.getTime() > at.getTime())
+                break;
+            last = next;
+            cursor = next;
+        }
+        if (last)
+            return last;
+    }
+    return null;
+}
 /**
  * Atomically CLAIM a run directory. Returns true on a successful claim, false
  * when the directory already exists (another caller — even in a separate process

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 {