Skip to content
14 changes: 7 additions & 7 deletions resources/skills/current-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -130,18 +130,18 @@
{
"name": "orchestration",
"sourcePath": "skills/orchestration",
"releaseRevision": 25,
"packageDigest": "c19171d213e827bdf5364b733b67889566aaa2fb3667ebe029db87044d08f908",
"gitTreeSha": "da346803bccae7fb1fdade31bbe9b4d851b25e38",
"releaseRevision": 26,
"packageDigest": "486748adb7164c3f580097f6334d68d40295272ad0a06e43549fbe3bb17debf0",
"gitTreeSha": "6fd9e9e14ec93d4124b34dfb1c898d2235b37bff",
"files": [
{
"path": "SKILL.md",
"size": 22676,
"size": 23226,
"executable": false,
"classification": "text",
"exactSha256": "0cfb6a082625edc0d474bae430eb22c28bbe484e54fbfebedb4ff89d96e36305",
"textNormalizedSha256": "0cfb6a082625edc0d474bae430eb22c28bbe484e54fbfebedb4ff89d96e36305",
"identitySha256": "0cfb6a082625edc0d474bae430eb22c28bbe484e54fbfebedb4ff89d96e36305"
"exactSha256": "05b73b2e3e792a1e79edded0aaacf28ffa0693e36ac4a1222e40b390dccf899b",
"textNormalizedSha256": "05b73b2e3e792a1e79edded0aaacf28ffa0693e36ac4a1222e40b390dccf899b",
"identitySha256": "05b73b2e3e792a1e79edded0aaacf28ffa0693e36ac4a1222e40b390dccf899b"
}
]
}
Expand Down
16 changes: 16 additions & 0 deletions resources/skills/snapshot-registry.json
Original file line number Diff line number Diff line change
Expand Up @@ -963,6 +963,22 @@
"identitySha256": "0cfb6a082625edc0d474bae430eb22c28bbe484e54fbfebedb4ff89d96e36305"
}
]
},
{
"releaseRevision": 26,
"packageDigest": "486748adb7164c3f580097f6334d68d40295272ad0a06e43549fbe3bb17debf0",
"gitTreeSha": "6fd9e9e14ec93d4124b34dfb1c898d2235b37bff",
"files": [
{
"path": "SKILL.md",
"size": 23226,
"executable": false,
"classification": "text",
"exactSha256": "05b73b2e3e792a1e79edded0aaacf28ffa0693e36ac4a1222e40b390dccf899b",
"textNormalizedSha256": "05b73b2e3e792a1e79edded0aaacf28ffa0693e36ac4a1222e40b390dccf899b",
"identitySha256": "05b73b2e3e792a1e79edded0aaacf28ffa0693e36ac4a1222e40b390dccf899b"
}
]
}
],
"mobile-fit-debug": [
Expand Down
8 changes: 4 additions & 4 deletions skill-guides/orchestration.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Do not use orchestration merely because the user says "hand off", "handoff", "ha

## Ownership

Orchestration messages and tasks are runtime-global. Lifecycle authority comes from the payload `taskId` + `dispatchId` of the active dispatch, verified against the dispatched pane. Terminal handles are routing metadata — a pane can receive a new handle after restart — so never accept or reject lifecycle provenance by comparing handles. Send `worker_done` and `heartbeat` from the worker's own terminal; the runtime ignores them when sent from a different pane.
Orchestration state is persisted by the runtime. Rows with a `workspace_key` are owned by that workspace; NULL rows are legacy/global and remain visible to scoped coordinators for compatibility. Lifecycle authority comes from the payload `taskId` + `dispatchId` of the active dispatch, verified against the dispatched pane. Terminal handles are routing metadata — a pane can receive a new handle after restart — so never accept or reject lifecycle provenance by comparing handles. Send `worker_done` and `heartbeat` from the worker's own terminal; the runtime ignores them when sent from a different pane.

Classify inherited context before sending lifecycle messages:

Expand Down Expand Up @@ -130,11 +130,11 @@ Dispatch rules:
orca orchestration gate-create --task <task_id> --question <text> [--options <json_array>] [--json]
orca orchestration gate-resolve --id <gate_id> --resolution <text> [--json]
orca orchestration gate-list [--task <task_id>] [--status <status>] [--json]
orca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector>] [--json]
orca orchestration run-stop [--json]
orca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector|all>] [--json]
orca orchestration run-stop [--worktree <selector|all>] [--json]
```

`run` returns immediately with a run ID. Query progress with `task-list`. Use `ask` for worker-to-coordinator questions; it creates a `decision_gate` message that the coordinator answers with `reply`. Use `gate-create` only for coordinator-managed task DAG decisions, not for answering a worker's `ask`.
`run` returns immediately with a run ID. Query progress with `task-list`. Pass `--worktree <selector>` to isolate a coordinator to one workspace; omit it or pass `--worktree all` for the global coordinator, which cannot run alongside scoped coordinators. `run-stop --worktree <selector>` stops that workspace exactly, while `--worktree all` stops the global coordinator; without a selector, stop succeeds only when exactly one coordinator is active. Use `ask` for worker-to-coordinator questions; it creates a `decision_gate` message that the coordinator answers with `reply`. Use `gate-create` only for coordinator-managed task DAG decisions, not for answering a worker's `ask`.

Recovery only: `orca orchestration reset --tasks|--messages|--all --json` clears runtime-global orchestration state. Do not run it during active coordination unless explicitly abandoning that state.

Expand Down
8 changes: 4 additions & 4 deletions skills/orchestration/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Do not use orchestration merely because the user says "hand off", "handoff", "ha

## Ownership

Orchestration messages and tasks are runtime-global. Lifecycle authority comes from the payload `taskId` + `dispatchId` of the active dispatch, verified against the dispatched pane. Terminal handles are routing metadata — a pane can receive a new handle after restart — so never accept or reject lifecycle provenance by comparing handles. Send `worker_done` and `heartbeat` from the worker's own terminal; the runtime ignores them when sent from a different pane.
Orchestration state is persisted by the runtime. Rows with a `workspace_key` are owned by that workspace; NULL rows are legacy/global and remain visible to scoped coordinators for compatibility. Lifecycle authority comes from the payload `taskId` + `dispatchId` of the active dispatch, verified against the dispatched pane. Terminal handles are routing metadata — a pane can receive a new handle after restart — so never accept or reject lifecycle provenance by comparing handles. Send `worker_done` and `heartbeat` from the worker's own terminal; the runtime ignores them when sent from a different pane.

Classify inherited context before sending lifecycle messages:

Expand Down Expand Up @@ -130,11 +130,11 @@ Dispatch rules:
orca orchestration gate-create --task <task_id> --question <text> [--options <json_array>] [--json]
orca orchestration gate-resolve --id <gate_id> --resolution <text> [--json]
orca orchestration gate-list [--task <task_id>] [--status <status>] [--json]
orca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector>] [--json]
orca orchestration run-stop [--json]
orca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector|all>] [--json]
orca orchestration run-stop [--worktree <selector|all>] [--json]
```

`run` returns immediately with a run ID. Query progress with `task-list`. Use `ask` for worker-to-coordinator questions; it creates a `decision_gate` message that the coordinator answers with `reply`. Use `gate-create` only for coordinator-managed task DAG decisions, not for answering a worker's `ask`.
`run` returns immediately with a run ID. Query progress with `task-list`. Pass `--worktree <selector>` to isolate a coordinator to one workspace; omit it or pass `--worktree all` for the global coordinator, which cannot run alongside scoped coordinators. `run-stop --worktree <selector>` stops that workspace exactly, while `--worktree all` stops the global coordinator; without a selector, stop succeeds only when exactly one coordinator is active. Use `ask` for worker-to-coordinator questions; it creates a `decision_gate` message that the coordinator answers with `reply`. Use `gate-create` only for coordinator-managed task DAG decisions, not for answering a worker's `ask`.

Recovery only: `orca orchestration reset --tasks|--messages|--all --json` clears runtime-global orchestration state. Do not run it during active coordination unless explicitly abandoning that state.

Expand Down
2 changes: 1 addition & 1 deletion src/cli/bundled-skill-guides.ts

Large diffs are not rendered by default.

8 changes: 7 additions & 1 deletion src/cli/handlers/orchestration.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'

const callMock = vi.fn()
const getTerminalHandleMock = vi.hoisted(() => vi.fn())
const getOptionalWorktreeSelectorMock = vi.hoisted(() => vi.fn())
const originalTerminalHandle = process.env.ORCA_TERMINAL_HANDLE
const originalPaneKey = process.env.ORCA_PANE_KEY
function lifecycleGroupRecipientError(type: 'worker_done' | 'heartbeat'): string {
Expand All @@ -10,7 +11,10 @@ function lifecycleGroupRecipientError(type: 'worker_done' | 'heartbeat'): string

// Why: isolate the handler's flag-to-param mapping; printResult only writes output.
vi.mock('../format', () => ({ printResult: vi.fn() }))
vi.mock('../selectors', () => ({ getTerminalHandle: getTerminalHandleMock }))
vi.mock('../selectors', () => ({
getOptionalWorktreeSelector: getOptionalWorktreeSelectorMock,
getTerminalHandle: getTerminalHandleMock
}))

import { ORCHESTRATION_HANDLERS } from './orchestration'
import { RuntimeClientError } from '../runtime-client'
Expand All @@ -36,6 +40,7 @@ function stubStaleHandleRemintFailure(error: RuntimeClientError): void {

afterEach(() => {
getTerminalHandleMock.mockReset()
getOptionalWorktreeSelectorMock.mockReset()
if (originalTerminalHandle === undefined) {
delete process.env.ORCA_TERMINAL_HANDLE
} else {
Expand Down Expand Up @@ -343,6 +348,7 @@ describe('orchestration dispatch coordinator handle', () => {
beforeEach(() => {
callMock.mockReset()
getTerminalHandleMock.mockReset()
getOptionalWorktreeSelectorMock.mockReset().mockResolvedValue(undefined)
delete process.env.ORCA_TERMINAL_HANDLE
delete process.env.ORCA_PANE_KEY
})
Expand Down
42 changes: 34 additions & 8 deletions src/cli/handlers/orchestration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import {
getRequiredStringFlag
} from '../flags'
import { RuntimeClientError } from '../runtime-client'
import { getTerminalHandle } from '../selectors'
import { getOptionalWorktreeSelector, getTerminalHandle } from '../selectors'
import { abbreviateOrchestrationTasks } from '../../shared/orchestration-task-summary'

// Why: 15 s is well under Claude Code's ~2 min Bash-tool silence budget while keeping log volume low. See design doc §3.4.
Expand Down Expand Up @@ -131,7 +131,7 @@ async function resolveOrchestrationTerminalHandle(
cwd: string,
client: Parameters<CommandHandler>[0]['client'],
flagName: 'from' | 'terminal',
options: { validateEnvHandle?: boolean } = {}
options: { validateEnvHandle?: boolean; resolvedWorktree?: string } = {}
): Promise<string> {
const explicit = getOptionalStringFlag(flags, flagName)
if (explicit) {
Expand All @@ -152,6 +152,12 @@ async function resolveOrchestrationTerminalHandle(
}
return envHandle
}
if (options.resolvedWorktree !== undefined) {
const response = await client.call<{ handle: string }>('terminal.resolveActive', {
worktree: options.resolvedWorktree
})
return response.result.handle
}
if (flagName === 'from') {
return await resolveImplicitOrchestrationSender(flags, cwd, client)
}
Expand Down Expand Up @@ -274,10 +280,12 @@ function getClientErrorMessage(err: unknown): string | undefined {
async function resolveCoordinatorTerminalHandle(
flags: Map<string, string | boolean>,
cwd: string,
client: Parameters<CommandHandler>[0]['client']
client: Parameters<CommandHandler>[0]['client'],
resolvedWorktree?: string
): Promise<string> {
return await resolveOrchestrationTerminalHandle(flags, cwd, client, 'from', {
validateEnvHandle: true
validateEnvHandle: true,
resolvedWorktree
})
}

Expand All @@ -304,6 +312,17 @@ function throwNoActiveSenderTerminal(): never {
)
}

async function getOptionalOrchestrationWorktreeSelector(
flags: Map<string, string | boolean>,
cwd: string,
client: Parameters<CommandHandler>[0]['client']
): Promise<string | undefined> {
if (getOptionalStringFlag(flags, 'worktree') === 'all') {
return 'all'
}
return await getOptionalWorktreeSelector(flags, 'worktree', cwd, client)
}

function isDevCliInvocation(): boolean {
return process.env.ORCA_USER_DATA_PATH?.includes('orca-dev') ?? false
}
Expand Down Expand Up @@ -671,7 +690,9 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
},

'orchestration run': async ({ flags, client, cwd, json }) => {
const from = await resolveCoordinatorTerminalHandle(flags, cwd, client)
const worktree = await getOptionalOrchestrationWorktreeSelector(flags, cwd, client)
const terminalWorktree = worktree === 'all' ? undefined : worktree
const from = await resolveCoordinatorTerminalHandle(flags, cwd, client, terminalWorktree)
const result = await client.call<{
runId: string
status: string
Expand All @@ -680,16 +701,21 @@ export const ORCHESTRATION_HANDLERS: Record<string, CommandHandler> = {
from,
pollIntervalMs: getOptionalPositiveIntegerFlag(flags, 'poll-interval-ms'),
maxConcurrent: getOptionalPositiveIntegerFlag(flags, 'max-concurrent'),
worktree: getOptionalStringFlag(flags, 'worktree')
worktree
})
printResult(result, json, (r) => `Run ${r.runId} started (${r.status})`)
},

'orchestration run-stop': async ({ client, json }) => {
'orchestration run-stop': async ({ flags, client, cwd, json }) => {
const result = await client.call<{
runId: string
stopped: boolean
}>('orchestration.runStop', {})
}>('orchestration.runStop', {
// Why (#4389): pass through an explicit worktree or `all` so the runtime
// can stop an exact coordinator. Omitting it keeps the legacy single-run
// convenience, but the runtime rejects ambiguity when several runs exist.
worktree: await getOptionalOrchestrationWorktreeSelector(flags, cwd, client)
})
printResult(result, json, (r) => `Run ${r.runId} stopped`)
},

Expand Down
2 changes: 1 addition & 1 deletion src/cli/help.ts
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ Orchestration:
orchestration dispatch Dispatch a task to a terminal
orchestration dispatch-show Show dispatch context for a task
orchestration run Start the coordinator loop
orchestration run-stop Stop the active coordinator run
orchestration run-stop Stop one coordinator run [--worktree <selector|all>]
orchestration gate-create Create a decision gate blocking a task
orchestration gate-resolve Resolve a pending decision gate
orchestration gate-list List decision gates
Expand Down
88 changes: 88 additions & 0 deletions src/cli/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3558,6 +3558,94 @@ describe('orca cli worktree awareness', () => {
})
})

it('uses the resolved enclosing worktree for orchestration run', async () => {
queueFixtures(
callMock,
worktreeListFixture([buildWorktree('/tmp/repo/feature', 'feature/foo')]),
okFixture('req_active_terminal', { handle: 'term_coord' }),
okFixture('req_run', { runId: 'run_1', status: 'running' })
)
vi.spyOn(console, 'log').mockImplementation(() => {})

await main(
['orchestration', 'run', '--spec', 'ship it', '--worktree', 'active', '--json'],
'/tmp/repo/feature/src'
)

expect(callMock).toHaveBeenNthCalledWith(1, 'worktree.list', {
limit: 10_000
})
expect(callMock).toHaveBeenNthCalledWith(2, 'terminal.resolveActive', {
worktree: 'id:repo::/tmp/repo/feature'
})
expect(callMock).toHaveBeenNthCalledWith(3, 'orchestration.run', {
spec: 'ship it',
from: 'term_coord',
pollIntervalMs: undefined,
maxConcurrent: undefined,
worktree: 'id:repo::/tmp/repo/feature'
})
})

it('treats --worktree all as explicit global orchestration run scope', async () => {
process.env.ORCA_TERMINAL_HANDLE = 'term_coord'
queueFixtures(
callMock,
okFixture('req_terminal', { terminal: { handle: 'term_coord' } }),
okFixture('req_run', { runId: 'run_1', status: 'running' })
)
vi.spyOn(console, 'log').mockImplementation(() => {})

await main(
['orchestration', 'run', '--spec', 'ship it', '--worktree', 'all', '--json'],
'/tmp/repo/feature/src'
)

expect(callMock).toHaveBeenNthCalledWith(1, 'terminal.show', {
terminal: 'term_coord'
})
expect(callMock).toHaveBeenNthCalledWith(2, 'orchestration.run', {
spec: 'ship it',
from: 'term_coord',
pollIntervalMs: undefined,
maxConcurrent: undefined,
worktree: 'all'
})
})

it('accepts and resolves --worktree for orchestration run-stop', async () => {
queueFixtures(
callMock,
worktreeListFixture([buildWorktree('/tmp/repo/feature', 'feature/foo')]),
okFixture('req_run_stop', { runId: 'run_1', stopped: true })
)
vi.spyOn(console, 'log').mockImplementation(() => {})

await main(
['orchestration', 'run-stop', '--worktree', 'active', '--json'],
'/tmp/repo/feature/src'
)

expect(callMock).toHaveBeenNthCalledWith(2, 'orchestration.runStop', {
worktree: 'id:repo::/tmp/repo/feature'
})
})

it('passes --worktree all through for explicit global orchestration run-stop', async () => {
queueFixtures(callMock, okFixture('req_run_stop', { runId: 'run_1', stopped: true }))
vi.spyOn(console, 'log').mockImplementation(() => {})

await main(
['orchestration', 'run-stop', '--worktree', 'all', '--json'],
'/tmp/repo/feature/src'
)

expect(callMock).toHaveBeenCalledTimes(1)
expect(callMock).toHaveBeenCalledWith('orchestration.runStop', {
worktree: 'all'
})
})

it('passes dev mode to injected orchestration dispatches', async () => {
process.env.ORCA_TERMINAL_HANDLE = 'term_sender'
process.env.ORCA_USER_DATA_PATH = '/tmp/orca-dev'
Expand Down
12 changes: 9 additions & 3 deletions src/cli/specs/orchestration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -117,21 +117,27 @@ export const ORCHESTRATION_COMMAND_SPECS: CommandSpec[] = [
path: ['orchestration', 'run'],
summary: 'Start the coordinator loop',
usage:
'orca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector>] [--json]',
'orca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector|all>] [--json]',
allowedFlags: [
...GLOBAL_FLAGS,
'spec',
'from',
'poll-interval-ms',
'max-concurrent',
'worktree'
],
notes: [
'Use --worktree <selector> for an isolated coordinator. Omit --worktree or pass --worktree all for the global coordinator, which cannot run alongside scoped coordinators.'
]
},
{
path: ['orchestration', 'run-stop'],
summary: 'Stop the active coordinator run',
usage: 'orca orchestration run-stop [--json]',
allowedFlags: [...GLOBAL_FLAGS]
usage: 'orca orchestration run-stop [--worktree <selector|all>] [--json]',
allowedFlags: [...GLOBAL_FLAGS, 'worktree'],
notes: [
'Use --worktree all for the global coordinator. With no --worktree, run-stop succeeds only when exactly one coordinator is active.'
]
},
{
path: ['orchestration', 'gate-create'],
Expand Down
Loading
Loading