Repository navigation
fix(remote-workspace): restore a wire field the snapshot normalizer silently dropped - #16747
Merged
Merged
Conversation
This was referenced Aug 27, 2026
Merged
nwparker
force-pushed
the
nwparker/ssh-01-e2e-lane
branch
from
August 27, 2026 09:49
607718a to
8daf1d8
Compare
nwparker
force-pushed
the
nwparker/ssh-02-normalizer-field
branch
from
August 27, 2026 09:49
80122bb to
a7f689a
Compare
nwparker
force-pushed
the
nwparker/ssh-01-e2e-lane
branch
from
August 27, 2026 09:52
8daf1d8 to
2c4463d
Compare
nwparker
force-pushed
the
nwparker/ssh-02-normalizer-field
branch
from
August 27, 2026 09:52
a7f689a to
5e16b6c
Compare
nwparker
force-pushed
the
nwparker/ssh-01-e2e-lane
branch
2 times, most recently
from
August 28, 2026 02:31
21f9c88 to
4630033
Compare
… through the normalizer
`defaultTerminalTabsAppliedByWorktreePath` is declared on the wire session
(`src/shared/remote-workspace-types.ts:16`), emitted by the renderer's export
(`remote-workspace-session-projection.ts:101-134`) and read back by its importer
(`:195`) -- but `normalizeRemoteSession` rebuilds the session as an object
literal and never copied it. Measured on a snapshot carrying `{ '/r': true }`:
normalizeSnapshot(...).session.defaultTerminalTabsAppliedByWorktreePath
=> undefined
remoteWorkspaceSessionMatchesSnapshot(withFlag, withoutFlag)
=> true
Two consequences. `getRemoteSnapshot` normalizes everything the relay returns
(`remote-workspace-relay-sync.ts:29`), so a client could never receive the flag
even though the write path sends `session` verbatim. And
`patchRemoteWorkspaceSession` short-circuits on
`remoteWorkspaceSessionMatchesSnapshot` (`:51`), which normalizes both sides --
so a change that only sets this marker was invisible to the dirty check and
could never be written at all.
The marker is the sole guard on `applyDefaultTerminalTabs`
(`worktree-default-terminal-tabs.ts:34`), so losing it re-applies the whole
default-tab template over the user's tabs.
This has never worked in either direction since the field was introduced.
`normalizeRemoteSession` predates `372469b7528` under a different path -- it
lived in `src/main/ipc/remote-workspace.ts` until `15e1ba3f84a` split it out for
max-lines, and at `372469b7528` it already copied all four sibling optional
fields and simply never gained a fifth. No test caught it because that commit
tested the projection round-trip (correct in isolation) while the normalizer sat
in another file with no test of its own.
The new test file closes that gap two ways: a case per consequence, plus a
`Required<RemoteWorkspaceSession>` fixture asserted key-for-key against the
normalizer's output. Because the normalizer is an object literal, the next field
added to the wire type and forgotten there is now a compile error in this test
rather than silent data loss.
Wire compatibility: safe, but not by the plain "new optional field" rule -- this
is an already-declared field that was silently stripped on every read. Both
readers treat it as optional; the relay is not a reader at all
(`src/relay/workspace-session-handler.ts:145-151` stores `patch.session` as an
opaque record and returns it verbatim), so no relay version can strip it. A
half-upgraded pair is one-directional: an old client still drops the key on read
and behaves exactly as today.
Before: 3 failed | 1 passed. After: 4 passed.
nwparker
force-pushed
the
nwparker/ssh-02-normalizer-field
branch
from
August 28, 2026 02:41
5e16b6c to
13341a3
Compare
paidaxingyo666
pushed a commit
to paidaxingyo666/Manta
that referenced
this pull request
Aug 30, 2026
… through the normalizer (stablyai#16747) `defaultTerminalTabsAppliedByWorktreePath` is declared on the wire session (`src/shared/remote-workspace-types.ts:16`), emitted by the renderer's export (`remote-workspace-session-projection.ts:101-134`) and read back by its importer (`:195`) -- but `normalizeRemoteSession` rebuilds the session as an object literal and never copied it. Measured on a snapshot carrying `{ '/r': true }`: normalizeSnapshot(...).session.defaultTerminalTabsAppliedByWorktreePath => undefined remoteWorkspaceSessionMatchesSnapshot(withFlag, withoutFlag) => true Two consequences. `getRemoteSnapshot` normalizes everything the relay returns (`remote-workspace-relay-sync.ts:29`), so a client could never receive the flag even though the write path sends `session` verbatim. And `patchRemoteWorkspaceSession` short-circuits on `remoteWorkspaceSessionMatchesSnapshot` (`:51`), which normalizes both sides -- so a change that only sets this marker was invisible to the dirty check and could never be written at all. The marker is the sole guard on `applyDefaultTerminalTabs` (`worktree-default-terminal-tabs.ts:34`), so losing it re-applies the whole default-tab template over the user's tabs. This has never worked in either direction since the field was introduced. `normalizeRemoteSession` predates `372469b7528` under a different path -- it lived in `src/main/ipc/remote-workspace.ts` until `15e1ba3f84a` split it out for max-lines, and at `372469b7528` it already copied all four sibling optional fields and simply never gained a fifth. No test caught it because that commit tested the projection round-trip (correct in isolation) while the normalizer sat in another file with no test of its own. The new test file closes that gap two ways: a case per consequence, plus a `Required<RemoteWorkspaceSession>` fixture asserted key-for-key against the normalizer's output. Because the normalizer is an object literal, the next field added to the wire type and forgotten there is now a compile error in this test rather than silent data loss. Wire compatibility: safe, but not by the plain "new optional field" rule -- this is an already-declared field that was silently stripped on every read. Both readers treat it as optional; the relay is not a reader at all (`src/relay/workspace-session-handler.ts:145-151` stores `patch.session` as an opaque record and returns it verbatim), so no relay version can strip it. A half-upgraded pair is one-directional: an old client still drops the key on read and behaves exactly as today. Before: 3 failed | 1 passed. After: 4 passed. (cherry picked from commit f864223)
enrick-dev
pushed a commit
to enrick-dev/orca
that referenced
this pull request
Oct 15, 2026
… through the normalizer (stablyai#16747) `defaultTerminalTabsAppliedByWorktreePath` is declared on the wire session (`src/shared/remote-workspace-types.ts:16`), emitted by the renderer's export (`remote-workspace-session-projection.ts:101-134`) and read back by its importer (`:195`) -- but `normalizeRemoteSession` rebuilds the session as an object literal and never copied it. Measured on a snapshot carrying `{ '/r': true }`: normalizeSnapshot(...).session.defaultTerminalTabsAppliedByWorktreePath => undefined remoteWorkspaceSessionMatchesSnapshot(withFlag, withoutFlag) => true Two consequences. `getRemoteSnapshot` normalizes everything the relay returns (`remote-workspace-relay-sync.ts:29`), so a client could never receive the flag even though the write path sends `session` verbatim. And `patchRemoteWorkspaceSession` short-circuits on `remoteWorkspaceSessionMatchesSnapshot` (`:51`), which normalizes both sides -- so a change that only sets this marker was invisible to the dirty check and could never be written at all. The marker is the sole guard on `applyDefaultTerminalTabs` (`worktree-default-terminal-tabs.ts:34`), so losing it re-applies the whole default-tab template over the user's tabs. This has never worked in either direction since the field was introduced. `normalizeRemoteSession` predates `6aab34cbdc9` under a different path -- it lived in `src/main/ipc/remote-workspace.ts` until `9107f6eab2e` split it out for max-lines, and at `6aab34cbdc9` it already copied all four sibling optional fields and simply never gained a fifth. No test caught it because that commit tested the projection round-trip (correct in isolation) while the normalizer sat in another file with no test of its own. The new test file closes that gap two ways: a case per consequence, plus a `Required<RemoteWorkspaceSession>` fixture asserted key-for-key against the normalizer's output. Because the normalizer is an object literal, the next field added to the wire type and forgotten there is now a compile error in this test rather than silent data loss. Wire compatibility: safe, but not by the plain "new optional field" rule -- this is an already-declared field that was silently stripped on every read. Both readers treat it as optional; the relay is not a reader at all (`src/relay/workspace-session-handler.ts:145-151` stores `patch.session` as an opaque record and returns it verbatim), so no relay version can strip it. A half-upgraded pair is one-directional: an old client still drops the key on read and behaves exactly as today. Before: 3 failed | 1 passed. After: 4 passed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stack: 2 of 6 — based on #16746. Smallest change in the stack; no semantics question.
ELI5
Orca can put a set of default terminal tabs into a new workspace, and it ticks a box saying "already did that one" so it never does it twice.
That tick-box is supposed to be shared with the remote machine. It never was. The code that reads data back from the remote quietly threw the box away every single time — since the day the feature shipped, in both directions.
So the remote never remembered, and every reconnect could lay the default tabs over the ones you already had.
The fix: carry that one field through instead of dropping it, plus a check that makes it a compile error to add a new shared field and forget to carry it.
Honest caveat: this only takes full effect once every client on a machine is upgraded. Until then an older client still drops the box and blanks it for everyone else.
Symptom
Every direct-SSH snapshot apply wipes the "default terminal tabs already applied" marker for that target's worktrees.
applyDefaultTerminalTabs(src/renderer/src/lib/worktree-default-terminal-tabs.ts:34) is guarded by that marker alone, so losing it re-applies the whole default-tab template over the user's tabs.Root cause
defaultTerminalTabsAppliedByWorktreePathis a declared wire field that has never worked in either direction. It is:src/shared/remote-workspace-types.ts:16src/shared/remote-workspace-session-projection.ts:101-134:195…but
normalizeRemoteSession(src/main/ipc/remote-workspace-snapshot-normalization.ts:32-65) rebuilds the session as an object literal and never copied it. Measured on a snapshot carrying{ '/r': true }:Two distinct consequences:
getRemoteSnapshotnormalizes whatever the relay returns (remote-workspace-relay-sync.ts:29), so a client can never receive this flag. The write path sendssessionverbatim (:66), so the flag can reach the relay — it just never comes back.patchRemoteWorkspaceSessionshort-circuits onremoteWorkspaceSessionMatchesSnapshot(current, session)(:51), which normalizes both sides and therefore cannot see this field. Marking default tabs applied is invisible to the dirty check.Origin, with a refinement reviewers will want.
372469b7528touches onlyremote-workspace-types.ts(+1),remote-workspace-session-projection.ts(+25) and its test — the normalizer is not in that stat. ButnormalizeRemoteSessionpredates it under a different path: it lived insrc/main/ipc/remote-workspace.tsuntil15e1ba3f84a(2026-08-15) split it out for max-lines. At372469b7528:src/main/ipc/remote-workspace.ts:58-92it already copied all four sibling optional fields and simply never gained a fifth. This field has never worked since the day it was introduced. Not a recent regression.No test caught it because that commit tested the projection round-trip (correct in isolation) while the normalizer sat in another file with no test of its own.
The fix, and why this shape
One added field in the normalizer's return literal, using the same
normalizeOptionalRecordas its four siblings.The new test file closes the structural gap two ways: a case per consequence, plus a
Required<RemoteWorkspaceSession>fixture asserted key-for-key against the normalizer's output. Because the normalizer is an object literal, the next field added to the wire type and forgotten here is now a compile error in this test rather than silent data loss. That ratchet is the point of the file; the one-line fix is not what needs protecting.Evidence
Before (fix reverted, test present):
After:
Wire compatibility
Safe — but not by the plain "a new optional field is safe" rule. This is an already-declared field that has been silently stripped on every read, not a new one.
docs/reference/remote-wire-compatibility.md:Both readers treat it as optional —
importRemoteWorkspaceSessioniteratesObject.keys(… ?? {}), so absent is a clean empty case.The relay is not a reader at all.
src/relay/workspace-session-handler.ts:145-151storespatch.sessionas an opaqueRecord<string, unknown>and returns it verbatim. No relay version can strip it, so there is no relay skew on this path.An old client on the same namespace actively blanks the marker. An earlier draft of this section claimed the opposite — that an old client "does not blank the shared snapshot, since its export has emitted the field since
372469b7528". That conflated emitting the key with emitting a value, and it is wrong. Traced onorigin/main:normalizeSnapshotstrips the field →undefinedimportRemoteWorkspaceSession(remote-workspace-session-projection.ts:194-198) →{}remote-workspace-session-merge.ts:257-259)omitTargetWorktreesdrops every target key and the remote half contributes nothing → marker cleared locallyexportRemoteWorkspaceSession(:101-108) rebuilds from that empty record → emits{}{}for every client on the namespaceSo this fix takes effect only once every peer on the namespace is upgraded. Until then an old client blanks the marker, and the fix is inert.
docs/reference/remote-wire-compatibility.mdsays mixed versions are the normal state, so that is the expected condition on landing, not an edge case.One narrow mitigation, which is not enough to rely on: a marker-only delta will not upload at all, because
remoteWorkspaceSessionMatchesSnapshotcannot see the field. But an unrelated upload — visit recency, a tab change — is near-certain in practice and carries the blanking{}with it.The code is correct and safe either way. Nothing here can lose a tab or corrupt a session; the failure mode is that a write-once marker gets cleared, which is exactly today's behaviour. This changes what the fix is worth on landing, not whether it is right.
Rule 3 does not apply: what the client publishes is unchanged; only what it reads changes.
Deliberately NOT done
normalizeOptionalRecordcasts without validating, uniform with its three siblings. Blast radius is bounded to marking a worktree applied. Not widened here.Found, not fixed (pre-existing, filed for follow-up):
importRemoteWorkspaceSessionsilently drops every path-keyed field whenuniqueWorktreeIdByPathreturns null for a path two worktree ids share. That affects all such fields, not just this one.Risk / blast radius
One field, one function. Worst case is that a marker now flows where it previously did not, which is the declared intent of the field. The
Required<>ratchet can only fail at compile time, never at runtime.How to verify
To see it fail:
git checkout main -- src/main/ipc/remote-workspace-snapshot-normalization.tsand re-run.End-to-end verification
Specs this PR routes to
Under
main's router the same two files route to[]— this fix would have shipped with no e2e coverage at all. That is the gap #16746 closes, and this is the first level to demonstrate it.Lane result
Covered by the full Docker-SSH lane at the stack tip (below). The routed subset for this level can also be run directly:
The two lane failures, resolved — and one is now exempted:
mainssh-docker-bulk-open-freeze-reproTypeError: … reading 'workerIndex'atdocker-ssh-relay-target.ts:226ssh-port-forward-lifecyclessh-port-forward-lifecycle-evidence.ts:159waiting ongetByText('Ports')Port-forward was re-run at the same commit and build and passed in 59.6s. It is green on
main, green at the tip in isolation, and red only inside the full lane — it is the set's one@headfulspec and runs last. Called flaky in-lane rather than "unrelated": a real lane-ordering problem, pre-existing, and worth tracking.Build provenance
This change adds no new identifier, so bundle-grep provenance is not available for this level, and I am not going to invent a symbol for it.
defaultTerminalTabsAppliedByWorktreePathalready appears in 5 files onmain(the wire type, the projection, its test, and two consumers), so its presence inout/main/index.jscannot distinguish a built-with from a built-without bundle. The count rises by one, which is too weak to rely on.The honest provenance for this level is the build SHA:
Clean tree at the stack tip. This level is contained in that build.
What is NOT covered
defaultTerminalTabsAppliedByWorktreePath. The direct proof for this change is the unit test, which is a genuine failing-first test — the e2e run here demonstrates no regression, not positive coverage of the field. Saying so plainly rather than implying otherwise.normalizeOptionalRecordcasts without checking, uniform with its three siblings. Blast radius is bounded to marking a worktree applied.importRemoteWorkspaceSessionsilently drops every path-keyed field whenuniqueWorktreeIdByPathreturns null for a path two worktree ids share. Affects all such fields.Failing-first test
Yes.
with the production hunk reverted to
main; 4 passed with it restored. TheRequired<RemoteWorkspaceSession>fixture additionally makes the next forgotten field a compile error rather than silent data loss.