@phnx-labs/agents-cli 1.22.73 → 1.22.74

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.22.74
+
+- **Launching an agent no longer dirties your tracked `.gitignore` (PHNX-3718).**
+  The per-harness resource sync self-manages ignore rules for the generated
+  `.claude/`, `.cursor/`, `.codex/`, … dirs it writes on every launch. Those
+  rules used to be written into the tracked `<project>/.gitignore`, but they are
+  never committed upstream — so every launch left the repo with a permanent
+  `M .gitignore` (one managed block per harness that had run there) that in turn
+  blocked `git pull` with *"local changes to .gitignore would be overwritten by
+  merge"*. The managed block now lives in `.git/info/exclude` (git's per-clone,
+  uncommitted ignore file, resolved via `git rev-parse --git-path info/exclude`
+  so it works from a subdir, linked worktree, or submodule), keeping the
+  generated dirs hidden while leaving the working tree clean. On the next launch,
+  a repo already dirtied by the old behavior self-heals: the leftover managed
+  block is stripped from the tracked `.gitignore` (hand-written rules untouched;
+  an untracked file that held only our block is removed). Source:
+  `cli/src/lib/project-resources.ts`.
+
+- **`sessions preview` of a remote session no longer dead-ends on the dispatcher
+  (PHNX-3890).** A box that launched a session running on another device kept a
+  transcript-less live row for it whose machine defaulted to itself, so
+  `agents sessions preview <full-uuid>` — and the interactive browser's preview
+  pane — rendered `Live session — full transcript not indexed here.` instead of
+  fetching the owning peer's digest. A passive peer rendered the same session
+  fine. The launcher shim is now reconciled against the fleet's own view of which
+  device runs the session, and a full-UUID hit only skips the fleet fan-out when
+  this box can actually answer for it (a transcript on disk, or a row that already
+  names another device). Remote previews fill in asynchronously over SSH; a
+  locally readable transcript or synced mirror still renders with no hop, and an
+  unreachable owner still fails loud. Source: `cli/src/commands/sessions.ts`,
+  `cli/src/lib/session/live-metadata.ts`.
+
 ## 1.22.73
 
 - **Ctrl-C works again while `agents sessions` is reaching other machines (PHNX-3791).** The static session list, `Searching the fleet…`, and the cloud session/fetch paths wrap their long SSH/network waits in `ora(...)`. ora defaults to `discardStdin: true`, which on a TTY flips stdin into raw mode for the spinner's lifetime (via `stdin-discarder`) — and raw mode disables the terminal's own ISIG, so a Ctrl-C keystroke no longer raises SIGINT. ora's compensating "re-emit SIGINT when I read a 0x03 byte" only fires when stdin is in *flowing* mode, but a fresh `process.stdin` has `flowing === null`, `isPaused()` returns false, the discarder skips its `resume()`, and `prependListener('data')` doesn't auto-resume — so the byte is never read and SIGINT is never raised. The global handler in `index.ts` (`process.exit(130)`) was correct; it simply never fired. The user-visible result: a sweep that stalls on offline/unreachable boxes (each burning a ~12s SSH `ConnectTimeout`) could not be aborted — measured, `agents sessions --flat` had to be SIGKILLed. New `lib/spinner.ts#interruptibleSpinner` is a drop-in for `ora(text)` built with `discardStdin: false`: the terminal stays in cooked mode, Ctrl-C raises SIGINT normally (and the terminal SIGINTs the whole foreground group, reaping the outstanding `ssh` children), and the process exits promptly — only cosmetic stray-keystroke discarding during the spin is lost. The five cross-machine/network spinners in `sessions.ts` route through it; short local spinners are unchanged. Source: `cli/src/lib/spinner.ts`, `cli/src/lib/spinner.test.ts`, `cli/src/commands/sessions.ts`.

package/dist/commands/sessions.d.ts

@@ -896,9 +896,58 @@ export declare function metadataResolveOutcome(localMatches: SessionMeta[], remo
     sessions: SessionMeta[];
     unreachable: string[];
 }, selector: string): MetadataResolveOutcome;
-/** Injectable dependency for the live-registry cold-miss fallback (RUSH-2682). */
+/**
+ * Whether a local candidate answers a full-UUID selector **definitively** — i.e.
+ * whether finding it on this box is the whole answer, so the fleet fan-out can be
+ * skipped (PHNX-3890).
+ *
+ * Two shapes qualify, and both are claims this box can actually back:
+ *
+ * - **A real transcript on this disk** (`filePath`). It renders locally, whoever
+ *   owns it — a local session or a fleet-synced mirror — so no SSH hop is needed.
+ * - **A genuine peer attribution** (`machine` names another box). The row already
+ *   routes the read to its owner through `transcriptOnPeerOf`, so the peer that
+ *   would answer the fan-out is the peer the render already dials.
+ *
+ * What does NOT qualify is the launcher-shim shape: a transcript-less live row
+ * whose `machine` is this box only because it DEFAULTED there
+ * (`activeSessionToSessionMeta`'s `active.machine ?? self`,
+ * `computeLocalMetadataMatches`'s `machine || localMachine`). A dispatcher holds
+ * exactly that row for a session whose agent and transcript live on a peer: the
+ * launch process is here, the conversation is not. Treating it as definitive is
+ * what dead-ended `agents sessions preview <full-uuid>` on the local
+ * "Live session — full transcript not indexed here." stub while a passive peer —
+ * which has no local row at all, so it fans out — rendered the real digest.
+ * Process locality is not transcript locality.
+ */
+export declare function isLocallyDefinitiveMatch(session: SessionMeta, self: string): boolean;
+/**
+ * Drop the launcher-shim local rows that a peer has since answered for
+ * (PHNX-3890). `fleetCandidatesByQuery` groups a logical session's copies per
+ * machine and every consumer reads `hits[0]`, with local rows passed first — so
+ * simply fanning out is not enough: the self-defaulted shim would still win the
+ * attribution and route the read back to a box with no transcript. When the peer
+ * that actually owns the session has answered the sweep, its row is the strictly
+ * better one, and the shim carries no information the candidate loses (same
+ * logical id, so the candidate — and any ambiguity it is part of — survives
+ * through the remote hit).
+ *
+ * A row that is {@link isLocallyDefinitiveMatch} is never dropped, so a locally
+ * readable transcript or a synced mirror still renders here with no SSH hop. When
+ * no peer answered for that id, the shim is kept: with no fleet evidence, a
+ * transcript-less self-attributed row is indistinguishable from a session THIS box
+ * just started, and dropping it would re-break the cold-index lookup RUSH-2682
+ * fixed.
+ */
+export declare function preferOwnerAttribution(localMatches: SessionMeta[], remoteSessions: SessionMeta[], self: string): SessionMeta[];
+/** Injectable dependencies for the live-registry cold-miss fallback (RUSH-2682)
+ * and the fleet-attribution reconciliation (PHNX-3890). */
 export type LiveMetadataDeps = {
     loadActive?: typeof loadLocalActiveSessions;
+    /** The fleet-active snapshot rows used to attribute a self-defaulted launcher
+     * shim to its true execution host. Defaults to the cached fleet snapshot; the
+     * cache is warmed by any fleet-wide `agents sessions --active`. */
+    loadFleetActive?: () => ActiveSession[];
 };
 /**
  * Local metadata candidates for a selector: the indexed SQLite rows, plus — when

package/dist/commands/sessions.js

@@ -29,14 +29,14 @@ import { mapPanesToTargets, listClients } from '../lib/tmux/session.js';
 import { resolveViewingIn, viewingInLabel } from '../lib/session/viewing-in.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.js';
-import { loadFleetActiveSessions, loadLocalActiveSessions, } from '../lib/session/session-cache.js';
+import { loadFleetActiveSessions, loadLocalActiveSessions, readActiveSessionsCache, } from '../lib/session/session-cache.js';
 import { gatherRemoteList, gatherRemoteToolProgramCounts, gatherRemoteToolSearch, runOnPeer } from '../lib/session/remote-list.js';
 import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
 import { inferSessionState } from '../lib/session/state.js';
 import { discoverSessions, queryIndexedSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots, scopeToManaged } from '../lib/session/discover.js';
 import { findSessionsById, querySessions, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
-import { liveSessionMetas } from '../lib/session/live-metadata.js';
+import { liveSessionMetas, fleetExecutionMachineById, reconcileLiveMetaMachine } from '../lib/session/live-metadata.js';
 import { filterTeamSessions, shouldShowTeamSessions, safeTeamText, groupSessionsByTeam, NO_TEAM_GROUP_KEY, } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
@@ -4844,6 +4844,59 @@ export function metadataResolveOutcome(localMatches, remote, selector) {
         return { kind: 'ambiguous', candidates };
     return { kind: 'resolved', session: candidates[0].hits[0].session };
 }
+/**
+ * Whether a local candidate answers a full-UUID selector **definitively** — i.e.
+ * whether finding it on this box is the whole answer, so the fleet fan-out can be
+ * skipped (PHNX-3890).
+ *
+ * Two shapes qualify, and both are claims this box can actually back:
+ *
+ * - **A real transcript on this disk** (`filePath`). It renders locally, whoever
+ *   owns it — a local session or a fleet-synced mirror — so no SSH hop is needed.
+ * - **A genuine peer attribution** (`machine` names another box). The row already
+ *   routes the read to its owner through `transcriptOnPeerOf`, so the peer that
+ *   would answer the fan-out is the peer the render already dials.
+ *
+ * What does NOT qualify is the launcher-shim shape: a transcript-less live row
+ * whose `machine` is this box only because it DEFAULTED there
+ * (`activeSessionToSessionMeta`'s `active.machine ?? self`,
+ * `computeLocalMetadataMatches`'s `machine || localMachine`). A dispatcher holds
+ * exactly that row for a session whose agent and transcript live on a peer: the
+ * launch process is here, the conversation is not. Treating it as definitive is
+ * what dead-ended `agents sessions preview <full-uuid>` on the local
+ * "Live session — full transcript not indexed here." stub while a passive peer —
+ * which has no local row at all, so it fans out — rendered the real digest.
+ * Process locality is not transcript locality.
+ */
+export function isLocallyDefinitiveMatch(session, self) {
+    if (session.filePath)
+        return true;
+    return !!session.machine && session.machine !== self;
+}
+/**
+ * Drop the launcher-shim local rows that a peer has since answered for
+ * (PHNX-3890). `fleetCandidatesByQuery` groups a logical session's copies per
+ * machine and every consumer reads `hits[0]`, with local rows passed first — so
+ * simply fanning out is not enough: the self-defaulted shim would still win the
+ * attribution and route the read back to a box with no transcript. When the peer
+ * that actually owns the session has answered the sweep, its row is the strictly
+ * better one, and the shim carries no information the candidate loses (same
+ * logical id, so the candidate — and any ambiguity it is part of — survives
+ * through the remote hit).
+ *
+ * A row that is {@link isLocallyDefinitiveMatch} is never dropped, so a locally
+ * readable transcript or a synced mirror still renders here with no SSH hop. When
+ * no peer answered for that id, the shim is kept: with no fleet evidence, a
+ * transcript-less self-attributed row is indistinguishable from a session THIS box
+ * just started, and dropping it would re-break the cold-index lookup RUSH-2682
+ * fixed.
+ */
+export function preferOwnerAttribution(localMatches, remoteSessions, self) {
+    if (remoteSessions.length === 0)
+        return localMatches;
+    const answeredByPeer = new Set(remoteSessions.map(session => session.id.toLowerCase()));
+    return localMatches.filter(session => isLocallyDefinitiveMatch(session, self) || !answeredByPeer.has(session.id.toLowerCase()));
+}
 /**
  * Local metadata candidates for a selector: the indexed SQLite rows, plus — when
  * an id-shaped selector misses the index entirely — the live-session registry
@@ -4881,7 +4934,20 @@ export async function computeLocalMetadataMatches(selector, scope, deps = {}) {
  */
 export async function liveMetadataMatches(selector, scope, self, deps = {}) {
     const load = deps.loadActive ?? loadLocalActiveSessions;
-    const match = (metas) => resolveIndexedMetadataRows(applyScopeFilters(metas, scope), selector, scope);
+    const loadFleet = deps.loadFleetActive ?? (() => readActiveSessionsCache('fleet')?.sessions ?? []);
+    // A launcher-shim row whose `machine` self-defaulted to this box gets its true
+    // EXECUTION host from the fleet snapshot, so a session dispatched to a peer is
+    // read on that peer instead of dead-ending on the local stub (PHNX-3890). The
+    // read is best-effort: an absent/cold snapshot leaves the row untouched and the
+    // fleet fan-out in resolveSessionMetadataValue supplies the owner instead.
+    let fleetExecMachine;
+    try {
+        fleetExecMachine = fleetExecutionMachineById(loadFleet());
+    }
+    catch {
+        fleetExecMachine = new Map();
+    }
+    const match = (metas) => resolveIndexedMetadataRows(applyScopeFilters(reconcileLiveMetaMachine(metas, fleetExecMachine, self), scope), selector, scope);
     try {
         const cached = liveSessionMetas((await load()).sessions, self, Date.now());
         const hit = match(cached);
@@ -4898,16 +4964,24 @@ export async function liveMetadataMatches(selector, scope, self, deps = {}) {
  * Full UUIDs hit the local SQLite index without any SSH fan-out. */
 export async function resolveSessionMetadataValue(selector, scope = {}, deps = { gatherRemoteList }) {
     const localMatches = await computeLocalMetadataMatches(selector, scope, deps);
+    const localMachine = machineId();
     // A full-UUID local hit resolves with ZERO SSH: a UUID is globally unique, so
     // finding it locally is the whole answer and no peer is dialed. (A label is
     // NOT resolved local-only here — it can collide with a same-label session on a
     // peer, so it must consult the fleet; see isDefinitiveMatch, RUSH-2203.) The
     // local index lookup is synchronous and completes before any fan-out spawns,
     // so this local hit never waits on a peer.
+    //
+    // "Found it locally" must mean this box can actually ANSWER for it, though —
+    // see isLocallyDefinitiveMatch. A transcript-less launcher shim for a session
+    // executing on a peer is a local row that is not a local answer, and
+    // short-circuiting on it skipped the one fan-out that could have named the
+    // owner (PHNX-3890).
     if (FULL_SESSION_ID_RE.test(selector)) {
         const localOutcome = metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, selector);
-        if (localOutcome.kind === 'resolved')
+        if (localOutcome.kind === 'resolved' && isLocallyDefinitiveMatch(localOutcome.session, localMachine)) {
             return localOutcome;
+        }
     }
     if (scope.local === true)
         return metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, selector);
@@ -4920,7 +4994,7 @@ export async function resolveSessionMetadataValue(selector, scope = {}, deps = {
         const remote = await deps.gatherRemoteList(forwarded, scope.hosts, selectorAllowsEarlyExit(selector)
             ? { isDefinitive: (session) => isDefinitiveMatch(session, selector) }
             : undefined);
-        return metadataResolveOutcome(localMatches, remote, selector);
+        return metadataResolveOutcome(preferOwnerAttribution(localMatches, remote.sessions, localMachine), remote, selector);
     }
     catch (error) {
         return metadataResolveOutcome(localMatches, { sessions: [], unreachable: [error?.message ?? 'fleet fan-out'] }, selector);

package/dist/lib/cloud/rush.d.ts

@@ -7,7 +7,7 @@
 import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities, ImageAttachment, SkillRef } from './types.js';
 /**
  * Returns true when ~/.rush/user.yaml exists, carries an access_token, and
- * the token has not passed its expires_at timestamp (Unix seconds). A missing
+ * the token has not passed its expires_at timestamp (Unix milliseconds). A missing
  * expires_at, or `expires_at: 0` (a non-expiring Phoenix `pid_` bearer), is
  * treated as non-expired (see isRushSessionExpired, PHNX-3645). Pass yamlPath
  * to override the default path in tests.

package/dist/lib/cloud/rush.js

@@ -19,7 +19,7 @@ const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 /**
  * Returns true when ~/.rush/user.yaml exists, carries an access_token, and
- * the token has not passed its expires_at timestamp (Unix seconds). A missing
+ * the token has not passed its expires_at timestamp (Unix milliseconds). A missing
  * expires_at, or `expires_at: 0` (a non-expiring Phoenix `pid_` bearer), is
  * treated as non-expired (see isRushSessionExpired, PHNX-3645). Pass yamlPath
  * to override the default path in tests.
@@ -58,7 +58,7 @@ export function readToken(yamlPath = USER_YAML) {
     }
     const expiresAt = data.session?.expires_at;
     if (isRushSessionExpired(expiresAt)) {
-        const expiredAt = new Date(expiresAt * 1000).toISOString();
+        const expiredAt = new Date(expiresAt).toISOString();
         throw new Error(`Rush session expired at ${expiredAt}. Run \`rush login\` to refresh.`);
     }
     return token;

package/dist/lib/project-resources.d.ts

@@ -7,7 +7,11 @@ export declare function projectAgentRoot(projectRoot: string, agent: AgentId): s
 export declare function syncProjectResourcesToAgent(agent: AgentId, version: string, projectAgentsDir: string): ProjectResourceSyncResult;
 /**
  * Turn the manifest's managed paths (relative to agentRoot) into anchored,
- * POSIX, projectRoot-relative `.gitignore` entries. Two guards keep it honest:
+ * POSIX, `referenceRoot`-relative ignore entries. `referenceRoot` is the
+ * directory the anchored `/…` patterns resolve against — the git worktree root
+ * for a `.git/info/exclude` block, since git anchors info/exclude patterns at
+ * the top of the working tree (not at the harness dir). Two guards keep it
+ * honest:
  *   - drop any path that escapes the harness config dir (e.g. grok writes
  *     commands back into the tracked `.agents/` tree via a `../` subdir —
  *     ignoring that would hide tracked source; separate bug, PHNX-3718);
@@ -16,7 +20,7 @@ export declare function syncProjectResourcesToAgent(agent: AgentId, version: str
  *     these never masks a hand-authored or committed file (e.g. a repo that
  *     commits its own `.claude/CLAUDE.md` keeps it — it is not in the manifest).
  */
-export declare function managedGitignoreEntries(agentRoot: string, projectRoot: string, managed: string[]): string[];
+export declare function managedGitignoreEntries(agentRoot: string, referenceRoot: string, managed: string[]): string[];
 /**
  * One human line for the files a project sync left alone because you already
  * wrote them. This is the normal steady state — every sync of a project whose

package/dist/lib/project-resources.js

@@ -1,3 +1,4 @@
+import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from './agents.js';
@@ -39,10 +40,14 @@ export function syncProjectResourcesToAgent(agent, version, projectAgentsDir) {
         // .agents/{commands,skills,…}, refreshed on every launch. Left untracked it
         // dirties `git status` and can block `git merge`/`checkout` when a stray
         // commit of the same path collides. So the generator owns its ignore rule:
-        // reconcile a per-agent marker block in <projectRoot>/.gitignore listing
-        // exactly the paths it manages. Passing the manifest set (empty when a sync
-        // clears a harness) also prunes the block. See PHNX-3717.
-        reconcileProjectGitignore(projectRoot, agent, agentRoot, Array.from(next).sort());
+        // reconcile a per-agent marker block listing exactly the paths it manages.
+        // That block lives in `.git/info/exclude` — git's per-clone, uncommitted
+        // ignore file — NOT the tracked `.gitignore`: these entries are never
+        // committed upstream, so writing them into `.gitignore` left every launch
+        // with a permanent `M .gitignore` that blocked `git pull` (PHNX-3718).
+        // Passing the manifest set (empty when a sync clears a harness) also prunes
+        // the block. See PHNX-3717 for the self-managed-ignore feature.
+        reconcileManagedIgnore(projectRoot, agent, agentRoot, Array.from(next).sort());
     }
     return result;
 }
@@ -75,7 +80,11 @@ function gitignoreMarkers(agent) {
 }
 /**
  * Turn the manifest's managed paths (relative to agentRoot) into anchored,
- * POSIX, projectRoot-relative `.gitignore` entries. Two guards keep it honest:
+ * POSIX, `referenceRoot`-relative ignore entries. `referenceRoot` is the
+ * directory the anchored `/…` patterns resolve against — the git worktree root
+ * for a `.git/info/exclude` block, since git anchors info/exclude patterns at
+ * the top of the working tree (not at the harness dir). Two guards keep it
+ * honest:
  *   - drop any path that escapes the harness config dir (e.g. grok writes
  *     commands back into the tracked `.agents/` tree via a `../` subdir —
  *     ignoring that would hide tracked source; separate bug, PHNX-3718);
@@ -84,7 +93,7 @@ function gitignoreMarkers(agent) {
  *     these never masks a hand-authored or committed file (e.g. a repo that
  *     commits its own `.claude/CLAUDE.md` keeps it — it is not in the manifest).
  */
-export function managedGitignoreEntries(agentRoot, projectRoot, managed) {
+export function managedGitignoreEntries(agentRoot, referenceRoot, managed) {
     const root = path.resolve(agentRoot);
     const entries = new Set();
     for (const rel of managed) {
@@ -93,31 +102,63 @@ export function managedGitignoreEntries(agentRoot, projectRoot, managed) {
         const abs = path.resolve(agentRoot, rel);
         if (abs !== root && !abs.startsWith(root + path.sep))
             continue;
-        const fromProject = toPosixRel(path.relative(projectRoot, abs));
-        if (!fromProject || fromProject === '..' || fromProject.startsWith('../'))
+        const fromRoot = toPosixRel(path.relative(referenceRoot, abs));
+        if (!fromRoot || fromRoot === '..' || fromRoot.startsWith('../'))
             continue;
-        entries.add('/' + fromProject);
+        entries.add('/' + fromRoot);
     }
     return Array.from(entries).sort();
 }
-/** True when `dir` is inside a git working tree — walks up to the filesystem
- *  root looking for a `.git` entry. `projectRoot` (the parent of the resolved
- *  `.agents/` dir) is not guaranteed to be the git root: a monorepo subdir can
- *  carry its own `.agents/` while `.git` lives several levels up. A root-only
- *  check would silently no-op the whole feature there. */
-function isInsideGitRepo(dir) {
-    let cur = path.resolve(dir);
-    for (;;) {
-        if (pathExists(path.join(cur, '.git')))
-            return true;
-        const parent = path.dirname(cur);
-        if (parent === cur)
-            return false;
-        cur = parent;
+/**
+ * Ask git where the local, per-clone ignore file lives and where the worktree
+ * top is, resolved robustly for every layout by delegating to git itself:
+ *   - normal repo → `<root>/.git/info/exclude`;
+ *   - monorepo subdir → the same file even when `.git` is several levels up
+ *     (`projectRoot`, the parent of `.agents/`, is not the git root);
+ *   - linked worktree / submodule → `.git` is a FILE (`gitdir: …`), and
+ *     `--git-path info/exclude` resolves to the shared COMMON dir so the block
+ *     applies across every worktree.
+ * `--path-format=absolute` forces absolute paths regardless of the `-C` cwd.
+ * One `git rev-parse` yields both paths (exclude path first, worktree root
+ * second), so the launch path spawns git ONCE, not twice.
+ * Returns null when `dir` is not inside a git repo (git exits non-zero), which
+ * fails the feature open (no-op) exactly like the old in-tree check did.
+ */
+function resolveGitExcludeTarget(dir) {
+    try {
+        const out = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-path', 'info/exclude', '--show-toplevel'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const [excludePath, worktreeRoot] = out.split('\n').map((l) => l.trim());
+        if (!excludePath || !worktreeRoot)
+            return null;
+        // Fail open on anything that isn't a clean pair of ABSOLUTE paths. A git
+        // older than 2.31 (predates `--path-format`) echoes the unrecognized flag
+        // back on stdout instead of erroring, which would otherwise shift the parse
+        // and have mkdirSync create a stray `--path-format=absolute` dir. The
+        // absolute-path check turns that into a clean no-op.
+        if (!path.isAbsolute(excludePath) || !path.isAbsolute(worktreeRoot))
+            return null;
+        return { excludePath, worktreeRoot };
+    }
+    catch {
+        return null;
+    }
+}
+/** True when git tracks `absPath` in the repo `dir` sits in. */
+function isTrackedByGit(dir, absPath) {
+    try {
+        execFileSync('git', ['-C', dir, 'ls-files', '--error-unmatch', '--', absPath], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+        });
+        return true;
+    }
+    catch {
+        return false;
     }
 }
 /**
- * Apply this agent's managed block to `.gitignore` content, IN PLACE.
+ * Apply this agent's managed block to ignore-file content, IN PLACE — used both
+ * to write the block into `.git/info/exclude` and to strip a leftover block from
+ * a legacy tracked `.gitignore` (entries `[]` prunes).
  *
  * In-place replacement (not strip-then-append) is load-bearing: appending would
  * move this agent's block behind every other agent's block on each resync, so in
@@ -141,9 +182,11 @@ function applyManagedBlock(content, begin, end, entries) {
         if (entries.length > 0) {
             return [...lines.slice(0, bi), begin, ...entries, end, ...lines.slice(ei + 1)].join('\n');
         }
-        // Prune the block, tidying the blank lines that hugged it. Vestigial on the
-        // reconcileProjectGitignore path (its entries always include the manifest,
-        // so entries.length is never 0 there) — kept for a direct caller/unit test.
+        // Prune the block, tidying the blank lines that hugged it. Unreached on the
+        // reconcileManagedIgnore write path (its entries always include the manifest,
+        // so entries.length is never 0 there), but the load-bearing case for
+        // stripLegacyManagedGitignoreBlock, which calls with entries=[] to migrate a
+        // leftover block out of the tracked .gitignore.
         const before = lines.slice(0, bi);
         const after = lines.slice(ei + 1);
         while (before.length && before[before.length - 1].trim() === '')
@@ -160,30 +203,42 @@ function applyManagedBlock(content, begin, end, entries) {
     return body.length > 0 ? `${body}\n\n${block}\n` : `${block}\n`;
 }
 /**
- * Reconcile a per-agent managed block in `<projectRoot>/.gitignore` so the
- * generated per-harness resource dir never shows as untracked dirt. Idempotent
- * and convergent: replaces the block in place and writes only when the content
- * actually changes, so the launch hot path does not churn the file (or its
- * watchers) every run — even in a project synced by several harnesses. When a
- * sync clears a harness's resources the block does not vanish: it shrinks to the
- * lone `.agents-managed.json` entry (that file still sits in the harness dir and
- * must stay ignored), so the block is only ever fully pruned by hand, never via
- * this call path. Never creates a `.gitignore` outside a git working tree.
+ * Reconcile a per-agent managed block in `.git/info/exclude` so the generated
+ * per-harness resource dir never shows as untracked dirt — WITHOUT dirtying the
+ * tracked `.gitignore`. Idempotent and convergent: replaces the block in place
+ * and writes only when the content actually changes, so the launch hot path does
+ * not churn the file (or its watchers) every run — even in a project synced by
+ * several harnesses. When a sync clears a harness's resources the block does not
+ * vanish: it shrinks to the lone `.agents-managed.json` entry (that file still
+ * sits in the harness dir and must stay ignored), so the block is only ever
+ * fully pruned by hand, never via this call path. Fails open (no-op) outside a
+ * git working tree.
+ *
+ * Also self-heals repos dirtied by the previous behavior: PHNX-3717 wrote these
+ * blocks into `<projectRoot>/.gitignore`, which is never committed upstream, so
+ * every launch left a permanent `M .gitignore` that blocked `git pull`
+ * (PHNX-3718). `stripLegacyManagedGitignoreBlock` removes this agent's leftover
+ * block from that tracked file on the next launch, cleaning the diff instead of
+ * stranding it.
  */
-function reconcileProjectGitignore(projectRoot, agent, agentRoot, managed) {
-    const gitignorePath = path.join(projectRoot, '.gitignore');
-    if (!isInsideGitRepo(projectRoot) && !pathExists(gitignorePath))
-        return;
+function reconcileManagedIgnore(projectRoot, agent, agentRoot, managed) {
+    // Migrate away from the old tracked-.gitignore location first, so an already
+    // dirtied repo cleans itself even if git resolution below fails.
+    stripLegacyManagedGitignoreBlock(projectRoot, agent);
+    const target = resolveGitExcludeTarget(projectRoot);
+    if (!target)
+        return; // not a git repo — fail open
     const { begin, end } = gitignoreMarkers(agent);
     // Ignore the manifest marker file too, not just the synced resources: the
     // sync always writes `<agentRoot>/.agents-managed.json`, so without this the
     // harness dir still shows as untracked in `git status` on the strength of that
     // one file (defeating the whole point). It lives at agentRoot, so it resolves
-    // through the same anchoring + escape guard as any managed path.
-    const entries = managedGitignoreEntries(agentRoot, projectRoot, [MANIFEST_FILE, ...managed]);
+    // through the same anchoring + escape guard as any managed path. Anchored to
+    // the worktree root, since info/exclude patterns resolve against the tree top.
+    const entries = managedGitignoreEntries(agentRoot, target.worktreeRoot, [MANIFEST_FILE, ...managed]);
     let original = '';
     try {
-        original = fs.readFileSync(gitignorePath, 'utf-8');
+        original = fs.readFileSync(target.excludePath, 'utf-8');
     }
     catch {
         original = '';
@@ -191,8 +246,42 @@ function reconcileProjectGitignore(projectRoot, agent, agentRoot, managed) {
     const next = applyManagedBlock(original, begin, end, entries);
     if (next === null || next === original)
         return;
-    const tmp = gitignorePath + '.tmp';
+    fs.mkdirSync(path.dirname(target.excludePath), { recursive: true }); // create info/ if missing
+    const tmp = target.excludePath + '.tmp';
     fs.writeFileSync(tmp, next);
+    fs.renameSync(tmp, target.excludePath);
+}
+/**
+ * Remove this agent's leftover managed block from a tracked `<projectRoot>/
+ * .gitignore` written by the pre-PHNX-3718 behavior. Strips ONLY the fenced
+ * block (leaving every hand-written rule untouched), never creates the file,
+ * and never touches a `.gitignore` that carries no block of ours. If stripping
+ * empties a file we created (its only content was our block), the empty file is
+ * removed when git does not track it — an empty untracked `.gitignore` would
+ * still read as `?? .gitignore` dirt, the very thing this migration clears.
+ */
+function stripLegacyManagedGitignoreBlock(projectRoot, agent) {
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    let original;
+    try {
+        original = fs.readFileSync(gitignorePath, 'utf-8');
+    }
+    catch {
+        return; // no .gitignore — nothing to migrate
+    }
+    const { begin, end } = gitignoreMarkers(agent);
+    // Empty entries → applyManagedBlock prunes the block; returns `original`
+    // unchanged when there is no block, or null on an orphaned begin marker
+    // (which we refuse to touch rather than truncate the user's rules).
+    const stripped = applyManagedBlock(original, begin, end, []);
+    if (stripped === null || stripped === original)
+        return;
+    if (stripped === '' && !isTrackedByGit(projectRoot, gitignorePath)) {
+        removePath(gitignorePath);
+        return;
+    }
+    const tmp = gitignorePath + '.tmp';
+    fs.writeFileSync(tmp, stripped);
     fs.renameSync(tmp, gitignorePath);
 }
 function removeManagedPath(agentRoot, rel) {

package/dist/lib/rush-session.d.ts

@@ -2,8 +2,16 @@
  * Rush session freshness — the ONE judgment shared by every consumer of
  * ~/.rush/user.yaml (cloud dispatch, cloud session source, secrets sync driver).
  *
- * A Rush session stores `expires_at` as Unix seconds. Two values mean "never
- * expires" and MUST NOT be read as an absolute timestamp:
+ * A Rush session stores `expires_at` as Unix MILLISECONDS — the same unit
+ * rush/cli writes and reads it in (`sessionTokenFresh` in auth_reader.go compares
+ * against `time.Now()...UnixMilli()`), and the same unit the JWT `exp` claim maps
+ * to (`exp * 1000`). So freshness must compare it against `Date.now()` (ms), NOT
+ * `Date.now() / 1000` (seconds). Comparing ms against seconds was PHNX-3805: a
+ * long-expired session (e.g. `expires_at: 1788157222000`) read as `1.788e12 <=
+ * 1.788e9` → always false → never expired, so `agents cloud providers` reported
+ * Rush `available: true` on a dead session and every dispatch failed with a 401.
+ *
+ * Two values mean "never expires" and MUST NOT be read as an absolute timestamp:
  *   - `0`         — an opaque Phoenix `pid_` bearer written by `rush login`;
  *                   `0` = non-expiring by contract (mirrors rush/cli's isFresh,
  *                   the same fix RUSH-1310 landed for the daemon-less freshness

package/dist/lib/rush-session.js

@@ -2,8 +2,16 @@
  * Rush session freshness — the ONE judgment shared by every consumer of
  * ~/.rush/user.yaml (cloud dispatch, cloud session source, secrets sync driver).
  *
- * A Rush session stores `expires_at` as Unix seconds. Two values mean "never
- * expires" and MUST NOT be read as an absolute timestamp:
+ * A Rush session stores `expires_at` as Unix MILLISECONDS — the same unit
+ * rush/cli writes and reads it in (`sessionTokenFresh` in auth_reader.go compares
+ * against `time.Now()...UnixMilli()`), and the same unit the JWT `exp` claim maps
+ * to (`exp * 1000`). So freshness must compare it against `Date.now()` (ms), NOT
+ * `Date.now() / 1000` (seconds). Comparing ms against seconds was PHNX-3805: a
+ * long-expired session (e.g. `expires_at: 1788157222000`) read as `1.788e12 <=
+ * 1.788e9` → always false → never expired, so `agents cloud providers` reported
+ * Rush `available: true` on a dead session and every dispatch failed with a 401.
+ *
+ * Two values mean "never expires" and MUST NOT be read as an absolute timestamp:
  *   - `0`         — an opaque Phoenix `pid_` bearer written by `rush login`;
  *                   `0` = non-expiring by contract (mirrors rush/cli's isFresh,
  *                   the same fix RUSH-1310 landed for the daemon-less freshness
@@ -20,5 +28,6 @@ export function isRushSessionExpired(expiresAt) {
     // `0` (non-expiring pid_ bearer) and a missing value are never expired.
     if (typeof expiresAt !== 'number' || expiresAt === 0)
         return false;
-    return expiresAt <= Date.now() / 1000;
+    // expires_at is Unix milliseconds — compare ms to ms.
+    return expiresAt <= Date.now();
 }

package/dist/lib/secrets/drivers/rush.js

@@ -29,7 +29,7 @@ function readRushToken() {
     }
     const expiresAt = data.session?.expires_at;
     if (isRushSessionExpired(expiresAt)) {
-        const expiredAt = new Date(expiresAt * 1000).toISOString();
+        const expiredAt = new Date(expiresAt).toISOString();
         throw new Error(`Rush session expired at ${expiredAt}. Run \`rush login\` to refresh.`);
     }
     return token;

package/dist/lib/session/cloud.js

@@ -32,7 +32,7 @@ function readToken() {
     }
     const expiresAt = data.session?.expires_at;
     if (isRushSessionExpired(expiresAt)) {
-        const expiredAt = new Date(expiresAt * 1000).toISOString();
+        const expiredAt = new Date(expiresAt).toISOString();
         throw new Error(`Rush session expired at ${expiredAt}. Run \`rush login\` to refresh.`);
     }
     return token;

package/dist/lib/session/live-metadata.d.ts

@@ -13,3 +13,27 @@ export declare function activeSessionToSessionMeta(active: ActiveSession, self:
  * (no id, non-agent kind) are dropped. Order follows the input.
  */
 export declare function liveSessionMetas(active: ActiveSession[], self: string, nowMs: number): SessionMeta[];
+/**
+ * Which box the AGENT of each live session executes on, keyed by lowercased id,
+ * as recovered from the fleet-active snapshot (`agents sessions --active`'s
+ * cross-machine merge). A dispatcher that launched a session running on a peer
+ * has a live shim row locally whose `machine` self-defaulted to itself — the
+ * launch process IS here, the agent is not (PHNX-3890). The fleet snapshot
+ * already reconciled that against the peer's own self-report, so it is the one
+ * place that knows the true execution host without a synced index row (which is
+ * why `foldExecutionMachine` can't recover it: there is no local index row to
+ * join). Only rows the fleet attributes to a real machine are included.
+ */
+export declare function fleetExecutionMachineById(fleet: ActiveSession[]): Map<string, string>;
+/**
+ * Correct a live `SessionMeta` candidate's machine to its true EXECUTION host
+ * using the fleet-active attribution (PHNX-3890). Only a **self-attributed,
+ * transcript-less** row is a candidate for correction — the launcher-shim shape
+ * a dispatcher holds for a session whose agent runs on a peer, which is
+ * indistinguishable from a genuinely-local just-started session by its local
+ * fields alone. A row already attributed to another box, or one carrying a
+ * transcript path, is left untouched. A corrected row is stamped `_remote` so
+ * the read-vs-resume router (`transcriptOnPeerOf`) sends the preview to the
+ * owning peer instead of dead-ending on the local "not indexed here" stub.
+ */
+export declare function reconcileLiveMetaMachine(metas: SessionMeta[], fleetExecutionMachine: Map<string, string>, self: string): SessionMeta[];

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

@@ -76,3 +76,58 @@ export function liveSessionMetas(active, self, nowMs) {
     }
     return out;
 }
+/**
+ * Which box the AGENT of each live session executes on, keyed by lowercased id,
+ * as recovered from the fleet-active snapshot (`agents sessions --active`'s
+ * cross-machine merge). A dispatcher that launched a session running on a peer
+ * has a live shim row locally whose `machine` self-defaulted to itself — the
+ * launch process IS here, the agent is not (PHNX-3890). The fleet snapshot
+ * already reconciled that against the peer's own self-report, so it is the one
+ * place that knows the true execution host without a synced index row (which is
+ * why `foldExecutionMachine` can't recover it: there is no local index row to
+ * join). Only rows the fleet attributes to a real machine are included.
+ */
+export function fleetExecutionMachineById(fleet) {
+    const byId = new Map();
+    for (const s of fleet) {
+        // The AGENT machine is `machine` (where the transcript/harness lives), NOT
+        // `offloadedFrom` (where the launcher shim runs) — reading follows the
+        // transcript owner, so a would-be reader must reach `machine`.
+        if (!s.sessionId || !s.machine)
+            continue;
+        byId.set(s.sessionId.toLowerCase(), s.machine);
+    }
+    return byId;
+}
+/**
+ * Correct a live `SessionMeta` candidate's machine to its true EXECUTION host
+ * using the fleet-active attribution (PHNX-3890). Only a **self-attributed,
+ * transcript-less** row is a candidate for correction — the launcher-shim shape
+ * a dispatcher holds for a session whose agent runs on a peer, which is
+ * indistinguishable from a genuinely-local just-started session by its local
+ * fields alone. A row already attributed to another box, or one carrying a
+ * transcript path, is left untouched. A corrected row is stamped `_remote` so
+ * the read-vs-resume router (`transcriptOnPeerOf`) sends the preview to the
+ * owning peer instead of dead-ending on the local "not indexed here" stub.
+ */
+export function reconcileLiveMetaMachine(metas, fleetExecutionMachine, self) {
+    return metas.map(meta => {
+        // Already attributed elsewhere, or locally readable — not a self-default.
+        if (meta.machine && meta.machine !== self)
+            return meta;
+        if (meta.filePath)
+            return meta;
+        const exec = fleetExecutionMachine.get(meta.id.toLowerCase());
+        // Only a PEER attribution is positive information. A snapshot entry that
+        // names THIS box cannot be trusted as confirmation, because the snapshot is
+        // a merge that INCLUDES this box's own rows — so for exactly the session
+        // shape being corrected here (no index row to fold from), a `self` entry may
+        // be nothing but an echo of the self-default above, recorded while the
+        // owning peer had not reported yet or was unreachable during that gather.
+        // Treating it as proof would skip the fan-out and dead-end on the local stub
+        // for a session genuinely running elsewhere — the PHNX-3890 bug itself.
+        if (!exec || exec === self)
+            return meta;
+        return { ...meta, machine: exec, _remote: true };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.73",
+  "version": "1.22.74",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",