@martintrojer/mu 0.3.1 → 0.3.2

package/dist/index.js

@@ -510,6 +510,18 @@ function formatClaimEvent(opts) {
   const self = opts.anonymous ? "1" : "0";
   return `${CLAIM_EVENT_PREFIX}	${opts.localId}	actor=${opts.actor}	self=${self}	${opts.prose}`;
 }
+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;
+}
 
 // src/detect.ts
 var TAIL_WINDOW_LINES = 100;
@@ -569,6 +581,7 @@ __export(tmux_exports, {
   newSessionWithPane: () => newSessionWithPane,
   newWindow: () => newWindow,
   paneExists: () => paneExists,
+  paneTTY: () => paneTTY,
   parseAgentNameFromTitle: () => parseAgentNameFromTitle,
   resetSleep: () => resetSleep,
   resetTmuxExecutor: () => resetTmuxExecutor,
@@ -913,6 +926,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}"]);
@@ -1583,7 +1614,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 = [
@@ -1591,9 +1622,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;
@@ -2162,16 +2193,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));
@@ -2342,9 +2363,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) {
@@ -2372,9 +2390,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;
@@ -2548,7 +2563,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
@@ -2626,24 +2640,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)`
       },
       {
@@ -2651,6 +2671,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 {
@@ -2719,6 +2746,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) {
@@ -2728,6 +2762,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 = {
@@ -2748,6 +2787,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
@@ -2890,6 +2943,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) {
@@ -2998,6 +3055,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
@@ -3118,6 +3192,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) {
@@ -3189,6 +3270,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
@@ -3265,6 +3358,10 @@ var slBackend = {
       workspacePath2
     );
     return parseNulRecords(out).reverse();
+  },
+  async listDirtyFiles(workspacePath2) {
+    if (!existsSync3(workspacePath2)) return [];
+    return listSlDirtyFiles(workspacePath2);
   }
 };
 async function listSlDirtyFiles(workspacePath2) {
@@ -3307,6 +3404,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";
@@ -3333,10 +3434,55 @@ 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;
+function setCommandResolverForTests(resolver) {
+  activeCommandResolver = resolver;
+}
+function resetCommandResolverForTests() {
+  activeCommandResolver = defaultCommandResolver;
+}
+async function checkCommandResolvable(command) {
+  return activeCommandResolver(command);
+}
 async function spawnAgent(db, opts) {
   if (!isValidAgentName(opts.name)) {
     throw new TypeError(
@@ -3350,33 +3496,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(
@@ -3436,7 +3585,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(() => {
@@ -3444,6 +3593,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;
@@ -3451,13 +3616,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)) {
@@ -3488,6 +3691,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}`);
@@ -3608,6 +3841,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(
@@ -3864,11 +4142,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,
@@ -3934,10 +4214,30 @@ async function mapWithConcurrency(items, limit, fn) {
   await Promise.all(Array.from({ length: workerCount }, () => worker()));
   return results;
 }
+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,
@@ -3949,17 +4249,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}$/;
@@ -4218,7 +4556,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}`);
@@ -4239,7 +4576,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;
@@ -4271,16 +4608,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;
@@ -4341,7 +4677,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);
@@ -4594,7 +4938,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,
@@ -4652,10 +4995,13 @@ 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
   };
 }
@@ -4663,11 +5009,12 @@ function idFromTitle(db, workstream, title) {
   return idFromTitleVerbose(db, workstream, title).id;
 }
 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}`);
 }
@@ -4765,14 +5112,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 = ? ORDER BY n.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`
   ).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')";
@@ -5194,6 +5553,148 @@ 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 setKickProcessExecutor(executor) {
+  const previous = currentExecutor2;
+  currentExecutor2 = executor;
+  return previous;
+}
+function resetKickProcessExecutor() {
+  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() {
@@ -5418,15 +5919,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;
   }
@@ -5436,12 +5946,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) {
@@ -5605,24 +6116,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(
@@ -5906,9 +6399,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) {
@@ -6127,6 +6617,8 @@ export {
   AgentExistsError,
   AgentNotFoundError,
   AgentNotInWorkstreamError,
+  AgentSpawnCliNotFoundError,
+  AgentSpawnStartupError,
   ArchiveAlreadyExistsError,
   ArchiveLabelInvalidError,
   ArchiveNotFoundError,
@@ -6139,8 +6631,7 @@ export {
   ImportBucketInvalidError,
   ImportEdgeRefMissingError,
   ImportFrontmatterParseError,
-  ImportLegacyLayoutError,
-  LegacyExportLayoutError,
+  NoForegroundProcessError,
   PANE_ID_RE,
   PaneNotFoundError,
   PruneOptionsInvalidError,
@@ -6174,6 +6665,7 @@ export {
   backendByName,
   capturePane,
   captureSnapshot,
+  checkCommandResolvable,
   claimTask,
   closeAgent,
   closeTask,
@@ -6198,11 +6690,13 @@ export {
   emitEvent,
   ensureWorkstream,
   ensureWorkstreamStateDir,
+  envVarNameForCli,
   exportArchive,
   exportSourceForWorkstream,
   exportSourcesForArchive,
   exportWorkstream,
   extractTail,
+  foregroundPgid,
   freeAgent,
   freeWorkspace,
   gcMaxAgeDays,
@@ -6223,6 +6717,7 @@ export {
   idFromTitleVerbose,
   importBucket,
   insertAgent,
+  isKickSignal,
   isStaleVersion,
   isTaskStatus,
   isValidAgentName,
@@ -6231,6 +6726,7 @@ export {
   isValidTaskId,
   isValidWorkstreamName,
   jjBackend,
+  kickAgent,
   killPane,
   killSession,
   latestSeq,
@@ -6263,10 +6759,13 @@ export {
   openDb,
   openTask,
   paneExists,
+  paneTTY,
   parseAgentNameFromTitle,
+  parsePsTtyOutput,
   pruneSnapshots,
   readAgent,
   reconcile,
+  recreateWorkspace,
   refreshAgentTitle,
   rejectTask,
   releaseTask,
@@ -6274,11 +6773,14 @@ export {
   removeFromArchive,
   renderToBucket,
   reparentTask,
+  resetCommandResolverForTests,
+  resetKickProcessExecutor,
   resetSleep,
   resetTmuxExecutor,
   resetWaitPollCount,
   resolveActorIdentity,
   resolveCliCommand,
+  resolveCliCommandWithSource,
   restoreSnapshot,
   searchArchives,
   searchTasks,
@@ -6286,6 +6788,8 @@ export {
   sendToAgent,
   sendToPane,
   sessionExists,
+  setCommandResolverForTests,
+  setKickProcessExecutor,
   setPaneTitle,
   setSleepForTests,
   setTaskStatus,