Merge pull request #555 from nwparker/cloud/v3-01-held-restore

fix(cloud): V3-01 a held Orca Cloud launch survives a restart
This commit is contained in:
Neil
2026-11-12 13:14:42 -08:00
committed by GitHub
19 changed files with 913 additions and 60 deletions
@@ -11,7 +11,10 @@ import {
type CloudStripActions
} from './CloudAgentSignInStrip'
import { cloudAgentStripModel } from './cloud-agent-strip-model'
import { cloudAgentSetupStripModel } from './cloud-agent-setup-strip-model'
import {
cloudAgentAwaitingStartStripModel,
cloudAgentSetupStripModel
} from './cloud-agent-setup-strip-model'
import type { OrcaCloudAgentSetup } from '../../../../shared/orca-cloud-agents/orca-cloud-agents-wire'
import { cloudRestartAttemptModel, cloudRunningStripModel } from './cloud-running-strip-model'
import type { CloudAgentRestartAttempt } from '@/lib/orca-cloud/cloud-agent-restart-attempt'
@@ -272,3 +275,59 @@ export const notSetUpBrowserCodeGapNarrow = fixture({
setUp: { setup: { phase: 'browser', startedAt: 0, canReopen: false, code: 'rejected' } },
width: 420
})
/** V3-01: restored after a restart; the account covers Claude; the first prompt waits. */
export const awaitingStartCovered = defineFixture({
width: 940,
render: () => <AwaitingPane awaiting="covered" queuedPrompt />
})
/** V3-01: restored; Orca couldn't read the sign-in after restarting. */
export const awaitingStartUnread = defineFixture({
width: 940,
render: () => <AwaitingPane awaiting="unread" queuedPrompt={false} />
})
/** V3-01: a restored expired hold, renewed: no auto-start, Start waits. */
export const awaitingStartRenewed = defineFixture({
width: 940,
render: () => <AwaitingPane awaiting="renewed" queuedPrompt />
})
export const awaitingStartUnreadNarrow = defineFixture({
width: 460,
render: () => <AwaitingPane awaiting="unread" queuedPrompt={false} width={420} />
})
function AwaitingPane({
awaiting,
queuedPrompt,
width = 900
}: {
awaiting: 'covered' | 'unread' | 'renewed'
queuedPrompt: boolean
width?: number
}): React.JSX.Element {
return (
<div className="bg-background p-4">
<div
className="pane relative h-[160px] overflow-hidden rounded-md border border-border bg-background"
style={{ width }}
>
<CloudStripLayer>
<CloudAgentSignInStrip
model={cloudAgentAwaitingStartStripModel({
agent: 'claude',
awaiting,
queuedPrompt,
t: translate
})}
prompt={queuedPrompt ? PROMPT : null}
width={cloudStripWidth(width)}
actions={ACTIONS}
/>
</CloudStripLayer>
<div className="xterm-container overflow-hidden font-mono text-xs leading-4 text-muted-foreground">
<div data-terminal-last-row>~/acme/web $</div>
</div>
</div>
</div>
)
}
@@ -222,3 +222,60 @@ export function cloudAgentSetupStripModel(args: {
}
}
}
/**
* V3-01: a launch put back after a restart that only needs the person's Start: the account covers
* the agent, Orca couldn't read it, or an expired sign-in was just renewed. Neutral, never "isn't
* set up"; Start launches it (a start that then finds no account holds as "isn't set up" again).
*/
export function cloudAgentAwaitingStartStripModel(args: {
agent: HostAgentSignInAgent
awaiting: 'covered' | 'unread' | 'renewed'
/** A first prompt waits with the launch. */
queuedPrompt: boolean
t: Translate
}): CloudStripModel {
const { t } = args
const agent = HOST_AGENT_SIGN_IN_AGENT_NAME[args.agent]
const title =
args.awaiting === 'covered'
? t('agentSignInStrip.awaitingCoveredTitle', '{{agent}} is set up', { agent })
: args.awaiting === 'renewed'
? t('agentSignInStrip.renewed', '{{agent}} sign-in renewed', { agent })
: t('agentSignInStrip.awaitingUnreadTitle', '{{agent}} hasn’t started', { agent })
const detail =
args.awaiting === 'unread'
? t(
'agentSignInStrip.awaitingUnreadDetail',
'Orca couldn’t check your sign-in after restarting. Start {{agent}} to try.',
{ agent }
)
: args.awaiting === 'covered'
? args.queuedPrompt
? t(
'agentSignInStrip.awaitingCoveredPromptDetail',
'Orca restarted before {{agent}} started. Your first prompt is kept.',
{ agent }
)
: t(
'agentSignInStrip.awaitingCoveredDetail',
'Orca restarted before {{agent}} started.',
{ agent }
)
: ''
return {
status: 'setup',
title,
detail,
description: null,
code: null,
paste: null,
otherWays: false,
primary: {
label: t('agentSignInStrip.startAgent', 'Start {{agent}}', { agent }),
narrowLabel: t('agentSignInStrip.start', 'Start'),
action: { kind: 'start' }
},
announcement: detail ? `${title}. ${detail}` : title
}
}
@@ -255,6 +255,9 @@ describe('the chat composer while a cloud launch is held', () => {
expect(cloudChatHoldHint({ agent: 'claude', reason: 'notSetUp' }, null, t)).toBe(
'Set up Claude above to start'
)
expect(cloudChatHoldHint({ agent: 'claude', reason: 'awaitingStart' }, null, t)).toBe(
'Start Claude above to begin'
)
expect(cloudChatHoldHint({ agent: 'claude', reason: 'accountExpired' }, null, t)).toBe(
'Renew Claude sign-in above to start'
)
@@ -22,7 +22,9 @@ export function cloudChatHoldHint(
const agent = agentName(hold.agent, t)
return hold.reason === 'notSetUp'
? t('orcaCloud.chatHold.notSetUp', 'Set up {{agent}} above to start', { agent })
: t('orcaCloud.chatHold.expired', 'Renew {{agent}} sign-in above to start', { agent })
: hold.reason === 'awaitingStart'
? t('orcaCloud.chatHold.awaitingStart', 'Start {{agent}} above to begin', { agent })
: t('orcaCloud.chatHold.expired', 'Renew {{agent}} sign-in above to start', { agent })
}
if (gate && isOrcaCloudEnvironmentId(gate.environmentId)) {
return t('orcaCloud.chatHold.signIn', 'Sign in to {{agent}} above to start', {
@@ -16,7 +16,10 @@ import { useOrcaCloudAgentAccounts } from '@/lib/orca-cloud/orca-cloud-agent-acc
import { agentSignInCardActions } from '../agent-sign-in/AgentSignInPanePortals'
import type { CloudStripActions } from './CloudAgentSignInStrip'
import { cloudAgentStripModel, type CloudStripModel } from './cloud-agent-strip-model'
import { cloudAgentSetupStripModel } from './cloud-agent-setup-strip-model'
import {
cloudAgentAwaitingStartStripModel,
cloudAgentSetupStripModel
} from './cloud-agent-setup-strip-model'
import { cloudSetupStripActions } from './cloud-setup-strip-actions'
export type CloudHeldStrip = {
@@ -60,22 +63,31 @@ export function useCloudHeldStrip(
: 'paused'
const gateActions = agentSignInCardActions(paneKey)
// PC-3b: a launch held because the agent isn't set up runs the one-time setup in the pane.
const setupHold = hold?.reason === 'notSetUp'
const awaiting = hold?.reason === 'awaitingStart' ? (hold.awaiting ?? 'unread') : null
// V3-01: a restored hold waiting for Start shares the setup hold's actions (Start, cancel).
const setupHold = hold?.reason === 'notSetUp' || awaiting !== null
const setup = accounts.setups[agent]
const model = setupHold
? cloudAgentSetupStripModel({
const model = awaiting
? cloudAgentAwaitingStartStripModel({
agent,
setup,
ready: accounts.load.kind === 'ready' && cloudAgentHoldReason(agent, accounts) === null,
t
})
: cloudAgentStripModel({
agent,
reason,
view: hold ? null : (cloudGate?.view ?? null),
hostLabel: cloudGate?.hostLabel ?? t('agentSignInStrip.sandbox', 'the sandbox'),
awaiting,
queuedPrompt: Boolean(hold?.prompt),
t
})
: setupHold
? cloudAgentSetupStripModel({
agent,
setup,
ready: accounts.load.kind === 'ready' && cloudAgentHoldReason(agent, accounts) === null,
t
})
: cloudAgentStripModel({
agent,
reason,
view: hold ? null : (cloudGate?.view ?? null),
hostLabel: cloudGate?.hostLabel ?? t('agentSignInStrip.sandbox', 'the sandbox'),
t
})
const holdActions: CloudStripActions | null = setupHold
? cloudSetupStripActions({
agent,
@@ -6,13 +6,13 @@ import { setOrcaCloudAgentAccountsStateForTest } from '@/lib/orca-cloud/orca-clo
import { CloudAgentHeldMark } from './CloudAgentHeldMark'
// A cloud workspace row whose Claude waits on its pane's "Set up once" strip (N-03).
function seed(): void {
function seed(restored = false): void {
setOrcaCloudAgentAccountsStateForTest({
load: {
kind: 'ready',
status: {
credentials: {
claude: { state: 'none' },
claude: { state: restored ? 'active' : 'none' },
codex: { state: 'none' },
providerEnabled: { claude: true, codex: true }
},
@@ -29,6 +29,7 @@ function seed(): void {
})
void holdCloudAgentLaunch({
decided: true,
restored,
paneKey: 'tab:web-terminal-g',
agent: 'claude',
prompt: null
@@ -45,21 +46,29 @@ function Row(): React.JSX.Element {
)
}
export const sidebarRowMark = defineFixture({
width: 340,
render: () => {
seed()
return (
<div className="h-[110px] p-3">
<Row />
</div>
)
},
interact: async (frame: HTMLElement) => {
await new Promise((resolve) => setTimeout(resolve, 50))
const mark = frame.querySelector<HTMLElement>('[data-cloud-agent-held]')
mark?.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }))
mark?.dispatchEvent(new PointerEvent('pointerenter', { bubbles: true }))
await new Promise((resolve) => setTimeout(resolve, 900))
}
})
const markFixture = (restored: boolean) =>
defineFixture({
width: 340,
render: () => {
seed(restored)
return (
<div className="h-[110px] p-3">
<Row />
</div>
)
},
interact: async (frame: HTMLElement) => {
await new Promise((resolve) => setTimeout(resolve, 50))
const mark = frame.querySelector<HTMLElement>('[data-cloud-agent-held]')
mark?.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }))
mark?.dispatchEvent(new PointerEvent('pointerenter', { bubbles: true }))
await new Promise((resolve) => setTimeout(resolve, 900))
}
})
export const sidebarRowMark = markFixture(false)
/**
* V3-01: a launch put back after a restart that only waits for Start: the muted play mark, never
* the amber key (the account here is covered: no "not set up").
*/
export const sidebarRowMarkNotStarted = markFixture(true)
@@ -1,5 +1,6 @@
import React from 'react'
import { KeyRound } from 'lucide-react'
import { CirclePlay, KeyRound } from 'lucide-react'
import { cn } from '@/lib/class-names'
import { useAppStore } from '@/store'
import { useTranslate } from '@/i18n/use-translate'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
@@ -39,10 +40,19 @@ export function CloudAgentHeldMark({
return null
}
const agent = agentName(hold.agent, t)
const label =
hold.reason === 'accountExpired'
const waiting = hold.reason === 'awaitingStart'
const label = waiting
? t(
'orcaCloud.agentHold.notStarted',
'{{agent}} hasn’t started. Open the workspace to start it.',
{
agent
}
)
: hold.reason === 'accountExpired'
? t('orcaCloud.agentHold.expired', '{{agent}} sign-in expired', { agent })
: t('orcaCloud.agentHold.notSetUp', '{{agent}} isn’t set up for Orca Cloud', { agent })
const Icon = waiting ? CirclePlay : KeyRound
return (
<Tooltip>
<TooltipTrigger asChild>
@@ -50,9 +60,13 @@ export function CloudAgentHeldMark({
role="img"
aria-label={label}
data-cloud-agent-held={hold.reason}
className="inline-flex size-3.5 shrink-0 items-center justify-center text-status-warning-text"
className={cn(
'inline-flex size-3.5 shrink-0 items-center justify-center',
// V3-01: a restored launch waiting for Start is no alarm: muted, not the amber key.
waiting ? 'text-muted-foreground' : 'text-status-warning-text'
)}
>
<KeyRound className="size-3" aria-hidden />
<Icon className="size-3" aria-hidden />
</span>
</TooltipTrigger>
<TooltipContent side="right" sideOffset={6}>
@@ -147,6 +147,11 @@ export const runningSignInExpired = card({
id: 'card-expired',
attention: { kind: 'agentExpired', agent: 'Claude', tabId: 'tab-1' }
})
/** V3-01: a launch put back after a restart that waits for Start: neutral, below the warnings. */
export const runningNotStarted = card({
id: 'card-not-started',
attention: { kind: 'agentNotStarted', agent: 'Claude', tabId: 'tab-1' }
})
/** Details open: the bars, uptime and sandbox hours. */
export const detailsOpen = card({ id: 'card-details', details: true })
/** The sub-panel with the mirror off: the two switches and the .context status. */
@@ -43,6 +43,7 @@ import { CloudWorkspaceCardMenu } from './CloudWorkspaceCardMenu'
import { useCloudOfflineData } from './offline/use-cloud-offline-data'
import {
cloudCardAttentionLabel,
cloudCardAttentionTone,
cloudCardOnComputerStatus,
cloudCardPrimary,
cloudCardStateDetail,
@@ -300,11 +301,11 @@ export function CloudWorkspaceStatusPanel({
{attention ? (
<button
type="button"
className={cn(ROW, 'font-medium text-status-warning-text')}
className={cn(ROW, 'font-medium', cloudCardAttentionTone(attention).text)}
onClick={() => openCloudCardAttention(workspaceId, attention)}
data-cloud-card-attention={attention.kind}
>
<span className="size-1.5 shrink-0 rounded-full bg-status-warning" aria-hidden />
<span className={cloudCardAttentionTone(attention).dot} aria-hidden />
<span className="min-w-0 flex-1 truncate">{cloudCardAttentionLabel(attention, t)}</span>
<ChevronRight aria-hidden className="size-3.5 shrink-0" />
</button>
@@ -7,6 +7,7 @@ import {
cloudCardStateDetail,
cloudCardUsageLine,
cloudCardAttentionLabel,
cloudCardAttentionTone,
mostUrgentAttention,
pickWorkspaceAgentSignIn,
signInAttention
@@ -120,3 +121,22 @@ describe('card attention for a running agent’s lapsed sign-in (n15)', () => {
expect(row([])).toBeNull()
})
})
describe('a launch put back after a restart that waits for Start (V3-01)', () => {
const notStarted = { kind: 'agentNotStarted' as const, agent: 'Claude', tabId: 't' }
it('reads "hasn’t started" in neutral colours, never "isn’t set up" or a warning', () => {
expect(cloudCardAttentionLabel(notStarted, t)).toBe('Claude hasn’t started')
expect(cloudCardAttentionTone(notStarted).text).toBe('text-foreground')
expect(cloudCardAttentionTone(notStarted).dot).toContain('bg-muted-foreground')
expect(
cloudCardAttentionTone({ kind: 'agentNotSetUp', agent: 'Claude', tabId: 't' }).text
).toBe('text-status-warning-text')
})
it('ranks below an agent that can’t start, above commits and pushes being off', () => {
const expired = { kind: 'agentExpired' as const, agent: 'Claude', tabId: 't' }
expect(mostUrgentAttention([notStarted, expired])).toBe(expired)
expect(mostUrgentAttention([{ kind: 'gitSetupOff' }, notStarted])).toBe(notStarted)
})
})
@@ -63,6 +63,8 @@ export function cloudCardUsageLine(
export type CloudCardAttention =
| { kind: 'agentNotSetUp'; agent: string; tabId: string }
| { kind: 'agentExpired'; agent: string; tabId: string }
/** V3-01: a launch put back after a restart that waits for the person's Start (neutral). */
| { kind: 'agentNotStarted'; agent: string; tabId: string }
/** GIT-SETUP: the teammates' git identities couldn't be installed; commits and pushes are off. */
| { kind: 'gitSetupOff' }
| { kind: 'secretsMissing'; count: number }
@@ -71,6 +73,8 @@ const URGENCY: Record<CloudCardAttention['kind'], number> = {
// An agent that can't start blocks the work the workspace was made for.
agentNotSetUp: 0,
agentExpired: 1,
// Below an agent that can't start, above commits and pushes being off (design-squad).
agentNotStarted: 1.5,
// Below an agent that can't start, above missing secrets (design-squad).
gitSetupOff: 2,
secretsMissing: 3
@@ -89,6 +93,13 @@ export function mostUrgentAttention(
return best
}
/** The row's colours: a launch waiting for Start (V3-01) is neutral info, everything else a warning. */
export function cloudCardAttentionTone(item: CloudCardAttention): { text: string; dot: string } {
return item.kind === 'agentNotStarted'
? { text: 'text-foreground', dot: 'size-1.5 shrink-0 rounded-full bg-muted-foreground' }
: { text: 'text-status-warning-text', dot: 'size-1.5 shrink-0 rounded-full bg-status-warning' }
}
export function cloudCardAttentionLabel(item: CloudCardAttention, t: Translate): string {
switch (item.kind) {
case 'agentNotSetUp':
@@ -97,6 +108,10 @@ export function cloudCardAttentionLabel(item: CloudCardAttention, t: Translate):
})
case 'agentExpired':
return t('orcaCloud.agentHold.expired', '{{agent}} sign-in expired', { agent: item.agent })
case 'agentNotStarted':
return t('orcaCloud.agentHold.notStartedRow', '{{agent}} hasn’t started', {
agent: item.agent
})
case 'gitSetupOff':
return t('orcaCloudWorkspace.card.gitSetupOff', 'Commits and pushes are off')
case 'secretsMissing':
@@ -50,7 +50,12 @@ export function useCloudCardAttention(workspaceId: string): CloudCardAttention |
return mostUrgentAttention([
hold
? {
kind: hold.reason === 'accountExpired' ? 'agentExpired' : 'agentNotSetUp',
kind:
hold.reason === 'accountExpired'
? 'agentExpired'
: hold.reason === 'awaitingStart'
? 'agentNotStarted'
: 'agentNotSetUp',
agent: agentName(hold.agent, t),
tabId: cloudAgentHoldTabId(hold.paneKey)
}
@@ -72,6 +77,7 @@ export function openCloudCardAttention(workspaceId: string, item: CloudCardAtten
switch (item.kind) {
case 'agentNotSetUp':
case 'agentExpired':
case 'agentNotStarted':
activateAndRevealWorktree(workspaceId)
useAppStore.getState().setActiveTab(item.tabId)
return
+10 -2
View File
@@ -28238,7 +28238,9 @@
"orcaCloud": {
"agentHold": {
"notSetUp": "{{agent}} isn’t set up for Orca Cloud",
"expired": "{{agent}} sign-in expired"
"expired": "{{agent}} sign-in expired",
"notStarted": "{{agent}} hasn’t started. Open the workspace to start it.",
"notStartedRow": "{{agent}} hasn’t started"
},
"chatSignIn": {
"renewAbove": "Your {{agent}} sign-in for Orca Cloud didn’t work. Renew it above, then send your message again."
@@ -28246,7 +28248,8 @@
"chatHold": {
"notSetUp": "Set up {{agent}} above to start",
"expired": "Renew {{agent}} sign-in above to start",
"signIn": "Sign in to {{agent}} above to start"
"signIn": "Sign in to {{agent}} above to start",
"awaitingStart": "Start {{agent}} above to begin"
},
"continueOffer": {
"title": "An agent was interrupted by the restart",
@@ -28890,6 +28893,11 @@
"renewed": "{{agent}} sign-in renewed",
"renewedResume": "Restart {{agent}} to pick up where you left off.",
"renewedFresh": "Starts a new conversation.",
"awaitingCoveredTitle": "{{agent}} is set up",
"awaitingUnreadTitle": "{{agent}} hasn’t started",
"awaitingUnreadDetail": "Orca couldn’t check your sign-in after restarting. Start {{agent}} to try.",
"awaitingCoveredPromptDetail": "Orca restarted before {{agent}} started. Your first prompt is kept.",
"awaitingCoveredDetail": "Orca restarted before {{agent}} started.",
"renewedChat": "Your next message uses it.",
"renewedChatAnnounce": "{{agent}} sign-in renewed. Your next message uses it.",
"restart": "Restart",
@@ -39,7 +39,14 @@ export function cloudAgentStripReason(
}
/** Why a launch is held: account recovery, or the one-time setup (PC-3b). */
export type CloudAgentHoldReason = 'accountExpired' | 'notSetUp'
export type CloudAgentHoldReason =
| 'accountExpired'
| 'notSetUp'
/**
* V3-01: a hold put back after a restart whose account now covers the agent (or whose read
* failed): it waits for the person's Start. Never labelled "not set up" or "expired".
*/
| 'awaitingStart'
/** The hold a launch needs from this accounts read; null starts it. */
export function cloudAgentHoldReason(
@@ -80,6 +87,11 @@ export type CloudAgentHold = {
agent: HostAgentSignInAgent
prompt: string | null
reason: CloudAgentHoldReason
/**
* Why an 'awaitingStart' hold waits: the account covers the agent now, Orca couldn't read it,
* or an expired sign-in was renewed (V3-01). Absent for every other reason.
*/
awaiting?: 'covered' | 'unread' | 'renewed'
}
/** The hold key of a host-published tab (RA-1): its first pane shows the strip. */
@@ -87,9 +99,15 @@ export function cloudTabHoldKey(tabId: string): string {
return `tab:${tabId}`
}
type HoldRequest = Omit<CloudAgentHold, 'reason'> & {
type HoldRequest = Omit<CloudAgentHold, 'reason' | 'awaiting'> & {
/** The caller already read the account and decided to hold; skip the re-read. */
decided?: boolean
/**
* V3-01: a hold put back after a restart always waits for the person's explicit Start: a covered
* account (or a failed read) holds as 'awaitingStart', and an expired one that is then renewed
* turns 'awaitingStart' instead of starting. In-session holds keep their behaviour.
*/
restored?: boolean
}
type Entry = CloudAgentHold & { release: (outcome: 'proceed' | 'cancel') => void }
@@ -101,11 +119,12 @@ const listeners = new Set<() => void>()
let holdsSnapshot: readonly CloudAgentHold[] = []
function notify(): void {
holdsSnapshot = [...holds.values()].map(({ paneKey, agent, prompt, reason }) => ({
holdsSnapshot = [...holds.values()].map(({ paneKey, agent, prompt, reason, awaiting }) => ({
paneKey,
agent,
prompt,
reason
reason,
...(awaiting ? { awaiting } : {})
}))
for (const listener of listeners) {
listener()
@@ -215,25 +234,53 @@ async function holdReasonBeforeLaunch(
*/
export async function holdCloudAgentLaunch({
decided,
restored,
...hold
}: HoldRequest): Promise<'proceed' | 'cancel'> {
// The caller's read decided to hold; if it no longer does, start rather than wait on a strip.
const reason = decided
const read = decided
? cloudAgentHoldReason(hold.agent, readOrcaCloudAgentAccounts())
: await holdReasonBeforeLaunch(hold.agent)
const reason = read ?? (restored ? 'awaitingStart' : null)
if (!reason) {
return 'proceed'
}
const accountsRead = readOrcaCloudAgentAccounts().load.kind === 'ready'
const awaiting =
reason === 'awaitingStart' ? (accountsRead ? ('covered' as const) : ('unread' as const)) : null
return new Promise((resolve) => {
const stop = subscribeOrcaCloudAgentAccounts(() => {
// Renewed (or a key now covers it): every pane held on recovery starts. A first-time setup
// waits for its "Start {{agent}}" click instead (PC-3b), so it never starts unasked.
if (
reason === 'accountExpired' &&
cloudAgentStripReason(hold.agent, readOrcaCloudAgentAccounts()) !== 'accountExpired'
) {
finish('proceed')
const entry = holds.get(hold.paneKey)
if (entry?.release !== finish || entry.reason !== 'accountExpired') {
return
}
const accounts = readOrcaCloudAgentAccounts()
const now = accounts.load.kind === 'ready' ? cloudAgentHoldReason(hold.agent, accounts) : null
if (accounts.load.kind !== 'ready' || now === 'accountExpired') {
return
}
if (now === 'notSetUp') {
// The sign-in was removed, not renewed: nothing covers the agent, so it never starts here;
// the hold becomes the one-time setup.
holds.set(hold.paneKey, { ...entry, reason: 'notSetUp' })
notify()
return
}
// Only a real renewal (the account or a key covers it) starts it; a paused or withdrawn agent
// (kill switch, never offered) or an unknown coverage stays held.
const coverage = orcaCloudAgentCoverageFromAccounts(hold.agent, accounts)?.kind
if (coverage !== 'account' && coverage !== 'key') {
return
}
if (restored) {
// After a restart the person starts it: renewed, it waits for Start (V3-01).
holds.set(hold.paneKey, { ...entry, reason: 'awaitingStart', awaiting: 'renewed' })
notify()
return
}
finish('proceed')
})
function finish(outcome: 'proceed' | 'cancel'): void {
if (holds.get(hold.paneKey)?.release !== finish) {
@@ -244,7 +291,7 @@ export async function holdCloudAgentLaunch({
notify()
resolve(outcome)
}
holds.set(hold.paneKey, { ...hold, reason, release: finish })
holds.set(hold.paneKey, { ...hold, reason, ...(awaiting ? { awaiting } : {}), release: finish })
notify()
})
}
@@ -0,0 +1,103 @@
// V3-01: a held Orca Cloud launch waits in a plain-shell placeholder tab on the host, and the hold
// itself lives only in memory (cloud-agent-launch-hold). A quit loses it: the placeholder comes back
// as a plain shell with no strip and no way to start the agent. This keeps one record per held
// placeholder so a restart can put the hold back. Per Orca profile, on this device; never the
// launch's env, command or secrets, only what re-planning the launch needs.
import { useAppStore } from '@/store'
export type HeldCloudLaunchRecord = {
environmentId: string
worktreeId: string
/** The placeholder's surface tab id (derived from the host tab id, which the host keeps). */
tabId: string
agent: 'claude' | 'codex'
prompt: string | null
cwd: string | null
targetGroupId: string | null
createdAt: number
}
const KEY_PREFIX = 'orca.cloudHeldLaunches.v1'
/** Bounded so a long-lived profile can't grow the record without limit. */
const MAX_RECORDS = 50
/**
* A record left by a workspace or sandbox deleted while the app was closed never meets its tab
* again; it ages out (a restored one is also dropped once its tab doesn't come back).
*/
export const HELD_LAUNCH_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
function storage(): Storage | undefined {
return typeof localStorage === 'undefined' ? undefined : localStorage
}
function storageKey(profileId: string | null): string {
return `${KEY_PREFIX}:${profileId ?? 'default'}`
}
function activeProfileId(): string | null {
return useAppStore.getState().activeOrcaProfileId ?? null
}
function isRecord(value: unknown): value is HeldCloudLaunchRecord {
if (typeof value !== 'object' || value === null) {
return false
}
const record: Partial<Record<keyof HeldCloudLaunchRecord, unknown>> = value
return (
typeof record.environmentId === 'string' &&
typeof record.worktreeId === 'string' &&
typeof record.tabId === 'string' &&
(record.agent === 'claude' || record.agent === 'codex') &&
(record.prompt === null || typeof record.prompt === 'string') &&
(record.cwd === null || typeof record.cwd === 'string') &&
(record.targetGroupId === null || typeof record.targetGroupId === 'string') &&
typeof record.createdAt === 'number'
)
}
function readAll(profileId: string | null): HeldCloudLaunchRecord[] {
try {
const raw = storage()?.getItem(storageKey(profileId))
const parsed: unknown = raw ? JSON.parse(raw) : []
const now = Date.now()
return Array.isArray(parsed)
? parsed.filter(isRecord).filter((each) => now - each.createdAt < HELD_LAUNCH_MAX_AGE_MS)
: []
} catch {
return []
}
}
function writeAll(profileId: string | null, records: HeldCloudLaunchRecord[]): void {
try {
const kept = records.slice(-MAX_RECORDS)
if (kept.length === 0) {
storage()?.removeItem(storageKey(profileId))
} else {
storage()?.setItem(storageKey(profileId), JSON.stringify(kept))
}
} catch {
// Storage full or unavailable: the hold still works for this run, it just won't survive a quit.
}
}
/** Remember a held placeholder (replacing any record for the same tab). */
export function rememberHeldCloudLaunch(record: HeldCloudLaunchRecord): void {
const profileId = activeProfileId()
writeAll(profileId, [...readAll(profileId).filter((each) => each.tabId !== record.tabId), record])
}
/** Forget a placeholder's record: its hold settled (Start, cancel) or its tab is gone. */
export function forgetHeldCloudLaunch(tabId: string): void {
const profileId = activeProfileId()
const records = readAll(profileId)
const kept = records.filter((each) => each.tabId !== tabId)
if (kept.length !== records.length) {
writeAll(profileId, kept)
}
}
/** The records for one Orca Cloud environment, for the active profile. */
export function readHeldCloudLaunches(environmentId: string): HeldCloudLaunchRecord[] {
return readAll(activeProfileId()).filter((each) => each.environmentId === environmentId)
}
@@ -0,0 +1,341 @@
// @vitest-environment happy-dom
// V3-01: a held Orca Cloud launch survives a quit. Its placeholder is remembered (per profile), and
// on the next start the hold is put back once the placeholder tab returns: the strip's key and the
// original prompt come back, Start launches it, Cancel forgets it, and nothing launches unasked.
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { useAppStore } from '@/store'
import type { CreateWebRuntimeSessionTerminalOnHostArgs } from '@/runtime/hosted-terminals/creation/terminal-create-contracts'
const mocks = vi.hoisted(() => {
const state: {
coverage: 'notSetUp' | 'covered' | 'expired' | 'killSwitch'
/** 'loading' with a failing read: Orca couldn't check the sign-in. */
load: 'ready' | 'loading'
closed: string[]
listeners: Set<() => void>
} = {
coverage: 'notSetUp',
load: 'ready',
closed: [],
listeners: new Set()
}
return state
})
vi.mock('./orca-cloud-environment-id', () => ({
isOrcaCloudEnvironmentId: () => true,
isOrcaCloudExecutionHostId: () => true
}))
vi.mock('./orca-cloud-agent-accounts-store', () => ({
readOrcaCloudAgentAccounts: () => ({ load: { kind: mocks.load }, keyKinds: {} }),
ensureFreshOrcaCloudAgentAccounts: async () => {
if (mocks.load === 'loading') {
throw new Error('read failed')
}
return { load: { kind: 'ready' }, keyKinds: {} }
},
isOrcaCloudAgentAccountsFresh: () => true,
subscribeOrcaCloudAgentAccounts: (listener: () => void) => {
mocks.listeners.add(listener)
return () => mocks.listeners.delete(listener)
}
}))
vi.mock('./orca-cloud-agent-accounts-model', async (importOriginal) => ({
...(await importOriginal<object>()),
orcaCloudAgentCoverageFromAccounts: () => ({
kind:
mocks.coverage === 'covered'
? 'account'
: mocks.coverage === 'expired' || mocks.coverage === 'killSwitch'
? mocks.coverage
: 'notSetUp'
})
}))
vi.mock('@/runtime/web-session-tabs-sync/actions/web-runtime-session-tab-lifecycle', () => ({
closeWebRuntimeSessionTab: async (args: { tabId: string }) => {
mocks.closed.push(args.tabId)
}
}))
vi.mock('@/runtime/hosted-terminals/creation/web-runtime-terminal-create-operation', () => ({
createWebRuntimeSessionTerminalResult: vi.fn()
}))
const { cloudTabHoldKey, readCloudAgentHold, releaseCloudAgentHold } =
await import('./cloud-agent-launch-hold')
const { createWithCloudAgentHold } = await import('./cloud-web-host-launch-hold')
const { readHeldCloudLaunches, rememberHeldCloudLaunch } =
await import('./cloud-held-launch-memory')
const { resumeHeldCloudLaunches, resetHeldCloudLaunchResumeForTest } =
await import('./cloud-held-launch-resume')
const ENV = 'env-cloud'
const WT = 'repo::/ws'
const HOST_TAB = 'host-tab-1'
const TAB = 'web-terminal-host-tab-1'
function setTabs(ids: string[]): void {
useAppStore.setState({
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the hold reads only tab ids.
tabsByWorktree: { [WT]: ids.map((id) => ({ id })) } as never
})
}
const created = (hostTabId: string) => ({
outcome: { status: 'created' as const },
hostTabId
})
const flush = () => new Promise((resolve) => setTimeout(resolve, 0))
beforeEach(() => {
localStorage.clear()
mocks.coverage = 'notSetUp'
mocks.closed = []
mocks.load = 'ready'
mocks.listeners.clear()
resetHeldCloudLaunchResumeForTest()
useAppStore.setState({ activeOrcaProfileId: 'profile-a' })
setTabs([])
})
afterEach(() => {
for (const key of [cloudTabHoldKey(TAB)]) {
if (readCloudAgentHold(key)) {
releaseCloudAgentHold(key, 'cancel')
}
}
vi.useRealTimers()
})
describe('a held launch is remembered', () => {
it('records the placeholder with agent and prompt, and forgets it once Start launches it', async () => {
const create = vi.fn(async (args: CreateWebRuntimeSessionTerminalOnHostArgs) =>
args.agent || args.launchAgent ? created('host-agent') : created(HOST_TAB)
)
setTabs([TAB])
const launch = createWithCloudAgentHold(
{ worktreeId: WT, environmentId: ENV, agent: 'claude', prompt: 'fix the test' },
create
)
await flush()
expect(readHeldCloudLaunches(ENV)).toMatchObject([
{ tabId: TAB, agent: 'claude', prompt: 'fix the test', worktreeId: WT }
])
releaseCloudAgentHold(cloudTabHoldKey(TAB), 'proceed')
await launch
expect(readHeldCloudLaunches(ENV)).toEqual([])
})
it('is per profile: another profile never reads it', () => {
rememberHeldCloudLaunch({
environmentId: ENV,
worktreeId: WT,
tabId: TAB,
agent: 'claude',
prompt: null,
cwd: null,
targetGroupId: null,
createdAt: Date.now()
})
useAppStore.setState({ activeOrcaProfileId: 'profile-b' })
expect(readHeldCloudLaunches(ENV)).toEqual([])
useAppStore.setState({ activeOrcaProfileId: 'profile-a' })
expect(readHeldCloudLaunches(ENV)).toHaveLength(1)
})
})
describe('after a restart', () => {
const remember = () =>
rememberHeldCloudLaunch({
environmentId: ENV,
worktreeId: WT,
tabId: TAB,
agent: 'claude',
prompt: 'fix the test',
cwd: '/ws',
targetGroupId: null,
createdAt: Date.now()
})
it('puts the hold back once the placeholder returns; Start launches the original prompt', async () => {
remember()
const create = vi.fn(async () => created('host-agent'))
resumeHeldCloudLaunches(ENV, { create, waitMs: 5_000 })
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))).toBeNull()
setTabs([TAB])
await flush()
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))).toMatchObject({
agent: 'claude',
reason: 'notSetUp',
prompt: 'fix the test'
})
expect(create).not.toHaveBeenCalled()
releaseCloudAgentHold(cloudTabHoldKey(TAB), 'proceed')
await flush()
await flush()
expect(create).toHaveBeenCalledWith(
expect.objectContaining({ agent: 'claude', prompt: 'fix the test', worktreeId: WT })
)
expect(mocks.closed).toEqual([TAB])
expect(readHeldCloudLaunches(ENV)).toEqual([])
})
it('an account that is covered now waits for Start, as awaitingStart (never "not set up")', async () => {
mocks.coverage = 'covered'
remember()
setTabs([TAB])
const create = vi.fn(async () => created('host-agent'))
resumeHeldCloudLaunches(ENV, { create, waitMs: 5_000 })
await flush()
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))).toMatchObject({
reason: 'awaitingStart',
awaiting: 'covered'
})
expect(create).not.toHaveBeenCalled()
})
it('a sign-in read that fails after restart waits as unread, never "not set up"', async () => {
mocks.load = 'loading'
remember()
setTabs([TAB])
const create = vi.fn(async () => created('host-agent'))
resumeHeldCloudLaunches(ENV, { create, waitMs: 5_000 })
await flush()
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))).toMatchObject({
reason: 'awaitingStart',
awaiting: 'unread'
})
expect(create).not.toHaveBeenCalled()
})
it('restored and expired: a Renew turns it awaitingStart and starts nothing', async () => {
mocks.coverage = 'expired'
remember()
setTabs([TAB])
const create = vi.fn(async () => created('host-agent'))
resumeHeldCloudLaunches(ENV, { create, waitMs: 5_000 })
await flush()
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))?.reason).toBe('accountExpired')
mocks.coverage = 'covered'
for (const listener of mocks.listeners) {
listener()
}
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))).toMatchObject({
reason: 'awaitingStart',
awaiting: 'renewed'
})
expect(create).not.toHaveBeenCalled()
})
it('Cancel forgets the record and launches nothing', async () => {
remember()
setTabs([TAB])
const create = vi.fn(async () => created('host-agent'))
resumeHeldCloudLaunches(ENV, { create, waitMs: 5_000 })
await flush()
await flush()
releaseCloudAgentHold(cloudTabHoldKey(TAB), 'cancel')
await flush()
expect(create).not.toHaveBeenCalled()
expect(readHeldCloudLaunches(ENV)).toEqual([])
})
it('a placeholder that never comes back is dropped after the bounded wait', async () => {
vi.useFakeTimers()
remember()
const info = vi.spyOn(console, 'info').mockImplementation(() => undefined)
resumeHeldCloudLaunches(ENV, { create: vi.fn(), waitMs: 1_000 })
await vi.advanceTimersByTimeAsync(1_000)
expect(readHeldCloudLaunches(ENV)).toEqual([])
expect(info).toHaveBeenCalledWith(expect.stringContaining('held launch dropped'))
info.mockRestore()
})
it('waits for the profile before reading the records', async () => {
remember()
setTabs([TAB])
useAppStore.setState({ activeOrcaProfileId: null })
const create = vi.fn(async () => created('host-agent'))
resumeHeldCloudLaunches(ENV, { create, waitMs: 5_000 })
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))).toBeNull()
useAppStore.setState({ activeOrcaProfileId: 'profile-a' })
await flush()
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))).not.toBeNull()
})
})
describe('in session (not restored)', () => {
it('in-session (not restored), an expired hold still starts on Renew as before', async () => {
mocks.coverage = 'expired'
setTabs([TAB])
const create = vi.fn(async (args: CreateWebRuntimeSessionTerminalOnHostArgs) =>
args.agent ? created('host-agent') : created(HOST_TAB)
)
const launch = createWithCloudAgentHold(
{ worktreeId: WT, environmentId: ENV, agent: 'claude', prompt: 'p' },
create
)
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))?.reason).toBe('accountExpired')
mocks.coverage = 'covered'
for (const listener of mocks.listeners) {
listener()
}
await launch
expect(create).toHaveBeenLastCalledWith(expect.objectContaining({ agent: 'claude' }))
})
it('an expired hold whose sign-in is removed (not renewed) never starts: it becomes the setup', async () => {
mocks.coverage = 'expired'
setTabs([TAB])
const create = vi.fn(async (args: CreateWebRuntimeSessionTerminalOnHostArgs) =>
args.agent ? created('host-agent') : created(HOST_TAB)
)
void createWithCloudAgentHold(
{ worktreeId: WT, environmentId: ENV, agent: 'claude', prompt: 'p' },
create
)
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))?.reason).toBe('accountExpired')
mocks.coverage = 'notSetUp'
for (const listener of mocks.listeners) {
listener()
}
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))?.reason).toBe('notSetUp')
expect(create).toHaveBeenCalledTimes(1)
})
it('a paused (kill switch) agent never starts the expired hold; a real renewal does', async () => {
mocks.coverage = 'expired'
setTabs([TAB])
const create = vi.fn(async (args: CreateWebRuntimeSessionTerminalOnHostArgs) =>
args.agent ? created('host-agent') : created(HOST_TAB)
)
const launch = createWithCloudAgentHold(
{ worktreeId: WT, environmentId: ENV, agent: 'claude', prompt: 'p' },
create
)
await flush()
mocks.coverage = 'killSwitch'
for (const listener of mocks.listeners) {
listener()
}
await flush()
expect(readCloudAgentHold(cloudTabHoldKey(TAB))?.reason).toBe('accountExpired')
expect(create).toHaveBeenCalledTimes(1)
mocks.coverage = 'covered'
for (const listener of mocks.listeners) {
listener()
}
await launch
expect(create).toHaveBeenLastCalledWith(expect.objectContaining({ agent: 'claude' }))
})
})
@@ -0,0 +1,111 @@
// V3-01: after a restart, put back the holds the quit dropped. Each remembered placeholder tab comes
// back from the host as a plain shell; once it is in the store again, its hold is re-placed under the
// same key, so the strip and the sidebar's key mark return and Start launches the original agent and
// prompt. A record whose tab doesn't come back within a bounded wait is dropped (a workspace or
// sandbox deleted meanwhile ends that way, or ages out). A restored hold always waits for the
// person's explicit Start, even once its account covers the agent or is renewed.
import { useAppStore } from '@/store'
import { createWebRuntimeSessionTerminalResult } from '@/runtime/hosted-terminals/creation/web-runtime-terminal-create-operation'
import { cloudTabHoldKey, readCloudAgentHold } from './cloud-agent-launch-hold'
import { isOrcaCloudEnvironmentId } from './orca-cloud-environment-id'
import {
forgetHeldCloudLaunch,
readHeldCloudLaunches,
type HeldCloudLaunchRecord
} from './cloud-held-launch-memory'
import {
isTabOpen,
settleHeldPlaceholder,
type CreateHostTerminal
} from './cloud-web-host-launch-hold'
/** How long a restored placeholder may take to reach the store before its record is dropped. */
export const HELD_LAUNCH_RESTORE_WAIT_MS = 120_000
const resuming = new Set<string>()
function waitForTab(record: HeldCloudLaunchRecord, waitMs: number): Promise<boolean> {
if (isTabOpen(record.worktreeId, record.tabId)) {
return Promise.resolve(true)
}
return new Promise((resolve) => {
const finish = (found: boolean): void => {
unsubscribe()
clearTimeout(timer)
resolve(found)
}
const unsubscribe = useAppStore.subscribe(() => {
if (isTabOpen(record.worktreeId, record.tabId)) {
finish(true)
}
})
const timer = setTimeout(() => finish(false), waitMs)
})
}
async function resumeOne(
record: HeldCloudLaunchRecord,
create: CreateHostTerminal,
waitMs: number
): Promise<void> {
if (!(await waitForTab(record, waitMs))) {
console.info(
`[orca-cloud] held launch dropped: tab ${record.tabId} did not come back after restart`
)
forgetHeldCloudLaunch(record.tabId)
return
}
await settleHeldPlaceholder({
args: {
worktreeId: record.worktreeId,
environmentId: record.environmentId,
agent: record.agent,
...(record.prompt ? { prompt: record.prompt } : {}),
...(record.cwd ? { cwd: record.cwd } : {}),
...(record.targetGroupId ? { targetGroupId: record.targetGroupId } : {})
},
tabId: record.tabId,
agent: record.agent,
create,
restored: true
})
}
/**
* Called when a host's session subscription opens (app start, reconnect). Idempotent: a placeholder
* whose hold is already live (this run placed it) or already being resumed is left alone.
*/
export function resumeHeldCloudLaunches(
environmentId: string,
{
create = createWebRuntimeSessionTerminalResult,
waitMs = HELD_LAUNCH_RESTORE_WAIT_MS
}: { create?: CreateHostTerminal; waitMs?: number } = {}
): void {
if (!isOrcaCloudEnvironmentId(environmentId)) {
return
}
// The records are per Orca profile: read them once the profile is known (it loads at app start).
if (useAppStore.getState().activeOrcaProfileId == null) {
const unsubscribe = useAppStore.subscribe((state) => {
if (state.activeOrcaProfileId != null) {
unsubscribe()
clearTimeout(timer)
resumeHeldCloudLaunches(environmentId, { create, waitMs })
}
})
const timer = setTimeout(unsubscribe, waitMs)
return
}
for (const record of readHeldCloudLaunches(environmentId)) {
if (resuming.has(record.tabId) || readCloudAgentHold(cloudTabHoldKey(record.tabId))) {
continue
}
resuming.add(record.tabId)
void resumeOne(record, create, waitMs).finally(() => resuming.delete(record.tabId))
}
}
export function resetHeldCloudLaunchResumeForTest(): void {
resuming.clear()
}
@@ -22,8 +22,9 @@ import {
holdCloudAgentLaunch,
takeCloudAgentHoldStartedByPerson
} from './cloud-agent-launch-hold'
import { forgetHeldCloudLaunch, rememberHeldCloudLaunch } from './cloud-held-launch-memory'
type CreateHostTerminal = (
export type CreateHostTerminal = (
args: CreateWebRuntimeSessionTerminalOnHostArgs
) => Promise<CreatedWebRuntimeSessionTerminal>
@@ -73,12 +74,49 @@ export async function createWithCloudAgentHold(
return await create(args)
}
const tabId = toWebTerminalSurfaceTabId(webTerminalPlacementParentTabId(placeholder.hostTabId))
// V3-01: the hold is in memory; this record lets a restart put it back in the same placeholder.
if (args.environmentId) {
rememberHeldCloudLaunch({
environmentId: args.environmentId,
worktreeId: args.worktreeId,
tabId,
agent,
prompt: args.prompt?.trim() || null,
cwd: args.cwd?.trim() || null,
targetGroupId: args.targetGroupId ?? null,
createdAt: Date.now()
})
}
return (await settleHeldPlaceholder({ args, tabId, agent, create, decided: true })) ?? placeholder
}
/**
* Holds a launch in its placeholder tab until the strip releases it, then starts the agent in its
* own tab and closes the placeholder. Cancel leaves the shell (returns null). The record of the held
* placeholder is forgotten once the hold settles either way.
*/
export async function settleHeldPlaceholder({
args,
tabId,
agent,
create,
decided = false,
restored = false
}: {
args: CreateWebRuntimeSessionTerminalOnHostArgs
tabId: string
agent: 'claude' | 'codex'
create: CreateHostTerminal
decided?: boolean
restored?: boolean
}): Promise<CreatedWebRuntimeSessionTerminal | null> {
const outcome = await holdCloudAgentLaunch({
paneKey: cloudTabHoldKey(tabId),
agent,
prompt: args.prompt?.trim() || null,
decided: true
})
decided,
restored
}).finally(() => forgetHeldCloudLaunch(tabId))
if (outcome === 'cancel') {
// NOACCT-MISLABEL: the confirmation answers the person's own Cancel, while the shell is still
// there. A hold that ended because its tab or workspace went away (deleted, archived, closed)
@@ -92,7 +130,7 @@ export async function createWithCloudAgentHold(
)
)
}
return placeholder
return null
}
// Started by the person's click in the held pane: bring the agent's tab forward so they see their
// queued prompt run. A Renew's auto-start (maybe on a background tab) never steals focus.
@@ -1,4 +1,5 @@
import { toRuntimeExecutionHostId } from '../../../../shared/execution-host'
import { resumeHeldCloudLaunches } from '@/lib/orca-cloud/cloud-held-launch-resume'
import type { RuntimeMobileSessionTabsResult } from '../../../../shared/runtime-types'
import { recheckUnconfirmedStructuredAgentLaunches } from '../../lib/agent-session/launch/structured-agent-session-launch-unconfirmed-recheck'
import { useAppStore } from '../../store'
@@ -188,4 +189,5 @@ export function handleGlobalSessionInventoryEvent({
})
// Each subscription opens with one census: recheck launches now that the host is reachable.
recheckUnconfirmedStructuredAgentLaunches(toRuntimeExecutionHostId(environmentId))
resumeHeldCloudLaunches(environmentId)
}