@phnx-labs/agents-cli 1.22.65 → 1.22.68

package/dist/lib/session/discover.js

@@ -26,7 +26,7 @@ import { getConfigSymlinkVersion } from '../installations/shims.js';
 import { SESSION_AGENTS } from './types.js';
 import { deriveShortId } from './short-id.js';
 import { buildClaudeAccountIndex, resolveClaudeAccount } from './claude-accounts.js';
-import { extractSessionTopic, extractSlashCommandName, extractSlashCommandFromToolInput, cleanGeneratedSessionLabel } from './prompt.js';
+import { cleanFirstUserMessage, extractSessionTopic, extractSlashCommandName, extractSlashCommandFromToolInput, cleanGeneratedSessionLabel } from './prompt.js';
 import { isBackgroundShellStart, isSkillInvocation, extractSkills, extractSlashCommands, isSubAgentTool } from './highlights.js';
 import { parseAntigravity, parseCursor, splitSessionFilePath } from './parse.js';
 import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand, detectSpawnedTeam, isTicketCreateTool, extractCreatedTicket, extractRecentDirectoriesTouched, extractTodoProgressFromEvents } from './state.js';
@@ -1200,6 +1200,7 @@ async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, label) {
             accountKey: acct.key,
             accountOrg: acct.orgName ?? undefined,
             topic: scan.topic,
+            firstUserMessage: scan.firstUserMessage,
             // The live sessions metadata file contains only user `/rename` values;
             // prefer it when present, then fall back to the title parsed from JSONL.
             label: label || scan.label,
@@ -1256,6 +1257,7 @@ async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, label) {
             costUsdNoCache: scan.costUsdNoCache,
             durationMs: scan.durationMs,
             topic: scan.topic,
+            firstUserMessage: scan.firstUserMessage,
             isTeamOrigin,
             prUrl: scan.prUrl,
             prNumber: scan.prNumber,
@@ -1565,6 +1567,7 @@ export async function readCodexMeta(filePath, resolveAccount, currentVersion, sc
         version: resolveSessionVersion('codex', filePath, scan.version, currentVersion),
         model: scan.model,
         topic: scan.topic,
+        firstUserMessage: scan.firstUserMessage,
         messageCount: scan.messageCount,
         tokenCount: scan.tokenCount,
         outputTokens: scan.outputTokens,
@@ -1804,6 +1807,7 @@ function readGeminiMeta(filePath, hashDir, projectMap, currentVersion) {
         version: resolveSessionVersion('gemini', filePath, embeddedVersion, currentVersion),
         model: sessionModel,
         topic,
+        firstUserMessage: userTexts.map(cleanFirstUserMessage).find((text) => !!text),
         messageCount,
         tokenCount: sawTokenCount ? tokenCount : undefined,
         outputTokens: sawTokenCount ? outputTokens : undefined,
@@ -2046,7 +2050,12 @@ async function scanOpenCodeIncremental(onProgress) {
         fileSize: stat.size,
     };
     const prev = getScanStampByPath(OPENCODE_DB);
-    if (prev && prev.fileMtimeMs === currentScan.fileMtimeMs && prev.fileSize === currentScan.fileSize) {
+    // OpenCode has a shared database rather than one transcript file per session,
+    // so this container-level gate must honor extractor-version invalidation too.
+    if (prev &&
+        prev.fileMtimeMs === currentScan.fileMtimeMs &&
+        prev.fileSize === currentScan.fileSize &&
+        prev.extractorVersion === CONTENT_INDEX_VERSION) {
         return;
     }
     const currentVersion = await getCurrentAgentVersion('opencode');
@@ -2154,11 +2163,31 @@ async function scanOpenCodeIncremental(onProgress) {
             const prevStamp = priorStamps.get(c.filePath);
             return !prevStamp
                 || prevStamp.fileMtimeMs !== c.scan.fileMtimeMs
-                || prevStamp.fileSize !== c.scan.fileSize;
+                || prevStamp.fileSize !== c.scan.fileSize
+                || prevStamp.extractorVersion !== CONTENT_INDEX_VERSION;
         });
+        // Role lives on the message row and the genuine user text lives on its
+        // ordered text parts. Poisoned JSON is ignored per row, never per database.
+        const firstUserStmt = db.prepare(`
+      SELECT json_extract(p.data, '$.text') AS text
+      FROM part p
+      WHERE p.message_id = (
+        SELECT m.id FROM message m
+        WHERE m.session_id = ?
+          AND json_valid(m.data) AND json_extract(m.data, '$.role') = 'user'
+        ORDER BY m.time_created ASC
+        LIMIT 1
+      )
+      AND json_valid(p.data) AND json_extract(p.data, '$.type') = 'text'
+      ORDER BY p.time_created ASC
+    `);
         const entries = [];
         for (const { row, id, filePath, scan } of changed) {
             const title = typeof row.title === 'string' ? row.title : '';
+            const firstUserMessage = firstUserStmt.all(id)
+                .map((part) => (typeof part.text === 'string' ? part.text : ''))
+                .join('')
+                .trim() || undefined;
             const directory = typeof row.directory === 'string' ? row.directory : '';
             const version = typeof row.version === 'string' ? row.version : '';
             const timeCreated = asInt(row.time_created);
@@ -2212,6 +2241,7 @@ async function scanOpenCodeIncremental(onProgress) {
                 version: resolveSessionVersion('opencode', OPENCODE_DB, version || undefined, currentVersion),
                 account,
                 topic,
+                firstUserMessage,
                 model,
                 costUsd,
                 durationMs,
@@ -2420,6 +2450,7 @@ async function readRushMeta(filePath, sessionId) {
         project: scan.agentId,
         filePath,
         topic: scan.topic,
+        firstUserMessage: scan.firstUserMessage,
         messageCount: scan.messageCount,
     };
     return { meta, content: scan.contentText || '', assistantContent: scan.assistantText || '' };
@@ -2430,6 +2461,7 @@ async function scanRushSession(filePath) {
     const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
     let timestamp;
     let topic;
+    let firstUserMessage;
     let agentId;
     let messageCount = 0;
     const userTexts = [];
@@ -2467,6 +2499,8 @@ async function scanRushSession(filePath) {
             messageCount++;
             if (parsed.role === 'user') {
                 userTexts.push(cleaned);
+                if (!firstUserMessage)
+                    firstUserMessage = cleanFirstUserMessage(cleaned);
                 if (!topic)
                     topic = extractSessionTopic(cleaned);
             }
@@ -2482,6 +2516,7 @@ async function scanRushSession(filePath) {
     return {
         timestamp,
         topic,
+        firstUserMessage,
         agentId,
         messageCount,
         contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
@@ -2559,6 +2594,7 @@ function readHermesMeta(filePath) {
     const userTexts = [];
     const assistantTexts = [];
     let topic;
+    let firstUserMessage;
     let messageCount = 0;
     for (const msg of messages) {
         const text = extractHermesMessageText(msg?.content);
@@ -2567,6 +2603,8 @@ function readHermesMeta(filePath) {
         messageCount++;
         if (msg?.role === 'user') {
             userTexts.push(text);
+            if (!firstUserMessage)
+                firstUserMessage = cleanFirstUserMessage(text);
             if (!topic)
                 topic = extractSessionTopic(text);
         }
@@ -2593,6 +2631,7 @@ function readHermesMeta(filePath) {
         version: model,
         model,
         topic,
+        firstUserMessage,
         messageCount: messageCount || (typeof session.message_count === 'number' ? session.message_count : undefined),
     };
     return { meta, content: userTexts.join('\n'), assistantContent: assistantTexts.join('\n') };
@@ -2695,6 +2734,7 @@ function readMuseMeta(filePath) {
     const userTexts = [];
     const assistantTexts = [];
     let topic;
+    let firstUserMessage;
     let messageCount = 0;
     let model;
     let project;
@@ -2731,6 +2771,8 @@ function readMuseMeta(filePath) {
             if (cmd?.kind === 'turn_submit' && typeof cmd.prompt === 'string' && cmd.prompt.trim()) {
                 messageCount++;
                 userTexts.push(cmd.prompt.trim());
+                if (!firstUserMessage)
+                    firstUserMessage = cleanFirstUserMessage(cmd.prompt.trim());
                 if (!topic)
                     topic = extractSessionTopic(cmd.prompt.trim());
             }
@@ -2762,6 +2804,7 @@ function readMuseMeta(filePath) {
         filePath,
         model,
         topic,
+        firstUserMessage,
         messageCount: messageCount || undefined,
     };
     return { meta, content: userTexts.join('\n'), assistantContent: assistantTexts.join('\n') };
@@ -2865,6 +2908,7 @@ async function readDroidMeta(filePath, currentVersion) {
         version: resolveSessionVersion('droid', filePath, undefined, currentVersion),
         model,
         topic: scan.topic,
+        firstUserMessage: scan.firstUserMessage,
         messageCount: scan.messageCount,
         tokenCount,
         outputTokens: settings.usage?.outputTokens,
@@ -2913,6 +2957,7 @@ async function scanDroidSession(filePath) {
     let title;
     let sessionTitle;
     let firstUserTopic;
+    let firstUserMessage;
     let model;
     let messageCount = 0;
     let firstTsMs;
@@ -2965,6 +3010,8 @@ async function scanDroidSession(filePath) {
             messageCount++;
             if (msg.role === 'user') {
                 userTexts.push(text);
+                if (!firstUserMessage)
+                    firstUserMessage = cleanFirstUserMessage(text);
                 if (!firstUserTopic)
                     firstUserTopic = extractSessionTopic(text);
             }
@@ -2987,6 +3034,7 @@ async function scanDroidSession(filePath) {
         // Prefer Droid's auto-title, then the raw first-prompt title, then the
         // derived first-user-message topic.
         topic: sessionTitle || title || firstUserTopic,
+        firstUserMessage,
         model,
         messageCount,
         durationMs,
@@ -3020,6 +3068,7 @@ export function initClaudeParseState() {
         version: undefined,
         model: undefined,
         topic: undefined,
+        firstUserMessage: undefined,
         customTitle: undefined,
         aiTitle: undefined,
         entrypoint: undefined,
@@ -3202,6 +3251,8 @@ export function applyClaudeLine(state, parsed) {
     if (parsed.type === 'user') {
         const text = extractClaudeUserText(parsed);
         if (text) {
+            if (!state.firstUserMessage)
+                state.firstUserMessage = cleanFirstUserMessage(text);
             state.messageCount++;
             state.userTexts.push(text);
             if (!state.topic)
@@ -3297,6 +3348,7 @@ export function finalizeClaudeScan(state) {
         version: state.version,
         model: state.model,
         topic: state.topic,
+        firstUserMessage: state.firstUserMessage,
         label,
         entrypoint: state.entrypoint,
         messageCount: state.messageCount,
@@ -3366,7 +3418,7 @@ export function serializeClaudeParserState(state, offset, jsonlDroppingOversized
         : allIds;
     const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
     return {
-        v: 5,
+        v: 6,
         subAgents: state.subAgents,
         backgroundShells: state.backgroundShells,
         offset,
@@ -3379,6 +3431,7 @@ export function serializeClaudeParserState(state, offset, jsonlDroppingOversized
         entrypoint: state.entrypoint,
         firstTsMs: state.firstTsMs,
         topic: state.topic,
+        firstUserMessage: state.firstUserMessage,
         customTitle: state.customTitle,
         aiTitle: state.aiTitle,
         plan: state.plan,
@@ -3449,6 +3502,7 @@ export function hydrateClaudeParseState(prior) {
         version: prior.version,
         model: prior.model,
         topic: prior.topic,
+        firstUserMessage: prior.firstUserMessage,
         customTitle: prior.customTitle,
         aiTitle: prior.aiTitle,
         entrypoint: prior.entrypoint,
@@ -3613,7 +3667,7 @@ function parsePriorClaudeState(row) {
         return null;
     try {
         const parsed = JSON.parse(row.parserState);
-        if (parsed?.v !== 5 || typeof parsed.offset !== 'number' || parsed.toolCalls?.v !== 1)
+        if (parsed?.v !== 6 || typeof parsed.offset !== 'number' || parsed.toolCalls?.v !== 1)
             return null;
         return parsed;
     }
@@ -3644,6 +3698,7 @@ export function initCodexParseState() {
         version: undefined,
         model: undefined,
         topic: undefined,
+        firstUserMessage: undefined,
         messageCount: 0,
         tokenCount: undefined,
         lastTotalTokenUsage: undefined,
@@ -3748,7 +3803,8 @@ function applyCodexLine(state, parsed) {
         return;
     }
     if (parsed.type === 'response_item' && parsed.payload?.type === 'message') {
-        const role = parsed.payload.role === 'user' || parsed.payload.role === 'developer'
+        const payloadRole = parsed.payload.role;
+        const role = payloadRole === 'user' || payloadRole === 'developer'
             ? 'user'
             : 'assistant';
         const text = extractCodexMessageText(parsed.payload.content, role);
@@ -3756,9 +3812,17 @@ function applyCodexLine(state, parsed) {
             return;
         state.messageCount++;
         if (role === 'user') {
-            state.userTexts.push(text);
+            const genuine = cleanFirstUserMessage(text);
+            if (!genuine)
+                return;
+            state.userTexts.push(genuine);
+            // Codex records developer instructions as response_item messages too.
+            // They remain searchable for compatibility, but only an actual user role
+            // may become the session's first request.
+            if (payloadRole === 'user' && !state.firstUserMessage)
+                state.firstUserMessage = genuine;
             if (!state.topic)
-                state.topic = extractSessionTopic(text);
+                state.topic = extractSessionTopic(genuine);
         }
         else {
             state.assistantTexts.push(text);
@@ -3827,6 +3891,7 @@ function finalizeCodexScan(state) {
         version: state.version,
         model: state.model,
         topic: state.topic,
+        firstUserMessage: state.firstUserMessage,
         messageCount: state.messageCount,
         tokenCount: state.tokenCount,
         outputTokens,
@@ -3882,7 +3947,7 @@ async function scanCodexSession(filePath) {
 export function serializeCodexParserState(state, offset, jsonlDroppingOversizedLine = false) {
     const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
     return {
-        v: 3,
+        v: 4,
         offset,
         jsonlDroppingOversizedLine: jsonlDroppingOversizedLine || undefined,
         sessionId: state.sessionId,
@@ -3892,6 +3957,7 @@ export function serializeCodexParserState(state, offset, jsonlDroppingOversizedL
         version: state.version,
         model: state.model,
         topic: state.topic,
+        firstUserMessage: state.firstUserMessage,
         messageCount: state.messageCount,
         tokenCount: state.tokenCount,
         lastTotalTokenUsage: state.lastTotalTokenUsage,
@@ -3934,6 +4000,7 @@ function hydrateCodexParseState(prior) {
         version: prior.version,
         model: prior.model,
         topic: prior.topic,
+        firstUserMessage: prior.firstUserMessage,
         messageCount: prior.messageCount,
         tokenCount: prior.tokenCount,
         lastTotalTokenUsage: prior.lastTotalTokenUsage,
@@ -4073,7 +4140,7 @@ function parsePriorCodexState(row) {
         return null;
     try {
         const parsed = JSON.parse(row.parserState);
-        if (parsed?.v !== 3 || typeof parsed.offset !== 'number' || parsed.toolCalls?.v !== 1)
+        if (parsed?.v !== 4 || typeof parsed.offset !== 'number' || parsed.toolCalls?.v !== 1)
             return null;
         return parsed;
     }
@@ -4208,7 +4275,7 @@ function getClaudeUsageTotal(usage) {
         usage.cache_read_input_tokens,
     ]);
 }
-/** Extract text from Codex message content blocks, filtering out system instructions for user messages. */
+/** Extract text from Codex message content blocks; the caller classifies user scaffolding. */
 function extractCodexMessageText(contentBlocks, role) {
     if (!Array.isArray(contentBlocks))
         return undefined;
@@ -4217,14 +4284,7 @@ function extractCodexMessageText(contentBlocks, role) {
         : contentBlocks.filter((block) => block.type === 'output_text');
     const text = matches
         .map((block) => String(block.text || '').trim())
-        .find((value) => {
-        if (!value)
-            return false;
-        if (role === 'user' && (value.length >= 2000 || value.includes('<permissions instructions>') || value.startsWith('# AGENTS.md instructions'))) {
-            return false;
-        }
-        return true;
-    });
+        .find((value) => !!value);
     return text || undefined;
 }
 /** Trim and normalize a version string, returning undefined for empty values. */
@@ -4233,11 +4293,18 @@ function normalizeVersion(version) {
     return trimmed ? trimmed : undefined;
 }
 /** Extract the version number from a managed versions/<agent>/<version>/... path under either repo. */
-function extractVersionFromManagedPath(agent, sourcePath) {
+export function extractVersionFromManagedPath(agent, sourcePath) {
     if (!sourcePath)
         return undefined;
     const candidates = [sourcePath, safeRealpathSync(sourcePath) || ''];
     const markers = [`/.agents/versions/${agent}/`, `/.agents-system/versions/${agent}/`];
+    // Codex is relocated by CODEX_HOME to `~/.agents/.codex-homes/<version>/`
+    // (shims.ts `codexHomeShimBash`), NOT the `versions/<agent>/<version>/home/…`
+    // layout every other isolated agent uses — so its rollout transcripts live
+    // under `.codex-homes/<version>/sessions/…` and the markers above never match,
+    // leaving `version` NULL and native resume degraded to `/continue` (PHNX-3626).
+    if (agent === 'codex')
+        markers.push('/.agents/.codex-homes/');
     for (const candidate of candidates) {
         if (!candidate)
             continue;
@@ -4585,16 +4652,30 @@ export function readKimiMeta(filePath, priorRow) {
         project,
         filePath,
         topic,
+        firstUserMessage: newState.firstUserMessage,
         messageCount,
         tokenCount: tokenCount > 0 ? tokenCount : undefined,
         outputTokens: outputTokens > 0 ? outputTokens : undefined,
     };
     return { meta, content: lastPrompt || '', parserState: JSON.stringify(newState) };
 }
+function kimiWireUserText(event) {
+    if (event?.type !== 'context.append_message' || event?.message?.role !== 'user')
+        return undefined;
+    const content = event.message.content;
+    const raw = typeof content === 'string'
+        ? content
+        : Array.isArray(content)
+            ? content.map((part) => typeof part === 'string' ? part : typeof part?.text === 'string' ? part.text : '').join('\n')
+            : '';
+    return cleanFirstUserMessage(raw);
+}
 /** Fold one parsed Kimi wire event into the additive counters, in place. */
 function applyKimiWireEvent(acc, event) {
     if (event.type === 'context.append_message') {
         acc.messageCount++;
+        if (!acc.firstUserMessage)
+            acc.firstUserMessage = kimiWireUserText(event);
     }
     else if (event.type === 'usage.record' && event.usage) {
         // Kimi usage structure: inputOther + output + inputCacheRead + inputCacheCreation
@@ -4624,7 +4705,7 @@ export function parseKimiWireMetricsIncremental(sessionDir, prior) {
     if (!stat) {
         // No wire.jsonl (yet): zero counters, offset 0 so a later append is a clean
         // full parse.
-        return { messageCount: 0, tokenCount: 0, outputTokens: 0, newState: { v: 1, offset: 0, messageCount: 0, tokenCount: 0, outputTokens: 0 } };
+        return { messageCount: 0, tokenCount: 0, outputTokens: 0, newState: { v: 2, offset: 0, messageCount: 0, tokenCount: 0, outputTokens: 0 } };
     }
     // INCREMENTAL only when a usable prior exists AND the file grew past its
     // offset; otherwise FULL from byte 0 with fresh counters (cold start OR the
@@ -4643,8 +4724,8 @@ export function parseKimiWireMetricsIncremental(sessionDir, prior) {
     const canIncrement = prior !== null && stat.size > prior.offset;
     const fromOffset = canIncrement ? prior.offset : 0;
     const acc = canIncrement
-        ? { messageCount: prior.messageCount, tokenCount: prior.tokenCount, outputTokens: prior.outputTokens }
-        : { messageCount: 0, tokenCount: 0, outputTokens: 0 };
+        ? { messageCount: prior.messageCount, tokenCount: prior.tokenCount, outputTokens: prior.outputTokens, firstUserMessage: prior.firstUserMessage }
+        : { messageCount: 0, tokenCount: 0, outputTokens: 0, firstUserMessage: undefined };
     let consumedBytes = 0;
     let fd;
     try {
@@ -4699,7 +4780,7 @@ export function parseKimiWireMetricsIncremental(sessionDir, prior) {
         messageCount: acc.messageCount,
         tokenCount: acc.tokenCount,
         outputTokens: acc.outputTokens,
-        newState: { v: 1, offset: fromOffset + consumedBytes, messageCount: acc.messageCount, tokenCount: acc.tokenCount, outputTokens: acc.outputTokens },
+        newState: { v: 2, offset: fromOffset + consumedBytes, messageCount: acc.messageCount, tokenCount: acc.tokenCount, outputTokens: acc.outputTokens, firstUserMessage: acc.firstUserMessage },
     };
 }
 /**
@@ -4713,7 +4794,7 @@ function parsePriorKimiState(row) {
         return null;
     try {
         const parsed = JSON.parse(row.parserState);
-        if (parsed?.v !== 1 || typeof parsed.offset !== 'number')
+        if (parsed?.v !== 2 || typeof parsed.offset !== 'number')
             return null;
         return parsed;
     }

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,16 @@
  * own scaffolding at parse time simply never reach here.
  */
 export declare function isSyntheticUserMessage(raw: string | undefined): boolean;
+/**
+ * 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.
+ */
+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,6 +47,7 @@ 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*## (?:In-flight in this repo|Host & Fleet)/i,
     /^\s*Your current session id is\b/i,
@@ -68,6 +69,30 @@ export function isSyntheticUserMessage(raw) {
         return false;
     return SYNTHETIC_USER_MESSAGE_PATTERNS.some(pattern => pattern.test(raw));
 }
+/**
+ * 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.
+ */
+export function cleanFirstUserMessage(raw) {
+    if (!raw || isSyntheticUserMessage(raw))
+        return undefined;
+    const clean = raw.trim();
+    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,11 +1,30 @@
 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 only 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. Absent means
+ * "use the launched version home's own native login" — the healthy-origin happy
+ * path and every /continue fallback.
+ */
+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';
@@ -46,7 +65,16 @@ export declare function inspectNativeResumeSession(session: SessionMeta, version
  * retained version trash. 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);
@@ -152,6 +158,39 @@ 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 providerAccount = rotated?.picked.providerAccount;
+            if (providerAccount) {
+                // `originLimited` guarantees the origin is unhealthy with a limit reason.
+                const why = originReadiness.ready ? 'limited' : originReadiness.reason;
+                const label = rotated.picked.accountLabel || providerAccount;
+                return {
+                    mode: 'native',
+                    agent,
+                    version: session.version,
+                    cwd: inspection.cwd,
+                    account: { providerAccount, label, email: rotated.picked.email },
+                    reason: `origin ${agent}@${session.version} account is ${why}; rotated to healthy ${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 +203,11 @@ 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)) {
+    // 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) {
@@ -190,9 +233,18 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
         reason: `${sourceReason(session, candidates)}; continuing with healthy ${agent}@${version}`,
     };
 }
-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