@martintrojer/mu 0.3.2 → 0.4.1

package/docs/VISION.md

@@ -316,10 +316,11 @@ speaking for another.
   tests. Verification is the caller's job. (mu may grow optional
   verifying-runners later if friction surfaces; today it's an
   audit-trail discipline, not enforcement.)
-- **Not undoable.** No snapshots, no `mu undo`. `mu workstream
-  destroy --yes` is irreversible. Recovery is restoring `mu.db` from
-  a backup. Snapshots are deferred past 1.0 — the SQL escape hatch
-  + FK CASCADE behaviour cover most repair scenarios.
+- **DB-undoable, not substrate-undoable.** Destructive verbs
+  auto-capture whole-DB snapshots and `mu undo --yes` restores the
+  registry. That does not replay killed tmux panes or recreate freed
+  workspace directories; after a restore, reconciliation reports
+  ghosts/orphans and the caller decides what to re-spawn or adopt.
 
 ---
 
@@ -354,6 +355,49 @@ speaking for another.
    (SQLite hooks, fs.watch) are a future ask if anyone hits the
    latency cliff.
 
+7. **Every invocation is short-lived — except for two named
+   interactive readers.** mu is a CLI: each verb starts, mutates
+   or reads, prints, and exits. There is no daemon, no resident
+   state outside SQLite, no background process. Two verbs are
+   deliberately and narrowly exempt because they are interactive
+   *readers*, not background workers:
+
+   - `mu log --tail` — polls SQLite once per second; emits NDJSON
+     until SIGINT or the parent closes stdin.
+   - the TUI dashboard — rendered by `mu state --tui` explicitly or
+     by bare `mu` when stdout is attached to a TTY, until the user
+     quits with `q`/`Ctrl-C`. Plain `mu state` keeps the static-card
+     behaviour; non-TTY bare `mu` prints help instead of entering Ink.
+
+   Both share the same shape, and the shape is the predicate that
+   bounds the exception:
+
+   - **Interactive, not a daemon.** The process is owned by a
+     human (or a parent script) and dies the moment that owner
+     ends it. Nothing keeps it alive across sessions; nothing
+     restarts it.
+   - **Read-only against SQLite.** Neither verb writes. The TUI's
+     act-intents (claim, close, send, ...) yank the canonical
+     `mu <verb>` command into the clipboard and exit the
+     dashboard; every mutation still lands through a fresh
+     short-lived CLI invocation.
+   - **No resources beyond stdout, stdin, and a poll timer.** No
+     sockets, no file watches, no subscriptions to external
+     services, no spawned subprocesses, no inter-process state
+     beyond the SQLite reads any other CLI invocation already
+     does.
+   - **Human-TTY gated, with static/script fallbacks.** The TUI mode
+     activates when `--tui` is passed to `mu state` or when bare `mu`
+     sees `process.stdout.isTTY === true`. Default `mu state` prints
+     the static card. Non-interactive callers (pipes, CI, `--json`, or
+     `MU_NO_TUI=1`) never enter the TUI.
+
+   This is not a precedent for any other long-lived process. The
+   anti-feature pledges in [ROADMAP.md](ROADMAP.md) ("no daemon,
+   watcher, or background process beyond what tmux / SQLite give
+   us") remain in force; a third member of this exception class
+   would need its own promotion.
+
 ---
 
 ## What looking at a prior multi-agent runtime taught us

package/docs/VOCABULARY.md

@@ -49,15 +49,18 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **one-shot**          | Agent that exists for a single task and then terminates                  | "ephemeral", "transient"                           |
 | **workspace**         | A VCS-isolated checkout (jj workspace / sl worktree / git worktree / cp) | "branch" (it has one but isn't one), "checkout" (only for `none` backend) |
 | **workspace orphan**  | A directory under `<state-dir>/workspaces/<workstream>/` with no row in `vcs_workspaces`. Blocks subsequent `--workspace` spawns. Surfaced by `mu workspace orphans -w X` and `mu state -w X`. | "stray dir", "leftover workspace"                  |
-| **stale workspace**   | A workspace whose `parent_ref` is N commits behind the project's default branch HEAD (per the workspace's local refs cache). Rendered as a color-coded `behind` column (green ≤2, yellow 3–9, red ≥10) in `mu workspace list` and `mu state`; ≥10 triggers a one-line warn in `mu state`. Pure observation — mu never auto-fetches. | "out of date", "drifting"                          |
+| **stale workspace**   | A workspace whose `parent_ref` is N commits behind the project's default branch HEAD (per the workspace's local refs cache). Rendered as a color-coded `behind` column (green ≤2, yellow 3–9, red ≥10) in `mu workspace list` and `mu state`; ≥10 triggers a one-line warn in `mu state`, `mu task claim --for`, and `mu agent send` (or refusal on the two dispatch verbs with `--strict-staleness`). Pure observation — mu never auto-fetches. | "out of date", "drifting"                          |
 | **refresh**           | `mu workspace refresh <agent>` — rebase the agent's workspace onto a fresh base (default = backend's tracked main; `--from <ref>` overrides) WITHOUT touching the agent or pane. Refuses on dirty WC; surfaces conflicts as exit 5 with a resolve-in-place hint. The `none` backend errors (no VCS to rebase). | "recycle", "reset" (overloaded)                     |
 | **recreate**          | `mu workspace recreate <agent>` — free + create the agent's workspace in one shot. The between-wave "prep this worker for the next dispatch" verb. Reuses the previous backend unless `--backend` overrides; bases on current main unless `--from <ref>` overrides. Refuses on dirty WC the same way `free` does; `--force` discards the dirty edits (lossy). Sibling of **refresh**: refresh PRESERVES the worker's commits (rebases them onto fresh main); recreate THROWS THEM AWAY. | "recycle", "reset" (overloaded), "free+create" (only in commit messages) |
 | **backend**           | Implementation of `AgentBackend` or `VcsBackend`                         | "driver", "provider"                               |
 | **detector**          | Per-CLI pattern matcher for busy/permission/ready. Today mu has one (`detectPiStatus` in `src/detect.ts`); covers vanilla pi + any TUI wrapper that uses Braille spinner glyphs. Other CLIs spawned via `--cli <other>` may misclassify; trust scrollback over the emoji. | "matcher", "parser"                                |
 | **snapshot**          | A whole-DB backup (`<state-dir>/snapshots/<id>.db`) auto-captured before each destructive verb (workstream destroy, agent close, task close/reject/defer/release/delete, workspace free). Indexed by the `snapshots` table; restore via `mu undo`. | "checkpoint", "backup"                             |
 | **prune**             | Verb: bulk-drop rows from the snapshots collection per a policy (`mu snapshot prune` with `--keep-last`, `--older-than <D>d`, `--stale-version`, `--all`, or the bare GC-policy form). Sibling of the auto-GC that runs on every capture; the explicit verb is for the dogfood case where the auto-GC's count + age caps need an operator-driven supplement (e.g. "drop every snapshot whose schema_version is now stale"). Surgical single-row removal is `mu snapshot delete <id>`. | "reap", "sweep" (overloaded by workstream-destroy --empty) |
-| **export**            | A directory of plain markdown files produced by `mu workstream export` (one `.md` per task + `INDEX.md` + `README.md` + `manifest.json`). Survives `mu workstream destroy` (auto-run pre-destroy to `<state-dir>/exports/<ws>-<ts>/` unless `--no-export`). Idempotent: re-export against the same dir rewrites only changed files; deleted tasks are preserved with a banner. Markdown-only by design — no HTML/PDF, no embedded VCS. The inverse is **import** (markdown only; never `.db`). | "dump", "snapshot" (snapshot is the binary `.db`)  |
-| **import**            | The inverse of **export**: `mu workstream import <bucket-dir>` walks a v0.3 bucket directory and rebuilds every source-ws subdir as live tasks + edges + notes in the DB. Markdown-only by design (cross-machine `.db` is `mu undo` + snapshots). Per-source-ws transactional; refuses to merge silently into an existing workstream (use `--workstream <name>` for single-source rename, or destroy the existing one first). Owners reset to NULL on import (agents aren't restored); the original owner name survives in the markdown frontmatter. | "rehydrate", "restore" (restore = `mu undo`)       |
+| **machine_id**        | Per-state-directory uuid seeded on first `openDb` and stored in `machine_identity`. Identifies one mu DB across `mu db export` / `mu db import`; users do not configure it. | "device id", "host id"                              |
+| **db sync**           | The `mu db {export, import, replay}` cluster of verbs: whole-DB SQLite copy with manifest, per-workstream drift-detecting import, and manual replay from parked divergence sidecars. Explicit file handoff only; not live synchronization. | "live sync", "replication", "collab"              |
+| **divergence sidecar** | SQLite file at `<state-dir>/divergence/<ws>-<ts>.db` parked by `mu db import --force-source` before clobbering local divergent state. Later inspected or cherry-picked via `mu db replay`. | "conflict backup", "loser DB"                       |
+| **export**            | A directory of plain markdown files produced by `mu workstream export` (one `.md` per task + `INDEX.md` + `README.md` + `manifest.json`). Survives `mu workstream destroy` (auto-run pre-destroy to `<state-dir>/exports/<ws>-<ts>/` unless `--no-export`). Idempotent: re-export against the same dir rewrites only changed files; deleted tasks are preserved with a banner. Markdown-only by design — no HTML/PDF, no embedded VCS. Exports are now read-only artifacts for humans / git / docs; the lossless movement paths are **db sync** and `mu archive restore`. | "dump", "snapshot" (snapshot is the binary `.db`)  |
+| **import**            | Avoid as a generic noun unless naming `mu db import`. The removed `mu workstream import` bucket→DB round-trip was replaced by **db sync** for cross-machine handoff and `mu archive restore` for un-archive. | "rehydrate", "restore" (restore has specific meanings) |
 | **archive**           | An operator-named bucket of preserved task graphs (rows in `archives` + `archived_tasks` + `archived_edges` + `archived_notes` + `archived_events`). Cross-workstream and additive: one archive may accumulate snapshots from many workstreams under the same label. Outlives every source workstream; `archived_tasks.source_workstream` is intentionally TEXT (not an FK) so destroyed-workstream attribution survives. Distinct from a **snapshot** (binary whole-DB backup for `mu undo`) and an **export** (markdown files on disk). | "backup", "vault"                                 |
 | **archived task**     | A row in `archived_tasks`: a snapshot of a `tasks` row at archive time. Pins `status`, `impact`, `effort_days`, `owner_name`, and the original `created_at`/`updated_at` for retrospect ordering. The `(archive_id, source_workstream, original_local_id)` composite UNIQUE makes `mu archive add` idempotent at the (archive, workstream) granularity. | "closed task" (status-orthogonal)                  |
 | **archive label**     | The operator-facing TEXT name of an **archive**. Globally unique across the machine (NOT per-workstream — archives outlive workstreams). Shape: `/^[a-z][a-z0-9_-]{0,63}$/` (wider than workstream names because labels often encode workstream + date + purpose, e.g. `auth-2026-q1`). | "archive name" (in code; `label` only)             |
@@ -72,6 +75,19 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **reconcile**         | Verb: re-derive registry rows from substrate reality (tmux). Always runs in `mu agent list` and `mu doctor`. | "sync", "refresh"                              |
 | **adopt**             | Verb (`mu agent adopt`): register an existing tmux pane as a managed **agent**. The inverse of `mu agent list`'s 'orphan' state. Pane must be in the workstream's tmux session. | "import", "absorb"                       |
 | **pi-subagents**      | A different package by Nico Bailon for in-pi focused delegation. Mu and pi-subagents are complementary, not competing. | conflating with mu                                 |
+| **TUI**               | The interactive ink-based dashboard launched by bare `mu` in a TTY or explicitly by `mu state --tui`. Lives in `src/cli/tui/`. Read-only against SQLite (yanks, never executes). | "GUI", "interactive mode"                         |
+| **dashboard**         | The TUI's main screen — the grid of cards above the status bar. | "home screen", "main view"                         |
+| **card**              | A glanceable summary tile on the dashboard, identified by its toggle digit (0-9). Wrapped in a TitledBox. | "panel", "section" (overloaded)                    |
+| **popup**             | A fullscreen drill-down opened with `Shift+0`-`Shift+9` or a keybind-only shortcut such as `g` for DAG; single-popup invariant. Closed with `Esc`/`q`. | "modal", "dialog", "detail view"                   |
+| **TitledBox**         | The `<TitledBox>` component (`src/cli/tui/titled-box.tsx`) that renders a rounded border with the section header inset into the top border line. The visual primitive used by every card / popup / help overlay. | "header box", "box" (alone)                       |
+| **tick**              | The TUI's periodic data refresh (default 1s; `+/-/=` adjusts). Owned by a single `setInterval` in `<App>`. | "poll", "refresh" (verb sense), "frame"            |
+| **yank**              | Copy the canonical `mu` command for the focused row to the clipboard. Bound to `y` in every popup. | "copy", "export command"                           |
+| **footer**            | The persistent bottom line on the dashboard showing the last yank. Cleared with `c`. | "status line" (reserved for status bar), "toast"   |
+| **toast**             | Transient in-popup message (e.g. "tick floor 100ms" when `+` hits floor). | "notification", "banner"                           |
+| **act-intent**        | The conceptual action a `y` keypress would trigger. **Never executed by the TUI** — the user runs the yanked command in their shell. The R1 read-only contract: model drives the CLI. | "command intent", "action proposal"                |
+| **help overlay**      | The `?` / `F1` modal showing the global + per-popup keymap. Same TitledBox family as cards/popups. | "keys", "cheat sheet"                              |
+| **glanceable**        | Design property of cards: readable at a glance, no cursor, no row interaction. The contract is "never exhaustive" — long lists clip with `+M more` hint pointing at the popup. | "compact", "summary" (use the noun form for the data, the adjective for the property) |
+| **drill-down**        | Design property of popups: full-screen, focused, scrollable, filterable. The exhaustive view a card promises in its `+M more` hint. | "detail view", "expansion"                         |
 
 ---
 
@@ -137,10 +153,10 @@ cache; `mu agent list` reconciles on every call.
 | Verb                  | Effect                                                                      |
 | --------------------- | --------------------------------------------------------------------------- |
 | `mu agent free alice`       | Sets `alice.status = 'free'`. Agent stays alive. Means "I'm done with you for now; you're available."  |
-| `mu release feature_a`| Clears `tasks.owner` for `feature_a`. The agent who claimed it is unaffected.  |
+| `mu task release feature_a`| Clears the task owner for `feature_a`. The agent who claimed it is unaffected.  |
 | `mu agent close alice`      | Terminates alice's pane and removes from registry. Destructive.             |
 | `mu agent kick alice`       | Signals (default SIGINT) the foreground process group of alice's pane TTY. For wedged tool subprocesses (`find /`, busy-wait); the wrapping CLI itself is untouched. Refuses when the foreground IS the wrapping CLI. |
-| `mu detach alice`     | (Future) Tmux-detaches alice's pane without killing the process. Not in v1. |
+| *(none)*              | There is no detach verb. Use tmux detach to leave a workstream attached session without killing panes. |
 
 **Don't conflate `free` and `release`.** Free is about the *agent*;
 release is about the *task*.
@@ -152,7 +168,7 @@ release is about the *task*.
 | `mu task add <id> ...`                | Creates a new OPEN task                               |
 | `mu task close/open/reject/defer <id>` | Lifecycle transition                                 |
 | `mu task claim <task> [--for <agent>]`     | Atomic: sets `owner`, flips status to `IN_PROGRESS`   |
-| `mu release <task>`                   | Clears `owner`. Auto-flips `IN_PROGRESS` → `OPEN` (so the task re-enters the ready set); other statuses preserved. `--reopen` forces `OPEN` from `CLOSED`/`REJECTED`/`DEFERRED` |
+| `mu task release <task>`              | Clears `owner`. Auto-flips `IN_PROGRESS` → `OPEN` (so the task re-enters the ready set); other statuses preserved. `--reopen` forces `OPEN` from `CLOSED`/`REJECTED`/`DEFERRED` |
 | `mu task note <task> "..."`           | Appends to `task_notes`. Never edits prior notes.     |
 | `mu task notes <task> [--tail N \| --since <iso> \| --since-claim]` | List notes (oldest first). `--tail N` (alias `--last N`) prints last N; `--since <iso>` filters by `created_at`; `--since-claim` auto-resolves to the most recent `task claim` event timestamp. `--since` and `--since-claim` are mutually exclusive. |
 
@@ -222,7 +238,19 @@ For worked examples of each verb, see
 [USAGE_GUIDE.md](USAGE_GUIDE.md).
 
 This document is a *vocabulary* doc; it doesn't try to be a verb
-reference too.
+reference too. Rows here exist to keep names canonical, not to replace
+`--help`.
+
+| Operation | Canonical meaning |
+| --------- | ----------------- |
+| `mu db export <file>` | Whole-DB SQLite copy via `VACUUM INTO` plus `<file>.manifest.json` (`machineId`, `schemaVersion`, per-workstream `latestSeq`). |
+| `mu db import <file>` | Drift-detecting per-workstream import from an exported DB. Dry-run by default; `--apply` commits; five case branches: `IDENTICAL` / `FAST_FORWARD` / `LOCAL_AHEAD` / `CONFLICT` / `IMPORT`. |
+| `mu db replay <sidecar>` | Manual cherry-pick of tasks, notes, and eligible edges from a divergence sidecar parked by `mu db import --force-source`. |
+| `mu archive restore <label> --as <new-ws> [--source <orig-ws>]` | Lossless un-archive from `archived_*` rows into a fresh workstream. |
+
+Removed operation: `mu workstream import`. Use `mu db import` for
+cross-machine sync and `mu archive restore` for un-archive. Bucket
+exports remain read-only artifacts.
 
 ---
 
@@ -295,6 +323,9 @@ XDG-Base-Directory-Spec compliant. The state directory resolves as:
   `mu snapshot show <id>`). Default colocation: snapshots live
   next to the live DB, so per-test isolation works without env
   gymnastics.
+- `<state-dir>/divergence/<workstream>-<timestamp>-<suffix>.db` —
+  divergence sidecars parked by `mu db import --force-source` before
+  clobbering local state. Replay selected rows with `mu db replay`.
 - mu does NOT consult any agent-template directory. If pi-subagents
   is installed, its `~/.pi/agent/agents/` and `.pi/agents/` paths
   are pi-subagents' concern — not mu's.
@@ -348,5 +379,5 @@ documented as "workstream id" in column comments.
      it duplicated the canonical-terms table at the top of this file,
      drifted out of sync, and carried entries for rejected features
      (capability, agent-frontmatter `persistent: false`, the JS DSL,
-     the `defineOperation` registry). The table is the single source.
+     the operation-registry idea). The table is the single source.
      For deeper background, follow the links the table rows carry. -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martintrojer/mu",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "A persistent, observable crew of pi agents running in one tmux session per workstream, coordinated through a built-in task DAG.",
   "publishConfig": {
     "access": "public"
@@ -26,7 +26,7 @@
     "pi-package"
   ],
   "engines": {
-    "node": ">=20 <24"
+    "node": ">=20 <=24"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -39,36 +39,36 @@
   "bin": {
     "mu": "./dist/cli.js"
   },
-  "files": [
-    "dist",
-    "skills",
-    "docs",
-    "README.md",
-    "AGENTS.md"
-  ],
+  "files": ["dist", "skills", "docs", "README.md", "AGENTS.md"],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
+    "test:fast": "vitest run --config vitest.fast.config.ts",
     "test:watch": "vitest",
+    "test:watch:fast": "vitest --config vitest.fast.config.ts",
     "lint": "biome check src test",
     "lint:fix": "biome check --write src test",
     "format": "biome format --write src test",
-    "typecheck": "tsc --noEmit",
-    "prepare": "npm run build"
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "prepare": "npm run build",
+    "test:stress": "tools/test-stress.sh"
   },
   "dependencies": {
     "better-sqlite3": "^11.8.0",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.0",
     "execa": "^9.5.2",
+    "ink": "^5.0.0",
     "picocolors": "^1.1.1",
-    "zod": "^3.24.1"
+    "react": "^18.0.0",
+    "string-width": "^4.2.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@types/better-sqlite3": "^7.6.12",
     "@types/node": "^22.10.7",
+    "@types/react": "^18.0.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",
     "vitest": "^2.1.8"