[RFC] Conditional idle turn admission and durable delivery outcomes

[afspies]

External orchestration clients can already observe T3 threads with orchestration.subscribeShell and submit provider-neutral thread.turn.start commands. There are two gaps when a client needs to deliver work after a thread becomes quiet without risking a duplicate provider prompt:

1. A shell snapshot saying “idle” can become stale before thread.turn.start is decided. Another client can start a turn in that window.
2. HTTP/command acceptance proves that orchestration persisted the command, but it does not say whether the provider was never contacted, accepted the turn, or may have accepted it before the server lost the response.

A concrete example is an external job watcher that wants to wake a thread once, after CI finishes. It can keep its own queue, but it still needs an atomic “start only if idle” operation and enough durable outcome information to decide whether retrying is safe.

Relationship to existing work

T3's current architecture is already the right provider-neutral foundation: orchestration records intent and state, while provider-specific behavior stays in adapters.

#7240 directly addresses the product-level queue: persist after-current messages in T3, show and cancel them in clients, then dispatch them across providers. Its queued -> handoff boundary and conservative restart handling solve much of the same user problem.

This proposal asks whether a smaller lower-level contract is also useful, either underneath #7240 or for authenticated external clients that own their own queue. It does not propose another T3 queue or UI. subscribeShell remains the state stream, and the broader SDK question belongs in #6977.

Smallest useful semantics

Conditional start

Add an optional onlyIfIdle: true to thread.turn.start, advertised by an environment capability because an older server may ignore an unknown optional field.

The serialized orchestration decision rejects a busy thread atomically, before appending the user message or a command receipt. The same command/message IDs can then be retried after a later shell event. Ordinary starts keep their current behavior.

“Idle” should include the durable turn/session state and blockers such as pending approval or user input. The provider boundary needs a final per-thread admission check so ordinary input cannot slip between the decision and provider send.

Delivery outcome

For accepted conditional starts, persist a record keyed by command ID:

• accepted: orchestration events are durable; provider not called
• attempted: marker committed immediately before the provider call
• started: adapter returned a correlated provider turn ID and that transition persisted
• failed: proven pre-attempt failure
• unresolved: provider was attempted but the outcome is unknown
• abandoned: an operator explicitly closed an unresolved record without claiming it was not delivered

On restart, re-drive accepted records with the same IDs. Convert pre-boot attempted records to unresolved and never resend them automatically. This is deliberately at-most-once at the provider boundary; it does not claim exactly-once model execution.

Targeted interrupt

Preserve and enforce the existing optional thread.turn.interrupt target turn ID end to end. Check it when deciding the command, immediately before provider contact, and at provider-specific fallback boundaries. If the turn ended or a successor started, reject or no-op rather than interrupting the successor. The reference strengthens the current partial stale-turn checks; it does not introduce the field itself.

Reference implementation and limits

I built this against T3 Code 0.0.40 as a design probe:

• branch: https://github.com/afspies/t3code/tree/alex/rm-async-delivery
• commit: afspies@03d61c0bc
• base: 09e8de9c655a

The shared command, persistence, recovery, HTTP, and capability shapes are provider-neutral. The reference only enables conditional delivery for Codex and Claude, where the provider admission boundary was verified; other adapters would need explicit support before advertising the guarantee. It includes focused tests for back-to-back admission, restart recovery, lost provider responses, failed persistence, exact-target interruption, and HTTP wire behavior. A local isolated server smoke test exercised conditional Claude delivery and command-to-turn correlation.

The branch is about 2,800 added lines including tests, so I am not opening it as an unsolicited PR. FAR-specific program routing, mailboxes, research ledgers, and notification policy remain outside T3.

Questions

1. Is this lower-level delivery contract useful alongside feat(orchestration): persist run-next messages server-side across providers #7240, or should T3's server-owned queue be the only supported abstraction for quiet delivery?
2. If useful, would maintainers prefer a first slice containing only atomic onlyIfIdle admission, with delivery records and targeted interrupt split into later work?
3. For adapters beyond Codex and Claude, which provider response should count as a reliable started admission receipt?

[bompus]

Would maintainers approve a smaller first step here: a read-only orchestration.getCommandOutcome RPC on the existing authenticated WebSocket transport?

After losing a dispatch response, an external client needs to know whether T3 committed the original command. The proposed lookup accepts a thread ID and command ID, uses the existing command receipt store and orchestration:read authorization, and requires an exact receipt/thread match. It returns only IDs, command type and one of accepted, rejected or unknown. A rejected receipt explicitly reports admission as unknown; neither rejection nor a missing receipt grants permission to resend. Missing and foreign-thread receipts are indistinguishable, and storage errors expose no diagnostic cause.

This differs from the broader conditional-delivery proposal above. It adds no idle precondition, provider admission guarantee, delivery queue, database migration, HTTP endpoint or MCP wrapper. It also does not fix the credential-dependent retry namespace reported in #16184.

A reference candidate is available in this fork PR, against current V2 source. It passes 31 focused tests, contracts and server typechecks, and scoped lint with six unchanged baseline warnings. An isolated loopback server also passed nine checks through the production WebSocket route, real authentication/session storage, full RPC handler registration, JSON encoding and receipt repository. Unrelated services were model-free mocks and the database was in memory. The complete application startup, packaged build, Windows runtime and full test suite have not been qualified. The candidate has not been deployed.

Would you approve this direction and scope for a focused upstream PR, or is there already a supported receipt lookup that external clients should use? Upstream PR submission remains held pending explicit maintainer approval.