@remodex/rmx 1.0.2

package/src/android-remote/session-command-recovery.ts

@@ -0,0 +1,1384 @@
+import { realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getCodexHome } from "../codex/paths";
+import { planUpdateFromToolCall, toolItem } from "./desktop-session-stream";
+import { fileChangesFromToolCall, type AndroidRemoteFileChange } from "./file-change-parser";
+import {
+  canonicalUserMessageText,
+  publicUserMessageText,
+} from "./user-message-identity";
+import { resolveThreadSourcePaths } from "./thread-source-paths";
+
+type JsonRecord = Record<string, unknown>;
+
+const MAX_RECORD_BYTES = 2 * 1024 * 1024;
+const MAX_COMMAND_BYTES = 64 * 1024;
+const MAX_OUTPUT_BYTES = 64 * 1024;
+const MAX_CACHE_ENTRIES = 6;
+
+type RecoveredCommand = {
+  callId: string;
+  itemId: string;
+  order: number;
+  command: string;
+  status: string;
+  output: string | null;
+  exitCode: number | null;
+  durationMs: number | null;
+};
+
+type RecoveredFileChange = {
+  callId: string;
+  itemId: string;
+  order: number;
+  status: string;
+  changes: AndroidRemoteFileChange[];
+};
+
+type RecoveredActivity = {
+  callId: string;
+  itemId: string;
+  order: number;
+  item: JsonRecord;
+};
+
+type RecoveredTurnItem = {
+  order: number;
+  item: JsonRecord;
+};
+
+type RecoveredTurn = {
+  id: string;
+  order: number;
+  status: "inProgress" | "completed" | "interrupted" | "failed";
+  startedAt: number | null;
+  completedAt: number | null;
+  durationMs: number | null;
+  error: JsonRecord | null;
+  collaborationMode: JsonRecord | null;
+  items: Map<string, RecoveredTurnItem>;
+  canonicalItemEvents: boolean;
+  durableUserMessages: boolean;
+};
+
+type PendingDurableUserMessage = {
+  turnId: string;
+  order: number;
+  item: JsonRecord;
+  comparisonText: string;
+};
+
+type TurnRecovery = {
+  commands: Map<string, RecoveredCommand>;
+  fileChanges: Map<string, RecoveredFileChange>;
+  activities: Map<string, RecoveredActivity>;
+  responseOrder: Map<string, number>;
+  anchors: Array<{
+    type: "userMessage" | "agentMessage" | "reasoning" | "mcpToolCall" | "fileChange";
+    order: number;
+  }>;
+};
+
+type SessionCache = {
+  canonicalPath: string;
+  device: number | bigint;
+  inode: number | bigint;
+  size: number;
+  completeOffset: number;
+  firstTimestamp: number | null;
+  lastTimestamp: number | null;
+  threadId: string | null;
+  currentTurnId: string | null;
+  nextTurnPlanMode: boolean;
+  turnsInOrder: string[];
+  recoveredTurns: Map<string, RecoveredTurn>;
+  turns: Map<string, TurnRecovery>;
+  pendingUserMessage: PendingDurableUserMessage | null;
+  touchedAt: number;
+};
+
+export interface AndroidRemoteCommandRecovery {
+  enrichThread(thread: JsonRecord, sourcePaths?: readonly string[]): Promise<JsonRecord>;
+  clear(): void;
+}
+
+export type AndroidRemoteSessionCommandRecoveryOptions = {
+  codexHome?: string;
+  now?: () => number;
+};
+
+function record(value: unknown): JsonRecord | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as JsonRecord
+    : null;
+}
+
+function stringValue(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function bounded(value: string, maximumBytes: number): string {
+  const encoded = new TextEncoder().encode(value);
+  if (encoded.byteLength <= maximumBytes) return value;
+  return new TextDecoder().decode(encoded.subarray(0, maximumBytes)).replace(/\uFFFD$/u, "");
+}
+
+function turnRecovery(turns: Map<string, TurnRecovery>, turnId: string): TurnRecovery {
+  const existing = turns.get(turnId);
+  if (existing) return existing;
+  const created: TurnRecovery = {
+    commands: new Map(),
+    fileChanges: new Map(),
+    activities: new Map(),
+    responseOrder: new Map(),
+    anchors: [],
+  };
+  turns.set(turnId, created);
+  return created;
+}
+
+function recoveredTurn(cache: SessionCache, turnId: string, order: number): RecoveredTurn {
+  const existing = cache.recoveredTurns.get(turnId);
+  if (existing) return existing;
+  const created: RecoveredTurn = {
+    id: turnId,
+    order,
+    status: "inProgress",
+    startedAt: null,
+    completedAt: null,
+    durationMs: null,
+    error: null,
+    collaborationMode: null,
+    items: new Map(),
+    canonicalItemEvents: false,
+    durableUserMessages: false,
+  };
+  cache.recoveredTurns.set(turnId, created);
+  cache.turnsInOrder.push(turnId);
+  return created;
+}
+
+function timestampSeconds(value: unknown): number | null {
+  const numeric = finiteNumber(value);
+  if (numeric !== null) {
+    return numeric > 10_000_000_000 ? numeric / 1_000 : numeric;
+  }
+  const parsed = Date.parse(stringValue(value));
+  return Number.isFinite(parsed) ? parsed / 1_000 : null;
+}
+
+function durationMilliseconds(value: unknown): number | null {
+  const direct = finiteNumber(value);
+  if (direct !== null) return Math.max(0, Math.round(direct));
+  const row = record(value);
+  if (!row) return null;
+  const seconds = finiteNumber(row.secs) ?? finiteNumber(row.seconds) ?? 0;
+  const nanos = finiteNumber(row.nanos) ?? finiteNumber(row.nanoseconds) ?? 0;
+  return Math.max(0, Math.round(seconds * 1_000 + nanos / 1_000_000));
+}
+
+function camelKey(value: string): string {
+  return value.replace(/_([a-z0-9])/gu, (_match, letter: string) => letter.toUpperCase());
+}
+
+function camelEnum(value: string): string {
+  return camelKey(value.toLowerCase());
+}
+
+function normalizedStatus(value: unknown, fallback = ""): string {
+  const status = stringValue(value).trim();
+  return status ? camelEnum(status) : fallback;
+}
+
+function deepCamelValue(value: unknown, depth = 0): unknown {
+  if (depth > 8) return null;
+  if (Array.isArray(value)) return value.slice(0, 256).map(entry => deepCamelValue(entry, depth + 1));
+  const row = record(value);
+  if (!row) return value;
+  const output: JsonRecord = {};
+  for (const [key, entry] of Object.entries(row).slice(0, 256)) {
+    output[camelKey(key)] = deepCamelValue(entry, depth + 1);
+  }
+  return output;
+}
+
+function localPath(value: unknown): string {
+  const path = stringValue(value).trim();
+  if (!path.toLowerCase().startsWith("file://")) return path;
+  try {
+    return fileURLToPath(path);
+  } catch {
+    return path;
+  }
+}
+
+function itemType(value: unknown): string {
+  const raw = stringValue(value).trim();
+  const known: Record<string, string> = {
+    AgentMessage: "agentMessage",
+    CollabAgentToolCall: "collabAgentToolCall",
+    CommandExecution: "commandExecution",
+    ContextCompaction: "contextCompaction",
+    DynamicToolCall: "dynamicToolCall",
+    EnteredReviewMode: "reviewMarker",
+    ExitedReviewMode: "reviewMarker",
+    FileChange: "fileChange",
+    ImageGeneration: "imageGeneration",
+    ImageView: "imageView",
+    McpToolCall: "mcpToolCall",
+    Plan: "plan",
+    Reasoning: "reasoning",
+    ReviewMarker: "reviewMarker",
+    SubAgentActivity: "subAgentActivity",
+    UserInputRequest: "userInputRequest",
+    UserMessage: "userMessage",
+    WebSearch: "webSearch",
+  };
+  return known[raw] ?? (raw ? `${raw.charAt(0).toLowerCase()}${raw.slice(1)}` : "");
+}
+
+function normalizedFileChanges(value: unknown): JsonRecord[] {
+  const changes = record(value);
+  if (changes) {
+    return Object.entries(changes).slice(0, 64).flatMap(([path, rawChange]) => {
+      const change = record(deepCamelValue(rawChange));
+      if (!path || !change) return [];
+      const kind = stringValue(change.type).trim() || "update";
+      const diff = stringValue(change.unifiedDiff).trim();
+      const movePath = stringValue(change.movePath).trim();
+      return [{
+        path,
+        kind: {
+          type: kind,
+          ...(movePath ? { movePath } : {}),
+        },
+        ...(diff ? { diff: bounded(diff, 1024 * 1024) } : {}),
+      }];
+    });
+  }
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, 64).flatMap(rawChange => {
+    const change = record(deepCamelValue(rawChange));
+    return change ? [change] : [];
+  });
+}
+
+/**
+ * `item_completed` rollout events contain Codex's already-structured public
+ * ThreadItem snapshot, but use Rust's persisted enum/key spelling. Normalize
+ * that durable snapshot instead of trying to infer UI rows from raw tool JSON.
+ */
+function normalizedCompletedItem(value: unknown, completed: boolean): JsonRecord | null {
+  const raw = record(value);
+  const type = itemType(raw?.type);
+  const id = stringValue(raw?.id).trim();
+  if (!raw || !type || !id) return null;
+  const common = record(deepCamelValue(raw)) ?? {};
+
+  if (type === "userMessage") {
+    return {
+      type,
+      id,
+      clientId: stringValue(raw.client_id ?? raw.clientId).trim() || null,
+      content: Array.isArray(raw.content)
+        ? raw.content.slice(0, 128).map(entry => deepCamelValue(entry))
+        : [],
+    };
+  }
+  if (type === "agentMessage") {
+    const content = Array.isArray(raw.content) ? raw.content : [];
+    const text = content.flatMap(entry => {
+      const row = record(entry);
+      const part = stringValue(row?.text);
+      return part ? [part] : [];
+    }).join("");
+    return {
+      type,
+      id,
+      text: bounded(text || stringValue(raw.text), 2 * 1024 * 1024),
+      phase: stringValue(raw.phase).trim() || null,
+      memoryCitation: deepCamelValue(raw.memory_citation ?? raw.memoryCitation) ?? null,
+    };
+  }
+  if (type === "reasoning") {
+    const summary = Array.isArray(raw.summary_text ?? raw.summary)
+      ? (raw.summary_text ?? raw.summary) as unknown[]
+      : [];
+    const content = Array.isArray(raw.raw_content ?? raw.content)
+      ? (raw.raw_content ?? raw.content) as unknown[]
+      : [];
+    return {
+      type,
+      id,
+      summary: summary.flatMap(entry => typeof entry === "string" ? [entry] : []),
+      content: content.flatMap(entry => typeof entry === "string" ? [entry] : []),
+    };
+  }
+  if (type === "commandExecution") {
+    const command = Array.isArray(raw.command)
+      ? raw.command.flatMap(entry => typeof entry === "string" ? [entry] : []).join(" ")
+      : stringValue(raw.command);
+    const rawCommandActions = raw.parsed_cmd ?? raw.commandActions;
+    const output = stringValue(raw.aggregated_output ?? raw.aggregatedOutput)
+      || [stringValue(raw.stdout), stringValue(raw.stderr)].filter(Boolean).join("\n");
+    return {
+      type,
+      id,
+      pluginId: stringValue(raw.plugin_id ?? raw.pluginId).trim() || null,
+      scriptPath: stringValue(raw.script_path ?? raw.scriptPath).trim() || null,
+      command: bounded(command, MAX_COMMAND_BYTES),
+      cwd: localPath(raw.cwd),
+      processId: stringValue(raw.process_id ?? raw.processId).trim() || null,
+      source: camelEnum(stringValue(raw.source)),
+      status: normalizedStatus(raw.status, completed ? "completed" : "inProgress"),
+      commandActions: Array.isArray(rawCommandActions)
+        ? rawCommandActions.slice(0, 128).map(entry => deepCamelValue(entry))
+        : [],
+      aggregatedOutput: bounded(output, MAX_OUTPUT_BYTES),
+      exitCode: finiteNumber(raw.exit_code ?? raw.exitCode),
+      durationMs: durationMilliseconds(raw.duration_ms ?? raw.durationMs ?? raw.duration),
+    };
+  }
+  if (type === "fileChange") {
+    return {
+      type,
+      id,
+      status: normalizedStatus(raw.status, completed ? "completed" : "inProgress"),
+      changes: normalizedFileChanges(raw.changes),
+    };
+  }
+  if (type === "imageView") {
+    return { type, id, path: localPath(raw.path) };
+  }
+  if (type === "contextCompaction") {
+    return { type, id, status: completed ? "completed" : "inProgress" };
+  }
+  if (type === "reviewMarker") {
+    return {
+      type,
+      id,
+      state: raw.type === "EnteredReviewMode"
+        ? "entered"
+        : raw.type === "ExitedReviewMode"
+          ? "exited"
+          : stringValue(raw.state).trim(),
+    };
+  }
+
+  const normalized: JsonRecord = {
+    ...common,
+    type,
+    id,
+  };
+  if ("status" in raw || ["dynamicToolCall", "mcpToolCall", "collabAgentToolCall", "imageGeneration", "userInputRequest"].includes(type)) {
+    normalized.status = normalizedStatus(raw.status, completed ? "completed" : "inProgress");
+  }
+  const durationMs = durationMilliseconds(raw.duration_ms ?? raw.durationMs ?? raw.duration);
+  if (durationMs !== null) normalized.durationMs = durationMs;
+  delete normalized.duration;
+  return normalized;
+}
+
+function rememberRecoveredTurnItem(
+  cache: SessionCache,
+  turnId: string,
+  order: number,
+  value: unknown,
+  completed: boolean,
+): void {
+  const item = normalizedCompletedItem(value, completed);
+  if (!item) return;
+  const turn = recoveredTurn(cache, turnId, order);
+  const id = stringValue(item.id);
+  const existing = turn.items.get(id);
+  turn.items.set(id, {
+    order: existing?.order ?? order,
+    item: {
+      ...(existing?.item ?? {}),
+      ...item,
+    },
+  });
+  turn.canonicalItemEvents ||= completed;
+  if (item.type === "userMessage") turn.durableUserMessages = true;
+}
+
+function responseMessageText(payload: JsonRecord): string {
+  if (!Array.isArray(payload.content)) return "";
+  return payload.content.flatMap(value => {
+    const row = record(value);
+    return row && typeof row.text === "string" ? [row.text] : [];
+  }).join("");
+}
+
+function responseUserMessageContent(payload: JsonRecord): JsonRecord[] {
+  if (!Array.isArray(payload.content)) return [];
+  return payload.content.flatMap(value => {
+    const row = record(value);
+    const text = publicUserMessageText(row?.text);
+    return text ? [{ type: "text", text }] : [];
+  });
+}
+
+function recoveredUserMessageText(value: unknown): string {
+  const item = record(value);
+  if (!item || item.type !== "userMessage" || !Array.isArray(item.content)) return "";
+  return canonicalUserMessageText(item.content.flatMap(partValue => {
+    const part = record(partValue);
+    const text = stringValue(part?.text);
+    return text ? [text] : [];
+  }).join(""));
+}
+
+function rememberPendingUserMessage(
+  cache: SessionCache,
+  pending: PendingDurableUserMessage,
+  clientId = "",
+): void {
+  const turn = recoveredTurn(cache, pending.turnId, pending.order);
+  const item: JsonRecord = {
+    ...pending.item,
+    ...(clientId ? { clientId } : {}),
+  };
+  const matchingEntry = clientId
+    ? [...turn.items.entries()].find(([, existing]) =>
+        existing.item.type === "userMessage"
+        && stringValue(existing.item.clientId ?? existing.item.client_id).trim() === clientId)
+    : undefined;
+  const key = matchingEntry?.[0] ?? stringValue(item.id);
+  const existing = matchingEntry?.[1] ?? turn.items.get(key);
+  turn.items.set(key, {
+    order: existing?.order ?? pending.order,
+    item: {
+      ...(existing?.item ?? {}),
+      ...item,
+    },
+  });
+  turn.durableUserMessages = true;
+}
+
+function outputText(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return null;
+  const parts: string[] = [];
+  for (const entry of value) {
+    const row = record(entry);
+    if (!row) continue;
+    const text = stringValue(row.text);
+    if (text) parts.push(text);
+  }
+  return parts.length > 0 ? parts.join("") : null;
+}
+
+function parseCommandOutput(value: string): {
+  output: string;
+  exitCode: number | null;
+  durationMs: number | null;
+} {
+  let exitCode: number | null = null;
+  let durationMs: number | null = null;
+  let pastHeader = false;
+  const output: string[] = [];
+  for (const line of value.replaceAll("\r\n", "\n").split("\n")) {
+    if (!pastHeader) {
+      const exit = /^(?:Process|Command|Script) (?:exited|failed) with (?:code|exit code) (-?\d+)$/u.exec(line);
+      if (exit?.[1]) {
+        exitCode = Number.parseInt(exit[1], 10);
+        continue;
+      }
+      const wall = /^Wall time:?\s+([\d.]+)\s+(?:seconds?|s)$/u.exec(line);
+      if (wall?.[1]) {
+        durationMs = Math.round(Number.parseFloat(wall[1]) * 1_000);
+        continue;
+      }
+      if (
+        line === "Script completed" ||
+        line.startsWith("Command:") ||
+        line.startsWith("Chunk ID:") ||
+        line.startsWith("Original token count:")
+      ) {
+        continue;
+      }
+      if (line === "Output:" || line === "Final output:") {
+        pastHeader = true;
+        continue;
+      }
+    }
+    output.push(line);
+  }
+  return {
+    output: bounded(output.join("\n").trimEnd(), MAX_OUTPUT_BYTES),
+    exitCode,
+    durationMs,
+  };
+}
+
+function commandFromFunctionCall(payload: JsonRecord): string | null {
+  const raw = stringValue(payload.arguments);
+  if (!raw) return null;
+  try {
+    const args = record(JSON.parse(raw));
+    const command = args?.command;
+    if (typeof command === "string" && command.trim()) return command;
+    if (Array.isArray(command)) {
+      const joined = command.filter(value => typeof value === "string").join(" ").trim();
+      if (joined) return joined;
+    }
+    for (const key of ["cmd", "script", "input"] as const) {
+      const value = stringValue(args?.[key]).trim();
+      if (value) return value;
+    }
+  } catch {
+    return raw;
+  }
+  return raw;
+}
+
+function customExecCommand(payload: JsonRecord): string | null {
+  const input = stringValue(payload.input);
+  if (!input || !/\btools\.exec_command\s*\(/u.test(input)) return null;
+  return input;
+}
+
+function responseIdentity(payload: JsonRecord): string[] {
+  return [stringValue(payload.id), stringValue(payload.call_id)].filter(Boolean);
+}
+
+function consumeRecord(
+  parsed: JsonRecord,
+  order: number,
+  state: { currentTurnId: string | null; cache: SessionCache },
+): void {
+  const timestamp = timestampSeconds(parsed.timestamp);
+  if (timestamp !== null) {
+    state.cache.firstTimestamp = state.cache.firstTimestamp === null
+      ? timestamp
+      : Math.min(state.cache.firstTimestamp, timestamp);
+    state.cache.lastTimestamp = state.cache.lastTimestamp === null
+      ? timestamp
+      : Math.max(state.cache.lastTimestamp, timestamp);
+  }
+  const payload = record(parsed.payload);
+  if (!payload) return;
+  const rowType = stringValue(parsed.type);
+  const payloadType = stringValue(payload.type);
+  const userMessageIdentityEvent =
+    rowType === "event_msg" && payloadType === "user_message";
+  if (state.cache.pendingUserMessage) {
+    const pending = state.cache.pendingUserMessage;
+    const completedUserItem = rowType === "event_msg"
+      && (payloadType === "item_started" || payloadType === "item_completed")
+      ? normalizedCompletedItem(payload.item, payloadType === "item_completed")
+      : null;
+    const completedUserTurnId = stringValue(payload.turn_id) || state.currentTurnId;
+    if (
+      completedUserItem?.type === "userMessage"
+      && completedUserTurnId === pending.turnId
+      && recoveredUserMessageText(completedUserItem) === pending.comparisonText
+    ) {
+      // Current Codex rollouts persist one logical phone prompt twice: first
+      // as the native response item, then as the structured ThreadItem that
+      // carries the Android client id. They are adjacent representations of
+      // one message, not two chat bubbles. Preserve the earlier ordering while
+      // letting the structured item provide the stable visible identity.
+      state.cache.pendingUserMessage = null;
+      rememberRecoveredTurnItem(
+        state.cache,
+        pending.turnId,
+        pending.order,
+        payload.item,
+        payloadType === "item_completed",
+      );
+      return;
+    }
+    const clientId = userMessageIdentityEvent
+      ? stringValue(payload.client_id ?? payload.clientId).trim()
+      : "";
+    const comparisonText = userMessageIdentityEvent
+      ? canonicalUserMessageText(payload.message)
+      : "";
+    if (
+      userMessageIdentityEvent
+      && clientId
+      && comparisonText === pending.comparisonText
+    ) {
+      state.cache.pendingUserMessage = null;
+      rememberPendingUserMessage(state.cache, pending, clientId);
+      return;
+    }
+    state.cache.pendingUserMessage = null;
+    rememberPendingUserMessage(state.cache, pending);
+  }
+  // The identity event enriches the immediately preceding response item. It
+  // never represents another standalone Android message.
+  if (userMessageIdentityEvent) return;
+  if (rowType === "session_meta") {
+    const id = stringValue(payload.id) || stringValue(payload.session_id);
+    if (id && state.cache.threadId === null) state.cache.threadId = id;
+    return;
+  }
+  if (rowType === "turn_context") {
+    state.currentTurnId = stringValue(payload.turn_id) || null;
+    state.cache.currentTurnId = state.currentTurnId;
+    if (state.currentTurnId) {
+      const turn = recoveredTurn(state.cache, state.currentTurnId, order);
+      const collaborationMode = record(deepCamelValue(payload.collaboration_mode));
+      if (collaborationMode) turn.collaborationMode = collaborationMode;
+    }
+    return;
+  }
+  if (rowType === "event_msg") {
+    const event = stringValue(payload.type);
+    if (event === "thread_settings_applied") {
+      const settings = record(payload.thread_settings);
+      state.cache.nextTurnPlanMode =
+        stringValue(record(settings?.collaboration_mode)?.mode) === "plan";
+      return;
+    }
+    if (event === "task_started") {
+      state.currentTurnId = stringValue(payload.turn_id) || state.currentTurnId;
+      state.cache.currentTurnId = state.currentTurnId;
+      if (state.currentTurnId) {
+        const turn = recoveredTurn(state.cache, state.currentTurnId, order);
+        turn.status = "inProgress";
+        turn.startedAt = timestampSeconds(payload.started_at)
+          ?? timestampSeconds(parsed.timestamp)
+          ?? turn.startedAt;
+        if (
+          stringValue(payload.collaboration_mode_kind) === "plan"
+          || state.cache.nextTurnPlanMode
+        ) {
+          turn.collaborationMode = { mode: "plan" };
+        }
+      }
+      state.cache.nextTurnPlanMode = false;
+      return;
+    }
+    if (event === "task_complete" || event === "turn_aborted") {
+      const turnId = stringValue(payload.turn_id) || state.currentTurnId;
+      if (turnId) {
+        const turn = recoveredTurn(state.cache, turnId, order);
+        const error = record(deepCamelValue(payload.error));
+        turn.status = event === "turn_aborted"
+          ? "interrupted"
+          : error
+            ? "failed"
+            : "completed";
+        turn.error = error;
+        turn.startedAt = timestampSeconds(payload.started_at) ?? turn.startedAt;
+        turn.completedAt = timestampSeconds(payload.completed_at)
+          ?? timestampSeconds(parsed.timestamp)
+          ?? turn.completedAt;
+        turn.durationMs = durationMilliseconds(payload.duration_ms) ?? turn.durationMs;
+      }
+      if (!turnId || state.currentTurnId === turnId) {
+        state.currentTurnId = null;
+        state.cache.currentTurnId = null;
+      }
+      return;
+    }
+    if (event === "item_started" || event === "item_completed") {
+      const turnId = stringValue(payload.turn_id) || state.currentTurnId;
+      if (turnId) {
+        rememberRecoveredTurnItem(
+          state.cache,
+          turnId,
+          order,
+          payload.item,
+          event === "item_completed",
+        );
+      }
+      return;
+    }
+    if (event === "thread_rolled_back") {
+      const count = Math.max(0, Math.floor(finiteNumber(payload.num_turns) ?? 0));
+      const removed = state.cache.turnsInOrder.splice(Math.max(0, state.cache.turnsInOrder.length - count));
+      for (const turnId of removed) {
+        state.cache.recoveredTurns.delete(turnId);
+        state.cache.turns.delete(turnId);
+      }
+      state.currentTurnId = null;
+      state.cache.currentTurnId = null;
+      return;
+    }
+    if (event === "error" && state.currentTurnId) {
+      const turn = recoveredTurn(state.cache, state.currentTurnId, order);
+      turn.status = "failed";
+      turn.error = {
+        message: stringValue(payload.message) || "Codex task failed",
+      };
+    }
+  }
+  if (rowType === "compacted" && state.currentTurnId) {
+    const recovery = turnRecovery(state.cache.turns, state.currentTurnId);
+    const itemId = `context-compaction-${state.currentTurnId}`;
+    recovery.activities.set(itemId, {
+      callId: itemId,
+      itemId,
+      order,
+      item: { type: "contextCompaction", id: itemId, status: "inProgress" },
+    });
+    return;
+  }
+  if (rowType === "event_msg" && state.currentTurnId) {
+    const recovery = turnRecovery(state.cache.turns, state.currentTurnId);
+    const callId = stringValue(payload.call_id);
+    if (payload.type === "context_compacted") {
+      const itemId = `context-compaction-${state.currentTurnId}`;
+      const existing = recovery.activities.get(itemId);
+      recovery.activities.set(itemId, {
+        callId: itemId,
+        itemId,
+        order: existing?.order ?? order,
+        item: { type: "contextCompaction", id: itemId, status: "completed" },
+      });
+    } else if (payload.type === "mcp_tool_call_end") {
+      recovery.anchors.push({ type: "mcpToolCall", order });
+      if (callId) recovery.responseOrder.set(callId, order);
+    } else if (payload.type === "patch_apply_end") {
+      recovery.anchors.push({ type: "fileChange", order });
+      if (callId) recovery.responseOrder.set(callId, order);
+    }
+    return;
+  }
+  if (rowType === "response_item" && payloadType === "message" && payload.role === "user") {
+    const metadata = record(payload.internal_chat_message_metadata_passthrough);
+    const turnId = stringValue(metadata?.turn_id) || state.currentTurnId;
+    const id = stringValue(payload.id).trim();
+    const rawText = responseMessageText(payload);
+    if (!turnId || !id || !rawText) return;
+    state.currentTurnId = turnId;
+    state.cache.currentTurnId = turnId;
+    const recovery = turnRecovery(state.cache.turns, turnId);
+    recovery.anchors.push({ type: "userMessage", order });
+    recovery.responseOrder.set(id, order);
+    state.cache.pendingUserMessage = {
+      turnId,
+      order,
+      item: {
+        type: "userMessage",
+        id,
+        content: responseUserMessageContent(payload),
+      },
+      comparisonText: canonicalUserMessageText(rawText),
+    };
+    return;
+  }
+  if (rowType !== "response_item" || !state.currentTurnId) return;
+
+  const recovery = turnRecovery(state.cache.turns, state.currentTurnId);
+  for (const id of responseIdentity(payload)) {
+    if (!recovery.responseOrder.has(id)) recovery.responseOrder.set(id, order);
+  }
+  const type = payloadType;
+  const name = stringValue(payload.name);
+  if (type === "reasoning") {
+    recovery.anchors.push({ type: "reasoning", order });
+  } else if (type === "message") {
+    const role = stringValue(payload.role);
+    if (role === "user") recovery.anchors.push({ type: "userMessage", order });
+    else if (role === "assistant") recovery.anchors.push({ type: "agentMessage", order });
+  }
+  const callId = stringValue(payload.call_id) || stringValue(payload.id);
+  if (!callId) return;
+
+  const planUpdate = planUpdateFromToolCall(payload);
+  if (planUpdate) {
+    const itemId = `turn-plan-${state.currentTurnId}`;
+    recovery.activities.set(itemId, {
+      callId,
+      itemId,
+      order,
+      item: {
+        type: "planUpdate",
+        id: itemId,
+        status: "completed",
+        plan: planUpdate.plan,
+        ...(planUpdate.explanation ? { explanation: planUpdate.explanation } : {}),
+      },
+    });
+    return;
+  }
+
+  const fileChanges = fileChangesFromToolCall(payload);
+  if (fileChanges.length > 0) {
+    if (!recovery.fileChanges.has(callId)) {
+      recovery.fileChanges.set(callId, {
+        callId,
+        itemId: stringValue(payload.id) || callId,
+        order,
+        status: stringValue(payload.status) || "inProgress",
+        changes: fileChanges,
+      });
+    }
+    return;
+  }
+
+  let command: string | null = null;
+  if (type === "function_call" && ["exec_command", "shell", "shell_command"].includes(name)) {
+    command = commandFromFunctionCall(payload);
+  } else if (type === "custom_tool_call" && name === "exec") {
+    // New Codex sessions wrap every tool through a generic `exec` record.
+    // Only the wrappers that actually call exec_command are terminal rows;
+    // MCP calls and other nested tools must keep their own activity type.
+    command = customExecCommand(payload);
+  }
+  if (command) {
+    if (!recovery.commands.has(callId)) {
+      recovery.commands.set(callId, {
+        callId,
+        itemId: stringValue(payload.id) || callId,
+        order,
+        command: bounded(command, MAX_COMMAND_BYTES),
+        status: stringValue(payload.status) || "inProgress",
+        output: null,
+        exitCode: null,
+        durationMs: null,
+      });
+    }
+    return;
+  }
+
+  if (type === "function_call" || type === "custom_tool_call") {
+    const recoveredTool = toolItem(payload);
+    if (recoveredTool?.type === "dynamicToolCall") {
+      const recoveredToolName = stringValue(recoveredTool.tool);
+      // MCP calls already have a durable first-class `mcpToolCall` item in
+      // thread/read. Replaying their outer JavaScript router would duplicate
+      // one visible action under a second generic tool id.
+      if (!recoveredToolName.startsWith("mcp__")) {
+        const toolToken = recoveredToolName.split("__").at(-1);
+        const item = toolToken === "request_user_input"
+          ? {
+              type: "userInputRequest",
+              id: stringValue(recoveredTool.id) || callId,
+              status: "inProgress",
+              questions: record(recoveredTool.arguments)?.questions,
+            }
+          : recoveredTool;
+        recovery.activities.set(callId, {
+          callId,
+          itemId: stringValue(item.id) || callId,
+          order,
+          item,
+        });
+      }
+    }
+    return;
+  }
+
+  if (type !== "function_call_output" && type !== "custom_tool_call_output") return;
+  const rawOutput = outputText(payload.output);
+  const output = rawOutput === null ? null : parseCommandOutput(rawOutput);
+  const failed = typeof output?.exitCode === "number" && output.exitCode !== 0;
+  const recoveredActivity = recovery.activities.get(callId);
+  if (recoveredActivity) {
+    recoveredActivity.item = {
+      ...recoveredActivity.item,
+      status: failed ? "failed" : "completed",
+    };
+  }
+  const recoveredFileChange = recovery.fileChanges.get(callId);
+  if (recoveredFileChange) {
+    recoveredFileChange.status = failed ? "failed" : "completed";
+  }
+  const recovered = recovery.commands.get(callId);
+  if (!recovered || !output) return;
+  recovered.output = output.output;
+  recovered.exitCode = output.exitCode;
+  recovered.durationMs = output.durationMs;
+  recovered.status = failed ? "failed" : "completed";
+}
+
+async function scanSession(cache: SessionCache, startOffset: number): Promise<number> {
+  const decoder = new TextDecoder();
+  const stream = Bun.file(cache.canonicalPath).slice(startOffset).stream();
+  const reader = stream.getReader();
+  let absoluteOffset = startOffset;
+  let lineStart = startOffset;
+  let parts: Uint8Array[] = [];
+  let lineBytes = 0;
+  let oversized = false;
+  const state = { currentTurnId: cache.currentTurnId, cache };
+
+  const append = (bytes: Uint8Array) => {
+    lineBytes += bytes.byteLength;
+    if (lineBytes > MAX_RECORD_BYTES) {
+      oversized = true;
+      parts = [];
+    } else if (!oversized && bytes.byteLength > 0) {
+      parts.push(bytes.slice());
+    }
+  };
+
+  const emit = (nextOffset: number) => {
+    if (!oversized && lineBytes > 0) {
+      const joined = new Uint8Array(lineBytes);
+      let offset = 0;
+      for (const part of parts) {
+        joined.set(part, offset);
+        offset += part.byteLength;
+      }
+      try {
+        const parsed = record(JSON.parse(decoder.decode(joined)));
+        if (parsed) consumeRecord(parsed, lineStart, state);
+      } catch {
+        // A malformed or concurrently incomplete line is ignored. The next
+        // refresh rescans it because completeOffset advances only at newline.
+      }
+    }
+    lineStart = nextOffset;
+    parts = [];
+    lineBytes = 0;
+    oversized = false;
+  };
+
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      const chunk = value instanceof Uint8Array ? value : new Uint8Array(value);
+      let segmentStart = 0;
+      for (let index = 0; index < chunk.byteLength; index += 1) {
+        if (chunk[index] !== 0x0a) continue;
+        append(chunk.subarray(segmentStart, index));
+        absoluteOffset += index - segmentStart + 1;
+        emit(absoluteOffset);
+        segmentStart = index + 1;
+      }
+      append(chunk.subarray(segmentStart));
+      absoluteOffset += chunk.byteLength - segmentStart;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return lineStart;
+}
+
+function inside(root: string, candidate: string): boolean {
+  const path = relative(root, candidate);
+  return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}
+
+function itemId(item: JsonRecord): string {
+  return stringValue(item.id) || stringValue(item.callId) || stringValue(item.call_id);
+}
+
+function isUserMessageItem(item: JsonRecord): boolean {
+  const type = itemType(item.type);
+  return type === "userMessage"
+    || (type === "message" && stringValue(item.role).toLowerCase() === "user");
+}
+
+function userMessageClientId(item: JsonRecord): string {
+  return stringValue(
+    item.clientId
+    ?? item.client_id
+    ?? item.clientUserMessageId
+    ?? item.client_user_message_id,
+  ).trim();
+}
+
+function commandText(item: JsonRecord): string {
+  return stringValue(item.command).trim();
+}
+
+function terminalTurnStatus(value: unknown): boolean {
+  return ["completed", "interrupted", "failed"].includes(stringValue(value));
+}
+
+function mergeRecoveredTurnItems(
+  existingValue: unknown,
+  recovered: RecoveredTurn,
+): JsonRecord[] {
+  const existing = Array.isArray(existingValue)
+    ? existingValue.flatMap(value => record(value) ? [record(value)!] : [])
+    : [];
+  if (recovered.items.size === 0) return existing;
+  const unmatchedExisting = new Set(existing);
+  const recoveredItems = [...recovered.items.values()]
+    .sort((left, right) => left.order - right.order)
+    .map(({ item }) => {
+      const clientId = isUserMessageItem(item) ? userMessageClientId(item) : "";
+      const current = clientId
+        ? existing.find(candidate =>
+            unmatchedExisting.has(candidate)
+            && isUserMessageItem(candidate)
+            && userMessageClientId(candidate) === clientId)
+        : existing.find(candidate =>
+            unmatchedExisting.has(candidate) && itemId(candidate) === itemId(item));
+      if (current) unmatchedExisting.delete(current);
+      return current ? { ...current, ...item } : item;
+    });
+  // Durable rollout user-message records are authoritative. Once at least one
+  // exists for a turn, unmatched app-server-only user previews are discarded
+  // instead of becoming permanent duplicate/failed prompt bubbles.
+  return [
+    ...recoveredItems,
+    ...existing.filter(item =>
+      unmatchedExisting.has(item)
+      && (!recovered.durableUserMessages || !isUserMessageItem(item))),
+  ];
+}
+
+function mergeRecoveredTurns(thread: JsonRecord, cache: SessionCache): JsonRecord {
+  if (cache.threadId !== stringValue(thread.id) || cache.recoveredTurns.size === 0) return thread;
+  const existing = Array.isArray(thread.turns)
+    ? thread.turns.flatMap(value => record(value) ? [record(value)!] : [])
+    : [];
+  const existingById = new Map(existing.map(turn => [stringValue(turn.id), turn]));
+  const merged = [...existing];
+  let changed = false;
+
+  for (const recovered of cache.recoveredTurns.values()) {
+    const current = existingById.get(recovered.id);
+    const currentStatus = stringValue(current?.status);
+    const status = terminalTurnStatus(recovered.status)
+      ? recovered.status
+      : terminalTurnStatus(currentStatus)
+        ? currentStatus
+        : recovered.status;
+    const next: JsonRecord = {
+      ...(current ?? {}),
+      id: recovered.id,
+      status,
+      startedAt: recovered.startedAt ?? finiteNumber(current?.startedAt),
+      completedAt: terminalTurnStatus(status)
+        ? recovered.completedAt ?? finiteNumber(current?.completedAt)
+        : null,
+      ...(recovered.durationMs !== null
+        ? { durationMs: recovered.durationMs }
+        : current?.durationMs === undefined
+          ? {}
+          : { durationMs: current.durationMs }),
+      ...(recovered.error
+        ? { error: recovered.error }
+        : current?.error === undefined
+          ? {}
+          : { error: current.error }),
+      ...(recovered.collaborationMode
+        ? { collaborationMode: recovered.collaborationMode }
+        : current?.collaborationMode === undefined
+          ? {}
+          : { collaborationMode: current.collaborationMode }),
+      items: mergeRecoveredTurnItems(current?.items, recovered),
+      _androidRemoteRecoveredOrder: recovered.order,
+    };
+    if (current) {
+      const index = merged.indexOf(current);
+      if (index >= 0) merged[index] = next;
+    } else {
+      merged.push(next);
+    }
+    changed = true;
+  }
+
+  if (!changed) return thread;
+  const ordered = merged.sort((left, right) => {
+    const leftStarted = finiteNumber(left.startedAt);
+    const rightStarted = finiteNumber(right.startedAt);
+    if (leftStarted !== null && rightStarted !== null && leftStarted !== rightStarted) {
+      return leftStarted - rightStarted;
+    }
+    if (leftStarted !== null) return -1;
+    if (rightStarted !== null) return 1;
+    return (finiteNumber(left._androidRemoteRecoveredOrder) ?? Number.MAX_SAFE_INTEGER)
+      - (finiteNumber(right._androidRemoteRecoveredOrder) ?? Number.MAX_SAFE_INTEGER);
+  }).map(turn => {
+    if (!("_androidRemoteRecoveredOrder" in turn)) return turn;
+    const { _androidRemoteRecoveredOrder: _order, ...publicTurn } = turn;
+    return publicTurn;
+  });
+  const latestStartedAt = Math.max(
+    ...ordered.map(turn => finiteNumber(turn.startedAt) ?? Number.NEGATIVE_INFINITY),
+  );
+  const latestCompletedAt = Math.max(
+    ...ordered.map(turn => finiteNumber(turn.completedAt) ?? Number.NEGATIVE_INFINITY),
+  );
+  const latestActivityAt = Math.max(latestStartedAt, latestCompletedAt);
+  return {
+    ...thread,
+    turns: ordered,
+    ...(Number.isFinite(latestActivityAt)
+      ? {
+          updatedAt: Math.max(
+            finiteNumber(thread.updatedAt) ?? Number.NEGATIVE_INFINITY,
+            latestActivityAt,
+          ),
+        }
+      : {}),
+  };
+}
+
+function mergeRecoveredCommands(thread: JsonRecord, cache: SessionCache): JsonRecord {
+  if (cache.threadId !== stringValue(thread.id)) return thread;
+  const turns = Array.isArray(thread.turns) ? thread.turns : [];
+  let changed = false;
+  const mergedTurns = turns.map(value => {
+    const turn = record(value);
+    if (!turn) return value;
+    const recovery = cache.turns.get(stringValue(turn.id));
+    if (cache.recoveredTurns.get(stringValue(turn.id))?.canonicalItemEvents) return value;
+    if (
+      !recovery ||
+      (
+        recovery.commands.size === 0 &&
+        recovery.fileChanges.size === 0 &&
+        recovery.activities.size === 0
+      )
+    ) return value;
+    const items = Array.isArray(turn.items) ? turn.items : [];
+    const originalItems = items.flatMap(value => record(value) ? [record(value)!] : []);
+    const recoveredFileChanges = [...recovery.fileChanges.values()];
+    const usedFileChanges = new Set<string>();
+    let hydratedFileChanges = false;
+    const existingItems = originalItems.map(item => {
+      if (item.type !== "fileChange" || recoveredFileChanges.length === 0) return item;
+      const id = itemId(item);
+      const recovered = recoveredFileChanges.find(candidate =>
+        !usedFileChanges.has(candidate.callId) && (candidate.itemId === id || candidate.callId === id),
+      ) ?? recoveredFileChanges.find(candidate => !usedFileChanges.has(candidate.callId));
+      if (!recovered) return item;
+      usedFileChanges.add(recovered.callId);
+      if (Array.isArray(item.changes) && item.changes.length > 0) return item;
+      changed = true;
+      hydratedFileChanges = true;
+      return { ...item, changes: recovered.changes };
+    });
+    const existingIds = new Set(existingItems.map(itemId).filter(Boolean));
+    const existingCallIds = new Set(
+      existingItems.flatMap(item => {
+        const callId = stringValue(item.callId) || stringValue(item.call_id);
+        return callId ? [callId] : [];
+      }),
+    );
+    const existingCommands = new Set(
+      existingItems.filter(item => item.type === "commandExecution").map(commandText).filter(Boolean),
+    );
+    const recoveredCommandItems = [...recovery.commands.values()].flatMap(command => {
+      if (existingIds.has(command.itemId) || existingIds.has(command.callId)) return [];
+      if (existingCommands.has(command.command.trim())) return [];
+      return [{
+        type: "commandExecution",
+        id: command.itemId,
+        command: command.command,
+        cwd: stringValue(thread.cwd),
+        status: command.status,
+        exitCode: command.exitCode,
+        aggregatedOutput: command.output,
+        durationMs: command.durationMs,
+        processId: null,
+        commandActions: [],
+        _androidRemoteRecoveredOrder: command.order,
+      }];
+    });
+    const recoveredFileItems = recoveredFileChanges.flatMap(fileChange => {
+      if (usedFileChanges.has(fileChange.callId)) return [];
+      if (existingIds.has(fileChange.itemId) || existingIds.has(fileChange.callId)) return [];
+      return [{
+        type: "fileChange",
+        id: fileChange.itemId,
+        status: fileChange.status,
+        changes: fileChange.changes,
+        _androidRemoteRecoveredOrder: fileChange.order,
+      }];
+    });
+    const recoveredActivityItems = [...recovery.activities.values()].flatMap(activity => {
+      if (
+        existingIds.has(activity.itemId) ||
+        existingIds.has(activity.callId) ||
+        existingCallIds.has(activity.callId)
+      ) return [];
+      if (
+        activity.item.type === "contextCompaction" &&
+        existingItems.some(item => item.type === "contextCompaction")
+      ) return [];
+      if (
+        activity.item.type === "planUpdate" &&
+        existingItems.some(item => item.type === "planUpdate")
+      ) return [];
+      return [{ ...activity.item, _androidRemoteRecoveredOrder: activity.order }];
+    });
+    const recoveredItems = [
+      ...recoveredCommandItems,
+      ...recoveredFileItems,
+      ...recoveredActivityItems,
+    ];
+    if (recoveredItems.length === 0) {
+      return hydratedFileChanges ? { ...turn, items: existingItems } : value;
+    }
+    changed = true;
+    let anchorIndex = 0;
+    const positioned = existingItems.map((item, index) => {
+      let order = recovery.responseOrder.get(itemId(item)) ?? null;
+      if (
+        order === null &&
+        (
+          item.type === "userMessage" ||
+          item.type === "agentMessage" ||
+          item.type === "reasoning" ||
+          item.type === "mcpToolCall" ||
+          item.type === "fileChange"
+        )
+      ) {
+        for (; anchorIndex < recovery.anchors.length; anchorIndex += 1) {
+          const anchor = recovery.anchors[anchorIndex];
+          if (anchor?.type !== item.type) continue;
+          order = anchor.order;
+          anchorIndex += 1;
+          break;
+        }
+      }
+      return { item, index, order };
+    });
+    for (const item of recoveredItems) {
+      const order = typeof item._androidRemoteRecoveredOrder === "number"
+        ? item._androidRemoteRecoveredOrder
+        : Number.MAX_SAFE_INTEGER;
+      const nextKnown = positioned.findIndex(entry => entry.order !== null && entry.order > order);
+      if (nextKnown >= 0) {
+        positioned.splice(nextKnown, 0, { item, index: positioned.length, order });
+        continue;
+      }
+      let insertion = positioned.length;
+      for (let index = positioned.length - 1; index >= 0; index -= 1) {
+        const candidateOrder = positioned[index]?.order ?? null;
+        if (candidateOrder !== null && candidateOrder <= order) {
+          insertion = index + 1;
+          while (
+            insertion < positioned.length &&
+            positioned[insertion]?.order !== null &&
+            (positioned[insertion]?.order ?? Number.MAX_SAFE_INTEGER) <= order
+          ) {
+            insertion += 1;
+          }
+          break;
+        }
+      }
+      positioned.splice(insertion, 0, { item, index: positioned.length, order });
+    }
+    return {
+      ...turn,
+      items: positioned.map(({ item }) => {
+        if (!("_androidRemoteRecoveredOrder" in item)) return item;
+        const { _androidRemoteRecoveredOrder: _order, ...publicItem } = item;
+        return publicItem;
+      }),
+    };
+  });
+  return changed ? { ...thread, turns: mergedTurns } : thread;
+}
+
+export class AndroidRemoteSessionCommandRecovery implements AndroidRemoteCommandRecovery {
+  private readonly caches = new Map<string, SessionCache>();
+  private readonly codexHome: string;
+  private readonly now: () => number;
+
+  constructor(options: AndroidRemoteSessionCommandRecoveryOptions = {}) {
+    this.codexHome = options.codexHome ?? getCodexHome();
+    this.now = options.now ?? Date.now;
+  }
+
+  clear(): void {
+    this.caches.clear();
+  }
+
+  async enrichThread(thread: JsonRecord, sourcePaths: readonly string[] = []): Promise<JsonRecord> {
+    const threadId = stringValue(thread.id).trim();
+    if (!threadId) return thread;
+    try {
+      const candidates = await this.sourcePaths(threadId, [
+        stringValue(thread.path),
+        ...sourcePaths,
+      ]);
+      const caches: SessionCache[] = [];
+      for (const sourcePath of candidates) {
+        try {
+          const cache = await this.updateCache(sourcePath);
+          if (cache?.threadId === threadId) caches.push(cache);
+        } catch {
+          // A continuation can be archived or rotated while the sibling set is
+          // being traversed. Keep every other readable rollout in the merge.
+        }
+      }
+      caches.sort((left, right) =>
+        (left.firstTimestamp ?? Number.MAX_SAFE_INTEGER)
+          - (right.firstTimestamp ?? Number.MAX_SAFE_INTEGER)
+        || left.canonicalPath.localeCompare(right.canonicalPath));
+      let enriched = thread;
+      for (const cache of caches) enriched = mergeRecoveredTurns(enriched, cache);
+      for (const cache of caches) enriched = mergeRecoveredCommands(enriched, cache);
+      this.prune();
+      return enriched;
+    } catch {
+      // Session enrichment is optional. A missing, moving, or unreadable file
+      // must never stop Android from receiving Codex's normal thread result.
+      return thread;
+    }
+  }
+
+  private async sourcePaths(threadId: string, explicit: readonly string[]): Promise<string[]> {
+    return resolveThreadSourcePaths(threadId, explicit, {
+      codexHome: this.codexHome,
+      now: this.now,
+    });
+  }
+
+  private async updateCache(sourcePath: string): Promise<SessionCache | null> {
+    if (!sourcePath.toLowerCase().endsWith(".jsonl")) return null;
+    const [canonicalHome, canonicalPath] = await Promise.all([
+      realpath(resolve(this.codexHome)),
+      realpath(resolve(sourcePath)),
+    ]);
+    const sessionsRoot = resolve(canonicalHome, "sessions");
+    const archivedRoot = resolve(canonicalHome, "archived_sessions");
+    if (!inside(sessionsRoot, canonicalPath) && !inside(archivedRoot, canonicalPath)) return null;
+    const source = await stat(canonicalPath, { bigint: true });
+    if (!source.isFile() || source.size > BigInt(Number.MAX_SAFE_INTEGER)) return null;
+    const size = Number(source.size);
+    let cache = this.caches.get(canonicalPath);
+    if (
+      !cache ||
+      cache.device !== source.dev ||
+      cache.inode !== source.ino ||
+      size < cache.completeOffset
+    ) {
+      cache = {
+        canonicalPath,
+        device: source.dev,
+        inode: source.ino,
+        size: 0,
+        completeOffset: 0,
+        firstTimestamp: null,
+        lastTimestamp: null,
+        threadId: null,
+        currentTurnId: null,
+        nextTurnPlanMode: false,
+        turnsInOrder: [],
+        recoveredTurns: new Map(),
+        turns: new Map(),
+        pendingUserMessage: null,
+        touchedAt: this.now(),
+      };
+      this.caches.set(canonicalPath, cache);
+    }
+    if (size > cache.completeOffset) {
+      cache.completeOffset = await scanSession(cache, cache.completeOffset);
+      cache.size = size;
+    }
+    cache.touchedAt = this.now();
+    return cache;
+  }
+
+  private prune(): void {
+    if (this.caches.size <= MAX_CACHE_ENTRIES) return;
+    const oldest = [...this.caches.entries()]
+      .sort((first, second) => first[1].touchedAt - second[1].touchedAt)
+      .slice(0, this.caches.size - MAX_CACHE_ENTRIES);
+    for (const [path] of oldest) this.caches.delete(path);
+  }
+}