{"record":{"id":"afb460377a5c2de5","repo":"stablyai/orca","slug":"terminal-checkpoint-replay-is-unavailable","errorCode":null,"errorMessage":"Terminal checkpoint replay is unavailable","messagePattern":"Terminal checkpoint replay is unavailable","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"src/main/daemon/terminal-checkpoint-serializer.ts","lineNumber":232,"sourceCode":"  return writer.result()\n}\n\nasync function replaySnapshot(snapshot: TerminalSnapshot): Promise<HeadlessEmulator> {\n  const emulator = new HeadlessEmulator({\n    cols: snapshot.cols,\n    rows: snapshot.rows,\n    scrollback: Math.max(0, Math.min(50_000, snapshot.scrollbackLines))\n  })\n  const replay = new ColdRestoreReplayWriter(emulator)\n  try {\n    for (const segment of [\n      snapshot.scrollbackAnsi,\n      snapshot.rehydrateSequences,\n      snapshot.snapshotAnsi,\n      snapshot.pendingEscapeTailAnsi ?? ''\n    ]) {\n      if (!(await replay.write(segment))) {\n        throw new Error('Terminal checkpoint replay is unavailable')\n      }\n    }\n    emulator.setCwd(snapshot.cwd)\n    if (snapshot.lastTitle) {\n      emulator.setLastTitle(snapshot.lastTitle)\n    }\n    emulator.setRestoredOscLinks(snapshot.oscLinks)\n    return emulator\n  } catch (error) {\n    emulator.dispose()\n    throw error\n  }\n}\n\nexport async function serializeTerminalCheckpointWithinLimit(\n  snapshot: TerminalSnapshot,\n  metadata: CheckpointMetadata,\n  maxBytes: number","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/daemon/terminal-checkpoint-serializer.ts#L214-L250","documentation":"Thrown during checkpoint serialization fallback: the direct bounded JSON stringification exceeded the byte limit, so the serializer tries to replay the snapshot through a headless emulator to trim it. If ColdRestoreReplayWriter.write() returns false for any ANSI segment (scrollbackAnsi, rehydrateSequences, snapshotAnsi, pendingEscapeTailAnsi), the emulator could not replay it (e.g., exceeded operation/char budgets or rejected the input) and replay is unavailable.","triggerScenarios":"serializeTerminalCheckpointWithinLimit falls back to replaySnapshot, and emulator.writeSync returns false during replay of one of the four ANSI segments — typically because the segment is malformed, oversized, or trips the per-turn operation budget.","commonSituations":"A snapshot with extremely large or corrupt scrollback ANSI; a snapshot captured from an emulator whose escape sequences the headless replay cannot reproduce; a checkpoint just over the byte limit whose trimmed replay still fails.","solutions":["Let the caller treat checkpoint serialization as best-effort: catch the error and skip persisting this checkpoint rather than crashing.","Investigate the snapshot source if replay consistently fails (capture a cleaner snapshot with less scrollback).","Reduce the snapshot size before serialization (cap scrollbackRows at capture time).","Ensure the headless emulator's writeSync budget is not being exhausted by pathological escape sequences."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":"function isCheckpointReplayUnavailable(e: unknown): boolean {\n  return e instanceof Error && e.message === 'Terminal checkpoint replay is unavailable'\n}","tryCatchPattern":"try {\n  return await serializeTerminalCheckpointWithinLimit(snapshot, metadata, maxBytes)\n} catch (e) {\n  if (e instanceof Error && e.message === 'Terminal checkpoint replay is unavailable') {\n    // skip persisting this checkpoint; history is best-effort\n    return null\n  }\n  throw e\n}","preventionTips":["Treat checkpoint serialization as best-effort; never let it crash the session.","Cap scrollback at capture time so snapshots stay replayable.","Investigate recurring replay failures (likely corrupt/pathological ANSI in the snapshot)."],"tags":["checkpoint","replay","serialization","history"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}