@jaggerxtrm/specialists 3.4.0 → 3.4.1

package/dist/index.js

@@ -17442,9 +17442,6 @@ function getFriendlyMessage(issue2) {
   if (issue2.code === "invalid_literal") {
     return `Invalid value at "${path}": expected "${issue2.expected}"`;
   }
-  if (issue2.code === "missing_key") {
-    return `Missing required field: "${formatPath(issue2.path)}"`;
-  }
   return issue2.message;
 }
 async function validateSpecialist(yamlContent) {
@@ -17505,7 +17502,7 @@ ${result.warnings.map((w) => `  ⚠ ${w}`).join(`
   const raw = $parse(yamlContent);
   return SpecialistSchema.parseAsync(raw);
 }
-var KebabCase, Semver, MetadataSchema, ExecutionSchema, PromptSchema2, ScriptEntrySchema, SkillsSchema, CapabilitiesSchema, CommunicationSchema, ValidationSchema, SpecialistSchema;
+var KebabCase, Semver, MetadataSchema, ExecutionSchema, PromptSchema2, ScriptEntrySchema, SkillsSchema, CapabilitiesSchema, CommunicationSchema, ValidationSchema, StallDetectionSchema, SpecialistSchema;
 var init_schema = __esm(() => {
   init_zod();
   init_dist();
@@ -17527,6 +17524,8 @@ var init_schema = __esm(() => {
     fallback_model: stringType().optional(),
     timeout_ms: numberType().default(120000),
     stall_timeout_ms: numberType().optional(),
+    max_retries: numberType().int().min(0).default(0),
+    interactive: booleanType().default(false),
     response_format: enumType(["text", "json", "markdown"]).default("text"),
     permission_required: enumType(["READ_ONLY", "LOW", "MEDIUM", "HIGH"]).default("READ_ONLY"),
     thinking_level: enumType(["off", "minimal", "low", "medium", "high", "xhigh"]).optional(),
@@ -17564,9 +17563,14 @@ var init_schema = __esm(() => {
   }).optional();
   ValidationSchema = objectType({
     files_to_watch: arrayType(stringType()).optional(),
-    references: arrayType(unknownType()).optional(),
     stale_threshold_days: numberType().optional()
   }).optional();
+  StallDetectionSchema = objectType({
+    running_silence_warn_ms: numberType().optional(),
+    running_silence_error_ms: numberType().optional(),
+    waiting_stale_ms: numberType().optional(),
+    tool_duration_warn_ms: numberType().optional()
+  }).optional();
   SpecialistSchema = objectType({
     specialist: objectType({
       metadata: MetadataSchema,
@@ -17576,8 +17580,10 @@ var init_schema = __esm(() => {
       capabilities: CapabilitiesSchema,
       communication: CommunicationSchema,
       validation: ValidationSchema,
+      stall_detection: StallDetectionSchema,
       output_file: stringType().optional(),
       beads_integration: enumType(["auto", "always", "never"]).default("auto"),
+      beads_write_notes: booleanType().default(true),
       heartbeat: unknownType().optional()
     })
   });
@@ -17614,8 +17620,13 @@ class SpecialistLoader {
   }
   getScanDirs() {
     const dirs = [
+      { path: join(this.projectDir, ".specialists", "user"), scope: "user" },
       { path: join(this.projectDir, ".specialists", "user", "specialists"), scope: "user" },
-      { path: join(this.projectDir, ".specialists", "default", "specialists"), scope: "default" }
+      { path: join(this.projectDir, ".specialists", "default"), scope: "default" },
+      { path: join(this.projectDir, ".specialists", "default", "specialists"), scope: "default" },
+      { path: join(this.projectDir, "specialists"), scope: "default" },
+      { path: join(this.projectDir, ".claude", "specialists"), scope: "default" },
+      { path: join(this.projectDir, ".agent-forge", "specialists"), scope: "default" }
     ];
     return dirs.filter((d) => existsSync(d.path));
   }
@@ -17645,7 +17656,8 @@ class SpecialistLoader {
             filePath,
             updated,
             filestoWatch: spec.specialist.validation?.files_to_watch,
-            staleThresholdDays: spec.specialist.validation?.stale_threshold_days
+            staleThresholdDays: spec.specialist.validation?.stale_threshold_days,
+            stallDetection: spec.specialist.stall_detection ?? undefined
           });
         } catch (e) {
           const reason = e instanceof Error ? e.message : String(e);
@@ -17759,7 +17771,11 @@ class PiAgentSession {
   _agentEndReceived = false;
   _killed = false;
   _lineBuffer = "";
-  _pendingCommand;
+  _pendingRequests = new Map;
+  _nextRequestId = 1;
+  _stderrBuffer = "";
+  _stallTimer;
+  _stallError;
   meta;
   constructor(options, meta) {
     this.options = options;
@@ -17809,7 +17825,7 @@ class PiAgentSession {
       args.push("--append-system-prompt", this.options.systemPrompt);
     }
     this.proc = spawn("pi", args, {
-      stdio: ["pipe", "pipe", "inherit"],
+      stdio: ["pipe", "pipe", "pipe"],
       cwd: this.options.cwd
     });
     const donePromise = new Promise((resolve, reject) => {
@@ -17818,6 +17834,9 @@ class PiAgentSession {
     });
     donePromise.catch(() => {});
     this._donePromise = donePromise;
+    this.proc.stderr?.on("data", (chunk) => {
+      this._stderrBuffer += chunk.toString();
+    });
     this.proc.stdout?.on("data", (chunk) => {
       this._lineBuffer += chunk.toString();
       const lines = this._lineBuffer.split(`
@@ -17835,6 +17854,7 @@ class PiAgentSession {
       }
     });
     this.proc.on("close", (code) => {
+      this._clearStallTimer();
       if (this._agentEndReceived || this._killed) {
         this._doneResolve?.();
       } else if (code === 0 || code === null) {
@@ -17844,6 +17864,25 @@ class PiAgentSession {
       }
     });
   }
+  _clearStallTimer() {
+    if (this._stallTimer) {
+      clearTimeout(this._stallTimer);
+      this._stallTimer = undefined;
+    }
+  }
+  _markActivity() {
+    const timeoutMs = this.options.stallTimeoutMs;
+    if (!timeoutMs || timeoutMs <= 0 || this._killed || this._agentEndReceived)
+      return;
+    this._clearStallTimer();
+    this._stallTimer = setTimeout(() => {
+      if (this._killed || this._agentEndReceived)
+        return;
+      const err = new StallTimeoutError(timeoutMs);
+      this._stallError = err;
+      this.kill(err);
+    }, timeoutMs);
+  }
   _handleEvent(line) {
     let event;
     try {
@@ -17851,11 +17890,18 @@ class PiAgentSession {
     } catch {
       return;
     }
+    this._markActivity();
     const { type } = event;
     if (type === "response") {
-      const handler = this._pendingCommand;
-      this._pendingCommand = undefined;
-      handler?.(event);
+      const id = event.id;
+      if (id !== undefined) {
+        const entry = this._pendingRequests.get(id);
+        if (entry) {
+          clearTimeout(entry.timer);
+          this._pendingRequests.delete(id);
+          entry.resolve(event);
+        }
+      }
       return;
     }
     if (type === "message_start") {
@@ -17895,11 +17941,13 @@ class PiAgentSession {
         this._lastOutput = last.content.filter((c) => c.type === "text").map((c) => c.text).join("");
       }
       this._agentEndReceived = true;
+      this._clearStallTimer();
       this.options.onEvent?.("agent_end");
       this._doneResolve?.();
       return;
     }
     if (type === "tool_execution_start") {
+      this.options.onToolStart?.(event.toolName ?? event.name ?? "tool", event.args, event.toolCallId);
       this.options.onEvent?.("tool_execution_start");
       return;
     }
@@ -17908,10 +17956,18 @@ class PiAgentSession {
       return;
     }
     if (type === "tool_execution_end") {
-      this.options.onToolEnd?.(event.toolName ?? event.name ?? "tool");
+      this.options.onToolEnd?.(event.toolName ?? event.name ?? "tool", event.isError ?? false, event.toolCallId);
       this.options.onEvent?.("tool_execution_end");
       return;
     }
+    if (type === "auto_compaction_start" || type === "auto_compaction_end") {
+      this.options.onEvent?.("auto_compaction");
+      return;
+    }
+    if (type === "auto_retry_start" || type === "auto_retry_end") {
+      this.options.onEvent?.("auto_retry");
+      return;
+    }
     if (type === "message_update") {
       const ae = event.assistantMessageEvent;
       if (!ae)
@@ -17943,26 +17999,38 @@ class PiAgentSession {
       }
     }
   }
-  sendCommand(cmd) {
+  sendCommand(cmd, timeoutMs = 1e4) {
     return new Promise((resolve, reject) => {
       if (!this.proc?.stdin) {
         reject(new Error("No stdin available"));
         return;
       }
-      this._pendingCommand = resolve;
-      this.proc.stdin.write(JSON.stringify(cmd) + `
+      const id = this._nextRequestId++;
+      const timer = setTimeout(() => {
+        this._pendingRequests.delete(id);
+        reject(new Error(`RPC timeout: no response for command id=${id} after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this._pendingRequests.set(id, { resolve, reject, timer });
+      this.proc.stdin.write(JSON.stringify({ ...cmd, id }) + `
 `, (err) => {
         if (err) {
-          this._pendingCommand = undefined;
+          const entry = this._pendingRequests.get(id);
+          if (entry) {
+            clearTimeout(entry.timer);
+            this._pendingRequests.delete(id);
+          }
           reject(err);
         }
       });
     });
   }
   async prompt(task) {
-    const msg = JSON.stringify({ type: "prompt", message: task }) + `
-`;
-    this.proc?.stdin?.write(msg);
+    this._stallError = undefined;
+    this._markActivity();
+    const response = await this.sendCommand({ type: "prompt", message: task });
+    if (response?.success === false) {
+      throw new Error(`Prompt rejected by pi: ${response.error ?? "already streaming"}`);
+    }
   }
   async waitForDone(timeout) {
     const donePromise = this._donePromise ?? Promise.resolve();
@@ -18001,6 +18069,7 @@ class PiAgentSession {
   async close() {
     if (this._killed)
       return;
+    this._clearStallTimer();
     this.proc?.stdin?.end();
     if (this.proc) {
       await new Promise((resolve) => {
@@ -18014,23 +18083,41 @@ class PiAgentSession {
       });
     }
   }
-  kill() {
+  kill(reason) {
     if (this._killed)
       return;
     this._killed = true;
+    this._clearStallTimer();
+    if (this.proc?.stdin?.writable) {
+      try {
+        this.proc.stdin.write(JSON.stringify({ type: "abort" }) + `
+`);
+      } catch {}
+    }
+    const killError = reason ?? this._stallError ?? new SessionKilledError;
+    for (const [, entry] of this._pendingRequests) {
+      clearTimeout(entry.timer);
+      entry.reject(killError);
+    }
+    this._pendingRequests.clear();
     this.proc?.kill();
     this.proc = undefined;
-    this._doneReject?.(new SessionKilledError);
+    this._doneReject?.(killError);
+  }
+  getStderr() {
+    return this._stderrBuffer;
   }
   async steer(message) {
     if (this._killed || !this.proc?.stdin) {
       throw new Error("Session is not active");
     }
-    const cmd = JSON.stringify({ type: "steer", message }) + `
-`;
-    await new Promise((resolve, reject) => {
-      this.proc.stdin.write(cmd, (err) => err ? reject(err) : resolve());
-    });
+    const response = await this.sendCommand({ type: "steer", message });
+    if (response?.success === false) {
+      throw new Error(`Steer rejected by pi: ${response.error ?? "steer failed"}`);
+    }
+  }
+  followUp(_task) {
+    throw new Error("followUp() is not yet implemented. Use resume() to send a next-turn prompt to a waiting session.");
   }
   async resume(task, timeout) {
     if (this._killed || !this.proc?.stdin) {
@@ -18047,7 +18134,7 @@ class PiAgentSession {
     await this.waitForDone(timeout);
   }
 }
-var SessionKilledError;
+var SessionKilledError, StallTimeoutError;
 var init_session = __esm(() => {
   init_backendMap();
   SessionKilledError = class SessionKilledError extends Error {
@@ -18056,6 +18143,74 @@ var init_session = __esm(() => {
       this.name = "SessionKilledError";
     }
   };
+  StallTimeoutError = class StallTimeoutError extends Error {
+    constructor(timeoutMs) {
+      super(`Session stalled: no activity for ${timeoutMs}ms`);
+      this.name = "StallTimeoutError";
+    }
+  };
+});
+
+// src/utils/circuitBreaker.ts
+function isTransientError(error2) {
+  if (!error2)
+    return false;
+  const status = error2.status ?? error2.statusCode;
+  if (typeof status === "number" && status >= 500 && status < 600) {
+    return true;
+  }
+  const message = error2 instanceof Error ? error2.message : typeof error2 === "string" ? error2 : JSON.stringify(error2);
+  return TRANSIENT_ERROR_PATTERNS.some((pattern) => pattern.test(message));
+}
+
+class CircuitBreaker {
+  states = new Map;
+  threshold;
+  cooldownMs;
+  constructor(options = {}) {
+    this.threshold = options.failureThreshold ?? 3;
+    this.cooldownMs = options.cooldownMs ?? 60000;
+  }
+  getState(backend) {
+    const entry = this.states.get(backend);
+    if (!entry)
+      return "CLOSED";
+    if (entry.state === "OPEN" && Date.now() - entry.openedAt > this.cooldownMs) {
+      entry.state = "HALF_OPEN";
+    }
+    return entry.state;
+  }
+  isAvailable(backend) {
+    return this.getState(backend) !== "OPEN";
+  }
+  recordSuccess(backend) {
+    this.states.set(backend, { state: "CLOSED", failures: 0 });
+  }
+  recordFailure(backend) {
+    const entry = this.states.get(backend) ?? { state: "CLOSED", failures: 0 };
+    entry.failures++;
+    if (entry.failures >= this.threshold) {
+      entry.state = "OPEN";
+      entry.openedAt = Date.now();
+    }
+    this.states.set(backend, entry);
+  }
+}
+var TRANSIENT_ERROR_PATTERNS;
+var init_circuitBreaker = __esm(() => {
+  TRANSIENT_ERROR_PATTERNS = [
+    /\b5\d{2}\b/,
+    /timeout/i,
+    /timed out/i,
+    /econnreset/i,
+    /econnrefused/i,
+    /eai_again/i,
+    /etimedout/i,
+    /network error/i,
+    /service unavailable/i,
+    /bad gateway/i,
+    /gateway timeout/i
+  ];
 });
 
 // src/specialist/beads.ts
@@ -18065,6 +18220,9 @@ function buildBeadContext(bead, completedBlockers = []) {
   if (bead.description?.trim()) {
     lines.push(bead.description.trim());
   }
+  if (bead.parent?.trim()) {
+    lines.push("", "## Parent epic", bead.parent.trim());
+  }
   if (bead.notes?.trim()) {
     lines.push("", "## Notes", bead.notes.trim());
   }
@@ -18203,12 +18361,17 @@ import { execSync, spawnSync as spawnSync2 } from "node:child_process";
 import { existsSync as existsSync3, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { homedir as homedir2 } from "node:os";
-function runScript(run) {
+function runScript(command) {
+  const run = (command ?? "").trim();
+  if (!run) {
+    return { name: "unknown", output: "Missing script command (expected `run` or legacy `path`).", exitCode: 1 };
+  }
+  const scriptName = basename(run.split(" ")[0]);
   try {
     const output = execSync(run, { encoding: "utf8", timeout: 30000 });
-    return { name: basename(run.split(" ")[0]), output, exitCode: 0 };
+    return { name: scriptName, output, exitCode: 0 };
   } catch (e) {
-    return { name: basename(run.split(" ")[0]), output: e.stdout ?? e.message ?? "", exitCode: e.status ?? 1 };
+    return { name: scriptName, output: e.stdout ?? e.message ?? "", exitCode: e.status ?? 1 };
   }
 }
 function formatScriptOutput(results) {
@@ -18253,7 +18416,14 @@ function validateShebang(filePath, errors5) {
     }
   } catch {}
 }
-function validateBeforeRun(spec) {
+function isToolAvailable(tool, permissionLevel) {
+  const normalized = permissionLevel.toUpperCase();
+  const gatedLevels = PERMISSION_GATED_TOOLS[tool.toLowerCase()];
+  if (!gatedLevels)
+    return true;
+  return gatedLevels.includes(normalized);
+}
+function validateBeforeRun(spec, permissionLevel) {
   const errors5 = [];
   const warnings = [];
   for (const p of spec.specialist.skills?.paths ?? []) {
@@ -18262,7 +18432,7 @@ function validateBeforeRun(spec) {
       warnings.push(`  ⚠ skills.paths: file not found: ${p}`);
   }
   for (const script of spec.specialist.skills?.scripts ?? []) {
-    const { run } = script;
+    const run = script.run ?? script.path;
     if (!run)
       continue;
     const isFilePath = run.startsWith("./") || run.startsWith("../") || run.startsWith("/") || run.startsWith("~/");
@@ -18285,6 +18455,11 @@ function validateBeforeRun(spec) {
       errors5.push(`  ✗ capabilities.external_commands: not found on PATH: ${cmd}`);
     }
   }
+  for (const tool of spec.specialist.capabilities?.required_tools ?? []) {
+    if (!isToolAvailable(tool, permissionLevel)) {
+      errors5.push(`  ✗ capabilities.required_tools: tool "${tool}" requires higher permission than "${permissionLevel}"`);
+    }
+  }
   if (warnings.length > 0) {
     process.stderr.write(`[specialists] pre-run warnings:
 ${warnings.join(`
@@ -18297,6 +18472,18 @@ ${errors5.join(`
 `)}`);
   }
 }
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function getRetryDelayMs(attemptNumber) {
+  const baseDelay = RETRY_BASE_DELAY_MS * 2 ** Math.max(0, attemptNumber - 1);
+  const jitterMultiplier = 1 + (Math.random() * 2 - 1) * RETRY_MAX_JITTER;
+  return Math.max(0, Math.round(baseDelay * jitterMultiplier));
+}
+function isAuthError(error2) {
+  const message = error2 instanceof Error ? error2.message : typeof error2 === "string" ? error2 : JSON.stringify(error2);
+  return /\b(401|403|unauthorized|forbidden|authentication|auth|invalid api key|api key)\b/i.test(message);
+}
 
 class SpecialistRunner {
   deps;
@@ -18305,7 +18492,7 @@ class SpecialistRunner {
     this.deps = deps;
     this.sessionFactory = deps.sessionFactory ?? PiAgentSession.create.bind(PiAgentSession);
   }
-  async run(options, onProgress, onEvent, onMeta, onKillRegistered, onBeadCreated, onSteerRegistered, onResumeReady) {
+  async run(options, onProgress, onEvent, onMeta, onKillRegistered, onBeadCreated, onSteerRegistered, onResumeReady, onToolStartCallback, onToolEndCallback) {
     const { loader, hooks, circuitBreaker, beadsClient } = this.deps;
     const invocationId = crypto.randomUUID();
     const start = Date.now();
@@ -18321,9 +18508,11 @@ class SpecialistRunner {
       circuit_breaker_state: circuitBreaker.getState(model),
       scope: "project"
     });
-    validateBeforeRun(spec);
+    const permissionLevel = options.autonomyLevel ?? execution.permission_required;
+    const effectiveKeepAlive = options.noKeepAlive ? false : options.keepAlive ?? execution.interactive ?? false;
+    validateBeforeRun(spec, permissionLevel);
     const preScripts = spec.specialist.skills?.scripts?.filter((s) => s.phase === "pre") ?? [];
-    const preResults = preScripts.map((s) => runScript(s.run)).filter((_, i) => preScripts[i].inject_output);
+    const preResults = preScripts.map((s) => runScript(s.run ?? s.path)).filter((_, i) => preScripts[i].inject_output);
     const preScriptOutput = formatScriptOutput(preResults);
     const beadVariables = options.inputBeadId ? { bead_context: options.prompt, bead_id: options.inputBeadId } : {};
     const variables = {
@@ -18341,7 +18530,20 @@ class SpecialistRunner {
       estimated_tokens: Math.ceil(renderedTask.length / 4),
       system_prompt_present: !!prompt.system
     });
-    const agentsMd = prompt.system ?? "";
+    let agentsMd = prompt.system ?? "";
+    if (options.inputBeadId) {
+      agentsMd += `
+
+---
+## Specialist Run Context
+You are running as a specialist with bead ${options.inputBeadId} as your task.
+- Claim this bead directly: \`bd update ${options.inputBeadId} --claim\`
+- Do NOT create new beads or sub-issues — this bead IS your task.
+- Do NOT run \`bd create\` — the orchestrator manages issue tracking.
+- Close the bead when done: \`bd close ${options.inputBeadId} --reason="..."\`
+---
+`;
+    }
     const skillPaths = [];
     if (prompt.skill_inherit)
       skillPaths.push(prompt.skill_inherit);
@@ -18360,7 +18562,7 @@ ${skillPaths.map((p) => `    • ${p}`).join(`
       }
       if (preScripts.length > 0) {
         onProgress?.(`  pre scripts/commands:
-${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_output" : ""}`).join(`
+${preScripts.map((s) => `    • ${s.run ?? s.path ?? "<missing>"}${s.inject_output ? " → $pre_script_output" : ""}`).join(`
 `)}
 `);
       }
@@ -18368,13 +18570,6 @@ ${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_o
 
 `);
     }
-    const permissionLevel = options.autonomyLevel ?? execution.permission_required;
-    await hooks.emit("pre_execute", invocationId, metadata.name, metadata.version, {
-      backend: model,
-      model,
-      timeout_ms: execution.timeout_ms,
-      permission_level: permissionLevel
-    });
     const beadsIntegration = spec.specialist.beads_integration ?? "auto";
     let beadId;
     let ownsBead = false;
@@ -18387,11 +18582,19 @@ ${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_o
         onBeadCreated?.(beadId);
       }
     }
+    await hooks.emit("pre_execute", invocationId, metadata.name, metadata.version, {
+      backend: model,
+      model,
+      timeout_ms: execution.timeout_ms,
+      permission_level: permissionLevel
+    });
     let output;
     let sessionBackend = model;
     let session;
     let keepAliveActive = false;
     let sessionClosed = false;
+    const maxRetries = Math.max(0, Math.trunc(options.maxRetries ?? execution.max_retries ?? 0));
+    const maxAttempts = maxRetries + 1;
     try {
       session = await this.sessionFactory({
         model,
@@ -18399,25 +18602,50 @@ ${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_o
         skillPaths: skillPaths.length > 0 ? skillPaths : undefined,
         thinkingLevel: execution.thinking_level,
         permissionLevel,
+        stallTimeoutMs: execution.stall_timeout_ms,
         cwd: process.cwd(),
         onToken: (delta) => onProgress?.(delta),
         onThinking: (delta) => onProgress?.(`\uD83D\uDCAD ${delta}`),
-        onToolStart: (tool) => onProgress?.(`
-⚙ ${tool}…`),
-        onToolEnd: (_tool) => onProgress?.(`✓
-`),
+        onToolStart: (tool, args, toolCallId) => {
+          onProgress?.(`
+⚙ ${tool}…`);
+          onToolStartCallback?.(tool, args, toolCallId);
+        },
+        onToolEnd: (tool, isError, toolCallId) => {
+          onProgress?.(`✓
+`);
+          onToolEndCallback?.(tool, isError, toolCallId);
+        },
         onEvent: (type) => onEvent?.(type),
         onMeta: (meta) => onMeta?.(meta)
       });
       await session.start();
       onKillRegistered?.(session.kill.bind(session));
       onSteerRegistered?.((msg) => session.steer(msg));
-      await session.prompt(renderedTask);
-      await session.waitForDone(execution.timeout_ms);
-      sessionBackend = session.meta.backend;
-      output = await session.getLastOutput();
-      sessionBackend = session.meta.backend;
-      if (options.keepAlive && onResumeReady) {
+      for (let attempt = 1;attempt <= maxAttempts; attempt++) {
+        try {
+          await session.prompt(renderedTask);
+          await session.waitForDone(execution.timeout_ms);
+          output = await session.getLastOutput();
+          sessionBackend = session.meta.backend;
+          break;
+        } catch (err) {
+          const shouldRetry = attempt < maxAttempts && !(err instanceof SessionKilledError) && !isAuthError(err) && isTransientError(err);
+          if (!shouldRetry) {
+            throw err;
+          }
+          const delayMs = getRetryDelayMs(attempt);
+          onEvent?.("auto_retry");
+          onProgress?.(`
+↻ transient backend error on attempt ${attempt}/${maxAttempts}; retrying in ${delayMs}ms
+`);
+          await sleep(delayMs);
+        }
+      }
+      if (output === undefined) {
+        throw new Error("Specialist run finished without output");
+      }
+      if (effectiveKeepAlive && onResumeReady) {
         keepAliveActive = true;
         const resumeFn = async (msg) => {
           await session.resume(msg, execution.timeout_ms);
@@ -18434,7 +18662,7 @@ ${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_o
       }
       const postScripts = spec.specialist.skills?.scripts?.filter((s) => s.phase === "post") ?? [];
       for (const script of postScripts)
-        runScript(script.run);
+        runScript(script.run ?? script.path);
       circuitBreaker.recordSuccess(model);
     } catch (err) {
       const isCancelled = err instanceof SessionKilledError;
@@ -18469,8 +18697,6 @@ ${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_o
       output_valid: true
     });
     if (beadId) {
-      if (ownsBead)
-        beadsClient?.closeBead(beadId, "COMPLETE", durationMs, model);
       beadsClient?.auditBead(beadId, metadata.name, model, 0);
     }
     return {
@@ -18480,7 +18706,8 @@ ${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_o
       durationMs,
       specialistVersion: metadata.version,
       promptHash,
-      beadId
+      beadId,
+      permissionRequired: execution.permission_required
     };
   }
   async startAsync(options, registry2) {
@@ -18499,9 +18726,16 @@ ${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_o
     return jobId;
   }
 }
+var PERMISSION_GATED_TOOLS, RETRY_BASE_DELAY_MS = 1000, RETRY_MAX_JITTER = 0.2;
 var init_runner = __esm(() => {
   init_session();
+  init_circuitBreaker();
   init_beads();
+  PERMISSION_GATED_TOOLS = {
+    bash: ["LOW", "MEDIUM", "HIGH"],
+    edit: ["MEDIUM", "HIGH"],
+    write: ["HIGH"]
+  };
 });
 
 // src/specialist/hooks.ts
@@ -18540,62 +18774,21 @@ class HookEmitter {
 }
 var init_hooks = () => {};
 
-// src/utils/circuitBreaker.ts
-class CircuitBreaker {
-  states = new Map;
-  threshold;
-  cooldownMs;
-  constructor(options = {}) {
-    this.threshold = options.failureThreshold ?? 3;
-    this.cooldownMs = options.cooldownMs ?? 60000;
-  }
-  getState(backend) {
-    const entry = this.states.get(backend);
-    if (!entry)
-      return "CLOSED";
-    if (entry.state === "OPEN" && Date.now() - entry.openedAt > this.cooldownMs) {
-      entry.state = "HALF_OPEN";
-    }
-    return entry.state;
-  }
-  isAvailable(backend) {
-    return this.getState(backend) !== "OPEN";
-  }
-  recordSuccess(backend) {
-    this.states.set(backend, { state: "CLOSED", failures: 0 });
-  }
-  recordFailure(backend) {
-    const entry = this.states.get(backend) ?? { state: "CLOSED", failures: 0 };
-    entry.failures++;
-    if (entry.failures >= this.threshold) {
-      entry.state = "OPEN";
-      entry.openedAt = Date.now();
-    }
-    this.states.set(backend, entry);
-  }
-}
-
 // src/specialist/timeline-events.ts
 function mapCallbackEventToTimelineEvent(callbackEvent, context) {
   const t = Date.now();
   switch (callbackEvent) {
     case "thinking":
       return { t, type: TIMELINE_EVENT_TYPES.THINKING };
-    case "toolcall":
-      return {
-        t,
-        type: TIMELINE_EVENT_TYPES.TOOL,
-        tool: context.tool ?? "unknown",
-        phase: "start",
-        tool_call_id: context.toolCallId
-      };
     case "tool_execution_start":
       return {
         t,
         type: TIMELINE_EVENT_TYPES.TOOL,
         tool: context.tool ?? "unknown",
         phase: "start",
-        tool_call_id: context.toolCallId
+        tool_call_id: context.toolCallId,
+        args: context.args,
+        started_at: new Date(t).toISOString()
       };
     case "tool_execution_update":
     case "tool_execution":
@@ -18653,6 +18846,16 @@ function createMetaEvent(model, backend) {
     backend
   };
 }
+function createStaleWarningEvent(reason, options) {
+  return {
+    t: Date.now(),
+    type: TIMELINE_EVENT_TYPES.STALE_WARNING,
+    reason,
+    silence_ms: options.silence_ms,
+    threshold_ms: options.threshold_ms,
+    ...options.tool !== undefined ? { tool: options.tool } : {}
+  };
+}
 function createRunCompleteEvent(status, elapsed_s, options) {
   return {
     t: Date.now(),
@@ -18710,6 +18913,7 @@ var init_timeline_events = __esm(() => {
     MESSAGE: "message",
     TURN: "turn",
     RUN_COMPLETE: "run_complete",
+    STALE_WARNING: "stale_warning",
     DONE: "done",
     AGENT_END: "agent_end"
   };
@@ -18717,6 +18921,7 @@ var init_timeline_events = __esm(() => {
 
 // src/specialist/supervisor.ts
 import {
+  appendFileSync,
   closeSync,
   existsSync as existsSync4,
   fsyncSync,
@@ -18834,23 +19039,59 @@ class Supervisor {
   crashRecovery() {
     if (!existsSync4(this.opts.jobsDir))
       return;
+    const thresholds = {
+      ...STALL_DETECTION_DEFAULTS,
+      ...this.opts.stallDetection
+    };
+    const now = Date.now();
     for (const entry of readdirSync(this.opts.jobsDir)) {
       const statusPath = join3(this.opts.jobsDir, entry, "status.json");
       if (!existsSync4(statusPath))
         continue;
       try {
         const s = JSON.parse(readFileSync2(statusPath, "utf-8"));
-        if (s.status !== "running" && s.status !== "starting")
-          continue;
-        if (!s.pid)
-          continue;
-        try {
-          process.kill(s.pid, 0);
-        } catch {
-          const tmp = statusPath + ".tmp";
-          const updated = { ...s, status: "error", error: "Process crashed or was killed" };
-          writeFileSync(tmp, JSON.stringify(updated, null, 2), "utf-8");
-          renameSync(tmp, statusPath);
+        if (s.status === "running" || s.status === "starting") {
+          if (!s.pid)
+            continue;
+          let pidAlive = true;
+          try {
+            process.kill(s.pid, 0);
+          } catch {
+            pidAlive = false;
+          }
+          if (!pidAlive) {
+            const tmp = statusPath + ".tmp";
+            const updated = { ...s, status: "error", error: "Process crashed or was killed" };
+            writeFileSync(tmp, JSON.stringify(updated, null, 2), "utf-8");
+            renameSync(tmp, statusPath);
+          } else if (s.status === "running") {
+            const lastEventAt = s.last_event_at_ms ?? s.started_at_ms;
+            const silenceMs = now - lastEventAt;
+            if (silenceMs > thresholds.running_silence_error_ms) {
+              const tmp = statusPath + ".tmp";
+              const updated = {
+                ...s,
+                status: "error",
+                error: `No activity for ${Math.round(silenceMs / 1000)}s (threshold: ${thresholds.running_silence_error_ms / 1000}s)`
+              };
+              writeFileSync(tmp, JSON.stringify(updated, null, 2), "utf-8");
+              renameSync(tmp, statusPath);
+            }
+          }
+        } else if (s.status === "waiting") {
+          const lastEventAt = s.last_event_at_ms ?? s.started_at_ms;
+          const silenceMs = now - lastEventAt;
+          if (silenceMs > thresholds.waiting_stale_ms) {
+            const eventsPath = join3(this.opts.jobsDir, entry, "events.jsonl");
+            const event = createStaleWarningEvent("waiting_stale", {
+              silence_ms: silenceMs,
+              threshold_ms: thresholds.waiting_stale_ms
+            });
+            try {
+              appendFileSync(eventsPath, JSON.stringify(event) + `
+`);
+            } catch {}
+          }
         }
       } catch {}
     }
@@ -18869,7 +19110,8 @@ class Supervisor {
       specialist: runOptions.name,
       status: "starting",
       started_at_ms: startedAtMs,
-      pid: process.pid
+      pid: process.pid,
+      ...runOptions.inputBeadId ? { bead_id: runOptions.inputBeadId } : {}
     };
     this.writeStatusFile(id, initialStatus);
     writeFileSync(join3(this.opts.jobsDir, "latest"), `${id}
@@ -18889,24 +19131,69 @@ class Supervisor {
         console.error(`[supervisor] Failed to write event: ${err?.message ?? err}`);
       }
     };
-    appendTimelineEvent(createRunStartEvent(runOptions.name));
+    appendTimelineEvent(createRunStartEvent(runOptions.name, runOptions.inputBeadId));
     const fifoPath = join3(dir, "steer.pipe");
-    const needsFifo = runOptions.keepAlive;
-    if (needsFifo) {
-      try {
-        execFileSync("mkfifo", [fifoPath]);
-        setStatus({ fifo_path: fifoPath });
-      } catch {}
-    }
+    try {
+      execFileSync("mkfifo", [fifoPath]);
+      setStatus({ fifo_path: fifoPath });
+    } catch {}
     let textLogged = false;
     let currentTool = "";
     let currentToolCallId = "";
+    let currentToolArgs;
+    let currentToolIsError = false;
+    const activeToolCalls = new Map;
     let killFn;
     let steerFn;
     let resumeFn;
     let closeFn;
     let fifoReadStream;
     let fifoReadline;
+    const thresholds = {
+      ...STALL_DETECTION_DEFAULTS,
+      ...this.opts.stallDetection
+    };
+    let lastActivityMs = startedAtMs;
+    let silenceWarnEmitted = false;
+    let toolStartMs;
+    let toolDurationWarnEmitted = false;
+    let stuckIntervalId;
+    stuckIntervalId = setInterval(() => {
+      const now = Date.now();
+      if (statusSnapshot.status === "running") {
+        const silenceMs = now - lastActivityMs;
+        if (!silenceWarnEmitted && silenceMs > thresholds.running_silence_warn_ms) {
+          silenceWarnEmitted = true;
+          appendTimelineEvent(createStaleWarningEvent("running_silence", {
+            silence_ms: silenceMs,
+            threshold_ms: thresholds.running_silence_warn_ms
+          }));
+        }
+        if (silenceMs > thresholds.running_silence_error_ms) {
+          appendTimelineEvent(createStaleWarningEvent("running_silence_error", {
+            silence_ms: silenceMs,
+            threshold_ms: thresholds.running_silence_error_ms
+          }));
+          setStatus({
+            status: "error",
+            error: `No activity for ${Math.round(silenceMs / 1000)}s (threshold: ${thresholds.running_silence_error_ms / 1000}s)`
+          });
+          killFn?.();
+          clearInterval(stuckIntervalId);
+        }
+      }
+      if (toolStartMs !== undefined && !toolDurationWarnEmitted) {
+        const toolDurationMs = now - toolStartMs;
+        if (toolDurationMs > thresholds.tool_duration_warn_ms) {
+          toolDurationWarnEmitted = true;
+          appendTimelineEvent(createStaleWarningEvent("tool_duration", {
+            silence_ms: toolDurationMs,
+            threshold_ms: thresholds.tool_duration_warn_ms,
+            tool: currentTool
+          }));
+        }
+      }
+    }, 1e4);
     const sigtermHandler = () => killFn?.();
     process.once("SIGTERM", sigtermHandler);
     try {
@@ -18919,6 +19206,8 @@ class Supervisor {
         this.opts.onProgress?.(delta);
       }, (eventType) => {
         const now = Date.now();
+        lastActivityMs = now;
+        silenceWarnEmitted = false;
         setStatus({
           status: "running",
           current_event: eventType,
@@ -18927,7 +19216,9 @@ class Supervisor {
         });
         const timelineEvent = mapCallbackEventToTimelineEvent(eventType, {
           tool: currentTool,
-          toolCallId: currentToolCallId || undefined
+          toolCallId: currentToolCallId || undefined,
+          args: currentToolArgs,
+          isError: currentToolIsError
         });
         if (timelineEvent) {
           appendTimelineEvent(timelineEvent);
@@ -18945,7 +19236,7 @@ class Supervisor {
         setStatus({ bead_id: beadId });
       }, (fn) => {
         steerFn = fn;
-        if (!needsFifo || !existsSync4(fifoPath))
+        if (!existsSync4(fifoPath))
           return;
         fifoReadStream = createReadStream(fifoPath, { flags: "r+" });
         fifoReadline = createInterface({ input: fifoReadStream });
@@ -18954,7 +19245,24 @@ class Supervisor {
             const parsed = JSON.parse(line);
             if (parsed?.type === "steer" && typeof parsed.message === "string") {
               steerFn?.(parsed.message).catch(() => {});
+            } else if (parsed?.type === "resume" && typeof parsed.task === "string") {
+              if (resumeFn) {
+                setStatus({ status: "running", current_event: "starting" });
+                resumeFn(parsed.task).then((output) => {
+                  mkdirSync(this.jobDir(id), { recursive: true });
+                  writeFileSync(this.resultPath(id), output, "utf-8");
+                  setStatus({
+                    status: "waiting",
+                    current_event: "waiting",
+                    elapsed_s: Math.round((Date.now() - startedAtMs) / 1000),
+                    last_event_at_ms: Date.now()
+                  });
+                }).catch((err) => {
+                  setStatus({ status: "error", error: err?.message ?? String(err) });
+                });
+              }
             } else if (parsed?.type === "prompt" && typeof parsed.message === "string") {
+              console.error('[specialists] DEPRECATED: FIFO message {type:"prompt"} is deprecated. Use {type:"resume", task:"..."} instead.');
               if (resumeFn) {
                 setStatus({ status: "running", current_event: "starting" });
                 resumeFn(parsed.message).then((output) => {
@@ -18980,12 +19288,51 @@ class Supervisor {
         resumeFn = rFn;
         closeFn = cFn;
         setStatus({ status: "waiting", current_event: "waiting" });
+      }, (tool, args, toolCallId) => {
+        currentTool = tool;
+        currentToolArgs = args;
+        currentToolCallId = toolCallId ?? "";
+        currentToolIsError = false;
+        toolStartMs = Date.now();
+        toolDurationWarnEmitted = false;
+        setStatus({ current_tool: tool });
+        if (toolCallId) {
+          activeToolCalls.set(toolCallId, { tool, args });
+        }
+      }, (tool, isError, toolCallId) => {
+        if (toolCallId && activeToolCalls.has(toolCallId)) {
+          const entry = activeToolCalls.get(toolCallId);
+          currentTool = entry.tool;
+          currentToolArgs = entry.args;
+          currentToolCallId = toolCallId;
+          activeToolCalls.delete(toolCallId);
+        } else {
+          currentTool = tool;
+        }
+        currentToolIsError = isError;
+        toolStartMs = undefined;
+        toolDurationWarnEmitted = false;
       });
       const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
       mkdirSync(this.jobDir(id), { recursive: true });
       writeFileSync(this.resultPath(id), result.output, "utf-8");
-      if (result.beadId) {
+      const inputBeadId = runOptions.inputBeadId;
+      const ownsBead = Boolean(result.beadId && !inputBeadId);
+      const shouldWriteExternalBeadNotes = runOptions.beadsWriteNotes ?? true;
+      const shouldAppendReadOnlyResultToInputBead = Boolean(inputBeadId && result.permissionRequired === "READ_ONLY" && this.opts.beadsClient);
+      if (ownsBead && result.beadId) {
         this.opts.beadsClient?.updateBeadNotes(result.beadId, formatBeadNotes(result));
+      } else if (shouldWriteExternalBeadNotes) {
+        if (shouldAppendReadOnlyResultToInputBead && inputBeadId) {
+          this.opts.beadsClient?.updateBeadNotes(inputBeadId, formatBeadNotes(result));
+        } else if (result.beadId) {
+          this.opts.beadsClient?.updateBeadNotes(result.beadId, formatBeadNotes(result));
+        }
+      }
+      if (result.beadId) {
+        if (!inputBeadId) {
+          this.opts.beadsClient?.closeBead(result.beadId, "COMPLETE", result.durationMs, result.model);
+        }
       }
       setStatus({
         status: "done",
@@ -18998,7 +19345,8 @@ class Supervisor {
       appendTimelineEvent(createRunCompleteEvent("COMPLETE", elapsed, {
         model: result.model,
         backend: result.backend,
-        bead_id: result.beadId
+        bead_id: result.beadId,
+        output: result.output
       }));
       mkdirSync(this.readyDir(), { recursive: true });
       writeFileSync(join3(this.readyDir(), id), "", "utf-8");
@@ -19016,6 +19364,8 @@ class Supervisor {
       }));
       throw err;
     } finally {
+      if (stuckIntervalId !== undefined)
+        clearInterval(stuckIntervalId);
       process.removeListener("SIGTERM", sigtermHandler);
       try {
         fifoReadline?.close();
@@ -19034,52 +19384,184 @@ class Supervisor {
     }
   }
 }
-var JOB_TTL_DAYS;
+var JOB_TTL_DAYS, STALL_DETECTION_DEFAULTS;
 var init_supervisor = __esm(() => {
   init_timeline_events();
   JOB_TTL_DAYS = Number(process.env.SPECIALISTS_JOB_TTL_DAYS ?? 7);
+  STALL_DETECTION_DEFAULTS = {
+    running_silence_warn_ms: 60000,
+    running_silence_error_ms: 300000,
+    waiting_stale_ms: 3600000,
+    tool_duration_warn_ms: 120000
+  };
 });
 
-// src/cli/install.ts
-var exports_install = {};
-__export(exports_install, {
-  run: () => run
-});
-async function run() {
-  console.log("");
-  console.log(yellow("⚠ DEPRECATED: `specialists install` is deprecated"));
-  console.log("");
-  console.log(`  Use ${bold("specialists init")} instead.`);
-  console.log("");
-  console.log("  The init command:");
-  console.log("    • creates specialists/ and .specialists/ directories");
-  console.log("    • registers the MCP server in .mcp.json");
-  console.log("    • injects workflow context into AGENTS.md/CLAUDE.md");
-  console.log("");
-  console.log(`  ${dim("Run: specialists init --help for full details")}`);
-  console.log("");
+// src/specialist/timeline-query.ts
+import { existsSync as existsSync5, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "node:fs";
+import { join as join8 } from "node:path";
+function readJobEvents(jobDir) {
+  const eventsPath = join8(jobDir, "events.jsonl");
+  if (!existsSync5(eventsPath))
+    return [];
+  const content = readFileSync3(eventsPath, "utf-8");
+  const lines = content.split(`
+`).filter(Boolean);
+  const events = [];
+  for (const line of lines) {
+    const event = parseTimelineEvent(line);
+    if (event)
+      events.push(event);
+  }
+  events.sort(compareTimelineEvents);
+  return events;
 }
-var bold = (s) => `\x1B[1m${s}\x1B[0m`, yellow = (s) => `\x1B[33m${s}\x1B[0m`, dim = (s) => `\x1B[2m${s}\x1B[0m`;
-
-// src/cli/version.ts
-var exports_version = {};
-__export(exports_version, {
-  run: () => run2
-});
-import { createRequire as createRequire2 } from "node:module";
-import { fileURLToPath } from "node:url";
-import { dirname as dirname2, join as join8 } from "node:path";
-import { existsSync as existsSync6 } from "node:fs";
-async function run2() {
-  const req = createRequire2(import.meta.url);
-  const here = dirname2(fileURLToPath(import.meta.url));
-  const bundlePkgPath = join8(here, "..", "package.json");
-  const sourcePkgPath = join8(here, "..", "..", "package.json");
-  let pkg;
-  if (existsSync6(bundlePkgPath)) {
-    pkg = req("../package.json");
-  } else if (existsSync6(sourcePkgPath)) {
-    pkg = req("../../package.json");
+function readJobEventsById(jobsDir, jobId) {
+  return readJobEvents(join8(jobsDir, jobId));
+}
+function readAllJobEvents(jobsDir) {
+  if (!existsSync5(jobsDir))
+    return [];
+  const batches = [];
+  const entries = readdirSync2(jobsDir);
+  for (const entry of entries) {
+    const jobDir = join8(jobsDir, entry);
+    try {
+      const stat2 = __require("node:fs").statSync(jobDir);
+      if (!stat2.isDirectory())
+        continue;
+    } catch {
+      continue;
+    }
+    const jobId = entry;
+    const statusPath = join8(jobDir, "status.json");
+    let specialist = "unknown";
+    let beadId;
+    if (existsSync5(statusPath)) {
+      try {
+        const status = JSON.parse(readFileSync3(statusPath, "utf-8"));
+        specialist = status.specialist ?? "unknown";
+        beadId = status.bead_id;
+      } catch {}
+    }
+    const events = readJobEvents(jobDir);
+    if (events.length > 0) {
+      batches.push({ jobId, specialist, beadId, events });
+    }
+  }
+  return batches;
+}
+function mergeTimelineEvents(batches) {
+  const merged = [];
+  for (const batch of batches) {
+    for (const event of batch.events) {
+      merged.push({
+        jobId: batch.jobId,
+        specialist: batch.specialist,
+        beadId: batch.beadId,
+        event
+      });
+    }
+  }
+  merged.sort((a, b) => compareTimelineEvents(a.event, b.event));
+  return merged;
+}
+function filterTimelineEvents(merged, filter) {
+  let result = merged;
+  if (filter.since !== undefined) {
+    result = result.filter(({ event }) => event.t >= filter.since);
+  }
+  if (filter.jobId !== undefined) {
+    result = result.filter(({ jobId }) => jobId === filter.jobId);
+  }
+  if (filter.specialist !== undefined) {
+    result = result.filter(({ specialist }) => specialist === filter.specialist);
+  }
+  if (filter.limit !== undefined && filter.limit > 0) {
+    result = result.slice(0, filter.limit);
+  }
+  return result;
+}
+function queryTimeline(jobsDir, filter = {}) {
+  let batches = readAllJobEvents(jobsDir);
+  if (filter.jobId !== undefined) {
+    batches = batches.filter((b) => b.jobId === filter.jobId);
+  }
+  if (filter.specialist !== undefined) {
+    batches = batches.filter((b) => b.specialist === filter.specialist);
+  }
+  const merged = mergeTimelineEvents(batches);
+  return filterTimelineEvents(merged, filter);
+}
+function isJobComplete(events) {
+  return events.some((e) => e.type === "run_complete");
+}
+var init_timeline_query = __esm(() => {
+  init_timeline_events();
+});
+
+// src/specialist/model-display.ts
+function extractModelId(model) {
+  if (!model)
+    return;
+  const trimmed = model.trim();
+  if (!trimmed)
+    return;
+  return trimmed.includes("/") ? trimmed.split("/").pop() : trimmed;
+}
+function toModelAlias(model) {
+  const modelId = extractModelId(model);
+  if (!modelId)
+    return;
+  if (modelId.startsWith("claude-")) {
+    return modelId.slice("claude-".length);
+  }
+  return modelId;
+}
+function formatSpecialistModel(specialist, model) {
+  const alias = toModelAlias(model);
+  return alias ? `${specialist}/${alias}` : specialist;
+}
+
+// src/cli/install.ts
+var exports_install = {};
+__export(exports_install, {
+  run: () => run
+});
+async function run() {
+  console.log("");
+  console.log(yellow("⚠ DEPRECATED: `specialists install` is deprecated"));
+  console.log("");
+  console.log(`  Use ${bold("specialists init")} instead.`);
+  console.log("");
+  console.log("  The init command:");
+  console.log("    • creates specialists/ and .specialists/ directories");
+  console.log("    • registers the MCP server in .mcp.json");
+  console.log("    • injects workflow context into AGENTS.md/CLAUDE.md");
+  console.log("");
+  console.log(`  ${dim("Run: specialists init --help for full details")}`);
+  console.log("");
+}
+var bold = (s) => `\x1B[1m${s}\x1B[0m`, yellow = (s) => `\x1B[33m${s}\x1B[0m`, dim = (s) => `\x1B[2m${s}\x1B[0m`;
+
+// src/cli/version.ts
+var exports_version = {};
+__export(exports_version, {
+  run: () => run2
+});
+import { createRequire as createRequire2 } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname as dirname2, join as join12 } from "node:path";
+import { existsSync as existsSync8 } from "node:fs";
+async function run2() {
+  const req = createRequire2(import.meta.url);
+  const here = dirname2(fileURLToPath(import.meta.url));
+  const bundlePkgPath = join12(here, "..", "package.json");
+  const sourcePkgPath = join12(here, "..", "..", "package.json");
+  let pkg;
+  if (existsSync8(bundlePkgPath)) {
+    pkg = req("../package.json");
+  } else if (existsSync8(sourcePkgPath)) {
+    pkg = req("../../package.json");
   } else {
     console.error("Cannot find package.json");
     process.exit(1);
@@ -19281,8 +19763,8 @@ var exports_init = {};
 __export(exports_init, {
   run: () => run5
 });
-import { copyFileSync, cpSync, existsSync as existsSync7, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join9 } from "node:path";
+import { copyFileSync, cpSync, existsSync as existsSync9, mkdirSync as mkdirSync2, readdirSync as readdirSync3, readFileSync as readFileSync5, renameSync as renameSync2, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join13 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function ok(msg) {
   console.log(`  ${green3("✓")} ${msg}`);
@@ -19291,10 +19773,10 @@ function skip(msg) {
   console.log(`  ${yellow4("○")} ${msg}`);
 }
 function loadJson(path, fallback) {
-  if (!existsSync7(path))
+  if (!existsSync9(path))
     return structuredClone(fallback);
   try {
-    return JSON.parse(readFileSync3(path, "utf-8"));
+    return JSON.parse(readFileSync5(path, "utf-8"));
   } catch {
     return structuredClone(fallback);
   }
@@ -19306,34 +19788,64 @@ function saveJson(path, value) {
 function resolvePackagePath(relativePath) {
   const configPath = `config/${relativePath}`;
   let resolved = fileURLToPath2(new URL(`../${configPath}`, import.meta.url));
-  if (existsSync7(resolved))
+  if (existsSync9(resolved))
     return resolved;
   resolved = fileURLToPath2(new URL(`../../${configPath}`, import.meta.url));
-  if (existsSync7(resolved))
+  if (existsSync9(resolved))
     return resolved;
   return null;
 }
+function migrateLegacySpecialists(cwd, scope) {
+  const sourceDir = join13(cwd, ".specialists", scope, "specialists");
+  if (!existsSync9(sourceDir))
+    return;
+  const targetDir = join13(cwd, ".specialists", scope);
+  if (!existsSync9(targetDir)) {
+    mkdirSync2(targetDir, { recursive: true });
+  }
+  const files = readdirSync3(sourceDir).filter((f) => f.endsWith(".specialist.yaml"));
+  if (files.length === 0)
+    return;
+  let moved = 0;
+  let skipped = 0;
+  for (const file of files) {
+    const src = join13(sourceDir, file);
+    const dest = join13(targetDir, file);
+    if (existsSync9(dest)) {
+      skipped++;
+      continue;
+    }
+    renameSync2(src, dest);
+    moved++;
+  }
+  if (moved > 0) {
+    ok(`migrated ${moved} specialist${moved === 1 ? "" : "s"} from .specialists/${scope}/specialists/ to .specialists/${scope}/`);
+  }
+  if (skipped > 0) {
+    skip(`${skipped} legacy specialist${skipped === 1 ? "" : "s"} already exist in .specialists/${scope}/ (not moved)`);
+  }
+}
 function copyCanonicalSpecialists(cwd) {
   const sourceDir = resolvePackagePath("specialists");
   if (!sourceDir) {
     skip("no canonical specialists found in package");
     return;
   }
-  const targetDir = join9(cwd, ".specialists", "default", "specialists");
-  const files = readdirSync2(sourceDir).filter((f) => f.endsWith(".specialist.yaml"));
+  const targetDir = join13(cwd, ".specialists", "default");
+  const files = readdirSync3(sourceDir).filter((f) => f.endsWith(".specialist.yaml"));
   if (files.length === 0) {
     skip("no specialist files found in package");
     return;
   }
-  if (!existsSync7(targetDir)) {
+  if (!existsSync9(targetDir)) {
     mkdirSync2(targetDir, { recursive: true });
   }
   let copied = 0;
   let skipped = 0;
   for (const file of files) {
-    const src = join9(sourceDir, file);
-    const dest = join9(targetDir, file);
-    if (existsSync7(dest)) {
+    const src = join13(sourceDir, file);
+    const dest = join13(targetDir, file);
+    if (existsSync9(dest)) {
       skipped++;
     } else {
       copyFileSync(src, dest);
@@ -19341,7 +19853,7 @@ function copyCanonicalSpecialists(cwd) {
     }
   }
   if (copied > 0) {
-    ok(`copied ${copied} canonical specialist${copied === 1 ? "" : "s"} to .specialists/default/specialists/`);
+    ok(`copied ${copied} canonical specialist${copied === 1 ? "" : "s"} to .specialists/default/`);
   }
   if (skipped > 0) {
     skip(`${skipped} specialist${skipped === 1 ? "" : "s"} already exist (not overwritten)`);
@@ -19353,21 +19865,21 @@ function installProjectHooks(cwd) {
     skip("no canonical hooks found in package");
     return;
   }
-  const targetDir = join9(cwd, ".claude", "hooks");
-  const hooks = readdirSync2(sourceDir).filter((f) => f.endsWith(".mjs"));
+  const targetDir = join13(cwd, ".claude", "hooks");
+  const hooks = readdirSync3(sourceDir).filter((f) => f.endsWith(".mjs"));
   if (hooks.length === 0) {
     skip("no hook files found in package");
     return;
   }
-  if (!existsSync7(targetDir)) {
+  if (!existsSync9(targetDir)) {
     mkdirSync2(targetDir, { recursive: true });
   }
   let copied = 0;
   let skipped = 0;
   for (const file of hooks) {
-    const src = join9(sourceDir, file);
-    const dest = join9(targetDir, file);
-    if (existsSync7(dest)) {
+    const src = join13(sourceDir, file);
+    const dest = join13(targetDir, file);
+    if (existsSync9(dest)) {
       skipped++;
     } else {
       copyFileSync(src, dest);
@@ -19382,9 +19894,9 @@ function installProjectHooks(cwd) {
   }
 }
 function ensureProjectHookWiring(cwd) {
-  const settingsPath = join9(cwd, ".claude", "settings.json");
-  const settingsDir = join9(cwd, ".claude");
-  if (!existsSync7(settingsDir)) {
+  const settingsPath = join13(cwd, ".claude", "settings.json");
+  const settingsDir = join13(cwd, ".claude");
+  if (!existsSync9(settingsDir)) {
     mkdirSync2(settingsDir, { recursive: true });
   }
   const settings = loadJson(settingsPath, {});
@@ -19413,25 +19925,25 @@ function installProjectSkills(cwd) {
     skip("no canonical skills found in package");
     return;
   }
-  const skills = readdirSync2(sourceDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  const skills = readdirSync3(sourceDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
   if (skills.length === 0) {
     skip("no skill directories found in package");
     return;
   }
   const targetDirs = [
-    join9(cwd, ".claude", "skills"),
-    join9(cwd, ".pi", "skills")
+    join13(cwd, ".claude", "skills"),
+    join13(cwd, ".pi", "skills")
   ];
   let totalCopied = 0;
   let totalSkipped = 0;
   for (const targetDir of targetDirs) {
-    if (!existsSync7(targetDir)) {
+    if (!existsSync9(targetDir)) {
       mkdirSync2(targetDir, { recursive: true });
     }
     for (const skill of skills) {
-      const src = join9(sourceDir, skill);
-      const dest = join9(targetDir, skill);
-      if (existsSync7(dest)) {
+      const src = join13(sourceDir, skill);
+      const dest = join13(targetDir, skill);
+      if (existsSync9(dest)) {
         totalSkipped++;
       } else {
         cpSync(src, dest, { recursive: true });
@@ -19447,20 +19959,20 @@ function installProjectSkills(cwd) {
   }
 }
 function createUserDirs(cwd) {
-  const userDir = join9(cwd, ".specialists", "user", "specialists");
-  if (!existsSync7(userDir)) {
+  const userDir = join13(cwd, ".specialists", "user");
+  if (!existsSync9(userDir)) {
     mkdirSync2(userDir, { recursive: true });
-    ok("created .specialists/user/specialists/ for custom specialists");
+    ok("created .specialists/user/ for custom specialists");
   }
 }
 function createRuntimeDirs(cwd) {
   const runtimeDirs = [
-    join9(cwd, ".specialists", "jobs"),
-    join9(cwd, ".specialists", "ready")
+    join13(cwd, ".specialists", "jobs"),
+    join13(cwd, ".specialists", "ready")
   ];
   let created = 0;
   for (const dir of runtimeDirs) {
-    if (!existsSync7(dir)) {
+    if (!existsSync9(dir)) {
       mkdirSync2(dir, { recursive: true });
       created++;
     }
@@ -19470,7 +19982,7 @@ function createRuntimeDirs(cwd) {
   }
 }
 function ensureProjectMcp(cwd) {
-  const mcpPath = join9(cwd, MCP_FILE);
+  const mcpPath = join13(cwd, MCP_FILE);
   const mcp = loadJson(mcpPath, { mcpServers: {} });
   mcp.mcpServers ??= {};
   const existing = mcp.mcpServers[MCP_SERVER_NAME];
@@ -19483,8 +19995,8 @@ function ensureProjectMcp(cwd) {
   ok("registered specialists in project .mcp.json");
 }
 function ensureGitignore(cwd) {
-  const gitignorePath = join9(cwd, ".gitignore");
-  const existing = existsSync7(gitignorePath) ? readFileSync3(gitignorePath, "utf-8") : "";
+  const gitignorePath = join13(cwd, ".gitignore");
+  const existing = existsSync9(gitignorePath) ? readFileSync5(gitignorePath, "utf-8") : "";
   let added = 0;
   const lines = existing.split(`
 `);
@@ -19504,9 +20016,9 @@ function ensureGitignore(cwd) {
   }
 }
 function ensureAgentsMd(cwd) {
-  const agentsPath = join9(cwd, "AGENTS.md");
-  if (existsSync7(agentsPath)) {
-    const existing = readFileSync3(agentsPath, "utf-8");
+  const agentsPath = join13(cwd, "AGENTS.md");
+  if (existsSync9(agentsPath)) {
+    const existing = readFileSync5(agentsPath, "utf-8");
     if (existing.includes(AGENTS_MARKER)) {
       skip("AGENTS.md already has Specialists section");
     } else {
@@ -19525,6 +20037,8 @@ async function run5() {
   console.log(`
 ${bold4("specialists init")}
 `);
+  migrateLegacySpecialists(cwd, "default");
+  migrateLegacySpecialists(cwd, "user");
   copyCanonicalSpecialists(cwd);
   createUserDirs(cwd);
   createRuntimeDirs(cwd);
@@ -19546,15 +20060,13 @@ ${bold4("Done!")}
   console.log(`  ${dim4(".specialists/ structure:")}`);
   console.log(`  .specialists/`);
   console.log(`  ├── default/           ${dim4("# canonical specialists (from init)")}`);
-  console.log(`  │   └── specialists/`);
   console.log(`  ├── user/              ${dim4("# your custom specialists")}`);
-  console.log(`  │   └── specialists/`);
   console.log(`  ├── jobs/              ${dim4("# runtime (gitignored)")}`);
   console.log(`  └── ready/             ${dim4("# runtime (gitignored)")}`);
   console.log(`
   ${dim4("Next steps:")}`);
   console.log(`  1. Run ${yellow4("specialists list")} to see available specialists`);
-  console.log(`  2. Add custom specialists to ${yellow4(".specialists/user/specialists/")}`);
+  console.log(`  2. Add custom specialists to ${yellow4(".specialists/user/")}`);
   console.log(`  3. Restart Claude Code or pi to pick up changes
 `);
 }
@@ -19563,12 +20075,29 @@ var init_init = __esm(() => {
   AGENTS_BLOCK = `
 ## Specialists
 
-Call \`specialist_init\` at the start of every session to bootstrap context and
-see available specialists. Use \`use_specialist\` or \`start_specialist\` to
-delegate heavy tasks (code review, bug hunting, deep reasoning) to the right
-specialist without user intervention.
-
-Add custom specialists to \`.specialists/user/specialists/\` to extend the defaults.
+Call \`specialists init\` once per project, then use CLI commands via Bash.
+
+Core specialist commands (CLI-first in pi):
+- \`specialists list\`
+- \`specialists run <name> --bead <id>\`
+- \`specialists run <name> --prompt "..."\`
+- \`specialists feed -f\` / \`specialists feed <job-id>\`
+- \`specialists result <job-id>\`
+- \`specialists resume <job-id> "next task"\` (for keep-alive jobs in waiting)
+- \`specialists stop <job-id>\`
+
+For background specialists in pi, prefer the process extension:
+- \`process start\`, \`process list\`, \`process output\`, \`process logs\`, \`process kill\`, \`process clear\`
+- TUI: \`/ps\`, \`/ps:pin\`, \`/ps:logs\`, \`/ps:kill\`, \`/ps:clear\`, \`/ps:dock\`, \`/ps:settings\`
+
+Canonical tracked flow:
+1. Create/claim bead issue
+2. Run specialist with \`--bead <id>\` (for long work, launch via \`process start\`)
+3. Observe progress (\`process output\` / \`process logs\` or \`specialists feed\`)
+4. Read final output (\`specialists result <job-id>\`)
+5. Close/update bead with outcome
+
+Add custom specialists to \`.specialists/user/\` to extend defaults.
 `.trimStart();
   GITIGNORE_ENTRIES = [".specialists/jobs/", ".specialists/ready/"];
   MCP_SERVER_CONFIG = { command: "specialists", args: [] };
@@ -19582,8 +20111,8 @@ __export(exports_validate, {
   ArgParseError: () => ArgParseError2
 });
 import { readFile as readFile2 } from "node:fs/promises";
-import { existsSync as existsSync8 } from "node:fs";
-import { join as join10 } from "node:path";
+import { existsSync as existsSync10 } from "node:fs";
+import { join as join14 } from "node:path";
 function parseArgs3(argv) {
   const name = argv[0];
   if (!name || name.startsWith("--")) {
@@ -19594,13 +20123,15 @@ function parseArgs3(argv) {
 }
 function findSpecialistFile(name) {
   const scanDirs = [
-    join10(process.cwd(), ".specialists", "user", "specialists"),
-    join10(process.cwd(), ".specialists", "default", "specialists"),
-    join10(process.cwd(), "specialists")
+    join14(process.cwd(), ".specialists", "user"),
+    join14(process.cwd(), ".specialists", "user", "specialists"),
+    join14(process.cwd(), ".specialists", "default"),
+    join14(process.cwd(), ".specialists", "default", "specialists"),
+    join14(process.cwd(), "specialists")
   ];
   for (const dir of scanDirs) {
-    const candidate = join10(dir, `${name}.specialist.yaml`);
-    if (existsSync8(candidate)) {
+    const candidate = join14(dir, `${name}.specialist.yaml`);
+    if (existsSync10(candidate)) {
       return candidate;
     }
   }
@@ -19692,7 +20223,9 @@ var exports_edit = {};
 __export(exports_edit, {
   run: () => run7
 });
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "node:fs";
+import { spawnSync as spawnSync6 } from "node:child_process";
+import { existsSync as existsSync11, readdirSync as readdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join15 } from "node:path";
 function parseArgs4(argv) {
   const name = argv[0];
   if (!name || name.startsWith("--")) {
@@ -19755,8 +20288,30 @@ function setIn(doc2, path, value) {
     node.set(leaf, value);
   }
 }
+function openAllConfigSpecialistsInEditor() {
+  const configDir = join15(process.cwd(), "config", "specialists");
+  if (!existsSync11(configDir)) {
+    console.error(`Error: missing directory: ${configDir}`);
+    process.exit(1);
+  }
+  const files = readdirSync4(configDir).filter((file) => file.endsWith(".specialist.yaml")).sort().map((file) => join15(configDir, file));
+  if (files.length === 0) {
+    console.error("Error: no specialist YAML files found in config/specialists/");
+    process.exit(1);
+  }
+  const editor = process.env.VISUAL ?? process.env.EDITOR ?? "vi";
+  const result = spawnSync6(editor, files, { stdio: "inherit", shell: true });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
 async function run7() {
-  const args = parseArgs4(process.argv.slice(3));
+  const rawArgs = process.argv.slice(3);
+  if (rawArgs.length === 1 && rawArgs[0] === "--all") {
+    openAllConfigSpecialistsInEditor();
+    return;
+  }
+  const args = parseArgs4(rawArgs);
   const { name, field, value, dryRun, scope } = args;
   const loader = new SpecialistLoader;
   const all = await loader.list();
@@ -19767,7 +20322,7 @@ async function run7() {
     console.error(`  Run ${yellow6("specialists list")} to see available specialists`);
     process.exit(1);
   }
-  const raw = readFileSync4(match.filePath, "utf-8");
+  const raw = readFileSync6(match.filePath, "utf-8");
   const doc2 = $parseDocument(raw);
   const yamlPath = FIELD_MAP[field];
   let typedValue = value;
@@ -19817,168 +20372,178 @@ var init_edit = __esm(() => {
   VALID_PERMISSIONS = ["READ_ONLY", "LOW", "MEDIUM", "HIGH"];
 });
 
-// src/cli/run.ts
-var exports_run = {};
-__export(exports_run, {
+// src/cli/config.ts
+var exports_config = {};
+__export(exports_config, {
   run: () => run8
 });
-import { join as join11 } from "node:path";
-async function parseArgs5(argv) {
-  const name = argv[0];
-  if (!name || name.startsWith("--")) {
-    console.error('Usage: specialists|sp run <name> [--prompt "..."] [--bead <id>] [--context-depth <n>] [--model <model>] [--no-beads] [--keep-alive]');
-    process.exit(1);
+import { existsSync as existsSync12 } from "node:fs";
+import { readdir as readdir2, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
+import { basename as basename2, join as join16 } from "node:path";
+function usage() {
+  return [
+    "Usage:",
+    "  specialists config get <key> [--all] [--name <specialist>]",
+    "  specialists config set <key> <value> [--all] [--name <specialist>]",
+    "",
+    "Examples:",
+    "  specialists config get specialist.execution.stall_timeout_ms",
+    "  specialists config set specialist.execution.stall_timeout_ms 180000",
+    "  specialists config set specialist.execution.stall_timeout_ms 120000 --name executor"
+  ].join(`
+`);
+}
+function parseArgs5(argv) {
+  const command = argv[0];
+  if (command !== "get" && command !== "set") {
+    throw new ArgParseError3(usage());
   }
-  let prompt = "";
-  let beadId;
-  let model;
-  let noBeads = false;
-  let keepAlive = false;
-  let contextDepth = 1;
-  for (let i = 1;i < argv.length; i++) {
-    const token = argv[i];
-    if (token === "--prompt" && argv[i + 1]) {
-      prompt = argv[++i];
-      continue;
-    }
-    if (token === "--bead" && argv[i + 1]) {
-      beadId = argv[++i];
-      continue;
-    }
-    if (token === "--model" && argv[i + 1]) {
-      model = argv[++i];
-      continue;
-    }
-    if (token === "--context-depth" && argv[i + 1]) {
-      contextDepth = parseInt(argv[++i], 10) || 0;
-      continue;
+  const key = argv[1];
+  if (!key || key.startsWith("--")) {
+    throw new ArgParseError3(`Missing key
+
+${usage()}`);
+  }
+  let value;
+  let index = 2;
+  if (command === "set") {
+    value = argv[2];
+    if (value === undefined || value.startsWith("--")) {
+      throw new ArgParseError3(`Missing value for set
+
+${usage()}`);
     }
-    if (token === "--no-beads") {
-      noBeads = true;
+    index = 3;
+  }
+  let name;
+  let all = false;
+  for (let i = index;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--all") {
+      all = true;
       continue;
     }
-    if (token === "--keep-alive") {
-      keepAlive = true;
+    if (token === "--name") {
+      const next = argv[++i];
+      if (!next || next.startsWith("--")) {
+        throw new ArgParseError3("--name requires a specialist name");
+      }
+      name = next;
       continue;
     }
+    throw new ArgParseError3(`Unknown option: ${token}`);
   }
-  if (prompt && beadId) {
-    console.error("Error: use either --prompt or --bead, not both.");
-    process.exit(1);
+  if (name && all) {
+    throw new ArgParseError3("Use either --name or --all, not both");
   }
-  if (!prompt && !beadId && !process.stdin.isTTY) {
-    prompt = await new Promise((resolve2) => {
-      let buf = "";
-      process.stdin.setEncoding("utf-8");
-      process.stdin.on("data", (chunk) => {
-        buf += chunk;
-      });
-      process.stdin.on("end", () => resolve2(buf.trim()));
-    });
+  if (!name) {
+    all = true;
   }
-  if (!prompt && !beadId) {
-    console.error("Error: provide --prompt, pipe stdin, or use --bead <id>.");
-    process.exit(1);
+  return { command, key, value, name, all };
+}
+function splitKeyPath(key) {
+  const path = key.split(".").map((part) => part.trim()).filter(Boolean);
+  if (path.length === 0) {
+    throw new ArgParseError3(`Invalid key: ${key}`);
+  }
+  return path;
+}
+function getSpecialistDir(projectDir) {
+  return join16(projectDir, "config", "specialists");
+}
+function getSpecialistNameFromPath(path) {
+  return path.replace(/\.specialist\.yaml$/, "");
+}
+async function listSpecialistFiles(projectDir) {
+  const specialistDir = getSpecialistDir(projectDir);
+  if (!existsSync12(specialistDir)) {
+    throw new Error(`Missing directory: ${specialistDir}`);
+  }
+  const entries = await readdir2(specialistDir);
+  return entries.filter((entry) => entry.endsWith(".specialist.yaml")).sort((a, b) => a.localeCompare(b)).map((entry) => join16(specialistDir, entry));
+}
+async function findNamedSpecialistFile(projectDir, name) {
+  const path = join16(getSpecialistDir(projectDir), `${name}.specialist.yaml`);
+  if (!existsSync12(path)) {
+    throw new Error(`Specialist not found in config/specialists/: ${name}`);
+  }
+  return path;
+}
+function parseValue(rawValue) {
+  try {
+    return $parse(rawValue);
+  } catch {
+    return rawValue;
+  }
+}
+function formatValue(value) {
+  if (value === undefined)
+    return "<unset>";
+  if (typeof value === "string")
+    return value;
+  return JSON.stringify(value);
+}
+async function getAcrossFiles(files, keyPath) {
+  for (const file of files) {
+    const content = await readFile3(file, "utf-8");
+    const doc2 = $parseDocument(content);
+    const value = doc2.getIn(keyPath);
+    const name = getSpecialistNameFromPath(basename2(file));
+    console.log(`${yellow7(name)}: ${formatValue(value)}`);
+  }
+}
+async function setAcrossFiles(files, keyPath, rawValue) {
+  const typedValue = parseValue(rawValue);
+  for (const file of files) {
+    const content = await readFile3(file, "utf-8");
+    const doc2 = $parseDocument(content);
+    doc2.setIn(keyPath, typedValue);
+    await writeFile2(file, doc2.toString(), "utf-8");
   }
-  return { name, prompt, beadId, model, noBeads, keepAlive, contextDepth };
+  console.log(`${green6("✓")} updated ${files.length} specialist${files.length === 1 ? "" : "s"}: ` + `${keyPath.join(".")} = ${formatValue(typedValue)}`);
 }
 async function run8() {
-  const args = await parseArgs5(process.argv.slice(3));
-  const loader = new SpecialistLoader;
-  const circuitBreaker = new CircuitBreaker;
-  const hooks = new HookEmitter({ tracePath: join11(process.cwd(), ".specialists", "trace.jsonl") });
-  const beadsClient = args.noBeads ? undefined : new BeadsClient;
-  const beadReader = beadsClient ?? new BeadsClient;
-  let prompt = args.prompt;
-  let variables;
-  if (args.beadId) {
-    const bead = beadReader.readBead(args.beadId);
-    if (!bead) {
-      throw new Error(`Unable to read bead '${args.beadId}' via bd show --json`);
-    }
-    const blockers = args.contextDepth > 0 ? beadReader.getCompletedBlockers(args.beadId, args.contextDepth) : [];
-    if (blockers.length > 0) {
-      process.stderr.write(dim7(`
-[context: ${blockers.length} completed dep${blockers.length > 1 ? "s" : ""} injected]
-`));
+  let args;
+  try {
+    args = parseArgs5(process.argv.slice(3));
+  } catch (error2) {
+    if (error2 instanceof ArgParseError3) {
+      console.error(error2.message);
+      process.exit(1);
     }
-    const beadContext = buildBeadContext(bead, blockers);
-    prompt = beadContext;
-    variables = {
-      bead_context: beadContext,
-      bead_id: args.beadId
-    };
+    throw error2;
   }
-  const runner = new SpecialistRunner({
-    loader,
-    hooks,
-    circuitBreaker,
-    beadsClient
-  });
-  const jobsDir = join11(process.cwd(), ".specialists", "jobs");
-  const supervisor = new Supervisor({
-    runner,
-    runOptions: {
-      name: args.name,
-      prompt,
-      variables,
-      backendOverride: args.model,
-      inputBeadId: args.beadId,
-      keepAlive: args.keepAlive
-    },
-    jobsDir,
-    beadsClient,
-    onProgress: (delta) => process.stdout.write(delta),
-    onMeta: (meta) => process.stderr.write(dim7(`
-[${meta.backend} / ${meta.model}]
-
-`)),
-    onJobStarted: ({ id }) => process.stderr.write(dim7(`[job started: ${id}]
-`))
-  });
+  const keyPath = splitKeyPath(args.key);
+  const projectDir = process.cwd();
+  let files;
   try {
-    await loader.get(args.name);
-  } catch (err) {
-    process.stderr.write(`Error: ${err?.message ?? err}
-`);
+    files = args.name ? [await findNamedSpecialistFile(projectDir, args.name)] : await listSpecialistFiles(projectDir);
+  } catch (error2) {
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    console.error(message);
     process.exit(1);
+    return;
   }
-  process.stderr.write(`
-${bold7(`Running ${cyan4(args.name)}`)}
-
-`);
-  let jobId;
-  try {
-    jobId = await supervisor.run();
-  } catch (err) {
-    process.stderr.write(`Error: ${err?.message ?? err}
-`);
+  if (files.length === 0) {
+    console.error("No specialists found in config/specialists/");
     process.exit(1);
+    return;
   }
-  const status = supervisor.readStatus(jobId);
-  const secs = ((status?.last_event_at_ms ?? Date.now()) - (status?.started_at_ms ?? Date.now())) / 1000;
-  const footer = [
-    `job ${jobId}`,
-    status?.bead_id ? `bead ${status.bead_id}` : "",
-    `${secs.toFixed(1)}s`,
-    status?.model ? dim7(`${status.backend}/${status.model}`) : ""
-  ].filter(Boolean).join("  ");
-  process.stderr.write(`
-${green6("✓")} ${footer}
-
-`);
-  process.stderr.write(dim7(`Poll: specialists poll ${jobId} --json
-
-`));
-  process.exit(0);
+  if (args.command === "get") {
+    await getAcrossFiles(files, keyPath);
+    return;
+  }
+  await setAcrossFiles(files, keyPath, args.value);
 }
-var bold7 = (s) => `\x1B[1m${s}\x1B[0m`, dim7 = (s) => `\x1B[2m${s}\x1B[0m`, green6 = (s) => `\x1B[32m${s}\x1B[0m`, cyan4 = (s) => `\x1B[36m${s}\x1B[0m`;
-var init_run = __esm(() => {
-  init_loader();
-  init_runner();
-  init_hooks();
-  init_beads();
-  init_supervisor();
+var green6 = (s) => `\x1B[32m${s}\x1B[0m`, yellow7 = (s) => `\x1B[33m${s}\x1B[0m`, ArgParseError3;
+var init_config = __esm(() => {
+  init_dist();
+  ArgParseError3 = class ArgParseError3 extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "ArgParseError";
+    }
+  };
 });
 
 // src/cli/format-helpers.ts
@@ -20018,29 +20583,46 @@ class JobColorMap {
     return this.colors.size;
   }
 }
+function formatToolArgValue(value, maxLen = 240) {
+  const raw = typeof value === "string" ? value : JSON.stringify(value);
+  const flat = raw.replace(/\s+/g, " ").trim();
+  return flat.length > maxLen ? `${flat.slice(0, maxLen - 3)}...` : flat;
+}
+function formatToolDetail(event) {
+  const toolName = cyan4(event.tool);
+  if (event.phase === "start") {
+    if (typeof event.args?.command === "string") {
+      return `${toolName}: ${yellow8(formatToolArgValue(event.args.command))}`;
+    }
+    if (event.args && Object.keys(event.args).length > 0) {
+      const argStr = Object.entries(event.args).map(([k, v]) => `${k}=${formatToolArgValue(v)}`).join(" ");
+      return `${toolName}: ${dim7(argStr)}`;
+    }
+    return `${toolName}: ${dim7("start")}`;
+  }
+  if (event.phase === "end" && event.is_error) {
+    return `${toolName}: ${red2("error")}`;
+  }
+  return `${toolName}: ${dim7(event.phase)}`;
+}
 function formatEventLine(event, options) {
-  const ts = dim8(formatTime(event.t));
-  const label = options.colorize(bold8(getEventLabel(event.type).padEnd(5)));
-  const prefix = `${options.colorize(`[${options.jobId}]`)} ${options.specialist}${options.beadId ? ` ${dim8(`[${options.beadId}]`)}` : ""}`;
+  const ts = dim7(formatTime(event.t));
+  const job = options.colorize(`[${options.jobId}]`);
+  const bead = dim7(`[${options.beadId ?? "-"}]`);
+  const label = options.colorize(bold7(getEventLabel(event.type).padEnd(5)));
   const detailParts = [];
+  let detail = "";
   if (event.type === "meta") {
     detailParts.push(`model=${event.model}`);
     detailParts.push(`backend=${event.backend}`);
   } else if (event.type === "tool") {
-    detailParts.push(`tool=${event.tool}`);
-    detailParts.push(`phase=${event.phase}`);
-    if (event.phase === "end") {
-      detailParts.push(`ok=${event.is_error ? "false" : "true"}`);
-    }
+    detail = formatToolDetail(event);
   } else if (event.type === "run_complete") {
     detailParts.push(`status=${event.status}`);
     detailParts.push(`elapsed=${formatElapsed(event.elapsed_s)}`);
     if (event.error) {
       detailParts.push(`error=${event.error}`);
     }
-  } else if (event.type === "done" || event.type === "agent_end") {
-    detailParts.push("status=COMPLETE");
-    detailParts.push(`elapsed=${formatElapsed(event.elapsed_s ?? 0)}`);
   } else if (event.type === "run_start") {
     detailParts.push(`specialist=${event.specialist}`);
     if (event.bead_id) {
@@ -20056,54 +20638,396 @@ function formatEventLine(event, options) {
   } else if (event.type === "turn") {
     detailParts.push(`phase=${event.phase}`);
   }
-  const detail = detailParts.length > 0 ? dim8(detailParts.join(" ")) : "";
-  return `${ts} ${prefix}  ${label}${detail ? ` ${detail}` : ""}`.trimEnd();
+  if (!detail && detailParts.length > 0) {
+    detail = dim7(detailParts.join(" "));
+  }
+  return `${ts} ${job} ${bead} ${label} ${options.specialist}${detail ? ` ${detail}` : ""}`.trimEnd();
+}
+function formatEventInline(event) {
+  switch (event.type) {
+    case "meta":
+      return dim7(`[model] ${event.backend}/${event.model}`);
+    case "thinking":
+      return dim7("[thinking...]");
+    case "text":
+      return dim7("[response]");
+    case "tool": {
+      if (event.phase !== "start")
+        return null;
+      const firstArgVal = event.args ? Object.values(event.args)[0] : undefined;
+      const argStr = firstArgVal !== undefined ? ": " + (typeof firstArgVal === "string" ? firstArgVal.split(`
+`)[0].slice(0, 80) : JSON.stringify(firstArgVal).slice(0, 80)) : "";
+      return `${dim7("[tool]")}  ${cyan4(event.tool)}${dim7(argStr)}`;
+    }
+    case "stale_warning":
+      return yellow8(`[warning] ${event.reason}: ${Math.round(event.silence_ms / 1000)}s silent`);
+    default:
+      return null;
+  }
+}
+function formatEventInlineDebounced(event, activePhase) {
+  if (event.type === "thinking" || event.type === "text") {
+    if (activePhase === event.type) {
+      return { line: null, nextPhase: activePhase };
+    }
+    return { line: formatEventInline(event), nextPhase: event.type };
+  }
+  return {
+    line: formatEventInline(event),
+    nextPhase: null
+  };
+}
+var dim7 = (s) => `\x1B[2m${s}\x1B[0m`, bold7 = (s) => `\x1B[1m${s}\x1B[0m`, cyan4 = (s) => `\x1B[36m${s}\x1B[0m`, yellow8 = (s) => `\x1B[33m${s}\x1B[0m`, red2 = (s) => `\x1B[31m${s}\x1B[0m`, green7 = (s) => `\x1B[32m${s}\x1B[0m`, blue = (s) => `\x1B[34m${s}\x1B[0m`, magenta = (s) => `\x1B[35m${s}\x1B[0m`, JOB_COLORS, EVENT_LABELS;
+var init_format_helpers = __esm(() => {
+  JOB_COLORS = [cyan4, yellow8, magenta, green7, blue, red2];
+  EVENT_LABELS = {
+    run_start: "START",
+    meta: "META",
+    thinking: "THINK",
+    tool: "TOOL",
+    text: "TEXT",
+    message: "MSG",
+    turn: "TURN",
+    run_complete: "DONE",
+    error: "ERR"
+  };
+});
+
+// src/cli/run.ts
+var exports_run = {};
+__export(exports_run, {
+  run: () => run9
+});
+import { join as join17 } from "node:path";
+import { readFileSync as readFileSync7 } from "node:fs";
+import { spawn as cpSpawn } from "node:child_process";
+async function parseArgs6(argv) {
+  const name = argv[0];
+  if (!name || name.startsWith("--")) {
+    console.error('Usage: specialists|sp run <name> [--prompt "..."] [--bead <id>] [--context-depth <n>] [--model <model>] [--no-beads] [--no-bead-notes] [--keep-alive|--no-keep-alive] [--json|--raw]');
+    process.exit(1);
+  }
+  let prompt = "";
+  let beadId;
+  let model;
+  let noBeads = false;
+  let noBeadNotes = false;
+  let keepAlive;
+  let noKeepAlive = false;
+  let background = false;
+  let outputMode = "human";
+  let contextDepth = 1;
+  for (let i = 1;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--prompt" && argv[i + 1]) {
+      prompt = argv[++i];
+      continue;
+    }
+    if (token === "--bead" && argv[i + 1]) {
+      beadId = argv[++i];
+      continue;
+    }
+    if (token === "--model" && argv[i + 1]) {
+      model = argv[++i];
+      continue;
+    }
+    if (token === "--context-depth" && argv[i + 1]) {
+      contextDepth = parseInt(argv[++i], 10) || 0;
+      continue;
+    }
+    if (token === "--no-beads") {
+      noBeads = true;
+      continue;
+    }
+    if (token === "--no-bead-notes") {
+      noBeadNotes = true;
+      continue;
+    }
+    if (token === "--keep-alive") {
+      keepAlive = true;
+      noKeepAlive = false;
+      continue;
+    }
+    if (token === "--no-keep-alive") {
+      keepAlive = undefined;
+      noKeepAlive = true;
+      continue;
+    }
+    if (token === "--background") {
+      background = true;
+      continue;
+    }
+    if (token === "--json") {
+      outputMode = "json";
+      continue;
+    }
+    if (token === "--raw") {
+      outputMode = "raw";
+      continue;
+    }
+  }
+  if (prompt && beadId) {
+    console.error("Error: use either --prompt or --bead, not both.");
+    process.exit(1);
+  }
+  if (!prompt && !beadId && !process.stdin.isTTY) {
+    prompt = await new Promise((resolve2) => {
+      let buf = "";
+      process.stdin.setEncoding("utf-8");
+      process.stdin.on("data", (chunk) => {
+        buf += chunk;
+      });
+      process.stdin.on("end", () => resolve2(buf.trim()));
+    });
+  }
+  if (!prompt && !beadId) {
+    console.error("Error: provide --prompt, pipe stdin, or use --bead <id>.");
+    process.exit(1);
+  }
+  return { name, prompt, beadId, model, noBeads, noBeadNotes, keepAlive, noKeepAlive, background, contextDepth, outputMode };
+}
+function startEventTailer(jobId, jobsDir, mode, specialist, beadId) {
+  const eventsPath = join17(jobsDir, jobId, "events.jsonl");
+  let linesRead = 0;
+  let activeInlinePhase = null;
+  const drain = () => {
+    let content;
+    try {
+      content = readFileSync7(eventsPath, "utf-8");
+    } catch {
+      return;
+    }
+    if (!content)
+      return;
+    const lastNl = content.lastIndexOf(`
+`);
+    if (lastNl < 0)
+      return;
+    const complete = content.slice(0, lastNl);
+    const lines = complete.split(`
+`);
+    for (let i = linesRead;i < lines.length; i++) {
+      linesRead++;
+      const line = lines[i].trim();
+      if (!line)
+        continue;
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (mode === "json") {
+        process.stdout.write(JSON.stringify({ jobId, specialist, beadId, ...event }) + `
+`);
+      } else {
+        if (event.type === "run_complete" && event.output) {
+          activeInlinePhase = null;
+          process.stdout.write(`
+` + event.output + `
+`);
+        } else {
+          const { line: line2, nextPhase } = formatEventInlineDebounced(event, activeInlinePhase);
+          activeInlinePhase = nextPhase;
+          if (line2)
+            process.stdout.write(line2 + `
+`);
+        }
+      }
+    }
+  };
+  const intervalId = setInterval(drain, 100);
+  return () => {
+    clearInterval(intervalId);
+    drain();
+  };
+}
+function formatFooterModel(backend, model) {
+  if (!model)
+    return "";
+  if (!backend)
+    return model;
+  return model.startsWith(`${backend}/`) ? model : `${backend}/${model}`;
+}
+async function run9() {
+  const args = await parseArgs6(process.argv.slice(3));
+  if (args.background) {
+    const latestPath = join17(process.cwd(), ".specialists", "jobs", "latest");
+    const oldLatest = (() => {
+      try {
+        return readFileSync7(latestPath, "utf-8").trim();
+      } catch {
+        return "";
+      }
+    })();
+    const childArgs = process.argv.slice(2).filter((a) => a !== "--background");
+    const child = cpSpawn(process.execPath, [process.argv[1], ...childArgs], {
+      detached: true,
+      stdio: "ignore",
+      cwd: process.cwd(),
+      env: process.env
+    });
+    child.unref();
+    const deadline = Date.now() + 5000;
+    let jobId2 = "";
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 100));
+      try {
+        const current = readFileSync7(latestPath, "utf-8").trim();
+        if (current && current !== oldLatest) {
+          jobId2 = current;
+          break;
+        }
+      } catch {}
+    }
+    if (jobId2) {
+      process.stdout.write(`${jobId2}
+`);
+    } else {
+      process.stderr.write(`Warning: job started but ID not yet available. Check specialists status.
+`);
+      process.stdout.write(`${child.pid}
+`);
+    }
+    process.exit(0);
+  }
+  const loader = new SpecialistLoader;
+  const circuitBreaker = new CircuitBreaker;
+  const hooks = new HookEmitter({ tracePath: join17(process.cwd(), ".specialists", "trace.jsonl") });
+  const beadsClient = args.noBeads ? undefined : new BeadsClient;
+  const beadReader = beadsClient ?? new BeadsClient;
+  let prompt = args.prompt;
+  let variables;
+  if (args.beadId) {
+    const bead = beadReader.readBead(args.beadId);
+    if (!bead) {
+      throw new Error(`Unable to read bead '${args.beadId}' via bd show --json`);
+    }
+    const blockers = args.contextDepth > 0 ? beadReader.getCompletedBlockers(args.beadId, args.contextDepth) : [];
+    if (blockers.length > 0) {
+      process.stderr.write(dim8(`
+[context: ${blockers.length} completed dep${blockers.length > 1 ? "s" : ""} injected]
+`));
+    }
+    const beadContext = buildBeadContext(bead, blockers);
+    prompt = beadContext;
+    variables = {
+      bead_context: beadContext,
+      bead_id: args.beadId
+    };
+  }
+  const specialist = await loader.get(args.name).catch((err) => {
+    process.stderr.write(`Error: ${err?.message ?? err}
+`);
+    process.exit(1);
+  });
+  const runner = new SpecialistRunner({
+    loader,
+    hooks,
+    circuitBreaker,
+    beadsClient
+  });
+  const beadsWriteNotes = args.noBeadNotes ? false : specialist.specialist.beads_write_notes ?? true;
+  const jobsDir = join17(process.cwd(), ".specialists", "jobs");
+  let stopTailer;
+  const supervisor = new Supervisor({
+    runner,
+    runOptions: {
+      name: args.name,
+      prompt,
+      variables,
+      backendOverride: args.model,
+      inputBeadId: args.beadId,
+      keepAlive: args.keepAlive,
+      noKeepAlive: args.noKeepAlive,
+      beadsWriteNotes
+    },
+    jobsDir,
+    beadsClient,
+    stallDetection: specialist.specialist.stall_detection,
+    onProgress: args.outputMode === "raw" ? (delta) => process.stdout.write(delta) : undefined,
+    onMeta: args.outputMode !== "human" ? (meta) => process.stderr.write(dim8(`
+[${meta.backend} / ${meta.model}]
+
+`)) : undefined,
+    onJobStarted: ({ id }) => {
+      process.stderr.write(dim8(`[job started: ${id}]
+`));
+      if (args.outputMode !== "raw") {
+        stopTailer = startEventTailer(id, jobsDir, args.outputMode, args.name, args.beadId);
+      }
+    }
+  });
+  process.stderr.write(`
+${bold8(`Running ${cyan5(args.name)}`)}
+
+`);
+  let jobId;
+  try {
+    jobId = await supervisor.run();
+  } catch (err) {
+    stopTailer?.();
+    process.stderr.write(`Error: ${err?.message ?? err}
+`);
+    process.exit(1);
+  }
+  stopTailer?.();
+  const status = supervisor.readStatus(jobId);
+  const secs = ((status?.last_event_at_ms ?? Date.now()) - (status?.started_at_ms ?? Date.now())) / 1000;
+  const modelLabel = formatFooterModel(status?.backend, status?.model);
+  const footer = [
+    `job ${jobId}`,
+    status?.bead_id ? `bead ${status.bead_id}` : "",
+    `${secs.toFixed(1)}s`,
+    modelLabel ? dim8(modelLabel) : ""
+  ].filter(Boolean).join("  ");
+  process.stderr.write(`
+${green8("✓")} ${footer}
+
+`);
+  process.stderr.write(dim8(`Poll: specialists poll ${jobId} --json
+
+`));
+  process.exit(0);
 }
-var dim8 = (s) => `\x1B[2m${s}\x1B[0m`, bold8 = (s) => `\x1B[1m${s}\x1B[0m`, cyan5 = (s) => `\x1B[36m${s}\x1B[0m`, yellow7 = (s) => `\x1B[33m${s}\x1B[0m`, red2 = (s) => `\x1B[31m${s}\x1B[0m`, green7 = (s) => `\x1B[32m${s}\x1B[0m`, blue = (s) => `\x1B[34m${s}\x1B[0m`, magenta = (s) => `\x1B[35m${s}\x1B[0m`, JOB_COLORS, EVENT_LABELS;
-var init_format_helpers = __esm(() => {
-  JOB_COLORS = [cyan5, yellow7, magenta, green7, blue, red2];
-  EVENT_LABELS = {
-    run_start: "START",
-    meta: "META",
-    thinking: "THINK",
-    tool: "TOOL",
-    text: "TEXT",
-    message: "MSG",
-    turn: "TURN",
-    run_complete: "DONE",
-    done: "DONE",
-    agent_end: "DONE",
-    error: "ERR"
-  };
+var bold8 = (s) => `\x1B[1m${s}\x1B[0m`, dim8 = (s) => `\x1B[2m${s}\x1B[0m`, green8 = (s) => `\x1B[32m${s}\x1B[0m`, cyan5 = (s) => `\x1B[36m${s}\x1B[0m`;
+var init_run = __esm(() => {
+  init_loader();
+  init_runner();
+  init_circuitBreaker();
+  init_hooks();
+  init_beads();
+  init_supervisor();
+  init_format_helpers();
 });
 
 // src/cli/status.ts
 var exports_status = {};
 __export(exports_status, {
-  run: () => run9
+  run: () => run10
 });
-import { spawnSync as spawnSync6 } from "node:child_process";
-import { existsSync as existsSync9 } from "node:fs";
-import { join as join12 } from "node:path";
+import { spawnSync as spawnSync7 } from "node:child_process";
+import { existsSync as existsSync13, readFileSync as readFileSync8 } from "node:fs";
+import { join as join18 } from "node:path";
 function ok2(msg) {
   console.log(`  ${green7("✓")} ${msg}`);
 }
 function warn(msg) {
-  console.log(`  ${yellow7("○")} ${msg}`);
+  console.log(`  ${yellow8("○")} ${msg}`);
 }
 function fail(msg) {
   console.log(`  ${red2("✗")} ${msg}`);
 }
 function info(msg) {
-  console.log(`  ${dim8(msg)}`);
+  console.log(`  ${dim7(msg)}`);
 }
 function section(label) {
   const line = "─".repeat(Math.max(0, 38 - label.length));
   console.log(`
-${bold8(`── ${label} ${line}`)}`);
+${bold7(`── ${label} ${line}`)}`);
 }
 function cmd(bin, args) {
-  const r = spawnSync6(bin, args, {
+  const r = spawnSync7(bin, args, {
     encoding: "utf8",
     stdio: "pipe",
     timeout: 5000
@@ -20111,7 +21035,7 @@ function cmd(bin, args) {
   return { ok: r.status === 0 && !r.error, stdout: (r.stdout ?? "").trim() };
 }
 function isInstalled(bin) {
-  return spawnSync6("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
+  return spawnSync7("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
 }
 function formatElapsed2(s) {
   if (s.elapsed_s === undefined)
@@ -20123,20 +21047,83 @@ function formatElapsed2(s) {
 function statusColor(status) {
   switch (status) {
     case "running":
-      return cyan5(status);
+      return cyan4(status);
     case "done":
       return green7(status);
     case "error":
       return red2(status);
     case "starting":
-      return yellow7(status);
+      return yellow8(status);
     default:
       return status;
   }
 }
-async function run9() {
+function parseStatusArgs(argv) {
+  let jsonMode = false;
+  let jobId;
+  for (let i = 0;i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      jsonMode = true;
+      continue;
+    }
+    if (arg === "--job") {
+      const candidate = argv[i + 1];
+      if (!candidate || candidate.startsWith("--")) {
+        throw new Error("--job requires a value");
+      }
+      jobId = candidate;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--job=")) {
+      const candidate = arg.slice("--job=".length).trim();
+      if (!candidate) {
+        throw new Error("--job requires a value");
+      }
+      jobId = candidate;
+    }
+  }
+  return { jsonMode, jobId };
+}
+function countJobEvents(jobsDir, jobId) {
+  const eventsFile = join18(jobsDir, jobId, "events.jsonl");
+  if (!existsSync13(eventsFile))
+    return 0;
+  const raw = readFileSync8(eventsFile, "utf-8").trim();
+  if (!raw)
+    return 0;
+  return raw.split(`
+`).filter((line) => line.trim().length > 0).length;
+}
+function renderJobDetail(job, eventCount) {
+  console.log(`
+${bold7("specialists status")}
+`);
+  section(`Job ${job.id}`);
+  console.log(`  specialist   ${job.specialist}`);
+  console.log(`  status       ${statusColor(job.status)}`);
+  console.log(`  model        ${job.model ?? "n/a"}`);
+  console.log(`  backend      ${job.backend ?? "n/a"}`);
+  console.log(`  elapsed      ${formatElapsed2(job)}`);
+  console.log(`  bead_id      ${job.bead_id ?? "n/a"}`);
+  console.log(`  events       ${eventCount}`);
+  if (job.session_file)
+    console.log(`  session_file ${job.session_file}`);
+  if (job.error)
+    console.log(`  error        ${red2(job.error)}`);
+  console.log();
+}
+async function run10() {
   const argv = process.argv.slice(3);
-  const jsonMode = argv.includes("--json");
+  let parsedArgs;
+  try {
+    parsedArgs = parseStatusArgs(argv);
+  } catch (error2) {
+    console.error(red2(error2.message));
+    process.exit(1);
+  }
+  const { jsonMode, jobId } = parsedArgs;
   const loader = new SpecialistLoader;
   const allSpecialists = await loader.list();
   const piInstalled = isInstalled("pi");
@@ -20146,18 +21133,42 @@ async function run9() {
 `).slice(1).map((line) => line.split(/\s+/)[0]).filter(Boolean)) : new Set;
   const bdInstalled = isInstalled("bd");
   const bdVersion = bdInstalled ? cmd("bd", ["--version"]) : null;
-  const beadsPresent = existsSync9(join12(process.cwd(), ".beads"));
+  const beadsPresent = existsSync13(join18(process.cwd(), ".beads"));
   const specialistsBin = cmd("which", ["specialists"]);
-  const jobsDir = join12(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join18(process.cwd(), ".specialists", "jobs");
   let jobs = [];
-  if (existsSync9(jobsDir)) {
-    const supervisor = new Supervisor({
+  let supervisor = null;
+  if (existsSync13(jobsDir)) {
+    supervisor = new Supervisor({
       runner: null,
       runOptions: null,
       jobsDir
     });
     jobs = supervisor.listJobs();
   }
+  if (jobId) {
+    const selectedJob = supervisor?.readStatus(jobId) ?? null;
+    if (!selectedJob) {
+      if (jsonMode) {
+        console.log(JSON.stringify({ error: `Job not found: ${jobId}` }, null, 2));
+      } else {
+        fail(`job not found: ${jobId}`);
+      }
+      process.exit(1);
+    }
+    const eventCount = countJobEvents(jobsDir, jobId);
+    if (jsonMode) {
+      console.log(JSON.stringify({
+        job: {
+          ...selectedJob,
+          event_count: eventCount
+        }
+      }, null, 2));
+      return;
+    }
+    renderJobDetail(selectedJob, eventCount);
+    return;
+  }
   const stalenessMap = {};
   for (const s of allSpecialists) {
     stalenessMap[s.name] = await checkStaleness(s);
@@ -20201,51 +21212,51 @@ async function run9() {
     return;
   }
   console.log(`
-${bold8("specialists status")}
+${bold7("specialists status")}
 `);
   section("Specialists");
   if (allSpecialists.length === 0) {
-    warn(`no specialists found — run ${yellow7("specialists init")} to scaffold`);
+    warn(`no specialists found — run ${yellow8("specialists init")} to scaffold`);
   } else {
     const byScope = allSpecialists.reduce((acc, s) => {
       acc[s.scope] = (acc[s.scope] ?? 0) + 1;
       return acc;
     }, {});
     const scopeSummary = Object.entries(byScope).map(([scope, n]) => `${n} ${scope}`).join(", ");
-    ok2(`${allSpecialists.length} found  ${dim8(`(${scopeSummary})`)}`);
+    ok2(`${allSpecialists.length} found  ${dim7(`(${scopeSummary})`)}`);
     for (const s of allSpecialists) {
       const staleness = stalenessMap[s.name];
       if (staleness === "AGED") {
-        warn(`${s.name}  ${red2("AGED")}  ${dim8(s.scope)}`);
+        warn(`${s.name}  ${red2("AGED")}  ${dim7(s.scope)}`);
       } else if (staleness === "STALE") {
-        warn(`${s.name}  ${yellow7("STALE")}  ${dim8(s.scope)}`);
+        warn(`${s.name}  ${yellow8("STALE")}  ${dim7(s.scope)}`);
       }
     }
   }
   section("pi  (coding agent runtime)");
   if (!piInstalled) {
-    fail(`pi not installed — install ${yellow7("pi")} first`);
+    fail(`pi not installed — install ${yellow8("pi")} first`);
   } else {
     const vStr = piVersion?.ok ? `v${piVersion.stdout}` : "unknown version";
-    const pStr = piProviders.size > 0 ? `${piProviders.size} provider${piProviders.size > 1 ? "s" : ""} active  ${dim8(`(${[...piProviders].join(", ")})`)} ` : yellow7("no providers configured — run pi config");
+    const pStr = piProviders.size > 0 ? `${piProviders.size} provider${piProviders.size > 1 ? "s" : ""} active  ${dim7(`(${[...piProviders].join(", ")})`)} ` : yellow8("no providers configured — run pi config");
     ok2(`${vStr}  —  ${pStr}`);
   }
   section("beads  (issue tracker)");
   if (!bdInstalled) {
-    fail(`bd not installed — install ${yellow7("bd")} first`);
+    fail(`bd not installed — install ${yellow8("bd")} first`);
   } else {
-    ok2(`bd installed${bdVersion?.ok ? `  ${dim8(bdVersion.stdout)}` : ""}`);
+    ok2(`bd installed${bdVersion?.ok ? `  ${dim7(bdVersion.stdout)}` : ""}`);
     if (beadsPresent) {
       ok2(".beads/ present in project");
     } else {
-      warn(`.beads/ not found — run ${yellow7("bd init")} to enable issue tracking`);
+      warn(`.beads/ not found — run ${yellow8("bd init")} to enable issue tracking`);
     }
   }
   section("MCP");
   if (!specialistsBin.ok) {
-    fail(`specialists not installed globally — run ${yellow7("npm install -g @jaggerxtrm/specialists")}`);
+    fail(`specialists not installed globally — run ${yellow8("npm install -g @jaggerxtrm/specialists")}`);
   } else {
-    ok2(`specialists binary installed  ${dim8(specialistsBin.stdout)}`);
+    ok2(`specialists binary installed  ${dim7(specialistsBin.stdout)}`);
     info(`verify registration: claude mcp get specialists`);
     info(`re-register:         specialists install`);
   }
@@ -20255,8 +21266,8 @@ ${bold8("specialists status")}
   } else {
     for (const job of jobs) {
       const elapsed = formatElapsed2(job);
-      const detail = job.status === "error" ? red2(job.error?.slice(0, 40) ?? "error") : job.current_tool ? dim8(`tool: ${job.current_tool}`) : dim8(job.current_event ?? "");
-      console.log(`  ${dim8(job.id)}  ${job.specialist.padEnd(20)}  ${statusColor(job.status).padEnd(7)}  ${elapsed.padStart(6)}  ${detail}`);
+      const detail = job.status === "error" ? red2(job.error?.slice(0, 40) ?? "error") : job.current_tool ? dim7(`tool: ${job.current_tool}`) : dim7(job.current_event ?? "");
+      console.log(`  ${dim7(job.id)}  ${job.specialist.padEnd(20)}  ${statusColor(job.status).padEnd(7)}  ${elapsed.padStart(6)}  ${detail}`);
     }
   }
   console.log();
@@ -20270,33 +21281,88 @@ var init_status = __esm(() => {
 // src/cli/result.ts
 var exports_result = {};
 __export(exports_result, {
-  run: () => run10
+  run: () => run11
 });
-import { existsSync as existsSync10, readFileSync as readFileSync5 } from "node:fs";
-import { join as join13 } from "node:path";
-async function run10() {
-  const jobId = process.argv[3];
-  if (!jobId) {
-    console.error("Usage: specialists|sp result <job-id>");
+import { existsSync as existsSync14, readFileSync as readFileSync9 } from "node:fs";
+import { join as join19 } from "node:path";
+function parseArgs7(argv) {
+  const jobId = argv[0];
+  if (!jobId || jobId.startsWith("--")) {
+    console.error("Usage: specialists|sp result <job-id> [--wait] [--timeout <seconds>]");
     process.exit(1);
   }
-  const jobsDir = join13(process.cwd(), ".specialists", "jobs");
+  let wait = false;
+  let timeout;
+  for (let i = 1;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--wait") {
+      wait = true;
+      continue;
+    }
+    if (token === "--timeout" && argv[i + 1]) {
+      const parsed = parseInt(argv[++i], 10);
+      if (isNaN(parsed) || parsed <= 0) {
+        console.error("Error: --timeout must be a positive integer (seconds)");
+        process.exit(1);
+      }
+      timeout = parsed;
+      continue;
+    }
+  }
+  return { jobId, wait, timeout };
+}
+async function run11() {
+  const args = parseArgs7(process.argv.slice(3));
+  const { jobId } = args;
+  const jobsDir = join19(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
+  const resultPath = join19(jobsDir, jobId, "result.txt");
+  if (args.wait) {
+    const startMs = Date.now();
+    while (true) {
+      const status2 = supervisor.readStatus(jobId);
+      if (!status2) {
+        console.error(`No job found: ${jobId}`);
+        process.exit(1);
+      }
+      if (status2.status === "done") {
+        if (!existsSync14(resultPath)) {
+          console.error(`Result file not found for job ${jobId}`);
+          process.exit(1);
+        }
+        process.stdout.write(readFileSync9(resultPath, "utf-8"));
+        return;
+      }
+      if (status2.status === "error") {
+        process.stderr.write(`${red3(`Job ${jobId} failed:`)} ${status2.error ?? "unknown error"}
+`);
+        process.exit(1);
+      }
+      if (args.timeout !== undefined) {
+        const elapsedSecs = (Date.now() - startMs) / 1000;
+        if (elapsedSecs >= args.timeout) {
+          process.stderr.write(`Timeout: job ${jobId} did not complete within ${args.timeout}s
+`);
+          process.exit(1);
+        }
+      }
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+  }
   const status = supervisor.readStatus(jobId);
   if (!status) {
     console.error(`No job found: ${jobId}`);
     process.exit(1);
   }
-  const resultPath = join13(jobsDir, jobId, "result.txt");
   if (status.status === "running" || status.status === "starting") {
-    if (!existsSync10(resultPath)) {
+    if (!existsSync14(resultPath)) {
       process.stderr.write(`${dim9(`Job ${jobId} is still ${status.status}. Use 'specialists feed --job ${jobId}' to follow.`)}
 `);
       process.exit(1);
     }
     process.stderr.write(`${dim9(`Job ${jobId} is currently ${status.status}. Showing last completed output while it continues.`)}
 `);
-    process.stdout.write(readFileSync5(resultPath, "utf-8"));
+    process.stdout.write(readFileSync9(resultPath, "utf-8"));
     return;
   }
   if (status.status === "error") {
@@ -20304,130 +21370,30 @@ async function run10() {
 `);
     process.exit(1);
   }
-  if (!existsSync10(resultPath)) {
+  if (!existsSync14(resultPath)) {
     console.error(`Result file not found for job ${jobId}`);
     process.exit(1);
   }
-  process.stdout.write(readFileSync5(resultPath, "utf-8"));
+  process.stdout.write(readFileSync9(resultPath, "utf-8"));
 }
 var dim9 = (s) => `\x1B[2m${s}\x1B[0m`, red3 = (s) => `\x1B[31m${s}\x1B[0m`;
 var init_result = __esm(() => {
   init_supervisor();
 });
 
-// src/specialist/timeline-query.ts
-import { existsSync as existsSync11, readdirSync as readdirSync3, readFileSync as readFileSync6 } from "node:fs";
-import { join as join14 } from "node:path";
-function readJobEvents(jobDir) {
-  const eventsPath = join14(jobDir, "events.jsonl");
-  if (!existsSync11(eventsPath))
-    return [];
-  const content = readFileSync6(eventsPath, "utf-8");
-  const lines = content.split(`
-`).filter(Boolean);
-  const events = [];
-  for (const line of lines) {
-    const event = parseTimelineEvent(line);
-    if (event)
-      events.push(event);
-  }
-  events.sort(compareTimelineEvents);
-  return events;
-}
-function readJobEventsById(jobsDir, jobId) {
-  return readJobEvents(join14(jobsDir, jobId));
-}
-function readAllJobEvents(jobsDir) {
-  if (!existsSync11(jobsDir))
-    return [];
-  const batches = [];
-  const entries = readdirSync3(jobsDir);
-  for (const entry of entries) {
-    const jobDir = join14(jobsDir, entry);
-    try {
-      const stat2 = __require("node:fs").statSync(jobDir);
-      if (!stat2.isDirectory())
-        continue;
-    } catch {
-      continue;
-    }
-    const jobId = entry;
-    const statusPath = join14(jobDir, "status.json");
-    let specialist = "unknown";
-    let beadId;
-    if (existsSync11(statusPath)) {
-      try {
-        const status = JSON.parse(readFileSync6(statusPath, "utf-8"));
-        specialist = status.specialist ?? "unknown";
-        beadId = status.bead_id;
-      } catch {}
-    }
-    const events = readJobEvents(jobDir);
-    if (events.length > 0) {
-      batches.push({ jobId, specialist, beadId, events });
-    }
-  }
-  return batches;
-}
-function mergeTimelineEvents(batches) {
-  const merged = [];
-  for (const batch of batches) {
-    for (const event of batch.events) {
-      merged.push({
-        jobId: batch.jobId,
-        specialist: batch.specialist,
-        beadId: batch.beadId,
-        event
-      });
-    }
-  }
-  merged.sort((a, b) => compareTimelineEvents(a.event, b.event));
-  return merged;
-}
-function filterTimelineEvents(merged, filter) {
-  let result = merged;
-  if (filter.since !== undefined) {
-    result = result.filter(({ event }) => event.t >= filter.since);
-  }
-  if (filter.jobId !== undefined) {
-    result = result.filter(({ jobId }) => jobId === filter.jobId);
-  }
-  if (filter.specialist !== undefined) {
-    result = result.filter(({ specialist }) => specialist === filter.specialist);
-  }
-  if (filter.limit !== undefined && filter.limit > 0) {
-    result = result.slice(0, filter.limit);
-  }
-  return result;
-}
-function queryTimeline(jobsDir, filter = {}) {
-  let batches = readAllJobEvents(jobsDir);
-  if (filter.jobId !== undefined) {
-    batches = batches.filter((b) => b.jobId === filter.jobId);
-  }
-  if (filter.specialist !== undefined) {
-    batches = batches.filter((b) => b.specialist === filter.specialist);
-  }
-  const merged = mergeTimelineEvents(batches);
-  return filterTimelineEvents(merged, filter);
-}
-var init_timeline_query = __esm(() => {
-  init_timeline_events();
-});
-
 // src/cli/feed.ts
 var exports_feed = {};
 __export(exports_feed, {
-  run: () => run11
+  run: () => run12
 });
-import { existsSync as existsSync12 } from "node:fs";
-import { join as join15 } from "node:path";
+import { existsSync as existsSync15, readFileSync as readFileSync10 } from "node:fs";
+import { join as join20 } from "node:path";
 function getHumanEventKey(event) {
   switch (event.type) {
     case "meta":
       return `meta:${event.backend}:${event.model}`;
     case "tool":
-      return `tool:${event.tool}:${event.phase}:${event.is_error ? "error" : "ok"}`;
+      return `tool:${event.tool}:${event.phase}:${event.tool_call_id ?? event.t}`;
     case "text":
       return "text";
     case "thinking":
@@ -20440,13 +21406,21 @@ function getHumanEventKey(event) {
       return `run_start:${event.specialist}:${event.bead_id ?? ""}`;
     case "run_complete":
       return `run_complete:${event.status}:${event.error ?? ""}`;
-    case "done":
-    case "agent_end":
-      return `complete:${event.type}`;
     default:
       return event.type;
   }
 }
+function shouldRenderHumanEvent(event) {
+  if (event.type === "message" || event.type === "turn")
+    return false;
+  if (event.type === "tool") {
+    if (event.phase === "update")
+      return false;
+    if (event.phase === "end" && !event.is_error)
+      return false;
+  }
+  return true;
+}
 function shouldSkipHumanEvent(event, jobId, lastPrintedEventKey, seenMetaKey) {
   if (event.type === "meta") {
     const metaKey = `${event.backend}:${event.model}`;
@@ -20454,6 +21428,9 @@ function shouldSkipHumanEvent(event, jobId, lastPrintedEventKey, seenMetaKey) {
       return true;
     seenMetaKey.set(jobId, metaKey);
   }
+  if (event.type === "tool") {
+    return false;
+  }
   const key = getHumanEventKey(event);
   if (lastPrintedEventKey.get(jobId) === key)
     return true;
@@ -20473,7 +21450,36 @@ function parseSince(value) {
   }
   return;
 }
-function parseArgs6(argv) {
+function isTerminalJobStatus(jobsDir, jobId) {
+  const statusPath = join20(jobsDir, jobId, "status.json");
+  try {
+    const status = JSON.parse(readFileSync10(statusPath, "utf-8"));
+    return status.status === "done" || status.status === "error";
+  } catch {
+    return false;
+  }
+}
+function makeJobMetaReader(jobsDir) {
+  const cache = new Map;
+  return (jobId) => {
+    if (cache.has(jobId))
+      return cache.get(jobId);
+    const statusPath = join20(jobsDir, jobId, "status.json");
+    let meta = { startedAtMs: Date.now() };
+    try {
+      const status = JSON.parse(readFileSync10(statusPath, "utf-8"));
+      meta = {
+        model: status.model,
+        backend: status.backend,
+        beadId: status.bead_id,
+        startedAtMs: status.started_at_ms ?? Date.now()
+      };
+    } catch {}
+    cache.set(jobId, meta);
+    return meta;
+  };
+}
+function parseArgs8(argv) {
   let jobId;
   let specialist;
   let since;
@@ -20515,33 +21521,52 @@ function parseArgs6(argv) {
   }
   return { jobId, specialist, since, limit, follow, forever, json };
 }
-function printSnapshot(merged, options) {
+function printSnapshot(merged, options, jobsDir) {
   if (merged.length === 0) {
     if (!options.json)
-      console.log(dim8("No events found."));
+      console.log(dim7("No events found."));
     return;
   }
   const colorMap = new JobColorMap;
   if (options.json) {
+    const getJobMeta2 = jobsDir ? makeJobMetaReader(jobsDir) : () => ({ startedAtMs: Date.now() });
     for (const { jobId, specialist, beadId, event } of merged) {
-      console.log(JSON.stringify({ jobId, specialist, beadId, ...event }));
+      const meta = getJobMeta2(jobId);
+      const model = meta.model ?? (event.type === "meta" ? event.model : undefined);
+      const backend = meta.backend ?? (event.type === "meta" ? event.backend : undefined);
+      console.log(JSON.stringify({
+        jobId,
+        specialist,
+        specialist_model: formatSpecialistModel(specialist, model),
+        model,
+        backend,
+        beadId: meta.beadId ?? beadId,
+        elapsed_ms: Date.now() - meta.startedAtMs,
+        ...event
+      }));
     }
     return;
   }
   const lastPrintedEventKey = new Map;
   const seenMetaKey = new Map;
+  const getJobMeta = jobsDir ? makeJobMetaReader(jobsDir) : () => ({ startedAtMs: Date.now() });
   for (const { jobId, specialist, beadId, event } of merged) {
+    if (!shouldRenderHumanEvent(event))
+      continue;
     if (shouldSkipHumanEvent(event, jobId, lastPrintedEventKey, seenMetaKey))
       continue;
     const colorize = colorMap.get(jobId);
-    console.log(formatEventLine(event, { jobId, specialist, beadId, colorize }));
+    const meta = getJobMeta(jobId);
+    const specialistDisplay = formatSpecialistModel(specialist, meta.model ?? (event.type === "meta" ? event.model : undefined));
+    console.log(formatEventLine(event, { jobId, specialist: specialistDisplay, beadId, colorize }));
   }
 }
 function isCompletionEvent(event) {
-  return isRunCompleteEvent(event) || event.type === "done" || event.type === "agent_end";
+  return isRunCompleteEvent(event);
 }
 async function followMerged(jobsDir, options) {
   const colorMap = new JobColorMap;
+  const getJobMeta = makeJobMetaReader(jobsDir);
   const lastSeenT = new Map;
   const completedJobs = new Set;
   const filteredBatches = () => readAllJobEvents(jobsDir).filter((batch) => !options.jobId || batch.jobId === options.jobId).filter((batch) => !options.specialist || batch.specialist === options.specialist);
@@ -20551,26 +21576,26 @@ async function followMerged(jobsDir, options) {
     since: options.since,
     limit: options.limit
   });
-  printSnapshot(initial, { ...options, json: options.json });
+  printSnapshot(initial, { ...options, json: options.json }, jobsDir);
   for (const batch of filteredBatches()) {
     if (batch.events.length > 0) {
       const maxT = Math.max(...batch.events.map((event) => event.t));
       lastSeenT.set(batch.jobId, maxT);
     }
-    if (batch.events.some(isCompletionEvent)) {
+    if (batch.events.some(isCompletionEvent) || isTerminalJobStatus(jobsDir, batch.jobId)) {
       completedJobs.add(batch.jobId);
     }
   }
   const initialBatchCount = filteredBatches().length;
   if (!options.forever && initialBatchCount > 0 && completedJobs.size === initialBatchCount) {
     if (!options.json) {
-      process.stderr.write(dim8(`All jobs complete.
+      process.stderr.write(dim7(`All jobs complete.
 `));
     }
     return;
   }
   if (!options.json) {
-    process.stderr.write(dim8(`Following... (Ctrl+C to stop)
+    process.stderr.write(dim7(`Following... (Ctrl+C to stop)
 `));
   }
   const lastPrintedEventKey = new Map;
@@ -20595,19 +21620,34 @@ async function followMerged(jobsDir, options) {
           const maxT = Math.max(...batch.events.map((e) => e.t));
           lastSeenT.set(batch.jobId, maxT);
         }
-        if (batch.events.some(isCompletionEvent)) {
+        if (batch.events.some(isCompletionEvent) || isTerminalJobStatus(jobsDir, batch.jobId)) {
           completedJobs.add(batch.jobId);
         }
       }
       newEvents.sort((a, b) => a.event.t - b.event.t);
       for (const { jobId, specialist, beadId, event } of newEvents) {
+        const meta = getJobMeta(jobId);
+        const model = meta.model ?? (event.type === "meta" ? event.model : undefined);
+        const backend = meta.backend ?? (event.type === "meta" ? event.backend : undefined);
         if (options.json) {
-          console.log(JSON.stringify({ jobId, specialist, beadId, ...event }));
+          console.log(JSON.stringify({
+            jobId,
+            specialist,
+            specialist_model: formatSpecialistModel(specialist, model),
+            model,
+            backend,
+            beadId: meta.beadId ?? beadId,
+            elapsed_ms: Date.now() - meta.startedAtMs,
+            ...event
+          }));
         } else {
+          if (!shouldRenderHumanEvent(event))
+            continue;
           if (shouldSkipHumanEvent(event, jobId, lastPrintedEventKey, seenMetaKey))
             continue;
           const colorize = colorMap.get(jobId);
-          console.log(formatEventLine(event, { jobId, specialist, beadId, colorize }));
+          const specialistDisplay = formatSpecialistModel(specialist, model);
+          console.log(formatEventLine(event, { jobId, specialist: specialistDisplay, beadId, colorize }));
         }
       }
       if (!options.forever && batches.length > 0 && completedJobs.size === batches.length) {
@@ -20617,37 +21657,11 @@ async function followMerged(jobsDir, options) {
     }, 500);
   });
 }
-function showUsage() {
-  console.log(`Usage: specialists feed <job-id> [options]
-       specialists feed -f [--forever]
-
-Read background job events.
-
-Modes:
-  specialists feed <job-id>        Replay events for one job
-  specialists feed <job-id> -f     Follow one job until completion
-  specialists feed -f              Follow all jobs globally
-
-Options:
-  -f, --follow   Follow live updates
-  --forever      Keep following in global mode even when all jobs complete
-
-Examples:
-  specialists feed 49adda
-  specialists feed 49adda --follow
-  specialists feed -f
-  specialists feed -f --forever
-`);
-}
-async function run11() {
-  const options = parseArgs6(process.argv.slice(3));
-  if (!options.jobId && !options.follow) {
-    showUsage();
-    process.exit(1);
-  }
-  const jobsDir = join15(process.cwd(), ".specialists", "jobs");
-  if (!existsSync12(jobsDir)) {
-    console.log(dim8("No jobs directory found."));
+async function run12() {
+  const options = parseArgs8(process.argv.slice(3));
+  const jobsDir = join20(process.cwd(), ".specialists", "jobs");
+  if (!existsSync15(jobsDir)) {
+    console.log(dim7("No jobs directory found."));
     return;
   }
   if (options.follow) {
@@ -20660,7 +21674,7 @@ async function run11() {
     since: options.since,
     limit: options.limit
   });
-  printSnapshot(merged, options);
+  printSnapshot(merged, options, jobsDir);
 }
 var init_feed = __esm(() => {
   init_timeline_events();
@@ -20671,14 +21685,14 @@ var init_feed = __esm(() => {
 // src/cli/poll.ts
 var exports_poll = {};
 __export(exports_poll, {
-  run: () => run12
+  run: () => run13
 });
-import { existsSync as existsSync13, readFileSync as readFileSync7 } from "node:fs";
-import { join as join16 } from "node:path";
-function parseArgs7(argv) {
+import { existsSync as existsSync16, readFileSync as readFileSync11 } from "node:fs";
+import { join as join21 } from "node:path";
+function parseArgs9(argv) {
   let jobId;
   let cursor = 0;
-  let json = false;
+  let outputCursor = 0;
   for (let i = 0;i < argv.length; i++) {
     if (argv[i] === "--cursor" && argv[i + 1]) {
       cursor = parseInt(argv[++i], 10);
@@ -20686,50 +21700,44 @@ function parseArgs7(argv) {
         cursor = 0;
       continue;
     }
+    if (argv[i] === "--output-cursor" && argv[i + 1]) {
+      outputCursor = parseInt(argv[++i], 10);
+      if (isNaN(outputCursor) || outputCursor < 0)
+        outputCursor = 0;
+      continue;
+    }
     if (argv[i] === "--json") {
-      json = true;
       continue;
     }
-    if (!argv[i].startsWith("--")) {
-      jobId = argv[i];
+    if (argv[i] === "--follow" || argv[i] === "-f") {
+      process.stderr.write(`--follow removed from poll. Use 'specialists feed --follow' for live human-readable output.
+`);
+      process.exit(1);
     }
-  }
-  if (!jobId) {
-    console.error("Usage: specialists poll <job-id> [--cursor N] [--json]");
-    process.exit(1);
-  }
-  return { jobId, cursor, json };
-}
-async function run12() {
-  const { jobId, cursor, json } = parseArgs7(process.argv.slice(3));
-  const jobsDir = join16(process.cwd(), ".specialists", "jobs");
-  const jobDir = join16(jobsDir, jobId);
-  if (!existsSync13(jobDir)) {
-    const result2 = {
-      job_id: jobId,
-      status: "error",
-      elapsed_ms: 0,
-      cursor: 0,
-      output: "",
-      output_delta: "",
-      events: [],
-      error: `Job not found: ${jobId}`
-    };
-    console.log(JSON.stringify(result2));
+    if (!argv[i].startsWith("-")) {
+      jobId = argv[i];
+    }
+  }
+  if (!jobId) {
+    console.error("Usage: specialists poll <job-id> [--cursor N] [--output-cursor N]");
     process.exit(1);
   }
-  const statusPath = join16(jobDir, "status.json");
+  return { jobId, cursor, outputCursor };
+}
+function readJobState(jobsDir, jobId, cursor, outputCursor) {
+  const jobDir = join21(jobsDir, jobId);
+  const statusPath = join21(jobDir, "status.json");
   let status = null;
-  if (existsSync13(statusPath)) {
+  if (existsSync16(statusPath)) {
     try {
-      status = JSON.parse(readFileSync7(statusPath, "utf-8"));
+      status = JSON.parse(readFileSync11(statusPath, "utf-8"));
     } catch {}
   }
-  const resultPath = join16(jobDir, "result.txt");
-  let output = "";
-  if (existsSync13(resultPath)) {
+  const resultPath = join21(jobDir, "result.txt");
+  let fullOutput = "";
+  if (existsSync16(resultPath)) {
     try {
-      output = readFileSync7(resultPath, "utf-8");
+      fullOutput = readFileSync11(resultPath, "utf-8");
     } catch {}
   }
   const events = readJobEventsById(jobsDir, jobId);
@@ -20738,13 +21746,18 @@ async function run12() {
   const startedAt = status?.started_at_ms ?? Date.now();
   const lastEvent = status?.last_event_at_ms ?? Date.now();
   const elapsedMs = status?.status === "done" || status?.status === "error" ? lastEvent - startedAt : Date.now() - startedAt;
-  const result = {
+  const isDone = status?.status === "done";
+  const output = isDone ? fullOutput : "";
+  const outputDelta = fullOutput.length > outputCursor ? fullOutput.slice(outputCursor) : "";
+  const nextOutputCursor = fullOutput.length;
+  return {
     job_id: jobId,
     status: status?.status ?? "starting",
     elapsed_ms: elapsedMs,
     cursor: nextCursor,
-    output: status?.status === "done" ? output : "",
-    output_delta: "",
+    output_cursor: nextOutputCursor,
+    output,
+    output_delta: outputDelta,
     events: newEvents,
     current_event: status?.current_event,
     current_tool: status?.current_tool,
@@ -20753,27 +21766,32 @@ async function run12() {
     bead_id: status?.bead_id,
     error: status?.error
   };
-  if (json) {
-    console.log(JSON.stringify(result, null, 2));
-  } else {
-    console.log(`Job:      ${jobId}`);
-    console.log(`Status:   ${result.status}`);
-    console.log(`Elapsed:  ${Math.round(result.elapsed_ms / 1000)}s`);
-    if (result.model)
-      console.log(`Model:    ${result.backend}/${result.model}`);
-    if (result.bead_id)
-      console.log(`Bead:     ${result.bead_id}`);
-    if (result.current_tool)
-      console.log(`Tool:     ${result.current_tool}`);
-    if (result.error)
-      console.log(`Error:    ${result.error}`);
-    console.log(`Events:   ${newEvents.length} new (cursor: ${cursor} → ${nextCursor})`);
-    if (result.status === "done" && result.output) {
-      console.log(`
---- Output ---`);
-      console.log(result.output.slice(0, 500) + (result.output.length > 500 ? "..." : ""));
-    }
+}
+async function run13() {
+  const { jobId, cursor, outputCursor } = parseArgs9(process.argv.slice(3));
+  const jobsDir = join21(process.cwd(), ".specialists", "jobs");
+  const jobDir = join21(jobsDir, jobId);
+  if (!existsSync16(jobDir)) {
+    const result2 = {
+      job_id: jobId,
+      status: "error",
+      elapsed_ms: 0,
+      cursor: 0,
+      output_cursor: 0,
+      output: "",
+      output_delta: "",
+      events: [],
+      error: `Job not found: ${jobId}`
+    };
+    console.log(JSON.stringify(result2));
+    process.exit(1);
   }
+  const result = readJobState(jobsDir, jobId, cursor, outputCursor);
+  if (result.status !== "done" && result.status !== "error" && !result.output_delta) {
+    process.stderr.write(`Tip: use 'specialists feed --follow' for live human-readable output.
+`);
+  }
+  console.log(JSON.stringify(result));
 }
 var init_poll = __esm(() => {
   init_timeline_query();
@@ -20782,18 +21800,18 @@ var init_poll = __esm(() => {
 // src/cli/steer.ts
 var exports_steer = {};
 __export(exports_steer, {
-  run: () => run13
+  run: () => run14
 });
-import { join as join17 } from "node:path";
+import { join as join22 } from "node:path";
 import { writeFileSync as writeFileSync6 } from "node:fs";
-async function run13() {
+async function run14() {
   const jobId = process.argv[3];
   const message = process.argv[4];
   if (!jobId || !message) {
     console.error('Usage: specialists|sp steer <job-id> "<message>"');
     process.exit(1);
   }
-  const jobsDir = join17(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join22(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const status = supervisor.readStatus(jobId);
   if (!status) {
@@ -20808,7 +21826,7 @@ async function run13() {
   if (!status.fifo_path) {
     process.stderr.write(`${red4("Error:")} Job ${jobId} has no steer pipe.
 `);
-    process.stderr.write(`Only jobs started with --background support mid-run steering.
+    process.stderr.write(`FIFO support may not be available on this system (mkfifo failed at job start).
 `);
     process.exit(1);
   }
@@ -20816,7 +21834,7 @@ async function run13() {
     const payload = JSON.stringify({ type: "steer", message }) + `
 `;
     writeFileSync6(status.fifo_path, payload, { flag: "a" });
-    process.stdout.write(`${green8("✓")} Steer message sent to job ${jobId}
+    process.stdout.write(`${green9("✓")} Steer message sent to job ${jobId}
 `);
   } catch (err) {
     process.stderr.write(`${red4("Error:")} Failed to write to steer pipe: ${err?.message}
@@ -20824,26 +21842,26 @@ async function run13() {
     process.exit(1);
   }
 }
-var green8 = (s) => `\x1B[32m${s}\x1B[0m`, red4 = (s) => `\x1B[31m${s}\x1B[0m`;
+var green9 = (s) => `\x1B[32m${s}\x1B[0m`, red4 = (s) => `\x1B[31m${s}\x1B[0m`;
 var init_steer = __esm(() => {
   init_supervisor();
 });
 
-// src/cli/follow-up.ts
-var exports_follow_up = {};
-__export(exports_follow_up, {
-  run: () => run14
+// src/cli/resume.ts
+var exports_resume = {};
+__export(exports_resume, {
+  run: () => run15
 });
-import { join as join18 } from "node:path";
+import { join as join23 } from "node:path";
 import { writeFileSync as writeFileSync7 } from "node:fs";
-async function run14() {
+async function run15() {
   const jobId = process.argv[3];
-  const message = process.argv[4];
-  if (!jobId || !message) {
-    console.error('Usage: specialists|sp follow-up <job-id> "<message>"');
+  const task = process.argv[4];
+  if (!jobId || !task) {
+    console.error('Usage: specialists|sp resume <job-id> "<task>"');
     process.exit(1);
   }
-  const jobsDir = join18(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join23(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const status = supervisor.readStatus(jobId);
   if (!status) {
@@ -20853,7 +21871,7 @@ async function run14() {
   if (status.status !== "waiting") {
     process.stderr.write(`${red5("Error:")} Job ${jobId} is not in waiting state (status: ${status.status}).
 `);
-    process.stderr.write(`Only jobs started with --keep-alive and --background support follow-up prompts.
+    process.stderr.write(`resume is only valid for keep-alive jobs in waiting state. Use steer for running jobs.
 `);
     process.exit(1);
   }
@@ -20863,10 +21881,10 @@ async function run14() {
     process.exit(1);
   }
   try {
-    const payload = JSON.stringify({ type: "prompt", message }) + `
+    const payload = JSON.stringify({ type: "resume", task }) + `
 `;
     writeFileSync7(status.fifo_path, payload, { flag: "a" });
-    process.stdout.write(`${green9("✓")} Follow-up sent to job ${jobId}
+    process.stdout.write(`${green10("✓")} Resume sent to job ${jobId}
 `);
     process.stdout.write(`  Use 'specialists feed ${jobId} --follow' to watch the response.
 `);
@@ -20876,24 +21894,226 @@ async function run14() {
     process.exit(1);
   }
 }
-var green9 = (s) => `\x1B[32m${s}\x1B[0m`, red5 = (s) => `\x1B[31m${s}\x1B[0m`;
-var init_follow_up = __esm(() => {
+var green10 = (s) => `\x1B[32m${s}\x1B[0m`, red5 = (s) => `\x1B[31m${s}\x1B[0m`;
+var init_resume = __esm(() => {
   init_supervisor();
 });
 
+// src/cli/follow-up.ts
+var exports_follow_up = {};
+__export(exports_follow_up, {
+  run: () => run16
+});
+async function run16() {
+  process.stderr.write("\x1B[33m⚠ DEPRECATED:\x1B[0m `specialists follow-up` is deprecated. Use `specialists resume` instead.\n\n");
+  const { run: resumeRun } = await Promise.resolve().then(() => (init_resume(), exports_resume));
+  return resumeRun();
+}
+
+// src/cli/clean.ts
+var exports_clean = {};
+__export(exports_clean, {
+  run: () => run17
+});
+import {
+  existsSync as existsSync17,
+  readdirSync as readdirSync5,
+  readFileSync as readFileSync12,
+  rmSync as rmSync2,
+  statSync as statSync2
+} from "node:fs";
+import { join as join24 } from "node:path";
+function parseTtlDaysFromEnvironment() {
+  const rawValue = process.env.SPECIALISTS_JOB_TTL_DAYS ?? process.env.JOB_TTL_DAYS;
+  if (!rawValue)
+    return DEFAULT_TTL_DAYS;
+  const parsedValue = Number(rawValue);
+  if (!Number.isFinite(parsedValue) || parsedValue < 0)
+    return DEFAULT_TTL_DAYS;
+  return parsedValue;
+}
+function parseOptions(argv) {
+  let removeAllCompleted = false;
+  let dryRun = false;
+  let keepRecentCount = null;
+  for (let index = 0;index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--all") {
+      removeAllCompleted = true;
+      continue;
+    }
+    if (argument === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (argument === "--keep") {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error("Missing value for --keep");
+      }
+      const parsedValue = Number(value);
+      const isInteger = Number.isInteger(parsedValue);
+      if (!isInteger || parsedValue < 0) {
+        throw new Error("--keep must be a non-negative integer");
+      }
+      keepRecentCount = parsedValue;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("--keep=")) {
+      const value = argument.slice("--keep=".length);
+      const parsedValue = Number(value);
+      const isInteger = Number.isInteger(parsedValue);
+      if (!isInteger || parsedValue < 0) {
+        throw new Error("--keep must be a non-negative integer");
+      }
+      keepRecentCount = parsedValue;
+      continue;
+    }
+    throw new Error(`Unknown option: ${argument}`);
+  }
+  return { removeAllCompleted, dryRun, keepRecentCount };
+}
+function readDirectorySizeBytes(directoryPath) {
+  let totalBytes = 0;
+  const entries = readdirSync5(directoryPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = join24(directoryPath, entry.name);
+    const stats = statSync2(entryPath);
+    if (stats.isDirectory()) {
+      totalBytes += readDirectorySizeBytes(entryPath);
+      continue;
+    }
+    totalBytes += stats.size;
+  }
+  return totalBytes;
+}
+function readCompletedJobDirectory(baseDirectory, entry) {
+  if (!entry.isDirectory())
+    return null;
+  const directoryPath = join24(baseDirectory, entry.name);
+  const statusFilePath = join24(directoryPath, "status.json");
+  if (!existsSync17(statusFilePath))
+    return null;
+  let statusData;
+  try {
+    statusData = JSON.parse(readFileSync12(statusFilePath, "utf-8"));
+  } catch {
+    return null;
+  }
+  if (!COMPLETED_STATUSES.has(statusData.status))
+    return null;
+  const directoryStats = statSync2(directoryPath);
+  return {
+    id: entry.name,
+    directoryPath,
+    modifiedAtMs: directoryStats.mtimeMs,
+    startedAtMs: statusData.started_at_ms,
+    sizeBytes: readDirectorySizeBytes(directoryPath)
+  };
+}
+function collectCompletedJobDirectories(jobsDirectoryPath) {
+  const entries = readdirSync5(jobsDirectoryPath, { withFileTypes: true });
+  const completedJobs = [];
+  for (const entry of entries) {
+    const completedJob = readCompletedJobDirectory(jobsDirectoryPath, entry);
+    if (completedJob) {
+      completedJobs.push(completedJob);
+    }
+  }
+  return completedJobs;
+}
+function selectJobsToRemove(completedJobs, options) {
+  const jobsByNewest = [...completedJobs].sort((left, right) => {
+    if (right.startedAtMs !== left.startedAtMs) {
+      return right.startedAtMs - left.startedAtMs;
+    }
+    return right.modifiedAtMs - left.modifiedAtMs;
+  });
+  if (options.keepRecentCount !== null) {
+    return jobsByNewest.slice(options.keepRecentCount);
+  }
+  if (options.removeAllCompleted) {
+    return jobsByNewest;
+  }
+  const ttlDays = parseTtlDaysFromEnvironment();
+  const cutoffMs = Date.now() - ttlDays * MS_PER_DAY;
+  return jobsByNewest.filter((job) => job.modifiedAtMs < cutoffMs);
+}
+function formatBytes(bytes) {
+  if (bytes < 1024)
+    return `${bytes} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes / 1024;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+  return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+function renderSummary(removedCount, freedBytes, dryRun) {
+  const action = dryRun ? "Would remove" : "Removed";
+  const noun = removedCount === 1 ? "directory" : "directories";
+  return `${action} ${removedCount} job ${noun} (${formatBytes(freedBytes)} freed)`;
+}
+function printDryRunPlan(jobs) {
+  if (jobs.length === 0)
+    return;
+  console.log("Would remove:");
+  for (const job of jobs) {
+    console.log(`  - ${job.id}`);
+  }
+}
+function printUsageAndExit(message) {
+  console.error(message);
+  console.error("Usage: specialists|sp clean [--all] [--keep <n>] [--dry-run]");
+  process.exit(1);
+}
+async function run17() {
+  let options;
+  try {
+    options = parseOptions(process.argv.slice(3));
+  } catch (error2) {
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    printUsageAndExit(message);
+  }
+  const jobsDirectoryPath = join24(process.cwd(), ".specialists", "jobs");
+  if (!existsSync17(jobsDirectoryPath)) {
+    console.log("No jobs directory found.");
+    return;
+  }
+  const completedJobs = collectCompletedJobDirectories(jobsDirectoryPath);
+  const jobsToRemove = selectJobsToRemove(completedJobs, options);
+  const freedBytes = jobsToRemove.reduce((total, job) => total + job.sizeBytes, 0);
+  if (options.dryRun) {
+    printDryRunPlan(jobsToRemove);
+    console.log(renderSummary(jobsToRemove.length, freedBytes, true));
+    return;
+  }
+  for (const job of jobsToRemove) {
+    rmSync2(job.directoryPath, { recursive: true, force: true });
+  }
+  console.log(renderSummary(jobsToRemove.length, freedBytes, false));
+}
+var MS_PER_DAY = 86400000, DEFAULT_TTL_DAYS = 7, COMPLETED_STATUSES;
+var init_clean = __esm(() => {
+  COMPLETED_STATUSES = new Set(["done", "error"]);
+});
+
 // src/cli/stop.ts
 var exports_stop = {};
 __export(exports_stop, {
-  run: () => run15
+  run: () => run18
 });
-import { join as join19 } from "node:path";
-async function run15() {
+import { join as join25 } from "node:path";
+async function run18() {
   const jobId = process.argv[3];
   if (!jobId) {
     console.error("Usage: specialists|sp stop <job-id>");
     process.exit(1);
   }
-  const jobsDir = join19(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join25(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const status = supervisor.readStatus(jobId);
   if (!status) {
@@ -20912,7 +22132,7 @@ async function run15() {
   }
   try {
     process.kill(status.pid, "SIGTERM");
-    process.stdout.write(`${green10("✓")} Sent SIGTERM to PID ${status.pid} (job ${jobId})
+    process.stdout.write(`${green11("✓")} Sent SIGTERM to PID ${status.pid} (job ${jobId})
 `);
   } catch (err) {
     if (err.code === "ESRCH") {
@@ -20925,7 +22145,7 @@ async function run15() {
     }
   }
 }
-var green10 = (s) => `\x1B[32m${s}\x1B[0m`, red6 = (s) => `\x1B[31m${s}\x1B[0m`, dim10 = (s) => `\x1B[2m${s}\x1B[0m`;
+var green11 = (s) => `\x1B[32m${s}\x1B[0m`, red6 = (s) => `\x1B[31m${s}\x1B[0m`, dim10 = (s) => `\x1B[2m${s}\x1B[0m`;
 var init_stop = __esm(() => {
   init_supervisor();
 });
@@ -20933,7 +22153,7 @@ var init_stop = __esm(() => {
 // src/cli/quickstart.ts
 var exports_quickstart = {};
 __export(exports_quickstart, {
-  run: () => run16
+  run: () => run19
 });
 function section2(title) {
   const bar = "─".repeat(60);
@@ -20942,12 +22162,12 @@ ${bold9(cyan6(title))}
 ${dim11(bar)}`;
 }
 function cmd2(s) {
-  return yellow8(s);
+  return yellow9(s);
 }
 function flag(s) {
-  return green11(s);
+  return green12(s);
 }
-async function run16() {
+async function run19() {
   const lines = [
     "",
     bold9("specialists  ·  Quick Start Guide"),
@@ -20967,11 +22187,12 @@ async function run16() {
   lines.push(section2("2. Initialize a Project"));
   lines.push("");
   lines.push(`  Run once per project root:`);
-  lines.push(`  ${cmd2("specialists init")}                          # creates specialists/, .specialists/, AGENTS.md`);
+  lines.push(`  ${cmd2("specialists init")}                          # creates .specialists/, wires MCP + AGENTS.md`);
   lines.push("");
   lines.push(`  What this creates:`);
-  lines.push(`  ${dim11("specialists/")}       — put your .specialist.yaml files here`);
-  lines.push(`  ${dim11(".specialists/")}      — runtime data (jobs/, ready/) — gitignored`);
+  lines.push(`  ${dim11(".specialists/default/")} — canonical specialists (from init)`);
+  lines.push(`  ${dim11(".specialists/user/")}    — custom .specialist.yaml files`);
+  lines.push(`  ${dim11(".specialists/jobs|ready")} — runtime data — gitignored`);
   lines.push(`  ${dim11("AGENTS.md")}          — context block injected into Claude sessions`);
   lines.push("");
   lines.push(section2("3. Discover Specialists"));
@@ -20983,8 +22204,8 @@ async function run16() {
   lines.push(`  ${cmd2("specialists list")} ${flag("--json")}                     # machine-readable JSON`);
   lines.push("");
   lines.push(`  Scopes (searched in order, user wins on name collision):`);
-  lines.push(`  ${blue2("user")}      .specialists/user/specialists/*.specialist.yaml`);
-  lines.push(`  ${blue2("default")}   .specialists/default/specialists/*.specialist.yaml`);
+  lines.push(`  ${blue2("user")}      .specialists/user/*.specialist.yaml`);
+  lines.push(`  ${blue2("default")}   .specialists/default/*.specialist.yaml`);
   lines.push("");
   lines.push(section2("4. Running a Specialist"));
   lines.push("");
@@ -21004,9 +22225,11 @@ async function run16() {
   lines.push(`  Pipe a prompt from stdin:`);
   lines.push(`  ${cmd2("cat my-brief.md | specialists run code-review")}`);
   lines.push("");
-  lines.push(section2("5. Background Job Lifecycle"));
+  lines.push(section2("5. Async Job Lifecycle"));
   lines.push("");
-  lines.push(`  Use Claude Code's native backgrounding or run in a separate terminal.`);
+  lines.push(`  ${bold9("MCP pattern")}: ${cmd2("start_specialist")} → ${cmd2("feed_specialist")} (returns job_id directly)`);
+  lines.push(`  ${bold9("CLI pattern")}: ${cmd2('specialists run <name> --prompt "..."')} prints ${dim11("[job started: <id>]")} to stderr`);
+  lines.push(`  ${bold9("Shell pattern")}: ${cmd2('specialists run <name> --prompt "..." &')} for native backgrounding`);
   lines.push("");
   lines.push(`  ${bold9("Watch progress")} — stream events as they arrive:`);
   lines.push(`  ${cmd2("specialists feed job_a1b2c3d4")}            # print events so far`);
@@ -21100,10 +22323,10 @@ async function run16() {
   lines.push(`  Specialists emits lifecycle events to ${dim11(".specialists/trace.jsonl")}:`);
   lines.push("");
   lines.push(`  ${bold9("Hook point")}              ${bold9("When fired")}`);
-  lines.push(`  ${yellow8("specialist:start")}       before the agent session begins`);
-  lines.push(`  ${yellow8("specialist:token")}       on each streamed token (delta)`);
-  lines.push(`  ${yellow8("specialist:done")}        after successful completion`);
-  lines.push(`  ${yellow8("specialist:error")}       on failure or timeout`);
+  lines.push(`  ${yellow9("specialist:start")}       before the agent session begins`);
+  lines.push(`  ${yellow9("specialist:token")}       on each streamed token (delta)`);
+  lines.push(`  ${yellow9("specialist:done")}        after successful completion`);
+  lines.push(`  ${yellow9("specialist:error")}       on failure or timeout`);
   lines.push("");
   lines.push(`  Each event line in trace.jsonl:`);
   lines.push(`  ${dim11('{"t":"<ISO>","hook":"specialist:done","specialist":"code-review","durationMs":4120}')}`);
@@ -21120,9 +22343,9 @@ async function run16() {
   lines.push(`  ${bold9("use_specialist")}     — full lifecycle: load → agents.md → run → output`);
   lines.push(`  ${bold9("run_parallel")}       — concurrent or pipeline execution`);
   lines.push(`  ${bold9("start_specialist")}   — async job start, returns job ID`);
-  lines.push(`  ${bold9("poll_specialist")}    — poll job status/output by ID`);
+  lines.push(`  ${bold9("feed_specialist")}    — stream events/output by job ID`);
   lines.push(`  ${bold9("steer_specialist")}      — send a mid-run message to a running job`);
-  lines.push(`  ${bold9("follow_up_specialist")} — send a next-turn prompt to a keep-alive session`);
+  lines.push(`  ${bold9("resume_specialist")}    — resume a waiting keep-alive session with a next-turn prompt`);
   lines.push(`  ${bold9("stop_specialist")}      — cancel a running job by ID`);
   lines.push(`  ${bold9("specialist_status")}  — circuit breaker health + staleness`);
   lines.push("");
@@ -21155,27 +22378,27 @@ async function run16() {
   console.log(lines.join(`
 `));
 }
-var bold9 = (s) => `\x1B[1m${s}\x1B[0m`, dim11 = (s) => `\x1B[2m${s}\x1B[0m`, yellow8 = (s) => `\x1B[33m${s}\x1B[0m`, cyan6 = (s) => `\x1B[36m${s}\x1B[0m`, blue2 = (s) => `\x1B[34m${s}\x1B[0m`, green11 = (s) => `\x1B[32m${s}\x1B[0m`;
+var bold9 = (s) => `\x1B[1m${s}\x1B[0m`, dim11 = (s) => `\x1B[2m${s}\x1B[0m`, yellow9 = (s) => `\x1B[33m${s}\x1B[0m`, cyan6 = (s) => `\x1B[36m${s}\x1B[0m`, blue2 = (s) => `\x1B[34m${s}\x1B[0m`, green12 = (s) => `\x1B[32m${s}\x1B[0m`;
 
 // src/cli/doctor.ts
 var exports_doctor = {};
 __export(exports_doctor, {
-  run: () => run17
+  run: () => run20
 });
-import { spawnSync as spawnSync7 } from "node:child_process";
-import { existsSync as existsSync14, mkdirSync as mkdirSync3, readFileSync as readFileSync8, readdirSync as readdirSync4 } from "node:fs";
-import { join as join20 } from "node:path";
+import { spawnSync as spawnSync8 } from "node:child_process";
+import { existsSync as existsSync18, mkdirSync as mkdirSync3, readFileSync as readFileSync13, readdirSync as readdirSync6 } from "node:fs";
+import { join as join26 } from "node:path";
 function ok3(msg) {
-  console.log(`  ${green12("✓")} ${msg}`);
+  console.log(`  ${green13("✓")} ${msg}`);
 }
 function warn2(msg) {
-  console.log(`  ${yellow9("○")} ${msg}`);
+  console.log(`  ${yellow10("○")} ${msg}`);
 }
 function fail2(msg) {
   console.log(`  ${red7("✗")} ${msg}`);
 }
 function fix(msg) {
-  console.log(`    ${dim12("→ fix:")} ${yellow9(msg)}`);
+  console.log(`    ${dim12("→ fix:")} ${yellow10(msg)}`);
 }
 function hint(msg) {
   console.log(`    ${dim12(msg)}`);
@@ -21186,17 +22409,17 @@ function section3(label) {
 ${bold10(`── ${label} ${line}`)}`);
 }
 function sp(bin, args) {
-  const r = spawnSync7(bin, args, { encoding: "utf8", stdio: "pipe", timeout: 5000 });
+  const r = spawnSync8(bin, args, { encoding: "utf8", stdio: "pipe", timeout: 5000 });
   return { ok: r.status === 0 && !r.error, stdout: (r.stdout ?? "").trim() };
 }
 function isInstalled2(bin) {
-  return spawnSync7("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
+  return spawnSync8("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
 }
 function loadJson2(path) {
-  if (!existsSync14(path))
+  if (!existsSync18(path))
     return null;
   try {
-    return JSON.parse(readFileSync8(path, "utf8"));
+    return JSON.parse(readFileSync13(path, "utf8"));
   } catch {
     return null;
   }
@@ -21239,7 +22462,7 @@ function checkBd() {
     return false;
   }
   ok3(`bd installed  ${dim12(sp("bd", ["--version"]).stdout || "")}`);
-  if (existsSync14(join20(CWD, ".beads")))
+  if (existsSync18(join26(CWD, ".beads")))
     ok3(".beads/ present in project");
   else
     warn2(".beads/ not found in project");
@@ -21259,8 +22482,8 @@ function checkHooks() {
   section3("Claude Code hooks  (2 expected)");
   let allPresent = true;
   for (const name of HOOK_NAMES) {
-    const dest = join20(HOOKS_DIR, name);
-    if (!existsSync14(dest)) {
+    const dest = join26(HOOKS_DIR, name);
+    if (!existsSync18(dest)) {
       fail2(`${name}  ${red7("missing")}`);
       fix("specialists install");
       allPresent = false;
@@ -21304,18 +22527,18 @@ function checkMCP() {
 }
 function checkRuntimeDirs() {
   section3(".specialists/ runtime directories");
-  const rootDir = join20(CWD, ".specialists");
-  const jobsDir = join20(rootDir, "jobs");
-  const readyDir = join20(rootDir, "ready");
+  const rootDir = join26(CWD, ".specialists");
+  const jobsDir = join26(rootDir, "jobs");
+  const readyDir = join26(rootDir, "ready");
   let allOk = true;
-  if (!existsSync14(rootDir)) {
+  if (!existsSync18(rootDir)) {
     warn2(".specialists/ not found in current project");
     fix("specialists init");
     allOk = false;
   } else {
     ok3(".specialists/ present");
     for (const [subDir, label] of [[jobsDir, "jobs"], [readyDir, "ready"]]) {
-      if (!existsSync14(subDir)) {
+      if (!existsSync18(subDir)) {
         warn2(`.specialists/${label}/ missing — auto-creating`);
         mkdirSync3(subDir, { recursive: true });
         ok3(`.specialists/${label}/ created`);
@@ -21328,14 +22551,14 @@ function checkRuntimeDirs() {
 }
 function checkZombieJobs() {
   section3("Background jobs");
-  const jobsDir = join20(CWD, ".specialists", "jobs");
-  if (!existsSync14(jobsDir)) {
+  const jobsDir = join26(CWD, ".specialists", "jobs");
+  if (!existsSync18(jobsDir)) {
     hint("No .specialists/jobs/ — skipping");
     return true;
   }
   let entries;
   try {
-    entries = readdirSync4(jobsDir);
+    entries = readdirSync6(jobsDir);
   } catch {
     entries = [];
   }
@@ -21347,11 +22570,11 @@ function checkZombieJobs() {
   let total = 0;
   let running = 0;
   for (const jobId of entries) {
-    const statusPath = join20(jobsDir, jobId, "status.json");
-    if (!existsSync14(statusPath))
+    const statusPath = join26(jobsDir, jobId, "status.json");
+    if (!existsSync18(statusPath))
       continue;
     try {
-      const status = JSON.parse(readFileSync8(statusPath, "utf8"));
+      const status = JSON.parse(readFileSync13(statusPath, "utf8"));
       total++;
       if (status.status === "running" || status.status === "starting") {
         const pid = status.pid;
@@ -21365,7 +22588,7 @@ function checkZombieJobs() {
             running++;
           else {
             zombies++;
-            warn2(`${jobId}  ${yellow9("ZOMBIE")}  ${dim12(`pid ${pid} not found, status=${status.status}`)}`);
+            warn2(`${jobId}  ${yellow10("ZOMBIE")}  ${dim12(`pid ${pid} not found, status=${status.status}`)}`);
             fix(`Edit .specialists/jobs/${jobId}/status.json  →  set "status": "error"`);
           }
         }
@@ -21378,7 +22601,7 @@ function checkZombieJobs() {
   }
   return zombies === 0;
 }
-async function run17() {
+async function run20() {
   console.log(`
 ${bold10("specialists doctor")}
 `);
@@ -21393,21 +22616,21 @@ ${bold10("specialists doctor")}
   const allOk = piOk && bdOk && xtOk && hooksOk && mcpOk && dirsOk && jobsOk;
   console.log("");
   if (allOk) {
-    console.log(`  ${green12("✓")} ${bold10("All checks passed")}  — specialists is healthy`);
+    console.log(`  ${green13("✓")} ${bold10("All checks passed")}  — specialists is healthy`);
   } else {
-    console.log(`  ${yellow9("○")} ${bold10("Some checks failed")}  — follow the fix hints above`);
+    console.log(`  ${yellow10("○")} ${bold10("Some checks failed")}  — follow the fix hints above`);
     console.log(`  ${dim12("specialists install fixes hook + MCP registration; pi, bd, and xt must be installed separately.")}`);
   }
   console.log("");
 }
-var bold10 = (s) => `\x1B[1m${s}\x1B[0m`, dim12 = (s) => `\x1B[2m${s}\x1B[0m`, green12 = (s) => `\x1B[32m${s}\x1B[0m`, yellow9 = (s) => `\x1B[33m${s}\x1B[0m`, red7 = (s) => `\x1B[31m${s}\x1B[0m`, CWD, CLAUDE_DIR, SPECIALISTS_DIR, HOOKS_DIR, SETTINGS_FILE, MCP_FILE2, HOOK_NAMES;
+var bold10 = (s) => `\x1B[1m${s}\x1B[0m`, dim12 = (s) => `\x1B[2m${s}\x1B[0m`, green13 = (s) => `\x1B[32m${s}\x1B[0m`, yellow10 = (s) => `\x1B[33m${s}\x1B[0m`, red7 = (s) => `\x1B[31m${s}\x1B[0m`, CWD, CLAUDE_DIR, SPECIALISTS_DIR, HOOKS_DIR, SETTINGS_FILE, MCP_FILE2, HOOK_NAMES;
 var init_doctor = __esm(() => {
   CWD = process.cwd();
-  CLAUDE_DIR = join20(CWD, ".claude");
-  SPECIALISTS_DIR = join20(CWD, ".specialists");
-  HOOKS_DIR = join20(SPECIALISTS_DIR, "default", "hooks");
-  SETTINGS_FILE = join20(CLAUDE_DIR, "settings.json");
-  MCP_FILE2 = join20(CWD, ".mcp.json");
+  CLAUDE_DIR = join26(CWD, ".claude");
+  SPECIALISTS_DIR = join26(CWD, ".specialists");
+  HOOKS_DIR = join26(SPECIALISTS_DIR, "default", "hooks");
+  SETTINGS_FILE = join26(CLAUDE_DIR, "settings.json");
+  MCP_FILE2 = join26(CWD, ".mcp.json");
   HOOK_NAMES = [
     "specialists-complete.mjs",
     "specialists-session-start.mjs"
@@ -21417,11 +22640,11 @@ var init_doctor = __esm(() => {
 // src/cli/setup.ts
 var exports_setup = {};
 __export(exports_setup, {
-  run: () => run18
+  run: () => run21
 });
-async function run18() {
+async function run21() {
   console.log("");
-  console.log(yellow10("⚠ DEPRECATED: `specialists setup` is deprecated"));
+  console.log(yellow11("⚠ DEPRECATED: `specialists setup` is deprecated"));
   console.log("");
   console.log(`  Use ${bold11("specialists init")} instead.`);
   console.log("");
@@ -21437,18 +22660,18 @@ async function run18() {
   console.log(`  ${dim13("Run: specialists init --help for full details")}`);
   console.log("");
 }
-var bold11 = (s) => `\x1B[1m${s}\x1B[0m`, yellow10 = (s) => `\x1B[33m${s}\x1B[0m`, dim13 = (s) => `\x1B[2m${s}\x1B[0m`;
+var bold11 = (s) => `\x1B[1m${s}\x1B[0m`, yellow11 = (s) => `\x1B[33m${s}\x1B[0m`, dim13 = (s) => `\x1B[2m${s}\x1B[0m`;
 
 // src/cli/help.ts
 var exports_help = {};
 __export(exports_help, {
-  run: () => run19
+  run: () => run22
 });
 function formatCommands(entries) {
   const width = Math.max(...entries.map(([cmd3]) => cmd3.length));
   return entries.map(([cmd3, desc]) => `  ${cmd3.padEnd(width)}   ${desc}`);
 }
-async function run19() {
+async function run22() {
   const lines = [
     "",
     "Specialists lets you run project-scoped specialist agents with a bead-first workflow.",
@@ -21476,10 +22699,16 @@ async function run19() {
     "    --context-depth defaults to 1 with --bead",
     "    --no-beads does not disable bead reading",
     "",
-    "  Background execution",
-    "    Use Claude Code's native backgrounding (run_in_background: true)",
-    "    or run in a separate terminal and poll with:",
-    "      specialists poll <job-id> --json",
+    "  Output modes",
+    '    specialists run <name> --prompt "..."          # human (default): formatted event summary',
+    '    specialists run <name> --prompt "..." --json   # NDJSON event stream to stdout',
+    '    specialists run <name> --prompt "..." --raw    # legacy: raw LLM text deltas',
+    "",
+    "  Async patterns",
+    "    MCP:   start_specialist + feed_specialist",
+    '    CLI:   specialists run <name> --prompt "..."       # job ID prints on stderr',
+    "           specialists feed|poll|result <job-id>         # observe/progress/final output",
+    '    Shell: specialists run <name> --prompt "..." &      # native shell backgrounding',
     "",
     bold12("Core commands:"),
     ...formatCommands(CORE_COMMANDS),
@@ -21493,20 +22722,24 @@ async function run19() {
     bold12("Examples:"),
     "  specialists init",
     "  specialists list",
+    "  specialists config get specialist.execution.stall_timeout_ms",
     "  specialists run debugger --bead unitAI-123",
     '  specialists run codebase-explorer --prompt "Map the CLI architecture"',
     "  specialists poll abc123 --json                  # check job status",
     "  specialists feed -f                             # stream all job events",
     '  specialists steer <job-id> "focus only on supervisor.ts"',
-    '  specialists follow-up <job-id> "now write the fix"',
-    "  specialists result <job-id>",
+    '  specialists resume <job-id> "now write the fix"',
+    '  specialists run debugger --prompt "why does auth fail"',
+    "  specialists report list",
+    "  specialists report show --specialists",
+    "  specialists result <job-id> --wait",
     "",
     bold12("More help:"),
     "  specialists quickstart         Full guide and workflow reference",
     "  specialists run --help         Run command details and flags",
     "  specialists poll --help        Job status polling details",
     "  specialists steer --help       Mid-run steering details",
-    "  specialists follow-up --help   Multi-turn keep-alive details",
+    "  specialists resume --help      Multi-turn keep-alive details",
     "  specialists init --help        Bootstrap behavior and workflow injection",
     "  specialists feed --help        Job event streaming details",
     "",
@@ -21522,13 +22755,17 @@ var init_help = __esm(() => {
     ["init", "Bootstrap a project: dirs, workflow injection, project MCP registration"],
     ["list", "List specialists in this project"],
     ["validate", "Validate a specialist YAML against the schema"],
-    ["run", "Run a specialist with --bead for tracked work or --prompt for ad-hoc work"],
+    ["config", "Batch get/set specialist YAML keys in config/specialists/"],
+    ["run", "Run a specialist; --json for NDJSON event stream, --raw for legacy text"],
     ["feed", "Tail job events; use -f to follow all jobs"],
     ["poll", "Machine-readable job status polling (for scripts/Claude Code)"],
-    ["result", "Print final output of a completed job"],
+    ["result", "Print final output of a completed job; --wait polls until done, --timeout <ms> sets a limit"],
+    ["clean", "Purge completed job directories (TTL, --all, --keep, --dry-run)"],
     ["steer", "Send a mid-run message to a running job"],
-    ["follow-up", "Send a next-turn prompt to a keep-alive session (retains full context)"],
+    ["resume", "Resume a waiting keep-alive session with a next-turn prompt (retains full context)"],
+    ["follow-up", "[deprecated] Use resume instead"],
     ["stop", "Stop a running job"],
+    ["report", "Generate/show/list/diff session reports in .xtrm/reports/"],
     ["status", "Show health, MCP state, and active jobs"],
     ["doctor", "Diagnose installation/runtime problems"],
     ["quickstart", "Full getting-started guide"],
@@ -21546,7 +22783,8 @@ var init_help = __esm(() => {
     ["xt claude [name]", "Start a Claude session in a sandboxed xt worktree"],
     ["xt attach [slug]", "Resume an existing xt worktree session"],
     ["xt worktree list", "List worktrees with runtime and activity"],
-    ["xt end", "Close session, push, PR, cleanup"]
+    ["xt end", "Close session, push, PR, cleanup"],
+    ["xt report show|list|diff", "Session report surfaces (same .xtrm/reports files)"]
   ];
 });
 
@@ -28752,7 +29990,7 @@ class StdioServerTransport {
 }
 
 // src/server.ts
-import { join as join7 } from "node:path";
+import { join as join11 } from "node:path";
 
 // src/constants.ts
 var LOG_PREFIX = "[specialists]";
@@ -28819,6 +30057,7 @@ var logger = {
 init_loader();
 init_runner();
 init_hooks();
+init_circuitBreaker();
 init_beads();
 
 // src/tools/specialist/list_specialists.tool.ts
@@ -28842,14 +30081,14 @@ function createListSpecialistsTool(loader) {
 // src/tools/specialist/use_specialist.tool.ts
 init_zod();
 init_beads();
-var useSpecialistSchema = exports_external.object({
-  name: exports_external.string().describe("Specialist identifier (e.g. codebase-explorer)"),
-  prompt: exports_external.string().optional().describe("The task or question for the specialist"),
-  bead_id: exports_external.string().optional().describe("Use an existing bead as the specialist prompt"),
-  variables: exports_external.record(exports_external.string()).optional().describe("Additional $variable substitutions"),
-  backend_override: exports_external.string().optional().describe("Force a specific backend (gemini, qwen, anthropic)"),
-  autonomy_level: exports_external.string().optional().describe("Override permission level for this invocation"),
-  context_depth: exports_external.number().optional().describe("Depth of blocker context injection (0 = none, 1 = immediate blockers, etc.)")
+var useSpecialistSchema = objectType({
+  name: stringType().describe("Specialist identifier (e.g. codebase-explorer)"),
+  prompt: stringType().optional().describe("The task or question for the specialist"),
+  bead_id: stringType().optional().describe("Use an existing bead as the specialist prompt"),
+  variables: recordType(stringType()).optional().describe("Additional $variable substitutions"),
+  backend_override: stringType().optional().describe("Force a specific backend (gemini, qwen, anthropic)"),
+  autonomy_level: stringType().optional().describe("Override permission level for this invocation"),
+  context_depth: numberType().optional().describe("Depth of blocker context injection (0 = none, 1 = immediate blockers, etc.)")
 }).refine((input) => Boolean(input.prompt?.trim() || input.bead_id), {
   message: "Either prompt or bead_id is required",
   path: ["prompt"]
@@ -28944,7 +30183,7 @@ var runParallelSchema = objectType({
 function createRunParallelTool(runner) {
   return {
     name: "run_parallel",
-    description: "[DEPRECATED v3] Execute multiple specialists concurrently. Returns aggregated results. Prefer CLI background jobs for async work.",
+    description: "[DEPRECATED v3] Execute multiple specialists concurrently. Returns aggregated results. Prefer start_specialist/feed_specialist for async orchestration.",
     inputSchema: runParallelSchema,
     async execute(input, onProgress) {
       if (input.merge_strategy === "pipeline") {
@@ -29205,66 +30444,99 @@ class JobRegistry {
 
 // src/tools/specialist/start_specialist.tool.ts
 init_zod();
-var startSpecialistSchema = exports_external.object({
-  name: exports_external.string().describe("Specialist identifier (e.g. codebase-explorer)"),
-  prompt: exports_external.string().describe("The task or question for the specialist"),
-  variables: exports_external.record(exports_external.string()).optional().describe("Additional $variable substitutions"),
-  backend_override: exports_external.string().optional().describe("Force a specific backend (gemini, qwen, anthropic)")
-});
-function createStartSpecialistTool(runner, registry2) {
+init_supervisor();
+import { join as join4 } from "node:path";
+init_loader();
+var startSpecialistSchema = objectType({
+  name: stringType().describe("Specialist identifier (e.g. codebase-explorer)"),
+  prompt: stringType().describe("The task or question for the specialist"),
+  variables: recordType(stringType()).optional().describe("Additional $variable substitutions"),
+  backend_override: stringType().optional().describe("Force a specific backend (gemini, qwen, anthropic)"),
+  bead_id: stringType().optional().describe("Existing bead ID to associate with this run (propagated into status.json and run_start event)"),
+  keep_alive: booleanType().optional().describe("Keep the specialist session open for resume_specialist (overrides execution.interactive)."),
+  no_keep_alive: booleanType().optional().describe("Force one-shot behavior even when execution.interactive is true.")
+});
+function createStartSpecialistTool(runner, beadsClient) {
   return {
     name: "start_specialist",
-    description: "[DEPRECATED v3] Start a specialist asynchronously. Returns job_id immediately. Prefer CLI: `specialists run <name> --background`. " + "Use poll_specialist to track progress, receive output delta, and retrieve beadId " + "(the beads issue auto-created for this run, if beads_integration policy applies). " + "Use stop_specialist to cancel. Enables true parallel execution of multiple specialists.",
+    description: "Start a specialist asynchronously. Returns job_id immediately. " + "Use feed_specialist to stream events and track progress (pass job_id and --follow for live output). " + "Use specialist_status for circuit breaker health checks. " + "Use stop_specialist to cancel. Enables true parallel execution of multiple specialists.",
     inputSchema: startSpecialistSchema,
     async execute(input) {
-      const jobId = await runner.startAsync({
-        name: input.name,
-        prompt: input.prompt,
-        variables: input.variables,
-        backendOverride: input.backend_override
-      }, registry2);
+      const jobsDir = join4(process.cwd(), ".specialists", "jobs");
+      let keepAlive;
+      try {
+        const loader = new SpecialistLoader;
+        const specialist = await loader.get(input.name);
+        const interactiveDefault = specialist.specialist.execution.interactive ? true : undefined;
+        keepAlive = input.no_keep_alive ? false : input.keep_alive ?? interactiveDefault;
+      } catch {
+        keepAlive = input.no_keep_alive ? false : input.keep_alive;
+      }
+      const jobStarted = new Promise((resolve2, reject) => {
+        const supervisor = new Supervisor({
+          runner,
+          runOptions: {
+            name: input.name,
+            prompt: input.prompt,
+            variables: input.variables,
+            backendOverride: input.backend_override,
+            inputBeadId: input.bead_id,
+            keepAlive,
+            noKeepAlive: input.no_keep_alive ?? false
+          },
+          jobsDir,
+          beadsClient,
+          onJobStarted: ({ id }) => resolve2(id)
+        });
+        supervisor.run().catch((error2) => {
+          logger.error(`start_specialist job failed: ${error2 instanceof Error ? error2.message : String(error2)}`);
+          reject(error2);
+        });
+      });
+      const jobId = await jobStarted;
       return { job_id: jobId };
     }
   };
 }
 
-// src/tools/specialist/poll_specialist.tool.ts
-init_zod();
-var pollSpecialistSchema = exports_external.object({
-  job_id: exports_external.string().describe("Job ID returned by start_specialist"),
-  cursor: exports_external.number().int().min(0).optional().default(0).describe("Character offset from previous poll. Pass next_cursor from the last response to receive only new content. Omit (or pass 0) for the first poll.")
-});
-function createPollSpecialistTool(registry2) {
-  return {
-    name: "poll_specialist",
-    description: "[DEPRECATED v3] Poll a running specialist job. Returns status (running|done|error|cancelled), " + "delta (new tokens since cursor), next_cursor, and full output when done. " + "Pass next_cursor back as cursor on each subsequent poll to receive only new content. " + "Response also includes beadId (string | undefined) once the specialist has started — " + "this is the beads issue tracking this run. If present after status=done, consider: " + '`bd update <beadId> --notes "<key finding>"` to attach results, or ' + '`bd remember "<insight>"` to persist discoveries across sessions.',
-    inputSchema: pollSpecialistSchema,
-    async execute(input) {
-      const snapshot = registry2.snapshot(input.job_id, input.cursor ?? 0);
-      if (!snapshot) {
-        return { status: "error", error: `Job not found: ${input.job_id}`, job_id: input.job_id };
-      }
-      return snapshot;
-    }
-  };
-}
-
 // src/tools/specialist/stop_specialist.tool.ts
 init_zod();
-var stopSpecialistSchema = exports_external.object({
-  job_id: exports_external.string().describe("Job ID returned by start_specialist")
+init_supervisor();
+import { join as join5 } from "node:path";
+var stopSpecialistSchema = objectType({
+  job_id: stringType().describe("Job ID returned by start_specialist")
 });
-function createStopSpecialistTool(registry2) {
+function createStopSpecialistTool() {
   return {
     name: "stop_specialist",
-    description: "[DEPRECATED v3] Cancel a running specialist job. Prefer CLI: `specialists stop <id>`. Kills the pi process immediately and sets status to cancelled. Subsequent poll_specialist calls return status: cancelled with output buffered up to that point.",
+    description: "Cancel a running specialist job by sending SIGTERM to its recorded process. Works for jobs started via start_specialist and CLI background runs.",
     inputSchema: stopSpecialistSchema,
     async execute(input) {
-      const result = registry2.cancel(input.job_id);
-      if (!result) {
+      const jobsDir = join5(process.cwd(), ".specialists", "jobs");
+      const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
+      const status = supervisor.readStatus(input.job_id);
+      if (!status) {
         return { status: "error", error: `Job not found: ${input.job_id}`, job_id: input.job_id };
       }
-      return { ...result, job_id: input.job_id };
+      if (status.status === "done" || status.status === "error") {
+        return {
+          status: "error",
+          error: `Job is already ${status.status}`,
+          job_id: input.job_id
+        };
+      }
+      if (!status.pid) {
+        return { status: "error", error: `No PID recorded for job ${input.job_id}`, job_id: input.job_id };
+      }
+      try {
+        process.kill(status.pid, "SIGTERM");
+        return { status: "cancelled", job_id: input.job_id, pid: status.pid };
+      } catch (err) {
+        if (err?.code === "ESRCH") {
+          return { status: "error", error: `Process ${status.pid} not found`, job_id: input.job_id };
+        }
+        return { status: "error", error: err?.message ?? String(err), job_id: input.job_id };
+      }
     }
   };
 }
@@ -29273,15 +30545,15 @@ function createStopSpecialistTool(registry2) {
 init_zod();
 init_supervisor();
 import { writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join4 } from "node:path";
+import { join as join6 } from "node:path";
 var steerSpecialistSchema = exports_external.object({
-  job_id: exports_external.string().describe("Job ID returned by start_specialist or specialists run --background"),
+  job_id: exports_external.string().describe("Job ID returned by start_specialist or printed by specialists run"),
   message: exports_external.string().describe('Steering instruction to send to the running agent (e.g. "focus only on supervisor.ts")')
 });
 function createSteerSpecialistTool(registry2) {
   return {
     name: "steer_specialist",
-    description: "Send a mid-run steering message to a running specialist job. The agent receives the message after its current tool calls finish, before the next LLM call. Works for both in-process jobs (start_specialist) and background CLI jobs (specialists run --background).",
+    description: "Send a mid-run steering message to a running specialist job. The agent receives the message after its current tool calls finish, before the next LLM call. Works for both in-process jobs (start_specialist) and CLI-started jobs (specialists run).",
     inputSchema: steerSpecialistSchema,
     async execute(input) {
       const snap = registry2.snapshot(input.job_id);
@@ -29292,7 +30564,7 @@ function createSteerSpecialistTool(registry2) {
         }
         return { status: "error", error: result.error, job_id: input.job_id };
       }
-      const jobsDir = join4(process.cwd(), ".specialists", "jobs");
+      const jobsDir = join6(process.cwd(), ".specialists", "jobs");
       const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
       const status = supervisor.readStatus(input.job_id);
       if (!status) {
@@ -29318,47 +30590,50 @@ function createSteerSpecialistTool(registry2) {
 
 // src/tools/specialist/follow_up_specialist.tool.ts
 init_zod();
+
+// src/tools/specialist/resume_specialist.tool.ts
+init_zod();
 init_supervisor();
 import { writeFileSync as writeFileSync3 } from "node:fs";
-import { join as join5 } from "node:path";
-var followUpSpecialistSchema = exports_external.object({
+import { join as join7 } from "node:path";
+var resumeSpecialistSchema = exports_external.object({
   job_id: exports_external.string().describe("Job ID of a waiting keep-alive specialist session"),
-  message: exports_external.string().describe("Next prompt to send to the specialist (conversation history is retained)")
+  task: exports_external.string().describe("Next task/prompt to send to the specialist (conversation history is retained)")
 });
-function createFollowUpSpecialistTool(registry2) {
+function createResumeSpecialistTool(registry2) {
   return {
-    name: "follow_up_specialist",
-    description: "Send a follow-up prompt to a waiting keep-alive specialist session. The Pi session retains full conversation history between turns. Only works for jobs started with keepAlive=true (CLI: --keep-alive --background).",
-    inputSchema: followUpSpecialistSchema,
+    name: "resume_specialist",
+    description: "Resume a waiting keep-alive specialist session with a next-turn prompt. " + "The Pi session retains full conversation history between turns. " + "Only valid for jobs in waiting state (started with keepAlive=true, either explicit --keep-alive or execution.interactive default). " + "Use steer_specialist for mid-run steering of running jobs.",
+    inputSchema: resumeSpecialistSchema,
     async execute(input) {
       const snap = registry2.snapshot(input.job_id);
       if (snap) {
         if (snap.status !== "waiting") {
-          return { status: "error", error: `Job is not waiting (status: ${snap.status})`, job_id: input.job_id };
+          return { status: "error", error: `Job is not waiting (status: ${snap.status}). resume is only valid in waiting state.`, job_id: input.job_id };
         }
-        const result = await registry2.followUp(input.job_id, input.message);
+        const result = await registry2.followUp(input.job_id, input.task);
         if (result.ok) {
           return { status: "resumed", job_id: input.job_id, output: result.output };
         }
         return { status: "error", error: result.error, job_id: input.job_id };
       }
-      const jobsDir = join5(process.cwd(), ".specialists", "jobs");
+      const jobsDir = join7(process.cwd(), ".specialists", "jobs");
       const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
       const status = supervisor.readStatus(input.job_id);
       if (!status) {
         return { status: "error", error: `Job not found: ${input.job_id}`, job_id: input.job_id };
       }
       if (status.status !== "waiting") {
-        return { status: "error", error: `Job is not waiting (status: ${status.status})`, job_id: input.job_id };
+        return { status: "error", error: `Job is not waiting (status: ${status.status}). resume is only valid in waiting state.`, job_id: input.job_id };
       }
       if (!status.fifo_path) {
         return { status: "error", error: "Job has no steer pipe", job_id: input.job_id };
       }
       try {
-        const payload = JSON.stringify({ type: "prompt", message: input.message }) + `
+        const payload = JSON.stringify({ type: "resume", task: input.task }) + `
 `;
         writeFileSync3(status.fifo_path, payload, { flag: "a" });
-        return { status: "sent", job_id: input.job_id, message: input.message };
+        return { status: "sent", job_id: input.job_id, task: input.task };
       } catch (err) {
         return { status: "error", error: `Failed to write to steer pipe: ${err?.message}`, job_id: input.job_id };
       }
@@ -29366,19 +30641,92 @@ function createFollowUpSpecialistTool(registry2) {
   };
 }
 
+// src/tools/specialist/follow_up_specialist.tool.ts
+var followUpSpecialistSchema = exports_external.object({
+  job_id: exports_external.string().describe("Job ID of a waiting keep-alive specialist session"),
+  message: exports_external.string().describe("Next prompt to send to the specialist (conversation history is retained)")
+});
+function createFollowUpSpecialistTool(registry2) {
+  const resumeTool = createResumeSpecialistTool(registry2);
+  return {
+    name: "follow_up_specialist",
+    description: "[DEPRECATED] Use resume_specialist instead. " + "Delegates to resume_specialist with a deprecation warning.",
+    inputSchema: followUpSpecialistSchema,
+    async execute(input) {
+      console.error("[specialists] DEPRECATED: follow_up_specialist is deprecated. Use resume_specialist instead.");
+      return resumeTool.execute({ job_id: input.job_id, task: input.message });
+    }
+  };
+}
+
+// src/tools/specialist/feed_specialist.tool.ts
+init_zod();
+init_timeline_query();
+import { existsSync as existsSync6, readFileSync as readFileSync4 } from "node:fs";
+import { join as join9 } from "node:path";
+var feedSpecialistSchema = objectType({
+  job_id: stringType().describe("Job ID returned by start_specialist or printed by specialists run"),
+  cursor: numberType().int().min(0).optional().default(0).describe("Event index offset from previous call. Pass next_cursor from the last response to receive only new events. Omit (or pass 0) for the first call."),
+  limit: numberType().int().min(1).max(100).optional().default(50).describe("Maximum number of events to return per call.")
+});
+function createFeedSpecialistTool(jobsDir) {
+  return {
+    name: "feed_specialist",
+    description: "Read cursor-paginated timeline events from a specialist job's events.jsonl. " + "Returns structured event objects (run_start, meta, tool, text, run_complete, etc.) " + "with job metadata (status, specialist, model, bead_id). " + "Poll incrementally: pass next_cursor from each response as cursor on the next call. " + "When is_complete=true and has_more=false, the job is fully observed. " + "Use for structured event inspection; use specialists result <job-id> for final text output.",
+    inputSchema: feedSpecialistSchema,
+    async execute(input) {
+      const { job_id, cursor = 0, limit = 50 } = input;
+      const statusPath = join9(jobsDir, job_id, "status.json");
+      if (!existsSync6(statusPath)) {
+        return { error: `Job not found: ${job_id}`, job_id };
+      }
+      let status = "unknown";
+      let specialist = "unknown";
+      let model;
+      let bead_id;
+      try {
+        const s = JSON.parse(readFileSync4(statusPath, "utf-8"));
+        status = s.status ?? "unknown";
+        specialist = s.specialist ?? "unknown";
+        model = s.model;
+        bead_id = s.bead_id;
+      } catch {}
+      const allEvents = readJobEventsById(jobsDir, job_id);
+      const total = allEvents.length;
+      const sliced = allEvents.slice(cursor, cursor + limit);
+      const next_cursor = cursor + sliced.length;
+      const has_more = next_cursor < total;
+      const is_complete = isJobComplete(allEvents);
+      return {
+        job_id,
+        specialist,
+        specialist_model: formatSpecialistModel(specialist, model),
+        ...model !== undefined ? { model } : {},
+        status,
+        ...bead_id !== undefined ? { bead_id } : {},
+        events: sliced,
+        cursor,
+        next_cursor,
+        has_more,
+        is_complete
+      };
+    }
+  };
+}
+
 // src/server.ts
 init_zod();
 
 // src/tools/specialist/specialist_init.tool.ts
 init_zod();
 import { spawnSync as spawnSync4 } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
-import { join as join6 } from "node:path";
+import { existsSync as existsSync7 } from "node:fs";
+import { join as join10 } from "node:path";
 var specialistInitSchema = objectType({});
 function createSpecialistInitTool(loader, deps) {
   const resolved = deps ?? {
     bdAvailable: () => spawnSync4("bd", ["--version"], { stdio: "ignore" }).status === 0,
-    beadsExists: () => existsSync5(join6(process.cwd(), ".beads")),
+    beadsExists: () => existsSync7(join10(process.cwd(), ".beads")),
     bdInit: () => spawnSync4("bd", ["init"], { stdio: "ignore" })
   };
   return {
@@ -29413,22 +30761,24 @@ class SpecialistsServer {
     const circuitBreaker = new CircuitBreaker;
     const loader = new SpecialistLoader;
     const hooks = new HookEmitter({
-      tracePath: join7(process.cwd(), ".specialists", "trace.jsonl")
+      tracePath: join11(process.cwd(), ".specialists", "trace.jsonl")
     });
     const beadsClient = new BeadsClient;
     const runner = new SpecialistRunner({ loader, hooks, circuitBreaker, beadsClient });
     const registry2 = new JobRegistry;
+    const jobsDir = join11(process.cwd(), ".specialists", "jobs");
     this.tools = [
       createListSpecialistsTool(loader),
       createUseSpecialistTool(runner),
       createRunParallelTool(runner),
       createSpecialistStatusTool(loader, circuitBreaker),
-      createStartSpecialistTool(runner, registry2),
-      createPollSpecialistTool(registry2),
-      createStopSpecialistTool(registry2),
+      createStartSpecialistTool(runner, beadsClient),
+      createStopSpecialistTool(),
       createSteerSpecialistTool(registry2),
+      createResumeSpecialistTool(registry2),
       createFollowUpSpecialistTool(registry2),
-      createSpecialistInitTool(loader)
+      createSpecialistInitTool(loader),
+      createFeedSpecialistTool(jobsDir)
     ];
     this.server = new Server({ name: MCP_CONFIG.SERVER_NAME, version: MCP_CONFIG.VERSION }, { capabilities: MCP_CONFIG.CAPABILITIES });
     this.setupHandlers();
@@ -29441,11 +30791,12 @@ class SpecialistsServer {
       run_parallel: runParallelSchema,
       specialist_status: exports_external.object({}),
       start_specialist: startSpecialistSchema,
-      poll_specialist: pollSpecialistSchema,
       stop_specialist: stopSpecialistSchema,
       steer_specialist: steerSpecialistSchema,
+      resume_specialist: resumeSpecialistSchema,
       follow_up_specialist: followUpSpecialistSchema,
-      specialist_init: specialistInitSchema
+      specialist_init: specialistInitSchema,
+      feed_specialist: feedSpecialistSchema
     };
     this.toolSchemas = schemaMap;
     this.server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -29517,7 +30868,7 @@ var next = process.argv[3];
 function wantsHelp() {
   return next === "--help" || next === "-h";
 }
-async function run20() {
+async function run23() {
   if (sub === "install") {
     if (wantsHelp()) {
       console.log([
@@ -29656,6 +31007,7 @@ async function run20() {
       console.log([
         "",
         "Usage: specialists edit <name> --<field> <value> [options]",
+        "       specialists edit --all",
         "",
         "Edit a field in a .specialist.yaml without opening the file.",
         "",
@@ -29670,11 +31022,13 @@ async function run20() {
         "Options:",
         "  --dry-run                Preview the change without writing",
         "  --scope <default|user>   Disambiguate if same name exists in multiple scopes",
+        "  --all                    Open all YAML files in config/specialists/ in $EDITOR",
         "",
         "Examples:",
         "  specialists edit code-review --model anthropic/claude-opus-4-6",
         "  specialists edit code-review --permission HIGH --dry-run",
         "  specialists edit code-review --tags analysis,security",
+        "  specialists edit --all",
         ""
       ].join(`
 `));
@@ -29683,6 +31037,34 @@ async function run20() {
     const { run: handler } = await Promise.resolve().then(() => (init_edit(), exports_edit));
     return handler();
   }
+  if (sub === "config") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists config <get|set> <key> [value] [options]",
+        "",
+        "Batch-read or batch-update specialist YAML config in config/specialists/.",
+        "",
+        "Commands:",
+        "  get <key>                 Show a key across all specialists",
+        "  set <key> <value>         Set a key across all specialists",
+        "",
+        "Options:",
+        "  --all                     Apply to all specialists (default when --name omitted)",
+        "  --name <specialist>       Target one specialist",
+        "",
+        "Examples:",
+        "  specialists config get specialist.execution.stall_timeout_ms",
+        "  specialists config set specialist.execution.stall_timeout_ms 180000",
+        "  specialists config set specialist.execution.stall_timeout_ms 120000 --name executor",
+        ""
+      ].join(`
+`));
+      return;
+    }
+    const { run: handler } = await Promise.resolve().then(() => (init_config(), exports_config));
+    return handler();
+  }
   if (sub === "run") {
     if (wantsHelp()) {
       console.log([
@@ -29700,6 +31082,7 @@ async function run20() {
         "  --prompt <text>      Ad-hoc prompt for untracked work",
         "  --context-depth <n>  Dependency context depth when using --bead (default: 1)",
         "  --no-beads           Do not create a new tracking bead (does not disable bead reading)",
+        "  --no-bead-notes      Do not append completion notes to an external --bead",
         "  --model <model>      Override the configured model for this run",
         "  --keep-alive         Keep session alive for follow-up prompts",
         "",
@@ -29713,10 +31096,10 @@ async function run20() {
         "  Use --bead for tracked work.",
         "  Use --prompt for quick ad-hoc work.",
         "",
-        "Background execution:",
-        "  Use Claude Code's native backgrounding (run_in_background: true)",
-        "  or run in a separate terminal and poll with:",
-        "    specialists poll <job-id> --json",
+        "Async execution patterns:",
+        "  MCP:   start_specialist + feed_specialist",
+        "  CLI:   run prints [job started: <id>] on stderr, then use feed/poll/result",
+        '  Shell: specialists run <name> --prompt "..." &',
         ""
       ].join(`
 `));
@@ -29760,7 +31143,7 @@ async function run20() {
         "",
         "Usage: specialists result <job-id>",
         "",
-        "Print the final output of a completed background job.",
+        "Print the final output of a completed job.",
         "Exits with code 1 if the job is still running or failed.",
         "",
         "Examples:",
@@ -29785,7 +31168,7 @@ async function run20() {
         "Usage: specialists feed <job-id> [options]",
         "       specialists feed -f [--forever]",
         "",
-        "Read background job events.",
+        "Read job events.",
         "",
         "Modes:",
         "  specialists feed <job-id>        Replay events for one job",
@@ -29880,35 +31263,82 @@ async function run20() {
     const { run: handler } = await Promise.resolve().then(() => (init_steer(), exports_steer));
     return handler();
   }
-  if (sub === "follow-up") {
+  if (sub === "resume") {
     if (wantsHelp()) {
       console.log([
         "",
-        'Usage: specialists follow-up <job-id> "<message>"',
+        'Usage: specialists resume <job-id> "<task>"',
         "",
-        "Send a follow-up prompt to a waiting keep-alive specialist session.",
+        "Resume a waiting keep-alive specialist session with a next-turn prompt.",
         "The Pi session retains full conversation history between turns.",
         "",
         "Requires: job started with --keep-alive.",
         "",
         "Examples:",
-        '  specialists follow-up a1b2c3 "Now write the fix for the bug you found"',
-        '  specialists follow-up a1b2c3 "Focus only on the auth module"',
+        '  specialists resume a1b2c3 "Now write the fix for the bug you found"',
+        '  specialists resume a1b2c3 "Focus only on the auth module"',
         "",
         "Workflow:",
         "  specialists run debugger --bead <id> --keep-alive",
         "  # → Job started: a1b2c3  (status: waiting after first turn)",
-        "  specialists result a1b2c3            # read first turn output",
-        '  specialists follow-up a1b2c3 "..."   # send next prompt',
-        "  specialists feed a1b2c3 --follow      # watch response",
+        "  specialists result a1b2c3          # read first turn output",
+        '  specialists resume a1b2c3 "..."    # send next task',
+        "  specialists feed a1b2c3 --follow   # watch response",
+        "",
+        "See also: specialists steer (mid-run redirect for running jobs)",
+        ""
+      ].join(`
+`));
+      return;
+    }
+    const { run: handler } = await Promise.resolve().then(() => (init_resume(), exports_resume));
+    return handler();
+  }
+  if (sub === "follow-up") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "⚠ DEPRECATED: Use `specialists resume` instead.",
+        "",
+        'Usage: specialists follow-up <job-id> "<task>"',
         "",
-        "See also: specialists steer (mid-run redirect)",
+        "Delegates to `specialists resume`. This alias will be removed in a future release.",
+        ""
+      ].join(`
+`));
+      return;
+    }
+    const { run: handler } = await Promise.resolve().then(() => exports_follow_up);
+    return handler();
+  }
+  if (sub === "clean") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists clean [--all] [--keep <n>] [--dry-run]",
+        "",
+        "Purge completed job directories from .specialists/jobs/.",
+        "",
+        "Default behavior:",
+        "  - removes done/error jobs older than SPECIALISTS_JOB_TTL_DAYS",
+        "  - TTL defaults to 7 days if env is unset",
+        "",
+        "Options:",
+        "  --all        Remove all done/error jobs regardless of age",
+        "  --keep <n>   Keep only the N most recent done/error jobs",
+        "  --dry-run    Show what would be removed without deleting",
+        "",
+        "Examples:",
+        "  specialists clean",
+        "  specialists clean --all",
+        "  specialists clean --keep 20",
+        "  specialists clean --dry-run",
         ""
       ].join(`
 `));
       return;
     }
-    const { run: handler } = await Promise.resolve().then(() => (init_follow_up(), exports_follow_up));
+    const { run: handler } = await Promise.resolve().then(() => (init_clean(), exports_clean));
     return handler();
   }
   if (sub === "stop") {
@@ -29993,7 +31423,7 @@ Run 'specialists help' to see available commands.`);
   const server = new SpecialistsServer;
   await server.start();
 }
-run20().catch((error2) => {
+run23().catch((error2) => {
   logger.error(`Fatal error: ${error2}`);
   process.exit(1);
 });