orcasynth 1.3.0 → 1.4.0

package/README.md

@@ -4,13 +4,14 @@
 
 **Control autonomous coding agents — without losing control.**
 
-Plan work, launch isolated coding agents, watch every session, and step in
-before risky changes reach your codebase.
+Plan the work, launch isolated coding agents, watch every session live, and step in
+before a risky change ever reaches your codebase.
 
 `Plan · Dispatch · Observe · Intervene`
 
-Orcasynth is a self-hosted daemon that runs coding agents (Claude Code, OpenCode,
-Codex) in isolated `tmux` sessions — with a REST API, a CLI, and a real-time web UI.
+Orcasynth is a self-hosted daemon that orchestrates autonomous coding agents
+(Claude Code, OpenCode, Codex) in isolated `tmux` sessions — with a REST API, a CLI,
+and a real-time Next.js web UI. No SaaS, no lock-in: your machine, your agents, your code.
 
 [![CI](https://github.com/dragocz1995/orcasynth/actions/workflows/ci.yml/badge.svg)](https://github.com/dragocz1995/orcasynth/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
@@ -21,32 +22,51 @@ Codex) in isolated `tmux` sessions — with a REST API, a CLI, and a real-time w
 
 ---
 
+## Why Orcasynth
+
+Coding agents are powerful but messy to run at scale: one terminal per agent, no shared
+view of what's happening, and no safety net when an agent decides to `rm -rf` something.
+
+Orcasynth puts a control plane in front of them. Hand it a goal and it plans the work,
+spawns the right agent for each step in its own `tmux` session, streams every keystroke to
+your browser, and gates dangerous actions behind a human when you want it to. When you
+trust it more, you turn the autonomy up; when you trust it less, you turn it down.
+
 ## What it does
 
-- **Autopilot planning.** Give the Pilot a goal; an LLM decomposes it into ordered
-  phases, names an agent per phase, and chains them by dependency.
-- **Per-model descriptions & per-phase model selection.** Write a capability
-  description for each model in Settings; flip on "Autopilot picks the model" and the
-  planner chooses the best-suited model for each phase from those descriptions —
-  validated against your allow-list, falling back to the default on anything invalid.
-- **Agent-agnostic spawning.** Runs Claude Code, OpenCode, or Codex in `tmux`,
-  configurable per task. Each agent gets the task context and closes its own task when done.
-- **Autonomy levels (L0–L3).** The overseer auto-clears safe permission prompts at
-  higher autonomy and escalates destructive or uncertain ones to a human.
-- **Live web UI.** Tasks, a kanban board + calendar, missions with progress, a timeline,
-  and live `tmux` session previews with one-click agent intervention. EN/CS i18n built in.
-- **Self-healing.** A stuck-session detector revives agents that die without closing out,
-  and live token/cost usage is shown per run.
-- **Multi-user RBAC.** Per-project assignments, per-user model allow-lists, profiles & avatars,
-  and a first-run onboarding that needs no login until the first admin is created.
-- **Self-hosted & lightweight.** A single SQLite-backed daemon (Hono) + a Next.js front end.
-  No external services required beyond your LLM provider.
+- **Autopilot planning.** Give the Pilot a goal and an LLM decomposes it into ordered
+  phases, chains them by dependency, and can name an agent per phase. Phases only start
+  once the phases they depend on are done.
+- **Per-model descriptions & per-phase model selection.** Write a capability description
+  for each model in Settings, flip on "Autopilot picks the model," and the planner chooses
+  the best-suited model for each phase from those descriptions — validated against your
+  allow-list, falling back to the default on anything invalid.
+- **Agent-agnostic spawning.** Runs Claude Code, OpenCode, or Codex in isolated `tmux`
+  sessions, configurable per task. Each agent receives the task context and closes its own
+  task when it's done.
+- **Autonomy levels (L0–L3).** Choose how much rope each mission gets — from
+  **L0 · Recommend** (plan only, nothing runs until you approve) through **L1 · Assist**
+  and **L2 · Pilot** to **L3 · Auto** (full autonomy). The overseer's decision engine
+  auto-clears agent permission prompts when confidence is high and the action is safe, and
+  escalates anything destructive or uncertain to a human. Operations like `rm -rf`, dropping
+  tables, force-pushes, or touching `.env` always escalate, whatever the level.
+- **Live web UI with one-click intervention.** Tasks, a kanban board with a calendar,
+  missions with phase progress, a timeline, and real-time `tmux` session previews you can
+  jump into and take over. Full EN/CS internationalization built in.
+- **Self-healing.** A stuck-session detector revives agents that die without closing out
+  (and blocks the task after repeated failures instead of crash-looping). A janitor sweeps
+  up finished sessions. Live token and cost usage is shown per run.
+- **Multi-user RBAC.** Admin and member roles, per-project assignments, per-user model
+  allow-lists, profiles and avatars, and a first-run onboarding that needs no login until
+  the first admin is created.
+- **Self-hosted & lightweight.** A single SQLite-backed daemon (Hono + SSE) plus a Next.js
+  front end. No external services required beyond your own LLM provider.
 
 ## Screenshots
 
 <div align="center">
 
-**Dashboard** — live agents, active missions, autopilot spotlight, and recent outcomes at a glance.
+**Dashboard** — live agents, active missions, the autopilot spotlight, and recent outcomes at a glance.
 
 ![Dashboard](docs/screenshots/dashboard.png)
 
@@ -54,7 +74,7 @@ Codex) in isolated `tmux` sessions — with a REST API, a CLI, and a real-time w
 
 | | |
 |---|---|
-| **Tasks** — list + detail with live agent output and token usage. ![Tasks](docs/screenshots/tasks.png) | **Kanban** — open / in-progress / blocked / closed, with mission progress. ![Kanban](docs/screenshots/kanban.png) |
+| **Tasks** — list + detail with live agent output and token usage. ![Tasks](docs/screenshots/tasks.png) | **Kanban** — open / in-progress / blocked / closed, with mission progress and a calendar. ![Kanban](docs/screenshots/kanban.png) |
 | **Missions** — phase graph and task flow for an autopilot run (folded into Tasks). ![Missions](docs/screenshots/missions.png) | **Timeline** — a live activity feed across tasks, missions, and signals. ![Timeline](docs/screenshots/timeline.png) |
 | **Sessions** — real-time `tmux` agent previews with one-click intervention. ![Sessions](docs/screenshots/sessions.png) | **Terminal** — the full agent TUI, including human-in-the-loop approvals. ![Terminal](docs/screenshots/terminal.png) |
 | **Projects** — a built-in Monaco editor with the project file tree. ![Projects editor](docs/screenshots/projects-editor.png) | **Settings** — model presets & descriptions, providers, autopilot, and defaults. ![Settings](docs/screenshots/settings.png) |
@@ -86,8 +106,8 @@ orca update     # update to the latest release from npm
 ```
 
 Requires **Node ≥ 22** and **tmux**. On first run, `orca` walks you through a quick
-setup — admin account, LLM provider + API key, default model. Your data (config, the
-SQLite database and logs) lives in **`~/.config/orca/`** and survives every update.
+setup — admin account, LLM provider + API key, and a default model. Your data (config,
+the SQLite database, and logs) lives in **`~/.config/orca/`** and survives every update.
 
 Then open <http://localhost:4500> and sign in.
 
@@ -111,12 +131,36 @@ npm start -- -p 4500
 Open <http://localhost:4500> and sign in. Configure your LLM provider and models in
 **Settings → Autopilot / Models**, then create a task or engage an autopilot mission.
 
-The CLI auto-starts the daemon if it isn't running:
+The CLI talks to the daemon over the REST API and auto-starts it if it isn't running:
 
 ```bash
-node dist/cli/index.js ls        # list tasks
-node dist/cli/index.js close <id>
+node dist/cli/index.js ls          # list tasks
+node dist/cli/index.js close <id>  # close a task
+```
+
+## How it works
+
 ```
+        goal
+         │
+         ▼
+   ┌───────────┐   phases + deps    ┌─────────────┐   spawn    ┌──────────────┐
+   │   Pilot   │ ─────────────────► │   Overseer  │ ─────────► │  Agent (tmux) │
+   │ (planner) │                    │ (scheduler, │            │ Claude Code / │
+   └───────────┘                    │  decisions) │ ◄───────── │ OpenCode /    │
+                                    └─────────────┘   signals  │ Codex         │
+                                          │                    └──────────────┘
+                                          │ escalate
+                                          ▼
+                                    human-in-the-loop
+```
+
+The **Pilot** decomposes a goal into a dependency-ordered set of phases. The **Overseer**
+schedules ready phases, spawns the right **Agent** for each one in its own `tmux` session,
+and watches the output. A deriver reads each session and emits signals — `working`,
+`needs_input`, `complete`. When an agent hits a permission prompt, the decision engine
+either clears it automatically (high confidence, non-destructive, within the mission's
+autonomy level) or escalates it to a human.
 
 ## Architecture
 
@@ -125,12 +169,14 @@ is a thin client over the REST API + SSE event stream.
 
 | Layer | What lives there |
 |-------|------------------|
-| `src/store` | SQLite stores (tasks, missions, agents, config, users) |
-| `src/overseer` | mission engine, scheduler, planner, decision engine, janitor |
+| `src/store` | SQLite stores (tasks, missions, agents, config, users, projects, events) via `better-sqlite3` |
+| `src/overseer` | mission engine, planner, scheduler, decision engine, stuck-detector, janitor |
 | `src/spawn` · `src/tmux` | agent command building + tmux driver |
-| `src/deriver` | derives signals from agent output (working / needs-input / complete) |
-| `src/api` | Hono REST server + SSE bus |
-| `web/modules` | feature modules (tasks, kanban, missions, sessions, timeline, …) |
+| `src/deriver` | derives signals from agent output (`working` / `needs_input` / `complete`) |
+| `src/integrations` | per-executor token/cost usage extraction |
+| `src/api` | Hono REST server + SSE event bus |
+| `src/cli` · `src/daemon` | the `orca` CLI and the daemon entrypoint |
+| `web/modules` | feature modules (tasks, kanban, sessions, timeline, projects, settings, …) |
 
 See [`docs/`](./docs) for the [API](./docs/API.md), [architecture](./docs/ARCHITECTURE.md),
 [concepts](./docs/CONCEPTS.md), [CLI](./docs/CLI.md), and [development](./docs/DEVELOPMENT.md) guides.
@@ -158,3 +204,5 @@ Star the repo if you find it useful — it helps others discover the project.
 ## License
 
 [MIT](./LICENSE)
+</content>
+</invoke>

package/dist/cli/index.js

@@ -7,7 +7,45 @@ import { OrcaClient } from './client.js';
 import { defaultLifecycleDeps, runLifecycle } from './commands.js';
 import { menu } from './menu.js';
 const BASE = process.env.ORCA_URL ?? 'http://localhost:4400';
-const USAGE = 'usage: orca [menu] | install | <up|down|status|update> | <ls|ready|sessions|close|plan submit|overseer poll|overseer decide>';
+const USAGE = "usage: orca [command] [options]  —  run `orca --help` for the full command list";
+/** The full, grouped help shown for `orca --help`. Kept as a function so the version is interpolated. */
+function helpText(version) {
+    return `🐋 orca ${version} — control plane for autonomous coding agents
+
+USAGE
+  orca                            open the interactive launcher menu (in a terminal)
+  orca <command> [options]
+
+SETUP
+  install                         provision orca as a service: systemd units, a reverse proxy
+                                  and the first admin (run as root). See \`orca install --help\`.
+
+SERVICE
+  up                              start the daemon (:4400) and web UI (:4500) in the background
+  down                            stop the daemon and web UI
+  status                          show which services are running and healthy
+  update                          update to the latest npm release and restart in place
+
+TASKS
+  ls                              list all tasks (JSON)
+  ready                           list tasks ready to run (JSON)
+  sessions                        list live agent sessions (JSON)
+  close <id> [options]            close a task
+                                    --summary "<text>"        closing note
+                                    --outcome ok|fail         record the outcome
+
+AGENT-FACING                      (invoked by running agents — rarely needed by hand)
+  plan submit --phases '<json>'   submit an autopilot plan        (needs ORCA_PLAN_JOB)
+  overseer poll                   wait for the next decision       (needs ORCA_MISSION)
+  overseer decide --id <id> …     resolve a decision: --approve | --escalate | --choice <optionId>
+                                    [--confidence <0..1>] [--rationale "<text>"]
+
+OPTIONS
+  -h, --help                      show this help
+  -v, --version                   print the version
+
+Docs & issues: https://github.com/dragocz1995/orcasynth`;
+}
 /** Commands that talk to the daemon API — only these justify auto-starting it. Everything else
  *  (help, unknown verbs) must NOT spawn a daemon: a stray detached daemon squats the port and starves
  *  the systemd-managed one into a restart loop. */
@@ -160,7 +198,7 @@ async function main() {
     }
     // Help / bare non-TTY invocation: print usage and stop. Must NOT fall through to ensureDaemon.
     if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
-        console.log(USAGE);
+        console.log(helpText(version));
         return;
     }
     if (argv[0] === '--version' || argv[0] === '-v') {

package/dist/cli/install/index.js

@@ -7,7 +7,7 @@ import { ensureServiceUser, userHome } from './serviceUser.js';
 import { detectAgentClis, installCommand } from './agentClis.js';
 import { daemonUnit, webUnit } from './systemdUnits.js';
 import { detectProxy, nginxVhost, apacheVhost, certbotCommand } from './proxy.js';
-import { applySetup, buildSetupPlan, isFirstRun } from '../setup.js';
+import { applySetup, buildSetupPlan, defaultExecForCli, isFirstRun } from '../setup.js';
 import { runSetupWizard } from '../setupWizard.js';
 import { INSTALL_INFO_PATH, serializeInstallInfo } from '../installInfo.js';
 const DAEMON_PORT = Number(process.env.ORCA_PORT ?? 4400);
@@ -237,8 +237,12 @@ async function planFromArgs(r, args) {
             : agentsRaw.split(',').map((s) => s.trim()).filter(Boolean);
     const adminUser = flag(args, '--admin-user');
     const adminPass = flag(args, '--admin-pass');
+    // `--autopilot-cli <claude|opencode|codex>` runs autopilot through an agent CLI (no API key);
+    // otherwise the --llm-* flags configure the hosted-API engine.
+    const autopilotCli = flag(args, '--autopilot-cli');
+    const pilotExec = autopilotCli ? defaultExecForCli(autopilotCli, flag(args, '--autopilot-model')) : undefined;
     const admin = adminUser && adminPass
-        ? { username: adminUser, password: adminPass, apiUrl: flag(args, '--llm-url') ?? 'https://api.openai.com/v1', apiKey: flag(args, '--llm-key') ?? '', model: flag(args, '--llm-model') ?? 'gpt-4o-mini' }
+        ? { username: adminUser, password: adminPass, pilotExec, apiUrl: flag(args, '--llm-url') ?? 'https://api.openai.com/v1', apiKey: flag(args, '--llm-key') ?? '', model: flag(args, '--llm-model') ?? 'gpt-4o-mini' }
         : null;
     return {
         installTmux: !args.includes('--no-tmux'),
@@ -378,7 +382,40 @@ function planSummary(plan) {
 }
 /** `orca install` — provision a fresh Debian/Ubuntu box. Run as root. Pass `--unattended` (with flags)
  *  for a non-interactive install; otherwise an interactive wizard collects every answer. */
+const INSTALL_HELP = `🐋 orca install — provision a fresh Debian/Ubuntu box as an orca service (run as root)
+
+USAGE
+  orca install                    interactive wizard (recommended)
+  orca install --unattended [options]
+
+OPTIONS
+  --unattended                    run non-interactively from the flags below
+  --user <name>                   service user that runs the agents          (default: orca)
+  --agents <list>                 agent CLIs to install: all | none | claude,opencode,codex
+  --no-tmux                       skip installing tmux
+
+  Deployment (pick one; default is localhost):
+  --domain <host>                 serve on a domain behind a reverse proxy (+ Let's Encrypt HTTPS)
+  --ip <addr> | --host <addr>     serve directly on the public IP and port (no proxy)
+  --localhost                     bind to localhost only
+  --proxy <nginx|apache|none>     reverse proxy to configure for --domain
+  --email <addr>                  contact email for Let's Encrypt renewal notices
+
+  First admin + autopilot:
+  --admin-user <name>             create the first admin account
+  --admin-pass <pass>             admin password
+  --autopilot-cli <cli>           run autopilot through an agent CLI (claude|opencode|codex) — no API key
+  --autopilot-model <spec>        model for --autopilot-cli opencode (e.g. anthropic/claude-sonnet-4-5)
+  --llm-url <url>                 hosted-API engine: base URL    (default: https://api.openai.com/v1)
+  --llm-key <key>                 hosted-API engine: API key
+  --llm-model <name>              hosted-API engine: model       (default: gpt-4o-mini)
+
+  -h, --help                      show this help`;
 export async function install(args = []) {
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(INSTALL_HELP);
+        return;
+    }
     const r = realRunner();
     const unattended = args.includes('--unattended');
     p.intro(`🐋 orca install${unattended ? ' (unattended)' : ''}`);

package/dist/cli/menu.js

@@ -1,12 +1,13 @@
-import { spawn, execFile } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import * as p from '@clack/prompts';
 import { status } from './launcher.js';
 import { defaultLifecycleDeps, formatStatus, runLifecycle } from './commands.js';
 import { isFirstRun } from './setup.js';
 import { runSetupWizard } from './setupWizard.js';
 import { readInstallInfo } from './installInfo.js';
+import { update } from './update.js';
+import { SERVICES, runCmd, systemctl, servicesActive } from './systemd.js';
 const BASE = process.env.ORCA_URL ?? 'http://localhost:4400';
-const SERVICES = ['orca-daemon', 'orca-web'];
 /** Open a URL in the user's default browser, cross-platform, fire-and-forget. */
 function openUrl(url) {
     const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
@@ -16,26 +17,6 @@ function openUrl(url) {
     }
     catch { /* headless box — ignore */ }
 }
-/** Run a command, resolving its stdout/exit code (never rejects). */
-function run(cmd, args) {
-    return new Promise((resolve) => {
-        execFile(cmd, args, (err, stdout) => {
-            const code = err && typeof err.code === 'number' ? err.code : err ? 1 : 0;
-            resolve({ code, stdout: stdout?.toString() ?? '' });
-        });
-    });
-}
-/** systemctl, transparently via sudo when we aren't root (so a non-root operator still works). */
-async function systemctl(...args) {
-    const asRoot = typeof process.getuid === 'function' && process.getuid() === 0;
-    return asRoot ? run('systemctl', args) : run('sudo', ['systemctl', ...args]);
-}
-/** Whether both ORCA units report active. */
-async function servicesActive() {
-    const r = await systemctl('is-active', ...SERVICES);
-    const states = r.stdout.trim().split('\n');
-    return states.length > 0 && states.every((s) => s.trim() === 'active');
-}
 /** Launcher menu for a systemd-provisioned box (`orca install`): drives the units via systemctl and
  *  shows the real public URL the operator chose — never spawns a second, port-conflicting daemon. */
 async function systemdMenu(info, version) {
@@ -68,20 +49,21 @@ async function systemdMenu(info, version) {
             continue;
         }
         if (action === 'logs') {
-            const r = await run('journalctl', ['-u', 'orca-daemon', '-n', '20', '--no-pager']);
+            const r = await runCmd('journalctl', ['-u', 'orca-daemon', '-n', '20', '--no-pager']);
             p.note(r.stdout.trim() || '(no logs — try: journalctl -u orca-daemon)', 'orca-daemon');
             continue;
         }
         if (action === 'update') {
             const s = p.spinner();
-            s.start('Updating orcasynth…');
-            const upd = await run('npm', ['install', '-g', 'orcasynth@latest']);
-            if (upd.code !== 0) {
-                s.stop('Update failed — see npm output above.');
-                continue;
+            s.start('Checking npm for a newer version…');
+            try {
+                // Shared updater: self-locating npm --prefix + systemd-aware restart (same path as `orca update`).
+                const r = await update(process.env, { current: version });
+                s.stop(r.updated ? `Updated ${r.from} → ${r.to} and restarted.` : `Already on the latest version (${r.to}).`);
+            }
+            catch (e) {
+                s.stop(`Update failed: ${e.message}`);
             }
-            await systemctl('restart', ...SERVICES);
-            s.stop('Updated and restarted.');
             continue;
         }
         // start | stop | restart

package/dist/cli/setup.js

@@ -1,6 +1,20 @@
 /** First-run wizard logic, kept pure/injectable so the menu shell stays thin. All persistence goes
  *  through the daemon's own HTTP API (POST /users, POST /auth/login, PUT /config) — the single source
  *  of truth — rather than writing the DB directly, so there is no parallel config path. */
+/** Autopilot CLIs that can drive missions without an API key, in recommended order. Mirrors the agent
+ *  programs the daemon knows about (src/shared/execs.ts). */
+const AUTOPILOT_CLIS = ['claude', 'opencode', 'codex'];
+/** Default autopilot exec spec for a detected agent CLI — a well-formed `<prefix>:<model>` spec that
+ *  resolveExecutor routes to the right program (so it passes the daemon's allow-list guard without
+ *  needing a custom model entry). opencode is provider-agnostic, so its model comes from the caller. */
+export function defaultExecForCli(cli, opencodeModel = 'anthropic/claude-sonnet-4-5') {
+    switch (cli) {
+        case 'claude': return 'claude:sonnet';
+        case 'codex': return 'codex:gpt-5.5';
+        case 'opencode': return `opencode:${opencodeModel}`;
+        default: return '';
+    }
+}
 /** True when the daemon has no users yet — the open setup window during which the wizard may create
  *  the first admin and save the provider/key. */
 export async function isFirstRun(fetchFn, base) {
@@ -8,33 +22,58 @@ export async function isFirstRun(fetchFn, base) {
     const body = await r.json();
     return body.needsSetup === true;
 }
-/** Pure mapper: wizard answers → the API payloads. A blank apiKey is omitted so we never overwrite an
- *  existing key with an empty string. */
+/** Pure mapper: wizard answers → the API payloads. With a pilotExec the autopilot runs through an
+ *  agent CLI (same exec for pilot and overseer) and no API key is sent; otherwise a blank apiKey is
+ *  omitted so we never overwrite an existing key with an empty string. */
 export function buildSetupPlan(a) {
-    const autopilot = { model: a.model, apiUrl: a.apiUrl };
-    if (a.apiKey)
+    const autopilot = a.pilotExec
+        ? { pilotExec: a.pilotExec, overseerExec: a.pilotExec }
+        : { model: a.model, apiUrl: a.apiUrl };
+    if (!a.pilotExec && a.apiKey)
         autopilot.apiKey = a.apiKey;
     return { user: { username: a.username, password: a.password }, config: { autopilot } };
 }
-/** Create the admin (open during setup), log in for a bearer token, then save the config. The first
- *  user created is automatically the admin (userStore.create), so the authenticated PUT /config
- *  succeeds once users exist. */
-export async function applySetup(fetchFn, base, plan) {
-    const post = (path, body, token) => fetchFn(`${base}${path}`, {
-        method: path === '/config' ? 'PUT' : 'POST',
-        headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
-        body: JSON.stringify(body),
+/** Create the admin (open during setup) and log in for a bearer token. The first user created is
+ *  automatically the admin (userStore.create), so subsequent authenticated calls succeed. */
+export async function createAdmin(fetchFn, base, user) {
+    const post = (path, body) => fetchFn(`${base}${path}`, {
+        method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),
     });
-    const created = await post('/users', plan.user);
+    const created = await post('/users', user);
     if (!created.ok)
         throw new Error(`setup: creating the admin failed (${created.status})`);
-    const login = await post('/auth/login', plan.user);
+    const login = await post('/auth/login', user);
     if (!login.ok)
         throw new Error(`setup: login failed (${login.status})`);
     const { token } = await login.json();
     if (!token)
         throw new Error('setup: login returned no token');
-    const cfg = await post('/config', plan.config, token);
-    if (!cfg.ok)
-        throw new Error(`setup: saving config failed (${cfg.status})`);
+    return token;
+}
+/** Persist the config patch with an admin bearer token. */
+export async function saveConfig(fetchFn, base, token, config) {
+    const r = await fetchFn(`${base}/config`, {
+        method: 'PUT', headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: JSON.stringify(config),
+    });
+    if (!r.ok)
+        throw new Error(`setup: saving config failed (${r.status})`);
+}
+/** Ask the daemon which autopilot-capable agent CLIs are installed & functional for the SERVICE USER
+ *  (the daemon detects on its own PATH, which is who actually runs the agents), returned in
+ *  recommended order. Requires an admin bearer token. Returns [] on any failure — callers fall back
+ *  to the API-key engine. */
+export async function fetchAvailableClis(fetchFn, base, token) {
+    const r = await fetchFn(`${base}/integrations/cli-status`, { headers: { authorization: `Bearer ${token}` } });
+    if (!r.ok)
+        return [];
+    const body = await r.json();
+    const functional = new Set((body.tools ?? []).filter((t) => t.functional).map((t) => t.name));
+    return AUTOPILOT_CLIS.filter((c) => functional.has(c));
+}
+/** Create the admin, log in for a bearer token, then save the config. Kept for the non-interactive
+ *  (unattended) install path; the interactive wizard creates the admin earlier so it can probe the
+ *  daemon for installed CLIs before choosing the autopilot engine. */
+export async function applySetup(fetchFn, base, plan) {
+    const token = await createAdmin(fetchFn, base, plan.user);
+    await saveConfig(fetchFn, base, token, plan.config);
 }

package/dist/cli/setupWizard.js

@@ -1,20 +1,12 @@
 import * as p from '@clack/prompts';
-import { buildSetupPlan, applySetup } from './setup.js';
+import { createAdmin, saveConfig, fetchAvailableClis, defaultExecForCli } from './setup.js';
 const PROVIDERS = {
     OpenAI: 'https://api.openai.com/v1',
     Anthropic: 'https://api.anthropic.com/v1',
 };
-/** Interactive first-run wizard: collect admin creds + LLM provider/key/model and persist them
- *  through the daemon API at `base`. Shared by the launcher menu and `orca install`. Returns the
- *  admin credentials on success (so the caller can run a login smoke test), or null if the operator
- *  cancelled. Throws only on an API failure (caller reports it). */
-export async function runSetupWizard(base) {
-    const username = await p.text({ message: 'Admin username', initialValue: 'admin' });
-    if (p.isCancel(username))
-        return null;
-    const password = await p.password({ message: 'Admin password', validate: (v) => ((v ?? '').length < 4 ? 'At least 4 characters' : undefined) });
-    if (p.isCancel(password))
-        return null;
+const CLI_LABEL = { claude: 'Claude Code', opencode: 'OpenCode', codex: 'Codex' };
+/** Configure the hosted-API (relay) autopilot engine: provider URL + key + default model. */
+async function chooseApiEngine() {
     const choice = await p.select({
         message: 'LLM provider',
         options: [...Object.keys(PROVIDERS).map((k) => ({ value: k, label: k })), { value: 'Custom', label: 'Custom (enter URL)' }],
@@ -34,16 +26,73 @@ export async function runSetupWizard(base) {
     const model = await p.text({ message: 'Default model', initialValue: 'gpt-4o-mini' });
     if (p.isCancel(model))
         return null;
-    const answers = { username, password, apiUrl, apiKey, model };
+    const patch = { model, apiUrl };
+    if (apiKey)
+        patch.apiKey = apiKey;
+    return patch;
+}
+/** Pick the autopilot engine: an installed agent CLI (no API key — recommended) or a hosted API key.
+ *  `clis` are the agent CLIs the daemon found installed for the service user, in recommended order. */
+async function chooseAutopilot(clis) {
+    const options = [
+        ...clis.map((c, i) => ({ value: `cli:${c}`, label: `${CLI_LABEL[c] ?? c} CLI`, hint: i === 0 ? 'no API key — recommended' : 'no API key' })),
+        { value: 'apikey', label: 'LLM API key', hint: clis.length ? 'use a hosted model via an API key' : 'recommended' },
+        { value: 'skip', label: 'Skip for now', hint: 'configure later in the web UI' },
+    ];
+    const choice = await p.select({ message: 'How should Autopilot plan and oversee missions?', options });
+    if (p.isCancel(choice) || choice === 'skip')
+        return null;
+    if (choice === 'apikey')
+        return chooseApiEngine();
+    const cli = choice.slice('cli:'.length);
+    // opencode is provider-agnostic — ask which model it should use (it must already be authenticated).
+    let opencodeModel;
+    if (cli === 'opencode') {
+        const m = await p.text({ message: 'OpenCode model for autopilot', placeholder: 'provider/model', initialValue: 'anthropic/claude-sonnet-4-5' });
+        if (p.isCancel(m))
+            return null;
+        opencodeModel = m.trim() || undefined;
+    }
+    const exec = defaultExecForCli(cli, opencodeModel);
+    return { pilotExec: exec, overseerExec: exec };
+}
+/** Interactive first-run wizard: create the admin, then let the operator pick the autopilot engine —
+ *  an installed agent CLI (no API key) or an LLM API key — and persist it through the daemon API at
+ *  `base`. The admin is created up front so the CLI-detection probe can authenticate (which engines
+ *  are available is only knowable as the service user). Shared by the launcher menu and `orca
+ *  install`. Returns the admin credentials on success (so the caller can run a login smoke test), or
+ *  null if the operator cancelled before any account was created. Throws only on an API failure. */
+export async function runSetupWizard(base) {
+    const username = await p.text({ message: 'Admin username', initialValue: 'admin' });
+    if (p.isCancel(username))
+        return null;
+    const password = await p.password({ message: 'Admin password', validate: (v) => ((v ?? '').length < 4 ? 'At least 4 characters' : undefined) });
+    if (p.isCancel(password))
+        return null;
     const s = p.spinner();
-    s.start('Saving…');
+    s.start('Creating admin…');
+    let token;
     try {
-        await applySetup(fetch, base, buildSetupPlan(answers));
+        token = await createAdmin(fetch, base, { username, password });
         s.stop('Admin account created.');
-        return { username, password };
     }
     catch (e) {
         s.stop(`Setup failed: ${e.message}`);
         throw e;
     }
+    const clis = await fetchAvailableClis(fetch, base, token);
+    const autopilot = await chooseAutopilot(clis);
+    if (autopilot) {
+        const s2 = p.spinner();
+        s2.start('Saving autopilot settings…');
+        try {
+            await saveConfig(fetch, base, token, { autopilot });
+            s2.stop(autopilot.pilotExec ? 'Autopilot will run through your agent CLI — no API key needed.' : 'Autopilot configured.');
+        }
+        catch (e) {
+            // The admin already exists and is usable; autopilot can be configured later in the web UI.
+            s2.stop(`Saving autopilot settings failed: ${e.message}`);
+        }
+    }
+    return { username, password };
 }

package/dist/cli/systemd.js

@@ -0,0 +1,24 @@
+import { execFile } from 'node:child_process';
+/** The two units `orca install` provisions. Shared so the menu and the updater drive the same names. */
+export const SERVICES = ['orca-daemon', 'orca-web'];
+/** Run a command, resolving its exit code + stdout (never rejects). */
+export function runCmd(cmd, args) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, (err, stdout) => {
+            const code = err && typeof err.code === 'number' ? err.code : err ? 1 : 0;
+            resolve({ code, stdout: stdout?.toString() ?? '' });
+        });
+    });
+}
+/** systemctl, transparently via sudo when we aren't root (so a non-root operator — e.g. the services'
+ *  own www-data with passwordless sudo — still manages the units). */
+export function systemctl(...args) {
+    const asRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+    return asRoot ? runCmd('systemctl', args) : runCmd('sudo', ['systemctl', ...args]);
+}
+/** Whether all ORCA units report active. */
+export async function servicesActive() {
+    const r = await systemctl('is-active', ...SERVICES);
+    const states = r.stdout.trim().split('\n');
+    return states.length > 0 && states.every((s) => s.trim() === 'active');
+}