talon-agent 5.26.6 → 5.27.0

package/src/core/agents/runner.ts

@@ -24,8 +24,19 @@
  * `spawnAgent` returns as soon as the run is under way: the caller (a chat
  * turn or another agent) keeps working and hears back through the wake turn
  * or its mailbox.
+ *
+ *   - **Restarts are not deaths.** Every agent is mirrored to the `agents`
+ *     table (see the registry's `persist` hook). A daemon shutdown parks the
+ *     live ones (`interruptAgentsForRestart`) before it tears the backends
+ *     down, so the abort that follows is not recorded as a kill and the
+ *     parent is not told the agent died. On the next boot
+ *     `resumeAgentsAfterRestart` brings each one back under its original id:
+ *     on a backend that can resume (Claude SDK session, Codex thread) it
+ *     continues its own conversation with a short "you were interrupted"
+ *     note; elsewhere it is re-briefed with the tail of its previous run log.
  */
 
+import { readFile } from "node:fs/promises";
 import { dirs } from "../../util/paths.js";
 import { log, logError, logWarn } from "../../util/log.js";
 import {
@@ -61,9 +72,14 @@ import {
 import {
   agentLogHeader,
   agentLogPath,
+  agentResumeLogHeader,
   buildAgentPrompt,
   buildAgentSystemPrompt,
+  buildRebriefPrompt,
+  buildResumePrompt,
 } from "./prompt.js";
+import * as agentsRepo from "../../storage/agents/repo.js";
+import type { PersistedAgent } from "../../storage/agents/repo.js";
 import { agentRegistry } from "./registry.js";
 import type {
   AgentCaps,
@@ -259,6 +275,10 @@ export async function spawnAgent(
       ...(spec.reasoningEffort
         ? { reasoningEffort: spec.reasoningEffort }
         : {}),
+      ...(spec.model ? { requestedModel: spec.model } : {}),
+      timeoutMs: spec.timeoutMs ?? capsHolder.caps.defaultTimeoutMs,
+      cwd: dirs.workspace,
+      ...(spec.preflight ? { preflight: true } : {}),
     },
     capsHolder.caps,
   );
@@ -295,6 +315,16 @@ export async function spawnAgent(
   };
 }
 
+/**
+ * How a restarted run picks up. `sessionId` set = continue that backend
+ * conversation; unset = a fresh conversation re-briefed with `prompt`.
+ */
+interface ResumePlan {
+  readonly prompt: string;
+  readonly sessionId?: string;
+  readonly interruptedAt: number;
+}
+
 /** Build the one-shot params for a run, wired to its log and text capture. */
 async function buildRunParams(
   record: AgentRecord,
@@ -302,15 +332,26 @@ async function buildRunParams(
   model: string,
   abortController: AbortController,
   capture: { last: string },
+  resume?: ResumePlan,
 ): Promise<OneShotAgentParams> {
   const appendLog = await openRunLog(
     agentLogPath(record.id),
-    agentLogHeader(record, model),
+    resume
+      ? agentResumeLogHeader(
+          record,
+          model,
+          resume.interruptedAt,
+          resume.sessionId,
+        )
+      : agentLogHeader(record, model),
   );
+  const id = record.id;
   return {
-    prompt: buildAgentPrompt(record.brief, {
-      preflight: spec.preflight === true,
-    }),
+    prompt: resume
+      ? resume.prompt
+      : buildAgentPrompt(record.brief, {
+          preflight: spec.preflight === true,
+        }),
     systemPrompt: buildAgentSystemPrompt({
       agentId: record.id,
       label: record.label,
@@ -327,6 +368,10 @@ async function buildRunParams(
       const trimmed = text.trim();
       if (trimmed) capture.last = trimmed;
     },
+    // Persisted the moment the backend reports it, so a restart at any
+    // point after the first message can resume the conversation.
+    onSessionId: (sessionId) => agentRegistry.setSessionId(id, sessionId),
+    ...(resume?.sessionId ? { resumeSessionId: resume.sessionId } : {}),
     ...(spec.reasoningEffort ? { reasoningEffort: spec.reasoningEffort } : {}),
   };
 }
@@ -389,6 +434,7 @@ async function runAgent(
   spec: AgentSpawnSpec,
   resolved: { model: string; background: BackgroundRunner },
   acquired: Awaited<ReturnType<typeof acquireBackendInstance>>,
+  resume?: ResumePlan,
 ): Promise<void> {
   const { model, background } = resolved;
   const { release } = acquired;
@@ -419,8 +465,11 @@ async function runAgent(
       model,
       abortController,
       capture,
+      resume,
     );
-    if (abortController.signal.aborted) {
+    if (agentRegistry.isInterrupted(id)) {
+      settled = null;
+    } else if (abortController.signal.aborted) {
       // A kill that lands during startup — while the backend is being
       // acquired or the log opened — must not be lost. Handing an
       // already-aborted signal to a backend relies on it checking, and not
@@ -441,18 +490,38 @@ async function runAgent(
         evictLabel: agentContextLabel(id),
       });
       recordBackendRunUsage(record.backendId, usage ?? undefined);
-      recordBackendRunSuccess(record.backendId);
-      settled = settleSuccess(id, task, capture.last, usage ?? undefined);
+      // A backend may swallow the shutdown abort and return normally — the
+      // run still did not finish, so it must not settle as done/failed, and
+      // it says nothing about the backend's health either way.
+      if (agentRegistry.isInterrupted(id)) {
+        settled = null;
+      } else {
+        recordBackendRunSuccess(record.backendId);
+        settled = settleSuccess(id, task, capture.last, usage ?? undefined);
+      }
     }
   } catch (err) {
-    recordBackendRunFailure(record.backendId, err);
-    settled = settleFailure(id, task, err);
+    if (agentRegistry.isInterrupted(id)) {
+      settled = null;
+    } else {
+      recordBackendRunFailure(record.backendId, err);
+      settled = settleFailure(id, task, err);
+    }
   } finally {
     await release().catch((err: unknown) =>
       logError("agents", `failed to release backend for ${id}`, err),
     );
   }
 
+  if (agentRegistry.isInterrupted(id)) {
+    // Parked by a daemon shutdown: the persisted row stays `running` for
+    // the next boot to resume. No settlement, no delivery, no reaping — the
+    // parent is not told its agent died, because it didn't.
+    task.fail(new Error("interrupted by daemon shutdown — will resume"));
+    agentRegistry.releaseInterrupted(id);
+    log("agents", `${id} "${record.label}" interrupted by shutdown — parked`);
+    return;
+  }
   if (!settled) return;
   log(
     "agents",
@@ -491,12 +560,264 @@ export function killAgent(agentId: string): boolean {
   return agentRegistry.requestKill(agentId);
 }
 
+/**
+ * Park every live agent for the next boot. Called FIRST in a graceful
+ * shutdown — before the frontends and the backend pool go down, since
+ * tearing a backend down aborts the runs on it and an unparked agent would
+ * record that abort as its death. Idempotent.
+ */
+export function interruptAgentsForRestart(): number {
+  const parked = agentRegistry.interruptAll();
+  if (parked > 0) {
+    log("agents", `Shutdown: parked ${parked} running agent(s) for resume`);
+  }
+  return parked;
+}
+
 /**
  * Abort every live agent — the shutdown lever, alongside heartbeat's and
- * cron's. Returns how many kills were requested.
+ * cron's. Agents are parked first (a no-op if the shutdown already did), so
+ * this abort ends the process's hold on them without ending the agents:
+ * the next boot resumes them. Returns how many aborts were requested.
  */
 export function shutdownAgents(): number {
+  interruptAgentsForRestart();
   const killed = agentRegistry.killAll();
   if (killed > 0) log("agents", `Shutdown: aborted ${killed} running agent(s)`);
   return killed;
 }
+
+// ── Resume after restart ─────────────────────────────────────────────────────
+
+/** A restart may resume one agent at most this many times. */
+export const MAX_AGENT_RESUMES = 3;
+/** An agent interrupted longer ago than this is not resumed. */
+const AGENT_RESUME_STALE_MS = 24 * 60 * 60 * 1000;
+/** A resumed run always gets at least this much wall-clock. */
+const AGENT_RESUME_MIN_TIMEOUT_MS = 10 * 60 * 1000;
+/** Settled rows are kept this long for inspection, then pruned at boot. */
+const SETTLED_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/** How much of the previous run log a re-briefed agent is shown. */
+const REBRIEF_LOG_TAIL_CHARS = 12_000;
+
+/** The last `max` characters of an agent's previous run log, if any. */
+async function previousLogTail(agentId: string, max: number): Promise<string> {
+  try {
+    const text = await readFile(agentLogPath(agentId), "utf-8");
+    return text.length > max ? `…${text.slice(text.length - max)}` : text;
+  } catch {
+    return "";
+  }
+}
+
+/** Settle a restored agent without running it, and tell its parent. */
+async function settleRestored(
+  record: AgentRecord,
+  patch: Parameters<typeof agentRegistry.settle>[1],
+): Promise<void> {
+  const settled = agentRegistry.settle(record.id, patch);
+  if (!settled) return;
+  log(
+    "agents",
+    `${record.id} "${record.label}" → ${settled.state} (after restart)`,
+  );
+  reapChildren(settled);
+  await deliverSettlement(settled).catch((err: unknown) =>
+    logError("agents", `delivery failed for ${record.id}`, err),
+  );
+}
+
+/** Mark a row that cannot even be restored (its parent agent is gone). */
+function abandonRow(saved: PersistedAgent, error: string): void {
+  try {
+    agentsRepo.upsert({
+      ...saved,
+      state: "failed",
+      error,
+      endedAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+  } catch (err) {
+    logError("agents", `could not mark ${saved.id} abandoned`, err);
+  }
+}
+
+/**
+ * Resolve the model a resumed run uses: the one it ran on, else the one it
+ * asked for, else the backend default — a model withdrawn across the
+ * restart must not strand the agent.
+ */
+async function resolveResumeRun(
+  backend: Backend,
+  backendId: string,
+  candidates: ReadonlyArray<string | undefined>,
+): Promise<Awaited<ReturnType<typeof resolveRun>>> {
+  let last: Awaited<ReturnType<typeof resolveRun>> = {
+    ok: false,
+    error: "no model",
+  };
+  const tried = new Set<string | undefined>();
+  for (const candidate of [...candidates, undefined]) {
+    if (tried.has(candidate)) continue;
+    tried.add(candidate);
+    last = await resolveRun(backend, backendId, candidate);
+    if (last.ok) return last;
+  }
+  return last;
+}
+
+/** Bring one interrupted agent back. Never throws. */
+async function resumeOne(saved: PersistedAgent, now: number): Promise<void> {
+  // A crash leaves no interruption stamp: charge the run up to its last
+  // persisted write, which is as close as anyone can know.
+  const interruptedAt = saved.interruptedAt ?? saved.updatedAt;
+  const elapsedMs =
+    saved.interruptedAt === undefined && saved.startedAt !== undefined
+      ? saved.elapsedMs + Math.max(0, saved.updatedAt - saved.startedAt)
+      : saved.elapsedMs;
+
+  // Already back (a second resume pass in the same process) — leave it be.
+  if (agentRegistry.isLive(saved.id)) return;
+  const record = agentRegistry.restore({ ...saved, elapsedMs, interruptedAt });
+  if (!record) {
+    abandonRow(
+      saved,
+      "interrupted by a daemon restart; its parent agent did not survive it",
+    );
+    logWarn("agents", `${saved.id}: parent gone after restart — abandoned`);
+    return;
+  }
+
+  if (saved.reported) {
+    // It finished its job (report_result landed) and was only waiting to
+    // wind down — deliver what it said instead of running it again.
+    await settleRestored(record, { state: "done" });
+    return;
+  }
+  if (saved.resumeCount >= MAX_AGENT_RESUMES) {
+    await settleRestored(record, {
+      state: "failed",
+      error:
+        `interrupted by ${saved.resumeCount + 1} daemon restarts; not ` +
+        `resumed again. Its run log is ${agentLogPath(saved.id)}.`,
+    });
+    return;
+  }
+  if (now - interruptedAt > AGENT_RESUME_STALE_MS) {
+    await settleRestored(record, {
+      state: "failed",
+      error:
+        `interrupted by a daemon restart at ${new Date(interruptedAt).toISOString()} ` +
+        `and the daemon was down too long to resume it. Its run log is ` +
+        `${agentLogPath(saved.id)}.`,
+    });
+    return;
+  }
+
+  const backendId = saved.backendId;
+  let acquired: Awaited<ReturnType<typeof acquireBackendInstance>>;
+  try {
+    acquired = await acquireBackendInstance(backendId);
+  } catch (err) {
+    await settleRestored(record, {
+      state: "failed",
+      error:
+        `interrupted by a daemon restart, and its backend "${backendId}" ` +
+        `is unavailable after it: ${errText(err)}`,
+    });
+    return;
+  }
+  const resolved = await resolveResumeRun(acquired.backend, backendId, [
+    saved.model,
+    saved.requestedModel,
+  ]);
+  if (!resolved.ok) {
+    await acquired.release().catch(() => {});
+    await settleRestored(record, {
+      state: "failed",
+      error: `interrupted by a daemon restart and could not resume: ${resolved.error}`,
+    });
+    return;
+  }
+
+  const canResume =
+    resolved.background.supportsResume === true &&
+    saved.sessionId !== undefined;
+  const minutes = Math.round(elapsedMs / 60_000);
+  const plan: ResumePlan = canResume
+    ? {
+        prompt: buildResumePrompt({ interruptedAt, elapsedMinutes: minutes }),
+        sessionId: saved.sessionId!,
+        interruptedAt,
+      }
+    : {
+        prompt: buildRebriefPrompt({
+          brief: saved.brief,
+          preflight: saved.preflight === true,
+          interruptedAt,
+          elapsedMinutes: minutes,
+          logPath: agentLogPath(saved.id),
+          logTail: await previousLogTail(saved.id, REBRIEF_LOG_TAIL_CHARS),
+        }),
+        interruptedAt,
+      };
+
+  const budget =
+    (saved.timeoutMs ?? capsHolder.caps.defaultTimeoutMs) - elapsedMs;
+  const timeoutMs = Math.max(AGENT_RESUME_MIN_TIMEOUT_MS, budget);
+  const spec: AgentSpawnSpec = {
+    brief: saved.brief,
+    label: saved.label,
+    parent: record.parent,
+    backendId,
+    ...(saved.requestedModel ? { model: saved.requestedModel } : {}),
+    ...(record.reasoningEffort
+      ? { reasoningEffort: record.reasoningEffort }
+      : {}),
+    timeoutMs,
+    ...(saved.preflight ? { preflight: true } : {}),
+  };
+  agentRegistry.markResumed(record.id);
+  log(
+    "agents",
+    `${record.id} "${record.label}" resuming after restart ` +
+      `(${canResume ? `session ${saved.sessionId}` : "re-briefed"}, ` +
+      `${backendId}/${resolved.model}, ${Math.round(timeoutMs / 1000)}s left, ` +
+      `resume #${saved.resumeCount + 1})`,
+  );
+  void runAgent(record, spec, resolved, acquired, plan);
+}
+
+/**
+ * Boot-time: respawn every agent the previous process left running. Call
+ * once, after the dispatcher, backend pool and frontends are up (a resumed
+ * agent reaches its tools and its parent through them). Parents come back
+ * before their children, so a child re-attaches to its live parent.
+ * Returns how many rows were considered.
+ */
+export async function resumeAgentsAfterRestart(): Promise<number> {
+  const now = Date.now();
+  try {
+    const pruned = agentsRepo.pruneSettled(now - SETTLED_RETENTION_MS);
+    if (pruned > 0) log("agents", `Pruned ${pruned} settled agent row(s)`);
+  } catch (err) {
+    logError("agents", "prune of settled agent rows failed", err);
+  }
+  let rows: PersistedAgent[];
+  try {
+    rows = agentsRepo.listInterrupted();
+  } catch (err) {
+    logError("agents", "could not read interrupted agents", err);
+    return 0;
+  }
+  if (rows.length === 0) return 0;
+  log("agents", `Resuming ${rows.length} agent(s) interrupted by the restart`);
+  for (const saved of rows) {
+    try {
+      await resumeOne(saved, now);
+    } catch (err) {
+      logError("agents", `resume of ${saved.id} failed`, err);
+    }
+  }
+  return rows.length;
+}

package/src/core/types.ts

@@ -172,6 +172,21 @@ export type OneShotAgentParams = {
    * and logs a throwing callback so a consumer bug can never fail the run.
    */
   onAssistantText?: (text: string) => void;
+  /**
+   * Resume this backend conversation instead of starting a fresh one — the
+   * handle an earlier run reported through `onSessionId`. Honoured only by
+   * backends whose `BackgroundRunner.supportsResume` is true (Claude SDK:
+   * session id; Codex: thread id); the others ignore it and start fresh,
+   * which is why the sub-agent runner checks that flag before relying on it.
+   */
+  resumeSessionId?: string;
+  /**
+   * Called once the backend knows the run's conversation handle (Claude SDK
+   * session id, Codex thread id) — a sub-agent persists it so a daemon
+   * restart can resume the conversation. Best-effort and synchronous, like
+   * `onAssistantText`: a throwing callback must never fail the run.
+   */
+  onSessionId?: (sessionId: string) => void;
 };
 
 /** How much cache telemetry a backend can surface in /status. */

package/src/storage/agents/repo.ts

@@ -0,0 +1,200 @@
+/**
+ * Agents repository — executes the statements in sql/agents.sql against
+ * the `agents` table; no SQL text lives here. The domain side (what gets
+ * written when, and the boot-time resume) is core/agents/registry.ts and
+ * core/agents/runner.ts.
+ */
+
+import { getDatabase } from "../db.js";
+import { agentsSql } from "../sql/statements.generated.js";
+
+/** One persisted message waiting in an agent's mailbox. */
+type PersistedAgentMessage = {
+  from: string;
+  text: string;
+  at: number;
+};
+
+/** A sub-agent as stored — everything a restart needs to bring it back. */
+export type PersistedAgent = {
+  id: string;
+  label: string;
+  brief: string;
+  parentKind: "chat" | "agent";
+  /** Chat key (chat parent) or agent id (agent parent). */
+  parentId: string;
+  /** Frontend numeric chat id — chat parents only. */
+  parentNumericChatId?: number;
+  backendId: string;
+  model?: string;
+  requestedModel?: string;
+  reasoningEffort?: string;
+  timeoutMs?: number;
+  depth: number;
+  cwd?: string;
+  state: string;
+  createdAt: number;
+  startedAt?: number;
+  endedAt?: number;
+  updatedAt: number;
+  sessionId?: string;
+  inbox: PersistedAgentMessage[];
+  reported: boolean;
+  resultSummary?: string;
+  resultDetails?: string;
+  error?: string;
+  elapsedMs: number;
+  resumeCount: number;
+  interruptedAt?: number;
+  /** The spawn asked for the pre-flight lane instruction. */
+  preflight?: boolean;
+};
+
+type Row = {
+  id: string;
+  label: string;
+  brief: string;
+  parent_kind: string;
+  parent_id: string;
+  parent_numeric: number | null;
+  backend_id: string;
+  model: string | null;
+  requested_model: string | null;
+  effort: string | null;
+  timeout_ms: number | null;
+  depth: number;
+  cwd: string | null;
+  state: string;
+  created_at: number;
+  started_at: number | null;
+  ended_at: number | null;
+  updated_at: number;
+  session_id: string | null;
+  inbox_json: string;
+  reported: number;
+  result_summary: string | null;
+  result_details: string | null;
+  error: string | null;
+  elapsed_ms: number;
+  resume_count: number;
+  interrupted_at: number | null;
+  preflight: number;
+};
+
+function parseInbox(raw: string): PersistedAgentMessage[] {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (m): m is PersistedAgentMessage =>
+        typeof m === "object" &&
+        m !== null &&
+        typeof (m as { from?: unknown }).from === "string" &&
+        typeof (m as { text?: unknown }).text === "string" &&
+        typeof (m as { at?: unknown }).at === "number",
+    );
+  } catch {
+    return [];
+  }
+}
+
+function rowToAgent(row: Row): PersistedAgent {
+  const agent: PersistedAgent = {
+    id: row.id,
+    label: row.label,
+    brief: row.brief,
+    parentKind: row.parent_kind === "agent" ? "agent" : "chat",
+    parentId: row.parent_id,
+    backendId: row.backend_id,
+    depth: row.depth,
+    state: row.state,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    inbox: parseInbox(row.inbox_json),
+    reported: row.reported === 1,
+    elapsedMs: row.elapsed_ms,
+    resumeCount: row.resume_count,
+  };
+  if (row.parent_numeric !== null)
+    agent.parentNumericChatId = row.parent_numeric;
+  if (row.model !== null) agent.model = row.model;
+  if (row.requested_model !== null) agent.requestedModel = row.requested_model;
+  if (row.effort !== null) agent.reasoningEffort = row.effort;
+  if (row.timeout_ms !== null) agent.timeoutMs = row.timeout_ms;
+  if (row.cwd !== null) agent.cwd = row.cwd;
+  if (row.started_at !== null) agent.startedAt = row.started_at;
+  if (row.ended_at !== null) agent.endedAt = row.ended_at;
+  if (row.session_id !== null) agent.sessionId = row.session_id;
+  if (row.result_summary !== null) agent.resultSummary = row.result_summary;
+  if (row.result_details !== null) agent.resultDetails = row.result_details;
+  if (row.error !== null) agent.error = row.error;
+  if (row.interrupted_at !== null) agent.interruptedAt = row.interrupted_at;
+  if (row.preflight === 1) agent.preflight = true;
+  return agent;
+}
+
+export function upsert(a: PersistedAgent): void {
+  getDatabase()
+    .prepare(agentsSql.upsert)
+    .run(
+      a.id,
+      a.label,
+      a.brief,
+      a.parentKind,
+      a.parentId,
+      a.parentNumericChatId ?? null,
+      a.backendId,
+      a.model ?? null,
+      a.requestedModel ?? null,
+      a.reasoningEffort ?? null,
+      a.timeoutMs ?? null,
+      a.depth,
+      a.cwd ?? null,
+      a.state,
+      a.createdAt,
+      a.startedAt ?? null,
+      a.endedAt ?? null,
+      a.updatedAt,
+      a.sessionId ?? null,
+      JSON.stringify(a.inbox),
+      a.reported ? 1 : 0,
+      a.resultSummary ?? null,
+      a.resultDetails ?? null,
+      a.error ?? null,
+      a.elapsedMs,
+      a.resumeCount,
+      a.interruptedAt ?? null,
+      a.preflight ? 1 : 0,
+    );
+}
+
+export function get(id: string): PersistedAgent | undefined {
+  const row = getDatabase().prepare(agentsSql.get).get(id) as Row | undefined;
+  return row ? rowToAgent(row) : undefined;
+}
+
+/** Rows still queued/running — interrupted by the last restart. */
+export function listInterrupted(): PersistedAgent[] {
+  const rows = getDatabase().prepare(agentsSql.listInterrupted).all() as Row[];
+  return rows.map(rowToAgent);
+}
+
+export function remove(id: string): boolean {
+  const result = getDatabase().prepare(agentsSql.remove).run(id) as {
+    changes?: number;
+  };
+  return (result.changes ?? 0) > 0;
+}
+
+/** Delete settled rows last touched before `cutoff`. Returns how many. */
+export function pruneSettled(cutoff: number): number {
+  const result = getDatabase().prepare(agentsSql.pruneSettled).run(cutoff) as {
+    changes?: number;
+  };
+  return result.changes ?? 0;
+}
+
+/** Test-only: wipe the table between suites sharing a worker DB. */
+export function removeAll(): void {
+  getDatabase().prepare(agentsSql.removeAll).run();
+}

package/src/storage/sql/agents.sql

@@ -0,0 +1,43 @@
+-- Statements for the agents table (see storage/agents/repo.ts for
+-- the parameter order and row↔domain mapping).
+
+-- name: upsert
+INSERT OR REPLACE INTO agents
+  (id, label, brief, parent_kind, parent_id, parent_numeric, backend_id,
+   model, requested_model, effort, timeout_ms, depth, cwd, state,
+   created_at, started_at, ended_at, updated_at, session_id, inbox_json,
+   reported, result_summary, result_details, error, elapsed_ms,
+   resume_count, interrupted_at, preflight)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+
+-- name: get
+SELECT id, label, brief, parent_kind, parent_id, parent_numeric, backend_id,
+       model, requested_model, effort, timeout_ms, depth, cwd, state,
+       created_at, started_at, ended_at, updated_at, session_id, inbox_json,
+       reported, result_summary, result_details, error, elapsed_ms,
+       resume_count, interrupted_at, preflight
+FROM agents WHERE id = ?
+
+-- Rows a restart interrupted, parents before children (a child can only
+-- be re-attached to a parent that is already back in the registry).
+
+-- name: listInterrupted
+SELECT id, label, brief, parent_kind, parent_id, parent_numeric, backend_id,
+       model, requested_model, effort, timeout_ms, depth, cwd, state,
+       created_at, started_at, ended_at, updated_at, session_id, inbox_json,
+       reported, result_summary, result_details, error, elapsed_ms,
+       resume_count, interrupted_at, preflight
+FROM agents WHERE state IN ('queued', 'running')
+ORDER BY depth, created_at
+
+-- name: remove
+DELETE FROM agents WHERE id = ?
+
+-- Retention: settled rows past their window. Live rows are never pruned.
+
+-- name: pruneSettled
+DELETE FROM agents
+WHERE state NOT IN ('queued', 'running') AND updated_at < ?
+
+-- name: removeAll
+DELETE FROM agents