Repository navigation
[Other]: Include Dispatch-aware reclaim guidance in failed worker-start receipts #15944
Description
Current scope — 2026-09-04
A failed worker-start can name residual resources without providing an applicable next action for them. The remaining request is recovery guidance through the Dispatch-aware owner, not a general instruction to close the terminal by handle.
I withdrew that terminal close proposal in the 2026-08-22 comment. This body now reflects that correction. The comment describes work proposed in #15966; that PR is still open, so it should not be read as a shipped fix.
Evidence
The CLI contract promises stage, effects, residual resources and recovery commands when needed. The original Windows/PowerShell report on 1.4.188 had a failed-start receipt naming a created agent terminal in residualResources. The existing mutation recovery text supplied --retry-request, but that recovers the request result; it does not explain what to do with the resource named in that result.
Requested behavior
- First recover an unknown mutation outcome idempotently. Do not start a second worker while the first request remains unresolved.
- For a failed supervised Dispatch, provide the applicable inspection/release action keyed by Dispatch, using
worker-release --dispatch <id>only when the runtime says it is eligible. - Re-check present ownership on the execution host when acting, preserve inspectable output, and retain adopted/configured/setup terminals or anything whose ownership cannot be established.
- Preserve
release_pending/release_unknownguidance. Neither is permission to substituteterminal close, and a federated resource must not be reclaimed on the coordinator's host.
A receipt proving that this attempt once created a terminal does not prove it still owns that terminal. A subsequent worker or a person may have adopted it before cleanup. Wording alone cannot remove that race.
#15966 and #15949 are open approaches to coordinate, not two separately required fixes. #15920 covers a release-path failure; #15313 covers orphan visibility. No live release/close operation was performed for this editorial update.
Activity
fix(cli): quote the dispatch id in printed recovery commands
fix(cli): reject unsafe dispatch ids and drop the terminal-close exce…
Tauri-EPO commentedon Aug 22, 2026
Update on the direction, because the PR that closes this (#15966) deliberately does not do half of what I asked for here.
What I asked for
Two things: emit a recovery command for a residual resource, and state the affirmative
terminal closecase in the orchestration guide, scoping the existing line-246 prohibition to a settled Dispatch.The first is done. The second is gone, and should stay gone.
Why the affirmative case cannot be written safely
The first attempt emitted
orca terminal close --terminal <id>directly. Review killed it twice, and the second reason is the one that generalises.At the moment a failed start hands you a residual terminal, the receipts available prove two things: that this Dispatch once created that terminal, and that the old Dispatch no longer owns it. Neither says anything about now. Between the proof and the action, a later
worker-start --terminal <handle>— or a person taking the terminal over — can adopt it. Closing it then destroys live work.That is a race, not an ambiguity, so no wording fixes it. Any guide sentence of the form "if the receipt says X, closing is safe" is wrong the moment adoption is possible, and adoption is always possible.
What #15966 does instead
orca orchestration worker-release --dispatch <id> --jsonis the only reclaim path the guide names. It re-checks ownership on the host that holds the terminal, at the moment of the action, preserves inspectable output first, and retains setup terminals, configured tabs, adopted terminals and anything it cannot prove.WORKER_RELEASABLE_STATESalready includesfailed, so no state change was needed.A federated receipt gets
worker-show --dispatchand a note naming the worker server, becauseworkerReleasefails closed on federation and a home-side close would target the wrong host.The line-246 prohibition is restored verbatim rather than scoped.
So this issue is still closed by that PR, but read it this way
The gap this issue reports is real:
worker-startnames a leak inresidualResources, the spec promises "recovery commands when needed", and nothing told the orchestrator what to do. That is fixed.What changed is the answer. I asked for the guide to teach a command; the right fix was to route the decision to the component that can make it correctly and to teach that instead. Recording the reasoning here so the closing PR does not look like it drifted from its issue by accident.
[-][Other]: worker-start names a residual resource with no stated way to reclaim it[/-][+][Other]: Include Dispatch-aware reclaim guidance in failed worker-start receipts[/+]Tauri-EPO commentedon Sep 7, 2026
Closing as resolved on
mainby #16904 (merged 2026-09-06, not yet in a release as of v1.4.197).The failed
worker-startreceipt now carries the Dispatch-scoped reclaim path itself, and only when the ownership table accepted the residual terminal for that Dispatch:src/main/runtime/rpc/methods/orchestration/worker/worker-start-receipt.tsreturnsrecovery: "This start created a terminal that never ran the Task. Close it with: orca orchestration worker-release --dispatch <id>". The guide says the same and forbids substitutingterminal close(skill-guides/orchestration/references/recovery-and-cleanup.md). The idempotency half is covered by the mutation-recovery guidance insrc/cli/orchestration-mutation-recovery.ts(inspect withworker-show/request-showbefore--retry-request).Residual, small enough for a follow-up PR rather than this issue: the human-readable
worker-startoutput (src/cli/handlers/orchestration/worker-output.ts) printsnextCommandsbut notrecovery, so the guidance is JSON-only today. I will retest the receipt on the first release that carries #16904.