Skip to content

fix(remote-workspace): restore a wire field the snapshot normalizer silently dropped - #16747

Merged
nwparker merged 1 commit into
mainfrom
nwparker/ssh-02-normalizer-field
Aug 28, 2026
Merged

nwparker merged 1 commit into
mainfrom
nwparker/ssh-02-normalizer-field

Conversation

@nwparker

@nwparker nwparker commented Aug 27, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 26 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​2546 $\color{#cf222e}{\Huge{\mathbf{−}}}$​69 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​2477
Prod 53 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​1945 $\color{#cf222e}{\Huge{\mathbf{−}}}$​552 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​1393

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

defaultTerminalTabsAppliedByWorktreePath is a declared wire field that has never worked in either direction. It is:

  • declared on the wire type — src/shared/remote-workspace-types.ts:16
  • populated by the renderer's export — src/shared/remote-workspace-session-projection.ts:101-134
  • read back by its importer — :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 }:

normalizeSnapshot(...).session.defaultTerminalTabsAppliedByWorktreePath  → undefined
remoteWorkspaceSessionMatchesSnapshot(withFlag, withoutFlag)             → true

Two distinct consequences:

  1. The read path always strips it. getRemoteSnapshot normalizes whatever the relay returns (remote-workspace-relay-sync.ts:29), so a client can never receive this flag. The write path sends session verbatim (:66), so the flag can reach the relay — it just never comes back.
  2. A flag-only change can never be written at all. patchRemoteWorkspaceSession short-circuits on remoteWorkspaceSessionMatchesSnapshot(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. 372469b7528 touches only remote-workspace-types.ts (+1), remote-workspace-session-projection.ts (+25) and its test — the normalizer is not in that stat. But normalizeRemoteSession predates it under a different path: it lived in src/main/ipc/remote-workspace.ts until 15e1ba3f84a (2026-08-15) split it out for max-lines. At 372469b7528:src/main/ipc/remote-workspace.ts:58-92 it 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 normalizeOptionalRecord as 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):

 Test Files  1 failed (1)
      Tests  3 failed | 1 passed (4)

 FAIL  … > normalizeSnapshot: field coverage > copies every declared field of the wire session
 FAIL  … > normalizeSnapshot: defaultTerminalTabsAppliedByWorktreePath > carries the marker through instead of dropping it
 FAIL  … > remoteWorkspaceSessionMatchesSnapshot > sees a change that only sets the default-terminal-tabs marker
      AssertionError: expected true to be false

After:

 Test Files  5 passed (5)
      Tests  19 passed (19)     # src/main/ipc/remote-workspace* + src/shared/remote-workspace*
$ pnpm tc → clean
$ pnpm run check:code-quality:changed → 0 new findings across 10 changed files

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 — importRemoteWorkspaceSession iterates Object.keys(… ?? {}), so absent is a clean empty case.

  • The relay is not a reader at all. src/relay/workspace-session-handler.ts:145-151 stores patch.session as an opaque Record<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 on origin/main:

    1. normalizeSnapshot strips the field → undefined
    2. importRemoteWorkspaceSession (remote-workspace-session-projection.ts:194-198) → {}
    3. the merge (remote-workspace-session-merge.ts:257-259) omitTargetWorktrees drops every target key and the remote half contributes nothing → marker cleared locally
    4. exportRemoteWorkspaceSession (:101-108) rebuilds from that empty record → emits {}
    5. the next upload overwrites the shared marker with {} for every client on the namespace

    So 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.md says 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 remoteWorkspaceSessionMatchesSnapshot cannot 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

  • The merge-side half. A client that never receives the marker still needs to keep its local one rather than lose it. That is PR 3 of this stack, where the merge gains the same "authoritative for what it knows, not for what it was never told" preservation branch every other field in that function already has. Neither half suffices alone: this one alone still loses the marker against an older relay; that one alone leaves a declared wire field permanently dead.
  • Validating record values. normalizeOptionalRecord casts 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): importRemoteWorkspaceSession silently drops every path-keyed field when uniqueWorktreeIdByPath returns 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

pnpm test src/main/ipc/remote-workspace-snapshot-normalization.test.ts

To see it fail: git checkout main -- src/main/ipc/remote-workspace-snapshot-normalization.ts and re-run.


End-to-end verification

Specs this PR routes to

$ git diff --name-only nwparker/ssh-01-e2e-lane..nwparker/ssh-02-normalizer-field \
    | node config/scripts/pr-e2e-source-routing.mjs
["tests/e2e/ssh-cold-activation-restore.spec.ts",
 "tests/e2e/ssh-reconnect-tab-destruction.spec.ts"]

$ … | node config/scripts/pr-e2e-source-routing.mjs --ssh-source
true

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:

pnpm test:e2e:ssh-docker -- tests/e2e/ssh-cold-activation-restore.spec.ts \
                            tests/e2e/ssh-reconnect-tab-destruction.spec.ts
$ pnpm test:e2e:ssh-docker
BUILD_SHA=49bb96e0b4c135ce305a2f4dfe2d4b52e0b19cde   DIRTY=0
14 specs / 20 tests → 17 passed, 2 failed, 1 skipped (10.7m)

The two lane failures, resolved — and one is now exempted:

Spec main tip (isolated) tip (full lane) Outcome
ssh-docker-bulk-open-freeze-repro FAILED — harness TypeError: … reading 'workerIndex' at docker-ssh-relay-target.ts:226 — FAILED Not a flake — a 100% failure, and three further arity bugs behind it. Now exempted from the lane; repair tracked in #16764
ssh-port-forward-lifecycle PASSED PASSED (59.6s) FAILED at ssh-port-forward-lifecycle-evidence.ts:159 waiting on getByText('Ports') Flaky in-lane, not a regression

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 @headful spec and runs last. Called flaky in-lane rather than "unrelated": a real lane-ordering problem, pre-existing, and worth tracking.

Note on the recorded run: the 14-spec result above predates the bulk-open exemption. The lane now runs 13 specs; bulk-open is not among them. The other 13 results are unaffected — nothing about that spec's failure changes another's outcome, since the runner passes them all to one Playwright invocation with --workers=1 and each spec owns its own fixture container.

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. defaultTerminalTabsAppliedByWorktreePath already appears in 5 files on main (the wire type, the projection, its test, and two consumers), so its presence in out/main/index.js cannot 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:

git rev-parse HEAD && git status --porcelain
BUILD_SHA=49bb96e0b4c135ce305a2f4dfe2d4b52e0b19cde   DIRTY=0

Clean tree at the stack tip. This level is contained in that build.

Provenance trap, reproduced on this tree. Do not grep a single renderer chunk. grep -c <sym> out/renderer/assets/store-*.js | head -1 matched store-DtDSfs7_.js and reported 0 for a symbol present 13 times across store-uJWnDUOY.js, App-CZkf3Bu7.js and quick-commands-menu-events-SBDd6cXN.js. Always use cat out/renderer/assets/*.js | grep -c <sym>.

Also: renderer console.warn never reaches the app log. Only main-process stdio is forwarded by ORCA_E2E_FORWARD_APP_LOGS=1.

What is NOT covered

  • No e2e spec asserts this field specifically. The two routed specs exercise SSH cold activation and reconnect tab destruction; neither reads 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.
  • The merge-side half is not in this PR. A client that never receives the marker still needs to keep its local one. That is fix(remote-workspace): host silence must not delete a local row it was never told about #16748. Neither half suffices alone.
  • Record values are not validated. normalizeOptionalRecord casts without checking, uniform with its three siblings. Blast radius is bounded to marking a worktree applied.
  • Pre-existing, found not fixed: importRemoteWorkspaceSession silently drops every path-keyed field when uniqueWorktreeIdByPath returns null for a path two worktree ids share. Affects all such fields.

Failing-first test

Yes.

 Test Files  1 failed (1)
      Tests  3 failed | 1 passed (4)

with the production hunk reverted to main; 4 passed with it restored. The Required<RemoteWorkspaceSession> fixture additionally makes the next forgotten field a compile error rather than silent data loss.

… 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
nwparker force-pushed the nwparker/ssh-02-normalizer-field branch from 5e16b6c to 13341a3 Compare August 28, 2026 02:41
@nwparker
nwparker requested a review from brennanb2025 as a code owner August 28, 2026 02:41
@nwparker
nwparker changed the base branch from nwparker/ssh-01-e2e-lane to main August 28, 2026 02:41
@nwparker
nwparker merged commit f864223 into main Aug 28, 2026
17 checks passed
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant