@martintrojer/mu 0.3.1 → 0.3.2

package/dist/cli.js

@@ -530,6 +530,18 @@ function lastClaimActor(db, workstream, localId) {
   if (!row) return null;
   return parseClaimEventActor(row.payload);
 }
+function lastClaimEventAt(db, workstream, localId) {
+  const escaped = localId.replace(/[\\%_]/g, (c) => `\\${c}`);
+  const pattern = `${CLAIM_EVENT_PREFIX}	${escaped}	%`;
+  const wsId = tryResolveWorkstreamId(db, workstream);
+  if (wsId === null) return null;
+  const row = db.prepare(
+    `SELECT created_at FROM agent_logs
+        WHERE workstream_id = ? AND kind = 'event' AND payload LIKE ? ESCAPE '\\'
+        ORDER BY seq DESC LIMIT 1`
+  ).get(wsId, pattern);
+  return row ? row.created_at : null;
+}
 var EVENT_VERB_PREFIXES = [
   // src/tasks.ts + src/tasks/*.ts
   "task add",
@@ -552,6 +564,7 @@ var EVENT_VERB_PREFIXES = [
   "agent close",
   "agent free",
   "agent adopt",
+  "agent kick",
   // src/tasks/wait.ts — emitted when --stuck-after fires (alive +
   // assigned + no recent progress; idle_assigned_agent_detection).
   "agent stalled",
@@ -559,6 +572,7 @@ var EVENT_VERB_PREFIXES = [
   "workspace create",
   "workspace free",
   "workspace refresh",
+  "workspace recreate",
   // src/workstream.ts
   "workstream init",
   "workstream destroy",
@@ -892,6 +906,24 @@ async function enableMuPaneBorders(target) {
   await tmux(["set-option", "-w", "-t", target, "pane-active-border-style", "fg=cyan,bold"]);
   await tmux(["set-option", "-w", "-t", target, "pane-border-style", "fg=brightblack"]);
 }
+async function paneTTY(paneId) {
+  assertValidPaneId(paneId);
+  const result = await currentExecutor(["display-message", "-t", paneId, "-p", "#{pane_tty}"]);
+  if (result.exitCode !== 0) {
+    if (/can't find pane|pane not found/i.test(result.stderr)) {
+      throw new PaneNotFoundError(paneId);
+    }
+    throw new TmuxError(
+      ["display-message", "-t", paneId, "-p", "#{pane_tty}"],
+      result.stderr,
+      result.stdout,
+      result.exitCode
+    );
+  }
+  const tty = result.stdout.trim();
+  if (tty === "") throw new PaneNotFoundError(paneId);
+  return tty;
+}
 async function getPaneTitle(paneId) {
   if (!isValidPaneId(paneId)) return void 0;
   const result = await currentExecutor(["display-message", "-t", paneId, "-p", "#{pane_title}"]);
@@ -1559,7 +1591,7 @@ var ClaimerNotRegisteredError = class extends Error {
    * Three actionable resolutions in expected-frequency order:
    *   1. --self  : orchestrator pattern (working directly)
    *   2. --for   : dispatcher pattern (assigning to a worker)
-   *   3. mu adopt: registration pattern (promote pane to worker)
+   *   3. mu agent adopt: registration pattern (promote pane to worker)
    */
   errorNextSteps() {
     const steps = [
@@ -1567,9 +1599,9 @@ var ClaimerNotRegisteredError = class extends Error {
       { intent: "Dispatch to a worker", command: "mu task claim <id> --for <worker>" }
     ];
     steps.push(
-      this.paneId !== null ? { intent: "Register this pane", command: `mu adopt ${this.paneId}` } : {
+      this.paneId !== null ? { intent: "Register this pane", command: `mu agent adopt ${this.paneId}` } : {
         intent: "Register a pane",
-        command: "mu adopt <pane-id>  (must be in mu-<workstream> tmux session)"
+        command: "mu agent adopt <pane-id>  (must be in mu-<workstream> tmux session)"
       }
     );
     return steps;
@@ -2170,16 +2202,6 @@ function listArchivedTasks(db, label, opts = {}) {
 }
 
 // src/exporting.ts
-var LegacyExportLayoutError = class extends Error {
-  constructor(outDir) {
-    super(
-      `${outDir} was created with a pre-bucket export (mu < 0.3); the on-disk shape changed in 0.3 (top-level README/INDEX/manifest + per-source-ws subdirs). Re-export is not in-place; either pick a different --out or 'rm -rf ${outDir}' and re-run.`
-    );
-    this.outDir = outDir;
-  }
-  outDir;
-  name = "LegacyExportLayoutError";
-};
 function fenceForBody(body) {
   const longestRun = (body.match(/`+/g) ?? []).reduce((m, s) => Math.max(m, s.length), 0);
   return "`".repeat(Math.max(3, longestRun + 1));
@@ -2350,9 +2372,6 @@ function readManifest(path) {
   if (obj.bucketVersion === 2 && typeof obj.sources === "object" && obj.sources !== null) {
     return { kind: "v2", manifest: obj };
   }
-  if (typeof obj.workstream === "string" && Array.isArray(obj.tasks)) {
-    return { kind: "legacy" };
-  }
   return { kind: "corrupt" };
 }
 function sha256Hex(content) {
@@ -2380,9 +2399,6 @@ function renderToBucket(input) {
   }
   const manifestPath = join3(outDir, "manifest.json");
   const probe = readManifest(manifestPath);
-  if (probe.kind === "legacy") {
-    throw new LegacyExportLayoutError(outDir);
-  }
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const muVersion = readMuVersion();
   const previous = probe.kind === "v2" ? probe.manifest : void 0;
@@ -2556,7 +2572,6 @@ function exportSourcesForArchive(db, label) {
   for (const [sourceName, taskList] of bySource) {
     const tasks = taskList.map((t) => ({
       name: t.originalLocalId,
-      localId: t.originalLocalId,
       workstreamName: t.sourceWorkstream,
       title: t.title,
       // Status as snapshotted; cast through the TaskStatus union by
@@ -2634,24 +2649,30 @@ var WorkspaceVcsRequiredError = class extends Error {
   }
 };
 var WorkspaceDirtyError = class extends Error {
-  constructor(workspacePath2, files) {
+  constructor(workspacePath2, files, verb = "rebase") {
     super(
-      `workspace dirty (${files.length} uncommitted file(s)): ${workspacePath2}; refusing to rebase`
+      `workspace dirty (${files.length} uncommitted file(s)): ${workspacePath2}; refusing to ${verb}`
     );
     this.workspacePath = workspacePath2;
     this.files = files;
+    this.verb = verb;
   }
   workspacePath;
   files;
   name = "WorkspaceDirtyError";
+  /** The verb that refused ("rebase", "recreate", ...). Used to make
+   *  the error message + nextSteps point the operator at the right
+   *  escape hatch (e.g. recreate's `--force`). Default "rebase" for
+   *  backward compatibility with the original rebaseTo call sites. */
+  verb;
   errorNextSteps() {
-    return [
+    const steps = [
       {
         intent: "Inspect the dirty files",
         command: `(cd ${this.workspacePath} && git status -s)  # or jj st / sl st`
       },
       {
-        intent: "Commit them first, then retry refresh",
+        intent: `Commit them first, then retry ${this.verb}`,
         command: `(cd ${this.workspacePath} && git add -A && git commit -m WIP)`
       },
       {
@@ -2659,6 +2680,13 @@ var WorkspaceDirtyError = class extends Error {
         command: `(cd ${this.workspacePath} && git stash)`
       }
     ];
+    if (this.verb === "recreate") {
+      steps.push({
+        intent: "Or DISCARD all uncommitted changes (the lossy escape)",
+        command: "mu workspace recreate <agent> --force"
+      });
+    }
+    return steps;
   }
 };
 var WorkspaceConflictError = class extends Error {
@@ -2727,6 +2755,13 @@ var noneBackend = {
   async commitsBehind(_workspacePath, _ref) {
     return null;
   },
+  // none has no notion of clean — a cp -a snapshot doesn't track
+  // committed vs uncommitted state. Returning true makes the
+  // close-auto-free path silently free a none-workspace (consistent
+  // with the fact that there are no commits to lose).
+  async isClean(_workspacePath) {
+    return true;
+  },
   // none has no upstream to rebase onto. Throw a typed error so the
   // CLI's handle() maps it to exit 4 with a clean Next: hint.
   async rebaseTo(workspacePath2, _fromRef) {
@@ -2736,6 +2771,11 @@ var noneBackend = {
   // doesn't track history. Same typed error as rebaseTo.
   async commitsSinceBase(workspacePath2, _baseRef) {
     throw new WorkspaceVcsRequiredError("commits", workspacePath2);
+  },
+  // No VCS → nothing to compare against; "dirty" is unanswerable.
+  // Caller (`recreateWorkspace`) treats [] as "clean" and proceeds.
+  async listDirtyFiles(_workspacePath) {
+    return [];
   }
 };
 var gitBackend = {
@@ -2756,6 +2796,20 @@ var gitBackend = {
     const sha = await run("git", ["rev-parse", "HEAD"], opts.workspacePath);
     return { parentRef: sha };
   },
+  // Working-copy clean check: empty `git status --porcelain` output
+  // means no working-tree, staged, or untracked-not-ignored changes.
+  // Returns false on any failure (workspace path missing, git
+  // explodes) — be conservative; auto-free should never "silently
+  // succeed" because we couldn't check.
+  async isClean(workspacePath2) {
+    if (!existsSync3(workspacePath2)) return false;
+    try {
+      const files = await listGitDirtyFiles(workspacePath2);
+      return files.length === 0;
+    } catch {
+      return false;
+    }
+  },
   // Compute commits-behind as: count of commits reachable from main
   // but not from `ref`. Resolves "main" via origin/HEAD (the symbolic
   // ref the remote advertises), falling back to origin/main and then
@@ -2898,6 +2952,10 @@ var gitBackend = {
     const result = { removed: true };
     if (committedRef !== void 0) result.committedRef = committedRef;
     return result;
+  },
+  async listDirtyFiles(workspacePath2) {
+    if (!existsSync3(workspacePath2)) return [];
+    return listGitDirtyFiles(workspacePath2);
   }
 };
 async function resolveGitMainRef(workspacePath2) {
@@ -3006,6 +3064,23 @@ var jjBackend = {
     if (committedRef !== void 0) result.committedRef = committedRef;
     return result;
   },
+  // jj working-copy clean: @ has no diff from its parent.
+  // `jj diff -r @ --summary` prints one line per changed file; empty
+  // stdout = clean. jj's auto-snapshotting means there's no separate
+  // "untracked" bucket — every working-tree change is already in @.
+  async isClean(workspacePath2) {
+    if (!existsSync3(workspacePath2)) return false;
+    try {
+      const out = await run(
+        "jj",
+        ["diff", "-r", "@", "--summary", "--no-pager", "--color", "never"],
+        workspacePath2
+      );
+      return out.length === 0;
+    } catch {
+      return false;
+    }
+  },
   // Compute commits-behind via jj's `trunk()` revset, which resolves
   // to the project's configured trunk (default-branch heuristic).
   // Returns null when trunk() is unresolvable (e.g. fresh repo with
@@ -3126,6 +3201,13 @@ var jjBackend = {
       workspacePath2
     );
     return parseNulRecords(out);
+  },
+  // jj is always-snapshotted: there is no "uncommitted" state. The
+  // working copy is itself a commit; the next snapshot folds any
+  // edits in. Surface that by returning [] so `recreateWorkspace`
+  // never refuses a jj workspace as "dirty".
+  async listDirtyFiles(_workspacePath) {
+    return [];
   }
 };
 function parseNulRecords(raw) {
@@ -3197,6 +3279,18 @@ var slBackend = {
     if (committedRef !== void 0) result.committedRef = committedRef;
     return result;
   },
+  // sl working-copy clean: empty `sl status` output. Same shape as
+  // listSlDirtyFiles below but inlined to keep the failure-mode
+  // boundary tight (any throw → not clean).
+  async isClean(workspacePath2) {
+    if (!existsSync3(workspacePath2)) return false;
+    try {
+      const out = await run("sl", ["status"], workspacePath2);
+      return out.length === 0;
+    } catch {
+      return false;
+    }
+  },
   // Same shape as the jj impl: count commits in trunk() not reachable
   // from ref. Sapling's revset language is close enough to jj's that
   // the same idiom works. Returns null when trunk() is unresolvable
@@ -3273,6 +3367,10 @@ var slBackend = {
       workspacePath2
     );
     return parseNulRecords(out).reverse();
+  },
+  async listDirtyFiles(workspacePath2) {
+    if (!existsSync3(workspacePath2)) return [];
+    return listSlDirtyFiles(workspacePath2);
   }
 };
 async function listSlDirtyFiles(workspacePath2) {
@@ -3315,6 +3413,10 @@ import { existsSync as existsSync4, readdirSync, rmSync as rmSync2 } from "fs";
 import { homedir as homedir2 } from "os";
 import { join as join5, resolve as resolve2 } from "path";
 
+// src/agents/spawn.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+
 // src/output.ts
 import Table from "cli-table3";
 import picocolors from "picocolors";
@@ -3397,10 +3499,49 @@ function maybeWarnNonConventionalAgentName(name) {
   );
 }
 function resolveCliCommand(cli) {
-  const envName = `MU_${cli.toUpperCase()}_COMMAND`;
+  const envName = envVarNameForCli(cli);
   const override = process.env[envName];
   return override && override.trim() !== "" ? override : cli;
 }
+function envVarNameForCli(cli) {
+  return `MU_${cli.toUpperCase().replace(/-/g, "_")}_COMMAND`;
+}
+function resolveCliCommandWithSource(cli) {
+  const envVar = envVarNameForCli(cli);
+  const override = process.env[envVar];
+  if (override !== void 0 && override.trim() !== "") {
+    return { command: override, envVar, resolvedFromEnv: true };
+  }
+  return { command: cli, envVar, resolvedFromEnv: false };
+}
+var execFileP = promisify2(execFile2);
+async function defaultCommandResolver(command) {
+  const binary = parseFirstToken(command);
+  if (binary === "") return { ok: false, binary };
+  try {
+    const { stdout } = await execFileP("/bin/sh", ["-c", `command -v -- ${shellQuote(binary)}`], {
+      env: process.env
+    });
+    const resolvedPath = stdout.trim();
+    if (resolvedPath === "") return { ok: false, binary };
+    return { ok: true, binary, resolvedPath };
+  } catch {
+    return { ok: false, binary };
+  }
+}
+function shellQuote(s) {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function parseFirstToken(command) {
+  const trimmed = command.trim();
+  if (trimmed === "") return "";
+  const match = trimmed.match(/^\S+/);
+  return match ? match[0] : "";
+}
+var activeCommandResolver = defaultCommandResolver;
+async function checkCommandResolvable(command) {
+  return activeCommandResolver(command);
+}
 async function spawnAgent(db, opts) {
   if (!isValidAgentName(opts.name)) {
     throw new TypeError(
@@ -3414,33 +3555,36 @@ async function spawnAgent(db, opts) {
   const windowName = opts.tab ?? opts.name;
   const cli = opts.cli ?? "pi";
   const command = opts.command ?? resolveCliCommand(cli);
+  if (opts.command === void 0) {
+    const check = await checkCommandResolvable(command);
+    if (!check.ok) {
+      throw new AgentSpawnCliNotFoundError(cli, check.binary, envVarNameForCli(cli));
+    }
+  }
   const workspacePathStr = opts.workspace ? await prestageWorkspace(db, opts, cli) : void 0;
   const paneEnv = {
     MU_MANAGED_AGENT: "1",
     MU_AGENT_NAME: opts.name,
     MU_WORKSTREAM: opts.workstream
   };
-  const paneId = await createOrReusePane({
-    session,
-    windowName,
-    command,
-    cwd: workspacePathStr ?? opts.cwd,
-    env: paneEnv
-  });
   const hasWorkspace = workspacePathStr !== void 0;
+  let paneId;
   let agent;
   try {
+    paneId = await createOrReusePane({
+      session,
+      windowName,
+      command,
+      cwd: workspacePathStr ?? opts.cwd,
+      env: paneEnv
+    });
     await setPaneTitle(paneId, opts.name);
     await enableMuPaneBordersForPane(paneId);
     agent = finalizeAgentRow(db, { opts, cli, paneId, hasWorkspace });
-  } catch (err) {
-    await rollbackSpawn(db, opts.name, paneId, hasWorkspace, opts.workstream);
-    throw err;
-  }
-  try {
     await awaitSpawnLiveness(paneId, opts.name);
   } catch (err) {
     await rollbackSpawn(db, opts.name, paneId, hasWorkspace, opts.workstream);
+    if (hasWorkspace) attachOrphanCleanupHint(err, opts.name, opts.workstream);
     throw err;
   }
   emitEvent(
@@ -3500,7 +3644,7 @@ function finalizeAgentRow(db, args) {
   return row;
 }
 async function rollbackSpawn(db, name, paneId, hasWorkspace, workstream) {
-  await killPane(paneId).catch(() => {
+  if (paneId !== void 0) await killPane(paneId).catch(() => {
   });
   if (hasWorkspace) {
     await freeWorkspace(db, name, { workstream }).catch(() => {
@@ -3508,6 +3652,22 @@ async function rollbackSpawn(db, name, paneId, hasWorkspace, workstream) {
   }
   deleteAgent(db, name, workstream);
 }
+function attachOrphanCleanupHint(err, agent, workstream) {
+  if (typeof err !== "object" || err === null) return;
+  const target = err;
+  const existing = typeof target.errorNextSteps === "function" ? target.errorNextSteps.bind(target) : null;
+  const orphanHints = [
+    {
+      intent: "Check for an orphan workspace dir (rollback is best-effort; may have failed)",
+      command: `mu workspace orphans -w ${workstream}`
+    },
+    {
+      intent: "Free the workspace if it survived the rollback (idempotent on missing)",
+      command: `mu workspace free ${agent} -w ${workstream}`
+    }
+  ];
+  target.errorNextSteps = () => [...existing ? existing() : [], ...orphanHints];
+}
 function defaultSpawnLivenessMs() {
   const raw = process.env.MU_SPAWN_LIVENESS_MS;
   if (raw === void 0) return 1500;
@@ -3515,13 +3675,51 @@ function defaultSpawnLivenessMs() {
   if (Number.isNaN(parsed) || parsed < 0) return 1500;
   return parsed;
 }
+var STARTUP_ERROR_PATTERNS = [
+  /No API key found for [\w-]+/i,
+  /Error: invalid API key/i,
+  /Authentication failed/i,
+  /401 Unauthorized/i,
+  /Could not authenticate/i,
+  // fb_agent_spawn_no_validation part B: post-spawn detection of the
+  // "binary not found at exec time" failure mode. The pre-flight check
+  // above catches the common typo BEFORE any side effect, but a few
+  // edge cases still slip through and only surface in the pane:
+  //   - `--command "..."` skips the pre-flight (operator opt-out).
+  //   - PATH inside the spawned shell differs from PATH in mu's
+  //     process (login shell rc files, /etc/paths.d, etc.).
+  //   - Race: binary on PATH at spawn time, gone 1.5s later.
+  // Scoped to the FIRST 30 lines of scrollback (see
+  // STARTUP_ERROR_TAIL_LINES) so a user's later `cat /no/such/file`
+  // can't false-positive long after spawn.
+  /command not found/i,
+  /No such file or directory/i
+];
+var STARTUP_ERROR_TAIL_LINES = 30;
+function detectSpawnStartupError(scrollback) {
+  const lines = scrollback.split(/\r?\n/);
+  const tail = lines.slice(Math.max(0, lines.length - STARTUP_ERROR_TAIL_LINES));
+  for (const line of tail) {
+    for (const pattern of STARTUP_ERROR_PATTERNS) {
+      if (pattern.test(line)) return line;
+    }
+  }
+  return void 0;
+}
 async function awaitSpawnLiveness(paneId, agentName) {
   const ms = defaultSpawnLivenessMs();
   if (ms === 0) return;
   await sleep(ms);
   const scrollback = await capturePane(paneId, { lines: 50 }).catch(() => void 0);
-  if (await paneExists(paneId)) return;
-  throw new AgentDiedOnSpawnError(agentName, paneId, scrollback);
+  if (!await paneExists(paneId)) {
+    throw new AgentDiedOnSpawnError(agentName, paneId, scrollback);
+  }
+  if (scrollback !== void 0) {
+    const matchedLine = detectSpawnStartupError(scrollback);
+    if (matchedLine !== void 0) {
+      throw new AgentSpawnStartupError(agentName, paneId, matchedLine, scrollback);
+    }
+  }
 }
 async function createOrReusePane(opts) {
   if (!await sessionExists(opts.session)) {
@@ -3552,6 +3750,36 @@ async function createOrReusePane(opts) {
 }
 
 // src/agents/errors.ts
+var AgentSpawnCliNotFoundError = class extends Error {
+  constructor(cli, binary, envVarChecked) {
+    super(
+      `--cli ${cli} resolved to binary "${binary}" which is not on PATH (and not an executable absolute/relative path). Refusing to spawn \u2014 would create a pane that dies immediately on "command not found".`
+    );
+    this.cli = cli;
+    this.binary = binary;
+    this.envVarChecked = envVarChecked;
+  }
+  cli;
+  binary;
+  envVarChecked;
+  name = "AgentSpawnCliNotFoundError";
+  errorNextSteps() {
+    return [
+      {
+        intent: "Try the default CLI (the one mu's substrate ships against)",
+        command: "mu agent spawn <name> --cli pi"
+      },
+      {
+        intent: "If you meant a custom alias, set the env var to its real path",
+        command: `export ${this.envVarChecked}="<absolute-path-to-binary> [args...]"`
+      },
+      {
+        intent: "List installed CLIs typically supported by mu",
+        command: "which pi pi-meta claude codex"
+      }
+    ];
+  }
+};
 var AgentExistsError = class extends Error {
   constructor(agentName) {
     super(`agent already exists in this workstream: ${agentName}`);
@@ -3672,6 +3900,51 @@ ${tail}
     ];
   }
 };
+var AgentSpawnStartupError = class extends Error {
+  constructor(agentName, paneId, matchedLine, scrollback) {
+    super(
+      `agent ${agentName} reported a startup error within ${defaultSpawnLivenessMs()}ms of spawn (pane ${paneId}). The pane is alive but the spawned CLI parked at an error prompt instead of becoming a working agent.
+
+Matched line: ${matchedLine.trim()}
+
+--- pane scrollback ---
+${scrollback.trim()}
+--- end scrollback ---`
+    );
+    this.agentName = agentName;
+    this.paneId = paneId;
+    this.matchedLine = matchedLine;
+    this.scrollback = scrollback;
+  }
+  agentName;
+  paneId;
+  matchedLine;
+  scrollback;
+  name = "AgentSpawnStartupError";
+  errorNextSteps() {
+    return [
+      {
+        intent: "Inspect the parked pane's scrollback for the full error",
+        command: `mu agent read ${this.agentName} -n 100`
+      },
+      {
+        // Most common today: the operator picked a model whose
+        // provider has no credentials in this env. Default Anthropic
+        // is the safe fallback for pi-meta.
+        intent: "Re-spawn with a CLI command whose provider credentials are present",
+        command: `mu agent spawn ${this.agentName} --command "pi-meta --no-solo"   # default Anthropic`
+      },
+      {
+        intent: "Or set the missing API key env var for the provider you wanted, then re-spawn",
+        command: "export ANTHROPIC_API_KEY=...   # or AWS_BEARER_TOKEN_BEDROCK, OPENAI_API_KEY, ..."
+      },
+      {
+        intent: "Disable the startup-error scan if you actually wanted that prompt (CI / scripted recovery)",
+        command: "export MU_SPAWN_LIVENESS_MS=0"
+      }
+    ];
+  }
+};
 var WorkspacePreservedError = class extends Error {
   constructor(agentName, workspacePath2) {
     super(
@@ -3928,11 +4201,13 @@ async function createWorkspace(db, opts) {
     });
     throw err;
   }
-  emitEvent(
-    db,
-    opts.workstream,
-    `workspace create ${opts.agent} (backend=${backend.name}, path=${path}${created.parentRef ? `, parent=${created.parentRef.slice(0, 12)}` : ""})`
-  );
+  if (opts._suppressEvent !== true) {
+    emitEvent(
+      db,
+      opts.workstream,
+      `workspace create ${opts.agent} (backend=${backend.name}, path=${path}${created.parentRef ? `, parent=${created.parentRef.slice(0, 12)}` : ""})`
+    );
+  }
   return {
     agentName: opts.agent,
     workstreamName: opts.workstream,
@@ -4024,10 +4299,30 @@ async function listCommitsForWorkspace(db, agent, opts) {
   const commits = await backend.commitsSinceBase(row.path, baseRef);
   return { vcs: row.backend, baseRef, commits, workspacePath: row.path };
 }
+async function isWorkspaceClean(row) {
+  const backend = backendByName(row.backend);
+  let clean;
+  try {
+    clean = await backend.isClean(row.path);
+  } catch {
+    return false;
+  }
+  if (!clean) return false;
+  if (row.backend === "none") return true;
+  if (row.parentRef === null || row.parentRef.length === 0) return false;
+  try {
+    const commits = await backend.commitsSinceBase(row.path, row.parentRef);
+    return commits.length === 0;
+  } catch {
+    return false;
+  }
+}
 async function freeWorkspace(db, agent, opts) {
   const row = getWorkspaceForAgent(db, agent, opts.workstream);
   if (!row) return { removed: false, rowDeleted: false };
-  captureSnapshot(db, `workspace free ${agent}`, row.workstreamName);
+  if (opts._suppressEvent !== true) {
+    captureSnapshot(db, `workspace free ${agent}`, row.workstreamName);
+  }
   const backend = backendByName(row.backend);
   const result = await backend.freeWorkspace({
     workspacePath: row.path,
@@ -4039,17 +4334,55 @@ async function freeWorkspace(db, agent, opts) {
              WHERE agent_id = (SELECT id FROM agents WHERE name = ? AND workstream_id = ?)
                AND workstream_id = ?`
   ).run(agent, wsIdForDel, wsIdForDel);
-  emitEvent(
-    db,
-    row.workstreamName,
-    `workspace free ${agent} (backend=${row.backend}, path=${row.path}${result.committedRef ? `, committed=${result.committedRef.slice(0, 12)}` : ""})`
-  );
+  if (opts._suppressEvent !== true) {
+    emitEvent(
+      db,
+      row.workstreamName,
+      `workspace free ${agent} (backend=${row.backend}, path=${row.path}${result.committedRef ? `, committed=${result.committedRef.slice(0, 12)}` : ""})`
+    );
+  }
   return {
     removed: result.removed,
     rowDeleted: del.changes > 0,
     ...result.committedRef !== void 0 ? { committedRef: result.committedRef } : {}
   };
 }
+async function recreateWorkspace(db, agent, opts) {
+  const row = getWorkspaceForAgent(db, agent, opts.workstream);
+  if (!row) throw new WorkspaceNotFoundError(agent);
+  if (opts.force !== true) {
+    const oldBackend = backendByName(row.backend);
+    const dirty = await oldBackend.listDirtyFiles(row.path);
+    if (dirty.length > 0) {
+      throw new WorkspaceDirtyError(row.path, dirty, "recreate");
+    }
+  }
+  captureSnapshot(db, `workspace recreate ${agent}`, row.workstreamName);
+  await freeWorkspace(db, agent, {
+    workstream: opts.workstream,
+    commit: false,
+    _suppressEvent: true
+  });
+  const createOpts = {
+    agent,
+    workstream: opts.workstream,
+    _suppressEvent: true
+  };
+  if (opts.projectRoot !== void 0) createOpts.projectRoot = opts.projectRoot;
+  if (opts.backend !== void 0) {
+    createOpts.backend = opts.backend;
+  } else {
+    createOpts.backend = row.backend;
+  }
+  if (opts.parentRef !== void 0) createOpts.parentRef = opts.parentRef;
+  const fresh = await createWorkspace(db, createOpts);
+  emitEvent(
+    db,
+    opts.workstream,
+    `workspace recreate ${agent} (backend=${fresh.backend}, path=${fresh.path}, old_parent=${row.parentRef ? row.parentRef.slice(0, 12) : "\u2014"}, new_parent=${fresh.parentRef ? fresh.parentRef.slice(0, 12) : "\u2014"})`
+  );
+  return { workspace: fresh, previousParentRef: row.parentRef };
+}
 
 // src/workstream.ts
 var WORKSTREAM_NAME_RE = /^[a-z][a-z0-9_-]{0,31}$/;
@@ -4331,7 +4664,6 @@ async function waitForTasks(db, input, opts) {
   const stuckAfterMs = opts.stuckAfterMs ?? 3e5;
   const onStall = opts.onStall ?? "warn";
   const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : Number.POSITIVE_INFINITY;
-  const startedAt = Date.now();
   for (const ref of refs) {
     if (getTask(db, ref.name, ref.workstreamName) === void 0)
       throw new TaskNotFoundError(`${ref.workstreamName}/${ref.name}`);
@@ -4352,7 +4684,7 @@ async function waitForTasks(db, input, opts) {
     return ageMs >= stuckAfterMs;
   };
   const snapshot = () => {
-    const tasks = refs.map((ref) => {
+    const refStates = refs.map((ref) => {
       const row = getTask(db, ref.name, ref.workstreamName);
       const status = row?.status ?? "OPEN";
       const owner = row?.ownerName ?? null;
@@ -4384,16 +4716,15 @@ async function waitForTasks(db, input, opts) {
         stuck
       };
     });
-    const reachedCount = tasks.filter((t) => t.reachedTarget).length;
     return {
-      tasks,
-      allReached: reachedCount === tasks.length,
-      anyReached: reachedCount > 0,
-      elapsedMs: Date.now() - startedAt,
+      refs: refStates,
       timedOut: false
     };
   };
-  const isDone = (snap2) => wantAny ? snap2.anyReached : snap2.allReached;
+  const isDone = (snap2) => {
+    const reached = snap2.refs.filter((r) => r.reachedTarget).length;
+    return wantAny ? reached > 0 : reached === snap2.refs.length;
+  };
   if (opts.beforePoll) await opts.beforePoll();
   let snap = snapshot();
   if (isDone(snap)) return snap;
@@ -4454,7 +4785,15 @@ function closeTask(db, localId, opts) {
   if (before && before.status !== "CLOSED") {
     captureSnapshot(db, `task close ${localId}`, before.workstreamName);
   }
-  return setTaskStatus(db, localId, "CLOSED", opts);
+  const r = setTaskStatus(db, localId, "CLOSED", opts);
+  if (r.changed && before && opts.evidence !== void 0 && opts.evidence !== "") {
+    const noteOpts = {
+      workstream: before.workstreamName
+    };
+    if (opts.author !== void 0 && opts.author !== "") noteOpts.author = opts.author;
+    addNote(db, localId, `CLOSE: ${opts.evidence}`, noteOpts);
+  }
+  return r;
 }
 function openTask(db, localId, opts) {
   return setTaskStatus(db, localId, "OPEN", opts);
@@ -4707,7 +5046,6 @@ var SELECT_NOTE_COLS = `
 function rowFromDb4(row) {
   return {
     name: row.local_id,
-    localId: row.local_id,
     workstreamName: row.workstream,
     title: row.title,
     status: row.status,
@@ -4762,19 +5100,23 @@ function slugifyTitleVerbose(title) {
     const lastSep = window.lastIndexOf("_");
     trimmed = lastSep > 0 ? window.slice(0, lastSep) : window;
   }
-  const slug = /^[a-z]/.test(trimmed) ? trimmed.slice(0, SLUG_HARD_CAP) : `t_${trimmed}`.slice(0, SLUG_HARD_CAP);
+  const applyPrefix = (s) => /^[a-z]/.test(s) ? s.slice(0, SLUG_HARD_CAP) : `t_${s}`.slice(0, SLUG_HARD_CAP);
+  const slug = applyPrefix(trimmed);
+  const originalSlug = applyPrefix(stripped);
   return {
     slug,
     strippedLength: stripped.length,
+    originalSlug,
     truncated: trimmed.length < stripped.length
   };
 }
 function idFromTitleVerbose(db, workstream, title) {
-  const { slug: base, truncated } = slugifyTitleVerbose(title);
-  if (getTask(db, base, workstream) === void 0) return { id: base, truncated };
+  const { slug: base, truncated, originalSlug } = slugifyTitleVerbose(title);
+  if (getTask(db, base, workstream) === void 0) return { id: base, truncated, originalSlug };
   for (let i = 2; i < 1e3; i++) {
     const candidate = `${base}_${i}`.slice(0, SLUG_HARD_CAP);
-    if (getTask(db, candidate, workstream) === void 0) return { id: candidate, truncated };
+    if (getTask(db, candidate, workstream) === void 0)
+      return { id: candidate, truncated, originalSlug };
   }
   throw new Error(`could not derive a unique id from title in workstream ${workstream}: ${title}`);
 }
@@ -4872,14 +5214,26 @@ function listRecentClosed(db, workstream, limit = 5) {
   ).all(wsId, limit);
   return rows.map(rowFromDb4);
 }
-function listNotes(db, taskLocalId, workstream) {
+function listNotes(db, taskLocalId, workstream, opts = {}) {
   const taskId = taskIdFor(db, taskLocalId, workstream);
   if (taskId === null) return [];
-  const rows = db.prepare(
+  let cutoff = opts.since;
+  if (cutoff === void 0 && opts.sinceClaim === true) {
+    const at = lastClaimEventAt(db, workstream, taskLocalId);
+    if (at !== null) cutoff = at;
+  }
+  const rows = cutoff !== void 0 ? db.prepare(
+    `SELECT ${SELECT_NOTE_COLS} FROM task_notes n JOIN tasks t ON t.id = n.task_id
+              WHERE n.task_id = ? AND n.created_at > ? ORDER BY n.id`
+  ).all(taskId, cutoff) : db.prepare(
     `SELECT ${SELECT_NOTE_COLS} FROM task_notes n JOIN tasks t ON t.id = n.task_id
-        WHERE n.task_id = ? ORDER BY n.id`
+              WHERE n.task_id = ? ORDER BY n.id`
   ).all(taskId);
-  return rows.map(noteFromDb);
+  const mapped = rows.map(noteFromDb);
+  if (opts.tail !== void 0 && opts.tail >= 0) {
+    return opts.tail === 0 ? [] : mapped.slice(-opts.tail);
+  }
+  return mapped;
 }
 function listTasksByOwner(db, workstream, owner, opts = {}) {
   const filter = opts.includeClosed ? "" : "AND t.status NOT IN ('CLOSED', 'REJECTED', 'DEFERRED')";
@@ -5287,6 +5641,140 @@ async function adoptAgent(db, opts) {
   };
 }
 
+// src/agents/kick.ts
+var ALLOWED_SIGNALS = ["SIGINT", "SIGTERM", "SIGKILL"];
+function isKickSignal(s) {
+  return ALLOWED_SIGNALS.includes(s);
+}
+var NoForegroundProcessError = class extends Error {
+  constructor(agentName, tty, reason) {
+    const detail = reason === "no-foreground" ? `no foreground process group on tty ${tty} (pane is idle)` : `the only foreground process on tty ${tty} is the agent's wrapping CLI itself; refusing to signal it (use \`mu agent close ${agentName}\` to close the agent)`;
+    super(`agent ${agentName}: ${detail}`);
+    this.agentName = agentName;
+    this.tty = tty;
+    this.reason = reason;
+  }
+  agentName;
+  tty;
+  reason;
+  name = "NoForegroundProcessError";
+  errorNextSteps() {
+    return [
+      {
+        intent: "Inspect what's running in the pane",
+        command: `mu agent show ${this.agentName} -n 50`
+      },
+      {
+        intent: "Close the agent (kills the wrapping CLI + pane)",
+        command: `mu agent close ${this.agentName}`
+      }
+    ];
+  }
+};
+var realExecutor2 = async (cmd, args) => {
+  const { execa: execa2 } = await import("execa");
+  const result = await execa2(cmd, [...args], { reject: false });
+  return {
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    exitCode: result.exitCode ?? null
+  };
+};
+var currentExecutor2 = realExecutor2;
+function parsePsTtyOutput(output) {
+  const rows = [];
+  for (const raw of output.split("\n")) {
+    const line = raw.trim();
+    if (line === "") continue;
+    const parts = line.split(/\s+/);
+    if (parts.length < 4) continue;
+    const [pidStr, pgidStr, stat2, ...commParts] = parts;
+    if (pidStr === void 0 || pgidStr === void 0 || stat2 === void 0) continue;
+    const pid = Number.parseInt(pidStr, 10);
+    const pgid = Number.parseInt(pgidStr, 10);
+    if (!Number.isFinite(pid) || !Number.isFinite(pgid)) continue;
+    rows.push({ pid, pgid, stat: stat2, comm: commParts.join(" ") });
+  }
+  return rows;
+}
+var WRAPPER_COMM_PREFIXES = [
+  "pi",
+  "claude",
+  "codex",
+  "bash",
+  "zsh",
+  "sh",
+  "fish",
+  "dash"
+];
+function isWrapperComm(comm) {
+  const cleaned = comm.replace(/^-/, "").trim();
+  if (cleaned === "") return false;
+  for (const prefix of WRAPPER_COMM_PREFIXES) {
+    if (cleaned === prefix) return true;
+    if (cleaned.startsWith(`${prefix}-`)) return true;
+  }
+  return false;
+}
+async function foregroundPgid(tty) {
+  const ttyShort = tty.startsWith("/dev/") ? tty.slice("/dev/".length) : tty;
+  const result = await currentExecutor2("ps", ["-t", ttyShort, "-o", "pid=,pgid=,stat=,comm="]);
+  if (result.exitCode !== 0 && result.stdout.trim() === "") {
+    return { kind: "no-foreground", rows: [] };
+  }
+  const rows = parsePsTtyOutput(result.stdout);
+  if (rows.length === 0) return { kind: "no-foreground", rows };
+  const fg = rows.find((r) => r.stat.includes("+"));
+  if (!fg) {
+    return { kind: "no-foreground", rows };
+  }
+  if (isWrapperComm(fg.comm)) {
+    return { kind: "shell-only", pgid: fg.pgid, fgRow: fg, rows };
+  }
+  return { kind: "ok", pgid: fg.pgid, fgRow: fg, rows };
+}
+async function killPgrp(pgid, signal) {
+  const result = await currentExecutor2("kill", [`-${signal}`, `-${pgid}`]);
+  if (result.exitCode !== 0) {
+    if (/no such process/i.test(result.stderr)) return;
+    throw new Error(
+      `kill -${signal} -${pgid} failed (exit ${result.exitCode}): ${result.stderr.trim() || "no stderr"}`
+    );
+  }
+}
+async function kickAgent(db, name, opts) {
+  const signal = opts.signal ?? "SIGINT";
+  const agent = getAgent(db, name, opts.workstream);
+  if (!agent) throw new AgentNotFoundError(name, opts.workstream);
+  const tty = await paneTTY(agent.paneId);
+  const lookup = await foregroundPgid(tty);
+  if (lookup.kind === "no-foreground") {
+    throw new NoForegroundProcessError(name, tty, "no-foreground");
+  }
+  if (lookup.kind === "shell-only") {
+    throw new NoForegroundProcessError(name, tty, "shell-only");
+  }
+  const pgid = lookup.pgid;
+  const fgRow = lookup.fgRow;
+  if (pgid === void 0 || fgRow === void 0) {
+    throw new NoForegroundProcessError(name, tty, "no-foreground");
+  }
+  await killPgrp(pgid, signal);
+  emitEvent(
+    db,
+    agent.workstreamName,
+    `agent kick ${name} (signal=${signal}, pgid=${pgid}, comm=${fgRow.comm})`
+  );
+  return {
+    agentName: name,
+    paneId: agent.paneId,
+    tty,
+    signaledPgid: pgid,
+    signal,
+    foregroundComm: fgRow.comm
+  };
+}
+
 // src/agents.ts
 var DEFAULT_IDLE_THRESHOLD_MS = 3e5;
 function idleThresholdMs() {
@@ -5511,15 +5999,24 @@ function freeAgent(db, name, workstream) {
 async function closeAgent(db, name, opts) {
   const agent = getAgent(db, name, opts.workstream);
   if (!agent) {
-    return { killedPane: false, deletedRow: false, workspaceFreed: false };
+    return {
+      killedPane: false,
+      deletedRow: false,
+      workspaceFreed: false,
+      workspaceAutoFreedClean: false
+    };
   }
   const ws = getWorkspaceForAgent(db, name, agent.workstreamName);
+  let autoFreeClean = false;
   if (ws !== void 0 && opts.discardWorkspace !== true) {
-    throw new WorkspacePreservedError(name, ws.path);
+    autoFreeClean = await isWorkspaceClean(ws);
+    if (!autoFreeClean) {
+      throw new WorkspacePreservedError(name, ws.path);
+    }
   }
   captureSnapshot(db, `agent close ${name}`, agent.workstreamName);
   let workspaceFreed = false;
-  if (ws !== void 0 && opts.discardWorkspace === true) {
+  if (ws !== void 0 && (opts.discardWorkspace === true || autoFreeClean)) {
     await freeWorkspace(db, name, { commit: false, workstream: agent.workstreamName });
     workspaceFreed = true;
   }
@@ -5529,12 +6026,13 @@ async function closeAgent(db, name, opts) {
   emitEvent(
     db,
     agent.workstreamName,
-    `agent close ${name} (pane=${agent.paneId}${workspaceFreed ? ", workspace discarded" : ""})`
+    `agent close ${name} (pane=${agent.paneId}${workspaceFreed ? autoFreeClean ? ", workspace auto-freed (clean)" : ", workspace discarded" : ""})`
   );
   return {
     killedPane: true,
     deletedRow,
-    workspaceFreed
+    workspaceFreed,
+    workspaceAutoFreedClean: workspaceFreed && autoFreeClean
   };
 }
 async function listLiveAgents(db, opts) {
@@ -5682,9 +6180,10 @@ function formatEdgeList(edges, dim) {
 }
 async function cmdTaskAdd(db, localId, opts) {
   const workstream = await resolveWorkstream(opts.workstream);
+  const autoDerived = localId === void 0;
   let derivation;
   if (localId !== void 0) {
-    derivation = { id: localId, truncated: false };
+    derivation = { id: localId, truncated: false, originalSlug: localId };
   } else {
     derivation = idFromTitleVerbose(db, workstream, opts.title);
   }
@@ -5718,7 +6217,13 @@ async function cmdTaskAdd(db, localId, opts) {
     }
   ];
   if (opts.json) {
-    emitJson({ task: withRoiAll([task])[0], blockers: blockedBy ?? [], nextSteps });
+    const truncationFields = autoDerived && derivation.truncated ? { truncated: true, originalSlug: derivation.originalSlug } : {};
+    emitJson({
+      task: withRoiAll([task])[0],
+      blockers: blockedBy ?? [],
+      nextSteps,
+      ...truncationFields
+    });
     return;
   }
   if (derivation.truncated) {
@@ -5807,12 +6312,32 @@ async function cmdTaskShow(db, rawId, opts = {}) {
   }
 }
 async function cmdTaskNotes(db, rawId, opts = {}) {
+  if (opts.since !== void 0 && opts.sinceClaim === true) {
+    throw new UsageError(
+      "--since and --since-claim are mutually exclusive (both define a cutoff); pick one"
+    );
+  }
+  if (opts.tail !== void 0 && (!Number.isFinite(opts.tail) || opts.tail <= 0 || !Number.isInteger(opts.tail))) {
+    throw new UsageError(`--tail must be a positive integer (got ${JSON.stringify(opts.tail)})`);
+  }
+  if (opts.since !== void 0) {
+    const parsed = Date.parse(opts.since);
+    if (Number.isNaN(parsed)) {
+      throw new UsageError(
+        `--since must be an ISO 8601 timestamp (got ${JSON.stringify(opts.since)})`
+      );
+    }
+  }
   const { name: localId } = await resolveEntityRef(db, rawId, opts, "task");
   assertTaskInWorkstream(db, localId, opts.workstream);
   const ws = await resolveWorkstream(opts.workstream);
   const task = getTask(db, localId, ws);
   if (!task) throw new TaskNotFoundError(localId);
-  const notes = listNotes(db, localId, task.workstreamName);
+  const filterOpts = {};
+  if (opts.tail !== void 0) filterOpts.tail = opts.tail;
+  if (opts.since !== void 0) filterOpts.since = opts.since;
+  if (opts.sinceClaim === true) filterOpts.sinceClaim = true;
+  const notes = listNotes(db, localId, task.workstreamName, filterOpts);
   if (opts.json) {
     emitJsonCollection(notes);
     return;
@@ -6015,10 +6540,12 @@ async function cmdTaskWait(db, ids, opts) {
       priorState.set(key, { status, owner });
     }
   };
+  const startedAt = Date.now();
   const result = await waitForTasks(db, refs, sdkOpts);
-  const firingRef = wantFirstShape && !result.timedOut ? result.tasks.find((t) => t.reachedTarget) ?? null : null;
-  const reachedRefs = result.tasks.filter((t) => t.reachedTarget);
-  const unmetRefs = result.tasks.filter((t) => !t.reachedTarget);
+  const elapsedMs = Date.now() - startedAt;
+  const firingRef = wantFirstShape && !result.timedOut ? result.refs.find((t) => t.reachedTarget) ?? null : null;
+  const reachedRefs = result.refs.filter((t) => t.reachedTarget);
+  const unmetRefs = result.refs.filter((t) => !t.reachedTarget);
   const nextSteps = [];
   if (!result.timedOut && firingRef !== null) {
     const owner = firingRef.owner;
@@ -6030,7 +6557,7 @@ async function cmdTaskWait(db, ids, opts) {
     }
     nextSteps.push({
       intent: "Verify the cherry-pick",
-      command: "npm run typecheck && npm run lint && npm run test && npm run build"
+      command: "<your project verify command \u2014 e.g. npm run test, cargo test, uv run pytest>"
     });
     if (owner !== null) {
       nextSteps.push({
@@ -6041,7 +6568,7 @@ async function cmdTaskWait(db, ids, opts) {
   } else if (!result.timedOut && wantFirstShape === false) {
     nextSteps.push({
       intent: "Verify the merged work",
-      command: "npm run typecheck && npm run lint && npm run test && npm run build"
+      command: "<your project verify command \u2014 e.g. npm run test, cargo test, uv run pytest>"
     });
   }
   for (const t of unmetRefs) {
@@ -6068,7 +6595,6 @@ async function cmdTaskWait(db, ids, opts) {
     };
     const timedOutArray = result.timedOut ? unmetRefs.map((t) => ({ ...t, qualifiedId: qualifiedId(t) })) : [];
     emitJson({
-      ...result,
       firing: firingJson,
       all: reachedRefs.map((t) => ({
         ...t,
@@ -6085,11 +6611,11 @@ async function cmdTaskWait(db, ids, opts) {
   if (firingRef !== null) {
     console.log(qualifiedId(firingRef));
   }
-  const summary = result.timedOut ? pc.yellow(`Timed out after ${result.elapsedMs}ms`) : pc.green(
-    `${wantAny ? "any-of" : "all-of"} ${refs.length} reached ${targetStatus} in ${result.elapsedMs}ms`
+  const summary = result.timedOut ? pc.yellow(`Timed out after ${elapsedMs}ms`) : pc.green(
+    `${wantAny ? "any-of" : "all-of"} ${refs.length} reached ${targetStatus} in ${elapsedMs}ms`
   );
   console.log(summary);
-  for (const t of result.tasks) {
+  for (const t of result.refs) {
     const marker = t.reachedTarget ? pc.green("\u2713") : pc.dim("\u2022");
     const label = workstreamSet.size > 1 ? qualifiedId(t) : t.name;
     console.log(`  ${marker} ${pc.bold(label)} ${pc.dim(`(${t.status})`)}`);
@@ -6232,6 +6758,9 @@ async function cmdTaskClose(db, rawId, opts = {}) {
   const sdkOpts = { workstream: ws };
   if (opts.evidence !== void 0) sdkOpts.evidence = opts.evidence;
   if (opts.ifReady) sdkOpts.ifReady = true;
+  if (opts.evidence !== void 0 && opts.evidence !== "") {
+    sdkOpts.author = await resolveActorIdentity();
+  }
   const taskRow = getTask(db, localId, ws);
   const r = closeTask(db, localId, sdkOpts);
   if ("skipped" in r) {
@@ -6537,9 +7066,21 @@ function wireTaskCommands(program) {
     const opts = this.opts();
     return handle((db) => cmdTaskTree(db, id, opts), this)();
   });
-  task.command("notes <id>").description("List the notes attached to a task (oldest first)").option(...WORKSTREAM_OPT).option(...JSON_OPT).action(function(id) {
+  task.command("notes <id>").description(
+    "List the notes attached to a task (oldest first). Filters: --tail N (last N), --since <iso> (after timestamp), --since-claim (since most recent claim event)."
+  ).option(...WORKSTREAM_OPT).option(...JSON_OPT).option("--tail <n>", "print only the last N notes (alias --last)", parsePositiveNumber).option("--last <n>", "alias for --tail", parsePositiveNumber).option("--since <iso>", "print only notes created after this ISO 8601 timestamp").option(
+    "--since-claim",
+    "print only notes since the most recent 'task claim' event (auto-resolved)"
+  ).action(function(id) {
     const opts = this.opts();
-    return handle((db) => cmdTaskNotes(db, id, opts), this)();
+    const tail = opts.tail ?? opts.last;
+    const merged = {};
+    if (opts.json !== void 0) merged.json = opts.json;
+    if (opts.workstream !== void 0) merged.workstream = opts.workstream;
+    if (tail !== void 0) merged.tail = tail;
+    if (opts.since !== void 0) merged.since = opts.since;
+    if (opts.sinceClaim !== void 0) merged.sinceClaim = opts.sinceClaim;
+    return handle((db) => cmdTaskNotes(db, id, merged), this)();
   });
   const EVIDENCE_OPT = [
     "--evidence <text>",
@@ -6683,6 +7224,7 @@ async function cmdSpawn(db, name, opts) {
   const workspace = opts.workspace ? getWorkspaceForAgent(db, name, workstream) : void 0;
   const resolvedCommand = opts.command ?? resolveCliCommand(agent.cli);
   const commandOverridden = resolvedCommand !== agent.cli;
+  const envSourced = opts.command === void 0 ? resolveCliCommandWithSource(agent.cli) : void 0;
   const nextSteps = [
     { intent: "Send work", command: `mu agent send ${name} "..." -w ${workstream}` },
     { intent: "Read pane", command: `mu agent read ${name} -w ${workstream}` },
@@ -6698,12 +7240,16 @@ async function cmdSpawn(db, name, opts) {
       workspace: workspace ?? null,
       resolvedCommand,
       commandOverridden,
+      // env-var attribution for machine consumers: present iff the
+      // resolution came from $MU_<UPPER_CLI>_COMMAND. Mirrors the
+      // human `(via $MU_PI_META_COMMAND)` suffix below.
+      ...envSourced?.resolvedFromEnv ? { resolvedFromEnvVar: envSourced.envVar } : {},
       nextSteps
     });
     return;
   }
   const wsBit = opts.workspace ? pc.dim(" with auto-workspace") : "";
-  const cliDisplay = commandOverridden ? `${agent.cli} ${pc.dim(`(cmd: ${resolvedCommand})`)}` : agent.cli;
+  const cliDisplay = opts.command !== void 0 ? `${agent.cli} ${pc.dim(`(cmd: ${resolvedCommand})`)}` : envSourced?.resolvedFromEnv ? `${agent.cli} ${pc.dim(`(via $${envSourced.envVar})`)}` : agent.cli;
   console.log(
     `Spawned ${pc.bold(agent.name)} (${cliDisplay}) in window ${pc.bold(agent.tab ?? agent.name)} of ${pc.bold(`mu-${workstream}`)}, pane ${pc.dim(agent.paneId)}${wsBit}`
   );
@@ -6761,7 +7307,7 @@ async function cmdList(db, opts) {
     console.log(pc.dim("  Panes that look like agents but aren't in the registry."));
     console.log(
       pc.dim(
-        "  Run `mu adopt <pane-id>` to register one as a managed agent (e.g. `mu adopt %15`)."
+        "  Run `mu agent adopt <pane-id>` to register one as a managed agent (e.g. `mu agent adopt %15`)."
       )
     );
     for (const orphan of view.orphans) {
@@ -6848,7 +7394,7 @@ async function cmdClose(db, rawName, opts = {}) {
   const next = [];
   if (result.workspaceFreed) {
     next.push({
-      intent: "Workspace was freed alongside the agent (--discard-workspace)",
+      intent: result.workspaceAutoFreedClean ? "Workspace was clean (no uncommitted changes, no commits since fork) so it was auto-freed alongside the agent" : "Workspace was freed alongside the agent (--discard-workspace)",
       command: "cd /  # the workspace dir is gone"
     });
   }
@@ -6865,7 +7411,7 @@ async function cmdClose(db, rawName, opts = {}) {
     printNextSteps(next);
     return;
   }
-  const wsBit = result.workspaceFreed ? pc.dim(" (workspace discarded)") : "";
+  const wsBit = result.workspaceFreed ? pc.dim(result.workspaceAutoFreedClean ? " (workspace auto-freed)" : " (workspace discarded)") : "";
   console.log(`Closed ${pc.bold(name)}${wsBit}`);
   printNextSteps(next);
 }
@@ -6924,6 +7470,41 @@ async function cmdAdopt(db, paneOrTitle, opts) {
   }
   printNextSteps(nextSteps);
 }
+async function cmdKick(db, rawName, opts = {}) {
+  const { name } = await resolveEntityRef(db, rawName, opts, "agent");
+  assertAgentInWorkstream(db, name, opts.workstream);
+  const ws = await resolveWorkstream(opts.workstream);
+  const sigRaw = opts.signal ?? "SIGINT";
+  if (!isKickSignal(sigRaw)) {
+    throw new UsageError(
+      `--signal must be one of SIGINT, SIGTERM, SIGKILL (got ${JSON.stringify(sigRaw)})`
+    );
+  }
+  const signal = sigRaw;
+  const result = await kickAgent(db, name, { workstream: ws, signal });
+  const nextSteps = [
+    {
+      intent: "Read the pane to confirm the tool aborted",
+      command: `mu agent read ${name} -n 30 -w ${ws}`
+    },
+    {
+      intent: "Send follow-up steering once the prompt returns",
+      command: `mu agent send ${name} '...' -w ${ws}`
+    },
+    {
+      intent: "Escalate (graceful \u2192 polite \u2192 hammer)",
+      command: `mu agent kick ${name} --signal SIGTERM -w ${ws}`
+    }
+  ];
+  if (opts.json) {
+    emitJson({ ...result, nextSteps });
+    return;
+  }
+  console.log(
+    `Kicked ${pc.bold(name)} ${pc.dim(`(signal=${result.signal}, pgid=${result.signaledPgid}, comm=${result.foregroundComm}, tty=${result.tty})`)}`
+  );
+  printNextSteps(nextSteps);
+}
 async function cmdFree(db, rawName, opts = {}) {
   const { name } = await resolveEntityRef(db, rawName, opts, "agent");
   assertAgentInWorkstream(db, name, opts.workstream);
@@ -7007,7 +7588,7 @@ function wireAgentCommands(program) {
     return handle((db) => cmdAgentShow(db, name, opts), this)();
   });
   agent.command("close <name>").description(
-    "Kill an agent's pane and remove its registry row. If the agent has a workspace, refuses by default (would orphan the on-disk dir); pass --discard-workspace to free both, or run `mu workspace free <agent>` first."
+    "Kill an agent's pane and remove its registry row. If the agent has a clean workspace (no uncommitted changes AND no commits since fork) it is auto-freed alongside the close; otherwise close refuses (would orphan or lose work) \u2014 pass --discard-workspace to free both anyway (lossy), or run `mu workspace free <agent>` first."
   ).option(
     "--discard-workspace",
     "free the agent's workspace alongside close (lossy: pending changes are gone)"
@@ -7015,6 +7596,16 @@ function wireAgentCommands(program) {
     const opts = this.opts();
     return handle((db) => cmdClose(db, name, opts), this)();
   });
+  agent.command("kick <name>").description(
+    "Signal the foreground process group of an agent's pane TTY (escape hatch for a worker wedged on an unbounded `find` / busy-wait loop). Default --signal SIGINT (graceful, matches Ctrl-C). Refuses when the foreground is the wrapping CLI itself \u2014 use `mu agent close` to close the agent."
+  ).option(
+    "--signal <sig>",
+    "signal to send: SIGINT (default; graceful), SIGTERM (polite), SIGKILL (hammer)",
+    "SIGINT"
+  ).option(...WORKSTREAM_OPT).option(...JSON_OPT).action(function(name) {
+    const opts = this.opts();
+    return handle((db) => cmdKick(db, name, opts), this)();
+  });
   agent.command("free <name>").description(
     "Mark an agent's status as 'free' (idempotent). Pane untouched; reconcile flips back to busy on real activity."
   ).option(...WORKSTREAM_OPT).option(...JSON_OPT).action(function(name) {
@@ -7025,7 +7616,7 @@ function wireAgentCommands(program) {
     const opts = this.opts();
     return handle((db) => cmdAttach(db, name, opts), this)();
   });
-  program.command("adopt <pane-or-title>").description(
+  agent.command("adopt <pane-or-title>").description(
     "Register an existing tmux pane as a managed mu agent (the inverse of `mu agent list`'s 'orphan' state). Pane id form '%15' or pane title form 'worker-2'."
   ).option("--name <name>", "agent name (defaults to the pane's current title)").option("--cli <cli>", "agent CLI key (default: pi)").option("--role <role>", "full-access | read-only", "full-access").option(...WORKSTREAM_OPT).option(...JSON_OPT).action(function(paneOrTitle) {
     const opts = this.optsWithGlobals();
@@ -7737,24 +8328,6 @@ var ImportSourceNotInBucketError = class extends Error {
     ];
   }
 };
-var ImportLegacyLayoutError = class extends Error {
-  constructor(bucketDir) {
-    super(
-      `${bucketDir} is a pre-0.3 (single-workstream) export; mu workstream import requires bucketVersion 2. Re-export with mu \u2265 0.3, or run mu workstream import on a freshly-rendered bucket.`
-    );
-    this.bucketDir = bucketDir;
-  }
-  bucketDir;
-  name = "ImportLegacyLayoutError";
-  errorNextSteps() {
-    return [
-      {
-        intent: "Re-export the source workstream into a new bucket",
-        command: "mu workstream export -w <ws> --out <new-bucket-dir>"
-      }
-    ];
-  }
-};
 var WorkstreamAlreadyExistsError = class extends Error {
   constructor(workstream) {
     super(
@@ -8038,9 +8611,6 @@ function walkBucket(bucketDir) {
   if (probe.kind === "corrupt") {
     throw new ImportBucketInvalidError(bucketDir, "manifest.json is unreadable / malformed");
   }
-  if (probe.kind === "legacy") {
-    throw new ImportLegacyLayoutError(bucketDir);
-  }
   const tasksDir = join7(bucketDir, "tasks");
   const looksLikeSourceWs = existsSync6(join7(bucketDir, "README.md")) && existsSync6(join7(bucketDir, "INDEX.md")) && existsSync6(tasksDir) && statSync3(tasksDir).isDirectory();
   if (!looksLikeSourceWs) {
@@ -8295,7 +8865,7 @@ var NameAmbiguousError = class extends Error {
   }
 };
 function classifyError(err) {
-  if (err instanceof UsageError || err instanceof WorkstreamNameInvalidError || err instanceof ArchiveLabelInvalidError || err instanceof LegacyExportLayoutError || err instanceof ImportBucketInvalidError || err instanceof ImportLegacyLayoutError || err instanceof ImportFrontmatterParseError || err instanceof ImportEdgeRefMissingError || err instanceof PruneOptionsInvalidError) {
+  if (err instanceof UsageError || err instanceof WorkstreamNameInvalidError || err instanceof ArchiveLabelInvalidError || err instanceof ImportBucketInvalidError || err instanceof ImportFrontmatterParseError || err instanceof ImportEdgeRefMissingError || err instanceof PruneOptionsInvalidError) {
     return { label: "error", exitCode: 2 };
   }
   if (err instanceof AgentNotFoundError || err instanceof TaskNotFoundError || err instanceof WorkstreamNotFoundError || err instanceof WorkspaceNotFoundError || err instanceof SnapshotNotFoundError || err instanceof ArchiveNotFoundError) {
@@ -8304,9 +8874,15 @@ function classifyError(err) {
   if (err instanceof NameAmbiguousError || err instanceof AgentExistsError || err instanceof TaskExistsError || err instanceof TaskAlreadyOwnedError || err instanceof TaskNotInWorkstreamError || err instanceof AgentNotInWorkstreamError || err instanceof CycleError || err instanceof TaskHasOpenDependentsError || err instanceof CrossWorkstreamEdgeError || err instanceof WorkspaceExistsError || err instanceof WorkspacePathNotEmptyError || err instanceof WorkspacePreservedError || err instanceof HomeDirAsProjectRootError || err instanceof WorkspaceVcsRequiredError || err instanceof WorkspaceDirtyError || err instanceof ClaimerNotRegisteredError || err instanceof SnapshotVersionMismatchError || err instanceof SchemaTooOldError || err instanceof TaskIdInvalidError || err instanceof ArchiveAlreadyExistsError || err instanceof ImportSourceNotInBucketError || err instanceof WorkstreamAlreadyExistsError) {
     return { label: "conflict", exitCode: 4 };
   }
+  if (err instanceof AgentSpawnCliNotFoundError) {
+    return { label: "spawn cli not found", exitCode: 1 };
+  }
   if (err instanceof AgentDiedOnSpawnError) {
     return { label: "spawn failed", exitCode: 1 };
   }
+  if (err instanceof AgentSpawnStartupError) {
+    return { label: "spawn startup error", exitCode: 1 };
+  }
   if (err instanceof TmuxError || err instanceof PaneNotFoundError) {
     return { label: "tmux", exitCode: 5 };
   }
@@ -8954,7 +9530,7 @@ async function cmdSnapshotShow(db, id, opts = {}) {
 }
 function wireSnapshotCommands(program) {
   program.command("undo").description(
-    "Restore the most recent snapshot (or one selected via --to). Pass --yes to actually restore; otherwise prints a dry-run summary. tmux state is NOT rolled back \u2014 the post-restore reconcile prunes ghost agents and surfaces orphan panes; re-spawn or `mu adopt` as needed."
+    "Restore the most recent snapshot (or one selected via --to). Pass --yes to actually restore; otherwise prints a dry-run summary. tmux state is NOT rolled back \u2014 the post-restore reconcile prunes ghost agents and surfaces orphan panes; re-spawn or `mu agent adopt` as needed."
   ).option("--to <id>", "snapshot id to restore (default: most recent)", parseLines).option("-y, --yes", "actually restore (without this flag, prints a dry-run summary)").option(...JSON_OPT).action(function() {
     const opts = this.opts();
     return handle((db) => cmdUndo(db, opts), this)();
@@ -9912,6 +10488,38 @@ async function cmdWorkspaceList(db, opts) {
   }
   console.log(formatWorkspacesTable(decorated));
 }
+async function cmdWorkspaceRecreate(db, rawAgent, opts) {
+  const { name: agent } = await resolveEntityRef(db, rawAgent, opts, "workspace");
+  assertAgentInWorkstream(db, agent, opts.workstream);
+  const workstream = await resolveWorkstream(opts.workstream);
+  const recreateOpts = { workstream };
+  if (opts.backend !== void 0) recreateOpts.backend = opts.backend;
+  if (opts.from !== void 0) recreateOpts.parentRef = opts.from;
+  if (opts.projectRoot !== void 0) recreateOpts.projectRoot = opts.projectRoot;
+  if (opts.force === true) recreateOpts.force = true;
+  const r = await recreateWorkspace(db, agent, recreateOpts);
+  const nextSteps = [
+    {
+      intent: "Send work to the agent (workspace is ready)",
+      command: `mu agent send ${agent} -w ${workstream} "<prompt>"`
+    },
+    {
+      intent: "cd into the freshly recreated workspace",
+      command: `cd $(mu workspace path ${agent} -w ${workstream})`
+    },
+    { intent: "List workspaces in this workstream", command: `mu workspace list -w ${workstream}` }
+  ];
+  if (opts.json) {
+    emitJson({ workspace: r.workspace, previousParentRef: r.previousParentRef, nextSteps });
+    return;
+  }
+  const oldRef = r.previousParentRef ? r.previousParentRef.slice(0, 12) : "\u2014";
+  const newRef = r.workspace.parentRef ? r.workspace.parentRef.slice(0, 12) : "\u2014";
+  console.log(
+    `Recreated workspace ${pc.bold(agent)} ${pc.dim(`(backend=${r.workspace.backend}, ${oldRef} \u2192 ${newRef})`)}`
+  );
+  printNextSteps(nextSteps);
+}
 async function cmdWorkspaceFree(db, rawAgent, opts) {
   const { name: agent } = await resolveEntityRef(db, rawAgent, opts, "workspace");
   assertAgentInWorkstream(db, agent, opts.workstream);
@@ -10082,6 +10690,15 @@ function wireWorkspaceCommands(program) {
     const opts = this.opts();
     return handle((db) => cmdWorkspaceFree(db, agent, opts), this)();
   });
+  workspace.command("recreate <agent>").description(
+    "Free + create an agent's workspace in one shot \u2014 the canonical between-wave \"prep this worker for the next dispatch\" verb. Atomic guarantees match the underlying free + create pair (one pre-mutation snapshot, one `workspace recreate` event in the audit trail). Reuses the previous backend unless --backend overrides; bases on the project's current main unless --from <ref> overrides. Refuses on a dirty workspace (uncommitted changes) the same way `free` does \u2014 pass --force to discard the dirty changes (the lossy escape hatch)."
+  ).option(
+    "--backend <name>",
+    "force a backend instead of reusing the previous one (jj | sl | git | none)"
+  ).option("--from <ref>", "base the new workspace on a specific commit / branch / changeset").option("--project-root <path>", "override the project root to branch from (default: cwd)").option("--force", "discard uncommitted changes in the existing workspace (the lossy escape)").option(...WORKSTREAM_OPT).option(...JSON_OPT).action(function(agent) {
+    const opts = this.opts();
+    return handle((db) => cmdWorkspaceRecreate(db, agent, opts), this)();
+  });
   workspace.command("commits <agent>").description(
     "Print commits the agent's workspace has on top of its recorded parent_ref (the fork point), oldest-first. Default text output is `<sha> <subject>` per line; --json emits the full array `[{sha, subject, body, authorDate}]` for piping. --since <ref> overrides the base. The `none` backend errors (no fork point to compare against)."
   ).option("--since <ref>", "override the base ref (default: workspace's recorded parent_ref)").option(...WORKSTREAM_OPT).option(...JSON_OPT).action(function(agent) {
@@ -11188,12 +11805,22 @@ function applyExitOverride(cmd) {
     applyExitOverride(sub);
   }
 }
+function injectBareNamespaceHelp(program, argv) {
+  if (argv.length !== 3) return argv;
+  const token = argv[2];
+  if (token === void 0 || token.startsWith("-")) return argv;
+  const sub = program.commands.find((c) => c.name() === token || c.aliases().includes(token));
+  if (!sub) return argv;
+  if (sub.commands.length === 0) return argv;
+  return [...argv, "--help"];
+}
 if (isMainEntrypoint()) {
   const program = buildProgram();
+  const argv = injectBareNamespaceHelp(program, process.argv);
   try {
-    await program.parseAsync(process.argv);
+    await program.parseAsync(argv);
   } catch (err) {
-    const failingCmd = findCommandForArgv(program, process.argv.slice(2));
+    const failingCmd = findCommandForArgv(program, argv.slice(2));
     const exitCode = emitParseError(err, failingCmd);
     process.exit(exitCode);
   }
@@ -11233,6 +11860,7 @@ export {
   formatWorkspacesTable,
   formatWorkstreamsTable,
   handle,
+  injectBareNamespaceHelp,
   isTaskSortKey,
   parseCsvFlag,
   parseImpact,