chore(orchestration): declare terminal and chat parity per method, ratchet new agent-kind branches

This commit is contained in:
Jinwoo-H
2026-11-09 05:15:21 -05:00
parent 19afa64ee7
commit 03f2b62bdf
11 changed files with 613 additions and 4 deletions
+4
View File
@@ -485,6 +485,10 @@ jobs:
if: needs.code_paths.outputs.static_analysis == 'true'
run: node config/scripts/plugin-authoring/rpc-catalog/generate-rpc-params-catalog.mjs --check
- name: Check orchestration parity declarations
if: needs.code_paths.outputs.static_analysis == 'true'
run: node config/scripts/static-analysis/orchestration-parity/check-orchestration-parity-declarations.mjs
- name: Verify the generated ACP protocol schema
if: needs.code_paths.outputs.static_analysis == 'true'
run: node config/scripts/acp/generate-protocol.mjs --check
@@ -0,0 +1,11 @@
id: orchestration-agent-kind-branch
valid:
- const party = resolveOrchestrationParty(address, db)
- if (party.terminalHandle === undefined) { return }
- const local = target.startsWith('run:')
invalid:
- if (to.startsWith(ORCA_SESSION_ADDRESS_PREFIX)) { return }
- const session = parseOrcaSessionAddress(to)
- if (party.orcaSessionId !== null) { notify() }
- if (agent.kind === 'structured') { inject() }
- const chat = !isTuiAgent(agent)
@@ -0,0 +1,39 @@
# Ratcheted by config/scripts/static-analysis/ratchets/orchestration/check-orchestration-agent-kind-ratchet.mjs;
# info severity keeps `pnpm lint:ast-grep` quiet about the grandfathered baseline.
# The addressing owners resolve an address or caller to its party; everything else should use that party.
id: orchestration-agent-kind-branch
language: typescript
severity: info
message: Branching on agent kind (terminal or chat) in an orchestration command splits their behaviour per command. Use the party the addressing owners resolve, and declare any per-kind refusal in src/main/runtime/orchestration/orchestration-parity.md.
note: 'A deliberate exception takes `// ast-grep-ignore: orchestration-agent-kind-branch -- <reason>` above the line.'
files:
- src/main/runtime/rpc/methods/orchestration/**
- src/main/runtime/orchestration/**
- src/main/runtime/rpc/orchestration-*.ts
- src/cli/handlers/orchestration/**
ignores:
- '**/*.test.*'
- '**/*test-support*'
- '**/*test-fixture*'
- src/main/runtime/orchestration/addressing/**
- src/main/runtime/rpc/orchestration-session-caller.ts
rule:
any:
# Address shape
- pattern: $X.startsWith(ORCA_SESSION_ADDRESS_PREFIX)
- pattern: $X.startsWith('orca_session_id:')
- pattern: isOrcaSessionId($$$)
- pattern: parseOrcaSessionAddress($$$)
- pattern: mayNameSession($$$)
# Party shape
- pattern: $P.orcaSessionId !== null
- pattern: $P.orcaSessionId === null
- pattern: $P.terminalHandle === null
- pattern: $P.terminalHandle !== null
# Kind and mode literals
- pattern: $K.kind === 'structured'
- pattern: $K.mode === 'structured'
- pattern: isTuiAgent($$$)
# Caller kind read from the environment
- pattern: readInjectedAgentSessionId($$$)
- pattern: hasStructuredSessionMarker($$$)
@@ -0,0 +1,37 @@
# Agent-kind branches per file (config/ast-grep/rules/orchestration-agent-kind-branch.yml).
# This is a RATCHET: counts may only go DOWN. Prune after a fix:
# pnpm check:orchestration-agent-kind-ratchet --prune
2 src/cli/handlers/orchestration/message-send-handler.ts
4 src/cli/handlers/orchestration/terminal-identity.ts
1 src/main/runtime/orchestration/crew/crew-parent-inputs.ts
4 src/main/runtime/orchestration/crew/crew-parties.ts
2 src/main/runtime/orchestration/crew/crew-party-snapshot.ts
1 src/main/runtime/orchestration/crew/crew-recipient-owner-queries.ts
3 src/main/runtime/orchestration/db/dispatch-context/worker-follow-up-lineage.ts
1 src/main/runtime/orchestration/db/runs/run-lookup.ts
1 src/main/runtime/orchestration/db/schema/structured-worker-orca-session-backfill.ts
1 src/main/runtime/orchestration/mailbox/routing/structured-session-mail-address.ts
3 src/main/runtime/orchestration/mailbox/routing/structured-session-mail-target.ts
1 src/main/runtime/orchestration/mailbox/senders/agent-message-sender.ts
2 src/main/runtime/orchestration/terminal-authority/structured-sessions/structured-worker-authority.ts
1 src/main/runtime/orchestration/terminal-authority/structured-sessions/structured-worker-custody.ts
1 src/main/runtime/orchestration/terminal-authority/structured-sessions/structured-worker-identity.ts
1 src/main/runtime/orchestration/terminal-authority/write-orchestration-pointer-pty.ts
2 src/main/runtime/orchestration/workers/launch/configured-worker-agent-selector.ts
1 src/main/runtime/orchestration/workers/launch/orchestration-cli-command.ts
1 src/main/runtime/orchestration/workers/launch/worker-dispatch-preamble.ts
1 src/main/runtime/orchestration/workers/launch/worker-launch-observation.ts
1 src/main/runtime/orchestration/workers/lifecycle/chat-assignee.ts
1 src/main/runtime/orchestration/workers/turn-stops/chat-worker-error-escalation.ts
1 src/main/runtime/rpc/methods/orchestration/caller-show.ts
1 src/main/runtime/rpc/methods/orchestration/federation/federated-worker-start.ts
3 src/main/runtime/rpc/methods/orchestration/messaging/recipient-routing.ts
1 src/main/runtime/rpc/methods/orchestration/messaging/send-methods.ts
6 src/main/runtime/rpc/methods/orchestration/messaging/session-recipient.ts
1 src/main/runtime/rpc/methods/orchestration/messaging/settled-worker-follow-through.ts
1 src/main/runtime/rpc/methods/orchestration/runs/dispatch-creator.ts
1 src/main/runtime/rpc/methods/orchestration/worker/deliver-worker-dispatch-preamble.ts
1 src/main/runtime/rpc/methods/orchestration/worker/worker-configured-agent-preflight.ts
1 src/main/runtime/rpc/methods/orchestration/worker/worker-earlier-work.ts
1 src/main/runtime/rpc/methods/orchestration/worker/worker-follow-up-placement.ts
1 src/main/runtime/rpc/methods/orchestration/worker/worker-start-validation.ts
@@ -33,6 +33,7 @@ export const LINT_STEPS = [
'check:legacy-relay-fence-ratchet',
'check:runtime-electron-ratchet',
'verify:rpc-params-catalog',
'check:orchestration-parity',
'check:repo-host-read-ratchet',
'test:ast-grep',
'check:max-lines-ratchet',
@@ -0,0 +1,107 @@
import { readFileSync } from 'node:fs'
import path from 'node:path'
import process from 'node:process'
import { pathToFileURL } from 'node:url'
import { readTrackedSources } from '../ratchet-baseline/ratchet-baseline.mjs'
// Every orchestration method declares what each agent kind gets in each location (terminal and chat parity).
const DECLARATION = 'src/main/runtime/orchestration/orchestration-parity.md'
// Generated from the RPC registry and checked fresh in CI, so it lists every registered method.
const CATALOG = 'src/shared/rpc-contract/rpc-params-catalog.generated.ts'
const LABELS = [
'Terminal · Local',
'Chat · Local',
'Terminal · Paired',
'Chat · Paired',
'Terminal · SSH/WSL',
'Chat · SSH/WSL'
]
const CELL = /^(?:supported(?:: .+)?|refused `([a-z_]+)`: .+|n\/a: .+)$/
// Both catalog lists are generated from the registry: methods with shared params, then those without.
export function registeredMethods(catalogText) {
return new Set(
[...catalogText.matchAll(/^\s*'(orchestration\.[A-Za-z]+)'[:,\n]/gm)].map((m) => m[1])
)
}
/** Each `## \`orchestration.x\`` section, as its `- <label>: <cell>` lines. */
export function declaredSections(markdown) {
const sections = []
for (const line of markdown.split('\n')) {
const method = /^## `(orchestration\.[A-Za-z]+)`$/.exec(line)?.[1]
if (method) {
sections.push({ method, cells: [] })
continue
}
const cell = /^- ([^:]+): (.+)$/.exec(line)
if (cell && sections.length > 0) {
sections.at(-1).cells.push({ label: cell[1], value: cell[2] })
}
}
return sections
}
/** `codeExists` says whether a refusal code is a real string literal in the source. */
export function censusProblems(methods, sections, codeExists) {
const problems = []
const declared = new Set()
for (const { method, cells } of sections) {
if (declared.has(method)) {
problems.push(`${method}: declared twice.`)
}
declared.add(method)
if (!methods.has(method)) {
problems.push(`${method}: declared, but no such method is registered.`)
}
const labels = cells.map((cell) => cell.label).join('\n')
if (labels !== 'All' && labels !== LABELS.join('\n')) {
problems.push(`${method}: list ${LABELS.join(', ')} in that order, or one All line.`)
}
for (const { value } of cells) {
const match = CELL.exec(value)
if (!match) {
problems.push(
`${method}: "${value}" is not supported, refused \`<code>\`: <reason>, or n/a: <reason>.`
)
} else if (match[1] && !codeExists(match[1])) {
problems.push(`${method}: refusal code ${match[1]} appears nowhere in src.`)
}
}
}
for (const method of [...methods].sort()) {
if (!declared.has(method)) {
problems.push(`${method}: no section; declare it in ${DECLARATION}.`)
}
}
return problems
}
export function main(root = process.cwd()) {
const read = (rel) => readFileSync(path.join(root, rel), 'utf8')
const sources = [
...readTrackedSources(root, ['src/main', 'src/shared'], (rel) => rel.endsWith('.ts')).values()
]
const codeExists = (code) => sources.some((text) => text.includes(`'${code}'`))
const problems = censusProblems(
registeredMethods(read(CATALOG)),
declaredSections(read(DECLARATION)),
codeExists
)
for (const problem of problems) {
console.error(problem)
}
if (problems.length > 0) {
console.error(
`${problems.length} orchestration parity problem(s). Sections describe the code as it is.`
)
return 1
}
console.log('Orchestration parity declaration OK.')
return 0
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
process.exitCode = main()
}
@@ -12,8 +12,9 @@ const RUN_ELSEWHERE = new Set([
'check-runtime-launcher-protocol-ratchet.mjs',
// Its own background preflight step, so it overlaps lint and typecheck.
'check-main-sync-spawn-ratchet.mjs',
// ast-grep-gates.mjs checks it from the ast-grep lint scan instead of scanning again.
'check-flaky-test-pattern-ratchet.mjs'
// ast-grep-gates.mjs checks these from the ast-grep lint scan instead of scanning again.
'check-flaky-test-pattern-ratchet.mjs',
'check-orchestration-agent-kind-ratchet.mjs'
])
export function listRatchetScripts(scriptsDir) {
@@ -0,0 +1,51 @@
import process from 'node:process'
import { pathToFileURL } from 'node:url'
import { scanAstGrep } from '../../structural-scan/ast-grep-scan.mjs'
import { listTrackedFiles, runCountRatchet } from '../../ratchet-baseline/ratchet-baseline.mjs'
// Orchestration code that branches on terminal vs chat; new sites fail so both kinds share one path.
const BASELINE_PATH = 'config/orchestration-agent-kind-baseline.txt'
const RULE_ID = 'orchestration-agent-kind-branch'
const HEADER = [
`# Agent-kind branches per file (config/ast-grep/rules/${RULE_ID}.yml).`,
'# This is a RATCHET: counts may only go DOWN. Prune after a fix:',
'# pnpm check:orchestration-agent-kind-ratchet --prune'
]
/** `matches` may come from an unfiltered scan another gate shares; only this rule counts. */
export function collectAgentKindCounts(root = process.cwd(), matches = undefined) {
// Tracked files only, so untracked scratch never changes the baseline.
const tracked = new Set(listTrackedFiles(root, []))
const counts = new Map()
for (const match of matches ?? scanAstGrep(root, { filter: `^${RULE_ID}$` })) {
const file = match.file.split('\\').join('/')
if (match.ruleId === RULE_ID && tracked.has(file)) {
counts.set(file, (counts.get(file) ?? 0) + 1)
}
}
return counts
}
export function main(root = process.cwd(), arg = undefined, matches = undefined) {
return runCountRatchet(
{
name: 'orchestration-agent-kind',
baselinePath: BASELINE_PATH,
header: HEADER,
collect: (dir) => collectAgentKindCounts(dir, matches),
unit: 'agent-kind branch(es)',
fix: [
'Use the party src/main/runtime/orchestration/addressing resolves instead of reading the',
'address or agent mode, and declare a per-kind refusal in orchestration-parity.md.',
`A deliberate exception takes \`// ast-grep-ignore: ${RULE_ID} -- <reason>\` above the line.`
]
},
root,
arg
)
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
process.exit(main(process.cwd(), process.argv[2]))
}
@@ -1,4 +1,4 @@
// One ast-grep scan for both gates: the lint gate (warning and up) and the flaky-test ratchet (`test-*` rules).
// One ast-grep scan for every gate: the lint gate (warning and up) and the info-severity ratchets.
import { spawnSync } from 'node:child_process'
import process from 'node:process'
import { pathToFileURL } from 'node:url'
@@ -9,6 +9,7 @@ import {
scanAstGrep
} from './ast-grep-scan.mjs'
import { main as checkFlakyTestPatterns } from '../ratchets/test-quality/check-flaky-test-pattern-ratchet.mjs'
import { main as checkOrchestrationAgentKind } from '../ratchets/orchestration/check-orchestration-agent-kind-ratchet.mjs'
const LINT_SEVERITIES = new Set(['error', 'warning'])
// Windows caps a command line near 32K characters; past this, rescan the whole tree.
@@ -58,7 +59,8 @@ export function main(root = process.cwd(), argv = []) {
const files = lintFindingFiles(matches)
const lint = files.length > 0 ? reportLintFindings(root, files, format) : 0
const flaky = checkFlakyTestPatterns(root, undefined, matches)
return Math.max(lint, flaky)
const agentKind = checkOrchestrationAgentKind(root, undefined, matches)
return Math.max(lint, flaky, agentKind)
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+2
View File
@@ -53,6 +53,8 @@
"check:react-compiler-compat-ratchet": "node config/scripts/static-analysis/ratchets/react-compiler/check-react-compiler-compat-ratchet.mjs",
"check:render-path-translate-ratchet": "node config/scripts/static-analysis/ratchets/renderer-state/check-render-path-translate-ratchet.mjs",
"check:flaky-test-pattern-ratchet": "node config/scripts/static-analysis/ratchets/test-quality/check-flaky-test-pattern-ratchet.mjs",
"check:orchestration-parity": "node config/scripts/static-analysis/orchestration-parity/check-orchestration-parity-declarations.mjs",
"check:orchestration-agent-kind-ratchet": "node config/scripts/static-analysis/ratchets/orchestration/check-orchestration-agent-kind-ratchet.mjs",
"check:path-literal-ratchet": "node config/scripts/static-analysis/ratchets/source-budget/check-path-literal-ratchet.mjs",
"check:legacy-relay-fence-ratchet": "node config/scripts/static-analysis/process-boundaries/check-legacy-relay-fence-ratchet.mjs",
"check:unproven-pty-retirement-ratchet": "node config/scripts/static-analysis/ratchets/runtime-lifecycle/check-unproven-pty-retirement-ratchet.mjs",
@@ -0,0 +1,354 @@
# Orchestration parity declaration
Every `orchestration.*` RPC method has one section: what an agent caller gets, per agent kind (terminal, chat) and location. `config/scripts/static-analysis/orchestration-parity/check-orchestration-parity-declarations.mjs` fails CI when a method has no section, a section names no registered method, or a section misses a kind and location. Sections describe the code as it is; a change in behaviour updates its section.
- **Local**: the caller runs on the Orca that serves the method.
- **Paired**: the caller's CLI runs the command on a paired Orca (`--environment`).
- **SSH/WSL**: the caller runs in an SSH or WSL workspace of the serving Orca.
Each line is `supported` (or `supported: <note>`), ``refused `<code>`: <reason>``, or `n/a: <reason>`. A method whose answer is the same for both kinds everywhere may give it once, as `All`.
## `orchestration.ask`
- Terminal · Local: supported: inside a supervised Dispatch
- Chat · Local: supported: inside a supervised Dispatch
- Terminal · Paired: refused `dispatch_inactive`: the paired Orca has no Dispatch for this caller
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported: inside a supervised Dispatch
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.callerShow`
- Terminal · Local: supported: no session, so it answers no caller
- Chat · Local: supported: names the live chat session
- Terminal · Paired: supported: the paired Orca knows no session for this caller
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported: no session, so it answers no caller
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.check`
- Terminal · Local: supported
- Chat · Local: supported: refused `session_caller_not_live` while the chat is released
- Terminal · Paired: refused `stable_pane_required`: the mailbox lives on the caller's own Orca
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.crewSubscribe`
- All: n/a: the Orca app and phone call it; no agent command
## `orchestration.dispatch`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: runs on the paired Orca, which records a caller it cannot reach
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.dispatchShow`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: reads the paired Orca's own records
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.federationAck`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.federationAttachStart`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.federationFleetSnapshot`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.federationImport`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.federationPull`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.federationRead`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.federationReadOutput`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.federationRelease`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.federationRetain`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.federationShow`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.federationStop`
- All: n/a: a home Orca calls it on its paired Orca; no agent command
## `orchestration.gateCreate`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: runs on the paired Orca, which records a caller it cannot reach
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.gateList`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: reads the paired Orca's own records
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.gateResolve`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: runs on the paired Orca, which records a caller it cannot reach
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.inbox`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: lists the paired Orca's mail, not the caller's
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.partyLocation`
- All: n/a: the Orca app and phone call it; no agent command
## `orchestration.partyOpen`
- All: n/a: the Orca app and phone call it; no agent command
## `orchestration.reply`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: the reply stays on the paired Orca and never reaches the caller
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.requestShow`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: reads the paired Orca's own records
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.reset`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: resets the paired Orca's orchestration state
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.run`
- All: refused `orchestration_migration_required`: retired; use `run-create` and `run-use`
## `orchestration.runCreate`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: runs on the paired Orca, which records a caller it cannot reach
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.runCurrent`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: reads the paired Orca's own records
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.runList`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: reads the paired Orca's own records
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.runShow`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: reads the paired Orca's own records
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.runStop`
- All: refused `orchestration_migration_required`: retired; use `run-create` and `run-use`
## `orchestration.runUse`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: runs on the paired Orca, which records a caller it cannot reach
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.send`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: the paired Orca stores a sender it cannot reach, so replies never come back
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.sessionAddress`
- All: n/a: the Orca app and phone call it; no agent command
## `orchestration.taskCreate`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: runs on the paired Orca, which records a caller it cannot reach
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.taskList`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: reads the paired Orca's own records
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.taskUpdate`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: runs on the paired Orca, which records a caller it cannot reach
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.workerAbandon`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: acts on the paired Orca's own workers
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.workerAutoClose`
- All: n/a: the Orca app and phone call it; no agent command
## `orchestration.workerChatTouch`
- All: n/a: the Orca app and phone call it; no agent command
## `orchestration.workerKeepOpen`
- All: n/a: the Orca app and phone call it; no agent command
## `orchestration.workerList`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: reads the paired Orca's own records
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.workerRead`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: acts on the paired Orca's own workers
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.workerRelease`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: acts on the paired Orca's own workers
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.workerRetain`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: acts on the paired Orca's own workers
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.workerShow`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: acts on the paired Orca's own workers
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.workerStart`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: `--on` starts it from the caller's own Orca and reports come home
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca; `--on` starts it from the caller's own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.workerStop`
- Terminal · Local: supported
- Chat · Local: supported
- Terminal · Paired: supported: acts on the paired Orca's own workers
- Chat · Paired: refused `session_caller_host_boundary`: a session id names a caller only on its own Orca
- Terminal · SSH/WSL: supported
- Chat · SSH/WSL: refused `session_caller_host_boundary`: chat agents do not run in SSH or WSL
## `orchestration.workerTerminalUserInput`
- All: n/a: the Orca app and phone call it; no agent command