@repo-os/repoos 0.5.45

package/dist/server/agents.js

@@ -0,0 +1,4070 @@
+/**
+ * The agent runner: launches the repo's default coding agent against a task in
+ * its worktree, tracks running processes, and supports graceful pause.
+ *
+ * Zero runtime deps — `node:child_process` only. Everything here is best-effort:
+ * a missing CLI or a broken agent config must never crash the server or block
+ * an HTTP response, so spawns are async-fired and failures surface as events.
+ */
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { agentsForConfig, defaultMaxConcurrentAgents } from "../core/config.js";
+import { fileCommittedClean, currentBranch } from "../core/git.js";
+import { buildIndex } from "../core/indexer.js";
+import { parseTask, serializeTask, recordChange } from "../core/task.js";
+import { patchTaskFile } from "./write.js";
+import { stripAnsi } from "./done.js";
+import { getRepoOSDb } from "../core/db.js";
+import { listSkills } from "./routes/helpers.js";
+export const HANDOFF_READY_SIGNAL = "::repoos-handoff-ready::";
+/**
+ * The exact line a sandboxed agent emits to request ITS managed preview
+ * (#0121). Like the handoff signal, it is an output-only intent: the agent
+ * never touches localhost or picks a port — the runner binds it to the live
+ * run and the server starts/probes the preview on the agent's behalf.
+ */
+export const PREVIEW_REQUEST_SIGNAL = "::repoos-preview-request::";
+/**
+ * The transcript marker appended when a user interrupts an in-flight AI chat
+ * response. Shared so the runner and the CTO manager (and tests) never drift.
+ */
+export const INTERRUPTED_MARKER = "— response interrupted —";
+const now = () => new Date().toISOString();
+/** Hard cap on a session transcript (drop oldest lines beyond this). */
+const OUTPUT_CAP_BYTES = 256 * 1024;
+/** Path to the durable agent registry (0214). */
+function registryPath(cacheDir) {
+    return join(cacheDir, "agents.json");
+}
+/** Path to the pending-handoffs store (#0235). */
+function pendingHandoffsPath(cacheDir) {
+    return join(cacheDir, "pending-handoffs.json");
+}
+/** Read the pending handoff store; returns empty when missing or corrupted. */
+function readPendingHandoffs(cacheDir) {
+    try {
+        const raw = readFileSync(pendingHandoffsPath(cacheDir), "utf8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed.requests)) {
+            return {
+                requests: parsed.requests.filter((r) => typeof r.taskId === "string" &&
+                    typeof r.runId === "string" &&
+                    typeof r.branch === "string" &&
+                    typeof r.workdir === "string"),
+            };
+        }
+    }
+    catch {
+        /* missing or corrupt — start fresh */
+    }
+    return { requests: [] };
+}
+/** Persist the pending handoff store atomically (best-effort). */
+function writePendingHandoffs(cacheDir, store) {
+    try {
+        mkdirSync(cacheDir, { recursive: true });
+        const file = pendingHandoffsPath(cacheDir);
+        const temp = `${file}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+        try {
+            writeFileSync(temp, JSON.stringify(store, null, 2), "utf8");
+            renameSync(temp, file);
+        }
+        finally {
+            if (existsSync(temp))
+                unlinkSync(temp);
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Read the durable registry; returns empty when missing or corrupted. */
+function readRegistry(cacheDir) {
+    try {
+        const raw = readFileSync(registryPath(cacheDir), "utf8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed.entries)) {
+            return {
+                entries: parsed.entries.filter((e) => typeof e.taskId === "string" &&
+                    typeof e.pid === "number" &&
+                    typeof e.workdir === "string"),
+            };
+        }
+    }
+    catch {
+        /* missing or corrupt — start fresh */
+    }
+    return { entries: [] };
+}
+/** Persist the durable registry atomically (best-effort). */
+function writeRegistry(cacheDir, registry) {
+    try {
+        mkdirSync(cacheDir, { recursive: true });
+        const file = registryPath(cacheDir);
+        const temp = `${file}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+        try {
+            writeFileSync(temp, JSON.stringify(registry, null, 2), "utf8");
+            renameSync(temp, file);
+        }
+        finally {
+            if (existsSync(temp))
+                unlinkSync(temp);
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Default silence window before a still-running turn is flagged as possibly
+ * stalled (0080). Conservative on purpose: silence alone is never proof of a
+ * hang (the agent could just be thinking through a slow step), so this only
+ * fires a neutral "may be stalled" warning, never a definitive "it's dead."
+ * `AgentRunner`'s constructor accepts an override for tests.
+ */
+export const DEFAULT_STALL_TIMEOUT_MS = 90_000;
+/**
+ * Estimate cost from token count when the CLI doesn't report it explicitly.
+ * Uses rough pricing for common models: claude 3.5 sonnet $3/M input, $15/M output.
+ * This is a fallback when extractUsage yields no cost; never fabricates when
+ * the CLI provides no data at all.
+ */
+export function estimateCostUsd(tokens) {
+    if (!tokens || tokens < 1)
+        return undefined;
+    const avgCostPerToken = (3 + 15) / 2 / 1_000_000;
+    return Math.max(0.001, tokens * avgCostPerToken);
+}
+export function extractUsage(raw) {
+    const out = {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+            const obj = parsed;
+            const inputTokens = inputTokensFromObject(obj);
+            if (inputTokens !== undefined)
+                out.inputTokens = inputTokens;
+            const outputTokens = outputTokensFromObject(obj);
+            if (outputTokens !== undefined)
+                out.outputTokens = outputTokens;
+            const totalTokens = tokensFromObject(obj);
+            if (totalTokens !== undefined)
+                out.totalTokens = totalTokens;
+            const cost = costFromObject(obj);
+            if (cost !== undefined)
+                out.costUsd = cost;
+            const cache = cacheTokensFromObject(obj);
+            if (cache.cacheReadTokens !== undefined)
+                out.cacheReadTokens = cache.cacheReadTokens;
+            if (cache.cacheCreationTokens !== undefined)
+                out.cacheCreationTokens = cache.cacheCreationTokens;
+            const turns = turnsFromObject(obj);
+            if (turns !== undefined)
+                out.turns = turns;
+            // opencode emits one `step_finish` per model round-trip; its token/cost
+            // figures are that step's delta, never a running total — fold by SUM.
+            if (obj.type === "step_finish" || obj.type === "step-finish")
+                out.deltas = true;
+            // claude's terminal turn summary — authoritative for the whole turn.
+            if (obj.type === "result" && typeof obj.total_cost_usd === "number") {
+                out.authoritative = true;
+            }
+        }
+    }
+    catch {
+        /* not JSON — fall through to text patterns below */
+    }
+    if (out.totalTokens === undefined) {
+        const m = raw.match(/\btotal[_ ]tokens\b["'\s:=]+([\d,]+)/i) ?? raw.match(/\b([\d,]+)\s+tokens\b/i);
+        if (m) {
+            const n = Number(m[1].replace(/,/g, ""));
+            if (Number.isFinite(n))
+                out.totalTokens = n;
+        }
+    }
+    if (out.costUsd === undefined) {
+        const m = raw.match(/total cost[:\s]+\$?([\d.]+)/i) ?? raw.match(/\bcost_usd\b["'\s:=]+\$?([\d.]+)/i);
+        if (m) {
+            const n = Number(m[1]);
+            if (Number.isFinite(n))
+                out.costUsd = n;
+        }
+    }
+    // Kiro CLI emits a credits footer on stderr: " ▸ Credits: 0.15 • Time: 12s"
+    // Map credits → costUsd so the task panel shows the charge. Note: for Kiro
+    // sessions, costUsd holds credits (Kiro's billing unit), not US dollars.
+    if (out.costUsd === undefined) {
+        const m = raw.match(/▸\s*Credits:\s*([\d.]+)/i);
+        if (m) {
+            const n = Number(m[1]);
+            if (Number.isFinite(n))
+                out.costUsd = n;
+        }
+    }
+    return out;
+}
+/**
+ * Fold usage/cost found in a raw output line into a running total, clamped to
+ * never move backward (some CLIs report a running total, some reset per turn).
+ * Mirrors `AgentRunner.applyUsage` so one-shot roles aggregate the same way the
+ * streaming engineer runner does. Never fabricates a number — absent fields are
+ * simply left untouched.
+ */
+export function foldUsage(total, raw) {
+    const found = extractUsage(raw);
+    // Three fold modes:
+    //  - authoritative (claude `result`): overwrite — the turn's real total.
+    //  - deltas (opencode `step_finish`): SUM — each event is one round-trip.
+    //  - otherwise (codex/claude running totals): Math.max — count up, never
+    //    flicker down on a transient mid-stream figure.
+    const merge = (key) => {
+        const v = found[key];
+        if (v === undefined)
+            return;
+        total[key] = found.authoritative
+            ? v
+            : found.deltas
+                ? (total[key] ?? 0) + v
+                : Math.max(total[key] ?? 0, v);
+    };
+    merge("inputTokens");
+    merge("outputTokens");
+    merge("totalTokens");
+    merge("costUsd");
+    merge("cacheReadTokens");
+    merge("cacheCreationTokens");
+    // Turns are a per-event delta — always accumulate.
+    if (found.turns !== undefined)
+        total.turns = (total.turns ?? 0) + found.turns;
+}
+/**
+ * Classify the cost source for a recorded session (0230). Authoritative
+ * CLI-reported cost wins; Kiro is flagged as its own unit (credits), never
+ * passed off as USD. Callers that compute a token-based estimate (the engineer
+ * runner) set `costSource` to "estimate" themselves — this only reports whether
+ * a real CLI figure was present.
+ */
+export function usageCostSource(agent, usage) {
+    if (usage.costUsd)
+        return agent.cli === "kiro" ? "kiro-credits" : "extractUsage";
+    return "none";
+}
+/**
+ * Map a runner session key to the REAL task id it belongs to (0230). Engineer
+ * and review sessions are keyed by the task id directly. PM chats are keyed by
+ * a synthetic `pm-task-v2:<id>` id whose suffix is the actual task — attribute
+ * them under that real id so PM cost/tokens aggregate per-task. Non-task chats
+ * (guide) have no task and return null. Per-user PM sessions (0248) append
+ * `::<email>` after the task id; that suffix is stripped here too so cost
+ * attribution doesn't treat "<id>::<email>" as the task id.
+ */
+export function resolveSessionTaskId(taskKey) {
+    if (!taskKey)
+        return null;
+    // Board-level chat keys belong to no task — attribute them to nothing so
+    // they surface on the board panel only, never a task drawer (0331).
+    if (NON_TASK_SESSION_KEYS.has(taskKey.toLowerCase()))
+        return null;
+    // Per-task Debugger chats (`debugger:<taskId>`, #0337) are a separate role,
+    // not a task's engineering work — never attribute their cost/tokens to a task
+    // named "debugger:<id>" (which would otherwise surface as a phantom board task).
+    if (taskKey.startsWith("debugger:"))
+        return null;
+    // Each alternative has a strict literal prefix so nothing else is captured;
+    // covers the current `pm-task-v2:<id>` scheme (with or without a `::<email>`
+    // per-user suffix) and the legacy `pm-task:<id>` / `pm:<id>` forms, without
+    // mis-parsing their suffixes (0230 / review).
+    const pm = taskKey.match(/^pm-task-v2:([^:]+)(?:::.*)?$/i) ??
+        taskKey.match(/^pm-task:(.+)$/i) ??
+        taskKey.match(/^pm:(.+)$/i);
+    if (pm)
+        return pm[1] || null;
+    // Durable review sessions are keyed by `review:<taskId>` (0288); strip the
+    // prefix so any DB attribution lands on the real task.
+    if (/^review:/i.test(taskKey))
+        return taskKey.replace(/^review:/i, "") || null;
+    return taskKey;
+}
+/**
+ * Persistent session key for Ross's board-level chat. Must match the id the
+ * guide client subscribes to and persists under (RepoGuideChat.vue uses
+ * "repoos-guide"); a previous refactor drifted this to "__repoos-guide__",
+ * which hid the guide's running/stop state from the UI.
+ */
+export const REPO_GUIDE_SESSION_ID = "repoos-guide";
+/** Persistent session id for the Debugger's bug-paste conversation. */
+export const debuggerSessionId = "__repoos-debugger__";
+/**
+ * Runner session keys that are conversations with board-level roles rather
+ * than task-scoped work. `repoos-guide` is Ross's chat (REPO_GUIDE_SESSION_ID
+ * in routes/info.ts); `__repoos-guide__` is the key a previous refactor
+ * drifted to; `__repoos-debugger__` is the Debugger's chat (debuggerSessionId
+ * above).
+ */
+const NON_TASK_SESSION_KEYS = new Set([
+    REPO_GUIDE_SESSION_ID,
+    "__repoos-guide__",
+    debuggerSessionId,
+]);
+/** Exact agent-name → sessionType mappings for the built-in roles (0331). */
+const EXACT_ROLE_TYPES = {
+    ross: "guide",
+    guide: "guide",
+    "repoos guide": "guide",
+    "repoos-guide": "guide",
+    engineer: "engineer",
+    reviewer: "reviewer",
+    review: "reviewer",
+    pm: "pm",
+    cto: "cto",
+    debugger: "debugger",
+    "tech-debt": "tech-debt",
+    "tech debt": "tech-debt",
+};
+/**
+ * Classify a runner session into the role label the board's "AI usage — all
+ * roles" panel groups by (0331). Exact matches on the built-in role names win
+ * first: the legacy "RepoOS Guide" name used to be swallowed into "engineer"
+ * because an earlier `includes("repoos")` probe ran before the guide check —
+ * classify on what the agent IS, not on a substring an earlier rule grabbed.
+ * Unknown names fall through ordered substring probes (guide before the rest
+ * so "ross guide"-style hybrids still land right), then to "task" when the
+ * session is keyed to a task at all, "chat" when it is not.
+ */
+export function classifySessionType(agentName, taskKey) {
+    const name = (agentName ?? "").trim().toLowerCase();
+    const exact = EXACT_ROLE_TYPES[name];
+    if (exact)
+        return exact;
+    if (name.includes("guide") || name.includes("ross"))
+        return "guide";
+    if (name.includes("debugger"))
+        return "debugger";
+    if (name.includes("review"))
+        return "reviewer";
+    if (name.includes("engineer"))
+        return "engineer";
+    if (name.includes("pm"))
+        return "pm";
+    if (name.includes("cto"))
+        return "cto";
+    if (name.includes("tech"))
+        return "tech-debt";
+    return taskKey ? "task" : "chat";
+}
+/** Input tokens from a `usage`-shaped JSON object, or undefined if absent. */
+function inputTokensFromObject(obj) {
+    const usage = findUsage(obj);
+    if (usage && typeof usage.input_tokens === "number")
+        return usage.input_tokens;
+    return undefined;
+}
+/** Output tokens from a `usage`-shaped JSON object, or undefined if absent. */
+function outputTokensFromObject(obj) {
+    const usage = findUsage(obj);
+    if (usage && typeof usage.output_tokens === "number")
+        return usage.output_tokens;
+    return undefined;
+}
+/**
+ * Locate a `usage`-shaped block: top-level (codex `usage` events and claude's
+ * terminal `result`) or nested at `message.usage` (claude per-`assistant`
+ * events, 0109). Also recognizes opencode's `step_finish` shape, whose tokens
+ * live at `part.tokens.{total,input,output}` and cost at `part.cost` — a
+ * different field layout entirely, normalized here to the `input_tokens` /
+ * `output_tokens` / `total_tokens` / `cost_usd` names the callers expect.
+ */
+function findUsage(obj) {
+    if (obj.usage && typeof obj.usage === "object")
+        return obj.usage;
+    const msg = obj.message;
+    if (msg && typeof msg === "object") {
+        const m = msg;
+        if (m.usage && typeof m.usage === "object")
+            return m.usage;
+    }
+    const part = obj.part;
+    if (part && typeof part === "object") {
+        const p = part;
+        const tokens = p.tokens;
+        if (tokens && typeof tokens === "object") {
+            const t = tokens;
+            // opencode nests cache counts under `tokens.cache = { read, write }`.
+            const cache = (t.cache && typeof t.cache === "object" ? t.cache : {});
+            return {
+                ...(typeof t.input === "number" ? { input_tokens: t.input } : {}),
+                ...(typeof t.output === "number" ? { output_tokens: t.output } : {}),
+                ...(typeof t.total === "number" ? { total_tokens: t.total } : {}),
+                ...(typeof p.cost === "number" ? { cost_usd: p.cost } : {}),
+                ...(typeof cache.read === "number" ? { cache_read_input_tokens: cache.read } : {}),
+                ...(typeof cache.write === "number" ? { cache_creation_input_tokens: cache.write } : {}),
+            };
+        }
+    }
+    return undefined;
+}
+/**
+ * Token count from a `usage`-shaped JSON object, or undefined if absent.
+ *
+ * Only billable input+output (or an explicit `total_tokens`) count toward the
+ * headline number: claude's `cache_creation_input_tokens` / `cache_read_input_tokens`
+ * bill at different rates, so summing them into the same "tokens" figure would
+ * be fabricated precision (0109). The terminal `result` event reports the
+ * authoritative turn total, so the running figure converges on it.
+ */
+function tokensFromObject(obj) {
+    const usage = findUsage(obj);
+    if (usage) {
+        if (typeof usage.total_tokens === "number")
+            return usage.total_tokens;
+        const input = typeof usage.input_tokens === "number" ? usage.input_tokens : 0;
+        const output = typeof usage.output_tokens === "number" ? usage.output_tokens : 0;
+        if (input || output)
+            return input + output;
+    }
+    if (typeof obj.total_tokens === "number")
+        return obj.total_tokens;
+    return undefined;
+}
+/** Cost (USD) from a `usage`-shaped JSON object, or undefined if absent. */
+function costFromObject(obj) {
+    // claude's terminal `result` event reports the authoritative per-turn cost.
+    if (typeof obj.total_cost_usd === "number")
+        return obj.total_cost_usd;
+    if (typeof obj.cost_usd === "number")
+        return obj.cost_usd;
+    const usage = findUsage(obj);
+    if (usage) {
+        if (typeof usage.cost_usd === "number")
+            return usage.cost_usd;
+        if (typeof usage.total_cost_usd === "number")
+            return usage.total_cost_usd;
+    }
+    return undefined;
+}
+/**
+ * Prompt-cache token counts from a `usage`-shaped object. Provider field names
+ * vary; `findUsage` already normalizes opencode's `part.tokens.cache.{read,
+ * write}`. Claude: `cache_read_input_tokens` / `cache_creation_input_tokens`.
+ * Codex: `cached_input_tokens` (read only). All absent when a CLI reports no
+ * cache figures — never fabricated.
+ */
+function cacheTokensFromObject(obj) {
+    const usage = findUsage(obj);
+    if (!usage)
+        return {};
+    const num = (v) => (typeof v === "number" && v >= 0 ? v : undefined);
+    const read = num(usage.cache_read_input_tokens) ??
+        num(usage.cached_input_tokens) ??
+        num(usage.cache_read_tokens);
+    const creation = num(usage.cache_creation_input_tokens) ?? num(usage.cache_creation_tokens);
+    const out = {};
+    if (read !== undefined)
+        out.cacheReadTokens = read;
+    if (creation !== undefined)
+        out.cacheCreationTokens = creation;
+    return out;
+}
+/**
+ * Model round-trips this event accounts for (a DELTA — see ExtractedUsage.turns).
+ * Only the two clear cases: claude's terminal `result` carries `num_turns` for
+ * that invocation; opencode emits one `step_finish` per model round-trip. Other
+ * CLIs report nothing countable yet.
+ */
+function turnsFromObject(obj) {
+    if (obj.type === "step_finish" || obj.type === "step-finish")
+        return 1;
+    if (obj.type === "result" && typeof obj.num_turns === "number" && obj.num_turns >= 0) {
+        return obj.num_turns;
+    }
+    return undefined;
+}
+/** On-disk transcript schema. Bump when persisted fields change incompatibly. */
+const SESSION_FILE_VERSION = 1;
+const SESSION_WRITE_DELAY_MS = 500;
+const SESSION_RETENTION_DAYS = 30;
+const SESSION_RETENTION_COUNT = 1000;
+/** Best-effort session-id extraction from agent output (opencode / claude). */
+const SESSION_ID_PATTERNS = [
+    /"session_id"\s*:\s*"([^"]+)"/,
+    /session[ \t]+id[:\s]*["']?([A-Za-z0-9][A-Za-z0-9_.-]{5,})/i,
+];
+/**
+ * Which structured-event engine (if any) a session should use for a CLI. Both
+ * structured engines parse newline-delimited JSON events; they differ only in
+ * event shape (`part` vs `message.content[]`), so each gets its own parser
+ * branch in `appendLine`.
+ */
+function engineForCli(cli) {
+    if (cli === "claude code")
+        return "claude";
+    if (cli === "github copilot")
+        return "copilot";
+    if (cli === "qwen code")
+        return "qwen";
+    if (cli === "codex")
+        return "codex";
+    if (cli === "kiro")
+        return "kiro";
+    return "opencode";
+}
+/**
+ * Render a tool input as display text: a bash call shows its command, an
+ * object input becomes pretty JSON, and strings pass through untouched.
+ */
+function toolInputText(input) {
+    if (typeof input === "string")
+        return input;
+    if (input === undefined || input === null)
+        return undefined;
+    if (typeof input === "object") {
+        const obj = input;
+        if (typeof obj.command === "string" && obj.command)
+            return obj.command;
+        try {
+            const s = JSON.stringify(obj, null, 2);
+            return s && s !== "{}" ? s : undefined;
+        }
+        catch {
+            return String(input);
+        }
+    }
+    return String(input);
+}
+/**
+ * Render a tool output as display text: strings pass through untouched and
+ * object outputs become pretty JSON. Falls back to the error payload when the
+ * call failed.
+ */
+function toolOutputText(output) {
+    if (typeof output === "string" && output)
+        return output;
+    if (output === undefined || output === null)
+        return undefined;
+    if (typeof output === "object") {
+        try {
+            const s = JSON.stringify(output, null, 2);
+            return s && s !== "{}" ? s : undefined;
+        }
+        catch {
+            return String(output);
+        }
+    }
+    const s = String(output);
+    return s ? s : undefined;
+}
+/**
+ * Parse one line of opencode's `--format json` stream into a structured
+ * transcript entry. Returns null for malformed lines and for event types we
+ * don't surface (session-id, title, reasoning, …) — callers fall back to the
+ * plain-line handling in those cases.
+ */
+export function parseJsonEvent(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const ev = parsed;
+    const type = typeof ev.type === "string" ? ev.type : "";
+    if (!type)
+        return null;
+    const sessionID = typeof ev.sessionID === "string" && ev.sessionID ? ev.sessionID : undefined;
+    const part = ev.part ?? {};
+    switch (type) {
+        case "text": {
+            const text = typeof part.text === "string" ? part.text : "";
+            if (!text.trim())
+                return null;
+            return { entry: { type: "text", text }, sessionID };
+        }
+        case "tool_use": {
+            const tool = typeof part.tool === "string" ? part.tool : "";
+            if (!tool)
+                return null;
+            const state = part.state ?? {};
+            const status = typeof state.status === "string" ? state.status : undefined;
+            const input = toolInputText(state.input);
+            const output = toolOutputText(state.output ?? state.error);
+            return {
+                entry: {
+                    type: "tool",
+                    tool,
+                    ...(input ? { input } : {}),
+                    ...(output ? { output } : {}),
+                    ...(status ? { state: status } : {}),
+                },
+                sessionID,
+            };
+        }
+        case "step_start":
+            return { entry: { type: "step", kind: "start", at: now() }, sessionID };
+        case "step_finish":
+            return {
+                entry: {
+                    type: "step",
+                    kind: "finish",
+                    at: now(),
+                    ...(typeof part.reason === "string" && part.reason ? { reason: part.reason } : {}),
+                },
+                sessionID,
+            };
+        case "error": {
+            const err = ev.error ?? {};
+            const data = err.data ?? {};
+            const msg = typeof data.message === "string" && data.message
+                ? data.message
+                : typeof err.name === "string" && err.name
+                    ? err.name
+                    : "";
+            if (!msg)
+                return null;
+            return { entry: { type: "sys", d: `error: ${msg}` }, sessionID };
+        }
+        case "file-update": {
+            // Older opencode emitted file-write events directly; surface the path.
+            const path = typeof ev.path === "string" && ev.path
+                ? ev.path
+                : typeof part.path === "string"
+                    ? part.path
+                    : "";
+            if (!path)
+                return null;
+            return { entry: { type: "sys", d: `✎ ${path}` }, sessionID };
+        }
+        default:
+            return null;
+    }
+}
+/** Render a claude tool_result `content` (string or a list of text blocks). */
+function toolResultText(content) {
+    if (typeof content === "string" && content)
+        return content;
+    if (Array.isArray(content)) {
+        const text = content
+            .filter((b) => !!b && typeof b === "object")
+            .map((b) => (typeof b.text === "string" ? b.text : ""))
+            .join("\n");
+        return text || undefined;
+    }
+    if (typeof content === "object" && content !== null) {
+        try {
+            const s = JSON.stringify(content);
+            return s && s !== "{}" ? s : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/** A claude `assistant` event's first surfaceable content block, if any. */
+function claudeAssistantEntry(content) {
+    for (const block of content) {
+        if (typeof block.type !== "string")
+            continue;
+        if (block.type === "text") {
+            const text = typeof block.text === "string" ? block.text : "";
+            if (!text.trim())
+                continue;
+            return { entry: { type: "text", text } };
+        }
+        if (block.type === "tool_use") {
+            const id = typeof block.id === "string" ? block.id : "";
+            const name = typeof block.name === "string" ? block.name : "";
+            if (!id || !name)
+                continue;
+            const input = toolInputText(block.input);
+            return { pendingTool: { id, name, ...(input ? { input } : {}) } };
+        }
+        // thinking / unknown blocks are not surfaced — same policy as opencode's
+        // reasoning events. Swallowed by the caller, never dumped as raw JSON.
+    }
+    return null;
+}
+/**
+ * Parse one line of claude code's `--output-format stream-json` stream into a
+ * structured transcript result. Mirrors `parseJsonEvent` for opencode but with
+ * claude's event shapes: content is nested under `message.content[]` (not
+ * `part`), the session id is a real `session_id` field on `system/init`, and
+ * tool results arrive as separate `user` events. Recognized-but-voiceless
+ * events (rate_limit, thinking-only assistant messages, the terminal `result`)
+ * are returned without an `entry` so the runner swallows them instead of
+ * dumping raw JSON into the transcript. `null` for anything else — callers
+ * fall back to the plain-line path.
+ */
+export function parseClaudeEvent(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const ev = parsed;
+    const type = typeof ev.type === "string" ? ev.type : "";
+    if (!type)
+        return null;
+    const sessionID = typeof ev.session_id === "string" && ev.session_id ? ev.session_id : undefined;
+    const content = Array.isArray(ev.message?.content)
+        ? ev.message.content
+        : [];
+    switch (type) {
+        case "system": {
+            const subtype = typeof ev.subtype === "string" ? ev.subtype : "";
+            if (subtype === "init") {
+                // The stream's real session id lives here; the runner captures it for
+                // `--resume` on follow-up turns instead of regex-scraping prose.
+                return { sessionID };
+            }
+            if (subtype === "thinking_tokens") {
+                // A thinking phase begins — a step boundary the UI renders as a start
+                // marker (visually dropped in favor of a quiet timeline).
+                return { entry: { type: "step", kind: "start", at: now() }, sessionID };
+            }
+            if (subtype === "post_turn_summary") {
+                // The turn's work is done — the boundary before the `result` line.
+                return { entry: { type: "step", kind: "finish", at: now() }, sessionID };
+            }
+            // Unknown system subtypes: swallow, don't dump.
+            return { sessionID };
+        }
+        case "assistant": {
+            const surfaced = claudeAssistantEntry(content);
+            if (surfaced)
+                return { ...surfaced, sessionID };
+            // Thinking-only (or empty) assistant events are voiceless — swallow.
+            return { sessionID };
+        }
+        case "user": {
+            for (const block of content) {
+                if (typeof block.type !== "string" || block.type !== "tool_result")
+                    continue;
+                const id = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+                if (!id)
+                    continue;
+                const contentText = toolResultText(block.content);
+                return {
+                    toolResult: {
+                        id,
+                        ...(contentText ? { content: contentText } : {}),
+                        ...(block.is_error === true ? { isError: true } : {}),
+                    },
+                    sessionID,
+                };
+            }
+            return { sessionID };
+        }
+        case "result": {
+            // Authoritative usage/cost totals — consumed by extractUsage on the raw
+            // line; the `result` text duplicates the final assistant text, so it is
+            // never surfaced as its own entry.
+            return { sessionID };
+        }
+        case "rate_limit_event":
+            return { sessionID };
+        case "stream_event": {
+            // Anthropic API streaming events wrapped by claude code CLI (0151).
+            // These are intermediate streaming updates (content_block_delta,
+            // content_block_stop, etc.) that are not surfaced as their own entries —
+            // they are aggregated by the API layer and only the final "message" or
+            // "assistant" event is rendered to the transcript. Swallow them here with
+            // the session id extracted from the outer wrapper.
+            const streamSessionId = typeof ev.session_id === "string" && ev.session_id ? ev.session_id : undefined;
+            return { sessionID: streamSessionId };
+        }
+        default:
+            return null;
+    }
+}
+/** Text-bearing values in Copilot tool results and error payloads. */
+function copilotText(value) {
+    if (typeof value === "string" && value)
+        return value;
+    if (!value || typeof value !== "object")
+        return undefined;
+    const obj = value;
+    for (const key of ["content", "text", "message", "error"]) {
+        if (typeof obj[key] === "string" && obj[key])
+            return obj[key];
+    }
+    return toolOutputText(value);
+}
+/**
+ * Parse Copilot CLI's `--output-format json` JSONL stream. The CLI emits
+ * lifecycle telemetry alongside assistant and tool events; lifecycle records
+ * are recognized and swallowed so the Agent tab remains a useful transcript.
+ */
+export function parseCopilotEvent(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const event = parsed;
+    const type = typeof event.type === "string" ? event.type : "";
+    if (!type)
+        return null;
+    const data = event.data ?? {};
+    const sessionID = typeof event.sessionId === "string" && event.sessionId ? event.sessionId : undefined;
+    if (type === "assistant.message_delta")
+        return { sessionID };
+    if (type === "assistant.message") {
+        const text = typeof data.content === "string" ? data.content : "";
+        return text ? { entry: { type: "text", text }, sessionID } : { sessionID };
+    }
+    if (type === "tool.execution_start") {
+        const tool = typeof data.toolName === "string"
+            ? data.toolName
+            : typeof data.tool === "string"
+                ? data.tool
+                : "";
+        if (!tool)
+            return { sessionID };
+        const input = toolInputText(data.arguments ?? data.input);
+        return {
+            entry: { type: "tool", tool, ...(input ? { input } : {}), state: "running" },
+            sessionID,
+        };
+    }
+    if (type === "tool.execution_complete") {
+        const tool = typeof data.toolName === "string"
+            ? data.toolName
+            : typeof data.tool === "string"
+                ? data.tool
+                : "tool";
+        const input = toolInputText(data.arguments ?? data.input);
+        const output = copilotText(data.result ?? data.output ?? data.error);
+        return {
+            entry: {
+                type: "tool",
+                tool,
+                ...(input ? { input } : {}),
+                ...(output ? { output } : {}),
+                ...(data.error ? { state: "error" } : { state: "completed" }),
+            },
+            sessionID,
+        };
+    }
+    if (type === "error" || type.endsWith(".error")) {
+        const message = copilotText(data.error ?? data.message ?? data);
+        return message ? { entry: { type: "sys", d: `error: ${message}` }, sessionID } : { sessionID };
+    }
+    if (type === "result" ||
+        type.startsWith("session.") ||
+        type.startsWith("model.") ||
+        type.startsWith("mcp."))
+        return { sessionID };
+    return null;
+}
+/**
+ * Qwen's stream-json is Claude-compatible for assistant/tool content, but
+ * versions in the wild also emit the shorter `{type, content}` form. Keep
+ * this adapter deliberately tolerant so a CLI upgrade cannot turn the chat
+ * into a wall of JSON.
+ */
+export function parseQwenEvent(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== "object")
+        return null;
+    const event = value;
+    const sessionID = typeof event.session_id === "string"
+        ? event.session_id
+        : typeof event.sessionId === "string"
+            ? event.sessionId
+            : undefined;
+    const type = typeof event.type === "string" ? event.type : "";
+    if (!type)
+        return null;
+    const message = event.message && typeof event.message === "object"
+        ? event.message
+        : undefined;
+    const content = Array.isArray(message?.content)
+        ? message.content
+        : typeof event.content === "string"
+            ? [{ type: "text", text: event.content }]
+            : [];
+    if (type === "system" || type === "session_start" || type === "session_started") {
+        return { sessionID };
+    }
+    if (type === "assistant" || type === "message" || type === "assistant_message") {
+        const surfaced = claudeAssistantEntry(content);
+        return surfaced ? { ...surfaced, sessionID } : { sessionID };
+    }
+    if (type === "content_block_delta" || type === "message_delta") {
+        const delta = event.delta && typeof event.delta === "object"
+            ? event.delta
+            : undefined;
+        const text = typeof delta?.text === "string"
+            ? delta.text
+            : typeof event.text === "string"
+                ? event.text
+                : "";
+        return text ? { entry: { type: "text", text }, sessionID } : { sessionID };
+    }
+    if (type === "user") {
+        for (const block of content) {
+            if (block.type !== "tool_result" || typeof block.tool_use_id !== "string")
+                continue;
+            return {
+                toolResult: {
+                    id: block.tool_use_id,
+                    ...(toolResultText(block.content) ? { content: toolResultText(block.content) } : {}),
+                    ...(block.is_error === true ? { isError: true } : {}),
+                },
+                sessionID,
+            };
+        }
+    }
+    if (content.length) {
+        const surfaced = claudeAssistantEntry(content);
+        return surfaced ? { ...surfaced, sessionID } : { sessionID };
+    }
+    if (["result", "turn_complete", "turn.completed", "rate_limit_event"].includes(type)) {
+        return { sessionID };
+    }
+    return null;
+}
+/** Parse Codex `exec --json` JSONL into the same chat cards as OpenCode. */
+export function parseCodexEvent(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== "object")
+        return null;
+    const event = value;
+    const type = typeof event.type === "string" ? event.type : "";
+    const sessionID = typeof event.thread_id === "string"
+        ? event.thread_id
+        : typeof event.session_id === "string"
+            ? event.session_id
+            : undefined;
+    if (!type)
+        return null;
+    const item = event.item && typeof event.item === "object"
+        ? event.item
+        : undefined;
+    if (type === "thread.started")
+        return { sessionID };
+    if (type === "item.updated" && typeof event.delta === "string") {
+        return event.delta.trim()
+            ? { entry: { type: "text", text: event.delta }, sessionID }
+            : { sessionID };
+    }
+    if (type === "error" || type === "turn.failed") {
+        const message = typeof event.message === "string"
+            ? event.message
+            : typeof event.error === "string"
+                ? event.error
+                : undefined;
+        return message ? { entry: { type: "sys", d: `error: ${message}` }, sessionID } : { sessionID };
+    }
+    if (!item)
+        return { sessionID };
+    const itemType = typeof item.type === "string" ? item.type : "";
+    if (itemType === "agent_message") {
+        const text = typeof item.text === "string" ? item.text : typeof item.delta === "string" ? item.delta : "";
+        return text.trim() ? { entry: { type: "text", text }, sessionID } : { sessionID };
+    }
+    if (itemType === "command_execution") {
+        const command = typeof item.command === "string" ? item.command : undefined;
+        const output = typeof item.aggregated_output === "string"
+            ? item.aggregated_output
+            : typeof item.output === "string"
+                ? item.output
+                : undefined;
+        const state = typeof item.status === "string"
+            ? item.status
+            : typeof item.exit_code === "number"
+                ? item.exit_code === 0
+                    ? "completed"
+                    : "error"
+                : undefined;
+        return {
+            entry: {
+                type: "tool",
+                tool: "shell",
+                ...(command ? { input: command } : {}),
+                ...(output ? { output } : {}),
+                ...(state ? { state } : {}),
+            },
+            sessionID,
+        };
+    }
+    if (itemType === "file_change" || itemType === "file_changes") {
+        const changes = item.changes ?? item.files;
+        const detail = typeof changes === "string" ? changes : toolOutputText(changes);
+        return {
+            entry: { type: "tool", tool: "file changes", ...(detail ? { output: detail } : {}) },
+            sessionID,
+        };
+    }
+    return { sessionID };
+}
+/** Byte estimate of one entry, for the transcript cap. */
+function entryBytes(e) {
+    const legacy = e;
+    if (typeof legacy.d === "string")
+        return legacy.d.length + 1;
+    return JSON.stringify(e).length + 1;
+}
+/** Branch derived from a task title, mirroring the UI's `feat/<slug>` rule. */
+export function deriveBranch(title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 40);
+    return `feat/${slug || "task"}`;
+}
+/**
+ * Role-name matching is case-insensitive: the Agents page stores agent names
+ * verbatim (it only lowercases when checking duplicates), so a stored
+ * `"CTO"`/`"Reviewer"`/`"PM"` must still resolve to its role. This bit the CTO
+ * (0174): the merged `repoos.toml` stored `name = "CTO"`, so the exact-match
+ * `"cto"` lookup always returned null and the agent read as permanently
+ * disabled.
+ */
+function matchesRole(a, role) {
+    return a.name.toLowerCase() === role;
+}
+/** Resolve the enabled `engineer` agent, or null when none is configured. */
+export function resolveEngineer(config) {
+    const list = agentsForConfig(config);
+    return list.find((a) => a.enabled && matchesRole(a, "engineer")) ?? null;
+}
+/** Resolve the enabled `pm` agent, or null when none is configured. */
+export function resolvePmAgent(config) {
+    const list = agentsForConfig(config);
+    return list.find((a) => a.enabled && matchesRole(a, "pm")) ?? null;
+}
+/**
+ * Resolve the enabled `reviewer` agent, or null when it is disabled/absent.
+ *
+ * This is the single source of truth for whether a task landing in `review`
+ * gets an automatic agent review (0101): the Agents page writes the toggle
+ * into `repoos.toml`, and null here means "no agent review runs".
+ */
+export function resolveReviewer(config) {
+    const list = agentsForConfig(config);
+    return list.find((a) => a.enabled && matchesRole(a, "reviewer")) ?? null;
+}
+/**
+ * Resolve the reviewer agent for a specific task, honoring per-task review
+ * overrides (set via the Review tab's selector, like Dev/PM overrides).
+ *
+ * When the task has no review override, this behaves exactly as the global
+ * `resolveReviewer` — the Agents-page reviewer. When a `reviewAgentOverride`
+ * is set, the enabled agent with that name is used (falling back to the global
+ * reviewer base when only CLI/model are overridden); `reviewCliOverride` /
+ * `reviewModelOverride` then replace the agent's CLI and model.
+ */
+export function resolveReviewerForTask(config, task) {
+    const modelPinned = isModelOverridePinned(task.reviewModelOverride);
+    const hasOverride = task.reviewAgentOverride || task.reviewCliOverride || modelPinned;
+    if (!hasOverride) {
+        return resolveReviewer(config);
+    }
+    const list = agentsForConfig(config);
+    const baseName = task.reviewAgentOverride || "reviewer";
+    const base = list.find((a) => a.enabled && matchesRole(a, baseName)) ?? null;
+    if (!base)
+        return null;
+    return {
+        ...base,
+        ...(task.reviewCliOverride ? { cli: task.reviewCliOverride } : {}),
+        ...(modelPinned ? { model: task.reviewModelOverride } : {}),
+    };
+}
+export function resolveCto(config) {
+    const list = agentsForConfig(config);
+    return list.find((a) => a.enabled && matchesRole(a, "cto")) ?? null;
+}
+/**
+ * Resolve the agent for a specific task, honoring per-task overrides.
+ *
+ * When the task has an `agentOverride`, the enabled agent with that name is
+ * used (falling back to the base agent when the override name matches). When
+ * only `cliOverride` or `modelOverride` are set (without a different agent
+ * name), the base agent's name and instructions are kept but cli/model are
+ * overridden.
+ *
+ * @param config  Global config (provides the agents list and defaults).
+ * @param task    The task being run (may carry overrides).
+ * @param role    The role to resolve when no agent override is set (default: "engineer").
+ * @returns A merged Agent, or null when no matching enabled agent exists.
+ */
+/**
+ * True when a model-override field carries a real pin, not the "default"
+ * sentinel `AGENT_MODELS` offers for "use the base agent's own configured
+ * model, whatever that is" (config.ts). Every per-task model-override
+ * resolver (this file's `resolveAgentForTask`/`resolveReviewerForTask`, and
+ * routes/tasks.ts's inline PM-override logic) MUST run the override string
+ * through this before treating it as active — bare truthiness treats the
+ * literal string `"default"` as a real pin and force-overwrites the base
+ * agent's actual configured model with the string `"default"`, which then
+ * skips `--model` entirely (see `modelArgs` below) and falls back to the
+ * underlying CLI's own raw default — NOT the model configured on the
+ * Agents page. Confirmed live: tasks kept ending up running
+ * opencode+(no model flag) instead of the configured model every time a
+ * Dev/Review/PM override dropdown was left on (or reset to) "Default".
+ */
+export function isModelOverridePinned(model) {
+    return !!model && model !== "default";
+}
+export function resolveAgentForTask(config, task, role = "engineer") {
+    const list = agentsForConfig(config);
+    const modelPinned = isModelOverridePinned(task.modelOverride);
+    const hasOverride = task.agentOverride || task.cliOverride || modelPinned;
+    if (!hasOverride) {
+        return list.find((a) => a.enabled && a.name === role) ?? null;
+    }
+    // Resolve the base agent: use the override name if set, else the role.
+    const baseName = task.agentOverride || role;
+    const base = list.find((a) => a.enabled && a.name === baseName) ?? null;
+    if (!base)
+        return null;
+    // Merge overrides onto the base agent.
+    return {
+        ...base,
+        ...(task.cliOverride ? { cli: task.cliOverride } : {}),
+        ...(modelPinned ? { model: task.modelOverride } : {}),
+    };
+}
+/** Resolve the enabled built-in repository assistant (by current "Ross" name or legacy "RepoOS Guide"). */
+export function resolveRepoGuide(config) {
+    const agents = agentsForConfig(config);
+    return (agents.find((agent) => agent.enabled &&
+        (agent.name.toLowerCase() === "ross" || agent.name.toLowerCase() === "repoos guide")) ?? null);
+}
+/**
+ * Map an agent `cli` string to the binary + args that run it headless.
+ *
+ * opencode re-resolves its project directory from `--git-common-dir`, which
+ * for a linked worktree points at the main repo's `.git` — so every worktree
+ * path would be treated as `external_directory` and auto-rejected. `--dir`
+ * forces the worktree path explicitly. claude code and qwen code use the spawn
+ * `cwd` and need no flag.
+ *
+ * Verified flags (0042/0043):
+ * - claude code: `claude -p <prompt> --output-format stream-json --verbose
+ *   --dangerously-skip-permissions` (print mode, 0109). stream-json emits one
+ *   JSON event per line (assistant text, tool calls, results) that streams
+ *   live instead of claude buffering all stdout until exit — the #0070/#0101/
+ *   #0080 blank-Agent-tab fix. `--verbose` is required alongside stream-json
+ *   in print mode. The permission flag is REQUIRED here, not optional: the
+ *   agent is spawned with stdin ignored, so no approval prompt can ever reach
+ *   a human. Without it every non-read-only command (`bun`, `repoos check`,
+ *   writes) is denied instantly, the agent stalls explaining it needs
+ *   approval, and the task is left stuck in `active` with no changes. Same
+ *   intent as codex's `--sandbox workspace-write` below; the blast radius is
+ *   the task's own git worktree.
+ * - qwen code: `qwen -p <prompt> --output-format stream-json` — stream-json
+ *   emits one JSON event per line, which streams live and carries a
+ *   `session_id` RepoOS can resume.
+ * - codex: `codex exec <prompt> --json --sandbox workspace-write` — `--json`
+ *   streams newline-delimited events; `--sandbox workspace-write` lets the
+ *   agent edit files inside the worktree (the default is read-only).
+ * - opencode: `opencode run --format json --dir <cwd> --auto <prompt>` —
+ *   `--auto` ("auto-approve permissions that are not explicitly denied") is
+ *   REQUIRED for the same reason claude's flag is: stdin is ignored, so a
+ *   permission prompt can never be answered. Without it, opencode blocks on
+ *   its first gated tool call and hangs indefinitely — confirmed live on
+ *   #0069, which sat at ~1% CPU with zero commits for ~2 hours before being
+ *   killed. Same blast radius as the other engines: the task's own worktree.
+ */
+function modelArgs(cli, model) {
+    if (!model || model === "default")
+        return [];
+    if (cli === "codex")
+        return ["--model", model];
+    return ["--model", model];
+}
+const COPILOT_TOOL_PERMISSIONS = [
+    "--allow-tool",
+    "write",
+    "--allow-tool",
+    "shell(bun:*)",
+    "--allow-tool",
+    "shell(node:*)",
+    "--allow-tool",
+    "shell(npm:*)",
+    "--allow-tool",
+    "shell(npx:*)",
+    "--allow-tool",
+    "shell(git:*)",
+    "--allow-tool",
+    "shell(curl:*)",
+    "--allow-tool",
+    "shell(ls)",
+    "--allow-tool",
+    "shell(cat)",
+];
+function copilotArgs(options) {
+    return [
+        "--output-format",
+        "json",
+        "--no-ask-user",
+        "--no-auto-update",
+        "--no-remote",
+        "--no-remote-export",
+        ...(options.write ? COPILOT_TOOL_PERMISSIONS : []),
+    ];
+}
+function cliCommand(agent, mission, cwd) {
+    const { cli, model } = agent;
+    if (cli === "claude code") {
+        return {
+            cmd: "claude",
+            args: [
+                "-p",
+                mission,
+                ...modelArgs(cli, model),
+                "--output-format",
+                "stream-json",
+                "--include-partial-messages",
+                "--verbose",
+                "--dangerously-skip-permissions",
+            ],
+        };
+    }
+    if (cli === "qwen code") {
+        return {
+            cmd: "qwen",
+            args: [
+                "-p",
+                mission,
+                ...modelArgs(cli, model),
+                "--output-format",
+                "stream-json",
+                "--include-partial-messages",
+            ],
+        };
+    }
+    if (cli === "codex") {
+        return {
+            cmd: "codex",
+            args: ["exec", mission, ...modelArgs(cli, model), "--json", "--sandbox", "workspace-write"],
+        };
+    }
+    if (cli === "github copilot") {
+        return {
+            cmd: "copilot",
+            args: ["-p", mission, ...modelArgs(cli, model), ...copilotArgs({ write: true })],
+        };
+    }
+    if (cli === "kiro") {
+        // --no-interactive: headless mode (no TUI, answer is printed to stdout).
+        // --trust-all-tools: REQUIRED — stdin is ignored so no approval prompt can
+        // ever be answered. Without it every file write/shell call is denied and
+        // the agent stalls. Same blast radius as claude's --dangerously-skip-permissions:
+        // the task's own git worktree.
+        return {
+            cmd: "kiro-cli",
+            args: ["chat", "--no-interactive", "--trust-all-tools", ...modelArgs(cli, model), mission],
+        };
+    }
+    // default: opencode's headless `run` mode. `--format json` streams one JSON
+    // event per line (step_start / text / tool_use / step_finish / error) that
+    // the runner parses into structured transcript entries. `--dir` (0044) keeps
+    // the worktree path explicit so linked-worktree paths are never auto-rejected.
+    return {
+        cmd: "opencode",
+        args: ["run", "--format", "json", "--dir", cwd, ...modelArgs(cli, model), "--auto", mission],
+    };
+}
+/**
+ * Map a follow-up turn to a resume invocation that continues the SAME session.
+ * claude: `-p --resume <id>` + stream-json/--verbose (falls back to
+ * `-c --continue` when the id is unknown). opencode: `run --format json
+ * --session <id>`. qwen: `--resume <id>` / `--continue` with `-p` +
+ * stream-json. codex: `exec resume <id>` / `exec resume --last`.
+ * All degrade to a fresh run with the user's text if resume metadata is
+ * unavailable — the turn still happens.
+ */
+function resumeCommand(agent, text, sessionId, cwd) {
+    const { cli, model } = agent;
+    if (cli === "claude code") {
+        return {
+            cmd: "claude",
+            args: [
+                "-p",
+                ...(sessionId ? ["--resume", sessionId] : ["-c", "--continue"]),
+                text,
+                ...modelArgs(cli, model),
+                "--output-format",
+                "stream-json",
+                "--include-partial-messages",
+                "--verbose",
+                "--dangerously-skip-permissions",
+            ],
+        };
+    }
+    if (cli === "qwen code") {
+        return {
+            cmd: "qwen",
+            args: [
+                ...(sessionId ? ["--resume", sessionId] : ["--continue"]),
+                "-p",
+                text,
+                ...modelArgs(cli, model),
+                "--output-format",
+                "stream-json",
+                "--include-partial-messages",
+            ],
+        };
+    }
+    if (cli === "codex") {
+        return {
+            cmd: "codex",
+            args: [
+                "exec",
+                "--sandbox",
+                "workspace-write",
+                "resume",
+                ...modelArgs(cli, model),
+                "--json",
+                ...(sessionId ? [sessionId] : ["--last"]),
+                text,
+            ],
+        };
+    }
+    if (cli === "github copilot") {
+        // Never use --continue here: it could attach a different task's most
+        // recent Copilot session. Without a saved id, start a fresh safe turn.
+        return {
+            cmd: "copilot",
+            args: [
+                "-p",
+                text,
+                ...(sessionId ? [`--resume=${sessionId}`] : []),
+                ...modelArgs(cli, model),
+                ...copilotArgs({ write: true }),
+            ],
+        };
+    }
+    if (cli === "kiro") {
+        // --resume-id <uuid>: resume a specific session by UUID (preferred).
+        // -r / --resume: fall back to most-recent session in cwd when no id yet.
+        return {
+            cmd: "kiro-cli",
+            args: [
+                "chat",
+                "--no-interactive",
+                "--trust-all-tools",
+                ...(sessionId ? ["--resume-id", sessionId] : ["-r"]),
+                ...modelArgs(cli, model),
+                text,
+            ],
+        };
+    }
+    return {
+        cmd: "opencode",
+        args: [
+            "run",
+            "--format",
+            "json",
+            ...(sessionId ? ["--session", sessionId] : []),
+            ...(cwd ? ["--dir", cwd] : []),
+            ...modelArgs(cli, model),
+            "--auto",
+            text,
+        ],
+    };
+}
+/** Build the read-only mission used by the persistent repository chat. */
+export function repoGuidePrompt(question, repositoryContext, agent) {
+    return `You are Ross, the always-available assistant for the repository in your current working directory.
+
+${agent.instructions ?? "Answer questions about RepoOS and this repository."}
+
+Rules:
+- Answer the user's question directly and concisely.
+- Ground answers in the repository context below and inspect repository files when useful.
+- You may read files and run read-only discovery commands. Never edit files, change task status, commit, launch servers, or start agents.
+- When discussing tasks, include task IDs and current statuses when relevant.
+- If the repository does not support a claim, say what you could not verify.
+
+Current repository context:
+${repositoryContext}
+
+User question:
+${question}`;
+}
+/** The Debugger agent's role name, used to route its chat prompt. */
+export const DEBUGGER_NAME = "debugger";
+/**
+ * The Debugger agent: a chat-first bug diagnostician (no background scan).
+ * Its CLI/model can be overridden from the persisted built-in agent state so
+ * the inline "coding agent + model" selector on the Agents page actually drives
+ * which model the Debugger runs on.
+ */
+export function debuggerAgent(override) {
+    // previously "big pickle"
+    const base = { cli: "opencode", model: "deepinfra/deepseek-ai/DeepSeek-V4-Flash-0731" };
+    return {
+        name: DEBUGGER_NAME,
+        cli: override?.cli || base.cli,
+        model: override?.model || base.model,
+        enabled: true,
+        instructions: "You are the Debugger, a bug diagnostician. When you're handed a pasted bug report, stack trace, or error message, identify the root cause and suggest a concrete, actionable fix. Ask for more context only when the report is too ambiguous to diagnose. Ground your diagnosis in the repository when the pasted text references code you can inspect.",
+    };
+}
+export function debuggerPrompt(question, repositoryContext, agent) {
+    return `You are the Debugger, the agent you copy a failing report to for a clear diagnosis.
+
+${agent.instructions ?? "Diagnose the root cause and suggest a fix."}
+
+Rules:
+- Identify the root cause, not just the symptom, and explain your reasoning briefly.
+- Give a concrete, actionable suggested fix (code or config where appropriate).
+- You may read repository files and run read-only discovery commands to verify.
+- Never edit files, change task status, commit, launch servers, or start agents.
+- If you cannot determine the cause with confidence, say exactly what is missing.
+
+The pasted bug / error / question is below. Current repository context:
+${repositoryContext}
+
+Bug report:
+${question}`;
+}
+/** Build the writable task-management mission used only by the PM chat. */
+export function taskPmPrompt(request, taskContext, agent) {
+    return `You are the Product Manager for RepoOS, working on the task below. You are not Ross or the read-only repository assistant.
+
+${agent.instructions ?? "Own the roadmap and keep task specifications accurate."}
+
+Rules:
+- You may create or update tasks, including task body, metadata, and status, only through RepoOS CLI commands (e.g. \`repoos new\`, \`repoos update\`, \`repoos mv\`). Never call the RepoOS HTTP API directly (no \`curl\`/fetch against localhost) — it requires a browser session and is not reachable from your sandbox.
+- Never edit \`work/*.md\` files directly. Never move task files between folders.
+- Do not implement product code, commit code, merge branches, or start servers unless the user explicitly asks for that separately.
+- Explain the requested task change briefly after applying it, including the task ID and what changed.
+
+Task context:
+${taskContext}
+
+User request:
+${request}`;
+}
+/** The mission handed to the coding agent: instructions + task pointer. */
+const SKILL_ROUTING_HINTS = {
+    "frontend-design": [
+        "frontend",
+        "ui",
+        "ux",
+        "vue",
+        "css",
+        "html",
+        "component",
+        "layout",
+        "page",
+        "style",
+        "accessibility",
+    ],
+    "code-review": ["review", "reviewer", "sign-off", "signoff", "diff", "regression"],
+};
+/** Pick a small relevant subset; role defaults are preferences, never an unconditional prompt append. */
+export function selectSkillsForRun(task, agent, config) {
+    const taskText = `${task.title} ${task.area} ${task.body}`.toLowerCase();
+    const words = new Set(taskText.match(/[a-z][a-z0-9-]{2,}/g) ?? []);
+    const preferred = new Set(agent.skills ?? []);
+    return listSkills(config)
+        .map((skill) => {
+        const hints = SKILL_ROUTING_HINTS[skill.name] ?? [];
+        const descriptionWords = skill.description.toLowerCase().match(/[a-z][a-z0-9-]{3,}/g) ?? [];
+        const score = hints.filter((hint) => taskText.includes(hint)).length * 2 +
+            descriptionWords.filter((word) => words.has(word)).length +
+            (preferred.has(skill.name) &&
+                (hints.some((hint) => taskText.includes(hint)) ||
+                    descriptionWords.some((word) => words.has(word)))
+                ? 1
+                : 0);
+        return { skill, score };
+    })
+        .filter(({ score }) => score >= 2)
+        .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
+        .slice(0, 3)
+        .map(({ skill }) => skill);
+}
+function missionFor(task, branch, workdir, agent, config, contextPack, resumePreamble, enabledSkills = []) {
+    // Source edits stay inside the sandbox. RepoOS owns the privileged Git and
+    // canonical-board mutations after the structured signal below (ADR-0005).
+    const worktreeTask = join(workdir, relative(config.root, task.path));
+    const baseBranch = currentBranch(config.root) ?? "main";
+    const parts = [];
+    if (contextPack) {
+        parts.push(contextPack);
+        parts.push("");
+    }
+    if (resumePreamble) {
+        parts.push(resumePreamble);
+        parts.push("");
+    }
+    parts.push(agent.instructions?.trim() ? agent.instructions.trim() : "Implement this task.", "");
+    // Skills are intentionally explicit: a repository may contain many
+    // procedures, but an agent sees only the skills enabled for its role. Resolve
+    // names through the discovered list rather than constructing paths from
+    // config input, so a stale or malicious name can never escape skillsDir.
+    //
+    // CACHING: `enabledSkills` is now chosen per-run by keyword scoring
+    // (selectSkillsForRun), so this block's content VARIES from one task to the
+    // next. Today the whole mission is one `-p` string and the downstream CLI
+    // caches on its own conversation prefix, so a turn-1 cost is all this adds
+    // (resume turns never re-send it). But if this is ever split into a cached
+    // system prefix + a variable user turn, per-task-varying content sitting
+    // HERE — before the stable fail-safe checklist below — would bust the cache
+    // for everything after it. Move skills last (or into their own turn) before
+    // introducing any such prefix cache.
+    if (enabledSkills.length) {
+        parts.push("## Enabled repository skills", "");
+        for (const skill of enabledSkills) {
+            try {
+                const text = readFileSync(join(config.root, skill.path), "utf8").trim();
+                if (text)
+                    parts.push(`### ${skill.name}`, "", text, "");
+            }
+            catch {
+                // A skill may disappear after configuration was saved. Launching work
+                // must remain safe and useful in that case.
+            }
+        }
+    }
+    parts.push(`Task #${task.id}: ${task.title}`, `Working directory: ${workdir} (a git worktree checked out on branch ${branch} — work here).`, `Task file (read this worktree copy for the specification): ${worktreeTask}`, "", "Run this fail-safe checklist IN ORDER. Do not stop until it is fully checked off:", "", "1. Read the task file and implement what it describes.", `2. Run \`REPOOS_CHECK_CHANGED=${baseBranch} repoos check\` and confirm it passes (build, typecheck, tests scoped to what your branch changed vs ${baseBranch}, UI smoke test). It MUST be green before requesting handoff. RepoOS re-verifies it server-side before finalizing your handoff, and runs the full unscoped test suite again when your branch actually merges — so this scoped run is a fast correctness check, not the final word.`, "3. Do not run git add/commit and do not edit the main checkout; those privileged paths are intentionally outside your sandbox.", "   RepoOS commits only source, work, docs, and config files to the branch — never `dist/` or `screenshots/`; build artifacts created by `repoos check` stay local.", `4. When the implementation is ready, finish your response with this exact line: ${HANDOFF_READY_SIGNAL}`, "5. Stop. RepoOS will independently run `repoos check`, commit the implementation, set the worktree task to review, and update the canonical board copy.", "", "If you are blocked or need a decision from the human:", "1. Explain the blocker clearly and do NOT emit the handoff-ready signal.", "2. Leave the task active and STOP so the same worktree/session can be resumed.", "", "Work in turns: finish the requested work, then stop and report. The session can be continued later with follow-up instructions from the user.", "", "## Managed previews are server-owned — never run `repoos serve` yourself", "", "RepoOS owns previews and the control-plane port. Do NOT launch `repoos serve` directly, do not choose a port, and never run a long-lived serve process: direct serve attempts from managed agent processes are rejected. Preview ports and lifecycle are managed for you.", "", "Preview requests are the human's to make, not yours. Do NOT automatically request a preview before handoff or as a routine part of finishing a task. If the human wants to inspect a change in the browser, they request the preview manually from the UI — no action needed from you.", "", "Only use the preview request signal below if the human explicitly asks you to verify something the way a browser would see it (or to confirm your change serves). It is idempotent — repeat requests return the same task preview. Do NOT call the control-plane HTTP API and do NOT use `curl`: your sandbox may have no localhost network access. Instead, include this exact line in your response so RepoOS can start and verify the preview for you:", "", `    ${PREVIEW_REQUEST_SIGNAL}`, "", "RepoOS validates the request against your live run, starts the preview from your worktree, probes it server-side (health + static page), and records the result — the preview URL and the probe outcome — in your task transcript as trusted system entries. You never need a port or localhost.", "", "If the preview fails, RepoOS records an actionable reason in your transcript. Leave the task active and stop so the same worktree/session can be resumed. Do NOT retry the request repeatedly, and never fall back to launching your own server.", "", "If this working directory has no build artifacts yet, build before relying on the `repoos` CLI — it warns when its build is stale.");
+    return parts.join("\n");
+}
+/** Default ceiling on a one-shot agent run (agent rewrites can be slow). */
+const PROMPT_TIMEOUT_MS = 180_000;
+/**
+ * Map an agent `cli` to a one-shot (print mode) invocation that writes its
+ * answer to stdout. opencode: `run`, claude: `-p`, qwen: `-p`, codex:
+ * `exec`. Explicit configured models are forwarded with the driver's model
+ * flag; `default` intentionally omits the flag and lets the CLI resolve it.
+ */
+export function promptCommand(agent, prompt) {
+    const extra = modelArgs(agent.cli, agent.model);
+    if (agent.cli === "claude code")
+        return { cmd: "claude", args: ["-p", prompt, ...extra] };
+    if (agent.cli === "qwen code")
+        return { cmd: "qwen", args: ["-p", prompt, ...extra] };
+    if (agent.cli === "codex")
+        return { cmd: "codex", args: ["exec", prompt, ...extra] };
+    if (agent.cli === "github copilot") {
+        return {
+            cmd: "copilot",
+            // One-shot callers (PM/freeform and model probes) consume the final
+            // response, not the streaming transcript. Keep JSONL exclusive to the
+            // AgentRunner so freeform task parsing receives markdown.
+            args: [
+                "-p",
+                prompt,
+                ...extra,
+                "--no-ask-user",
+                "--no-auto-update",
+                "--no-remote",
+                "--no-remote-export",
+            ],
+        };
+    }
+    if (agent.cli === "kiro") {
+        return {
+            cmd: "kiro-cli",
+            args: ["chat", "--no-interactive", "--trust-all-tools", ...extra, prompt],
+        };
+    }
+    return { cmd: "opencode", args: ["run", ...extra, prompt] };
+}
+/**
+ * Map an agent `cli` to a one-shot PM authoring invocation (0335). Same
+ * print-mode shape as `promptCommand`, with one difference that matters for
+ * the usage tab: structured output flags wherever the driver offers them, so
+ * `runPrompt`'s extractUsage/foldUsage sees real tokens/cost and the initial
+ * PM flesh-out lands in the ledger with figures instead of a blank row —
+ * exactly the treatment the reviewer got in 0273. Unlike `reviewCommand`,
+ * no permission-bypass flags: the PM only authors text (its output is applied
+ * via `patchTaskFile`), so it must not be able to write files or run tools.
+ *
+ * The JSONL/JSON stdout this produces is parsed back to the final answer with
+ * `extractOneShotReportText` and rendered live with `parseOneShotLine` — the
+ * same pairing the reviewer/CTO one-shots use.
+ */
+export function pmCommand(agent, prompt, cwd) {
+    const extra = modelArgs(agent.cli, agent.model);
+    if (agent.cli === "claude code") {
+        // stream-json — the terminal `result` event carries authoritative tokens
+        // and total_cost_usd for the whole turn (0273).
+        return {
+            cmd: "claude",
+            args: [
+                "-p",
+                prompt,
+                ...extra,
+                "--output-format",
+                "stream-json",
+                "--include-partial-messages",
+                "--verbose",
+            ],
+        };
+    }
+    if (agent.cli === "qwen code") {
+        // Mirrors the claude-compatible stream-json so usage is captured.
+        return {
+            cmd: "qwen",
+            args: [
+                "-p",
+                prompt,
+                ...extra,
+                "--output-format",
+                "stream-json",
+                "--include-partial-messages",
+            ],
+        };
+    }
+    if (agent.cli === "codex") {
+        // `--json` streams usage events; the default (read-only) sandbox is the
+        // right blast radius for an authoring pass.
+        return { cmd: "codex", args: ["exec", prompt, ...extra, "--json"] };
+    }
+    if (agent.cli === "github copilot") {
+        // copilotArgs already emits `--output-format json`, so usage is captured;
+        // write:false keeps the authoring pass read-only.
+        return {
+            cmd: "copilot",
+            args: ["-p", prompt, ...extra, ...copilotArgs({ write: false })],
+        };
+    }
+    if (agent.cli === "kiro") {
+        // No structured one-shot mode is verified for kiro — plain chat, matching
+        // `promptCommand` (usage stays unreported for this driver).
+        return {
+            cmd: "kiro-cli",
+            args: ["chat", "--no-interactive", "--trust-all-tools", ...extra, prompt],
+        };
+    }
+    // opencode: `--format json` separates the final answer from step-by-step
+    // narration (0264 vs 0253) and its `step_finish` events carry per-call
+    // usage deltas; `--dir` pins the repo root. Deliberately NO `--auto`: that
+    // flag auto-approves gated tool calls, and the PM must not be able to write
+    // files or run tools. A stray gated call blocks until the run's timeout —
+    // the acceptable failure mode (the draft is kept with its original prompt),
+    // and the same behavior the plain `promptCommand` path had.
+    return {
+        cmd: "opencode",
+        args: ["run", "--format", "json", "--dir", cwd, ...extra, prompt],
+    };
+}
+/**
+ * Map an agent `cli` to a one-shot REVIEW invocation: the agent inspects a
+ * worktree it must not modify and prints its report to stdout.
+ *
+ * Same print-mode shape as `promptCommand`, with one difference that matters:
+ * a reviewer has to READ the worktree (git diff, file reads, maybe the test
+ * suite), and stdin is ignored — so any engine that gates those calls behind a
+ * permission prompt would hang until the timeout instead of reporting. Only
+ * flags already verified for this repo's drivers are used:
+ * - claude code: `--dangerously-skip-permissions` (same reason as the runner's
+ *   start turns — nobody can answer a prompt).
+ * - opencode: `--dir <cwd>` so a linked-worktree path is not auto-rejected,
+ *   plus `--auto` so gated tool calls resolve instead of blocking.
+ * - codex: `exec` alone — its default sandbox is already read-only, which is
+ *   exactly the blast radius a reviewer should have.
+ * - qwen code: plain `-p`, matching `promptCommand`.
+ * - opencode: `--format json`, matching the interactive runner (`cliCommand`
+ *   below). Without it, `run`'s plain-text stdout interleaves the model's
+ *   step-by-step narration ("Let me look at...") with its final answer, and
+ *   nothing separates the two — the whole transcript ends up as the review
+ *   report (0264 vs 0253). `extractOneShotReportText` below picks the final
+ *   text event back out of the JSON stream.
+ */
+export function reviewCommand(agent, prompt, cwd) {
+    const extra = modelArgs(agent.cli, agent.model);
+    if (agent.cli === "claude code") {
+        // stream-json — same structured usage output the engineer's `cliCommand`
+        // uses — so `runPrompt`'s extractUsage/foldUsage sees real tokens/cost and
+        // the reviewer lands in the ledger (0273). The review stays read-only
+        // (no codex-style write sandbox is involved for claude).
+        return {
+            cmd: "claude",
+            args: [
+                "-p",
+                prompt,
+                ...extra,
+                "--output-format",
+                "stream-json",
+                "--include-partial-messages",
+                "--verbose",
+                "--dangerously-skip-permissions",
+            ],
+        };
+    }
+    if (agent.cli === "qwen code") {
+        // Mirrors the engineer's claude-compatible stream-json so usage is captured.
+        return {
+            cmd: "qwen",
+            args: [
+                "-p",
+                prompt,
+                ...extra,
+                "--output-format",
+                "stream-json",
+                "--include-partial-messages",
+            ],
+        };
+    }
+    if (agent.cli === "codex") {
+        // `--json` streams usage events; the default (read-only) sandbox is exactly
+        // the blast radius a reviewer should have — no `--sandbox workspace-write`.
+        return { cmd: "codex", args: ["exec", prompt, ...extra, "--json"] };
+    }
+    if (agent.cli === "github copilot") {
+        // copilotArgs already emits `--output-format json`, so usage is captured.
+        return {
+            cmd: "copilot",
+            args: ["-p", prompt, ...extra, ...copilotArgs({ write: false })],
+        };
+    }
+    if (agent.cli === "kiro") {
+        // Review is read-only; --trust-all-tools still needed so file reads
+        // aren't gated behind a prompt that can never be answered (stdin ignored).
+        return {
+            cmd: "kiro-cli",
+            args: ["chat", "--no-interactive", "--trust-all-tools", ...extra, prompt],
+        };
+    }
+    return {
+        cmd: "opencode",
+        args: ["run", "--format", "json", "--dir", cwd, ...extra, "--auto", prompt],
+    };
+}
+/**
+ * Turn one line of a one-shot (review/CTO) agent's stdout into a transcript
+ * entry for live display. Structured event streams (opencode `--format json`,
+ * claude/qwen stream-json, codex `--json`, copilot json) get the same per-line
+ * parsing the interactive runner applies, so the review transcript reads
+ * cleanly instead of dumping raw JSON. A recognized-but-voiceless structured
+ * event (claude `result`, `system/init`, a thinking-only assistant message …)
+ * returns null so the caller can swallow it; a non-JSON line (warnings, plain
+ * text from kiro) passes through as a plain `{s, d}` entry.
+ */
+export function parseOneShotLine(cli, raw) {
+    let isJson = false;
+    try {
+        isJson = raw.trim().startsWith("{");
+        void JSON.parse(raw);
+    }
+    catch {
+        return { s: "out", d: raw };
+    }
+    if (!isJson)
+        return { s: "out", d: raw };
+    if (cli === "opencode") {
+        const parsed = parseJsonEvent(raw);
+        return parsed ? parsed.entry : null;
+    }
+    if (cli === "claude code") {
+        const parsed = parseClaudeEvent(raw);
+        return parsed?.entry ?? null;
+    }
+    if (cli === "qwen code") {
+        const parsed = parseQwenEvent(raw);
+        return parsed?.entry ?? null;
+    }
+    if (cli === "codex") {
+        const parsed = parseCodexEvent(raw);
+        return parsed?.entry ?? null;
+    }
+    if (cli === "github copilot") {
+        const parsed = parseCopilotEvent(raw);
+        return parsed?.entry ?? null;
+    }
+    return { s: "out", d: raw };
+}
+/**
+ * Isolate the final report/answer from a one-shot agent's full captured
+ * stdout. Structured JSONL engines (opencode `--format json`, claude/qwen
+ * stream-json, codex `--json`, copilot json) carry the model's whole narration
+ * as a sequence of `text` events interleaved with tool calls — the actual final
+ * answer is the LAST `text` event, so this discards the rest (0264 vs 0253).
+ * Non-JSON one-shot CLIs (kiro) print only the final answer, so their raw
+ * output IS the report. Falls back to the raw output if no text event parses,
+ * so a format change never yields an empty report.
+ */
+export function extractOneShotReportText(cli, rawOutput) {
+    const trimmed = rawOutput.trim();
+    if (!trimmed)
+        return trimmed;
+    let last = "";
+    for (const line of trimmed.split("\n")) {
+        if (!line.trim())
+            continue;
+        const entry = parseOneShotLine(cli, line);
+        if (entry && "type" in entry && entry.type === "text")
+            last = entry.text;
+    }
+    return (last || trimmed).trim();
+}
+/**
+ * Run a coding agent once, non-interactively, and capture its full stdout.
+ * Unlike the streaming runner this is synchronous — callers wait for the whole
+ * answer (e.g. freeform task creation). Never throws: failures and timeouts
+ * resolve as `{ ok: false, error }` so an HTTP handler can respond cleanly.
+ *
+ * `onLine` streams each complete stdout line as it arrives (line-buffered, the
+ * same shape the runner uses) so a caller can forward live progress over SSE
+ * without waiting for the run to finish. It is called for real output only —
+ * never for a synthetic failure — and a trailing partial line is flushed on
+ * exit.
+ *
+ * `command` overrides the invocation (default: `promptCommand`) so a caller
+ * that needs different flags — the review agent's read-the-worktree mode —
+ * reuses this spawn/timeout/capture handling instead of duplicating it.
+ * `onSpawn` hands the live child to the caller so it can be killed early.
+ *
+ * The child inherits the server's env verbatim: unlike the streaming runner,
+ * NO `REPOOS_API_URL` / `REPOOS_TASK_ID` is injected, so a one-shot agent has
+ * no pointer at the control plane's task endpoints.
+ */
+export function runPrompt(agent, prompt, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const timeoutMs = opts.timeoutMs ?? PROMPT_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        const { cmd, args } = opts.command ?? promptCommand(agent, prompt);
+        let proc;
+        const startedAt = Date.now();
+        try {
+            proc = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            resolve({ ok: false, error: `could not launch ${cmd}: ${reason}` });
+            return;
+        }
+        opts.onSpawn?.(proc);
+        const out = [];
+        const errOut = [];
+        let pending = "";
+        // The full stdout, folded through the same usage/extract path the streaming
+        // runner uses, so one-shot roles (reviewer/CTO) persist real CLI-reported
+        // tokens/cost instead of zeros (0230). `costUsd` holds Kiro credits when
+        // this is a Kiro session (extractUsage maps its credits footer) — callers
+        // must present it as credits, never as USD.
+        const usage = {};
+        const forwardChunk = (c) => {
+            out.push(c);
+            pending += c.toString("utf8").replace(/\r/g, "\n");
+            const parts = pending.split("\n");
+            pending = parts.pop() ?? "";
+            for (const part of parts) {
+                if (part.length === 0)
+                    continue;
+                // Fold usage regardless of whether a consumer wants live lines, so the
+                // one-shot result always carries CLI-reported tokens/cost (0230).
+                foldUsage(usage, part);
+                opts.onLine?.(part);
+            }
+        };
+        proc.stdout?.on("data", forwardChunk);
+        proc.stderr?.on("data", (c) => errOut.push(c));
+        const timer = setTimeout(() => {
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch {
+                /* already gone */
+            }
+            resolve({
+                ok: false,
+                error: `the ${agent.cli} agent timed out after ${Math.round(timeoutMs / 1000)}s`,
+            });
+        }, timeoutMs);
+        const done = () => {
+            clearTimeout(timer);
+            const elapsedMs = Date.now() - startedAt;
+            // Flush a trailing line with no final newline so nothing is held back.
+            if (opts.onLine && pending.trim()) {
+                foldUsage(usage, pending.trimEnd());
+                opts.onLine(pending.trimEnd());
+            }
+            pending = "";
+            const output = stripAnsi(Buffer.concat(out).toString("utf8").trim());
+            const stderr = Buffer.concat(errOut).toString("utf8").trim();
+            // The line stream may drop usage when a CLI emits no trailing newline, so
+            // fold the full accumulated stdout as a backstop (idempotent via Math.max).
+            foldUsage(usage, output);
+            const usageFields = {
+                elapsedMs,
+                inputTokens: usage.inputTokens,
+                outputTokens: usage.outputTokens,
+                totalTokens: usage.totalTokens,
+                costUsd: usage.costUsd,
+                cacheReadTokens: usage.cacheReadTokens,
+                cacheCreationTokens: usage.cacheCreationTokens,
+                turns: usage.turns,
+            };
+            if (output) {
+                resolve({ ok: true, output, ...usageFields });
+                return;
+            }
+            const reason = stderr ? stderr.split("\n").slice(-3).join(" ").trim() : "no output produced";
+            resolve({ ok: false, error: `${cmd} exited without output: ${reason}`, ...usageFields });
+        };
+        // `close` (not `exit`) fires only after stdio has drained, so a trailing
+        // line with no final newline is still readable when we flush it.
+        proc.on("close", () => done());
+        proc.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ ok: false, error: `could not launch ${cmd}: ${err.message}` });
+        });
+    });
+}
+/**
+ * Persist a one-shot `runPrompt` run to the sessions DB (0311). One-shot AI
+ * work — freeform task/doc authoring, the auto-engineering dispatch pass —
+ * bypasses the AgentRunner, so nothing books it unless the caller does. This
+ * is the shared path for those: it folds the `PromptResult` (elapsed, tokens,
+ * cost) into a session row, classifying `costSource` the same way
+ * `recordSessionToDb` does — a real CLI figure wins, a token-only run gets an
+ * estimate, Kiro credits are never presented as USD. Best-effort: a DB failure
+ * never propagates to the request.
+ *
+ * `taskId` is null for board-level work that belongs to no single task; those
+ * rows still roll into every board-level aggregation (getSessionTypeStats /
+ * getDailyTotals / board summary), just not a task drawer.
+ */
+export function recordOneShotSession(repoRoot, agent, result, opts) {
+    const db = getRepoOSDb(repoRoot);
+    if (!db)
+        return;
+    try {
+        const endedAt = new Date().toISOString();
+        const elapsedMs = result.elapsedMs ?? 0;
+        const totalTokens = result.totalTokens ?? undefined;
+        let costUsd = result.costUsd ?? undefined;
+        let costSource = "none";
+        if (totalTokens && !costUsd) {
+            costUsd = estimateCostUsd(totalTokens);
+            costSource = "estimate";
+        }
+        else if (result.costUsd) {
+            costSource = agent.cli === "kiro" ? "kiro-credits" : "extractUsage";
+        }
+        db.upsertSession({
+            sessionId: opts.sessionId ??
+                `${opts.sessionType}:${opts.taskId ?? "board"}:${endedAt}:${randomUUID()}`,
+            sessionType: opts.sessionType,
+            taskId: opts.taskId ?? undefined,
+            agent: agent.name,
+            model: agent.model,
+            codingAgent: agent.cli,
+            startedAt: new Date(Date.parse(endedAt) - elapsedMs).toISOString(),
+            endedAt,
+            elapsedMs,
+            inputTokens: result.inputTokens ?? undefined,
+            outputTokens: result.outputTokens ?? undefined,
+            totalTokens,
+            cacheReadTokens: result.cacheReadTokens ?? undefined,
+            cacheCreationTokens: result.cacheCreationTokens ?? undefined,
+            turns: result.turns ?? undefined,
+            costUsd,
+            costSource,
+            status: result.ok ? "finished" : "errored",
+            lastActivityAt: endedAt,
+        });
+    }
+    catch {
+        // Database recording is best-effort and must never crash the caller.
+    }
+}
+export class AgentRunner {
+    entries = new Map();
+    sessions = new Map();
+    config;
+    /**
+     * Cap on simultaneously-spawned agent CLI processes — each one may
+     * itself run a build/test worker pool sized to the host's core count, so
+     * unlimited concurrent agents oversubscribe the machine. Configurable via
+     * `maxConcurrentAgents` in repoos.toml; "auto" (unset) sizes it to this
+     * machine's CPU count so the same repo behaves on a laptop and a desktop.
+     */
+    maxConcurrentAgents;
+    /** Ids (taskId or chat sessionId) with a queued start/send waiting for a free slot, mapped to when they were queued. */
+    queuedIds = new Map();
+    /** FIFO of deferred spawns, drained as running agents exit (see cleanup()). */
+    startQueue = [];
+    emit;
+    logger;
+    sessionsDir;
+    cacheDir;
+    logDir;
+    db;
+    writeDelayMs;
+    retentionDays;
+    retentionCount;
+    clock;
+    writeTimers = new Map();
+    pendingCompletion = new Set();
+    /**
+     * The main RepoOS server's own API URL, injected into every agent process so
+     * agents with host networking have an informational pointer at the ACTUAL
+     * control plane, never a hardcoded port. Managed previews are requested by
+     * signal (#0121), so this is not a requirement — it stays for diagnostics
+     * and future HTTP-capable drivers.
+     */
+    apiUrl;
+    stallTimeoutMs;
+    stallTimer;
+    authorizedHandoffs = new Map();
+    handoffsInFlight = new Set();
+    onHandoff;
+    /**
+     * Fired on completion of a durable REVIEW turn (0288) — including for an
+     * entry re-attached after a reload, whose process finishes on the new
+     * server. The owning ReviewManager finalizes the report from this hook
+     * rather than a post-spawn continuation that would die with the old process.
+     * `reviewKind` (run vs chat) and `exitedCleanly` are threaded through so the
+     * ReviewManager can finalize an adopted turn in the right mode and decide
+     * whether it finished cleanly.
+     */
+    onReviewDone;
+    /**
+     * Tasks a human deliberately paused (via POST /api/tasks/:id/pause, 0070).
+     * The task stays `active` with no process, so without this the watchdog would
+     * treat a legitimately-paused task as stuck and disturb it (#0180). In-memory
+     * only: a paused task across a server restart loses the marker and reads as a
+     * stopped agent — the watchdog then surfaces it, which is the correct default
+     * (the paused process is, after all, gone).
+     */
+    pausedTasks = new Set();
+    /**
+     * Preview capabilities minted per clean run (#0121). Superseded when a new
+     * run starts for the same task, so a stale request can never start a preview
+     * against a different worktree.
+     */
+    authorizedPreviews = new Map();
+    onPreviewRequest;
+    /** Resolve a task from the repo task index by ID. Used to populate task/branch on resume turns. */
+    getTask;
+    /**
+     * `opts.stallTimeoutMs` overrides the 90s default (tests use a small value
+     * so stall detection doesn't need a real 90s wait); `opts.stallCheckIntervalMs`
+     * overrides the poll cadence, which otherwise scales with the timeout.
+     */
+    constructor(config, emit, opts = {}) {
+        this.config = config;
+        this.maxConcurrentAgents = config.maxConcurrentAgents ?? defaultMaxConcurrentAgents();
+        this.emit = emit;
+        this.logger = opts.logger;
+        this.onHandoff = opts.onHandoff;
+        this.onPreviewRequest = opts.onPreviewRequest;
+        this.onReviewDone = opts.onReviewDone;
+        this.getTask = opts.getTask;
+        this.db = getRepoOSDb(config.root);
+        this.cacheDir = join(config.root, config.cacheDir);
+        this.sessionsDir = join(this.cacheDir, "sessions");
+        this.logDir = join(this.cacheDir, "agent-logs");
+        this.writeDelayMs = opts.writeDelayMs ?? SESSION_WRITE_DELAY_MS;
+        this.retentionDays = opts.retentionDays ?? SESSION_RETENTION_DAYS;
+        this.retentionCount = opts.retentionCount ?? SESSION_RETENTION_COUNT;
+        this.clock = opts.now ?? (() => new Date());
+        this.stallTimeoutMs = opts.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+        const checkMs = opts.stallCheckIntervalMs ??
+            Math.max(20, Math.min(5000, Math.floor(this.stallTimeoutMs / 3)));
+        this.stallTimer = setInterval(() => this.checkStalls(), checkMs);
+        this.stallTimer.unref();
+        this.loadHotSessions();
+        this.pruneSessions();
+    }
+    /** Stop the stall-check timer (server shutdown / test cleanup). Idempotent. */
+    dispose() {
+        clearInterval(this.stallTimer);
+        for (const entry of this.entries.values()) {
+            for (const tailer of entry.tailers ?? [])
+                clearInterval(tailer.timer);
+        }
+    }
+    /**
+     * Re-attach to agent children that survived a server restart (0214).
+     * Reads the durable registry, checks PID aliveness, and for each still-live
+     * child tail-catches the log file and restores the in-memory entry/session
+     * so `isRunning()` reports true and SSE streaming resumes from this point.
+     * Stale entries (PID dead) are dropped — this must not resurrect dead sessions.
+     */
+    adoptRunningAgents() {
+        const registry = readRegistry(this.cacheDir);
+        const live = [];
+        for (const rec of registry.entries) {
+            if (this.entries.has(rec.taskId))
+                continue;
+            let alive = false;
+            try {
+                process.kill(rec.pid, 0);
+                alive = true;
+            }
+            catch {
+                /* PID is dead — drop it */
+            }
+            const isReview = rec.kind === "review";
+            // A dead non-review entry is stale — drop it (must not resurrect dead
+            // sessions). A DEAD REVIEW entry, however, means the review process
+            // finished sometime during the reload handoff before this process could
+            // adopt it — its durable log still holds the full report, so we replay
+            // it and hand completion to the new ReviewManager (0288). By the time the
+            // deferred hook fires, the server has built `reviews`.
+            if (!alive && !isReview)
+                continue;
+            const outLog = join(this.logDir, `${rec.taskId}.out.log`);
+            const errLog = join(this.logDir, `${rec.taskId}.err.log`);
+            // Restore the session so the transcript is pre-loaded for the task.
+            let session = this.sessions.get(rec.taskId) ?? this.loadSession(rec.taskId);
+            if (!session) {
+                session = this.emptySession();
+                session.workdir = rec.workdir;
+                session.engine = "plain";
+            }
+            session.workdir = rec.workdir;
+            session.turnStartedAt = session.turnStartedAt ?? now();
+            session.lastOutputAt = session.lastOutputAt ?? now();
+            this.sessions.set(rec.taskId, session);
+            // Tail-catch: read any log output written during the handoff gap and
+            // replay it into the session so the transcript isn't missing a chunk.
+            // Separate logs preserve stdout/stderr type during the handoff gap.
+            try {
+                this.replayLog(rec.taskId, outLog, "out");
+                this.replayLog(rec.taskId, errLog, "err");
+                // Compatibility with an early 0214 build that used one tagged log.
+                this.replayLog(rec.taskId, join(this.logDir, `${rec.taskId}.log`), "out", true);
+            }
+            catch {
+                /* best-effort */
+            }
+            if (!alive && isReview) {
+                // The reviewer already finished: finalize its report and drop the entry.
+                this.removeRegistryEntry(rec.taskId);
+                session.accumulatedMs = Date.now() - Date.parse(session.turnStartedAt ?? now());
+                // Defer so `reviews` (and safe handler wiring) exists before we finalize.
+                setTimeout(() => {
+                    try {
+                        this.onReviewDone?.(rec.taskId, false, rec.reviewKind);
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                }, 0);
+                continue;
+            }
+            live.push(rec);
+            // Start tailing the log file for live output, and register a fake Entry
+            // so isRunning() is true and the task reads as in-flight. The real ChildProcess
+            // is referenced by PID, not held directly — we poll for aliveness instead.
+            const tailers = [
+                this.tailLog(rec.taskId, outLog, "out", true),
+                this.tailLog(rec.taskId, errLog, "err", true),
+            ];
+            this.entries.set(rec.taskId, {
+                startedAt: now(),
+                workdir: rec.workdir,
+                task: undefined,
+                branch: rec.branch,
+                runId: rec.runId,
+                handoffRequested: false,
+                previewRequested: false,
+                adoptedPid: rec.pid,
+                review: isReview,
+                reviewKind: rec.kind === "review" ? rec.reviewKind : undefined,
+                tailers,
+            });
+        }
+        if (live.length > 0) {
+            writeRegistry(this.cacheDir, { entries: live });
+        }
+        else {
+            this.clearRegistry();
+        }
+    }
+    /** Replay a durable log into a transcript, optionally decoding the legacy tagged format. */
+    replayLog(taskId, logFile, stream, tagged = false) {
+        if (!existsSync(logFile))
+            return;
+        const data = readFileSync(logFile, "utf8");
+        // Replay rebuilds the transcript only — usage was already folded live and
+        // (for a hot session being re-adopted) re-folding here would double-count,
+        // most visibly the SUM-folded opencode deltas and `turns`. `applyUsage`
+        // still appends to `session_usage_events` (deduped), so no event is lost.
+        this.replayingUsage = true;
+        try {
+            for (const line of data.split("\n")) {
+                if (!line)
+                    continue;
+                if (tagged && line.startsWith("O:"))
+                    this.appendLine(taskId, "out", line.slice(2));
+                else if (tagged && line.startsWith("E:"))
+                    this.appendLine(taskId, "err", line.slice(2));
+                else
+                    this.appendLine(taskId, stream, line);
+            }
+        }
+        finally {
+            this.replayingUsage = false;
+        }
+    }
+    /** True only while `replayLog` is rebuilding a transcript — see `applyUsage`. */
+    replayingUsage = false;
+    /** Tail one durable stream file into the live transcript. */
+    tailLog(taskId, logFile, stream, startAtEnd = false) {
+        // `stat.size` is a byte offset. Keep it in bytes and decode only the new
+        // buffer range; slicing a decoded string with that offset loses output as
+        // soon as an agent writes emoji, CJK, or any other multi-byte UTF-8.
+        let lastSize = 0;
+        let pending = "";
+        let decoder = new StringDecoder("utf8");
+        if (startAtEnd) {
+            try {
+                lastSize = statSync(logFile).size;
+            }
+            catch {
+                /* missing log */
+            }
+        }
+        const drain = () => {
+            try {
+                const currentSize = statSync(logFile).size;
+                // A new turn truncates the same durable log path. Reset both the byte
+                // cursor and decoder rather than treating the truncated file as idle.
+                if (currentSize < lastSize) {
+                    lastSize = 0;
+                    decoder = new StringDecoder("utf8");
+                }
+                if (currentSize > lastSize) {
+                    const data = readFileSync(logFile);
+                    const delta = decoder.write(data.subarray(lastSize));
+                    lastSize = currentSize;
+                    const lines = (pending + delta).replace(/\r/g, "\n").split("\n");
+                    pending = lines.pop() ?? "";
+                    for (const line of lines) {
+                        if (line.length === 0)
+                            continue;
+                        this.appendLine(taskId, stream, line);
+                    }
+                }
+            }
+            catch (err) {
+                /* best-effort on any other error */
+            }
+        };
+        const interval = setInterval(() => {
+            if (!this.entries.has(taskId)) {
+                clearInterval(interval);
+                return;
+            }
+            drain();
+        }, 200);
+        interval.unref();
+        // `pending` is local to this tailer (rather than Session.pending), so a
+        // process that exits without its final newline needs an explicit flush.
+        // Route it through appendLine to preserve structured JSON parsing.
+        const flush = () => {
+            const line = pending.trimEnd();
+            pending = "";
+            if (line)
+                this.appendLine(taskId, stream, line);
+        };
+        return { timer: interval, drain, flush };
+    }
+    /** Persist a registry entry for one running task (0214). */
+    writeRegistryEntry(taskId, pid, workdir, branch, runId, kind, reviewKind) {
+        const registry = readRegistry(this.cacheDir);
+        const existing = registry.entries.findIndex((e) => e.taskId === taskId);
+        const entry = { taskId, pid, workdir, branch, runId, kind, reviewKind };
+        if (existing >= 0) {
+            registry.entries[existing] = entry;
+        }
+        else {
+            registry.entries.push(entry);
+        }
+        writeRegistry(this.cacheDir, registry);
+    }
+    /** Remove a registry entry for a task (0214). */
+    removeRegistryEntry(taskId) {
+        const registry = readRegistry(this.cacheDir);
+        registry.entries = registry.entries.filter((e) => e.taskId !== taskId);
+        writeRegistry(this.cacheDir, registry);
+    }
+    /** Clear the entire durable registry (0214). */
+    clearRegistry() {
+        try {
+            const file = registryPath(this.cacheDir);
+            if (existsSync(file))
+                unlinkSync(file);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    // ---- Pending handoff persistence (#0235) ----
+    /** Persist a handoff request for recovery across process boundaries. */
+    persistPendingHandoff(request) {
+        const store = readPendingHandoffs(this.cacheDir);
+        // Newer run supersedes older one for the same task.
+        store.requests = store.requests.filter((r) => r.taskId !== request.taskId);
+        store.requests.push(request);
+        writePendingHandoffs(this.cacheDir, store);
+    }
+    /** Remove a persisted handoff request (by task id). */
+    clearPendingHandoff(taskId) {
+        const store = readPendingHandoffs(this.cacheDir);
+        const before = store.requests.length;
+        store.requests = store.requests.filter((r) => r.taskId !== taskId);
+        if (store.requests.length < before) {
+            writePendingHandoffs(this.cacheDir, store);
+        }
+    }
+    /**
+     * Recover persisted handoff requests at server boot. Validates each request
+     * (task still exists, still active, branch matches, not already finalizing)
+     * and re-fires onHandoff for valid ones. Idempotent: a request already in
+     * handoffsInFlight is skipped.
+     */
+    recoverPendingHandoffs() {
+        const store = readPendingHandoffs(this.cacheDir);
+        if (store.requests.length === 0)
+            return;
+        for (const request of store.requests) {
+            if (this.handoffsInFlight.has(request.taskId))
+                continue;
+            // Validate: task must still exist and be active, branch must match.
+            const task = this.getTask?.(request.taskId) ?? null;
+            if (!task) {
+                this.clearPendingHandoff(request.taskId);
+                continue;
+            }
+            if (task.status !== "active") {
+                this.clearPendingHandoff(request.taskId);
+                continue;
+            }
+            if (task.branch !== request.branch) {
+                this.clearPendingHandoff(request.taskId);
+                continue;
+            }
+            // Admit to the authorized-capability map so the server's
+            // consumeHandoff validation (server.ts onHandoff) succeeds. The normal
+            // clean-exit path does the same in cleanup().
+            this.authorizedHandoffs.set(request.runId, request);
+            // Move to in-flight before firing so concurrent checks see it.
+            this.handoffsInFlight.add(request.taskId);
+            // Clear the persisted entry so a later boot does not re-fire the same
+            // request. If finalization ultimately fails, the task stays active and
+            // can be resumed manually.
+            this.clearPendingHandoff(request.taskId);
+            // Ensure the session is loaded so system()/appendLine() can write to
+            // the transcript.  For a dead-interrupted task, adoptRunningAgents only
+            // pre-loads sessions for live PIDs — the interrupted-turn session is on
+            // disk but not yet in memory (#0235 review fix).
+            if (!this.sessions.has(request.taskId)) {
+                const loaded = this.loadSession(request.taskId);
+                if (loaded)
+                    this.sessions.set(request.taskId, loaded);
+            }
+            // Surface in the transcript so the human sees recovery.
+            this.system(request.taskId, "Recovering pending handoff from interrupted turn — finalizing now");
+            void Promise.resolve(this.onHandoff?.(request))
+                .catch((err) => {
+                this.appendLine(request.taskId, "sys", `✗ recovered handoff failed: ${err.message}`);
+            })
+                .finally(() => {
+                this.handoffsInFlight.delete(request.taskId);
+                // If the server handler rejected (consumeHandoff denied, or a
+                // concurrent finalization was already in flight), the capability
+                // was never consumed — remove it so it does not leak and confuse
+                // a later validateHandoff check.
+                if (this.authorizedHandoffs.has(request.runId)) {
+                    this.authorizedHandoffs.delete(request.runId);
+                }
+                // If the task is still active after recovery, record the outcome in
+                // the Activity log so the watchdog's HANDOFF_RETAINED guard can
+                // unstick it: without this, the retained line permanently blocks
+                // auto-surface/escalation even when recovery has already been
+                // attempted and failed (#0235 review fix).
+                const task = this.getTask?.(request.taskId) ?? null;
+                if (task && task.status === "active") {
+                    this.persistHandoffFailure(request.taskId, task, "handoff recovery attempted · finalization failed");
+                }
+            });
+        }
+    }
+    /** Append trusted server orchestration progress to the retained transcript. */
+    system(taskId, text) {
+        this.appendLine(taskId, "sys", text);
+    }
+    /** Validate that a handoff capability was minted by a successful active turn. */
+    validateHandoff(request) {
+        const issued = this.authorizedHandoffs.get(request.runId);
+        return Boolean(issued &&
+            issued.taskId === request.taskId &&
+            issued.branch === request.branch &&
+            this.samePath(issued.workdir, request.workdir) &&
+            issued.sessionId === request.sessionId);
+    }
+    /** Validate and expire one runner-issued handoff capability atomically. */
+    consumeHandoff(request) {
+        if (!this.validateHandoff(request))
+            return false;
+        this.authorizedHandoffs.delete(request.runId);
+        return true;
+    }
+    /**
+     * Validate that a preview capability was minted by a real, current runner
+     * turn (#0121). The capability carries the task id, the run id issued for
+     * that turn, the registered branch, and the registered worktree — a forged,
+     * expired (superseded by a newer run), cross-task, or path-substituted
+     * request never matches all four.
+     */
+    validatePreview(request) {
+        const issued = this.authorizedPreviews.get(request.runId);
+        return Boolean(issued &&
+            issued.taskId === request.taskId &&
+            issued.branch === request.branch &&
+            this.samePath(issued.workdir, request.workdir) &&
+            issued.sessionId === request.sessionId);
+    }
+    isRunning(taskId) {
+        return this.entries.has(taskId);
+    }
+    /**
+     * The review turn kind ("run" | "chat") of a durable review session, if the
+     * entry is one (0288). Used by ReviewManager to finalize an ADOPTED turn in
+     * the right mode — the session's own `Run` record is not carried across a
+     * reload, but its review kind is (persisted in the registry).
+     */
+    reviewKindOf(sessionKey) {
+        return this.entries.get(sessionKey)?.reviewKind;
+    }
+    /**
+     * Record a deliberate human pause (0070): the task stays `active` but its
+     * agent is intentionally stopped, so the watchdog must not touch it (#0180).
+     * Cleared automatically the moment a new turn starts for the task.
+     */
+    markPaused(taskId) {
+        this.pausedTasks.add(taskId);
+    }
+    /** True when the task was explicitly paused and no new turn has started since. */
+    isPaused(taskId) {
+        return this.pausedTasks.has(taskId);
+    }
+    /**
+     * True while the server-side handoff for a task is still finalizing (check,
+     * commit, review). The process is already gone, so `isRunning` is false, but
+     * the task is not stuck — the close-out pipeline owns it for a few seconds.
+     */
+    isHandoffInFlight(taskId) {
+        return this.handoffsInFlight.has(taskId);
+    }
+    /** Live run telemetry for a task's session — zeros/nulls when none exists yet. */
+    stats(taskId) {
+        return this.snapshotStats(taskId);
+    }
+    running() {
+        const out = [];
+        for (const [id, e] of this.entries) {
+            out.push({
+                id,
+                pid: e.adoptedPid ?? e.proc?.pid ?? -1,
+                startedAt: e.startedAt,
+                workdir: e.workdir,
+            });
+        }
+        return out;
+    }
+    /** Query historical stats for a task from the database. */
+    taskStats(taskId) {
+        return this.db?.getTaskStats(taskId) ?? null;
+    }
+    /** Query historical stats grouped by session type from the database. */
+    sessionTypeStats() {
+        return this.db?.getSessionTypeStats() ?? [];
+    }
+    /** Per-day usage totals (server's local time). */
+    dailyTotals() {
+        return this.db?.getDailyTotals() ?? [];
+    }
+    /** Query board-level summary stats from the database, optionally scoped to a usage range (0334). */
+    boardStats(range = "all") {
+        return this.db?.getBoardStats(range) ?? null;
+    }
+    /**
+     * Spawn the coding agent on the task. Never blocks — the child runs
+     * detached from the HTTP response. Returns a StartResult describing the
+     * launch attempt; an async spawn failure is emitted as agent.exited.
+     *
+     * `opts.cwd` is the task's worktree directory when one was provisioned;
+     * defaults to the repo root so launch still works (best-effort) when
+     * worktree setup failed or the task's branch is the main checkout.
+     */
+    start(task, branch, agent, opts = {}) {
+        if (this.entries.has(task.id) ||
+            this.handoffsInFlight.has(task.id) ||
+            this.queuedIds.has(task.id)) {
+            return { ok: false, reason: "task is already running or finalizing" };
+        }
+        const cwd = opts.cwd ?? this.config.root;
+        const session = this.sessions.get(task.id) ?? this.loadSession(task.id) ?? this.emptySession();
+        this.captureUsageBaseline(session);
+        session.workdir = cwd;
+        session.engine = engineForCli(agent.cli);
+        session.task = task;
+        session.branch = branch;
+        session.agent = agent.name;
+        session.model = agent.model;
+        this.sessions.set(task.id, session);
+        const selectedSkills = selectSkillsForRun(task, agent, this.config);
+        // Only note it in the transcript when a skill was actually injected — a
+        // "no skills selected" line on every single run is pure noise, and nothing
+        // downstream keys off its presence.
+        if (selectedSkills.length) {
+            this.recordEntry(task.id, session, "sys", {
+                s: "sys",
+                d: `Skill routing: ${selectedSkills.map((skill) => skill.name).join(", ")}`,
+            });
+        }
+        const mission = missionFor(task, branch, cwd, agent, this.config, opts.contextPack, opts.resumePreamble, selectedSkills);
+        const { cmd, args } = cliCommand(agent, mission, cwd);
+        return this.spawnOrQueue(task.id, cmd, args, cwd, task, branch);
+    }
+    /** Start a persistent, non-task conversation with an explicit role mission. */
+    startChat(sessionId, text, agent, repositoryContext, promptBuilder = repoGuidePrompt) {
+        if (this.entries.has(sessionId) || this.queuedIds.has(sessionId)) {
+            return {
+                ok: false,
+                busy: true,
+                reason: "agent is busy — wait for the current turn to finish",
+            };
+        }
+        if (this.sessions.has(sessionId)) {
+            return { ok: false, reason: "conversation already exists — send a follow-up instead" };
+        }
+        const human = { type: "human", text, at: new Date().toISOString() };
+        const session = {
+            lines: [human],
+            pending: "",
+            bytes: entryBytes(human),
+            workdir: this.config.root,
+            engine: engineForCli(agent.cli),
+            agent: agent.name,
+            model: agent.model,
+            accumulatedMs: 0,
+            stalledEmitted: false,
+        };
+        this.sessions.set(sessionId, session);
+        const mission = agent.name === DEBUGGER_NAME
+            ? debuggerPrompt(text, repositoryContext, agent)
+            : promptBuilder(text, repositoryContext, agent);
+        const { cmd, args } = cliCommand(agent, mission, this.config.root);
+        return this.spawnOrQueue(sessionId, cmd, args, this.config.root);
+    }
+    /**
+     * Spawn a durable REVIEW turn under a synthetic session key (0288), so the
+     * reviewer survives a server reload the same way engineer/PM turns do: the
+     * child's stdout/stderr stream to durable log files and its PID is registered
+     * so the next server's `adoptRunningAgents()` re-attaches and replays any
+     * output written during the handoff. On completion — even post-reload —
+     * `cleanup()` fires `onReviewDone` for the owning ReviewManager to finalize.
+     *
+     * Unlike `start`/`send`, the review agent is deliberately NOT given
+     * `REPOOS_TASK_ID` / `REPOOS_API_URL`, preserving the read-only boundary that
+     * keeps it from reaching the control plane's task endpoints (review.ts layer
+     * 2). `kind: "review"` is persisted in the durable registry so adoption knows
+     * to re-attach as a review.
+     *
+     * `reset: true` (a fresh run) clears any prior conversation; a chat turn
+     * (`reset: false`, with `humanEntry`) continues the existing one.
+     */
+    startReview(sessionKey, agent, mission, cwd, opts = {}) {
+        if (this.entries.has(sessionKey)) {
+            return { ok: false, busy: true, reason: "a review is already running for this task" };
+        }
+        let session = this.sessions.get(sessionKey) ?? this.loadSession(sessionKey);
+        if (!session || opts.reset) {
+            session = this.emptySession();
+        }
+        if (opts.reset) {
+            session.lines = [];
+            session.bytes = 0;
+        }
+        session.workdir = cwd;
+        session.engine = engineForCli(agent.cli);
+        session.agent = agent.name;
+        session.model = agent.model;
+        if (opts.humanEntry) {
+            session.lines.push(opts.humanEntry);
+            session.bytes += entryBytes(opts.humanEntry);
+            while (session.bytes > OUTPUT_CAP_BYTES) {
+                const dropped = session.lines.shift();
+                if (!dropped)
+                    break;
+                session.bytes -= entryBytes(dropped);
+            }
+        }
+        this.sessions.set(sessionKey, session);
+        const { cmd, args } = reviewCommand(agent, mission, cwd);
+        return this.spawnTurn(sessionKey, cmd, args, cwd, undefined, "", {
+            review: true,
+            reviewKind: opts.reviewKind ?? "run",
+        });
+    }
+    /** Release a durable review session from the in-memory map (its file stays). */
+    discardReviewSession(sessionKey) {
+        this.sessions.delete(sessionKey);
+    }
+    /**
+     * Send a follow-up message to a task's session, resuming the same
+     * conversation as a new turn. Rejected when the task has no session yet
+     * (`ok: false`) or when a turn is already running (`ok: false, busy: true`).
+     */
+    send(taskId, text, agent, opts = {}) {
+        // Completed/non-task conversations are deliberately not preloaded at boot.
+        // Hydrate one on demand so a persisted RepoOS Guide transcript can resume
+        // after a server reload instead of being visible-but-unsendable.
+        const session = this.sessions.get(taskId) ?? this.loadSession(taskId);
+        if (!session) {
+            return { ok: false, reason: "no session for this task — start work first" };
+        }
+        if (this.entries.has(taskId) ||
+            this.handoffsInFlight.has(taskId) ||
+            this.queuedIds.has(taskId)) {
+            return {
+                ok: false,
+                busy: true,
+                reason: "agent is busy — wait for the current turn or handoff to finish",
+            };
+        }
+        this.sessions.set(taskId, session);
+        this.captureUsageBaseline(session);
+        const entry = { type: "human", text, at: new Date().toISOString() };
+        session.lines.push(entry);
+        session.bytes += entryBytes(entry);
+        while (session.bytes > OUTPUT_CAP_BYTES) {
+            const dropped = session.lines.shift();
+            if (!dropped)
+                break;
+            session.bytes -= entryBytes(dropped);
+        }
+        this.schedulePersist(taskId);
+        // On resume turns, resolve the task from the index if not already set in the session.
+        // This ensures task/branch are always available for handoff finalization.
+        if (!session.task && this.getTask) {
+            const resolvedTask = this.getTask(taskId);
+            if (resolvedTask) {
+                session.task = resolvedTask;
+                session.branch = resolvedTask.branch;
+            }
+        }
+        const fullText = opts.resumePreamble ? `${opts.resumePreamble}\n\n${text}` : text;
+        // session.sessionId is only meaningful to the CLI that produced it — if
+        // agent.cli has since changed (override edited/cleared between turns),
+        // reusing it would hand one CLI's session id to a different CLI's
+        // --resume flag (e.g. an opencode `ses_...` id passed to `claude
+        // --resume`, which requires a UUID and errors out). Drop it and let
+        // resumeCommand fall back to a fresh/most-recent-session start instead.
+        const sessionId = session.engine === engineForCli(agent.cli) ? session.sessionId : undefined;
+        const { cmd, args } = resumeCommand(agent, fullText, sessionId, session.workdir ?? this.config.root);
+        return this.spawnOrQueue(taskId, cmd, args, session.workdir ?? this.config.root, session.task, session.branch, { skipBoardDivergence: opts.skipBoardDivergence });
+    }
+    /** The retained transcript for a task, or null when no session exists. */
+    output(taskId) {
+        return this.sessions.get(taskId) ?? this.loadSession(taskId);
+    }
+    /** Whether a session exists for a key (in memory or persisted on disk). */
+    hasSession(sessionKey) {
+        return this.sessions.has(sessionKey) || this.readPersisted(sessionKey) !== null;
+    }
+    /** Drop a session both in memory and from disk (a fresh review run). */
+    clearSession(sessionKey) {
+        this.sessions.delete(sessionKey);
+        const file = this.sessionFile(sessionKey);
+        if (file && existsSync(file)) {
+            try {
+                unlinkSync(file);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    /**
+     * Mark a task transcript complete and release its RAM. If its child is still
+     * draining after a stop request, cleanup performs the final flush/eviction.
+     */
+    complete(taskId) {
+        // Task is leaving active — clear any persisted handoff (#0235).
+        this.clearPendingHandoff(taskId);
+        for (const [runId, req] of this.authorizedPreviews) {
+            if (req.taskId === taskId)
+                this.authorizedPreviews.delete(runId);
+        }
+        if (this.entries.has(taskId)) {
+            this.pendingCompletion.add(taskId);
+            return;
+        }
+        this.finishCompletion(taskId);
+    }
+    /** Flush all debounced transcript writes before shutdown/reload handover. */
+    flushAll() {
+        for (const taskId of this.writeTimers.keys())
+            this.persist(taskId);
+    }
+    /**
+     * Gate for every spawnTurn call site: at capacity, defer the spawn
+     * instead of oversubscribing the machine. The caller still gets `ok: true`
+     * immediately — `queued: true` distinguishes "will run shortly" from
+     * "running now" without changing callers' happy-path handling. `id` is
+     * marked busy via queuedIds so a second start/send for the same task/chat
+     * while queued is rejected the same way an already-running one would be.
+     */
+    spawnOrQueue(id, cmd, args, cwd, task, branch, opts = {}) {
+        if (this.entries.size < this.maxConcurrentAgents) {
+            return this.spawnTurn(id, cmd, args, cwd, task, branch, opts);
+        }
+        this.queuedIds.set(id, now());
+        this.startQueue.push(() => {
+            this.queuedIds.delete(id);
+            this.emit({ type: "agent.dequeued", id, at: now() });
+            this.spawnTurn(id, cmd, args, cwd, task, branch, opts);
+        });
+        this.logger?.agent(id, "info", `Queued — ${this.entries.size}/${this.maxConcurrentAgents} agent processes already running.`);
+        this.emit({ type: "agent.queued", id, at: now() });
+        return { ok: true, queued: true };
+    }
+    /** Tasks/chats currently waiting for a free maxConcurrentAgents slot. */
+    queued() {
+        return Array.from(this.queuedIds.entries()).map(([id, queuedAt]) => ({ id, queuedAt }));
+    }
+    /** Start the next queued spawn once a slot is free (called from cleanup() on every exit). */
+    drainQueue() {
+        while (this.startQueue.length > 0 && this.entries.size < this.maxConcurrentAgents) {
+            const next = this.startQueue.shift();
+            next?.();
+        }
+    }
+    /**
+     * Spawn one turn and attach streaming. Everything after the spawn is async;
+     * failures surface as agent.exited via cleanup.
+     */
+    spawnTurn(taskId, cmd, args, cwd, task, branch, opts = {}) {
+        const runId = randomUUID();
+        // A new turn means the task is active again — a human restarted a paused
+        // task, or sent a follow-up — so the pause marker no longer applies.
+        this.pausedTasks.delete(taskId);
+        // A new turn supersedes any persisted handoff from a previous turn (#0235).
+        this.clearPendingHandoff(taskId);
+        // A new run supersedes the previous run's preview capability for this task
+        // (#0121): a capability minted for an older run is expired the moment a
+        // newer turn claims the task.
+        for (const [prevRunId, req] of this.authorizedPreviews) {
+            if (req.taskId === taskId)
+                this.authorizedPreviews.delete(prevRunId);
+        }
+        const outLog = join(this.logDir, `${taskId}.out.log`);
+        const errLog = join(this.logDir, `${taskId}.err.log`);
+        let outFd;
+        let errFd;
+        let proc;
+        try {
+            // Give the child file descriptors, not pipes owned by this server. The
+            // child keeps those descriptors when this process exits during reload,
+            // so subsequent output cannot fail with EPIPE.
+            mkdirSync(this.logDir, { recursive: true });
+            outFd = openSync(outLog, "w");
+            errFd = openSync(errLog, "w");
+            // REPOOS_AGENT=1 marks every managed agent process so the CLI's defense
+            // in depth can reject an accidental direct `repoos serve` attempt, and
+            // REPOOS_TASK_ID/REPOOS_RUN_ID let the runner bind any capability-request
+            // signal to this exact turn. REPOOS_API_URL is kept as an informational
+            // pointer at the control plane (ADR-0005: agents express intent, RepoOS
+            // owns privileged process/network lifecycle) — managed previews are
+            // requested by signal, never by a sandboxed localhost call (#0121).
+            // A managed agent is, by definition, never a preview child or a reload
+            // replacement. Scrub the control-plane's lifecycle markers and reload
+            // secret before they can leak into the agent (and from it into the
+            // #0096 agent-serve-guard test, where REPOOS_RELOAD=1 would exempt the
+            // child from the direct-serve guard and hang the test).
+            const agentEnv = { ...process.env };
+            delete agentEnv.REPOOS_RELOAD;
+            delete agentEnv.REPOOS_RELOAD_SECRET;
+            delete agentEnv.REPOOS_PREVIEW_CHILD;
+            agentEnv.REPOOS_AGENT = "1";
+            // A REVIEW turn is deliberately read-only: unlike the engineer/PM, it is
+            // NOT given REPOOS_TASK_ID / REPOOS_API_URL, so it has no pointer at the
+            // control plane's task endpoints and cannot reach /done (review.ts layer
+            // 2). REPOOS_RUN_ID is still bound so any capability-request signal (none
+            // expected) would route to this exact run.
+            if (!opts.review)
+                agentEnv.REPOOS_TASK_ID = taskId;
+            agentEnv.REPOOS_RUN_ID = runId;
+            if (this.apiUrl && !opts.review)
+                agentEnv.REPOOS_API_URL = this.apiUrl;
+            proc = spawn(cmd, args, {
+                cwd,
+                stdio: ["ignore", outFd, errFd],
+                env: agentEnv,
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            this.logger?.agent(taskId, "error", `Failed to spawn agent: ${reason}`, { cmd, args });
+            this.emit({ type: "agent.exited", id: taskId, at: now() });
+            return { ok: false, reason };
+        }
+        finally {
+            // spawn duplicates the descriptors into the child. The parent's copies
+            // are no longer needed and must not keep the files artificially open.
+            if (outFd !== undefined)
+                closeSync(outFd);
+            if (errFd !== undefined)
+                closeSync(errFd);
+        }
+        const tailers = [this.tailLog(taskId, outLog, "out"), this.tailLog(taskId, errLog, "err")];
+        this.entries.set(taskId, {
+            proc,
+            startedAt: now(),
+            workdir: cwd,
+            task,
+            branch: branch ?? task?.branch ?? "",
+            runId,
+            handoffRequested: false,
+            previewRequested: false,
+            skipBoardDivergence: opts.skipBoardDivergence,
+            review: opts.review,
+            reviewKind: opts.review ? opts.reviewKind : undefined,
+            tailers,
+        });
+        // Turn-start bookkeeping for the live stats readout (0080): the silence
+        // clock resets here too, not just on output, so a follow-up turn on a
+        // session that's been idle in `review` for hours doesn't immediately read
+        // as "stalled" before the freshly-spawned process has had a chance to
+        // produce a single line.
+        const session = this.sessions.get(taskId);
+        if (session) {
+            session.turnStartedAt = now();
+            session.lastOutputAt = now();
+            session.stalledEmitted = false;
+        }
+        // Persist the durable registry entry so a restart can re-attach (0214).
+        if (proc.pid) {
+            this.writeRegistryEntry(taskId, proc.pid, cwd, branch ?? task?.branch ?? "", runId, opts.review ? "review" : "engineer", opts.review ? opts.reviewKind : undefined);
+        }
+        // Either path means the run is over: natural exit, spawn error (e.g. the
+        // CLI isn't installed), or our own SIGKILL after a graceful pause. `close`
+        // (not `exit`) fires only after stdio has drained, so a trailing line with
+        // no final newline is still in `pending` when cleanup flushes it.
+        const finishTurn = (code) => {
+            // The final write can arrive just before close, before the next polling
+            // tick. Drain synchronously so no trailing output is lost.
+            for (const tailer of this.entries.get(taskId)?.tailers ?? [])
+                tailer.drain();
+            this.cleanup(taskId, code === 0);
+        };
+        proc.on("close", finishTurn);
+        proc.on("error", () => this.cleanup(taskId, false));
+        // A very short-lived command can exit between `spawn()` and listener
+        // registration. ChildProcess does not replay a missed `close` event, so
+        // finalize it explicitly instead of leaving its last log line and runner
+        // entry behind forever.
+        if (proc.exitCode !== null)
+            finishTurn(proc.exitCode);
+        this.logger?.agent(taskId, "info", "Agent started", { pid: proc.pid, cwd, cmd });
+        this.emit({
+            type: "agent.running",
+            id: taskId,
+            at: this.entries.get(taskId)?.startedAt ?? now(),
+        });
+        this.emitStats(taskId);
+        return { ok: true, pid: proc.pid };
+    }
+    /** Line-buffer a chunk into the session transcript and stream it out. */
+    onData(taskId, stream, chunk) {
+        const session = this.sessions.get(taskId);
+        if (!session)
+            return;
+        session.pending += chunk.toString("utf8").replace(/\r/g, "\n");
+        const parts = session.pending.split("\n");
+        session.pending = parts.pop() ?? "";
+        for (const raw of parts) {
+            if (raw.length === 0)
+                continue;
+            this.appendLine(taskId, stream, raw);
+        }
+    }
+    /** Turn one buffered line into a transcript entry and stream it out. */
+    appendLine(taskId, stream, raw) {
+        const session = this.sessions.get(taskId);
+        if (!session)
+            return;
+        // claude's stream-json event shapes (nested under `message.content[]`)
+        // differ from opencode's `part` shapes, so it gets its own parser branch
+        // rather than a merged parser sniffing both (0109).
+        if (stream === "out" && session.engine === "claude") {
+            this.appendClaudeLine(taskId, session, raw);
+            return;
+        }
+        if (stream === "out" && session.engine === "copilot") {
+            this.appendCopilotLine(taskId, session, raw);
+            return;
+        }
+        if (stream === "out" && session.engine === "qwen") {
+            this.appendClaudeLine(taskId, session, raw, parseQwenEvent);
+            return;
+        }
+        if (stream === "out" && session.engine === "codex") {
+            this.appendCodexLine(taskId, session, raw);
+            return;
+        }
+        const parsed = stream === "out" && session.engine === "opencode" ? parseJsonEvent(raw) : null;
+        let entry;
+        if (parsed) {
+            if (parsed.sessionID && !session.sessionId)
+                session.sessionId = parsed.sessionID;
+            entry = parsed.entry;
+        }
+        else {
+            // Plain line: qwen / codex output, malformed JSON, anything on stderr,
+            // or a `sys` notice. Keep the legacy `{s,d}` shape and the regex
+            // session-id extraction (opencode's session-id event, unknown schemas).
+            entry = { s: stream, d: raw };
+            this.tryExtractSessionId(raw, session);
+        }
+        if (stream === "out") {
+            entry = this.applySignals(taskId, raw, entry, session);
+        }
+        this.recordEntry(taskId, session, stream, entry);
+        this.lineTouched(taskId, session, raw);
+    }
+    /**
+     * Append a transcript entry, stream it out, and enforce the output cap.
+     * `sys` entries (self-heal notices) flow on the "out" stream, matching how
+     * parsed `error`/`file-update` events already surface as sys lines.
+     */
+    recordEntry(taskId, session, stream, entry) {
+        const stamped = entry.at ? entry : { ...entry, at: new Date().toISOString() };
+        session.lines.push(stamped);
+        session.bytes += entryBytes(stamped);
+        this.emit({
+            type: "agent.output",
+            id: taskId,
+            entry: stamped,
+            stream: stream === "sys" ? "out" : stream,
+            at: now(),
+        });
+        while (session.bytes > OUTPUT_CAP_BYTES) {
+            const dropped = session.lines.shift();
+            if (!dropped)
+                break;
+            session.bytes -= entryBytes(dropped);
+        }
+        this.schedulePersist(taskId);
+    }
+    /**
+     * Per-line bookkeeping shared by every append path: fold any usage/cost the
+     * line reported into the session and reset the stall clock. Any output is
+     * evidence the process isn't hung, so it resets the silence clock and clears
+     * a stall warning immediately — the periodic check only ever needs to raise
+     * the flag, never lower it.
+     */
+    lineTouched(taskId, session, raw) {
+        const usageChanged = this.applyUsage(taskId, session, raw);
+        session.lastOutputAt = now();
+        const stallCleared = session.stalledEmitted;
+        session.stalledEmitted = false;
+        if (usageChanged || stallCleared)
+            this.emitStats(taskId);
+    }
+    /**
+     * The claude stream-json branch of `appendLine` (0109). Recognized events
+     * map onto structured entries, or are swallowed when they have no transcript
+     * representation; anything else (a non-JSON `Warning: no stdin…` line, an
+     * unknown schema) falls back to the plain-line path so nothing the CLI said
+     * is lost.
+     */
+    appendClaudeLine(taskId, session, raw, parser = parseClaudeEvent) {
+        const parsed = parser(raw);
+        if (!parsed) {
+            const entry = { s: "out", d: raw };
+            this.tryExtractSessionId(raw, session);
+            this.recordEntry(taskId, session, "out", this.applySignals(taskId, raw, entry, session));
+            this.lineTouched(taskId, session, raw);
+            return;
+        }
+        if (parsed.sessionID && !session.sessionId)
+            session.sessionId = parsed.sessionID;
+        if (parsed.pendingTool) {
+            // A tool call with its result still to come: buffer it and emit the card
+            // only when the matching tool_result line arrives, so it carries name +
+            // input + output together. If a second call starts before the first
+            // resolved, flush the stale one without its output so it isn't lost.
+            if (session.pendingTool && session.pendingTool.id !== parsed.pendingTool.id) {
+                this.recordEntry(taskId, session, "out", this.pendingToolEntry(session.pendingTool));
+            }
+            session.pendingTool = parsed.pendingTool;
+        }
+        else if (parsed.toolResult) {
+            const pending = session.pendingTool && session.pendingTool.id === parsed.toolResult.id
+                ? session.pendingTool
+                : undefined;
+            if (pending) {
+                session.pendingTool = undefined;
+                this.recordEntry(taskId, session, "out", {
+                    type: "tool",
+                    tool: pending.name,
+                    ...(pending.input ? { input: pending.input } : {}),
+                    ...(parsed.toolResult.content ? { output: parsed.toolResult.content } : {}),
+                    ...(parsed.toolResult.isError ? { state: "error" } : {}),
+                });
+            }
+            // An orphaned tool_result (an id we never saw a tool_use for) has
+            // nothing to attach to — drop it rather than fabricate a tool card.
+        }
+        else if (parsed.entry) {
+            this.recordEntry(taskId, session, "out", this.applySignals(taskId, raw, parsed.entry, session));
+        }
+        // Otherwise the line was a recognized-but-voiceless claude event (init,
+        // rate_limit, thinking-only assistant message, terminal `result`) — it is
+        // swallowed rather than dumped into the transcript as raw JSON.
+        this.lineTouched(taskId, session, raw);
+    }
+    /** Copilot's JSONL branch; unlike Claude, tool start/finish events stand alone. */
+    appendCopilotLine(taskId, session, raw) {
+        const parsed = parseCopilotEvent(raw);
+        if (!parsed) {
+            const entry = { s: "out", d: raw };
+            this.tryExtractSessionId(raw, session);
+            this.recordEntry(taskId, session, "out", this.applySignals(taskId, raw, entry, session));
+            this.lineTouched(taskId, session, raw);
+            return;
+        }
+        if (parsed.sessionID && !session.sessionId)
+            session.sessionId = parsed.sessionID;
+        if (parsed.entry) {
+            this.recordEntry(taskId, session, "out", this.applySignals(taskId, raw, parsed.entry, session));
+        }
+        this.lineTouched(taskId, session, raw);
+    }
+    /** Codex has one completed item per tool/message rather than Claude blocks. */
+    appendCodexLine(taskId, session, raw) {
+        const parsed = parseCodexEvent(raw);
+        if (!parsed) {
+            const entry = { s: "out", d: raw };
+            this.tryExtractSessionId(raw, session);
+            this.recordEntry(taskId, session, "out", this.applySignals(taskId, raw, entry, session));
+            this.lineTouched(taskId, session, raw);
+            return;
+        }
+        if (parsed.sessionID && !session.sessionId)
+            session.sessionId = parsed.sessionID;
+        if (parsed.entry) {
+            this.recordEntry(taskId, session, "out", this.applySignals(taskId, raw, parsed.entry, session));
+        }
+        this.lineTouched(taskId, session, raw);
+    }
+    /** The transcript entry for a tool_use whose result never arrived. */
+    pendingToolEntry(pending) {
+        return {
+            type: "tool",
+            tool: pending.name,
+            ...(pending.input ? { input: pending.input } : {}),
+        };
+    }
+    /**
+     * Whether a raw line carries the exact capability-request `signal` in plain
+     * or structured output. Codex `--json` wraps the final assistant response in
+     * an `item.completed` event, so the signal is matched inside `item.text` too,
+     * not just as a standalone line.
+     */
+    signalPresent(raw, entry, signal) {
+        if (raw.trim() === signal)
+            return true;
+        if ("type" in entry &&
+            entry.type === "text" &&
+            entry.text.split("\n").some((line) => line.trim() === signal))
+            return true;
+        try {
+            const event = JSON.parse(raw);
+            return (event.type === "item.completed" &&
+                event.item?.type === "agent_message" &&
+                typeof event.item.text === "string" &&
+                event.item.text.split("\n").some((line) => line.trim() === signal));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Recognize the exact handoff-request signal in plain or structured output. */
+    isHandoffSignal(raw, entry) {
+        return this.signalPresent(raw, entry, HANDOFF_READY_SIGNAL);
+    }
+    /** Recognize the exact managed-preview request signal (#0121). */
+    isPreviewRequestSignal(raw, entry) {
+        return this.signalPresent(raw, entry, PREVIEW_REQUEST_SIGNAL);
+    }
+    /**
+     * Detect the runner's capability-request signals in one output line and act:
+     * the handoff signal is recorded for turn-end finalization, and the preview
+     * request is recorded for server-side start+probe at turn exit (#0121). The
+     * surfaced entry becomes a trusted system line so the raw signal text never
+     * clutters the transcript.
+     *
+     * When a handoff signal is recognized (#0235), the request is persisted to
+     * disk immediately so it survives an interrupted turn or server restart.
+     */
+    applySignals(taskId, raw, entry, session) {
+        let out = entry;
+        if (this.isPreviewRequestSignal(raw, entry)) {
+            const running = this.entries.get(taskId);
+            if (running)
+                running.previewRequested = true;
+            out = { s: "sys", d: "✓ agent requested a managed preview" };
+        }
+        if (this.isHandoffSignal(raw, entry)) {
+            const running = this.entries.get(taskId);
+            if (running)
+                running.handoffRequested = true;
+            // Persist immediately so the request survives a crash before cleanup (#0235).
+            if (running) {
+                this.persistPendingHandoff({
+                    taskId,
+                    runId: running.runId,
+                    branch: running.branch,
+                    workdir: running.workdir ?? this.config.root,
+                    ...(session?.sessionId ? { sessionId: session.sessionId } : {}),
+                });
+            }
+            out = { s: "sys", d: "✓ agent requested server-side handoff" };
+        }
+        return out;
+    }
+    /**
+     * Fold any usage/cost found in a raw output line into the session. Returns
+     * true when a stored value actually changed (so callers only emit stats when
+     * there's something new to show). Also appends the raw event to
+     * `session_usage_events` — the lossless ground truth this rollup derives from.
+     *
+     * Three fold modes, matching `foldUsage`:
+     *  - authoritative (claude `result`): the turn's real total FOR THIS PROCESS
+     *    — added onto `usageBaseline` (prior processes' totals for this same
+     *    session), not a bare overwrite, so a task resumed after review doesn't
+     *    see its cumulative cost/tokens drop back down.
+     *  - deltas (opencode `step_finish`): SUM — each event is one round-trip, and
+     *    `Math.max` would keep only the largest step (0109 undercounted a
+     *    17-step reviewer run's cache-reads ~15x). Deltas accumulate directly on
+     *    `cur`, so they're baseline-safe across process boundaries already.
+     *  - otherwise (codex/claude running totals): Math.max against this
+     *    process's own total plus baseline — count up, never flicker down on a
+     *    transient mid-stream figure, and never dip below a prior process's
+     *    total either.
+     */
+    applyUsage(taskKey, session, raw) {
+        const found = extractUsage(raw);
+        this.recordUsageEvent(taskKey, session, raw, found);
+        // During a transcript replay the counters must not move — see `replayLog`.
+        if (this.replayingUsage)
+            return false;
+        let changed = false;
+        const set = (cur, v, baseline = 0) => found.authoritative
+            ? v + baseline
+            : found.deltas
+                ? (cur ?? 0) + v
+                : Math.max(cur ?? 0, v + baseline);
+        const baseline = session.usageBaseline;
+        if (found.inputTokens !== undefined) {
+            const next = set(session.inputTokens, found.inputTokens, baseline?.inputTokens);
+            if (next !== session.inputTokens) {
+                session.inputTokens = next;
+                changed = true;
+            }
+        }
+        if (found.outputTokens !== undefined) {
+            const next = set(session.outputTokens, found.outputTokens, baseline?.outputTokens);
+            if (next !== session.outputTokens) {
+                session.outputTokens = next;
+                changed = true;
+            }
+        }
+        if (found.totalTokens !== undefined) {
+            const next = set(session.tokens, found.totalTokens, baseline?.tokens);
+            if (next !== session.tokens) {
+                session.tokens = next;
+                changed = true;
+            }
+        }
+        if (found.costUsd !== undefined) {
+            const next = set(session.costUsd, found.costUsd, baseline?.costUsd);
+            if (next !== session.costUsd) {
+                session.costUsd = next;
+                changed = true;
+            }
+        }
+        if (found.cacheReadTokens !== undefined) {
+            const next = set(session.cacheReadTokens, found.cacheReadTokens, baseline?.cacheReadTokens);
+            if (next !== session.cacheReadTokens) {
+                session.cacheReadTokens = next;
+                changed = true;
+            }
+        }
+        if (found.cacheCreationTokens !== undefined) {
+            const next = set(session.cacheCreationTokens, found.cacheCreationTokens, baseline?.cacheCreationTokens);
+            if (next !== session.cacheCreationTokens) {
+                session.cacheCreationTokens = next;
+                changed = true;
+            }
+        }
+        if (found.turns !== undefined && found.turns > 0) {
+            session.turns = (session.turns ?? 0) + found.turns; // delta — accumulate
+            changed = true;
+        }
+        return changed;
+    }
+    /**
+     * Append one raw usage-bearing line to `session_usage_events` before it is
+     * folded. Skips lines that carried no usage figure at all (the vast majority
+     * — text, tool calls, step_start). Best-effort; keyed by the CLI's own
+     * session id when known, else the runner key, plus the resolved task id and a
+     * timestamp so rows always correlate to a `sessions` row.
+     */
+    recordUsageEvent(taskKey, session, raw, found) {
+        if (!this.db)
+            return;
+        if (found.inputTokens === undefined &&
+            found.outputTokens === undefined &&
+            found.totalTokens === undefined &&
+            found.cacheReadTokens === undefined &&
+            found.cacheCreationTokens === undefined &&
+            found.costUsd === undefined &&
+            found.turns === undefined) {
+            return;
+        }
+        let eventType;
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.type === "string")
+                eventType = parsed.type;
+        }
+        catch {
+            /* non-JSON usage line (plain-text summary) — leave eventType null */
+        }
+        this.db.recordUsageEvent({
+            sessionId: session.sessionId || taskKey,
+            taskId: resolveSessionTaskId(taskKey),
+            agent: session.agent ?? null,
+            model: session.model ?? null,
+            codingAgent: session.engine,
+            eventType: eventType ?? null,
+            inputTokens: found.inputTokens ?? null,
+            outputTokens: found.outputTokens ?? null,
+            totalTokens: found.totalTokens ?? null,
+            cacheReadTokens: found.cacheReadTokens ?? null,
+            cacheCreationTokens: found.cacheCreationTokens ?? null,
+            costUsd: found.costUsd ?? null,
+            turns: found.turns ?? null,
+            raw,
+        });
+    }
+    /** Emit the current live-stats snapshot for a task. */
+    emitStats(taskId) {
+        this.emit({ type: "agent.stats", id: taskId, stats: this.snapshotStats(taskId), at: now() });
+    }
+    /** Compute a fresh stats snapshot — always safe to call, even with no session. */
+    snapshotStats(taskId) {
+        const session = this.sessions.get(taskId);
+        const running = this.entries.has(taskId);
+        const lastOutputAt = session?.lastOutputAt ?? null;
+        const stalled = running && !!lastOutputAt && Date.now() - Date.parse(lastOutputAt) >= this.stallTimeoutMs;
+        return {
+            accumulatedMs: session?.accumulatedMs ?? 0,
+            turnStartedAt: running ? (session?.turnStartedAt ?? null) : null,
+            lastOutputAt,
+            tokens: session?.tokens ?? null,
+            costUsd: session?.costUsd ?? null,
+            stalled,
+        };
+    }
+    /**
+     * Periodic sweep (every `stallCheckIntervalMs`) over currently-running turns:
+     * raises the stall flag the moment silence crosses the threshold. Recovery
+     * (new output, or the turn exiting) is handled inline where it happens, so
+     * this only ever needs to turn the warning ON, never off.
+     * Also polls adopted entries (0214) for PID liveness: if the adopted PID
+     * died, clean up the entry so the task doesn't read as running forever.
+     */
+    checkStalls() {
+        for (const [taskId, entry] of this.entries) {
+            if (entry.adoptedPid) {
+                try {
+                    process.kill(entry.adoptedPid, 0);
+                }
+                catch {
+                    // PID died during adoption — clean up
+                    this.cleanup(taskId, false);
+                    continue;
+                }
+            }
+            const session = this.sessions.get(taskId);
+            if (!session || session.stalledEmitted)
+                continue;
+            if (this.snapshotStats(taskId).stalled) {
+                session.stalledEmitted = true;
+                this.emitStats(taskId);
+            }
+        }
+    }
+    tryExtractSessionId(line, session) {
+        if (session.sessionId)
+            return;
+        for (const re of SESSION_ID_PATTERNS) {
+            const m = line.match(re);
+            if (m?.[1]) {
+                session.sessionId = m[1];
+                return;
+            }
+        }
+    }
+    /**
+     * Signal a running agent to stop: graceful SIGTERM first, SIGKILL after a
+     * short grace period. Returns immediately; the registry clears on exit.
+     */
+    stop(taskId) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return { stopped: false, reason: "task is not running" };
+        for (const tailer of entry.tailers ?? []) {
+            tailer.drain();
+            tailer.flush();
+            clearInterval(tailer.timer);
+        }
+        entry.tailers = undefined;
+        if (entry.adoptedPid) {
+            // For adopted entries (0214): kill by PID directly since proc is null.
+            try {
+                process.kill(entry.adoptedPid, "SIGTERM");
+            }
+            catch {
+                /* already gone */
+            }
+            const adoptedPid = entry.adoptedPid;
+            entry.killTimer = setTimeout(() => {
+                try {
+                    process.kill(adoptedPid, "SIGKILL");
+                }
+                catch {
+                    /* already gone */
+                }
+            }, 3000);
+        }
+        else if (!entry.killTimer) {
+            try {
+                entry.proc?.kill("SIGTERM");
+            }
+            catch {
+                /* already gone */
+            }
+            entry.killTimer = setTimeout(() => {
+                try {
+                    entry.proc?.kill("SIGKILL");
+                }
+                catch {
+                    /* already gone */
+                }
+            }, 3000);
+        }
+        return { stopped: true };
+    }
+    /**
+     * Interrupt a running AI chat response (PM, guide, debugger, …). Stops the
+     * in-flight agent process via {@link stop} and appends a persistent marker to
+     * the chat's transcript so the user sees the response was user-stopped rather
+     * than completed normally. Idempotent — safe to call when nothing is running.
+     *
+     * The marker is emitted server-side (so it survives a client hydrate, not just
+     * the live SSE stream) as a `sys` entry on the session. The agent's own exit
+     * also triggers the generic `agent.exited` "stopped" notice client-side.
+     */
+    interrupt(taskId) {
+        const wasRunning = this.entries.has(taskId);
+        const result = this.stop(taskId);
+        if (wasRunning && this.sessions.has(taskId)) {
+            this.system(taskId, INTERRUPTED_MARKER);
+        }
+        return result;
+    }
+    /** Record a session to the database. Best-effort, never fails the server. */
+    recordSessionToDb(sessionId, session, taskKey, exitedCleanly) {
+        if (!this.db || !session)
+            return;
+        try {
+            // Determine session type from agent name for better aggregations (0331):
+            // exact built-in role names first, ordered substring probes second — so
+            // a legacy "RepoOS Guide" is a "guide", never an "engineer".
+            const sessionType = classifySessionType(session.agent, taskKey);
+            // Attribute the session to the REAL task ID. The runner key (`taskKey`) is
+            // the task id for engineer/review sessions, but chat-style sessions (PM)
+            // are keyed by a synthetic id like `pm-task-v2:123`; stripping the prefix
+            // restores the actual task so PM cost/tokens aggregate under the task
+            // (0230). Non-task chats (guide) record no task id at all.
+            const taskId = resolveSessionTaskId(taskKey);
+            // Reuse existing session ID to accumulate multi-turn sessions into one record
+            const finalSessionId = sessionId || `${taskKey}-${randomUUID()}`;
+            const endedAt = new Date().toISOString();
+            const elapsedMs = session.accumulatedMs;
+            const agent = session.agent ?? "unknown";
+            const model = session.model ?? "default";
+            const codingAgent = session.engine;
+            const inputTokens = session.inputTokens ?? undefined;
+            const outputTokens = session.outputTokens ?? undefined;
+            const totalTokens = session.tokens ?? undefined;
+            const cacheReadTokens = session.cacheReadTokens ?? undefined;
+            const cacheCreationTokens = session.cacheCreationTokens ?? undefined;
+            const turns = session.turns ?? undefined;
+            let costUsd = session.costUsd ?? undefined;
+            let costSource = "none";
+            const isKiro = session.engine === "kiro";
+            if (totalTokens && !costUsd) {
+                costUsd = estimateCostUsd(totalTokens);
+                costSource = "estimate";
+            }
+            else if (session.costUsd) {
+                // Kiro reports credits in its billing unit, not US dollars — flag the
+                // source so aggregation/UI never present it as USD (0230).
+                costSource = isKiro ? "kiro-credits" : "extractUsage";
+            }
+            const status = exitedCleanly ? "finished" : "errored";
+            // Use session creation time (first time this session started), not current time
+            const startedAt = session.createdAt ?? endedAt;
+            this.db.upsertSession({
+                sessionId: finalSessionId,
+                sessionType,
+                taskId: taskId || undefined,
+                agent,
+                model,
+                codingAgent,
+                startedAt,
+                endedAt,
+                elapsedMs,
+                inputTokens,
+                outputTokens,
+                totalTokens,
+                cacheReadTokens,
+                cacheCreationTokens,
+                turns,
+                costUsd,
+                costSource,
+                status,
+                lastActivityAt: session.lastOutputAt ?? endedAt,
+            });
+        }
+        catch {
+            // Database recording is best-effort and must never crash the server.
+        }
+    }
+    /** Drop the registry entry for a task (idempotent) and announce it. */
+    cleanup(taskId, exitedCleanly) {
+        const entry = this.entries.get(taskId);
+        if (!entry)
+            return;
+        // Capture before the entry is deleted below so the review-completion hook
+        // can still be fired and its DB recording skipped (0288).
+        const wasReview = entry.review === true;
+        // Drain and flush durable-log pollers before removing the registry entry.
+        // The final output may not carry a newline, so it lives in the tailer's
+        // local pending buffer until this point.
+        for (const tailer of entry.tailers ?? []) {
+            tailer.drain();
+            tailer.flush();
+            clearInterval(tailer.timer);
+        }
+        entry.tailers = undefined;
+        this.removeRegistryEntry(taskId);
+        this.logger?.agent(taskId, exitedCleanly ? "info" : "error", `Agent exited ${exitedCleanly ? "cleanly" : "with error"}`, { runId: entry.runId });
+        const session = this.sessions.get(taskId);
+        if (session && session.pending.trim()) {
+            // Flush a trailing line with no final newline through the same parse
+            // path: a complete JSON event becomes a structured entry, and a partial
+            // one degrades to a plain line — either way nothing is lost or dropped.
+            const line = session.pending.trimEnd();
+            this.appendLine(taskId, "out", line);
+            session.pending = "";
+        }
+        if (entry.killTimer)
+            clearTimeout(entry.killTimer);
+        // claude stream (0109): a tool_use whose result never arrived before the
+        // turn ended still gets its card, so a call is never silently invisible.
+        if ((session?.engine === "claude" || session?.engine === "qwen") && session.pendingTool) {
+            this.recordEntry(taskId, session, "out", this.pendingToolEntry(session.pendingTool));
+            session.pendingTool = undefined;
+        }
+        // Fold the finished turn's wall time into the running total (0080) — the
+        // time-spent counter accumulates across turns rather than resetting each
+        // time a follow-up message starts a fresh process.
+        if (session?.turnStartedAt) {
+            session.accumulatedMs += Date.now() - Date.parse(session.turnStartedAt);
+            session.turnStartedAt = undefined;
+        }
+        if (session)
+            session.stalledEmitted = false;
+        this.entries.delete(taskId);
+        this.drainQueue();
+        // Kiro CLI does not print a session ID during the run. Capture it now by
+        // querying the CLI's session list in the same cwd. Best-effort: if the
+        // probe fails, sessionId stays undefined and the next turn falls back to
+        // `-r` (most-recent resume). The lookup is synchronous-in-practice because
+        // cleanup() is called from proc.on("close") — we fire-and-update so the
+        // emit below is not delayed waiting for a CLI round-trip.
+        if (session?.engine === "kiro" && !session.sessionId && entry.workdir) {
+            void this.captureKiroSessionId(taskId, session, entry.workdir);
+        }
+        this.emit({ type: "agent.exited", id: taskId, at: now() });
+        // A confirmed exit always clears any stall warning — silence is only
+        // ambiguous while the process is still alive.
+        if (session)
+            this.emitStats(taskId);
+        // Record session to database (best-effort). Review sessions are recorded by
+        // ReviewManager's own completion handler instead, so they are skipped here
+        // to avoid double-booking (0288).
+        if (session && !wasReview) {
+            this.recordSessionToDb(session.sessionId, session, taskId, exitedCleanly);
+        }
+        // Resolve task from index if not in entry (important for resume turns).
+        const taskForHandoff = entry.task ?? (this.getTask ? this.getTask(taskId) : null);
+        // Any non-clean exit that isn't a deliberate human pause means the task is
+        // about to sit silently in its current status with nothing left running —
+        // flag it the moment the process ends rather than waiting for
+        // TaskWatchdog's staleness poll, which wouldn't even catch a fast
+        // crash-on-exit (an expired CLI auth session, say): the process isn't
+        // stalled, it's just done. Excludes `entry.handoffRequested`: that shape
+        // already has its own recovery path below ("retained for recovery" on
+        // next boot) and must not be double-flagged before that has a chance to
+        // run.
+        if (!exitedCleanly && !this.isPaused(taskId) && !entry.handoffRequested && taskForHandoff) {
+            this.escalateFailedExit(taskId, taskForHandoff, session);
+        }
+        if (entry.handoffRequested &&
+            exitedCleanly &&
+            taskForHandoff &&
+            entry.branch &&
+            entry.workdir) {
+            // Clean exit with handoff requested: clear the persisted request and fire finalization.
+            this.clearPendingHandoff(taskId);
+            const request = {
+                taskId,
+                runId: entry.runId,
+                branch: entry.branch,
+                workdir: entry.workdir,
+                ...(session?.sessionId ? { sessionId: session.sessionId } : {}),
+            };
+            this.authorizedHandoffs.set(request.runId, request);
+            this.handoffsInFlight.add(taskId);
+            void Promise.resolve(this.onHandoff?.(request))
+                .catch((err) => {
+                this.appendLine(taskId, "sys", `✗ server-side handoff failed: ${err.message}`);
+            })
+                .finally(() => this.handoffsInFlight.delete(taskId));
+        }
+        else if (entry.handoffRequested && exitedCleanly && !taskForHandoff) {
+            this.appendLine(taskId, "sys", "✗ handoff was not started because the task could not be resolved");
+            this.clearPendingHandoff(taskId);
+            this.persistHandoffFailure(taskId, undefined, "task could not be resolved");
+        }
+        else if (entry.handoffRequested && !exitedCleanly) {
+            // Interrupted turn: the persisted request survives for recovery on next boot (#0235).
+            this.appendLine(taskId, "sys", "⚠ handoff retained for recovery — the request will be finalized on the next server start");
+            this.persistHandoffFailure(taskId, entry.task, "agent turn was interrupted · handoff retained for recovery");
+        }
+        // A preview request is honored only after a clean turn (#0121): the runner
+        // mints a capability bound to that run's task/branch/worktree and hands the
+        // request to the server, which owns preview process and network lifecycle.
+        if (entry.previewRequested &&
+            exitedCleanly &&
+            taskForHandoff &&
+            entry.branch &&
+            entry.workdir) {
+            const request = {
+                taskId,
+                runId: entry.runId,
+                branch: entry.branch,
+                workdir: entry.workdir,
+                ...(session?.sessionId ? { sessionId: session.sessionId } : {}),
+            };
+            this.authorizedPreviews.set(request.runId, request);
+            void Promise.resolve(this.onPreviewRequest?.(request)).catch((err) => {
+                this.appendLine(taskId, "sys", `✗ managed preview failed: ${err.message}`);
+            });
+        }
+        else if (entry.previewRequested && !exitedCleanly) {
+            this.appendLine(taskId, "sys", "✗ managed preview was not started because the agent turn was interrupted");
+        }
+        // Defense-in-depth (0077): a turn that ended with the worktree copy at
+        // `review`/`needs_input` while the main copy is still `active` means the
+        // fail-safe checklist's main-copy sync silently failed (the #0068 shape).
+        // Patch the main copy to match so the live board cannot drift silently.
+        this.healBoardDivergence(taskId, entry, session);
+        // Self-heal may have appended a final system line, so persist only after it.
+        this.persist(taskId);
+        if (this.pendingCompletion.delete(taskId))
+            this.finishCompletion(taskId);
+        // A review turn completed. Fire the hook so the owning ReviewManager can
+        // finalize (write the report, log "review completed", auto-bounce) from the
+        // durable session — including for an entry re-attached after a reload whose
+        // completion is only observed here (0288).
+        if (wasReview) {
+            try {
+                this.onReviewDone?.(taskId, exitedCleanly, entry.reviewKind);
+            }
+            catch (err) {
+                this.logger?.agent(taskId, "error", `Review completion handler failed: ${err.message}`);
+            }
+        }
+    }
+    /**
+     * Post-run session-id capture for Kiro CLI (#0148). Kiro does not print its
+     * session id during the run; after the process exits we query the CLI's local
+     * session list for the cwd and take the most-recently-updated entry — that is
+     * the turn that just finished. Best-effort and fail-soft: any failure leaves
+     * sessionId undefined so the next turn falls back to `-r` (most-recent resume).
+     */
+    captureKiroSessionId(taskId, session, cwd) {
+        return new Promise((resolve) => {
+            let proc;
+            try {
+                proc = spawn("kiro-cli", ["chat", "--list-sessions", "--format", "json"], {
+                    cwd,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+            }
+            catch {
+                resolve();
+                return;
+            }
+            let out = "";
+            const timer = setTimeout(() => {
+                try {
+                    proc.kill("SIGKILL");
+                }
+                catch {
+                    /* already gone */
+                }
+                resolve();
+            }, 5000);
+            proc.stdout?.on("data", (c) => {
+                out += c.toString("utf8");
+            });
+            proc.on("error", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            proc.on("close", () => {
+                clearTimeout(timer);
+                try {
+                    const rows = JSON.parse(out);
+                    const sessionId = rows[0]?.sessions?.[0]?.sessionId;
+                    if (typeof sessionId === "string" && sessionId) {
+                        session.sessionId = sessionId;
+                        this.schedulePersist(taskId);
+                    }
+                }
+                catch {
+                    /* malformed JSON — leave sessionId undefined */
+                }
+                resolve();
+            });
+        });
+    }
+    /**
+     * Snapshot a session's cumulative usage into `usageBaseline` right before a
+     * new CLI process is spawned for it (`start()` / `send()`), so an
+     * authoritative or running-total figure from THAT process — which starts
+     * counting at zero — is added onto prior processes' totals in `applyUsage`
+     * instead of replacing them.
+     */
+    captureUsageBaseline(session) {
+        session.usageBaseline = {
+            inputTokens: session.inputTokens ?? 0,
+            outputTokens: session.outputTokens ?? 0,
+            tokens: session.tokens ?? 0,
+            costUsd: session.costUsd ?? 0,
+            cacheReadTokens: session.cacheReadTokens ?? 0,
+            cacheCreationTokens: session.cacheCreationTokens ?? 0,
+        };
+    }
+    emptySession() {
+        return {
+            lines: [],
+            pending: "",
+            bytes: 0,
+            engine: "plain",
+            accumulatedMs: 0,
+            createdAt: now(),
+            stalledEmitted: false,
+        };
+    }
+    sessionFile(taskId) {
+        // IDs can name both tasks and durable non-task conversations such as
+        // `pm-task-v2:0209::alice@example.com` (per-user PM chat, 0248). Keep the
+        // input strictly filename-safe, then escape the cross-platform-invalid
+        // separators before constructing the path.
+        if (!/^[A-Za-z0-9._:@-]+$/.test(taskId) || taskId === "." || taskId === "..")
+            return null;
+        return join(this.sessionsDir, `${taskId.replaceAll(":", "%3A").replaceAll("@", "%40")}.json`);
+    }
+    /** Read and validate one versioned file. Corruption/version drift fails soft. */
+    readPersisted(taskId) {
+        const file = this.sessionFile(taskId);
+        if (!file || !existsSync(file))
+            return null;
+        try {
+            const value = JSON.parse(readFileSync(file, "utf8"));
+            if (value.version !== SESSION_FILE_VERSION ||
+                !Array.isArray(value.lines) ||
+                !value.lines.every((line) => typeof line === "object" && line !== null) ||
+                !["opencode", "claude", "copilot", "qwen", "codex", "kiro", "plain"].includes(value.engine) ||
+                typeof value.updatedAt !== "string" ||
+                (value.sessionId !== undefined && typeof value.sessionId !== "string") ||
+                (value.workdir !== undefined && typeof value.workdir !== "string") ||
+                (value.completedAt !== undefined && typeof value.completedAt !== "string") ||
+                (value.agent !== undefined && typeof value.agent !== "string") ||
+                (value.model !== undefined && typeof value.model !== "string"))
+                return null;
+            return value;
+        }
+        catch {
+            return null;
+        }
+    }
+    loadSession(taskId) {
+        const saved = this.readPersisted(taskId);
+        if (!saved)
+            return null;
+        const session = {
+            lines: [...saved.lines],
+            pending: "",
+            bytes: saved.lines.reduce((sum, line) => sum + entryBytes(line), 0),
+            engine: saved.engine,
+            sessionId: saved.sessionId,
+            workdir: saved.workdir,
+            createdAt: saved.createdAt,
+            agent: saved.agent,
+            model: saved.model,
+            accumulatedMs: 0,
+            stalledEmitted: false,
+        };
+        while (session.bytes > OUTPUT_CAP_BYTES) {
+            const dropped = session.lines.shift();
+            if (!dropped)
+                break;
+            session.bytes -= entryBytes(dropped);
+        }
+        return session;
+    }
+    /** Boot only hot lifecycle states; completed transcripts remain cold. */
+    loadHotSessions() {
+        try {
+            const hot = new Set(buildIndex(this.config)
+                .tasks.filter((task) => task.status === "active" || task.status === "review")
+                .map((task) => task.id));
+            for (const taskId of hot) {
+                const session = this.loadSession(taskId);
+                if (session)
+                    this.sessions.set(taskId, session);
+            }
+        }
+        catch {
+            // A bad task or unreadable cache must never prevent `repoos serve` boot.
+        }
+    }
+    schedulePersist(taskId) {
+        const existing = this.writeTimers.get(taskId);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => this.persist(taskId), this.writeDelayMs);
+        timer.unref?.();
+        this.writeTimers.set(taskId, timer);
+    }
+    /** Atomic temp-file + rename write; persistence remains best-effort. */
+    persist(taskId, completedAt) {
+        const timer = this.writeTimers.get(taskId);
+        if (timer)
+            clearTimeout(timer);
+        this.writeTimers.delete(taskId);
+        const session = this.sessions.get(taskId);
+        const file = this.sessionFile(taskId);
+        if (!session || !file)
+            return;
+        try {
+            mkdirSync(dirname(file), { recursive: true });
+            const payload = {
+                version: SESSION_FILE_VERSION,
+                lines: session.lines,
+                sessionId: session.sessionId,
+                engine: session.engine,
+                workdir: session.workdir,
+                createdAt: session.createdAt,
+                agent: session.agent,
+                model: session.model,
+                completedAt,
+                updatedAt: this.clock().toISOString(),
+            };
+            const temp = `${file}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+            try {
+                writeFileSync(temp, JSON.stringify(payload, null, 2), "utf8");
+                renameSync(temp, file);
+            }
+            finally {
+                if (existsSync(temp))
+                    unlinkSync(temp);
+            }
+        }
+        catch {
+            // Session history is useful but must never take down the server/agent.
+        }
+    }
+    finishCompletion(taskId) {
+        const hot = this.sessions.get(taskId);
+        const saved = hot ? null : this.readPersisted(taskId);
+        const session = hot ?? (saved?.completedAt ? null : this.loadSession(taskId));
+        if (session) {
+            this.sessions.set(taskId, session);
+            this.persist(taskId, this.clock().toISOString());
+        }
+        this.sessions.delete(taskId);
+        this.pendingCompletion.delete(taskId);
+        this.pruneSessions();
+    }
+    /** Remove completed files older than the age bound or beyond the count cap. */
+    pruneSessions() {
+        let completed = [];
+        try {
+            completed = readdirSync(this.sessionsDir)
+                .filter((name) => name.endsWith(".json"))
+                .flatMap((name) => {
+                const taskId = name.slice(0, -5);
+                const saved = this.readPersisted(taskId);
+                if (!saved?.completedAt)
+                    return [];
+                const at = Date.parse(saved.completedAt);
+                return Number.isFinite(at) ? [{ file: join(this.sessionsDir, name), at }] : [];
+            })
+                .sort((a, b) => b.at - a.at);
+        }
+        catch {
+            return;
+        }
+        const cutoff = this.clock().getTime() - this.retentionDays * 24 * 60 * 60 * 1000;
+        for (let i = 0; i < completed.length; i++) {
+            if (completed[i].at >= cutoff && i < this.retentionCount)
+                continue;
+            try {
+                // Re-check it is still a regular file before deletion.
+                if (statSync(completed[i].file).isFile())
+                    unlinkSync(completed[i].file);
+            }
+            catch {
+                /* pruning is best-effort */
+            }
+        }
+    }
+    /**
+     * True when two absolute paths denote the same directory (realpath-normalized
+     * when possible, so macOS /var vs /private/var aliases compare equal).
+     */
+    samePath(a, b) {
+        try {
+            return realpathSync(a) === realpathSync(b);
+        }
+        catch {
+            return resolve(a) === resolve(b);
+        }
+    }
+    /**
+     * Persist a handoff failure reason to the task file's Activity log.
+     * Called when a handoff signal is expected but not detected, the process
+     * exits uncleanly before handoff can be finalized, or (from handoff.ts)
+     * server-side finalization itself fails. This persists the reason so it
+     * survives server reloads and lets the task watchdog classify the failure
+     * correctly instead of falling back to its generic guess (unlike
+     * in-memory transcript entries, which the watchdog cannot see).
+     */
+    persistHandoffFailure(taskId, task, reason) {
+        if (!task)
+            return;
+        try {
+            const current = parseTask({
+                content: readFileSync(task.absPath, "utf8"),
+                absPath: task.absPath,
+                root: this.config.root,
+                defaultStatus: this.config.defaultStatus,
+                defaultAssignee: this.config.defaultAssignee,
+            });
+            recordChange(current, `handoff failed · ${reason}`);
+            writeFileSync(task.absPath, serializeTask(current));
+        }
+        catch (err) {
+            // Fail-soft: if we can't persist, just log — don't crash the runner
+            console.error(`[repoos] failed to persist handoff failure for #${taskId}: ${err.message}`);
+        }
+    }
+    /**
+     * Best-effort one-line summary of why a turn failed. Prefers the last
+     * non-empty stderr line (where CLI-level failures like an expired OAuth
+     * session land), falling back to the last `sys`/error line RepoOS itself
+     * parsed out of the CLI's own JSON stream, then a generic fallback.
+     */
+    lastFailureLine(session) {
+        if (session) {
+            for (let i = session.lines.length - 1; i >= 0; i--) {
+                const line = session.lines[i];
+                if ("s" in line && line.s === "err" && line.d.trim())
+                    return line.d.trim();
+            }
+            for (let i = session.lines.length - 1; i >= 0; i--) {
+                const line = session.lines[i];
+                const text = "type" in line && line.type === "sys"
+                    ? line.d
+                    : "s" in line && line.s === "sys"
+                        ? line.d
+                        : undefined;
+                if (text?.trim())
+                    return text.trim();
+            }
+        }
+        return "the agent process exited with an error — open the task to see the full output";
+    }
+    /**
+     * Flag a task for human attention the instant its agent turn ends non-
+     * cleanly (and isn't a deliberate pause or an in-flight handoff recovery —
+     * see the call site in cleanup()). Mirrors TaskWatchdog's own
+     * `needsInput` escalation, just fired immediately instead of waiting for
+     * the next staleness poll. Never overwrites an existing needsInput note.
+     *
+     * Also bumps `dev_error_count` — unlike the needsInput note, this always
+     * increments, even on a repeat error before a human clears the flag,
+     * because it counts real dev attempts, not distinct escalations (#0271
+     * follow-up: confirmed live on #0291 — an engineer session that errors out
+     * before ever reaching a review pass left `review_passes` at 0, so the
+     * board's `D# · R#` badge showed nothing for a task that genuinely had one
+     * failed dev round. TaskDrawer.vue's `taskRounds` folds this count into
+     * `dev` so D can exceed R when a round errored without being reviewed.)
+     */
+    escalateFailedExit(taskId, task, session) {
+        try {
+            const current = parseTask({
+                content: readFileSync(task.absPath, "utf8"),
+                absPath: task.absPath,
+                root: this.config.root,
+                defaultStatus: this.config.defaultStatus,
+                defaultAssignee: this.config.defaultAssignee,
+            });
+            const errCount = current.extra?.dev_error_count;
+            current.extra = {
+                ...current.extra,
+                dev_error_count: (typeof errCount === "number" && Number.isFinite(errCount) ? errCount : 0) + 1,
+            };
+            if (current.needsInput) {
+                writeFileSync(task.absPath, serializeTask(current));
+                return;
+            }
+            current.needsInput = true;
+            current.needsInputReason = "dev-error";
+            const engine = session?.engine && session.engine !== "plain" ? ` (${session.engine})` : "";
+            recordChange(current, `agent exited with an error${engine} · ${this.lastFailureLine(session)}`);
+            writeFileSync(task.absPath, serializeTask(current));
+        }
+        catch (err) {
+            console.error(`[repoos] failed to escalate failed exit for #${taskId}: ${err.message}`);
+        }
+    }
+    /**
+     * Self-heal the #0068 divergence. Narrowly scoped: ONLY the shape where the
+     * main checkout's copy of the task is still `active` but the agent's
+     * worktree copy shows `review` or `needs_input` backed by a real commit.
+     * Any other state (task moved by a human, uncommitted worktree edit, no
+     * separate worktree) is left untouched — this is not a general bidirectional
+     * sync. The correction is surfaced (server log + a task.corrected event +
+     * a transcript sys line) because it means the checklist itself failed.
+     */
+    healBoardDivergence(taskId, entry, session) {
+        if (entry.skipBoardDivergence)
+            return;
+        const task = entry.task ?? (this.getTask ? this.getTask(taskId) : null);
+        if (!task || !entry.workdir)
+            return;
+        const worktreeCopy = join(entry.workdir, task.path);
+        if (this.samePath(task.absPath, worktreeCopy))
+            return; // same file — no divergence possible
+        if (!existsSync(task.absPath) || !existsSync(worktreeCopy))
+            return;
+        const parse = (absPath) => {
+            try {
+                return parseTask({
+                    content: readFileSync(absPath, "utf8"),
+                    absPath,
+                    root: this.config.root,
+                    defaultStatus: this.config.defaultStatus,
+                    defaultAssignee: this.config.defaultAssignee,
+                });
+            }
+            catch {
+                return null;
+            }
+        };
+        const main = parse(task.absPath);
+        const wt = parse(worktreeCopy);
+        if (!main || !wt)
+            return;
+        // Only the active-but-worktree-shows-review/needs_input divergence.
+        if (main.status !== "active")
+            return;
+        const wantsReview = wt.status === "review";
+        const wantsInput = wt.needsInput;
+        if (!wantsReview && !wantsInput)
+            return;
+        // The worktree state must be backed by a commit, not a stray mid-edit.
+        if (!fileCommittedClean(entry.workdir, task.path))
+            return;
+        const patch = {};
+        if (wantsReview)
+            patch.status = "review";
+        if (wantsInput) {
+            patch.needsInput = true;
+            patch.needsInputReason = wt.needsInputReason;
+        }
+        try {
+            patchTaskFile(this.config, task.absPath, patch);
+        }
+        catch (err) {
+            console.error(`[repoos] self-heal failed for #${taskId}: ${err.message}`);
+            return;
+        }
+        const note = `agent turn ended with the main copy still ${main.status} while the worktree copy was ` +
+            `committed to ${wantsReview ? "review" : "needs_input"} — main copy patched to match`;
+        if (session)
+            this.appendLine(taskId, "sys", `⚠ board self-healed: ${note}`);
+        this.emit({ type: "task.corrected", id: taskId, path: task.path, note, at: now() });
+        console.error(`[repoos] self-healed task #${taskId} — ${note}`);
+    }
+}