@martintrojer/mu 0.3.1 → 0.3.2

package/docs/ARCHITECTURE.md

@@ -245,7 +245,7 @@ returning. Three steps, in order:
    that has no matching `agents` row but whose pane title looks like
    an agent name, add it to the orphans list. **Do not auto-adopt** —
    `mu agent list` shows orphans under a separate "(orphans)" section and
-   the user runs `mu adopt %15 [--name X]` to formally claim them.
+   the user runs `mu agent adopt %15 [--name X]` to formally claim them.
 
 Full algorithm lives in `src/reconcile.ts` (the canonical
 implementation).
@@ -282,7 +282,7 @@ Each module is concrete and consumed today.
 | `src/detect.ts`       | Pi-only status detector (`busy` / `needs_input` / `idle` / `done`)                        |
 | `src/reconcile.ts`    | Ghost prune + status detect + orphan surface; "reality wins"                              |
 | `src/agents.ts`       | Hub: CRUD + send / read / list / close / free + liveness + reaper. Re-exports `src/agents/*` (spawn, adopt, errors); pane-title composition (`composeAgentTitle`) lives here. |
-| `src/agents/*.ts`     | Cohesive cluster of agent-lifecycle internals: `spawn.ts` (spawnAgent + resolveCliCommand / awaitSpawnLiveness / pane create-or-reuse / prestage / rollback), `adopt.ts` (register an existing tmux pane as a managed agent), `errors.ts` (typed agent error classes — `AgentNotFoundError`, `AgentDiedOnSpawnError`, …). |
+| `src/agents/*.ts`     | Cohesive cluster of agent-lifecycle internals: `spawn.ts` (spawnAgent + resolveCliCommand / awaitSpawnLiveness / pane create-or-reuse / prestage / rollback), `adopt.ts` (register an existing tmux pane as a managed agent), `kick.ts` (signal the foreground pgid of an agent pane's TTY — escape hatch for wedged tool subprocesses), `errors.ts` (typed agent error classes — `AgentNotFoundError`, `AgentDiedOnSpawnError`, …). |
 | `src/tasks.ts`        | Hub: every read/write verb on the DAG (edit / edges / queries) + cycle check + auto-event emission. Re-exports `src/tasks/*` (status, claim, lifecycle, wait, errors). |
 | `src/tasks/*.ts`      | Cohesive cluster of task-graph internals: `status.ts` (TaskStatus enum + helpers — single source of truth), `claim.ts` (claim/release + `resolveActorIdentity`, atomic CAS), `lifecycle.ts` (setTaskStatus / closeTask / openTask / rejectTask / deferTask + cascade), `wait.ts` (waitForTasks: block until tasks reach a target status), `errors.ts` (typed task error classes — `TaskAlreadyOwnedError`, `CycleError`, …). |
 | `src/tracks.ts`       | Parallel-tracks union-find with diamond merge                                             |
@@ -291,7 +291,7 @@ Each module is concrete and consumed today.
 | `src/importing.ts`    | Inverse of `src/exporting.ts`: parses a v0.3 bucket directory and rebuilds every source-ws as live tasks + edges + notes. Markdown-only (never reads .db); per-source-ws transactional; refuses silent merges into existing workstreams |
 | `src/archives.ts`     | Cross-workstream **archives** — feature complete (SDK + 6 CLI verbs: `mu archive create / list / show / add / remove / delete`, plus `search` and `export` via the unified bucket renderer): `createArchive` / `listArchives` / `getArchive` / `deleteArchive` / `addToArchive` (idempotent at `(archive, source_workstream)`) / `removeFromArchive` / `listArchivedTasks`. Backed by the v6 `archives` + `archived_tasks` + `archived_edges` + `archived_notes` + `archived_events` tables; archives outlive workstreams (TEXT `source_workstream` columns, no FK). |
 | `src/logs.ts`         | `agent_logs` SDK: appendLog / listLogs / latestSeq / emitEvent                            |
-| `src/vcs.ts`          | `VcsBackend` interface + jj / sl / git / none impls; detection precedence; `commitsBehind(workspacePath, ref)` for staleness signal (no auto-fetch; pure observation) |
+| `src/vcs.ts`          | `VcsBackend` interface + jj / sl / git / none impls; detection precedence; `commitsBehind(workspacePath, ref)` for staleness signal (no auto-fetch; pure observation); `isClean(workspacePath)` cheap working-copy probe used by `closeAgent`'s clean-workspace auto-free path |
 | `src/workspace.ts`    | Per-agent VCS workspaces (registry layer on top of vcs.ts); CRUD + cascade; orphan-dir detection (`listWorkspaceOrphans`); staleness decoration (`decorateWithStaleness` populates `commitsBehindMain` per row) |
 | `src/snapshots.ts`    | Whole-DB snapshots (`VACUUM INTO`); auto-captured before destructive verbs; SDK for `mu undo`. The `snapshots` table is schema v4 (carried forward unchanged through v5/v6/v7). |
 | `src/output.ts`       | NextStep type + `printNextSteps` + `errorNextSteps` plumbing for self-documenting output |
@@ -328,7 +328,7 @@ each are deliberately small.
 
 | Seam                | Add a new impl by...                                                                                                          |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `VcsBackend`        | Implementing `detect / createWorkspace / freeWorkspace / commitsBehind` (~80–150 LOC; jj/sl/git/none are working examples)        |
+| `VcsBackend`        | Implementing `detect / createWorkspace / freeWorkspace / isClean / commitsBehind / rebaseTo / commitsSinceBase` (~80–150 LOC; jj/sl/git/none are working examples)        |
 | Per-CLI `Detector`  | Adding patterns to `detectPiStatus` (vanilla pi `to interrupt)`; pi-meta + every TUI wrapper covered by Braille spinner glyph fallback `[\u2800-\u28FF]`)                  |
 | New typed verb      | Add an SDK function in the relevant `src/*.ts`; add a `cmd<Verb>` to the matching `src/cli/<namespace>.ts` (or create a new namespace if the verb doesn't fit existing ones); wire one commander block in `src/cli.ts`'s `buildProgram()` (use `handle()` for the exit-code map; route through `printNextSteps` for self-documenting output) |
 | New schema migration| Bump `CURRENT_SCHEMA_VERSION` in `src/db.ts`; mirror the new shape in `CURRENT_SCHEMA`. Two of the three post-v5 bumps were script-free: v5 → v6 was purely additive (the existing CREATE-TABLE-IF-NOT-EXISTS pass picked up the new `archive_*` tables), and v6 → v7 was a destructive-but-idempotent in-place migration (a `DROP TABLE IF EXISTS approvals` block in `applySchema`). 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; restore from git history if you need to see the shape). The loud-fail hook in `openDb` rejects pre-current DBs with `SchemaTooOldError` (exit code 4) and a migration instruction. |

package/docs/ROADMAP.md

@@ -115,12 +115,14 @@ if it lands, three rules stay non-negotiable:
 If those three rules hold, mu stays driveable from a shell forever
 and the extension stays thin.
 
-### `mu adopt <pane-id> [--name <agent>]` — SHIPPED in v0.2 (`e20af89`)
-
-Reconciliation surfaces orphan panes; `mu adopt` formally registers
-one of them as a managed agent. Promotion was triggered by the
-multi-agent dogfood pattern (orchestrator runs in a pane outside
-the `mu-<ws>` session and wants to be claimable as a worker).
+### `mu agent adopt <pane-id> [--name <agent>]` — SHIPPED in v0.2 (`e20af89`)
+
+Reconciliation surfaces orphan panes; `mu agent adopt` formally
+registers one of them as a managed agent. Promotion was triggered
+by the multi-agent dogfood pattern (orchestrator runs in a pane
+outside the `mu-<ws>` session and wants to be claimable as a
+worker). Originally shipped at the top level as `mu adopt`; moved
+under `mu agent` to match every other agent-lifecycle verb.
 
 ### Heterogeneous CLI status detection (claude, codex, ...)
 

package/docs/USAGE_GUIDE.md

@@ -561,9 +561,9 @@ mu agent list -w auth-refactor   # surfaces orphans at the bottom
 # Orphan panes (1)
 #   %15 title=worker-2 cli=pi
 
-mu adopt %15 -w auth-refactor                    # adopt by pane id
-mu adopt worker-2 -w auth-refactor               # adopt by pane title (same effect)
-mu adopt %15 --name investigator -w auth-refactor  # adopt and rename the pane
+mu agent adopt %15 -w auth-refactor                    # adopt by pane id
+mu agent adopt worker-2 -w auth-refactor               # adopt by pane title (same effect)
+mu agent adopt %15 --name investigator -w auth-refactor  # adopt and rename the pane
 ```
 
 The pane title becomes the agent name (`mu`'s claim protocol
@@ -737,7 +737,7 @@ If the orchestrator tries `mu task claim some-task` directly:
 conflict: claimer 'pi-mu' (pane %6441) is not a registered mu agent.
   Working directly?           Pass --self to attribute via log instead.
   Dispatching to a worker?    Pass --for <worker> to assign.
-  Want full registration?     Run: mu adopt %6441
+  Want full registration?     Run: mu agent adopt %6441
 ```
 
 Three actionable next steps. Pick one based on intent:
@@ -754,7 +754,7 @@ mu task claim some-task --for worker-1
 #   -> tasks.owner = 'worker-1'
 
 # Orchestrator wants to BE a registered worker (rare):
-mu adopt %6441 -w <ws>      # only if pane is in mu-<ws> session
+mu agent adopt %6441 -w <ws>  # only if pane is in mu-<ws> session
 mu task claim some-task     # now works as a normal worker claim
 ```
 
@@ -790,7 +790,31 @@ mu task note design "DECISION: JWT, 24h expiry, refresh via cookie"
 mu task note design "FILES: src/auth.rs:45-120"
 ```
 
-Read them via the SQL escape hatch:
+Read them via the typed verb:
+
+```bash
+mu task notes design                          # all notes, oldest first
+mu task notes design --tail 3                 # only the last 3 (alias --last)
+mu task notes design --since 2026-01-01       # only notes after an ISO 8601 cutoff
+mu task notes design --since-claim            # only notes since the most recent
+                                              # 'task claim' event for this task
+                                              # (auto-resolved from agent_logs)
+mu task notes design --tail 5 --json          # collection envelope {items, count}
+```
+
+Filters compose: `--tail` slices the last N of whatever survived
+the timestamp filter. `--since` and `--since-claim` are mutually
+exclusive (both define a cutoff) — pick one. With no filters the
+output is unchanged from prior versions (every note, oldest-first).
+
+`--since-claim` is the orchestrator-friendly form: dispatch flows
+often drop a multi-screen SPEC note BEFORE claiming, then the
+worker appends progress notes AFTER the claim. `--since-claim`
+slices off the SPEC so you see only the worker's reports. If no
+claim event exists for the task, it degrades to no filter (so the
+verb stays useful on un-claimed tasks).
+
+Or, for ad-hoc shape, the SQL escape hatch:
 
 ```bash
 mu sql "SELECT author, content, created_at FROM task_notes WHERE task_id='design' ORDER BY id"
@@ -934,6 +958,10 @@ while (( ${#in_flight[@]} > 0 )); do
   #    overrides. Refuses on dirty WC; conflicts exit 5 with a `cd`
   #    hint to resolve in-place.
   mu workspace refresh "$worker" -w "$ws"
+  # Alt: `mu workspace recreate "$worker" -w "$ws"` does free + create
+  #      atomically — same shortcut, but throws away the worker's local
+  #      changes (the lossy escape: requires --force on a dirty WC).
+  #      Use when you don't care about replaying the worker's commits.
 
   # 4. Drop $closed from in_flight, dispatch the next task, repeat.
   in_flight=( "${in_flight[@]/$closed}" )
@@ -1078,7 +1106,32 @@ Reconciliation runs on every `mu agent list` / `mu`. Three steps:
 3. **Surface orphan panes** — panes in the workstream's tmux session
    whose `pane.command` looks like an agent CLI (pi) but
    that aren't in the registry. **Not** auto-adopted; mu shows them
-   under "Orphan panes" and tells you `mu adopt <pane-id>` to register
+   under "Orphan panes" and tells you `mu agent adopt <pane-id>` to register
+
+### A worker is wedged on an unbounded tool subprocess
+
+A worker ran `find / -maxdepth 6 ...` (30-60 minutes on a populated
+home directory) or a busy-wait loop. `mu agent send` queues steering
+messages until the tool returns; `tmux send-keys C-c` against the
+pane doesn't propagate (the wrapping pi/claude/codex CLI catches it
+as TUI input). The escape hatch:
+
+```bash
+mu agent kick worker-1                       # SIGINT (graceful, default)
+mu agent kick worker-1 --signal SIGTERM      # polite escalation
+mu agent kick worker-1 --signal SIGKILL      # hammer
+```
+
+`mu agent kick` looks up the pane's TTY via `tmux display-message
+-p '#{pane_tty}'`, asks `ps -t <tty>` for the foreground process
+group (the row whose `stat` field contains `+`), and signals the
+whole pgrp directly. Refuses with `NoForegroundProcessError` when
+the foreground IS the wrapping CLI itself — use `mu agent close`
+to close the agent.
+
+Prevention: don't prompt workers to run filesystem-wide `find`,
+broad `grep -r /`, or unbounded busy-wait loops. Pass paths
+explicitly or scope to `$WORKSPACE`.
 
 ### You closed your terminal session
 
@@ -1219,6 +1272,19 @@ mu agent close reviewer-1
 `mu agent close` is idempotent: `killPane` swallows "pane already gone"
 errors; `deleteAgent` returns false (not throws) on a missing row.
 
+If the agent has a workspace, behaviour depends on its state:
+
+- **Clean** (no uncommitted changes AND no commits since fork) — the
+  workspace is silently auto-freed alongside the close, so a
+  `--workspace` spawn that did no real work doesn't make you type
+  `--discard-workspace` just to clean up.
+- **Dirty** (uncommitted changes OR commits since fork) — close refuses
+  with `WorkspacePreservedError` (exit 4). Two resolutions: (a) `mu
+  workspace free <agent>` first (optionally with `--commit` to capture
+  pending changes), then `mu agent close <agent>`; or (b) `mu agent
+  close <agent> --discard-workspace` to free both in one shot (lossy:
+  any work in the workspace is gone).
+
 ### Tear down the whole workstream
 
 `mu workstream destroy` is the symmetric counterpart of `mu workstream init`: it kills the
@@ -1413,8 +1479,6 @@ Key properties:
 - **Forward edge refs are deferred.** `blocked_by` / `blocks`
   arrays are validated against the bucket's id-set up front, then
   inserted after every task in the source-ws is created.
-- **Pre-0.3 layouts refuse.** Buckets without a `bucketVersion: 2`
-  manifest throw `ImportLegacyLayoutError` with a re-export hint.
 - **Partial import.** Multi-source buckets accept either a
   per-source-ws subdir path (auto-detected via
   `README.md` + `INDEX.md` + `tasks/` + a parent

package/docs/VOCABULARY.md

@@ -51,6 +51,7 @@ defined here, fix the doc. If you need a new term, add it here first.
 | **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"                          |
 | **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,7 +70,7 @@ 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                                 |
 
 ---
@@ -138,6 +139,7 @@ cache; `mu agent list` reconciles on every call.
 | `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 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. |
 
 **Don't conflate `free` and `release`.** Free is about the *agent*;
@@ -152,6 +154,7 @@ release is about the *task*.
 | `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 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 +319,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martintrojer/mu",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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"

package/skills/mu/SKILL.md

@@ -86,8 +86,13 @@ track. Don't spawn more agents than there are tracks.
 For two agents editing the same project, use `--workspace` on spawn.
 Each gets an isolated working copy under
 `<state-dir>/workspaces/<workstream>/<agent>/`. Auto-detects
-jj/sl/git; `cp -a` for non-VCS. Workspaces are NOT freed when you
-close an agent — run `mu workspace free <agent>` explicitly. Between
+jj/sl/git; `cp -a` for non-VCS. Workspaces are auto-freed when
+you close an agent **iff the workspace is clean** (no uncommitted
+changes AND no commits since fork); a non-clean workspace blocks
+`mu agent close` with `WorkspacePreservedError` and forces an
+explicit `mu workspace free <agent>` (or
+`mu agent close <agent> --discard-workspace` for the lossy override).
+Between
 waves, `mu workspace refresh <agent>` rebases the dir onto fresh
 main without killing the agent's LLM context; `mu workspace commits
 <agent>` lists since-fork commits for cherry-picking.
@@ -222,6 +227,16 @@ running a wave.
   un-closing CLOSED/REJECTED/DEFERRED). Tunable via
   `MU_IDLE_THRESHOLD_MS` (default 5 min).
 
+- **Wedged on an unbounded tool subprocess (`find /`, busy-wait
+  loop)** — `mu agent send` queues until the tool returns;
+  `tmux send-keys C-c` doesn't propagate (the wrapping CLI eats
+  it as TUI input). Use `mu agent kick <name>` to SIGINT the
+  foreground process group of the pane's TTY directly from
+  outside. Default `--signal SIGINT` is graceful; escalate to
+  `--signal SIGTERM` then `--signal SIGKILL` if the tool
+  ignores it. Refuses when the foreground IS the wrapping CLI
+  itself — use `mu agent close` for that.
+
 ## Parallelisation decision table
 
 | Situation | Action |
@@ -259,10 +274,13 @@ running a wave.
   `--archive <label>` to preserve graph atomically), `export`,
   `import`.
 - **Agents**: `spawn` (`--workspace`, `--role read-only`,
-  `--command`), `send`, `read`, `show`, `list`, `close`, `free`.
-  **`mu adopt <pane-id|title>`** registers an orphan pane as a
-  managed agent.
-- **Tasks**: `add`, `list`, `next`, `show`, `tree`, `notes`, `note`,
+  `--command`), `send`, `read`, `show`, `list`, `close`, `free`,
+  `kick` (signal a wedged foreground tool subprocess from outside
+  the pane). **`mu agent adopt <pane-id|title>`** registers an
+  orphan pane as a managed agent.
+- **Tasks**: `add`, `list`, `next`, `show`, `tree`, `notes`
+  (`--tail N` / `--since <iso>` / `--since-claim` to slice the
+  timeline; default = every note, oldest first), `note`,
   `claim` (`--for | --self`), `release` (`--reopen` to un-close),
   `close` (`--if-ready` = no-op unless every blocker terminal),
   `open`, `reject`, `defer`, `block`, `unblock`, `update`,
@@ -270,9 +288,11 @@ running a wave.
   Edge direction: `block <blocked> --by <blocker>`.
 - **Self (in-pane)**: `mu me`, `mu me tasks`, `mu me next`.
 - **Workspace**: `create`, `list` (`behind` column), `refresh`
-  (rebase onto fresh base, agent stays alive), `commits` (since-fork
-  `<sha> <subject>`; `--json` for piping), `free`, `path`
-  (`cd $(mu workspace path X)`), `orphans`.
+  (rebase onto fresh base, agent stays alive), `recreate` (free +
+  create in one shot for between-wave prep; `--force` to discard
+  dirty edits), `commits` (since-fork `<sha> <subject>`; `--json`
+  for piping), `free`, `path` (`cd $(mu workspace path X)`),
+  `orphans`.
 - **Activity log**: `mu log "text"` (write), `mu log -n N` (read),
   `mu log --tail` (subscribe). Don't pipe `--tail` for waits — use
   `mu task wait`.
@@ -361,10 +381,12 @@ IDs auto-derive from titles via slugify.
 # Wait for any-of N to close, cherry-pick that one, return.
 res=$(mu task wait t1 t2 t3 -w ws --any --first --json \
         --timeout 600 --on-stall exit)
-firing=$(jq -r .firing.qualifiedId <<<"$res")
-sha=$(mu workspace commits $worker -w ws --json \
-        | jq -r --arg id "${firing#*/}" \
-            '.items[] | select(.subject | startswith($id+":")) | .sha' | head -1)
+worker=$(jq -r .firing.owner <<<"$res")
+# Workers run in fresh single-purpose workspaces, so HEAD is the
+# task's commit. Don't filter on subject — workers don't prefix
+# subjects with the task-id, and any such filter silently returns
+# empty (then `git cherry-pick` fails with "empty commit set").
+sha=$(mu workspace commits $worker -w ws --json | jq -r '.items[0].sha')
 git cherry-pick $sha && cargo test --lib
 # Next turn: same wait on the smaller set.
 ```
@@ -439,11 +461,11 @@ Verbs auto-resolve via `$TMUX_PANE` — `mu me`, `mu me next`,
 (set at spawn) IS the agent identity.
 
 - **Worker**: pane was created by `mu agent spawn` (or promoted via
-  `mu adopt`). Bare `mu task claim <id>` works.
+  `mu agent adopt`). Bare `mu task claim <id>` works.
 - **Orchestrator**: a top-level pi session NOT in `agents`. Bare
   `mu task claim` errors with `ClaimerNotRegisteredError` whose
   `errorNextSteps()` lists three options: `--self` (work directly,
-  owner=NULL), `--for <worker>` (dispatch), or `mu adopt <pane>`.
+  owner=NULL), `--for <worker>` (dispatch), or `mu agent adopt <pane>`.
 
 Working loop:
 
@@ -504,6 +526,11 @@ orchestrator's `mu task wait` hang.
 - **Don't use the `mu_` task-id prefix.** Reserved.
 - **Don't message agents directly.** Coordinate via task notes and
   the activity log.
+- **Don't prompt workers to run filesystem-wide `find`, broad
+  `grep -r /`, or unbounded busy-wait loops.** Pass paths
+  explicitly or scope to `$WORKSPACE`. If a worker wedges on one,
+  use `mu agent kick <name>` to SIGINT the foreground tool
+  from outside the pane.
 
 ## What mu is NOT