{"record":{"id":"4f834b72e757824b","repo":"stablyai/orca","slug":"terminal-history-seed-transfer-exceeds-retained-by","errorCode":null,"errorMessage":"Terminal history seed transfer exceeds retained byte limit","messagePattern":"Terminal history seed transfer exceeds retained byte limit","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/daemon/terminal-history-seed-transfer-registry.ts","lineNumber":67,"sourceCode":"  }\n\n  append(ownerId: string, transferId: string, index: number, data: string): void {\n    const transfer = this.getOwned(ownerId, transferId)\n    if (transfer.finished) {\n      throw new Error('Terminal history seed transfer is already finished')\n    }\n    if (index !== transfer.chunks.length || index >= transfer.manifest.chunkCount) {\n      throw new Error('Terminal history seed chunk sequence mismatch')\n    }\n    if (data.length === 0 || data.length > TERMINAL_HISTORY_SEED_CHUNK_CODE_UNITS) {\n      throw new Error('Terminal history seed chunk size is invalid')\n    }\n    const utf8Bytes = Buffer.byteLength(data, 'utf8')\n    if (\n      transfer.codeUnits + data.length > transfer.manifest.codeUnits ||\n      this.retainedBytes + utf8Bytes > this.maxRetainedBytes\n    ) {\n      throw new Error('Terminal history seed transfer exceeds retained byte limit')\n    }\n    transfer.chunks.push(data)\n    transfer.codeUnits += data.length\n    transfer.utf8Bytes += utf8Bytes\n    transfer.hash.update(Buffer.from(data, 'utf16le'))\n    this.retainedBytes += utf8Bytes\n    this.refreshExpiry(transferId, transfer)\n  }\n\n  finish(ownerId: string, transferId: string): void {\n    const transfer = this.getOwned(ownerId, transferId)\n    if (transfer.finished) {\n      throw new Error('Terminal history seed transfer is already finished')\n    }\n    if (\n      transfer.chunks.length !== transfer.manifest.chunkCount ||\n      transfer.codeUnits !== transfer.manifest.codeUnits\n    ) {","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/daemon/terminal-history-seed-transfer-registry.ts#L49-L85","documentation":"Thrown by TerminalHistorySeedTransferRegistry.append when appending a chunk would push cumulative retained bytes over maxRetainedBytes (default 200 MB, TERMINAL_HISTORY_CHECKPOINT_MAX_BYTES) or would exceed the manifest's declared total codeUnits. The registry tracks retainedBytes across all transfers to bound daemon memory; a single append that breaches either budget is rejected and the transfer is left consistent.","triggerScenarios":"append(ownerId, transferId, index, data) where this.retainedBytes + utf8Bytes(data) > maxRetainedBytes, or transfer.codeUnits + data.length > manifest.codeUnits. The manifest declared fewer code units than the client is sending, or total memory is saturated.","commonSituations":"A manifest whose codeUnits understates the actual seed size; many concurrent transfers whose retained bytes collectively exceed 200 MB; a client re-chunking with different boundaries than the manifest measured.","solutions":["Re-measure the seed with measureTerminalHistorySeed and send a manifest whose codeUnits matches the actual chunks exactly.","Reduce the number of concurrent transfers so retained bytes stay under 200 MB.","Chunk the seed with iterateTerminalHistorySeedChunks so chunk sizes and totals match the manifest.","Abort and restart the transfer with a corrected manifest if the size estimate was wrong."],"exampleFix":"// before: manifest with a guessed codeUnits\nregistry.start(id, { chunkCount, codeUnits: guessed, sha256 })\n\n// after: measure exact metrics\nconst { chunkCount, codeUnits, sha256 } = measureTerminalHistorySeed(segments)\nregistry.start(id, { chunkCount, codeUnits, sha256 })","handlingStrategy":"validation","validationCode":"import { measureTerminalHistorySeed, iterateTerminalHistorySeedChunks } from './terminal-history-seed-chunks'\n// Build the manifest from the exact chunks you will send\nconst metrics = measureTerminalHistorySeed(segments)\n// Then verify each append stays within manifest.codeUnits and global budget\nfunction appendFits(transferCodeUnits: number, chunk: string, manifestCodeUnits: number): boolean {\n  return transferCodeUnits + chunk.length <= manifestCodeUnits\n}","typeGuard":"function isSeedRetainedByteLimit(e: unknown): boolean {\n  return e instanceof Error && e.message === 'Terminal history seed transfer exceeds retained byte limit'\n}","tryCatchPattern":"try {\n  registry.append(ownerId, transferId, index, data)\n} catch (e) {\n  if (e instanceof Error && e.message === 'Terminal history seed transfer exceeds retained byte limit') {\n    // abort and restart with a corrected manifest / fewer concurrent transfers\n    registry.abort(ownerId, transferId)\n  } else { throw e }\n}","preventionTips":["Always measure with measureTerminalHistorySeed so manifest.codeUnits matches the chunks exactly.","Chunk with iterateTerminalHistorySeedChunks to keep boundaries consistent.","Limit concurrent transfers so total retained bytes stay under 200 MB."],"tags":["history","seed-transfer","limits","memory"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}