{"record":{"id":"fa8a047fff977847","repo":"paperclipai/paperclip","slug":"warm-run-transition-permits-only-its-exact-cached","errorCode":null,"errorMessage":"Warm run transition permits only its exact cached attachment replay.","messagePattern":"Warm run transition permits only its exact cached attachment replay\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/control-plane/durable-prp-control-plane.ts","lineNumber":1830,"sourceCode":"    return ticket;\n  }\n\n  queueCommand(\n    type: string,\n    payload: Record<string, unknown> = {},\n    commandId?: string,\n    deliverImmediately = false,\n  ): DurableRecoveryCoreCommand {\n    this.#store.assertWritable();\n    const transition = this.#store.state.warmTransition;\n    if (transition && transition.phase !== \"activated\") {\n      if (\n        commandId === transition.command.commandId &&\n        type === \"run.attach\" &&\n        canonicalJson(payload) === canonicalJson(transition.command.payload)\n      )\n        return transition.command;\n      throw new Error(\n        \"Warm run transition permits only its exact cached attachment replay.\",\n      );\n    }\n    if (\n      type === \"run.attach\" &&\n      payload.paperclipNextAuthority !== undefined &&\n      ![...this.#connections].some(\n        (connection) =>\n          connection.secureChannel !== null &&\n          connection.warmTransitionVersion === 1 &&\n          !connection.replayOnly,\n      )\n    ) {\n      throw new Error(\n        \"Warm run transition capability is required before attachment.\",\n      );\n    }\n    if (","sourceCodeStart":1812,"sourceCodeEnd":1848,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/control-plane/durable-prp-control-plane.ts#L1812-L1848","documentation":"During a warm run transition, command replay is deliberately restricted: only the exact cached run.attach command (matching commandId AND canonical JSON payload) associated with the transition may be replayed. Any other command id, command type, or altered payload during the warm transition is rejected to prevent tampering or duplicate attachment with different parameters.","triggerScenarios":"Replaying a run.attach command during a warm transition whose commandId differs from transition.command.commandId, or whose payload does not serialize identically (canonicalJson) to the cached transition.command.payload. Also thrown if a non-run.attach command is issued inside the exact-replay branch.","commonSituations":"Re-serializing the payload after JSON round-trips that change key order or numeric formatting; retry logic that sends an updated attach payload; sending new commands while a warm transition is in flight instead of after it completes.","solutions":["Replay the attach command with byte-identical payload to the one cached on the transition (same key order/content).","Reuse the original commandId stored on transition.command.","Defer any modified or new attach commands until after the warm transition completes and the connection exits replay-only mode.","Compare canonicalJson(payload) with canonicalJson(transition.command.payload) locally before sending."],"exampleFix":"// before\nawait conn.send({ type: \"run.attach\", commandId: newId, payload: { ...cachedPayload, extra: true } });\n// after\nawait conn.send({ type: \"run.attach\", commandId: transition.command.commandId, payload: transition.command.payload });","handlingStrategy":"validation","validationCode":"function canReplayAttach(transition, msg) {\n  return msg.commandId === transition.command.commandId &&\n    msg.type === \"run.attach\" &&\n    canonicalJson(msg.payload) === canonicalJson(transition.command.payload);\n}\nif (!canReplayAttach(transition, msg)) throw new Error(\"non-identical attach replay\");","typeGuard":"function isExactCachedReplay(transition, msg) {\n  return msg.type === \"run.attach\" && msg.commandId === transition.command.commandId;\n}","tryCatchPattern":"try {\n  await conn.send(msg);\n} catch (err) {\n  if (err.message.includes(\"exact cached attachment replay\")) {\n    // resend transition.command verbatim\n  } else throw err;\n}","preventionTips":["Replay commands by reference (transition.command), never by reconstructed copies.","Avoid mutating payloads between attempts; JSON round-trips can reorder keys.","Queue new commands until the warm transition finishes."],"tags":["replay","warm-transition","protocol"],"backgroundTag":"invalid-state-transition","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}