Normalize agent resume fallback policy (#5269)

Author: alucero270

apps/daemon/src/agent-session-resume.ts

@@ -41,6 +41,87 @@ export interface AgentResumeContext {
 
 export type CapturedAgentSessionResult = 'stored' | 'cleared' | 'skipped';
 
+export type AgentResumeTranscriptMode = 'resume-session' | 'full-transcript';
+
+export interface AgentResumePromptPolicy {
+  mode: AgentResumeTranscriptMode;
+  /** Stored upstream handle to continue this turn, or null when reseeding. */
+  resumeSessionId: string | null;
+  /** True only when the daemon also asks the agent to resume native state. */
+  skipTranscript: boolean;
+  /** True for every guard miss, missing handle, unsupported adapter, or create turn. */
+  requiresFullTranscript: boolean;
+  invalidationReason: ResumeInvalidationReason | null;
+}
+
+export interface AgentResumeFailurePolicy {
+  resumeFailed: boolean;
+  /** Clear the persisted handle before the next attempt. */
+  clearStaleSession: boolean;
+  /** Re-run this turn fresh so the daemon sends the full transcript. */
+  autoReseedFullTranscript: boolean;
+  reason: 'resume_failed' | null;
+}
+
+/**
+ * Shared transcript policy for resumable adapters. Native continuation and
+ * transcript skipping are coupled: if the daemon cannot prove it is resuming a
+ * valid upstream session this turn, the prompt path must recompose the full
+ * transcript.
+ */
+export function resolveAgentResumePromptPolicy(
+  ctx: Pick<AgentResumeContext, 'isResuming' | 'resumeSessionId' | 'invalidationReason'>,
+): AgentResumePromptPolicy {
+  const canResume =
+    ctx.isResuming === true
+    && typeof ctx.resumeSessionId === 'string'
+    && ctx.resumeSessionId.length > 0
+    && ctx.invalidationReason == null;
+  if (canResume) {
+    return {
+      mode: 'resume-session',
+      resumeSessionId: ctx.resumeSessionId,
+      skipTranscript: true,
+      requiresFullTranscript: false,
+      invalidationReason: null,
+    };
+  }
+  return {
+    mode: 'full-transcript',
+    resumeSessionId: null,
+    skipTranscript: false,
+    requiresFullTranscript: true,
+    invalidationReason: ctx.invalidationReason ?? null,
+  };
+}
+
+/**
+ * Shared fallback policy for a resume target that no longer exists upstream.
+ * Only a run that actually attempted native resume may clear the stored handle
+ * and auto-reseed; fresh/create turns must ignore matching prose in stdout.
+ */
+export function resolveAgentResumeFailurePolicy(input: {
+  agentId: string;
+  stderr: string;
+  stdout?: string;
+  isResuming: boolean;
+  resumeSessionId: string | null | undefined;
+}): AgentResumeFailurePolicy {
+  const attemptedResume =
+    input.isResuming === true
+    && typeof input.resumeSessionId === 'string'
+    && input.resumeSessionId.length > 0;
+  const resumeFailed =
+    attemptedResume &&
+    isAgentResumeFailure(input.agentId, input.stderr, input.stdout ?? '');
+  return {
+    resumeFailed,
+    clearStaleSession: resumeFailed,
+    autoReseedFullTranscript: resumeFailed,
+    reason: resumeFailed ? 'resume_failed' : null,
+  };
+}
+
 /**
  * Resume identity guard. A stored upstream session is only safe to continue
  * (and to `skipTranscript` for) when the conversation has not changed shape

apps/daemon/src/server.ts

@@ -684,9 +684,10 @@ import {
 import {
   computeIncludeStable,
   hashStableInstructions,
-  isAgentResumeFailure,
   persistCapturedAgentSession,
   resolveAgentResumeContext,
+  resolveAgentResumeFailurePolicy,
+  resolveAgentResumePromptPolicy,
 } from './agent-session-resume.js';
 import {
   initialNativeSessionRecoveryMetadata,
@@ -10505,14 +10506,15 @@ export async function startServer({
       invalidationReason: agentResumeCtx.invalidationReason,
     });
     publishNativeSessionRecoveryMetadata();
+    const agentResumePromptPolicy = resolveAgentResumePromptPolicy(agentResumeCtx);
     const userRequestPrompt = composeChatUserRequestForAgent(
       message,
       currentPrompt,
       // Only trim to the latest turn when we are actually resuming an
       // existing session. A create turn still sends the full transcript so
       // a brand-new session (incl. first turn after another agent)
       // is seeded with prior context.
-      { skipTranscript: agentResumeCtx.isResuming },
+      { skipTranscript: agentResumePromptPolicy.skipTranscript },
     );
     // The stable instruction slice (daemon prompt + tool contract + system
     // prompt = design system / skills / memory) is identical across turns of
@@ -10538,12 +10540,12 @@ export async function startServer({
     // tool-token grant's presence flips between turns (rare cwd/projectId edge
     // cases); any such change correctly forces a full re-send that turn.
     const includeStableInstructions = computeIncludeStable(
-      agentResumeCtx.isResuming,
+      agentResumePromptPolicy.skipTranscript,
       agentResumeCtx.storedStablePromptHash,
       currentStableHash,
     );
     run.promptCache = describeStablePromptCache({
-      isResuming: agentResumeCtx.isResuming,
+      isResuming: agentResumePromptPolicy.skipTranscript,
       storedStablePromptHash: agentResumeCtx.storedStablePromptHash,
       currentStableHash,
       storedStableSections: agentResumeCtx.storedStableSections,
@@ -11694,7 +11696,7 @@ export async function startServer({
           hasPriorAssistantTurn,
           agentLogFilePath,
           promptFilePath: promptFile?.path,
-          resumeSessionId: agentResumeCtx.resumeSessionId,
+          resumeSessionId: agentResumePromptPolicy.resumeSessionId,
           newSessionId: agentResumeCtx.newSessionId,
           disablePlugins:
             def.id === 'codex'
@@ -13049,15 +13051,20 @@ export async function startServer({
           // authority on how a resume failure ends.
           if (
             (runtimeResumesSessionById(def) || def.resumesSessionViaAcpLoad === true) &&
-            agentResumeCtx.isResuming &&
             !run.resumeAutoReseeded &&
-            isAgentResumeFailure(def.id, agentStderrTail, agentStdoutTail)
+            resolveAgentResumeFailurePolicy({
+              agentId: def.id,
+              stderr: agentStderrTail,
+              stdout: agentStdoutTail,
+              isResuming: agentResumePromptPolicy.skipTranscript,
+              resumeSessionId: agentResumePromptPolicy.resumeSessionId,
+            }).resumeFailed
           ) {
             design.runs.emit(run, 'diagnostic', {
               type: 'agent_resume_failed_suppressed',
               agent_id: def.id,
               reason: 'resume_failed',
-              previous_session_id: agentResumeCtx.resumeSessionId ?? null,
+              previous_session_id: agentResumePromptPolicy.resumeSessionId ?? null,
             });
             return;
           }
@@ -13199,8 +13206,8 @@ export async function startServer({
         prompt: composed,
         cwd: effectiveCwd,
         model: safeModel,
-        parentSession: agentResumeCtx.isResuming && agentResumeCtx.resumeSessionId
-          ? agentResumeCtx.resumeSessionId
+        parentSession: agentResumePromptPolicy.resumeSessionId
+          ? agentResumePromptPolicy.resumeSessionId
           : undefined,
         send: (channel, payload) => {
           if (channel === 'agent') {
@@ -13249,8 +13256,8 @@ export async function startServer({
         ...(def.id === 'amr' ? { modelUnavailableErrorCode: 'AMR_MODEL_UNAVAILABLE' } : {}),
         // Resume the prior upstream session (drives `session/load`) when the
         // resume-identity guard says it is safe; otherwise a fresh session/new.
-        ...(def.resumesSessionViaAcpLoad === true && agentResumeCtx.isResuming && agentResumeCtx.resumeSessionId
-          ? { resumeSessionId: agentResumeCtx.resumeSessionId }
+        ...(def.resumesSessionViaAcpLoad === true && agentResumePromptPolicy.resumeSessionId
+          ? { resumeSessionId: agentResumePromptPolicy.resumeSessionId }
           : {}),
         onCliReady: () => noteCliReadyAt(),
         onSessionInit: () => noteSessionInitDoneAt(),
@@ -13308,16 +13315,20 @@ export async function startServer({
           if (
             event === 'error' &&
             def.resumesSessionViaAcpLoad === true &&
-            agentResumeCtx.isResuming &&
-            agentResumeCtx.resumeSessionId &&
             !run.resumeAutoReseeded &&
-            isAgentResumeFailure(def.id, agentStderrTail, agentStdoutTail)
+            resolveAgentResumeFailurePolicy({
+              agentId: def.id,
+              stderr: agentStderrTail,
+              stdout: agentStdoutTail,
+              isResuming: agentResumePromptPolicy.skipTranscript,
+              resumeSessionId: agentResumePromptPolicy.resumeSessionId,
+            }).resumeFailed
           ) {
             design.runs.emit(run, 'diagnostic', {
               type: 'agent_resume_failed_suppressed',
               agent_id: def.id,
               reason: 'resume_failed',
-              previous_session_id: agentResumeCtx.resumeSessionId ?? null,
+              previous_session_id: agentResumePromptPolicy.resumeSessionId ?? null,
             });
             return;
           }
@@ -13523,9 +13534,14 @@ export async function startServer({
       if (
         !run.cancelRequested &&
         (runtimeResumesSessionById(def) || def.resumesSessionViaAcpLoad === true) &&
-        agentResumeCtx.isResuming &&
         run.conversationId &&
-        isAgentResumeFailure(def.id, agentStderrTail, agentStdoutTail)
+        resolveAgentResumeFailurePolicy({
+          agentId: def.id,
+          stderr: agentStderrTail,
+          stdout: agentStdoutTail,
+          isResuming: agentResumePromptPolicy.skipTranscript,
+          resumeSessionId: agentResumePromptPolicy.resumeSessionId,
+        }).autoReseedFullTranscript
       ) {
         // The resumed upstream session is gone (expired / pruned). Clear the dead
         // handle and TRANSPARENTLY re-run this same turn with a fresh session +
@@ -13538,11 +13554,11 @@ export async function startServer({
         clearAgentSession(db, run.conversationId, def.id);
         if (!run.resumeAutoReseeded) {
           run.resumeAutoReseeded = true;
-          run.resumeAutoReseededFrom = agentResumeCtx.resumeSessionId ?? null;
+          run.resumeAutoReseededFrom = agentResumePromptPolicy.resumeSessionId ?? null;
           run.nativeSessionRecovery = markNativeSessionAutoReseeded({
             previous: run.nativeSessionRecovery,
             agentId: def.id,
-            previousSessionId: agentResumeCtx.resumeSessionId,
+            previousSessionId: agentResumePromptPolicy.resumeSessionId,
           });
           publishNativeSessionRecoveryMetadata();
           // Persisted to the per-run events.jsonl that the help → diagnostics
@@ -13552,7 +13568,7 @@ export async function startServer({
             type: 'agent_resume_auto_reseed',
             agent_id: def.id,
             reason: 'resume_failed',
-            previous_session_id: agentResumeCtx.resumeSessionId ?? null,
+            previous_session_id: agentResumePromptPolicy.resumeSessionId ?? null,
             stale_session_cleared: true,
             nativeSessionRecovery: run.nativeSessionRecovery,
           });

apps/daemon/tests/agent-session-resume.test.ts

@@ -23,6 +23,8 @@ import {
   isOpencodeResumeFailure,
   persistCapturedAgentSession,
   resolveAgentResumeContext,
+  resolveAgentResumeFailurePolicy,
+  resolveAgentResumePromptPolicy,
 } from '../src/agent-session-resume.js';
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -258,6 +260,71 @@ describe('computeIncludeStable', () => {
   });
 });
 
+describe('resolveAgentResumePromptPolicy', () => {
+  it('allows transcript skipping only when a valid native resume handle is selected', () => {
+    expect(
+      resolveAgentResumePromptPolicy({
+        isResuming: true,
+        resumeSessionId: 'sess-A',
+        invalidationReason: null,
+      }),
+    ).toEqual({
+      mode: 'resume-session',
+      resumeSessionId: 'sess-A',
+      skipTranscript: true,
+      requiresFullTranscript: false,
+      invalidationReason: null,
+    });
+  });
+
+  it('requires the full transcript for a fresh create turn with no stored session', () => {
+    expect(
+      resolveAgentResumePromptPolicy({
+        isResuming: false,
+        resumeSessionId: null,
+        invalidationReason: null,
+      }),
+    ).toMatchObject({
+      mode: 'full-transcript',
+      resumeSessionId: null,
+      skipTranscript: false,
+      requiresFullTranscript: true,
+      invalidationReason: null,
+    });
+  });
+
+  it('requires the full transcript for every guard failure', () => {
+    expect(
+      resolveAgentResumePromptPolicy({
+        isResuming: false,
+        resumeSessionId: null,
+        invalidationReason: 'conversation_advanced',
+      }),
+    ).toMatchObject({
+      mode: 'full-transcript',
+      resumeSessionId: null,
+      skipTranscript: false,
+      requiresFullTranscript: true,
+      invalidationReason: 'conversation_advanced',
+    });
+  });
+
+  it('treats inconsistent resume state as full-transcript reseed instead of skipping history', () => {
+    expect(
+      resolveAgentResumePromptPolicy({
+        isResuming: true,
+        resumeSessionId: null,
+        invalidationReason: null,
+      }),
+    ).toMatchObject({
+      mode: 'full-transcript',
+      resumeSessionId: null,
+      skipTranscript: false,
+      requiresFullTranscript: true,
+    });
+  });
+});
+
 describe('persistCapturedAgentSession', () => {
   let tempDir: string;
 
@@ -577,3 +644,39 @@ describe('isAgentResumeFailure dispatch', () => {
     expect(isAgentResumeFailure('claude', '')).toBe(false);
   });
 });
+
+describe('resolveAgentResumeFailurePolicy', () => {
+  it('clears stale state and auto-reseeds only for a failed attempted resume', () => {
+    expect(
+      resolveAgentResumeFailurePolicy({
+        agentId: 'opencode',
+        stderr: 'Error: Session not found',
+        stdout: '',
+        isResuming: true,
+        resumeSessionId: 'ses-old',
+      }),
+    ).toEqual({
+      resumeFailed: true,
+      clearStaleSession: true,
+      autoReseedFullTranscript: true,
+      reason: 'resume_failed',
+    });
+  });
+
+  it('does not clear state on a create turn even if output contains a resume-like phrase', () => {
+    expect(
+      resolveAgentResumeFailurePolicy({
+        agentId: 'opencode',
+        stderr: 'Error: Session not found',
+        stdout: '',
+        isResuming: false,
+        resumeSessionId: null,
+      }),
+    ).toEqual({
+      resumeFailed: false,
+      clearStaleSession: false,
+      autoReseedFullTranscript: false,
+      reason: null,
+    });
+  });
+});