[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?