@mu-crew/mu 3.1.0 → 3.2.1

package/dist/index.d.ts

@@ -1,19 +1,29 @@
 import { Database } from 'better-sqlite3';
 
+type CtlState = "busy" | "idle" | "needs_input";
+
 type RuntimeState = "busy" | "needs_input" | "needs_permission" | "unknown";
-type StateSource = "murmur" | "herdr" | "none";
+type StateSource = "murmur" | "herdr" | "ctl" | "none";
+/** How a pi agent's control socket answered; "n/a" for non-pi agents. */
+type CtlLink = "ok" | "missing" | "refused" | "n/a";
 interface StateReading {
     state: RuntimeState;
     source: StateSource;
     since: number | null;
     alive: boolean;
     reason?: string;
+    /** Set for agents that expect a control socket. */
+    ctl?: Exclude<CtlLink, "n/a">;
 }
 interface StateAgentRef {
     name: string;
     workstreamName: string;
     paneId: string;
+    /** When set and it names pi, the control socket is the state source. */
+    cli?: string;
 }
+/** ctl's idle maps to needs_input, the same as murmur's idle. */
+declare function ctlRuntimeState(state: CtlState): RuntimeState;
 declare const UNKNOWN_REASON: {
     readonly murmurMissing: "murmur not installed";
     readonly extensionMissing: "murmur pi extension not linked";
@@ -21,14 +31,24 @@ declare const UNKNOWN_REASON: {
     readonly stale: "remote snapshot stale";
     readonly herdrNone: "herdr reports no state";
     readonly paneGone: "pane gone";
+    readonly ctlMissing: "ctl missing";
+    readonly ctlRefused: "ctl refused";
 };
 declare function agentKey(a: {
     name: string;
     workstreamName: string;
 }): string;
 declare function murmurAvailable(): boolean;
+/**
+ * Read the runtime state of each agent. Order per agent: control socket
+ * (pi agents) → murmur pane option → murmur remote → herdr. A pi agent
+ * whose socket does not answer reads `unknown` with reason `ctl missing`
+ * or `ctl refused`, never a murmur reading, so the gap stays visible.
+ * `stateDir` roots the derived socket path (spawn uses the DB's directory).
+ */
 declare function readAgentStates(agents: readonly StateAgentRef[], opts?: {
     now?: number;
+    stateDir?: string;
 }): Promise<Map<string, StateReading>>;
 
 /**
@@ -1101,429 +1121,96 @@ interface ReconcileReport {
 }
 declare function reconcile(db: Db, opts: ReconcileOptions): Promise<ReconcileReport>;
 
-interface AdoptAgentOptions {
-    /** tmux pane id (e.g. '%15'). Must already exist on the tmux server. */
-    paneId: string;
-    /** Workstream to adopt the pane into. The pane MUST be in the
-     *  matching tmux session (`mu-<workstream>`); cross-session adopt is
-     *  rejected. */
+type AbortResult = {
+    agent: string;
     workstream: string;
-    /** Override the pane's title with this name. When omitted, the pane's
-     *  current title becomes the agent name (zero-config adoption). */
-    name?: string;
-    /** Defaults to 'pi' via the schema DEFAULT. */
-    cli?: string;
-    /** 'full-access' (default) or 'read-only'. */
-    role?: string;
-    /** Override the tmux session lookup. Defaults to `mu-<workstream>`. */
-    tmuxSession?: string;
+    before: CtlState;
+    after: CtlState;
+    /** True when pi settled (or was never busy). */
+    settled: boolean;
+    /** False when the agent was not busy, so no abort was sent. */
+    aborted: boolean;
+    elapsedMs: number;
+};
+type AbortAgentOptions = {
+    workstream: string;
+    timeoutMs?: number;
+    /** Control socket path. Default: derived from the agent's identity. */
+    socket?: string;
+};
+declare function abortAgent(db: Db, name: string, opts: AbortAgentOptions): Promise<AbortResult>;
+
+type VcsBackendName = "jj" | "sl" | "git" | "none";
+interface RebaseResult {
+    /** The ref the workspace was actually rebased onto (resolved
+     *  symbolic-or-revset → concrete name). For git that is the
+     *  resolveGitMainRef() symbolic ref; for jj/sl it's the literal
+     *  `trunk()` revset (or whatever the operator passed via fromRef). */
+    fromRef: string;
+    /** Commit subjects (or descriptions) that got replayed, oldest-first.
+     *  Empty when the workspace was already at fromRef (no-op). */
+    replayed: string[];
+    /** Files / commits that conflicted during the rebase. Always
+     *  empty for a successful rebase — a non-empty conflicts list
+     *  means we threw WorkspaceConflictError before returning. The
+     *  field exists so the error's serialised payload can carry it. */
+    conflicts: string[];
 }
-interface AdoptAgentResult {
-    agent: AgentRow;
-    /** True when the pane already had a matching agents row — the call
-     *  was a no-op (idempotent). */
-    alreadyAdopted: boolean;
-    /** The pane title before adopt, or null if the pane had no title. */
-    previousTitle: string | null;
-    /** The title the pane was set to (== agent.name post-adopt). Equal to
-     *  previousTitle when no retitle happened. */
-    paneTitleSetTo: string;
+interface CommitSummary {
+    /** Full commit / change id. */
+    sha: string;
+    /** First-line description / subject. */
+    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;
 }
-/**
- * Register an existing tmux pane as a managed mu agent. Inverse of the
- * 'orphan' state surfaced by `mu agent list`: a pane that looks like an
- * agent (running pi/claude/codex) but has no DB row.
- *
- * Identity contract (matches the claim protocol invariant):
- *   - Post-adopt, the pane's title equals the agent's name.
- *   - When `name` is omitted, the pane's existing title becomes the
- *     agent name verbatim. Adopting a pane titled 'pi' would fail name
- *     validation — caller must supply --name in that case.
- *
- * Idempotent: adopting the same pane twice with the same name is a
- * no-op (returns alreadyAdopted=true). Adopting a different pane under
- * an existing agent name throws AgentExistsError.
- *
- * Validation order (matches the design in note #100):
- *   1. Pane id format     -> assertValidPaneId via paneExists / setPaneTitle
- *   2. Pane exists        -> PaneNotFoundError
- *   3. Pane is in session -> AgentNotInWorkstreamError (cross-session)
- *   4. Resolved name OK   -> isValidAgentName / Error('agent name invalid')
- *   5. Idempotent check   -> if pane already owned by an agent of this
- *                            name, return alreadyAdopted=true
- *   6. Name not taken     -> AgentExistsError (else)
- *   7. Insert + retitle.
- *
- * Status starts at 'free' — reconcile/detect will update it on the next
- * `mu agent list` based on actual pane content (the pi prompt yields
- * 'free'; an agent mid-thought yields 'busy'; etc.). We don't run
- * detection inline here because the caller may not have $TMUX, and
- * adoption shouldn't depend on a captured-pane probe succeeding.
- */
-declare function adoptAgent(db: Db, opts: AdoptAgentOptions): Promise<AdoptAgentResult>;
-
-/**
- * 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[];
+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;
 }
-declare class AgentExistsError extends Error implements HasNextSteps {
-    readonly agentName: string;
-    readonly name = "AgentExistsError";
-    constructor(agentName: string);
-    errorNextSteps(): NextStep[];
+interface CreateWorkspaceOptions$1 {
+    /** The repository being branched from. Absolute path. */
+    projectRoot: string;
+    /** Where to place the new workspace. Absolute path; must NOT exist. */
+    workspacePath: string;
+    /** Optional commit / branch / changeset id to base off. Backend-specific:
+     *  git uses it as a `git worktree add`'s ref, jj as a revset, sl as a
+     *  rev. Undefined = current head. */
+    parentRef?: string;
 }
-declare class AgentNotFoundError extends Error implements HasNextSteps {
-    readonly agentName: string;
-    /** Optional workstream context. When set, the message is enriched
-     *  with `(in workstream <ws>)` so the verb that hit the miss
-     *  (e.g. `mu workspace path <agent> -w <ws>`) doesn't leave the
-     *  operator guessing which scope was searched. Optional so existing
-     *  call sites that only know the agent name keep their original
-     *  one-line message. */
-    readonly workstream?: string | undefined;
-    readonly name = "AgentNotFoundError";
-    constructor(agentName: string, 
-    /** Optional workstream context. When set, the message is enriched
-     *  with `(in workstream <ws>)` so the verb that hit the miss
-     *  (e.g. `mu workspace path <agent> -w <ws>`) doesn't leave the
-     *  operator guessing which scope was searched. Optional so existing
-     *  call sites that only know the agent name keep their original
-     *  one-line message. */
-    workstream?: string | undefined);
-    errorNextSteps(): NextStep[];
+interface CreateWorkspaceResult {
+    /** The actual ref the workspace points at (resolved to a stable id
+     *  when possible). Stored on the row; useful for `mu workspace list`
+     *  and for `--commit` flows. May be null for backends that don't
+     *  expose a meaningful parent (e.g. `none`). */
+    parentRef: string | null;
 }
-/**
- * Thrown when an entity-targeted verb is invoked with `-w/--workstream
- * <name>` but the named agent lives in a different workstream.
- * Mirrors `TaskNotInWorkstreamError`. Maps to exit code 4 (conflict /
- * wrong scope). Distinguishes "the user typo'd the workstream" from
- * "the agent doesn't exist anywhere" (which surfaces as
- * `AgentNotFoundError`).
- */
-declare class AgentNotInWorkstreamError extends Error implements HasNextSteps {
-    readonly agentName: string;
-    readonly expectedWorkstream: string;
-    readonly actualWorkstream: string;
-    readonly name = "AgentNotInWorkstreamError";
-    constructor(agentName: string, expectedWorkstream: string, actualWorkstream: string);
-    errorNextSteps(): NextStep[];
+interface FreeWorkspaceOptions$1 {
+    workspacePath: string;
+    /** If true, attempt to commit any pending changes BEFORE removal.
+     *  Backend-specific: jj auto-commits via `jj describe + jj new`, git
+     *  needs an explicit commit on the worktree, sl needs `sl commit`,
+     *  none has nothing to commit. If pending changes exist and `commit`
+     *  is false, the on-disk directory still gets removed and changes are
+     *  lost — the verb prints a clear warning. */
+    commit: boolean;
 }
-/**
- * Thrown when an agent's pane is created and titled successfully but the
- * spawned process exits within the liveness window (default 1500ms;
- * configurable via `MU_SPAWN_LIVENESS_MS`). The most common cause is the
- * underlying CLI failing fast: a wrapper CLI blocking on a single-instance
- * lock, `claude` rejecting an invalid API key, etc. The agent's last
- * scrollback (when capturable) is attached to help diagnose.
- */
-declare class AgentDiedOnSpawnError extends Error implements HasNextSteps {
-    readonly agentName: string;
-    readonly paneId: string;
-    readonly scrollback: string | undefined;
-    readonly name = "AgentDiedOnSpawnError";
-    constructor(agentName: string, paneId: string, scrollback: string | undefined);
-    errorNextSteps(): NextStep[];
-}
-/**
- * Thrown when 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.
- *
- * Background: the FK on `vcs_workspaces.agent` cascades on agent
- * delete, so a naive `closeAgent` drops the workspace registry row
- * but leaves the on-disk dir orphaned (mu can't see it via
- * `mu workspace list / free / path` afterwards). Surfaced during
- * the multi-agent dogfood teardown when three workspaces went
- * orphaned silently.
- *
- * The fix: refuse close if a workspace exists; force the caller to
- * decide. Two actionable resolutions:
- *   - `mu workspace free <agent>` first, then close cleanly.
- *   - `mu agent close <agent> --discard-workspace` to free the
- *     workspace AND close the agent in one shot (lossy: pending
- *     changes in the workspace are gone).
- *
- * Maps to exit code 4 (conflict) via the cli.ts handler.
- */
-declare class WorkspacePreservedError extends Error implements HasNextSteps {
-    readonly agentName: string;
-    readonly workspacePath: string;
-    readonly name = "WorkspacePreservedError";
-    constructor(agentName: string, workspacePath: string);
-    errorNextSteps(): NextStep[];
-}
-
-/** 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>;
-
-type VcsBackendName = "jj" | "sl" | "git" | "none";
-interface RebaseResult {
-    /** The ref the workspace was actually rebased onto (resolved
-     *  symbolic-or-revset → concrete name). For git that is the
-     *  resolveGitMainRef() symbolic ref; for jj/sl it's the literal
-     *  `trunk()` revset (or whatever the operator passed via fromRef). */
-    fromRef: string;
-    /** Commit subjects (or descriptions) that got replayed, oldest-first.
-     *  Empty when the workspace was already at fromRef (no-op). */
-    replayed: string[];
-    /** Files / commits that conflicted during the rebase. Always
-     *  empty for a successful rebase — a non-empty conflicts list
-     *  means we threw WorkspaceConflictError before returning. The
-     *  field exists so the error's serialised payload can carry it. */
-    conflicts: string[];
-}
-interface CommitSummary {
-    /** Full commit / change id. */
-    sha: string;
-    /** First-line description / subject. */
-    subject: string;
-    /** Remainder of the commit message (may be empty). */
-    body: string;
-    /** 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. */
-    projectRoot: string;
-    /** Where to place the new workspace. Absolute path; must NOT exist. */
-    workspacePath: string;
-    /** Optional commit / branch / changeset id to base off. Backend-specific:
-     *  git uses it as a `git worktree add`'s ref, jj as a revset, sl as a
-     *  rev. Undefined = current head. */
-    parentRef?: string;
-}
-interface CreateWorkspaceResult {
-    /** The actual ref the workspace points at (resolved to a stable id
-     *  when possible). Stored on the row; useful for `mu workspace list`
-     *  and for `--commit` flows. May be null for backends that don't
-     *  expose a meaningful parent (e.g. `none`). */
-    parentRef: string | null;
-}
-interface FreeWorkspaceOptions$1 {
-    workspacePath: string;
-    /** If true, attempt to commit any pending changes BEFORE removal.
-     *  Backend-specific: jj auto-commits via `jj describe + jj new`, git
-     *  needs an explicit commit on the worktree, sl needs `sl commit`,
-     *  none has nothing to commit. If pending changes exist and `commit`
-     *  is false, the on-disk directory still gets removed and changes are
-     *  lost — the verb prints a clear warning. */
-    commit: boolean;
-}
-interface FreeWorkspaceResult$1 {
-    /** The commit id that captured the pending changes, when `commit` was
-     *  true and there was something to commit. Otherwise undefined. */
-    committedRef?: string;
-    /** True iff the on-disk path was actually removed (vs. already gone). */
-    removed: boolean;
+interface FreeWorkspaceResult$1 {
+    /** The commit id that captured the pending changes, when `commit` was
+     *  true and there was something to commit. Otherwise undefined. */
+    committedRef?: string;
+    /** True iff the on-disk path was actually removed (vs. already gone). */
+    removed: boolean;
 }
 interface VcsBackend {
     readonly name: VcsBackendName;
@@ -1644,136 +1331,597 @@ interface VcsBackend {
      */
     listDirtyFiles(workspacePath: string): Promise<string[]>;
 }
-
-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. */
-declare function detectBackend(projectRoot: string): Promise<VcsBackend>;
-/** Look up a backend by name. Throws on unknown name. Used by
- *  `mu agent spawn --workspace-backend ...` to honour an explicit
- *  override. */
-declare function backendByName(name: VcsBackendName): 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. */
+declare function detectBackend(projectRoot: string): Promise<VcsBackend>;
+/** Look up a backend by name. Throws on unknown name. Used by
+ *  `mu agent spawn --workspace-backend ...` to honour an explicit
+ *  override. */
+declare function backendByName(name: VcsBackendName): VcsBackend;
+
+/**
+ * Resolve the actual executable to launch in an agent's pane for a given
+ * `cli`. Honours the env var `MU_<UPPER_CLI>_COMMAND` (e.g. `MU_PI_COMMAND=
+ * pi-alt` makes `--cli pi` actually exec `pi-alt`). Falls back to the cli
+ * name itself, which is what users expect when their `pi` binary is on
+ * `$PATH` under that exact name.
+ *
+ * Used by `spawnAgent` to pick the spawned command, and by reconcile's
+ * orphan detector so externally-spawned panes running the resolved binary
+ * are still recognised as agents.
+ */
+declare function resolveCliCommand(cli: string): string;
+/**
+ * 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;
+    /** Defaults to "pi". 0.1.0 only really supports "pi" but the column
+     *  accepts any string for forward-compat with future multi-CLI support
+     *  (claude/codex). */
+    cli?: string;
+    /** The actual command to run in the pane. Defaults to the cli value. */
+    command?: string;
+    /** Window name to group this agent under. Defaults to the agent's name
+     *  (so each agent gets its own window). Multiple agents sharing a `tab`
+     *  share a window with multiple panes. */
+    tab?: string;
+    /** "full-access" (default) or "read-only". The schema stores it; today
+     *  the role isn't enforced (deferred to a future capabilities pass). */
+    role?: string;
+    /** Initial working directory for the spawned pane (`tmux -c <path>`).
+     *  When `workspace: true` is passed, this is ignored — the workspace
+     *  path is used instead. */
+    cwd?: string;
+    /** Override the tmux session name. Defaults to `mu-<workstream>`. */
+    tmuxSession?: string;
+    /** Auto-create a VCS workspace for this agent before spawning the
+     *  pane and use the workspace path as cwd. Backend defaults to
+     *  detection (jj > sl > git > none). */
+    workspace?: boolean;
+    /** Force a specific VCS backend (only meaningful with `workspace: true`). */
+    workspaceBackend?: VcsBackendName;
+    /** Optional ref to base the workspace on (only meaningful with
+     *  `workspace: true`). Backend-specific. */
+    workspaceFrom?: string;
+    /** Project root the workspace branches from (only meaningful with
+     *  `workspace: true`). Defaults to `process.cwd()`. */
+    workspaceProjectRoot?: string;
+    /** Run the control-socket handshake for pi agents (default true).
+     *  `false` skips it and reports `ctl: "skipped"`. */
+    ctl?: boolean;
+}
+/** Outcome of the spawn-time control-socket handshake. */
+type SpawnCtl = "ok" | "missing" | "refused" | "skipped";
+/** What spawnAgent returns: the registered row plus the handshake outcome. */
+type SpawnedAgent = AgentRow & {
+    ctl: SpawnCtl;
+    ctlSocket: string;
+};
+/**
+ * Spawn a new agent in its tmux pane and register it in the DB.
+ *
+ * Phases:
+ *   1. Validate name + uniqueness.
+ *   2. If --workspace: prestageWorkspace() (placeholder agent row +
+ *      workspace dir + workspace row).
+ *   3. createOrReusePane() in the workspace path (or opts.cwd).
+ *   4. setPaneTitle + enableMuPaneBordersForPane.
+ *   5. finalizeAgentRow() — patch placeholder pane_id to real (workspace
+ *      path), or insert a fresh agent row (no-workspace path).
+ *   6. awaitSpawnLiveness().
+ *
+ * Failure between any of (3)–(6) calls rollbackSpawn() to undo the
+ * pane + row + workspace. The caller-visible error is preserved.
+ */
+declare function spawnAgent(db: Db, opts: SpawnAgentOptions): Promise<SpawnedAgent>;
+/**
+ * Default liveness window in milliseconds. 0 disables the check (useful
+ * for fast tests that don't want to wait). Override via env var
+ * `MU_SPAWN_LIVENESS_MS`.
+ */
+declare function defaultSpawnLivenessMs(): number;
+
+interface AdoptAgentOptions {
+    /** tmux pane id (e.g. '%15'). Must already exist on the tmux server. */
+    paneId: string;
+    /** Workstream to adopt the pane into. The pane MUST be in the
+     *  matching tmux session (`mu-<workstream>`); cross-session adopt is
+     *  rejected. */
+    workstream: string;
+    /** Override the pane's title with this name. When omitted, the pane's
+     *  current title becomes the agent name (zero-config adoption). */
+    name?: string;
+    /** Defaults to 'pi' via the schema DEFAULT. */
+    cli?: string;
+    /** 'full-access' (default) or 'read-only'. */
+    role?: string;
+    /** Override the tmux session lookup. Defaults to `mu-<workstream>`. */
+    tmuxSession?: string;
+}
+interface AdoptAgentResult {
+    agent: AgentRow;
+    /** True when the pane already had a matching agents row — the call
+     *  was a no-op (idempotent). */
+    alreadyAdopted: boolean;
+    /** The pane title before adopt, or null if the pane had no title. */
+    previousTitle: string | null;
+    /** The title the pane was set to (== agent.name post-adopt). Equal to
+     *  previousTitle when no retitle happened. */
+    paneTitleSetTo: string;
+    /** One probe of the derived control socket; "skipped" for non-pi CLIs.
+     *  An adopted pi pane usually lacks MU_CTL_SOCK, so this is "missing". */
+    ctl: SpawnCtl;
+    ctlSocket: string;
+}
+/**
+ * Register an existing tmux pane as a managed mu agent. Inverse of the
+ * 'orphan' state surfaced by `mu agent list`: a pane that looks like an
+ * agent (running pi/claude/codex) but has no DB row.
+ *
+ * Identity contract (matches the claim protocol invariant):
+ *   - Post-adopt, the pane's title equals the agent's name.
+ *   - When `name` is omitted, the pane's existing title becomes the
+ *     agent name verbatim. Adopting a pane titled 'pi' would fail name
+ *     validation — caller must supply --name in that case.
+ *
+ * Idempotent: adopting the same pane twice with the same name is a
+ * no-op (returns alreadyAdopted=true). Adopting a different pane under
+ * an existing agent name throws AgentExistsError.
+ *
+ * Validation order (matches the design in note #100):
+ *   1. Pane id format     -> assertValidPaneId via paneExists / setPaneTitle
+ *   2. Pane exists        -> PaneNotFoundError
+ *   3. Pane is in session -> AgentNotInWorkstreamError (cross-session)
+ *   4. Resolved name OK   -> isValidAgentName / Error('agent name invalid')
+ *   5. Idempotent check   -> if pane already owned by an agent of this
+ *                            name, return alreadyAdopted=true
+ *   6. Name not taken     -> AgentExistsError (else)
+ *   7. Insert + retitle.
+ *
+ * Status starts at 'free' — reconcile/detect will update it on the next
+ * `mu agent list` based on actual pane content (the pi prompt yields
+ * 'free'; an agent mid-thought yields 'busy'; etc.). We don't run
+ * detection inline here because the caller may not have $TMUX, and
+ * adoption shouldn't depend on a captured-pane probe succeeding.
+ */
+declare function adoptAgent(db: Db, opts: AdoptAgentOptions): Promise<AdoptAgentResult>;
+
+/**
+ * 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";
+    constructor(agentName: string);
+    errorNextSteps(): NextStep[];
+}
+declare class AgentNotFoundError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    /** Optional workstream context. When set, the message is enriched
+     *  with `(in workstream <ws>)` so the verb that hit the miss
+     *  (e.g. `mu workspace path <agent> -w <ws>`) doesn't leave the
+     *  operator guessing which scope was searched. Optional so existing
+     *  call sites that only know the agent name keep their original
+     *  one-line message. */
+    readonly workstream?: string | undefined;
+    readonly name = "AgentNotFoundError";
+    constructor(agentName: string, 
+    /** Optional workstream context. When set, the message is enriched
+     *  with `(in workstream <ws>)` so the verb that hit the miss
+     *  (e.g. `mu workspace path <agent> -w <ws>`) doesn't leave the
+     *  operator guessing which scope was searched. Optional so existing
+     *  call sites that only know the agent name keep their original
+     *  one-line message. */
+    workstream?: string | undefined);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown when an entity-targeted verb is invoked with `-w/--workstream
+ * <name>` but the named agent lives in a different workstream.
+ * Mirrors `TaskNotInWorkstreamError`. Maps to exit code 4 (conflict /
+ * wrong scope). Distinguishes "the user typo'd the workstream" from
+ * "the agent doesn't exist anywhere" (which surfaces as
+ * `AgentNotFoundError`).
+ */
+declare class AgentNotInWorkstreamError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly expectedWorkstream: string;
+    readonly actualWorkstream: string;
+    readonly name = "AgentNotInWorkstreamError";
+    constructor(agentName: string, expectedWorkstream: string, actualWorkstream: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * Thrown when an agent's pane is created and titled successfully but the
+ * spawned process exits within the liveness window (default 1500ms;
+ * configurable via `MU_SPAWN_LIVENESS_MS`). The most common cause is the
+ * underlying CLI failing fast: a wrapper CLI blocking on a single-instance
+ * lock, `claude` rejecting an invalid API key, etc. The agent's last
+ * scrollback (when capturable) is attached to help diagnose.
+ */
+declare class AgentDiedOnSpawnError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly paneId: string;
+    readonly scrollback: string | undefined;
+    /** The command the pane ran; an `ssh ...` command gets remote hints. */
+    readonly command?: string | undefined;
+    readonly name = "AgentDiedOnSpawnError";
+    /** The spawned command is an ssh hop: remote causes, not wrapper locks. */
+    readonly remote: boolean;
+    constructor(agentName: string, paneId: string, scrollback: string | undefined, 
+    /** The command the pane ran; an `ssh ...` command gets remote hints. */
+    command?: 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.
+ *
+ * Background: the FK on `vcs_workspaces.agent` cascades on agent
+ * delete, so a naive `closeAgent` drops the workspace registry row
+ * but leaves the on-disk dir orphaned (mu can't see it via
+ * `mu workspace list / free / path` afterwards). Surfaced during
+ * the multi-agent dogfood teardown when three workspaces went
+ * orphaned silently.
+ *
+ * The fix: refuse close if a workspace exists; force the caller to
+ * decide. Two actionable resolutions:
+ *   - `mu workspace free <agent>` first, then close cleanly.
+ *   - `mu agent close <agent> --discard-workspace` to free the
+ *     workspace AND close the agent in one shot (lossy: pending
+ *     changes in the workspace are gone).
+ *
+ * Maps to exit code 4 (conflict) via the cli.ts handler.
+ */
+declare class WorkspacePreservedError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly workspacePath: string;
+    readonly name = "WorkspacePreservedError";
+    constructor(agentName: string, workspacePath: string);
+    errorNextSteps(): NextStep[];
+}
+/**
+ * The agent's pane and pi are up, but nothing answers on its control
+ * socket (`MU_CTL_SOCK`): the mu pi extension is not loaded, or, for a
+ * remote agent, the ssh command lacks the `-L` forward. Spawn does not
+ * throw it — the agent is usable by hand — but prints it as a warning;
+ * verbs that need the socket throw it.
+ */
+declare class AgentCtlUnreachableError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly workstream: string;
+    readonly socket: string;
+    readonly kind: "missing" | "refused";
+    readonly name = "AgentCtlUnreachableError";
+    constructor(agentName: string, workstream: string, socket: string, kind: "missing" | "refused");
+    errorNextSteps(): NextStep[];
+}
 /**
- * Resolve the actual executable to launch in an agent's pane for a given
- * `cli`. Honours the env var `MU_<UPPER_CLI>_COMMAND` (e.g. `MU_PI_COMMAND=
- * pi-alt` makes `--cli pi` actually exec `pi-alt`). Falls back to the cli
- * name itself, which is what users expect when their `pi` binary is on
- * `$PATH` under that exact name.
- *
- * Used by `spawnAgent` to pick the spawned command, and by reconcile's
- * orphan detector so externally-spawned panes running the resolved binary
- * are still recognised as agents.
+ * `mu agent abort` on an agent that does not run pi: there is no control
+ * socket to carry the abort, and mu does not silently signal the pane.
  */
-declare function resolveCliCommand(cli: string): string;
+declare class AgentAbortNeedsCtlError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly workstream: string;
+    readonly cli: string;
+    readonly name = "AgentAbortNeedsCtlError";
+    constructor(agentName: string, workstream: string, cli: string);
+    errorNextSteps(): NextStep[];
+}
+/** The abort was delivered but pi did not settle within the timeout. */
+declare class AgentAbortTimeoutError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly workstream: string;
+    readonly timeoutMs: number;
+    readonly name = "AgentAbortTimeoutError";
+    constructor(agentName: string, workstream: string, timeoutMs: number);
+    errorNextSteps(): NextStep[];
+}
 /**
- * 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`).
+ * `mu agent send --fresh` on an agent without a control socket (non-pi
+ * CLI, or forced `--via mux`): there is no one-operation new session.
  */
-declare function envVarNameForCli(cli: string): string;
+declare class AgentFreshNeedsCtlError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly workstream: string;
+    readonly cli: string;
+    readonly name = "AgentFreshNeedsCtlError";
+    constructor(agentName: string, workstream: string, cli: string);
+    errorNextSteps(): NextStep[];
+}
+/** `send --fresh` refused: pi is mid-turn, and a fresh session would abandon it. */
+declare class AgentBusyError extends Error implements HasNextSteps {
+    readonly agentName: string;
+    readonly workstream: string;
+    readonly name = "AgentBusyError";
+    constructor(agentName: string, workstream: string);
+    errorNextSteps(): NextStep[];
+}
+
+/** 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;
 /**
- * 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).
+ * 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 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;
+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;
 }
-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.
+ * 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 checkCommandResolvable(command: string): Promise<CommandResolutionResult>;
-interface SpawnAgentOptions {
-    name: string;
+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 "pi". 0.1.0 only really supports "pi" but the column
-     *  accepts any string for forward-compat with future multi-CLI support
-     *  (claude/codex). */
-    cli?: string;
-    /** The actual command to run in the pane. Defaults to the cli value. */
-    command?: string;
-    /** Window name to group this agent under. Defaults to the agent's name
-     *  (so each agent gets its own window). Multiple agents sharing a `tab`
-     *  share a window with multiple panes. */
-    tab?: string;
-    /** "full-access" (default) or "read-only". The schema stores it; today
-     *  the role isn't enforced (deferred to a future capabilities pass). */
-    role?: string;
-    /** Initial working directory for the spawned pane (`tmux -c <path>`).
-     *  When `workspace: true` is passed, this is ignored — the workspace
-     *  path is used instead. */
-    cwd?: string;
-    /** Override the tmux session name. Defaults to `mu-<workstream>`. */
-    tmuxSession?: string;
-    /** Auto-create a VCS workspace for this agent before spawning the
-     *  pane and use the workspace path as cwd. Backend defaults to
-     *  detection (jj > sl > git > none). */
-    workspace?: boolean;
-    /** Force a specific VCS backend (only meaningful with `workspace: true`). */
-    workspaceBackend?: VcsBackendName;
-    /** Optional ref to base the workspace on (only meaningful with
-     *  `workspace: true`). Backend-specific. */
-    workspaceFrom?: string;
-    /** Project root the workspace branches from (only meaningful with
-     *  `workspace: true`). Defaults to `process.cwd()`. */
-    workspaceProjectRoot?: string;
+    /** 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;
 }
 /**
- * Spawn a new agent in its tmux pane and register it in the DB.
+ * Send `signal` to the foreground process group of an agent's pane
+ * TTY. Default signal is SIGINT.
  *
- * Phases:
- *   1. Validate name + uniqueness.
- *   2. If --workspace: prestageWorkspace() (placeholder agent row +
- *      workspace dir + workspace row).
- *   3. createOrReusePane() in the workspace path (or opts.cwd).
- *   4. setPaneTitle + enableMuPaneBordersForPane.
- *   5. finalizeAgentRow() — patch placeholder pane_id to real (workspace
- *      path), or insert a fresh agent row (no-workspace path).
- *   6. awaitSpawnLiveness().
+ * 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`).
  *
- * Failure between any of (3)–(6) calls rollbackSpawn() to undo the
- * pane + row + workspace. The caller-visible error is preserved.
+ * Emits an `agent kick <name> (signal=..., pgid=..., comm=...)` event
+ * on success.
  */
-declare function spawnAgent(db: Db, opts: SpawnAgentOptions): Promise<AgentRow>;
+declare function kickAgent(db: Db, name: string, opts: KickAgentOptions): Promise<KickAgentResult>;
+
+type Transport = "ctl" | "mux";
+type SendResult = {
+    transport: Transport;
+    state?: CtlState;
+};
+type TransportSendOptions = SendOptions & {
+    /** How a busy pi queues the message. Default followUp. ctl only. */
+    mode?: "steer" | "followUp";
+    /** Force a transport instead of choosing by agent and text. */
+    via?: Transport;
+    /** Control socket path. Default: agentCtlSocket(db, agent). */
+    socket?: string;
+    /** Start a new pi session and send the text into it, as one ctl op. */
+    fresh?: boolean;
+    /** With fresh: abandon a running turn instead of refusing. */
+    force?: boolean;
+};
 /**
- * Default liveness window in milliseconds. 0 disables the check (useful
- * for fast tests that don't want to wait). Override via env var
- * `MU_SPAWN_LIVENESS_MS`.
- */
-declare function defaultSpawnLivenessMs(): number;
+ * True when the agent runs pi, so sends go through its control socket.
+ * The cli key decides when it names pi (or MU_<KEY>_COMMAND here runs
+ * pi). Otherwise the agent's own socket file decides: spawn removes any
+ * stale file before the pane starts, so a file at the derived path was
+ * bound by this agent's extension (or its ssh forward). That covers
+ * `--cli helper --command "pi-meta ..."`, whose command is not stored,
+ * without a schema change. `sock` defaults to the derived path; pass
+ * agentCtlSocket(db, agent) when a DB is at hand.
+ */
+declare function expectsCtl(agent: Pick<AgentRow, "cli" | "name" | "workstreamName">, sock?: string): boolean;
+declare function sendViaTransport(agent: AgentRow, text: string, opts: TransportSendOptions & {
+    socket: string;
+}): Promise<SendResult>;
 
 interface AgentRow {
     name: string;
@@ -1792,6 +1940,8 @@ interface AgentRow {
 interface LiveAgent extends AgentRow {
     state: RuntimeState;
     source: StateSource;
+    /** Control-socket link: ok / missing / refused for pi agents, n/a otherwise. */
+    ctl?: CtlLink;
     /** ISO 8601 time when the source entered this state. */
     since: string | null;
     reason?: string;
@@ -1846,12 +1996,14 @@ declare function refreshAgentTitle(db: Db, agentName: string, workstream: string
 declare function deleteAgent(db: Db, name: string, workstream: string): boolean;
 declare function isValidAgentName(name: string): boolean;
 /**
- * Send a single line of text to an agent's pane and submit it. Uses the
- * canonical bracketed-paste protocol from src/tmux.ts.
+ * Send text to an agent and submit it. A pi agent gets it through its
+ * control socket (AgentCtlUnreachableError when that does not answer —
+ * never a silent paste); a non-pi CLI, a slash command, or `via: "mux"`
+ * goes through the mux paste path. See src/agents/transport.ts.
  */
-declare function sendToAgent(db: Db, name: string, text: string, opts: SendOptions & {
+declare function sendToAgent(db: Db, name: string, text: string, opts: TransportSendOptions & {
     workstream: string;
-}): Promise<void>;
+}): Promise<SendResult>;
 /**
  * Read scrollback from an agent's pane. With no options, returns the full
  * scrollback (`-S - -E -`); with `lines: N`, returns only the last N lines.
@@ -3348,6 +3500,56 @@ declare function loadFullDag(db: Db, workstream: string, opts?: LoadFullDagOptio
 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;
 
+/**
+ * Identifies a generated shim on its own line, so re-linking (and
+ * `inspectLinks`) can tell it from an older inlined copy without
+ * depending on the import statement's exact shape.
+ */
+declare const MU_SHIM_MARKER = "// mu:shim";
+type LinkState = "ok" | "missing" | "stale-copy" | "foreign" | "dangling";
+interface LinkStatus {
+    path: string;
+    state: LinkState;
+    target?: string;
+}
+interface LinkOptions {
+    /** Root under which `.pi/` and `.agents/` live. Default `MU_PI_HOME ?? homedir()`. */
+    home?: string;
+}
+/** Raised when the destination holds something mu did not put there
+ *  (a real directory, or a symlink to another checkout without
+ *  `--force`). mu never deletes user files to make room. */
+declare class LinkConflictError extends Error implements HasNextSteps {
+    readonly path: string;
+    readonly reason: "not-a-symlink" | "foreign-symlink";
+    readonly current?: string | undefined;
+    constructor(path: string, reason: "not-a-symlink" | "foreign-symlink", current?: string | undefined);
+    errorNextSteps(): NextStep[];
+}
+/** Install the extension shim (or, with `copy`, an inlined copy pinned
+ *  to this version). `replacedCopy` is true when an existing file without
+ *  the shim marker was overwritten. */
+declare function linkPi(opts?: LinkOptions & {
+    copy?: boolean;
+}): {
+    path: string;
+    replacedCopy: boolean;
+};
+/** Symlink `<home>/.agents/skills/mu` to the package's `skills/mu`.
+ *  `previous` is the old link target when one was replaced. */
+declare function linkSkill(opts?: LinkOptions & {
+    force?: boolean;
+}): {
+    path: string;
+    target: string;
+    previous?: string;
+};
+/** Report the state of both installs without changing anything. */
+declare function inspectLinks(opts?: LinkOptions): {
+    extension: LinkStatus;
+    skill: LinkStatus;
+};
+
 type LogKind = "message" | "event" | "broadcast" | string;
 interface LogRow {
     /** Monotonic AUTOINCREMENT id. Use as the cursor for `--since`. */
@@ -4979,4 +5181,4 @@ declare function summarizeWorkstream(db: Db, opts: WorkstreamOptions): Promise<W
  */
 declare function teardownWorkstream(db: Db, opts: TeardownWorkstreamOptions): Promise<TeardownResult>;
 
-export { AGENT_STATE_GLYPH, type AddNoteOptions, type AddTaskOptions, type AdoptAgentOptions, type AdoptAgentResult, AgentDiedOnSpawnError, AgentExistsError, AgentNotFoundError, AgentNotInWorkstreamError, type AgentRow, AgentSpawnCliNotFoundError, AgentSpawnStartupError, type AmbientOptions, type AmbientResult, type AppendLogOptions, type ApplyResult, type BlockEdgeResult, CAPTURE_TRIGGER_DDL, CURRENT_SCHEMA_VERSION, type CaptureDb, type CaptureIntent, type CaptureOptions, type CaseCollision, type CheapDriftReport, type ClaimResult, type ClaimTaskOptions, ClaimerNotRegisteredError, type CloseAgentOptions, type CloseAgentResult, type CloseSubstate, type CloseTaskResult, type CommandResolutionResult, type CommandResolver, CrossWorkstreamEdgeError, CycleError, DEFAULT_SUBSTATE, DRIFT_REPORT_CAP, type Db, type DeleteTaskResult, type DoctorCheck, type DoctorStatus, type DoctorSummary, DriftDetectedError, type DriftRecord, type DriftReport, EXPECTED_TABLES, type EvidenceOption, type FileLockOptions, type FleetHazard, type FlushResult, type FsProbe, type FullDag, GLYPH, type GroupSummary, type HazardSeverity, type Hlc, HlcOverflowError, HlcParseError, HomeDirAsProjectRootError, type IdFromTitleResult, type IngestFromDbResult, type IngestResult, type InsertAgentInput, InvalidSubstateError, type InverseOp, KNOWN_INTENTS, KNOWN_VERBS, type KickAgentOptions, type KickAgentResult, type KickProcessExecutor, type KickSignal, type KnownIntent, type ListLiveAgentsOptions, type ListLogsOptions, type ListNotesOptions, type ListReadyOptions, type ListTasksOptions, type LiveAgent, type LiveAgentsView, type LoadFullDagOptions, type LoadWorkstreamSnapshotOptions, type LocalIntent, type LogKind, type LogRow, MACHINE_LOCAL_ENTITIES, MACHINE_LOCAL_TABLES, MachineIdentityMissingError, type MachineLocalEntity, type MachineLocalLoss, type MachineLocalTable, type MuxBackend, type MuxBackendName, MuxError, type MuxPane, type MuxPaneStatus, type MuxSession, type MuxWindow, type NewSessionOptions, type NewWindowOptions, NoForegroundProcessError, NoMultiplexerError, NothingToUndoError, OP_CTX_DDL, type Op, type OpContext, OpEntityNotSyncedError, OpKeyMalformedError, type OpenDbOptions, type OwnedTasksSummary, PANE_ID_RE, PEER_SHORT_LEN, PEER_STALE_MS, PORTABLE_TABLES, PaneNotFoundError, type ParkTaskOptions, type PeerSegment, type PeerStatus, type PortableTable, type RebuildOptions, type RebuildReport, RebuildTargetExistsError, RebuildTargetIsSourceError, type ReconcileMode, type ReconcileOptions, type ReconcileReport, type ReleaseResult, type ReleaseTaskOptions, type RemoveBlockEdgeResult, type RenderableOp, type RenderedOp, type ReparentTaskResult, type RoiBucket, type RuntimeState, SEGMENT_FORMAT_VERSION, SYNCED_ENTITIES, SchemaTooOldError, type SegmentDefect, type SegmentDefectKind, type SegmentLine, type SegmentManifest, type SendOptions, type SendWarning, type SetStatusOptions, type SetStatusResult, type SlugifyResult, type SpawnAgentOptions, type SplitWindowOptions, type StateReading, type StateSource, type StrandedWorkspaceOrphan, SubstateReasonRequiredError, type SyncPassResult, SyncPeerNotFoundError, SyncPeerRefAmbiguousError, SyncSourceNotFoundError, type SyncedEntity, TASK_STATUSES, TASK_STATUS_LIST, TASK_SUBSTATES, TASK_SUBSTATE_ROWS, TaskAlreadyOwnedError, type TaskEdgeWithStatus, type TaskEdges, type TaskEdgesWithStatus, TaskExistsError, TaskNotFoundError, TaskNotInWorkstreamError, type TaskNoteRow, type TaskPair, TaskParkStateError, TaskParkedError, type TaskRow, type TaskStatus, type TaskSubstate, type TaskWaitOptions, type TaskWaitRef, type TaskWaitResult, type TaskWaitTaskState, type TeardownResult, TmuxError, type TmuxExecResult, type TmuxExecutor, type TmuxPane, type TmuxSession, type TmuxWindow, type Track, UNKNOWN_REASON, UndoGroupNotFoundError, type UndoOptions, type UndoPlan, type UndoResult, UndoSupersededError, type UpdateTaskOptions, type UpdateTaskResult, type VcsBackend, type VcsBackendName, WORKSPACE_STALE_THRESHOLD, WorkspaceExistsError, type WorkspaceFailure, WorkspaceNotFoundError, type WorkspaceOrphan, WorkspacePathNotEmptyError, WorkspacePreservedError, type WorkspaceRow, type WorkspaceStaleness, WorkstreamExistsError, WorkstreamNameInvalidError, type WorkstreamOptions, type WorkstreamSnapshot, type WorkstreamSnapshotSlowFields, type WorkstreamSummary, activeMux, addBlockEdge, addNote, addTask, adoptAgent, agentKey, agentStateGlyph, agentStateHistogram, ambientFlush, ambientIngest, ambientSyncPass, appendLog, applyIncomingOp, applyOp, applyOps, assertValidPaneId, awaitPaneQuiescence, backendByName, capturePane, checkCaseCollisions, checkCheapDriftInvariant, checkCommandResolvable, checkDbInsideSyncDir, checkDrift, checkFleetHazards, checkNetworkMount, claimTask, classifyFsType, closeAgent, closeTask, compareHlc, composeAgentTitle, countProblems, createWorkspace, currentAgentName, currentOpContext, currentPaneTitle, decorateWithDirty, decorateWithStaleness, defaultDbPath, defaultSendDelayMs, defaultSendReadinessMs, defaultSpawnLivenessMs, defaultStateDir, deleteAgent, deleteTask, detectBackend, detectMux, discoverPeers, driftRemediation, emitEvent, ensureWorkstream, envVarNameForCli, findCaseCollisions, flushSegment, foregroundPgid, formatDriftRecord, formatHlc, formatPair, freeWorkspace, getAgent, getAgentByPane, getParallelTracks, getPrerequisites, getTask, getTaskEdges, getTaskEdgesWithStatus, getWaitPollCount, getWatermark, getWorkspaceForAgent, getWorkspaceStaleness, gitBackend, hasWorkMarker, idFromTitle, idFromTitleVerbose, ingestFromDb, ingestSegment, insertAgent, installCapture, isKickSignal, isPathInside, isTaskStatus, isValidAgentName, isValidPair, isValidPaneId, isValidTaskId, isValidWorkstreamName, isWorkspaceStale, jjBackend, kickAgent, killPane, killSession, latestSeq, listAgents, listAllOrphanWorkspaces, listBlocked, listGoals, listInProgress, listLiveAgents, listLogs, listNotes, listPanes, listPanesInSession, listReady, listRecentClosed, listRecentGroups, listSessions, listTasks, listTasksByOwner, listWindows, listWorkspaceOrphans, listWorkspaces, listWorkstreams, loadDoctorChecks, loadDoctorSummary, loadFullDag, loadWorkstreamSnapshot, loadWorkstreamSnapshotFast, loadWorkstreamSnapshotSlow, localMachineId, locksDir, mapLegacyStatus, mergeSnapshotFastSlow, mostRecentGroup, murmurAvailable, mux, muxByName, newSession, newSessionWithPane, newWindow, nextHlc, noneBackend, opSubject, openDb, openTask, paneExists, paneTTY, parkTask, parseAgentNameFromTitle, parseHlc, parseOpKey, parsePsTtyOutput, peerStatuses, planUndo, priorFieldValue, probeFilesystem, readAgent, readAgentStates, readFileLockMeta, readManifest, rebuildInto, receiveHlc, reconcile, refreshAgentTitle, releaseTask, remediationParagraph, removeBlockEdge, renderForest, renderOp, renderOpLine, renderTaskTree, repairPeer, reparentTask, resetCommandResolverForTests, resetKickProcessExecutor, resetMux, resetSleep, resetTmuxExecutor, resetWaitPollCount, resetWatermark, resolveActorIdentity, resolveCliCommand, resolveCliCommandWithSource, resolveGroupId, resolvePair, resolvePeerRef, roiBucket, segmentLineCount, segmentPath, selectLayout, sendToAgent, sendToPane, sessionExists, setCommandResolverForTests, setKickProcessExecutor, setMuxForTests, setPaneTitle, setSleepForTests, setTaskStatus, setTmuxExecutor, setWaitSleepForTests, setWaitStuckWarnForTests, setWatermark, slBackend, sleep, slugifyTitle, slugifyTitleVerbose, spawnAgent, splitWindow, summarizeOwnedTasks, summarizeWorkstream, syncDir, syncEnabled, syncPass, teardownWorkstream, tmux, tmuxBackend, transportNextSteps, undoGroup, unparkTask, updateTask, verifyAgainstManifest, waitForTasks, withCaptureSuppressed, withFileLock, withOpContext, workspacePath, workspacesRoot, yankCommandForCheck };
+export { AGENT_STATE_GLYPH, type AbortAgentOptions, type AbortResult, type AddNoteOptions, type AddTaskOptions, type AdoptAgentOptions, type AdoptAgentResult, AgentAbortNeedsCtlError, AgentAbortTimeoutError, AgentBusyError, AgentCtlUnreachableError, AgentDiedOnSpawnError, AgentExistsError, AgentFreshNeedsCtlError, AgentNotFoundError, AgentNotInWorkstreamError, type AgentRow, AgentSpawnCliNotFoundError, AgentSpawnStartupError, type AmbientOptions, type AmbientResult, type AppendLogOptions, type ApplyResult, type BlockEdgeResult, CAPTURE_TRIGGER_DDL, CURRENT_SCHEMA_VERSION, type CaptureDb, type CaptureIntent, type CaptureOptions, type CaseCollision, type CheapDriftReport, type ClaimResult, type ClaimTaskOptions, ClaimerNotRegisteredError, type CloseAgentOptions, type CloseAgentResult, type CloseSubstate, type CloseTaskResult, type CommandResolutionResult, type CommandResolver, CrossWorkstreamEdgeError, type CtlLink, CycleError, DEFAULT_SUBSTATE, DRIFT_REPORT_CAP, type Db, type DeleteTaskResult, type DoctorCheck, type DoctorStatus, type DoctorSummary, DriftDetectedError, type DriftRecord, type DriftReport, EXPECTED_TABLES, type EvidenceOption, type FileLockOptions, type FleetHazard, type FlushResult, type FsProbe, type FullDag, GLYPH, type GroupSummary, type HazardSeverity, type Hlc, HlcOverflowError, HlcParseError, HomeDirAsProjectRootError, type IdFromTitleResult, type IngestFromDbResult, type IngestResult, type InsertAgentInput, InvalidSubstateError, type InverseOp, KNOWN_INTENTS, KNOWN_VERBS, type KickAgentOptions, type KickAgentResult, type KickProcessExecutor, type KickSignal, type KnownIntent, LinkConflictError, type LinkState, type LinkStatus, type ListLiveAgentsOptions, type ListLogsOptions, type ListNotesOptions, type ListReadyOptions, type ListTasksOptions, type LiveAgent, type LiveAgentsView, type LoadFullDagOptions, type LoadWorkstreamSnapshotOptions, type LocalIntent, type LogKind, type LogRow, MACHINE_LOCAL_ENTITIES, MACHINE_LOCAL_TABLES, MU_SHIM_MARKER, MachineIdentityMissingError, type MachineLocalEntity, type MachineLocalLoss, type MachineLocalTable, type MuxBackend, type MuxBackendName, MuxError, type MuxPane, type MuxPaneStatus, type MuxSession, type MuxWindow, type NewSessionOptions, type NewWindowOptions, NoForegroundProcessError, NoMultiplexerError, NothingToUndoError, OP_CTX_DDL, type Op, type OpContext, OpEntityNotSyncedError, OpKeyMalformedError, type OpenDbOptions, type OwnedTasksSummary, PANE_ID_RE, PEER_SHORT_LEN, PEER_STALE_MS, PORTABLE_TABLES, PaneNotFoundError, type ParkTaskOptions, type PeerSegment, type PeerStatus, type PortableTable, type RebuildOptions, type RebuildReport, RebuildTargetExistsError, RebuildTargetIsSourceError, type ReconcileMode, type ReconcileOptions, type ReconcileReport, type ReleaseResult, type ReleaseTaskOptions, type RemoveBlockEdgeResult, type RenderableOp, type RenderedOp, type ReparentTaskResult, type RoiBucket, type RuntimeState, SEGMENT_FORMAT_VERSION, SYNCED_ENTITIES, SchemaTooOldError, type SegmentDefect, type SegmentDefectKind, type SegmentLine, type SegmentManifest, type SendOptions, type SendResult, type SendWarning, type SetStatusOptions, type SetStatusResult, type SlugifyResult, type SpawnAgentOptions, type SplitWindowOptions, type StateReading, type StateSource, type StrandedWorkspaceOrphan, SubstateReasonRequiredError, type SyncPassResult, SyncPeerNotFoundError, SyncPeerRefAmbiguousError, SyncSourceNotFoundError, type SyncedEntity, TASK_STATUSES, TASK_STATUS_LIST, TASK_SUBSTATES, TASK_SUBSTATE_ROWS, TaskAlreadyOwnedError, type TaskEdgeWithStatus, type TaskEdges, type TaskEdgesWithStatus, TaskExistsError, TaskNotFoundError, TaskNotInWorkstreamError, type TaskNoteRow, type TaskPair, TaskParkStateError, TaskParkedError, type TaskRow, type TaskStatus, type TaskSubstate, type TaskWaitOptions, type TaskWaitRef, type TaskWaitResult, type TaskWaitTaskState, type TeardownResult, TmuxError, type TmuxExecResult, type TmuxExecutor, type TmuxPane, type TmuxSession, type TmuxWindow, type Track, type Transport, UNKNOWN_REASON, UndoGroupNotFoundError, type UndoOptions, type UndoPlan, type UndoResult, UndoSupersededError, type UpdateTaskOptions, type UpdateTaskResult, type VcsBackend, type VcsBackendName, WORKSPACE_STALE_THRESHOLD, WorkspaceExistsError, type WorkspaceFailure, WorkspaceNotFoundError, type WorkspaceOrphan, WorkspacePathNotEmptyError, WorkspacePreservedError, type WorkspaceRow, type WorkspaceStaleness, WorkstreamExistsError, WorkstreamNameInvalidError, type WorkstreamOptions, type WorkstreamSnapshot, type WorkstreamSnapshotSlowFields, type WorkstreamSummary, abortAgent, activeMux, addBlockEdge, addNote, addTask, adoptAgent, agentKey, agentStateGlyph, agentStateHistogram, ambientFlush, ambientIngest, ambientSyncPass, appendLog, applyIncomingOp, applyOp, applyOps, assertValidPaneId, awaitPaneQuiescence, backendByName, capturePane, checkCaseCollisions, checkCheapDriftInvariant, checkCommandResolvable, checkDbInsideSyncDir, checkDrift, checkFleetHazards, checkNetworkMount, claimTask, classifyFsType, closeAgent, closeTask, compareHlc, composeAgentTitle, countProblems, createWorkspace, ctlRuntimeState, currentAgentName, currentOpContext, currentPaneTitle, decorateWithDirty, decorateWithStaleness, defaultDbPath, defaultSendDelayMs, defaultSendReadinessMs, defaultSpawnLivenessMs, defaultStateDir, deleteAgent, deleteTask, detectBackend, detectMux, discoverPeers, driftRemediation, emitEvent, ensureWorkstream, envVarNameForCli, expectsCtl, findCaseCollisions, flushSegment, foregroundPgid, formatDriftRecord, formatHlc, formatPair, freeWorkspace, getAgent, getAgentByPane, getParallelTracks, getPrerequisites, getTask, getTaskEdges, getTaskEdgesWithStatus, getWaitPollCount, getWatermark, getWorkspaceForAgent, getWorkspaceStaleness, gitBackend, hasWorkMarker, idFromTitle, idFromTitleVerbose, ingestFromDb, ingestSegment, insertAgent, inspectLinks, installCapture, isKickSignal, isPathInside, isTaskStatus, isValidAgentName, isValidPair, isValidPaneId, isValidTaskId, isValidWorkstreamName, isWorkspaceStale, jjBackend, kickAgent, killPane, killSession, latestSeq, linkPi, linkSkill, listAgents, listAllOrphanWorkspaces, listBlocked, listGoals, listInProgress, listLiveAgents, listLogs, listNotes, listPanes, listPanesInSession, listReady, listRecentClosed, listRecentGroups, listSessions, listTasks, listTasksByOwner, listWindows, listWorkspaceOrphans, listWorkspaces, listWorkstreams, loadDoctorChecks, loadDoctorSummary, loadFullDag, loadWorkstreamSnapshot, loadWorkstreamSnapshotFast, loadWorkstreamSnapshotSlow, localMachineId, locksDir, mapLegacyStatus, mergeSnapshotFastSlow, mostRecentGroup, murmurAvailable, mux, muxByName, newSession, newSessionWithPane, newWindow, nextHlc, noneBackend, opSubject, openDb, openTask, paneExists, paneTTY, parkTask, parseAgentNameFromTitle, parseHlc, parseOpKey, parsePsTtyOutput, peerStatuses, planUndo, priorFieldValue, probeFilesystem, readAgent, readAgentStates, readFileLockMeta, readManifest, rebuildInto, receiveHlc, reconcile, refreshAgentTitle, releaseTask, remediationParagraph, removeBlockEdge, renderForest, renderOp, renderOpLine, renderTaskTree, repairPeer, reparentTask, resetCommandResolverForTests, resetKickProcessExecutor, resetMux, resetSleep, resetTmuxExecutor, resetWaitPollCount, resetWatermark, resolveActorIdentity, resolveCliCommand, resolveCliCommandWithSource, resolveGroupId, resolvePair, resolvePeerRef, roiBucket, segmentLineCount, segmentPath, selectLayout, sendToAgent, sendToPane, sendViaTransport, sessionExists, setCommandResolverForTests, setKickProcessExecutor, setMuxForTests, setPaneTitle, setSleepForTests, setTaskStatus, setTmuxExecutor, setWaitSleepForTests, setWaitStuckWarnForTests, setWatermark, slBackend, sleep, slugifyTitle, slugifyTitleVerbose, spawnAgent, splitWindow, summarizeOwnedTasks, summarizeWorkstream, syncDir, syncEnabled, syncPass, teardownWorkstream, tmux, tmuxBackend, transportNextSteps, undoGroup, unparkTask, updateTask, verifyAgainstManifest, waitForTasks, withCaptureSuppressed, withFileLock, withOpContext, workspacePath, workspacesRoot, yankCommandForCheck };