@phnx-labs/agents-cli 1.22.66 → 1.22.69

package/dist/lib/session/linear.js

@@ -16,6 +16,50 @@ import os from 'node:os';
 import path from 'node:path';
 /** A Linear tracker key: `TEAM-N`, e.g. `RUSH-1234`. Mirrors the detector's shape. */
 const LINEAR_KEY_RE = /^[A-Z]{2,6}-\d{1,6}$/;
+/**
+ * The same key, matched inside free text on word boundaries. Uppercase-only team
+ * key (2–6 letters) so a lowercase `utf-8` can't masquerade as a ticket. Global
+ * so {@link linearIssueKeys} can pull every mention out of a body.
+ */
+const LINEAR_KEY_IN_TEXT_RE = /\b([A-Z]{2,6}-\d{1,6})\b/g;
+/**
+ * Team prefixes that match the key shape but are not trackers — unit strings and
+ * common acronyms. Canonical here (the Linear module) so both the URL linkifier
+ * and the session-transcript ticket detector (`detectTicket` in `state.ts`) agree
+ * on what is a real key rather than each keeping its own copy.
+ */
+export const LINEAR_KEY_DENYLIST = new Set([
+    'UTF',
+    'SHA',
+    'ISO',
+    'RFC',
+    'IPV',
+    'X86',
+    'ARM',
+    'MP',
+    'H',
+]);
+/**
+ * Every distinct real Linear key mentioned in free text, in first-seen order.
+ * Honours {@link LINEAR_KEY_DENYLIST} so `UTF-8` / `X86-64` never count. Used to
+ * linkify ticket ids an owner ping only names in prose (no `session.ticketId`).
+ */
+export function linearIssueKeys(text) {
+    if (!text)
+        return [];
+    const seen = new Set();
+    const keys = [];
+    for (const m of text.matchAll(LINEAR_KEY_IN_TEXT_RE)) {
+        const key = m[1];
+        if (LINEAR_KEY_DENYLIST.has(key.split('-')[0]))
+            continue;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        keys.push(key);
+    }
+    return keys;
+}
 // `undefined` = not yet resolved; `null` = resolved-but-unknown (skip re-reading).
 let workspaceCache;
 /** The configured Linear workspace slug, or undefined when unknown. Cached per process. */

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

@@ -49,6 +49,7 @@ export function activeSessionToSessionMeta(active, self, nowMs) {
         project: active.project ?? undefined,
         label: active.label,
         topic: active.topic,
+        firstUserMessage: active.firstUserMessage,
         version: active.version,
         messageCount: undefined,
         machine: active.machine ?? self,

package/dist/lib/session/parse.js

@@ -10,7 +10,7 @@ import { truncate } from '../format.js';
 import { sanitizeForTerminal } from '../redact.js';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { isSyntheticUserMessage, extractSlashCommandName, extractSlashCommandFromToolInput } from './prompt.js';
+import { isSyntheticUserMessage, extractSlashCommandName, extractSlashCommandFromToolInput, unwrapUserQuery } from './prompt.js';
 import { structuredToolResult, commandsFromCodexExec } from './tool-calls.js';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
@@ -1989,9 +1989,8 @@ export function parseCursor(filePath) {
  * differs from the one that wrote the transcript.
  */
 function parseCursorUserText(text) {
-    const query = text.match(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/);
     const stamp = text.match(/<timestamp>\s*([\s\S]*?)\s*<\/timestamp>/)?.[1]?.trim();
-    return { text: (query?.[1] ?? text).trim(), timestamp: parseCursorTimestamp(stamp) };
+    return { text: unwrapUserQuery(text), timestamp: parseCursorTimestamp(stamp) };
 }
 function parseCursorTimestamp(stamp) {
     if (!stamp)

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

@@ -5,6 +5,7 @@
  * wrapper tags, team-spawn boilerplate) so that only the real user intent
  * remains. Used by the session picker to show a human-readable topic line.
  */
+import type { SessionEvent } from './types.js';
 /**
  * True when a `role=user` message is harness-injected scaffolding, not a genuine
  * user turn. Text-based so it is cross-harness by construction (the markers are
@@ -12,6 +13,22 @@
  * own scaffolding at parse time simply never reach here.
  */
 export declare function isSyntheticUserMessage(raw: string | undefined): boolean;
+/**
+ * Inner text of a `<user_query>` wrapper, or the original string if none.
+ * Same extraction Cursor already applies in `parseCursorUserText`.
+ */
+export declare function unwrapUserQuery(text: string): string;
+/**
+ * Return one genuine user turn in full.
+ * Synthetic scaffolding is rejected as a whole so an injected Apps/AGENTS
+ * preamble can never become the session's displayed request. Unlike the topic
+ * cleaner, this intentionally preserves internal whitespace and every line of
+ * the user's actual request. A Grok/Cursor `<user_query>` wrapper is unwrapped
+ * so the stored turn is the originating request, not the harness tags.
+ */
+export declare function cleanFirstUserMessage(raw: string | undefined): string | undefined;
+/** First genuine user message from an already-normalized event stream. */
+export declare function firstUserMessageFromEvents(events: SessionEvent[]): string | undefined;
 /**
  * Extract the invoked slash-command name from a raw `role=user` message, or
  * undefined when the message carries no `<command-name>` wrapper. Used by

package/dist/lib/session/prompt.js

@@ -47,7 +47,9 @@ const SYNTHETIC_USER_MESSAGE_PATTERNS = [
     /^\s*<\/?persisted-output>/i,
     /^\s*<permissions instructions>/i,
     /^\s*<(?:apps|plugins|skills)_instructions>/i,
+    /^\s*<recommended_plugins>/i,
     /^\s*<(?:multi_agent_mode|environment_context)>/i,
+    /^\s*<user_info>/i,
     /^\s*## (?:In-flight in this repo|Host & Fleet)/i,
     /^\s*Your current session id is\b/i,
     /^\s*Linear context skipped:/i,
@@ -68,6 +70,39 @@ export function isSyntheticUserMessage(raw) {
         return false;
     return SYNTHETIC_USER_MESSAGE_PATTERNS.some(pattern => pattern.test(raw));
 }
+/**
+ * Inner text of a `<user_query>` wrapper, or the original string if none.
+ * Same extraction Cursor already applies in `parseCursorUserText`.
+ */
+export function unwrapUserQuery(text) {
+    const query = text.match(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/);
+    return (query?.[1] ?? text).trim();
+}
+/**
+ * Return one genuine user turn in full.
+ * Synthetic scaffolding is rejected as a whole so an injected Apps/AGENTS
+ * preamble can never become the session's displayed request. Unlike the topic
+ * cleaner, this intentionally preserves internal whitespace and every line of
+ * the user's actual request. A Grok/Cursor `<user_query>` wrapper is unwrapped
+ * so the stored turn is the originating request, not the harness tags.
+ */
+export function cleanFirstUserMessage(raw) {
+    if (!raw || isSyntheticUserMessage(raw))
+        return undefined;
+    const clean = unwrapUserQuery(raw);
+    return clean || undefined;
+}
+/** First genuine user message from an already-normalized event stream. */
+export function firstUserMessageFromEvents(events) {
+    for (const event of events) {
+        if (event.type !== 'message' || event.role !== 'user' || event._synthetic)
+            continue;
+        const first = cleanFirstUserMessage(event.content);
+        if (first)
+            return first;
+    }
+    return undefined;
+}
 /**
  * The `<command-name>` wrapper Claude injects into a `role=user` message when
  * a typed slash command is invoked, e.g.:

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

@@ -1,16 +1,39 @@
 import { type RotateCandidate } from '../accounting/rotate.js';
 import type { AgentId } from '../types.js';
-import type { SessionMeta } from './types.js';
+import type { SessionAgentId, SessionMeta } from './types.js';
+/** One capability boundary for every surface that advertises faithful Resume. */
+export declare function sessionAgentSupportsResume(agent: SessionAgentId): boolean;
+/**
+ * The account a recovery should authenticate as. Present when resume rotates
+ * AWAY from the session's original login (an account limit) to a healthy
+ * sibling of the SAME harness. A `providerAccount` is a durable setup-token /
+ * API-key account (RUSH-3182) injected via the `--account` spawn path
+ * (`resolveSpawnAccount` → `accountEnv`); it is the only kind that can
+ * authenticate a NATIVE resume in the origin version home, because a native
+ * login lives in its own isolated home and cannot be forwarded. It is also
+ * required on `/continue` when the balanced pick is a provider: exec only
+ * injects from this field, so omitting it would launch the version home's
+ * native login — the exhausted origin in the PHNX-3674 fixture. Absent means
+ * "use the launched version home's own native login" (the healthy-origin happy
+ * path, or `/continue` on a healthy native sibling).
+ */
+export interface RecoveryAccount {
+    providerAccount: string;
+    label: string;
+    email: string | null;
+}
 export type SessionRecoveryTarget = {
     mode: 'native';
     agent: AgentId;
     version: string;
     cwd?: string;
+    account?: RecoveryAccount;
     reason: string;
 } | {
     mode: 'continue';
     agent: AgentId;
     version: string;
+    account?: RecoveryAccount;
     reason: string;
 };
 export type NativeResumeInspection = {
@@ -40,13 +63,27 @@ export declare function inspectNativeResumeSession(session: SessionMeta, version
 /**
  * Decide how a durable session resumes on the device that owns it.
  *
- * Native resume is legal only in the exact origin version's isolated home and
- * only while that account is healthy. Every other successful path stays on the
- * same harness and uses `/continue`, whose indexed transcript reader can reach
- * retained version trash. No healthy same-harness account is a loud failure.
+ * Native resume is legal only in the exact origin version's isolated home,
+ * and only while that home owns the indexed transcript AND some injectable
+ * credential for this harness is healthy: the origin login itself, or a
+ * provider account rotated in when the origin is usage-limited (PHNX-3626).
+ * Every other successful path stays on the same harness and uses `/continue`,
+ * whose indexed transcript reader can reach retained version trash. A
+ * `/continue` pick of a provider account carries RecoveryAccount so exec
+ * injects it instead of launching the version home's native login
+ * (PHNX-3674). No healthy same-harness account is a loud failure.
  */
 export declare function resolveSessionRecoveryFromCandidates(session: SessionMeta, candidates: RotateCandidate[], supportsNative?: (agent: AgentId, version?: string) => boolean, nativeInspection?: NativeResumeInspection): SessionRecoveryTarget;
-export declare function resolveSessionRecovery(session: SessionMeta): Promise<SessionRecoveryTarget>;
+/**
+ * Resolve recovery for a durable session, reading the live account pool.
+ *
+ * Uses {@link collectRunCandidatesForRun} (native version-home logins PLUS
+ * durable provider accounts, RUSH-3182) rather than the native-only
+ * {@link collectRunCandidates}, so an origin-account limit can rotate to a
+ * healthy provider account and stay NATIVE (PHNX-3626). `collect` is injectable
+ * for tests and for callers that must stay native-only.
+ */
+export declare function resolveSessionRecovery(session: SessionMeta, collect?: (agent: AgentId) => Promise<RotateCandidate[]>): Promise<SessionRecoveryTarget>;
 /** Stable self-command used by focus, resume, and attach. The owning device runs
  * the recovery resolver above; callers must not native-resume another version's
  * isolated home themselves. */

package/dist/lib/session/recovery.js

@@ -4,8 +4,14 @@ import { AGENTS, agentConfigDirName } from '../agents.js';
 import { isSelfHost } from '../devices/self-host.js';
 import { nativeResume } from '../exec.js';
 import { machineId, normalizeHost } from '../machine-id.js';
-import { collectRunCandidates, formatNoHealthyAccountError, pickBalancedCandidate, readinessFromCandidate, } from '../accounting/rotate.js';
+import { formatNoHealthyAccountError, pickBalancedCandidate, readinessFromCandidate, } from '../accounting/rotate.js';
+import { collectRunCandidatesForRun } from '../accounting/account-pool-collect.js';
 import { getVersionHomePath } from '../installations/store.js';
+const RESUMABLE_SESSION_AGENTS = new Set(['claude', 'codex', 'muse', 'opencode']);
+/** One capability boundary for every surface that advertises faithful Resume. */
+export function sessionAgentSupportsResume(agent) {
+    return RESUMABLE_SESSION_AGENTS.has(agent);
+}
 export class SessionRecoveryError extends Error {
     constructor(message) {
         super(message);
@@ -44,6 +50,16 @@ function sourceReason(session, candidates) {
         ? `origin ${session.agent}@${session.version} has no native resume form`
         : `origin ${session.agent}@${session.version} is ${readiness.reason}`;
 }
+function recoveryAccountFromCandidate(candidate) {
+    const providerAccount = candidate.providerAccount;
+    if (!providerAccount)
+        return undefined;
+    return {
+        providerAccount,
+        label: candidate.accountLabel || providerAccount,
+        email: candidate.email,
+    };
+}
 function isPathInside(candidate, dir) {
     const rel = path.relative(dir, candidate);
     return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
@@ -140,10 +156,15 @@ export function inspectNativeResumeSession(session, versionHome) {
 /**
  * Decide how a durable session resumes on the device that owns it.
  *
- * Native resume is legal only in the exact origin version's isolated home and
- * only while that account is healthy. Every other successful path stays on the
- * same harness and uses `/continue`, whose indexed transcript reader can reach
- * retained version trash. No healthy same-harness account is a loud failure.
+ * Native resume is legal only in the exact origin version's isolated home,
+ * and only while that home owns the indexed transcript AND some injectable
+ * credential for this harness is healthy: the origin login itself, or a
+ * provider account rotated in when the origin is usage-limited (PHNX-3626).
+ * Every other successful path stays on the same harness and uses `/continue`,
+ * whose indexed transcript reader can reach retained version trash. A
+ * `/continue` pick of a provider account carries RecoveryAccount so exec
+ * injects it instead of launching the version home's native login
+ * (PHNX-3674). No healthy same-harness account is a loud failure.
  */
 export function resolveSessionRecoveryFromCandidates(session, candidates, supportsNative = nativeResume, nativeInspection) {
     const agent = runnableSessionAgent(session);
@@ -152,6 +173,38 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
         ? candidates.find((candidate) => candidate.version === session.version)
         : undefined;
     const sourceReady = source ? readinessFromCandidate(source).ready : false;
+    // Native-first with account rotation (PHNX-3626). When the origin login is
+    // usage/rate/session-LIMITED (not signed-out or revoked — those need a login,
+    // not a rotation, so they keep going to /continue per SES-39) but its version
+    // home is installed, native-resume-capable, and still owns the indexed
+    // transcript, keep resume NATIVE by rotating to a healthy INJECTABLE (provider)
+    // account in that SAME home — rather than dropping to /continue on a different
+    // version. Only a provider token/key qualifies: a native login lives in its own
+    // isolated home and cannot be forwarded, so it could never authenticate a
+    // resume that must read the origin home's transcript (see §11).
+    const originReadiness = source ? readinessFromCandidate(source) : null;
+    const originLimited = !!originReadiness && !originReadiness.ready
+        && (originReadiness.reason === 'rate_limited' || originReadiness.reason === 'out_of_credits');
+    if (originLimited && source && session.version && supportsNative(agent, session.version)) {
+        const inspection = nativeInspection
+            ?? inspectNativeResumeSession(session, getVersionHomePath(agent, session.version));
+        if (inspection.available) {
+            const rotated = pickBalancedCandidate(candidates.filter((c) => c.providerAccount && c.accountKey !== source.accountKey));
+            const account = rotated ? recoveryAccountFromCandidate(rotated.picked) : undefined;
+            if (account) {
+                // `originLimited` guarantees the origin is unhealthy with a limit reason.
+                const why = originReadiness.ready ? 'limited' : originReadiness.reason;
+                return {
+                    mode: 'native',
+                    agent,
+                    version: session.version,
+                    cwd: inspection.cwd,
+                    account,
+                    reason: `origin ${agent}@${session.version} account is ${why}; rotated to healthy ${account.label} and resuming natively in the same home`,
+                };
+            }
+        }
+    }
     // An exact healthy origin is deterministic: preserve its isolated home. If
     // native resume is unavailable for that harness, /continue still launches in
     // that same healthy home. Only an unusable/missing origin enters balanced
@@ -164,7 +217,13 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
         throw new SessionRecoveryError(`Cannot recover session ${session.shortId} on ${device}; origin ${agent}@${session.version ?? 'unknown'}. ${detail}`);
     }
     const version = selection.picked.version;
-    if (session.version === version && supportsNative(agent, version)) {
+    const account = recoveryAccountFromCandidate(selection.picked);
+    const continueWith = account ? `healthy ${account.label}` : `healthy ${agent}@${version}`;
+    // Native resume without an injected RecoveryAccount is valid only for the
+    // exact healthy origin login. A balanced same-version provider selected for
+    // a signed-out/revoked origin must stay on /continue; otherwise we would open
+    // the origin home with no usable credential and fail (or fork state).
+    if (sourceReady && session.version === version && supportsNative(agent, version)) {
         const inspection = nativeInspection
             ?? inspectNativeResumeSession(session, getVersionHomePath(agent, version));
         if (inspection.available) {
@@ -180,19 +239,30 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
             mode: 'continue',
             agent,
             version,
-            reason: `${inspection.reason}; continuing with healthy ${agent}@${version}`,
+            ...(account ? { account } : {}),
+            reason: `${inspection.reason}; continuing with ${continueWith}`,
         };
     }
     return {
         mode: 'continue',
         agent,
         version,
-        reason: `${sourceReason(session, candidates)}; continuing with healthy ${agent}@${version}`,
+        ...(account ? { account } : {}),
+        reason: `${sourceReason(session, candidates)}; continuing with ${continueWith}`,
     };
 }
-export async function resolveSessionRecovery(session) {
+/**
+ * Resolve recovery for a durable session, reading the live account pool.
+ *
+ * Uses {@link collectRunCandidatesForRun} (native version-home logins PLUS
+ * durable provider accounts, RUSH-3182) rather than the native-only
+ * {@link collectRunCandidates}, so an origin-account limit can rotate to a
+ * healthy provider account and stay NATIVE (PHNX-3626). `collect` is injectable
+ * for tests and for callers that must stay native-only.
+ */
+export async function resolveSessionRecovery(session, collect = collectRunCandidatesForRun) {
     const agent = runnableSessionAgent(session);
-    return resolveSessionRecoveryFromCandidates(session, await collectRunCandidates(agent));
+    return resolveSessionRecoveryFromCandidates(session, await collect(agent));
 }
 /** Stable self-command used by focus, resume, and attach. The owning device runs
  * the recovery resolver above; callers must not native-resume another version's

package/dist/lib/session/remote/remote-list.d.ts

@@ -145,7 +145,23 @@ export declare function fetchPeerPreviewDigest(sessionId: string, machine: strin
  * `opts.sessionId` (with `tty`) prints the session id and resume command when
  * the SSH hop ends, so OpenSSH's `Shared connection … closed.` is not the last
  * thing on the local shell (RUSH-3227). Omit it for one-shot non-TTY renders.
+ *
+ * Resolves `'unreachable'` when the SSH connection itself failed — ssh could not
+ * launch (spawn error) or exited with {@link SSH_CONN_FAILURE_CODE} (255, its
+ * connect-failure convention) — as opposed to `'ok'` for a hop that actually
+ * reached the peer (whatever the remote command's own exit code). This lets a
+ * caller prefer the recorded device yet fall back locally when it is genuinely
+ * offline (PHNX-3626); callers that ignore `'unreachable'` behave exactly as
+ * before (it was `'ok'`).
+ */
+/**
+ * Classify a finished SSH hop by its exit code: `'unreachable'` when the
+ * connection itself failed (ssh's {@link SSH_CONN_FAILURE_CODE} = 255, or a null
+ * code from a killed/never-launched child), else `'ok'` — the remote command ran,
+ * whatever its own exit status. Pure so the offline-device fallback is unit-tested
+ * without a live SSH hop (PHNX-3626).
  */
+export declare function peerHopOutcome(code: number | null): 'ok' | 'unreachable';
 export declare function peerHopCloseNotice(opts: {
     tty?: boolean;
     sessionId?: string;
@@ -154,4 +170,4 @@ export declare function runOnPeer(args: string[], machine: string, opts?: {
     tty?: boolean;
     env?: Record<string, string>;
     sessionId?: string;
-}): Promise<'ok' | 'no-target'>;
+}): Promise<'ok' | 'no-target' | 'unreachable'>;

package/dist/lib/session/remote/remote-list.js

@@ -582,7 +582,25 @@ export async function fetchPeerPreviewDigest(sessionId, machine, timeoutMs = PEE
  * `opts.sessionId` (with `tty`) prints the session id and resume command when
  * the SSH hop ends, so OpenSSH's `Shared connection … closed.` is not the last
  * thing on the local shell (RUSH-3227). Omit it for one-shot non-TTY renders.
+ *
+ * Resolves `'unreachable'` when the SSH connection itself failed — ssh could not
+ * launch (spawn error) or exited with {@link SSH_CONN_FAILURE_CODE} (255, its
+ * connect-failure convention) — as opposed to `'ok'` for a hop that actually
+ * reached the peer (whatever the remote command's own exit code). This lets a
+ * caller prefer the recorded device yet fall back locally when it is genuinely
+ * offline (PHNX-3626); callers that ignore `'unreachable'` behave exactly as
+ * before (it was `'ok'`).
+ */
+/**
+ * Classify a finished SSH hop by its exit code: `'unreachable'` when the
+ * connection itself failed (ssh's {@link SSH_CONN_FAILURE_CODE} = 255, or a null
+ * code from a killed/never-launched child), else `'ok'` — the remote command ran,
+ * whatever its own exit status. Pure so the offline-device fallback is unit-tested
+ * without a live SSH hop (PHNX-3626).
  */
+export function peerHopOutcome(code) {
+    return code === SSH_CONN_FAILURE_CODE || code === null ? 'unreachable' : 'ok';
+}
 export function peerHopCloseNotice(opts, machine, code) {
     if (!opts.tty || !opts.sessionId)
         return undefined;
@@ -596,9 +614,13 @@ export async function runOnPeer(args, machine, opts = {}) {
     const cols = terminalWidth();
     const env = { ...(cols > 0 ? { COLUMNS: String(cols) } : {}), ...opts.env };
     const assignments = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`);
+    const invocation = assignments.concat(['agents', ...args].map(shellQuote)).join(' ');
+    // OpenSSH uses 255 for transport failure, but also propagates a reached remote
+    // program's 255 verbatim. Remap only the remote program's 255 inside the peer
+    // shell so the outer SSH status remains an unambiguous connectivity signal.
     const remoteCmd = remoteShellFor(peer.os) === 'powershell'
-        ? buildWindowsAgentsCommand({ args, env: assignments.length ? env : undefined })
-        : `bash -lc ${shellQuote(assignments.concat(['agents', ...args].map(shellQuote)).join(' '))}`;
+        ? buildWindowsAgentsCommand({ args, env: assignments.length ? env : undefined, remapExit255: true })
+        : `bash -lc ${shellQuote(`${invocation}; agents_rc=$?; if [ "$agents_rc" -eq 255 ]; then exit 254; fi; exit "$agents_rc"`)}`;
     const sshArgs = [...SSH_OPTS, ...controlOpts()];
     if (opts.tty)
         sshArgs.push('-tt'); // force a PTY so the resumed agent is interactive
@@ -610,7 +632,7 @@ export async function runOnPeer(args, machine, opts = {}) {
         // we resolve once it settles so the picker flow completes.
         child.on('error', (err) => {
             process.stderr.write(chalk.red(`Failed to reach ${machine}: ${err?.message ?? 'ssh failed to launch'}\n`));
-            resolve('ok');
+            resolve('unreachable');
         });
         child.on('close', (code) => {
             // Interactive TTY hop: OpenSSH prints "Shared connection … closed." and
@@ -618,7 +640,10 @@ export async function runOnPeer(args, machine, opts = {}) {
             const notice = peerHopCloseNotice(opts, machine, code);
             if (notice)
                 process.stderr.write(notice);
-            resolve('ok');
+            // ssh exits 255 only when the connection itself failed (host down/asleep),
+            // distinct from the remote command's own non-zero exit. Report that so a
+            // caller can fall back locally instead of silently completing.
+            resolve(peerHopOutcome(code));
         });
     });
 }

package/dist/lib/session/remote/watch.d.ts

@@ -1,7 +1,9 @@
 import { type ActiveSession } from '../active.js';
+import type { SessionMeta } from '../types.js';
 import { readActiveSessionsCache } from '../session-cache.js';
 export declare const SESSION_WATCH_VERSION: 1;
 export declare const SESSION_WATCH_HEARTBEAT_MS = 15000;
+export declare const SESSION_WATCH_PREVIOUS_LIMIT = 50;
 export type SessionWatchScopeStatus = 'available' | 'unavailable';
 export type SessionWatchEnvelope = {
     version: 1;
@@ -45,9 +47,15 @@ export type SessionWatchEnvelope = {
     scope: string;
     capturedAt: number;
 };
-export interface SessionWatchRow extends Omit<ActiveSession, 'viewingIn'> {
+export interface SessionWatchRow extends Omit<ActiveSession, 'viewingIn' | 'context'> {
+    context: ActiveSession['context'] | 'recent';
+    /** Flat durable branch for history rows that are not currently in a worktree. */
+    branch?: string;
     rowKey: string;
     sourceDevice: string;
+    /** Durable index rows are kept on the stream under a distinct identity so a
+     * live row can replace/disappear without erasing its recoverable history. */
+    previous: boolean;
     resumable: boolean;
     unwatched: boolean;
     viewingIn: string | null;
@@ -60,6 +68,13 @@ export interface SessionWatchRow extends Omit<ActiveSession, 'viewingIn'> {
 /** Stable, opaque identity for one row within one device scope. */
 export declare function sessionWatchRowKey(scope: string, row: ActiveSession): string;
 export declare function toSessionWatchRow(scope: string, row: ActiveSession): SessionWatchRow;
+/** Stable identity for a durable Previous row. It is deliberately distinct
+ * from the live row key for the same session id: both may coexist on the one
+ * stream, and the presentation layer lets the live row win while it exists. */
+export declare function previousSessionWatchRowKey(scope: string, sessionId: string): string;
+/** Project one durable indexed session into the same canonical watch contract
+ * as live sessions. This is the only history backfill consumed by AGI EXT. */
+export declare function toPreviousSessionWatchRow(scope: string, session: SessionMeta): SessionWatchRow;
 /** Stream-local sequencer and convergent row diff. */
 export declare class SessionWatchState {
     readonly streamId: string;
@@ -67,7 +82,10 @@ export declare class SessionWatchState {
     private readonly rows;
     constructor(streamId?: string);
     private base;
-    reset(scope: string, sourceRows: ActiveSession[]): SessionWatchEnvelope;
+    /** Keep one visible Previous row per session and the newest bounded window.
+     * Returns removed keys so delta callers can converge already-connected clients. */
+    private prunePrevious;
+    reset(scope: string, sourceRows: ActiveSession[], indexedRows?: SessionMeta[]): SessionWatchEnvelope;
     update(scope: string, sourceRows: ActiveSession[]): SessionWatchEnvelope[];
     patch(scope: string, upserts: ActiveSession[], removes: string[]): SessionWatchEnvelope[];
     scope(scope: string, status: SessionWatchScopeStatus, reason?: string): SessionWatchEnvelope;
@@ -80,9 +98,14 @@ export interface WatchLocalOptions {
     refreshMs?: number;
     heartbeatMs?: number;
     readCache?: typeof readActiveSessionsCache;
+    readPrevious?: (scope: string) => SessionMeta[];
     journalPath?: string;
     journalPollMs?: number;
 }
+/** One bounded index read when the watch starts. The stream then owns this
+ * projection: active rows update through the journal, and removals demote into
+ * Previous rows without another transcript/index poll. */
+export declare function readPreviousSessionsForWatch(scope: string): SessionMeta[];
 /**
  * Keep one local subscription alive. Startup reads one canonical reset snapshot;
  * steady state tails the canonical writer journal and never invokes a gather.