V2: preserve permission and question waits across server restart

[kitlangton]

Summary

Pending permission requests and question forms are process-local in V2. Restarting the server destroys the request and its suspended continuation. Managed-service restart continuity may resume the Session, but it cannot restore or accept a reply to the old blocker.

We need a durable model for interactive waits that covers both permissions and questions without blindly replaying the tool call that created them.

Current behavior

Permissions keep pending requests in an in-memory Map with a Deferred owned by the running tool fiber:

• packages/core/src/permission.ts
• layer finalization declines every pending request and clears the map

Questions use Form.Service, whose entries and Deferreds live in an in-memory cache:

• packages/core/src/form.ts
• layer finalization cancels every pending form
• the built-in question tool waits on forms.ask(...) inside its tool execution

On managed-server shutdown, active Sessions are suspended for restart continuity. On startup, the runner resumes the Session and reconciles stale running tools as interrupted. The old permission/form request no longer exists, so clients cannot display or answer it.

This also gives shutdown the wrong domain meaning for forms: finalization publishes cancellation even though the user did not cancel the question.

Design pressure

Persisting the request payload alone is insufficient. The reply currently settles a process-local Deferred inside a tool call, and that continuation disappears with the process.

Permissions are the harder case because permission.assert(...) can be called from within tool execution. Re-entering the tool to reach the permission check may repeat work or side effects that happened before the check. Treating every interrupted tool as replayable is therefore unsafe.

The design should decide where the restartable boundary lives. Possibilities include:

• Make interactive blockers durable workflow records whose terminal reply can settle the owning tool call without restoring the old JavaScript continuation.
• Move authorization to an explicit boundary before the physical tool attempt, so an approved attempt can start safely after restart.
• Define a resumable tool protocol for tools that can suspend on interactive input, while ordinary tools remain non-replayable.

Questions and permissions should share the same lifecycle concepts where possible, even if permission evaluation and form rendering remain separate APIs.

Required semantics

• A pending permission or question survives a graceful managed-service restart and remains visible through the existing list APIs.
• The original request ID remains replyable after restart.
• Server shutdown does not record a user rejection or cancellation.
• A reply settles the blocker exactly once and allows the owning Session to continue.
• Recovery does not repeat provider work or tool side effects that may already have executed.
• Saved permission rules remain distinct from one pending permission decision.
• Reconnect hydration and live events converge on the same durable blocker state.
• Location and Session ownership checks continue to prevent cross-location or cross-session replies.
• The design explicitly states whether unexpected process death is supported or remains outside the first implementation.

Coverage

Add an integration test that:

1. Starts a Session that blocks on a permission request or question form.
2. Tears down the server/location graph while preserving the database.
3. Builds a fresh graph and performs managed restart continuation.
4. Verifies the same blocker is listed and replyable.
5. Replies and verifies the Session continues without duplicate tool side effects.

Cover permission approval, permission rejection, question answer, and question cancellation.

Related

• Unanswered question disappears from UI after OpenCode restart #15172 tracks the same user-visible question loss in V1.
• V2: reconcile pending TUI blockers after reconnect #35447 covered V2 blocker reconciliation after reconnect and requested fresh focused issues against the current lifecycle.
• V2: auto-resume active sessions after server restart #35646 added graceful managed-service Session continuation, but intentionally reconciles ambiguous in-flight tools rather than replaying them.
• specs/v2/session-restart-continuation.md documents the current restart boundary.

[opencode-agent]

Follow-up: permission preflight and persisted forms

The permission path can be made significantly more restartable if authorization is an explicit phase before any physical tool side effect.

A useful durable distinction is:

tool call: authorizing -> executing -> settled
permission request: pending -> approved | rejected

Recovery may reconstruct an authorizing call, but must never replay an ambiguous executing call. Permission request IDs should be deterministic for the owning tool call (and request ordinal/resource set), with the request payload and terminal answer persisted. After all required approvals are present, transition the tool call to executing durably before entering the body.

Most current built-ins already place permission.assert(...) before their physical side effects, but this is a convention inside each executor rather than an enforceable phase. Several tools perform path resolution/inspection first and some issue multiple permission assertions. A restartable design therefore needs one of:

• an explicit tool authorization/preparation seam that computes every request before execution; or
• a built-in-only resumable protocol with a tested invariant that all work before the final authorization barrier is safe to repeat.

Dynamic/plugin tools and MCP calls should remain non-replayable unless they opt into that contract. In particular, an MCP elicitation may occur after a remote call has already started, so the generic permission/form recovery rule cannot safely replay it.

Persisting form CRUD state itself is straightforward: durable form row, payload, owner Session, status, answer, and compare-and-set reply/cancel. Form.ask should use a deterministic owner ID and rejoin an existing pending or answered form after reconstruction. Shutdown must not publish a user cancellation merely because the Location graph is closing.

The continuation still matters:

• The built-in question tool is a good first target because it has no physical work between authorization and Form.ask; it can safely reconstruct and rejoin the durable form.
• API-created/global forms can persist independently without resuming a tool.
• Forms raised mid-side-effect (notably MCP elicitation) need a separate resumable protocol or an explicit interrupted outcome.

Focused recovery coverage should prove: restart while authorizing, approval/rejection before and after the new process attaches, answer/cancel before and after reconstruction, no replay once executing, deterministic retry IDs, and changed path/resource resolution causing a fresh authorization rather than using an approval for a different target.

[kitlangton]

The concrete next-15386 to next-15388 incident in #36585 confirms this failure mode. #36591 provides the narrow TUI escape hatch: if a stale form reply returns FormNotFoundError, refresh authoritative form state so the user is no longer trapped.

The long-term design has now been worked through in specs/v2/durable-session-interactions.md. The main conclusion is that persisting the form alone is insufficient. The original JavaScript continuation and Deferred are also gone, so recovery needs to park and later complete the original Step without replaying its provider request or ordinary Tool side effects.

Key decisions from the reviewed plan:

• Start with the Core-owned question Tool only. Durable permission waits need a separate preflight design because permissions can occur inside arbitrary side-effecting Tool execution.
• After the provider attempt completes, settle ordinary eager Tools, prepare questions, capture the end snapshot, then publish one replayable atomic session.step.parked fact containing all questions and unconsumed Step facts.
• Project each linked question call into a durable waiting state. Waiting is not process-local running state.
• Admit answer/cancellation with a transactional first-response-wins compare-and-set. Current clients send a response ID for exact retry; legacy payloads remain temporarily accepted with weaker retry behavior.
• Treat a terminal question linked to a Waiting Tool as durable eligible Session work. A recovery loop schedules it at startup and on a bounded live cadence, so a lost advisory wake cannot strand it.
• Resume through a versioned Core-owned question@1 continuation adapter. Do not rerun the provider, ordinary Tools, before-hooks, permission, or the original question executor.
• Block compaction, prompt promotion, and provider continuation while the Step is waiting.
• Human cancellation terminates the whole Waiting Step and derives sibling question aborts so no form remains live.
• Keep global MCP elicitation on a separately owned ephemeral path for the first slice. Do not let the "global" sentinel enter Session persistence.
• Use reader-before-writer rollout, a disabled writer flag through race testing, and a precursor database floor guard so unsupported rollback binaries refuse the database before serving or mutating it.

The plan has two gates before persistence work may begin:

1. An executable question-continuation interface prototype proving codecs, output finalization, hook semantics, version resolution, and Code Mode exclusion without a second Tool representation.
2. An atomic parking/response harness proving there is no commit boundary with a Waiting Tool but no replayable parked Step, and that terminal publication consumes pending Step state once.

The existing issue currently groups permissions and questions together. The vetted recommendation is to use the durable question path as the tracer bullet, then design permission durability separately rather than assuming it is another adapter over the same continuation.