orcasynth 1.4.1 → 1.4.4

package/dist/advisor/mcpConfig.js

@@ -0,0 +1,26 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Write the per-program MCP config into the advisor session's cwd so the spawned CLI auto-connects
+ *  to Orca's MCP server. Each CLI has its own config schema — claude reads `.mcp.json`, opencode reads
+ *  `opencode.json`, codex reads a TOML config. The schemas are version-sensitive: VERIFY each against
+ *  the installed CLI version's docs. The `orca api` CLI verb is the always-available fallback, so an
+ *  imperfect MCP wiring for one program degrades gracefully rather than removing the advisor's reach. */
+export function writeMcpConfig(program, cwd, token, mcpUrl) {
+    const auth = `Bearer ${token}`;
+    if (program.startsWith('claude')) {
+        writeFileSync(join(cwd, '.mcp.json'), JSON.stringify({
+            mcpServers: { orca: { type: 'http', url: mcpUrl, headers: { Authorization: auth } } },
+        }, null, 2));
+    }
+    else if (program.startsWith('opencode')) {
+        writeFileSync(join(cwd, 'opencode.json'), JSON.stringify({
+            $schema: 'https://opencode.ai/config.json',
+            mcp: { orca: { type: 'remote', url: mcpUrl, headers: { Authorization: auth }, enabled: true } },
+        }, null, 2));
+    }
+    else if (program.startsWith('codex')) {
+        // Codex reads MCP servers from its TOML config. Written project-local; VERIFY the exact key/path
+        // (and whether the installed codex needs a `--config`/`-c` flag to pick this up) for the version.
+        writeFileSync(join(cwd, '.codex-mcp.toml'), `[mcp_servers.orca]\nurl = "${mcpUrl}"\nbearer_token = "${token}"\n`);
+    }
+}

package/dist/advisor/service.js

@@ -0,0 +1,74 @@
+import { resolveExecutor } from '../overseer/routing.js';
+import { render } from '../prompts/index.js';
+import { logger } from '../shared/logger.js';
+const log = logger('advisor');
+/** Per-user advisor lifecycle: a persistent `orca-advisor-<userId>` agent session that controls Orca
+ *  on the user's behalf with a full-scope token. Chosen exec is remembered and auto-started on login. */
+export class AdvisorService {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    session(userId) { return `orca-advisor-${userId}`; }
+    /** An exec must be globally allowed AND (for a restricted non-admin) on the user's own allow-list. */
+    execAllowed(userId, exec) {
+        const u = this.d.users.get(userId);
+        if (!u)
+            return false;
+        if (!this.d.config.get().allowedExecs.includes(exec))
+            return false;
+        if (u.is_admin || u.allowed_execs.length === 0)
+            return true;
+        return u.allowed_execs.includes(exec);
+    }
+    async status(userId) {
+        const u = this.d.users.get(userId);
+        const name = this.session(userId);
+        const running = (await this.d.tmux.list()).includes(name);
+        return { running, exec: u?.advisor_exec ?? '', session: running ? name : null };
+    }
+    async start(userId, exec) {
+        if (!this.execAllowed(userId, exec))
+            throw new Error('exec not allowed for user');
+        const name = this.session(userId);
+        if ((await this.d.tmux.list()).includes(name))
+            return { session: name }; // already live — idempotent
+        this.d.users.setAdvisorExec(userId, exec); // remember the choice for autostart
+        const spec = resolveExecutor([`exec:${exec}`], this.d.fallback);
+        const token = this.d.users.ensureAdvisorToken(userId); // full-scope, reused across restarts
+        const cwd = this.d.advisorDir(userId);
+        await this.d.prepareMcp?.(spec.program, cwd, token, this.d.url);
+        const u = this.d.users.get(userId);
+        const rawPrompt = render('advisor', { userName: u.name || u.username });
+        // agentName `advisor-<id>` → SpawnService names the tmux session `orca-advisor-<id>`. The full
+        // advisor token overrides the daemon's agent service token via extraEnv, so the advisor acts with
+        // the user's own rights. The cwd is a neutral per-user dir, not a project checkout.
+        await this.d.spawn.launch({
+            projectId: this.d.projectId ?? 0,
+            projectPath: cwd,
+            taskId: name,
+            agentName: `advisor-${userId}`,
+            spec,
+            rawPrompt,
+            extraEnv: { ORCA_TOKEN: token, ORCA_URL: this.d.url },
+        });
+        log.info(`advisor started for user ${userId} (${spec.program}/${spec.model})`);
+        return { session: name };
+    }
+    async stop(userId) {
+        await this.d.tmux.kill(this.session(userId));
+    }
+    /** Bring the user's advisor back up after login, if they set one up and left autostart on. Never
+     *  throws — a spawn failure must not block the login response. */
+    async ensureOnLogin(userId) {
+        const u = this.d.users.get(userId);
+        if (!u || !u.advisor_exec || !u.advisor_autostart)
+            return;
+        try {
+            await this.start(userId, u.advisor_exec);
+        }
+        catch (e) {
+            log.error(`advisor autostart failed for user ${userId}`, e);
+        }
+    }
+}

package/dist/api/server.js

@@ -2,11 +2,11 @@ import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { writeFileSync, readFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
-import { randomBytes, createHmac, timingSafeEqual } from 'node:crypto';
+import { createHmac, timingSafeEqual } from 'node:crypto';
 import { hermesStatus, installHermesPlugin } from '../integrations/hermesInstall.js';
 import { detectClis } from '../integrations/cliDetection.js';
 import { readTaskUsage } from '../integrations/usage/index.js';
-import { listProjectFiles, readProjectFile, writeProjectFile, readProjectBytes, createProjectFile, createProjectDir, deleteProjectEntry, renameProjectEntry, copyProjectEntry, projectFileAtHead, projectFileDiff, projectCommitDiff, projectCommitFiles, projectCommitFileDiff, projectCommitLog, projectChangedFiles, projectWorkingDiff, projectReviewDiff } from '../integrations/projectFiles.js';
+import { listProjectFiles, readProjectFile, writeProjectFile, readProjectBytes, createProjectFile, createProjectDir, deleteProjectEntry, renameProjectEntry, copyProjectEntry, projectFileAtHead, projectFileDiff, projectCommitDiff, projectCommitFiles, projectCommitFileDiff, projectCommitLog, projectChangedFiles, projectWorkingDiff, projectReviewDiff, isProjectImage } from '../integrations/projectFiles.js';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { streamSSE } from 'hono/streaming';
@@ -21,7 +21,9 @@ import { RelayClient } from '../inference/client.js';
 import { uniqueName } from '../daemon/uniqueName.js';
 import { assembleMissionDetail } from '../store/missionDetail.js';
 import { authMiddleware } from './auth.js';
+import { handleMcpRequest } from '../mcp/server.js';
 import { logger } from '../shared/logger.js';
+import { shortId } from '../shared/id.js';
 /** How many times an L3 mission auto-re-spawns a phase that the post-done review rejected before it
  *  gives up and escalates to a human. Mirrors the stuck detector's `maxRelaunch` (2) so the two
  *  bounded-retry loops behave consistently. */
@@ -36,6 +38,8 @@ const ORCA_VERSION = (() => {
         return '0.0.0';
     }
 })();
+/** Port the daemon listens on — the MCP route reaches back into this same daemon's REST API at it. */
+const ORCA_PORT = Number(process.env.ORCA_PORT ?? 4400);
 export function createServer(d) {
     const log = logger('api');
     // Core reasoning stores are optional in deps for back-compat with existing call sites/tests; the
@@ -107,6 +111,12 @@ export function createServer(d) {
                 const p = c.req.path;
                 if (!GATED.some((g) => p === g || p.startsWith(g + '/')))
                     return next();
+                // An advisor session is per-user, not project-scoped: its access is governed by ownership in
+                // the route's own sessionAccessible check, so the project gate must not pre-empt it (the user
+                // need not be assigned to the daemon's project to reach their own advisor).
+                const sess = p.match(/^\/sessions\/([^/]+)/);
+                if (sess?.[1] && classifySession(decodeURIComponent(sess[1])).role === 'advisor')
+                    return next();
                 if (users.count() === 0)
                     return next(); // setup mode — no users to gate yet
                 const u = c.get('user');
@@ -148,7 +158,9 @@ export function createServer(d) {
             if (!user)
                 return c.json({ error: 'invalid credentials' }, 401);
             loginHits.delete(ip); // a valid login clears the counter so an earlier typo streak can't lock the user out
-            return c.json({ token: users.issueToken(user.id), user });
+            const token = users.issueToken(user.id);
+            void d.advisor?.ensureOnLogin(user.id); // fire-and-forget: bring the user's advisor back up; never block login
+            return c.json({ token, user });
         });
         app.post('/auth/logout', (c) => { const t = c.get('token'); if (t)
             users.revokeToken(t); return c.json({ ok: true }); });
@@ -427,6 +439,14 @@ export function createServer(d) {
         if (!d.userProjects || !d.users)
             return true; // open / single-user mode — no tenancy boundary
         const u = c.get('user');
+        // An advisor session belongs to exactly one user: only its owner (or an admin) may reach it, and
+        // never via an agent-scoped token. It has no task row, so the project check below can't apply.
+        const info = classifySession(name);
+        if (info.role === 'advisor') {
+            if (c.get('tokenScope') === 'agent')
+                return false;
+            return !!u && (u.id === info.userId || d.userProjects.isAdmin(u.id));
+        }
         // Admin sees every session — but NOT via an agent-scoped token (it's owned by the admin user yet
         // must stay confined to its working set; fall through to the project check below).
         if (c.get('tokenScope') !== 'agent' && u && d.userProjects.isAdmin(u.id))
@@ -468,7 +488,7 @@ export function createServer(d) {
     function persistPlan(job) {
         const path = pathFor(job.projectId);
         const allowedExecs = d.config.get().allowedExecs;
-        const newId = () => `${basename(path)}-${randomBytes(4).toString('hex')}`;
+        const newId = () => shortId(basename(path));
         const epicId = job.epicId ?? newId();
         let epic = d.tasks.get(epicId);
         if (!epic) {
@@ -573,7 +593,8 @@ export function createServer(d) {
                 return c.json({ error: 'forbidden' }, 403);
         }
         const id = Number(c.req.param('id'));
-        if (!d.projects.get(id))
+        const cur = d.projects.get(id);
+        if (!cur)
             return c.json({ error: 'project not found' }, 404);
         const b = await c.req.json();
         const patch = {};
@@ -581,6 +602,13 @@ export function createServer(d) {
             patch.path = b.path.trim();
         if (typeof b.notes === 'string')
             patch.notes = b.notes;
+        // Icon is a project-relative image path. '' clears it; anything else must resolve to a real image
+        // file inside the project root (guards against path traversal / pointing at a non-image).
+        if (typeof b.icon === 'string') {
+            if (b.icon !== '' && !isProjectImage(cur.path, b.icon))
+                return c.json({ error: 'invalid icon path' }, 400);
+            patch.icon = b.icon;
+        }
         return c.json(d.projects.update(id, patch));
     });
     // Remove a project from orca entirely: cascades to its tasks, missions, agents and access grants
@@ -930,7 +958,7 @@ export function createServer(d) {
         const target = resolveTarget(c, b.project_id);
         if ('error' in target)
             return c.json({ error: target.error }, target.status);
-        const id = b.id ?? `${basename(target.project.path)}-${randomBytes(4).toString('hex')}`;
+        const id = b.id ?? shortId(basename(target.project.path));
         const created = d.tasks.create({ id, project_id: target.project.id, title: b.title, type: b.type, priority: b.priority, description: b.description, scheduled_at: b.scheduled_at, autostart: b.autostart });
         if (Array.isArray(b.deps))
             d.tasks.setDeps(created.id, b.deps);
@@ -1373,6 +1401,18 @@ export function createServer(d) {
         await d.tmux.sendKeys(c.req.param('name'), keys);
         return c.json({ ok: true });
     });
+    app.post('/sessions/:name/input', async (c) => {
+        // Raw interactive input: the xterm `onData` bytes (printable chars, control codes, ESC sequences)
+        // are forwarded verbatim to the pane via `send-keys -l`, so the advisor terminal behaves like a
+        // real one. `-l` + `--` (in the driver) make a leading '-' safe, so no flag-token validation here.
+        if (!sessionAccessible(c, c.req.param('name')))
+            return c.json({ error: 'forbidden' }, 403);
+        const { data } = await c.req.json().catch(() => ({}));
+        if (typeof data !== 'string' || data.length === 0)
+            return c.json({ error: 'data must be a non-empty string' }, 400);
+        await d.tmux.sendRaw(c.req.param('name'), data);
+        return c.json({ ok: true });
+    });
     app.post('/sessions/:name/resize', async (c) => {
         if (!sessionAccessible(c, c.req.param('name')))
             return c.json({ error: 'forbidden' }, 403);
@@ -1415,6 +1455,45 @@ export function createServer(d) {
             clear();
         });
     });
+    // Per-user advisor lifecycle. Full-scope (non-agent) callers only — a spawned agent must not be able
+    // to start/stop a human's advisor. Each acts on the caller's own session (`orca-advisor-<userId>`).
+    app.get('/advisor/status', async (c) => {
+        if (!d.advisor)
+            return c.json({ running: false, exec: '', session: null });
+        if (c.get('tokenScope') === 'agent')
+            return c.json({ error: 'forbidden' }, 403);
+        return c.json(await d.advisor.status(c.get('user').id));
+    });
+    app.post('/advisor/start', async (c) => {
+        if (!d.advisor)
+            return c.json({ error: 'advisor unavailable' }, 503);
+        if (c.get('tokenScope') === 'agent')
+            return c.json({ error: 'forbidden' }, 403);
+        const { exec } = await c.req.json().catch(() => ({}));
+        if (typeof exec !== 'string' || !exec)
+            return c.json({ error: 'exec required' }, 400);
+        try {
+            return c.json(await d.advisor.start(c.get('user').id, exec), 201);
+        }
+        catch (e) {
+            return c.json({ error: e.message }, 403);
+        } // exec not allowed for the user
+    });
+    app.post('/advisor/stop', async (c) => {
+        if (!d.advisor)
+            return c.json({ ok: true });
+        if (c.get('tokenScope') === 'agent')
+            return c.json({ error: 'forbidden' }, 403);
+        await d.advisor.stop(c.get('user').id);
+        return c.json({ ok: true });
+    });
+    // MCP endpoint: the advisor agent connects here to control Orca with native tools. Each request is
+    // handled statelessly with the toolset bound to the caller's token, and every tool delegates to the
+    // same `callOrcaApi` core as the `orca api` CLI verb — so a new REST endpoint needs zero edits here.
+    app.all('/mcp', async (c) => {
+        const token = c.get('token');
+        return handleMcpRequest(c.req.raw, { url: `http://localhost:${ORCA_PORT}`, token });
+    });
     app.get('/missions', c => {
         const allowed = accessibleProjects(c);
         const live = d.missions.live();

package/dist/cli/commands.js

@@ -1,5 +1,31 @@
 import { start as realStart, stop as realStop, status as realStatus } from './launcher.js';
 import { update as realUpdate } from './update.js';
+/** `orca api <METHOD> <path> [jsonBody]` — generic authenticated REST passthrough. Reads
+ *  ORCA_URL/ORCA_TOKEN from the env the daemon injects into every spawned agent, so an agent can
+ *  drive ANY endpoint without a per-endpoint CLI command (and a new endpoint needs zero CLI edits).
+ *  Injectable for tests; returns a process exit code. */
+export async function runApiCommand(args, env, deps) {
+    const [method, path, rawBody] = args;
+    if (!method || !path) {
+        deps.err('usage: orca api <METHOD> <path> [jsonBody]');
+        return 2;
+    }
+    let body;
+    if (rawBody !== undefined) {
+        try {
+            body = JSON.parse(rawBody);
+        }
+        catch {
+            deps.err('api: body must be valid JSON');
+            return 2;
+        }
+    }
+    const url = env.ORCA_URL ?? 'http://localhost:4400';
+    const token = env.ORCA_TOKEN ?? '';
+    const res = await deps.call(method, path, body, { url, token });
+    deps.out(res.data !== undefined ? JSON.stringify(res.data, null, 2) : res.text);
+    return res.ok ? 0 : 1;
+}
 export function defaultLifecycleDeps(version) {
     return {
         version,

package/dist/cli/index.js

@@ -4,7 +4,8 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { OrcaClient } from './client.js';
-import { defaultLifecycleDeps, runLifecycle } from './commands.js';
+import { defaultLifecycleDeps, runLifecycle, runApiCommand } from './commands.js';
+import { callOrcaApi } from '../shared/apiClient.js';
 import { menu } from './menu.js';
 const BASE = process.env.ORCA_URL ?? 'http://localhost:4400';
 const USAGE = "usage: orca [command] [options]  —  run `orca --help` for the full command list";
@@ -35,6 +36,7 @@ TASKS
                                     --outcome ok|fail         record the outcome
 
 AGENT-FACING                      (invoked by running agents — rarely needed by hand)
+  api <METHOD> <path> [body]      generic authenticated REST call (needs ORCA_URL/ORCA_TOKEN)
   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>
@@ -49,7 +51,7 @@ 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. */
-const API_COMMANDS = new Set(['ls', 'ready', 'sessions', 'close', 'plan', 'overseer']);
+const API_COMMANDS = new Set(['ls', 'ready', 'sessions', 'close', 'plan', 'overseer', 'api']);
 /** True only for verbs that need the daemon API up — the gate for ensureDaemon's auto-spawn. */
 export function needsDaemon(cmd) {
     return cmd !== undefined && API_COMMANDS.has(cmd);
@@ -102,6 +104,11 @@ export async function run(argv, c, env) {
         case 'sessions':
             console.log(JSON.stringify(await c.sessions(), null, 2));
             break;
+        case 'api': {
+            const code = await runApiCommand(argv.slice(1), env, { call: callOrcaApi, out: (s) => console.log(s), err: (s) => console.error(s) });
+            process.exit(code);
+            break;
+        }
         case 'close': {
             if (!arg) {
                 console.error('usage: orca close <taskId> [--summary "<text>"] [--outcome ok|fail]');

package/dist/daemon/bootstrap.js

@@ -27,9 +27,12 @@ import { UserProjectStore } from '../store/userProjectStore.js';
 import { RealGitReader } from '../git/gitReader.js';
 import { uniqueName } from './uniqueName.js';
 import { logger } from '../shared/logger.js';
+import { AdvisorService } from '../advisor/service.js';
+import { writeMcpConfig } from '../advisor/mcpConfig.js';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
 const log = logger('daemon');
 /** Build the overseer-model prompt that turns a finished mission's phase results into a short,
  *  human-readable Czech summary shown on the epic in the dashboard. Kept terse so the relay returns
@@ -226,7 +229,17 @@ export function buildApp(opts) {
     // Per-process secret for short-lived signed avatar URLs (finding W2) — keeps the long-lived session
     // token out of <img> src query strings. Rotates on restart; links live ~5 min, so that's harmless.
     const avatarSecret = randomBytes(32).toString('hex');
-    const app = createServer({ tasks, readiness, missions, engine, spawn, tmux, bus, events, agents, project: opts.project, fallback: { program: 'claude-code', model: 'sonnet' }, clock: new SystemClock(), config, users, projects, userProjects, git, avatarsDir, avatarSecret, planJobs, decisionQueue, pilot });
+    // Per-user advisor: a persistent assistant session controlling Orca on the user's behalf. Its cwd
+    // is a neutral per-user dir (alongside the DB, NOT a project checkout) so the per-program MCP config
+    // never pollutes a repo. Disabled for the in-memory DB (tests build their own AdvisorService).
+    const mcpUrl = `${orcaCli.url}/mcp`; // the daemon hosts the MCP server on its own /mcp route
+    const advisor = opts.dbPath === ':memory:' ? undefined : new AdvisorService({
+        spawn, tmux, users, config, fallback: { program: 'claude-code', model: 'sonnet' },
+        projectId: opts.project.id, url: orcaCli.url,
+        advisorDir: (id) => { const p = join(dirname(opts.dbPath), 'advisor', String(id)); mkdirSync(p, { recursive: true }); return p; },
+        prepareMcp: (program, cwd, token) => writeMcpConfig(program, cwd, token, mcpUrl),
+    });
+    const app = createServer({ tasks, readiness, missions, engine, spawn, tmux, bus, events, agents, project: opts.project, fallback: { program: 'claude-code', model: 'sonnet' }, clock: new SystemClock(), config, users, projects, userProjects, git, avatarsDir, avatarSecret, planJobs, decisionQueue, pilot, advisor });
     // Root-cause recovery: after a daemon crash/restart, tasks left 'in_progress' whose tmux
     // session is gone are zombies — revert them to 'open' so they can be picked up again. No grace
     // or relaunch counter here: a restart isn't an agent death, so it shouldn't spend the budget.

package/dist/integrations/projectFiles.js

@@ -40,6 +40,22 @@ function safe(root, rel, forWrite = false) {
         throw new Error('path outside project');
     return abs;
 }
+// Image extensions a project icon may point at. Matches what `/raw` serves and what the picker shows.
+const IMAGE_EXT = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'ico', 'bmp', 'avif']);
+/** True when `rel` resolves to a regular image file strictly inside the project root — used to validate
+ *  a chosen project icon before persisting it. Never throws: a traversal/symlink escape, a missing
+ *  file, a directory or a non-image extension all return false. */
+export function isProjectImage(root, rel) {
+    if (!IMAGE_EXT.has((rel.split('.').pop() ?? '').toLowerCase()))
+        return false;
+    try {
+        const abs = safe(root, rel);
+        return statSync(abs).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 /** Flat list of a project's files and directories (relative paths), skipping VCS/build dirs. */
 export function listProjectFiles(root, maxDepth = 8) {
     const r = resolve(root);

package/dist/integrations/usage/claude.js

@@ -1,6 +1,7 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { EMPTY_USAGE, SESSION_MATCH_SKEW_MS } from './types.js';
+import { EMPTY_USAGE } from './types.js';
+import { pickNthSession } from './walk.js';
 /** claude-code stores one JSONL transcript per session under
  *  ~/.claude/projects/<encoded-cwd>/<sessionUuid>.jsonl, where each assistant event carries
  *  `message.usage`. Pick the session that started when this spawn ran and sum its usage.
@@ -10,24 +11,23 @@ export function claudeUsage(home, dir, sinceMs, nth = 0) {
     const projDir = join(home, '.claude', 'projects', dir.replace(/[/._]/g, '-'));
     if (!existsSync(projDir))
         return null;
-    // Transcripts started at/after the spawn window, ordered by start; `nth` picks one so
-    // concurrent agents in the same project map to distinct sessions instead of colliding.
+    // Transcripts that carry a start time; `pickNthSession` keeps those in the spawn window,
+    // orders by start, and picks the nth so concurrent agents map to distinct sessions.
     const sessions = [];
     for (const name of readdirSync(projDir)) {
         if (!name.endsWith('.jsonl'))
             continue;
         const p = join(projDir, name);
         const start = firstEventMs(p);
-        if (start == null || start < sinceMs - SESSION_MATCH_SKEW_MS)
+        if (start == null)
             continue;
         sessions.push({ path: p, start });
     }
-    sessions.sort((a, b) => a.start - b.start);
-    const best = sessions[nth];
+    const best = pickNthSession(sessions, sinceMs, nth);
     if (!best)
         return null;
     const u = { ...EMPTY_USAGE };
-    for (const line of readFileSync(best.path, 'utf8').split('\n')) {
+    for (const line of readFileSync(best, 'utf8').split('\n')) {
         if (!line.trim())
             continue;
         try {

package/dist/integrations/usage/codex.js

@@ -1,8 +1,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { basename } from 'node:path';
-import { SESSION_MATCH_SKEW_MS } from './types.js';
-import { walkFiles } from './walk.js';
+import { pickNthSession, walkFiles } from './walk.js';
 /** codex stores one rollout JSONL per session under ~/.codex/sessions/<Y>/<M>/<D>/rollout-*.jsonl,
  *  carrying a cumulative `total_token_usage` object. Pick the rollout started when this spawn ran
  *  and read its final cumulative usage. codex does not record cost (costUsd stays null). */
@@ -11,21 +10,20 @@ export function codexUsage(home, _dir, sinceMs, nth = 0) {
     if (!existsSync(root))
         return null;
     // codex rollouts aren't dir-scoped on disk, so concurrent codex agents can only be
-    // disambiguated by start order; `nth` picks the rank-th rollout in the spawn window.
+    // disambiguated by start order; `pickNthSession` picks the rank-th rollout in the spawn window.
     const sessions = [];
     for (const f of walkFiles(root)) {
         if (!basename(f).startsWith('rollout-') || !f.endsWith('.jsonl'))
             continue;
         const start = rolloutStartMs(f);
-        if (start == null || start < sinceMs - SESSION_MATCH_SKEW_MS)
+        if (start == null)
             continue;
         sessions.push({ path: f, start });
     }
-    sessions.sort((a, b) => a.start - b.start);
-    const best = sessions[nth];
+    const best = pickNthSession(sessions, sinceMs, nth);
     if (!best)
         return null;
-    return finalUsage(best.path);
+    return finalUsage(best);
 }
 /** Start time of a rollout: its first event's ISO timestamp, else the timestamp in its filename. */
 function rolloutStartMs(path) {

package/dist/integrations/usage/index.js

@@ -4,13 +4,7 @@ import { opencodeUsage } from './opencode.js';
 import { claudeUsage } from './claude.js';
 import { codexUsage } from './codex.js';
 import { SESSION_MATCH_SKEW_MS } from './types.js';
-/** Parse a SQLite ("2026-06-19 11:13:20", UTC) or ISO timestamp to epoch ms. */
-function parseTs(ts) {
-    if (!ts)
-        return 0;
-    const ms = Date.parse(ts.includes('T') ? ts : ts.replace(' ', 'T') + 'Z');
-    return Number.isNaN(ms) ? 0 : ms;
-}
+import { parseDbTs } from '../../shared/time.js';
 /** The precise spawn time (epoch ms) the agent launched, from the `started:<ms>` label — this is
  *  sub-second and reflects real spawn order, unlike whole-second `created_at` (set at row insert).
  *  Falls back to created_at for tasks launched before this label existed. */
@@ -21,7 +15,7 @@ function startedMs(task) {
         if (Number.isFinite(ms))
             return ms;
     }
-    return parseTs(task.created_at);
+    return parseDbTs(task.created_at);
 }
 /** The resolved CLI program + model for a task (program normalized: 'opencode' | 'claude-code' |
  *  'codex' | …). */

package/dist/integrations/usage/walk.js

@@ -1,5 +1,19 @@
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { SESSION_MATCH_SKEW_MS } from './types.js';
+/**
+ * From a set of session candidates `{path, start}`, pick the nth one that started within the spawn
+ * window (`start >= sinceMs - SESSION_MATCH_SKEW_MS`), ordered by start time. `nth` lets concurrent
+ * agents in the same project map to distinct sessions instead of colliding. Returns null when no
+ * candidate qualifies or `nth` is out of range. Single source of truth for the claude/codex
+ * session-select logic (opencode selects via SQL).
+ */
+export function pickNthSession(candidates, sinceMs, nth) {
+    const inWindow = candidates
+        .filter((c) => c.start >= sinceMs - SESSION_MATCH_SKEW_MS)
+        .sort((a, b) => a.start - b.start);
+    return inWindow[nth]?.path ?? null;
+}
 /** Recursively yield every file path under `dir` (depth-limited). Returns [] if dir is missing. */
 export function walkFiles(dir, maxDepth = 4) {
     const out = [];

package/dist/mcp/server.js

@@ -0,0 +1,34 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { z } from 'zod';
+import { makeOrcaTools } from './tools.js';
+/** Build an MCP server exposing the Orca toolset bound to one caller's token. Every tool delegates to
+ *  `makeOrcaTools` → the shared `callOrcaApi` core, so there is no request logic here to maintain. */
+function createOrcaMcpServer(deps) {
+    const tools = makeOrcaTools(deps);
+    const server = new McpServer({ name: 'orca', version: '1.0.0' });
+    const text = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data ?? null, null, 2) }] });
+    server.registerTool('orca_request', {
+        description: 'Call any Orca REST endpoint (full control). Generic escape hatch — every endpoint works without a dedicated tool.',
+        inputSchema: { method: z.string(), path: z.string(), body: z.unknown().optional() },
+    }, async (a) => text(await tools.orca_request({ method: a.method, path: a.path, body: a.body })));
+    server.registerTool('orca_tasks', { description: 'List all tasks.', inputSchema: {} }, async () => text(await tools.orca_tasks()));
+    server.registerTool('orca_create_task', {
+        description: 'Create a task.',
+        inputSchema: { title: z.string(), project_id: z.number().optional(), description: z.string().optional() },
+    }, async (a) => text(await tools.orca_create_task(a)));
+    server.registerTool('orca_plan', {
+        description: 'Plan a goal into an epic with phases (autopilot).',
+        inputSchema: { goal: z.string(), project_id: z.number().optional() },
+    }, async (a) => text(await tools.orca_plan(a)));
+    server.registerTool('orca_sessions', { description: 'List live agent sessions.', inputSchema: {} }, async () => text(await tools.orca_sessions()));
+    return server;
+}
+/** Stateless HTTP handler: a fresh server + transport per request, with the toolset bound to the
+ *  request's bearer token, so each advisor connection acts with exactly its user's rights. */
+export async function handleMcpRequest(req, deps) {
+    const server = createOrcaMcpServer(deps);
+    const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    await server.connect(transport);
+    return transport.handleRequest(req);
+}

package/dist/mcp/tools.js

@@ -0,0 +1,17 @@
+import { callOrcaApi } from '../shared/apiClient.js';
+export function makeOrcaTools(d) {
+    const call = d.call ?? callOrcaApi;
+    const req = async (method, path, body) => {
+        const r = await call(method, path, body, { url: d.url, token: d.token });
+        if (!r.ok)
+            throw new Error(`orca ${r.status}: ${r.text || JSON.stringify(r.data)}`);
+        return r.data;
+    };
+    return {
+        orca_request: (a) => req(a.method, a.path, a.body),
+        orca_tasks: () => req('GET', '/tasks'),
+        orca_create_task: (a) => req('POST', '/tasks', a),
+        orca_plan: (a) => req('POST', '/tasks/plan', a),
+        orca_sessions: () => req('GET', '/sessions'),
+    };
+}

package/dist/overseer/sessionInfo.js

@@ -1,13 +1,19 @@
 const ORCA = 'orca-';
 const OVERSEER = 'overseer-';
 const PILOT = 'pilot-';
+const ADVISOR = 'advisor-';
 /** Classify a live session name into its role + identity. Mirrors the spawn-time conventions:
- *  overseer → `orca-overseer-<missionId>`, pilot → `orca-pilot-<name>`, worker → `orca-<name>`. */
+ *  overseer → `orca-overseer-<missionId>`, pilot → `orca-pilot-<name>`, advisor → `orca-advisor-<userId>`,
+ *  worker → `orca-<name>`. */
 export function classifySession(name) {
     const bare = name.startsWith(ORCA) ? name.slice(ORCA.length) : name;
     if (bare.startsWith(OVERSEER))
         return { name, role: 'overseer', agent: '', missionId: bare.slice(OVERSEER.length) };
     if (bare.startsWith(PILOT))
         return { name, role: 'pilot', agent: bare.slice(PILOT.length) };
+    if (bare.startsWith(ADVISOR)) {
+        const userId = Number(bare.slice(ADVISOR.length));
+        return { name, role: 'advisor', agent: '', userId: Number.isInteger(userId) ? userId : undefined };
+    }
     return { name, role: 'agent', agent: bare };
 }

package/dist/overseer/stuckDetector.js

@@ -1,3 +1,4 @@
+import { parseDbTs } from '../shared/time.js';
 const agentOf = (t) => t.labels.find((l) => l.startsWith('agent:'))?.slice('agent:'.length) ?? null;
 /** Epoch-ms the task's agent was spawned: the precise `started:<ms>` label, falling back to the
  *  whole-second `created_at` (stored UTC). Null only for a task that has neither. */
@@ -8,16 +9,9 @@ function startedOf(t) {
         if (Number.isFinite(n))
             return n;
     }
-    if (t.created_at) {
-        // SQLite `datetime('now')` is `YYYY-MM-DD HH:MM:SS` (UTC, no zone) → normalise to ISO + 'Z'. But
-        // if it already carries a zone (a 'T' separator implies an ISO string), parse it as-is — appending
-        // a second 'Z' would yield `...ZZ` and a NaN. Brittle-format guard for #54.
-        const iso = t.created_at.includes('T') ? t.created_at : t.created_at.replace(' ', 'T') + 'Z';
-        const n = Date.parse(iso);
-        if (Number.isFinite(n))
-            return n;
-    }
-    return null;
+    // SQLite `datetime('now')` is `YYYY-MM-DD HH:MM:SS` (UTC, no zone); parseDbTs normalises it and
+    // returns 0 for an absent/unparseable value, which maps back to null (no usable start time).
+    return parseDbTs(t.created_at) || null;
 }
 /** in_progress tasks whose agent tmux session is no longer live — the agent exited or crashed
  *  (no `orca close`), or the task never got an agent label. Shared by the startup zombie