@mu-crew/mu 3.6.2 → 3.7.0

package/dist/cli.js

@@ -861,6 +861,7 @@ ${GOALS_VIEW_SQL}
 
 // src/ctl/path.ts
 import { createHash } from "crypto";
+import { rmSync } from "fs";
 import { dirname as dirname2, join as join2 } from "path";
 function sockPathUnder(dir, workstream, agent) {
   const readable = join2(dir, workstream, `${agent}.sock`);
@@ -873,6 +874,13 @@ function ctlSocketPath(workstream, agent, stateDir) {
   const base = stateDir ?? (dbPath ? dirname2(dbPath) : defaultStateDir());
   return sockPathUnder(join2(base, "sock"), workstream, agent);
 }
+function unlinkCtlSocket(db, name, workstream) {
+  if (db.memory) return;
+  try {
+    rmSync(ctlSocketPath(workstream, name, dirname2(db.name)), { force: true });
+  } catch {
+  }
+}
 function remoteCtlSocketPath(workstream, agent, uid) {
   return sockPathUnder(`/tmp/mu-${uid}`, workstream, agent);
 }
@@ -2698,12 +2706,6 @@ var init_tmux2 = __esm({
 function isWorkspaceStale(behind) {
   return behind !== null && behind !== void 0 && behind >= WORKSPACE_STALE_THRESHOLD;
 }
-function isLingeringScratchAgent(updatedAt, thresholdMs, now = Date.now()) {
-  if (thresholdMs <= 0) return false;
-  const updated = Date.parse(updatedAt);
-  if (!Number.isFinite(updated)) return false;
-  return now - updated >= thresholdMs;
-}
 var WORKSPACE_STALE_THRESHOLD;
 var init_staleness = __esm({
   "src/staleness.ts"() {
@@ -2935,7 +2937,7 @@ var init_types2 = __esm({
 
 // src/vcs/helpers.ts
 import { execFile } from "child_process";
-import { existsSync, rmSync } from "fs";
+import { existsSync, rmSync as rmSync2 } from "fs";
 import { mkdir } from "fs/promises";
 import { dirname as dirname3 } from "path";
 import { promisify } from "util";
@@ -2959,7 +2961,7 @@ async function ensureParent(path2) {
 }
 function rmDirSync(path2) {
   if (!existsSync(path2)) return false;
-  rmSync(path2, { recursive: true, force: true });
+  rmSync2(path2, { recursive: true, force: true });
   return true;
 }
 async function run(bin, args, cwd) {
@@ -3826,7 +3828,7 @@ var init_vcs2 = __esm({
 });
 
 // src/workspace/crud.ts
-import { existsSync as existsSync6, rmSync as rmSync2 } from "fs";
+import { existsSync as existsSync6, rmSync as rmSync3 } from "fs";
 import { homedir as homedir2 } from "os";
 import { resolve as resolve3 } from "path";
 async function createWorkspace(db, opts) {
@@ -3852,7 +3854,7 @@ async function createWorkspace(db, opts) {
     created = await backend.createWorkspace(createOpts);
   } catch (err) {
     try {
-      rmSync2(path2, { recursive: true, force: true });
+      rmSync3(path2, { recursive: true, force: true });
     } catch {
     }
     throw err;
@@ -4241,7 +4243,7 @@ var init_spawn_lock = __esm({
 
 // src/agents/spawn.ts
 import { execFile as execFile2 } from "child_process";
-import { mkdirSync as mkdirSync2, rmSync as rmSync3 } from "fs";
+import { mkdirSync as mkdirSync2, rmSync as rmSync4 } from "fs";
 import { basename, dirname as dirname4 } from "path";
 import { setTimeout as delay } from "timers/promises";
 import { promisify as promisify2 } from "util";
@@ -4310,7 +4312,7 @@ function defaultSpawnCtlMs() {
   if (Number.isNaN(parsed) || parsed < 0) return 3e4;
   return parsed;
 }
-async function awaitCtlHandshake(sock) {
+async function awaitCtlHandshake(sock, onMiss) {
   const budgetMs = defaultSpawnCtlMs();
   const deadline = Date.now() + budgetMs;
   for (; ; ) {
@@ -4318,6 +4320,7 @@ async function awaitCtlHandshake(sock) {
     const probe = await ctlProbe(sock, Math.max(1, Math.min(remaining, CTL_POLL_INTERVAL_MS * 4)));
     if (probe.kind === "ok") return "ok";
     const last = probeToSpawnCtl(probe.kind);
+    if (onMiss) await onMiss();
     const left = deadline - Date.now();
     if (left <= 0) return last;
     await delay(Math.min(CTL_POLL_INTERVAL_MS, left));
@@ -4347,7 +4350,7 @@ async function spawnAgent(db, opts) {
   const workspacePathStr = opts.workspace ? await prestageWorkspace(db, opts, cli) : void 0;
   const ctlSocket = ctlSocketPath(opts.workstream, opts.name, dirname4(db.name));
   mkdirSync2(dirname4(ctlSocket), { recursive: true, mode: 448 });
-  rmSync3(ctlSocket, { force: true });
+  rmSync4(ctlSocket, { force: true });
   const paneEnv = {
     MU_MANAGED_AGENT: "1",
     MU_AGENT_NAME: opts.name,
@@ -4357,6 +4360,8 @@ async function spawnAgent(db, opts) {
   const hasWorkspace = workspacePathStr !== void 0;
   let paneId;
   let agent;
+  const wantsCtl = opts.ctl !== false && speaksMuCtl(cli, command) && defaultSpawnCtlMs() !== 0;
+  let ctl;
   try {
     const created = await withSpawnLock(session, async () => {
       const pid = await createOrReusePane({
@@ -4377,7 +4382,23 @@ async function spawnAgent(db, opts) {
     agent = created.row;
     const startAgent = (await activeMux()).startAgentInPane;
     if (startAgent === void 0) {
-      await awaitSpawnLiveness(paneId, opts.name, command);
+      if (wantsCtl) {
+        const pid = paneId;
+        const check = defaultSpawnLivenessMs() !== 0;
+        const when = `during the ctl handshake (up to ${defaultSpawnCtlMs()}ms after spawn)`;
+        let lastScrollback;
+        const assertPaneAlive = async () => {
+          const mux = await activeMux();
+          const sb = await mux.capturePane(pid, { lines: 50 }).catch(() => void 0);
+          lastScrollback = sb ?? lastScrollback;
+          if (await mux.paneExists(pid)) return;
+          throw new AgentDiedOnSpawnError(opts.name, pid, lastScrollback, command, when);
+        };
+        ctl = await awaitCtlHandshake(ctlSocket, check ? assertPaneAlive : void 0);
+        if (check) await checkSpawnHealth(pid, opts.name, command, when);
+      } else {
+        await awaitSpawnLiveness(paneId, opts.name, command);
+      }
     } else {
       await startAgent({ paneId, name: opts.name, cli, command, commandSource });
     }
@@ -4386,14 +4407,13 @@ async function spawnAgent(db, opts) {
     if (hasWorkspace) attachOrphanCleanupHint(err, opts.name, opts.workstream);
     throw err;
   }
-  const ctl = opts.ctl === false || !speaksMuCtl(cli, command) || defaultSpawnCtlMs() === 0 ? "skipped" : await awaitCtlHandshake(ctlSocket);
+  ctl ??= wantsCtl ? await awaitCtlHandshake(ctlSocket) : "skipped";
   emitEvent(
     db,
     opts.workstream,
     "agent.spawn",
     `agent spawn ${opts.name} (cli=${cli}, role=${opts.role ?? "full-access"}, pane=${paneId})`
   );
-  await refreshAgentTitle(db, opts.name, opts.workstream);
   maybeWarnNonConventionalAgentName(opts.name);
   return { ...agent, ctl, ctlSocket };
 }
@@ -4490,15 +4510,18 @@ async function awaitSpawnLiveness(paneId, agentName, command) {
   const ms = defaultSpawnLivenessMs();
   if (ms === 0) return;
   await sleep(ms);
+  await checkSpawnHealth(paneId, agentName, command);
+}
+async function checkSpawnHealth(paneId, agentName, command, when) {
   const mux = await activeMux();
   const scrollback = await mux.capturePane(paneId, { lines: 50 }).catch(() => void 0);
   if (!await mux.paneExists(paneId)) {
-    throw new AgentDiedOnSpawnError(agentName, paneId, scrollback, command);
+    throw new AgentDiedOnSpawnError(agentName, paneId, scrollback, command, when);
   }
   if (scrollback !== void 0) {
     const matchedLine = detectSpawnStartupError(scrollback);
     if (matchedLine !== void 0) {
-      throw new AgentSpawnStartupError(agentName, paneId, matchedLine, scrollback);
+      throw new AgentSpawnStartupError(agentName, paneId, matchedLine, scrollback, when);
     }
   }
 }
@@ -4709,7 +4732,7 @@ var init_errors = __esm({
       }
     };
     AgentDiedOnSpawnError = class extends Error {
-      constructor(agentName, paneId, scrollback, command) {
+      constructor(agentName, paneId, scrollback, command, when = `within ${defaultSpawnLivenessMs()}ms of spawn`) {
         const tail = scrollback?.trim();
         const detail = tail ? `
 
@@ -4718,9 +4741,7 @@ ${tail}
 --- end scrollback ---` : "";
         const remote = /^\s*ssh\s/.test(command ?? "");
         const cause = remote ? 'The command is an ssh hop, so the likely causes are remote: the remote binary is missing, or its env (PATH, provider keys) is absent because ssh runs a non-interactive shell that skips ~/.zshrc / ~/.bashrc (wrap it: $SHELL -ilc "pi --approve"); or sshd refused the socket forward (ExitOnForwardFailure=yes kills the connection; check AllowStreamLocalForwarding).' : "Most common cause: the spawned CLI exited immediately (e.g. a wrapper CLI blocking on its instance lock; set MU_<UPPER_CLI>_COMMAND to a non-blocking variant to bypass).";
-        super(
-          `agent ${agentName} died within ${defaultSpawnLivenessMs()}ms of spawn (pane ${paneId}). ${cause}${detail}`
-        );
+        super(`agent ${agentName} died ${when} (pane ${paneId}). ${cause}${detail}`);
         this.agentName = agentName;
         this.paneId = paneId;
         this.scrollback = scrollback;
@@ -4779,9 +4800,9 @@ ${tail}
       }
     };
     AgentSpawnStartupError = class extends Error {
-      constructor(agentName, paneId, matchedLine, scrollback) {
+      constructor(agentName, paneId, matchedLine, scrollback, when = `within ${defaultSpawnLivenessMs()}ms of spawn`) {
         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.
+          `agent ${agentName} reported a startup error ${when} (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()}
 
@@ -4867,7 +4888,14 @@ ${scrollback.trim()}
       kind;
       name = "AgentCtlUnreachableError";
       errorNextSteps() {
+        const trust = this.kind === "missing" ? [
+          {
+            intent: "Just spawned? pi may sit at its project trust prompt: answer /trust in the pane, or respawn with --command 'pi --approve'",
+            command: `mu agent read ${this.agentName} -w ${this.workstream}`
+          }
+        ] : [];
         return [
+          ...trust,
           { intent: "Check whether the mu pi extension is linked", command: "mu doctor" },
           {
             intent: "Stop a runaway tool without the socket",
@@ -4950,7 +4978,7 @@ ${scrollback.trim()}
       }
     };
     AgentExtensionOutdatedError = class extends Error {
-      constructor(agentName, workstream, op, extVersion) {
+      constructor(agentName, workstream, op, extVersion, ops) {
         super(
           `agent ${agentName}'s mu pi extension (${extVersion ?? "version unknown"}) predates op ${op}: its pi loaded an older mu build; reload or respawn it`
         );
@@ -4958,18 +4986,21 @@ ${scrollback.trim()}
         this.workstream = workstream;
         this.op = op;
         this.extVersion = extVersion;
+        this.ops = ops;
       }
       agentName;
       workstream;
       op;
       extVersion;
+      ops;
       name = "AgentExtensionOutdatedError";
       errorNextSteps() {
         const w = `-w ${this.workstream}`;
+        const via = this.ops?.includes("command") ? "" : " --via mux";
         return [
           {
-            intent: "Reload pi's extensions in the pane (keeps the session and context)",
-            command: `mu agent send ${this.agentName} '/reload' --via mux ${w}`
+            intent: "Reload pi's extensions (keeps the session and context)",
+            command: `mu agent send ${this.agentName} '/reload'${via} ${w}`
           },
           {
             intent: "Or respawn the agent (loses its context)",
@@ -5058,7 +5089,7 @@ async function extensionOutdated(agent, sock, e) {
     if (hello.ok) extVersion = hello.extVersion;
   } catch {
   }
-  return new AgentExtensionOutdatedError(agent.name, agent.workstreamName, e.op, extVersion);
+  return new AgentExtensionOutdatedError(agent.name, agent.workstreamName, e.op, extVersion, e.ops);
 }
 async function ctlRequestFor(agent, sock, req) {
   try {
@@ -5107,7 +5138,11 @@ async function sendViaTransport(agent, text2, opts) {
     }
     throw new Error(`control socket refused the send: ${reply.error}`);
   }
-  return reply.state === void 0 ? { transport } : { transport, state: reply.state };
+  return {
+    transport,
+    ...reply.state !== void 0 ? { state: reply.state } : {},
+    ...reply.runs !== void 0 ? { runs: reply.runs } : {}
+  };
 }
 async function runSessionCommand(agent, sock, cmd, force) {
   const reply = await ctlRequestFor(agent, sock, {
@@ -5301,7 +5336,8 @@ async function readAgentStates(agents, opts = {}) {
         since: probe.status.since,
         alive: true,
         ctl: "ok",
-        pending: probe.status.pending
+        pending: probe.status.pending,
+        runs: probe.status.runs
       });
     } else {
       failed.set(agentKey(agent), probe?.kind === "missing" ? "missing" : "refused");
@@ -5857,6 +5893,15 @@ var init_id = __esm({
 });
 
 // src/tasks/errors.ts
+function stallWaitHint(owner, ws, runs) {
+  if (runs === void 0 || runs < 1) return [];
+  return [
+    {
+      intent: "Read the worker's last answer (its final text, at once)",
+      command: `mu agent wait ${owner} --after-runs ${runs - 1} --json -w ${ws}`
+    }
+  ];
+}
 var TaskNotFoundError, TaskIdInvalidError, TaskExistsError, TaskNotInWorkstreamError, TaskAlreadyOwnedError, ClaimerNotRegisteredError, TaskClaimStaleWorkspaceError, CycleError, ReaperDetectedDuringWaitError, StallDetectedDuringWaitError, CrossWorkstreamEdgeError, SubstateReasonRequiredError, TaskParkStateError, TaskInTriageError, TaskParkedError, InvalidSubstateError;
 var init_errors2 = __esm({
   "src/tasks/errors.ts"() {
@@ -6079,7 +6124,7 @@ var init_errors2 = __esm({
       }
     };
     StallDetectedDuringWaitError = class extends Error {
-      constructor(taskName, owner, workstream, ageSecs, ownerExpectsCtl = false) {
+      constructor(taskName, owner, workstream, ageSecs, ownerExpectsCtl = false, ownerRuns) {
         const ownerBit = owner !== null ? owner : "<unknown>";
         super(
           `task ${taskName} owned by ${ownerBit} has been needs_input for ${ageSecs}s; exiting per --on-stall exit. Read the pane to see which it is \u2014 finished without closing, waiting on an answer, or sitting at a prompt.`
@@ -6089,12 +6134,14 @@ var init_errors2 = __esm({
         this.workstream = workstream;
         this.ageSecs = ageSecs;
         this.ownerExpectsCtl = ownerExpectsCtl;
+        this.ownerRuns = ownerRuns;
       }
       taskName;
       owner;
       workstream;
       ageSecs;
       ownerExpectsCtl;
+      ownerRuns;
       name = "StallDetectedDuringWaitError";
       /**
        * Diagnose before acting. `mu agent read` comes FIRST because the
@@ -6109,6 +6156,7 @@ var init_errors2 = __esm({
         const ws = this.workstream;
         const ownerBit = this.owner !== null ? this.owner : "<owner>";
         return [
+          ...stallWaitHint(ownerBit, ws, this.ownerRuns),
           {
             intent: "Read the worker's pane to see what it is waiting on",
             command: `mu agent read ${ownerBit} -w ${ws} --lines 60`
@@ -6460,7 +6508,7 @@ var init_edges = __esm({
 
 // src/workstream.ts
 import { existsSync as existsSync9, readdirSync as readdirSync2, rmdirSync } from "fs";
-import { join as join8 } from "path";
+import { dirname as dirname6, join as join8 } from "path";
 async function listMuxSessions() {
   try {
     return await (await activeMux()).listSessions();
@@ -6614,6 +6662,7 @@ async function teardownWorkstream(db, opts) {
   const notesBefore = countNotes(db, opts.workstream);
   const edgesBefore = countEdges(db, opts.workstream);
   const workspacesBefore = listWorkspaces2(db, opts.workstream);
+  const agentNames = listAgentNames(db, opts.workstream);
   const mux = await activeMux();
   const muxAliveBefore = await mux.sessionExists(muxSession);
   if (muxAliveBefore) {
@@ -6651,6 +6700,14 @@ async function teardownWorkstream(db, opts) {
     } catch {
     }
   }
+  for (const name of agentNames) unlinkCtlSocket(db, name, opts.workstream);
+  if (!db.memory) {
+    const sockDir = join8(dirname6(db.name), "sock", opts.workstream);
+    try {
+      if (readdirSync2(sockDir).length === 0) rmdirSync(sockDir);
+    } catch {
+    }
+  }
   withOpContext(
     db,
     { intent: "workstream.teardown", group: "new" },
@@ -6667,6 +6724,14 @@ async function teardownWorkstream(db, opts) {
     failedWorkspaces
   };
 }
+function listAgentNames(db, workstream) {
+  const rows = db.prepare(
+    `SELECT a.name FROM agents a
+         JOIN workstreams ws ON ws.id = a.workstream_id
+        WHERE ws.name = ?`
+  ).all(workstream);
+  return rows.map((r) => r.name);
+}
 function countAgents(db, workstream) {
   const row2 = db.prepare(
     `SELECT COUNT(*) AS n FROM agents a
@@ -6707,6 +6772,7 @@ var WORKSTREAM_NAME_RE, RESERVED_WORKSTREAM_PREFIX, RESERVED_WORKSTREAM_NAMES, W
 var init_workstream = __esm({
   "src/workstream.ts"() {
     "use strict";
+    init_path();
     init_db();
     init_legacy_ops();
     init_mux2();
@@ -7360,12 +7426,15 @@ async function waitForTasks(db, input, opts) {
   const ctlBrokenSince = /* @__PURE__ */ new Map();
   const stuckLabel = /* @__PURE__ */ new Map();
   const ctlOwners = /* @__PURE__ */ new Set();
+  const ownerRuns = /* @__PURE__ */ new Map();
   const stuckAgeMs = async (status, owner, workstreamName) => {
     if (stuckAfterMs <= 0 || status !== "IN_PROGRESS" || owner === null || opts.readOwnerState === void 0)
       return null;
     const reading = await opts.readOwnerState({ name: owner, workstreamName });
     const ownerKey = `${workstreamName}/${owner}`;
     if (reading?.ctl !== void 0) ctlOwners.add(ownerKey);
+    if (reading?.runs !== void 0) ownerRuns.set(ownerKey, reading.runs);
+    else ownerRuns.delete(ownerKey);
     if (reading?.alive === true && (reading.ctl === "missing" || reading.ctl === "refused")) {
       const firstSeen = ctlBrokenSince.get(ownerKey) ?? Date.now();
       ctlBrokenSince.set(ownerKey, firstSeen);
@@ -7395,10 +7464,13 @@ async function waitForTasks(db, input, opts) {
         stuckWarned.add(key);
         const ageSecs = Math.round(ageMs2 / 1e3);
         const ownerBit = owner ?? "<none>";
+        const runs = ownerRuns.get(`${ref.workstreamName}/${ownerBit}`);
         const stateBit = stuckLabel.get(`${ref.workstreamName}/${ownerBit}`) ?? "needs_input";
+        const waitLine = stallWaitHint(ownerBit, ref.workstreamName, runs).map((s) => `  ${s.command}
+`).join("");
         currentStuckWarn(
           `\x1B[33mmu task wait: ${key} needs attention \u2014 owner=${ownerBit} has been in ${stateBit} for ${formatStallAge(ageMs2)}. It may have finished without closing, be waiting on an answer, or be sitting at a prompt.\x1B[0m
-  mu agent read ${ownerBit} -w ${ref.workstreamName} --lines 60
+` + waitLine + `  mu agent read ${ownerBit} -w ${ref.workstreamName} --lines 60
 `
         );
         emitEvent(
@@ -7414,7 +7486,8 @@ async function waitForTasks(db, input, opts) {
             owner,
             ref.workstreamName,
             ageSecs,
-            ctlOwners.has(`${ref.workstreamName}/${owner ?? ""}`)
+            ctlOwners.has(`${ref.workstreamName}/${owner ?? ""}`),
+            runs
           );
         }
       }
@@ -7930,8 +8003,7 @@ var init_wait2 = __esm({
 });
 
 // src/agents.ts
-import { rmSync as rmSync4 } from "fs";
-import { dirname as dirname6 } from "path";
+import { dirname as dirname7 } from "path";
 function idleThresholdMs() {
   const env = process.env.MU_IDLE_THRESHOLD_MS;
   if (env === void 0 || env === "") return DEFAULT_IDLE_THRESHOLD_MS;
@@ -8050,13 +8122,6 @@ function deleteAgent(db, name, workstream) {
   if (deleted) unlinkCtlSocket(db, name, workstream);
   return deleted;
 }
-function unlinkCtlSocket(db, name, workstream) {
-  if (db.memory) return;
-  try {
-    rmSync4(ctlSocketPath(workstream, name, dirname6(db.name)), { force: true });
-  } catch {
-  }
-}
 function deleteAgentRow(db, name, workstream) {
   return withOpContext(
     db,
@@ -8151,7 +8216,7 @@ async function listLiveAgents(db, opts) {
     ...opts.mode !== void 0 ? { mode: opts.mode } : {}
   });
   const baseAgents = listAgents(db, { workstream: opts.workstream });
-  const readings = await readAgentStates(baseAgents, { stateDir: dirname6(db.name) });
+  const readings = await readAgentStates(baseAgents, { stateDir: dirname7(db.name) });
   const now = Date.now();
   const agents = baseAgents.map((agent) => {
     const reading = readings.get(agentKey(agent)) ?? {
@@ -8708,7 +8773,7 @@ var init_apply = __esm({
 
 // src/rebuild.ts
 import { existsSync as existsSync10, mkdirSync as mkdirSync3, statSync } from "fs";
-import { dirname as dirname8 } from "path";
+import { dirname as dirname9 } from "path";
 function isProjectable(entity, intent) {
   if (isLegacyLogOnlyIntent(intent)) return false;
   if (LOG_ONLY_ENTITIES.has(entity)) return false;
@@ -8739,7 +8804,7 @@ function rebuildInto(source, opts) {
   if (existsSync10(targetPath) && opts.force !== true) {
     throw new RebuildTargetExistsError(targetPath);
   }
-  mkdirSync3(dirname8(targetPath), { recursive: true });
+  mkdirSync3(dirname9(targetPath), { recursive: true });
   const identity = source.prepare(
     "SELECT machine_id, hostname, created_at, last_wall, last_counter FROM machine_identity WHERE id = 1"
   ).get();
@@ -9321,13 +9386,13 @@ import {
   writeFileSync
 } from "fs";
 import { homedir as homedir4 } from "os";
-import { dirname as dirname9, join as join10, resolve as resolve5 } from "path";
+import { dirname as dirname10, join as join10, resolve as resolve5 } from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 function resolveHome(opts) {
   return opts?.home ?? process.env.MU_PI_HOME ?? homedir4();
 }
 function packageRoot() {
-  return resolve5(dirname9(fileURLToPath(import.meta.url)), "..");
+  return resolve5(dirname10(fileURLToPath(import.meta.url)), "..");
 }
 function extensionEntry() {
   return process.env.MU_EXTENSION_ENTRY ?? join10(packageRoot(), "dist", "extension", "mu-pi.js");
@@ -9363,7 +9428,7 @@ function linkPi(opts) {
     replacedCopy = !readFileSync(path2, "utf8").includes(MU_SHIM_MARKER);
   } catch {
   }
-  mkdirSync4(dirname9(path2), { recursive: true });
+  mkdirSync4(dirname10(path2), { recursive: true });
   writeFileSync(path2, opts?.copy === true ? readFileSync(entry, "utf8") : shim(entry));
   return { path: path2, replacedCopy };
 }
@@ -9374,7 +9439,7 @@ function linkSkill(opts) {
   const st = lstatOrUndefined(path2);
   if (st) {
     if (!st.isSymbolicLink()) throw new LinkConflictError(path2, "not-a-symlink");
-    const current = resolve5(dirname9(path2), readlinkSync(path2));
+    const current = resolve5(dirname10(path2), readlinkSync(path2));
     if (current === target) return { path: path2, target };
     if (existsSync12(current) && opts?.force !== true) {
       throw new LinkConflictError(path2, "foreign-symlink", current);
@@ -9382,7 +9447,7 @@ function linkSkill(opts) {
     previous = current;
     rmSync6(path2);
   }
-  mkdirSync4(dirname9(path2), { recursive: true });
+  mkdirSync4(dirname10(path2), { recursive: true });
   symlinkSync(target, path2, "dir");
   return previous === void 0 ? { path: path2, target } : { path: path2, target, previous };
 }
@@ -9416,7 +9481,7 @@ function inspectSkill(path2) {
   try {
     target = realpathSync(path2);
   } catch {
-    return { path: path2, state: "dangling", target: resolve5(dirname9(path2), readlinkSync(path2)) };
+    return { path: path2, state: "dangling", target: resolve5(dirname10(path2), readlinkSync(path2)) };
   }
   let skillMd;
   try {
@@ -9467,7 +9532,7 @@ var init_link = __esm({
 
 // src/doctor-summary.ts
 import { accessSync as accessSync2, constants as constants2, existsSync as existsSync13, readFileSync as readFileSync2, realpathSync as realpathSync2 } from "fs";
-import { delimiter as delimiter2, dirname as dirname10, join as join11, parse } from "path";
+import { delimiter as delimiter2, dirname as dirname11, join as join11, parse } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function loadDoctorSummary(db, snapshot2, agentStateSource = "murmur") {
   const checks = [];
@@ -9628,7 +9693,7 @@ function resolveExecutable(name) {
   return null;
 }
 function murmurVersion(executable) {
-  let dir = dirname10(executable);
+  let dir = dirname11(executable);
   const root = parse(dir).root;
   while (dir !== root) {
     const packagePath = join11(dir, "package.json");
@@ -9641,7 +9706,7 @@ function murmurVersion(executable) {
       } catch {
       }
     }
-    dir = dirname10(dir);
+    dir = dirname11(dir);
   }
   return null;
 }
@@ -9676,7 +9741,7 @@ function murmurDoctorCheck(agentStateSource, opts = {}) {
     return {
       name: "murmur",
       status: "warn",
-      detail: `murmur ${version} is older than 1.0.0; @murmur_pane_since missing, idle/stall timing unknown`
+      detail: opts.muExtOk === true ? `murmur ${version} is older than 1.0.0; idle/stall timing unknown for non-pi CLIs (pi agents use ctl)` : `murmur ${version} is older than 1.0.0; @murmur_pane_since missing, idle/stall timing unknown`
     };
   }
   return {
@@ -9730,7 +9795,7 @@ function skillDoctorCheck(opts) {
 }
 function installedMuVersion() {
   try {
-    const pkgPath = join11(dirname10(fileURLToPath2(import.meta.url)), "..", "package.json");
+    const pkgPath = join11(dirname11(fileURLToPath2(import.meta.url)), "..", "package.json");
     const pkg = JSON.parse(readFileSync2(pkgPath, "utf8"));
     const v = typeof pkg === "object" && pkg !== null ? pkg.version : null;
     return typeof v === "string" ? v : null;
@@ -9774,7 +9839,10 @@ async function ctlSocketsDoctorCheck(agents, opts = {}) {
         socket,
         probe: probe.kind,
         ...probe.kind === "ok" && probe.extVersion !== void 0 ? { extVersion: probe.extVersion } : {},
-        ...older || missingOps.length > 0 ? { outdated: true } : {},
+        ...older || missingOps.length > 0 ? {
+          outdated: true,
+          reloadVia: probe.kind === "ok" && probe.ops?.includes("command") ? "ctl" : "mux"
+        } : {},
         ...missingOps.length > 0 ? { missingOps } : {}
       };
     })
@@ -9860,11 +9928,14 @@ function remediationParagraph(check) {
       return [
         "mu talks to pi agents over a per-agent control socket served by",
         "the mu pi extension. `missing`: no socket (extension not loaded,",
-        "or the agent predates `mu link pi`). `refused`: socket present but",
-        "not answering. `version`: protocol mismatch; upgrade mu or pi.",
+        "the agent predates `mu link pi`, or a new pi still waits at its",
+        "project trust prompt: answer /trust in the pane, or spawn with",
+        "--command 'pi --approve'). `refused`: socket present but not",
+        "answering. `version`: protocol mismatch; upgrade mu or pi.",
         "Run `mu link pi`, then respawn the agent. `extension X older than",
-        "installed Y`: the agent's pi loaded an older mu build; type /reload",
-        "in its pane (`mu agent send <a> '/reload' --via mux`) or respawn it."
+        "installed Y` or `lacks ops`: the agent's pi loaded an older mu",
+        "build; reload it with `mu agent send <a> '/reload'` (add",
+        "`--via mux` when the extension lacks op command) or respawn it."
       ];
     case "agents":
       return [
@@ -18608,14 +18679,14 @@ var init_tui = __esm({
 // src/cli.ts
 init_agents();
 import { readFileSync as readFileSync4, realpathSync as realpathSync4 } from "fs";
-import { dirname as dirname16, join as join14 } from "path";
+import { dirname as dirname17, join as join14 } from "path";
 import { fileURLToPath as fileURLToPath3, pathToFileURL as pathToFileURL2 } from "url";
 import { Command, InvalidArgumentError } from "commander";
 
 // src/cli/agents.ts
 init_agent_state();
 init_agents();
-import { dirname as dirname12 } from "path";
+import { dirname as dirname13 } from "path";
 init_client();
 init_mux2();
 init_output();
@@ -18715,7 +18786,7 @@ function formatStaleWorkspaceWarning(staleness) {
 
 // src/cli/agents-remote.ts
 init_agents();
-import { dirname as dirname7 } from "path";
+import { dirname as dirname8 } from "path";
 init_path();
 init_output();
 init_workstream();
@@ -18731,7 +18802,7 @@ function buildRemoteEnv(db, agent, workstream, remoteSock) {
   if (!isValidWorkstreamName(workstream)) {
     throw new UsageError(`invalid workstream name ${JSON.stringify(workstream)}`);
   }
-  const localSock = ctlSocketPath(workstream, agent, dirname7(db.name));
+  const localSock = ctlSocketPath(workstream, agent, dirname8(db.name));
   const remote = remoteSock ?? remoteCtlSocketPath(workstream, agent, process.getuid?.() ?? 0);
   if (!remote.startsWith("/") || !SAFE_WORD.test(remote)) {
     throw new UsageError(
@@ -19210,12 +19281,13 @@ init_tasks();
 init_agent_state();
 init_errors();
 init_agents();
-import { dirname as dirname11 } from "path";
+import { dirname as dirname12 } from "path";
 init_db();
 init_glyphs();
 init_output();
 init_reconcile();
 init_state();
+init_errors2();
 init_tasks();
 init_vcs2();
 init_workspace();
@@ -19446,7 +19518,7 @@ async function cmdTaskWait(db, ids, opts) {
       const agent = getAgent(db, owner, ref.workstreamName);
       return agent === void 0 ? [] : [agent];
     });
-    ownerReadings = await readAgentStates(owners, { stateDir: dirname11(db.name) });
+    ownerReadings = await readAgentStates(owners, { stateDir: dirname12(db.name) });
     if (!reaperExitEnabled) return;
     for (const ref of refs) {
       const key = qualifiedId(ref);
@@ -19498,6 +19570,10 @@ async function cmdTaskWait(db, ids, opts) {
   }
   for (const t of unmetRefs) {
     if (t.stuck && t.owner !== null) {
+      const runs = ownerReadings.get(
+        agentKey({ name: t.owner, workstreamName: t.workstreamName })
+      )?.runs;
+      nextSteps3.push(...stallWaitHint(t.owner, t.workstreamName, runs));
       nextSteps3.push({
         intent: `Read ${t.owner}'s pane \u2014 ${qualifiedId(t)} is IN_PROGRESS but its owner needs attention`,
         command: `mu agent read ${t.owner} -w ${t.workstreamName} --lines 60`
@@ -20305,8 +20381,6 @@ async function cmdSend(db, rawName, text2, opts = {}) {
   });
   let undelivered;
   const agentRow = getAgent(db, name, ws);
-  const plainCtl = agentRow !== void 0 && !opts.fresh && !opts.steer && parseSessionCommand(text2) === void 0 && (via ?? chooseTransport(agentRow, agentCtlSocket(db, agentRow))) === "ctl";
-  const before = plainCtl && agentRow !== void 0 ? await ctlProbe(agentCtlSocket(db, agentRow)) : void 0;
   const sent = await sendToAgent(db, name, text2, {
     workstream: ws,
     ...opts.steer ? { mode: "steer" } : {},
@@ -20318,11 +20392,15 @@ async function cmdSend(db, rawName, text2, opts = {}) {
     }
   });
   const nextSteps3 = [
-    { intent: "Read response", command: `mu agent read ${name} -n 50 -w ${ws}` },
+    sent.transport === "ctl" && sent.runs !== void 0 ? {
+      intent: "Wait for the response (returns its final text)",
+      command: `mu agent wait ${name} --after-runs ${sent.runs} --json -w ${ws}`
+    } : { intent: "Read response", command: `mu agent read ${name} -n 50 -w ${ws}` },
     { intent: "Watch live events", command: `mu log -w ${ws} --tail` }
   ];
-  if (agentRow !== void 0 && before?.kind === "ok") {
-    nextSteps3.push(...plainSendHints(agentRow, before.status));
+  const plainCtl = sent.transport === "ctl" && !opts.fresh && !opts.steer && sent.command === void 0;
+  if (agentRow !== void 0 && plainCtl && sent.state !== void 0 && sent.runs !== void 0) {
+    nextSteps3.push(...plainSendHints(agentRow, { state: sent.state, runs: sent.runs }));
   }
   if (stalenessCheck.warned && stalenessCheck.nextStep !== null) {
     nextSteps3.push(stalenessCheck.nextStep);
@@ -20341,6 +20419,7 @@ async function cmdSend(db, rawName, text2, opts = {}) {
       fresh: opts.fresh === true,
       ...sent.command !== void 0 ? { command: sent.command } : {},
       ...sent.state !== void 0 ? { state: sent.state } : {},
+      ...sent.runs !== void 0 ? { runs: sent.runs } : {},
       delivered: undelivered === void 0,
       ...undelivered !== void 0 ? { undelivered: { reason: undelivered.reason, message: undelivered.message } } : {},
       staleness: stalenessCheck.staleness,
@@ -20351,7 +20430,7 @@ async function cmdSend(db, rawName, text2, opts = {}) {
   if (undelivered !== void 0) {
     console.error(pc.yellow(`warning: ${undelivered.message}`));
   } else {
-    const how = sent.transport === "mux" ? "via mux paste" : opts.fresh ? "via ctl, fresh session" : sent.command !== void 0 ? `via ctl, pi ran /${sent.command}` : `via ctl, pi ${sent.state ?? "?"}`;
+    const how = sent.transport === "mux" ? "via mux paste" : opts.fresh ? "via ctl, fresh session" : sent.command !== void 0 ? `via ctl, pi ran /${sent.command}` : sent.runs !== void 0 ? `via ctl, pi was ${sent.state ?? "?"}, runs ${sent.runs}` : `via ctl, pi ${sent.state ?? "?"}`;
     console.log(pc.dim(`sent ${text2.length} bytes to ${name} (${how})`));
   }
   printNextSteps(nextSteps3);
@@ -20414,7 +20493,7 @@ async function cmdAgentShow(db, rawName, opts) {
   } catch {
     scrollback = "";
   }
-  const reading = (await readAgentStates([agent], { stateDir: dirname12(db.name) })).get(
+  const reading = (await readAgentStates([agent], { stateDir: dirname13(db.name) })).get(
     agentKey(agent)
   );
   const displayed = {
@@ -20449,7 +20528,7 @@ async function cmdAgentShow(db, rawName, opts) {
 }
 async function cmdMe(db, opts = {}) {
   const self = resolveSelf(db);
-  const reading = (await readAgentStates([self], { stateDir: dirname12(db.name) })).get(
+  const reading = (await readAgentStates([self], { stateDir: dirname13(db.name) })).get(
     agentKey(self)
   );
   const displayed = {
@@ -20642,7 +20721,7 @@ async function cmdAbort(db, rawName, opts = {}) {
       intent: "Steer it with the next instruction",
       command: `mu agent send ${name} '...' -w ${ws}`
     },
-    { intent: "Read the pane", command: `mu agent read ${name} -n 30 -w ${ws}` }
+    ...result.after === "idle" ? [] : [{ intent: "Read the pane", command: `mu agent read ${name} -n 30 -w ${ws}` }]
   ];
   if (opts.json) {
     emitJson({ ...result, nextSteps: nextSteps3 });
@@ -20667,12 +20746,22 @@ async function cmdAgentWait(db, rawNames, opts) {
       return { name, workstreamName };
     })
   );
+  if (opts.afterRuns !== void 0) {
+    for (const ref of refs) {
+      const agent = getAgent(db, ref.name, ref.workstreamName);
+      if (agent !== void 0 && !expectsCtl(agent, agentCtlSocket(db, agent))) {
+        throw new UsageError(
+          `--after-runs needs a pi agent (control socket); ${ref.workstreamName}/${ref.name} runs ${agent.cli}. Drop --after-runs to wait on its pane state.`
+        );
+      }
+    }
+  }
   const readStatuses = async (pending2) => {
     const agents = pending2.flatMap((ref) => {
       const agent = getAgent(db, ref.name, ref.workstreamName);
       return agent === void 0 ? [] : [agent];
     });
-    const readings = await readAgentStates(agents, { stateDir: dirname12(db.name) });
+    const readings = await readAgentStates(agents, { stateDir: dirname13(db.name) });
     const snapshots = /* @__PURE__ */ new Map();
     for (const ref of pending2) {
       const agent = getAgent(db, ref.name, ref.workstreamName);
@@ -20689,9 +20778,15 @@ async function cmdAgentWait(db, rawNames, opts) {
     if (agent === void 0) return void 0;
     const sock = agentCtlSocket(db, agent);
     if (!expectsCtl(agent, sock)) return void 0;
-    const probe = await ctlProbe(sock);
-    if (probe.kind !== "ok") return void 0;
-    const settled = ctlRequest(sock, { op: "wait", afterRuns: probe.status.runs }, { signal }).then(
+    let initial = { status: "busy" };
+    let afterRuns = opts.afterRuns;
+    if (afterRuns === void 0) {
+      const probe = await ctlProbe(sock);
+      if (probe.kind !== "ok") return void 0;
+      afterRuns = probe.status.runs;
+      initial = { status: ctlRuntimeState(probe.status.state) };
+    }
+    const settled = ctlRequest(sock, { op: "wait", afterRuns }, { signal }).then(
       (reply) => reply.ok && reply.state !== void 0 ? {
         status: ctlRuntimeState(reply.state),
         ...reply.lastText !== void 0 ? { lastText: reply.lastText } : {},
@@ -20706,7 +20801,7 @@ async function cmdAgentWait(db, rawNames, opts) {
         return again.kind === "ok" ? { status: "unknown", unknownReason: "ctl wait interrupted" } : { status: null };
       }
     );
-    return { initial: { status: ctlRuntimeState(probe.status.state) }, settled };
+    return { initial, settled };
   };
   const timeoutMs = (opts.timeout ?? 600) * 1e3;
   const result = await waitForAgents(db, refs, {
@@ -20729,6 +20824,12 @@ async function cmdAgentWait(db, rawNames, opts) {
   const fired = result.agents.filter((a) => a.fired);
   const firing = wantFirstShape && fired.length > 0 ? fired[0] : null;
   const qualified = (a) => `${a.workstreamName}/${a.name}`;
+  const readHint = firing && (!firing.lastText || firing.lastError !== void 0) ? [
+    {
+      intent: "Read the finished agent",
+      command: `mu agent read ${firing.name} -w ${firing.workstreamName}`
+    }
+  ] : [];
   if (opts.json) {
     emitJson({
       agents: result.agents.map((a) => ({
@@ -20738,12 +20839,7 @@ async function cmdAgentWait(db, rawNames, opts) {
       timedOut: result.timedOut,
       ...firing ? { firing: { workstream: firing.workstreamName, name: firing.name } } : {},
       ...dead.length > 0 ? { dead: dead.map(qualified) } : {},
-      nextSteps: firing ? [
-        {
-          intent: "Read the finished agent",
-          command: `mu agent read ${firing.name} -w ${firing.workstreamName}`
-        }
-      ] : []
+      nextSteps: readHint
     });
   } else if (result.timedOut) {
     console.log(
@@ -20755,12 +20851,7 @@ async function cmdAgentWait(db, rawNames, opts) {
     console.log(pc.red(`Agent pane(s) died: ${dead.map(qualified).join(", ")}`));
   } else if (firing) {
     console.log(`${pc.bold(qualified(firing))} finished`);
-    printNextSteps([
-      {
-        intent: "Read the finished agent",
-        command: `mu agent read ${firing.name} -w ${firing.workstreamName}`
-      }
-    ]);
+    printNextSteps(readHint);
   } else {
     console.log(`All ${result.agents.length} agent(s) finished`);
   }
@@ -20855,7 +20946,11 @@ function wireAgentCommands(program) {
     "--timeout <seconds>",
     "max seconds to wait (0 = forever, default 600)",
     parseNonNegativeInt
-  ).option("--lines <n>", "scrollback lines to scan per poll (default 100)", parseLines).option(...WORKSTREAM_OPT).option(...JSON_OPT).action(function(names) {
+  ).option(
+    "--after-runs <n>",
+    "pi agents only: fire on the first run settled past N (the `runs` that `mu agent send --json` printed), even one that settled before this wait started",
+    parseNonNegativeInt
+  ).option(...WORKSTREAM_OPT).option(...JSON_OPT).action(function(names) {
     const opts = this.optsWithGlobals();
     return handle(
       (db) => cmdAgentWait(db, names, {
@@ -20905,7 +21000,7 @@ function wireSelfCommands(program) {
 
 // src/cli/db.ts
 import { existsSync as existsSync16, mkdirSync as mkdirSync6, statSync as statSync5 } from "fs";
-import { dirname as dirname13, resolve as resolve7 } from "path";
+import { dirname as dirname14, resolve as resolve7 } from "path";
 
 // src/compact.ts
 init_legacy_ops();
@@ -21997,7 +22092,7 @@ function cmdDbBackup(db, file, opts = {}) {
   if (existsSync16(target)) {
     throw new UsageError(`${target} already exists: mu db backup never overwrites`);
   }
-  mkdirSync6(dirname13(target), { recursive: true });
+  mkdirSync6(dirname14(target), { recursive: true });
   db.prepare("VACUUM INTO ?").run(target);
   const nextSteps3 = [
     {
@@ -22141,7 +22236,7 @@ function wireDbCommands(program) {
 
 // src/cli/doctor.ts
 init_agents();
-import { dirname as dirname14 } from "path";
+import { dirname as dirname15 } from "path";
 init_db();
 init_doctor_summary();
 
@@ -22307,7 +22402,7 @@ async function cmdDoctor(db, opts = {}) {
   printCheck("mu skill", skillDoctorCheck());
   printCheck(
     "ctl",
-    (await ctlSocketsDoctorCheck(listAgents(db), { stateDir: dirname14(db.name) })).check
+    (await ctlSocketsDoctorCheck(listAgents(db), { stateDir: dirname15(db.name) })).check
   );
   console.log(pc.bold("\ndb"));
   console.log(`  path             : ${pc.dim(defaultDbPath())}`);
@@ -22505,7 +22600,7 @@ function opsSizeHint(db) {
 async function cmdDoctorJson(db, opts = {}) {
   const health = await muxHealth();
   const muExt = ctlExtensionDoctorCheck();
-  const ctlSockets = await ctlSocketsDoctorCheck(listAgents(db), { stateDir: dirname14(db.name) });
+  const ctlSockets = await ctlSocketsDoctorCheck(listAgents(db), { stateDir: dirname15(db.name) });
   const env = {
     // `mux` is the backend-agnostic key. `tmux` is kept as an alias for
     // back-compat with scripts that grew around the pre-MuxBackend
@@ -23209,7 +23304,6 @@ function wireSqlCommand(program) {
 }
 
 // src/cli/state.ts
-init_agents();
 init_db();
 init_glyphs();
 init_output();
@@ -23224,7 +23318,7 @@ import path from "path";
 // src/project-root.ts
 import { execFile as execFile3 } from "child_process";
 import { realpath } from "fs/promises";
-import { dirname as dirname15, resolve as resolve8 } from "path";
+import { dirname as dirname16, resolve as resolve8 } from "path";
 import { promisify as promisify3 } from "util";
 var exec2 = promisify3(execFile3);
 async function run2(bin, args, cwd) {
@@ -23246,7 +23340,7 @@ async function gitProjectRoot(workspacePath2) {
       workspacePath2
     );
     if (commonDir.length === 0) return null;
-    return realpathOrResolve(dirname15(commonDir));
+    return realpathOrResolve(dirname16(commonDir));
   } catch {
     return null;
   }
@@ -23266,7 +23360,7 @@ async function workspaceProjectRoot(workspacePath2, backend) {
   if (backend === "sl") return slProjectRoot(workspacePath2);
   const gitRoot = await gitProjectRoot(workspacePath2);
   if (gitRoot !== null) return gitRoot;
-  return realpathOrResolve(dirname15(workspacePath2));
+  return realpathOrResolve(dirname16(workspacePath2));
 }
 
 // src/cli/tui-launch-focus.ts
@@ -23455,6 +23549,13 @@ async function cmdState(db, opts) {
   renderFullMode(perWs);
 }
 var BIG_WORKSTREAM_TASKS = 300;
+function scratchIdleNudge(workstreamName, agents) {
+  if (!isScratchWorkstream(workstreamName)) return null;
+  const lingering = agents.filter((a) => a.idle === true);
+  if (lingering.length === 0) return null;
+  const names = lingering.map((a) => a.name).join(", ");
+  return `\u26A0 ${lingering.length} idle scratch agent(s): ${names}. Close when done: mu agent close ${lingering[0]?.name ?? "<name>"} -w scratch`;
+}
 function renderFullMode(perWs) {
   perWs.forEach((d, i) => {
     if (i > 0) console.log("");
@@ -23475,18 +23576,8 @@ function renderFullCard(d) {
       );
     }
   }
-  if (isScratchWorkstream(workstreamName)) {
-    const threshold = idleThresholdMs();
-    const lingering = view.agents.filter((a) => isLingeringScratchAgent(a.updatedAt, threshold));
-    if (lingering.length > 0) {
-      const names = lingering.map((a) => a.name).join(", ");
-      console.log(
-        pc.yellow(
-          `\u26A0 ${lingering.length} idle scratch agent(s): ${names}. Close when done: mu agent close ${lingering[0]?.name ?? "<name>"} -w scratch`
-        )
-      );
-    }
-  }
+  const nudge = scratchIdleNudge(workstreamName, view.agents);
+  if (nudge !== null) console.log(pc.yellow(nudge));
   const total = d.taskCount;
   const open = ready.length + inProgress.length + blocked.length + d.triage.length;
   if (total >= BIG_WORKSTREAM_TASKS && open * 10 < total) {
@@ -24759,7 +24850,7 @@ async function cmdBareTui(db, program, requestedWorkstreams) {
 }
 function readPackageVersion() {
   try {
-    const here = dirname16(fileURLToPath3(import.meta.url));
+    const here = dirname17(fileURLToPath3(import.meta.url));
     const pkgPath = join14(here, "..", "package.json");
     const raw = readFileSync4(pkgPath, "utf8");
     const parsed = JSON.parse(raw);