@martintrojer/mu 0.3.1 → 0.4.0

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,8 +49,9 @@ 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"                             |
@@ -69,8 +70,21 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **substrate**         | An external system mu depends on (tmux, jj, sl, git, sqlite)             | "dependency" (means npm dep), "service"            |
 | **operation**         | A canonical mu verb (e.g. `mu task add`). Each verb is a thin CLI wrapper over a typed function in `src/*.ts` — the SDK and the CLI share one surface. | "command" (overloaded), "action"             |
 | **reconcile**         | Verb: re-derive registry rows from substrate reality (tmux). Always runs in `mu agent list` and `mu doctor`. | "sync", "refresh"                              |
-| **adopt**             | Verb: 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"                       |
+| **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"                         |
 
 ---
 
@@ -136,9 +150,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 detach alice`     | (Future) Tmux-detaches alice's pane without killing the process. Not in v1. |
+| `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. |
+| *(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*.
@@ -150,8 +165,9 @@ 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. |
 
 ---
 
@@ -316,8 +332,8 @@ XDG-Base-Directory-Spec compliant. The state directory resolves as:
 | `XDG_STATE_HOME`             | Inherited; mu uses `<XDG_STATE_HOME>/mu` by default  |
 | `MU_SEND_DELAY_MS`           | Delay between bracketed paste and Enter (default `500`) |
 | `MU_TMUX_SOCKET`             | Override tmux socket (`-L <name>`); default uses `$TMUX` |
-| `MU_<UPPER_CLI>_COMMAND`     | Override the executable launched for `--cli <cli>` (e.g. `MU_PI_COMMAND=pi-alt` makes `--cli pi` exec `pi-alt`). Accepts multi-word strings (`MU_PI_COMMAND="pi-alt --some-flag"`); tmux exec's via a shell. Reconcile also treats the resolved binary as agent-worthy when surfacing orphan panes. |
-| `MU_SPAWN_LIVENESS_MS`       | After spawn, wait this many ms then verify the pane is still alive. Default 1500. Set to 0 to disable (useful in CI). On detected death, the DB row is rolled back and `AgentDiedOnSpawnError` is thrown with the captured scrollback. |
+| `MU_<UPPER_CLI>_COMMAND`     | Override the executable launched for `--cli <cli>` (e.g. `MU_PI_COMMAND=pi-alt` makes `--cli pi` exec `pi-alt`; hyphens in the cli key become underscores in the env var name, so `--cli pi-meta` reads `MU_PI_META_COMMAND`). Accepts multi-word strings (`MU_PI_COMMAND="pi-alt --some-flag"`); tmux exec's via a shell. Reconcile also treats the resolved binary as agent-worthy when surfacing orphan panes. When this env var supplies the override (and `--command` did not), the spawn-success line surfaces the env-var name (`Spawned worker-1 (pi-meta via $MU_PI_META_COMMAND)`) so stale aliases are visible without `mu agent show`. |
+| `MU_SPAWN_LIVENESS_MS`       | After spawn, wait this many ms then verify the pane is still alive AND scan the tail of its scrollback for known startup-error patterns (provider auth failures — `No API key found for X`, `401 Unauthorized`, … — plus shell-level `command not found` / `No such file or directory` when the spawned binary vanished post-pre-flight). Default 1500. Set to 0 to disable (useful in CI). On detected death the DB row is rolled back and `AgentDiedOnSpawnError` is thrown with the captured scrollback; on a startup-error match (pane alive but parked at an error prompt) the row is rolled back and `AgentSpawnStartupError` is thrown with the matched line + remediation hints. The complementary pre-flight check (PATH lookup of `--cli`'s resolved binary BEFORE any side effect) is not env-tunable; on miss it throws `AgentSpawnCliNotFoundError` with no orphan workspace / pane / row. |
 
 These mirror pi-subagents' `PI_SUBAGENT_*` env vars in spirit but live
 in a separate namespace so the two can coexist in one pi session.
@@ -345,5 +361,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.1",
+  "version": "0.4.0",
   "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",
@@ -37,7 +37,7 @@
     }
   },
   "bin": {
-    "mu": "./dist/cli.js"
+    "mu": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -50,25 +50,31 @@
     "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"