// Drive user/CLI/paired-client layout journeys; compare structural rules, window DOM, client/CLI views, expected layout and restart preservation after every step. // Fail findings absent from workspace-layout-oracle-known-on-main.ts. ORCA_LAYOUT_ORACLE_RECORD=1 records without failing; ORCA_LAYOUT_ORACLE_REPEAT= repeats. import { mkdtempSync, rmSync } from 'node:fs' import os from 'node:os' import path from 'node:path' import type { Page } from '@stablyai/playwright-test' import { test, expect } from './helpers/orca-app' import { moveTerminalPaneByLeafId, readTerminalPaneDomLeafOrder, splitActiveTerminalPane, waitForActiveTerminalManager } from './helpers/terminal' import { bootstrapFirstLaunch, seededRepoPathOrSkip } from './helpers/terminal-restart-persistence' import { createTerminalTabFromMenu, SORTABLE_TAB } from './helpers/terminal-tab-menu' import { ensureTerminalVisible, waitForSessionReady } from './helpers/store' import { addFolderWorkspace, closeActivePaneFromKeyboard, dragPaneOutToTabStrip, waitForBoundPanes } from './helpers/terminal-layout-journeys' import { addHostCreatedSplitWorktree, openHostSplitWorktree, sleepAgentPane, wakeByClick } from './helpers/host-split-and-sleep-journeys' import { runOracleScenario, type OracleRun } from './helpers/workspace-layout-oracle-session' import { RuntimeClient } from '../../src/cli/runtime/client' import { unexpectedFindings } from './workspace-layout-oracle-known-on-main' import type { RuntimeTerminalListResult } from '../../src/shared/runtime-types' import type { RuntimeMobileSessionTabsResult } from '../../src/shared/runtime-session-contracts' type Scenario = { id: string /** Defaults to the seeded repo's first worktree with one terminal. */ setup?: (run: OracleRun) => Promise<{ worktreeId: string; cleanup?: () => void }> journey: (run: OracleRun, worktreeId: string) => Promise /** False where a pane runs an agent, not a shell, so an echo proves nothing. */ endMarkers?: false } async function listTerminals(run: OracleRun, worktreeId: string) { const listed = await run.client.call('terminal.list', { worktree: `id:${worktreeId}` }) return listed.result.terminals } async function firstHandle(run: OracleRun, worktreeId: string): Promise { let handle: string | undefined await expect .poll(async () => { handle = (await listTerminals(run, worktreeId).catch(() => []))[0]?.handle return handle }) .toBeDefined() return handle! } /** The relaunched window shows the worktree again, however many panes its tab restores. */ async function reopenActiveWorktree(page: Page): Promise { await waitForSessionReady(page) await ensureTerminalVisible(page) await waitForActiveTerminalManager(page, 30_000) } /** A client paired to the window's runtime over its WebSocket offer, with its own state directory. */ // Both clients use the window's one runtime offer, as the headless corpus's two clients share one. async function pairWindowClient(run: OracleRun, stateDir: string): Promise { const offer = await run.page.evaluate(() => window.api.mobile.getRuntimePairingUrl({ address: '127.0.0.1' }) ) if (!offer.available || !offer.pairingUrl) { throw new Error('The window runtime did not offer a pairing') } return new RuntimeClient(stateDir, 30_000, offer.pairingUrl, null) } /** Each paired client's tab order must equal the CLI's; a difference is a `client` finding. */ async function compareClientTabOrders( run: OracleRun, step: string, worktreeId: string, clients: Record ): Promise { const order = async (client: RuntimeClient) => JSON.stringify( ( await client.call('session.tabs.list', { worktree: `id:${worktreeId}` }) ).result.tabGroups?.map((group) => group.tabOrder) ?? [] ) const expected = await order(run.client) for (const [name, client] of Object.entries(clients)) { const seen = await order(client) if (seen !== expected) { run.oracle.findings.push({ check: 'client', step, details: [`${name} tab order ${seen} vs CLI ${expected}`] }) } } } async function splitTwice(page: Page): Promise { await splitActiveTerminalPane(page, 'vertical') await waitForBoundPanes(page, 2) await splitActiveTerminalPane(page, 'horizontal') await waitForBoundPanes(page, 3) } async function newTabFromMenu(page: Page): Promise { // The tab menu can miss a click while the previous tab's menu is still closing. await createTerminalTabFromMenu(page).catch(async () => { await page.keyboard.press('Escape') await createTerminalTabFromMenu(page) }) await waitForActiveTerminalManager(page) await waitForBoundPanes(page, 1) } const SCENARIOS: Scenario[] = [ { id: 'create-tab', journey: async (run, worktreeId) => { await newTabFromMenu(run.page) await run.oracle.step('new tab', { worktreeId, panesPerTab: [1, 1] }) } }, { id: 'split-right-down', journey: async (run, worktreeId) => { await splitTwice(run.page) await run.oracle.step('split twice', { worktreeId, panesPerTab: [3] }) } }, { id: 'close-pane', journey: async (run, worktreeId) => { await splitTwice(run.page) await run.oracle.step('split twice', { worktreeId, panesPerTab: [3] }) await closeActivePaneFromKeyboard(run.page, 3) await run.oracle.step('close pane', { worktreeId, panesPerTab: [2], removed: 1 }) } }, { id: 'close-tab', journey: async (run, worktreeId) => { await newTabFromMenu(run.page) await run.oracle.step('new tab', { worktreeId, panesPerTab: [1, 1] }) const firstTab = run.page.locator(SORTABLE_TAB).first() await firstTab.getByRole('button', { name: /^Close tab /i }).click() await expect(run.page.locator(SORTABLE_TAB)).toHaveCount(1) await run.oracle.step('close first tab', { worktreeId, panesPerTab: [1], removed: 1 }) } }, { id: 'reorder-panes', journey: async (run, worktreeId) => { await splitActiveTerminalPane(run.page, 'vertical') await waitForBoundPanes(run.page, 2) const [firstLeaf, secondLeaf] = await readTerminalPaneDomLeafOrder(run.page) await moveTerminalPaneByLeafId(run.page, secondLeaf!, firstLeaf!, 'left') await expect .poll(() => readTerminalPaneDomLeafOrder(run.page)) .toEqual([secondLeaf, firstLeaf]) await run.oracle.step('swap panes', { worktreeId, panesPerTab: [2] }) } }, { // A paired client reorders the tab bar through the runtime command. id: 'client-reorder-tabs', journey: async (run, worktreeId) => { await newTabFromMenu(run.page) await newTabFromMenu(run.page) await run.oracle.step('three tabs', { worktreeId, panesPerTab: [1, 1, 1] }) const tabs = await run.client.call('session.tabs.list', { worktree: `id:${worktreeId}` }) const group = tabs.result.tabGroups?.[0] expect(group?.tabOrder.length).toBe(3) const reversed = group!.tabOrder.toReversed() await run.client.call('session.tabs.move', { worktree: `id:${worktreeId}`, tabId: reversed[0], targetGroupId: group!.id, kind: 'reorder', tabOrder: reversed }) await run.oracle.step('client reverses tab order', { worktreeId, panesPerTab: [1, 1, 1] }) } }, { // STA-9259: the dragged-out pane must live in exactly one tab, across two restarts. id: 'drag-out-to-tab', journey: async (run, worktreeId) => { await splitActiveTerminalPane(run.page, 'vertical') await waitForBoundPanes(run.page, 2) const [, secondLeaf] = await readTerminalPaneDomLeafOrder(run.page) await dragPaneOutToTabStrip(run.page, worktreeId, secondLeaf!) await expect(run.page.locator(SORTABLE_TAB)).toHaveCount(2) await waitForBoundPanes(run.page, 1) await run.oracle.step('drag pane out', { worktreeId, panesPerTab: [1, 1] }) await run.relaunch({ worktreeId, paneCount: 1, panesPerTab: [1, 1] }) await run.relaunch({ worktreeId, paneCount: 1, panesPerTab: [1, 1] }) } }, { id: 'cli-split', journey: async (run, worktreeId) => { const handle = await firstHandle(run, worktreeId) await run.client.call('terminal.split', { terminal: handle, direction: 'horizontal' }) await waitForBoundPanes(run.page, 2) await run.oracle.step('CLI split', { worktreeId, panesPerTab: [2] }) } }, { // #19582 and #10747 with a window: a CLI-created tab, renamed, then closed. id: 'cli-create-rename-close', journey: async (run, worktreeId) => { await run.client.call('terminal.create', { worktree: `id:${worktreeId}` }) await expect.poll(async () => (await listTerminals(run, worktreeId)).length).toBe(2) await run.oracle.step('CLI create', { worktreeId, panesPerTab: [1, 1] }) const created = (await listTerminals(run, worktreeId))[1]! await run.client.call('terminal.rename', { terminal: created.handle, title: 'oracle-renamed' }) await run.oracle.step('CLI rename', { worktreeId, panesPerTab: [1, 1] }) await run.client.call('terminal.close', { terminal: created.handle }) await run.oracle.step('CLI close', { worktreeId, panesPerTab: [1], removed: [created.leafId] }) } }, { // The paired-client tab commands: create a terminal tab, split it into a new group, close it. id: 'client-create-split-close', journey: async (run, worktreeId) => { const worktree = `id:${worktreeId}` const created = await run.client.call<{ tab: { parentTabId: string } }>( 'session.tabs.createTerminal', { worktree } ) const tabId = created.result.tab.parentTabId await run.oracle.step('client creates tab', { worktreeId, panesPerTab: [1, 1] }) const tabs = await run.client.call('session.tabs.list', { worktree }) await run.client.call('session.tabs.move', { worktree, tabId, targetGroupId: tabs.result.tabGroups![0]!.id, kind: 'split', splitDirection: 'right' }) await run.oracle.step('client moves tab to a new group', { worktreeId, panesPerTab: [1, 1] }) await run.client.call('session.tabs.close', { worktree, tabId, reason: 'user' }) await run.oracle.step('client closes tab', { worktreeId, panesPerTab: [1], removed: 1 }) } }, { // #9450 with a window attached: paired client A creates, paired client B closes. id: 'two-clients-create-close', journey: async (run, worktreeId) => { const stateDir = mkdtempSync(path.join(os.tmpdir(), 'layout-oracle-clients-')) try { const clients = { 'client A': await pairWindowClient(run, path.join(stateDir, 'a')), 'client B': await pairWindowClient(run, path.join(stateDir, 'b')) } const worktree = `id:${worktreeId}` const create = async () => ( await clients['client A'].call<{ tab: { parentTabId: string } }>( 'session.tabs.createTerminal', { worktree } ) ).result.tab.parentTabId const first = await create() await create() await run.oracle.step('A creates two tabs', { worktreeId, panesPerTab: [1, 1, 1] }) await compareClientTabOrders(run, 'A creates two tabs', worktreeId, clients) await clients['client B'].call('session.tabs.close', { worktree, tabId: first, reason: 'user' }) await run.oracle.step('B closes one', { worktreeId, panesPerTab: [1, 1], removed: 1 }) await compareClientTabOrders(run, 'B closes one', worktreeId, clients) } finally { rmSync(stateDir, { recursive: true, force: true }) } } }, { // The CLI and a phone move the host window ('host' navigation); the layout must not change. id: 'host-navigation', // It ends on an editor tab, so its markers are checked while a terminal is shown. endMarkers: false, journey: async (run, worktreeId) => { await newTabFromMenu(run.page) await run.oracle.step('new tab', { worktreeId, panesPerTab: [1, 1] }) const first = (await listTerminals(run, worktreeId))[0]! await run.client.call('terminal.focus', { terminal: first.handle, navigation: 'host' }) await expect( run.page.locator(`${SORTABLE_TAB}[data-tab-id="${first.tabId}"][data-active="true"]`) ).toHaveCount(1) await run.oracle.step('CLI focuses the first tab', { worktreeId, panesPerTab: [1, 1] }) await run.oracle.checkMarkers('first tab shown', worktreeId) await run.client.call('files.open', { worktree: `id:${worktreeId}`, relativePath: 'README.md', navigation: 'host' }) await expect( run.page.locator('[data-tab-group-strip-id]').getByText('README.md').first() ).toBeVisible() await run.oracle.step('CLI opens a file', { worktreeId, panesPerTab: [1, 1] }) } }, { // A reloaded window republishes its graph, which is what the phone's tab list is built from. id: 'window-reload', journey: async (run, worktreeId) => { await splitActiveTerminalPane(run.page, 'vertical') await waitForBoundPanes(run.page, 2) await run.oracle.step('split', { worktreeId, panesPerTab: [2] }) await run.reloadWindow() await waitForActiveTerminalManager(run.page) await waitForBoundPanes(run.page, 2).catch(() => {}) await run.oracle.step( 'after window reload', { worktreeId, panesPerTab: [2] }, { allowRemount: true } ) } }, { // Quit straight after a gesture: only the quit-time save can carry it. id: 'quit-right-after-change', journey: async (run, worktreeId) => { await splitActiveTerminalPane(run.page, 'vertical') await run.relaunch({ worktreeId, paneCount: 2, panesPerTab: [2], quitWithoutSettling: true, reopen: reopenActiveWorktree }) } }, { // An older phone build sends a whole pane tree; a stale one must not drop a live pane. id: 'old-client-pane-tree', journey: async (run, worktreeId) => { const handle = await firstHandle(run, worktreeId) await run.client.call('terminal.split', { terminal: handle, direction: 'vertical' }) await waitForBoundPanes(run.page, 2) await run.oracle.step('split', { worktreeId, panesPerTab: [2] }) const [first] = await listTerminals(run, worktreeId) await run.client .call('session.tabs.updatePaneLayout', { worktree: `id:${worktreeId}`, tabId: first!.tabId, root: { type: 'leaf', leafId: first!.leafId } }) .catch(() => {}) await run.oracle.step('stale pane tree from an old client', { worktreeId, panesPerTab: [2] }) } }, { id: 'restart-restore', journey: async (run, worktreeId) => { await splitActiveTerminalPane(run.page, 'vertical') await waitForBoundPanes(run.page, 2) await newTabFromMenu(run.page) await run.oracle.step('split and new tab', { worktreeId, panesPerTab: [2, 1] }) await run.relaunch({ worktreeId, paneCount: 1, panesPerTab: [2, 1] }) await run.oracle.checkMarkers('after relaunch', worktreeId) } }, { id: 'cold-daemon-restart', journey: async (run, worktreeId) => { await splitActiveTerminalPane(run.page, 'vertical') await waitForBoundPanes(run.page, 2) await newTabFromMenu(run.page) await run.oracle.step('split and new tab', { worktreeId, panesPerTab: [2, 1] }) await run.relaunch({ worktreeId, paneCount: 1, coldDaemon: true, panesPerTab: [2, 1] }) await run.oracle.checkMarkers('after cold relaunch', worktreeId) } }, { // The in-app "restart terminal daemon" action, with the window open. id: 'live-daemon-restart', journey: async (run, worktreeId) => { await splitActiveTerminalPane(run.page, 'vertical') await waitForBoundPanes(run.page, 2) const before = await run.oracle.step('split', { worktreeId, panesPerTab: [2] }) run.oracle.rememberForRestart(before) await run.page.evaluate(() => window.api.pty.management.restart()) await waitForBoundPanes(run.page, 2).catch(() => {}) const after = await run.oracle.step( 'daemon restarted', { worktreeId, panesPerTab: [2], terminalsRestart: true }, { allowRemount: true } ) run.oracle.compareRestart('daemon restart', after, { maskPtyIds: true }) await run.oracle.checkMarkers('after daemon restart', worktreeId) // What the user gets back after the next relaunch is the layout that survived. await run.relaunch({ worktreeId, paneCount: 2, panesPerTab: [2] }) } }, { id: 'folder-workspace', setup: async (run) => addFolderWorkspace(run.page), journey: async (run, worktreeId) => { await splitActiveTerminalPane(run.page, 'vertical') await waitForBoundPanes(run.page, 2) await newTabFromMenu(run.page) await run.oracle.step('split and new tab', { worktreeId, panesPerTab: [2, 1] }) } }, { // A host creates and manually splits a terminal, then the user returns to its saved layout. id: 'host-split-reactivation', // Its own worktree's panes are checked in the journey; the seeded one is no longer shown. endMarkers: false, setup: async (run) => addHostCreatedSplitWorktree(run.page, run.userDataDir), journey: async (run) => { const setupWorktreeId = await openHostSplitWorktree(run.page, run.userDataDir) run.worktreeIds.push(setupWorktreeId) await run.oracle.step('open setup worktree', { worktreeId: setupWorktreeId, panesPerTab: [2] }) await run.oracle.checkMarkers('setup worktree', setupWorktreeId) } }, { id: 'sleep-quit-resume', endMarkers: false, journey: async (run, worktreeId) => { await sleepAgentPane(run.page, worktreeId) await run.oracle.step('sleep agent pane', { worktreeId, panesPerTab: [2] }) await run.relaunch({ worktreeId, paneCount: 2, panesPerTab: [2], terminalsRestart: true, reopen: wakeByClick }) } } ] const REPEAT = Math.max(1, Number(process.env.ORCA_LAYOUT_ORACLE_REPEAT ?? 1)) const RECORD_ONLY = process.env.ORCA_LAYOUT_ORACLE_RECORD === '1' for (const scenario of SCENARIOS) { for (let attempt = 1; attempt <= REPEAT; attempt += 1) { const suffix = REPEAT > 1 ? ` #${attempt}` : '' // oxlint-disable-next-line no-empty-pattern -- Each scenario owns its launches. test(`layout oracle: ${scenario.id}${suffix}`, async ({}, testInfo) => { const repoPath = seededRepoPathOrSkip() const findings = await runOracleScenario(testInfo, scenario.id, async (run) => { let cleanup: (() => void) | undefined try { let worktreeId: string if (scenario.setup) { const setup = await scenario.setup(run) worktreeId = setup.worktreeId cleanup = setup.cleanup } else { worktreeId = (await bootstrapFirstLaunch(run.page, repoPath)).worktreeId } run.worktreeIds.push(worktreeId) await waitForBoundPanes(run.page, 1) await run.oracle.step('start', { worktreeId, panesPerTab: [1] }) await scenario.journey(run, worktreeId) if (scenario.endMarkers !== false) { await run.oracle.checkMarkers('end', worktreeId) } } finally { cleanup?.() } }) for (const finding of findings) { console.log( `[layout-oracle] ${scenario.id}: ${finding.check} @ ${finding.step}\n ${finding.details.join('\n ')}` ) } if (!RECORD_ONLY) { expect(unexpectedFindings(scenario.id, findings)).toEqual([]) } }) } }