agent's kernel gateway session expired mid-run, restore failed, agent lost execution state

TL;DR

Kernel gateway sessions expire, and an agent mid-run loses its kernel connection with no way to resume unless it planned for it. Build the agent to detect session expiry (401/403 on kernel calls), re-authenticate against the gateway, and relaunch the kernel. More importantly, checkpoint the run's progress to durable storage as it goes, so the resumed run continues from the last checkpoint instead of from zero.

agent's kernel gateway session expired mid-run, restore failed, agent lost execution state

Use this when

• An agent's long run dies with auth errors from the kernel gateway.
• The gateway issues short-lived session tokens.
• Runs longer than the session lifetime fail reliably.

Not for this skill when

• The kernel itself crashes. That is a kernel problem.
• Auth fails immediately. That is a credentials problem.

Steps

1. Confirm expiry: the failure is 401/403 on gateway calls after a working period. Verify: the timing matches the session lifetime.
2. Add session refresh: the agent re-authenticates before expiry (or on 401) and re-establishes the kernel session. Verify: a run longer than one session lifetime survives.
3. Checkpoint progress: after each major step, write state to durable storage. Verify: a killed run leaves a readable checkpoint.
4. Add resume logic: on start, the agent loads the latest checkpoint and continues. Verify: a resumed run skips completed steps.
5. Test with an artificially short session lifetime. Verify: the agent rides through multiple expiries.

Variant phrasings

kernel gateway session expired agent

Short form. Refresh plus checkpoints.

agent lost kernel session gateway

The symptom phrasing. Resume from checkpoints.

gateway auth expiry long notebook run

The cause phrasing. Re-auth mid-run.

Compatibility: Jupyter kernel gateway / enterprise gateway with token auth. Checkpointing is agent-side.

Why it happens

Gateway sessions are deliberately short-lived for security, but agent runs are long-lived by nature. Without refresh logic the agent's credentials rot mid-run, and without checkpoints the run's state lives only in the dead kernel's memory. Both halves are needed: refresh keeps the connection alive, checkpoints make expiry survivable when refresh fails.

Edge cases / pitfalls

• Refreshing the session does not restore the old kernel's variables. Only checkpoints restore progress.
• Storing the refresh credentials where the agent can read them has security implications. Scope them tightly.
• A checkpoint that is written only at the end is useless. Checkpoint incrementally.
• Test expiry handling; it is the kind of code that rots because sessions rarely expire in dev.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0yBIlfcw8MjYF2ODFYPmVQ