{"record":{"id":"437151a8b6d63b41","repo":"stablyai/orca","slug":"no-active-sender-terminal","errorCode":"no_active_sender_terminal","errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/handlers/orchestration.ts","lineNumber":348,"sourceCode":"}\n\nasync function resolveImplicitOrchestrationSender(\n  flags: Map<string, string | boolean>,\n  cwd: string,\n  client: Parameters<CommandHandler>[0]['client']\n): Promise<string> {\n  try {\n    return await getTerminalHandle(flags, cwd, client)\n  } catch (err) {\n    if (!isNoActiveTerminalError(err)) {\n      throw err\n    }\n    throwNoActiveSenderTerminal()\n  }\n}\n\nfunction throwNoActiveSenderTerminal(): never {\n  throw new RuntimeClientError(\n    'no_active_sender_terminal',\n    'Could not determine the sender terminal for this orchestration command. ' +\n      'Pass --from <terminal-handle> or run the command inside a live Orca terminal with ORCA_TERMINAL_HANDLE set.'\n  )\n}\n\nfunction isDevCliInvocation(): boolean {\n  return (\n    process.env.ORCA_DEV_CLI_INVOCATION === '1' ||\n    (process.env.ORCA_USER_DATA_PATH?.includes('orca-dev') ?? false)\n  )\n}\n\nfunction getOptionalPositiveIntegerValueFlag(\n  flags: Map<string, string | boolean>,\n  name: string\n): number | undefined {\n  if (!flags.has(name)) {","sourceCodeStart":330,"sourceCodeEnd":366,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/handlers/orchestration.ts#L330-L366","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass an explicit --from <terminal-handle> on the command line.","Run the command from inside a live Orca terminal so ORCA_TERMINAL_HANDLE is set in the environment.","Export ORCA_TERMINAL_HANDLE in the calling environment (e.g. from a previously resolved handle) for headless use.","Ensure ORCA_PANE_KEY is set if relying on pane-key remint fallback for the sender identity."],"exampleFix":"// before\norca orchestration send --type worker_done --outcome succeeded --subject done\n// after\norca orchestration send --type worker_done --outcome succeeded --subject done --from t_abc123","handlingStrategy":"try-catch","validationCode":"function resolveSender(flags, env): string | undefined {\n  return flags.get('from')\n    ?? (env.ORCA_TERMINAL_HANDLE && env.ORCA_TERMINAL_HANDLE.length > 0 ? env.ORCA_TERMINAL_HANDLE : undefined)\n}\nconst sender = resolveSender(flags, process.env)\nif (!sender) { /* prompt user / export ORCA_TERMINAL_HANDLE / pass --from */ }","typeGuard":"function hasSenderIdentity(flags: Map<string, string | boolean>, env: NodeJS.ProcessEnv): boolean {\n  const f = flags.get('from')\n  return (typeof f === 'string' && f.length > 0) || (!!env.ORCA_TERMINAL_HANDLE && env.ORCA_TERMINAL_HANDLE.length > 0)\n}","tryCatchPattern":"try {\n  await runLifecycleSend(args)\n} catch (err) {\n  if (err instanceof RuntimeClientError && err.code === 'no_active_sender_terminal') {\n    // re-resolve a live terminal handle and retry with --from\n  } else { throw err }\n}","preventionTips":["Always run lifecycle commands inside a live Orca terminal.","Export ORCA_TERMINAL_HANDLE explicitly for headless/CI use.","Set ORCA_PANE_KEY to enable pane-key remint fallback.","For worker_done/heartbeat, pass --from explicitly rather than relying on focus."],"tags":["cli","terminal","env","orchestration","identity","lifecycle"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}