stablyai/orca · error · RuntimeClientError

no_active_sender_terminal

no_active_sender_terminal

Error message

Could not determine the sender terminal for this orchestration command. Pass --from <terminal-handle> or run the command inside a live Orca terminal with ORCA_TERMINAL_HANDLE set.

What it means

Thrown by throwNoActiveSenderTerminal when the CLI cannot determine which Orca terminal is issuing a lifecycle/coordinator command. The sender identity is required because the runtime authorizes lifecycle operations (worker_done, heartbeat) and Run bindings against a concrete terminal handle. It fires either when getTerminalHandle throws no_active_terminal during implicit resolution (resolveImplicitOrchestrationSender, line 343) or directly in 'orchestration send' for worker_done/heartbeat messages lacking both --from and ORCA_TERMINAL_HANDLE (lines 559-566). The design intent (line 564 comment) is fail-closed: focus is not lifecycle authority, so an identity-less subprocess must not guess the worker.

Source

Thrown at src/cli/handlers/orchestration.ts:348

}

async function resolveImplicitOrchestrationSender(
  flags: Map<string, string | boolean>,
  cwd: string,
  client: Parameters<CommandHandler>[0]['client']
): Promise<string> {
  try {
    return await getTerminalHandle(flags, cwd, client)
  } catch (err) {
    if (!isNoActiveTerminalError(err)) {
      throw err
    }
    throwNoActiveSenderTerminal()
  }
}

function throwNoActiveSenderTerminal(): never {
  throw new RuntimeClientError(
    'no_active_sender_terminal',
    'Could not determine the sender terminal for this orchestration command. ' +
      'Pass --from <terminal-handle> or run the command inside a live Orca terminal with ORCA_TERMINAL_HANDLE set.'
  )
}

function isDevCliInvocation(): boolean {
  return (
    process.env.ORCA_DEV_CLI_INVOCATION === '1' ||
    (process.env.ORCA_USER_DATA_PATH?.includes('orca-dev') ?? false)
  )
}

function getOptionalPositiveIntegerValueFlag(
  flags: Map<string, string | boolean>,
  name: string
): number | undefined {
  if (!flags.has(name)) {

View on GitHub (pinned to 1136503c6a)

Solutions

  1. Pass an explicit --from <terminal-handle> on the command line.
  2. Run the command from inside a live Orca terminal so ORCA_TERMINAL_HANDLE is set in the environment.
  3. Export ORCA_TERMINAL_HANDLE in the calling environment (e.g. from a previously resolved handle) for headless use.
  4. Ensure ORCA_PANE_KEY is set if relying on pane-key remint fallback for the sender identity.

Example fix

// before
orca orchestration send --type worker_done --outcome succeeded --subject done
// after
orca orchestration send --type worker_done --outcome succeeded --subject done --from t_abc123
Defensive patterns

Strategy: try-catch

Validate before calling

function resolveSender(flags, env): string | undefined {
  return flags.get('from')
    ?? (env.ORCA_TERMINAL_HANDLE && env.ORCA_TERMINAL_HANDLE.length > 0 ? env.ORCA_TERMINAL_HANDLE : undefined)
}
const sender = resolveSender(flags, process.env)
if (!sender) { /* prompt user / export ORCA_TERMINAL_HANDLE / pass --from */ }

Type guard

function hasSenderIdentity(flags: Map<string, string | boolean>, env: NodeJS.ProcessEnv): boolean {
  const f = flags.get('from')
  return (typeof f === 'string' && f.length > 0) || (!!env.ORCA_TERMINAL_HANDLE && env.ORCA_TERMINAL_HANDLE.length > 0)
}

Try / catch

try {
  await runLifecycleSend(args)
} catch (err) {
  if (err instanceof RuntimeClientError && err.code === 'no_active_sender_terminal') {
    // re-resolve a live terminal handle and retry with --from
  } else { throw err }
}

Prevention

When it happens

Trigger: Running 'orchestration send --type worker_done' (or heartbeat) with no --from flag and no ORCA_TERMINAL_HANDLE in the environment; running run-create/run-use/dispatch/ask/gate/task commands outside a live Orca terminal when the active-terminal resolver also cannot find a pane. Also triggered after a pane-key remint leaves the env handle stale and no remint fallback resolves (line 226).

Common situations: Calling the CLI from a plain shell, cron job, or CI runner that was not launched inside an Orca terminal; ORCA_TERMINAL_HANDLE expired after the terminal was reminted; running over SSH where the handle env var was never exported; scripts that worked interactively but fail when daemonized.

Related errors

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/437151a8b6d63b41. Report an issue: GitHub.