fix(agents/cli-runner): reseed claude-cli context after invalidator-driven session reset

adele-with-a-b · adele-with-a-b · commit 3a6de1b62ab9 · 2026-05-14T17:15:29.000-04:00
When `prepareCliRunContext` invalidates a claude-cli session for ANY
reason — missing-transcript, orphaned-tool-use, system-prompt, mcp,
auth-profile, auth-epoch — the runtime starts a fresh claude-cli
session and the agent loses memory of every prior turn. The OC-side
history reseed (`buildCliSessionHistoryPrompt` /
`loadCliSessionReseedMessages`) only fires on a pre-existing compaction
summary, which agents that haven't been long enough to compact don't
have. The user-visible result: the silent-abort cycle is replaced by
amnesia. Same end-user pain, different shape.

The dead claude-cli transcript still has the full conversation on disk
(it's what we just walked to find the orphan, or what the
missing-transcript / system-prompt / mcp paths were just told to
discard). Read it, build a `priorContextPrelude` from the main-
conversation messages (sidechain already filtered out by the existing
`parseClaudeCliHistoryEntry`), and prepend via the same
`resolveFallbackRetryPrompt` shape the fallback-to-different-provider
path already uses. The fresh session inherits the conversation; the
recovery becomes invisible to the user beyond a one-turn delay.

Note: `session-expired` retains the sessionId, so it doesn't apply
here — it's already covered by the existing `rawTranscriptReseedReason`
path that runs `buildCliSessionHistoryPrompt`.

Surfaces `buildClaudeCliFallbackContextPrelude` through `prepareDeps`
so tests can stub the on-disk reader without seeding a real
`~/.claude/projects/&lt;encoded-cwd&gt;/&lt;sid&gt;.jsonl`. Tests cover:
  - reseed fires for `missing-transcript` invalidation
  - reseed fires for `orphaned-tool-use` invalidation
  - reseed fires for `system-prompt` invalidation
  - reseed does NOT fire when the session is reusable
  - reseed does NOT fire for non-claude-cli providers

Note: this only mitigates the user-visible amnesia. The upstream cause
of the orphan creation (live-session manager tearing down claude-cli
mid-tool on fingerprint mismatch) and the system-prompt-drift cause
(extraSystemPromptHash changing across turns despite the static-only
hashing intent) are still tracked separately — see the diagnostic in
`claude-live-session.ts` from the prior commit on this branch.

AI-assisted: yes. Tooling: Claude Opus + claude-cli.
diff --git a/src/agents/cli-runner/prepare.test.ts b/src/agents/cli-runner/prepare.test.ts
@@ -5,6 +5,7 @@ import { CURRENT_SESSION_VERSION } from "@earendil-works/pi-coding-agent";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { getGlobalHookRunner } from "../../plugins/hook-runner-global.js";
+import { CLI_AUTH_EPOCH_VERSION } from "../cli-auth-epoch.js";
 import { __testing as cliBackendsTesting } from "../cli-backends.js";
 import { hashCliSessionText } from "../cli-session.js";
 import { buildActiveMusicGenerationTaskPromptContextForSession } from "../music-generation-task-status.js";
@@ -993,4 +994,279 @@ describe("shouldSkipLocalCliCredentialEpoch", () => {
       fs.rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  it("reseeds prior context from the dead claude-cli transcript when invalidator fires for missing-transcript", async () => {
+    const { dir, sessionFile } = createSessionFile();
+    try {
+      cliBackendsTesting.setDepsForTest({
+        resolvePluginSetupCliBackend: () => undefined,
+        resolveRuntimeCliBackends: () => [
+          {
+            id: "claude-cli",
+            pluginId: "anthropic",
+            bundleMcp: false,
+            config: {
+              command: "claude",
+              args: ["--print"],
+              resumeArgs: ["--resume", "{sessionId}"],
+              output: "jsonl",
+              input: "stdin",
+              sessionMode: "existing",
+            },
+          },
+        ],
+      });
+      const transcriptCheck = vi.fn(async () => false);
+      const orphanCheck = vi.fn(async () => false);
+      const fallbackPrelude = vi.fn(
+        () =>
+          "## Prior session context (from claude-cli)\n\nuser: prior question\nassistant: prior answer",
+      );
+      setCliRunnerPrepareTestDeps({
+        claudeCliSessionTranscriptHasContent: transcriptCheck,
+        claudeCliSessionTranscriptHasOrphanedToolUse: orphanCheck,
+        buildClaudeCliFallbackContextPrelude: fallbackPrelude,
+      });
+
+      const context = await prepareCliRunContext({
+        sessionId: "session-test",
+        sessionKey: "agent:main:telegram:direct:peer",
+        sessionFile,
+        workspaceDir: dir,
+        prompt: "follow-up ask",
+        provider: "claude-cli",
+        model: "opus",
+        timeoutMs: 1_000,
+        runId: "run-reseed-missing",
+        cliSessionBinding: { sessionId: "stale-claude-sid" },
+        cliSessionId: "stale-claude-sid",
+        config: createCliBackendConfig({ systemPromptOverride: null }),
+      });
+
+      expect(context.reusableCliSession).toEqual({ invalidatedReason: "missing-transcript" });
+      expect(fallbackPrelude).toHaveBeenCalledWith({ cliSessionId: "stale-claude-sid" });
+      expect(context.params.prompt).toContain("Prior session context (from claude-cli)");
+      expect(context.params.prompt).toContain(
+        "[Retry after the previous model attempt failed or timed out]",
+      );
+      expect(context.params.prompt).toContain("follow-up ask");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("reseeds prior context when invalidator fires for orphaned-tool-use", async () => {
+    const { dir, sessionFile } = createSessionFile();
+    try {
+      cliBackendsTesting.setDepsForTest({
+        resolvePluginSetupCliBackend: () => undefined,
+        resolveRuntimeCliBackends: () => [
+          {
+            id: "claude-cli",
+            pluginId: "anthropic",
+            bundleMcp: false,
+            config: {
+              command: "claude",
+              args: ["--print"],
+              resumeArgs: ["--resume", "{sessionId}"],
+              output: "jsonl",
+              input: "stdin",
+              sessionMode: "existing",
+            },
+          },
+        ],
+      });
+      const transcriptCheck = vi.fn(async () => true);
+      const orphanCheck = vi.fn(async () => true);
+      const fallbackPrelude = vi.fn(
+        () => "## Prior session context (from claude-cli)\n\nassistant: stuck mid-tool reply",
+      );
+      setCliRunnerPrepareTestDeps({
+        claudeCliSessionTranscriptHasContent: transcriptCheck,
+        claudeCliSessionTranscriptHasOrphanedToolUse: orphanCheck,
+        buildClaudeCliFallbackContextPrelude: fallbackPrelude,
+      });
+
+      const context = await prepareCliRunContext({
+        sessionId: "session-test",
+        sessionKey: "agent:main:telegram:direct:peer",
+        sessionFile,
+        workspaceDir: dir,
+        prompt: "are you there?",
+        provider: "claude-cli",
+        model: "opus",
+        timeoutMs: 1_000,
+        runId: "run-reseed-orphan",
+        cliSessionBinding: { sessionId: "orphaned-claude-sid" },
+        cliSessionId: "orphaned-claude-sid",
+        config: createCliBackendConfig({ systemPromptOverride: null }),
+      });
+
+      expect(context.reusableCliSession).toEqual({ invalidatedReason: "orphaned-tool-use" });
+      expect(fallbackPrelude).toHaveBeenCalledWith({ cliSessionId: "orphaned-claude-sid" });
+      expect(context.params.prompt).toContain("Prior session context (from claude-cli)");
+      expect(context.params.prompt).toContain("are you there?");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("does not call the prelude builder when the claude-cli session is reusable (no invalidation)", async () => {
+    const { dir, sessionFile } = createSessionFile();
+    try {
+      cliBackendsTesting.setDepsForTest({
+        resolvePluginSetupCliBackend: () => undefined,
+        resolveRuntimeCliBackends: () => [
+          {
+            id: "claude-cli",
+            pluginId: "anthropic",
+            bundleMcp: false,
+            config: {
+              command: "claude",
+              args: ["--print"],
+              resumeArgs: ["--resume", "{sessionId}"],
+              output: "jsonl",
+              input: "stdin",
+              sessionMode: "existing",
+            },
+          },
+        ],
+      });
+      const transcriptCheck = vi.fn(async () => true);
+      const orphanCheck = vi.fn(async () => false);
+      const fallbackPrelude = vi.fn(() => "");
+      setCliRunnerPrepareTestDeps({
+        claudeCliSessionTranscriptHasContent: transcriptCheck,
+        claudeCliSessionTranscriptHasOrphanedToolUse: orphanCheck,
+        buildClaudeCliFallbackContextPrelude: fallbackPrelude,
+      });
+
+      const context = await prepareCliRunContext({
+        sessionId: "session-test",
+        sessionKey: "agent:main:telegram:direct:peer",
+        sessionFile,
+        workspaceDir: dir,
+        prompt: "next ask",
+        provider: "claude-cli",
+        model: "opus",
+        timeoutMs: 1_000,
+        runId: "run-reseed-skip",
+        cliSessionBinding: { sessionId: "live-claude-sid" },
+        cliSessionId: "live-claude-sid",
+        config: createCliBackendConfig({ systemPromptOverride: null }),
+      });
+
+      expect(context.reusableCliSession).toEqual({ sessionId: "live-claude-sid" });
+      expect(fallbackPrelude).not.toHaveBeenCalled();
+      expect(context.params.prompt).not.toContain("Prior session context");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("reseeds prior context when invalidator fires for system-prompt change", async () => {
+    // system-prompt invalidation happens when the cli session reuse layer
+    // detects that the agent's static system prompt hashed differently
+    // than the binding's stored hash. Same end-user pain as the other
+    // invalidation paths (fresh CLI session, no memory), so the same
+    // recovery applies — read the dead transcript and reseed.
+    const { dir, sessionFile } = createSessionFile();
+    try {
+      cliBackendsTesting.setDepsForTest({
+        resolvePluginSetupCliBackend: () => undefined,
+        resolveRuntimeCliBackends: () => [
+          {
+            id: "claude-cli",
+            pluginId: "anthropic",
+            bundleMcp: false,
+            config: {
+              command: "claude",
+              args: ["--print"],
+              resumeArgs: ["--resume", "{sessionId}"],
+              output: "jsonl",
+              input: "stdin",
+              sessionMode: "existing",
+            },
+          },
+        ],
+      });
+      const transcriptCheck = vi.fn(async () => true);
+      const orphanCheck = vi.fn(async () => false);
+      const fallbackPrelude = vi.fn(
+        () =>
+          "## Prior session context (from claude-cli)\n\nuser: prior question\nassistant: prior answer",
+      );
+      setCliRunnerPrepareTestDeps({
+        claudeCliSessionTranscriptHasContent: transcriptCheck,
+        claudeCliSessionTranscriptHasOrphanedToolUse: orphanCheck,
+        buildClaudeCliFallbackContextPrelude: fallbackPrelude,
+      });
+
+      // Drive a system-prompt invalidation by passing a binding whose
+      // extraSystemPromptHash doesn't match the current hash. The runtime
+      // recomputes the hash from extraSystemPromptStatic/extraSystemPrompt;
+      // we set the binding hash to a fixed wrong value.
+      const context = await prepareCliRunContext({
+        sessionId: "session-test",
+        sessionKey: "agent:main:telegram:direct:peer",
+        sessionFile,
+        workspaceDir: dir,
+        prompt: "follow-up",
+        provider: "claude-cli",
+        model: "opus",
+        timeoutMs: 1_000,
+        runId: "run-reseed-system-prompt",
+        extraSystemPrompt: "agent-static-prompt",
+        extraSystemPromptStatic: "agent-static-prompt",
+        cliSessionBinding: {
+          sessionId: "stale-system-prompt-sid",
+          extraSystemPromptHash: "deadbeefdeadbeef",
+          authEpochVersion: CLI_AUTH_EPOCH_VERSION,
+        },
+        cliSessionId: "stale-system-prompt-sid",
+        config: createCliBackendConfig({ systemPromptOverride: null }),
+      });
+
+      expect(context.reusableCliSession).toEqual({ invalidatedReason: "system-prompt" });
+      expect(fallbackPrelude).toHaveBeenCalledWith({ cliSessionId: "stale-system-prompt-sid" });
+      expect(context.params.prompt).toContain("Prior session context (from claude-cli)");
+      expect(context.params.prompt).toContain("follow-up");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("does not reseed for non-claude-cli providers even on invalidation-shaped paths", async () => {
+    const { dir, sessionFile } = createSessionFile();
+    try {
+      const transcriptCheck = vi.fn(async () => false);
+      const orphanCheck = vi.fn(async () => false);
+      const fallbackPrelude = vi.fn(() => "should-not-be-called");
+      setCliRunnerPrepareTestDeps({
+        claudeCliSessionTranscriptHasContent: transcriptCheck,
+        claudeCliSessionTranscriptHasOrphanedToolUse: orphanCheck,
+        buildClaudeCliFallbackContextPrelude: fallbackPrelude,
+      });
+
+      const context = await prepareCliRunContext({
+        sessionId: "session-test",
+        sessionFile,
+        workspaceDir: dir,
+        prompt: "next ask",
+        provider: "test-cli",
+        model: "test-model",
+        timeoutMs: 1_000,
+        runId: "run-reseed-other-provider",
+        cliSessionBinding: { sessionId: "test-cli-sid" },
+        config: createCliBackendConfig({ systemPromptOverride: null }),
+      });
+
+      expect(transcriptCheck).not.toHaveBeenCalled();
+      expect(orphanCheck).not.toHaveBeenCalled();
+      expect(fallbackPrelude).not.toHaveBeenCalled();
+      expect(context.params.prompt).not.toContain("should-not-be-called");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });
diff --git a/src/agents/cli-runner/prepare.ts b/src/agents/cli-runner/prepare.ts
@@ -30,8 +30,10 @@ import { CLI_AUTH_EPOCH_VERSION, resolveCliAuthEpoch } from "../cli-auth-epoch.j
 import { resolveCliBackendConfig } from "../cli-backends.js";
 import { hashCliSessionText, resolveCliSessionReuse } from "../cli-session.js";
 import {
+  buildClaudeCliFallbackContextPrelude,
   claudeCliSessionTranscriptHasContent,
   claudeCliSessionTranscriptHasOrphanedToolUse,
+  resolveFallbackRetryPrompt,
 } from "../command/attempt-execution.helpers.js";
 import { resolveHeartbeatPromptForSystemPrompt } from "../heartbeat-system-prompt.js";
 import {
@@ -72,6 +74,9 @@ const prepareDeps = {
   // without touching ~/.claude/projects.
   claudeCliSessionTranscriptHasContent,
   claudeCliSessionTranscriptHasOrphanedToolUse,
+  // Surfaced so tests can stub the claude-cli transcript reader without
+  // having to seed a real `~/.claude/projects/<encoded-cwd>/<sid>.jsonl`.
+  buildClaudeCliFallbackContextPrelude,
 };
 
 export function setCliRunnerPrepareTestDeps(overrides: Partial<typeof prepareDeps>): void {
@@ -433,6 +438,43 @@ export async function prepareCliRunContext(
     prompt: preparedPrompt,
   });
   preparedPrompt = annotateInterSessionPromptText(preparedPrompt, params.inputProvenance);
+
+  // When we just invalidated a claude-cli session for ANY reason, the OC-side
+  // session-history reseed only fires on a pre-existing compaction summary —
+  // which agents that haven't been long enough to compact don't have. The
+  // user-visible result was amnesia: the recovered session has no memory of
+  // the invalidated one. Read the dead claude-cli transcript directly (it's
+  // still on disk and has the full conversation) and prepend a
+  // `priorContextPrelude` so the fresh session inherits the conversation
+  // context. This reuses the same builder the failover-to-different-provider
+  // path uses (`buildClaudeCliFallbackContextPrelude`), since the shape of
+  // the problem is identical: "fresh CLI session, please continue this
+  // prior conversation."
+  //
+  // We fire for EVERY invalidation reason — missing-transcript,
+  // orphaned-tool-use, system-prompt, mcp, auth-profile, auth-epoch — because
+  // every one of them produces a fresh CLI session with no prior context.
+  // (`session-expired` retains the sessionId, so it doesn't apply here; it's
+  // already covered by the existing `rawTranscriptReseedReason` path below.)
+  const recoverFromClaudeCliInvalidation =
+    !reusableCliSession.sessionId &&
+    reusableCliSession.invalidatedReason !== undefined &&
+    isClaudeCliProvider(params.provider) &&
+    candidateClaudeCliSessionId !== undefined;
+  if (recoverFromClaudeCliInvalidation) {
+    const recoveryPrelude = prepareDeps.buildClaudeCliFallbackContextPrelude({
+      cliSessionId: candidateClaudeCliSessionId,
+    });
+    if (recoveryPrelude) {
+      preparedPrompt = resolveFallbackRetryPrompt({
+        body: preparedPrompt,
+        isFallbackRetry: true,
+        sessionHasHistory: true,
+        priorContextPrelude: recoveryPrelude,
+      });
+    }
+  }
+
   const allowRawTranscriptReseed =
     backendResolved.config.reseedFromRawTranscriptWhenUncompacted === true;
   const rawTranscriptReseedReason = reusableCliSession.sessionId
