@mu-crew/mu 3.2.0 → 3.3.0

package/docs/guide/stop-a-worker.md

@@ -0,0 +1,64 @@
+# How to stop a worker
+
+Use the gentlest step that works, in this order: abort, kick, close.
+
+## Abort the turn (pi agents)
+
+```bash
+mu agent abort worker-1 -w auth
+```
+
+`mu agent abort` does what Esc does in the pane, through the control
+socket, and waits for pi to settle. It kills the running tool and
+keeps the session and its context. It works for remote agents too.
+
+- An idle agent is left alone (exit 0).
+- Exit 5 means pi was still busy after `--timeout` (default 30 s).
+  Go to the next step.
+- A follow-up queued before the abort does not run. pi puts it back
+  into the pane's editor, unsent. Send it again if you still want it.
+
+To give the agent new work after the abort, send with `--fresh`. See
+[Dispatch work to a worker](dispatch.md#pick-the-send-mode).
+
+## Kick the foreground process
+
+Use `mu agent kick` when abort failed, when the agent is not pi, or
+when pi's socket is gone:
+
+```bash
+mu agent kick worker-1 -w auth                    # SIGINT
+mu agent kick worker-1 -w auth --signal SIGTERM
+mu agent kick worker-1 -w auth --signal SIGKILL
+```
+
+mu finds the foreground process group on the pane's TTY and signals
+it. This is the fix for a worker stuck on an unbounded `find /` or a
+busy-wait loop. Typing Ctrl-C into the pane does not work, because
+the agent CLI catches it as input.
+
+- Kick refuses with `NoForegroundProcessError` when the foreground
+  process is the agent CLI itself. Close the agent instead.
+- Kick works on local panes only. On herdr it works on Linux only.
+
+To prevent the problem, scope worker prompts to the workspace. Do not
+ask for filesystem-wide `find` or `grep -r /`.
+
+## Close the agent
+
+```bash
+mu agent close worker-1 -w auth
+```
+
+Close kills the pane and deletes the agent row. A clean workspace is
+freed with it. If the workspace has edits or commits, close refuses
+with exit 4. Then do one of these:
+
+- Run `mu workspace free worker-1 -w auth --commit` to commit pending
+  changes and free the workspace, then close.
+- Run `mu agent close worker-1 -w auth --discard-workspace` to free
+  and close in one step. You lose the changes.
+
+If the worker owned a task, its pane is gone, so the reaper returns
+the task to `OPEN` on the next reconcile. A `mu task wait` on that task
+exits 6.

package/docs/guide/sync.md

@@ -0,0 +1,78 @@
+# How to sync between machines
+
+Set one environment variable to the same folder on every machine:
+
+```bash
+export MU_SYNC_DIR=$HOME/Sync/mu
+```
+
+Every `mu` command then writes your ops to
+`$MU_SYNC_DIR/<machine_id>.jsonl` and reads every other `.jsonl` file
+in the folder. There is no export, import, or peer list. A new machine
+appears when its file does.
+
+```bash
+# laptop
+mu task add auth_fix -w app -t "Fix the auth redirect" -i 80 -e 2
+# devserver, after the folder syncs
+mu task close auth_fix -w app --evidence "shipped in #412"
+```
+
+## Keep the DB out of the sync folder
+
+Never put `MU_DB_PATH` inside `MU_SYNC_DIR`. A live SQLite DB is three
+files (`mu.db`, `-wal`, `-shm`). A file syncer copies them out of
+order and can bring back a stale `-wal`, which corrupts the DB with no
+error. `mu doctor` fails the `db-vs-sync` row when you do this.
+
+Also keep the DB off NFS, SMB, and sshfs. `mu doctor` warns in the
+`db-filesystem` row.
+
+## Move the files
+
+mu never runs ssh, scp, or rsync. Segments are append-only and each
+file has one writer, so any file mover works:
+
+| Mover | How |
+| ----- | --- |
+| Syncthing (recommended) | share `$MU_SYNC_DIR` on every machine |
+| rsync | `rsync -av host:$MU_SYNC_DIR/ $MU_SYNC_DIR/`, in both directions |
+| sshfs or NFS | point `MU_SYNC_DIR` at the mounted folder |
+| scp or a USB stick | copy the `.jsonl` files whenever you like |
+
+Copying is safe in any direction and any number of times. An
+interrupted copy leaves a cut last line that mu skips until the next
+copy completes it.
+
+On macOS, do not use iCloud Drive, Dropbox, Google Drive File Stream,
+or OneDrive Files On-Demand. They replace idle files with network
+stubs, and mu reads the folder on every command, so commands hang.
+
+## Check peers
+
+```bash
+mu sync
+```
+
+The table lists each peer by `machine_id` prefix, when you last saw
+it, and `behind`: lines you hold but have not applied. A non-zero
+`behind` is either a copy in flight or a cut file.
+
+```bash
+mu sync --repair c8ec                              # re-read a peer's file from the start
+mu sync --from /mnt/devserver/.local/state/mu/mu.db # read a peer's DB directly
+MU_SYNC_DIR=/media/usb-stick mu state              # one-off folder
+```
+
+Ingest is idempotent, so `--repair` is safe at any time.
+
+## Know what travels
+
+Workstreams, tasks, edges, and notes travel. Agents and workspaces
+stay on their machine, because a pane id and a local path mean nothing
+elsewhere. So task ownership does not sync: a task claimed on the
+devserver shows no owner on your laptop.
+
+Merges are per field. If the laptop changes a task's impact while the
+devserver closes it, both changes survive. If both machines change the
+same field, the later hybrid logical clock (HLC) wins with no warning.

package/docs/guide/tui.md

@@ -0,0 +1,98 @@
+# 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 task popups, `o`, `i`, and `c` toggle `OPEN`, `IN_PROGRESS`, and
+`CLOSED`. In the DAG and All-tasks popups, `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.

package/docs/guide/upgrade.md

@@ -0,0 +1,76 @@
+# How to upgrade mu
+
+## Upgrade the package
+
+```bash
+npm i -g @mu-crew/mu@latest
+mu link pi
+mu doctor
+```
+
+`mu link pi` installs a one-line shim at
+`~/.pi/agent/extensions/mu.ts` that loads the installed extension, and
+links `~/.agents/skills/mu` to the package's skill. Later upgrades
+update both with no relink. `MU_PI_HOME` changes the home directory
+that both paths start from.
+
+- `--copy` copies the extension instead of the shim. You then have to
+  relink after every upgrade.
+- `--force` replaces a skill symlink that points elsewhere, such as a
+  dev checkout. mu never replaces a real directory there (exit 4).
+- `--extension-only` and `--skill-only` install one part.
+
+For agents other than pi, see [README § Install](../../README.md#install).
+
+## Reload running pi agents
+
+A running pi keeps the extension it loaded at start. After an upgrade,
+type `/reload` in each agent's pane, or respawn the agent. From a
+shell:
+
+```bash
+mu agent send worker-1 -w auth '/reload' --via mux
+```
+
+Until then, the `ctl` row of `mu doctor` warns
+`extension X older than installed Y`. Ops the old extension lacks,
+such as `send --fresh`, fail with exit 4.
+
+## Upgrade from 3.1 or earlier
+
+Before 3.2.0, mu pasted text into pi panes. Now it sends through a
+control socket. Agents started before `mu link pi` have no socket, so
+sends to them fail with `ctl missing` instead of pasting. Restart those
+agents, or force the old path with `--via mux`.
+
+## Migrate an old DB
+
+mu refuses a DB older than schema v11 with `SchemaTooOldError`, and a
+newer one with `SchemaTooNewError`. Both exit 4 and leave the file
+alone. `scripts/migrate.ts` converts a v7, v8, v9, or v10 DB into a new
+v11 file. It never writes in place.
+
+```bash
+DB=${MU_DB_PATH:-$HOME/.local/state/mu/mu.db}
+BACKUP="$HOME/mu-old-backup-$(date +%Y%m%d-%H%M%S).db"
+sqlite3 "$DB" ".backup '$BACKUP'"
+npx tsx scripts/migrate.ts "$BACKUP" --out "${DB}.v11"
+MU_DB_PATH="${DB}.v11" mu doctor --deep
+mv "$DB" "${DB}.old-kept" && mv "${DB}.v11" "$DB"
+mu doctor
+```
+
+Legacy `REJECTED` tasks become `CLOSED/rejected`, and `DEFERRED` tasks
+become `OPEN/parked`. Flags and the rules for what carries over are in
+[scripts/README.md](../../scripts/README.md).
+
+## Run mu from a checkout
+
+```bash
+npm install && npm run build
+alias mu="node $PWD/dist/cli.js"
+```
+
+Or run `npm install -g .` in the checkout. Its `prepare` script builds
+first. Run `mu link pi --force` to point the skill link at the
+checkout.