@inceptionstack/roundhouse 0.5.29 → 0.5.31

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to `@inceptionstack/roundhouse` are documented here.
 
+## [0.5.31] — 2026-05-14
+
+### Internal
+- **Refactor: session-repair module split + DRY shared error-classifier helper.** Pure refactor, zero behavior change. Addresses 7 maintainability findings from the post-v0.5.30 review:
+  - Extracted `matchesErrorPatterns()` shared helper so `isContextOverflowError` and `isToolPairingError` no longer duplicate ~80% of their structure. Both classifiers now walk the `cause` chain (previously only the overflow classifier did — fixed divergent-change smell). Both share `looksLikeValidationError()` gating.
+  - Extracted `buildTrimmedEntries()` from `softResetSessionFile` and `attemptSoftResetRecovery()` from `flushMemoryThenCompact`. The lifecycle catch block is now ~25 lines of linear flow (classify → recover → log → persist) instead of ~60 lines with a nested try/catch.
+  - `MAX_CAUSE_CHAIN_DEPTH = 5` named constant.
+  - Split `src/agents/shared/session-repair.ts` (574 lines, two domains) into four focused files: `session-repair.ts` (81 lines, public surface), `session-soft-reset.ts`, `error-classifiers.ts`, `session-repair-internal.ts`. All public exports preserved via re-exports for backward compat.
+  - Introduced `SessionRepairResult` named type replacing anonymous `{entries, report}` shape (named to avoid collision with the existing `RepairResult` in `message-validator.ts`).
+- 2 new regression tests for `isToolPairingError`'s now-fixed cause-chain walking. **536 tests passing.**
+
+## [0.5.30] — 2026-05-14
+
+### Fixed
+- **Soft-reset robustness fixes from codex review of v0.5.29:**
+  - **P1 — byte-cap could cut mid-turn.** When `findSoftResetCutIndex()` hit the byte budget before reaching `keepRecentUserTurns`, it returned `i + 1` which could land on an assistant reply or toolResult whose user prompt was about to be dropped. The kept tail then started mid-turn and tool-pairing repair didn't fix that (only orphans, not turn boundaries). Fixed: byte-cap path now snaps to the most-recent user-message boundary we've walked through.
+  - **P2 — byte cap measured in JS code units, not real bytes.** `JSON.stringify(e).length` counts UTF-16 code units; non-ASCII content (emoji, CJK) overshot the advertised 250k ceiling 2–3x. Now uses `Buffer.byteLength(..., 'utf8')` end-to-end so reported `bytesAfter` and the cap decision both reflect actual file bytes.
+  - **P2 — trim + repair was not atomic end-to-end.** Old flow wrote the trimmed file, then called `repairSessionFile()` which re-backed-up the *already-trimmed* file and rewrote it again. A crash between the two writes left a partial state and lost the true original. Refactored: extracted `repairEntriesInMemory()` so trim + tool-pair repair compose in memory and land as a single backup + atomic rename.
+  - **P2 — `isContextOverflowError()` only inspected top-level `.message`.** Wrapped provider errors (`err.cause.message`, Bedrock `ValidationException` carrying overflow text in nested SDK fields) fell through to re-arming `pendingCompact` instead of triggering recovery. Now mirrors `isToolPairingError()`'s nested handling: walks the `cause` chain (bounded, cycle-safe) and stringify-searches gated on a 4xx/`ValidationException` shape so we don't false-positive on unrelated 5xx noise.
+- 7 regression tests added (534 total passing): byte-cap user-boundary snap, UTF-8 byte accounting, single-atomic-write backup integrity, wrapped-cause classification, Bedrock validation classification, false-positive gating, circular-cause safety.
+
 ## [0.5.29] — 2026-05-14
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.5.29",
+  "version": "0.5.31",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",

package/src/agents/pi/pi-adapter.ts

@@ -28,7 +28,9 @@ import {
 
 import type { AgentAdapter, AgentAdapterFactory, AgentMessage, AgentResponse, AgentStreamEvent, MessageContext } from "../../types";
 import { formatMessage, extractCustomMessage, customContentToText } from "./message-format";
-import { isToolPairingError, repairSessionFile, softResetSessionFile, type SoftResetReport } from "../shared/session-repair";
+import { isToolPairingError } from "../shared/error-classifiers";
+import { repairSessionFile } from "../shared/session-repair";
+import { softResetSessionFile, type SoftResetReport } from "../shared/session-soft-reset";
 import { SESSIONS_DIR } from "../../config";
 import { DEBUG_STREAM, threadIdToDir } from "../../util";
 

package/src/agents/shared/error-classifiers.ts

@@ -0,0 +1,71 @@
+export const MAX_CAUSE_CHAIN_DEPTH = 5;
+
+interface ErrorPatternMatchOptions {
+  stringifyGate?: (err: unknown) => boolean;
+}
+
+/**
+ * Stringify-search gate: only walk serialized error fields when the error
+ * looks like a 4xx / Bedrock ValidationException. Avoids false-positives
+ * from unrelated 5xx noise that happens to contain trigger phrases.
+ */
+function looksLikeValidationError(err: unknown): boolean {
+  const name = (err as { name?: string }).name ?? '';
+  const httpStatus =
+    (err as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode;
+  return name === 'ValidationException' || httpStatus === 400;
+}
+
+export function matchesErrorPatterns(
+  err: unknown,
+  patterns: RegExp[],
+  options: ErrorPatternMatchOptions = {},
+): boolean {
+  if (!err) return false;
+
+  const matches = (value: unknown): boolean => {
+    const message = (value as { message?: string }).message ?? String(value);
+    return patterns.some(pattern => pattern.test(message));
+  };
+
+  if (matches(err)) return true;
+
+  let current: unknown = (err as { cause?: unknown }).cause;
+  for (let depth = 0; depth < MAX_CAUSE_CHAIN_DEPTH && current; depth++) {
+    if (matches(current)) return true;
+    current = (current as { cause?: unknown }).cause;
+  }
+
+  if (!options.stringifyGate?.(err)) {
+    return false;
+  }
+
+  try {
+    const serialized = JSON.stringify(err);
+    return patterns.some(pattern => pattern.test(serialized));
+  } catch {
+    return false;
+  }
+}
+
+export function isContextOverflowError(err: unknown): boolean {
+  const patterns = [
+    /prompt is too long/i,
+    /tokens?\s*[>>]\s*\d+\s*maximum/i,
+    /input is too long/i,
+    /context length exceeded/i,
+    /maximum context length/i,
+  ];
+  return matchesErrorPatterns(err, patterns, { stringifyGate: looksLikeValidationError });
+}
+
+export function isToolPairingError(err: unknown): boolean {
+  const patterns = [
+    /tool_use.*without.*tool_result/i,
+    /tool_result.*without.*tool_use/i,
+    /toolUse.*without.*toolResult/i,
+    /unmatched.*tool.?use/i,
+    /orphan.*tool/i,
+  ];
+  return matchesErrorPatterns(err, patterns, { stringifyGate: looksLikeValidationError });
+}

package/src/agents/shared/session-repair-internal.ts

@@ -0,0 +1,239 @@
+import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync } from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import { validateToolPairing } from './message-validator';
+import type { Message, ToolCall, AssistantMessage, ToolResultMessage } from '@earendil-works/pi-ai';
+
+/** Minimal structural type for a pi-ai session file entry (we only touch message entries). */
+export interface SessionFileEntry {
+  type: string;
+  id?: string;
+  parentId?: string | null;
+  message?: Message;
+  // other fields preserved as-is
+  [key: string]: unknown;
+}
+
+export interface SessionRepairReport {
+  repaired: boolean;
+  droppedEntryIds: string[];
+  droppedToolCallIds: string[];
+  droppedToolResultIds: string[];
+  backupPath?: string;
+  totalEntries: number;
+}
+
+export interface SessionRepairResult {
+  entries: SessionFileEntry[];
+  report: SessionRepairReport;
+}
+
+/** Parse a .jsonl session file. Tolerant of trailing blank lines. Throws on malformed JSON. */
+export function parseSessionFile(path: string): SessionFileEntry[] {
+  const raw = readFileSync(path, 'utf8');
+  const lines = raw.split('\n');
+  const entries: SessionFileEntry[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line) as SessionFileEntry);
+    } catch (err) {
+      throw new Error(`Session file parse error at line ${i + 1}: ${(err as Error).message}`);
+    }
+  }
+  return entries;
+}
+
+/**
+ * Extract `Message[]` from file entries in the order they appear.
+ * Only includes entries of type "message" (skips session header, model_change, etc).
+ */
+function extractMessages(entries: SessionFileEntry[]): { messages: Message[]; entryIndex: number[] } {
+  const messages: Message[] = [];
+  const entryIndex: number[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.type === 'message' && entry.message) {
+      messages.push(entry.message);
+      entryIndex.push(i);
+    }
+  }
+  return { messages, entryIndex };
+}
+
+/**
+ * Re-parent children of dropped entries to preserve tree validity.
+ * If entry X is dropped and entry Y has parentId=X, set Y.parentId = X.parentId.
+ */
+function reparentDroppedEntries(
+  entries: SessionFileEntry[],
+  droppedEntryIds: Set<string>
+): SessionFileEntry[] {
+  const entryById = new Map<string, SessionFileEntry>();
+  for (const entry of entries) {
+    if (entry.id) entryById.set(entry.id, entry);
+  }
+
+  const remap = new Map<string, string | null>();
+  const resolveAncestor = (id: string, visited: Set<string> = new Set()): string | null => {
+    if (remap.has(id)) return remap.get(id)!;
+    if (!droppedEntryIds.has(id)) return id;
+    if (visited.has(id)) {
+      remap.set(id, null);
+      return null;
+    }
+    visited.add(id);
+    const entry = entryById.get(id);
+    const parent = entry?.parentId ?? null;
+    const resolved = parent === null ? null : resolveAncestor(parent, visited);
+    remap.set(id, resolved);
+    return resolved;
+  };
+
+  const kept: SessionFileEntry[] = [];
+  for (const entry of entries) {
+    if (entry.id && droppedEntryIds.has(entry.id)) continue;
+    if (entry.parentId && droppedEntryIds.has(entry.parentId)) {
+      kept.push({ ...entry, parentId: resolveAncestor(entry.parentId) });
+    } else {
+      kept.push(entry);
+    }
+  }
+  return kept;
+}
+
+/**
+ * Compute the set of entry IDs to drop based on orphaned tool IDs.
+ *
+ * - Orphaned toolResult message → drop the whole entry
+ * - Orphaned toolCall inside an assistant message → drop the entry only if the
+ *   toolCall was the *only* content block (otherwise keep the entry with the
+ *   block stripped; handled separately in applyEntryEdits)
+ */
+function findEntriesToDrop(
+  entries: SessionFileEntry[],
+  orphanedToolCallIds: Set<string>,
+  orphanedToolResultIds: Set<string>
+): { entriesToDrop: Set<string>; entriesToEdit: Map<string, string[]> } {
+  const entriesToDrop = new Set<string>();
+  const entriesToEdit = new Map<string, string[]>();
+
+  for (const entry of entries) {
+    if (entry.type !== 'message' || !entry.message || !entry.id) continue;
+    const message = entry.message;
+
+    if (message.role === 'toolResult') {
+      const toolResult = message as ToolResultMessage;
+      if (orphanedToolResultIds.has(toolResult.toolCallId)) {
+        entriesToDrop.add(entry.id);
+      }
+      continue;
+    }
+
+    if (message.role === 'assistant') {
+      const assistantMessage = message as AssistantMessage;
+      const orphanCallIds: string[] = [];
+      let hasNonOrphanContent = false;
+      for (const block of assistantMessage.content) {
+        if ((block as ToolCall).type === 'toolCall') {
+          const callId = (block as ToolCall).id;
+          if (orphanedToolCallIds.has(callId)) {
+            orphanCallIds.push(callId);
+          } else {
+            hasNonOrphanContent = true;
+          }
+        } else {
+          hasNonOrphanContent = true;
+        }
+      }
+      if (orphanCallIds.length === 0) continue;
+      if (hasNonOrphanContent) {
+        entriesToEdit.set(entry.id, orphanCallIds);
+      } else {
+        entriesToDrop.add(entry.id);
+      }
+    }
+  }
+
+  return { entriesToDrop, entriesToEdit };
+}
+
+/** Apply in-place edits to assistant entries: strip orphaned toolCall blocks. */
+function applyEntryEdits(
+  entries: SessionFileEntry[],
+  entriesToEdit: Map<string, string[]>
+): SessionFileEntry[] {
+  if (entriesToEdit.size === 0) return entries;
+  return entries.map(entry => {
+    if (!entry.id || !entriesToEdit.has(entry.id)) return entry;
+    const orphanIds = new Set(entriesToEdit.get(entry.id)!);
+    const message = entry.message as AssistantMessage;
+    const cleanedContent = message.content.filter(block => {
+      if ((block as ToolCall).type === 'toolCall') {
+        return !orphanIds.has((block as ToolCall).id);
+      }
+      return true;
+    });
+    return { ...entry, message: { ...message, content: cleanedContent } };
+  });
+}
+
+/** Atomic write: tmp file + rename. Preserves partial-failure safety. */
+export function atomicWrite(path: string, content: string): void {
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, content, { encoding: 'utf8' });
+  renameSync(tmp, path);
+}
+
+/** Back up the original file before mutation. Returns the backup path. */
+export function backupFile(path: string): string {
+  const ts = Date.now();
+  const backupPath = join(dirname(path), `${basename(path)}.bak-${ts}`);
+  copyFileSync(path, backupPath);
+  return backupPath;
+}
+
+/**
+ * Pure in-memory tool-pairing repair. Takes entries, returns repaired entries
+ * + a report. Does not touch the filesystem.
+ */
+export function repairEntriesInMemory(entries: SessionFileEntry[]): SessionRepairResult {
+  const { messages } = extractMessages(entries);
+  const validation = validateToolPairing(messages);
+
+  if (validation.isValid) {
+    return {
+      entries,
+      report: {
+        repaired: false,
+        droppedEntryIds: [],
+        droppedToolCallIds: [],
+        droppedToolResultIds: [],
+        totalEntries: entries.length,
+      },
+    };
+  }
+
+  const orphanedCalls = new Set(validation.orphanedToolCallIds);
+  const orphanedResults = new Set(validation.orphanedToolResultIds);
+  const { entriesToDrop, entriesToEdit } = findEntriesToDrop(entries, orphanedCalls, orphanedResults);
+  const edited = applyEntryEdits(entries, entriesToEdit);
+  const kept = reparentDroppedEntries(edited, entriesToDrop);
+
+  return {
+    entries: kept,
+    report: {
+      repaired: true,
+      droppedEntryIds: Array.from(entriesToDrop),
+      droppedToolCallIds: validation.orphanedToolCallIds,
+      droppedToolResultIds: validation.orphanedToolResultIds,
+      totalEntries: entries.length,
+    },
+  };
+}
+
+export function assertSessionFileExists(path: string): void {
+  if (!existsSync(path)) {
+    throw new Error(`Session file not found: ${path}`);
+  }
+}

package/src/agents/shared/session-repair.test.ts

@@ -10,10 +10,9 @@ import {
   parseSessionFile,
   inspectSessionFile,
   repairSessionFile,
-  isToolPairingError,
-  softResetSessionFile,
-  isContextOverflowError,
 } from './session-repair';
+import { isToolPairingError, isContextOverflowError } from './error-classifiers';
+import { softResetSessionFile } from './session-soft-reset';
 
 // ---------- fixtures ----------
 
@@ -306,6 +305,24 @@ describe('session-repair', () => {
       expect(isToolPairingError(err)).toBe(true);
     });
 
+    it('matches wrapped Bedrock ValidationException through cause chain', () => {
+      const err = new Error('session resume failed', {
+        cause: Object.assign(new Error('Request failed with status 400'), {
+          name: 'ValidationException',
+          $metadata: { httpStatusCode: 400 },
+          cause: { message: 'messages.3: `tool_use` ids were found without `tool_result` blocks immediately after' },
+        }),
+      });
+      expect(isToolPairingError(err)).toBe(true);
+    });
+
+    it('matches wrapped tool pairing text from a nested cause without stringify fallback', () => {
+      const err = new Error('session resume failed', {
+        cause: new Error('toolUse id abc123 without matching toolResult'),
+      });
+      expect(isToolPairingError(err)).toBe(true);
+    });
+
     it('does not match unrelated 400s', () => {
       const err = new Error('Invalid model ID');
       expect(isToolPairingError(err)).toBe(false);
@@ -505,6 +522,104 @@ describe('softResetSessionFile', () => {
     expect(() => softResetSessionFile('/nonexistent/path.jsonl')).toThrow(/not found/);
   });
 
+  it('softResetSessionFile_ByteCapHit_SnapsToUserTurnBoundary_NeverStartsMidTurn', () => {
+    // Regression test for codex P1: byte-cap path used to return `i + 1`
+    // which could land mid-turn (assistant reply or toolResult with no user
+    // prompt above it). Fixed to snap to the most-recent user-message index.
+    // Arrange: many small turns, byte cap forces an early cut.
+    const entries: object[] = [HEADER, MODEL_CHANGE];
+    let parent: string | null = 'mc-1';
+    for (let i = 1; i <= 30; i++) {
+      entries.push(...userTurn(`t${i}`, parent));
+      parent = `t${i}a`;
+    }
+    const path = tmpJsonl(entries);
+
+    // Act: very tight byte budget so cap fires before keepRecentUserTurns reached.
+    const report = softResetSessionFile(path, { keepRecentUserTurns: 100, maxBytes: 600 });
+
+    // Assert: reset happened AND first kept entry is a user message.
+    expect(report.reset).toBe(true);
+    const trimmed = parseSessionFile(path);
+    expect(trimmed[0].type).toBe('session');           // header preserved
+    expect(trimmed[1].message?.role).toBe('user');     // first kept = user turn
+    expect(trimmed[1].parentId).toBeNull();            // re-parented
+  });
+
+  it('softResetSessionFile_NonAsciiContent_ReportedBytesMatchActualFileBytes', () => {
+    // Regression test for codex P2: trim used JSON.stringify(e).length
+    // (UTF-16 code units) but reported bytesAfter from real file bytes.
+    // After fix, both use Buffer.byteLength(..., 'utf8').
+    // Arrange: turns containing multi-byte UTF-8 (each emoji = 4 bytes,
+    // length 2 in code units — 2x discrepancy).
+    const entries: object[] = [HEADER, MODEL_CHANGE];
+    const emojis = '🚀🔥🎉✨💡'.repeat(20); // ~100 bytes per turn
+    let parent: string | null = 'mc-1';
+    for (let i = 1; i <= 20; i++) {
+      entries.push(
+        userMsg(`t${i}u`, parent, `${emojis} text-${i}`),
+        {
+          type: 'message', id: `t${i}a`, parentId: `t${i}u`,
+          timestamp: '2026-05-01T00:00:04Z',
+          message: {
+            role: 'assistant',
+            content: [{ type: 'text', text: `${emojis} reply-${i}` }],
+            api: 'bedrock-converse-stream', provider: 'amazon-bedrock', model: 'claude',
+            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+            stopReason: 'endTurn', timestamp: 4,
+          },
+        },
+      );
+      parent = `t${i}a`;
+    }
+    const path = tmpJsonl(entries);
+
+    // Act
+    const report = softResetSessionFile(path, { keepRecentUserTurns: 100, maxBytes: 2000 });
+
+    // Assert: reported bytesAfter matches actual file bytes (true UTF-8 size).
+    expect(report.reset).toBe(true);
+    const actualBytes = readFileSync(path).length;
+    expect(report.bytesAfter).toBe(actualBytes);
+    // And we honored the cap (allow some slack for snap-to-user-boundary).
+    expect(report.bytesAfter).toBeLessThan(4000);
+  });
+
+  it('softResetSessionFile_OnSingleAtomicWrite_OriginalBackupIsRecoverable', () => {
+    // Regression test for codex P2: previously trim wrote once, then
+    // repairSessionFile() wrote again with its OWN backup of the
+    // already-trimmed file. After fix, only one backup exists and it's
+    // the true original.
+    // Arrange: session with orphaned tool pair so post-cut repair fires.
+    const oldToolCall = assistantToolCall('a-old', 'mc-1', 'call-X');
+    const orphanedResult = {
+      type: 'message', id: 'tr-1', parentId: 'a-old',
+      timestamp: '2026-05-01T00:00:05Z',
+      message: { role: 'toolResult', toolCallId: 'call-X', content: 'ok', timestamp: 5 },
+    };
+    const entries: object[] = [HEADER, MODEL_CHANGE, userMsg('u-old', 'mc-1', 'old'), oldToolCall];
+    let parent: string | null = 'a-old';
+    for (let i = 1; i <= 5; i++) {
+      entries.push(...userTurn(`f${i}`, parent));
+      parent = `f${i}a`;
+    }
+    entries.splice(6, 0, orphanedResult);
+    const path = tmpJsonl(entries);
+    const originalBytes = readFileSync(path);
+
+    // Act
+    const report = softResetSessionFile(path, { keepRecentUserTurns: 3 });
+
+    // Assert: backup contents = TRUE original (pre-trim, pre-repair),
+    // not an intermediate trimmed-but-unrepaired state.
+    expect(report.reset).toBe(true);
+    expect(report.backupPath).toBeDefined();
+    const backup = readFileSync(report.backupPath!);
+    expect(backup.equals(originalBytes)).toBe(true);
+    // Final on-disk file is internally consistent.
+    expect(inspectSessionFile(path).hasOrphans).toBe(false);
+  });
+
   it('softResetSessionFile_BytesCapHonored_StopsCutAtCap', () => {
     // Arrange: each turn is small but we set a tiny byte cap so we cut early.
     const entries: object[] = [HEADER, MODEL_CHANGE];
@@ -549,4 +664,46 @@ describe('isContextOverflowError', () => {
     expect(isContextOverflowError(undefined)).toBe(false);
     expect(isContextOverflowError({})).toBe(false);
   });
+
+  it('classifies overflow when text lives in err.cause.message (wrapped SDK error)', () => {
+    // Regression test for codex P2: wrapped provider errors used to fall
+    // through to re-arming pendingCompact. After fix, cause-chain is walked.
+    const inner = new Error('prompt is too long: 212776 tokens > 200000 maximum');
+    const outer = new Error('Summarization failed');
+    (outer as { cause?: unknown }).cause = inner;
+    expect(isContextOverflowError(outer)).toBe(true);
+  });
+
+  it('classifies overflow on Bedrock ValidationException with nested overflow text', () => {
+    // Regression test: Bedrock SDK can carry the useful text in nested
+    // $metadata or stringify-only fields. We only stringify-search when
+    // the error LOOKS like a 4xx validation (mirrors isToolPairingError).
+    const err = Object.assign(new Error('validation failed'), {
+      name: 'ValidationException',
+      $metadata: { httpStatusCode: 400 },
+      detail: { reason: 'prompt is too long' },
+    });
+    expect(isContextOverflowError(err)).toBe(true);
+  });
+
+  it('does NOT stringify-search arbitrary errors that contain overflow keywords', () => {
+    // Negative case: gating prevents false-positives on unrelated 5xx errors
+    // whose payload happens to contain trigger phrases.
+    const err = Object.assign(new Error('internal error'), {
+      name: 'InternalServerError',
+      $metadata: { httpStatusCode: 500 },
+      diagnostics: 'log line: prompt is too long check disabled',
+    });
+    expect(isContextOverflowError(err)).toBe(false);
+  });
+
+  it('does not loop forever on circular cause chains', () => {
+    // Safety: cause walk is bounded.
+    const a = new Error('outer');
+    const b = new Error('inner');
+    (a as { cause?: unknown }).cause = b;
+    (b as { cause?: unknown }).cause = a; // cycle
+    expect(() => isContextOverflowError(a)).not.toThrow();
+    expect(isContextOverflowError(a)).toBe(false);
+  });
 });

package/src/agents/shared/session-repair.ts

@@ -1,216 +1,33 @@
 /**
- * session-repair.ts — File-level session repair for corrupted pi-ai session files.
- *
- * Pi-ai persists sessions as JSONL at ~/.roundhouse/sessions/<thread>/<id>.jsonl.
- * Each line is a `FileEntry` in a tree (parentId links). Message entries wrap
- * pi-ai `Message` objects (role: user | assistant | toolResult).
- *
- * Corruption scenarios (mid-session):
- *   - Tool execution aborted → toolCall entry written, toolResult never lands
- *   - Process crash between tool completion and result persist
- *   - Manual Ctrl-C mid-tool
- *
- * On next resume, pi-ai loads these entries → sends history to the model →
- * model rejects with "toolUse without toolResult" (Bedrock/Anthropic 400).
- *
- * This module detects and repairs orphaned tool pairs at the file level,
- * preserving the parentId tree by re-parenting children of dropped entries.
- *
- * Delegates tool-pairing logic to message-validator.ts.
- */
-
-import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync } from 'node:fs';
-import { dirname, basename, join } from 'node:path';
-import { validateToolPairing } from './message-validator.js';
-import type { Message, ToolCall, AssistantMessage, ToolResultMessage } from '@earendil-works/pi-ai';
-
-/** Minimal structural type for a pi-ai session file entry (we only touch message entries). */
-interface SessionFileEntry {
-  type: string;
-  id?: string;
-  parentId?: string | null;
-  message?: Message;
-  // other fields preserved as-is
-  [key: string]: unknown;
-}
-
-export interface SessionRepairReport {
-  repaired: boolean;
-  droppedEntryIds: string[];
-  droppedToolCallIds: string[];
-  droppedToolResultIds: string[];
-  backupPath?: string;
-  totalEntries: number;
-}
-
-/** Parse a .jsonl session file. Tolerant of trailing blank lines. Throws on malformed JSON. */
-export function parseSessionFile(path: string): SessionFileEntry[] {
-  const raw = readFileSync(path, 'utf8');
-  const lines = raw.split('\n');
-  const entries: SessionFileEntry[] = [];
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (!line.trim()) continue;
-    try {
-      entries.push(JSON.parse(line) as SessionFileEntry);
-    } catch (err) {
-      throw new Error(`Session file parse error at line ${i + 1}: ${(err as Error).message}`);
-    }
-  }
-  return entries;
-}
-
-/**
- * Extract `Message[]` from file entries in the order they appear.
- * Only includes entries of type "message" (skips session header, model_change, etc).
- */
-function extractMessages(entries: SessionFileEntry[]): { messages: Message[]; entryIndex: number[] } {
-  const messages: Message[] = [];
-  const entryIndex: number[] = []; // parallel array: messages[i] came from entries[entryIndex[i]]
-  for (let i = 0; i < entries.length; i++) {
-    const e = entries[i];
-    if (e.type === 'message' && e.message) {
-      messages.push(e.message);
-      entryIndex.push(i);
-    }
-  }
-  return { messages, entryIndex };
-}
-
-/**
- * Re-parent children of dropped entries to preserve tree validity.
- * If entry X is dropped and entry Y has parentId=X, set Y.parentId = X.parentId.
- */
-function reparentDroppedEntries(
-  entries: SessionFileEntry[],
-  droppedEntryIds: Set<string>
-): SessionFileEntry[] {
-  // Build a map: droppedId → nearest non-dropped ancestor (walk up the tree)
-  const entryById = new Map<string, SessionFileEntry>();
-  for (const e of entries) {
-    if (e.id) entryById.set(e.id, e);
-  }
-
-  const remap = new Map<string, string | null>();
-  const resolveAncestor = (id: string, visited: Set<string> = new Set()): string | null => {
-    if (remap.has(id)) return remap.get(id)!;
-    if (!droppedEntryIds.has(id)) return id;
-    if (visited.has(id)) {
-      // Cycle in parentId chain (self-parent or loop) — bail with null rather than
-      // blow the stack. Should never happen in a well-formed session file.
-      remap.set(id, null);
-      return null;
-    }
-    visited.add(id);
-    const e = entryById.get(id);
-    const parent = e?.parentId ?? null;
-    const resolved = parent === null ? null : resolveAncestor(parent, visited);
-    remap.set(id, resolved);
-    return resolved;
-  };
-
-  const kept: SessionFileEntry[] = [];
-  for (const e of entries) {
-    if (e.id && droppedEntryIds.has(e.id)) continue;
-    if (e.parentId && droppedEntryIds.has(e.parentId)) {
-      kept.push({ ...e, parentId: resolveAncestor(e.parentId) });
-    } else {
-      kept.push(e);
-    }
-  }
-  return kept;
-}
-
-/**
- * Compute the set of entry IDs to drop based on orphaned tool IDs.
- *
- * - Orphaned toolResult message → drop the whole entry
- * - Orphaned toolCall inside an assistant message → drop the entry only if the
- *   toolCall was the *only* content block (otherwise keep the entry with the
- *   block stripped; handled separately in applyEntryEdits)
+ * session-repair.ts — File-level repair for orphaned toolCall/toolResult pairs.
  */
-function findEntriesToDrop(
-  entries: SessionFileEntry[],
-  orphanedToolCallIds: Set<string>,
-  orphanedToolResultIds: Set<string>
-): { entriesToDrop: Set<string>; entriesToEdit: Map<string, string[]> } {
-  const entriesToDrop = new Set<string>();
-  const entriesToEdit = new Map<string, string[]>(); // entryId → toolCallIds to strip
-
-  for (const e of entries) {
-    if (e.type !== 'message' || !e.message || !e.id) continue;
-    const msg = e.message;
 
-    if (msg.role === 'toolResult') {
-      const tr = msg as ToolResultMessage;
-      if (orphanedToolResultIds.has(tr.toolCallId)) {
-        entriesToDrop.add(e.id);
-      }
-      continue;
-    }
-
-    if (msg.role === 'assistant') {
-      const am = msg as AssistantMessage;
-      const orphanCallIds: string[] = [];
-      let hasNonOrphanContent = false;
-      for (const block of am.content) {
-        if ((block as ToolCall).type === 'toolCall') {
-          const callId = (block as ToolCall).id;
-          if (orphanedToolCallIds.has(callId)) {
-            orphanCallIds.push(callId);
-          } else {
-            hasNonOrphanContent = true;
-          }
-        } else {
-          hasNonOrphanContent = true;
-        }
-      }
-      if (orphanCallIds.length === 0) continue;
-      if (hasNonOrphanContent) {
-        entriesToEdit.set(e.id, orphanCallIds);
-      } else {
-        entriesToDrop.add(e.id);
-      }
-    }
-  }
-
-  return { entriesToDrop, entriesToEdit };
-}
-
-/** Apply in-place edits to assistant entries: strip orphaned toolCall blocks. */
-function applyEntryEdits(
-  entries: SessionFileEntry[],
-  entriesToEdit: Map<string, string[]>
-): SessionFileEntry[] {
-  if (entriesToEdit.size === 0) return entries;
-  return entries.map(e => {
-    if (!e.id || !entriesToEdit.has(e.id)) return e;
-    const orphanIds = new Set(entriesToEdit.get(e.id)!);
-    const msg = e.message as AssistantMessage;
-    const cleanedContent = msg.content.filter(block => {
-      if ((block as ToolCall).type === 'toolCall') {
-        return !orphanIds.has((block as ToolCall).id);
-      }
-      return true;
-    });
-    return { ...e, message: { ...msg, content: cleanedContent } };
-  });
-}
-
-/** Atomic write: tmp file + rename. Preserves partial-failure safety. */
-function atomicWrite(path: string, content: string): void {
-  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-  writeFileSync(tmp, content, { encoding: 'utf8' });
-  renameSync(tmp, path);
-}
-
-/** Back up the original file before mutation. Returns the backup path. */
-function backupFile(path: string): string {
-  const ts = Date.now();
-  const backupPath = join(dirname(path), `${basename(path)}.bak-${ts}`);
-  copyFileSync(path, backupPath);
-  return backupPath;
-}
+import { validateToolPairing } from './message-validator';
+import {
+  assertSessionFileExists,
+  atomicWrite,
+  backupFile,
+  parseSessionFile,
+  repairEntriesInMemory,
+} from './session-repair-internal';
+
+export { parseSessionFile } from './session-repair-internal';
+export type {
+  SessionRepairResult,
+  SessionFileEntry,
+  SessionRepairReport,
+} from './session-repair-internal';
+export {
+  MAX_CAUSE_CHAIN_DEPTH,
+  isContextOverflowError,
+  isToolPairingError,
+  matchesErrorPatterns,
+} from './error-classifiers';
+export {
+  softResetSessionFile,
+  type SoftResetOptions,
+  type SoftResetReport,
+} from './session-soft-reset';
 
 /**
  * Validate a session file for orphaned tool pairs without modifying it.
@@ -224,7 +41,9 @@ export function inspectSessionFile(path: string): {
   totalMessages: number;
 } {
   const entries = parseSessionFile(path);
-  const { messages } = extractMessages(entries);
+  const messages = entries
+    .filter(entry => entry.type === 'message' && entry.message)
+    .map(entry => entry.message!);
   const validation = validateToolPairing(messages);
   return {
     hasOrphans: !validation.isValid,
@@ -246,258 +65,17 @@ export function inspectSessionFile(path: string): {
  *
  * @returns report describing what was repaired
  */
-export function repairSessionFile(path: string): SessionRepairReport {
-  if (!existsSync(path)) {
-    throw new Error(`Session file not found: ${path}`);
-  }
-
-  const entries = parseSessionFile(path);
-  const { messages } = extractMessages(entries);
-  const validation = validateToolPairing(messages);
-
-  if (validation.isValid) {
-    return {
-      repaired: false,
-      droppedEntryIds: [],
-      droppedToolCallIds: [],
-      droppedToolResultIds: [],
-      totalEntries: entries.length,
-    };
-  }
-
-  const orphanedCalls = new Set(validation.orphanedToolCallIds);
-  const orphanedResults = new Set(validation.orphanedToolResultIds);
-
-  const { entriesToDrop, entriesToEdit } = findEntriesToDrop(entries, orphanedCalls, orphanedResults);
-  const edited = applyEntryEdits(entries, entriesToEdit);
-  const kept = reparentDroppedEntries(edited, entriesToDrop);
-
-  const backupPath = backupFile(path);
-  const newContent = kept.map(e => JSON.stringify(e)).join('\n') + '\n';
-  atomicWrite(path, newContent);
-
-  return {
-    repaired: true,
-    droppedEntryIds: Array.from(entriesToDrop),
-    droppedToolCallIds: validation.orphanedToolCallIds,
-    droppedToolResultIds: validation.orphanedToolResultIds,
-    backupPath,
-    totalEntries: entries.length,
-  };
-}
-
-// ── Soft reset (recovery from already-overflowed sessions) ──────────────
-
-/**
- * When a session has grown past the model's context window, normal compact
- * cannot recover — the summarizer prompt itself overflows. Soft reset trims
- * the session jsonl on disk to its most-recent N user turns, drops everything
- * older, and re-runs the tool-pairing repair so what's left is internally
- * consistent.
- *
- * Trade-off: loses fidelity for older turns. The roundhouse memory layer
- * (MEMORY.md, daily front-page) re-injects on the next turn, so the agent
- * still has its durable context — just not the verbatim message history.
- *
- * Conservative defaults aim for ~30–40% of a 200k window so the next compact
- * has ample room to summarize.
- */
-export interface SoftResetOptions {
-  /** Keep at most this many user turns from the tail (default: 8). */
-  keepRecentUserTurns?: number;
-  /** Hard cap on jsonl bytes after trim (default: 250_000 ≈ 60–80k tokens). */
-  maxBytes?: number;
-}
-
-export interface SoftResetReport {
-  reset: boolean;
-  reason: string;
-  entriesBefore: number;
-  entriesAfter: number;
-  bytesBefore: number;
-  bytesAfter: number;
-  backupPath?: string;
-  /** Tool-pairing repair report on the trimmed file (orphans created by the cut). */
-  postRepair?: SessionRepairReport;
-}
-
-/**
- * Find a safe cut index in the entries array. Walk backwards from the end
- * looking for user message entries; the cut sits *just before* the Nth
- * most-recent user message we encounter. Returns the index of the first
- * entry to KEEP (i.e. all entries[0..cutIdx) are dropped).
- *
- * If we can't find enough user messages, returns 1 to keep everything except
- * the session header (which we preserve separately).
- */
-function findSoftResetCutIndex(
-  entries: SessionFileEntry[],
-  keepRecentUserTurns: number,
-  maxBytes: number,
-): { cutIdx: number; reason: string } {
-  let userTurnsSeen = 0;
-  let bytesAccumulated = 0;
-  // Scan tail-to-head, stop when we've collected enough user turns OR exceeded byte budget.
-  for (let i = entries.length - 1; i >= 0; i--) {
-    const e = entries[i];
-    bytesAccumulated += JSON.stringify(e).length + 1; // +1 for newline
-    if (e.type === 'message' && e.message?.role === 'user') {
-      userTurnsSeen++;
-      if (userTurnsSeen >= keepRecentUserTurns) {
-        return { cutIdx: i, reason: `kept-${userTurnsSeen}-user-turns` };
-      }
-    }
-    // Byte cap is a safety net for sessions where a single turn is enormous
-    // (e.g. one turn dumped a 200k file). Stop once we'd exceed the cap.
-    if (bytesAccumulated > maxBytes && userTurnsSeen > 0) {
-      return { cutIdx: i + 1, reason: `byte-cap-${bytesAccumulated}b` };
-    }
-  }
-  // Not enough user turns in the file — keep everything except header.
-  // (Header is always at index 0 and is preserved by the writer separately.)
-  return { cutIdx: 1, reason: 'fewer-turns-than-target' };
-}
-
-/**
- * Soft-reset a pi-ai session jsonl: keep the most-recent N user turns + their
- * surrounding messages, drop everything older. Always preserves the session
- * header (entries[0]). Re-parents the first kept entry to null so the tree
- * remains valid. Re-runs tool-pairing repair on the trimmed file because
- * the cut likely orphaned some toolCall/toolResult pairs.
- *
- * Atomic + backup: same safety pattern as repairSessionFile.
- *
- * @returns report describing what was reset, or `{reset:false}` if nothing to do.
- */
-export function softResetSessionFile(
-  path: string,
-  options: SoftResetOptions = {},
-): SoftResetReport {
-  if (!existsSync(path)) {
-    throw new Error(`Session file not found: ${path}`);
-  }
-
-  const keepRecentUserTurns = options.keepRecentUserTurns ?? 8;
-  const maxBytes = options.maxBytes ?? 250_000;
+export function repairSessionFile(path: string) {
+  assertSessionFileExists(path);
 
   const entries = parseSessionFile(path);
-  const bytesBefore = readFileSync(path).length;
-
-  // Need at least header + a couple of messages to be worth resetting.
-  if (entries.length < 4) {
-    return {
-      reset: false,
-      reason: 'session-too-small',
-      entriesBefore: entries.length,
-      entriesAfter: entries.length,
-      bytesBefore,
-      bytesAfter: bytesBefore,
-    };
-  }
-
-  const { cutIdx, reason } = findSoftResetCutIndex(entries, keepRecentUserTurns, maxBytes);
-
-  // No-op if cut is already at the start (nothing to drop besides header).
-  if (cutIdx <= 1) {
-    return {
-      reset: false,
-      reason: `cut-at-start (${reason})`,
-      entriesBefore: entries.length,
-      entriesAfter: entries.length,
-      bytesBefore,
-      bytesAfter: bytesBefore,
-    };
-  }
+  const { entries: repaired, report } = repairEntriesInMemory(entries);
 
-  // Build trimmed entries: header + tail.
-  // Re-parent the first kept tail entry to null so the tree root is intact.
-  const header = entries[0];
-  const tail = entries.slice(cutIdx);
-  if (tail.length > 0 && tail[0].parentId !== undefined) {
-    tail[0] = { ...tail[0], parentId: null };
-  }
-  const trimmed = [header, ...tail];
+  if (!report.repaired) return report;
 
   const backupPath = backupFile(path);
-  const newContent = trimmed.map(e => JSON.stringify(e)).join('\n') + '\n';
+  const newContent = repaired.map(entry => JSON.stringify(entry)).join('\n') + '\n';
   atomicWrite(path, newContent);
 
-  // The cut may have orphaned tool pairs (e.g. toolResult kept but its
-  // toolCall is now in the dropped section). Run repair to clean those up.
-  const postRepair = repairSessionFile(path);
-
-  const bytesAfter = readFileSync(path).length;
-  return {
-    reset: true,
-    reason,
-    entriesBefore: entries.length,
-    entriesAfter: trimmed.length - postRepair.droppedEntryIds.length,
-    bytesBefore,
-    bytesAfter,
-    backupPath,
-    postRepair,
-  };
-}
-
-// ── Error classifiers ────────────────────────────────────────────────────
-
-/**
- * Detect whether an error from pi-ai / the model provider indicates the
- * session has grown past the model's context window (input > max).
- *
- * Triggers soft-reset recovery in the memory lifecycle. Intentionally narrow:
- * only matches the well-known overflow phrasings, not generic 4xx errors.
- */
-export function isContextOverflowError(err: unknown): boolean {
-  if (!err) return false;
-  const msg = (err as { message?: string }).message ?? String(err);
-  const patterns = [
-    /prompt is too long/i,
-    /tokens?\s*[>>]\s*\d+\s*maximum/i,
-    /input is too long/i,
-    /context length exceeded/i,
-    /maximum context length/i,
-  ];
-  return patterns.some(p => p.test(msg));
-}
-
-/**
- * Detect whether an error from pi-ai / the model provider indicates a
- * tool-pairing mismatch that can be recovered by session repair.
- *
- * Matches Bedrock Converse and Anthropic error shapes. Intentionally narrow —
- * we don't want to repair on unrelated 400s.
- */
-export function isToolPairingError(err: unknown): boolean {
-  if (!err) return false;
-  const msg = (err as { message?: string }).message ?? String(err);
-  const name = (err as { name?: string }).name ?? '';
-
-  // Bedrock Converse: "messages.N: `tool_use` ids were found without `tool_result` blocks..."
-  // Anthropic direct: similar phrasing
-  const patterns = [
-    /tool_use.*without.*tool_result/i,
-    /tool_result.*without.*tool_use/i,
-    /toolUse.*without.*toolResult/i,
-    /unmatched.*tool.?use/i,
-    /orphan.*tool/i,
-  ];
-
-  if (patterns.some(p => p.test(msg))) return true;
-
-  // Bedrock ValidationException may carry the pairing text in nested fields
-  // (e.g. err.cause.message, $metadata). Only stringify-search when the error
-  // *looks* like a Bedrock validation error — avoid noisy matches on unrelated
-  // messages that happen to contain '400'.
-  const httpStatus =
-    (err as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode;
-  if (name === 'ValidationException' || httpStatus === 400) {
-    try {
-      const full = JSON.stringify(err);
-      if (patterns.some(p => p.test(full))) return true;
-    } catch {
-      /* circular structure — give up */
-    }
-  }
-  return false;
+  return { ...report, backupPath };
 }

package/src/agents/shared/session-soft-reset.ts

@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs';
+import {
+  assertSessionFileExists,
+  atomicWrite,
+  backupFile,
+  parseSessionFile,
+  repairEntriesInMemory,
+  type SessionFileEntry,
+  type SessionRepairReport,
+} from './session-repair-internal';
+
+export interface SoftResetOptions {
+  /** Keep at most this many user turns from the tail (default: 8). */
+  keepRecentUserTurns?: number;
+  /** Hard cap on jsonl bytes after trim (default: 250_000 ≈ 60–80k tokens). */
+  maxBytes?: number;
+}
+
+export interface SoftResetReport {
+  reset: boolean;
+  reason: string;
+  entriesBefore: number;
+  entriesAfter: number;
+  bytesBefore: number;
+  bytesAfter: number;
+  backupPath?: string;
+  /** Tool-pairing repair report on the trimmed file (orphans created by the cut). */
+  postRepair?: SessionRepairReport;
+}
+
+function findSoftResetCutIndex(
+  entries: SessionFileEntry[],
+  keepRecentUserTurns: number,
+  maxBytes: number,
+): { cutIdx: number; reason: string } {
+  let userTurnsSeen = 0;
+  let bytesAccumulated = 0;
+  let lastUserIdx = -1;
+
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    bytesAccumulated += Buffer.byteLength(JSON.stringify(entry), 'utf8') + 1;
+    if (entry.type === 'message' && entry.message?.role === 'user') {
+      userTurnsSeen++;
+      lastUserIdx = i;
+      if (userTurnsSeen >= keepRecentUserTurns) {
+        return { cutIdx: i, reason: `kept-${userTurnsSeen}-user-turns` };
+      }
+    }
+    if (bytesAccumulated > maxBytes && userTurnsSeen > 0) {
+      return { cutIdx: lastUserIdx, reason: `byte-cap-${bytesAccumulated}b` };
+    }
+  }
+
+  return { cutIdx: 1, reason: 'fewer-turns-than-target' };
+}
+
+function buildTrimmedEntries(entries: SessionFileEntry[], cutIdx: number): SessionFileEntry[] {
+  const header = entries[0];
+  const tail = entries.slice(cutIdx);
+  if (tail.length > 0 && tail[0].parentId !== undefined) {
+    tail[0] = { ...tail[0], parentId: null };
+  }
+  return [header, ...tail];
+}
+
+export function softResetSessionFile(
+  path: string,
+  options: SoftResetOptions = {},
+): SoftResetReport {
+  assertSessionFileExists(path);
+
+  const keepRecentUserTurns = options.keepRecentUserTurns ?? 8;
+  const maxBytes = options.maxBytes ?? 250_000;
+
+  const entries = parseSessionFile(path);
+  const bytesBefore = readFileSync(path).length;
+
+  if (entries.length < 4) {
+    return {
+      reset: false,
+      reason: 'session-too-small',
+      entriesBefore: entries.length,
+      entriesAfter: entries.length,
+      bytesBefore,
+      bytesAfter: bytesBefore,
+    };
+  }
+
+  const { cutIdx, reason } = findSoftResetCutIndex(entries, keepRecentUserTurns, maxBytes);
+  if (cutIdx <= 1) {
+    return {
+      reset: false,
+      reason: `cut-at-start (${reason})`,
+      entriesBefore: entries.length,
+      entriesAfter: entries.length,
+      bytesBefore,
+      bytesAfter: bytesBefore,
+    };
+  }
+
+  const trimmed = buildTrimmedEntries(entries, cutIdx);
+  const repaired = repairEntriesInMemory(trimmed);
+
+  const backupPath = backupFile(path);
+  const newContent = repaired.entries.map(entry => JSON.stringify(entry)).join('\n') + '\n';
+  atomicWrite(path, newContent);
+
+  const bytesAfter = Buffer.byteLength(newContent, 'utf8');
+  return {
+    reset: true,
+    reason,
+    entriesBefore: entries.length,
+    entriesAfter: repaired.entries.length,
+    bytesBefore,
+    bytesAfter,
+    backupPath,
+    postRepair: repaired.report,
+  };
+}

package/src/memory/lifecycle.ts

@@ -16,7 +16,7 @@ import { shouldInjectMemory, classifyContextPressure, isSoftFlushOnCooldown } fr
 import { buildMemoryInjection, injectMemoryIntoMessage } from "./inject";
 import { buildFlushPrompt } from "./prompts";
 import { bootstrapMemoryFiles } from "./bootstrap";
-import { isContextOverflowError } from "../agents/shared/session-repair";
+import { isContextOverflowError } from "../agents/shared/error-classifiers";
 import { appendFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -51,6 +51,32 @@ function appendCompactLog(entry: CompactLogEntry): void {
     .catch((err) => console.warn(`[memory] timing log write failed:`, (err as Error).message));
 }
 
+async function attemptSoftResetRecovery(
+  err: unknown,
+  threadId: string,
+  agent: AgentAdapter,
+  onProgress?: (step: string) => void | Promise<void>,
+): Promise<{ attempted: boolean; succeeded: boolean }> {
+  if (!isContextOverflowError(err) || !agent.softReset) {
+    return { attempted: false, succeeded: false };
+  }
+
+  try {
+    await onProgress?.("♻️ Session overflowed — soft-resetting to recent turns...");
+    const report = await agent.softReset(threadId);
+    if (report?.reset) {
+      console.warn(`[memory] soft-reset recovered ${threadId} from overflow`);
+      return { attempted: true, succeeded: true };
+    }
+
+    console.warn(`[memory] soft-reset returned no-op for ${threadId} (${(report as { reason?: string } | null)?.reason ?? "unknown"})`);
+    return { attempted: true, succeeded: false };
+  } catch (resetErr) {
+    console.error(`[memory] soft-reset failed for ${threadId}:`, (resetErr as Error).message);
+    return { attempted: true, succeeded: false };
+  }
+}
+
 // ── Memory mode detection ────────────────────────────
 
 /**
@@ -360,34 +386,7 @@ export async function flushMemoryThenCompact(
   } catch (err) {
     const errMsg = (err as Error).message;
     console.error(`[memory] flush+compact failed for ${threadId}:`, errMsg);
-
-    // Recovery path: when the session has grown past the model's context
-    // window, the summarizer prompt itself overflows and compact() throws
-    // "prompt is too long". Threshold tuning prevents *new* sessions from
-    // hitting this, but does nothing for sessions already past the line.
-    // Trim the on-disk session jsonl to its most recent N user turns and
-    // mark the next turn for a fresh memory injection. We do NOT retry
-    // compact inline — that would extend the thread lock for another long
-    // operation. The trimmed session is small enough that the next user
-    // turn proceeds normally; any soft pressure from injected memory will
-    // trigger a regular compact later.
-    let softResetAttempted = false;
-    let softResetSucceeded = false;
-    if (isContextOverflowError(err) && agent.softReset) {
-      softResetAttempted = true;
-      try {
-        await onProgress?.("♻️ Session overflowed — soft-resetting to recent turns...");
-        const report = await agent.softReset(threadId);
-        if (report?.reset) {
-          softResetSucceeded = true;
-          console.warn(`[memory] soft-reset recovered ${threadId} from overflow`);
-        } else {
-          console.warn(`[memory] soft-reset returned no-op for ${threadId} (${(report as { reason?: string } | null)?.reason ?? "unknown"})`);
-        }
-      } catch (resetErr) {
-        console.error(`[memory] soft-reset failed for ${threadId}:`, (resetErr as Error).message);
-      }
-    }
+    const recovery = await attemptSoftResetRecovery(err, threadId, agent, onProgress);
 
     appendCompactLog({
       threadId,
@@ -401,13 +400,13 @@ export async function flushMemoryThenCompact(
       totalMs: Date.now() - t0,
       model: flushModel ?? "default",
       status: "failed",
-      error: (softResetAttempted
-        ? `${softResetSucceeded ? "soft-reset-recovered" : "soft-reset-failed"}: ${errMsg}`
+      error: (recovery.attempted
+        ? `${recovery.succeeded ? "soft-reset-recovered" : "soft-reset-failed"}: ${errMsg}`
         : errMsg).slice(0, 500),
     });
 
     try {
-      if (softResetSucceeded) {
+      if (recovery.succeeded) {
         // Soft reset cleared the overflow. Mark the next turn for memory
         // re-injection so the agent has its durable context, and clear the
         // pendingCompact flag — there's nothing left to compact now.