Commit Graph
536 Commits
Author SHA1 Message Date
Neil fa977b6521 docs(ssh): correct the design where a live client disproved it
D2, D3 and D4 each stated something about OpenSSH that turned out to be wrong
when tested against a real client and sshd rather than read from the source.

D3's premise is the notable one: OpenSSH is not type-scoped at all, so it does
not avoid the RSA-era false alarm the way the doc claimed. It avoids the
situation via order_hostkeyalgs and hard-fails when the situation arises anyway.
The conclusion survives — the ordering is still what makes our scoping safe —
but for a different reason than the one written down, and a reader would have
drawn the wrong lesson.

D2 gains the two rules that actually bite: the entry condition to the fallback
pass, and HostKeyAlias suppressing the port. D4 records both reversals with their
reasoning and the residual risk each one accepts, and the ssh -G spelling trap
that made StrictHostKeyChecking dead on arrival.

Corrections are kept visible rather than edited out, per the note at the top of
the file.
2026-08-14 13:41:14 -07:00
Neil 73132520de docs(ssh): record the two assumptions a live client confirmed
Both were load-bearing and neither was obvious: the bare-host fallback pass may
not report a change, and unknown-type-known-host is what ssh itself does rather
than something we invented. Getting the first backwards would have refused hosts
ssh connects to happily, which is the failure mode that looks like caution.
2026-08-14 04:09:32 -07:00
Neil b71b007934 docs(ssh): record where the rejection message actually lands
Traced end to end, because a rejection the user cannot read is a half-shipped
feature — and two of the surfaces were dropping it entirely, both now fixed.

What is left is written down rather than guessed at: the status bar renders only
'Error', the terminal overlay's call to action still invites a retry that cannot
succeed, toasts carry Electron's remote-method prefix, and the paired-web path
replaces the text with 'SSH connection unavailable' on every route — which also
affects a DESKTOP user viewing a host owned by a remote Orca server, not just web
clients.
2026-08-14 04:01:42 -07:00
Neil efcb407c89 docs(ssh): record what review changed and the STA-4319 follow-ups
The design survived implementation; every defect found afterwards was in the
wiring. Worth recording the pattern, because it repeated five times: each one
made us either blind or unusable, never subtly wrong — and four of the five
broke legitimate hosts rather than admitting bad ones.

Action items separate the things Phase 2 must decide (UpdateHostKeys, which is
now the likeliest way a legitimate user meets a rejection; the web client never
seeing the reason; RPC fail-fast) from the gaps Phase 1 knowingly accepts (WSL,
CheckHostIP, ca-only hosts, the hand-copied ssh2 algorithm list).

Also flags the rollout risk plainly: this is the first release in which Orca can
refuse an SSH connection at all.
2026-08-14 03:39:56 -07:00
Neil 0f37005de0 fix(ssh): bind the host key store to the active profile at startup
Without this the store reports nothing trusted on every launch. Safe — known_hosts
still decides, and a host trusted only by us degrades to first contact and is
re-recorded — but it silently discarded our own accept records, so the store the
design calls for was not actually in use.

Bound beside the profile Store, since it is a sidecar of the same data file.

Also records why the paired-web carve-out the migration review asked for is NOT
implemented in Phase 1, rather than leaving it looking forgotten. That carve-out
exists to stop a web client waiting out the 120s prompt timeout — a hang only
reachable if a prompt exists, and Phase 1 has none, which the decision function
pins with a test asserting it never returns 'prompt'. An RPC connect therefore
behaves exactly like a local one. Adding a fail-fast path now would introduce a
failure mode for a hang that cannot occur; it becomes load-bearing when the
dialog lands and is listed under Phase 2.

Noted there for whoever builds Phase 2: runtime/rpc/methods/ssh.ts already
swallows the specific error and rethrows a generic one, so the host-key reason
will not reach a web user without a change there too.

Full unit suite: 52,352 pass. The 8 failures are the known environment baseline
(5 osc8, 2 IME) plus one browser-cookie suite-ordering flake that passes in
isolation — none in src/main/ssh, and none related to this change.
2026-08-14 03:10:23 -07:00
Neil 8be1696629 docs(ssh): revise the host key design after security and migration review
Three things the reviews changed, kept visible rather than quietly edited out.

THREAT MODEL WAS WRONG IN THREE PLACES. Jump hosts are not the worst case — they
are already safe: shouldUseSystemSshTransport branches on exactly the inputs
resolveEffectiveProxy does, and attemptConnect returns after the system probe, so
ProxyJump goes through OpenSSH and is verified. Agent forwarding was overstated
(gated on the user's ForwardAgent). Credential theft was understated: any auth
error counts as agent fallback, so a MITM walks the user to the password AND
private-key passphrase prompts, and cachedPassword replays without prompting. The
relay claim was backwards — the attacker owns their own machine; the real impact
is the return direction, where they become the host our workspace trusts.

TYPE SCOPING IS A DOWNGRADE VECTOR WITHOUT ALGORITHM ORDERING. This was the
decision I flagged as least certain and asked to have argued both ways. OpenSSH
is safe only because order_hostkeyalgs() puts known types first and RFC 4253
gives the client's order priority. ssh2 negotiates ed25519 first regardless, so
an attacker who cannot forge the RSA key on file just presents ed25519 and gets a
friendly first-contact prompt instead of a hard failure. Keep scoping, but set
algorithms.serverHostKey to lead with the types on file — and add a sixth
outcome for 'unknown type, known host', which must never read as first contact.

SHIP THE DEFENCE BEFORE THE DIALOG. Startup restore fires eager connects for all
targets in parallel with a 15s timeout while a prompt would live 120s; ephemeral
VM targets present a new key every launch; paired-web connects run on the host
desktop, so the dialog opens on someone else's screen. Phase 1 is therefore no
modal at all: consult known_hosts and our store, match connects, unknown persists
with accept-new semantics, mismatch and revoked hard-fail. That is the whole MITM
defence with none of the migration risk.

Also folded in, verified live against OpenSSH 10.2p1: the without-port fallback
(bracketed lookup first, then bare, where the second pass can only yield match or
unknown — otherwise a bare line plus a non-default port produces a spurious
prompt); hashed entries hash the candidate form; multiple files union; a
cert-authority line does not match a plain key. IPv6 and bracket parsing moved
INTO scope — that is a parser requirement, not a scope call, and getting it wrong
produces the prompt-training harm the design exists to avoid.
2026-08-14 02:39:33 -07:00
Neil 2a99a95b9c docs(ssh): design for real host key verification (STA-4319)
Today's ssh2 verifier records a fingerprint and returns true — every host key is
accepted, with no known_hosts consult and no change detection anywhere in
src/main/ssh/. Scope is per-connection, so exec, SFTP, port forwarding, the
watcher and relay deploy all ride that one unverified handshake, and the
ProxyJump path puts the final hop — the topology most likely to cross untrusted
network — on ssh2 specifically.

Decisions worth calling out:

- Read the user's known_hosts as a trust source but NEVER write to it. That file
  is shared with every other SSH tool on the machine; appending means line
  endings, permissions, concurrent writers and a corruption blast radius well
  beyond us. Accepted keys go to our own per-target store. Reading theirs is also
  the entire migration story: most developers already have their hosts there.
- Mismatch is scoped to the SAME key type. A host with only an RSA entry that
  presents ed25519 is unknown, not changed. ssh2 negotiates ed25519 first, so
  without this we would fire a change-of-key alarm at nearly every existing user
  on their first upgraded connect — training them to dismiss the one warning that
  is supposed to mean something. Flagged in review as the decision I am least
  sure of; a downgrade-vector argument against it is being tested.
- Changed key hard-fails with no override button; recovery is a separate explicit
  action, offered only when OUR store is what disagreed, because forgetting our
  record cannot unblock a known_hosts conflict.
- Background reconnects deny rather than prompt. A dialog the user cannot place
  in context only teaches click-through.

Two traps are documented because either would make the fix silently do nothing:
an async verifier returns a Promise, which ssh2 reads as truthy and accepts
immediately; and the existing test mock invokes hostVerifier with one argument
and ignores the return, so it would pass against a verifier that never decides.

Design only — no behaviour change. The doc is added to the tracked-reference
allowlist in .gitignore alongside the other docs/reference entries.
2026-08-14 02:35:56 -07:00
github-actions[bot] f4e4b5aded Update README downloads badge 2026-08-14 06:46:22 +00:00
Neil eb22e497bb Revert "fix(ssh): reapply the reattach-identity work and stop the fallback fence stranding moved panes" (#14395) 2026-08-13 18:11:33 -07:00
Neil 6a0c8fa541 fix(ssh): reapply the reattach-identity work and stop the fallback fence stranding moved panes (#14384)
* Reapply #13326 and #13928 (un-revert #14361)

Restores the SSH reattach-identity and daemon-occupancy fixes. Reverting them
reintroduced their P0s, filed as STA-4224, STA-4225, STA-4227, STA-4230,
STA-4232, STA-4233 and STA-4234 against #14361.

The tab loss that motivated the revert is fixed in the commits that follow, so
this reapplication is not a straight redo.

* fix(relay): stop the fallback attach fence refusing a pane that moved tabs

The primary fence was moved to the shell's own incarnation precisely because
paneKey/tabId froze the pane's LOCATION at spawn and refused panes that had
merely moved. The fallback that older clients fall into kept the old rule, so
the correction never reached it — the same 'the rule exists, but this path does
not ask it' leak this work has hit repeatedly.

A refusal here is not recoverable: an identity mismatch never grounds a respawn,
so the pane keeps a live shell it can no longer reach and renders blank.

Narrowed to paneKey, which is the identity; the tab is a location. Restoring the
tabId comparison reddens the new test.
2026-08-13 16:45:24 -07:00
Jinwoo Hong ff8dda81e8 fix(serve): exit cleanly after headless Linux signals (#14334)
* fix(serve): keep owned Xvfb alive through Electron teardown

* test(serve): gate packaged signal shutdown

* test: harden headless shutdown lifecycle gate

* fix(serve): isolate Xvfb from foreground signals

* docs(serve): preserve Xvfb during systemd stop

* test(serve): pin shutdown policy to owned Xvfb unit

* test(serve): harden shutdown gate portability

* test(serve): bound systemd unit parsing
2026-08-13 15:45:00 -07:00
Neil 11cd2b4310 revert(ssh): back out #13326 and #13928 — reconnect loses every tab (#14361)
* Revert "fix(daemon): stop killing live coding agents when the daemon can't report its sessions (#13928)"

This reverts commit 2e8cf589de.

Reverted together with #13326: the 1.4.182-daily.202608131439 build carrying
both loses every tab on an SSH disconnect/reconnect cycle. Reverting first so
main stays releasable and the P0 fixes in the wild remain cherry-pickable,
rather than fixing forward on a shipped regression.

* Revert "fix(ssh): stop SSH reconnect from multiplying terminals and resuming agents twice (STA-3077)" (#13326)

This reverts commit 3ab8b6a117.

Reported on 1.4.182-daily.202608131439: connect to an SSH worktree, disconnect
the host from the hosts popup, reconnect — every tab is gone. That is worse than
the behaviour this PR set out to fix, where most tabs were retained.

Reverting rather than fixing forward, so main stays releasable and the P0 fixes
already out in the wild stay cherry-pickable. STA-3077 stays open.
2026-08-13 14:54:29 -07:00
NeilandOrca 3ab8b6a117 fix(ssh): stop SSH reconnect from multiplying terminals and resuming agents twice (STA-3077) (#13326)
* fix(ssh): stop reconnect from grafting panes and stacking remote leases

Reconnecting an SSH-backed workspace added terminal panes the user never
opened, and the remote host accumulated shells nobody was using — one
report went from 2 to 19 to 20 relay PTYs across three reconnects
(STA-3077).

Two root causes, both in the store.

Reattach could create UI. `persistPtyBinding` has four creating branches
— mint a tab, mint a root leaf, split the root and graft a leaf, mint a
layout. All four are load-bearing for `pty:spawn`, which can beat the
renderer's debounced layout writer, but none of them is appropriate on
reattach, where the pane either already exists or is gone for good. Add
`mayCreate`, defaulting true so the spawn path is untouched; every
creating branch already sets `terminalMembershipChanged`, so refusing is
a check rather than a new code path.

Lease identity had no pane key. `upsertSshRemotePtyLease` matched on
`(targetId, ptyId)` alone, so a pane that re-leased under a new relay id
left its predecessor live with nothing to retire it, and the next
reattach fanned out over both. One pane now keeps at most one live
lease. Superseded leases are marked `expired` rather than terminated:
losing a lease is not proof the shell died, so the remote process is
deliberately left running.

Tests assert observable behavior rather than mechanism, so they stay
valid under any implementation that fixes this.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): record the terminal session behavior contract

Properties stated as observable behavior rather than mechanism, so an
oracle written against them survives a change of implementation.

Records the weaker, correct form of the timer rule — a timer may never
be the sole cause of a destructive action — because recovery budgets and
scratch-file age gates are correct code that an absolute ban would
condemn. Also notes which mechanisms are deliberately not required, so
each has to earn its place rather than arrive with an architecture.

Co-authored-by: Orca <help@stably.ai>

* fix(ssh): heal duplicate pane leases that predate pane-keyed supersession

Pane-keyed supersession stops new duplicates, but it does nothing for
installs that already carry the ones STA-3077 accumulated — the report
behind this reached 20 live leases across a handful of panes, and every
reconnect fanned out over all of them.

Retire the stale duplicates once per reattach pass, keeping the newest
lease for each pane under a total order so two hosts resolve a tie the
same way. As with supersession, retired leases are marked `expired`
rather than terminated: their remote shells are deliberately left
running, because a lease we chose not to revive is not evidence the
shell died.

The relay-session store stubs gain the new method. Note the gap this
leaves open: those shells keep running and are no longer reachable from
the app, so the "accumulates unused shells" half of the report needs a
visible recovery surface rather than a silent kill.

Co-authored-by: Orca <help@stably.ai>

* fix(terminal): stop respawning a shell that is still running

A pane that failed to reattach spawned a fresh shell. Because the
restored session id came along, the replacement resumed the same agent
session, and two processes appended to one transcript — reported
repeatedly, up to five concurrent resumes of a single session.

Two defects fed it.

The relay reported a source that merely needed re-establishing as
`SSH_SESSION_EXPIRED`. The shell was still running; only its output
source was gone. Give that outcome its own error so it stops reading as
"the session no longer exists".

The reattach failure handler then treated every error as proof of death.
It checked for expiry and, in the else branch, took the identical
action — so the check bought nothing and a transport fault, a timed-out
call, or a wedged relay all respawned. Respawn now requires proof: an
explicit host expiry or a not-found PTY. Anything else, including an
error we have never seen before, is unresolved, leaves the shell
running, and keeps the binding for a later reattach.

Two existing tests asserted the old behavior. One threw a bare error as
scaffolding to reach the spawn-adoption door; it now throws proof, which
is what it meant. The other pinned the expiry mapping itself, and now
asserts the outcome fails closed *without* being reported as expiry.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): record what makes a retention bound safe

Shortening a grace period is the wrong lever. Measuring process time and
gating reclamation on an independent observation are what make one safe,
and they are what deployed systems actually do.

Also records that lifecycle belongs in the attach reply rather than a
delivered event — that is what removes the need for a durable per-consumer
cursor to guarantee an exit is never lost.

Co-authored-by: Orca <help@stably.ai>

* test(terminal): assert the empty-failure case without an empty Error

A thrown empty value exercises the same property — a failure carrying no
usable message is not proof the session is gone — and does not trip the
empty-error-message lint.

Co-authored-by: Orca <help@stably.ai>

* fix(ssh): let the durable pane binding outrank recency when retiring leases

Choosing the newest lease for a pane is wrong whenever a newer lease
exists that no pane is bound to: it retires the lease the pane is
actually attached to, detaching a live terminal instead of healing it.

Two changes. Arbitration now prefers the lease matching the pane's
durable binding, across both the SSH-target and local partitions,
falling back to recency only when no binding names either candidate.

And supersession at upsert time now defers rather than expiring a bound
predecessor. When a lease arrives for a pane that is still bound to a
different PTY, the binding has not caught up yet, so both stay live and
reattach arbitrates once the binding is available.

Co-authored-by: Orca <help@stably.ai>

* fix(ssh): roll back a lease retirement whose durable write fails

`flush()` logs and swallows write errors, so a failed write left these
leases retired in memory while disk still called them attached — and the
pane bindings scrubbed alongside them stayed scrubbed. Use `flushOrThrow`
and restore both the lease states and the affected session partitions
when it throws, reporting nothing retired.

Co-authored-by: Orca <help@stably.ai>

* test(ssh): prove pane and remote PTY cardinality across reconnects

Counts the shells the relay actually hosts, on the container, rather
than inferring them from app state — that is the census the report was
based on. Asserts the PIDs are unchanged, not merely the count, so a
kill-and-respawn cannot pass.

Every pane streams before the transport is severed: an idle pane sends
no recovery checkpoint, so only a live source comes back needing
re-establishment, which is the outcome that used to read as expiry.

Co-authored-by: Orca <help@stably.ai>

* fix(ssh): actually pass mayCreate:false from the reattach binding write

The `mayCreate` guard was correct and had no production caller, so the
reattach path still went through the creating branches and grafted panes
back. `restoreReattachedPtyRuntime` is that call site — RC3 in the
original diagnosis — and it now refuses to create.

Binding moves ahead of runtime registration, because registering first
would surface a pane the user never opened before the refusal landed. A
refusal leaves the remote shell running and reattachable; a *thrown*
write stays unknown and still registers, so a failed disk write cannot
detach a live pane.

Adds an oracle over the call site itself. The store-level tests all
passed while the fix was inert, because they called the store directly —
only pinning the wiring catches that.

Co-authored-by: Orca <help@stably.ai>

* fix(terminal): apply the respawn-requires-proof rule to both reattach paths

connectPanePty has two near-verbatim reattach blocks — one keyed on the
deferred SSH session, one on the restored session — and only the second
was fixed. The first still checked for expiry and then respawned
unconditionally anyway, so a transport fault there resumed the same agent
session a second time.

Also keep the wire token out of the pane. The main-process bridge only
special-cases expiry, so a source-restore failure crossed IPC as raw
`SSH_SOURCE_RESTORE_REQUIRED: <id>` text and surfaced to the user. It
correctly does not respawn; it just should not read like that.

Co-authored-by: Orca <help@stably.ai>

* test(ssh): state plainly that the reconnect spec is a forward guard

It was run against an unfixed tree and passed, so it does not prove the
STA-3077 fixes and should not be read as if it does. A clean severed
transport does not reproduce the field conditions — accumulated duplicate
leases, or a source returning needing re-establishment.

It keeps its place as a forward guard: it counts the shells the relay
actually hosts and pins their PIDs, so a later change that grafts a pane
or respawns a shell fails here.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): record that a guard must be pinned at its call site

A refusal that exists and is never passed is indistinguishable from no
refusal, and store-level tests cannot tell the difference — they call the
store directly. Learned from `mayCreate`, which was correct and had no
production caller for several commits.

Co-authored-by: Orca <help@stably.ai>

* fix(ssh): park one PTY's exhausted delivery recovery instead of dropping the channel

A per-PTY recovery budget running out disposed the whole relay channel,
so one PTY that could not re-prove its delivery aborted every in-flight
filesystem and git request on that host and stalled every sibling pane.
A retry count is not proof of anything, and it certainly is not proof
about the other sessions sharing the channel.

Exhaustion now parks that PTY's delivery. The remote shell keeps
running, its lease stands, and the next relay open reattaches it with a
fresh delivery generation — the parked state is cleared on teardown and
the generation changes on reconnect, so a reconnect recovers it.

The consecutive-attempt ceiling goes away entirely; the per-generation
one is what bounds the retry cost, and the second ceiling only existed
to reach the channel drop sooner.

Tradeoff worth stating: the failing pane used to self-heal within
seconds because the forced reconnect wiped all rejection state, and it
now stays frozen until the next relay open. That is a worse outcome for
that one pane and a much better one for every other session on the host,
and reconnecting is user-reachable.

Co-authored-by: Orca <help@stably.ai>

* fix(pty): let liveness say unknown instead of forcing it to say dead

`IPtyProvider.hasPty` returned a boolean, so a provider whose inventory
was empty for reasons that have nothing to do with the session — socket
down, cache never hydrated, provider generation just constructed — had no
way to say so and answered "absent". Its own siblings already knew
better: `probePtyLiveness` and the runtime's `PtyController.hasPty` were
both already `boolean | null`, with consumers branching on null
correctly. The lie was injected at exactly one interface.

Now three-valued, and each provider answers unknown where it cannot
prove absence: the daemon adapter off-socket, the SSH provider before a
completed listing, the router when any adapter cannot answer, and the
degraded provider rather than fabricating a verdict. `terminal_gone`
requires unanimous proven absence.

Also fixes a real cold-start bug this surfaced: `pty:hasPty` never
awaited the daemon-swap startup promise, though the sibling
`probePtyLiveness` bridge already did, so before the swap the local
provider answered an authoritative false for every daemon-owned id.

Net +27 production lines. The plan behind this predicted -92 on the
strength of deleting the renderer's dead-session reconcile path; that
code is live (`pty-connection.ts` imports it), so nothing was deleted.
Expressing a third value where there were two costs lines, and a
deletion that is not real is not worth manufacturing.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): track the terminal-session correctness handoff package

The package was untracked under a gitignored `docs/**`, with the
un-ignore rules living only in an uncommitted .gitignore edit — a single
`git clean -xdf` would have destroyed the authoritative plan.

The 814-path construction snapshot is now pushed as
`nwparker/react185-authority-snapshot` too; it had no remote ref.

Co-authored-by: Orca <help@stably.ai>

* test(ssh): make the reconnect settle window actually wait

The settle poll reused a matcher the assertion 15 lines above had already
satisfied, and Playwright's poll engine probes immediately and returns as
soon as the matcher passes — so it observed the same state twice and
elapsed 0ms. A shell grafted a second or two after reattach reported
ready slipped through into the next cycle.

Reviewer was right on #13111. Test-only; no production change.

Co-authored-by: Orca <help@stably.ai>

* test(ssh): census both durable session partitions on reconnect

Adds a second reconnect scenario and a helper that reads pane records
from the local partition as well as the ssh host partition. That split
matters: the reattach binding call passes no hostId, so a grafted pane
lands in the LOCAL partition and an oracle reading only the host
partition passes whether or not the guard is present.

Both tests remain forward guards. The second one was reported as
discriminating and did not reproduce: with `mayCreate: false` removed
from the call site and the app rebuilt, both still passed. Its induction
races `pty:kill` against a severed transport, so when the kill lands the
lease is cleaned up and there is nothing left to graft. The handoff
README is corrected to say so rather than claim a journey.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): record the user decision relaxing G6

G6 becomes minimise-and-justify rather than strictly net-negative. The
deletion budget the plan assumed does not exist: an entrypoint-rooted
import graph found 51 of 53 candidate files reachable and instantiated
on live paths, leaving 263 deletable LOC against roughly +1,021 to
offset. Correctness may still not be traded for line count.

Co-authored-by: Orca <help@stably.ai>

* test(terminal): add discriminating oracles for restart, daemon, skew and namespaces

Six parallel streams, each required to fail with its guard removed rather
than merely pass.

Local restart proves the OS process itself survives, by reading
`ps -o lstart=` for the shell's own pid. That matters: with the quit path
made destructive, the tab, leaf and pty ids all came back byte-identical
while the shell underneath was a new process — every existing restart
spec would have stayed green. Two separate guards were removed to redden
it, and the second reddens only the stale-operation case.

Daemon restart discriminates by reverting three-valued `hasPty`; version
skew now covers publication semantics and confirms the new
`SSH_SOURCE_RESTORE_REQUIRED` token mutates nothing on an old client;
two-host isolation censuses both containers.

Deletes `src/relay/pty-source-replay-index.ts` — 201 production lines
with no importer outside its own test, verified against an
entrypoint-rooted import graph rather than a name grep.

Five namespace tests are skipped, not passing: they reproduce a defect
still live on main where folder-workspace ids compare equal with the
instance suffix stripped. PR #12474 fixes it; they are its oracle.

Co-authored-by: Orca <help@stably.ai>

* test(ssh): induce the reattach graft deterministically instead of racing a kill

The previous induction closed a pane while the transport was severed and
relied on `pty:kill` FAILING so the lease outlived the pane record. It
does not fail: with the provider already torn down, `pty:kill` takes its
tombstone branch and marks the lease terminated, and `reattachKnownPtys`
filters terminated leases out of the fan-out — so the reconnect never
visited the PTY the test was about. It passed on both trees.

Seed the precondition instead. Spawn a real remote PTY on a leaf that
never becomes a pane, then roll the host partition back to its pre-spawn
snapshot, leaving a live lease and a live remote shell that no durable
pane owns. No failure races a success.

Adds a vacuity guard that is independent of the tree under test: the
lease's own `lastAttachedAt` must advance, proving the fan-out actually
visited this lease before the pane census is trusted.

Verified on this machine under an isolated TMPDIR, since the e2e
harness keys its seeded-repo pointer on a machine-global tmpdir path:
guard present passes, guard removed fails with the phantom leaf grafted
into the local partition, guard restored passes.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): propose one authoritative binding identity

Every defect this program has touched is the same defect: identity
compared with the wrong key, or not compared at all. Lease keyed without
the pane, reattach using a creating write, folder-workspace ids compared
with the instance suffix stripped, local mutating IPC carrying only an
id, a live shell classified as expired, liveness unable to say unknown.

Proposal: one branded binding type built from fields that already exist
and are already persisted, constructible only from an authoritative
source, carried by mutating operations, compared by one shared function.
Makes a wrong-key comparison a type error rather than the next incident.

Under adversarial review, including against the open issue corpus.
Not accepted.

Co-authored-by: Orca <help@stably.ai>

* fix(pty): refuse mutating operations aimed at a superseded PTY

`pty:write`, `pty:writeAccepted` and `pty:resize` accepted any id. The
renderer queues input, so a keystroke buffered before a reattach landed
on whatever PTY had since taken the pane — and a resize reshaped the
successor's shell.

Main already tracks `ptyPaneKey` and `paneKeyPtyId` in lock-step, so
their disagreement is proof the caller's id was superseded. No wire
change, no renderer change, nothing added to the input payload.

An id with no recorded pane stays permitted: unowned and orphaned PTYs
are unknown, not stale, and unknown never authorizes refusing an explicit
operation. That is also what keeps orphan cleanup working — those ids
have no pane by construction.

The tests pin the CALL SITES, not the predicate. A capability that exists
and is never called is indistinguishable from no capability, which is
exactly how `mayCreate` sat inert here for several commits with every
test green.

Co-authored-by: Orca <help@stably.ai>

* fix(pty): fence signals at a superseded PTY, and pin why kill is exempt

A signal means "interrupt my pane", so delivering one to a PTY the pane
has already replaced is a misdirected interrupt. Fence it with the same
lock-step proof used for write and resize.

`pty:kill` stays deliberately unfenced and a test now pins that: a
superseded PTY is orphaned, and reclaiming it is exactly what the
orphan-cleanup callers ask for. Refusing there would break the operation
that reclaims leaked shells — the opposite of the intent.

The fence sits at the IPC boundary, above `tryGetProviderForPty`, so it
covers local, daemon and SSH rather than the local path alone.

Co-authored-by: Orca <help@stably.ai>

* test(terminal): poll the pane binding read so a slower host cannot flake it

`readPaneBinding` took a single unpolled read of a DOM dataset attribute
immediately after a renderer reload, while its sibling helper polls the
same data for 15s. On a native Linux host both tests failed every run
with 'No bound terminal pane is mounted' while the app was demonstrably
healthy — the screenshot showed the terminal restored with a live prompt
and the boot PID echoed.

The assertion is unchanged; it is only awaited. Nothing is weakened.

Found by running this spec on native Linux rather than assuming macOS
behaviour generalises.

Co-authored-by: Orca <help@stably.ai>

* test(terminal): make the restart identity spec run on Windows too

Both probes were POSIX-only and unconditional: `echo ...=\$\$` for the
shell's own pid, and `ps -o lstart=` for its start time. Running the spec
on a real Windows host proved it dies before reaching either guard, so
Journey 1's Windows half was unprovable rather than merely unproven.

PowerShell exposes the same two facts as `$PID` and `Get-Process`
StartTime. The start time still matters on both platforms for the same
reason: a PID alone cannot separate a survivor from a reused number.

Still green on macOS. The Windows path is written from the host probe and
has not itself been executed end to end — that is the next thing to run
there, not a claim being made here.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): record the fence's real gap and what peer designs taught

Marks the client-constructed binding proposal as rejected with the three
false claims that sank it, and records what shipped instead.

States the shipped fence's actual limitation rather than leaving it
implied: it compares a binding, not an incarnation, so a respawn under a
reused ptyId passes. The obvious remedy is wrong here — the agent-create
id is deterministic by design so a replayed create stays idempotent, and
randomising it would trade this narrow gap for a duplicate-spawn bug.

Also records the ranked lessons from four comparable agent IDEs, chiefly
that a typed end-reason at end time is what stops a user quit from
looking like a resume candidate.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): promote Journey 1 to proven on all three platforms

The oracle now runs natively on macOS, Linux and Windows, and its
discrimination was watched on each: a mutation reddens it, a restore
greens it. On Linux and Windows both mutations were run, and the second
reddens only the stale-operation test — so the journey's two clauses are
proved independently rather than jointly.

Windows is the new evidence. The PowerShell branches added blind at
ebffb85a848 executed correctly on their first run: `$PID` expanded to
real integers, which also proves the pane shell there is PowerShell-family
rather than Git Bash, and `Get-Process StartTime` returned kernel start
times 5.4s apart — so a recycled pid could not have passed as a survivor.

First journey promoted in this program. The other twelve are unchanged,
and the residual limit on "every stale exact operation" is recorded
rather than glossed.

Co-authored-by: Orca <help@stably.ai>

* test(terminal): add discriminating oracles for the daemon, skew and multi-host journeys

Daemon: replaces a spec that modelled only a client restart and never
crossed the daemon boundary, whose successor generation owned nothing so
"the live successor is neither killed nor replaced" was vacuous. The PTY
leader is now a real login shell reporting `$$` back through the
production write path, resolved to a kernel start time. Two mutations
each redden exactly one of the three clauses, on macOS and Linux:
reverting three-valued `hasPty` reddens only the unknown-not-dead
clause; widening the sole-provider fallback reddens only the stale
generation clause.

Skew: reverting the restore-required publication to expiry reddens 4 of
5 new tests while the legacy control stays green — the regression this
branch fixed is now caught if reintroduced.

Multi-host: restoring `mux.dispose('connection_lost')` reddens sibling
isolation on one host. It does NOT redden across hosts, and that is
recorded rather than glossed: a mux belongs to one relay session per
target, so its dispose cannot cross a host boundary. Journey 4's
cross-host clause rests on isolation-by-construction, not on a mutation.

No production code changes.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): record journey evidence that falls short of promotion

Four journeys now have discriminating oracles but none meets its full
stated scope, and each shortfall is named rather than rounded up.

Journey 2 is one WSL run from promotion. Journey 12's tests are
in-process, so they do not close the live-skew gap the original ledger
named. Journey 4's cross-host clause cannot be proven by mutation at all
— a mux is per target, so its dispose cannot cross hosts, and the
cross-host test stayed green under the mutation that reddens siblings.
Journey 13 measured one dimension of ten, on lifted predicates rather
than through real IPC.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): promote Journey 2 to proven on macOS, Linux and physical WSL

The oracle runs on every environment the journey names, and is
clause-selective on all three: reverting three-valued `hasPty` reddens
only the unknown-not-dead clause, and widening the sole-provider fallback
reddens only the stale-generation clause.

Selectivity in WSL was established rather than assumed. The spec runs
serially, so a red first test reports the others as "did not run" — they
were re-run alone under the same mutation and stayed green.

Also records that an Orca WSL-mode terminal now starts on that host at
all, which it could not before: the distro had no provisioned default
Unix user, so every interactive launch blocked on first-run setup.

One diagnosis from the WSL run is corrected here rather than repeated:
the unrelated `local-pty-shell-ready` failure was attributed to bash
5.3.9, but macOS runs the same bash version and passes 67/67. The trigger
is environmental to that distro, and the underlying defect is that the
spec pins an absolute count of OSC markers it does not own.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): correct the WSL provider-suite diagnosis

The WSL run blamed bash 5.3.9 for the unrelated
`local-pty-shell-ready` failure. macOS runs the same bash version and
passes 67/67, so the version is not the cause — the trigger is
environmental to that distro, and the underlying defect is that the spec
asserts an absolute count of OSC markers it does not own.

Co-authored-by: Orca <help@stably.ai>

* test(runtime): unskip the workspace-namespace oracles now their fix has merged

These five reproduced a defect that was live on main: folder-workspace
ids were compared with the instance suffix stripped, so two workspaces
sharing a directory read as the same namespace. They were committed
skipped, pointing at the PR that fixes it.

That PR is merged, and they pass. Verified they still bite: restoring the
suffix-stripping comparison reddens exactly these five and leaves the
other four green.

An oracle written before its fix, held skipped, and confirmed against the
fix after the merge — rather than deleted and rewritten from the answer.

Co-authored-by: Orca <help@stably.ai>

* test(ssh): add MaxSessions, lazy-discovery and paired-skew oracles

Three journeys attempted; none promoted, and the reasons are recorded in
the ledger rather than rounded up.

MaxSessions=1 against real OpenSSH, with the cap read back from `sshd -T`
rather than assumed, and remote pids read on the container two
independent ways that must agree, each carrying its kernel start time.
Two disjoint mutations discriminate — one reddens only the reconnect
clause, the other only the two restart clauses. But the disconnect clause
is a forward guard: four separate guard removals left it green, so
nothing shipped is load-bearing for it.

Lazy discovery samples sshd's own accept log and live session census
across a 22s window with the in-use host as a positive control. No
mutation reddens its third clause alone — the real cross-host lease
scoping is load-bearing, but removing it breaks the sibling host during
setup, so the failure carries no clause information.

The paired-runtime skew spec pairs two real processes at different
versions and refuses to run rather than degrade into a same-version
pairing that would look green and prove nothing.

No production code changes.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): record why the duplicate-resume fix was not built

I recommended adding a typed end-reason so a user quit stops looking like
a resume candidate, then went to implement it and stopped.

`SleepingAgentSessionRecord` already carries three fields that each exist
to stop something resuming that should not have — `origin`,
`restoreOnTabOpenOnly`, and `automaticResumeBlockedBy` — each traceable
to its own incident, consulted at 22 non-test sites. A fourth predicate,
however well typed, is the fifth containment cycle.

The designs without this bug do not have a better flag; they resume only
on an explicit action, into a new terminal id, and make two agents in one
terminal unrepresentable in the schema. The first of those is a product
decision about whether automatic resume stays a feature, so it is the
user's call rather than mine.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): reconcile G6 with the recorded decision and assess its clauses

G6's body still demanded strictly-negative production LOC after the user
relaxed it to minimise-and-justify, so the gate had two conflicting pass
conditions and no single truth value. Its body now points at that
decision.

Assessed the remaining clauses against the branch rather than assuming.
Two fail structurally: more than one identity comparison and mutation
admission path still exist, and `terminal-input-quarantine.ts` is still
reachable from two production files.

Records why the quarantine is not subsumed by the superseded-PTY fence,
which I had assumed and checked. The fence refuses writes aimed at a
stale ptyId; the quarantine guards the user's next keystrokes landing on
the successor under its current, correct id — a case the fence never
sees. Removing it needs the recovery path to surface a different shell as
unresolved, not a deletion.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): the input quarantine is load-bearing, not superseded

G6 lists "no superseded quarantine remains reachable" and this module was
assumed to be one. Disabling its single call site reproduces the hazard
it exists for — `cho hi; rm -rf x` reaching the shell — so deleting it
without a replacement re-opens command execution.

The replacement was costed by building it rather than estimated: +26
production LOC to thread the incarnation, ~+33 complete, and the
cross-remount state it needs outlives the destroyed pane so it becomes a
module about the size of the one deleted. Floor is roughly +140 to delete
88, and it would add a second identity comparison to a gate already
failing for having more than one.

The decisive part is that the route is not uniformly available: remote
runtime results carry no incarnation, old hosts cannot be made to publish
one, and mixed versions are the normal state. A paired client reads
unknown, which this program's own rule says is not proof — so either
every remote reattach surfaces unresolved, or a fallback is needed and
the only correct fallback is this module.

Whether to amend the clause or accept something weaker on remote hosts is
a user decision, so the clause verdict is left as failing rather than
quietly reclassified.

Co-authored-by: Orca <help@stably.ai>

* refactor(runtime): collapse duplicate identity comparisons

G6 requires one identity comparison; five implementations existed across
two concepts.

Worktree-namespace identity had two: `runtimeWorktreeIdsEqual` and
`runtimeWorktreeIdentityKey` independently re-derived repoId plus
normalized path. Equality now derives from the key, so the comparison and
the sleep / mutation-queue keying cannot drift into two different rules —
which is exactly how the suffix-stripping bug reached production once.

Pane identity had three byte-identical leaf-UUID comparisons, in
orchestration `db.ts`, `lifecycle-reconciliation.ts`, and
`orchestration-legacy-process-identity.ts`. One copy moved to
`stable-pane-id.ts`, which already owns `PaneKey`, `parsePaneKey` and
`makePaneKey` and which all three already imported. No new module, no
branded type, no parallel comparison.

Net -14 production lines. The namespace oracle still bites: restoring the
filesystem parser inside the identity key reddens exactly its five cases.

The raw counts are not the actionable set, and the classification is
worth recording: of 409 non-test `worktreeId` comparisons, 71 are typeof
guards and 81 are sentinel tag checks. Most of the remainder are renderer
predicates over store rows where both operands are the same main-minted
id, so normalizing there would widen equality rather than correct it.

Co-authored-by: Orca <help@stably.ai>

* refactor(terminal): finish a half-done fixture move and audit the rest

`xterm-bypass-event-fixture.ts` and `__fixtures__/xterm-bypass-event.ts`
were byte-identical apart from an import path. The `__fixtures__` copy had
zero importers and the live copy compiled as production — someone started
the move and left both. Dead copy deleted, live one moved, its three test
importers updated.

Audited the wider G6 clause by importer rather than filename: 32 test-only
files, roughly 3,300 LOC, currently compile as production; 4 of the 36
candidates have real production importers and are correctly placed. The
list is recorded in the goalposts.

Those 32 are almost all older than this program and outside the terminal
surface, so sweeping them belongs in its own change rather than inside a
terminal PR. The clause stays failing, with the remaining files named.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): the fixture clause already holds where it matters

Checked what the build emits rather than reasoning from file paths. None
of the 32 test-only fixtures appears in `out/` — Rollup drops them because
no production entrypoint reaches them. On "compiles into the shipped
product", this clause holds today.

On the other reading it cannot be closed by moving files at all: both
production tsconfigs use bare `include` globs with no `exclude`, so a
`__tests__/` directory matches exactly like any other path, as does every
`*.test.ts` in the repo. Relocating 32 fixtures would remove nothing from
typecheck scope.

A sweep was started and stopped once this was verified, rather than
landing 32 moves across areas this program does not own for no gain. If
the intent is that typecheck scope should exclude test code, that is a
repo-wide tsconfig change with a different owner.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): add plain-language design and test overviews

Two reviewable documents with diagrams, written so someone with no prior
context can follow what breaks, why, and what changed.

The design overview explains the five things stacked behind one terminal
rectangle, the 2 -> 19 -> 20 report, the three root causes, and the rule
underneath all of them: unknown is not dead.

The test overview explains why a green test proves nothing on its own,
the four-step mutation proof we adopted, and — the part worth reviewing
hardest — an honest account of what could not be proven and why, including
the properties that are true by construction and therefore have no guard
to remove.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): add a self-contained visual report of the design and its evidence

Pre-renders every diagram to inline SVG in both themes so the report opens
offline and stays sharp when zoomed. States the gate/journey score and the
retractions alongside the fixes, so the unproven half is as visible as the
proven half.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): record the finalized two-plane architecture decision

Adopts the data-plane proposal and adds the control-plane track it does not
cover: re-key ownership by pane, split orphan inventory out, then delete the
compensating code. Records that the host-authority alternative was refuted and
that the shipped keystroke fence is inert on the reattach path.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): add the design brief the review counsel works from

Separates verified code facts from unverified leads so reviewers attack the
design rather than a reconstruction of it, and records which simpler
alternatives were already refuted and why.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): report the design counsel's outcome and the live respawn bug it found

Three review rounds across two models replaced the two-record split with one
leaf-keyed record, deleted attach-time pane identity, and made orphans a
connect-time projection. Records that a shipped gesture still turns a healthy
remote shell into a duplicate agent resume, and that the renderer classifier in
that chain treats an error-message shape as proof of death.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): correct the report — the respawn proof gate guards a minority path

A final review traced every auto-respawn route. The primary one converts the
reattach failure into a boolean before any classifier sees it, so the shipped
proof gate never runs there. Records that two of the six shipped changes are
narrower than claimed, and why their tests could not have caught it.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): explain the landed design on its own terms

One leaf-keyed ownership record, orphans computed at connect, and replacement
shells only on positive proof — with the shipping order and the one product
trade the design asks the owner to accept.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): rewrite the design explainer in plain English

The first version assumed the reader knew the codebase. Reframed around two
bugs, two fixes and one decision, with the jargon replaced by pane / program /
note / helper and a five-word glossary for what could not be avoided.

Co-authored-by: Orca <help@stably.ai>

* fix(ssh): stop reading an identity mismatch as a dead shell

The relay reports a pane-identity mismatch by saying the pty was not found,
but it found it — comparing identity is how it noticed. Publishing that as
expiry made the renderer clear the binding and cold-restore with agent resume,
so a live shell gained a second agent on one transcript. Reachable today by
detaching a pane into a new tab, which changes the tab the relay froze at spawn.

Mismatch now carries its own token and the classifier refuses it as proof.
Genuine absence still expires, so a shell that really went away is not stranded.

The three failure tokens move to src/shared: main published them and the
renderer decided respawn on them, from two copies that had drifted apart.

Co-authored-by: Orca <help@stably.ai>

* fix(ssh): stop sending pane identity on reattach

The relay froze pane identity at spawn, so moving a pane to another tab made it
refuse a live shell — and refuse by saying 'not found'. The comparison is
presence-guarded, so not sending the fields disarms it on every relay version
including ones already installed on hosts: no wire change, no redeploy.

Nothing is lost. It existed to catch a relay restart recycling pty-N for a new
shell, and in exactly that case pane and tab both still match, so it accepted
the wrong shell anyway. The incarnation the attach returns is what distinguishes
those, and it already crosses the wire.

Removes the whole client-side apparatus: the expected-identity type, its
per-lease derivation, its map, and the parameter threaded through four layers.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): add tracked goalposts for the new design

Each goalpost is a behaviour with an oracle and the mutation that must redden
it, so 'proven' cannot be claimed from a green test. Records the anti-inert rule
as a first-class goalpost, since three guards in this program passed their tests
while sitting off the route production takes.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): record that the recovery grant is dead code, deleting a design step

The lease stores a relay-native pty id and the caller passes the app form, with
a raw equality comparison between them, so the 30s grant cannot fire for a real
SSH pane. The death rule that existed to referee it is deleted rather than
built, and the dead path itself becomes a removal.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): keep the full design detail in the repo

It only existed in an ephemeral job directory, so the plain-English explainer
had no durable source for its specifics — record shape, death rule, reattach
algorithm, migration order and the 25 oracles.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): add a resume prompt for a clean session

Points at the goalposts as the contract, names the three goalposts whose oracles
are already written and red, and carries the process rules that were learned the
expensive way — prove guards reachable, verify mutations land, commit per step,
and never let a subagent write production files in a shared worktree.

Co-authored-by: Orca <help@stably.ai>

* test(ssh): add the failing oracles for goalposts S3, S4 and S5

Intentionally RED: 14 clauses that fail against current behaviour and go green
under the changes named in new-design-goalposts.md. The branch is held unmerged,
so red here means unimplemented, not broken.

Each was verified to fail for the right reason and to flip green under the
identified fix, which was then reverted. Each pins the producer as well as the
consumer, so no clause can pass vacuously if its route is ever severed — the
failure mode that let three earlier guards ship inert.

Co-authored-by: Orca <help@stably.ai>

* fix(ssh): stop fabricating an exit when a reattach fails

A failed attach never proves the shell exited. The relay answers not-found for
a pane-identity mismatch and for any id it merely cannot hand back, so treating
it as death sent the pane a synthetic `pty:exit { code: -1 }`, cleared provider
state, deleted ownership and expired the lease — four claims about a process we
know nothing about, on a shell that is usually still running.

Collapse every failure into the non-destructive branch that already existed a
few lines above (`restoreRequired = 'reattachAttemptsExhausted'` + wakeRecovery).
A branch collapse, not a new mechanism: goalpost S3.

Two tests pinned the deleted premise and are INVERTED rather than patched, so
the new intent stays covered:
- ssh-relay-orphan-abandon-paths: "retires the lease without a kill when the
  relay proves the PTY is gone" -> "leaves the shell running when the relay only
  reports the PTY as not found". Its comment claimed attach verifies liveness
  before answering not-found; it does not.
- ssh-relay-session: "invalidates and broadcasts remote PTYs that cannot
  reattach" -> "leaves an unreattachable remote PTY alone while its sibling
  reattaches".

Also repairs two clauses left red by c51be8072b (step A), which dropped the
expected-identity parameter and the expectedIdentityByPtyId map.

Mutation proof: restoring the destructive block reddens 6 of the 8 oracle
clauses in ssh-relay-reattach-exit-proof.test.ts; the 2 producer pins stay
green. Verified the mutation landed before believing the result.

Net production: -21 lines.

Co-authored-by: Orca <help@stably.ai>

* fix(ssh): give an SSH pane binding one home

An SSH pane's durable binding lived in two persisted partitions. Main's spawn
wrote `ssh:<target>`; the relay's reattach write passed no hostId and landed in
`local`; the renderer has always published SSH pane membership to `local` on
purpose. So `durablyBoundPtyIdForPane` hedged ssh-first-then-local, read a
partition no live writer maintained, saw the arriving lease disagree with a
stale pty id, and bailed — supersession silently no-opped and both leases stayed
live. That is the STA-3077 2 -> 19 -> 20 mechanism.

`local` wins: it is the only publisher of pane membership and where
`mayCreate:false` is evaluated. Every reader and writer now names it.
- resolvePersistedStablePaneOwner / retirePersistedStablePaneOwner drop their
  connectionId parameter and read the default partition.
- the CAS write and both spawn upserts drop the hostId argument (each was an
  if/else that collapses to one call).
- durablyBoundPtyIdForPane stops hedging.
- a one-time load fold moves any legacy `ssh:<target>` ptyIdsByLeafId into
  `local`, preferring `local` on conflict, sequenced after the leaf remap so
  every folded binding keys on a UUID.

Side effect worth naming: the renderer never hydrated the `ssh:*` partition
(listKnownRuntimeHostIds filters to `runtime:*`), so the Issue #217 force-quit
binding protection had never worked for SSH panes. It does now.

Mutation proof, run as a 2x2 because the two edits can mask each other:
- fold disabled, reader local-only -> 1 clause reddens (the fold is live)
- fold disabled, hedge restored    -> 3 more redden (the reader is live)
- fold enabled,  hedge restored    -> ALL GREEN

That last row is why this commit adds an eighth clause: with the fold shipping,
the fold erases the divergent copy at boot, so the reader guard would have
shipped unproven — the exact failure mode G5 exists to catch. The new clause
rewrites `ssh:<target>` mid-session (orphan adoption still writes there) and
reddens when the hedge is restored, pinning the reader on its own.

Five clauses in ipc/pty.test.ts pinned the two-partition shape and are INVERTED
to the single home, each keeping an explicit arity check so a re-added partition
argument fails loudly rather than silently.

Net production: +9 lines (the fold is new state repair; the call sites shrank).

Co-authored-by: Orca <help@stably.ai>

* fix(ssh): bind a pane through one producer so the fence is live on reattach

The superseded-PTY fence refuses a keystroke queued for a shell whose pane has
since bound a different one. It reads `ptyPaneKey` disagreeing with
`paneKeyPtyId` — and only spawn ever wrote those maps. Reattach bound the pane
through `runtime.registerPty` instead, so the maps never learned the successor,
`isSupersededPtyId` returned false by construction, and the fence was inert on
the one path it was built for. Goalpost S5; a defect in already-shipped work.

Collapse to one `bindPaneShell` producer that writes the durable record and the
fence maps together. All three binding paths call it: the relay reattach and
both spawn handlers. Error policy stays at the call sites because it genuinely
differs — a caller that just created a shell must clean it up on a failed
durable write, a caller that merely reattached must not detach anything.

The paneKey is composed from the tab that holds the leaf *now*, resolved from
the live layout, not from the tabId frozen in the lease. Only the leaf half of
a pane key is remint-stable; `detachTerminalPaneToTab` moves a live pane and its
PTY into a new tab, so a stored tabId names the tab the pane left.

Mutation proof, both sub-guards isolated:
- drop the `rememberPaneKeyForPty` call    -> 3 clauses redden
- prefer `args.tabId` over the live layout -> 1 clause reddens
The second clause is new in this commit. Every pre-existing clause in the fence
oracle used one tabId on both sides, so a producer that simply forwarded
`lease.tabId` would have gone green and shipped the tab bug unnoticed.

Two source-text clauses are STRENGTHENED, not relaxed. They previously required
the relay to hold a `persistPtyBinding` call of its own and merely forbade an
ssh-partition argument on it. The relay now has none, so they assert ZERO direct
binding writes there plus a `bindPaneShell` call — a second bind producer is
exactly the defect this removes.

Also repairs a latent false green: the "persistence fails" case in
ssh-relay-session-reconnect-incarnation was passing because a missing mock made
the call throw a TypeError that happened to emit the console.error it asserted.
The failure is now injected at the producer, so it is a real oracle for "a
thrown durable write must not detach the PTY".

Net production: +60 lines. This is the one step in the program that grows;
the shrink arrives with S8's deletion. Reported rather than smoothed over.

Co-authored-by: Orca <help@stably.ai>

* feat(terminal): show an unreachable pane as disconnected with two actions

Ships with S3. Collapsing the fabricated exit removed a lie, but it left the
pane frozen: `restoreRequired` never crosses to the renderer, so a relay-driven
reattach failure had no user-visible signal at all, and the renderer's own
reattach arms showed a raw error toast with no way to act.

An unproven failure now renders the pane as disconnected with exactly two
explicit actions — "Try again" (remount against the same shell via
requestTerminalPaneRecovery) and "Start a new terminal" (retire the binding,
then spawn fresh). Nothing infers death and nothing auto-spawns; the user
decides, because at that point no one knows whether the shell is alive.

The two actions are the same two things the code already did, moved behind a
click: the retry is the existing pane-recovery request, and "start a new
terminal" is the existing clearExitedPanePtyLayoutBinding + clearTabPtyId +
startFreshColdRestoreAgentResume sequence that used to run automatically on a
"proven gone" error. No new IPC channel: the silent-respawn decision was always
renderer-local.

Copy constraint, enforced by an oracle rather than a review note: the banner may
never assert the shell exited. STYLEGUIDE.md:236 already forbids result verbs
without result data, and a failed attach is not result data. A test asserts the
rendered text matches no death verb and shows no wire token.

`TerminalRemoteRuntimeReconnectBanner` is renamed `TerminalPaneDisconnectedBanner`
— it now serves any transport, and per AGENTS.md the name must say what it holds.
Existing i18n key strings are kept verbatim so no shipped translation breaks;
the SSH copy is additive (4 new en.json keys).

`describeReattachFailure` is deleted with its last caller. Its two cases were
not dropped: "keeps the wire token out of the pane" is re-asserted against the
new copy, which is a stronger place for it.

Renderer production (excluding the pure rename): +28 lines.

* refactor(terminal): delete the SSH pane recovery grant, which could not fire

For a disconnected pane, `recoverTerminalPane` consulted a recently-expired SSH
lease and, on a match, spawned a replacement shell. It could never match: leases
store a relay-native pty id (`pty-7`, normalized on every write) while the
runtime registers the app-form id (`ssh:<conn>@@pty-7`), and the comparison was
a raw `===`. The branch was also unreachable for a local pane, which has no SSH
lease. Goalposts S6 and S8.

A characterisation oracle lands FIRST and proves it, rather than assuming it:
ssh-pane-recovery-grant-reachability.test.ts mints BOTH id forms from the
production helpers — never as two hand-typed literals — so it tracks the real
namespace split instead of restating it, and seeds a lease that qualifies on
every other predicate (state, worktree, tab, leaf, grace window). Anti-vacuity
assertions pin that control actually reaches the gate rather than bailing early.

Mutation proof, run before the deletion: normalizing the comparison at the
`lease.ptyId === ptyId` site makes the grant fire and reddens the oracle. That
is the exact "fix" someone would reach for, so the oracle is pinned to
unreachability rather than to the throw.

Deleted: the grant tail, the `terminalPaneRecoveryByIdentity` dedup map (whose
only consumer was the grant), and the dead `ptyId` parameter.
NOT deleted, and worth naming because over-deleting here would break users:
`getRecentExpiredSshLease` itself, `hasRecentExpiredSshLeasePane` and
`SSH_PANE_RECOVERY_GRACE_MS` all stay. Their other two callers pass `ptyId`
undefined, which short-circuits the broken comparison — those are live today and
feed headless-mobile terminal-tab visibility.

Also NOT done: deleting only the gate while keeping the spawn. That would have
granted a respawn to every disconnected pane — a behaviour change in the
dangerous direction. The refusal is what stays.

Four tests pinned the grant. All were seeded through a helper that stores the
lease id as the same literal it registers as the runtime pty, with a null
connectionId — a shape production cannot mint. Three are INVERTED, keeping their
scenarios; the fourth is now tautological and carries a comment saying so rather
than being left silently hollow. The oracle's own counterfactual control is
inverted by this deletion too, which is recorded in the file: its flip from
grant to refusal is what "inert" means here.

Honest limit, stated in the oracle rather than smoothed over: unreachable BY
CONSTRUCTION for SSH panes; for a local pane, unreachable only up to a random
UUID collision.

Net production: -32 lines.

* docs(terminal): record S3, S4, S5 and S8 proven, and G1 missed

All seven step goalposts are now proven. G1 (net-negative production) is NOT met
at +83 and is reported as a miss with a per-step breakdown rather than reframed.

Also records the near-miss G5 caught: S4's reader guard showed no mutation
response because the load fold had already erased the divergent state at boot.
It was correct and would have shipped unproven. An added clause pins it.

* fix(terminal): a reattach not-found is not proof the shell is gone

Closes the last live route to the reported duplicate agent resume (RC2), found
by the E2E harness rather than by reading: when a relay is stalled and replaced,
the fresh relay has no memory of `pty-1` while the old shells keep running under
its predecessor. It answers not-found, and the renderer read that as proof.

A not-found means the relay WE ASKED cannot hand that id back. That proves an
exit only if the relay process that minted the pty is the one answering. The
design says exactly this (D3 row 2), and gates the grant on `relayInstanceId`
equality — a field step E-2 never built. `SSH_SESSION_EXPIRED` is not
independent evidence either: its ONLY producer is that same not-found mapping in
reattachSshPtySession, and the token's own doc comment claimed "the host proved
the session is gone", which it never did.

So `isProvenSshSessionGoneError` returns false. Both reattach arms now always
take the non-proof path and surface the pane as disconnected, which is what the
owner approved in D1 — and what makes that affordance load-bearing rather than
near-unreachable, since it was previously only reached by errors that were
already rare.

The respawn tails are deliberately NOT deleted. The design preserves the grant
as a conditional for E-2, so the decision point stays and a clause pins that
nothing reaches it meanwhile. This is the one place in the program where an
unreachable branch is kept on purpose, and it is labelled as such.

Tests: three clauses asserted a not-found proves death and are INVERTED, with
the reasoning recorded. The #12101 cold-restore case reached the spawn door by
throwing a not-found; that door is now opened by the user's "Start a new
terminal", so the test drives that instead and keeps all four of its original
assertions verbatim — strictly better coverage, since it now pins that the
automatic respawn stopped AND that the door still works.

Mutation proof: restoring the old predicate makes the new no-respawn clause fail
with "expected connect to be called 1 times, but got 2", confirming it reddens
on the real production route rather than passing vacuously.

* test(ssh): add E2E oracles for pane cardinality and duplicate resume

Both reported failures now have end-to-end coverage against a real Docker
OpenSSH relay, gated on ORCA_E2E_SSH_DOCKER like the rest of the suite.

- ssh-reconnect-pane-cardinality-across-partitions: three real reconnect cycles;
  after each, pane ids unchanged, exactly one live lease per leaf, exactly one
  remote shell per pane key, and exactly one pty id bound per leaf ACROSS BOTH
  durable partitions. Two partitions agreeing is tolerated; two naming different
  shells is the S4 divergence and fails. PASSES.
- ssh-reattach-does-not-resume-agent-twice: the host itself records one line per
  shell launch via a .bashrc hook keyed by ORCA_PANE_KEY, so a duplicate resume
  is counted at the source rather than inferred. Fault is SIGSTOP on the
  detached relay. PASSES.
- ssh-disconnected-pane-affordance: written whole but held as test.fixme. The
  banner needs the target CONNECTED while a single pane's attach fails, and both
  host-side faults drove the target out of connected instead. Held rather than
  deleted so it runs the day a seam exists; the reason is measured, not assumed.

New helpers: docker-ssh-relay-stall (SIGSTOP/SIGCONT, reads the stop back off
/proc so a fault that did not land cannot make an oracle vacuous), and
remote-pane-launch-transcript.

Note for whoever picks these up: a stalled relay leaves two detached relay groups
on the host, and readDockerSshRelayProcessSnapshot throws on more than one, so
call it before the fault.

Writing these is what surfaced RC2 surviving S3 — fixed in 7cd7fef927.

* fix(ssh): fold the pane incarnation with the binding it fences

Found by adversarial review. `persistPtyBinding` writes the binding and its
incarnation into the SAME partition, and the incarnation is what its CAS
compares. Step P's load fold moved only `ptyIdsByLeafId`, so after upgrade a
pane whose incarnation had been written to `ssh:<target>` kept the guard in the
partition nothing reads: `resolvePersistedStablePaneOwner` read `undefined` from
`local`, the CAS then compared undefined against undefined, and the incarnation
half of the fence passed for any value until the next write healed it.

Not data loss and not a wrong-shell bind — the ptyId half still held — but a
guard silently weakened by a migration is the exact shape this program keeps
finding, so it is closed rather than noted.

Mutation proof: disabling the incarnation half of the fold reddens the new
clause; the other eight stay green.

One clause in persistence.test.ts asserted the incarnation survives a reload in
the SSH partition. Its subject is that the reconciled value is preserved, not
which partition holds it, so the assertion follows the binding to its one home
and additionally pins that the ssh partition no longer keeps a copy.

* docs(terminal): record the two defects found after the goalposts were met

RC2 survived S3 and was found by writing the E2E test, not by reading. The load
fold left the incarnation half of the pane fence behind and was found by
adversarial review. Both were invisible to unit oracles that had already gone
green, which is the useful part of the record.

* fix(terminal): close four defects found by adversarial review

Four reviewers over the diff, every finding put to an independent skeptic. Nine
of twelve agents died on prompt length, so most findings arrived UNREFUTED
rather than refuted — I checked those myself instead of counting them clean.
Four were real.

1. "Start a new terminal" resumed the agent instead of starting a new one.
   The action passed the cold-restore startup, which carries the agent's
   providerSession. That was correct for the automatic respawn it replaced,
   because that only ran on PROOF the shell was gone. Behind this button the
   shell is probably still alive, so it put a second agent process on one
   transcript — the exact defect this pane exists to prevent, reintroduced by
   the fix for it. Now starts a genuinely fresh shell, which is also what the
   button says.

2. The banner was never retracted. The app-SSH transport publishes no recovery
   states, so nothing cleared the card: it sat over a live shell with armed
   buttons. Both actions now clear it before acting.

3. The load fold destroyed bindings it could not move. When a tab existed only
   in the ssh partition there was no local layout to fold into, and the code
   cleared the source anyway — deleting the only record of that binding. It now
   leaves such a tab alone: with no second home there is nothing to disagree
   with and nothing to fold.

4. The relay registered the pty under the lease's frozen tabId while
   bindPaneShell bound and fenced it under the live one, splitting a moved pane
   across two tabs and ensuring a mobile surface for the tab it left.
   bindPaneShell now returns the resolved tabId so both use one coordinate.

Also repairs a reliability-gate manifest entry the banner rename broke. That
would have been caught by the pre-commit lint gate, which I had been skipping
with --no-verify; the full-repo sweep caught it instead.

Mutation proofs, each verified to land before being believed:
- restoring the resume reddens on `registerAgentLaunchConfig` and, with that
  clause disabled, on the spawned command being
  "codex '--dangerously-bypass-approvals-and-sandbox' 'resume' 'codex-session-1'"
- disabling the fold's move reddens the ssh-only-tab clause
- registering under lease.tabId reddens the moved-tab clause

The first clause was VACUOUS on its first attempt and is recorded as such: the
fixture had no resumable agent, and it asserted a field name the spawn path does
not use. It now pins the fixture itself, so it fails loudly rather than going
quiet again if `codex` stops being resumable.

* fix(terminal): drop the remote-host assumption from the disconnected copy

The banner said the shell 'may still be running on the host'. The reattach arm
that publishes it is not SSH-only — a local or folder-workspace pane reaches it
too, and there is no host to speak of there. The claim that matters is that the
shell may still be running, which holds either way.

* fix(terminal): close round-2 review findings, including one regression

Round 2 ran narrow per-area scopes so agents stopped dying on context: 7 of 7
reported, versus 3 of 12 in round 1. Two findings survived refutation and both
were real.

1. REGRESSION I INTRODUCED. `bindPaneShell` resolved the tab from the live
   layout for EVERY caller. That is right on reattach, where the lease's tabId
   is the frozen side — but backwards on spawn, where the caller's tabId is
   fresh truth and the persisted layout is the stale side inside the renderer's
   publish debounce. Breaking a pane out into a new tab and spawning into it in
   that window resolved back to the tab the pane had just left, writing the
   durable binding and the fence under one tab while the lease and the runtime
   registration used the other — the split-coordinate defect step F exists to
   remove, reintroduced on the spawn path.
   Live-layout resolution is now opt-in via `tabIdMayBeStale`, set only by the
   reattach bind. A clause pins that no spawn-side call sets it.

2. The fold moved every incarnation even for a binding it had deliberately left
   in place, splitting a pane's binding from the incarnation that fences it —
   the same defect 994733d8b1 closed, in the other direction. Incarnations now
   move only with the binding they belong to. The reload clause that had been
   inverted for the fold is restored to its original assertion, because an
   ssh-only pane now correctly keeps both halves together.

Also closes a live route to the reported duplicate resume that my earlier fix
missed. `isProvenSshSessionGoneError` covered the rejected-promise arms, but a
reattach can also report expiry through the transport's error callback and then
resolve falsy; those two branches still cleared ownership and cold-restore
resumed the agent. A skeptic refuted this as pre-existing rather than caused by
this branch, and that is correct on causation — but it is a live second route to
the exact defect this work exists to remove, so leaving it would make the claim
that duplicate resume is fixed false. Both branches now surface the disconnected
pane.

Five tests pinned that callback respawn. Two are INVERTED to the disconnected
outcome; two keep their real subject (stale-callback fencing, delayed parked
snapshot) and now reach a replacement shell through the banner's "Start a new
terminal", which is the new production route; one — the cold-restore resume
after expiry — is inverted to assert no resume command and no agent launch
config, with a fixture pin so "no resume" cannot pass vacuously.

* fix(terminal): close round-3 review findings on tab resolution and the fold

Round 3, narrow scopes again: 9 of 9 agents reported. Two findings confirmed.

1. A thrown durable write lost the resolved live tab. `bindPaneShell` resolved
   the tab internally, so when `persistPtyBinding` threw, the relay's `bind`
   stayed null and it registered the pane in the runtime graph under the frozen
   lease tab — splitting the graph from the durable record it had just moved.
   Resolution is now an explicit `resolvePaneShellTabId` the relay calls BEFORE
   the write, so a throw cannot lose the answer. This also deletes the
   `tabIdMayBeStale` flag added a commit ago: the reattach resolves its own tab
   and passes a live one, and spawn callers simply pass theirs. The distinction
   is now carried by which caller resolves, not by a flag they must remember.

2. The fold could pair a binding with an incarnation that was never written
   alongside it. Where both partitions named a leaf, local won the binding but
   the incarnation was copied across independently — so local's pty could end up
   fenced by the superseded partition's incarnation. `persistPtyBinding`'s CAS
   compares both, so that pane's next legitimate update would be refused. An
   incarnation now moves only when the pty it belongs to is the one that ends up
   bound.

   My first attempt at this over-corrected and skipped the case where both
   partitions name the SAME pty — where the incarnation does belong with it. The
   existing clause caught that immediately, which is the fixture doing its job.

Also hardens `findTerminalTabIdForLeaf`: it now requires the tab to still exist
in `tabsByWorktree`. A layout entry outlives the tab it described, and binding a
live shell to a deleted tab registers a pane under a ghost and can resurface it.
The fence oracle's fixture gained the live tab it was missing, so that clause
cannot pass by resolving nothing.

New clause covers the divergent-pty case the reviewer named — the two partitions
naming DIFFERENT ptys for one leaf, which is the divergence being migrated and
was previously untested.

* fix(terminal): check tab liveness without depending on a worktreeId match

A reviewer asked, correctly, whether lease.worktreeId always matches the
tabsByWorktree key exactly — including for a folder workspace, whose worktreeId
carries a `::workspace:<uuid>` suffix and is matched by full-string equality.

Rather than assert that invariant, this removes the dependency on it. Tab
liveness is now checked across every worktree instead of under one key. A leaf
id is a UUID, so there is nothing to disambiguate by worktree, and the resolver
no longer has an answer that depends on two strings agreeing — which is exactly
the class of full-string comparison that produced issue #12474 in this area.

Had they diverged, resolution would have silently returned undefined and fallen
back to the stale lease tab, quietly restoring the moved-pane bug for folder
workspaces only. Failing open like that is worse than the check itself.

* style(terminal): keep the membership authority under the max-lines limit

My previous comment pushed the file to 301 lines. AGENTS.md forbids a max-lines
disable or a per-file bump, so the comment is trimmed to the repo's concise
standard and the liveness check folded into the existing condition.

* fix(ssh): resolve every incarnation in the pass that clears its binding

Round 4 confirmed one defect, in my own round-3 fix. The filter that stopped an
incarnation following a LOSING binding also stopped it being deleted — while the
binding itself was still cleared. So a conflicted leaf left the superseded
incarnation behind with nothing to fence: durable fence state in a partition
holding no binding, which is the one-home invariant this step exists to
establish, broken by the code establishing it.

The reviewer also named the test gap exactly: the clause I added asserted only
that the value was not copied into local, never that it was gone from the
partition it lost in. Both are asserted now.

Incarnations are resolved in the same loop that clears the bindings, so no
binding can be cleared without its fence being resolved. Three outcomes, by
which pty ends up bound:
- this binding moves (local had none)   -> its incarnation moves and OVERWRITES
  any local value, because a local incarnation with no local binding is a
  leftover rather than a fence. That case previously synthesized a pair.
- both name the same pty                 -> keep whichever fence local holds.
- local wins with a different pty        -> drop this incarnation with the
  binding it belonged to.

The second and third outcomes were flagged by the same reviewer as real but
attributable to my earlier commit rather than that one. They are the same defect
class, so they are fixed here rather than filed.

Two new clauses: the superseded incarnation is deleted, not merely uncopied; and
a moving binding overwrites an orphaned local incarnation.

* fix(ssh): never pair a moving binding with a fence that was not written for it

Round 5 ran a mechanical ten-case matrix over the fold twice, independently. Both
passes landed on the same primary defect, and it is one my previous fix created.

Case 7: the ssh partition holds a binding with NO incarnation, and local holds a
stale incarnation with no binding. The binding moves into local and inherits that
leftover, producing (arriving pty, unrelated incarnation) — a pair no writer ever
produced. persistPtyBinding's CAS compares both halves, so the pane's next
legitimate update is refused. The previous fix only replaced local's leftover
when the ssh side had an incarnation to replace it WITH; absent one, the leftover
survived. A moving binding now takes the ssh fence whatever it is, including
absent, in which case local's is deleted.

Also fixes the bookkeeping both passes flagged: the function defaulted
`workspaceSession` at the top, so a profile with no local session could be
mutated on a path that then returns false — a mutation with no save scheduled.
It now returns early instead: with no local session there is nothing to fold
into, which is also the honest reading.

Two findings are deliberately NOT fixed, recorded rather than silently dropped:
- An ssh incarnation whose binding was already missing BEFORE the fold survives,
  because iteration is binding-driven. It is a pre-existing orphan isolated in a
  partition no reader consults for pane bindings, and reinterpreting it is not
  this migration's business. The comment claiming an incarnation never outlives
  its binding overclaimed and is corrected to say what the code does.
- Two ssh partitions carrying the SAME tab and leaf resolve by object-key order.
  A tab belongs to one worktree on one host, so this is not a shape production
  writes; making it deterministic would mean inventing a precedence rule for a
  state that should not exist.

New clause covers case 7 directly. The matrix cases both reviewers named as
uncovered are now covered except the two above.

* refactor(ssh): delete the pane-binding fold; its premise was false

The migration moved legacy `ssh:<target>` pane bindings into `local` and cleared
them, on the theory that the ssh partition was a stale spill of the desktop
plane's state. Investigation of both hypotheses the team raised disproved that:

- NOT cross-version compat. The introducing commit says it is for CONCURRENT
  multi-host. Nothing about the partition crosses the wire (zero references under
  src/main/runtime/rpc/), and the payload that does cross the SSH boundary —
  RemoteWorkspaceSnapshot — is projected from `local`. The only downgrade-compat
  comment protects `local`, the other direction.
- NOT multi-client. PersistedState is one file on one machine; phones and CLI are
  RPC clients into that same process. Orca's real per-client state is
  `mobileClientTabSelectionsByDeviceId`, 13 lines above in the same struct, and
  it carries selections only — never a ptyId.

What it actually is: the headless/CLI/mobile plane's OWN home, written and read
deliberately across several tickets (STA-3463, STA-3465), with tests that assert
that partition by name. So the fold was not tidying a spill — it was erasing
another plane's live state. Measured symptom: a split SSH tab would disappear
from mobile while its shell kept running.

The desktop plane's fix never needed it. Supersession multiplied panes because
`durablyBoundPtyIdForPane` hedged into the other plane's copy; reading `local`
alone is the fix, and it stands without any migration.

Deleting rather than redesigning, because the redesign had no target: five review
rounds each found a defect in that function, three of them inside the previous
round's fix, and every one was a cell of a merge matrix that only existed to
serve a premise that was false.

The `boundPtyIdsAcrossPartitions` clause is INVERTED, not dropped. It required
the two partitions to AGREE after load — which encoded the false premise, and is
what made a migration look necessary. It now asserts the narrower, stronger
property: what the desktop plane resolves follows `local` alone, whatever the
other plane holds.

Also proven, and the reason unification was NOT attempted: worktreeId is
`<repoId>::<path>` where repoId is a randomUUID minted client-side at repo add
(orca-runtime.ts:18722), so two servers cannot collide on one. Host scoping was
not protecting against that here — but the two planes' opposite choices are each
deliberate and each test-pinned, so choosing a winner is an architecture call,
not a cleanup.

Net production: -75 lines.

* fix(ssh): arbitrate on the pane, not the tab its lease was written in

Correctness review round 1 on #13326: 5 raised, 2 confirmed, both real.

1. Arbitration looked the durable binding up under the lease's FROZEN tabId.
   `detachTerminalPaneToTab` moves a live pane and its PTY, and nothing re-keys a
   lease, so after a break-out the binding lives under the new tab and the lookup
   found nothing. The bound shell then lost to recency and supersession expired
   the pane's OWN lease; the follow-on scrub could not clean up either, because
   it matches lease.tabId against the layout's tabId. Reconnect skipped the
   expired-but-bound PTY and reattached the stale winner onto the pane.

   The leaf is the stable half of pane identity, so the lookup now prefers the
   named tab and falls back to wherever the leaf actually is.

2. Arbitration read the desktop plane only while the scrub reached into
   `ssh:<target>`, so a headless-plane pane was invisible to the ranking and
   then lost its live binding to it.

   Fixed at the reader, not the scrub: local FIRST, headless plane only as a
   fallback. That is NOT the STA-3077 hedge — that bug was preferring
   `ssh:<target>`, letting a copy no live writer maintains outvote the real
   binding. A fallback consulted only when local is silent gives a headless-owned
   pane a vote without ever outranking a live desktop binding.

   Proven by mutation: swapping the two back to ssh-first reddens 4 clauses,
   including the ten-reconnect cardinality one.

Also closes two fulfilled-result routes to the duplicate agent resume that the
earlier RC2 fix missed — `handleReattachResult` respawned on a result flagged
`sessionExpired` and on a result carrying no pty id. A skeptic refuted both as
pre-existing rather than PR-caused, which is correct on causation, but they are
live routes to the defect this PR claims to fix.

Scoped to SSH panes only. The first attempt diverted every pane and broke three
daemon tests — correctly: a local provider is authoritative about its own ptys,
so "cannot reattach" there is not the ambiguous evidence it is for a relay that
may have been replaced. New clause covers both routes; disabling the diversion
reddens it.

43,253 pass; the 7 failures are pre-existing on clean main in this environment.

* fix(ssh): supersede on the leaf, so a moved pane retires its own predecessor

Correctness round 2. This is the reported cardinality growth in its surviving
form, and it is the sharpest finding of the review so far.

Supersession matched sibling leases on `(worktreeId, tabId, leafId)` and bucketed
duplicates under the same key. A lease freezes its tabId when written, and
`detachTerminalPaneToTab` moves a live pane — so after a break-out the pane's
next lease carries the NEW tab and its predecessor carries the old one. The two
never match, the predecessor is never superseded, and the live count grows on
every reconnect. Exactly the reported 2 -> 19 -> 20, for any pane that has been
moved between tabs.

Round 1 fixed the same frozen-tabId mistake at the binding LOOKUP. It did not fix
it here, at the sibling match and the bucket key, which is why the bug survived a
round. Both are now keyed on the leaf — the stable half of pane identity, per
stable-pane-id.ts: the tab half changes on break-out.

Two clauses cover it: a predecessor whose lease names the tab the pane left is
superseded, and the live count stays flat across ten reconnects that each land in
a new tab. Restoring `tabId` to either the match or the key reddens both.

E2E re-run against a real Docker relay after the change: 2 passed. Full suite
43,255 pass; the 7 failures are pre-existing on clean main in this environment.

* fix(ssh): a supersession decided from one plane only mutates that plane

Correctness round 2 confirmed finding. Arbitration ranks leases using the desktop
plane's binding, then handed its losers to a scrub that walked BOTH planes — so
the headless/CLI/mobile plane's binding was deleted for a lease it never got to
vote on. Its owner then has no durable record to reattach that shell by, and can
fall back to recency or orphan a shell that is still running.

`clearSshRemotePtyBindingsForLeases` now takes `arbitratedFrom`. A decision
reached by reading one plane may only mutate that plane. An explicit expiry or
termination is plane-agnostic — the pty is gone for everyone — so those callers
pass nothing and still scrub both, which is what the existing
`markSshRemotePtyLease` oracle pins.

I initially assessed this as not-a-defect, reasoning that local winning IS the
STA-3077 fix. That was about RANKING and did not justify DELETING the other
plane's record; the round-2 verdict was right and I was wrong.

It did also catch a comment of mine that had gone stale — a clause claimed the
other plane was "deliberately left alone" while the code cleared it. The comment
now says what the code does and why.

Mutation: letting arbitration scrub both planes again reddens the new clause.
43,256 pass; the 7 failures are pre-existing on clean main in this environment.

* fix(terminal): put the unreachable-pane guards in one place

Correctness round 3. The leaf-keying from round 2 came back clean, twice and
independently. But the renderer produced findings for a third consecutive round,
and they were all one shape: `publishUnreachablePane` is called from seven sites,
each needing the same guards, and a different one was missing at each.

So this stops patching sites and moves the guards into the publisher:

- `disposed` — a late rejection republished a card for a numeric pane id that had
  already been reused, giving a fresh pane a phantom card whose actions closed
  over a dead session.
- `connectionId` — the deferred catch is not SSH-only. A local/daemon pane could
  be shown an SSH ambiguity card it can never clear, and would loop: retry
  remounts, reattach rejects, card returns. Its provider is authoritative about
  its own ptys, which is exactly why the two branches in handleReattachResult
  already had this guard — and why the catch needed it too.

Two more real defects in the banner's own actions:

- "Start a new terminal" passed `null` to suppress the saved agent startup, but
  connect FALLS BACK to the startup its transport was constructed with whenever a
  per-call field is absent (pty-transport.ts). So the "fresh" shell could resume
  the same provider session — the duplicate transcript this pane exists to
  prevent, for the third time in this button. `suppressSavedStartup` makes the
  suppression explicit; `??` means passing null could never have worked.
- It also cleared both durable bindings BEFORE the spawn, and discarded the
  promise. A spawn that resolves null left the pane blank, unbound, and with no
  way back to a shell that may still be running. Bindings are now cleared only
  once a replacement actually starts, and the card returns if it does not.
- "Try again" voided its boolean; a declined remount left no card and no shell,
  strictly worse than the toast it replaced. It now republishes.

The strengthened clause is the point: the old one asserted the ABSENCE of
per-call startup fields on a mocked transport, which passes whether or not the
production fallback fires. It now asserts the explicit suppression, and reddens
when the flag is dropped.

Four fixtures were under-specified — they drive SSH reattach scenarios but never
seeded an SSH repo, so `connectionId` was null and they had been passing without
the pane being SSH at all. Seeded, not weakened.

43,256 pass; the 7 failures are pre-existing on clean main in this environment.

* fix(terminal): suppress the whole saved startup set, not field by field

Round 4 self-check on my own round-3 fix. `suppressSavedStartup` guarded four of
the six values `connect` falls back to — `launchAgent` and
`startupCommandDelivery` still inherited from the transport's constructor. Adding
the guard per field is precisely how those two were missed, and the guarded
expressions had become unreadable.

The saved values are now one object that `suppressSavedStartup` drops wholesale.
A field added later is covered by construction rather than by remembering.

Found by asking the question the review lens was given rather than waiting for
its answer: does the suppression cover EVERY channel, or only the ones I noticed?
It did not.

* fix(terminal): stop stranding a local pane whose restore fails

The unreachable-pane card is SSH-only: a local, daemon or runtime-host pane has
no connection to be unreachable ON. Consolidating that guard into the publisher
made it silent, and four callers paired the now-conditional publish with an
unconditional `return` — so on the deferred-reattach path, which unlike the
direct-SSH one is not nested under `connectionId`, a local pane got no card, no
error and no replacement. Frozen, with a stale binding.

The diversion now reports whether it took ownership of the failure, so a caller
can only stop when something actually handled it. A pane that cannot show the
card falls through to the replace-in-place it had before, which is correct: its
provider is authoritative about its own ptys.

The two direct-SSH sites are inside `if (connectionId)`, so they are unchanged
in behaviour; the return value simply makes the pairing impossible to get wrong
at the next call site.

* docs(terminal): put two comments back on the thing they describe

The lease-healing docblock had drifted onto durablyBoundPtyIdForPane, which
neither retires leases nor returns a count, leaving the real healing entry point
undocumented and its neighbour carrying two contradictory descriptions.

The suppression comment claimed to cover "every startup value this transport was
constructed with"; env/envToDelete are constructor values and deliberately stay
outside the set. Nothing behavioural changes here — but a comment that overstates
a boundary is how the next maintainer picks the wrong one.

* docs(terminal): do not claim a remote runtime is authoritative about its ptys

A remote runtime reaches its pty over a connection that can fail, so a failed
reattach proves no more there than it does over SSH. It keeps replacing in place
only because the card is SSH-scoped, not because its provider is authoritative.
Say that, so the limitation is deliberate rather than implied.

* perf(ssh): stop fsyncing the whole store from the main thread on reconnect

supersedeDuplicatePaneLeases runs at the top of every reattach pass, and when it
retires anything it flushed synchronously. flushOrThrow fsyncs a multi-MB file
from the Electron main thread — this file already documents (see flushAsync) that
on a stalled network profile mount that syscall is uninterruptible, so the app
stops repainting and no deadline can bound it, because the deadline's own timer
is stuck behind the same block.

The population that hits this is exactly the one the heal exists for: an upgraded
install carrying accumulated duplicates. It now awaits the async durable twin its
neighbours on this path already use. Still "OrThrow", because a retirement that
is not durable must not be believed — the rollback is unchanged.

* fix(ssh): make a parked PTY delivery expire instead of going dark for good

Exhausting the per-generation recovery budget parks one PTY's delivery rather
than dropping the shared relay channel — right, because the channel is shared and
a retry count proves nothing. But the only escape it named was "the next relay
open", and a channel that stays healthy never gives it one. That leaves a pane
with no output and no way back, which is the exact state this change exists to
prevent; before this branch, exhaustion dropped the channel and the reconnect
ladder recovered the pane (loudly, at every sibling's expense).

The park is now a cooldown rather than a verdict: the next rejected frame after
it starts a fresh budget. Recovery is rate-limited, never abandoned, and the
containment that made parking right in the first place is untouched.

Elapsed time, not a timer, so there is nothing to cancel on teardown and no late
fire after dispose.

* fix(ssh): let a due park past the retired-delivery filter, and prove it

The cooldown added in 124e00e8a8 was reactive: it needed a later rejected frame
to reach recovery. But retirement is ours, not the host's — a stalled source keeps
publishing the very token we retired, and acceptPtyData drops those frames before
classification. So the wake-up could never fire in the case that actually happens,
and the pane stayed dark exactly as before.

A parked PTY past its cooldown is now let through that filter. It costs nothing:
the frame is re-classified as rejected and re-retired, so no output reaches the
terminal — it only regains the ability to ask for recovery.

The test shipped with that commit could not have caught this: it woke recovery
with a fabricated NEW delivery token. Retirement holds one key per relay PTY, so
that frame overwrote the key and un-retired the original — the assertion passed
with the wake-up path fully broken. It now reuses the original token throughout,
and reverting the guard above reddens it.

* refactor(terminal): one i18n namespace per component, and two notes worth keeping

The disconnected banner was renamed but kept reading five keys under the old
component's namespace while its new strings sat under the new one — a component
translating from two namespaces at once. Keys moved across all five locales;
values and behaviour unchanged.

Two comments earn their place. durablyBoundPtyIdForPane deliberately does NOT
require the tab to still exist, unlike findTerminalTabIdForLeaf which must —
adding the "missing" check there would make arbitration retire shells more
eagerly, which is the opposite of what this change is for. And the respawn after
the proof check in the direct-SSH catch is unreachable today by construction;
saying so stops it reading as forgotten code.

* fix(ssh): unknown PTY liveness is not proof of death

hasPty is three-state and says so: null means the provider has not listed the
host yet — ignorance, not death. The retry gate tested it with `!`, which reads
null and false alike, so it ended recovery on ignorance.

That state is not exotic: a reconnect builds a fresh provider with an empty set,
which is exactly the moment rejected frames arrive. The attempt was deleted and
no retry scheduled, and because the delivery token was already retired, no later
frame could revive it — the pane stayed dark. It also short-circuited the park
cooldown, since parkedAt was never set on an entry that no longer existed.

Only an explicit false stops us now. The proven-exit clause still pins that.

* fix(terminal): do not unbind a live shell the new-terminal spawn adopted

While the card is up the pane keeps its durable binding on purpose, so a failed
replacement can put the card back. But main resolves a stable pane's owner from
that same binding: if the shell answers again between the failed reattach and the
click, the spawn adopts it and returns its id. Nothing was replaced, and clearing
the binding then unbound a shell that is live and attached to this very pane —
leaving it running with no durable record of what it owns.

Detected by identity: an id equal to the one we were replacing means adoption,
not replacement. Suppressing adoption outright would need a new spawn option
plumbed renderer -> transport -> IPC; the user-visible oddity that remains is
getting the old shell back rather than a new one, which is benign next to
orphaning it.

* feat(ssh): record the host-attested shell identity on the lease

A lease names a shell by ptyId, and ptyId alone cannot identify one: a replaced
relay restarts its ids at pty-1, so the same id can name somebody else's shell.
This adds the missing primitive — the incarnation the HOST attested — so a later
change can tell "my shell" from "a different shell wearing its id". No behaviour
changes yet; nothing reads the field.

Only host-attested values are stored. The provider synthesizes a stand-in when a
host reports none; that stand-in is first-write-wins and is dropped when provider
state resets, so the same live shell can present a different one after a
reconnect. Recording that would later read as a different shell and strand a live
pane, so it is refused, and the synthesizer now shares the prefix constant with
the predicate that rejects it.

Leases are rebuilt field by field on load, so the normalizer had to learn the
field too — adding it to the type alone drops it on every boot, which is how a
fence ships silently permitting everything. The oracle reddens on exactly that.

* fix(ssh): fence a recycled relay PTY id on the shell's own identity

A reset relay restarts its ids at pty-1, so an id alone can name somebody else's
shell: a pane still bound to pty-1 could attach to a shell another pane was
already driving, and the two would share keystrokes and output.

The guard that used to catch this compared the paneKey and tabId frozen at spawn.
It was removed for good reason — a pane moved to another tab was refused its own
live shell, and refused as "not found", which read as death and resumed the agent
a second time. So it traded a cross-attach for a double resume.

The incarnation is the shell's OWN identity, so it discriminates a recycled id
without caring where the pane lives: both failures close at once. The relay
refuses a mismatch and is deliberately not worded "not found" — that phrasing is
what the client maps to an expired session, and expiry authorizes a respawn onto
a shell this branch just proved is alive.

Only a host-attested expectation is sent. The locally synthesized stand-in is not
stable across reconnects and would refuse a pane its own shell. An older relay
ignores the field and an older client sends none, so both stay permissive.

The tab-keyed comparator is deleted rather than left dormant, and its suite is
inverted onto the new identity: a recycled id is still refused, and a pane that
moved tabs now attaches instead of being told its shell is gone.

* fix(ssh): only an exit the relay watched may authorize a replacement

A bare not-found became SSH_SESSION_EXPIRED, and expiry authorizes a respawn.
But "the relay I asked cannot hand that id back" proves an exit only if that
relay is the one that minted it — a replaced relay answers exactly this for
shells still running under its predecessor. So after a relay restart, live
orphaned shells were read as dead: ownership cleared, lease expired, and the
agent resumed a second time onto a transcript its first process was still
writing to.

The relay now keeps what it actually observed. On a real exit, and on the
liveness probe that finds a pid gone, it remembers {code, incarnation} in a
bounded map and answers a later attach with SSH_PTY_EXITED instead of throwing
that knowledge away. That is first-hand, same-process evidence, and it is the
only answer that now maps to expiry.

A remembered exit for a DIFFERENT incarnation is not an answer about the caller's
shell, so a recycled id cannot report a stranger's death as its own. A crash
loses the map, which correctly reads as no knowledge rather than as death.

The carrier is the message text: the relay's error transport keeps only a message
and a numeric code, so a structured payload would not survive. It is deliberately
worded to avoid "not found", which older clients map to expiry.

Cost, stated plainly: against a relay too old to remember exits, a genuinely dead
shell is now unproven, so the pane offers the disconnected card instead of
replacing itself. That is the affordance's purpose, and it is the safe direction.

* fix(ssh): a remembered exit answers only the shell that asked for it

Review found three ways the new proof could be believed too easily.

A caller that names no shell was still handed a remembered exit. That is the same
double resume in a new costume: relay A is killed leaving pty-1 alive and
orphaned, relay B mints its own pty-1 and THAT one exits, and a pane carrying no
recorded identity would be told its shell is gone — then replace a process still
running. The expectation must now be present AND match. Panes with nothing to
compare get the disconnected card, which is the direction that cannot lose work.

The proof is also gated on the client declaring it understands it. What the host
answers reaches clients that predate the reply, and one of those reads an
unrecognised attach error as neither death nor recovery — a stranded pane. Older
clients keep the wording they already act on; nothing is lost, because they could
not have used the proof anyway.

And the match is anchored on the whole grammar rather than the token, with the id
and incarnation percent-encoded. A substring test would let any text that merely
quotes the token stand in for the relay's own observation.

Two callers that key on "already gone" now also accept a proven exit, so the
liveness-probe reap does not burn a retry before reaching the same conclusion.

The oracle for the first of these was itself vacuous: `toThrow` with a negated
asymmetric matcher passes whenever anything throws at all. It now reads the
thrown message, and reverting the guard reddens it.

* fix(ssh): the liveness reap proves nothing to a caller who named another shell

The remembered-exit route was fixed to require a present, matching expectation.
The liveness probe is the other route to the same claim, and it still answered
anyone: it fires when a pty EXISTS but its pid is gone, and under a given id a
replacement relay may hold a shell that is not the caller's at all. Its death is
then no evidence about a pane whose own shell may be running orphaned under the
relay this one replaced — and the reply authorizes replacing it.

Both routes now demand the same thing. The reap still happens either way, because
a dead shell should be cleared whoever asked; only the answer depends on whose it
was, and a caller who named a different shell is told exactly that.

Found by asking whether the guard ordering was right, after the first fix closed
only the half that had been reported.

* fix(ssh): the client checks whose exit the proof is about

Enforcement lived only on the host. But the host is the party whose answer is in
question, and mixed versions are the normal state — a host that applies the rule
loosely, or not at all, could hand back an exit for a shell the pane never owned
and the client would replace a process that is still running.

The incarnation travels in the proof precisely so the asking side can check it.
A proof that cannot be tied to the shell this pane asked about is not proof, and
falls through to the disconnected pane. A pane that knows no incarnation cannot
verify anything, so it does not get to act on one either.

Both halves now apply the same rule independently, which is what makes it hold
across versions rather than only when both ends agree.

* fix(ssh): fence the reconnect path too, not just the pane-driven restore

There are two client attach routes and only one was fenced. The pane-driven
restore goes through reattachSshPtySession, which was sending the shell identity;
the relay session's own reattach — the one that reconnects EVERY known pty when a
relay comes back — goes through attachForReconnect, which sent nothing.

That is the wrong one to leave open. A relay coming back is exactly when ids have
been reissued from pty-1, so the main reconnect was the likeliest place to attach
somebody else's shell, and it was attaching by id alone.

It now sends the identity the lease recorded, which is what the lease field added
earlier was for; the two halves finally meet. Pane identity is still not sent —
only the shell's own — so a pane that moved tabs is unaffected. It also declares
exit-proof support, so a proven exit can reach the path that reattaches after a
host restart.

Callers with nothing extra to say keep the older call shape, so this does not
churn every reconnect assertion in the suite over trailing undefineds.

* fix(ssh): actually write the shell identity the reconnect fence reads

The lease field was declared, preserved on load, and read on reconnect — and
never written. Both spawn writers omitted it, so every lease carried only
"pty-N", the reconnect always took the no-expectation path, and the fence added
for it could not fire. The main reconnect went on attaching by id alone, which
is the replaced-relay case the fence exists for.

Worse than inert: a successful unfenced attach durably binds the pane to
whatever answered, so the wrong identity would be recorded and carried forward.

The host attests the identity at spawn and it was already in scope one line
above both writers.

The oracle for this had to pin the WRITE. Every other clause — the type, the
loader, the reader, the reconnect forwarding — was green throughout, because
each was correct in isolation; only nothing joined them. The test that covers
the spawn now seeds a host incarnation and requires it on the persisted lease,
and removing either writer reddens it.

* refactor(ssh): one home for the exit-proof rule, and comments the house style allows

AGENTS.md asks for brief non-obvious comments, one line where possible. Several
of mine ran to five and eight lines of narrative on the relay's attach path,
which is the one place a reviewer most needs to scan the branching quickly. They
now say the same thing shorter.

Both gone-paths in attach() had independently spelled out the rule that proof
must name the caller's own shell. That duplication is what let the earlier fix
close one and miss the other, so the condition is now a single predicate both
ask — a change to the rule cannot reach one path and skip the other.

The renderer kept its own copy of SSH_SESSION_EXPIRED while this branch created
a shared home for exactly that token, whose whole reason for existing is that the
two copies once disagreed about an identity mismatch and the renderer respawned a
live shell. It imports the shared one now.

Not changed, after checking: the per-generation recovery budget still does not
reset on a successful reattach. Resetting it looks obviously right and is wrong —
a flapping PTY alternates failure and success, and a covering test drives exactly
that for forty rounds. The park cooldown already bounds the harm.

* fix(ssh): keep the pane fence for clients that cannot name a shell

Deleting the relay's pane-identity comparison disarmed the recycled-id guard for
every client that has not upgraded. The relay is shared and host-side: one person
updating a host would leave their colleagues attaching by id alone, with nothing
checking it in either direction.

It is back as a FALLBACK, used only when the caller sends no incarnation. A
client that can name the shell is still fenced on that and still attaches after
moving tabs; a client that cannot gets the older, coarser check it was already
living with rather than none at all.

The two clauses inverted when it was deleted are restored, because they send pane
identity with no incarnation — the old-client shape, which should be refused. The
moved-pane property they used to contradict is pinned separately by the clause
that sends an incarnation, and reverting the override reddens it.

* fix(ssh): a bare not-found must not retire a pane's owner

Retiring a stable pane's owner authorizes a replacement that carries the pane's
agent resume payload. Until this branch, an SSH reattach failure reached that
decision as SSH_SESSION_EXPIRED, which the gone-check did not match, so it never
fired for SSH. Retiring the not-found mapping changed that: the raw
`PTY "<id>" not found` now matches, so a replaced relay answering for a shell its
predecessor is still running would retire the owner, fabricate an exit, and
respawn with the resume payload — the double resume, reintroduced by the commit
meant to prevent it.

For an SSH pane the two proving answers are the relay's own observed exit and the
expiry the reattach mints only after verifying that proof names this shell. A
bare not-found is neither, and now propagates instead: the pane keeps its owner
and surfaces as disconnected.

Local and daemon ptys are unchanged — their provider owns its ptys, so absence
really is proof. The shutdown paths that also use the gone-check are untouched:
there, "not found" is the outcome being asked for.

The covering test drove the dangerous shape directly — bare not-found, retire,
respawn with `codex resume …`. It now drives the proof, and the bare not-found
case is pinned beside it.

* fix(ssh): retire a lease the relay proved dead

Reattach failure left every record untouched, including the one answer that
settles it. A shell the relay watched exit kept a live lease, so every later
reconnect fanned out an attach for it — two attempts and a ten-second deadline
each — and the set only grew, in a file written to disk.

A proven exit now retires the record. `terminated`, not `expired`: expiry is the
state the recovery grant reads, and retiring a record must not also authorise a
replacement.

Everything else is unchanged and still leaves the pane detached and recoverable,
which is the point — a not-found is also what a replaced relay answers for shells
its predecessor is still running.

* fix(ipc): one import of the incarnation module, not two

CI's code-quality plugins deny a second import of a module already imported in
the same file; the pre-commit hook runs a different oxlint config and did not
see it. Both failing checks were this: `verify` is a gate that only reported
static analysis, with typecheck, tests and both package jobs already green.

* fix(ssh): harden PTY reattach reliability

* fix(persistence): fence duplicate lease rollback

* test(pty): pin incarnation write fence

* fix(ui): center narrow terminal recovery actions

* fix(ssh): make the unreachable-pane state reachable, and its actions work

The decisive cases for this affordance have sat at `fixme` because the state was
not inducible: the card needs the SSH target CONNECTED while exactly one pane's
attach fails without proving the shell gone, and every host-side fault takes the
whole connection down instead. So the behaviour was only ever argued from
reading, which is how several oracles here ended up green for the wrong reason.

It is inducible now, using the fence this branch added for another purpose: the
relay refuses an attach whose expected incarnation names a different shell, which
is per-pty and leaves the connection healthy. Rewriting a pane's recorded
identity while the app is closed reproduces it deterministically.

Running it immediately found two defects that reading had not:

The error toast painted over the card. It renders at z-50 in the same bottom
strip and was suppressed only for the connection overlay, not for the pane's own
card — so in the one state this affordance exists for, BOTH its actions were
unclickable.

"Start a new terminal" then did nothing at all: no shell, no host change, card
straight back. It routes through the path that resolves the pane's owner and
attaches it, and the owner is the very shell we cannot reach — so the attach
fails and nothing is created. The action now refuses adoption, which is what
makes it a creation. Nothing is killed; the old shell stays alive and unbound.

Honest status: the gate is NOT green. The card now clears and the action runs,
but shell creation is not yet observed reliably across runs. Committing so the
oracle and both fixes are not lost; the remaining failure is the next work.

* fix(ssh): a session id is the instruction to attach, so a refused adoption drops it

Skipping stable-pane owner resolution in main was not enough: the action still
sent the pane's recorded sessionId, and the provider reattaches on that before
any owner logic runs. So "Start a new terminal" kept attaching the very shell it
could not reach, and created nothing.

The id is now dropped at the last gate before the IPC, where it cannot be
reintroduced by a caller that forgets.

Also records what running the gate has established so far, including the one
defect still open: with both fixes in, the click still produces no spawn at all
(visible=true launches=1 shells=1), while the main log over the same window shows
only the pane's own restore retries. The evidence points at the action closure
belonging to a superseded connection, not at the spawn path — so the next step is
to instrument the handler rather than add a third spawn-path guard.

* docs(ssh): locate the remaining defect — main re-derives the session id

Instrumented the handler, the transport and main in one correlated run. The
closure hypothesis was wrong: the handler runs, the connection is live, and the
renderer half is correct — it sends no session id and asks for adoption to be
refused. Main re-derives the id anyway, attaches the unreachable shell, and the
spawn rejects, so the action resolves null and the card returns.

That narrows it from "a renderer race" to one gate in main:
createFreshShellForUnreachablePane covers only the early owner resolution, while
a second site downstream still passes sessionId: owner.ptyId to the provider.

Recorded with the evidence and the shortlist of call sites, plus the instruction
to gate where the owner is CONSUMED rather than adding a third condition at a
third producer — this is the same rule leaking at a third site, which is the
signature this branch keeps producing.

* fix(ssh): refuse adoption where the owner is consumed, not where it is derived

The unreachable pane's "start a new terminal" still attached the shell it could
not reach. The renderer was already correct — instrumenting handler, transport
and main together showed it sending no session id and asking for adoption to be
refused, while main re-derived the id anyway.

The rule had been applied at the two places an owner is PRODUCED and missed at
the one place it is CONSUMED: spawnForStablePane turns an owner into `sessionId`
for the provider, which is what makes an attach an attach. Gating there closes it
for every producer at once.

The decisive E2E now passes: with the target connected and one pane unreachable,
the action creates exactly one shell, leaves the unproven old shell running and
unbound, and clears the card. Reverting the single condition reddens it.

This rule leaked at three sites in a row and each fix was necessary while none
was sufficient. The one that held was placed where the value is used.

* refactor(terminal): the same-id guard now protects a new shell, not an adoption

Refusing adoption removed the case this guard was written for. What remains is
the opposite: a reset relay can reissue the old id to a genuinely NEW shell, and
main has already bound the pane to it — so clearing by that id would unbind the
shell just created. Same code, and it is still needed; the comment said the wrong
reason, which is how the next reader deletes it.

This also closes the planned "tell the user we recovered your terminal" work as
obsolete: there is no silent recovery left to announce, because the action now
always creates.

---------

Co-authored-by: Orca <help@stably.ai>
2026-08-13 01:36:01 -07:00
Neil 501337454c perf(runtime): stop rescanning every repo every 30s with a Git-admin fingerprint (#14207)
The main-process worktree resolution cache expired on wall-clock time: the whole-fleet snapshot has a 1s TTL, so any poller faster than 1Hz recomputed it, and every 30s the per-repo scan cache expired and shelled out `git worktree list` for every registered repo. A production trace recorded 4,272 `git worktree` invocations over 3h27m across 10 repos.

In-Orca mutations are already event-driven, so the 30s TTL existed only to discover changes made outside Orca. Before re-running an expired scan for a local, non-WSL repo, read a cheap subprocess-free Git-admin fingerprint (admin dir entries, per-checkout HEAD and its ref tip, gitdir/locked/existence per entry, packed-refs and reftable stamps). If it matches the fingerprint captured at the cached scan's start, extend the cache without spawning Git. A real scan still runs every 5 minutes so anything the probe cannot see still reconciles.

Measured: 600 -> 60 `git worktree list` spawns on the reported workload (10 idle repos, 1Hz polling, 30 simulated minutes), and main-thread event-loop stall of 2.69ms -> 0.01ms per refresh. External worktree add/remove/move/lock/checkout/commit discovery stays bounded at 30s.

SSH repos, WSL-routed repos, folder workspaces, agent-scratch repos, and any repo whose layout the probe cannot read keep today's behaviour exactly.

Design: docs/reference/worktree-scan-fingerprint.md
2026-08-13 01:01:33 -07:00
erish 1192f73f4d docs(i18n): sync Korean README with current content (#14124) 2026-08-12 17:32:36 -07:00
github-actions[bot] ad6f8011e2 Update README downloads badge 2026-08-12 09:33:52 +00:00
Neil 9c091cf77e chore(perf): add renderer agent-status benchmark harness (#13905)
Splits run-idle-cpu-benchmark.mjs into a scale fixture, an in-page timing
probe, and process sampling, and records a measured origin/main baseline so
the agent-status batching slice has an auditable before.

The agent-status write workload is not included: it needs setAgentStatuses,
so it lands with the store slice.
2026-08-12 00:37:48 -07:00
Jinjing 97ebfd9b81 fix(cmd-j): improve keyboard selection visibility in light mode (#13855)
Use color-mix to blend selection highlight instead of flat accent, making the keyboard cursor visible on light popover surfaces in both light and dark modes. Fix race condition in selection handling where deferred query lag could break arrow navigation by always accepting cmdk's internal cursor updates.
2026-08-11 12:31:30 -07:00
Brennan Benson 915ee50cc2 fix(ui): rename Caffeinate Auto mode to Agent (#13751)
* fix(ui): rename caffeinate auto mode to agent

* fix(ui): center caffeinate radio indicator

* fix(ui): center caffeinate indicator within option
2026-08-10 23:50:41 -07:00
Brennan Benson 4dcb410982 docs: remove restored shell validation report (#13759) 2026-08-10 23:49:38 -07:00
Brennan Benson 7250fde148 fix(codex): repair hook trust before restored shells reconnect (#13745)
* fix(codex): reconcile hooks for restored shells

* docs: move restored shell validation report

* perf(codex): gate retained pane inventory
2026-08-10 23:47:32 -07:00
Neil 1979f5a3e3 refactor(linear): remove replaced team combobox (#13506) 2026-08-10 20:25:16 -07:00
github-actions[bot] 1c1107fc9b Update README downloads badge 2026-08-11 00:33:35 +00:00
Brennan Benson d50adec2d2 feat(ai-vault): isolate scanning from terminal workloads (#13411)
* feat(ai-vault): isolate scanning in service processes

* fix(ai-vault): retire idle service processes

* fix(ai-vault): discard unverified cache processes

* fix(ai-vault): clear relay sidecar cancel watchdog on acknowledgement

A cancelled relay call is settled before its 2s cancel watchdog is armed, so the acknowledgement path bailed out of settle() before clearing the timer. The watchdog then faulted a healthy sidecar two seconds after every aborted scan, killing whatever request had since become active.

* fix(ai-vault): clear the pending restart before scheduling another

recordFault overwrote this.timer, stranding a restart that dispose() could no longer cancel.

* refactor(ai-vault): drop the orphaned first-prompt IPC wrapper

session-first-user-prompt-handler.ts now owns this entry point and routes through the service; the copy left in the read module had no callers.

* fix(ai-vault): retry a faulted cold start before surfacing it

A slow first start surfaced a raw 'did not become ready' error to the caller even though the supervisor was already respawning. Requeue an unsent call once onto the scheduled respawn instead.

Also stop arming the cancellation watchdog for a call the child never received: no acknowledgement is coming, so it killed a healthy service and stalled the lane.

Invalidation bookkeeping and ready-waiter construction move to the state module to stay under the max-lines cap.

* fix(ai-vault): give relay title reads their own lane

Before this branch the relay read title files directly, concurrently with scans. Routing both through one sidecar lane put title resolution behind a list scan that may run up to 130s, so SSH tab titles could lag minutes behind.

Split cache and interactive lanes in both the relay client and the sidecar entry, mirroring the desktop service.

Also: clear the ready deadline on fault, so a sidecar that dies before ready cannot fault its healthy replacement five seconds later; retry an unsent call once across a respawn; and skip the cancellation watchdog for a call the sidecar never received.

Restart/circuit bookkeeping moves to its own module, mirroring the desktop policy, to stay under the max-lines cap.

* fix(ai-vault): degrade relay title resolution on sidecar failure

listSessions already returns a host issue when the sidecar is unavailable; titles propagated the raw RPC error instead. Return no titles so callers fall back to preview text, and keep cancellation propagating.

* fix(ai-vault): scrub the service child environment

The children are forked with a 384 MiB heap cap and no loader, but both
spawn sites handed them the full parent environment, so an exported
NODE_OPTIONS silently raised the cap or --require'd code into them.

Allowlist both, following the plugin worker. The desktop child keeps the
eleven agent-root overrides it resolves its own roots from; the relay
sidecar takes remoteHome and hostPlatform from its init message and so
needs none of them. Both children share one priority module while they
share this one.

* fix(ai-vault): soft-disable relay vault when the service is missing

A missing service threw out of the constructor, so a Vault wiring bug
would abort relay startup and take every PTY on the host with it. The
unsupported-platform branch three lines above already treats a Vault
failure as a soft disable; do the same here.

Threading the service through the two handlers instead of a field also
retires the definite-assignment assertion the throw was propping up.

* fix(ai-vault): drain consumed cache invalidations

invalidatedPaths was re-applied in every request's finally and never
drained, so once N paths had been invalidated every later request paid N
evictions for the life of the process; the 4096 cap only bounded how bad
that got.

The re-apply exists to cover a read that overlapped the invalidation, so
drain once nothing is executing. Clearing unconditionally would drop the
re-apply for a request still running on the other lane.

* fix(ai-vault): keep a busy child through slow invalidation acks

invalidate() reused the 5s ready budget as its acknowledgement deadline
and killed the child on expiry, so a delete issued during a large scan
could kill a healthy process mid-scan and burn a slot toward the restart
circuit.

Fault only when nothing is executing. Fork IPC ordering already puts the
invalidation ahead of any later request, so a busy child owes no ack
here, and the 130s/15s request deadlines still catch a wedged one.

The start-retry predicate moves to the state module to stay under the
line cap, matching the shape the relay client already uses.

* fix(ai-vault): report a failed local scan as a host issue

A local-scope scan let its error escape to the renderer, which paints it
over the session list. Service supervision now produces those errors, so
"AI Vault service restart circuit is open." replaced the list.

Route local scope through the degradation the all-hosts leg and every SSH
leg already use, so it lands as a retryable host issue row instead. Same
result shape either way, so no IPC or wire contract changes.

* test(ai-vault): cover the relay restart circuit transitions

The relay policy shipped without tests. Pin both circuit edges, the
aging-out case, the forced-refresh reopen the relay has and the desktop
does not, and the backoff schedule.

* fix(ai-vault): keep the OpenCode roots in the service child env

The scrubbed allowlist dropped XDG_DATA_HOME and OPENCODE_DB, which the child
reads to locate the OpenCode store and database. The pre-PR worker thread
inherited them, so a user who sets either lost every OpenCode session.

* test(ai-vault): anchor the service spawn env assertion
2026-08-10 15:52:59 -07:00
Neil 6cdd019367 docs(mobile): keep Android links on published release (#13565) 2026-08-10 02:22:35 -07:00
Neil bbcf89e221 chore(mobile): prepare 0.0.43 releases (#13549) 2026-08-10 01:49:33 -07:00
Jinjing 8331fe5995 docs: update GitHub star history chart (#13380)
Refresh README star history graphic to the latest ~40K stars curve (through August).
2026-08-09 15:17:11 -07:00
NeilandOrca 17cfc968cf Revert the terminal IME composition-ownership change (#13282)
* Revert "test(ime): restore coverage the composition-ownership change removed (#13168)"

This reverts commit 25a8c517e1.

* Revert "refactor(terminal): return IME composition ownership to xterm (#13128)"

This reverts commit 17b3dff3c4.

* test(ime): keep the architecture-neutral Korean trace coverage

The recorded IBus/fcitx5 and Windows MS-Korean traces from #13168 assert PTY
byte order, not composition ownership, so they still hold once the terminal
composition layer is restored. The mobile accessory-order test pinned the new
handleLiveInputChange signature and does not.

Co-authored-by: Orca <help@stably.ai>

* fix(terminal): keep the macOS Backslash bypass through the revert

The restored native-text forwarder only claims keys for input sources in its
hardcoded CJK allowlist, so third-party IMEs off that list (Qingg, #10896) still
get a raw backslash. #13128 added this bypass as a partial replacement; keep it
rather than trade the open issue back.

Scoped to the bare backslash key. The rest of shouldBypassXtermForMacNativeText
bypassed all unmodified non-ASCII text, which would race the restored forwarder.

Co-authored-by: Orca <help@stably.ai>

* fix(mobile): move the mirror-step ref write out of render

The restored hook assigned runMirrorStepRef during render, which is not
replay-safe — React can discard render work, so the mutation can leak from UI
that never commits. Its only read is inside the held-commit timer, which fires
long after commit, and the ref has a safe default, so an effect is soon enough.

Surfaced by the changed-lines React Doctor gate: the rule postdates this code,
so restoring the file re-introduced it as a new violation.

Co-authored-by: Orca <help@stably.ai>

---------

Co-authored-by: Orca <help@stably.ai>
2026-08-08 19:06:50 -07:00
github-actions[bot] 54a9b5840b Update README downloads badge 2026-08-08 12:28:05 +00:00
NeilandOrca 17b3dff3c4 refactor(terminal): return IME composition ownership to xterm (#13128)
* fix(terminal): return IME composition ownership to xterm

* fix(mobile): derive terminal input from native replacement ranges

* test(mobile): record iOS Japanese IME traces

* fix(mobile): preserve native IME replacement ranges

* fix(xterm): flush queued application input after IME commit

* test(terminal): pin Korean intermediate commit

* test: pin Windows IME shortcut ownership

* test: replay IBus number candidate commit

* fix: preserve native macOS input-method punctuation

* refactor(terminal): remove stale mac focus override

* fix(mobile): preserve soft keyboard deletion ranges

* fix: keep IME-owned palette chords in renderer

* fix: stop carried IME shortcuts at renderer owner

* fix: preserve carried IME shortcut dispatch

* fix: narrow main-owned shortcut actions

* test(mobile): pin Japanese IME replacement traces

* test(terminal): retain paired native IME trace

* fix(chat): preserve browser IME composition ownership

* fix(chat): retain macOS IME confirm gesture

* fix(chat): expire unmatched IME confirm carry

* fix(chat): isolate IME confirmation expiry

* fix(chat): retain active IME confirmation

* refactor(terminal): remove dead composition handler

* feat(ime): add shared Enter-ownership seams for CJK composition

The confirming Enter of a CJK composition arrives as two keydowns and the
orderings differ by platform: Windows/Linux redispatch the unmarked Enter/13
before keyup, macOS delivers keyup first. A guard reading only isComposing or
keyCode 229 misses the redispatch, so surfaces submitted on a confirm.

Adds useImeEnterGestureOwnership (carry token, next-frame expiry), a shared
ImeEnterGuardedForm for native implicit submission, and the cmdk seam covering
18 CommandInput surfaces at one site.

A chorded Enter arms the carry but is never swallowed — the reverse would eat a
user's deliberate Cmd/Ctrl+Enter. Both failure modes are pinned by
ime-enter-gesture-ownership-contract.test.ts.

Co-authored-by: Orca <help@stably.ai>

* refactor(terminal): consolidate native input listeners and parked-screen owner

Extracts the shared native-input listener installer and renames the parked-screen
detector for what it actually does, replacing per-call-site duplication. The
listener installer keeps a forgetOptionKeyLocationOnBlur flag so per-window
semantics are preserved rather than flattened.

Net deletion; no behaviour change intended.

Co-authored-by: Orca <help@stably.ai>

* test(terminal): pin recorded IME shapes as regression tests

Nine regression tests built from hashed affected-platform captures, each with a
paired ordinary negative and a discriminating mutation verified to take the file
from all-passing to exactly one failure.

Covers the Windows MS-Korean Shift family (#12179, #11878, #12151, #11946,
#12152) and the Korean TUI line-break rows (STA-3237, STA-3222, STA-3129).

STA-3237 pins the empirical 3-Shift / 2-active-composition / 2-newline ratio the
device run established — the third Shift produces nothing because Space has
already committed. That ratio is not derivable from a static capture.

Co-authored-by: Orca <help@stably.ai>

* fix(ime): guard Enter-commit surfaces against CJK confirm

Applies the Enter-ownership guards across the surfaces whose Enter commits
something: publishes, clones, pairs, installs, posts, or persists.

Tiered deliberately rather than uniformly. Irreversible and remote-effect sites
take the carry token, which also blocks the unmarked redispatch. Locally
reversible sites take the oracle check with a one-line comment naming the
residual, because a spurious commit there costs one undo.

Three numeric fields are left unguarded with the reason in-code: Chromium blanks
number inputs at compositionstart, so a confirm-Enter only ever reaches an
empty-draft reset. Measured with a CDP probe rather than assumed — a guard that
cannot fire is noise.

Co-authored-by: Orca <help@stably.ai>

* test(ime): teeth-check the Enter guards on every guarded surface

One suite per guarded surface, each verified by deleting the guard and
confirming the test fails. A green guard test without that check is unverified,
not verified.

Two shapes pass vacuously in happy-dom and are avoided here: native implicit
form submission never fires, and blur() is inert on an unfocused element. Both
made "the commit did not happen" assertions pass with the guard removed, so the
suites assert the guard's contract directly instead.

Co-authored-by: Orca <help@stably.ai>

* fix(mobile): keep iOS Korean commits whole through the live-input path

iOS Korean reports isComposing: false on every event, so it bypasses the
composition guard entirely. The strict owner rejected UIKit's transformed
post-change field and sent only the leading jamo — the reported symptom.

Prefers the authoritative same-event field text over the predicted text when the
supplied operation cannot produce it. Generic: no Korean special-case, no locale
classifier, no normalization. Adds the RN-target-keyed submit carry alongside it.

Co-authored-by: Orca <help@stably.ai>

* test(e2e): make IME capture harnesses fail loudly instead of silently

Four instruments recorded silence as success, so a void run scored as a clean
one:

- readTerminalImeBoundaryTrace returned an empty trace when the probe never
  installed, making every "nothing leaked" negative pass vacuously
- summarizeLatencies([]) returned a perfect zero distribution that passed all
  three latency thresholds
- the macOS Vietnamese spec pinned an input-source ID that does not exist, and
  failed as though the operator had chosen the wrong source
- the expectedLineCount=1 prefix property was undocumented and one edit from
  silently downgrading a PTY assertion

Input sources now resolve by enumeration and name the near-matches on failure.

Co-authored-by: Orca <help@stably.ai>

* test(terminal): cover Cangjie cancellation and fix a cross-namespace assertion

Adds #11951's recorded Cangjie cancel shape to the existing cancellation suite,
which covered Pinyin and Sogou but not Cangjie. One keystroke then Backspace
arriving as deleteContentBackward with data: null, so the stale preedit is the
only thing a fallback could replay.

Verified against the historical pre-6cd944c62b3 bundle: the positive fails with
['尸'] where [] is expected, while the ordinary negative stays green.

Also fixes the Vietnamese spec, which asserted a TIS-space input-source ID
against getKeyboardInputSourceId(). Those two Orca APIs report the same source
in different namespaces — TIS nests it under VietnameseIM, the app API does not.
The resolver stays as an installation precondition; the assertion matches the
leaf.

Co-authored-by: Orca <help@stably.ai>

* test(e2e): add a real-IME macOS arm for the Korean chord commit

The existing korean-ime-terminal-shift-enter-commit spec synthesizes composition
over CDP: Input.imeSetComposition sets the preedit directly and Input.insertText
performs the commit. Asserting the IME produced events you injected yourself is
circular, so that spec cannot certify real-IME behaviour.

This arm selects 2-Set Korean via TIS, reads it back live, and injects through
System Events key codes, so the OS owns the preedit, the commit instant, and
isComposing. PTY byte expectations are preserved verbatim.

Covers 2 of the original 4 cases by design. The other two are the Windows/Linux
redispatch-before-keyup ordering, which macOS cannot produce and which cannot be
selected -- the OS decides it. Reintroducing synthesis to "restore coverage"
would reintroduce the circularity.

Co-authored-by: Orca <help@stably.ai>

* test(e2e): assert the macOS chord arm at the PTY boundary, not the renderer

The byte expectations were transcribed from korean-ime-terminal-shift-enter-commit
:364/:383, which assert against onData -- a renderer boundary where the terminator
is CR. This spec reads the PTY child, where the tty has already converted CR to LF.

Names both forms per row rather than swapping the constant, so the conversion reads
as evidence that the capture reached past the renderer, as #11936 and #11951 record.
Ctrl+Enter's CSI-u sequence is unaffected and is identical at both boundaries.

Co-authored-by: Orca <help@stably.ai>

* test(e2e): measure composer-to-onData latency and stop dropping IME keystrokes

Two defects in the echo latency probe.

It hooked onWriteParsed and onRender but never onData, so it measured
key->parse->render echo rather than the composer-vs-onData delta the latency rows
need. Adds a third hook feeding its own sample set.

And `event.key.length !== 1` silently dropped IME keystrokes: Pinyin and Cangjie
keydowns arrive as key:'Process' (length 7). Replayed over the captured corpus,
the old filter accepted 580 of 4137 Chinese IME keydowns -- it was discarding 80%
of them. The new filter matches the shape the owner itself branches on.

Attribution charges each onData to the latest keydown rather than a FIFO head,
because composing jamo emit no onData at all and a queue would credit a whole
composition to its first keystroke. The consumer now asserts sample count before
any percentile, so a zero-sample run cannot render as a flawless distribution.

Co-authored-by: Orca <help@stably.ai>

* test(terminal): pin the WSL shifted-jamo newline shape for #11919

In Korean 2-set, Shift types ordinary letters -- the double consonants and the
compound vowels. Each such keystroke reaches Chromium as key='Process',
keyCode=229, shiftKey=true.

The v1.4.163 classifier matched exactly that pattern with no code guard, so it
called those keystrokes Enter, rewrote them to a synthetic Shift+Enter, and
injected a newline into the middle of the word -- with no Enter key pressed.
That is why the reporters said "no modifier key pressed": they had not chorded
Shift+Enter, but they had pressed Shift, to type the double consonant.

Asserts the row's own recorded capture: 40 immediate keydowns, exactly 3 of them
Shift-carrying inside a single syllable, and an onData stream with one newline
per Enter press and none mid-word. Two ordinary negatives keep it from being a
blanket mute -- the same session's non-IME keydowns still reach shortcut policy,
and an ordinary Shift+Enter still resolves through the real policy.

Co-authored-by: Orca <help@stably.ai>

* test(terminal): pin the composition commit lag that made Korean type one behind

macOS Korean 2-Set commits syllable N only when the first jamo of N+1 arrives, so
compositionend and compositionstart land in the same task. A composition-start
handler cancelled the pending finalizer that was the only path to triggerDataEvent
and ended the session without emitting bytes, so every committed syllable reached
onData exactly one syllable late and the backlog cleared only at a Space or Enter.

Types continuously with no Enter and no Space -- either would flush the backlog and
hide it -- and samples onData at every syllable boundary. Paired with a
length-matched ASCII arm that stays green throughout, so the positive is a fact
about composition rather than about timing in general.

Bisected to a single call site across five builds: pristine, 1.4.155 and 1.4.162
pass, 1.4.163 fails, removing the one call repairs it, restoring it fails
identically. That window is exactly the reporter's "started immediately after
updating".

Co-authored-by: Orca <help@stably.ai>

* test(mobile): cover the send-queue abort that silently drops queued keystrokes

One failed send in use-terminal-live-input-commit aborts every keystroke
queued behind it, with the error swallowed by .catch(() => false). The
existing test resolves(true) on every send, so the failure branch was
uncovered.

Four arms: the abort itself, an ordinary negative on the healthy path, a
throwing sender, and a liveness control proving the queue recovers once
the chain settles. Deleting the abort takes 4 passed to 3 failed, with the
ordinary negative correctly surviving.

Scope is stated in the docblock: this is a transport send-queue abort,
reachable only via a real disconnect or RPC error. REQUEST_TIMEOUT_MS is
30s, so latency alone cannot reach the branch — consistent with #7094's
symptom class, not proven to be its cause.

* test(terminal): pin that daemon snapshot/restore cannot disturb a composition

Two independent reporters attributed broken Korean composition to the
always-on PTY daemon repainting terminal state over the preedit. The
attribution is wrong on ancestry — the daemon shipped three months before
the version both call good — but the boundary was never actually tested.

Runs the real applyMainBufferSnapshot choreography against a live
composition, including the full 2J/3J/H wipe plus the resize and
alt-screen branches. textarea.value, selectionStart/End,
compositionView.textContent and .active all survive byte-identical, and
interleaving a restore between every jamo of 문제 still commits 문제 at
onData. Also pins that the uncommitted preedit is absent from the captured
snapshot: it lives in the textarea, never the buffer, so a restore has
nothing stale to echo back.

Injecting one textarea.value = '' into the restore fails exactly the three
restore-boundary tests.

* test(terminal): pin that Cmd tears down a composition where Ctrl and Shift do not

xterm's composition keydown exempts only keyCode 16/17/18 (Shift/Ctrl/Alt)
plus 20/229. macOS Meta — 91/93/224 — is absent, so a Cmd press mid-composition
takes _finalizeComposition(false): the overlay goes dark and never recovers,
because compositionstart is not re-fired. The user composes the rest of the
word blind. Linux and Windows users press Ctrl and are exempt.

xterm already has a Meta-aware modifier predicate in wasModifierKeyOnlyEvent,
so this is an internal inconsistency rather than a deliberate choice.

Owns no reported row and is version-neutral: 5/5 on both 1.4.162 and 1.4.163.
The branch is unexercised in all 328 recorded traces, so this is a hazard pin,
not a regression guard. Only the teardown is asserted; the likely duplicated
commit needs a compositionend the IME kept alive across the Cmd, which no
capture contains.

Deleting the exemption fails exactly the three paired negatives; adding Meta
to it fails exactly the two Cmd arms.

* test(native-chat): characterize preedit loss when a question card replaces the composer

An AskUserQuestion card fully replaces the composer by design, but the
in-flight composition goes with it: the composer unmounts before
compositionend reaches it, so the preedit is never committed to the draft.
The committed text survives only because the draft is cached and restored
via defaultValue. Node identity changes, value 'abc' is preserved, the 가
is gone.

Drives the real NativeChatView -> SessionGate -> InteractiveCard ->
questionActive swap -> Composer -> ComposerField, flipped by writing the
same store field an AskUserQuestion hook event writes. Flipping
questionActive to false fails exactly this test and nothing else across
639 native-chat tests, so the path was entirely unguarded.

CHARACTERIZATION TEST: it asserts the loss. Fixing the defect — committing
the preedit before the swap, or keeping the composer mounted — will make
this file fail. Update the expectations to the new contract rather than
working around them.

Owns no reported row. #12118/STA-3219 flicker is keyed to token counters,
which provably do not remount, and a question card arrives once per
question.

* test(terminal): pin the duplicated commit when Meta interrupts a composition

_finalizeComposition(false) sends textarea.value.substring(start, end) but
cannot clear the IME-owned textarea, so a later compositionend re-sends the
same range. Meta reaches that path because CompositionHelper exempts only
Shift/Ctrl/Alt; xterm's own wasModifierKeyOnlyEvent covers Meta four ways,
so the omission is an internal inconsistency rather than a choice.

Companion to the modifier-exemption guard, which deliberately pins only the
overlay teardown. This pins the data consequence.

HAZARD PIN: owns no reported row. The trigger is unverified on hardware —
no capture in the corpus contains a Meta-during-composition gesture, and
whether macOS keeps the composition alive across it is unmeasured. The
duplication follows from the code given that sequence; whether users reach
the sequence is the open half.

An earlier premise that Space (keyCode 32) reaches this path was refuted by
a corpus scan: 0 of 731 evidence files carry a keyCode-32 Space while
composing, against 171 at 229, and 229 returns early.

* test(terminal): characterize the syllable lost when the textarea blurs mid-composition

CoreBrowserTerminal._handleTextAreaBlur clears the helper textarea
unconditionally — "Text can safely be removed on blur" — while
CompositionHelper._finalizeComposition reads the committed text back out of
that same value from a deferred timeout. By the time it runs the value is
empty, the substring is '', and triggerDataEvent never sees the syllable.
xterm checks composition state in _syncTextArea and omits the same check
here.

Six cases. Blurring mid-composition loses the syllable in every ordering,
including compositionend-before-blur, which is Chromium's real order — so
it is not an ordering artifact. A bare textarea.blur() with no Orca code
loses it too, which places the owner upstream: Orca's unguarded release on
outside pointerdown is one trigger, not the cause. Committing 한 then
blurring mid-가 yields ['한'] where ['한','가'] is correct: one syllable
gone, surrounding text intact.

Teeth checked by inverting — adding an Orca-side composition guard flips
exactly the three cases that route through the release path and leaves the
bare-blur and no-blur cases green, which is the scope split: a fix in
regular-terminal-focus-ownership alone would not close this.

HAZARD PIN, but unlike the others this one has a real production injector —
clicking outside the terminal mid-composition. Owns no reported row. The
shape matches #9738's report; the injector does not, and a shape match with
a mismatched injector is not an owner.

* test(terminal): say which arm the STA-3237 fixture came from

The recorded keydowns are wave 4's A-shift-unmarked-only — the arm that
emits no PTY bytes. Nothing in the file said so, so two readers concluded
the row's events fail the owner's predicate and that STA-3237 and STA-3222
were different defects. They share an owner; the arm that fires is
Process/229+Shift, absent from this bubble-phase trace because the owner
claims it in the capture phase.

Also corrects "code-blind": the v1.4.163 policy emits \x1b\r only for a
shift-only key:'Enter', and a jamo keydown reaches that branch solely via
the isTerminalImeProcessEnter rewrite. The mock is deliberately wider so
the ownership guard stays under test if that rewrite moves.

Comments only — no assertion, fixture value, or mock behaviour changed.

* test(e2e): track the input-source selector the macOS specs shell out to

Five tracked macOS IME specs ran `swift .tmp/select-input-source.swift`, a
file that is gitignored and existed only on one machine. Anyone else
checking out the repo — or the same machine after .tmp is cleaned — could
not run them, and they are the capture drivers for the macOS rows that are
blocked waiting for exactly those runs.

Moves it to tests/e2e/ beside its callers. The chord spec now resolves it
from __dirname rather than reaching two levels up into .tmp.

* test(terminal): pin the CJK repaint decision against the reporter's own output

#12164 comment 1 and #5921 report agent output with double-width glyphs
rendering duplicated character-by-character while ASCII in the same line
stays clean. No IME, no composition, no keystroke — the user never types
the CJK.

Segmenting all three verbatim samples into maximal same-risk-class runs
gives 33 runs and zero violations of "this run is corrupted iff the
production detector flags it": 17 wide runs all corrupted, 16 narrow runs
all byte-identical. The paired negative is co-located in the same line
rather than in a separate run — the reporter supplied it without knowing.

Doubling is asserted as present, not uniform: 자바스크립트 and 시스템 each
leave a jamo undoubled, which is a repaint-region boundary artifact rather
than a per-character transform.

The discriminating arm is in the test rather than a source mutation:
be3f30e2f8 (#6890) elects a repaint for all 17 corrupted runs when the
agent types nothing, and reverting its disjunct elects none. Both
predicates agree once the user has recently typed, which is the pre-#6890
condition.

Samples inlined with per-sample SHA-256 because .tmp is gitignored and
cannot back a landed test.

* test(terminal): pin macOS period substitution landing after the composition

#11504's reporter published a DOM trace showing insertText ". " arriving
149ms after compositionend, when two spaces are typed with a CJK input
source and NSAutomaticPeriodSubstitutionEnabled is on. This replays that
trace against a real Terminal and asserts what reaches onData — bytes to
the PTY, not anything visual.

The owner is stock upstream CoreBrowserTerminal._inputEvent, not an Orca
module, confirmed at the resolved install and in the shipped bundle Vite
loads rather than in the TypeScript source.

Three mutations against that install, predictions written before the runs,
each failing exactly the arms predicted: dropping the composed/keyDownSeen
guard fails two, dropping Orca's intercept fails the one arm where the
payload arrives before the send window drains, and flipping || to && —
the candidate-fix shape — fails the arm that pins the defect itself.

CHARACTERIZATION: arm 1 asserts the broken behaviour and will fail the
moment #11504 is fixed. Update it to the new contract rather than working
around it.

composed is absent from every recorded bundle, so composed: true is the
spec-required value rather than a captured one; the test asserts it before
dispatching so a harness that dropped the field fails loudly.

* test(terminal): replay the recorded Windows Shift sessions through the IME guard

STA-3179 reports a Shift release sending Enter; #12171 reports delayed
Hangul plus doubled newlines. Both replay their own recorded Windows
MS-Korean keydowns through resolveTerminalKeyboardShortcutAction with the
shortcut policy mocked, so the assertions are about which events reach the
policy and what reaches terminal input.

STA-3179's held-Shift gesture yields exactly one newline, from the unmarked
Enter alone; its release arms nothing for the next composition, asserted
after a precondition check that the release really is keyups with shiftKey
already dropped; and an ordinary Shift press-and-release still routes every
keydown, which is the paired non-IME negative.

Teeth, verified by mutation: bypassing the isImeOwnedKeyboardEvent guard in
keyboard-handlers takes STA-3179 from 3 passed to 2 failed / 1 passed — the
survivor being the ordinary-session negative, which is correct, since a
non-IME session should not depend on that guard — and #12171 from 2 passed
to 2 failed. Source restored byte-identical.

Recorded shapes are inlined and the bundles cited in comments; nothing is
imported from .tmp, which is gitignored.

* test(native-chat): correct 61977d4517 — the preedit survives the question card

61977d4517 claimed a composed syllable vanishes silently when an
AskUserQuestion card replaces the composer, and characterized that loss.
The claim was false. Its premise was an artifact of the harness: the test
simulated a preedit with a silent textarea.value assignment and no input
event, which no IME does.

Real composition fires input with insertCompositionText on every keystroke
— the shape this repo already records in its own observed-event capture —
and React's change handler returns on input/change with no composition
gate, so onChange runs for each frame. The draft cache is written
synchronously inside the updater, so the preedit is already committed
before the card can arrive. Driven that way, it survives.

Renamed to match the contract that actually holds, and extended: Hangul
jamo-per-frame, Japanese kana accumulation followed by per-segment
conversion asserting the candidate the user was looking at survives, and a
pin on the mechanism itself — the draft cache holds the preedit while the
card is up.

Teeth: there is no fix to revert, so the mutation is the plausible wrong
one — gating onChange on isComposing(). That takes 4 passed to 3 failed,
with the English negative correctly surviving, since it has no composition
to gate.

Two consequences remain, recorded rather than fixed: the OS aborts the
composition when the field disappears, so a lone jamo returns as a
compatibility jamo the user cannot compose onto, and the remounted
composer is unfocused because the card owned focus.

* docs(native-chat): name the corrected commit and the degraded-jamo consequence

Records in the file itself that 61977d4517 is pushed and wrong, quoting
the two claims that are false, so a reader who finds it in git log reaches
the correction from the file that replaced it.

Also states the residual as a consequence rather than a curiosity: a lone
leading jamo returns as a standalone compatibility jamo (U+3131), which is
not a composable state — the user cannot resume the syllable, only delete
and retype. Preserved, but degraded into something unusable. That is the
note to find if a reporter ever describes exactly that.

The invariant these tests pin is not "the composer commits on unmount" but
"composition input events must reach React" — which is what a future IME
change would break, and is not visible from the swap site at all.

* test(terminal): replay the recorded macOS Telex commit boundaries

#6905 reports Vietnamese composed characters breaking in the terminal.
Replays the retained macOS built-in Simple Telex capture — recorded
selection and value set before each dispatch, since that is what the
commit range reads — and asserts what reaches onData: the first commit
alone, then through the real Enter, then the ASCII tail of the same run.
A code-point count would catch NFD normalisation.

ENGINE CAVEAT, stated first in the docblock: this is macOS built-in Simple
Telex, Telex only. The reporter's three named engines cannot run on the
platform they declared, and which macOS Vietnamese engine they used is
unconfirmed. This file certifies no engine, and does not imply VNI.

The owner is upstream's — CompositionHelper._finalizeComposition's
waitForPropagation branch — so the arms are copies under .tmp aliased by a
scratch config, with node_modules verified unchanged by shasum after every
run. Collapsing the range end onto its start fails all three; collapsing
the start to zero re-emits the first word into the second commit, which is
the reporter's "duplicated" direction. Different failure sets, so the
mutants are distinguishable rather than merely detectable, and the ASCII
assertion passes under both.

Falsifiability here is by mutation, not by a defective build: #6905 does
not reproduce at HEAD, so this has never been watched going red on a real
reproduction.

* docs(terminal): lead the #6905 test with its engine caveat

Comment-only. Moves the caveat above the source line so a reader meets what
the file does NOT establish before what it does — the capture is macOS
built-in Simple Telex, the reporter's named engines cannot run on the
platform they declared, and which engine they used is what gates this row.

Co-authored-by: Orca <help@stably.ai>

* docs(terminal): record that the swallow eats a keystroke after Japanese conversion

This pin framed the swallowed insertText around Cmd interrupting a
composition. A differential through Japanese multi-segment conversion shows
it is broader: type a segment, convert, then press `a`, and the `a` is
lost. No modifier, no exotic gesture. Korean surfaced it first only because
2-Set composes on nearly every keystroke.

Also records why it cannot simply be fixed. The suppression de-duplicates
IMEs that deliver their commit a task after compositionend, which a sibling
test pins; this swallow is that dedup's false positive, and the two events
differ only in payload, so no flag-timing change separates them. Both a
smaller redesign and a content-aware variant were built and measured — the
first duplicates on IBus, the second costs a reported row's test and is
blocked while the patch cannot be regenerated.

The Japanese arrays behind this are authored, not observed: no Japanese DOM
composition trace exists in the corpus.

* docs(terminal): a Japanese capture does exist — correcting dbeecb11be

That commit said no Japanese DOM composition trace exists in the corpus.
False. One does, filed under the Linux bundles rather than the bundle named
for Japanese: 30 DOM events, two にほんご->日本語 conversions, with full
selection state per event. It is retained byte-identically in three further
bundles — one capture copied four times, not four observations, checked by
hash rather than by counting files.

The claim came from checking the bundle named for Japanese, finding nothing,
and generalising to the corpus without querying the rest of it.

Replaying it emits 日本語日本語 under both sequencing extremes on all four
arms, matching its own recorded onData. So "repeated conversion is
undisturbed" is now captured rather than authored. It carries no
post-compositionend insertText, so it cannot speak to the swallow: the
a-after-conversion figure stays authored and unobserved.

Also rewords the paragraph opener. It claimed to broaden a Cmd framing, but
hazard 2 was never Cmd-framed — the lines above already say Cmd does not
reach it. The real gap was that hazard 2 named no trigger at all, which
reads as exotic when it is ordinary.

* build(xterm): land the patch regeneration harness

The five dependency patches under config/patches/ shipped with no tracked
way to regenerate any of them. The xterm one is the hard case: it is derived
from an upstream build, so no fix could be made without rebuilding, and the
tooling to rebuild lived only in one machine's scratch directory. That
blocked a measured fix for a live keystroke-loss bug, and the EditContext
reduction an OSS survey identified as the only real one available.

Adds the regenerator, the upstream pin, the hand-written source patch the
bundle hunks derive from, tests, docs, and a PR job that verifies the
shipped patches still match the pinned build. The job caches the shallow
clone keyed on the manifest, so a cold run is minutes and a warm one under
one. Round-trip verified: regenerating from a clean checkout reproduces the
shipped patch byte-for-byte.

Marks the emitted patch -diff -text. pnpm hashes it byte-for-byte, so a
CRLF checkout would break install on Windows, and its minified bundle lines
make a diff nobody can read — review the source patch instead.

Also rejects unknown flags. --check was the fallback for any unrecognised
argument, so a typo, or --help, silently triggered a full upstream build
instead of what the caller asked for.

* fix(xterm): stop swallowing a keystroke typed after an IME commit

Type a Japanese segment, convert it, then press a key one macrotask later
and that key was lost. No modifier, nothing exotic — every user who keeps
typing straight after converting. Korean surfaced it first only because
2-Set composes on nearly every keystroke.

handleCompositionInput discarded the payload unconditionally in the window
after the deferred send: _isSendingComposition stays true for one macrotask
after the timer cleared _pendingCompositionStart, and the branch substituted
'' for whatever arrived. The suppression is not itself wrong — it
de-duplicates IMEs that deliver their commit an event-loop turn late, which
terminal-stock-composition.test.ts pins. It just could not tell a duplicate
from new input, because the two events are identical apart from payload.

Now it compares against _sentComposition, the text the deferred send
actually emitted, and discards only a match. A flag-timing redesign was
measured first and rejected: it fixed this and duplicated on IBus, because
no timing change can separate events that differ only in content.

Edited in config/patches/xterm-src/ and regenerated through the harness, so
the emitted patch and the lockfile hash are derived, not hand-written.

The commit-overlap pin's swallow arm now asserts the repaired contract —
the value its own comment already named as correct and as what stock
beta.287 emits. #11504's arm at :184 flips too; it never covered that
report, as its own prior note recorded, and the reporter's +149ms arm is
untouched and still asserting the defect. Provenance hashes in three test
docblocks are updated, since regenerating changes the patch hash and with it
the resolved install directory.

* docs(terminal): re-measure the #6905 mutation citations against the new bundle

Regenerating the patch moved the resolved install, so this docblock's
patch_hash, line count, two line numbers and three mutation outcomes all
described a bundle that no longer exists. The deferred branch is one the
fix writes into, so the outcomes could not be re-pointed on reasoning.

Line numbers read off both files by diffing anchors rather than derived by
arithmetic: 201 to 205, 159 to 163. Outcomes re-run through the retained
rig, which re-resolves through the module loader and re-derives each arm
from a unique minified anchor: pristine 3 passed, m1 3 failed, m2 2 failed,
m3 3 passed — identical to the old bundle. Guard controls in both
directions exit 1, so the counts are falsifiable.

Comment-only; the assertions and expectations are unchanged.

* fix(xterm): size the preedit overlay to the cells its text will occupy

updateCompositionElements computed the overlay's left edge from the grid
but never its width, so the preedit rendered at the font's natural advance
while the committed text takes two cells per wide glyph. Measured in
Chromium 150: 가나다라 drew 48.45px as a preedit and 69.20px once committed
— the same characters, same font, 30% narrower, and drifting further with
each syllable. Every macOS mono font carrying Hangul measured 0.49–0.72 of
two cells; never 1.0.

Deriving the width from wcwidth and the cell measure moves Korean, Japanese
and Chinese to 1.000 and leaves ASCII at 1.000, which it already was:

  한        12.125 -> 17.297   (17.30 expected)
  가나다라   48.453 -> 69.188   (69.20)
  안녕하세요 60.563 -> 86.500   (86.50)
  日本語     42.000 -> 51.906   (51.90)
  abcdefgh  69.234 -> 69.203   (69.20, unchanged)

Edited in config/patches/xterm-src/ and regenerated through the harness, so
the emitted patch and lockfile hash are derived rather than hand-written.

The unit test asserts the arithmetic, which is what CI can run. The pixel
consequence was measured on macOS with SF Mono in an Electron harness, not
on the Windows font stack STA-3232 reports from — so this demonstrates the
mechanism and does not stand as that row's platform evidence.

* test(e2e): pin the macOS Korean preedit as visible only while composing

#11914 reports the composing text invisible until Space. Its c3 was recorded
as unobtainable, and the reason on file was wrong: the boundary IS
assertable, but not in happy-dom, which reports display:block in BOTH the
active and inactive states and zeros for every rect. A test there passes
with the defect present.

Captured on real hardware instead: hidden and 0x0 before, .active with
display:block, a 15.84x16 rect and checkVisibility() true while composing
그, hidden again after. 39 DOM events, 2 composition starts, onData
["한","그","\r"].

Two mechanism findings are carried in the setup because both are invisible
in the result and fatal if removed. The input source must be selected AFTER
the app takes focus — focusing resets it to ABC. And the IME must be warmed
until an observed keyCode 229; typed cold it emits raw QWERTY (g k s r m)
with no composition at all, which is indistinguishable from an IME that is
not installed. Two runs were voided on exactly that signature before the
warm-up was found.

The has229 and compositionStarts assertions exist to make such a run fail
loudly rather than pass as a clean negative.

Gated on darwin plus ORCA_E2E_NATIVE_MACOS_KOREAN, like its siblings. The
final spec form has not itself been executed — the machine became
unavailable — so it carries the probe's measured values as literals rather
than a run of its own.

* docs(e2e): correct 19a8d133db — the Korean preedit spec has been executed

That commit said the landed form had never run and carried the probe's
values as literals. It has now run on real hardware: 1 passed, 9.1s, rc=0,
with the capture and log sealed under a verified hash manifest.

The teeth check was also run rather than reasoned about, and it changes
which assertion matters. Forcing the active overlay to max-width:0 with
overflow:hidden — invisible on screen — leaves the active class, the
textContent, display:block AND checkVisibility() all passing. Only
during.rect.width fails. checkVisibility() is not sufficient against this
defect; the bounding rect is the single load-bearing assertion, which the
docblock already said and this run confirms.

An earlier teeth attempt injected the CSS mid-run and tripped the
hasActiveClass poll instead, failing at the wrong assertion. It is
inconclusive and excluded from the seal rather than counted.

* test(terminal): add #12171's ordinary-English arm from a real Windows capture

c4 was recorded as unmet and the ledger sourced its control to
evidence/windows-current/, which holds 12 captures and not one English one.
The arm here comes from windows-9803-final instead — same probe, same host
geometry, same injector, en-US with no IME, replayed keydown for keydown.

Two limits are stated in the file rather than left for a reader to find. It
is a different bundle and a different run about 3.6 hours later, so it is
not a same-run arm. And it is #9803's range-active MUTANT arm: ordinary
English stays byte-exact even with that saved-range mutation live, which is
why it reads as a negative rather than as a baseline.

Bundle cited by directory with its file SHA-256; MANIFEST.sha256 verifies
21/21, rc=0. Nothing imported from .tmp.

* docs(terminal): correct #12164's grounds — the cited comments say no such thing

The rejection of #12164 from this file's family was recorded as resting on its
comment 1 (output doubling) and comment 2 (filed against 1.4.163). Checked
against the API: the issue has exactly two comments, neither of which says
that, and the string 1.4.163 appears nowhere in the thread.

The conclusion survives on better grounds. The issue BODY's repro is "Run any
CLI agent (Codex, AGY, Claude, etc.) that outputs Korean text into the Orca
terminal" — untyped output, no keystrokes, no composition — so excluding
CompositionHelper is right, and the input-path hunt was looking in the wrong
place. The body is also LLM-authored (it still contains a literal
"## 5. GitHub Submission Draft (Ready to Post)") and its Root Cause section
blames a CJK IME preedit buffer its own repro never engages, so it should not
be read as observation.

Comment-only; suite unchanged at 5/5.

* test(native-chat): make composition frames carry isComposing, not just inputType

This suite's comment claimed "Gating onChange on `isComposing` breaks here."
It did not. composeFrame() fired `input` with `inputType` but never set
`isComposing`, so a gate on `isComposing` passed all four tests untouched —
the suite asserted a discriminator it did not exercise.

Composition frames now carry both, so neither gate is exempt. Verified by
pointing the mutant at it: with an `isComposing` gate on the composer's
onChange, this suite now fails 3 of 4 (it passed 4 of 4 before), and the
ordinary-English arm correctly survives, since a composition gate should not
touch it. Production code is unchanged and stays gate-free; the mutation was
applied, measured, and reverted.

Found while excluding NativeChatView's question-card remount as the owner of
#12118 / STA-3219: the remount is real, but the preedit survives it precisely
because this write path has no composition gate.

* fix(mobile): ship the patched xterm build, matching desktop

mobile pinned @xterm/xterm 6.1.0-beta.285 while the patch is keyed to
6.1.0-beta.287, so mobile shipped stock xterm and neither IME defect fix
reached it: the swallowed keystroke after an IME commit (9506039de7) and
the preedit sized to the font rather than the grid (e04e0c88da).

Bumps the three xterm packages to the desktop versions and adds the patch
to mobile's own pnpm.patchedDependencies. No copy of the patch: pnpm
accepts the parent-relative path and records it in the lockfile against
hash 8d63166272e9040a…, byte-identical to what desktop resolves, so the
two stay in step by construction rather than by a drift check.

The workspace separation is untouched — root pnpm-workspace.yaml still
declares `packages: []` and mobile keeps its own lockfile, which is what
keeps the root's patches from failing as ERR_PNPM_UNUSED_PATCH.

Verified in the generated webview bundle rather than at the install:
alignPreeditToGrid 0->2, sentComposition 0->3, pendingInput 0->11, and the
stock-only _handleAnyTextareaChanges 2->0 and dataAlreadySent 4->0. pnpm
applies patches during linking before postinstall regenerates the bundle,
confirmed by a revert/reinstall/re-apply cycle in both directions.

Mobile suite 2971 passed, 3 skipped — identical before and after. Bundle
+1,514 B (+0.24%). Lockfile churn is xterm-only; --frozen-lockfile passes.

mobile/src/ime/ime-submit-carry.ts is NOT made redundant and is untouched:
it handles iOS firing onSubmitEditing on a React Native native TextInput
after unmarking a composition, which is outside the WebView entirely.

Known divergence left alone: desktop also patches @xterm/addon-webgl and
mobile now runs that version unpatched. That patch is glyph/texture-atlas
rendering with nothing IME-related, so it affects neither fix.

* test(terminal): pin the preedit overlay against already-committed cells

STA-3132 (arm A), STA-3170 and STA-3232 report a Korean preedit painted on
top of text already on screen. Builds v1.4.163-v1.4.166 cancel the pending
finalizer in compositionstart, so a committed syllable reaches onData one
syllable late and buffer.x is stale — the overlay lands on the cell the
flushed syllable is about to occupy.

Replays a recorded hardware trace rather than an authored one: the ordered
DOM event stream captured on Windows + MS Korean (wave5-r2 evidence, 64
events), echoing onData back as PTY output.

The load-bearing assertion is deliberately not the obvious one. Comparing
overlay style.left against cursorX is tautological — left is computed from
buffer.x. This counts committed syllables from the compositionend events
the IME fired, so the two sides are independently derived.

Discriminated by a historical re-add across seven real bundles, since the
owner is deletion-shaped: pristine beta287, v1.4.155 and v1.4.162 pass;
v1.4.163 fails; v1.4.163 with that single call removed passes; the byte
identical baseline restored fails again; head passes. Every failing arm
fails only this case — the ordinary negative stays green in all seven.

The negative asserts its own category rather than claiming it: zero
composition events, zero isComposing, zero keyCode 229, exactly 16 events,
paired against the Korean arm's 4 starts / 3 ends / 11 updates / 64 events.

Scope: cell indices, not pixels. happy-dom has no layout, so the recorded
8x16 cell metrics are supplied to the render service. This makes no claim
about pixels visually overlapping; that is affected-OS confirmation and
stays open. Covers the overlap arm only — STA-3132's auto-line-break arm
and STA-3232's half-line-capacity and a11y arms are untouched.

* test(e2e): matrix macOS period substitution against the OS preference

#11504 reports macOS inserting ". " after a Hangul Space commit. This
sweeps six arms across both states of NSAutomaticPeriodSubstitutionEnabled,
reading the preference live per run rather than asserting a literal.

Two results worth having on record.

The reporter's stated trigger did not reproduce. Their words are "There is
no second press at all. One space is enough", but korean-single-space emits
zero insertText with the preference on or off. So does word-space-word-space.

Their timing does reproduce, with different content. korean-double-space and
korean-longer-word-double-space emit a delayed insertText at +122.5-122.7ms
after compositionend — squarely the reported +149ms — but the payload is a
space, never ". ". Consistent with the double-space rule seeing two slots
under ABC and only one under Korean, where the IME commit consumes the first.

The substitution itself is real and preference-bound: latin-double-space
gives "ab . " with the preference on and "ab  " with it off, on one build
with the preference as the sole variable, reproduced across two runs.

That also refutes a claim in PR #11506, which states the substitution "is
enforced outside the renderer and never reproduces in dev builds, so changes
here must be verified against a packaged app". It reproduced in the dev build
twice and did not reproduce on the signed packaged app. That claim should not
be used as a verification gate.

Gated @headful behind ORCA_E2E_NATIVE_MACOS_PERIOD, same shape as the Korean
preedit spec, so it does not run in ordinary CI. Evidence is onData and DOM
only — the PTY-child reader aborted and no packaged-app arm was stable.

* test(terminal): actually enforce the recorded jamo progression

The preedit assertion compared sample.overlayText against sample.overlayText
— the same expression on both sides. A lane proved it by mutation: corrupting
seven of the eight recorded preedit values left the suite fully green. So the
docblock's ㄱ→가→간→나→낟→다→달→라, which the matrix also cites as this row's
recorded shape, was cited and unenforced.

The first attempt at a fix was insufficient and is worth recording. Threading
stroke.preedit through to the expectation still passed on a corrupted fixture,
because that value both drives the rig and was the expectation — corrupting it
moved both sides together. Same tautology, one level down.

The expectation is now an independent literal. Verified by mutation rather
than by reading: corrupting two recorded values fails one arm; restoring them
passes 3/3.

overlayCell was never affected — it is compared against a count derived from
the compositionend events, not from the buffer, and remains the load-bearing
assertion for the overlap.

* fix(e2e): select the selectable input source, not the first match

TISCreateInputSourceList can return several entries for one input source
id. A third-party IME publishes a non-selectable parent alongside the
selectable mode, and taking sources.first can return the parent — after
which TISSelectInputSource fails with paramErr (-50) while the caller
reports success from the enable step.

Found with Qingg (com.aodaren.inputmethod.Qingg), which exposes exactly
that pair under one id. Its mode id equals the bundle id, so filtering by
name would not have helped; selectability is the discriminator.

Now filters on kTISPropertyInputSourceIsSelectCapable and falls back to
the old behaviour when nothing advertises it, so single-entry sources are
unaffected. Also enables every entry for the id rather than only the one
being selected: selecting a mode whose parent is still disabled fails the
same way.

Compile-checked, and selecting com.apple.keylayout.ABC still exits 0.

Unrelated to the enable path: on macOS 26.5.2 third-party IMEs are gated
behind a consent sheet in System Settings. TISEnableInputSource returns
noErr immediately regardless, and the enable only lands if that sheet is
answered while the requesting process is still alive.

* test(terminal): discriminate #12171 against the real shortcut policy

The prior candidate mutation for this row was correctly refused: its suite
mocked shortcut policy so Process/229 became actionable, while the real
resolveTerminalShortcutAction has no Process branch — so the kill measured
the mock. This does not mock it.

Replays a capture of this row's own gesture (d, l, Shift+T, e, k, Space,
Enter under MS Korean, committing 있다) taken on Orca 1.4.164, through the
real useTerminalKeyboardShortcuts hook, capturing bytes at terminal.input.
The earlier capture could not discriminate at all because it recorded no
shiftKey; this one records it on 10 of 10 keydowns with code populated.

One physical Shift+T produces two shifted Process/229 keydowns. Under the
pre-#12265 classifier each synthesizes {key:'Enter', shiftKey:true}, which
the real policy resolves to sendInput '\x1b\r' — twice, giving 1b0d1b0d,
the two escapes the known-bad ed96881b0d1b0d contains.

Mutation is the retained pre-12265-process-shift.patch applied to HEAD, not
an authored one: patch -p1 applies clean and diffs identical to the mutant
copy. Arms are copies; shared source hashes the same before and after.

The English arm stays clean under both modules, so the mutation
discriminates by language rather than by harness — and a real Shift+Enter
through the same rig yields exactly ['\x1b\r'] in every arm, so a silent
pristine result means the code is quiet rather than the harness dead.

Scope: 1b0d1b0d is measured at the renderer boundary. The capture recorded
no PTY bytes — window.api.pty is frozen on shipped builds and the onData
channel needs a build-time flag — so this shows the renderer producing the
two escapes that payload contains, not a re-observation of the payload.

* docs(native-chat): narrow this file's disclaimer to what is now true

It said "THIS OWNS NO REPORTED ROW". Half of that is stale: the remount site
is now the attributed owner of #12118 and STA-3219. On real Windows TSF the
questionActive swap aborts a live composition — the old node gets only a
blur and no compositionend, the text returns as committed, and the next jamo
yields 아ㄴ rather than 안.

The other half holds. This file pins the opposite property, that the text
survives, which is the half those reporters already agree with. Mutation
shows the gap rather than asserting it: deleting the unmount entirely leaves
three of four tests green, because every substantive assertion is
after.value === … and a composer that never unmounts keeps its value.

Also records why the abort cannot be asserted here. The DOM exposes no
observable separating committed text from a live preedit — value is the same
string either way, there is no EditContext, and the only composing-ness
state is a per-instance ref discarded with the node. A test pinning "no
compositionend fires" would be an anti-guard: red the day it is fixed.

The cadence objection is kept, since it is now the open question rather than
the reason for exclusion.

* refactor(terminal): drop the unread isComposing field from XtermBypassEvent

Added by #6396 for terminal IME candidate handling that this branch has since
removed. No production or test code reads it, and the policy is safe without it:
during composition `key` is 'Process', so the non-ASCII printable checks that
would care never match.

Co-authored-by: Orca <help@stably.ai>

* fix(native-chat): keep the composer mounted through an in-flight IME composition

A question card replaced the composer outright
(`{questionActive ? null : <NativeChatComposer/>}`). Unmounting the field
mid-composition aborts the composition in the OS: the node is detached before
`compositionend` can fire, the preedit returns as committed text, and a resumed
Hangul syllable degrades — 아 then ㄴ yields `아ㄴ`, never `안`.

Confirmed in rasterised pixels on Windows with a real MS Korean IME, at both
v1.4.171 and the reporter-era v1.4.164 (the swap block is byte-identical
across them): the preedit underline present before the swap, the composer
visibly absent during it, and the same glyph back afterwards WITHOUT the
underline — committed, not composing.

The swap is now deferred while a composition is in flight, which is what
editors that survive IME do: ProseMirror gates DOM work on `view.composing`,
CodeMirror protects the composing subtree from redraws. Hiding instead of
unmounting does not work — `display:none` and `visibility:hidden` both blur the
focused element and abort the composition the same way.

The hold releases on `compositionend`, which browsers also fire on blur, so
clicking into the card's own answer input yields the input region immediately;
with nothing composing the card still replaces the composer at once, so no
stray "Send a message" appears beside a question.

The existing characterization test flips to a regression guard: it pinned the
node being destroyed, which was the defect. Node identity is the load-bearing
assertion — value-only checks are trivially satisfied by a composer that never
unmounts and cannot tell a held composition from a destroyed one.

The typing-redirect handler moves to its own hook. That is not cosmetic: both
touched files sat at the 400-line cap, and `max-lines` suppressions are
forbidden, so the room had to come from a real extraction.

* fix(macos): opt Orca out of AppKit automatic period substitution

macOS "Add period with double-space" (`NSAutomaticPeriodSubstitutionEnabled`,
on by default) is applied by AppKit's text input system. Native terminals never
join that system; Chromium text fields do, so xterm's helper textarea inherits
it and a double space arrives as `". "` — a period nobody typed, handed straight
to the PTY (#11504).

Chromium answers AppKit for quote and dash substitution and defaults both off,
but declares no period accessor at all, so AppKit applies that one without
asking. This user default is the only lever: there is no per-field or
per-webContents opt-out to prefer over it. Writing the key into Orca's own
defaults domain overrides the global value for this app alone and leaves the
user's system-wide setting untouched. It necessarily covers every Orca text
field, not only terminals — AppKit offers no narrower scope, and that tradeoff
is deliberate rather than accidental.

Measured on the reporter's own build v1.4.161: with the preference ON, typing
a,b,space,space yields `onData ["a","b"," ",". "]`; with it OFF the same arm
yields two spaces.

Note the issue's causal model is wrong and this fix does not follow it. It
claims the substitution only fires with a CJK input source and never with ABC.
The measurement is the inverse — every Korean arm is clean and the ABC arm is
the one that fires — so the fix is not conditioned on input source.

NOT YET VERIFIED ON HARDWARE. The unit tests inject the writer, so they prove
the call is made on darwin and skipped elsewhere; they do not prove AppKit
honours an app-domain override for this key. That check is outstanding.

* fix(xterm): keep a live composition across a lone Cmd press on macOS

CompositionHelper.keydown exempted keyCodes 16/17/18 from tearing a composition
down, which covers Shift/Ctrl/Alt but not macOS Meta — 91/93 in Chromium, 224 in
Firefox. A lone Cmd press mid-composition therefore reached
_finalizeComposition(false), which dropped the preedit overlay's `active` class
and committed the live syllable early. macOS keeps the marked text alive across
that press, so no later compositionstart re-arms the overlay and the rest of the
word composes invisibly.

Measured on hardware (m4air, macOS 26.5.2, Apple M4, 2-Set Korean) with the Cmd
posted as a CGEventType.flagsChanged, which is what a physical modifier emits.
AppleScript `key code 55` posts nothing a browser can see — a bare `key code 56`
for Shift is equally silent — which is why no capture in the corpus ever reached
this branch. Three arms, same build otherwise: overlay live throughout with the
exemption, dark and prematurely committed without it, live again with it
restored. Evidence under
.tmp/ime-handoff/swarm-scratch/wave31-cmd-preedit/evidence/.

The fix cannot widen past a lone modifier: only a standalone press reports these
keyCodes, and a Cmd chord during composition is reported by Chromium as 229,
which was already exempt. Cmd+A still ends the composition, via the IME's own
compositionend. Ghostty draws the same line, returning early from flagsChanged
under hasMarkedText() for every modifier including Super.

Orca's terminal pane was never affected — shouldSuppressTerminalModifierKeyboardEvent
drops a standalone Meta keydown before xterm sees it, and deleting only 'Meta'
from that set is what flipped the hardware arm to broken. The popout preview
terminal and mobile's webview install no such guard and did reach the teardown.

terminal-ime-xterm-composition-commit-overlap.test.ts asked its fixer to update
the two Cmd arms to the values it named as correct; both now emit a single ['한'].

* test(native-chat): drop two byte-identical duplicate cases

`4632b86919d` copy-pasted two cases twice into the same describe block:
`retains carry across a same-frame non-Enter keyup before redispatch` and
`expires carry before a deliberate Enter after the next frame`. Each pair is
byte-identical — same title, same body — so the copies asserted nothing the
originals did not.

This is what has been failing `static analysis` on this branch since 2026-08-06:
`oxlint vitest(no-identical-title)` reports both under `--deny-warnings`, and
`verify` fails solely because it requires static analysis to pass. Every other
gate in `verify` was already green, including typecheck, xterm patch sync, the
full test shard set, and both package jobs.

12 cases still pass in the file.

* test(e2e): skip the WebGL arm when no WebGL renderer exists

The #12164 probe runs two arms, webgl and dom, and closes by asserting the
active renderer is the requested one. That assertion is right for the dom arm —
it is what proves the pane actually left WebGL, without which the arm is
meaningless — but headless CI has no GPU, xterm falls back to DOM silently, and
the webgl arm then fails.

The failure reads as a Korean rendering defect and is not one, so the webgl arm
now skips with the active renderer named. The dom arm keeps the assertion
unchanged.

This is the third of three checks that have been red on this branch since
2026-08-06. `static analysis` and `verify` were fixed in c51c6b5837e; the CI log
shows this job as 1 failed / 1 passed, the pass being the dom arm.

* chore(lint): drop five unused no-console disable directives

`check-changed-code-quality` reports unused eslint-disable directives as errors,
and these five sat above diagnostic `console.log` calls in IME test and spec
files where `no-console` is not enabled — so each suppressed nothing.

This is the second of the two static-analysis steps. `c51c6b5837e` fixed
"Enforce focused code-quality plugins" (duplicate test titles); this fixes
"Enforce changed-code quality". Both had been red on this branch since
2026-08-06, and I mistook the first for the whole job.

The diagnostic logs themselves are kept — they are what a failing IME arm prints
for a reader to inspect.

* test(e2e): cover #12164 under fractional device scale factor

Fractional display scaling was #12164's last unexplored branch, and the reason
is worth recording: earlier attempts were BLOCKED, correctly, because they
proposed mutating the Windows display scale on a remote physical machine with no
console recovery. `--force-device-scale-factor` reaches the same renderer state
per process, so nothing outside the Electron instance changes and there is
nothing to restore.

The hypothesis was specific: `프프로로젝젝트트` is what a half-pixel cell boundary
could produce on a 2-column glyph, and nothing else in the suite varies dpr.

Measured at 1.25 and 1.5, both under WebGL: ink extents 25/21/16 with identical
ink groups, matching the scale-1 run. No doubling.

The arm self-certifies before asserting — if the flag does not take, the test
fails rather than silently measuring at dpr 1. That matters here: the sibling
spec's WebGL arm went two days reporting a missing GPU as a Korean rendering
defect precisely because a silent fallback looked like a result.

* fix(terminal): match Mod+letter shortcuts by physical key, not IME-rewritten key

With a CJK input source active, macOS and Windows report the physical key through
`code` but rewrite `key` to the layout's character: Korean 2-Set turns Cmd+C into
`{ key: "ㅊ", code: "KeyC", metaKey: true }`. Every `key.toLowerCase() === 'c'`
match misses it, so the shortcut is not recognised and xterm encodes the chord as
PTY input instead — issue #13033 reports `ESC[12618;9u` and a terminal that jumps
to the bottom, because user input scrolls the viewport.

This is the same key-vs-code confusion that owned #12171, where a `Shift+T`
typing ㅆ was read as Enter for want of a `code` guard, so the fix is the same
shape: trust `code` when it is present, fall back to `key` and then the legacy
`keyCode` when it is not (Chromium omits `code` on synthetic and some keypress
events, and `keyCode` keeps its US value even when `key` is rewritten).

Applied to the four terminal-side sites, including the dashboard pop-out, which
#13033 called out specifically as having its own key handler:
  pty-connection.ts            Cmd/Ctrl+C copy guard
  keyboard-handlers.ts         Cmd+G search navigation
  agent-interrupt-inference.ts interrupt inference
  preview-terminal-key-handler.ts  pop-out paste

Nine further `key.toLowerCase()` letter matches exist outside the terminal
(TaskPage, editor, GitHub composer, browser markup). They have the same defect
and are deliberately left for a separate change rather than widening this one.

An existing case, `matchSearchNavigate > returns null for wrong key`, overrode
only `key` and left `code: 'KeyG'`, so it began passing for the wrong reason. It
now overrides both — which is what "wrong key" means once matching is physical —
and a companion case pins the Korean-rewritten chord still matching.

#13033 was closed NOT_PLANNED; the reporter's event shapes drive the new test.

* fix(renderer): match every Mod+letter shortcut by physical key, not IME-rewritten key

Completes the previous commit. A CJK input source rewrites `event.key` while
`event.code` keeps the physical key, so `key.toLowerCase() === 'z'` and friends
silently stop matching — the shortcut is not recognised and the keystroke falls
through to whatever handles unclaimed input.

The helper moves to `@/lib/ime-latin-shortcut-key` first: it now serves the
editor, GitHub composer and browser markup, and importing terminal-pane
internals into those would be the wrong direction. `lib/` already hosts
`ime-composition-keyboard-event` for the same reason.

Nine remaining sites, all previously unreachable under Korean/Japanese/Chinese/
Vietnamese input:
  TaskPage, ActivityPrototypePage, ProjectViewWrapper   Cmd+F search
  useMarkupKeyboardShortcuts                            Cmd+Z undo
  GitHubMarkdownComposer, RichMarkdownLinkBubble,
    rich-markdown-link-shortcut                         Cmd+K link
  native-chat-shortcut                                  Cmd+J
  rich-markdown-key-handler                             Cmd+Shift+X

Six of the nine test `!== 'letter'` as early-return guards and three test
`=== 'letter'`; the negation is applied per site, since a blind substitution
would have inverted six of them.

Full suite: 4249 files pass. Three files fail locally and none is caused by this
change — the branch touches no file under `src/main/` or `src/relay/`, all four
failures reproduce on an unmodified tree or pass in isolation (the worktree
poller passes 21/21 alone, so it is full-suite parallelism), and all 16 CI test
shards are green.

* docs(ime): scope the IME composition rules to the terminal-pane directory

#11893 proposed adding these to the root `AGENTS.md`, which every agent loads on
every task regardless of what it is doing. They only bind keyboard handling, the
composer and the terminal input path, so they belong next to that code —
`tests/e2e/AGENTS.md` already establishes the nested convention here.

Kept from #11893: range-derived commits, guarding above the key dispatch,
the `attachCustomKeyEventHandler` / `CompositionHelper` interaction, no
normalization at commit, and the recorded-trace evidence bar.

Added from defects found since it was written:
- match shortcuts on `event.code`, not `event.key` (#12171, #13033)
- `keyCode === 229` means an IME owns the press
- do not unmount a field mid-composition, and hiding is not a fix because
  `display:none` blurs and aborts it too (#12118, STA-3219, #11332)

The evidence bar now also names the mutation check, since a test that survives
deleting the code it guards is guarding nothing — a failure this effort hit more
than once.

* fix(terminal): gate Ctrl+Enter CSI-u on a negotiated pane, porting #12462

Found while scoping the rebase onto `main`: #12462 landed on 2026-08-06 and
fixes a real defect this branch does not carry. Ctrl+Enter emitted
`\x1b[13;5u` unconditionally, so a pane that never negotiated the kitty
keyboard protocol — local Windows ConPTY, plain shell — printed the escape
verbatim into the prompt.

This branch deletes `terminal-ime-deferred-newline.ts`, which is one of the
files #12462 touched, so a rebase resolving those conflicts by taking our side
wholesale would silently reintroduce the defect. Porting it forward now means
the fix survives the rebase however the conflicts are resolved.

Mirrors the Shift+Enter guard already here: local ConPTY falls back to the
legacy CR every emulator sends, and a negotiated pane keeps the chord, so the
fallback is scoped to panes that cannot receive CSI-u rather than to Windows.

NARROWER THAN #12462 BY ONE CONDITION, deliberately. `main` also allows CSI-u
via `hasCtrlEnterCsiUAuthority()` (trusted consumer evidence, #12329); that
helper and its plumbing do not exist on this branch. Omitting it is the
conservative direction — an authorised pane gets `\r` instead of the chord,
rather than an unnegotiated pane printing an escape — but it should be restored
when the two histories are reconciled.

Test covers both directions and is mutation-checked: forcing the gate open
fails it, so it cannot pass by construction.

* fix: reconcile two more fixtures main moved while the stack waited

Both caught by CI, not locally, and the reason the local run missed one is
worth recording:

1. `browser-toolbar-profile-dialogs.ime-enter.test.tsx` did not pass
   `useNativeUserAgent` / `onUseNativeUserAgentChange`, which `main` added to
   `BrowserToolbarProfileDialogsProps`.

   Local `pnpm typecheck` reported 0 errors on the same commit CI failed. The
   cause was a stale `config/*.tsbuildinfo` — tsc reused an incremental cache
   from before the merge. Deleting it reproduced CI's error exactly. Any
   "typecheck clean" during this merge should be treated as unverified unless
   the cache was cleared first.

2. Localization keys for `SshDisconnectedDialog` were absent from `en.json`:
   the merge took this branch's component alongside `main`'s catalog.
   Regenerated with `pnpm run sync:localization-catalog` rather than hand-added.

* fix(mobile): regenerate the lockfile the merge resolved by taking one side

CI's `verify` failed with `ERR_PNPM_OUTDATED_LOCKFILE` on `mermaid (lockfile:
11.16.0, manifest: 11.16.1)`. The mismatch was in `mobile/`, not the root — the
root lockfile was consistent throughout, which is why inspecting it (and even
GitHub's merge ref) found nothing wrong.

Cause: during the merge I resolved `mobile/pnpm-lock.yaml` by taking this
branch's side wholesale rather than merging it, so it kept `mermaid 11.16.0`
while `mobile/package.json` came from `main` at `11.16.1`. Taking one side of a
lockfile is only safe when the corresponding manifest comes from the same side.

Regenerated with `pnpm install --lockfile-only`; `--frozen-lockfile` now passes
in `mobile/`. Verified the xterm patch entry survives intact — same hash
`4f1b42d268f3964d…` and the parent-relative path into `config/patches/`, which
is the desktop/mobile coupling that would silently break the mobile build.

Two earlier diagnoses of this failure were wrong and are worth recording: it was
not the root lockfile, and it was not a stale merge ref (a rerun reproduced it
exactly).

---------

Co-authored-by: Orca <help@stably.ai>
2026-08-07 22:58:40 -07:00
github-actions[bot] 7df7aa5fe9 Update README downloads badge 2026-08-07 01:27:54 +00:00
github-actions[bot] 2539889197 Update README downloads badge 2026-08-05 18:28:05 +00:00
Jinwoo Hong 06780260c0 test(remote-runtime): run an old client and an old server against current code (#12682)
Mixed versions are the normal state of the remote-server feature: users update clients and servers independently. Until now nothing tested that. Every cross-version claim was made by code reading plus unit tests with hand-written old/new shapes — enough to catch design problems, not enough to catch a real skew regression.

This runs the REAL protocol implementations from two builds against each other in one process: the actual host methods and RPC dispatcher on one side, the actual renderer multiplexer on the other, with a transport that reproduces the production asymmetry — each side decodes with its OWN codec and drops frames whose opcode it does not know. A frame survives only if the RECEIVING build understands it, which is what makes this level sufficient without launching two apps. The old side is a genuine checkout extracted from the release tag; the extracted client was confirmed to lack a symbol that exists only on main.

Journey: subscribe, first snapshot, input reaching the process, live output, hide/reveal snapshot, transport drop, resubscribe, input landing again — across old->new, new->old, and a current/current control. Every step ends on an observed-state barrier; no sleeps. The oracle asserts the recorded step list, the exact 16-frame named sequence, negotiated capabilities, the exact input the host wrote to the PTY, rendered content, and zero decoder-rejected frames. A host method the stub lacks is recorded by name and asserted empty, so a harness gap cannot masquerade as a wire break.

Detection is proven per violation shape, and it attributes each to the correct side: an unnegotiated opcode goes red only where a decoder would reject it, a removed published field goes red only where an old client consumes it, and a legal additive field stays green in all three pairings so the harness will not cry wolf on safe changes.

It also documents the three compatibility rules in docs/reference/remote-wire-compatibility.md, linked from AGENTS.md, since they previously existed only as folklore — notably that "decoders reject unknown opcodes" is true for the desktop decoder but NOT for mobile, which silently drops them.

Deliberately scoped: terminal stream only. The session-tab sync channel is not covered, nor agent-session publications, file/Git RPCs, mobile E2EE framing, or the relay transport. Two version points, so a regression introduced and reverted between them is invisible.

CI selection was verified rather than assumed — `vitest list` confirms 0 matches under the shard's exclude and 4 under the dedicated job — because a lane silently running zero tests is precisely how a host-side defect escaped CI earlier in this series. Closes STA-3469.
2026-08-05 01:31:29 -07:00
Jinwoo HongandOrcaWin 738f640428 fix(mobile): relay UX overhaul — steady status colors, visible relay dials, coordinated deep links (F1-F10)
* fix(mobile): keep healthy relays green through focus and network nudges (F1+F2)

Focus/app-resume nudges probe the active relay instead of suspending it;
network-change nudges replace it make-before-break, suspending only after a
failed dial. Mount, Retry, and host-swap windows read 'connecting' instead of
'disconnected'; the host list keeps last-known worktrees for every
not-connected state and spins instead of rendering nothing.

* feat(mobile): surface the pairing relay path in the pairing log (F3)

The relay candidate was silent during pairing: dialing, E2EE handshake,
director recovery, and the winning path now emit redacted phase lines through
the same connectOptions.onLog the direct path already used.

* docs(mobile): relay UX investigation findings and F0-F10 fix plan

* feat(mobile): name and narrate relay dials while they happen (F5)

migrateTo forwards the dialing session's connecting/handshaking/reconnecting
phases whenever the client is suspended or disconnected — never downgrading a
live session — and exposes getPendingPath so the host card can say
'· Orca Relay' during the dial instead of only after it.

* feat(mobile): race a relay dial when the direct dial stalls (F6)

A 2.5s grace timer starts relay recovery while an unauthenticated direct dial
is still inside its 12s connect window; the race gets one attempt through the
existing mutex/cooldown machinery, cancels when direct authenticates, and
never arms for hosts without a relay endpoint.

* fix(mobile): overlay the protocol gate instead of unmounting the host stack (F9)

A pending status.get used to swap the mounted HostStack for a spinner at the
moment the socket connected, destroying in-flight nested navigation. Once
children have rendered for a host they stay mounted under an opaque
touch-blocking overlay; first visits and blocked verdicts keep the old
behavior.

* fix(mobile): keep loaded data through transient connection blips (F10)

Git history no longer blanks on reconnect (and commit files refetch instead
of caching an offline empty answer), the repo picker keeps its last-good list
when an in-flight repo.list rejects, the diff review's ready-state
preservation actually runs, and proven host capabilities survive a drop
flagged unverified instead of being wiped.

* feat(mobile): coordinate every home deep push and bounce dead resume targets (F4+F7+F8)

Notification taps, the Accounts card, and host-edit now use the shared
mount-then-replace transition (with a focused-route walker so root-layout
scope works); the Resume card renders from the snapshot in a disabled state
so its late arrival can't shift Tasks under the thumb; resume targets are
validated against proven catalog data, and a session route whose worktree
the host proves missing bounces to the host index with a notice banner
instead of stranding on a dead screen.

* test(mobile): cover the resume-target and notice policies (F7)

Key notice dismissal by code so closing one banner cannot swallow a later,
different one, and move the visibility rule into host-route-notice.ts where it
is testable without a screen.

Adds the missing units for F7's decision points: isResumeTargetConfirmedMissing
(unproven catalog is silence, synthetic routes exempt), the validating
last-visited reader, and the notice visibility rule.

* fix(mobile): review-pass hardening for the gate overlay and diff preservation

Adversarial review findings: the reader's hunk position now survives a
connection blip (reset only on item change), the covered stack is hidden from
TalkBack while the gate overlay is up, and the overlay's hit-test comment is
scoped honestly to in-tree views (native-Modal drawers present above it —
follow-up).

* fix(mobile): CI + CodeRabbit review fixes for #12609

Move the findings doc under docs/ (root directory guard), drop two unused
eslint-disable directives, and address review findings: an unproven snapshot
seed can no longer downgrade a proven worktree catalog; a locally-aborted
relay dial skips the director fallback; post-migration bookkeeping failures
log instead of masquerading as dial failures (which could suspend the healthy
session); the auth wait arms its timeout before subscribing; forwarded dial
phases stop at close(); the legacy selector_not_found fallback requires
runtime_error; the diff-loading effect depends on the fields it reads; and
host-edit auto-cancellation is now pinned by a test.

* fix(mobile): second review round — queued replacements, race fence, confirmed bounces

A network-change replacement now survives the recovery mutex and cooldowns as
a queued intent instead of being dropped or suspending a healthy session —
only a failed dial or a dead probe tears one down. The happy-eyeballs
migration withdraws when direct authenticated during the relay dial
(first-authenticated-wins). A worktree bounce requires two consecutive
host-proven misses, since a transient desktop repo-scan rejection answers
selector_not_found for a live worktree. Background network flaps no longer
wake a billed relay splice, the lifecycle foreground flag stays in sync, a
screen unmount cancels only its own pending host-stack transition, and diff
review keeps the loaded review when its reconnect refresh rejects.

Extracted mobile-endpoint-nudge-router.ts and the establisher's dialEligible
pass, and split the supervisor nudge tests, to stay under max-lines.

* fix(mobile): satisfy the React Doctor changed-code gate

Render-phase ref writes move into effects: the protocol gate's resolved/mounted
latches now record committed outcomes only (a discarded children render can no
longer count as mounted), and the bounce hook syncs its callback ref in an
effect. Array<T> annotations become T[] in the extracted modules.

* fix(mobile): keep the loaded diff when the reconnect refetch rejects (F10)

The diff-loading hook's catch was the one path still erasing a ready diff —
the same keepLoadedDiff guard its disconnect and loading branches already use,
now pinned by a reject-after-ready test.

* fix(mobile): process foreground revival nudges

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
2026-08-04 19:47:39 -07:00
github-actions[bot] 9058059154 Update README downloads badge 2026-08-04 09:51:50 +00:00
NeilandOrca d8e5944b60 Stop a duplicate headless orca serve from crash-looping and exhausting AppImage FUSE mounts (#12212)
* fix(startup): stop a duplicate headless serve from crash-looping and leaking AppImage mounts

A second Orca launch that loses the single-instance lock called app.quit()
before `ready`. That quit is deferred, so the doomed process kept booting into
Chromium's Linux display initialization, failed with "Missing X server or
$DISPLAY", and died with SIGSEGV. systemd read that as a crash and restarted it
forever; each restart re-mounted the AppImage and left the squashfuse mount
behind, until the host hit the 1000-mount FUSE ceiling and every later launch
failed.

The lock-losing launch now calls app.exit(3), which terminates synchronously
before any display init. Exit code 3 is a stable "another process already owns
this userData profile" contract, and the documented systemd unit uses
RestartPreventExitStatus=3 plus a real StartLimitIntervalSec/StartLimitBurst
window so a permanently failing launch can no longer retry unbounded.

Second-instance argv is now forwarded to the owner, and a duplicate `orca serve`
no longer asks the live headless server to open a desktop window. Desktop
activation for ordinary launches and macOS dock re-activation is unchanged.

Closes #11935

* docs(headless): clear the start limit before the scripted service starts

StartLimitIntervalSec=300/StartLimitBurst=5 rate-limits operator starts too, so
after a crash-loop trips the burst systemd refuses a plain `systemctl start` for
the rest of the window. The Upgrade and Roll back scripts run under
`set -euo pipefail`, so that refusal aborted the rollback mid-flight and left the
server down on the exact recovery path the doc prescribes.

Both scripts (and their EXIT-trap recoveries) now run `systemctl reset-failed`
first, the unit reference explains the interaction, and the crash-loop bullet
points at it for manual starts.

Co-authored-by: Orca <help@stably.ai>

* test(startup): reproduce the #11935 duplicate-serve crash loop under real Electron

The committed coverage for #11935 was source-text greps, so nothing gated the
mechanism the fix rests on: pre-`ready` `app.quit()` is deferred, which is why
the lock-losing headless `orca serve` kept booting into Linux display init.

This runs two real Electron processes against one disposable profile. The
duplicate executes the lock-loss gate's own `app.*` statement, lifted out of
`src/main/index.ts`, so reverting to `app.quit()` fails the test. It also feeds
the owner's real forwarded argv through `shouldActivateDesktopForSecondInstance`.

Also record why the activation predicate matches `--serve` and not the `serve`
subcommand: an AppImage launched as `orca serve` exits at the CLI redirect
before requesting the lock.

* test(startup): wait for the owner process to exit before removing its profile

Windows holds the profile's handles for a beat after SIGKILL, so an immediate
rmSync can fail with EBUSY/EPERM.

Co-authored-by: Orca <help@stably.ai>

* test(startup): pass the fixture marker path by env, not argv

Chromium reorders argv and the duplicate's argv is itself under test, so a
trailing positional was the wrong channel for it.

Co-authored-by: Orca <help@stably.ai>

* test(startup): only the activation case waits on the owner notification

The exit-contract cases assert on the duplicate's own already-terminated
process, so they should not block on cross-process delivery.

Co-authored-by: Orca <help@stably.ai>

* test(startup): drop the staged lock race, keep the real-Electron gate contract

CI proved the two-process form cannot work on a display-less Linux runner:
Chromium's ProcessSingleton needs the browser IO thread, which needs `ready`,
which needs a display. The pre-`ready` owner looked stale and the duplicate took
the lock (`expected [ 'DUPLICATE_WON_LOCK' ] to include 'DUPLICATE_LOST_LOCK'`).

Lock acquisition and argv forwarding are already covered in
single-instance-lock.test.ts. What only a real process can settle is what the
loser does next, so that is all this file now runs -- display-independent.

Co-authored-by: Orca <help@stably.ai>

---------

Co-authored-by: Orca <help@stably.ai>
2026-08-03 23:34:22 -07:00
OrcaWinandOrcaWin ed7849eb7b fix(worktrees): stop silently switching existing Windows setup scripts to Git Bash (#12406)
* fix(worktrees): stop silently switching existing Windows setup scripts to Git Bash

#6967 derived the Windows setup-runner shell from `terminalWindowsShell`. On
upgrade, any Windows user whose terminal preference resolved to Git Bash had
their existing `orca.yaml` setup script (and issue command) handed to bash
instead of cmd.exe. Scripts authored against the cmd runner — `copy`, `xcopy`,
`set VAR=value`, `if errorlevel 1`, `%VAR%`, backslash paths — broke with no
migration and no warning, and the failure looked like Orca broke the project.

The conflation is also wrong in the steady state: a terminal preference is
per-user, so two people on the same repo got different interpreters for the
same orca.yaml and no project could write a setup script that worked for all
of its Windows contributors.

The interpreter is now a property of the script, declared the standard way:
a leading `#!` line. Native Windows keeps the historical `.cmd` runner unless
the script declares a POSIX shell, so no existing script changes behavior.
`resolveSetupRunnerShell` keeps its role as the feasibility gate — a bash
runner still requires the terminal to resolve to Git Bash, since the launch
command is typed into that shell and uses MSYS `/c/...` paths.

`buildWindowsRunnerScript` now drops a leading `#!` line rather than `call`ing
it, so a declared-bash script that falls back to cmd (Git Bash missing) fails
on a real setup line instead of aborting on errorlevel at line one.

WSL worktrees, POSIX platforms, and SSH hosts are untouched.

* fix(worktrees): keep the cmd setup runner launchable from a Git Bash pane

Adversarial review of this PR found that pinning the runner format per script
reopened issue #6896 one layer down.

- `WorktreeSetupLaunch.shell` had been redefined to mean "the format the runner
  file was written in". `resolveSetupRunnerCommand` consumes it as "the shell
  that types the launch command", so a Git Bash terminal with a batch setup
  script produced `cmd.exe /c "C:\...\setup-runner.cmd"` typed into a bash pane,
  where MSYS rewrites the `/c` switch into a drive path: cmd opens interactively
  and setup never runs. `shell` is the terminal's family again; the runner file's
  .cmd/.sh extension carries the format, and a batch runner launched from a POSIX
  pane reuses the existing PowerShell ProcessStartInfo launcher.
- The cmd runner dropped a leading `#!` line and ran the rest as batch, so a bash
  script reaching cmd (PowerShell/cmd terminal, or any SSH-to-Windows host) got
  its interpreter-agnostic prefix executed before failing mid-way. It now prints
  why and exits 1 without running anything.
- A `#!` line's option flags were discarded: `#!/usr/bin/env -S bash -euo
  pipefail` lost pipefail because the runner is launched as `bash <path>`. The
  generated posix runner now replays declared flags via `set` and drops the
  duplicate interpreter line.
- Docs cover the per-user setup command in repository hook settings, which goes
  through the same `#!` rule, and describe what the `#!` line does and does not
  select.

Tests: composed launch command for a POSIX pane + cmd runner (hooks, shared
runner command, setup sequencing gate, observed-setup signal), the cmd runner's
shebang refusal, and shebang flag replay. Each fails with the source reverted.

* fix(worktrees): replay only real `set` flags and keep the gate in the pane's shell

Two round-2 review findings:

- `#!/bin/bash -l` replayed `set -l`, which exits 2 and aborted the runner under
  its own `set -e` before a single setup line ran (all platforms). Only the flags
  `set` documents are replayed now; a bare `-o` with no option name is dropped
  instead of dumping the shell-option table.
- The wait-for-setup gate picked its language from the runner file, so a batch
  runner launched from a Git Bash pane got the PowerShell gate while the agent
  startup command was already POSIX-quoted — `Invoke-Expression` cannot parse
  `'\''`. The gate now follows the pane; the runner still launches through the
  ProcessStartInfo launcher, never through bash.

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
2026-08-03 23:25:50 -07:00
Jinjing 6f28c118bb docs: drop WeChat group 5/6 QRs; keep group 7 only
Older groups are full; community join path is group 7 only.
2026-08-02 19:48:51 -07:00
Jinjing 616d22406e docs: add WeChat group 7 QR with overflow guidance
Groups 5/6 filled; point community join flow at group 6 + group 7.
2026-08-02 19:47:46 -07:00
github-actions[bot] e0f597a351 Update README downloads badge 2026-08-02 00:58:08 +00:00
Jinjing 96c954f3be chore: remove force-added design docs from docs/ (#11891)
Keep only the durable docs already allowlisted for tracking
(STYLEGUIDE, assets, localized readme, and reference compatibility
guides). Drop feature design notes, plans, and repro artifacts that
were force-added past the existing docs ignore rules.
2026-08-01 00:33:20 -07:00
OrcaWinandOrcaWin 3b7ea59c5b fix(windows): make the GPU fallback actually remove the GPU child, and stop WSL latching absent (#11295)
* fix(windows): make the GPU fallback actually remove the GPU child, and stop WSL latching absent

Three Windows crash/regression fixes from shipped 1.4.156/1.4.158/1.4.159 crash reports.

GPU fallback (cluster D, 14 reports, exit 0x80000003 STATUS_BREAKPOINT):
the software-rendering fallback called disableHardwareAcceleration() plus
--disable-gpu, neither of which removes the GPU child process — Chromium still
spawns it to host Viz and merely drops the backend to software GL. Measured on
Windows 11 / Electron 43.1.0: gpuProcessCount stays 1. So a GPU process being
killed by a bad driver or an injected DLL kept dying after the fallback engaged,
on every launch, for the life of that build (the marker is sticky per version).
The crash tails show exactly this: gpu_fallback_applied followed by another GPU
crash 1.3s later. --in-process-gpu is the only switch that drops the child count
to 0; --disable-software-rasterizer is deliberately excluded because it also
kills SwiftShader, which would drop every terminal to the DOM renderer.

WSL distro list: a successful-but-empty `wsl --list --quiet` was cached for the
process lifetime. `wsl --install` reports zero distros while one is still
provisioning, so an early probe latched "no WSL" until restart — WSL appeared
during setup and then vanished from the terminal picker. Empty results now
re-probe on an exponential window (15s doubling to a 5min cap) while staying
readable, so a missing distro is still visible to isKnownMissingDistro.

WSL availability: isWslAvailable() latched false on any failure via a bare catch,
so one slow wsl.exe activation disabled WSL for the whole session. Failures are
now classified — a numeric exit status or ENOENT is answer-shaped and holds for
10min, anything else (timeout, spawn failure) retries after 45s — and both back
off per consecutive failure, mirroring isPwshAvailable.

Windows-only: every changed path is behind an existing process.platform check,
so macOS and Linux behaviour is unchanged.

* fix(windows): drop a stale WSL availability failure once a distro list succeeds

The distro-list and availability caches expire independently, and
getWslRepairReason checks availability first. So a definitive availability
failure (numeric exit status or ENOENT) held for 10-30min would keep reporting
`wsl-unavailable` even after `wsl --list --quiet` successfully returned a
distro — i.e. over a WSL that demonstrably just answered. That is the same
latch class this branch fixes, surviving in the gap between the two caches.

A non-empty distro list proves wsl.exe ran, so drop the negative availability
cache and let the next call re-probe. Scoped to non-empty lists only: those are
cached for the process lifetime, so this cannot re-spawn the blocking 5s probe
more than once. An empty list keeps its failure cache, since it re-probes on a
15s-to-5min schedule and would otherwise pay the blocking probe far too often.

* fix(windows): harden GPU safe mode and WSL recovery

* fix(wsl): make capability refresh cleanup explicit

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
2026-07-30 17:49:32 -07:00
github-actions[bot] 9f5aa41a7a Update README downloads badge 2026-07-30 18:48:03 +00:00
Sebastián Castañoandscastanoh21 676ef7fab8 feat(cli): add orca skills install and orca skills update for headless skill setup (#9201)
Adds `orca skills install` and `orca skills update` so skills can be set up without the GUI — SSH hosts, containers, CI. Previously `orca skills` had only `list` and `get`, so there was no headless path.

**Agent targeting is scoped explicitly rather than delegated to detection.** The `skills` CLI decides which agents to install into, and with `-y` and zero detected agents it takes `targetAgents = validAgents` — all ~75. That is not a corner case for a headless CLI: a fresh SSH box or container with no agent installed is the normal starting state. Measured on a bare host, the unscoped command created **52 top-level agent directories and 54 junctions** (one real payload in `~/.agents/skills`, the rest links) on Windows, and 52/53 on macOS.

The CLI now passes `--agent` derived from Orca's own detection, mapped to the `skills` key namespace, plus `universal`. Supplying `--agent` makes `runAdd` use it directly and never call `detectInstalledAgents()`, so the fan-out branch is unreachable. On a bare host it now refuses with `No coding agent detected on this host` and exit 1, creating nothing. Same command with scoping: **1 directory, 0 junctions.**

`universal` alone would under-install — Claude Code is not in that set, and 19 of 28 mapped keys write agent-private homes `universal` never touches. `--agent '*'` is the bug itself. The mapping is hedged three ways: `null` for any agent whose key could not be confirmed, `satisfies Record<TuiAgent, …>` so a new Orca agent is a compile error, and a test pinning every mapped key against the CLI's own valid list.

Fixed during review — two holes that each restored the full fan-out through a different door:
- `--agent ','` trimmed to nothing, which skipped the refusal *and* emitted no `--agent`.
- `--agent -y` passed an emptiness check, and the vendor CLI silently drops `-`-leading values, re-emptying its list.

The real invariant is argument *shape*, not emptiness, and it is now enforced at the choke point in `buildAgentFeatureSkillInstallArgs`, so no caller can emit `-y` without a usable target. `*` remains allowed — asking for every agent explicitly is a choice, not an accident. Verified with 51 hostile inputs through the built binary, each recorded argv replayed through the vendor's own parser.

Also fixed: the `ORCA_CLI_CWD` refusal now runs before target resolution (it was quoting the wrong host's agent list), and `--dry-run` is refused in a forwarded shell rather than printing a command naming the wrong machine.

Validated on a real Windows host across PowerShell 7, PowerShell 5.1, cmd.exe and Git Bash: `.cmd` shims route through `cmd.exe` and `.exe` shims spawn directly (proved with instrumented shims, not inferred), the ENOENT path produces an actionable error rather than a silent failure, and `skills update` genuinely restores a corrupted skill byte-for-byte.

Known, not addressed here — both upstream behaviours this only forwards: a partial install failure exits 0, and "no installed skills found" exits 0. Both are invisible to the headless callers this feature exists for.

Co-authored-by: scastanoh21 <scastanoh21@gmail.com>
2026-07-30 11:20:29 -07:00
JinjingandOrcaWin 5f7807497e feat(ssh): bound relay PTY output end to end (#11005)
* docs: design SSH relay PTY backpressure

* fix(ssh): bound relay frame decoding

* fix(relay): bound PTY output publication

* fix(ssh): bound PTY model admission

* fix(ssh): settle closed model admissions

* feat(ssh): negotiate bounded PTY consumer sessions

* fix(ssh): fence exit on renderer settlement

* feat(ssh): track PTY source credit end to end

* fix(ssh): recover bounded PTY output across reconnect

* feat(ssh): complete relay PTY output backpressure

* fix(ssh): close final PTY source credit races

* docs(ssh): record final backpressure validation

* feat(ssh): complete relay PTY source-credit lifecycle

* test(ssh): complete provider notification fixture

* fix(ssh): preserve terminal source credit across rotation

* fix(ssh): fail closed on recovery cancellation

* fix(ssh): prioritize mux control writes after drain

* fix(ssh): retire canceled relay restore deliveries

* fix(ssh): order exit cancellation cleanup

* fix(ssh): gate provisional source activation

* test(ssh): register mux drain-priority coverage

* fix(ssh): type stale owner recovery mismatches

* fix(ssh): close projection replacement races

* fix(relay): contain streaming edge failures

* fix(ssh): secure relay endpoint credentials

* docs(ssh): reconcile final backpressure lifecycle

* fix(ssh): bound main IPC output lifecycle

* fix(ssh): close recovery ownership gaps

* docs(ssh): record exact artifact validation

* fix(ssh): reject reclaimed snapshot replacements

* fix(ssh): fence model admission across reconnect

* fix(ssh): contain migration failure per PTY

* docs(ssh): record final exact-head validation

* test(ssh): align deploy fixtures with credential publication

* feat(ssh): add per-target bounded output setting

* fix(ssh): close source recovery review gaps

* fix(ssh): latch source credit environment override

* feat(ssh): make PTY source credit the default

* docs(ssh): record always-on relay validation

* docs(ssh): bind validation to current main

* test(ssh): grant source credit in IPC fixture

* test(ssh): grant source credit in fake relay

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
2026-07-29 17:03:15 -07:00
OrcaWinandOrcaWin dde72f85de fix(windows): separate updater from orchestration migration (#11405)
* fix(windows): separate updater from orchestration migration

* fix(terminal): attest adopted reveal identity

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
2026-07-29 15:23:06 -07:00
OrcaWinandOrcaWin 363e478909 fix(orchestration): preserve active workers across updates (#11271)
* fix(orchestration): preserve active workers across updates

* test(ssh): model absent legacy adoption

* test(orchestration): align compatibility contracts

* fix(windows): escape updater PowerShell booleans

* fix(windows): restore stock uninstall process check

* fix(orchestration): keep recovery off renderer startup barrier

* fix(orchestration): harden legacy recovery migration

* fix(orchestration): close recovery review gaps

* fix(orchestration): complete legacy worker cutover recovery

* fix(orchestration): preserve legacy workers across updates

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
2026-07-29 11:31:35 -07:00
NeilandOrca 3a80fbe162 Revert terminal rendering changes from #10692, #10794, #10871, and #10907 (#11338)
* Revert "fix(terminal): avoid flash while restoring parked terminals (#10871)"

This reverts commit 5a6a9e0b28.

Reverted for terminal rendering regressions (flashing, lost content).
Conflict resolution preserves the forwardRef signature from #10433 and
drops the parked-presentation gating #11016 fed with its effective set.

Co-authored-by: Orca <help@stably.ai>

* Revert "fix(terminal): limit pre-paint WebGL resume to macOS (#10794)" and "fix(terminal): stop switch bold flash and Windows lag (#10692)"

This reverts commits 4681edb520 and
8f5a45401f.

#10794 was itself a partial revert of #10692, so both are reverted
together: the Windows retained-WebGL LRU and the macOS pre-paint
(layout-phase) visibility transition that survived it. Terminal
visibility resume returns to passive disposal and recreation on every
platform, and the WebGL context ceiling returns to a flat 128.

Co-authored-by: Orca <help@stably.ai>

* Revert "fix(terminal): release an abandoned synchronized-output frame on reveal (STA-2694) (#10907)"

This reverts commit 97cb32c1cc.

---------

Co-authored-by: Orca <help@stably.ai>
2026-07-29 01:47:20 -07:00
NeilandOrca a721125d06 fix(perf): correct three 07-27 perf regressions (#11234)
* fix(perf): correct three 07-27 perf regressions

Traversal capacity cap no longer scales with worker concurrency
(#11026). retainWorkspaceSpaceScanEntry charged a traversal-wide entry
counter, so N workers each holding a listing multiplied the live charge.
At concurrency 48 a 48x2,100 tree (100,848 entries) hit the 100,000 cap
while 100x1,500 (150,100 entries, 50% more) passed, and scanLocalWorktree
treats the capacity error as terminal, reporting an intact worktree as
"Unavailable" with sizeBytes 0. The cap is now per directory listing --
the only quantity fixed by directory shape -- restoring the invariant
docs/workspace-space-scan-resource-bounds.md already states. Aggregate
live retention stays bounded by the unchanged 64 MiB byte cap.

Note: releasing each entry's charge at dispatch (the originally suggested
fix) was measured and does not help; the peak is set at admission, before
any entry is dispatched.

Repo image icons are no longer fully base64-decoded on every snapshot
publish (#11012). sanitizeRepoIcon reached decodeBase64Prefix, which
sized its buffer to the whole payload to read a 24-byte header, running
synchronously inside ipcMain.handle at a 250 ms throttle. Validation is
now memoized on source+src in a BoundedMap. Measured for 10 icons x
256 KB: 37.34 ms -> 0.67 ms per publish.

One over-long card label no longer discards the entire snapshot (#11012).
isDashboardSnapshot was all-or-nothing and dashboard-popout returned
early with no log while replaying lastSnapshot, so `orca terminal rename
--title "<1025+ chars>"` froze the pop-out board on its last good paint
with nothing surfaced. Labels are truncated at the producer, the
validator drops only the offending card, and both the rejection and the
drop are logged. The bound now lives in the shared snapshot contract so
producer and validator cannot drift.

Co-authored-by: Orca <help@stably.ai>

* fix(perf): charge a scan listing's parent path once, not per entry

The 4.1 fix made the entry cap per-listing but left the 64 MiB byte cap
charging parentPath.length for every entry in a listing. Because a
listing's entries all share one parent-path string, that multiplied the
path by the directory's width, so the byte cap measured checkout depth
rather than live heap.

The reported symptom therefore still reproduced at the production default
limits: 48 x 2,100 @ concurrency 48 raised a capacity error once the
worktree path passed ~58 characters, while the same layout at concurrency
1 succeeded. The shipped regression test could not see this because it
passes maxRetainedBytes: Number.MAX_SAFE_INTEGER, disabling the only cap
still in play. Measured at a real 65-char worktree root, 3 of the report's
4 documented layouts still failed.

The parent path is now charged once per listing, with its first entry, so
an empty listing strands no charge. Per-entry overhead is unchanged at
512 B + name, which still dominates the estimate, so the OOM protection
the original PR added is preserved.

Adds a production-default-limits case covering the report's layouts under
a deep root, plus an assertion that a short and a deep root reach the same
verdict -- the path independence docs/workspace-space-scan-resource-bounds.md
requires and which no existing test enforced.

Co-authored-by: Orca <help@stably.ai>

* fix(perf): prove the icon cache by decode count, not wall clock

The caching test asserted a per-publish millisecond budget, which failed
on CI at 5.64 ms against a 5 ms ceiling. Any threshold flakes on a loaded
box, so count real sanitizeRepoIcon entries instead: 10 repos x 20
publishes is 200 icon checks against exactly 1 decode. Added cases pin
the cache key (payload and source both re-decode; a cached image verdict
never answers for an emoji) and that a rejection is cached too.

Also drops budget.entries, which the per-listing cap left as a
traversal-wide counter no check reads -- exactly the shape a future
guard could reintroduce the concurrency bug from.

Co-authored-by: Orca <help@stably.ai>

* fix(dashboard): bound the project filter label the whole board rides on

#11042 added snapshot-level filterOptions whose project labels are
repo.displayName -- the same unbounded source this PR already bounds for
card.repoName, but one level up where dropping a card cannot recover it.
An over-long project name would fail isDashboardFilterOptions and take
the entire snapshot with it, which is the exact frozen-board failure the
per-card drop was added to end. Workspace-status labels are already
capped at 32 by workspace-statuses.ts, so only projects needed this.

Co-authored-by: Orca <help@stably.ai>

* fix(dashboard): disambiguate the repo icon cache key

The memoization key joined `source` and `src` with a space, but the
sanitizer's base64 pattern admits whitespace inside a valid `src`. A
rejected icon can therefore split the same concatenation differently and
inherit an accepted icon's cached verdict, reaching the pop-out's
`<img src>` without ever being sanitized. Length-prefix the source.

Co-authored-by: Orca <help@stably.ai>

---------

Co-authored-by: Orca <help@stably.ai>
2026-07-28 17:08:14 -07:00
JinjingandOrcaWin a40183389b feat: bound direct SSH reconnect fan-out and recovery (#11003)
* docs: design for direct SSH reconnect fan-out

Capture the implementation-ready plan for host-qualified, epoch-fenced
SSH reconnect recovery after two rounds of multi-model LLM counsel review.

* docs: reconcile SSH reconnect fan-out design

* docs: close reconnect design consistency gaps

* feat: implement bounded direct SSH reconnect recovery

* fix: bound direct SSH retry settlement

* fix: harden direct SSH reconnect authority

* fix: preserve split SSH retry ownership

* fix: preserve SSH split continuation authority

* docs: record final SSH reconnect validation

* fix: preserve SSH authority through retained and detached state

* fix: retain SSH authority across delayed split mounts

* fix: close SSH authority recovery gaps

* fix: fence stale SSH transport replacement

* fix: serialize SSH target teardown

* fix: settle SSH teardown failures before reconnect

* fix: retire failed SSH reset sessions

* test: reconcile current main E2E contracts

* fix: close direct SSH reconnect review gaps

* fix: fence stale SSH reconnect side effects

* fix: close final SSH reconnect lifecycle gaps

* test: stabilize current-main reliability gates

* test: prove plugin navigation containment

* test: make plugin navigation oracle authoritative

* test: make plugin navigation oracle deterministic

* ci: allow sharded e2e suite to finish

* test: wait for runtime pane publication

* test: classify pane readiness by error code

* test: select close persistence terminal by tab identity

* docs: mark reconnect implementation validated

---------

Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
2026-07-28 12:33:17 -07:00