@martintrojer/mu 0.3.1

package/dist/index.d.ts

@@ -0,0 +1,3130 @@
+import { Database } from 'better-sqlite3';
+
+/**
+ * One actionable next step. The `intent` is human-prose ("Drop notes
+ * as you work"); the `command` is a literal shell command the user (or
+ * an LLM) can copy-paste or `eval` directly.
+ *
+ * Used both for success-path hints (post-verb) and for typed-error
+ * resolutions (in the error message + JSON output).
+ */
+interface NextStep {
+    /** Short human-prose label, e.g. "Drop notes as you work". */
+    intent: string;
+    /** Literal shell command, e.g. `mu task note foo "..."`. */
+    command: string;
+}
+/**
+ * Marker interface for typed errors that carry actionable resolutions.
+ * The handler checks this with a duck-typed `typeof err.errorNextSteps
+ * === "function"` rather than instanceof so cross-realm errors (e.g.
+ * thrown from a different module instance after a hot-reload) still
+ * surface their nextSteps.
+ */
+interface HasNextSteps {
+    errorNextSteps(): NextStep[];
+}
+
+type Db = Database;
+interface OpenDbOptions {
+    /**
+     * Absolute path to the SQLite file. Defaults to MU_DB_PATH env var or
+     * the XDG state path (see `defaultDbPath`). Use a per-test temp path
+     * in tests.
+     */
+    path?: string;
+    /**
+     * If true, opens the DB read-only. Used by `mu sql` and similar read-only
+     * surfaces to enforce no-mutation guarantees at the connection level.
+     */
+    readonly?: boolean;
+}
+/**
+ * Resolve the canonical mu state directory:
+ *   MU_STATE_DIR > $XDG_STATE_HOME/mu > ~/.local/state/mu
+ */
+declare function defaultStateDir(): string;
+/**
+ * Resolve the canonical DB path:
+ *   MU_DB_PATH > <state-dir>/mu.db
+ */
+declare function defaultDbPath(): string;
+/**
+ * Per-workstream artifact directory: <state-dir>/workstreams/<workstream>/
+ *
+ * Created lazily by callers. 0.1.0 doesn't write to it yet — reserved
+ * for future snapshots / tracing logs / forensic pane captures. The DB
+ * stays canonical and shared; this directory is only for things that
+ * naturally don't need cross-workstream queries.
+ */
+declare function workstreamStateDir(workstream: string): string;
+/**
+ * Open the mu database. Creates the parent directory and applies the schema
+ * idempotently on every open. Safe to call from many short-lived processes
+ * concurrently — WAL mode handles cross-process writes.
+ */
+declare function openDb(options?: OpenDbOptions): Db;
+declare class SchemaTooOldError extends Error implements HasNextSteps {
+    readonly detectedVersion: number;
+    readonly requiredVersion: number;
+    readonly name = "SchemaTooOldError";
+    constructor(detectedVersion: number, requiredVersion: number);
+    errorNextSteps(): NextStep[];
+}
+/** Test seam: ensure a workstream's artifact dir exists. Unused today. */
+declare function ensureWorkstreamStateDir(workstream: string): string;
+/** The schema version a fresh DB starts at. v7 drops the
+ *  `approvals` table on top of v6 (which added 5 archive_* tables
+ *  on top of v5's surrogate-PK substrate; docs/ARCHITECTURE.md §
+ *  Surrogate-PK + SDK-boundary discipline). The refusal floor is
+ *  v5 — pre-v5 DBs throw `SchemaTooOldError`; v5 → v6 → v7 DBs
+ *  are forward-bumped in place by `applySchema`. */
+declare const CURRENT_SCHEMA_VERSION = 7;
+/** Tables a healthy DB must contain. Single source of truth so
+ *  `mu doctor` and any other consumer don't drift. Adding a new table
+ *  = one new entry here AND a CREATE TABLE in CURRENT_SCHEMA. (Schema
+ *  changes that aren't compatible with prior schemas bump
+ *  CURRENT_SCHEMA_VERSION and ship with a one-shot script under
+ *  scripts/ (the v4→v5 transition was the canonical example
+ *  before the script was deleted post-landing). */
+declare const EXPECTED_TABLES: readonly string[];
+
+/**
+ * The full agent lifecycle status. Most values are scrollback-derived
+ * (`DetectedStatus`); the rest are set by the lifecycle layer.
+ */
+type AgentStatus = "spawning" | "busy" | "needs_input" | "needs_permission" | "free" | "unreachable" | "terminated";
+/** Status that can be inferred from pane scrollback. */
+type DetectedStatus = "busy" | "needs_input" | "needs_permission";
+/**
+ * Run the detector against pane scrollback and return the inferred
+ * status. Permission overrides busy.
+ */
+declare function detectPiStatus(scrollback: string): DetectedStatus;
+/**
+ * Public for tests — extract the tail window the detector actually
+ * inspects. Take last TAIL_WINDOW_LINES, strip trailing blanks, take
+ * last TAIL_LINES.
+ */
+declare function extractTail(scrollback: string): string;
+
+declare class TmuxError extends Error implements HasNextSteps {
+    readonly args: readonly string[];
+    readonly stderr: string;
+    readonly stdout: string;
+    readonly exitCode: number | null;
+    constructor(args: readonly string[], stderr: string, stdout: string, exitCode: number | null);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown when a verb references a tmux pane id that doesn't exist on
+ * the running tmux server. Distinct from TmuxError (which wraps any
+ * tmux command failure) so callers can map it to a specific exit code
+ * (`mu` maps it to 5 — substrate failure — alongside other tmux
+ * issues, but the message is more actionable than a raw tmux stderr).
+ */
+declare class PaneNotFoundError extends Error implements HasNextSteps {
+    readonly paneId: string;
+    readonly name = "PaneNotFoundError";
+    constructor(paneId: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Stable tmux pane IDs are of the form `%N` (e.g. "%15"). They never change
+ * for the lifetime of the pane. **Pane indexes** (0, 1, 2…) are volatile and
+ * shift when other panes close — never store or pass them.
+ */
+declare const PANE_ID_RE: RegExp;
+declare function isValidPaneId(s: string): boolean;
+declare function assertValidPaneId(s: string): void;
+/**
+ * Delay between bracketed-paste and Enter, in milliseconds. Claude/Codex/pi
+ * process pasted text asynchronously; without this delay, Enter can arrive
+ * before the agent has ingested the text. Defaults to 500; lower for tests,
+ * raise for slow remotes via `MU_SEND_DELAY_MS`.
+ */
+declare function defaultSendDelayMs(): number;
+interface TmuxExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+}
+type TmuxExecutor = (args: readonly string[]) => Promise<TmuxExecResult>;
+/**
+ * Install a custom executor (for tests). Returns the previous executor so
+ * tests can restore it cleanly. Production code should never call this.
+ */
+declare function setTmuxExecutor(executor: TmuxExecutor): TmuxExecutor;
+/** Restore the real (execa-backed) executor. */
+declare function resetTmuxExecutor(): void;
+/**
+ * Run an arbitrary tmux command. The single point of contact with the
+ * tmux binary; every higher-level operation in this module goes through it.
+ *
+ * Throws `TmuxError` on non-zero exit. Returns stdout on success.
+ */
+declare function tmux(args: readonly string[]): Promise<string>;
+declare function setSleepForTests(impl: (ms: number) => Promise<void>): (ms: number) => Promise<void>;
+declare function resetSleep(): void;
+/** Test-aware sleep — honours `setSleepForTests`. Public so other modules
+ *  (notably `agents.ts` for spawn liveness polling) get free no-op-ing in
+ *  tests without re-implementing the swap. */
+declare function sleep(ms: number): Promise<void>;
+interface TmuxSession {
+    name: string;
+}
+interface TmuxWindow {
+    /** tmux window id, e.g. "@1". */
+    id: string;
+    name: string;
+    /** Session this window belongs to (only set by cross-session listings). */
+    sessionName?: string;
+}
+interface TmuxPane {
+    /** Stable tmux pane id, e.g. "%15". */
+    paneId: string;
+    /** Pane title set via `select-pane -T`. The agent's name in mu's convention. */
+    title: string;
+    /** Current foreground command (e.g. "claude", "node", "bash"). */
+    command: string;
+    /** Window this pane lives in. Only set by cross-window listings. */
+    windowId?: string;
+    /** Session this pane lives in. Only set by cross-session listings. */
+    sessionName?: string;
+}
+declare function listSessions(): Promise<TmuxSession[]>;
+declare function sessionExists(name: string): Promise<boolean>;
+interface NewSessionOptions {
+    detached?: boolean;
+    windowName?: string;
+    command?: string;
+    /** Initial working directory for the first pane (`-c <path>`). */
+    cwd?: string;
+    /** Extra env vars to set in the new pane via tmux `-e KEY=VALUE`.
+     *  Available since tmux 3.0; sets the variable in the new pane's
+     *  environment without polluting the tmux server's global env. */
+    env?: Record<string, string>;
+}
+declare function newSession(name: string, opts?: NewSessionOptions): Promise<void>;
+interface NewSessionWithPaneOptions {
+    windowName: string;
+    command: string;
+    cwd?: string;
+    detached?: boolean;
+    /** Extra env vars to set in the new pane via tmux `-e KEY=VALUE`. */
+    env?: Record<string, string>;
+}
+/**
+ * Create a tmux session AND its first window+pane in one atomic call.
+ * Returns the new pane's stable id. Used by mu when spawning the first
+ * agent in a workstream so we never end up with an empty `mu-<workstream>`
+ * session left behind by a failed spawn.
+ */
+declare function newSessionWithPane(name: string, opts: NewSessionWithPaneOptions): Promise<string>;
+/** Idempotent: succeeds even if the session is already gone. */
+declare function killSession(name: string): Promise<void>;
+declare function listWindows(session?: string): Promise<TmuxWindow[]>;
+interface NewWindowOptions {
+    /** Target session. Required if invoking outside an existing tmux client. */
+    session?: string;
+    /** Window name. Maps to the agent's `tab:` value (or its name if no tab). */
+    name: string;
+    /** Command to run in the first pane. */
+    command: string;
+    /** If true, do not switch focus. Defaults to true. */
+    detached?: boolean;
+    /** Initial working directory (`-c <path>`). */
+    cwd?: string;
+    /** Extra env vars to set in the new pane via tmux `-e KEY=VALUE`. */
+    env?: Record<string, string>;
+}
+/**
+ * Create a new tmux window with one pane. Returns the new pane's stable
+ * pane id (e.g. `%15`).
+ */
+declare function newWindow(opts: NewWindowOptions): Promise<string>;
+/**
+ * List ALL panes in a tmux session (across every window). Used by
+ * reconciliation to find every pane in the workstream's session.
+ *
+ * Note `list-panes -t <session>` (no -s) lists panes in the current
+ * *window* of that session, not the whole session — a common gotcha.
+ * `-s` is the flag that says "all panes in this session."
+ *
+ * Returns `[]` (not throws) when the session doesn't exist or has no
+ * panes. tmux destroys a session as soon as its last pane closes, so the
+ * "session was just here a moment ago" case is normal during reconcile.
+ * tmux's error wording in this case varies ("can't find session" or
+ * "can't find window"), so we match either.
+ */
+declare function listPanesInSession(session: string): Promise<TmuxPane[]>;
+/**
+ * List panes in the current session, a specific window/session target, or
+ * all panes across all sessions when `target` is the literal "*".
+ */
+declare function listPanes(target?: string): Promise<TmuxPane[]>;
+interface SplitWindowOptions {
+    /** Target window or pane (e.g. ":Backend" or "%15"). */
+    target: string;
+    command: string;
+    /** Horizontal split (side-by-side). Default true. */
+    horizontal?: boolean;
+    detached?: boolean;
+    /** Initial working directory for the new pane (`-c <path>`). */
+    cwd?: string;
+    /** Extra env vars to set in the new pane via tmux `-e KEY=VALUE`. */
+    env?: Record<string, string>;
+}
+/**
+ * Split a window and run a command in the new pane. Returns the new pane's
+ * stable pane id.
+ */
+declare function splitWindow(opts: SplitWindowOptions): Promise<string>;
+/** Idempotent: succeeds even if the pane is already gone. */
+declare function killPane(paneId: string): Promise<void>;
+declare function paneExists(paneId: string): Promise<boolean>;
+declare function setPaneTitle(paneId: string, title: string): Promise<void>;
+/**
+ * Look up the window id (e.g. `@42`) that contains a given pane id
+ * (e.g. `%15`). Used by spawn so we can apply window-scoped options
+ * (`pane-border-status`) to the freshly created window.
+ *
+ * Returns undefined if the pane no longer exists.
+ */
+declare function getWindowIdForPane(paneId: string): Promise<string | undefined>;
+/**
+ * Apply the mu pane border (status=top, format='[mu] #{pane_title}')
+ * to EVERY window currently in `session`. Idempotent. Best-effort:
+ * windows that have vanished mid-iteration are silently skipped. Used
+ * by `mu workstream init` (covers the placeholder `_mu` window plus
+ * any windows that already exist, e.g. on re-init of an upgraded
+ * mu-pre-border session) and by `mu agent spawn` (covers the
+ * just-created window so the border shows immediately on attach).
+ *
+ * No-op (returns 0) when `MU_BANNER_QUIET=1`.
+ *
+ * Returns the number of windows that received the option.
+ */
+declare function enableMuPaneBordersForSession(session: string): Promise<number>;
+/**
+ * Apply the mu pane border to the window containing `paneId`. This is
+ * the spawn/adopt shape: callers have a pane id (from `new-window` or
+ * from an adopt target), and need to resolve the enclosing window
+ * before calling `enableMuPaneBorders` (a window-scoped option).
+ *
+ * Self-checks `MU_BANNER_QUIET` and swallows tmux errors — the border
+ * is decorative; failing to set it is never load-bearing.
+ */
+declare function enableMuPaneBordersForPane(paneId: string): Promise<void>;
+/**
+ * Enable a one-line top pane border on a specific window/session target,
+ * showing `[mu] <pane-title>`. Idempotent (set-option is a write, not
+ * a toggle).
+ *
+ * IMPORTANT: tmux's `pane-border-status` and `pane-border-format` are
+ * **window** options, not session options. `set-option -t <session>`
+ * only updates the active window at call time — windows created later
+ * inherit from the GLOBAL value (which is `off` by default and which
+ * we deliberately do NOT touch, since changing the global would
+ * affect every other tmux session on the user's machine, including
+ * dotfile-curated ones).
+ *
+ * Therefore mu must call this twice:
+ *   1. At `mu workstream init` time on the placeholder `_mu` window
+ *      (so an attached operator sees a border immediately).
+ *   2. On every `mu agent spawn` (which calls `tmux new-window`),
+ *      against the new window's id.
+ *
+ * The border is tmux chrome, not pane content: it doesn't scroll, it
+ * survives copy-mode, and the inner CLI never sees it.
+ *
+ * Designed in roadmap-v0-2 hud_visual_cue_design (note #283); shipped
+ * in hud_visual_cue_impl.
+ */
+declare function enableMuPaneBorders(target: string): Promise<void>;
+declare function getPaneTitle(paneId: string): Promise<string | undefined>;
+/**
+ * Read the title of the *current* pane (the one whose shell is running this
+ * process), via $TMUX_PANE. Returns undefined when not inside tmux. Used by
+ * `mu claim` to derive the agent identity from the pane title — the claim
+ * protocol's zero-config identity step.
+ */
+declare function currentPaneTitle(): Promise<string | undefined>;
+/**
+ * Read the *current* pane's interior size (`pane_width` x `pane_height`)
+ * via $TMUX_PANE. Returns undefined when not inside tmux or when the
+ * tmux call fails. Used by `mu hud` to size its tables when stdout
+ * isn't a TTY (e.g. when running under `watch -n 5 mu hud -w X` or
+ * `tmux display-popup -E 'mu hud -w X'`, both of which strip TTY-ness
+ * but still run inside a tmux pane whose dimensions matter).
+ */
+declare function currentPaneSize(): Promise<{
+    width: number;
+    height: number;
+} | undefined>;
+/**
+ * Extract the agent-name token from a (possibly composed) pane title.
+ * mu's composeAgentTitle renders titles as `name · <glyph> · task_id`,
+ * where <glyph> is a Nerd Font codepoint from STATUS_EMOJI (see
+ * src/agents.ts). The agent name is always the first ' · '-separated
+ * token. Adopted panes that haven't been re-titled by mu have just the
+ * name (one token) — still parses.
+ *
+ * Returns trimmed name, or the input unchanged if no separator.
+ */
+declare function parseAgentNameFromTitle(title: string): string;
+/**
+ * Convenience: read the current pane's title and extract the agent name.
+ */
+declare function currentAgentName(): Promise<string | undefined>;
+declare function selectLayout(window: string, layout: string): Promise<void>;
+interface SendOptions {
+    /** Override the default delay between paste and Enter, in ms. */
+    delayMs?: number;
+}
+/**
+ * Send a single line of text to a pane and submit it.
+ *
+ * Sequence:
+ *   1. exit copy mode (silent if not in copy mode)
+ *   2. load text into a uniquely-named tmux buffer
+ *   3. paste with bracketed-paste mode (-p) so apps treat as literal text;
+ *      delete buffer after paste (-d); preserve LF (-r)
+ *   4. wait MU_SEND_DELAY_MS (default 500) so the agent ingests the text
+ *   5. send Enter as a real key event
+ *
+ * Naive `send-keys "<text>"` would let characters like /, ?, f, : be
+ * interpreted by the agent's TUI or by tmux's copy mode. Always use this.
+ */
+declare function sendToPane(paneId: string, text: string, opts?: SendOptions): Promise<void>;
+interface CaptureOptions {
+    /**
+     * Number of trailing lines to capture. Omitted = full scrollback.
+     * 0 = visible pane only.
+     */
+    lines?: number;
+}
+/**
+ * Read pane scrollback as plain text (no ANSI escapes).
+ *
+ * - No options: full scrollback (`-S - -E -`)
+ * - `lines: 0`: visible pane only
+ * - `lines: N`: last N lines (`-S -N`)
+ */
+declare function capturePane(paneId: string, opts?: CaptureOptions): Promise<string>;
+
+type tmux$1_CaptureOptions = CaptureOptions;
+type tmux$1_NewSessionOptions = NewSessionOptions;
+type tmux$1_NewSessionWithPaneOptions = NewSessionWithPaneOptions;
+type tmux$1_NewWindowOptions = NewWindowOptions;
+declare const tmux$1_PANE_ID_RE: typeof PANE_ID_RE;
+type tmux$1_PaneNotFoundError = PaneNotFoundError;
+declare const tmux$1_PaneNotFoundError: typeof PaneNotFoundError;
+type tmux$1_SendOptions = SendOptions;
+type tmux$1_SplitWindowOptions = SplitWindowOptions;
+type tmux$1_TmuxError = TmuxError;
+declare const tmux$1_TmuxError: typeof TmuxError;
+type tmux$1_TmuxExecResult = TmuxExecResult;
+type tmux$1_TmuxExecutor = TmuxExecutor;
+type tmux$1_TmuxPane = TmuxPane;
+type tmux$1_TmuxSession = TmuxSession;
+type tmux$1_TmuxWindow = TmuxWindow;
+declare const tmux$1_assertValidPaneId: typeof assertValidPaneId;
+declare const tmux$1_capturePane: typeof capturePane;
+declare const tmux$1_currentAgentName: typeof currentAgentName;
+declare const tmux$1_currentPaneSize: typeof currentPaneSize;
+declare const tmux$1_currentPaneTitle: typeof currentPaneTitle;
+declare const tmux$1_defaultSendDelayMs: typeof defaultSendDelayMs;
+declare const tmux$1_enableMuPaneBorders: typeof enableMuPaneBorders;
+declare const tmux$1_enableMuPaneBordersForPane: typeof enableMuPaneBordersForPane;
+declare const tmux$1_enableMuPaneBordersForSession: typeof enableMuPaneBordersForSession;
+declare const tmux$1_getPaneTitle: typeof getPaneTitle;
+declare const tmux$1_getWindowIdForPane: typeof getWindowIdForPane;
+declare const tmux$1_isValidPaneId: typeof isValidPaneId;
+declare const tmux$1_killPane: typeof killPane;
+declare const tmux$1_killSession: typeof killSession;
+declare const tmux$1_listPanes: typeof listPanes;
+declare const tmux$1_listPanesInSession: typeof listPanesInSession;
+declare const tmux$1_listSessions: typeof listSessions;
+declare const tmux$1_listWindows: typeof listWindows;
+declare const tmux$1_newSession: typeof newSession;
+declare const tmux$1_newSessionWithPane: typeof newSessionWithPane;
+declare const tmux$1_newWindow: typeof newWindow;
+declare const tmux$1_paneExists: typeof paneExists;
+declare const tmux$1_parseAgentNameFromTitle: typeof parseAgentNameFromTitle;
+declare const tmux$1_resetSleep: typeof resetSleep;
+declare const tmux$1_resetTmuxExecutor: typeof resetTmuxExecutor;
+declare const tmux$1_selectLayout: typeof selectLayout;
+declare const tmux$1_sendToPane: typeof sendToPane;
+declare const tmux$1_sessionExists: typeof sessionExists;
+declare const tmux$1_setPaneTitle: typeof setPaneTitle;
+declare const tmux$1_setSleepForTests: typeof setSleepForTests;
+declare const tmux$1_setTmuxExecutor: typeof setTmuxExecutor;
+declare const tmux$1_sleep: typeof sleep;
+declare const tmux$1_splitWindow: typeof splitWindow;
+declare const tmux$1_tmux: typeof tmux;
+declare namespace tmux$1 {
+  export { type tmux$1_CaptureOptions as CaptureOptions, type tmux$1_NewSessionOptions as NewSessionOptions, type tmux$1_NewSessionWithPaneOptions as NewSessionWithPaneOptions, type tmux$1_NewWindowOptions as NewWindowOptions, tmux$1_PANE_ID_RE as PANE_ID_RE, tmux$1_PaneNotFoundError as PaneNotFoundError, type tmux$1_SendOptions as SendOptions, type tmux$1_SplitWindowOptions as SplitWindowOptions, tmux$1_TmuxError as TmuxError, type tmux$1_TmuxExecResult as TmuxExecResult, type tmux$1_TmuxExecutor as TmuxExecutor, type tmux$1_TmuxPane as TmuxPane, type tmux$1_TmuxSession as TmuxSession, type tmux$1_TmuxWindow as TmuxWindow, tmux$1_assertValidPaneId as assertValidPaneId, tmux$1_capturePane as capturePane, tmux$1_currentAgentName as currentAgentName, tmux$1_currentPaneSize as currentPaneSize, tmux$1_currentPaneTitle as currentPaneTitle, tmux$1_defaultSendDelayMs as defaultSendDelayMs, tmux$1_enableMuPaneBorders as enableMuPaneBorders, tmux$1_enableMuPaneBordersForPane as enableMuPaneBordersForPane, tmux$1_enableMuPaneBordersForSession as enableMuPaneBordersForSession, tmux$1_getPaneTitle as getPaneTitle, tmux$1_getWindowIdForPane as getWindowIdForPane, tmux$1_isValidPaneId as isValidPaneId, tmux$1_killPane as killPane, tmux$1_killSession as killSession, tmux$1_listPanes as listPanes, tmux$1_listPanesInSession as listPanesInSession, tmux$1_listSessions as listSessions, tmux$1_listWindows as listWindows, tmux$1_newSession as newSession, tmux$1_newSessionWithPane as newSessionWithPane, tmux$1_newWindow as newWindow, tmux$1_paneExists as paneExists, tmux$1_parseAgentNameFromTitle as parseAgentNameFromTitle, tmux$1_resetSleep as resetSleep, tmux$1_resetTmuxExecutor as resetTmuxExecutor, tmux$1_selectLayout as selectLayout, tmux$1_sendToPane as sendToPane, tmux$1_sessionExists as sessionExists, tmux$1_setPaneTitle as setPaneTitle, tmux$1_setSleepForTests as setSleepForTests, tmux$1_setTmuxExecutor as setTmuxExecutor, tmux$1_sleep as sleep, tmux$1_splitWindow as splitWindow, tmux$1_tmux as tmux };
+}
+
+/**
+ * What kind of reconciliation pass to run.
+ *
+ *   "full"        Default for `mu agent list`. Prunes ghosts (deleting
+ *                 the registry row, which fires the deleteAgent reaper
+ *                 that flips IN_PROGRESS tasks back to OPEN with
+ *                 [reaper] notes), runs status detection against
+ *                 surviving panes, surfaces orphans.
+ *
+ *   "status-only" The "freshen the operator's view" mode. Runs status
+ *                 detection (DB writes that update agent status +
+ *                 pane title — desired side-effects of a refresh) and
+ *                 orphan surface. Does NOT prune (so a dead pane's
+ *                 row stays visible until a real `mu agent list`) and
+ *                 does NOT reap. Used by `mu state`, `mu hud`, bare
+ *                 `mu`, and `mu agent attach` — the verbs an operator
+ *                 polls to answer "is worker-X busy or idle right
+ *                 now?". Status detection skips placeholder agents
+ *                 whose pane id starts with `%pending-` (mid-spawn,
+ *                 no usable scrollback yet).
+ *
+ *   "report-only" Pure observation. Counts would-be-pruned ghosts
+ *                 without deleting; skips status detection entirely
+ *                 (no DB writes, no tmux title writes); surfaces
+ *                 orphans (pure read). Used by `mu undo` (the
+ *                 post-restore pass MUST NOT delete rows the snapshot
+ *                 just restored — see
+ *                 snap_undo_reconcile_destroys_recovered_agents) and
+ *                 `mu doctor` (read-only diagnostic).
+ *
+ * Surfaced live by bug_pane_title_glyph_stuck_at_needs_input: the
+ * old `dryRun: boolean` flag conflated "don't prune" with "don't
+ * detect status", so `mu state` / `mu hud` showed stale status
+ * indefinitely. Splitting prune-suppression from status-suppression
+ * is the fix.
+ */
+type ReconcileMode = "full" | "status-only" | "report-only";
+interface ReconcileOptions {
+    /** The workstream whose registry rows we're reconciling. */
+    workstream: string;
+    /**
+     * Override the tmux session name. Defaults to `mu-<workstream>`. Useful
+     * for tests and for the rare case where a workstream's tmux session was
+     * created with a non-default name.
+     */
+    tmuxSession?: string;
+    /**
+     * Which kind of pass to run. Default is `"full"` (the documented
+     * mutating behaviour `mu agent list` has always had). See
+     * `ReconcileMode` for the full per-mode contract.
+     *
+     * BREAKING: this replaces the previous `dryRun?: boolean` flag.
+     * Migration: `dryRun: true` → `mode: "report-only"`; default
+     * (`dryRun: false` / unset) → `mode: "full"`.
+     */
+    mode?: ReconcileMode;
+}
+interface ReconcileReport {
+    /** Number of registry rows whose pane was gone. In status-only and
+     *  report-only modes this is the count of rows that WOULD have
+     *  been pruned; in `full` mode it's the count actually deleted. */
+    prunedGhosts: number;
+    /** Number of agents whose status was changed by scrollback detection.
+     *  Always 0 in `report-only` mode (status detection is skipped). */
+    statusChanges: number;
+    /** Panes in the workstream's tmux session that look like agents but
+     *  aren't in the registry. NOT auto-adopted. */
+    orphans: TmuxPane[];
+    /** Which mode this report was generated in. Lets callers switch their
+     *  output text ("agents pruned" vs "would-be-pruned (suppressed)")
+     *  without re-deriving from options. */
+    mode: ReconcileMode;
+}
+declare function reconcile(db: Db, opts: ReconcileOptions): Promise<ReconcileReport>;
+
+declare class AgentExistsError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly name = "AgentExistsError";
+    constructor(agentName: string);
+    errorNextSteps(): NextStep[];
+}
+declare class AgentNotFoundError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    /** Optional workstream context. When set, the message is enriched
+     *  with `(in workstream <ws>)` so the verb that hit the miss
+     *  (e.g. `mu workspace create <agent> -w <ws>`) doesn't leave the
+     *  operator guessing which scope was searched. Optional so existing
+     *  call sites that only know the agent name keep their original
+     *  one-line message. */
+    readonly workstream?: string | undefined;
+    readonly name = "AgentNotFoundError";
+    constructor(agentName: string, 
+    /** Optional workstream context. When set, the message is enriched
+     *  with `(in workstream <ws>)` so the verb that hit the miss
+     *  (e.g. `mu workspace create <agent> -w <ws>`) doesn't leave the
+     *  operator guessing which scope was searched. Optional so existing
+     *  call sites that only know the agent name keep their original
+     *  one-line message. */
+    workstream?: string | undefined);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown when an entity-targeted verb is invoked with `-w/--workstream
+ * <name>` but the named agent lives in a different workstream.
+ * Mirrors `TaskNotInWorkstreamError`. Maps to exit code 4 (conflict /
+ * wrong scope). Distinguishes "the user typo'd the workstream" from
+ * "the agent doesn't exist anywhere" (which surfaces as
+ * `AgentNotFoundError`).
+ */
+declare class AgentNotInWorkstreamError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly expectedWorkstream: string;
+    readonly actualWorkstream: string;
+    readonly name = "AgentNotInWorkstreamError";
+    constructor(agentName: string, expectedWorkstream: string, actualWorkstream: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown when an agent's pane is created and titled successfully but the
+ * spawned process exits within the liveness window (default 1500ms;
+ * configurable via `MU_SPAWN_LIVENESS_MS`). The most common cause is the
+ * underlying CLI failing fast: a wrapper CLI blocking on a single-instance
+ * lock, `claude` rejecting an invalid API key, etc. The agent's last
+ * scrollback (when capturable) is attached to help diagnose.
+ */
+declare class AgentDiedOnSpawnError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly paneId: string;
+    readonly scrollback: string | undefined;
+    readonly name = "AgentDiedOnSpawnError";
+    constructor(agentName: string, paneId: string, scrollback: string | undefined);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown when `closeAgent` is called on an agent that has an associated
+ * workspace AND the caller didn't explicitly opt into discarding it.
+ *
+ * Background: the FK on `vcs_workspaces.agent` cascades on agent
+ * delete, so a naive `closeAgent` drops the workspace registry row
+ * but leaves the on-disk dir orphaned (mu can't see it via
+ * `mu workspace list / free / path` afterwards). Surfaced during
+ * the multi-agent dogfood teardown when three workspaces went
+ * orphaned silently.
+ *
+ * The fix: refuse close if a workspace exists; force the caller to
+ * decide. Two actionable resolutions:
+ *   - `mu workspace free <agent>` first, then close cleanly.
+ *   - `mu agent close <agent> --discard-workspace` to free the
+ *     workspace AND close the agent in one shot (lossy: pending
+ *     changes in the workspace are gone).
+ *
+ * Maps to exit code 4 (conflict) via the cli.ts handler.
+ */
+declare class WorkspacePreservedError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly workspacePath: string;
+    readonly name = "WorkspacePreservedError";
+    constructor(agentName: string, workspacePath: string);
+    errorNextSteps(): NextStep[];
+}
+
+type VcsBackendName = "jj" | "sl" | "git" | "none";
+interface RebaseResult {
+    /** The ref the workspace was actually rebased onto (resolved
+     *  symbolic-or-revset → concrete name). For git that is the
+     *  resolveGitMainRef() symbolic ref; for jj/sl it's the literal
+     *  `trunk()` revset (or whatever the operator passed via fromRef). */
+    fromRef: string;
+    /** Commit subjects (or descriptions) that got replayed, oldest-first.
+     *  Empty when the workspace was already at fromRef (no-op). */
+    replayed: string[];
+    /** Files / commits that conflicted during the rebase. Always
+     *  empty for a successful rebase — a non-empty conflicts list
+     *  means we threw WorkspaceConflictError before returning. The
+     *  field exists so the error's serialised payload can carry it. */
+    conflicts: string[];
+}
+interface CommitSummary {
+    /** Full commit / change id. */
+    sha: string;
+    /** First-line description / subject. */
+    subject: string;
+    /** Remainder of the commit message (may be empty). */
+    body: string;
+    /** ISO-8601 author / commit timestamp. */
+    authorDate: string;
+}
+interface CreateWorkspaceOptions$1 {
+    /** The repository being branched from. Absolute path. */
+    projectRoot: string;
+    /** Where to place the new workspace. Absolute path; must NOT exist. */
+    workspacePath: string;
+    /** Optional commit / branch / changeset id to base off. Backend-specific:
+     *  git uses it as a `git worktree add`'s ref, jj as a revset, sl as a
+     *  rev. Undefined = current head. */
+    parentRef?: string;
+}
+interface CreateWorkspaceResult {
+    /** The actual ref the workspace points at (resolved to a stable id
+     *  when possible). Stored on the row; useful for `mu workspace list`
+     *  and for `--commit` flows. May be null for backends that don't
+     *  expose a meaningful parent (e.g. `none`). */
+    parentRef: string | null;
+}
+interface FreeWorkspaceOptions$1 {
+    workspacePath: string;
+    /** If true, attempt to commit any pending changes BEFORE removal.
+     *  Backend-specific: jj auto-commits via `jj describe + jj new`, git
+     *  needs an explicit commit on the worktree, sl needs `sl commit`,
+     *  none has nothing to commit. If pending changes exist and `commit`
+     *  is false, the on-disk directory still gets removed and changes are
+     *  lost \u2014 the verb prints a clear warning. */
+    commit: boolean;
+}
+interface FreeWorkspaceResult$1 {
+    /** The commit id that captured the pending changes, when `commit` was
+     *  true and there was something to commit. Otherwise undefined. */
+    committedRef?: string;
+    /** True iff the on-disk path was actually removed (vs. already gone). */
+    removed: boolean;
+}
+interface VcsBackend {
+    readonly name: VcsBackendName;
+    /** True iff this backend should handle `projectRoot`. Implementations
+     *  check for the relevant marker dir (`.jj`, `.sl`, `.git`); `none`
+     *  always returns true and is consulted last. */
+    detect(projectRoot: string): Promise<boolean>;
+    createWorkspace(opts: CreateWorkspaceOptions$1): Promise<CreateWorkspaceResult>;
+    freeWorkspace(opts: FreeWorkspaceOptions$1): Promise<FreeWorkspaceResult$1>;
+    /**
+     * Count commits that the project's default branch ("main") has but
+     * `ref` does not — i.e. how many commits `ref` is BEHIND main.
+     *
+     * Used by `mu workspace list` and `mu state` to surface staleness
+     * (bug_workspace_stale_parent_silent_drift). Cheap, pure-observation:
+     * NO automatic fetch. We compare against whatever main resolves to in
+     * the workspace's LOCAL refs cache. The user can `git fetch` (or
+     * equivalent) themselves if they want a fresher number.
+     *
+     * Returns null when:
+     *  - main / trunk cannot be resolved (no origin/HEAD, no origin/main,
+     *    no origin/master, no trunk() bookmark, etc.)
+     *  - the underlying VCS command fails for any reason (detached worktree,
+     *    missing refs, the `none` backend which has no notion of "main")
+     *
+     * Callers treat null as "unknown — render — — and don't warn".
+     */
+    commitsBehind(workspacePath: string, ref: string): Promise<number | null>;
+    /**
+     * Rebase the workspace onto `fromRef` (or the backend's tracked
+     * base when undefined: `origin/HEAD` for git, `trunk()` for jj/sl).
+     * Returns the resolved ref + replayed commits + conflicts list.
+     *
+     * Backend-specific behaviour:
+     *   - git: refuses on dirty WC (WorkspaceDirtyError); fetches first;
+     *     `git rebase <ref>`. On conflict, aborts the rebase and throws
+     *     WorkspaceConflictError so the operator resolves manually.
+     *   - jj:  always-snapshotted, so dirty is never an issue. After
+     *     `jj rebase -d <ref>` the conflict-set is queried via
+     *     `jj log -r 'conflict()'`. Conflicts surface as
+     *     WorkspaceConflictError without an abort (jj's conflict markers
+     *     persist as commits; the operator resolves in-place).
+     *   - sl:  similar to jj. `sl rebase -d <ref>`; conflicts via
+     *     `sl resolve -l`. On dirty WC sl errors itself; we wrap that
+     *     into WorkspaceDirtyError.
+     *   - none: throws WorkspaceVcsRequiredError unconditionally.
+     *
+     * Surfaced by fb_workspace_recycle_verb: dogfood between waves
+     * needed `close → free → spawn` to refresh a worker against new
+     * main; that killed the worker's LLM context. `refresh` updates
+     * the on-disk dir without touching the agent or pane.
+     */
+    rebaseTo(workspacePath: string, fromRef?: string): Promise<RebaseResult>;
+    /**
+     * List commits the workspace has on top of `baseRef`, oldest-first.
+     * Used by `mu workspace commits` (fb_workspace_commits_verb) to
+     * promote the dogfood-painful
+     *     cd $(mu workspace path X) && git log <base>..HEAD
+     * incantation into a typed verb that knows the workspace's
+     * parent_ref. The CommitSummary fields survive subjects/bodies with
+     * embedded newlines (NUL-delimited record format on the wire).
+     *
+     * `none` throws WorkspaceVcsRequiredError. Returns `[]` when the
+     * workspace is exactly at baseRef (no commits since fork). Throws
+     * on backend command failure (unknown ref, missing repo).
+     */
+    commitsSinceBase(workspacePath: string, baseRef: string): Promise<CommitSummary[]>;
+}
+declare const noneBackend: VcsBackend;
+declare const gitBackend: VcsBackend;
+declare const jjBackend: VcsBackend;
+declare const slBackend: VcsBackend;
+/** Return the backend that should handle projectRoot. Walks BACKENDS
+ *  in precedence order; never returns undefined because noneBackend
+ *  always claims. */
+declare function detectBackend(projectRoot: string): Promise<VcsBackend>;
+/** Look up a backend by name. Throws on unknown name. Used by
+ *  `mu workspace create --backend ...` to honour an explicit override. */
+declare function backendByName(name: VcsBackendName): VcsBackend;
+
+/**
+ * Resolve the actual executable to launch in an agent's pane for a given
+ * `cli`. Honours the env var `MU_<UPPER_CLI>_COMMAND` (e.g. `MU_PI_COMMAND=
+ * pi-alt` makes `--cli pi` actually exec `pi-alt`). Falls back to the cli
+ * name itself, which is what users expect when their `pi` binary is on
+ * `$PATH` under that exact name.
+ *
+ * Used by `spawnAgent` to pick the spawned command, and by reconcile's
+ * orphan detector so externally-spawned panes running the resolved binary
+ * are still recognised as agents.
+ */
+declare function resolveCliCommand(cli: string): string;
+interface SpawnAgentOptions {
+    name: string;
+    workstream: string;
+    /** Defaults to "pi". 0.1.0 only really supports "pi" but the column
+     *  accepts any string for forward-compat with future multi-CLI support
+     *  (claude/codex). */
+    cli?: string;
+    /** The actual command to run in the pane. Defaults to the cli value. */
+    command?: string;
+    /** Window name to group this agent under. Defaults to the agent's name
+     *  (so each agent gets its own window). Multiple agents sharing a `tab`
+     *  share a window with multiple panes. */
+    tab?: string;
+    /** "full-access" (default) or "read-only". The schema stores it; today
+     *  the role isn't enforced (deferred to a future capabilities pass). */
+    role?: string;
+    /** Initial working directory for the spawned pane (`tmux -c <path>`).
+     *  When `workspace: true` is passed, this is ignored — the workspace
+     *  path is used instead. */
+    cwd?: string;
+    /** Override the tmux session name. Defaults to `mu-<workstream>`. */
+    tmuxSession?: string;
+    /** Auto-create a VCS workspace for this agent before spawning the
+     *  pane and use the workspace path as cwd. Backend defaults to
+     *  detection (jj > sl > git > none). */
+    workspace?: boolean;
+    /** Force a specific VCS backend (only meaningful with `workspace: true`). */
+    workspaceBackend?: VcsBackendName;
+    /** Optional ref to base the workspace on (only meaningful with
+     *  `workspace: true`). Backend-specific. */
+    workspaceFrom?: string;
+    /** Project root the workspace branches from (only meaningful with
+     *  `workspace: true`). Defaults to `process.cwd()`. */
+    workspaceProjectRoot?: string;
+}
+/**
+ * Spawn a new agent in its tmux pane and register it in the DB.
+ *
+ * Phases:
+ *   1. Validate name + uniqueness.
+ *   2. If --workspace: prestageWorkspace() (placeholder agent row +
+ *      workspace dir + workspace row).
+ *   3. createOrReusePane() in the workspace path (or opts.cwd).
+ *   4. setPaneTitle + enableMuPaneBordersForPane.
+ *   5. finalizeAgentRow() — patch placeholder pane_id to real (workspace
+ *      path), or insert a fresh agent row (no-workspace path).
+ *   6. awaitSpawnLiveness().
+ *
+ * Failure between any of (3)–(6) calls rollbackSpawn() to undo the
+ * pane + row + workspace. The caller-visible error is preserved.
+ */
+declare function spawnAgent(db: Db, opts: SpawnAgentOptions): Promise<AgentRow>;
+/**
+ * Default liveness window in milliseconds. 0 disables the check (useful
+ * for fast tests that don't want to wait). Override via env var
+ * `MU_SPAWN_LIVENESS_MS`.
+ */
+declare function defaultSpawnLivenessMs(): number;
+
+interface AdoptAgentOptions {
+    /** tmux pane id (e.g. '%15'). Must already exist on the tmux server. */
+    paneId: string;
+    /** Workstream to adopt the pane into. The pane MUST be in the
+     *  matching tmux session (`mu-<workstream>`); cross-session adopt is
+     *  rejected. */
+    workstream: string;
+    /** Override the pane's title with this name. When omitted, the pane's
+     *  current title becomes the agent name (zero-config adoption). */
+    name?: string;
+    /** Defaults to 'pi' via the schema DEFAULT. */
+    cli?: string;
+    /** 'full-access' (default) or 'read-only'. */
+    role?: string;
+    /** Override the tmux session lookup. Defaults to `mu-<workstream>`. */
+    tmuxSession?: string;
+}
+interface AdoptAgentResult {
+    agent: AgentRow;
+    /** True when the pane already had a matching agents row — the call
+     *  was a no-op (idempotent). */
+    alreadyAdopted: boolean;
+    /** The pane title before adopt, or null if the pane had no title. */
+    previousTitle: string | null;
+    /** The title the pane was set to (== agent.name post-adopt). Equal to
+     *  previousTitle when no retitle happened. */
+    paneTitleSetTo: string;
+}
+/**
+ * Register an existing tmux pane as a managed mu agent. Inverse of the
+ * 'orphan' state surfaced by `mu agent list`: a pane that looks like an
+ * agent (running pi/claude/codex) but has no DB row.
+ *
+ * Identity contract (matches the claim protocol invariant):
+ *   - Post-adopt, the pane's title equals the agent's name.
+ *   - When `name` is omitted, the pane's existing title becomes the
+ *     agent name verbatim. Adopting a pane titled 'pi' would fail name
+ *     validation — caller must supply --name in that case.
+ *
+ * Idempotent: adopting the same pane twice with the same name is a
+ * no-op (returns alreadyAdopted=true). Adopting a different pane under
+ * an existing agent name throws AgentExistsError.
+ *
+ * Validation order (matches the design in note #100):
+ *   1. Pane id format     -> assertValidPaneId via paneExists / setPaneTitle
+ *   2. Pane exists        -> PaneNotFoundError
+ *   3. Pane is in session -> AgentNotInWorkstreamError (cross-session)
+ *   4. Resolved name OK   -> isValidAgentName / Error('agent name invalid')
+ *   5. Idempotent check   -> if pane already owned by an agent of this
+ *                            name, return alreadyAdopted=true
+ *   6. Name not taken     -> AgentExistsError (else)
+ *   7. Insert + retitle.
+ *
+ * Status starts at 'free' — reconcile/detect will update it on the next
+ * `mu agent list` based on actual pane content (the pi prompt yields
+ * 'free'; an agent mid-thought yields 'busy'; etc.). We don't run
+ * detection inline here because the caller may not have $TMUX, and
+ * adoption shouldn't depend on a captured-pane probe succeeding.
+ */
+declare function adoptAgent(db: Db, opts: AdoptAgentOptions): Promise<AdoptAgentResult>;
+
+interface AgentRow {
+    name: string;
+    /** Foreign-name reference to the owning workstream. */
+    workstreamName: string;
+    cli: string;
+    paneId: string;
+    status: AgentStatus;
+    role: string;
+    /** Window name; null when the agent has its own window named after itself. */
+    tab: string | null;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp. */
+    updatedAt: string;
+    /**
+     * Derived 'idle but assigned' flag (idle_assigned_agent_detection).
+     * Set ONLY by `listLiveAgents` (and the helper `computeAgentIdle`);
+     * never stored in the DB. Predicate:
+     *   status === 'needs_input'
+     *   AND owns ≥1 IN_PROGRESS task in this workstream
+     *   AND (now - updated_at) >= MU_IDLE_THRESHOLD_MS (default 300_000ms)
+     *
+     * Surfaces the third lifecycle state (alive but assigned, no recent
+     * progress) to `mu state` renders + `mu state --json`. Omitted (i.e.
+     * absent — NOT `false`) when the predicate doesn't fire, so JSON
+     * consumers can do a simple `if (agent.idle)` check and the field
+     * stays out of the way for callers that don't care.
+     */
+    idle?: boolean;
+}
+interface InsertAgentInput {
+    name: string;
+    workstream: string;
+    paneId: string;
+    status: AgentStatus;
+    /** Defaults to "pi" via schema DEFAULT. */
+    cli?: string;
+    /** Defaults to "full-access" via schema DEFAULT. */
+    role?: string;
+    tab?: string | null;
+}
+declare function insertAgent(db: Db, input: InsertAgentInput): AgentRow;
+/**
+ * Look up an agent by its tmux pane id (e.g. `%4`). Returns undefined if
+ * no agent currently owns that pane. Used by `mu me` and friends to
+ * answer "which agent am I?" from `$TMUX_PANE` without the LLM having to
+ * remember its own name.
+ *
+ * Note: `pane_id` is not declared UNIQUE in the schema (a managed agent
+ * could in theory be re-spawned into the same recycled pane id) but in
+ * practice tmux pane ids are unique within a server's lifetime, and
+ * reconcile prunes ghosts. We return the first match.
+ */
+declare function getAgentByPane(db: Db, paneId: string): AgentRow | undefined;
+declare function getAgent(db: Db, name: string, workstream: string): AgentRow | undefined;
+declare function listAgents(db: Db, opts?: {
+    workstream?: string;
+}): AgentRow[];
+/**
+ * Update an agent's status. Returns true if a row was matched.
+ * Also bumps updated_at. Workstream is required (v5: agents.name is
+ * per-workstream unique).
+ */
+declare function updateAgentStatus(db: Db, name: string, status: AgentStatus, workstream: string): boolean;
+/** Plain-text emoji map for the agent status. Mirrors statusIcon in
+ *  cli.ts but without picocolors (tmux pane titles don't render ANSI
+ *  colour). 'spawning' is omitted on purpose — the title gets the
+ *  initial render before status detection runs, and 'spawning' is a
+ *  transient state. */
+declare const STATUS_EMOJI: Record<AgentStatus, string>;
+/** Build the pane title for `agent` based on current DB state.
+ *  Pure (no tmux side effect; no DB write). Read-only on the DB. */
+declare function composeAgentTitle(db: Db, agent: AgentRow): string;
+/** Push a fresh pane title for `agentName`. Best-effort — a missing
+ *  agent, a placeholder pane id, or a tmux failure are all swallowed
+ *  silently (titles are decorative; never block the calling verb). */
+declare function refreshAgentTitle(db: Db, agentName: string, workstream: string): Promise<void>;
+/**
+ * Delete an agent row. Returns true if a row was matched. Idempotent;
+ * deleting an agent that doesn't exist returns false without throwing.
+ *
+ * Reaper side-effect: any task that was IN_PROGRESS owned by this
+ * agent gets flipped back to OPEN with a `[reaper]` task_note and a
+ * `task reap` event in `agent_logs`. The FK on `tasks.owner` is
+ * `ON DELETE SET NULL` so the owner column resets automatically; the
+ * extra step here is the status revert. Without this an agent that
+ * crashed (or was explicitly closed mid-task) leaves the task graph
+ * in a wrong state — IN_PROGRESS forever, with no owner to release.
+ */
+declare function deleteAgent(db: Db, name: string, workstream: string): boolean;
+declare function isValidAgentName(name: string): boolean;
+/**
+ * Send a single line of text to an agent's pane and submit it. Uses the
+ * canonical bracketed-paste protocol from src/tmux.ts.
+ */
+declare function sendToAgent(db: Db, name: string, text: string, opts: SendOptions & {
+    workstream: string;
+}): Promise<void>;
+/**
+ * Read scrollback from an agent's pane. With no options, returns the full
+ * scrollback (`-S - -E -`); with `lines: N`, returns only the last N lines.
+ */
+declare function readAgent(db: Db, name: string, opts: CaptureOptions & {
+    workstream: string;
+}): Promise<string>;
+interface FreeAgentResult {
+    /** Status before the call. */
+    previousStatus: AgentStatus;
+    /** Status after the call (always 'free' on success). */
+    status: AgentStatus;
+    /** True iff the row actually changed. False on idempotent no-op. */
+    changed: boolean;
+}
+/**
+ * Mark an agent's status as `free` — the explicit "I'm done with you
+ * for now; you're available" signal. The agent's pane and DB row are
+ * untouched; reconcile treats `free` as sticky (only flips back to busy
+ * on real activity, never on an idle prompt) so this verb composes
+ * cleanly with the existing scrollback detector.
+ *
+ * Idempotent: setting an already-free agent to free is a no-op (returns
+ * `changed: false`). Throws AgentNotFoundError on missing.
+ */
+declare function freeAgent(db: Db, name: string, workstream: string): FreeAgentResult;
+interface CloseAgentOptions {
+    /**
+     * When true, free the agent's workspace BEFORE deleting the agent
+     * (so we control the order rather than relying on FK cascade, which
+     * leaves the on-disk dir orphaned). Lossy: any pending changes in
+     * the workspace are gone unless the caller frees with `--commit`
+     * separately first.
+     *
+     * When false (default) and a workspace exists, throws
+     * WorkspacePreservedError so the caller has to decide explicitly.
+     * Surfaced as a real bug in the multi-agent dogfood teardown.
+     */
+    discardWorkspace?: boolean;
+}
+interface CloseAgentResult {
+    killedPane: boolean;
+    deletedRow: boolean;
+    /** True iff the agent had an associated workspace AND the caller
+     *  passed `discardWorkspace: true` so we proactively freed it.
+     *  False on the no-workspace path (nothing to free) and on the
+     *  refused path (we threw before doing anything). */
+    workspaceFreed: boolean;
+}
+/**
+ * Close an agent: kill its tmux pane and remove its DB row. Idempotent:
+ *   - if the agent doesn't exist in the DB, returns a no-op result
+ *   - if the tmux pane is already gone, killPane swallows the error
+ *
+ * Workspace handling: closing an agent and freeing its workspace are
+ * separate concerns (agent lifecycle vs disk artifacts), so by default
+ * `closeAgent` REFUSES if the agent has a workspace — you'd otherwise
+ * orphan the on-disk dir (the FK cascade drops the registry row but
+ * not the directory). Two ways to proceed:
+ *
+ *   1. `freeWorkspace(db, name)` first, then `closeAgent(db, name)`.
+ *      Preserves the option to `--commit` pending changes.
+ *   2. `closeAgent(db, name, { discardWorkspace: true })`. One-shot;
+ *      lossy.
+ *
+ * The CLI surfaces these as the two actionable nextSteps on the
+ * `WorkspacePreservedError` thrown by the refuse path.
+ */
+declare function closeAgent(db: Db, name: string, opts: CloseAgentOptions & {
+    workstream: string;
+}): Promise<CloseAgentResult>;
+interface ListLiveAgentsOptions {
+    workstream: string;
+    tmuxSession?: string;
+    /**
+     * Which kind of reconciliation pass to run. Forwarded to
+     * `reconcile()`'s same-name option. Default `"full"` (the
+     * documented mutating behaviour `mu agent list` has always had).
+     *
+     * Read-only callers split two ways:
+     *   - `mu hud`, `mu state`, bare `mu`, `mu agent attach` →
+     *     `"status-only"`: refresh status + title (writes to DB),
+     *     skip prune + reap. The operator's primary signal
+     *     (busy/needs_input) stays fresh without a periodic poll
+     *     racing in-flight spawns.
+     *   - `mu doctor`, `mu undo` → `"report-only"`: count drift,
+     *     mutate nothing. `mu undo` MUST use this so a post-restore
+     *     reconcile doesn't delete the rows the snapshot just
+     *     restored (snap_undo_reconcile_destroys_recovered_agents).
+     *
+     * Skipping prune is what protects mid-spawn placeholders (pane
+     * id `%pending-<name>`) from being treated as ghosts and pruned
+     * out from under `createWorkspace`'s FK insert
+     * (bug_agent_spawn_workspace_fk_failure).
+     *
+     * BREAKING: this replaces the previous `dryRun?: boolean`
+     * option. Migration: `dryRun: true` → `mode: "report-only"`;
+     * default (`dryRun: false` / unset) → `mode: "full"`.
+     */
+    mode?: ReconcileMode;
+}
+interface LiveAgentsView {
+    /** All registered agents in the workstream, post-reconcile. */
+    agents: AgentRow[];
+    /** Panes in the tmux session that look like agents but aren't registered. */
+    orphans: TmuxPane[];
+    /** Diagnostic numbers from the reconcile pass; useful for `mu doctor`. */
+    report: ReconcileReport;
+}
+/**
+ * Return the live, reality-reconciled view of agents in a workstream.
+ * `mu agent list` calls this with `mode: "full"` (mutating); status
+ * pollers (`mu hud`, `mu state`, bare `mu`, `mu agent attach`) call
+ * it with `mode: "status-only"` to refresh status without pruning;
+ * read-only diagnostic / restore paths (`mu doctor`, `mu undo`)
+ * call it with `mode: "report-only"` to mutate nothing at all.
+ */
+declare function listLiveAgents(db: Db, opts: ListLiveAgentsOptions): Promise<LiveAgentsView>;
+
+/** True iff `label` matches the archive-label rule. Pure predicate. */
+declare function isValidArchiveLabel(label: string): boolean;
+declare class ArchiveNotFoundError extends Error implements HasNextSteps {
+    readonly label: string;
+    readonly name = "ArchiveNotFoundError";
+    constructor(label: string);
+    errorNextSteps(): NextStep[];
+}
+declare class ArchiveAlreadyExistsError extends Error implements HasNextSteps {
+    readonly label: string;
+    readonly name = "ArchiveAlreadyExistsError";
+    constructor(label: string);
+    errorNextSteps(): NextStep[];
+}
+declare class ArchiveLabelInvalidError extends Error implements HasNextSteps {
+    readonly attempted: string;
+    readonly name = "ArchiveLabelInvalidError";
+    constructor(attempted: string);
+    errorNextSteps(): NextStep[];
+}
+interface Archive {
+    /** Surrogate INTEGER id. Internal — operators identify by label. */
+    id: number;
+    /** Globally-unique operator-facing TEXT label. */
+    label: string;
+    /** Optional one-liner description set at create time. */
+    description: string | null;
+    /** ISO 8601, set when the archive was first created. */
+    createdAt: string;
+    /** ISO 8601, bumped on every successful add. */
+    lastAddedAt: string;
+}
+interface ArchiveSourceSummary {
+    /** TEXT name of the source workstream this snapshot came from. */
+    name: string;
+    /** Number of archived_tasks rows from this workstream in this archive. */
+    taskCount: number;
+    /** Earliest archived_at among this workstream's rows in this archive. */
+    addedAt: string;
+}
+interface ArchiveSummary extends Archive {
+    /** One row per source workstream that contributed to this archive,
+     *  sorted by source workstream name. */
+    sourceWorkstreams: ArchiveSourceSummary[];
+    /** Total archived_tasks rows across every source workstream. */
+    totalTasks: number;
+}
+interface ArchivedTaskRow {
+    /** Surrogate id of the archived_tasks row. */
+    id: number;
+    /** Operator-facing label of the parent archive. */
+    archiveLabel: string;
+    /** TEXT name of the source workstream (intentionally not an FK). */
+    sourceWorkstream: string;
+    /** The local_id the task had in its source workstream. */
+    originalLocalId: string;
+    title: string;
+    /** Status as stored at archive time. */
+    status: string;
+    impact: number;
+    effortDays: number;
+    /** Owner agent name as snapshotted at archive time. */
+    ownerName: string | null;
+    /** Status at the moment of archive (pinned for re-add semantics). */
+    archivedAtStatus: string;
+    /** ISO 8601, when this row was added to the archive. */
+    archivedAt: string;
+    /** Original tasks.created_at preserved for retrospect ordering. */
+    originalCreatedAt: string;
+    /** Original tasks.updated_at preserved for retrospect ordering. */
+    originalUpdatedAt: string;
+}
+interface AddToArchiveResult {
+    /** Number of new archived_tasks rows actually inserted. Zero on a
+     *  re-run against the same workstream (idempotency). */
+    addedTasks: number;
+    /** Tasks present in the source workstream that were already in the
+     *  archive (skipped by the OR IGNORE). */
+    skippedTasks: number;
+    /** Number of new archived_edges rows actually inserted. */
+    addedEdges: number;
+    /** Number of new archived_notes rows inserted. (Notes have no
+     *  natural unique key, so this matches the count of notes attached
+     *  to NEW archived_tasks rows; existing rows' notes are not
+     *  duplicated because note copy is gated on at-least-one new task
+     *  for the (archive, source_workstream) pair.) */
+    addedNotes: number;
+    /** Number of new archived_events rows inserted (one per kind='event'
+     *  agent_logs row in the source workstream). */
+    addedEvents: number;
+}
+interface RemoveFromArchiveResult {
+    /** Number of archived_tasks rows deleted (cascade cleans the rest). */
+    removedTasks: number;
+    /** Number of archived_edges rows removed by the cascade. */
+    removedEdges: number;
+    /** Number of archived_notes rows removed by the cascade. */
+    removedNotes: number;
+    /** Number of archived_events rows directly deleted. */
+    removedEvents: number;
+}
+/**
+ * Create a new archive bucket. Throws `ArchiveAlreadyExistsError` if
+ * the label is already in use; throws `ArchiveLabelInvalidError` for
+ * malformed labels.
+ *
+ * The archive starts EMPTY: created_at and last_added_at both equal
+ * now(). Use `addToArchive(label, workstream)` to populate it.
+ */
+declare function createArchive(db: Db, label: string, description?: string): Archive;
+/**
+ * List every archive on this machine, summarised with per-source-
+ * workstream counts. Sorted by label ascending. Pure read; safe to
+ * call against an empty DB (returns []).
+ */
+declare function listArchives(db: Db): ArchiveSummary[];
+/**
+ * Look up a single archive by label. Throws `ArchiveNotFoundError`
+ * on miss.
+ */
+declare function getArchive(db: Db, label: string): ArchiveSummary;
+/**
+ * Delete an archive and every row that references it. The FK
+ * CASCADE chain (archives → archived_tasks → archived_edges /
+ * archived_notes; archives → archived_events) cleans every row in
+ * one statement.
+ *
+ * Idempotent: throws `ArchiveNotFoundError` rather than silently
+ * succeeding on a missing label (operator confusion safeguard).
+ *
+ * Mirror of `destroyWorkstream`'s safety story but cheaper: archives
+ * have no on-disk artifacts (no tmux session, no workspaces). The
+ * pre-delete snapshot is the operator's recovery path if they run
+ * this verb by mistake (handled in the CLI wrapper, Phase 2).
+ */
+declare function deleteArchive(db: Db, label: string): void;
+/**
+ * Add every task in `workstream` to the archive identified by `label`.
+ *
+ * Idempotency invariant: re-running with the same (label, workstream)
+ * pair is a no-op for tasks already present. The
+ * (archive_id, source_workstream, original_local_id) UNIQUE on
+ * archived_tasks is the lever; we INSERT OR IGNORE and skip notes /
+ * events for the (archive, source_workstream) pair entirely when the
+ * task copy added zero new rows. This makes addToArchive
+ * coarse-grained idempotent: the only way to get duplicate notes is
+ * to add a NEW task to the source workstream and re-run, which
+ * legitimately copies the new task's notes.
+ *
+ * Throws:
+ *   - `ArchiveNotFoundError` if the label doesn't exist (call
+ *     `createArchive` first).
+ *   - `WorkstreamNotFoundError` if the source workstream is gone
+ *     (you must archive BEFORE destroy).
+ *
+ * The whole operation runs in a transaction so a partial failure
+ * leaves the archive untouched.
+ */
+declare function addToArchive(db: Db, label: string, workstream: string): AddToArchiveResult;
+/**
+ * Remove every row contributed by `sourceWorkstream` from the named
+ * archive. Other source workstreams' contributions are untouched
+ * (additive accumulation invariant). Throws `ArchiveNotFoundError`
+ * if the label doesn't exist; returns all-zero counts (no error)
+ * when the source workstream never contributed to this archive.
+ */
+declare function removeFromArchive(db: Db, label: string, sourceWorkstream: string): RemoveFromArchiveResult;
+interface ListArchivedTasksOptions {
+    /** Filter by source workstream. Omit to return every source's
+     *  contribution, sorted by (source_workstream, original_local_id). */
+    sourceWorkstream?: string;
+}
+/**
+ * List archived task rows in a single archive. Throws
+ * `ArchiveNotFoundError` on missing label.
+ *
+ * Default order: source_workstream ASC, then original_local_id ASC,
+ * so the output is deterministic and groups each workstream's
+ * contribution together.
+ */
+interface ArchiveSearchHit {
+    /** Operator-facing label of the parent archive. */
+    archiveLabel: string;
+    /** TEXT name of the source workstream this row came from. */
+    sourceWorkstream: string;
+    /** local_id the task had in its source workstream. */
+    originalLocalId: string;
+    /** Snapshotted title (always present, even on a note match). */
+    title: string;
+    /** Where the match was found: the title column, or one of this
+     *  task's archived_notes.content rows. Title matches win when
+     *  both apply (the dedup pass below picks one row per task). */
+    matchKind: "title" | "note";
+    /** Up to ~120 chars of context centered on the FIRST occurrence
+     *  of the pattern in the matching field. Case-insensitive index;
+     *  the snippet itself preserves original casing. */
+    matchSnippet: string;
+}
+interface SearchArchivesOptions {
+    /** LIKE-style needle. Wrapped in `%…%` automatically; `_` and `%`
+     *  inside the pattern are still SQL LIKE wildcards (matches the
+     *  `searchTasks` convention in src/tasks.ts). Empty / whitespace-
+     *  only patterns throw — the CLI is the canonical caller and
+     *  enforces it via UsageError before we get here, but the SDK
+     *  guards it too so direct programmatic callers don't accidentally
+     *  match every row. */
+    pattern: string;
+    /** Restrict to one archive label; undefined = search every
+     *  archive. Throws ArchiveNotFoundError on miss. */
+    label?: string;
+    /** Cap on hits returned. Default 50; values below 1 fall back to
+     *  the default. There is no `--all` escape hatch — for unbounded
+     *  exports use `mu sql`. */
+    limit?: number;
+}
+/**
+ * LIKE-search archived task titles AND archived note content. The
+ * pattern is bound as a SQL parameter (never concatenated): an
+ * archive label like `'); DROP TABLE archives; --` round-trips
+ * through `?` without touching the DDL surface.
+ *
+ * Behaviour:
+ *   - One row per (archive, source_workstream, original_local_id)
+ *     pair. When a task matches via BOTH title and note, the title
+ *     row wins (matchKind='title'); only note matches stand on
+ *     their own as matchKind='note'.
+ *   - With `opts.label`, restricts to that archive. Resolves the
+ *     label up-front via the helper; throws ArchiveNotFoundError
+ *     on miss.
+ *   - Results sorted by (archive label, source workstream,
+ *     original_local_id) — the same order `mu archive show` uses,
+ *     so a search hit lines up with the show output.
+ *   - `limit` defaults to 50 and caps the result set. There is no
+ *     unbounded mode (use `mu sql` for raw extracts).
+ */
+declare function searchArchives(db: Db, opts: SearchArchivesOptions): ArchiveSearchHit[];
+declare function listArchivedTasks(db: Db, label: string, opts?: ListArchivedTasksOptions): ArchivedTaskRow[];
+
+type TaskStatus = "OPEN" | "IN_PROGRESS" | "CLOSED" | "REJECTED" | "DEFERRED";
+/** Every legal task status, in canonical order (matches the schema
+ *  CHECK clause). Exported so CLI surfaces (`--status` validators,
+ *  --help text, error messages) name them all in one place; missing
+ *  one used to silently lie about the supported set. */
+declare const TASK_STATUSES: readonly TaskStatus[];
+/** Statuses that count as 'no longer scheduled work' — used by the
+ *  goals view and by the dependent-check on reject/defer.
+ *
+ *  (The complement — 'statuses that satisfy a blocked-by edge' — is
+ *  just `["CLOSED"]` and is hardcoded inline in the SQL views in
+ *  src/db.ts. A constant for it was tried and reverted: a one-element
+ *  array doesn't earn its keep, and parameterising the SQL views from
+ *  a TS const would be brittle.) */
+declare const STATUSES_TERMINAL_OR_PARKED: readonly TaskStatus[];
+declare function isTaskStatus(s: string): s is TaskStatus;
+/** Pipe-separated list of every legal status, e.g.
+ *  'OPEN | IN_PROGRESS | CLOSED | REJECTED | DEFERRED'. Single source
+ *  of truth for --help text and error messages so adding a new status
+ *  doesn't leave stale lists rotting in the CLI surface. */
+declare const TASK_STATUS_LIST: string;
+
+declare class TaskNotFoundError extends Error implements HasNextSteps {
+    readonly taskId: string;
+    readonly name = "TaskNotFoundError";
+    constructor(taskId: string);
+    errorNextSteps(): NextStep[];
+}
+declare class TaskExistsError extends Error implements HasNextSteps {
+    readonly taskId: string;
+    readonly name = "TaskExistsError";
+    constructor(taskId: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown when a verb is invoked with `-w/--workstream <name>` but the
+ * named task lives in a different workstream. Distinguishes "the user
+ * typo'd the workstream" from "the task doesn't exist anywhere"
+ * (which surfaces as `TaskNotFoundError`). Maps to exit code 4
+ * (conflict / wrong scope).
+ */
+declare class TaskNotInWorkstreamError extends Error implements HasNextSteps {
+    readonly taskId: string;
+    readonly expectedWorkstream: string;
+    readonly actualWorkstream: string;
+    readonly name = "TaskNotInWorkstreamError";
+    constructor(taskId: string, expectedWorkstream: string, actualWorkstream: string);
+    errorNextSteps(): NextStep[];
+}
+declare class TaskAlreadyOwnedError extends Error implements HasNextSteps {
+    readonly taskId: string;
+    readonly currentOwner: string;
+    readonly name = "TaskAlreadyOwnedError";
+    constructor(taskId: string, currentOwner: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown by `rejectTask` / `deferTask` when the target task has
+ * dependents that are still OPEN or IN_PROGRESS. Rejecting or
+ * deferring such a task would silently strand the dependents (they'd
+ * remain blocked by a prereq that's never going to satisfy the edge),
+ * so we refuse and force an explicit decision: pass `--cascade` to
+ * apply the same status to every transitive dependent, drop the
+ * blocking edge first with `mu task unblock`, or address the
+ * dependents individually. Maps to exit code 4.
+ */
+declare class TaskHasOpenDependentsError extends Error implements HasNextSteps {
+    readonly taskId: string;
+    readonly verb: "reject" | "defer";
+    readonly dependents: readonly string[];
+    readonly name = "TaskHasOpenDependentsError";
+    constructor(taskId: string, verb: "reject" | "defer", dependents: readonly string[]);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown when `mu task claim` resolves a claimer agent name (from the
+ * pane title or --for) that has no matching row in the agents table.
+ *
+ * The FK on `tasks.owner` references `agents.name`; without this guard
+ * the claim attempt would fail with the unhelpful 'FOREIGN KEY constraint
+ * failed' from SQLite. This typed error gives the user actionable next
+ * steps (run `mu adopt <pane-id>` to register, or use --for to pick a
+ * different agent).
+ *
+ * Maps to exit code 4 (conflict) via the cli.ts handler.
+ */
+declare class ClaimerNotRegisteredError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly paneId: string | null;
+    readonly name = "ClaimerNotRegisteredError";
+    constructor(agentName: string, paneId: string | null);
+    /**
+     * Three actionable resolutions in expected-frequency order:
+     *   1. --self  : orchestrator pattern (working directly)
+     *   2. --for   : dispatcher pattern (assigning to a worker)
+     *   3. mu adopt: registration pattern (promote pane to worker)
+     */
+    errorNextSteps(): NextStep[];
+}
+declare class CycleError extends Error implements HasNextSteps {
+    readonly from: string;
+    readonly to: string;
+    readonly name = "CycleError";
+    constructor(from: string, to: string);
+    errorNextSteps(): NextStep[];
+}
+declare class CrossWorkstreamEdgeError extends Error implements HasNextSteps {
+    readonly blocker: string;
+    readonly blockerWorkstream: string;
+    readonly dependent: string;
+    readonly dependentWorkstream: string;
+    readonly name = "CrossWorkstreamEdgeError";
+    constructor(blocker: string, blockerWorkstream: string, dependent: string, dependentWorkstream: string);
+    errorNextSteps(): NextStep[];
+}
+
+declare function setWaitSleepForTests(impl: ((ms: number) => Promise<void>) | undefined): (ms: number) => Promise<void>;
+/** Test seam: swap the stderr writer used by the stuck-task warning so
+ *  unit tests can capture warnings without spying on process.stderr. */
+declare function setWaitStuckWarnForTests(impl: ((msg: string) => void) | undefined): (msg: string) => void;
+/** Total number of polls performed across all `waitForTasks` calls in this
+ *  process. Tests typically reset before exercising and read after. */
+declare function getWaitPollCount(): number;
+declare function resetWaitPollCount(): void;
+/** A single task ref the wait verb is watching. Cross-workstream
+ *  waits arrive as a heterogeneous list of (workstream, name) pairs;
+ *  the legacy single-workstream call passes the same workstream on
+ *  every ref. task_wait_cross_workstream. */
+interface TaskWaitRef {
+    /** The workstream the task lives in. Each ref carries its own so
+     *  the SDK doesn't need a single "the workstream" — cross-ws waits
+     *  pass refs from multiple workstreams in one call. */
+    workstreamName: string;
+    /** The task's per-workstream-unique local id. */
+    name: string;
+}
+interface TaskWaitOptions {
+    /** Target status. Default 'CLOSED'. */
+    status?: TaskStatus;
+    /** When true, succeed as soon as ONE listed task reaches the target.
+     *  Default false: every listed task must reach the target. */
+    any?: boolean;
+    /** Maximum time to wait, in milliseconds. Default 600_000 (10 min).
+     *  Pass 0 to wait forever. */
+    timeoutMs?: number;
+    /** Polling interval. Default 1000ms; overridable for tests. */
+    pollMs?: number;
+    /** Workstream context applied to bare-string ids. Required when the
+     *  caller passes `string[]`; ignored when the caller passes
+     *  `TaskWaitRef[]` (each ref carries its own ws). The legacy
+     *  single-ws SDK call site keeps its today's shape; the cross-ws
+     *  callers (CLI verb) pass `TaskWaitRef[]` and omit `workstream`.
+     *  task_wait_cross_workstream. */
+    workstream?: string;
+    /** Emit a yellow STUCK warning to stderr (once per task per wait call)
+     *  when an IN_PROGRESS task's owner has been in `needs_input` for at
+     *  least this many milliseconds since the agent row's last update.
+     *  Default 300_000 (5 min). Pass 0 to disable.
+     *
+     *  Surfaced by agent_close_discipline_gap in mufeedback: workers
+     *  occasionally finish + commit + go idle without running
+     *  `mu task close <id>`, leaving wait blocked indefinitely. The
+     *  warning is observation-only — wait keeps polling so the operator
+     *  (or a wrapping policy) decides whether to force-close, re-prompt,
+     *  or escalate. */
+    stuckAfterMs?: number;
+    /** What to do when the `--stuck-after` predicate fires on a watched
+     *  task. `'warn'` (default) = today's behaviour: yellow STUCK line
+     *  to stderr (deduped per task per wait call) + corroborating
+     *  `kind='event'` agent_logs row; wait keeps polling. `'exit'` =
+     *  same emit + persist, but THEN throw `StallDetectedDuringWaitError`
+     *  so the CLI wrapper exits 7 (STALL_DETECTED). The exit-action is
+     *  the unattended-orchestrator escape: a wrapping policy can branch
+     *  on 7 (idle, ambiguous — operator decides poke vs release) vs 6
+     *  (dead pane, unambiguous — re-dispatch).
+     *
+     *  Carve-out (lives at the call site, not here): the CLI passes
+     *  `'exit'` only when the wait target is CLOSED — mirrors exit-6's
+     *  reaper-flip suppression. With `--status OPEN` the worker reaching
+     *  needs_input might BE the success path. See
+     *  task_wait_stall_action_flag. */
+    onStall?: "warn" | "exit";
+    /** Optional async hook run BEFORE every snapshot (initial + each
+     *  poll iteration). The CLI uses this to reconcile the workstream
+     *  each tick (reaper flips IN_PROGRESS → OPEN for dead-pane
+     *  workers) and to throw a typed error when a reaper-flip on a
+     *  watched task should abandon the wait — see
+     *  task_wait_reconcile_dead_panes. Throwing from `beforePoll`
+     *  propagates out of `waitForTasks` unchanged.
+     *
+     *  Kept as a generic seam (not a `--reconcile`-shaped option) so
+     *  the SDK module stays free of tmux/reconcile imports — that
+     *  layering belongs above the SDK in the CLI wrapper. */
+    beforePoll?: () => Promise<void>;
+}
+interface TaskWaitTaskState {
+    /** The workstream this task lives in. Cross-workstream waits
+     *  return a mixed list; the workstream is part of identity.
+     *  task_wait_cross_workstream. */
+    workstreamName: string;
+    /** The task's per-workstream-unique name. */
+    name: string;
+    /** Current status (at the moment we exit). */
+    status: TaskStatus;
+    /** Owner at exit time (NULL when unowned, after release, or after
+     *  the reaper flipped IN_PROGRESS → OPEN due to a dead pane). */
+    owner: string | null;
+    /** True when this task's status equals the target. */
+    reachedTarget: boolean;
+    /** True when the task is IN_PROGRESS, owned by a registered agent
+     *  whose detected status is `needs_input` for >= `stuckAfterMs`.
+     *  Surfaces the agent_close_discipline_gap pattern: worker finished +
+     *  committed but skipped `mu task close <id>`. Backwards-compatible
+     *  signal — callers ignoring it see no behaviour change. */
+    stuck: boolean;
+}
+interface TaskWaitResult {
+    /** Per-task state at exit time. Same length and order as the input list. */
+    tasks: TaskWaitTaskState[];
+    /** True when EVERY task reached the target (the --all condition). */
+    allReached: boolean;
+    /** True when AT LEAST ONE task reached the target (the --any condition). */
+    anyReached: boolean;
+    /** Wall-clock time spent waiting, in ms (always >= 0). */
+    elapsedMs: number;
+    /** True when we exited because of the timeout, not because the wait
+     *  condition was met. allReached / anyReached can still be true on
+     *  partial progress when timedOut is true. */
+    timedOut: boolean;
+}
+/**
+ * Block until a set of tasks reaches `opts.status` (default CLOSED).
+ * Returns a result describing the final state — the caller decides
+ * whether to treat partial-progress timeouts as success or failure
+ * (the CLI maps a clean exit to 0, a timeout to 5).
+ *
+ * Pre-flight: every task in `localIds` MUST exist; missing ones throw
+ * TaskNotFoundError before any waiting begins. This is loud-fail by
+ * design — a typo'd id silently waiting forever is the worst-case UX.
+ */
+declare function waitForTasks(db: Db, input: readonly TaskWaitRef[] | readonly string[], opts: TaskWaitOptions): Promise<TaskWaitResult>;
+
+interface SetStatusResult {
+    /** Status before the call. */
+    previousStatus: TaskStatus;
+    /** Status after the call (== requested status). */
+    status: TaskStatus;
+    /** True iff the row actually changed. False on idempotent no-op. */
+    changed: boolean;
+}
+/**
+ * Optional evidence string carried on lifecycle verbs (close / open /
+ * claim / release). Lands in the auto-emitted `kind='event'` payload
+ * verbatim, prefixed with `evidence=`. The first inch of distinguishing
+ * "observed" from "claimed" state per an internal critique: the
+ * verb still trusts the caller (it's not a verifier), but the audit
+ * trail records what the caller said it relied on.
+ */
+interface EvidenceOption {
+    evidence?: string;
+}
+/**
+ * Flip a task's status to any of OPEN / IN_PROGRESS / CLOSED.
+ * Idempotent: setting a task to its current status is a no-op (returns
+ * `changed: false`) rather than throwing. Owner is unchanged.
+ */
+declare function setTaskStatus(db: Db, localId: string, status: TaskStatus, opts: EvidenceOption & {
+    workstream: string;
+}): SetStatusResult;
+/** Result of `closeTask` when called with `ifReady: true` and the
+ *  task is NOT yet ready to close (still has at least one OPEN /
+ *  IN_PROGRESS blocker). Distinguished from a regular `SetStatusResult`
+ *  by the literal `skipped` field; the CLI keys on it to switch
+ *  between the "closed" and "waiting" rendering paths.
+ *
+ *  Surfaced in `fb_umbrella_no_auto_close` (impact=60): a wave umbrella
+ *  with N blockers stayed OPEN after every blocker reached a terminal
+ *  status. `--if-ready` is the cheap fix: bare `mu task close` is
+ *  unchanged (closes regardless), `--if-ready` is a no-op unless every
+ *  blocker is in a terminal status (CLOSED / REJECTED / DEFERRED).
+ *  Reject and defer satisfy the predicate too because `--if-ready`'s
+ *  job is to fire when the umbrella has nothing left to wait for, and
+ *  a rejected/deferred blocker is no longer being waited on. */
+interface CloseSkippedResult {
+    /** Always 'not_ready' when set; future cause-codes can extend this
+     *   without reshaping the JSON payload (the literal-union narrows
+     *   safely in the CLI rendering path). */
+    skipped: "not_ready";
+    /** Status before the call (always the current status, no change). */
+    previousStatus: TaskStatus;
+    /** Status after the call (== previousStatus, since we no-op). */
+    status: TaskStatus;
+    /** Always false on a skip (no row mutated). */
+    changed: false;
+    /** Local ids of every blocker still in OPEN or IN_PROGRESS, sorted
+     *   alphabetically for deterministic rendering. Empty list is
+     *   impossible on this branch — the no-op only fires when ≥1
+     *   blocker is non-terminal. */
+    blockingIds: string[];
+}
+interface CloseTaskOptions extends EvidenceOption {
+    workstream: string;
+    /** When true, no-op the close unless every blocker is in a terminal
+     *   status (CLOSED / REJECTED / DEFERRED). Returns a
+     *   `CloseSkippedResult` carrying the still-blocking ids; the CLI
+     *   renders the skip with a Next: hint pointing at `mu task wait`.
+     *   When false / omitted, behaves as bare `closeTask` (closes
+     *   regardless of blocker status). */
+    ifReady?: boolean;
+}
+/** Convenience: setTaskStatus(db, id, "CLOSED"). Accepts evidence.
+ *  Pre-snapshots the DB (snap_design §CAPTURE STRATEGY > WHEN). Skipped
+ *  for the idempotent no-op (already CLOSED) so we don't accumulate
+ *  empty-delta snapshots on retry loops.
+ *
+ *  With `ifReady: true`, returns a `CloseSkippedResult` (no mutation,
+ *  no snapshot) when any blocker is still OPEN / IN_PROGRESS. Used by
+ *  `mu task close --if-ready` so an orchestrator can fire-and-forget
+ *  the umbrella close after every blocker resolves without first
+ *  re-querying the graph. */
+declare function closeTask(db: Db, localId: string, opts: CloseTaskOptions): SetStatusResult | CloseSkippedResult;
+/** Convenience: setTaskStatus(db, id, "OPEN"). Owner intentionally NOT
+ *  cleared — use `releaseTask` for that. Accepts evidence. */
+declare function openTask(db: Db, localId: string, opts: EvidenceOption & {
+    workstream: string;
+}): SetStatusResult;
+interface RejectDeferOptions extends EvidenceOption {
+    /** Workstream context for the root task. All internal task lookups
+     *  (including the dependent walk) scope to this workstream. */
+    workstream: string;
+    /** If true, walk the transitive dependent closure and (with `yes`)
+     *  apply the same status to every dependent, atomically. Without
+     *  `yes`, runs as a dry-run: returns the list of tasks that WOULD
+     *  be swept (changedIds) with `dryRun: true` and changes nothing.
+     *  Logs one event per task (via setTaskStatus) on commit. */
+    cascade?: boolean;
+    /** Required to actually commit a `cascade` operation. Without it,
+     *  cascade is dry-run only — prints the affected dependents so the
+     *  caller can verify before sweeping. Mirrors `mu workstream destroy
+     *  --yes`. Surfaced in mufeedback bug_cascade_reject_too_aggressive
+     *  when an accidentally-cascaded reject swept hud_dogfood (which had
+     *  independent merit and needed reopening). */
+    yes?: boolean;
+}
+interface RejectDeferResult {
+    /** Tasks that actually changed status, in cascade order (root first). */
+    changedIds: string[];
+    /** The status now stamped on every changedId. */
+    status: TaskStatus;
+    /** True iff anything changed. False on a clean idempotent no-op
+     *  (root task already in target status, no dependents). */
+    changed: boolean;
+    /** True iff this was a `cascade` dry-run (cascade requested without
+     *  `yes`). In that case `changedIds` lists tasks that WOULD be
+     *  swept; the DB is unchanged. */
+    dryRun: boolean;
+    /** Tasks that would be touched by a cascade. Same as `changedIds`
+     *  on a dry-run; populated even on a commit so the caller can
+     *  report what was swept. */
+    affectedIds: string[];
+}
+/** Reject a task: terminal 'won't do' (out of scope, duplicate, wontfix).
+ *  Refuses if dependents are open unless `--cascade`.
+ *  Pre-snapshots once at the verb level so a cascade onto N children
+ *  produces a single snapshot, not N. Skipped for the idempotent no-op. */
+declare function rejectTask(db: Db, localId: string, opts: RejectDeferOptions): RejectDeferResult;
+/** Defer a task: parked, may revisit. Same dependent-stranding semantics
+ *  as reject (DEFERRED also doesn't satisfy a `--blocked-by` edge).
+ *  Pre-snapshots once at the verb level. Skipped for the idempotent no-op. */
+declare function deferTask(db: Db, localId: string, opts: RejectDeferOptions): RejectDeferResult;
+
+interface ReleaseResult {
+    /** The previous owner (null if the task was already unowned). */
+    previousOwnerName: string | null;
+    /** Status before the release. */
+    previousStatus: TaskStatus;
+    /** Status after the release. */
+    status: TaskStatus;
+    /** True iff owner OR status actually changed. */
+    changed: boolean;
+}
+interface ReleaseTaskOptions extends EvidenceOption {
+    /** Workstream context for the task (v5: tasks.local_id is
+     *  per-workstream unique). */
+    workstream: string;
+    /** Force `status = OPEN` regardless of the current status. Without
+     *  this flag, `IN_PROGRESS` is also flipped to `OPEN` automatically
+     *  (so a released task isn't left structurally stranded with
+     *  `owner=NULL, status=IN_PROGRESS`); CLOSED / REJECTED / DEFERRED
+     *  are preserved. `--reopen` is the override for the rarer "un-
+     *  close and hand back to the pool" workflow. */
+    reopen?: boolean;
+}
+/**
+ * Release a task: clear `tasks.owner`.
+ *
+ * Status side-effects (review_release_open_in_progress_inconsistency):
+ *   - IN_PROGRESS → OPEN automatically (without it, the task is
+ *     stranded: no owner to drive it forward, but `mu task next`
+ *     skips it because it's not OPEN).
+ *   - OPEN / CLOSED / REJECTED / DEFERRED preserved.
+ *   - `--reopen` forces OPEN regardless of current status — the
+ *     escape hatch for un-closing a CLOSED owned task in one verb.
+ *
+ * Idempotent: releasing an already-unowned task with no `--reopen` and
+ * no IN_PROGRESS status is a no-op (returns `changed: false`).
+ * Throws TaskNotFoundError on missing.
+ */
+declare function releaseTask(db: Db, localId: string, opts: ReleaseTaskOptions): ReleaseResult;
+interface ClaimTaskOptions extends EvidenceOption {
+    /** Workstream context for both the task and the claiming agent.
+     *  v5: agents.name and tasks.local_id are per-workstream unique;
+     *  the task lookup AND the agent FK lookup scope to this
+     *  workstream so a same-named task or worker elsewhere can't be
+     *  silently picked. The CLI always passes this from the resolved
+     *  -w / $MU_SESSION. */
+    workstream: string;
+    /**
+     * Override the agent name. If omitted, derived from the current pane's
+     * title via `tmux display-message -t $TMUX_PANE -p '#{pane_title}'`.
+     *
+     * Mutually exclusive with `self: true`.
+     */
+    agentName?: string;
+    /**
+     * Workstream that the claimer agent lives in. When omitted, defaults
+     * to `opts.workstream` (today's same-workstream behaviour). Set by
+     * the CLI when `mu task claim X -w A --for B/worker-1` qualifies the
+     * `--for` ref with a different workstream prefix
+     * (`task_claim_for_cross_workstream`).
+     *
+     * Cross-workstream ownership is structurally allowed by the schema:
+     * `tasks.owner_id` is an INTEGER FK to `agents.id` with no
+     * workstream qualifier on the agent side. The per-workstream UNIQUE
+     * on `agents(workstream_id, name)` is what previously made the
+     * SDK's name → id lookup scope to one workstream; this option
+     * widens that lookup to a different workstream when the operator
+     * dispatches across a workstream boundary. The agent's own
+     * workstream remains unchanged — only the task's `owner_id` points
+     * out-of-workstream.
+     */
+    agentWorkstream?: string;
+    /**
+     * Anonymous claim: write `owner = NULL` instead of resolving an agent
+     * name and checking the FK. Use when the actor is the orchestrator
+     * (or a script, or a human) doing direct work in a workstream they
+     * aren't a registered worker in.
+     *
+     * The actor name is still recorded — it ends up in `agent_logs.source`
+     * for the auto-emitted `task claim` event — so provenance is preserved.
+     * Just not in the FK column.
+     *
+     * Resolution order for the actor name (used as the log source):
+     *   1. `actor` if explicitly passed.
+     *   2. Current pane title (when `$TMUX_PANE` is set).
+     *   3. `$USER`.
+     *   4. The literal string 'unknown'.
+     *
+     * Mutually exclusive with `agentName` (the two are alternative
+     * answers to "who's the actor for this claim?"). Passing both is a
+     * usage error.
+     */
+    self?: boolean;
+    /**
+     * Override the actor name used for the log source when `self: true`.
+     * Ignored when `self: false`. Useful when the orchestrator wants to
+     * attribute the work to a meaningful name rather than the pane
+     * title (e.g. "deploy-bot" rather than "pi-mu").
+     */
+    actor?: string;
+}
+interface ClaimResult {
+    /** The agent now owning the task, or null when the claim was anonymous (--self). */
+    ownerName: string | null;
+    /** The actor recorded in the agent_logs event — the agent name for a
+     *  registered-worker claim, or the resolved actor for --self. */
+    actorName: string;
+    /** The previous owner (null if it was unowned). */
+    previousOwnerName: string | null;
+    /** The status BEFORE the claim; post-claim is IN_PROGRESS unless was CLOSED. */
+    previousStatus: TaskStatus;
+    /** The status AFTER the claim. */
+    status: TaskStatus;
+}
+/**
+ * Claim a task. Two modes:
+ *
+ *   Worker claim (default):
+ *     Resolve an agent name from `opts.agentName` or from $TMUX_PANE's
+ *     pane title. The name MUST exist in the agents table (FK on
+ *     tasks.owner). Sets `owner = <name>`. This is what mu-spawned
+ *     workers do, and what `mu task claim --for <worker>` does for
+ *     orchestrator dispatch.
+ *
+ *   Anonymous claim (--self):
+ *     Skip the name -> agents FK lookup entirely. Sets `owner = NULL`.
+ *     Records the actor in `agent_logs.source` instead. This is the
+ *     orchestrator-doing-direct-work path — the actor is logged but
+ *     not registered as a worker pane.
+ *
+ * Status side-effect: OPEN -> IN_PROGRESS; IN_PROGRESS / CLOSED unchanged.
+ *
+ * Concurrency: the worker-claim path uses a single-statement CAS UPDATE
+ * with `WHERE owner IS NULL OR owner = ?` so two workers racing to
+ * claim the same task can't both win. The anonymous path uses
+ * `WHERE owner IS NULL` (anonymous claims don't 'own' the task in any
+ * exclusive sense; if it's already owned by anyone, the anonymous claim
+ * is a TaskAlreadyOwnedError just like a worker claim would be).
+ */
+declare function claimTask(db: Db, localId: string, opts: ClaimTaskOptions): Promise<ClaimResult>;
+/**
+ * Resolve the current actor's identity for attribution in task notes,
+ * --self claims, and any other write that wants 'who did this?'.
+ *
+ * Resolution order:
+ *   1. $MU_AGENT_NAME env var (set by mu spawnAgent on every managed
+ *      pane; surfaced from the f3d4bdd commit). Authoritative when
+ *      present — you're inside a mu-spawned worker, no ambiguity.
+ *   2. tmux pane title (the pane-title identity step). Works
+ *      when running inside any pane mu manages OR adopted.
+ *   3. $USER (when running outside tmux entirely).
+ *   4. The literal 'orchestrator' as a last-resort default.
+ *
+ * Why prefer env over pane title: pane titles are a tmux-server-wide
+ * resource that anything can rewrite. The env var is set per-pane at
+ * spawn time and is unforgeable from outside without explicit
+ * `--actor` override. Pane title is the only identity available for
+ * adopted panes that didn't go through mu's spawn path.
+ */
+declare function resolveActorIdentity(): Promise<string>;
+
+interface TaskRow {
+    /** Per-workstream-unique TEXT name. The operator-facing identifier. */
+    name: string;
+    /** Alias for `name` — the per-workstream-unique TEXT id. Emitted alongside
+     *  `name` so JSON consumers can dot-access the canonical field name without
+     *  having to know that, for tasks specifically, `name` plays the localId
+     *  role. Always equal to `name`. */
+    localId: string;
+    /** Foreign-name reference to the owning workstream. */
+    workstreamName: string;
+    title: string;
+    status: TaskStatus;
+    impact: number;
+    effortDays: number;
+    /** Foreign-name reference to the owning agent (NULL when unowned). */
+    ownerName: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TaskNoteRow {
+    author: string | null;
+    content: string;
+    createdAt: string;
+}
+declare function isValidTaskId(id: string): boolean;
+/**
+ * Lowercase title; collapse non-alnum runs into single `_`; trim
+ * leading/trailing `_`; prefix `t_` if the result starts with a digit
+ * (schema requires first char letter); apply the soft cap with
+ * word-boundary trim (cut at the last `_` at-or-before SLUG_SOFT_CAP
+ * when one exists, else hard-truncate). Mirrors `tg`'s `id_from_title`
+ * but adds the soft cap.
+ *
+ * Throws if `title` yields an empty slug after stripping.
+ */
+declare function slugifyTitle(title: string): string;
+/**
+ * Result of `slugifyTitleVerbose`: the slug plus enough metadata for
+ * the CLI to decide whether to warn the user that meaning was lost.
+ *
+ *   slug           — the same string `slugifyTitle` returns.
+ *   strippedLength — length of the post-strip pre-cap slug. When this
+ *                    exceeds the SLUG_SOFT_CAP the verbose form had to
+ *                    cut at a word boundary (or hard-truncate); the
+ *                    cut clauses are gone with no in-band signal.
+ *   truncated      — true iff `slug.length < strippedLength` AFTER the
+ *                    `t_` digit-prefix correction, i.e. real bytes were
+ *                    dropped. False for any title that fits under the
+ *                    soft cap or whose only diff vs the stripped slug
+ *                    is the `t_` prefix.
+ *
+ * The CLI's `mu task add` uses `truncated` to print a one-line stderr
+ * hint pointing at the `<id>` positional override
+ * (slugifytitle_silently_drops_clauses).
+ */
+interface SlugifyResult {
+    slug: string;
+    strippedLength: number;
+    truncated: boolean;
+}
+/**
+ * Verbose sibling of `slugifyTitle`: returns the slug AND a
+ * `truncated` flag so the CLI can hint to the user when the soft cap
+ * dropped clauses (the meaning-shift hazard documented in
+ * slugifytitle_silently_drops_clauses).
+ *
+ * Algorithm is byte-for-byte identical to `slugifyTitle`; this just
+ * surfaces the metadata that the plain form throws away.
+ */
+declare function slugifyTitleVerbose(title: string): SlugifyResult;
+/**
+ * Generate a unique task id from a title. v5: tasks.local_id is
+ * per-workstream unique, so the collision check scopes to one
+ * workstream. On collision, appends `_2`, `_3`, … until unique.
+ */
+declare function idFromTitle(db: Db, workstream: string, title: string): string;
+/**
+ * Result of `idFromTitleVerbose`: the unique-in-workstream id plus the
+ * truncated flag from the underlying slugify pass. Used by `mu task
+ * add` to decide whether to surface the stderr hint about lost clauses
+ * (slugifytitle_silently_drops_clauses).
+ */
+interface IdFromTitleResult {
+    id: string;
+    truncated: boolean;
+}
+/**
+ * Verbose sibling of `idFromTitle`: returns both the unique id and the
+ * `truncated` flag from the slugify pass. Collision-suffixing (`_2`,
+ * `_3`, …) does not flip `truncated` — the underlying slug's lossiness
+ * is what the CLI hint cares about.
+ */
+declare function idFromTitleVerbose(db: Db, workstream: string, title: string): IdFromTitleResult;
+declare function getTask(db: Db, localId: string, workstream: string): TaskRow | undefined;
+/**
+ * List tasks. With no `workstream` arg returns every row — used by `mu sql`
+ * and by tests; CLI surfaces always pass a workstream so users only see
+ * their own.
+ */
+interface ListTasksOptions {
+    /** Filter to one or more lifecycle statuses. Omitted = all statuses. */
+    status?: TaskStatus | readonly TaskStatus[];
+}
+declare function listTasks(db: Db, workstream?: string, opts?: ListTasksOptions): TaskRow[];
+/** Options for listReady. The optional `statuses` filter composes
+ *  on top of the `ready` view (which itself constrains to
+ *  `status='OPEN'`); passing only OPEN is identical to today's no-
+ *  filter shape, passing only non-OPEN values returns []. Exists so
+ *  `mu task next --status` can mirror the multi-status flag shape
+ *  shipped on `mu task list` (task_list_multi_status_union). */
+interface ListReadyOptions {
+    status?: TaskStatus | readonly TaskStatus[];
+}
+declare function listReady(db: Db, workstream: string, opts?: ListReadyOptions): TaskRow[];
+declare function listBlocked(db: Db, workstream: string): TaskRow[];
+declare function listGoals(db: Db, workstream: string): TaskRow[];
+/** All IN_PROGRESS tasks in a workstream, most-recently-touched first.
+ *  Used by `mu state` and `mu hud` to populate their in-progress slice;
+ *  exposed as a named SDK helper so those CLI verbs don't re-derive
+ *  the row-shape conversion (review_code_raw_task_state_duplicate). */
+declare function listInProgress(db: Db, workstream: string): TaskRow[];
+/** Most-recently-closed tasks in a workstream, newest first, capped at
+ *  `limit` (default 5). Used by `mu state` for its 'recent closed'
+ *  slice; exposed as a named SDK helper so the CLI no longer needs the
+ *  raw-row type that was duplicating RawTaskRow
+ *  (review_code_raw_task_state_duplicate). */
+declare function listRecentClosed(db: Db, workstream: string, limit?: number): TaskRow[];
+/** List notes for a task. Operator-facing local_id; resolves to the
+ *  surrogate task id via taskIdFor (with optional workstream scope). */
+declare function listNotes(db: Db, taskLocalId: string, workstream: string): TaskNoteRow[];
+/**
+ * All tasks currently owned by `agent` in a given workstream
+ * (v5: agents.name is per-workstream unique). Sorted by local_id.
+ *
+ * Defaults to **excluding CLOSED** since the verb's purpose is "what
+ * is X currently working on?" and a closed task is no longer being
+ * worked on. closeTask intentionally preserves `owner` as a
+ * historical record (so audit/notes can attribute decisions); pass
+ * `{ includeClosed: true }` to surface that history.
+ */
+declare function listTasksByOwner(db: Db, workstream: string, owner: string, opts?: {
+    includeClosed?: boolean;
+}): TaskRow[];
+interface SearchTasksOptions {
+    /** Restrict to one workstream; undefined = search across all. */
+    workstream?: string;
+    /** Also search `task_notes.content` (default false: titles + ids only). */
+    includeNotes?: boolean;
+}
+/**
+ * Substring search on task `title` and `local_id`, case-insensitive.
+ * With `includeNotes: true` also searches `task_notes.content`. The
+ * pattern is wrapped in `%...%` automatically so callers don't need
+ * SQL LIKE knowledge — for explicit globs (or regex), use `mu sql`.
+ */
+declare function searchTasks(db: Db, pattern: string, opts?: SearchTasksOptions): TaskRow[];
+interface TaskEdges {
+    /** Tasks that must close before this one can start (blockers). */
+    blockers: string[];
+    /** Tasks that this one blocks (dependents). */
+    dependents: string[];
+}
+/** One end of an edge with the neighbour's current status attached.
+ *  Used by `mu task show` to group blockers/dependents into
+ *  "still gating" vs "satisfied" buckets without making the renderer
+ *  do a second round-trip to the DB per neighbour. */
+interface TaskEdgeWithStatus {
+    name: string;
+    status: TaskStatus;
+}
+interface TaskEdgesWithStatus {
+    /** Tasks that must close before this one can start (blockers),
+     *  carrying each blocker's current status. */
+    blockers: TaskEdgeWithStatus[];
+    /** Tasks that this one blocks (dependents), carrying each
+     *  dependent's current status. */
+    dependents: TaskEdgeWithStatus[];
+}
+/**
+ * Direct (one-hop) edges for a task. For transitive prerequisites, use
+ * `getPrerequisites()`; this helper is the immediate-neighbour view used
+ * by `mu task show`.
+ */
+declare function getTaskEdges(db: Db, taskLocalId: string, workstream: string): TaskEdges;
+/**
+ * Same one-hop edge view as `getTaskEdges`, but each neighbour is
+ * returned as `{ name, status }` so callers can group / colour by
+ * status without an N+1 round-trip. Used by `mu task show` to split
+ * "blocked by" (still-gating) from "satisfied" (already-CLOSED)
+ * blockers, and the symmetric split on the dependents side
+ * (task_show_blocked_by_renders_closed). The status is the neighbour's
+ * full TaskStatus, not just OPEN/CLOSED — REJECTED/DEFERRED still
+ * gate downstream work, so the renderer keeps them in the
+ * still-gating bucket.
+ */
+declare function getTaskEdgesWithStatus(db: Db, taskLocalId: string, workstream: string): TaskEdgesWithStatus;
+/**
+ * All tasks transitively reachable from `taskId` via reverse-edge
+ * traversal (i.e. the set of tasks that block this one), including the
+ * task itself.
+ */
+declare function getPrerequisites(db: Db, taskLocalId: string, workstream: string): Set<string>;
+interface AddTaskOptions {
+    localId: string;
+    workstream: string;
+    title: string;
+    /** 1..100; enforced by schema CHECK. */
+    impact: number;
+    /** > 0; enforced by schema CHECK. */
+    effortDays: number;
+    /**
+     * Tasks that block this one. Edges inserted as `blocker -> newTask`.
+     * Each blocker must already exist AND share this task's workstream
+     * (cross-workstream edges are forbidden); cycle check guards each
+     * edge. The CLI surfaces this as `--blocked-by`; the SDK key matches.
+     */
+    blockedBy?: string[];
+}
+/**
+ * Atomically create a task and (optionally) its incoming blocked-by
+ * edges.
+ *
+ * The task insert + every edge insert + cycle check happen inside one
+ * SQLite transaction. If any blocker is missing or any edge would
+ * create a cycle, the entire add rolls back.
+ *
+ * Cycle check for `addTask` is structurally trivial (a fresh task has
+ * no outgoing edges, so `to -> ... -> from` is impossible). It's still
+ * called here so the same primitive is exercised by tests.
+ */
+declare function addTask(db: Db, opts: AddTaskOptions): TaskRow;
+interface AddNoteOptions {
+    /** Free-form author label. Convention: agent name, "user", or "orchestrator". */
+    author?: string;
+    /** Workstream context (operator-facing name). v5: tasks.local_id is
+     *  per-workstream unique, so this is required to disambiguate. */
+    workstream: string;
+}
+declare function addNote(db: Db, taskLocalId: string, content: string, opts: AddNoteOptions): TaskNoteRow;
+interface BlockEdgeResult {
+    /** True iff a row was actually inserted (vs. already present). */
+    added: boolean;
+}
+/**
+ * Add the edge `blocker → blocked` ('blocker blocks blocked').
+ * Idempotent (existing edge → `added: false`). Validates:
+ *
+ *   - both tasks exist
+ *   - same workstream (cross-workstream edges forbidden)
+ *   - no cycle (the new edge wouldn't form a path blocked → ... → blocker)
+ *   - blocker ≠ blocked (no self-reference)
+ */
+declare function addBlockEdge(db: Db, workstream: string, blocked: string, blocker: string): BlockEdgeResult;
+interface RemoveBlockEdgeResult {
+    /** True iff a row was actually deleted (vs. no such edge). */
+    removed: boolean;
+}
+/**
+ * Remove the edge `blocker → blocked`. Idempotent (no edge →
+ * `removed: false`). Does NOT validate task existence — if the
+ * edge is gone there's nothing to do, regardless of whether the
+ * tasks are gone too.
+ */
+declare function removeBlockEdge(db: Db, workstream: string, blocked: string, blocker: string): RemoveBlockEdgeResult;
+interface DeleteTaskResult {
+    /** True iff the row existed and was deleted. False on a dry-run
+     *  (preview) AND on the idempotent missing-row case. */
+    deleted: boolean;
+    /** Number of `task_edges` rows cascaded out (informational). On a
+     *  dry-run, this is the would-be count. */
+    deletedEdges: number;
+    /** Number of `task_notes` rows cascaded out (informational). On a
+     *  dry-run, this is the would-be count. */
+    deletedNotes: number;
+    /** True iff this was a dry-run (`opts.dryRun: true`). On a
+     *  dry-run `deleted` is false and the counts are the would-be
+     *  counts; the DB is unchanged. Always false on a commit / on a
+     *  missing-row idempotent no-op. */
+    dryRun: boolean;
+    /** True iff a matching task row was found at the time of the
+     *  call. Discriminator for the CLI: a dry-run that found nothing
+     *  (`present: false`) renders differently from a dry-run that
+     *  found an existing task with zero edges and zero notes
+     *  (`present: true, deletedEdges: 0, deletedNotes: 0`). */
+    present: boolean;
+}
+interface DeleteTaskOptions {
+    /** When true, return the cascade preview (would-be edge / note
+     *  counts) without mutating and without snapshotting. The CLI uses
+     *  this to power the bare `mu task delete <id>` two-phase pattern
+     *  (mirrors `mu workstream destroy` / `mu archive delete` /
+     *  `mu snapshot prune`). Surfaced by feedback ws task
+     *  fb_task_delete_no_yes (impact=30): a dogfood report typed
+     *  `mu task delete X --yes` (mirroring workstream destroy) and got
+     *  'unknown option --yes' — the verb took no confirmation flag at
+     *  all. Two failed deletes left long-named tasks lingering. */
+    dryRun?: boolean;
+}
+/**
+ * Delete a task. FK CASCADE on `task_edges` (from + to) and
+ * `task_notes` cleans the joined rows automatically. Idempotent on
+ * a missing task (returns `deleted: false`).
+ *
+ * Pre-counts the cascade victims for reporting because SQLite's
+ * `changes()` only reports rows directly affected by the DELETE.
+ *
+ * With `opts.dryRun: true`, returns the would-be counts without
+ * touching the DB and without taking a snapshot (no mutation = no
+ * snapshot — same reasoning that gates the closeTask snap on the
+ * idempotent no-op path). The CLI bare `mu task delete <id>` form
+ * uses this; `--yes` calls through with `dryRun: false`.
+ */
+declare function deleteTask(db: Db, localId: string, workstream: string, opts?: DeleteTaskOptions): DeleteTaskResult;
+interface UpdateTaskOptions {
+    title?: string;
+    /** 1..100; enforced by schema CHECK. */
+    impact?: number;
+    /** > 0; enforced by schema CHECK. */
+    effortDays?: number;
+}
+interface UpdateTaskResult {
+    /** True iff at least one field actually changed. */
+    updated: boolean;
+    /** The fields whose values differ post-update (in `UpdateTaskOptions`'s
+     *  camelCase shape). Empty when `updated: false`. */
+    changedFields: string[];
+}
+/**
+ * Update scalar fields on a task. Each option is independently optional;
+ * passing none is a typed no-op (returns `updated: false, changedFields: []`).
+ * Fields whose new value equals the current value are skipped (no row change).
+ *
+ * NOT for status (use `closeTask` / `openTask` / `setTaskStatus`), owner
+ * (use `claimTask` / `releaseTask`), local_id (rename is deferred), or
+ * workstream (cross-workstream moves are deferred).
+ */
+interface UpdateTaskScopeOption {
+    workstream: string;
+}
+declare function updateTask(db: Db, localId: string, opts: UpdateTaskOptions, scope: UpdateTaskScopeOption): UpdateTaskResult;
+interface ReparentTaskResult {
+    /** Edges removed (i.e. all incoming `to_task = taskId` edges). */
+    removedEdges: number;
+    /** Edges added (== blockers.length on success). */
+    addedEdges: number;
+}
+/**
+ * Atomically replace every incoming edge of `taskId` with new ones
+ * `blocker[i] → taskId`. Pass an empty `blockers` array to clear all
+ * incoming edges (the task becomes ready iff its status allows).
+ *
+ * Validates ALL new blockers up-front (existence + same workstream +
+ * cycle check); if any fails, no DELETE happens — the call is fully
+ * atomic via a single transaction.
+ *
+ * Cycle reasoning: removing the existing incoming edges to `taskId`
+ * doesn't change `taskId`'s OUTGOING reachability, so
+ * `wouldCreateCycle(db, blocker, taskId)` evaluated against the
+ * pre-state gives the right answer for each new edge.
+ */
+declare function reparentTask(db: Db, taskLocalId: string, blockers: readonly string[], scope: {
+    workstream: string;
+}): ReparentTaskResult;
+
+interface Track {
+    /** Goal tasks (no outgoing edges) belonging to this track. */
+    roots: TaskRow[];
+    /** Every task id reachable as a prerequisite of any root in this track. */
+    taskIds: ReadonlySet<string>;
+    /** Number of READY tasks (per the SQL view) within this track's subgraph. */
+    readyCount: number;
+}
+/**
+ * Identify independent task subtrees suitable for parallel assignment
+ * within a workstream. Open goals only; CLOSED goals are excluded as
+ * they no longer represent work to schedule.
+ *
+ * Scoping: only goals belonging to `workstream` are considered.
+ * Cross-workstream edges are forbidden by addTask, so a goal's
+ * prerequisite subgraph is naturally workstream-internal.
+ */
+declare function getParallelTracks(db: Db, workstream: string): Track[];
+
+/** One per-task summary inside a per-source-ws section of the manifest. */
+interface ExportTaskEntry {
+    /** Task local_id == filename stem (`<id>.md`). */
+    id: string;
+    /** Path relative to the bucket root (e.g. `auth/tasks/design.md`). */
+    path: string;
+    /** sha256 of the markdown body bytes; idempotency key. */
+    sha256: string;
+    /** ISO timestamp of the first observed export at which the task
+     *  was missing from the source. Absent for tasks still present. */
+    deletedAt?: string;
+}
+/** Per-source-ws entry under `manifest.sources`. */
+interface ExportSourceManifest {
+    /** ISO timestamp the source was first added to the bucket. */
+    addedAt: string;
+    /** ISO timestamp of the most recent re-export of this source. */
+    lastReExportedAt: string;
+    /** `latestSeq(db)` at the most recent re-export; for live workstreams
+     *  this is the live `agent_logs.seq` cursor. For archive sources
+     *  there is no equivalent live counter — we record the seq at
+     *  archive-add time when available, else 0. */
+    eventsSeqAtExport: number;
+    /** Per-task entries; sorted by id for stable diffs. */
+    tasks: ExportTaskEntry[];
+}
+/** Top-level bucket manifest. `bucketVersion: 2` — the v0.3 shape.
+ *  v1 (bucketVersion absent + top-level `workstream` field) is the
+ *  legacy single-source shape and is rejected at write time. */
+interface ExportManifest {
+    /** Schema discriminator. Always 2 in this codebase. */
+    bucketVersion: 2;
+    /** Operator-chosen bucket label (an archive label, or null for a
+     *  one-shot `mu workstream export`). Surfaced in README only. */
+    bucketLabel: string | null;
+    bucketCreatedAt: string;
+    bucketLastUpdatedAt: string;
+    muVersion: string;
+    /** Per-source-ws map; key is the source workstream's TEXT name. */
+    sources: Record<string, ExportSourceManifest>;
+}
+/** One source's worth of input: the per-task data the renderer needs.
+ *  Both entry points (workstream / archive) collapse to this shape. */
+interface ExportSource {
+    /** Source workstream name. Becomes the subdirectory name. */
+    name: string;
+    tasks: TaskRow[];
+    /** Per-task edges keyed on task name. Missing keys → no edges. */
+    edges: Map<string, {
+        blockers: string[];
+        dependents: string[];
+    }>;
+    /** Per-task notes keyed on task name. Missing keys → no notes. */
+    notes: Map<string, TaskNoteRow[]>;
+    /** `agent_logs.seq` cursor at this source's snapshot moment. 0 for
+     *  archive sources (no live cursor). */
+    eventsSeqAtExport: number;
+}
+interface RenderBucketInput {
+    sources: ExportSource[];
+    /** Operator-chosen archive label, or null for a workstream export. */
+    bucketLabel: string | null;
+    outDir: string;
+}
+interface RenderBucketResult {
+    outDir: string;
+    /** Per-source-ws stat: how many task files were rewritten across
+     *  every source in this call. */
+    written: number;
+    /** Per-source-ws stat: how many task files were sha256-skipped. */
+    unchanged: number;
+    /** Per-source-ws stat: how many task files exist for a task that
+     *  has since vanished from the source. Banner is added once. */
+    preserved: number;
+    manifestPath: string;
+    manifest: ExportManifest;
+}
+/** Thrown when the operator points an export at a directory whose
+ *  existing manifest predates bucket layout (v1, single-source). The
+ *  fix is destructive (remove and re-export) so we refuse to touch
+ *  it in-place — the legacy directory may be checked into git and
+ *  the operator should choose between rebuilding it and picking a
+ *  new --out. */
+declare class LegacyExportLayoutError extends Error {
+    readonly outDir: string;
+    readonly name = "LegacyExportLayoutError";
+    constructor(outDir: string);
+}
+/**
+ * Render `input.sources` to disk under `input.outDir` in the v0.3
+ * bucket layout. Idempotent + additive:
+ *   - If the bucket doesn't exist, scaffold it.
+ *   - If it does exist with bucketVersion 2, MERGE: each source in
+ *     `input.sources` either appends (new) or refreshes (existing)
+ *     its subdirectory; sources NOT in `input.sources` are left
+ *     untouched.
+ *   - If it exists but with a legacy (v1) manifest, throw
+ *     `LegacyExportLayoutError`.
+ *
+ * Per-task idempotency is sha256-keyed: a re-export of the same
+ * source against an unchanged DB rewrites zero task files. Tasks
+ * that disappear from a source between re-exports are preserved on
+ * disk with a one-time `> **Deleted from DB on <ts>**` banner.
+ */
+declare function renderToBucket(input: RenderBucketInput): RenderBucketResult;
+/** Construct an ExportSource for one live workstream by reading the
+ *  current DB. Pure data assembly; renderer does the I/O. */
+declare function exportSourceForWorkstream(db: Db, workstream: string): ExportSource;
+/** Construct ExportSources for every source workstream that
+ *  contributed to an archive label. One ExportSource per
+ *  (archive_id, source_workstream) partition. The TaskRow shapes are
+ *  reconstructed from archived_* rows; `workstreamName` is set to
+ *  the source workstream so the rendered frontmatter reflects the
+ *  task's original home. */
+declare function exportSourcesForArchive(db: Db, label: string): ExportSource[];
+interface ExportArchiveOptions {
+    label: string;
+    /** Output directory (the bucket). Created if missing. */
+    outDir: string;
+}
+interface ExportArchiveResult extends RenderBucketResult {
+    archiveLabel: string;
+    /** Number of source workstreams the renderer wrote / refreshed. */
+    sourceCount: number;
+}
+/** Render every source-ws in an archive to a bucket directory.
+ *  Throws `ArchiveNotFoundError` (via listArchivedTasks) when the
+ *  label doesn't exist. */
+declare function exportArchive(db: Db, opts: ExportArchiveOptions): ExportArchiveResult;
+
+declare function isValidWorkstreamName(name: string): boolean;
+/** Thrown by `ensureWorkstream` and `mu workstream init` when the name
+ *  doesn't match the rules. */
+declare class WorkstreamNameInvalidError extends Error implements HasNextSteps {
+    readonly attempted: string;
+    readonly name = "WorkstreamNameInvalidError";
+    constructor(attempted: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Ensure a row exists in the `workstreams` table for `name`. Idempotent;
+ * INSERT OR IGNORE so concurrent callers race safely. Called by
+ * `insertAgent` and `addTask` so callers don't need to remember to call
+ * `mu init` before adding a task / spawning an agent (preserves the
+ * spawn-without-init ergonomics now that agents.workstream and
+ * tasks.workstream are real FKs into this table).
+ *
+ * Validates the name before inserting; throws `WorkstreamNameInvalidError`
+ * for names tmux would silently mangle (containing '.' or ':') or that
+ * exceed 32 chars / start with a non-letter.
+ *
+ * Returns true iff a row was actually inserted (vs. already present).
+ */
+declare function ensureWorkstream(db: Db, name: string): boolean;
+interface WorkstreamSummary {
+    /** The workstream's own name. */
+    name: string;
+    /** Tmux session name, defaults to `mu-<name>`. */
+    tmuxSession: string;
+    /** True iff `tmux has-session -t <tmuxSession>` succeeds right now. */
+    tmuxAlive: boolean;
+    /** Rows in `agents` for this workstream. */
+    agentCount: number;
+    /** Rows in `tasks` for this workstream. */
+    taskCount: number;
+    /** Rows in `task_notes` whose task is in this workstream. */
+    noteCount: number;
+    /** Rows in `task_edges` whose `from_task` is in this workstream. */
+    edgeCount: number;
+    /** Rows in `vcs_workspaces` for this workstream. Surfaced so the
+     *  destroy dry-run can warn about per-agent worktrees that need
+     *  cleanup before the FK cascade silently nukes their rows. */
+    workspaceCount: number;
+    /** True iff a row exists in the `workstreams` table itself. False
+     *  for tmux-only `mu-*` sessions that mu never observed via
+     *  `mu workstream init`. Surfaced so destroy can clean up bare
+     *  registry rows (workstream row exists, no agents/tasks/etc.) —
+     *  otherwise such rows are orphaned forever (the previous
+     *  `nothingToDo` heuristic short-circuited on them). */
+    registered: boolean;
+}
+interface DestroyResult {
+    /** True iff `tmux kill-session` actually killed something. */
+    killedTmux: boolean;
+    /** Number of `agents` rows deleted. */
+    deletedAgents: number;
+    /** Number of `tasks` rows deleted (edges/notes cascade via FK). */
+    deletedTasks: number;
+    /** Number of `task_notes` deleted by the cascade — informational. */
+    deletedNotes: number;
+    /** Number of `task_edges` deleted by the cascade — informational. */
+    deletedEdges: number;
+    /** Number of vcs_workspaces whose on-disk path was actually
+     *  removed by the backend on this destroy. Excludes
+     *  `alreadyGoneWorkspaces` (those were no-ops on disk). */
+    freedWorkspaces: number;
+    /** Number of vcs_workspaces whose registry row existed but
+     *  whose on-disk path was already gone (manual rm -rf or a prior
+     *  interrupted destroy). The DB row was cascade-deleted; the
+     *  backend did no filesystem work. Tracked separately so the
+     *  destroy report doesn't lie about how much cleanup it actually
+     *  performed. */
+    alreadyGoneWorkspaces: number;
+    /** Workspaces whose backend cleanup failed (e.g. `git worktree
+     *  remove` refused because of uncommitted changes). The DB row
+     *  was still cascade-deleted; the on-disk path remains and needs
+     *  manual cleanup. */
+    failedWorkspaces: WorkspaceFailure[];
+}
+interface WorkspaceFailure {
+    agent: string;
+    backend: string;
+    path: string;
+    error: string;
+}
+interface WorkstreamOptions {
+    workstream: string;
+    /** Override the tmux session name. Defaults to `mu-<workstream>`. */
+    tmuxSession?: string;
+    /** Override the per-name VcsBackend resolver. Defaults to
+     *  `backendByName`. Lets tests inject a fake backend (e.g. one whose
+     *  `freeWorkspace` throws) without mutating the exported singletons —
+     *  same pattern as `createWorkspace`'s `opts.backend` accepting a
+     *  pre-built `VcsBackend` object. Production callers leave this
+     *  unset. */
+    resolveBackend?: (name: VcsBackendName) => VcsBackend;
+}
+/**
+ * Discover every workstream visible on this machine. The union of:
+ *   - rows in the `workstreams` table (canonical DB source; populated by
+ *     `mu init` and auto-created by insertAgent / addTask)
+ *   - tmux sessions named `mu-*` (with the prefix stripped) — catches
+ *     externally-created `tmux new-session -s mu-foo` that mu hasn't
+ *     observed yet
+ *
+ * Returns one `WorkstreamSummary` per workstream, sorted by name.
+ * Useful as a pre-flight before `mu init` ("is this name taken?") and
+ * for `mu doctor`-style diagnostics.
+ */
+declare function listWorkstreams(db: Db): Promise<WorkstreamSummary[]>;
+declare function summarizeWorkstream(db: Db, opts: WorkstreamOptions): Promise<WorkstreamSummary>;
+/**
+ * Tear down a workstream: kill its tmux session and delete every DB row
+ * tagged with its name. Cascades on `tasks` clean up `task_edges` and
+ * `task_notes` automatically (FK ON DELETE CASCADE in the schema).
+ *
+ * Idempotent: safe to call against a workstream that never existed; safe
+ * to call repeatedly. Returns counts so the caller can print a useful
+ * summary.
+ */
+declare function destroyWorkstream(db: Db, opts: WorkstreamOptions): Promise<DestroyResult>;
+interface ExportWorkstreamOptions {
+    workstream: string;
+    /** Output directory (the bucket). Defaults to `./<workstream>/`
+     *  in the cwd — i.e. the bucket and its single source-ws subdir
+     *  share a name. */
+    outDir?: string;
+}
+interface ExportResult {
+    outDir: string;
+    /** Per-task files rewritten this call. */
+    written: number;
+    /** Per-task files sha256-skipped this call. */
+    unchanged: number;
+    /** Tasks present in a prior manifest that are no longer in the DB.
+     *  Their .md stays on disk; a banner is added once. */
+    preserved: number;
+    manifestPath: string;
+    manifest: ExportManifest;
+    /** Per-source-ws manifest entry for this workstream — convenience
+     *  for callers who only want one source's view. */
+    source: ExportSourceManifest;
+}
+/**
+ * Export one live workstream to a bucket directory. Idempotent +
+ * additive: re-exporting the same workstream is sha256-skipped,
+ * exporting a different workstream into the same bucket appends a
+ * sibling subdir.
+ *
+ * Throws:
+ *   - `LegacyExportLayoutError` if `outDir` already contains a
+ *     pre-0.3 (single-source) manifest.json.
+ */
+declare function exportWorkstream(db: Db, opts: ExportWorkstreamOptions): ExportResult;
+
+declare class ImportBucketInvalidError extends Error implements HasNextSteps {
+    readonly bucketDir: string;
+    readonly reason: string;
+    readonly name = "ImportBucketInvalidError";
+    constructor(bucketDir: string, reason: string);
+    errorNextSteps(): NextStep[];
+}
+declare class ImportLegacyLayoutError extends Error implements HasNextSteps {
+    readonly bucketDir: string;
+    readonly name = "ImportLegacyLayoutError";
+    constructor(bucketDir: string);
+    errorNextSteps(): NextStep[];
+}
+declare class WorkstreamAlreadyExistsError extends Error implements HasNextSteps {
+    readonly workstream: string;
+    readonly name = "WorkstreamAlreadyExistsError";
+    constructor(workstream: string);
+    errorNextSteps(): NextStep[];
+}
+declare class ImportFrontmatterParseError extends Error implements HasNextSteps {
+    readonly path: string;
+    readonly line: number;
+    readonly raw: string;
+    readonly name = "ImportFrontmatterParseError";
+    constructor(path: string, line: number, raw: string);
+    errorNextSteps(): NextStep[];
+}
+declare class ImportEdgeRefMissingError extends Error implements HasNextSteps {
+    readonly fromTask: string;
+    readonly toTask: string;
+    readonly direction: "blocked_by" | "blocks";
+    readonly name = "ImportEdgeRefMissingError";
+    constructor(fromTask: string, toTask: string, direction: "blocked_by" | "blocks");
+    errorNextSteps(): NextStep[];
+}
+interface ImportBucketOptions {
+    bucketDir: string;
+    /** Rename the (single) source workstream on import. Only valid when
+     *  the bucket has exactly one source-ws subdir (after applying any
+     *  `sourceWs` filter); otherwise rejected with an
+     *  ImportBucketInvalidError. */
+    workstreamOverride?: string;
+    /** Restrict the import to a subset of source-ws subdirs (by name).
+     *  Each name must be a key in the bucket manifest's `sources` map;
+     *  otherwise ImportSourceNotInBucketError is raised. Mutually
+     *  exclusive with the per-source-ws-subdir invocation form (Form 1):
+     *  passing this flag against a Form 1 path raises
+     *  ImportBucketInvalidError. Empty array is treated as "no filter";
+     *  the CLI rejects an explicitly-empty `--source-ws ,,`. */
+    sourceWs?: string[];
+    /** Walk + parse but write nothing to the DB. */
+    dryRun?: boolean;
+}
+interface ImportSourceResult {
+    workstreamName: string;
+    tasksImported: number;
+    edgesImported: number;
+    notesImported: number;
+    tombstonesSkipped: number;
+    /** Per-source-ws errors that did NOT roll back this source. Empty
+     *  on success. (Sibling failures live in their own entry.) */
+    errors: string[];
+}
+interface ImportBucketResult {
+    bucketLabel: string | null;
+    bucketVersion: number;
+    sources: ImportSourceResult[];
+}
+/**
+ * Import a v0.3 bucket directory back into the DB. One source-ws
+ * subdirectory becomes one workstream + N tasks + M edges + K notes.
+ * Per source-ws transactional: a failure in source A rolls back A
+ * but leaves source B's import committed.
+ *
+ * Throws on unrecoverable bucket-level errors (no manifest, legacy
+ * layout, --workstream override against multi-source). Per-source
+ * errors (frontmatter parse, edge ref, target name collision) leave
+ * the failing source's `errors` array populated and that source's
+ * counts at zero; siblings still attempt their own import.
+ */
+declare function importBucket(db: Db, opts: ImportBucketOptions): ImportBucketResult;
+
+interface WorkspaceRow {
+    agentName: string;
+    workstreamName: string;
+    backend: VcsBackendName;
+    path: string;
+    parentRef: string | null;
+    createdAt: string;
+    /** How many commits the workspace's parent_ref is behind the project's
+     *  default branch HEAD, as of the last time the workspace's local refs
+     *  cache was updated. Undefined when not yet computed (the listWorkspaces
+     *  fast path leaves it unset; call decorateWithStaleness to populate).
+     *  Null when staleness was queried but cannot be computed (no main found,
+     *  none-backend, missing parent_ref, command failure). */
+    commitsBehindMain?: number | null;
+}
+declare class WorkspaceExistsError extends Error implements HasNextSteps {
+    readonly agent: string;
+    readonly name = "WorkspaceExistsError";
+    constructor(agent: string);
+    errorNextSteps(): NextStep[];
+}
+declare class WorkspaceNotFoundError extends Error implements HasNextSteps {
+    readonly agent: string;
+    readonly name = "WorkspaceNotFoundError";
+    constructor(agent: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown by createWorkspace when the on-disk path it would create is
+ * already occupied. Distinct from WorkspaceExistsError (which is about
+ * the DB row) so the recovery is clear: the dir is orphaned (no DB
+ * row points at it) and needs cleanup.
+ *
+ * Surfaced as a real bug from the multi-agent dogfood (mufeedback note
+ * #143): users hit a bare 'vcs git: workspacePath already exists' from
+ * the backend, with no nextSteps. After the cccba88 fix (close-refuses-
+ * with-workspace), this case only fires when an orphan from a previous
+ * mu version persists OR when the dir was manually rm-rf'd while a
+ * stale registration remains (the git-worktree case).
+ *
+ * Maps to exit code 4 (conflict).
+ */
+declare class WorkspacePathNotEmptyError extends Error implements HasNextSteps {
+    readonly agent: string;
+    readonly workstream: string;
+    readonly workspacePath: string;
+    readonly name = "WorkspacePathNotEmptyError";
+    constructor(agent: string, workstream: string, workspacePath: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown by createWorkspace when the resolved projectRoot is the
+ * user's $HOME. Surfaced by snap_dogfood Finding 4: a `mu workspace
+ * create` invoked from cwd=$HOME with no --project-root began a
+ * recursive `cp -a` of $HOME (~/Music, ~/.config, ...) into the
+ * workspace dir, stalled on DRM-protected files, and on ctrl-C left
+ * a partial dir behind with no DB row.
+ *
+ * The guard's whole point is to make the user pick a real project
+ * deliberately — there's no --force escape hatch on purpose. The
+ * resolution is `--project-root <real-path>` (or `cd` into a real
+ * project first).
+ *
+ * Maps to exit code 4 (conflict).
+ */
+declare class HomeDirAsProjectRootError extends Error implements HasNextSteps {
+    readonly agent: string;
+    readonly workstream: string;
+    readonly homeDir: string;
+    readonly name = "HomeDirAsProjectRootError";
+    constructor(agent: string, workstream: string, homeDir: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Compose the canonical on-disk path for an agent's workspace. Used by
+ * createWorkspace and reachable from `mu workspace path` so the user
+ * can `cd $(mu workspace path foo)` even before the directory exists.
+ */
+declare function workspacePath(workstream: string, agent: string): string;
+/** Root dir for a workstream's workspaces — the parent of all
+ *  per-agent workspace dirs. Used by listWorkspaceOrphans to scan
+ *  the filesystem. */
+declare function workspacesRoot(workstream: string): string;
+interface WorkspaceOrphan {
+    /** The on-disk dir name (the agent name it WOULD be for, if mu had
+     *  registered it). */
+    agentName: string;
+    /** Workstream the dir is filed under. */
+    workstreamName: string;
+    /** Absolute path to the orphan dir. */
+    path: string;
+}
+/**
+ * Like WorkspaceOrphan but additionally flags whether the parent
+ * workstream itself is gone (no row in `workstreams`). Returned by
+ * listAllOrphanWorkspaces; the per-workstream listWorkspaceOrphans
+ * doesn't carry this since by construction it only runs against an
+ * existing workstream.
+ */
+interface StrandedWorkspaceOrphan extends WorkspaceOrphan {
+    /** True iff the parent workstream has no DB row (the dir was left
+     *  behind by a `mu workstream destroy` or a manual DELETE). */
+    stranded: boolean;
+}
+/**
+ * Scan `<state-dir>/workspaces/<workstream>/` for directories that
+ * have no row in `vcs_workspaces`. These are the result of:
+ *   - pre-cccba88 agents closed without --discard-workspace
+ *   - failed spawn rollbacks (pre-bug_agent_spawn_workspace_fk_failure fix)
+ *   - manual cleanup that left the dir but not the row
+ *   - any case where the operator manually rm-rf'd vcs_workspaces rows
+ *
+ * Returns `[]` when the workstream's workspaces dir doesn't exist,
+ * or when every dir on disk has a corresponding DB row. Filesystem
+ * read is best-effort: a missing/inaccessible dir returns `[]`
+ * (caller doesn't have to check existsSync first).
+ *
+ * Surfaced by bug_workspace_orphan_not_in_state: orphan dirs were
+ * invisible to `mu state` and `mu workspace list`, but blocked
+ * subsequent `--workspace` spawns with WorkspacePathNotEmptyError.
+ */
+declare function listWorkspaceOrphans(db: Db, workstream: string): WorkspaceOrphan[];
+/**
+ * Cross-workstream variant of listWorkspaceOrphans. Reads
+ * `<state-dir>/workspaces/`, recurses one level (per-ws subdir →
+ * per-agent subdir), and surfaces every dir with no row in
+ * `vcs_workspaces`.
+ *
+ * Each entry is additionally tagged with `stranded: boolean`: true
+ * when the parent workstream has no row in `workstreams`. Stranded
+ * orphans are the failure mode this verb was added for — workstreams
+ * destroyed before the close-refuses-with-workspace fix landed (or
+ * via `mu sql DELETE FROM workstreams ...`) would leave their entire
+ * workspace subtree invisible to `mu workspace orphans -w <ws>`,
+ * because the user couldn't know to ask for the right name.
+ *
+ * Surfaced by workspace_orphans_misses_destroyed_workstreams. Returns
+ * `[]` when the workspaces root itself doesn't exist; otherwise scans
+ * best-effort and skips any subdir that fails to read.
+ */
+declare function listAllOrphanWorkspaces(db: Db): StrandedWorkspaceOrphan[];
+interface CreateWorkspaceOptions {
+    agent: string;
+    workstream: string;
+    /** Project root to branch from. Defaults to the current working
+     *  directory (the `mu` invocation site, which is normally what the
+     *  user wants). */
+    projectRoot?: string;
+    /** Override backend detection. Default: walk `detectBackend`.
+     *  Accepts either a name ("jj" / "sl" / "git" / "none") OR a
+     *  pre-built `VcsBackend` object — the object form lets tests inject
+     *  a fresh fake backend without mutating the exported singletons. */
+    backend?: VcsBackendName | VcsBackend;
+    /** Optional ref to base the workspace on. Backend-specific. */
+    parentRef?: string;
+}
+/**
+ * Create a fresh workspace for an agent. Allocates the on-disk
+ * directory, records the row, emits a system event. Idempotent ONLY
+ * to the extent that the row check is up-front; if the row exists
+ * we throw `WorkspaceExistsError` rather than silently re-using a
+ * possibly-stale on-disk state. Callers should `freeWorkspace` first.
+ */
+declare function createWorkspace(db: Db, opts: CreateWorkspaceOptions): Promise<WorkspaceRow>;
+declare function getWorkspaceForAgent(db: Db, agent: string, workstream: string): WorkspaceRow | undefined;
+declare function listWorkspaces(db: Db, workstream?: string): WorkspaceRow[];
+declare function decorateWithStaleness(rows: readonly WorkspaceRow[]): Promise<WorkspaceRow[]>;
+interface FreeWorkspaceOptions {
+    /** If true, attempt to commit pending changes before tearing down.
+     *  Backend-specific; see VcsBackend.freeWorkspace. */
+    commit?: boolean;
+}
+interface FreeWorkspaceResult {
+    /** The committed ref, when `commit` was true and there was something
+     *  to commit. */
+    committedRef?: string;
+    /** True iff the on-disk path was actually removed. */
+    removed: boolean;
+    /** True iff the DB row was actually deleted. */
+    rowDeleted: boolean;
+}
+/**
+ * Tear down an agent's workspace. Calls the backend to remove the
+ * on-disk directory (with optional auto-commit), then DELETEs the row.
+ * Idempotent on a missing workspace (returns all-false).
+ */
+declare function freeWorkspace(db: Db, agent: string, opts: FreeWorkspaceOptions & {
+    workstream: string;
+}): Promise<FreeWorkspaceResult>;
+
+type LogKind = "message" | "event" | "broadcast" | string;
+interface LogRow {
+    /** Monotonic AUTOINCREMENT id. Use as the cursor for `--since`. */
+    seq: number;
+    /** Workstream this entry belongs to, or `null` for machine-wide. */
+    workstreamName: string | null;
+    /** Free TEXT: agent name, "system", "user", or anything a caller picks. */
+    source: string;
+    /** Free TEXT: "message" (default), "event" (auto state changes),
+     *  "broadcast" (explicit cross-agent), or any caller-defined value. */
+    kind: LogKind;
+    /** Free utf-8 string. May be JSON if the kind suggests structure. */
+    payload: string;
+    /** ISO 8601 timestamp set at insert time. */
+    createdAt: string;
+}
+interface AppendLogOptions {
+    /** Workstream this entry belongs to. `null` for machine-wide. */
+    workstream: string | null;
+    /** Who emitted this. Agent name, "system", "user", or arbitrary. */
+    source: string;
+    /** Defaults to "message". */
+    kind?: LogKind;
+    /** Free utf-8. Multi-line allowed. */
+    payload: string;
+}
+/**
+ * Append a log entry. Returns the inserted row (with assigned `seq`).
+ * Constant-time. Single INSERT; safe to call from any state-changing
+ * verb without a transaction wrapper.
+ */
+declare function appendLog(db: Db, opts: AppendLogOptions): LogRow;
+interface ListLogsOptions {
+    /** Filter by workstream. `undefined` = every workstream + machine-wide.
+     *  `null` = ONLY machine-wide entries. */
+    workstream?: string | null;
+    /** Strictly > this seq. Use to resume a tail. */
+    since?: number;
+    /** Cap the result. With `since`, returns the FIRST N matching (oldest
+     *  first). Without `since`, returns the LAST N (most recent),
+     *  re-sorted oldest-first. */
+    limit?: number;
+    source?: string;
+    kind?: string;
+}
+/**
+ * List log entries. Always returns oldest-first. Use `since` for
+ * cursor-based reads (the canonical tail pattern); use `limit` alone
+ * for "show me the most recent N" reads.
+ */
+declare function listLogs(db: Db, opts?: ListLogsOptions): LogRow[];
+/**
+ * Return the latest seq currently in the table (or 0 if empty). Used
+ * by `mu log --tail` to start the cursor at "now" so the subscriber
+ * only sees NEW entries unless they explicitly pass `--since 0`.
+ */
+declare function latestSeq(db: Db): number;
+/**
+ * One-line helper for state-changing SDK functions to auto-emit a
+ * `kind='event'` log entry. Called AFTER the mutation succeeds, only
+ * when the mutation actually produced a change (no-ops stay quiet).
+ *
+ * `source` defaults to 'system' since this is the auto-emission path;
+ * a different source means "a specific agent caused this" and is set
+ * by callers like `claimTask` (source = the claiming agent).
+ */
+declare function emitEvent(db: Db, workstream: string | null, payload: string, source?: string): void;
+
+interface SnapshotRow {
+    /** Operator-facing snapshot id. EXCEPTION to the no-surrogate-ids rule:
+     *  snapshots have no human-meaningful name; the id is what the
+     *  operator types in `mu undo --to <id>` / `mu snapshot show <id>`. */
+    id: number;
+    /** NULL for whole-DB snapshots (e.g. workstream destroy). */
+    workstreamName: string | null;
+    /** Human-readable operation label, e.g. "task close design". */
+    label: string;
+    /** Absolute path to the .db file on disk. */
+    dbPath: string;
+    /** schema_version at the moment of capture. */
+    schemaVersion: number;
+    /** ISO-8601 capture timestamp. */
+    createdAt: string;
+}
+interface ListSnapshotsOptions {
+    /** Filter to one workstream. NULL-workstream rows are also returned
+     *  when this is set, since they (workstream-destroy snapshots) span
+     *  every workstream including this one. */
+    workstream?: string;
+    /** Cap the number of rows returned. Default: no cap. */
+    limit?: number;
+}
+interface CaptureSnapshotResult {
+    id: number;
+    dbPath: string;
+}
+interface RestoreSnapshotResult {
+    id: number;
+    /** The path the snapshot was copied to (the live DB path). */
+    restoredTo: string;
+    /** schema_version of the restored snapshot (== CURRENT_SCHEMA_VERSION
+     *  by virtue of having passed the version check). */
+    schemaVersion: number;
+}
+declare class SnapshotNotFoundError extends Error implements HasNextSteps {
+    readonly snapshotId: number;
+    readonly name = "SnapshotNotFoundError";
+    constructor(snapshotId: number);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown by restoreSnapshot when the snapshot's schema_version doesn't
+ * match the live DB's CURRENT_SCHEMA_VERSION. Maps to exit code 4
+ * (conflict). Auto-migration of snapshot files was deliberately rejected
+ * in snap_design note #293 (mutates forensic data; migrations are
+ * forward-only).
+ */
+declare class SnapshotVersionMismatchError extends Error implements HasNextSteps {
+    readonly snapshotId: number;
+    readonly snapshotVersion: number;
+    readonly currentVersion: number;
+    readonly name = "SnapshotVersionMismatchError";
+    constructor(snapshotId: number, snapshotVersion: number, currentVersion: number);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown when the snapshot's .db file has been removed from disk (manual
+ * cleanup, fs corruption) but the row still exists. Maps to exit code 3
+ * (not found).
+ */
+declare class SnapshotFileMissingError extends Error implements HasNextSteps {
+    readonly snapshotId: number;
+    readonly dbPath: string;
+    readonly name = "SnapshotFileMissingError";
+    constructor(snapshotId: number, dbPath: string);
+    errorNextSteps(): NextStep[];
+}
+/** Read the operator-tunable count cap (`MU_SNAPSHOT_KEEP_LAST`). */
+declare function gcMaxCount(): number;
+/** Read the operator-tunable age cap (`MU_SNAPSHOT_MAX_AGE_DAYS`). */
+declare function gcMaxAgeDays(): number;
+/**
+ * Resolve the snapshots directory.
+ *
+ * If a live `Db` handle is supplied, snapshots land under
+ * `<dirname(db-path)>/snapshots/` — colocated with the DB they back.
+ * This keeps snapshots discoverable for non-default DB paths
+ * (`MU_DB_PATH=/some/place/foo.db` users) AND keeps tests that use
+ * temp-dir DBs from polluting the user's `~/.local/state/mu/`.
+ *
+ * Without a Db handle, falls back to `<state-dir>/snapshots/` (the
+ * canonical default per snap_design §WHERE).
+ *
+ * Flat (not per-workstream) by design: workstream-destroy snapshots
+ * span every workstream so subdirs would lie about scope.
+ */
+declare function snapshotsDir(db?: Db): string;
+/**
+ * Take a whole-DB snapshot before a destructive verb mutates state.
+ *
+ * Steps:
+ *   1. INSERT a row to claim an id.
+ *   2. VACUUM INTO <state-dir>/snapshots/<id>.db. Synchronous; runs
+ *      page-level on the live DB without extra locks beyond SQLite's
+ *      existing busy_timeout.
+ *   3. UPDATE the row with the canonical db_path (we couldn't know it
+ *      before step 1 because id is AUTOINCREMENT).
+ *   4. Run opportunistic GC.
+ *
+ * If VACUUM INTO fails (disk full, perms, race), the row is rolled back
+ * so the DB never points at a non-existent file. The original verb's
+ * exception path still surfaces the underlying error.
+ *
+ * Idempotent on a same-instant double-call (each call gets its own id).
+ */
+declare function captureSnapshot(db: Db, label: string, workstream?: string | null): CaptureSnapshotResult;
+/**
+ * List snapshots, newest first. When `workstream` is set, returns rows
+ * for that workstream PLUS rows with workstream = NULL (workstream-
+ * destroy snapshots span every workstream so excluding them would hide
+ * the most-recent restorable point during recovery).
+ */
+declare function listSnapshots(db: Db, opts?: ListSnapshotsOptions): SnapshotRow[];
+/**
+ * Restore a snapshot by file-swapping its .db onto the live DB path.
+ *
+ * Caller contract: pass the live `Db` handle so we can read the live DB
+ * path, the snapshot row, and emit a pre-restore self-snapshot for the
+ * "undo of undo" case (snap_design §EDGE CASES > snapshot-of-snapshot).
+ *
+ * The caller is expected to be a short-lived `mu undo` process: this
+ * function CLOSES `db` after taking the pre-restore snapshot, then
+ * fs.copyFileSync's the snapshot file onto the live DB path and unlinks
+ * any -wal / -shm sidecars. Any other live mu process holding the DB
+ * will see SQLITE_BUSY / disk-image-malformed on next write and exit
+ * cleanly (snap_design recommends gating the verb behind --yes for
+ * exactly this reason; that's snap_undo_verb's surface, not ours).
+ */
+declare function restoreSnapshot(db: Db, snapshotId: number): RestoreSnapshotResult;
+/**
+ * Drop snapshots that are EITHER past the count cap OR past the age
+ * cap — "whichever cap is more permissive wins" (snap_design §GC).
+ * Concretely: keep the N most recent AND keep everything <D days old;
+ * delete the rest (and their on-disk .db files).
+ *
+ * The caps come from `gcMaxCount()` / `gcMaxAgeDays()` (env-tunable
+ * via `MU_SNAPSHOT_KEEP_LAST` / `MU_SNAPSHOT_MAX_AGE_DAYS`).
+ *
+ * NOTE: prior to snapshot_gc_caps_too_lax_no_cleanup_verb the WHERE
+ * was `created_at < cutoff AND id NOT IN protected`, i.e. "delete
+ * only if BOTH old AND past the count cap". That made the count cap
+ * effectively dead under bursty use (every row was younger than the
+ * 14-day age cap, so the date filter spared everything regardless of
+ * row count). The fix flips AND→OR.
+ *
+ * Best-effort on file unlink: if a file is already gone, the row goes
+ * anyway (the user's intent — "this snapshot is gone" — is satisfied).
+ */
+declare function gcSnapshots(db: Db): {
+    deletedRows: number;
+    deletedFiles: number;
+};
+type PruneMode = "gc" | "keep-last" | "older-than" | "stale-version" | "all";
+interface PruneOptions {
+    mode: PruneMode;
+    /** For mode='keep-last'. Required by the CLI. */
+    keepLast?: number;
+    /** For mode='older-than'. Days; required by the CLI. */
+    olderThanDays?: number;
+    /** When true, return the would-delete shape but don't touch the DB
+     *  or the on-disk .db files. */
+    dryRun?: boolean;
+}
+interface PruneResult {
+    /** Rows that would be / were deleted. Always populated, even on
+     *  dry-run (the CLI's summary uses it). */
+    victims: SnapshotRow[];
+    /** Total bytes that would be / were freed (sum of victim file
+     *  sizes; missing files contribute 0). */
+    freedBytes: number;
+    /** Number of `snapshots` rows actually deleted. 0 on dry-run. */
+    deletedRows: number;
+    /** Number of on-disk .db files actually unlinked. 0 on dry-run. */
+    deletedFiles: number;
+    /** Set when mode='all' and dryRun=false: id of the safety-net
+     *  snapshot captured BEFORE the wipe. (Survives the wipe.) */
+    safetyNetSnapshotId?: number;
+}
+declare class PruneOptionsInvalidError extends Error implements HasNextSteps {
+    readonly name = "PruneOptionsInvalidError";
+    errorNextSteps(): NextStep[];
+}
+/** True if a snapshot row's schema_version doesn't match the live DB's
+ *  CURRENT_SCHEMA_VERSION. Stale snapshots are unrestorable (restore
+ *  raises SnapshotVersionMismatchError) — surfaced dimmed in
+ *  `mu snapshot list` and as the target set of `prune --stale-version`. */
+declare function isStaleVersion(row: {
+    schemaVersion: number;
+}): boolean;
+/**
+ * Bulk policy-driven cleanup. The CLI's `mu snapshot prune` verb is
+ * a thin wrapper. Modes:
+ *
+ *   gc            — apply the auto-GC policy explicitly (same as the
+ *                   opportunistic call inside captureSnapshot).
+ *   keep-last     — keep only the N newest rows.
+ *   older-than    — drop rows whose created_at is older than D days.
+ *   stale-version — drop rows whose schema_version != current.
+ *   all           — drop EVERY row. dryRun=false additionally captures
+ *                   a safety-net snapshot of the live DB FIRST, so a
+ *                   subsequent `mu undo` can recover; the safety-net
+ *                   row survives the wipe.
+ *
+ * On dryRun=true: returns the victim set + freed-bytes total without
+ * touching the DB or the filesystem.
+ */
+declare function pruneSnapshots(db: Db, opts: PruneOptions): PruneResult;
+interface DeleteSnapshotResult {
+    /** Always true on success. (Misses raise SnapshotNotFoundError; the
+     *  shape mirrors `deleteTask`'s structured-result style.) */
+    deleted: true;
+    /** 1 if the .db file was on disk + unlinked; 0 if it was already
+     *  gone (orphaned row). */
+    deletedFiles: 0 | 1;
+    /** Bytes freed by unlinking the .db file. 0 when the file was
+     *  already gone. */
+    freedBytes: number;
+}
+/**
+ * Surgical removal of one snapshot: drop the `snapshots` row + unlink
+ * the on-disk .db file. Mirrors `mu task delete`. Errors with
+ * `SnapshotNotFoundError` on miss.
+ *
+ * No auto-snapshot before the delete: the point IS to delete one row,
+ * and removing one stepping-stone can't break `mu undo` (it still has
+ * every other snapshot). Auto-snapshotting here would be circular.
+ */
+declare function deleteSnapshot(db: Db, snapshotId: number): DeleteSnapshotResult;
+/** Return the on-disk size of the snapshot file in bytes, or null if
+ *  the file is missing. Useful for `mu snapshot list --json` output. */
+declare function snapshotFileSize(snapshot: SnapshotRow): number | null;
+
+export { type AddNoteOptions, type AddTaskOptions, type AddToArchiveResult, type AdoptAgentOptions, type AdoptAgentResult, AgentDiedOnSpawnError, AgentExistsError, AgentNotFoundError, AgentNotInWorkstreamError, type AgentRow, type AgentStatus, type AppendLogOptions, type Archive, ArchiveAlreadyExistsError, ArchiveLabelInvalidError, ArchiveNotFoundError, type ArchiveSearchHit, type ArchiveSourceSummary, type ArchiveSummary, type ArchivedTaskRow, type BlockEdgeResult, CURRENT_SCHEMA_VERSION, type CaptureOptions, type CaptureSnapshotResult, type ClaimResult, type ClaimTaskOptions, ClaimerNotRegisteredError, type CloseAgentOptions, type CloseAgentResult, CrossWorkstreamEdgeError, CycleError, type Db, type DeleteSnapshotResult, type DeleteTaskResult, type DestroyResult, type DetectedStatus, EXPECTED_TABLES, type EvidenceOption, type ExportArchiveOptions, type ExportArchiveResult, type ExportManifest, type ExportResult, type ExportSource, type ExportSourceManifest, type ExportTaskEntry, type ExportWorkstreamOptions, type FreeAgentResult, HomeDirAsProjectRootError, type IdFromTitleResult, ImportBucketInvalidError, type ImportBucketOptions, type ImportBucketResult, ImportEdgeRefMissingError, ImportFrontmatterParseError, ImportLegacyLayoutError, type ImportSourceResult, type InsertAgentInput, LegacyExportLayoutError, type ListArchivedTasksOptions, type ListLiveAgentsOptions, type ListLogsOptions, type ListReadyOptions, type ListSnapshotsOptions, type ListTasksOptions, type LiveAgentsView, type LogKind, type LogRow, type NewSessionOptions, type NewWindowOptions, type OpenDbOptions, PANE_ID_RE, PaneNotFoundError, type PruneMode, type PruneOptions, PruneOptionsInvalidError, type PruneResult, type ReconcileMode, type ReconcileOptions, type ReconcileReport, type RejectDeferOptions, type RejectDeferResult, type ReleaseResult, type ReleaseTaskOptions, type RemoveBlockEdgeResult, type RemoveFromArchiveResult, type RenderBucketInput, type RenderBucketResult, type ReparentTaskResult, type RestoreSnapshotResult, STATUSES_TERMINAL_OR_PARKED, STATUS_EMOJI, SchemaTooOldError, type SearchArchivesOptions, type SearchTasksOptions, type SendOptions, type SetStatusResult, type SlugifyResult, SnapshotFileMissingError, SnapshotNotFoundError, type SnapshotRow, SnapshotVersionMismatchError, type SpawnAgentOptions, type SplitWindowOptions, type StrandedWorkspaceOrphan, TASK_STATUSES, TASK_STATUS_LIST, TaskAlreadyOwnedError, type TaskEdgeWithStatus, type TaskEdges, type TaskEdgesWithStatus, TaskExistsError, TaskHasOpenDependentsError, TaskNotFoundError, TaskNotInWorkstreamError, type TaskNoteRow, type TaskRow, type TaskStatus, type TaskWaitOptions, type TaskWaitRef, type TaskWaitResult, type TaskWaitTaskState, TmuxError, type TmuxExecResult, type TmuxExecutor, type TmuxPane, type TmuxSession, type TmuxWindow, type Track, type UpdateTaskOptions, type UpdateTaskResult, type VcsBackend, type VcsBackendName, type CreateWorkspaceOptions$1 as VcsCreateWorkspaceOptions, type CreateWorkspaceResult as VcsCreateWorkspaceResult, type FreeWorkspaceOptions$1 as VcsFreeWorkspaceOptions, type FreeWorkspaceResult$1 as VcsFreeWorkspaceResult, type CreateWorkspaceOptions as WorkspaceCreateOptions, WorkspaceExistsError, type WorkspaceFailure, type FreeWorkspaceOptions as WorkspaceFreeOptions, type FreeWorkspaceResult as WorkspaceFreeResult, WorkspaceNotFoundError, type WorkspaceOrphan, WorkspacePathNotEmptyError, WorkspacePreservedError, type WorkspaceRow, WorkstreamAlreadyExistsError, WorkstreamNameInvalidError, type WorkstreamOptions, type WorkstreamSummary, addBlockEdge, addNote, addTask, addToArchive, adoptAgent, appendLog, assertValidPaneId, backendByName, capturePane, captureSnapshot, claimTask, closeAgent, closeTask, composeAgentTitle, createArchive, createWorkspace, currentAgentName, currentPaneTitle, decorateWithStaleness, defaultDbPath, defaultSendDelayMs, defaultSpawnLivenessMs, defaultStateDir, deferTask, deleteAgent, deleteArchive, deleteSnapshot, deleteTask, destroyWorkstream, detectBackend, detectPiStatus, emitEvent, ensureWorkstream, ensureWorkstreamStateDir, exportArchive, exportSourceForWorkstream, exportSourcesForArchive, exportWorkstream, extractTail, freeAgent, freeWorkspace, gcMaxAgeDays, gcMaxCount, gcSnapshots, getAgent, getAgentByPane, getArchive, getParallelTracks, getPrerequisites, getTask, getTaskEdges, getTaskEdgesWithStatus, getWaitPollCount, getWorkspaceForAgent, gitBackend, idFromTitle, idFromTitleVerbose, importBucket, insertAgent, isStaleVersion, isTaskStatus, isValidAgentName, isValidArchiveLabel, isValidPaneId, isValidTaskId, isValidWorkstreamName, jjBackend, killPane, killSession, latestSeq, listAgents, listAllOrphanWorkspaces, listArchivedTasks, listArchives, listBlocked, listGoals, listInProgress, listLiveAgents, listLogs, listNotes, listPanes, listPanesInSession, listReady, listRecentClosed, listSessions, listSnapshots, listTasks, listTasksByOwner, listWindows, listWorkspaceOrphans, listWorkspaces, listWorkstreams, newSession, newSessionWithPane, newWindow, noneBackend, openDb, openTask, paneExists, parseAgentNameFromTitle, pruneSnapshots, readAgent, reconcile, refreshAgentTitle, rejectTask, releaseTask, removeBlockEdge, removeFromArchive, renderToBucket, reparentTask, resetSleep, resetTmuxExecutor, resetWaitPollCount, resolveActorIdentity, resolveCliCommand, restoreSnapshot, searchArchives, searchTasks, selectLayout, sendToAgent, sendToPane, sessionExists, setPaneTitle, setSleepForTests, setTaskStatus, setTmuxExecutor, setWaitSleepForTests, setWaitStuckWarnForTests, slBackend, sleep, slugifyTitle, slugifyTitleVerbose, snapshotFileSize, snapshotsDir, spawnAgent, splitWindow, summarizeWorkstream, tmux$1 as tmux, updateAgentStatus, updateTask, waitForTasks, workspacePath, workspacesRoot, workstreamStateDir };