@mu-crew/mu 3.13.3 → 4.0.0

package/docs/architecture/sync.md

@@ -1,159 +0,0 @@
-# Sync
-
-Machines share a workstream by exchanging ops through a shared folder
-(`MU_SYNC_DIR`) kept in step by any folder syncer, such as Syncthing. The ops
-themselves are described in [ops-log.md](ops-log.md). Overview:
-[ARCHITECTURE.md](../ARCHITECTURE.md). Why segments and not
-Litestream, cr-sqlite or a peer list, and why the DB must never sit in
-`MU_SYNC_DIR`:
-[ROADMAP § Rejected sync substrates](../ROADMAP.md#rejected-sync-substrates).
-
-## Segments
-
-`src/segments.ts` is the transport.
-
-- `flushSegment` appends this machine's unflushed ops to
-  `<MU_SYNC_DIR>/<machine_id>.jsonl`.
-- `ingestSegment` reads a peer segment from its watermark into
-  `applyOp`. Ambient ingest skips a peer that is caught up: the manifest
-  counts the watermark, and the segment's size, exact mtime and
-  manifest sha256 equal what the last clean read to the end recorded
-  (in `sync_fingerprints`). Any change, including a rewrite with a
-  backdated mtime, fails that check, so the full read hashes the file
-  and reports the mismatch. `mu sync` always reads every line.
-- When a peer segment has grown, ambient ingest resumes: a clean read
-  saved the byte offset and running sha256 state with the fingerprint
-  (`src/segment-resume.ts`), so only the appended bytes are read, and
-  they count only if the resumed hash equals the manifest's sha256. A
-  shrunk file, a stale manifest, a defect, or `mu sync` takes the full
-  read and whole-file verify. The resumed hash trusts the bytes it
-  already read, so a local change to that prefix (with the file still
-  growing) is caught only by `mu sync`.
-- Peer discovery is implicit: every non-self `*.jsonl` is a peer. A
-  peer disappears only when its segment is deleted.
-- A Syncthing conflict copy (`<machine>.sync-conflict-….jsonl`) is
-  ingested too, with its own watermark keyed by the file stem: it can
-  diverge from the original, so line counts are not comparable.
-
-**Single writer per file.** A machine appends only to its own segment,
-so nothing is contended and any folder syncer is adequate. Segments
-are regenerable, so there is no fsync. `src/file-lock.ts` stops two
-local `mu` processes from interleaving partial lines. A flush never
-appends without that lock: if another process still holds it after
-2 s (15 s for `mu sync`), the flush writes nothing, the ops stay
-pending in `ops`, and the next invocation appends them. A stale lock
-(holder crashed, older than 30 s) is broken as before.
-
-**Only `SYNCED_ENTITIES` and only this machine's ops are flushed.**
-Pane ids and absolute paths never leave the machine, and peers never
-echo each other's history.
-
-**Payload encoding.** `ops.payload` is TEXT that is usually JSON, but
-`mu log "text"` writes prose. The encoder passes valid JSON through
-verbatim, so the crc covers those exact bytes, and JSON-encodes
-anything else, unwrapping on ingest.
-
-## Robustness layers
-
-The first three checks stop ingest at the first bad record and advance
-the watermark only that far. The fourth is whole-file: it reports the
-defect without halting, because every line still present is valid, and
-only a fresh copy of the file clears it:
-
-| Layer | Catches |
-| --- | --- |
-| `JSON.parse` | a torn write (line lacks its trailing `,"crc"…}` framing) or a malformed shape (framing present). Same failure, different remediation: a cut transfer vs a writer bug |
-| crc32 per line | bit rot |
-| monotonic HLC | reorder, duplicate, truncation |
-| `.manifest` sidecar | truncation exactly on a line boundary |
-
-**Damage halts; refusal skips.** Halting is right for damage, where a
-gap looks the same as reordering. It is wrong for a well-formed line
-mu declines to project: a refusal leaves no hole, and halting would
-freeze the peer's watermark for good, since `mu sync --repair` only
-resets the watermark and re-reads into the same line. Ingest
-distinguishes three cases:
-
-| Line | Result |
-| --- | --- |
-| damaged (including a blank line) | halt |
-| a known machine-local entity | reported defect, skipped |
-| a historical log-only intent (`workstream.export` prose from mu < 1.1) | skipped silently, as flush and `--from` skip it |
-| an unrecognised entity | applied as a no-op, no defect (a reader behind the writer is normal in a mixed fleet) |
-
-`mu sync` suggests `--repair` only for defects a re-read can clear.
-
-**Sync never fails a command.** A truncated segment, a garbage segment,
-a sync dir that is a file, or a vanished directory warns on stderr and
-returns.
-
-## The ambient hook
-
-Sync is ambient, not a daemon: no watcher, no background process, no
-poll outliving a command. It happens because you already run `mu`
-constantly.
-
-The seam is `handle()` (`src/cli/handle.ts`), which every verb passes
-through and which is already async. It awaits `ambientIngest` and
-`ambientFlush`; the flush is async because it takes the file lock,
-while most verb bodies are synchronous
-better-sqlite3 code. One `await` before `fn(db)` and one after cover
-every verb.
-
-- **Ingest before the body**, so the verb reads the freshest state.
-- **Flush after the body**, so this invocation's ops reach the segment
-  now.
-- **Flush on the error path too.** A verb may commit ops before
-  throwing. Those ops are canonical, so withholding them would make
-  this machine's history depend on the exit code.
-
-`src/sync.ts` holds `ambientIngest`, `ambientFlush`, `ambientSyncPass`,
-`peerStatuses`, `ingestFromDb` (`mu sync --from <path>`) and
-`repairPeer` (`mu sync --repair <peer>`, a unique prefix; ambiguity is
-exit 4). A prefix names a machine, so it resets the watermark of the
-peer's segment and of every conflict copy of it.
-
-### Carve-outs
-
-| Surface | Behaviour | Why |
-| --- | --- | --- |
-| `MU_SYNC_DIR` unset | one `if` on one env var; no filesystem touch | the single-machine case pays nothing (measured: baseline; about 3ms with one peer) |
-| `mu sql` | opts out (`handle(..., { ambientSync: false })`) | an ingest changing a row count mid-inspection reads as a mu bug |
-| `mu sync` | opts out and runs the pass itself | otherwise the report prints "ingested 0" right after ingesting |
-| the TUI | slow tick only (10s), one pass per beat across tabs, `quiet: true` | the fast tick can go to 100ms; the TUI owns the screen, so problems show on the Doctor card |
-
-## Out-of-order arrival
-
-An `edge` or `note` put whose task has not arrived yet skips as
-`absent`, correctly. Ingest still advances the watermark past it, so
-without a second pass it would never land. Peers are discovered by
-`localeCompare` over random-UUID filenames, so the arrival order is a
-coin flip per fleet.
-
-`reprojectDeferredOps` (`src/apply.ts`) re-queries the log for note and
-edge puts that are resolvable now but unprojected. It skips ops whose
-parent task is gone and keys with a newer `del`, so a deleted edge is
-never resurrected and an orphan is not retried forever. It runs once
-per ingest pass, not per peer, because an edge in one segment may name
-a task in another. Ambient ingest runs it only while SQLite's
-`user_version` is 1. `applyIncomingOp` sets that marker in the same
-transaction whenever an op changes a row or defers (`absent`), whether
-it came from a segment, `--from`, or an SDK caller; the repair clears
-it. A process that dies between
-the two leaves the marker set, so the next invocation runs the repair.
-`mu sync` and `--from` always run it.
-
-There is no retry queue. A queue would be a second source of truth and
-would not survive a short-lived `mu` process when the parent arrives
-days later.
-
-## Mixed-fleet hazards
-
-`src/fleet-hazards.ts` adds three checks to the default `mu doctor`,
-all no-ops when `MU_SYNC_DIR` is unset:
-
-| Check | Severity |
-| --- | --- |
-| `MU_DB_PATH` inside `MU_SYNC_DIR` | fail |
-| DB on a network mount | warn |
-| two workstream names differing only by case | warn |

package/docs/architecture/tui.md

@@ -1,165 +0,0 @@
-# TUI architecture
-
-The TUI is a read-only, live-updating dashboard of 10 cards on `ink`.
-It lives entirely under `src/cli/tui/`, the only place ink and react
-are imported (a [ROADMAP](../ROADMAP.md#anti-feature-pledges) pledge).
-CLI verbs stay the mutation API: the TUI yanks `mu` commands and the
-operator runs them. Overview: [ARCHITECTURE.md](../ARCHITECTURE.md).
-Press `?` in the TUI for the keymap.
-
-## Entry points
-
-- Bare `mu` launches the TUI when `process.stdout.isTTY` is true. It
-  loads every workstream and picks the initial tab with the focus
-  ladder in `src/cli/tui-launch-focus.ts`: `$MU_SESSION` → tmux session
-  name → cwd inside a workspace → cwd equal to a workspace's project
-  root (`src/project-root.ts`; latest activity breaks ties) → tab 0.
-  With no workstreams it prints `mu --help` plus
-  `Get started: mu workstream init <name>` and exits 0.
-- On non-TTY stdout (pipes, CI, most agent calls) bare `mu` prints help.
-  `MU_NO_TUI=1` forces that path inside a terminal.
-- `mu state` is the static card; `mu state --tui` selects the TUI.
-- The import stays dynamic (`await import("./cli/tui/index.js")`). A
-  static import of ink anywhere else would pull the TUI graph into the
-  help, version and `--json` paths.
-
-## Cluster shape
-
-| Files | Role |
-| --- | --- |
-| `index.ts`, `escapes.ts` | `runTui` entry; alt-screen and SGR mouse-mode lifecycle; pure escape bytes |
-| `app.tsx` | `<App>` root: popup state machine, global keymap, tabs, footer |
-| `state.ts` | `useDashboardSnapshot` poll loop (fast and slow tiers) |
-| `keys.ts`, `keymap-spec.ts`, `help.tsx` | pure key dispatch; the keymap source of truth that drives both dispatch and the `?` overlay |
-| `mouse.ts`, `use-popup-action-queue.ts` | vendored SGR mouse parser with double-click; one queued popup action per render |
-| `layout.ts`, `columns.ts`, `wrap-ansi.ts`, `use-terminal-size.ts` | responsive columns and row budgets; aligned clipping; ANSI-aware wrapping; resize hook |
-| `popup-input.ts` | `usePopupInput`: popup keyboard, off while the help overlay covers the popup |
-| `titled-box.tsx`, `popup-shell.tsx`, `list-row.tsx`, `padded-rows.tsx`, `status-bar.tsx`, `tab-strip*.ts(x)` | chrome primitives |
-| `format-helpers.ts`, `agent-display.ts` | shared formatters and agent-row display |
-| `use-popup-filter.tsx`, `use-status-filter.tsx`, `use-notes-drill.ts` | `/` filter; status (`o`/`i`/`c`) and substate (`p`/`w`) toggles; shared notes drill |
-| `yank.ts`, `tuicr.ts`, `lazygit.ts`, `tmux-attach.ts` | clipboard; the alt-screen handoffs |
-| `cards/*.tsx` | the 10 dashboard cards, plus `_placeholder.tsx` |
-| `popups/*.tsx` | one fullscreen popup per card, plus `dag.tsx` (`g`), `all-tasks.tsx` (`t`), the `task-list-popup.tsx` scaffold, `drill.tsx`, `task-detail.tsx`, `cursor-row.tsx`, `scroll.ts`, `viewport.ts`, `show-loader.ts` |
-
-## State machine
-
-`<App>` owns:
-
-- **Popup state:** `null` (dashboard) or one popup id. One popup at a
-  time; `Esc` or `q` returns to the dashboard. `?` over a popup hides
-  it (`display="none"`) and turns its keyboard off rather than
-  unmounting it, so its cursor, filter and drill survive the overlay.
-- **Card visibility:** toggled by `0`-`9`.
-- **Tick rate:** fast tick, 1s default, adjusted with `+` / `=` and
-  `-`. There is no reset key: `0` toggles the Commits card.
-- **Active workstream tab:** `Tab` / `Shift-Tab` cycles when there are
-  two or more. A torn-down workstream keeps its tab position and
-  renders dimmed with strikethrough until the name is recreated. A
-  torn-down single workstream shows its normally hidden tab.
-- **Footer flash:** a transient status-bar message.
-
-Popups own their local state (cursor, filter, drill mode, local modes
-such as Workspaces' `list` / `commits` / `show`). They never mutate App
-state. They receive a read-only props bag: `snapshot`, `db`,
-`workstream`, `fastTickNonce`, `slowTickNonce`, `yank`, `onClose`,
-`onModeChange`, `onFilterEditingChange`, `onFooter`.
-
-## Polling tiers
-
-| Tier | Interval | Loader | Reads | Cost |
-| --- | --- | --- | --- | --- |
-| fast | 1s, adjustable | `loadWorkstreamSnapshotFast` | SQL only: tasks, tracks, workspace rows, recent events, workspace orphans | p50 < 1ms |
-| slow | 10s (`SLOW_TICK_MS`) | `loadWorkstreamSnapshotSlow` | subprocesses: agent liveness and state, workspace dirty status, recent commits, doctor summary | p50 hundreds of ms |
-
-`mergeSnapshotFastSlow` merges the last slow result into every fast
-render, so cards never flicker through loading. `r` / `F5` runs both
-tiers now. A tab switch clears the slow cache and fetches eagerly.
-`snapshotKey` returns the same `data` reference across no-op ticks, so
-React's diffing short-circuits. The slow tick also runs ambient sync
-([sync.md](sync.md#carve-outs)).
-
-## Render geometry
-
-`layout.ts`:
-
-- **Columns by width:** stacked below 120 columns, then 2 at 120, 3 at
-  180, 4 at 240. Stream cards (Commits, Activity log) trail; Commits
-  trails last.
-- **Row budgets:** each card has `min` / `max` / `chrome`. The allocator
-  distributes rows up to `max` first so a noisy list cannot crowd its
-  siblings, then gives any spare rows to the cards still hiding data,
-  in proportion to what each hides. A column with hidden data always
-  fills its height; short lists are not padded. Overflow shows as
-  `+N more · Shift+N` in the card's bottom border.
-- **Card placement:** `arrangeColumns` starts from the group packing
-  and moves or swaps cards between columns while that lowers the total
-  hidden rows (a local optimum, well under 1ms). It keeps the previous
-  assignment unless the new one hides at least max(3, 10%) fewer rows,
-  so cards do not jump as counts change. A resize, toggle or tab
-  switch reflows freely.
-- **Culling:** when even minimum budgets do not fit, cards drop by
-  priority (Doctor → Recent → Workspaces → …) and the screen shows
-  `+N cards hidden · resize taller`.
-
-`wrap-ansi.ts` wraps by visual width (`string-width`) and closes open
-SGR state on every exit path, so a fragment without a trailing
-`\x1b[0m` cannot bleed into ink chrome. Drill bodies are space-padded
-to the exact box width, or ink's `wrap="truncate"` ANSI miscount eats
-the right border.
-
-## Read-only, with handoffs
-
-Every popup row exposes one canonical `mu` command through `y`.
-`yank.ts` probes pbcopy, wl-copy, xclip, xsel and clip.exe, then falls
-back to OSC-52 written to `/dev/tty`, since ink owns stdout.
-
-The handoffs leave the alt screen, disable mouse mode, run a
-foreground subprocess, and restore both on exit:
-
-- `t` in any `git show` drill runs `tuicr -r <sha>` in the project root
-  or workspace.
-- `l` in the Commits popup runs lazygit.
-- `a` in the Agents popup attaches to the agent's mux pane.
-
-A TUI gesture that mutates state needs a ROADMAP entry first.
-
-## Input
-
-Mouse support uses SGR mouse mode. `mouse.ts` parses
-`ESC[<button;x;y;M/m`, detects double-clicks, and exposes `useMouse()`.
-A double-click on a card opens its popup. A double-click on a popup row
-emits one `clickRow` action (the 0-based body row) through the action
-queue. The popup maps that row through its own scroll window and
-header strips (`clickedItem` in `popups/scroll.ts`), then focuses and
-drills the item. App cannot do the mapping: only the popup knows its
-window start and strip rows.
-
-`keys.ts` holds `dispatchGlobalKey` (dashboard), `dispatchPopupKey`
-(popup), and `shouldSwallowGlobalKey` (keys a popup consumes).
-
-## Drill recursion
-
-List popups drill with `Enter`. Each popup pins the drilled row's
-identity at `Enter` (task, agent, check, commit sha, log seq, track
-goals), so a refresh that reorders or extends the list cannot move an
-open drill to another row. `DrillScrollView`
-(`popups/drill.tsx`) is the shared scrollable text leaf: Workspaces'
-git show, Agents' scrollback, Activity log payloads, and Doctor
-remediation. Task popups drill into `TaskDetailDrill`
-(`popups/task-detail.tsx`, the notes timeline). Tracks chains track →
-task list → `TaskDetailDrill`.
-
-`useDrillKeymap` owns scroll state. An optional `resetKey` resets
-scroll on identity change while a tick refresh keeps it, and
-`onScrollChange` serves the DAG popup's focused-root tracking. Body
-wrap metadata is shared so the scroll clamp and the painter cannot
-disagree. Subprocess-backed drills use `popups/show-loader.ts`, which
-keeps the prior body during a refetch.
-
-## Test seam
-
-See `test/README.md`. `test/_ink-render.ts` provides
-`createInkInputStream`, `createInkCaptureStream`, `simulateInput` and
-`latestRenderedFrame`: mount a popup or `<App>`, drive keys, assert on
-the visible frame and spy callbacks. Source greps are for narrow
-structural guards only, never behaviour.

package/docs/guide/tui.md

@@ -1,98 +0,0 @@
-# How to use the TUI dashboard
-
-The dashboard is read-only. To change anything, press `y` on a row to
-copy its `mu` command, then run it in your shell.
-
-## Open it
-
-```bash
-mu                        # every workstream, as tabs
-mu state --tui -w a,b     # only these workstreams
-MU_NO_TUI=1 mu            # print help instead
-```
-
-Bare `mu` opens the dashboard only when stdout is a terminal. Scripts
-get help text. For a static card or JSON, use `mu state` and
-`mu state --json`. Quit with `q` or `Ctrl-C`.
-
-The first active tab is the first match of: `$MU_SESSION`, the current
-`mu-<ws>` tmux session, a workspace that contains the current
-directory, a project root that contains it, then the first tab.
-
-## Read the cards
-
-| Key | Card | Shows |
-| --- | ---- | ----- |
-| `0` | Commits | recent commits in the project root |
-| `1` | Agents | agents with runtime state, CLI, and role |
-| `2` | Tracks | parallel tracks of tasks |
-| `3` | Ready | tasks with no open blockers |
-| `4` | Activity log | recent ops as prose |
-| `5` | Workspaces | per-agent workspaces, commits behind, dirty flag |
-| `6` | In-progress | `IN_PROGRESS` tasks |
-| `7` | Blocked | tasks with an open blocker |
-| `8` | Recent | recently closed tasks |
-| `9` | Doctor | quick health checks |
-| `g` | DAG | the whole task graph (popup only) |
-| `t` | All tasks | every task, sortable (popup only) |
-
-A digit hides or shows its card. `Shift` plus the digit opens the
-card as a popup. Only one popup is open at a time.
-
-Cards reflow into 2, 3, or 4 columns at 120, 180, and 240 columns
-wide. On a short terminal, low-priority cards drop out and the footer
-says how many are hidden.
-
-With two or more workstreams, a tab strip appears. `Tab` and
-`Shift-Tab` switch tabs. A `*` marks `scratch`. A torn-down
-workstream's tab stays, dimmed and struck through.
-
-## Drill into rows
-
-`Enter` opens the focused row. On a task it opens the task's notes.
-`Esc` or `q` goes back one level.
-
-- Tracks: track, then its tasks, then a task's notes.
-- Workspaces: workspace, then its commits, then `git show`.
-- Commits: commit, then the backend's show view.
-- Activity log: the full text of the entry.
-- Doctor: the remediation text for the check.
-
-In a `git show` view, `t` opens `tuicr -r <sha>`. In the Commits popup,
-`l` opens lazygit. In the Agents popup, `a` attaches to the agent's
-pane. The dashboard comes back when the tool exits.
-
-## Filter and sort
-
-`/` filters the popup's rows by substring as you type. `Enter` keeps
-the filter. `Esc` clears it.
-
-In the DAG and All-tasks popups, `o`, `i`, and `c` toggle `OPEN`,
-`IN_PROGRESS`, and `CLOSED`, `p` toggles parked tasks, and `w` toggles
-tasks closed as anything but `done`. In All tasks, `b`
-cycles the blocked filter and `s` cycles the sort: ROI, recency, age,
-id.
-
-## Keys
-
-| Where | Keys | Action |
-| ----- | ---- | ------ |
-| dashboard | `+` or `=`, `-` | refresh faster (100 ms floor), slower (10 s ceiling) |
-| dashboard | `r` or `F5` | refresh now |
-| dashboard | `c` | clear the footer |
-| any | `?` | help overlay |
-| popup | `j` `k` | move |
-| popup | `g` `G` | top, bottom |
-| popup | `Ctrl-D` `Ctrl-U`, `PgDn` `PgUp` | half page, full page |
-| popup | `y` | copy the row's `mu` command |
-
-The mouse works for navigation only. Double-click a card to open it,
-double-click a row to drill in, and scroll inside lists. There is no
-mouse binding for back.
-
-## Refresh
-
-Task, track, and log data refreshes every second from SQLite. Agent
-state, workspace dirty flags, commits, and doctor checks come from
-subprocesses and refresh every 10 seconds. Switching tabs refreshes
-the new tab at once.