Opt-in completion wake for threads started with t3_thread_launch

[kkolodziej7]

Problem

delegate_task children wake their parent when they finish, but they always run in the parent's project and checkout. A thread started with t3_thread_launch (the only way to get its own worktree, or to work in another project) never notifies the thread that launched it.

So an orchestrating agent has to choose: completion wake with a shared checkout, or an isolated worktree with no signal at all. With a cross-project launch there is not even a way to poll, because t3_thread_wait / t3_thread_read are project-scoped (#15125).

In practice the orchestrator ends up running a shell loop that watches for a report file or a PR, and it never learns that the launched run failed (for example a provider turn that dies during startup) unless the user tells it.

Proposal

An opt-in completion notification on t3_thread_launch (and create_threads), e.g. completionWake: true:

• T3 records the launching thread as the watcher of the initial run.
• When that run reaches a terminal state (completed, failed, interrupted, or a preparation failure), T3 delivers one message to the launching thread through the same continuation/mailbox path that async delegate_task uses: steered into an active turn where supported, queued otherwise, replayed after restart, delivered once.
• The message carries the thread id, the terminal status and, on failure, the failure class. Reading the result still goes through t3_thread_read (which needs the launcher-scoped read from [Bug]: Threads launched into another project via t3_thread_launch can't be waited on, read, sent to, or interrupted by the launching thread #15125 for cross-project launches).

This keeps launched threads ordinary top-level threads; it only adds the one-shot signal the launcher currently has to improvise.

Smallest useful version

Wake for the initial run only, default off, no change to permissions or to who may send to the launched thread.

Related

• [Bug]: Threads launched into another project via t3_thread_launch can't be waited on, read, sent to, or interrupted by the launching thread #15125 — launching thread cannot wait/read/send/interrupt a thread it launched into another project
• Feature: Parent is never notified when a delegated child finishes a follow-up turn (V2) #13490 — follow-up turns of delegated children not waking the parent
• Let a thread message threads in other projects, with a grant the user sets #13888 — user-granted cross-project messaging/read/wait

[niieani]

this would be super useful, thank you for considering 🙇

[NeuroQi]

+1. Here are measurements from a workflow this would fix directly.

We run a coordinator thread that starts workers with t3_thread_launch. We use top-level threads so each worker gets its own project or worktree and the user can step in. Each piece of work is tracked in a GitHub issue, so if a coordinator or worker disappears, a fresh coordinator can reconstruct the state and continue. Across three small recovery tests:

• Workers that end their turn early go unnoticed. Four workers posted their claim and then ended their turn within seconds, without doing the work or reporting a failure. Their run status went to completed, but the launching thread got no signal. One coordinator's shell poller was waiting for a result and missed a dead worker for 22 minutes. A one-shot wake on the terminal state (completed vs interrupted vs failed) would have caught each case within seconds.
• The improvised signal dies with the coordinator. The usual workaround is a shell loop owned by the coordinator. When the coordinator's run is interrupted, that loop is gone or orphaned, so nothing notices the worker finishing. That's why the proposal's "replayed after restart, delivered once" matters: the wake should reach the launching thread after that thread's own turn has ended, and start a new turn there.

One possible extension, not needed for the smallest version: let another thread take over as the watcher of a launched run, for example a replacement coordinator. Today, if the launching thread is gone, the signal has nowhere to go. Even just showing the watcher relationship in t3_thread_read would let a successor see what it has inherited.

The smallest version proposed here (initial run only, off by default) would cover everything above except the takeover.

[DamonYoungWork]

+1 from another orchestrator setup. An Opus thread delegates coding to children, and some work needs its own top-level thread (a benchmark arm, a long job in another project). One of those launched threads finished while the parent kept waiting, and the parent only learned about it when I told it.

Our workaround is a standing instruction: every brief for a t3_thread_launch thread tells it to call t3_thread_send back to the parent when it finishes. That works when the child completes normally. It does nothing when the child's turn dies, which is the case where the parent most needs to know. An opt-in completionWake that also fires on failure would let us drop the instruction.