@martintrojer/mu 0.4.0 → 0.4.2

package/AGENTS.md

@@ -14,7 +14,7 @@ write code. Follow the conventions below.
 1. **[docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md)** — what mu does
    from a user's perspective. ~10 minutes.
 2. **[CHANGELOG.md](CHANGELOG.md)** — the upcoming version's
-   entry (currently `[0.4.0] — unreleased`). Single source of truth
+   entry (currently `[0.4.1] — 2026-05-14`). Single source of truth
    for the verb list, schema, env vars.
 3. **[docs/VISION.md](docs/VISION.md)** — the load-bearing pillars.
    The design principles you must not violate.
@@ -60,7 +60,7 @@ mu/
 ├── src/                   # all source (root files: SDK + shared infra; one
 │                          # level of subdirs OK for cohesive clusters — see
 │                          # `src/cli/`, `src/agents/`, `src/tasks/` below)
-│   ├── db.ts              # SQLite schema + openDb (single CREATE-IF-NOT-EXISTS block; v7)
+│   ├── db.ts              # SQLite schema + openDb (single CREATE-IF-NOT-EXISTS block; v8)
 │   ├── tmux.ts            # tmux wrapper, send protocol, pane validation
 │   ├── detect.ts          # pi status detector + Braille-spinner fallback for other CLIs
 │   ├── reconcile.ts       # ghost prune + status detect + orphan surface
@@ -86,8 +86,9 @@ mu/
 │   ├── tracks.ts          # parallel-tracks union-find with diamond merge
 │   ├── workstream.ts      # ensureWorkstream / list / summarize / destroy / export
 │   ├── archives.ts        # cross-workstream archive bucket SDK hub (re-exports src/archives/*)
-│   ├── exporting.ts       # unified bucket renderer (workstream + archive export)
-│   ├── importing.ts       # inverse of exporting.ts: parse a bucket dir → live DB rows
+│   ├── exporting.ts       # unified bucket renderer (workstream + archive export; read-only buckets)
+│   ├── db-sync.ts         # whole-DB export/import + drift detection + sidecar park SDK
+│   ├── db-sync-replay.ts  # manual replay of divergence sidecars parked by db import --force-source
 │   ├── logs.ts            # agent_logs SDK (append, list, latestSeq, emitEvent)
 │   ├── vcs.ts             # VcsBackend hub (re-exports src/vcs/*: jj/sl/git/none impls)
 │   ├── workspace.ts       # per-agent VCS workspaces hub (re-exports src/workspace/*)
@@ -113,7 +114,7 @@ mu/
 │   │   │   └── wire.ts       # Commander glue
 │   │   ├── workspace.ts   # workspace create / list / free / path / orphans / refresh / commits
 │   │   ├── log.ts         # log read / write / tail
-│   │   ├── archive.ts     # archive create / list / show / add / remove / delete
+│   │   ├── archive.ts     # archive create / list / show / add / restore / remove / delete
 │   │   ├── state.ts       # `mu state` (canonical state card); --tui dispatches to src/cli/tui/
 │   │   ├── staleness.ts   # shared workspace-staleness CLI helpers + warn formatter
 │   │   ├── tui-launch-focus.ts # initial-tab focus ladder for bare `mu` and `mu state --tui`
@@ -150,6 +151,7 @@ mu/
 │   │   │                          # cursor-row.tsx, scroll.ts (applyCursor/applyScroll), viewport.ts,
 │   │   │                          # show-loader.ts (shared subprocess-preserving loader)
 │   │   ├── snapshot.ts    # undo / snapshot list / snapshot show
+│   │   ├── db.ts          # db export / import / replay
 │   │   ├── sql.ts         # sql escape hatch
 │   │   ├── doctor.ts      # doctor diagnostic
 │   │   ├── format.ts      # pure rendering helpers (table renderers, status colourers, truncate/relTime)
@@ -377,21 +379,24 @@ real friction proves itself.
 
 ### "Update the schema"
 
-1. Current schema version is **v7** (see `CURRENT_SCHEMA_VERSION`
+1. Current schema version is **v8** (see `CURRENT_SCHEMA_VERSION`
    in `src/db.ts`). The schema lives in `src/db.ts` as the
    `applySchema(db)` block, which is idempotent CREATE-IF-NOT-EXISTS
    plus targeted `DROP TABLE IF EXISTS` for retired tables
-   (e.g. v7's `DROP TABLE IF EXISTS approvals`). `openDb` rejects
-   pre-current DBs with `SchemaTooOldError` (exit 4) and a
-   migration hint.
+   (e.g. v7's `DROP TABLE IF EXISTS approvals`). v8 is additive:
+   `machine_identity` and `workstream_sync` are
+   `CREATE TABLE IF NOT EXISTS`, and `openDb` seeds the single
+   `machine_identity` row on first open. `openDb` rejects pre-current
+   DBs with `SchemaTooOldError` (exit 4) and a migration hint.
 2. Bump `CURRENT_SCHEMA_VERSION` in `src/db.ts` and mirror the new
-   shape in `CURRENT_SCHEMA`. Two of the last three bumps were
+   shape in `CURRENT_SCHEMA`. Three of the last four bumps were
    script-free: v5 → v6 was purely additive (existing
    CREATE-TABLE-IF-NOT-EXISTS picked up new tables); v6 → v7 was a
-   destructive-but-idempotent `DROP TABLE` block. Reach for a
-   one-shot migration script only when the change can't be
-   expressed that way (the v4 → v5 surrogate-PK substrate switch
-   was the canonical example).
+   destructive-but-idempotent `DROP TABLE` block; v7 → v8 is
+   additive plus the `machine_identity` seed. Reach for a one-shot
+   migration script only when the change can't be expressed that way
+   (the v4 → v5 surrogate-PK substrate switch was the canonical
+   example).
 3. Update tests that exercise the schema (`test/db.test.ts`).
 4. Update [CHANGELOG.md](CHANGELOG.md) under the upcoming version's
    `### Changed` section.

package/README.md

@@ -26,17 +26,15 @@ mu state -w auth-refactor --json  # agent/script API: typed static state for jq
 mu log --tail                 # subscribe to every state change
 ```
 
-The crew is real (tmux panes you can attach to), the work graph is
-real (SQLite + a parallel-tracks algorithm with diamond-merge), the
-workspaces are real (jj workspace / sl share / git worktree), and
-**mu stays out of the model's way.** Tasks, workspaces, panes, notes,
-and logs persist state and coordinate handoffs; the model still
-decides what to do. Workers use the bundled
-[SKILL.md](skills/mu/SKILL.md) when they need the full in-pane ground
-truth. Bare `mu` is the human front door when stdout is attached to a
-TTY: it launches the read-only TUI with every workstream loaded.
-Piped/scripted calls print help instead; use typed verbs plus `--json`
-(or `MU_NO_TUI=1`) for agent/API flows.
+Crew, graph, and workspaces are all real things you can poke at:
+tmux panes (`tmux attach`), a SQLite DAG with parallel-tracks +
+diamond-merge, and jj workspace / sl share / git worktree on disk.
+**mu persists state and coordinates handoffs; the model still
+decides what to do.** Workers reach for the bundled
+[SKILL.md](skills/mu/SKILL.md) when they need in-pane ground truth.
+Bare `mu` on a TTY launches the read-only multi-workstream TUI;
+piped/scripted calls print help, so use typed verbs + `--json` (or
+`MU_NO_TUI=1`) for agent/API flows.
 
 ---
 
@@ -54,9 +52,7 @@ Piped/scripted calls print help instead; use typed verbs plus `--json`
   drive; mu records, scopes, and yanks the next command.
 - **A local typed state surface.** One CLI, one SQLite registry,
   typed verbs, `--json` everywhere useful, and a read-only dashboard
-  for humans. Contributor-facing boundaries and rejected ideas live
-  in [ROADMAP.md](docs/ROADMAP.md); the README stays focused on how
-  mu feels to use.
+  for humans.
 
 ## What mu is NOT
 
@@ -193,6 +189,24 @@ expanded [dashboard/state guide](docs/USAGE_GUIDE.md#5-see-the-graph-dashboard--
 
 ---
 
+## Portability and handoff
+
+State lives in one SQLite DB, so it travels. `mu db export <file>`
+writes a consistent whole-DB copy plus a manifest sidecar; `mu db
+import <file>` ships it back, with per-workstream drift detection
+(dry-run by default; `--apply` commits) and a sharp `--force-source`
+that parks the loser to a sidecar before clobbering. Hard rule: don't
+edit the same workstream on two machines concurrently.
+
+For humans / git / docs, `mu workstream export` and `mu archive
+export` render a workstream (or an archive bucket) as Markdown:
+per-task `.md` files plus an `INDEX.md`, suitable for committing,
+reviewing, or pasting. Bucket exports are read-only artifacts; the
+lossless un-archive path back into a live workstream is `mu archive
+restore <label> --as <new-ws>`.
+
+---
+
 ## vs `pi-subagents`
 
 |                          | [`pi-subagents`](https://github.com/nicobailon/pi-subagents) | `mu` |