paperclipai/paperclip · error

native_runner_warm_transition_recovery_pending

Error message

native_runner_warm_transition_recovery_pending

What it means

Timeout guard in the warm-transition wait loop of the runnerd Codex transport: after a warm recovery reconnect, the runner's stored identity has not converged to the desired identity (or warmTransition state is still set) within runnerReconnectGraceMs (default 5s), or the runner process exited during the wait. The warm handover could not be proven complete in the grace window.

Source

Thrown at packages/paperclip-runner/src/live/runnerd-codex-transport.ts:5173

    if (!adoptedRunner) await this.#awaitRegistrationReady(registration?.ready);
    if (adoptedRunner) {
      this.#evidence.runnerPid = adoptedRunner.pid;
      this.#evidence.runnerProcessGroupId = adoptedRunner.processGroupId;
      this.#watchAdoptedRunner(adoptedRunner);
    } else {
      this.#evidence.runnerPid = handle?.child.pid ?? null;
      this.#evidence.runnerProcessGroupId = handle?.processGroupId ?? null;
    }
    this.#publish();
    if (warmRecovery) {
      const deadline =
        Date.now() + (this.options.runnerReconnectGraceMs ?? 5_000);
      while (
        !recoveryIdentityMatches(core.store.state.identity, desiredIdentity) ||
        core.store.state.warmTransition !== undefined
      ) {
        if (Date.now() >= deadline || (await this.#runnerHasExited())) {
          throw new Error("native_runner_warm_transition_recovery_pending");
        }
        await new Promise<void>((resolveWait) => setTimeout(resolveWait, 10));
      }
      if (core.getCommand(warmRecovery.commandId)?.status !== "completed") {
        throw new Error("native_runner_warm_transition_result_unproven");
      }
      this.#durableTurnId = desiredIdentity.turnId;
      this.#eventIdentity = structuredClone(desiredIdentity);
      this.#eventSourceSeq = 0;
      this.#deferredTurnStartEvents = [];
      if (oldTransitionRegistration && newTransitionRegistration) {
        await oldTransitionRegistration.release();
        this.#controlPlaneRelease = newTransitionRegistration.release;
        this.#controlPlaneCheckpoint =
          newTransitionRegistration.checkpoint ?? null;
      }
    }
    this.#pump = setInterval(() => this.#pumpEventsSafely(), 5);

View on GitHub (pinned to 01ad858492)

Solutions

1. Increase runnerReconnectGraceMs if the runner legitimately needs longer to adopt the new identity
2. Check runnerd logs for why the identity was not adopted (crash, restart loop)
3. Fall back to a cold start of the runner if warm recovery keeps timing out

When it happens

Trigger: Thrown at packages/paperclip-runner/src/live/runnerd-codex-transport.ts:5173 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/94959356ece1db5e. Report an issue: GitHub.