4 Commits

Include renames

Author	SHA1	Message	Date
Brennan Benson	7a1f55c52a	fix(native-chat): give a failed Claude background task a typed row instead of an opcode (#20519) ... * fix(native-chat): give a failed Claude background task a typed row instead of an opcode A failed backgrounded command printed red rows whose visible text was the wire opcode, and printed one failure twice. All five task lifecycle kinds are catalogued status-chrome, but the payload sniffer in classifyProviderFrame runs first and promotes any frame reporting a failure to the generic unknown-frame fallback, whose sentence lookup has no key for the field Claude puts its own sentence in. Two frames for one task therefore produced two rows, both of them the method name. Suppressing those frames is not the fix: when the last background task settles the tracker flushes it and the strip unmounts, local_bash is excluded from the subagent roster, and the status feed publishes only live tasks, so for a lone backgrounded command the transcript row is the only report of the failure that exists anywhere. So the catalogue now binds: kinds a dedicated typed translator owns are named as covered, and the generic fallback refuses to emit for them in either direction. A new row owner keeps one durable row per task id, opened by the announcement, revised in place by the lifecycle frames and closed by the notification, carrying the provider's summary, error, output path, usage and a run state. The row is written on the same dual carrier the subagent roster uses: a frozen text twin plus a typed block, so a client without the block type reads the sentence rather than nothing. hasProviderError keeps its authority everywhere else, unchanged. * fix(native-chat): keep tool attribution across a background-task row A background task's row is a system message landing mid-turn between the assistant's tool calls, exactly where the spawn-group roster row lands. Without the same exemption it ended the run the following tool messages fold into, so a tool result arriving after one stopped folding into its own assistant turn. Also syncs the catalog with the row's one new translate key. * fix(native-chat): harden background task rows * fix(native-chat): settle background rows on provider end * fix(native-chat): scope malformed task fallback text * test(native-chat): assert only eligibility at the disposition layer The malformed-task-frame test asserted the generic fallback resolves Claude's `summary` field itself, which was true only while that key sat in the shared key list. Eligibility is what this layer decides; the sentence the row leads with is Claude's, supplied through the display-text seam and proven in the translation test. * fix(native-chat): gate background-task admission and scope rows per run Admission now matches the reference on all three gates. Type is the whole gate and MONITORS ARE NOT ADMITTED: a monitor runs for the life of the session and has no outcome a row could report, so it never reaches the timeline. On first admission only, the task's tool_use_id must name a tool call this session forwarded at the TOP level — a Task spawned inside a subagent's sidechain names an id that never reached the transcript, and a top-level row for it would claim an invocation the user never saw. And a task that already exists and has not finished is not re-opened: a duplicate announcement is a redelivery, not a second run. Rows are now keyed per RUN. A provider may reuse a task id for a distinct later invocation, and a row keyed by the id alone overwrote the first run's transcript history instead of leaving it standing. Generation 1 keeps the bare key, so every row already written is unaffected. The spawning tool call is carried on the row as parentToolUseId. Orca's journal has no structural parent link for an item — AgentJournalItemIdentity has four arms and none carries one — so the relationship is data on the item rather than nesting. A terminal frame that names NO tool still opens a row. That is a named deviation, recorded at its call site, and the measurement behind it is in the PR. * fix(native-chat): read the aggregate roster by membership, not a phantom status The background-tasks payload types every entry as exactly {task_id, task_type, description, ambient?}. It has no per-entry status, so the state this owner derived from one was always undefined and the reopen branch it guarded was unreachable on every real payload — proven by deriving the state from an SDK-shaped entry and getting null. Membership is the only liveness the payload carries: it is the whole live set after a change, so presence means live and absence means merely "no longer listed", never an outcome. Presence does not revive a settled row either — the level's ordering against the start/stop edges is unspecified and it carries no evidence of a new run, so the task's own frames stay the only thing that opens or settles one. Only the identity fields it really sends are read, and ambient housekeeping entries are excluded as the payload asks. The two helpers that served the dead branch are removed, along with the test that exercised it through a synthetic status the CLI cannot send. * fix(native-chat): mirror reference task admission and drop the synthesis path The forwarded-parent gate is conditional on the field being PRESENT. An announcement naming a tool this session never forwarded is a nested child and is refused; one naming no tool at all is admitted, because absence of the field is not evidence of an unforwarded parent. The previous rule required the field and so refused every tool-less task. Terminal frames now match on task_id alone. The forwarded-parent question is settled once, at admission, and is never re-asked on a notification or a patch. A frame for a task that was never admitted yields no row, and a patch is folded into the row it names rather than opening one. That removes the synthesized-row path entirely, and with it the named deviation it carried: the captured tool-less failure lands on a row that already exists, because its own tool-less announcement is admitted. The dead builders go with it. Left deliberately stricter than the reference, and flagged rather than changed: a terminal frame still records its task id as terminal even for a task never admitted, so a late announcement cannot open a row for work already reported finished. Two existing tests pin that. * fix(native-chat): preserve background task ownership across restarts * chore: restore pnpm-lock.yaml to origin/main A local pnpm run rewrote the lockfile and the merge commit swept it in. The branch changes no dependencies, so it must carry no lockfile delta at all. * fix(claude): harden background task lifecycle * fix(claude): bound task generation history * fix(claude): preserve task identity after history eviction * fix(claude): resolve background task identity after rebind * fix(claude): isolate queued task runs * refactor(claude): give the background-task ledgers one bounded owner The bounded collections behind a background-task row were read out of the class with `Reflect.get` to prove they stay capped, which the anti-slop gate rejects. Move them into `ClaudeBackgroundTaskLedgers`, which owns the caps beside the eviction helpers and reports a typed readonly size view the tests assert against. Also replace a `Reflect.get` in the mobile recording proxy with typed property access. * fix(native-chat): report a background task failure the transcript never admitted A terminal `task_notification` for a task no announcement ever admitted rendered nothing at all. The typed row owner declined the row because its map held no entry for the id, and reported the frame as handled — which is exactly what tells the generic provider-frame fallback to stay quiet. Both surfaces declined the same frame, so a real failed background task was dropped on the floor. A terminal frame is self-sufficient: it states an outcome, and it carries the summary, status, error, output path and usage that outcome needs. It now opens its own row from those fields, with the summary as the label and `unknown` as the kind when the frame names no task type. The row map enriches a terminal frame; it never gates one. Every terminal status writes one, not failures alone, so there is one rule here rather than a third behaviour for failures. The deliberate hand-offs still win, because they are recorded rather than implied: ambient, subagent and foreground tasks are claimed in the foreign-owner ledger the notification path already checks first. A Task spawned inside a subagent's sidechain now records its refusal there too, under `sidechain`, instead of leaving no trace and reading as a task nothing ever decided about. A capacity-refused task whose outcome the generic fallback already printed records `fallback` the same way, so a redelivery neither prints twice nor mints the row capacity refused. The anti-resurrection guard stays and stays scoped to announcements: a late `task_started` cannot reopen work already reported finished. The restart rule is now stated once instead of twice — a different parent alias is the provider's restart signal only when BOTH runs name their parent, which is what the terminal ledger already required of an evicted row and what the live row now requires too. * test(native-chat): pin that an orphan task row reopens the provider's turn * fix(native-chat): stop an orphan task row drawing its sentence twice An orphan row took its header label from the notification's summary, which also renders as the row's sentence, so the same string appeared in both slots of the same collapsed row. The label now stays empty and the header falls back to the task kind, leaving the sentence to carry the provider's words. * fix(native-chat): keep Claude task outcomes owned through capacity and redelivery * fix(native-chat): keep settled overflow notifications from reopening a turn * fix(native-chat): retain Claude task rows through journal pressure	2026-09-17 10:10:27 -07:00
OrcaWinandm4air	5d0a45bb92	perf: use counted membership for worker transcript roster twins (#19484) ... Co-authored-by: m4air <m4air@m4airs-MacBook-Air.local>	2026-09-07 22:21:20 -07:00
Brennan BensonandMerge Sim	0252fe5c36	feat(native-chat): show Codex subagent activity instead of opcode rows (#18773) ... * feat(native-chat): show Codex subagent activity instead of opcode rows Codex spawns subagents and reports their lifecycle, but Orca rendered only gray `codex · item:subAgentActivity` opcode rows. Build the real display: one summary row per spawn group with a live working count and token usage. State is accumulated from `subAgentActivity.kind` alone. A live probe against app-server 0.152.1 showed `agentsStates` arrives empty even in a real subagent run, and that every activity item is delivered twice (item/started and item/completed), so every transition is idempotent and terminal states latch. Children never receive `thread/started`, so there is no nickname, role, or depth to read; the row labels from the trailing segment of `agentPath`. Two sweeps keep a row from claiming work forever: the parent turn's terminal event settles still-running children, and session start marks a pre-restart roster unverifiable rather than exited, since Codex resume replays no non-message items and no event can ever settle them. The roster rides a new NativeChatBlock variant paired with a plain-text twin. A journal item kind could not be used: that union is closed, and an unknown kind parses as malformed, which is the corrupt-journal class that can hide the chat tab. Block types are explicitly admissible when unknown, so an older client drops the block and renders the sentence. MessageRow moves out of NativeChatMessageList to keep both files under the max-lines budget without a disable. * feat(native-chat): give the subagent summary row its bot glyph The row led with a glyph that swapped on state — a check once every child completed, a group icon otherwise — so a group appeared to change identity the moment it settled. Per the approved mock, the glyph names the category and never moves: state is carried by the status dot and the tone of the words beside it. Use lucide `bot`, the same glyph the individual `subAgentActivity` rows take in the eight-category vocabulary, so the summary reads as their parent. Slot and glyph are the mock's 16px/14px, muted by default, and the svg is `aria-hidden` — the headline is what a screen reader announces, so the icon never stands alone. * fix(native-chat): correct the Codex subagent roster's build, journal write, and failure reporting * Restore the exhaustive block handling that adding `subagent-group` to `NativeChatBlock` broke. `formatWorkerTranscriptMessage` and `boundBlock` both fell through to `image-ref` field access, so `tsc -p` failed for the CLI and node projects and `build:cli` could not emit. Both now guard on `image-ref` explicitly and give the roster block its own branch. * Stop the roster's publish from evicting its own append. The sink queue coalesces by `coalescingKey` alone with no op-kind check, so passing the append's key to `tryPublish` spliced the queued append out and the row never reached the journal — permanently, since `lastSerialized` was already set. `tryPublish()` now takes no argument, matching every other call site. The regression test's fake sink honours the key, which the previous fake did not. * Keep `collabAgentToolCall` substantive. Only the MultiAgentV2 path emits `subAgentActivity`, so a V1 turn has no roster row; suppressing its collab tool calls too would have left a V1 fan-out showing nothing at all. * Surface a settled failure while siblings still work. The summary now reports the worst adverse outcome independently of the group verdict, so the row shows `3 working +1 failed` with a failed-coloured dot instead of a neutral pulsing dot. The plain-text twin names it too. * Treat `/morpheus` as a child. Only `/root` is the turn itself; the old segment-count test silently dropped a valid single-segment agent. * Refresh token-usage recency on update so an active thread is not evicted as the oldest entry, and scope the `agentsStates` comment to the V2 path. * fix(native-chat): stop the subagent roster announcing a new duration every second The roster row is an `aria-live="polite"` region and it contains the elapsed clock, which reticks once a second for as long as the fan-out runs. A screen reader therefore reads out a fresh duration every second, burying the state changes the live region exists to report — the headline, the verdict, and the `+1 failed` alert. No other live region in the transcript does this. `NativeChatToolRun`'s live button holds only the active tool label, and in `NativeChatWorkingStatus` the variant that shows a duration is precisely the one with no `aria-live`. Hide the clock from the accessibility tree only while it is moving. Once the group settles the duration is fixed, so it stays readable and costs no announcements. * fix(native-chat): retry a refused roster publish, and stop two wrong readings Four defects from a third review pass over the Codex subagent roster. `write()` set `lastSerialized` before the append and rolled it back only when the APPEND was refused. A refused PUBLISH left it set, so an identical replay short-circuited and the revision was never published again. The repo's own pattern is the opposite: `codex-structured-item-streams.ts` advances `checkpointLengths` only once the append AND the publish are both accepted. Roll back on either half. That alone did not cover the sweep, which is the LAST event a group ever gets: its `changed` guard skips the write on a retry because every child has already latched, stranding the settled roster's final revision. Write when the previous attempt was refused part-way, too. `formatWorkerTranscriptMessage` read `block.agents` as its exhaustive fallback. The journal schema deliberately admits block types this build does not know and `client.call` casts the RPC result instead of validating it, so a newer remote host's block reached that line and threw `agents is not iterable`, taking down the whole `worker read`. It printed a harmless `[image omitted]` before. Match `subagent-group` explicitly and degrade the unknown case. The elapsed clock measured to `now` whenever no child carried a terminal timestamp. That is exactly the roster restored from the journal after the host died: the reconciler latches `unverifiable` without a `settledAt`, so a child that ran four seconds reported the time since the crash as its run length, on a row that is not even counting. Show no duration when none is known. Also restores package.json to origin/main: the merge had deleted one of main's two duplicate `bench:terminal-partial-escape-tail` keys. Behaviour-preserving (JSON is last-wins and the deleted line was the dead one), but unrelated to this PR and better left to its own change. No gate rejects duplicate JSON keys. The new refusal tests also cover the append-side rollback, which had none. * fix(native-chat): stop the subagent roster vanishing from every settled turn `NativeChatToolRun` bailed out for a completed turn whose activity disclosure is collapsed before it reached the branch that draws a roster-only run. That guard exists to push TOOL activity behind the turn-status disclosure, and it fires on exactly the shape a spawn group has: a roster message carries no tool blocks, so `selectActiveToolCall` returns null and `isSettled` is true, while the list passes `expandOverride={expandedTurnIds.has(turnKey)}` — false until the reader opens that turn — and `activeTurnIsWorking={false}`. That is the default state of every finished turn in the transcript, so the one compact row this feature exists to leave behind ("Ran 3 subagents") disappeared the moment its turn ended. Worse, `MessageRow` counts a spawn group as renderable specifically so the row survives, then rendered a wrapper around a component that returned null — the empty ghost bubble its own guard is written to prevent. Order the roster branch before the disclosure guard. A roster has no tool activity to hide, and the guard's reasoning ("a failed child command looked like the whole response was still running") does not reach it. Runs that do carry tool blocks still fall through to the guard unchanged, and in practice a roster never shares a message with them: it is its own `role: 'system'` journal row and `isToolOnlyMessage` is false for it, so `foldToolMessages` never merges tool blocks into it. Also drop childless groups when building the rows, so `subagentRows.length` stays an honest test of "something will draw" — the roster-only branch returns a margin-bearing wrapper on the strength of it, and a group with no children renders null. Both tests fail with their fix reverted; the existing NativeChatToolRun suite still passes, so the completed-turn disclosure behaviour is unchanged. * test(native-chat): cover the subagent roster at the message-list level Every defect this feature has shipped so far lived in the assembly between rows, and the row-level suites kept passing through all of them. Loop 4's regression — a settled roster swallowed by the completed-turn disclosure — was found by reading the code, not by a test, and an independent visual-proof run observed the same symptom in the real UI and routed around it rather than reporting it. `NativeChatToolRun` rendered alone is handed `expandOverride` and `activeTurnIsWorking` by the test author, so it agrees with whatever the caller was assumed to pass. Drive the real component instead. The roster is its own `role: 'system'` journal row carrying the producer's two blocks (structured + plain-text twin), so what reaches the DOM depends on `foldToolMessages`, the turn-key mapping and the disclosure state `NativeChatMessageList` owns — none of which a row test exercises. Three cases, on one assembled transcript that holds tool calls AND a roster: - a settled turn with activity collapsed, the resting state of the whole transcript, still shows the row (fails with loop 4's reorder reverted); - tool activity stays behind that disclosure and appears only on expand, and expanding draws no second roster (fails with the guard removed); - a working turn reads as a live spawn. The first also pins that the plain-text twin is dropped rather than printed beside the row it stands in for. Timestamps are explicit and ascending: the list re-sorts by (timestamp, id), so rows sharing a millisecond tie-break alphabetically and the user turn can sort last, stranding the roster outside its own turn and reconciling live children to `unverifiable`. No production code changed. * fix(native-chat): make "counts as renderable" and "actually draws" agree for a spawn group `MessageRow` counts any `subagent-group` block as renderable, but `NativeChatSubagentRun` renders null for a childless roster. A group with `agents: []` therefore mounted a row that drew nothing — an empty div that still costs the transcript one `gap-5` slot. The Codex producer never writes one (every `write()` call site operates on a group that already holds an entry), but the block schema admits `agents: []` with no `.min(1)`, and the wire is where such a shape would arrive. Narrow `subagentGroupBlocks` — whose only production caller IS that renderable check — to the groups that will draw, behind a named `isRenderableSubagentGroup` that `NativeChatToolRun` now shares in place of its own copy of the predicate, so the two guards cannot drift apart again. A childless group carrying its plain-text twin now prints the twin, which is what the twin is for; a bare one skips the row entirely. Also correct four comments that had stopped describing the code: - the roster header called `agentsStates` "always empty", contradicting the probe note in `codex-subagent-activity.ts` — it is empty on the MultiAgentV2 path that emits these items, and the V1 path does populate it; - `tokensByThread` was documented "retained UNCONDITIONALLY" while `handleTokenUsage` LRU-caps it 65 lines below; - the sweep is not "the LAST event a group ever gets": neither `settleTurn` nor `settleSession` removes the group, so a later `thread/tokenUsage/updated` naming a swept child still writes it. The retry condition is right; only its stated reason was wrong; - the `subAgentActivity` classification is not reached "for every event — and every one of them arrives twice". `handleSubagentItem` intercepts those items before `items.handle`, so the live path never consults the catalog; `restoreThread` replays them straight through, and is the real consumer. Comment-only apart from the childless-group guard. * fix(cli): stop `worker read` printing the subagent roster sentence twice The producer ALWAYS writes a roster block beside a plain-text twin carrying the same sentence, for clients that cannot draw the block. The renderer honours that contract from one side — it draws the block and drops the twin. The CLI honoured neither side: it printed the twin as prose AND rendered the block as `[subagents] <same sentence>`, so a real roster message read [system] Ran 2 subagents (1 failed) [subagents] Ran 2 subagents (1 failed) Take the mirror of the renderer's rule, which is the cleaner half for a text client: the twin IS the sentence, so print it and drop the block it stands in for. A block that arrives WITHOUT its twin — a shape the wire admits and no producer writes — still stands in for itself, because dropping it unconditionally would lose the roster entirely. Either way the sentence prints exactly once, off the same `subagentGroupFallbackText` helper both sides use. Unreachable through `readWorkerTranscript` today, whose provider rollout decoder never emits a `subagent-group` block — but the formatter is the CLI's contract for any transcript source, and the shape is already producible. The test pinned a TWIN-LESS group, a body `codexSubagentGroupBody` never writes: it asserted the exact double-print this fixes was correct output, and would have blessed either behaviour. Rebuild the fixture as the producer's real two-block row, with the sentence taken from the shared helper rather than hardcoded so it cannot drift, and assert the sentence appears exactly once. The twin-less shape keeps a test of its own, labelled as the wire-only fallback it is. Also record why `settleTurn` keys on the RAW `turnId` while `groupFor` remaps off-primary activity onto the primary's active turn. The asymmetry is load-bearing, not an oversight: were `settleTurn` to remap, a child thread ending its own turn would sweep the parent group and settle every still-working sibling to `unverifiable`. The lookup missing is the intended no-op. * fix(native-chat): add the subagent roster's localization keys and narrow its twin filters The roster row called 16 `components.native-chat.subagents.*` keys that were never added to the catalog, failing the localization gate. Synced en.json; the English strings are the component's own inline fallbacks, so nothing renders differently. Also tightens the twin/block handoff on both readers. The renderer dropped every text block once a roster was present, which is safe only because Codex writes a roster as its own message — the block is provider-agnostic, so a lane folding prose in beside one would have lost it on desktop while mobile kept it. And both readers decided "the twin is already printing" by recomputing the sentence and comparing bytes, which a roster from a newer build never matches: its unknown state normalizes to `unverifiable` here, so the CLI printed the roster twice with two different verdicts. Both now recognize a twin by shape. * test(native-chat): pin the roster twin recognizer against prose Both readers use it to decide the twin is already printing, so a false positive eats a message's real prose and a false negative prints the roster twice. * docs(codex): restore the roster's evictionated trigger to its KNOWN LIMITATION The previous rewrite dropped both triggers the old comment named and kept only the restart one, but eviction is the reachable half: `groupFor` caps `groups` at MAX_CODEX_SUBAGENT_GROUPS and drops the oldest-INSERTED entry (it returns an existing group without re-inserting, so this is not LRU), which can evict a still-live group in-process. The row identity is keyed on the group id alone, so the next activity item rebuilds that row from one child — the same N-to-1 rewrite, with no restart, and with the sweep skipped so the children never latch `unverifiable`. Also softens "every real turn id is freshly minted" to the provider assumption it is: turn ids are read verbatim off provider frames and nothing in this repo mints or asserts them. * docs(codex): justify the subagent wire notes from the live probe alone The roster and disposition comments explained themselves in terms of a provider-internal path taxonomy rather than anything this repo can observe. Restate them from the evidence Orca actually has: the live app-server probe saw `agentsStates` arrive empty, so nothing reads it; and `collabAgentToolCall` stays substantive because nothing guarantees a session reports subagent work as `subAgentActivity` at all — one that only emits the collab tool call gets no roster row, and suppressing that too would leave its fan-out blank. Same behaviour, same tests; comments and one test name only. * fix(native-chat): stop the roster's durable twin from claiming live subagents The spawn-group row is written once and revised in place, but the row itself is durable and replayed on every reconnect. Its plain-text twin — the only thing a client that cannot draw the block ever sees — froze a live count into that row: `Kicked off 4 subagents — 2 working`. The desktop renderer never shows it, and reconciles the block's `working` to `unverifiable` outside the live turn. A text-only reader does neither. When the writing process dies mid-flight the turn-end sweep never runs, so the sentence keeps asserting two running children forever, with nothing left that could re-check them. That is the collapse `docs/reference/ssh-execution-boundary.md` forbids: loss of contact reported as a live state. Fix it at the source rather than per client: the durable sentence now states only what survives its process — that the group was spawned, plus whatever outcome had latched. `Kicked off` vs `Ran` stays, because it reports whether an outcome was recorded at write time; saying `Ran` while children were in flight would assert they exited, the same error inverted. The adverse count stays so a failing fan-out still reads as failing. Reconciliation stays in the renderer, where the block still needs it. The twin recognizer keeps matching the legacy `— N working` shape: journals already hold those sentences and their rows replay forever, so dropping the branch would print every one of them twice, once as the block and once as prose the reader meant to drop. Also align the two functions that read `agentPath`. The root check compared the raw string while the label normalized separators, so `/root/` was both the turn itself and a child of it — a phantom row labelled `root` inflating the group by one. Compare normalized segments instead, keeping `/morpheus` a child. And a trailing segment with nothing visible in it survives the empty-segment filter and would draw a nameless row, so it now reads as no label and falls back to the placeholder. * fix(codex): key the subagent label collision ordinal on what the row draws `codexSubagentLabel` tested the trailing segment trimmed but returned it untrimmed, and `claimLabel` keys its collision ordinal on that string. Two children at `/root/read` and `/root/ read ` therefore both drew as `read` with no ordinal — the one thing the ordinal exists to prevent. Return the trimmed segment so labels that render identically collide. Also correct the legacy-clause note on the twin recognizer. It claimed shipped journals hold the old `— N working` sentence; the feature is unreleased, so the only journals holding one are dev worktrees of this branch. The branch still earns its place — those rows replay too, and it adds no false-positive surface the bare shape does not already carry — but the stated reason was wrong. * test(native-chat): retire the subagent-visibility guards now the roster renders Two tests from the sibling item-coverage PR asserted that subagent items stay on the generic gray row, explicitly gated on "until a real renderer exists". This branch is that renderer, so both guards fire on merge — the handoff they were written to mark rather than a regression. They now pin the other side of it: subAgentActivity is suppressed because the spawn-group roster renders it, and collabAgentToolCall deliberately stays visible, since nothing guarantees a session reports subagent work as subAgentActivity at all. Git merged both files without conflict; only running the suite surfaced this. * fix(native-chat): let a subagent swept at turn end still report what it did The turn-end sweep marks still-running children `unverifiable`, and the producer latched on any state that was not `working` — so `unverifiable` latched too. A subagent that outlived its turn then reported `completed`, the latch refused it, and a child that finished successfully read as one we never saw finish, permanently. One predicate was doing two jobs. `isTerminalSubagentState` is right for counting — `unverifiable` is not working — and wrong for latching, because `unverifiable` records that we stopped being able to see the child, not what it did. Split them: a child's own verdict latches, the sweep's guess does not. The reverse stays refused. Nothing returns to `working` once we have given up on it, so a straggler progress tick cannot re-light a settled row. Neither the latch nor the sweep was wrong alone, and both were tested; the defect lived only in their interaction, and only when a subagent outlives its turn — which the probe that drove this design never produced, because the parent it captured waited on its child. * fix: drop the @pnpm/exe lockfile drift a merge staged `git add -A` swept up the pnpm-lock.yaml mutation that every pnpm invocation leaves in this repo. Nineteen lines, thirteen of them @pnpm/exe, and it fails sixteen unrelated CI checks — native smoke, typecheck, packaging, xterm patch sync — none of which name the lockfile. * fix(native-chat): restore the item fall-through an inline dropped Inlining the subagent routing helper lost its null check: the roster returning null means it did not claim the item, and the translator must keep looking. Returning unconditionally once any thread item parsed swallowed every ordinary item — twelve settlement tests, none of them about subagents. * fix(orchestration): rebind the subagent block arm to the renamed bound state Main renamed clipMetadata's second parameter from a warnings set to a TranscriptBoundState. The subagent-group arm still passed `warnings`, and git merged both sides without a conflict because the lines never overlapped — the rename and the new arm are in different hunks. Typecheck was the only thing that could catch it, and did. * fix(codex): publish the turn tail for a subagent item the roster claims Main's #19055 added a `subAgentActivity` arm to the provider activity table, which is reached only through `publishActivity`. The roster's admission returned above that call, so every `subAgentActivity` item bypassed it and a fan-out that reports nothing else left the turn tail stuck on the previous frame's text. `publishActivity` already no-ops on a refused admission and on a non-primary thread, so routing the roster's admission through it is safe. Also corrects a docstring the frames extraction copy-pasted onto `settleOversizedNotification`. * fix(native-chat): bound the subagent roster on every boundary that carries it The spawn-group arm was the one collection in the worker-transcript payload with no cap, and the one block type mobile's `sanitizeBlock` forwarded verbatim. The producer's `MAX_CODEX_SUBAGENTS_PER_GROUP` does not reach either boundary: the journal schema declares no maximum on `agents`, and a remote host may run a build with a different cap. Both transports now cap the roster and bound `id`, `label` and the open `state` string; `label` and `id` also take the standard inline bound on the journal write path, where every other provider string already does. A token count is now persisted onto its entry at write time. `write` rebuilt `tokens` from the LRU-capped thread map on every write, so an eviction silently retracted a count the durable row had already shown. Adds the first coverage of the three roster caps, including the group eviction that rewrites a row from N children down to one. * fix(native-chat): keep the roster drawn beside tool calls and its clock honest The roster-only escape is keyed on `blocks.length === 0`, so a spawn group sharing its message with tool-call blocks fell through to the settled-turn guard, which returned bare null and took the roster with it — the exact regression the escape above was written to avoid, after the message row had already counted the group as renderable. Unreachable for Codex today; the block type is deliberately provider-agnostic, so it is live for the Claude lane. The elapsed clock also froze at a sibling's timestamp on a partial sweep: in a group where one child completed and another is unaccounted for, the ended turn left `working === 0` with the completed child's `settledAt`, and the row showed that child's duration as the group's run length. No clock is drawn while any child is `unverifiable` with no terminal timestamp. * perf(native-chat): bound the roster's provider strings without digesting them `boundInlineText` computes a sha256 and a Buffer BEFORE it checks the length, so the roster paid two digests per child on every write even when nothing was truncated — and `write()` runs on every claimed activity item (each delivered twice) and again from `handleTokenUsage`, which streams. A same-process A/B over a 64-child group: 76.5 us/write before, 2.0 us/write after (plain, unbounded row is 1.2 us). The cap changes with the mechanism. 16 KB is the tool-output bound; both readers of this row already clip the same fields to 512, so the producer was admitting ~2 MB per durable roster row for consumers to throw ~97% of away. One `MAX_SUBAGENT_FIELD_CHARS` now serves the producer and both readers, and the marker is an ellipsis rather than the tool-output truncation sentence — `id` is the roster key and the renderer's React key. Also raises the orchestration arm's per-group bound from 20 to the producer's 64, matching the mobile arm: a 21-64 child group is routinely producible here, so that arm clipped children and warned while its sibling clipped none. The slice and warning stay as the transport's own defence against a remote host with a larger cap. * fix(orchestration): suppress one roster block per twin, not all of them `hasTwin` was a single boolean over the whole message, so a message carrying two `subagent-group` blocks and one plain-text twin printed one sentence and dropped the second roster with no marker. Count the twins and claim one per group instead. Not reachable from this branch's producer, which writes one group per journal item, but the surrounding reasoning is explicitly about wire shapes the producer never writes and this is the adjacent one it missed. * fix(native-chat): loop-3 fixes to the Codex subagent worklog Five defects loop 2's own fixes introduced. Twin claiming was order-blind: the count-based claim silenced whichever roster block came first, so a lone twin belonging to a LATER group erased an earlier group's roster and printed the later sentence twice. Exact-text claims are now settled for every group before any leftover twin is claimed by position; the positional fallback stays for a newer build's frozen twin, which can never equal a recomputed sentence. `boundSubagentField` sliced UTF-16 units and could leave a lone high surrogate in a durable row, and the clip removed exactly the tail that told two children apart — `id` is the renderer's React key and `claimLabel` writes its repeat ordinal at the end. It now backs off a split pair and reserves the child index inside the bound, so both readers' re-clip cannot cut the disambiguator off again. `MAX_SUBAGENT_FIELD_CHARS`'s doc claimed a `groupId` bound the producer never applies; the doc now says so and why. The worker-transcript metadata cap is a separate literal again: it governs message ids, turn ids, tool-call names and image urls, so a roster-motivated change must not move it. * fix(native-chat): never infer a lost subagent from a turn boundary QA drove a real Codex session with three live `spawn_agent` children and sent a mid-turn correction. The roster row immediately read "Ran 3 subagents / 3 unverifiable" with no clock, while all three were still running — they reported `completed` 57-87s after that turn ended. Both sites rested on the same false premise: that a turn ending means no event will ever settle a child. Children outlive their turn and keep reporting into the same group. - Renderer: drop `reconcileSubagentRoster`. Nothing plumbed to the component distinguishes a row written by a dead host from a turn that merely ended — journal render items carry no epoch, and a new epoch deletes the rows of the one it supersedes — so the row now draws the state the journal recorded. Under-claiming beats over-claiming. - Main: stop sweeping on `turn/completed`. That sweep wrote `unverifiable` into the DURABLE journal, which mobile reads with no reconciliation. `turn/completed` is Codex's only turn-end notification, so an abort cannot be told apart from a clean finish; the safe default is not to sweep. `settleSession` — the provider actually being gone — is unchanged and is now the only sweep. `unverifiable` stays non-latching so a late verdict still lands. * test(native-chat): pin the roster at the seam the QA defect came from The mid-turn correction opens a new turn, so the fan-out's row stops being the current turn and the list hands the roster `activeTurnIsWorking={false}`. Asserted through the list, not the component, because that prop is what carried the wrong claim. * fix(native-chat): settle a roster the dying host never got to sweep `settleSession` only fires when the provider goes away while this process is alive. If the host itself dies, nothing sweeps and nothing reconciles on restore, so a `subagent-group` row persisted as `working` claimed live children forever — the mirror of the defect the previous commit fixed, and the same `ssh-execution-boundary.md` violation in the other direction. Reconciled host-side, at journal open, not in the renderer: mobile shows only the durable text twin and reconciles nothing, so a renderer-only fix would leave it claiming live children indefinitely. Opening the journal is also the one moment a host can honestly say the previous writer is gone. - `staleSubagentRosterRevisions` rewrites every child still reading `working` to `unverifiable` and regenerates the twin from the same summary, so the block and the sentence cannot disagree. - No terminal timestamp: the child stopped being observable at an unknown moment, and stamping the reopen would report the downtime as its run length. - Revises in place under the parsed identity, so a reopen upserts the row rather than appending a duplicate, and a second reopen writes nothing. - Skipped on a corrupt load: that journal is still owed a rebuild from provider history, and content past the repair's free sequence retires the demand. Reconciles journal ROWS, not roster state — the producer's in-process group map is untouched, so the roster's known seeding limitation is unchanged, as is `canReplaceSubagentState`: `unverifiable` still does not latch. --------- Co-authored-by: Merge Sim <sim@local>	2026-09-07 09:38:16 -07:00
Brennan BensonandMerge Sim	68dd3909c7	feat(orchestration): orchestrate native-born structured chat sessions (#18827) ... * feat(orchestration): orchestrate native-born structured chat sessions Orchestration resolves every worker through a terminal handle and a pane key backed by a live PTY. A session created directly as structured has neither, so it was not refused by orchestration — it was invisible. A coordinator could not start one, address one, or receive `worker_done` from one. Add a second authority source rather than a parameter channel. A registry maps a session id to the same three facts the PTY path supplies — a bearer handle, a pane key and a host scope — and the four runtime getters consult it before giving up on `ptysById`. `orchestration.send` and `verifyDispatchCapability` are untouched: authority stays host-derived and the CLI still cannot assert who it is. PTY handles short-circuit on the handle prefix, so the terminal path is unchanged. Mail travels as a session turn instead of as bytes, on a sibling lane that keeps the PTY lane's outstanding-run, waiter, reserved-type and batch rules. Orchestration's database stays the source of truth; the send is best-effort, exactly as the byte write is, and mail is consumed only on a proven-accepted dispatch. Delivery waits for the session to be between turns, because one provider refuses a mid-turn start outright and the other cannot acknowledge one inside the ack window. Security properties, each pinned by test: the pane key's leaf is random and persisted rather than derived, since `check` is identity-gated and accepts a caller-supplied pane key; the handle is a random bearer token; the child env carries no pane key, which would otherwise flow into hook pipelines that assume a PTY leaf; hook attestation stays closed for structured handles; and process continuity comes from record lineage, never the runtime fence, which the host bumps during its own crash recovery. Also remove the "Orchestration paused" notice, which gated only on dispatch status and rendered over bridge chat where orchestration always worked; refuse the implicit-sender fallback when a worktree has more than one candidate leaf instead of guessing; and collapse the archive kinds to one named type with a compile-time assertion that the capture set cannot drift ahead of the storable set. * fix(orchestration): answer the structured idle gate from the reduced timeline The structured pointer gate read a bounded 40-item tail page. A settled turn is tombstoned rather than rewritten, so an idle worker with any real history carries no turnLifecycle item at all and the "full page, no lifecycle item" guard read it as busy forever: every nudge after the worker's first substantial turn parked on a settle edge that had already passed, and the preamble tells workers not to poll. The attention gate had the mirror bug — a prompt older than the tail window was missed and the nudge was delivered into a session blocked on a human. Both facts now come from `journal.snapshot()`, the fully reduced timeline, via a new narrow `readGateFacts` host read; the policy module stays pure and still projects through the shared helpers the chat view reads. Also: - Park `session-not-attached` on the journal edge, so mail that arrives during a transient detach is redriven by the re-attach reset instead of sitting unread. - Resolve a structured worker's provider from the durable agent-session record when the registry entry was rehydrated, so a restarted Codex worker is no longer reported and archived as Claude. - Clear `structured_pointer_operations` in every `orchestration reset` scope. - Drop the per-chat-pane dispatch-status store subscription left behind by the removed paused notice, and re-pin the two terminal-pane ratchets it moves. - Hoist the identical pointer batch selection out of both delivery lanes into `selectOrchestrationPointerBatch`. - Refuse the pre-graph-ready focus-based guess for `requireUnambiguous` callers, matching the ready path. - Move the host teardown phase list into the teardown module it belongs to, which is what keeps the host inside its max-lines budget. * fix(orchestration): discard a structured worker session whose create settled unknown `commitStructuredAgentSessionCreate` answers `agent_session_operation_unknown` when `attach` SUCCEEDED and only the tab publish failed, so `created.ok === false` is not proof that nothing exists. The worker start read it that way and skipped `discardCreatedSession`, leaving a live provider child that took no hold, has no `bindingsByDispatchId` entry and no published tab — the outer `releaseStructuredWorkerSession` no-ops without a binding, and a session that never had a holder never starts the eviction clock, so nothing in the runtime ever retires it. A throw out of the commit half is past `attach` for the same reason; the pre-commit half refuses rather than throwing. Cleanup now asks whether the create MAY have committed, via the existing `isDefinitiveAgentSessionCreateRefusal` predicate. Also: - Strengthen the pre-ready `requireUnambiguous` test so it actually pins the guard: the snapshot now carries a focused terminal, so deleting the `? [] :` ternary turns the test red instead of leaving the refusal to the ambiguous `listTerminals` fallback. - Correct the guard's justification comment, which cited `orchestration check` as covered. `check` resolves through the `--terminal` scope and still guesses; the guard covers the implicit `--from` sender, and a structured worker is covered by the `ORCA_TERMINAL_HANDLE` baked into its child. * docs(orchestration): stop two structured-worker comments claiming guarantees the code does not give The send-time owner re-check reads `target.refusal`, the snapshot the resolver already admitted, so `decideStructuredPointerDelivery` can only agree with the resolve-time answer and `owner-not-settled-native` is unreachable from that call site. What actually fences an owner that moved is `expectedRuntimeFence`, which a handoff bumps. Say that, so nobody later drops the fence trusting a re-check that is structurally a tautology. `discardCreatedSession` was credited with retiring "a published background tab that no dispatch owns". It hides the DURABLE tab reference and closes the session; the live tab snapshot keeps the row, so the background tab this start published stays on screen until the app restarts. Same for stop and release. The comment now describes what the two calls do — including that both are no-ops on a session that was never attached, which is what makes the non-definitive-refusal path safe to reach unconditionally. * fix(orchestration): retire a structured worker's chat tab when the worker settles Starting a structured worker always publishes a real `agent-session:<id>` tab, but every settlement path only called `setSessionTabVisibility(sessionId, false)` plus `host.close(sessionId)`. That clears the DURABLE restore index and leaves the LIVE snapshot untouched, so stop, release and the half-started discard all left a dead "Claude Chat" / "Codex Chat" tab in the worktree's tab bar for the rest of the app session — five dispatches, five dead tabs — and opening one re-attached the released session, respawning a provider child outside orchestration's hold accounting. The snapshot-pruning half of `closeStructuredAgentSessionTab` is extracted into `structured-agent-session-tab-retirement.ts` and exposed on the runtime as `retireStructuredAgentSessionTabFromSnapshot`, so the user-initiated tab close and the three settlements share one implementation instead of a second copy. The settlement side is best-effort BY CONSTRUCTION: it runs only after the close is already proven, calls the runtime method optionally, and swallows any throw. It talks to no renderer, so the startup release reconciler can call it too. Nothing here can turn a proven stop into `release_unknown`. * fix(orchestration): stop a structured worker's nudges, archive and liveness from lying Five defects in the structured-worker lanes, each with the same shape: a check that answered from something other than what it claimed to measure. - The pointer lane gated a WORKER's `dispatch:` mailbox on its RUN's outstanding delivery. Delivery rows exist only for a `run:` address, so that row belongs to the coordinator — and a coordinator holds one for exactly as long as it is acting on received mail, which is when it replies to its workers. The gate is gone; there is no coordinator mailbox in this lane to protect. - `dispatch-rejected` now parks on the journal edge. A rejection consumes no mail and nothing else redrives the mailbox, so an unparked pointer left the worker idle on durable mail until unrelated mail happened to arrive. - The released journal archive bounded forward — keeping the HEAD — before capping newest-first, so a long worker's archive ended at its early exploration and dropped the answer it was released for, under a warning that said the oldest messages had gone. One newest-first pass now, and the warning is true. - The durable pointer operation id was reused on a matching BODY fingerprint, and the body names only the unread count. Two unrelated same-size batches collided, the host replayed its ledger answer as `accepted` with no turn sent, and the lane marked the new mail delivered. Reuse is keyed on the batch's message ids. - `worker-read` on a structured worker hardcoded `terminal: 'running'` and emitted no `liveness`, so a runtime that could not see the session reported the worker as alive. It now carries the observed verdict, as the PTY branch does. Also: the live journal cursor is an index into a re-derived tail window, so the page's oldest item joins its source identity — a slid window now answers `source_changed` instead of silently resuming past the items it skipped. And a stop that reached no host reports `processAction: 'none'`, after installing the host the way release already does. * fix(orchestration): stop a released structured archive claiming a close that never landed `worker-read` on a released structured worker hardcoded `liveness: 'exited'`. The archive is frozen BEFORE the close, so it proves nothing about the provider child, and the read is served for `release_state` in `releasing` / `unknown` too — the two states that exist precisely to record a close that did NOT land. A coordinator that read `exited` from a `release_unknown` worker would start a replacement over the same worktree while the original child was still attached, which is the outcome docs/reference/ssh-execution-boundary.md rule 2 exists to prevent, and it contradicts the release receipt's own "the structured session close was not proven" text. The verdict now comes from the resource row the read already holds: only a settled `released` row is `exited`, everything else is `unverifiable` — which the existing mapping renders as `terminal: 'unknown'`, the same way the live branch does. * fix(orchestration): stop a structured worker-start reporting a preamble it never delivered Two ways a structured `worker-start` handed the coordinator a receipt that did not describe the worker it got. `sendStructuredWorkerPreamble` threw only on a refusal and on `rejected`, so a submission that settled `unknown` fell through as success: the start pushed `dispatch_input: accepted` and marked the dispatch ready. `unknown` is not rare — `dispatchSafely` converts ANY thrown adapter call (provider child gone, transport dropped, ack window missed) into it, and `performSend` still returns ok. The worker then has no task spec while its coordinator blocks in `check --wait --types worker_done` until timeout. This PR's own mail lane already states the rule — "`pending` is not yet an acknowledgement; only `accepted` may consume mail" — so the preamble now applies it too, and raises `operation_unknown` for the states that prove neither delivery nor failure, which is the code `failWorkerStartWithReceipt` turns into the `outcome_unknown` receipt whose nextCommands send the coordinator to look. `rejected` stays a proven failure. `--structured` also accepted `--model` / `--effort` and dropped them: structured session creation takes no launch preferences, while `launch.receipt.effective` echoes whatever was requested either way, so `--model opus` ran on the workspace default and the receipt still said `opus`. Refused now, for the same reason `--terminal` refuses them, and the spec note records that refusal along with the new-child/new-top-level one it never mentioned. Tests: the refusal guard had no coverage at all, and `structured-mailbox-pointer-host` — where the full-timeline gate read lives — had none either; reinstating the bounded tail there left the whole repo green. Both are covered now, and the vacuous "never selects an exact provider session" case is re-pointed at the absent `ORCA_PANE_KEY` that actually keeps that selector shut. * fix(orchestration): let a structured worker actually reach the Orca CLI, and stop four settlements lying A structured worker's provider child runs `orca orchestration ...` exactly like a PTY worker's agent does, but it was handed the ambient PATH. On packaged Linux the CLI installs as `orca-ide` so it never claims GNOME Orca's /usr/bin/orca (#7904), so bare `orca` execs the screen reader and the worker can never read mail, reply or send worker_done; on packaged macOS/Windows the bundled launcher is only reachable from the app's own resources dir. The PTY lane already solves this inside `buildPtyHostEnv`; that block is now its own module and both lanes call it. Also: - a worker start that fails AFTER its session exists now discards the session, so a failed start stops stranding a dead chat tab that the durable restore index republishes on every launch; - a structured worker's resource reconciles to `released` after settlement forgot its identity, instead of answering `unverifiable` for the life of the DB; - `closeAttempted` is set only once a close is issued, so a tab-visibility failure can no longer report `closed_agent_terminal` for a running child; - `forgetSession` prunes only what the settled worker parked, not every sibling whose target momentarily fails to resolve; - release settles with an explicitly empty, warned archive when the journal is unreadable AND the session is proven exited — closing the chat tab is routine, and `archive_failed` there wedged release on evidence that could never arrive; - the new migration test uses mkdtemp and cleans up, so it stops failing Windows CI and leaking. * fix(orchestration): merge the duplicated release-receipts import The release-completion module imported ./orchestration-worker-release-receipts twice, which trips import/no-duplicates in audit:code-quality:native. The changed-file gate does not load that config, so only whole-tree CI saw it. * docs(runtime): note that a background structured tab re-publish is a no-op The activate:false branch for an already-published session returns without writing the snapshot or emitting, so it cannot re-surface a client whose mirror lost the tab. Orchestration is safe from this only incidentally. * feat(orchestration): make the worker mode the user's own default, not a flag `worker-start --structured` was an explicit opt-in that REFUSED --on, --terminal, --model/--effort and worktree-creating placements. The flag, its spec entry and the `structured` RPC param are gone: the mode now follows the user's setting for new agent tabs, so a local claude/codex worker is a structured chat session whenever the user's own default says agent tabs open as one. A setting is a preference, not a demand, so none of those combinations refuses any more. A dispatch that cannot be structured starts an ordinary PTY terminal worker and the receipt names the mode that ran and why, so the fallback is never silent: - a remote --on, an existing --terminal, a new-child/new-top-level worktree and --model/--effort are decided from the request; - the agent, TUI launch customization, Codex-on-Windows and the runtime capability are decided by the shared launch route; - WSL, remoteness and the Windows start-time gate are settled by the executing host's own agentSession.createSupport, asked once the worktree resolves and before anything is created, so a refusal is a terminal worker rather than a failed start. The decision is the renderer's, lifted rather than copied: `resolveAgentLaunchRoute`'s structured half and the settings predicate now live in shared/structured-native-chat-launch-route, which both surfaces call, and the TUI launch customization test moves to shared beside it. `getClientSettings` gains the two native-chat default booleans it was missing. No security invariant moves: the structured worker registry, bearer handle, persisted pane key, the absence of ORCA_PANE_KEY from the child env, hook attestation and lineage-derived process incarnation are untouched. * fix(orchestration): stop the worker mode leaking into the agent contract The mode a worker runs in is a runtime implementation detail. An agent should be taught the same verbs, run the same commands and read the same receipts whether it is a structured chat session or a PTY terminal — otherwise a settings-driven fallback silently changes what the agent can do. The real leak was `canDispatchSubWorkers`, which was forced false for a structured worker. That was not a wording choice: `worker-start` resolved `--from` through `showTerminal`, which needs a live PTY or renderer leaf, so a `structworker_` coordinator genuinely could not dispatch. Rather than withhold the capability, the one fact the command needs from `--from` — its worktree id — now comes from `getOrchestrationDispatchAuthority`, the same authority the pane-key and process-incarnation getters already answer structured handles from. Sub-dispatch is gated on depth alone, identically for both modes. `showTerminal` itself is deliberately NOT taught structured handles: it returns a ptyId, a leaf id and a pane runtime id, and synthesising those for a session with no PTY would hand every caller of a public terminal verb something that looks writable and is not. `inspectWorkerTerminal` already returns `terminal: null` for exactly that reason. Also neutralised three agent-visible refusals that named the worker's kind: a `worker-read --source terminal` on a worker with no terminal now names the sources that do work, and both archive refusals say "transcript output" rather than "structured chat output" (the PTY `transcript_pin` branch said "structured" too). New tests pin both properties: the two preambles are byte-identical once the handle and per-dispatch ids are normalised, and a structured coordinator starts a worker with `showTerminal` rejecting. * fix(orchestration): stop claiming a structured worker was checked for a prompt worker-show reported observation.agentWait: null for every structured worker. The field's own contract says null means Orca looked and found no wait, and absent means it never looked — and nothing looks here: a structured worker parks on a journal question item, which no terminal prompt scan can see. So null was a false negative on the one field a coordinator is explicitly told to read, and it was mode-dependent: the same worker as a PTY would have reported the wait. Absent is both the honest value and a state a PTY worker already reaches (an older host, an unreadable pane, a probe that did not answer), so it discloses nothing about which mode ran. * docs(cli): stop the worker-start spec pointing a caller at the worker kind The note said "the receipt mode field names the mode used and why", which is an instruction to read a field no verb behaves differently for — the one thing the mode was not supposed to become. It now says what a caller actually needs: the dispatch always starts, the options passed are the ones honoured, and every worker is driven the same way. The receipt still carries the mode for operators and telemetry; nothing tells an agent to look at it. * perf(orchestration): coalesce the structured redrive edge Every journal batch is a redrive candidate, because a settled turn is tombstoned rather than rewritten — there is no completed row to watch for. That is free while nothing is parked on the session, but once mail IS parked each batch re-resolved the dispatch, queried unread mail and read the host's gate facts, only to re-park because the turn was still running. A turn streaming tool calls paid that per batch. The edge now coalesces on a 300ms quiet window with a 2s starvation cap, so a streaming turn costs a handful of evaluations instead of one per batch and a settled turn still nudges promptly. Delivery semantics are untouched: the gate, the accepted/rejected/unknown handling and the retain rules all still run exactly as before, just fewer times. Nor is this the path fresh mail takes to an idle worker — that is `deliverForHandle` at enqueue time, which this does not touch — so the common case gains no latency. The mechanism is the session.tabs notify coalescer, generalised into `keyed-trailing-edge-coalescer` and called by both rather than duplicated; the session.tabs windows stay where they were, since 50ms is right for a spinner title and far too tight for a journal stream. Disposal drops the pending timer rather than flushing it, on the existing subscription disposer that every settlement already reaches, so a redrive can never fire for a session no dispatch owns. * fix(orchestration): deliver direct peer mail to a structured worker, and let a peer read it Two agent-to-agent verbs had no answer for a worker that IS a structured agent session, and both failed quietly. Mail addressed to a worker's own bearer handle — how agents mail each other outside a dispatch — fell between the lanes. The send stored durably and reported success, `getLiveTerminalPaneKey` resolved the recipient, and then neither lane claimed the mailbox: the structured resolver answered only `dispatch:` addresses, and the PTY lane refuses a structured handle outright. Nothing errored and nothing logged, so the worker never reacted and the peer waiting on a reply hung. The resolver now also answers a bare worker handle, preferring that worker's active dispatch so peer and coordinator nudges share one operation-ledger budget. A worker BETWEEN dispatches is still nudged, under a session-scoped key: a dispatch says nothing about whether delivery is safe — the idle gate and the lease fence do — and its own `check` reads exactly the direct mailbox the mail is sitting in. The dispatch caller key is left byte-identical, because the ledger is keyed on (callerKey, operationId) and reshaping it would re-mint nudges already in flight as second turns. `terminal read` had no structured branch, so the only peer-accessible read verb answered `terminal_handle_stale` for a live worker; `worker-read` is closed to a peer, which holds neither coordinator standing nor a dispatch id. It now serves the session's journal, projected to LINES and paged by the same reader the PTY tail uses, so the result stays a plain RuntimeTerminalRead and nothing an agent reads discloses which kind of worker answered. Bounding and dispatch-capability redaction are the archive path's, reused rather than rebuilt. A session that is not attached refuses with the existing not-attached code rather than returning an empty tail, which would read as "this worker has said nothing". `terminal.show` still refuses a structured handle. This is read-only on purpose: synthesising a ptyId/leafId/paneRuntimeId would hand every public terminal verb something that looks writable and is not. * fix(orchestration): stop three PTY-only probes answering for structured sessions Three defects, one shape: a probe that enumerates PTYs or resolves a pane was standing in for a question that is not about panes at all. `worktree rm` destroyed a live structured worker. `killAllProcessesForWorktree` sweeps the renderer graph, the provider session list and the local pty-registry, and a structured session is registered on none of them — so all three counted zero, nothing errored, and removal deleted the checkout out from under a running provider child, which kept running with its `cwd` gone while the dispatch still reported the worker live and exact. A fourth sweep now asks what the other three cannot: membership by `location.workspaceId`, which covers a plain chat session as well as a dispatched worker, and liveness by the same `live`/`unverifiable`/`exited` observation the rest of the structured surface uses. It REFUSES a destructive removal rather than auto-closing, on the same bargain and the same `--force` escape hatch as the unstopped-PTY gate — this is the verb that deletes a user's work, and a running agent is exactly what they would want to be told about. Force closes the sessions properly instead of orphaning a child. Best-effort reconciliation callers are excluded: they repair state, delete nothing, and must never be failed closed. Twelve coordinator verbs failed for a structured worker running as itself. `isLiveTerminalHandle` validated `ORCA_TERMINAL_HANDLE` with `terminal.show`, a PTY verb whose leaf lookup misses for a session that never had a pane; the pane remint that would have recovered it needs `ORCA_PANE_KEY`, which a structured child deliberately does not carry, so every one of them died on `no_active_sender_terminal` — including the ones the worker's own dispatch preamble tells it to run. The identity question gets its own probe, `terminal.resolveIdentity`: a handle and a boolean and nothing writable. `terminal.show` still refuses a structured handle, because synthesising ptyId/leafId/paneRuntimeId would hand every public terminal verb something that looks writable and is not. The PTY half is byte-for-byte today's check, `getLiveLeafForHandle` included, so its `rendererGraphEpoch` re-check still runs — that check is the whole reason the sender is validated at all, and a cheaper probe would have quietly started passing stale post-reload handles. A host that predates the method answers `method_not_found` and the client falls back to `terminal.show`, which is correct for that host: one without the identity probe has no structured workers to miss. `dispatch --inject` reported `no_agent_detected` for a structured worker, because `isTerminalRunningAgent` reaches `getLiveLeaf`, throws, and the catch returns false. A structured session IS the agent; there is no foreground process to recognise, so it answers before the PTY probes rather than through them. Also: a Run whose coordinator is structured now gets its `run:` mail. Both lanes declined and neither logged — the PTY lane because the owner is structured, the structured lane because the mailbox was not `dispatch:` — so each half believed the other owned it. The PTY lane's reasoning (a coordinator blocks in `check --wait`, where a waiter preempts pointer delivery) does not transfer: a structured coordinator is a chat session whose turn ends. Its `run:` deliveries take the `hasOutstandingRunDelivery` gate the PTY lane applies for exactly that mailbox, and only for that mailbox. The test that would have caught the twelve drives the CLI with `ORCA_TERMINAL_HANDLE=structworker_…` and no `--from`. Every existing orchestration CLI test passes `--from` explicitly, so the resolver a real worker goes through was never exercised — which is why the suite stayed green while the preamble failed on its first line. Two files crossed their line ceiling and are split rather than waived: `worktree-teardown.ts` sheds its two PTY-surface sweeps and the deadline arithmetic they share, and `orchestration.test.ts` — which sat exactly on 800 — sheds the two caller-identity suites this change rewrote. * fix(orchestration): arm the takeover signal for structured chat input `worker-release` closed a structured session a user had taken over, losing work mid-conversation, while `orchestration-worker-specs.ts:106` promised "Never closes … user-taken-over terminals". Every guard was already correct and simply never armed. `reportWorkerTerminalUserInput` has exactly one call site — the real-user-input signal on a PTY connection — so structured chat input never reached `orchestration.workerTerminalUserInput`, `markWorkerTerminalUserOwned` never ran, ownership stayed `owned` instead of `user_owned`, `retainedReason` never returned `user_takeover`, and `stopStructuredWorker` proceeded. The durable flag is reused as-is rather than given a parallel mechanism: it exists precisely so a restart, an SSH drop or a renderer remount cannot erase a takeover. Addressed by SESSION, never by pane key. A structured worker's pane key is a random identity credential — anyone holding it can read and consume that worker's mailbox, and session ids are embedded in tab ids in plain text — so it stays in main and the runtime resolves the session to it. Handing it to a renderer to echo back would make it learnable by anyone who can see a chat pane. The RPC gains an optional `sessionId` alongside `paneKey`; a host that predates it rejects the call, and the report is already best-effort with a catch, so that host degrades to exactly today's behaviour rather than failing a send. The signal fires from the composer send hook and only past `accepted`: the outbox dispatcher retries, and orchestration's own pointer nudges never pass through the composer at all — so neither can be mistaken for a user takeover. * fix(orchestration): reach structured workers through group addresses `orca orchestration send --to @all` — and `@idle`, `@claude`, `@codex`, `@worktree:<id>` — silently skipped every structured worker. Recipients came from `listTerminals`, which enumerates leaves and PTYs, and a structured session is on neither. The exclusion happened BEFORE per-recipient resolution, so the `SendRecipientWarning` machinery never ran: the caller got exit 0 and a receipt naming the workers that did resolve, and a broadcast "stop work" or "base moved" reached the PTY workers and nobody else. With every worker structured it degraded to `terminal_not_found`, which reads as "the group was empty". Fixed at the group-resolution site rather than inside `listTerminals`. That result is published to paired mobile and remote clients and to consumers that assume a summary carries a `ptyId` or is writable, so widening it is its own change under `docs/reference/remote-wire-compatibility.md`. Group addressing reads exactly three fields off a recipient, and `RuntimeTerminalSummary` already satisfies them structurally, so the resolver widens to that smaller shape and nothing here invents a `worktreePath` or a `branch`. Candidates are liveness- gated on the same observation the rest of the structured surface uses — mail addressed to a settled worker would be stored for a lane that will never deliver it — and once a worker IS a candidate, the existing per-recipient warnings cover it, so an unresolvable one is reported rather than dropped. `@idle` needed more than enumeration: `getAgentStatusForHandle` reaches a PTY probe that throws for a handle with no pane, so a structured worker would have been enumerated and then silently dropped from the one group address that selects on status. It now answers from the session's journal — and off the FULL reduced timeline, never a bounded tail. Settlement tombstones the running turn's lifecycle item rather than rewriting it, so on any page-sized read a long tool-calling turn looks identical to an idle session; `@idle` would then broadcast into a running turn, which Codex answers with `turn already running` and Claude queues behind. An unreadable session answers null, never idle. `terminal list` and `worktree ps` still omit structured workers; that is the wire-visible half and is deliberately not in this change. * fix(orchestration): refuse rather than guess when a chat session has no identity An ordinary structured chat session — not a dispatched worker — is spawned with no `ORCA_TERMINAL_HANDLE`, because `structuredWorkerChildIdentityEnv` early- returns for any session outside the worker registry. `orca orchestration check` then fell through to `terminal.resolveActive`, which picks the focused tab's active leaf or the first leaf in the worktree. It returned a valid handle, so nothing errored — and `check` is destructive by default, so it consumed another pane's oldest unacknowledged batch and marked it read. The rightful worker never saw that mail. `requireUnambiguous` does not fix this, only narrows it: it refuses when MULTIPLE leaves could be meant, and with exactly one terminal pane in the worktree the guess still resolves — to a sibling. "One terminal pane plus one chat tab" is a normal layout, so the common case stayed broken. The pinned test is that case. So the child now carries `ORCA_STRUCTURED_SESSION`, and every remaining route that would GUESS an implicit terminal refuses on it with an error naming the flag to pass. The marker names NOTHING — no handle, no pane key, no session id, no token — which is the whole reason it is safe: it cannot be replayed, cannot impersonate, and cannot flow into the hook-attestation, agent-row or mobile-projection pipelines the way a pane key would. That makes it a different decision from withholding `ORCA_PANE_KEY`, not a reversal of it. It also grants no CLI reachability, so packaged builds keep exactly today's exposure. The comment at `orca-runtime-adopt-terminal-orphans-from-inventory.ts` that justified the guess — "a structured worker is covered instead by the `ORCA_TERMINAL_HANDLE` its child is spawned with" — was true only for dispatched workers and false for every other structured session, a population this branch creates. It now says which case it covers and which case it does not. * fix(orchestration): stop two surfaces lying about a worker with no terminal `orca terminal <verb>` answered `terminal_handle_stale` for a structured worker's handle. Nothing went stale: the session is live and simply has no terminal, and it never had one — so callers acted on a false claim and went hunting for a remint that cannot exist. The refusal now carries its own code and names the structured equivalents (`orca terminal read`, `worker-read --source transcript`, `orca orchestration send`), so an agent that lands there learns what to run rather than what failed. A PTY handle that really did go stale keeps the old error, and so does a session this runtime no longer owns — that handle IS dead. `terminal.show` stays non-resolving: synthesising a ptyId/leafId/paneRuntimeId would hand every public terminal verb something that looks writable and is not. `orchestration-worker-specs.ts` promised "the same verbs, the same handle, and the same worker-read sources", and all three clauses were false for a worker with no terminal. A spec agents read must not carry a false promise, so it now states the limitation and the alternative that always works. Note this had to be reconciled with an invariant this branch already holds: the worker MODE must stay opaque, or a coordinator starts branching on something no verb it runs behaves differently for. So the note says "not every worker has a terminal" and points at `--source auto`/`--source transcript` WITHOUT naming a kind — the same mode-neutral wording `readStructuredWorkerOutput` already uses when it refuses `--source terminal`. Both properties are now pinned by tests, so neither can be restored by breaking the other. * fix(orchestration): close the review findings on the structured parity work Four defects and two follow-ups from the delta review. The `worktree rm` refusal was a dead end in the desktop UI. Its message matched no matcher in `classifyWorktreeForceDeleteReason`, and an ordinary desktop delete already passes `force=true` for the dirty-file skip, so classification returned null unconditionally: the toast showed raw CLI wording with no Force Delete button, and a user with a live chat session was stuck unless they knew to reach for the CLI. That is the #11960 shape `shared/worktree/removal.ts` documents, so the refusal now has its own prefix, matcher, `WorktreeForceDeleteReason` and toast copy, classified BEFORE the `force` guard and nulled once the waiver is spent — exactly how `unstopped-pty` is handled, with matcher and hint kept in the same file as that contract requires. The copy says Force Delete will close a running conversation rather than borrowing the "could not confirm" wording, because Orca watched these sessions stay attached; there is no doubt to waive. Structured `terminal read` cursors were unsound and are now refused. The PTY cursor indexes an append-only completed-line buffer with a monotone count; a session journal is a BOUNDED tail re-projected on every read, so a saved index addressed different lines as the journal grew — and `truncated` could never fire to say so, because it tests `cursor < oldestCursor` and `oldestCursor` was always 0. A poller got wrong or duplicated lines under `truncated:false`. Separately, a streaming turn's lines counted as completed with `partialLine` hardcoded empty, so a mid-turn cursor consumed a half-written line whose growth was never redelivered — the `"hel"`/`"hello"` hazard the PTY reader guards against. The journal does have stable item identity, but `terminal.read`'s cursor is a number on the wire and cannot carry it, so a cursor read now refuses and names `worker-read --source transcript`, which already has that contract including `source_changed`. No cursor space is advertised either: `nextCursor` is null and the cursor fields are absent, rather than claiming an index the next read cannot honour. The header claim that all four fields kept their meanings was true of the shape and false of the invariants; it now says which ones hold. Two fixes had no test at their real seam, which is the same failure that produced this whole set — the runtime tested directly, the seam tested by neither. The group-addressing test hand-composed the recipient list itself, so deleting the composition at the call site left it green; it now drives `sendGroupMessage` with no PTY terminals at all. Nothing referenced `isLiveStructuredAgent`, so the `dispatch --inject` fix had no red-then-green at all; it now has one driving `RuntimeTerminalAgentPresence.isRunning`. Both were ablated and confirmed red. Folder-workspace removals sweep and kill PTYs without `requirePhysicalStop`, so the structured sweep no-opped there and left a live session bound to a workspace about to be forgotten. They now close best-effort under an explicit `closeStructuredSessions` flag, kept separate from `requirePhysicalStop` because the two questions differ: that one asks whether a stop must be PROVEN before files are touched, and it is what licenses a refusal. These paths do not refuse — the root is shared so no checkout vanishes under the child, and one of them is a never-throw forget a refusal would wedge. Reconciliation sweeps set neither and still close nothing. Also: the force close is raced against the same sweep deadline every PTY surface is bounded by, so a wedged provider close reports the timeout instead of hanging `worktree rm --force` forever; and the refusal now prints a count and the providers instead of raw session ids, which our own marker rationale treats as one tab-id hop from a credential. * test: pin structured-session close on the folder-workspace removal path The folder and orphan removal callers now pass closeStructuredSessions so a live structured session is closed best-effort rather than left bound to a workspace Orca has forgotten. These three exact-args characterizations describe that call and had not been updated. * fix(orchestration): stop the structured worker-read cursor misdelivering silently `worker-read --source transcript` for a structured worker fingerprinted only the oldest item's id, so `source_changed` fired when the window slid off the front and could NOT fire when the page's contents changed under a stable oldest item — which is the normal case, because the journal is a reduced, mutable timeline. A `running` tool item gains its `[tool result]` at its original sequence once later items exist, the 60ms delta coalescer revises a message in place, settlement can rewrite an item smaller, and a pending approval projects to null until it resolves and then appears in the MIDDLE of the array. Two silent failures followed, both returning ok. Omission: a caller handed a coalesced `hel`, resuming past it, never received the revision to `hello world` — the same defect we refused to ship on the terminal read path, already shipped here. Duplication: a resolved approval inserted ahead of a saved index, which was still accepted, so the caller re-read content it already had. The blast radius is the coordinator polling loop, the verb's primary consumer. The anchor is now the oldest item PLUS every item whose projected message sits below the caller's position, by id and revision. `createWorkerOutputSourceIdentity` already takes an arbitrary string array and the cursor is already opaque base64url carrying its own position, so neither the wire shape nor the `source_changed` contract changes. Prefix-scoped rather than whole-page deliberately: fingerprinting every item on the page would flip the identity every 60ms with the coalescer window during an active turn, making the cursor unusable exactly while the worker is working — that trades a silent bug for a useless verb. Tail growth the caller has not read cannot invalidate; any change to what it already holds does. Position-dependence is safe because `p` rides in the same opaque payload as the identity, and the returned cursor is stamped with the identity of its own end, which is precisely what the next read recomputes. The frozen archive keeps a constant identity: no item can be revised under a caller there, so it has no prefix to fingerprint. Both silent shapes are pinned across a page boundary with the journal mutating between reads — a static-journal test passes either way. Two ablations at the real call site: reverting to the oldest-item-only anchor turns both red, and widening the prefix to the whole page turns the tail-growth case red, which is what proves the scoping is real in both directions. * docs(orchestration): stop the structured terminal-read refusal recommending a dead end The refusal told a peer to "page it with `orca orchestration worker-read --source transcript`", which is wrong three ways and this file said so itself: its own header explains that this verb exists BECAUSE `worker-read` demands a dispatch id and coordinator standing "a peer does not have" — and then the refusal sent that same peer there. The verb it named is also a window index over the same bounded page, so it is not a paging answer even for a caller who can reach it; under load it now answers `source_changed` on most polls, which is better than the silent hole it had before but still not what the sentence promised. The refusal now says what actually works — the tail is bounded and newest-last, so poll it and diff — and names no alternative, because there is none. That is the honest framing: a durable cursor is not achievable here at all, rather than blocked on the wire shape. The journal is a reduced, MUTABLE timeline: an item's projected text changes at its original sequence after later items exist, the delta coalescer revises repeatedly, settlement can rewrite an item smaller, a pending approval renders as nothing and then as something, and `sequence` resets on epoch rollover. No index, numeric or opaque, survives that. So the docstring's "pagination with a real anchor lives on `worker-read --source transcript`" is gone too — there is no real anchor there — and the file now records why no windowed alternative should be built later: a broken cursor fails UNSAFE, as a silent hole in a poller's output, while diffing a bounded tail fails safe as a harmless re-read, and a second paging-shaped verb would invite the PTY assumptions this one cannot honour. The test asserted the old advice, so it now pins the contract instead: the refusal explains the working approach and must never name `worker-read`. `worker-read --source transcript` remains a good bounded snapshot for a coordinator reading a worker it dispatched; only the "or page it with" clause was false. * fix(i18n): add the missing worktree-removal agent-session refusal string The structured-session removal refusal introduced a translate() key with no en.json entry. Nothing local catches that: typecheck passes, and the full suite passes, because a missing key falls back to its inline default at runtime. Only verify:localization-catalog fails on it, which is why CI's static analysis reddened on a branch that was green everywhere else. Fallback wording mirrors the sibling unstoppedPtyLive string, since the two refusals differ only in what is still running and what Force Delete does to it. * test(codex): expect the no-identity marker on an unregistered structured child The refuse-rather-than-guess marker landed after these expectations were written, and all three assert exact env equality on the unregistered path — the one branch that now carries ORCA_STRUCTURED_SESSION. One of the two files was added by this same branch, so this is a self-inflicted drift; the other predates the branch and was broken by it. The marker's presence is still pinned positively by structured-worker-child-identity-env.test.ts and the CLI's orchestration-structured-session-no-identity.test.ts, so relaxing these three exact-equality checks loses no coverage of the security property. * fix(orchestration): require exit evidence before settling structured close --------- Co-authored-by: Merge Sim <sim@local>	2026-09-06 20:24:21 -07:00