Merge pull request #603 from nwparker/cloud/paired-held-active

fix(cloud): PAIRED-HELD-ACTIVE a GitHub-only create's held placeholder is its one tab and in front (n39)
This commit is contained in:
Neil
2026-11-12 20:57:02 -08:00
committed by GitHub
2 changed files with 328 additions and 3 deletions
@@ -15,6 +15,13 @@ import { isTuiAgent } from '../../../../shared/agent-launch/catalog/tui-agent-co
import { tuiAgentDisplayName } from '../../../../shared/agent-launch/catalog/tui-agent-display-names'
import { parseExecutionHostId } from '../../../../shared/execution-host'
import { isOrcaCloudEnvironmentForLaunch } from './orca-cloud-environment-id'
import { readHeldCloudLaunches } from './cloud-held-launch-memory'
import {
beginWebRuntimeInitialTerminalBootstrap,
endWebRuntimeInitialTerminalBootstrap,
isWebRuntimeInitialTerminalBootstrapInFlight,
markWebRuntimeInitialTerminalBootstrapAwaitingMirror
} from '@/runtime/web-session-tabs-sync/initial-terminal/web-runtime-initial-terminal-bootstrap'
export type FirstCloudAgentRequest = {
fullName: string
@@ -39,17 +46,29 @@ export async function launchFirstCloudAgent(request: FirstCloudAgentRequest): Pr
const worktreeId =
request.worktreeId ?? (request.hostId ? await waitForFirstWorktree(request.hostId) : null)
const host = parseExecutionHostId(request.hostId)
const environmentId = host?.kind === 'runtime' ? host.environmentId : null
// PAIRED-HELD-ACTIVE: the agent's tab (or its held placeholder) is this workspace's first terminal.
// Without the claim, the mirror's first empty frame seeds a plain shell too, activated, which hides
// the held placeholder and its "Set up once" strip behind a bare prompt (n39).
const claimed =
worktreeId && environmentId
? beginWebRuntimeInitialTerminalBootstrap(environmentId, worktreeId)
: false
const confirmed =
!worktreeId ||
host?.kind !== 'runtime' ||
(await waitForOrcaCloudEnvironment(host.environmentId, deadline))
!worktreeId || !environmentId || (await waitForOrcaCloudEnvironment(environmentId, deadline))
if (!worktreeId || !confirmed) {
if (claimed && worktreeId && environmentId) {
endWebRuntimeInitialTerminalBootstrap(environmentId, worktreeId)
}
agentNotStartedNotice(request.agent, request.fullName, request.hostId)
return
}
const agent = isTuiAgent(request.agent)
? request.agent
: await resolveDefaultAgentForWorktree(useAppStore.getState, worktreeId).catch(() => null)
if (environmentId) {
void settleFirstTerminal({ environmentId, worktreeId, claimed, launched: Boolean(agent) })
}
if (!agent) {
return
}
@@ -63,6 +82,108 @@ export async function launchFirstCloudAgent(request: FirstCloudAgentRequest): Pr
})
}
/** How long the first agent's tab may take to reach this workspace's mirror. */
const FIRST_TAB_WAIT_MS = 30_000
/**
* The claimed bootstrap latch is released once the workspace has a tab (the seeder then sees it), or
* handed back to the seeder after the wait so a launch that never arrived still gets its shell. If the
* seeder had already claimed it, its shell may land on top: once it settles, the held placeholder is
* brought to the front, once, while the person is still on this workspace.
*/
async function settleFirstTerminal(args: {
environmentId: string
worktreeId: string
claimed: boolean
launched: boolean
}): Promise<void> {
const { environmentId, worktreeId } = args
// Tabs the person could already be on; the seeder's late shell is never one of them.
const tabsAtLaunch = new Set(
(useAppStore.getState().tabsByWorktree[worktreeId] ?? []).map((tab) => tab.id)
)
if (args.claimed && !args.launched) {
endWebRuntimeInitialTerminalBootstrap(environmentId, worktreeId)
return
}
const heldTab = (): string | null => {
const tabs = useAppStore.getState().tabsByWorktree[worktreeId] ?? []
const record = readHeldCloudLaunches(environmentId).find(
(each) => each.worktreeId === worktreeId && tabs.some((tab) => tab.id === each.tabId)
)
return record?.tabId ?? null
}
const hasTab = (): boolean => (useAppStore.getState().tabsByWorktree[worktreeId] ?? []).length > 0
const ready = await waitForStore(
() =>
args.claimed
? hasTab()
: !isWebRuntimeInitialTerminalBootstrapInFlight(environmentId, worktreeId) &&
heldTab() !== null,
FIRST_TAB_WAIT_MS
)
if (args.claimed) {
if (ready) {
endWebRuntimeInitialTerminalBootstrap(environmentId, worktreeId)
} else {
markWebRuntimeInitialTerminalBootstrapAwaitingMirror(environmentId, worktreeId)
}
return
}
const tab = ready ? heldTab() : null
if (tab && seederShellInFront(worktreeId, tab, tabsAtLaunch)) {
useAppStore.getState().setActiveTab(tab)
}
}
/**
* Never steals focus: only the seeder's late shell (the newest tab, made after the launch began) is
* replaced in front. Another workspace, or a tab the person was already on, keeps focus.
*/
function seederShellInFront(
worktreeId: string,
heldTabId: string,
tabsAtLaunch: ReadonlySet<string>
): boolean {
const state = useAppStore.getState()
const active = state.activeTabId
const tabs = state.tabsByWorktree[worktreeId] ?? []
return (
state.activeWorktreeId === worktreeId &&
active !== null &&
active !== heldTabId &&
!tabsAtLaunch.has(active) &&
tabs.at(-1)?.id === active
)
}
function waitForStore(done: () => boolean, waitMs: number): Promise<boolean> {
if (done()) {
return Promise.resolve(true)
}
return new Promise((resolve) => {
let recheck: ReturnType<typeof setTimeout> | undefined
const finish = (value: boolean): void => {
unsubscribe()
clearTimeout(recheck)
clearTimeout(timer)
resolve(value)
}
const check = (): void => {
if (done()) {
finish(true)
return
}
// The seeder's latch is not store state: it ends just after the mirror change that came
// with its shell, so look once more shortly after the last change.
clearTimeout(recheck)
recheck = setTimeout(() => done() && finish(true), 300)
}
const unsubscribe = useAppStore.subscribe(check)
const timer = setTimeout(() => finish(done()), waitMs)
})
}
async function waitForOrcaCloudEnvironment(
environmentId: string,
deadline: number
@@ -0,0 +1,204 @@
// @vitest-environment happy-dom
// PAIRED-HELD-ACTIVE (n39): after a GitHub-only Orca Cloud create (GH-CREATE-SHEET hand-off) whose
// agent isn't set up, the held placeholder is the workspace's one tab and it is in front, so its
// "Set up once" strip is what the person sees. The mirror's initial-terminal seeder must not add a
// plain shell over it; if the seeder got there first, the held tab is brought forward once, but
// never over a tab the person chose or another workspace.
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { useAppStore } from '@/store'
import type { TuiAgent } from '../../../../shared/agent-launch/catalog/tui-agent'
import { setOrcaCloudAgentAccountsStateForTest } from './orca-cloud-agent-accounts-store'
import {
cloudTabHoldKey,
readCloudAgentHold,
releaseCloudAgentHold
} from './cloud-agent-launch-hold'
import {
beginWebRuntimeInitialTerminalBootstrap,
endWebRuntimeInitialTerminalBootstrap,
isWebRuntimeInitialTerminalBootstrapInFlight,
resetWebRuntimeInitialTerminalBootstrapForTests
} from '@/runtime/web-session-tabs-sync/initial-terminal/web-runtime-initial-terminal-bootstrap'
const host = vi.hoisted(() => {
const value: {
creates: { launchAgent?: string; environmentId: string | null; activate?: boolean }[]
} = { creates: [] }
return value
})
/** The mirror publishing a host tab (activated unless the create said not to). */
function mirrorTab(tabId: string, activate: boolean): void {
const state = useAppStore.getState()
const tabs = [...(state.tabsByWorktree['wt-1'] ?? []), { id: tabId, worktreeId: 'wt-1' }]
useAppStore.setState({
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the code under test reads only tab ids
tabsByWorktree: { ...state.tabsByWorktree, 'wt-1': tabs } as never,
...(activate && state.activeWorktreeId === 'wt-1' ? { activeTabId: tabId } : {})
})
}
vi.mock('@/components/cloud-workspaces/open-cloud-workspace', () => ({
openCloudWorkspace: async () => ({ ok: true, worktreeId: 'wt-1', hostId: 'runtime:env-paired' }),
firstWorktreeOnHost: () => 'wt-1'
}))
vi.mock('@/runtime/web-session-tabs-sync/actions/web-runtime-session-tab-lifecycle', () => ({
closeWebRuntimeSessionTab: async () => 'applied'
}))
vi.mock('@/runtime/hosted-terminals/placement/web-session-terminal-placement', () => ({
webTerminalPlacementParentTabId: (id: string) => id
}))
vi.mock('@/components/agent-tab-launch-context', () => ({
captureAgentTabLaunchContext: () => ({})
}))
// The new-tab launch on a paired web host is one host terminal create through the account hold.
vi.mock('@/lib/agent-session/launch/new-tab/launch-agent-in-new-tab', async () => {
const { createWithCloudAgentHold } = await import('./cloud-web-host-launch-hold')
return {
launchAgentInNewTabWithOutcome: (args: { agent: TuiAgent; worktreeId: string }) => {
void createWithCloudAgentHold(
{ worktreeId: args.worktreeId, environmentId: 'env-paired', launchAgent: args.agent },
async (create) => {
host.creates.push(create)
const hostTabId = `h${host.creates.length}`
mirrorTab(toWebTerminalSurfaceTabId(hostTabId), create.activate !== false)
return { outcome: { status: 'created' }, hostTabId }
}
)
}
}
})
const { startCloudWorkspaceFromGitHub } = await import('./start-cloud-workspace-from-github')
const { toWebTerminalSurfaceTabId } =
await import('../../../../shared/workspace-layout/terminal-surface-id')
beforeEach(() => {
host.creates = []
resetWebRuntimeInitialTerminalBootstrapForTests()
localStorage.clear()
setOrcaCloudAgentAccountsStateForTest({
load: {
kind: 'ready',
status: {
credentials: {
claude: { state: 'none' },
codex: { state: 'none' },
providerEnabled: { claude: true, codex: true }
},
sources: { defaults: {}, coveredByKey: { claude: false, codex: false } }
}
},
setups: { claude: { phase: 'idle' }, codex: { phase: 'idle' } },
keyKinds: { claude: null, codex: null },
queue: { agents: [], index: 0 }
})
// The fresh pairing is in the catalog without its orcaCloudPaired flag yet; main knows it.
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the checks read only id, name and source
const runtimeEnvironments = [
{ id: 'env-paired', name: 'web (cloud)', source: 'manual' }
] as unknown as ReturnType<typeof useAppStore.getState>['runtimeEnvironments']
useAppStore.setState({
pendingWorktreeCreations: {},
runtimeEnvironments,
activeWorktreeId: 'wt-1',
activeTabId: null,
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the code under test reads only tab ids
tabsByWorktree: {} as never
})
Object.assign(window, {
api: {
...window.api,
orcaCloudWorkspace: {
createFromGitHub: async () => ({ ok: true, value: { sandboxId: 'sbx_1' } })
},
cloudWorkspaces: { get: async (id: string) => ({ ok: true, value: { id } }) },
ephemeralVm: { onProvisionEvent: () => () => undefined },
orcaCloudAgents: {
isCloudEnvironment: async ({ runtimeEnvironmentId }: { runtimeEnvironmentId: string }) =>
runtimeEnvironmentId === 'env-paired'
}
}
})
})
const create = () =>
startCloudWorkspaceFromGitHub({
repoUrl: 'https://github.com/acme/web',
fullName: 'acme/web',
prompt: '',
agent: 'claude'
})
const HELD = () => toWebTerminalSurfaceTabId('h1')
const tabIds = () => (useAppStore.getState().tabsByWorktree['wt-1'] ?? []).map((tab) => tab.id)
/** The seeder's plain shell landing late, activated (what hid the strip on n39). */
function seederShellLands(): void {
mirrorTab('web-terminal-seeded-shell', true)
endWebRuntimeInitialTerminalBootstrap('env-paired', 'wt-1')
}
describe('PAIRED-HELD-ACTIVE: the held placeholder is in front after a GitHub-only create', () => {
it('exactly one tab, the held placeholder, active; the seeder is held off meanwhile', async () => {
await expect(create()).resolves.toBe(true)
// While the agent's launch is on its way, the seeder can't claim the first terminal.
expect(isWebRuntimeInitialTerminalBootstrapInFlight('env-paired', 'wt-1')).toBe(true)
await vi.waitFor(() => expect(readCloudAgentHold(cloudTabHoldKey(HELD()))).not.toBeNull())
await vi.waitFor(() =>
expect(isWebRuntimeInitialTerminalBootstrapInFlight('env-paired', 'wt-1')).toBe(false)
)
expect(tabIds()).toEqual([HELD()])
const active = useAppStore.getState().activeTabId
expect(active).toBe(HELD())
// The strip resolves for the tab in front.
expect(readCloudAgentHold(cloudTabHoldKey(active!))).toMatchObject({ reason: 'notSetUp' })
releaseCloudAgentHold(cloudTabHoldKey(HELD()), 'cancel')
})
it('the seeder got there first: once its shell lands in front, the held tab is brought forward', async () => {
beginWebRuntimeInitialTerminalBootstrap('env-paired', 'wt-1')
await create()
await vi.waitFor(() => expect(tabIds()).toEqual([HELD()]))
seederShellLands()
await vi.waitFor(() => expect(useAppStore.getState().activeTabId).toBe(HELD()))
releaseCloudAgentHold(cloudTabHoldKey(HELD()), 'cancel')
})
it('never steals focus from a tab the person is on in that workspace', async () => {
mirrorTab('web-terminal-mine', true)
beginWebRuntimeInitialTerminalBootstrap('env-paired', 'wt-1')
await create()
await vi.waitFor(() => expect(tabIds()).toContain(HELD()))
// Fake time from here: the settle's recheck after the seeder's shell runs on a timer.
vi.useFakeTimers()
try {
mirrorTab('web-terminal-seeded-shell', false)
useAppStore.setState({ activeTabId: 'web-terminal-mine' })
endWebRuntimeInitialTerminalBootstrap('env-paired', 'wt-1')
await vi.advanceTimersByTimeAsync(600)
} finally {
vi.useRealTimers()
}
expect(useAppStore.getState().activeTabId).toBe('web-terminal-mine')
releaseCloudAgentHold(cloudTabHoldKey(HELD()), 'cancel')
})
it('never steals focus from another workspace', async () => {
beginWebRuntimeInitialTerminalBootstrap('env-paired', 'wt-1')
await create()
await vi.waitFor(() => expect(tabIds()).toEqual([HELD()]))
useAppStore.setState({ activeWorktreeId: 'wt-2', activeTabId: 'web-terminal-elsewhere' })
// Fake time from here: the settle's recheck after the seeder's shell runs on a timer.
vi.useFakeTimers()
try {
seederShellLands()
await vi.advanceTimersByTimeAsync(600)
} finally {
vi.useRealTimers()
}
expect(useAppStore.getState()).toMatchObject({
activeWorktreeId: 'wt-2',
activeTabId: 'web-terminal-elsewhere'
})
releaseCloudAgentHold(cloudTabHoldKey(HELD()), 'cancel')
})
})