From 15adbd9d18a1c8b469297d135bbfa5e90f935880 Mon Sep 17 00:00:00 2001 From: Neil <4138956+nwparker@users.noreply.github.com> Date: Mon, 7 Sep 2026 23:35:26 -0700 Subject: [PATCH 01/59] fix(agent-hooks): guard every Windows missing-target fallback before it reads stdin (#19415) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A Windows hook whose target file is missing fell back to reading stdin and throwing it away. That read never returns when the caller abandons the pipe, which is what happens outside an Orca pane — one stuck process and a visible console per hook event (#11549). The rule 'check the Orca env before you own stdin' existed once in cmd syntax and was retyped by hand elsewhere, so the PowerShell and Git Bash launchers never got it. Derive all three dialects from one list of vars and apply them wherever a missing target makes the caller the stdin owner. - wrapWindowsHookCommand and the runtime-home PowerShell branch guard before ReadToEnd, and emit the fallback answer before the guard so a gate event outside a pane is not answered with silence. - The runtime-home Git Bash fallback picks its rule by platform: POSIX keeps capture-first (#8110), Windows answers, guards, then drains. - The Antigravity wrapper disables delayed expansion like its core; with a '!' in the hooks path it was missing the core on every event (#9358/#9941). Tests drive the wrapper through the production 'cmd /d /c' chain under both delayed-expansion states, and the cross-agent ratchet covers the launchers with an abandoned pipe rather than requiring the unguarded drain. --- src/main/agent-hooks/hook-stdin-contract.ts | 29 +++- src/main/agent-hooks/installer-utils.test.ts | 34 ++-- src/main/agent-hooks/installer-utils.ts | 6 +- .../managed-hook-stdin-lifecycle.test.ts | 101 +++++++++-- .../agent-hooks/runtime-home-hook-command.ts | 30 +++- src/main/antigravity/hook-script.ts | 9 +- .../windows-hook-payload-delivery.test.ts | 160 ++++++++++++++---- src/main/copilot/copilot-managed-script.ts | 5 +- 8 files changed, 303 insertions(+), 71 deletions(-) diff --git a/src/main/agent-hooks/hook-stdin-contract.ts b/src/main/agent-hooks/hook-stdin-contract.ts index acba7927650..de77b2f3e9f 100644 --- a/src/main/agent-hooks/hook-stdin-contract.ts +++ b/src/main/agent-hooks/hook-stdin-contract.ts @@ -74,21 +74,38 @@ export const WINDOWS_HOOK_STDIN_DRAIN_LABEL = 'orca_agent_hook_drain_stdin' export const WINDOWS_HOOK_STDIN_READER = '"%SystemRoot%\\System32\\more.com"' export const WINDOWS_HOOK_STDIN_DRAIN_COMMAND = `${WINDOWS_HOOK_STDIN_READER} >nul 2>nul` +// The Orca context a hook needs before it may own stdin; see the rule below. +const WINDOWS_HOOK_ENVIRONMENT_VARS = [ + 'ORCA_AGENT_HOOK_PORT', + 'ORCA_AGENT_HOOK_TOKEN', + 'ORCA_PANE_KEY' +] as const + // Why (#11549): missing Orca context means the hook ran outside an Orca pane, where the caller // may abandon stdin rather than close it — a read-to-EOF then blocks forever and strands a // visible window per hook event. The Windows rule: a hook must check the Orca env before it // owns stdin, and exit without reading when the env is missing — the payload is discarded on -// that path anyway. This applies to .cmd, the copilot .ps1, and the Git Bash kimi .sh alike. +// that path anyway. This applies to .cmd, the copilot .ps1, and the Git Bash kimi .sh alike, +// and to the launchers that own stdin themselves when the managed script is missing. // POSIX hooks keep capture-first: their callers close stdin, and exiting mid-write there // surfaces as EPIPE the agent can see (#8110). export function buildWindowsHookEnvironmentGuardLines(): string[] { - return [ - 'if "%ORCA_AGENT_HOOK_PORT%"=="" exit /b 0', - 'if "%ORCA_AGENT_HOOK_TOKEN%"=="" exit /b 0', - 'if "%ORCA_PANE_KEY%"=="" exit /b 0' - ] + return WINDOWS_HOOK_ENVIRONMENT_VARS.map((name) => `if "%${name}%"=="" exit /b 0`) } +/** The same guard in sh, for the Git Bash hooks and launchers that run on Windows. + * Default-formed because a static hook precheck (Grok) rejects a bare reference it + * cannot resolve. POSIX hosts keep capture-first — this is the Windows rule only. */ +export const WINDOWS_GIT_BASH_HOOK_ENVIRONMENT_GUARD = `if ${WINDOWS_HOOK_ENVIRONMENT_VARS.map( + (name) => `[ -z "\${${name}-}" ]` +).join(' || ')}; then exit 0; fi` + +/** The same guard for a PowerShell hook or launcher. Anything that reaches + * `[Console]::In.ReadToEnd()` must run this first, or it inherits #11549. */ +export const WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD = `if (${WINDOWS_HOOK_ENVIRONMENT_VARS.map( + (name) => `-not $env:${name}` +).join(' -or ')}) { exit 0 }` + export function buildWindowsHookStdinDrainEpilogue(): string[] { return [`:${WINDOWS_HOOK_STDIN_DRAIN_LABEL}`, WINDOWS_HOOK_STDIN_DRAIN_COMMAND, 'exit /b 0'] } diff --git a/src/main/agent-hooks/installer-utils.test.ts b/src/main/agent-hooks/installer-utils.test.ts index 215979206e9..cbe29ee1ca1 100644 --- a/src/main/agent-hooks/installer-utils.test.ts +++ b/src/main/agent-hooks/installer-utils.test.ts @@ -31,7 +31,10 @@ import { type HooksConfig } from './installer-utils' import { buildPosixAgentHookPostCommand } from './hook-post-command' -import { POSIX_HOOK_STDIN_DRAIN_COMMAND } from './hook-stdin-contract' +import { + POSIX_HOOK_STDIN_DRAIN_COMMAND, + WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD +} from './hook-stdin-contract' import { wrapRuntimeHomeHookCommand } from './runtime-home-hook-command' let tmpDir: string @@ -618,7 +621,10 @@ function expectedDecodedWindowsHookCommand(scriptPath: string): string { // Why: the execution-policy bypass rides in the payload, not on the command // line, so the launcher cannot spell the AV-blocked flag triple (#16003). // Why: PowerShell progress CLIXML corrupts consumers that merge stderr into JSON stdout. - return `$ProgressPreference='SilentlyContinue'; try { Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force -ErrorAction SilentlyContinue } catch {}; if (Test-Path -LiteralPath ${quoted} -PathType Leaf) { & ${quoted}; exit $LASTEXITCODE }; [Console]::In.ReadToEnd() | Out-Null; exit 0` + // Why the guard is spelled by import: the launcher owns stdin on the missing-script path, + // so it obeys the shared Windows rule (#11549), and re-typing it here would let the two + // drift back apart. + return `$ProgressPreference='SilentlyContinue'; try { Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force -ErrorAction SilentlyContinue } catch {}; if (Test-Path -LiteralPath ${quoted} -PathType Leaf) { & ${quoted}; exit $LASTEXITCODE }; ${WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD}; [Console]::In.ReadToEnd() | Out-Null; exit 0` } describe('wrapWindowsHookCommand', () => { @@ -640,15 +646,23 @@ describe('wrapWindowsHookCommand', () => { ) }) - it('emits fallback stdout when the managed script is missing', () => { - const command = wrapWindowsHookCommand( - 'C:\\hooks\\cursor-hook.cmd', - {}, - { fallbackStdout: '{"permission":"allow"}' } - ) - expect(decodeWindowsHookCommand(command)).toContain( - 'Write-Output \'{"permission":"allow"}\'; exit 0' + // Why the ordering matters: a gate event reads silence as deny (#2426), and outside an + // Orca pane the guard exits before the read — so an answer placed after the drain never + // reaches the agent at all when the caller abandons the pipe (#11549). + it('answers before it guards, and guards before it owns stdin', () => { + const decoded = decodeWindowsHookCommand( + wrapWindowsHookCommand( + 'C:\\hooks\\cursor-hook.cmd', + {}, + { fallbackStdout: '{"permission":"allow"}' } + ) ) + const answer = decoded.indexOf('Write-Output \'{"permission":"allow"}\'') + const guard = decoded.indexOf(WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD) + const ownsStdin = decoded.indexOf('[Console]::In.ReadToEnd()') + expect(answer).toBeGreaterThan(-1) + expect(guard).toBeGreaterThan(answer) + expect(ownsStdin).toBeGreaterThan(guard) }) // Why: a user profile path like `C:\Users\Jane Doe` is the regression from diff --git a/src/main/agent-hooks/installer-utils.ts b/src/main/agent-hooks/installer-utils.ts index 8667c418492..a53721d42fe 100644 --- a/src/main/agent-hooks/installer-utils.ts +++ b/src/main/agent-hooks/installer-utils.ts @@ -16,6 +16,7 @@ import { grantDirAcl, isPermissionError } from '../win32-utils' import { resolveHooksJsonWritePath } from './hook-config-write-path' import { writeRollingFileBackup } from '../rolling-file-backup' import { wrapWindowsPowerShellEncodedCommand } from './windows-powershell-hook-launcher' +import { WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD } from './hook-stdin-contract' export type HookCommandConfig = { type: 'command' @@ -131,7 +132,10 @@ export function wrapWindowsHookCommand( options.fallbackStdout === undefined ? '' : `Write-Output ${quotePowerShellString(options.fallbackStdout)}; ` - const command = `${envPrefix}if (Test-Path -LiteralPath ${quoted} -PathType Leaf) { & ${quoted}; exit $LASTEXITCODE }; [Console]::In.ReadToEnd() | Out-Null; ${fallback}exit 0` + // Why the order: answer first (a gate event reads silence as deny), then the shared + // env guard, and only then own stdin — outside an Orca pane the caller may abandon the + // pipe, and ReadToEnd would strand the launcher there forever (#11549). + const command = `${envPrefix}if (Test-Path -LiteralPath ${quoted} -PathType Leaf) { & ${quoted}; exit $LASTEXITCODE }; ${fallback}${WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD}; [Console]::In.ReadToEnd() | Out-Null; exit 0` return wrapWindowsPowerShellEncodedCommand(command) } diff --git a/src/main/agent-hooks/managed-hook-stdin-lifecycle.test.ts b/src/main/agent-hooks/managed-hook-stdin-lifecycle.test.ts index af70f6f54f0..dea4545ad11 100644 --- a/src/main/agent-hooks/managed-hook-stdin-lifecycle.test.ts +++ b/src/main/agent-hooks/managed-hook-stdin-lifecycle.test.ts @@ -63,12 +63,26 @@ import { KimiHookService } from '../kimi/hook-service' import { openClaudeHookService } from '../openclaude/hook-service' import { wrapPosixHookCommand, wrapWindowsHookCommand } from './installer-utils' -import { POSIX_HOOK_STDIN_READER } from './hook-stdin-contract' +import { + POSIX_HOOK_STDIN_READER, + WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD +} from './hook-stdin-contract' import { wrapRuntimeHomeHookCommand } from './runtime-home-hook-command' import { createAgentHookMemorySftp } from './agent-hook-memory-sftp.test-fixture' import { findGitBash } from './windows-git-bash-path.test-fixture' +/** The launchers ship their command base64'd; assert the shape they actually run. */ +function decodeEncodedPowerShellCommand(command: string): string { + const encoded = command.match(/-EncodedCommand\s+(\S+)/) + expect(encoded, 'launcher carries an encoded command').not.toBeNull() + return Buffer.from(encoded![1], 'base64').toString('utf16le') +} + const REMOTE_HOME = '/home/dev' +// Why all three: Windows reports a write to a pipe whose reader is gone as any of these, +// depending on whether the read handle, the pipe, or the process went first. Enumerating +// them keeps the guard-exit legs from failing on which race the host happened to run. +const WRITER_BROKEN_BY_EARLY_EXIT = ['EPIPE', 'ECONNRESET', 'EOF'] const LARGE_PAYLOAD = Buffer.alloc(1_000_000, 'x') // Why: a developer box may set HKCU\...\Command Processor\AutoRun, which cmd.exe runs before any @@ -156,7 +170,10 @@ type HookRun = { function runHookProcess( executable: string, args: string[], - env: NodeJS.ProcessEnv + env: NodeJS.ProcessEnv, + // Why: `abandon` leaves the pipe open and unwritten — the shape a caller outside an Orca + // pane produces, and the only one that can catch a read-to-EOF that never returns (#11549). + stdin: 'close' | 'abandon' = 'close' ): Promise { return new Promise((resolve, reject) => { const child = spawn(executable, args, { env, stdio: ['pipe', 'pipe', 'pipe'] }) @@ -164,8 +181,9 @@ function runHookProcess( let stderr = '' let stdout = '' const timeout = setTimeout(() => { + child.stdin.destroy() child.kill('SIGKILL') - reject(new Error('hook did not finish after stdin closed')) + reject(new Error(`hook did not finish with stdin ${stdin}d`)) }, 10_000) child.on('error', (error) => { clearTimeout(timeout) @@ -182,7 +200,9 @@ function runHookProcess( clearTimeout(timeout) resolve({ exitCode, stdinErrors, stderr, stdout }) }) - child.stdin.end(LARGE_PAYLOAD) + if (stdin === 'close') { + child.stdin.end(LARGE_PAYLOAD) + } }) } @@ -303,6 +323,31 @@ describe('Windows managed hook stdin structure', () => { expect(copilot.indexOf('if (-not $env:ORCA_AGENT_HOOK_PORT')).toBeLessThan( copilot.indexOf('[Console]::In.ReadToEnd()') ) + // Why: the two encoded-PowerShell launchers own stdin themselves when the managed + // script is missing, so the same guard has to precede their ReadToEnd — and the + // fallback answer has to precede the guard, or a gate event outside a pane is + // answered with silence, which reads as deny (#2426/#15462). + for (const [name, command] of [ + [ + 'wrapWindowsHookCommand', + wrapWindowsHookCommand('C:\\missing\\orca-hook.cmd', {}, { fallbackStdout: '{}' }) + ], + [ + 'wrapRuntimeHomeHookCommand', + wrapRuntimeHomeHookCommand('missing-orca-hook', { neutralJsonWhenMissing: true }) + ] + ] as const) { + const decoded = decodeEncodedPowerShellCommand(command) + expect(decoded, `${name} decoded`).toContain(WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD) + expect(decoded.indexOf("Write-Output '{}'"), `${name} answers first`).toBeLessThan( + decoded.indexOf(WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD) + ) + expect( + decoded.indexOf(WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD), + `${name} guards before owning stdin` + ).toBeLessThan(decoded.indexOf('[Console]::In.ReadToEnd()')) + } + const kimi = readFileSync(join(hooksDir, 'kimi-hook.sh'), 'utf8') expect(kimi.indexOf('if [ -z "$ORCA_AGENT_HOOK_PORT" ]')).toBeGreaterThan(-1) expect(kimi.indexOf('if [ -z "$ORCA_AGENT_HOOK_PORT" ]')).toBeLessThan( @@ -365,12 +410,11 @@ describe('Windows managed hook stdin structure', () => { const result = await runHookProcess(executable, args, hookEnvironment()) expect(result.exitCode, `${fileName} exit code`).toBe(0) // Why (#11549 class): every Windows-local hook exits before owning stdin when the - // Orca env is missing, so the writer may break — EPIPE, or ECONNRESET when Windows - // tears the pipe down first. hookEnvironment() strips every ORCA_* var, so this - // relaxation only ever covers the missing-env path — a happy-path case added to - // this loop must not reuse it. + // Orca env is missing, so the writer may break. hookEnvironment() strips every + // ORCA_* var, so this relaxation only ever covers the missing-env path — a + // happy-path case added to this loop must not reuse it. for (const error of result.stdinErrors) { - expect(['EPIPE', 'ECONNRESET'], `${fileName} stdin error`).toContain(error.code) + expect(WRITER_BROKEN_BY_EARLY_EXIT, `${fileName} stdin error`).toContain(error.code) } } @@ -395,9 +439,42 @@ describe('Windows managed hook stdin structure', () => { } ] for (const launcher of launcherCases) { - const result = await runHookProcess(launcher.executable, launcher.args, hookEnvironment()) - expect(result.exitCode, `${launcher.name} exit code`).toBe(0) - expect(result.stdinErrors, `${launcher.name} stdin errors`).toHaveLength(0) + // Why (#11549 class): a launcher that reaches an interpreter owns stdin for a + // missing script exactly like a managed script does, so it obeys the same rule — + // drain inside a pane, exit before reading outside one. Its writer may therefore + // break on the missing-env leg, and must not on the in-pane leg. + const outside = await runHookProcess( + launcher.executable, + launcher.args, + hookEnvironment() + ) + expect(outside.exitCode, `${launcher.name} exit code`).toBe(0) + for (const error of outside.stdinErrors) { + expect(WRITER_BROKEN_BY_EARLY_EXIT, `${launcher.name} stdin error`).toContain( + error.code + ) + } + const insideAPane = await runHookProcess( + launcher.executable, + launcher.args, + hookEnvironment({ + ORCA_AGENT_HOOK_PORT: '59999', + ORCA_AGENT_HOOK_TOKEN: 'token', + ORCA_PANE_KEY: 'tab:leaf' + }) + ) + expect(insideAPane.exitCode, `${launcher.name} in-pane exit code`).toBe(0) + expect(insideAPane.stdinErrors, `${launcher.name} in-pane stdin errors`).toHaveLength(0) + // Why this leg and not a shape assertion: an unguarded ReadToEnd exits fine when + // the writer closes the pipe. Only a caller that abandons it strands the launcher, + // which is what left a console per hook event on the reporting hosts. + const abandoned = await runHookProcess( + launcher.executable, + launcher.args, + hookEnvironment(), + 'abandon' + ) + expect(abandoned.exitCode, `${launcher.name} abandoned-stdin exit code`).toBe(0) } } finally { homedirMock.mockImplementation(() => process.env.HOME ?? tmpdir()) diff --git a/src/main/agent-hooks/runtime-home-hook-command.ts b/src/main/agent-hooks/runtime-home-hook-command.ts index 3a6f0d20725..e56fc603b43 100644 --- a/src/main/agent-hooks/runtime-home-hook-command.ts +++ b/src/main/agent-hooks/runtime-home-hook-command.ts @@ -1,4 +1,8 @@ -import { POSIX_HOOK_STDIN_DRAIN_COMMAND } from './hook-stdin-contract' +import { + POSIX_HOOK_STDIN_DRAIN_COMMAND, + WINDOWS_GIT_BASH_HOOK_ENVIRONMENT_GUARD, + WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD +} from './hook-stdin-contract' import { encodeWindowsPowerShellHookCommand, WINDOWS_POWERSHELL_HOOK_SWITCHES @@ -19,16 +23,30 @@ export function wrapRuntimeHomeHookCommand( const windowsScript = `"\${HOME-}/.orca/agent-hooks/${scriptBaseName}.cmd"` const posixScript = `"\${HOME-}/.orca/agent-hooks/${scriptBaseName}.sh"` const drain = POSIX_HOOK_STDIN_DRAIN_COMMAND - const missingScriptFallback = options.neutralJsonWhenMissing ? `${drain}; printf '{}\\n'` : drain + const neutralJson = options.neutralJsonWhenMissing ? `printf '{}\\n'` : '' + // Why two forms: the missing-script fallback owns stdin, so it follows the rule of the host + // it lands on. POSIX callers close the pipe, so capture-first is safe there and a mid-write + // exit stays visible as EPIPE (#8110). A Windows caller may abandon the pipe, so there the + // answer comes first and the drain only runs with an Orca env behind it (#11549). + const posixMissingScriptFallback = neutralJson ? `${drain}; ${neutralJson}` : drain + const windowsMissingScriptFallback = [ + ...(neutralJson ? [neutralJson] : []), + WINDOWS_GIT_BASH_HOOK_ENVIRONMENT_GUARD, + drain + ].join('; ') + // Why platform-selected even when HOME is unset: which stdin rule applies follows the + // caller, not the reason the script could not be found. + const missingScriptFallback = `case "\${OSTYPE-}" in msys*|cygwin*|win32*) ${windowsMissingScriptFallback} ;; *) ${posixMissingScriptFallback} ;; esac` const powershell = '"${SYSTEMROOT-}/System32/WindowsPowerShell/v1.0/powershell.exe"' const powershellFallback = options.neutralJsonWhenMissing ? "; Write-Output '{}'" : '' - const powershellCommand = `$homePath = $env:HOME -replace '^/([A-Za-z])/', '$1:/'; $scriptPath = Join-Path $homePath '.orca\\agent-hooks\\${scriptBaseName}.cmd'; if (Test-Path -LiteralPath $scriptPath -PathType Leaf) { & $scriptPath; exit $LASTEXITCODE }; [Console]::In.ReadToEnd() | Out-Null${powershellFallback}; exit 0` + // Why the order: answer first, then the shared env guard, then own stdin — see wrapWindowsHookCommand. + const powershellCommand = `$homePath = $env:HOME -replace '^/([A-Za-z])/', '$1:/'; $scriptPath = Join-Path $homePath '.orca\\agent-hooks\\${scriptBaseName}.cmd'; if (Test-Path -LiteralPath $scriptPath -PathType Leaf) { & $scriptPath; exit $LASTEXITCODE }${powershellFallback}; ${WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD}; [Console]::In.ReadToEnd() | Out-Null; exit 0` const encodedCommand = encodeWindowsPowerShellHookCommand(powershellCommand) // Why: the Git Bash and native Windows launchers must spell the same switches — window suppression (#14815) and an AV verdict on the shape (#16003) both hit either path. const powershellInvocation = `${powershell} ${WINDOWS_POWERSHELL_HOOK_SWITCHES} -EncodedCommand ${encodedCommand}` - const encodedWindowsBranch = `if [ -f ${powershell} ]; then ${powershellInvocation}; else ${missingScriptFallback}; fi` - const windowsBranch = `if [ -f ${windowsScript} ]; then case "\${HOME-}" in ${WINDOWS_GIT_BASH_RUNTIME_HOME_UNSAFE}) ${encodedWindowsBranch} ;; *) ${windowsScript} ;; esac; else ${missingScriptFallback}; fi` - const posixBranch = `if [ -f ${posixScript} ] && [ -r ${posixScript} ] && [ -x ${posixScript} ]; then /bin/sh ${posixScript}; else ${missingScriptFallback}; fi` + const encodedWindowsBranch = `if [ -f ${powershell} ]; then ${powershellInvocation}; else ${windowsMissingScriptFallback}; fi` + const windowsBranch = `if [ -f ${windowsScript} ]; then case "\${HOME-}" in ${WINDOWS_GIT_BASH_RUNTIME_HOME_UNSAFE}) ${encodedWindowsBranch} ;; *) ${windowsScript} ;; esac; else ${windowsMissingScriptFallback}; fi` + const posixBranch = `if [ -f ${posixScript} ] && [ -r ${posixScript} ] && [ -x ${posixScript} ]; then /bin/sh ${posixScript}; else ${posixMissingScriptFallback}; fi` // Why: OSTYPE is shell-owned, so platform selection adds no process to every hook invocation. return `if [ -z "\${HOME-}" ]; then ${missingScriptFallback}; else case "\${OSTYPE-}" in msys*|cygwin*|win32*) ${windowsBranch} ;; *) ${posixBranch} ;; esac; fi` } diff --git a/src/main/antigravity/hook-script.ts b/src/main/antigravity/hook-script.ts index 67f1f639ef9..fb27ad63494 100644 --- a/src/main/antigravity/hook-script.ts +++ b/src/main/antigravity/hook-script.ts @@ -88,7 +88,10 @@ export function getManagedScript(target: 'local' | 'posix' = 'local'): string { export function getWindowsWrapperScript(eventName: string): string { return [ '@echo off', - 'setlocal', + // Why (#9358/#9941): `!` is legal in the hooks path, and inherited delayed expansion + // eats it out of the percent-expanded `%~dp0` — the wrapper then misses the core and + // silently falls back on every event. Same reason the core disables it. + 'setlocal DisableDelayedExpansion', `set "ORCA_ANTIGRAVITY_EVENT=${eventName}"`, 'set "ORCA_ANTIGRAVITY_CORE=%~dp0antigravity-hook.cmd"', 'if exist "%ORCA_ANTIGRAVITY_CORE%" (', @@ -102,8 +105,8 @@ export function getWindowsWrapperScript(eventName: string): string { ') else (', ' echo {}', ')', - // Why: when the shared core script is missing, this wrapper becomes the - // stdin owner and must finish the agent's payload write before returning. + // Missing-core fallbacks obey the same outside-Orca stdin guard as the core. + ...buildWindowsHookEnvironmentGuardLines(), WINDOWS_HOOK_STDIN_DRAIN_COMMAND, 'exit /b 0', '' diff --git a/src/main/antigravity/windows-hook-payload-delivery.test.ts b/src/main/antigravity/windows-hook-payload-delivery.test.ts index 8261cc3ce91..6c9ca08bd27 100644 --- a/src/main/antigravity/windows-hook-payload-delivery.test.ts +++ b/src/main/antigravity/windows-hook-payload-delivery.test.ts @@ -28,7 +28,8 @@ vi.mock('os', async (importOriginal) => { import { AntigravityHookService } from './hook-service' import { ANTIGRAVITY_EVENTS, ANTIGRAVITY_PRE_TOOL_USE_DECISION } from './hook-events' -import { getManagedScript } from './hook-script' +import { getManagedScript, getWindowsWrapperScript } from './hook-script' +import { WINDOWS_HOOK_STDIN_DRAIN_COMMAND } from '../agent-hooks/hook-stdin-contract' // Why (#9358/#9941): `!` is legal in a Windows path and in a pane key. Under inherited // delayed expansion cmd eats it out of a percent-expanded curl argument, so bake one into @@ -91,17 +92,23 @@ async function startHookListener(): Promise<{ type HookRun = { exitCode: number | null; stdout: string; stderr: string; timedOut: boolean } +// Why spell `/v`: `cmd /d /c ` is the chain in the bug report's process trace, +// and it inherits HKCU\...\Command Processor\DelayedExpansion. Naming the state makes the +// hostile half reachable on any host — under `/v:on` cmd eats `!` out of every percent +// expansion (#9358/#9941), and a harness pinned to `/v:off` could never fail on it. +type DelayedExpansion = 'on' | 'off' +const DELAYED_EXPANSION_STATES = ['off', 'on'] as const satisfies readonly DelayedExpansion[] + function runWrapper( wrapperPath: string, env: NodeJS.ProcessEnv, // Why: `null` abandons stdin instead of closing it — the shape a caller outside an Orca // pane produces, and the only way to prove the env guard exits before reading (#11549). - stdinPayload: string | null = PAYLOAD + stdinPayload: string | null = PAYLOAD, + delayedExpansion: DelayedExpansion = 'off' ): Promise { return new Promise((resolve, reject) => { - // Why: mirror how Antigravity spawns the hook — `cmd /c `, the exact - // chain in the bug report's process trace. - const child = spawn('cmd.exe', ['/d', '/c', wrapperPath], { + const child = spawn('cmd.exe', [`/v:${delayedExpansion}`, '/d', '/c', wrapperPath], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, env @@ -111,6 +118,7 @@ function runWrapper( let timedOut = false const timer = setTimeout(() => { timedOut = true + child.stdin.destroy() child.kill('SIGKILL') }, 15_000) child.on('error', (error) => { @@ -154,6 +162,24 @@ function expectedStdout(eventName: string): string { // Why: runs on every platform — the live delivery suite below is Windows-only, so this // keeps a POSIX-only CI leg from letting the interpreter back into the hot path. describe('Antigravity Windows hook post command', () => { + it.each(ANTIGRAVITY_EVENTS)('guards missing-core stdin for $eventName', ({ eventName }) => { + const script = getWindowsWrapperScript(eventName) + const drain = script.indexOf(WINDOWS_HOOK_STDIN_DRAIN_COMMAND) + const answer = script.lastIndexOf('echo {}') + expect(drain).toBeGreaterThan(answer) + for (const key of ['ORCA_AGENT_HOOK_PORT', 'ORCA_AGENT_HOOK_TOKEN', 'ORCA_PANE_KEY']) { + const guard = script.indexOf(`if "%${key}%"=="" exit /b 0`) + expect(guard, key).toBeGreaterThan(answer) + expect(guard, key).toBeLessThan(drain) + } + }) + + // Why (#9358/#9941): `%~dp0` carries the hooks path, so an inherited delayed expansion eats + // a `!` out of it and the wrapper silently misses the core on every event. + it.each(ANTIGRAVITY_EVENTS)('disables delayed expansion for $eventName', ({ eventName }) => { + expect(getWindowsWrapperScript(eventName)).toContain('setlocal DisableDelayedExpansion') + }) + it('posts through curl.exe rather than a PowerShell interpreter', () => { vi.spyOn(process, 'platform', 'get').mockReturnValue('win32') const script = getManagedScript('local') @@ -185,7 +211,10 @@ describe.skipIf(process.platform !== 'win32')('Antigravity Windows hook payload }) it('delivers every event wrapper payload to the listener without spawning PowerShell', async () => { - home = mkdtempSync(join(tmpdir(), 'orca-antigravity-hook-')) + // Why the `!` in the directory: it lands in the wrapper's `%~dp0`, which is what an + // inherited delayed expansion eats (#9358/#9941). Without it the `/v:on` leg below + // proves nothing about the core lookup. + home = mkdtempSync(join(tmpdir(), 'orca-antigravity-hook!bang-')) homedirMock.mockReturnValue(home) expect(new AntigravityHookService().install().state).toBe('installed') @@ -204,34 +233,42 @@ describe.skipIf(process.platform !== 'win32')('Antigravity Windows hook payload ORCA_WORKTREE_ID: WORKTREE_ID }) - for (const event of ANTIGRAVITY_EVENTS) { - const label = event.eventName - const before = listener.posts.length - const result = await runWrapper(join(hooksDir, event.windowsWrapperFileName), env) + for (const delayedExpansion of DELAYED_EXPANSION_STATES) { + for (const event of ANTIGRAVITY_EVENTS) { + const label = `${event.eventName} (/v:${delayedExpansion})` + const before = listener.posts.length + const result = await runWrapper( + join(hooksDir, event.windowsWrapperFileName), + env, + PAYLOAD, + delayedExpansion + ) - expect(result.timedOut, `${label} timed out`).toBe(false) - expect(result.exitCode, `${label} exit code`).toBe(0) - expect(result.stderr, `${label} stderr`).toBe('') - // Why: Antigravity reads silence on PreToolUse as deny (#2426), so the gate answer - // must survive the transport change. - expect(result.stdout.trim(), `${label} stdout`).toBe(expectedStdout(label)) + expect(result.timedOut, `${label} timed out`).toBe(false) + expect(result.exitCode, `${label} exit code`).toBe(0) + expect(result.stderr, `${label} stderr`).toBe('') + // Why: Antigravity reads silence on PreToolUse as deny (#2426), so the gate answer + // must survive the transport change. + expect(result.stdout.trim(), `${label} stdout`).toBe(expectedStdout(event.eventName)) - const posts = listener.posts.slice(before) - expect(posts, `${label} posted exactly one hook`).toHaveLength(1) - // Why: byte-exact, not "non-empty" — PowerShell recoded this body through the console - // code page, and a silently corrupted payload still looks posted. - expect(posts[0].payload, `${label} payload`).toBe(PAYLOAD) - expect(posts[0].hookEventName, `${label} hook_event_name`).toBe(label) - // Why: the `!` in both values is the delayed-expansion regression guard. - expect(posts[0].paneKey, `${label} paneKey`).toBe(PANE_KEY) - expect(posts[0].worktreeId, `${label} worktreeId`).toBe(WORKTREE_ID) - expect(posts[0].token, `${label} token`).toBe(HOOK_TOKEN) - expect(posts[0].contentType, `${label} content-type`).toContain( - 'application/x-www-form-urlencoded' - ) + const posts = listener.posts.slice(before) + expect(posts, `${label} posted exactly one hook`).toHaveLength(1) + // Why: byte-exact, not "non-empty" — PowerShell recoded this body through the console + // code page, and a silently corrupted payload still looks posted. + expect(posts[0].payload, `${label} payload`).toBe(PAYLOAD) + expect(posts[0].hookEventName, `${label} hook_event_name`).toBe(event.eventName) + // Why: the `!` in both values is the delayed-expansion regression guard — it is the + // `/v:on` leg that can actually fail on it. + expect(posts[0].paneKey, `${label} paneKey`).toBe(PANE_KEY) + expect(posts[0].worktreeId, `${label} worktreeId`).toBe(WORKTREE_ID) + expect(posts[0].token, `${label} token`).toBe(HOOK_TOKEN) + expect(posts[0].contentType, `${label} content-type`).toContain( + 'application/x-www-form-urlencoded' + ) + } } - // Why: five wrapper launches plus a real install can overrun the default under load. - }, 60_000) + // Why: ten wrapper launches plus a real install can overrun the default under load. + }, 90_000) // Why (#15117): Antigravity fires some events with no stdin at all. PowerShell substituted // `{}` before posting; curl forwards the empty body, so prove the post still happens — the @@ -264,6 +301,67 @@ describe.skipIf(process.platform !== 'win32')('Antigravity Windows hook payload expect(listener.posts[0].hookEventName).toBe('PreInvocation') }, 30_000) + // Why a helper: the missing-core cases all need a real install with the core removed, which + // is the shape an AV quarantine or a half-finished uninstall leaves behind. + async function installWithoutCore(): Promise { + home = mkdtempSync(join(tmpdir(), 'orca-antigravity-fallback-')) + homedirMock.mockReturnValue(home) + expect(new AntigravityHookService().install().state).toBe('installed') + const hooksDir = join(home, '.orca', 'agent-hooks') + rmSync(join(hooksDir, 'antigravity-hook.cmd')) + return hooksDir + } + + it.each(['ORCA_AGENT_HOOK_PORT', 'ORCA_AGENT_HOOK_TOKEN', 'ORCA_PANE_KEY'])( + 'answers every missing-core event with abandoned stdin and no %s', + async (missingKey) => { + const hooksDir = await installWithoutCore() + const listener = await startHookListener() + server = listener.server + const env = hookEnvironment({ + USERPROFILE: home, + HOME: home, + ORCA_AGENT_HOOK_PORT: String(listener.port), + ORCA_AGENT_HOOK_TOKEN: HOOK_TOKEN, + ORCA_PANE_KEY: PANE_KEY, + [missingKey]: '' + }) + for (const event of ANTIGRAVITY_EVENTS) { + const result = await runWrapper(join(hooksDir, event.windowsWrapperFileName), env, null) + expect(result.timedOut, event.eventName).toBe(false) + expect(result.exitCode, event.eventName).toBe(0) + expect(result.stdout.trim(), event.eventName).toBe(expectedStdout(event.eventName)) + expect(result.stderr, event.eventName).toBe('') + } + expect(listener.posts).toHaveLength(0) + }, + 90_000 + ) + + // Why: the guard must not cost the valid path its drain — with the Orca env present the + // fallback still owns stdin, so the agent's payload write completes instead of breaking. + it('still drains a closed payload for every missing-core event inside a pane', async () => { + const hooksDir = await installWithoutCore() + const listener = await startHookListener() + server = listener.server + const env = hookEnvironment({ + USERPROFILE: home, + HOME: home, + ORCA_AGENT_HOOK_PORT: String(listener.port), + ORCA_AGENT_HOOK_TOKEN: HOOK_TOKEN, + ORCA_PANE_KEY: PANE_KEY + }) + for (const event of ANTIGRAVITY_EVENTS) { + const result = await runWrapper(join(hooksDir, event.windowsWrapperFileName), env) + expect(result.timedOut, event.eventName).toBe(false) + expect(result.exitCode, event.eventName).toBe(0) + expect(result.stdout.trim(), event.eventName).toBe(expectedStdout(event.eventName)) + expect(result.stderr, event.eventName).toBe('') + } + // Why: the fallback answers the agent but has no core to post through. + expect(listener.posts).toHaveLength(0) + }, 60_000) + it('exits without reading stdin when the pane env is missing', async () => { home = mkdtempSync(join(tmpdir(), 'orca-antigravity-hook-')) homedirMock.mockReturnValue(home) diff --git a/src/main/copilot/copilot-managed-script.ts b/src/main/copilot/copilot-managed-script.ts index 492caafc045..018b026c992 100644 --- a/src/main/copilot/copilot-managed-script.ts +++ b/src/main/copilot/copilot-managed-script.ts @@ -1,7 +1,8 @@ import { getSharedManagedScriptPath } from '../agent-hooks/installer-utils' import { buildPosixHookPayloadCapture, - buildPosixHookSpoolLines + buildPosixHookSpoolLines, + WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD } from '../agent-hooks/hook-stdin-contract' export function getManagedScriptFileName(): string { @@ -30,7 +31,7 @@ export function getManagedScript(target: 'local' | 'posix' = 'local'): string { // Why (#11549 class): missing Orca context means a user-wide hook fired outside an // Orca pane. ReadToEnd blocks forever if that caller abandons the pipe, so the guard // must run before the hook owns stdin; the payload would be discarded anyway. - 'if (-not $env:ORCA_AGENT_HOOK_PORT -or -not $env:ORCA_AGENT_HOOK_TOKEN -or -not $env:ORCA_PANE_KEY) { exit 0 }', + WINDOWS_POWERSHELL_HOOK_ENVIRONMENT_GUARD, '$inputData = [Console]::In.ReadToEnd()', 'if ([string]::IsNullOrWhiteSpace($inputData)) { exit 0 }', 'try {', From 53233be289a32b158433025b330248ba73e7c837 Mon Sep 17 00:00:00 2001 From: OrcaWin Date: Tue, 8 Sep 2026 00:10:38 -0700 Subject: [PATCH 02/59] perf: count GitLab diff line prefixes without splitting all lines (#19505) * perf: count GitLab diff line prefixes without splitting all lines * test(gitlab): pin diff-count parity for CRLF, lone CR and non-ASCII lines --------- Co-authored-by: m4air Co-authored-by: Neil <4138956+nwparker@users.noreply.github.com> --- src/main/gitlab/mr-file-diffs.ts | 24 ++++++++------ src/main/gitlab/work-item-details.test.ts | 38 +++++++++++++++++++++++ 2 files changed, 52 insertions(+), 10 deletions(-) diff --git a/src/main/gitlab/mr-file-diffs.ts b/src/main/gitlab/mr-file-diffs.ts index 0e16567a294..8f6d10ce410 100644 --- a/src/main/gitlab/mr-file-diffs.ts +++ b/src/main/gitlab/mr-file-diffs.ts @@ -25,19 +25,23 @@ export function countDiffLines(diff: string): { additions: number; deletions: nu // diff line `---`, colliding with the `--- a/file` header — so it must // be counted once inside a hunk, not skipped. let inHunk = false - for (const line of diff.split('\n')) { - if (line.startsWith('@@')) { + let cursor = 0 + while (cursor < diff.length) { + if (diff.startsWith('@@', cursor)) { inHunk = true - continue + } else if (inHunk) { + const prefix = diff.charCodeAt(cursor) + if (prefix === 43) { + additions += 1 + } else if (prefix === 45) { + deletions += 1 + } } - if (!inHunk) { - continue - } - if (line.startsWith('+')) { - additions += 1 - } else if (line.startsWith('-')) { - deletions += 1 + const newline = diff.indexOf('\n', cursor) + if (newline === -1) { + break } + cursor = newline + 1 } return { additions, deletions } } diff --git a/src/main/gitlab/work-item-details.test.ts b/src/main/gitlab/work-item-details.test.ts index f1e2297e14b..9de6bb43d03 100644 --- a/src/main/gitlab/work-item-details.test.ts +++ b/src/main/gitlab/work-item-details.test.ts @@ -458,4 +458,42 @@ describe('countDiffLines', () => { // Why: the `@@` hunk check runs first, so it must not swallow `+`/`-` content. expect(countDiffLines('@@ -1 +1 @@\n-@@ old\n+@@ new')).toEqual({ additions: 1, deletions: 1 }) }) + + // Why: the scan now reads a prefix code unit at a byte cursor rather than a split + // segment, so line-ending and non-ASCII shapes are the new regression surface. + it('counts a CRLF hunk the same as an LF hunk', () => { + expect(countDiffLines('@@ -1 +1,2 @@\r\n-old\r\n+a\r\n+b\r\n')).toEqual({ + additions: 2, + deletions: 1 + }) + }) + + it('treats a lone CR as content, not a line break', () => { + expect(countDiffLines('@@ -1 +1 @@\n-old\r+new')).toEqual({ additions: 0, deletions: 1 }) + }) + + it('counts lines whose content is multi-byte or a surrogate pair', () => { + expect(countDiffLines('@@ -1 +1 @@\n-é ünïcode\n+🚀 rocket')).toEqual({ + additions: 1, + deletions: 1 + }) + }) + + it('ignores non-ASCII context lines and blank lines inside a hunk', () => { + expect(countDiffLines('@@ -1 +1 @@\n é leading accent\n 🚀 leading emoji\n\n')).toEqual({ + additions: 0, + deletions: 0 + }) + }) + + it('counts large diff prefixes without allocating a string array for every line', () => { + const diff = `--- a/file\n+++ b/file\n@@ -1 +1 @@\n${'-old\n+new\n context\n'.repeat(10000)}` + const split = vi.spyOn(String.prototype, 'split') + try { + expect(countDiffLines(diff)).toEqual({ additions: 10000, deletions: 10000 }) + expect(split.mock.calls.length).toBe(0) + } finally { + split.mockRestore() + } + }) }) From 2e19342c120dc92ee27a0c5d8c4321b1e5b39c70 Mon Sep 17 00:00:00 2001 From: Neil <4138956+nwparker@users.noreply.github.com> Date: Tue, 8 Sep 2026 00:37:21 -0700 Subject: [PATCH 03/59] fix(terminal): remove host-retired ghost panes in paired remote splits (#19365) Adds the missing removal path to the host-authoritative layout reconciler, so a pane the host has retired is unmounted once its PTY has cleared. Fixes #17770. The removal planner, its retired-set gate, the null-PTY guard, the never-last-pane guard and their unit tests originate from #18387 by @ylcn91. This PR adds the recovery-state dependency that makes the deferred removal actually re-run, an e2e regression spec, and a hook-parity repin. Co-authored-by: ylcn91 <7249450+ylcn91@users.noreply.github.com> --- ...erminal-live-layout-reconciliation.test.ts | 173 +++++++++++++++++- .../terminal-live-layout-reconciliation.ts | 73 ++++++++ .../terminal-pane-hook-order-parity.test.ts | 6 +- .../use-terminal-pane-reconciliation.ts | 61 +++++- ...mote-split-pane-host-retired-ghost.spec.ts | 142 ++++++++++++++ 5 files changed, 446 insertions(+), 9 deletions(-) create mode 100644 tests/e2e/paired-remote-split-pane-host-retired-ghost.spec.ts diff --git a/src/renderer/src/components/terminal-pane/terminal-live-layout-reconciliation.test.ts b/src/renderer/src/components/terminal-pane/terminal-live-layout-reconciliation.test.ts index 06b321d0d04..814ca8d974f 100644 --- a/src/renderer/src/components/terminal-pane/terminal-live-layout-reconciliation.test.ts +++ b/src/renderer/src/components/terminal-pane/terminal-live-layout-reconciliation.test.ts @@ -1,7 +1,10 @@ import { describe, expect, it } from 'vitest' import { isHostAuthoritativeLayout, - planTerminalLiveLayoutInsertions + planTerminalLiveLayoutInsertions, + planTerminalLiveLayoutRemovals, + selectRetiredPaneIds, + trackRetiredLeafIds } from './terminal-live-layout-reconciliation' import type { TerminalPaneLayoutNode } from '../../../../shared/terminal-tab-types' @@ -232,3 +235,171 @@ describe('planTerminalLiveLayoutInsertions', () => { expect(planTerminalLiveLayoutInsertions(layout, [])).toEqual([]) }) }) + +describe('planTerminalLiveLayoutRemovals', () => { + // Every mounted leaf counted as retired: the layout alone must veto removals. + const BOTH = new Set(['leaf-a', 'leaf-b']) + + it('plans the mounted leaf a host-retired layout no longer names', () => { + // Why: closing one pane of a remote-server split kills its PTY on the host, + // which retires the leaf and republishes a one-leaf layout; the pane mounted + // for the retired leaf must go too, or it lingers as a blank ghost. + const layout: TerminalPaneLayoutNode = { type: 'leaf', leafId: 'leaf-a' } + + expect( + planTerminalLiveLayoutRemovals(layout, ['leaf-a', 'leaf-b'], new Set(['leaf-b'])) + ).toEqual(['leaf-b']) + }) + + it('plans nothing when every mounted leaf is still in the layout', () => { + const layout: TerminalPaneLayoutNode = { + type: 'split', + direction: 'vertical', + first: { type: 'leaf', leafId: 'leaf-a' }, + second: { type: 'leaf', leafId: 'leaf-b' } + } + + expect(planTerminalLiveLayoutRemovals(layout, ['leaf-a', 'leaf-b'], BOTH)).toEqual([]) + expect(planTerminalLiveLayoutRemovals(layout, ['leaf-a'], BOTH)).toEqual([]) + }) + + it('plans nothing for an empty layout', () => { + expect(planTerminalLiveLayoutRemovals(null, ['leaf-a'], BOTH)).toEqual([]) + expect(planTerminalLiveLayoutRemovals(undefined, ['leaf-a'], BOTH)).toEqual([]) + }) + + it('leaves a mounted leaf the host has never named alone', () => { + // Why: a pane the client just split is still spawning, so its transport has + // no PTY yet, and a host snapshot that lands mid-spawn does not name it. + // Only a leaf the host named before can be one the host retired. + const layout: TerminalPaneLayoutNode = { type: 'leaf', leafId: 'leaf-a' } + + expect( + planTerminalLiveLayoutRemovals(layout, ['leaf-a', 'leaf-new'], new Set(['leaf-a'])) + ).toEqual([]) + expect(planTerminalLiveLayoutRemovals(layout, ['leaf-a', 'leaf-new'], new Set())).toEqual([]) + }) +}) + +describe('selectRetiredPaneIds', () => { + const view = (ptyIdsByPane: Record) => ({ + paneCount: Object.keys(ptyIdsByPane).length, + paneIdForLeaf: (leafId: string) => (leafId === 'leaf-b' ? 2 : leafId === 'leaf-c' ? 3 : null), + ptyIdForPane: (paneId: number) => ptyIdsByPane[paneId] + }) + + it('closes the pane whose transport lost its PTY', () => { + // Why: the host retired the leaf because its PTY ended, so a pane that no + // longer has one is exactly the blank ghost the layout stopped naming. + expect(selectRetiredPaneIds(['leaf-b'], view({ 1: 'pty-a', 2: null }))).toEqual([2]) + }) + + it('keeps a pane still bound to a PTY or not yet attached to a transport', () => { + // A stale snapshot may simply not name a live pane yet; a pane with no + // transport is still mounting. Neither is evidence of a retired leaf. + expect(selectRetiredPaneIds(['leaf-b'], view({ 1: 'pty-a', 2: 'pty-b' }))).toEqual([]) + expect(selectRetiredPaneIds(['leaf-b'], view({ 1: 'pty-a', 2: undefined }))).toEqual([]) + }) + + it('never removes the last pane on the tab', () => { + expect(selectRetiredPaneIds(['leaf-b'], view({ 2: null }))).toEqual([]) + expect(selectRetiredPaneIds(['leaf-b', 'leaf-c'], view({ 2: null, 3: null }))).toEqual([2]) + }) + + it('skips a leaf that has no mounted pane', () => { + expect(selectRetiredPaneIds(['leaf-x'], view({ 1: 'pty-a', 2: null }))).toEqual([]) + }) +}) + +describe('trackRetiredLeafIds', () => { + it('retires a mounted leaf the host dropped from its layout', () => { + expect( + trackRetiredLeafIds({ + retiredLeafIds: new Set(), + previousLayoutLeafIds: new Set(['leaf-a', 'leaf-b']), + layoutLeafIds: new Set(['leaf-a']), + mountedLeafIds: ['leaf-a', 'leaf-b'] + }) + ).toEqual(new Set(['leaf-b'])) + }) + + it('keeps a retired leaf until its pane is gone', () => { + // Why: the removal may have been skipped while the transport still held its + // PTY; the next reconciliation must still see the leaf as retired. + const args = { + retiredLeafIds: new Set(['leaf-b']), + previousLayoutLeafIds: new Set(['leaf-a']), + layoutLeafIds: new Set(['leaf-a']) + } + expect(trackRetiredLeafIds({ ...args, mountedLeafIds: ['leaf-a', 'leaf-b'] })).toEqual( + new Set(['leaf-b']) + ) + expect(trackRetiredLeafIds({ ...args, mountedLeafIds: ['leaf-a'] })).toEqual(new Set()) + }) + + it('forgets a retired leaf the host names again', () => { + expect( + trackRetiredLeafIds({ + retiredLeafIds: new Set(['leaf-b']), + previousLayoutLeafIds: new Set(['leaf-a']), + layoutLeafIds: new Set(['leaf-a', 'leaf-b']), + mountedLeafIds: ['leaf-a', 'leaf-b'] + }) + ).toEqual(new Set()) + }) + + it('never retires a leaf the host has not named', () => { + expect( + trackRetiredLeafIds({ + retiredLeafIds: new Set(), + previousLayoutLeafIds: new Set(['leaf-a']), + layoutLeafIds: new Set(['leaf-a']), + mountedLeafIds: ['leaf-a', 'leaf-new'] + }) + ).toEqual(new Set()) + }) +}) + +describe('host retirement that lands before the transport teardown', () => { + it('removes the pane on the reconciliation after its PTY clears', () => { + // Why: the host drops the leaf and ends its PTY in one step, but the two + // reach the client separately. If the layout arrives first the pane still + // holds its PTY and must not be closed yet; once the exit lands and rewrites + // the layout bindings, the effect runs again and must close it then. + const layout: TerminalPaneLayoutNode = { type: 'leaf', leafId: 'leaf-a' } + const mounted = ['leaf-a', 'leaf-b'] + const paneIdForLeaf = (leafId: string) => + leafId === 'leaf-a' ? 1 : leafId === 'leaf-b' ? 2 : null + + let retired = trackRetiredLeafIds({ + retiredLeafIds: new Set(), + previousLayoutLeafIds: new Set(mounted), + layoutLeafIds: new Set(['leaf-a']), + mountedLeafIds: mounted + }) + let removals = planTerminalLiveLayoutRemovals(layout, mounted, retired) + expect(removals).toEqual(['leaf-b']) + expect( + selectRetiredPaneIds(removals, { + paneCount: 2, + paneIdForLeaf, + ptyIdForPane: (paneId) => (paneId === 2 ? 'pty-b' : 'pty-a') + }) + ).toEqual([]) + + retired = trackRetiredLeafIds({ + retiredLeafIds: retired, + previousLayoutLeafIds: new Set(['leaf-a']), + layoutLeafIds: new Set(['leaf-a']), + mountedLeafIds: mounted + }) + removals = planTerminalLiveLayoutRemovals(layout, mounted, retired) + expect( + selectRetiredPaneIds(removals, { + paneCount: 2, + paneIdForLeaf, + ptyIdForPane: (paneId) => (paneId === 2 ? null : 'pty-a') + }) + ).toEqual([2]) + }) +}) diff --git a/src/renderer/src/components/terminal-pane/terminal-live-layout-reconciliation.ts b/src/renderer/src/components/terminal-pane/terminal-live-layout-reconciliation.ts index 7de00009a73..859f6c97168 100644 --- a/src/renderer/src/components/terminal-pane/terminal-live-layout-reconciliation.ts +++ b/src/renderer/src/components/terminal-pane/terminal-live-layout-reconciliation.ts @@ -3,6 +3,7 @@ import type { TerminalPaneSplitDirection } from '../../../../shared/terminal-tab-types' import { isRemoteRuntimePtyId } from '@/runtime/runtime-terminal-inspection' +import { collectLeafIds } from './terminal-pane-layout-tree' /** * Whether a tab's split layout is owned by a host (web/mobile clients, or a @@ -85,6 +86,29 @@ function mountedLeafIdsIn( ] } +/** + * Mounted leaves the host layout no longer names. The host retires a leaf when + * its PTY ends, so a pane still mounted for it is a ghost: it renders nothing + * and, once it is the only pane left, absorbs the tab's next close. An empty + * layout plans nothing — absence of a tree is not evidence about any pane. + */ +export function planTerminalLiveLayoutRemovals( + root: TerminalPaneLayoutNode | null | undefined, + currentLeafIds: Iterable, + retiredLeafIds: ReadonlySet +): string[] { + if (!root) { + return [] + } + const layoutLeafIds = new Set(collectLeafIds(root)) + // Why: a mounted leaf the layout stopped naming is a removal only once the + // host is known to have retired it (trackRetiredLeafIds). A snapshot landing + // while the client is still starting a pane must not read as a retirement. + return [...currentLeafIds].filter( + (leafId) => !layoutLeafIds.has(leafId) && retiredLeafIds.has(leafId) + ) +} + export function planTerminalLiveLayoutInsertions( root: TerminalPaneLayoutNode | null | undefined, currentLeafIds: Iterable @@ -156,3 +180,52 @@ export function planTerminalLiveLayoutInsertions( ensureSubtree(root) return insertions } + +/** Panes to close for leaves the host retired. Only a pane whose transport has + * no PTY any more is a ghost; a pane with no transport yet, or still bound to + * a PTY, may simply not be named by a stale snapshot. The last pane on the tab + * is never removed. */ +export function selectRetiredPaneIds( + retiredLeafIds: readonly string[], + view: { + paneCount: number + paneIdForLeaf: (leafId: string) => number | null + ptyIdForPane: (paneId: number) => string | null | undefined + } +): number[] { + const paneIds: number[] = [] + for (const leafId of retiredLeafIds) { + if (view.paneCount - paneIds.length <= 1) { + break + } + const paneId = view.paneIdForLeaf(leafId) + if (paneId === null || view.ptyIdForPane(paneId) !== null) { + continue + } + paneIds.push(paneId) + } + return paneIds +} + +/** + * Leaves the host dropped from its layout whose panes are still mounted. Only a + * leaf the host named before can be retired: a leaf it has never named belongs + * to a pane the client is still starting. A retired leaf stays retired until + * its pane is gone or the host names it again, so a removal skipped while the + * transport still held its PTY is planned again once that PTY clears. + */ +export function trackRetiredLeafIds(args: { + retiredLeafIds: ReadonlySet + previousLayoutLeafIds: ReadonlySet + layoutLeafIds: ReadonlySet + mountedLeafIds: Iterable +}): ReadonlySet { + const mounted = new Set(args.mountedLeafIds) + const next = new Set() + for (const leafId of [...args.retiredLeafIds, ...args.previousLayoutLeafIds]) { + if (mounted.has(leafId) && !args.layoutLeafIds.has(leafId)) { + next.add(leafId) + } + } + return next +} diff --git a/src/renderer/src/components/terminal-pane/terminal-pane-hook-order-parity.test.ts b/src/renderer/src/components/terminal-pane/terminal-pane-hook-order-parity.test.ts index 80150075f7a..2eb22ecfb03 100644 --- a/src/renderer/src/components/terminal-pane/terminal-pane-hook-order-parity.test.ts +++ b/src/renderer/src/components/terminal-pane/terminal-pane-hook-order-parity.test.ts @@ -16,8 +16,10 @@ const TERMINAL_PANE_HOOK_SOURCE_PATTERN = // toggle in projection (208 hooks, still 8 useMemo). // Then chat-state's orchestration dispatch-status subscription went with the // paused notice that read it (207 hooks, still 8 useMemo). +// Then host-authoritative layout removal added two `useRef`s in reconciliation +// (last host layout leaf set, retired leaf set) (209 hooks, still 8 useMemo). const PRE_REFACTOR_HOOK_ORDER_SHA256 = - '2bbb42427b61e3722114ac37c407230cb7daffbf9b899090c7a635f15731ccad' + 'f6de13ab7d6d130444c50fec2cfe097851ee1b7ecf0f3a2cbdc082c2e8e8838b' const sourceFiles = readdirSync(__dirname) .filter((name) => TERMINAL_PANE_HOOK_SOURCE_PATTERN.test(name)) @@ -82,7 +84,7 @@ function readFlattenedHookOrder(): string[] { describe('TerminalPane refactor hook parity', () => { it('preserves the recursively flattened render hook order', () => { const hooks = readFlattenedHookOrder() - expect(hooks).toHaveLength(207) + expect(hooks).toHaveLength(209) expect(hooks.filter((hook) => hook === 'useMemo')).toHaveLength(8) expect(createHash('sha256').update(hooks.join('\n')).digest('hex')).toBe( PRE_REFACTOR_HOOK_ORDER_SHA256 diff --git a/src/renderer/src/components/terminal-pane/use-terminal-pane-reconciliation.ts b/src/renderer/src/components/terminal-pane/use-terminal-pane-reconciliation.ts index 25e52ad6bcc..879b9509e3f 100644 --- a/src/renderer/src/components/terminal-pane/use-terminal-pane-reconciliation.ts +++ b/src/renderer/src/components/terminal-pane/use-terminal-pane-reconciliation.ts @@ -1,4 +1,4 @@ -import { useEffect, useLayoutEffect } from 'react' +import { useEffect, useLayoutEffect, useRef } from 'react' import { applyExpandedLayoutTo, cancelPendingPaneSizeRefreshFrames, @@ -8,8 +8,12 @@ import { safeFit } from '@/lib/pane-manager/pane-tree-ops' import { resolvePaneKeyForManager } from '@/lib/pane-manager/pane-key-resolution' import { isHostAuthoritativeLayout, - planTerminalLiveLayoutInsertions + planTerminalLiveLayoutInsertions, + planTerminalLiveLayoutRemovals, + selectRetiredPaneIds, + trackRetiredLeafIds } from './terminal-live-layout-reconciliation' +import { collectLeafIds } from './terminal-pane-layout-tree' import { useTerminalPaneProcessExitActions } from './use-terminal-pane-process-exit-actions' import type { TerminalPaneCloseController } from './use-terminal-pane-close-actions' @@ -18,17 +22,25 @@ export function useTerminalPaneReconciliation(controller: TerminalPaneCloseContr activityIsolationSnapshotRef, closeTerminalLinkActions, containerRef, + executeClosePane, isActive, isRendererVisible, isolatedPaneKey, managerRef, paneCount, paneLayoutRevision, + paneTransportsRef, pendingPaneSizeRefreshFrameIdsRef, persistLayoutSnapshot, + ptyRecoveryStatesByPaneId, restoredLayout, tabId } = controller + // Leaves the last host-authoritative layout named, and the ones it has since + // dropped whose panes are still mounted; a removal needs the host to have + // named the leaf before it dropped it, and may have to wait for the PTY exit. + const hostLayoutLeafIdsRef = useRef>(new Set()) + const retiredLeafIdsRef = useRef>(new Set()) useEffect(() => { closeTerminalLinkActions() @@ -47,11 +59,23 @@ export function useTerminalPaneReconciliation(controller: TerminalPaneCloseContr ) { return } - const insertions = planTerminalLiveLayoutInsertions( + const layoutLeafIds = new Set(collectLeafIds(restoredLayout.root)) + const mountedLeafIds = manager.getPanes().map((pane) => pane.leafId) + const retiredLeafIds = trackRetiredLeafIds({ + retiredLeafIds: retiredLeafIdsRef.current, + previousLayoutLeafIds: hostLayoutLeafIdsRef.current, + layoutLeafIds, + mountedLeafIds + }) + hostLayoutLeafIdsRef.current = layoutLeafIds + retiredLeafIdsRef.current = retiredLeafIds + const insertions = planTerminalLiveLayoutInsertions(restoredLayout.root, mountedLeafIds) + const removals = planTerminalLiveLayoutRemovals( restoredLayout.root, - manager.getPanes().map((pane) => pane.leafId) + mountedLeafIds, + retiredLeafIds ) - if (insertions.length === 0) { + if (insertions.length === 0 && removals.length === 0) { return } let appliedInsertion = false @@ -82,6 +106,21 @@ export function useTerminalPaneReconciliation(controller: TerminalPaneCloseContr appliedInsertion = true } } + // Why: the host retired these leaves (its PTY for them ended), so their panes + // would otherwise outlive the layout as blank ghosts and take the tab's next + // close for themselves. selectRetiredPaneIds closes only a pane whose PTY has + // already cleared, so this never kills a still-live remote terminal; a leaf + // whose PTY is still ending is kept retired and removed on the re-run the + // transport's recovery-state change (ptyRecoveryStatesByPaneId) triggers. + // executeClosePane runs the same cleanup a user close does. + const retiredPaneIds = selectRetiredPaneIds(removals, { + paneCount: manager.getPanes().length, + paneIdForLeaf: (leafId) => manager.getNumericIdForLeaf(leafId), + ptyIdForPane: (paneId) => paneTransportsRef.current.get(paneId)?.getPtyId() + }) + for (const paneId of retiredPaneIds) { + executeClosePane(paneId) + } if (appliedInsertion) { persistLayoutSnapshot() } @@ -93,8 +132,18 @@ export function useTerminalPaneReconciliation(controller: TerminalPaneCloseContr if (nextActivePaneId !== null) { manager.setActivePane(nextActivePaneId, { focus: isActive }) } + // Why ptyRecoveryStatesByPaneId: a host-retired pane whose PTY has not yet + // finished ending is kept until this re-run, when its transport reports a new + // recovery state and its PTY has cleared. // oxlint-disable-next-line react-hooks/exhaustive-deps -- Preserve the pre-split dependency contract. - }, [isActive, paneCount, persistLayoutSnapshot, restoredLayout]) + }, [ + executeClosePane, + isActive, + paneCount, + persistLayoutSnapshot, + ptyRecoveryStatesByPaneId, + restoredLayout + ]) useLayoutEffect(() => { const snapshots = activityIsolationSnapshotRef.current diff --git a/tests/e2e/paired-remote-split-pane-host-retired-ghost.spec.ts b/tests/e2e/paired-remote-split-pane-host-retired-ghost.spec.ts new file mode 100644 index 00000000000..c5b4c69d8aa --- /dev/null +++ b/tests/e2e/paired-remote-split-pane-host-retired-ghost.spec.ts @@ -0,0 +1,142 @@ +/** + * Reproduction for #17770: closing one pane of a split terminal in a paired + * remote-server workspace must not leave the other pane mounted as a blank, + * dead ghost. + * + * Topology: a headless paired Orca runtime host + a paired Orca desktop client. + * The host owns the pane layout; the client mirrors it. The host splits a + * terminal (two leaves, two remote PTYs, each a login shell), then the user + * quits the second shell with `exit`. The host retires that leaf and + * republishes a one-leaf layout. + * + * Before the fix, the host-authoritative reconciler planned insertions only, so + * the client kept the retired leaf's pane mounted forever — a blank ghost with + * no exit overlay and no restart control. The refutation-proof shape (verified + * here) is that the client's store layout shrinks to one leaf while its DOM + * keeps two panes. After the fix the client removes the retired pane and store + * + DOM agree at exactly the surviving leaf. + * + * Run: + * pnpm exec playwright test tests/e2e/paired-remote-split-pane-host-retired-ghost.spec.ts \ + * --config tests/playwright.config.ts --project electron-headless --workers=1 + */ +import type { Page } from '@stablyai/playwright-test' +import { toWebTerminalSurfaceTabId } from '../../src/shared/terminal-surface-id' +import { expect, test } from './helpers/orca-app' +import { launchHeadlessPairedRuntimeHost } from './helpers/headless-paired-runtime-host' +import { launchPairedElectronClient } from './helpers/paired-electron-client' +import { findPairedWorktreeId } from './helpers/paired-browser-placement-fixture' + +async function mountedPaneCount(page: Page, webTabId: string): Promise { + return page.evaluate( + (tabId) => window.__paneManagers?.get(tabId)?.getPanes().length ?? -1, + webTabId + ) +} + +async function mountedLeafPtyIds( + page: Page, + webTabId: string +): Promise<{ leafId: string; ptyId: string | null }[]> { + return page.evaluate( + (tabId) => + (window.__paneManagers?.get(tabId)?.getPanes() ?? []).map((pane) => ({ + leafId: pane.leafId, + ptyId: pane.container.dataset.ptyId ?? null + })), + webTabId + ) +} + +/** Leaves the host-authoritative layout the client currently holds for this tab. */ +async function hostLayoutLeafIds(page: Page, webTabId: string): Promise { + return page.evaluate((tabId) => { + const layout = window.__store?.getState().terminalLayoutsByTabId[tabId] + return layout ? Object.keys(layout.ptyIdsByLeafId ?? {}) : [] + }, webTabId) +} + +test('removes the pane a paired remote host retired instead of leaving a dead ghost', async ({ + testRepoPath +}, testInfo) => { + test.setTimeout(240_000) + const host = await launchHeadlessPairedRuntimeHost() + let client: Awaited> | null = null + try { + await host.client.call('repo.add', { path: testRepoPath, kind: 'git' }) + const created = await host.client.call<{ terminal: { handle: string } }>('terminal.create', { + worktree: `path:${testRepoPath}`, + title: 'Ghost Repro' + }) + const firstHandle = created.result.terminal.handle + + client = await launchPairedElectronClient(host.offer, testInfo, '#17770 host-retired ghost') + const worktreeId = await findPairedWorktreeId(client.page, testRepoPath) + await client.page.evaluate( + ({ environmentId, worktreeId }) => { + window.__store?.getState().setActiveWorktree(worktreeId, `runtime:${environmentId}`) + }, + { environmentId: client.environmentId, worktreeId } + ) + + // Host splits the terminal: a second leaf with its own remote login shell. + const split = await host.client.call<{ split: { handle: string; tabId: string } }>( + 'terminal.split', + { terminal: firstHandle, direction: 'horizontal' } + ) + const secondHandle = split.result.split.handle + const webTabId = toWebTerminalSurfaceTabId(split.result.split.tabId) + + // The client mirrors the split as two mounted panes, each PTY-bound. + await expect + .poll(() => mountedPaneCount(client!.page, webTabId), { + timeout: 90_000, + message: 'paired client never materialized both split panes' + }) + .toBe(2) + await expect + .poll(async () => (await mountedLeafPtyIds(client!.page, webTabId)).every((p) => p.ptyId), { + timeout: 30_000, + message: 'split panes never settled with PTY bindings' + }) + .toBe(true) + const beforeExit = await mountedLeafPtyIds(client.page, webTabId) + + // The user quits the second shell — the host retires that leaf and + // republishes a one-leaf layout. + await host.client.call('terminal.send', { terminal: secondHandle, text: 'exit', enter: true }) + + // The host-authoritative layout the client holds shrinks to one leaf + // (confirms the retirement). This is the refutation-proof signal: before the + // fix the store layout shrinks here while the DOM keeps a ghost; after the + // fix the DOM follows and both agree at one leaf. + await expect + .poll(() => hostLayoutLeafIds(client!.page, webTabId).then((ids) => ids.length), { + timeout: 60_000, + message: 'host never retired the exited split leaf from its published layout' + }) + .toBe(1) + + // The client must drop the retired pane and keep exactly the surviving one. + await expect + .poll(() => mountedPaneCount(client!.page, webTabId), { + timeout: 60_000, + message: 'paired client kept the retired pane mounted as a dead ghost' + }) + .toBe(1) + + const afterExit = await mountedLeafPtyIds(client.page, webTabId) + const exitedLeafId = beforeExit.find( + (p) => !afterExit.some((a) => a.leafId === p.leafId) + )?.leafId + expect(afterExit).toHaveLength(1) + expect(afterExit[0]?.leafId).toBeTruthy() + expect(afterExit[0]?.ptyId).toBeTruthy() + expect(exitedLeafId).toBeTruthy() + // The pane that survives is the one the host still names. + await expect(hostLayoutLeafIds(client.page, webTabId)).resolves.toEqual([afterExit[0]?.leafId]) + } finally { + await client?.dispose() + await host.dispose() + } +}) From 53852c9ca4a34e741d68115caa474ebb622bed4e Mon Sep 17 00:00:00 2001 From: Neil <4138956+nwparker@users.noreply.github.com> Date: Tue, 8 Sep 2026 00:39:33 -0700 Subject: [PATCH 04/59] feat(terminal): make the contrast floor user-configurable (#10754) (#18126) * feat(terminal): make the contrast floor user-configurable (#10754) The xterm minimumContrastRatio floor was hardcoded (3 on dark backgrounds, 4.5 on light) and applied to every pane with no way out, so TUIs that use deliberately low contrast were rewritten: Powerline separators drawn in the neighbouring segment's background became visible seams, and dimmed secondary text lost its hierarchy. Adds an optional `terminalMinimumContrastRatio` setting under Settings -> Terminal -> Rendering. Blank keeps today's automatic, background-luminance gated floor; 1 disables correction entirely (matching VS Code's documented `terminal.integrated.minimumContrastRatio` and iTerm2's off-by-default Minimum Contrast); values are clamped to xterm's 1-21 range. The floor is resolved in one place, so live panes, the Appearance preview and the dashboard terminal preview all follow it, and the existing value-gated write still avoids clearing xterm's contrast cache on no-op re-applies. The clamp also lives at the persistence boundary that every writer crosses, so a hand-edited profile or CLI write can never hand xterm a non-finite option. Mobile mirrors the desktop gate, so the resolved floor travels with the terminal theme payload as a new optional field; hosts that omit it leave older and newer clients on the luminance gate. Fixes #10754. Co-authored-by: Nyanako <44753291+Nanako0129@users.noreply.github.com> * fix(terminal): refresh mobile payload fixture and clarify contrast target * feat(terminal): make contrast controls intent-based with custom tuning --------- Co-authored-by: Nyanako <44753291+Nanako0129@users.noreply.github.com> Co-authored-by: m4air --- .../terminal-webview-payload-hash.test.ts | 4 +- .../terminal-webview-theme-injected.test.ts | 39 +++++ .../terminal-webview-theme-injected.ts | 17 ++- .../settings-update-terminal-contrast.test.ts | 74 ++++++++++ .../applying-settings/settings-update.ts | 8 + .../preview-terminal-options.test.ts | 37 +++++ .../preview-terminal-options.ts | 3 +- ...SettingsFormControls.number-field.test.tsx | 86 +++++++++++ .../settings/SettingsFormControls.tsx | 14 +- .../settings/TerminalContrastSetting.test.tsx | 66 +++++++++ .../settings/TerminalContrastSetting.tsx | 137 ++++++++++++++++++ .../settings/TerminalRenderingSection.tsx | 3 + .../settings/TerminalSettingsPreview.tsx | 10 +- .../src/components/settings/setting-labels.ts | 1 + .../settings/terminal-typography-search.ts | 49 +++++++ .../terminal-pane/terminal-appearance.test.ts | 40 +++++ .../terminal-pane/terminal-appearance.ts | 3 +- src/renderer/src/i18n/locales/en.json | 38 ++++- .../lib/terminal-contrast-correction.test.ts | 60 ++++++++ .../src/lib/terminal-contrast-correction.ts | 16 +- .../mobile-terminal-theme.test.ts | 48 ++++++ .../mobile-terminal-theme.ts | 11 +- src/shared/global-settings-types.ts | 4 + .../runtime-mobile-session-tab-contracts.ts | 3 + .../terminal-minimum-contrast-settings.ts | 16 ++ 25 files changed, 775 insertions(+), 12 deletions(-) create mode 100644 src/main/persistence/applying-settings/settings-update-terminal-contrast.test.ts create mode 100644 src/renderer/src/components/settings/SettingsFormControls.number-field.test.tsx create mode 100644 src/renderer/src/components/settings/TerminalContrastSetting.test.tsx create mode 100644 src/renderer/src/components/settings/TerminalContrastSetting.tsx create mode 100644 src/renderer/src/runtime/sync-runtime-graph/mobile-terminal-theme.test.ts create mode 100644 src/shared/terminal-minimum-contrast-settings.ts diff --git a/mobile/src/terminal/terminal-webview-payload-hash.test.ts b/mobile/src/terminal/terminal-webview-payload-hash.test.ts index f8bfa4bd134..66cd2735ea2 100644 --- a/mobile/src/terminal/terminal-webview-payload-hash.test.ts +++ b/mobile/src/terminal/terminal-webview-payload-hash.test.ts @@ -6,8 +6,8 @@ import { XTERM_HTML } from './terminal-webview-html' // uncovered region ships silently. A diff here means the emitted WebView source changed — // update these values only when that change is deliberate, and only after checking the // document still runs. Refactors that merely move slice boundaries must leave them alone. -const EXPECTED_SHA256 = '42cc000faddc3b58b8fd4855f848c7878f0cd6166c613f66d733645e8e1b9608' -const EXPECTED_LENGTH = 729776 +const EXPECTED_SHA256 = '5c69dce3236662c381abbfb5d2d6b7163e0f4dd6841d72753733f9470326fee3' +const EXPECTED_LENGTH = 730428 describe('terminal WebView payload', () => { it('composes the expected document', () => { diff --git a/mobile/src/terminal/terminal-webview-theme-injected.test.ts b/mobile/src/terminal/terminal-webview-theme-injected.test.ts index 92e4127b2fc..d0947ef3e92 100644 --- a/mobile/src/terminal/terminal-webview-theme-injected.test.ts +++ b/mobile/src/terminal/terminal-webview-theme-injected.test.ts @@ -76,4 +76,43 @@ describe('mobile terminal-webview contrast floor gate', () => { context.applyTerminalTheme({ theme: { background: '#1e242a' } }) expect(term.options.minimumContrastRatio).toBe(DARK_FLOOR) }) + + // #10754: the desktop user can lower or disable the floor. Mobile mirrors the desktop gate, so the + // published value has to win here or the same session renders differently on the phone. + describe('published desktop override', () => { + function applyOn(term: { options: { minimumContrastRatio: number } }, input: unknown): void { + const context = loadThemeInjected({ + term, + document: { + documentElement: { style: { background: '' } }, + body: { style: { background: '' } } + } + }) as Record & { applyTerminalTheme: (input: unknown) => void } + context.applyTerminalTheme(input) + } + + it('uses the published floor instead of the luminance gate', () => { + const term = { options: { minimumContrastRatio: 0 } } + applyOn(term, { theme: { background: '#1e242a' }, minimumContrastRatio: 1 }) + expect(term.options.minimumContrastRatio).toBe(1) + }) + + it("clamps a published floor to xterm's 1-21 window", () => { + const term = { options: { minimumContrastRatio: 0 } } + applyOn(term, { theme: { background: '#1e242a' }, minimumContrastRatio: 99 }) + expect(term.options.minimumContrastRatio).toBe(21) + applyOn(term, { theme: { background: '#1e242a' }, minimumContrastRatio: 0 }) + expect(term.options.minimumContrastRatio).toBe(1) + }) + + it('falls back to the luminance gate for an older host that omits the field', () => { + const term = { options: { minimumContrastRatio: 0 } } + for (const published of [undefined, null, 'off', Number.NaN]) { + applyOn(term, { theme: { background: '#1e242a' }, minimumContrastRatio: published }) + expect(term.options.minimumContrastRatio).toBe(DARK_FLOOR) + applyOn(term, { theme: { background: '#ffffff' }, minimumContrastRatio: published }) + expect(term.options.minimumContrastRatio).toBe(LIGHT_FLOOR) + } + }) + }) }) diff --git a/mobile/src/terminal/terminal-webview-theme-injected.ts b/mobile/src/terminal/terminal-webview-theme-injected.ts index c2d9beb4786..98489b219c7 100644 --- a/mobile/src/terminal/terminal-webview-theme-injected.ts +++ b/mobile/src/terminal/terminal-webview-theme-injected.ts @@ -5,7 +5,8 @@ import { colors } from '../theme/mobile-theme' // #7934/#10104): a dark composed background gets a mild floor of 3 to rescue near-background body text // (e.g. Antigravity's #262b30 on #1e242a) without over-brightening vibrant ANSI colors; a light // background keeps the WCAG-AA 4.5 floor. Gate on the composed background luminance, not app mode, -// because either theme slot can hold either kind of theme. +// because either theme slot can hold either kind of theme. An explicit desktop override published on +// the theme payload (#10754) wins over the luminance gate; older hosts simply omit it. export const TERMINAL_WEBVIEW_THEME_JS = ` var DARK_BG_MIN_CONTRAST = 3; var LIGHT_BG_MIN_CONTRAST = 4.5; @@ -63,6 +64,12 @@ export const TERMINAL_WEBVIEW_THEME_JS = ` return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05); } + // Clamp an explicit desktop override to xterm's 1-21 range; null means "no usable override". + function normalizeTerminalContrastOverride(value) { + if (typeof value !== 'number' || !isFinite(value)) return null; + return Math.min(21, Math.max(1, value)); + } + // Pick the xterm minimumContrastRatio floor from the composed terminal background. // Unparseable input defaults to the dark floor so agent output never stays invisible. function resolveTerminalContrastFloor(background) { @@ -100,7 +107,13 @@ export const TERMINAL_WEBVIEW_THEME_JS = ` var background = terminalTheme.background || '${colors.terminalBg}'; document.documentElement.style.background = background; document.body.style.background = background; - terminalMinimumContrastRatio = resolveTerminalContrastFloor(background); + // Why prefer the published value: the desktop user may have lowered or disabled the floor (#10754); + // an older host omits the field and the luminance gate stays authoritative. + var publishedFloor = normalizeTerminalContrastOverride( + input && typeof input === 'object' ? input.minimumContrastRatio : undefined + ); + terminalMinimumContrastRatio = + publishedFloor === null ? resolveTerminalContrastFloor(background) : publishedFloor; if (term) { term.options.theme = terminalTheme; term.options.minimumContrastRatio = terminalMinimumContrastRatio; diff --git a/src/main/persistence/applying-settings/settings-update-terminal-contrast.test.ts b/src/main/persistence/applying-settings/settings-update-terminal-contrast.test.ts new file mode 100644 index 00000000000..7de32d7b36d --- /dev/null +++ b/src/main/persistence/applying-settings/settings-update-terminal-contrast.test.ts @@ -0,0 +1,74 @@ +import { describe, expect, it, vi } from 'vitest' +import type { PersistedState } from '../../../shared/persisted-state-types' +import { updateSettings, type SettingsMutationOperations } from './settings-update' + +function makeOperations(): SettingsMutationOperations { + return { + // Only the fields updateSettings reads; the rest of GlobalSettings is irrelevant to the clamp. + state: { settings: { terminalFontSize: 14 }, repos: [] } as unknown as PersistedState, + bumpLocalWorktreeScanGeneration: vi.fn(), + removeRetainedBlob: vi.fn(), + scheduleSave: vi.fn(), + notifySettingsChanged: vi.fn() + } +} + +// #10754: desktop IPC, the web RPC and the CLI all reach the store through this boundary, and xterm +// throws on a non-finite minimumContrastRatio, so the clamp cannot live in the settings UI alone. +describe('updateSettings terminalMinimumContrastRatio', () => { + it('persists an in-range floor unchanged', () => { + const operations = makeOperations() + + expect( + updateSettings(operations, { terminalMinimumContrastRatio: 1 }).terminalMinimumContrastRatio + ).toBe(1) + expect( + updateSettings(operations, { terminalMinimumContrastRatio: 4.5 }).terminalMinimumContrastRatio + ).toBe(4.5) + }) + + it('clamps a hand-edited value into xterm range', () => { + const operations = makeOperations() + + expect( + updateSettings(operations, { terminalMinimumContrastRatio: 0 }).terminalMinimumContrastRatio + ).toBe(1) + expect( + updateSettings(operations, { terminalMinimumContrastRatio: 500 }).terminalMinimumContrastRatio + ).toBe(21) + }) + + it('drops an unusable value back to automatic rather than storing it', () => { + const operations = makeOperations() + + expect( + updateSettings(operations, { + terminalMinimumContrastRatio: Number.NaN + }).terminalMinimumContrastRatio + ).toBeUndefined() + expect( + updateSettings(operations, { + terminalMinimumContrastRatio: 'off' as unknown as number + }).terminalMinimumContrastRatio + ).toBeUndefined() + }) + + it('clears the override so the automatic floor comes back', () => { + const operations = makeOperations() + + updateSettings(operations, { terminalMinimumContrastRatio: 1 }) + expect( + updateSettings(operations, { terminalMinimumContrastRatio: undefined }) + .terminalMinimumContrastRatio + ).toBeUndefined() + }) + + it('leaves a stored floor alone when an unrelated setting is written', () => { + const operations = makeOperations() + + updateSettings(operations, { terminalMinimumContrastRatio: 1 }) + expect(updateSettings(operations, { terminalFontSize: 15 }).terminalMinimumContrastRatio).toBe( + 1 + ) + }) +}) diff --git a/src/main/persistence/applying-settings/settings-update.ts b/src/main/persistence/applying-settings/settings-update.ts index 20614061bdd..e8a080763da 100644 --- a/src/main/persistence/applying-settings/settings-update.ts +++ b/src/main/persistence/applying-settings/settings-update.ts @@ -9,6 +9,7 @@ import { normalizeTerminalQuickCommands } from '../../../shared/terminal-quick-c import { normalizeTerminalCustomThemes } from '../../../shared/terminal-custom-themes' import { normalizeTerminalCursorStyleDefault } from '../../../shared/terminal-cursor-style-settings' import { normalizeDesktopTerminalScrollbackRows } from '../../../shared/terminal-scrollback-policy' +import { normalizeTerminalMinimumContrastRatio } from '../../../shared/terminal-minimum-contrast-settings' import { normalizeTaskProviderSettings } from '../../../shared/task-providers' import { normalizeOpenInApplications } from '../../../shared/open-in-applications' import { normalizeTerminalShortcutPolicy } from '../../../shared/keybindings' @@ -123,6 +124,13 @@ export function updateSettings( updates.terminalScrollbackRows ) } + // Why here: every writer (desktop IPC, web RPC, CLI) crosses this boundary, so xterm can never be + // handed an out-of-range floor, and undefined stays undefined to mean "automatic" (#10754). + if ('terminalMinimumContrastRatio' in updates) { + sanitizedUpdates.terminalMinimumContrastRatio = normalizeTerminalMinimumContrastRatio( + updates.terminalMinimumContrastRatio + ) + } if ( 'terminalTuiScrollSensitivity' in updates || 'terminalTuiScrollSensitivityDefaultedToOne' in updates diff --git a/src/renderer/src/components/dashboard-popout/preview-terminal-options.test.ts b/src/renderer/src/components/dashboard-popout/preview-terminal-options.test.ts index 319ec241293..2ad4147d235 100644 --- a/src/renderer/src/components/dashboard-popout/preview-terminal-options.test.ts +++ b/src/renderer/src/components/dashboard-popout/preview-terminal-options.test.ts @@ -58,6 +58,43 @@ describe('buildPreviewTerminalOptions', () => { scrollback: 1000 } + // #10754: the dashboard preview renders the agent's live buffer, so it has to reproduce the same + // contrast floor the pane used or a Powerline statusline looks different in the popout. + it('mirrors the automatic contrast floor when no override is set', () => { + expect( + buildPreviewTerminalOptions({ + ...base, + terminalInput: null, + theme: { background: '#1e242a' } + }).minimumContrastRatio + ).toBe(3) + expect( + buildPreviewTerminalOptions({ + ...base, + terminalInput: null, + theme: { background: '#ffffff' }, + themeMode: 'light' + }).minimumContrastRatio + ).toBe(4.5) + }) + + it('honors the user contrast override, clamped to xterm range', () => { + expect( + buildPreviewTerminalOptions({ + ...base, + terminalInput: null, + settings: { ...SETTINGS, terminalMinimumContrastRatio: 1 } + }).minimumContrastRatio + ).toBe(1) + expect( + buildPreviewTerminalOptions({ + ...base, + terminalInput: null, + settings: { ...SETTINGS, terminalMinimumContrastRatio: 0 } + }).minimumContrastRatio + ).toBe(1) + }) + it('keeps the kitty advertisement and skips ConPTY options off Windows', () => { const options = buildPreviewTerminalOptions({ ...base, diff --git a/src/renderer/src/components/dashboard-popout/preview-terminal-options.ts b/src/renderer/src/components/dashboard-popout/preview-terminal-options.ts index 284f6510558..14fe851a657 100644 --- a/src/renderer/src/components/dashboard-popout/preview-terminal-options.ts +++ b/src/renderer/src/components/dashboard-popout/preview-terminal-options.ts @@ -80,7 +80,8 @@ export function buildPreviewTerminalOptions(args: { theme: args.theme ?? undefined, minimumContrastRatio: resolveTerminalMinimumContrastRatio( args.theme?.background, - args.themeMode + args.themeMode, + args.settings?.terminalMinimumContrastRatio ) } } diff --git a/src/renderer/src/components/settings/SettingsFormControls.number-field.test.tsx b/src/renderer/src/components/settings/SettingsFormControls.number-field.test.tsx new file mode 100644 index 00000000000..4b8b2ff1bae --- /dev/null +++ b/src/renderer/src/components/settings/SettingsFormControls.number-field.test.tsx @@ -0,0 +1,86 @@ +// @vitest-environment happy-dom +import { cleanup, fireEvent, render, screen } from '@testing-library/react' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { NumberField } from './SettingsFormControls' + +afterEach(cleanup) + +// #10754: an optional setting needs a way back to "unset". Without a clear path the field can pin a +// value but never restore Orca's automatic behavior, which is the state most users should be in. +describe('NumberField clearable fields', () => { + it('renders the placeholder and commits nothing while the value is unset', () => { + render( + + ) + + const input = screen.getByLabelText('Minimum Contrast Ratio') as HTMLInputElement + expect(input.value).toBe('') + expect(input.getAttribute('placeholder')).toBe('Auto') + }) + + it('clears the setting when the field is emptied', () => { + const onChange = vi.fn() + const onClear = vi.fn() + render( + + ) + + const input = screen.getByLabelText('Minimum Contrast Ratio') + fireEvent.change(input, { target: { value: '' } }) + fireEvent.blur(input) + + expect(onClear).toHaveBeenCalledTimes(1) + expect(onChange).not.toHaveBeenCalled() + }) + + it('still snaps back to the current value when the field is not clearable', () => { + const onChange = vi.fn() + render() + + const input = screen.getByLabelText('Font Size') as HTMLInputElement + fireEvent.change(input, { target: { value: '' } }) + fireEvent.blur(input) + + expect(onChange).not.toHaveBeenCalled() + expect(input.value).toBe('14') + }) + + it('clamps a committed value into the min/max window', () => { + const onChange = vi.fn() + render( + + ) + + const input = screen.getByLabelText('Minimum Contrast Ratio') + fireEvent.change(input, { target: { value: '99' } }) + fireEvent.blur(input) + + expect(onChange).toHaveBeenCalledWith(21) + }) +}) diff --git a/src/renderer/src/components/settings/SettingsFormControls.tsx b/src/renderer/src/components/settings/SettingsFormControls.tsx index 9a0993849f6..ef374619344 100644 --- a/src/renderer/src/components/settings/SettingsFormControls.tsx +++ b/src/renderer/src/components/settings/SettingsFormControls.tsx @@ -262,13 +262,17 @@ type ColorFieldProps = { type NumberFieldProps = { label: string description: string - value: number + /** undefined renders the field empty — pair it with `placeholder` and `onClear` for an unset state. */ + value: number | undefined defaultValue?: number min: number max?: number step?: number integer?: boolean onChange: (value: number) => void + /** When set, emptying the field clears the setting instead of snapping back to the current value. */ + onClear?: () => void + placeholder?: string suffix?: string className?: string } @@ -316,6 +320,8 @@ export function NumberField({ step = 1, integer = false, onChange, + onClear, + placeholder, suffix, className }: NumberFieldProps): React.JSX.Element { @@ -331,6 +337,11 @@ export function NumberField({ const commit = (): void => { const trimmed = draft.trim() if (trimmed === '') { + if (onClear) { + // Clearable fields treat empty as "unset" so the caller can fall back to its automatic value. + onClear() + return + } // Empty input — reset to current value rather than committing 0 setDraft(Number.isFinite(value) ? String(value) : '') return @@ -369,6 +380,7 @@ export function NumberField({ max={max} step={step} aria-label={label} + placeholder={placeholder} value={draft} onChange={(e) => setDraft(e.target.value)} onBlur={commit} diff --git a/src/renderer/src/components/settings/TerminalContrastSetting.test.tsx b/src/renderer/src/components/settings/TerminalContrastSetting.test.tsx new file mode 100644 index 00000000000..41739d8bb2d --- /dev/null +++ b/src/renderer/src/components/settings/TerminalContrastSetting.test.tsx @@ -0,0 +1,66 @@ +// @vitest-environment happy-dom +import { useState } from 'react' +import { cleanup, fireEvent, render, screen } from '@testing-library/react' +import { afterEach, describe, expect, it, vi } from 'vitest' +import type { GlobalSettings } from '../../../../shared/global-settings-types' +import { TerminalContrastSetting } from './TerminalContrastSetting' + +vi.mock('./SearchableSetting', () => ({ SearchableSetting: ({ children }) => children })) +afterEach(cleanup) + +function mount(initial: number | undefined = undefined): ReturnType { + const persist = vi.fn() + function Harness(): React.JSX.Element { + const [settings, setSettings] = useState({ + terminalMinimumContrastRatio: initial + } as GlobalSettings) + return ( + { + persist(patch) + setSettings((previous) => ({ ...previous, ...patch })) + }} + /> + ) + } + render() + return persist +} + +describe('terminal contrast modes', () => { + it('lets users turn correction off and restore automatic without editing a number', () => { + const persist = mount() + expect(screen.getByRole('radio', { name: 'Automatic' }).getAttribute('aria-checked')).toBe( + 'true' + ) + expect(screen.queryByRole('spinbutton')).toBeNull() + fireEvent.click(screen.getByRole('radio', { name: 'Off' })) + expect(persist).toHaveBeenLastCalledWith({ terminalMinimumContrastRatio: 1 }) + expect(screen.queryByRole('spinbutton')).toBeNull() + fireEvent.click(screen.getByRole('radio', { name: 'Automatic' })) + expect(persist).toHaveBeenLastCalledWith({ terminalMinimumContrastRatio: undefined }) + }) + + it('restores the custom target when toggling through off and automatic', () => { + const persist = mount(7) + fireEvent.click(screen.getByRole('radio', { name: 'Off' })) + fireEvent.click(screen.getByRole('radio', { name: 'Automatic' })) + fireEvent.click(screen.getByRole('radio', { name: 'Custom' })) + expect(persist).toHaveBeenLastCalledWith({ terminalMinimumContrastRatio: 7 }) + expect((screen.getByRole('spinbutton') as HTMLInputElement).value).toBe('7') + }) + + it('starts custom at a usable target and bounds precise input', () => { + const persist = mount() + fireEvent.click(screen.getByRole('radio', { name: 'Custom' })) + expect(persist).toHaveBeenLastCalledWith({ terminalMinimumContrastRatio: 4.5 }) + const input = screen.getByRole('spinbutton') + fireEvent.change(input, { target: { value: '99' } }) + fireEvent.blur(input) + expect(persist).toHaveBeenLastCalledWith({ terminalMinimumContrastRatio: 21 }) + fireEvent.change(input, { target: { value: '1' } }) + fireEvent.blur(input) + expect(screen.getByRole('radio', { name: 'Off' }).getAttribute('aria-checked')).toBe('true') + }) +}) diff --git a/src/renderer/src/components/settings/TerminalContrastSetting.tsx b/src/renderer/src/components/settings/TerminalContrastSetting.tsx new file mode 100644 index 00000000000..174979602f2 --- /dev/null +++ b/src/renderer/src/components/settings/TerminalContrastSetting.tsx @@ -0,0 +1,137 @@ +import { useRef, useState } from 'react' +import type { GlobalSettings } from '../../../../shared/global-settings-types' +import { Slider } from '../ui/slider' +import { NumberField, SettingsRow, SettingsSegmentedControl } from './SettingsFormControls' +import { SearchableSetting } from './SearchableSetting' +import { + LIGHT_BG_MIN_CONTRAST, + MIN_TERMINAL_CONTRAST_RATIO, + MAX_TERMINAL_CONTRAST_RATIO, + normalizeTerminalMinimumContrastRatio +} from '@/lib/terminal-contrast-correction' +import { translate } from '@/i18n/i18n' + +type ContrastMode = 'auto' | 'off' | 'custom' + +type Props = { + settings: GlobalSettings + updateSettings: (updates: Partial) => void +} + +export function TerminalContrastSetting({ settings, updateSettings }: Props): React.JSX.Element { + const value = normalizeTerminalMinimumContrastRatio(settings.terminalMinimumContrastRatio) + const mode: ContrastMode = value === undefined ? 'auto' : value === 1 ? 'off' : 'custom' + const lastCustomValue = useRef(LIGHT_BG_MIN_CONTRAST) + const [draft, setDraft] = useState(value ?? LIGHT_BG_MIN_CONTRAST) + const [previousValue, setPreviousValue] = useState(value) + if (value !== previousValue) { + setPreviousValue(value) + setDraft(value ?? LIGHT_BG_MIN_CONTRAST) + } + const title = translate('auto.components.settings.contrast.title', 'Color Contrast') + const description = translate( + 'auto.components.settings.contrast.description', + 'Improve text readability or preserve the colors chosen by terminal programs.' + ) + const ratioLabel = translate('auto.components.settings.contrast.ratio', 'Contrast target') + const selectMode = (next: ContrastMode): void => { + if (mode === 'custom' && value !== undefined) { + lastCustomValue.current = value + } + updateSettings({ + terminalMinimumContrastRatio: + next === 'auto' ? undefined : next === 'off' ? 1 : lastCustomValue.current + }) + } + + return ( + + + ariaLabel={title} + value={mode} + onChange={selectMode} + options={[ + { + value: 'auto', + label: translate('auto.components.settings.contrast.auto', 'Automatic') + }, + { value: 'off', label: translate('auto.components.settings.contrast.off', 'Off') }, + { + value: 'custom', + label: translate('auto.components.settings.contrast.custom', 'Custom') + } + ]} + /> + } + /> + {mode === 'custom' && ( +
+ updateSettings({ terminalMinimumContrastRatio: ratio })} + /> + setDraft(ratio)} + onValueCommit={([ratio]) => updateSettings({ terminalMinimumContrastRatio: ratio })} + /> +
+ {translate('auto.components.settings.contrast.subtle', 'Subtle')} + {translate('auto.components.settings.contrast.strong', 'Strong')} +
+
+ )} + + ) +} diff --git a/src/renderer/src/components/settings/TerminalRenderingSection.tsx b/src/renderer/src/components/settings/TerminalRenderingSection.tsx index 47e3017d353..b4031e8f7a4 100644 --- a/src/renderer/src/components/settings/TerminalRenderingSection.tsx +++ b/src/renderer/src/components/settings/TerminalRenderingSection.tsx @@ -5,6 +5,7 @@ import { SettingsSubsectionHeader } from './SettingsFormControls' import { SearchableSetting } from './SearchableSetting' +import { TerminalContrastSetting } from './TerminalContrastSetting' import { translate } from '@/i18n/i18n' type TerminalRenderingSectionProps = { @@ -91,6 +92,8 @@ export function TerminalRenderingSection({ } /> + + ) diff --git a/src/renderer/src/components/settings/TerminalSettingsPreview.tsx b/src/renderer/src/components/settings/TerminalSettingsPreview.tsx index b3a881f9cd0..e597a47173c 100644 --- a/src/renderer/src/components/settings/TerminalSettingsPreview.tsx +++ b/src/renderer/src/components/settings/TerminalSettingsPreview.tsx @@ -206,7 +206,8 @@ export function TerminalSettingsPreview({ // Why: share applyTerminalAppearance's gating helper (#7934) so the preview can't drift from live panes. terminal.options.minimumContrastRatio = resolveTerminalMinimumContrastRatio( composedTheme.background, - effectiveMode + effectiveMode, + settings.terminalMinimumContrastRatio ) // Why: xterm renders an alpha-channel background opaque unless allowTransparency is set (matches applyTerminalAppearance). terminal.options.allowTransparency = @@ -218,7 +219,12 @@ export function TerminalSettingsPreview({ // Why reset() not clear(): buffer ends mid-line on the prompt, so clear()+write would duplicate the trailing fragment. terminal.reset() terminal.write(PREVIEW_BUFFER) - }, [composedTheme, effectiveMode, settings.terminalBackgroundOpacity]) + }, [ + composedTheme, + effectiveMode, + settings.terminalBackgroundOpacity, + settings.terminalMinimumContrastRatio + ]) useEffect(() => { const terminal = terminalRef.current diff --git a/src/renderer/src/components/settings/setting-labels.ts b/src/renderer/src/components/settings/setting-labels.ts index c2cec96322f..e46e35bf4e4 100644 --- a/src/renderer/src/components/settings/setting-labels.ts +++ b/src/renderer/src/components/settings/setting-labels.ts @@ -10,6 +10,7 @@ export const SETTING_LABELS: Partial> = { terminalFastScrollSensitivity: 'Fast Scroll Speed', terminalTuiScrollSensitivity: 'TUI Scroll Speed', terminalBackgroundOpacity: 'Background Opacity', + terminalMinimumContrastRatio: 'Color Contrast', terminalCursorStyle: 'Cursor Style', terminalCursorBlink: 'Cursor Blink', terminalCursorOpacity: 'Cursor Opacity', diff --git a/src/renderer/src/components/settings/terminal-typography-search.ts b/src/renderer/src/components/settings/terminal-typography-search.ts index 02fe124d25f..6a4c378fb83 100644 --- a/src/renderer/src/components/settings/terminal-typography-search.ts +++ b/src/renderer/src/components/settings/terminal-typography-search.ts @@ -128,6 +128,55 @@ export const getTerminalRenderingSearchEntries = createLocalizedCatalog(() => [ ...translateSearchKeyword('auto.components.settings.terminal.search.7d924d870d', 'graphics'), ...translateSearchKeyword('auto.components.settings.terminal.search.1abcf4d7de', 'linux') ] + }, + { + title: translate( + 'auto.components.settings.terminal.search.minimumContrast.title', + 'Color Contrast' + ), + description: translate( + 'auto.components.settings.terminal.search.minimumContrast.description', + 'Improve text readability or preserve the colors chosen by terminal programs.' + ), + keywords: [ + ...translateSearchKeyword('auto.components.settings.terminal.search.f66a7cf715', 'terminal'), + ...translateSearchKeyword( + 'auto.components.settings.terminal.search.minimumContrast.contrast', + 'contrast' + ), + ...translateSearchKeyword( + 'auto.components.settings.terminal.search.minimumContrast.minimum', + 'minimum' + ), + ...translateSearchKeyword( + 'auto.components.settings.terminal.search.minimumContrast.ratio', + 'ratio' + ), + ...translateSearchKeyword( + 'auto.components.settings.terminal.search.minimumContrast.readability', + 'readability' + ), + ...translateSearchKeyword( + 'auto.components.settings.terminal.search.minimumContrast.wcag', + 'wcag' + ), + ...translateSearchKeyword( + 'auto.components.settings.terminal.search.minimumContrast.powerline', + 'powerline' + ), + ...translateSearchKeyword( + 'auto.components.settings.terminal.search.minimumContrast.statusline', + 'statusline' + ), + ...translateSearchKeyword( + 'auto.components.settings.terminal.search.minimumContrast.dim', + 'dim' + ), + ...translateSearchKeyword( + 'auto.components.settings.terminal.search.minimumContrast.colors', + 'colors' + ) + ] } ]) diff --git a/src/renderer/src/components/terminal-pane/terminal-appearance.test.ts b/src/renderer/src/components/terminal-pane/terminal-appearance.test.ts index 6f7bec8592b..ce259c5d04d 100644 --- a/src/renderer/src/components/terminal-pane/terminal-appearance.test.ts +++ b/src/renderer/src/components/terminal-pane/terminal-appearance.test.ts @@ -268,6 +268,46 @@ describe('applyTerminalAppearance theme assignment', () => { expect(pane.terminal.options.minimumContrastRatio).toBe(4.5) }) + // #10754: a Powerline statusline draws its segment separators in the neighbouring segment's + // background color, so the automatic floor turns every invisible seam into a bright line. + it('lets the user setting disable contrast correction on a dark theme', () => { + const pane = makePane(1) + const settings = getDefaultSettings('/tmp') + + apply(pane, { ...settings, theme: 'dark', terminalMinimumContrastRatio: 1 }) + + expect(pane.terminal.options.minimumContrastRatio).toBe(1) + }) + + it('lets the user setting override the light-background floor as well', () => { + const pane = makePane(1) + const settings = getDefaultSettings('/tmp') + + apply(pane, { ...settings, theme: 'light', terminalMinimumContrastRatio: 1 }) + + expect(pane.terminal.options.minimumContrastRatio).toBe(1) + }) + + it('clamps an out-of-range user setting before it reaches xterm', () => { + const pane = makePane(1) + const settings = getDefaultSettings('/tmp') + + apply(pane, { ...settings, theme: 'dark', terminalMinimumContrastRatio: 99 }) + + expect(pane.terminal.options.minimumContrastRatio).toBe(21) + }) + + it('returns to the automatic floor when the user setting is cleared live', () => { + const pane = makePane(1) + const settings = getDefaultSettings('/tmp') + + apply(pane, { ...settings, theme: 'dark', terminalMinimumContrastRatio: 1 }) + expect(pane.terminal.options.minimumContrastRatio).toBe(1) + + apply(pane, { ...settings, theme: 'dark', terminalMinimumContrastRatio: undefined }) + expect(pane.terminal.options.minimumContrastRatio).toBe(3) + }) + it('skips the minimumContrastRatio write on a no-op re-apply (preserves xterm contrast cache)', () => { const pane = makePane(1) let writes = 0 diff --git a/src/renderer/src/components/terminal-pane/terminal-appearance.ts b/src/renderer/src/components/terminal-pane/terminal-appearance.ts index a5aa36568ca..6b589e7a6dd 100644 --- a/src/renderer/src/components/terminal-pane/terminal-appearance.ts +++ b/src/renderer/src/components/terminal-pane/terminal-appearance.ts @@ -170,7 +170,8 @@ export function applyTerminalAppearance( // Why value-gated: writing minimumContrastRatio clears xterm's contrast cache, so skip on no-op re-applies. const minimumContrastRatio = resolveTerminalMinimumContrastRatio( theme?.background, - appearance.mode + appearance.mode, + settings.terminalMinimumContrastRatio ) if (pane.terminal.options.minimumContrastRatio !== minimumContrastRatio) { pane.terminal.options.minimumContrastRatio = minimumContrastRatio diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json index 352b086f9d5..4fa36b54a9f 100644 --- a/src/renderer/src/i18n/locales/en.json +++ b/src/renderer/src/i18n/locales/en.json @@ -8627,6 +8627,15 @@ "fastDescription": "Extra multiplier while scrolling with a modifier key.", "tui": "TUI", "tuiDescription": "Discrete wheel reports for full-screen terminal apps." + }, + "minimumContrast": { + "title": "Minimum Contrast Ratio", + "description": "Lifts terminal foreground colors that sit too close to the background. Leave blank for automatic, or set 1 to render program colors exactly as sent.", + "automatic": "Automatic: {{light}} on light backgrounds, {{dark}} on dark.", + "disabled": "Correction off. Programs that rely on low contrast, like Powerline separators, render as sent.", + "pinned": "Targets {{ratio}}:1 contrast for foreground colors, where possible.", + "placeholder": "Auto", + "suffix": "blank = automatic, 1 = off" } }, "TerminalSettingsPreview": { @@ -10488,7 +10497,20 @@ "agent": "agent", "process": "process", "prompt": "prompt", - "stop": "stop" + "stop": "stop", + "minimumContrast": { + "title": "Color Contrast", + "description": "Improve text readability or preserve the colors chosen by terminal programs.", + "contrast": "contrast", + "minimum": "minimum", + "ratio": "ratio", + "readability": "readability", + "wcag": "wcag", + "powerline": "powerline", + "statusline": "statusline", + "dim": "dim", + "colors": "colors" + } }, "windows": { "search": { @@ -11813,6 +11835,20 @@ }, "NativeChatSupportedAgents": { "label": "Supported agents:" + }, + "contrast": { + "title": "Color Contrast", + "description": "Improve text readability or preserve the colors chosen by terminal programs.", + "ratio": "Contrast target", + "autoDescription": "Balances readability with your terminal theme. Recommended.", + "offDescription": "Keeps program colors unchanged, including dim text and Powerline separators.", + "customDescription": "Choose how much to increase contrast between text and its background.", + "auto": "Automatic", + "off": "Off", + "custom": "Custom", + "targetDescription": "Higher values increase contrast where possible. Background colors stay unchanged.", + "subtle": "Subtle", + "strong": "Strong" } }, "right": { diff --git a/src/renderer/src/lib/terminal-contrast-correction.test.ts b/src/renderer/src/lib/terminal-contrast-correction.test.ts index 2197bdf903c..cf34328b879 100644 --- a/src/renderer/src/lib/terminal-contrast-correction.test.ts +++ b/src/renderer/src/lib/terminal-contrast-correction.test.ts @@ -2,6 +2,9 @@ import { describe, expect, it } from 'vitest' import { DARK_BG_MIN_CONTRAST, LIGHT_BG_MIN_CONTRAST, + MAX_TERMINAL_CONTRAST_RATIO, + MIN_TERMINAL_CONTRAST_RATIO, + normalizeTerminalMinimumContrastRatio, resolveTerminalMinimumContrastRatio } from './terminal-contrast-correction' import { TERMINAL_THEME_CATALOG } from './terminal-themes' @@ -42,6 +45,63 @@ describe('resolveTerminalMinimumContrastRatio', () => { }) }) +// #10754: the automatic floor rewrites deliberately low-contrast TUI output (Powerline seams, dimmed +// secondary text), so the user setting has to win over the luminance gate on both backgrounds. +describe('resolveTerminalMinimumContrastRatio with a user override', () => { + it('lets 1 disable contrast correction on a dark background', () => { + expect(resolveTerminalMinimumContrastRatio('#1e242a', 'dark', 1)).toBe(1) + }) + + it('lets 1 disable contrast correction on a light background too', () => { + expect(resolveTerminalMinimumContrastRatio('#ffffff', 'light', 1)).toBe(1) + }) + + it('honors an intermediate override instead of the automatic floor', () => { + expect(resolveTerminalMinimumContrastRatio('#1e242a', 'dark', 1.5)).toBe(1.5) + expect(resolveTerminalMinimumContrastRatio('#ffffff', 'light', 7)).toBe(7) + }) + + it("clamps an out-of-range override to xterm's 1-21 window", () => { + expect(resolveTerminalMinimumContrastRatio('#1e242a', 'dark', 0)).toBe( + MIN_TERMINAL_CONTRAST_RATIO + ) + expect(resolveTerminalMinimumContrastRatio('#1e242a', 'dark', -5)).toBe( + MIN_TERMINAL_CONTRAST_RATIO + ) + expect(resolveTerminalMinimumContrastRatio('#1e242a', 'dark', 99)).toBe( + MAX_TERMINAL_CONTRAST_RATIO + ) + }) + + it('falls back to the automatic floor when the override is unset or unusable', () => { + // A hand-edited settings file can carry any of these; xterm throws on a non-finite option. + for (const value of [undefined, Number.NaN, Number.POSITIVE_INFINITY]) { + expect(resolveTerminalMinimumContrastRatio('#1e242a', 'dark', value)).toBe( + DARK_BG_MIN_CONTRAST + ) + expect(resolveTerminalMinimumContrastRatio('#ffffff', 'light', value)).toBe( + LIGHT_BG_MIN_CONTRAST + ) + } + }) +}) + +describe('normalizeTerminalMinimumContrastRatio', () => { + it('returns undefined for anything that is not a usable number', () => { + for (const value of [undefined, null, '3', Number.NaN, Number.POSITIVE_INFINITY, {}]) { + expect(normalizeTerminalMinimumContrastRatio(value)).toBeUndefined() + } + }) + + it('passes in-range values through and clamps the rest', () => { + expect(normalizeTerminalMinimumContrastRatio(1)).toBe(1) + expect(normalizeTerminalMinimumContrastRatio(4.5)).toBe(4.5) + expect(normalizeTerminalMinimumContrastRatio(21)).toBe(21) + expect(normalizeTerminalMinimumContrastRatio(0.5)).toBe(1) + expect(normalizeTerminalMinimumContrastRatio(1000)).toBe(21) + }) +}) + // #10104: the dark-background floor must sit in the window that rescues near-background body text // without over-brightening vibrant ANSI colors (the #7934 regression). Guarding both edges keeps a // future tweak from silently sliding out of that window. diff --git a/src/renderer/src/lib/terminal-contrast-correction.ts b/src/renderer/src/lib/terminal-contrast-correction.ts index 4a4e9ac3cb6..7293ce2735e 100644 --- a/src/renderer/src/lib/terminal-contrast-correction.ts +++ b/src/renderer/src/lib/terminal-contrast-correction.ts @@ -1,4 +1,11 @@ import { isTerminalBackgroundLight } from '@/lib/terminal-title-contrast' +import { normalizeTerminalMinimumContrastRatio } from '../../../shared/terminal-minimum-contrast-settings' + +export { + MAX_TERMINAL_CONTRAST_RATIO, + MIN_TERMINAL_CONTRAST_RATIO, + normalizeTerminalMinimumContrastRatio +} from '../../../shared/terminal-minimum-contrast-settings' // xterm minimumContrastRatio tuning (#7934, #9599, #10104). Light backgrounds keep WCAG-AA correction so // invisible white/bright-white ANSI body text stays readable. Dark backgrounds use a mild floor of 3 @@ -13,10 +20,17 @@ export const DARK_BG_MIN_CONTRAST = 3 // Why gate by background luminance, not app mode (#7934): either theme slot can hold either kind of // theme (match-dark-mode, or a light theme in the dark slot), so follow the composed background. +// `override` is the user's terminalMinimumContrastRatio; clamped here too so a hand-edited settings +// file can't hand xterm an out-of-range or non-finite floor. export function resolveTerminalMinimumContrastRatio( background: string | undefined, - appSurface: 'dark' | 'light' + appSurface: 'dark' | 'light', + override?: number ): number { + const configured = normalizeTerminalMinimumContrastRatio(override) + if (configured !== undefined) { + return configured + } return isTerminalBackgroundLight(background, { appSurface }) ? LIGHT_BG_MIN_CONTRAST : DARK_BG_MIN_CONTRAST diff --git a/src/renderer/src/runtime/sync-runtime-graph/mobile-terminal-theme.test.ts b/src/renderer/src/runtime/sync-runtime-graph/mobile-terminal-theme.test.ts new file mode 100644 index 00000000000..ce5f4aea704 --- /dev/null +++ b/src/renderer/src/runtime/sync-runtime-graph/mobile-terminal-theme.test.ts @@ -0,0 +1,48 @@ +import { describe, expect, it } from 'vitest' +import type { AppState } from '@/store/types' +import { resolveMobileTerminalTheme } from './mobile-terminal-theme' + +function stateWith(settings: Record | null): AppState { + return { settings } as unknown as AppState +} + +const BASE = { + terminalThemeDark: 'Ghostty Default Style Dark', + terminalThemeLight: 'Builtin Tango Light', + terminalUseSeparateLightTheme: true, + theme: 'dark' +} + +// #10754: mobile mirrors the desktop contrast gate, so an explicit floor has to travel with the +// theme payload — otherwise the same session renders differently on the phone. +describe('resolveMobileTerminalTheme contrast floor', () => { + it('omits the floor when the user has not set one', () => { + const theme = resolveMobileTerminalTheme(stateWith(BASE), true) + expect(theme?.minimumContrastRatio).toBeUndefined() + }) + + it('publishes the user floor so the phone stops lifting low-contrast output', () => { + const theme = resolveMobileTerminalTheme( + stateWith({ ...BASE, terminalMinimumContrastRatio: 1 }), + true + ) + expect(theme?.minimumContrastRatio).toBe(1) + }) + + it('clamps before publishing so an old client can trust the value', () => { + expect( + resolveMobileTerminalTheme(stateWith({ ...BASE, terminalMinimumContrastRatio: 99 }), true) + ?.minimumContrastRatio + ).toBe(21) + expect( + resolveMobileTerminalTheme( + stateWith({ ...BASE, terminalMinimumContrastRatio: Number.NaN }), + true + )?.minimumContrastRatio + ).toBeUndefined() + }) + + it('returns nothing without settings', () => { + expect(resolveMobileTerminalTheme(stateWith(null), true)).toBeUndefined() + }) +}) diff --git a/src/renderer/src/runtime/sync-runtime-graph/mobile-terminal-theme.ts b/src/renderer/src/runtime/sync-runtime-graph/mobile-terminal-theme.ts index ab9e2c05042..c4bae609a39 100644 --- a/src/renderer/src/runtime/sync-runtime-graph/mobile-terminal-theme.ts +++ b/src/renderer/src/runtime/sync-runtime-graph/mobile-terminal-theme.ts @@ -2,6 +2,7 @@ import { getSystemPrefersDark, resolveEffectiveTerminalAppearance } from '@/lib/ import type { AppState } from '@/store/types' import type { RuntimeMobileTerminalTheme } from '../../../../shared/runtime-types' import { graphState } from './graph-state' +import { normalizeTerminalMinimumContrastRatio } from '@/lib/terminal-contrast-correction' function hexToRgba(hex: string, alpha: number): string { let clean = hex.replace('#', '') @@ -52,7 +53,15 @@ export function resolveMobileTerminalTheme( theme[key] = value } } - return { mode: appearance.mode, theme: theme as RuntimeMobileTerminalTheme['theme'] } + return { + mode: appearance.mode, + theme: theme as RuntimeMobileTerminalTheme['theme'], + // Why publish: mobile mirrors the desktop contrast gate, so an explicit floor has to travel with + // the theme or the same session would render differently on the phone (#10754). + minimumContrastRatio: normalizeTerminalMinimumContrastRatio( + settings.terminalMinimumContrastRatio + ) + } } export function getMobileTerminalTheme( diff --git a/src/shared/global-settings-types.ts b/src/shared/global-settings-types.ts index bef153ba8c9..5aac39c52ca 100644 --- a/src/shared/global-settings-types.ts +++ b/src/shared/global-settings-types.ts @@ -144,6 +144,10 @@ export type GlobalSettings = { terminalPaneOpacityTransitionMs: number terminalDividerThicknessPx: number terminalBackgroundOpacity?: number + /** xterm minimumContrastRatio floor for terminal panes (#10754). Undefined keeps the automatic, + * background-luminance-gated floor (3 dark / 4.5 light); 1 disables contrast correction so TUIs + * that rely on deliberately low contrast (Powerline seams, dimmed secondary text) render as sent. */ + terminalMinimumContrastRatio?: number terminalColorOverrides?: TerminalColorOverrides terminalPaddingX?: number terminalPaddingY?: number diff --git a/src/shared/runtime-mobile-session-tab-contracts.ts b/src/shared/runtime-mobile-session-tab-contracts.ts index 07e3a1b5524..563637c562f 100644 --- a/src/shared/runtime-mobile-session-tab-contracts.ts +++ b/src/shared/runtime-mobile-session-tab-contracts.ts @@ -33,6 +33,9 @@ export type RuntimeMobileSessionTerminalTab = { export type RuntimeMobileTerminalTheme = { mode: 'dark' | 'light' theme: TerminalColorOverrides + /** Optional desktop terminalMinimumContrastRatio override (#10754). Absent means the client picks + * its own background-luminance floor, which is what pre-#10754 clients always do. */ + minimumContrastRatio?: number } export type RuntimeMobileSessionMarkdownTab = { diff --git a/src/shared/terminal-minimum-contrast-settings.ts b/src/shared/terminal-minimum-contrast-settings.ts new file mode 100644 index 00000000000..c2df1c7ebbb --- /dev/null +++ b/src/shared/terminal-minimum-contrast-settings.ts @@ -0,0 +1,16 @@ +// xterm's minimumContrastRatio range: 1 disables contrast correction entirely, 21 is the maximum +// WCAG ratio (black on white). Shared so main's persistence boundary and the renderer clamp alike. +export const MIN_TERMINAL_CONTRAST_RATIO = 1 +export const MAX_TERMINAL_CONTRAST_RATIO = 21 + +/** + * Clamps a user-supplied contrast floor (#10754). `undefined` means "unset", so callers fall back to + * Orca's automatic background-luminance floor; anything unusable is treated the same way rather than + * handed to xterm, which throws on a non-finite option. + */ +export function normalizeTerminalMinimumContrastRatio(value: unknown): number | undefined { + if (typeof value !== 'number' || !Number.isFinite(value)) { + return undefined + } + return Math.min(MAX_TERMINAL_CONTRAST_RATIO, Math.max(MIN_TERMINAL_CONTRAST_RATIO, value)) +} From 98fdbc4adee2b1d5d23cd24ea5d818eebef59691 Mon Sep 17 00:00:00 2001 From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com> Date: Tue, 8 Sep 2026 04:03:07 -0400 Subject: [PATCH 05/59] fix(orchestration): file federated worker mail under the coordinator Run (#19542) --- config/reliability-gates.jsonc | 9 + .../orchestration-skill-guidance.test.mjs | 7 +- skill-guides/orchestration.md | 4 +- src/cli/bundled-skill-guides.ts | 4 +- ...ca-runtime-subscribe-to-terminal-resize.ts | 2 +- .../lineage-and-scan-cache-part-05.spec.ts | 5 +- ...creation-and-orchestration-part-02.spec.ts | 12 +- ...output-and-worker-recovery-part-04.spec.ts | 10 +- ...orchestration-messages-fake-parity.test.ts | 46 ++- .../coordinator-decision-gates.test.ts | 20 +- ...dinator-dispatch-unobserved-prompt.test.ts | 6 +- ...coordinator-drift-probe-coalescing.test.ts | 15 +- .../coordinator-escalation-triage.test.ts | 8 +- .../coordinator-stale-base-flag.test.ts | 52 +++ .../runtime/orchestration/coordinator.test.ts | 165 ++++----- ...ty-dispatch-shortcircuit.benchmark.test.ts | 8 +- .../db-heartbeat-straggler-guard.test.ts | 2 +- .../db-message-timestamp.test.ts | 7 +- .../runtime/orchestration/db-messages.test.ts | 194 +++++++++++ .../db-task-create-readiness.test.ts | 58 ++-- .../db-task-dispatch-invariant.test.ts | 109 ++++-- .../db-task-dispatch-lifecycle-guards.test.ts | 99 ++++-- .../db-task-dispatch-races.test.ts | 29 +- .../db-undelivered-mailboxes.test.ts | 25 +- src/main/runtime/orchestration/db.test.ts | 320 ++++++------------ .../db/attempt-outcome-projection.test.ts | 12 +- .../orchestration/db/contract-constants.ts | 2 +- .../db/decision-gate-lifecycle.test.ts | 4 +- .../db/decision-gates/decision-gate-store.ts | 27 +- .../orchestration/db/dispatch-depth.test.ts | 37 +- .../dispatch-mailbox-consumer-fencing.test.ts | 13 +- .../orchestration/db/dispatch-row-writer.ts | 6 +- ...derated-dispatch-observation-fence.test.ts | 5 +- .../remote-dispatch-attachment-create.ts | 12 + ...remote-dispatch-attachment-release.test.ts | 1 + .../db/lifecycle-transition.test.ts | 6 +- .../db/messages/message-insert.ts | 6 +- .../db/schema/create-graph-tables-sql.ts | 1 + .../federated-home-run-migration.test.ts | 26 ++ .../orchestration/db/schema/migrate-v40.ts | 11 + .../orchestration/db/schema/migrate.ts | 2 + .../orchestration/db/tasks/task-store.ts | 6 +- .../db/writer-run-required.test.ts | 40 +++ .../dispatch-failure-idempotency.test.ts | 6 +- .../failed-start-terminal-adoption.test.ts | 6 +- ...ederation-acknowledgment-integrity.test.ts | 1 + .../federation-control-message.ts | 10 + .../lifecycle-caller-edges.test.ts | 20 +- .../lifecycle-reconciliation.test.ts | 86 +++-- ...tweight-run-worker-exit-escalation.test.ts | 5 +- .../mailbox-pointer-eligibility.test.ts | 6 +- .../mailbox-pointer-stage.test.ts | 32 +- .../mailbox-pointer-submit.test.ts | 21 +- .../message-batch-atomicity.test.ts | 17 +- .../nested-worker-depth-migration.test.ts | 3 +- .../orchestration-adopted-run-binding.test.ts | 2 + ...ation-all-start-versions-migration.test.ts | 7 +- ...hestration-db-retention-pagination.test.ts | 13 +- ...chestration-federated-legacy-probe.test.ts | 97 ++++++ ...chestration-legacy-storage-test-fixture.ts | 13 + ...orchestration-mutation-question-db.test.ts | 1 + .../orchestration-schema-version-skew.ts | 14 +- ...ion-settled-worker-resume-fence-db.test.ts | 2 +- ...chestration-version-skew-migration.test.ts | 5 +- .../orchestration-worker-dispatch-db.test.ts | 23 +- .../r1-identity-migration.test.ts | 2 +- src/main/runtime/orchestration/types.ts | 1 + ...start-unobserved-prompt-settlement.test.ts | 2 +- .../federated-message-targeting.test.ts | 1 + .../federated-release-safety.test.ts | 1 + .../federation/federated-worker-start.ts | 1 + .../federation-agent-launch.test.ts | 1 + .../federation-control-mail.test.ts | 1 + .../federation-folder-placement.test.ts | 1 + .../federation-lifecycle-settlement.test.ts | 1 + .../federation-liveness-verdict.test.ts | 2 + .../federation/federation-setup.test.ts | 1 + .../federation-start-prompt-budget.test.ts | 1 + .../federation/federation-start-schema.ts | 1 + .../orchestration/federation/federation.ts | 1 + .../check-worker-federated-attachment.test.ts | 188 ++++++++++ .../orchestration/messaging/check-worker.ts | 6 +- .../runs/migration-behavior.test.ts | 5 +- .../failed-start-residual-terminal.test.ts | 2 +- .../worker/legacy-dispatch-projection.test.ts | 2 +- .../manual-dispatch-observation.test.ts | 13 +- .../structured-worker-stop-receipt.test.ts | 5 +- ...tion-11745-regression-verification.test.ts | 7 +- ...y-compatibility-dispatcher-test-fixture.ts | 1 + ...hestration-legacy-coordinator-race.test.ts | 1 + ...estration-legacy-question-takeover.test.ts | 8 +- ...estration-legacy-takeover-delivery.test.ts | 1 + ...tration-legacy-takeover-dispatcher.test.ts | 1 + .../rpc/orchestration-mutation-ledger.test.ts | 7 +- ...rchestration-mutation-request-show.test.ts | 2 +- ...stration-runtime-update-settlement.test.ts | 1 + ...egacy-worker-terminal-resume-fence.test.ts | 2 +- .../runtime-rpc-request-authorization.test.ts | 15 +- .../orchestration-fleet-projection.test.ts | 33 +- .../orchestration-fleet-worker-projection.ts | 4 + 100 files changed, 1599 insertions(+), 546 deletions(-) create mode 100644 src/main/runtime/orchestration/coordinator-stale-base-flag.test.ts create mode 100644 src/main/runtime/orchestration/db-messages.test.ts create mode 100644 src/main/runtime/orchestration/db/schema/federated-home-run-migration.test.ts create mode 100644 src/main/runtime/orchestration/db/schema/migrate-v40.ts create mode 100644 src/main/runtime/orchestration/db/writer-run-required.test.ts create mode 100644 src/main/runtime/orchestration/orchestration-federated-legacy-probe.test.ts create mode 100644 src/main/runtime/rpc/methods/orchestration/messaging/check-worker-federated-attachment.test.ts diff --git a/config/reliability-gates.jsonc b/config/reliability-gates.jsonc index 8a1349a7852..8c6a4646386 100644 --- a/config/reliability-gates.jsonc +++ b/config/reliability-gates.jsonc @@ -13658,6 +13658,7 @@ "invariant": "Starting a worker in the coordinator's current workspace must materialize one inactive terminal tab before worker-start returns, preserve coordinator focus, and remain exactly once after workspace re-entry. After an app update or restart, an exact live legacy worker must fence automatic provider resume, adopt its original PTY into its original background pane, retain readable output, and clear the resume record without spawning, writing, signalling, interrupting, replacing, or focusing the worker. A current-contract worker whose renderer graph identity is temporarily absent must retain its Dispatch capability and settle exactly once from exact hook-attested handle, pane, and process evidence; otherwise only an exact attested coordinator may take over. A worker_done caller may report success only after the owning runtime returns an explicit lifecycle verdict or authoritative reads prove that the exact Task, Dispatch, and worker report receipt settled the expected outcome. Federated terminal settlement must remain replay-eligible until the worker durably acknowledges it, and identical same-outcome retries must converge idempotently. Independently updated clients and worker servers must preserve the negotiated protocol: current peers use Run-home lifecycle settlement, while protocol v1/v2 peers retain their legacy completion path without receiving newer-only fields. A federated worker may accept only the authority defined by its negotiated protocol. An exact existing target workspace must receive a discoverable tab without stealing coordinator focus; if renderer reveal fails, worker-start must expose that the live worker remains background-only. Run and Dispatch checks must resolve through the caller's stable pane identity when a terminal handle is reminted, while a live handle outranks mismatched pane metadata. A nested worker's creator edge requires the current creator pane, process incarnation, and owning Run generation; reminting and rebinding that pane to another Run must remove the stale edge. Explicit legacy terminal inspection remains handle-scoped, and remote or headless worker presentation remains background-only.", "oracle": "Drive Run create, Task create, and worker-start through production Electron runtimes with a deterministic Codex fixture. Require append-only ledgers with one still-live PID and no interruption, a visible inactive worker tab while the coordinator stays active, Run delivery through stable pane identity, and stable PTY/incarnation, tab, leaf, worktree, Task, and Dispatch across workspace re-entry. In a restart journey, retain the original daemon PTY and PID, remove renderer ownership, retain sleeping-session evidence, mark the Dispatch legacy, relaunch, and require exact inactive tab adoption, readable ACK output, cleared resume state, one spawn, and no resume argv or Conversation interrupted text after another workspace round trip. The service oracle removes renderer lookup identity from current-contract callers while retaining real restored-PTY and hook commitments, replays authenticated completion and takeover across fresh runtimes, and requires one Task, Dispatch, terminal authority, message, mutation, ordinary-mail delivery, remote process fencing, and unchanged fixture marker bytes while foreign pane evidence remains rejected. Unit tests separately remint a creator pane and process from Run A into Run B, require the nested Run A worker to fall back to its current coordinator, require indexed query plans, and bound 300 Task reads with 50,000 retained Runs. They also assert authority-specific legacy affordances, exact identity and owner matching, retained-output fallback, pane-stable routing, federated non-activation, and SSH fallback parity.", "commands": [ + "ORCA_BACKGROUND_LAUNCH=1 npx vitest run --config config/vitest.config.ts src/main/runtime/rpc/methods/orchestration/messaging/check-worker-federated-attachment.test.ts", "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/rpc/orchestration-runtime-update-settlement.test.ts --reporter=dot", "pnpm exec vitest run --config config/vitest.config.ts src/cli/handlers/orchestration.test.ts src/cli/handlers/orchestration-check-identity.test.ts src/cli/handlers/orchestration-worker-cli.test.ts src/main/runtime/rpc/methods/orchestration/worker/composed-workers.test.ts src/main/runtime/rpc/methods/orchestration/messaging/check.test.ts src/main/runtime/rpc/methods/orchestration/messaging/send.test.ts src/main/ssh/ssh-remote-orca-cli.test.ts", "pnpm exec vitest run --config config/vitest.config.ts src/cli/handlers/orchestration-lifecycle-rejection.test.ts src/cli/handlers/orchestration-lifecycle-json-rejection.test.ts src/cli/handlers/orchestration-migration.test.ts", @@ -13672,6 +13673,7 @@ "pnpm run build:cli && SKIP_BUILD=1 pnpm exec playwright test tests/e2e/orchestration-worker-settlement-release-cli.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1" ], "testFiles": [ + "src/main/runtime/rpc/methods/orchestration/messaging/check-worker-federated-attachment.test.ts", "src/main/runtime/rpc/orchestration-runtime-update-settlement.test.ts", "src/main/runtime/orchestration/formatter.test.ts", "src/main/runtime/orchestration/orchestration-legacy-worker-terminal-recovery.test.ts", @@ -13695,6 +13697,13 @@ "tests/e2e/orchestration-worker-settlement-release-cli.spec.ts" ], "assertionRefs": [ + { + "file": "src/main/runtime/rpc/methods/orchestration/messaging/check-worker-federated-attachment.test.ts", + "assertions": [ + "replays the coordinator instruction and takes its ack after the app restarts", + "files loopback mail once under the local Dispatch Run without replacing its owner" + ] + }, { "file": "src/main/runtime/rpc/orchestration-runtime-update-settlement.test.ts", "assertions": [ diff --git a/config/scripts/orchestration-skill-guidance.test.mjs b/config/scripts/orchestration-skill-guidance.test.mjs index ce501954322..c15e3e93ea8 100644 --- a/config/scripts/orchestration-skill-guidance.test.mjs +++ b/config/scripts/orchestration-skill-guidance.test.mjs @@ -168,9 +168,10 @@ describe('orchestration kernel', () => { expect(kernel).toContain( '`projection.attention` categories, `projection.attention.requiresAction`, and literal `projection.nextAction` argv' ) - expect(kernel).toContain( - 'An `inspect` `nextAction` on a `live` row with `attention.requiresAction` false is informational, not a command to re-run: keep waiting with `check --wait`' - ) + // Unverifiable workers can still owe release; the guide must explain the action itself. + expect(kernel).toContain('A `none` `nextAction` has no argv to run') + expect(kernel).toContain('read `liveness.reason` and keep waiting with `check --wait`') + expect(kernel).toContain('Absence never earns an argv; settlement and pending work still do') expect(kernel).toContain('choose `worker-stop` or `worker-abandon`') }) diff --git a/skill-guides/orchestration.md b/skill-guides/orchestration.md index 4e49a0d84af..d744785ab10 100644 --- a/skill-guides/orchestration.md +++ b/skill-guides/orchestration.md @@ -137,8 +137,8 @@ After three consecutive empty waits, stop waiting blindly and enumerate with `ORCA orchestration worker-list --include-remote --json` (defaults to the bound Run; `--run ` overrides; the receipt's `scope` names which), acting on each row's `projection.attention` categories, `projection.attention.requiresAction`, and literal `projection.nextAction` argv. -An `inspect` `nextAction` on a `live` row with `attention.requiresAction` false -is informational, not a command to re-run: keep waiting with `check --wait`. +A `none` `nextAction` has no argv to run: read `liveness.reason` and keep waiting +with `check --wait`. Absence never earns an argv; settlement and pending work still do. Leave the wait only on positive proof the agent stopped: `exited` liveness, the worker's own observation of process exit, or a transcript whose final agent turn sent no `worker_done`. Then load `references/recovery-and-cleanup.md` and choose diff --git a/src/cli/bundled-skill-guides.ts b/src/cli/bundled-skill-guides.ts index fc30604a264..47b5559f01b 100644 --- a/src/cli/bundled-skill-guides.ts +++ b/src/cli/bundled-skill-guides.ts @@ -66,10 +66,10 @@ const ORCA_PER_WORKSPACE_ENV_SSH_HOST_REFERENCE_MARKDOWN = "# SSH connection mod const ORCA_PER_WORKSPACE_ENV_WINDOWS_SCRIPTS_REFERENCE_MARKDOWN = "# Windows local-side scripts\n\nLoad this when the user's desktop is Windows and you are scaffolding the local-side scripts. A bare\n`.sh` will not execute there. Either require WSL or Git Bash and point `orca.yaml` at a launcher such\nas `bash ./scripts/orca-vm/.sh` through a `.cmd` file, or scaffold PowerShell equivalents.\n\nThe remote-side commands you run inside the Linux environment stay bash regardless of the desktop OS.\n\n```powershell\n#requires -Version 5\n$ErrorActionPreference = 'Stop'\n# resolve env→state→fallback; run the provider CLI / ssh the same way;\n# capture provider output; build the result object for the chosen mode and write ONE line of JSON to stdout.\n# Orca-server mode: @{ schemaVersion=1; pairingCode=$pairingCode; projectRoot=$projectRoot; userData=@{...} }\n# SSH mode: @{ schemaVersion=1; connection=@{ type=\"ssh\"; projectRoot=$projectRoot;\n# target=@{ label=$label; host=$host; port=$port; username=$user } } }\n($result | ConvertTo-Json -Compress -Depth 6)\n# progress/errors → Write-Error / the error stream, never stdout.\n```\n\nThe doctor's executable-bit check is a POSIX concept and is skipped on Windows, so a script that is\nunusable on the user's machine for a different reason still has to be caught by the `--provision`\nself-test.\n" // oxfmt-ignore -const ORCHESTRATION_MARKDOWN = "---\nname: orchestration\ndescription: >-\n Coordinate supervised Orca workers: threaded messages, blocking ask/reply,\n task dispatch, worker_done/escalation waits, task DAGs, decision gates,\n coordinator loops, and decomposing work across agents. Use `orca-cli` for full\n ownership handoffs — \"hand off\", \"handoff\", \"handover\", \"give this to another\n agent\", \"another worktree\" — unless asked to supervise, monitor, or coordinate\n a DAG, and for terminal control, lightweight terminal prompts, shell commands,\n Orca worktree management, and reading or waiting on terminals. Use Computer\n Use for external browser windows, webviews, Orca app UI, or desktop UI outside\n Orca's embedded browser only when the task requires OS/window-level control\n such as focus, menus, dialogs, coordinates, or screenshots. Use `orca-cli` for\n Orca's embedded pages and a page-automation tool such as Playwright or CDP for\n external pages.\n---\n\n# Orca orchestration\n\nOrchestration is Orca's structured coordination layer. It records who owns work,\nwhich attempt is authoritative, and when supervised work has settled.\n\n## Outcome\n\n**Result:** every in-scope Task has one explicit outcome and every settled worker\nterminal has a next owner or cleanup decision. **Next consumer:** the user who\nrequested supervision. **Done:** all expected Dispatches have settled, every\ndelivered message was processed before acknowledgment, each settled worker was\nreused, explicitly retained, or released, and the turn ends only when the report\nto that user names, per Task, its outcome, the evidence behind it, and any\nunresolved blocker.\n\n**Safe failure:** preserve work and authority and report the state as unknown or\n`unverifiable`. Only positive proof of exit authorizes stop, abandon, or retry,\nand only an accepted settlement authorizes release. Every other observation,\nabsence included, is a checkpoint.\n\n## Classify the role\n\n| Current context | Role | Route |\n| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------ |\n| The user explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use a decision gate, or manage ask/reply | Coordinator | Use the supervised loop below |\n| The current prompt contains a live injected preamble with Task and Dispatch IDs | Dispatched worker | Follow the preamble and the worker obligations below |\n| The user asks to hand off ownership or start another agent/worktree without supervision | Handoff owner | Use `orca-cli`; create no Run, Task, or Dispatch and do not monitor completion |\n| A message carries a legacy authority label | Compatibility operator | Load the legacy contract reference before any lifecycle mutation |\n| No live preamble and no explicit supervision | Ordinary terminal agent | Do not emit lifecycle messages; use `orca-cli` for terminal/worktree work |\n\nModel or effort selection does not make a handoff supervised. Never substitute a\nnon-Orca subagent tool when Orca orchestration provenance was requested.\n\n## Authority and safety floor\n\n- A Run is a durable namespace and coordinator inbox; it does not schedule or\n place workers. A Task is work. A Dispatch is one authoritative Task attempt.\n- Lifecycle authority comes from the active Dispatch, not a terminal title,\n copied ID, old database row, provider transcript, or visible pane.\n- Workers use the exact executable, handle, capability, Task ID, and Dispatch ID\n in the live preamble. Never reconstruct, translate, or broaden those arguments.\n- After remote start, address the worker by Dispatch ID. The execution host owns\n process, filesystem, transcript, stop, and cleanup facts. Preserve the verdicts\n `live` / `unverifiable` / `exited`; contact loss is not process death.\n- Liveness is layered: `worker-list`'s `projection.liveness` is the fleet verdict\n for the agent; `worker-show`'s `observation.status` is PTY liveness only. A live\n terminal can still hold a dead or stuck agent.\n- Folder workspaces are valid; never require Git or assume a worktree.\n- Clients and remote servers update independently. Treat unknown optional fields\n as absent. A new stream operation requires advertised capability because old\n decoders may silently drop unknown opcodes. Never fall back to local execution\n when remote authority or capability is unproven.\n- Use the executable you used to run `skills get` for the entire run. In the\n examples below, replace `ORCA` with it; do not create a shell variable or run\n `ORCA` literally. If it fails, report that exact error instead of switching.\n- A successful `orchestration send` proves durable enqueue; its wake or nudge is\n best-effort attention only and does not prove the recipient read or accepted it.\n\n## Worker obligations\n\nThe injected preamble is authoritative. A dispatched worker must:\n\n1. Do only the current Task and use the preamble's `ask` command for a blocking\n coordinator question. Never open a local question TUI the coordinator cannot\n answer. Resume the same message ID after an ask timeout.\n2. Send heartbeats only at the cadence in the preamble. A heartbeat proves\n liveness, not completion.\n3. Read coordinator follow-ups at each natural checkpoint — before starting a\n new file, after a test run — and once more immediately before `worker_done`:\n `ORCA orchestration check --terminal --json`.\n4. Send `worker_done` exactly once, from the dispatched terminal, with a\n three-sentence executive summary, both lifecycle IDs, and explicit\n `--outcome succeeded` or `--outcome failed`. Never encode failure only in prose.\n5. Append `--files-modified` and `--report-path` only with real values when\n applicable. After `worker_done`, end the dispatched turn and idle; do not poll\n or start new work.\n\nA direct user instruction after completion starts new user-owned work and takes\nprecedence over the idle rule. Do not reuse the settled lifecycle IDs.\n\n## Canonical supervised loop\n\nConfirm the runtime, bind one Run, and start the full independent wave before\nwaiting. `worker-start --spec` creates the Task and its attempt in one call:\n\n```text\nORCA status --json\nORCA orchestration run-create --objective \"\" --json\nORCA orchestration worker-start --spec \"\" --worktree current --agent codex --json\nORCA orchestration worker-start --spec \"\" --worktree current --agent claude --json\nORCA orchestration check --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json\n```\n\nIf `worker-start` exits non-zero, do not relaunch. Read the receipt's\n`failedStage` and `residualResources`, then load\n`references/recovery-and-cleanup.md`.\n\nUse `task-create` plus `worker-start --task ` for planned fan-out with\ndependencies or a retry of a known Task. Use dependencies only for real ordering\nand prefer parallel waves over chains deeper than three or four steps; nested\nworkers obey the depth limit, and a new Run does not reset the caller's depth.\n\nA consuming `check` names its caller with `--terminal `, never `--from`;\nomit it inside the coordinator's own Orca terminal. It returns the bound Run's\noldest FIFO Delivery and replays that batch until acknowledged. Process every\nmessage: reply to questions, validate each `worker_done` against the expected\nactive Dispatch, and decide each settled terminal's next owner before the ack:\n\n```text\nORCA orchestration reply --id --body \"\" --json\nORCA orchestration worker-release --dispatch --json\nORCA orchestration check --ack --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json\n```\n\nKeep waiting until every expected Dispatch settles. A timeout or empty result is\na checkpoint, not a failure. Do not stop, retry, release, or launch a duplicate\neditor without the positive proof `## Outcome` requires.\n\nAfter three consecutive empty waits, stop waiting blindly and enumerate with\n`ORCA orchestration worker-list --include-remote --json` (defaults to the bound\nRun; `--run ` overrides; the receipt's `scope` names which), acting on\neach row's `projection.attention` categories, `projection.attention.requiresAction`, and literal `projection.nextAction` argv.\nAn `inspect` `nextAction` on a `live` row with `attention.requiresAction` false\nis informational, not a command to re-run: keep waiting with `check --wait`.\nLeave the wait only on positive proof the agent stopped: `exited` liveness, the\nworker's own observation of process exit, or a transcript whose final agent turn\nsent no `worker_done`. Then load `references/recovery-and-cleanup.md` and choose\n`worker-stop` or `worker-abandon` explicitly. `unverifiable` is absence,\nincluding when `worker-show` reports `agentWait` null. Absence never authorizes\nstop, abandon, retry, or release; keep waiting or inspect.\n\n`worker-start` is the normal path, composing placement, terminal readiness,\nprompt injection, and supervised resource ownership. `dispatch --inject` leaves\nan operator-created process unsupervised and is only for an expressiveness gap.\n\n## Task-spec contract\n\nEvery Task spec must be self-contained and name:\n\n- **Target:** the files, component, or environment in scope.\n- **Change:** the concrete result to produce.\n- **Constraints:** invariants, compatibility rules, and do-not-touch boundaries.\n- **Ownership:** what this worker may edit and any coordination boundary.\n- **Observable acceptance:** the test, output, or evidence that proves completion.\n\n## Completion accounting\n\nAfter an accepted success or failure report, immediately do exactly one:\n\n1. Reuse the same proven agent terminal for an immediate follow-up Dispatch.\n2. Record user-requested retention with `worker-retain`.\n3. Run `worker-release`.\n\nRelease is post-settlement cleanup, not cancellation. Only an accepted\nsettlement authorizes it; no other observation does. If release is uncertain,\nfollow its exact recovery receipt and never substitute `terminal close`.\n\nA valid `worker_done` settles the Task and Dispatch automatically; do not follow\nit with `task-update --status completed`. Enumerate the terminals still owing a\ndecision with `worker-list --run --terminal-state reclaimable --json`,\nand do not end the coordinator turn until it returns none.\n\n## Conditional references\n\nThis compact guide is sufficient for the normal local loop. At an action gate\nbelow, run `ORCA skills get orchestration --reference references/.md` and\nread only that document; `--references` lists the names. If the CLI rejects\n`--reference`, run `ORCA skills get orchestration --full` once instead: it\nreturns this exact kernel and every reference, so read only the named one. If an\nolder CLI rejects `--full`, keep this kernel's safety floor, use that command's\n`--help`, and never guess newer flags.\n\n| Action gate | Bundled reference |\n| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |\n| Expanded DAG waves, launch model/effort, same-terminal reuse, or review ownership | `references/coordinator-loop.md` |\n| You are a dispatched worker and the live preamble does not answer your question, or `check` returned an error | `references/worker-contract.md` |\n| New worktree, exact workspace, SSH, WSL, or connected-server placement | `references/placement-and-remote.md` |\n| Inbox replay, follow-up messages, group addresses, or decision gates | `references/messaging-and-gates.md` |\n| Failed/stopped/unknown attempts, retry, stop, abandon, retain, or uncertain release | `references/recovery-and-cleanup.md` |\n| Custom argv or terminal topology that `worker-start` cannot express | `references/low-level-topology.md` |\n| Any legacy label, adopted Run, compatibility receipt, or takeover | `references/legacy-contract-migration.md` |\n\nRetired scheduler commands are not aliases for Run creation. Recovery commands\nmust provide their exact next action; follow it with the same selected executable.\n" +const ORCHESTRATION_MARKDOWN = "---\nname: orchestration\ndescription: >-\n Coordinate supervised Orca workers: threaded messages, blocking ask/reply,\n task dispatch, worker_done/escalation waits, task DAGs, decision gates,\n coordinator loops, and decomposing work across agents. Use `orca-cli` for full\n ownership handoffs — \"hand off\", \"handoff\", \"handover\", \"give this to another\n agent\", \"another worktree\" — unless asked to supervise, monitor, or coordinate\n a DAG, and for terminal control, lightweight terminal prompts, shell commands,\n Orca worktree management, and reading or waiting on terminals. Use Computer\n Use for external browser windows, webviews, Orca app UI, or desktop UI outside\n Orca's embedded browser only when the task requires OS/window-level control\n such as focus, menus, dialogs, coordinates, or screenshots. Use `orca-cli` for\n Orca's embedded pages and a page-automation tool such as Playwright or CDP for\n external pages.\n---\n\n# Orca orchestration\n\nOrchestration is Orca's structured coordination layer. It records who owns work,\nwhich attempt is authoritative, and when supervised work has settled.\n\n## Outcome\n\n**Result:** every in-scope Task has one explicit outcome and every settled worker\nterminal has a next owner or cleanup decision. **Next consumer:** the user who\nrequested supervision. **Done:** all expected Dispatches have settled, every\ndelivered message was processed before acknowledgment, each settled worker was\nreused, explicitly retained, or released, and the turn ends only when the report\nto that user names, per Task, its outcome, the evidence behind it, and any\nunresolved blocker.\n\n**Safe failure:** preserve work and authority and report the state as unknown or\n`unverifiable`. Only positive proof of exit authorizes stop, abandon, or retry,\nand only an accepted settlement authorizes release. Every other observation,\nabsence included, is a checkpoint.\n\n## Classify the role\n\n| Current context | Role | Route |\n| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------ |\n| The user explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use a decision gate, or manage ask/reply | Coordinator | Use the supervised loop below |\n| The current prompt contains a live injected preamble with Task and Dispatch IDs | Dispatched worker | Follow the preamble and the worker obligations below |\n| The user asks to hand off ownership or start another agent/worktree without supervision | Handoff owner | Use `orca-cli`; create no Run, Task, or Dispatch and do not monitor completion |\n| A message carries a legacy authority label | Compatibility operator | Load the legacy contract reference before any lifecycle mutation |\n| No live preamble and no explicit supervision | Ordinary terminal agent | Do not emit lifecycle messages; use `orca-cli` for terminal/worktree work |\n\nModel or effort selection does not make a handoff supervised. Never substitute a\nnon-Orca subagent tool when Orca orchestration provenance was requested.\n\n## Authority and safety floor\n\n- A Run is a durable namespace and coordinator inbox; it does not schedule or\n place workers. A Task is work. A Dispatch is one authoritative Task attempt.\n- Lifecycle authority comes from the active Dispatch, not a terminal title,\n copied ID, old database row, provider transcript, or visible pane.\n- Workers use the exact executable, handle, capability, Task ID, and Dispatch ID\n in the live preamble. Never reconstruct, translate, or broaden those arguments.\n- After remote start, address the worker by Dispatch ID. The execution host owns\n process, filesystem, transcript, stop, and cleanup facts. Preserve the verdicts\n `live` / `unverifiable` / `exited`; contact loss is not process death.\n- Liveness is layered: `worker-list`'s `projection.liveness` is the fleet verdict\n for the agent; `worker-show`'s `observation.status` is PTY liveness only. A live\n terminal can still hold a dead or stuck agent.\n- Folder workspaces are valid; never require Git or assume a worktree.\n- Clients and remote servers update independently. Treat unknown optional fields\n as absent. A new stream operation requires advertised capability because old\n decoders may silently drop unknown opcodes. Never fall back to local execution\n when remote authority or capability is unproven.\n- Use the executable you used to run `skills get` for the entire run. In the\n examples below, replace `ORCA` with it; do not create a shell variable or run\n `ORCA` literally. If it fails, report that exact error instead of switching.\n- A successful `orchestration send` proves durable enqueue; its wake or nudge is\n best-effort attention only and does not prove the recipient read or accepted it.\n\n## Worker obligations\n\nThe injected preamble is authoritative. A dispatched worker must:\n\n1. Do only the current Task and use the preamble's `ask` command for a blocking\n coordinator question. Never open a local question TUI the coordinator cannot\n answer. Resume the same message ID after an ask timeout.\n2. Send heartbeats only at the cadence in the preamble. A heartbeat proves\n liveness, not completion.\n3. Read coordinator follow-ups at each natural checkpoint — before starting a\n new file, after a test run — and once more immediately before `worker_done`:\n `ORCA orchestration check --terminal --json`.\n4. Send `worker_done` exactly once, from the dispatched terminal, with a\n three-sentence executive summary, both lifecycle IDs, and explicit\n `--outcome succeeded` or `--outcome failed`. Never encode failure only in prose.\n5. Append `--files-modified` and `--report-path` only with real values when\n applicable. After `worker_done`, end the dispatched turn and idle; do not poll\n or start new work.\n\nA direct user instruction after completion starts new user-owned work and takes\nprecedence over the idle rule. Do not reuse the settled lifecycle IDs.\n\n## Canonical supervised loop\n\nConfirm the runtime, bind one Run, and start the full independent wave before\nwaiting. `worker-start --spec` creates the Task and its attempt in one call:\n\n```text\nORCA status --json\nORCA orchestration run-create --objective \"\" --json\nORCA orchestration worker-start --spec \"\" --worktree current --agent codex --json\nORCA orchestration worker-start --spec \"\" --worktree current --agent claude --json\nORCA orchestration check --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json\n```\n\nIf `worker-start` exits non-zero, do not relaunch. Read the receipt's\n`failedStage` and `residualResources`, then load\n`references/recovery-and-cleanup.md`.\n\nUse `task-create` plus `worker-start --task ` for planned fan-out with\ndependencies or a retry of a known Task. Use dependencies only for real ordering\nand prefer parallel waves over chains deeper than three or four steps; nested\nworkers obey the depth limit, and a new Run does not reset the caller's depth.\n\nA consuming `check` names its caller with `--terminal `, never `--from`;\nomit it inside the coordinator's own Orca terminal. It returns the bound Run's\noldest FIFO Delivery and replays that batch until acknowledged. Process every\nmessage: reply to questions, validate each `worker_done` against the expected\nactive Dispatch, and decide each settled terminal's next owner before the ack:\n\n```text\nORCA orchestration reply --id --body \"\" --json\nORCA orchestration worker-release --dispatch --json\nORCA orchestration check --ack --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json\n```\n\nKeep waiting until every expected Dispatch settles. A timeout or empty result is\na checkpoint, not a failure. Do not stop, retry, release, or launch a duplicate\neditor without the positive proof `## Outcome` requires.\n\nAfter three consecutive empty waits, stop waiting blindly and enumerate with\n`ORCA orchestration worker-list --include-remote --json` (defaults to the bound\nRun; `--run ` overrides; the receipt's `scope` names which), acting on\neach row's `projection.attention` categories, `projection.attention.requiresAction`, and literal `projection.nextAction` argv.\nA `none` `nextAction` has no argv to run: read `liveness.reason` and keep waiting\nwith `check --wait`. Absence never earns an argv; settlement and pending work still do.\nLeave the wait only on positive proof the agent stopped: `exited` liveness, the\nworker's own observation of process exit, or a transcript whose final agent turn\nsent no `worker_done`. Then load `references/recovery-and-cleanup.md` and choose\n`worker-stop` or `worker-abandon` explicitly. `unverifiable` is absence,\nincluding when `worker-show` reports `agentWait` null. Absence never authorizes\nstop, abandon, retry, or release; keep waiting or inspect.\n\n`worker-start` is the normal path, composing placement, terminal readiness,\nprompt injection, and supervised resource ownership. `dispatch --inject` leaves\nan operator-created process unsupervised and is only for an expressiveness gap.\n\n## Task-spec contract\n\nEvery Task spec must be self-contained and name:\n\n- **Target:** the files, component, or environment in scope.\n- **Change:** the concrete result to produce.\n- **Constraints:** invariants, compatibility rules, and do-not-touch boundaries.\n- **Ownership:** what this worker may edit and any coordination boundary.\n- **Observable acceptance:** the test, output, or evidence that proves completion.\n\n## Completion accounting\n\nAfter an accepted success or failure report, immediately do exactly one:\n\n1. Reuse the same proven agent terminal for an immediate follow-up Dispatch.\n2. Record user-requested retention with `worker-retain`.\n3. Run `worker-release`.\n\nRelease is post-settlement cleanup, not cancellation. Only an accepted\nsettlement authorizes it; no other observation does. If release is uncertain,\nfollow its exact recovery receipt and never substitute `terminal close`.\n\nA valid `worker_done` settles the Task and Dispatch automatically; do not follow\nit with `task-update --status completed`. Enumerate the terminals still owing a\ndecision with `worker-list --run --terminal-state reclaimable --json`,\nand do not end the coordinator turn until it returns none.\n\n## Conditional references\n\nThis compact guide is sufficient for the normal local loop. At an action gate\nbelow, run `ORCA skills get orchestration --reference references/.md` and\nread only that document; `--references` lists the names. If the CLI rejects\n`--reference`, run `ORCA skills get orchestration --full` once instead: it\nreturns this exact kernel and every reference, so read only the named one. If an\nolder CLI rejects `--full`, keep this kernel's safety floor, use that command's\n`--help`, and never guess newer flags.\n\n| Action gate | Bundled reference |\n| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |\n| Expanded DAG waves, launch model/effort, same-terminal reuse, or review ownership | `references/coordinator-loop.md` |\n| You are a dispatched worker and the live preamble does not answer your question, or `check` returned an error | `references/worker-contract.md` |\n| New worktree, exact workspace, SSH, WSL, or connected-server placement | `references/placement-and-remote.md` |\n| Inbox replay, follow-up messages, group addresses, or decision gates | `references/messaging-and-gates.md` |\n| Failed/stopped/unknown attempts, retry, stop, abandon, retain, or uncertain release | `references/recovery-and-cleanup.md` |\n| Custom argv or terminal topology that `worker-start` cannot express | `references/low-level-topology.md` |\n| Any legacy label, adopted Run, compatibility receipt, or takeover | `references/legacy-contract-migration.md` |\n\nRetired scheduler commands are not aliases for Run creation. Recovery commands\nmust provide their exact next action; follow it with the same selected executable.\n" // oxfmt-ignore -const ORCHESTRATION_FULL_MARKDOWN = "---\nname: orchestration\ndescription: >-\n Coordinate supervised Orca workers: threaded messages, blocking ask/reply,\n task dispatch, worker_done/escalation waits, task DAGs, decision gates,\n coordinator loops, and decomposing work across agents. Use `orca-cli` for full\n ownership handoffs — \"hand off\", \"handoff\", \"handover\", \"give this to another\n agent\", \"another worktree\" — unless asked to supervise, monitor, or coordinate\n a DAG, and for terminal control, lightweight terminal prompts, shell commands,\n Orca worktree management, and reading or waiting on terminals. Use Computer\n Use for external browser windows, webviews, Orca app UI, or desktop UI outside\n Orca's embedded browser only when the task requires OS/window-level control\n such as focus, menus, dialogs, coordinates, or screenshots. Use `orca-cli` for\n Orca's embedded pages and a page-automation tool such as Playwright or CDP for\n external pages.\n---\n\n# Orca orchestration\n\nOrchestration is Orca's structured coordination layer. It records who owns work,\nwhich attempt is authoritative, and when supervised work has settled.\n\n## Outcome\n\n**Result:** every in-scope Task has one explicit outcome and every settled worker\nterminal has a next owner or cleanup decision. **Next consumer:** the user who\nrequested supervision. **Done:** all expected Dispatches have settled, every\ndelivered message was processed before acknowledgment, each settled worker was\nreused, explicitly retained, or released, and the turn ends only when the report\nto that user names, per Task, its outcome, the evidence behind it, and any\nunresolved blocker.\n\n**Safe failure:** preserve work and authority and report the state as unknown or\n`unverifiable`. Only positive proof of exit authorizes stop, abandon, or retry,\nand only an accepted settlement authorizes release. Every other observation,\nabsence included, is a checkpoint.\n\n## Classify the role\n\n| Current context | Role | Route |\n| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------ |\n| The user explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use a decision gate, or manage ask/reply | Coordinator | Use the supervised loop below |\n| The current prompt contains a live injected preamble with Task and Dispatch IDs | Dispatched worker | Follow the preamble and the worker obligations below |\n| The user asks to hand off ownership or start another agent/worktree without supervision | Handoff owner | Use `orca-cli`; create no Run, Task, or Dispatch and do not monitor completion |\n| A message carries a legacy authority label | Compatibility operator | Load the legacy contract reference before any lifecycle mutation |\n| No live preamble and no explicit supervision | Ordinary terminal agent | Do not emit lifecycle messages; use `orca-cli` for terminal/worktree work |\n\nModel or effort selection does not make a handoff supervised. Never substitute a\nnon-Orca subagent tool when Orca orchestration provenance was requested.\n\n## Authority and safety floor\n\n- A Run is a durable namespace and coordinator inbox; it does not schedule or\n place workers. A Task is work. A Dispatch is one authoritative Task attempt.\n- Lifecycle authority comes from the active Dispatch, not a terminal title,\n copied ID, old database row, provider transcript, or visible pane.\n- Workers use the exact executable, handle, capability, Task ID, and Dispatch ID\n in the live preamble. Never reconstruct, translate, or broaden those arguments.\n- After remote start, address the worker by Dispatch ID. The execution host owns\n process, filesystem, transcript, stop, and cleanup facts. Preserve the verdicts\n `live` / `unverifiable` / `exited`; contact loss is not process death.\n- Liveness is layered: `worker-list`'s `projection.liveness` is the fleet verdict\n for the agent; `worker-show`'s `observation.status` is PTY liveness only. A live\n terminal can still hold a dead or stuck agent.\n- Folder workspaces are valid; never require Git or assume a worktree.\n- Clients and remote servers update independently. Treat unknown optional fields\n as absent. A new stream operation requires advertised capability because old\n decoders may silently drop unknown opcodes. Never fall back to local execution\n when remote authority or capability is unproven.\n- Use the executable you used to run `skills get` for the entire run. In the\n examples below, replace `ORCA` with it; do not create a shell variable or run\n `ORCA` literally. If it fails, report that exact error instead of switching.\n- A successful `orchestration send` proves durable enqueue; its wake or nudge is\n best-effort attention only and does not prove the recipient read or accepted it.\n\n## Worker obligations\n\nThe injected preamble is authoritative. A dispatched worker must:\n\n1. Do only the current Task and use the preamble's `ask` command for a blocking\n coordinator question. Never open a local question TUI the coordinator cannot\n answer. Resume the same message ID after an ask timeout.\n2. Send heartbeats only at the cadence in the preamble. A heartbeat proves\n liveness, not completion.\n3. Read coordinator follow-ups at each natural checkpoint — before starting a\n new file, after a test run — and once more immediately before `worker_done`:\n `ORCA orchestration check --terminal --json`.\n4. Send `worker_done` exactly once, from the dispatched terminal, with a\n three-sentence executive summary, both lifecycle IDs, and explicit\n `--outcome succeeded` or `--outcome failed`. Never encode failure only in prose.\n5. Append `--files-modified` and `--report-path` only with real values when\n applicable. After `worker_done`, end the dispatched turn and idle; do not poll\n or start new work.\n\nA direct user instruction after completion starts new user-owned work and takes\nprecedence over the idle rule. Do not reuse the settled lifecycle IDs.\n\n## Canonical supervised loop\n\nConfirm the runtime, bind one Run, and start the full independent wave before\nwaiting. `worker-start --spec` creates the Task and its attempt in one call:\n\n```text\nORCA status --json\nORCA orchestration run-create --objective \"\" --json\nORCA orchestration worker-start --spec \"\" --worktree current --agent codex --json\nORCA orchestration worker-start --spec \"\" --worktree current --agent claude --json\nORCA orchestration check --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json\n```\n\nIf `worker-start` exits non-zero, do not relaunch. Read the receipt's\n`failedStage` and `residualResources`, then load\n`references/recovery-and-cleanup.md`.\n\nUse `task-create` plus `worker-start --task ` for planned fan-out with\ndependencies or a retry of a known Task. Use dependencies only for real ordering\nand prefer parallel waves over chains deeper than three or four steps; nested\nworkers obey the depth limit, and a new Run does not reset the caller's depth.\n\nA consuming `check` names its caller with `--terminal `, never `--from`;\nomit it inside the coordinator's own Orca terminal. It returns the bound Run's\noldest FIFO Delivery and replays that batch until acknowledged. Process every\nmessage: reply to questions, validate each `worker_done` against the expected\nactive Dispatch, and decide each settled terminal's next owner before the ack:\n\n```text\nORCA orchestration reply --id --body \"\" --json\nORCA orchestration worker-release --dispatch --json\nORCA orchestration check --ack --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json\n```\n\nKeep waiting until every expected Dispatch settles. A timeout or empty result is\na checkpoint, not a failure. Do not stop, retry, release, or launch a duplicate\neditor without the positive proof `## Outcome` requires.\n\nAfter three consecutive empty waits, stop waiting blindly and enumerate with\n`ORCA orchestration worker-list --include-remote --json` (defaults to the bound\nRun; `--run ` overrides; the receipt's `scope` names which), acting on\neach row's `projection.attention` categories, `projection.attention.requiresAction`, and literal `projection.nextAction` argv.\nAn `inspect` `nextAction` on a `live` row with `attention.requiresAction` false\nis informational, not a command to re-run: keep waiting with `check --wait`.\nLeave the wait only on positive proof the agent stopped: `exited` liveness, the\nworker's own observation of process exit, or a transcript whose final agent turn\nsent no `worker_done`. Then load `references/recovery-and-cleanup.md` and choose\n`worker-stop` or `worker-abandon` explicitly. `unverifiable` is absence,\nincluding when `worker-show` reports `agentWait` null. Absence never authorizes\nstop, abandon, retry, or release; keep waiting or inspect.\n\n`worker-start` is the normal path, composing placement, terminal readiness,\nprompt injection, and supervised resource ownership. `dispatch --inject` leaves\nan operator-created process unsupervised and is only for an expressiveness gap.\n\n## Task-spec contract\n\nEvery Task spec must be self-contained and name:\n\n- **Target:** the files, component, or environment in scope.\n- **Change:** the concrete result to produce.\n- **Constraints:** invariants, compatibility rules, and do-not-touch boundaries.\n- **Ownership:** what this worker may edit and any coordination boundary.\n- **Observable acceptance:** the test, output, or evidence that proves completion.\n\n## Completion accounting\n\nAfter an accepted success or failure report, immediately do exactly one:\n\n1. Reuse the same proven agent terminal for an immediate follow-up Dispatch.\n2. Record user-requested retention with `worker-retain`.\n3. Run `worker-release`.\n\nRelease is post-settlement cleanup, not cancellation. Only an accepted\nsettlement authorizes it; no other observation does. If release is uncertain,\nfollow its exact recovery receipt and never substitute `terminal close`.\n\nA valid `worker_done` settles the Task and Dispatch automatically; do not follow\nit with `task-update --status completed`. Enumerate the terminals still owing a\ndecision with `worker-list --run --terminal-state reclaimable --json`,\nand do not end the coordinator turn until it returns none.\n\n## Conditional references\n\nThis compact guide is sufficient for the normal local loop. At an action gate\nbelow, run `ORCA skills get orchestration --reference references/.md` and\nread only that document; `--references` lists the names. If the CLI rejects\n`--reference`, run `ORCA skills get orchestration --full` once instead: it\nreturns this exact kernel and every reference, so read only the named one. If an\nolder CLI rejects `--full`, keep this kernel's safety floor, use that command's\n`--help`, and never guess newer flags.\n\n| Action gate | Bundled reference |\n| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |\n| Expanded DAG waves, launch model/effort, same-terminal reuse, or review ownership | `references/coordinator-loop.md` |\n| You are a dispatched worker and the live preamble does not answer your question, or `check` returned an error | `references/worker-contract.md` |\n| New worktree, exact workspace, SSH, WSL, or connected-server placement | `references/placement-and-remote.md` |\n| Inbox replay, follow-up messages, group addresses, or decision gates | `references/messaging-and-gates.md` |\n| Failed/stopped/unknown attempts, retry, stop, abandon, retain, or uncertain release | `references/recovery-and-cleanup.md` |\n| Custom argv or terminal topology that `worker-start` cannot express | `references/low-level-topology.md` |\n| Any legacy label, adopted Run, compatibility receipt, or takeover | `references/legacy-contract-migration.md` |\n\nRetired scheduler commands are not aliases for Run creation. Recovery commands\nmust provide their exact next action; follow it with the same selected executable.\n\n---\n\n# Bundled references\n\nThese references belong to the version-matched guide above. Read only the documents named by its action gates.\n\n\n\n# Coordinator loop\n\nLoad this reference for expanded DAG waves, per-invocation launch preferences,\nsame-terminal reuse, or review ownership. The compact guide remains the source\nof truth for the loop order and completion boundary.\n\n## Ready waves\n\nCreate independent Tasks before the first wait. Encode only real dependencies,\nthen use the ready view as external memory:\n\n```text\nORCA orchestration task-create --spec \"\" --deps --json\nORCA orchestration task-list --ready --brief --json\n```\n\n`--brief` collapses whitespace and caps echoed specs at 160 characters;\n`spec_truncated` identifies shortened rows. Omit it when full specs are needed or\nwhen an older CLI rejects the flag. A nested worker must respect\n`nested_worker_depth_exceeded`; creating another Run does not reset depth.\n\n## Launch preferences\n\nFor a fresh Claude, Codex, or Cursor terminal, `--model` accepts an opaque\nprovider model ID. Pass it only when the user named a model; otherwise omit it\nso the worker inherits the user's configured agent default. Add `--effort` only\nwhen that model supports it:\n\n```text\nORCA orchestration worker-start --task --worktree current --agent claude --model opus --effort high --json\n```\n\n`--effort` requires `--model`; neither option combines with `--terminal`. A\nconnected worker server must advertise launch-preference support before Orca\nforwards either field. Compare `launch.requested` with `launch.effective`; never\nclaim a model or effort from requested arguments alone.\n\n## Reuse after settlement\n\nChoose the terminal's next owner before acknowledging the Delivery. When the\nsame exact agent has immediate follow-up work, recover the proven handle and\ntransfer cleanup ownership to the new Dispatch:\n\n```text\nORCA orchestration worker-show --dispatch --json\nORCA orchestration worker-start --task --terminal --json\n```\n\nOtherwise explicitly retain or release the settled worker. Do not leave it live\nonly to inspect output; archived output remains available through `worker-read`.\n\n## Review ownership\n\nA review-only `worker_done` authorizes synthesis of findings, not coordinator\nfile edits. Dispatch or hand off fixes unless the user explicitly assigned them\nto the coordinator. If the user's plan names a next owner, post-review fixes and\nPR preparation remain with that owner; the coordinator routes and synthesizes.\n\n\n\n# Legacy contract migration\n\nLoad this reference only for an authority label, adopted Run, compatibility or\nrecovery receipt, or explicit legacy takeover. A newly created attempt always\nuses the current grammar.\n\n## Authority labels\n\n- `[LEGACY COMPATIBILITY]` is live and attested. Run only the exact supported\n command printed with the message, using the same selected executable and\n arguments supplied by the original prompt.\n- `[LEGACY RECOVERY REPLAY — MAY HAVE BEEN SEEN]` is one bounded,\n at-least-once cutover replay. Process it idempotently and acknowledge only\n through the exact displayed guidance.\n- `[LEGACY READ-ONLY]` is inspection-only. It has no reply, acknowledgment, or\n lifecycle mutation.\n- An unlabeled current message uses the current guide and grammar.\n\nAn explicitly selected current Run, attested current binding, current Dispatch,\nor federated attachment takes precedence over legacy fallback. A retained\nadoption record alone does not grant mutation authority. If liveness, principal\nownership, capability, or the exact legacy contract is unproven, degrade to\nread-only inspection and never fall back to local execution.\n\nAdoption preserves the live agent process, PTY/session, terminal handle,\ntab/pane, worktree or folder workspace, Task, and Dispatch. It never restarts or\nreplaces the worker and never revives the retired scheduler. Loss of lifecycle\nauthority does not invalidate the existing process, assignment, or filesystem\nwork. Exact recovery may restore the same PTY once in its original inactive\nbackground tab; it must not spawn, write, signal, stop, switch, focus, split, or\ninject a terminal.\n\n## Compatibility recovery\n\nWhen a compatibility response returns structured next-step arguments, execute\nthose exact arguments with the same selected CLI executable. Do not translate\nfrom memory, broaden the recipient, or retry as a current mutation unless the\nreceipt explicitly authorizes it.\n\nA pending ask, reply, final Dispatch settlement, and consuming check have\ndurable recovery identities. Heartbeat and escalation remain at-least-once\nacross a manual contract-boundary retry. If an ask may already have been\nanswered, run the exact non-consuming recovery check printed by Orca before\ncreating any new question. Never guess among identical question threads.\n\nOn packaged Windows, a legacy ask uses a two-step commit/resume protocol. The\ninitial command commits the question, prints its exact\n`ask --resume ` command, and exits with launcher status `75`. Run\nthat exact resume after the launcher or update boundary. For an attested WSL\nlaunch, preserve the printed `orca-ide` executable and distro route. Older WSL\nworkers without launch proof remain lifecycle read-only even while their\nterminal and filesystem work continue.\n\n## Read-only inspection and takeover\n\nRead-only inspection does not consume mail:\n\n```text\nORCA orchestration run-list --json\nORCA orchestration run-show --id run_legacy_local --json\nORCA orchestration run-show --id --json\nORCA orchestration task-list --run --json\nORCA orchestration inbox --full --json\nORCA orchestration check --terminal --peek --format --json\nORCA terminal read --terminal --json\nORCA terminal wait --terminal --for tui-idle --timeout-ms 60000 --json\n```\n\n`run_legacy_local` is an empty audit tombstone after adoption. Find the ordinary\nRun whose objective is `Recovered orchestration work from a contract update`.\n\nOnly when the original coordinator is unavailable or cannot prove retained\nauthority may a new live coordinator take over from its own terminal:\n\n```text\nORCA orchestration run-use --id --takeover-legacy --json\nORCA orchestration check --run --json\n```\n\nTakeover binds the authenticated invoking terminal; `--from` cannot nominate\nanother coordinator. It fences only the old coordinator and moves pending mail\ninto current Run delivery. It preserves live workers, Tasks, Dispatches, processes, and files.\nNever take over while the original coordinator is actively coordinating.\n\nDo not launch a replacement editor merely because Orca updated or authority is\nunclear. Keep the original worker as the only editor until a stable handoff\npoint, then use a fresh current Dispatch in a conflict-free placement.\n\n\n\n# Low-level topology\n\nLoad this reference only when `worker-start` cannot express required custom argv\nor terminal topology. It is not the normal supervised loop and is never a full\nhandoff recipe.\n\n```text\nORCA terminal create --worktree active --title --command \"\" --json\nORCA terminal wait --terminal --for tui-idle --timeout-ms 60000 --json\nORCA orchestration dispatch --task --to --inject --json\n```\n\nWait for readiness only when startup could lose injected input. Prefer\nagent-first `worker-start` whenever its argv and topology are sufficient.\n\n`dispatch --inject` creates authoritative Task/Dispatch context but deliberately\nkeeps an operator-created process unsupervised: it creates no supervised worker\nresource row. `worker-show`, `worker-read`, and `worker-list` report the lane as\n`unsupervised`; `worker-stop` and `worker-abandon` do not close that process, and\nsettled retain/release take no process action.\n\nUse `worker-start --terminal ` when lifecycle ownership of an existing\nagent terminal is required. Never imply that low-level dispatch retroactively\nowns a process, never use it to route around the nested-depth limit, and never\nuse it for an ownership handoff.\n\n\n\n# Messaging and gates\n\nLoad this reference for inbox replay, attempt-specific guidance, group\naddresses, blocking questions, or coordinator-managed DAG decisions.\n\nA successful `send` proves durable enqueue. Wake and nudge are best-effort\nattention only: neither proves the recipient read the message, began a turn, or\naccepted steering.\n\n## Coordinator delivery loop\n\n`check` names its caller with `--terminal ` and is the only verb that\nrejects `--from`. Omit `--terminal` inside an Orca terminal, where Orca resolves\nthe caller; pass it explicitly from anywhere else, including a dispatched\nworker reading coordinator follow-ups.\n\nA consuming coordinator `check` returns the bound Run's oldest FIFO Delivery,\nup to 50 messages, and replays that exact batch until acknowledged. Process\nevery row and required terminal ownership decision before `--ack`. Type filters\ndecide when a waiter wakes; they do not authorize skipping older actionable\nmail. A Delivery therefore always carries the whole FIFO batch whatever its\ntypes, and a `check` without `--wait` hands that batch over unfiltered.\n`--peek` and `--all` are read-only inspection, not progress through the\ncoordinator inbox.\n\nAn empty wait or timeout is a checkpoint. Continue rolling waits until every\nexpected Dispatch settles. Heartbeat or visible activity means alive, not done.\n\n## Addresses\n\nUse a stable Dispatch address for attempt-specific coordinator guidance:\n\n```text\nORCA orchestration send --to dispatch: --subject \"Follow-up\" --body \"\" --json\n```\n\nDo not substitute a remote terminal handle. Omit `--from` for ordinary\ncoordinator calls; a dispatched worker instead copies the exact `--from` and\ncapability arguments in its preamble. `check` is the exception: it identifies\nits caller with `--terminal`, never `--from`.\n\nGroup addresses include `@all`, `@idle`, `@claude`, `@codex`, `@opencode`,\n`@gemini`, `@droid`, `@grok`, `@cursor`, and `@worktree:`. Use them only for\nintentional fan-out status or questions. `worker_done`, heartbeat, and other\nDispatch lifecycle messages never target groups.\n\n## Questions and gates\n\nA worker uses `ask`; its timeout leaves one durable question pending, which the\nworker resumes by message ID. The coordinator answers that message with `reply`.\n\nUse a gate only for a coordinator-owned Task-DAG decision:\n\n```text\nORCA orchestration gate-create --task --question \"\" --options --json\nORCA orchestration gate-resolve --id --resolution \"\" --json\nORCA orchestration gate-list --task --json\n```\n\nPass `json_array` using the quoting rules of the active shell; do not copy POSIX\nsingle-quote syntax into PowerShell or `cmd.exe`.\n\nDo not create a gate merely to answer a worker's `ask`.\n\n\n\n# Placement and remote execution\n\nLoad this reference before creating a new worktree or placing work through SSH,\nWSL, or another connected Orca server.\n\n## Placement choices\n\nA fresh worker means a fresh agent terminal, not a new Git worktree. Use the\ncurrent or an exact existing workspace by default. Create a worktree only when\nthe user requested one or a concrete checkout or filesystem conflict makes\nsharing unsafe.\n\n```text\n# Current workspace; setup is not rerun.\nORCA orchestration worker-start --task --worktree current --agent codex --json\n\n# Stacked child worktree.\nORCA orchestration worker-start --task --worktree new-child --name --agent codex --setup run --json\n\n# Independent top-level worktree.\nORCA orchestration worker-start --task --worktree new-top-level --name --agent codex --setup run --json\n```\n\nCurrent and exact existing workspaces create a fresh terminal unless\n`--terminal` is explicit. Folder workspaces are first-class; do not invoke Git\nor require worktree lineage when the selected workspace is a folder.\n\nRegister a folder workspace through project setup. `repo add --path `\nrequires a valid Git repository and rejects a plain directory:\n\n```text\nORCA project setup-existing-folder --project --host --path --kind folder --json\n```\n\nThen place work on the returned workspace with an exact selector. A worktree\nselector needs the full `::` value Orca returned, passed as\n`id:`; a bare repo id is not a worktree id. `new-child` and\n`new-top-level` are worktree creation and do not apply to a folder.\n\nNew worktrees use agent-first creation and run setup by default. Preserve the\nrepository's startup policy: `start-immediately` can report setup as `running`,\nwhile `wait-for-setup` gates prompt delivery on success. Orca lineage, Git base,\nfilesystem isolation, coordination parentage, UI grouping, and execution host\nare separate decisions.\n\n## Connected servers\n\nThe Run and Tasks remain authoritative on the current server. `--on` selects\nonly the worker's execution server and appears only on `worker-start`:\n\n```text\nORCA orchestration worker-start --task --on --worktree new-top-level --repo --name --agent codex --setup run --json\n```\n\nRemote `current` and `new-child` are invalid because they are ambiguous across\nservers. Use an exact discovered remote workspace, or `new-top-level` with an\nexact remote repository selector. After start, route every follow-up, read,\nstop, and cleanup by Dispatch ID; never repeat `--on` or substitute a remote\nterminal handle.\n\n```text\nORCA orchestration worker-show --dispatch --json\nORCA orchestration worker-read --dispatch --limit 50 --json\nORCA orchestration send --to dispatch: --subject \"Follow-up\" --body \"\" --json\nORCA orchestration worker-list --run --include-remote --json\n```\n\n`worker-list` reads local fleet state only; enumerate remote workers with\n`--include-remote` or every one of them reads `unverifiable`. Scope every list\nwith `--run `: unscoped, it reports every Dispatch this runtime has\nrecorded, and the workers you are waiting on are lost in that history.\n\n## Execution-host and mixed-version floor\n\nThe execution host owns process, filesystem, transcript, stop, and cleanup\nfacts. Render only `live`, `unverifiable`, or `exited`. Connection loss, relay\nabsence, missing client inventory, or timeout yields `unverifiable`, never\nsynthetic exit and never a client-local substitute action.\n\nClients and servers update independently. Optional response fields may be\nabsent. Forward model/effort, transcript reads, cleanup, or another new remote\noperation only when the peer advertises the relevant capability; unknown stream\nopcodes can be silently dropped. A narrow unsupported response may degrade to a\ndocumented older path, but must not broaden the target or cross the execution\nboundary. Changing host-published content reaches old clients even without a\nwire-shape change, so preserve established semantics or negotiate the behavior.\n\nFor WSL, use the exact executable and arguments returned by Orca so the distro\nand packaged launcher remain bound. Do not translate a printed `orca-ide`\nrecovery command into a PATH-resolved local command.\n\n\n\n# Recovery and cleanup\n\nLoad this reference only after a failed/stopped/unknown attempt, explicit retry\ndecision, stop/abandon request, retention request, or uncertain release.\n\n| Proven state | Safe action |\n| ----------------------- | ------------------------------------------------------------------ |\n| `ready` or active | Keep waiting; optionally read bounded output |\n| `failed` or `stopped` | Start a replacement with `--retry-of`; repeat placement explicitly |\n| `outcome_unknown` | Inspect, then choose `worker-stop` or explicit `worker-abandon` |\n| Accepted `worker_done` | Reuse, retain, or release |\n| Remote contact lost | Preserve `unverifiable`; do not stop or retry from absence alone |\n| `unverifiable` liveness | Keep waiting or inspect; never stop, abandon, retry, or release |\n| Proven `exited` agent | Enumerate with `worker-list`; follow its `nextAction` |\n\n## Inspect before acting\n\n```text\nORCA orchestration worker-list --run --json\nORCA orchestration worker-list --run --include-remote --json\nORCA orchestration worker-show --dispatch --json\nORCA orchestration worker-read --dispatch --limit 50 --json\n```\n\n`worker-list` is the enumerating command and the authority on agent liveness:\neach row carries `projection.liveness`, `projection.attention.categories`,\n`projection.attention.requiresAction`, and a literal `projection.nextAction`\nargv to run. Always scope it with `--run `; an unscoped list reports\nevery Dispatch this runtime has ever recorded and buries the live ones.\n`worker-show`'s `observation.status` is PTY liveness only, so a `live` terminal\nwhose agent died at a trust prompt still reads `live` there.\n\nWhen the two disagree, the fleet verdict decides — unless the fleet row is\n`unverifiable` for a reason that names a gap on this client rather than a fact\nabout the worker. `missing_status`, `host_unavailable`, and\n`capability_unsupported` are such gaps: the first means this runtime holds no\nstatus row, the second that it could not ask the execution host at all, and the\nthird that a stale peer answered but lacks the fleet-snapshot capability.\nAgainst any of them, a `worker-show` verdict sourced from the execution host is\nthe better evidence and outranks the row. Only `host_unavailable` is contact\nloss; the other two mean the host was never asked or answered without the\ncapability.\n\nThis never promotes absence. `unverifiable` from either command still authorizes\nnothing — only a positive `live` or `exited` verdict does.\n\nA worker started with `--on ` reads `unverifiable` until you\nenumerate with `--include-remote`, which asks its execution host for the\nverdict. Past 100 rows the response pages, so follow `page.nextCursor` with\n`--cursor ` until `page.hasMore` is false.\n\n## Stall needs positive evidence\n\nLeave the wait only on positive proof the agent stopped: `exited` liveness, the\nworker's own observation of process exit, or a transcript whose final agent turn\nsent no `worker_done`. Only then choose `worker-stop` or `worker-abandon`.\n\n`unverifiable` is always absence — `missing_status`, `stale_status`,\n`restored_unconfirmed`, or a remote worker with no connection — and a null\n`agentWait` or an unchanged `worker-read` tail is that same absence seen again.\nAbsence never authorizes stop, abandon, retry, or release: keep waiting, or\ninspect until you hold one of the positive signals above. A `nextAction` that\nnames an inspecting command is asking for evidence, not for cleanup.\n\n`worker-read --source auto` uses a proven provider transcript when available and\notherwise returns bounded terminal output with a typed `fallbackReason`.\nContinue with its top-level cursor, which is pinned to that source. If Orca\nreports `source_changed`, restart without the old cursor. A bounded initial\ntranscript tail can return an EOF cursor that follows only newly appended records;\nread `contentComplete`, `clipping`, and `warnings` before assuming omitted older\nrecords are pageable. Never guess a provider session ID, transcript path, or\nremote terminal handle.\n\n## Was the mutation applied?\n\nWhen a mutation's response was lost and named no Dispatch, do not replay blind.\nEvery orchestration mutation accepts `--retry-request `, which reuses one\noperation identity so Orca can replay, join, or recover it instead of starting a\nduplicate. Ask what happened first:\n\n```text\nORCA orchestration request-show --request --json\n```\n\n`completed` means the mutation already took effect; read its recorded receipt\ninstead of rerunning. `pending` means the original mutation is still running or\nOrca restarted before recording its outcome; replay the original command with\n`--retry-request `. `absent` means this runtime holds no receipt\nunder your caller identity — that is not proof nothing happened, so inspect the\naffected Task, Dispatch, and terminal before deciding whether to retry.\n\nWhen a worker's terminal accepted input but the submit is unconfirmed, use\n`terminal send --wait-submit `: it observes the accepted prompt for that\nlong and, on timeout, returns the input-accepted receipt without resending.\n\n## Refused starts\n\n`dispatch` and `worker-start` refuse the following preflight cases with a stable\n`error.code`; read it before choosing a recovery, and treat `error.data.nextSteps`\nas the exact recovery text. Older hosts may omit `data`, so treat every field as\noptional.\n\n| Code | Meaning | Recovery |\n| -------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `task_not_found` | No Task with that id, or not in the bound Run (`data.taskId`, `data.runId`) | Check `task-list --json`; create the Task with `task-create` if it does not exist |\n| `task_not_startable` | Task cannot start now: not `ready`, or invalid `--retry-of` (`data.status`, `data.unmetDependencies`, `data.retryOf`) | Wait for running dependencies with `check --wait`; retry or unblock failed ones; inspect `dispatch-show` if already dispatched |\n| `inject_rejected` | `--inject` refused because no recognized agent runs in the target (`data.terminal`, `data.reason`) | Start a recognized agent there or pick another terminal; or dispatch without `--inject` and use `terminal send` |\n| `runtime_error` | Any other failure, including a target terminal that already owns an active Dispatch | Read the message, inspect state, and do not retry unchanged |\n\n## Retry, stop, and abandon\n\nRetry only a positively proven failed or stopped attempt. Name the failed Task\nwith `--task`, since `--spec` creates a new one. Placement is never silently\ninherited:\n\n```text\nORCA orchestration worker-start --task --retry-of --worktree --agent --json\n```\n\nAfter three consecutive failures for one Task, its dispatch context\ncircuit-breaks and the Task is failed. Do not route around that boundary with a\nnew Run or an unrelated Dispatch.\n\nFor `outcome_unknown`, inspect first, then make an explicit choice:\n\n```text\nORCA orchestration worker-stop --dispatch --json\nORCA orchestration worker-abandon --dispatch --json\n```\n\n`worker-stop` closes only the exact proven supervised agent terminal. It never\ndeletes the worktree, setup terminal, configured tabs, or unrelated processes.\n`worker-abandon` fences orchestration while accepting that resources may remain\nlive; it performs no remote, process, or filesystem action.\n\n## Retain and release\n\n```text\nORCA orchestration worker-retain --dispatch --json\nORCA orchestration worker-release --dispatch --json\n```\n\nRetain only when the user explicitly wants the settled terminal kept live.\nRelease works after succeeded and failed reports, archives readable output, and\ncloses only the exact terminal owned by that settled Dispatch. Replays may call\nrelease again safely. Reused, pre-existing, setup, coordinator, active,\nuser-taken-over, and unproven terminals are retained.\n\nA `worker-start` that failed before its agent was ready still owns the terminal\nit created. Its receipt names `worker-release`, and `worker-list` reports that\nrow as `reclaimable`; release it there rather than closing the terminal by hand.\n\nNever release because of timeout, TUI idle, heartbeat, status, question,\nescalation, or stale/rejected completion. If the receipt says `release_pending`\nor `release_unknown`, follow its exact recovery action. Never substitute\n`terminal close`.\n\n`orchestration reset` is destructive recovery. Do not run it during active\ncoordination unless the user explicitly abandons that state.\n\n\n\n# Worker contract\n\nThe injected preamble is authoritative. Copy its command rather than\nreconstructing flags. In particular, preserve the exact executable, worker\nhandle, Dispatch capability, Task ID, and Dispatch ID.\n\n## Heartbeat\n\nSend heartbeats only at the cadence required by the live preamble. Skip them\nwhile blocked inside `ask` or `check --wait`; those calls are liveness signals.\n\n```text\nORCA orchestration send --from --dispatch-capability --type heartbeat --subject \"alive\" --task-id --dispatch-id --phase \"\"\n```\n\nUse typed lifecycle flags, not a hand-written JSON payload. A heartbeat proves\nliveness, never completion.\n\n## Ask and resume\n\nUse Orca `ask` whenever the coordinator must answer. Never open a local question\nTUI the coordinator cannot answer.\n\n```text\nORCA orchestration ask --from --dispatch-capability --question \"\" --options \",\" --timeout-ms 600000\n\nORCA orchestration ask --from --dispatch-capability --resume --timeout-ms 600000\n```\n\nA timeout or disconnect leaves the original question pending. Resume its\nmessage ID; do not create a duplicate question.\n\n## Reading coordinator follow-ups\n\nThe coordinator steers a running worker with `send --to dispatch:`. That\nenqueue is durable but does not interrupt you, so nothing arrives unless you\nlook:\n\n```text\nORCA orchestration check --terminal --json\n```\n\nRun it at each natural checkpoint — before starting a new file, after a test\nrun — and once more immediately before `worker_done`, so a redirect or a\ncancellation lands before the Task settles. `check` names its caller with\n`--terminal`, never `--from`. Stop checking after `worker_done`.\n\nIf `check` returns `consumer_fenced`, this process no longer owns its Dispatch:\nthe Attempt was re-attached to another worker or settled without you. Stop, do\nnot send `worker_done`, and do not retry the check. An empty `check` never means\nyou were replaced; `consumer_fenced` is the only way you learn that.\n\n## Escalation\n\nEscalate only before completion and only when the coordinator must intervene:\n\n```text\nORCA orchestration send --from --dispatch-capability --type escalation --subject \"Blocked: \" --body \"
\" --task-id --dispatch-id \n```\n\n## Completion\n\nSend exactly one terminal report. `--body` is three sentences: what changed,\nwhat was found, and what remains. Use `--outcome failed` when the requested work\nis not complete; never hide failure in prose or silently exit.\n\nAppend `--files-modified` or `--report-path` only when applicable, using actual\npaths. Do not send documentation placeholders as metadata.\n\n```text\nORCA orchestration send --from --dispatch-capability --type worker_done --subject \"\" --body \"\" --task-id --dispatch-id --outcome succeeded\n```\n\nAfter `worker_done`, end the dispatched turn and idle. Do not poll, close your\nown terminal, or begin unrelated work. A later direct user instruction is new\nuser-owned work and must not reuse settled lifecycle IDs; a supervised follow-up\narrives with a fresh preamble and Task block.\n" +const ORCHESTRATION_FULL_MARKDOWN = "---\nname: orchestration\ndescription: >-\n Coordinate supervised Orca workers: threaded messages, blocking ask/reply,\n task dispatch, worker_done/escalation waits, task DAGs, decision gates,\n coordinator loops, and decomposing work across agents. Use `orca-cli` for full\n ownership handoffs — \"hand off\", \"handoff\", \"handover\", \"give this to another\n agent\", \"another worktree\" — unless asked to supervise, monitor, or coordinate\n a DAG, and for terminal control, lightweight terminal prompts, shell commands,\n Orca worktree management, and reading or waiting on terminals. Use Computer\n Use for external browser windows, webviews, Orca app UI, or desktop UI outside\n Orca's embedded browser only when the task requires OS/window-level control\n such as focus, menus, dialogs, coordinates, or screenshots. Use `orca-cli` for\n Orca's embedded pages and a page-automation tool such as Playwright or CDP for\n external pages.\n---\n\n# Orca orchestration\n\nOrchestration is Orca's structured coordination layer. It records who owns work,\nwhich attempt is authoritative, and when supervised work has settled.\n\n## Outcome\n\n**Result:** every in-scope Task has one explicit outcome and every settled worker\nterminal has a next owner or cleanup decision. **Next consumer:** the user who\nrequested supervision. **Done:** all expected Dispatches have settled, every\ndelivered message was processed before acknowledgment, each settled worker was\nreused, explicitly retained, or released, and the turn ends only when the report\nto that user names, per Task, its outcome, the evidence behind it, and any\nunresolved blocker.\n\n**Safe failure:** preserve work and authority and report the state as unknown or\n`unverifiable`. Only positive proof of exit authorizes stop, abandon, or retry,\nand only an accepted settlement authorizes release. Every other observation,\nabsence included, is a checkpoint.\n\n## Classify the role\n\n| Current context | Role | Route |\n| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------ |\n| The user explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use a decision gate, or manage ask/reply | Coordinator | Use the supervised loop below |\n| The current prompt contains a live injected preamble with Task and Dispatch IDs | Dispatched worker | Follow the preamble and the worker obligations below |\n| The user asks to hand off ownership or start another agent/worktree without supervision | Handoff owner | Use `orca-cli`; create no Run, Task, or Dispatch and do not monitor completion |\n| A message carries a legacy authority label | Compatibility operator | Load the legacy contract reference before any lifecycle mutation |\n| No live preamble and no explicit supervision | Ordinary terminal agent | Do not emit lifecycle messages; use `orca-cli` for terminal/worktree work |\n\nModel or effort selection does not make a handoff supervised. Never substitute a\nnon-Orca subagent tool when Orca orchestration provenance was requested.\n\n## Authority and safety floor\n\n- A Run is a durable namespace and coordinator inbox; it does not schedule or\n place workers. A Task is work. A Dispatch is one authoritative Task attempt.\n- Lifecycle authority comes from the active Dispatch, not a terminal title,\n copied ID, old database row, provider transcript, or visible pane.\n- Workers use the exact executable, handle, capability, Task ID, and Dispatch ID\n in the live preamble. Never reconstruct, translate, or broaden those arguments.\n- After remote start, address the worker by Dispatch ID. The execution host owns\n process, filesystem, transcript, stop, and cleanup facts. Preserve the verdicts\n `live` / `unverifiable` / `exited`; contact loss is not process death.\n- Liveness is layered: `worker-list`'s `projection.liveness` is the fleet verdict\n for the agent; `worker-show`'s `observation.status` is PTY liveness only. A live\n terminal can still hold a dead or stuck agent.\n- Folder workspaces are valid; never require Git or assume a worktree.\n- Clients and remote servers update independently. Treat unknown optional fields\n as absent. A new stream operation requires advertised capability because old\n decoders may silently drop unknown opcodes. Never fall back to local execution\n when remote authority or capability is unproven.\n- Use the executable you used to run `skills get` for the entire run. In the\n examples below, replace `ORCA` with it; do not create a shell variable or run\n `ORCA` literally. If it fails, report that exact error instead of switching.\n- A successful `orchestration send` proves durable enqueue; its wake or nudge is\n best-effort attention only and does not prove the recipient read or accepted it.\n\n## Worker obligations\n\nThe injected preamble is authoritative. A dispatched worker must:\n\n1. Do only the current Task and use the preamble's `ask` command for a blocking\n coordinator question. Never open a local question TUI the coordinator cannot\n answer. Resume the same message ID after an ask timeout.\n2. Send heartbeats only at the cadence in the preamble. A heartbeat proves\n liveness, not completion.\n3. Read coordinator follow-ups at each natural checkpoint — before starting a\n new file, after a test run — and once more immediately before `worker_done`:\n `ORCA orchestration check --terminal --json`.\n4. Send `worker_done` exactly once, from the dispatched terminal, with a\n three-sentence executive summary, both lifecycle IDs, and explicit\n `--outcome succeeded` or `--outcome failed`. Never encode failure only in prose.\n5. Append `--files-modified` and `--report-path` only with real values when\n applicable. After `worker_done`, end the dispatched turn and idle; do not poll\n or start new work.\n\nA direct user instruction after completion starts new user-owned work and takes\nprecedence over the idle rule. Do not reuse the settled lifecycle IDs.\n\n## Canonical supervised loop\n\nConfirm the runtime, bind one Run, and start the full independent wave before\nwaiting. `worker-start --spec` creates the Task and its attempt in one call:\n\n```text\nORCA status --json\nORCA orchestration run-create --objective \"\" --json\nORCA orchestration worker-start --spec \"\" --worktree current --agent codex --json\nORCA orchestration worker-start --spec \"\" --worktree current --agent claude --json\nORCA orchestration check --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json\n```\n\nIf `worker-start` exits non-zero, do not relaunch. Read the receipt's\n`failedStage` and `residualResources`, then load\n`references/recovery-and-cleanup.md`.\n\nUse `task-create` plus `worker-start --task ` for planned fan-out with\ndependencies or a retry of a known Task. Use dependencies only for real ordering\nand prefer parallel waves over chains deeper than three or four steps; nested\nworkers obey the depth limit, and a new Run does not reset the caller's depth.\n\nA consuming `check` names its caller with `--terminal `, never `--from`;\nomit it inside the coordinator's own Orca terminal. It returns the bound Run's\noldest FIFO Delivery and replays that batch until acknowledged. Process every\nmessage: reply to questions, validate each `worker_done` against the expected\nactive Dispatch, and decide each settled terminal's next owner before the ack:\n\n```text\nORCA orchestration reply --id --body \"\" --json\nORCA orchestration worker-release --dispatch --json\nORCA orchestration check --ack --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json\n```\n\nKeep waiting until every expected Dispatch settles. A timeout or empty result is\na checkpoint, not a failure. Do not stop, retry, release, or launch a duplicate\neditor without the positive proof `## Outcome` requires.\n\nAfter three consecutive empty waits, stop waiting blindly and enumerate with\n`ORCA orchestration worker-list --include-remote --json` (defaults to the bound\nRun; `--run ` overrides; the receipt's `scope` names which), acting on\neach row's `projection.attention` categories, `projection.attention.requiresAction`, and literal `projection.nextAction` argv.\nA `none` `nextAction` has no argv to run: read `liveness.reason` and keep waiting\nwith `check --wait`. Absence never earns an argv; settlement and pending work still do.\nLeave the wait only on positive proof the agent stopped: `exited` liveness, the\nworker's own observation of process exit, or a transcript whose final agent turn\nsent no `worker_done`. Then load `references/recovery-and-cleanup.md` and choose\n`worker-stop` or `worker-abandon` explicitly. `unverifiable` is absence,\nincluding when `worker-show` reports `agentWait` null. Absence never authorizes\nstop, abandon, retry, or release; keep waiting or inspect.\n\n`worker-start` is the normal path, composing placement, terminal readiness,\nprompt injection, and supervised resource ownership. `dispatch --inject` leaves\nan operator-created process unsupervised and is only for an expressiveness gap.\n\n## Task-spec contract\n\nEvery Task spec must be self-contained and name:\n\n- **Target:** the files, component, or environment in scope.\n- **Change:** the concrete result to produce.\n- **Constraints:** invariants, compatibility rules, and do-not-touch boundaries.\n- **Ownership:** what this worker may edit and any coordination boundary.\n- **Observable acceptance:** the test, output, or evidence that proves completion.\n\n## Completion accounting\n\nAfter an accepted success or failure report, immediately do exactly one:\n\n1. Reuse the same proven agent terminal for an immediate follow-up Dispatch.\n2. Record user-requested retention with `worker-retain`.\n3. Run `worker-release`.\n\nRelease is post-settlement cleanup, not cancellation. Only an accepted\nsettlement authorizes it; no other observation does. If release is uncertain,\nfollow its exact recovery receipt and never substitute `terminal close`.\n\nA valid `worker_done` settles the Task and Dispatch automatically; do not follow\nit with `task-update --status completed`. Enumerate the terminals still owing a\ndecision with `worker-list --run --terminal-state reclaimable --json`,\nand do not end the coordinator turn until it returns none.\n\n## Conditional references\n\nThis compact guide is sufficient for the normal local loop. At an action gate\nbelow, run `ORCA skills get orchestration --reference references/.md` and\nread only that document; `--references` lists the names. If the CLI rejects\n`--reference`, run `ORCA skills get orchestration --full` once instead: it\nreturns this exact kernel and every reference, so read only the named one. If an\nolder CLI rejects `--full`, keep this kernel's safety floor, use that command's\n`--help`, and never guess newer flags.\n\n| Action gate | Bundled reference |\n| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |\n| Expanded DAG waves, launch model/effort, same-terminal reuse, or review ownership | `references/coordinator-loop.md` |\n| You are a dispatched worker and the live preamble does not answer your question, or `check` returned an error | `references/worker-contract.md` |\n| New worktree, exact workspace, SSH, WSL, or connected-server placement | `references/placement-and-remote.md` |\n| Inbox replay, follow-up messages, group addresses, or decision gates | `references/messaging-and-gates.md` |\n| Failed/stopped/unknown attempts, retry, stop, abandon, retain, or uncertain release | `references/recovery-and-cleanup.md` |\n| Custom argv or terminal topology that `worker-start` cannot express | `references/low-level-topology.md` |\n| Any legacy label, adopted Run, compatibility receipt, or takeover | `references/legacy-contract-migration.md` |\n\nRetired scheduler commands are not aliases for Run creation. Recovery commands\nmust provide their exact next action; follow it with the same selected executable.\n\n---\n\n# Bundled references\n\nThese references belong to the version-matched guide above. Read only the documents named by its action gates.\n\n\n\n# Coordinator loop\n\nLoad this reference for expanded DAG waves, per-invocation launch preferences,\nsame-terminal reuse, or review ownership. The compact guide remains the source\nof truth for the loop order and completion boundary.\n\n## Ready waves\n\nCreate independent Tasks before the first wait. Encode only real dependencies,\nthen use the ready view as external memory:\n\n```text\nORCA orchestration task-create --spec \"\" --deps --json\nORCA orchestration task-list --ready --brief --json\n```\n\n`--brief` collapses whitespace and caps echoed specs at 160 characters;\n`spec_truncated` identifies shortened rows. Omit it when full specs are needed or\nwhen an older CLI rejects the flag. A nested worker must respect\n`nested_worker_depth_exceeded`; creating another Run does not reset depth.\n\n## Launch preferences\n\nFor a fresh Claude, Codex, or Cursor terminal, `--model` accepts an opaque\nprovider model ID. Pass it only when the user named a model; otherwise omit it\nso the worker inherits the user's configured agent default. Add `--effort` only\nwhen that model supports it:\n\n```text\nORCA orchestration worker-start --task --worktree current --agent claude --model opus --effort high --json\n```\n\n`--effort` requires `--model`; neither option combines with `--terminal`. A\nconnected worker server must advertise launch-preference support before Orca\nforwards either field. Compare `launch.requested` with `launch.effective`; never\nclaim a model or effort from requested arguments alone.\n\n## Reuse after settlement\n\nChoose the terminal's next owner before acknowledging the Delivery. When the\nsame exact agent has immediate follow-up work, recover the proven handle and\ntransfer cleanup ownership to the new Dispatch:\n\n```text\nORCA orchestration worker-show --dispatch --json\nORCA orchestration worker-start --task --terminal --json\n```\n\nOtherwise explicitly retain or release the settled worker. Do not leave it live\nonly to inspect output; archived output remains available through `worker-read`.\n\n## Review ownership\n\nA review-only `worker_done` authorizes synthesis of findings, not coordinator\nfile edits. Dispatch or hand off fixes unless the user explicitly assigned them\nto the coordinator. If the user's plan names a next owner, post-review fixes and\nPR preparation remain with that owner; the coordinator routes and synthesizes.\n\n\n\n# Legacy contract migration\n\nLoad this reference only for an authority label, adopted Run, compatibility or\nrecovery receipt, or explicit legacy takeover. A newly created attempt always\nuses the current grammar.\n\n## Authority labels\n\n- `[LEGACY COMPATIBILITY]` is live and attested. Run only the exact supported\n command printed with the message, using the same selected executable and\n arguments supplied by the original prompt.\n- `[LEGACY RECOVERY REPLAY — MAY HAVE BEEN SEEN]` is one bounded,\n at-least-once cutover replay. Process it idempotently and acknowledge only\n through the exact displayed guidance.\n- `[LEGACY READ-ONLY]` is inspection-only. It has no reply, acknowledgment, or\n lifecycle mutation.\n- An unlabeled current message uses the current guide and grammar.\n\nAn explicitly selected current Run, attested current binding, current Dispatch,\nor federated attachment takes precedence over legacy fallback. A retained\nadoption record alone does not grant mutation authority. If liveness, principal\nownership, capability, or the exact legacy contract is unproven, degrade to\nread-only inspection and never fall back to local execution.\n\nAdoption preserves the live agent process, PTY/session, terminal handle,\ntab/pane, worktree or folder workspace, Task, and Dispatch. It never restarts or\nreplaces the worker and never revives the retired scheduler. Loss of lifecycle\nauthority does not invalidate the existing process, assignment, or filesystem\nwork. Exact recovery may restore the same PTY once in its original inactive\nbackground tab; it must not spawn, write, signal, stop, switch, focus, split, or\ninject a terminal.\n\n## Compatibility recovery\n\nWhen a compatibility response returns structured next-step arguments, execute\nthose exact arguments with the same selected CLI executable. Do not translate\nfrom memory, broaden the recipient, or retry as a current mutation unless the\nreceipt explicitly authorizes it.\n\nA pending ask, reply, final Dispatch settlement, and consuming check have\ndurable recovery identities. Heartbeat and escalation remain at-least-once\nacross a manual contract-boundary retry. If an ask may already have been\nanswered, run the exact non-consuming recovery check printed by Orca before\ncreating any new question. Never guess among identical question threads.\n\nOn packaged Windows, a legacy ask uses a two-step commit/resume protocol. The\ninitial command commits the question, prints its exact\n`ask --resume ` command, and exits with launcher status `75`. Run\nthat exact resume after the launcher or update boundary. For an attested WSL\nlaunch, preserve the printed `orca-ide` executable and distro route. Older WSL\nworkers without launch proof remain lifecycle read-only even while their\nterminal and filesystem work continue.\n\n## Read-only inspection and takeover\n\nRead-only inspection does not consume mail:\n\n```text\nORCA orchestration run-list --json\nORCA orchestration run-show --id run_legacy_local --json\nORCA orchestration run-show --id --json\nORCA orchestration task-list --run --json\nORCA orchestration inbox --full --json\nORCA orchestration check --terminal --peek --format --json\nORCA terminal read --terminal --json\nORCA terminal wait --terminal --for tui-idle --timeout-ms 60000 --json\n```\n\n`run_legacy_local` is an empty audit tombstone after adoption. Find the ordinary\nRun whose objective is `Recovered orchestration work from a contract update`.\n\nOnly when the original coordinator is unavailable or cannot prove retained\nauthority may a new live coordinator take over from its own terminal:\n\n```text\nORCA orchestration run-use --id --takeover-legacy --json\nORCA orchestration check --run --json\n```\n\nTakeover binds the authenticated invoking terminal; `--from` cannot nominate\nanother coordinator. It fences only the old coordinator and moves pending mail\ninto current Run delivery. It preserves live workers, Tasks, Dispatches, processes, and files.\nNever take over while the original coordinator is actively coordinating.\n\nDo not launch a replacement editor merely because Orca updated or authority is\nunclear. Keep the original worker as the only editor until a stable handoff\npoint, then use a fresh current Dispatch in a conflict-free placement.\n\n\n\n# Low-level topology\n\nLoad this reference only when `worker-start` cannot express required custom argv\nor terminal topology. It is not the normal supervised loop and is never a full\nhandoff recipe.\n\n```text\nORCA terminal create --worktree active --title --command \"\" --json\nORCA terminal wait --terminal --for tui-idle --timeout-ms 60000 --json\nORCA orchestration dispatch --task --to --inject --json\n```\n\nWait for readiness only when startup could lose injected input. Prefer\nagent-first `worker-start` whenever its argv and topology are sufficient.\n\n`dispatch --inject` creates authoritative Task/Dispatch context but deliberately\nkeeps an operator-created process unsupervised: it creates no supervised worker\nresource row. `worker-show`, `worker-read`, and `worker-list` report the lane as\n`unsupervised`; `worker-stop` and `worker-abandon` do not close that process, and\nsettled retain/release take no process action.\n\nUse `worker-start --terminal ` when lifecycle ownership of an existing\nagent terminal is required. Never imply that low-level dispatch retroactively\nowns a process, never use it to route around the nested-depth limit, and never\nuse it for an ownership handoff.\n\n\n\n# Messaging and gates\n\nLoad this reference for inbox replay, attempt-specific guidance, group\naddresses, blocking questions, or coordinator-managed DAG decisions.\n\nA successful `send` proves durable enqueue. Wake and nudge are best-effort\nattention only: neither proves the recipient read the message, began a turn, or\naccepted steering.\n\n## Coordinator delivery loop\n\n`check` names its caller with `--terminal ` and is the only verb that\nrejects `--from`. Omit `--terminal` inside an Orca terminal, where Orca resolves\nthe caller; pass it explicitly from anywhere else, including a dispatched\nworker reading coordinator follow-ups.\n\nA consuming coordinator `check` returns the bound Run's oldest FIFO Delivery,\nup to 50 messages, and replays that exact batch until acknowledged. Process\nevery row and required terminal ownership decision before `--ack`. Type filters\ndecide when a waiter wakes; they do not authorize skipping older actionable\nmail. A Delivery therefore always carries the whole FIFO batch whatever its\ntypes, and a `check` without `--wait` hands that batch over unfiltered.\n`--peek` and `--all` are read-only inspection, not progress through the\ncoordinator inbox.\n\nAn empty wait or timeout is a checkpoint. Continue rolling waits until every\nexpected Dispatch settles. Heartbeat or visible activity means alive, not done.\n\n## Addresses\n\nUse a stable Dispatch address for attempt-specific coordinator guidance:\n\n```text\nORCA orchestration send --to dispatch: --subject \"Follow-up\" --body \"\" --json\n```\n\nDo not substitute a remote terminal handle. Omit `--from` for ordinary\ncoordinator calls; a dispatched worker instead copies the exact `--from` and\ncapability arguments in its preamble. `check` is the exception: it identifies\nits caller with `--terminal`, never `--from`.\n\nGroup addresses include `@all`, `@idle`, `@claude`, `@codex`, `@opencode`,\n`@gemini`, `@droid`, `@grok`, `@cursor`, and `@worktree:`. Use them only for\nintentional fan-out status or questions. `worker_done`, heartbeat, and other\nDispatch lifecycle messages never target groups.\n\n## Questions and gates\n\nA worker uses `ask`; its timeout leaves one durable question pending, which the\nworker resumes by message ID. The coordinator answers that message with `reply`.\n\nUse a gate only for a coordinator-owned Task-DAG decision:\n\n```text\nORCA orchestration gate-create --task --question \"\" --options --json\nORCA orchestration gate-resolve --id --resolution \"\" --json\nORCA orchestration gate-list --task --json\n```\n\nPass `json_array` using the quoting rules of the active shell; do not copy POSIX\nsingle-quote syntax into PowerShell or `cmd.exe`.\n\nDo not create a gate merely to answer a worker's `ask`.\n\n\n\n# Placement and remote execution\n\nLoad this reference before creating a new worktree or placing work through SSH,\nWSL, or another connected Orca server.\n\n## Placement choices\n\nA fresh worker means a fresh agent terminal, not a new Git worktree. Use the\ncurrent or an exact existing workspace by default. Create a worktree only when\nthe user requested one or a concrete checkout or filesystem conflict makes\nsharing unsafe.\n\n```text\n# Current workspace; setup is not rerun.\nORCA orchestration worker-start --task --worktree current --agent codex --json\n\n# Stacked child worktree.\nORCA orchestration worker-start --task --worktree new-child --name --agent codex --setup run --json\n\n# Independent top-level worktree.\nORCA orchestration worker-start --task --worktree new-top-level --name --agent codex --setup run --json\n```\n\nCurrent and exact existing workspaces create a fresh terminal unless\n`--terminal` is explicit. Folder workspaces are first-class; do not invoke Git\nor require worktree lineage when the selected workspace is a folder.\n\nRegister a folder workspace through project setup. `repo add --path `\nrequires a valid Git repository and rejects a plain directory:\n\n```text\nORCA project setup-existing-folder --project --host --path --kind folder --json\n```\n\nThen place work on the returned workspace with an exact selector. A worktree\nselector needs the full `::` value Orca returned, passed as\n`id:`; a bare repo id is not a worktree id. `new-child` and\n`new-top-level` are worktree creation and do not apply to a folder.\n\nNew worktrees use agent-first creation and run setup by default. Preserve the\nrepository's startup policy: `start-immediately` can report setup as `running`,\nwhile `wait-for-setup` gates prompt delivery on success. Orca lineage, Git base,\nfilesystem isolation, coordination parentage, UI grouping, and execution host\nare separate decisions.\n\n## Connected servers\n\nThe Run and Tasks remain authoritative on the current server. `--on` selects\nonly the worker's execution server and appears only on `worker-start`:\n\n```text\nORCA orchestration worker-start --task --on --worktree new-top-level --repo --name --agent codex --setup run --json\n```\n\nRemote `current` and `new-child` are invalid because they are ambiguous across\nservers. Use an exact discovered remote workspace, or `new-top-level` with an\nexact remote repository selector. After start, route every follow-up, read,\nstop, and cleanup by Dispatch ID; never repeat `--on` or substitute a remote\nterminal handle.\n\n```text\nORCA orchestration worker-show --dispatch --json\nORCA orchestration worker-read --dispatch --limit 50 --json\nORCA orchestration send --to dispatch: --subject \"Follow-up\" --body \"\" --json\nORCA orchestration worker-list --run --include-remote --json\n```\n\n`worker-list` reads local fleet state only; enumerate remote workers with\n`--include-remote` or every one of them reads `unverifiable`. Scope every list\nwith `--run `: unscoped, it reports every Dispatch this runtime has\nrecorded, and the workers you are waiting on are lost in that history.\n\n## Execution-host and mixed-version floor\n\nThe execution host owns process, filesystem, transcript, stop, and cleanup\nfacts. Render only `live`, `unverifiable`, or `exited`. Connection loss, relay\nabsence, missing client inventory, or timeout yields `unverifiable`, never\nsynthetic exit and never a client-local substitute action.\n\nClients and servers update independently. Optional response fields may be\nabsent. Forward model/effort, transcript reads, cleanup, or another new remote\noperation only when the peer advertises the relevant capability; unknown stream\nopcodes can be silently dropped. A narrow unsupported response may degrade to a\ndocumented older path, but must not broaden the target or cross the execution\nboundary. Changing host-published content reaches old clients even without a\nwire-shape change, so preserve established semantics or negotiate the behavior.\n\nFor WSL, use the exact executable and arguments returned by Orca so the distro\nand packaged launcher remain bound. Do not translate a printed `orca-ide`\nrecovery command into a PATH-resolved local command.\n\n\n\n# Recovery and cleanup\n\nLoad this reference only after a failed/stopped/unknown attempt, explicit retry\ndecision, stop/abandon request, retention request, or uncertain release.\n\n| Proven state | Safe action |\n| ----------------------- | ------------------------------------------------------------------ |\n| `ready` or active | Keep waiting; optionally read bounded output |\n| `failed` or `stopped` | Start a replacement with `--retry-of`; repeat placement explicitly |\n| `outcome_unknown` | Inspect, then choose `worker-stop` or explicit `worker-abandon` |\n| Accepted `worker_done` | Reuse, retain, or release |\n| Remote contact lost | Preserve `unverifiable`; do not stop or retry from absence alone |\n| `unverifiable` liveness | Keep waiting or inspect; never stop, abandon, retry, or release |\n| Proven `exited` agent | Enumerate with `worker-list`; follow its `nextAction` |\n\n## Inspect before acting\n\n```text\nORCA orchestration worker-list --run --json\nORCA orchestration worker-list --run --include-remote --json\nORCA orchestration worker-show --dispatch --json\nORCA orchestration worker-read --dispatch --limit 50 --json\n```\n\n`worker-list` is the enumerating command and the authority on agent liveness:\neach row carries `projection.liveness`, `projection.attention.categories`,\n`projection.attention.requiresAction`, and a literal `projection.nextAction`\nargv to run. Always scope it with `--run `; an unscoped list reports\nevery Dispatch this runtime has ever recorded and buries the live ones.\n`worker-show`'s `observation.status` is PTY liveness only, so a `live` terminal\nwhose agent died at a trust prompt still reads `live` there.\n\nWhen the two disagree, the fleet verdict decides — unless the fleet row is\n`unverifiable` for a reason that names a gap on this client rather than a fact\nabout the worker. `missing_status`, `host_unavailable`, and\n`capability_unsupported` are such gaps: the first means this runtime holds no\nstatus row, the second that it could not ask the execution host at all, and the\nthird that a stale peer answered but lacks the fleet-snapshot capability.\nAgainst any of them, a `worker-show` verdict sourced from the execution host is\nthe better evidence and outranks the row. Only `host_unavailable` is contact\nloss; the other two mean the host was never asked or answered without the\ncapability.\n\nThis never promotes absence. `unverifiable` from either command still authorizes\nnothing — only a positive `live` or `exited` verdict does.\n\nA worker started with `--on ` reads `unverifiable` until you\nenumerate with `--include-remote`, which asks its execution host for the\nverdict. Past 100 rows the response pages, so follow `page.nextCursor` with\n`--cursor ` until `page.hasMore` is false.\n\n## Stall needs positive evidence\n\nLeave the wait only on positive proof the agent stopped: `exited` liveness, the\nworker's own observation of process exit, or a transcript whose final agent turn\nsent no `worker_done`. Only then choose `worker-stop` or `worker-abandon`.\n\n`unverifiable` is always absence — `missing_status`, `stale_status`,\n`restored_unconfirmed`, or a remote worker with no connection — and a null\n`agentWait` or an unchanged `worker-read` tail is that same absence seen again.\nAbsence never authorizes stop, abandon, retry, or release: keep waiting, or\ninspect until you hold one of the positive signals above. A `nextAction` that\nnames an inspecting command is asking for evidence, not for cleanup.\n\n`worker-read --source auto` uses a proven provider transcript when available and\notherwise returns bounded terminal output with a typed `fallbackReason`.\nContinue with its top-level cursor, which is pinned to that source. If Orca\nreports `source_changed`, restart without the old cursor. A bounded initial\ntranscript tail can return an EOF cursor that follows only newly appended records;\nread `contentComplete`, `clipping`, and `warnings` before assuming omitted older\nrecords are pageable. Never guess a provider session ID, transcript path, or\nremote terminal handle.\n\n## Was the mutation applied?\n\nWhen a mutation's response was lost and named no Dispatch, do not replay blind.\nEvery orchestration mutation accepts `--retry-request `, which reuses one\noperation identity so Orca can replay, join, or recover it instead of starting a\nduplicate. Ask what happened first:\n\n```text\nORCA orchestration request-show --request --json\n```\n\n`completed` means the mutation already took effect; read its recorded receipt\ninstead of rerunning. `pending` means the original mutation is still running or\nOrca restarted before recording its outcome; replay the original command with\n`--retry-request `. `absent` means this runtime holds no receipt\nunder your caller identity — that is not proof nothing happened, so inspect the\naffected Task, Dispatch, and terminal before deciding whether to retry.\n\nWhen a worker's terminal accepted input but the submit is unconfirmed, use\n`terminal send --wait-submit `: it observes the accepted prompt for that\nlong and, on timeout, returns the input-accepted receipt without resending.\n\n## Refused starts\n\n`dispatch` and `worker-start` refuse the following preflight cases with a stable\n`error.code`; read it before choosing a recovery, and treat `error.data.nextSteps`\nas the exact recovery text. Older hosts may omit `data`, so treat every field as\noptional.\n\n| Code | Meaning | Recovery |\n| -------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `task_not_found` | No Task with that id, or not in the bound Run (`data.taskId`, `data.runId`) | Check `task-list --json`; create the Task with `task-create` if it does not exist |\n| `task_not_startable` | Task cannot start now: not `ready`, or invalid `--retry-of` (`data.status`, `data.unmetDependencies`, `data.retryOf`) | Wait for running dependencies with `check --wait`; retry or unblock failed ones; inspect `dispatch-show` if already dispatched |\n| `inject_rejected` | `--inject` refused because no recognized agent runs in the target (`data.terminal`, `data.reason`) | Start a recognized agent there or pick another terminal; or dispatch without `--inject` and use `terminal send` |\n| `runtime_error` | Any other failure, including a target terminal that already owns an active Dispatch | Read the message, inspect state, and do not retry unchanged |\n\n## Retry, stop, and abandon\n\nRetry only a positively proven failed or stopped attempt. Name the failed Task\nwith `--task`, since `--spec` creates a new one. Placement is never silently\ninherited:\n\n```text\nORCA orchestration worker-start --task --retry-of --worktree --agent --json\n```\n\nAfter three consecutive failures for one Task, its dispatch context\ncircuit-breaks and the Task is failed. Do not route around that boundary with a\nnew Run or an unrelated Dispatch.\n\nFor `outcome_unknown`, inspect first, then make an explicit choice:\n\n```text\nORCA orchestration worker-stop --dispatch --json\nORCA orchestration worker-abandon --dispatch --json\n```\n\n`worker-stop` closes only the exact proven supervised agent terminal. It never\ndeletes the worktree, setup terminal, configured tabs, or unrelated processes.\n`worker-abandon` fences orchestration while accepting that resources may remain\nlive; it performs no remote, process, or filesystem action.\n\n## Retain and release\n\n```text\nORCA orchestration worker-retain --dispatch --json\nORCA orchestration worker-release --dispatch --json\n```\n\nRetain only when the user explicitly wants the settled terminal kept live.\nRelease works after succeeded and failed reports, archives readable output, and\ncloses only the exact terminal owned by that settled Dispatch. Replays may call\nrelease again safely. Reused, pre-existing, setup, coordinator, active,\nuser-taken-over, and unproven terminals are retained.\n\nA `worker-start` that failed before its agent was ready still owns the terminal\nit created. Its receipt names `worker-release`, and `worker-list` reports that\nrow as `reclaimable`; release it there rather than closing the terminal by hand.\n\nNever release because of timeout, TUI idle, heartbeat, status, question,\nescalation, or stale/rejected completion. If the receipt says `release_pending`\nor `release_unknown`, follow its exact recovery action. Never substitute\n`terminal close`.\n\n`orchestration reset` is destructive recovery. Do not run it during active\ncoordination unless the user explicitly abandons that state.\n\n\n\n# Worker contract\n\nThe injected preamble is authoritative. Copy its command rather than\nreconstructing flags. In particular, preserve the exact executable, worker\nhandle, Dispatch capability, Task ID, and Dispatch ID.\n\n## Heartbeat\n\nSend heartbeats only at the cadence required by the live preamble. Skip them\nwhile blocked inside `ask` or `check --wait`; those calls are liveness signals.\n\n```text\nORCA orchestration send --from --dispatch-capability --type heartbeat --subject \"alive\" --task-id --dispatch-id --phase \"\"\n```\n\nUse typed lifecycle flags, not a hand-written JSON payload. A heartbeat proves\nliveness, never completion.\n\n## Ask and resume\n\nUse Orca `ask` whenever the coordinator must answer. Never open a local question\nTUI the coordinator cannot answer.\n\n```text\nORCA orchestration ask --from --dispatch-capability --question \"\" --options \",\" --timeout-ms 600000\n\nORCA orchestration ask --from --dispatch-capability --resume --timeout-ms 600000\n```\n\nA timeout or disconnect leaves the original question pending. Resume its\nmessage ID; do not create a duplicate question.\n\n## Reading coordinator follow-ups\n\nThe coordinator steers a running worker with `send --to dispatch:`. That\nenqueue is durable but does not interrupt you, so nothing arrives unless you\nlook:\n\n```text\nORCA orchestration check --terminal --json\n```\n\nRun it at each natural checkpoint — before starting a new file, after a test\nrun — and once more immediately before `worker_done`, so a redirect or a\ncancellation lands before the Task settles. `check` names its caller with\n`--terminal`, never `--from`. Stop checking after `worker_done`.\n\nIf `check` returns `consumer_fenced`, this process no longer owns its Dispatch:\nthe Attempt was re-attached to another worker or settled without you. Stop, do\nnot send `worker_done`, and do not retry the check. An empty `check` never means\nyou were replaced; `consumer_fenced` is the only way you learn that.\n\n## Escalation\n\nEscalate only before completion and only when the coordinator must intervene:\n\n```text\nORCA orchestration send --from --dispatch-capability --type escalation --subject \"Blocked: \" --body \"
\" --task-id --dispatch-id \n```\n\n## Completion\n\nSend exactly one terminal report. `--body` is three sentences: what changed,\nwhat was found, and what remains. Use `--outcome failed` when the requested work\nis not complete; never hide failure in prose or silently exit.\n\nAppend `--files-modified` or `--report-path` only when applicable, using actual\npaths. Do not send documentation placeholders as metadata.\n\n```text\nORCA orchestration send --from --dispatch-capability --type worker_done --subject \"\" --body \"\" --task-id --dispatch-id --outcome succeeded\n```\n\nAfter `worker_done`, end the dispatched turn and idle. Do not poll, close your\nown terminal, or begin unrelated work. A later direct user instruction is new\nuser-owned work and must not reuse settled lifecycle IDs; a supervised follow-up\narrives with a fresh preamble and Task block.\n" // oxfmt-ignore const ORCHESTRATION_COORDINATOR_LOOP_REFERENCE_MARKDOWN = "# Coordinator loop\n\nLoad this reference for expanded DAG waves, per-invocation launch preferences,\nsame-terminal reuse, or review ownership. The compact guide remains the source\nof truth for the loop order and completion boundary.\n\n## Ready waves\n\nCreate independent Tasks before the first wait. Encode only real dependencies,\nthen use the ready view as external memory:\n\n```text\nORCA orchestration task-create --spec \"\" --deps --json\nORCA orchestration task-list --ready --brief --json\n```\n\n`--brief` collapses whitespace and caps echoed specs at 160 characters;\n`spec_truncated` identifies shortened rows. Omit it when full specs are needed or\nwhen an older CLI rejects the flag. A nested worker must respect\n`nested_worker_depth_exceeded`; creating another Run does not reset depth.\n\n## Launch preferences\n\nFor a fresh Claude, Codex, or Cursor terminal, `--model` accepts an opaque\nprovider model ID. Pass it only when the user named a model; otherwise omit it\nso the worker inherits the user's configured agent default. Add `--effort` only\nwhen that model supports it:\n\n```text\nORCA orchestration worker-start --task --worktree current --agent claude --model opus --effort high --json\n```\n\n`--effort` requires `--model`; neither option combines with `--terminal`. A\nconnected worker server must advertise launch-preference support before Orca\nforwards either field. Compare `launch.requested` with `launch.effective`; never\nclaim a model or effort from requested arguments alone.\n\n## Reuse after settlement\n\nChoose the terminal's next owner before acknowledging the Delivery. When the\nsame exact agent has immediate follow-up work, recover the proven handle and\ntransfer cleanup ownership to the new Dispatch:\n\n```text\nORCA orchestration worker-show --dispatch --json\nORCA orchestration worker-start --task --terminal --json\n```\n\nOtherwise explicitly retain or release the settled worker. Do not leave it live\nonly to inspect output; archived output remains available through `worker-read`.\n\n## Review ownership\n\nA review-only `worker_done` authorizes synthesis of findings, not coordinator\nfile edits. Dispatch or hand off fixes unless the user explicitly assigned them\nto the coordinator. If the user's plan names a next owner, post-review fixes and\nPR preparation remain with that owner; the coordinator routes and synthesizes.\n" diff --git a/src/main/runtime/orca-runtime-subscribe-to-terminal-resize.ts b/src/main/runtime/orca-runtime-subscribe-to-terminal-resize.ts index d610dbb235f..484ea73064e 100644 --- a/src/main/runtime/orca-runtime-subscribe-to-terminal-resize.ts +++ b/src/main/runtime/orca-runtime-subscribe-to-terminal-resize.ts @@ -145,7 +145,7 @@ export class OrcaRuntimeWithSubscribeToTerminalResize extends OrcaRuntimeWithApp exitCause: cause, handle }), - ...(recipient.runId ? { runId: recipient.runId } : {}) + runId: dispatch.run_id }) this.notifyMessageArrived(escalation.to_handle, escalation.type) } catch (error) { diff --git a/src/main/runtime/orca-runtime-tests/lineage-and-scan-cache-part-05.spec.ts b/src/main/runtime/orca-runtime-tests/lineage-and-scan-cache-part-05.spec.ts index 1df978ac165..ad66e89ec7e 100644 --- a/src/main/runtime/orca-runtime-tests/lineage-and-scan-cache-part-05.spec.ts +++ b/src/main/runtime/orca-runtime-tests/lineage-and-scan-cache-part-05.spec.ts @@ -95,7 +95,10 @@ describe('OrcaRuntimeService', () => { return [name, createRootDispatch(db, task.id, handles[name], paneKey(name))] }) ) - const legacyTask = db.createTask({ spec: 'legacy worker' }) + const legacyTask = db.createTask({ + runId: 'run_legacy_local', + spec: 'legacy worker' + }) const legacyDispatch = createRootDispatch( db, legacyTask.id, diff --git a/src/main/runtime/orca-runtime-tests/mobile-creation-and-orchestration-part-02.spec.ts b/src/main/runtime/orca-runtime-tests/mobile-creation-and-orchestration-part-02.spec.ts index 57c1d2c3031..9291c30c1a2 100644 --- a/src/main/runtime/orca-runtime-tests/mobile-creation-and-orchestration-part-02.spec.ts +++ b/src/main/runtime/orca-runtime-tests/mobile-creation-and-orchestration-part-02.spec.ts @@ -216,7 +216,10 @@ describe('OrcaRuntimeService', () => { runtime as unknown as { leaves: Map< string, - { lastAgentStatus: string | null; lastAgentStatusObservedLive: boolean } + { + lastAgentStatus: string | null + lastAgentStatusObservedLive: boolean + } > } ).leaves.values() @@ -415,7 +418,12 @@ describe('OrcaRuntimeService', () => { const [terminal] = (await runtime.listTerminals()).terminals runtime.onPtyData('pty-1', '\x1b]0;Codex working\x07', 100) - db.insertMessage({ from: 'term_worker', to: terminal.handle, subject: 'pending' }) + db.insertMessage({ + runId: 'run_legacy_local', + from: 'term_worker', + to: terminal.handle, + subject: 'pending' + }) runtime.notifyMessageArrived(terminal.handle, 'status') db.close() diff --git a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-04.spec.ts b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-04.spec.ts index d09b4c64ce8..48f820cee01 100644 --- a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-04.spec.ts +++ b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-04.spec.ts @@ -56,7 +56,10 @@ describe('OrcaRuntimeService', () => { ) const db = new OrchestrationDb(':memory:') try { - const task = db.createTask({ spec: 'continue after missing worker recovery' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'continue after missing worker recovery' + }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -163,7 +166,10 @@ describe('OrcaRuntimeService', () => { ) const db = new OrchestrationDb(':memory:') try { - const task = db.createTask({ spec: 'retry missing worker recovery' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'retry missing worker recovery' + }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/orchestration-messages-fake-parity.test.ts b/src/main/runtime/orchestration-messages-fake-parity.test.ts index 72ed8695b5b..5a785fc8602 100644 --- a/src/main/runtime/orchestration-messages-fake-parity.test.ts +++ b/src/main/runtime/orchestration-messages-fake-parity.test.ts @@ -7,9 +7,13 @@ type PointerTarget = { ptyId: string; processIncarnation: string } // The slice of the mailbox store the pointer batch selector depends on. type PointerStore = { - insertMessage(message: { from: string; to: string; subject: string; type?: MessageType }): { - id: string - } + insertMessage(message: { + runId: string + from: string + to: string + subject: string + type?: MessageType + }): { id: string } stageMailboxPointerEnter(ids: string[], target: PointerTarget): boolean markMailboxPointerWriteAttempted(ids: string[], target: PointerTarget): boolean getUndeliveredUnreadMessages( @@ -32,7 +36,12 @@ describe.each(STORES)('mailbox pointer reservations (%s)', (_name, createStore) it('refuses a claim another flight already holds', () => { const store = createStore() - const message = store.insertMessage({ from: 'a', to: 'run:run-1', subject: 'contended' }) + const message = store.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 'contended' + }) expect(store.stageMailboxPointerEnter([message.id], rival)).toBe(true) expect(store.stageMailboxPointerEnter([message.id], mine)).toBe(false) @@ -41,8 +50,18 @@ describe.each(STORES)('mailbox pointer reservations (%s)', (_name, createStore) it('rolls the whole batch back when one row is already claimed', () => { const store = createStore() - const free = store.insertMessage({ from: 'a', to: 'run:run-1', subject: 'free' }) - const taken = store.insertMessage({ from: 'a', to: 'run:run-1', subject: 'taken' }) + const free = store.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 'free' + }) + const taken = store.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 'taken' + }) expect(store.stageMailboxPointerEnter([taken.id], rival)).toBe(true) expect(store.stageMailboxPointerEnter([free.id, taken.id], mine)).toBe(false) @@ -52,8 +71,19 @@ describe.each(STORES)('mailbox pointer reservations (%s)', (_name, createStore) it('applies the exclusion and limit the pointer batch selector relies on', () => { const store = createStore() - store.insertMessage({ from: 'a', to: 'run:run-1', subject: 'reserved', type: 'escalation' }) - const kept = store.insertMessage({ from: 'a', to: 'run:run-1', subject: 'kept' }) + store.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 'reserved', + type: 'escalation' + }) + const kept = store.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 'kept' + }) expect( store diff --git a/src/main/runtime/orchestration/coordinator-decision-gates.test.ts b/src/main/runtime/orchestration/coordinator-decision-gates.test.ts index 15e0cd2c7b0..3e9934b85ad 100644 --- a/src/main/runtime/orchestration/coordinator-decision-gates.test.ts +++ b/src/main/runtime/orchestration/coordinator-decision-gates.test.ts @@ -12,13 +12,14 @@ describe('coordinator decision-gate authority', () => { it('opens a gate only for the sender-owned active Dispatch', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'owned gate target' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'owned gate target' }) const dispatch = createRootDispatch(db, task.id, 'term_owner', 'tab_owner:leaf_owner') const logs: string[] = [] openDecisionGateFromMessage( db, db.insertMessage({ + runId: 'run_legacy_local', from: 'term_owner', to: 'term_coordinator', subject: 'Need approval', @@ -41,20 +42,27 @@ describe('coordinator decision-gate authority', () => { it('rejects a gate targeting another active Dispatch without mutating either Task', () => { db = new OrchestrationDb(':memory:') - const attackerTask = db.createTask({ spec: 'attacker assignment' }) + const attackerTask = db.createTask({ + runId: 'run_legacy_local', + spec: 'attacker assignment' + }) const attacker = createRootDispatch( db, attackerTask.id, 'term_attacker', 'tab_attacker:leaf_attacker' ) - const victimTask = db.createTask({ spec: 'victim assignment' }) + const victimTask = db.createTask({ + runId: 'run_legacy_local', + spec: 'victim assignment' + }) const victim = createRootDispatch(db, victimTask.id, 'term_victim', 'tab_victim:leaf_victim') const logs: string[] = [] openDecisionGateFromMessage( db, db.insertMessage({ + runId: 'run_legacy_local', from: 'term_attacker', to: 'term_coordinator', subject: 'Block the victim', @@ -79,12 +87,16 @@ describe('coordinator decision-gate authority', () => { it('accepts the canonical sender of an imported federated Dispatch', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'remote gate target' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'remote gate target' + }) const dispatch = createRootDispatch(db, task.id, 'remote-worker') openDecisionGateFromMessage( db, db.insertMessage({ + runId: 'run_legacy_local', from: `dispatch:${dispatch.id}`, to: 'term_coordinator', subject: 'Remote approval required', diff --git a/src/main/runtime/orchestration/coordinator-dispatch-unobserved-prompt.test.ts b/src/main/runtime/orchestration/coordinator-dispatch-unobserved-prompt.test.ts index 5f99e283de3..f0960803988 100644 --- a/src/main/runtime/orchestration/coordinator-dispatch-unobserved-prompt.test.ts +++ b/src/main/runtime/orchestration/coordinator-dispatch-unobserved-prompt.test.ts @@ -66,7 +66,7 @@ describe('coordinator dispatch with an unobserved prompt', () => { it('never re-pastes a preamble whose turn start was not observed', async () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'do the work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'do the work' }) const runtime = createRuntime(new Error('agent_prompt_stalled')) const logs: string[] = [] @@ -88,7 +88,7 @@ describe('coordinator dispatch with an unobserved prompt', () => { it('lets a late worker report settle a dispatch whose prompt was unobserved', async () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'do the work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'do the work' }) await dispatch(createRuntime(new Error('agent_prompt_stalled')), task.id, []) const dispatchId = db.getDispatchContext(task.id)!.id const minted = db.mintDispatchCapability({ @@ -119,7 +119,7 @@ describe('coordinator dispatch with an unobserved prompt', () => { it('still fails the dispatch when the prompt was never delivered', async () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'do the work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'do the work' }) const runtime = createRuntime(new Error('terminal_not_writable')) await expect(dispatch(runtime, task.id, [])).rejects.toThrow('terminal_not_writable') diff --git a/src/main/runtime/orchestration/coordinator-drift-probe-coalescing.test.ts b/src/main/runtime/orchestration/coordinator-drift-probe-coalescing.test.ts index f42713c0dc9..5367af466bf 100644 --- a/src/main/runtime/orchestration/coordinator-drift-probe-coalescing.test.ts +++ b/src/main/runtime/orchestration/coordinator-drift-probe-coalescing.test.ts @@ -44,8 +44,8 @@ describe('Coordinator drift probe coalescing', () => { : { base: 'origin/main', behind: 0, recentSubjects: [] } } } - const first = db.createTask({ spec: 'first task' }) - const second = db.createTask({ spec: 'second task' }) + const first = db.createTask({ runId: 'run_legacy_local', spec: 'first task' }) + const second = db.createTask({ runId: 'run_legacy_local', spec: 'second task' }) const coordinator = new Coordinator(db, runtime, { spec: 'go', coordinatorHandle: 'coord', @@ -65,6 +65,7 @@ describe('Coordinator drift probe coalescing', () => { throw new Error(`missing dispatch for ${task.id}`) } db.insertMessage({ + runId: 'run_legacy_local', from: dispatch.assignee_handle, to: 'coord', subject: 'Done', @@ -105,8 +106,14 @@ describe('Coordinator drift probe coalescing', () => { } } } - const refused = db.createTask({ spec: 'requires a current base' }) - const allowed = db.createTask({ spec: 'can use stale base\nallow-stale-base: true' }) + const refused = db.createTask({ + runId: 'run_legacy_local', + spec: 'requires a current base' + }) + const allowed = db.createTask({ + runId: 'run_legacy_local', + spec: 'can use stale base\nallow-stale-base: true' + }) const coordinator = new Coordinator(db, runtime, { spec: 'go', coordinatorHandle: 'coord', diff --git a/src/main/runtime/orchestration/coordinator-escalation-triage.test.ts b/src/main/runtime/orchestration/coordinator-escalation-triage.test.ts index c020e62dca0..e0bdf75fc98 100644 --- a/src/main/runtime/orchestration/coordinator-escalation-triage.test.ts +++ b/src/main/runtime/orchestration/coordinator-escalation-triage.test.ts @@ -12,20 +12,21 @@ describe('coordinator escalation authority', () => { it('rejects an escalation targeting another active Dispatch', () => { db = new OrchestrationDb(':memory:') - const attackerTask = db.createTask({ spec: 'attacker assignment' }) + const attackerTask = db.createTask({ runId: 'run_legacy_local', spec: 'attacker assignment' }) const attacker = createRootDispatch( db, attackerTask.id, 'term_attacker', 'tab_attacker:leaf_attacker' ) - const victimTask = db.createTask({ spec: 'victim assignment' }) + const victimTask = db.createTask({ runId: 'run_legacy_local', spec: 'victim assignment' }) const victim = createRootDispatch(db, victimTask.id, 'term_victim') const logs: string[] = [] applyEscalationToDispatch( db, db.insertMessage({ + runId: 'run_legacy_local', from: 'term_attacker', to: 'term_coordinator', subject: 'Fail the victim', @@ -43,12 +44,13 @@ describe('coordinator escalation authority', () => { it('accepts the canonical sender of an imported federated Dispatch', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'remote escalation target' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'remote escalation target' }) const dispatch = createRootDispatch(db, task.id, 'remote-worker') applyEscalationToDispatch( db, db.insertMessage({ + runId: 'run_legacy_local', from: `dispatch:${dispatch.id}`, to: 'term_coordinator', subject: 'Remote worker failed', diff --git a/src/main/runtime/orchestration/coordinator-stale-base-flag.test.ts b/src/main/runtime/orchestration/coordinator-stale-base-flag.test.ts new file mode 100644 index 00000000000..818d3f848dc --- /dev/null +++ b/src/main/runtime/orchestration/coordinator-stale-base-flag.test.ts @@ -0,0 +1,52 @@ +import { describe, expect, it } from 'vitest' +import { parseAllowStaleBaseFromSpec } from './coordinator-stale-base-flag' + +describe('parseAllowStaleBaseFromSpec', () => { + it('matches canonical form on its own line and strips it', () => { + const spec = `Do the work +allow-stale-base: true` + const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) + expect(allowStale).toBe(true) + expect(strippedSpec).toBe('Do the work\n') + expect(strippedSpec).not.toContain('allow-stale-base') + }) + + it('matches case-insensitively', () => { + const spec = `Do the work +Allow-Stale-Base: TRUE` + const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) + expect(allowStale).toBe(true) + expect(strippedSpec).not.toMatch(/[Aa]llow-[Ss]tale-[Bb]ase/) + }) + + it('does not match allow-stale-base: false', () => { + const spec = `Do the work +allow-stale-base: false` + const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) + expect(allowStale).toBe(false) + expect(strippedSpec).toBe(spec) + }) + + it('does not match allow-stale-base: truthy', () => { + const spec = `Do the work +allow-stale-base: truthy` + const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) + expect(allowStale).toBe(false) + expect(strippedSpec).toBe(spec) + }) + + it('does not match the flag embedded inside a sentence', () => { + const spec = 'we allow-stale-base: true sometimes' + const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) + expect(allowStale).toBe(false) + expect(strippedSpec).toBe(spec) + }) + + it('handles the flag as the last line with no trailing newline', () => { + const spec = 'line 1\nallow-stale-base: true' + const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) + expect(allowStale).toBe(true) + expect(strippedSpec).toBe('line 1\n') + expect(strippedSpec.endsWith('allow-stale-base: true')).toBe(false) + }) +}) diff --git a/src/main/runtime/orchestration/coordinator.test.ts b/src/main/runtime/orchestration/coordinator.test.ts index 38701a9d7dd..75ba01ffa27 100644 --- a/src/main/runtime/orchestration/coordinator.test.ts +++ b/src/main/runtime/orchestration/coordinator.test.ts @@ -3,12 +3,11 @@ import { OrchestrationDb } from './db' import { reconcileLifecycleMessage } from './lifecycle-reconciliation' import { Coordinator } from './coordinator' import type { CoordinatorRuntime } from './coordinator-runtime-contract' -import { - DISPATCH_STALE_THRESHOLD, - parseAllowStaleBaseFromSpec -} from './coordinator-stale-base-flag' +import { DISPATCH_STALE_THRESHOLD } from './coordinator-stale-base-flag' import { createRootDispatch } from './db/root-dispatch-test-fixture' +const runId = 'run_legacy_local' + type DriftResult = { base: string behind: number @@ -92,6 +91,7 @@ function insertWorkerDone( } const from = params.from ?? dispatch?.assignee_handle ?? 'term_unknown' db.insertMessage({ + runId, from, to: params.to ?? 'coord', subject: 'Done', @@ -131,7 +131,10 @@ describe('Coordinator', () => { runtime.cliCommand = 'orca-ide' runtime.terminals = [{ handle: 'term_a', worktreeId: 'wt1', connected: true, writable: true }] - const task = db.createTask({ spec: 'implement feature' }) + const task = db.createTask({ + runId, + spec: 'implement feature' + }) // Simulate worker_done arriving after dispatch const coordinator = new Coordinator(db, runtime, { @@ -166,7 +169,10 @@ describe('Coordinator', () => { getTerminalPaneKey: (handle: string) => (handle === 'term_a' ? 'tab_a:leaf_a' : null) }) - const task = db.createTask({ spec: 'implement feature' }) + const task = db.createTask({ + runId, + spec: 'implement feature' + }) const coordinator = new Coordinator(db, withPaneLookup, { spec: 'build it', coordinatorHandle: 'coord', @@ -198,7 +204,10 @@ describe('Coordinator', () => { } : null }) - const task = db.createTask({ spec: 'implement feature' }) + const task = db.createTask({ + runId, + spec: 'implement feature' + }) const coordinator = new Coordinator(db, withAuthority, { spec: 'build it', coordinatorHandle: 'coord', @@ -223,9 +232,13 @@ describe('Coordinator', () => { db = new OrchestrationDb(':memory:') const runtime = createMockRuntime() - const task = db.createTask({ spec: 'send-driven completion' }) + const task = db.createTask({ + runId, + spec: 'send-driven completion' + }) const dispatch = createRootDispatch(db, task.id, 'term_a') const msg = db.insertMessage({ + runId, from: 'term_a', to: 'coord', subject: 'Done', @@ -250,7 +263,10 @@ describe('Coordinator', () => { db = new OrchestrationDb(':memory:') const runtime = createMockRuntime() - const task = db.createTask({ spec: 'duplicate completion' }) + const task = db.createTask({ + runId, + spec: 'duplicate completion' + }) const dispatch = createRootDispatch(db, task.id, 'term_a') const payload = JSON.stringify({ taskId: task.id, @@ -258,6 +274,7 @@ describe('Coordinator', () => { outcome: 'succeeded' }) const first = db.insertMessage({ + runId, from: 'term_a', to: 'coord', subject: 'Done', @@ -265,6 +282,7 @@ describe('Coordinator', () => { payload }) db.insertMessage({ + runId, from: 'term_a', to: 'coord', subject: 'Done again', @@ -289,7 +307,7 @@ describe('Coordinator', () => { db = new OrchestrationDb(':memory:') const runtime = createMockRuntime() - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId, spec: 'work' }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -321,7 +339,10 @@ describe('Coordinator', () => { { handle: 'term_b', worktreeId: 'wt1', connected: true, writable: true } ] - const task = db.createTask({ spec: 'risky work' }) + const task = db.createTask({ + runId, + spec: 'risky work' + }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -339,6 +360,7 @@ describe('Coordinator', () => { const dispatch = db.getDispatchContext(task.id) expect(dispatch).toBeDefined() db.insertMessage({ + runId, from: dispatch?.assignee_handle ?? 'missing-worker', to: 'coord', subject: `Failed attempt ${i + 1}`, @@ -360,7 +382,10 @@ describe('Coordinator', () => { throw new Error('terminal_not_writable') } - const task = db.createTask({ spec: 'cannot dispatch' }) + const task = db.createTask({ + runId, + spec: 'cannot dispatch' + }) const coordinator = new Coordinator(db, runtime, { spec: 'go', coordinatorHandle: 'coord', @@ -379,7 +404,10 @@ describe('Coordinator', () => { const runtime = createMockRuntime() runtime.terminals = [{ handle: 'term_a', worktreeId: 'wt1', connected: true, writable: true }] - const task = db.createTask({ spec: 'needs approval' }) + const task = db.createTask({ + runId, + spec: 'needs approval' + }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -398,6 +426,7 @@ describe('Coordinator', () => { const dispatch = db.getDispatchContext(task.id) expect(dispatch).toBeDefined() db.insertMessage({ + runId, from: 'term_a', to: 'coord', subject: 'Need approval', @@ -441,8 +470,12 @@ describe('Coordinator', () => { const runtime = createMockRuntime() runtime.terminals = [{ handle: 'term_a', worktreeId: 'wt1', connected: true, writable: true }] - const t1 = db.createTask({ spec: 'first' }) - const t2 = db.createTask({ spec: 'second', deps: [t1.id] }) + const t1 = db.createTask({ runId, spec: 'first' }) + const t2 = db.createTask({ + runId, + spec: 'second', + deps: [t1.id] + }) expect(t2.status).toBe('pending') @@ -492,9 +525,9 @@ describe('Coordinator', () => { { handle: 'term_c', worktreeId: 'wt1', connected: true, writable: true } ] - const t1 = db.createTask({ spec: 'one' }) - const t2 = db.createTask({ spec: 'two' }) - const t3 = db.createTask({ spec: 'three' }) + const t1 = db.createTask({ runId, spec: 'one' }) + const t2 = db.createTask({ runId, spec: 'two' }) + const t3 = db.createTask({ runId, spec: 'three' }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -530,7 +563,7 @@ describe('Coordinator', () => { const runtime = createMockRuntime() // No terminals available so dispatchReadyTasks creates one and we can // drive the stale-scan deterministically via SQL backdating. - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId, spec: 'work' }) const ctx = createRootDispatch(db, task.id, 'term_stale') // Backdate dispatched_at and last_heartbeat_at beyond the 10-min threshold @@ -569,7 +602,7 @@ describe('Coordinator', () => { const runtime = createMockRuntime() runtime.terminals = [{ handle: 'term_a', worktreeId: 'wt1', connected: true, writable: true }] - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId, spec: 'work' }) const ctx = createRootDispatch(db, task.id, 'term_a') const coordinator = new Coordinator(db, runtime, { @@ -581,6 +614,7 @@ describe('Coordinator', () => { const runPromise = coordinator.run() db.insertMessage({ + runId, from: 'term_a', to: 'coord', subject: 'alive', @@ -606,12 +640,16 @@ describe('Coordinator', () => { const runtime = createMockRuntime() const logs: string[] = [] - const task = db.createTask({ spec: 'retry-sensitive work' }) + const task = db.createTask({ + runId, + spec: 'retry-sensitive work' + }) const staleCtx = createRootDispatch(db, task.id, 'term_old') db.failDispatch(staleCtx.id, 'retry elsewhere') const activeCtx = createRootDispatch(db, task.id, 'term_current') db.insertMessage({ + runId, from: 'term_old', to: 'coord', subject: 'Late done', @@ -663,11 +701,15 @@ describe('Coordinator', () => { const runtime = createMockRuntime() const logs: string[] = [] - const task = db.createTask({ spec: 'owned work' }) + const task = db.createTask({ + runId, + spec: 'owned work' + }) const leafId = '11111111-1111-4111-8111-111111111111' const ctx = createRootDispatch(db, task.id, 'term_owner', `tab_before:${leafId}`) db.insertMessage({ + runId, from: 'term_reminted', to: 'coord', subject: 'Done after restart', @@ -693,7 +735,7 @@ describe('Coordinator', () => { it('can be stopped', async () => { db = new OrchestrationDb(':memory:') const runtime = createMockRuntime() - db.createTask({ spec: 'never finishes' }) + db.createTask({ runId, spec: 'never finishes' }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -723,7 +765,10 @@ describe('Coordinator', () => { recentSubjects: ['fix A', 'fix B', 'fix C'] }) - const task = db.createTask({ spec: 'do the work' }) + const task = db.createTask({ + runId, + spec: 'do the work' + }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -759,7 +804,10 @@ describe('Coordinator', () => { recentSubjects: ['fix A'] }) - const task = db.createTask({ spec: 'do the work' }) + const task = db.createTask({ + runId, + spec: 'do the work' + }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -799,7 +847,7 @@ describe('Coordinator', () => { const spec = `Investigate issue #42 allow-stale-base: true` - const task = db.createTask({ spec }) + const task = db.createTask({ runId, spec }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -832,7 +880,10 @@ allow-stale-base: true` runtime.terminals = [{ handle: 'term_a', worktreeId: 'wt1', connected: true, writable: true }] runtime.setProbeDrift(null) - const task = db.createTask({ spec: 'do the work' }) + const task = db.createTask({ + runId, + spec: 'do the work' + }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -861,7 +912,10 @@ allow-stale-base: true` runtime.terminals = [{ handle: 'term_a', worktreeId: 'wt1', connected: true, writable: true }] const logs: string[] = [] - const task = db.createTask({ spec: 'do the work' }) + const task = db.createTask({ + runId, + spec: 'do the work' + }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -892,7 +946,10 @@ allow-stale-base: true` runtime.terminals = [{ handle: 'term_a', worktreeId: 'wt1', connected: true, writable: true }] runtime.throwProbeDrift = new Error('boom') - const task = db.createTask({ spec: 'do the work' }) + const task = db.createTask({ + runId, + spec: 'do the work' + }) const coordinator = new Coordinator(db, runtime, { spec: 'go', @@ -915,53 +972,3 @@ allow-stale-base: true` }) }) }) - -describe('parseAllowStaleBaseFromSpec', () => { - it('matches canonical form on its own line and strips it', () => { - const spec = `Do the work -allow-stale-base: true` - const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) - expect(allowStale).toBe(true) - expect(strippedSpec).toBe('Do the work\n') - expect(strippedSpec).not.toContain('allow-stale-base') - }) - - it('matches case-insensitively', () => { - const spec = `Do the work -Allow-Stale-Base: TRUE` - const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) - expect(allowStale).toBe(true) - expect(strippedSpec).not.toMatch(/[Aa]llow-[Ss]tale-[Bb]ase/) - }) - - it('does not match allow-stale-base: false', () => { - const spec = `Do the work -allow-stale-base: false` - const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) - expect(allowStale).toBe(false) - expect(strippedSpec).toBe(spec) - }) - - it('does not match allow-stale-base: truthy', () => { - const spec = `Do the work -allow-stale-base: truthy` - const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) - expect(allowStale).toBe(false) - expect(strippedSpec).toBe(spec) - }) - - it('does not match the flag embedded inside a sentence', () => { - const spec = 'we allow-stale-base: true sometimes' - const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) - expect(allowStale).toBe(false) - expect(strippedSpec).toBe(spec) - }) - - it('handles the flag as the last line with no trailing newline', () => { - const spec = 'line 1\nallow-stale-base: true' - const { allowStale, strippedSpec } = parseAllowStaleBaseFromSpec(spec) - expect(allowStale).toBe(true) - expect(strippedSpec).toBe('line 1\n') - expect(strippedSpec.endsWith('allow-stale-base: true')).toBe(false) - }) -}) diff --git a/src/main/runtime/orchestration/db-empty-dispatch-shortcircuit.benchmark.test.ts b/src/main/runtime/orchestration/db-empty-dispatch-shortcircuit.benchmark.test.ts index c729a8b1dd7..6407e67bc4b 100644 --- a/src/main/runtime/orchestration/db-empty-dispatch-shortcircuit.benchmark.test.ts +++ b/src/main/runtime/orchestration/db-empty-dispatch-shortcircuit.benchmark.test.ts @@ -64,7 +64,7 @@ describe('orchestration empty-dispatch short-circuit (benchmark)', () => { it('still runs the fan-out once a dispatch exists (correctness preserved)', () => { const db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) createRootDispatch(db, task.id, 'term_5') const handles = Array.from({ length: 10 }, (_, i) => `term_${i}`) @@ -76,7 +76,11 @@ describe('orchestration empty-dispatch short-circuit (benchmark)', () => { it('predicate lifecycle: false when empty, true after dispatch (even completed), false after reset', () => { const db = new OrchestrationDb(':memory:') expect(db.hasAnyDispatchContexts()).toBe(false) - const ctx = createRootDispatch(db, db.createTask({ spec: 'work' }).id, 'term_worker') + const ctx = createRootDispatch( + db, + db.createTask({ runId: 'run_legacy_local', spec: 'work' }).id, + 'term_worker' + ) expect(db.hasAnyDispatchContexts()).toBe(true) // Completed rows still count — recent-completed lookups must stay valid. db.completeDispatch(ctx.id) diff --git a/src/main/runtime/orchestration/db-heartbeat-straggler-guard.test.ts b/src/main/runtime/orchestration/db-heartbeat-straggler-guard.test.ts index 793c218e162..c7743757aa9 100644 --- a/src/main/runtime/orchestration/db-heartbeat-straggler-guard.test.ts +++ b/src/main/runtime/orchestration/db-heartbeat-straggler-guard.test.ts @@ -13,7 +13,7 @@ afterEach(() => { function seedHeartbeatedDispatch(): { d: OrchestrationDb; dispatchId: string } { const d = new OrchestrationDb(':memory:') db = d - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(d, task.id, 'term_worker') d.recordHeartbeat(dispatch.id, '2026-05-03T00:00:00.000Z') return { d, dispatchId: dispatch.id } diff --git a/src/main/runtime/orchestration/db-message-timestamp.test.ts b/src/main/runtime/orchestration/db-message-timestamp.test.ts index d4d000c48d3..3900904e5b1 100644 --- a/src/main/runtime/orchestration/db-message-timestamp.test.ts +++ b/src/main/runtime/orchestration/db-message-timestamp.test.ts @@ -8,7 +8,12 @@ describe('orchestration message timestamps', () => { it('exposes SQLite timestamps with an explicit UTC designator', () => { db = new OrchestrationDb(':memory:') - const message = db.insertMessage({ from: 'a', to: 'b', subject: 'timestamped' }) + const message = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'b', + subject: 'timestamped' + }) expect(message.created_at).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/) db.markAsDelivered([message.id]) diff --git a/src/main/runtime/orchestration/db-messages.test.ts b/src/main/runtime/orchestration/db-messages.test.ts new file mode 100644 index 00000000000..789797d12f0 --- /dev/null +++ b/src/main/runtime/orchestration/db-messages.test.ts @@ -0,0 +1,194 @@ +import { afterEach, describe, expect, it } from 'vitest' +import type Database from '../../sqlite/sync-database' +import { OrchestrationDb, type MessageType } from './db' + +const runId = 'run_legacy_local' + +describe('OrchestrationDb', () => { + let db: OrchestrationDb | undefined + + afterEach(() => { + db?.close() + }) + + function createDb(): OrchestrationDb { + db = new OrchestrationDb(':memory:') + return db + } + + describe('messages', () => { + it('inserts and retrieves a message', () => { + const d = createDb() + const msg = d.insertMessage({ + runId, + from: 'term_a', + to: 'term_b', + subject: 'hello', + body: 'world' + }) + expect(msg.id).toMatch(/^msg_/) + expect(msg.from_handle).toBe('term_a') + expect(msg.to_handle).toBe('term_b') + expect(msg.subject).toBe('hello') + expect(msg.body).toBe('world') + expect(msg.type).toBe('status') + expect(msg.priority).toBe('normal') + expect(msg.read).toBe(0) + expect(msg.sequence).toBeGreaterThan(0) + }) + + it('returns unread messages in sequence order', () => { + const d = createDb() + d.insertMessage({ runId, from: 'a', to: 'b', subject: 'first' }) + d.insertMessage({ runId, from: 'a', to: 'b', subject: 'second' }) + d.insertMessage({ runId, from: 'a', to: 'c', subject: 'other' }) + + const unread = d.getUnreadMessages('b') + expect(unread).toHaveLength(2) + expect(unread[0].subject).toBe('first') + expect(unread[1].subject).toBe('second') + }) + + it('filters unread by type', () => { + const d = createDb() + d.insertMessage({ + runId, + from: 'a', + to: 'b', + subject: 'status msg', + type: 'status' + }) + d.insertMessage({ + runId, + from: 'a', + to: 'b', + subject: 'done msg', + type: 'worker_done' + }) + + const filtered = d.getUnreadMessages('b', ['worker_done']) + expect(filtered).toHaveLength(1) + expect(filtered[0].type).toBe('worker_done') + }) + + it('excludes already-delivered rows from getUndeliveredUnreadMessages', () => { + const d = createDb() + const m1 = d.insertMessage({ runId, from: 'a', to: 'b', subject: 'one' }) + const m2 = d.insertMessage({ runId, from: 'a', to: 'b', subject: 'two' }) + + d.markAsDelivered([m1.id]) + + // Push delivery query: only undelivered, unread. + const pending = d.getUndeliveredUnreadMessages('b') + expect(pending).toHaveLength(1) + expect(pending[0].id).toBe(m2.id) + + // Explicit `check` still sees both (they are still unread). + const unread = d.getUnreadMessages('b') + expect(unread).toHaveLength(2) + }) + + it('creates the undelivered inbox index used by push delivery', () => { + const d = createDb() + const sqlite = (d as unknown as { db: Database.Database }).db + + const indexes = sqlite + .prepare( + `SELECT name FROM sqlite_master WHERE type = 'index' AND tbl_name = 'messages' AND name = 'idx_messages_undelivered_inbox'` + ) + .all() + + expect(indexes).toHaveLength(1) + }) + + it('filters getUndeliveredUnreadMessages by type', () => { + const d = createDb() + d.insertMessage({ + runId, + from: 'a', + to: 'b', + subject: 's', + type: 'status' + }) + const wd = d.insertMessage({ + runId, + from: 'a', + to: 'b', + subject: 'd', + type: 'worker_done' + }) + + const filtered = d.getUndeliveredUnreadMessages('b', ['worker_done']) + expect(filtered).toHaveLength(1) + expect(filtered[0].id).toBe(wd.id) + }) + + it('marks messages as read', () => { + const d = createDb() + const m1 = d.insertMessage({ runId, from: 'a', to: 'b', subject: 'one' }) + const m2 = d.insertMessage({ runId, from: 'a', to: 'b', subject: 'two' }) + + d.markAsRead([m1.id]) + + const unread = d.getUnreadMessages('b') + expect(unread).toHaveLength(1) + expect(unread[0].id).toBe(m2.id) + }) + + it('stores typed payload and thread_id', () => { + const d = createDb() + const payload = JSON.stringify({ taskId: 'task_abc', filesModified: ['src/a.ts'] }) + const msg = d.insertMessage({ + runId, + from: 'a', + to: 'b', + subject: 'done', + type: 'worker_done', + priority: 'high', + threadId: 'thread_1', + payload + }) + + expect(msg.type).toBe('worker_done') + expect(msg.priority).toBe('high') + expect(msg.thread_id).toBe('thread_1') + expect(msg.payload).toBe(payload) + }) + + it('rejects invalid message type', () => { + const d = createDb() + expect(() => + d.insertMessage({ + runId, + from: 'a', + to: 'b', + subject: 'bad', + type: 'invalid' as MessageType + }) + ).toThrow() + }) + + it('getInbox returns all messages across recipients', () => { + const d = createDb() + d.insertMessage({ runId, from: 'a', to: 'b', subject: 'one' }) + d.insertMessage({ runId, from: 'a', to: 'c', subject: 'two' }) + d.insertMessage({ runId, from: 'b', to: 'a', subject: 'three' }) + + const inbox = d.getInbox(10) + expect(inbox).toHaveLength(3) + }) + + it('getMessageById returns the correct message', () => { + const d = createDb() + const msg = d.insertMessage({ + runId, + from: 'a', + to: 'b', + subject: 'test' + }) + const found = d.getMessageById(msg.id) + expect(found?.subject).toBe('test') + expect(d.getMessageById('msg_nonexistent')).toBeUndefined() + }) + }) +}) diff --git a/src/main/runtime/orchestration/db-task-create-readiness.test.ts b/src/main/runtime/orchestration/db-task-create-readiness.test.ts index 019b627da6c..4b661829d02 100644 --- a/src/main/runtime/orchestration/db-task-create-readiness.test.ts +++ b/src/main/runtime/orchestration/db-task-create-readiness.test.ts @@ -33,12 +33,16 @@ describe('task creation dependency readiness', () => { it('creates a late dependent as ready when every dependency is completed', () => { const db = createDb() - const first = db.createTask({ spec: 'first' }) - const second = db.createTask({ spec: 'second' }) + const first = db.createTask({ runId: 'run_legacy_local', spec: 'first' }) + const second = db.createTask({ runId: 'run_legacy_local', spec: 'second' }) db.updateTaskStatus(first.id, 'completed') db.updateTaskStatus(second.id, 'completed') - const child = db.createTask({ spec: 'child', deps: [first.id, second.id] }) + const child = db.createTask({ + runId: 'run_legacy_local', + spec: 'child', + deps: [first.id, second.id] + }) expect(child.status).toBe('ready') }) @@ -49,7 +53,7 @@ describe('task creation dependency readiness', () => { const path = join(directory, 'orchestration.db') const db = createDb(path) const concurrent = createDb(path) - const dependency = db.createTask({ spec: 'dependency' }) + const dependency = db.createTask({ runId: 'run_legacy_local', spec: 'dependency' }) const sqlite = (db as unknown as OrchestrationDbAccess).db const prepare = sqlite.prepare.bind(sqlite) let injected = false @@ -61,7 +65,7 @@ describe('task creation dependency readiness', () => { return prepare(sql) }) - const child = db.createTask({ spec: 'child', deps: [dependency.id] }) + const child = db.createTask({ runId: 'run_legacy_local', spec: 'child', deps: [dependency.id] }) expect(injected).toBe(true) expect(child.status).toBe('ready') @@ -69,10 +73,14 @@ describe('task creation dependency readiness', () => { it('promotes only after every dependency completes', () => { const db = createDb() - const first = db.createTask({ spec: 'first' }) - const second = db.createTask({ spec: 'second' }) + const first = db.createTask({ runId: 'run_legacy_local', spec: 'first' }) + const second = db.createTask({ runId: 'run_legacy_local', spec: 'second' }) db.updateTaskStatus(first.id, 'completed') - const child = db.createTask({ spec: 'child', deps: [first.id, second.id] }) + const child = db.createTask({ + runId: 'run_legacy_local', + spec: 'child', + deps: [first.id, second.id] + }) expect(child.status).toBe('pending') db.updateTaskStatus(second.id, 'completed') @@ -83,11 +91,15 @@ describe('task creation dependency readiness', () => { 'does not unlock a dependent whose dependency is %s', (status) => { const db = createDb() - const terminal = db.createTask({ spec: 'terminal dependency' }) - const completing = db.createTask({ spec: 'completing dependency' }) + const terminal = db.createTask({ runId: 'run_legacy_local', spec: 'terminal dependency' }) + const completing = db.createTask({ runId: 'run_legacy_local', spec: 'completing dependency' }) db.updateTaskStatus(terminal.id, status) - const child = db.createTask({ spec: 'child', deps: [terminal.id, completing.id] }) + const child = db.createTask({ + runId: 'run_legacy_local', + spec: 'child', + deps: [terminal.id, completing.id] + }) expect(child.status).toBe('pending') db.updateTaskStatus(completing.id, 'completed') @@ -98,9 +110,9 @@ describe('task creation dependency readiness', () => { it('rejects missing dependencies without inserting a task', () => { const db = createDb() - expect(() => db.createTask({ spec: 'child', deps: ['task_missing'] })).toThrow( - 'Dependency task task_missing must belong to run' - ) + expect(() => + db.createTask({ runId: 'run_legacy_local', spec: 'child', deps: ['task_missing'] }) + ).toThrow('Dependency task task_missing must belong to run') expect(db.listTasks()).toEqual([]) }) @@ -109,7 +121,7 @@ describe('task creation dependency readiness', () => { const sqlite = (db as unknown as OrchestrationDbAccess).db sqlite.exec('BEGIN IMMEDIATE') - const task = db.createTask({ spec: 'transactional child' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'transactional child' }) sqlite.exec('ROLLBACK') expect(db.getTask(task.id)).toBeUndefined() @@ -120,11 +132,19 @@ describe('task creation dependency readiness', () => { directories.push(directory) const path = join(directory, 'orchestration.db') const before = createDb(path) - const completed = before.createTask({ spec: 'completed' }) - const open = before.createTask({ spec: 'open' }) + const completed = before.createTask({ runId: 'run_legacy_local', spec: 'completed' }) + const open = before.createTask({ runId: 'run_legacy_local', spec: 'open' }) before.updateTaskStatus(completed.id, 'completed') - const ready = before.createTask({ spec: 'ready', deps: [completed.id] }) - const pending = before.createTask({ spec: 'pending', deps: [completed.id, open.id] }) + const ready = before.createTask({ + runId: 'run_legacy_local', + spec: 'ready', + deps: [completed.id] + }) + const pending = before.createTask({ + runId: 'run_legacy_local', + spec: 'pending', + deps: [completed.id, open.id] + }) before.close() databases.splice(databases.indexOf(before), 1) diff --git a/src/main/runtime/orchestration/db-task-dispatch-invariant.test.ts b/src/main/runtime/orchestration/db-task-dispatch-invariant.test.ts index 53340b6dce5..2b81b2f2897 100644 --- a/src/main/runtime/orchestration/db-task-dispatch-invariant.test.ts +++ b/src/main/runtime/orchestration/db-task-dispatch-invariant.test.ts @@ -30,9 +30,17 @@ describe('Task/Dispatch invariant transactions', () => { 'allows a dependency-blocked pending Task to become %s', (status) => { const { db } = createDatabase() - const dependency = db.createTask({ spec: 'unresolved dependency' }) - const task = db.createTask({ spec: 'manual resolution', deps: [dependency.id] }) - const dependent = db.createTask({ spec: 'downstream work', deps: [task.id] }) + const dependency = db.createTask({ runId: 'run_legacy_local', spec: 'unresolved dependency' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'manual resolution', + deps: [dependency.id] + }) + const dependent = db.createTask({ + runId: 'run_legacy_local', + spec: 'downstream work', + deps: [task.id] + }) expect(task.status).toBe('pending') const updated = db.updateTaskStatus(task.id, status, 'manual resolution') @@ -45,7 +53,7 @@ describe('Task/Dispatch invariant transactions', () => { it('surfaces invalid Task lifecycle edges instead of returning the unchanged row', () => { const { db } = createDatabase() - const task = db.createTask({ spec: 'invalid lifecycle edge' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'invalid lifecycle edge' }) db.updateTaskStatus(task.id, 'blocked') expect(() => @@ -67,8 +75,12 @@ describe('Task/Dispatch invariant transactions', () => { 'rolls back a %s Task when Dispatch settlement fails', (status) => { const { db } = createDatabase() - const task = db.createTask({ spec: 'atomic work' }) - const dependent = db.createTask({ spec: 'dependent work', deps: [task.id] }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'atomic work' }) + const dependent = db.createTask({ + runId: 'run_legacy_local', + spec: 'dependent work', + deps: [task.id] + }) const dispatch = createRootDispatch(db, task.id, 'term_worker') const capability = db.mintDispatchCapability({ dispatchId: dispatch.id, @@ -111,7 +123,10 @@ describe('Task/Dispatch invariant transactions', () => { it('does not commit a caller-owned transaction', () => { const { db } = createDatabase() - const task = db.createTask({ spec: 'outer transaction work' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'outer transaction work' + }) const dispatch = createRootDispatch(db, task.id, 'term_worker') const sqlite = sqliteFor(db) @@ -135,7 +150,10 @@ describe('Task/Dispatch invariant transactions', () => { it('keeps Dispatch creation inside a caller-owned transaction', () => { const { db } = createDatabase() - const task = db.createTask({ spec: 'outer transaction dispatch' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'outer transaction dispatch' + }) const sqlite = sqliteFor(db) sqlite.exec('BEGIN IMMEDIATE') @@ -152,7 +170,10 @@ describe('Task/Dispatch invariant transactions', () => { 'settles every active Dispatch left by a pre-fix split when the Task becomes %s', (status) => { const { db } = createDatabase() - const task = db.createTask({ spec: 'legacy split work' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'legacy split work' + }) const first = createRootDispatch(db, task.id, 'term_first') sqliteFor(db).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const second = createRootDispatch(db, task.id, 'term_second') @@ -169,17 +190,31 @@ describe('Task/Dispatch invariant transactions', () => { expect(db.getActiveDispatchForTerminal('term_first')).toBeUndefined() expect(db.getActiveDispatchForTerminal('term_second')).toBeUndefined() expect(() => - createRootDispatch(db, db.createTask({ spec: 'first later work' }).id, 'term_first') + createRootDispatch( + db, + db.createTask({ runId: 'run_legacy_local', spec: 'first later work' }).id, + 'term_first' + ) ).not.toThrow() expect(() => - createRootDispatch(db, db.createTask({ spec: 'second later work' }).id, 'term_second') + createRootDispatch( + db, + db.createTask({ + runId: 'run_legacy_local', + spec: 'second later work' + }).id, + 'term_second' + ) ).not.toThrow() } ) it('does not requeue a legacy split Task while another Dispatch remains active', () => { const { db } = createDatabase() - const task = db.createTask({ spec: 'legacy split retry' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'legacy split retry' + }) const first = createRootDispatch(db, task.id, 'term_first') sqliteFor(db).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const second = createRootDispatch(db, task.id, 'term_second') @@ -193,7 +228,10 @@ describe('Task/Dispatch invariant transactions', () => { it('does not block a legacy split Task while another Dispatch remains active', () => { const { db } = createDatabase() - const task = db.createTask({ spec: 'legacy split release' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'legacy split release' + }) const first = createRootDispatch(db, task.id, 'term_first') sqliteFor(db).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const second = createRootDispatch(db, task.id, 'term_second') @@ -211,7 +249,10 @@ describe('Task/Dispatch invariant transactions', () => { 'rejects moving a Task to %s while a Dispatch remains active', (status) => { const { db } = createDatabase() - const task = db.createTask({ spec: 'guarded work' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'guarded work' + }) const dispatch = createRootDispatch(db, task.id, 'term_worker') expect(() => db.updateTaskStatus(task.id, status, 'must not persist')).toThrowError( @@ -227,7 +268,10 @@ describe('Task/Dispatch invariant transactions', () => { it('rejects moving a Task to dispatched without an active Dispatch', () => { const { db } = createDatabase() - const task = db.createTask({ spec: 'unassigned work' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'unassigned work' + }) expect(() => db.updateTaskStatus(task.id, 'dispatched')).toThrowError( expect.objectContaining({ @@ -241,7 +285,10 @@ describe('Task/Dispatch invariant transactions', () => { it('rejects a Dispatch when failure wins after readiness was observed', () => { const first = createDatabase() const concurrent = createDatabase(first.path) - const task = first.db.createTask({ spec: 'interleaved work' }) + const task = first.db.createTask({ + runId: 'run_legacy_local', + spec: 'interleaved work' + }) const sqlite = sqliteFor(first.db) const prepare = sqlite.prepare.bind(sqlite) let injected = false @@ -264,8 +311,14 @@ describe('Task/Dispatch invariant transactions', () => { it('atomically rejects a same-pane Dispatch that loses the occupancy race', () => { const first = createDatabase() const concurrent = createDatabase(first.path) - const firstTask = first.db.createTask({ spec: 'first terminal claimant' }) - const secondTask = first.db.createTask({ spec: 'second terminal claimant' }) + const firstTask = first.db.createTask({ + runId: 'run_legacy_local', + spec: 'first terminal claimant' + }) + const secondTask = first.db.createTask({ + runId: 'run_legacy_local', + spec: 'second terminal claimant' + }) const sqlite = sqliteFor(first.db) const prepare = sqlite.prepare.bind(sqlite) let winnerId: string | undefined @@ -303,14 +356,20 @@ describe('Task/Dispatch invariant transactions', () => { it('rejects worker authority when another Dispatch owns the pane', () => { const { db } = createDatabase() - const ownerTask = db.createTask({ spec: 'current pane owner' }) + const ownerTask = db.createTask({ + runId: 'run_legacy_local', + spec: 'current pane owner' + }) const owner = createRootDispatch( db, ownerTask.id, 'term_owner', 'tab_old:cccccccc-cccc-4ccc-8ccc-cccccccccccc' ) - const workerTask = db.createTask({ spec: 'competing supervised worker' }) + const workerTask = db.createTask({ + runId: 'run_legacy_local', + spec: 'competing supervised worker' + }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -346,7 +405,10 @@ describe('Task/Dispatch invariant transactions', () => { 'rejects a %s Task update while its supervised worker remains active', (status) => { const { db } = createDatabase() - const task = db.createTask({ spec: 'supervised lifecycle' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'supervised lifecycle' + }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -394,7 +456,10 @@ describe('Task/Dispatch invariant transactions', () => { it('keeps a federated late start authoritative after rejecting Task failure', () => { const { db } = createDatabase() - const task = db.createTask({ spec: 'federated lifecycle' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'federated lifecycle' + }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/orchestration/db-task-dispatch-lifecycle-guards.test.ts b/src/main/runtime/orchestration/db-task-dispatch-lifecycle-guards.test.ts index bb6d3472d4e..f4cdcdf63b8 100644 --- a/src/main/runtime/orchestration/db-task-dispatch-lifecycle-guards.test.ts +++ b/src/main/runtime/orchestration/db-task-dispatch-lifecycle-guards.test.ts @@ -29,7 +29,7 @@ afterEach(() => { describe('Task/Dispatch lifecycle guards', () => { it('rejects a worker report while another supervised Dispatch is active', () => { const database = createDatabase() - const task = database.createTask({ spec: 'legacy supervised split' }) + const task = database.createTask({ runId: 'run_legacy_local', spec: 'legacy supervised split' }) const first = startWorker(database, task.id, 'first') sqliteFor(database).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const second = startWorker(database, task.id, 'second') @@ -55,7 +55,7 @@ describe('Task/Dispatch lifecycle guards', () => { 'settles context-only legacy siblings after a %s worker report', (outcome) => { const database = createDatabase() - const task = database.createTask({ spec: 'legacy mixed split' }) + const task = database.createTask({ runId: 'run_legacy_local', spec: 'legacy mixed split' }) const contextOnly = createRootDispatch(database, task.id, 'term_context') sqliteFor(database).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const worker = startWorker(database, task.id, 'reporter') @@ -78,7 +78,10 @@ describe('Task/Dispatch lifecycle guards', () => { expect(() => createRootDispatch( database, - database.createTask({ spec: 'later context work' }).id, + database.createTask({ + runId: 'run_legacy_local', + spec: 'later context work' + }).id, 'term_context' ) ).not.toThrow() @@ -87,7 +90,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('settles a newer context-only legacy sibling after a worker report', () => { const database = createDatabase() - const task = database.createTask({ spec: 'reversed legacy mixed split' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'reversed legacy mixed split' + }) const worker = startWorker(database, task.id, 'reversed_reporter') sqliteFor(database).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const contextOnly = createRootDispatch(database, task.id, 'term_reversed_context') @@ -112,7 +118,10 @@ describe('Task/Dispatch lifecycle guards', () => { 'treats abandon of an already %s worker as stale without a lifecycle conflict', (state) => { const database = createDatabase() - const task = database.createTask({ spec: `already ${state}` }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: `already ${state}` + }) const worker = startWorker(database, task.id, `already_${state}`) if (state === 'failed') { database.failDispatch(worker.dispatchId, 'process exited', { workerProcessExited: true }) @@ -130,7 +139,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('rejects generic failure while a supervised worker remains active', () => { const database = createDatabase() - const task = database.createTask({ spec: 'supervised failure guard' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'supervised failure guard' + }) const worker = startWorker(database, task.id, 'guarded') expect(() => database.failDispatch(worker.dispatchId, 'unsafe retry')).toThrowError( @@ -151,7 +163,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('atomically settles worker state when a proven process exit fails its Dispatch', () => { const database = createDatabase() - const task = database.createTask({ spec: 'exited worker' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'exited worker' + }) const worker = startWorker(database, task.id, 'exited') expect( @@ -168,7 +183,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('settles a stop-unknown worker when a positive PTY exit arrives', () => { const database = createDatabase() - const task = database.createTask({ spec: 'stop-unknown exited worker' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'stop-unknown exited worker' + }) const worker = startWorker(database, task.id, 'stop_unknown_exited') expect(database.beginWorkerStop(worker.dispatchId, 'runtime_test').disposition).toBe('stopping') @@ -198,7 +216,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('keeps a Task dispatched when missing-terminal recovery leaves another worker active', () => { const database = createDatabase() - const task = database.createTask({ spec: 'legacy missing-terminal split' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'legacy missing-terminal split' + }) const missing = startWorker(database, task.id, 'missing') sqliteFor(database).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const live = startWorker(database, task.id, 'live') @@ -225,7 +246,10 @@ describe('Task/Dispatch lifecycle guards', () => { 'keeps a Task dispatched when a %s worker start fails beside a live worker', (kind) => { const database = createDatabase() - const task = database.createTask({ spec: `${kind} split start failure` }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: `${kind} split start failure` + }) const failed = database.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -342,7 +366,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('rolls back federated start uncertainty when the Task transition cannot commit', () => { const database = createDatabase() - const task = database.createTask({ spec: 'atomic federated uncertainty' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'atomic federated uncertainty' + }) const started = database.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -383,7 +410,10 @@ describe('Task/Dispatch lifecycle guards', () => { '%s releases the last context-only sibling after a newer worker start fails', (operation) => { const database = createDatabase() - const task = database.createTask({ spec: `${operation} historical sibling` }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: `${operation} historical sibling` + }) const contextOnly = createRootDispatch(database, task.id, `term_${operation}`) sqliteFor(database).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const failed = database.createStartingWorkerDispatch({ @@ -411,7 +441,10 @@ describe('Task/Dispatch lifecycle guards', () => { expect(() => createRootDispatch( database, - database.createTask({ spec: `${operation} later work` }).id, + database.createTask({ + runId: 'run_legacy_local', + spec: `${operation} later work` + }).id, `term_${operation}` ) ).not.toThrow() @@ -422,7 +455,10 @@ describe('Task/Dispatch lifecycle guards', () => { '%s records guarded receipts for context-only Dispatch and Task release', (operation) => { const database = createDatabase() - const task = database.createTask({ spec: `${operation} receipt release` }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: `${operation} receipt release` + }) const contextOnly = createRootDispatch(database, task.id, `term_${operation}`) const released = @@ -445,7 +481,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('rolls back both context-only projections when the Task transition fails', () => { const database = createDatabase() - const task = database.createTask({ spec: 'context-only atomic receipt' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'context-only atomic receipt' + }) const contextOnly = createRootDispatch(database, task.id, 'term_context') sqliteFor(database).exec(` CREATE TRIGGER reject_context_release_task_block @@ -470,7 +509,10 @@ describe('Task/Dispatch lifecycle guards', () => { '%s preserves a live worker sibling and lets it report', (operation) => { const database = createDatabase() - const task = database.createTask({ spec: `${operation} legacy worker split` }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: `${operation} legacy worker split` + }) const live = startWorker(database, task.id, `${operation}_live`) sqliteFor(database).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const released = startWorker(database, task.id, `${operation}_released`) @@ -502,7 +544,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('blocks a Task when an interleaved stop settles its final active Dispatch', () => { const database = createDatabase() - const task = database.createTask({ spec: 'interleaved legacy worker release' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'interleaved legacy worker release' + }) const stopping = startWorker(database, task.id, 'interleaved_stopping') sqliteFor(database).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const abandoned = startWorker(database, task.id, 'interleaved_abandoned') @@ -521,7 +566,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('restores a live sibling after stopping an uncertain worker start', () => { const database = createDatabase() - const task = database.createTask({ spec: 'uncertain legacy worker split' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'uncertain legacy worker split' + }) const live = startWorker(database, task.id, 'uncertain_live') sqliteFor(database).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const uncertain = database.createStartingWorkerDispatch({ @@ -552,7 +600,10 @@ describe('Task/Dispatch lifecycle guards', () => { 'restores a live sibling after an uncertain worker start fails through %s', (recovery) => { const database = createDatabase() - const task = database.createTask({ spec: `${recovery} uncertain sibling` }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: `${recovery} uncertain sibling` + }) const live = startWorker(database, task.id, `${recovery}_live`) sqliteFor(database).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const uncertain = database.createStartingWorkerDispatch({ @@ -589,7 +640,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('rejects gate creation while a supervised worker remains active', () => { const database = createDatabase() - const task = database.createTask({ spec: 'worker gate guard' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'worker gate guard' + }) const worker = startWorker(database, task.id, 'gate') expect(() => database.createGate({ taskId: task.id, question: 'Proceed?' })).toThrowError( @@ -607,7 +661,10 @@ describe('Task/Dispatch lifecycle guards', () => { it('rolls back gate resolution when an active Dispatch blocks readiness', () => { const database = createDatabase() - const task = database.createTask({ spec: 'corrupt gated task' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'corrupt gated task' + }) const gate = database.createGate({ taskId: task.id, question: 'Proceed?' }) sqliteFor(database).prepare("UPDATE tasks SET status = 'ready' WHERE id = ?").run(task.id) const dispatch = createRootDispatch(database, task.id, 'term_worker') diff --git a/src/main/runtime/orchestration/db-task-dispatch-races.test.ts b/src/main/runtime/orchestration/db-task-dispatch-races.test.ts index b4c27ac0c64..c671aa4566b 100644 --- a/src/main/runtime/orchestration/db-task-dispatch-races.test.ts +++ b/src/main/runtime/orchestration/db-task-dispatch-races.test.ts @@ -29,7 +29,10 @@ describe('Task/Dispatch concurrency', () => { it('reads a concurrent Task result before applying an explicit status correction', () => { const first = createDatabase() const concurrent = createDatabase(first.path) - const task = first.db.createTask({ spec: 'concurrent status winner' }) + const task = first.db.createTask({ + runId: 'run_legacy_local', + spec: 'concurrent status winner' + }) const sqlite = sqliteFor(first.db) const exec = sqlite.exec.bind(sqlite) let concurrentWon = false @@ -57,7 +60,7 @@ describe('Task/Dispatch concurrency', () => { it('holds the Task status writer reservation through its lifecycle reads', () => { const first = createDatabase() const concurrent = createDatabase(first.path) - const task = first.db.createTask({ spec: 'reserved status winner' }) + const task = first.db.createTask({ runId: 'run_legacy_local', spec: 'reserved status winner' }) const sqlite = sqliteFor(first.db) const exec = sqlite.exec.bind(sqlite) sqliteFor(concurrent.db).pragma('busy_timeout = 0') @@ -86,7 +89,7 @@ describe('Task/Dispatch concurrency', () => { it('rolls back Dispatch failure when Task requeue fails', () => { const { db } = createDatabase() - const task = db.createTask({ spec: 'atomic retry failure' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'atomic retry failure' }) const dispatch = createRootDispatch(db, task.id, 'term_worker') sqliteFor(db).exec(` CREATE TRIGGER reject_task_requeue @@ -113,7 +116,10 @@ describe('Task/Dispatch concurrency', () => { it('does not let stale failure overwrite a completed worker report', () => { const first = createDatabase() const concurrent = createDatabase(first.path) - const task = first.db.createTask({ spec: 'worker completion wins' }) + const task = first.db.createTask({ + runId: 'run_legacy_local', + spec: 'worker completion wins' + }) const started = first.db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -177,7 +183,10 @@ describe('Task/Dispatch concurrency', () => { it('keeps nested dispatch failure atomic with its caller transaction', () => { const { db } = createDatabase() - const task = db.createTask({ spec: 'nested atomic failure' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'nested atomic failure' + }) const dispatch = createRootDispatch(db, task.id, 'term_worker') const sqlite = sqliteFor(db) @@ -198,8 +207,14 @@ describe('Task/Dispatch concurrency', () => { it('serializes reminted-pane worker authority claims', () => { const first = createDatabase() const concurrent = createDatabase(first.path) - const losingTask = first.db.createTask({ spec: 'losing worker' }) - const winningTask = first.db.createTask({ spec: 'winning worker' }) + const losingTask = first.db.createTask({ + runId: 'run_legacy_local', + spec: 'losing worker' + }) + const winningTask = first.db.createTask({ + runId: 'run_legacy_local', + spec: 'winning worker' + }) const loser = first.db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/orchestration/db-undelivered-mailboxes.test.ts b/src/main/runtime/orchestration/db-undelivered-mailboxes.test.ts index 86bc9fdf46b..b20dd625310 100644 --- a/src/main/runtime/orchestration/db-undelivered-mailboxes.test.ts +++ b/src/main/runtime/orchestration/db-undelivered-mailboxes.test.ts @@ -8,10 +8,20 @@ describe('undelivered orchestration mailboxes', () => { it('lists only mailboxes with undelivered unread messages', () => { db = new OrchestrationDb(':memory:') - const delivered = db.insertMessage({ from: 'a', to: 'delivered', subject: 'done' }) - const read = db.insertMessage({ from: 'a', to: 'read', subject: 'seen' }) - db.insertMessage({ from: 'a', to: 'pending', subject: 'first' }) - db.insertMessage({ from: 'a', to: 'pending', subject: 'second' }) + const delivered = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'delivered', + subject: 'done' + }) + const read = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'read', + subject: 'seen' + }) + db.insertMessage({ runId: 'run_legacy_local', from: 'a', to: 'pending', subject: 'first' }) + db.insertMessage({ runId: 'run_legacy_local', from: 'a', to: 'pending', subject: 'second' }) db.markAsDelivered([delivered.id]) db.markAsRead([read.id]) @@ -20,7 +30,12 @@ describe('undelivered orchestration mailboxes', () => { it('persists and settles a pending pointer Enter independently of delivery', () => { db = new OrchestrationDb(':memory:') - const message = db.insertMessage({ from: 'a', to: 'run:run_1', subject: 'staged' }) + const message = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run_1', + subject: 'staged' + }) expect( db.stageMailboxPointerEnter([message.id], { diff --git a/src/main/runtime/orchestration/db.test.ts b/src/main/runtime/orchestration/db.test.ts index 4825246586a..33af326f34d 100644 --- a/src/main/runtime/orchestration/db.test.ts +++ b/src/main/runtime/orchestration/db.test.ts @@ -4,9 +4,10 @@ import { join } from 'node:path' import { afterEach, describe, expect, it } from 'vitest' import Database from '../../sqlite/sync-database' import { LEGACY_RUN_ID, OrchestrationDb } from './db' -import type { MessageType } from './db' import { createRootDispatch } from './db/root-dispatch-test-fixture' +const runId = 'run_legacy_local' + // Overwrites the datetime('now')-seeded timestamps with explicit fixture values // so stale-detection assertions stay deterministic (no wall clock). function setDispatchTimes( @@ -33,154 +34,10 @@ describe('OrchestrationDb', () => { return db } - describe('messages', () => { - it('inserts and retrieves a message', () => { - const d = createDb() - const msg = d.insertMessage({ - from: 'term_a', - to: 'term_b', - subject: 'hello', - body: 'world' - }) - expect(msg.id).toMatch(/^msg_/) - expect(msg.from_handle).toBe('term_a') - expect(msg.to_handle).toBe('term_b') - expect(msg.subject).toBe('hello') - expect(msg.body).toBe('world') - expect(msg.type).toBe('status') - expect(msg.priority).toBe('normal') - expect(msg.read).toBe(0) - expect(msg.sequence).toBeGreaterThan(0) - }) - - it('returns unread messages in sequence order', () => { - const d = createDb() - d.insertMessage({ from: 'a', to: 'b', subject: 'first' }) - d.insertMessage({ from: 'a', to: 'b', subject: 'second' }) - d.insertMessage({ from: 'a', to: 'c', subject: 'other' }) - - const unread = d.getUnreadMessages('b') - expect(unread).toHaveLength(2) - expect(unread[0].subject).toBe('first') - expect(unread[1].subject).toBe('second') - }) - - it('filters unread by type', () => { - const d = createDb() - d.insertMessage({ from: 'a', to: 'b', subject: 'status msg', type: 'status' }) - d.insertMessage({ from: 'a', to: 'b', subject: 'done msg', type: 'worker_done' }) - - const filtered = d.getUnreadMessages('b', ['worker_done']) - expect(filtered).toHaveLength(1) - expect(filtered[0].type).toBe('worker_done') - }) - - it('excludes already-delivered rows from getUndeliveredUnreadMessages', () => { - const d = createDb() - const m1 = d.insertMessage({ from: 'a', to: 'b', subject: 'one' }) - const m2 = d.insertMessage({ from: 'a', to: 'b', subject: 'two' }) - - d.markAsDelivered([m1.id]) - - // Push delivery query: only undelivered, unread. - const pending = d.getUndeliveredUnreadMessages('b') - expect(pending).toHaveLength(1) - expect(pending[0].id).toBe(m2.id) - - // Explicit `check` still sees both (they are still unread). - const unread = d.getUnreadMessages('b') - expect(unread).toHaveLength(2) - }) - - it('creates the undelivered inbox index used by push delivery', () => { - const d = createDb() - const sqlite = (d as unknown as { db: Database.Database }).db - - const indexes = sqlite - .prepare( - `SELECT name FROM sqlite_master WHERE type = 'index' AND tbl_name = 'messages' AND name = 'idx_messages_undelivered_inbox'` - ) - .all() - - expect(indexes).toHaveLength(1) - }) - - it('filters getUndeliveredUnreadMessages by type', () => { - const d = createDb() - d.insertMessage({ from: 'a', to: 'b', subject: 's', type: 'status' }) - const wd = d.insertMessage({ from: 'a', to: 'b', subject: 'd', type: 'worker_done' }) - - const filtered = d.getUndeliveredUnreadMessages('b', ['worker_done']) - expect(filtered).toHaveLength(1) - expect(filtered[0].id).toBe(wd.id) - }) - - it('marks messages as read', () => { - const d = createDb() - const m1 = d.insertMessage({ from: 'a', to: 'b', subject: 'one' }) - const m2 = d.insertMessage({ from: 'a', to: 'b', subject: 'two' }) - - d.markAsRead([m1.id]) - - const unread = d.getUnreadMessages('b') - expect(unread).toHaveLength(1) - expect(unread[0].id).toBe(m2.id) - }) - - it('stores typed payload and thread_id', () => { - const d = createDb() - const payload = JSON.stringify({ taskId: 'task_abc', filesModified: ['src/a.ts'] }) - const msg = d.insertMessage({ - from: 'a', - to: 'b', - subject: 'done', - type: 'worker_done', - priority: 'high', - threadId: 'thread_1', - payload - }) - - expect(msg.type).toBe('worker_done') - expect(msg.priority).toBe('high') - expect(msg.thread_id).toBe('thread_1') - expect(msg.payload).toBe(payload) - }) - - it('rejects invalid message type', () => { - const d = createDb() - expect(() => - d.insertMessage({ - from: 'a', - to: 'b', - subject: 'bad', - type: 'invalid' as MessageType - }) - ).toThrow() - }) - - it('getInbox returns all messages across recipients', () => { - const d = createDb() - d.insertMessage({ from: 'a', to: 'b', subject: 'one' }) - d.insertMessage({ from: 'a', to: 'c', subject: 'two' }) - d.insertMessage({ from: 'b', to: 'a', subject: 'three' }) - - const inbox = d.getInbox(10) - expect(inbox).toHaveLength(3) - }) - - it('getMessageById returns the correct message', () => { - const d = createDb() - const msg = d.insertMessage({ from: 'a', to: 'b', subject: 'test' }) - const found = d.getMessageById(msg.id) - expect(found?.subject).toBe('test') - expect(d.getMessageById('msg_nonexistent')).toBeUndefined() - }) - }) - describe('tasks', () => { it('creates a task with no deps as ready', () => { const d = createDb() - const task = d.createTask({ spec: 'do something' }) + const task = d.createTask({ runId, spec: 'do something' }) expect(task.id).toMatch(/^task_/) expect(task.status).toBe('ready') expect(task.deps).toBe('[]') @@ -191,6 +48,7 @@ describe('OrchestrationDb', () => { it('persists explicit task display metadata', () => { const d = createDb() const task = d.createTask({ + runId, spec: 'full details', taskTitle: 'Checkout race', displayName: 'Fix checkout race' @@ -204,6 +62,7 @@ describe('OrchestrationDb', () => { it('persists the creating terminal handle for task-created worktrees', () => { const d = createDb() const task = d.createTask({ + runId, spec: 'spawn related workspace', createdByTerminalHandle: 'term_creator' }) @@ -214,16 +73,16 @@ describe('OrchestrationDb', () => { it('creates a task with deps as pending', () => { const d = createDb() - const parent = d.createTask({ spec: 'parent' }) - const child = d.createTask({ spec: 'child', deps: [parent.id] }) + const parent = d.createTask({ runId, spec: 'parent' }) + const child = d.createTask({ runId, spec: 'child', deps: [parent.id] }) expect(child.status).toBe('pending') expect(JSON.parse(child.deps)).toEqual([parent.id]) }) it('promotes pending tasks when deps complete', () => { const d = createDb() - const t1 = d.createTask({ spec: 'first' }) - const t2 = d.createTask({ spec: 'second', deps: [t1.id] }) + const t1 = d.createTask({ runId, spec: 'first' }) + const t2 = d.createTask({ runId, spec: 'second', deps: [t1.id] }) expect(d.getTask(t2.id)?.status).toBe('pending') @@ -234,9 +93,9 @@ describe('OrchestrationDb', () => { it('does not promote task until ALL deps complete', () => { const d = createDb() - const t1 = d.createTask({ spec: 'a' }) - const t2 = d.createTask({ spec: 'b' }) - const t3 = d.createTask({ spec: 'c', deps: [t1.id, t2.id] }) + const t1 = d.createTask({ runId, spec: 'a' }) + const t2 = d.createTask({ runId, spec: 'b' }) + const t3 = d.createTask({ runId, spec: 'c', deps: [t1.id, t2.id] }) d.updateTaskStatus(t1.id, 'completed') expect(d.getTask(t3.id)?.status).toBe('pending') @@ -247,7 +106,7 @@ describe('OrchestrationDb', () => { it('sets completed_at on completion', () => { const d = createDb() - const task = d.createTask({ spec: 'do it' }) + const task = d.createTask({ runId, spec: 'do it' }) const updated = d.updateTaskStatus(task.id, 'completed', '{"result": true}') expect(updated?.completed_at).toBeTruthy() expect(updated?.result).toBe('{"result": true}') @@ -255,7 +114,7 @@ describe('OrchestrationDb', () => { it('completing a task frees its active dispatch context', () => { const d = createDb() - const task = d.createTask({ spec: 'do it' }) + const task = d.createTask({ runId, spec: 'do it' }) createRootDispatch(d, task.id, 'term_a') d.updateTaskStatus(task.id, 'completed') @@ -266,8 +125,8 @@ describe('OrchestrationDb', () => { it('listTasks filters by status', () => { const d = createDb() - d.createTask({ spec: 'ready task' }) - const t2 = d.createTask({ spec: 'another' }) + d.createTask({ runId, spec: 'ready task' }) + const t2 = d.createTask({ runId, spec: 'another' }) d.updateTaskStatus(t2.id, 'completed') expect(d.listTasks({ status: 'ready' })).toHaveLength(1) @@ -277,15 +136,15 @@ describe('OrchestrationDb', () => { it('listTasks returns all when no filter', () => { const d = createDb() - d.createTask({ spec: 'one' }) - d.createTask({ spec: 'two' }) + d.createTask({ runId, spec: 'one' }) + d.createTask({ runId, spec: 'two' }) expect(d.listTasks()).toHaveLength(2) }) it('listTasksWithDispatch joins active dispatch metadata', () => { const d = createDb() - const ready = d.createTask({ spec: 'ready task' }) - const dispatched = d.createTask({ spec: 'active task' }) + const ready = d.createTask({ runId, spec: 'ready task' }) + const dispatched = d.createTask({ runId, spec: 'active task' }) const ctx = createRootDispatch(d, dispatched.id, 'term_worker') const rows = d.listTasksWithDispatch() @@ -300,7 +159,7 @@ describe('OrchestrationDb', () => { it('listTasksWithDispatch does not surface completed dispatches', () => { const d = createDb() - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) createRootDispatch(d, task.id, 'term_worker') d.updateTaskStatus(task.id, 'completed') @@ -314,8 +173,8 @@ describe('OrchestrationDb', () => { it('supports parent_id for task decomposition', () => { const d = createDb() - const parent = d.createTask({ spec: 'parent' }) - const child = d.createTask({ spec: 'child', parentId: parent.id }) + const parent = d.createTask({ runId, spec: 'parent' }) + const child = d.createTask({ runId, spec: 'child', parentId: parent.id }) expect(child.parent_id).toBe(parent.id) }) }) @@ -323,7 +182,7 @@ describe('OrchestrationDb', () => { describe('dispatch contexts', () => { it('creates a dispatch context and marks task as dispatched', () => { const d = createDb() - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) const ctx = createRootDispatch(d, task.id, 'term_worker') expect(ctx.id).toMatch(/^ctx_/) @@ -335,8 +194,8 @@ describe('OrchestrationDb', () => { it('rejects dispatch for non-ready tasks', () => { const d = createDb() - const parent = d.createTask({ spec: 'parent' }) - const child = d.createTask({ spec: 'child', deps: [parent.id] }) + const parent = d.createTask({ runId, spec: 'parent' }) + const child = d.createTask({ runId, spec: 'child', deps: [parent.id] }) expect(() => createRootDispatch(d, child.id, 'term_worker')).toThrow( /only ready tasks can be dispatched/ @@ -345,8 +204,8 @@ describe('OrchestrationDb', () => { it('rejects dispatch to an occupied terminal', () => { const d = createDb() - const t1 = d.createTask({ spec: 'first' }) - const t2 = d.createTask({ spec: 'second' }) + const t1 = d.createTask({ runId, spec: 'first' }) + const t2 = d.createTask({ runId, spec: 'second' }) createRootDispatch(d, t1.id, 'term_worker') expect(() => createRootDispatch(d, t2.id, 'term_worker')).toThrow( @@ -361,8 +220,8 @@ describe('OrchestrationDb', () => { it('rejects dispatch to a reminted handle on a pane with an active dispatch', () => { const d = createDb() - const t1 = d.createTask({ spec: 'first' }) - const t2 = d.createTask({ spec: 'second' }) + const t1 = d.createTask({ runId, spec: 'first' }) + const t2 = d.createTask({ runId, spec: 'second' }) createRootDispatch(d, t1.id, 'term_old', `tab_1:${LEAF_A}`) expect(() => createRootDispatch(d, t2.id, 'term_new', `tab_1:${LEAF_A}`)).toThrow( @@ -372,8 +231,8 @@ describe('OrchestrationDb', () => { it('rejects dispatch when pane keys share a leaf after break-out', () => { const d = createDb() - const t1 = d.createTask({ spec: 'first' }) - const t2 = d.createTask({ spec: 'second' }) + const t1 = d.createTask({ runId, spec: 'first' }) + const t2 = d.createTask({ runId, spec: 'second' }) createRootDispatch(d, t1.id, 'term_old', `tab_1:${LEAF_A}`) expect(() => createRootDispatch(d, t2.id, 'term_new', `tab_2:${LEAF_A}`)).toThrow( @@ -383,8 +242,8 @@ describe('OrchestrationDb', () => { it('allows concurrent dispatches to different panes', () => { const d = createDb() - const t1 = d.createTask({ spec: 'first' }) - const t2 = d.createTask({ spec: 'second' }) + const t1 = d.createTask({ runId, spec: 'first' }) + const t2 = d.createTask({ runId, spec: 'second' }) createRootDispatch(d, t1.id, 'term_a', `tab_1:${LEAF_A}`) expect(() => createRootDispatch(d, t2.id, 'term_b', `tab_1:${LEAF_B}`)).not.toThrow() @@ -392,8 +251,8 @@ describe('OrchestrationDb', () => { it('falls back to handle lock when pane keys are missing', () => { const d = createDb() - const t1 = d.createTask({ spec: 'first' }) - const t2 = d.createTask({ spec: 'second' }) + const t1 = d.createTask({ runId, spec: 'first' }) + const t2 = d.createTask({ runId, spec: 'second' }) createRootDispatch(d, t1.id, 'term_worker') // New dispatch has a pane key but the active row is legacy (no pane key): @@ -403,8 +262,8 @@ describe('OrchestrationDb', () => { it('allows dispatch to a terminal after previous dispatch completes', () => { const d = createDb() - const t1 = d.createTask({ spec: 'first' }) - const t2 = d.createTask({ spec: 'second' }) + const t1 = d.createTask({ runId, spec: 'first' }) + const t2 = d.createTask({ runId, spec: 'second' }) const ctx1 = createRootDispatch(d, t1.id, 'term_worker') d.completeDispatch(ctx1.id) @@ -414,7 +273,7 @@ describe('OrchestrationDb', () => { it('getDispatchContext returns latest for a task', () => { const d = createDb() - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) const ctx = createRootDispatch(d, task.id, 'term_a') const found = d.getDispatchContext(task.id) expect(found?.id).toBe(ctx.id) @@ -422,7 +281,7 @@ describe('OrchestrationDb', () => { it('getDispatchContext uses insertion order when timestamps tie', () => { const d = createDb() - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) const ctx1 = createRootDispatch(d, task.id, 'term_a') d.failDispatch(ctx1.id, 'retry') const ctx2 = createRootDispatch(d, task.id, 'term_a') @@ -432,7 +291,7 @@ describe('OrchestrationDb', () => { it('getActiveDispatchForTerminal returns active dispatch', () => { const d = createDb() - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) createRootDispatch(d, task.id, 'term_a') const active = d.getActiveDispatchForTerminal('term_a') @@ -442,10 +301,16 @@ describe('OrchestrationDb', () => { it('getLatestDispatchForTerminal returns the most recent completed dispatch', () => { const d = createDb() - const firstTask = d.createTask({ spec: 'first' }) + const firstTask = d.createTask({ + runId, + spec: 'first' + }) const first = createRootDispatch(d, firstTask.id, 'term_a') d.completeDispatch(first.id) - const secondTask = d.createTask({ spec: 'second' }) + const secondTask = d.createTask({ + runId, + spec: 'second' + }) const second = createRootDispatch(d, secondTask.id, 'term_a') d.completeDispatch(second.id) @@ -457,7 +322,7 @@ describe('OrchestrationDb', () => { it('circuit breaker trips after 3 failures', () => { const d = createDb() - const task = d.createTask({ spec: 'flaky' }) + const task = d.createTask({ runId, spec: 'flaky' }) const ctx = createRootDispatch(d, task.id, 'term_a') const after1 = d.failDispatch(ctx.id, 'timeout') @@ -480,7 +345,7 @@ describe('OrchestrationDb', () => { it('completeDispatch sets completed_at', () => { const d = createDb() - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) const ctx = createRootDispatch(d, task.id, 'term_a') d.completeDispatch(ctx.id) @@ -493,7 +358,10 @@ describe('OrchestrationDb', () => { describe('decision gates', () => { it('creates a gate and blocks the task', () => { const d = createDb() - const task = d.createTask({ spec: 'needs approval' }) + const task = d.createTask({ + runId, + spec: 'needs approval' + }) createRootDispatch(d, task.id, 'term_a') const gate = d.createGate({ taskId: task.id, @@ -513,7 +381,7 @@ describe('OrchestrationDb', () => { it('resolves a gate and unblocks the task', () => { const d = createDb() - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) const gate = d.createGate({ taskId: task.id, question: 'ok?' }) const resolved = d.resolveGate(gate.id, 'yes') @@ -526,7 +394,7 @@ describe('OrchestrationDb', () => { it('times out a gate', () => { const d = createDb() - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) const gate = d.createGate({ taskId: task.id, question: 'ok?' }) const timedOut = d.timeoutGate(gate.id) @@ -535,8 +403,8 @@ describe('OrchestrationDb', () => { it('lists gates with filters', () => { const d = createDb() - const t1 = d.createTask({ spec: 'a' }) - const t2 = d.createTask({ spec: 'b' }) + const t1 = d.createTask({ runId, spec: 'a' }) + const t2 = d.createTask({ runId, spec: 'b' }) d.createGate({ taskId: t1.id, question: 'q1' }) const g2 = d.createGate({ taskId: t2.id, question: 'q2' }) d.resolveGate(g2.id, 'done') @@ -599,8 +467,13 @@ describe('OrchestrationDb', () => { describe('lifecycle', () => { it('resetAll clears all tables', () => { const d = createDb() - d.insertMessage({ from: 'a', to: 'b', subject: 'test' }) - d.createTask({ spec: 'work' }) + d.insertMessage({ + runId, + from: 'a', + to: 'b', + subject: 'test' + }) + d.createTask({ runId, spec: 'work' }) d.resetAll() @@ -610,8 +483,13 @@ describe('OrchestrationDb', () => { it('resetMessages clears only messages', () => { const d = createDb() - d.insertMessage({ from: 'a', to: 'b', subject: 'test' }) - d.createTask({ spec: 'work' }) + d.insertMessage({ + runId, + from: 'a', + to: 'b', + subject: 'test' + }) + d.createTask({ runId, spec: 'work' }) d.resetMessages() @@ -621,8 +499,13 @@ describe('OrchestrationDb', () => { it('resetTasks clears tasks and dispatch contexts', () => { const d = createDb() - d.insertMessage({ from: 'a', to: 'b', subject: 'test' }) - const task = d.createTask({ spec: 'work' }) + d.insertMessage({ + runId, + from: 'a', + to: 'b', + subject: 'test' + }) + const task = d.createTask({ runId, spec: 'work' }) createRootDispatch(d, task.id, 'term_a') d.resetTasks() @@ -636,6 +519,7 @@ describe('OrchestrationDb', () => { it('insertMessage accepts type = heartbeat', () => { const d = createDb() const msg = d.insertMessage({ + runId, from: 'worker', to: 'coord', subject: 'alive', @@ -647,7 +531,7 @@ describe('OrchestrationDb', () => { it('recordHeartbeat updates last_heartbeat_at on dispatched rows', () => { const d = createDb() - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) const ctx = createRootDispatch(d, task.id, 'term_a') d.recordHeartbeat(ctx.id, '2026-05-04T00:00:00.000Z') @@ -662,10 +546,10 @@ describe('OrchestrationDb', () => { // (b) dispatched, heartbeated 12 min ago → STALE (expected result) // (c) dispatched, never heartbeated, dispatched 30s ago → not stale (grace) // (d) completed, heartbeated 30 min ago → not stale (status filter) - const taskA = d.createTask({ spec: 'a' }) - const taskB = d.createTask({ spec: 'b' }) - const taskC = d.createTask({ spec: 'c' }) - const taskD = d.createTask({ spec: 'd' }) + const taskA = d.createTask({ runId, spec: 'a' }) + const taskB = d.createTask({ runId, spec: 'b' }) + const taskC = d.createTask({ runId, spec: 'c' }) + const taskD = d.createTask({ runId, spec: 'd' }) const ctxA = createRootDispatch(d, taskA.id, 'term_a') const ctxB = createRootDispatch(d, taskB.id, 'term_b') const ctxC = createRootDispatch(d, taskC.id, 'term_c') @@ -710,15 +594,19 @@ describe('OrchestrationDb', () => { // Fresh worker: dispatched 12:00, heartbeat 12:05 (space-format), both // after the 11:55 threshold → NOT stale. - const fresh = createRootDispatch(d, d.createTask({ spec: 'fresh' }).id, 'term_fresh') + const fresh = createRootDispatch(d, d.createTask({ runId, spec: 'fresh' }).id, 'term_fresh') setDispatchTimes(d, fresh.id, '2026-07-12 12:00:00', '2026-07-12 12:05:00') // Legacy ISO-format fresh row (mixed-format table) stays fresh too. - const legacy = createRootDispatch(d, d.createTask({ spec: 'legacy' }).id, 'term_legacy') + const legacy = createRootDispatch( + d, + d.createTask({ runId, spec: 'legacy' }).id, + 'term_legacy' + ) setDispatchTimes(d, legacy.id, '2026-07-12T12:00:00.000Z', '2026-07-12T12:05:00.000Z') // Genuinely hung: dispatched + heartbeated at 10:00, ~2h before threshold. - const hung = createRootDispatch(d, d.createTask({ spec: 'hung' }).id, 'term_hung') + const hung = createRootDispatch(d, d.createTask({ runId, spec: 'hung' }).id, 'term_hung') setDispatchTimes(d, hung.id, '2026-07-12 10:00:00', '2026-07-12 10:00:00') const stale = d.getStaleDispatches('2026-07-12T11:55:00.000Z') @@ -730,7 +618,7 @@ describe('OrchestrationDb', () => { // Space-format dispatched_at one minute after the threshold, no heartbeat // yet → still inside the grace window, must not be flagged. - const ctx = createRootDispatch(d, d.createTask({ spec: 'x' }).id, 'term_x') + const ctx = createRootDispatch(d, d.createTask({ runId, spec: 'x' }).id, 'term_x') setDispatchTimes(d, ctx.id, '2026-07-12 12:00:00') const stale = d.getStaleDispatches('2026-07-12T11:59:00.000Z') @@ -742,7 +630,11 @@ describe('OrchestrationDb', () => { it('getStaleDispatches keeps a fresh row just after a UTC-midnight threshold (#8452)', () => { const d = createDb() - const ctx = createRootDispatch(d, d.createTask({ spec: 'midnight' }).id, 'term_midnight') + const ctx = createRootDispatch( + d, + d.createTask({ runId, spec: 'midnight' }).id, + 'term_midnight' + ) setDispatchTimes(d, ctx.id, '2026-05-04 00:04:00') const stale = d.getStaleDispatches('2026-05-04T00:00:00.000Z') @@ -755,7 +647,7 @@ describe('OrchestrationDb', () => { it('getStaleDispatches keeps a live worker with a fresh space-format heartbeat (#8452)', () => { const d = createDb() - const ctx = createRootDispatch(d, d.createTask({ spec: 'live' }).id, 'term_live') + const ctx = createRootDispatch(d, d.createTask({ runId, spec: 'live' }).id, 'term_live') setDispatchTimes(d, ctx.id, '2026-07-12 10:00:00', '2026-07-12 11:59:00') const stale = d.getStaleDispatches('2026-07-12T11:55:00.000Z') @@ -765,6 +657,7 @@ describe('OrchestrationDb', () => { it('getThreadMessagesFor returns only same-thread replies to a handle', () => { const d = createDb() const outbound = d.insertMessage({ + runId, from: 'worker', to: 'coord', subject: 'Question', @@ -773,6 +666,7 @@ describe('OrchestrationDb', () => { }) // Reply in the same thread addressed to the worker const reply = d.insertMessage({ + runId, from: 'coord', to: 'worker', subject: 'Re: Question', @@ -781,6 +675,7 @@ describe('OrchestrationDb', () => { }) // Distractor: different thread, same recipient d.insertMessage({ + runId, from: 'coord', to: 'worker', subject: 'other', @@ -789,6 +684,7 @@ describe('OrchestrationDb', () => { }) // Distractor: same thread but not addressed to worker d.insertMessage({ + runId, from: 'coord', to: 'someone_else', subject: 'cc', @@ -902,6 +798,7 @@ describe('OrchestrationDb', () => { // (a) INSERT type='heartbeat' now succeeds expect(() => d.insertMessage({ + runId, from: 'w', to: 'c', subject: 'alive', @@ -911,7 +808,7 @@ describe('OrchestrationDb', () => { ).not.toThrow() // (b) last_heartbeat_at column exists on dispatch_contexts - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) const ctx = createRootDispatch(d, task.id, 'term_a') d.recordHeartbeat(ctx.id, '2026-05-04T00:00:00.000Z') expect(d.getDispatchContext(task.id)?.last_heartbeat_at).toBe('2026-05-04T00:00:00.000Z') @@ -942,11 +839,12 @@ describe('OrchestrationDb', () => { const d = new OrchestrationDb(path) db = d - const task = d.createTask({ spec: 'work' }) + const task = d.createTask({ runId, spec: 'work' }) const ctx = createRootDispatch(d, task.id, 'term_a', 'tab_1:leaf_1') expect(d.getDispatchContextById(ctx.id)?.assignee_pane_key).toBe('tab_1:leaf_1') const msg = d.insertMessage({ + runId, from: 'w', to: 'c', subject: 'done', @@ -960,6 +858,7 @@ describe('OrchestrationDb', () => { const path = createV1Snapshot() const first = new OrchestrationDb(path) first.insertMessage({ + runId, from: 'w', to: 'c', subject: 'alive', @@ -972,6 +871,7 @@ describe('OrchestrationDb', () => { db = second expect(() => second.insertMessage({ + runId, from: 'w', to: 'c', subject: 'again', diff --git a/src/main/runtime/orchestration/db/attempt-outcome-projection.test.ts b/src/main/runtime/orchestration/db/attempt-outcome-projection.test.ts index eae300a7b20..a8dc098728a 100644 --- a/src/main/runtime/orchestration/db/attempt-outcome-projection.test.ts +++ b/src/main/runtime/orchestration/db/attempt-outcome-projection.test.ts @@ -48,7 +48,7 @@ describe('durable Attempt observation and outcome projection', () => { function createAttempt(): { taskId: string; dispatchId: string } { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'observe outcome' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'observe outcome' }) const dispatch = createRootDispatch(db, task.id, 'term_observed') return { taskId: task.id, dispatchId: dispatch.id } } @@ -162,7 +162,10 @@ describe('durable Attempt observation and outcome projection', () => { const path = join(dir, 'orchestration.sqlite') try { db = new OrchestrationDb(path) - const task = db.createTask({ spec: 'durable observation' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'durable observation' + }) const dispatch = createRootDispatch(db, task.id, 'term_durable') db.recordAttemptObservation( fact(dispatch.id, { @@ -189,7 +192,10 @@ describe('durable Attempt observation and outcome projection', () => { it('keeps worker_done settlement as the atomic success fast path', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'worker_done fast path' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'worker_done fast path' + }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/orchestration/db/contract-constants.ts b/src/main/runtime/orchestration/db/contract-constants.ts index 287ce565d5b..47e0cd6165a 100644 --- a/src/main/runtime/orchestration/db/contract-constants.ts +++ b/src/main/runtime/orchestration/db/contract-constants.ts @@ -7,4 +7,4 @@ export const LEGACY_CONTRACT_VERSION = 0 export const CURRENT_CONTRACT_VERSION = ORCHESTRATION_CONTRACT_VERSION // Schema versions: v2 'heartbeat'+last_heartbeat_at, v3 delivered_at, v4 task-creator terminal, v5 task_title/display_name, v6 pane identity, v7 lightweight Runs, v8 crash-safe Run deliveries, v9 durable question threads, v10 Dispatch capabilities, v11 durable mutation receipts, v12 composed worker state, v18 post-v6 version-skew repair, v19 adopted legacy Runs and compatibility receipts, v20 legacy question backfill, v21 legacy scheduler-loss provenance, v22 dispatch assignee lookup, v23 worker terminal resource ownership, v24 creator-incarnation authority, v25 active Dispatch handle lookup, v26 indexed mutation receipt capacity, v27 durable federation acknowledgments, v28 durable local mutation caller identity, v31 dispatch/resource identity links, v32 bounded worker-terminal recovery metadata, v33 durable mailbox pointer Enter state, v34 role-addressed mailbox deliveries, v35 mailbox delivery default and index-predicate repair, v36 dispatch mailbox consumer generation, v37 recorded dispatch creator identity, v39 structured session journal archives. -export const SCHEMA_VERSION = 39 +export const SCHEMA_VERSION = 40 diff --git a/src/main/runtime/orchestration/db/decision-gate-lifecycle.test.ts b/src/main/runtime/orchestration/db/decision-gate-lifecycle.test.ts index 219cf6fe212..9fdc9d9b5fb 100644 --- a/src/main/runtime/orchestration/db/decision-gate-lifecycle.test.ts +++ b/src/main/runtime/orchestration/db/decision-gate-lifecycle.test.ts @@ -9,7 +9,7 @@ describe('decision-gate lifecycle transitions', () => { it('blocks the dispatched Task when creating a gate', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'gate blocks task' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'gate blocks task' }) createRootDispatch(db, task.id, 'term_gate') expect(db.getTask(task.id)?.status).toBe('dispatched') @@ -20,7 +20,7 @@ describe('decision-gate lifecycle transitions', () => { it('rolls back the gate row when the Task transition cannot commit', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'atomic gate creation' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'atomic gate creation' }) const dispatch = createRootDispatch(db, task.id, 'term_gate') db.db.exec(` CREATE TRIGGER reject_gate_task_block diff --git a/src/main/runtime/orchestration/db/decision-gates/decision-gate-store.ts b/src/main/runtime/orchestration/db/decision-gates/decision-gate-store.ts index 532fa52b22a..296bcea42bc 100644 --- a/src/main/runtime/orchestration/db/decision-gates/decision-gate-store.ts +++ b/src/main/runtime/orchestration/db/decision-gates/decision-gate-store.ts @@ -1,6 +1,5 @@ import type { DecisionGateRow, DispatchContextRow, GateStatus } from '../../types' import { OrchestrationError } from '../../orchestration-error' -import { LEGACY_RUN_ID } from '../contract-constants' import { generateId } from '../generated-id' import type { OrchestrationDb } from '../orchestration-db' import { transitionLifecycleWithDb } from '../lifecycle-transition' @@ -18,6 +17,16 @@ export function createGate( ): DecisionGateRow { this.db.exec('SAVEPOINT create_gate') try { + const task = this.getTask(gate.taskId) + if (!task) { + throw new OrchestrationError( + 'lifecycle_not_found', + `Task ${gate.taskId} was not found while creating a decision gate.`, + { taskId: gate.taskId } + ) + } + const runId = task.run_id + this.requireRun(runId) const active = this.db .prepare( `SELECT * FROM dispatch_contexts @@ -65,22 +74,8 @@ export function createGate( .prepare( 'INSERT INTO decision_gates (id, run_id, task_id, question, options) VALUES (?, ?, ?, ?, ?)' ) - .run( - id, - this.getTask(gate.taskId)?.run_id ?? LEGACY_RUN_ID, - gate.taskId, - gate.question, - optionsJson - ) + .run(id, runId, gate.taskId, gate.question, optionsJson) this.completeActiveDispatchesForTask(gate.taskId) - const task = this.getTask(gate.taskId) - if (!task) { - throw new OrchestrationError( - 'lifecycle_not_found', - `Task ${gate.taskId} was not found while creating a decision gate.`, - { taskId: gate.taskId } - ) - } transitionLifecycleWithDb(this.db, { entity: 'task', id: gate.taskId, diff --git a/src/main/runtime/orchestration/db/dispatch-depth.test.ts b/src/main/runtime/orchestration/db/dispatch-depth.test.ts index 97df3f01c51..013cedffe91 100644 --- a/src/main/runtime/orchestration/db/dispatch-depth.test.ts +++ b/src/main/runtime/orchestration/db/dispatch-depth.test.ts @@ -16,7 +16,7 @@ describe('nested worker depth', () => { function coordinatorDispatchesWorker(maxDepth = UNCAPPED) { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'root task' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'root task' }) const worker = db.createDispatchContext({ taskId: task.id, assigneeHandle: 'term_worker', @@ -33,7 +33,7 @@ describe('nested worker depth', () => { it('refuses a worker dispatching a sub-worker at the default cap', () => { coordinatorDispatchesWorker() - const nested = db.createTask({ spec: 'nested task' }) + const nested = db.createTask({ runId: 'run_legacy_local', spec: 'nested task' }) expect(() => db.createDispatchContext({ taskId: nested.id, @@ -51,7 +51,7 @@ describe('nested worker depth', () => { it('tells the refused worker to complete the task itself', () => { coordinatorDispatchesWorker() - const nested = db.createTask({ spec: 'nested task' }) + const nested = db.createTask({ runId: 'run_legacy_local', spec: 'nested task' }) expect(() => db.createDispatchContext({ taskId: nested.id, @@ -64,7 +64,7 @@ describe('nested worker depth', () => { it('permits one more generation when the cap is raised, and records depth 2', () => { coordinatorDispatchesWorker() - const nested = db.createTask({ spec: 'nested task' }) + const nested = db.createTask({ runId: 'run_legacy_local', spec: 'nested task' }) const sub = db.createDispatchContext({ taskId: nested.id, assigneeHandle: 'term_sub', @@ -113,9 +113,9 @@ describe('nested worker depth', () => { db.db .prepare( `INSERT INTO remote_dispatch_attachments - (dispatch_id, task_id, home_peer_fingerprint, protocol_version, runtime_epoch, + (dispatch_id, task_id, home_run_id, home_peer_fingerprint, protocol_version, runtime_epoch, pane_key, process_incarnation, state, depth) - VALUES (?, ?, 'peer', 1, 'epoch', ?, ?, ?, ?)` + VALUES (?, ?, 'run_home', 'peer', 1, 'epoch', ?, ?, ?, ?)` ) .run(`ctx_${state}_${depth}_${paneKey}_${inc}`, 'task_remote', paneKey, inc, state, depth) } @@ -182,7 +182,10 @@ describe('nested worker depth', () => { it('takes the maximum when a process holds both a local and a remote role', () => { // Query order must not decide the answer: the deeper role governs. db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'local role' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'local role' + }) db.createDispatchContext({ taskId: task.id, assigneeHandle: 'term_both', @@ -220,13 +223,19 @@ describe('nested worker depth', () => { it('stamps depth 1 for a root coordinator', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'root work' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'root work' + }) expect(startWorker(task.id, SYSTEM, UNCAPPED).dispatch.depth).toBe(1) }) it('refuses a worker starting a sub-worker at the default cap', () => { coordinatorDispatchesWorker() - const nested = db.createTask({ spec: 'nested work' }) + const nested = db.createTask({ + runId: 'run_legacy_local', + spec: 'nested work' + }) expect(() => startWorker( nested.id, @@ -238,7 +247,10 @@ describe('nested worker depth', () => { it('refuses a worker retrying into a sub-worker at the default cap', () => { coordinatorDispatchesWorker() - const nested = db.createTask({ spec: 'nested retry work' }) + const nested = db.createTask({ + runId: 'run_legacy_local', + spec: 'nested retry work' + }) const first = startWorker(nested.id, SYSTEM, UNCAPPED) db.failWorkerStart(first.dispatch.id, 'accepted', 'first attempt failed') expect(() => @@ -257,7 +269,10 @@ describe('nested worker depth', () => { // Context-only dispatch stores null on purpose; requiring an incarnation // locally would silently drop real parents and fail open. db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'context only' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'context only' + }) const row = db.createDispatchContext({ taskId: task.id, assigneeHandle: 'term_ctx', diff --git a/src/main/runtime/orchestration/db/dispatch-mailbox-consumer-fencing.test.ts b/src/main/runtime/orchestration/db/dispatch-mailbox-consumer-fencing.test.ts index c7d287e8bdb..29a2e468ee8 100644 --- a/src/main/runtime/orchestration/db/dispatch-mailbox-consumer-fencing.test.ts +++ b/src/main/runtime/orchestration/db/dispatch-mailbox-consumer-fencing.test.ts @@ -22,7 +22,7 @@ describe('dispatch mailbox consumer fencing', () => { afterEach(() => db.close()) function dispatchWithMail(subjects: string[]): { id: string; runId: string } { - const task = db.createTask({ spec: 'fenced worker work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'fenced worker work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker', PANE_A) for (const subject of subjects) { db.insertMessage({ @@ -116,7 +116,10 @@ describe('dispatch mailbox consumer fencing', () => { }) it('bumps and fences on the worker-start attach path', () => { - const task = db.createTask({ spec: 'worker-start attach' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'worker-start attach' + }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -149,6 +152,7 @@ describe('dispatch mailbox consumer fencing', () => { it('gives a federated attachment its own generation on the worker host', () => { const dispatchId = 'ctx_remote_fence' db.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId, taskId: 'task_remote', homePeerFingerprint: 'home-peer', @@ -187,7 +191,10 @@ describe('dispatch mailbox consumer fencing', () => { }) it('starts a retry Dispatch on a fresh mailbox address rather than sharing the old one', () => { - const task = db.createTask({ spec: 'work that fails once' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'work that fails once' + }) const first = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/orchestration/db/dispatch-row-writer.ts b/src/main/runtime/orchestration/db/dispatch-row-writer.ts index 807814a87b1..84862ee343d 100644 --- a/src/main/runtime/orchestration/db/dispatch-row-writer.ts +++ b/src/main/runtime/orchestration/db/dispatch-row-writer.ts @@ -49,8 +49,8 @@ const STARTING_DISPATCH_CONTEXT_SQL = `INSERT INTO dispatch_contexts ( ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', datetime('now'))` const REMOTE_DISPATCH_ATTACHMENT_SQL = `INSERT INTO remote_dispatch_attachments ( - dispatch_id, task_id, home_peer_fingerprint, protocol_version, runtime_epoch, depth - ) VALUES (?, ?, ?, ?, ?, ?)` + dispatch_id, home_run_id, task_id, home_peer_fingerprint, protocol_version, runtime_epoch, depth + ) VALUES (?, ?, ?, ?, ?, ?, ?)` /** Last line of defence: a row that reached here unstamped would read as a root. */ function assertStampedDepth(depth: number): void { @@ -140,6 +140,7 @@ export function insertRemoteDispatchAttachmentRow( db: Database.Database, params: { dispatchId: string + runId: string taskId: string homePeerFingerprint: string protocolVersion: number @@ -151,6 +152,7 @@ export function insertRemoteDispatchAttachmentRow( assertStampedDepth(params.depth) db.prepare(REMOTE_DISPATCH_ATTACHMENT_SQL).run( params.dispatchId, + params.runId, params.taskId, params.homePeerFingerprint, params.protocolVersion, diff --git a/src/main/runtime/orchestration/db/federation/federated-dispatch-observation-fence.test.ts b/src/main/runtime/orchestration/db/federation/federated-dispatch-observation-fence.test.ts index e32bf27a00c..ecc3ca5e2c0 100644 --- a/src/main/runtime/orchestration/db/federation/federated-dispatch-observation-fence.test.ts +++ b/src/main/runtime/orchestration/db/federation/federated-dispatch-observation-fence.test.ts @@ -8,7 +8,10 @@ describe('federated Dispatch observation fence', () => { it('rejects out-of-order epochs and observations captured before release', () => { const database = (db = new OrchestrationDb(':memory:')) - const task = database.createTask({ spec: 'fenced federated observation' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'fenced federated observation' + }) const started = database.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/orchestration/db/federation/remote-dispatch-attachment-create.ts b/src/main/runtime/orchestration/db/federation/remote-dispatch-attachment-create.ts index 56d26ccfe3b..d927cf96838 100644 --- a/src/main/runtime/orchestration/db/federation/remote-dispatch-attachment-create.ts +++ b/src/main/runtime/orchestration/db/federation/remote-dispatch-attachment-create.ts @@ -8,6 +8,7 @@ export function createRemoteDispatchAttachment( this: OrchestrationDb, params: { dispatchId: string + runId: string taskId: string homePeerFingerprint: string protocolVersion: number @@ -43,6 +44,16 @@ export function createRemoteDispatchAttachment( `Remote attachment request ${params.mutationReceipt.requestId} already exists.` ) } + if (!params.runId?.trim()) { + throw new OrchestrationError('invalid_argument', 'Missing Run ID') + } + this.db + .prepare( + `INSERT OR IGNORE INTO runs (id, objective, home_database, consumer_generation, legacy) + VALUES (?, ?, 'remote', 0, 0)` + ) + .run(params.runId, `Coordinated from ${params.homePeerFingerprint}`) + this.requireRun(params.runId) ensureMutationReceiptCapacity(this.db) this.db .prepare( @@ -59,6 +70,7 @@ export function createRemoteDispatchAttachment( ) insertRemoteDispatchAttachmentRow(this.db, { dispatchId: params.dispatchId, + runId: params.runId, taskId: params.taskId, homePeerFingerprint: params.homePeerFingerprint, protocolVersion: params.protocolVersion, diff --git a/src/main/runtime/orchestration/db/federation/remote-dispatch-attachment-release.test.ts b/src/main/runtime/orchestration/db/federation/remote-dispatch-attachment-release.test.ts index ab515ffb30c..0865d4b8972 100644 --- a/src/main/runtime/orchestration/db/federation/remote-dispatch-attachment-release.test.ts +++ b/src/main/runtime/orchestration/db/federation/remote-dispatch-attachment-release.test.ts @@ -16,6 +16,7 @@ describe('the remote attachment release guard', () => { function settledAttachment(dispatchId: string): void { db.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId, taskId: `task_${dispatchId}`, homePeerFingerprint: 'home-peer', diff --git a/src/main/runtime/orchestration/db/lifecycle-transition.test.ts b/src/main/runtime/orchestration/db/lifecycle-transition.test.ts index eed4332879f..936208e77ef 100644 --- a/src/main/runtime/orchestration/db/lifecycle-transition.test.ts +++ b/src/main/runtime/orchestration/db/lifecycle-transition.test.ts @@ -8,7 +8,7 @@ describe('guarded lifecycle transitions', () => { it('rejects a stale prior state without changing the projection', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'guarded transition' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'guarded transition' }) expect(() => db!.transitionLifecycle({ @@ -23,7 +23,7 @@ describe('guarded lifecycle transitions', () => { it('composes its projection into the caller-owned transaction', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'caller-owned rollback' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'caller-owned rollback' }) db.db.exec('SAVEPOINT lifecycle_test') expect( @@ -49,7 +49,7 @@ describe('guarded lifecycle transitions', () => { ['completed', 'blocked'] ] as const)('preserves public task updates from %s to %s', (from, to) => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'manual status correction' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'manual status correction' }) db.db.prepare('UPDATE tasks SET status = ? WHERE id = ?').run(from, task.id) expect(db.updateTaskStatus(task.id, to)?.status).toBe(to) diff --git a/src/main/runtime/orchestration/db/messages/message-insert.ts b/src/main/runtime/orchestration/db/messages/message-insert.ts index 2984545a09b..82573305479 100644 --- a/src/main/runtime/orchestration/db/messages/message-insert.ts +++ b/src/main/runtime/orchestration/db/messages/message-insert.ts @@ -1,5 +1,4 @@ import type { MessageType, MessagePriority, MessageDeliveryContract, MessageRow } from '../../types' -import { LEGACY_RUN_ID } from '../contract-constants' import { generateId } from '../generated-id' import { exposeMessageTimestamps } from '../utc-timestamp' import type { OrchestrationDb } from '../orchestration-db' @@ -26,7 +25,10 @@ export type MessageInsert = { } export function insertMessage(this: OrchestrationDb, msg: MessageInsert): MessageRow { - const runId = msg.runId ?? LEGACY_RUN_ID + const runId = msg.runId + if (!runId) { + throw new Error('Run is required') + } const deliveryContract = msg.deliveryContract ?? 'current_delivery' this.requireRun(runId) const id = msg.id ?? generateId('msg') diff --git a/src/main/runtime/orchestration/db/schema/create-graph-tables-sql.ts b/src/main/runtime/orchestration/db/schema/create-graph-tables-sql.ts index 5aed50eb7f9..0897cb852de 100644 --- a/src/main/runtime/orchestration/db/schema/create-graph-tables-sql.ts +++ b/src/main/runtime/orchestration/db/schema/create-graph-tables-sql.ts @@ -38,6 +38,7 @@ CREATE TABLE IF NOT EXISTS federated_dispatches ( ); CREATE TABLE IF NOT EXISTS remote_dispatch_attachments ( + home_run_id TEXT NOT NULL, dispatch_id TEXT PRIMARY KEY, task_id TEXT NOT NULL, home_peer_fingerprint TEXT NOT NULL, diff --git a/src/main/runtime/orchestration/db/schema/federated-home-run-migration.test.ts b/src/main/runtime/orchestration/db/schema/federated-home-run-migration.test.ts new file mode 100644 index 00000000000..b970435223a --- /dev/null +++ b/src/main/runtime/orchestration/db/schema/federated-home-run-migration.test.ts @@ -0,0 +1,26 @@ +import { afterEach, describe, expect, it } from 'vitest' +import { OrchestrationDb } from '../orchestration-db' +import { migrateV40 } from './migrate-v40' +import { importFederatedControlMessage } from '../../federation-control-message' + +describe('federated home Run migration', () => { + const db = new OrchestrationDb(':memory:') + afterEach(() => db.close()) + + it('adds the home Run column and refuses mail for a development placeholder', () => { + db.db.exec('ALTER TABLE remote_dispatch_attachments DROP COLUMN home_run_id') + db.db.exec(`INSERT INTO remote_dispatch_attachments + (dispatch_id, task_id, home_peer_fingerprint, runtime_epoch) + VALUES ('ctx_old', 'task_old', 'home', 'epoch')`) + migrateV40.call(db, 39) + expect(db.getRemoteDispatchAttachment('ctx_old')?.home_run_id).toBe('') + expect(() => + importFederatedControlMessage(db, { + dispatchId: 'ctx_old', + messageId: 'message_old', + payload: JSON.stringify({ from: 'home', subject: 'Instruction', body: '', type: 'message' }) + }) + ).toThrow('Run not found:') + expect(db.getMessageById('message_old')).toBeUndefined() + }) +}) diff --git a/src/main/runtime/orchestration/db/schema/migrate-v40.ts b/src/main/runtime/orchestration/db/schema/migrate-v40.ts new file mode 100644 index 00000000000..50ef46f82cc --- /dev/null +++ b/src/main/runtime/orchestration/db/schema/migrate-v40.ts @@ -0,0 +1,11 @@ +import type { OrchestrationDb } from '../orchestration-db' + +export function migrateV40(this: OrchestrationDb, current: number): void { + if (current >= 40 || this.hasColumn('remote_dispatch_attachments', 'home_run_id')) { + return + } + // Federation is unreleased; any development-only rows fail Run validation until reattached. + this.db.exec( + "ALTER TABLE remote_dispatch_attachments ADD COLUMN home_run_id TEXT NOT NULL DEFAULT ''" + ) +} diff --git a/src/main/runtime/orchestration/db/schema/migrate.ts b/src/main/runtime/orchestration/db/schema/migrate.ts index b8da910722d..582dedf4752 100644 --- a/src/main/runtime/orchestration/db/schema/migrate.ts +++ b/src/main/runtime/orchestration/db/schema/migrate.ts @@ -10,6 +10,7 @@ import { migrateV36 } from './migrate-v36' import { migrateV37 } from './migrate-v37' import { migrateV38 } from './migrate-v38' import { migrateV39 } from './migrate-v39' +import { migrateV40 } from './migrate-v40' // Why: CREATE TABLE IF NOT EXISTS won't alter existing DBs; migrate in a txn that bumps user_version only on success (atomic all-or-nothing). export function migrate(this: OrchestrationDb): void { @@ -30,6 +31,7 @@ export function migrate(this: OrchestrationDb): void { migrateV37.call(this, current) migrateV38.call(this, current) migrateV39.call(this, current) + migrateV40.call(this, current) this.createMailboxDeliveryIndexesIfPossible() this.db.pragma(`user_version = ${SCHEMA_VERSION}`) this.db.exec('COMMIT') diff --git a/src/main/runtime/orchestration/db/tasks/task-store.ts b/src/main/runtime/orchestration/db/tasks/task-store.ts index 4ad3e8e3ffa..af43dc2be12 100644 --- a/src/main/runtime/orchestration/db/tasks/task-store.ts +++ b/src/main/runtime/orchestration/db/tasks/task-store.ts @@ -1,7 +1,6 @@ import type Database from '../../../../sqlite/sync-database' import type { TaskStatus, TaskRow } from '../../types' import { buildOrchestrationTaskDisplayMetadata } from '../../../../../shared/orchestration-task-display' -import { LEGACY_RUN_ID } from '../contract-constants' import { generateId } from '../generated-id' import type { TaskRuntimeLineageRow } from '../run-list-page' import type { OrchestrationDb } from '../orchestration-db' @@ -25,7 +24,10 @@ export function createTask( runId?: string } ): TaskRow { - const runId = task.runId ?? LEGACY_RUN_ID + const runId = task.runId + if (!runId) { + throw new Error('Run is required') + } this.requireRun(runId) if (task.parentId) { const parent = this.getTask(task.parentId) diff --git a/src/main/runtime/orchestration/db/writer-run-required.test.ts b/src/main/runtime/orchestration/db/writer-run-required.test.ts new file mode 100644 index 00000000000..21fcbeb28d6 --- /dev/null +++ b/src/main/runtime/orchestration/db/writer-run-required.test.ts @@ -0,0 +1,40 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { OrchestrationDb } from './orchestration-db' + +describe('writers require a Run', () => { + let db: OrchestrationDb + beforeEach(() => { + db = new OrchestrationDb(':memory:') + }) + afterEach(() => db.close()) + + it('rejects a message without a Run instead of using the legacy Run', () => { + expect(() => db.insertMessage({ from: 'sender', to: 'worker', subject: 'mail' })).toThrow( + 'Run is required' + ) + expect(db.db.prepare('SELECT id FROM messages').all()).toEqual([]) + }) + + it('rejects a Task without a Run instead of using the legacy Run', () => { + expect(() => db.createTask({ spec: 'work' })).toThrow('Run is required') + expect(db.listTasks()).toEqual([]) + }) + + it('rejects a decision gate whose Task has no Run', () => { + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) + vi.spyOn(db, 'getTask').mockReturnValue({ ...task, run_id: undefined } as never) + expect(() => db.createGate({ taskId: task.id, question: 'Proceed?' })).toThrow() + expect(db.listGates()).toEqual([]) + }) + + it('rejects a decision gate without a Task before writing', () => { + db.db.exec(` + CREATE TRIGGER reject_gate_insert BEFORE INSERT ON decision_gates + BEGIN SELECT RAISE(ABORT, 'gate insert reached'); END; + `) + expect(() => db.createGate({ taskId: 'missing', question: 'Proceed?' })).toThrow( + 'Task missing was not found while creating a decision gate.' + ) + expect(db.listGates()).toEqual([]) + }) +}) diff --git a/src/main/runtime/orchestration/dispatch-failure-idempotency.test.ts b/src/main/runtime/orchestration/dispatch-failure-idempotency.test.ts index c6f75723cf3..5704db1490e 100644 --- a/src/main/runtime/orchestration/dispatch-failure-idempotency.test.ts +++ b/src/main/runtime/orchestration/dispatch-failure-idempotency.test.ts @@ -6,7 +6,7 @@ import { createRootDispatch } from './db/root-dispatch-test-fixture' describe('dispatch failure idempotency', () => { it('counts an active dispatch failure only once', () => { const db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker') expect(db.failDispatch(dispatch.id, 'exit')?.failure_count).toBe(1) @@ -19,7 +19,7 @@ describe('dispatch failure idempotency', () => { it('does not overwrite a completed dispatch', () => { const db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker') db.completeDispatch(dispatch.id) @@ -33,7 +33,7 @@ describe('dispatch failure idempotency', () => { it('rolls back the dispatch when the task update fails', () => { const db = new OrchestrationDb(':memory:') const sqlite = (db as unknown as { db: Database.Database }).db - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker') sqlite.exec(` CREATE TRIGGER reject_task_failure_update diff --git a/src/main/runtime/orchestration/failed-start-terminal-adoption.test.ts b/src/main/runtime/orchestration/failed-start-terminal-adoption.test.ts index d38248f9cb8..b980a7f2a25 100644 --- a/src/main/runtime/orchestration/failed-start-terminal-adoption.test.ts +++ b/src/main/runtime/orchestration/failed-start-terminal-adoption.test.ts @@ -17,7 +17,7 @@ describe('a start that fails before authority still owns the terminal it created adoption?: Parameters[3] ): { db: OrchestrationDb; dispatchId: string } { const d = (db = new OrchestrationDb(':memory:')) - const task = d.createTask({ spec: 'residual terminal' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'residual terminal' }) const started = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -122,7 +122,7 @@ describe('a start that fails before authority still owns the terminal it created const first = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, - taskId: d.createTask({ spec: 'owner' }).id, + taskId: d.createTask({ runId: 'run_legacy_local', spec: 'owner' }).id, startOptions: {} }) d.prepareStartingWorkerAuthority({ @@ -138,7 +138,7 @@ describe('a start that fails before authority still owns the terminal it created const second = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, - taskId: d.createTask({ spec: 'claimant' }).id, + taskId: d.createTask({ runId: 'run_legacy_local', spec: 'claimant' }).id, startOptions: {} }) d.recordWorkerStage({ diff --git a/src/main/runtime/orchestration/federation-acknowledgment-integrity.test.ts b/src/main/runtime/orchestration/federation-acknowledgment-integrity.test.ts index fd8e32d1a32..e5c452f91a1 100644 --- a/src/main/runtime/orchestration/federation-acknowledgment-integrity.test.ts +++ b/src/main/runtime/orchestration/federation-acknowledgment-integrity.test.ts @@ -14,6 +14,7 @@ describe('federation acknowledgment integrity', () => { db = new OrchestrationDb(':memory:') const dispatchId = `ctx_protocol_${protocolVersion}` db.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId, taskId: `task_protocol_${protocolVersion}`, homePeerFingerprint: 'home_peer', diff --git a/src/main/runtime/orchestration/federation-control-message.ts b/src/main/runtime/orchestration/federation-control-message.ts index bcab04f99b8..2d86ef3c67b 100644 --- a/src/main/runtime/orchestration/federation-control-message.ts +++ b/src/main/runtime/orchestration/federation-control-message.ts @@ -58,11 +58,20 @@ export function importFederatedControlMessage( payload: string } ): { imported: boolean; type: MessageType } { + const attachment = db.getRemoteDispatchAttachment(params.dispatchId) + if (!attachment) { + throw new OrchestrationError( + 'dispatch_not_found', + `Remote Dispatch ${params.dispatchId} was not found.` + ) + } + db.requireRun(attachment.home_run_id) const message = parseFederatedControlMessage(params.payload) const recipient = `dispatch:${params.dispatchId}` const existing = db.getMessageById(params.messageId) if (existing) { if ( + existing.run_id !== attachment.home_run_id || existing.to_handle !== recipient || existing.from_handle !== message.from || existing.subject !== message.subject || @@ -81,6 +90,7 @@ export function importFederatedControlMessage( } db.insertMessage({ id: params.messageId, + runId: attachment.home_run_id, from: message.from, to: recipient, subject: message.subject, diff --git a/src/main/runtime/orchestration/lifecycle-caller-edges.test.ts b/src/main/runtime/orchestration/lifecycle-caller-edges.test.ts index 3bc2eee4ae9..7f445388a25 100644 --- a/src/main/runtime/orchestration/lifecycle-caller-edges.test.ts +++ b/src/main/runtime/orchestration/lifecycle-caller-edges.test.ts @@ -109,7 +109,10 @@ describe('lifecycle graph against its callers', () => { it('settles a stopping worker whose PTY exits during the stop', () => { const database = createDatabase() - const task = database.createTask({ spec: 'stopping exited worker' }) + const task = database.createTask({ + runId: 'run_legacy_local', + spec: 'stopping exited worker' + }) const dispatchId = startWorker(database, task.id, 'stopping_exited') expect(database.beginWorkerStop(dispatchId, 'runtime_test').disposition).toBe('stopping') @@ -127,9 +130,18 @@ describe('lifecycle graph against its callers', () => { it('still lets a coordinator reopen or overturn a settled Task', () => { const database = createDatabase() - const reopened = database.createTask({ spec: 'reopen me' }) - const overturned = database.createTask({ spec: 'overturn me' }) - const retried = database.createTask({ spec: 'retry me' }) + const reopened = database.createTask({ + runId: 'run_legacy_local', + spec: 'reopen me' + }) + const overturned = database.createTask({ + runId: 'run_legacy_local', + spec: 'overturn me' + }) + const retried = database.createTask({ + runId: 'run_legacy_local', + spec: 'retry me' + }) database.updateTaskStatus(reopened.id, 'completed', 'first result') database.updateTaskStatus(overturned.id, 'completed', 'wrong result') database.updateTaskStatus(retried.id, 'failed', 'boom') diff --git a/src/main/runtime/orchestration/lifecycle-reconciliation.test.ts b/src/main/runtime/orchestration/lifecycle-reconciliation.test.ts index 3f0f0a7664f..dedea449629 100644 --- a/src/main/runtime/orchestration/lifecycle-reconciliation.test.ts +++ b/src/main/runtime/orchestration/lifecycle-reconciliation.test.ts @@ -10,10 +10,11 @@ describe('lifecycle reconciliation', () => { it('rejects handle churn when neither side has stable pane identity', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_before_restart') const logs: string[] = [] const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_after_restart', to: 'term_coordinator', subject: 'Done', @@ -37,9 +38,10 @@ describe('lifecycle reconciliation', () => { it('completes worker_done from the dispatched pane after a handle remint', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_before_restart', `tab_w:${LEAF_A}`) const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_after_restart', to: 'term_coordinator', subject: 'Done', @@ -54,7 +56,7 @@ describe('lifecycle reconciliation', () => { it('completes an exact-authority worker_done after an uncertain worker start', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -82,6 +84,7 @@ describe('lifecycle reconciliation', () => { ).toEqual({ valid: true }) const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker', to: 'term_coordinator', subject: 'Done after reconnect', @@ -106,9 +109,10 @@ describe('lifecycle reconciliation', () => { it('fails both the dispatch and task from an authenticated failed worker report', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker', `tab_w:${LEAF_A}`) const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker', to: 'term_coordinator', subject: 'Failed: tests cannot start', @@ -139,7 +143,7 @@ describe('lifecycle reconciliation', () => { it('keeps worker report settlement nested in its caller transaction', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker') db.db.exec('BEGIN IMMEDIATE') @@ -160,19 +164,16 @@ describe('lifecycle reconciliation', () => { it('replays an identical terminal outcome without mutating settled state', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker') const makeMessage = () => db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker', to: 'term_coordinator', subject: 'Done', type: 'worker_done', - payload: JSON.stringify({ - taskId: task.id, - dispatchId: dispatch.id, - outcome: 'succeeded' - }) + payload: JSON.stringify({ taskId: task.id, dispatchId: dispatch.id, outcome: 'succeeded' }) }) expect(reconcileLifecycleMessage(db, makeMessage()).action).toBe('completed') @@ -199,6 +200,7 @@ describe('lifecycle reconciliation', () => { ])('rejects malformed worker reports with $code', ({ payload, code }) => { db = new OrchestrationDb(':memory:') const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker', to: 'term_coordinator', subject: 'Done', @@ -215,11 +217,12 @@ describe('lifecycle reconciliation', () => { it('completes worker_done from the same leaf after a pane break-out changed the tab half', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) // Dispatch recorded the post-break-out pane key; the worker shell still // holds the spawn-time key with the old tab id. const dispatch = createRootDispatch(db, task.id, 'term_before_restart', `tab_new:${LEAF_A}`) const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_after_restart', to: 'term_coordinator', subject: 'Done', @@ -234,9 +237,10 @@ describe('lifecycle reconciliation', () => { it('rejects mismatched opaque pane keys instead of treating them as legacy', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_owner', `tab_w:${LEAF_A}`) const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_reminted', to: 'term_coordinator', subject: 'Done', @@ -251,9 +255,10 @@ describe('lifecycle reconciliation', () => { it('rejects worker_done from a foreign pane that claims the assignee handle', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_owner', `tab_w1:${LEAF_A}`) const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_owner', to: 'term_coordinator', subject: 'Done', @@ -294,9 +299,10 @@ describe('lifecycle reconciliation', () => { it('does not let a caller-supplied rejection marker turn completion into success', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker', `tab_w:${LEAF_A}`) const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker', to: 'term_coordinator', subject: 'Done', @@ -323,9 +329,10 @@ describe('lifecycle reconciliation', () => { it('rejects a coordinator completion for a pane-bound dispatch', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker', `tab_w:${LEAF_A}`) const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_coordinator', to: 'term_coordinator', subject: 'Done', @@ -342,9 +349,13 @@ describe('lifecycle reconciliation', () => { it('uses exact handle equality only for a legacy dispatch without a pane key', () => { db = new OrchestrationDb(':memory:') - const acceptedTask = db.createTask({ spec: 'legacy work' }) + const acceptedTask = db.createTask({ + runId: 'run_legacy_local', + spec: 'legacy work' + }) const acceptedDispatch = createRootDispatch(db, acceptedTask.id, 'term_legacy') const accepted = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy', to: 'term_coordinator', subject: 'Done', @@ -357,9 +368,13 @@ describe('lifecycle reconciliation', () => { }) expect(reconcileLifecycleMessage(db, accepted).action).toBe('completed') - const rejectedTask = db.createTask({ spec: 'other legacy work' }) + const rejectedTask = db.createTask({ + runId: 'run_legacy_local', + spec: 'other legacy work' + }) const rejectedDispatch = createRootDispatch(db, rejectedTask.id, 'term_other_legacy') const rejected = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_foreign', to: 'term_coordinator', subject: 'Done', @@ -379,8 +394,12 @@ describe('lifecycle reconciliation', () => { it('does not release a dependent when a foreign completion wins the arrival race', () => { db = new OrchestrationDb(':memory:') - const parent = db.createTask({ spec: 'parent' }) - const child = db.createTask({ spec: 'child', deps: [parent.id] }) + const parent = db.createTask({ runId: 'run_legacy_local', spec: 'parent' }) + const child = db.createTask({ + runId: 'run_legacy_local', + spec: 'child', + deps: [parent.id] + }) const dispatch = createRootDispatch(db, parent.id, 'term_worker', `tab_w:${LEAF_A}`) const payload = JSON.stringify({ taskId: parent.id, @@ -389,6 +408,7 @@ describe('lifecycle reconciliation', () => { }) const foreign = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_coordinator', to: 'term_coordinator', subject: 'Done', @@ -403,6 +423,7 @@ describe('lifecycle reconciliation', () => { expect(db.getTask(child.id)?.status).toBe('pending') const owner = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker_reminted', to: 'term_coordinator', subject: 'Done', @@ -416,7 +437,7 @@ describe('lifecycle reconciliation', () => { it('does not let a foreign replay overwrite an authorized completion', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker', `tab_w:${LEAF_A}`) const payload = JSON.stringify({ taskId: task.id, @@ -424,6 +445,7 @@ describe('lifecycle reconciliation', () => { outcome: 'succeeded' }) const owner = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker', to: 'term_coordinator', subject: 'Done', @@ -435,6 +457,7 @@ describe('lifecycle reconciliation', () => { const result = db.getTask(task.id)?.result const replay = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_foreign', to: 'term_coordinator', subject: 'Forged replay', @@ -451,10 +474,11 @@ describe('lifecycle reconciliation', () => { it('surfaces worker_done sent from a different pane as rejected', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_owner', `tab_w1:${LEAF_A}`) const logs: string[] = [] const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_other_worker', to: 'term_coordinator', subject: 'Done', @@ -474,9 +498,10 @@ describe('lifecycle reconciliation', () => { it('surfaces a heartbeat sent from a different pane without recording liveness', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_owner', `tab_w1:${LEAF_A}`) const heartbeat = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_other_worker', to: 'term_coordinator', subject: 'alive', @@ -508,9 +533,10 @@ describe('lifecycle reconciliation', () => { it('surfaces a foreign heartbeat that claims the assignee handle', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_owner', `tab_w1:${LEAF_A}`) const heartbeat = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_owner', to: 'term_coordinator', subject: 'alive', @@ -528,9 +554,10 @@ describe('lifecycle reconciliation', () => { it('records a heartbeat whose pane key drifted only in the tab half', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_owner', `tab_new:${LEAF_A}`) const heartbeat = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_owner', to: 'term_coordinator', subject: 'alive', @@ -548,12 +575,16 @@ describe('lifecycle reconciliation', () => { it('suppresses same-dispatch heartbeats once worker_done is reconciled', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'work' }) const dispatch = createRootDispatch(db, task.id, 'term_worker') - const otherTask = db.createTask({ spec: 'other work' }) + const otherTask = db.createTask({ + runId: 'run_legacy_local', + spec: 'other work' + }) const otherDispatch = createRootDispatch(db, otherTask.id, 'term_other') const insertHeartbeat = (dispatchId: string, from: string) => db.insertMessage({ + runId: 'run_legacy_local', from, to: 'term_coordinator', subject: 'alive', @@ -565,6 +596,7 @@ describe('lifecycle reconciliation', () => { reconcileLifecycleMessage(db, staleHeartbeat) reconcileLifecycleMessage(db, otherHeartbeat) const done = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker', to: 'term_coordinator', subject: 'Done', diff --git a/src/main/runtime/orchestration/lightweight-run-worker-exit-escalation.test.ts b/src/main/runtime/orchestration/lightweight-run-worker-exit-escalation.test.ts index 2b8d9c90bc2..d37e379e1c5 100644 --- a/src/main/runtime/orchestration/lightweight-run-worker-exit-escalation.test.ts +++ b/src/main/runtime/orchestration/lightweight-run-worker-exit-escalation.test.ts @@ -412,7 +412,7 @@ describe('STA-4604 worker PTY exit escalation reaches the coordinator', () => { } }) - it('falls back to the legacy gate when the dispatch owning Run row is gone', async () => { + it('preserves the dispatch Run when legacy coordinator routing is used', async () => { const { runtime, workerHandle, coordinatorHandle } = makeRuntimeWithTwoPanes() const insertMessage = vi.fn((message: { to: string }) => ({ ...message, @@ -435,8 +435,7 @@ describe('STA-4604 worker PTY exit escalation reaches the coordinator', () => { expect(insertMessage).toHaveBeenCalledWith( expect.objectContaining({ to: coordinatorHandle, type: 'escalation' }) ) - // An orphaned dispatch has no Run mailbox to address, so it must not invent one. - expect(insertMessage.mock.calls[0]?.[0]).not.toHaveProperty('runId') + expect(insertMessage.mock.calls[0]?.[0]).toHaveProperty('runId', 'run-that-no-longer-exists') }) it('still reaches the Run mailbox when the Run has no bound coordinator', async () => { diff --git a/src/main/runtime/orchestration/mailbox-pointer-eligibility.test.ts b/src/main/runtime/orchestration/mailbox-pointer-eligibility.test.ts index 87b090e4e48..2276665fc1c 100644 --- a/src/main/runtime/orchestration/mailbox-pointer-eligibility.test.ts +++ b/src/main/runtime/orchestration/mailbox-pointer-eligibility.test.ts @@ -15,9 +15,9 @@ const MAILBOX = 'dispatch:d1' function seeded(): OrchestrationDb { const db = new OrchestrationDb(':memory:') db.insertMessages([ - { from: 'coordinator', to: MAILBOX, subject: 'a', type: 'status' }, - { from: 'coordinator', to: MAILBOX, subject: 'b', type: 'question' }, - { from: 'coordinator', to: MAILBOX, subject: 'c', type: 'status' } + { runId: 'run_legacy_local', from: 'coordinator', to: MAILBOX, subject: 'a', type: 'status' }, + { runId: 'run_legacy_local', from: 'coordinator', to: MAILBOX, subject: 'b', type: 'question' }, + { runId: 'run_legacy_local', from: 'coordinator', to: MAILBOX, subject: 'c', type: 'status' } ]) return db } diff --git a/src/main/runtime/orchestration/mailbox-pointer-stage.test.ts b/src/main/runtime/orchestration/mailbox-pointer-stage.test.ts index 9573f02fc0c..d76a480ecfd 100644 --- a/src/main/runtime/orchestration/mailbox-pointer-stage.test.ts +++ b/src/main/runtime/orchestration/mailbox-pointer-stage.test.ts @@ -59,7 +59,12 @@ function stageArgs(db: OrchestrationDb, state: OrchestrationMailboxPointerState) describe('mailbox pointer staging watermark', () => { it('leaves no watermark when the reservation claim is lost', () => { const db = new OrchestrationDb(':memory:') - const message = db.insertMessage({ from: 'a', to: 'run:run-1', subject: 's' }) + const message = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 's' + }) // A concurrent flight already owns the reservation, so this claim cannot succeed. expect( db.stageMailboxPointerEnter([message.id], { ptyId: 'other-pty', processIncarnation: 'inc-x' }) @@ -79,7 +84,12 @@ describe('mailbox pointer staging watermark', () => { it('leaves no watermark when the reservation write throws', () => { const db = new OrchestrationDb(':memory:') - const message = db.insertMessage({ from: 'a', to: 'run:run-1', subject: 's' }) + const message = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 's' + }) const throwing = new Proxy(db, { get(target, prop, receiver) { if (prop === 'markMailboxPointerWriteAttempted') { @@ -107,7 +117,12 @@ describe('mailbox pointer staging watermark', () => { it('keeps the watermark for the flight that owns the reservation', () => { const db = new OrchestrationDb(':memory:') - const message = db.insertMessage({ from: 'a', to: 'run:run-1', subject: 's' }) + const message = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 's' + }) const state = new OrchestrationMailboxPointerState() const args = stageArgs(db, state) stageOrchestrationMailboxPointer({ @@ -122,7 +137,12 @@ describe('mailbox pointer staging watermark', () => { it('drains a delivery parked behind the watermark when the write is refused', () => { const db = new OrchestrationDb(':memory:') - const message = db.insertMessage({ from: 'a', to: 'run:run-1', subject: 's' }) + const message = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 's' + }) const state = new OrchestrationMailboxPointerState() const args = stageArgs(db, state) const redrive = vi.fn() @@ -148,7 +168,7 @@ describe('mailbox pointer staging watermark', () => { it('still points new mail after a delivery lost its reservation claim', async () => { const db = new OrchestrationDb(':memory:') - db.insertMessage({ from: 'a', to: 'run:run-1', subject: 'first' }) + db.insertMessage({ runId: 'run_legacy_local', from: 'a', to: 'run:run-1', subject: 'first' }) let stealNextClaim = true const contended = new Proxy(db, { get(target, prop, receiver) { @@ -172,7 +192,7 @@ describe('mailbox pointer staging watermark', () => { expect(writePty).not.toHaveBeenCalled() // Newer mail must still reach the agent; a leaked watermark used to park it forever. - db.insertMessage({ from: 'a', to: 'run:run-1', subject: 'second' }) + db.insertMessage({ runId: 'run_legacy_local', from: 'a', to: 'run:run-1', subject: 'second' }) delivery.deliver(LEAF, { mailboxHandle: 'run:run-1', skipAbsenceProbe: true }) await new Promise((resolve) => setImmediate(resolve)) diff --git a/src/main/runtime/orchestration/mailbox-pointer-submit.test.ts b/src/main/runtime/orchestration/mailbox-pointer-submit.test.ts index 00126bc237b..02d556204df 100644 --- a/src/main/runtime/orchestration/mailbox-pointer-submit.test.ts +++ b/src/main/runtime/orchestration/mailbox-pointer-submit.test.ts @@ -14,7 +14,12 @@ import type { WriteSettlement } from '../../../shared/pty-write-settlement' describe('orchestration mailbox pointer submit', () => { it('does not settle a replacement reservation after an old Enter write resolves', async () => { const db = new OrchestrationDb(':memory:') - const message = db.insertMessage({ from: 'a', to: 'run:run-1', subject: 'staged' }) + const message = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 'staged' + }) const ptyId = 'pty-reused' const oldReservation = { ptyId, processIncarnation: 'inc-old' } const replacementReservation = { ptyId, processIncarnation: 'inc-new' } @@ -86,8 +91,18 @@ describe('orchestration mailbox pointer submit', () => { it('does not overwrite a message already reserved by another pointer flight', () => { const db = new OrchestrationDb(':memory:') - const first = db.insertMessage({ from: 'a', to: 'run:run-1', subject: 'first' }) - const second = db.insertMessage({ from: 'a', to: 'run:run-1', subject: 'second' }) + const first = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 'first' + }) + const second = db.insertMessage({ + runId: 'run_legacy_local', + from: 'a', + to: 'run:run-1', + subject: 'second' + }) const original = { ptyId: 'pty-a', processIncarnation: 'inc-a' } const replacement = { ptyId: 'pty-b', processIncarnation: 'inc-b' } diff --git a/src/main/runtime/orchestration/message-batch-atomicity.test.ts b/src/main/runtime/orchestration/message-batch-atomicity.test.ts index f2e43ed31e4..fda83fad9a9 100644 --- a/src/main/runtime/orchestration/message-batch-atomicity.test.ts +++ b/src/main/runtime/orchestration/message-batch-atomicity.test.ts @@ -108,8 +108,20 @@ describe('message batch atomicity', () => { expect(() => db?.insertMessages([ - { id: 'inner_first', from: 'sender', to: 'recipient', subject: 'first' }, - { id: 'inner_second', from: 'sender', to: 'recipient', subject: 'second' } + { + runId: 'run_legacy_local', + id: 'inner_first', + from: 'sender', + to: 'recipient', + subject: 'first' + }, + { + runId: 'run_legacy_local', + id: 'inner_second', + from: 'sender', + to: 'recipient', + subject: 'second' + } ]) ).toThrow('blocked') sqlite.exec('COMMIT') @@ -133,6 +145,7 @@ describe('message batch atomicity', () => { expect(() => db?.commitWorkerDoneMessageMutation(() => { db?.insertMessage({ + runId: 'run_legacy_local', id: 'inner', from: 'worker', to: 'coordinator', diff --git a/src/main/runtime/orchestration/nested-worker-depth-migration.test.ts b/src/main/runtime/orchestration/nested-worker-depth-migration.test.ts index fa955b7cf08..9d05c0dac07 100644 --- a/src/main/runtime/orchestration/nested-worker-depth-migration.test.ts +++ b/src/main/runtime/orchestration/nested-worker-depth-migration.test.ts @@ -34,6 +34,7 @@ describe('nested worker depth migration (v30)', () => { const oldDb = new Database(dbPath) oldDb.exec('ALTER TABLE dispatch_contexts DROP COLUMN depth') oldDb.exec('ALTER TABLE remote_dispatch_attachments DROP COLUMN depth') + oldDb.exec('ALTER TABLE remote_dispatch_attachments DROP COLUMN home_run_id') oldDb.pragma('user_version = 29') oldDb .prepare( @@ -78,7 +79,7 @@ describe('nested worker depth migration (v30)', () => { ) .run() - const task = db.createTask({ spec: 'post-upgrade nesting attempt' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'post-upgrade nesting attempt' }) expect(() => db!.createDispatchContext({ taskId: task.id, diff --git a/src/main/runtime/orchestration/orchestration-adopted-run-binding.test.ts b/src/main/runtime/orchestration/orchestration-adopted-run-binding.test.ts index 800a7511451..d667267e0a6 100644 --- a/src/main/runtime/orchestration/orchestration-adopted-run-binding.test.ts +++ b/src/main/runtime/orchestration/orchestration-adopted-run-binding.test.ts @@ -47,11 +47,13 @@ function createAdoptedFixture(options: { settleWork: boolean }): AdoptedFixture const before = new OrchestrationDb(dbPath) const task = before.createTask({ + runId: 'run_legacy_local', spec: 'legacy assignment', createdByTerminalHandle: LEGACY_COORDINATOR_HANDLE }) const dispatch = createRootDispatch(before, task.id, LEGACY_WORKER_HANDLE, LEGACY_WORKER_PANE) const recovery = before.insertMessage({ + runId: 'run_legacy_local', from: LEGACY_WORKER_HANDLE, to: LEGACY_COORDINATOR_HANDLE, subject: 'recovered worker outcome', diff --git a/src/main/runtime/orchestration/orchestration-all-start-versions-migration.test.ts b/src/main/runtime/orchestration/orchestration-all-start-versions-migration.test.ts index b4c9281d89b..b62677e465b 100644 --- a/src/main/runtime/orchestration/orchestration-all-start-versions-migration.test.ts +++ b/src/main/runtime/orchestration/orchestration-all-start-versions-migration.test.ts @@ -36,7 +36,12 @@ describe('orchestration migration from every prior version stamp', () => { expect(reopened.db.pragma('user_version', { simple: true }), `reopen v${version}`).toBe( SCHEMA_VERSION ) - expect(() => reopened.createTask({ spec: `migration v${version}` })).not.toThrow() + expect(() => + reopened.createTask({ + runId: 'run_legacy_local', + spec: `migration v${version}` + }) + ).not.toThrow() reopened.close() } }) diff --git a/src/main/runtime/orchestration/orchestration-db-retention-pagination.test.ts b/src/main/runtime/orchestration/orchestration-db-retention-pagination.test.ts index 38eeca64337..c980b8fe02a 100644 --- a/src/main/runtime/orchestration/orchestration-db-retention-pagination.test.ts +++ b/src/main/runtime/orchestration/orchestration-db-retention-pagination.test.ts @@ -103,6 +103,7 @@ describe('OrchestrationDb bounded mutation receipts', () => { insertMutationReceipts(db, MUTATION_RECEIPT_MAX_ROWS, 'completed') db.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId: 'ctx_remote_pruned', taskId: 'task_remote_pruned', homePeerFingerprint: 'caller', @@ -131,6 +132,7 @@ describe('OrchestrationDb bounded mutation receipts', () => { expect(() => db!.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId: 'ctx_remote_overflow', taskId: 'task_remote_overflow', homePeerFingerprint: 'caller', @@ -151,7 +153,7 @@ describe('OrchestrationDb bounded mutation receipts', () => { it('guards atomic worker acceptance without changing task state', () => { db = new OrchestrationDb(':memory:') - const task = db.createTask({ spec: 'capacity check' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'capacity check' }) insertMutationReceipts(db, MUTATION_RECEIPT_MAX_ROWS, 'pending') expect(() => @@ -226,7 +228,10 @@ describe('OrchestrationDb dispatch assignee index migration', () => { tempDir = mkdtempSync(join(tmpdir(), 'orca-dispatch-index-migration-')) const dbPath = join(tempDir, 'orchestration.db') db = new OrchestrationDb(dbPath) - const task = db.createTask({ spec: 'indexed lookup' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'indexed lookup' + }) const dispatch = createRootDispatch(db, task.id, 'term_worker') db.close() db = undefined @@ -245,7 +250,9 @@ describe('OrchestrationDb dispatch assignee index migration', () => { db = new OrchestrationDb(dbPath) const sqlite = sqliteFor(db) expect(sqlite.pragma('user_version', { simple: true })).toBe(SCHEMA_VERSION) - expect(db.getDispatchContextById(dispatch.id)).toMatchObject({ assignee_handle: 'term_worker' }) + expect(db.getDispatchContextById(dispatch.id)).toMatchObject({ + assignee_handle: 'term_worker' + }) expect(db.getTask(task.id)).toMatchObject({ created_by_pane_key: null, created_by_process_incarnation: null, diff --git a/src/main/runtime/orchestration/orchestration-federated-legacy-probe.test.ts b/src/main/runtime/orchestration/orchestration-federated-legacy-probe.test.ts new file mode 100644 index 00000000000..ad08a7383f0 --- /dev/null +++ b/src/main/runtime/orchestration/orchestration-federated-legacy-probe.test.ts @@ -0,0 +1,97 @@ +import { mkdtempSync, rmSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { LEGACY_RUN_ID, OrchestrationDb } from './db' +import { SCHEMA_VERSION } from './db/contract-constants' +import { resolveOrchestrationMigrationStartVersion } from './orchestration-schema-version-skew' + +describe('federated mailbox legacy-adoption probe', () => { + let db: OrchestrationDb | undefined + let directory: string | undefined + + afterEach(() => { + db?.close() + if (directory) { + rmSync(directory, { recursive: true, force: true }) + } + }) + + function seedMailbox(handle: string, kind: 'message' | 'delivery'): string { + directory = mkdtempSync(join(tmpdir(), 'orca-federated-legacy-probe-')) + const path = join(directory, 'orchestration.db') + db = new OrchestrationDb(path) + db.db.exec(` + INSERT INTO remote_dispatch_attachments ( + dispatch_id, task_id, home_peer_fingerprint, home_run_id, runtime_epoch, state + ) VALUES ('ctx_remote', 'task_remote', 'peer_home', 'run_home', 'epoch', 'ready'); + `) + if (kind === 'message') { + db.db + .prepare( + `INSERT INTO messages ( + id, run_id, delivery_contract, from_handle, to_handle, subject, type + ) VALUES ('msg_probe', ?, 'current_delivery', 'term_home', ?, 'continue', 'dispatch')` + ) + .run(LEGACY_RUN_ID, handle) + } else { + db.db + .prepare( + `INSERT INTO deliveries (id, run_id, mailbox_handle, consumer_generation, message_ids) + VALUES ('delivery_probe', ?, ?, 0, '[]')` + ) + .run(LEGACY_RUN_ID, handle) + } + return path + } + + it.each(['message', 'delivery'] as const)( + 'does not replay adoption for a misfiled federated %s', + (kind) => { + const path = seedMailbox('dispatch:ctx_remote', kind) + expect( + resolveOrchestrationMigrationStartVersion(db!.db, SCHEMA_VERSION, SCHEMA_VERSION) + ).toBe(SCHEMA_VERSION) + db!.close() + db = new OrchestrationDb(path) + expect(db.getLegacyAdoption()).toBeUndefined() + if (kind === 'message') { + expect(db.getMessageById('msg_probe')).toMatchObject({ + run_id: LEGACY_RUN_ID, + delivery_contract: 'current_delivery' + }) + } else { + expect( + db.db.prepare("SELECT status FROM deliveries WHERE id = 'delivery_probe'").get() + ).toEqual({ + status: 'outstanding' + }) + } + } + ) + + it.each(['message', 'delivery'] as const)( + 'still replays adoption for a genuine legacy %s', + (kind) => { + const path = seedMailbox('term_legacy_coordinator', kind) + expect( + resolveOrchestrationMigrationStartVersion(db!.db, SCHEMA_VERSION, SCHEMA_VERSION) + ).toBe(6) + db!.close() + db = new OrchestrationDb(path) + expect(db.getLegacyAdoption()).toBeDefined() + if (kind === 'message') { + expect(db.getMessageById('msg_probe')).toMatchObject({ + run_id: db.getLegacyAdoption()!.adopted_run_id, + delivery_contract: 'legacy_direct' + }) + } else { + expect( + db.db.prepare("SELECT status FROM deliveries WHERE id = 'delivery_probe'").get() + ).toEqual({ + status: 'fenced' + }) + } + } + ) +}) diff --git a/src/main/runtime/orchestration/orchestration-legacy-storage-test-fixture.ts b/src/main/runtime/orchestration/orchestration-legacy-storage-test-fixture.ts index 4cdc8f5ee91..886f2383db5 100644 --- a/src/main/runtime/orchestration/orchestration-legacy-storage-test-fixture.ts +++ b/src/main/runtime/orchestration/orchestration-legacy-storage-test-fixture.ts @@ -54,6 +54,7 @@ export function createLegacyStorageCutoverFixture(): { }) const legacyTask = first.createTask({ + runId: 'run_legacy_local', spec: 'legacy', createdByTerminalHandle: 'term_legacy_coord' }) @@ -76,16 +77,19 @@ export function createLegacyStorageCutoverFixture(): { ) const legacyMessages = [ first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_coord', to: 'term_legacy_worker', subject: 'read worker mail' }), first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_worker', to: 'term_legacy_coord', subject: 'read coordinator mail' }), first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_coord', to: 'term_legacy_worker', subject: 'second worker page' @@ -99,6 +103,7 @@ export function createLegacyStorageCutoverFixture(): { question: 'Retained question?' }) const rejection = first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_worker', to: 'term_legacy_coord', subject: 'Rejected heartbeat', @@ -106,6 +111,7 @@ export function createLegacyStorageCutoverFixture(): { payload: JSON.stringify({ _orcaLifecycleRejection: { code: 'migration', reason: 'cutover' } }) }) const lookalike = first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_worker', to: 'term_legacy_coord', subject: 'Ordinary legacy mail', @@ -115,36 +121,42 @@ export function createLegacyStorageCutoverFixture(): { }) const malformedRejections = [ first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_worker', to: 'term_legacy_coord', subject: 'Invalid JSON marker', payload: '{"_orcaLifecycleRejection":' }), first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_worker', to: 'term_legacy_coord', subject: 'Array marker', payload: JSON.stringify({ _orcaLifecycleRejection: [] }) }), first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_worker', to: 'term_legacy_coord', subject: 'String marker', payload: JSON.stringify({ _orcaLifecycleRejection: 'migration' }) }), first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_worker', to: 'term_legacy_coord', subject: 'Incomplete marker', payload: JSON.stringify({ _orcaLifecycleRejection: { code: 'migration' } }) }), first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_worker', to: 'term_legacy_coord', subject: 'Non-string marker fields', payload: JSON.stringify({ _orcaLifecycleRejection: { code: 19, reason: false } }) }), first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_worker', to: 'term_legacy_coord', subject: 'Array root', @@ -153,6 +165,7 @@ export function createLegacyStorageCutoverFixture(): { ]) }), first.insertMessage({ + runId: 'run_legacy_local', from: 'term_legacy_worker', to: 'term_legacy_coord', subject: 'String root', diff --git a/src/main/runtime/orchestration/orchestration-mutation-question-db.test.ts b/src/main/runtime/orchestration/orchestration-mutation-question-db.test.ts index 5a26448bd98..c4911b7d676 100644 --- a/src/main/runtime/orchestration/orchestration-mutation-question-db.test.ts +++ b/src/main/runtime/orchestration/orchestration-mutation-question-db.test.ts @@ -77,6 +77,7 @@ describe('OrchestrationDb mutation and question state', () => { it('accepts a question message in the fresh canonical schema', () => { const d = createDb() const message = d.insertMessage({ + runId: 'run_legacy_local', from: 'worker', to: 'run:run_1', subject: 'Need input', diff --git a/src/main/runtime/orchestration/orchestration-schema-version-skew.ts b/src/main/runtime/orchestration/orchestration-schema-version-skew.ts index a2767e1e5a7..85e0a78b3ae 100644 --- a/src/main/runtime/orchestration/orchestration-schema-version-skew.ts +++ b/src/main/runtime/orchestration/orchestration-schema-version-skew.ts @@ -42,7 +42,8 @@ const VERSIONED_POST_V6_COLUMNS = [ { version: 36, table: 'dispatch_contexts', column: 'consumer_generation' }, { version: 36, table: 'remote_dispatch_attachments', column: 'consumer_generation' }, { version: 37, table: 'dispatch_contexts', column: 'creator_handle' }, - { version: 37, table: 'dispatch_contexts', column: 'creator_pane_key' } + { version: 37, table: 'dispatch_contexts', column: 'creator_pane_key' }, + { version: 40, table: 'remote_dispatch_attachments', column: 'home_run_id' } ] as const // Why: v34 shipped without these two, so a v34 stamp proves nothing about them; v35 repairs both @@ -122,15 +123,22 @@ function messagesAllowQuestions(db: Database.Database): boolean { function hasConsistentLegacyAdoption(db: Database.Database): boolean { const sourceRunId = 'run_legacy_local' + // Misfiled federated mail is not evidence of a pre-Runs database. + const notFederatedMailbox = (handle: string): string => + `NOT EXISTS (SELECT 1 FROM remote_dispatch_attachments AS attachment + WHERE 'dispatch:' || attachment.dispatch_id = ${handle})` + const deliveryFilter = hasOrchestrationColumn(db, 'deliveries', 'mailbox_handle') + ? ` AND ${notFederatedMailbox('mailbox_handle')}` + : '' const sourceGraph = db .prepare( `SELECT 1 WHERE EXISTS(SELECT 1 FROM tasks WHERE run_id = ?) OR EXISTS(SELECT 1 FROM dispatch_contexts WHERE run_id = ?) OR EXISTS(SELECT 1 FROM decision_gates WHERE run_id = ?) - OR EXISTS(SELECT 1 FROM messages WHERE run_id = ?) + OR EXISTS(SELECT 1 FROM messages WHERE run_id = ? AND ${notFederatedMailbox('to_handle')}) OR EXISTS(SELECT 1 FROM question_threads WHERE run_id = ?) - OR EXISTS(SELECT 1 FROM deliveries WHERE run_id = ?)` + OR EXISTS(SELECT 1 FROM deliveries WHERE run_id = ?${deliveryFilter})` ) .get(sourceRunId, sourceRunId, sourceRunId, sourceRunId, sourceRunId, sourceRunId) const adoption = db diff --git a/src/main/runtime/orchestration/orchestration-settled-worker-resume-fence-db.test.ts b/src/main/runtime/orchestration/orchestration-settled-worker-resume-fence-db.test.ts index ee52bc026d0..5cde241093d 100644 --- a/src/main/runtime/orchestration/orchestration-settled-worker-resume-fence-db.test.ts +++ b/src/main/runtime/orchestration/orchestration-settled-worker-resume-fence-db.test.ts @@ -13,7 +13,7 @@ describe('settled worker terminal resume fence rows', () => { function createReadyWorker(): { db: OrchestrationDb; taskId: string; dispatchId: string } { const d = new OrchestrationDb(':memory:') db = d - const task = d.createTask({ spec: 'settled worker' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'settled worker' }) const started = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/orchestration/orchestration-version-skew-migration.test.ts b/src/main/runtime/orchestration/orchestration-version-skew-migration.test.ts index 12ccf7303ca..f8fa7a5df48 100644 --- a/src/main/runtime/orchestration/orchestration-version-skew-migration.test.ts +++ b/src/main/runtime/orchestration/orchestration-version-skew-migration.test.ts @@ -389,7 +389,10 @@ describe('OrchestrationDb version-skew migration', () => { tempDir = mkdtempSync(join(tmpdir(), 'orca-db-version-skew-v30-reset-')) const dbPath = join(tempDir, 'orchestration.db') db = new OrchestrationDb(dbPath) - const task = db.createTask({ spec: 'reset by an older writer' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'reset by an older writer' + }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/orchestration/orchestration-worker-dispatch-db.test.ts b/src/main/runtime/orchestration/orchestration-worker-dispatch-db.test.ts index 16a118008de..d6e6038cd65 100644 --- a/src/main/runtime/orchestration/orchestration-worker-dispatch-db.test.ts +++ b/src/main/runtime/orchestration/orchestration-worker-dispatch-db.test.ts @@ -15,7 +15,7 @@ describe('OrchestrationDb worker Dispatch state', () => { it('creates and activates a composed worker Dispatch transactionally', () => { const d = createDb() - const task = d.createTask({ spec: 'worker' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'worker' }) const started = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -82,7 +82,7 @@ describe('OrchestrationDb worker Dispatch state', () => { it('retains an active supervised worker terminal', () => { const d = createDb() - const task = d.createTask({ spec: 'retain active worker' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'retain active worker' }) const started = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -114,7 +114,7 @@ describe('OrchestrationDb worker Dispatch state', () => { it('requeues an active Task before settling a worker whose terminal is missing', () => { const d = createDb() - const task = d.createTask({ spec: 'recover missing worker' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'recover missing worker' }) const started = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -153,7 +153,7 @@ describe('OrchestrationDb worker Dispatch state', () => { it('commits worker-start mutation acceptance with the starting Dispatch', () => { const d = createDb() - const task = d.createTask({ spec: 'atomic acceptance' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'atomic acceptance' }) const mutationReceipt = { callerFingerprint: 'caller_fingerprint', requestId: 'worker_start_request', @@ -207,7 +207,7 @@ describe('OrchestrationDb worker Dispatch state', () => { it('fails a composed start without losing residual resource receipts', () => { const d = createDb() - const task = d.createTask({ spec: 'worker' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'worker' }) const started = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -232,7 +232,7 @@ describe('OrchestrationDb worker Dispatch state', () => { it('allows retry only from the Task current terminal Dispatch', () => { const d = createDb() - const task = d.createTask({ spec: 'retry current' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'retry current' }) const first = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -272,7 +272,7 @@ describe('OrchestrationDb worker Dispatch state', () => { it('treats abandon of a superseded Dispatch as a no-op', () => { const d = createDb() - const task = d.createTask({ spec: 'stale abandon' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'stale abandon' }) const first = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -317,7 +317,7 @@ describe('OrchestrationDb worker Dispatch state', () => { it('lets the stop fence win before a late worker completion', () => { const d = createDb() - const task = d.createTask({ spec: 'race' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'race' }) const started = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -350,7 +350,7 @@ describe('OrchestrationDb worker Dispatch state', () => { it('allows explicit stop recovery from uncertain local and remote starts', () => { const d = createDb() - const task = d.createTask({ spec: 'uncertain local start' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'uncertain local start' }) const started = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, @@ -365,6 +365,7 @@ describe('OrchestrationDb worker Dispatch state', () => { }) d.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId: 'ctx_remote_unknown', taskId: 'task_remote_unknown', homePeerFingerprint: 'home_peer', @@ -398,6 +399,7 @@ describe('OrchestrationDb worker Dispatch state', () => { const paneKey = 'tab_remote:11111111-1111-4111-8111-111111111111' const attach = (dispatchId: string): void => { d.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId, taskId: `task_${dispatchId}`, homePeerFingerprint: 'home_peer', @@ -452,6 +454,7 @@ describe('OrchestrationDb worker Dispatch state', () => { const leafId = '11111111-1111-4111-8111-111111111111' const attach = (dispatchId: string, paneKey: string): void => { d.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId, taskId: `task_${dispatchId}`, homePeerFingerprint: 'home_peer', @@ -499,7 +502,7 @@ describe('OrchestrationDb worker Dispatch state', () => { it('returns already-settled when completion wins before stop', () => { const d = createDb() - const task = d.createTask({ spec: 'race' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'race' }) const started = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/orchestration/r1-identity-migration.test.ts b/src/main/runtime/orchestration/r1-identity-migration.test.ts index bb263d0b9ce..673a72fd844 100644 --- a/src/main/runtime/orchestration/r1-identity-migration.test.ts +++ b/src/main/runtime/orchestration/r1-identity-migration.test.ts @@ -27,7 +27,7 @@ describe('R1 identity migration', () => { tempDir = mkdtempSync(join(tmpdir(), 'orca-r1-identity-')) const dbPath = join(tempDir, 'orchestration.db') db = new OrchestrationDb(dbPath) - const task = db.createTask({ spec: 'legacy supervised worker' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'legacy supervised worker' }) const started = db.createStartingWorkerDispatch({ taskId: task.id, startOptions: { worktree: 'folder:/workspace' }, diff --git a/src/main/runtime/orchestration/types.ts b/src/main/runtime/orchestration/types.ts index 00005443006..85d5dcfc159 100644 --- a/src/main/runtime/orchestration/types.ts +++ b/src/main/runtime/orchestration/types.ts @@ -190,6 +190,7 @@ export type FederatedDispatchRow = { } export type RemoteDispatchAttachmentRow = { + home_run_id: string dispatch_id: string task_id: string home_peer_fingerprint: string diff --git a/src/main/runtime/orchestration/worker-start-unobserved-prompt-settlement.test.ts b/src/main/runtime/orchestration/worker-start-unobserved-prompt-settlement.test.ts index 382ec304bb6..1d123f51b38 100644 --- a/src/main/runtime/orchestration/worker-start-unobserved-prompt-settlement.test.ts +++ b/src/main/runtime/orchestration/worker-start-unobserved-prompt-settlement.test.ts @@ -6,7 +6,7 @@ const INCARNATION = 'runtime_test:term_worker:1' let db: OrchestrationDb function startWorker(spec: string): { taskId: string; dispatchId: string; capability: string } { - const task = db.createTask({ spec }) + const task = db.createTask({ runId: 'run_legacy_local', spec }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federated-message-targeting.test.ts b/src/main/runtime/rpc/methods/orchestration/federation/federated-message-targeting.test.ts index 8e80a8e3925..c28ef94a4a9 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federated-message-targeting.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federated-message-targeting.test.ts @@ -25,6 +25,7 @@ describe('orchestration federated message targeting', () => { vi.spyOn(runtime, 'getTerminalPaneKey').mockReturnValue(paneKey) vi.spyOn(runtime, 'getTerminalProcessIncarnation').mockReturnValue(processIncarnation) db.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId, taskId: 'task_remote_targeting', homePeerFingerprint: 'home_peer', diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federated-release-safety.test.ts b/src/main/runtime/rpc/methods/orchestration/federation/federated-release-safety.test.ts index f3e160244d1..d5150dc052e 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federated-release-safety.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federated-release-safety.test.ts @@ -152,6 +152,7 @@ describe('federated worker release ownership', () => { function createAttachment(dispatchId: string, terminalOwnership?: 'created' | 'external'): void { db.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId, taskId: `task_${dispatchId}`, homePeerFingerprint: HOME_FINGERPRINT, diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-start.ts b/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-start.ts index b577cc87737..a7c59b7064b 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-start.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federated-worker-start.ts @@ -162,6 +162,7 @@ export async function startFederatedWorker(args: { server.environmentId, 'orchestration.federationAttachStart', { + runId, dispatchId: started.dispatch.id, taskId: taskForRemote.id, taskSpec: taskForRemote.spec, diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federation-agent-launch.test.ts b/src/main/runtime/rpc/methods/orchestration/federation/federation-agent-launch.test.ts index 748e4c55295..ace3bfe407a 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federation-agent-launch.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federation-agent-launch.test.ts @@ -56,6 +56,7 @@ describe('federated worker agent launch', () => { const result = (await method.handler( method.params!.parse({ + runId: 'run-home', dispatchId: 'ctx_remote', taskId: 'task_remote', taskSpec: 'remote cursor worker', diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federation-control-mail.test.ts b/src/main/runtime/rpc/methods/orchestration/federation/federation-control-mail.test.ts index 755f85fd512..c95ec9b5630 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federation-control-mail.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federation-control-mail.test.ts @@ -107,6 +107,7 @@ describe('orchestration federation control mail', () => { homeDb.markWorkerDispatchReady(dispatchId) workerDb.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId, taskId: task.id, homePeerFingerprint: homeFingerprint, diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federation-folder-placement.test.ts b/src/main/runtime/rpc/methods/orchestration/federation/federation-folder-placement.test.ts index b8264bd61a7..68364dac1ed 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federation-folder-placement.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federation-folder-placement.test.ts @@ -27,6 +27,7 @@ describe('orchestration federated folder placement', () => { await expect( method.handler( method.params!.parse({ + runId: 'run-home', dispatchId: 'ctx_folder', taskId: 'task_folder', taskSpec: 'work in folder', diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federation-lifecycle-settlement.test.ts b/src/main/runtime/rpc/methods/orchestration/federation/federation-lifecycle-settlement.test.ts index 3e949383731..e111865d904 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federation-lifecycle-settlement.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federation-lifecycle-settlement.test.ts @@ -445,6 +445,7 @@ describe('orchestration federation lifecycle settlement', () => { const dispatchId = `ctx_persisted_protocol_${protocolVersion}` const taskId = `task_persisted_protocol_${protocolVersion}` workerDb.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId, taskId, homePeerFingerprint: 'run-home-device-token', diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federation-liveness-verdict.test.ts b/src/main/runtime/rpc/methods/orchestration/federation/federation-liveness-verdict.test.ts index 20ae3135ec2..7c75c52eb6c 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federation-liveness-verdict.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federation-liveness-verdict.test.ts @@ -58,6 +58,7 @@ describe('federation host liveness verdicts', () => { status: 'exited' } as never) db.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId: DISPATCH_ID, taskId: 'task_remote', homePeerFingerprint: HOME_FINGERPRINT, @@ -112,6 +113,7 @@ describe('federation host liveness verdicts', () => { throw new Error('Expected the real runtime PTY to be listed') } hostDb.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId: DISPATCH_ID, taskId: 'task_remote', homePeerFingerprint: HOME_FINGERPRINT, diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federation-setup.test.ts b/src/main/runtime/rpc/methods/orchestration/federation/federation-setup.test.ts index c905ddffeb8..83865cf96e4 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federation-setup.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federation-setup.test.ts @@ -49,6 +49,7 @@ describe('orchestration federated setup evidence', () => { } ] db.createRemoteDispatchAttachment({ + runId: 'run-home', dispatchId, taskId: 'task_remote_setup', homePeerFingerprint: 'home_peer', diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federation-start-prompt-budget.test.ts b/src/main/runtime/rpc/methods/orchestration/federation/federation-start-prompt-budget.test.ts index 83b446eb102..d3d5b6d71b1 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federation-start-prompt-budget.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federation-start-prompt-budget.test.ts @@ -29,6 +29,7 @@ describe('federation attach-start prompt budget', () => { await expect( method.handler( method.params!.parse({ + runId: 'run-home', dispatchId: 'ctx_oversized_remote', taskId: 'task_oversized_remote', taskSpec: 'x'.repeat(8 * 1024 * 1024), diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federation-start-schema.ts b/src/main/runtime/rpc/methods/orchestration/federation/federation-start-schema.ts index d5d1874a788..1e7257df27d 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federation-start-schema.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federation-start-schema.ts @@ -3,6 +3,7 @@ import { OptionalFiniteNumber, OptionalString, requiredString } from '../../../s import { OptionalWorkerLaunchPreference } from '../worker/worker-start-schema' export const FederationAttachStartParams = z.object({ + runId: requiredString('Missing Run ID'), dispatchId: requiredString('Missing Dispatch ID'), taskId: requiredString('Missing Task ID'), taskSpec: requiredString('Missing Task spec'), diff --git a/src/main/runtime/rpc/methods/orchestration/federation/federation.ts b/src/main/runtime/rpc/methods/orchestration/federation/federation.ts index 57afd3103a2..785f6a67eec 100644 --- a/src/main/runtime/rpc/methods/orchestration/federation/federation.ts +++ b/src/main/runtime/rpc/methods/orchestration/federation/federation.ts @@ -65,6 +65,7 @@ export const ORCHESTRATION_FEDERATION_ATTACH_METHODS: RpcMethod[] = [ const db = runtime.getOrchestrationDb() db.createRemoteDispatchAttachment({ + runId: params.runId, dispatchId: params.dispatchId, taskId: params.taskId, homePeerFingerprint: orchestrationMutation.callerFingerprint, diff --git a/src/main/runtime/rpc/methods/orchestration/messaging/check-worker-federated-attachment.test.ts b/src/main/runtime/rpc/methods/orchestration/messaging/check-worker-federated-attachment.test.ts new file mode 100644 index 00000000000..58e0b3aa0ca --- /dev/null +++ b/src/main/runtime/rpc/methods/orchestration/messaging/check-worker-federated-attachment.test.ts @@ -0,0 +1,188 @@ +import { mkdtempSync, rmSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { ORCHESTRATION_METHODS } from '../../orchestration' +import type { RpcContext } from '../../../core' +import { OrchestrationDb } from '../../../../orchestration/db' +import { OrcaRuntimeService } from '../../../../orca-runtime' +import { + encodeFederatedControlMessage, + importFederatedControlMessage +} from '../../../../orchestration/federation-control-message' + +const DISPATCH_ID = 'ctx_federated_worker_1' +const WORKER_HANDLE = 'term_federated_worker' +const WORKER_PANE = 'tab_w:eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee' +const INCARNATION = 'runtime_test:term_federated_worker:1' + +type CheckResult = { + runId: string + deliveryId: string | null + messages: { id: string; subject: string }[] + count: number + replayed: boolean + acknowledged: string | null +} + +describe('orchestration.check on a federated attachment across a restart', () => { + let directory: string | undefined + let db: OrchestrationDb | undefined + + afterEach(() => { + db?.close() + db = undefined + if (directory) { + rmSync(directory, { recursive: true, force: true }) + directory = undefined + } + }) + + function launch(path: string): RpcContext { + db = new OrchestrationDb(path) + const runtime = new OrcaRuntimeService() + runtime.setOrchestrationDb(db) + vi.spyOn(runtime, 'getTerminalPaneKey').mockImplementation((handle) => + handle === WORKER_HANDLE ? WORKER_PANE : null + ) + vi.spyOn(runtime, 'getLiveTerminalPaneKey').mockImplementation((handle) => + runtime.getTerminalPaneKey(handle) + ) + vi.spyOn(runtime, 'getTerminalProcessIncarnation').mockImplementation((handle) => + handle === WORKER_HANDLE ? INCARNATION : null + ) + return { runtime } + } + + function check(ctx: RpcContext, params: Record = {}): Promise { + const method = ORCHESTRATION_METHODS.find((entry) => entry.name === 'orchestration.check') + if (!method) { + throw new Error('orchestration.check is not registered') + } + const parsed = method.params + ? method.params.parse({ terminal: WORKER_HANDLE, ...params }) + : undefined + return method.handler(parsed, ctx) as Promise + } + + function attach(store: OrchestrationDb, dispatchId: string, runId: string): void { + store.createRemoteDispatchAttachment({ + dispatchId, + runId, + taskId: 'task_federated_1', + homePeerFingerprint: 'peer_fp', + protocolVersion: 1, + runtimeEpoch: 'epoch_1', + mutationReceipt: { + callerFingerprint: 'peer_fp', + requestId: 'attach_1', + method: 'orchestration.federationAttachStart', + payloadHash: 'attach_payload' + } + }) + expect(store.getRunRaw(runId)).toBeDefined() + store.prepareRemoteAttachmentAuthority({ + dispatchId, + paneKey: WORKER_PANE, + processIncarnation: INCARNATION, + worktreeId: 'folder_workspace', + terminalHandle: WORKER_HANDLE, + setupState: 'not_applicable', + effects: [] + }) + store.markRemoteAttachmentReady(dispatchId) + } + + it('replays the coordinator instruction and takes its ack after the app restarts', async () => { + directory = mkdtempSync(join(tmpdir(), 'orca-federated-check-')) + const path = join(directory, 'orchestration.db') + + const first = launch(path) + attach(db as OrchestrationDb, DISPATCH_ID, 'run_coordinator') + importFederatedControlMessage(db as OrchestrationDb, { + dispatchId: DISPATCH_ID, + messageId: 'msg_federated_1', + payload: encodeFederatedControlMessage({ + from: 'term_coord', + subject: 'continue the task', + body: 'the plan changed', + type: 'dispatch', + priority: 'normal', + threadId: null, + payload: null + }) + }) + + const delivered = await check(first) + expect(delivered.messages.map((message) => message.id)).toEqual(['msg_federated_1']) + expect(delivered.runId).toBe('run_coordinator') + expect(delivered.replayed).toBe(false) + const deliveryId = delivered.deliveryId as string + expect(deliveryId).not.toBeNull() + ;(db as OrchestrationDb).close() + + // The worker's process outlives the app; its instruction is still unacknowledged. + const second = launch(path) + const replayed = await check(second) + expect(replayed.deliveryId).toBe(deliveryId) + expect(replayed.replayed).toBe(true) + expect(replayed.messages.map((message) => message.id)).toEqual(['msg_federated_1']) + + const acknowledged = await check(second, { ack: deliveryId }) + expect(acknowledged.acknowledged).toBe(deliveryId) + expect(acknowledged.count).toBe(0) + }) + + it('files loopback mail once under the local Dispatch Run without replacing its owner', async () => { + const ctx = launch(':memory:') + const store = db as OrchestrationDb + const run = store.createRun({ + objective: 'loopback coordinator', + coordinatorHandle: 'term_coord', + coordinatorPaneKey: 'tab_coord:pane_coord' + }) + const task = store.createTask({ runId: run.id, spec: 'loopback task' }) + const { dispatch } = store.createStartingWorkerDispatch({ + creator: { kind: 'system' }, + maxDepth: Number.MAX_SAFE_INTEGER, + taskId: task.id, + startOptions: {} + }) + attach(store, dispatch.id, run.id) + expect(store.getRemoteDispatchAttachment(dispatch.id)?.home_run_id).toBe(dispatch.run_id) + expect(store.getRun(run.id)).toEqual(run) + const message = { + dispatchId: dispatch.id, + messageId: 'msg_loopback', + payload: encodeFederatedControlMessage({ + from: 'term_coord', + subject: 'continue', + body: 'loopback instruction', + type: 'dispatch', + priority: 'normal', + threadId: null, + payload: null + }) + } + expect(importFederatedControlMessage(store, message).imported).toBe(true) + expect(importFederatedControlMessage(store, message).imported).toBe(false) + expect(store.getMessageById(message.messageId)?.run_id).toBe(run.id) + const delivered = await check(ctx) + expect(delivered.runId).toBe(run.id) + expect(delivered.messages.map((entry) => entry.id)).toEqual([message.messageId]) + expect((await check(ctx, { ack: delivered.deliveryId })).count).toBe(0) + }) + + it('refuses an attachment with no home Run before writing a Delivery', async () => { + const ctx = launch(':memory:') + const store = db as OrchestrationDb + attach(store, DISPATCH_ID, 'run_coordinator') + const attachment = store.getRemoteDispatchAttachment(DISPATCH_ID)! + vi.spyOn(store, 'findActiveRemoteAttachmentForPane').mockReturnValue({ + ...attachment, + home_run_id: undefined + } as never) + await expect(check(ctx)).rejects.toThrow() + expect(store.db.prepare('SELECT id FROM deliveries').all()).toEqual([]) + }) +}) diff --git a/src/main/runtime/rpc/methods/orchestration/messaging/check-worker.ts b/src/main/runtime/rpc/methods/orchestration/messaging/check-worker.ts index 27df8fd2afa..355a12be5c1 100644 --- a/src/main/runtime/rpc/methods/orchestration/messaging/check-worker.ts +++ b/src/main/runtime/rpc/methods/orchestration/messaging/check-worker.ts @@ -3,7 +3,6 @@ import type { OrcaRuntimeService } from '../../../../orca-runtime' import { OrchestrationError } from '../../../../orchestration/orchestration-error' import { formatMessageBanner } from '../../../../orchestration/formatter' import { exposeMessages } from './mailbox-message-receipt' -import { ORCHESTRATION_LEGACY_RUN_ID } from '../../../../../../shared/orchestration-rpc-contract' import { routeAllMailboxPages } from '../schemas' import { asDispatchFence, callerHoldsDispatchPane, dispatchFenced } from './dispatch-mailbox-fence' import type { CheckParams } from '../schemas' @@ -46,13 +45,15 @@ export async function checkWorkerMailbox(args: { : remoteAttachment ? { dispatchId: remoteAttachment.dispatch_id, - runId: undefined, + runId: remoteAttachment.home_run_id, generation: remoteAttachment.consumer_generation } : undefined if (!workerMailbox) { return undefined } + const deliveryRunId = workerMailbox.runId + db.requireRun(deliveryRunId) const address = `dispatch:${workerMailbox.dispatchId}` // Why: a federated worker host has no dispatch_contexts row, so its generation lives on the // remote_dispatch_attachments row instead. @@ -164,7 +165,6 @@ export async function checkWorkerMailbox(args: { } } await revalidateWorkerMailbox() - const deliveryRunId = workerMailbox.runId ?? ORCHESTRATION_LEGACY_RUN_ID let acknowledged try { acknowledged = params.ack diff --git a/src/main/runtime/rpc/methods/orchestration/runs/migration-behavior.test.ts b/src/main/runtime/rpc/methods/orchestration/runs/migration-behavior.test.ts index d372c733246..929dd5c1ee3 100644 --- a/src/main/runtime/rpc/methods/orchestration/runs/migration-behavior.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/runs/migration-behavior.test.ts @@ -31,7 +31,7 @@ describe('orchestration migration behavior', () => { it('lists an explicitly selected legacy Run without binding or mutation', async () => { const { db, runtime } = createRuntime() - const task = db.createTask({ spec: 'pre-upgrade work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'pre-upgrade work' }) const taskList = ORCHESTRATION_METHODS.find( (method) => method.name === 'orchestration.taskList' )! @@ -55,6 +55,7 @@ describe('orchestration migration behavior', () => { it('formats legacy terminal inspection as read-only without consuming mail', async () => { const { db, runtime } = createRuntime() const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker', to: 'term_coord', subject: 'still working', @@ -79,6 +80,7 @@ describe('orchestration migration behavior', () => { // A consuming check refuses a handle with no live pane before it reads any mail. vi.spyOn(runtime, 'getTerminalPaneKey').mockReturnValue('tab_legacy:leaf_legacy') const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker', to: 'term_coord', subject: 'still working' @@ -98,6 +100,7 @@ describe('orchestration migration behavior', () => { it('rejects replies to legacy mail without marking or inserting rows', async () => { const { db, runtime } = createRuntime() const message = db.insertMessage({ + runId: 'run_legacy_local', from: 'term_worker', to: 'term_coord', subject: 'legacy question' diff --git a/src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.test.ts b/src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.test.ts index bdf5daad565..413a397462b 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.test.ts @@ -131,7 +131,7 @@ describe('failed worker-start receipt for a residual terminal', () => { function failStart(residual: boolean): { recovery?: string } { const d = (db = new OrchestrationDb(':memory:')) - const task = d.createTask({ spec: 'residual receipt' }) + const task = d.createTask({ runId: 'run_legacy_local', spec: 'residual receipt' }) const started = d.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/rpc/methods/orchestration/worker/legacy-dispatch-projection.test.ts b/src/main/runtime/rpc/methods/orchestration/worker/legacy-dispatch-projection.test.ts index 4df73994beb..75ad57f3a12 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/legacy-dispatch-projection.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/legacy-dispatch-projection.test.ts @@ -117,6 +117,6 @@ describe('pre-v3 dispatch rows in worker-list', () => { }) expect(worker.projection.attention.categories).toContain('unverifiable') expect(worker.projection.attention.requiresAction).toBe(true) - expect(worker.projection.nextAction.kind).toBe('inspect') + expect(worker.projection.nextAction).toEqual({ kind: 'none', argv: [] }) }) }) diff --git a/src/main/runtime/rpc/methods/orchestration/worker/manual-dispatch-observation.test.ts b/src/main/runtime/rpc/methods/orchestration/worker/manual-dispatch-observation.test.ts index 4cd8810ad6b..2890fa08938 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/manual-dispatch-observation.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/manual-dispatch-observation.test.ts @@ -242,7 +242,13 @@ describe('manual Dispatch observation', () => { const result = (await workerListMethod.handler( workerListMethod.params?.parse({ run: run.id }), { runtime } - )) as { workers: { dispatchId: string; workerState: string; terminalState: string | null }[] } + )) as { + workers: { + dispatchId: string + workerState: string + terminalState: string | null + }[] + } expect(result.workers).toEqual([ expect.objectContaining({ @@ -262,7 +268,10 @@ describe('manual Dispatch observation', () => { const runtime = new OrcaRuntimeService() runtime.setOrchestrationDb(db) const closeTerminal = vi.spyOn(runtime, 'closeTerminal') - const task = db.createTask({ spec: 'operator-owned lane' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'operator-owned lane' + }) const dispatch = createRootDispatch( db, task.id, diff --git a/src/main/runtime/rpc/methods/structured-worker-stop-receipt.test.ts b/src/main/runtime/rpc/methods/structured-worker-stop-receipt.test.ts index 82cc53ff735..151285ffb1e 100644 --- a/src/main/runtime/rpc/methods/structured-worker-stop-receipt.test.ts +++ b/src/main/runtime/rpc/methods/structured-worker-stop-receipt.test.ts @@ -62,7 +62,10 @@ describe('worker-stop on a structured worker this runtime cannot reach', () => { worktreeId: WORKTREE, hostScope: { kind: 'local', hostId: 'local' } }) - const task = db.createTask({ spec: 'stop a structured worker' }) + const task = db.createTask({ + runId: 'run_legacy_local', + spec: 'stop a structured worker' + }) const started = db.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/rpc/orchestration-11745-regression-verification.test.ts b/src/main/runtime/rpc/orchestration-11745-regression-verification.test.ts index 47d585ca244..7a644cc9def 100644 --- a/src/main/runtime/rpc/orchestration-11745-regression-verification.test.ts +++ b/src/main/runtime/rpc/orchestration-11745-regression-verification.test.ts @@ -642,7 +642,11 @@ function createAdoptedDb(options: { settleWork: boolean }): { const dbPath = join(dir, 'orchestration.db') const before = new OrchestrationDb(dbPath) - const task = before.createTask({ spec: 'legacy assignment', createdByTerminalHandle: 'term_old' }) + const task = before.createTask({ + runId: 'run_legacy_local', + spec: 'legacy assignment', + createdByTerminalHandle: 'term_old' + }) createRootDispatch( before, task.id, @@ -650,6 +654,7 @@ function createAdoptedDb(options: { settleWork: boolean }): { 'tab_old:33333333-3333-4333-8333-333333333333' ) const recovery = before.insertMessage({ + runId: 'run_legacy_local', from: 'term_old_worker', to: 'term_old', subject: 'recovered worker outcome', diff --git a/src/main/runtime/rpc/orchestration-legacy-compatibility-dispatcher-test-fixture.ts b/src/main/runtime/rpc/orchestration-legacy-compatibility-dispatcher-test-fixture.ts index cca68da8f63..faf934a6d66 100644 --- a/src/main/runtime/rpc/orchestration-legacy-compatibility-dispatcher-test-fixture.ts +++ b/src/main/runtime/rpc/orchestration-legacy-compatibility-dispatcher-test-fixture.ts @@ -53,6 +53,7 @@ export function createHarness(): LegacyCompatibilityDispatcherHarness { const dbPath = join(dir, 'orchestration.db') const before = new OrchestrationDb(dbPath) const task = before.createTask({ + runId: 'run_legacy_local', spec: 'legacy assignment', createdByTerminalHandle: COORDINATOR_HANDLE }) diff --git a/src/main/runtime/rpc/orchestration-legacy-coordinator-race.test.ts b/src/main/runtime/rpc/orchestration-legacy-coordinator-race.test.ts index 3040c37a9ef..71daf09b0e3 100644 --- a/src/main/runtime/rpc/orchestration-legacy-coordinator-race.test.ts +++ b/src/main/runtime/rpc/orchestration-legacy-coordinator-race.test.ts @@ -43,6 +43,7 @@ function createHarness(): Harness { const dbPath = join(dir, 'orchestration.db') const before = new OrchestrationDb(dbPath) const task = before.createTask({ + runId: 'run_legacy_local', spec: 'legacy assignment', createdByTerminalHandle: COORDINATOR_HANDLE }) diff --git a/src/main/runtime/rpc/orchestration-legacy-question-takeover.test.ts b/src/main/runtime/rpc/orchestration-legacy-question-takeover.test.ts index 77d7e2d5a02..82c59f39587 100644 --- a/src/main/runtime/rpc/orchestration-legacy-question-takeover.test.ts +++ b/src/main/runtime/rpc/orchestration-legacy-question-takeover.test.ts @@ -40,12 +40,14 @@ function createHarness(options?: { seedCutoverQuestion?: boolean; seedCutoverAns const dbPath = join(dir, 'orchestration.db') const before = new OrchestrationDb(dbPath) const task = before.createTask({ + runId: 'run_legacy_local', spec: 'legacy assignment', createdByTerminalHandle: COORDINATOR_HANDLE }) const dispatch = createRootDispatch(before, task.id, WORKER_HANDLE, WORKER_PANE) const cutoverQuestion = options?.seedCutoverQuestion ? before.insertMessage({ + runId: 'run_legacy_local', from: WORKER_HANDLE, to: COORDINATOR_HANDLE, subject: 'Question', @@ -60,6 +62,7 @@ function createHarness(options?: { seedCutoverQuestion?: boolean; seedCutoverAns const cutoverAnswer = cutoverQuestion && options?.seedCutoverAnswer ? before.insertMessage({ + runId: 'run_legacy_local', from: COORDINATOR_HANDLE, to: WORKER_HANDLE, subject: 'Re: Question', @@ -308,7 +311,10 @@ describe('legacy question takeover compatibility', () => { resumed as { result: { legacyCompatibility: { - answerAcknowledgement: { questionId: string; answerMessageId: string } + answerAcknowledgement: { + questionId: string + answerMessageId: string + } } } } diff --git a/src/main/runtime/rpc/orchestration-legacy-takeover-delivery.test.ts b/src/main/runtime/rpc/orchestration-legacy-takeover-delivery.test.ts index bcaf5fca11f..feb3017b538 100644 --- a/src/main/runtime/rpc/orchestration-legacy-takeover-delivery.test.ts +++ b/src/main/runtime/rpc/orchestration-legacy-takeover-delivery.test.ts @@ -51,6 +51,7 @@ function createHarness(): Harness { const dbPath = join(dir, 'orchestration.db') const before = new OrchestrationDb(dbPath) const task = before.createTask({ + runId: 'run_legacy_local', spec: 'legacy assignment', createdByTerminalHandle: COORDINATOR_HANDLE }) diff --git a/src/main/runtime/rpc/orchestration-legacy-takeover-dispatcher.test.ts b/src/main/runtime/rpc/orchestration-legacy-takeover-dispatcher.test.ts index 2a2d6b4937b..e5a05fe7d26 100644 --- a/src/main/runtime/rpc/orchestration-legacy-takeover-dispatcher.test.ts +++ b/src/main/runtime/rpc/orchestration-legacy-takeover-dispatcher.test.ts @@ -47,6 +47,7 @@ function createHarness(): Harness { const dbPath = join(dir, 'orchestration.db') const before = new OrchestrationDb(dbPath) const task = before.createTask({ + runId: 'run_legacy_local', spec: 'legacy assignment', createdByTerminalHandle: COORDINATOR_HANDLE }) diff --git a/src/main/runtime/rpc/orchestration-mutation-ledger.test.ts b/src/main/runtime/rpc/orchestration-mutation-ledger.test.ts index d44d3f153d7..b87f595f4b2 100644 --- a/src/main/runtime/rpc/orchestration-mutation-ledger.test.ts +++ b/src/main/runtime/rpc/orchestration-mutation-ledger.test.ts @@ -44,7 +44,7 @@ describe('durable orchestration mutation ledger', () => { const runtime = new OrcaRuntimeService() runtime.setOrchestrationDb(db) const effect = vi.fn((subject: string) => - db.insertMessage({ from: 'caller', to: 'recipient', subject }) + db.insertMessage({ runId: 'run_legacy_local', from: 'caller', to: 'recipient', subject }) ) const dispatcher = new RpcDispatcher({ runtime, @@ -299,7 +299,10 @@ describe('durable orchestration mutation ledger', () => { const db = new OrchestrationDb(':memory:') const runtime = new OrcaRuntimeService() runtime.setOrchestrationDb(db) - const params = { from: 'term_coord', task: db.createTask({ spec: 'restart' }).id } + const params = { + from: 'term_coord', + task: db.createTask({ runId: 'run_legacy_local', spec: 'restart' }).id + } const callerFingerprint = db.getOrCreateLocalMutationCallerFingerprint() const payloadHash = createHash('sha256') .update(JSON.stringify({ method: 'orchestration.workerStart', params })) diff --git a/src/main/runtime/rpc/orchestration-mutation-request-show.test.ts b/src/main/runtime/rpc/orchestration-mutation-request-show.test.ts index cb31ea22736..e64fb5b9640 100644 --- a/src/main/runtime/rpc/orchestration-mutation-request-show.test.ts +++ b/src/main/runtime/rpc/orchestration-mutation-request-show.test.ts @@ -22,7 +22,7 @@ function createHarness() { const runtime = new OrcaRuntimeService() runtime.setOrchestrationDb(db) const effect = vi.fn((subject: string) => - db.insertMessage({ from: 'caller', to: 'recipient', subject }) + db.insertMessage({ runId: 'run_legacy_local', from: 'caller', to: 'recipient', subject }) ) const dispatcher = new RpcDispatcher({ runtime, diff --git a/src/main/runtime/rpc/orchestration-runtime-update-settlement.test.ts b/src/main/runtime/rpc/orchestration-runtime-update-settlement.test.ts index b2d3d110627..4172097853d 100644 --- a/src/main/runtime/rpc/orchestration-runtime-update-settlement.test.ts +++ b/src/main/runtime/rpc/orchestration-runtime-update-settlement.test.ts @@ -62,6 +62,7 @@ function createUpdateHarness(): Harness { const oldRuntimeDb = new OrchestrationDb(dbPath) const task = oldRuntimeDb.createTask({ + runId: 'run_legacy_local', spec: 'finish work across an app update', createdByTerminalHandle: COORDINATOR_HANDLE }) diff --git a/src/main/runtime/runtime-legacy-worker-terminal-resume-fence.test.ts b/src/main/runtime/runtime-legacy-worker-terminal-resume-fence.test.ts index 6fe14f2abe7..4d1f81869d5 100644 --- a/src/main/runtime/runtime-legacy-worker-terminal-resume-fence.test.ts +++ b/src/main/runtime/runtime-legacy-worker-terminal-resume-fence.test.ts @@ -60,7 +60,7 @@ describe('settled worker automatic-resume fence persistence', () => { getWorkspaceSessionHostIds: () => [LOCAL_EXECUTION_HOST_ID], flushOrThrow: vi.fn() } as unknown as RuntimeStore - const task = orchestrationDb.createTask({ spec: 'fence me' }) + const task = orchestrationDb.createTask({ runId: 'run_legacy_local', spec: 'fence me' }) const started = orchestrationDb.createStartingWorkerDispatch({ creator: { kind: 'system' }, maxDepth: Number.MAX_SAFE_INTEGER, diff --git a/src/main/runtime/runtime-rpc-request-authorization.test.ts b/src/main/runtime/runtime-rpc-request-authorization.test.ts index d7e7576bc27..5ff19f94563 100644 --- a/src/main/runtime/runtime-rpc-request-authorization.test.ts +++ b/src/main/runtime/runtime-rpc-request-authorization.test.ts @@ -92,9 +92,19 @@ describe('OrcaRuntimeRpcServer', () => { } try { - db.insertMessage({ from: 'worker', to: 'coordinator', subject: 'before reset' }) + db.insertMessage({ + runId: 'run_legacy_local', + from: 'worker', + to: 'coordinator', + subject: 'before reset' + }) const first = await resetMessages('reset-first', firstDevice.token) - db.insertMessage({ from: 'worker', to: 'coordinator', subject: 'after reset' }) + db.insertMessage({ + runId: 'run_legacy_local', + from: 'worker', + to: 'coordinator', + subject: 'after reset' + }) const replay = await resetMessages('reset-replay', firstDevice.token) expect(first).toMatchObject({ @@ -129,6 +139,7 @@ describe('OrcaRuntimeRpcServer', () => { const device = server['deviceRegistry']!.addDevice('existing-cli', 'runtime') const existingFingerprint = createHash('sha256').update(device.token).digest('hex') db.createRemoteDispatchAttachment({ + runId: 'run_home', dispatchId: 'ctx_existing_remote', taskId: 'task_existing_remote', homePeerFingerprint: existingFingerprint, diff --git a/src/shared/orchestration-fleet-projection.test.ts b/src/shared/orchestration-fleet-projection.test.ts index f8cc10de176..5941c696c88 100644 --- a/src/shared/orchestration-fleet-projection.test.ts +++ b/src/shared/orchestration-fleet-projection.test.ts @@ -137,7 +137,7 @@ describe('orchestration fleet projection', () => { host: { kind: 'local' }, liveness: { verdict: 'unverifiable', reason: 'missing_status' }, resource: { state: 'absent', reason: 'unsupervised' }, - nextAction: { kind: 'inspect' } + nextAction: { kind: 'none' } }) }) @@ -229,6 +229,7 @@ describe('orchestration fleet projection', () => { expect(second.workers.at(-1)?.id).toBe('dispatch-109') }) + // Cleanup still earns a command when liveness is unverifiable. it('suggests release only for reclaimable ownership', () => { const result = projectOrchestrationFleet({ workers: [worker('done', { terminalState: 'reclaimable' })], @@ -236,6 +237,7 @@ describe('orchestration fleet projection', () => { now: 1 }) + expect(result.workers[0]?.liveness.verdict).toBe('unverifiable') expect(result.workers[0]?.nextAction).toEqual({ kind: 'release', argv: ['orchestration', 'worker-release', '--dispatch', 'done'] @@ -487,7 +489,8 @@ describe('fleet liveness and attention after a host verdict', () => { verdict: 'unverifiable', reason: 'missing_status' }) - expect(projected.workers[0]!.nextAction.kind).toBe('inspect') + // `recover` is reserved for a proven exit; worker-show would only restate this row. + expect(projected.workers[0]!.nextAction).toEqual({ kind: 'none', argv: [] }) }) it('certifies a process_exited stage whose exit was observed', () => { @@ -519,15 +522,19 @@ describe('fleet liveness and attention after a host verdict', () => { expect(projected.workers[0]!.nextAction).toEqual({ kind: 'none', argv: [] }) }) - it('keeps an unverifiable worker on inspect: absence is never authority to stop', () => { + // worker-show repeats this projection, so inspecting again would loop. + it('asks nothing of an unverifiable worker instead of looping on worker-show', () => { const now = 10 * AGENT_STATUS_STALE_AFTER_MS const projected = projectOrchestrationFleet({ workers: [worker('1')], statuses: [status('1', now - AGENT_STATUS_STALE_AFTER_MS - 60_000)], now }) - expect(projected.workers[0]!.liveness.verdict).toBe('unverifiable') - expect(projected.workers[0]!.nextAction.kind).toBe('inspect') + expect(projected.workers[0]!.liveness).toMatchObject({ + verdict: 'unverifiable', + reason: 'stale_status' + }) + expect(projected.workers[0]!.nextAction).toEqual({ kind: 'none', argv: [] }) }) it('leaves a worker blocked on a question inspectable rather than recoverable', () => { @@ -539,6 +546,22 @@ describe('fleet liveness and attention after a host verdict', () => { expect(projected.workers[0]!.nextAction.kind).toBe('inspect') }) + it.each([{ pendingInput: true }, { pendingApproval: true }])( + 'keeps an unverifiable worker with %o inspectable', + (pending) => { + const projected = projectOrchestrationFleet({ + workers: [worker('1', pending)], + statuses: [], + now: 10_000 + }) + expect(projected.workers[0]!.liveness.verdict).toBe('unverifiable') + expect(projected.workers[0]!.nextAction).toEqual({ + kind: 'inspect', + argv: ['orchestration', 'worker-show', '--dispatch', '1'] + }) + } + ) + // The live worker-list row from a stopped worker: the same receipt proved the exit, // called it absence, and pointed back at the command that reported the settlement. it('never contradicts a proven exit on a stopped worker still owning its terminal', () => { diff --git a/src/shared/orchestration-fleet-worker-projection.ts b/src/shared/orchestration-fleet-worker-projection.ts index a463ca299df..aec9377ea82 100644 --- a/src/shared/orchestration-fleet-worker-projection.ts +++ b/src/shared/orchestration-fleet-worker-projection.ts @@ -176,6 +176,10 @@ export function projectFleetNextAction( ) { return { kind: 'none', argv: [] } } + // worker-show repeats this projection; absence alone cannot earn another command. + if (liveness.verdict === 'unverifiable' && !worker.pendingInput && !worker.pendingApproval) { + return { kind: 'none', argv: [] } + } return { kind: 'inspect', argv: ['orchestration', 'worker-show', '--dispatch', worker.dispatchId] From d346d6f4474e1377b7d2564afcf609c7e48add6d Mon Sep 17 00:00:00 2001 From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com> Date: Tue, 8 Sep 2026 04:03:23 -0400 Subject: [PATCH 06/59] fix(orchestration): refuse Task re-open under a live worker; allow stop re-issue on a stranded row (#19551) --- .../db-stopping-worker-task-guard.test.ts | 122 ++++++++++++++++++ .../db/tasks/task-status-transition.ts | 20 ++- .../worker-dispatch/worker-dispatch-stop.ts | 14 +- .../orchestration/worker/worker-stop.ts | 5 +- 4 files changed, 151 insertions(+), 10 deletions(-) create mode 100644 src/main/runtime/orchestration/db-stopping-worker-task-guard.test.ts diff --git a/src/main/runtime/orchestration/db-stopping-worker-task-guard.test.ts b/src/main/runtime/orchestration/db-stopping-worker-task-guard.test.ts new file mode 100644 index 00000000000..21816c4492a --- /dev/null +++ b/src/main/runtime/orchestration/db-stopping-worker-task-guard.test.ts @@ -0,0 +1,122 @@ +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { OrchestrationDb } from './db' +import { createRootDispatch } from './db/root-dispatch-test-fixture' + +const PANE_W = 'tab_w:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa' + +describe('a Task whose supervised worker is stopping', () => { + let db: OrchestrationDb + beforeEach(() => { + db = new OrchestrationDb(':memory:') + }) + afterEach(() => db.close()) + + function localWorker() { + const task = db.createTask({ spec: 'local work' }) + const { dispatch } = db.createStartingWorkerDispatch({ + taskId: task.id, + startOptions: {}, + creator: { kind: 'system' }, + maxDepth: 9 + }) + db.prepareStartingWorkerAuthority({ + dispatchId: dispatch.id, + handle: 'term_w', + paneKey: PANE_W, + processIncarnation: 'inc1', + worktreeId: 'wt', + effects: [], + setupState: 'not_configured' + }) + db.markWorkerDispatchReady(dispatch.id) + return { task, dispatch } + } + + describe('task-update', () => { + it('refuses to re-open the Task while the worker is stopping', () => { + const { task, dispatch } = localWorker() + db.beginWorkerStop(dispatch.id, 'epoch_home') + expect(db.getTask(task.id)?.status).toBe('blocked') + + expect(() => db.updateTaskStatus(task.id, 'dispatched')).toThrowError( + expect.objectContaining({ + code: 'task_not_startable', + data: { taskId: task.id, dispatchId: dispatch.id } + }) + ) + expect(db.getTask(task.id)?.status).toBe('blocked') + }) + + it('refuses to re-open the Task while the stop outcome is unknown', () => { + const { task, dispatch } = localWorker() + db.beginWorkerStop(dispatch.id, 'epoch_home') + db.markWorkerStopUnknown(dispatch.id, 'the execution host did not answer') + + expect(() => db.updateTaskStatus(task.id, 'dispatched')).toThrowError( + expect.objectContaining({ code: 'task_not_startable' }) + ) + expect(db.getTask(task.id)?.status).toBe('blocked') + }) + + it('control: still accepts dispatched for an active Dispatch with no supervised worker', () => { + const task = db.createTask({ spec: 'unsupervised work' }) + createRootDispatch(db, task.id, 'term_worker') + + expect(db.updateTaskStatus(task.id, 'dispatched')?.status).toBe('dispatched') + }) + + it('control: still accepts dispatched while the supervised worker is ready', () => { + const { task } = localWorker() + + expect(db.updateTaskStatus(task.id, 'dispatched')?.status).toBe('dispatched') + }) + + it('control: a no-op re-assert of dispatched under a stopping worker stays legal', () => { + const { task, dispatch } = localWorker() + expect(db.getTask(task.id)?.status).toBe('dispatched') + db.beginWorkerStop(dispatch.id, 'epoch_home') + // beginWorkerStop moved the Task to blocked; put it back the only way that is not a re-open. + db.db.prepare("UPDATE tasks SET status = 'dispatched' WHERE id = ?").run(task.id) + + expect(db.updateTaskStatus(task.id, 'dispatched')?.status).toBe('dispatched') + }) + }) + + describe('operator escape', () => { + it('accepts a re-issued worker-stop and reaches an honest stop_unknown outcome', () => { + const { task, dispatch } = localWorker() + db.beginWorkerStop(dispatch.id, 'epoch_dead_runtime') + + // The runtime that owned the first stop died mid-flight; the re-issue is the way out. + const reissued = db.beginWorkerStop(dispatch.id, 'epoch_new_runtime') + expect(reissued).toMatchObject({ disposition: 'stopping' }) + expect(db.getWorkerDispatch(dispatch.id)?.runtime_epoch).toBe('epoch_new_runtime') + + db.markWorkerStopUnknown(dispatch.id, 'the execution host did not answer') + expect(db.abandonWorkerDispatch(dispatch.id)).toMatchObject({ disposition: 'abandoned' }) + expect(db.getTask(task.id)?.status).toBe('blocked') + }) + + it('refuses a re-issue from the runtime whose own stop is still in flight', () => { + const { dispatch } = localWorker() + db.beginWorkerStop(dispatch.id, 'epoch_this_runtime') + + // The terminal is closing and its exit event has not landed yet. Letting this second pass + // record stop_unknown would make the exit read as a crash instead of this stop succeeding. + expect(() => db.beginWorkerStop(dispatch.id, 'epoch_this_runtime')).toThrowError( + /cannot stop from stopping/ + ) + + // The row is still the one the exit path claims a clean stop from: stopping, same epoch. + expect(db.getWorkerDispatch(dispatch.id)).toMatchObject({ + state: 'stopping', + runtime_epoch: 'epoch_this_runtime' + }) + expect(db.settleWorkerStop(dispatch.id).state).toBe('stopped') + expect(db.getDispatchContextById(dispatch.id)).toMatchObject({ + status: 'failed', + last_failure: 'stopped' + }) + }) + }) +}) diff --git a/src/main/runtime/orchestration/db/tasks/task-status-transition.ts b/src/main/runtime/orchestration/db/tasks/task-status-transition.ts index e1de8dc5b17..dcddc781b6d 100644 --- a/src/main/runtime/orchestration/db/tasks/task-status-transition.ts +++ b/src/main/runtime/orchestration/db/tasks/task-status-transition.ts @@ -35,18 +35,24 @@ export function updateTaskStatus( ORDER BY rowid DESC LIMIT 1` ) .get(id) as { id: string } | undefined - const activeWorker = terminalStatus - ? (this.db - .prepare( - `SELECT active.id + // Why: a supervised worker owns its Task for as long as it is alive. Every status this + // function lets past the active-Dispatch check must clear the same worker check, or the Task + // re-opens under a worker whose own lifecycle can no longer settle it (#16904 relay wedge). + // A no-op re-assert of `dispatched` re-opens nothing and stays legal. + const reopensUnderWorker = requiresActiveDispatch && task.status !== 'dispatched' + const activeWorker = + terminalStatus || reopensUnderWorker + ? (this.db + .prepare( + `SELECT active.id FROM dispatch_contexts active JOIN worker_dispatches worker ON worker.dispatch_id = active.id WHERE active.task_id = ? AND active.status IN ('pending', 'dispatched') AND worker.state NOT IN ('failed', 'succeeded', 'stopped', 'abandoned') ORDER BY active.rowid DESC LIMIT 1` - ) - .get(id) as { id: string } | undefined) - : undefined + ) + .get(id) as { id: string } | undefined) + : undefined if (activeWorker) { throw new OrchestrationError( 'task_not_startable', diff --git a/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-stop.ts b/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-stop.ts index 8dbda2030c5..fd4ee773bb4 100644 --- a/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-stop.ts +++ b/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-stop.ts @@ -59,7 +59,19 @@ export function beginWorkerStop( this.db.exec('COMMIT') return { disposition: 'already_settled', worker, dispatch } } - if (!['ready', 'start_unknown'].includes(worker.state)) { + // Why `stopping` under a DIFFERENT epoch is accepted: a stop whose runtime died mid-flight + // leaves the row here forever, and refusing the re-issue was the only operator escape + // (#16904). Re-running the stop earns the honest outcome — settled, or `stop_unknown`, from + // which the worker can be abandoned. It never asserts an exit the runtime did not observe. + // + // Why the epoch and not just the state: this runtime's own `stopping` row means its stop is + // still in flight, and a second pass would record `stop_unknown` over it. The exit event that + // follows claims a clean stop only from `stopping` under its own epoch + // (failActiveDispatchOnExit), so it would then read the operator's stop as a crash and + // escalate it. Same predicate as that reader, so both agree on whose stop this is. + const stopStrandedByAnotherRuntime = + worker.state === 'stopping' && worker.runtime_epoch !== runtimeEpoch + if (!['ready', 'start_unknown'].includes(worker.state) && !stopStrandedByAnotherRuntime) { throw new OrchestrationError( 'dispatch_inactive', `Dispatch ${dispatchId} cannot stop from ${worker.state}.` diff --git a/src/main/runtime/rpc/methods/orchestration/worker/worker-stop.ts b/src/main/runtime/rpc/methods/orchestration/worker/worker-stop.ts index 605d8c52d4a..643323cf62e 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/worker-stop.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/worker-stop.ts @@ -245,8 +245,9 @@ export const ORCHESTRATION_WORKER_STOP_METHODS: RpcMethod[] = [ const activeStopByRuntime = new WeakMap>>() -/** Two callers stopping one Dispatch: the second reached `beginWorkerStop` after the first moved - * the row to `stopping` and got `dispatch_inactive` instead of the first caller's receipt. */ +/** Two callers stopping one Dispatch: coalesced so only one of them closes the terminal. Both are + * in this runtime and so carry one epoch, which `beginWorkerStop` refuses a second time anyway; + * the epoch it does accept belongs to a row a dead runtime stranded, and no caller here holds one. */ function dedupeWorkerStop( runtime: OrcaRuntimeService, dispatchId: string, From ea102a9eb892b084654fecf1825281d676dbc01b Mon Sep 17 00:00:00 2001 From: Neil <4138956+nwparker@users.noreply.github.com> Date: Tue, 8 Sep 2026 01:45:52 -0700 Subject: [PATCH 07/59] fix(i18n): drop orphan TerminalPane.minimumContrast entries that broke main static analysis The 7 auto.components.settings.TerminalPane.minimumContrast.* entries added by #18126 have zero call sites; the shipped component reads settings.contrast.*. Because the runtime-required catalog classifies any key with no literal-default call site as required, the orphans broke 'Verify runtime-required localization catalog' on main and red-lit every PR in the repo. Deleting them is the root-cause fix: regenerating would instead add dead strings to the boot bundle. On main+delete, --fix regenerates a byte-identical catalog and the CI step exits 0. Merged with 'test / tests node 24 3/8' red: that failure is an unrelated main break from the #19542/#19551 collision, not from this change. --- src/renderer/src/i18n/locales/en.json | 9 --------- 1 file changed, 9 deletions(-) diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json index 4fa36b54a9f..8e6d862e3b5 100644 --- a/src/renderer/src/i18n/locales/en.json +++ b/src/renderer/src/i18n/locales/en.json @@ -8627,15 +8627,6 @@ "fastDescription": "Extra multiplier while scrolling with a modifier key.", "tui": "TUI", "tuiDescription": "Discrete wheel reports for full-screen terminal apps." - }, - "minimumContrast": { - "title": "Minimum Contrast Ratio", - "description": "Lifts terminal foreground colors that sit too close to the background. Leave blank for automatic, or set 1 to render program colors exactly as sent.", - "automatic": "Automatic: {{light}} on light backgrounds, {{dark}} on dark.", - "disabled": "Correction off. Programs that rely on low contrast, like Powerline separators, render as sent.", - "pinned": "Targets {{ratio}}:1 contrast for foreground colors, where possible.", - "placeholder": "Auto", - "suffix": "blank = automatic, 1 = off" } }, "TerminalSettingsPreview": { From d058da4786701d74574959ab9d602b762d17e523 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 8 Sep 2026 08:54:09 +0000 Subject: [PATCH 08/59] Update README downloads badge --- docs/assets/readme-downloads.svg | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/assets/readme-downloads.svg b/docs/assets/readme-downloads.svg index ebee3673b77..75762752848 100644 --- a/docs/assets/readme-downloads.svg +++ b/docs/assets/readme-downloads.svg @@ -1,5 +1,5 @@ - - downloads: 42m + + downloads: 43m @@ -15,7 +15,7 @@ downloads downloads - 42m - 42m + 43m + 43m From 12f53da542d03473367e48a63b85a49eae7c5f8b Mon Sep 17 00:00:00 2001 From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com> Date: Tue, 8 Sep 2026 05:14:59 -0400 Subject: [PATCH 09/59] Remove settled-worker automatic resume and hibernation fences (#19544) * Remove settled-worker automatic resume and hibernation fences * test: retirement rollback case follows the no-fence policy Case 4 seeded and asserted automaticResumeBlockedBy, which this branch deletes. A rolled-back settled worker is now an ordinary done record that wake clears as passive evidence, same as any finished agent pane. * chore(i18n): regenerate the runtime-required catalog for the contrast floor strings * test(orchestration): give the stopping-worker guard fixtures a Run --- config/ts-nocheck-baseline.txt | 2 +- .../stable-pane-relay-absence-respawn.test.ts | 43 ++ ... => orca-runtime-automation-operations.ts} | 6 +- ...act-persisted-terminal-surface-identity.ts | 4 +- .../orca-runtime-preserved-branch-cleanup.ts | 3 +- src/main/runtime/orca-runtime-register-pty.ts | 9 + ...ca-runtime-subscribe-to-terminal-resize.ts | 12 - ...output-and-worker-recovery-part-02.spec.ts | 7 +- ...output-and-worker-recovery-part-03.spec.ts | 12 +- ...output-and-worker-recovery-part-04.spec.ts | 10 +- ...output-and-worker-recovery-part-05.spec.ts | 85 +-- ...output-and-worker-recovery-part-06.spec.ts | 10 +- .../db-stopping-worker-task-guard.test.ts | 4 +- .../worker-terminal-recovery.ts | 12 +- .../worker-terminal-resource-store.ts | 33 ++ ...on-legacy-worker-terminal-recovery.test.ts | 22 +- ...tration-legacy-worker-terminal-recovery.ts | 25 +- ...ion-settled-worker-resume-fence-db.test.ts | 124 ---- src/main/runtime/rpc/methods/orchestration.ts | 3 +- .../messaging/send-point-to-point.ts | 6 - .../worker/worker-release.test.ts | 30 +- .../orchestration/worker/worker-release.ts | 6 - .../settled-worker-resume-fence-sweep.ts | 45 -- ...acy-worker-terminal-recovery-controller.ts | 4 - ...cy-worker-terminal-recovery-persistence.ts | 139 +---- ...-legacy-worker-terminal-recovery-runner.ts | 1 - ...e-legacy-worker-terminal-recovery-types.ts | 1 - ...egacy-worker-terminal-resume-fence.test.ts | 286 ---------- src/main/runtime/runtime-notifier-contract.ts | 1 - ...settled-worker-process-replacement.test.ts | 111 ++++ .../startup/main-process-runtime-service.ts | 1 - src/main/window/runtime-window-lifecycle.ts | 2 - src/preload/api/agent-status-api.ts | 4 - src/preload/api/agent-status-bridge.ts | 10 - ...ty-connection-agent-session-resume.test.ts | 241 +++----- .../cold-restore-resume-startup.ts | 4 +- .../pty-connection/deferred-session-attach.ts | 11 +- .../deferred-session-reattach-choice.ts | 84 ++- .../pty-connection/fresh-spawn-start.ts | 5 +- .../retained-legacy-pty-attach.ts | 30 - .../pty-connection/run-deferred-connect.ts | 2 - .../pty-connection/sleeping-record-access.ts | 3 - .../sleeping-record-park-exemption.test.ts | 16 - .../sleeping-record-park-exemption.ts | 4 +- ...k-subscription-narrowing.react185.test.tsx | 15 - .../use-terminal-tab-cold-parking.test.ts | 39 +- .../ipc-events/agent-status-listeners.ts | 8 - ...cEvents-agent-status-ssh-authority.test.ts | 6 +- .../src/hooks/useIpcEvents-lifecycle.test.ts | 2 - .../src/i18n/en-runtime-required.json | 11 +- .../lib/agent-hibernation-pane-eligibility.ts | 10 +- .../src/lib/agent-hibernation-planner.test.ts | 31 - .../src/lib/live-resume-anchor-record.ts | 11 - ...eeping-agent-session-legacy-worker.test.ts | 53 -- .../src/lib/resume-sleeping-agent-session.ts | 3 - .../lib/settled-worker-wake-policy.test.ts | 47 ++ .../store/slices/agent-pane-authority.test.ts | 7 +- .../agent-status-manual-sleep-capture.test.ts | 62 -- ...agent-status-open-tab-resume-fence.test.ts | 60 -- .../agent-status-provider-session-actions.ts | 4 - .../agent-status-provider-session.test.ts | 58 -- .../slices/agent-status-recovery-actions.ts | 42 -- .../agent-status-recovery-collection.ts | 6 - .../slices/agent-status-sleeping-records.ts | 22 +- .../slices/agent-status-slice-contract.ts | 5 - src/renderer/src/store/slices/agent-status.ts | 1 - .../terminals/terminal-pane-hibernation.ts | 14 - .../web/preload-api/web-agent-status-api.ts | 1 - src/shared/agent-session-resume.ts | 3 - ...pace-session-schema.sleeping-agent.test.ts | 32 ++ .../workspace-session-sleeping-agents.ts | 1 - ...eted-worker-retirement-resume.unit.test.ts | 24 +- .../completed-worker-retirement-fixture.ts | 27 +- ...ettled-worker-tab-survives-restart.spec.ts | 530 ++++++++++++++++++ 74 files changed, 1015 insertions(+), 1593 deletions(-) rename src/main/runtime/{orca-runtime-fence-automation-owner.ts => orca-runtime-automation-operations.ts} (97%) delete mode 100644 src/main/runtime/orchestration/orchestration-settled-worker-resume-fence-db.test.ts delete mode 100644 src/main/runtime/rpc/methods/settled-worker-resume-fence-sweep.ts delete mode 100644 src/main/runtime/runtime-legacy-worker-terminal-resume-fence.test.ts create mode 100644 src/main/runtime/settled-worker-process-replacement.test.ts delete mode 100644 src/renderer/src/components/terminal-pane/pty-connection/retained-legacy-pty-attach.ts delete mode 100644 src/renderer/src/lib/resume-sleeping-agent-session-legacy-worker.test.ts create mode 100644 src/renderer/src/lib/settled-worker-wake-policy.test.ts delete mode 100644 src/renderer/src/store/slices/agent-status-open-tab-resume-fence.test.ts create mode 100644 tests/e2e/settled-worker-tab-survives-restart.spec.ts diff --git a/config/ts-nocheck-baseline.txt b/config/ts-nocheck-baseline.txt index b770b06f827..e897af7387c 100644 --- a/config/ts-nocheck-baseline.txt +++ b/config/ts-nocheck-baseline.txt @@ -34,7 +34,7 @@ src/main/runtime/orca-runtime-create-terminal-side-effect-command-code-detector. src/main/runtime/orca-runtime-create-terminal.ts src/main/runtime/orca-runtime-deliver-pending-messages.ts src/main/runtime/orca-runtime-emit-daemon-pty-transient-fact.ts -src/main/runtime/orca-runtime-fence-automation-owner.ts +src/main/runtime/orca-runtime-automation-operations.ts src/main/runtime/orca-runtime-file-commands.ts src/main/runtime/orca-runtime-fit-override-listeners.ts src/main/runtime/orca-runtime-focus-terminal.ts diff --git a/src/main/ipc/pty/pane/stable-pane-relay-absence-respawn.test.ts b/src/main/ipc/pty/pane/stable-pane-relay-absence-respawn.test.ts index 9a77dd7fbb9..e68bcf6ec99 100644 --- a/src/main/ipc/pty/pane/stable-pane-relay-absence-respawn.test.ts +++ b/src/main/ipc/pty/pane/stable-pane-relay-absence-respawn.test.ts @@ -81,6 +81,49 @@ function sessionStore(leaves: string[]): { store: Store; read: () => WorkspaceSe } describe('stable pane adoption after the relay reports the PTY absent', () => { + it.each([false, true])( + 'reattaches a live pane without launching a provider process (settled worker: %s)', + async (settledWorker) => { + const { store, read } = sessionStore([LEAF]) + const paneKey = `${OWNER.tabId}:${LEAF}` + const record = { + paneKey, + tabId: OWNER.tabId, + worktreeId: WORKTREE, + agent: 'claude' as const, + providerSession: { key: 'session_id' as const, id: 'provider-session' }, + prompt: '', + state: 'done' as const, + capturedAt: 1, + updatedAt: 1, + ...(settledWorker ? { automaticResumeBlockedBy: 'legacy-orchestration-worker' } : {}) + } + store.setWorkspaceSession({ + ...read(), + sleepingAgentSessionsByPaneKey: { [paneKey]: record } + }) + const spawn = vi.fn().mockResolvedValue({ id: OWNER.ptyId, isReattach: true }) + const onFreshSpawn = vi.fn() + const result = await spawnForStablePane({ + runtime: undefined, + store, + worktreeId: WORKTREE, + provider: { spawn } as unknown as IPtyProvider, + spawnOptions: { cols: 80, rows: 24, command: 'claude --resume provider-session' }, + owner: OWNER, + connectionId: 'conn-1', + resolveOwner: () => OWNER, + onFreshSpawn + }) + expect(result.owner).toBe(OWNER) + expect(spawn).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ sessionId: OWNER.ptyId, attachOnly: true, command: undefined }) + ) + expect(onFreshSpawn).not.toHaveBeenCalled() + expect(read().tabsByWorktree[WORKTREE]).toHaveLength(1) + } + ) + it('spawns fresh once the relay has positively answered for that id', async () => { const { run, spawn } = spawnAfterAttachRejection( new SshPtyAbsentFromRelayError(`${SSH_SESSION_EXPIRED_ERROR}: pty-1`) diff --git a/src/main/runtime/orca-runtime-fence-automation-owner.ts b/src/main/runtime/orca-runtime-automation-operations.ts similarity index 97% rename from src/main/runtime/orca-runtime-fence-automation-owner.ts rename to src/main/runtime/orca-runtime-automation-operations.ts index a90730c7886..fe65979ed1e 100644 --- a/src/main/runtime/orca-runtime-fence-automation-owner.ts +++ b/src/main/runtime/orca-runtime-automation-operations.ts @@ -23,7 +23,7 @@ import type { LegacyWorkerTerminalRecoveryResult } from './runtime-legacy-worker import { makePaneKey } from '../../shared/stable-pane-id' import { runtimeWorktreeIdsEqual } from './runtime-worktree-path-identity' -export class OrcaRuntimeWithFenceAutomationOwner extends OrcaRuntimeWithPtyForegroundProcessReads { +export class OrcaRuntimeWithAutomationOperations extends OrcaRuntimeWithPtyForegroundProcessReads { protected fenceAutomationOwner( id: string, expectedOwner: AutomationOwnerPrecondition | undefined, @@ -167,10 +167,6 @@ export class OrcaRuntimeWithFenceAutomationOwner extends OrcaRuntimeWithPtyForeg this.scheduleRestoredMessageRepoints() } - prepareLegacyWorkerTerminalRecovery(): LegacyWorkerTerminalRecoveryPlan { - return this.legacyWorkerRecovery.prepare() - } - protected async flushWorkspaceSessionOrThrowAsync(): Promise { const store = this.store if (store?.flushPendingOrThrowAsync) { diff --git a/src/main/runtime/orca-runtime-has-exact-persisted-terminal-surface-identity.ts b/src/main/runtime/orca-runtime-has-exact-persisted-terminal-surface-identity.ts index 6956644c748..d0425cdc1f9 100644 --- a/src/main/runtime/orca-runtime-has-exact-persisted-terminal-surface-identity.ts +++ b/src/main/runtime/orca-runtime-has-exact-persisted-terminal-surface-identity.ts @@ -1,5 +1,5 @@ // @ts-nocheck -- mechanically split from OrcaRuntimeService; behavior is covered by AST equivalence and characterization tests. -import { OrcaRuntimeWithFenceAutomationOwner } from './orca-runtime-fence-automation-owner' +import { OrcaRuntimeWithAutomationOperations } from './orca-runtime-automation-operations' import { resolveTerminalSessionWorktreeId, runtimeWorktreeIdsEqual @@ -26,7 +26,7 @@ import type { ArtifactWriteRequest } from '../../shared/artifacts' -export class OrcaRuntimeWithHasExactPersistedTerminalSurfaceIdentity extends OrcaRuntimeWithFenceAutomationOwner { +export class OrcaRuntimeWithHasExactPersistedTerminalSurfaceIdentity extends OrcaRuntimeWithAutomationOperations { protected hasExactPersistedTerminalSurfaceIdentity(expected: { worktreeId: string tabId: string diff --git a/src/main/runtime/orca-runtime-preserved-branch-cleanup.ts b/src/main/runtime/orca-runtime-preserved-branch-cleanup.ts index d53994032a1..2e1357e3450 100644 --- a/src/main/runtime/orca-runtime-preserved-branch-cleanup.ts +++ b/src/main/runtime/orca-runtime-preserved-branch-cleanup.ts @@ -136,8 +136,7 @@ export class OrcaRuntimeWithPreservedBranchCleanup extends OrcaRuntimeWithTermin new RuntimeLegacyWorkerTerminalRecoveryPersistence( () => this.store, () => this.getOrchestrationDb(), - (worktreeId) => this.tryGetWorkspaceSessionHostIdForWorktree(worktreeId), - (paneKey, blocked) => this.notifier?.setLegacyWorkerTerminalResumeFence?.(paneKey, blocked) + (worktreeId) => this.tryGetWorkspaceSessionHostIdForWorktree(worktreeId) ) protected readonly legacyWorkerRecovery = new RuntimeLegacyWorkerTerminalRecoveryController({ diff --git a/src/main/runtime/orca-runtime-register-pty.ts b/src/main/runtime/orca-runtime-register-pty.ts index 410798a329d..dae2519ca9f 100644 --- a/src/main/runtime/orca-runtime-register-pty.ts +++ b/src/main/runtime/orca-runtime-register-pty.ts @@ -80,6 +80,15 @@ export class OrcaRuntimeWithRegisterPty extends OrcaRuntimeWithInvalidateAllHand ...(binding && paneKey ? { tabId: binding.tabId, paneKey } : {}), ...(binding?.incarnationId ? { incarnationId: binding.incarnationId } : {}) }) + const hostScope = this.getOrchestrationCompatibilityHostScope(pty) + if (paneKey && binding?.incarnationId && hostScope) { + this._orchestrationDb?.retainReplacedWorkerTerminalResources({ + paneKey, + worktreeId, + hostScope: JSON.stringify(hostScope), + processIncarnation: `${ptyId}:${binding.incarnationId}` + }) + } const agentLaunchAuthority = binding?.agentLaunchAuthority if ( agentLaunchAuthority && diff --git a/src/main/runtime/orca-runtime-subscribe-to-terminal-resize.ts b/src/main/runtime/orca-runtime-subscribe-to-terminal-resize.ts index 484ea73064e..1cef2bbf23a 100644 --- a/src/main/runtime/orca-runtime-subscribe-to-terminal-resize.ts +++ b/src/main/runtime/orca-runtime-subscribe-to-terminal-resize.ts @@ -54,16 +54,6 @@ export class OrcaRuntimeWithSubscribeToTerminalResize extends OrcaRuntimeWithApp // dispatch contexts immediately, rather than waiting for the coordinator's // next poll cycle. This catches agent crashes and unexpected exits within // milliseconds. The task is set back to 'pending' so it can be re-dispatched. - /** A worker settled by its own process exit makes its pane fenceable now, not at the next app - * start; a fence sweep must never fail the exit path behind it. */ - private sweepSettledWorkerResumeFencesAfterExit(): void { - try { - this.prepareLegacyWorkerTerminalRecovery() - } catch (error) { - console.warn('[orchestration] settled worker resume fence sweep failed', error) - } - } - protected failActiveDispatchOnExit( handle: string, paneKey: string | null, @@ -90,7 +80,6 @@ export class OrcaRuntimeWithSubscribeToTerminalResize extends OrcaRuntimeWithApp const stopping = this._orchestrationDb.getWorkerDispatch?.(dispatch.id) if (stopping?.state === 'stopping' && stopping.runtime_epoch === this.getRuntimeId()) { this._orchestrationDb.settleWorkerStop(dispatch.id) - this.sweepSettledWorkerResumeFencesAfterExit() return } @@ -99,7 +88,6 @@ export class OrcaRuntimeWithSubscribeToTerminalResize extends OrcaRuntimeWithApp workerProcessExited: true, terminationReason: cause.kind }) - this.sweepSettledWorkerResumeFencesAfterExit() if (isDeliberateTerminalExit(cause)) { return } diff --git a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-02.spec.ts b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-02.spec.ts index 3c61985e597..a2d45395b26 100644 --- a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-02.spec.ts +++ b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-02.spec.ts @@ -390,7 +390,7 @@ describe('OrcaRuntimeService', () => { expect(getSession().terminalTopologyRevisionByRepoId?.[TEST_REPO_ID]).toBe(1) }) - it('fences provider resume and reveals one exact live legacy worker without stealing focus', async () => { + it('reveals one exact live legacy worker without stealing focus', async () => { const workerLeafId = HEADLESS_LEAF_ID const coordinatorLeafId = HEADLESS_SECOND_LEAF_ID const workerPaneKey = `legacy-worker:${workerLeafId}` @@ -526,10 +526,7 @@ describe('OrcaRuntimeService', () => { resolveLegacyWorkerTerminalRecovery } as never) - runtime.prepareLegacyWorkerTerminalRecovery() - expect( - getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') + expect(getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeDefined() const recovered = await runtime.reconcileLegacyWorkerTerminals({ materializeRenderer: true diff --git a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-03.spec.ts b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-03.spec.ts index 44edd9aa371..00a08310877 100644 --- a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-03.spec.ts +++ b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-03.spec.ts @@ -17,7 +17,7 @@ import { } from '../orca-runtime-test-scenario-builders.spec' describe('OrcaRuntimeService', () => { - it('retries renderer reveal before clearing an adopted legacy worker resume fence', async () => { + it('retries renderer reveal before clearing an adopted legacy worker sleeping record', async () => { const workerPaneKey = `legacy-worker:${HEADLESS_LEAF_ID}` const incarnationId = '44444444-4444-4444-8444-444444444444' const session: WorkspaceSessionState = { @@ -106,7 +106,7 @@ describe('OrcaRuntimeService', () => { expect(resolveLegacyWorkerTerminalRecovery).toHaveBeenCalledWith(workerPaneKey, 'adopted') }) - it('keeps a revealed worker fenced until its exact renderer graph is published', async () => { + it('defers a revealed worker until its exact renderer graph is published', async () => { vi.useFakeTimers() try { const harness = makePostRevealWorkerRecoveryHarness(() => true) @@ -288,7 +288,7 @@ describe('OrcaRuntimeService', () => { } }) - it('keeps recovery fenced when the renderer omits the exact reveal identity', async () => { + it('defers recovery when the renderer omits the exact reveal identity', async () => { const harness = makePostRevealWorkerRecoveryHarness(() => false) harness.revealTerminalSession.mockResolvedValue({ tabId: 'legacy-post-reveal' }) @@ -417,7 +417,7 @@ describe('OrcaRuntimeService', () => { ) }) - it('keeps the legacy worker resume fence in memory when persistence fails', async () => { + it('keeps the legacy worker sleeping record in memory when persistence fails', async () => { const workerPaneKey = `legacy-worker:${HEADLESS_LEAF_ID}` const incarnationId = '99999999-9999-4999-8999-999999999999' const session: WorkspaceSessionState = { @@ -526,9 +526,7 @@ describe('OrcaRuntimeService', () => { }) expect(flushPendingOrThrowAsync).toHaveBeenCalledTimes(2) expect(revealTerminalSession).toHaveBeenCalledOnce() - expect( - getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') + expect(getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeDefined() expect(getSession().sleepingAgentSessionsByPaneKey?.[concurrentPaneKey]?.tabId).toBe( 'concurrent-tab' ) diff --git a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-04.spec.ts b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-04.spec.ts index 48f820cee01..ea70b730388 100644 --- a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-04.spec.ts +++ b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-04.spec.ts @@ -334,10 +334,7 @@ describe('OrcaRuntimeService', () => { resolveLegacyWorkerTerminalRecovery } as never) - runtime.prepareLegacyWorkerTerminalRecovery() - expect( - getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') + expect(getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeDefined() await expect(runtime.reconcileLegacyWorkerTerminals()).resolves.toMatchObject({ adoptedDispatchIds: ['dispatch-exited-two'], @@ -451,9 +448,7 @@ describe('OrcaRuntimeService', () => { exitedDispatchIds: [], deferredDispatchIds: ['dispatch-inventory-unavailable'] }) - expect( - getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') + expect(getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeDefined() expect(resolveLegacyWorkerTerminalRecovery).not.toHaveBeenCalled() expect(listProcesses).toHaveBeenCalledOnce() expect(getSession().tabsByWorktree[TEST_WORKTREE_ID]).toEqual([]) @@ -483,7 +478,6 @@ describe('OrcaRuntimeService', () => { try { const runtime = new OrcaRuntimeService(store) const reconcile = vi.spyOn(runtime, 'reconcileLegacyWorkerTerminals').mockResolvedValue({ - blockedPaneCount: 1, adoptedDispatchIds: [], exitedDispatchIds: [], deferredDispatchIds: [] diff --git a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-05.spec.ts b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-05.spec.ts index 5798916570e..389c70d4f42 100644 --- a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-05.spec.ts +++ b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-05.spec.ts @@ -18,13 +18,12 @@ import { TEST_WORKTREE_PATH, makeFolderProjectGroup, makeFolderWorkspace, - makeRuntimeStoreWithWorkspaceSession, - store + makeRuntimeStoreWithWorkspaceSession } from '../orca-runtime-test-fixtures.spec' import { publishLegacyWorkerReveal } from '../orca-runtime-test-scenario-builders.spec' describe('OrcaRuntimeService', () => { - it('keeps live workers fenced without exact controller identity evidence', async () => { + it('defers live workers without exact controller identity evidence', async () => { const incarnationId = '56565656-5656-4656-8656-565656565656' const cases = [ { @@ -152,8 +151,7 @@ describe('OrcaRuntimeService', () => { for (const { name, leafId } of cases.slice(0, 2)) { expect( getSession().sleepingAgentSessionsByPaneKey?.[`legacy-${name}:${leafId}`] - ?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') + ).toBeDefined() } for (const { name, leafId } of cases.slice(2)) { expect( @@ -374,12 +372,7 @@ describe('OrcaRuntimeService', () => { } as never) try { - expect(runtime.prepareLegacyWorkerTerminalRecovery()).toMatchObject({ - blockedPanes: [expect.objectContaining({ paneKey: workerPaneKey })] - }) - expect( - sshSession.sleepingAgentSessionsByPaneKey?.[workerPaneKey]?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') + expect(sshSession.sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeDefined() expect(localSession.sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeUndefined() await expect( runtime.reconcileLegacyWorkerTerminals({ @@ -422,74 +415,4 @@ describe('OrcaRuntimeService', () => { } }) }) - - it('fences an unresolved folder legacy worker in its exact retained session partition', () => { - const connectionId = 'ssh-unresolved-folder' - const worktreeId = 'folder:missing-folder' - const workerPaneKey = `legacy-unresolved-folder-worker:${HEADLESS_LEAF_ID}` - const remoteInitialSession: WorkspaceSessionState = { - ...getDefaultWorkspaceSession(), - tabsByWorktree: { [worktreeId]: [] }, - sleepingAgentSessionsByPaneKey: { - [workerPaneKey]: { - paneKey: workerPaneKey, - tabId: 'legacy-unresolved-folder-worker', - worktreeId, - agent: 'codex', - providerSession: { key: 'session_id', id: 'legacy-unresolved-folder-session' }, - prompt: 'continue', - state: 'working', - capturedAt: 1, - updatedAt: 1, - origin: 'live', - connectionId - } - } - } - const localSession = getDefaultWorkspaceSession() - let remoteSession = remoteInitialSession - const getWorkspaceSession = vi.fn((hostId?: string | null) => - hostId === `ssh:${connectionId}` ? remoteSession : localSession - ) - const setWorkspaceSession = vi.fn((next: WorkspaceSessionState, hostId?: string | null) => { - if (hostId !== `ssh:${connectionId}`) { - throw new Error(`unexpected workspace-session host ${hostId ?? 'default'}`) - } - remoteSession = next - }) - const runtime = new OrcaRuntimeService({ - ...store, - getFolderWorkspaces: () => [], - getWorkspaceSession, - getWorkspaceSessionHostIds: () => ['local', `ssh:${connectionId}`], - setWorkspaceSession, - flushOrThrow: vi.fn() - } as never) - runtime.setOrchestrationDb({ - listLegacyWorkerTerminalRecoveryRows: () => [ - { - dispatch_id: 'dispatch-unresolved-folder', - task_id: 'task-unresolved-folder', - dispatch_status: 'completed', - contract_version: 0, - assignee_handle: 'term_unresolved_folder', - assignee_pane_key: workerPaneKey, - process_incarnation: 'pty-unresolved-folder:68686868-6868-4868-8868-686868686868', - worker_state: 'ready', - worktree_id: worktreeId, - agent_terminal_handle: 'term_unresolved_folder' - } - ] - } as unknown as OrchestrationDb) - - expect(runtime.prepareLegacyWorkerTerminalRecovery()).toMatchObject({ - blockedPanes: [expect.objectContaining({ paneKey: workerPaneKey, worktreeId })] - }) - expect( - remoteSession.sleepingAgentSessionsByPaneKey?.[workerPaneKey]?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') - expect(localSession.sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeUndefined() - expect(setWorkspaceSession).toHaveBeenCalledOnce() - expect(setWorkspaceSession).toHaveBeenCalledWith(expect.any(Object), `ssh:${connectionId}`) - }) }) diff --git a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-06.spec.ts b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-06.spec.ts index 4078a291ab5..1907b2bb450 100644 --- a/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-06.spec.ts +++ b/src/main/runtime/orca-runtime-tests/terminal-output-and-worker-recovery-part-06.spec.ts @@ -153,11 +153,8 @@ describe('OrcaRuntimeService', () => { deferredDispatchIds: ['dispatch-ssh'] }) expect(listProcesses).not.toHaveBeenCalled() - expect( - getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') + expect(getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeDefined() expect(localSession.sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeUndefined() - expect(getWorkspaceSession).toHaveBeenCalledWith(`ssh:${connectionId}`) await expect( runtime.reconcileLegacyWorkerTerminals({ @@ -175,6 +172,7 @@ describe('OrcaRuntimeService', () => { } expect(getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeUndefined() + expect(getWorkspaceSession).toHaveBeenCalledWith(`ssh:${connectionId}`) expect(setWorkspaceSession).toHaveBeenCalledWith(expect.any(Object), `ssh:${connectionId}`) expect(listProcesses).toHaveBeenCalledTimes(3) expect(revealTerminalSession).toHaveBeenCalledWith(TEST_WORKTREE_ID, { @@ -297,9 +295,7 @@ describe('OrcaRuntimeService', () => { exitedDispatchIds: [], deferredDispatchIds: ['dispatch-wsl'] }) - expect( - getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') + expect(getSession().sleepingAgentSessionsByPaneKey?.[workerPaneKey]).toBeDefined() expect(revealTerminalSession).not.toHaveBeenCalled() observedDistro = 'Ubuntu' diff --git a/src/main/runtime/orchestration/db-stopping-worker-task-guard.test.ts b/src/main/runtime/orchestration/db-stopping-worker-task-guard.test.ts index 21816c4492a..a747ae07a51 100644 --- a/src/main/runtime/orchestration/db-stopping-worker-task-guard.test.ts +++ b/src/main/runtime/orchestration/db-stopping-worker-task-guard.test.ts @@ -12,7 +12,7 @@ describe('a Task whose supervised worker is stopping', () => { afterEach(() => db.close()) function localWorker() { - const task = db.createTask({ spec: 'local work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'local work' }) const { dispatch } = db.createStartingWorkerDispatch({ taskId: task.id, startOptions: {}, @@ -59,7 +59,7 @@ describe('a Task whose supervised worker is stopping', () => { }) it('control: still accepts dispatched for an active Dispatch with no supervised worker', () => { - const task = db.createTask({ spec: 'unsupervised work' }) + const task = db.createTask({ runId: 'run_legacy_local', spec: 'unsupervised work' }) createRootDispatch(db, task.id, 'term_worker') expect(db.updateTaskStatus(task.id, 'dispatched')?.status).toBe('dispatched') diff --git a/src/main/runtime/orchestration/db/worker-dispatch/worker-terminal-recovery.ts b/src/main/runtime/orchestration/db/worker-dispatch/worker-terminal-recovery.ts index 97179eb0185..410318bf9c6 100644 --- a/src/main/runtime/orchestration/db/worker-dispatch/worker-terminal-recovery.ts +++ b/src/main/runtime/orchestration/db/worker-dispatch/worker-terminal-recovery.ts @@ -9,7 +9,6 @@ import { DISPATCH_CIRCUIT_BREAK_FAILURES } from '../dispatch-context/dispatch-ci import type { OrchestrationDb } from '../orchestration-db' import { reconcileTaskAfterDispatchInterruption } from '../dispatch-context/task-dispatch-reconciliation' import { transitionLifecycleWithDb } from '../lifecycle-transition' -import { WORKER_SETTLED_STATES } from '../../worker-terminal-ownership' export function listLegacyWorkerTerminalRecoveryRows( this: OrchestrationDb @@ -23,18 +22,9 @@ export function listLegacyWorkerTerminalRecoveryRows( FROM dispatch_contexts dc INNER JOIN worker_dispatches wd ON wd.dispatch_id = dc.id WHERE wd.state IN ('starting', 'ready', 'start_unknown', 'stopping', 'stop_unknown') - -- A settled worker whose terminal orchestration still owns keeps a resumable agent - -- session; it needs the resume fence until release or retain retires the pane. - OR (wd.state IN (${WORKER_SETTLED_STATES.map(() => '?').join(', ')}) - AND EXISTS ( - SELECT 1 FROM worker_terminal_resources wtr - WHERE wtr.owner_dispatch_id = dc.id - AND wtr.ownership_state = 'owned' - AND wtr.release_state NOT IN ('released', 'retained') - )) ORDER BY dc.rowid` ) - .all(...WORKER_SETTLED_STATES) as LegacyWorkerTerminalRecoveryRow[] + .all() as LegacyWorkerTerminalRecoveryRow[] } export function reconcileMissingWorkerTerminal( diff --git a/src/main/runtime/orchestration/db/worker-terminal/worker-terminal-resource-store.ts b/src/main/runtime/orchestration/db/worker-terminal/worker-terminal-resource-store.ts index 1d7232107b1..e6942503dbf 100644 --- a/src/main/runtime/orchestration/db/worker-terminal/worker-terminal-resource-store.ts +++ b/src/main/runtime/orchestration/db/worker-terminal/worker-terminal-resource-store.ts @@ -2,6 +2,7 @@ import type { WorkerTerminalResourceRow, WorkerTerminalOwnershipState } from '../../worker-terminal-ownership' +import { WORKER_SETTLED_STATES } from '../../worker-terminal-ownership' import { OrchestrationError } from '../../orchestration-error' import { generateId } from '../generated-id' import type { OrchestrationDb } from '../orchestration-db' @@ -199,9 +200,40 @@ export function transferWorkerTerminalResourceStatement( return this.getWorkerTerminalResource(params.resourceId) as WorkerTerminalResourceRow } +// A new process in the same pane is ordinary user work, not the settled Dispatch's resource. +export function retainReplacedWorkerTerminalResources( + this: OrchestrationDb, + params: { paneKey: string; worktreeId: string; hostScope: string; processIncarnation: string } +): number { + return Number( + this.db + .prepare( + `UPDATE worker_terminal_resources + SET release_state = 'retained', retained_reason = 'identity_unproven', + updated_at = datetime('now') + WHERE pane_key = ? AND worktree_id = ? AND host_scope = ? + AND process_incarnation IS NOT NULL AND process_incarnation != ? + AND ownership_state = 'owned' AND release_state = 'not_requested' + AND EXISTS ( + SELECT 1 FROM worker_dispatches w + WHERE w.dispatch_id = worker_terminal_resources.owner_dispatch_id + AND w.state IN (${WORKER_SETTLED_STATES.map(() => '?').join(', ')}) + )` + ) + .run( + params.paneKey, + params.worktreeId, + params.hostScope, + params.processIncarnation, + ...WORKER_SETTLED_STATES + ).changes + ) +} + // Finds an owned, settled, exact-match resource for an explicitly reused terminal. export type WorkerTerminalResourceStoreMethods = { + retainReplacedWorkerTerminalResources: typeof retainReplacedWorkerTerminalResources backfillWorkerTerminalResources: typeof backfillWorkerTerminalResources createWorkerTerminalResourceStatement: typeof createWorkerTerminalResourceStatement getWorkerTerminalResource: typeof getWorkerTerminalResource @@ -214,6 +246,7 @@ export type WorkerTerminalResourceStoreMethods = { export function attachWorkerTerminalResourceStore(ctor: { prototype: object }): void { Object.assign(ctor.prototype, { + retainReplacedWorkerTerminalResources, backfillWorkerTerminalResources, createWorkerTerminalResourceStatement, getWorkerTerminalResource, diff --git a/src/main/runtime/orchestration/orchestration-legacy-worker-terminal-recovery.test.ts b/src/main/runtime/orchestration/orchestration-legacy-worker-terminal-recovery.test.ts index abb0b7bdfcc..7d0f0931263 100644 --- a/src/main/runtime/orchestration/orchestration-legacy-worker-terminal-recovery.test.ts +++ b/src/main/runtime/orchestration/orchestration-legacy-worker-terminal-recovery.test.ts @@ -26,14 +26,6 @@ function recoveryRow( describe('legacy worker terminal recovery planning', () => { it('retains completed Dispatches when the worker process row is still live', () => { expect(planLegacyWorkerTerminalRecovery([recoveryRow()])).toEqual({ - blockedPanes: [ - { - worktreeId: 'repo::/workspace', - paneKey: `tab-worker:${LEAF_ID}`, - contractVersion: 0, - settled: false - } - ], candidates: [ expect.objectContaining({ dispatchId: 'dispatch-1', @@ -45,18 +37,10 @@ describe('legacy worker terminal recovery planning', () => { }) }) - it('blocks resume but refuses recovery when durable handles disagree', () => { + it('refuses recovery when durable handles disagree', () => { expect( planLegacyWorkerTerminalRecovery([recoveryRow({ agent_terminal_handle: 'term-replacement' })]) ).toEqual({ - blockedPanes: [ - { - worktreeId: 'repo::/workspace', - paneKey: `tab-worker:${LEAF_ID}`, - contractVersion: 0, - settled: false - } - ], candidates: [], ambiguousDispatchIds: [] }) @@ -70,8 +54,6 @@ describe('legacy worker terminal recovery planning', () => { expect(plan.candidates).toEqual([expect.objectContaining({ dispatchId: 'dispatch-live' })]) expect(plan.ambiguousDispatchIds).toEqual([]) - // A live dispatch still holds this pane, so it must not be reported as a settled fence. - expect(plan.blockedPanes).toEqual([expect.objectContaining({ settled: false })]) }) it('fails closed when two Dispatches claim one terminal identity', () => { @@ -82,7 +64,6 @@ describe('legacy worker terminal recovery planning', () => { expect(plan.candidates).toEqual([]) expect(plan.ambiguousDispatchIds).toEqual(['dispatch-1', 'dispatch-2']) - expect(plan.blockedPanes).toHaveLength(1) }) it('does not trust malformed pane or process identities', () => { @@ -94,7 +75,6 @@ describe('legacy worker terminal recovery planning', () => { ]) expect(plan).toEqual({ - blockedPanes: [], candidates: [], ambiguousDispatchIds: [] }) diff --git a/src/main/runtime/orchestration/orchestration-legacy-worker-terminal-recovery.ts b/src/main/runtime/orchestration/orchestration-legacy-worker-terminal-recovery.ts index 8b1426cb07e..7a159a89ea0 100644 --- a/src/main/runtime/orchestration/orchestration-legacy-worker-terminal-recovery.ts +++ b/src/main/runtime/orchestration/orchestration-legacy-worker-terminal-recovery.ts @@ -19,16 +19,7 @@ export type LegacyWorkerTerminalRecoveryCandidate = { incarnationId: PtyIncarnationId } -export type LegacyWorkerTerminalRecoveryBlockedPane = { - worktreeId: string - paneKey: string - contractVersion: number - /** The dispatch reported an outcome; its pane needs the fence but owns no process to recover. */ - settled: boolean -} - export type LegacyWorkerTerminalRecoveryPlan = { - blockedPanes: LegacyWorkerTerminalRecoveryBlockedPane[] candidates: LegacyWorkerTerminalRecoveryCandidate[] ambiguousDispatchIds: string[] } @@ -65,26 +56,13 @@ function countCandidateKeys( export function planLegacyWorkerTerminalRecovery( rows: readonly LegacyWorkerTerminalRecoveryRow[] ): LegacyWorkerTerminalRecoveryPlan { - const blockedPanes = new Map() const parsedCandidates: LegacyWorkerTerminalRecoveryCandidate[] = [] for (const row of rows) { const worktreeId = row.worktree_id?.trim() const paneKey = row.assignee_pane_key?.trim() const pane = paneKey ? parsePaneKey(paneKey) : null const settled = WORKER_SETTLED_STATES.includes(row.worker_state) - if (worktreeId && paneKey && pane) { - const blockedKey = `${worktreeId}\0${paneKey}` - const alreadySettled = blockedPanes.get(blockedKey)?.settled - blockedPanes.set(blockedKey, { - worktreeId, - paneKey, - contractVersion: row.contract_version, - // A pane reused across dispatches is settled only once every dispatch holding it is. - settled: (alreadySettled ?? true) && settled - }) - } - // A settled worker owns no live process to adopt or roll back, so its identity must never - // compete with a running worker's in the ambiguity count below. + // Settled dispatches need no adoption and must not make an active worker's identity ambiguous. if (settled) { continue } @@ -134,7 +112,6 @@ export function planLegacyWorkerTerminalRecovery( return !ambiguous }) return { - blockedPanes: [...blockedPanes.values()], candidates, ambiguousDispatchIds: [...ambiguousDispatchIds] } diff --git a/src/main/runtime/orchestration/orchestration-settled-worker-resume-fence-db.test.ts b/src/main/runtime/orchestration/orchestration-settled-worker-resume-fence-db.test.ts deleted file mode 100644 index 5cde241093d..00000000000 --- a/src/main/runtime/orchestration/orchestration-settled-worker-resume-fence-db.test.ts +++ /dev/null @@ -1,124 +0,0 @@ -import { afterEach, describe, expect, it } from 'vitest' -import { OrchestrationDb } from './db' -import { planLegacyWorkerTerminalRecovery } from './orchestration-legacy-worker-terminal-recovery' -import type { WorkerTerminalResourceRow } from './worker-terminal-ownership' - -const PANE_KEY = 'tab_worker:33333333-3333-4333-8333-333333333333' - -describe('settled worker terminal resume fence rows', () => { - let db: OrchestrationDb | undefined - - afterEach(() => db?.close()) - - function createReadyWorker(): { db: OrchestrationDb; taskId: string; dispatchId: string } { - const d = new OrchestrationDb(':memory:') - db = d - const task = d.createTask({ runId: 'run_legacy_local', spec: 'settled worker' }) - const started = d.createStartingWorkerDispatch({ - creator: { kind: 'system' }, - maxDepth: Number.MAX_SAFE_INTEGER, - taskId: task.id, - startOptions: {} - }) - d.prepareStartingWorkerAuthority({ - dispatchId: started.dispatch.id, - handle: 'term_worker', - paneKey: PANE_KEY, - processIncarnation: 'runtime:pty:1', - worktreeId: 'repo::worktree', - setupState: 'not_applicable', - effects: [], - terminalOwnership: 'created' - }) - d.markWorkerDispatchReady(started.dispatch.id) - return { db: d, taskId: task.id, dispatchId: started.dispatch.id } - } - - /** Asserts the `requested` arm so the resource row is non-null for the caller. */ - function requestRelease(d: OrchestrationDb, dispatchId: string): WorkerTerminalResourceRow { - const requested = d.requestWorkerTerminalRelease(dispatchId) - if (requested.disposition !== 'requested') { - throw new Error(`expected a release request, got ${requested.disposition}`) - } - return requested.resource - } - - function settle(d: OrchestrationDb, taskId: string, dispatchId: string): void { - expect( - d.settleWorkerReport({ - taskId, - dispatchId, - outcome: 'succeeded', - result: 'worker succeeded' - }).action - ).toBe('settled') - } - - it('keeps a settled-but-unreleased worker terminal in the recovery rows', () => { - const { db: d, taskId, dispatchId } = createReadyWorker() - settle(d, taskId, dispatchId) - - expect(d.getWorkerDispatch(dispatchId)?.state).toBe('succeeded') - expect(d.listLegacyWorkerTerminalRecoveryRows()).toEqual([ - expect.objectContaining({ - dispatch_id: dispatchId, - worker_state: 'succeeded', - assignee_pane_key: PANE_KEY - }) - ]) - }) - - // A settled worker owns no live process, so it must only fence — never be offered for adoption. - it('plans a settled pane as a fence with no adoption candidate', () => { - const { db: d, taskId, dispatchId } = createReadyWorker() - settle(d, taskId, dispatchId) - - const plan = planLegacyWorkerTerminalRecovery(d.listLegacyWorkerTerminalRecoveryRows()) - - expect(plan.blockedPanes).toEqual([ - expect.objectContaining({ paneKey: PANE_KEY, settled: true }) - ]) - expect(plan.candidates).toEqual([]) - expect(plan.ambiguousDispatchIds).toEqual([]) - }) - - // `release_unknown` is the ticket's own repro: release could not be proven, the pane keeps a - // resumable provider session, and dropping it here would re-open the auto-resume. - it('keeps a settled worker terminal whose release could not be proven', () => { - const { db: d, taskId, dispatchId } = createReadyWorker() - settle(d, taskId, dispatchId) - const resource = requestRelease(d, dispatchId) - expect( - d.markWorkerTerminalReleaseUnknown(resource.id, 'terminal no longer resolves').release_state - ).toBe('unknown') - - expect(d.listLegacyWorkerTerminalRecoveryRows()).toEqual([ - expect.objectContaining({ dispatch_id: dispatchId, assignee_pane_key: PANE_KEY }) - ]) - }) - - it('drops a settled worker terminal once its resource is released', () => { - const { db: d, taskId, dispatchId } = createReadyWorker() - settle(d, taskId, dispatchId) - const resource = requestRelease(d, dispatchId) - expect(d.settleWorkerTerminalRelease(resource.id).release_state).toBe('released') - - expect(d.listLegacyWorkerTerminalRecoveryRows()).toEqual([]) - }) - - it('drops a settled worker terminal the user chose to retain', () => { - const { db: d, taskId, dispatchId } = createReadyWorker() - d.retainWorkerTerminalResource(dispatchId) - settle(d, taskId, dispatchId) - - expect(d.listLegacyWorkerTerminalRecoveryRows()).toEqual([]) - }) - - it('drops a settled worker terminal the user took over', () => { - const { db: d, taskId, dispatchId } = createReadyWorker() - settle(d, taskId, dispatchId) - expect(d.markWorkerTerminalUserOwned(PANE_KEY)).toBe(1) - - expect(d.listLegacyWorkerTerminalRecoveryRows()).toEqual([]) - }) -}) diff --git a/src/main/runtime/rpc/methods/orchestration.ts b/src/main/runtime/rpc/methods/orchestration.ts index fbc8f263cd0..ed89ae4519d 100644 --- a/src/main/runtime/rpc/methods/orchestration.ts +++ b/src/main/runtime/rpc/methods/orchestration.ts @@ -1,5 +1,4 @@ import type { RpcMethod } from '../core' -import { sweepingSettledWorkerResumeFences } from './settled-worker-resume-fence-sweep' import { ORCHESTRATION_RUN_METHODS } from './orchestration/runs/runs' import { ORCHESTRATION_WORKER_METHODS } from './orchestration/worker/worker-methods' import { ORCHESTRATION_FEDERATION_METHODS } from './orchestration/federation/federation-methods' @@ -24,4 +23,4 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [ ...ORCHESTRATION_ASK_METHODS, ...ORCHESTRATION_GATE_METHODS, ...ORCHESTRATION_RESET_METHODS -].map(sweepingSettledWorkerResumeFences) +] diff --git a/src/main/runtime/rpc/methods/orchestration/messaging/send-point-to-point.ts b/src/main/runtime/rpc/methods/orchestration/messaging/send-point-to-point.ts index c7386acd49f..807e709003a 100644 --- a/src/main/runtime/rpc/methods/orchestration/messaging/send-point-to-point.ts +++ b/src/main/runtime/rpc/methods/orchestration/messaging/send-point-to-point.ts @@ -7,7 +7,6 @@ import type { SendParams } from '../schemas' import { legacyWorkerDeliveryContract } from '../routing' import { exposeMessage } from './mailbox-message-receipt' import { recordReceiptForPostCommitNudge } from './mutation-replay-nudge' -import { sweepSettledWorkerResumeFences } from '../../settled-worker-resume-fence-sweep' import type { SendRecipientWarning } from './recipient-routing' import type { z } from 'zod' @@ -150,11 +149,6 @@ export function sendPointToPointMessage(args: { ? db.commitWorkerDoneMessageMutation(commitMessage) : commitMessage() committed.nudge() - if (messageType === 'worker_done') { - // Settlement is what makes the pane fenceable; without this the fence only appeared at the - // next app start and reopening the pane in the same session respawned the agent. - sweepSettledWorkerResumeFences(runtime) - } return committed.receipt } diff --git a/src/main/runtime/rpc/methods/orchestration/worker/worker-release.test.ts b/src/main/runtime/rpc/methods/orchestration/worker/worker-release.test.ts index 5207b83c8de..e6466ed48c4 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/worker-release.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/worker-release.test.ts @@ -322,18 +322,36 @@ describe('orchestration worker release', () => { expect(h.db.getWorkerTerminalResourceByOwner(dispatchId)?.ownership_state).toBe('user_owned') }) - it('retains when the exact process identity changed instead of closing', async () => { + it('keeps a resumed settled worker retained in worker-list without re-dispatch or release', async () => { h.setup() - const { dispatchId } = await h.startSettledWorker() + const { dispatchId, taskId } = await h.startSettledWorker() + const dispatch = h.db.getDispatchContextById(dispatchId) + const task = h.db.getTask(taskId) + vi.mocked(h.runtime.createTerminal).mockClear() + vi.mocked(h.runtime.sendTerminalAgentPrompt).mockClear() vi.mocked(h.runtime.getTerminalProcessIncarnation).mockImplementation((handle) => handle === 'term_worker' ? 'runtime_test:term_worker:2' : null ) - const receipt = (await h.call('orchestration.workerRelease', { dispatch: dispatchId })) as { - state: string - reason?: string + + await expect( + h.call('orchestration.workerRelease', { dispatch: dispatchId }) + ).resolves.toMatchObject({ + state: 'retained', + reason: 'identity_unproven', + processAction: 'none' + }) + const listed = (await h.call('orchestration.workerList', { run: h.activeRunId })) as { + workers: { dispatchId: string; terminalState: string; workerState: string }[] } - expect(receipt).toMatchObject({ state: 'retained', reason: 'identity_unproven' }) + expect(listed.workers).toEqual([ + expect.objectContaining({ dispatchId, terminalState: 'retained', workerState: 'succeeded' }) + ]) + expect(h.db.getTask(taskId)).toEqual(task) + expect(h.db.getDispatchContextById(dispatchId)).toEqual(dispatch) + expect(h.db.getWorkerTerminalResourceByOwner(dispatchId)?.release_state).toBe('retained') expect(h.runtime.closeTerminal).not.toHaveBeenCalled() + expect(h.runtime.createTerminal).not.toHaveBeenCalled() + expect(h.runtime.sendTerminalAgentPrompt).not.toHaveBeenCalled() }) it('retains when the terminal host scope changed instead of closing', async () => { diff --git a/src/main/runtime/rpc/methods/orchestration/worker/worker-release.ts b/src/main/runtime/rpc/methods/orchestration/worker/worker-release.ts index 2a24a3efd0e..5d219d76591 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/worker-release.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/worker-release.ts @@ -10,7 +10,6 @@ import { type WorkerReleaseReceipt } from './worker-release-completion' import { WorkerDispatchParams, WorkerRetainParams } from './worker-release-schemas' -import { sweepSettledWorkerResumeFences } from '../../settled-worker-resume-fence-sweep' export const ORCHESTRATION_WORKER_RELEASE_METHODS: RpcMethod[] = [ defineMethod({ @@ -148,11 +147,6 @@ export const ORCHESTRATION_WORKER_RELEASE_METHODS: RpcMethod[] = [ const changed = paneKey ? runtime.getOrchestrationDb().markWorkerTerminalUserOwned(paneKey) : 0 - if (changed > 0) { - // Only a real takeover retires the resource; ordinary panes report here too and must not - // pay for a plan read on every keystroke window. - sweepSettledWorkerResumeFences(runtime) - } return { changed } } }) diff --git a/src/main/runtime/rpc/methods/settled-worker-resume-fence-sweep.ts b/src/main/runtime/rpc/methods/settled-worker-resume-fence-sweep.ts deleted file mode 100644 index e3aac0e5803..00000000000 --- a/src/main/runtime/rpc/methods/settled-worker-resume-fence-sweep.ts +++ /dev/null @@ -1,45 +0,0 @@ -import type { OrcaRuntimeService } from '../../orca-runtime' -import type { RpcMethod } from '../core' - -/** - * One pass both stamps the automatic-resume fence on every settled worker pane and lifts it from - * every pane the recovery plan no longer claims. A fenced pane refuses a fresh spawn, so any path - * that drops a worker's row from that plan — release, user retain, user takeover — has to run the - * sweep in the same call, or the fence outlives its dispatch and the pane stays unspawnable until - * the next app start. Failures are swallowed: a fence sweep must never fail the RPC behind it. - */ -export function sweepSettledWorkerResumeFences(runtime: OrcaRuntimeService): void { - try { - runtime.prepareLegacyWorkerTerminalRecovery() - } catch (error) { - console.warn('[orchestration] settled worker resume fence sweep failed', error) - } -} - -/** Settling a worker is what makes its pane fenceable, and release/retain/takeover are what make it - * unfenceable again — so every one of those has to sweep in the same call. Without the settlement - * half the fence only appeared at the next app start, and reopening the pane in the same session - * respawned the agent. */ -const FENCE_SWEEPING_METHOD_NAMES = new Set([ - 'orchestration.workerRelease', - 'orchestration.workerRetain', - 'orchestration.workerStop', - 'orchestration.workerAbandon', - // Reusing a settled worker's pane for a new Dispatch drops the old row from the plan; without - // this the stale fence stays on the pane it just relaunched into. - 'orchestration.workerStart' -]) - -export function sweepingSettledWorkerResumeFences(method: RpcMethod): RpcMethod { - if (!FENCE_SWEEPING_METHOD_NAMES.has(method.name)) { - return method - } - return { - ...method, - handler: async (params, ctx) => { - const result = await method.handler(params, ctx) - sweepSettledWorkerResumeFences(ctx.runtime) - return result - } - } -} diff --git a/src/main/runtime/runtime-legacy-worker-terminal-recovery-controller.ts b/src/main/runtime/runtime-legacy-worker-terminal-recovery-controller.ts index cbb28e20336..ce034d8e349 100644 --- a/src/main/runtime/runtime-legacy-worker-terminal-recovery-controller.ts +++ b/src/main/runtime/runtime-legacy-worker-terminal-recovery-controller.ts @@ -22,10 +22,6 @@ export class RuntimeLegacyWorkerTerminalRecoveryController { constructor(private readonly ports: LegacyWorkerRecoveryPorts) {} - prepare(): LegacyWorkerTerminalRecoveryPlan { - return this.ports.preparePlan() - } - reconcile( options: LegacyWorkerRecoveryOptions = {} ): Promise { diff --git a/src/main/runtime/runtime-legacy-worker-terminal-recovery-persistence.ts b/src/main/runtime/runtime-legacy-worker-terminal-recovery-persistence.ts index 613718de7e5..df794567737 100644 --- a/src/main/runtime/runtime-legacy-worker-terminal-recovery-persistence.ts +++ b/src/main/runtime/runtime-legacy-worker-terminal-recovery-persistence.ts @@ -1,4 +1,4 @@ -import { LOCAL_EXECUTION_HOST_ID, type ExecutionHostId } from '../../shared/execution-host' +import type { ExecutionHostId } from '../../shared/execution-host' import type { WorkspaceSessionState } from '../../shared/workspace-session-state-types' import { retireTerminalSurfaceFromPersistence } from './mobile-session-terminal-persistence-retirement' import type { OrchestrationDb } from './orchestration/db' @@ -18,144 +18,11 @@ export class RuntimeLegacyWorkerTerminalRecoveryPersistence { constructor( private readonly getStore: () => RuntimeStore | null, private readonly getDb: () => OrchestrationDb, - private readonly getHostId: (worktreeId: string) => ExecutionHostId | null, - /** The store write only reaches the next app start; a live renderer holds its own copy. */ - private readonly notifyFenceChanged?: (paneKey: string, blocked: boolean) => void + private readonly getHostId: (worktreeId: string) => ExecutionHostId | null ) {} - /** Panes announced as fenced before any sleeping record existed; the only place a lift for one - * can come from, because `liftRetiredFences` can only see panes that already have a record. */ - private readonly announcedBlockedPaneKeys = new Set() - prepare(): LegacyWorkerTerminalRecoveryPlan { - const plan = this.getPlan() - if (!plan) { - // An unreadable plan is not evidence that any pane stopped needing its fence: stamp - // nothing, lift nothing, retry on the next pass. - return { blockedPanes: [], candidates: [], ambiguousDispatchIds: [] } - } - const store = this.getStore() - if ( - !store?.getWorkspaceSession || - !store.setWorkspaceSession || - (!store.flushPendingOrThrowAsync && !store.flushOrThrow) - ) { - return plan - } - const sessions = new Map< - ExecutionHostId, - { current: WorkspaceSessionState; next: WorkspaceSessionState } - >() - const changedHostIds = new Set() - const fenceChanges: [string, boolean][] = [] - for (const blocked of plan.blockedPanes) { - // A worker can settle while its tab is still open, so there is no sleeping record to stamp - // yet. Tell the live renderer anyway: it mints the record on close and must fence it there. - if (!this.announcedBlockedPaneKeys.has(blocked.paneKey)) { - this.announcedBlockedPaneKeys.add(blocked.paneKey) - fenceChanges.push([blocked.paneKey, true]) - } - let hostIds: ExecutionHostId[] - try { - const hostId = this.getHostId(blocked.worktreeId) - if (!hostId) { - throw new Error('folder_workspace_not_found') - } - hostIds = [hostId] - } catch (error) { - console.warn('[orchestration] legacy worker resume fence owner is unavailable', { - worktreeId: blocked.worktreeId, - error - }) - hostIds = store.getWorkspaceSessionHostIds?.() ?? [LOCAL_EXECUTION_HOST_ID] - } - for (const hostId of hostIds) { - let state = sessions.get(hostId) - if (!state) { - const current = store.getWorkspaceSession(hostId) - if (!current) { - continue - } - state = { current, next: structuredClone(current) } - sessions.set(hostId, state) - } - const record = state.next.sleepingAgentSessionsByPaneKey?.[blocked.paneKey] - if ( - !record || - !runtimeWorktreeIdsEqual(record.worktreeId, blocked.worktreeId) || - record.automaticResumeBlockedBy === 'legacy-orchestration-worker' - ) { - continue - } - state.next.sleepingAgentSessionsByPaneKey = { - ...state.next.sleepingAgentSessionsByPaneKey, - [blocked.paneKey]: { ...record, automaticResumeBlockedBy: 'legacy-orchestration-worker' } - } - changedHostIds.add(hostId) - } - } - this.liftRetiredFences(store, plan, sessions, changedHostIds, fenceChanges) - const changed = [...sessions].filter(([hostId]) => changedHostIds.has(hostId)) - try { - for (const [hostId, state] of changed) { - store.setWorkspaceSession(state.next, hostId) - } - } catch (error) { - console.warn('[orchestration] failed to stage legacy worker resume fence', error) - return plan - } - for (const [paneKey, blocked] of fenceChanges) { - this.notifyFenceChanged?.(paneKey, blocked) - } - return plan - } - - /** A fence that outlives its dispatch leaves a pane that can never spawn again, so release, - * retain, user takeover and dispatch pruning — each of which drops the row from the plan — - * retire it here. An unreadable plan yields no blocked panes, so callers must not sweep. */ - private liftRetiredFences( - store: RuntimeStore, - plan: LegacyWorkerTerminalRecoveryPlan, - sessions: Map, - changedHostIds: Set, - fenceChanges: [string, boolean][] - ): void { - const blockedPaneKeys = new Set(plan.blockedPanes.map((blocked) => blocked.paneKey)) - for (const paneKey of this.announcedBlockedPaneKeys) { - if (!blockedPaneKeys.has(paneKey)) { - this.announcedBlockedPaneKeys.delete(paneKey) - fenceChanges.push([paneKey, false]) - } - } - for (const hostId of store.getWorkspaceSessionHostIds?.() ?? [LOCAL_EXECUTION_HOST_ID]) { - const staged = sessions.get(hostId) - const session = staged?.next ?? store.getWorkspaceSession?.(hostId) - const retired = Object.entries(session?.sleepingAgentSessionsByPaneKey ?? {}).filter( - ([paneKey, record]) => - record.automaticResumeBlockedBy === 'legacy-orchestration-worker' && - !blockedPaneKeys.has(paneKey) - ) - if (retired.length === 0) { - continue - } - let state = staged - if (!state) { - const current = store.getWorkspaceSession?.(hostId) - if (!current) { - continue - } - state = { current, next: structuredClone(current) } - sessions.set(hostId, state) - } - const next = { ...state.next.sleepingAgentSessionsByPaneKey } - for (const [paneKey, record] of retired) { - const { automaticResumeBlockedBy: _retired, ...unfenced } = record - next[paneKey] = unfenced - fenceChanges.push([paneKey, false]) - } - state.next.sleepingAgentSessionsByPaneKey = next - changedHostIds.add(hostId) - } + return this.getPlan() ?? { candidates: [], ambiguousDispatchIds: [] } } async persist( diff --git a/src/main/runtime/runtime-legacy-worker-terminal-recovery-runner.ts b/src/main/runtime/runtime-legacy-worker-terminal-recovery-runner.ts index bd15abc7d4d..6bbe3b2ed2f 100644 --- a/src/main/runtime/runtime-legacy-worker-terminal-recovery-runner.ts +++ b/src/main/runtime/runtime-legacy-worker-terminal-recovery-runner.ts @@ -104,7 +104,6 @@ export async function runLegacyWorkerTerminalRecovery( exitedDispatchIds.push(candidate.dispatchId) } const result = { - blockedPaneCount: plan.blockedPanes.length, adoptedDispatchIds, exitedDispatchIds, deferredDispatchIds: [...deferredDispatchIds] diff --git a/src/main/runtime/runtime-legacy-worker-terminal-recovery-types.ts b/src/main/runtime/runtime-legacy-worker-terminal-recovery-types.ts index c65afd73952..16ca330647c 100644 --- a/src/main/runtime/runtime-legacy-worker-terminal-recovery-types.ts +++ b/src/main/runtime/runtime-legacy-worker-terminal-recovery-types.ts @@ -5,7 +5,6 @@ import type { PtyControllerInventory } from './runtime-pty-controller-contract' import type { ResolvedWorktree } from './runtime-worktree-path-identity' export type LegacyWorkerTerminalRecoveryResult = { - blockedPaneCount: number adoptedDispatchIds: string[] exitedDispatchIds: string[] deferredDispatchIds: string[] diff --git a/src/main/runtime/runtime-legacy-worker-terminal-resume-fence.test.ts b/src/main/runtime/runtime-legacy-worker-terminal-resume-fence.test.ts deleted file mode 100644 index 4d1f81869d5..00000000000 --- a/src/main/runtime/runtime-legacy-worker-terminal-resume-fence.test.ts +++ /dev/null @@ -1,286 +0,0 @@ -import { afterEach, describe, expect, it, vi } from 'vitest' -import { getDefaultWorkspaceSession } from '../../shared/constants' -import { LOCAL_EXECUTION_HOST_ID } from '../../shared/execution-host' -import type { WorkspaceSessionState } from '../../shared/workspace-session-state-types' -import { OrchestrationDb } from './orchestration/db' -import { OrcaRuntimeService } from './orca-runtime' -import { ORCHESTRATION_METHODS } from './rpc/methods/orchestration' -import { RuntimeLegacyWorkerTerminalRecoveryPersistence } from './runtime-legacy-worker-terminal-recovery-persistence' -import type { RuntimeStore } from './runtime-store-contract' - -const PANE_KEY = 'tab_worker:33333333-3333-4333-8333-333333333333' -const WORKTREE_ID = 'repo::worktree' - -function sessionWithSleepingWorker(): WorkspaceSessionState { - return { - ...getDefaultWorkspaceSession(), - sleepingAgentSessionsByPaneKey: { - [PANE_KEY]: { - paneKey: PANE_KEY, - tabId: 'tab_worker', - worktreeId: WORKTREE_ID, - agent: 'codex', - providerSession: { key: 'session_id', id: 'codex-session-1' }, - prompt: '', - state: 'done', - capturedAt: 1, - updatedAt: 1, - origin: 'live' - } - } - } as WorkspaceSessionState -} - -describe('settled worker automatic-resume fence persistence', () => { - let db: OrchestrationDb | undefined - - afterEach(() => db?.close()) - - function harness( - onFenceChanged?: (paneKey: string, blocked: boolean) => void, - /** False models a worker that settles while its tab is still open: no record to stamp yet. */ - withSleepingRecord = true - ): { - db: OrchestrationDb - taskId: string - dispatchId: string - persistence: RuntimeLegacyWorkerTerminalRecoveryPersistence - fence: () => string | undefined - } { - const orchestrationDb = new OrchestrationDb(':memory:') - db = orchestrationDb - let session = withSleepingRecord - ? sessionWithSleepingWorker() - : (getDefaultWorkspaceSession() as WorkspaceSessionState) - const store = { - getWorkspaceSession: () => session, - setWorkspaceSession: (next: WorkspaceSessionState) => { - session = next - }, - getWorkspaceSessionHostIds: () => [LOCAL_EXECUTION_HOST_ID], - flushOrThrow: vi.fn() - } as unknown as RuntimeStore - const task = orchestrationDb.createTask({ runId: 'run_legacy_local', spec: 'fence me' }) - const started = orchestrationDb.createStartingWorkerDispatch({ - creator: { kind: 'system' }, - maxDepth: Number.MAX_SAFE_INTEGER, - taskId: task.id, - startOptions: {} - }) - orchestrationDb.prepareStartingWorkerAuthority({ - dispatchId: started.dispatch.id, - handle: 'term_worker', - paneKey: PANE_KEY, - processIncarnation: 'runtime:pty:1', - worktreeId: WORKTREE_ID, - setupState: 'not_applicable', - effects: [], - terminalOwnership: 'created' - }) - orchestrationDb.markWorkerDispatchReady(started.dispatch.id) - return { - db: orchestrationDb, - taskId: task.id, - dispatchId: started.dispatch.id, - persistence: new RuntimeLegacyWorkerTerminalRecoveryPersistence( - () => store, - () => orchestrationDb, - () => LOCAL_EXECUTION_HOST_ID, - onFenceChanged - ), - fence: () => session.sleepingAgentSessionsByPaneKey?.[PANE_KEY]?.automaticResumeBlockedBy - } - } - - function settle(d: OrchestrationDb, taskId: string, dispatchId: string): void { - expect( - d.settleWorkerReport({ taskId, dispatchId, outcome: 'succeeded', result: 'done' }).action - ).toBe('settled') - } - - it('pushes the fence to the live renderer instead of waiting for the next app start', () => { - const fenceChanges: [string, boolean][] = [] - const h = harness((paneKey, blocked) => fenceChanges.push([paneKey, blocked])) - settle(h.db, h.taskId, h.dispatchId) - - h.persistence.prepare() - - expect(fenceChanges).toEqual([[PANE_KEY, true]]) - }) - - it('announces the fence for a pane that has no sleeping record to stamp yet', () => { - const fenceChanges: [string, boolean][] = [] - const h = harness((paneKey, blocked) => fenceChanges.push([paneKey, blocked]), false) - settle(h.db, h.taskId, h.dispatchId) - - h.persistence.prepare() - expect(fenceChanges).toEqual([[PANE_KEY, true]]) - - const requested = h.db.requestWorkerTerminalRelease(h.dispatchId) - h.db.settleWorkerTerminalRelease((requested as { resource: { id: string } }).resource.id) - h.persistence.prepare() - - // A fence the plan no longer claims must be lifted even with no record to read it from. - expect(fenceChanges).toEqual([ - [PANE_KEY, true], - [PANE_KEY, false] - ]) - }) - - // The STA-4577 repro: worker_done, no release, restart, open the worktree — the pane still - // holds a resumable provider session and must not respawn `codex resume`. - it('fences a settled worker pane whose terminal was never released', () => { - const h = harness() - settle(h.db, h.taskId, h.dispatchId) - - h.persistence.prepare() - - expect(h.fence()).toBe('legacy-orchestration-worker') - }) - - it('lifts the fence once release retires the terminal resource', () => { - const h = harness() - settle(h.db, h.taskId, h.dispatchId) - h.persistence.prepare() - expect(h.fence()).toBe('legacy-orchestration-worker') - - const requested = h.db.requestWorkerTerminalRelease(h.dispatchId) - expect(requested.disposition).toBe('requested') - h.db.settleWorkerTerminalRelease((requested as { resource: { id: string } }).resource.id) - h.persistence.prepare() - - expect(h.fence()).toBeUndefined() - }) - - it('lifts the fence when the user takes the pane over', () => { - const h = harness() - settle(h.db, h.taskId, h.dispatchId) - h.persistence.prepare() - expect(h.fence()).toBe('legacy-orchestration-worker') - - expect(h.db.markWorkerTerminalUserOwned(PANE_KEY)).toBe(1) - h.persistence.prepare() - - expect(h.fence()).toBeUndefined() - }) - - // An unreadable plan is not evidence a pane stopped needing its fence. - it('keeps the fence when the recovery plan cannot be read', () => { - const h = harness() - settle(h.db, h.taskId, h.dispatchId) - h.persistence.prepare() - expect(h.fence()).toBe('legacy-orchestration-worker') - - vi.spyOn(h.db, 'listLegacyWorkerTerminalRecoveryRows').mockImplementation(() => { - throw new Error('orchestration_db_unavailable') - }) - const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) - try { - expect(h.persistence.prepare()).toEqual({ - blockedPanes: [], - candidates: [], - ambiguousDispatchIds: [] - }) - } finally { - warn.mockRestore() - } - - expect(h.fence()).toBe('legacy-orchestration-worker') - }) - - // A live worker's pane was already fenced while main reconciles it against PTY inventory; the - // settled arm must not disturb that, and the plan must still name it as unsettled. - it('keeps a live worker pane fenced and marked unsettled', () => { - const h = harness() - - const plan = h.persistence.prepare() - - expect(h.fence()).toBe('legacy-orchestration-worker') - expect(plan.blockedPanes).toEqual([ - expect.objectContaining({ paneKey: PANE_KEY, settled: false }) - ]) - expect(plan.candidates).toEqual([expect.objectContaining({ dispatchId: h.dispatchId })]) - }) -}) - -// STA-4577's other half: settlement with no release and no restart. The stamp only ran at startup -// and after release/retain/takeover, so reopening the pane in the same session respawned the agent. -describe('worker_done without a release', () => { - let db: OrchestrationDb | undefined - - afterEach(() => db?.close()) - - it('fences the pane in the same session', async () => { - const orchestrationDb = new OrchestrationDb(':memory:') - db = orchestrationDb - let session = sessionWithSleepingWorker() - const store = { - getWorkspaceSession: () => session, - setWorkspaceSession: (next: WorkspaceSessionState) => { - session = next - }, - getWorkspaceSessionHostIds: () => [LOCAL_EXECUTION_HOST_ID], - flushOrThrow: vi.fn() - } as unknown as RuntimeStore - const runtime = new OrcaRuntimeService(store) - runtime.setOrchestrationDb(orchestrationDb) - vi.spyOn(runtime, 'getTerminalPaneKey').mockImplementation((handle) => - handle === 'term_worker' ? PANE_KEY : 'tab_coord:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa' - ) - vi.spyOn(runtime, 'getTerminalProcessIncarnation').mockReturnValue('runtime:pty:1') - vi.spyOn(runtime, 'notifyMessageArrived').mockImplementation(() => {}) - - const run = orchestrationDb.createRun({ - objective: 'settle without release', - coordinatorHandle: 'term_coord', - coordinatorPaneKey: 'tab_coord:aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa' - }) - const task = orchestrationDb.createTask({ spec: 'settle without release', runId: run.id }) - const started = orchestrationDb.createStartingWorkerDispatch({ - creator: { kind: 'system' }, - maxDepth: Number.MAX_SAFE_INTEGER, - taskId: task.id, - startOptions: {} - }) - orchestrationDb.prepareStartingWorkerAuthority({ - dispatchId: started.dispatch.id, - handle: 'term_worker', - paneKey: PANE_KEY, - processIncarnation: 'runtime:pty:1', - worktreeId: WORKTREE_ID, - setupState: 'not_applicable', - effects: [], - terminalOwnership: 'created' - }) - orchestrationDb.markWorkerDispatchReady(started.dispatch.id) - const capability = orchestrationDb.mintDispatchCapability({ - dispatchId: started.dispatch.id, - paneKey: PANE_KEY, - processIncarnation: 'runtime:pty:1' - }) - expect(session.sleepingAgentSessionsByPaneKey?.[PANE_KEY]?.automaticResumeBlockedBy).toBe( - undefined - ) - - const send = ORCHESTRATION_METHODS.find((method) => method.name === 'orchestration.send')! - await send.handler( - send.params!.parse({ - from: 'term_worker', - to: 'term_coord', - subject: 'Done', - type: 'worker_done', - payload: JSON.stringify({ - taskId: task.id, - dispatchId: started.dispatch.id, - outcome: 'succeeded' - }) - }), - { runtime, orchestrationCapability: capability } - ) - - expect(orchestrationDb.getWorkerDispatch(started.dispatch.id)?.state).toBe('succeeded') - expect(session.sleepingAgentSessionsByPaneKey?.[PANE_KEY]?.automaticResumeBlockedBy).toBe( - 'legacy-orchestration-worker' - ) - }) -}) diff --git a/src/main/runtime/runtime-notifier-contract.ts b/src/main/runtime/runtime-notifier-contract.ts index aa2982082b4..9cdc365e1ba 100644 --- a/src/main/runtime/runtime-notifier-contract.ts +++ b/src/main/runtime/runtime-notifier-contract.ts @@ -80,7 +80,6 @@ export type RuntimeNotifier = { ptyId?: string ): void /** The fence lives in the workspace session, which a live renderer only re-reads at startup. */ - setLegacyWorkerTerminalResumeFence?(paneKey: string, blocked: boolean): void splitTerminal( tabId: string, paneRuntimeId: number, diff --git a/src/main/runtime/settled-worker-process-replacement.test.ts b/src/main/runtime/settled-worker-process-replacement.test.ts new file mode 100644 index 00000000000..2e575cd4546 --- /dev/null +++ b/src/main/runtime/settled-worker-process-replacement.test.ts @@ -0,0 +1,111 @@ +import { afterEach, describe, expect, it } from 'vitest' +import { OrcaRuntimeService } from './orca-runtime' +import { OrchestrationDb } from './orchestration/db' + +const TAB = 'worker-tab' +const LEAF = '11111111-1111-4111-8111-111111111111' +const PANE = `${TAB}:${LEAF}` +const WORKSPACE = '/folder-workspace' +const LOCAL_HOST = JSON.stringify({ kind: 'local', hostId: 'local' }) +const SSH_HOST = JSON.stringify({ kind: 'ssh', targetId: 'remote-host' }) +let db: OrchestrationDb +let runtime: OrcaRuntimeService + +afterEach(() => { + db?.close() +}) + +function seedWorker(hostScope: string, settled = true) { + db = new OrchestrationDb(':memory:') + runtime = new OrcaRuntimeService(null) + runtime.setOrchestrationDb(db) + const started = db.createStartingWorkerDispatch({ + creator: { kind: 'system' }, + maxDepth: Number.MAX_SAFE_INTEGER, + taskSpec: 'Ordinary pane after worker completion', + taskRunId: 'run_legacy_local', + startOptions: {} + }) + db.prepareStartingWorkerAuthority({ + dispatchId: started.dispatch.id, + handle: 'term_original', + paneKey: PANE, + processIncarnation: 'pty-original:inc-original', + hostScope, + worktreeId: WORKSPACE, + setupState: 'not_applicable', + effects: [], + terminalOwnership: 'created' + }) + db.markWorkerDispatchReady(started.dispatch.id) + if (settled) { + db.settleWorkerReport({ + taskId: started.task.id, + dispatchId: started.dispatch.id, + outcome: 'succeeded', + result: '{}' + }) + } + return { + dispatchId: started.dispatch.id, + task: db.getTask(started.task.id), + dispatch: db.getDispatchContextById(started.dispatch.id) + } +} + +function register(ptyId: string, incarnationId?: string, connectionId: string | null = null) { + runtime.registerPty(ptyId, WORKSPACE, connectionId, { + tabId: TAB, + leafId: LEAF, + ...(incarnationId ? { incarnationId } : {}) + }) +} + +describe('settled worker process replacement accounting', () => { + it.each([null, 'remote-host'])( + 'retains the replaced resource on owning host %s', + (connectionId) => { + const worker = seedWorker(connectionId ? SSH_HOST : LOCAL_HOST) + register('pty-resumed', 'inc-resumed', connectionId) + register('pty-resumed', 'inc-resumed', connectionId) + expect(db.getWorkerTerminalResourceByOwner(worker.dispatchId)).toMatchObject({ + release_state: 'retained', + retained_reason: 'identity_unproven', + process_incarnation: 'pty-original:inc-original' + }) + expect(db.getTask(worker.task!.id)).toEqual(worker.task) + expect(db.getDispatchContextById(worker.dispatchId)).toEqual(worker.dispatch) + expect(db.listWorkerTerminalResources({})).toEqual([ + expect.objectContaining({ dispatchId: worker.dispatchId, terminalState: 'retained' }) + ]) + } + ) + + it('keeps the original live resource unchanged across reattach', () => { + const worker = seedWorker(LOCAL_HOST) + const original = db.getWorkerTerminalResourceByOwner(worker.dispatchId) + register('pty-original', 'inc-original') + expect(db.getWorkerTerminalResourceByOwner(worker.dispatchId)).toEqual(original) + }) + + it('does not use missing incarnation evidence as proof of replacement', () => { + const worker = seedWorker(LOCAL_HOST) + const original = db.getWorkerTerminalResourceByOwner(worker.dispatchId) + register('pty-unverifiable') + expect(db.getWorkerTerminalResourceByOwner(worker.dispatchId)).toEqual(original) + }) + + it('does not change another execution host with the same pane and folder', () => { + const worker = seedWorker(SSH_HOST) + const original = db.getWorkerTerminalResourceByOwner(worker.dispatchId) + register('pty-resumed', 'inc-resumed') + expect(db.getWorkerTerminalResourceByOwner(worker.dispatchId)).toEqual(original) + }) + + it('does not change an active Dispatch resource', () => { + const worker = seedWorker(LOCAL_HOST, false) + const original = db.getWorkerTerminalResourceByOwner(worker.dispatchId) + register('pty-resumed', 'inc-resumed') + expect(db.getWorkerTerminalResourceByOwner(worker.dispatchId)).toEqual(original) + }) +}) diff --git a/src/main/startup/main-process-runtime-service.ts b/src/main/startup/main-process-runtime-service.ts index a684e951bc3..1b7f69213ad 100644 --- a/src/main/startup/main-process-runtime-service.ts +++ b/src/main/startup/main-process-runtime-service.ts @@ -129,7 +129,6 @@ export function initializeMainProcessRuntime(): OrcaRuntimeService { agentHookServer.subscribeEnrichedStatus((enriched) => recordObservedAgentStatusPaneIdentity(observedPaneIdentities, enriched.paneKey, runtime) ) - runtime.prepareLegacyWorkerTerminalRecovery() // Why before anything can attach: a client host that reattaches to a restarted runtime is only // handed its pages back if the runtime found them first. runtime.rehydrateClientHostedBrowserPages() diff --git a/src/main/window/runtime-window-lifecycle.ts b/src/main/window/runtime-window-lifecycle.ts index 2a6ab95a07f..78c5f2ec426 100644 --- a/src/main/window/runtime-window-lifecycle.ts +++ b/src/main/window/runtime-window-lifecycle.ts @@ -149,8 +149,6 @@ export function registerRuntimeWindowLifecycle( resolution, ...(ptyId ? { ptyId } : {}) }), - setLegacyWorkerTerminalResumeFence: (paneKey, blocked) => - send('agentStatus:legacyWorkerTerminalResumeFence', { paneKey, blocked }), splitTerminal: (tabId, paneRuntimeId, opts) => { send('ui:splitTerminal', { tabId, diff --git a/src/preload/api/agent-status-api.ts b/src/preload/api/agent-status-api.ts index 89677022506..7aa6c21115d 100644 --- a/src/preload/api/agent-status-api.ts +++ b/src/preload/api/agent-status-api.ts @@ -28,10 +28,6 @@ export type AgentStatusApi = { ptyId?: string }) => void ) => () => void - /** Listen for the automatic-resume fence a settled worker's pane gains or loses mid-session. */ - onLegacyWorkerTerminalResumeFence: ( - callback: (data: { paneKey: string; blocked: boolean }) => void - ) => () => void getMigrationUnsupportedSnapshot: () => Promise /** Drop a paneKey from the main-process hook cache and on-disk last-status file. Fire-and-forget. */ drop: (paneKey: string) => void diff --git a/src/preload/api/agent-status-bridge.ts b/src/preload/api/agent-status-bridge.ts index 3c3415cd207..3cc1654aaed 100644 --- a/src/preload/api/agent-status-bridge.ts +++ b/src/preload/api/agent-status-bridge.ts @@ -61,16 +61,6 @@ export const agentStatusApi = { ipcRenderer.on('agentStatus:legacyWorkerTerminalRecovery', listener) return () => ipcRenderer.removeListener('agentStatus:legacyWorkerTerminalRecovery', listener) }, - onLegacyWorkerTerminalResumeFence: ( - callback: (data: { paneKey: string; blocked: boolean }) => void - ): (() => void) => { - const listener = ( - _event: Electron.IpcRendererEvent, - data: { paneKey: string; blocked: boolean } - ) => callback(data) - ipcRenderer.on('agentStatus:legacyWorkerTerminalResumeFence', listener) - return () => ipcRenderer.removeListener('agentStatus:legacyWorkerTerminalResumeFence', listener) - }, getMigrationUnsupportedSnapshot: (): Promise => ipcRenderer.invoke('agentStatus:getMigrationUnsupportedSnapshot'), /** Drop the cached hook status for a paneKey on both sides (memory + on-disk) so a relaunch can't resurrect a dismissed row. */ diff --git a/src/renderer/src/components/terminal-pane/pty-connection-agent-session-resume.test.ts b/src/renderer/src/components/terminal-pane/pty-connection-agent-session-resume.test.ts index c93294ba2f9..9fec98aa409 100644 --- a/src/renderer/src/components/terminal-pane/pty-connection-agent-session-resume.test.ts +++ b/src/renderer/src/components/terminal-pane/pty-connection-agent-session-resume.test.ts @@ -1,7 +1,6 @@ import type * as React from 'react' import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import { makePaneKey } from '../../../../shared/stable-pane-id' -import { toAppSshPtyId } from '../../../../shared/ssh-pty-id' import { flushAsyncTicks } from './pty-connection-test-async' import { UUID_RE } from './pty-connection-test-constants' import { @@ -406,177 +405,81 @@ describe('connectPanePty', () => { expect(mockStoreState.clearSleepingAgentSession).not.toHaveBeenCalled() }) - it('does not resume a live provider session while legacy worker recovery owns the pane', async () => { - const { connectPanePty } = await import('./pty-connection') - const retainedPtyId = 'wt-1@@lost-pty' - const transport = createMockTransport() - transport.connect.mockImplementation(async ({ sessionId }: { sessionId?: string }) => - sessionId - ? { - id: 'fresh-pty', - coldRestore: { scrollback: 'cold-payload', cwd: '/tmp/wt-1' } + it.each(['ordinary', 'settled-worker'])( + 'restores %s through main with one resume command', + async (kind) => { + const { connectPanePty } = await import('./pty-connection') + const retainedPtyId = 'wt-1@@lost-pty' + const transport = createMockTransport() + transport.connect.mockImplementation(async ({ sessionId }: { sessionId?: string }) => + sessionId + ? { + id: 'fresh-pty', + coldRestore: { scrollback: 'cold-payload', cwd: '/tmp/wt-1' } + } + : 'fresh-pty' + ) + transportFactoryQueue.push(transport) + const paneKey = makePaneKey('tab-1', LEAF_1) + mockStoreState = { + ...mockStoreState, + tabsByWorktree: { + 'wt-1': [{ id: 'tab-1', ptyId: retainedPtyId }] + }, + settings: { + ...mockStoreState.settings, + agentCmdOverrides: {} + }, + agentStatusByPaneKey: { + [paneKey]: { + paneKey, + state: 'working', + prompt: 'finish the task', + agentType: 'claude', + providerSession: { key: 'session_id', id: 'claude-session-1' } + } + }, + sleepingAgentSessionsByPaneKey: { + [paneKey]: { + paneKey, + tabId: 'tab-1', + worktreeId: 'wt-1', + agent: 'claude', + providerSession: { key: 'session_id', id: 'claude-session-1' }, + prompt: 'finish the task', + state: 'working', + capturedAt: 1, + updatedAt: 1, + ...(kind === 'settled-worker' + ? { automaticResumeBlockedBy: 'legacy-orchestration-worker' } + : {}) } - : 'fresh-pty' - ) - transportFactoryQueue.push(transport) - const paneKey = makePaneKey('tab-1', LEAF_1) - mockStoreState = { - ...mockStoreState, - tabsByWorktree: { - 'wt-1': [{ id: 'tab-1', ptyId: retainedPtyId }] - }, - settings: { - ...mockStoreState.settings, - agentCmdOverrides: {} - }, - agentStatusByPaneKey: { - [paneKey]: { - paneKey, - state: 'working', - prompt: 'finish the task', - agentType: 'codex', - providerSession: { key: 'session_id', id: 'codex-session-1' } - } - }, - sleepingAgentSessionsByPaneKey: { - [paneKey]: { - paneKey, - tabId: 'tab-1', - worktreeId: 'wt-1', - agent: 'codex', - providerSession: { key: 'session_id', id: 'codex-session-1' }, - prompt: 'finish the task', - state: 'working', - capturedAt: 1, - updatedAt: 1, - automaticResumeBlockedBy: 'legacy-orchestration-worker' } + } as StoreState + + connectPanePty( + createPane(1) as never, + createManager(1) as never, + createDeps({ + restoredLeafId: LEAF_1, + restoredPtyIdByLeafId: { [LEAF_1]: retainedPtyId } + }) as never + ) + await flushAsyncTicks(20) + await new Promise((resolve) => setTimeout(resolve, 70)) + + expect(transport.connect).toHaveBeenCalledTimes(1) + expect(transport.attach).not.toHaveBeenCalled() + const options = transport.connect.mock.calls[0]?.[0] as { + sessionId?: string + command?: string } - } as StoreState - - connectPanePty( - createPane(1) as never, - createManager(1) as never, - createDeps({ - restoredLeafId: LEAF_1, - restoredPtyIdByLeafId: { [LEAF_1]: retainedPtyId } - }) as never - ) - await flushAsyncTicks(20) - await new Promise((resolve) => setTimeout(resolve, 70)) - - expect(transport.connect).not.toHaveBeenCalled() - expect(transport.attach).toHaveBeenCalledWith( - expect.objectContaining({ existingPtyId: retainedPtyId }) - ) - const attachOptions = transport.attach.mock.calls[0]?.[0] as Record - expect(attachOptions).not.toHaveProperty('cols') - expect(attachOptions).not.toHaveProperty('rows') - expect(mockStoreState.registerAgentLaunchConfig).not.toHaveBeenCalled() - expect(mockStoreState.clearSleepingAgentSession).not.toHaveBeenCalled() - }) - - it('does not replace a missing retained legacy worker over direct SSH', async () => { - const { connectPanePty } = await import('./pty-connection') - const retainedPtyId = toAppSshPtyId('ssh-a', 'missing-legacy-worker') - const transport = createMockTransport() - transport.getConnectionId.mockReturnValue('ssh-a') - transport.attach.mockImplementation(() => { - throw new Error('remote PTY missing') - }) - transportFactoryQueue.push(transport) - const paneKey = makePaneKey('tab-1', LEAF_1) - mockStoreState = { - ...mockStoreState, - tabsByWorktree: { - 'wt-1': [{ id: 'tab-1', ptyId: retainedPtyId }] - }, - repos: [{ id: 'repo1', connectionId: 'ssh-a' }], - sshConnectionStates: new Map([['ssh-a', { status: 'connected' }]]), - sleepingAgentSessionsByPaneKey: { - [paneKey]: { - paneKey, - tabId: 'tab-1', - worktreeId: 'wt-1', - agent: 'codex', - providerSession: { key: 'session_id', id: 'codex-session-1' }, - prompt: 'finish the task', - state: 'working', - capturedAt: 1, - updatedAt: 1, - automaticResumeBlockedBy: 'legacy-orchestration-worker' - } - } - } as StoreState - const deps = createDeps({ - restoredLeafId: LEAF_1, - restoredPtyIdByLeafId: { [LEAF_1]: retainedPtyId } - }) - - connectPanePty(createPane(1) as never, createManager(1) as never, deps as never) - await flushAsyncTicks(20) - await new Promise((resolve) => setTimeout(resolve, 70)) - - expect(transport.attach).toHaveBeenCalledWith( - expect.objectContaining({ existingPtyId: retainedPtyId }) - ) - expect(transport.connect).not.toHaveBeenCalled() - expect(deps.clearTabPtyId).not.toHaveBeenCalled() - expect(mockStoreState.registerAgentLaunchConfig).not.toHaveBeenCalled() - }) - - it('preserves a missing retained legacy worker through direct SSH reconnect', async () => { - const { connectPanePty } = await import('./pty-connection') - const retainedPtyId = toAppSshPtyId('ssh-a', 'missing-legacy-worker') - const transport = createMockTransport() - transport.getConnectionId.mockReturnValue('ssh-a') - transport.attach.mockImplementation(() => { - throw new Error('remote PTY missing') - }) - transportFactoryQueue.push(transport) - const paneKey = makePaneKey('tab-1', LEAF_1) - mockStoreState = { - ...mockStoreState, - tabsByWorktree: { - 'wt-1': [{ id: 'tab-1', ptyId: retainedPtyId }] - }, - repos: [{ id: 'repo1', connectionId: 'ssh-a' }], - sshConnectionStates: new Map([['ssh-a', { status: 'disconnected' }]]), - deferredSshReconnectTargets: ['ssh-a'], - deferredSshSessionIdsByTabId: { 'tab-1': retainedPtyId }, - sleepingAgentSessionsByPaneKey: { - [paneKey]: { - paneKey, - tabId: 'tab-1', - worktreeId: 'wt-1', - agent: 'codex', - providerSession: { key: 'session_id', id: 'codex-session-1' }, - prompt: 'finish the task', - state: 'working', - capturedAt: 1, - updatedAt: 1, - automaticResumeBlockedBy: 'legacy-orchestration-worker' - } - } - } as StoreState - const deps = createDeps({ - restoredLeafId: LEAF_1, - restoredPtyIdByLeafId: { [LEAF_1]: retainedPtyId } - }) - - connectPanePty(createPane(1) as never, createManager(1) as never, deps as never) - await flushAsyncTicks(20) - await new Promise((resolve) => setTimeout(resolve, 70)) - - expect(window.api.ssh.connect).toHaveBeenCalledWith({ targetId: 'ssh-a' }) - expect(transport.attach).toHaveBeenCalledWith( - expect.objectContaining({ existingPtyId: retainedPtyId }) - ) - expect(transport.connect).not.toHaveBeenCalled() - expect(mockStoreState.removeDeferredSshSessionId).not.toHaveBeenCalled() - expect(deps.clearTabPtyId).not.toHaveBeenCalled() - expect(mockStoreState.registerAgentLaunchConfig).not.toHaveBeenCalled() - }) + expect(options.sessionId).toBe(retainedPtyId) + expect(options.command).toContain('claude-session-1') + expect(options.command?.match(/--resume/g)).toHaveLength(1) + expect(mockStoreState.tabsByWorktree['wt-1']).toHaveLength(1) + } + ) it('ignores stale live launch config when cold restore identity lookup rejects it', async () => { const { connectPanePty } = await import('./pty-connection') diff --git a/src/renderer/src/components/terminal-pane/pty-connection/cold-restore-resume-startup.ts b/src/renderer/src/components/terminal-pane/pty-connection/cold-restore-resume-startup.ts index 3e4ab1e38d5..c719e4a83ef 100644 --- a/src/renderer/src/components/terminal-pane/pty-connection/cold-restore-resume-startup.ts +++ b/src/renderer/src/components/terminal-pane/pty-connection/cold-restore-resume-startup.ts @@ -25,9 +25,7 @@ export function bindBuildColdRestoreAgentResumeStartup(session: ConnectPanePtySe const entry = state.agentStatusByPaneKey[session.cacheKey] const sleepingRecordEntry = session.getSleepingRecordForPane(state) const sleepingRecord = sleepingRecordEntry?.record - if (session.isLegacyWorkerAutomaticResumeBlocked()) { - return null - } + const useLiveEntry = entry && entry.state !== 'done' const agent = useLiveEntry ? entry.agentType : sleepingRecord?.agent if (!agent || !isResumableTuiAgent(agent)) { diff --git a/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-attach.ts b/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-attach.ts index 1b05fa09e60..726744b7729 100644 --- a/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-attach.ts +++ b/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-attach.ts @@ -1,4 +1,3 @@ -import { scheduleRuntimeGraphSync } from '@/runtime/sync-runtime-graph' import { useAppStore } from '@/store' import { isRuntimeOwnedSshTargetId } from '../../../../../shared/execution-host' import { resolveSshPaneConnectGate } from '../ssh-pane-connect-gate' @@ -61,8 +60,7 @@ export function runDeferredSessionAttach(session: ConnectPanePtySession): void { console.warn( `[pty-connection] SSH tab=${session.deps.tabId} connectionId=${session.connectionId} pendingSessionId=${pendingSessionId} sshConnected=${gate.sshConnected}` ) - const legacyWorkerOwnsPane = session.isLegacyWorkerAutomaticResumeBlocked() - if (gate.enterDeferredFlow && (!legacyWorkerOwnsPane || !gate.sshConnected)) { + if (gate.enterDeferredFlow) { // Paint main's parked model while SSH recovery continues off the render path. session.prepaintParkedSshSnapshot(pendingSessionId) void (async () => { @@ -115,13 +113,6 @@ export function runDeferredSessionAttach(session: ConnectPanePtySession): void { } useAppStore.getState().removeDeferredSshReconnectTarget(session.connectionId) if (pendingSessionId) { - if (session.isLegacyWorkerAutomaticResumeBlocked()) { - if (session.attachRetainedLegacyPty(pendingSessionId)) { - useAppStore.getState().removeDeferredSshSessionId(session.deps.tabId) - scheduleRuntimeGraphSync() - } - return - } console.warn( `[pty-connection] Attempting reattach for tab=${session.deps.tabId} sessionId=${pendingSessionId}` ) diff --git a/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-reattach-choice.ts b/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-reattach-choice.ts index bb4eab2444c..f56f3c54f6c 100644 --- a/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-reattach-choice.ts +++ b/src/renderer/src/components/terminal-pane/pty-connection/deferred-session-reattach-choice.ts @@ -89,9 +89,6 @@ export function runDeferredSessionReattachChoice(session: ConnectPanePtySession) : null // Why: after a daemon crash + cold restore, a stale session-to-tab mapping can make a tab hold a ptyId from another worktree. // Restoring it would paint the wrong terminal content, so drop the reattach and spawn fresh. - const legacyAttachOnlyPtyId = session.isLegacyWorkerAutomaticResumeBlocked() - ? candidateReattachSessionId - : null const pairedParkedReattachSessionId = session.mountFollowsTerminalPark && candidateReattachSessionId && @@ -99,64 +96,51 @@ export function runDeferredSessionReattachChoice(session: ConnectPanePtySession) canRestorePairedParkedTerminal(candidateReattachSessionId) ? candidateReattachSessionId : null - const deferredReattachSessionId = legacyAttachOnlyPtyId - ? null - : (runtimeHostPtyWakeHint ?? - pairedParkedReattachSessionId ?? - (candidateReattachSessionId && - !isRemoteRuntimePtyId(candidateReattachSessionId) && - !candidateHasEagerBuffer && - isSessionOwnedByWorktree(candidateReattachSessionId, session.deps.worktreeId) - ? candidateReattachSessionId - : null)) + const deferredReattachSessionId = + runtimeHostPtyWakeHint ?? + pairedParkedReattachSessionId ?? + (candidateReattachSessionId && + !isRemoteRuntimePtyId(candidateReattachSessionId) && + !candidateHasEagerBuffer && + isSessionOwnedByWorktree(candidateReattachSessionId, session.deps.worktreeId) + ? candidateReattachSessionId + : null) recordPtyConnectDiagnostic( `pane=${session.pane.id} tab=${session.deps.tabId} restored=${restoredPtyId} existing=${existingPtyId} detached=${detachedRemoteLeafPtyId ?? detachedLivePtyId} reattach=${deferredReattachSessionId} hasTransport=${session.hadExistingPaneTransportAtConnect} pendingKey=${session.pendingSpawnKey}` ) if (deferredReattachSessionId) { startDeferredSessionReattach(session, deferredReattachSessionId) - } else if ( - legacyAttachOnlyPtyId || - detachedRemoteLeafPtyId || - detachedLivePtyId || - eagerLivePtyId - ) { + } else if (detachedRemoteLeafPtyId || detachedLivePtyId || eagerLivePtyId) { // Why: mirrored web-leaf panes must attach to their exact remote PTY, not spawn a replacement host tab. // eagerLivePtyId covers a still-live background PTY (e.g. an automation agent) with a live eager buffer to adopt. - const attachPtyId = - legacyAttachOnlyPtyId ?? detachedRemoteLeafPtyId ?? detachedLivePtyId ?? eagerLivePtyId! + const attachPtyId = detachedRemoteLeafPtyId ?? detachedLivePtyId ?? eagerLivePtyId! recordPtyConnectDiagnostic(`pane=${session.pane.id} -> ATTACH detached=${attachPtyId}`) session.allowInitialIdleCacheSeed = false - if (legacyAttachOnlyPtyId) { - if (session.attachRetainedLegacyPty(legacyAttachOnlyPtyId) && session.connectionId) { - useAppStore.getState().removeDeferredSshSessionId(session.deps.tabId) - } - } else { - // Why: surface synchronous attach failures via session.reportError so the pane shows a diagnostic instead of a blank surface. - // On throw, clear the stale ptyId from the tab and fresh-spawn — else the next remount reads the same dead id and loops here. - try { - session.clearPaneMode2031State() - session.clearHiddenOutputRestoreState() - const outputCallbacks = session.captureTransportOutputCallbacks(session.reportError, null) - session.transport.attach({ - existingPtyId: attachPtyId, - cols: session.cols, - rows: session.rows, - callbacks: outputCallbacks.callbacks - }) - const attachedPtyId = session.transport.getPtyId() ?? attachPtyId - session.bindActivePanePty(attachedPtyId, { - updateTabPtyId: 'if-missing', - sampleVisibleForegroundAgent: true - }) - if (attachPtyId === eagerLivePtyId || isRemoteRuntimePtyId(attachedPtyId)) { - session.registerPaneSerializerFor(attachedPtyId) - } - } catch (err) { - session.reportError(err instanceof Error ? err.message : String(err)) - session.deps.clearTabPtyId(session.deps.tabId, attachPtyId) - session.startFreshSpawn() + // Why: surface synchronous attach failures via session.reportError so the pane shows a diagnostic instead of a blank surface. + // On throw, clear the stale ptyId from the tab and fresh-spawn — else the next remount reads the same dead id and loops here. + try { + session.clearPaneMode2031State() + session.clearHiddenOutputRestoreState() + const outputCallbacks = session.captureTransportOutputCallbacks(session.reportError, null) + session.transport.attach({ + existingPtyId: attachPtyId, + cols: session.cols, + rows: session.rows, + callbacks: outputCallbacks.callbacks + }) + const attachedPtyId = session.transport.getPtyId() ?? attachPtyId + session.bindActivePanePty(attachedPtyId, { + updateTabPtyId: 'if-missing', + sampleVisibleForegroundAgent: true + }) + if (attachPtyId === eagerLivePtyId || isRemoteRuntimePtyId(attachedPtyId)) { + session.registerPaneSerializerFor(attachedPtyId) } + } catch (err) { + session.reportError(err instanceof Error ? err.message : String(err)) + session.deps.clearTabPtyId(session.deps.tabId, attachPtyId) + session.startFreshSpawn() } } else { session.allowInitialIdleCacheSeed = false diff --git a/src/renderer/src/components/terminal-pane/pty-connection/fresh-spawn-start.ts b/src/renderer/src/components/terminal-pane/pty-connection/fresh-spawn-start.ts index f3dab2d5425..b1319e3137c 100644 --- a/src/renderer/src/components/terminal-pane/pty-connection/fresh-spawn-start.ts +++ b/src/renderer/src/components/terminal-pane/pty-connection/fresh-spawn-start.ts @@ -34,10 +34,7 @@ export function bindStartFreshSpawn(session: ConnectPanePtySession): void { } } } - if (session.isLegacyWorkerAutomaticResumeBlocked()) { - releaseDeferredCwdFence() - return Promise.resolve(null) - } + if (useAppStore.getState().deleteStateByWorktreeId?.[session.deps.worktreeId]?.isDeleting) { // Why: the worktree is being deleted; its PTYs were just killed for the // filesystem teardown. A fresh shell must not spawn into a directory the diff --git a/src/renderer/src/components/terminal-pane/pty-connection/retained-legacy-pty-attach.ts b/src/renderer/src/components/terminal-pane/pty-connection/retained-legacy-pty-attach.ts deleted file mode 100644 index db1d277dcc3..00000000000 --- a/src/renderer/src/components/terminal-pane/pty-connection/retained-legacy-pty-attach.ts +++ /dev/null @@ -1,30 +0,0 @@ -import { isRemoteRuntimePtyId } from './paired-parked-terminal-restore' - -import type { ConnectPanePtySession } from './connect-pane-pty-session' - -export function bindAttachRetainedLegacyPty(session: ConnectPanePtySession): void { - session.attachRetainedLegacyPty = (ptyId: string): boolean => { - try { - session.authoritativeReattachGeneration += 1 - session.clearPaneMode2031State() - session.clearHiddenOutputRestoreState() - const outputCallbacks = session.captureTransportOutputCallbacks(session.reportError, null) - session.transport.attach({ - existingPtyId: ptyId, - callbacks: outputCallbacks.callbacks - }) - const attachedPtyId = session.transport.getPtyId() ?? ptyId - session.bindActivePanePty(attachedPtyId, { - updateTabPtyId: 'if-missing', - sampleVisibleForegroundAgent: true - }) - if (isRemoteRuntimePtyId(attachedPtyId)) { - session.registerPaneSerializerFor(attachedPtyId) - } - return true - } catch (err) { - session.reportError(err instanceof Error ? err.message : String(err)) - return false - } - } -} diff --git a/src/renderer/src/components/terminal-pane/pty-connection/run-deferred-connect.ts b/src/renderer/src/components/terminal-pane/pty-connection/run-deferred-connect.ts index efc1ef59b7c..120805f9d29 100644 --- a/src/renderer/src/components/terminal-pane/pty-connection/run-deferred-connect.ts +++ b/src/renderer/src/components/terminal-pane/pty-connection/run-deferred-connect.ts @@ -12,7 +12,6 @@ import { bindPrepaintParkedSshSnapshot } from './ssh-snapshot-prepaint' import { bindForegroundOutputRefresh } from './foreground-output-refresh' import { bindRegisterPaneSerializer } from './pane-serializer-register' import { bindHandleReattachResult } from './reattach-result-handler' -import { bindAttachRetainedLegacyPty } from './retained-legacy-pty-attach' import { runDeferredSessionAttach } from './deferred-session-attach' import { bindSerializeHiddenOutputSnapshot } from './hidden-output-snapshot-serialize' @@ -154,7 +153,6 @@ export function installRunDeferredConnect(session: ConnectPanePtySession): void bindPrepaintParkedSshSnapshot(session) bindHandleReattachResult(session) - bindAttachRetainedLegacyPty(session) runDeferredSessionAttach(session) } diff --git a/src/renderer/src/components/terminal-pane/pty-connection/sleeping-record-access.ts b/src/renderer/src/components/terminal-pane/pty-connection/sleeping-record-access.ts index 0777dead431..c756a29e80a 100644 --- a/src/renderer/src/components/terminal-pane/pty-connection/sleeping-record-access.ts +++ b/src/renderer/src/components/terminal-pane/pty-connection/sleeping-record-access.ts @@ -62,9 +62,6 @@ export function installSleepingRecordAccess(session: ConnectPanePtySession): voi const [paneKey, record] = selectedLegacyMatch return { paneKey, record } } - session.isLegacyWorkerAutomaticResumeBlocked = (): boolean => - session.getSleepingRecordForPane(useAppStore.getState())?.record.automaticResumeBlockedBy === - 'legacy-orchestration-worker' session.clearSleepingRecordProviderDuplicates = ( state: ReturnType, consumed: { paneKey: string; record: SleepingAgentSessionRecord } diff --git a/src/renderer/src/components/terminal-pane/sleeping-record-park-exemption.test.ts b/src/renderer/src/components/terminal-pane/sleeping-record-park-exemption.test.ts index 9c1c3512e5e..0d731bc07f0 100644 --- a/src/renderer/src/components/terminal-pane/sleeping-record-park-exemption.test.ts +++ b/src/renderer/src/components/terminal-pane/sleeping-record-park-exemption.test.ts @@ -43,20 +43,4 @@ describe('selectSleepingRecordParkExemptTabIds', () => { expect([...selectSleepingRecordParkExemptTabIds(records, 'wt-1')]).toEqual([]) }) - - it('skips records that cannot resume in this worktree', () => { - const records = { - [`tab-other:${LEAF_ID}`]: sleepingRecord({ - paneKey: `tab-other:${LEAF_ID}`, - worktreeId: 'wt-2' - }), - [`tab-done:${LEAF_ID}`]: sleepingRecord({ paneKey: `tab-done:${LEAF_ID}`, state: 'done' }), - [`tab-blocked:${LEAF_ID}`]: sleepingRecord({ - paneKey: `tab-blocked:${LEAF_ID}`, - automaticResumeBlockedBy: 'legacy-orchestration-worker' - }) - } - - expect([...selectSleepingRecordParkExemptTabIds(records, 'wt-1')]).toEqual([]) - }) }) diff --git a/src/renderer/src/components/terminal-pane/sleeping-record-park-exemption.ts b/src/renderer/src/components/terminal-pane/sleeping-record-park-exemption.ts index f38ee52bb80..5a2ccec0e2a 100644 --- a/src/renderer/src/components/terminal-pane/sleeping-record-park-exemption.ts +++ b/src/renderer/src/components/terminal-pane/sleeping-record-park-exemption.ts @@ -6,7 +6,7 @@ const EMPTY_TAB_IDS: ReadonlySet = new Set() /** Tab ids whose panes own a sleeping record a mount can actually consume. * Why: a parked pane can never cold-restore, so per-tab parks must exempt - * these — but only these: blocked and passive-completed records never resume, + * these — but only these: passive-completed records never resume, * and exempting them would pin a hidden pane mounted indefinitely. * Callers subscribe through `useShallow`, which compares the set structurally, * so a write for another worktree cannot re-render this one. Iterates in place — @@ -24,7 +24,7 @@ export function selectSleepingRecordParkExemptTabIds( if (!record || record.worktreeId !== worktreeId) { continue } - if (record.automaticResumeBlockedBy || isPassiveCompletedHibernationEvidence(record)) { + if (isPassiveCompletedHibernationEvidence(record)) { continue } // Why: malformed pane keys must yield no owner instead of a truncated tab id. diff --git a/src/renderer/src/components/terminal-pane/terminal-cold-park-subscription-narrowing.react185.test.tsx b/src/renderer/src/components/terminal-pane/terminal-cold-park-subscription-narrowing.react185.test.tsx index 81153a03ca6..98c0d4dc0cc 100644 --- a/src/renderer/src/components/terminal-pane/terminal-cold-park-subscription-narrowing.react185.test.tsx +++ b/src/renderer/src/components/terminal-pane/terminal-cold-park-subscription-narrowing.react185.test.tsx @@ -111,21 +111,6 @@ describe('cold-park store subscription narrowing', () => { expect(harness.renders).toBe(0) }) - // Why: a blocked record never resumes, so it leaves the exempt set — and the - // narrowed subscription's compared value — unchanged. - it('ignores a sleeping-session write this worktree can never resume', () => { - act(() => { - useAppStore.setState({ - sleepingAgentSessionsByPaneKey: { - 'tab-1:1': sleepingRecord('tab-1:1', WORKTREE_ID, { - automaticResumeBlockedBy: 'legacy-orchestration-worker' - }) - } - }) - }) - expect(harness.renders).toBe(0) - }) - it('still re-renders when this worktree gains a pending startup', () => { act(() => { useAppStore.setState({ diff --git a/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.test.ts b/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.test.ts index ec2611d19e0..586df3d71a6 100644 --- a/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.test.ts +++ b/src/renderer/src/components/terminal-pane/use-terminal-tab-cold-parking.test.ts @@ -528,43 +528,6 @@ describe('useTerminalTabColdParking measure-clock contract', () => { expect(result.current).toEqual(new Set(['tab-2'])) }) - // Why: blocked and passive-completed records never auto-resume, so exempting + // Why: passive-completed records never auto-resume, so exempting // them would pin a hidden pane mounted indefinitely for nothing. - it('keeps parking panes whose records cannot be consumed', () => { - const { result, rerender } = renderHook( - (args: ReturnType) => useTerminalTabColdParking(args), - { initialProps: hookArgs(false) } - ) - act(() => { - vi.advanceTimersByTime(TERMINAL_TAB_HOT_RETAIN_MS + 1) - }) - expect(result.current).toEqual(new Set(['tab-2'])) - - mocks.storeState.sleepingAgentSessionsByPaneKey = { - 'tab-2:22222222-2222-4222-8222-222222222222': { - paneKey: 'tab-2:22222222-2222-4222-8222-222222222222', - tabId: 'tab-2', - worktreeId: WORKTREE_ID, - automaticResumeBlockedBy: 'legacy-orchestration-worker' - } as never - } - act(() => { - rerender(hookArgs(false)) - }) - expect(result.current).toEqual(new Set(['tab-2'])) - - mocks.storeState.sleepingAgentSessionsByPaneKey = { - 'tab-2:22222222-2222-4222-8222-222222222222': { - paneKey: 'tab-2:22222222-2222-4222-8222-222222222222', - tabId: 'tab-2', - worktreeId: WORKTREE_ID, - origin: 'worktree-sleep', - state: 'done' - } as never - } - act(() => { - rerender(hookArgs(false)) - }) - expect(result.current).toEqual(new Set(['tab-2'])) - }) }) diff --git a/src/renderer/src/hooks/ipc-events/agent-status-listeners.ts b/src/renderer/src/hooks/ipc-events/agent-status-listeners.ts index 2426dcb932d..70b13e22a41 100644 --- a/src/renderer/src/hooks/ipc-events/agent-status-listeners.ts +++ b/src/renderer/src/hooks/ipc-events/agent-status-listeners.ts @@ -126,12 +126,4 @@ export function registerAgentStatusListeners(args: { if (unsubscribeLegacyWorkerTerminalRecovery) { unsubs.push(unsubscribeLegacyWorkerTerminalRecovery) } - const unsubscribeResumeFence = window.api.agentStatus.onLegacyWorkerTerminalResumeFence?.( - ({ paneKey, blocked }) => { - useAppStore.getState().setSleepingAgentAutomaticResumeBlocked(paneKey, blocked) - } - ) - if (unsubscribeResumeFence) { - unsubs.push(unsubscribeResumeFence) - } } diff --git a/src/renderer/src/hooks/useIpcEvents-agent-status-ssh-authority.test.ts b/src/renderer/src/hooks/useIpcEvents-agent-status-ssh-authority.test.ts index 4a3287e8477..bc6ec581586 100644 --- a/src/renderer/src/hooks/useIpcEvents-agent-status-ssh-authority.test.ts +++ b/src/renderer/src/hooks/useIpcEvents-agent-status-ssh-authority.test.ts @@ -19,13 +19,11 @@ describe('useIpcEvents agent status snapshot integration', () => { it('retires the exact sleeping record after adopted or exited legacy worker recovery', async () => { const clearSleepingAgentSession = vi.fn() - const setSleepingAgentAutomaticResumeBlocked = vi.fn() let listener: | ((data: { paneKey: string; resolution: 'adopted' | 'exited' }) => void) | undefined const storeState = buildStoreState({ - clearSleepingAgentSession, - setSleepingAgentAutomaticResumeBlocked + clearSleepingAgentSession }) stubReactSyncEffect() @@ -54,12 +52,10 @@ describe('useIpcEvents agent status snapshot integration', () => { listener?.({ paneKey: 'tab-adopted:leaf-adopted', resolution: 'adopted' }) expect(clearSleepingAgentSession).toHaveBeenCalledWith('tab-adopted:leaf-adopted') - expect(setSleepingAgentAutomaticResumeBlocked).not.toHaveBeenCalled() clearSleepingAgentSession.mockClear() listener?.({ paneKey: 'tab-exited:leaf-exited', resolution: 'exited' }) expect(clearSleepingAgentSession).toHaveBeenCalledWith('tab-exited:leaf-exited') - expect(setSleepingAgentAutomaticResumeBlocked).not.toHaveBeenCalled() }) it.each([ diff --git a/src/renderer/src/hooks/useIpcEvents-lifecycle.test.ts b/src/renderer/src/hooks/useIpcEvents-lifecycle.test.ts index 2ba4d506077..5991c40c4de 100644 --- a/src/renderer/src/hooks/useIpcEvents-lifecycle.test.ts +++ b/src/renderer/src/hooks/useIpcEvents-lifecycle.test.ts @@ -5,7 +5,6 @@ import { createHarnessStoreState } from './ipc-events-test-harness' const EXPECTED_DIRECT_CALLBACK_METHODS = [ 'agentStatus.onClear', 'agentStatus.onLegacyWorkerTerminalRecovery', - 'agentStatus.onLegacyWorkerTerminalResumeFence', 'agentStatus.onMigrationUnsupported', 'agentStatus.onMigrationUnsupportedClear', 'agentStatus.onSet', @@ -199,7 +198,6 @@ const EXPECTED_CALLBACK_REGISTRATION_SEQUENCE = [ 'agentStatus.onMigrationUnsupported', 'agentStatus.onMigrationUnsupportedClear', 'agentStatus.onLegacyWorkerTerminalRecovery', - 'agentStatus.onLegacyWorkerTerminalResumeFence', 'runtime.onTerminalFitOverrideChanged', 'runtime.onTerminalDriverChanged', 'runtime.onNativeChatLaunchDraftResolved', diff --git a/src/renderer/src/i18n/en-runtime-required.json b/src/renderer/src/i18n/en-runtime-required.json index a1c33b790bc..47024572e8c 100644 --- a/src/renderer/src/i18n/en-runtime-required.json +++ b/src/renderer/src/i18n/en-runtime-required.json @@ -1503,7 +1503,16 @@ "ask_before_closing_running_terminals_description": "Show a confirmation before closing a terminal that has a running command or agent.", "ask_before_closing_running_terminals_title": "Ask Before Closing Running Terminals", "cc8c5ca224": "Windows default", - "d78fc4fdef": "Loading distributions" + "d78fc4fdef": "Loading distributions", + "minimumContrast": { + "automatic": "Automatic: {{light}} on light backgrounds, {{dark}} on dark.", + "description": "Lifts terminal foreground colors that sit too close to the background. Leave blank for automatic, or set 1 to render program colors exactly as sent.", + "disabled": "Correction off. Programs that rely on low contrast, like Powerline separators, render as sent.", + "pinned": "Targets {{ratio}}:1 contrast for foreground colors, where possible.", + "placeholder": "Auto", + "suffix": "blank = automatic, 1 = off", + "title": "Minimum Contrast Ratio" + } }, "TerminalSettingsPreview": { "d06664e889": "dark" diff --git a/src/renderer/src/lib/agent-hibernation-pane-eligibility.ts b/src/renderer/src/lib/agent-hibernation-pane-eligibility.ts index 839209ea809..bc55936fd24 100644 --- a/src/renderer/src/lib/agent-hibernation-pane-eligibility.ts +++ b/src/renderer/src/lib/agent-hibernation-pane-eligibility.ts @@ -4,10 +4,7 @@ import { parsePaneKey } from '../../../shared/stable-pane-id' import type { TerminalLayoutSnapshot, TerminalTab } from '../../../shared/terminal-tab-types' import { parseRemoteRuntimePtyId } from '@/runtime/runtime-terminal-stream' import { lastInputBlocksHibernation } from './agent-hibernation-input-guard' -import { - isAutomaticHibernationAllowed, - isLiveResumeAnchorForCompletedAgent -} from './live-resume-anchor-record' +import { isLiveResumeAnchorForCompletedAgent } from './live-resume-anchor-record' import type { AgentHibernationPlannerSnapshot } from './agent-hibernation-planner-snapshot' export type EligiblePane = { @@ -95,10 +92,7 @@ export function getEligiblePane(args: { entry.interrupted === true || Boolean(entry.subagents?.length) || hasUnsettledOrUnknownDispatch(entry) || - (sleepingRecord && !hasOnlyLiveResumeAnchor) || - // Why: a fenced worker must never be auto-relaunched; killing it would also - // erase the fence, since the capture does not copy it. - !isAutomaticHibernationAllowed(sleepingRecord) + (sleepingRecord && !hasOnlyLiveResumeAnchor) ) { return null } diff --git a/src/renderer/src/lib/agent-hibernation-planner.test.ts b/src/renderer/src/lib/agent-hibernation-planner.test.ts index 10414249dfb..5be241004bb 100644 --- a/src/renderer/src/lib/agent-hibernation-planner.test.ts +++ b/src/renderer/src/lib/agent-hibernation-planner.test.ts @@ -753,37 +753,6 @@ describe('live resume anchors do not block hibernation (#10238 regression)', () ) ).toEqual([agentEntry.paneKey]) }) - - it('still refuses a pane fenced against automatic resume', () => { - const providerSession = { key: 'session_id' as const, id: 'claude-session-1' } - const agentEntry = entry({ agentType: 'claude', providerSession }) - const fenced = { - ...liveAnchor('claude', providerSession), - automaticResumeBlockedBy: 'legacy-orchestration-worker' - } - expect( - plannedPaneKeys( - snapshot({ - agentStatusByPaneKey: { [agentEntry.paneKey]: agentEntry }, - sleepingAgentSessionsByPaneKey: { [agentEntry.paneKey]: fenced as never }, - ptyBindingFirstSeenAtByPaneKey: { [agentEntry.paneKey]: OLD } - }) - ) - ).toEqual([]) - // Control: the identical pane IS planned once the fence is gone, so the rejection - // above isolates the fence rather than some other guard. - expect( - plannedPaneKeys( - snapshot({ - agentStatusByPaneKey: { [agentEntry.paneKey]: agentEntry }, - sleepingAgentSessionsByPaneKey: { - [agentEntry.paneKey]: liveAnchor('claude', providerSession) as never - }, - ptyBindingFirstSeenAtByPaneKey: { [agentEntry.paneKey]: OLD } - }) - ) - ).toEqual([agentEntry.paneKey]) - }) }) describe('idle clock anchors on stateStartedAt, not updatedAt', () => { diff --git a/src/renderer/src/lib/live-resume-anchor-record.ts b/src/renderer/src/lib/live-resume-anchor-record.ts index 7fa9d3f88ed..bc00a2f52c5 100644 --- a/src/renderer/src/lib/live-resume-anchor-record.ts +++ b/src/renderer/src/lib/live-resume-anchor-record.ts @@ -50,14 +50,3 @@ export function isCompletedPiCompatibleAgentWithLiveRecoveryRecord( isLiveResumeAnchorForCompletedAgent(entry, record, worktreeId) ) } - -/** - * A durable orchestration fence against automatic provider relaunch. Hibernating - * a fenced pane would strand it or — since `sleepingRecordFromEntry` does not copy - * the flag — erase the fence and later auto-resume prohibited work. - */ -export function isAutomaticHibernationAllowed( - record: SleepingAgentSessionRecord | undefined -): boolean { - return !record?.automaticResumeBlockedBy -} diff --git a/src/renderer/src/lib/resume-sleeping-agent-session-legacy-worker.test.ts b/src/renderer/src/lib/resume-sleeping-agent-session-legacy-worker.test.ts deleted file mode 100644 index 1ec95258f05..00000000000 --- a/src/renderer/src/lib/resume-sleeping-agent-session-legacy-worker.test.ts +++ /dev/null @@ -1,53 +0,0 @@ -import { afterEach, describe, expect, it, vi } from 'vitest' -import type { SleepingAgentSessionRecord } from '../../../shared/agent-session-resume' -import { useAppStore } from '@/store' -import { resumeSleepingAgentSessionsForWorktree } from './resume-sleeping-agent-session' - -const initialAppStoreState = useAppStore.getState() - -afterEach(() => { - vi.unstubAllGlobals() - useAppStore.setState(initialAppStoreState, true) -}) - -describe('legacy worker sleeping-session recovery', () => { - it('never resumes a proven-exited legacy worker on workspace activation', () => { - const record: SleepingAgentSessionRecord = { - paneKey: 'tab-legacy:leaf-legacy', - tabId: 'tab-legacy', - worktreeId: 'wt-legacy', - agent: 'claude', - providerSession: { key: 'session_id', id: 'session-legacy' }, - prompt: 'continue legacy work', - state: 'working', - capturedAt: 1, - updatedAt: 1, - origin: 'live', - automaticResumeBlockedBy: 'legacy-orchestration-worker' - } - useAppStore.setState({ - tabsByWorktree: { - 'wt-legacy': [ - { - id: 'tab-legacy', - ptyId: null, - worktreeId: 'wt-legacy', - title: 'Legacy worker', - customTitle: null, - color: null, - sortOrder: 0, - createdAt: 1 - } - ] - }, - sleepingAgentSessionsByPaneKey: { [record.paneKey]: record } - } as never) - - expect(resumeSleepingAgentSessionsForWorktree('wt-legacy')).toBe(0) - expect(useAppStore.getState().sleepingAgentSessionsByPaneKey[record.paneKey]).toBe(record) - - useAppStore.getState().clearSleepingAgentSession(record.paneKey) - expect(resumeSleepingAgentSessionsForWorktree('wt-legacy')).toBe(0) - expect(useAppStore.getState().sleepingAgentSessionsByPaneKey[record.paneKey]).toBeUndefined() - }) -}) diff --git a/src/renderer/src/lib/resume-sleeping-agent-session.ts b/src/renderer/src/lib/resume-sleeping-agent-session.ts index 94dc52bc7c6..e0b5b79ac6e 100644 --- a/src/renderer/src/lib/resume-sleeping-agent-session.ts +++ b/src/renderer/src/lib/resume-sleeping-agent-session.ts @@ -210,9 +210,6 @@ export function resumeSleepingAgentSessionsForWorktree( if (options?.skipClaimKeys?.has(claimKey)) { continue } - if (record.automaticResumeBlockedBy === 'legacy-orchestration-worker') { - continue - } if (isInvalidWorktreeActivationRecord(record)) { state.clearSleepingAgentSession(record.paneKey) continue diff --git a/src/renderer/src/lib/settled-worker-wake-policy.test.ts b/src/renderer/src/lib/settled-worker-wake-policy.test.ts new file mode 100644 index 00000000000..d227568cb00 --- /dev/null +++ b/src/renderer/src/lib/settled-worker-wake-policy.test.ts @@ -0,0 +1,47 @@ +import { afterEach, expect, it, vi } from 'vitest' +import { useAppStore } from '@/store' +import { resumeSleepingAgentSessionsForWorktree } from './resume-sleeping-agent-session' + +const initialState = useAppStore.getState() + +afterEach(() => { + vi.unstubAllGlobals() + useAppStore.setState(initialState, true) +}) + +it('resumes a settled worker and an ordinary agent once each in the same wake sweep', () => { + const records = ['settled-worker', 'ordinary-agent'].map((id) => ({ + paneKey: `${id}:leaf`, + tabId: id, + worktreeId: 'wt-1', + agent: 'claude' as const, + providerSession: { key: 'session_id' as const, id }, + prompt: 'continue the session', + state: 'working' as const, + capturedAt: Date.now(), + updatedAt: Date.now(), + origin: 'worktree-sleep' as const, + // Old clients can still publish the withdrawn policy field. + ...(id === 'settled-worker' ? { automaticResumeBlockedBy: 'legacy-orchestration-worker' } : {}) + })) + useAppStore.setState({ + tabsByWorktree: { 'wt-1': [] }, + sleepingAgentSessionsByPaneKey: Object.fromEntries(records.map((r) => [r.paneKey, r])) + }) + + expect(resumeSleepingAgentSessionsForWorktree('wt-1')).toBe(2) + expect(resumeSleepingAgentSessionsForWorktree('wt-1')).toBe(0) + const state = useAppStore.getState() + const tabs = state.tabsByWorktree['wt-1'] + expect(tabs).toHaveLength(2) + const commands = tabs.map((tab) => state.pendingStartupByTabId[tab.id]?.command ?? '') + for (const record of records) { + expect(commands.filter((command) => command.includes(record.providerSession.id))).toHaveLength( + 1 + ) + } + for (const command of commands) { + expect(command.match(/--resume/g)).toHaveLength(1) + } + expect(state.sleepingAgentSessionsByPaneKey).toEqual({}) +}) diff --git a/src/renderer/src/store/slices/agent-pane-authority.test.ts b/src/renderer/src/store/slices/agent-pane-authority.test.ts index 01e99f27d6f..767104fda87 100644 --- a/src/renderer/src/store/slices/agent-pane-authority.test.ts +++ b/src/renderer/src/store/slices/agent-pane-authority.test.ts @@ -156,7 +156,7 @@ describe('agent pane authority', () => { expect(store.getState().agentStatusByPaneKey[SIBLING]).toBeUndefined() }) - it('can retire live pane authority while retaining a migration recovery fence', () => { + it('can retire live pane authority while retaining its sleeping session', () => { const store = createTestStore() store.getState().setAgentStatus(TARGET, { state: 'working', prompt: 'target' }) store.getState().registerAgentLaunchConfig(TARGET, { agentArgs: '', agentEnv: {} }) @@ -171,8 +171,7 @@ describe('agent pane authority', () => { prompt: 'continue', state: 'working', capturedAt: 1, - updatedAt: 1, - automaticResumeBlockedBy: 'legacy-orchestration-worker' + updatedAt: 1 } } }) @@ -183,7 +182,7 @@ describe('agent pane authority', () => { expect(state.agentStatusByPaneKey[TARGET]).toBeUndefined() expect(state.agentLaunchConfigByPaneKey[TARGET]).toBeUndefined() expect(state.sleepingAgentSessionsByPaneKey[TARGET]).toMatchObject({ - automaticResumeBlockedBy: 'legacy-orchestration-worker' + providerSession: { key: 'session_id', id: 'session-1' } }) expect(state.recentlyRetiredAgentStatusPaneKeys[TARGET]).toBe(true) expect(retirePaneAuthority).toHaveBeenCalledWith(TARGET) diff --git a/src/renderer/src/store/slices/agent-status-manual-sleep-capture.test.ts b/src/renderer/src/store/slices/agent-status-manual-sleep-capture.test.ts index f1deb30370f..527db809596 100644 --- a/src/renderer/src/store/slices/agent-status-manual-sleep-capture.test.ts +++ b/src/renderer/src/store/slices/agent-status-manual-sleep-capture.test.ts @@ -141,36 +141,6 @@ describe('manual sleep agent session capture', () => { expect(records['tab-1:working'].restoreOnTabOpenOnly).toBeUndefined() }) - it('carries a blocked legacy-orchestration-worker flag onto the replacement record', () => { - vi.useFakeTimers() - vi.setSystemTime(NOW) - const store = createTestStore() - seedTabs(store) - store.setState({ - agentStatusByPaneKey: { - 'tab-1:leaf-1': makeAgentEntry(), - 'tab-1:leaf-2': makeAgentEntry({ paneKey: 'tab-1:leaf-2' }) - }, - sleepingAgentSessionsByPaneKey: { - 'tab-1:leaf-1': makeSleepingRecord({ - providerSession: { key: 'session_id', id: 'session-tab-1:leaf-1' }, - automaticResumeBlockedBy: 'legacy-orchestration-worker' - }), - 'tab-1:leaf-2': makeSleepingRecord({ - paneKey: 'tab-1:leaf-2', - automaticResumeBlockedBy: 'legacy-orchestration-worker' - }) - } - } as Partial) - - store.getState().captureSleepingAgentSessionsByWorktree('wt-1') - - const records = store.getState().sleepingAgentSessionsByPaneKey - expect(records['tab-1:leaf-1'].automaticResumeBlockedBy).toBe('legacy-orchestration-worker') - // Different provider session: the block belonged to a session that is no longer running here. - expect(records['tab-1:leaf-2'].automaticResumeBlockedBy).toBeUndefined() - }) - it('preserves retained completed sessions as intentional sleep records', () => { vi.useFakeTimers() vi.setSystemTime(NOW) @@ -231,38 +201,6 @@ describe('manual sleep agent session capture', () => { expect(record.interrupted).toBeUndefined() }) - it('carries a blocked legacy-orchestration-worker flag onto a retained replacement record', () => { - vi.useFakeTimers() - vi.setSystemTime(NOW) - const store = createTestStore() - seedTabs(store) - const entry = makeAgentEntry({ paneKey: 'tab-1:retained', state: 'done' }) - store.setState({ - retainedAgentsByPaneKey: { - 'tab-1:retained': { - entry, - tab: makeTab({ id: 'tab-1', worktreeId: 'wt-1' }), - worktreeId: 'wt-1', - agentType: 'codex', - startedAt: entry.stateStartedAt - } - }, - sleepingAgentSessionsByPaneKey: { - 'tab-1:retained': makeSleepingRecord({ - paneKey: 'tab-1:retained', - providerSession: { key: 'session_id', id: 'session-tab-1:retained' }, - automaticResumeBlockedBy: 'legacy-orchestration-worker' - }) - } - } as Partial) - - store.getState().captureSleepingAgentSessionsByWorktree('wt-1') - - expect( - store.getState().sleepingAgentSessionsByPaneKey['tab-1:retained'].automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') - }) - // Why: the promoted checkpoint owns the pane's recovery identity (connection, transcript); the // retained pass must not re-derive over it any more than the live pass may. it('keeps a promoted live checkpoint that also has a retained row', () => { diff --git a/src/renderer/src/store/slices/agent-status-open-tab-resume-fence.test.ts b/src/renderer/src/store/slices/agent-status-open-tab-resume-fence.test.ts deleted file mode 100644 index cbd6b186997..00000000000 --- a/src/renderer/src/store/slices/agent-status-open-tab-resume-fence.test.ts +++ /dev/null @@ -1,60 +0,0 @@ -import { describe, expect, it } from 'vitest' -import type { AgentStatusEntry } from '../../../../shared/agent-status-types' -import type { AppState } from '../types' -import { createTestStore, makeTab } from './store-test-helpers' - -const NOW = 1_800_000_000_000 -const PANE_KEY = 'tab-1:leaf-1' - -function liveWorkerEntry(): AgentStatusEntry { - return { - state: 'working', - prompt: 'finish the task', - updatedAt: NOW, - stateStartedAt: NOW, - stateHistory: [], - agentType: 'codex', - paneKey: PANE_KEY, - tabId: 'tab-1', - worktreeId: 'wt-1', - providerSession: { key: 'session_id', id: 'session-1' } - } -} - -// The worker settles while its tab is still open, so there is no sleeping record to stamp; the -// record is minted on close and used to arrive unfenced, respawning settled work on reopen. -describe('a resume fence that arrives before the sleeping record exists', () => { - it('carries the block onto the record minted after the tab closes', () => { - const store = createTestStore() - store.setState({ - tabsByWorktree: { 'wt-1': [makeTab({ id: 'tab-1', worktreeId: 'wt-1' })] }, - agentStatusByPaneKey: { [PANE_KEY]: liveWorkerEntry() } - } as Partial) - - store.getState().setSleepingAgentAutomaticResumeBlocked(PANE_KEY, true) - expect(store.getState().sleepingAgentSessionsByPaneKey[PANE_KEY]).toBeUndefined() - - store.getState().captureAllSleepingAgentSessions('quit') - - expect(store.getState().sleepingAgentSessionsByPaneKey[PANE_KEY]).toMatchObject({ - paneKey: PANE_KEY, - automaticResumeBlockedBy: 'legacy-orchestration-worker' - }) - }) - - it('mints an unfenced record once the runtime lifts the block', () => { - const store = createTestStore() - store.setState({ - tabsByWorktree: { 'wt-1': [makeTab({ id: 'tab-1', worktreeId: 'wt-1' })] }, - agentStatusByPaneKey: { [PANE_KEY]: liveWorkerEntry() } - } as Partial) - - store.getState().setSleepingAgentAutomaticResumeBlocked(PANE_KEY, true) - store.getState().setSleepingAgentAutomaticResumeBlocked(PANE_KEY, false) - store.getState().captureAllSleepingAgentSessions('quit') - - expect( - store.getState().sleepingAgentSessionsByPaneKey[PANE_KEY]?.automaticResumeBlockedBy - ).toBeUndefined() - }) -}) diff --git a/src/renderer/src/store/slices/agent-status-provider-session-actions.ts b/src/renderer/src/store/slices/agent-status-provider-session-actions.ts index 32e5378fe11..1ffe1d7cb0e 100644 --- a/src/renderer/src/store/slices/agent-status-provider-session-actions.ts +++ b/src/renderer/src/store/slices/agent-status-provider-session-actions.ts @@ -113,10 +113,6 @@ export function createAgentStatusProviderSessionActions( ? { connectionId: existingRecord.connectionId } : {}), ...(launchConfig ? { launchConfig: copyLaunchConfig(launchConfig) } : {}), - ...(existingRecordMatchesProviderSession && - existingRecord.automaticResumeBlockedBy === 'legacy-orchestration-worker' - ? { automaticResumeBlockedBy: 'legacy-orchestration-worker' } - : {}), ...(preservesCompletedRecoveryRecord && existingRecord.interrupted !== undefined ? { interrupted: existingRecord.interrupted } : {}), diff --git a/src/renderer/src/store/slices/agent-status-provider-session.test.ts b/src/renderer/src/store/slices/agent-status-provider-session.test.ts index 0d60d023956..786b45378ec 100644 --- a/src/renderer/src/store/slices/agent-status-provider-session.test.ts +++ b/src/renderer/src/store/slices/agent-status-provider-session.test.ts @@ -327,64 +327,6 @@ describe('recordAgentProviderSession', () => { ).toBeUndefined() }) - it('preserves the legacy resume fence only for the same Pi session identity', () => { - const store = createTestStore() - const makeRecord = (transcriptPath: string): SleepingAgentSessionRecord => ({ - paneKey: 'tab-1:leaf-1', - tabId: 'tab-1', - worktreeId: 'wt-1', - agent: 'pi', - providerSession: { - key: 'session_id', - id: 'pi-session-1', - transcriptPath - }, - prompt: '', - state: 'working', - capturedAt: 10, - updatedAt: 10, - automaticResumeBlockedBy: 'legacy-orchestration-worker', - origin: 'live' - }) - store.setState({ - sleepingAgentSessionsByPaneKey: { - 'tab-1:leaf-1': makeRecord('/tmp/pi-session-1.jsonl') - } - } as Partial) - - store.getState().recordAgentProviderSession( - 'tab-1:leaf-1', - 'pi', - { - key: 'session_id', - id: 'pi-session-1', - transcriptPath: '/tmp/pi-session-1.jsonl' - }, - { updatedAt: 20 }, - { tabId: 'tab-1', worktreeId: 'wt-1' } - ) - - expect( - store.getState().sleepingAgentSessionsByPaneKey['tab-1:leaf-1']?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') - - store.getState().recordAgentProviderSession( - 'tab-1:leaf-1', - 'pi', - { - key: 'session_id', - id: 'pi-session-1', - transcriptPath: '/tmp/pi-session-2.jsonl' - }, - { updatedAt: 30 }, - { tabId: 'tab-1', worktreeId: 'wt-1' } - ) - - expect( - store.getState().sleepingAgentSessionsByPaneKey['tab-1:leaf-1']?.automaticResumeBlockedBy - ).toBeUndefined() - }) - it.each(PI_COMPATIBLE_CASES)( 'keeps a completed $label session resumable through manual worktree sleep', async ({ agent, label }) => { diff --git a/src/renderer/src/store/slices/agent-status-recovery-actions.ts b/src/renderer/src/store/slices/agent-status-recovery-actions.ts index d750f5c0df9..0e256834a9f 100644 --- a/src/renderer/src/store/slices/agent-status-recovery-actions.ts +++ b/src/renderer/src/store/slices/agent-status-recovery-actions.ts @@ -22,7 +22,6 @@ export function createAgentStatusRecoveryActions( | 'captureAllSleepingAgentSessions' | 'clearSleepingAgentSession' | 'clearSleepingAgentSessionsByPaneKey' - | 'setSleepingAgentAutomaticResumeBlocked' | 'clearSleepingAgentSessionsByWorktree' | 'pruneSleepingAgentSessions' > { @@ -109,47 +108,6 @@ export function createAgentStatusRecoveryActions( clearSleepingAgentSession: (paneKey) => clearSleepingAgentSessionsByPaneKey([paneKey]), clearSleepingAgentSessionsByPaneKey, - setSleepingAgentAutomaticResumeBlocked: (paneKey, blocked) => { - set((s) => { - // The pane key is tracked even with no record: a worker settled while its tab was open - // is fenced before the record exists, and the record is only minted on close. - const wasBlocked = s.automaticResumeBlockedPaneKeys[paneKey] === true - let paneKeys = s.automaticResumeBlockedPaneKeys - if (blocked !== wasBlocked) { - paneKeys = { ...s.automaticResumeBlockedPaneKeys } - if (blocked) { - paneKeys[paneKey] = true - } else { - delete paneKeys[paneKey] - } - } - const current = s.sleepingAgentSessionsByPaneKey[paneKey] - if ( - !current || - (blocked - ? current.automaticResumeBlockedBy === 'legacy-orchestration-worker' - : current.automaticResumeBlockedBy === undefined) - ) { - return paneKeys === s.automaticResumeBlockedPaneKeys - ? s - : { automaticResumeBlockedPaneKeys: paneKeys } - } - const next = { ...current } - if (blocked) { - next.automaticResumeBlockedBy = 'legacy-orchestration-worker' - } else { - delete next.automaticResumeBlockedBy - } - return { - automaticResumeBlockedPaneKeys: paneKeys, - sleepingAgentSessionsByPaneKey: { - ...s.sleepingAgentSessionsByPaneKey, - [paneKey]: next - } - } - }) - }, - clearSleepingAgentSessionsByWorktree: (worktreeId) => { set((s) => { let changed = false diff --git a/src/renderer/src/store/slices/agent-status-recovery-collection.ts b/src/renderer/src/store/slices/agent-status-recovery-collection.ts index 4587f919d36..689dbf861a7 100644 --- a/src/renderer/src/store/slices/agent-status-recovery-collection.ts +++ b/src/renderer/src/store/slices/agent-status-recovery-collection.ts @@ -10,7 +10,6 @@ import { retainedAgentEntryFromLive } from './agent-status-pane-key-tab-binding' import { - carryOverAutomaticResumeBlock, isValidCompletedAgentHibernationEntry, manualSleepCaptureEntry, markManualSleepLazyRestore, @@ -96,10 +95,6 @@ export function collectSleepingAgentSessionRecordsForWorktree( if (record) { if (isManualWorktreeSleep) { markManualSleepLazyRestore(record) - carryOverAutomaticResumeBlock( - record, - state.sleepingAgentSessionsByPaneKey[retained.entry.paneKey] - ) } records[record.paneKey] = record } @@ -133,7 +128,6 @@ export function collectSleepingAgentSessionRecordsForWorktree( if (record) { if (isManualWorktreeSleep) { markManualSleepLazyRestore(record) - carryOverAutomaticResumeBlock(record, state.sleepingAgentSessionsByPaneKey[paneKey]) } records[record.paneKey] = record } diff --git a/src/renderer/src/store/slices/agent-status-sleeping-records.ts b/src/renderer/src/store/slices/agent-status-sleeping-records.ts index 48691b078bc..6363fb9e216 100644 --- a/src/renderer/src/store/slices/agent-status-sleeping-records.ts +++ b/src/renderer/src/store/slices/agent-status-sleeping-records.ts @@ -1,7 +1,6 @@ import type { AppState } from '../types' import type { AgentStatusEntry } from '../../../../shared/agent-status-types' import { - agentProviderSessionsEqual, getAgentResumeArgv, isResumableTuiAgent, type SleepingAgentLaunchConfig, @@ -59,11 +58,7 @@ export function sleepingRecordFromEntry(args: { : {}), ...(args.launchConfig ? { launchConfig: copyLaunchConfig(args.launchConfig) } : {}), ...(args.entry.interrupted ? { interrupted: true } : {}), - ...(args.origin ? { origin: args.origin } : {}), - // The worker can settle while the tab is open, so the fence arrives before this record exists. - ...(args.state.automaticResumeBlockedPaneKeys?.[args.entry.paneKey] - ? { automaticResumeBlockedBy: 'legacy-orchestration-worker' as const } - : {}) + ...(args.origin ? { origin: args.origin } : {}) } } @@ -113,21 +108,6 @@ export function manualSleepCaptureEntry( return { ...entry, updatedAt: capturedAt, interrupted: false } } -// Why: capture recreates a record the manual-sleep wipe would otherwise remove, so a deliberately -// blocked worker must not become auto-resumable at wake. -export function carryOverAutomaticResumeBlock( - record: SleepingAgentSessionRecord, - previous: SleepingAgentSessionRecord | undefined -): void { - if ( - previous?.automaticResumeBlockedBy === 'legacy-orchestration-worker' && - previous.agent === record.agent && - agentProviderSessionsEqual(record.agent, previous.providerSession, record.providerSession) - ) { - record.automaticResumeBlockedBy = previous.automaticResumeBlockedBy - } -} - export function removeSleepingRecordsReplacedByManualWorktreeSleep( records: Record, worktreeId: string, diff --git a/src/renderer/src/store/slices/agent-status-slice-contract.ts b/src/renderer/src/store/slices/agent-status-slice-contract.ts index f9c02abda5a..8dc01fc5598 100644 --- a/src/renderer/src/store/slices/agent-status-slice-contract.ts +++ b/src/renderer/src/store/slices/agent-status-slice-contract.ts @@ -51,10 +51,6 @@ export type AgentStatusSlice = { /** Durable agent sessions captured on sleep (not live rows); power the one-click CLI resume on wake. */ sleepingAgentSessionsByPaneKey: Record - /** Panes the runtime fenced against automatic resume. Held separately because a worker can - * settle while its tab is open, before the sleeping record the fence belongs on exists. */ - automaticResumeBlockedPaneKeys: Record - /** Ephemeral launch snapshots keyed by pane; hook payloads lack Orca launch settings, so the renderer supplies them from startup. */ agentLaunchConfigByPaneKey: Record @@ -162,7 +158,6 @@ export type AgentStatusSlice = { captureAllSleepingAgentSessions: (mode: AllAgentSessionCaptureMode) => void clearSleepingAgentSession: (paneKey: string) => void clearSleepingAgentSessionsByPaneKey: (paneKeys: readonly string[]) => void - setSleepingAgentAutomaticResumeBlocked: (paneKey: string, blocked: boolean) => void clearSleepingAgentSessionsByWorktree: (worktreeId: string) => void pruneSleepingAgentSessions: (validWorktreeIds: Set) => void diff --git a/src/renderer/src/store/slices/agent-status.ts b/src/renderer/src/store/slices/agent-status.ts index 64941669dfb..6a1ed10025c 100644 --- a/src/renderer/src/store/slices/agent-status.ts +++ b/src/renderer/src/store/slices/agent-status.ts @@ -100,7 +100,6 @@ export const createAgentStatusSlice: StateCreator { - const record = get().sleepingAgentSessionsByPaneKey[opts.paneKey] - if (!isAutomaticHibernationAllowed(record)) { - throw new Error('agent_hibernation_automatic_resume_blocked') - } - } - assertAutomaticHibernationStillAllowed() const capture = shutdownBufferCaptures.get(opts.tabId) if (capture) { try { @@ -82,8 +70,6 @@ export function createTerminalPaneHibernationActions( // Don't let one tab's capture failure block the pane hibernation. } } - // Why: the capture callback runs synchronously above and can itself fence the pane. - assertAutomaticHibernationStillAllowed() // Why: store sleeping records before kill, since pty:exit can arrive first. const sleepingRecordKeys = Object.keys(sleepingAgentSessionRecords) const replacedSleepingRecords: Record = diff --git a/src/renderer/src/web/preload-api/web-agent-status-api.ts b/src/renderer/src/web/preload-api/web-agent-status-api.ts index 1a07b6d6a6c..d7c9740018c 100644 --- a/src/renderer/src/web/preload-api/web-agent-status-api.ts +++ b/src/renderer/src/web/preload-api/web-agent-status-api.ts @@ -12,7 +12,6 @@ export function createWebAgentStatusApi(): Partial { onMigrationUnsupported: () => noopUnsubscribe, onMigrationUnsupportedClear: () => noopUnsubscribe, onLegacyWorkerTerminalRecovery: () => noopUnsubscribe, - onLegacyWorkerTerminalResumeFence: () => noopUnsubscribe, getMigrationUnsupportedSnapshot: () => Promise.resolve([]), drop: () => {}, dropPersisted: () => {}, diff --git a/src/shared/agent-session-resume.ts b/src/shared/agent-session-resume.ts index 3e763fc20a6..9ae49955d84 100644 --- a/src/shared/agent-session-resume.ts +++ b/src/shared/agent-session-resume.ts @@ -63,9 +63,6 @@ export type SleepingAgentSessionRecord = { * so only the pane's own cold-restore path may consume them — activation * launching a tab too would duplicate a warm-reattached session (#5232). */ origin?: 'worktree-sleep' | 'quit' | 'live' - /** Prevents provider-session relaunch while main reconciles a durable - * orchestration assignment against authoritative PTY inventory. */ - automaticResumeBlockedBy?: 'legacy-orchestration-worker' /** Set on a finished pane captured by an explicit workspace sleep. Its * `--resume` is issued by the pane's own cold restore when its tab is * opened, so a mobile wake must not background-mount every such tab and diff --git a/src/shared/workspace-session-schema.sleeping-agent.test.ts b/src/shared/workspace-session-schema.sleeping-agent.test.ts index 0f34528bcb5..57d4a832b46 100644 --- a/src/shared/workspace-session-schema.sleeping-agent.test.ts +++ b/src/shared/workspace-session-schema.sleeping-agent.test.ts @@ -41,6 +41,38 @@ describe('parseWorkspaceSession sleeping agents', () => { } }) + it.each([undefined, 'legacy-orchestration-worker'])( + 'new host ignores an old client resume fence (%s)', + (automaticResumeBlockedBy) => { + const record = { + paneKey: 'tab1:pane-1', + tabId: 'tab1', + worktreeId: 'wt', + agent: 'codex', + providerSession: { key: 'session_id', id: 'codex-session' }, + prompt: 'continue', + state: 'done', + capturedAt: 10, + updatedAt: 10, + origin: 'worktree-sleep' + } + const result = parseWorkspaceSession({ + activeRepoId: null, + activeWorktreeId: null, + activeTabId: null, + tabsByWorktree: {}, + terminalLayoutsByTabId: {}, + sleepingAgentSessionsByPaneKey: { + [record.paneKey]: { ...record, automaticResumeBlockedBy } + } + }) + expect(result.ok).toBe(true) + if (result.ok) { + expect(result.value.sleepingAgentSessionsByPaneKey?.[record.paneKey]).toEqual(record) + } + } + ) + it('hydrates a persisted Kimi sleeping agent record', () => { const result = parseWorkspaceSession({ activeRepoId: null, diff --git a/src/shared/workspace-session-sleeping-agents.ts b/src/shared/workspace-session-sleeping-agents.ts index 4ee620efa82..2f2ac1252bb 100644 --- a/src/shared/workspace-session-sleeping-agents.ts +++ b/src/shared/workspace-session-sleeping-agents.ts @@ -99,7 +99,6 @@ const sleepingAgentSessionRecordSchema = z connectionId: z.string().nullable().optional(), launchConfig: sleepingAgentLaunchConfigSchema.optional(), origin: z.enum(['worktree-sleep', 'quit', 'live']).optional(), - automaticResumeBlockedBy: z.enum(['legacy-orchestration-worker']).optional(), restoreOnTabOpenOnly: z.boolean().optional() }) .refine( diff --git a/tests/e2e/completed-worker-retirement-resume.unit.test.ts b/tests/e2e/completed-worker-retirement-resume.unit.test.ts index 8e3eb9c4470..82511787f57 100644 --- a/tests/e2e/completed-worker-retirement-resume.unit.test.ts +++ b/tests/e2e/completed-worker-retirement-resume.unit.test.ts @@ -434,17 +434,11 @@ describe('completed background-worker retirement resume matrix', () => { expect(retiredRestart.tabsByWorktree[WORKTREE_ID]).toEqual([]) expect(retiredRestart.sleepingAgentSessionsByPaneKey?.[ORIGINAL_PANE_KEY]).toBeUndefined() - // Case 4: legacy rollback preserves a fenced record; exited resolution clears it. + // Case 4: legacy rollback preserves the settled worker's record as an ordinary sleeping + // record; with its tab gone it is passive completed evidence that wake clears, and an exited + // resolution clears it too. No fence: a finished worker follows the same rule as any agent pane. seedWorkspace() - const legacyRecord = recordCompletedWorker() - useAppStore.setState({ - sleepingAgentSessionsByPaneKey: { - [ORIGINAL_PANE_KEY]: { - ...legacyRecord, - automaticResumeBlockedBy: 'legacy-orchestration-worker' - } - } - }) + recordCompletedWorker() const legacyAction = resolveLegacyWorkerTerminalRecoveryAction({ paneKey: ORIGINAL_PANE_KEY, resolution: 'rolled_back', @@ -456,17 +450,19 @@ describe('completed background-worker retirement resume matrix', () => { rollbackLegacyWorkerTerminalSurfaceInStore(useAppStore.getState(), legacyAction.detail) ).toBe('removed') } - expect(resumeSleepingAgentSessionsForWorktree(WORKTREE_ID)).toBe(0) + expect(useAppStore.getState().sleepingAgentSessionsByPaneKey[ORIGINAL_PANE_KEY]).toMatchObject({ + state: 'done' + }) expect( useAppStore.getState().sleepingAgentSessionsByPaneKey[ORIGINAL_PANE_KEY] - ?.automaticResumeBlockedBy - ).toBe('legacy-orchestration-worker') + ).not.toHaveProperty('automaticResumeBlockedBy') + expect(resumeSleepingAgentSessionsForWorktree(WORKTREE_ID)).toBe(0) + expect(useAppStore.getState().sleepingAgentSessionsByPaneKey[ORIGINAL_PANE_KEY]).toBeUndefined() const exitedAction = resolveLegacyWorkerTerminalRecoveryAction({ paneKey: ORIGINAL_PANE_KEY, resolution: 'exited' }) expect(exitedAction).toEqual({ kind: 'clear-sleeping', paneKey: ORIGINAL_PANE_KEY }) - useAppStore.getState().clearSleepingAgentSession(ORIGINAL_PANE_KEY) // Case 5: coordinator manual close is the same safe exact-tab retirement boundary. seedWorkspace() diff --git a/tests/e2e/helpers/completed-worker-retirement-fixture.ts b/tests/e2e/helpers/completed-worker-retirement-fixture.ts index 43de5782648..d3ef3fb8195 100644 --- a/tests/e2e/helpers/completed-worker-retirement-fixture.ts +++ b/tests/e2e/helpers/completed-worker-retirement-fixture.ts @@ -60,18 +60,23 @@ process.stdin.resume() setInterval(() => {}, 60_000) ` -if (process.platform === 'win32') { - writeFileSync(path.join(fakeCliDir, 'fake-codex.js'), fakeCodexSource) - writeFileSync( - path.join(fakeCliDir, 'codex.cmd'), - '@echo off\r\nnode "%~dp0\\fake-codex.js" %*\r\n' - ) -} else { - const executable = path.join(fakeCliDir, 'codex') - writeFileSync(executable, `#!/usr/bin/env node\n${fakeCodexSource}`) - chmodSync(executable, 0o755) +function installCompletedWorkerFakeCodex(): void { + mkdirSync(fakeCliDir, { recursive: true }) + if (process.platform === 'win32') { + writeFileSync(path.join(fakeCliDir, 'fake-codex.js'), fakeCodexSource) + writeFileSync( + path.join(fakeCliDir, 'codex.cmd'), + '@echo off\r\nnode "%~dp0\\fake-codex.js" %*\r\n' + ) + } else { + const executable = path.join(fakeCliDir, 'codex') + writeFileSync(executable, `#!/usr/bin/env node\n${fakeCodexSource}`) + chmodSync(executable, 0o755) + } } +installCompletedWorkerFakeCodex() + export const completedWorkerLaunchEnv = { PATH: `${fakeCliDir}${path.delimiter}${process.env.PATH ?? ''}`, ORCA_E2E_CODEX_LIFECYCLE_LEDGER: lifecycleLedgerPath @@ -91,6 +96,8 @@ export type TerminalIdentity = Pick< > export function clearCompletedWorkerLedger(): void { + // Another spec can clean up this cached fixture before the next test uses it. + installCompletedWorkerFakeCodex() rmSync(lifecycleLedgerPath, { force: true }) } diff --git a/tests/e2e/settled-worker-tab-survives-restart.spec.ts b/tests/e2e/settled-worker-tab-survives-restart.spec.ts new file mode 100644 index 00000000000..db3b03409dd --- /dev/null +++ b/tests/e2e/settled-worker-tab-survives-restart.spec.ts @@ -0,0 +1,530 @@ +import { existsSync, readFileSync } from 'node:fs' +import path from 'node:path' +import { DaemonClient } from '../../src/main/daemon/client' +import { getDaemonSocketPath, getDaemonTokenPath } from '../../src/main/daemon/daemon-spawner' +import { DEFAULT_LOCAL_ORCA_PROFILE_ID } from '../../src/shared/orca-profiles' +import type { ElectronApplication, Page } from '@stablyai/playwright-test' +import { test, expect } from './helpers/orca-app' +import { TEST_REPO_PATH_FILE } from './global-setup' +import { attachRepoAndOpenTerminal, createRestartSession } from './helpers/orca-restart' +import { ensureTerminalVisible, waitForActiveWorktree, waitForSessionReady } from './helpers/store' +import { + waitForActivePaneHookDescriptor, + waitForActivePanePtyId, + waitForActiveTerminalManager +} from './helpers/terminal' +import { FAKE_AGENT_WINDOWS_SHELL } from './helpers/fake-agent-command-override' +import { + clearCompletedWorkerLedger, + completedWorkerFakeCodexCommand, + completedWorkerLaunchEnv, + listRuntimeTerminals, + readCompletedWorkerDispatchCapability, + readCompletedWorkerLedger, + seedCurrentCodexTranscript +} from './helpers/completed-worker-retirement-fixture' +import { RuntimeClient } from '../../src/cli/runtime-client' +import type { RuntimeTerminalSummary } from '../../src/shared/runtime-types' +import { splitWorktreeIdForFilesystem } from '../../src/shared/worktree/id' + +const PROVIDER_SESSION_ID = '019feb51-2269-71c2-89c6-faa8dc65c8dd' + +test.describe.configure({ mode: 'serial' }) + +async function findSecondaryWorktree( + page: Page, + client: RuntimeClient, + coordinatorWorktreeId: string +): Promise { + let targetWorktreeId: string | null = null + await expect + .poll( + async () => { + const listed = await client.call<{ worktrees: { id: string }[] }>('worktree.list', {}) + // The restart fixture only waits for the primary; refetch until the seeded secondary lands. + const rendererWorktreeIds = await page.evaluate(async () => { + const store = window.__store + if (!store) { + return [] + } + await Promise.all( + store.getState().repos.map((repo) => store.getState().fetchWorktrees(repo.id)) + ) + return Object.values(store.getState().worktreesByRepo) + .flat() + .map((worktree) => worktree.id) + }) + targetWorktreeId = + listed.result.worktrees.find( + (worktree) => + worktree.id !== coordinatorWorktreeId && rendererWorktreeIds.includes(worktree.id) + )?.id ?? null + return targetWorktreeId + }, + { timeout: 60_000, message: 'runtime never registered the secondary worktree' } + ) + .not.toBeNull() + if (!targetWorktreeId) { + throw new Error('The seeded repository did not expose its secondary worktree') + } + return targetWorktreeId +} + +async function backgroundMountTab(page: Page, worktreeId: string, tabId: string): Promise { + await page.evaluate( + ({ tabId, worktreeId }) => { + window.dispatchEvent( + new CustomEvent('orca-background-mount-terminal-worktree', { + detail: { worktreeId, tabIds: [tabId] } + }) + ) + }, + { tabId, worktreeId } + ) + await expect + .poll(() => page.evaluate((tabId) => Boolean(window.__paneManagers?.get(tabId)), tabId)) + .toBe(true) +} + +function readPersistedSession(userDataDir: string) { + return JSON.parse( + readFileSync( + path.join(userDataDir, 'profiles', DEFAULT_LOCAL_ORCA_PROFILE_ID, 'orca-data.json'), + 'utf8' + ) + ).workspaceSession +} + +function expectNoPersistedWorkerFence(userDataDir: string, paneKey: string): void { + const persisted = readPersistedSession(userDataDir) + // Keep the baseline running through reveal even when it still writes the withdrawn policy. + expect + .soft(persisted.sleepingAgentSessionsByPaneKey?.[paneKey] ?? {}) + .not.toHaveProperty('automaticResumeBlockedBy') + expect.soft(persisted.legacyWorkerResumeFencesByPaneKey ?? {}).not.toHaveProperty(paneKey) +} + +// A restored worker must attach through main so revealing it never fabricates a missing PTY. +for (const daemonSessionGone of [false, true]) { + test(`a settled worker tab survives restart with daemon session ${daemonSessionGone ? 'exited' : 'live'}`, async (// oxlint-disable-next-line no-empty-pattern -- Playwright's second fixture arg is testInfo; the first must be an object destructure to opt out of the default fixture set. + {}, testInfo) => { + test.setTimeout(300_000) + const repoPath = readFileSync(TEST_REPO_PATH_FILE, 'utf-8').trim() + if (!repoPath || !existsSync(repoPath)) { + test.skip(true, 'Global setup did not produce a seeded test repo') + return + } + clearCompletedWorkerLedger() + + const session = createRestartSession(testInfo, completedWorkerLaunchEnv) + let firstApp: ElectronApplication | null = null + let secondApp: ElectronApplication | null = null + try { + const first = await session.launch() + firstApp = first.app + const coordinatorWorktreeId = await attachRepoAndOpenTerminal(first.page, repoPath) + await waitForSessionReady(first.page) + await waitForActiveWorktree(first.page) + await ensureTerminalVisible(first.page) + await waitForActiveTerminalManager(first.page) + await waitForActivePanePtyId(first.page) + await first.page.evaluate( + async ({ agentCommand, terminalWindowsShell }) => { + await window.__store?.getState().updateSettings({ + agentCmdOverrides: { codex: agentCommand }, + terminalWindowsShell, + disabledTuiAgents: [], + terminalHiddenViewParking: false + }) + }, + { + agentCommand: completedWorkerFakeCodexCommand, + terminalWindowsShell: FAKE_AGENT_WINDOWS_SHELL + } + ) + const isolatedHome = await firstApp.evaluate(({ app }) => app.getPath('home')) + const client = new RuntimeClient(session.userDataDir, 30_000, null, null) + const coordinatorPane = await waitForActivePaneHookDescriptor(first.page) + const coordinatorHandle = ( + await client.call<{ terminal: { handle: string } }>('terminal.resolvePane', { + paneKey: coordinatorPane.paneKey + }) + ).result.terminal.handle + const targetWorktreeId = await findSecondaryWorktree( + first.page, + client, + coordinatorWorktreeId + ) + const targetWorktreePath = splitWorktreeIdForFilesystem(targetWorktreeId)?.worktreePath + if (!targetWorktreePath) { + throw new Error('The secondary worktree did not expose a filesystem path') + } + + const run = await client.call<{ run: { id: string } }>('orchestration.runCreate', { + objective: 'Keep one settled worker tab across restart', + from: coordinatorHandle + }) + const task = await client.call<{ task: { id: string } }>('orchestration.taskCreate', { + spec: 'Report completion and stay open', + run: run.result.run.id, + callerTerminalHandle: coordinatorHandle + }) + const started = await client.call<{ + dispatchId: string + state: string + effects: { kind: string; role?: string; id?: string }[] + }>('orchestration.workerStart', { + task: task.result.task.id, + from: coordinatorHandle, + worktree: `id:${targetWorktreeId}`, + agent: 'codex', + timeoutMs: 30_000 + }) + expect(started.result.state).toBe('ready') + const workerHandle = started.result.effects.find( + (effect) => effect.kind === 'terminal' && effect.role === 'agent' + )?.id + if (!workerHandle) { + throw new Error('worker-start did not return its agent terminal') + } + let worker: RuntimeTerminalSummary | undefined + await expect + .poll( + async () => { + worker = (await listRuntimeTerminals(client)).find( + (terminal) => terminal.handle === workerHandle + ) + return worker?.ptyId ?? null + }, + { timeout: 30_000, message: 'background worker never published its PTY identity' } + ) + .not.toBeNull() + if (!worker?.ptyId) { + throw new Error('Background worker did not publish its PTY') + } + const workerPtyId = worker.ptyId + const workerTabId = worker.tabId + const workerPaneKey = `${worker.tabId}:${worker.leafId}` + await backgroundMountTab(first.page, targetWorktreeId, workerTabId) + let dispatchCapability: string | null = null + await expect + .poll(() => { + dispatchCapability = readCompletedWorkerDispatchCapability() + return dispatchCapability + }) + .not.toBeNull() + if (!dispatchCapability) { + throw new Error('Background worker did not receive its dispatch capability') + } + const transcriptPath = seedCurrentCodexTranscript( + isolatedHome, + PROVIDER_SESSION_ID, + targetWorktreePath + ) + await first.page.evaluate( + ({ + agentCommand, + paneKey, + providerSessionId, + tabId, + terminalHandle, + transcriptPath, + worktreeId + }) => { + const state = window.__store?.getState() + if (!state) { + throw new Error('Renderer store unavailable') + } + const metadata = { tabId, worktreeId, terminalHandle } + const recovery = { + providerSession: { key: 'session_id' as const, id: providerSessionId, transcriptPath }, + launchConfig: { + agentCommand, + agentArgs: '--dangerously-bypass-approvals-and-sandbox', + agentEnv: {} + } + } + for (const agentState of ['working', 'done'] as const) { + state.setAgentStatus( + paneKey, + { state: agentState, prompt: 'Report completion and stay open', agentType: 'codex' }, + 'Settled background worker', + undefined, + metadata, + recovery + ) + } + }, + { + agentCommand: completedWorkerFakeCodexCommand, + paneKey: workerPaneKey, + providerSessionId: PROVIDER_SESSION_ID, + tabId: workerTabId, + terminalHandle: workerHandle, + transcriptPath, + worktreeId: targetWorktreeId + } + ) + const completed = await client.call<{ message: { type: string } }>( + 'orchestration.send', + { + from: workerHandle, + subject: 'Completed', + body: 'The fixture completed and stays open for inspection.', + type: 'worker_done', + payload: JSON.stringify({ + taskId: task.result.task.id, + dispatchId: started.result.dispatchId, + outcome: 'succeeded' + }) + }, + { orchestrationCapability: dispatchCapability } + ) + expect(completed.result.message.type).toBe('worker_done') + const taskBeforeRestart = ( + await client.call('orchestration.taskList', { run: run.result.run.id }) + ).result + const dispatchBeforeRestart = ( + await client.call('orchestration.dispatchShow', { task: task.result.task.id }) + ).result + + await session.close(firstApp) + firstApp = null + expectNoPersistedWorkerFence(session.userDataDir, workerPaneKey) + expect(readCompletedWorkerLedger().filter((event) => event.event === 'normal-exit')).toEqual( + [] + ) + + const launchesBeforeRestart = readCompletedWorkerLedger().filter( + (event) => event.event === 'spawn' + ) + if (daemonSessionGone) { + const daemonDir = path.join(session.userDataDir, 'daemon') + const daemon = new DaemonClient({ + socketPath: getDaemonSocketPath(daemonDir), + tokenPath: getDaemonTokenPath(daemonDir) + }) + try { + await daemon.ensureConnected() + await daemon.request('kill', { sessionId: workerPtyId, immediate: true }) + await expect + .poll(async () => { + const result = await daemon.request<{ sessions: { sessionId: string }[] }>( + 'listSessions', + undefined + ) + return result.sessions.some((entry) => entry.sessionId === workerPtyId) + }) + .toBe(false) + } finally { + daemon.disconnect() + } + } + const second = await session.launch() + secondApp = second.app + await waitForSessionReady(second.page) + if (!daemonSessionGone) { + // The restarted runtime must rediscover the daemon-owned worker before reveal. + await expect + .poll( + async () => + (await listRuntimeTerminals(client)).find( + (terminal) => terminal.ptyId === workerPtyId + )?.connected ?? null, + { timeout: 60_000, message: 'restarted runtime never rediscovered the worker PTY' } + ) + .toBe(true) + } + expect( + await second.page.evaluate( + ({ tabId, worktreeId }) => + Boolean( + window.__store?.getState().tabsByWorktree[worktreeId]?.some((tab) => tab.id === tabId) + ), + { tabId: workerTabId, worktreeId: targetWorktreeId } + ) + ).toBe(true) + + // Hidden mount, then click to reveal: reveal runs the missing-session reconciler. + await backgroundMountTab(second.page, targetWorktreeId, workerTabId) + // Poll, don't sample: main's cache learns the session when the pane's deferred reattach lands, + // and backgroundMountTab only waits for the pane manager to exist. A restarted main that never + // attaches stays false for the whole window, which is the regression this guards. + if (!daemonSessionGone) { + await expect + .configure({ soft: true }) + .poll(() => second.page.evaluate((ptyId) => window.api.pty.hasPty(ptyId), workerPtyId), { + timeout: 20_000, + message: 'liveness before reveal' + }) + .toBe(true) + } + await second.page.evaluate( + ({ tabId, worktreeId }) => { + const store = window.__store + if (!store) { + throw new Error('Renderer store unavailable') + } + type Transition = { + activeWorktreeId: string | null + tabPresent: boolean + leafPtyIds: string[] + activeTabId: string | null + } + const snapshot = (state: ReturnType): Transition => ({ + activeWorktreeId: state.activeWorktreeId ?? null, + tabPresent: Boolean(state.tabsByWorktree[worktreeId]?.some((tab) => tab.id === tabId)), + leafPtyIds: Object.values(state.terminalLayoutsByTabId[tabId]?.ptyIdsByLeafId ?? {}), + activeTabId: state.activeTabIdByWorktree[worktreeId] ?? null + }) + const transitions: Transition[] = [snapshot(store.getState())] + const e2eWindow = window as typeof window & { __orcaRevealTransitions?: Transition[] } + e2eWindow.__orcaRevealTransitions = transitions + store.subscribe((state) => { + const next = snapshot(state) + if (JSON.stringify(next) !== JSON.stringify(transitions.at(-1))) { + transitions.push(next) + } + }) + }, + { tabId: workerTabId, worktreeId: targetWorktreeId } + ) + await second.page + .locator(`[role="option"][data-worktree-id="${targetWorktreeId}"]`) + .first() + .click() + const visibleTab = second.page + .locator(`[data-testid="sortable-tab"][data-tab-id="${workerTabId}"]`) + .first() + await visibleTab.click({ timeout: 10_000 }) + await expect(visibleTab).toBeVisible() + await ensureTerminalVisible(second.page) + // Give the reconciler's async verdict time to land; the tab must never have left. + await second.page.waitForTimeout(3_000) + const transitions = await second.page.evaluate( + () => + ( + window as typeof window & { + __orcaRevealTransitions?: { + activeWorktreeId: string | null + tabPresent: boolean + leafPtyIds: string[] + }[] + } + ).__orcaRevealTransitions ?? [] + ) + // Pre-fix this read: leaf binding cleared -> tab removed -> worktree deselected -> tab re-added by graph sync. + expect( + transitions.filter( + (step) => !step.tabPresent || (!daemonSessionGone && step.leafPtyIds.length === 0) + ), + 'reveal must not tear the settled worker tab down' + ).toEqual([]) + expect(transitions.at(-1)?.activeWorktreeId).toBe(targetWorktreeId) + expect( + await second.page.evaluate( + (tabId) => Boolean(window.__paneManagers?.get(tabId)), + workerTabId + ) + ).toBe(true) + if (!daemonSessionGone) { + expect( + (await listRuntimeTerminals(client)).find((terminal) => terminal.ptyId === workerPtyId) + ?.connected + ).toBe(true) + expect( + readCompletedWorkerLedger().filter((event) => event.event === 'normal-exit') + ).toEqual([]) + } + const newLaunches = readCompletedWorkerLedger() + .filter((event) => event.event === 'spawn') + .slice(launchesBeforeRestart.length) + if (daemonSessionGone) { + expect(newLaunches.length).toBeLessThanOrEqual(1) + for (const launch of newLaunches) { + // Codex's --resume equivalent is the `resume ` subcommand. + expect(launch.args).toContain('resume') + expect(launch.args).toContain(PROVIDER_SESSION_ID) + } + const listed = await client.call<{ + workers: { dispatchId: string; terminalState: string; workerState: string }[] + }>('orchestration.workerList', { run: run.result.run.id }) + await testInfo.attach('resumed-worker-accounting', { + body: JSON.stringify({ newLaunches, workers: listed.result.workers }), + contentType: 'application/json' + }) + expect(listed.result.workers).toEqual([ + expect.objectContaining({ + dispatchId: started.result.dispatchId, + terminalState: 'retained', + workerState: 'succeeded' + }) + ]) + } else { + expect(newLaunches).toEqual([]) + expect( + await second.page.evaluate((ptyId) => window.api.pty.hasPty(ptyId), workerPtyId) + ).toBe(true) + } + expect(readCompletedWorkerLedger().filter((event) => event.event === 'normal-exit')).toEqual( + [] + ) + expect( + (await client.call('orchestration.taskList', { run: run.result.run.id })).result + ).toEqual(taskBeforeRestart) + expect( + (await client.call('orchestration.dispatchShow', { task: task.result.task.id })).result + ).toEqual(dispatchBeforeRestart) + await expect(visibleTab).toBeVisible() + const paneKeys = await second.page.evaluate((tabId) => { + const layout = window.__store?.getState().terminalLayoutsByTabId[tabId] + const leaves: string[] = [] + const visit = (node: NonNullable['root']) => { + if (node.type === 'leaf') { + leaves.push(`${tabId}:${node.leafId}`) + } else { + visit(node.first) + visit(node.second) + } + } + if (layout?.root) { + visit(layout.root) + } + return leaves + }, workerTabId) + expect(paneKeys).toContain(workerPaneKey) + expect( + await secondApp.evaluate(({ BrowserWindow }) => + BrowserWindow.getAllWindows().map((window) => ({ + visible: window.isVisible(), + focused: window.isFocused() + })) + ) + ).toEqual([{ visible: false, focused: false }]) + await second.page.screenshot({ path: testInfo.outputPath('settled-worker-revealed.png') }) + await session.close(secondApp) + secondApp = null + const persisted = readPersistedSession(session.userDataDir) + expectNoPersistedWorkerFence(session.userDataDir, workerPaneKey) + expect( + persisted.tabsByWorktree[targetWorktreeId].some( + (tab: { id: string }) => tab.id === workerTabId + ) + ).toBe(true) + expect(persisted.terminalLayoutsByTabId[workerTabId]).toBeDefined() + if (!daemonSessionGone) { + expect( + Object.values(persisted.terminalLayoutsByTabId[workerTabId].ptyIdsByLeafId) + ).toContain(workerPtyId) + } + } finally { + if (secondApp) { + await session.close(secondApp) + } + if (firstApp) { + await session.close(firstApp) + } + await session.dispose() + } + }) +} From bba68b1bddf1276c8bd27ad4ca41efcbd4260321 Mon Sep 17 00:00:00 2001 From: Neil <4138956+nwparker@users.noreply.github.com> Date: Tue, 8 Sep 2026 03:06:54 -0700 Subject: [PATCH 10/59] fix(pi): finish the dialog-wait signal on every surface (#19533) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(pi): carry modal waits to mobile and stop losing the dialog close Follow-ups to #18836, from its readiness review. - Paint pi's `!` needs-input state marker while a dialog is open, so the 80ms spinner frame stops repainting a working title over a mid-turn wait. Mobile and the CLI read the title, so they saw `working` where the desktop already showed `waiting`. - Keep the assistant reply that lands while a dialog is open. The modal guard cleared tool fields and the `message_end` capture with them, so a turn ending under a dialog left the preview on the previous message. - Report `ui_prompt_end` even when `ctx.isIdle()` throws on a runner the modal itself invalidated; the lost post stranded the pane on `waiting`. - Declare the `esbuild` the runtime smoke tool imports. * fix(pi): hold the needs-input marker until the dialog actually closes From review of the previous commit. - Settling under an open dialog no longer retires the marker. stopAnimation painted the plain title unconditionally, so agent_settled, a resolved agent_end, or an idle auto_compaction_end erased it mid-dialog — and because that also cleared the timer, the close then painted the plain title again and the wait was lost for good. - Track the dialog as a boolean, not a depth counter. Pi does its own nesting accounting and emits one pair per stack, which is what the status extension already assumes; two files disagreeing on that would have let an inner close release the outer wait. - Reset the flag on agent_start in both extensions. A turn cannot begin under a dialog holding input focus, so it is the one boundary that can recover a close that never arrived instead of pinning the pane forever. - Leave OMP to its approval events: it reports waits through those already, and painting the marker there too would put title and hook in disagreement. * fix(pi): do not ring the completion bell for a dialog that lost its close From review of the previous commit. - Report working, not done, when ui_prompt_end's isIdle() throws. done is not cosmetic: it reaches dispatchCompletion and fires the pane's finished notification, so a turn that is still running would announce itself. The real done still arrives from agent_end/agent_settled. - Keep the idle-maintenance frame cap accruing while a dialog holds the title, so a dialog left open cannot suspend the guard that stops a compaction spinner whose end event never came. - Guard the dialog handlers against a ctx without ui. The source is generated and untypechecked, and pi does not document the ctx it passes these two events; a TypeError there would surface on every dialog. * fix(pi): let a turn still complete after a dialog loses its runner From review of the previous commit. - Re-arm the completion report when ui_prompt_end's isIdle() throws. The fallback posts working, but the finished turn had already reported its end, so nothing further would ever fire and an idle pane sat spinning. - Count dialog depth in both extensions instead of trusting pi to emit one pair per stack. The guarantee is undocumented, and if it ever does emit a pair per dialog, an inner close would release the wait the outer dialog still holds. A counter costs nothing and drops the dependency. * fix(pi): decide a dialog close from turn state, not from a guess From review of the previous commit. - Fall back to agentEndReported when ctx.isIdle is unavailable or throws. The previous guess of working stranded the common case — a dialog opened at idle — because no later event was coming to correct it, and the agentEndReported re-arm it relied on could not fire either. A turn that already reported its end is not still running, and that is knowledge this process holds without needing ctx at all. - Only suppress spinner frames once the marker is actually painted. Pi may pass a ctx with no ui, and freezing the title on its last working frame is the opposite of what the marker is for. - Gate the titlebar dialog handlers on the OMP runtime too, not just the installed kind: a bare-shell OMP launch runs inside a pi-kind pane, and the status extension already defers there. Extracted that check so both extensions share it rather than carrying two copies. * fix(pi): treat a pane that never ran a turn as idle, not busy From review of the previous commit. - Track turn-in-flight separately from agentEndReported. That flag also dedupes the completion post, so it starts false on a pane that has not run a turn — which read as still-running and left a dialog opened before the first prompt spinning forever. - Retry the marker paint on each dialog open instead of only the outermost, so an outer ctx without ui cannot decide the whole nested stack goes unmarked. - Fall back to the opening ctx when the close carries no ui. Nothing else clears the needs-input marker, so the pane would have kept asking for attention until the next turn. * fix(pi): keep a dying dialog ctx from stranding the needs-input marker The close path paints through the ctx captured at open time, which is the one a session-switching modal is most likely to have invalidated. Guard both paint sites so a throw cannot reject the handler and leave the title on the needs-input marker, and make local turn state the floor for the status extension's idleness verdict instead of a fallback. * fix(pi): hold the dialog wait against pi's own title writes and lost closes Reviewed against real Pi 0.85.1 source rather than inference: - ctx.ui is a getter that calls assertActive() and throws once a session- replacing dialog invalidates the runner, so optional chaining never screened it out and the probe sat outside the try. A throw landed after the depth decrement but before markerPainted cleared, stranding the needs-input marker until the next turn. - Pi writes the same terminal title from its own writers with no event we observe, so the marker is now re-asserted rather than merely not overwritten, on a slow timer that outlives the spinner and its cap. - resetExtensionUI drops an open dialog without resolving its promise, so a replaced or reloaded session never emits the matching ui_prompt_end. Both extensions now release the wait on session_start and shutdown. * fix(pi): build the title inside the guard, not as an argument to it paintTitle caught the setTitle throw but not the two calls one argument to its left: pi.getSessionName() asserts runner liveness the same way ctx.ui does, and process.cwd() throws ENOENT once the worktree is unlinked under a live pane. Four of the six call sites are timer callbacks, where an escape is an uncaught exception and pi exits(1) through its own handler — so the cwd route was reachable today. paintTitle now takes a builder and runs it inside the existing try. * fix(pi): let only the pane-owning process assert the needs-input marker The spinner is harmlessly per-process, but the marker is status the pane reports, and child agents inherit ORCA_PANE_KEY. Gate the two dialog handlers on a PID claim, mirroring ORCA_PI_STATUS_OWNED in the status hook. --- package.json | 1 + pnpm-lock.yaml | 3 + .../pi/agent-status-extension-source.test.ts | 10 +- src/main/pi/agent-status-extension-source.ts | 4 +- src/main/pi/agent-status-handler-source.ts | 7 + .../agent-status-runtime-detection-source.ts | 43 ++- src/main/pi/agent-status-ui-prompt-source.ts | 31 +- src/main/pi/agent-status-ui-prompt.test.ts | 141 ++++++- src/main/pi/titlebar-extension-service.ts | 2 +- src/main/pi/titlebar-extension-source.test.ts | 351 +++++++++++++++++- src/main/pi/titlebar-extension-source.ts | 166 ++++++++- .../providers/pi-family-tool-fields.ts | 10 +- 12 files changed, 719 insertions(+), 50 deletions(-) diff --git a/package.json b/package.json index 321f2ada9ed..0536f4fd606 100644 --- a/package.json +++ b/package.json @@ -243,6 +243,7 @@ "electron-vite": "^5.0.0", "emoji-picker-react": "^4.19.1", "emojibase-data": "17.0.0", + "esbuild": "^0.25.12", "happy-dom": "^20.11.8", "html-to-image": "^1.11.13", "husky": "^9.1.7", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9ee9fff6785..7add63b397b 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -366,6 +366,9 @@ importers: emojibase-data: specifier: 17.0.0 version: 17.0.0(emojibase@17.0.0) + esbuild: + specifier: ^0.25.12 + version: 0.25.12 happy-dom: specifier: ^20.11.8 version: 20.11.8 diff --git a/src/main/pi/agent-status-extension-source.test.ts b/src/main/pi/agent-status-extension-source.test.ts index fed179837db..fa9823d76dd 100644 --- a/src/main/pi/agent-status-extension-source.test.ts +++ b/src/main/pi/agent-status-extension-source.test.ts @@ -481,12 +481,14 @@ describe('getPiAgentStatusExtensionSource', () => { await handlerCall }) - it('leaves runtime shutdown to PTY teardown instead of reporting turn completion', () => { + it('leaves runtime shutdown to PTY teardown instead of reporting turn completion', async () => { const harness = createHarness({ kind: 'pi' }) - // Why: Pi emits session_shutdown for reload/new/resume/fork while its PTY - // stays alive. agent_end is the only extension event that proves done. - expect(harness.handlers.session_shutdown).toBeUndefined() + // Why: Pi emits session_shutdown for reload/new/resume/fork while its PTY stays + // alive. agent_end is the only extension event that proves done, so the handler + // exists solely to release a dialog Pi tore down without a close. + await harness.callHook('session_shutdown') + expect(harness.fetchMock).not.toHaveBeenCalled() }) it('bounds stalled delivery to one active request and the latest pending status', async () => { diff --git a/src/main/pi/agent-status-extension-source.ts b/src/main/pi/agent-status-extension-source.ts index 8b046e0db79..38775ca1973 100644 --- a/src/main/pi/agent-status-extension-source.ts +++ b/src/main/pi/agent-status-extension-source.ts @@ -101,7 +101,7 @@ export function getPiAgentStatusExtensionSource(kind: PiAgentKind = 'pi'): strin '// Orca receiver from building an unbounded queue of obsolete snapshots.', 'const HOOK_POST_TIMEOUT_MS = 1000', 'let activePost = false', - ...(kind === 'pi' ? ['let piUiPromptActive = false'] : []), + ...(kind === 'pi' ? ['let piUiPromptDepth = 0', 'let piTurnInFlight = false'] : []), 'let pendingPost: { hookEventName: string; extra: Record; metadata: Record; ompRuntime: boolean } | null = null', ...sessionMetadataSourceLines, '', @@ -167,7 +167,7 @@ export function getPiAgentStatusExtensionSource(kind: PiAgentKind = 'pi'): strin ' hookEventName,', // Why: every coalesced snapshot must retain an open modal, not just its start event. kind === 'pi' - ? ' extra: { ...extra, ...(!ompRuntime && piUiPromptActive ? { ui_prompt_active: true } : {}) },' + ? ' extra: { ...extra, ...(!ompRuntime && piUiPromptDepth > 0 ? { ui_prompt_active: true } : {}) },' : ' extra,', ' metadata: getPostSessionMetadata(ompRuntime),', ' ompRuntime,', diff --git a/src/main/pi/agent-status-handler-source.ts b/src/main/pi/agent-status-handler-source.ts index a769bfc74d2..9d02abbd78d 100644 --- a/src/main/pi/agent-status-handler-source.ts +++ b/src/main/pi/agent-status-handler-source.ts @@ -9,6 +9,7 @@ export function getPiAgentStatusHandlerSourceLines(kind: PiAgentKind): string[] ? [ " pi.on('session_start', (event, ctx) => {", ' updateSessionMetadata(ctx)', + ...(kind === 'pi' ? [' piUiPromptDepth = 0'] : []), ' // Why: /reload re-registers the active session, but it is not a', ' // turn boundary and must not clear the visible status or unread state.', " if (event.reason === 'reload') return", @@ -105,6 +106,9 @@ export function getPiAgentStatusHandlerSourceLines(kind: PiAgentKind): string[] ...captureSessionMetadata, ' clearPendingAgentEndCheck()', ' agentEndReported = false', + // Why: a turn cannot begin under a dialog holding input focus, so this is the one + // boundary that can recover a modal whose close never arrived. + ...(kind === 'pi' ? [' piUiPromptDepth = 0', ' piTurnInFlight = true'] : []), " post('agent_start')", ' })', '', @@ -168,6 +172,9 @@ export function getPiAgentStatusHandlerSourceLines(kind: PiAgentKind): string[] ' function postAgentEndOnce(): void {', ' if (agentEndReported) return', ' agentEndReported = true', + // Why: distinct from agentEndReported, which also dedupes the completion post and so + // starts false on a pane that has not run a turn yet — that pane is idle, not busy. + ...(kind === 'pi' ? [' piTurnInFlight = false'] : []), " post('agent_end')", ' }', '', diff --git a/src/main/pi/agent-status-runtime-detection-source.ts b/src/main/pi/agent-status-runtime-detection-source.ts index 5d9cdbf6de8..6ba5edb69b9 100644 --- a/src/main/pi/agent-status-runtime-detection-source.ts +++ b/src/main/pi/agent-status-runtime-detection-source.ts @@ -1,26 +1,15 @@ import type { PiAgentKind } from '../../shared/pi-agent-kind' -export function getPiAgentStatusRuntimeDetectionSourceLines(kind: PiAgentKind): string[] { - if (kind === 'prime-agent') { - return [ - `const CONFIGURED_HOOK_PATH = '/hook/${kind}'`, - '', - 'function isOmpRuntime(): boolean {', - ' return false', - '}', - '', - 'function resolveHookPath(_ompRuntime: boolean): string {', - ' return CONFIGURED_HOOK_PATH', - '}' - ] - } - +/** Why: a bare-shell OMP launch runs inside a pi-kind pane, so every extension that has to + * defer to OMP's own approval events needs this check — not just the status extension it + * was first written for. */ +export function getPiOmpRuntimeDetectionSourceLines(configuredHookPath: string): string[] { return [ 'function processName(value: unknown): string {', " return String(value || '').split(/[\\\\/]/).pop()?.toLowerCase() || ''", '}', '', - `const CONFIGURED_HOOK_PATH = '/hook/${kind}'`, + `const CONFIGURED_HOOK_PATH = '${configuredHookPath}'`, 'let cachedOmpRuntime: boolean | null = null', '', 'function isOmpRuntime(): boolean {', @@ -39,7 +28,27 @@ export function getPiAgentStatusRuntimeDetectionSourceLines(kind: PiAgentKind): " ['omp', 'omp.js', 'omp.sh', 'omp.cmd', 'omp.exe', 'omp.bat'].includes(name)", ' )', ' return cachedOmpRuntime', - '}', + '}' + ] +} + +export function getPiAgentStatusRuntimeDetectionSourceLines(kind: PiAgentKind): string[] { + if (kind === 'prime-agent') { + return [ + `const CONFIGURED_HOOK_PATH = '/hook/${kind}'`, + '', + 'function isOmpRuntime(): boolean {', + ' return false', + '}', + '', + 'function resolveHookPath(_ompRuntime: boolean): string {', + ' return CONFIGURED_HOOK_PATH', + '}' + ] + } + + return [ + ...getPiOmpRuntimeDetectionSourceLines(`/hook/${kind}`), '', 'function resolveHookPath(ompRuntime: boolean): string {', ' // Why: runtime detection keeps a bare-shell OMP launch from reporting as Pi.', diff --git a/src/main/pi/agent-status-ui-prompt-source.ts b/src/main/pi/agent-status-ui-prompt-source.ts index 2f1ed92c9ae..5790c5c30a7 100644 --- a/src/main/pi/agent-status-ui-prompt-source.ts +++ b/src/main/pi/agent-status-ui-prompt-source.ts @@ -1,6 +1,6 @@ import type { PiAgentKind } from '../../shared/pi-agent-kind' -/** Pi owns nested prompt depth and emits one pair around select/confirm/input/editor/custom. */ +/** Mirrors the titlebar extension's dialog tracking so both agree on when the wait ends. */ export function getPiAgentStatusUiPromptHandlerSourceLines(kind: PiAgentKind): string[] { if (kind !== 'pi') { return [] @@ -9,14 +9,35 @@ export function getPiAgentStatusUiPromptHandlerSourceLines(kind: PiAgentKind): s return [ " pi.on('ui_prompt_start', () => {", ' if (isOmpRuntime()) return', - ' piUiPromptActive = true', + ' piUiPromptDepth++', + ' if (piUiPromptDepth > 1) return', " post('ui_prompt_start')", ' })', '', " pi.on('ui_prompt_end', (_event, ctx) => {", - ' if (isOmpRuntime() || !piUiPromptActive) return', - ' piUiPromptActive = false', - " post('ui_prompt_end', { is_idle: ctx?.isIdle?.() === true })", + ' if (isOmpRuntime() || piUiPromptDepth === 0) return', + ' piUiPromptDepth--', + ' if (piUiPromptDepth > 0) return', + ' // Why: ctx.isIdle throws outright once a session-switching modal invalidates the', + ' // runner (it calls assertActive), so local turn state is the floor, not a fallback:', + ' // with no turn in flight, no later event is coming to correct a working verdict, so', + ' // only consult ctx when this process believes work is running.', + ' let isIdle = !piTurnInFlight', + ' try {', + " if (!isIdle && typeof ctx?.isIdle === 'function') isIdle = ctx.isIdle() === true", + ' } catch {', + ' // Why: a runner this very modal invalidated cannot answer; keep the local verdict.', + ' }', + " post('ui_prompt_end', { is_idle: isIdle })", + ' })', + '', + " pi.on('session_shutdown', () => {", + ' if (isOmpRuntime()) return', + ' // Why: pi tears an open dialog down through resetExtensionUI without resolving its', + ' // promise, so a replaced session never emits the matching ui_prompt_end and the wait', + ' // would stick forever. Reset without posting: shutdown is not a turn boundary, and', + ' // the session_start that follows republishes the corrected state.', + ' piUiPromptDepth = 0', ' })', '' ] diff --git a/src/main/pi/agent-status-ui-prompt.test.ts b/src/main/pi/agent-status-ui-prompt.test.ts index 4ab9341589e..d91ccc37b34 100644 --- a/src/main/pi/agent-status-ui-prompt.test.ts +++ b/src/main/pi/agent-status-ui-prompt.test.ts @@ -92,11 +92,21 @@ describe('Pi UI prompt status', () => { expect(harness.statuses.map((status) => status?.payload.state)).toEqual(['waiting', 'done']) }) - it('does not infer done when the context cannot establish idleness', async () => { + it('returns a pane that never ran a turn to done when idleness is unreadable', async () => { const harness = createHarness() await post(harness, 'ui_prompt_start') await post(harness, 'ui_prompt_end') - expect(harness.statuses.at(-1)?.payload.state).toBe('working') + // Why: no turn has started, so the pane is idle — reporting working would spin forever. + expect(harness.statuses.at(-1)?.payload.state).toBe('done') + }) + + it('trusts local turn state over a ctx that claims work on an idle pane', async () => { + const harness = createHarness() + await post(harness, 'ui_prompt_start') + await harness.callHook('ui_prompt_end', {}, { isIdle: () => false }) + await flushPosts() + // Why: no turn ever started, so nothing later would correct a working verdict. + expect(harness.statuses.at(-1)?.payload.state).toBe('done') }) it('lets the normal settlement hook finish work after a modal closes', async () => { @@ -118,20 +128,139 @@ describe('Pi UI prompt status', () => { const harness = createHarness() await post(harness, 'ui_prompt_start') harness.reload() - await post(harness, 'session_start', { reason: 'reload' }) await post(harness, 'tool_execution_end', { toolName: 'bash' }) + // Why: re-registering handlers is not a session boundary and must not lose the wait. expect(harness.statuses.at(-1)?.payload.state).toBe('waiting') }) - it('keeps a session-switching modal blocked until it actually closes', async () => { + it('releases a modal that a session replacement tore down without a close', async () => { const harness = createHarness() await post(harness, 'before_agent_start', { prompt: 'Old session prompt' }) await post(harness, 'ui_prompt_start') - await post(harness, 'session_start', { reason: 'switch' }) expect(harness.statuses.at(-1)?.payload.state).toBe('waiting') - expect(harness.statuses.at(-1)?.payload.prompt).toBe('') + // Why: pi hides the dialog through resetExtensionUI without resolving its promise, + // so no ui_prompt_end is ever emitted — these two boundaries are the only release. + await post(harness, 'session_shutdown') + await post(harness, 'session_start', { reason: 'switch' }) + await post(harness, 'tool_execution_end', { toolName: 'bash' }) + expect(harness.statuses.at(-1)?.payload.state).not.toBe('waiting') + }) + + it('releases a modal dropped by a reload that emits no shutdown', async () => { + const harness = createHarness() + await post(harness, 'ui_prompt_start') + await post(harness, 'session_start', { reason: 'reload' }) + await post(harness, 'tool_execution_end', { toolName: 'bash' }) + expect(harness.statuses.at(-1)?.payload.state).not.toBe('waiting') + }) + + it('still captures the assistant reply that lands while a modal is open', async () => { + const harness = createHarness() + await post(harness, 'agent_start') + await post(harness, 'message_end', { + message: { role: 'assistant', content: [{ type: 'text', text: 'Before modal' }] } + }) + await post(harness, 'ui_prompt_start') + await post(harness, 'message_end', { + message: { role: 'assistant', content: [{ type: 'text', text: 'Final reply' }] } + }) await harness.callHook('ui_prompt_end', {}, { isIdle: () => true }) await flushPosts() + expect(harness.statuses.at(-1)?.payload).toMatchObject({ + state: 'done', + lastAssistantMessage: 'Final reply' + }) + expect(harness.statuses.at(-1)?.payload.toolName).toBeUndefined() + expect(harness.statuses.at(-1)?.payload.interactivePrompt).toBeUndefined() + }) + + it('still reports the close when the modal invalidated its own runner', async () => { + const harness = createHarness() + await post(harness, 'ui_prompt_start') + await harness.callHook( + 'ui_prompt_end', + {}, + { + isIdle: () => { + throw new Error('extension runner is no longer active') + } + } + ) + await flushPosts() + // Why: a lost close would strand the pane on waiting; no turn is running, so done. + expect(harness.statuses.at(-1)?.payload.state).toBe('done') + }) + + it('keeps a mid-turn modal working when its runner throws on close', async () => { + const harness = createHarness() + await post(harness, 'agent_start') + await post(harness, 'ui_prompt_start') + await harness.callHook( + 'ui_prompt_end', + {}, + { + isIdle: () => { + throw new Error('extension runner is no longer active') + } + } + ) + await flushPosts() + // Why: the turn is still in flight, so done would ring the completion bell early. + expect(harness.statuses.at(-1)?.payload.state).toBe('working') + await post(harness, 'agent_settled') + expect(harness.statuses.at(-1)?.payload.state).toBe('done') + }) + + it('recovers on a new turn when a modal close was lost', async () => { + const harness = createHarness() + await post(harness, 'ui_prompt_start') + expect(harness.statuses.at(-1)?.payload.state).toBe('waiting') + // Why: a turn cannot begin under a dialog holding input focus, so this is recovery. + await post(harness, 'agent_start') + await post(harness, 'tool_execution_end', { toolName: 'bash' }) + expect(harness.statuses.at(-1)?.payload.state).toBe('working') + }) + + it('keeps the wait until the outermost of nested modals closes', async () => { + const harness = createHarness() + await post(harness, 'ui_prompt_start') + await post(harness, 'ui_prompt_start') + await harness.callHook('ui_prompt_end', {}, { isIdle: () => true }) + await flushPosts() + expect(harness.statuses.at(-1)?.payload.state).toBe('waiting') + await harness.callHook('ui_prompt_end', {}, { isIdle: () => true }) + await flushPosts() + expect(harness.statuses.at(-1)?.payload.state).toBe('done') + }) + + it('returns an idle pane to done when its modal lost the runner', async () => { + const harness = createHarness() + await post(harness, 'agent_start') + await post(harness, 'agent_settled') + expect(harness.statuses.at(-1)?.payload.state).toBe('done') + await post(harness, 'ui_prompt_start') + await harness.callHook( + 'ui_prompt_end', + {}, + { + isIdle: () => { + throw new Error('extension runner is no longer active') + } + } + ) + await flushPosts() + // Why: the turn already reported its end, so no later event is coming to correct a + // guess of working — fall back to what this process knows rather than strand it. + expect(harness.statuses.at(-1)?.payload.state).toBe('done') + }) + + it('keeps a mid-turn modal working when its close cannot read idleness', async () => { + const harness = createHarness() + await post(harness, 'agent_start') + await post(harness, 'ui_prompt_start') + await post(harness, 'ui_prompt_end') + expect(harness.statuses.at(-1)?.payload.state).toBe('working') + await post(harness, 'agent_settled') expect(harness.statuses.at(-1)?.payload.state).toBe('done') }) diff --git a/src/main/pi/titlebar-extension-service.ts b/src/main/pi/titlebar-extension-service.ts index 3a43ce4ac38..8a093096f4e 100644 --- a/src/main/pi/titlebar-extension-service.ts +++ b/src/main/pi/titlebar-extension-service.ts @@ -150,7 +150,7 @@ export class PiTitlebarExtensionService { if (kind !== 'prime-agent') { this.writeManagedExtension( join(extensionsDir, ORCA_PI_EXTENSION_FILE), - withOrcaManagedExtensionMarker(getPiTitlebarExtensionSource()) + withOrcaManagedExtensionMarker(getPiTitlebarExtensionSource(kind)) ) this.writeManagedExtension( join(extensionsDir, ORCA_PI_PREFILL_EXTENSION_FILE), diff --git a/src/main/pi/titlebar-extension-source.test.ts b/src/main/pi/titlebar-extension-source.test.ts index bee2e007c57..be21f8c6a16 100644 --- a/src/main/pi/titlebar-extension-source.test.ts +++ b/src/main/pi/titlebar-extension-source.test.ts @@ -3,6 +3,8 @@ import { runInNewContext } from 'node:vm' import ts from 'typescript-api' import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { detectAgentStatusFromTitle } from '../../shared/agent-detection' +import type { PiAgentKind } from '../../shared/pi-agent-kind' import { getPiTitlebarExtensionSource } from './titlebar-extension-source' const BRAILLE_RE = /[⠀-⣿]/ @@ -23,8 +25,19 @@ type Harness = { const CWD = '/repo/orca-app' const SESSION = 'omp-session' const IDLE_TITLE = `π - ${SESSION} - orca-app` +const PROMPT_TITLE = `π ! ${SESSION} - orca-app` -function createHarness(options: { paneKey?: string; isIdle?: () => boolean } = {}): Harness { +function createHarness( + options: { + paneKey?: string + isIdle?: () => boolean + kind?: PiAgentKind + processTitle?: string + cwdImpl?: () => string + sessionNameImpl?: () => string + env?: Record + } = {} +): Harness { const titles: string[] = [] const ctx: TitlebarContext = { ui: { @@ -48,8 +61,11 @@ function createHarness(options: { paneKey?: string; isIdle?: () => boolean } = { module, exports: module.exports, process: { - env: { ORCA_PANE_KEY: options.paneKey ?? 'pane-1' }, - cwd: () => CWD + env: { ORCA_PANE_KEY: options.paneKey ?? 'pane-1', ...options.env }, + pid: options.env?.ORCA_PI_TITLE_MARKER_OWNED === undefined ? 111 : 222, + title: options.processTitle ?? 'pi', + argv: ['node', 'pi'], + cwd: options.cwdImpl ?? (() => CWD) }, console: { warn: vi.fn(), error: vi.fn(), log: vi.fn() }, Promise, @@ -61,7 +77,7 @@ function createHarness(options: { paneKey?: string; isIdle?: () => boolean } = { } as Record context.globalThis = context - const output = ts.transpileModule(getPiTitlebarExtensionSource(), { + const output = ts.transpileModule(getPiTitlebarExtensionSource(options.kind ?? 'pi'), { compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2020 } }).outputText runInNewContext(output, context) @@ -76,7 +92,7 @@ function createHarness(options: { paneKey?: string; isIdle?: () => boolean } = { on(name: string, handler: HookHandler) { handlers[name] = handler }, - getSessionName: () => SESSION + getSessionName: options.sessionNameImpl ?? (() => SESSION) }) return { @@ -247,4 +263,329 @@ describe('getPiTitlebarExtensionSource', () => { expect(vi.getTimerCount()).toBe(0) expect(harness.lastTitle()).toBe(IDLE_TITLE) }) + + it('marks a mid-turn dialog as needing input and holds it against the spinner', async () => { + const harness = createHarness() + + await harness.callHook('agent_start') + await harness.callHook('ui_prompt_start') + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + expect(detectAgentStatusFromTitle(PROMPT_TITLE)).toBe('permission') + + // Why: the spinner interval keeps running, but must not repaint over the marker. + await vi.advanceTimersByTimeAsync(800) + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + + await harness.callHook('ui_prompt_end') + expect(harness.lastTitle()).toMatch(BRAILLE_RE) + expect(vi.getTimerCount()).toBe(1) + }) + + it('returns an idle pane to its plain title when the dialog closes', async () => { + const harness = createHarness() + + await harness.callHook('ui_prompt_start') + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + + await harness.callHook('ui_prompt_end') + expect(harness.lastTitle()).toBe(IDLE_TITLE) + expect(vi.getTimerCount()).toBe(0) + }) + + it('only the outermost of nested dialogs moves the title', async () => { + const harness = createHarness() + + await harness.callHook('agent_start') + await harness.callHook('ui_prompt_start') + await harness.callHook('ui_prompt_start') + await harness.callHook('ui_prompt_end') + // Why: the outer dialog still holds input focus. + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + + await harness.callHook('ui_prompt_end') + expect(harness.lastTitle()).toMatch(BRAILLE_RE) + }) + + it('ignores an unmatched dialog close', async () => { + const harness = createHarness() + + await harness.callHook('agent_start') + const titleCount = harness.titles.length + await harness.callHook('ui_prompt_end') + expect(harness.titles.length).toBe(titleCount) + }) + + it.each(['agent_settled', 'session_shutdown'])( + 'keeps the marker when %s lands under an open dialog', + async (name) => { + const harness = createHarness() + + await harness.callHook('agent_start') + await harness.callHook('ui_prompt_start') + await harness.callHook(name) + // Why: settling does not answer the dialog, so the pane still needs the user. + const expected = name === 'session_shutdown' ? IDLE_TITLE : PROMPT_TITLE + expect(harness.lastTitle()).toBe(expected) + // Why: settling stops the spinner but must leave the marker re-assert running, or + // pi's own next title write would silently retire a dialog that is still open. + expect(vi.getTimerCount()).toBe(name === 'session_shutdown' ? 0 : 1) + } + ) + + it('keeps the marker across an idle compaction that finishes under a dialog', async () => { + const harness = createHarness() + + await harness.callHook('ui_prompt_start') + await harness.callHook('auto_compaction_start', { reason: 'idle' }) + await harness.callHook('auto_compaction_end') + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + }) + + it('recovers the spinner on a new turn when a dialog close was lost', async () => { + const harness = createHarness() + + await harness.callHook('ui_prompt_start') + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + + // Why: a turn cannot start under a dialog holding input focus, so this is recovery. + await harness.callHook('agent_start') + await vi.advanceTimersByTimeAsync(80) + expect(harness.lastTitle()).toMatch(BRAILLE_RE) + }) + + it('leaves the marker to OMP approval events instead of painting it', () => { + expect(createHarness({ kind: 'omp' }).handlers.ui_prompt_start).toBeUndefined() + }) + + it('still caps idle maintenance while a dialog holds the title', async () => { + const harness = createHarness() + + await harness.callHook('auto_compaction_start', { reason: 'idle' }) + await harness.callHook('ui_prompt_start') + // Why: an open dialog must not suspend the cap that stops a stranded spinner. + vi.advanceTimersByTime(301_000) + + // Why: the spinner is capped, but the marker re-assert survives it — the dialog is + // still open, so the pane must keep reporting that it needs input. + expect(vi.getTimerCount()).toBe(1) + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + }) + + it('survives a dialog event that carries no ui context', async () => { + const harness = createHarness() + + await harness.callHook('agent_start') + await expect(harness.handlers.ui_prompt_start?.({}, undefined)).resolves.toBeUndefined() + await expect(harness.handlers.ui_prompt_end?.({}, undefined)).resolves.toBeUndefined() + }) + + it('keeps spinning when the dialog event could not paint the marker', async () => { + const harness = createHarness() + + await harness.callHook('agent_start') + await harness.handlers.ui_prompt_start?.({}, undefined) + // Why: suppressing frames without a marker would freeze the title mid-spinner, which + // still reads as working — the opposite of what the marker is for. + await vi.advanceTimersByTimeAsync(160) + expect(harness.lastTitle()).toMatch(BRAILLE_RE) + }) + + it('marks a nested dialog when the outer one could not paint', async () => { + const harness = createHarness() + + await harness.callHook('agent_start') + await harness.handlers.ui_prompt_start?.({}, undefined) + await harness.callHook('ui_prompt_start') + // Why: the outer ctx cannot decide that the whole stack stays unmarked. + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + }) + + it('clears the marker through the opening ctx when the close carries none', async () => { + const harness = createHarness() + + await harness.callHook('ui_prompt_start') + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + await harness.handlers.ui_prompt_end?.({}, undefined) + // Why: otherwise the pane asks for attention until the next turn. + expect(harness.lastTitle()).toBe(IDLE_TITLE) + }) + + it('does not reject when the dialog ctx can no longer paint', async () => { + const harness = createHarness() + const throwing = { + ui: { + setTitle: () => { + throw new Error('extension runner is no longer active') + } + } + } + + await expect(harness.handlers.ui_prompt_start?.({}, throwing)).resolves.toBeUndefined() + // Why: the marker never went up, so the spinner must not stay suppressed. + await harness.callHook('agent_start') + await vi.advanceTimersByTimeAsync(80) + expect(harness.lastTitle()).toMatch(BRAILLE_RE) + }) + + it('does not reject when the captured ctx dies before the dialog closes', async () => { + const harness = createHarness() + let live = true + const dying = { + ui: { + setTitle: (title: string) => { + if (!live) { + throw new Error('extension runner is no longer active') + } + harness.titles.push(title) + } + } + } + + await harness.handlers.ui_prompt_start?.({}, dying) + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + live = false + // Why: the close carries no ui, so it falls back to the ctx the modal invalidated. + await expect(harness.handlers.ui_prompt_end?.({}, undefined)).resolves.toBeUndefined() + // Why: a later turn still recovers a clean title through a live ctx. + await harness.callHook('agent_start') + await vi.advanceTimersByTimeAsync(80) + expect(harness.lastTitle()).toMatch(BRAILLE_RE) + }) + + it('does not strand the marker when the closing ctx throws on ui access', async () => { + const harness = createHarness() + // Why: pi's ctx.ui is a getter that calls assertActive(); a session-replacing dialog + // invalidates the runner, so reading ctx.ui throws rather than yielding undefined. + const stale = { + get ui(): never { + throw new Error('This extension ctx is stale') + } + } + + await harness.callHook('ui_prompt_start') + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + + await expect(harness.handlers.ui_prompt_end?.({}, stale as never)).resolves.toBeUndefined() + // Why: the opening ctx still paints, so the pane stops asking for input. + expect(harness.lastTitle()).toBe(IDLE_TITLE) + + // Why: a stranded markerPainted would suppress every later working frame. + await harness.callHook('agent_start') + await vi.advanceTimersByTimeAsync(80) + expect(harness.lastTitle()).toMatch(BRAILLE_RE) + }) + + it('does not reject when the opening ctx throws on ui access', async () => { + const harness = createHarness() + const stale = { + get ui(): never { + throw new Error('This extension ctx is stale') + } + } + + await harness.callHook('agent_start') + await expect(harness.handlers.ui_prompt_start?.({}, stale as never)).resolves.toBeUndefined() + // Why: no marker went up, so the spinner must keep running. + await vi.advanceTimersByTimeAsync(80) + expect(harness.lastTitle()).toMatch(BRAILLE_RE) + }) + + it('re-asserts the marker when pi repaints the title under a dialog', async () => { + const harness = createHarness() + + await harness.callHook('agent_start') + await harness.callHook('ui_prompt_start') + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + + // Why: pi repaints on session_info_changed/rebindCurrentSession with no event we see, + // so a marker that is merely "not overwritten by us" would be silently lost. + harness.titles.push('π - other - orca-app') + await vi.advanceTimersByTimeAsync(80) + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + }) + + it('re-asserts the marker on an idle pane with no spinner running', async () => { + const harness = createHarness() + + await harness.callHook('ui_prompt_start') + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + + // Why: no turn is running, so renderFrame never fires — only the slow re-assert can + // undo a title pi writes from session_info_changed or its update-check restore. + harness.titles.push('\u03c0 - other - orca-app') + await vi.advanceTimersByTimeAsync(1000) + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + + await harness.callHook('ui_prompt_end') + expect(harness.lastTitle()).toBe(IDLE_TITLE) + expect(vi.getTimerCount()).toBe(0) + }) + + it('releases the marker when a session replacement drops the dialog', async () => { + const harness = createHarness() + + await harness.callHook('ui_prompt_start') + expect(harness.lastTitle()).toBe(PROMPT_TITLE) + + // Why: pi hides the dialog without resolving it, so no close is coming. + await harness.callHook('session_start', { reason: 'switch' }) + expect(vi.getTimerCount()).toBe(0) + await harness.callHook('agent_start') + await vi.advanceTimersByTimeAsync(80) + expect(harness.lastTitle()).toMatch(BRAILLE_RE) + }) + + it('survives a deleted cwd instead of crashing the pi process', async () => { + const harness = createHarness({ + cwdImpl: () => { + throw new Error('ENOENT: uv_cwd') + } + }) + + // Why: these run inside setInterval callbacks, where an escape is an uncaught + // exception and pi exits(1) through its own uncaughtException handler. + await expect(harness.callHook('agent_start')).resolves.toBeUndefined() + await expect(harness.callHook('ui_prompt_start')).resolves.toBeUndefined() + // Why: an unguarded throw in the interval would surface here as an unhandled error. + await vi.advanceTimersByTimeAsync(2000) + await expect(harness.callHook('ui_prompt_end')).resolves.toBeUndefined() + await expect(harness.callHook('agent_settled')).resolves.toBeUndefined() + }) + + it('survives a session name that throws on a stale runtime', async () => { + let live = true + const harness = createHarness({ + sessionNameImpl: () => { + if (!live) { + throw new Error('This extension API is stale') + } + return SESSION + } + }) + + await harness.callHook('agent_start') + await harness.callHook('ui_prompt_start') + live = false + await vi.advanceTimersByTimeAsync(2000) + await expect(harness.callHook('ui_prompt_end')).resolves.toBeUndefined() + }) + + it('leaves the needs-input marker to the process that owns the pane', async () => { + // Why: child agents inherit ORCA_PANE_KEY, and a second process asserting the marker + // would report needs-input for a pane it does not speak for. + const harness = createHarness({ env: { ORCA_PI_TITLE_MARKER_OWNED: '111' } }) + + await harness.callHook('agent_start') + await harness.callHook('ui_prompt_start') + await vi.advanceTimersByTimeAsync(1000) + expect(harness.titles).not.toContain(PROMPT_TITLE) + expect(harness.lastTitle()).toMatch(BRAILLE_RE) + }) + + it('leaves an OMP runtime to its own approval events', () => { + const harness = createHarness({ processTitle: 'omp' }) + + expect(harness.handlers.ui_prompt_start).toBeDefined() + expect(() => harness.handlers.ui_prompt_start?.({}, undefined)).not.toThrow() + }) }) diff --git a/src/main/pi/titlebar-extension-source.ts b/src/main/pi/titlebar-extension-source.ts index a41eafb896f..7fc15c191bc 100644 --- a/src/main/pi/titlebar-extension-source.ts +++ b/src/main/pi/titlebar-extension-source.ts @@ -1,7 +1,54 @@ +import type { PiAgentKind } from '../../shared/pi-agent-kind' +import { getPiOmpRuntimeDetectionSourceLines } from './agent-status-runtime-detection-source' + export const ORCA_PI_EXTENSION_FILE = 'orca-titlebar-spinner.ts' -export function getPiTitlebarExtensionSource(): string { +export function getPiTitlebarExtensionSource(kind: PiAgentKind = 'pi'): string { + // Why: OMP reports input waits through its own approval events, which the status + // extension already maps, and it writes this same marker natively. The runtime check + // matters as well as the kind: a bare-shell OMP launch runs inside a pi-kind pane. + const uiPromptHandlers = + kind === 'pi' + ? [ + " pi.on('ui_prompt_start', async (_event, ctx) => {", + ' if (isOmpRuntime() || !ownsMarker) return', + ' promptDepth++', + ' // Why: retry on every open rather than only the outermost, so an outer ctx', + ' // that could not paint cannot decide the whole stack stays unmarked.', + ' if (markerPainted) return', + ' const painter = resolvePainter(ctx)', + ' // Why: only hold the spinner off once the marker is actually up, or a ctx', + ' // that cannot paint would freeze the title on its last working frame.', + " if (!paintTitle(painter, () => getMarkedTitle(pi, '!'))) return", + ' markerPainted = true', + ' promptCtx = painter', + ' startMarkerReassert(painter)', + ' })', + '', + " pi.on('ui_prompt_end', async (_event, ctx) => {", + ' if (isOmpRuntime() || !ownsMarker || promptDepth === 0) return', + ' promptDepth--', + ' if (promptDepth > 0) return', + ' // Why: the opening ctx already painted once, so a close whose own ctx is stale', + ' // does not leave the needs-input marker up until the next turn.', + ' const painter = resolvePainter(ctx) ?? promptCtx', + ' markerPainted = false', + ' promptCtx = null', + ' stopMarkerReassert()', + ' // Why: a still-live turn resumes its spinner in place; otherwise the pane is idle', + ' // and must drop the needs-input marker rather than keep asking for attention.', + ' if (timer) {', + ' renderFrame(painter)', + ' return', + ' }', + ' paintTitle(painter, () => getBaseTitle(pi))', + ' })', + '' + ] + : [] + return [ + ...(kind === 'pi' ? [...getPiOmpRuntimeDetectionSourceLines(`/hook/${kind}`), ''] : []), 'const BRAILLE_FRAMES = [', " '\\u280b',", " '\\u2819',", @@ -16,36 +63,111 @@ export function getPiTitlebarExtensionSource(): string { ']', '', 'const FRAME_INTERVAL_MS = 80', + '// Why: pi repaints the title from its own writers (session_info_changed, the win32', + '// update-check restore) with no event we observe, so the marker has to be re-asserted', + '// even when no spinner frame is due. Coarse on purpose: it only rewrites one string.', + 'const MARKER_REASSERT_MS = 1000', 'const AGENT_END_IDLE_RECHECK_MS = 25', 'const AGENT_END_IDLE_RECHECK_MAX_MS = 250', '// Why: a failed idle compaction can end without auto_compaction_end, and no agent turn will', '// close a maintenance spinner — cap it so idle maintenance cannot strand a working title.', 'const IDLE_COMPACTION_MAX_FRAMES = Math.ceil(300000 / FRAME_INTERVAL_MS)', '', - 'function getBaseTitle(pi) {', + '// Why: `-` is the plain separator; `!` is the state marker Orca reads as needs-input', + '// (src/shared/pi-state-title-marker.ts), so mobile and the CLI see the wait too.', + 'function getMarkedTitle(pi, marker) {', ' const cwd = process.cwd().split(/[\\\\/]/).filter(Boolean).at(-1) || process.cwd()', ' const session = pi.getSessionName()', - ' return session ? `\\u03c0 - ${session} - ${cwd}` : `\\u03c0 - ${cwd}`', + ' return session', + ' ? `\\u03c0 ${marker} ${session} - ${cwd}`', + ' : `\\u03c0 ${marker} ${cwd}`', + '}', + '', + 'function getBaseTitle(pi) {', + " return getMarkedTitle(pi, '-')", + '}', + '', + '// Why: the ctx.ui pi passes is a getter that calls assertActive() and throws once a', + '// session-replacing dialog invalidates the runner; optional chaining cannot screen', + '// that out. Read it behind a try and never mutate state before a paint has succeeded.', + 'function resolvePainter(ctx) {', + ' try {', + " return typeof ctx?.ui?.setTitle === 'function' ? ctx : null", + ' } catch {', + ' return null', + ' }', + '}', + '', + '// Why: buildTitle runs inside the try because it is not safe either — getSessionName()', + '// calls assertActive() and process.cwd() throws ENOENT once the worktree is deleted.', + '// Most call sites are timer callbacks, where an escape is an uncaught exception and pi', + '// exits(1) through its own uncaughtException handler.', + 'function paintTitle(ctx, buildTitle) {', + ' if (!ctx) return false', + ' try {', + ' ctx.ui.setTitle(buildTitle())', + ' return true', + ' } catch {', + ' return false', + ' }', '}', '', 'export default function (pi) {', ' if (!process.env.ORCA_PANE_KEY) return', + ...(kind === 'pi' + ? [ + ' // Why: child agents inherit the pane env, and the spinner is harmlessly', + ' // per-process — but the needs-input marker is status the pane reports, so only', + ' // one process may assert it. Mirrors ORCA_PI_STATUS_OWNED in the status hook.', + ' const markerOwnerPid = process.env.ORCA_PI_TITLE_MARKER_OWNED', + ' const ownsMarker = !markerOwnerPid || markerOwnerPid === String(process.pid)', + ' if (ownsMarker) process.env.ORCA_PI_TITLE_MARKER_OWNED = String(process.pid)' + ] + : []), + ' let timer = null', ' let frameIndex = 0', ' // Why: only idle maintenance owns a spinner of its own. A threshold compaction runs', ' // inside an agent turn, whose spinner must outlive it, and any newer start clears the', ' // marker so a late idle completion cannot stop current work (#16470).', ' let idleCompactionOwnsSpinner = false', + ' // Why: pi already collapses nested prompts into one start/end pair, so this counter', + ' // guards a close that never arrives, not nesting. A new turn cannot start under a', + ' // dialog holding input focus, so agent_start doubles as recovery.', + ' let promptDepth = 0', + ' let markerPainted = false', + ' let promptCtx = null', + ' // Why: a separate handle from `timer`, which clearAnimation() nulls — the marker must', + ' // survive a turn settling, a shutdown of the spinner, and the idle-maintenance cap.', + ' let markerTimer = null', ' let pendingAgentEndCheck = null', ' let pendingAgentEndContext = null', ' let agentEndIdleRecheckMs = AGENT_END_IDLE_RECHECK_MS', '', + ' function resetPromptState() {', + ' stopMarkerReassert()', + ' promptDepth = 0', + ' markerPainted = false', + ' promptCtx = null', + ' }', + '', ' function clearPendingAgentEndCheck() {', ' if (pendingAgentEndCheck !== null) clearTimeout(pendingAgentEndCheck)', ' pendingAgentEndCheck = null', ' pendingAgentEndContext = null', ' }', '', + ' function stopMarkerReassert() {', + ' if (markerTimer) clearInterval(markerTimer)', + ' markerTimer = null', + ' }', + '', + ' function startMarkerReassert(ctx) {', + ' stopMarkerReassert()', + " markerTimer = setInterval(() => paintTitle(ctx, () => getMarkedTitle(pi, '!')), MARKER_REASSERT_MS)", + " if (typeof markerTimer.unref === 'function') markerTimer.unref()", + ' }', + '', ' function clearAnimation() {', ' if (timer) {', ' clearInterval(timer)', @@ -58,19 +180,35 @@ export function getPiTitlebarExtensionSource(): string { ' function stopAnimation(ctx) {', ' clearPendingAgentEndCheck()', ' clearAnimation()', - ' ctx.ui.setTitle(getBaseTitle(pi))', + ' // Why: settling under an open dialog still leaves the pane waiting on the user, so', + ' // the idle title must not retire the marker the dialog is holding.', + " paintTitle(ctx, () => (markerPainted ? getMarkedTitle(pi, '!') : getBaseTitle(pi)))", ' }', '', ' function renderFrame(ctx) {', + ' // Why: the maintenance cap runs before the dialog guard so a dialog left open', + ' // cannot suspend it; stopAnimation keeps the marker while a dialog is open.', ' if (idleCompactionOwnsSpinner && frameIndex >= IDLE_COMPACTION_MAX_FRAMES) {', ' stopAnimation(ctx)', ' return', ' }', - ' const frame = BRAILLE_FRAMES[frameIndex % BRAILLE_FRAMES.length]', - ' const cwd = process.cwd().split(/[\\\\/]/).filter(Boolean).at(-1) || process.cwd()', - ' const session = pi.getSessionName()', - ' const title = session ? `${frame} \\u03c0 - ${session} - ${cwd}` : `${frame} \\u03c0 - ${cwd}`', - ' ctx.ui.setTitle(title)', + ' // Why: an 80ms working frame would repaint over the needs-input marker within one', + ' // tick, so a mid-turn dialog would still look busy everywhere the title is the', + ' // only evidence. Re-assert rather than skip: pi repaints the title on its own', + ' // (session_info_changed, resetExtensionUI, rebindCurrentSession) and would', + ' // otherwise wipe the marker with nothing to restore it. The frame still counts,', + ' // so the cap above keeps accruing in wall-clock.', + ' if (markerPainted) {', + " paintTitle(ctx, () => getMarkedTitle(pi, '!'))", + ' frameIndex++', + ' return', + ' }', + ' paintTitle(ctx, () => {', + ' const frame = BRAILLE_FRAMES[frameIndex % BRAILLE_FRAMES.length]', + ' const cwd = process.cwd().split(/[\\\\/]/).filter(Boolean).at(-1) || process.cwd()', + ' const session = pi.getSessionName()', + ' return session ? `${frame} \\u03c0 - ${session} - ${cwd}` : `${frame} \\u03c0 - ${cwd}`', + ' })', ' frameIndex++', ' }', '', @@ -101,9 +239,17 @@ export function getPiTitlebarExtensionSource(): string { ' }', '', " pi.on('agent_start', async (_event, ctx) => {", + ' resetPromptState()', ' startAnimation(ctx)', ' })', '', + ' // Why: pi drops an open dialog through resetExtensionUI without resolving its promise,', + ' // so a replaced or reloaded session never sends the matching close. Both boundaries', + ' // prove no dialog from the old session is still on screen.', + " pi.on('session_start', async () => {", + ' resetPromptState()', + ' })', + '', ' // Why: modern Pi/OMP emit agent_end mid-run and only settle later, so settlement is the', ' // authoritative completion boundary. Legacy runtimes never emit it, so agent_end stays.', " pi.on('agent_settled', async (_event, ctx) => {", @@ -126,6 +272,7 @@ export function getPiTitlebarExtensionSource(): string { " if (typeof pendingAgentEndCheck.unref === 'function') pendingAgentEndCheck.unref()", ' })', '', + ...uiPromptHandlers, " pi.on('auto_compaction_start', async (event, ctx) => {", " if (event?.reason !== 'idle') return", ' // Why: the idle worker can fire against a turn that just started, and reason alone does', @@ -142,6 +289,7 @@ export function getPiTitlebarExtensionSource(): string { ' })', '', " pi.on('session_shutdown', async (_event, ctx) => {", + ' resetPromptState()', ' stopAnimation(ctx)', ' })', '}', diff --git a/src/shared/agent-hook-listener/providers/pi-family-tool-fields.ts b/src/shared/agent-hook-listener/providers/pi-family-tool-fields.ts index d20b4aedbf7..65c61981868 100644 --- a/src/shared/agent-hook-listener/providers/pi-family-tool-fields.ts +++ b/src/shared/agent-hook-listener/providers/pi-family-tool-fields.ts @@ -36,7 +36,15 @@ export function extractPiToolFields( eventName === 'ui_prompt_start' || eventName === 'ui_prompt_end') ) { - return clearActiveToolFieldsUpdate() + // Why: the reply is the agent's own text, not modal content, so a turn that finishes + // while a dialog is open must not leave the preview stuck on the previous message. + const assistantText = + eventName === 'message_end' && hookPayload.role === 'assistant' + ? readString(hookPayload, 'text') + : undefined + return assistantText + ? { ...clearActiveToolFieldsUpdate(), lastAssistantMessage: assistantText } + : clearActiveToolFieldsUpdate() } if ( eventName === 'tool_call' || From 6108ce617c8696c3d52a97d29911aed630a22e78 Mon Sep 17 00:00:00 2001 From: Jinjing <6427696+AmethystLiang@users.noreply.github.com> Date: Tue, 8 Sep 2026 10:53:26 -0700 Subject: [PATCH 11/59] Organize activity menu into filter and view sections (#19547) * refactor: organize activity menu into sections and change toggle callbac Restructure the activity thread options menu to use explicit boolean callbacks instead of toggle functions (rename onToggleUnread to onUnreadOnlyChange) and organize options into logical "Filters" and "View" sections. Remove descriptive tooltips for compact mode and unread filter. Rename ActivityScopeFilterMenuSections to ActivityScopeFilterMenuItems and shift layout responsibility to parent component. * i18n * fix issues * i18n * Hide empty Filters section in activity options menu - Extract visibility logic into reusable hook `useActivityScopeFilterMenuItemsVisible` to avoid duplication - Only render Filters label and items when filters are available, preventing empty section in dropdown - Improves UX by not showing unused menu sections --- .../ActivityThreadOptionsMenu.test.tsx | 54 +++-- .../activity-scope-filter-controls.tsx | 59 ++++-- .../activity/activity-thread-options-menu.tsx | 185 +++++++----------- .../components/sidebar/SidebarAgentsList.tsx | 2 +- src/renderer/src/i18n/locales/en.json | 10 +- src/renderer/src/i18n/locales/es.json | 6 +- src/renderer/src/i18n/locales/fr.json | 4 + src/renderer/src/i18n/locales/ja.json | 6 +- src/renderer/src/i18n/locales/ko.json | 6 +- src/renderer/src/i18n/locales/zh.json | 7 +- 10 files changed, 166 insertions(+), 173 deletions(-) diff --git a/src/renderer/src/components/activity/ActivityThreadOptionsMenu.test.tsx b/src/renderer/src/components/activity/ActivityThreadOptionsMenu.test.tsx index 3f753f3d69d..6ba2b7906a4 100644 --- a/src/renderer/src/components/activity/ActivityThreadOptionsMenu.test.tsx +++ b/src/renderer/src/components/activity/ActivityThreadOptionsMenu.test.tsx @@ -167,9 +167,18 @@ describe('ActivityThreadOptionsMenu', () => { expect(document.body.textContent).toContain('Agent') }) - it('explains compact mode on hover', async () => { + it('updates compact mode without closing the menu', async () => { + const onCompactModeChange = vi.fn() await act(async () => { - root.render() + root.render( + + + + ) }) const trigger = container.querySelector( @@ -179,19 +188,20 @@ describe('ActivityThreadOptionsMenu', () => { trigger?.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, key: 'Enter' })) }) - const compactMode = document.querySelector('[role="menuitemcheckbox"]') + const compactMode = Array.from( + document.querySelectorAll('[role="menuitemcheckbox"]') + ).find((item) => item.textContent === 'Compact mode') await act(async () => { - compactMode?.dispatchEvent(new Event('pointermove', { bubbles: true })) + compactMode?.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, key: 'Enter' })) }) - expect(document.body.textContent).toContain( - 'Shows shorter thread rows with one-line titles and two-line status messages.' - ) + expect(onCompactModeChange).toHaveBeenCalledWith(true) + expect(document.body.textContent).toContain('Compact mode') }) it('puts persisted search visibility and unread actions in the menu', async () => { const onShowSearchChange = vi.fn() - const onToggleUnread = vi.fn() + const onUnreadOnlyChange = vi.fn() await act(async () => { root.render( @@ -203,7 +213,7 @@ describe('ActivityThreadOptionsMenu', () => { showSearch onShowSearchChange={onShowSearchChange} unreadOnly={false} - onToggleUnread={onToggleUnread} + onUnreadOnlyChange={onUnreadOnlyChange} /> ) @@ -230,8 +240,8 @@ describe('ActivityThreadOptionsMenu', () => { expect(onShowSearchChange).toHaveBeenCalledWith(false) }) - it('explains show unread threads only on hover without a second unread state marker', async () => { - const onToggleUnread = vi.fn() + it('updates the unread filter without closing the menu', async () => { + const onUnreadOnlyChange = vi.fn() await act(async () => { root.render( @@ -241,7 +251,7 @@ describe('ActivityThreadOptionsMenu', () => { onCompactModeChange={vi.fn()} onMarkAllThreadsRead={vi.fn()} unreadOnly={false} - onToggleUnread={onToggleUnread} + onUnreadOnlyChange={onUnreadOnlyChange} /> ) @@ -254,15 +264,15 @@ describe('ActivityThreadOptionsMenu', () => { trigger?.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, key: 'Enter' })) }) - const unreadItem = document.querySelector('[role="menuitemcheckbox"]') + const unreadItem = Array.from( + document.querySelectorAll('[role="menuitemcheckbox"]') + ).find((item) => item.textContent === 'Show unread only') await act(async () => { - unreadItem?.dispatchEvent(new Event('pointermove', { bubbles: true })) + unreadItem?.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, key: 'Enter' })) }) - expect(document.body.textContent).toContain( - 'Filters the activity list to show only threads with unread updates.' - ) - expect(document.querySelector('[data-unread-dot]')).toBeNull() + expect(onUnreadOnlyChange).toHaveBeenCalledWith(true) + expect(document.body.textContent).toContain('Show unread only') }) it('renders show child agents checkbox when onShowChildAgentsChange is provided', async () => { @@ -281,6 +291,14 @@ describe('ActivityThreadOptionsMenu', () => { trigger?.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, key: 'Enter' })) }) + const childAgentsItem = Array.from( + document.querySelectorAll('[role="menuitemcheckbox"]') + ).find((item) => item.textContent === 'Show child agents') + await act(async () => { + childAgentsItem?.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, key: 'Enter' })) + }) + + expect(onShowChildAgentsChange).toHaveBeenCalledWith(true) expect(document.body.textContent).toContain('Show child agents') }) }) diff --git a/src/renderer/src/components/activity/activity-scope-filter-controls.tsx b/src/renderer/src/components/activity/activity-scope-filter-controls.tsx index a9e75e10483..e90ec1f3322 100644 --- a/src/renderer/src/components/activity/activity-scope-filter-controls.tsx +++ b/src/renderer/src/components/activity/activity-scope-filter-controls.tsx @@ -1,6 +1,6 @@ import React from 'react' import { useAppStore } from '@/store' -import { DropdownMenuItem, DropdownMenuSeparator } from '@/components/ui/dropdown-menu' +import { DropdownMenuItem } from '@/components/ui/dropdown-menu' import { translate } from '@/i18n/i18n' import SidebarRepositoryFilterSection from '@/components/sidebar/SidebarRepositoryFilterSection' import { SidebarHostScopeMenuSection } from '@/components/sidebar/SidebarHostScopeMenuSection' @@ -11,12 +11,30 @@ import { import { useSidebarHostScopeOptions } from '@/components/sidebar/use-sidebar-host-scope-options' /** - * Host/project scope controls for the Agents activity surfaces. State is the - * persisted agents-view scope (agentsVisibleHostIds / agentsFilterRepoIds), - * deliberately separate from the workspace-nav filters. + * Whether {@link ActivityScopeFilterMenuItems} renders anything. + * Why exported: the parent owns the Filters label and separator, so it has to + * know whether the section would be empty. */ -export function ActivityScopeFilterMenuSections(): React.JSX.Element | null { +export function useActivityScopeFilterMenuItemsVisible(): boolean { const repos = useAppStore((s) => s.repos) + const agentsVisibleHostIds = useAppStore((s) => s.agentsVisibleHostIds) + const agentsFilterRepoIds = useAppStore((s) => s.agentsFilterRepoIds) + const { hostOptions } = useSidebarHostScopeOptions() + return ( + agentsVisibleHostIds !== null || + agentsFilterRepoIds.length > 0 || + shouldShowHostScopeControls(hostOptions) || + repos.length > 1 + ) +} + +/** + * Host/project scope items for the Agents activity surfaces. State is the + * persisted agents-view scope (agentsVisibleHostIds / agentsFilterRepoIds), + * deliberately separate from the workspace-nav filters. The parent owns the + * Filters label and separator. + */ +export function ActivityScopeFilterMenuItems(): React.JSX.Element | null { const agentsVisibleHostIds = useAppStore((s) => s.agentsVisibleHostIds) const setAgentsVisibleHostIds = useAppStore((s) => s.setAgentsVisibleHostIds) const agentsFilterRepoIds = useAppStore((s) => s.agentsFilterRepoIds) @@ -24,25 +42,14 @@ export function ActivityScopeFilterMenuSections(): React.JSX.Element | null { const { hostOptions } = useSidebarHostScopeOptions() const showHostScopeControls = shouldShowHostScopeControls(hostOptions) const hasScopeFilter = agentsVisibleHostIds !== null || agentsFilterRepoIds.length > 0 + const visible = useActivityScopeFilterMenuItemsVisible() - if (!hasScopeFilter && !showHostScopeControls && repos.length <= 1) { + if (!visible) { return null } + return ( <> - {hasScopeFilter ? ( - { - setAgentsVisibleHostIds(null) - setAgentsFilterRepoIds([]) - }} - > - {translate( - 'auto.components.activity.ActivityScopeFilterControls.resetScope', - 'Show all hosts and projects' - )} - - ) : null} {showHostScopeControls ? ( - + {hasScopeFilter ? ( + { + setAgentsVisibleHostIds(null) + setAgentsFilterRepoIds([]) + }} + > + {translate( + 'auto.components.activity.ActivityScopeFilterControls.resetScope', + 'Show all hosts and projects' + )} + + ) : null} ) } diff --git a/src/renderer/src/components/activity/activity-thread-options-menu.tsx b/src/renderer/src/components/activity/activity-thread-options-menu.tsx index bd398986bd3..5a9bd3bc59c 100644 --- a/src/renderer/src/components/activity/activity-thread-options-menu.tsx +++ b/src/renderer/src/components/activity/activity-thread-options-menu.tsx @@ -1,21 +1,12 @@ import React from 'react' -import { - Check, - CheckCheck, - GitFork, - Layers, - ListChecks, - ListFilter, - Rows3, - Search, - Trash2 -} from 'lucide-react' +import { CheckCheck, ListFilter, Trash2 } from 'lucide-react' import { Button } from '@/components/ui/button' import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, + DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, @@ -27,12 +18,19 @@ import { import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip' import { translate } from '@/i18n/i18n' import { - ActivityScopeFilterMenuSections, - useActivityScopeFilterActive + ActivityScopeFilterMenuItems, + useActivityScopeFilterActive, + useActivityScopeFilterMenuItemsVisible } from './activity-scope-filter-controls' import type { ActivityGroupBy } from './activity-thread-types' -const ALIGNED_CHECKBOX_ITEM_CLASS = 'pl-2 [&>span.absolute]:hidden' +const GROUP_BY_OPTIONS = [ + 'none', + 'status', + 'project', + 'worktree', + 'agent' +] as const satisfies readonly ActivityGroupBy[] function getActivityGroupByLabel(groupBy: ActivityGroupBy): string { switch (groupBy) { @@ -63,7 +61,7 @@ export function ActivityThreadOptionsMenu({ showSearch = false, onShowSearchChange, unreadOnly = false, - onToggleUnread + onUnreadOnlyChange }: { groupBy?: ActivityGroupBy onGroupByChange?: (groupBy: ActivityGroupBy) => void @@ -78,10 +76,14 @@ export function ActivityThreadOptionsMenu({ showSearch?: boolean onShowSearchChange?: (showSearch: boolean) => void unreadOnly?: boolean - onToggleUnread?: () => void + onUnreadOnlyChange?: (unreadOnly: boolean) => void }): React.JSX.Element { const skipCloseAutoFocusRef = React.useRef(false) const scopeFilterActive = useActivityScopeFilterActive() + const scopeFilterItemsVisible = useActivityScopeFilterMenuItemsVisible() + const hasFilters = Boolean( + onUnreadOnlyChange || onShowChildAgentsChange || scopeFilterItemsVisible + ) const optionsLabel = scopeFilterActive ? translate( 'auto.components.activity.ActivityPrototypePage.threadListOptionsFiltered', @@ -126,7 +128,7 @@ export function ActivityThreadOptionsMenu({ side="right" align="start" sideOffset={8} - className="w-56" + className="w-60" onCloseAutoFocus={(event) => { if (skipCloseAutoFocusRef.current) { event.preventDefault() @@ -134,70 +136,56 @@ export function ActivityThreadOptionsMenu({ } }} > - {onShowSearchChange || onToggleUnread ? ( + {hasFilters ? ( <> - {onShowSearchChange ? ( + + {translate( + 'auto.components.activity.ActivityPrototypePage.filtersSection', + 'Filters' + )} + + {onUnreadOnlyChange ? ( { - skipCloseAutoFocusRef.current = checked === true - onShowSearchChange(checked === true) - }} + checked={unreadOnly} + onCheckedChange={(checked) => onUnreadOnlyChange(checked === true)} + onSelect={(event) => event.preventDefault()} > - - - {translate( - 'auto.components.activity.ActivityPrototypePage.showSearch', - 'Show search' - )} - - {showSearch ? : null} + {translate( + 'auto.components.activity.ActivityPrototypePage.showUnreadOnly', + 'Show unread only' + )} ) : null} - {onToggleUnread ? ( - - - onToggleUnread()} - onSelect={(event) => event.preventDefault()} - > - - - {translate( - 'auto.components.activity.ActivityPrototypePage.showUnreadOnly', - 'Show unread only' - )} - - {unreadOnly ? : null} - - - - {translate( - 'auto.components.activity.ActivityPrototypePage.unreadOnlyDescription', - 'Filters the activity list to show only threads with unread updates.' - )} - - + {onShowChildAgentsChange ? ( + onShowChildAgentsChange(checked === true)} + onSelect={(event) => event.preventDefault()} + > + {translate( + 'auto.components.activity.ActivityPrototypePage.showChildAgents', + 'Show child agents' + )} + ) : null} + ) : null} - + + {translate('auto.components.activity.ActivityPrototypePage.viewSection', 'View')} + {groupBy && onGroupByChange ? ( - - + {translate( 'auto.components.activity.ActivityPrototypePage.770d458144', 'Group by' )} - + {getActivityGroupByLabel(groupBy)} @@ -207,73 +195,36 @@ export function ActivityThreadOptionsMenu({ value={groupBy} onValueChange={(value) => onGroupByChange(value as ActivityGroupBy)} > - {[ - ['none', 'None', 'auto.components.activity.ActivityPrototypePage.none'], - ['status', 'Status', 'auto.components.activity.ActivityPrototypePage.4a3986b200'], - [ - 'project', - 'Project', - 'auto.components.activity.ActivityPrototypePage.8c3b621ddf' - ], - [ - 'worktree', - 'Worktree', - 'auto.components.activity.ActivityPrototypePage.b29191b3e0' - ], - ['agent', 'Agent', 'auto.components.activity.ActivityPrototypePage.f6396e1f85'] - ].map(([value, label, key]) => ( + {GROUP_BY_OPTIONS.map((value) => ( event.preventDefault()} > - {translate(key, label)} + {getActivityGroupByLabel(value)} ))} ) : null} - - - onCompactModeChange(checked === true)} - onSelect={(event) => event.preventDefault()} - > - - - {translate( - 'auto.components.activity.ActivityPrototypePage.f70e4bec47', - 'Compact mode' - )} - - {compactMode ? : null} - - - - {translate( - 'auto.components.activity.ActivityPrototypePage.compactModeDescription', - 'Shows shorter thread rows with one-line titles and two-line status messages.' - )} - - - {onShowChildAgentsChange ? ( + onCompactModeChange(checked === true)} + onSelect={(event) => event.preventDefault()} + > + {translate('auto.components.activity.ActivityPrototypePage.f70e4bec47', 'Compact mode')} + + {onShowSearchChange ? ( onShowChildAgentsChange(checked === true)} - onSelect={(event) => event.preventDefault()} + checked={showSearch} + onCheckedChange={(checked) => { + const show = checked === true + skipCloseAutoFocusRef.current = show + onShowSearchChange(show) + }} > - - - {translate( - 'auto.components.activity.ActivityPrototypePage.showChildAgents', - 'Show child agents' - )} - - {showChildAgents ? : null} + {translate('auto.components.activity.ActivityPrototypePage.showSearch', 'Show search')} ) : null} {onMarkAllThreadsRead || onClearCompleted ? ( diff --git a/src/renderer/src/components/sidebar/SidebarAgentsList.tsx b/src/renderer/src/components/sidebar/SidebarAgentsList.tsx index 3f22d7fc2da..cd782457d64 100644 --- a/src/renderer/src/components/sidebar/SidebarAgentsList.tsx +++ b/src/renderer/src/components/sidebar/SidebarAgentsList.tsx @@ -182,7 +182,7 @@ export default function SidebarAgentsList({ showSearch={showSearch} onShowSearchChange={handleShowSearchChange} unreadOnly={readFilter === 'unread'} - onToggleUnread={() => setReadFilter(readFilter === 'unread' ? 'all' : 'unread')} + onUnreadOnlyChange={(unreadOnly) => setReadFilter(unreadOnly ? 'unread' : 'all')} />, optionsTarget ) diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json index 8e6d862e3b5..fb8e84b7ef7 100644 --- a/src/renderer/src/i18n/locales/en.json +++ b/src/renderer/src/i18n/locales/en.json @@ -16244,8 +16244,6 @@ "5651b216c6": "Unknown project", "22b22034bc": "Standalone terminal unavailable in Activity.", "afdc2139a8": "Agent terminal closed. Open a new terminal in this workspace to continue.", - "compactModeDescription": "Shows shorter thread rows with one-line titles and two-line status messages.", - "unreadOnlyDescription": "Filters the activity list to show only threads with unread updates.", "clearCompleted": "Clear completed", "none": "None", "search": "Search", @@ -16265,7 +16263,9 @@ "idle": "Idle", "unverifiable": "No recent update", "permission": "Needs attention" - } + }, + "filtersSection": "Filters", + "viewSection": "View" }, "clearCompleted": { "clearedOne": "Cleared 1 completed agent", @@ -16282,8 +16282,8 @@ "dc708f3eff": "Close agents" }, "ActivityScopeFilterControls": { - "resetScope": "Show all hosts and projects", - "hiddenCount": "{{value0}} hidden" + "hiddenCount": "{{value0}} hidden", + "resetScope": "Show all hosts and projects" }, "ActivityThreadHoverCard": { "pathCopied": "Path copied to clipboard", diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json index f1539887478..2ee1716ea20 100644 --- a/src/renderer/src/i18n/locales/es.json +++ b/src/renderer/src/i18n/locales/es.json @@ -14188,8 +14188,6 @@ "5651b216c6": "Proyecto desconocido", "22b22034bc": "Terminal independiente no disponible en Actividad.", "afdc2139a8": "Terminal de Agent cerrada. Abre una nueva terminal en este workspace para continuar.", - "compactModeDescription": "Muestra filas de hilo más cortas con títulos de una línea y mensajes de estado de dos líneas.", - "unreadOnlyDescription": "Filtra la lista de actividad para mostrar solo hilos con actualizaciones sin leer.", "clearCompleted": "Borrar completados", "none": "Ninguno", "search": "Buscar", @@ -14207,7 +14205,9 @@ "idle": "Inactivo", "unverifiable": "Sin actualizaciones recientes", "permission": "Requiere atención" - } + }, + "filtersSection": "Filtros", + "viewSection": "Vista" }, "ActivityScopeFilterControls": { "resetScope": "Mostrar todos los hosts y proyectos" diff --git a/src/renderer/src/i18n/locales/fr.json b/src/renderer/src/i18n/locales/fr.json index 0c5f01f067e..6113d606c90 100644 --- a/src/renderer/src/i18n/locales/fr.json +++ b/src/renderer/src/i18n/locales/fr.json @@ -15464,6 +15464,10 @@ "4616ea39fd": "Aller à l'espace de travail", "threadListOptionsFiltered": "Options de la liste des fils, filtres actifs", "showSearch": "Afficher la recherche", + "showUnreadOnly": "Afficher uniquement les fils non lus", + "showChildAgents": "Afficher les agents enfants", + "filtersSection": "Filtres", + "viewSection": "Affichage", "59b131fbd9": "Marquer le fil comme non lu", "beb2c19173": "Non lus", "5651b216c6": "Projet inconnu", diff --git a/src/renderer/src/i18n/locales/ja.json b/src/renderer/src/i18n/locales/ja.json index cd9c24ea7d8..f0c1666d911 100644 --- a/src/renderer/src/i18n/locales/ja.json +++ b/src/renderer/src/i18n/locales/ja.json @@ -14188,8 +14188,6 @@ "5651b216c6": "不明なプロジェクト", "22b22034bc": "スタンドアロンターミナルはアクティビティでは使用できません。", "afdc2139a8": "Agent ターミナルが閉じられました。続行するには、このワークスペースで新規ターミナルを開いてください。", - "compactModeDescription": "1 行のタイトルと 2 行のステータスメッセージで短いスレッド行を表示します。", - "unreadOnlyDescription": "未読の更新があるスレッドのみをアクティビティ一覧に表示します。", "clearCompleted": "完了済みをクリア", "none": "なし", "search": "検索", @@ -14207,7 +14205,9 @@ "idle": "アイドル", "unverifiable": "最近の更新なし", "permission": "要対応" - } + }, + "filtersSection": "フィルター", + "viewSection": "表示" }, "ActivityScopeFilterControls": { "resetScope": "すべてのホストとプロジェクトを表示" diff --git a/src/renderer/src/i18n/locales/ko.json b/src/renderer/src/i18n/locales/ko.json index 76d778c1550..42983088062 100644 --- a/src/renderer/src/i18n/locales/ko.json +++ b/src/renderer/src/i18n/locales/ko.json @@ -14266,8 +14266,6 @@ "5651b216c6": "알 수 없는 프로젝트", "22b22034bc": "활동에서는 독립형 terminal을 사용할 수 없습니다.", "afdc2139a8": "Agent terminal이 닫혔습니다. 계속하려면 이 워크스페이스에서 새 terminal을 여세요.", - "compactModeDescription": "한 줄 제목과 두 줄 상태 메시지로 더 짧은 스레드 행을 표시합니다.", - "unreadOnlyDescription": "읽지 않은 업데이트가 있는 스레드만 활동 목록에 표시합니다.", "clearCompleted": "완료된 항목 지우기", "none": "없음", "search": "검색", @@ -14285,7 +14283,9 @@ "idle": "유휴", "unverifiable": "최근 업데이트 없음", "permission": "주의 필요" - } + }, + "filtersSection": "필터", + "viewSection": "보기" }, "ActivityScopeFilterControls": { "resetScope": "모든 호스트 및 프로젝트 표시" diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json index a267853a78c..09ca1689ea3 100644 --- a/src/renderer/src/i18n/locales/zh.json +++ b/src/renderer/src/i18n/locales/zh.json @@ -14266,8 +14266,6 @@ "5651b216c6": "未知项目", "22b22034bc": "独立终端在活动中不可用。", "afdc2139a8": "智能体终端关闭。在此工作区中打开一个新终端以继续。", - "compactModeDescription": "以单行标题和两行状态消息显示更短的线程行。", - "unreadOnlyDescription": "将活动列表筛选为仅显示有未读更新的线程。", "clearCompleted": "清除已完成", "none": "无", "search": "搜索", @@ -14285,8 +14283,11 @@ "idle": "空闲", "unverifiable": "暂无近期更新", "permission": "需注意" - } + }, + "filtersSection": "筛选", + "viewSection": "视图" }, + "ActivityScopeFilterControls": { "resetScope": "显示所有主机和项目" }, From e829bb523a77bbc2f357c8d1237e5a8750fc3d49 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 8 Sep 2026 18:31:49 +0000 Subject: [PATCH 12/59] Update README downloads badge --- docs/assets/readme-downloads.svg | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/assets/readme-downloads.svg b/docs/assets/readme-downloads.svg index 75762752848..724be685ea7 100644 --- a/docs/assets/readme-downloads.svg +++ b/docs/assets/readme-downloads.svg @@ -1,5 +1,5 @@ - - downloads: 43m + + downloads: 44m @@ -15,7 +15,7 @@ downloads downloads - 43m - 43m + 44m + 44m From 2ba2c90cb602d54240b307c02986e5ae53cfc4ae Mon Sep 17 00:00:00 2001 From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com> Date: Tue, 8 Sep 2026 14:32:01 -0400 Subject: [PATCH 13/59] fix(orchestration): own a worker terminal from creation, not after the boot wait (#19608) * fix(orchestration): own a worker terminal from creation, not after the boot wait A worker pane is visible on desktop and phone the moment it is created, but the worker_terminal_resources row saying orchestration owns it was written only after the agent TUI went idle (up to 60s). A keystroke into the booting pane found no owned row, markWorkerTerminalUserOwned returned 0, and the takeover was dropped - so a later worker-release closed the pane under the user. Record custody on the branches that create a terminal, right after creation and before the tui-idle wait. The Dispatch capability still waits for the agent to come up. An explicit --terminal reuse is untouched: it transfers at authority. With the row present from creation, the failed-start adoption is dead. What a failed start still needs is the Dispatch-context pane identity release re-proves through, which is now copied from the custody row. * chore(i18n): drop the orphan minimumContrast entries #19544 re-added to the runtime catalog --- .../worker-dispatch-authority.ts | 56 ++++- .../worker-dispatch-outcome.ts | 17 +- .../failed-start-dispatch-identity.ts | 34 +++ .../failed-start-terminal-adoption.ts | 68 ------ .../failed-start-terminal-adoption.test.ts | 157 ------------- .../worker/created-worker-terminal-custody.ts | 32 +++ .../failed-start-residual-terminal.test.ts | 191 ---------------- .../worker/failed-start-residual-terminal.ts | 53 ----- .../worker/failed-worker-start-teardown.ts | 23 +- .../worker/local-worker-start.ts | 12 +- .../worker/worker-start-receipt.ts | 20 +- ...orker-terminal-custody-at-creation.test.ts | 216 ++++++++++++++++++ .../src/i18n/en-runtime-required.json | 11 +- 13 files changed, 360 insertions(+), 530 deletions(-) create mode 100644 src/main/runtime/orchestration/db/worker-terminal/failed-start-dispatch-identity.ts delete mode 100644 src/main/runtime/orchestration/db/worker-terminal/failed-start-terminal-adoption.ts delete mode 100644 src/main/runtime/orchestration/failed-start-terminal-adoption.test.ts create mode 100644 src/main/runtime/rpc/methods/orchestration/worker/created-worker-terminal-custody.ts delete mode 100644 src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.test.ts delete mode 100644 src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.ts create mode 100644 src/main/runtime/rpc/methods/orchestration/worker/worker-terminal-custody-at-creation.test.ts diff --git a/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-authority.ts b/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-authority.ts index b89468c77a0..5e0f5f5b142 100644 --- a/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-authority.ts +++ b/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-authority.ts @@ -160,12 +160,66 @@ export function prepareStartingWorkerAuthority( } } +/** + * Custody for an agent terminal this worker-start just created, recorded at creation instead of + * after the agent boot wait. Until the row exists a keystroke into the booting pane finds no + * ownership to flip, so the takeover is silently dropped and a later `worker-release` closes the + * pane under the user. + * + * Ownership of a pane only; the Dispatch capability stays behind the boot wait, because authority + * must not be handed to a process that has not come up. + */ +export function recordCreatedWorkerTerminalCustody( + this: OrchestrationDb, + params: { + dispatchId: string + handle: string + paneKey: string + processIncarnation: string + worktreeId: string + hostScope?: string | null + } +): void { + this.db.exec('BEGIN IMMEDIATE') + try { + // Same guard as prepareStartingWorkerAuthority, read inside the transaction: a dispatch stopped + // while the terminal was being created must not acquire an owner. + const dispatch = this.getDispatchContextById(params.dispatchId) + const worker = this.getWorkerDispatch(params.dispatchId) + if (!dispatch || dispatch.status !== 'pending' || worker?.state !== 'starting') { + throw new OrchestrationError( + 'dispatch_inactive', + `Dispatch ${params.dispatchId} is not starting.` + ) + } + if (!this.getWorkerTerminalResourceByOwner(params.dispatchId)) { + this.createWorkerTerminalResourceStatement({ + dispatchId: params.dispatchId, + worktreeId: params.worktreeId, + terminalHandle: params.handle, + paneKey: params.paneKey, + processIncarnation: params.processIncarnation, + endpointId: worker.runtime_epoch, + endpointIncarnation: params.processIncarnation, + hostScope: params.hostScope, + ownership: 'owned' + }) + } + this.db.exec('COMMIT') + } catch (error) { + this.db.exec('ROLLBACK') + throw error + } +} + export type WorkerDispatchAuthorityMethods = { prepareStartingWorkerAuthority: typeof prepareStartingWorkerAuthority + recordCreatedWorkerTerminalCustody: typeof recordCreatedWorkerTerminalCustody } export function attachWorkerDispatchAuthority(ctor: { prototype: object }): void { Object.assign(ctor.prototype, { - prepareStartingWorkerAuthority + prepareStartingWorkerAuthority, + recordCreatedWorkerTerminalCustody }) } diff --git a/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-outcome.ts b/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-outcome.ts index 5ff97f83fd9..6544f519497 100644 --- a/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-outcome.ts +++ b/src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-outcome.ts @@ -2,10 +2,7 @@ import type { WorkerDispatchRow } from '../../types' import { OrchestrationError } from '../../orchestration-error' import type { OrchestrationDb } from '../orchestration-db' import { transitionLifecycleWithDb } from '../lifecycle-transition' -import { - adoptFailedStartTerminal, - type FailedStartTerminalAdoption -} from '../worker-terminal/failed-start-terminal-adoption' +import { recordFailedStartDispatchIdentity } from '../worker-terminal/failed-start-dispatch-identity' export function markWorkerDispatchReady( this: OrchestrationDb, @@ -51,11 +48,7 @@ export function failWorkerStart( // Why (#16095): revocation exists to stop a worker acting on a dispatch that never landed. A // prompt whose turn start went unobserved provably landed, so its worker keeps the authority its // own report needs. - options: { - retainCapability?: boolean - /** A start that died before authority attached still owns the terminal it created. */ - adoptResidualTerminal?: FailedStartTerminalAdoption - } = {} + options: { retainCapability?: boolean } = {} ): WorkerDispatchRow { this.db.exec('BEGIN IMMEDIATE') try { @@ -104,11 +97,7 @@ export function failWorkerStart( }) } this.closeQuestionsForDispatch(dispatchId) - adoptFailedStartTerminal( - this, - this.getWorkerDispatch(dispatchId) as WorkerDispatchRow, - options.adoptResidualTerminal - ) + recordFailedStartDispatchIdentity(this, this.getWorkerDispatch(dispatchId) as WorkerDispatchRow) this.db.exec('COMMIT') return this.getWorkerDispatch(dispatchId) as WorkerDispatchRow } catch (error) { diff --git a/src/main/runtime/orchestration/db/worker-terminal/failed-start-dispatch-identity.ts b/src/main/runtime/orchestration/db/worker-terminal/failed-start-dispatch-identity.ts new file mode 100644 index 00000000000..671b12c39a7 --- /dev/null +++ b/src/main/runtime/orchestration/db/worker-terminal/failed-start-dispatch-identity.ts @@ -0,0 +1,34 @@ +import type { WorkerDispatchRow } from '../../types' +import type { OrchestrationDb } from '../orchestration-db' + +/** + * A start that dies before `prepareStartingWorkerAuthority` never filled the Dispatch context in, + * and release re-proves identity through it — so the custody row written at terminal creation would + * name a pane no release path could match. Copy that identity across. + * + * `capability_hash` stays null, so this grants nothing: it records which pane the Dispatch owns. + * + * No transaction: composes inside `failWorkerStart`'s. + */ +export function recordFailedStartDispatchIdentity( + db: OrchestrationDb, + worker: WorkerDispatchRow +): void { + const resource = db.getWorkerTerminalResourceByOwner(worker.dispatch_id) + if (!resource || resource.terminal_handle !== worker.agent_terminal_handle) { + return + } + db.db + .prepare( + `UPDATE dispatch_contexts + SET assignee_handle = ?, assignee_pane_key = ?, process_incarnation = ?, host_scope = ? + WHERE id = ? AND status = 'failed' AND capability_hash IS NULL` + ) + .run( + resource.terminal_handle, + resource.pane_key, + resource.process_incarnation, + resource.host_scope, + worker.dispatch_id + ) +} diff --git a/src/main/runtime/orchestration/db/worker-terminal/failed-start-terminal-adoption.ts b/src/main/runtime/orchestration/db/worker-terminal/failed-start-terminal-adoption.ts deleted file mode 100644 index 607ae9f45a7..00000000000 --- a/src/main/runtime/orchestration/db/worker-terminal/failed-start-terminal-adoption.ts +++ /dev/null @@ -1,68 +0,0 @@ -import type { WorkerDispatchRow } from '../../types' -import type { OrchestrationDb } from '../orchestration-db' - -/** Identity of a terminal this worker-start created and never handed to an owner. */ -export type FailedStartTerminalAdoption = { - terminalHandle: string - worktreeId: string | null - paneKey: string - processIncarnation: string - hostScope?: string | null -} - -/** - * A start that dies before `prepareStartingWorkerAuthority` leaves the terminal it created with no - * owner, so no release path can ever close it and the fleet can only say `inspect`. Record the - * ownership the successful path would have recorded, so ordinary `worker-release` owns the cleanup. - * - * No transaction: composes inside `failWorkerStart`'s. - */ -export function adoptFailedStartTerminal( - db: OrchestrationDb, - worker: WorkerDispatchRow, - adoption: FailedStartTerminalAdoption | undefined -): void { - if (!adoption || worker.agent_terminal_handle !== adoption.terminalHandle) { - return - } - if (db.getWorkerTerminalResourceByOwner(worker.dispatch_id)) { - return - } - // A second owner for one process could close it twice, or close a terminal already handed on. - const conflict = db.db - .prepare( - `SELECT 1 FROM worker_terminal_resources - WHERE ownership_state <> 'released' - AND (terminal_handle = ? OR process_incarnation = ?) LIMIT 1` - ) - .get(adoption.terminalHandle, adoption.processIncarnation) - if (conflict) { - return - } - db.createWorkerTerminalResourceStatement({ - dispatchId: worker.dispatch_id, - worktreeId: adoption.worktreeId ?? worker.worktree_id, - terminalHandle: adoption.terminalHandle, - paneKey: adoption.paneKey, - processIncarnation: adoption.processIncarnation, - endpointId: worker.runtime_epoch ?? null, - endpointIncarnation: adoption.processIncarnation, - hostScope: adoption.hostScope ?? null, - ownership: 'owned' - }) - // Release re-proves identity through the Dispatch context, which a failed start never filled in. - // This records which pane the Dispatch owns; `capability_hash` stays null, so it grants nothing. - db.db - .prepare( - `UPDATE dispatch_contexts - SET assignee_handle = ?, assignee_pane_key = ?, process_incarnation = ?, host_scope = ? - WHERE id = ? AND status = 'failed' AND capability_hash IS NULL` - ) - .run( - adoption.terminalHandle, - adoption.paneKey, - adoption.processIncarnation, - adoption.hostScope ?? null, - worker.dispatch_id - ) -} diff --git a/src/main/runtime/orchestration/failed-start-terminal-adoption.test.ts b/src/main/runtime/orchestration/failed-start-terminal-adoption.test.ts deleted file mode 100644 index b980a7f2a25..00000000000 --- a/src/main/runtime/orchestration/failed-start-terminal-adoption.test.ts +++ /dev/null @@ -1,157 +0,0 @@ -import { afterEach, describe, expect, it } from 'vitest' -import { OrchestrationDb } from './db' - -const HANDLE = 'term_residual' -const PANE_KEY = 'tab_residual:leaf_residual' -const INCARNATION = 'runtime:pty-residual:1' - -describe('a start that fails before authority still owns the terminal it created', () => { - let db: OrchestrationDb | undefined - - afterEach(() => { - db?.close() - }) - - /** Replays the shipping order: readiness stage records the handle, then the wait fails. */ - function failStartAfterCreatingTerminal( - adoption?: Parameters[3] - ): { db: OrchestrationDb; dispatchId: string } { - const d = (db = new OrchestrationDb(':memory:')) - const task = d.createTask({ runId: 'run_legacy_local', spec: 'residual terminal' }) - const started = d.createStartingWorkerDispatch({ - creator: { kind: 'system' }, - maxDepth: Number.MAX_SAFE_INTEGER, - taskId: task.id, - startOptions: {} - }) - const effects = [ - { kind: 'terminal', role: 'agent', action: 'created', id: HANDLE, surface: 'visible' } - ] - d.recordWorkerStage({ - dispatchId: started.dispatch.id, - stage: 'terminal_readying', - worktreeId: 'repo::worktree', - terminalHandle: HANDLE, - effects, - residualResources: effects - }) - d.failWorkerStart( - started.dispatch.id, - 'agent_readiness', - 'Agent startup blocked: codex-interactive-prompt', - adoption - ) - return { db: d, dispatchId: started.dispatch.id } - } - - const adoption = { - adoptResidualTerminal: { - terminalHandle: HANDLE, - worktreeId: 'repo::worktree', - paneKey: PANE_KEY, - processIncarnation: INCARNATION, - hostScope: null - } - } - - it('leaves nothing that can close the terminal when the start is not adopted', () => { - const { db: d, dispatchId } = failStartAfterCreatingTerminal() - - expect(d.getWorkerTerminalResourceByOwner(dispatchId)).toBeUndefined() - expect(d.requestWorkerTerminalRelease(dispatchId)).toMatchObject({ - disposition: 'retained', - reason: 'no_owned_resource' - }) - }) - - it('records the ownership the successful path would have recorded', () => { - const { db: d, dispatchId } = failStartAfterCreatingTerminal(adoption) - - expect(d.getWorkerTerminalResourceByOwner(dispatchId)).toMatchObject({ - owner_dispatch_id: dispatchId, - terminal_handle: HANDLE, - pane_key: PANE_KEY, - process_incarnation: INCARNATION, - ownership_state: 'owned', - release_state: 'not_requested' - }) - }) - - it('lets worker-release proceed on the failed dispatch', () => { - const { db: d, dispatchId } = failStartAfterCreatingTerminal(adoption) - - expect(d.requestWorkerTerminalRelease(dispatchId)).toMatchObject({ - disposition: 'requested', - resource: { release_state: 'requested' } - }) - }) - - it('re-proves identity through the dispatch context release reads', () => { - const { db: d, dispatchId } = failStartAfterCreatingTerminal(adoption) - - expect( - d.isDispatchProcessCurrent({ dispatchId, paneKey: PANE_KEY, processIncarnation: INCARNATION }) - ).toBe(true) - // Adoption records which pane the dispatch owns; it never restores authority over it. - expect(d.getDispatchContextById(dispatchId)).toMatchObject({ - status: 'failed', - capability_hash: null - }) - expect(d.getDispatchContextById(dispatchId)?.capability_revoked_at).not.toBeNull() - }) - - it('publishes the terminal as reclaimable so the fleet names release', () => { - const { db: d, dispatchId } = failStartAfterCreatingTerminal(adoption) - - expect(d.listWorkerTerminalResources({ dispatchIds: [dispatchId] })[0]).toMatchObject({ - agentTerminalHandle: HANDLE, - terminalState: 'reclaimable' - }) - }) - - it('never claims a terminal the durable row does not name', () => { - const { db: d, dispatchId } = failStartAfterCreatingTerminal({ - adoptResidualTerminal: { ...adoption.adoptResidualTerminal, terminalHandle: 'term_other' } - }) - - expect(d.getWorkerTerminalResourceByOwner(dispatchId)).toBeUndefined() - }) - - it('never claims a terminal another live resource already accounts for', () => { - const d = (db = new OrchestrationDb(':memory:')) - const first = d.createStartingWorkerDispatch({ - creator: { kind: 'system' }, - maxDepth: Number.MAX_SAFE_INTEGER, - taskId: d.createTask({ runId: 'run_legacy_local', spec: 'owner' }).id, - startOptions: {} - }) - d.prepareStartingWorkerAuthority({ - dispatchId: first.dispatch.id, - handle: HANDLE, - paneKey: PANE_KEY, - processIncarnation: INCARNATION, - worktreeId: 'repo::worktree', - setupState: 'not_applicable', - effects: [], - terminalOwnership: 'created' - }) - const second = d.createStartingWorkerDispatch({ - creator: { kind: 'system' }, - maxDepth: Number.MAX_SAFE_INTEGER, - taskId: d.createTask({ runId: 'run_legacy_local', spec: 'claimant' }).id, - startOptions: {} - }) - d.recordWorkerStage({ - dispatchId: second.dispatch.id, - stage: 'terminal_readying', - terminalHandle: HANDLE - }) - - d.failWorkerStart(second.dispatch.id, 'agent_readiness', 'blocked', adoption) - - expect(d.getWorkerTerminalResourceByOwner(second.dispatch.id)).toBeUndefined() - expect(d.getWorkerTerminalResourceByOwner(first.dispatch.id)).toMatchObject({ - ownership_state: 'owned' - }) - }) -}) diff --git a/src/main/runtime/rpc/methods/orchestration/worker/created-worker-terminal-custody.ts b/src/main/runtime/rpc/methods/orchestration/worker/created-worker-terminal-custody.ts new file mode 100644 index 00000000000..c73884b1d96 --- /dev/null +++ b/src/main/runtime/rpc/methods/orchestration/worker/created-worker-terminal-custody.ts @@ -0,0 +1,32 @@ +import type { OrcaRuntimeService } from '../../../../orca-runtime' +import type { OrchestrationDb } from '../../../../orchestration/db' +import { requireWorkerAuthority } from './worker-topology' + +/** + * Custody for an agent terminal this start created, recorded when the terminal exists rather than + * after the agent boot wait: a keystroke into the booting pane has to find an `owned` row to flip, + * or the takeover is dropped and a later `worker-release` closes the pane under the user. + * + * Ownership of a pane only. The Dispatch capability still waits for the agent to come up. + * + * `created` is false for an explicit `--terminal` reuse, which is the caller's own pane, and for a + * structured session, which reaches its authority in this same turn and so has no gap to close. + */ +export function recordCreatedWorkerTerminalCustody( + runtime: OrcaRuntimeService, + stage: { db: OrchestrationDb; dispatchId: string; worktreeId: string; terminalHandle: string }, + created: boolean +): void { + if (!created) { + return + } + const authority = requireWorkerAuthority(runtime, stage.terminalHandle) + stage.db.recordCreatedWorkerTerminalCustody({ + dispatchId: stage.dispatchId, + handle: stage.terminalHandle, + paneKey: authority.paneKey, + processIncarnation: authority.processIncarnation, + worktreeId: stage.worktreeId, + hostScope: authority.hostScope ?? null + }) +} diff --git a/src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.test.ts b/src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.test.ts deleted file mode 100644 index 413a397462b..00000000000 --- a/src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.test.ts +++ /dev/null @@ -1,191 +0,0 @@ -import { afterEach, describe, expect, it } from 'vitest' -import type { OrcaRuntimeService } from '../../../../orca-runtime' -import { OrchestrationDb } from '../../../../orchestration/db' -import { resolveResidualAgentTerminal } from './failed-start-residual-terminal' -import { failWorkerStartWithReceipt } from './worker-start-receipt' -import type { WorkerEffect } from './worker-topology' - -const HANDLE = 'term_residual' -const PANE_KEY = 'tab_residual:leaf_residual' -const INCARNATION = 'pty-residual:1' - -const createdAgentTerminal: WorkerEffect = { - kind: 'terminal', - role: 'agent', - action: 'created', - id: HANDLE, - surface: 'visible' -} - -function createRuntime(overrides: Partial> = {}): OrcaRuntimeService { - return { - getOrchestrationDispatchAuthority: () => ({ - paneKey: PANE_KEY, - processIncarnation: INCARNATION, - hostScope: { kind: 'local', hostId: 'local' } - }), - getTerminalPaneKey: () => PANE_KEY, - getTerminalProcessIncarnation: () => INCARNATION, - ...overrides - } as unknown as OrcaRuntimeService -} - -describe('residual agent terminal left by a failed start', () => { - it('resolves identity for a terminal this start created', () => { - expect( - resolveResidualAgentTerminal({ - runtime: createRuntime(), - effects: [createdAgentTerminal], - terminalHandle: HANDLE, - worktreeId: 'repo::worktree' - }) - ).toEqual({ - terminalHandle: HANDLE, - worktreeId: 'repo::worktree', - paneKey: PANE_KEY, - processIncarnation: INCARNATION, - hostScope: JSON.stringify({ kind: 'local', hostId: 'local' }) - }) - }) - - it('resolves the agent-first worktree terminal the same way', () => { - expect( - resolveResidualAgentTerminal({ - runtime: createRuntime(), - effects: [{ ...createdAgentTerminal, action: 'reused_agent_terminal' }], - terminalHandle: HANDLE, - worktreeId: null - }) - ).toMatchObject({ terminalHandle: HANDLE }) - }) - - it('never claims a caller-supplied terminal', () => { - expect( - resolveResidualAgentTerminal({ - runtime: createRuntime(), - effects: [{ ...createdAgentTerminal, action: 'reused' }], - terminalHandle: HANDLE, - worktreeId: null - }) - ).toBeUndefined() - }) - - it('never claims a setup terminal', () => { - expect( - resolveResidualAgentTerminal({ - runtime: createRuntime(), - effects: [{ ...createdAgentTerminal, role: 'setup' }], - terminalHandle: HANDLE, - worktreeId: null - }) - ).toBeUndefined() - }) - - it('refuses a pane whose process cannot be identified', () => { - expect( - resolveResidualAgentTerminal({ - runtime: createRuntime({ - getOrchestrationDispatchAuthority: () => null, - getTerminalProcessIncarnation: () => null - }), - effects: [createdAgentTerminal], - terminalHandle: HANDLE, - worktreeId: null - }) - ).toBeUndefined() - }) - - it('refuses when the start never resolved a terminal', () => { - expect( - resolveResidualAgentTerminal({ - runtime: createRuntime(), - effects: [], - terminalHandle: undefined, - worktreeId: null - }) - ).toBeUndefined() - }) - - it('stays silent when identity resolution throws', () => { - expect( - resolveResidualAgentTerminal({ - runtime: createRuntime({ - getOrchestrationDispatchAuthority: () => { - throw new Error('handle retired') - } - }), - effects: [createdAgentTerminal], - terminalHandle: HANDLE, - worktreeId: null - }) - ).toBeUndefined() - }) -}) - -describe('failed worker-start receipt for a residual terminal', () => { - let db: OrchestrationDb | undefined - - afterEach(() => { - db?.close() - }) - - function failStart(residual: boolean): { recovery?: string } { - const d = (db = new OrchestrationDb(':memory:')) - const task = d.createTask({ runId: 'run_legacy_local', spec: 'residual receipt' }) - const started = d.createStartingWorkerDispatch({ - creator: { kind: 'system' }, - maxDepth: Number.MAX_SAFE_INTEGER, - taskId: task.id, - startOptions: {} - }) - d.recordWorkerStage({ - dispatchId: started.dispatch.id, - stage: 'terminal_readying', - terminalHandle: HANDLE, - effects: [createdAgentTerminal], - residualResources: [createdAgentTerminal] - }) - return failWorkerStartWithReceipt({ - db: d, - mode: { - mode: 'terminal', - preferred: 'terminal', - reason: 'user_default', - detail: 'terminal by default' - } as const, - runId: 'run_residual', - taskId: task.id, - dispatchId: started.dispatch.id, - failedStage: 'agent_readiness', - error: new Error('Agent startup blocked: codex-interactive-prompt'), - setup: { - requested: 'not_applicable', - effective: 'not_applicable', - source: 'existing_worktree', - hookFound: false, - startupPolicy: 'start-immediately', - state: 'not_applicable' - }, - launch: { requested: { agent: 'codex' }, effective: { agent: 'codex' } } as never, - ...(residual - ? { - residualAgentTerminal: { - terminalHandle: HANDLE, - worktreeId: 'repo::worktree', - paneKey: PANE_KEY, - processIncarnation: INCARNATION, - hostScope: null - } - } - : {}) - }) as { recovery?: string } - } - - it('names worker-release for the terminal it left behind', () => { - expect(failStart(true).recovery).toContain('worker-release') - }) - - it('promises no cleanup when there is no residual terminal', () => { - expect(failStart(false).recovery).toBeUndefined() - }) -}) diff --git a/src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.ts b/src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.ts deleted file mode 100644 index e42923e93a9..00000000000 --- a/src/main/runtime/rpc/methods/orchestration/worker/failed-start-residual-terminal.ts +++ /dev/null @@ -1,53 +0,0 @@ -import type { OrcaRuntimeService } from '../../../../orca-runtime' -import type { FailedStartTerminalAdoption } from '../../../../orchestration/db/worker-terminal/failed-start-terminal-adoption' -import type { WorkerEffect } from './worker-topology' - -/** True only for an agent terminal this worker-start brought into existence. An explicit - * `--terminal` reuse records `reused` and is never residual — it is the caller's terminal. */ -function orchestrationCreatedAgentTerminal( - effects: readonly WorkerEffect[], - handle: string -): boolean { - return effects.some( - (effect) => - effect.kind === 'terminal' && - effect.role === 'agent' && - effect.id === handle && - (effect.action?.startsWith('created') === true || effect.action === 'reused_agent_terminal') - ) -} - -/** - * Identity for the terminal a failed start leaves behind, so the failed Dispatch can own it and - * `worker-release` can close it. Returns nothing unless the pane and process are both provable: - * an unprovable identity must never authorize a later close. - */ -export function resolveResidualAgentTerminal(args: { - runtime: OrcaRuntimeService - effects: readonly WorkerEffect[] - terminalHandle: string | undefined - worktreeId: string | null -}): FailedStartTerminalAdoption | undefined { - const handle = args.terminalHandle - if (!handle || !orchestrationCreatedAgentTerminal(args.effects, handle)) { - return undefined - } - try { - const authority = args.runtime.getOrchestrationDispatchAuthority(handle) - const paneKey = authority?.paneKey ?? args.runtime.getTerminalPaneKey(handle) - const processIncarnation = - authority?.processIncarnation ?? args.runtime.getTerminalProcessIncarnation(handle) - if (!paneKey || !processIncarnation) { - return undefined - } - return { - terminalHandle: handle, - worktreeId: args.worktreeId, - paneKey, - processIncarnation, - hostScope: authority?.hostScope ? JSON.stringify(authority.hostScope) : null - } - } catch { - return undefined - } -} diff --git a/src/main/runtime/rpc/methods/orchestration/worker/failed-worker-start-teardown.ts b/src/main/runtime/rpc/methods/orchestration/worker/failed-worker-start-teardown.ts index 32827377b54..250b639fc60 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/failed-worker-start-teardown.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/failed-worker-start-teardown.ts @@ -3,40 +3,27 @@ import { discardStructuredWorkerSession, releaseStructuredWorkerSession } from '../../orchestration-structured-worker-session' -import { resolveResidualAgentTerminal } from './failed-start-residual-terminal' import type { createStructuredWorkerSessionForWorktree } from './worker-topology' -import type { FailedStartTerminalAdoption } from '../../../../orchestration/db/worker-terminal/failed-start-terminal-adoption' /** - * Undoes what a start created before it failed, and reports what `worker-release` still owns. + * Undoes what a start created before it failed. * * A start that never reached ready leaves no settlement to release the hold later, and its session * was already published as a chat tab — without the discard, a failed start strands a dead chat tab * that the durable restore index republishes on every app launch. Both halves are best-effort by * construction, so neither can replace the real error. + * + * A created PTY terminal is deliberately NOT torn down: its custody row was written at creation, so + * `worker-release` on the failed Dispatch owns that cleanup and the coordinator decides when. */ export async function tearDownFailedWorkerStart(args: { runtime: OrcaRuntimeService structuredSession: Awaited> | null dispatchId: string - effects: unknown[] - terminalHandle: string | undefined - worktreeId: string | null -}): Promise { +}): Promise { const { runtime, structuredSession } = args - // A structured session is torn down outright here, so it must never also be adopted as a residual - // terminal for `worker-release` to close a second time. - const residualAgentTerminal = structuredSession - ? undefined - : resolveResidualAgentTerminal({ - runtime, - effects: args.effects as never, - terminalHandle: args.terminalHandle, - worktreeId: args.worktreeId - }) releaseStructuredWorkerSession(args.dispatchId, runtime) if (structuredSession) { await discardStructuredWorkerSession(structuredSession.identity.sessionId, runtime) } - return residualAgentTerminal } diff --git a/src/main/runtime/rpc/methods/orchestration/worker/local-worker-start.ts b/src/main/runtime/rpc/methods/orchestration/worker/local-worker-start.ts index 48b14f9a84e..d67d09b766a 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/local-worker-start.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/local-worker-start.ts @@ -19,6 +19,7 @@ import { failWorkerStartWithReceipt } from './worker-start-receipt' import { parseTaskDeps } from './task-deps-argument' import { assertExplicitWorkerTerminalUsable } from './explicit-worker-terminal-validation' import { deliverWorkerDispatchPreamble } from './deliver-worker-dispatch-preamble' +import { recordCreatedWorkerTerminalCustody } from './created-worker-terminal-custody' import { tearDownFailedWorkerStart } from './failed-worker-start-teardown' import { createExistingWorktreeWorkerTerminal, @@ -203,6 +204,7 @@ export async function startLocalWorker(args: { setup: setupReceipt, effects } + recordCreatedWorkerTerminalCustody(runtime, setupStage, !params.terminal && !structuredSession) if (persistGatedSetupSpawnFailure(setupStage)) { failedStage = 'setup_start' throw new Error('Setup terminal failed to start before the gated agent launch.') @@ -285,13 +287,10 @@ export async function startLocalWorker(args: { ...(terminalRevealWarning ? { warning: terminalRevealWarning } : {}) } } catch (error) { - const residualAgentTerminal = await tearDownFailedWorkerStart({ + await tearDownFailedWorkerStart({ runtime, structuredSession, - dispatchId: started.dispatch.id, - effects, - terminalHandle, - worktreeId: resolvedWorktree?.id ?? null + dispatchId: started.dispatch.id }) return failWorkerStartWithReceipt({ db, @@ -302,8 +301,7 @@ export async function startLocalWorker(args: { error, setup: setupReceipt, launch: launch.receipt, - mode, - ...(residualAgentTerminal ? { residualAgentTerminal } : {}) + mode }) } } diff --git a/src/main/runtime/rpc/methods/orchestration/worker/worker-start-receipt.ts b/src/main/runtime/rpc/methods/orchestration/worker/worker-start-receipt.ts index 9fd98dd9db3..f2dee00b44c 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/worker-start-receipt.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/worker-start-receipt.ts @@ -4,8 +4,8 @@ import { isUnknownWorkerStartOutcome, type WorkerSetupReceipt } from './worker-t import type { OrchestrationWorkerLaunchReceipt } from './worker-launch-preferences' import type { WorkerStartModeReceipt } from '../../orchestration-worker-start-mode' import { isAgentSessionPtyWriteRefusedError } from '../../../../../../shared/agent-session-pty-write-admission' -import type { FailedStartTerminalAdoption } from '../../../../orchestration/db/worker-terminal/failed-start-terminal-adoption' import { structuredChatPtyWriteRefusalCopy } from '../../../../../../shared/agent-session-pty-write-refusal-copy' +import { isStructuredWorkerHandle } from '../../../../structured-worker-identity' export function failWorkerStartWithReceipt(args: { db: OrchestrationDb @@ -17,8 +17,6 @@ export function failWorkerStartWithReceipt(args: { setup: WorkerSetupReceipt launch: OrchestrationWorkerLaunchReceipt mode: WorkerStartModeReceipt - /** The terminal this start created and never handed to an owner. */ - residualAgentTerminal?: FailedStartTerminalAdoption }): unknown { const agentSessionRefusal = isAgentSessionPtyWriteRefusedError(args.error) ? args.error.refusal @@ -33,14 +31,14 @@ export function failWorkerStartWithReceipt(args: { : args.db.failWorkerStart(args.dispatchId, args.failedStage, reason, { // Why (#16095): the preamble is written before submission is verified, so a stalled // verdict never means the worker lacks its task — keep the authority its report needs. - retainCapability: isAgentPromptStalledError(args.error), - ...(args.residualAgentTerminal ? { adoptResidualTerminal: args.residualAgentTerminal } : {}) + retainCapability: isAgentPromptStalledError(args.error) }) - // Only claim cleanup the ownership table actually accepted; the adoption declines a terminal - // another resource already accounts for. - const adopted = - Boolean(args.residualAgentTerminal) && - Boolean(args.db.getWorkerTerminalResourceByOwner(args.dispatchId)) + // Only name cleanup this start actually left behind: a terminal it created and still owns. A + // structured session is discarded by the teardown, a pane the user typed into is theirs, and an + // unknown outcome is not settled — none of the three has anything for `worker-release` to close. + const residual = unknown ? undefined : args.db.getWorkerTerminalResourceByOwner(args.dispatchId) + const releasable = + residual?.ownership_state === 'owned' && !isStructuredWorkerHandle(residual.terminal_handle) return { runId: args.runId, taskId: args.taskId, @@ -55,7 +53,7 @@ export function failWorkerStartWithReceipt(args: { effects: JSON.parse(worker.effects) as unknown[], residualResources: JSON.parse(worker.residual_resources) as unknown[], ...(agentSessionRefusal ? { agentSessionRefusal } : {}), - ...(adopted + ...(releasable ? { recovery: `This start created a terminal that never ran the Task. Close it with: orca orchestration worker-release --dispatch ${args.dispatchId}` } diff --git a/src/main/runtime/rpc/methods/orchestration/worker/worker-terminal-custody-at-creation.test.ts b/src/main/runtime/rpc/methods/orchestration/worker/worker-terminal-custody-at-creation.test.ts new file mode 100644 index 00000000000..201201e5877 --- /dev/null +++ b/src/main/runtime/rpc/methods/orchestration/worker/worker-terminal-custody-at-creation.test.ts @@ -0,0 +1,216 @@ +/** + * Custody for an agent terminal this start created is written when the terminal is created, not + * after the agent boot wait. + * + * A worker pane is visible on desktop and phone the moment it exists. While the row was written + * only after `tui-idle` (up to 60 s later), a keystroke into the booting pane found no `owned` row, + * `markWorkerTerminalUserOwned` returned 0, and the takeover was lost — so a later `worker-release` + * closed the pane the user had claimed. + */ + +import { afterEach, describe, expect, it, vi } from 'vitest' +import { OrchestrationDb } from '../../../../orchestration/db' +import { createOrchestrationWorkerReleaseHarness } from './worker-release.test-support' + +const READY_WAIT = { + handle: 'term_worker', + condition: 'tui-idle', + satisfied: true, + status: 'running', + exitCode: null +} + +describe('worker terminal custody is recorded at terminal creation', () => { + const h = createOrchestrationWorkerReleaseHarness() + + afterEach(() => h.cleanup()) + + /** Holds the agent boot wait open so the mid-start database state can be read. */ + function holdBootWait(): { finish: (satisfied?: boolean) => void } { + const gate = h.deferred() + vi.spyOn(h.runtime, 'waitForTerminal').mockReturnValue(gate.promise as never) + return { + finish: (satisfied = true) => + gate.resolve({ ...READY_WAIT, satisfied, status: satisfied ? 'running' : 'exited' }) + } + } + + function startingDispatchId(): string { + return ( + h.db.db + .prepare("SELECT dispatch_id FROM worker_dispatches WHERE state = 'starting'") + .get() as { dispatch_id: string } + ).dispatch_id + } + + async function startHeldAtBootWait(options: { terminal?: string } = {}): Promise<{ + dispatchId: string + taskId: string + start: Promise + finish: (satisfied?: boolean) => void + }> { + const task = h.db.createTask({ spec: 'custody at creation', runId: h.activeRunId }) + const { finish } = holdBootWait() + const start = h.call('orchestration.workerStart', { + task: task.id, + from: 'term_coord', + ...(options.terminal ? { terminal: options.terminal } : { agent: 'codex' }) + }) + await vi.waitFor(() => expect(h.runtime.waitForTerminal).toHaveBeenCalled()) + return { dispatchId: startingDispatchId(), taskId: task.id, start, finish } + } + + it('owns the created terminal before the boot wait resolves', async () => { + h.setup() + const held = await startHeldAtBootWait() + + expect(h.db.getWorkerTerminalResourceByOwner(held.dispatchId)).toMatchObject({ + ownership_state: 'owned', + release_state: 'not_requested', + terminal_handle: 'term_worker', + pane_key: h.workerPaneKey, + process_incarnation: 'runtime_test:term_worker:1', + host_scope: JSON.stringify({ kind: 'local', hostId: 'local' }) + }) + // worker-list reads the same row: a booting worker now says `active`, not `retained`. + expect(h.db.listWorkerTerminalResources({ dispatchIds: [held.dispatchId] })[0]).toMatchObject({ + agentTerminalHandle: 'term_worker', + terminalState: 'active' + }) + + held.finish() + await expect(held.start).resolves.toMatchObject({ state: 'ready' }) + }) + + it('claims nothing for an explicitly reused terminal until authority transfers it', async () => { + h.setup() + const held = await startHeldAtBootWait({ terminal: 'term_worker' }) + + expect(h.db.getWorkerTerminalResourceByOwner(held.dispatchId)).toBeUndefined() + + held.finish() + await expect(held.start).resolves.toMatchObject({ state: 'ready' }) + expect(h.db.getWorkerTerminalResourceByOwner(held.dispatchId)).toMatchObject({ + ownership_state: 'external', + retained_reason: 'external_terminal' + }) + }) + + it('lets a keystroke during the boot wait take the pane, and release then retains it', async () => { + h.setup() + const held = await startHeldAtBootWait() + + await expect( + h.call('orchestration.workerTerminalUserInput', { paneKey: h.workerPaneKey }) + ).resolves.toEqual({ changed: 1 }) + + held.finish() + await expect(held.start).resolves.toMatchObject({ state: 'ready' }) + expect(h.db.getWorkerTerminalResourceByOwner(held.dispatchId)).toMatchObject({ + ownership_state: 'user_owned', + retained_reason: 'user_takeover' + }) + + h.settle(held.taskId, held.dispatchId, 'succeeded') + await expect( + h.call('orchestration.workerRelease', { dispatch: held.dispatchId }) + ).resolves.toMatchObject({ state: 'retained', reason: 'user_takeover', processAction: 'none' }) + expect(h.runtime.closeTerminal).not.toHaveBeenCalled() + }) + + it('still refuses to release a starting worker that already owns its terminal', async () => { + h.setup() + const held = await startHeldAtBootWait() + + await expect( + h.call('orchestration.workerRelease', { dispatch: held.dispatchId }) + ).rejects.toThrow(/only a settled worker can release/) + + held.finish() + await held.start + }) + + it('leaves a start that died on the boot wait a terminal worker-release can close', async () => { + h.setup() + const held = await startHeldAtBootWait() + held.finish(false) + + await expect(held.start).resolves.toMatchObject({ + state: 'failed', + failedStage: 'agent_readiness', + recovery: expect.stringContaining('worker-release') + }) + expect(h.db.getWorkerTerminalResourceByOwner(held.dispatchId)).toMatchObject({ + ownership_state: 'owned', + terminal_handle: 'term_worker' + }) + + await expect( + h.call('orchestration.workerRelease', { dispatch: held.dispatchId }) + ).resolves.toMatchObject({ state: 'released', processAction: 'closed_agent_terminal' }) + expect(h.runtime.closeTerminal).toHaveBeenCalledWith('term_worker') + }) + + it('promises no cleanup while the start outcome is still unknown', async () => { + h.setup() + const task = h.db.createTask({ spec: 'unknown outcome', runId: h.activeRunId }) + const unknown = Object.assign(new Error('the execution host went away'), { + code: 'operation_unknown' + }) + vi.spyOn(h.runtime, 'waitForTerminal').mockRejectedValue(unknown) + + const receipt = (await h.call('orchestration.workerStart', { + task: task.id, + from: 'term_coord', + agent: 'codex' + })) as { state: string; dispatchId: string; nextCommands?: string[] } + + expect(receipt).toMatchObject({ state: 'outcome_unknown' }) + // worker-release refuses an unsettled worker, so the receipt must not name it. + expect(receipt).not.toHaveProperty('recovery') + expect(receipt.nextCommands?.join(' ')).toContain('worker-abandon') + expect(h.db.getWorkerTerminalResourceByOwner(receipt.dispatchId)).toMatchObject({ + ownership_state: 'owned' + }) + }) + + it('promises no cleanup for a reused terminal whose start died', async () => { + h.setup() + const held = await startHeldAtBootWait({ terminal: 'term_worker' }) + held.finish(false) + + const receipt = await held.start + expect(receipt).toMatchObject({ state: 'failed' }) + expect(receipt).not.toHaveProperty('recovery') + expect(h.db.getWorkerTerminalResourceByOwner(held.dispatchId)).toBeUndefined() + }) +}) + +describe('custody refuses a dispatch that stopped while its terminal was being created', () => { + let db: OrchestrationDb | undefined + + afterEach(() => db?.close()) + + it('records no owner once the dispatch is no longer starting', () => { + const d = (db = new OrchestrationDb(':memory:')) + const started = d.createStartingWorkerDispatch({ + creator: { kind: 'system' }, + maxDepth: Number.MAX_SAFE_INTEGER, + taskId: d.createTask({ runId: 'run_legacy_local', spec: 'stopped mid-create' }).id, + startOptions: {} + }) + // Startup reconciliation abandons a `starting` worker whose terminal it cannot find. + d.reconcileMissingWorkerTerminal(started.dispatch.id, 'runtime restarted') + + expect(() => + d.recordCreatedWorkerTerminalCustody({ + dispatchId: started.dispatch.id, + handle: 'term_worker', + paneKey: 'tab_w:leaf_w', + processIncarnation: 'pty_w:1', + worktreeId: 'repo::worktree' + }) + ).toThrow(/is not starting/) + expect(d.getWorkerTerminalResourceByOwner(started.dispatch.id)).toBeUndefined() + }) +}) diff --git a/src/renderer/src/i18n/en-runtime-required.json b/src/renderer/src/i18n/en-runtime-required.json index 47024572e8c..a1c33b790bc 100644 --- a/src/renderer/src/i18n/en-runtime-required.json +++ b/src/renderer/src/i18n/en-runtime-required.json @@ -1503,16 +1503,7 @@ "ask_before_closing_running_terminals_description": "Show a confirmation before closing a terminal that has a running command or agent.", "ask_before_closing_running_terminals_title": "Ask Before Closing Running Terminals", "cc8c5ca224": "Windows default", - "d78fc4fdef": "Loading distributions", - "minimumContrast": { - "automatic": "Automatic: {{light}} on light backgrounds, {{dark}} on dark.", - "description": "Lifts terminal foreground colors that sit too close to the background. Leave blank for automatic, or set 1 to render program colors exactly as sent.", - "disabled": "Correction off. Programs that rely on low contrast, like Powerline separators, render as sent.", - "pinned": "Targets {{ratio}}:1 contrast for foreground colors, where possible.", - "placeholder": "Auto", - "suffix": "blank = automatic, 1 = off", - "title": "Minimum Contrast Ratio" - } + "d78fc4fdef": "Loading distributions" }, "TerminalSettingsPreview": { "d06664e889": "dark" From 8f78c28248fbfa4d55fb837ab6698ac77d4e35c5 Mon Sep 17 00:00:00 2001 From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com> Date: Tue, 8 Sep 2026 14:48:57 -0400 Subject: [PATCH 14/59] fix(orchestration): fence worker release on mobile keystrokes (#19337) * fix(orchestration): fence worker release on mobile keystrokes A settled worker's terminal stayed ownership_state='owned' unless a takeover was recorded, and the only recorder was orchestration.workerTerminalUserInput, which only the desktop/web xterm input signal and the native-chat composer call. Mobile input arrives as terminal.send / stream input frames instead of a report, so a phone user typing in a settled worker's pane never fenced anything: worker-list kept recommending release and worker-release closed the PTY under them. Give the host one definition of "a human typed into this terminal" and route every lane through it. The mobile input floor claim is that definition and already exists on both byte lanes: it is taken only for deliberate phone input, never for the emulator's own query replies, and never for an agent's `orca terminal send`, which names itself a desktop client and so is indistinguishable from a keystroke at this layer. Settling that claim after an accepted write now records the takeover through the same code the RPC reporter uses, throttled to one write per pane per 30s so a keystroke does not pay for an immediate transaction. The record lands on the runtime that owns both the terminal and the orchestration database, so SSH-hosted and remote workers behave exactly like local ones. No mobile change: mobile already sends client.type (mobile/src/terminal/terminal-send-request.ts:24). * fix(orchestration): ask the database, do not remember, whether a pane is fenced The keystroke throttle armed on the attempt rather than on the outcome, so a zero-row or thrown record poisoned the pane for 30s. A phone keystroke during the worker-start readiness wait lands before prepareStartingWorkerAuthority creates the owned resource; a real keystroke seconds later was then suppressed, the worker settled, and workerRelease closed the terminal under the phone user. A SQLITE_BUSY on the first write did the same, with no retry. The cache was the defect, not its arming condition. Its precondition is the set of owned resources on the pane, which changes underneath it, and any cache keyed on ownership identity would have to read the database to learn that identity -- which is the whole question. So the input lane now asks: a read using the same predicate the write uses answers "is anything still fenceable here?" without taking BEGIN IMMEDIATE, and only then is the write attempted. Ordinary typing costs a lookup instead of a write lock, a failed write is retried by the next keystroke, and a takeover writes once per ownership epoch rather than once per window, because the flip to user_owned removes the pane from the candidate set. Sharing the predicate keeps the probe from drifting from the writer. Adds the two escape cases as permanent regressions, drives the mocked send through the real RuntimeTerminalWriter, and asserts a mobile takeover lifts the settled-worker resume fence, which no test covered. * refactor(orchestration): let the database dedupe the takeover, drop the read probe The probe was meant to keep keystrokes off BEGIN IMMEDIATE, so it had to earn that with a number. Measured against a real WAL database it costs more than the write it avoids: at 25 live workers the probe is 0.19ms and the no-op write is 0.10ms, because the probe runs the same candidate selection with each statement taking its own read snapshot instead of sharing the transaction's. It is a compensating mechanism with negative value, so it goes, along with the database method and the predicate extraction it needed. owned -> user_owned is one-way and scoped to a resource, so the database is already the dedupe: every deliberate human write attempts the transition, the second attempt matches no row, and the fence sweep runs only on changed > 0. Nothing is remembered between keystrokes, so no state can outlive the ownership it described -- a keystroke before the worker's authority attaches, a write the database refuses, and a re-dispatch onto the same pane all resolve against the rows as they are at that instant. An attempt costs about 0.1ms at typical fleet size and 0.34ms at 100 live workers, on mobile writes only. Replaces the write-count test, which asserted the old mechanism, with the invariant: many keystrokes settle into one takeover and one fence sweep. Adds the re-dispatch case, where a pane's next worker is fenced on its own merits. * refactor(terminal): name the provenance rule the takeover fence hangs off The fence rode the mobile input floor claim, with only a comment tying the two together. The floor is arbitration -- who may write next -- while the fence needs provenance -- who produced the bytes. They agree today, so anyone reweighing the floor would have moved the fence without noticing. isDeliberateHumanInput states the provenance rule on its own terms, and both byte lanes decide with it when they open a write: the claim carries the verdict beside the handle, and settlement records the takeover only when a human produced the bytes. No behavior change -- afterWrite is wired only where the predicate already answers true -- and the rule is now pinned by its own cases, so a future arbitration change has to answer this question again rather than inherit it. * test(orchestration): prove the unary lane classifies a metadata-less phone A phone build older than client.type is recognised only by its pane's mobile driver, which the unary lane passes as the provenance evidence. Nothing proved it did: replacing that argument with false left all 17 tests green while a shipped phone silently stopped fencing worker release. The new case drives a clientless send on a mobile-driven pane and fails under that mutation. The stream lane now passes false outright. Its isMobile is read off the same client object it carries, so the metadata-less phone cannot reach it, and passing the flag suggested a legacy path that does not exist there. Also states what the per-keystroke cost scales with. A pane owning no resource misses the pane_key index and falls through to a scan of owned resources, so the figure is tens of microseconds at realistic worker counts rather than a flat 0.1ms, and it grows with rows that are never released. * fix(terminal): let provenance alone decide the takeover, on every accepted write A phone older than client.type sends no client metadata, and both stream initializers derive isMobile from that metadata alone, so such a subscription reported false and took the stream lane's uninstrumented branch: provenance was computed and then never consumed. Bytes from a real person landed through both frame adapters and the resource stayed owned, so workerRelease closed the PTY under them. The unary lane already fenced that population off the pane's mobile driver, which is the host's standing reading of clientless input, so the two byte lanes disagreed at the destructive boundary. The predicate was still subordinate to floor plumbing: it could only be consulted where a floor client id existed. Now the accepted-write callback attaches on both lanes regardless of whether a floor was reserved, and humanInput alone decides recording; a write holding no claim commits nothing. Arbitration keeps its own condition around reserveWrite, where it belongs, and the unary lane's duplicate outer provenance filter is gone. The stream lane reads clientless provenance from the pane's driver, the same policy the unary lane uses. The claim holder is now TerminalInputWrite, carrying the verdict beside an optional floorClaim, so the structure says what the doc said: a write may fence without holding the floor. Regressions drive both real frame adapters, clientless direct delivery, and the paired-web desktop negative. Metadata-only provenance fails 3 on the stream lane and 1 on the unary lane; gating the callback on a reservation fails the same 3. * fix(runtime): resolve retained handles before mobile input provenance A renderer reload clears transient handles while retaining runtime-owned PTY identities. Legacy mobile provenance saw no leaf, then sendTerminal restored the same handle and delivered an unfenced key. Normalize through getLivePtyForHandle at the shared live-leaf resolver entry so classification and writes agree, preserving existing leaf generation/incarnation checks. Caller audit: - terminal-send-method: driver, query-reply authority, lock and floor checks now resolve the retained PTY before sending. - terminal-input-delivery: legacy mobile classification and exact-PTY binding now see the same target as the writer; equality checks remain. - terminal-multiplex-subscribe-resolution: retained PTYs resolve directly without a spurious missing-terminal wait. - terminal-lifecycle-methods resize and terminal-viewport-methods display mode, restore-fit and updateViewport retain their original PTY target. - inspectTerminalProcess: avoids false terminal_gone after reload while preserving provider inspection and incarnation fences. - getLivePaneKeyForTerminalHandle and getOrchestrationDispatchAuthority: unaffected because both already call getLivePtyForHandle first. No wire/schema changes, host fallback, process-death inference, or Git workspace assumptions; SSH providers keep ownership of execution evidence. Validation: - Unmodified round-3 reviewer probe: reproduced 2/2 failures, then 2/2 pass. - Unmodified round-2 reviewer probes: 13/13 pass. - Checked-in takeover suites: 24/24 pass. Removing only the resolver call fails both new reload cases; source restored afterward. - RPC orchestration + terminal, aggregate runtime handle registry, handle incarnation, mobile tab mount, stale geometry, and reload probe: 2027 passed, 1 skipped (89 files). - tc:node and check:code-quality:changed pass; background launch enabled. * test(rpc): require unconditional terminal afterWrite callbacks Update exact sendTerminal expectations for the round-2 accepted-write contract. Preserve beforeWrite expectations, absence of reserveWrite, byte payloads and call-count checks; require afterWrite to be a function. Reproduced the requested two-file run: 5 failed, 31 passed. The full RPC suite exposed the same stale shape in ACK budget/overflow, desktop resize (including its later retry), and agent-prompt fallback assertions. Update those too, for 11 assertions across six test files. No production changes. Validation: ORCA_BACKGROUND_LAUNCH=1 full src/main/runtime/rpc suite: 264 files passed; 2292 tests passed, 1 skipped. Changed-code quality and staged oxlint/React Doctor/oxfmt checks passed. Ran lint-staged --no-stash manually to honor checkout safety rather than its default backup hook. * fix(mobile): report worker takeover outside terminal byte delivery New phones announce accepted real user input through the existing worker report RPC, addressed by terminal handle. Share a per-client/per-handle 30-second gate with one bounded retry; report through the same RPC client as the input. Cover live commits and dictation via their shared sender, accessory keys, gestures, buffered submit, paste and accepted native chat. Query replies, attachment heals, triage and diff-review sends do not report. Phones predating this build do not fence release. Remove byte provenance and takeover callbacks from host delivery. Restore both lanes' pre-PR floor-claim plumbing and the original options assertions. Keep the host recorder uncached with its conditional resume-fence sweep. No DB schema or stream change; terminal is an optional report address. Retain the shared resolver recovery independently of takeover: the new SSH inspection test fails without it during renderer reload. Other callers still benefit for subscription, resize, viewport and exact-PTY binding; unary driver/lock checks see the retained PTY. Pane routing and dispatch authority already recover through getLivePtyForHandle and are unaffected. Existing leaf generation checks and first-PTY adoption remain unchanged. No other input-plumbing hunk is retained relative to the PR base. Replace byte-takeover tests with handle-addressed local/SSH report and unknown-handle tests, plus real unary/stream writes asserting zero SQL prepare/exec calls. Mobile send-site integration covers reports, exclusions, rejected writes and gate counts. Desktop report tests are unchanged. Register replacement coverage in the settled-worker release manifest. Validation (all background): host/RPC/runtime 3541 passed, 2 skipped; mobile session/terminal 2045 passed; node and mobile typechecks, changed quality, mobile oxlint, reliability manifest and max-lines ratchet passed. All five requested mutations fail assertions; resolver revert also fails independent inspection. Staged checks run manually with --no-stash. Final src diff against PR base: 5 files, +165/-13 (previously +839/-85). * fix(runtime): allow the takeover report from mobile-scoped tokens The mobile RPC allow-list gates every phone request before dispatch and the reporter swallows a refusal, so without this entry every phone shipped unfenced. Pin it beside the report tests, and pin the once-per-takeover fence sweep the replaced byte-lane suite used to assert. * fix(mobile): a no-op takeover report does not arm the gate; Stop reports too A key during worker startup reports before the resource is owned; caching that zero-change reply for 30 s suppressed the report that would have fenced the worker once it attached. Native-chat Stop is deliberate input and now reports on an accepted Escape. * fix(mobile): takeover gate ignores the host answer, like desktop Reopening the gate on a zero-change reply made every accepted key on an ordinary terminal an RPC plus a host write transaction (round 6: 100 for 100). The startup window it closed is unreachable: the agent has no prompt to accept input until after its resource row exists. Plain terminals now pay one report per 30 s window; the native-chat Stop report stays. Send-site fixture answers the report RPC with a changed count; the draft test filters to terminal.send calls. * docs(runtime): say why resolveLiveLeafForHandle re-links before lookup * chore(i18n): regenerate the runtime-required catalog for the contrast floor strings * test(orchestration): give the stopping-worker guard fixtures a Run * test(orchestration): drop fence-sweep assertions retired by the settled-worker policy * test(orchestration): pin the mid-boot phone takeover that #19608 makes possible A handle-addressed report during the worker's tui-idle wait now finds the custody row written at terminal creation, so it flips the pane to user_owned and worker-release retains it instead of closing it under the user. --- config/reliability-gates.jsonc | 21 +- ...mobile-native-chat-permission-send.test.ts | 5 + .../session/mobile-native-chat-send.test.ts | 18 +- mobile/src/session/mobile-native-chat-send.ts | 7 +- .../mobile-session-route-parity.test.ts | 4 +- .../mobile-worker-takeover-send-sites.test.ts | 267 ++++++++++++++++++ ...use-mobile-native-chat-answer-send.test.ts | 5 + .../use-mobile-native-chat-stop.test.ts | 29 ++ .../session/use-mobile-native-chat-stop.ts | 3 + .../use-mobile-session-terminal-input.ts | 7 +- ...se-mobile-session-terminal-send-actions.ts | 15 +- .../src/session/use-mobile-terminal-paste.ts | 7 +- .../terminal-live-accessory-raw-send.ts | 12 +- .../worker-terminal-takeover-report.test.ts | 82 ++++++ .../worker-terminal-takeover-report.ts | 59 ++++ ...time-serialize-headless-terminal-buffer.ts | 3 + ...untime-terminal-handle-incarnation.test.ts | 22 ++ .../worker-release-mobile-report.test.ts | 165 +++++++++++ .../orchestration/worker/worker-release.ts | 16 +- .../runtime-rpc-mobile-method-allowlist.ts | 2 + 20 files changed, 733 insertions(+), 16 deletions(-) create mode 100644 mobile/src/session/mobile-worker-takeover-send-sites.test.ts create mode 100644 mobile/src/terminal/worker-terminal-takeover-report.test.ts create mode 100644 mobile/src/terminal/worker-terminal-takeover-report.ts create mode 100644 src/main/runtime/rpc/methods/orchestration/worker/worker-release-mobile-report.test.ts diff --git a/config/reliability-gates.jsonc b/config/reliability-gates.jsonc index 8c6a4646386..e364dc76b0e 100644 --- a/config/reliability-gates.jsonc +++ b/config/reliability-gates.jsonc @@ -14202,7 +14202,7 @@ "providers": ["local", "daemon", "ssh", "wsl", "remote-runtime"], "coveredPlatforms": ["macos"], "coveredProviders": ["local", "ssh"], - "coverageNotes": "Deterministic service tests cover release-versus-reuse ordering, transactional retain and takeover cancellation, exact host/pane/process identity, dead external/user-owned/transferred/stopped/abandoned reconciliation, host-partition persistence and legacy retirement replay with an absent web-terminal layout map, conservative unknown provider and legacy metadata handling, immutable transcript and bounded terminal archives, mutation restart, reset cleanup, replay idempotency, and 50-resource accounting. A macOS Electron journey invokes the freshly compiled worker-release CLI after the worker process disappears, then independently checks released SQLite state and coordinator liveness. Injected inventories cover local and SSH provider routing; live SSH, WSL, Windows, paired-runtime, and provider-close lost-ack journeys remain explicit gaps.", + "coverageNotes": "New phones explicitly report terminal takeover on real user sends, throttled per owning client and handle. Host byte lanes perform zero orchestration SQL work; local and injected SSH report tests fence release. Phones predating this build do not fence release. Deterministic service tests cover release-versus-reuse ordering, transactional retain and takeover cancellation, exact host/pane/process identity, dead external/user-owned/transferred/stopped/abandoned reconciliation, host-partition persistence and legacy retirement replay with an absent web-terminal layout map, conservative unknown provider and legacy metadata handling, immutable transcript and bounded terminal archives, mutation restart, reset cleanup, replay idempotency, and 50-resource accounting. A macOS Electron journey invokes the freshly compiled worker-release CLI after the worker process disappears, then independently checks released SQLite state and coordinator liveness. Injected inventories cover local and SSH provider routing; live SSH, WSL, Windows, paired-runtime, and provider-close lost-ack journeys remain explicit gaps.", "motivatingLinks": [ "https://github.com/stablyai/orca/pull/12355", "https://github.com/stablyai/orca/issues/13860", @@ -14213,6 +14213,8 @@ "invariant": "A settled Dispatch may close only its one coordinator-created terminal lease. Explicit reuse, real user input, retain, identity or host change, ambiguity, and another resource for the same exact host/pane/process must fence closure. Once the authoritative owning provider positively excludes the resource's exact immutable process incarnation, even an external, user-owned, or transferred dead resource must converge to released without any process close. Unknown host scope, missing incarnation metadata, or unavailable inventory must remain retained. Exact terminal-close persistence must settle when a host partition omits renderer-owned layout state. Output preservation and the requested-to-releasing transition are atomic, archives remain readable without the provider file, retries resume idempotently, and orchestration reset removes archive and authority state.", "oracle": "Record release intent for a settled owner, attempt exact reuse before close, and require worker-start to fail with terminal_release_in_progress while the terminal stays open; then release the original owner exactly once. Race retain and real user input against a controlled archive promise and require no committed archive or close. Rebase a closed web-terminal host partition without terminalLayoutsByTabId and require the persistence write to complete while preserving host-authoritative membership; replay a valid legacy retirement under the same omission and require exact membership removal plus revision advancement. For retained external, user-owned, transferred, stopped, and abandoned resources, run one fresh inventory against the exact local/WSL or SSH provider: an exact live incarnation and every unknown inventory shape stay retained, while positive absence atomically sets ownership_state and release_state to released with processAction none and zero closeTerminal calls. Change host or process identity and inject duplicate resource evidence to require retention. Freeze a structured transcript, delete its source file, and require archived worker-read to return the same bounded redacted messages. Restart a pending mutation, reset orchestration state, and create 50 resources while asserting replay convergence, zero orphan rows, two-query worker listing, and no unrelated close.", "commands": [ + "ORCA_BACKGROUND_LAUNCH=1 pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/rpc/methods/orchestration/worker/worker-release-mobile-report.test.ts src/main/runtime/orca-runtime-terminal-handle-incarnation.test.ts src/renderer/src/lib/worker-terminal-takeover-report.test.ts", + "ORCA_BACKGROUND_LAUNCH=1 mobile/node_modules/.bin/vitest run --config mobile/vitest.config.ts mobile/src/session/mobile-worker-takeover-send-sites.test.ts mobile/src/terminal/worker-terminal-takeover-report.test.ts", "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/pty-inventory-liveness-verdict.test.ts src/main/runtime/orca-runtime-process-incarnation-liveness.test.ts src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts src/main/runtime/rpc/methods/orchestration/worker/worker-release.test.ts src/main/runtime/rpc/methods/orchestration/worker/worker-release-recovery.test.ts src/main/runtime/rpc/orchestration-mutation-ledger.test.ts src/main/runtime/orchestration/worker-transcript-read.test.ts src/renderer/src/lib/worker-terminal-takeover-report.test.ts --reporter=dot", "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/orca-runtime-process-incarnation-liveness.test.ts src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts src/main/runtime/rpc/methods/orchestration/worker/worker-release.test.ts src/main/runtime/rpc/methods/orchestration/worker/worker-release-recovery.test.ts src/main/runtime/rpc/orchestration-mutation-ledger.test.ts src/main/runtime/orchestration/worker-transcript-read.test.ts src/renderer/src/lib/worker-terminal-takeover-report.test.ts --reporter=dot", "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/orca-runtime-process-incarnation-liveness.test.ts src/main/runtime/rpc/methods/orchestration/worker/worker-release.test.ts src/main/runtime/rpc/methods/orchestration/worker/worker-release-recovery.test.ts src/main/runtime/rpc/orchestration-mutation-ledger.test.ts src/main/runtime/orchestration/worker-transcript-read.test.ts src/renderer/src/lib/worker-terminal-takeover-report.test.ts --reporter=dot", @@ -14221,6 +14223,9 @@ "pnpm run build:cli && SKIP_BUILD=1 pnpm exec playwright test tests/e2e/orchestration-worker-settlement-release-cli.spec.ts --config tests/playwright.config.ts --project electron-headless --workers=1" ], "testFiles": [ + "src/main/runtime/rpc/methods/orchestration/worker/worker-release-mobile-report.test.ts", + "mobile/src/session/mobile-worker-takeover-send-sites.test.ts", + "mobile/src/terminal/worker-terminal-takeover-report.test.ts", "src/main/runtime/pty-inventory-liveness-verdict.test.ts", "src/main/runtime/orca-runtime-process-incarnation-liveness.test.ts", "src/main/runtime/mobile-session-terminal-persistence-retirement.test.ts", @@ -14233,6 +14238,20 @@ "tests/e2e/orchestration-worker-settlement-release-cli.spec.ts" ], "assertionRefs": [ + { + "file": "src/main/runtime/rpc/methods/orchestration/worker/worker-release-mobile-report.test.ts", + "assertions": [ + "a handle-addressed phone report fences %s worker release", + "mobile %s bytes do no orchestration database work" + ] + }, + { + "file": "mobile/src/session/mobile-worker-takeover-send-sites.test.ts", + "assertions": [ + "%s reports on its send target once per handle per 30 seconds", + "%s never reports takeover" + ] + }, { "file": "src/main/runtime/pty-inventory-liveness-verdict.test.ts", "assertions": [ diff --git a/mobile/src/session/mobile-native-chat-permission-send.test.ts b/mobile/src/session/mobile-native-chat-permission-send.test.ts index f74289d97ab..1525f090029 100644 --- a/mobile/src/session/mobile-native-chat-permission-send.test.ts +++ b/mobile/src/session/mobile-native-chat-permission-send.test.ts @@ -1,3 +1,8 @@ +// Takeover RPCs have their own send-site integration tests; these fixtures script PTY acknowledgements. +vi.mock('../terminal/worker-terminal-takeover-report', () => ({ + reportWorkerTerminalUserInput: vi.fn() +})) + import { createElement } from 'react' import { act, create, type ReactTestRenderer } from 'react-test-renderer' import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' diff --git a/mobile/src/session/mobile-native-chat-send.test.ts b/mobile/src/session/mobile-native-chat-send.test.ts index a3b3c1e720e..c13841f7f77 100644 --- a/mobile/src/session/mobile-native-chat-send.test.ts +++ b/mobile/src/session/mobile-native-chat-send.test.ts @@ -309,10 +309,13 @@ describe('typeMobileNativeChatCommandWithOutcome', () => { await expect(result).resolves.toBe('accepted') expect( - vi.mocked(client.sendRequest).mock.calls.map((call) => { - const params = call[1] as { text: string; enter: boolean } - return { text: params.text, enter: params.enter } - }) + vi + .mocked(client.sendRequest) + .mock.calls.filter(([method]) => method === 'terminal.send') + .map((call) => { + const params = call[1] as { text: string; enter: boolean } + return { text: params.text, enter: params.enter } + }) ).toEqual( ['\x15', '/', 'm', 'o', 'd', 'e', 'l', '\r'].map((text) => ({ text, @@ -338,7 +341,12 @@ describe('typeMobileNativeChatCommandWithOutcome', () => { await vi.runAllTimersAsync() await result - const params = vi.mocked(client.sendRequest).mock.calls.map((call) => call[1]) as Array<{ + // Why the filter: an accepted send also fires the unawaited takeover report, which is not a + // terminal.send and carries no draft. + const params = vi + .mocked(client.sendRequest) + .mock.calls.filter((call) => call[0] === 'terminal.send') + .map((call) => call[1]) as Array<{ text: string resolvedLaunchDraft?: { text: string; createdAt: number } }> diff --git a/mobile/src/session/mobile-native-chat-send.ts b/mobile/src/session/mobile-native-chat-send.ts index 16f4aac2d3e..22c44f3eb84 100644 --- a/mobile/src/session/mobile-native-chat-send.ts +++ b/mobile/src/session/mobile-native-chat-send.ts @@ -1,3 +1,4 @@ +import { reportWorkerTerminalUserInput } from '../terminal/worker-terminal-takeover-report' import type { RpcClient } from '../transport/rpc-client' import { isRpcDeliveryUnknown } from '../transport/rpc-delivery-ambiguity' import { isLogicalClientCutoverError } from '../transport/stable-logical-rpc-client' @@ -64,7 +65,11 @@ export async function sendMobileNativeChatMessageWithOutcome( // pins the composer for twice as long. { timeoutMs, budgetSpansConnect: true } ) - return isTerminalSendRpcAccepted(response) ? 'accepted' : 'rejected' + if (!isTerminalSendRpcAccepted(response)) { + return 'rejected' + } + reportWorkerTerminalUserInput(args.client, args.terminal) + return 'accepted' } catch (error) { // Why: a logical relay↔direct cutover rejects the in-flight send without // knowing whether its frame reached the wire (the desktop may have delivered diff --git a/mobile/src/session/mobile-session-route-parity.test.ts b/mobile/src/session/mobile-session-route-parity.test.ts index bc951bfa206..3a6b04661de 100644 --- a/mobile/src/session/mobile-session-route-parity.test.ts +++ b/mobile/src/session/mobile-session-route-parity.test.ts @@ -66,11 +66,11 @@ const HEAD_MAIN_HOOK_SHA256 = '10071240ef9edafc2b9c8bed73be83dceaf7828e3b29f17da const HEAD_HOOK_BINDING_SHA256 = '1dadb8c3dc0573ea20659ce7251629669e618dd0effaeac3a4536b29c2e865a1' const HEAD_CALLBACK_IDENTITY_SHA256 = '2a9e4825df007f6ef53b81aa5004991d6318eee7507b44d625c07e630be432eb' -const HEAD_CALLBACK_BODY_SHA256 = '22103ba85a86e3a3fcb80a7509c7a455d79863010cde3af02db6565b55e3ebe9' +const HEAD_CALLBACK_BODY_SHA256 = 'af7f3c62954250d4be7ee432ecd10dc2689792aad8230fed2d1d68bbc892d776' const HEAD_EFFECT_SHA256 = 'd9ebfaabc1e79773cdada7ab370b20459ed972f1f8edce1652199f4d0391cd13' const HEAD_CONTENT_HOOK_SHA256 = '9c3b612fef3f370d66873aefdbe1d701f20cb64ded31fef5cc45fde6f8189581' const HEAD_NESTED_FUNCTION_SHA256 = - '536c72b233c813bb0cea164b090bdce5406ceb965bbc5b83c1f89b89b46f3821' + 'fde6679349ab2b8c30c7e627841ff99bd1dd24441ee95323d0aa70230422ae24' const HEAD_NATIVE_REGISTRATION_SHA256 = 'cab85e4e4a3f43289ba93ddea9ccce57aea83e0bf14fd1620a965aad0c1cb49e' const HEAD_NATIVE_REMOVAL_SHA256 = diff --git a/mobile/src/session/mobile-worker-takeover-send-sites.test.ts b/mobile/src/session/mobile-worker-takeover-send-sites.test.ts new file mode 100644 index 00000000000..2700d8d24fe --- /dev/null +++ b/mobile/src/session/mobile-worker-takeover-send-sites.test.ts @@ -0,0 +1,267 @@ +import { createElement } from 'react' +import { act, create, type ReactTestRenderer } from 'react-test-renderer' +import { beforeEach, afterEach, expect, it, vi } from 'vitest' +import type { RpcClient } from '../transport/rpc-client' +import { resetWorkerTerminalTakeoverReportsForTest } from '../terminal/worker-terminal-takeover-report' +import { useMobileSessionTerminalSendActions } from './use-mobile-session-terminal-send-actions' +import { useMobileSessionTerminalInput } from './use-mobile-session-terminal-input' +import { useMobileTerminalPaste } from './use-mobile-terminal-paste' +import { useTerminalLiveInputCommit } from '../terminal/use-terminal-live-input-commit' +import { routeDictationTranscript } from '../terminal/terminal-live-dictation-routing' +import { + sendMobileNativeChatMessageWithOutcome, + clearMobileNativeChatInput +} from './mobile-native-chat-send' +import { sendMobileTerminalQueryReply } from '../terminal/mobile-terminal-query-reply' +import { createTerminalAndSendPrompt } from './pr-ai-triage-launch' +import { useMobileDiffReviewSendActions } from './use-mobile-diff-review-send-actions' +import { pasteMobileNativeChatImagePaths } from './mobile-native-chat-image-send' + +vi.mock('react-native', () => ({ Keyboard: { dismiss: vi.fn() } })) +vi.mock('../platform/haptics', () => ({ triggerError: vi.fn(), triggerSuccess: vi.fn() })) +vi.mock('expo-clipboard', () => ({ getStringAsync: async () => 'pasted text' })) +vi.mock('expo-file-system', () => ({ File: class {}, Paths: { cache: '/tmp' } })) +vi.mock('expo-image-manipulator', () => ({ ImageManipulator: {}, SaveFormat: {} })) + +const REPORT = 'orchestration.workerTerminalUserInput' +const ref = (current: T) => ({ current }) +const renderers: ReactTestRenderer[] = [] +function clientFixture() { + return { + sendRequest: vi.fn(async (method: string) => ({ + id: 'rpc', + ok: true as const, + result: + method === 'session.tabs.createTerminal' + ? { tab: { type: 'terminal', id: 'tab', terminal: 'term-1', title: 'test' } } + : method === REPORT + ? { changed: 1 } + : { send: { accepted: true } } + })) + } +} + +function mountSendSites(client: ReturnType, handle = 'term-1') { + const activeHandleRef = ref(handle) + const activeSessionTabTypeRef = ref('terminal') + const sendLiveTerminalInputRef = ref(async (_handle: string, _text: string) => false) + const scope = { + client, + clientRef: ref(client), + activeHandle: handle, + activeHandleRef, + activeSessionTabTypeRef, + connState: 'connected', + connStateRef: ref('connected'), + activeSessionTab: { type: 'terminal', terminal: handle }, + sendingRef: ref(false), + canSend: true, + deviceTokenRef: ref('phone'), + liveInputRef: ref(null), + commandInputRef: ref(null), + liveInputFocusTimerRef: ref(null), + sendLiveTerminalInputRef, + getSendCompletionGeneration: () => 0, + showToast: vi.fn(), + ptyModesRef: ref(new Map([[handle, { altScreen: true }]])), + terminalGestureInputBucketsRef: ref(new Map()), + terminalGestureInputQueuesRef: ref(new Map()), + terminalGestureInputInFlightRef: ref(new Set()), + bufferedTerminalDraftState: { + input: 'command', + beginBufferedTerminalDraftSend: vi.fn(), + restoreRejectedDraft: vi.fn(), + settleBufferedTerminalDraftSend: () => true + } + } + let actions!: ReturnType + let live!: ReturnType + let gestures!: ReturnType + let paste!: ReturnType + let diff!: ReturnType + function Harness() { + live = useTerminalLiveInputCommit({ + activeHandle: handle, + activeHandleRef, + activeSessionTabType: 'terminal', + activeSessionTabTypeRef, + connected: true, + liveInputRef: ref(null), + liveInputTerminalHandles: new Set([handle]), + liveInputTerminalHandlesRef: ref(new Set([handle])), + sendLiveTerminalInputRef, + setLiveInputCapture: vi.fn() + }) + actions = useMobileSessionTerminalSendActions({ + ...scope, + handleLiveInputAccessoryBytes: live.handleLiveInputAccessoryBytes + } as never) + gestures = useMobileSessionTerminalInput(scope as never) + paste = useMobileTerminalPaste({ + ...scope, + flushPendingLiveInputBeforeExternalSend: live.flushPendingLiveInputBeforeExternalSend, + getActiveWorktreeConnectionId: async () => null, + onError: vi.fn(), + onSuccess: vi.fn(), + refreshCanPaste: vi.fn() + } as never) + diff = useMobileDiffReviewSendActions({ + client: client as unknown as RpcClient, + connState: 'connected', + worktreeId: 'workspace', + screenState: { kind: 'loading' }, + setActionError: vi.fn(), + setSendSheet: vi.fn(), + saveCommentsAndReviewState: vi.fn() + } as never) + return null + } + act(() => { + renderers.push(create(createElement(Harness))) + }) + let text = '' + return { + 'live field': async () => { + text += 'x' + live.handleLiveInputChange({ nativeEvent: { text, isComposing: false } }) + await live.flushPendingLiveInputBeforeExternalSend(handle) + }, + 'live submit': () => live.handleLiveInputSubmit(), + 'live accessory': async () => { + live.handleLiveInputChange({ nativeEvent: { text: 'composing', isComposing: true } }) + await live.handleLiveInputAccessoryBytes({ bytes: '\x1b[A' }) + }, + 'raw accessory': () => actions.handleAccessoryKey({ bytes: '\x1b[A' } as never), + 'buffered submit': () => actions.handleSend(), + 'gesture arrows': async () => { + await gestures.handleTerminalInput(handle, '\x1b[A') + await gestures.flushTerminalGestureInput(handle) + }, + paste: () => paste(), + dictation: async () => { + const route = routeDictationTranscript('dictated text', true) + expect(route.kind).toBe('live-insert') + await actions.sendLiveTerminalInput(handle, route.text) + }, + 'native chat': () => + sendMobileNativeChatMessageWithOutcome({ + client: client as unknown as RpcClient, + terminal: handle, + text: 'hello' + }), + 'query reply': () => + sendMobileTerminalQueryReply({ + bytes: '\x1b[0n', + client, + clientId: 'phone', + connected: true, + handle, + hostSupportsQueryReplyInput: true, + subscribedTerminals: new Set([handle]) + }), + 'image heal': () => + clearMobileNativeChatInput({ + client: client as unknown as RpcClient, + terminal: handle, + clearInput: '\x15' + }), + 'image attachment': () => + pasteMobileNativeChatImagePaths({ + client, + terminal: handle, + deviceToken: 'phone', + imagePaths: ['/tmp/picture.png'], + followedByText: true + }), + 'PR triage': () => createTerminalAndSendPrompt(client, 'workspace', 'fix checks'), + 'diff review': () => diff.sendPromptToTerminal(handle, []), + programmatic: () => client.sendRequest('terminal.send') + } +} + +beforeEach(() => { + vi.useFakeTimers() + vi.setSystemTime(1_000) + resetWorkerTerminalTakeoverReportsForTest() +}) +afterEach(() => { + act(() => { + for (const renderer of renderers.splice(0)) { + renderer.unmount() + } + }) + vi.useRealTimers() +}) + +const realSites = [ + 'live field', + 'live submit', + 'live accessory', + 'raw accessory', + 'buffered submit', + 'gesture arrows', + 'paste', + 'dictation', + 'native chat' +] as const +it.each(realSites)('%s reports on its send target once per handle per 30 seconds', async (site) => { + const client = clientFixture() + const sites = mountSendSites(client) + const invoke = async () => { + await act(async () => { + await sites[site]() + }) + } + const reports = () => client.sendRequest.mock.calls.filter(([method]) => method === REPORT) + await invoke() + await invoke() + expect( + client.sendRequest.mock.calls.filter(([method]) => method === 'terminal.send').length + ).toBeGreaterThanOrEqual(2) + expect(reports()).toHaveLength(1) + expect(reports()[0]).toEqual([REPORT, { terminal: 'term-1' }, expect.any(Object)]) + await vi.advanceTimersByTimeAsync(29_999) + await invoke() + expect(reports()).toHaveLength(1) + await vi.advanceTimersByTimeAsync(1) + await invoke() + expect(reports()).toHaveLength(2) + const other = mountSendSites(client, 'term-2') + await act(async () => { + await other[site]() + }) + expect(reports()).toHaveLength(3) + expect(reports()[2][1]).toEqual({ terminal: 'term-2' }) +}) + +it.each([ + 'query reply', + 'image heal', + 'image attachment', + 'PR triage', + 'diff review', + 'programmatic' +] as const)('%s never reports takeover', async (site) => { + const client = clientFixture() + const sites = mountSendSites(client) + await act(async () => { + await sites[site]() + await sites[site]() + }) + expect(client.sendRequest.mock.calls.some(([method]) => method === 'terminal.send')).toBe(true) + expect(client.sendRequest.mock.calls.filter(([method]) => method === REPORT)).toHaveLength(0) +}) + +it.each(realSites)('%s does not report a rejected send', async (site) => { + const client = clientFixture() + client.sendRequest.mockResolvedValue({ + id: 'rpc', + ok: true, + result: { send: { accepted: false } } + }) + const sites = mountSendSites(client) + await act(async () => { + await sites[site]() + }) + expect(client.sendRequest.mock.calls.filter(([method]) => method === REPORT)).toHaveLength(0) +}) diff --git a/mobile/src/session/use-mobile-native-chat-answer-send.test.ts b/mobile/src/session/use-mobile-native-chat-answer-send.test.ts index 82db799deed..cfb35417e9f 100644 --- a/mobile/src/session/use-mobile-native-chat-answer-send.test.ts +++ b/mobile/src/session/use-mobile-native-chat-answer-send.test.ts @@ -1,3 +1,8 @@ +// Takeover RPCs have their own send-site integration tests; these fixtures script PTY acknowledgements. +vi.mock('../terminal/worker-terminal-takeover-report', () => ({ + reportWorkerTerminalUserInput: vi.fn() +})) + import { createElement } from 'react' import { act, create, type ReactTestRenderer } from 'react-test-renderer' import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' diff --git a/mobile/src/session/use-mobile-native-chat-stop.test.ts b/mobile/src/session/use-mobile-native-chat-stop.test.ts index bdc405cb57d..a1ee9ab4dd9 100644 --- a/mobile/src/session/use-mobile-native-chat-stop.test.ts +++ b/mobile/src/session/use-mobile-native-chat-stop.test.ts @@ -6,6 +6,12 @@ import { markRpcDeliveryUnknown } from '../transport/rpc-delivery-ambiguity' import { MOBILE_NATIVE_CHAT_SEND_TIMEOUT_MS } from './mobile-native-chat-send' import { useMobileNativeChatStop } from './use-mobile-native-chat-stop' +// Why mocked: the reporter is tested on its own; here Stop's escapes must be counted alone. +const reportWorkerTerminalUserInput = vi.fn() +vi.mock('../terminal/worker-terminal-takeover-report', () => ({ + reportWorkerTerminalUserInput: (...args: unknown[]) => reportWorkerTerminalUserInput(...args) +})) + describe('useMobileNativeChatStop', () => { let renderer: ReactTestRenderer | null = null let stop: (() => void) | null = null @@ -19,6 +25,7 @@ describe('useMobileNativeChatStop', () => { result: { send: { accepted: true } } }) onSendError.mockReset() + reportWorkerTerminalUserInput.mockReset() }) afterEach(() => { @@ -184,4 +191,26 @@ describe('useMobileNativeChatStop', () => { expect(onSendError).not.toHaveBeenCalled() }) + + it('reports the takeover once an Escape is accepted', async () => { + await render(true, 'stream-1') + + act(() => stop?.()) + await act(async () => vi.runAllTimersAsync()) + + expect(reportWorkerTerminalUserInput).toHaveBeenCalledWith( + expect.objectContaining({ sendRequest }), + 'terminal-1' + ) + }) + + it('does not report a Stop the host rejected', async () => { + sendRequest.mockResolvedValue({ ok: true, result: { send: { accepted: false } } }) + await render(true, 'stream-1') + + act(() => stop?.()) + await act(async () => vi.runAllTimersAsync()) + + expect(reportWorkerTerminalUserInput).not.toHaveBeenCalled() + }) }) diff --git a/mobile/src/session/use-mobile-native-chat-stop.ts b/mobile/src/session/use-mobile-native-chat-stop.ts index 871d221abb2..69d2d8e73e8 100644 --- a/mobile/src/session/use-mobile-native-chat-stop.ts +++ b/mobile/src/session/use-mobile-native-chat-stop.ts @@ -3,6 +3,7 @@ import type { RpcClient } from '../transport/rpc-client' import { isRpcDeliveryUnknown } from '../transport/rpc-delivery-ambiguity' import { isLogicalClientCutoverError } from '../transport/stable-logical-rpc-client' import { isTerminalSendRpcAccepted } from '../terminal/terminal-send-rpc-response' +import { reportWorkerTerminalUserInput } from '../terminal/worker-terminal-takeover-report' import { openMobileNativeChatSendBudget } from './mobile-native-chat-send' export function useMobileNativeChatStop(args: { @@ -111,6 +112,8 @@ export function useMobileNativeChatStop(args: { .then((response) => { if (isTerminalSendRpcAccepted(response)) { sawAccepted = true + // A deliberate Stop is human input; it takes the worker over like any other key. + reportWorkerTerminalUserInput(client, handle) } else { sawRejected = true } diff --git a/mobile/src/session/use-mobile-session-terminal-input.ts b/mobile/src/session/use-mobile-session-terminal-input.ts index 02906099e79..3f6e417e23a 100644 --- a/mobile/src/session/use-mobile-session-terminal-input.ts +++ b/mobile/src/session/use-mobile-session-terminal-input.ts @@ -1,4 +1,6 @@ +import { reportWorkerTerminalUserInput } from '../terminal/worker-terminal-takeover-report' import { useCallback } from 'react' +import { isTerminalSendRpcAccepted } from '../terminal/terminal-send-rpc-response' import { clearTerminalLiveInputFocusTimer, scheduleTerminalLiveInputFocus @@ -110,7 +112,7 @@ export function useMobileSessionTerminalInput(scope: MobileSessionFileActionsMod terminalGestureInputInFlightRef.current.add(handle) try { // Why: gesture arrows parked across a reconnect would move a TUI long after the swipe. - await rpc.sendRequest( + const response = await rpc.sendRequest( 'terminal.send', buildTerminalSendParams({ terminal: handle, @@ -120,6 +122,9 @@ export function useMobileSessionTerminalInput(scope: MobileSessionFileActionsMod }), TERMINAL_INPUT_SEND_OPTIONS ) + if (isTerminalSendRpcAccepted(response)) { + reportWorkerTerminalUserInput(rpc, handle) + } } catch { // Transient failure } finally { diff --git a/mobile/src/session/use-mobile-session-terminal-send-actions.ts b/mobile/src/session/use-mobile-session-terminal-send-actions.ts index 6909f71ca63..aa365d5ba39 100644 --- a/mobile/src/session/use-mobile-session-terminal-send-actions.ts +++ b/mobile/src/session/use-mobile-session-terminal-send-actions.ts @@ -1,3 +1,4 @@ +import { reportWorkerTerminalUserInput } from '../terminal/worker-terminal-takeover-report' import { useCallback } from 'react' import { Keyboard } from 'react-native' import { triggerError } from '../platform/haptics' @@ -98,6 +99,9 @@ export function useMobileSessionTerminalSendActions(scope: MobileSessionTerminal TERMINAL_INPUT_SEND_OPTIONS ) const accepted = isTerminalSendRpcAccepted(response) + if (accepted) { + reportWorkerTerminalUserInput(client, activeHandle) + } if (!accepted) { restoreRejectedDraft() } @@ -166,7 +170,16 @@ export function useMobileSessionTerminalSendActions(scope: MobileSessionTerminal }), TERMINAL_INPUT_SEND_OPTIONS ) - .then(isTerminalSendRpcAccepted, () => false) + .then( + (response) => { + const accepted = isTerminalSendRpcAccepted(response) + if (accepted) { + reportWorkerTerminalUserInput(rpc, handle) + } + return accepted + }, + () => false + ) }, [showToast] ) diff --git a/mobile/src/session/use-mobile-terminal-paste.ts b/mobile/src/session/use-mobile-terminal-paste.ts index 57ea720c4c8..3680fa2e505 100644 --- a/mobile/src/session/use-mobile-terminal-paste.ts +++ b/mobile/src/session/use-mobile-terminal-paste.ts @@ -1,4 +1,6 @@ +import { reportWorkerTerminalUserInput } from '../terminal/worker-terminal-takeover-report' import { useCallback, type RefObject } from 'react' +import { isTerminalSendRpcAccepted } from '../terminal/terminal-send-rpc-response' import * as Clipboard from 'expo-clipboard' import { File as FsFile, Paths } from 'expo-file-system' import { ImageManipulator, SaveFormat } from 'expo-image-manipulator' @@ -155,7 +157,7 @@ export function useMobileTerminalPaste({ ) { return } - await currentClient.sendRequest('terminal.send', { + const response = await currentClient.sendRequest('terminal.send', { terminal: targetHandle, text: payload, enter: false, @@ -163,6 +165,9 @@ export function useMobileTerminalPaste({ ? { client: { id: deviceTokenRef.current, type: 'mobile' as const } } : {}) }) + if (isTerminalSendRpcAccepted(response)) { + reportWorkerTerminalUserInput(currentClient, targetHandle) + } onSuccess() refreshCanPaste() } catch (e) { diff --git a/mobile/src/terminal/terminal-live-accessory-raw-send.ts b/mobile/src/terminal/terminal-live-accessory-raw-send.ts index 3824d750792..6fa00ce7bac 100644 --- a/mobile/src/terminal/terminal-live-accessory-raw-send.ts +++ b/mobile/src/terminal/terminal-live-accessory-raw-send.ts @@ -1,3 +1,4 @@ +import { reportWorkerTerminalUserInput } from './worker-terminal-takeover-report' import { getTerminalLiveAccessoryRawSendTarget } from './terminal-live-accessory-raw-send-target' import { isTerminalSendRpcAccepted } from './terminal-send-rpc-response' import { buildTerminalSendParams, TERMINAL_INPUT_SEND_OPTIONS } from './terminal-send-request' @@ -37,5 +38,14 @@ export async function sendTerminalLiveAccessoryRawBytes( }), TERMINAL_INPUT_SEND_OPTIONS ) - .then(isTerminalSendRpcAccepted, () => false) + .then( + (response) => { + const accepted = isTerminalSendRpcAccepted(response) + if (accepted) { + reportWorkerTerminalUserInput(args.client!, rawSendTarget) + } + return accepted + }, + () => false + ) } diff --git a/mobile/src/terminal/worker-terminal-takeover-report.test.ts b/mobile/src/terminal/worker-terminal-takeover-report.test.ts new file mode 100644 index 00000000000..5ef62be1f0b --- /dev/null +++ b/mobile/src/terminal/worker-terminal-takeover-report.test.ts @@ -0,0 +1,82 @@ +import { beforeEach, afterEach, expect, it, vi } from 'vitest' +import { + reportWorkerTerminalUserInput, + resetWorkerTerminalTakeoverReportsForTest +} from './worker-terminal-takeover-report' + +const success = { id: 'report', ok: true as const, result: { changed: 1 } } +beforeEach(() => { + vi.useFakeTimers() + vi.setSystemTime(1_000) + resetWorkerTerminalTakeoverReportsForTest() +}) +afterEach(() => vi.useRealTimers()) + +it('gates per handle and owning client for 30 seconds', () => { + const relay = { sendRequest: vi.fn().mockResolvedValue(success) } + const direct = { sendRequest: vi.fn().mockResolvedValue(success) } + for (let i = 0; i < 100; i++) { + reportWorkerTerminalUserInput(relay, 'term-1') + } + expect(relay.sendRequest).toHaveBeenCalledTimes(1) + reportWorkerTerminalUserInput(relay, 'term-2') + reportWorkerTerminalUserInput(direct, 'term-1') + expect(relay.sendRequest).toHaveBeenCalledTimes(2) + expect(direct.sendRequest).toHaveBeenCalledTimes(1) + vi.advanceTimersByTime(29_999) + reportWorkerTerminalUserInput(relay, 'term-1') + expect(relay.sendRequest).toHaveBeenCalledTimes(2) + vi.advanceTimersByTime(1) + reportWorkerTerminalUserInput(relay, 'term-1') + expect(relay.sendRequest).toHaveBeenCalledTimes(3) + expect(relay.sendRequest).toHaveBeenLastCalledWith( + 'orchestration.workerTerminalUserInput', + { terminal: 'term-1' }, + { timeoutMs: 5_000, budgetSpansConnect: true, failWhenDisconnected: true } + ) +}) + +it('does not await a report and coalesces input while it is pending', () => { + const client = { sendRequest: vi.fn(() => new Promise(() => {})) } + expect(reportWorkerTerminalUserInput(client, 'term-1')).toBeUndefined() + reportWorkerTerminalUserInput(client, 'term-1') + expect(client.sendRequest).toHaveBeenCalledTimes(1) +}) + +it.each(['throw', 'rpc refusal'])( + 'retries a %s once on the same target, then permits a later attempt', + async (failure) => { + const client = { + sendRequest: + failure === 'throw' + ? vi.fn().mockRejectedValue(new Error('offline')) + : vi.fn().mockResolvedValue({ id: 'report', ok: false, error: { message: 'refused' } }) + } + reportWorkerTerminalUserInput(client, 'term-1') + await vi.advanceTimersByTimeAsync(249) + expect(client.sendRequest).toHaveBeenCalledTimes(1) + await vi.advanceTimersByTimeAsync(1) + expect(client.sendRequest).toHaveBeenCalledTimes(2) + await vi.advanceTimersByTimeAsync(1_000) + expect(client.sendRequest).toHaveBeenCalledTimes(2) + client.sendRequest.mockResolvedValue(success) + reportWorkerTerminalUserInput(client, 'term-1') + expect(client.sendRequest).toHaveBeenCalledTimes(3) + } +) + +it('a report that changed nothing still arms the gate, so plain terminals pay once per window', async () => { + // Why: the host answers `changed: 0` for every ordinary terminal; reopening on that turned + // every accepted key into an RPC and a host write transaction (round 6 measurement: 100 for 100). + const client = { + sendRequest: vi.fn().mockResolvedValue({ id: 'report', ok: true, result: { changed: 0 } }) + } + for (let i = 0; i < 100; i++) { + reportWorkerTerminalUserInput(client, 'term-plain') + await vi.advanceTimersByTimeAsync(100) + } + expect(client.sendRequest).toHaveBeenCalledTimes(1) + await vi.advanceTimersByTimeAsync(30_000) + reportWorkerTerminalUserInput(client, 'term-plain') + expect(client.sendRequest).toHaveBeenCalledTimes(2) +}) diff --git a/mobile/src/terminal/worker-terminal-takeover-report.ts b/mobile/src/terminal/worker-terminal-takeover-report.ts new file mode 100644 index 00000000000..a3ed7f6424d --- /dev/null +++ b/mobile/src/terminal/worker-terminal-takeover-report.ts @@ -0,0 +1,59 @@ +import type { RpcClient } from '../transport/rpc-client' + +type ReportClient = Pick +const REPORT_INTERVAL_MS = 30_000 +const REPORT_RETRY_DELAY_MS = 250 +let reportsByClient = new WeakMap>() + +// The same logical client owns relay/direct cutover; never reroute a report via active UI state. +export function reportWorkerTerminalUserInput(client: ReportClient, terminal: string): void { + let reports = reportsByClient.get(client) + if (!reports) { + reports = new Map() + reportsByClient.set(client, reports) + } + const now = Date.now() + const last = reports.get(terminal) + if (last !== undefined && now - last < REPORT_INTERVAL_MS) { + return + } + if (reports.size >= 256) { + for (const [handle, reportedAt] of reports) { + if (now - reportedAt >= REPORT_INTERVAL_MS) { + reports.delete(handle) + } + } + } + // Why the gate ignores the answer: like desktop, one report per terminal per window is the + // whole cost of typing into any terminal, worker or not. A result-aware gate that reopened on + // "changed nothing" turned every key on an ordinary terminal into an RPC plus a host write. + reports.set(terminal, now) + void sendTakeoverReport(client, terminal).catch(() => { + if (reports.get(terminal) === now) { + reports.delete(terminal) + } + }) +} + +async function sendTakeoverReport(client: ReportClient, terminal: string): Promise { + const report = async (): Promise => { + const response = await client.sendRequest( + 'orchestration.workerTerminalUserInput', + { terminal }, + { timeoutMs: 5_000, budgetSpansConnect: true, failWhenDisconnected: true } + ) + if (!response.ok) { + throw new Error('Worker takeover report rejected') + } + } + try { + return await report() + } catch { + await new Promise((resolve) => setTimeout(resolve, REPORT_RETRY_DELAY_MS)) + return await report() + } +} + +export function resetWorkerTerminalTakeoverReportsForTest(): void { + reportsByClient = new WeakMap() +} diff --git a/src/main/runtime/orca-runtime-serialize-headless-terminal-buffer.ts b/src/main/runtime/orca-runtime-serialize-headless-terminal-buffer.ts index 8f4ddc430c5..673c31167f4 100644 --- a/src/main/runtime/orca-runtime-serialize-headless-terminal-buffer.ts +++ b/src/main/runtime/orca-runtime-serialize-headless-terminal-buffer.ts @@ -109,6 +109,9 @@ export class OrcaRuntimeWithSerializeHeadlessTerminalBuffer extends OrcaRuntimeW // still awaiting their first PTY (ptyId null) may adopt it, which preserves // the mobile pre-spawn subscribe flow. resolveLiveLeafForHandle(handle: string): { ptyId: string | null } | null { + // Why the discarded call: it re-links a runtime-owned handle whose `handles` record a renderer + // reload cleared, so the lookup below sees it; without it a phone's held handle inspects nothing. + this.getLivePtyForHandle(handle) const record = this.handles.get(handle) if (!record) { return null diff --git a/src/main/runtime/orca-runtime-terminal-handle-incarnation.test.ts b/src/main/runtime/orca-runtime-terminal-handle-incarnation.test.ts index 19605aa4ffa..9765465fdf0 100644 --- a/src/main/runtime/orca-runtime-terminal-handle-incarnation.test.ts +++ b/src/main/runtime/orca-runtime-terminal-handle-incarnation.test.ts @@ -53,6 +53,28 @@ function register(runtime: OrcaRuntimeService, incarnationId: string): void { } describe('runtime terminal handle incarnation fencing', () => { + it('inspects the retained SSH PTY during renderer reload without an input write', async () => { + const { runtime } = makeRuntime() + const handle = runtime.preAllocateHandleForPty(PTY_ID) + register(runtime, 'incarnation-1') + syncGraph(runtime) + const inspectProcess = vi.fn().mockResolvedValue({ foregroundProcess: 'codex' }) + runtime.setPtyController({ + write: vi.fn(() => true), + kill: () => true, + getForegroundProcess: async () => null, + inspectProcess + }) + expect(runtime.markRendererReloading(1)).not.toBeNull() + expect((runtime as unknown as { handles: Map }).handles.has(handle)).toBe( + false + ) + await expect( + runtime.inspectTerminalProcess(handle, { expectedIncarnationId: 'incarnation-1' }) + ).resolves.toEqual({ foregroundProcess: 'codex' }) + expect(inspectProcess).toHaveBeenCalledWith(PTY_ID, { expectedIncarnationId: 'incarnation-1' }) + }) + it('preserves a direct handle while the PTY incarnation is unchanged', async () => { const { runtime } = makeRuntime() const handle = runtime.preAllocateHandleForPty(PTY_ID) diff --git a/src/main/runtime/rpc/methods/orchestration/worker/worker-release-mobile-report.test.ts b/src/main/runtime/rpc/methods/orchestration/worker/worker-release-mobile-report.test.ts new file mode 100644 index 00000000000..68d40b4a04e --- /dev/null +++ b/src/main/runtime/rpc/methods/orchestration/worker/worker-release-mobile-report.test.ts @@ -0,0 +1,165 @@ +import { afterEach, beforeEach, expect, it, vi } from 'vitest' +import { createOrchestrationWorkerReleaseHarness } from './worker-release.test-support' +import { TERMINAL_SEND_METHODS } from '../../terminal/terminal-send-method' +import { sendTerminalStreamInput } from '../../terminal/terminal-input-delivery' +import { isStreamingMethod, type RpcMethod } from '../../../core' + +const h = createOrchestrationWorkerReleaseHarness() +beforeEach(() => h.setup()) +afterEach(() => h.cleanup()) + +it.each(['local', 'ssh'])( + 'a handle-addressed phone report fences %s worker release', + async (host) => { + if (host === 'ssh') { + vi.mocked(h.runtime.getOrchestrationDispatchAuthority).mockImplementation((handle) => + handle === 'term_worker' + ? ({ + terminalHandle: handle, + paneKey: h.workerPaneKey, + processIncarnation: 'runtime_test:term_worker:1', + hostScope: { kind: 'ssh', targetId: 'ssh-1' } + } as never) + : null + ) + } + const worker = await h.startSettledWorker() + expect(h.db.getWorkerTerminalResourceByOwner(worker.dispatchId)?.host_scope).toContain(host) + h.runtime.registerPreAllocatedHandleForPty('pty-worker', 'term_worker') + h.runtime.registerPty('pty-worker', 'repo::worktree', undefined, { + tabId: 'tab_worker', + leafId: 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb' + }) + vi.mocked(h.runtime.getTerminalPaneKey).mockRestore() + await expect( + h.call('orchestration.workerTerminalUserInput', { terminal: 'term_worker' }) + ).resolves.toEqual({ changed: 1 }) + expect(h.db.getWorkerTerminalResourceByOwner(worker.dispatchId)?.ownership_state).toBe( + 'user_owned' + ) + await expect( + h.call('orchestration.workerTerminalUserInput', { terminal: 'term_worker' }) + ).resolves.toEqual({ changed: 0 }) + await expect( + h.call('orchestration.workerRelease', { dispatch: worker.dispatchId }) + ).resolves.toMatchObject({ state: 'retained', reason: 'user_takeover' }) + expect(h.runtime.closeTerminal).not.toHaveBeenCalled() + } +) + +it('an unknown handle does not fence another worker or access the database', async () => { + const worker = await h.startSettledWorker() + h.runtime.registerPreAllocatedHandleForPty('pty-worker', 'term_worker') + h.runtime.registerPty('pty-worker', 'repo::worktree', undefined, { + tabId: 'tab_worker', + leafId: 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb' + }) + vi.mocked(h.runtime.getTerminalPaneKey).mockRestore() + const db = vi.spyOn(h.runtime, 'getOrchestrationDb') + await expect( + h.call('orchestration.workerTerminalUserInput', { terminal: 'term_missing' }) + ).resolves.toEqual({ changed: 0 }) + expect(db).not.toHaveBeenCalled() + expect(h.db.getWorkerTerminalResourceByOwner(worker.dispatchId)?.ownership_state).toBe('owned') + await expect( + h.call('orchestration.workerRelease', { dispatch: worker.dispatchId }) + ).resolves.toMatchObject({ state: 'released' }) +}) + +it.each(['unary', 'stream'])('mobile %s bytes do no orchestration database work', async (lane) => { + const worker = await h.startSettledWorker() + const runtime = h.runtime + runtime.registerPreAllocatedHandleForPty('pty-worker', 'term_worker') + runtime.registerPty('pty-worker', 'repo::worktree', undefined, { + tabId: 'tab_worker', + leafId: 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb', + incarnationId: 'runtime_test:term_worker:1' + }) + const write = vi.fn(() => true) + runtime.setPtyController({ write, kill: () => true, getForegroundProcess: async () => null }) + const commit = vi.fn(async () => {}) + vi.spyOn(runtime, 'beginMobileInputFloor').mockReturnValue({ commit, rollback: vi.fn() }) + const dbAccess = vi.spyOn(runtime, 'getOrchestrationDb') + const takeover = vi.spyOn(h.db, 'markWorkerTerminalUserOwned') + const prepare = vi.spyOn(h.db.db, 'prepare') + const exec = vi.spyOn(h.db.db, 'exec') + const params = { + terminal: 'term_worker', + text: 'x', + client: { id: 'phone', type: 'mobile' as const } + } + if (lane === 'stream') { + await expect(sendTerminalStreamInput(runtime, { ...params, isMobile: true })).resolves.toBe( + 'delivered' + ) + } else { + const method = TERMINAL_SEND_METHODS.find( + (m): m is RpcMethod => m.name === 'terminal.send' && !isStreamingMethod(m) + )! + await expect( + method.handler(method.params!.parse(params) as never, { runtime } as never) + ).resolves.toMatchObject({ send: { accepted: true } }) + } + expect(write).toHaveBeenCalledWith('pty-worker', 'x') + expect(commit).toHaveBeenCalledTimes(1) + expect(dbAccess).not.toHaveBeenCalled() + expect(takeover).not.toHaveBeenCalled() + expect(prepare).not.toHaveBeenCalled() + expect(exec).not.toHaveBeenCalled() + expect(h.db.getWorkerTerminalResourceByOwner(worker.dispatchId)?.ownership_state).toBe('owned') +}) + +it('the report is reachable from a mobile-scoped device token', async () => { + // Why: mobile tokens are gated by an allowlist before dispatch. The phone reporter swallows a + // refusal, so a missing entry silently reverts every phone to the unfenced behaviour. + const { MOBILE_RPC_METHOD_ALLOWLIST } = + await import('../../../../runtime-rpc/runtime-rpc-mobile-method-allowlist') + expect(MOBILE_RPC_METHOD_ALLOWLIST.has('orchestration.workerTerminalUserInput')).toBe(true) +}) + +// Round-1 regression (#19337 review): a phone key landing inside the worker's boot wait used to +// find no `owned` row, report `changed: 0`, and still arm the client's 30 s gate — so the real +// takeover was suppressed and `worker-release` closed the pane. #19608 writes custody at terminal +// creation, so the boot-wait key itself takes the pane. +it('a phone report during the boot wait takes the pane and fences the later release', async () => { + const gate = h.deferred() + vi.spyOn(h.runtime, 'waitForTerminal').mockReturnValue(gate.promise as never) + const task = h.db.createTask({ spec: 'mid-boot phone takeover', runId: h.activeRunId }) + const start = h.call('orchestration.workerStart', { + task: task.id, + from: 'term_coord', + agent: 'codex' + }) + await vi.waitFor(() => expect(h.runtime.waitForTerminal).toHaveBeenCalled()) + const dispatchId = ( + h.db.db.prepare("SELECT dispatch_id FROM worker_dispatches WHERE state = 'starting'").get() as { + dispatch_id: string + } + ).dispatch_id + + h.runtime.registerPreAllocatedHandleForPty('pty-worker', 'term_worker') + h.runtime.registerPty('pty-worker', 'repo::worktree', undefined, { + tabId: 'tab_worker', + leafId: 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb' + }) + vi.mocked(h.runtime.getTerminalPaneKey).mockRestore() + await expect( + h.call('orchestration.workerTerminalUserInput', { terminal: 'term_worker' }) + ).resolves.toEqual({ changed: 1 }) + + gate.resolve({ + handle: 'term_worker', + condition: 'tui-idle', + satisfied: true, + status: 'running', + exitCode: null + }) + await expect(start).resolves.toMatchObject({ state: 'ready' }) + expect(h.db.getWorkerTerminalResourceByOwner(dispatchId)?.ownership_state).toBe('user_owned') + + h.settle(task.id, dispatchId, 'succeeded') + await expect( + h.call('orchestration.workerRelease', { dispatch: dispatchId }) + ).resolves.toMatchObject({ state: 'retained', reason: 'user_takeover', processAction: 'none' }) + expect(h.runtime.closeTerminal).not.toHaveBeenCalled() +}) diff --git a/src/main/runtime/rpc/methods/orchestration/worker/worker-release.ts b/src/main/runtime/rpc/methods/orchestration/worker/worker-release.ts index 5d219d76591..e121f1b3f25 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/worker-release.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/worker-release.ts @@ -136,14 +136,24 @@ export const ORCHESTRATION_WORKER_RELEASE_METHODS: RpcMethod[] = [ // identity credential that never leaves main, so the caller names the session and the owning // runtime resolves it — a renderer echoing the pane key back would make it learnable. params: z - .object({ paneKey: z.string().min(1).optional(), sessionId: z.string().min(1).optional() }) - .refine((value) => Boolean(value.paneKey ?? value.sessionId), 'Missing paneKey or sessionId'), + .object({ + paneKey: z.string().min(1).optional(), + sessionId: z.string().min(1).optional(), + terminal: z.string().min(1).optional() + }) + .refine( + (value) => Boolean(value.paneKey ?? value.sessionId ?? value.terminal), + 'Missing paneKey, sessionId or terminal' + ), // Real user keystrokes durably relinquish orchestration ownership on the owning runtime, so // restarts, SSH drops, remote viewing, and renderer remounts cannot erase the takeover. handler: (params, { runtime }) => { // A structured worker reports by session id; it has no pane of its own to name. const paneKey = - params.paneKey ?? runtime.getStructuredWorkerPaneKeyForSession(params.sessionId!) + params.paneKey ?? + (params.sessionId + ? runtime.getStructuredWorkerPaneKeyForSession(params.sessionId) + : runtime.getTerminalPaneKey(params.terminal!)) const changed = paneKey ? runtime.getOrchestrationDb().markWorkerTerminalUserOwned(paneKey) : 0 diff --git a/src/main/runtime/runtime-rpc/runtime-rpc-mobile-method-allowlist.ts b/src/main/runtime/runtime-rpc/runtime-rpc-mobile-method-allowlist.ts index d6142e95569..534cf04b883 100644 --- a/src/main/runtime/runtime-rpc/runtime-rpc-mobile-method-allowlist.ts +++ b/src/main/runtime/runtime-rpc/runtime-rpc-mobile-method-allowlist.ts @@ -246,6 +246,8 @@ export const MOBILE_RPC_METHOD_ALLOWLIST = new Set([ 'status.get', 'agentTeams.prepareLaunch', 'agentTeams.tmuxCompat', + // Why: the phone reports a takeover out of band, the same signal the desktop renderer sends. + 'orchestration.workerTerminalUserInput', 'terminal.clearBuffer', 'terminal.close', 'terminal.closeAll', From 4f0e3806a94009c0c3d9fe698b844d3421921c6e Mon Sep 17 00:00:00 2001 From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com> Date: Tue, 8 Sep 2026 12:39:58 -0700 Subject: [PATCH 15/59] fix(native-chat): place effort after model picker (#19617) Co-authored-by: Merge Sim --- .../NativeChatSessionOptionPickers.test.tsx | 18 ++++++-- .../NativeChatSessionOptionPickers.tsx | 46 +++++++++---------- 2 files changed, 37 insertions(+), 27 deletions(-) diff --git a/src/renderer/src/components/native-chat/NativeChatSessionOptionPickers.test.tsx b/src/renderer/src/components/native-chat/NativeChatSessionOptionPickers.test.tsx index 031ce4bcd15..fb9292517e3 100644 --- a/src/renderer/src/components/native-chat/NativeChatSessionOptionPickers.test.tsx +++ b/src/renderer/src/components/native-chat/NativeChatSessionOptionPickers.test.tsx @@ -220,7 +220,12 @@ describe('NativeChatSessionOptionPickers', () => { /> ) await waitFor(() => - expect(screen.getAllByTestId('dropdown-root')[1]?.getAttribute('data-open')).toBe('true') + expect( + screen + .getByRole('button', { name: 'Model Opus 4.8' }) + .closest('[data-testid="dropdown-root"]') + ?.getAttribute('data-open') + ).toBe('true') ) rerender( @@ -232,7 +237,12 @@ describe('NativeChatSessionOptionPickers', () => { /> ) await waitFor(() => - expect(screen.getAllByTestId('dropdown-root')[0]?.getAttribute('data-open')).toBe('true') + expect( + screen + .getByRole('button', { name: 'Effort High' }) + .closest('[data-testid="dropdown-root"]') + ?.getAttribute('data-open') + ).toBe('true') ) }) @@ -270,8 +280,8 @@ describe('NativeChatSessionOptionPickers', () => { ) expect( screen - .getByRole('button', { name: 'Effort High · Fast' }) - .compareDocumentPosition(screen.getByRole('button', { name: 'Model Opus 4.8' })) & + .getByRole('button', { name: 'Model Opus 4.8' }) + .compareDocumentPosition(screen.getByRole('button', { name: 'Effort High · Fast' })) & Node.DOCUMENT_POSITION_FOLLOWING ).not.toBe(0) diff --git a/src/renderer/src/components/native-chat/NativeChatSessionOptionPickers.tsx b/src/renderer/src/components/native-chat/NativeChatSessionOptionPickers.tsx index 31ff2cbdc4e..e960e407b02 100644 --- a/src/renderer/src/components/native-chat/NativeChatSessionOptionPickers.tsx +++ b/src/renderer/src/components/native-chat/NativeChatSessionOptionPickers.tsx @@ -241,6 +241,29 @@ function NativeChatSessionOptionPickersInner({ return (
+ + + + {modelReason && !model.settable ? ( + {modelReason} + ) : null} + setOption(model, value)} + invokeAction={() => invokeAction(model)} + /> + + {options.length > 0 ? ( ) : null} - - - - {modelReason && !model.settable ? ( - {modelReason} - ) : null} - setOption(model, value)} - invokeAction={() => invokeAction(model)} - /> - -
) } From d7d21b2c55cd512b7f5a3011e4fa07ef11d9facb Mon Sep 17 00:00:00 2001 From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com> Date: Tue, 8 Sep 2026 14:00:58 -0700 Subject: [PATCH 16/59] Show picker-selected native chat skills as pills (#19616) * Render picker-selected native chat skills as inline pills * Use cube icon for native chat skill pills * Update skill pill label assertion * Use cube icon for every native chat skill pill * Use neutral cube icon for native chat skill pills * Match native chat skill icon to selector --------- Co-authored-by: Merge Sim --- .../native-chat/NativeChatComposer.tsx | 5 +- .../native-chat/NativeChatComposerField.tsx | 51 ++-- .../NativeChatPromptEditor.test.tsx | 142 +++++++++++ .../native-chat/NativeChatPromptEditor.tsx | 233 ++++++++++++++++++ .../native-chat/NativeChatSkillPill.tsx | 28 +++ .../native-chat-composer-autogrow.test.tsx | 4 +- .../native-chat-composer-composition.test.tsx | 70 +++--- .../native-chat/native-chat-composer-input.ts | 14 ++ .../native-chat/native-chat-draft-cache.ts | 31 ++- .../native-chat-prompt-document.ts | 68 +++++ .../native-chat-prompt-editor.test-support.ts | 17 ++ ...structured-send-composition-clear.test.tsx | 27 +- ...-chat-composer-app-menu-selection.test.tsx | 4 +- ...native-chat-composer-app-menu-selection.ts | 5 +- .../use-native-chat-composer-attachments.ts | 3 +- .../use-native-chat-composer-keydown.ts | 2 +- .../use-native-chat-dictation-actions.ts | 3 +- .../use-native-chat-picker-state.ts | 7 +- .../use-native-chat-typed-insertion.ts | 3 +- 19 files changed, 637 insertions(+), 80 deletions(-) create mode 100644 src/renderer/src/components/native-chat/NativeChatPromptEditor.test.tsx create mode 100644 src/renderer/src/components/native-chat/NativeChatPromptEditor.tsx create mode 100644 src/renderer/src/components/native-chat/NativeChatSkillPill.tsx create mode 100644 src/renderer/src/components/native-chat/native-chat-composer-input.ts create mode 100644 src/renderer/src/components/native-chat/native-chat-prompt-document.ts create mode 100644 src/renderer/src/components/native-chat/native-chat-prompt-editor.test-support.ts diff --git a/src/renderer/src/components/native-chat/NativeChatComposer.tsx b/src/renderer/src/components/native-chat/NativeChatComposer.tsx index 79ca7cbd851..4833f89fc94 100644 --- a/src/renderer/src/components/native-chat/NativeChatComposer.tsx +++ b/src/renderer/src/components/native-chat/NativeChatComposer.tsx @@ -1,3 +1,4 @@ +import type { NativeChatComposerInput } from './native-chat-composer-input' import { forwardRef, useCallback, useImperativeHandle, useState } from 'react' import { useAppStore } from '../../store' import { sendRuntimePtyInput } from '@/runtime/runtime-terminal-inspection' @@ -147,7 +148,7 @@ const NativeChatComposerPane = forwardRef { + const syncCaret = useCallback((el: NativeChatComposerInput) => { setCaret(el.selectionStart ?? el.value.length) }, []) @@ -353,7 +354,7 @@ const NativeChatComposerPane = forwardRef { + (value: string, element: NativeChatComposerInput) => { setDraft(value) setHistory((prev) => ({ entries: prev.entries, index: null })) syncCaret(element) diff --git a/src/renderer/src/components/native-chat/NativeChatComposerField.tsx b/src/renderer/src/components/native-chat/NativeChatComposerField.tsx index 25fff0267be..6b474a2f267 100644 --- a/src/renderer/src/components/native-chat/NativeChatComposerField.tsx +++ b/src/renderer/src/components/native-chat/NativeChatComposerField.tsx @@ -1,3 +1,5 @@ +import { NativeChatPromptEditor } from './NativeChatPromptEditor' +import type { NativeChatComposerInput } from './native-chat-composer-input' import type { ClipboardEventHandler, KeyboardEventHandler, RefObject } from 'react' import { useLayoutEffect, useRef } from 'react' import { ImageOff } from 'lucide-react' @@ -19,7 +21,7 @@ export type NativeChatComposerFieldProps = { /** Pane identity published to the drop pipeline so a native file drop lands * only in the composer it was dropped on. */ composerScopeKey: string - textareaRef: RefObject + textareaRef: RefObject draft: string disabled: boolean hasPty: boolean @@ -35,11 +37,11 @@ export type NativeChatComposerFieldProps = { isDictating: boolean isDictationHoldMode: boolean imeEnterGesture: ReturnType - onDraftChange: (value: string, element: HTMLTextAreaElement) => void - onTextareaSelect: (element: HTMLTextAreaElement) => void - onKeyDown: KeyboardEventHandler - onImeSettled: (element: HTMLTextAreaElement) => void - onPaste: ClipboardEventHandler + onDraftChange: (value: string, element: NativeChatComposerInput) => void + onTextareaSelect: (element: NativeChatComposerInput) => void + onKeyDown: KeyboardEventHandler + onImeSettled: (element: NativeChatComposerInput) => void + onPaste: ClipboardEventHandler pickerListboxId: string onChoosePickerItem: (item: NativeChatPickerItem) => void onRetrySkills: () => void @@ -151,7 +153,7 @@ export function NativeChatComposerField({ textarea.value = draft }, [draft, imeEnterGesture, textareaRef]) - const settleImeValue = (element: HTMLTextAreaElement): void => { + const settleImeValue = (element: NativeChatComposerInput): void => { if (droppedDraftClearRef.current) { droppedDraftClearRef.current = false element.value = imeComposedSegment(compositionBaseRef.current, element.value) @@ -204,38 +206,39 @@ export function NativeChatComposerField({ ))} ) : null} -