@martintrojer/mu 0.3.1 → 0.4.0

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,8 +62,6 @@ 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 §
@@ -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,10 +339,22 @@ 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>;
+/**
+ * Look up the TTY device path for a pane (e.g. `/dev/ttys012` on macOS,
+ * `/dev/pts/3` on Linux). Used by `mu agent kick` to find the
+ * foreground process group on the pane's TTY so it can be signalled
+ * directly — `tmux send-keys C-c` does NOT propagate to wrapped
+ * subprocesses inside a CLI like pi/claude/codex (the CLI catches it
+ * itself and treats it as a UI input). The escape hatch is signalling
+ * the foreground pgid of the underlying TTY from outside the pane.
+ *
+ * Throws `PaneNotFoundError` when the pane id is invalid or the pane
+ * has vanished. Throws `TmuxError` on any other tmux failure.
+ */
+declare function paneTTY(paneId: string): Promise<string>;
 declare function getPaneTitle(paneId: string): Promise<string | undefined>;
 /**
  * Read the title of the *current* pane (the one whose shell is running this
@@ -350,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`,
@@ -432,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;
@@ -451,6 +451,7 @@ declare const tmux$1_newSession: typeof newSession;
 declare const tmux$1_newSessionWithPane: typeof newSessionWithPane;
 declare const tmux$1_newWindow: typeof newWindow;
 declare const tmux$1_paneExists: typeof paneExists;
+declare const tmux$1_paneTTY: typeof paneTTY;
 declare const tmux$1_parseAgentNameFromTitle: typeof parseAgentNameFromTitle;
 declare const tmux$1_resetSleep: typeof resetSleep;
 declare const tmux$1_resetTmuxExecutor: typeof resetTmuxExecutor;
@@ -464,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_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 };
 }
 
 /**
@@ -481,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).
@@ -499,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.
  */
@@ -542,6 +543,52 @@ interface ReconcileReport {
 }
 declare function reconcile(db: Db, opts: ReconcileOptions): Promise<ReconcileReport>;
 
+/**
+ * Pre-flight failure: the command mu would have spawned in the new
+ * pane doesn't resolve to a binary on PATH (and isn't an absolute /
+ * relative path that exists + is executable). Thrown by `spawnAgent`
+ * BEFORE `prestageWorkspace` so a typo in `--cli` never leaves an
+ * orphan workspace dir behind.
+ *
+ * Source: feedback ws task `fb_agent_spawn_no_validation`. Live
+ * dogfood report: `mu agent spawn worker-1 --cli pi-meta` on a host
+ * where the `pi-meta` binary wasn't on PATH printed `Spawned worker-1
+ * (pi-meta)` and the pane immediately died with `command not found`;
+ * the existing 1.5s liveness check sometimes missed it (the shell
+ * stays alive after the failed exec). Pre-flighting the PATH lookup
+ * surfaces the typo before any side effects (workspace, pane, DB row).
+ *
+ * Distinct from `AgentSpawnStartupError` (pane alive but parked at an
+ * error prompt) and `AgentDiedOnSpawnError` (pane vanished within the
+ * liveness window). All three carry different remediation hints, so
+ * they're separate types.
+ */
+declare class AgentSpawnCliNotFoundError extends Error implements HasNextSteps {
+    readonly cli: string;
+    /** First whitespace-separated token of the resolved command — the
+     *  thing actually missing on PATH. Surfaced verbatim in the
+     *  message so the operator sees what mu searched for (which may
+     *  differ from `cli` when `$MU_<UPPER_CLI>_COMMAND` rewrites it). */
+    readonly binary: string;
+    /** Name of the env var that mu consulted before falling back to
+     *  the bare `cli` value (e.g. `MU_PI_META_COMMAND`). Always set
+     *  to the conventional name so the nextSteps hint can recommend
+     *  exporting it. */
+    readonly envVarChecked: string;
+    readonly name = "AgentSpawnCliNotFoundError";
+    constructor(cli: string, 
+    /** First whitespace-separated token of the resolved command — the
+     *  thing actually missing on PATH. Surfaced verbatim in the
+     *  message so the operator sees what mu searched for (which may
+     *  differ from `cli` when `$MU_<UPPER_CLI>_COMMAND` rewrites it). */
+    binary: string, 
+    /** Name of the env var that mu consulted before falling back to
+     *  the bare `cli` value (e.g. `MU_PI_META_COMMAND`). Always set
+     *  to the conventional name so the nextSteps hint can recommend
+     *  exporting it. */
+    envVarChecked: string);
+    errorNextSteps(): NextStep[];
+}
 declare class AgentExistsError extends Error implements HasNextSteps {
     readonly agentName: string;
     readonly name = "AgentExistsError";
@@ -600,6 +647,52 @@ declare class AgentDiedOnSpawnError extends Error implements HasNextSteps {
     constructor(agentName: string, paneId: string, scrollback: string | undefined);
     errorNextSteps(): NextStep[];
 }
+/**
+ * Thrown when an agent's pane is alive AND staying alive after the
+ * liveness window, but its first burst of output matches a known
+ * provider-startup-failure pattern (missing API key, auth rejected, …).
+ * Source: feedback ws task `agent_spawn_model_auth_failure_counts_as_live`.
+ * Live dogfood report: `pi-meta --no-solo --model sonnet:high` printed
+ * `Error: No API key found for amazon-bedrock` and parked at a prompt.
+ * The pane stayed alive (1.5s liveness check passed) but the worker
+ * could never do work — the orchestrator only discovered this when
+ * `mu task wait` stalled minutes later.
+ *
+ * Distinct from `AgentDiedOnSpawnError`:
+ *   - `AgentDiedOnSpawnError` → pane vanished within the liveness window
+ *     (CLI exited fast).
+ *   - `AgentSpawnStartupError` → pane alive, but the captured scrollback
+ *     tail contains a curated provider-auth-failure pattern.
+ * The two carry different remediation hints (CLI override vs. fix the
+ * env var), so they're separate types instead of one with a flag.
+ *
+ * The pattern list is curated and short to keep false-positive risk low
+ * — the scan only looks at the last ~30 lines of the 50-line capture
+ * taken right after the liveness sleep, so matches naturally come from
+ * the CLI's first ~1.5s of output (not arbitrary later prompts the
+ * agent might type into).
+ */
+declare class AgentSpawnStartupError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly paneId: string;
+    /** The single scrollback line that matched a known startup-error
+     *  pattern. Surfaced verbatim in the message so the operator sees
+     *  what mu saw. */
+    readonly matchedLine: string;
+    /** Full captured scrollback (tail-trimmed already by
+     *  awaitSpawnLiveness). Attached to the message for context. */
+    readonly scrollback: string;
+    readonly name = "AgentSpawnStartupError";
+    constructor(agentName: string, paneId: string, 
+    /** The single scrollback line that matched a known startup-error
+     *  pattern. Surfaced verbatim in the message so the operator sees
+     *  what mu saw. */
+    matchedLine: string, 
+    /** Full captured scrollback (tail-trimmed already by
+     *  awaitSpawnLiveness). Attached to the message for context. */
+    scrollback: string);
+    errorNextSteps(): NextStep[];
+}
 /**
  * Thrown when `closeAgent` is called on an agent that has an associated
  * workspace AND the caller didn't explicitly opt into discarding it.
@@ -651,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. */
@@ -678,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 {
@@ -740,6 +845,31 @@ interface VcsBackend {
      * the on-disk dir without touching the agent or pane.
      */
     rebaseTo(workspacePath: string, fromRef?: string): Promise<RebaseResult>;
+    /**
+     * Cheap "is the working copy clean?" probe used by close-auto-free
+     * (allow_mu_agent_close_without_discard). Definition: ZERO uncommitted
+     * changes (no working-tree modifications, no staged changes, no
+     * untracked-not-ignored files). Pure observation; no fetch, no commit.
+     *
+     * Backend-specific:
+     *   - git: empty `git status --porcelain` output.
+     *   - jj:  jj is auto-snapshotted, so the @ commit IS the WC; clean
+     *          here means @ has no diff from its parent (empty `jj diff
+     *          -r @ --summary`). A description-only difference still
+     *          counts as clean.
+     *   - sl:  empty `sl status` output.
+     *   - none: meaningless (cp -a snapshot has no notion of
+     *          "committed" vs "uncommitted"); always returns true so the
+     *          close-auto-free path treats every none-workspace as
+     *          eligible for silent free (no commits can be lost; the only
+     *          loss is local file edits, which the operator implicitly
+     *          accepts by closing the agent).
+     *
+     * Returns false on any backend command failure — be conservative
+     * (we'd rather refuse a close than auto-free a workspace whose
+     * cleanliness we couldn't verify).
+     */
+    isClean(workspacePath: string): Promise<boolean>;
     /**
      * List commits the workspace has on top of `baseRef`, oldest-first.
      * Used by `mu workspace commits` (fb_workspace_commits_verb) to
@@ -754,11 +884,44 @@ 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.
+     *
+     * Used by `mu workspace recreate` to refuse a free+create cycle on
+     * a dirty workspace unless the operator passes `--force` (the lossy
+     * escape hatch). Mirrors the dirty-check `rebaseTo` does internally.
+     *
+     * Backend semantics:
+     *   - git: `git status --porcelain` (working-tree + staged +
+     *     untracked-not-ignored, mirroring the rebaseTo path).
+     *   - sl:  `sl status` parsed for non-empty output.
+     *   - jj:  always-snapshotted, so no concept of "dirty" — returns [].
+     *   - none: cp -a snapshots have no VCS, so we can't decide "dirty";
+     *     returns [] so the caller doesn't refuse for an unanswerable
+     *     question.
+     *
+     * Throws on backend command failure (the operator should see a
+     * real error, not a silent "clean").
+     */
+    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. */
@@ -779,6 +942,48 @@ declare function backendByName(name: VcsBackendName): VcsBackend;
  * are still recognised as agents.
  */
 declare function resolveCliCommand(cli: string): string;
+/**
+ * Compute the `MU_<UPPER_CLI>_COMMAND` env var name mu consults when
+ * resolving `--cli <key>`. Hyphens in the cli key become underscores
+ * (env var names can't contain `-`); this matches the operator-aliases
+ * convention documented in the mu skill (e.g. `--cli pi-meta` →
+ * `MU_PI_META_COMMAND`).
+ */
+declare function envVarNameForCli(cli: string): string;
+/**
+ * Resolve `--cli <key>` to its actual command string AND tell the
+ * caller whether the resolution came from a `MU_<UPPER_CLI>_COMMAND`
+ * env var or fell through to the bare cli name. The CLI uses this to
+ * surface env-var attribution in the spawn-success line so config
+ * issues are visible without `mu agent show`
+ * (fb_agent_spawn_no_validation, part C).
+ */
+declare function resolveCliCommandWithSource(cli: string): {
+    command: string;
+    envVar: string;
+    resolvedFromEnv: boolean;
+};
+interface CommandResolutionResult {
+    ok: boolean;
+    /** First whitespace-separated token of the command — the binary
+     *  whose presence on PATH we checked. */
+    binary: string;
+    /** Absolute path of the resolved binary on PATH, when ok=true. */
+    resolvedPath?: string;
+}
+type CommandResolver = (command: string) => Promise<CommandResolutionResult>;
+/** Override the PATH resolver. Tests use this to simulate "binary
+ *  absent" / "binary present" without depending on what's actually
+ *  installed. Production callers should never touch this. */
+declare function setCommandResolverForTests(resolver: CommandResolver): void;
+/** Restore the default PATH resolver. */
+declare function resetCommandResolverForTests(): void;
+/**
+ * Verify the first token of `command` resolves to a binary on PATH.
+ * Public so tests can call it directly; spawnAgent calls it before
+ * prestageWorkspace so a bad --cli never creates an orphan workspace.
+ */
+declare function checkCommandResolvable(command: string): Promise<CommandResolutionResult>;
 interface SpawnAgentOptions {
     name: string;
     workstream: string;
@@ -899,6 +1104,119 @@ interface AdoptAgentResult {
  */
 declare function adoptAgent(db: Db, opts: AdoptAgentOptions): Promise<AdoptAgentResult>;
 
+/** The signal set kick supports. SIGINT is graceful (matches Ctrl-C
+ *  semantics — what the operator probably wanted in the first place);
+ *  SIGTERM is the polite escalation; SIGKILL is the unblockable
+ *  hammer. We deliberately don't expose arbitrary signals — the
+ *  three above are the actionable ones for "interrupt a wedged
+ *  foreground tool subprocess." */
+type KickSignal = "SIGINT" | "SIGTERM" | "SIGKILL";
+declare function isKickSignal(s: string): s is KickSignal;
+/**
+ * Thrown when the foreground pgid lookup on a pane's TTY yields
+ * either no rows at all (the pane is sitting at an idle shell with
+ * no foreground job) or only the wrapping shell itself (the LLM CLI
+ * — pi/claude/codex — is the foreground; signalling it would close
+ * the agent, which is what `mu agent close` is for).
+ *
+ * Maps to the generic exit code 1 in handle.ts (this is a
+ * runtime-state condition, not a typed not-found / conflict).
+ */
+declare class NoForegroundProcessError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly tty: string;
+    readonly reason: "no-foreground" | "shell-only";
+    readonly name = "NoForegroundProcessError";
+    constructor(agentName: string, tty: string, reason: "no-foreground" | "shell-only");
+    errorNextSteps(): NextStep[];
+}
+interface KickProcessExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+}
+type KickProcessExecutor = (cmd: string, args: readonly string[]) => Promise<KickProcessExecResult>;
+/** Install a custom executor (for tests). Returns the previous one so
+ *  tests can restore cleanly. */
+declare function setKickProcessExecutor(executor: KickProcessExecutor): KickProcessExecutor;
+/** Restore the real executor. */
+declare function resetKickProcessExecutor(): void;
+interface PsRow {
+    pid: number;
+    pgid: number;
+    /** ps's `stat` (or `state`) field. The presence of `+` means
+     *  "foreground process group on its controlling tty". */
+    stat: string;
+    /** Process command (just the comm; truncated, used for diagnostics). */
+    comm: string;
+}
+/**
+ * Parse `ps -t <tty> -o pid=,pgid=,stat=,comm=` output. Each non-blank
+ * line is one process: four whitespace-separated fields. Defensive
+ * about leading whitespace and command names with embedded spaces
+ * (the comm is the LAST field — join the tail).
+ */
+declare function parsePsTtyOutput(output: string): PsRow[];
+/**
+ * Resolve the foreground process group id for a TTY device path. The
+ * canonical signal `ps`'s `stat` field uses is `+` (BSD/Darwin AND
+ * Linux procps). We pick the first row whose stat contains `+`; its
+ * `pgid` is the foreground pgid of that controlling terminal.
+ *
+ * Returns:
+ *   - `{ kind: "ok", pgid, fgRow }` on success
+ *   - `{ kind: "no-foreground" }` when no row carries `+` AND there
+ *     are no candidate rows at all
+ *   - `{ kind: "shell-only", pgid, fgRow }` when the foreground pgid
+ *     resolves to a shell whose comm is the agent's wrapping CLI
+ *     (caller decides whether to refuse — kick refuses)
+ *
+ * The wrapping-CLI guard is intentionally narrow: we only refuse
+ * when the foreground process command matches one of the known
+ * pi/claude/codex/zsh/bash shapes. Anything else (a `find`, a
+ * `cargo build`, a `python script.py`) is exactly what we want to
+ * signal — that's the unbounded-tool case the verb was built for.
+ */
+interface ForegroundLookup {
+    kind: "ok" | "shell-only" | "no-foreground";
+    pgid?: number;
+    fgRow?: PsRow;
+    /** All rows ps returned for the tty, for diagnostics / tests. */
+    rows: PsRow[];
+}
+declare function foregroundPgid(tty: string): Promise<ForegroundLookup>;
+interface KickAgentOptions {
+    workstream: string;
+    /** Defaults to SIGINT (matches Ctrl-C semantics). */
+    signal?: KickSignal;
+}
+interface KickAgentResult {
+    agentName: string;
+    paneId: string;
+    /** TTY device path the foreground pgid was resolved against. */
+    tty: string;
+    /** The pgid we signalled. */
+    signaledPgid: number;
+    signal: KickSignal;
+    /** The comm of the foreground process at the time of signal — useful
+     *  diagnostic in the event log ("we kicked a `find`, not a `cargo`"). */
+    foregroundComm: string;
+}
+/**
+ * Send `signal` to the foreground process group of an agent's pane
+ * TTY. Default signal is SIGINT.
+ *
+ * Errors:
+ *   - `AgentNotFoundError` — the agent doesn't exist in this workstream.
+ *   - `PaneNotFoundError` (from paneTTY) — the agent's pane has vanished.
+ *   - `NoForegroundProcessError` — pane has no foreground job, OR the
+ *     foreground is the wrapping CLI itself (refuse; use `mu agent close`).
+ *
+ * Emits an `agent kick <name> (signal=..., pgid=..., comm=...)` event
+ * on success.
+ */
+declare function kickAgent(db: Db, name: string, opts: KickAgentOptions): Promise<KickAgentResult>;
+
 interface AgentRow {
     name: string;
     /** Foreign-name reference to the owning workstream. */
@@ -1025,14 +1343,17 @@ interface FreeAgentResult {
 declare function freeAgent(db: Db, name: string, workstream: string): FreeAgentResult;
 interface CloseAgentOptions {
     /**
-     * When true, free the agent's workspace BEFORE deleting the agent
-     * (so we control the order rather than relying on FK cascade, which
-     * leaves the on-disk dir orphaned). Lossy: any pending changes in
-     * the workspace are gone unless the caller frees with `--commit`
-     * separately first.
+     * Lossy override: when true, free the agent's workspace BEFORE
+     * deleting the agent regardless of whether it's clean. (We control
+     * the order rather than relying on FK cascade, which leaves the
+     * on-disk dir orphaned.) Any pending changes / commits since fork
+     * are gone unless the caller frees with `--commit` separately first.
      *
-     * When false (default) and a workspace exists, throws
-     * WorkspacePreservedError so the caller has to decide explicitly.
+     * When false (default), behaviour depends on workspace state:
+     *   - clean (no uncommitted changes AND no commits since fork):
+     *     silently auto-free. allow_mu_agent_close_without_discard.
+     *   - dirty (uncommitted changes OR commits since fork): throw
+     *     WorkspacePreservedError so the caller decides explicitly.
      * Surfaced as a real bug in the multi-agent dogfood teardown.
      */
     discardWorkspace?: boolean;
@@ -1040,11 +1361,20 @@ interface CloseAgentOptions {
 interface CloseAgentResult {
     killedPane: boolean;
     deletedRow: boolean;
-    /** True iff the agent had an associated workspace AND the caller
-     *  passed `discardWorkspace: true` so we proactively freed it.
-     *  False on the no-workspace path (nothing to free) and on the
-     *  refused path (we threw before doing anything). */
+    /** True iff the agent had an associated workspace AND we proactively
+     *  freed it — either because the caller passed `discardWorkspace:
+     *  true` (lossy) or because the workspace was clean and we
+     *  auto-freed (allow_mu_agent_close_without_discard). False on the
+     *  no-workspace path (nothing to free) and on the refused path (we
+     *  threw before doing anything). */
     workspaceFreed: boolean;
+    /** True iff `workspaceFreed` was triggered by the clean-workspace
+     *  auto-free path (no uncommitted changes AND no commits since
+     *  fork) rather than the explicit `discardWorkspace: true` override.
+     *  Lets the CLI render an accurate message ("auto-freed (clean)"
+     *  vs "workspace discarded") and gives JSON consumers a stable
+     *  signal. False on every other path. */
+    workspaceAutoFreedClean: boolean;
 }
 /**
  * Close an agent: kill its tmux pane and remove its DB row. Idempotent:
@@ -1052,15 +1382,22 @@ interface CloseAgentResult {
  *   - if the tmux pane is already gone, killPane swallows the error
  *
  * Workspace handling: closing an agent and freeing its workspace are
- * separate concerns (agent lifecycle vs disk artifacts), so by default
- * `closeAgent` REFUSES if the agent has a workspace — you'd otherwise
- * orphan the on-disk dir (the FK cascade drops the registry row but
- * not the directory). Two ways to proceed:
- *
- *   1. `freeWorkspace(db, name)` first, then `closeAgent(db, name)`.
- *      Preserves the option to `--commit` pending changes.
- *   2. `closeAgent(db, name, { discardWorkspace: true })`. One-shot;
- *      lossy.
+ * separate concerns (agent lifecycle vs disk artifacts). Three cases:
+ *
+ *   - No workspace: close proceeds normally.
+ *   - Workspace exists AND is CLEAN (no uncommitted changes, no
+ *     commits since fork): silently auto-free (so a workspace that
+ *     contains nothing worth preserving doesn't make the operator
+ *     type --discard-workspace just to clean it up). Surfaced by
+ *     allow_mu_agent_close_without_discard — a misconfigured-spawn
+ *     teardown was needlessly forced through the lossy flag.
+ *   - Workspace exists AND has either uncommitted changes OR commits
+ *     since fork: REFUSE with WorkspacePreservedError so the operator
+ *     decides explicitly. Two resolutions:
+ *       1. `freeWorkspace(db, name)` first, then `closeAgent(db, name)`.
+ *          Preserves the option to `--commit` pending changes.
+ *       2. `closeAgent(db, name, { discardWorkspace: true })`.
+ *          One-shot; lossy.
  *
  * The CLI surfaces these as the two actionable nextSteps on the
  * `WorkspacePreservedError` thrown by the refuse path.
@@ -1077,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
@@ -1109,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>;
 
@@ -1197,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 {
@@ -1217,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 /
@@ -1245,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;
@@ -1315,44 +1624,17 @@ 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[];
 
 type TaskStatus = "OPEN" | "IN_PROGRESS" | "CLOSED" | "REJECTED" | "DEFERRED";
 /** Every legal task status, in canonical order (matches the schema
@@ -1376,878 +1658,1207 @@ 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;
 }
-/**
- * Thrown when a verb is invoked with `-w/--workstream <name>` but the
- * named task lives in a different workstream. Distinguishes "the user
- * typo'd the workstream" from "the task doesn't exist anywhere"
- * (which surfaces as `TaskNotFoundError`). Maps to exit code 4
- * (conflict / wrong scope).
- */
-declare class TaskNotInWorkstreamError extends Error implements HasNextSteps {
-    readonly taskId: string;
-    readonly expectedWorkstream: string;
-    readonly actualWorkstream: string;
-    readonly name = "TaskNotInWorkstreamError";
-    constructor(taskId: string, expectedWorkstream: string, actualWorkstream: string);
-    errorNextSteps(): NextStep[];
+
+interface TaskEdges {
+    /** Tasks that must close before this one can start (blockers). */
+    blockers: string[];
+    /** Tasks that this one blocks (dependents). */
+    dependents: string[];
 }
-declare class TaskAlreadyOwnedError extends Error implements HasNextSteps {
-    readonly taskId: string;
-    readonly currentOwner: string;
-    readonly name = "TaskAlreadyOwnedError";
-    constructor(taskId: string, currentOwner: string);
-    errorNextSteps(): NextStep[];
+/** 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 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.
+ * 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 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 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;
 }
 /**
- * Thrown when `mu task claim` resolves a claimer agent name (from the
- * pane title or --for) that has no matching row in the agents table.
- *
- * The FK on `tasks.owner` references `agents.name`; without this guard
- * the claim attempt would fail with the unhelpful 'FOREIGN KEY constraint
- * failed' from SQLite. This typed error gives the user actionable next
- * steps (run `mu adopt <pane-id>` to register, or use --for to pick a
- * different agent).
+ * Add the edge `blocker → blocked` ('blocker blocks blocked').
+ * Idempotent (existing edge → `added: false`). Validates:
  *
- * Maps to exit code 4 (conflict) via the cli.ts handler.
+ *   - 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 class ClaimerNotRegisteredError extends Error implements HasNextSteps {
-    readonly agentName: string;
-    readonly paneId: string | null;
-    readonly name = "ClaimerNotRegisteredError";
-    constructor(agentName: string, paneId: string | null);
-    /**
-     * Three actionable resolutions in expected-frequency order:
-     *   1. --self  : orchestrator pattern (working directly)
-     *   2. --for   : dispatcher pattern (assigning to a worker)
-     *   3. mu adopt: registration pattern (promote pane to worker)
-     */
-    errorNextSteps(): NextStep[];
-}
-declare class CycleError extends Error implements HasNextSteps {
-    readonly from: string;
-    readonly to: string;
-    readonly name = "CycleError";
-    constructor(from: string, to: string);
-    errorNextSteps(): NextStep[];
+declare 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;
 }
-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[];
+/**
+ * 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 ReparentTaskResult {
+    /** Edges removed (i.e. all incoming `to_task = taskId` edges). */
+    removedEdges: number;
+    /** Edges added (after duplicate blockers are canonicalised). */
+    addedEdges: number;
 }
+/**
+ * Atomically replace every incoming edge of `taskId` with new ones
+ * `blocker[i] → taskId`. Pass an empty `blockers` array to clear all
+ * incoming edges (the task becomes ready iff its status allows).
+ *
+ * Validates ALL new blockers up-front (existence + same workstream +
+ * cycle check); if any fails, no DELETE happens — the call is fully
+ * atomic via a single transaction.
+ *
+ * Cycle reasoning: removing the existing incoming edges to `taskId`
+ * doesn't change `taskId`'s OUTGOING reachability, so
+ * `wouldCreateCycle(db, blocker, taskId)` evaluated against the
+ * pre-state gives the right answer for each new edge.
+ */
+declare function reparentTask(db: Db, taskLocalId: string, blockers: readonly string[], scope: {
+    workstream: string;
+}): ReparentTaskResult;
 
-declare function setWaitSleepForTests(impl: ((ms: number) => Promise<void>) | undefined): (ms: number) => Promise<void>;
-/** Test seam: swap the stderr writer used by the stuck-task warning so
- *  unit tests can capture warnings without spying on process.stderr. */
-declare function setWaitStuckWarnForTests(impl: ((msg: string) => void) | undefined): (msg: string) => void;
-/** Total number of polls performed across all `waitForTasks` calls in this
- *  process. Tests typically reset before exercising and read after. */
-declare function getWaitPollCount(): number;
-declare function resetWaitPollCount(): void;
-/** A single task ref the wait verb is watching. Cross-workstream
- *  waits arrive as a heterogeneous list of (workstream, name) pairs;
- *  the legacy single-workstream call passes the same workstream on
- *  every ref. task_wait_cross_workstream. */
-interface TaskWaitRef {
-    /** The workstream the task lives in. Each ref carries its own so
-     *  the SDK doesn't need a single "the workstream" — cross-ws waits
-     *  pass refs from multiple workstreams in one call. */
-    workstreamName: string;
-    /** The task's per-workstream-unique local id. */
-    name: string;
+interface AddTaskOptions {
+    localId: string;
+    workstream: string;
+    title: string;
+    /** 1..100; enforced by schema CHECK. */
+    impact: number;
+    /** > 0; enforced by schema CHECK. */
+    effortDays: number;
+    /**
+     * Tasks that block this one. Edges inserted as `blocker -> newTask`.
+     * Each blocker must already exist AND share this task's workstream
+     * (cross-workstream edges are forbidden); cycle check guards each
+     * edge. The CLI surfaces this as `--blocked-by`; the SDK key matches.
+     */
+    blockedBy?: string[];
 }
-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. */
-    tasks: TaskWaitTaskState[];
-    /** True when EVERY task reached the target (the --all condition). */
-    allReached: boolean;
-    /** True when AT LEAST ONE task reached the target (the --any condition). */
-    anyReached: boolean;
-    /** Wall-clock time spent waiting, in ms (always >= 0). */
-    elapsedMs: number;
-    /** True when we exited because of the timeout, not because the wait
-     *  condition was met. allReached / anyReached can still be true on
-     *  partial progress when timedOut is true. */
-    timedOut: boolean;
+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;
+}
+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[];
 }
 /**
- * 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.
+ * Update scalar fields on a task. Each option is independently optional;
+ * passing none is a typed no-op (returns `updated: false, changedFields: []`).
+ * Fields whose new value equals the current value are skipped (no row change).
+ *
+ * NOT for status (use `closeTask` / `openTask` / `setTaskStatus`), owner
+ * (use `claimTask` / `releaseTask`), local_id (rename is deferred), or
+ * workstream (cross-workstream moves are deferred).
  */
-interface EvidenceOption {
-    evidence?: string;
+interface UpdateTaskScopeOption {
+    workstream: string;
 }
+declare function updateTask(db: Db, localId: string, opts: UpdateTaskOptions, scope: UpdateTaskScopeOption): UpdateTaskResult;
+
+declare function isValidTaskId(id: string): boolean;
 /**
- * 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.
+ * Lowercase title; collapse non-alnum runs into single `_`; trim
+ * leading/trailing `_`; prefix `t_` if the result starts with a digit
+ * (schema requires first char letter); apply the soft cap with
+ * word-boundary trim (cut at the last `_` at-or-before SLUG_SOFT_CAP
+ * when one exists, else hard-truncate). Mirrors `tg`'s `id_from_title`
+ * but adds the soft cap.
+ *
+ * Throws if `title` yields an empty slug after stripping.
  */
-declare function 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.
+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.
  *
- *  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;
+ *   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;
 }
-/** 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.
+/**
+ * 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).
  *
- *  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;
+ * 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;
 }
-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 `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;
+
+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[];
 }
-/** 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;
+declare function listTasks(db: Db, workstream?: string, opts?: ListTasksOptions): TaskRow[];
+/** Options for listReady. The optional `statuses` filter composes
+ *  on top of the `ready` view (which itself constrains to
+ *  `status='OPEN'`); passing only OPEN is identical to today's no-
+ *  filter shape, passing only non-OPEN values returns []. Exists so
+ *  `mu task next --status` can mirror the multi-status flag shape
+ *  shipped on `mu task list` (task_list_multi_status_union). */
+interface ListReadyOptions {
+    status?: TaskStatus | readonly TaskStatus[];
+}
+declare function listReady(db: Db, workstream: string, opts?: ListReadyOptions): TaskRow[];
+declare function listBlocked(db: Db, workstream: string): TaskRow[];
+declare function listGoals(db: Db, workstream: string): TaskRow[];
+/** All IN_PROGRESS tasks in a workstream, most-recently-touched first.
+ *  Used by `mu state` 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.
+ *
+ *  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).
+ *
+ *  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 listTasksByOwner(db: Db, workstream: string, owner: string, opts?: {
+    includeClosed?: boolean;
+}): TaskRow[];
+interface SearchTasksOptions {
+    /** Restrict to one workstream; undefined = search across all. */
+    workstream?: string;
+    /** Also search `task_notes.content` (default false: titles + ids only). */
+    includeNotes?: boolean;
+}
+/**
+ * Substring search on task `title` and `local_id`, case-insensitive.
+ * With `includeNotes: true` also searches `task_notes.content`. The
+ * pattern is wrapped in `%...%` automatically so callers don't need
+ * SQL LIKE knowledge — for explicit globs (or regex), use `mu sql`.
+ */
+declare function searchTasks(db: Db, pattern: string, opts?: SearchTasksOptions): TaskRow[];
 
-interface 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 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;
 }
-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 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[];
 }
 /**
- * Release a task: clear `tasks.owner`.
+ * 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.
  *
- * 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.
+ * Maps to exit code 4 (conflict).
+ */
+declare class WorkspacePathNotEmptyError extends Error implements HasNextSteps {
+    readonly agent: string;
+    readonly workstream: string;
+    readonly workspacePath: string;
+    readonly name = "WorkspacePathNotEmptyError";
+    constructor(agent: string, workstream: string, workspacePath: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown by createWorkspace when the resolved projectRoot is the
+ * user's $HOME.
  *
- * 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.
+ * Maps to exit code 4 (conflict).
  */
-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 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[];
 }
-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;
+/**
+ * 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;
+    commitsBehindMain: number | null;
+    isStale: boolean;
+}
+
+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;
 }
 /**
- * Claim a task. Two modes:
- *
- *   Worker claim (default):
- *     Resolve an agent name from `opts.agentName` or from $TMUX_PANE's
- *     pane title. The name MUST exist in the agents table (FK on
- *     tasks.owner). Sets `owner = <name>`. This is what mu-spawned
- *     workers do, and what `mu task claim --for <worker>` does for
- *     orchestrator dispatch.
- *
- *   Anonymous claim (--self):
- *     Skip the name -> agents FK lookup entirely. Sets `owner = NULL`.
- *     Records the actor in `agent_logs.source` instead. This is the
- *     orchestrator-doing-direct-work path — the actor is logged but
- *     not registered as a worker pane.
- *
- * Status side-effect: OPEN -> IN_PROGRESS; IN_PROGRESS / CLOSED unchanged.
- *
- * Concurrency: the worker-claim path uses a single-statement CAS UPDATE
- * with `WHERE owner IS NULL OR owner = ?` so two workers racing to
- * claim the same task can't both win. The anonymous path uses
- * `WHERE owner IS NULL` (anonymous claims don't 'own' the task in any
- * exclusive sense; if it's already owned by anyone, the anonymous claim
- * is a TaskAlreadyOwnedError just like a worker claim would be).
+ * 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 claimTask(db: Db, localId: string, opts: ClaimTaskOptions): Promise<ClaimResult>;
+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;
+}
 /**
- * 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.
+ * 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.
  *
- * 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.
+ * 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 resolveActorIdentity(): Promise<string>;
+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.
+ *
+ * Returns a NEW array; does not mutate the input.
+ */
+declare function decorateWithDirty(rows: readonly WorkspaceRow[]): Promise<WorkspaceRow[]>;
 
-interface TaskRow {
-    /** Per-workstream-unique TEXT name. The operator-facing identifier. */
-    name: string;
-    /** Alias for `name` — the per-workstream-unique TEXT id. Emitted alongside
-     *  `name` so JSON consumers can dot-access the canonical field name without
-     *  having to know that, for tasks specifically, `name` plays the localId
-     *  role. Always equal to `name`. */
-    localId: string;
-    /** Foreign-name reference to the owning workstream. */
+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;
-    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;
+    /** Absolute path to the orphan dir. */
+    path: string;
 }
-interface TaskNoteRow {
-    author: string | null;
-    content: string;
-    createdAt: 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 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.
+ * Scan `<state-dir>/workspaces/<workstream>/` for directories that
+ * have no row in `vcs_workspaces`.
  *
- * Throws if `title` yields an empty slug after stripping.
+ * 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 slugifyTitle(title: string): string;
+declare function listWorkspaceOrphans(db: Db, workstream: string): WorkspaceOrphan[];
 /**
- * Result of `slugifyTitleVerbose`: the slug plus enough metadata for
- * the CLI to decide whether to warn the user that meaning was lost.
- *
- *   slug           — the same string `slugifyTitle` returns.
- *   strippedLength — length of the post-strip pre-cap slug. When this
- *                    exceeds the SLUG_SOFT_CAP the verbose form had to
- *                    cut at a word boundary (or hard-truncate); the
- *                    cut clauses are gone with no in-band signal.
- *   truncated      — true iff `slug.length < strippedLength` AFTER the
- *                    `t_` digit-prefix correction, i.e. real bytes were
- *                    dropped. False for any title that fits under the
- *                    soft cap or whose only diff vs the stripped slug
- *                    is the `t_` prefix.
- *
- * The CLI's `mu task add` uses `truncated` to print a one-line stderr
- * hint pointing at the `<id>` positional override
- * (slugifytitle_silently_drops_clauses).
+ * 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`.
  */
-interface SlugifyResult {
-    slug: string;
-    strippedLength: number;
-    truncated: boolean;
+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[];
 }
 /**
- * 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.
+ * Thrown when a verb is invoked with `-w/--workstream <name>` but the
+ * named task lives in a different workstream. Distinguishes "the user
+ * typo'd the workstream" from "the task doesn't exist anywhere"
+ * (which surfaces as `TaskNotFoundError`). Maps to exit code 4
+ * (conflict / wrong scope).
  */
-declare function slugifyTitleVerbose(title: string): SlugifyResult;
+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[];
+}
 /**
- * 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.
+ * 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 idFromTitle(db: Db, workstream: string, title: string): string;
+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[];
+}
 /**
- * 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).
+ * 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 IdFromTitleResult {
-    id: string;
-    truncated: boolean;
+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 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[];
+}
+
+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;
 }
 /**
- * Verbose sibling of `idFromTitle`: returns both the unique id and the
- * `truncated` flag from the slugify pass. Collision-suffixing (`_2`,
- * `_3`, …) does not flip `truncated` — the underlying slug's lossiness
- * is what the CLI hint cares about.
+ * 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 idFromTitleVerbose(db: Db, workstream: string, title: string): IdFromTitleResult;
-declare function getTask(db: Db, localId: string, workstream: string): TaskRow | undefined;
+interface EvidenceOption {
+    evidence?: string;
+}
 /**
- * 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.
+ * 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.
  */
-interface ListTasksOptions {
-    /** Filter to one or more lifecycle statuses. Omitted = all statuses. */
-    status?: TaskStatus | readonly TaskStatus[];
+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[];
 }
-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[];
+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;
 }
-declare function listReady(db: Db, workstream: string, opts?: ListReadyOptions): TaskRow[];
-declare function listBlocked(db: Db, workstream: string): TaskRow[];
-declare function listGoals(db: Db, workstream: string): TaskRow[];
-/** All IN_PROGRESS tasks in a workstream, most-recently-touched first.
- *  Used by `mu state` and `mu hud` to populate their in-progress slice;
- *  exposed as a named SDK helper so those CLI verbs don't re-derive
- *  the row-shape conversion (review_code_raw_task_state_duplicate). */
-declare function listInProgress(db: Db, workstream: string): TaskRow[];
-/** Most-recently-closed tasks in a workstream, newest first, capped at
- *  `limit` (default 5). Used by `mu state` for its 'recent closed'
- *  slice; exposed as a named SDK helper so the CLI no longer needs the
- *  raw-row type that was duplicating RawTaskRow
- *  (review_code_raw_task_state_duplicate). */
-declare function listRecentClosed(db: Db, workstream: string, limit?: number): TaskRow[];
-/** List notes for a task. Operator-facing local_id; resolves to the
- *  surrogate task id via taskIdFor (with optional workstream scope). */
-declare function listNotes(db: Db, taskLocalId: string, workstream: string): TaskNoteRow[];
-/**
- * All tasks currently owned by `agent` in a given workstream
- * (v5: agents.name is per-workstream unique). Sorted by local_id.
+/** 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.
  *
- * Defaults to **excluding CLOSED** since the verb's purpose is "what
- * is X currently working on?" and a closed task is no longer being
- * worked on. closeTask intentionally preserves `owner` as a
- * historical record (so audit/notes can attribute decisions); pass
- * `{ includeClosed: true }` to surface that history.
- */
-declare function listTasksByOwner(db: Db, workstream: string, owner: string, opts?: {
-    includeClosed?: boolean;
-}): TaskRow[];
-interface SearchTasksOptions {
-    /** Restrict to one workstream; undefined = search across all. */
-    workstream?: string;
-    /** Also search `task_notes.content` (default false: titles + ids only). */
-    includeNotes?: boolean;
+ *  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;
 }
-/**
- * Substring search on task `title` and `local_id`, case-insensitive.
- * With `includeNotes: true` also searches `task_notes.content`. The
- * pattern is wrapped in `%...%` automatically so callers don't need
- * SQL LIKE knowledge — for explicit globs (or regex), use `mu sql`.
- */
-declare function searchTasks(db: Db, pattern: string, opts?: SearchTasksOptions): TaskRow[];
-interface TaskEdges {
-    /** Tasks that must close before this one can start (blockers). */
-    blockers: string[];
-    /** Tasks that this one blocks (dependents). */
-    dependents: string[];
+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[];
 }
-/** 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;
+/** Reject a task: terminal 'won't do' (out of scope, duplicate, wontfix).
+ *  Refuses if dependents are open unless `--cascade`.
+ *  Pre-snapshots once at the verb level so a cascade onto N children
+ *  produces a single snapshot, not N. Skipped for the idempotent no-op. */
+declare function rejectTask(db: Db, localId: string, opts: RejectDeferOptions): RejectDeferResult;
+/** Defer a task: parked, may revisit. Same dependent-stranding semantics
+ *  as reject (DEFERRED also doesn't satisfy a `--blocked-by` edge).
+ *  Pre-snapshots once at the verb level. Skipped for the idempotent no-op. */
+declare function deferTask(db: Db, localId: string, opts: RejectDeferOptions): RejectDeferResult;
+
+interface ReleaseResult {
+    /** The previous owner (null if the task was already unowned). */
+    previousOwnerName: string | null;
+    /** Status before the release. */
+    previousStatus: TaskStatus;
+    /** Status after the release. */
     status: TaskStatus;
+    /** True iff owner OR status actually changed. */
+    changed: boolean;
 }
-interface 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[];
+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;
 }
 /**
- * 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.
+ * Release a task: clear `tasks.owner`.
+ *
+ * Status side-effects (review_release_open_in_progress_inconsistency):
+ *   - IN_PROGRESS → OPEN automatically (without it, the task is
+ *     stranded: no owner to drive it forward, but `mu task next`
+ *     skips it because it's not OPEN).
+ *   - OPEN / CLOSED / REJECTED / DEFERRED preserved.
+ *   - `--reopen` forces OPEN regardless of current status — the
+ *     escape hatch for un-closing a CLOSED owned task in one verb.
+ *
+ * Idempotent: releasing an already-unowned task with no `--reopen` and
+ * no IN_PROGRESS status is a no-op (returns `changed: false`).
+ * Throws TaskNotFoundError on missing.
  */
-declare function getPrerequisites(db: Db, taskLocalId: string, workstream: string): Set<string>;
-interface AddTaskOptions {
-    localId: string;
+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;
-    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.
+     * 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").
      */
-    blockedBy?: string[];
+    actor?: string;
+}
+interface ClaimResult {
+    /** The agent now owning the task, or null when the claim was anonymous (--self). */
+    ownerName: string | null;
+    /** The actor recorded in the agent_logs event — the agent name for a
+     *  registered-worker claim, or the resolved actor for --self. */
+    actorName: string;
+    /** The previous owner (null if it was unowned). */
+    previousOwnerName: string | null;
+    /** The status BEFORE the claim; post-claim is IN_PROGRESS unless was CLOSED. */
+    previousStatus: TaskStatus;
+    /** The status AFTER the claim. */
+    status: TaskStatus;
 }
 /**
- * Atomically create a task and (optionally) its incoming blocked-by
- * edges.
+ * Claim a task. Two modes:
  *
- * 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.
+ *   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.
  *
- * Cycle check for `addTask` is structurally trivial (a fresh task has
- * no outgoing edges, so `to -> ... -> from` is impossible). It's still
- * called here so the same primitive is exercised by tests.
- */
-declare function addTask(db: Db, opts: AddTaskOptions): TaskRow;
-interface AddNoteOptions {
-    /** Free-form author label. Convention: agent name, "user", or "orchestrator". */
-    author?: string;
-    /** Workstream context (operator-facing name). v5: tasks.local_id is
-     *  per-workstream unique, so this is required to disambiguate. */
-    workstream: string;
-}
-declare function addNote(db: Db, taskLocalId: string, content: string, opts: AddNoteOptions): TaskNoteRow;
-interface BlockEdgeResult {
-    /** True iff a row was actually inserted (vs. already present). */
-    added: boolean;
-}
-/**
- * Add the edge `blocker → blocked` ('blocker blocks blocked').
- * Idempotent (existing edge → `added: false`). Validates:
+ *   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.
  *
- *   - 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.
+ * Status side-effect: OPEN -> IN_PROGRESS; IN_PROGRESS / CLOSED unchanged.
+ *
+ * Concurrency: the worker-claim path uses a single-statement CAS UPDATE
+ * with `WHERE owner IS NULL OR owner = ?` so two workers racing to
+ * claim the same task can't both win. The anonymous path uses
+ * `WHERE owner IS NULL` (anonymous claims don't 'own' the task in any
+ * exclusive sense; if it's already owned by anyone, the anonymous claim
+ * is a TaskAlreadyOwnedError just like a worker claim would be).
  */
-declare function 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;
-}
+declare function claimTask(db: Db, localId: string, opts: ClaimTaskOptions): Promise<ClaimResult>;
 /**
- * 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`).
+ * Resolve the current actor's identity for attribution in task notes,
+ * --self claims, and any other write that wants 'who did this?'.
  *
- * Pre-counts the cascade victims for reporting because SQLite's
- * `changes()` only reports rows directly affected by the DELETE.
+ * 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.
  *
- * 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`.
+ * 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 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;
+declare function resolveActorIdentity(): Promise<string>;
+
+declare function setWaitSleepForTests(impl: ((ms: number) => Promise<void>) | undefined): (ms: number) => Promise<void>;
+/** Test seam: swap the stderr writer used by the stuck-task warning so
+ *  unit tests can capture warnings without spying on process.stderr. */
+declare function setWaitStuckWarnForTests(impl: ((msg: string) => void) | undefined): (msg: string) => void;
+/** Total number of polls performed across all `waitForTasks` calls in this
+ *  process. Tests typically reset before exercising and read after. */
+declare function getWaitPollCount(): number;
+declare function resetWaitPollCount(): void;
+/** A single task ref the wait verb is watching. Cross-workstream
+ *  waits arrive as a heterogeneous list of (workstream, name) pairs;
+ *  the legacy single-workstream call passes the same workstream on
+ *  every ref. task_wait_cross_workstream. */
+interface TaskWaitRef {
+    /** The workstream the task lives in. Each ref carries its own so
+     *  the SDK doesn't need a single "the workstream" — cross-ws waits
+     *  pass refs from multiple workstreams in one call. */
+    workstreamName: string;
+    /** The task's per-workstream-unique local id. */
+    name: string;
 }
-interface 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[];
+interface TaskWaitOptions {
+    /** Target status. Default 'CLOSED'. */
+    status?: TaskStatus;
+    /** When true, succeed as soon as ONE listed task reaches the target.
+     *  Default false: every listed task must reach the target. */
+    any?: boolean;
+    /** Maximum time to wait, in milliseconds. Default 600_000 (10 min).
+     *  Pass 0 to wait forever. */
+    timeoutMs?: number;
+    /** Polling interval. Default 1000ms; overridable for tests. */
+    pollMs?: number;
+    /** Workstream context applied to bare-string ids. Required when the
+     *  caller passes `string[]`; ignored when the caller passes
+     *  `TaskWaitRef[]` (each ref carries its own ws). The legacy
+     *  single-ws SDK call site keeps its today's shape; the cross-ws
+     *  callers (CLI verb) pass `TaskWaitRef[]` and omit `workstream`.
+     *  task_wait_cross_workstream. */
+    workstream?: string;
+    /** Emit a yellow STUCK warning to stderr (once per task per wait call)
+     *  when an IN_PROGRESS task's owner has been in `needs_input` for at
+     *  least this many milliseconds since the agent row's last update.
+     *  Default 300_000 (5 min). Pass 0 to disable.
+     *
+     *  Surfaced by agent_close_discipline_gap in mufeedback: workers
+     *  occasionally finish + commit + go idle without running
+     *  `mu task close <id>`, leaving wait blocked indefinitely. The
+     *  warning is observation-only — wait keeps polling so the operator
+     *  (or a wrapping policy) decides whether to force-close, re-prompt,
+     *  or escalate. */
+    stuckAfterMs?: number;
+    /** What to do when the `--stuck-after` predicate fires on a watched
+     *  task. `'warn'` (default) = today's behaviour: yellow STUCK line
+     *  to stderr (deduped per task per wait call) + corroborating
+     *  `kind='event'` agent_logs row; wait keeps polling. `'exit'` =
+     *  same emit + persist, but THEN throw `StallDetectedDuringWaitError`
+     *  so the CLI wrapper exits 7 (STALL_DETECTED). The exit-action is
+     *  the unattended-orchestrator escape: a wrapping policy can branch
+     *  on 7 (idle, ambiguous — operator decides poke vs release) vs 6
+     *  (dead pane, unambiguous — re-dispatch).
+     *
+     *  Carve-out (lives at the call site, not here): the CLI passes
+     *  `'exit'` only when the wait target is CLOSED — mirrors exit-6's
+     *  reaper-flip suppression. With `--status OPEN` the worker reaching
+     *  needs_input might BE the success path. See
+     *  task_wait_stall_action_flag. */
+    onStall?: "warn" | "exit";
+    /** Optional async hook run BEFORE every snapshot (initial + each
+     *  poll iteration). The CLI uses this to reconcile the workstream
+     *  each tick (reaper flips IN_PROGRESS → OPEN for dead-pane
+     *  workers) and to throw a typed error when a reaper-flip on a
+     *  watched task should abandon the wait — see
+     *  task_wait_reconcile_dead_panes. Throwing from `beforePoll`
+     *  propagates out of `waitForTasks` unchanged.
+     *
+     *  Kept as a generic seam (not a `--reconcile`-shaped option) so
+     *  the SDK module stays free of tmux/reconcile imports — that
+     *  layering belongs above the SDK in the CLI wrapper. */
+    beforePoll?: () => Promise<void>;
+}
+interface TaskWaitTaskState {
+    /** The workstream this task lives in. Cross-workstream waits
+     *  return a mixed list; the workstream is part of identity.
+     *  task_wait_cross_workstream. */
+    workstreamName: string;
+    /** The task's per-workstream-unique name. */
+    name: string;
+    /** Current status (at the moment we exit). */
+    status: TaskStatus;
+    /** Owner at exit time (NULL when unowned, after release, or after
+     *  the reaper flipped IN_PROGRESS → OPEN due to a dead pane). */
+    owner: string | null;
+    /** True when this task's status equals the target. */
+    reachedTarget: boolean;
+    /** True when the task is IN_PROGRESS, owned by a registered agent
+     *  whose detected status is `needs_input` for >= `stuckAfterMs`.
+     *  Surfaces the agent_close_discipline_gap pattern: worker finished +
+     *  committed but skipped `mu task close <id>`. Backwards-compatible
+     *  signal — callers ignoring it see no behaviour change. */
+    stuck: boolean;
+}
+interface TaskWaitResult {
+    /** Per-task state at exit time. Same length and order as the input
+     *  list. 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;
 }
 /**
- * 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).
+ * 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).
  *
- * NOT for status (use `closeTask` / `openTask` / `setTaskStatus`), owner
- * (use `claimTask` / `releaseTask`), local_id (rename is deferred), or
- * workstream (cross-workstream moves are deferred).
+ * 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.
  */
-interface UpdateTaskScopeOption {
-    workstream: 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>;
 }
-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;
+type TaskStatusLabelFn = (task: TaskRow) => string;
+interface RenderTreeOptions {
+    /** Include the task title after the name + status label. Default: true. */
+    includeTitle?: boolean;
+}
+interface LoadFullDagOptions {
+    /** Optional visible-status filter. Omitted = every task status. */
+    statuses?: ReadonlySet<TaskStatus>;
 }
+declare function loadFullDag(db: Db, workstream: string, opts?: LoadFullDagOptions): FullDag;
 /**
- * Atomically replace every incoming edge of `taskId` with new ones
- * `blocker[i] → taskId`. Pass an empty `blockers` array to clear all
- * incoming edges (the task becomes ready iff its status allows).
- *
- * Validates ALL new blockers up-front (existence + same workstream +
- * cycle check); if any fails, no DELETE happens — the call is fully
- * atomic via a single transaction.
- *
- * Cycle reasoning: removing the existing incoming edges to `taskId`
- * doesn't change `taskId`'s OUTGOING reachability, so
- * `wouldCreateCycle(db, blocker, taskId)` evaluated against the
- * pre-state gives the right answer for each new edge.
+ * 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 reparentTask(db: Db, taskLocalId: string, blockers: readonly string[], scope: {
-    workstream: string;
-}): ReparentTaskResult;
+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;
 
 interface Track {
     /** Goal tasks (no outgoing edges) belonging to this track. */
@@ -2268,10 +2879,18 @@ interface Track {
  */
 declare function getParallelTracks(db: Db, workstream: string): Track[];
 
+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`). */
+    /** 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;
     /** sha256 of the markdown body bytes; idempotency key. */
@@ -2294,12 +2913,16 @@ interface ExportSourceManifest {
     /** Per-task entries; sorted by id for stable diffs. */
     tasks: ExportTaskEntry[];
 }
-/** Top-level bucket manifest. `bucketVersion: 2` — the v0.3 shape.
- *  v1 (bucketVersion absent + top-level `workstream` field) is the
- *  legacy single-source shape and is rejected at write time. */
+/** 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 {
-    /** Schema discriminator. Always 2 in this codebase. */
+    /** 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;
@@ -2345,17 +2968,6 @@ interface RenderBucketResult {
     manifestPath: string;
     manifest: ExportManifest;
 }
-/** Thrown when the operator points an export at a directory whose
- *  existing manifest predates bucket layout (v1, single-source). The
- *  fix is destructive (remove and re-export) so we refuse to touch
- *  it in-place — the legacy directory may be checked into git and
- *  the operator should choose between rebuilding it and picking a
- *  new --out. */
-declare class LegacyExportLayoutError extends Error {
-    readonly outDir: string;
-    readonly name = "LegacyExportLayoutError";
-    constructor(outDir: string);
-}
 /**
  * Render `input.sources` to disk under `input.outDir` in the v0.3
  * bucket layout. Idempotent + additive:
@@ -2364,8 +2976,6 @@ declare class LegacyExportLayoutError extends Error {
  *     `input.sources` either appends (new) or refreshes (existing)
  *     its subdirectory; sources NOT in `input.sources` are left
  *     untouched.
- *   - If it exists but with a legacy (v1) manifest, throw
- *     `LegacyExportLayoutError`.
  *
  * Per-task idempotency is sha256-keyed: a re-export of the same
  * source against an unchanged DB rewrites zero task files. Tasks
@@ -2495,6 +3105,14 @@ interface WorkstreamOptions {
      *  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;
+}
 /**
  * Discover every workstream visible on this machine. The union of:
  *   - rows in the `workstreams` table (canonical DB source; populated by
@@ -2518,7 +3136,7 @@ declare function summarizeWorkstream(db: Db, opts: WorkstreamOptions): Promise<W
  * to call repeatedly. Returns counts so the caller can print a useful
  * summary.
  */
-declare function destroyWorkstream(db: Db, opts: WorkstreamOptions): Promise<DestroyResult>;
+declare function destroyWorkstream(db: Db, opts: DestroyWorkstreamOptions): Promise<DestroyResult>;
 interface ExportWorkstreamOptions {
     workstream: string;
     /** Output directory (the bucket). Defaults to `./<workstream>/`
@@ -2547,9 +3165,6 @@ interface ExportResult {
  * exporting a different workstream into the same bucket appends a
  * sibling subdir.
  *
- * Throws:
- *   - `LegacyExportLayoutError` if `outDir` already contains a
- *     pre-0.3 (single-source) manifest.json.
  */
 declare function exportWorkstream(db: Db, opts: ExportWorkstreamOptions): ExportResult;
 
@@ -2560,12 +3175,6 @@ declare class ImportBucketInvalidError extends Error implements HasNextSteps {
     constructor(bucketDir: string, reason: string);
     errorNextSteps(): NextStep[];
 }
-declare class ImportLegacyLayoutError extends Error implements HasNextSteps {
-    readonly bucketDir: string;
-    readonly name = "ImportLegacyLayoutError";
-    constructor(bucketDir: string);
-    errorNextSteps(): NextStep[];
-}
 declare class WorkstreamAlreadyExistsError extends Error implements HasNextSteps {
     readonly workstream: string;
     readonly name = "WorkstreamAlreadyExistsError";
@@ -2627,204 +3236,14 @@ interface ImportBucketResult {
  * Per source-ws transactional: a failure in source A rolls back A
  * but leaves source B's import committed.
  *
- * Throws on unrecoverable bucket-level errors (no manifest, legacy
- * layout, --workstream override against multi-source). Per-source
+ * 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.
  */
 declare function importBucket(db: Db, opts: ImportBucketOptions): ImportBucketResult;
 
-interface WorkspaceRow {
-    agentName: string;
-    workstreamName: string;
-    backend: VcsBackendName;
-    path: string;
-    parentRef: string | null;
-    createdAt: string;
-    /** How many commits the workspace's parent_ref is behind the project's
-     *  default branch HEAD, as of the last time the workspace's local refs
-     *  cache was updated. Undefined when not yet computed (the listWorkspaces
-     *  fast path leaves it unset; call decorateWithStaleness to populate).
-     *  Null when staleness was queried but cannot be computed (no main found,
-     *  none-backend, missing parent_ref, command failure). */
-    commitsBehindMain?: number | null;
-}
-declare class WorkspaceExistsError extends Error implements HasNextSteps {
-    readonly agent: string;
-    readonly name = "WorkspaceExistsError";
-    constructor(agent: string);
-    errorNextSteps(): NextStep[];
-}
-declare class WorkspaceNotFoundError extends Error implements HasNextSteps {
-    readonly agent: string;
-    readonly name = "WorkspaceNotFoundError";
-    constructor(agent: string);
-    errorNextSteps(): NextStep[];
-}
-/**
- * Thrown by createWorkspace when the on-disk path it would create is
- * already occupied. Distinct from WorkspaceExistsError (which is about
- * the DB row) so the recovery is clear: the dir is orphaned (no DB
- * row points at it) and needs cleanup.
- *
- * Surfaced as a real bug from the multi-agent dogfood (mufeedback note
- * #143): users hit a bare 'vcs git: workspacePath already exists' from
- * the backend, with no nextSteps. After the cccba88 fix (close-refuses-
- * with-workspace), this case only fires when an orphan from a previous
- * mu version persists OR when the dir was manually rm-rf'd while a
- * stale registration remains (the git-worktree case).
- *
- * Maps to exit code 4 (conflict).
- */
-declare class WorkspacePathNotEmptyError extends Error implements HasNextSteps {
-    readonly agent: string;
-    readonly workstream: string;
-    readonly workspacePath: string;
-    readonly name = "WorkspacePathNotEmptyError";
-    constructor(agent: string, workstream: string, workspacePath: string);
-    errorNextSteps(): NextStep[];
-}
-/**
- * Thrown by createWorkspace when the resolved projectRoot is the
- * user's $HOME. Surfaced by snap_dogfood Finding 4: a `mu workspace
- * create` invoked from cwd=$HOME with no --project-root began a
- * recursive `cp -a` of $HOME (~/Music, ~/.config, ...) into the
- * workspace dir, stalled on DRM-protected files, and on ctrl-C left
- * a partial dir behind with no DB row.
- *
- * The guard's whole point is to make the user pick a real project
- * deliberately — there's no --force escape hatch on purpose. The
- * resolution is `--project-root <real-path>` (or `cd` into a real
- * project first).
- *
- * Maps to exit code 4 (conflict).
- */
-declare class HomeDirAsProjectRootError extends Error implements HasNextSteps {
-    readonly agent: string;
-    readonly workstream: string;
-    readonly homeDir: string;
-    readonly name = "HomeDirAsProjectRootError";
-    constructor(agent: string, workstream: string, homeDir: string);
-    errorNextSteps(): NextStep[];
-}
-/**
- * Compose the canonical on-disk path for an agent's workspace. Used by
- * createWorkspace and reachable from `mu workspace path` so the user
- * can `cd $(mu workspace path foo)` even before the directory exists.
- */
-declare function workspacePath(workstream: string, agent: string): string;
-/** Root dir for a workstream's workspaces — the parent of all
- *  per-agent workspace dirs. Used by listWorkspaceOrphans to scan
- *  the filesystem. */
-declare function workspacesRoot(workstream: string): string;
-interface WorkspaceOrphan {
-    /** The on-disk dir name (the agent name it WOULD be for, if mu had
-     *  registered it). */
-    agentName: string;
-    /** Workstream the dir is filed under. */
-    workstreamName: string;
-    /** Absolute path to the orphan dir. */
-    path: string;
-}
-/**
- * Like WorkspaceOrphan but additionally flags whether the parent
- * workstream itself is gone (no row in `workstreams`). Returned by
- * listAllOrphanWorkspaces; the per-workstream listWorkspaceOrphans
- * doesn't carry this since by construction it only runs against an
- * existing workstream.
- */
-interface StrandedWorkspaceOrphan extends WorkspaceOrphan {
-    /** True iff the parent workstream has no DB row (the dir was left
-     *  behind by a `mu workstream destroy` or a manual DELETE). */
-    stranded: boolean;
-}
-/**
- * Scan `<state-dir>/workspaces/<workstream>/` for directories that
- * have no row in `vcs_workspaces`. These are the result of:
- *   - pre-cccba88 agents closed without --discard-workspace
- *   - failed spawn rollbacks (pre-bug_agent_spawn_workspace_fk_failure fix)
- *   - manual cleanup that left the dir but not the row
- *   - any case where the operator manually rm-rf'd vcs_workspaces rows
- *
- * Returns `[]` when the workstream's workspaces dir doesn't exist,
- * or when every dir on disk has a corresponding DB row. Filesystem
- * read is best-effort: a missing/inaccessible dir returns `[]`
- * (caller doesn't have to check existsSync first).
- *
- * Surfaced by bug_workspace_orphan_not_in_state: orphan dirs were
- * invisible to `mu state` and `mu workspace list`, but blocked
- * subsequent `--workspace` spawns with WorkspacePathNotEmptyError.
- */
-declare function listWorkspaceOrphans(db: Db, workstream: string): WorkspaceOrphan[];
-/**
- * Cross-workstream variant of listWorkspaceOrphans. Reads
- * `<state-dir>/workspaces/`, recurses one level (per-ws subdir →
- * per-agent subdir), and surfaces every dir with no row in
- * `vcs_workspaces`.
- *
- * Each entry is additionally tagged with `stranded: boolean`: true
- * when the parent workstream has no row in `workstreams`. Stranded
- * orphans are the failure mode this verb was added for — workstreams
- * destroyed before the close-refuses-with-workspace fix landed (or
- * via `mu sql DELETE FROM workstreams ...`) would leave their entire
- * workspace subtree invisible to `mu workspace orphans -w <ws>`,
- * because the user couldn't know to ask for the right name.
- *
- * Surfaced by workspace_orphans_misses_destroyed_workstreams. Returns
- * `[]` when the workspaces root itself doesn't exist; otherwise scans
- * best-effort and skips any subdir that fails to read.
- */
-declare function listAllOrphanWorkspaces(db: Db): StrandedWorkspaceOrphan[];
-interface CreateWorkspaceOptions {
-    agent: string;
-    workstream: string;
-    /** Project root to branch from. Defaults to the current working
-     *  directory (the `mu` invocation site, which is normally what the
-     *  user wants). */
-    projectRoot?: string;
-    /** Override backend detection. Default: walk `detectBackend`.
-     *  Accepts either a name ("jj" / "sl" / "git" / "none") OR a
-     *  pre-built `VcsBackend` object — the object form lets tests inject
-     *  a fresh fake backend without mutating the exported singletons. */
-    backend?: VcsBackendName | VcsBackend;
-    /** Optional ref to base the workspace on. Backend-specific. */
-    parentRef?: string;
-}
-/**
- * Create a fresh workspace for an agent. Allocates the on-disk
- * directory, records the row, emits a system event. Idempotent ONLY
- * to the extent that the row check is up-front; if the row exists
- * we throw `WorkspaceExistsError` rather than silently re-using a
- * possibly-stale on-disk state. Callers should `freeWorkspace` first.
- */
-declare function createWorkspace(db: Db, opts: CreateWorkspaceOptions): Promise<WorkspaceRow>;
-declare function getWorkspaceForAgent(db: Db, agent: string, workstream: string): WorkspaceRow | undefined;
-declare function listWorkspaces(db: Db, workstream?: string): WorkspaceRow[];
-declare function decorateWithStaleness(rows: readonly WorkspaceRow[]): Promise<WorkspaceRow[]>;
-interface FreeWorkspaceOptions {
-    /** If true, attempt to commit pending changes before tearing down.
-     *  Backend-specific; see VcsBackend.freeWorkspace. */
-    commit?: boolean;
-}
-interface FreeWorkspaceResult {
-    /** The committed ref, when `commit` was true and there was something
-     *  to commit. */
-    committedRef?: string;
-    /** True iff the on-disk path was actually removed. */
-    removed: boolean;
-    /** True iff the DB row was actually deleted. */
-    rowDeleted: boolean;
-}
-/**
- * Tear down an agent's workspace. Calls the backend to remove the
- * on-disk directory (with optional auto-commit), then DELETEs the row.
- * Idempotent on a missing workspace (returns all-false).
- */
-declare function freeWorkspace(db: Db, agent: string, opts: FreeWorkspaceOptions & {
-    workstream: string;
-}): Promise<FreeWorkspaceResult>;
-
 type LogKind = "message" | "event" | "broadcast" | string;
 interface LogRow {
     /** Monotonic AUTOINCREMENT id. Use as the cursor for `--since`. */
@@ -2892,6 +3311,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:
@@ -2935,13 +3561,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;
@@ -2950,11 +3569,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;
@@ -2962,169 +3576,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, type AgentStatus, type AppendLogOptions, type Archive, ArchiveAlreadyExistsError, ArchiveLabelInvalidError, ArchiveNotFoundError, type ArchiveSearchHit, type ArchiveSourceSummary, type ArchiveSummary, type ArchivedTaskRow, type BlockEdgeResult, CURRENT_SCHEMA_VERSION, type CaptureOptions, type CaptureSnapshotResult, type ClaimResult, type ClaimTaskOptions, ClaimerNotRegisteredError, type CloseAgentOptions, type CloseAgentResult, CrossWorkstreamEdgeError, CycleError, type Db, type DeleteSnapshotResult, type DeleteTaskResult, type DestroyResult, type DetectedStatus, EXPECTED_TABLES, type EvidenceOption, type ExportArchiveOptions, type ExportArchiveResult, type ExportManifest, type ExportResult, type ExportSource, type ExportSourceManifest, type ExportTaskEntry, type ExportWorkstreamOptions, type FreeAgentResult, HomeDirAsProjectRootError, type IdFromTitleResult, ImportBucketInvalidError, type ImportBucketOptions, type ImportBucketResult, ImportEdgeRefMissingError, ImportFrontmatterParseError, ImportLegacyLayoutError, type ImportSourceResult, type InsertAgentInput, LegacyExportLayoutError, type ListArchivedTasksOptions, type ListLiveAgentsOptions, type ListLogsOptions, type ListReadyOptions, type ListSnapshotsOptions, type ListTasksOptions, type LiveAgentsView, type LogKind, type LogRow, type NewSessionOptions, type NewWindowOptions, type OpenDbOptions, PANE_ID_RE, PaneNotFoundError, type PruneMode, type PruneOptions, PruneOptionsInvalidError, type PruneResult, type ReconcileMode, type ReconcileOptions, type ReconcileReport, type RejectDeferOptions, type RejectDeferResult, type ReleaseResult, type ReleaseTaskOptions, type RemoveBlockEdgeResult, type RemoveFromArchiveResult, type RenderBucketInput, type RenderBucketResult, type ReparentTaskResult, type RestoreSnapshotResult, STATUSES_TERMINAL_OR_PARKED, STATUS_EMOJI, SchemaTooOldError, type SearchArchivesOptions, type SearchTasksOptions, type SendOptions, type SetStatusResult, type SlugifyResult, SnapshotFileMissingError, SnapshotNotFoundError, type SnapshotRow, SnapshotVersionMismatchError, type SpawnAgentOptions, type SplitWindowOptions, type StrandedWorkspaceOrphan, TASK_STATUSES, TASK_STATUS_LIST, TaskAlreadyOwnedError, type TaskEdgeWithStatus, type TaskEdges, type TaskEdgesWithStatus, TaskExistsError, TaskHasOpenDependentsError, TaskNotFoundError, TaskNotInWorkstreamError, type TaskNoteRow, type TaskRow, type TaskStatus, type TaskWaitOptions, type TaskWaitRef, type TaskWaitResult, type TaskWaitTaskState, TmuxError, type TmuxExecResult, type TmuxExecutor, type TmuxPane, type TmuxSession, type TmuxWindow, type Track, type UpdateTaskOptions, type UpdateTaskResult, type VcsBackend, type VcsBackendName, type CreateWorkspaceOptions$1 as VcsCreateWorkspaceOptions, type CreateWorkspaceResult as VcsCreateWorkspaceResult, type FreeWorkspaceOptions$1 as VcsFreeWorkspaceOptions, type FreeWorkspaceResult$1 as VcsFreeWorkspaceResult, type CreateWorkspaceOptions as WorkspaceCreateOptions, WorkspaceExistsError, type WorkspaceFailure, type FreeWorkspaceOptions as WorkspaceFreeOptions, type FreeWorkspaceResult as WorkspaceFreeResult, WorkspaceNotFoundError, type WorkspaceOrphan, WorkspacePathNotEmptyError, WorkspacePreservedError, type WorkspaceRow, WorkstreamAlreadyExistsError, WorkstreamNameInvalidError, type WorkstreamOptions, type WorkstreamSummary, addBlockEdge, addNote, addTask, addToArchive, adoptAgent, appendLog, assertValidPaneId, backendByName, capturePane, captureSnapshot, claimTask, closeAgent, closeTask, composeAgentTitle, createArchive, createWorkspace, currentAgentName, currentPaneTitle, decorateWithStaleness, defaultDbPath, defaultSendDelayMs, defaultSpawnLivenessMs, defaultStateDir, deferTask, deleteAgent, deleteArchive, deleteSnapshot, deleteTask, destroyWorkstream, detectBackend, detectPiStatus, emitEvent, ensureWorkstream, ensureWorkstreamStateDir, exportArchive, exportSourceForWorkstream, exportSourcesForArchive, exportWorkstream, extractTail, freeAgent, freeWorkspace, gcMaxAgeDays, gcMaxCount, gcSnapshots, getAgent, getAgentByPane, getArchive, getParallelTracks, getPrerequisites, getTask, getTaskEdges, getTaskEdgesWithStatus, getWaitPollCount, getWorkspaceForAgent, gitBackend, idFromTitle, idFromTitleVerbose, importBucket, insertAgent, isStaleVersion, isTaskStatus, isValidAgentName, isValidArchiveLabel, isValidPaneId, isValidTaskId, isValidWorkstreamName, jjBackend, killPane, killSession, latestSeq, listAgents, listAllOrphanWorkspaces, listArchivedTasks, listArchives, listBlocked, listGoals, listInProgress, listLiveAgents, listLogs, listNotes, listPanes, listPanesInSession, listReady, listRecentClosed, listSessions, listSnapshots, listTasks, listTasksByOwner, listWindows, listWorkspaceOrphans, listWorkspaces, listWorkstreams, newSession, newSessionWithPane, newWindow, noneBackend, openDb, openTask, paneExists, parseAgentNameFromTitle, pruneSnapshots, readAgent, reconcile, refreshAgentTitle, rejectTask, releaseTask, removeBlockEdge, removeFromArchive, renderToBucket, reparentTask, resetSleep, resetTmuxExecutor, resetWaitPollCount, resolveActorIdentity, resolveCliCommand, restoreSnapshot, searchArchives, searchTasks, selectLayout, sendToAgent, sendToPane, sessionExists, setPaneTitle, setSleepForTests, setTaskStatus, setTmuxExecutor, setWaitSleepForTests, setWaitStuckWarnForTests, slBackend, sleep, slugifyTitle, slugifyTitleVerbose, snapshotFileSize, snapshotsDir, spawnAgent, splitWindow, summarizeWorkstream, tmux$1 as tmux, updateAgentStatus, updateTask, waitForTasks, workspacePath, workspacesRoot, workstreamStateDir };
+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, 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 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 ExportManifest, type ExportResult, type ExportSource, type ExportSourceManifest, type ExportTaskEntry, type ExportWorkstreamOptions, type FreeAgentResult, type FullDag, 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 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 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, WorkstreamAlreadyExistsError, WorkstreamNameInvalidError, type WorkstreamOptions, type WorkstreamSnapshot, type WorkstreamSnapshotSlowFields, type WorkstreamSummary, addBlockEdge, addNote, addTask, addToArchive, adoptAgent, agentStatusHistogram, appendLog, assertValidPaneId, backendByName, 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, exportSourceForWorkstream, exportSourcesForArchive, exportWorkstream, extractTail, foregroundPgid, freeAgent, freeWorkspace, gcMaxAgeDays, gcMaxCount, gcSnapshots, getAgent, getAgentByPane, getArchive, getParallelTracks, getPrerequisites, getTask, getTaskEdges, getTaskEdgesWithStatus, getWaitPollCount, getWorkspaceForAgent, getWorkspaceStaleness, gitBackend, idFromTitle, idFromTitleVerbose, importBucket, 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, resetCommandResolverForTests, resetKickProcessExecutor, resetSleep, resetTmuxExecutor, resetWaitPollCount, resolveActorIdentity, resolveCliCommand, resolveCliCommandWithSource, 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 };