talon-agent 5.26.6 → 5.28.0

package/src/core/mesh/credentials/store.ts

@@ -23,7 +23,7 @@ import { resolve } from "node:path";
 import { dirs } from "../../../util/paths.js";
 import { log, logWarn } from "../../../util/log.js";
 import { TalonError } from "../../errors.js";
-import { readArray, writePrivateJson } from "../persist.js";
+import { readArray, writePrivateJson, writesSettled } from "../persist.js";
 import { faultText } from "../../engine/fault-text.js";
 import { raiseAlert, resolveAlert } from "../../frontend-runtime/alerts.js";
 import {
@@ -506,6 +506,14 @@ export class DeviceCredentialStore {
     }
   }
 
+  /**
+   * Wait for every background write queued so far (mintNow, bind, re-pair
+   * revocation, lastUsedAt touches) to reach disk or fail.
+   */
+  flush(): Promise<void> {
+    return writesSettled(this.file);
+  }
+
   private persistSoon(): void {
     void this.persist().catch((err: unknown) =>
       logWarn("mesh", `Could not persist mesh credentials: ${err}`),

package/src/core/mesh/persist.ts

@@ -25,6 +25,15 @@ export async function readArray<T>(path: string): Promise<T[]> {
   }
 }
 
+/**
+ * Resolve once every write queued for `path` so far has finished (settled,
+ * success or failure) — for callers that persisted fire-and-forget and now
+ * need the file on disk.
+ */
+export function writesSettled(path: string): Promise<void> {
+  return writeQueues.get(path) ?? Promise.resolve();
+}
+
 /** Persist JSON atomically with 0600 perms, serialized per path. */
 export async function writePrivateJson(
   path: string,

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/frontend/discord/actions/channels.ts

@@ -14,9 +14,12 @@ export async function resolveChannel(
   const info = lookupDiscordChat(numericChatId);
   if (!info) return null;
   try {
-    const ch = await client.channels.fetch(info.channelId);
-    if (ch && "send" in ch && (ch as TextBasedChannel).isSendable?.()) {
-      return ch as TextBasedChannel;
+    // A DM rebuilt from its chat key has no channel id — open it by user.
+    if (info.channelId) {
+      const ch = await client.channels.fetch(info.channelId);
+      if (ch && "send" in ch && (ch as TextBasedChannel).isSendable?.()) {
+        return ch as TextBasedChannel;
+      }
     }
     if (info.userId) {
       const user = await client.users.fetch(info.userId);

package/src/frontend/discord/actions/index.ts

@@ -24,6 +24,11 @@ import type { Client } from "discord.js";
 import type { Gateway } from "../../../core/engine/gateway.js";
 import type { ActionResult } from "../../../core/types.js";
 import { resolveChannel } from "./channels.js";
+import {
+  lookupDiscordChat,
+  parseDiscordChatKey,
+  registerDiscordChat,
+} from "../handlers/registry.js";
 import { messagingHandlers, restoreScheduledMessages } from "./messaging.js";
 import { mediaHandlers } from "./media.js";
 import { chatInfoHandlers } from "./chat-info.js";
@@ -43,6 +48,24 @@ const handlers: DiscordActionHandlers = Object.assign(Object.create(null), {
   ...chatInfoHandlers,
 });
 
+/**
+ * A plain send addressed to a chat this process hasn't registered — the
+ * channel that asked for a staged restore, say, before anyone has spoken
+ * in it since the restart. The sender names the chat by key in
+ * `body.target`; when that key is the one the numeric id was derived
+ * from, register it so the channel resolves. send_message only.
+ */
+function adoptAddressedChat(
+  action: string,
+  body: Record<string, unknown>,
+  chatId: number,
+): void {
+  if (action !== "send_message" || lookupDiscordChat(chatId)) return;
+  const key = typeof body.target === "string" ? body.target : "";
+  const info = key ? parseDiscordChatKey(key) : undefined;
+  if (info && info.numericChatId === chatId) registerDiscordChat(info);
+}
+
 export function createDiscordActionHandler(client: Client, gateway: Gateway) {
   const scheduledMessages = new Map<string, ReturnType<typeof setTimeout>>();
 
@@ -58,6 +81,7 @@ export function createDiscordActionHandler(client: Client, gateway: Gateway) {
     const handler = handlers[action];
     if (!handler) return null; // not a Discord action
 
+    adoptAddressedChat(action, body, chatId);
     const channel = await resolveChannel(client, chatId);
 
     // For non-channel actions (e.g. cancel_scheduled) that don't need a

package/src/frontend/discord/commands/backup.ts

@@ -180,6 +180,7 @@ export async function handleBackupComponent(
       id,
       requestedAt: Date.now(),
       requestedBy: chatId,
+      frontend: "discord",
     });
     respawnSelf(`discord /backup restore ${id}`);
   } catch (err) {

package/src/frontend/discord/handlers/registry.ts

@@ -3,6 +3,7 @@
  * Discord channel info the action handler needs to post back.
  */
 
+import { deriveNumericChatId } from "../../../core/frontend-runtime/chat-id.js";
 import {
   chatRegistry,
   chatRegistryByString,
@@ -21,3 +22,37 @@ export function lookupDiscordChat(
 ): DiscordChatInfo | undefined {
   return chatRegistry.get(numericChatId);
 }
+
+/**
+ * Rebuild a chat's registry entry from its string key alone
+ * (`discord_guild_<guild>_<channel>` or `discord_dm_<user>`), for a chat
+ * this process hasn't seen a message from yet — the registry is in-memory,
+ * so after a restart only the allowed users' DMs are known until someone
+ * speaks. A DM entry carries no channel id; resolveChannel opens the DM
+ * from the user id. Undefined for anything that isn't a Discord chat key.
+ */
+export function parseDiscordChatKey(
+  chatKey: string,
+): DiscordChatInfo | undefined {
+  const guild = /^discord_guild_(\d+)_(\d+)$/.exec(chatKey);
+  if (guild) {
+    return {
+      channelId: guild[2]!,
+      guildId: guild[1]!,
+      userId: null,
+      numericChatId: deriveNumericChatId(chatKey),
+      chatId: chatKey,
+    };
+  }
+  const dm = /^discord_dm_(\d+)$/.exec(chatKey);
+  if (dm) {
+    return {
+      channelId: "",
+      guildId: null,
+      userId: dm[1]!,
+      numericChatId: deriveNumericChatId(chatKey),
+      chatId: chatKey,
+    };
+  }
+  return undefined;
+}

package/src/frontend/native/commands/backup.ts

@@ -145,6 +145,7 @@ async function restore(
       id,
       requestedAt: Date.now(),
       requestedBy: ctx.entry.id,
+      frontend: "native",
     });
   } catch (err) {
     logError("backup", "Staging the restore failed", err);

package/src/frontend/native/turn/actions.ts

@@ -15,6 +15,10 @@ import type {
 import type { Gateway } from "../../../core/engine/gateway.js";
 import type { NativeChats, ChatEntry } from "../chats/chats.js";
 import type { BridgeEvent, ClientButton } from "../protocol.js";
+import {
+  deriveNumericChatId,
+  isNativeChatId,
+} from "../../../core/frontend-runtime/chat-id.js";
 
 export type NativeActionDeps = {
   chats: NativeChats;
@@ -69,6 +73,28 @@ const NATIVE_ACTIONS = new Set([
   "send_chat_action",
 ]);
 
+/**
+ * A plain send addressed to a native chat this daemon doesn't list — the
+ * chat that asked for a staged restore, say, when the restored database
+ * predates it. The sender names the chat by key in `body.target`; the
+ * chat is adopted (as a deep link would) so the message lands in its
+ * history and the app shows it. Only when the key really is the chat the
+ * numeric id was derived from, and only for send_message: edits,
+ * reactions and deletes address messages, which an unknown chat has none of.
+ */
+function adoptAddressedChat(
+  chats: NativeChats,
+  action: string,
+  body: Record<string, unknown>,
+  chatId: number,
+): ChatEntry | undefined {
+  if (action !== "send_message") return undefined;
+  const key = typeof body.target === "string" ? body.target : "";
+  if (!key || !isNativeChatId(key) || deriveNumericChatId(key) !== chatId)
+    return undefined;
+  return chats.ensure(key);
+}
+
 export function createNativeActionHandler(
   deps: NativeActionDeps,
 ): FrontendActionHandler {
@@ -77,7 +103,9 @@ export function createNativeActionHandler(
   return async (body, chatId): Promise<ActionResult | null> => {
     const action = typeof body.action === "string" ? body.action : "";
     if (!NATIVE_ACTIONS.has(action)) return null;
-    const entry = chats.byNumeric(chatId);
+    const entry =
+      chats.byNumeric(chatId) ??
+      adoptAddressedChat(chats, action, body, chatId);
     if (!entry) return { ok: false, error: "No active native chat" };
 
     switch (action) {

package/src/frontend/telegram/commands/backup.ts

@@ -166,6 +166,7 @@ export async function stageRestore(chatId: string, id: string): Promise<void> {
     id,
     requestedAt: Date.now(),
     requestedBy: chatId,
+    frontend: "telegram",
   });
   respawnSelf(`telegram /backup restore ${id}`);
 }

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

package/src/storage/sql/schema.sql

@@ -406,3 +406,57 @@ CREATE TABLE IF NOT EXISTS backup_remotes (
   error       TEXT,
   PRIMARY KEY (backup_id, target_id)
 );
+
+-- Sub-agents, persisted so a daemon restart does not kill them. One row
+-- per spawn, written at registration and kept current on every lifecycle
+-- change (start, SDK session id, mailbox, report, settle). On boot, every
+-- row still 'queued' or 'running' was interrupted by the restart and is
+-- respawned — resuming its backend session when the backend can. See
+-- resumeAgentsAfterRestart in core/agents/runner.ts.
+CREATE TABLE IF NOT EXISTS agents (
+  id               TEXT PRIMARY KEY,
+  label            TEXT    NOT NULL,
+  brief            TEXT    NOT NULL,
+  -- 'chat' | 'agent'; parent_id is the chat key or the parent agent id.
+  parent_kind      TEXT    NOT NULL,
+  parent_id        TEXT    NOT NULL,
+  -- The frontend's numeric chat id (chat parents only) — the dispatcher
+  -- needs it to wake the chat with the report.
+  parent_numeric   INTEGER,
+  backend_id       TEXT    NOT NULL,
+  -- The model the run resolved to, and the one the caller asked for (null
+  -- = the backend default), so a resume can re-resolve if it vanished.
+  model            TEXT,
+  requested_model  TEXT,
+  effort           TEXT,
+  timeout_ms       INTEGER,
+  depth            INTEGER NOT NULL DEFAULT 0,
+  cwd              TEXT,
+  state            TEXT    NOT NULL,
+  created_at       INTEGER NOT NULL,
+  started_at       INTEGER,
+  ended_at         INTEGER,
+  updated_at       INTEGER NOT NULL,
+  -- Backend conversation handle (Claude SDK session id, Codex thread id),
+  -- recorded as soon as the backend reports it.
+  session_id       TEXT,
+  -- Pending check_inbox messages, JSON array of {from,text,at}.
+  inbox_json       TEXT    NOT NULL DEFAULT '[]',
+  -- 1 once report_result landed; result_* hold what it said.
+  reported         INTEGER NOT NULL DEFAULT 0,
+  result_summary   TEXT,
+  result_details   TEXT,
+  error            TEXT,
+  -- Wall-clock the agent has already spent in earlier (interrupted) runs,
+  -- charged against its timeout when it is resumed.
+  elapsed_ms       INTEGER NOT NULL DEFAULT 0,
+  -- How many times a restart has resumed it (bounded — a run that keeps
+  -- dying with the daemon eventually settles as failed).
+  resume_count     INTEGER NOT NULL DEFAULT 0,
+  -- When the last restart interrupted it, if one did.
+  interrupted_at   INTEGER,
+  -- 1 when the spawn asked for the pre-flight lane, so a re-briefed resume
+  -- keeps the instruction.
+  preflight        INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_agents_state ON agents(state, depth, created_at);

package/src/storage/sql/statements.generated.ts

@@ -410,7 +410,93 @@ CREATE TABLE IF NOT EXISTS backup_remotes (
   uploaded_at INTEGER,
   error       TEXT,
   PRIMARY KEY (backup_id, target_id)
-);`;
+);
+
+-- Sub-agents, persisted so a daemon restart does not kill them. One row
+-- per spawn, written at registration and kept current on every lifecycle
+-- change (start, SDK session id, mailbox, report, settle). On boot, every
+-- row still 'queued' or 'running' was interrupted by the restart and is
+-- respawned — resuming its backend session when the backend can. See
+-- resumeAgentsAfterRestart in core/agents/runner.ts.
+CREATE TABLE IF NOT EXISTS agents (
+  id               TEXT PRIMARY KEY,
+  label            TEXT    NOT NULL,
+  brief            TEXT    NOT NULL,
+  -- 'chat' | 'agent'; parent_id is the chat key or the parent agent id.
+  parent_kind      TEXT    NOT NULL,
+  parent_id        TEXT    NOT NULL,
+  -- The frontend's numeric chat id (chat parents only) — the dispatcher
+  -- needs it to wake the chat with the report.
+  parent_numeric   INTEGER,
+  backend_id       TEXT    NOT NULL,
+  -- The model the run resolved to, and the one the caller asked for (null
+  -- = the backend default), so a resume can re-resolve if it vanished.
+  model            TEXT,
+  requested_model  TEXT,
+  effort           TEXT,
+  timeout_ms       INTEGER,
+  depth            INTEGER NOT NULL DEFAULT 0,
+  cwd              TEXT,
+  state            TEXT    NOT NULL,
+  created_at       INTEGER NOT NULL,
+  started_at       INTEGER,
+  ended_at         INTEGER,
+  updated_at       INTEGER NOT NULL,
+  -- Backend conversation handle (Claude SDK session id, Codex thread id),
+  -- recorded as soon as the backend reports it.
+  session_id       TEXT,
+  -- Pending check_inbox messages, JSON array of {from,text,at}.
+  inbox_json       TEXT    NOT NULL DEFAULT '[]',
+  -- 1 once report_result landed; result_* hold what it said.
+  reported         INTEGER NOT NULL DEFAULT 0,
+  result_summary   TEXT,
+  result_details   TEXT,
+  error            TEXT,
+  -- Wall-clock the agent has already spent in earlier (interrupted) runs,
+  -- charged against its timeout when it is resumed.
+  elapsed_ms       INTEGER NOT NULL DEFAULT 0,
+  -- How many times a restart has resumed it (bounded — a run that keeps
+  -- dying with the daemon eventually settles as failed).
+  resume_count     INTEGER NOT NULL DEFAULT 0,
+  -- When the last restart interrupted it, if one did.
+  interrupted_at   INTEGER,
+  -- 1 when the spawn asked for the pre-flight lane, so a re-briefed resume
+  -- keeps the instruction.
+  preflight        INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_agents_state ON agents(state, depth, created_at);`;
+
+export const agentsSql = {
+  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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  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).`,
+  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`,
+  remove: `DELETE FROM agents WHERE id = ?
+
+-- Retention: settled rows past their window. Live rows are never pruned.`,
+  pruneSettled: `DELETE FROM agents
+WHERE state NOT IN ('queued', 'running') AND updated_at < ?`,
+  removeAll: `DELETE FROM agents`,
+} as const;
 
 export const backupsSql = {
   upsert: `INSERT OR REPLACE INTO backups