* fix(wsl): read machine output from a fenced login shell
Orca runs WSL reads through the distro's *interactive* login shell so
PATH matches the user's own terminal (nvm, mise and asdf only install
into rc files interactive shells read). An interactive shell also runs
the distro's rc/motd, and stock Ubuntu 24.04 writes its "run a command
as administrator" hint to stdout -- no user customization required.
Every caller parsing that stream was reading the banner as data:
statPath -> "To run a command as administrator...\n\ndirectory"
readPath -> banner prepended to the contents of every file read
preflight -> banner prepended to `gh --version` / auth output
`.trim()` cannot recover any of these, so a WSL worktree's file
explorer sees no valid entry types and file reads return junk.
Three call sites had independently grown their own marker to survive
this (`__ORCA_AGENT_PATH__`, `ORCA_WSL_GIT_READ_ENV_V1`, and a
`>/dev/null` fd dance), which is the tell that it belongs in one place.
Fence the payload once, in the shared builder, and hand callers a
reader that returns just their bytes. The fence carries a per-call
nonce so `cat`-ing a file that happens to quote a marker is not
truncated. Exit status is preserved, so the ENOENT mapping still works.
wsl-git-read-environment drops its bespoke marker and parsing.
* test(wsl): fence the login-shell path-lookup boundary test
It asserted a raw interactive login-shell read matched an absolute path,
so the distro rc banner made it fail on any stock Ubuntu. It is part of
the shell-contracts CI gate, where it skips on Linux and hid the break.
* docs(wsl): record the guest command-execution contract
Both failure modes are silent - the command runs, exits 0, and returns
the wrong bytes - so the rules need to live somewhere a reader will
find them before writing the next wsl.exe call site.
* fix(codex): fence the WSL Codex identity probe
buildWslCodexBinaryStamp reads the login shell's stdout positionally --
path before the first newline, version after -- through an interactive
login shell. On a stock Ubuntu the rc banner lands ahead of the payload,
so the first newline falls inside the banner and the stamp becomes
path="To run a command as administrator..." with the rest as version.
Both halves are non-empty, so nothing throws: the stamp is silently
wrong, and an unstable stamp reads as "the Codex binary changed" and
reissues the trust grant.
The identity script ends in `exec`, so it never writes a closing fence;
the reader returns everything after the opening one, which is exactly
this case.
buildWslCodexIdentityArgs becomes buildWslCodexIdentityProbe and returns
the reader with the argv so the two cannot drift apart. The other three
WSL Codex commands are deliberately left unfenced: availability is
exit-code only, and app-server/login hand stdout to a long-running
program.
* fix(wsl): harden the capture fence after review
- readStdout now takes the LAST opening fence, matching the lastIndexOf
the wsl-git-read-environment marker used deliberately: a login shell
can echo the command text before running it, repeating the fence.
- local-worktree-filesystem throws instead of falling back to raw stdout
when the fence is missing. The fallback silently reinstated the bug
being fixed -- statPath would return the banner as a file type and
readPath would return banner+contents, with no signal. Preflight keeps
its fallback; its matchers scan the whole blob and tolerate a prefix.
- The exit-status test asserted only that the script CONTAINS `exit $?`,
which is true for any input and never executed those lines. It now
runs a real distro and asserts status 2 reaches the caller, which is
what statPath's ENOENT mapping depends on.
- Corrected the doc: a sed backreference has no `$`, so `--` never
rewrote it. Replaced with the positional and shell-local cases that
were measured to differ.
* fix(wsl): stop running a login shell for filesystem reads
statPath/readPath/rm run coreutils at standard paths and shell builtins.
They need nothing from the user's PATH, so there was never a reason to
start a login shell -- and starting one is what put the distro's rc/motd
on the stdout these callers parse.
Fencing that output treated the symptom. Using a plain `sh -c` removes
the cause: no profile, no rc, no banner, by construction. The fence and
its missing-fence error go away with it.
The fence stays where it is actually needed: the three places that must
run the user's shell to resolve their PATH (the preflight CLI probe, the
WSL git environment probe, and the Codex identity probe).
Net -12 lines.
---------
Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
* build(xterm): restore the patch regeneration harness and gate it in CI
docs/reference/ime-architecture.md says "Never hand-edit the bundles in
the patch" and links to docs/reference/xterm-patch-regeneration.md. That
doc does not exist, and neither does the harness it describes.
Both landed in 29117bf776 and were deleted by 17cfc968cf, a revert of
the composition-ownership change, which swept up a build tool and a CI
gate as collateral. The rule survived; its enforcement did not. Every
xterm patch since has had to hand-edit minified bundles to comply with
the surrounding architecture, because everything resolves to
lib/xterm.mjs at runtime and under vitest, so a src-only edit is inert.
The shipped bundles were therefore not the output of any build, and this
restores them to build output. Comparing identifier multisets against a
pristine build of the pinned commit finds hand-written names a minifier
never emits ($rl, $hp, $tid), const in an otherwise let-only esbuild
bundle, !! where the source reads Boolean(), an escaped LRM where esbuild
emits the literal, and a return block esbuild collapses to void(...).
Every remaining token difference is a minifier local reallocating.
The old source patch could not be reused. It described the reverted
composition-ownership architecture, so restoring it would have re-applied
an abandoned design on top of dropping three accumulated fixes. It is
re-derived from the shipped patch instead, and the derivation is a fixed
point.
Two deliberate departures from the deleted version. Sourcemaps are
included rather than deleted, because a live test reads lib/*.map and
asserts the mapped version matches the runtime version. The source-patch
superset carve-out is gone, so a source hunk the shipped patch cannot
name now fails loudly instead of being carved out silently.
The doc's claim that the webgl and serialize addons reproduce byte for
byte was half wrong. Their ESM output does reproduce at the pinned
commit, but both also publish CJS that the root package script never
builds, so folding either in needs a build step this harness lacks.
Recorded as a blocker rather than a confident sentence.
xterm_patch_sync runs the regenerator in --check mode, so a patch that
does not match a rebuild of the pinned upstream now fails PR CI.
The -diff -text attribute is required, not cosmetic: pnpm hashes the
patch byte-for-byte, so a CRLF checkout breaks the install outright.
Not verified: the CI job has not run on a real runner, the addon CJS
bundles are unreproduced, and the generator is untested on Windows and
Linux.
* build(xterm): make the regenerator runnable on Windows and drop dead paths
Readiness review on the restore found one blocking gap and two cheap
cleanups. None of them change the emitted patch, which is byte-identical
before and after.
The generator could not run on Windows at all. Three sites called npm
through execFileSync with shell:false, but npm ships as npm.cmd there,
execFile applies no PATHEXT, and since CVE-2024-27980 it refuses a .cmd
target without a shell. That matters because this harness arms a
blocking gate whose documented remedy is --write, so a Windows
contributor who tripped the gate had no remedy except hand-editing a 7MB
minified bundle, which is the practice the gate exists to abolish. Four
sibling scripts in config/scripts already handle this; the fix follows
them and lands in run(), so the manifest-driven build step is covered
too. git and tar are real executables in System32 and keep resolving
without a shell, which avoids quoting exposure on paths with spaces.
deleteGeneratedSourcemaps was unreachable, since the policy is include.
Deleting it left "delete" as a legal policy value that nothing honoured,
so a manifest asking for it would have silently shipped sourcemaps that
do not match the bundle. The enum is narrowed and an unrecognised policy
now throws rather than falling through.
generatedHunks moved into the test file rather than being dropped; its
partition assertion, that generated and source hunks reconstruct the
whole patch, is worth keeping.
The -text attribute now covers all five patch files. pnpm hashes each of
them byte-for-byte, so the CRLF hazard the xterm patch was protected
from applies equally to node-pty and the three addons. All five were
already LF in the object DB, so this pins existing behaviour. -diff
stays scoped to the xterm patch, since the others are readable.
The doc's claim that the addons reproduce byte for byte is now dated and
marked a one-off measurement rather than an invariant, because nothing
re-runs it.
Effective lines fall from 591 to 568 against the 600 budget. Still the
largest file in config/scripts, and adding a second package to the
manifest would need a split first.
* 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.
* 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.
* feat(ssh): parse and match OpenSSH known_hosts
The matcher half of STA-4319. No behaviour change yet — nothing calls this.
Hand-rolled because no maintained JS implementation exists, and written against
behaviour observed from OpenSSH 10.2p1 rather than inferred from the man page.
Three of those behaviours a reasonable reading gets wrong:
- A non-default port is TWO ordered lookups, not one candidate set: '[host]:port'
first, then bare host ('checking without port identifier' in ssh -v). The
fallback pass can only yield match or unknown — OpenSSH downgrades a wrong key
there rather than reporting a change. Collapse them and anyone holding a bare
line who connects off-port gets a spurious first-contact result; treat the
fallback as authoritative and they get a false change-of-key alarm.
- Revocation resolves in its own pass so the verdict cannot depend on line order.
Verified both orderings.
- A cert-authority line never matches a plain host key; it only validates
certificates. A normal line alongside it still decides.
Mismatch is scoped to the same key type, and a host known by a DIFFERENT type
returns unknown-type-known-host rather than plain unknown — an attacker who
cannot forge the key on file must not get a friendly first-contact result by
presenting another type. That outcome is only half the defence; the other half
(leading serverHostKey with known types) lands with the wiring.
47 tests from vectors executed against real sshd, including ssh-keygen -H hashed
entries. Each of six mutations reddens it: collapsing the passes, letting the
fallback report mismatch, dropping type scoping, resolving revocation in line
order, honouring an unrecognised marker, and skipping the blob/type agreement
check.
* feat(ssh): decide what to do with a presented host key
The policy half of STA-4319, kept separate from the ssh2 wiring so it is testable
without a handshake and injected rather than importing its sources, so a test
states its own trust state instead of writing files.
Phase 1 ships no dialog — a test asserts the decision is never 'prompt'. Startup
restore opens every previously-active target at once, ephemeral VM targets would
ask every launch, and paired-web connects run on the host desktop where the
dialog would appear on someone else's screen.
Ordering that matters: revocation outranks everything including
StrictHostKeyChecking=no, because a revoked key is a statement that this key is
known-bad rather than merely unrecognised. known_hosts is named before our own
store on a change, because its remedy (ssh-keygen -R) is the one that also
unblocks ssh and git — pointing at a remedy that cannot work is worse than none.
Two carve-outs with reasons: an ephemeral runtime target accepts WITHOUT
recording, since a fresh VM presents a new key every launch and a stored record
would accumulate per launch and eventually read as a spurious change; and when
ssh -G ran on the HOME-divergent path that suppresses /etc/ssh/ssh_config, an
unknown host is denied, because a site-wide policy may forbid it and being laxer
than ssh is the one outcome that is never acceptable.
Rejection text deliberately avoids 'authentication failed' and 'permission
denied': the reconnect ladder classifies on those substrings, so a denial phrased
that way is retried forever against a decision that will never change. Pinned by
a test.
* feat(ssh): build the host key verifier and the algorithm order that makes it safe
Still not wired into the handshake — that lands next. This is the piece that
turns a decision into an ssh2 callback, plus the half of the design that is easy
to forget because it lives in a different config field.
The verifier MUST be a plain function returning undefined. ssh2 does
'const ret = verifier(key, verify); if (ret !== undefined) verify(ret)', so an
async function returns a Promise — neither undefined nor falsy — and ssh2 accepts
the key immediately while ignoring whatever the callback later decides. Making
this async would silently restore exactly the accept-everything behaviour the
module exists to remove, so a test asserts the return value is undefined.
orderServerHostKeyAlgorithms is what makes type-scoped matching safe rather than
a downgrade. RFC 4253 gives the client's algorithm order priority, so leading
with the types we already hold for a host denies a server the choice of
presenting some other type to convert a hard failure into first contact. Without
it, an attacker who cannot forge the key on file just offers a different
algorithm. Revoked entries never contribute to that order.
Also fails closed on two paths that would otherwise hang or over-trust: a key
whose own length-prefixed header cannot be read is refused rather than reasoned
about, and a throw from any dependency denies, because ssh2 may not catch an
exception raised inside the verifier and the handshake would hang instead of
failing.
18 tests. Includes the two negative cases that matter — first-contact keys are
recorded, but keys we already know, rejected keys, ephemeral runtime targets and
a lax StrictHostKeyChecking are not.
* fix(ssh): promote every RSA signature algorithm for a known ssh-rsa key
A known_hosts entry names the KEY type, which is not the negotiated ALGORITHM
name. One ssh-rsa key is offered as rsa-sha2-512, rsa-sha2-256 or ssh-rsa
depending on the signature algorithm, so matching the literal name only would
leave a host we know by RSA ordered behind ed25519 — precisely the ordering this
function exists to prevent, and precisely the population (RSA-era known_hosts
entries) it was written for.
Verified from ssh2's own negotiation while wiring this: kex.js iterates the
CLIENT list and takes the first entry the server also offers, so client order
does decide, as RFC 4253 says. ssh2's default order leads with ed25519 and places
the RSA algorithms fifth through seventh.
* fix(ssh): verify host keys instead of accepting every one (STA-4319)
The actual fix. ssh-connection's verifier recorded a fingerprint and returned
true, so every ssh2 connection accepted every host key — no known_hosts consult,
no change detection. It now consults the user's known_hosts plus our own store
and refuses a changed, revoked or unverifiable key.
Phase 1 by design: no dialog. Unknown hosts are accepted and recorded
(accept-new semantics), because startup restore opens every previously-active
target at once, ephemeral VM targets present a new key each launch, and
paired-web connects run on the host desktop where a prompt would appear on
someone else's screen. The MITM defence lands now; the prompt is Phase 2.
Also sets algorithms.serverHostKey to lead with the types already known for the
host. Without it the type-scoped matching is a downgrade — an attacker who cannot
forge the key on file just presents another type and turns a hard failure into
first contact. Verified from ssh2's kex.js that the client list decides.
Denial replaces ssh2's generic handshake error with the specific reason, because
the reconnect ladder cannot distinguish a generic failure from a transient fault
and would retry forever against a decision that will never change.
An unreadable trust store degrades to known_hosts only rather than failing the
connect: a changed key is still refused, and a host trusted only by us falls back
to first contact and is re-recorded, reaching the same decision.
The ssh2 mock now uses the callback form and aborts the handshake on denial. As
written it called hostVerifier(key) with one argument and ignored the result, so
it would have passed against a verifier that never decides — flagged in the
design as a mock that had to change, not a test to quietly rewrite. Two new tests
pin the wiring rather than the module: an unidentifiable blob is refused, and a
well-formed key is accepted.
Note for review: commit 2d2a0880ba unintentionally swept in two modules built
concurrently (ssh-known-hosts-source, ssh-host-key-store) because I staged with
'git add -A'; its message describes only the verifier. Both are covered by their
own tests, but the attribution in that commit is wrong.
1461 SSH tests pass.
* 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.
* fix(ssh): close two downgrades the implementation review found
Both were in my wiring, not the design, and two reviewers found the first
independently.
1. OUR STORE WAS TYPE-DOWNGRADABLE. The inline lookup filtered by key type first
and could only answer match/mismatch/unknown, so a record of a DIFFERENT type for
the same endpoint read as "unknown". A host learned on first contact — ed25519,
since ssh2 proposes it first — and absent from known_hosts could then be
impersonated by presenting RSA: both sources say unknown, so accept-and-remember,
silently. That is exactly the downgrade D3 says the design cannot ship without,
applied to the records we create ourselves. The store's own isTrusted already
computed the right answer and had no production caller. Stored types now also
feed the algorithm ordering, without which the guard is only half present.
2. WE KEYED ON THE ORCA LABEL, NOT THE DIALED HOST. "ssh -G" echoes its own
argument back as its hostname field when no Host block matches, so for a manual
target that field IS the Orca label — the one name D2 forbids keying on, and one
ssh never wrote. We consulted no entries at all, so an impersonated host read as
first contact. Now keys on the dialed host, which buildConnectConfig has already
resolved through HostName, with HostKeyAlias still winning.
That inverted an existing test rather than deleting it: "uses the resolved
hostname, never the Orca label" encoded an assumption disproved against OpenSSH
10.2p1, so it is renamed and reversed with the reason recorded in the test.
3. NO READABLE SOURCE IS NOT FIRST CONTACT. Every known_hosts file failing to
read was indistinguishable from "this host is unknown", so a changed key would be
accepted the one time we could not check. The loader now reports how many files
it could read, and zero readable sources with an empty store takes the strict
path instead of recording trust.
4. A superseded attempt's rejection could replace the live attempt's error, and
substituting a new Error drops ssh2's code, so a transient ECONNRESET would stop
being classified as retryable. The rejection is now local to its attempt.
5. displayHost was the Orca label, so a mismatch could print
"ssh-keygen -R <label>" — a remedy that removes nothing.
Also adds the tests that would have caught 1 and 2, the stale-attempt denial, and
IPv6 literals, which the design moved into scope and nothing covered.
1,469 SSH tests pass.
* fix(ssh): stop offering credentials to a host we just refused
A refused host key ended the handshake and then fell into the credential
ladder, because ssh2 reports a denied key as a generic auth failure and the
passphrase branch is eligible on message shape alone whenever an encrypted
identity file is configured. So the sequence was: decide this host may not be
who it claims to be, then ask the user for their passphrase and hand it to it.
Failing that, prompt for a password. Failing that, retry over the system ssh
binary, which for a disagreement with our own store rather than known_hosts
would simply connect.
That inverts the point of checking at all. A denied key is now final for the
attempt: recognised by type before any fallback runs, and again inside the
agent-fallback retry, which re-runs the handshake and so can be the attempt that
denies.
Two things had to change for that to hold.
The rejection is now a HostKeyVerificationError rather than a rebuilt Error, so
the connect path recognises it by type. Substring matching would have worked
today and quietly stopped working the first time a reason string was reworded —
and these strings are already worded around the auth-error classifier, so they
are exactly the kind that get edited.
And the verifier now reports the denials that skipped the policy: an
unreadable key blob and an internal failure both denied without calling
onDecision, so the connect path saw only ssh2's generic failure and walked the
ladder. That was the actual path the new test hit first. The report carries no
fingerprint, since there is no host key to identify, and the connection no
longer overwrites the fingerprint it holds with an empty one — the relay keys
install-lock isolation on that value.
The reconnect ladder also refuses to retry it. Its classifier is otherwise
substring-driven, so a reason containing "connection reset" would have been
retried until the ladder gave up, burying the reason under nine attempts.
Tests: no credential prompt after a refusal, an encrypted key configured so the
passphrase branch is eligible; refused reports as 'error', not 'auth-failed',
which would invite the user to re-enter credentials that are not the problem;
no retry; both bypassing denials report; a throwing listener still denies rather
than hanging the handshake.
Also drops three test files a bisect resurrected from before the revert that
deleted them.
172 tests pass across the three touched files; typecheck and lint clean.
Pre-existing on origin/main and untouched here: 3 failures in
ssh-connection-sftp-namespace.test.ts.
* fix(ssh): stop treating an absent known_hosts as a source we failed to read
The previous commit's "no readable source is not first contact" guard was right
about the danger and wrong about how to detect it, and the version that shipped
would have refused every connection a new profile ever makes.
A file that does not exist and a file that refuses to open both arrive as a
rejected readFile, and I counted them the same way. They are opposites. An
absent known_hosts is the normal state — ssh creates it on its own first connect,
and an Orca profile that has never connected has none — and it is real evidence
that no host is known. A file that exists and will not open is evidence withheld:
the entry that would have said "this key changed" may be sitting in it.
The default list is the reason this was fatal rather than obscure. It always
names known_hosts2, which essentially never exists, so on a machine with a normal
known_hosts the count was 1-of-2 and everything worked; on a fresh profile it was
0-of-2 and every connect failed with "the system SSH configuration could not be
read" — a message about a file the user does not have and an error they cannot
act on. The suite passed only because the machine running it happens to have a
known_hosts. Pointing HOME at an empty directory fails 62 connection tests, which
is what the new wiring test does.
So the count is now unreadableFileCount: files that exist and could not be read,
which is the condition the guard was always trying to express. Any one of them
takes the strict path; an absent or empty file takes none. The store clause is
gone with it — a store hit already returns accept before this is consulted, so it
never changed an outcome.
Tests: absent, empty, permission-denied, directory, and all-parsed at the source;
first contact with no known_hosts at all at the wiring level.
1,482 SSH tests pass. The 3 failures in ssh-connection-sftp-namespace.test.ts are
pre-existing on origin/main and untouched here.
* fix(ssh): let an ephemeral runtime outrank sources we could not read
Three things, all about the same question: when we cannot see everything that
decides a host key, what does that actually license us to refuse?
1. ON-DEMAND RUNTIMES WERE REFUSED FOR A POLICY THEY COULD NEVER SATISFY.
A machine provisioned a minute ago cannot be in known_hosts, by construction —
which is why it has a carve-out at all. But the carve-out sat BELOW the
incomplete-sources check, so anyone whose HOME diverges from their passwd home
(sandboxes, our own E2E isolation) took the `-F` path, and every on-demand
runtime connection was refused, pointing at a config file the user cannot fix.
Refusing there buys nothing. No policy, seen or unseen, is satisfiable by a host
that did not exist yesterday; the trust comes from the provisioning channel. So
the carve-out now outranks it. An EXPLICIT StrictHostKeyChecking=yes still wins
over both — that one we can read, and the user asked for it.
2. THE FLAG WAS NAMED FOR ONE OF ITS TWO MEANINGS.
`siteConfigSuppressed` started as "-F hid /etc/ssh/ssh_config" and had since
grown "a known_hosts file exists and would not open" — which is not a site
config, and reading the name in the decision function told you nothing about
why an unreadable file landed there. It is `verificationSourcesIncomplete` now:
we could not see something that decides this, so do not extend NEW trust. A host
we already know still connects, because a match is decided before this is
reached, and that is now pinned by name.
3. THE COPIED ssh2 ALGORITHM LIST HAD NO DRIFT ALARM.
We reorder ssh2's default host-key proposal, which meant hand-copying a list
ssh2 exports only from a deep internal path. ssh2 throws `Unsupported algorithm`
on anything outside its supported list, so drift does not degrade — every
target stops connecting, before a socket opens, with a message about an
algorithm the user never chose. Worth knowing that the list is also built
conditionally on ed25519 support.
Kept as a literal rather than a deep import, since silently adopting a new
proposal order is the wrong default — the order is what makes type-scoped
matching safe, so a change deserves review. A test now compares it against
ssh2's real constant and checks every entry is one ssh2 accepts. Moved next to
the ordering function it feeds, and out from between the import statements.
1,488 SSH tests pass. The 3 in ssh-connection-sftp-namespace.test.ts are
pre-existing on origin/main.
* 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.
* test(ssh): pin the ephemeral carve-out where it is actually observable
The first version of this test asserted an on-demand runtime connects on first
contact, which every target does — it would have passed with the carve-out
deleted. Pointing HOME at a home whose known_hosts exists and will not open makes
the two cases diverge: a normal target is refused there, an on-demand runtime is
not. Removing the carve-out now fails three tests instead of none.
Also covers the wiring for the unreadable-source refusal itself, which until now
was only pinned at the decision level.
* test(ssh): pin the parser against real ssh -G output, and accept-new against ask
Two gaps the audit named.
The ssh -G fixtures were all hand-written, which means they encode what I expect
ssh to print. This one is verbatim OpenSSH_10.2p1 output for a Host block using
HostName, HostKeyAlias, StrictHostKeyChecking accept-new, two UserKnownHostsFile
paths and a non-default port. The format detail that matters: each file list
arrives space-separated on ONE line, so reading it as a single path would consult
nothing for anyone with more than one file configured.
And accept-new was untested despite being a real OpenSSH value. It currently
behaves identically to ask, which is exactly right while no dialog exists and is
what lets the defence ship without a modal — so the equivalence is now pinned,
and Phase 2 has to break it deliberately rather than discover it. Plus a guard
that accept-new never falls into the strict branch.
* test(ssh): cover the wire from an accepted key to a record on disk
Nothing covered the store end to end. Every connection test runs with it
unwired — a real path, since it degrades to known_hosts only — so an accepted
first-contact key was never observed becoming a record, and the record was never
observed being believed on the next connection. Without that wire the store is
dead weight: an unknown host connects every time and is never learned.
Its own file for two reasons. initSshHostKeyStoreFile binds module-level state
for the rest of the process, and binding it makes the connect prelude do real
disk I/O — which the shared suite cannot absorb, because its reconnect tests
drive the clock with fake timers and an fs round trip does not complete inside an
advanced tick. Adding these there turned 12 unrelated tests red.
Covers: the record is written; it is read back as a match; the same key is not
recorded twice; a DIFFERENT key for a host we recorded ourselves is refused
(the store's entire security value, and a case known_hosts cannot catch since it
has never heard of the host); and an on-demand runtime records nothing.
Stubbing rememberHostKey to a no-op fails four of the five.
* fix(settings): stop truncating the SSH connection error to one line
The host key messages are written to be actionable — a mismatch ends in
"Run: ssh-keygen -R <host>", which is the remedy that also unblocks ssh and git.
The only place in the renderer that displays an SSH connection error clamped it
to a single line with `truncate` and carried no title attribute, so the remedy
was unreachable, not even on hover. The careful wording reached a CSS ellipsis.
Wraps instead, with [overflow-wrap:anywhere] because a long hostname offers no
break opportunity and would overflow the column on its own. The paragraph only
renders on failure, so the extra height costs nothing in the normal case.
CORRECTION to the four preceding commits: they each claimed 3 pre-existing
failures in ssh-connection-sftp-namespace.test.ts. That was my error — I had been
running `npx vitest` without `--config config/vitest.config.ts`, so the project's
setupFiles and execArgv were absent. Under the real config those 3 pass, and have
throughout. The whole SSH suite is green: 1,504 passed, 13 skipped.
Still failing on this branch and unrelated to it (different subsystems, no file
overlap): 5 in terminal-snapshot-osc8-roundtrip and 2 in browser-cookie-import.
* fix(terminal): show why the SSH connection failed, not just that it did
The reconnect overlay took only a status, so every failure rendered the same
sentence: "The SSH connection to devbox failed. Connect again to continue this
terminal session." A refused host key and a network timeout were indistinguishable
there, and the host key message — the only place that names the remedy, down to
`ssh-keygen -R <host>` — reached no terminal user at all. The state carried it the
whole way; the overlay simply never asked for it.
Adds it as a second line rather than replacing the sentence. The sentence says
what to do, the detail says what happened, and keeping both means an errno
failure does not lose its guidance to make room for "connect ETIMEDOUT". Wrapped,
for the same reason as the settings card: the remedy is at the end.
Suppressed for a removed target, which already explains itself and can never
reconnect — a stale connection error underneath would contradict it.
The new selector mirrors selectRuntimeAwareSshStatus branch for branch, including
the unreachable-environment and un-hydrated-bucket nulls, so the pair cannot
disagree about which source they read and a detail is never shown next to a status
it did not come from.
Known and NOT addressed here: "Connect again" is still the wrong advice for a
decision that will never change. Telling those apart needs a typed reason on the
wire rather than a string, which is a remote-wire-compatibility decision; it is
recorded in the STA-4319 follow-ups.
Pre-existing on this branch and untouched: 2 failures in
terminal-ime-xterm-resumed-preedit-visibility.
* 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.
* refactor(ssh): give the store one matcher instead of two
The connect path had its own copy of the store comparison, because ssh2's
verifier decides synchronously and cannot await the file, so records are
preloaded. That copy is precisely where the type downgrade came from: it answered
only match/mismatch/unknown, so a record of a different type for the same
endpoint read as first contact and a host learned on first contact could be
impersonated by presenting another key type. Fixing it left two implementations
that have to agree forever, which is the same bug waiting to happen.
matchTrustedHostKeys is now the single pure matcher; isTrusted is a load plus a
call to it, and the connect path calls it directly on preloaded records. Same for
the key types that feed the algorithm ordering, which the connect path was also
filtering by hand.
The two copies had in fact already drifted: the connect path lower-cased the
query host where the write trims AND lower-cases. Not reachable today — the host
is trimmed before it reaches there, which I confirmed by mutating the
normalisation and watching the wiring test pass anyway. So this is not a bug fix,
and the wiring-level test I first wrote for it proved nothing and is gone. The
unit test that replaces it drives the matcher directly, where the input is mine
to control, and it does fail when the normalisation diverges.
Also adds an equivalence test across all six outcomes between the preloaded and
awaited paths, so the two can never answer differently again.
Restores the local name siteConfigSuppressed for the `-F` check; it was renamed
along with the decision input, but at that site it really does mean only the one
thing, and the union with the unreadable-file count happens one line later.
1,509 SSH tests pass.
* test(ssh): check the matcher against a live OpenSSH client, not against my beliefs
Every other test in the parser file states what I believe ssh does. These state
what it did: an OpenSSH 10.2p1 client against a real sshd on 127.0.0.1:2222, with
the client's own verdict recorded from its output, and ssh-keygen -H's own salt
and hash pinned as a vector.
Two assumptions the design leans on were worth more than an argument.
THE FALLBACK PASS MAY NOT REPORT A CHANGE. We look up `[host]:port` first and
retry the bare host, and only the first pass may answer `mismatch`. With
StrictHostKeyChecking=accept-new, a bare line holding a DIFFERENT key, dialed on
2222, ssh connected and appended a new `[127.0.0.1]:2222` line — no
IDENTIFICATION HAS CHANGED banner. It read that as first contact. Had we reported
a change there we would refuse hosts ssh connects to happily, and the wrongness
would have been invisible: refusing looks like the cautious choice.
AND THE TYPE-SCOPING REJECTION IS NOT AN INVENTION. known_hosts holding an ssh-rsa
key while the server offers ed25519 makes ssh print IDENTIFICATION HAS CHANGED and
refuse. So unknown-type-known-host is neither stricter nor laxer than ssh —
treating it as first contact, which is what a naive type-scoped lookup does, is
the laxer mistake.
That second result also fixes the message. ssh is blocked too, so
`ssh-keygen -R <host>` is the remedy that unblocks both, and we were naming it
only for a same-type mismatch — leaving this case with a diagnosis and no way
out. Named now when known_hosts is the source that disagrees, and still not named
when it is our own store, which ssh-keygen would not touch.
1,516 SSH tests pass.
* 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.
* style(ssh): satisfy the code-quality lints in the two new test files
A string concatenation that should be a template literal, and an inline
import() type annotation that should be a type-only namespace import — erased
before vi.mock's hoisted factory runs, so the mock is unaffected.
pnpm lint is clean.
* fix(ssh): honour StrictHostKeyChecking, which had never once been read correctly
`ssh -G` does not echo the value the user wrote. StrictHostKeyChecking is
rendered through fmt_multistate_int, which prints the first entry of
multistate_strict_hostkey, and that table lists true/false before yes/no:
yes -> true | no -> false | off -> false | accept-new -> accept-new | ask -> ask
Verified against OpenSSH 10.2p1 from both a config file and -o. Not
10.2-specific; the table ordering is old.
The decision function tested only 'yes'/'always' and 'no'/'off' — spellings that
cannot arrive. So `StrictHostKeyChecking yes` fell through to the default branch
and we accepted AND PERSISTED a host the user's config explicitly says to refuse.
That is the worst outcome this feature can produce, and it was the behaviour for
every strict user from the first commit. `no`/`off` landed there too, breaking
the documented "lax settings never persist" invariant.
Every unit test passed throughout, because they fed the function 'yes' — the
value a human writes, not the one that reaches the code. My ssh -G parity test
did capture real output, but I happened to configure accept-new, one of only two
values that round-trip unchanged. The new table is keyed on configured value ->
what ssh -G actually prints, and asserts both reach the same verdict, so the
question "is this the spelling that arrives?" cannot be assumed again.
Found by a parity review against a live OpenSSH client.
* fix(ssh): stop the fallback pass accepting a changed key, and refusing a new one
One wrong loop scope, two opposite errors, both reproduced against a live
OpenSSH 10.2p1 client and an ed25519-only sshd on 127.0.0.1:2223.
ACCEPTING A CHANGED KEY. ssh runs the bare-host fallback only when the
port-qualified lookup matched no plain entry of ANY key type. We ran it unless
pass 0 produced a match or a SAME-TYPE mismatch. So with an off-port RSA entry
plus a bare, correct ed25519 line — an ordinary shape, an old off-port entry
beside one written by a port-22 connect — ssh printed IDENTIFICATION HAS CHANGED
and refused, with no "checking without port identifier" in -v because the
fallback never ran, while we reached the bare line and returned `match`.
REFUSING A NEW ONE. sawKnownHostOtherType and sawCertAuthority were declared
outside the pass loop, so an entry found only on the fallback pass could set
them. A bare ssh-rsa entry, dialed on a non-default port against an ed25519-only
server, made ssh add the host and connect — plain first contact — where we
returned unknown-type-known-host and hard-failed. That is Gitea/Forgejo, dev
containers, Gerrit, Vagrant: an off-port service on a host already in
known_hosts.
So the flags are per-pass now, and pass 0 decides as soon as it finds any plain
entry for the host. Which of the two rejections it reports only picks the
message; ssh calls both HOST_CHANGED.
Also drops the type check from the match test: byte equality already implies the
types agree, because the blob carries its own algorithm name and parsing rejects
any line whose declared type disagrees with it.
Reverting either half of the scope fix fails exactly the two new tests.
1,526 SSH tests pass.
* fix(ssh): refuse the known_hosts lines ssh itself refuses to parse
Three ways a line could be trusted by us and invisible to the user's own ssh —
or, worse, raise a CHANGED alarm from an entry ssh drops.
Buffer.from does not fail on bad base64, it SKIPS invalid characters, so
`<key>!!!` and a blob with `@@` spliced into it both decoded to the correct key
and matched. Verified live against OpenSSH 10.2p1 on 127.0.0.1:2224: the
unmodified control reached authentication and all three malformed variants
produced "No ED25519 host key is known". A re-encode-and-compare makes us agree.
`<key>AAAA` is the interesting one, and the reason the first fix was not enough:
68 characters plus 4 is still legal base64, and the algorithm header still reads
ssh-ed25519, so neither the base64 check nor the existing header check sees
anything wrong. ssh parses the whole key structure. We decoded 54 bytes where an
ed25519 key is 51 and reported `mismatch` — a man-in-the-middle warning caused by
a typo in a file ssh silently ignores.
So the blob is now walked as what it is: a run of length-prefixed fields that
must consume it exactly. Algorithm-agnostic on purpose, so a key type we do not
model is checked as well as one we do. It also rejects a length prefix that
overruns the buffer, which readHostKeyType only checked for the first field.
And ssh's extract_salt demands exactly one SHA1 digest — "expected salt len 20,
got 16" — where we accepted any non-empty salt. A short salt is still a usable
HMAC key for us, so a hand-crafted line could match for us and be a parse error
for ssh. ssh-keygen -H always writes 20 bytes, so refusing loses no real entry.
Worth recording that ssh-keygen -F cannot answer any of this: it matches host
names and prints lines without ever decoding the key, so it reports "found" for
all four blobs. The real client was the only instrument that worked.
Found by a parity review; the base64 finding as reported was right about the
behaviour and wrong about the mechanism for the padded case, which is what led to
the structural check.
1,533 SSH tests pass.
* fix(ssh): name a ssh-keygen -R target that actually removes the entry
Verified against OpenSSH 10.2p1: with both `[h.example]:2222` and `h.example`
on file, `ssh-keygen -R h.example` removes only the bare line and leaves the
bracketed one — and there is no port flag, `-R host -p 2222` is "Too many
arguments". An off-port target is keyed `[host]:port` in known_hosts, so the
command we printed removed nothing: the user runs it, reconnects, and meets the
identical failure with no indication of why.
The message now names the bracketed form, quoted because the brackets are shell
glob characters, whenever the port is not 22.
Found by a parity review.
* fix(ssh): read ssh2's host key algorithm list instead of copying it
ssh2 builds DEFAULT_SERVER_HOST_KEY at load time and prepends ssh-ed25519 only
when a RUNTIME PROBE succeeds — it signs and verifies with a fixed Ed25519 key.
On a build where that probe fails, ssh-ed25519 is absent from ssh2's SUPPORTED
list too, and generateAlgorithmList throws `Unsupported algorithm: ssh-ed25519`
from inside client.connect. That throw matches no retry classifier and no
transport-fallback classifier, so it is permanent — and because we only set
`algorithms` for hosts we already know, it would fire on trusted hosts while new
ones kept working. A copied list cannot be merely stale here; it can be wrong.
So it is read from ssh2 now, which also removes the drift risk the previous
commit could only report. ssh2 is external in the main bundle and the bundle is
CJS, so the deep path resolves at runtime from packaged node_modules.
The copy stays as a fallback in case a future ssh2 moves the file — losing the
proposal order degrades the type-scoping guarantee, but refusing to connect at
all is worse. The test that used to pin the copy against ssh2 now pins the
fallback, which is the only part that can still drift.
Found by an availability review.
pnpm lint clean; 1,537 SSH tests pass.
* fix(ssh): look a HostKeyAlias up the way ssh does — without the port
HostKeyAlias suppresses the port entirely. Verified against OpenSSH 10.2p1 on
port 2225 with HostKeyAlias=myalias: an entry keyed `myalias` authenticates, and
one keyed `[myalias]:2225` gives "No ED25519 host key is known for myalias". We
built [['[alias]:port'], ['alias']] and consulted a form ssh never writes.
On its own that was a stale-entry false alarm. The previous commit made it worse:
now that the first pass decides as soon as it finds any entry for the host, a
leftover `[alias]:2225` line STOPS the bare lookup ssh actually performs — so the
one population D2 cites HostKeyAlias for, bastions tunnelled through
localhost:port, would get a hard failure on a host ssh connects to.
So resolveKnownHostsLookupHost reports whether the name came from the alias, not
just what it is, and that flag reaches both the matcher and the algorithm
ordering. Returning the name alone is what made the bug invisible: the caller had
no way to know it was holding something that must not be bracketed.
Found by a parity review.
1,543 SSH tests pass.
* fix(ssh): only claim the site config was suppressed when ssh -G actually ran
sshGArgsForHost reports which arguments WOULD be used, not what happened. It
returns the -F form whenever ~/.ssh/config exists and os.homedir() diverges from
the passwd home, so a machine with no usable ssh at all — Windows without
OpenSSH, a restricted sandbox, a timed-out probe — was judged by whether it
happens to have a ~/.ssh/config, and rejected every unknown host permanently if
it did. The same broken machine WITHOUT one stayed fully permissive, which is the
tell: the flag is a claim about a config file we could not read, and when ssh
never ran there is no such claim to make.
Narrow but total where it lands: anything that sets HOME explicitly (wrapper
scripts, sudo -E, devcontainers), macOS mobile and network accounts, and the E2E
isolation this branch was written for.
Found by an availability review.
* fix(ssh): stop refusing hosts that ssh itself connects to
Two product decisions, both taken deliberately after a review priced their blast
radius, and both moving us from stricter-than-ssh to matching it.
CERTIFICATE-AUTHORITY HOSTS NO LONGER FAIL. The point of an SSH CA is that the
client holds ONE line — very often `@cert-authority *` — instead of per-host
entries. That line matches every candidate, so for a Teleport / Vault-SSH /
Smallstep / in-house-CA user EVERY target failed, not just CA-signed ones,
including on-demand runtime VMs, and StrictHostKeyChecking=no did not help. The
documented escape was an environment variable, which an Electron app launched
from the Dock or Start Menu never sees. Meanwhile OpenSSH, verified live, treats
a CA-covered host presenting a plain key as first contact and connects: ssh2
cannot validate certificates at all, so refusing bought nothing ssh was not
already giving up. The residual risk is real and accepted — for a CA-protected
host we take a plain key we cannot tie to the CA — and the ca-only outcome is
carried through the decision so it stays visible in the log.
AN UNREADABLE known_hosts NO LONGER REFUSES EVERYTHING. Any non-ENOENT read
error on any configured file rejected every unknown host, with a message blaming
the system SSH configuration, which was not what happened. The common trigger is
not exotic: a Windows OneDrive Known Folder Move placeholder while offline fails
with a cloud-file error, not ENOENT. It was also asymmetric with our own store,
which degrades an unreadable file to "nothing trusted" and connects. We now
connect as ssh does — it warns and treats the host as unknown — but record
NOTHING, so a first contact we could not check never becomes durable trust. That
second half is the reason the first is acceptable, so it is pinned end to end
with the store actually bound.
Which meant splitting verificationSourcesIncomplete back apart. It had been one
flag for two claims that now diverge: "a site policy may exist that we cannot
read" still refuses, "a file we could not open may contradict this" does not.
Merging them was what made the second inherit a strictness only the first
justified.
Both still lose to evidence we DID read: a mismatch, a revoked key, or an
explicit StrictHostKeyChecking still refuse in either state.
pnpm lint clean; 1,549 SSH tests pass.
* 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.
* fix(ssh): repaint the panes after a reconnect, not just reattach them
Reported: disconnect an SSH host from the Remote Hosts popup, reconnect, and the
terminals come back blank — but resizing a split or toggling the sidebar makes
them render correctly.
That last detail is the diagnosis. The panes were never broken: reattach restores
each pane's buffer but not its painted frame. xterm repaints on a write or a
resize, and a reconnect produces neither for a pane that was already correctly
sized — so nothing paints until a relayout forces it, which is exactly what
resizing or toggling the sidebar does.
The renderer already has refitAndRefreshAllTerminalPanes for this shape ('after
bulk desktop restore, background panes may have correct cols/rows but a stale
xterm renderer until focus forces a repaint'). Its only callers were the mobile
fit-reclaim paths; the SSH reconnect path never used it.
Scheduled from finalizeHydratedTerminalPanes, on both a frame and a 100ms settled
pass — the same pattern the desktop-restore path uses, because rAF alone lands
while panes are still remounting.
Mutation-proved: removing the schedule reddens the new test, which is the
reported symptom.
* fix(ssh): repaint background-tab panes revealed after a reconnect
Completes 834a495038, which only fixed the ACTIVE tab. Reported: split panes of
plain shells on another tab were still blank after reconnect until a divider drag
or a sidebar toggle.
The repaint did reach background managers — they stay mounted, only
rendererVisible flips — but it could not land. A tab-hidden pane measures as a
0-size box, so canMeasurePaneForFit bails and the fit is a no-op, and
refreshAllPanes marks rows dirty on a pane with no presented frame, which cannot
repair a grid the reattach's direct terminal.resize left diverged. The reveal
then takes the light resume path, which deliberately does not fit, and
scheduleRevealRepaint only reattaches WebGL. So nothing ever fixed the geometry —
and a divider drag or sidebar toggle is a real fit, which is why those appeared
to work.
Parks the repaint on a hidden manager and replays it on reveal, reusing the
existing reveal-fit machinery rather than adding a mechanism. Flag-gated so the
light path still does not fit in the ordinary case — 'does not fit on a light tab
reveal' stays green.
Splits are not special: the gap is per-manager, so it is identical for 1 or N
panes. Splits just expose it, because users find the workaround (drag a divider)
that a single full-tab pane rarely gets. A never-mounted tab is unaffected — it
has no live manager and fits through the normal initial-fit lifecycle.
Mutation-proved twice: removing the deferral, and reverting the reveal-side
condition. Each reddens only the new tests.
* test(terminal): pin that panes are PAINTED, not merely bound — and fix a broken commit
Two problems, both mine.
1) 0103a80b48 swept in an untracked fixture and left the branch failing
typecheck (unused Terminal import in painted-pane-fixture.ts). Its canvas stub
also threw 'clearRect is not a function' on every refresh. Fixed here.
2) direct-ssh-reconnect-repaint.test.ts, which I wrote to guard the reconnect
repaint, is VACUOUS: it re-implements finalizeHydratedTerminalPanes inside the
test and mocks the registry, so deleting the real fix from useIpcEvents leaves it
green. direct-ssh-reconnect-repaint-wiring.test.ts replaces that guarantee by
capturing the real callback the hook hands the coordinator and running it against
live panes — deleting the two scheduling lines now reddens it.
The gap this closes: content survival was already well covered at the BYTE layer
(snapshot roundtrip, hide/reveal stitching, cold-restore scrollback), but every
pane test stubbed terminal as {cols, rows, refresh: vi.fn()}, so 'repainted' only
ever meant 'a spy fired'. No test ran a real xterm through a real PaneManager.
pane-content-survival.test.ts does, reading .xterm-rows — what the user actually
sees — across reconnect, restart-shaped restore, tab reveal, window show, split
and unsplit, for plain shells and alt-screen TUIs.
The alt-screen distinction is now pinned explicitly: forcing a resize inside
fitAllPanes reddens only the TUI test, because a plain shell reflows and survives
while a TUI frame does not. That asymmetry is why the reported bug looked like a
plain-shell problem.
11 tests, each mutation-proven to redden only its own. 760 pane-manager tests
green; the 2 failures here are the known environmental IME baseline.
Flagged, not fixed: the unsplit path reparents the DOM without the dispose/
reattach that splitManagedPane does explicitly because 'DOM reparenting can
silently invalidate a WebGL context without firing contextlost', and follows it
with a safeFit that no-ops when the box is unchanged. Same shape as the reconnect
bug. happy-dom has no WebGL, so only a real-GPU E2E can confirm it.
* fix(ssh): send the pane its screen back on reconnect
A reconnect left every remote terminal blank. Measured on a live relay, not
inferred: pty.attach returned no replay for every pane, taking the
activation === 'existing' early return in the relay's attach.
'existing' means a source delivery is already open for this client, so it must
already be receiving live output and cannot need its screen re-sent. That holds
for a duplicate attach. It is false for a reconnect, for a reason neither side
can see alone: the client keeps its id across the drop (detachClient refuses to
detach the primary, and setWrite revives that same id) so the delivery outlives
the dead transport, while the RENDERER has already thrown its terminal away. A
reconnect bumps tab.generation, which is the pane's React key, so TerminalPane
remounts and the old xterm is disposed with its buffer, and nothing on that path
captures it first. Both halves are individually reasonable and together they
guarantee a blank pane: the relay reports the client already has the screen, to a
client holding a brand-new empty terminal, and nothing paints until new output
happens to arrive. Resizing appeared to fix it only because a TUI redraws itself.
So the client says which case it is. reattachSshPtySession is by definition
painting into a new terminal, so it asks; nobody else does, and the early return
keeps working for them. Optional on the wire, so an older relay ignores it and
behaves exactly as it does today.
Falling through rather than returning the replay inline is deliberate: the path
below already drops the pending batched bytes that are also in the buffer, which
is what stops the live delivery rendering them twice.
Reproduced first as a test against the real dispatcher, source publication and
PTY handler (the second attach for one client, which is what a reconnect is) and
it fails on the exact symptom before the fix. A second test pins that a caller
which does NOT ask still gets nothing, so this cannot become a double-render for
the duplicate-attach case the early return exists for.
Also updates four provider tests that assert the exact attach params.
NOT yet verified in the running app; the log will show replay=true on reconnect.
* chore(ssh): drop the temporary reconnect-replay diagnostic
Served its purpose: it is what turned 'the panes look blank' into
replay=false, replayLen=0 on every pane, and then into replay=true with real
byte counts once the relay fix landed. The permanent log line keeps the boolean,
which is the part worth having.
* revert: drop the reconnect repaint commits; they cannot fix the blank panes
Reverts 2fdab478c0, 34fc1424f0 and dc6f6bf685, which I cherry-picked onto
this branch to test alongside the host key work.
Their stated premise is 'reattach restores each pane's buffer but not its
painted frame'. That is false for this flow: a reconnect bumps tab.generation,
which is the pane's React key, so TerminalPane remounts and the old xterm is
disposed WITH its buffer, and nothing on that path captures it first. Refitting
and refreshing a terminal whose buffer is empty paints an empty pane. The blank
screen was the relay declining to re-send the scrollback, fixed separately and
verified on screen.
Their tests pass without exercising the real case: the fixture blanks the
painted rows and deliberately LEAVES THE BUFFER INTACT, which is the one
situation that never occurs here, and the hidden-tab test replaces the pane
manager with a stub that reports no panes.
They may still address a separate symptom — a diverged grid after a resize on a
hidden tab — but that is unproven, unrelated to this branch, and the originals
are untouched on nwparker/sta-3077-fix-v3 where they came from. Carrying
unproven renderer changes with a false premise in their message on a
security-focused branch is not worth it.
Reverting first and re-running the full two-step reconnect test is the point:
the earlier verification passed with these present, so it did not establish that
the relay fix stands alone.
* fix(ssh): repaint a reconnected pane from the grid, not a byte tail
A reconnect restored plain shells correctly but was reported to bring full-screen
apps back as fragments of a frame — Claude Code showed a few rules and its cost
line until a resize forced it to repaint.
The two payloads are not interchangeable. Relay replay is a byte TAIL: it can
begin mid-escape, and it misses the alt-screen enter, the clears and the absolute
cursor positioning that built the frame, so replaying it into a fresh terminal
paints whatever fragments survive. The model snapshot is a serialized GRID —
which is what tmux repaints on attach, and the only payload that reliably
restores a TUI.
Orca already had the grid path and already preferred it; it was gated to PARKING.
A reconnect needs it for the same underlying reason a park does: the pane paints
into a terminal holding nothing, because a reconnect bumps tab.generation, which
is the pane's React key, so TerminalPane remounts and the old xterm is disposed
with its buffer. So the gate now admits both, and prepaintParkedSshSnapshot is
prepaintSshModelSnapshot since parking is no longer the only caller.
Deliberately NOT inheriting the parking kill switch: main keeps its headless
model regardless of terminalSshViewParking, so a user who turns view parking off
would otherwise be stranded on the tail.
Every safety gate below eligibility is untouched, and pinned that way: null,
renderer-sourced, sourceless, empty, and escape-tail-only snapshots all still
degrade to relay replay, so widening WHY the model is trusted cannot widen WHAT
is trusted and cannot regress to a blank pane. Reverting either half of the gate
fails three of the new tests.
HONESTY ABOUT WHAT THIS IS VERIFIED TO DO. I could not reproduce the corruption
it targets. Two attempts against a live host, both on a build WITHOUT this
change, both restored correctly: a freshly started Claude Code and Codex side by
side, and an alt-screen `less` scrolled 4000 lines so its original full paint had
aged out of the relay's 100KB tail. The reporter's case also involved pulling
wifi — an abrupt drop rather than a clean disconnect — which is the one variable
I cannot simulate here.
So this is verified to be correct-by-construction and non-regressing: with it
applied, the same scenarios still restore correctly (top live, less at its
scrolled offset in alt-screen, both agent TUIs coherent). It is NOT verified to
fix the reported symptom, because the symptom did not reproduce. Treat the
symptom as open until someone confirms it on an abrupt drop.
Also: top was a poor proxy for a TUI in my earlier verification precisely because
it repaints every second and therefore self-heals within a tick.
* fix(ssh): stop the reconnect prepaint firing after its mount is spent
Regression I introduced with the snapshot-first reconnect paint. The payload path
consumes mountFollowsTerminalPark — it clears the flag after the first reattach
so a later in-place reconnect on the SAME mount cannot repaint. I replaced the
prepaint's read of that mutable flag with a const snapshot of it, so my combined
flag stayed true for the life of the mount. A snapshot could then be written on a
later reattach, into a terminal that already had live content, and its own
isCurrent() guard could no longer go false either.
The visible symptom was a tab that came up blank with no prompt and stayed
generically titled Terminal N — the title only stays generic when the shell never
printed a prompt for Orca to read one from. Every such tab in my session had been
through a remount; four tabs created cleanly with Cmd+T were all fine.
So the flag is mutable again and is consumed alongside the one it was derived
from. Both reasons a mount paints into an empty terminal — a park and a reconnect
— are spent by the first reattach, which is what the original code meant.
Worth stating plainly: my earlier claim that the snapshot change was
non-regressing was tested only against reconnect scenarios. I never exercised
creating a tab afterwards, which is exactly where this showed up.
* test(ssh): cover what a pane SHOWS after a reconnect, and after a new tab
The gap that let both regressions reach a user. Nothing asserted the rendered
pane: the existing SSH coverage checks pty ids, statuses and spy calls, and every
one of those was correct while the screen was blank.
Covers one flow end to end against the dockerized relay: write a marker,
reconnect, require the marker to still be on screen, then open a tab and require
the new shell to answer.
Three choices worth keeping:
A MARKER, NOT A PROMPT. A prompt reappears on its own after a reconnect, so
asserting one cannot tell restored scrollback from a fresh shell. The marker only
exists if the pane kept what it had.
ECHO, NOT EXISTENCE. The new tab must run a command and show its output. A pty
id proves a session was created; it does not prove the pane is usable, which is
the exact distinction the reported bug lived in.
AND THE TAB TITLE. It stays 'Terminal N' only when the shell never printed a
prompt for Orca to read one from, which is what the report showed and the
cheapest signal available.
Gated on ORCA_E2E_SSH_DOCKER=1 like the other relay specs.
* chore(ssh): rename the snapshot prefetch off its park-only name
The probe serves reconnect remounts as well now, so parkedSshSnapshotPrefetch
described only half of what it holds.
* revert: drop the snapshot-first reconnect paint; unproven and it regressed
Reverts e6541fe9b8, its follow-up c497a26788, and the rename f680a0b1cb.
The reasoning behind it still looks right — a byte tail cannot rebuild an
alt-screen application, a grid snapshot can, and that is what tmux repaints on
attach. What I could never do is show it fixing the reported symptom. Two
attempts to reproduce the corruption on a build WITHOUT it both restored
correctly: freshly started Claude Code and Codex, and an alt-screen `less`
scrolled 4000 lines so its full paint had aged out of the relay's 100KB tail.
Meanwhile it cost two real regressions. It fired on mounts that were not
reconnects, leaving a new tab with no prompt and a placeholder title, which a
user hit within minutes. The fix for that consumed the eligibility flag with the
one it was derived from — and after it, a reconnected Claude Code came back as
fragments of a frame, the exact symptom the change was meant to remove. So the
consume-once semantics that stop stale paints and the repaint a reconnect needs
are in direct tension, and I do not yet understand the ordering well enough to
satisfy both.
Shipping an unproven change that has already broken two things twice is worse
than shipping the blank-pane fix alone, which IS reproduced, A/B'd and visually
verified. The TUI corruption goes back to open — but now with something it never
had before: a reproduction. It shows up on a reconnect against a Claude Code
that has been running a while, not one just started, which is why my earlier
checks kept passing.
The e2e coverage stays. It asserts what the relay fix guarantees — a marker
surviving a reconnect, and a tab opened afterwards reaching a shell that answers
— and neither of those depends on this change.
* docs(ssh): name the root cause the reconnect replay fix does not address
requireReplay fixes the blank pane at the symptom. The cause is that a PTY
source delivery is the only per-client relay state that outlives its client
detaching: fs-handler, git-handler and relay-filesystem-watch-registry all
subscribe to dispatcher.onClientDetached and release theirs, and
relay-pty-source-publication never does. The primary client keeps its id across
a transport replacement, so its delivery survives a dead transport and
activate() answers 'existing' to a client that cannot receive anything.
Retiring the delivery on detach is the real fix. Not doing it here is a choice,
not an oversight — it is the flow-control and credit path, and I could not
verify it before handing this over. Recorded in the test that guards the
symptom, which is where someone changing this will actually look.
* docs(ssh): record the three root-cause routes that do not work
I went after the cause and failed three times. Each attempt looks correct until
it runs, so the dead ends are worth more written down than the time they cost:
RETIRING THE DELIVERY ON onClientDetached — the obvious fix, and the one I
argued for, since fs-handler, git-handler and the watch registry all release
their per-client state exactly there. It breaks checkpoint recovery: 10 tests
across relay-pty-source-recovery-interleavings and restore-retry. A delivery
outliving its client is DELIBERATE; that is what lets a reconnecting client
resume from a checkpoint instead of re-receiving everything. This class omits
the subscription on purpose, and that omission is not the bug.
RETIRING WITHOUT session.cancelDelivery() — the credit ledger keeps one upstream
owner per pty, so dropping the record without releasing it leaves the slot
taken and the next open throws 'PTY source delivery already has an upstream
owner'. I saw that live as an error toast over a blank pane.
COMPARING clientGeneration — the delivery identity carries one, but it is
client-supplied through pty.openClient and RequestContext has none to compare
against, so the relay cannot tell the generations apart on its own.
Which points where I would start next, unverified: the SSH client presents the
SAME clientGeneration across a reconnect, so the relay cannot distinguish the new
connection and reuses its delivery. reattachSshPtySession never sends
sourceRecovery at all — the recovery protocol exists and the SSH reattach path
simply does not participate in it. That is likely the real fix, and it is on the
client, not in the relay.
The symptom fix stays because it is verified and the tree is green; the cause
stays open with a map instead of a guess.
* fix(ssh): repaint a reconnected full-screen app from the grid
A reconnected TUI came back as fragments of a frame — Claude Code showed a few
rules and its cost line until a resize made it repaint itself.
Relay replay is a byte TAIL. It can begin mid-escape and it misses the
alt-screen enter, the clears and the absolute positioning that built the frame,
so replaying it into the fresh xterm a remount just created paints whatever
fragments survive. Main already keeps the thing that does restore a frame: a
real @xterm/headless grid, alt-screen aware, fed unconditionally for SSH. Local
terminals already repaint from it; SSH was the only path that did not.
So this routes an SSH reconnect into the painter that already exists, at the one
expression that chooses model over tail. No new call site, no second lifecycle,
and every existing gate still applies — a null, renderer-sourced or empty
snapshot still degrades to the tail, so it cannot paint blank.
ONLY ON THE ALTERNATE SCREEN, and that is the whole design. The reconnect replay
reaches the renderer without passing through main's model — forwardReattachReplay
and the inline attach replay both bypass onPtyData — so at that moment the model
is stale by exactly the outage. For a full-screen app that trade is right: a tail
cannot rebuild a frame it no longer contains, a grid can, and the SIGWINCH the
restore already sends makes the app redraw the delta. For a scrolling shell it
would be wrong: the tail holds output the model never saw, and preferring the
grid would drop it for good. A park has no such hole, so it keeps using the model
either way.
Derived from the PENDING retry, not directSshRetryAttempt. That also matches the
live binding, which is written at the same tab generation once a reconnect
succeeds and then outlives it — so it stays truthy for every later remount of
that generation. Reading it directly is what made my first attempt fire on mounts
that were not reconnects. Consumed alongside mountFollowsTerminalPark for the
same reason.
Verified live against the reported app: Claude Code restores identical to its
pre-disconnect frame, top restores coherent and live, and a plain shell still
shows output written before the disconnect. 5,470 tests pass across the touched
suites.
Not the whole story, and the remaining half is already written down: the model's
gap exists because the SSH reattach asks for a tail instead of participating in
the checkpointed resume the relay already implements. Close that and this paint
is not merely coherent but exactly correct, for shells too.
* test(ssh): cover a full-screen frame across a reconnect, not just scrollback
The case a byte tail cannot serve, and the one that reached a user twice. A tail
can begin mid-escape and misses the alt-screen enter and absolute positioning
that built the frame, so replaying it paints fragments — which is what a
reconnected Claude Code showed.
Uses top: present on any Linux image, and it repaints on a fixed interval, so a
whole header after the reconnect is unambiguous rather than a timing artifact.
Asserts the header AND the column row, because a tail that lost the frame start
still shows rows.
The spec now covers all three payloads one reconnect has to get right: a shell's
scrollback, a full-screen app's frame, and a tab opened afterwards reaching a
shell that answers.
* ci(e2e): actually run the Docker-SSH specs in the changed-specs lane
"I am surprised this was not caught" has a mechanical answer: these tests do not
run. A spec that reads ORCA_E2E_SSH_DOCKER test.skip()s itself when it is unset,
and exactly one place in CI set it — gated on tests/e2e/ephemeral-vm-provisioned-
root.spec.ts being among the changed files. So editing any SSH spec ran it as a
skip and reported green. Eighteen specs reference that variable, including both
reconnect regressions I have been chasing.
Now it is also enabled when any changed spec references the variable, which is
the same grep -l idiom the @headful check two lines below already uses. The
original clause stays: that spec needs Docker without naming the variable, so
replacing it rather than adding to it would have traded one silent skip for
another.
Simulated against the real files — the reconnect spec, the original trigger, a
multi-spec change, a non-Docker SSH spec, and a deleted path — enabling in the
first three, staying off in the last two, and not failing the step on a path that
no longer exists.
* fix(ssh): let the replay veto a stale alternate-screen belief
Adversarial review of the previous commit found a case where it is worse than
the bug it fixes, and it is the exact inverse of what that commit reasoned about.
The model reports alternateScreen from bytes it consumed, and it never consumes
the outage. So if a full-screen app EXITS during the disconnect — an agent
finishes, a command ends, the process dies — the model still says alternate. The
gate then painted a frozen frame of an application that no longer exists and, via
the else-if chain, discarded the replay carrying the shell's real output. Frozen
and wrong beats fragments, which were at least current bytes.
The replay is the only witness to the outage, so it now gets a veto: its last
47/1047/1049 transition, if any, outranks the model's belief. Leaving reset means
the frame is gone and the tail wins; re-entering means the model is right after
all. Same review found the width-mismatch guard drops the alt frame and leaves a
cleared screen for the app to repaint — free for a park with no tail to lose, but
here it meant discarding a usable one for a blank pane, so that degrades too.
Both vetoes are skipped when there is no replay, where they would only trade a
stale frame for an empty one.
Extracted as sshReconnectPaintsFromModel rather than more inline ternary, because
every interesting case is a disagreement between a stale belief and a replay —
awkward to stage end-to-end, trivial to state as a table. 14 unit tests, including
the two that fail against the previous commit. The e2e comment is corrected in the
same spirit: top redraws itself, so it never discriminated the paint source and
should not have claimed to.
Also from the review: the kitty flag stack was left stale on this path, since the
app's pushes during the outage exist only in the replay we discard — scanned now,
after the snapshot so the outage layers on the pre-outage baseline. And the
consume-once comment asserted an invariant that does not exist;
followsDirectSshReconnect is a const captured per connect, bounded by
connectStarted and the gates rather than by the read. Corrected rather than
restructured.
Known and NOT fixed, because it predates this work and is a behavior change of
its own: the model probe is gated on the terminalSshViewParking kill switch, so
turning off view parking also silently disables this repaint. Defaults on.
* docs(ssh): make the parking kill switch's reach over the reconnect repaint deliberate
Review flagged that terminalSshViewParking silently disables the full-screen
reconnect repaint, since both go through the same model probe, and that nothing
said so.
Keeping the coupling and documenting it rather than threading a reason through.
The switch is the kill for painting an SSH pane from main's model at all, and a
reconnect does exactly that; off should restore the relay-tail behavior that
predates the machinery, which is what an escape hatch is for. That matters more
than usual here: this repaint is new and review already found one case where it
was worse than the bug, so a way to turn it off in the field is worth its cost —
a user who disables parking also loses the reconnect repaint.
The alternative is worse than it looks anyway: the probe memo is keyed on ptyId
and shared with the park path, so a per-call reason would be reused by whichever
path created it first.
* docs(ssh): record why the obvious reconnect follow-up does not work
I proposed making the pane-retry path request source recovery the way
reattachKnownPtys does, and argued it was probably client-side routing. Tracing it
says the wiring is indeed trivial and the checkpoint state does survive a drop —
and that the change would still be wrong three ways, one of them harmful.
The relay short-circuits to 'existing' on a same-clientId attach BEFORE it looks
at the recovery argument, and the reconnecting client has already rotated the
delivery onto its id. A failed reattachKnownPtys then deletes the checkpoint on
purpose, so a later pane retry presents checkpointUnavailable, which becomes
restoreRequired and then SSH_SESSION_EXPIRED_ERROR — trading a blank pane with a
tail for a killed session. And the payloads answer different questions anyway:
recovery replays the post-checkpoint delta to keep main's model whole, while the
tail is a screen snapshot for a fresh empty xterm. Even a successful recovery
would put almost nothing in a remounted pane.
Also corrects the argument I had been leaning on hardest. "Old relays ignore
requireReplay, so those users still get blank panes" is false for the SSH relay:
the client deploys its own relay into a version-scoped directory and rejects any
grant whose serverBuildId differs, because client and relay ship in one build.
Mixed versions cannot occur on this channel. The independent-update rule still
governs remote runtime hosts, just not this one — so there is no stranded
population, and the urgency that framing created was imaginary.
What replaces it is a sharper question. Source recovery is gated on
outputFlowControl and on the client presenting a NEW clientId. We have empirical
evidence it does not: the blank-pane bug existed because the relay concluded this
client already held the stream, and the shipped fix works by bypassing that exact
early return. If the id is reused, reattachKnownPtys' recovery hits the same
short-circuit — meaning checkpointed recovery may never have run for SSH
reconnects, and the tail is not a fallback but the only path. Whether that is so
turns on daemon versus stdio-primary relay mode, which I did not verify and which
decides whether the work is "extend recovery" or "recovery has never run here."
* docs(ssh): the root cause — checkpointed recovery never runs on a reconnect
Chasing why the pane-retry path could not request source recovery turned up the
real answer: nothing can. Recovery is dead on every SSH reconnect, and the byte
tail is not a fallback but the only path that has ever run.
Five links, each read rather than inferred. setWrite reuses primaryClient
including its id, so a reconnected client presents the SAME clientId. activate()
tests exactly that at line 99 and returns 'existing' at 108, which makes the
rotateDelivery branch at 118-142 reachable only when the ids differ — never here.
So no sourceRecovery comes back, so finishSourceRecovery fails its
!pendingRecovery guard and abandons, cancelling the delivery and deleting the
checkpoint. The pane retry then opens fresh and takes the tail.
This also explains the blank panes exactly. The relay concluded that this client
already held the stream because, by its own identity rule, it does.
The fix that implies is smaller than anything proposed so far and avoids what
sank the three earlier attempts: bump a transport generation on the client record
in setWrite and compare it alongside clientId, so a reconnect rotates the delivery
instead of matching as 'existing'. Deliveries still outlive their clients and
nothing retires on onClientDetached — the rotation happens on re-attach, which is
what the recovery design already intends. RequestContext, setWrite and the
publication are all relay-internal, and client and relay ship in one build, so
there is no wire change and no compatibility exposure.
Left explicitly unverified: whether rotateDelivery's identity preconditions hold
at that moment, whether outputFlowControl is granted on the reconnected session,
and what a rotation gives the RENDERER — which still remounts an empty xterm and
needs a screen, not a post-checkpoint delta. Recovery keeps main's model whole; it
does not by itself repaint a fresh terminal, so the tail may still be wanted for
the pane even once the model stops going stale.
* ci(e2e): run the Docker-SSH specs when SSH SOURCE changes, not just specs
The earlier fix only helped when a spec file itself changed. Edit pty-connection,
pty-handler or ssh-relay-session and touch no test — which is what every one of
these regressions actually looked like — and the lane still did not run.
pr.yml now maps SSH source paths onto five Docker-backed specs. Five rather than
all fifteen because the rest are covered by unit tests that prove the same source
without paying for a container; that is a deliberate narrowing and this comment is
where it is admitted rather than left implicit. Test files are excluded from
triggering, since they prove themselves.
Simulated against the real paths this PR touches: pty-connection.ts,
pty-handler.ts, ssh-relay-session.ts and ssh-pty-session-reattach.ts all now pull
the SSH specs in, while pty-connection.test.ts, ssh-known-hosts.test.ts,
SshTargetCard.tsx and README.md correctly do not. The gate contract test covers
the mapping: 11 pass.
e2e.yml pays for it — 30 to 45 minutes, because the lane can now build a container
image and run SSH specs serially on top of whatever changed — and installs
openssh-client, which the fixture shells out to and which the lane did not need
back when it never received these specs.
* test(ssh): make the reconnect spec actually run — it now fails on a real bug
It had never executed once. The CI condition that enables Docker-SSH was gated on
an unrelated spec, so this skipped and reported green — and running it for the
first time found two bugs in the spec itself, both of which a typechecked tests/
would have caught instantly.
startDockerSshRelayTarget returns a DockerSshRelayTarget, which has no targetId;
the id comes from connectDockerSshRelayTarget's return value, which the spec
discarded. So every reconnect call passed undefined and the relay answered
'SSH target "undefined" not found'. And openNewTerminalTabInActiveWorkspace takes
the group to open into; called with no argument the new tab lands nowhere.
The third problem was the fixture rather than the spec. The image ships Debian's
/etc/bash.bashrc with the xterm title block commented out and an all-comments
/root/.bashrc, so its shell never emits OSC 0 — which is what Orca derives a tab
title from. The title assertion could not have passed for any shell, healthy or
not, so it was proving nothing. enableDockerSshRelayTargetShellTitle opts a spec
into the title-setting PS1 a real user's shell already has.
IT STILL FAILS, and that is the point: it fails on a PRODUCT bug it was written to
catch. An SSH reconnect destroys the terminal state behind a tab whose local
creation has not yet reached the host. remote-workspace-session-merge.ts:86-89
spreads the host's tab list over the local one for that worktree, so a local tab
missing from the host snapshot has no surviving branch; the upload that would have
put it there is DROPPED rather than deferred inside the 1s suppression window
after a snapshot apply. The tab bar still renders the tab, correctly titled, but
the terminal slice holds one tab and no pane manager exists for the second — so
the user clicks a tab that never paints, with no error and no recovery, while the
process keeps running on the host.
Pre-existing: none of remote-workspace-target-sync.ts,
remote-workspace-session-merge.ts, use-app-session-persistence.ts or
remote-workspace-snapshot-apply.ts is touched by this branch, and nothing in the
merge range touches them either.
Not worked around here. Waiting for the upload would hide it, and a user opening a
tab right after a reconnect has no such signal to wait on.
An earlier version of this message claimed the spec passes. It does not; I had
seen five green runs out of six and generalised from them. Sustained runs are
about three in eleven before the merge and zero in four after.
* chore(e2e): add a typecheck entry point for tests/, unenforced for now
tests/ has never been typechecked. That is how a spec could read target.targetId
off a type with no such field, and call a function without its required argument,
while the suite reported green — the spec was skipping, so nothing ever
disagreed with it.
Pointing tsc at tests/ finds both immediately. It also finds ~198 errors across
~94 files, which is a cleanup project rather than a change to make here, so this
ships as pnpm typecheck:e2e and is deliberately NOT added to the typecheck chain
or to CI. An unenforced script is worth less than a gate, but it is worth more
than nothing: it is runnable, it is discoverable, and the header says plainly
what it is so nobody mistakes it for coverage we have.
runtime-types.ts is the one fix included, because it was actively misleading:
every PaneManagerLike method was optional, so every call site was a
possibly-undefined invocation that TypeScript could not help with. They are real
methods on a real instance. Also widens AppStore to the StoreApi that
window.__store actually is.
* test(ssh): separate the reconnect paint guard from the tab-destruction bug
The paint guard was failing about two runs in three, and after the merge every
run, for a reason that has nothing to do with painting. It staged its full-screen
check in a tab it had opened AFTER a reconnect — which is exactly the tab an
unrelated session-sync bug destroys on the NEXT reconnect. Two independent
failures were riding on one assertion, and the one that fired was not the one the
spec is for.
Running top in the ORIGINAL tab fixes it. That tab predates every reconnect, so it
is in the host snapshot and survives. No assertion changed, none were weakened,
and the new-tab case simply moves after the full-screen case rather than before
it — it still opens its tab after a reconnect, which is the regression it exists
to cover. Five consecutive runs pass at ~13s, against three in eleven before.
The bug itself is not swept up. ssh-reconnect-tab-destruction.spec.ts records it
as a fixme with the mechanism written down: session-merge spreads the host tab
list over the local one, so a local tab missing from the host snapshot has no
surviving branch, and the upload that would have put it there is dropped rather
than deferred inside the 1s window after a snapshot apply. It is worse than a
vanishing tab — the tab bar keeps rendering it, correctly titled, while the
terminal slice has dropped it and no pane manager exists, so the user clicks a
selected tab that never paints, with no error and no recovery, while the process
runs on untouched.
fixme rather than a workaround because waiting for the upload would hide it, and a
user opening a tab right after a reconnect has no such signal to wait on. It is
pre-existing: none of the four files in that path is touched by this branch, and
nothing in the merge range touches them either.
Also lifts openTerminalTab into a shared helper, since both specs need it and the
group argument it must pass is the kind of thing worth stating once.
* fix(ssh): stop a reconnect deleting local state the host has not seen
Reported from a 60-second manual test: reconnect an SSH workspace and the app
drops to the home screen, a second tab running pnpm install is gone entirely, and
one launched agent is listed twice. Three symptoms, one cause.
The snapshot is applied as the whole truth for the reconnecting target. The tab
merge iterates only the host's worktrees, then the result is spread over a gap
where every local tab for that worktree has just been dropped — so a tab created
locally whose upload has not landed has no branch that keeps it. Not a race: it
cannot survive. Same for the pointers, where a snapshot that names no active
worktree nulls activeWorktreeId and activeWorkspaceKey, which is the home screen
while the user's terminals are still running.
So the host is now authoritative for what it knows and not for what it has never
been told. A local tab absent from the snapshot is kept, the worktree union is
used so a snapshot with no entry for it at all cannot erase it, and a null active
worktree only defers to local state when that workspace demonstrably still exists
in the merged result.
Two guards this change had to earn rather than assume. A null activeTabId is NOT
missing information — it is a deliberate deselect that arms the duplicate-tab
repair, and my first attempt defeated it and broke that test; it is honoured
verbatim now. And preserving by tab id alone reintroduces the duplicate agent,
because the host can carry the same session under a new tab id, so the preserve
also checks the remote session id — the identity that survives a tab-id change.
Testing, which is the part that failed here before. Eight tests fail on the
unfixed code and pass on this one, at two levels: the merge decision table, and
the real apply path driven through a store. The end-to-end version of the same
scenario is deliberately NOT the guard and now says so in its header — measured
against unfixed code it only reproduces about one run in three, because the
destruction needs the tab created inside the debounced upload's suppression
window and nothing external can force that. Its earlier green run is exactly why
this shipped.
* fix(ssh): let agent session history recover once the relay is ready
Reported against the adhoc build: a workspace whose editor was loading remote
files perfectly still showed "SSH relay is not ready" and "0 shown · 0 recent" in
the Agent Session History panel, permanently.
That string is what the relay throws before it is ready, which is ordinary at
startup and again for the window a reconnect leaves the session not-ready. The
panel had three refresh triggers — mount, window refocus, and a newly seen agent
session id — and none of them fire when the relay simply becomes ready. So a
transient startup error became a stuck panel next to a workspace that plainly
worked, which is why the report described it as broken while everything else was
fine.
The file explorer already recovers from exactly this, off exactly this signal,
with the rationale written down at use-file-explorer-tree-load-effects.ts: it
loads before SSH providers are registered, so it retries when
sshConnectedGeneration bumps. This panel simply never did. Same idiom, same gate —
only retries when there was a prior error, so a local workspace or one that
already listed fine does not rescan every time some unrelated host connects.
Two tests in the existing suite. The retry one fails on the unfixed code with
"the panel never retried after SSH became ready"; the second pins the gate, since
a retry that fires on every connection bump would turn one bug into a rescan
storm.
* fix(worktrees): name the create route when a raw filesystem error escapes
A worktree create over SSH failed with a bare
"ENOENT: no such file or directory, lstat '/home/neil/projects/orca-test1234'".
That message names nothing. An lstat is Node's LOCAL filesystem, so hitting one
against a path that lives on an SSH host means creation ran a local
implementation for a remote repo — but the user cannot know that, and neither
could I without re-deriving the routing by hand and then failing to reproduce it.
worktrees:create picks between three implementations, and the order matters:
isFolderRepo is consulted BEFORE connectionId, so a folder-kind repo on an SSH
host never reaches the remote path at all. Which route ran, and what the repo
looked like when it was chosen, is the entire diagnosis — and it is knowable
exactly at the throw site, where the decision was just made. So it is stated
there now: route, repo kind, connection id, path, and the original message.
Deliberately additive and deliberately narrow. Only ENOENT/EACCES/EPERM are
rewritten; a git failure, a relay-not-ready, or a validation error already says
what went wrong and burying it under a worse message would be a regression. The
original error is kept as `cause`, so anything matching on `code` or reading the
stack is unaffected.
This does NOT fix the reported failure — I could not reproduce it. On current
code I created a worktree at that exact path, at a second path, with a leftover
directory already present remotely (correctly suffixed -2), and with the SSH
target disconnected (clean actionable error, no ENOENT). What it does is make the
next occurrence identify itself in one screenshot instead of costing another
investigation.
* fix(ssh): recognise a missing path reported by the relay
Creating a worktree over SSH failed with a raw
"ENOENT: no such file or directory, lstat '/home/neil/projects/orca-test1234'".
The path was the one about to be created, so its absence was correct. The caller
asks exactly that question — remotePathExists returns false on ENOENT — and could
not get an answer, so it rethrew at the user instead.
The trace log settles where the error comes from, and it is not where I spent a
long time looking. The stack starts at SshChannelMultiplexer.handleResponse: the
lstat ran on the SSH HOST, and the failure travelled back as JSON-RPC. An lstat in
an ENOENT message is normally Node's local filesystem, which sent me hunting for a
local fs call on a remote path; there is none.
handleResponse rebuilds the error as `new Error(msg.error.message)` and then sets
`code` from `msg.error.code` — the TRANSPORT's numeric JSON-RPC code. Node's
'ENOENT' string code does not survive that, and isENOENT tested only for the
string, so a remote missing path could never be recognised as missing. Every
caller of that predicate asks the same question, so this was wrong for all of
them, not just worktree create.
The message is now consulted as well, matched on Node's full canonical phrase so a
branch name or log line that merely contains the word cannot make an existing path
look absent — that would silently skip a collision check rather than report one.
Fixed on the client because it holds for every relay version, including ones
already deployed; teaching the relay to send the original code would only help
hosts redeployed afterwards.
The two other copies of this predicate, in filesystem-rename-collision and
git-discard-path-safety, are deliberately left alone: both run against a local
filesystem — one inside the relay, one on the desktop — where the string code is
intact and broadening would only add false positives.
Seven tests, three of which fail on the unfixed code: the relay-rebuilt error, the
same error through the IPC wrapper the renderer sees, and one carrying no code at
all.
* revert: drop the worktree-create error-context wrapper
Written to make an unexplained ENOENT self-identifying when creating a worktree
over SSH. The cause is now known and fixed — the error came back from the RELAY
and isENOENT could not recognise it, because the multiplexer rebuilds a remote
error with the transport's numeric code — so the wrapper is scaffolding for a
solved problem.
Worse, its central claim is false. It reported 'the remote (SSH) path failed on a
local filesystem call', and the trace log shows the lstat ran on the SSH host, not
locally. Keeping a message that asserts the wrong thing about the one failure it
was built for is worse than not having it.
183 lines and a rewritten error at the IPC boundary, removed.
* docs(ssh): drop a comment claim about older relays that is not true
The requireReplay comment said the field is optional on the wire so an older relay
ignores it. It cannot happen: the client deploys its own relay into a
version-scoped directory and validateGrant rejects any grant whose serverBuildId
differs, so client and relay are the same build by construction.
The field IS optional, which is why the relay reads it as !== true — that part
stands on its own and needs no story about versions. A comment asserting a
compatibility property the code does not have is worse than no comment, because
the next person plans around it.
* fix(ssh): act on the host key review — three must-fixes and two hazards
M1. A stale record of ours outranked known_hosts, so the remedy we print did not
work. `ssh-keygen -R host` then reconnect leaves known_hosts holding the NEW key
while our store still holds the old one, and the store was consulted first — the
one state that cure produces was the one state we refused. Permanently, since
nothing in the app clears the store. known_hosts now decides a match first, which
concedes nothing: it is the artefact ssh itself obeys, so an attacker who can
rewrite it has already won. Both directions of the precedence are pinned now; the
rotation case fails without this change.
That leaves one rejection known_hosts cannot cure — a host trusted only on first
contact that later rotates its key. "Remove the saved key" named nothing a user
could find, so it now names the store file.
M2. A superseded attempt could put a passphrase prompt in front of a host we had
just refused. The verifier deliberately does not record a rejection for an attempt
nobody is waiting on, so nothing identified it and ssh2's generic handshake error
walked the credential ladder. Guarded on the generation, which catches it whatever
the error turned out to be. Deliberately NOT by rejecting with a cancellation: an
existing test pins that connect() still reports the raw late-startup error, and
that behaviour did not need to change to fix this.
M3. Every unknown host was refused whenever HOME diverges from the passwd home —
devcontainers, `su`, Nix shells, some corporate launchers — because `-F` makes ssh
ignore /etc/ssh/ssh_config and being blind to a site policy was treated as reason
to refuse. Being blind is only a reason to refuse if we cannot go and look, so it
now asks ssh for the system config on its own and takes the stricter of the two.
Only a probe that fails leaves the strict rule standing. Costs one `ssh -G` on the
rare path that already needed -F.
N1. A rejected key's fingerprint was still adopted, and the relay scopes install
locks by it — locks keyed to a host we refused to talk to.
N2. The fallback algorithm list re-introduced the throw its own comment describes.
ssh2 prepends ssh-ed25519 only when a runtime probe succeeds, so on a build where
that probe fails, proposing it makes generateAlgorithmList throw inside
client.connect — and only for hosts we already know. Not reading ssh2's list is a
reason to leave its defaults alone, not to guess: it returns null now and the
caller skips reordering.
1555 tests pass in src/main/ssh.
* docs(ssh): state the merge's real trade instead of claiming it has none
The preserve comment said a genuinely closed tab is never in the local list,
because closing removes it. True for a close on THIS client; false for one closed
on another client sharing the host, where the tab is still local, still absent
from the snapshot, and now kept.
That is a deliberate trade, not an oversight — absence cannot distinguish 'never
uploaded' from 'closed elsewhere', and the outcomes are not symmetric: keeping a
tab a moment too long is recoverable by closing it, deleting a live one with a
process in it is not. But the comment asserted the case could not arise, which is
the kind of claim that gets planned around. Now stated, and pinned by a test so
the next person can see it was chosen rather than missed.
* fix(ssh): stop a newer host key store being silently downgraded
The store writes a version and never read it back. A file from a future Orca would
have had every record dropped by validateRecord — the shape would not match — and
then been REWRITTEN as version 1, so a rollback silently discarded whatever that
version knew. Trust records are user-owned state; losing them costs a
first-contact prompt per host and, worse, re-establishes trust from nothing.
v1 is the only place this can be made safe, because v2 cannot retrofit a v1 that
already clobbers it. A newer file is now left alone: nothing is trusted from it,
and trustHostKey declines to write rather than downgrade. The check sits inside
the snapshot queue so it cannot be separated from the write by another writer, and
declining is not an error the caller fails on — the key still verified, and the
next connect re-derives the same decision from known_hosts.
The test writes a version-99 file and asserts it is byte-identical afterwards; it
fails on the unfixed code with the file rewritten as version 1.
* perf(ssh): skip the reconnect snapshot probe the replay has already ruled out
Every SSH reconnect paid up to the 750ms model-snapshot timeout, including the
ones where the answer was discarded. The gate needs the snapshot's alternate-screen
flag, so the probe looked unavoidable — but one of its two vetoes does not: if the
replay shows the app LEFT the alternate screen, no snapshot can be used whatever it
says.
Asking that first costs a regex over the replay and removes the probe entirely for
that case. It also shrinks the window that matters most: the await sits inside the
structural replay coordinator with live PTY bytes deferred, and the payload can be
superseded while it runs.
Behaviour is unchanged — sshReconnectPaintsFromModel returns false for a null
snapshot exactly as it did for a fetched one it then vetoed, and its tests still
pin both vetoes.
* test(ssh): cover the site host key policy probe
It shipped untested. Three cases, and the third is the one that matters: a system
config naming no policy answers 'ask', not null, because parseSshGOutput fills the
OpenSSH default — and that distinction is exactly what the caller keys on. Null
means 'we could not look', which is the only state that keeps refusing unknown
hosts; a successful read that sets nothing clears the blindness without relaxing
anything, since strictestHostKeyChecking leaves the user's value alone against
'ask'.
I expected null there and was wrong about my own code; the test now records the
behaviour rather than my assumption. Also pins that the probe passes the null
device and terminates its args with -- so a host starting with '-' stays a host.
* fix(ssh): three release blockers from the readiness review
P1-1 was my own fix from the previous round, and it was wrong. I claimed
`ssh -G -F /dev/null` reads the system config while excluding the user's. It does
not: -F excludes /etc/ssh/ssh_config too, which sshGArgsForHost's own comment says
and I quoted before contradicting. Confirmed live against OpenSSH 10.2p1 — plain
`ssh -G` reports the sendenv lines from /etc/ssh/ssh_config, `ssh -F /dev/null -G`
reports none. So the probe returned built-in defaults on every machine, the
fail-closed guard never engaged, and a site-wide StrictHostKeyChecking yes was
silently ignored while we accepted AND durably recorded a key the user's own ssh
refuses. That is worse than the lockout it was meant to fix.
There is no ssh-only way to ask this, so the file is read directly — and the
question asked is deliberately weaker than "what is the policy". Anything
ambiguous (unreadable, an Include that will not resolve, the directive present at
all) answers yes and the caller stays fail-closed. Only a site config that
demonstrably says nothing about host keys clears it, which is the common case that
was being punished. Includes are followed, since macOS and most distros ship
`Include /etc/ssh/ssh_config.d/*` and missing that would read as "no policy" on
nearly every machine that has one. strictestHostKeyChecking goes with it: there is
no separately-read site value left to merge.
P1-2. `ssh -G` prints UserKnownHostsFile unquoted and space-separated even when
the config quoted it — verified the same way. One path containing a space is
therefore indistinguishable from two, and splitting shreds
C:\Users\John Doe\.ssh\known_hosts into fragments that resolve to nothing. Every
fragment misses with ENOENT, which reads as "absent" rather than "unreadable", so
the user appears to know no hosts and a CHANGED key is accepted as first contact.
The filesystem is the only thing that can disambiguate, so it decides: if no
fragment exists but the rejoined path does, it was one path. A list where any
fragment exists is a genuine multi-file config and is left alone.
P1-3. oxlint is a PR gate and this diff failed it on two lines. Both fixed —
including by splitting the replay on ESC rather than matching it, which is
equivalent since every private-mode sequence begins right after one, and respects
no-control-regex instead of suppressing it.
That gate failure is on me twice over: I reported LINT clean repeatedly while
filtering oxlint's output with a grep that could never match its
`path:line:col: error` format. Verification is by exit code now.
5183 tests pass; each fix has a test that fails without it.
* fix(ssh): the readiness review's P2s
P2-1. activeRepoId and activeWorktreeId could describe different workspaces. The
repo followed the host while the worktree came from local state, and it split in
exactly the case the preservation exists for — "the host named no worktree" is
precisely when it can still name a repo. All three active-* fields now derive from
whichever worktree won, rather than each picking a source. The nested ternaries
that hid it are gone.
P2-2. The trust-source reads sit AHEAD of client.connect, and readyTimeout only
covers the handshake — nothing wrapped attemptConnect. A home directory on a
stalled NFS or SMB mount made readFile hang forever, leaving the connection wedged
in `connecting` with no ladder entry and no recovery. Bounded at 5s, reusing the
existing withTimeout helper. The fallback is the one an unreadable file already
produces — evidence withheld, connect as ssh does but record nothing — not the far
worse "no hosts known" that would let a changed key through as first contact.
That helper absorbs rejections into its fallback, so the store's catch had to move
INSIDE the timeout; wrapping the other way silently swallowed the warning that is
the only signal the store is unwired rather than merely slow.
P2-4. doSsh2Connect runs up to five times per attempt as the credential ladder
advances, and each run re-read every known_hosts file, re-read the store, and
re-scanned the system config. Nothing writes those while a handshake is in flight,
so they are read once per attempt — which matters more now that each read can cost
up to 5s. Keyed by connect generation rather than cleared, so a superseded attempt
can never hand its sources to the live one.
P2-3. forgetHostKey was exported, tested and referenced by nothing. The
store-mismatch rejection now names the store file, so the case it was meant to cure
has a cure without it; an exported API nothing can reach is unverified in
production. Removed until D5 ships its UI, and the doc says so.
P2-5 needed no change: the site-policy branch it called dead is reachable again now
that the probe reads the real config.
The design doc drifted from the code in the two places this review checks, and both
are corrected: revocation now propagates for the ordinary rotation because a
known_hosts match is decided first, and the -F blindness is resolved by reading the
file rather than by refusing.
* fix(ssh): rejoin a spaced known_hosts path even beside an ordinary one
The whole-list check only fired when NOTHING in the reported list existed, so a
config naming both a spaced path and an ordinary one kept the spaced one in
fragments — the ordinary path existing was enough to leave it alone. The file the
user actually verified their hosts in then never got read, which is the same
failure the rejoin exists to prevent, just harder to notice.
Longest run first now: the longest sequence of tokens that resolves to a real file
is taken as one path and the scan continues after it, falling back to the single
token when no run resolves. A genuinely absent path is still reported as-is rather
than invented.
The mixed case fails against the previous version.
* test(ssh): pin the site config scanner's edge cases
This control decides whether an unknown host is refused when we cannot see the
site policy, and my first attempt at it was a security regression, so the cases
that decide 'policy present' deserve to be written down rather than assumed.
Seven, and each could have gone the wrong way. A commented-out directive must NOT
read as a policy or the lockout returns for every distro shipping the line
commented. A directive inside a Host or Match block MUST read as one, because no
attempt is made to evaluate whether the block applies — guessing wrong in the
permissive direction is the failure that matters. The equals form counts;
StrictHostKeyCheckingExtended does not. A nested Include is followed, since a
policy one level down is still a policy. An Include cycle terminates and answers
false, which is knowledge rather than doubt: both files were read in full and
neither mentions it.
All seven passed as written, so this pins behaviour rather than fixing it.
* test(ssh): assert tab survival, record the reattach gap rather than flake on it
Running the two SSH e2e specs — which neither review executed — showed the
tab-destruction spec failing on liveness three times out of three. The screenshot
disproved the obvious reading: the marker was on screen, echoed by a live shell.
getTerminalContent resolves the store's active tab id and returns '' when
paneManagers has no entry under it, which is indistinguishable from 'the shell said
nothing', and across a reconnect those two disagree.
Scanning every mounted pane instead fixed the read, and then measured the real
thing: three runs in four. The tab survives every time; the reattach behind it does
not. So the merge fix is real and incomplete — the store keeps the tab, the tab bar
renders it, and the pane sometimes never rebinds, which is the frozen-tab shape the
original report described, one layer down from the deletion that used to cause it.
Asserting that would put a one-in-four flake into the lane built to catch this
class, and a lane nobody trusts is how the original silent-skip failure happened.
So the spec asserts survival, which is deterministic at five runs in five, and the
liveness gap is written down in docs/reference/ssh-reconnect-source-recovery.md
with the first place to look.
* fix(ssh): stop an unreadable host key store from wiping every pinned key
Second readiness pass, checking each of the first pass's ten fixes rather than
taking them on trust. Nine held. This is the one that did not, plus three
fail-open shapes in the site-config scanner that a live OpenSSH disproved.
P1 — the store. loadTrustedHostKeys returns [] for ANY read failure, and
trustHostKey then wrote [...that empty list, newRecord]: one transient EMFILE
followed by one first-contact accept replaced the file with a single record.
Every other host re-TOFUs, and one whose key genuinely changed in between is
accepted as first contact rather than refused — the exact outcome pinning
exists to prevent. It also contradicted the doctrine this PR applies to
known_hosts two files away, where a file that exists and refuses to open is
evidence withheld.
Fixed by classifying one read instead of guessing twice: readStore returns
ok/absent/withheld, the read path flattens withheld to 'nothing trusted' so it
still fails closed, and the write path declines. That subsumes the separate
newer-version probe, so trustHostKey now reads the file once inside the queue
rather than twice. The 'Trusted host key' log moved inside the branch that
actually writes — it was already claiming success on the newer-version path.
P2 — the site-config scanner documents 'doubt wins on every path' and had
three where it did not, each the same shape: a path resolved WRONG still
resolves to something, and a nonexistent Include reads as 'nothing there',
which is indistinguishable from 'no policy'. Verified against OpenSSH 10.2p1:
relative Includes resolve against a fixed dir, not the including file's, so a
directive two deep was missed; ? and [...] are globs it honours; ~ and %-tokens
expand before use. All three now answer doubt.
P2 — credential prompts are gated on the attempt generation in one place
rather than per rung. A superseded attempt is denied without a recorded
decision, so isHostKeyVerificationError reads false and the ladder ran on to
prompt for a passphrase nobody was waiting on.
P2 — resolveKnownHostsFiles is async. Its rejoin existsSync-scans the very
paths the 5s bound protects, and sat outside it as an eagerly-evaluated
argument, so a stalled NFS/SMB mount blocked the whole main process.
Tests fail against the pre-fix code: 2 for the store wipe, 3 for the scanner.
Also: the 4 IME failures I previously reported as pre-existing main breakage
were a stale node_modules — the xterm patch from #14758 was not applied here
(402,643 bytes installed vs 403,181 expected). pnpm install applies it and all
4 pass. The OSC8 and SFTP failures were the same cause.
* fix(ssh): make the merge non-duplicating, and close the last scanner hole
Third readiness pass. Three P2s, all fixed.
The merge one is the one I most wanted a verdict on, and it is real: hostUnknown
filtered against ids the HOST knows and never against ids this same merge had
already emitted, so a tab id local state holds under two worktrees was re-added
under both. Two panes then share one terminalLayoutsByTabId entry and one
remoteSessionIdsByTabId entry — one remote PTY — plus an activeTabId that never
converges, which is the self-retriggering repair loop active-tab-owner-worktree
.ts exists to mitigate (React #185).
This PR does not create that state. It used to DESTROY it, by deleting every
local tab under a replaced worktree, and keeping live panes cost that accidental
cure. So the guarantee is made explicit rather than incidental: the merge now
never emits one tab id twice, whatever it is handed. The active worktree is
walked first so the surviving copy is the one the user is looking at, which is
the owner resolveActiveTabOwnerWorktreeId already prefers — merge and repair now
agree instead of each picking differently.
Scanner: an Include path that is quoted AND contains a space was split before it
was unquoted, so both halves missed and two absent paths read as 'no site
policy'. OpenSSH honours that form -- 10.2p1 applies an Include of a quoted
spaced path -- and it is likelier on Windows. Quote-aware splitting rather than
'any quote is doubt', because answering doubt for an ordinary quoted Include
with no space would reinstate the lockout this scanner exists to avoid. An
unclosed quote is doubt. Unquoted spaces still split, which is also what OpenSSH does.
The reconnect paint gate took the replay and re-scanned it, having already been
scanned by the caller that decides whether to fetch a snapshot at all — two full
splits of up to 100KB per pane per reconnect. It now takes the transition.
hasReplay is passed separately because it cannot be inferred: a replay with no
mode change and no replay at all both give null.
Tests fail against the pre-fix code for the merge and all four scanner shapes.
Correcting my own evidence claim from last round: of the two store tests, only
the wipe one fails pre-fix. The other guards the asymmetry the fix creates and
passes either way — worth keeping, but I should not have counted it.
* fix(ssh): honour every Include quoting form OpenSSH does
Fourth readiness pass. Two findings; one fixed, one deliberately not, with the
evidence for refusing it.
The tokenizer modelled double quotes only. A live 10.2p1 honours single quotes
and backslash-escaped spaces too, and both fell into the same silent fail-open
the double-quote case was raised for: fragments that resolve to nothing, and
'nothing there' is indistinguishable from 'no site policy'.
The escape is limited to a backslash before whitespace, NOT a general one. A
general escape would be catastrophic on the platform this most needs to be right
for: the Windows site config lives at C:\ProgramData\ssh\ssh_config, so it
would eat every separator in an Include beneath it and resolve to nothing --
reintroducing the fail-open it was meant to close. The test for that is
discriminating rather than incidental: it gives the file a literal backslash in
its name, so a swallowed separator resolves elsewhere and fails, where a plain
'expect false' could not tell the two apart. Verified it catches the naive
version, and that the other two catch the old tokenizer.
NOT fixed: the non-duplication guarantee still stops at the worktrees the merge
rewrites. A worktree that is neither replaced nor named by the host is never
walked, so a duplicate straddling that boundary survives.
Extending the guarantee to the assembly point was implemented and REVERTED. Any
rule there has to pick a survivor, and the ones available are wrong during a
worktree-id change -- which is the very thing that produces these duplicates.
Preferring the active worktree keeps the OLD id's copy at the moment a rename
lands, because the active worktree has not moved yet; the new worktree was left
with no tabs and its groups were never created.
remote-workspace-snapshot-duplicate-tab-repair.test.ts caught it, which is the
only reason I know the stronger version was wrong rather than merely bolder. A
surviving duplicate is mitigated by active-tab-owner-worktree.ts; deleting the
tabs of the worktree the user is about to land in is not. The comment now claims
only what holds, and says why it is not stronger.
Also records the exit from the isENOENT message-matching trade in
remote-wire-compatibility.md, where someone touching the relay error path will
be standing.
* fix(ssh): expand Windows OpenSSH's __PROGRAMDATA__ token in known_hosts paths
Captured real 'ssh -G' output from a Windows host rather than reasoning about
it, which is the one thing that could not be inferred from the POSIX format.
Two things came back that the code did not handle correctly, and one of them is
the security failure mode this work exists to prevent.
Native Windows OpenSSH prints the system paths with its own token UNEXPANDED:
globalknownhostsfile __PROGRAMDATA__\ssh/ssh_known_hosts __PROGRAMDATA__\ssh/ssh_known_hosts2
userknownhostsfile C:\Users\neil/.ssh/known_hosts C:\Users\neil/.ssh/known_hosts2
Passed through as a literal path, __PROGRAMDATA__\ssh/ssh_known_hosts misses
with ENOENT -- and an absent file is deliberately treated as 'no host is known
there' rather than 'evidence withheld', because that is the normal state. So a
site-managed known_hosts on Windows was silently invisible: every host in it
read as first contact, and one whose key an admin had rotated produced a TOFU
accept where it should have produced a mismatch. Now expanded from
process.env.ProgramData, and left literal when that is unset rather than
guessed -- a wrong path reads as absent, which is the very failure being fixed.
The second finding is reassurance rather than a bug: separators are MIXED within
one path (C:\Users\neil/.ssh/...), which Node's fs accepts on Windows, and a
spaced home prints unquoted exactly as it does on POSIX. So the space-rejoin
design is confirmed against the real format rather than assumed -- its
motivating example, C:\Users\John Doe, splits the way the rejoin expects.
The captured output is pinned as a literal fixture. Parsing and the rejoin are
pure string work, so this covers the input shape honestly off Windows; it does
not pretend to cover the platform's path arithmetic. The expansion test fails
without the fix.
Also confirms C:\ProgramData\ssh is the right site-config directory -- it
exists on the host, empty -- so the scanner is looking in the right place.
* fix(ssh): branch Include backslash handling on platform, both halves measured
Fifth readiness pass found that the previous narrowing traded one fail-open for
another. Both rules are right, on different platforms:
POSIX 10.2p1: Include conf\.d/x.conf resolves as conf.d/x.conf
four backslashes needed to survive as one -- argv_split and
glob() each consume a level
Windows: Include C:\Users\...\x.conf resolves, separators intact
So a backslash before an ordinary character ESCAPES on POSIX and SEPARATES on
Windows, and either rule applied everywhere fails open on the other platform.
Preserving on POSIX means looking for a path with a literal backslash, missing,
and reading 'no site policy'. Answering doubt on Windows means every absolute
Include is doubt, which is the lockout the scanner exists to avoid.
Now branched. POSIX answers doubt rather than emulating two rounds of glob
escaping for a question this coarse -- a backslash in a POSIX system config path
is vanishingly rare, so fail-closed costs nothing there.
The review offered the Windows half as a reasoned assumption and flagged it as
such. It is now measured on a real Windows host instead: backslash separators
resolve, AND an escaped space still escapes amid them
(C:\Users\neil\sshprobe\sp\ ace\x.conf -> port 2802), which is exactly the rule
implemented. Two other worries were checked and came back unfounded -- a
backslash-space inside EITHER quote is consumed by ssh, and a single quote
inside double quotes is an ordinary character, which the single quote-state
variable already reproduced.
The tokenizer takes the platform as a parameter, so both sides are pinned from
one host. Every expectation in the new oracle came from running a real ssh and
reading what it resolved to, not from reading source or shell convention -- the
tokenizer's whole job is to agree with ssh about which file it would read.
Also narrows an overclaiming comment: the dedupe set is consulted only by the
host-unknown filter, so a duplicate in the HOST's own snapshot still propagates.
Pre-existing and unchanged; the comment now says what the code actually does.
* fix(ssh): only expand __PROGRAMDATA__ when it is a whole path segment
Found by probing the expansion I had just written, rather than by reading it: a
bare startsWith also matches a path that merely BEGINS with those characters, so
__PROGRAMDATA__evil/known_hosts was rewritten to C:\ProgramData\evil\known_hosts
-- a directory the user never named. Same prefix-collision class I checked the
site-config scanner for and then did not check here.
Low reachability, since the token only appears because Windows OpenSSH emitted
it, and it emits it as a whole segment. Fixed because the expansion is one review
pass old and sits in the security path: a rewritten known_hosts path resolves
somewhere unintended, and a path that resolves to nothing reads as 'no host is
known', which is the fail-open this whole line of work has been closing.
Now requires the token to be the entire path or be followed by a separator --
both separators, since the path is Windows-shaped but may be parsed anywhere. The
test fails without the check.
* test(ssh): split the pty provider spawn tests into their own file
CI's static analysis went red on the merge of main: ssh-pty-provider.test.ts
reached 803 counted lines against a maximum of 800. Both sides contributed --
main grew the file and this branch added 7 lines to it -- so neither shows the
violation alone, which is why local lint stayed green until main was merged in.
AGENTS.md forbids disabling max-lines or bumping a per-file limit, and that rule
is right here: the file was doing two jobs. Spawn owns the startup contract --
ingress version, env scrubbing, execution ownership, and the reconnect races --
and is 630 of the 922 lines. It reads as its own unit rather than as an overflow
file, so it moves to ssh-pty-provider-spawn.test.ts and the shared relay stub
moves beside it under a name that says what it is.
Same tests, same count: 713 provider tests pass, and the line total is unchanged
across the two files.
* fix(ssh): remove the dead lint suppressions, and reach Terminal 1 in the restore spec
Two CI failures, both surfaced by this branch rather than caused by it.
Static analysis: the two no-require-imports suppressions on the ssh2 constants
require() are now unused -- main's config no longer reports that rule there --
and the changed-code audit treats a dead directive as an error. Removed; the
audit CI runs passes locally on the merge.
E2E: ssh-cold-activation-restore failed on clicking Terminal 1. This PR is what
routes that spec into the changed-e2e lane at all -- before, the Docker-SSH
specs only ran when someone edited a spec file, which is the gap this branch set
out to close -- so its first run in CI was here, and the failure is pre-existing
rather than new. The trace shows the cause: six restored tabs overflow the strip
at CI's window size and the restore pins it to the END, so Terminal 1 sits
outside the scroll viewport. Playwright's own scroll-into-view loses that race
against the sticky-to-end effect and times out on an element it can see but
never reaches.
The spec's intent is to activate the first tab and prove it remounted, not to
exercise strip scrolling, so it now scrolls the strip to the start first. Not
papering over a product bug: the strip is a native overflow container with
working arrow controls, so a user can reach the tab -- it is Playwright that
cannot drive a moving target.
Six specs pass locally in CI's exact order and worker count.
* test(ssh): press the restored first tab directly instead of waiting for it to hold still
The previous attempt swapped a click for scrollIntoViewIfNeeded and hit the same
30s timeout, which identifies the real cause: not that Terminal 1 is out of view,
but that it never holds STILL. Both APIs wait for the element to stop moving, and
the strip keeps re-laying-out while the relay reconnects behind it -- so both
time out on an element they can see and never settle on.
Driving the pointer directly needs no element to be stable, only to be somewhere
at the moment it is pressed, and the attempt is retried against the store rather
than believed. Activation is deferred to pointerup and suppressed past a drag
threshold, so it has to be a real down/up pair at one position -- a synthetic
click event would not select the tab at all.
Passes twice locally. The previous version also passed locally, so the honest
statement is that the local runs prove the interaction still works, not that they
reproduce CI's instability -- CI is the oracle for that.
* 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.
* 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.
* 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>
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
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.
* 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>
* 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>
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.
* 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>
* 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>
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.
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>
* 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>
* fix(terminal): release an abandoned synchronized-output frame on reveal
Alt-screen agent TUIs (OpenCode/OpenTUI, Codex, grok) bracket every repaint
in `?2026h … ?2026l`. Hiding a pane mid-bracket — which a worktree switch or
cold-park lands on routinely, since these brackets are written many times a
second — leaves xterm's `decPrivateModes.synchronizedOutput` latched.
RenderService.refreshRows checks that latch *before* rendering, so while it
holds, every repaint Orca owns is a no-op: the forced render-pause repaint,
the plain `refresh()` fallback, and the shared glyph-atlas rebuild all render
zero rows while the xterm buffer is perfectly correct. Release the latch at
the two reveal repaint entry points so those repaints actually paint.
Also adds an OpenCode-shaped alt-screen e2e fixture and spec. The existing
inline-TUI convergence spec covers the normal-buffer shape (live block glued
to the bottom, history scrolling into scrollback); this covers the
full-screen alternate-buffer shape, where nothing scrolls and so no row ever
self-heals through the scroll path.
Scope note: xterm arms a 1s watchdog that clears this latch on its own, so
this closes a bounded window rather than the whole STA-2694 report. The e2e
spec passes with and without the production change for that reason; the unit
tests are what pin the behavior. Refs STA-2694.
* fix(terminal): clear the render model on the plain-refocus repaint path
`schedulePaneRevealPresent` — the atlas-preserving path a plain window
refocus takes — only called `terminal.refresh()`. xterm's renderers are
diff-based: `_updateModel` early-continues on any cell whose code/fg/bg/ext
still match the cached model, so a refresh repaints nothing for a pane whose
buffer never changed. When an occluded window loses its canvas contents while
that model stays populated, the refresh skips exactly the cells that went
stale and the pane keeps compositing pre-hide pixels — until a window resize
reallocates the model, which is the repair users find by hand.
Clear the model first (`RenderService.clear()` → renderer `clear()` →
`_clearModel(true)`) so the refresh becomes a guaranteed full repaint. That
drops cached cells and glyph vertices but NOT the texture atlas, which is
shared by every same-config terminal and whose mid-stream wipe re-arms xterm's
page-merge garble race (xterm.js #4480) — the reason this path is
atlas-preserving in the first place.
Also covers the DOM-renderer fallback in `resetWebglTextureAtlas`:
`clearTextureAtlas()` is what invalidated the model on the WebGL path, so a
pane without an addon had nothing invalidate it and hit the same skip.
Scope note: the e2e spec guards buffer/geometry convergence across the
hide/reveal boundaries and adds idle-agent and headful desktop-hide cases, but
it cannot observe a stale canvas — both oracles built for that (canvas-vs-buffer
ink sampling, screenshot-vs-forced-repaint) were proven blind by injecting the
defect, and the spec header documents why. The unit tests pin the ordering and
the atlas-preservation invariant. Refs STA-2694.
Co-authored-by: Orca <help@stably.ai>
* docs(terminal): hand off the STA-2694 reveal-artifact investigation
Records both fixed defects with their xterm mechanisms, the reveal/wake call
graph, why every e2e oracle for a stale canvas was proven blind, how to arm the
in-app render-desync sentinel on real hardware, and the one unverified lead
(dimension staleness) that would explain why a window resize specifically is
the repair users find. Refs STA-2694.
Co-authored-by: Orca <help@stably.ai>
* Revert "fix(terminal): clear the render model on the plain-refocus repaint path"
This reverts commit 0f7ec4458d.
* test(terminal): add a draw-command oracle for reveal repaints, and correct the STA-2694 scope
Every pixel oracle tried for STA-2694 was blind: `drawImage` on a
non-preserveDrawingBuffer WebGL canvas returns a re-rendered copy, and
Playwright's screenshot drives a fresh compositor frame that heals a stale paint
before capture. Reading pixels is self-defeating here — the read triggers the
repaint that hides the bug.
Count the WebGL draw commands instead, by wrapping GlyphRenderer.updateCell and
gl.drawElementsInstanced on the live pane. A draw command cannot be healed after
the fact, so "did the reveal actually repaint?" becomes directly observable.
Teeth-verified: removing releaseAbandonedSynchronizedOutput from
schedulePaneRevealPresent fails the stranded-latch test.
Two findings, both of which change previously-committed claims:
1. The 1s watchdog does NOT bound the synchronized-output defect. It is armed
only inside `bufferRows`, and `refreshRows` returns at its `_isPaused` check
first — so while a pane is occluded nothing reaches `bufferRows` and no timer
is ever pending. A pane hidden mid-`?2026h` holds the latch with no watchdog
behind it, indefinitely. ed1eaf55f1's "closes a bounded window" scope note was
wrong; this is the unbounded garble the report describes, and the fix closes
it. Corrected in the module doc comment.
2. It refutes the diff-based-staleness hypothesis behind 0f7ec4458d (reverted in
8d5eacecb4). `_updateModel` does early-continue per unchanged cell, but
`GlyphRenderer.render` then copies vertices for EVERY row up to
`lineLengths[y]` and issues ONE full-viewport draw — measured identical
instance counts (562) for a diff-skipped and a model-cleared refresh, with
updateCell at 0 vs 561. The DOM renderer likewise replaceChildren()s every
row unconditionally. Clearing the model could not change what reached the
screen, and `_clearModel(true)` zeroes every glyph vertex while
`RenderService.clear()` fires no repaint of its own — so it opened a
blank-viewport window (also asserted here) for no benefit.
Also keeps the idle-agent and headful desktop-hide cases from the reverted
commit, since those were independent of the refuted production change, and
rewrites the alt-screen spec header to point paint questions at this oracle.
Refs STA-2694.
Co-authored-by: Orca <help@stably.ai>
* docs(terminal): rewrite the STA-2694 handoff after the refutation
Records that the garble window is unbounded (the 1s watchdog never arms for an
occluded pane), that the diff-based-staleness hypothesis was refuted by
measurement and reverted, why pixel oracles are structurally blind here, and the
two leads now closed by measurement (dimension staleness, lazy atlas bindings).
Refs STA-2694.
Co-authored-by: Orca <help@stably.ai>
* test(terminal): capture visual proof of the STA-2694 stale paint
The earlier screenshot oracles were blind because they compared a revealed pane
against a repaired one and both ran the same repaint code. Capturing the defect
directly works instead, because the mechanism is self-preserving: while
synchronizedOutput is latched, refreshRows returns before reaching the renderer,
so a compositor frame just re-composites the existing canvas texture and the
stale pixels survive the screenshot rather than being healed by it.
Latch a frame, write a full new frame the pane cannot paint, and capture. The
screenshot comes back byte-identical to the pre-hide one while the buffer holds
the new frame — the buffer/screen divergence users report — and differs after
the reveal repaint runs. Asserts both halves, so it fails if either the defect
stops reproducing or the fix stops repairing it.
Refs STA-2694.
Co-authored-by: Orca <help@stably.ai>
* test(terminal): note where the xterm gate-order double is pinned for real
The unit double encodes RenderService's paused-then-latch gate order, which can
drift on an xterm upgrade. Point at the e2e oracle that pins the same order
against the real renderer, so a future upgrade has a trail to the authoritative
check. Refs STA-2694.
Co-authored-by: Orca <help@stably.ai>
* test(terminal): add a perf budget for the synchronized-output release
releaseAbandonedSynchronizedOutput runs inside resetWebglTextureAtlas, which a
streaming alt-screen TUI can reach through the terminal-output atlas recovery
path — not only on reveal. Measure rather than assert that this costs nothing.
Steady state (a TUI that closes every frame it opens): 200 bracketed frames
produce zero releases, zero extra draw calls, and an unmeasurable early-out
cost. Worst case (every reveal finds a latched frame): 50 latched atlas resets
at 0.08ms each. Both are asserted with headroom, so the guard catches a future
change that makes this scan the buffer per pane rather than flaking on machine
speed. Refs STA-2694.
Co-authored-by: Orca <help@stably.ai>
* test(terminal): address review — drive real code paths, close vacuity gaps
CodeRabbit caught a genuine tautology in the perf budget: it timed a
hand-copied mirror of the early-out rather than the shipped function, so the
assertion would have held even if the real code grew a buffer scan. Driving
resetWebglTextureAtlases instead moved the measured cost from ~0 to ~0.03ms per
call, which is the honest number for the whole recovery; bound re-set to 0.4ms
(10x measured).
Other review fixes:
- Assert the draw counts both perf tests were measuring and logging but never
checking, so the 'no extra draws' titles now mean something.
- Fail fast when decPrivateModes is unavailable; previously the latched test
would pass without ever exercising the fix.
- Re-check the latch right after the worktree switch in the mid-frame test: the
pane is visible until then, so the 1s watchdog can arm and clear it before the
hide, making the run vacuous.
- Count scheduleRevealPresent invocations instead of returning a literal true,
so a missing test hook no longer masquerades as a production failure.
- Assert the latch clears on every reveal iteration, not just the last.
- Make the fixture heartbeat write atomic (tmp + rename); writeFileSync
truncates first, so a reader could see '' and read it as frame 0.
- Relabel assertRevealPixelsNeedNoRepair as the weak secondary check it is; it
contradicted the file header by calling itself 'the decisive paint assertion'.
Refs STA-2694.
Co-authored-by: Orca <help@stably.ai>
---------
Co-authored-by: Orca <help@stably.ai>
* fix(linux): restore Ubuntu 20.04 launch by pinning node-pty glibc symbols (#9902)
The bundled node-pty pty.node is compiled from source in release CI on
ubuntu-latest (glibc 2.39). glibc's 2.32-2.34 libpthread/libutil merge
relocated openpty/forkpty (GLIBC_2.34) and pthread_sigmask (GLIBC_2.32)
into libc under new symbol versions, so the from-source build bound to
versions absent on Ubuntu 20.04 (glibc 2.31). The main process imports
node-pty at startup, so the app crashed on launch. pty.node is the sole
blocker (Electron needs GLIBC_2.25; other native modules <= 2.17).
- Patch node-pty: a .symver shim pins the 3 symbols to their pre-merge
version (GLIBC_2.2.5 x64 / GLIBC_2.17 arm64), and Linux-only ldflags
force libutil.so.1/libpthread.so.0 back into DT_NEEDED. Guarded to
Linux; macOS/Windows untouched.
- Add a packaging gate (verify-linux-glibc-floor.cjs, afterPack): reads
each bundled native binary's objdump -p version needs and fails the
Linux build if any strong GLIBC_/GLIBCXX_/CXXABI_ node exceeds stock
Ubuntu 20.04 (glibc 2.31 / GLIBCXX_3.4.28 / CXXABI_1.3.12). Catches
GLIBC_ABI_DT_RELR, rejects GLIBC_PRIVATE, skips weak needs, fail-closed.
- Docs + tests; the lazy sherpa-onnx speech prebuilt (GLIBCXX_3.4.29,
never loaded at launch) is a documented libstdc++-floor exemption.
* fix(linux): assert DT_NEEDED provider deps in the glibc-floor gate
Harden the packaging gate (flagged in adversarial re-eval): the version-floor
check alone can false-pass if the patch's forced `-l:libutil.so.1` ever silently
drops — the pinned openpty@GLIBC_2.2.5 still resolves from libc's compat alias at
build time, but fails to load on Ubuntu 20.04 where openpty/forkpty live only in
libutil. The gate now also asserts that any binary importing openpty/forkpty
keeps libutil.so.1 in DT_NEEDED. Validated on a real symver-pinned .so with
libutil dropped (now fails) vs. present (passes). Documents the recommended
real-host smoke-test follow-up.
* docs(headless-server): add upgrade SOP for orca serve on Linux
The headless Linux guide covered install/run/systemd but had no upgrade
section, leaving operators to guess how to move to a new AppImage without
losing state.
Add an "Upgrade" section documenting the manual SOP (serve mode never
auto-updates) and one troubleshooting bullet:
- State lives under the service user's ~/.config (orca + Orca dirs),
independent of /opt/orca, and orca-data.json is forward-migrated on load,
so a forward upgrade is safe.
- Replace the binary with an atomic same-filesystem rename (download to
.new, verify, mv) — never curl -o over the FUSE-mounted live binary.
- Back up the whole .config before upgrading, because rollback is NOT
binary-only safe: an older build strips newer orca-data.json fields it
doesn't recognize, and the .bak.* ring is corruption-recovery, not a
pre-upgrade copy.
- Note there is no headless version command; track the release tag instead.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(headless-server): harden the orca serve upgrade/rollback runbook
Address CodeRabbit review on #9575:
- Fail closed: run the upgrade block under `set -euo pipefail`, remove any stale
`.new` file before download, and gate the atomic `mv` on an explicit ELF check
so a failed/partial/non-ELF download can never be promoted.
- Keep /opt/orca/VERSION tied to the installed binary: a single `TAG` variable
drives both the download URL and the recorded VERSION, saved as VERSION.prev on
upgrade and restored on rollback so the audit file never drifts.
- Crash-loop troubleshooting now points to Roll back first (restores the
pre-upgrade orca-data.json) instead of re-running Upgrade.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(headless): harden server upgrade SOP
---------
Co-authored-by: fanyunqian.1 <fanyunqian.1@bytedance.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
* Add native chat skill and command picker with host-aware discovery
Adds a unified, keyboard-first skill and command picker to native chat that:
- Uses agent-native invocation syntax (slash for Claude/OpenClaude/Grok, dollar for Codex)
- Discovers skills only on the pane's execution host (local, WSL, SSH-unavailable, or runtime)
- Groups or separates commands and skills per agent configuration
- Deduplicates by canonical path but preserves visibility through all contributing roots
- Handles IME composition, loading states, and errors without claiming PTY-level control
- Records picker telemetry (open, item accepted, send classification, discovery outcomes)
- Extends shared agent profiles to define per-agent skill grammars and source ownership
* Remove obsolete reference and design documentation
Clean up stale design specs, implementation plans, and investigation notes from
docs/reference/. These documents predate the current implementation and are no
longer actively maintained or referenced by the codebase.
* Extract shared skill discovery utilities and add skill invocation envelo
- Move skill comparison and source classification to shared module for native/WSL reuse
- Extract display text sanitization to prevent control/zero-width character spoofing
- Add native-chat command envelope parser and surfacer for skill invocations
- Extend discovery timeout backstop to account for WSL metadata read sequence
* Localize skill picker UI for Spanish, Japanese, Korean, Chinese
Translate skill picker UI strings including commands, skills, loading
states, error messages, and scope labels for the new skill picker feature
across four language locales.
* Fix skill picker bugs and improve code robustness
- Fix i18n plural handling: rename `count` to `sourceCount` to prevent unintended plural-key resolution in localized strings
- Fix skill discovery array mutations: copy `root.providers` to prevent bugs during dedup merge
- Fix image attachments being silently dropped when message text starts with /skill or agent prefix
- Extract `quoteBashString` utility for WSL command code reuse across builders
- Add line-separator safety characters (0x2028/0x2029) to skill display filter
- Remove stale doc reference links and clarify inline comments
* Add reference docs for git compatibility and headless Linux server setup
Track previously untracked operational guides in `docs/reference/` that
explain Git binary compatibility requirements across host types and how to
run `orca serve` on headless Linux. Update AGENTS.md and README.md to link
to these references.
* fix(worktrees): stop surfacing prunable git worktrees as live workspaces
A worktree still registered in git but whose directory was deleted
(git's `prunable` state) was enumerated as a normal workspace,
producing repeated pty:spawn DaemonProtocolError / fs:readDir ENOENT
loops and a blank pane.
- Parse the `prunable` porcelain field (Git >= 2.36) in both the main
and relay worktree-list parsers.
- For Git < 2.36 (no `prunable` field), probe each linked worktree
path for existence on the fallback line-block path, skipping locked
registrations to mirror git's own prunable rules.
- Omit prunable worktrees from the detected-workspace enumeration only;
removal/cleanup flows keep seeing them.
- Extend the real-binary compatibility contract with the 2.36
`prunable` boundary.
Fixes#8389
Claude-Session: https://claude.ai/code/session_018Rg1Bpq4GGwmz613hq6RSD
* fix(worktrees): pin the prunable/locked porcelain annotations to their real Git 2.31 boundary
The prunable and locked annotations landed in Git 2.31, five releases
before `worktree list -z` (2.36); only -z defines the capability
fallback boundary. Correct the compatibility contract so a future
matrix entry in the 2.31-2.35 range passes, and reword the fallback
comments: on 2.31-2.35 the annotations still parse and the existence
probe is a backstop; only Git <2.31 relies on it outright.
* fix(worktrees): omit prunable registrations from the Space scan
A prunable registration has no directory to size or reclaim, so Space
rendered it as a dead "Missing" row whose checkbox stayed disabled with
no prune/remove affordance (reported on macOS after a reboot cleared
/private/tmp under 16 registrations). Skip prunable entries in the scan,
matching the workspace enumeration; removal flows list worktrees
separately and still see them.
---------
Co-authored-by: kaynan <kaynan.camargo@terceiro-sky.com.br>
Co-authored-by: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
* fix(terminal): kill agent descendant processes on session teardown (STA-1800)
Agent CLIs spawn tool children in detached process groups that PTY
SIGHUP can never reach. Killing an agent session (tab close, retire,
sleep) left those children running as orphans — eight orphaned git
processes burned ~8 cores for up to 11.5h under the agents-running
keep-awake and drained a battery to 8%.
New pty-descendant-termination module: snapshot the ppid tree BEFORE
signalling (a dead root's descendants reparent to pid 1 and become
unfindable), SIGTERM the root group and every descendant, then after a
2s grace SIGKILL survivors gated on a pid+start-time identity re-check
so a recycled pid is never signalled. Snapshot is bounded and never
rejects; failures degrade to today's shell-only kill.
Wired for agent sessions only (plain terminals keep nohup semantics) at
all three POSIX kill sites: local provider shutdown, daemon
TerminalHost immediate kill (the pty:kill path — force-kill bypassed
Session.kill entirely), and daemon Session graceful kill.
Verified live in the built app: an agent pane with a detached-pgid
child; the child survived on the unwired build (three control runs) and
dies within ~5s with the fix. Windows ConPTY and SSH-hosted PTYs keep
the previous foreground-tree contract (documented follow-ups).
* fix(terminal): harden descendant teardown
* fix(terminal): require fresh process snapshots
* fix(terminal): close descendant teardown races
* refactor(terminal): preserve teardown line budget
* fix(terminal): keep descendant teardown fresh and identity-safe
* docs(reliability): record integrated descendant E2E
* fix(terminal): bound descendant teardown work
* fix(terminal): share descendant snapshot indexes
* docs(reliability): record descendant review evidence
* revert: remove speculative descendant hardening
* feat(ssh): support Kerberos/GSSAPI hosts via the system OpenSSH transport
ssh2 has no gssapi-with-mic support, and adding it would mean forking its
protocol layer plus packaging the kerberos native module for three
platforms. Instead, route GSSAPI hosts through the existing system-OpenSSH
transport, which delegates Kerberos (tickets, SSPI on Windows) to the
platform ssh binary.
Two tiers, because RHEL-family distros enable GSSAPIAuthentication
globally in /etc/ssh/ssh_config and ssh -G therefore reports it for every
host:
- Targets whose ~/.ssh/config Host block explicitly sets
GSSAPIAuthentication yes (imported as target.gssapiAuthentication) try
system ssh first, falling through to ssh2 so key auth and credential
prompts still work when no ticket is available.
- When ssh2 exhausts key/agent auth and the ssh -G-resolved config
enables GSSAPI, retry over system ssh before prompting for credentials,
so Kerberos-only hosts on distro-default configs connect without a
password prompt. Hosts where keys work never leave the ssh2 path.
Manual targets flagged for GSSAPI pass -o GSSAPIAuthentication=yes
explicitly since they bypass ssh_config. Both tiers work headless (no
credential callbacks required).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(ssh): harden GSSAPI transport selection (review fixes for PR #7507)
Review fixes on top of the Kerberos/GSSAPI feature branch (s546126/kerberos-ssh):
- HIGH: reset useSystemSshTransport on the ssh2 fall-through. doSystemSshProbe
sets the flag before spawnSystemSshCommand, which throws synchronously when no
system ssh binary is on PATH (outside the probe try/catch). The proactive
fall-through previously reset only 2 of 3 transport fields, so exec/sftp kept
routing through the failed transport - breaking GSSAPI on Windows-with-Git-ssh
and headless Linux.
- MEDIUM: throw a cancellation error (not the stale ssh2 authError) when a
disconnect supersedes the reactive probe mid-flight, and guard connect()'s
catch on disposed, so a deliberate disconnect is not overwritten with
auth-failed.
- MEDIUM: skip the encrypted-key passphrase prompt when the GSSAPI fallback
applies, so a Kerberos ticket is tried before prompting; the general prompt
still fires if the probe fails.
Adds 3 mutation-verified regression tests and hardens two existing tests to
assert the probe actually ran. Not connected to any PR remote.
Co-authored-by: Orca <help@stably.ai>
* fix(ssh): isolate GSSAPI system transport
Co-authored-by: Orca <help@stably.ai>
---------
Co-authored-by: s546126 <268420947+s546126@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Neil <4138956+nwparker@users.noreply.github.com>
Co-authored-by: Jinwoo-H <jinwoo0825@gmail.com>
Co-authored-by: Orca <help@stably.ai>
Codex, Antigravity, and Devin launch their agent-hook `command` as a program
(argv[0]), not through cmd.exe. PR #8430 changed wrapWindowsCmdHookCommand to
emit an `if exist "path\." (drain) else if exist "path" (call "path") else
(drain)` compound whose argv[0] is the cmd builtin `if` — unspawnable — so every
Codex/Antigravity/Devin hook (SessionStart, UserPromptSubmit, Stop, ...) failed
with "hook exited with code 1" on Windows starting in v1.4.138.
Revert the cmd-safe fast path to the bare, directly-spawnable .cmd path (the
proven pre-#8430 form). A cmd-builtin drain and direct-spawnability are mutually
exclusive, and nesting cmd.exe /d /c breaks large-payload draining; the
missing-script stdin drain stays on the encoded-PowerShell fallback (used for
spaced/non-ASCII paths). Upgrades self-heal on first launch: startup install()
unconditionally rewrites the command and Codex trust entry, sweeping the old
compound form.
Add a platform-independent regression guard (launcher must resolve to a real
file, never a cmd-builtin fragment), update the lifecycle test + docs, and fix a
stale Devin comment.
* Fix hook scripts to drain stdin before any early-exit path
Generated agent hook scripts and missing-script launchers could exit
successfully before consuming the payload written to their stdin,
leaving the writer with a broken pipe (EPIPE/ERROR_BROKEN_PIPE) once
the reader closed early. Capture stdin (or drain it via a shared
epilogue/fast-path guard) before any whole-script success exit across
all POSIX, batch, PowerShell, and Git Bash launcher variants, and add
a cross-agent lifecycle test suite plus a live Electron verification
script to guard the contract going forward.
* Harden hook scripts against unreadable managed scripts and add a Claude/
- Extend the POSIX launcher guard to also require `[ -r ]`, not just `-f`/`-x`,
so an executable-but-unreadable managed script still drains stdin instead of
erroring or silently misbehaving.
- Add a verifier case (`verifyClaudeDevinSkip`) that spins up a local HTTP
server and confirms the Claude hook never forwards a request that Devin
already imported, catching accidental double-forwarding.
- Update installer-utils tests and stdin-lifecycle docs to match the new
readable-file guard and the added verification case.
* Fix hook-launcher verification to derive script paths from the installed
Extract the quoted path from the launcher's `if [ -f '...'` clause instead of
reconstructing it via join(home, ...), so missing/failing-script test cases
can't silently fall through to the real script if the install layout changes.
---------
Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
* Fix mobile terminal query reply authority
* fix(terminal): harden mobile query reply handoffs
* fix(terminal): exclude passive mobile query responders
* fix(terminal): gate mobile query replies on host capability
Older hosts strip terminal.send's inputKind (zod drops unknown keys), so a
forwarded xterm reply would land as ordinary floor-taking shell input. Hosts
now advertise terminal.query-reply-input.v1 via status.get and mobile drops
replies unless the host advertises it (pre-fix behavior). Also documents the
bounded desktop-to-mobile handoff double-reply residual.
Co-authored-by: Orca <help@stably.ai>
* fix(terminal): advance snapshot seq across recovery snapshots
The pending-overflow recovery loop trims buffered output against
recovery.seq while query replay and boundary strips kept using the
initial snapshot seq. Unreachable under today's control flow (no await
separates the initial-overflow consume from the loop), but the stale
seq would silently drop covered query replies if that ordering ever
changes. Track the seq that actually covered the buffered chunks.
Co-authored-by: Orca <help@stably.ai>
---------
Co-authored-by: Orca <help@stably.ai>
OrcaWinandOrcaWin
Neil
Jinwoo Hong
Jinjing
Brennan Benson
Sebastián Castañoandscastanoh21
