Skip to content

fix(runtime): a host with no window lists session tabs from its saved layout - #28421

Closed
Jinwoo-H wants to merge 59 commits into
mainfrom
pr3/session-tabs-from-saved-layout
Closed

Jinwoo-H wants to merge 59 commits into
mainfrom
pr3/session-tabs-from-saved-layout

Conversation

@Jinwoo-H

@Jinwoo-H Jinwoo-H commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 38 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​2243 $\color{#cf222e}{\Huge{\mathbf{−}}}$​219 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​2024
Prod 56 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​1688 $\color{#cf222e}{\Huge{\mathbf{−}}}$​135 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​1553

ELI5

On a computer running Orca without a window (a server that phones and other desktops connect to), the list of tabs those devices see was rebuilt from several in-memory sources that drifted apart: a moved tab could snap back, a closed tab could return, and the order could differ between devices. Now the server builds that list the way the desktop window builds its own tab strip: from the saved tab layout. Every change is saved first, and the list is read back from the save.

What Changed

Before: a host with no window kept its own tab list in memory, patched by each operation (create, move, close, select), and only some of those patches reached the saved layout. Phones and paired desktops saw that in-memory list, so it could disagree with what a window opening the same profile would show, and with itself after a restart.

After: with no window attached:

  • the session-tabs list is a projection of the saved layout (projectWindowlessSessionTabs), the same model and loader a window uses; it is re-projected after every saved-layout write, keeps one publication epoch, and tells subscribers about every change it stores;
  • creates, moves (through the existing old-client move translation and layout commands), closes and selections are saved to the layout first; the list follows;
  • live state is overlaid on the saved rows: a terminal's live process, its launch agent, a client page's live row, a host page's address and title;
  • a terminal being started is listed once its process is bound (UnboundTerminalTabs, on the existing stable-pane-create claim), so a client never types into a half-made tab;
  • a terminal tab saved only in another saved partition of the worktree ([Bug]: exact terminal close snaps back when one worktree is split across local and runtime session partitions #18202) is not listed, as a window does not list it, but closing it by handle or tab id still finds it in the partition that holds it (closeSnapshotFor, through fix(runtime): a terminal close commits in the session partition that holds the tab #27119's getWorkspaceSessionHostIdsForTab);
  • each paired device keeps its own selection; the device that moves a tab sees it selected where it lands.

With a window attached the list is unchanged: the window publishes its own list, as today. One shared read changes for both: when splitting or closing a terminal, the check that the tab is saved now reads the partition that holds the tab, not only the routed one (#18202).

Visible changes:

  • An untitled terminal is named "Terminal N" (by position) before a server restart too, not only after it.
  • A workspace's only tab is listed as active, as a window shows it.
  • A pane title set from a paired client stays a pane title; a sole pane's row shows the tab's title, as before.
  • Moving a tab selects it where it lands, for the host and the mover; a drop that changes no order does nothing.

Stacked on: #28166 (serve browser tabs), the client-hosted browser tab change (not yet opened; lands after #28166), and #28354 (chat tabs saved in the layout). The diff includes them until they merge.

Why

The window already has one rule for its tab strip: the saved layout, with live state overlaid. Giving the windowless host the same rule removes the separate in-memory bookkeeping that every bug in this area came from, and is the step before one runtime owner for the layout.

Alternatives considered:

  • Keeping the in-memory list and patching each drift. That is what the existing code did; each fix added another special case.
  • Listing tabs from every saved partition of a worktree. The window deliberately keeps a second host's copy of the same worktree id apart (it can be a different workspace on another host), so listing both would be a new rule the window does not have. Measured on main: without a prior publication, main's list does not show a spill-only tab either. The [Bug]: exact terminal close snaps back when one worktree is split across local and runtime session partitions #18202 close tests used to seed a published list containing both partitions; that seed stood in for a publisher that does not exist on main without one, so it is removed, and the tests now exercise the close's own cross-partition lookup.

Linked Issue

Workspace layout single-copy plan, part 2 (session tabs from the saved layout). Refs #18202.

Visual Proof

N/A: the list content is what the tests and the layout oracle check; the visible changes above are covered by the e2e specs listed below.

Testing

  • Unit: new windowless-session-tabs.test.ts and orca-runtime-tests/windowless-terminal-start.spec.ts; the [Bug]: exact terminal close snaps back when one worktree is split across local and runtime session partitions #18202 close tests now run without a seeded list and add a check that the list shows only the owner partition; existing suites moved to the saved-layout contract where they asserted the old in-memory list (pty-launch-parity, pty-retirement-publication-during-read, the [Bug]: exact terminal close snaps back when one worktree is split across local and runtime session partitions #18202 close tests). src/main/runtime passes in full. Across src/main and src/shared, the remaining failures also fail on main at the same base on this machine (browser-manager identity and viewport, packaged CLI assets, shell live tests, ssh/omp wrappers, serve-sim).

  • E2E: new headless-serve-mixed-tab-order.spec.ts and paired-desktop-mixed-tab-order.spec.ts (tab order across a phone and a paired desktop). The full suite on this head against main at the same base, and the layout oracle (runs in a comment).

  • Writer ratchet: a windowless host's layout writes go through one runtime method, applyWorkspaceSessionChange (counted once); the two view-selection edits in withSavedTabSelection are counted, since selection has no layout command yet. Both move onto the runtime's layout command channel.

  • I manually tested these changes locally

  • Automated tests added/updated, or explained why not below

AI Disclosure

Review

Agent skill upstream boundary

  • Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

  • Old clients / wire: no new fields or opcodes. Old clients receive the same list shape; the visible changes above reach them too.
  • SSH: the list reads the worktree's own partition, as the window's does; closes find a tab in whichever partition holds it.
  • Folder workspaces: projected the same way; an unroutable worktree saves nothing.
  • Known costs: every saved-layout write re-lists each listed worktree (coalesced per microtask); fine for today's sizes, to revisit with the runtime owner.
  • Follow-ups: some windowless paths still store a hand-built list that the next write re-reads from the layout (a phone tap that starts a pending agent, tab props, browser reconciliation); they converge, and move to the layout in the runtime-owner step. Also the mover's view on a desktop host (its own PR, reproduced first); moving stranded partition rows at load, after which unlisted-terminal-tab-close.ts is deleted.
  • Platforms: no platform-specific code.

Checklist

  • This PR is small and focused
  • I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
  • Before/after screenshots or videos attached for UI changes, or N/A with reason
  • Self-reviewed for correctness, security, and performance
  • Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
  • pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

A host with no window now saves the browser tabs it opens in the same shape a
desktop window saves its own, and restores them the same way: listed at once
with their last address, each page started when a client first opens or
drives it. A closed tab is forgotten; a page that ends with the process is not
a close.
…e id

Review fixes: a page's address is written onto its saved records without
reloading the layout, and only on committed navigations; reopening a saved
page writes nothing; a command naming only the page finds the workspace that
saved it; a refused save no longer throws from a page event or a close. The
browser-tab map is renamed to say it lists saved tabs too.
…the mover; a drop that changes no order is a no-op
…al when its binding is lost; serve-restart baseline names untitled rows by position before the restart too
…al names its launch agent; tests follow the saved-layout contract
…s, not the first saved one

A host now records the browser tab a window would show: the one it just
opened, and the one a tab switch picks. With nothing running, a command
that names no page starts that tab; when the layout shows none it starts
nothing and reports no browser tab open.
…aved' into pr3/session-tabs-from-saved-layout
… settled retire removes

Claude-Session: p2-headless
…nder its own epoch; review fixes

Claude-Session: p2-headless
@coderabbitai

coderabbitai Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: a5f832b9-35c8-471a-9494-d07f16d3492c
📥 Commits

Reviewing files that changed from the base of the PR and between b8e0db3 and b5695e5.

📒 Files selected for processing: 13
  • src/main/runtime/agent-session-tab-layout.ts
  • src/main/runtime/orca-runtime-close-structured-agent-session-tab.ts
  • src/main/runtime/orca-runtime-hydrate-headless-mobile-session-tabs-from-workspace-session.ts
  • src/main/runtime/orca-runtime-restore-structured-agent-session-tabs-once.ts
  • src/main/runtime/orca-runtime-runtime-id.ts
  • src/main/runtime/orca-runtime-serve-browser-restore.test.ts
  • src/main/runtime/serve-browser-tabs.ts
  • src/main/runtime/structured-agent-session-windowless-layout-host.test.ts
  • src/main/runtime/structured-agent-session-windowless-layout.test.ts
  • src/renderer/src/lib/structured-agent-session-provisional-tab.ts
  • src/shared/structured-agent-session-projection.ts
  • src/shared/workspace-layout/workspace-layout-command-types.ts
  • src/shared/workspace-layout/workspace-layout-content-commands.ts
💤 Files with no reviewable changes: 1
  • src/main/runtime/orca-runtime-runtime-id.ts
🚧 Files skipped from review as they are similar to previous changes: 1
  • src/main/runtime/orca-runtime-restore-structured-agent-session-tabs-once.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

The changes add windowless session-tab projection and persistence for agent-session tabs. They add saved serve-browser tab state, including page-state updates and lazy restoration. Runtime paths use saved layouts for tab selection, moves, and close handling. The changes also add expiry handling for persisted client-hosted pages and expand runtime and end-to-end tests.

Priority: ➖ Normal

Merge Risk: 🟡 Moderate · up to b5695

Resolve the persistent stale chat tab before merging. Strengthen the restart and paired-desktop checks so they detect tab loss and delayed regrouping.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 38.64% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 44 functions across 60 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly and concisely describes the main change: windowless hosts now list session tabs from the saved layout.
Description check Passed The description is detailed and covers the user impact, implementation, rationale, linked issue, visual-proof decision, testing, compatibility considerations, and checklist. Minor omissions include un…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
  • Fix all pre-merge checks with AI
✨ Finishing Touches: 💡 1
📝 Generate docstrings: 💡
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3


ℹ️ Review info
⚙️ Run configuration
  • Configuration used: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 8e753c31-769e-4846-9f3e-d6c0aa9d778e
📥 Commits

Reviewing files that changed from the base of the PR and between 0903ed9 and 46938f6.

📒 Files selected for processing: 90
  • config/main-layout-writer-baseline.txt
  • config/scripts/check-compat-boundary-imports.mjs
  • config/scripts/vitest-node-runtime-files.mjs
  • src/main/browser/offscreen-browser-backend.ts
  • src/main/ipc/pty-launch-parity-caller.test-cases.ts
  • src/main/ipc/pty-launch-parity-host.test-cases.ts
  • src/main/ipc/pty-launch-parity.test-fixture.ts
  • src/main/persistence/loading-store/pty-retirement-publication-during-read.test.ts
  • src/main/runtime/agent-session-tab-layout.ts
  • src/main/runtime/client-hosted-browser-page-persistence.ts
  • src/main/runtime/client-hosted-browser-tab-layout.integration.test.ts
  • src/main/runtime/client-hosted-session-browser-tabs.ts
  • src/main/runtime/created-mobile-session-tab-caller-selection.test.ts
  • src/main/runtime/orca-runtime-apply-mobile-session-tab-navigation.ts
  • src/main/runtime/orca-runtime-browser-client-hosted.test.ts
  • src/main/runtime/orca-runtime-build-headless-mobile-session-browser-tabs.ts
  • src/main/runtime/orca-runtime-close-headless-mobile-terminal-tab.ts
  • src/main/runtime/orca-runtime-close-mobile-session-tab.ts
  • src/main/runtime/orca-runtime-close-structured-agent-session-tab.ts
  • src/main/runtime/orca-runtime-create-terminal.ts
  • src/main/runtime/orca-runtime-get-pty-record-for-pane-key.ts
  • src/main/runtime/orca-runtime-get-runtime-id.ts
  • src/main/runtime/orca-runtime-hydrate-headless-mobile-session-tabs-from-workspace-session.ts
  • src/main/runtime/orca-runtime-move-headless-mobile-session-tab.test.ts
  • src/main/runtime/orca-runtime-perform-mobile-session-pty-records-refresh.ts
  • src/main/runtime/orca-runtime-persist-headless-session-tab-props.ts
  • src/main/runtime/orca-runtime-persist-headless-terminal-title.ts
  • src/main/runtime/orca-runtime-prune-mobile-session-tab-group-layout.ts
  • src/main/runtime/orca-runtime-pty-foreground-process-reads.ts
  • src/main/runtime/orca-runtime-refuse-unattributed-mobile-session-tab-close.ts
  • src/main/runtime/orca-runtime-resolve-terminal-split-source-authority.ts
  • src/main/runtime/orca-runtime-restore-structured-agent-session-tabs-once.ts
  • src/main/runtime/orca-runtime-runtime-id.ts
  • src/main/runtime/orca-runtime-schedule-mobile-session-tabs-changed.ts
  • src/main/runtime/orca-runtime-serve-browser-restore.test.ts
  • src/main/runtime/orca-runtime-stored-mobile-snapshot-has-stale-preserved-tab.ts
  • src/main/runtime/orca-runtime-structured-session-restore.test.ts
  • src/main/runtime/orca-runtime-terminal-close-spill-partition.test.ts
  • src/main/runtime/orca-runtime-terminal-drivers.ts
  • src/main/runtime/orca-runtime-test-fixtures.spec.ts
  • src/main/runtime/orca-runtime-tests/exit-retirement-activation.spec.ts
  • src/main/runtime/orca-runtime-tests/mobile-session-tabs-cold-serve-hydrate.spec.ts
  • src/main/runtime/orca-runtime-tests/mobile-session-tabs-part-05.spec.ts
  • src/main/runtime/orca-runtime-tests/mobile-session-tabs-part-06.spec.ts
  • src/main/runtime/orca-runtime-tests/mobile-session-tabs-part-09.spec.ts
  • src/main/runtime/orca-runtime-tests/windowless-terminal-start.spec.ts
  • src/main/runtime/orca-runtime-wait-for-mobile-terminal-surface.ts
  • src/main/runtime/orca-runtime.test.ts
  • src/main/runtime/orca-runtime.ts
  • src/main/runtime/renderer-browser-session-reconciliation.test.ts
  • src/main/runtime/rpc/methods/session-tab-browser-placement-mutations.test.ts
  • src/main/runtime/rpc/methods/session-tab-mutation-methods.ts
  • src/main/runtime/rpc/methods/session-tabs-move-validation.test.ts
  • src/main/runtime/rpc/methods/session-tabs.test.ts
  • src/main/runtime/rpc/methods/structured-chat-tab-table.test-fixture.ts
  • src/main/runtime/rpc/methods/structured-worker-tab-retirement.test.ts
  • src/main/runtime/runtime-browser-commands-active-screencasts-by-page-id.ts
  • src/main/runtime/runtime-browser-commands-browser-command-target-params.ts
  • src/main/runtime/runtime-browser-commands-browser-tab-close.ts
  • src/main/runtime/runtime-browser-commands-browser-tab-create.ts
  • src/main/runtime/runtime-browser-commands-browser-tab-list.ts
  • src/main/runtime/runtime-browser-commands-list-logical-browser-tabs.ts
  • src/main/runtime/serve-browser-tab-layout.test.ts
  • src/main/runtime/serve-browser-tab-layout.ts
  • src/main/runtime/serve-browser-tabs.ts
  • src/main/runtime/structured-agent-session-host-refusal.test.ts
  • src/main/runtime/structured-agent-session-startup-tab-restore.test.ts
  • src/main/runtime/structured-agent-session-windowless-layout-host.test.ts
  • src/main/runtime/structured-agent-session-windowless-layout.test.ts
  • src/main/runtime/unbound-terminal-tabs.ts
  • src/main/runtime/unlisted-terminal-tab-close.ts
  • src/main/runtime/windowless-session-tab-move.ts
  • src/main/runtime/windowless-session-tabs.test.ts
  • src/main/runtime/windowless-session-tabs.ts
  • src/main/startup/main-process-runtime-launch.ts
  • src/shared/workspace-layout/old-client/index.ts
  • src/shared/workspace-layout/old-client/old-client-session-tab-groups.ts
  • src/shared/workspace-layout/old-client/old-client-session-tabs-projection.test.ts
  • src/shared/workspace-layout/old-client/old-client-session-tabs-projection.ts
  • src/shared/workspace-layout/workspace-layout-command-types.ts
  • src/shared/workspace-layout/workspace-layout-content-commands.ts
  • src/shared/workspace-layout/workspace-layout-load-order.ts
  • tests/e2e/headless-serve-browser-tab-restart.spec.ts
  • tests/e2e/headless-serve-mixed-tab-order.spec.ts
  • tests/e2e/layout-compat-baselines.json
  • tests/e2e/layout-compat-serve-restart-keeps-at-at-terminals.spec.ts
  • tests/e2e/paired-client-hosted-browser-ghost-close.spec.ts
  • tests/e2e/paired-desktop-mixed-tab-order.spec.ts
  • tests/e2e/paired-mobile-desktop-tab-composition.spec.ts
  • tests/e2e/workspace-layout-oracle-known-on-main.ts
💤 Files with no reviewable changes: 1
  • tests/e2e/workspace-layout-oracle-known-on-main.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

Comment on lines +71 to +73
for (const sessionId of this.savedAgentSessionTabs().keys()) {
if (!host?.deps?.store?.isSessionUnreadable?.(sessionId)) {
this.removeWindowlessAgentSessionTab(sessionId)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Remove a confirmed missing chat even when the tab index is absent.

If a legacy profile has no tab index and its saved chat record is gone, restored is empty. Index seeding then writes nothing. removeWindowlessAgentSessionTab(sessionId) also does nothing because its retirement check requires a present index. The dead tab remains saved across restarts. For a session absent from restored and not marked unreadable, use the settled removal path; keep restored and unreadable sessions. (raw.githubusercontent.com)

Comment on lines +90 to +91
const listed = new Set((await strip(a, worktree)).flat())
await expectStrip('warm restart', [[first, browser, third].filter((id) => listed.has(id))])

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Require both terminal tabs after restart.

If either first or third disappears but two other tabs remain, filtering by listed removes the missing terminal from the expectation. The restart check can then pass despite losing a terminal. Assert that first and third are present before allowing the browser tab to be optional.

Comment on lines +152 to +155
await expect
.poll(take, { timeout: 90_000 })
.toBe(expected)
.catch(() => undefined)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Wait for the trigger before accepting the retained strip.

takeDesktopStrips retains the last strip, which already equals expected after the setup step. After a network restore or another asynchronous trigger, this poll can pass on that old strip before the desktop processes the trigger. A later regroup is then absent from findings. Add a trigger-specific completion check before settlement, then observe the strip through a bounded quiet period.

@Jinwoo-H

Copy link
Copy Markdown
Contributor Author

E2E evidence for this head and main at the same base (3a011e4):

  • Full suite on 46938f6 (run 38468145318) and on main at the base (run 38464353557). The commits after 46938f6 change only tests and lint.
    • Failures only on the head, first pass:
      • the 9 orcad cases of workspace-layout-oracle-headless.spec.ts failed with "out/orcad or its pinned Node is missing". The general shard does not build orcad. Those cases run in the D7 job, which builds it, and pass there (below).
      • 6 others (GitHub issue prefill, Linear URL entry, markdown find ×2, OS-opened documents ×2) were re-run once on both. They fail identically on the head (run 38483805703) and on main at the base (run 38483807939), so they also fail on main.
    • The Windows D7 job hit a registry network reset during setup; its re-run passed.
  • PR workflow on b8e0db3 (run 38487652060):
    • layout oracle: 21/21 passed;
    • D7: 18/18 headless oracle cases passed, orcad and Electron;
    • unit shards 1–5, static analysis, package and package (windows) all passed.
  • New specs on the head (run 38483805703) all passed: headless-serve-mixed-tab-order, paired-desktop-mixed-tab-order (6 triggers), and paired-client-hosted-browser-ghost-close.

Review pass: the saved tab reuses the id status and attention address, the close
checks for a window before scanning partitions, and the host tests seed readable
records with unreadable, other-host and no-index cases.

Claude-Session: p2-headless
A desktop document page or a remote page recorded as active no longer leaves a
pageless command with no tab. Adds a test for the first-saved-worktree scope.

Claude-Session: p2-headless
… into fix/client-hosted-browser-tabs-saved

# Conflicts:
#	src/main/runtime/serve-browser-tabs.ts
…aved' into pr3/session-tabs-from-saved-layout
…to pr3/session-tabs-from-saved-layout

# Conflicts:
#	src/main/runtime/orca-runtime-close-structured-agent-session-tab.ts
The window's existing-tab lookup moves to the shared projection so the
windowless-layout test exercises it without importing the renderer.

Claude-Session: p2-headless
@Jinwoo-H

Copy link
Copy Markdown
Contributor Author

Replaced by a smaller series; follow-up PRs link here.

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