@martintrojer/mu 0.3.2 → 0.4.1

package/dist/index.d.ts

@@ -49,15 +49,6 @@ declare function defaultStateDir(): string;
  *   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
@@ -71,15 +62,13 @@ declare class SchemaTooOldError extends Error implements HasNextSteps {
     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;
+/** The schema version a fresh DB starts at. v8 adds the
+ *  machine_identity and workstream_sync sync substrate on top of v7
+ *  (which dropped the approvals table), v6 (which added 5 archive_*
+ *  tables), and v5's surrogate-PK substrate. The refusal floor is
+ *  v5 — pre-v5 DBs throw `SchemaTooOldError`; v5+ DBs are
+ *  forward-bumped in place by `applySchema`. */
+declare const CURRENT_SCHEMA_VERSION = 8;
 /** 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
@@ -221,7 +210,19 @@ interface NewSessionWithPaneOptions {
  * 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. */
+/**
+ * Idempotent: succeeds even if the session is already gone.
+ *
+ * Three swallowed shapes:
+ *   - "can't find session: <name>"  — session never existed.
+ *   - "session not found"           — alternate phrasing on some tmux builds.
+ *   - "no server running on <path>" — the tmux server itself has exited
+ *     (typical when the test suite runs against a private `tmux -L
+ *     <socket>` server and the just-killed session was its last; tmux
+ *     quietly shuts the server down). Without this, killSession would
+ *     throw on the very next idempotent call — only visible under
+ *     Layer 3 of bug_test_suite_flake_leaks_isolation.
+ */
 declare function killSession(name: string): Promise<void>;
 declare function listWindows(session?: string): Promise<TmuxWindow[]>;
 interface NewWindowOptions {
@@ -338,8 +339,7 @@ declare function enableMuPaneBordersForPane(paneId: string): Promise<void>;
  * 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.
+ * Designed as the pane-border visual cue for mu-managed panes.
  */
 declare function enableMuPaneBorders(target: string): Promise<void>;
 /**
@@ -363,18 +363,6 @@ declare function getPaneTitle(paneId: string): Promise<string | undefined>;
  * 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`,
@@ -445,7 +433,6 @@ 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;
@@ -478,7 +465,7 @@ 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_paneTTY as paneTTY, 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 };
+  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_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_paneTTY as paneTTY, 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 };
 }
 
 /**
@@ -495,9 +482,9 @@ declare namespace tmux$1 {
  *                 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
+ *                 does NOT reap. Used by `mu state` 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).
@@ -513,7 +500,7 @@ declare namespace tmux$1 {
  *
  * 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
+ * detect status", so state-card pollers showed stale status
  * indefinitely. Splitting prune-suppression from status-suppression
  * is the fix.
  */
@@ -757,8 +744,20 @@ interface CommitSummary {
     subject: string;
     /** Remainder of the commit message (may be empty). */
     body: string;
+    /** Author display name, when the backend exposes one. */
+    author: string;
     /** ISO-8601 author / commit timestamp. */
     authorDate: string;
+    /** Compact relative author time (e.g. "3m", "2d"). */
+    relTime: string;
+}
+interface ShowCommitResult {
+    /** Captured VCS show output (possibly truncated). Empty string on error. */
+    text: string;
+    /** True when stdout exceeded SHOW_COMMIT_MAX_CHARS and was clipped. */
+    truncated: boolean;
+    /** Human-readable error message; omitted on success. */
+    error?: string;
 }
 interface CreateWorkspaceOptions$1 {
     /** The repository being branched from. Absolute path. */
@@ -784,7 +783,7 @@ interface FreeWorkspaceOptions$1 {
      *  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. */
+     *  lost — the verb prints a clear warning. */
     commit: boolean;
 }
 interface FreeWorkspaceResult$1 {
@@ -885,6 +884,13 @@ interface VcsBackend {
      * on backend command failure (unknown ref, missing repo).
      */
     commitsSinceBase(workspacePath: string, baseRef: string): Promise<CommitSummary[]>;
+    /** Last N commits on the project root, newest-first. Used by the
+     *  TUI Commits card / popup. Unlike commitsSinceBase, this is NOT
+     *  a per-workspace since-fork query. */
+    recentCommits(projectRoot: string, limit: number): Promise<CommitSummary[]>;
+    /** Show one commit / change from the project root, capped for TUI
+     *  rendering. Backend-specific equivalent of `git show <sha>`. */
+    showCommit(projectRoot: string, sha: string): Promise<ShowCommitResult>;
     /**
      * Return the list of dirty (uncommitted / unstaged / untracked-not-
      * ignored) paths in the workspace. Empty array = clean.
@@ -907,10 +913,15 @@ interface VcsBackend {
      */
     listDirtyFiles(workspacePath: string): Promise<string[]>;
 }
-declare const noneBackend: VcsBackend;
+
 declare const gitBackend: VcsBackend;
+
 declare const jjBackend: VcsBackend;
+
+declare const noneBackend: VcsBackend;
+
 declare const slBackend: VcsBackend;
+
 /** Return the backend that should handle projectRoot. Walks BACKENDS
  *  in precedence order; never returns undefined because noneBackend
  *  always claims. */
@@ -1403,7 +1414,7 @@ interface ListLiveAgentsOptions {
      * documented mutating behaviour `mu agent list` has always had).
      *
      * Read-only callers split two ways:
-     *   - `mu hud`, `mu state`, bare `mu`, `mu agent attach` →
+     *   - `mu state`, `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
@@ -1435,10 +1446,10 @@ interface LiveAgentsView {
 /**
  * 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.
+ * pollers (`mu state`, `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>;
 
@@ -1523,14 +1534,9 @@ interface AddToArchiveResult {
     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.) */
+    /** Number of new archived_notes rows inserted. */
     addedNotes: number;
-    /** Number of new archived_events rows inserted (one per kind='event'
-     *  agent_logs row in the source workstream). */
+    /** Number of new archived_events rows inserted. */
     addedEvents: number;
 }
 interface RemoveFromArchiveResult {
@@ -1543,26 +1549,25 @@ interface RemoveFromArchiveResult {
     /** 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.
+ * Add every task in `workstream` to the archive identified by `label`.
  *
- * 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 []).
+ * 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.
  */
-declare function listArchives(db: Db): ArchiveSummary[];
+declare function addToArchive(db: Db, label: string, workstream: string): AddToArchiveResult;
 /**
- * Look up a single archive by label. Throws `ArchiveNotFoundError`
- * on miss.
+ * Remove every row contributed by `sourceWorkstream` from the named
+ * archive. Other source workstreams' contributions are untouched
+ * (additive accumulation invariant).
  */
-declare function getArchive(db: Db, label: string): ArchiveSummary;
+declare function removeFromArchive(db: Db, label: string, sourceWorkstream: string): RemoveFromArchiveResult;
+
 /**
  * Delete an archive and every row that references it. The FK
  * CASCADE chain (archives → archived_tasks → archived_edges /
@@ -1571,57 +1576,35 @@ declare function getArchive(db: Db, label: string): ArchiveSummary;
  *
  * 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).
+ * Create a new archive bucket. Throws `ArchiveAlreadyExistsError` if
+ * the label is already in use; throws `ArchiveLabelInvalidError` for
+ * malformed labels.
  *
- * The whole operation runs in a transaction so a partial failure
- * leaves the archive untouched.
+ * The archive starts EMPTY: created_at and last_added_at both equal
+ * now(). Use `addToArchive(label, workstream)` to populate it.
  */
-declare function addToArchive(db: Db, label: string, workstream: string): AddToArchiveResult;
+declare function createArchive(db: Db, label: string, description?: string): Archive;
 /**
- * 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.
+ * 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 removeFromArchive(db: Db, label: string, sourceWorkstream: string): RemoveFromArchiveResult;
+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;
 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.
- */
+declare function listArchivedTasks(db: Db, label: string, opts?: ListArchivedTasksOptions): ArchivedTaskRow[];
 interface ArchiveSearchHit {
     /** Operator-facing label of the parent archive. */
     archiveLabel: string;
@@ -1641,44 +1624,37 @@ interface ArchiveSearchHit {
     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. */
+    /** LIKE-style needle. Wrapped in `%…%` automatically. */
     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`. */
+     *  the default. */
     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).
- */
+/** LIKE-search archived task titles AND archived note content. */
 declare function searchArchives(db: Db, opts: SearchArchivesOptions): ArchiveSearchHit[];
-declare function listArchivedTasks(db: Db, label: string, opts?: ListArchivedTasksOptions): ArchivedTaskRow[];
+
+declare class ArchiveSourceAmbiguousError extends Error implements HasNextSteps {
+    readonly label: string;
+    readonly sources: readonly string[];
+    readonly name = "ArchiveSourceAmbiguousError";
+    constructor(label: string, sources: readonly string[]);
+    errorNextSteps(): NextStep[];
+}
+interface RestoreArchiveOptions {
+    sourceWorkstream?: string;
+}
+interface RestoreArchiveResult {
+    archiveLabel: string;
+    sourceWorkstream: string;
+    workstreamName: string;
+    restoredTasks: number;
+    restoredEdges: number;
+    restoredNotes: number;
+}
+declare function restoreArchive(db: Db, label: string, asWorkstream: string, opts?: RestoreArchiveOptions): RestoreArchiveResult;
 
 type TaskStatus = "OPEN" | "IN_PROGRESS" | "CLOSED" | "REJECTED" | "DEFERRED";
 /** Every legal task status, in canonical order (matches the schema
@@ -1702,1561 +1678,1679 @@ declare function isTaskStatus(s: string): s is TaskStatus;
  *  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[];
+interface TaskRow {
+    /** Per-workstream-unique TEXT name. The operator-facing identifier. */
+    name: 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;
 }
-declare class TaskExistsError extends Error implements HasNextSteps {
-    readonly taskId: string;
-    readonly name = "TaskExistsError";
-    constructor(taskId: string);
-    errorNextSteps(): NextStep[];
+interface TaskNoteRow {
+    author: string | null;
+    content: string;
+    createdAt: string;
+}
+
+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[];
 }
 /**
- * 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).
+ * 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 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 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 BlockEdgeResult {
+    /** True iff a row was actually inserted (vs. already present). */
+    added: boolean;
 }
-declare class TaskAlreadyOwnedError extends Error implements HasNextSteps {
-    readonly taskId: string;
-    readonly currentOwner: string;
-    readonly name = "TaskAlreadyOwnedError";
-    constructor(taskId: string, currentOwner: string);
-    errorNextSteps(): NextStep[];
+/**
+ * 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;
 }
 /**
- * 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.
+ * 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 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[];
+declare function removeBlockEdge(db: Db, workstream: string, blocked: string, blocker: string): RemoveBlockEdgeResult;
+interface ReparentTaskResult {
+    /** Edges removed (i.e. all incoming `to_task = taskId` edges). */
+    removedEdges: number;
+    /** Edges added (after duplicate blockers are canonicalised). */
+    addedEdges: number;
 }
 /**
- * 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.
+ * 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).
  *
- * 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 agent adopt <pane-id>` to register, or use --for to pick a
- * different agent).
+ * 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.
  *
- * Maps to exit code 4 (conflict) via the cli.ts handler.
+ * 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 class ClaimerNotRegisteredError extends Error implements HasNextSteps {
-    readonly agentName: string;
-    readonly paneId: string | null;
-    readonly name = "ClaimerNotRegisteredError";
-    constructor(agentName: string, paneId: string | null);
+declare function reparentTask(db: Db, taskLocalId: string, blockers: readonly string[], scope: {
+    workstream: string;
+}): ReparentTaskResult;
+
+interface AddTaskOptions {
+    localId: string;
+    workstream: string;
+    title: string;
+    /** 1..100; enforced by schema CHECK. */
+    impact: number;
+    /** > 0; enforced by schema CHECK. */
+    effortDays: number;
     /**
-     * Three actionable resolutions in expected-frequency order:
-     *   1. --self  : orchestrator pattern (working directly)
-     *   2. --for   : dispatcher pattern (assigning to a worker)
-     *   3. mu agent adopt: registration pattern (promote pane to worker)
+     * 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.
      */
-    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;
+    blockedBy?: 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>;
+/**
+ * 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;
 }
-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;
+declare function addNote(db: Db, taskLocalId: string, content: string, opts: AddNoteOptions): {
+    author: string | null;
+    content: string;
+    createdAt: string;
+};
+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 TaskWaitResult {
-    /** Per-task state at exit time. Same length and order as the input
-     *  list. The caller derives all-reached / any-reached / elapsed
-     *  from this list (count `r.reachedTarget`) and from its own
-     *  startedAt clock — keeping the SDK return minimal. */
-    refs: TaskWaitTaskState[];
-    /** True when we exited because of the timeout, not because the wait
-     *  condition was met. Refs that did reach the target are still
-     *  reflected in `refs[i].reachedTarget` on partial-progress timeout. */
-    timedOut: 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;
 }
 /**
- * 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).
+ * 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-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.
+ * 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 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;
+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;
 }
-/**
- * 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;
+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[];
 }
 /**
- * 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.
+ * 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).
  */
-declare function setTaskStatus(db: Db, localId: string, status: TaskStatus, opts: EvidenceOption & {
+interface UpdateTaskScopeOption {
     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;
-    /** Optional actor identity attributed to the synthetic `CLOSE: …`
-     *  note auto-inserted when `evidence` is non-empty (see closeTask
-     *  body). The CLI resolves this via `resolveActorIdentity()` so the
-     *  note carries the closing worker's name; SDK callers (tests,
-     *  internal use) may omit it (the note then carries no author, same
-     *  as a bare `addNote` without `--author`). Surfaced in mufeedback
-     *  task_close_evidence_does_not_append_the. */
-    author?: string;
 }
-/** 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.
+declare function updateTask(db: Db, localId: string, opts: UpdateTaskOptions, scope: UpdateTaskScopeOption): UpdateTaskResult;
+
+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.
  *
- *  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;
+ * 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.
+ *   originalSlug   — what the slug WOULD have been without the
+ *                    SLUG_SOFT_CAP cut: full stripped slug with the
+ *                    same `t_` digit-prefix correction and the same
+ *                    SLUG_HARD_CAP ceiling, but no word-boundary
+ *                    truncation. Equal to `slug` when nothing was
+ *                    cut. The CLI surfaces this in `mu task add
+ *                    --json` so scripted callers can detect the
+ *                    truncation without grepping stderr.
+ *   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 and (under --json)
+ * to surface `originalSlug` alongside `truncated:true`
+ * (slugifytitle_silently_drops_clauses; task_add_slugify_silently_truncates_ids).
+ */
+interface SlugifyResult {
+    slug: string;
+    strippedLength: number;
+    originalSlug: string;
+    truncated: 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[];
+/**
+ * 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) and to surface the un-truncated
+ * slug in `--json` (task_add_slugify_silently_truncates_ids).
+ *
+ *   id            — the unique-in-workstream task id.
+ *   truncated     — true iff the underlying slugify pass cut real
+ *                   characters (collision-suffixing does NOT flip
+ *                   this).
+ *   originalSlug  — what the slug would have been without the
+ *                   SLUG_SOFT_CAP cut. Equal to `id` when nothing was
+ *                   cut AND no collision suffix was appended; for
+ *                   the truncation-detection use case the only thing
+ *                   the CLI cares about is the lossy-vs-not
+ *                   comparison surfaced via `truncated`.
+ */
+interface IdFromTitleResult {
+    id: string;
+    truncated: boolean;
+    originalSlug: 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;
+/**
+ * Verbose sibling of `idFromTitle`: returns the unique id, the
+ * `truncated` flag from the slugify pass, and the un-truncated
+ * `originalSlug` for `--json` consumers. 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;
 
-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;
+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[];
 }
-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;
+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[];
 }
-/**
- * Release a task: clear `tasks.owner`.
+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` to populate its in-progress slice; exposed as a
+ *  named SDK helper so CLI renderers 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[];
+/** Optional filter knobs for `listNotes`. Default-everything-undefined
+ *  preserves the historical "return every note, oldest-first" shape so
+ *  every existing caller (cmdTaskShow's notes block, exporting.ts's
+ *  bucket renderer, agents.test.ts) keeps working unchanged.
  *
- * 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.
+ *  Filters compose multiplicatively when both apply (`since` AND
+ *  `tail`): the timestamp filter is applied first, then `tail` slices
+ *  the last N of what survived. The CLI surface (`mu task notes
+ *  --tail / --since / --since-claim`) lives in src/cli/tasks/edit.ts;
+ *  the mutex between `--since` and `--since-claim` is a CLI concern,
+ *  not enforced here — if both arrive at the SDK, `since` wins (it's
+ *  the explicit one) and `sinceClaim` is ignored. The auto-resolve
+ *  for `sinceClaim` (look up the most recent `task claim` event in
+ *  agent_logs) happens here so the SDK is self-contained for scripted
+ *  callers. */
+interface ListNotesOptions {
+    /** Print only the last N notes (after any timestamp filter). Must
+     *  be a positive integer; a value of 0 returns no rows but is not
+     *  an error here — CLI-side validation rejects `--tail 0`. */
+    tail?: number;
+    /** ISO-8601 cutoff: only notes with `created_at > since` survive.
+     *  Comparison is lexicographic on the ISO string (matches the way
+     *  the rest of the codebase compares ISO timestamps). */
+    since?: string;
+    /** When true and `since` is unset, look up the `created_at` of the
+     *  most recent `task claim` event for this task and use it as the
+     *  cutoff. Falls back to no filter when no claim event exists
+     *  (equivalent to `--since-beginning`). */
+    sinceClaim?: boolean;
+}
+/** List notes for a task. Operator-facing local_id; resolves to the
+ *  surrogate task id via taskIdFor (with optional workstream scope).
  *
- * 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.
+ *  Optional filters: see {@link ListNotesOptions}. Default behaviour
+ *  (no opts) is unchanged — every note, oldest-first. */
+declare function listNotes(db: Db, taskLocalId: string, workstream: string, opts?: ListNotesOptions): 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 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;
+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;
 }
-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;
+/**
+ * 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[];
+
+declare const WORKSPACE_STALE_THRESHOLD = 10;
+declare function isWorkspaceStale(behind: number | null | undefined): boolean;
+
+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;
+    /** True when the workspace has uncommitted / unstaged / untracked-not-
+     *  ignored files, as observed by the backend's `listDirtyFiles`.
+     *  Undefined when not yet computed (the listWorkspaces fast path leaves
+     *  it unset; call decorateWithDirty to populate). Null when the dirty
+     *  check could not be performed (backend command failure). For jj /
+     *  none backends — which have no operator-visible "dirty" concept —
+     *  this is always false (their listDirtyFiles returns []). */
+    dirty?: boolean | 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[];
 }
 /**
- * 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.
+ * 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.
  *
- * 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).
+ * Maps to exit code 4 (conflict).
  */
-declare function claimTask(db: Db, localId: string, opts: ClaimTaskOptions): Promise<ClaimResult>;
+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[];
+}
 /**
- * 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.
+ * Thrown by createWorkspace when the resolved projectRoot is the
+ * user's $HOME.
  *
- * 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.
+ * Maps to exit code 4 (conflict).
  */
-declare function resolveActorIdentity(): Promise<string>;
-
-interface TaskRow {
-    /** Per-workstream-unique TEXT name. The operator-facing identifier. */
-    name: string;
-    /** Foreign-name reference to the owning workstream. */
+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 WorkspaceStaleness {
+    agentName: string;
     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;
+    commitsBehindMain: number | null;
+    isStale: boolean;
 }
-interface TaskNoteRow {
-    author: string | null;
-    content: string;
-    createdAt: string;
+
+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;
+    /** INTERNAL. When false, suppress the `workspace create` system
+     *  event. Used by `recreateWorkspace` so the audit trail records
+     *  ONE atomic `workspace recreate` line instead of separate
+     *  free + create entries. Defaults to true. */
+    _suppressEvent?: boolean;
 }
-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.
+ * 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 slugifyTitle(title: string): string;
+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[];
+interface FreeWorkspaceOptions {
+    /** If true, attempt to commit pending changes before tearing down.
+     *  Backend-specific; see VcsBackend.freeWorkspace. */
+    commit?: boolean;
+    /** INTERNAL. When false, suppress the `workspace free` system
+     *  event AND skip the pre-mutation snapshot capture. Used by
+     *  `recreateWorkspace` so the audit trail records ONE atomic
+     *  `workspace recreate` line and one snapshot for the whole
+     *  free+create cycle. Defaults to true. */
+    _suppressEvent?: 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;
+}
 /**
- * Result of `slugifyTitleVerbose`: the slug plus enough metadata for
- * the CLI to decide whether to warn the user that meaning was lost.
+ * 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>;
+
+declare function getWorkspaceStaleness(db: Db, agentName: string, workstreamName: string): Promise<WorkspaceStaleness | null>;
+/**
+ * Decorate each row with `commitsBehindMain` by asking the row's backend
+ * how far the parent_ref is behind the project's default branch HEAD.
+ * Cheap, pure observation: NO automatic `git fetch` / `jj git fetch` /
+ * `sl pull`. The number is as fresh as the workspace's local refs cache.
  *
- *   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.
- *   originalSlug   — what the slug WOULD have been without the
- *                    SLUG_SOFT_CAP cut: full stripped slug with the
- *                    same `t_` digit-prefix correction and the same
- *                    SLUG_HARD_CAP ceiling, but no word-boundary
- *                    truncation. Equal to `slug` when nothing was
- *                    cut. The CLI surfaces this in `mu task add
- *                    --json` so scripted callers can detect the
- *                    truncation without grepping stderr.
- *   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.
+ * Returns a NEW array; does not mutate the input. Rows whose parent_ref
+ * is missing, or whose backend's commitsBehind throws / returns null,
+ * get `commitsBehindMain: null`.
+ */
+declare function decorateWithStaleness(rows: readonly WorkspaceRow[]): Promise<WorkspaceRow[]>;
+/**
+ * Decorate every row with a `dirty` marker — true when the backend's
+ * `listDirtyFiles` reports any uncommitted / unstaged / untracked-not-
+ * ignored files; false when clean; null on backend-command failure.
  *
- * The CLI's `mu task add` uses `truncated` to print a one-line stderr
- * hint pointing at the `<id>` positional override and (under --json)
- * to surface `originalSlug` alongside `truncated:true`
- * (slugifytitle_silently_drops_clauses; task_add_slugify_silently_truncates_ids).
+ * Returns a NEW array; does not mutate the input.
  */
-interface SlugifyResult {
-    slug: string;
-    strippedLength: number;
-    originalSlug: string;
-    truncated: boolean;
+declare function decorateWithDirty(rows: readonly WorkspaceRow[]): Promise<WorkspaceRow[]>;
+
+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;
 }
 /**
- * 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).
+ * 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`.
  *
- * Algorithm is byte-for-byte identical to `slugifyTitle`; this just
- * surfaces the metadata that the plain form throws away.
+ * 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 `[]`.
  */
-declare function slugifyTitleVerbose(title: string): SlugifyResult;
+declare function listWorkspaceOrphans(db: Db, workstream: string): WorkspaceOrphan[];
 /**
- * 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.
+ * 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`.
  */
-declare function idFromTitle(db: Db, workstream: string, title: string): string;
+declare function listAllOrphanWorkspaces(db: Db): StrandedWorkspaceOrphan[];
+
+interface RecreateWorkspaceOptions {
+    /** Same as createWorkspace; defaults to cwd. */
+    projectRoot?: string;
+    /** Same as createWorkspace; if undefined the previous backend is
+     *  reused (auto-detection re-runs only when --backend was passed). */
+    backend?: VcsBackendName | VcsBackend;
+    /** Same as createWorkspace; if undefined the new workspace bases on
+     *  the backend's current head (for git/jj/sl: the project's main),
+     *  which is the whole point of the verb. */
+    parentRef?: string;
+    /** When true, skip the dirty-check refusal and discard any
+     *  uncommitted changes in the existing workspace. The lossy escape
+     *  hatch — mirrors the implicit semantics of `mu workspace free`
+     *  without --commit. */
+    force?: boolean;
+}
+interface RecreateWorkspaceResult {
+    /** The freshly-created workspace row (the previous row is already
+     *  gone by the time we return). */
+    workspace: WorkspaceRow;
+    /** parent_ref of the WORKSPACE BEFORE recreate, so callers (and the
+     *  CLI's success message) can show "bumped from <old> -> <new>". */
+    previousParentRef: string | null;
+}
+/**
+ * Free + create in one atomic-ish verb. Between waves the operator
+ * wants the SAME agent name with a fresh workspace pinned to current
+ * main; doing `free` then `create` manually was the dogfood-painful
+ * pattern.
+ */
+declare function recreateWorkspace(db: Db, agent: string, opts: RecreateWorkspaceOptions & {
+    workstream: string;
+}): Promise<RecreateWorkspaceResult>;
+
+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[];
+}
 /**
- * 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) and to surface the un-truncated
- * slug in `--json` (task_add_slugify_silently_truncates_ids).
- *
- *   id            — the unique-in-workstream task id.
- *   truncated     — true iff the underlying slugify pass cut real
- *                   characters (collision-suffixing does NOT flip
- *                   this).
- *   originalSlug  — what the slug would have been without the
- *                   SLUG_SOFT_CAP cut. Equal to `id` when nothing was
- *                   cut AND no collision suffix was appended; for
- *                   the truncation-detection use case the only thing
- *                   the CLI cares about is the lossy-vs-not
- *                   comparison surfaced via `truncated`.
+ * 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).
  */
-interface IdFromTitleResult {
-    id: string;
-    truncated: boolean;
-    originalSlug: string;
+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[];
 }
 /**
- * Verbose sibling of `idFromTitle`: returns the unique id, the
- * `truncated` flag from the slugify pass, and the un-truncated
- * `originalSlug` for `--json` consumers. Collision-suffixing (`_2`,
- * `_3`, …) does not flip `truncated` — the underlying slug's lossiness
- * is what the CLI hint cares about.
+ * 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 function idFromTitleVerbose(db: Db, workstream: string, title: string): IdFromTitleResult;
-declare function getTask(db: Db, localId: string, workstream: string): TaskRow | undefined;
+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[];
+}
 /**
- * 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.
+ * 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 agent adopt <pane-id>` to register, or use --for to pick a
+ * different agent).
+ *
+ * Maps to exit code 4 (conflict) via the cli.ts handler.
  */
-interface ListTasksOptions {
-    /** Filter to one or more lifecycle statuses. Omitted = all statuses. */
-    status?: TaskStatus | readonly TaskStatus[];
+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 agent adopt: registration pattern (promote pane to worker)
+     */
+    errorNextSteps(): NextStep[];
 }
-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 class CycleError extends Error implements HasNextSteps {
+    readonly from: string;
+    readonly to: string;
+    readonly name = "CycleError";
+    constructor(from: string, to: string);
+    errorNextSteps(): NextStep[];
 }
-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[];
-/** Optional filter knobs for `listNotes`. Default-everything-undefined
- *  preserves the historical "return every note, oldest-first" shape so
- *  every existing caller (cmdTaskShow's notes block, exporting.ts's
- *  bucket renderer, agents.test.ts) keeps working unchanged.
- *
- *  Filters compose multiplicatively when both apply (`since` AND
- *  `tail`): the timestamp filter is applied first, then `tail` slices
- *  the last N of what survived. The CLI surface (`mu task notes
- *  --tail / --since / --since-claim`) lives in src/cli/tasks/edit.ts;
- *  the mutex between `--since` and `--since-claim` is a CLI concern,
- *  not enforced here — if both arrive at the SDK, `since` wins (it's
- *  the explicit one) and `sinceClaim` is ignored. The auto-resolve
- *  for `sinceClaim` (look up the most recent `task claim` event in
- *  agent_logs) happens here so the SDK is self-contained for scripted
- *  callers. */
-interface ListNotesOptions {
-    /** Print only the last N notes (after any timestamp filter). Must
-     *  be a positive integer; a value of 0 returns no rows but is not
-     *  an error here — CLI-side validation rejects `--tail 0`. */
-    tail?: number;
-    /** ISO-8601 cutoff: only notes with `created_at > since` survive.
-     *  Comparison is lexicographic on the ISO string (matches the way
-     *  the rest of the codebase compares ISO timestamps). */
-    since?: string;
-    /** When true and `since` is unset, look up the `created_at` of the
-     *  most recent `task claim` event for this task and use it as the
-     *  cutoff. Falls back to no filter when no claim event exists
-     *  (equivalent to `--since-beginning`). */
-    sinceClaim?: boolean;
+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[];
+}
+
+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;
 }
-/** List notes for a task. Operator-facing local_id; resolves to the
- *  surrogate task id via taskIdFor (with optional workstream scope).
- *
- *  Optional filters: see {@link ListNotesOptions}. Default behaviour
- *  (no opts) is unchanged — every note, oldest-first. */
-declare function listNotes(db: Db, taskLocalId: string, workstream: string, opts?: ListNotesOptions): 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.
+ * 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.
  */
-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;
+interface EvidenceOption {
+    evidence?: string;
 }
 /**
- * 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`.
+ * 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 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[];
+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;
+    /** Optional actor identity attributed to the synthetic `CLOSE: …`
+     *  note auto-inserted when `evidence` is non-empty (see closeTask
+     *  body). The CLI resolves this via `resolveActorIdentity()` so the
+     *  note carries the closing worker's name; SDK callers (tests,
+     *  internal use) may omit it (the note then carries no author, same
+     *  as a bare `addNote` without `--author`). Surfaced in mufeedback
+     *  task_close_evidence_does_not_append_the. */
+    author?: 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;
+/** 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[];
 }
-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[];
+/** 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;
 }
-/**
- * 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;
+interface ReleaseTaskOptions extends EvidenceOption {
+    /** Workstream context for the task (v5: tasks.local_id is
+     *  per-workstream unique). */
     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[];
+    /** 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;
 }
 /**
- * Atomically create a task and (optionally) its incoming blocked-by
- * edges.
+ * Release a task: clear `tasks.owner`.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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 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. */
+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;
 }
-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;
+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;
 }
 /**
- * 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.
+ * Claim a task. Two modes:
  *
- * 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).
+ *   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.
  *
- * 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).
+ *   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.
  *
- * 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.
+ * Status side-effect: OPEN -> IN_PROGRESS; IN_PROGRESS / CLOSED unchanged.
  *
- * 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.
+ * 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 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;
-}
+declare function claimTask(db: Db, localId: string, opts: ClaimTaskOptions): Promise<ClaimResult>;
 /**
- * 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.
+ * Resolve the current actor's identity for attribution in task notes,
+ * --self claims, and any other write that wants 'who did this?'.
  *
- * 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.
+ * 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 getParallelTracks(db: Db, workstream: string): Track[];
+declare function resolveActorIdentity(): Promise<string>;
 
-/** 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.
- *  Manifests without `bucketVersion: 2` fall through to the
- *  `corrupt` lane in `readManifest`. */
-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. */
+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;
-    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 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 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;
+interface TaskWaitResult {
+    /** Per-task state at exit time. Same length and order as the input
+     *  list. The caller derives all-reached / any-reached / elapsed
+     *  from this list (count `r.reachedTarget`) and from its own
+     *  startedAt clock — keeping the SDK return minimal. */
+    refs: TaskWaitTaskState[];
+    /** True when we exited because of the timeout, not because the wait
+     *  condition was met. Refs that did reach the target are still
+     *  reflected in `refs[i].reachedTarget` on partial-progress timeout. */
+    timedOut: boolean;
 }
 /**
- * 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.
+ * 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).
  *
- * 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.
+ * 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 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;
+declare function waitForTasks(db: Db, input: readonly TaskWaitRef[] | readonly string[], opts: TaskWaitOptions): Promise<TaskWaitResult>;
+
+interface FullDag {
+    /** Root tasks: no incoming `blocks` edge (no blockers). */
+    roots: TaskRow[];
+    /** Edges map parent task name → child task names (what parent blocks). */
+    edges: Map<string, string[]>;
+    /** All tasks in the workstream, keyed by operator-facing name. */
+    tasks: Map<string, TaskRow>;
 }
-interface ExportArchiveResult extends RenderBucketResult {
-    archiveLabel: string;
-    /** Number of source workstreams the renderer wrote / refreshed. */
-    sourceCount: number;
+type TaskStatusLabelFn = (task: TaskRow) => string;
+interface RenderTreeOptions {
+    /** Include the task title after the name + status label. Default: true. */
+    includeTitle?: boolean;
 }
-/** 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[];
+interface LoadFullDagOptions {
+    /** Optional visible-status filter. Omitted = every task status. */
+    statuses?: ReadonlySet<TaskStatus>;
 }
+declare function loadFullDag(db: Db, workstream: string, opts?: LoadFullDagOptions): FullDag;
 /**
- * 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).
+ * Render a DAG forest in the same ASCII shape as `mu task tree --down`:
+ * each root is printed as a header node, dependents are below it, and
+ * DAG diamonds collapse after the first full subtree render with a
+ * one-line recurrence marker.
  */
-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;
+declare function renderForest(roots: readonly TaskRow[], edges: ReadonlyMap<string, readonly string[]>, statusFn: TaskStatusLabelFn, tasksByName?: ReadonlyMap<string, TaskRow>, opts?: RenderTreeOptions): string;
+declare function renderTaskTree(db: Db, workstream: string, root: TaskRow, direction: "blockers" | "dependents", statusFn: TaskStatusLabelFn, opts?: RenderTreeOptions): string;
+
+declare class DbReplayWorkstreamMissingError extends Error implements HasNextSteps {
+    readonly workstream: string;
+    readonly name = "DbReplayWorkstreamMissingError";
+    constructor(workstream: string);
+    errorNextSteps(): NextStep[];
 }
-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 DbReplayTaskConflict {
+    localId: string;
+    local: {
+        title: string;
+        status: string;
+    };
+    sidecar: {
+        title: string;
+        status: string;
+    };
+}
+declare class DbReplayLocalIdConflictError extends Error implements HasNextSteps {
+    readonly workstream: string;
+    readonly conflicts: readonly DbReplayTaskConflict[];
+    readonly name = "DbReplayLocalIdConflictError";
+    constructor(workstream: string, conflicts: readonly DbReplayTaskConflict[]);
+    errorNextSteps(): NextStep[];
 }
-interface WorkspaceFailure {
-    agent: string;
-    backend: string;
-    path: string;
-    error: string;
+interface ReplayDbOptions {
+    apply?: boolean;
+    tasks?: readonly string[];
+    notes?: readonly string[];
+    all?: boolean;
 }
-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;
+interface DbReplayTaskItem {
+    localId: string;
+    title: string;
+    status: string;
+    impact: number;
+    effortDays: number;
+    createdAt: string;
+    updatedAt: string;
 }
-/**
- * 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 DbReplayNoteItem {
+    taskLocalId: string;
+    author: string | null;
+    content: string;
+    createdAt: string;
+    hash: 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;
+interface DbReplayEdgeItem {
+    fromLocalId: string;
+    toLocalId: string;
+    createdAt: string;
 }
-/**
- * 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.
- *
- */
-declare function exportWorkstream(db: Db, opts: ExportWorkstreamOptions): ExportResult;
+interface DbReplayPlan {
+    sourceFile: string;
+    workstream: string;
+    tasks: DbReplayTaskItem[];
+    notes: DbReplayNoteItem[];
+    edges: DbReplayEdgeItem[];
+    conflicts: DbReplayTaskConflict[];
+}
+interface DbReplayResult extends DbReplayPlan {
+    dryRun: boolean;
+    applied: boolean;
+    snapshotId?: number;
+    added: {
+        tasks: number;
+        notes: number;
+        edges: number;
+    };
+    warnings: string[];
+}
+declare function replayDb(db: Db, file: string, opts?: ReplayDbOptions): DbReplayResult;
+declare function buildReplayPlan(localDb: Db, sidecarDb: Db, sourceFile: string): DbReplayPlan;
 
-declare class ImportBucketInvalidError extends Error implements HasNextSteps {
-    readonly bucketDir: string;
-    readonly reason: string;
-    readonly name = "ImportBucketInvalidError";
-    constructor(bucketDir: string, reason: string);
+interface DbExportManifestWorkstream {
+    name: string;
+    tasks: number;
+    edges: number;
+    notes: number;
+    latestSeq: number;
+}
+interface DbExportManifest {
+    muVersion: string;
+    schemaVersion: number;
+    machineId: string;
+    hostname: string | null;
+    exportedAt: string;
+    workstreams: DbExportManifestWorkstream[];
+}
+interface ExportDbOptions {
+    force?: boolean;
+}
+interface ExportDbResult {
+    file: string;
+    manifestPath: string;
+    manifest: DbExportManifest;
+    overwritten: boolean;
+}
+declare class DbExportTargetExistsError extends Error implements HasNextSteps {
+    readonly file: string;
+    readonly name = "DbExportTargetExistsError";
+    constructor(file: string);
     errorNextSteps(): NextStep[];
 }
-declare class WorkstreamAlreadyExistsError extends Error implements HasNextSteps {
-    readonly workstream: string;
-    readonly name = "WorkstreamAlreadyExistsError";
-    constructor(workstream: string);
+declare class DbImportManifestMissingError extends Error implements HasNextSteps {
+    readonly manifestPath: string;
+    readonly name = "DbImportManifestMissingError";
+    constructor(manifestPath: 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);
+declare class DbImportSchemaTooOldError extends Error implements HasNextSteps {
+    readonly sourceVersion: number;
+    readonly name = "DbImportSchemaTooOldError";
+    constructor(sourceVersion: number);
     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");
+declare class DbImportSchemaTooNewError extends Error implements HasNextSteps {
+    readonly sourceVersion: number;
+    readonly name = "DbImportSchemaTooNewError";
+    constructor(sourceVersion: number);
     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;
+declare class DbImportSourceStaleError extends Error implements HasNextSteps {
+    readonly workstreams: readonly string[];
+    readonly name = "DbImportSourceStaleError";
+    constructor(workstreams: readonly string[]);
+    errorNextSteps(): NextStep[];
 }
-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[];
+declare class DbImportConflictError extends Error implements HasNextSteps {
+    readonly workstreams: readonly string[];
+    readonly name = "DbImportConflictError";
+    constructor(workstreams: readonly string[]);
+    errorNextSteps(): NextStep[];
+}
+type DbImportDecision = "IDENTICAL" | "FAST_FORWARD" | "LOCAL_AHEAD" | "CONFLICT" | "IMPORT" | "LEAVE_ALONE";
+interface DbImportSummaryItem {
+    workstream: string;
+    decision: DbImportDecision;
+    delta: Record<string, unknown>;
+    needs?: string;
+    parkPath?: string;
+}
+interface ImportDbOptions {
+    apply?: boolean;
+    forceSource?: boolean;
+    onlyWorkstreams?: readonly string[];
+}
+interface ImportDbResult {
+    machineId: string;
+    sourceFile: string;
+    dryRun: boolean;
+    applied: boolean;
+    snapshotId?: number;
+    summary: DbImportSummaryItem[];
+}
+declare function exportDb(db: Db, file: string, opts?: ExportDbOptions): ExportDbResult;
+declare function importDb(db: Db, file: string, opts?: ImportDbOptions): ImportDbResult;
+declare function buildImportPlan(localDb: Db, manifest: DbExportManifest, sourceFile: string, onlyWorkstreams?: readonly string[]): DbImportSummaryItem[];
+
+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;
 }
 /**
- * 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.
+ * 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.
  *
- * Throws on unrecoverable bucket-level errors (no manifest,
- * --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.
+ * 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 importBucket(db: Db, opts: ImportBucketOptions): ImportBucketResult;
+declare function getParallelTracks(db: Db, workstream: string): Track[];
 
-interface WorkspaceRow {
-    agentName: string;
-    workstreamName: string;
-    backend: VcsBackendName;
+declare const EXPORT_MANIFEST_VERSION = 2;
+/** One per-task summary inside a per-source-ws section of the manifest. */
+interface ExportTaskEntry {
+    /** Task local_id == filename stem (`<id>.md`). Kept for v1 manifest compatibility. */
+    id: string;
+    /** Task local_id, duplicated under the operator-facing SDK name so bucket INDEX can render from manifest alone. */
+    name: string;
+    /** Compact summary fields needed for bucket-level INDEX.md without re-reading the DB. */
+    title: string;
+    status: TaskRow["status"];
+    impact: number;
+    effortDays: number;
+    /** Path relative to the bucket root (e.g. `auth/tasks/design.md`). */
     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;
+    /** 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;
 }
-declare class WorkspaceExistsError extends Error implements HasNextSteps {
-    readonly agent: string;
-    readonly name = "WorkspaceExistsError";
-    constructor(agent: string);
-    errorNextSteps(): NextStep[];
+/** 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[];
 }
-declare class WorkspaceNotFoundError extends Error implements HasNextSteps {
-    readonly agent: string;
-    readonly name = "WorkspaceNotFoundError";
-    constructor(agent: string);
-    errorNextSteps(): NextStep[];
+/** Top-level bucket manifest. `bucketVersion: 2` — the v0.3 disk layout.
+ *  `manifest_version` is the schema of the manifest JSON payload itself:
+ *  v1 lacked task summaries, v2 stores enough per-task data to render
+ *  bucket INDEX.md from `manifest.sources` alone. Manifests without
+ *  `bucketVersion: 2` fall through to the `corrupt` lane in `readManifest`. */
+interface ExportManifest {
+    /** Disk-layout discriminator. Always 2 in this codebase. */
+    bucketVersion: 2;
+    /** Manifest-payload discriminator. Always 2 when written by this codebase. */
+    manifest_version: typeof EXPORT_MANIFEST_VERSION;
+    /** 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>;
 }
-/**
- * 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[];
+/** 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 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).
+ * 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.
  *
- * Maps to exit code 4 (conflict).
+ * 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 class HomeDirAsProjectRootError extends Error implements HasNextSteps {
-    readonly agent: string;
+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 WorkstreamExistsError extends Error implements HasNextSteps {
     readonly workstream: string;
-    readonly homeDir: string;
-    readonly name = "HomeDirAsProjectRootError";
-    constructor(agent: string, workstream: string, homeDir: string);
+    readonly name: string;
+    constructor(workstream: 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;
+declare class WorkstreamNameInvalidError extends Error implements HasNextSteps {
+    readonly attempted: string;
+    readonly name = "WorkstreamNameInvalidError";
+    constructor(attempted: string);
+    errorNextSteps(): NextStep[];
 }
 /**
- * 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`.
+ * 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).
  *
- * 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.
+ * 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.
  *
- * 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.
+ * Returns true iff a row was actually inserted (vs. already present).
  */
-declare function listAllOrphanWorkspaces(db: Db): StrandedWorkspaceOrphan[];
-interface CreateWorkspaceOptions {
+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;
-    /** 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;
-    /** INTERNAL. When false, suppress the `workspace create` system
-     *  event. Used by `recreateWorkspace` so the audit trail records
-     *  ONE atomic `workspace recreate` line instead of separate
-     *  free + create entries. Defaults to true. */
-    _suppressEvent?: boolean;
+    /** 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;
+}
+interface DestroyWorkstreamOptions extends WorkstreamOptions {
+    /** Skip the per-workstream pre-mutation snapshot because the caller
+     *  already captured a broader snapshot for the whole destructive
+     *  operation. Used by `mu workstream destroy --empty` after its
+     *  sweep-level safety snapshot; direct destroy callers leave this
+     *  false so the default safety net is unchanged. */
+    suppressSnapshot?: boolean;
 }
 /**
- * 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.
+ * 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 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;
-    /** INTERNAL. When false, suppress the `workspace free` system
-     *  event AND skip the pre-mutation snapshot capture. Used by
-     *  `recreateWorkspace` so the audit trail records ONE atomic
-     *  `workspace recreate` line and one snapshot for the whole
-     *  free+create cycle. Defaults to true. */
-    _suppressEvent?: 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;
-}
+declare function listWorkstreams(db: Db): Promise<WorkstreamSummary[]>;
+declare function summarizeWorkstream(db: Db, opts: WorkstreamOptions): Promise<WorkstreamSummary>;
 /**
- * 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).
+ * 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 freeWorkspace(db: Db, agent: string, opts: FreeWorkspaceOptions & {
+declare function destroyWorkstream(db: Db, opts: DestroyWorkstreamOptions): Promise<DestroyResult>;
+interface ExportWorkstreamOptions {
     workstream: string;
-}): Promise<FreeWorkspaceResult>;
-interface RecreateWorkspaceOptions {
-    /** Same as createWorkspace; defaults to cwd. */
-    projectRoot?: string;
-    /** Same as createWorkspace; if undefined the previous backend is
-     *  reused (auto-detection re-runs only when --backend was passed). */
-    backend?: VcsBackendName | VcsBackend;
-    /** Same as createWorkspace; if undefined the new workspace bases on
-     *  the backend's current head (for git/jj/sl: the project's main),
-     *  which is the whole point of the verb. */
-    parentRef?: string;
-    /** When true, skip the dirty-check refusal and discard any
-     *  uncommitted changes in the existing workspace. The lossy escape
-     *  hatch — mirrors the implicit semantics of `mu workspace free`
-     *  without --commit. */
-    force?: boolean;
+    /** 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 RecreateWorkspaceResult {
-    /** The freshly-created workspace row (the previous row is already
-     *  gone by the time we return). */
-    workspace: WorkspaceRow;
-    /** parent_ref of the WORKSPACE BEFORE recreate, so callers (and the
-     *  CLI's success message) can show "bumped from <old> -> <new>". */
-    previousParentRef: string | null;
+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;
 }
 /**
- * Free + create in one atomic-ish verb. The whole point: between
- * waves the operator wants the SAME agent name with a fresh workspace
- * pinned to current main; doing `free` then `create` manually was the
- * dogfood-painful pattern (mufeedback note add_mu_workspace_recreate_free_create).
- *
- * Behaviour:
- *   - Refuses with WorkspaceDirtyError if the existing workspace has
- *     uncommitted changes (git/sl), UNLESS `force: true` is passed
- *     (lossy escape hatch). jj is always-snapshotted so dirty is never
- *     an issue; `none` has no VCS to consult so it never refuses.
- *   - Reuses the SAME backend the previous workspace had unless
- *     `backend` is explicitly overridden — a between-wave refresh
- *     should not silently swap from git to none because the operator
- *     happened to cd into a non-VCS dir. The override path matches
- *     `mu workspace create --backend ...` semantics.
- *   - Emits ONE `workspace recreate <agent>` event (with both old and
- *     new parent_ref in the payload) instead of separate free + create
- *     events. One pre-mutation snapshot is captured under the same
- *     label so the undo trail shows one step.
- *
- * Throws:
- *   - WorkspaceNotFoundError    — no row for this (agent, workstream).
- *   - AgentNotFoundError        — propagated from createWorkspace's
- *                                 typed agent check (the agent row
- *                                 was deleted between the lookup and
- *                                 the re-INSERT; vanishingly rare).
- *   - WorkspaceDirtyError       — dirty + !force.
- *   - any backend-level Error   — free or create failed.
- *
- * On a free-side failure the row + on-disk dir are best-effort gone;
- * on a create-side failure we surface the create error and the row is
- * already deleted (the operator can re-run `mu workspace create`).
+ * 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.
+ *
  */
-declare function recreateWorkspace(db: Db, agent: string, opts: RecreateWorkspaceOptions & {
-    workstream: string;
-}): Promise<RecreateWorkspaceResult>;
+declare function exportWorkstream(db: Db, opts: ExportWorkstreamOptions): ExportResult;
 
 type LogKind = "message" | "event" | "broadcast" | string;
 interface LogRow {
@@ -3314,7 +3408,7 @@ declare function listLogs(db: Db, opts?: ListLogsOptions): LogRow[];
  * 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;
+declare function latestSeq(db: Db, workstreamId?: number): number;
 /**
  * One-line helper for state-changing SDK functions to auto-emit a
  * `kind='event'` log entry. Called AFTER the mutation succeeds, only
@@ -3325,6 +3419,213 @@ declare function latestSeq(db: Db): number;
  * by callers like `claimTask` (source = the claiming agent).
  */
 declare function emitEvent(db: Db, workstream: string | null, payload: string, source?: string): void;
+/**
+ * Canonical list of two-token verb prefixes that `emitEvent` callers
+ * use as the leading words of a payload. Single source of truth for
+ * event renderers so they can never drift away from the actual emitter
+ * sites.
+ *
+ * Maintenance contract: when you add an `emitEvent(...)` call whose
+ * payload starts with a new two-word verb, add the verb here. A
+ * regression test walks every entry and asserts the classifier
+ * recognises it; the test fails if you add an emitter without adding
+ * its verb here.
+ *
+ * Audit (2026-05): every `emitEvent` callsite under src/ produces a
+ * payload that starts with one of these. Verified by
+ * `grep -rn emitEvent src/ | grep -v import`.
+ */
+declare const EVENT_VERB_PREFIXES: readonly string[];
+interface ClassifiedEvent {
+    /** One of EVENT_VERB_PREFIXES. */
+    verb: string;
+    /** Payload past the verb token; preserves leading separator (" " or "\t"). */
+    rest: string;
+}
+/**
+ * Match `payload` against EVENT_VERB_PREFIXES. Returns {verb, rest} on
+ * match; null otherwise. The verb-boundary check is `next is space, tab,
+ * or end-of-string` so we don't false-match e.g. `task addnote`.
+ *
+ * Pure parser. Consumers (the static state card, the ink Activity-log
+ * card) apply their own colour to `verb` after matching.
+ */
+declare function classifyEventVerb(payload: string): ClassifiedEvent | null;
+
+type DoctorStatus = "ok" | "warn" | "fail";
+interface DoctorCheck {
+    /** Short, stable identifier — used as the row label. Lowercase
+     *  one-word tokens so the column-aligned card layout looks tidy. */
+    name: string;
+    status: DoctorStatus;
+    /** Free-form prose for the row's right-hand column. Kept short so
+     *  the card's CLIP column doesn't truncate it on common widths. */
+    detail: string;
+}
+interface DoctorSummary {
+    /** Every check that ran, in stable display order. The card filters
+     *  to non-OK rows for its body but keeps the OK rows so the popup
+     *  (when it ships under feat_more_cards_umbrella) can render the
+     *  full list. */
+    checks: readonly DoctorCheck[];
+    /** Convenience: how many rows are warn or fail. Card subtitle
+     *  reads this directly. Pure derivation from `checks`. */
+    problemCount: number;
+}
+/**
+ * Compute the doctor summary for a workstream. Pure-ish: runs cheap
+ * synchronous DB queries + reads from the supplied snapshot. Callers
+ * that don't want to compute a snapshot first (or are running inside
+ * `loadWorkstreamSnapshot` mid-build) can omit `snapshot` — the
+ * snapshot-derived checks (ghosts / orphans / workspace-orphans) are
+ * skipped in that case.
+ */
+declare function loadDoctorSummary(db: Db, snapshot: WorkstreamSnapshot | null): DoctorSummary;
+/** Count of warn + fail rows. Pure; exported for unit tests. */
+declare function countProblems(checks: readonly DoctorCheck[]): number;
+/**
+ * Return the full check array (OK + warn + fail) in stable display
+ * order. Used by the TUI's slot-9 Doctor popup
+ * (feat_popup_9_doctor, workstream `tui-impl`) which renders every
+ * row — not just the non-OK subset Card 9 surfaces.
+ *
+ * Thin wrapper over `loadDoctorSummary` so the SDK seam stays
+ * single: `loadDoctorSummary` is the source of truth for the
+ * check vocabulary, and the popup's `loadDoctorChecks` view is
+ * just `.checks`. Pure-ish (same cheap synchronous DB reads as
+ * `loadDoctorSummary`).
+ */
+declare function loadDoctorChecks(db: Db, snapshot: WorkstreamSnapshot | null): readonly DoctorCheck[];
+/**
+ * Map a check row to the most useful informational command the
+ * operator might paste. Read-only by construction: `mu agent list`,
+ * `mu workspace orphans`, `mu doctor` are all SELECT-shape verbs;
+ * `# ...` lines are visibly inert. Per the slot-9 popup spec KEY
+ * MAP block this is INFORMATIONAL, never a mutating recipe — so
+ * even when the check is `fail`, we yank the diagnostic verb the
+ * operator should RUN MANUALLY, not a fix command.
+ *
+ * Pure; exported for unit tests + SDK reuse.
+ */
+declare function yankCommandForCheck(check: Pick<DoctorCheck, "name" | "status">): string;
+/**
+ * A short paragraph (one paragraph per check name) explaining the
+ * shape of the failure / warning. Returned as a `readonly string[]`
+ * so the popup's drill body can interleave the lines with other
+ * content; CLI consumers can `.join("\n")` themselves.
+ *
+ * Pure; exported for unit tests + SDK reuse.
+ */
+declare function remediationParagraph(check: DoctorCheck): readonly string[];
+
+interface WorkstreamSnapshot {
+    workstreamName: string;
+    view: LiveAgentsView;
+    tracks: Track[];
+    ready: TaskRow[];
+    inProgress: TaskRow[];
+    blocked: TaskRow[];
+    recentClosed: TaskRow[];
+    /** Populated only when callers explicitly pass `withAllTasks: true`.
+     *  The TUI dashboard fast tick leaves this empty and the all-tasks
+     *  popup reads its exhaustive list directly from SQLite while open. */
+    allTasks: TaskRow[];
+    workspaces: WorkspaceRow[];
+    workspaceOrphans: WorkspaceOrphan[];
+    recent: LogRow[];
+    /** Last N commits from the project root (process.cwd()), populated
+     *  when `loadWorkstreamSnapshot` is called with withRecentCommits.
+     *  This is intentionally NOT a per-agent workspace log. */
+    recentCommits: CommitSummary[];
+    /** Backend that produced recentCommits. Null when recent commits were
+     *  not requested or no VCS backend was detected. */
+    commitsBackend?: VcsBackendName | null;
+    /** Populated when `loadWorkstreamSnapshot` is called with
+     *  `withDoctor: true`. Used by the TUI's slot-9 Doctor card to
+     *  render a glanceable health badge on the dashboard
+     *  (feat_card_9_doctor, workstream `tui-impl`). The static `mu
+     *  state` card and `mu doctor` itself don't consume it — they
+     *  read the textual doctor card directly. Null when not requested. */
+    doctor: DoctorSummary | null;
+}
+interface LoadWorkstreamSnapshotOptions {
+    /** Recent-events cap (default 200). */
+    eventLimit?: number;
+    /** When true, slow snapshot loading also populates `WorkspaceRow.dirty`
+     *  via decorateWithDirty (one `git status --porcelain` shellout per row,
+     *  capped at DECORATE_CONCURRENCY). The TUI caches this slow-tier value
+     *  and merges it into every fast SQL tick. */
+    withDirty?: boolean;
+    /** When true, slow snapshot loading also populates
+     *  `WorkstreamSnapshot.doctor` via `loadDoctorSummary`. The summary is
+     *  cheap SQL, but it reports tmux/workspace drift from slow-tier fields,
+     *  so the TUI refreshes it with the subprocess tier. */
+    withDoctor?: boolean;
+    /** Optional full task list for the TUI all-tasks popup. */
+    withAllTasks?: true;
+    /** Optional recent-project-commits slice for the TUI Commits card /
+     *  popup. Uses process.cwd() as the project root on purpose: the TUI
+     *  is launched from the project checkout, while worker workspaces live
+     *  elsewhere under the mu state dir. */
+    withRecentCommits?: {
+        limit: number;
+    };
+}
+interface WorkstreamSnapshotSlowFields {
+    view: LiveAgentsView;
+    /** Workspace rows decorated with slow-tier VCS observations
+     *  (`commitsBehindMain`, and `dirty` when requested). */
+    workspaces: WorkspaceRow[];
+    recentCommits: CommitSummary[];
+    commitsBackend?: VcsBackendName | null;
+    doctor: DoctorSummary | null;
+}
+/**
+ * Fast TUI/state snapshot tier: pure SQLite reads only. Subprocess-backed
+ * fields are intentionally empty placeholders so callers can merge the last
+ * slow-tier values without blocking a 1s render tick on tmux or VCS probes.
+ */
+declare function loadWorkstreamSnapshotFast(db: Db, workstream: string, opts?: LoadWorkstreamSnapshotOptions): Promise<WorkstreamSnapshot>;
+/**
+ * Slow snapshot tier: fields backed by tmux / VCS subprocess probes (plus
+ * doctor, which reports over those slow-tier observations). Returns only the
+ * fields the fast snapshot deliberately leaves empty or undecorated.
+ *
+ * status-only refresh: don't prune mid-spawn placeholders or reap
+ * unreachable agents — every render-mode is a polling read surface.
+ */
+declare function loadWorkstreamSnapshotSlow(db: Db, workstream: string, opts?: LoadWorkstreamSnapshotOptions, baseSnapshot?: WorkstreamSnapshot): Promise<WorkstreamSnapshotSlowFields>;
+/** Merge the latest slow-tier subprocess observations into a fresh fast tier. */
+declare function mergeSnapshotFastSlow(fast: WorkstreamSnapshot, slow: WorkstreamSnapshotSlowFields | null): WorkstreamSnapshot;
+/**
+ * Back-compat wrapper for non-TUI callers: return the historical union shape
+ * by composing the new fast SQL tier with one slow subprocess tier.
+ */
+declare function loadWorkstreamSnapshot(db: Db, workstream: string, opts?: LoadWorkstreamSnapshotOptions): Promise<WorkstreamSnapshot>;
+/**
+ * ROI tiers used to colour task rows. Pure: returns the bucket name; the
+ * consumer maps bucket → picocolors function (or ink text colour).
+ * Magic numbers (≥100 high, ≥50 mid) lifted from the previous HUD impl.
+ */
+type RoiBucket = "high" | "mid" | "low" | "infinite";
+declare function roiBucket(impact: number, effortDays: number): RoiBucket;
+/** Histogram of agents by status. Pure derivation (no colour render). */
+declare function agentStatusHistogram(agents: readonly AgentRow[]): ReadonlyMap<AgentStatus, number>;
+interface OwnedTasksSummary {
+    /** Display token: "—" (none) | "<task_id>" (one) | "⊕<N>" (many). */
+    bit: string;
+    /** Underlying count for callers that want their own format. */
+    count: number;
+    /** The single owned task's local id, when count===1. */
+    onlyTaskId?: string;
+}
+/**
+ * Per-agent task summary: condensed display token + raw count. Used by
+ * both the static Agents table and the ink Agents card. Pure on the
+ * input rows — caller (e.g. loadWorkstreamSnapshot consumer) does the
+ * listTasksByOwner query upstream and feeds the rows in.
+ */
+declare function summarizeOwnedTasks(owned: readonly TaskRow[]): OwnedTasksSummary;
 
 interface SnapshotRow {
     /** Operator-facing snapshot id. EXCEPTION to the no-surrogate-ids rule:
@@ -3368,13 +3669,6 @@ declare class SnapshotNotFoundError extends Error implements HasNextSteps {
     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;
@@ -3383,11 +3677,6 @@ declare class SnapshotVersionMismatchError extends Error implements HasNextSteps
     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;
@@ -3395,169 +3684,47 @@ declare class SnapshotFileMissingError extends Error implements HasNextSteps {
     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 isStaleVersion(row: {
+    schemaVersion: number;
+}): boolean;
+declare function snapshotFileSize(snapshot: SnapshotRow): number | null;
+
 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, AgentSpawnCliNotFoundError, AgentSpawnStartupError, 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, type CommandResolutionResult, type CommandResolver, 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, type ImportSourceResult, type InsertAgentInput, type KickAgentOptions, type KickAgentResult, type KickProcessExecutor, type KickSignal, type ListArchivedTasksOptions, type ListLiveAgentsOptions, type ListLogsOptions, type ListNotesOptions, type ListReadyOptions, type ListSnapshotsOptions, type ListTasksOptions, type LiveAgentsView, type LogKind, type LogRow, type NewSessionOptions, type NewWindowOptions, NoForegroundProcessError, 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 RecreateWorkspaceOptions as WorkspaceRecreateOptions, type RecreateWorkspaceResult as WorkspaceRecreateResult, type WorkspaceRow, WorkstreamAlreadyExistsError, WorkstreamNameInvalidError, type WorkstreamOptions, type WorkstreamSummary, addBlockEdge, addNote, addTask, addToArchive, adoptAgent, appendLog, assertValidPaneId, backendByName, capturePane, captureSnapshot, checkCommandResolvable, claimTask, closeAgent, closeTask, composeAgentTitle, createArchive, createWorkspace, currentAgentName, currentPaneTitle, decorateWithStaleness, defaultDbPath, defaultSendDelayMs, defaultSpawnLivenessMs, defaultStateDir, deferTask, deleteAgent, deleteArchive, deleteSnapshot, deleteTask, destroyWorkstream, detectBackend, detectPiStatus, emitEvent, ensureWorkstream, ensureWorkstreamStateDir, envVarNameForCli, exportArchive, exportSourceForWorkstream, exportSourcesForArchive, exportWorkstream, extractTail, foregroundPgid, freeAgent, freeWorkspace, gcMaxAgeDays, gcMaxCount, gcSnapshots, getAgent, getAgentByPane, getArchive, getParallelTracks, getPrerequisites, getTask, getTaskEdges, getTaskEdgesWithStatus, getWaitPollCount, getWorkspaceForAgent, gitBackend, idFromTitle, idFromTitleVerbose, importBucket, insertAgent, isKickSignal, isStaleVersion, isTaskStatus, isValidAgentName, isValidArchiveLabel, isValidPaneId, isValidTaskId, isValidWorkstreamName, jjBackend, kickAgent, 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, paneTTY, parseAgentNameFromTitle, parsePsTtyOutput, pruneSnapshots, readAgent, reconcile, recreateWorkspace, refreshAgentTitle, rejectTask, releaseTask, removeBlockEdge, removeFromArchive, renderToBucket, reparentTask, resetCommandResolverForTests, resetKickProcessExecutor, resetSleep, resetTmuxExecutor, resetWaitPollCount, resolveActorIdentity, resolveCliCommand, resolveCliCommandWithSource, restoreSnapshot, searchArchives, searchTasks, selectLayout, sendToAgent, sendToPane, sessionExists, setCommandResolverForTests, setKickProcessExecutor, 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 };
+declare function restoreSnapshot(db: Db, snapshotId: number): RestoreSnapshotResult;
+
+export { type AddNoteOptions, type AddTaskOptions, type AddToArchiveResult, type AdoptAgentOptions, type AdoptAgentResult, AgentDiedOnSpawnError, AgentExistsError, AgentNotFoundError, AgentNotInWorkstreamError, type AgentRow, AgentSpawnCliNotFoundError, AgentSpawnStartupError, type AgentStatus, type AppendLogOptions, type Archive, ArchiveAlreadyExistsError, ArchiveLabelInvalidError, ArchiveNotFoundError, type ArchiveSearchHit, ArchiveSourceAmbiguousError, type ArchiveSourceSummary, type ArchiveSummary, type ArchivedTaskRow, type BlockEdgeResult, CURRENT_SCHEMA_VERSION, type CaptureOptions, type CaptureSnapshotResult, type ClaimResult, type ClaimTaskOptions, ClaimerNotRegisteredError, type ClassifiedEvent, type CloseAgentOptions, type CloseAgentResult, type CommandResolutionResult, type CommandResolver, CrossWorkstreamEdgeError, CycleError, type Db, type DbExportManifest, type DbExportManifestWorkstream, DbExportTargetExistsError, DbImportConflictError, type DbImportDecision, DbImportManifestMissingError, DbImportSchemaTooNewError, DbImportSchemaTooOldError, DbImportSourceStaleError, type DbImportSummaryItem, type DbReplayEdgeItem, DbReplayLocalIdConflictError, type DbReplayNoteItem, type DbReplayPlan, type DbReplayResult, type DbReplayTaskConflict, type DbReplayTaskItem, DbReplayWorkstreamMissingError, type DeleteSnapshotResult, type DeleteTaskResult, type DestroyResult, type DetectedStatus, type DoctorCheck, type DoctorStatus, type DoctorSummary, EVENT_VERB_PREFIXES, EXPECTED_TABLES, type EvidenceOption, type ExportArchiveOptions, type ExportArchiveResult, type ExportDbOptions, type ExportDbResult, type ExportManifest, type ExportResult, type ExportSource, type ExportSourceManifest, type ExportTaskEntry, type ExportWorkstreamOptions, type FreeAgentResult, type FullDag, HomeDirAsProjectRootError, type IdFromTitleResult, type ImportDbOptions, type ImportDbResult, type InsertAgentInput, type KickAgentOptions, type KickAgentResult, type KickProcessExecutor, type KickSignal, type ListArchivedTasksOptions, type ListLiveAgentsOptions, type ListLogsOptions, type ListNotesOptions, type ListReadyOptions, type ListSnapshotsOptions, type ListTasksOptions, type LiveAgentsView, type LoadFullDagOptions, type LoadWorkstreamSnapshotOptions, type LogKind, type LogRow, type NewSessionOptions, type NewWindowOptions, NoForegroundProcessError, type OpenDbOptions, type OwnedTasksSummary, 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 ReplayDbOptions, type RestoreArchiveOptions, type RestoreArchiveResult, type RestoreSnapshotResult, type RoiBucket, 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, WORKSPACE_STALE_THRESHOLD, type CreateWorkspaceOptions as WorkspaceCreateOptions, WorkspaceExistsError, type WorkspaceFailure, type FreeWorkspaceOptions as WorkspaceFreeOptions, type FreeWorkspaceResult as WorkspaceFreeResult, WorkspaceNotFoundError, type WorkspaceOrphan, WorkspacePathNotEmptyError, WorkspacePreservedError, type RecreateWorkspaceOptions as WorkspaceRecreateOptions, type RecreateWorkspaceResult as WorkspaceRecreateResult, type WorkspaceRow, type WorkspaceStaleness, WorkstreamExistsError, WorkstreamNameInvalidError, type WorkstreamOptions, type WorkstreamSnapshot, type WorkstreamSnapshotSlowFields, type WorkstreamSummary, addBlockEdge, addNote, addTask, addToArchive, adoptAgent, agentStatusHistogram, appendLog, assertValidPaneId, backendByName, buildImportPlan, buildReplayPlan, capturePane, captureSnapshot, checkCommandResolvable, claimTask, classifyEventVerb, closeAgent, closeTask, composeAgentTitle, countProblems, createArchive, createWorkspace, currentAgentName, currentPaneTitle, decorateWithDirty, decorateWithStaleness, defaultDbPath, defaultSendDelayMs, defaultSpawnLivenessMs, defaultStateDir, deferTask, deleteAgent, deleteArchive, deleteSnapshot, deleteTask, destroyWorkstream, detectBackend, detectPiStatus, emitEvent, ensureWorkstream, envVarNameForCli, exportArchive, exportDb, exportSourceForWorkstream, exportSourcesForArchive, exportWorkstream, extractTail, foregroundPgid, freeAgent, freeWorkspace, gcMaxAgeDays, gcMaxCount, gcSnapshots, getAgent, getAgentByPane, getArchive, getParallelTracks, getPrerequisites, getTask, getTaskEdges, getTaskEdgesWithStatus, getWaitPollCount, getWorkspaceForAgent, getWorkspaceStaleness, gitBackend, idFromTitle, idFromTitleVerbose, importDb, insertAgent, isKickSignal, isStaleVersion, isTaskStatus, isValidAgentName, isValidArchiveLabel, isValidPaneId, isValidTaskId, isValidWorkstreamName, isWorkspaceStale, jjBackend, kickAgent, 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, loadDoctorChecks, loadDoctorSummary, loadFullDag, loadWorkstreamSnapshot, loadWorkstreamSnapshotFast, loadWorkstreamSnapshotSlow, mergeSnapshotFastSlow, newSession, newSessionWithPane, newWindow, noneBackend, openDb, openTask, paneExists, paneTTY, parseAgentNameFromTitle, parsePsTtyOutput, pruneSnapshots, readAgent, reconcile, recreateWorkspace, refreshAgentTitle, rejectTask, releaseTask, remediationParagraph, removeBlockEdge, removeFromArchive, renderForest, renderTaskTree, renderToBucket, reparentTask, replayDb, resetCommandResolverForTests, resetKickProcessExecutor, resetSleep, resetTmuxExecutor, resetWaitPollCount, resolveActorIdentity, resolveCliCommand, resolveCliCommandWithSource, restoreArchive, restoreSnapshot, roiBucket, searchArchives, searchTasks, selectLayout, sendToAgent, sendToPane, sessionExists, setCommandResolverForTests, setKickProcessExecutor, setPaneTitle, setSleepForTests, setTaskStatus, setTmuxExecutor, setWaitSleepForTests, setWaitStuckWarnForTests, slBackend, sleep, slugifyTitle, slugifyTitleVerbose, snapshotFileSize, snapshotsDir, spawnAgent, splitWindow, summarizeOwnedTasks, summarizeWorkstream, tmux$1 as tmux, updateAgentStatus, updateTask, waitForTasks, workspacePath, workspacesRoot, yankCommandForCheck };