From 996333b338dc2b5c24dbdf8d93c595b5cfb0e6e9 Mon Sep 17 00:00:00 2001 From: Jinwoo-H Date: Wed, 28 Oct 2026 04:30:19 -0400 Subject: [PATCH 1/2] feat(orchestration): start a worker in one step; worker-start creates the coordinator's Run when none is bound worker-start --spec now creates and binds a Run for a root coordinator with no bound Run, through the same path run-create uses, and names the Run it created or joined in every receipt. Workers on a Dispatch keep starting helpers in their own Run and never get a new one. A new CLI against an older runtime runs run-create and retries; old CLIs need no change. --- skill-guides/orchestration.md | 12 +- src/cli/bundled-skill-guides.ts | 12 +- .../orchestration/worker-launch-handler.ts | 98 +++++++++++++--- .../handlers/orchestration/worker-output.ts | 6 + .../worker-start-older-runtime-run.test.ts | 83 ++++++++++++++ src/cli/specs/orchestration-worker-specs.ts | 1 + src/cli/specs/orchestration.ts | 2 +- .../rpc/methods/orchestration/runs/runs.ts | 39 ++++--- .../worker/composed-workers.test.ts | 35 ++++++ .../worker/worker-start-authority.ts | 45 +++++--- .../methods/orchestration/worker/workers.ts | 107 +++++++++++------- .../orchestration-runtime-capabilities.ts | 4 + src/shared/protocol-version.ts | 1 + 13 files changed, 348 insertions(+), 97 deletions(-) create mode 100644 src/cli/handlers/orchestration/worker-start-older-runtime-run.test.ts diff --git a/skill-guides/orchestration.md b/skill-guides/orchestration.md index 37f78d0fceb..0f6a17c6d15 100644 --- a/skill-guides/orchestration.md +++ b/skill-guides/orchestration.md @@ -102,12 +102,13 @@ precedence over the idle rule. Do not reuse the settled lifecycle IDs. ## Canonical supervised loop -Confirm the runtime, bind one Run, and start the full independent wave before -waiting. `worker-start --spec` creates the Task and its attempt in one call: +Confirm the runtime and start the full independent wave before waiting. +`worker-start --spec` creates the Task and its attempt in one call; with no Run +bound, it also creates one bound to you. Its receipt's `run` names the Run it +created or joined; if that is an earlier goal's Run, `run-create` first: ```text ORCA status --json -ORCA orchestration run-create --objective "" --json ORCA orchestration worker-start --spec "" --worktree current --agent codex --json ORCA orchestration worker-start --spec "" --worktree current --agent claude --json ORCA orchestration check --wait --types "worker_done,escalation,question" --timeout-ms 900000 --json @@ -123,8 +124,9 @@ If `worker-start` exits non-zero, do not relaunch. Read the receipt's `failedStage` and `residualResources`, then load `references/recovery-and-cleanup.md`. -Use `task-create` plus `worker-start --task ` for planned fan-out with -dependencies or a retry of a known Task. Use dependencies only for real ordering +Use `run-create --objective ""`, then `task-create` plus +`worker-start --task `, for planned fan-out with dependencies or a +retry of a known Task. Use dependencies only for real ordering and prefer parallel waves over chains deeper than three or four steps; nested workers obey the depth limit, and a new Run does not reset the caller's depth. A dispatched worker starts its own helpers with `worker-start --spec` on the Run diff --git a/src/cli/bundled-skill-guides.ts b/src/cli/bundled-skill-guides.ts index 2976556f017..e81dc42ab35 100644 --- a/src/cli/bundled-skill-guides.ts +++ b/src/cli/bundled-skill-guides.ts @@ -2435,12 +2435,13 @@ const ORCHESTRATION_MARKDOWN = [ "", "## Canonical supervised loop", "", - "Confirm the runtime, bind one Run, and start the full independent wave before", - "waiting. `worker-start --spec` creates the Task and its attempt in one call:", + "Confirm the runtime and start the full independent wave before waiting.", + "`worker-start --spec` creates the Task and its attempt in one call; with no Run", + "bound, it also creates one bound to you. Its receipt's `run` names the Run it", + "created or joined; if that is an earlier goal's Run, `run-create` first:", "", "```text", "ORCA status --json", - "ORCA orchestration run-create --objective \"\" --json", "ORCA orchestration worker-start --spec \"\" --worktree current --agent codex --json", "ORCA orchestration worker-start --spec \"\" --worktree current --agent claude --json", "ORCA orchestration check --wait --types \"worker_done,escalation,question\" --timeout-ms 900000 --json", @@ -2456,8 +2457,9 @@ const ORCHESTRATION_MARKDOWN = [ "`failedStage` and `residualResources`, then load", "`references/recovery-and-cleanup.md`.", "", - "Use `task-create` plus `worker-start --task ` for planned fan-out with", - "dependencies or a retry of a known Task. Use dependencies only for real ordering", + "Use `run-create --objective \"\"`, then `task-create` plus", + "`worker-start --task `, for planned fan-out with dependencies or a", + "retry of a known Task. Use dependencies only for real ordering", "and prefer parallel waves over chains deeper than three or four steps; nested", "workers obey the depth limit, and a new Run does not reset the caller's depth.", "A dispatched worker starts its own helpers with `worker-start --spec` on the Run", diff --git a/src/cli/handlers/orchestration/worker-launch-handler.ts b/src/cli/handlers/orchestration/worker-launch-handler.ts index 747d9801e4c..53e8505e9a8 100644 --- a/src/cli/handlers/orchestration/worker-launch-handler.ts +++ b/src/cli/handlers/orchestration/worker-launch-handler.ts @@ -1,9 +1,17 @@ import type { CommandHandler } from '../../dispatch' import { printResult } from '../../format' import { getOptionalStringFlag, getPresentStringFlag } from '../../flags' -import { RuntimeClientError } from '../../runtime-client' +import { + RuntimeClientError, + type RuntimeClient, + type RuntimeRpcSuccess +} from '../../runtime-client' import type { RuntimeStatus } from '../../../shared/runtime-types' -import { ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY } from '../../../shared/protocol-version' +import { + ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY, + ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY +} from '../../../shared/protocol-version' +import { buildOrchestrationTaskDisplayMetadata } from '../../../shared/orchestration-task-display' import { callOrchestrationMutation } from './mutation-request' import { getOptionalPositiveIntegerValueFlag } from './numeric-flags' import { isDevCliInvocation } from './runtime-compatibility' @@ -11,6 +19,75 @@ import { resolveCoordinatorTerminalHandle } from './terminal-identity' import { formatWorkerStart } from './worker-output' import { renderResolvedOrchestrationCommand } from '../../orchestration-mutation-recovery' +type WorkerStartResult = { + runId: string + taskId: string + dispatchId: string + state: string + failedStage?: string + lastError?: string + warning?: string + mode?: { mode: string; preferred: string; reason: string; detail: string } + run?: { id: string; objective: string; created: boolean } + effects: unknown[] + residualResources: unknown[] + nextCommands?: string[] +} + +// Older runtimes refuse an unbound coordinator with exactly this; it also proves the caller works no Dispatch there. +const OLDER_RUNTIME_UNBOUND_COORDINATOR = + 'worker-start needs the coordinator bound to the Run, or a worker on an active Dispatch in it.' + +/** Start a worker; against a runtime that cannot create the Run itself, run-create first as it would. */ +async function startWorker( + client: RuntimeClient, + flags: Map, + params: { spec?: string; taskTitle?: string; run?: string; from?: string } +): Promise> { + try { + return await callOrchestrationMutation( + client, + flags, + 'orchestration.workerStart', + params + ) + } catch (error) { + const { spec } = params + if ( + !spec || + params.run || + !(error instanceof RuntimeClientError) || + error.code !== 'consumer_fenced' || + error.message !== OLDER_RUNTIME_UNBOUND_COORDINATOR || + (await client.call('status.get')).result.capabilities?.includes( + ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY + ) + ) { + throw error + } + const { taskTitle: objective } = buildOrchestrationTaskDisplayMetadata({ + spec, + taskTitle: params.taskTitle + }) + const created = await callOrchestrationMutation<{ run: { id: string; objective: string } }>( + client, + new Map(), + 'orchestration.runCreate', + { objective, from: params.from } + ) + const started = await callOrchestrationMutation( + client, + flags, + 'orchestration.workerStart', + params + ) + return { + ...started, + result: { ...started.result, run: { ...created.result.run, created: true } } + } + } +} + export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record = { 'orchestration worker-start': async ({ flags, client, cwd, json }) => { const terminal = getPresentStringFlag(flags, 'terminal') @@ -34,19 +111,7 @@ export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record const taskTitle = getOptionalStringFlag(flags, 'task-title') const deps = getOptionalStringFlag(flags, 'deps') const parent = getOptionalStringFlag(flags, 'parent') - const result = await callOrchestrationMutation<{ - runId: string - taskId: string - dispatchId: string - state: string - failedStage?: string - lastError?: string - warning?: string - mode?: { mode: string; preferred: string; reason: string; detail: string } - effects: unknown[] - residualResources: unknown[] - nextCommands?: string[] - }>(client, flags, 'orchestration.workerStart', { + const params = { task, ...(spec ? { spec } : {}), ...(taskTitle ? { taskTitle } : {}), @@ -69,7 +134,8 @@ export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record run: getOptionalStringFlag(flags, 'run'), from: await resolveCoordinatorTerminalHandle(flags, cwd, client), devMode: isDevCliInvocation() - }) + } + const result = await startWorker(client, flags, params) if (result.result.state !== 'ready') { process.exitCode = 1 } diff --git a/src/cli/handlers/orchestration/worker-output.ts b/src/cli/handlers/orchestration/worker-output.ts index 7de970fabe6..55a95c624c3 100644 --- a/src/cli/handlers/orchestration/worker-output.ts +++ b/src/cli/handlers/orchestration/worker-output.ts @@ -9,6 +9,7 @@ export type LegacyWorkerReadResult = { export type WorkerStartReceipt = { mode?: { detail: string } + run?: { id: string; objective: string; created: boolean } taskId: string dispatchId: string state: string @@ -22,6 +23,11 @@ export type WorkerStartReceipt = { export function formatWorkerStart(value: WorkerStartReceipt): string { const lines = [`Worker ${value.dispatchId} [${value.state}] for ${value.taskId}`] + if (value.run) { + lines.push( + `${value.run.created ? 'Created and bound Run' : 'In Run'} ${value.run.id}: ${value.run.objective}` + ) + } // Show the mode that actually ran so a fallback from the user's default is visible. if (value.mode) { lines.push(value.mode.detail) diff --git a/src/cli/handlers/orchestration/worker-start-older-runtime-run.test.ts b/src/cli/handlers/orchestration/worker-start-older-runtime-run.test.ts new file mode 100644 index 00000000000..48c083a2a19 --- /dev/null +++ b/src/cli/handlers/orchestration/worker-start-older-runtime-run.test.ts @@ -0,0 +1,83 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { ORCHESTRATION_HANDLERS } from '../orchestration' +import { RuntimeClient, RuntimeClientError } from '../../runtime-client' +import { okFixture } from '../../test-fixtures' +import { ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY } from '../../../shared/protocol-version' + +const client = new RuntimeClient('/tmp/orca-older-runtime-run', 60_000, null, null) +const UNBOUND = new RuntimeClientError( + 'consumer_fenced', + 'worker-start needs the coordinator bound to the Run, or a worker on an active Dispatch in it.' +) + +describe('worker-start against a runtime that cannot create the Run itself', () => { + const methods: string[] = [] + let runCreateParams: unknown + + function stubRuntime(capabilities: string[]): void { + let starts = 0 + vi.spyOn(client, 'call').mockImplementation(async (method: string, params?: unknown) => { + methods.push(method) + if (method === 'status.get') { + return okFixture('req_status', { capabilities }) + } + if (method === 'orchestration.runCreate') { + runCreateParams = params + return okFixture('req_run', { run: { id: 'run_1', objective: 'Audit the parser' } }) + } + if (method === 'orchestration.workerStart') { + starts += 1 + if (starts === 1) { + throw UNBOUND + } + return okFixture('req_start', { state: 'ready', effects: [], residualResources: [] }) + } + throw new Error(`Unexpected RPC: ${method}`) + }) + } + + async function start(): Promise { + await ORCHESTRATION_HANDLERS['orchestration worker-start']({ + flags: new Map([ + ['spec', 'Audit the parser\nCheck every branch.'], + ['terminal', 'term_worker'], + ['from', 'term_coord'] + ]), + client, + cwd: '/tmp/coord', + json: true + }) + } + + beforeEach(() => { + methods.length = 0 + runCreateParams = undefined + vi.spyOn(console, 'log').mockImplementation(() => {}) + }) + + afterEach(() => { + vi.restoreAllMocks() + process.exitCode = undefined + }) + + it('creates the Run as run-create would, then starts the worker once more', async () => { + stubRuntime([]) + + await start() + + expect(methods).toEqual([ + 'orchestration.workerStart', + 'status.get', + 'orchestration.runCreate', + 'orchestration.workerStart' + ]) + expect(runCreateParams).toEqual({ objective: 'Audit the parser', from: 'term_coord' }) + }) + + it('leaves the refusal alone when the runtime would have created the Run', async () => { + stubRuntime([ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY]) + + await expect(start()).rejects.toBe(UNBOUND) + expect(methods).not.toContain('orchestration.runCreate') + }) +}) diff --git a/src/cli/specs/orchestration-worker-specs.ts b/src/cli/specs/orchestration-worker-specs.ts index 9123009f9de..16d2a3251b3 100644 --- a/src/cli/specs/orchestration-worker-specs.ts +++ b/src/cli/specs/orchestration-worker-specs.ts @@ -33,6 +33,7 @@ export const ORCHESTRATION_WORKER_COMMAND_SPECS: CommandSpec[] = [ ], identityFlagRoles: { from: 'caller', terminal: 'target' }, notes: [ + 'With --spec and no bound Run, a coordinator gets a new Run bound to it, named after the Task title; the receipt names the Run it created or joined.', 'Current and existing worktrees never rerun setup; a fresh agent terminal is created unless --terminal is explicit.', 'When reusing --terminal, pass --worktree for that terminal; current means the coordinator worktree.', '--agent takes an Orca agent id enabled on the worker server, such as claude, codex, cursor, antigravity, muse, zcode, opencode, or opencode2.', diff --git a/src/cli/specs/orchestration.ts b/src/cli/specs/orchestration.ts index 20008e45749..921b27e43b1 100644 --- a/src/cli/specs/orchestration.ts +++ b/src/cli/specs/orchestration.ts @@ -10,7 +10,7 @@ export const ORCHESTRATION_COMMAND_SPECS: CommandSpec[] = [ allowedFlags: [...GLOBAL_FLAGS, 'objective', 'from', 'retry-request'], identityFlagRoles: { from: 'caller' }, notes: [ - 'A Run is a namespace and home inbox. It never schedules or places workers.', + 'A Run is a namespace and home inbox. It never schedules or places workers. worker-start --spec creates one when none is bound; use run-create for Task graphs or a new goal.', '--retry-request is only for exact recovery after an unknown mutation result.' ] }, diff --git a/src/main/runtime/rpc/methods/orchestration/runs/runs.ts b/src/main/runtime/rpc/methods/orchestration/runs/runs.ts index 1add74b2e44..2d1b8132d6b 100644 --- a/src/main/runtime/rpc/methods/orchestration/runs/runs.ts +++ b/src/main/runtime/rpc/methods/orchestration/runs/runs.ts @@ -5,6 +5,7 @@ import { assertCallerHandleMatchesEvidence, resolveOrchestrationCaller } from '. import { exposeRun } from './run-receipt' import type { OrcaRuntimeService } from '../../../../orca-runtime' import type { OrchestrationCallerIdentity } from '../../../../orchestration/orchestration-caller-identity' +import type { RunRow } from '../../../../orchestration/types' import { currentDispatchAssigneeRun } from '../messaging/recipient-routing' import { RunCreateParams, @@ -26,6 +27,29 @@ function cancelBoundDispatchWaiters( } } +/** Create a Run and bind it to the caller, as `run-create` does; one-step `worker-start` reuses it. */ +export function createBoundRun( + runtime: OrcaRuntimeService, + caller: OrchestrationCallerIdentity, + from: string, + objective: string +): RunRow { + const db = runtime.getOrchestrationDb() + const priorRun = db.getCurrentRunForCoordinator(caller) + const run = db.createRun({ + objective, + coordinatorHandle: caller.terminalHandle, + coordinatorPaneKey: caller.paneKey, + coordinatorOrcaSessionId: caller.orcaSessionId + }) + runtime.cancelMessageWaiters(from) + cancelBoundDispatchWaiters(runtime, caller, run.id) + if (priorRun) { + runtime.cancelMessageWaiters(`run:${priorRun.id}`) + } + return run +} + export const ORCHESTRATION_RUN_METHODS = [ defineMethod({ name: 'orchestration.runCreate', @@ -38,20 +62,7 @@ export const ORCHESTRATION_RUN_METHODS = [ callerSession: orchestrationCaller, requireStablePane: true }) - const db = runtime.getOrchestrationDb() - const priorRun = db.getCurrentRunForCoordinator(caller) - const run = db.createRun({ - objective: params.objective, - coordinatorHandle: caller.terminalHandle, - coordinatorPaneKey: caller.paneKey, - coordinatorOrcaSessionId: caller.orcaSessionId - }) - runtime.cancelMessageWaiters(params.from) - cancelBoundDispatchWaiters(runtime, caller, run.id) - if (priorRun) { - runtime.cancelMessageWaiters(`run:${priorRun.id}`) - } - return { run: exposeRun(run) } + return { run: exposeRun(createBoundRun(runtime, caller, params.from, params.objective)) } } }), defineMethod({ diff --git a/src/main/runtime/rpc/methods/orchestration/worker/composed-workers.test.ts b/src/main/runtime/rpc/methods/orchestration/worker/composed-workers.test.ts index c63cee713d4..f6386d45705 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/composed-workers.test.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/composed-workers.test.ts @@ -165,6 +165,41 @@ describe('orchestration RPC methods', () => { ) }) + it('creates and binds a Run for an unbound coordinator, then names it on reuse', async () => { + setup(false) + mockCurrentWorkerStart() + const start = () => + call('orchestration.workerStart', { + spec: 'Audit the parser\nCheck every branch.', + from: 'term_coord', + agent: 'codex' + }) + + const first = await start() + const bound = db.getCurrentRunForCoordinator({ + terminalHandle: 'term_coord', + paneKey: coordinatorPaneKey, + orcaSessionId: null + }) + const run = { id: bound?.id, objective: 'Audit the parser' } + expect(first).toMatchObject({ state: 'ready', run: { ...run, created: true } }) + expect(await start()).toMatchObject({ run: { ...run, created: false } }) + }) + + it('creates no Run when an unbound coordinator names an existing Task', async () => { + setup(false) + mockCurrentWorkerStart() + + await expect( + call('orchestration.workerStart', { + task: 'task_missing', + from: 'term_coord', + agent: 'codex' + }) + ).rejects.toMatchObject({ code: 'consumer_fenced' }) + expect(db.listRuns().runs.filter((run) => run.legacy === 0)).toEqual([]) + }) + it('applies and reports opaque per-invocation model preferences', async () => { setup() mockCurrentWorkerStart() diff --git a/src/main/runtime/rpc/methods/orchestration/worker/worker-start-authority.ts b/src/main/runtime/rpc/methods/orchestration/worker/worker-start-authority.ts index 8c925a46c52..be74617d343 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/worker-start-authority.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/worker-start-authority.ts @@ -7,8 +7,10 @@ import type { import type { DispatchContextRow, RunRow, TaskRow } from '../../../../orchestration/types' import type { OrcaRuntimeService } from '../../../../orca-runtime' import { resolveDispatchCreator } from '../runs/dispatch-creator' +import { createBoundRun } from '../runs/runs' +import { ROOT_DISPATCH_DEPTH } from '../../../../../../shared/nested-worker-depth' -/** Coordinators start workers in their Run; active workers start helpers as themselves so reports return to their Dispatch without moving its mailbox. */ +/** Coordinators start workers in their Run, creating one when none is bound; active workers start helpers as themselves so reports return to their Dispatch without moving its mailbox. */ export function resolveWorkerStartRun( runtime: OrcaRuntimeService, args: { @@ -16,8 +18,10 @@ export function resolveWorkerStartRun( from: string callerSession: OrchestrationSessionCaller | undefined runId: string | undefined + /** Objective for a Run this start may create; absent when it names an existing Task. */ + objective: string | undefined } -): { run: RunRow; helperCreator?: DispatchContextRow } { +): { run: RunRow; runCreated: boolean; helperCreator?: DispatchContextRow } { const db = runtime.getOrchestrationDb() const coordinated = args.coordinator ? db.getCurrentRunForCoordinator(args.coordinator) @@ -26,25 +30,36 @@ export function resolveWorkerStartRun( if (args.runId && args.runId !== coordinated.id) { throw fenced(`This caller coordinates Run ${coordinated.id}, not ${args.runId}.`) } - return { run: coordinated } + return { run: coordinated, runCreated: false } } // Use the same active delegated Dispatch for authority and creator/reporting identity; remote Dispatches have no local row. - const creatorId = db.resolveCreatorDispatchId( - resolveDispatchCreator(runtime, args.from, args.callerSession) - ) + const dispatchCreator = resolveDispatchCreator(runtime, args.from, args.callerSession) + const creatorId = db.resolveCreatorDispatchId(dispatchCreator) const creator = creatorId ? db.getDispatchContextById(creatorId) : undefined const run = creator ? db.getRun(creator.run_id) : undefined - if (!creator || !run || run.legacy === 1) { - throw fenced( - 'worker-start needs the coordinator bound to the Run, or a worker on an active Dispatch in it.' - ) + if (creator && run && run.legacy !== 1) { + if (args.runId && args.runId !== run.id) { + throw fenced( + `This worker's Dispatch ${creator.id} is in Run ${run.id}; it starts helpers only there.` + ) + } + return { run, runCreated: false, helperCreator: creator } } - if (args.runId && args.runId !== run.id) { - throw fenced( - `This worker's Dispatch ${creator.id} is in Run ${run.id}; it starts helpers only there.` - ) + // Only a root caller gets a new Run, so a worker can never reset its depth this way. + if ( + args.coordinator && + args.objective && + !args.runId && + db.resolveCreatorDepth(dispatchCreator) === ROOT_DISPATCH_DEPTH + ) { + return { + run: createBoundRun(runtime, args.coordinator, args.from, args.objective), + runCreated: true + } } - return { run, helperCreator: creator } + throw fenced( + 'worker-start needs the coordinator bound to the Run, or a worker on an active Dispatch in it.' + ) } /** Workers may launch fresh local helpers or retry their own helper's latest Attempt, never coordinator Tasks or another party's pane. */ diff --git a/src/main/runtime/rpc/methods/orchestration/worker/workers.ts b/src/main/runtime/rpc/methods/orchestration/worker/workers.ts index eb5ef4aca8f..df2385766ab 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/workers.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/workers.ts @@ -13,6 +13,7 @@ import { isWorkerStartTimeoutWithinTimerLimit, resolveWorkerStartReadinessTimeoutMs } from '../../../../../../shared/orchestration-timing-budgets' +import { buildOrchestrationTaskDisplayMetadata } from '../../../../../../shared/orchestration-task-display' import { assertWorkerStartTaskSpecWithinPromptBudget } from './worker-start-prompt-budget' import { ORCA_SESSION_ADDRESS_PREFIX } from '../../../../../../shared/orca-session-address' import { ORCHESTRATION_SESSION_CALLER_ERROR_CODES as SESSION_CODES } from '../../../../../../shared/orchestration-session-caller-codes' @@ -32,34 +33,6 @@ export const ORCHESTRATION_WORKER_START_METHODS = [ '--timeout-ms is too large for worker-start transport grace; the derived timeout must fit within the timer limit.' ) } - const readinessTimeoutMs = resolveWorkerStartReadinessTimeoutMs(params.timeoutMs) - const db = runtime.getOrchestrationDb() - const coordinator = resolveOrchestrationCaller(runtime, { - callerTerminalHandle: params.from, - callerEvidence: orchestrationCompatibilityEvidence, - callerSession: orchestrationCaller - }) - const { run, helperCreator } = resolveWorkerStartRun(runtime, { - coordinator, - from: params.from, - callerSession: orchestrationCaller, - runId: params.run - }) - const existingTask = params.task ? db.getTask(params.task) : undefined - if (params.task && (!existingTask || existingTask.run_id !== run.id)) { - throw new OrchestrationError( - 'task_not_found', - `Task ${params.task} was not found in Run ${run.id}.` - ) - } - if (helperCreator) { - assertHelperStartScope(db, helperCreator, { task: existingTask, params }) - } - await assertWorkerStartTaskSpecWithinPromptBudget(params.spec ?? existingTask!.spec) - const mode = decideWorkerStartMode({ - params, - settings: readWorkerStartModeSettings(runtime) - }) if (params.on && params.terminal?.startsWith(ORCA_SESSION_ADDRESS_PREFIX)) { // Refused here, before any remote call: an Orca session ID names a chat only on its own host. throw new OrchestrationError( @@ -68,6 +41,56 @@ export const ORCHESTRATION_WORKER_START_METHODS = [ { effectsApplied: false } ) } + const readinessTimeoutMs = resolveWorkerStartReadinessTimeoutMs(params.timeoutMs) + const db = runtime.getOrchestrationDb() + const coordinator = resolveOrchestrationCaller(runtime, { + callerTerminalHandle: params.from, + callerEvidence: orchestrationCompatibilityEvidence, + callerSession: orchestrationCaller + }) + const { run, runCreated, helperCreator } = resolveWorkerStartRun(runtime, { + coordinator, + from: params.from, + callerSession: orchestrationCaller, + runId: params.run, + // The Run takes the title its first Task gets. + objective: params.spec + ? buildOrchestrationTaskDisplayMetadata({ + spec: params.spec, + taskTitle: params.taskTitle + }).taskTitle + : undefined + }) + // Name the Run in every receipt so a reused, stale binding is visible. + const withRun = (receipt: unknown): unknown => + receipt && typeof receipt === 'object' + ? { + ...receipt, + run: { + id: run.id, + objective: run.objective, + created: runCreated + } + } + : receipt + const existingTask = params.task ? db.getTask(params.task) : undefined + if (params.task && (!existingTask || existingTask.run_id !== run.id)) { + throw new OrchestrationError( + 'task_not_found', + `Task ${params.task} was not found in Run ${run.id}.` + ) + } + if (helperCreator) { + assertHelperStartScope(db, helperCreator, { + task: existingTask, + params + }) + } + await assertWorkerStartTaskSpecWithinPromptBudget(params.spec ?? existingTask!.spec) + const mode = decideWorkerStartMode({ + params, + settings: readWorkerStartModeSettings(runtime) + }) if (params.on) { // Remote workers are terminal-only; carry the mode receipt to explain structured-preference fallback. const receipt = await startFederatedWorker({ @@ -79,20 +102,22 @@ export const ORCHESTRATION_WORKER_START_METHODS = [ orchestrationMutation, callerSession: orchestrationCaller }) - return receipt && typeof receipt === 'object' ? { ...receipt, mode } : receipt + return withRun(receipt && typeof receipt === 'object' ? { ...receipt, mode } : receipt) } - return startLocalWorker({ - params: { ...params, timeoutMs: readinessTimeoutMs }, - runtime, - db, - run, - coordinator, - callerSession: orchestrationCaller, - existingTask, - orchestrationMutation, - mode, - helperCreator - }) + return withRun( + await startLocalWorker({ + params: { ...params, timeoutMs: readinessTimeoutMs }, + runtime, + db, + run, + coordinator, + callerSession: orchestrationCaller, + existingTask, + orchestrationMutation, + mode, + helperCreator + }) + ) } }) ] diff --git a/src/shared/orchestration-runtime-capabilities.ts b/src/shared/orchestration-runtime-capabilities.ts index 7e33fc70d21..4c340507515 100644 --- a/src/shared/orchestration-runtime-capabilities.ts +++ b/src/shared/orchestration-runtime-capabilities.ts @@ -7,6 +7,9 @@ export const ORCHESTRATION_WORKER_STOP_VERDICT_RUNTIME_CAPABILITY = 'orchestration.worker-stop-verdict.v1' as const export const ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY = 'orchestration.worker-launch-preferences.v1' as const +/** worker-start creates and binds a Run when a coordinator has none. */ +export const ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY = + 'orchestration.worker-start-creates-run.v1' as const export const ORCHESTRATION_FEDERATION_STRUCTURED_READ_RUNTIME_CAPABILITY = 'orchestration.federation-structured-read.v1' as const export const ORCHESTRATION_FEDERATION_FLEET_SNAPSHOT_RUNTIME_CAPABILITY = @@ -24,6 +27,7 @@ export const ORCHESTRATION_RUNTIME_CAPABILITIES = [ ORCHESTRATION_FEDERATION_LIFECYCLE_SETTLEMENT_RUNTIME_CAPABILITY, ORCHESTRATION_WORKER_STOP_VERDICT_RUNTIME_CAPABILITY, ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY, + ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_STRUCTURED_READ_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_FLEET_SNAPSHOT_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_RELEASE_ARCHIVE_RUNTIME_CAPABILITY, diff --git a/src/shared/protocol-version.ts b/src/shared/protocol-version.ts index 5b989c2cc3f..df661bf9686 100644 --- a/src/shared/protocol-version.ts +++ b/src/shared/protocol-version.ts @@ -90,6 +90,7 @@ export { ORCHESTRATION_FEDERATION_LIFECYCLE_SETTLEMENT_RUNTIME_CAPABILITY, ORCHESTRATION_WORKER_STOP_VERDICT_RUNTIME_CAPABILITY, ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY, + ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_STRUCTURED_READ_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_FLEET_SNAPSHOT_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_RELEASE_ARCHIVE_RUNTIME_CAPABILITY, From bc3ad67410aceffa9486f69109e36af54192f3ce Mon Sep 17 00:00:00 2001 From: Jinwoo-H Date: Wed, 28 Oct 2026 04:36:38 -0400 Subject: [PATCH 2/2] fix(orchestration): drop the older-runtime fallback; check the spec before a Run is created The CLI fallback matched a refusal text the client decorates, could not prove the caller was a root coordinator on an older runtime, and recovered an inner run-create under the worker-start command. Older runtimes keep their refusal and the guide says to run-create first there. The prompt budget check now runs before worker-start can create a Run. --- skill-guides/orchestration.md | 5 +- src/cli/bundled-skill-guides.ts | 5 +- .../orchestration/worker-launch-handler.ts | 98 +++---------------- .../worker-start-older-runtime-run.test.ts | 83 ---------------- .../methods/orchestration/worker/workers.ts | 8 +- .../orchestration-runtime-capabilities.ts | 4 - src/shared/protocol-version.ts | 1 - 7 files changed, 29 insertions(+), 175 deletions(-) delete mode 100644 src/cli/handlers/orchestration/worker-start-older-runtime-run.test.ts diff --git a/skill-guides/orchestration.md b/skill-guides/orchestration.md index 0f6a17c6d15..f899460808c 100644 --- a/skill-guides/orchestration.md +++ b/skill-guides/orchestration.md @@ -104,8 +104,9 @@ precedence over the idle rule. Do not reuse the settled lifecycle IDs. Confirm the runtime and start the full independent wave before waiting. `worker-start --spec` creates the Task and its attempt in one call; with no Run -bound, it also creates one bound to you. Its receipt's `run` names the Run it -created or joined; if that is an earlier goal's Run, `run-create` first: +bound, it also creates one bound to you (an older Orca refuses instead; then +`run-create` first). Its receipt's `run` names the Run it created or joined; if +that is an earlier goal's Run, `run-create` first: ```text ORCA status --json diff --git a/src/cli/bundled-skill-guides.ts b/src/cli/bundled-skill-guides.ts index e81dc42ab35..7442a8abdbc 100644 --- a/src/cli/bundled-skill-guides.ts +++ b/src/cli/bundled-skill-guides.ts @@ -2437,8 +2437,9 @@ const ORCHESTRATION_MARKDOWN = [ "", "Confirm the runtime and start the full independent wave before waiting.", "`worker-start --spec` creates the Task and its attempt in one call; with no Run", - "bound, it also creates one bound to you. Its receipt's `run` names the Run it", - "created or joined; if that is an earlier goal's Run, `run-create` first:", + "bound, it also creates one bound to you (an older Orca refuses instead; then", + "`run-create` first). Its receipt's `run` names the Run it created or joined; if", + "that is an earlier goal's Run, `run-create` first:", "", "```text", "ORCA status --json", diff --git a/src/cli/handlers/orchestration/worker-launch-handler.ts b/src/cli/handlers/orchestration/worker-launch-handler.ts index 53e8505e9a8..747d9801e4c 100644 --- a/src/cli/handlers/orchestration/worker-launch-handler.ts +++ b/src/cli/handlers/orchestration/worker-launch-handler.ts @@ -1,17 +1,9 @@ import type { CommandHandler } from '../../dispatch' import { printResult } from '../../format' import { getOptionalStringFlag, getPresentStringFlag } from '../../flags' -import { - RuntimeClientError, - type RuntimeClient, - type RuntimeRpcSuccess -} from '../../runtime-client' +import { RuntimeClientError } from '../../runtime-client' import type { RuntimeStatus } from '../../../shared/runtime-types' -import { - ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY, - ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY -} from '../../../shared/protocol-version' -import { buildOrchestrationTaskDisplayMetadata } from '../../../shared/orchestration-task-display' +import { ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY } from '../../../shared/protocol-version' import { callOrchestrationMutation } from './mutation-request' import { getOptionalPositiveIntegerValueFlag } from './numeric-flags' import { isDevCliInvocation } from './runtime-compatibility' @@ -19,75 +11,6 @@ import { resolveCoordinatorTerminalHandle } from './terminal-identity' import { formatWorkerStart } from './worker-output' import { renderResolvedOrchestrationCommand } from '../../orchestration-mutation-recovery' -type WorkerStartResult = { - runId: string - taskId: string - dispatchId: string - state: string - failedStage?: string - lastError?: string - warning?: string - mode?: { mode: string; preferred: string; reason: string; detail: string } - run?: { id: string; objective: string; created: boolean } - effects: unknown[] - residualResources: unknown[] - nextCommands?: string[] -} - -// Older runtimes refuse an unbound coordinator with exactly this; it also proves the caller works no Dispatch there. -const OLDER_RUNTIME_UNBOUND_COORDINATOR = - 'worker-start needs the coordinator bound to the Run, or a worker on an active Dispatch in it.' - -/** Start a worker; against a runtime that cannot create the Run itself, run-create first as it would. */ -async function startWorker( - client: RuntimeClient, - flags: Map, - params: { spec?: string; taskTitle?: string; run?: string; from?: string } -): Promise> { - try { - return await callOrchestrationMutation( - client, - flags, - 'orchestration.workerStart', - params - ) - } catch (error) { - const { spec } = params - if ( - !spec || - params.run || - !(error instanceof RuntimeClientError) || - error.code !== 'consumer_fenced' || - error.message !== OLDER_RUNTIME_UNBOUND_COORDINATOR || - (await client.call('status.get')).result.capabilities?.includes( - ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY - ) - ) { - throw error - } - const { taskTitle: objective } = buildOrchestrationTaskDisplayMetadata({ - spec, - taskTitle: params.taskTitle - }) - const created = await callOrchestrationMutation<{ run: { id: string; objective: string } }>( - client, - new Map(), - 'orchestration.runCreate', - { objective, from: params.from } - ) - const started = await callOrchestrationMutation( - client, - flags, - 'orchestration.workerStart', - params - ) - return { - ...started, - result: { ...started.result, run: { ...created.result.run, created: true } } - } - } -} - export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record = { 'orchestration worker-start': async ({ flags, client, cwd, json }) => { const terminal = getPresentStringFlag(flags, 'terminal') @@ -111,7 +34,19 @@ export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record const taskTitle = getOptionalStringFlag(flags, 'task-title') const deps = getOptionalStringFlag(flags, 'deps') const parent = getOptionalStringFlag(flags, 'parent') - const params = { + const result = await callOrchestrationMutation<{ + runId: string + taskId: string + dispatchId: string + state: string + failedStage?: string + lastError?: string + warning?: string + mode?: { mode: string; preferred: string; reason: string; detail: string } + effects: unknown[] + residualResources: unknown[] + nextCommands?: string[] + }>(client, flags, 'orchestration.workerStart', { task, ...(spec ? { spec } : {}), ...(taskTitle ? { taskTitle } : {}), @@ -134,8 +69,7 @@ export const ORCHESTRATION_WORKER_LAUNCH_HANDLER: Record run: getOptionalStringFlag(flags, 'run'), from: await resolveCoordinatorTerminalHandle(flags, cwd, client), devMode: isDevCliInvocation() - } - const result = await startWorker(client, flags, params) + }) if (result.result.state !== 'ready') { process.exitCode = 1 } diff --git a/src/cli/handlers/orchestration/worker-start-older-runtime-run.test.ts b/src/cli/handlers/orchestration/worker-start-older-runtime-run.test.ts deleted file mode 100644 index 48c083a2a19..00000000000 --- a/src/cli/handlers/orchestration/worker-start-older-runtime-run.test.ts +++ /dev/null @@ -1,83 +0,0 @@ -import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' -import { ORCHESTRATION_HANDLERS } from '../orchestration' -import { RuntimeClient, RuntimeClientError } from '../../runtime-client' -import { okFixture } from '../../test-fixtures' -import { ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY } from '../../../shared/protocol-version' - -const client = new RuntimeClient('/tmp/orca-older-runtime-run', 60_000, null, null) -const UNBOUND = new RuntimeClientError( - 'consumer_fenced', - 'worker-start needs the coordinator bound to the Run, or a worker on an active Dispatch in it.' -) - -describe('worker-start against a runtime that cannot create the Run itself', () => { - const methods: string[] = [] - let runCreateParams: unknown - - function stubRuntime(capabilities: string[]): void { - let starts = 0 - vi.spyOn(client, 'call').mockImplementation(async (method: string, params?: unknown) => { - methods.push(method) - if (method === 'status.get') { - return okFixture('req_status', { capabilities }) - } - if (method === 'orchestration.runCreate') { - runCreateParams = params - return okFixture('req_run', { run: { id: 'run_1', objective: 'Audit the parser' } }) - } - if (method === 'orchestration.workerStart') { - starts += 1 - if (starts === 1) { - throw UNBOUND - } - return okFixture('req_start', { state: 'ready', effects: [], residualResources: [] }) - } - throw new Error(`Unexpected RPC: ${method}`) - }) - } - - async function start(): Promise { - await ORCHESTRATION_HANDLERS['orchestration worker-start']({ - flags: new Map([ - ['spec', 'Audit the parser\nCheck every branch.'], - ['terminal', 'term_worker'], - ['from', 'term_coord'] - ]), - client, - cwd: '/tmp/coord', - json: true - }) - } - - beforeEach(() => { - methods.length = 0 - runCreateParams = undefined - vi.spyOn(console, 'log').mockImplementation(() => {}) - }) - - afterEach(() => { - vi.restoreAllMocks() - process.exitCode = undefined - }) - - it('creates the Run as run-create would, then starts the worker once more', async () => { - stubRuntime([]) - - await start() - - expect(methods).toEqual([ - 'orchestration.workerStart', - 'status.get', - 'orchestration.runCreate', - 'orchestration.workerStart' - ]) - expect(runCreateParams).toEqual({ objective: 'Audit the parser', from: 'term_coord' }) - }) - - it('leaves the refusal alone when the runtime would have created the Run', async () => { - stubRuntime([ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY]) - - await expect(start()).rejects.toBe(UNBOUND) - expect(methods).not.toContain('orchestration.runCreate') - }) -}) diff --git a/src/main/runtime/rpc/methods/orchestration/worker/workers.ts b/src/main/runtime/rpc/methods/orchestration/worker/workers.ts index df2385766ab..38937b74f01 100644 --- a/src/main/runtime/rpc/methods/orchestration/worker/workers.ts +++ b/src/main/runtime/rpc/methods/orchestration/worker/workers.ts @@ -48,6 +48,10 @@ export const ORCHESTRATION_WORKER_START_METHODS = [ callerEvidence: orchestrationCompatibilityEvidence, callerSession: orchestrationCaller }) + if (params.spec) { + // Before the Run resolves, so a refused spec cannot leave a new Run bound. + await assertWorkerStartTaskSpecWithinPromptBudget(params.spec) + } const { run, runCreated, helperCreator } = resolveWorkerStartRun(runtime, { coordinator, from: params.from, @@ -86,7 +90,9 @@ export const ORCHESTRATION_WORKER_START_METHODS = [ params }) } - await assertWorkerStartTaskSpecWithinPromptBudget(params.spec ?? existingTask!.spec) + if (existingTask) { + await assertWorkerStartTaskSpecWithinPromptBudget(existingTask.spec) + } const mode = decideWorkerStartMode({ params, settings: readWorkerStartModeSettings(runtime) diff --git a/src/shared/orchestration-runtime-capabilities.ts b/src/shared/orchestration-runtime-capabilities.ts index 4c340507515..7e33fc70d21 100644 --- a/src/shared/orchestration-runtime-capabilities.ts +++ b/src/shared/orchestration-runtime-capabilities.ts @@ -7,9 +7,6 @@ export const ORCHESTRATION_WORKER_STOP_VERDICT_RUNTIME_CAPABILITY = 'orchestration.worker-stop-verdict.v1' as const export const ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY = 'orchestration.worker-launch-preferences.v1' as const -/** worker-start creates and binds a Run when a coordinator has none. */ -export const ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY = - 'orchestration.worker-start-creates-run.v1' as const export const ORCHESTRATION_FEDERATION_STRUCTURED_READ_RUNTIME_CAPABILITY = 'orchestration.federation-structured-read.v1' as const export const ORCHESTRATION_FEDERATION_FLEET_SNAPSHOT_RUNTIME_CAPABILITY = @@ -27,7 +24,6 @@ export const ORCHESTRATION_RUNTIME_CAPABILITIES = [ ORCHESTRATION_FEDERATION_LIFECYCLE_SETTLEMENT_RUNTIME_CAPABILITY, ORCHESTRATION_WORKER_STOP_VERDICT_RUNTIME_CAPABILITY, ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY, - ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_STRUCTURED_READ_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_FLEET_SNAPSHOT_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_RELEASE_ARCHIVE_RUNTIME_CAPABILITY, diff --git a/src/shared/protocol-version.ts b/src/shared/protocol-version.ts index df661bf9686..5b989c2cc3f 100644 --- a/src/shared/protocol-version.ts +++ b/src/shared/protocol-version.ts @@ -90,7 +90,6 @@ export { ORCHESTRATION_FEDERATION_LIFECYCLE_SETTLEMENT_RUNTIME_CAPABILITY, ORCHESTRATION_WORKER_STOP_VERDICT_RUNTIME_CAPABILITY, ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY, - ORCHESTRATION_WORKER_START_CREATES_RUN_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_STRUCTURED_READ_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_FLEET_SNAPSHOT_RUNTIME_CAPABILITY, ORCHESTRATION_FEDERATION_RELEASE_ARCHIVE_RUNTIME_CAPABILITY,