@jaggerxtrm/specialists 3.2.0 → 3.3.0

package/dist/index.js

@@ -8531,6 +8531,7 @@ var require_limitLength = __commonJS((exports) => {
 var require_pattern = __commonJS((exports) => {
   Object.defineProperty(exports, "__esModule", { value: true });
   var code_1 = require_code2();
+  var util_1 = require_util();
   var codegen_1 = require_codegen();
   var error2 = {
     message: ({ schemaCode }) => (0, codegen_1.str)`must match pattern "${schemaCode}"`,
@@ -8543,10 +8544,18 @@ var require_pattern = __commonJS((exports) => {
     $data: true,
     error: error2,
     code(cxt) {
-      const { data, $data, schema, schemaCode, it } = cxt;
+      const { gen, data, $data, schema, schemaCode, it } = cxt;
       const u = it.opts.unicodeRegExp ? "u" : "";
-      const regExp = $data ? (0, codegen_1._)`(new RegExp(${schemaCode}, ${u}))` : (0, code_1.usePattern)(cxt, schema);
-      cxt.fail$data((0, codegen_1._)`!${regExp}.test(${data})`);
+      if ($data) {
+        const { regExp } = it.opts.code;
+        const regExpCode = regExp.code === "new RegExp" ? (0, codegen_1._)`new RegExp` : (0, util_1.useFunc)(gen, regExp);
+        const valid = gen.let("valid");
+        gen.try(() => gen.assign(valid, (0, codegen_1._)`${regExpCode}(${schemaCode}, ${u}).test(${data})`), () => gen.assign(valid, false));
+        cxt.fail$data((0, codegen_1._)`!${valid}`);
+      } else {
+        const regExp = (0, code_1.usePattern)(cxt, schema);
+        cxt.fail$data((0, codegen_1._)`!${regExp}.test(${data})`);
+      }
     }
   };
   exports.default = def;
@@ -17414,7 +17423,7 @@ async function parseSpecialist(yamlContent) {
   const raw = $parse(yamlContent);
   return SpecialistSchema.parseAsync(raw);
 }
-var KebabCase, Semver, MetadataSchema, ExecutionSchema, PromptSchema2, SkillsSchema, CapabilitiesSchema, CommunicationSchema, ValidationSchema, SpecialistSchema;
+var KebabCase, Semver, MetadataSchema, ExecutionSchema, PromptSchema2, ScriptEntrySchema, SkillsSchema, CapabilitiesSchema, CommunicationSchema, ValidationSchema, SpecialistSchema;
 var init_schema = __esm(() => {
   init_zod();
   init_dist();
@@ -17438,6 +17447,7 @@ var init_schema = __esm(() => {
     stall_timeout_ms: numberType().optional(),
     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(),
     preferred_profile: stringType().optional(),
     approval_mode: stringType().optional()
   });
@@ -17449,27 +17459,26 @@ var init_schema = __esm(() => {
     examples: arrayType(unknownType()).optional(),
     skill_inherit: stringType().optional()
   });
+  ScriptEntrySchema = objectType({
+    run: stringType().optional(),
+    path: stringType().optional(),
+    phase: enumType(["pre", "post"]),
+    inject_output: booleanType().default(false)
+  }).transform((s) => ({
+    run: s.run ?? s.path ?? "",
+    phase: s.phase,
+    inject_output: s.inject_output
+  }));
   SkillsSchema = objectType({
-    scripts: arrayType(objectType({
-      path: stringType(),
-      phase: enumType(["pre", "post"]),
-      inject_output: booleanType().default(false)
-    })).optional(),
-    references: arrayType(unknownType()).optional(),
-    tools: arrayType(stringType()).optional(),
-    paths: arrayType(stringType()).optional()
+    paths: arrayType(stringType()).optional(),
+    scripts: arrayType(ScriptEntrySchema).optional()
   }).optional();
   CapabilitiesSchema = objectType({
-    file_scope: arrayType(stringType()).optional(),
-    blocked_tools: arrayType(stringType()).optional(),
-    can_spawn: booleanType().optional(),
-    tools: arrayType(objectType({ name: stringType(), purpose: stringType() })).optional(),
-    diagnostic_scripts: arrayType(stringType()).optional()
+    required_tools: arrayType(stringType()).optional(),
+    external_commands: arrayType(stringType()).optional()
   }).optional();
   CommunicationSchema = objectType({
-    publishes: arrayType(stringType()).optional(),
-    subscribes: arrayType(stringType()).optional(),
-    output_to: stringType().optional()
+    next_specialists: unionType([stringType(), arrayType(stringType())]).optional()
   }).optional();
   ValidationSchema = objectType({
     files_to_watch: arrayType(stringType()).optional(),
@@ -17485,6 +17494,7 @@ var init_schema = __esm(() => {
       capabilities: CapabilitiesSchema,
       communication: CommunicationSchema,
       validation: ValidationSchema,
+      output_file: stringType().optional(),
       beads_integration: enumType(["auto", "always", "never"]).default("auto"),
       heartbeat: unknownType().optional()
     })
@@ -17494,7 +17504,6 @@ var init_schema = __esm(() => {
 // src/specialist/loader.ts
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { existsSync } from "node:fs";
 async function checkStaleness(summary) {
   if (!summary.filestoWatch?.length || !summary.updated)
@@ -17518,18 +17527,15 @@ async function checkStaleness(summary) {
 class SpecialistLoader {
   cache = new Map;
   projectDir;
-  userDir;
   constructor(options = {}) {
     this.projectDir = options.projectDir ?? process.cwd();
-    this.userDir = options.userDir ?? join(homedir(), ".agents", "specialists");
   }
   getScanDirs() {
-    return [
-      { path: join(this.projectDir, "specialists"), scope: "project" },
-      { path: join(this.projectDir, ".claude", "specialists"), scope: "project" },
-      { path: join(this.projectDir, ".agent-forge", "specialists"), scope: "project" },
-      { path: this.userDir, scope: "user" }
-    ].filter((d) => existsSync(d.path));
+    const dirs = [
+      { path: join(this.projectDir, ".specialists", "user", "specialists"), scope: "user" },
+      { path: join(this.projectDir, ".specialists", "default", "specialists"), scope: "default" }
+    ];
+    return dirs.filter((d) => existsSync(d.path));
   }
   async list(category) {
     const results = [];
@@ -17559,7 +17565,11 @@ class SpecialistLoader {
             filestoWatch: spec.specialist.validation?.files_to_watch,
             staleThresholdDays: spec.specialist.validation?.stale_threshold_days
           });
-        } catch {}
+        } catch (e) {
+          const reason = e instanceof Error ? e.message : String(e);
+          process.stderr.write(`[specialists] skipping ${filePath}: ${reason}
+`);
+        }
       }
     }
     return results;
@@ -17574,11 +17584,10 @@ class SpecialistLoader {
         const spec = await parseSpecialist(content);
         const rawPaths = spec.specialist.skills?.paths;
         if (rawPaths?.length) {
-          const home = homedir();
           const fileDir = dir.path;
           const resolved = rawPaths.map((p) => {
             if (p.startsWith("~/"))
-              return join(home, p.slice(2));
+              return join(process.env.HOME || "", p.slice(2));
             if (p.startsWith("./"))
               return join(fileDir, p.slice(2));
             return p;
@@ -17640,14 +17649,17 @@ var init_backendMap = __esm(() => {
 
 // src/pi/session.ts
 import { spawn } from "node:child_process";
+import { existsSync as existsSync2 } from "node:fs";
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
 function mapPermissionToTools(level) {
   switch (level?.toUpperCase()) {
     case "READ_ONLY":
-      return "read,bash,grep,find,ls";
-    case "BASH_ONLY":
-      return "bash";
+      return "read,grep,find,ls";
     case "LOW":
+      return "read,bash,grep,find,ls";
     case "MEDIUM":
+      return "read,bash,edit,grep,find,ls";
     case "HIGH":
       return "read,bash,edit,write,grep,find,ls";
     default:
@@ -17659,6 +17671,7 @@ class PiAgentSession {
   options;
   proc;
   _lastOutput = "";
+  _donePromise;
   _doneResolve;
   _doneReject;
   _agentEndReceived = false;
@@ -17686,6 +17699,7 @@ class PiAgentSession {
     const args = [
       "--mode",
       "rpc",
+      "--no-extensions",
       ...providerArgs,
       "--no-session",
       ...extraArgs
@@ -17693,11 +17707,28 @@ class PiAgentSession {
     const toolsFlag = mapPermissionToTools(this.options.permissionLevel);
     if (toolsFlag)
       args.push("--tools", toolsFlag);
+    if (this.options.thinkingLevel) {
+      args.push("--thinking", this.options.thinkingLevel);
+    }
+    for (const skillPath of this.options.skillPaths ?? []) {
+      args.push("--skill", skillPath);
+    }
+    const piExtDir = join2(homedir(), ".pi", "agent", "extensions");
+    const permLevel = (this.options.permissionLevel ?? "").toUpperCase();
+    if (permLevel !== "READ_ONLY") {
+      const qgPath = join2(piExtDir, "quality-gates");
+      if (existsSync2(qgPath))
+        args.push("-e", qgPath);
+    }
+    const ssPath = join2(piExtDir, "service-skills");
+    if (existsSync2(ssPath))
+      args.push("-e", ssPath);
     if (this.options.systemPrompt) {
       args.push("--append-system-prompt", this.options.systemPrompt);
     }
     this.proc = spawn("pi", args, {
-      stdio: ["pipe", "pipe", "inherit"]
+      stdio: ["pipe", "pipe", "inherit"],
+      cwd: this.options.cwd
     });
     const donePromise = new Promise((resolve, reject) => {
       this._doneResolve = resolve;
@@ -17759,34 +17790,11 @@ class PiAgentSession {
         this._lastOutput = last.content.filter((c) => c.type === "text").map((c) => c.text).join("");
       }
       this._agentEndReceived = true;
-      this.options.onEvent?.("done");
+      this.options.onEvent?.("agent_end");
       this._doneResolve?.();
       return;
     }
-    if (type === "thinking_start") {
-      this.options.onEvent?.("thinking");
-      return;
-    }
-    if (type === "thinking_delta") {
-      if (event.delta)
-        this.options.onThinking?.(event.delta);
-      this.options.onEvent?.("thinking");
-      return;
-    }
-    if (type === "thinking_end") {
-      return;
-    }
-    if (type === "toolcall_start") {
-      this.options.onToolStart?.(event.name ?? event.toolName ?? "tool");
-      this.options.onEvent?.("toolcall");
-      return;
-    }
-    if (type === "toolcall_end") {
-      this.options.onEvent?.("toolcall");
-      return;
-    }
     if (type === "tool_execution_start") {
-      this.options.onToolStart?.(event.name ?? event.toolName ?? "tool");
       this.options.onEvent?.("tool_execution");
       return;
     }
@@ -17795,7 +17803,7 @@ class PiAgentSession {
       return;
     }
     if (type === "tool_execution_end") {
-      this.options.onToolEnd?.(event.name ?? event.toolName ?? "tool");
+      this.options.onToolEnd?.(event.toolName ?? event.name ?? "tool");
       this.options.onEvent?.("tool_execution_end");
       return;
     }
@@ -17803,9 +17811,30 @@ class PiAgentSession {
       const ae = event.assistantMessageEvent;
       if (!ae)
         return;
-      if (ae.type === "text_delta" && ae.delta) {
-        this.options.onToken?.(ae.delta);
-        this.options.onEvent?.("text");
+      switch (ae.type) {
+        case "text_delta":
+          if (ae.delta)
+            this.options.onToken?.(ae.delta);
+          this.options.onEvent?.("text");
+          break;
+        case "thinking_start":
+          this.options.onEvent?.("thinking");
+          break;
+        case "thinking_delta":
+          if (ae.delta)
+            this.options.onThinking?.(ae.delta);
+          this.options.onEvent?.("thinking");
+          break;
+        case "toolcall_start":
+          this.options.onToolStart?.(ae.name ?? ae.toolName ?? "tool");
+          this.options.onEvent?.("toolcall");
+          break;
+        case "toolcall_end":
+          this.options.onEvent?.("toolcall");
+          break;
+        case "done":
+          this.options.onEvent?.("message_done");
+          break;
       }
     }
   }
@@ -17831,7 +17860,7 @@ class PiAgentSession {
     this.proc?.stdin?.write(msg);
   }
   async waitForDone(timeout) {
-    const donePromise = this._donePromise;
+    const donePromise = this._donePromise ?? Promise.resolve();
     if (!timeout)
       return donePromise;
     return Promise.race([
@@ -17868,7 +17897,7 @@ class PiAgentSession {
     if (this._killed)
       return;
     this.proc?.stdin?.end();
-    await this._donePromise.catch(() => {});
+    await this._donePromise?.catch(() => {});
   }
   kill() {
     if (this._killed)
@@ -17878,6 +17907,30 @@ class PiAgentSession {
     this.proc = undefined;
     this._doneReject?.(new SessionKilledError);
   }
+  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());
+    });
+  }
+  async resume(task, timeout) {
+    if (this._killed || !this.proc?.stdin) {
+      throw new Error("Session is not active");
+    }
+    this._agentEndReceived = false;
+    const donePromise = new Promise((resolve, reject) => {
+      this._doneResolve = resolve;
+      this._doneReject = reject;
+    });
+    donePromise.catch(() => {});
+    this._donePromise = donePromise;
+    await this.prompt(task);
+    await this.waitForDone(timeout);
+  }
 }
 var SessionKilledError;
 var init_session = __esm(() => {
@@ -17892,6 +17945,29 @@ var init_session = __esm(() => {
 
 // src/specialist/beads.ts
 import { spawnSync } from "node:child_process";
+function buildBeadContext(bead, completedBlockers = []) {
+  const lines = [`# Task: ${bead.title}`];
+  if (bead.description?.trim()) {
+    lines.push(bead.description.trim());
+  }
+  if (bead.notes?.trim()) {
+    lines.push("", "## Notes", bead.notes.trim());
+  }
+  if (completedBlockers.length > 0) {
+    lines.push("", "## Context from completed dependencies:");
+    for (const blocker of completedBlockers) {
+      lines.push("", `### ${blocker.title} (${blocker.id})`);
+      if (blocker.description?.trim()) {
+        lines.push(blocker.description.trim());
+      }
+      if (blocker.notes?.trim()) {
+        lines.push("", blocker.notes.trim());
+      }
+    }
+  }
+  return lines.join(`
+`).trim();
+}
 
 class BeadsClient {
   available;
@@ -17917,12 +17993,66 @@ class BeadsClient {
     const id = result.stdout?.trim();
     return id || null;
   }
+  readBead(id) {
+    if (!this.available || !id)
+      return null;
+    const result = spawnSync("bd", ["show", id, "--json"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+    if (result.error || result.status !== 0 || !result.stdout?.trim())
+      return null;
+    try {
+      const parsed = JSON.parse(result.stdout);
+      const bead = Array.isArray(parsed) ? parsed[0] : parsed;
+      if (!bead || typeof bead !== "object" || typeof bead.id !== "string" || typeof bead.title !== "string")
+        return null;
+      return bead;
+    } catch (err) {
+      console.warn(`[specialists] readBead: JSON parse failed for id=${id}: ${err}`);
+      return null;
+    }
+  }
+  getCompletedBlockers(id, depth = 1) {
+    if (!this.available || !id || depth < 1)
+      return [];
+    const result = spawnSync("bd", ["dep", "list", id, "--json"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+    if (result.error || result.status !== 0 || !result.stdout?.trim())
+      return [];
+    let deps;
+    try {
+      deps = JSON.parse(result.stdout);
+      if (!Array.isArray(deps))
+        return [];
+    } catch {
+      return [];
+    }
+    const blockers = deps.filter((d) => d.dependency_type === "blocks" && d.status === "closed");
+    const records = [];
+    for (const dep of blockers) {
+      const record3 = this.readBead(dep.id);
+      if (record3) {
+        records.push(record3);
+        if (depth > 1) {
+          records.push(...this.getCompletedBlockers(dep.id, depth - 1));
+        }
+      }
+    }
+    return records;
+  }
+  addDependency(trackingBeadId, inputBeadId) {
+    if (!this.available || !trackingBeadId || !inputBeadId)
+      return;
+    spawnSync("bd", ["dep", "add", trackingBeadId, inputBeadId], { stdio: "ignore" });
+  }
   closeBead(id, status, durationMs, model) {
     if (!this.available || !id)
       return;
     const reason = `${status}, ${Math.round(durationMs)}ms, ${model}`;
     spawnSync("bd", ["close", id, "-r", reason], { stdio: "ignore" });
   }
+  updateBeadNotes(id, notes) {
+    if (!this.available || !id || !notes)
+      return;
+    spawnSync("bd", ["update", id, "--notes", notes], { stdio: "ignore" });
+  }
   auditBead(id, toolName, model, exitCode) {
     if (!this.available || !id)
       return;
@@ -17954,14 +18084,16 @@ var init_beads = () => {};
 // src/specialist/runner.ts
 import { createHash } from "node:crypto";
 import { writeFile } from "node:fs/promises";
-import { execSync } from "node:child_process";
-import { basename } from "node:path";
-function runScript(scriptPath) {
+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) {
   try {
-    const output = execSync(scriptPath, { encoding: "utf8", timeout: 30000 });
-    return { name: basename(scriptPath), output, exitCode: 0 };
+    const output = execSync(run, { encoding: "utf8", timeout: 30000 });
+    return { name: basename(run.split(" ")[0]), output, exitCode: 0 };
   } catch (e) {
-    return { name: basename(scriptPath), output: e.stdout ?? e.message ?? "", exitCode: e.status ?? 1 };
+    return { name: basename(run.split(" ")[0]), output: e.stdout ?? e.message ?? "", exitCode: e.status ?? 1 };
   }
 }
 function formatScriptOutput(results) {
@@ -17979,6 +18111,77 @@ ${r.output.trim()}
 ${blocks}
 </pre_flight_context>`;
 }
+function resolvePath(p) {
+  return p.startsWith("~/") ? resolve(homedir2(), p.slice(2)) : resolve(p);
+}
+function commandExists(cmd) {
+  const result = spawnSync2("which", [cmd], { stdio: "ignore" });
+  return result.status === 0;
+}
+function validateShebang(filePath, errors5) {
+  try {
+    const head = readFileSync(filePath, "utf-8").slice(0, 120);
+    if (!head.startsWith("#!"))
+      return;
+    const shebang = head.split(`
+`)[0].toLowerCase();
+    const typos = [
+      [/pytho[^n]|pyton|pyhon/, "python"],
+      [/nod[^e]b/, "node"],
+      [/bsh$|bas$/, "bash"],
+      [/rub[^y]/, "ruby"]
+    ];
+    for (const [pattern, correct] of typos) {
+      if (pattern.test(shebang)) {
+        errors5.push(`  ✗ ${filePath}: shebang looks wrong — did you mean '${correct}'? (got: ${shebang})`);
+      }
+    }
+  } catch {}
+}
+function validateBeforeRun(spec) {
+  const errors5 = [];
+  const warnings = [];
+  for (const p of spec.specialist.skills?.paths ?? []) {
+    const abs = resolvePath(p);
+    if (!existsSync3(abs))
+      warnings.push(`  ⚠ skills.paths: file not found: ${p}`);
+  }
+  for (const script of spec.specialist.skills?.scripts ?? []) {
+    const { run } = script;
+    if (!run)
+      continue;
+    const isFilePath = run.startsWith("./") || run.startsWith("../") || run.startsWith("/") || run.startsWith("~/");
+    if (isFilePath) {
+      const abs = resolvePath(run);
+      if (!existsSync3(abs)) {
+        errors5.push(`  ✗ skills.scripts: script not found: ${run}`);
+      } else {
+        validateShebang(abs, errors5);
+      }
+    } else {
+      const binary = run.split(" ")[0];
+      if (!commandExists(binary)) {
+        errors5.push(`  ✗ skills.scripts: command not found on PATH: ${binary}`);
+      }
+    }
+  }
+  for (const cmd of spec.specialist.capabilities?.external_commands ?? []) {
+    if (!commandExists(cmd)) {
+      errors5.push(`  ✗ capabilities.external_commands: not found on PATH: ${cmd}`);
+    }
+  }
+  if (warnings.length > 0) {
+    process.stderr.write(`[specialists] pre-run warnings:
+${warnings.join(`
+`)}
+`);
+  }
+  if (errors5.length > 0) {
+    throw new Error(`Specialist pre-run validation failed:
+${errors5.join(`
+`)}`);
+  }
+}
 
 class SpecialistRunner {
   deps;
@@ -17987,12 +18190,12 @@ class SpecialistRunner {
     this.deps = deps;
     this.sessionFactory = deps.sessionFactory ?? PiAgentSession.create.bind(PiAgentSession);
   }
-  async run(options, onProgress, onEvent, onMeta, onKillRegistered, onBeadCreated) {
+  async run(options, onProgress, onEvent, onMeta, onKillRegistered, onBeadCreated, onSteerRegistered, onResumeReady) {
     const { loader, hooks, circuitBreaker, beadsClient } = this.deps;
     const invocationId = crypto.randomUUID();
     const start = Date.now();
     const spec = await loader.get(options.name);
-    const { metadata, execution, prompt, communication } = spec.specialist;
+    const { metadata, execution, prompt, output_file } = spec.specialist;
     const primaryModel = options.backendOverride ?? execution.model;
     const model = circuitBreaker.isAvailable(primaryModel) ? primaryModel : execution.fallback_model ?? primaryModel;
     const fallbackUsed = model !== primaryModel;
@@ -18003,10 +18206,18 @@ class SpecialistRunner {
       circuit_breaker_state: circuitBreaker.getState(model),
       scope: "project"
     });
+    validateBeforeRun(spec);
     const preScripts = spec.specialist.skills?.scripts?.filter((s) => s.phase === "pre") ?? [];
-    const preResults = preScripts.map((s) => runScript(s.path)).filter((_, i) => preScripts[i].inject_output);
+    const preResults = preScripts.map((s) => runScript(s.run)).filter((_, i) => preScripts[i].inject_output);
     const preScriptOutput = formatScriptOutput(preResults);
-    const variables = { prompt: options.prompt, pre_script_output: preScriptOutput, ...options.variables };
+    const beadVariables = options.inputBeadId ? { bead_context: options.prompt, bead_id: options.inputBeadId } : {};
+    const variables = {
+      prompt: options.prompt,
+      cwd: process.cwd(),
+      pre_script_output: preScriptOutput,
+      ...options.variables ?? {},
+      ...beadVariables
+    };
     const renderedTask = renderTemplate(prompt.task_template, variables);
     const promptHash = createHash("sha256").update(renderedTask).digest("hex").slice(0, 16);
     await hooks.emit("post_render", invocationId, metadata.name, metadata.version, {
@@ -18015,40 +18226,32 @@ class SpecialistRunner {
       estimated_tokens: Math.ceil(renderedTask.length / 4),
       system_prompt_present: !!prompt.system
     });
-    const { readFile: readFile2 } = await import("node:fs/promises");
-    let agentsMd = prompt.system ?? "";
-    if (prompt.skill_inherit) {
-      const skillContent = await readFile2(prompt.skill_inherit, "utf-8").catch(() => "");
-      if (skillContent)
-        agentsMd += `
-
----
-# Service Knowledge
-
-${skillContent}`;
-    }
-    const skillPaths = spec.specialist.skills?.paths ?? [];
-    for (const skillPath of skillPaths) {
-      const skillContent = await readFile2(skillPath, "utf-8").catch(() => "");
-      if (skillContent)
-        agentsMd += `
-
----
-# Skill: ${skillPath}
-
-${skillContent}`;
-    }
-    if (spec.specialist.capabilities?.diagnostic_scripts?.length) {
-      agentsMd += `
-
----
-# Diagnostic Scripts
-You have access via Bash:
-`;
-      for (const s of spec.specialist.capabilities.diagnostic_scripts) {
-        agentsMd += `- \`${s}\`
-`;
+    const agentsMd = prompt.system ?? "";
+    const skillPaths = [];
+    if (prompt.skill_inherit)
+      skillPaths.push(prompt.skill_inherit);
+    skillPaths.push(...spec.specialist.skills?.paths ?? []);
+    if (skillPaths.length > 0 || preScripts.length > 0) {
+      const line = "━".repeat(56);
+      onProgress?.(`
+${line}
+◆ AUTO INJECTED
+`);
+      if (skillPaths.length > 0) {
+        onProgress?.(`  skills (--skill):
+${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(`
+`)}
+`);
+      }
+      onProgress?.(`${line}
+
+`);
     }
     const permissionLevel = options.autonomyLevel ?? execution.permission_required;
     await hooks.emit("pre_execute", invocationId, metadata.name, metadata.version, {
@@ -18059,19 +18262,28 @@ You have access via Bash:
     });
     const beadsIntegration = spec.specialist.beads_integration ?? "auto";
     let beadId;
-    if (beadsClient && shouldCreateBead(beadsIntegration, execution.permission_required)) {
+    let ownsBead = false;
+    if (options.inputBeadId) {
+      beadId = options.inputBeadId;
+    } else if (beadsClient && shouldCreateBead(beadsIntegration, execution.permission_required)) {
       beadId = beadsClient.createBead(metadata.name) ?? undefined;
-      if (beadId)
+      if (beadId) {
+        ownsBead = true;
         onBeadCreated?.(beadId);
+      }
     }
     let output;
     let sessionBackend = model;
     let session;
+    let keepAliveActive = false;
     try {
       session = await this.sessionFactory({
         model,
         systemPrompt: agentsMd || undefined,
+        skillPaths: skillPaths.length > 0 ? skillPaths : undefined,
+        thinkingLevel: execution.thinking_level,
         permissionLevel,
+        cwd: process.cwd(),
         onToken: (delta) => onProgress?.(delta),
         onThinking: (delta) => onProgress?.(`\uD83D\uDCAD ${delta}`),
         onToolStart: (tool) => onProgress?.(`
@@ -18083,15 +18295,29 @@ You have access via Bash:
       });
       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;
-      await session.close();
+      if (options.keepAlive && onResumeReady) {
+        keepAliveActive = true;
+        const resumeFn = async (msg) => {
+          await session.resume(msg, execution.timeout_ms);
+          return session.getLastOutput();
+        };
+        const closeFn = async () => {
+          keepAliveActive = false;
+          await session.close();
+        };
+        onResumeReady(resumeFn, closeFn);
+      } else {
+        await session.close();
+      }
       const postScripts = spec.specialist.skills?.scripts?.filter((s) => s.phase === "post") ?? [];
       for (const script of postScripts)
-        runScript(script.path);
+        runScript(script.run);
       circuitBreaker.recordSuccess(model);
     } catch (err) {
       const isCancelled = err instanceof SessionKilledError;
@@ -18100,7 +18326,8 @@ You have access via Bash:
       }
       const beadStatus = isCancelled ? "CANCELLED" : "ERROR";
       if (beadId) {
-        beadsClient?.closeBead(beadId, beadStatus, Date.now() - start, model);
+        if (ownsBead)
+          beadsClient?.closeBead(beadId, beadStatus, Date.now() - start, model);
         beadsClient?.auditBead(beadId, metadata.name, model, 1);
       }
       await hooks.emit("post_execute", invocationId, metadata.name, metadata.version, {
@@ -18111,11 +18338,13 @@ You have access via Bash:
       });
       throw err;
     } finally {
-      session?.kill();
+      if (!keepAliveActive) {
+        session?.kill();
+      }
     }
     const durationMs = Date.now() - start;
-    if (communication?.output_to) {
-      await writeFile(communication.output_to, output, "utf-8").catch(() => {});
+    if (output_file) {
+      await writeFile(output_file, output, "utf-8").catch(() => {});
     }
     await hooks.emit("post_execute", invocationId, metadata.name, metadata.version, {
       status: "COMPLETE",
@@ -18123,7 +18352,8 @@ You have access via Bash:
       output_valid: true
     });
     if (beadId) {
-      beadsClient?.closeBead(beadId, "COMPLETE", durationMs, model);
+      if (ownsBead)
+        beadsClient?.closeBead(beadId, "COMPLETE", durationMs, model);
       beadsClient?.auditBead(beadId, metadata.name, model, 0);
     }
     return {
@@ -18132,6 +18362,7 @@ You have access via Bash:
       model,
       durationMs,
       specialistVersion: metadata.version,
+      promptHash,
       beadId
     };
   }
@@ -18147,7 +18378,7 @@ You have access via Bash:
       model: "?",
       specialistVersion
     });
-    this.run(options, (text) => registry2.appendOutput(jobId, text), (eventType) => registry2.setCurrentEvent(jobId, eventType), (meta) => registry2.setMeta(jobId, meta), (killFn) => registry2.setKillFn(jobId, killFn), (beadId) => registry2.setBeadId(jobId, beadId)).then((result) => registry2.complete(jobId, result)).catch((err) => registry2.fail(jobId, err));
+    this.run(options, (text) => registry2.appendOutput(jobId, text), (eventType) => registry2.setCurrentEvent(jobId, eventType), (meta) => registry2.setMeta(jobId, meta), (killFn) => registry2.setKillFn(jobId, killFn), (beadId) => registry2.setBeadId(jobId, beadId), (steerFn) => registry2.setSteerFn(jobId, steerFn), (resumeFn, closeFn) => registry2.setResumeFn(jobId, resumeFn, closeFn)).then((result) => registry2.complete(jobId, result)).catch((err) => registry2.fail(jobId, err));
     return jobId;
   }
 }
@@ -18227,129 +18458,531 @@ class CircuitBreaker {
   }
 }
 
-// src/cli/install.ts
-var exports_install = {};
-__export(exports_install, {
-  run: () => run
-});
-import { execFileSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname as dirname2, join as join4 } from "node:path";
-async function run() {
-  const installerPath = join4(dirname2(fileURLToPath(import.meta.url)), "..", "bin", "install.js");
-  execFileSync(process.execPath, [installerPath], { stdio: "inherit" });
+// 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_end":
+      return {
+        t,
+        type: TIMELINE_EVENT_TYPES.TOOL,
+        tool: context.tool ?? "unknown",
+        phase: "end",
+        tool_call_id: context.toolCallId,
+        is_error: context.isError
+      };
+    case "text":
+      return { t, type: TIMELINE_EVENT_TYPES.TEXT };
+    case "agent_end":
+    case "message_done":
+    case "done":
+      return null;
+    default:
+      return null;
+  }
 }
-var init_install = () => {};
-
-// src/cli/version.ts
-var exports_version = {};
-__export(exports_version, {
-  run: () => run2
-});
-import { createRequire as createRequire2 } from "node:module";
-async function run2() {
-  const req = createRequire2(import.meta.url);
-  const pkg = req("../package.json");
-  console.log(`${pkg.name} v${pkg.version}`);
+function createRunStartEvent(specialist, beadId) {
+  return {
+    t: Date.now(),
+    type: TIMELINE_EVENT_TYPES.RUN_START,
+    specialist,
+    bead_id: beadId
+  };
 }
-var init_version = () => {};
-
-// src/cli/list.ts
-var exports_list = {};
-__export(exports_list, {
-  run: () => run3,
-  parseArgs: () => parseArgs,
-  ArgParseError: () => ArgParseError
-});
-function parseArgs(argv) {
-  const result = {};
-  for (let i = 0;i < argv.length; i++) {
-    const token = argv[i];
-    if (token === "--category") {
-      const value = argv[++i];
-      if (!value || value.startsWith("--")) {
-        throw new ArgParseError("--category requires a value");
-      }
-      result.category = value;
-      continue;
-    }
-    if (token === "--scope") {
-      const value = argv[++i];
-      if (value !== "project" && value !== "user") {
-        throw new ArgParseError(`--scope must be "project" or "user", got: "${value ?? ""}"`);
-      }
-      result.scope = value;
-      continue;
-    }
-    if (token === "--json") {
-      result.json = true;
-      continue;
-    }
-  }
-  return result;
+function createMetaEvent(model, backend) {
+  return {
+    t: Date.now(),
+    type: TIMELINE_EVENT_TYPES.META,
+    model,
+    backend
+  };
 }
-async function run3() {
-  let args;
+function createRunCompleteEvent(status, elapsed_s, options) {
+  return {
+    t: Date.now(),
+    type: TIMELINE_EVENT_TYPES.RUN_COMPLETE,
+    status,
+    elapsed_s,
+    ...options
+  };
+}
+function parseTimelineEvent(line) {
   try {
-    args = parseArgs(process.argv.slice(3));
-  } catch (err) {
-    if (err instanceof ArgParseError) {
-      console.error(`Error: ${err.message}`);
-      process.exit(1);
+    const parsed = JSON.parse(line);
+    if (!parsed || typeof parsed !== "object")
+      return null;
+    if (typeof parsed.t !== "number")
+      return null;
+    if (typeof parsed.type !== "string")
+      return null;
+    if (parsed.type === TIMELINE_EVENT_TYPES.DONE) {
+      return {
+        t: parsed.t,
+        type: TIMELINE_EVENT_TYPES.DONE,
+        elapsed_s: typeof parsed.elapsed_s === "number" ? parsed.elapsed_s : undefined
+      };
     }
-    throw err;
-  }
-  const loader = new SpecialistLoader;
-  let specialists = await loader.list(args.category);
-  if (args.scope) {
-    specialists = specialists.filter((s) => s.scope === args.scope);
-  }
-  if (args.json) {
-    console.log(JSON.stringify(specialists, null, 2));
-    return;
-  }
-  if (specialists.length === 0) {
-    console.log("No specialists found.");
-    return;
-  }
-  const nameWidth = Math.max(...specialists.map((s) => s.name.length), 4);
-  console.log(`
-${bold(`Specialists (${specialists.length})`)}
-`);
-  for (const s of specialists) {
-    const name = cyan(s.name.padEnd(nameWidth));
-    const scopeTag = yellow(`[${s.scope}]`);
-    const model = dim(s.model);
-    const desc = s.description.length > 80 ? s.description.slice(0, 79) + "…" : s.description;
-    console.log(`  ${name}  ${scopeTag}  ${model}`);
-    console.log(`  ${" ".repeat(nameWidth)}  ${dim(desc)}`);
-    console.log();
+    if (parsed.type === TIMELINE_EVENT_TYPES.AGENT_END) {
+      return {
+        t: parsed.t,
+        type: TIMELINE_EVENT_TYPES.AGENT_END,
+        elapsed_s: typeof parsed.elapsed_s === "number" ? parsed.elapsed_s : undefined
+      };
+    }
+    const knownTypes = Object.values(TIMELINE_EVENT_TYPES).filter((type) => type !== TIMELINE_EVENT_TYPES.DONE && type !== TIMELINE_EVENT_TYPES.AGENT_END);
+    if (!knownTypes.includes(parsed.type))
+      return null;
+    return parsed;
+  } catch {
+    return null;
   }
 }
-var dim = (s) => `\x1B[2m${s}\x1B[0m`, bold = (s) => `\x1B[1m${s}\x1B[0m`, cyan = (s) => `\x1B[36m${s}\x1B[0m`, yellow = (s) => `\x1B[33m${s}\x1B[0m`, ArgParseError;
-var init_list = __esm(() => {
-  init_loader();
-  ArgParseError = class ArgParseError extends Error {
-    constructor(message) {
-      super(message);
-      this.name = "ArgParseError";
-    }
+function isRunCompleteEvent(event) {
+  return event.type === TIMELINE_EVENT_TYPES.RUN_COMPLETE;
+}
+function compareTimelineEvents(a, b) {
+  return a.t - b.t;
+}
+var TIMELINE_EVENT_TYPES;
+var init_timeline_events = __esm(() => {
+  TIMELINE_EVENT_TYPES = {
+    RUN_START: "run_start",
+    META: "meta",
+    THINKING: "thinking",
+    TOOL: "tool",
+    TEXT: "text",
+    RUN_COMPLETE: "run_complete",
+    DONE: "done",
+    AGENT_END: "agent_end"
   };
 });
 
-// src/cli/models.ts
-var exports_models = {};
-__export(exports_models, {
-  run: () => run4
-});
-import { spawnSync as spawnSync3 } from "node:child_process";
-function parsePiModels() {
-  const r = spawnSync3("pi", ["--list-models"], {
-    encoding: "utf8",
-    stdio: "pipe",
-    timeout: 8000
-  });
-  if (r.status !== 0 || r.error)
+// src/specialist/supervisor.ts
+import {
+  closeSync,
+  existsSync as existsSync4,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync as readFileSync2,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+  writeSync
+} from "node:fs";
+import { join as join3 } from "node:path";
+import { createInterface } from "node:readline";
+import { createReadStream } from "node:fs";
+import { spawnSync as spawnSync3, execFileSync } from "node:child_process";
+function getCurrentGitSha() {
+  const result = spawnSync3("git", ["rev-parse", "HEAD"], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (result.status !== 0)
+    return;
+  const sha = result.stdout?.trim();
+  return sha || undefined;
+}
+function formatBeadNotes(result) {
+  const metadata = [
+    `prompt_hash=${result.promptHash}`,
+    `git_sha=${getCurrentGitSha() ?? "unknown"}`,
+    `elapsed_ms=${Math.round(result.durationMs)}`,
+    `model=${result.model}`,
+    `backend=${result.backend}`
+  ].join(`
+`);
+  return `${result.output}
+
+---
+${metadata}`;
+}
+
+class Supervisor {
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  jobDir(id) {
+    return join3(this.opts.jobsDir, id);
+  }
+  statusPath(id) {
+    return join3(this.jobDir(id), "status.json");
+  }
+  resultPath(id) {
+    return join3(this.jobDir(id), "result.txt");
+  }
+  eventsPath(id) {
+    return join3(this.jobDir(id), "events.jsonl");
+  }
+  readyDir() {
+    return join3(this.opts.jobsDir, "..", "ready");
+  }
+  readStatus(id) {
+    const path = this.statusPath(id);
+    if (!existsSync4(path))
+      return null;
+    try {
+      return JSON.parse(readFileSync2(path, "utf-8"));
+    } catch {
+      return null;
+    }
+  }
+  listJobs() {
+    if (!existsSync4(this.opts.jobsDir))
+      return [];
+    const jobs = [];
+    for (const entry of readdirSync(this.opts.jobsDir)) {
+      const path = join3(this.opts.jobsDir, entry, "status.json");
+      if (!existsSync4(path))
+        continue;
+      try {
+        jobs.push(JSON.parse(readFileSync2(path, "utf-8")));
+      } catch {}
+    }
+    return jobs.sort((a, b) => b.started_at_ms - a.started_at_ms);
+  }
+  writeStatusFile(id, data) {
+    const path = this.statusPath(id);
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+    renameSync(tmp, path);
+  }
+  updateStatus(id, updates) {
+    const current = this.readStatus(id);
+    if (!current)
+      return;
+    this.writeStatusFile(id, { ...current, ...updates });
+  }
+  gc() {
+    if (!existsSync4(this.opts.jobsDir))
+      return;
+    const cutoff = Date.now() - JOB_TTL_DAYS * 86400000;
+    for (const entry of readdirSync(this.opts.jobsDir)) {
+      const dir = join3(this.opts.jobsDir, entry);
+      try {
+        const stat2 = statSync(dir);
+        if (!stat2.isDirectory())
+          continue;
+        if (stat2.mtimeMs < cutoff)
+          rmSync(dir, { recursive: true, force: true });
+      } catch {}
+    }
+  }
+  crashRecovery() {
+    if (!existsSync4(this.opts.jobsDir))
+      return;
+    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);
+        }
+      } catch {}
+    }
+  }
+  async run() {
+    const { runner, runOptions, jobsDir } = this.opts;
+    this.gc();
+    this.crashRecovery();
+    const id = crypto.randomUUID().slice(0, 6);
+    const dir = this.jobDir(id);
+    const startedAtMs = Date.now();
+    mkdirSync(dir, { recursive: true });
+    mkdirSync(this.readyDir(), { recursive: true });
+    const initialStatus = {
+      id,
+      specialist: runOptions.name,
+      status: "starting",
+      started_at_ms: startedAtMs,
+      pid: process.pid
+    };
+    this.writeStatusFile(id, initialStatus);
+    const eventsFd = openSync(this.eventsPath(id), "a");
+    const appendTimelineEvent = (event) => {
+      try {
+        writeSync(eventsFd, JSON.stringify(event) + `
+`);
+      } catch {}
+    };
+    appendTimelineEvent(createRunStartEvent(runOptions.name));
+    const fifoPath = join3(dir, "steer.pipe");
+    try {
+      execFileSync("mkfifo", [fifoPath]);
+      this.updateStatus(id, { fifo_path: fifoPath });
+    } catch {}
+    let textLogged = false;
+    let currentTool = "";
+    let currentToolCallId = "";
+    let killFn;
+    let steerFn;
+    let resumeFn;
+    let closeFn;
+    const sigtermHandler = () => killFn?.();
+    process.once("SIGTERM", sigtermHandler);
+    try {
+      const result = await runner.run(runOptions, (delta) => {
+        const toolMatch = delta.match(/⚙ (.+?)…/);
+        if (toolMatch) {
+          currentTool = toolMatch[1];
+          this.updateStatus(id, { current_tool: currentTool });
+        }
+      }, (eventType) => {
+        const now = Date.now();
+        this.updateStatus(id, {
+          status: "running",
+          current_event: eventType,
+          last_event_at_ms: now,
+          elapsed_s: Math.round((now - startedAtMs) / 1000)
+        });
+        const timelineEvent = mapCallbackEventToTimelineEvent(eventType, {
+          tool: currentTool,
+          toolCallId: currentToolCallId || undefined
+        });
+        if (timelineEvent) {
+          appendTimelineEvent(timelineEvent);
+        } else if (eventType === "text" && !textLogged) {
+          textLogged = true;
+          appendTimelineEvent({ t: Date.now(), type: TIMELINE_EVENT_TYPES.TEXT });
+        }
+      }, (meta) => {
+        this.updateStatus(id, { model: meta.model, backend: meta.backend });
+        appendTimelineEvent(createMetaEvent(meta.model, meta.backend));
+      }, (fn) => {
+        killFn = fn;
+      }, (beadId) => {
+        this.updateStatus(id, { bead_id: beadId });
+      }, (fn) => {
+        steerFn = fn;
+        if (existsSync4(fifoPath)) {
+          const rl = createInterface({ input: createReadStream(fifoPath, { flags: "r+" }) });
+          rl.on("line", (line) => {
+            try {
+              const parsed = JSON.parse(line);
+              if (parsed?.type === "steer" && typeof parsed.message === "string") {
+                steerFn?.(parsed.message).catch(() => {});
+              } else if (parsed?.type === "prompt" && typeof parsed.message === "string") {
+                if (resumeFn) {
+                  this.updateStatus(id, { status: "running", current_event: "starting" });
+                  resumeFn(parsed.message).then((output) => {
+                    writeFileSync(this.resultPath(id), output, "utf-8");
+                    this.updateStatus(id, {
+                      status: "waiting",
+                      current_event: "waiting",
+                      elapsed_s: Math.round((Date.now() - startedAtMs) / 1000),
+                      last_event_at_ms: Date.now()
+                    });
+                  }).catch((err) => {
+                    this.updateStatus(id, { status: "error", error: err?.message ?? String(err) });
+                  });
+                }
+              } else if (parsed?.type === "close") {
+                closeFn?.().catch(() => {});
+              }
+            } catch {}
+          });
+          rl.on("error", () => {});
+        }
+      }, (rFn, cFn) => {
+        resumeFn = rFn;
+        closeFn = cFn;
+        this.updateStatus(id, { status: "waiting", current_event: "waiting" });
+      });
+      const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
+      writeFileSync(this.resultPath(id), result.output, "utf-8");
+      if (result.beadId) {
+        this.opts.beadsClient?.updateBeadNotes(result.beadId, formatBeadNotes(result));
+      }
+      this.updateStatus(id, {
+        status: "done",
+        elapsed_s: elapsed,
+        last_event_at_ms: Date.now(),
+        model: result.model,
+        backend: result.backend,
+        bead_id: result.beadId
+      });
+      appendTimelineEvent(createRunCompleteEvent("COMPLETE", elapsed, {
+        model: result.model,
+        backend: result.backend,
+        bead_id: result.beadId
+      }));
+      writeFileSync(join3(this.readyDir(), id), "", "utf-8");
+      return id;
+    } catch (err) {
+      const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
+      const errorMsg = err?.message ?? String(err);
+      this.updateStatus(id, {
+        status: "error",
+        elapsed_s: elapsed,
+        error: errorMsg
+      });
+      appendTimelineEvent(createRunCompleteEvent("ERROR", elapsed, {
+        error: errorMsg
+      }));
+      throw err;
+    } finally {
+      process.removeListener("SIGTERM", sigtermHandler);
+      closeSync(eventsFd);
+      try {
+        if (existsSync4(fifoPath))
+          rmSync(fifoPath);
+      } catch {}
+    }
+  }
+}
+var JOB_TTL_DAYS;
+var init_supervisor = __esm(() => {
+  init_timeline_events();
+  JOB_TTL_DAYS = Number(process.env.SPECIALISTS_JOB_TTL_DAYS ?? 7);
+});
+
+// src/cli/install.ts
+var exports_install = {};
+__export(exports_install, {
+  run: () => run
+});
+import { execFileSync as execFileSync2 } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname as dirname2, join as join8 } from "node:path";
+async function run() {
+  const installerPath = join8(dirname2(fileURLToPath(import.meta.url)), "..", "bin", "install.js");
+  execFileSync2(process.execPath, [installerPath], { stdio: "inherit" });
+}
+var init_install = () => {};
+
+// src/cli/version.ts
+var exports_version = {};
+__export(exports_version, {
+  run: () => run2
+});
+import { createRequire as createRequire2 } from "node:module";
+async function run2() {
+  const req = createRequire2(import.meta.url);
+  const pkg = req("../package.json");
+  console.log(`${pkg.name} v${pkg.version}`);
+}
+var init_version = () => {};
+
+// src/cli/list.ts
+var exports_list = {};
+__export(exports_list, {
+  run: () => run3,
+  parseArgs: () => parseArgs,
+  ArgParseError: () => ArgParseError
+});
+function parseArgs(argv) {
+  const result = {};
+  for (let i = 0;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--category") {
+      const value = argv[++i];
+      if (!value || value.startsWith("--")) {
+        throw new ArgParseError("--category requires a value");
+      }
+      result.category = value;
+      continue;
+    }
+    if (token === "--scope") {
+      const value = argv[++i];
+      if (value !== "default" && value !== "user") {
+        throw new ArgParseError(`--scope must be "default" or "user", got: "${value ?? ""}"`);
+      }
+      result.scope = value;
+      continue;
+    }
+    if (token === "--json") {
+      result.json = true;
+      continue;
+    }
+  }
+  return result;
+}
+async function run3() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(3));
+  } catch (err) {
+    if (err instanceof ArgParseError) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  const loader = new SpecialistLoader;
+  let specialists = await loader.list(args.category);
+  if (args.scope) {
+    specialists = specialists.filter((s) => s.scope === args.scope);
+  }
+  if (args.json) {
+    console.log(JSON.stringify(specialists, null, 2));
+    return;
+  }
+  if (specialists.length === 0) {
+    console.log("No specialists found.");
+    return;
+  }
+  const nameWidth = Math.max(...specialists.map((s) => s.name.length), 4);
+  console.log(`
+${bold(`Specialists (${specialists.length})`)}
+`);
+  for (const s of specialists) {
+    const name = cyan(s.name.padEnd(nameWidth));
+    const scopeTag = s.scope === "default" ? green("[default]") : yellow("[user]");
+    const model = dim(s.model);
+    const desc = s.description.length > 80 ? s.description.slice(0, 79) + "…" : s.description;
+    console.log(`  ${name}  ${scopeTag}  ${model}`);
+    console.log(`  ${" ".repeat(nameWidth)}  ${dim(desc)}`);
+    console.log();
+  }
+}
+var dim = (s) => `\x1B[2m${s}\x1B[0m`, bold = (s) => `\x1B[1m${s}\x1B[0m`, cyan = (s) => `\x1B[36m${s}\x1B[0m`, green = (s) => `\x1B[32m${s}\x1B[0m`, yellow = (s) => `\x1B[33m${s}\x1B[0m`, ArgParseError;
+var init_list = __esm(() => {
+  init_loader();
+  ArgParseError = class ArgParseError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "ArgParseError";
+    }
+  };
+});
+
+// src/cli/models.ts
+var exports_models = {};
+__export(exports_models, {
+  run: () => run4
+});
+import { spawnSync as spawnSync5 } from "node:child_process";
+function parsePiModels() {
+  const r = spawnSync5("pi", ["--list-models"], {
+    encoding: "utf8",
+    stdio: "pipe",
+    timeout: 8000
+  });
+  if (r.status !== 0 || r.error)
     return null;
   return r.stdout.split(`
 `).slice(1).map((line) => line.trim()).filter(Boolean).map((line) => {
@@ -18391,7 +19024,7 @@ async function run4() {
   }
   const allModels = parsePiModels();
   if (!allModels) {
-    console.error("pi not found or failed — run specialists install");
+    console.error("pi not found or failed — install and configure pi first");
     process.exit(1);
   }
   let models = allModels;
@@ -18422,7 +19055,7 @@ ${bold2(`Models on pi`)}  ${dim2(`(${total} total)`)}
       const key = `${m.provider}/${m.model}`;
       const inUse = usedBy.get(key);
       const flags = [
-        m.thinking ? green("thinking") : dim2("·"),
+        m.thinking ? green2("thinking") : dim2("·"),
         m.images ? dim2("images") : ""
       ].filter(Boolean).join("  ");
       const ctx = dim2(`ctx ${m.context}`);
@@ -18437,7 +19070,7 @@ ${bold2(`Models on pi`)}  ${dim2(`(${total} total)`)}
     console.log();
   }
 }
-var bold2 = (s) => `\x1B[1m${s}\x1B[0m`, dim2 = (s) => `\x1B[2m${s}\x1B[0m`, cyan2 = (s) => `\x1B[36m${s}\x1B[0m`, yellow2 = (s) => `\x1B[33m${s}\x1B[0m`, green = (s) => `\x1B[32m${s}\x1B[0m`;
+var bold2 = (s) => `\x1B[1m${s}\x1B[0m`, dim2 = (s) => `\x1B[2m${s}\x1B[0m`, cyan2 = (s) => `\x1B[36m${s}\x1B[0m`, yellow2 = (s) => `\x1B[33m${s}\x1B[0m`, green2 = (s) => `\x1B[32m${s}\x1B[0m`;
 var init_models = __esm(() => {
   init_loader();
 });
@@ -18447,77 +19080,287 @@ var exports_init = {};
 __export(exports_init, {
   run: () => run5
 });
-import { existsSync as existsSync3, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join as join5 } from "node:path";
+import { copyFileSync, cpSync, existsSync as existsSync6, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join9 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 function ok(msg) {
-  console.log(`  ${green2("✓")} ${msg}`);
+  console.log(`  ${green3("✓")} ${msg}`);
+}
+function skip(msg) {
+  console.log(`  ${yellow3("○")} ${msg}`);
+}
+function loadJson(path, fallback) {
+  if (!existsSync6(path))
+    return structuredClone(fallback);
+  try {
+    return JSON.parse(readFileSync3(path, "utf-8"));
+  } catch {
+    return structuredClone(fallback);
+  }
+}
+function saveJson(path, value) {
+  writeFileSync4(path, JSON.stringify(value, null, 2) + `
+`, "utf-8");
+}
+function resolvePackagePath(relativePath) {
+  const configPath = `config/${relativePath}`;
+  let resolved = fileURLToPath2(new URL(`../${configPath}`, import.meta.url));
+  if (existsSync6(resolved))
+    return resolved;
+  resolved = fileURLToPath2(new URL(`../../${configPath}`, import.meta.url));
+  if (existsSync6(resolved))
+    return resolved;
+  return null;
+}
+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"));
+  if (files.length === 0) {
+    skip("no specialist files found in package");
+    return;
+  }
+  if (!existsSync6(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 (existsSync6(dest)) {
+      skipped++;
+    } else {
+      copyFileSync(src, dest);
+      copied++;
+    }
+  }
+  if (copied > 0) {
+    ok(`copied ${copied} canonical specialist${copied === 1 ? "" : "s"} to .specialists/default/specialists/`);
+  }
+  if (skipped > 0) {
+    skip(`${skipped} specialist${skipped === 1 ? "" : "s"} already exist (not overwritten)`);
+  }
+}
+function copyCanonicalHooks(cwd) {
+  const sourceDir = resolvePackagePath("hooks");
+  if (!sourceDir) {
+    skip("no canonical hooks found in package");
+    return;
+  }
+  const targetDir = join9(cwd, ".specialists", "default", "hooks");
+  const hooks = readdirSync2(sourceDir).filter((f) => f.endsWith(".mjs"));
+  if (hooks.length === 0) {
+    skip("no hook files found in package");
+    return;
+  }
+  if (!existsSync6(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 (existsSync6(dest)) {
+      skipped++;
+    } else {
+      copyFileSync(src, dest);
+      copied++;
+    }
+  }
+  if (copied > 0) {
+    ok(`copied ${copied} hook${copied === 1 ? "" : "s"} to .specialists/default/hooks/`);
+  }
+  if (skipped > 0) {
+    skip(`${skipped} hook${skipped === 1 ? "" : "s"} already exist (not overwritten)`);
+  }
+}
+function ensureProjectHooks(cwd) {
+  const settingsPath = join9(cwd, ".claude", "settings.json");
+  const settingsDir = join9(cwd, ".claude");
+  if (!existsSync6(settingsDir)) {
+    mkdirSync2(settingsDir, { recursive: true });
+  }
+  const settings = loadJson(settingsPath, {});
+  let changed = false;
+  function addHook(event, command) {
+    const eventList = settings[event] ?? [];
+    settings[event] = eventList;
+    const alreadyWired = eventList.some((entry) => entry?.hooks?.some?.((h) => h?.command === command));
+    if (!alreadyWired) {
+      eventList.push({ matcher: "", hooks: [{ type: "command", command }] });
+      changed = true;
+    }
+  }
+  addHook("UserPromptSubmit", "node .specialists/default/hooks/specialists-complete.mjs");
+  addHook("SessionStart", "node .specialists/default/hooks/specialists-session-start.mjs");
+  if (changed) {
+    saveJson(settingsPath, settings);
+    ok("wired specialists hooks in .claude/settings.json");
+  } else {
+    skip(".claude/settings.json already has specialists hooks");
+  }
+}
+function copyCanonicalSkills(cwd) {
+  const sourceDir = resolvePackagePath("skills");
+  if (!sourceDir) {
+    skip("no canonical skills found in package");
+    return;
+  }
+  const skills = readdirSync2(sourceDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  if (skills.length === 0) {
+    skip("no skill directories found in package");
+    return;
+  }
+  const targetDir = join9(cwd, ".specialists", "default", "skills");
+  if (!existsSync6(targetDir)) {
+    mkdirSync2(targetDir, { recursive: true });
+  }
+  let copied = 0;
+  let skipped = 0;
+  for (const skill of skills) {
+    const src = join9(sourceDir, skill);
+    const dest = join9(targetDir, skill);
+    if (existsSync6(dest)) {
+      skipped++;
+    } else {
+      cpSync(src, dest, { recursive: true });
+      copied++;
+    }
+  }
+  if (copied > 0) {
+    ok(`copied ${copied} skill${copied === 1 ? "" : "s"} to .specialists/default/skills/`);
+  }
+  if (skipped > 0) {
+    skip(`${skipped} skill${skipped === 1 ? "" : "s"} already exist (not overwritten)`);
+  }
+}
+function createUserDirs(cwd) {
+  const userDirs = [
+    join9(cwd, ".specialists", "user", "specialists"),
+    join9(cwd, ".specialists", "user", "hooks"),
+    join9(cwd, ".specialists", "user", "skills")
+  ];
+  let created = 0;
+  for (const dir of userDirs) {
+    if (!existsSync6(dir)) {
+      mkdirSync2(dir, { recursive: true });
+      created++;
+    }
+  }
+  if (created > 0) {
+    ok("created .specialists/user/ directories for custom assets");
+  }
 }
-function skip(msg) {
-  console.log(`  ${yellow3("○")} ${msg}`);
+function createRuntimeDirs(cwd) {
+  const runtimeDirs = [
+    join9(cwd, ".specialists", "jobs"),
+    join9(cwd, ".specialists", "ready")
+  ];
+  let created = 0;
+  for (const dir of runtimeDirs) {
+    if (!existsSync6(dir)) {
+      mkdirSync2(dir, { recursive: true });
+      created++;
+    }
+  }
+  if (created > 0) {
+    ok("created .specialists/jobs/ and .specialists/ready/");
+  }
 }
-async function run5() {
-  const cwd = process.cwd();
-  console.log(`
-${bold3("specialists init")}
+function ensureProjectMcp(cwd) {
+  const mcpPath = join9(cwd, MCP_FILE);
+  const mcp = loadJson(mcpPath, { mcpServers: {} });
+  mcp.mcpServers ??= {};
+  const existing = mcp.mcpServers[MCP_SERVER_NAME];
+  if (existing && existing.command === MCP_SERVER_CONFIG.command && Array.isArray(existing.args) && existing.args.length === MCP_SERVER_CONFIG.args.length) {
+    skip(".mcp.json already registers specialists");
+    return;
+  }
+  mcp.mcpServers[MCP_SERVER_NAME] = MCP_SERVER_CONFIG;
+  saveJson(mcpPath, mcp);
+  ok("registered specialists in project .mcp.json");
+}
+function ensureGitignore(cwd) {
+  const gitignorePath = join9(cwd, ".gitignore");
+  const existing = existsSync6(gitignorePath) ? readFileSync3(gitignorePath, "utf-8") : "";
+  let added = 0;
+  const lines = existing.split(`
 `);
-  const specialistsDir = join5(cwd, "specialists");
-  if (existsSync3(specialistsDir)) {
-    skip("specialists/ already exists");
-  } else {
-    mkdirSync(specialistsDir, { recursive: true });
-    ok("created specialists/");
+  for (const entry of GITIGNORE_ENTRIES) {
+    if (!lines.includes(entry)) {
+      lines.push(entry);
+      added++;
+    }
   }
-  const runtimeDir = join5(cwd, ".specialists");
-  if (existsSync3(runtimeDir)) {
-    skip(".specialists/ already exists");
-  } else {
-    mkdirSync(join5(runtimeDir, "jobs"), { recursive: true });
-    mkdirSync(join5(runtimeDir, "ready"), { recursive: true });
-    ok("created .specialists/ (jobs/, ready/)");
-  }
-  const gitignorePath = join5(cwd, ".gitignore");
-  if (existsSync3(gitignorePath)) {
-    const existing = readFileSync(gitignorePath, "utf-8");
-    if (existing.includes(GITIGNORE_ENTRY)) {
-      skip(".gitignore already has .specialists/ entry");
-    } else {
-      const separator = existing.endsWith(`
-`) ? "" : `
-`;
-      writeFileSync(gitignorePath, existing + separator + GITIGNORE_ENTRY + `
+  if (added > 0) {
+    writeFileSync4(gitignorePath, lines.join(`
+`) + `
 `, "utf-8");
-      ok("added .specialists/ to .gitignore");
-    }
+    ok("added .specialists/jobs/ and .specialists/ready/ to .gitignore");
   } else {
-    writeFileSync(gitignorePath, GITIGNORE_ENTRY + `
-`, "utf-8");
-    ok("created .gitignore with .specialists/ entry");
+    skip(".gitignore already has runtime entries");
   }
-  const agentsPath = join5(cwd, "AGENTS.md");
-  if (existsSync3(agentsPath)) {
-    const existing = readFileSync(agentsPath, "utf-8");
+}
+function ensureAgentsMd(cwd) {
+  const agentsPath = join9(cwd, "AGENTS.md");
+  if (existsSync6(agentsPath)) {
+    const existing = readFileSync3(agentsPath, "utf-8");
     if (existing.includes(AGENTS_MARKER)) {
       skip("AGENTS.md already has Specialists section");
     } else {
-      writeFileSync(agentsPath, existing.trimEnd() + `
+      writeFileSync4(agentsPath, existing.trimEnd() + `
 
 ` + AGENTS_BLOCK, "utf-8");
       ok("appended Specialists section to AGENTS.md");
     }
   } else {
-    writeFileSync(agentsPath, AGENTS_BLOCK, "utf-8");
+    writeFileSync4(agentsPath, AGENTS_BLOCK, "utf-8");
     ok("created AGENTS.md with Specialists section");
   }
+}
+async function run5() {
+  const cwd = process.cwd();
+  console.log(`
+${bold3("specialists init")}
+`);
+  copyCanonicalSpecialists(cwd);
+  copyCanonicalHooks(cwd);
+  copyCanonicalSkills(cwd);
+  createUserDirs(cwd);
+  createRuntimeDirs(cwd);
+  ensureGitignore(cwd);
+  ensureAgentsMd(cwd);
+  ensureProjectMcp(cwd);
+  ensureProjectHooks(cwd);
   console.log(`
 ${bold3("Done!")}
 `);
-  console.log(`  ${dim3("Next steps:")}`);
-  console.log(`  1. Add your specialists to ${yellow3("specialists/")}`);
-  console.log(`  2. Run ${yellow3("specialists list")} to verify they are discovered`);
-  console.log(`  3. Restart Claude Code to pick up AGENTS.md changes
+  console.log(`  ${dim3("Directory structure:")}`);
+  console.log(`  .specialists/`);
+  console.log(`  ├── default/      ${dim3("# canonical assets (from init)")}`);
+  console.log(`  │   ├── specialists/`);
+  console.log(`  │   ├── hooks/`);
+  console.log(`  │   └── skills/`);
+  console.log(`  ├── user/         ${dim3("# your custom additions")}`);
+  console.log(`  │   ├── specialists/`);
+  console.log(`  │   ├── hooks/`);
+  console.log(`  │   └── skills/`);
+  console.log(`  ├── jobs/         ${dim3("# runtime (gitignored)")}`);
+  console.log(`  └── ready/        ${dim3("# runtime (gitignored)")}`);
+  console.log(`
+  ${dim3("Next steps:")}`);
+  console.log(`  1. Run ${yellow3("specialists list")} to see available specialists`);
+  console.log(`  2. Add custom specialists to ${yellow3(".specialists/user/specialists/")}`);
+  console.log(`  3. Restart Claude Code to pick up changes
 `);
 }
-var bold3 = (s) => `\x1B[1m${s}\x1B[0m`, green2 = (s) => `\x1B[32m${s}\x1B[0m`, yellow3 = (s) => `\x1B[33m${s}\x1B[0m`, dim3 = (s) => `\x1B[2m${s}\x1B[0m`, AGENTS_BLOCK, AGENTS_MARKER = "## Specialists", GITIGNORE_ENTRY = ".specialists/";
+var bold3 = (s) => `\x1B[1m${s}\x1B[0m`, green3 = (s) => `\x1B[32m${s}\x1B[0m`, yellow3 = (s) => `\x1B[33m${s}\x1B[0m`, dim3 = (s) => `\x1B[2m${s}\x1B[0m`, AGENTS_BLOCK, AGENTS_MARKER = "## Specialists", GITIGNORE_ENTRIES, MCP_FILE = ".mcp.json", MCP_SERVER_NAME = "specialists", MCP_SERVER_CONFIG;
 var init_init = __esm(() => {
   AGENTS_BLOCK = `
 ## Specialists
@@ -18526,7 +19369,11 @@ 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.
 `.trimStart();
+  GITIGNORE_ENTRIES = [".specialists/jobs/", ".specialists/ready/"];
+  MCP_SERVER_CONFIG = { command: "specialists", args: [] };
 });
 
 // src/cli/edit.ts
@@ -18534,11 +19381,11 @@ var exports_edit = {};
 __export(exports_edit, {
   run: () => run6
 });
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "node:fs";
 function parseArgs3(argv) {
   const name = argv[0];
   if (!name || name.startsWith("--")) {
-    console.error("Usage: specialists edit <name> --<field> <value> [--dry-run]");
+    console.error("Usage: specialists|sp edit <name> --<field> <value> [--dry-run]");
     console.error(`  Fields: ${Object.keys(FIELD_MAP).join(", ")}`);
     process.exit(1);
   }
@@ -18588,273 +19435,75 @@ function parseArgs3(argv) {
 function setIn(doc2, path, value) {
   let node = doc2;
   for (let i = 0;i < path.length - 1; i++) {
-    node = node.get(path[i], true);
-  }
-  const leaf = path[path.length - 1];
-  if (Array.isArray(value)) {
-    node.set(leaf, value);
-  } else {
-    node.set(leaf, value);
-  }
-}
-async function run6() {
-  const args = parseArgs3(process.argv.slice(3));
-  const { name, field, value, dryRun, scope } = args;
-  const loader = new SpecialistLoader;
-  const all = await loader.list();
-  const match = all.find((s) => s.name === name && (scope === undefined || s.scope === scope));
-  if (!match) {
-    const hint = scope ? ` (scope: ${scope})` : "";
-    console.error(`Error: specialist "${name}" not found${hint}`);
-    console.error(`  Run ${yellow4("specialists list")} to see available specialists`);
-    process.exit(1);
-  }
-  const raw = readFileSync2(match.filePath, "utf-8");
-  const doc2 = $parseDocument(raw);
-  const yamlPath = FIELD_MAP[field];
-  let typedValue = value;
-  if (field === "timeout") {
-    typedValue = parseInt(value, 10);
-  } else if (field === "tags") {
-    typedValue = value.split(",").map((t) => t.trim()).filter(Boolean);
-  }
-  setIn(doc2, yamlPath, typedValue);
-  const updated = doc2.toString();
-  if (dryRun) {
-    console.log(`
-${bold4(`[dry-run] ${match.filePath}`)}
-`);
-    console.log(dim4("--- current"));
-    console.log(dim4(`+++ updated`));
-    const oldLines = raw.split(`
-`);
-    const newLines = updated.split(`
-`);
-    newLines.forEach((line, i) => {
-      if (line !== oldLines[i]) {
-        if (oldLines[i] !== undefined)
-          console.log(dim4(`- ${oldLines[i]}`));
-        console.log(green3(`+ ${line}`));
-      }
-    });
-    console.log();
-    return;
-  }
-  writeFileSync2(match.filePath, updated, "utf-8");
-  const displayValue = field === "tags" ? `[${typedValue.join(", ")}]` : String(typedValue);
-  console.log(`${green3("✓")} ${bold4(name)}: ${yellow4(field)} = ${displayValue}` + dim4(` (${match.filePath})`));
-}
-var bold4 = (s) => `\x1B[1m${s}\x1B[0m`, green3 = (s) => `\x1B[32m${s}\x1B[0m`, yellow4 = (s) => `\x1B[33m${s}\x1B[0m`, dim4 = (s) => `\x1B[2m${s}\x1B[0m`, FIELD_MAP, VALID_PERMISSIONS;
-var init_edit = __esm(() => {
-  init_dist();
-  init_loader();
-  FIELD_MAP = {
-    model: ["specialist", "execution", "model"],
-    "fallback-model": ["specialist", "execution", "fallback_model"],
-    description: ["specialist", "metadata", "description"],
-    permission: ["specialist", "execution", "permission_required"],
-    timeout: ["specialist", "execution", "timeout_ms"],
-    tags: ["specialist", "metadata", "tags"]
-  };
-  VALID_PERMISSIONS = ["READ_ONLY", "LOW", "MEDIUM", "HIGH"];
-});
-
-// src/specialist/supervisor.ts
-import {
-  closeSync,
-  existsSync as existsSync4,
-  mkdirSync as mkdirSync2,
-  openSync,
-  readdirSync,
-  readFileSync as readFileSync3,
-  renameSync,
-  rmSync,
-  statSync,
-  writeFileSync as writeFileSync3,
-  writeSync
-} from "node:fs";
-import { join as join6 } from "node:path";
-
-class Supervisor {
-  opts;
-  constructor(opts) {
-    this.opts = opts;
-  }
-  jobDir(id) {
-    return join6(this.opts.jobsDir, id);
-  }
-  statusPath(id) {
-    return join6(this.jobDir(id), "status.json");
-  }
-  resultPath(id) {
-    return join6(this.jobDir(id), "result.txt");
-  }
-  eventsPath(id) {
-    return join6(this.jobDir(id), "events.jsonl");
-  }
-  readyDir() {
-    return join6(this.opts.jobsDir, "..", "ready");
-  }
-  readStatus(id) {
-    const path = this.statusPath(id);
-    if (!existsSync4(path))
-      return null;
-    try {
-      return JSON.parse(readFileSync3(path, "utf-8"));
-    } catch {
-      return null;
-    }
-  }
-  listJobs() {
-    if (!existsSync4(this.opts.jobsDir))
-      return [];
-    const jobs = [];
-    for (const entry of readdirSync(this.opts.jobsDir)) {
-      const path = join6(this.opts.jobsDir, entry, "status.json");
-      if (!existsSync4(path))
-        continue;
-      try {
-        jobs.push(JSON.parse(readFileSync3(path, "utf-8")));
-      } catch {}
-    }
-    return jobs.sort((a, b) => b.started_at_ms - a.started_at_ms);
-  }
-  writeStatusFile(id, data) {
-    const path = this.statusPath(id);
-    const tmp = path + ".tmp";
-    writeFileSync3(tmp, JSON.stringify(data, null, 2), "utf-8");
-    renameSync(tmp, path);
-  }
-  updateStatus(id, updates) {
-    const current = this.readStatus(id);
-    if (!current)
-      return;
-    this.writeStatusFile(id, { ...current, ...updates });
-  }
-  gc() {
-    if (!existsSync4(this.opts.jobsDir))
-      return;
-    const cutoff = Date.now() - JOB_TTL_DAYS * 86400000;
-    for (const entry of readdirSync(this.opts.jobsDir)) {
-      const dir = join6(this.opts.jobsDir, entry);
-      try {
-        const stat2 = statSync(dir);
-        if (!stat2.isDirectory())
-          continue;
-        if (stat2.mtimeMs < cutoff)
-          rmSync(dir, { recursive: true, force: true });
-      } catch {}
-    }
-  }
-  crashRecovery() {
-    if (!existsSync4(this.opts.jobsDir))
-      return;
-    for (const entry of readdirSync(this.opts.jobsDir)) {
-      const statusPath = join6(this.opts.jobsDir, entry, "status.json");
-      if (!existsSync4(statusPath))
-        continue;
-      try {
-        const s = JSON.parse(readFileSync3(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" };
-          writeFileSync3(tmp, JSON.stringify(updated, null, 2), "utf-8");
-          renameSync(tmp, statusPath);
-        }
-      } catch {}
-    }
-  }
-  async run() {
-    const { runner, runOptions, jobsDir } = this.opts;
-    this.gc();
-    this.crashRecovery();
-    const id = crypto.randomUUID().slice(0, 6);
-    const dir = this.jobDir(id);
-    const startedAtMs = Date.now();
-    mkdirSync2(dir, { recursive: true });
-    mkdirSync2(this.readyDir(), { recursive: true });
-    const initialStatus = {
-      id,
-      specialist: runOptions.name,
-      status: "starting",
-      started_at_ms: startedAtMs,
-      pid: process.pid
-    };
-    this.writeStatusFile(id, initialStatus);
-    const eventsFd = openSync(this.eventsPath(id), "a");
-    const appendEvent = (obj) => {
-      try {
-        writeSync(eventsFd, JSON.stringify({ t: Date.now(), ...obj }) + `
-`);
-      } catch {}
-    };
-    let textLogged = false;
-    let currentTool = "";
-    try {
-      const result = await runner.run(runOptions, (delta) => {
-        const toolMatch = delta.match(/⚙ (.+?)…/);
-        if (toolMatch) {
-          currentTool = toolMatch[1];
-          this.updateStatus(id, { current_tool: currentTool });
-        }
-      }, (eventType) => {
-        const now = Date.now();
-        this.updateStatus(id, {
-          status: "running",
-          current_event: eventType,
-          last_event_at_ms: now,
-          elapsed_s: Math.round((now - startedAtMs) / 1000)
-        });
-        if (LOGGED_EVENTS.has(eventType)) {
-          const tool = eventType === "toolcall" || eventType === "tool_execution_end" ? currentTool : undefined;
-          appendEvent({ type: eventType, ...tool ? { tool } : {} });
-        } else if (eventType === "text" && !textLogged) {
-          textLogged = true;
-          appendEvent({ type: "text" });
-        }
-      }, (meta) => {
-        this.updateStatus(id, { model: meta.model, backend: meta.backend });
-        appendEvent({ type: "meta", model: meta.model, backend: meta.backend });
-      }, (_killFn) => {}, (beadId) => {
-        this.updateStatus(id, { bead_id: beadId });
-      });
-      const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
-      writeFileSync3(this.resultPath(id), result.output, "utf-8");
-      this.updateStatus(id, {
-        status: "done",
-        elapsed_s: elapsed,
-        last_event_at_ms: Date.now(),
-        model: result.model,
-        backend: result.backend,
-        bead_id: result.beadId
-      });
-      appendEvent({ type: "agent_end", elapsed_s: elapsed });
-      writeFileSync3(join6(this.readyDir(), id), "", "utf-8");
-      return id;
-    } catch (err) {
-      const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
-      this.updateStatus(id, {
-        status: "error",
-        elapsed_s: elapsed,
-        error: err?.message ?? String(err)
-      });
-      appendEvent({ type: "error", message: err?.message ?? String(err) });
-      throw err;
-    } finally {
-      closeSync(eventsFd);
-    }
+    node = node.get(path[i], true);
+  }
+  const leaf = path[path.length - 1];
+  if (Array.isArray(value)) {
+    node.set(leaf, value);
+  } else {
+    node.set(leaf, value);
   }
 }
-var JOB_TTL_DAYS, LOGGED_EVENTS;
-var init_supervisor = __esm(() => {
-  JOB_TTL_DAYS = Number(process.env.SPECIALISTS_JOB_TTL_DAYS ?? 7);
-  LOGGED_EVENTS = new Set(["thinking", "toolcall", "tool_execution_end", "done"]);
+async function run6() {
+  const args = parseArgs3(process.argv.slice(3));
+  const { name, field, value, dryRun, scope } = args;
+  const loader = new SpecialistLoader;
+  const all = await loader.list();
+  const match = all.find((s) => s.name === name && (scope === undefined || s.scope === scope));
+  if (!match) {
+    const hint = scope ? ` (scope: ${scope})` : "";
+    console.error(`Error: specialist "${name}" not found${hint}`);
+    console.error(`  Run ${yellow4("specialists list")} to see available specialists`);
+    process.exit(1);
+  }
+  const raw = readFileSync4(match.filePath, "utf-8");
+  const doc2 = $parseDocument(raw);
+  const yamlPath = FIELD_MAP[field];
+  let typedValue = value;
+  if (field === "timeout") {
+    typedValue = parseInt(value, 10);
+  } else if (field === "tags") {
+    typedValue = value.split(",").map((t) => t.trim()).filter(Boolean);
+  }
+  setIn(doc2, yamlPath, typedValue);
+  const updated = doc2.toString();
+  if (dryRun) {
+    console.log(`
+${bold4(`[dry-run] ${match.filePath}`)}
+`);
+    console.log(dim4("--- current"));
+    console.log(dim4(`+++ updated`));
+    const oldLines = raw.split(`
+`);
+    const newLines = updated.split(`
+`);
+    newLines.forEach((line, i) => {
+      if (line !== oldLines[i]) {
+        if (oldLines[i] !== undefined)
+          console.log(dim4(`- ${oldLines[i]}`));
+        console.log(green4(`+ ${line}`));
+      }
+    });
+    console.log();
+    return;
+  }
+  writeFileSync5(match.filePath, updated, "utf-8");
+  const displayValue = field === "tags" ? `[${typedValue.join(", ")}]` : String(typedValue);
+  console.log(`${green4("✓")} ${bold4(name)}: ${yellow4(field)} = ${displayValue}` + dim4(` (${match.filePath})`));
+}
+var bold4 = (s) => `\x1B[1m${s}\x1B[0m`, green4 = (s) => `\x1B[32m${s}\x1B[0m`, yellow4 = (s) => `\x1B[33m${s}\x1B[0m`, dim4 = (s) => `\x1B[2m${s}\x1B[0m`, FIELD_MAP, VALID_PERMISSIONS;
+var init_edit = __esm(() => {
+  init_dist();
+  init_loader();
+  FIELD_MAP = {
+    model: ["specialist", "execution", "model"],
+    "fallback-model": ["specialist", "execution", "fallback_model"],
+    description: ["specialist", "metadata", "description"],
+    permission: ["specialist", "execution", "permission_required"],
+    timeout: ["specialist", "execution", "timeout_ms"],
+    tags: ["specialist", "metadata", "tags"]
+  };
+  VALID_PERMISSIONS = ["READ_ONLY", "LOW", "MEDIUM", "HIGH"];
 });
 
 // src/cli/run.ts
@@ -18862,27 +19511,40 @@ var exports_run = {};
 __export(exports_run, {
   run: () => run7
 });
-import { join as join7 } from "node:path";
+import { spawn as spawn2 } from "node:child_process";
+import { join as join10 } from "node:path";
 async function parseArgs4(argv) {
   const name = argv[0];
   if (!name || name.startsWith("--")) {
-    console.error('Usage: specialists run <name> [--prompt "..."] [--model <model>] [--no-beads] [--background]');
+    console.error('Usage: specialists|sp run <name> [--prompt "..."] [--bead <id>] [--context-depth <n>] [--model <model>] [--no-beads] [--background] [--follow]');
     process.exit(1);
   }
   let prompt = "";
+  let beadId;
   let model;
   let noBeads = false;
   let background = false;
+  let follow = 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;
+    }
     if (token === "--no-beads") {
       noBeads = true;
       continue;
@@ -18891,61 +19553,130 @@ async function parseArgs4(argv) {
       background = true;
       continue;
     }
-  }
-  if (!prompt) {
-    if (process.stdin.isTTY) {
-      process.stderr.write(dim5("Prompt (Ctrl+D when done): "));
+    if (token === "--follow") {
+      follow = true;
+      continue;
+    }
+    if (token === "--keep-alive") {
+      keepAlive = true;
+      continue;
     }
-    prompt = await new Promise((resolve) => {
+  }
+  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", () => resolve(buf.trim()));
+      process.stdin.on("end", () => resolve2(buf.trim()));
     });
   }
-  return { name, prompt, model, noBeads, background };
+  if (!prompt && !beadId) {
+    console.error("Error: provide --prompt, pipe stdin, or use --bead <id>.");
+    process.exit(1);
+  }
+  return { name, prompt, beadId, model, noBeads, background, follow, keepAlive, contextDepth };
 }
 async function run7() {
   const args = await parseArgs4(process.argv.slice(3));
   const loader = new SpecialistLoader;
   const circuitBreaker = new CircuitBreaker;
-  const hooks = new HookEmitter({ tracePath: join7(process.cwd(), ".specialists", "trace.jsonl") });
-  const beadsClient = args.noBeads ? null : new BeadsClient;
+  const hooks = new HookEmitter({ tracePath: join10(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(dim5(`
+[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 runner = new SpecialistRunner({
     loader,
     hooks,
     circuitBreaker,
-    beadsClient: beadsClient ?? undefined
+    beadsClient
   });
-  if (args.background) {
-    const jobsDir = join7(process.cwd(), ".specialists", "jobs");
+  if (args.background || args.follow) {
+    const jobsDir = join10(process.cwd(), ".specialists", "jobs");
     const supervisor = new Supervisor({
       runner,
-      runOptions: { name: args.name, prompt: args.prompt, backendOverride: args.model },
-      jobsDir
+      runOptions: {
+        name: args.name,
+        prompt,
+        variables,
+        backendOverride: args.model,
+        inputBeadId: args.beadId,
+        keepAlive: args.keepAlive
+      },
+      jobsDir,
+      beadsClient
     });
+    let jobId;
     try {
-      const jobId = await supervisor.run();
-      process.stdout.write(`Job started: ${jobId}
+      jobId = await supervisor.run();
+      if (!args.follow) {
+        process.stdout.write(`Job started: ${jobId}
 `);
+      }
     } catch (err) {
       process.stderr.write(`Error: ${err?.message ?? err}
 `);
       process.exit(1);
     }
+    if (args.follow) {
+      await new Promise((resolve2, reject) => {
+        const feed = spawn2("specialists", ["feed", "--job", jobId, "--follow"], {
+          cwd: process.cwd(),
+          stdio: "inherit"
+        });
+        feed.on("close", (code) => {
+          if (code === 0) {
+            resolve2();
+          } else {
+            reject(new Error(`Feed exited with code ${code}`));
+          }
+        });
+        feed.on("error", (err) => {
+          reject(err);
+        });
+      }).catch((err) => {
+        process.stderr.write(`Error: ${err.message}
+`);
+        process.exit(1);
+      });
+    }
     return;
   }
   process.stderr.write(`
 ${bold5(`Running ${cyan3(args.name)}`)}
 
 `);
-  let beadId;
+  let trackingBeadId;
   const result = await runner.run({
     name: args.name,
-    prompt: args.prompt,
-    backendOverride: args.model
+    prompt,
+    variables,
+    backendOverride: args.model,
+    inputBeadId: args.beadId
   }, (delta) => process.stdout.write(delta), undefined, (meta) => process.stderr.write(dim5(`
 [${meta.backend} / ${meta.model}]
 
@@ -18958,10 +19689,10 @@ Interrupted.
       killFn();
       process.exit(130);
     });
-  }, (id) => {
-    beadId = id;
+  }, (beadId) => {
+    trackingBeadId = beadId;
     process.stderr.write(dim5(`
-[bead: ${id}]
+[bead: ${beadId}]
 `));
   });
   if (result.output && !result.output.endsWith(`
@@ -18969,17 +19700,18 @@ Interrupted.
     process.stdout.write(`
 `);
   const secs = (result.durationMs / 1000).toFixed(1);
+  const effectiveBeadId = args.beadId ?? trackingBeadId;
   const footer = [
-    beadId ? `bead ${beadId}` : "",
+    effectiveBeadId ? `bead ${effectiveBeadId}` : "",
     `${secs}s`,
     dim5(result.model)
   ].filter(Boolean).join("  ");
   process.stderr.write(`
-${green4("✓")} ${footer}
+${green5("✓")} ${footer}
 
 `);
 }
-var bold5 = (s) => `\x1B[1m${s}\x1B[0m`, dim5 = (s) => `\x1B[2m${s}\x1B[0m`, green4 = (s) => `\x1B[32m${s}\x1B[0m`, cyan3 = (s) => `\x1B[36m${s}\x1B[0m`;
+var bold5 = (s) => `\x1B[1m${s}\x1B[0m`, dim5 = (s) => `\x1B[2m${s}\x1B[0m`, green5 = (s) => `\x1B[32m${s}\x1B[0m`, cyan3 = (s) => `\x1B[36m${s}\x1B[0m`;
 var init_run = __esm(() => {
   init_loader();
   init_runner();
@@ -18988,16 +19720,105 @@ var init_run = __esm(() => {
   init_supervisor();
 });
 
+// src/cli/format-helpers.ts
+function formatTime(t) {
+  return new Date(t).toISOString().slice(11, 19);
+}
+function formatElapsed(seconds) {
+  if (seconds < 60)
+    return `${seconds}s`;
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return s > 0 ? `${m}m ${s}s` : `${m}m`;
+}
+function getEventLabel(type) {
+  return EVENT_LABELS[type] ?? type.slice(0, 5).toUpperCase();
+}
+
+class JobColorMap {
+  colors = new Map;
+  nextIdx = 0;
+  getColor(jobId) {
+    let color = this.colors.get(jobId);
+    if (!color) {
+      color = JOB_COLORS[this.nextIdx % JOB_COLORS.length];
+      this.colors.set(jobId, color);
+      this.nextIdx++;
+    }
+    return color;
+  }
+  get(jobId) {
+    return this.getColor(jobId);
+  }
+  has(jobId) {
+    return this.colors.has(jobId);
+  }
+  get size() {
+    return this.colors.size;
+  }
+}
+function formatEventLine(event, options) {
+  const ts = dim6(formatTime(event.t));
+  const label = options.colorize(bold6(getEventLabel(event.type).padEnd(5)));
+  const prefix = `${options.colorize(`[${options.jobId}]`)} ${options.specialist}${options.beadId ? ` ${dim6(`[${options.beadId}]`)}` : ""}`;
+  const detailParts = [];
+  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"}`);
+    }
+  } 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) {
+      detailParts.push(`bead=${event.bead_id}`);
+    }
+  } else if (event.type === "text") {
+    detailParts.push("kind=assistant");
+  } else if (event.type === "thinking") {
+    detailParts.push("kind=model");
+  }
+  const detail = detailParts.length > 0 ? dim6(detailParts.join(" ")) : "";
+  return `${ts} ${prefix}  ${label}${detail ? ` ${detail}` : ""}`.trimEnd();
+}
+var dim6 = (s) => `\x1B[2m${s}\x1B[0m`, bold6 = (s) => `\x1B[1m${s}\x1B[0m`, cyan4 = (s) => `\x1B[36m${s}\x1B[0m`, yellow5 = (s) => `\x1B[33m${s}\x1B[0m`, red = (s) => `\x1B[31m${s}\x1B[0m`, green6 = (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, yellow5, magenta, green6, blue, red];
+  EVENT_LABELS = {
+    run_start: "START",
+    meta: "META",
+    thinking: "THINK",
+    tool: "TOOL",
+    text: "TEXT",
+    run_complete: "DONE",
+    done: "DONE",
+    agent_end: "DONE",
+    error: "ERR"
+  };
+});
+
 // src/cli/status.ts
 var exports_status = {};
 __export(exports_status, {
   run: () => run8
 });
-import { spawnSync as spawnSync4 } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
-import { join as join8 } from "node:path";
+import { spawnSync as spawnSync6 } from "node:child_process";
+import { existsSync as existsSync7 } from "node:fs";
+import { join as join11 } from "node:path";
 function ok2(msg) {
-  console.log(`  ${green5("✓")} ${msg}`);
+  console.log(`  ${green6("✓")} ${msg}`);
 }
 function warn(msg) {
   console.log(`  ${yellow5("○")} ${msg}`);
@@ -19014,7 +19835,7 @@ function section(label) {
 ${bold6(`── ${label} ${line}`)}`);
 }
 function cmd(bin, args) {
-  const r = spawnSync4(bin, args, {
+  const r = spawnSync6(bin, args, {
     encoding: "utf8",
     stdio: "pipe",
     timeout: 5000
@@ -19022,9 +19843,9 @@ function cmd(bin, args) {
   return { ok: r.status === 0 && !r.error, stdout: (r.stdout ?? "").trim() };
 }
 function isInstalled(bin) {
-  return spawnSync4("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
+  return spawnSync6("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
 }
-function formatElapsed(s) {
+function formatElapsed2(s) {
   if (s.elapsed_s === undefined)
     return "...";
   const m = Math.floor(s.elapsed_s / 60);
@@ -19036,7 +19857,7 @@ function statusColor(status) {
     case "running":
       return cyan4(status);
     case "done":
-      return green5(status);
+      return green6(status);
     case "error":
       return red(status);
     case "starting":
@@ -19057,11 +19878,11 @@ async function run8() {
 `).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 = existsSync5(join8(process.cwd(), ".beads"));
+  const beadsPresent = existsSync7(join11(process.cwd(), ".beads"));
   const specialistsBin = cmd("which", ["specialists"]);
-  const jobsDir = join8(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join11(process.cwd(), ".specialists", "jobs");
   let jobs = [];
-  if (existsSync5(jobsDir)) {
+  if (existsSync7(jobsDir)) {
     const supervisor = new Supervisor({
       runner: null,
       runOptions: null,
@@ -19135,7 +19956,7 @@ ${bold6("specialists status")}
   }
   section("pi  (coding agent runtime)");
   if (!piInstalled) {
-    fail(`pi not installed — run ${yellow5("specialists install")}`);
+    fail(`pi not installed — install ${yellow5("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  ${dim6(`(${[...piProviders].join(", ")})`)} ` : yellow5("no providers configured — run pi config");
@@ -19143,7 +19964,7 @@ ${bold6("specialists status")}
   }
   section("beads  (issue tracker)");
   if (!bdInstalled) {
-    fail(`bd not installed — run ${yellow5("specialists install")}`);
+    fail(`bd not installed — install ${yellow5("bd")} first`);
   } else {
     ok2(`bd installed${bdVersion?.ok ? `  ${dim6(bdVersion.stdout)}` : ""}`);
     if (beadsPresent) {
@@ -19163,17 +19984,17 @@ ${bold6("specialists status")}
   if (jobs.length > 0) {
     section("Active Jobs");
     for (const job of jobs) {
-      const elapsed = formatElapsed(job);
+      const elapsed = formatElapsed2(job);
       const detail = job.status === "error" ? red(job.error?.slice(0, 40) ?? "error") : job.current_tool ? dim6(`tool: ${job.current_tool}`) : dim6(job.current_event ?? "");
       console.log(`  ${dim6(job.id)}  ${job.specialist.padEnd(20)}  ${statusColor(job.status).padEnd(7)}  ${elapsed.padStart(6)}  ${detail}`);
     }
   }
   console.log();
 }
-var bold6 = (s) => `\x1B[1m${s}\x1B[0m`, dim6 = (s) => `\x1B[2m${s}\x1B[0m`, green5 = (s) => `\x1B[32m${s}\x1B[0m`, yellow5 = (s) => `\x1B[33m${s}\x1B[0m`, red = (s) => `\x1B[31m${s}\x1B[0m`, cyan4 = (s) => `\x1B[36m${s}\x1B[0m`;
 var init_status = __esm(() => {
   init_loader();
   init_supervisor();
+  init_format_helpers();
 });
 
 // src/cli/result.ts
@@ -19181,15 +20002,15 @@ var exports_result = {};
 __export(exports_result, {
   run: () => run9
 });
-import { existsSync as existsSync6, readFileSync as readFileSync4 } from "node:fs";
-import { join as join9 } from "node:path";
+import { existsSync as existsSync8, readFileSync as readFileSync5 } from "node:fs";
+import { join as join12 } from "node:path";
 async function run9() {
   const jobId = process.argv[3];
   if (!jobId) {
-    console.error("Usage: specialists result <job-id>");
+    console.error("Usage: specialists|sp result <job-id>");
     process.exit(1);
   }
-  const jobsDir = join9(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join12(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const status = supervisor.readStatus(jobId);
   if (!status) {
@@ -19206,118 +20027,453 @@ async function run9() {
 `);
     process.exit(1);
   }
-  const resultPath = join9(jobsDir, jobId, "result.txt");
-  if (!existsSync6(resultPath)) {
+  const resultPath = join12(jobsDir, jobId, "result.txt");
+  if (!existsSync8(resultPath)) {
     console.error(`Result file not found for job ${jobId}`);
     process.exit(1);
   }
-  process.stdout.write(readFileSync4(resultPath, "utf-8"));
+  process.stdout.write(readFileSync5(resultPath, "utf-8"));
 }
 var dim7 = (s) => `\x1B[2m${s}\x1B[0m`, red2 = (s) => `\x1B[31m${s}\x1B[0m`;
 var init_result = __esm(() => {
   init_supervisor();
 });
 
+// src/specialist/timeline-query.ts
+import { existsSync as existsSync9, readdirSync as readdirSync3, readFileSync as readFileSync6 } from "node:fs";
+import { join as join13 } from "node:path";
+function readJobEvents(jobDir) {
+  const eventsPath = join13(jobDir, "events.jsonl");
+  if (!existsSync9(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 readAllJobEvents(jobsDir) {
+  if (!existsSync9(jobsDir))
+    return [];
+  const batches = [];
+  const entries = readdirSync3(jobsDir);
+  for (const entry of entries) {
+    const jobDir = join13(jobsDir, entry);
+    try {
+      const stat2 = __require("node:fs").statSync(jobDir);
+      if (!stat2.isDirectory())
+        continue;
+    } catch {
+      continue;
+    }
+    const jobId = entry;
+    const statusPath = join13(jobDir, "status.json");
+    let specialist = "unknown";
+    let beadId;
+    if (existsSync9(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: () => run10
 });
-import { existsSync as existsSync7, readFileSync as readFileSync5, watchFile } from "node:fs";
-import { join as join10 } from "node:path";
-function formatEvent(line) {
-  try {
-    const e = JSON.parse(line);
-    const ts = new Date(e.t).toISOString().slice(11, 19);
-    const type = e.type ?? "?";
-    const extra = e.tool ? ` ${cyan5(e.tool)}` : e.model ? ` ${dim8(e.model)}` : e.message ? ` ${red3(e.message)}` : "";
-    return `${dim8(ts)}  ${type}${extra}`;
-  } catch {
-    return line;
+import { existsSync as existsSync10 } from "node:fs";
+import { join as join14 } 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"}`;
+    case "text":
+      return "text";
+    case "thinking":
+      return "thinking";
+    case "run_start":
+      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 printLines(content, from) {
-  const lines = content.split(`
-`).filter(Boolean);
-  for (let i = from;i < lines.length; i++) {
-    console.log(formatEvent(lines[i]));
+function shouldSkipHumanEvent(event, jobId, lastPrintedEventKey, seenMetaKey) {
+  if (event.type === "meta") {
+    const metaKey = `${event.backend}:${event.model}`;
+    if (seenMetaKey.get(jobId) === metaKey)
+      return true;
+    seenMetaKey.set(jobId, metaKey);
+  }
+  const key = getHumanEventKey(event);
+  if (lastPrintedEventKey.get(jobId) === key)
+    return true;
+  lastPrintedEventKey.set(jobId, key);
+  return false;
+}
+function parseSince(value) {
+  if (value.includes("T") || value.includes("-")) {
+    return new Date(value).getTime();
+  }
+  const match = value.match(/^(\d+)([smhd])$/);
+  if (match) {
+    const num = parseInt(match[1], 10);
+    const unit = match[2];
+    const multipliers = { s: 1000, m: 60000, h: 3600000, d: 86400000 };
+    return Date.now() - num * multipliers[unit];
   }
-  return lines.length;
+  return;
 }
-async function run10() {
-  const argv = process.argv.slice(3);
+function parseArgs5(argv) {
   let jobId;
+  let specialist;
+  let since;
+  let limit = 100;
   let follow = false;
+  let forever = false;
+  let json = false;
   for (let i = 0;i < argv.length; i++) {
     if (argv[i] === "--job" && argv[i + 1]) {
       jobId = argv[++i];
       continue;
     }
+    if (argv[i] === "--specialist" && argv[i + 1]) {
+      specialist = argv[++i];
+      continue;
+    }
+    if (argv[i] === "--since" && argv[i + 1]) {
+      since = parseSince(argv[++i]);
+      continue;
+    }
+    if (argv[i] === "--limit" && argv[i + 1]) {
+      limit = parseInt(argv[++i], 10);
+      continue;
+    }
     if (argv[i] === "--follow" || argv[i] === "-f") {
       follow = true;
       continue;
     }
+    if (argv[i] === "--forever") {
+      forever = true;
+      continue;
+    }
+    if (argv[i] === "--json") {
+      json = true;
+      continue;
+    }
     if (!jobId && !argv[i].startsWith("--"))
       jobId = argv[i];
   }
-  if (!jobId) {
-    console.error("Usage: specialists feed --job <job-id> [--follow]");
-    process.exit(1);
+  return { jobId, specialist, since, limit, follow, forever, json };
+}
+function printSnapshot(merged, options) {
+  if (merged.length === 0) {
+    if (!options.json)
+      console.log(dim6("No events found."));
+    return;
   }
-  const jobsDir = join10(process.cwd(), ".specialists", "jobs");
-  const eventsPath = join10(jobsDir, jobId, "events.jsonl");
-  if (!existsSync7(eventsPath)) {
-    const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
-    if (!supervisor.readStatus(jobId)) {
-      console.error(`No job found: ${jobId}`);
-      process.exit(1);
+  const colorMap = new JobColorMap;
+  if (options.json) {
+    for (const { jobId, specialist, beadId, event } of merged) {
+      console.log(JSON.stringify({ jobId, specialist, beadId, ...event }));
+    }
+    return;
+  }
+  const lastPrintedEventKey = new Map;
+  const seenMetaKey = new Map;
+  for (const { jobId, specialist, beadId, event } of merged) {
+    if (shouldSkipHumanEvent(event, jobId, lastPrintedEventKey, seenMetaKey))
+      continue;
+    const colorize = colorMap.get(jobId);
+    console.log(formatEventLine(event, { jobId, specialist, beadId, colorize }));
+  }
+}
+function isCompletionEvent(event) {
+  return isRunCompleteEvent(event) || event.type === "done" || event.type === "agent_end";
+}
+async function followMerged(jobsDir, options) {
+  const colorMap = new JobColorMap;
+  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);
+  const initial = queryTimeline(jobsDir, {
+    jobId: options.jobId,
+    specialist: options.specialist,
+    since: options.since,
+    limit: options.limit
+  });
+  printSnapshot(initial, { ...options, json: options.json });
+  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)) {
+      completedJobs.add(batch.jobId);
     }
-    console.log(dim8("No events yet."));
+  }
+  const initialBatchCount = filteredBatches().length;
+  if (!options.forever && initialBatchCount > 0 && completedJobs.size === initialBatchCount) {
+    if (!options.json) {
+      process.stderr.write(dim6(`All jobs complete.
+`));
+    }
+    return;
+  }
+  if (!options.json) {
+    process.stderr.write(dim6(`Following... (Ctrl+C to stop)
+`));
+  }
+  const lastPrintedEventKey = new Map;
+  const seenMetaKey = new Map;
+  await new Promise((resolve2) => {
+    const interval = setInterval(() => {
+      const batches = filteredBatches();
+      const newEvents = [];
+      for (const batch of batches) {
+        const lastT = lastSeenT.get(batch.jobId) ?? 0;
+        for (const event of batch.events) {
+          if (event.t > lastT) {
+            newEvents.push({
+              jobId: batch.jobId,
+              specialist: batch.specialist,
+              beadId: batch.beadId,
+              event
+            });
+          }
+        }
+        if (batch.events.length > 0) {
+          const maxT = Math.max(...batch.events.map((e) => e.t));
+          lastSeenT.set(batch.jobId, maxT);
+        }
+        if (batch.events.some(isCompletionEvent)) {
+          completedJobs.add(batch.jobId);
+        }
+      }
+      newEvents.sort((a, b) => a.event.t - b.event.t);
+      for (const { jobId, specialist, beadId, event } of newEvents) {
+        if (options.json) {
+          console.log(JSON.stringify({ jobId, specialist, beadId, ...event }));
+        } else {
+          if (shouldSkipHumanEvent(event, jobId, lastPrintedEventKey, seenMetaKey))
+            continue;
+          const colorize = colorMap.get(jobId);
+          console.log(formatEventLine(event, { jobId, specialist, beadId, colorize }));
+        }
+      }
+      if (!options.forever && batches.length > 0 && completedJobs.size === batches.length) {
+        clearInterval(interval);
+        resolve2();
+      }
+    }, 500);
+  });
+}
+async function run10() {
+  const options = parseArgs5(process.argv.slice(3));
+  const jobsDir = join14(process.cwd(), ".specialists", "jobs");
+  if (!existsSync10(jobsDir)) {
+    console.log(dim6("No jobs directory found."));
+    return;
+  }
+  if (options.follow) {
+    await followMerged(jobsDir, options);
     return;
   }
-  const content = readFileSync5(eventsPath, "utf-8");
-  let linesRead = printLines(content, 0);
-  if (!follow)
-    return;
-  process.stderr.write(dim8(`Following ${jobId}... (Ctrl+C to stop)
-`));
-  await new Promise((resolve) => {
-    watchFile(eventsPath, { interval: 500 }, () => {
-      try {
-        const updated = readFileSync5(eventsPath, "utf-8");
-        linesRead = printLines(updated, linesRead);
-        const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
-        const status = supervisor.readStatus(jobId);
-        if (status && status.status !== "running" && status.status !== "starting") {
-          const finalMsg = status.status === "done" ? `
-${yellow6("Job complete.")} Run: specialists result ${jobId}` : `
-${red3(`Job ${status.status}.`)} ${status.error ?? ""}`;
-          process.stderr.write(finalMsg + `
+  const merged = queryTimeline(jobsDir, {
+    jobId: options.jobId,
+    specialist: options.specialist,
+    since: options.since,
+    limit: options.limit
+  });
+  printSnapshot(merged, options);
+}
+var init_feed = __esm(() => {
+  init_timeline_events();
+  init_timeline_query();
+  init_format_helpers();
+});
+
+// src/cli/steer.ts
+var exports_steer = {};
+__export(exports_steer, {
+  run: () => run11
+});
+import { join as join15 } from "node:path";
+import { writeFileSync as writeFileSync6 } from "node:fs";
+async function run11() {
+  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 = join15(process.cwd(), ".specialists", "jobs");
+  const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
+  const status = supervisor.readStatus(jobId);
+  if (!status) {
+    console.error(`No job found: ${jobId}`);
+    process.exit(1);
+  }
+  if (status.status === "done" || status.status === "error") {
+    process.stderr.write(`Job ${jobId} is already ${status.status}.
+`);
+    process.exit(1);
+  }
+  if (!status.fifo_path) {
+    process.stderr.write(`${red3("Error:")} Job ${jobId} has no steer pipe.
+`);
+    process.stderr.write(`Only jobs started with --background support mid-run steering.
+`);
+    process.exit(1);
+  }
+  try {
+    const payload = JSON.stringify({ type: "steer", message }) + `
+`;
+    writeFileSync6(status.fifo_path, payload, { flag: "a" });
+    process.stdout.write(`${green7("✓")} Steer message sent to job ${jobId}
+`);
+  } catch (err) {
+    process.stderr.write(`${red3("Error:")} Failed to write to steer pipe: ${err?.message}
+`);
+    process.exit(1);
+  }
+}
+var green7 = (s) => `\x1B[32m${s}\x1B[0m`, red3 = (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: () => run12
+});
+import { join as join16 } from "node:path";
+import { writeFileSync as writeFileSync7 } from "node:fs";
+async function run12() {
+  const jobId = process.argv[3];
+  const message = process.argv[4];
+  if (!jobId || !message) {
+    console.error('Usage: specialists|sp follow-up <job-id> "<message>"');
+    process.exit(1);
+  }
+  const jobsDir = join16(process.cwd(), ".specialists", "jobs");
+  const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
+  const status = supervisor.readStatus(jobId);
+  if (!status) {
+    console.error(`No job found: ${jobId}`);
+    process.exit(1);
+  }
+  if (status.status !== "waiting") {
+    process.stderr.write(`${red4("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.exit(1);
+  }
+  if (!status.fifo_path) {
+    process.stderr.write(`${red4("Error:")} Job ${jobId} has no steer pipe.
+`);
+    process.exit(1);
+  }
+  try {
+    const payload = JSON.stringify({ type: "prompt", message }) + `
+`;
+    writeFileSync7(status.fifo_path, payload, { flag: "a" });
+    process.stdout.write(`${green8("✓")} Follow-up sent to job ${jobId}
 `);
-          resolve();
-        }
-      } catch {}
-    });
-  });
+    process.stdout.write(`  Use 'specialists feed ${jobId} --follow' to watch the response.
+`);
+  } catch (err) {
+    process.stderr.write(`${red4("Error:")} Failed to write to steer pipe: ${err?.message}
+`);
+    process.exit(1);
+  }
 }
-var dim8 = (s) => `\x1B[2m${s}\x1B[0m`, cyan5 = (s) => `\x1B[36m${s}\x1B[0m`, yellow6 = (s) => `\x1B[33m${s}\x1B[0m`, red3 = (s) => `\x1B[31m${s}\x1B[0m`;
-var init_feed = __esm(() => {
+var green8 = (s) => `\x1B[32m${s}\x1B[0m`, red4 = (s) => `\x1B[31m${s}\x1B[0m`;
+var init_follow_up = __esm(() => {
   init_supervisor();
 });
 
 // src/cli/stop.ts
 var exports_stop = {};
 __export(exports_stop, {
-  run: () => run11
+  run: () => run13
 });
-import { join as join11 } from "node:path";
-async function run11() {
+import { join as join17 } from "node:path";
+async function run13() {
   const jobId = process.argv[3];
   if (!jobId) {
-    console.error("Usage: specialists stop <job-id>");
+    console.error("Usage: specialists|sp stop <job-id>");
     process.exit(1);
   }
-  const jobsDir = join11(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join17(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const status = supervisor.readStatus(jobId);
   if (!status) {
@@ -19325,31 +20481,31 @@ async function run11() {
     process.exit(1);
   }
   if (status.status === "done" || status.status === "error") {
-    process.stderr.write(`${dim9(`Job ${jobId} is already ${status.status}.`)}
+    process.stderr.write(`${dim8(`Job ${jobId} is already ${status.status}.`)}
 `);
     return;
   }
   if (!status.pid) {
-    process.stderr.write(`${red4(`No PID recorded for job ${jobId}.`)}
+    process.stderr.write(`${red5(`No PID recorded for job ${jobId}.`)}
 `);
     process.exit(1);
   }
   try {
     process.kill(status.pid, "SIGTERM");
-    process.stdout.write(`${green6("✓")} Sent SIGTERM to PID ${status.pid} (job ${jobId})
+    process.stdout.write(`${green9("✓")} Sent SIGTERM to PID ${status.pid} (job ${jobId})
 `);
   } catch (err) {
     if (err.code === "ESRCH") {
-      process.stderr.write(`${red4(`Process ${status.pid} not found.`)} Job may have already completed.
+      process.stderr.write(`${red5(`Process ${status.pid} not found.`)} Job may have already completed.
 `);
     } else {
-      process.stderr.write(`${red4("Error:")} ${err.message}
+      process.stderr.write(`${red5("Error:")} ${err.message}
 `);
       process.exit(1);
     }
   }
 }
-var green6 = (s) => `\x1B[32m${s}\x1B[0m`, red4 = (s) => `\x1B[31m${s}\x1B[0m`, dim9 = (s) => `\x1B[2m${s}\x1B[0m`;
+var green9 = (s) => `\x1B[32m${s}\x1B[0m`, red5 = (s) => `\x1B[31m${s}\x1B[0m`, dim8 = (s) => `\x1B[2m${s}\x1B[0m`;
 var init_stop = __esm(() => {
   init_supervisor();
 });
@@ -19357,32 +20513,33 @@ var init_stop = __esm(() => {
 // src/cli/quickstart.ts
 var exports_quickstart = {};
 __export(exports_quickstart, {
-  run: () => run12
+  run: () => run14
 });
 function section2(title) {
   const bar = "─".repeat(60);
   return `
-${bold7(cyan6(title))}
-${dim10(bar)}`;
+${bold7(cyan5(title))}
+${dim9(bar)}`;
 }
 function cmd2(s) {
-  return yellow7(s);
+  return yellow6(s);
 }
 function flag(s) {
-  return green7(s);
+  return green10(s);
 }
-async function run12() {
+async function run14() {
   const lines = [
     "",
     bold7("specialists  ·  Quick Start Guide"),
-    dim10("One MCP server. Multiple AI backends. Intelligent orchestration."),
+    dim9("One MCP server. Multiple AI backends. Intelligent orchestration."),
+    dim9("Tip: sp is a shorter alias — sp run, sp list, sp feed etc. work identically."),
     ""
   ];
   lines.push(section2("1. Installation"));
   lines.push("");
   lines.push(`  ${cmd2("npm install -g @jaggerxtrm/specialists")}    # install globally`);
-  lines.push(`  ${cmd2("specialists install")}                       # full-stack setup:`);
-  lines.push(`  ${dim10("                                            #   pi · beads · dolt · MCP · hooks")}`);
+  lines.push(`  ${cmd2("specialists install")}                       # project setup:`);
+  lines.push(`  ${dim9("                                            #   checks pi · bd · xt, then wires MCP + hooks")}`);
   lines.push("");
   lines.push(`  Verify everything is healthy:`);
   lines.push(`  ${cmd2("specialists status")}                        # shows pi, beads, MCP, active jobs`);
@@ -19393,9 +20550,9 @@ async function run12() {
   lines.push(`  ${cmd2("specialists init")}                          # creates specialists/, .specialists/, AGENTS.md`);
   lines.push("");
   lines.push(`  What this creates:`);
-  lines.push(`  ${dim10("specialists/")}       — put your .specialist.yaml files here`);
-  lines.push(`  ${dim10(".specialists/")}      — runtime data (jobs/, ready/) — gitignored`);
-  lines.push(`  ${dim10("AGENTS.md")}          — context block injected into Claude sessions`);
+  lines.push(`  ${dim9("specialists/")}       — put your .specialist.yaml files here`);
+  lines.push(`  ${dim9(".specialists/")}      — runtime data (jobs/, ready/) — gitignored`);
+  lines.push(`  ${dim9("AGENTS.md")}          — context block injected into Claude sessions`);
   lines.push("");
   lines.push(section2("3. Discover Specialists"));
   lines.push("");
@@ -19406,24 +20563,24 @@ async function run12() {
   lines.push(`  ${cmd2("specialists list")} ${flag("--json")}                     # machine-readable JSON`);
   lines.push("");
   lines.push(`  Scopes (searched in order):`);
-  lines.push(`  ${blue("project")}   ./specialists/*.specialist.yaml`);
-  lines.push(`  ${blue("user")}      ~/.specialists/*.specialist.yaml`);
-  lines.push(`  ${blue("system")}    bundled specialists (shipped with the package)`);
+  lines.push(`  ${blue2("project")}   ./specialists/*.specialist.yaml`);
+  lines.push(`  ${blue2("user")}      ~/.specialists/*.specialist.yaml`);
+  lines.push(`  ${blue2("system")}    bundled specialists (shipped with the package)`);
   lines.push("");
   lines.push(section2("4. Running a Specialist"));
   lines.push("");
   lines.push(`  ${bold7("Foreground")} (streams output to stdout):`);
-  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--prompt")} ${dim10('"Review src/api.ts for security issues"')}`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--prompt")} ${dim9('"Review src/api.ts for security issues"')}`);
   lines.push("");
   lines.push(`  ${bold7("Background")} (returns a job ID immediately):`);
-  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--prompt")} ${dim10('"..."')} ${flag("--background")}`);
-  lines.push(`  ${dim10("  # → Job started: job_a1b2c3d4")}`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--prompt")} ${dim9('"..."')} ${flag("--background")}`);
+  lines.push(`  ${dim9("  # → Job started: job_a1b2c3d4")}`);
   lines.push("");
   lines.push(`  Override model for one run:`);
-  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--model")} ${dim10("anthropic/claude-opus-4-6")} ${flag("--prompt")} ${dim10('"..."')}`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--model")} ${dim9("anthropic/claude-opus-4-6")} ${flag("--prompt")} ${dim9('"..."')}`);
   lines.push("");
   lines.push(`  Run without beads issue tracking:`);
-  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--no-beads")} ${flag("--prompt")} ${dim10('"..."')}`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--no-beads")} ${flag("--prompt")} ${dim9('"..."')}`);
   lines.push("");
   lines.push(`  Pipe a prompt from stdin:`);
   lines.push(`  ${cmd2("cat my-brief.md | specialists run code-review")}`);
@@ -19437,25 +20594,37 @@ async function run12() {
   lines.push(`  ${bold7("Read results")} — print the final output:`);
   lines.push(`  ${cmd2("specialists result job_a1b2c3d4")}          # exits 1 if still running`);
   lines.push("");
+  lines.push(`  ${bold7("Steer a running job")} — redirect the agent mid-run without cancelling:`);
+  lines.push(`  ${cmd2("specialists steer job_a1b2c3d4")} ${flag('"focus only on supervisor.ts"')}`);
+  lines.push(`  ${dim9("  # delivered after current tool calls finish, before the next LLM call")}`);
+  lines.push("");
+  lines.push(`  ${bold7("Keep-alive multi-turn")} — start with ${flag("--keep-alive")}, then follow up:`);
+  lines.push(`  ${cmd2("specialists run bug-hunt")} ${flag("--bead unitAI-abc --keep-alive --background")}`);
+  lines.push(`  ${dim9("  # → Job started: a1b2c3  (status: waiting after first turn)")}`);
+  lines.push(`  ${cmd2("specialists result a1b2c3")}                   # read first turn`);
+  lines.push(`  ${cmd2("specialists follow-up a1b2c3")} ${flag('"now write the fix"')}    # next turn, same Pi context`);
+  lines.push(`  ${cmd2("specialists feed a1b2c3")} ${flag("--follow")}               # watch response`);
+  lines.push("");
   lines.push(`  ${bold7("Cancel a job")}:`);
   lines.push(`  ${cmd2("specialists stop job_a1b2c3d4")}            # sends SIGTERM to the agent process`);
   lines.push("");
-  lines.push(`  ${bold7("Job files")} in ${dim10(".specialists/jobs/<job-id>/")}:`);
-  lines.push(`  ${dim10("status.json")}   — id, specialist, status, pid, started_at, elapsed_s, current_tool`);
-  lines.push(`  ${dim10("events.jsonl")} — one JSON event per line (tool_use, text, agent_end, error …)`);
-  lines.push(`  ${dim10("result.txt")}    — final output (written when status=done)`);
+  lines.push(`  ${bold7("Job files")} in ${dim9(".specialists/jobs/<job-id>/")}:`);
+  lines.push(`  ${dim9("status.json")}   — id, specialist, status, pid, started_at, elapsed_s, current_tool`);
+  lines.push(`  ${dim9("events.jsonl")} — one JSON event per line (tool_use, text, agent_end, error …)`);
+  lines.push(`  ${dim9("result.txt")}    — final output (written when status=done)`);
+  lines.push(`  ${dim9("steer.pipe")}    — named FIFO for mid-run steering (removed on job completion)`);
   lines.push("");
   lines.push(section2("6. Editing Specialists"));
   lines.push("");
   lines.push(`  Change a field without opening the YAML manually:`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim10("anthropic/claude-sonnet-4-6")}`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--description")} ${dim10('"Updated description"')}`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--timeout")} ${dim10("120000")}`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--permission")} ${dim10("HIGH")}`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--tags")} ${dim10("analysis,security,review")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim9("anthropic/claude-sonnet-4-6")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--description")} ${dim9('"Updated description"')}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--timeout")} ${dim9("120000")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--permission")} ${dim9("HIGH")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--tags")} ${dim9("analysis,security,review")}`);
   lines.push("");
   lines.push(`  Preview without writing:`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim10("...")} ${flag("--dry-run")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim9("...")} ${flag("--dry-run")}`);
   lines.push("");
   lines.push(section2("7. .specialist.yaml Schema"));
   lines.push("");
@@ -19502,21 +20671,21 @@ async function run12() {
     "    priority: 2                  # 0=critical … 4=backlog"
   ];
   for (const l of schemaLines) {
-    lines.push(`  ${dim10(l)}`);
+    lines.push(`  ${dim9(l)}`);
   }
   lines.push("");
   lines.push(section2("8. Hook System"));
   lines.push("");
-  lines.push(`  Specialists emits lifecycle events to ${dim10(".specialists/trace.jsonl")}:`);
+  lines.push(`  Specialists emits lifecycle events to ${dim9(".specialists/trace.jsonl")}:`);
   lines.push("");
   lines.push(`  ${bold7("Hook point")}              ${bold7("When fired")}`);
-  lines.push(`  ${yellow7("specialist:start")}       before the agent session begins`);
-  lines.push(`  ${yellow7("specialist:token")}       on each streamed token (delta)`);
-  lines.push(`  ${yellow7("specialist:done")}        after successful completion`);
-  lines.push(`  ${yellow7("specialist:error")}       on failure or timeout`);
+  lines.push(`  ${yellow6("specialist:start")}       before the agent session begins`);
+  lines.push(`  ${yellow6("specialist:token")}       on each streamed token (delta)`);
+  lines.push(`  ${yellow6("specialist:done")}        after successful completion`);
+  lines.push(`  ${yellow6("specialist:error")}       on failure or timeout`);
   lines.push("");
   lines.push(`  Each event line in trace.jsonl:`);
-  lines.push(`  ${dim10('{"t":"<ISO>","hook":"specialist:done","specialist":"code-review","durationMs":4120}')}`);
+  lines.push(`  ${dim9('{"t":"<ISO>","hook":"specialist:done","specialist":"code-review","durationMs":4120}')}`);
   lines.push("");
   lines.push(`  Tail the trace file to observe all activity:`);
   lines.push(`  ${cmd2("tail -f .specialists/trace.jsonl | jq .")}`);
@@ -19531,7 +20700,9 @@ async function run12() {
   lines.push(`  ${bold7("run_parallel")}       — concurrent or pipeline execution`);
   lines.push(`  ${bold7("start_specialist")}   — async job start, returns job ID`);
   lines.push(`  ${bold7("poll_specialist")}    — poll job status/output by ID`);
-  lines.push(`  ${bold7("stop_specialist")}    — cancel a running job by ID`);
+  lines.push(`  ${bold7("steer_specialist")}      — send a mid-run message to a running job`);
+  lines.push(`  ${bold7("follow_up_specialist")} — send a next-turn prompt to a keep-alive session`);
+  lines.push(`  ${bold7("stop_specialist")}      — cancel a running job by ID`);
   lines.push(`  ${bold7("specialist_status")}  — circuit breaker health + staleness`);
   lines.push("");
   lines.push(section2("10. Common Workflows"));
@@ -19544,41 +20715,51 @@ async function run12() {
   lines.push(`  ${cmd2("specialists feed <job-id> --follow")}`);
   lines.push(`  ${cmd2("specialists result <job-id> > analysis.md")}`);
   lines.push("");
+  lines.push(`  ${bold7("Steer a job mid-run:")}`);
+  lines.push(`  ${cmd2('specialists run deep-analysis --prompt "..." --background')}`);
+  lines.push(`  ${cmd2('specialists steer <job-id> "focus only on the auth module"')}`);
+  lines.push(`  ${cmd2("specialists result <job-id>")}`);
+  lines.push("");
+  lines.push(`  ${bold7("Multi-turn keep-alive (iterative work):")}`);
+  lines.push(`  ${cmd2("specialists run bug-hunt --bead unitAI-abc --keep-alive --background")}`);
+  lines.push(`  ${cmd2("specialists result <job-id>")}`);
+  lines.push(`  ${cmd2('specialists follow-up <job-id> "now write the fix for the root cause"')}`);
+  lines.push(`  ${cmd2("specialists feed <job-id> --follow")}`);
+  lines.push("");
   lines.push(`  ${bold7("Override model for a single run:")}`);
   lines.push(`  ${cmd2('specialists run code-review --model anthropic/claude-opus-4-6 --prompt "..."')}`);
   lines.push("");
-  lines.push(dim10("─".repeat(62)));
-  lines.push(`  ${dim10("specialists help")}     command list         ${dim10("specialists <cmd> --help")}   per-command flags`);
-  lines.push(`  ${dim10("specialists status")}   health check         ${dim10("specialists models")}         available models`);
+  lines.push(dim9("─".repeat(62)));
+  lines.push(`  ${dim9("specialists help")}     command list         ${dim9("specialists <cmd> --help")}   per-command flags`);
+  lines.push(`  ${dim9("specialists status")}   health check         ${dim9("specialists models")}         available models`);
   lines.push("");
   console.log(lines.join(`
 `));
 }
-var bold7 = (s) => `\x1B[1m${s}\x1B[0m`, dim10 = (s) => `\x1B[2m${s}\x1B[0m`, yellow7 = (s) => `\x1B[33m${s}\x1B[0m`, cyan6 = (s) => `\x1B[36m${s}\x1B[0m`, blue = (s) => `\x1B[34m${s}\x1B[0m`, green7 = (s) => `\x1B[32m${s}\x1B[0m`;
+var bold7 = (s) => `\x1B[1m${s}\x1B[0m`, dim9 = (s) => `\x1B[2m${s}\x1B[0m`, yellow6 = (s) => `\x1B[33m${s}\x1B[0m`, cyan5 = (s) => `\x1B[36m${s}\x1B[0m`, blue2 = (s) => `\x1B[34m${s}\x1B[0m`, green10 = (s) => `\x1B[32m${s}\x1B[0m`;
 
 // src/cli/doctor.ts
 var exports_doctor = {};
 __export(exports_doctor, {
-  run: () => run13
+  run: () => run15
 });
-import { spawnSync as spawnSync5 } from "node:child_process";
-import { existsSync as existsSync8, mkdirSync as mkdirSync3, readFileSync as readFileSync6, readdirSync as readdirSync2 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { join as join12 } from "node:path";
+import { spawnSync as spawnSync7 } from "node:child_process";
+import { existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync7, readdirSync as readdirSync4 } from "node:fs";
+import { join as join18 } from "node:path";
 function ok3(msg) {
-  console.log(`  ${green8("✓")} ${msg}`);
+  console.log(`  ${green11("✓")} ${msg}`);
 }
 function warn2(msg) {
-  console.log(`  ${yellow8("○")} ${msg}`);
+  console.log(`  ${yellow7("○")} ${msg}`);
 }
 function fail2(msg) {
-  console.log(`  ${red5("✗")} ${msg}`);
+  console.log(`  ${red6("✗")} ${msg}`);
 }
 function fix(msg) {
-  console.log(`    ${dim11("→ fix:")} ${yellow8(msg)}`);
+  console.log(`    ${dim10("→ fix:")} ${yellow7(msg)}`);
 }
 function hint(msg) {
-  console.log(`    ${dim11(msg)}`);
+  console.log(`    ${dim10(msg)}`);
 }
 function section3(label) {
   const line = "─".repeat(Math.max(0, 38 - label.length));
@@ -19586,17 +20767,26 @@ function section3(label) {
 ${bold8(`── ${label} ${line}`)}`);
 }
 function sp(bin, args) {
-  const r = spawnSync5(bin, args, { encoding: "utf8", stdio: "pipe", timeout: 5000 });
+  const r = spawnSync7(bin, args, { encoding: "utf8", stdio: "pipe", timeout: 5000 });
   return { ok: r.status === 0 && !r.error, stdout: (r.stdout ?? "").trim() };
 }
 function isInstalled2(bin) {
-  return spawnSync5("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
+  return spawnSync7("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
+}
+function loadJson2(path) {
+  if (!existsSync11(path))
+    return null;
+  try {
+    return JSON.parse(readFileSync7(path, "utf8"));
+  } catch {
+    return null;
+  }
 }
 function checkPi() {
   section3("pi  (coding agent runtime)");
   if (!isInstalled2("pi")) {
     fail2("pi not installed");
-    fix("specialists install");
+    fix("install pi first");
     return false;
   }
   const version2 = sp("pi", ["--version"]);
@@ -19609,75 +20799,94 @@ function checkPi() {
     fix("pi config   (add at least one API key)");
     return false;
   }
-  ok3(`pi ${vStr}  —  ${providers.size} provider${providers.size > 1 ? "s" : ""} active  ${dim11(`(${[...providers].join(", ")})`)} `);
+  ok3(`pi ${vStr}  —  ${providers.size} provider${providers.size > 1 ? "s" : ""} active  ${dim10(`(${[...providers].join(", ")})`)}`);
+  return true;
+}
+function checkBd() {
+  section3("beads  (issue tracker)");
+  if (!isInstalled2("bd")) {
+    fail2("bd not installed");
+    fix("install beads (bd) first");
+    return false;
+  }
+  ok3(`bd installed  ${dim10(sp("bd", ["--version"]).stdout || "")}`);
+  if (existsSync11(join18(CWD, ".beads")))
+    ok3(".beads/ present in project");
+  else
+    warn2(".beads/ not found in project");
+  return true;
+}
+function checkXt() {
+  section3("xtrm-tools");
+  if (!isInstalled2("xt")) {
+    fail2("xt not installed");
+    fix("install xtrm-tools first");
+    return false;
+  }
+  ok3(`xt installed  ${dim10(sp("xt", ["--version"]).stdout || "")}`);
   return true;
 }
 function checkHooks() {
-  section3("Claude Code hooks  (7 expected)");
+  section3("Claude Code hooks  (2 expected)");
   let allPresent = true;
   for (const name of HOOK_NAMES) {
-    const dest = join12(HOOKS_DIR, name);
-    if (!existsSync8(dest)) {
-      fail2(`${name}  ${red5("missing")}`);
-      fix("specialists install   (reinstalls all hooks)");
+    const dest = join18(HOOKS_DIR, name);
+    if (!existsSync11(dest)) {
+      fail2(`${name}  ${red6("missing")}`);
+      fix("specialists install");
       allPresent = false;
     } else {
       ok3(name);
     }
   }
-  if (allPresent && existsSync8(SETTINGS_FILE)) {
-    try {
-      const settings = JSON.parse(readFileSync6(SETTINGS_FILE, "utf8"));
-      const hooks = settings.hooks ?? {};
-      const allEntries = [
-        ...hooks.PreToolUse ?? [],
-        ...hooks.PostToolUse ?? [],
-        ...hooks.Stop ?? [],
-        ...hooks.UserPromptSubmit ?? [],
-        ...hooks.SessionStart ?? []
-      ];
-      const wiredCommands = new Set(allEntries.flatMap((e) => (e.hooks ?? []).map((h) => h.command ?? "")));
-      const guardWired = [...wiredCommands].some((c) => c.includes("specialists-main-guard"));
-      if (!guardWired) {
-        warn2("specialists-main-guard not wired in settings.json");
-        fix("specialists install   (rewires hooks in settings.json)");
-        allPresent = false;
-      } else {
-        hint(`Hooks wired in ${SETTINGS_FILE}`);
-      }
-    } catch {
-      warn2(`Could not parse ${SETTINGS_FILE}`);
+  const settings = loadJson2(SETTINGS_FILE);
+  if (!settings) {
+    warn2(`Could not read ${SETTINGS_FILE}`);
+    fix("specialists install");
+    return false;
+  }
+  const wiredCommands = new Set([
+    ...settings.UserPromptSubmit ?? [],
+    ...settings.SessionStart ?? []
+  ].flatMap((entry) => (entry.hooks ?? []).map((h) => h.command ?? "")));
+  for (const name of HOOK_NAMES) {
+    const expectedRelative = `node .specialists/default/hooks/${name}`;
+    if (!wiredCommands.has(expectedRelative)) {
+      warn2(`${name} not wired in settings.json`);
+      fix("specialists install");
       allPresent = false;
     }
   }
+  if (allPresent)
+    hint(`Hooks wired in ${SETTINGS_FILE}`);
   return allPresent;
 }
 function checkMCP() {
   section3("MCP registration");
-  const check2 = sp("claude", ["mcp", "get", MCP_NAME]);
-  if (!check2.ok) {
-    fail2(`MCP server '${MCP_NAME}' not registered`);
-    fix(`specialists install   (or: claude mcp add --scope user ${MCP_NAME} -- specialists)`);
+  const mcp = loadJson2(MCP_FILE2);
+  const spec = mcp?.mcpServers?.specialists;
+  if (!spec || spec.command !== "specialists") {
+    fail2(`MCP server 'specialists' not registered in .mcp.json`);
+    fix("specialists install");
     return false;
   }
-  ok3(`MCP server '${MCP_NAME}' registered`);
+  ok3(`MCP server 'specialists' registered in ${MCP_FILE2}`);
   return true;
 }
 function checkRuntimeDirs() {
   section3(".specialists/ runtime directories");
-  const cwd = process.cwd();
-  const rootDir = join12(cwd, ".specialists");
-  const jobsDir = join12(rootDir, "jobs");
-  const readyDir = join12(rootDir, "ready");
+  const rootDir = join18(CWD, ".specialists");
+  const jobsDir = join18(rootDir, "jobs");
+  const readyDir = join18(rootDir, "ready");
   let allOk = true;
-  if (!existsSync8(rootDir)) {
+  if (!existsSync11(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 (!existsSync8(subDir)) {
+      if (!existsSync11(subDir)) {
         warn2(`.specialists/${label}/ missing — auto-creating`);
         mkdirSync3(subDir, { recursive: true });
         ok3(`.specialists/${label}/ created`);
@@ -19690,14 +20899,14 @@ function checkRuntimeDirs() {
 }
 function checkZombieJobs() {
   section3("Background jobs");
-  const jobsDir = join12(process.cwd(), ".specialists", "jobs");
-  if (!existsSync8(jobsDir)) {
+  const jobsDir = join18(CWD, ".specialists", "jobs");
+  if (!existsSync11(jobsDir)) {
     hint("No .specialists/jobs/ — skipping");
     return true;
   }
   let entries;
   try {
-    entries = readdirSync2(jobsDir);
+    entries = readdirSync4(jobsDir);
   } catch {
     entries = [];
   }
@@ -19709,11 +20918,11 @@ function checkZombieJobs() {
   let total = 0;
   let running = 0;
   for (const jobId of entries) {
-    const statusPath = join12(jobsDir, jobId, "status.json");
-    if (!existsSync8(statusPath))
+    const statusPath = join18(jobsDir, jobId, "status.json");
+    if (!existsSync11(statusPath))
       continue;
     try {
-      const status = JSON.parse(readFileSync6(statusPath, "utf8"));
+      const status = JSON.parse(readFileSync7(statusPath, "utf8"));
       total++;
       if (status.status === "running" || status.status === "starting") {
         const pid = status.pid;
@@ -19723,11 +20932,11 @@ function checkZombieJobs() {
             process.kill(pid, 0);
             alive = true;
           } catch {}
-          if (alive) {
+          if (alive)
             running++;
-          } else {
+          else {
             zombies++;
-            warn2(`${jobId}  ${yellow8("ZOMBIE")}  ${dim11(`pid ${pid} not found, status=${status.status}`)}`);
+            warn2(`${jobId}  ${yellow7("ZOMBIE")}  ${dim10(`pid ${pid} not found, status=${status.status}`)}`);
             fix(`Edit .specialists/jobs/${jobId}/status.json  →  set "status": "error"`);
           }
         }
@@ -19740,37 +20949,36 @@ function checkZombieJobs() {
   }
   return zombies === 0;
 }
-async function run13() {
+async function run15() {
   console.log(`
 ${bold8("specialists doctor")}
 `);
   const piOk = checkPi();
+  const bdOk = checkBd();
+  const xtOk = checkXt();
   const hooksOk = checkHooks();
   const mcpOk = checkMCP();
   const dirsOk = checkRuntimeDirs();
   const jobsOk = checkZombieJobs();
-  const allOk = piOk && hooksOk && mcpOk && dirsOk && jobsOk;
+  const allOk = piOk && bdOk && xtOk && hooksOk && mcpOk && dirsOk && jobsOk;
   console.log("");
   if (allOk) {
-    console.log(`  ${green8("✓")} ${bold8("All checks passed")}  — specialists is healthy`);
+    console.log(`  ${green11("✓")} ${bold8("All checks passed")}  — specialists is healthy`);
   } else {
-    console.log(`  ${yellow8("○")} ${bold8("Some checks failed")}  — follow the fix hints above`);
-    console.log(`  ${dim11("specialists install  fixes most issues automatically.")}`);
+    console.log(`  ${yellow7("○")} ${bold8("Some checks failed")}  — follow the fix hints above`);
+    console.log(`  ${dim10("specialists install fixes hook + MCP registration; pi, bd, and xt must be installed separately.")}`);
   }
   console.log("");
 }
-var bold8 = (s) => `\x1B[1m${s}\x1B[0m`, dim11 = (s) => `\x1B[2m${s}\x1B[0m`, green8 = (s) => `\x1B[32m${s}\x1B[0m`, yellow8 = (s) => `\x1B[33m${s}\x1B[0m`, red5 = (s) => `\x1B[31m${s}\x1B[0m`, HOME, CLAUDE_DIR, HOOKS_DIR, SETTINGS_FILE, MCP_NAME = "specialists", HOOK_NAMES;
+var bold8 = (s) => `\x1B[1m${s}\x1B[0m`, dim10 = (s) => `\x1B[2m${s}\x1B[0m`, green11 = (s) => `\x1B[32m${s}\x1B[0m`, yellow7 = (s) => `\x1B[33m${s}\x1B[0m`, red6 = (s) => `\x1B[31m${s}\x1B[0m`, CWD, CLAUDE_DIR, SPECIALISTS_DIR, HOOKS_DIR, SETTINGS_FILE, MCP_FILE2, HOOK_NAMES;
 var init_doctor = __esm(() => {
-  HOME = homedir2();
-  CLAUDE_DIR = join12(HOME, ".claude");
-  HOOKS_DIR = join12(CLAUDE_DIR, "hooks");
-  SETTINGS_FILE = join12(CLAUDE_DIR, "settings.json");
+  CWD = process.cwd();
+  CLAUDE_DIR = join18(CWD, ".claude");
+  SPECIALISTS_DIR = join18(CWD, ".specialists");
+  HOOKS_DIR = join18(SPECIALISTS_DIR, "default", "hooks");
+  SETTINGS_FILE = join18(CLAUDE_DIR, "settings.json");
+  MCP_FILE2 = join18(CWD, ".mcp.json");
   HOOK_NAMES = [
-    "specialists-main-guard.mjs",
-    "beads-edit-gate.mjs",
-    "beads-commit-gate.mjs",
-    "beads-stop-gate.mjs",
-    "beads-close-memory-prompt.mjs",
     "specialists-complete.mjs",
     "specialists-session-start.mjs"
   ];
@@ -19779,29 +20987,29 @@ var init_doctor = __esm(() => {
 // src/cli/setup.ts
 var exports_setup = {};
 __export(exports_setup, {
-  run: () => run14
+  run: () => run16
 });
-import { existsSync as existsSync9, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync12, readFileSync as readFileSync8, writeFileSync as writeFileSync8 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { join as join13, resolve } from "node:path";
+import { join as join19, resolve as resolve2 } from "node:path";
 function ok4(msg) {
-  console.log(`  ${green9("✓")} ${msg}`);
+  console.log(`  ${green12("✓")} ${msg}`);
 }
 function skip2(msg) {
-  console.log(`  ${yellow9("○")} ${msg}`);
+  console.log(`  ${yellow8("○")} ${msg}`);
 }
 function resolveTarget(target) {
   switch (target) {
     case "global":
-      return join13(homedir3(), ".claude", "CLAUDE.md");
+      return join19(homedir3(), ".claude", "CLAUDE.md");
     case "agents":
-      return join13(process.cwd(), "AGENTS.md");
+      return join19(process.cwd(), "AGENTS.md");
     case "project":
     default:
-      return join13(process.cwd(), "CLAUDE.md");
+      return join19(process.cwd(), "CLAUDE.md");
   }
 }
-function parseArgs5() {
+function parseArgs6() {
   const argv = process.argv.slice(3);
   let target = "project";
   let dryRun = false;
@@ -19826,30 +21034,30 @@ function parseArgs5() {
   }
   return { target, dryRun };
 }
-async function run14() {
-  const { target, dryRun } = parseArgs5();
-  const filePath = resolve(resolveTarget(target));
+async function run16() {
+  const { target, dryRun } = parseArgs6();
+  const filePath = resolve2(resolveTarget(target));
   const label = target === "global" ? "~/.claude/CLAUDE.md" : filePath.replace(process.cwd() + "/", "");
   console.log(`
 ${bold9("specialists setup")}
 `);
-  console.log(`  Target: ${yellow9(label)}${dryRun ? dim12("  (dry-run)") : ""}
+  console.log(`  Target: ${yellow8(label)}${dryRun ? dim11("  (dry-run)") : ""}
 `);
-  if (existsSync9(filePath)) {
-    const existing = readFileSync7(filePath, "utf8");
+  if (existsSync12(filePath)) {
+    const existing = readFileSync8(filePath, "utf8");
     if (existing.includes(MARKER)) {
       skip2(`${label} already contains Specialists Workflow section`);
       console.log(`
-  ${dim12("To force-update, remove the ## Specialists Workflow section and re-run.")}
+  ${dim11("To force-update, remove the ## Specialists Workflow section and re-run.")}
 `);
       return;
     }
     if (dryRun) {
-      console.log(dim12("─".repeat(60)));
-      console.log(dim12("Would append to existing file:"));
+      console.log(dim11("─".repeat(60)));
+      console.log(dim11("Would append to existing file:"));
       console.log("");
       console.log(WORKFLOW_BLOCK);
-      console.log(dim12("─".repeat(60)));
+      console.log(dim11("─".repeat(60)));
       return;
     }
     const separator = existing.trimEnd().endsWith(`
@@ -19857,28 +21065,28 @@ ${bold9("specialists setup")}
 ` : `
 
 `;
-    writeFileSync4(filePath, existing.trimEnd() + separator + WORKFLOW_BLOCK, "utf8");
+    writeFileSync8(filePath, existing.trimEnd() + separator + WORKFLOW_BLOCK, "utf8");
     ok4(`Appended Specialists Workflow section to ${label}`);
   } else {
     if (dryRun) {
-      console.log(dim12("─".repeat(60)));
-      console.log(dim12(`Would create ${label}:`));
+      console.log(dim11("─".repeat(60)));
+      console.log(dim11(`Would create ${label}:`));
       console.log("");
       console.log(WORKFLOW_BLOCK);
-      console.log(dim12("─".repeat(60)));
+      console.log(dim11("─".repeat(60)));
       return;
     }
-    writeFileSync4(filePath, WORKFLOW_BLOCK, "utf8");
+    writeFileSync8(filePath, WORKFLOW_BLOCK, "utf8");
     ok4(`Created ${label} with Specialists Workflow section`);
   }
   console.log("");
-  console.log(`  ${dim12("Next steps:")}`);
+  console.log(`  ${dim11("Next steps:")}`);
   console.log(`  • Restart Claude Code to pick up the new context`);
-  console.log(`  • Run ${yellow9("specialists list")} to see available specialists`);
-  console.log(`  • Run ${yellow9("specialist_init")} in a new session to bootstrap context`);
+  console.log(`  • Run ${yellow8("specialists list")} to see available specialists`);
+  console.log(`  • Run ${yellow8("specialist_init")} in a new session to bootstrap context`);
   console.log("");
 }
-var bold9 = (s) => `\x1B[1m${s}\x1B[0m`, dim12 = (s) => `\x1B[2m${s}\x1B[0m`, green9 = (s) => `\x1B[32m${s}\x1B[0m`, yellow9 = (s) => `\x1B[33m${s}\x1B[0m`, MARKER = "## Specialists Workflow", WORKFLOW_BLOCK = `## Specialists Workflow
+var bold9 = (s) => `\x1B[1m${s}\x1B[0m`, dim11 = (s) => `\x1B[2m${s}\x1B[0m`, green12 = (s) => `\x1B[32m${s}\x1B[0m`, yellow8 = (s) => `\x1B[33m${s}\x1B[0m`, MARKER = "## Specialists Workflow", WORKFLOW_BLOCK = `## Specialists Workflow
 
 > Injected by \`specialists setup\`. Keep this section — agents use it for context.
 
@@ -19946,61 +21154,104 @@ var init_setup = () => {};
 // src/cli/help.ts
 var exports_help = {};
 __export(exports_help, {
-  run: () => run15
+  run: () => run17
 });
-function formatGroup(label, entries) {
-  const colWidth = Math.max(...entries.map(([cmd3]) => cmd3.length));
-  return [
-    "",
-    bold10(cyan7(label)),
-    ...entries.map(([cmd3, desc]) => `  ${cmd3.padEnd(colWidth)}    ${dim13(desc)}`)
-  ];
+function formatCommands(entries) {
+  const width = Math.max(...entries.map(([cmd3]) => cmd3.length));
+  return entries.map(([cmd3, desc]) => `  ${cmd3.padEnd(width)}   ${desc}`);
 }
-async function run15() {
+async function run17() {
   const lines = [
     "",
-    bold10("specialists <command> [options]"),
+    "Specialists lets you run project-scoped specialist agents with a bead-first workflow.",
+    "",
+    bold10("Usage:"),
+    "  specialists|sp [command]",
+    "  specialists|sp [command] --help",
     "",
-    dim13("One MCP server. Multiple AI backends. Intelligent orchestration."),
-    ...formatGroup("Setup", SETUP),
-    ...formatGroup("Discovery", DISCOVERY),
-    ...formatGroup("Running", RUNNING),
-    ...formatGroup("Jobs", JOBS),
-    ...formatGroup("Other", OTHER),
+    dim12("  sp is a shorter alias — sp run, sp list, sp feed etc. all work identically."),
     "",
-    dim13("Run 'specialists <command> --help' for command-specific options."),
-    dim13("Run 'specialists quickstart' for a full getting-started guide."),
+    bold10("Common flows:"),
+    "",
+    "  Tracked work (primary)",
+    '    bd create "Task title" -t task -p 1 --json',
+    "    specialists run <name> --bead <id> [--context-depth N] [--background] [--follow]",
+    "    specialists feed -f",
+    '    bd close <id> --reason "Done"',
+    "",
+    "  Ad-hoc work",
+    '    specialists run <name> --prompt "..."',
+    "",
+    "  Rules",
+    "    --bead is for tracked work",
+    "    --prompt is for quick untracked work",
+    "    --context-depth defaults to 1 with --bead",
+    "    --no-beads does not disable bead reading",
+    "    --follow runs in background and streams output live",
+    "",
+    bold10("Core commands:"),
+    ...formatCommands(CORE_COMMANDS),
+    "",
+    bold10("Extended commands:"),
+    ...formatCommands(EXTENDED_COMMANDS),
+    "",
+    bold10("xtrm worktree commands:"),
+    ...formatCommands(WORKTREE_COMMANDS),
+    "",
+    bold10("Examples:"),
+    "  specialists init",
+    "  specialists list",
+    "  specialists run bug-hunt --bead unitAI-123 --background",
+    "  specialists run sync-docs --follow                 # run + stream live output",
+    '  specialists run codebase-explorer --prompt "Map the CLI architecture"',
+    "  specialists feed -f",
+    '  specialists steer <job-id> "focus only on supervisor.ts"',
+    '  specialists follow-up <job-id> "now write the fix"',
+    "  specialists result <job-id>",
+    "",
+    bold10("More help:"),
+    "  specialists quickstart         Full guide and workflow reference",
+    "  specialists run --help         Run command details and flags",
+    "  specialists steer --help       Mid-run steering details",
+    "  specialists follow-up --help   Multi-turn keep-alive details",
+    "  specialists init --help        Bootstrap behavior and workflow injection",
+    "  specialists feed --help        Background job monitoring details",
+    "",
+    dim12("Project model: specialists are project-only; user-scope discovery is deprecated."),
     ""
   ];
   console.log(lines.join(`
 `));
 }
-var bold10 = (s) => `\x1B[1m${s}\x1B[0m`, dim13 = (s) => `\x1B[2m${s}\x1B[0m`, cyan7 = (s) => `\x1B[36m${s}\x1B[0m`, SETUP, DISCOVERY, RUNNING, JOBS, OTHER;
+var bold10 = (s) => `\x1B[1m${s}\x1B[0m`, dim12 = (s) => `\x1B[2m${s}\x1B[0m`, CORE_COMMANDS, EXTENDED_COMMANDS, WORKTREE_COMMANDS;
 var init_help = __esm(() => {
-  SETUP = [
-    ["install", "Full-stack installer: pi, beads, dolt, MCP registration, hooks"],
-    ["init", "Scaffold specialists/, .specialists/, AGENTS.md in current project"],
-    ["setup", "Inject workflow context block into CLAUDE.md or AGENTS.md"],
-    ["quickstart", "Rich getting-started guide with examples and YAML schema reference"],
-    ["doctor", "Health check: pi, hooks, MCP registration, dirs, zombie jobs"]
-  ];
-  DISCOVERY = [
-    ["list", "List available specialists with model and description"],
-    ["models", "List models available on pi, flagged with thinking/images support"],
-    ["status", "Show system health (pi, beads, MCP, jobs)"]
-  ];
-  RUNNING = [
-    ["run", "Run a specialist with a prompt (--background for async)"],
-    ["edit", "Edit a specialist field  (e.g. --model, --description)"]
-  ];
-  JOBS = [
-    ["feed", "Tail events for a background job (--follow to stream)"],
-    ["result", "Print result of a background job"],
-    ["stop", "Send SIGTERM to a running background job"]
+  CORE_COMMANDS = [
+    ["init", "Bootstrap a project: dirs, workflow injection, project MCP registration"],
+    ["list", "List specialists in this project"],
+    ["run", "Run a specialist with --bead for tracked work or --prompt for ad-hoc work"],
+    ["feed", "Tail job events; use -f to follow all jobs"],
+    ["result", "Print final output of a completed background job"],
+    ["steer", "Send a mid-run message to a running background job"],
+    ["follow-up", "Send a next-turn prompt to a keep-alive session (retains full context)"],
+    ["stop", "Stop a running background job"],
+    ["status", "Show health, MCP state, and active jobs"],
+    ["doctor", "Diagnose installation/runtime problems"],
+    ["quickstart", "Full getting-started guide"],
+    ["help", "Show this help"]
   ];
-  OTHER = [
+  EXTENDED_COMMANDS = [
+    ["edit", "Edit a specialist field such as model or description"],
+    ["models", "List models available on pi"],
     ["version", "Print installed version"],
-    ["help", "Show this help message"]
+    ["setup", "[deprecated] Use specialists init instead"],
+    ["install", "[deprecated] Use specialists init instead"]
+  ];
+  WORKTREE_COMMANDS = [
+    ["xt pi [name]", "Start a Pi session in a sandboxed xt worktree"],
+    ["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"]
   ];
 });
 
@@ -26030,6 +27281,9 @@ class Protocol {
     }
   }
   async connect(transport) {
+    if (this._transport) {
+      throw new Error("Already connected to a transport. Call close() before connecting to a new transport, or use a separate Protocol instance per connection.");
+    }
     this._transport = transport;
     const _onclose = this.transport?.onclose;
     this._transport.onclose = () => {
@@ -26062,6 +27316,10 @@ class Protocol {
     this._progressHandlers.clear();
     this._taskProgressTokens.clear();
     this._pendingDebouncedNotifications.clear();
+    for (const controller of this._requestHandlerAbortControllers.values()) {
+      controller.abort();
+    }
+    this._requestHandlerAbortControllers.clear();
     const error2 = McpError.fromError(ErrorCode.ConnectionClosed, "Connection closed");
     this._transport = undefined;
     this.onclose?.();
@@ -26112,6 +27370,8 @@ class Protocol {
       sessionId: capturedTransport?.sessionId,
       _meta: request.params?._meta,
       sendNotification: async (notification) => {
+        if (abortController.signal.aborted)
+          return;
         const notificationOptions = { relatedRequestId: request.id };
         if (relatedTaskId) {
           notificationOptions.relatedTask = { taskId: relatedTaskId };
@@ -26119,6 +27379,9 @@ class Protocol {
         await this.notification(notification, notificationOptions);
       },
       sendRequest: async (r, resultSchema, options) => {
+        if (abortController.signal.aborted) {
+          throw new McpError(ErrorCode.ConnectionClosed, "Request was cancelled");
+        }
         const requestOptions = { ...options, relatedRequestId: request.id };
         if (relatedTaskId && !requestOptions.relatedTask) {
           requestOptions.relatedTask = { taskId: relatedTaskId };
@@ -26732,6 +27995,62 @@ class ExperimentalServerTasks {
   requestStream(request, resultSchema, options) {
     return this._server.requestStream(request, resultSchema, options);
   }
+  createMessageStream(params, options) {
+    const clientCapabilities = this._server.getClientCapabilities();
+    if ((params.tools || params.toolChoice) && !clientCapabilities?.sampling?.tools) {
+      throw new Error("Client does not support sampling tools capability.");
+    }
+    if (params.messages.length > 0) {
+      const lastMessage = params.messages[params.messages.length - 1];
+      const lastContent = Array.isArray(lastMessage.content) ? lastMessage.content : [lastMessage.content];
+      const hasToolResults = lastContent.some((c) => c.type === "tool_result");
+      const previousMessage = params.messages.length > 1 ? params.messages[params.messages.length - 2] : undefined;
+      const previousContent = previousMessage ? Array.isArray(previousMessage.content) ? previousMessage.content : [previousMessage.content] : [];
+      const hasPreviousToolUse = previousContent.some((c) => c.type === "tool_use");
+      if (hasToolResults) {
+        if (lastContent.some((c) => c.type !== "tool_result")) {
+          throw new Error("The last message must contain only tool_result content if any is present");
+        }
+        if (!hasPreviousToolUse) {
+          throw new Error("tool_result blocks are not matching any tool_use from the previous message");
+        }
+      }
+      if (hasPreviousToolUse) {
+        const toolUseIds = new Set(previousContent.filter((c) => c.type === "tool_use").map((c) => c.id));
+        const toolResultIds = new Set(lastContent.filter((c) => c.type === "tool_result").map((c) => c.toolUseId));
+        if (toolUseIds.size !== toolResultIds.size || ![...toolUseIds].every((id) => toolResultIds.has(id))) {
+          throw new Error("ids of tool_result blocks and tool_use blocks from previous message do not match");
+        }
+      }
+    }
+    return this.requestStream({
+      method: "sampling/createMessage",
+      params
+    }, CreateMessageResultSchema, options);
+  }
+  elicitInputStream(params, options) {
+    const clientCapabilities = this._server.getClientCapabilities();
+    const mode = params.mode ?? "form";
+    switch (mode) {
+      case "url": {
+        if (!clientCapabilities?.elicitation?.url) {
+          throw new Error("Client does not support url elicitation.");
+        }
+        break;
+      }
+      case "form": {
+        if (!clientCapabilities?.elicitation?.form) {
+          throw new Error("Client does not support form elicitation.");
+        }
+        break;
+      }
+    }
+    const normalizedParams = mode === "form" && params.mode === undefined ? { ...params, mode: "form" } : params;
+    return this.requestStream({
+      method: "elicitation/create",
+      params: normalizedParams
+    }, ElicitResultSchema, options);
+  }
   async getTask(taskId, options) {
     return this._server.getTask({ taskId }, options);
   }
@@ -27206,7 +28525,7 @@ class StdioServerTransport {
 }
 
 // src/server.ts
-import { join as join3 } from "node:path";
+import { join as join7 } from "node:path";
 
 // src/constants.ts
 var LOG_PREFIX = "[specialists]";
@@ -27295,25 +28614,48 @@ 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().describe("The task or question for the specialist"),
+  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")
+  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.)")
+}).refine((input) => Boolean(input.prompt?.trim() || input.bead_id), {
+  message: "Either prompt or bead_id is required",
+  path: ["prompt"]
 });
 function createUseSpecialistTool(runner) {
   return {
     name: "use_specialist",
-    description: "Run a specialist synchronously and wait for the result. " + "Full lifecycle: load → agents.md → pi session → output. " + "Response includes output, model, durationMs, and beadId (string | undefined). " + "beadId is set when the specialist's beads_integration policy triggered bead creation " + "(default: auto — creates for LOW/MEDIUM/HIGH permission, skips for READ_ONLY). " + "If beadId is present, use `bd update <beadId> --notes` to attach findings or " + "`bd remember` to persist key discoveries for future sessions.",
+    description: "Run a specialist synchronously and wait for the result. " + "Full lifecycle: load → agents.md → pi session → output. " + "Response includes output, model, durationMs, and beadId (string | undefined). " + "beadId is set when the specialist's beads_integration policy triggered bead creation " + "(default: auto — creates for LOW/MEDIUM/HIGH permission, skips for READ_ONLY). " + "If beadId is present, use `bd update <beadId> --notes` to attach findings or " + "`bd remember` to persist key discoveries for future sessions. " + "When bead_id is provided, the source bead becomes the specialist prompt and the tracking bead links back to it. " + "Use context_depth to inject outputs from completed blocking dependencies (depth 1 = immediate blockers, 2 = include their blockers too).",
     inputSchema: useSpecialistSchema,
     async execute(input, onProgress) {
+      let prompt = input.prompt?.trim() ?? "";
+      let variables = input.variables;
+      if (input.bead_id) {
+        const beadsClient = new BeadsClient;
+        const bead = beadsClient.readBead(input.bead_id);
+        if (!bead) {
+          throw new Error(`Unable to read bead '${input.bead_id}' via bd show --json`);
+        }
+        const beadContext = buildBeadContext(bead);
+        prompt = beadContext;
+        variables = {
+          ...input.variables ?? {},
+          bead_context: beadContext,
+          bead_id: input.bead_id
+        };
+      }
       return runner.run({
         name: input.name,
-        prompt: input.prompt,
-        variables: input.variables,
+        prompt,
+        variables,
         backendOverride: input.backend_override,
-        autonomyLevel: input.autonomy_level
+        autonomyLevel: input.autonomy_level,
+        inputBeadId: input.bead_id
       }, onProgress);
     }
   };
@@ -27419,17 +28761,17 @@ function createSpecialistStatusTool(loader, circuitBreaker) {
     async execute(_) {
       const list = await loader.list();
       const stalenessResults = await Promise.all(list.map((s) => checkStaleness(s)));
-      const { existsSync: existsSync2, readdirSync, readFileSync } = await import("node:fs");
-      const { join: join2 } = await import("node:path");
-      const jobsDir = join2(process.cwd(), ".specialists", "jobs");
+      const { existsSync: existsSync4, readdirSync, readFileSync: readFileSync2 } = await import("node:fs");
+      const { join: join3 } = await import("node:path");
+      const jobsDir = join3(process.cwd(), ".specialists", "jobs");
       const jobs = [];
-      if (existsSync2(jobsDir)) {
+      if (existsSync4(jobsDir)) {
         for (const entry of readdirSync(jobsDir)) {
-          const statusPath = join2(jobsDir, entry, "status.json");
-          if (!existsSync2(statusPath))
+          const statusPath = join3(jobsDir, entry, "status.json");
+          if (!existsSync4(statusPath))
             continue;
           try {
-            jobs.push(JSON.parse(readFileSync(statusPath, "utf-8")));
+            jobs.push(JSON.parse(readFileSync2(statusPath, "utf-8")));
           } catch {}
         }
         jobs.sort((a, b) => b.started_at_ms - a.started_at_ms);
@@ -27508,6 +28850,74 @@ class JobRegistry {
     }
     job.killFn = killFn;
   }
+  setSteerFn(id, steerFn) {
+    const job = this.jobs.get(id);
+    if (!job)
+      return;
+    job.steerFn = steerFn;
+  }
+  setResumeFn(id, resumeFn, closeFn) {
+    const job = this.jobs.get(id);
+    if (!job)
+      return;
+    job.resumeFn = resumeFn;
+    job.closeFn = closeFn;
+    job.status = "waiting";
+    job.currentEvent = "waiting";
+  }
+  async followUp(id, message) {
+    const job = this.jobs.get(id);
+    if (!job)
+      return { ok: false, error: `Job not found: ${id}` };
+    if (job.status !== "waiting")
+      return { ok: false, error: `Job is not waiting (status: ${job.status})` };
+    if (!job.resumeFn)
+      return { ok: false, error: "Job has no resume function" };
+    job.status = "running";
+    job.currentEvent = "starting";
+    try {
+      const output = await job.resumeFn(message);
+      job.outputBuffer = output;
+      job.status = "waiting";
+      job.currentEvent = "waiting";
+      return { ok: true, output };
+    } catch (err) {
+      job.status = "error";
+      job.error = err?.message ?? String(err);
+      return { ok: false, error: job.error };
+    }
+  }
+  async closeSession(id) {
+    const job = this.jobs.get(id);
+    if (!job)
+      return { ok: false, error: `Job not found: ${id}` };
+    if (job.status !== "waiting")
+      return { ok: false, error: `Job is not in waiting state` };
+    try {
+      await job.closeFn?.();
+      job.status = "done";
+      job.currentEvent = "done";
+      job.endedAtMs = Date.now();
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err) };
+    }
+  }
+  async steer(id, message) {
+    const job = this.jobs.get(id);
+    if (!job)
+      return { ok: false, error: `Job not found: ${id}` };
+    if (job.status !== "running")
+      return { ok: false, error: `Job is not running (status: ${job.status})` };
+    if (!job.steerFn)
+      return { ok: false, error: "Job session not ready for steering yet" };
+    try {
+      await job.steerFn(message);
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err) };
+    }
+  }
   complete(id, result) {
     const job = this.jobs.get(id);
     if (!job || job.status !== "running")
@@ -27632,20 +29042,117 @@ function createStopSpecialistTool(registry2) {
   };
 }
 
+// src/tools/specialist/steer_specialist.tool.ts
+init_zod();
+init_supervisor();
+import { writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join4 } from "node:path";
+var steerSpecialistSchema = exports_external.object({
+  job_id: exports_external.string().describe("Job ID returned by start_specialist or specialists run --background"),
+  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).",
+    inputSchema: steerSpecialistSchema,
+    async execute(input) {
+      const snap = registry2.snapshot(input.job_id);
+      if (snap) {
+        const result = await registry2.steer(input.job_id, input.message);
+        if (result.ok) {
+          return { status: "steered", job_id: input.job_id, message: input.message };
+        }
+        return { status: "error", error: result.error, job_id: input.job_id };
+      }
+      const jobsDir = join4(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 === "done" || status.status === "error") {
+        return { status: "error", error: `Job is already ${status.status}`, job_id: input.job_id };
+      }
+      if (!status.fifo_path) {
+        return { status: "error", error: "Job has no steer pipe (may have been started without FIFO support)", job_id: input.job_id };
+      }
+      try {
+        const payload = JSON.stringify({ type: "steer", message: input.message }) + `
+`;
+        writeFileSync2(status.fifo_path, payload, { flag: "a" });
+        return { status: "steered", job_id: input.job_id, message: input.message };
+      } catch (err) {
+        return { status: "error", error: `Failed to write to steer pipe: ${err?.message}`, job_id: input.job_id };
+      }
+    }
+  };
+}
+
+// src/tools/specialist/follow_up_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({
+  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) {
+  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,
+    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 };
+        }
+        const result = await registry2.followUp(input.job_id, input.message);
+        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 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 };
+      }
+      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 }) + `
+`;
+        writeFileSync3(status.fifo_path, payload, { flag: "a" });
+        return { status: "sent", job_id: input.job_id, message: input.message };
+      } catch (err) {
+        return { status: "error", error: `Failed to write to steer pipe: ${err?.message}`, job_id: input.job_id };
+      }
+    }
+  };
+}
+
 // src/server.ts
 init_zod();
 
 // src/tools/specialist/specialist_init.tool.ts
 init_zod();
-import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
-import { join as join2 } from "node:path";
+import { spawnSync as spawnSync4 } from "node:child_process";
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join6 } from "node:path";
 var specialistInitSchema = objectType({});
 function createSpecialistInitTool(loader, deps) {
   const resolved = deps ?? {
-    bdAvailable: () => spawnSync2("bd", ["--version"], { stdio: "ignore" }).status === 0,
-    beadsExists: () => existsSync2(join2(process.cwd(), ".beads")),
-    bdInit: () => spawnSync2("bd", ["init"], { stdio: "ignore" })
+    bdAvailable: () => spawnSync4("bd", ["--version"], { stdio: "ignore" }).status === 0,
+    beadsExists: () => existsSync5(join6(process.cwd(), ".beads")),
+    bdInit: () => spawnSync4("bd", ["init"], { stdio: "ignore" })
   };
   return {
     name: "specialist_init",
@@ -27679,7 +29186,7 @@ class SpecialistsServer {
     const circuitBreaker = new CircuitBreaker;
     const loader = new SpecialistLoader;
     const hooks = new HookEmitter({
-      tracePath: join3(process.cwd(), ".specialists", "trace.jsonl")
+      tracePath: join7(process.cwd(), ".specialists", "trace.jsonl")
     });
     const beadsClient = new BeadsClient;
     const runner = new SpecialistRunner({ loader, hooks, circuitBreaker, beadsClient });
@@ -27692,6 +29199,8 @@ class SpecialistsServer {
       createStartSpecialistTool(runner, registry2),
       createPollSpecialistTool(registry2),
       createStopSpecialistTool(registry2),
+      createSteerSpecialistTool(registry2),
+      createFollowUpSpecialistTool(registry2),
       createSpecialistInitTool(loader)
     ];
     this.server = new Server({ name: MCP_CONFIG.SERVER_NAME, version: MCP_CONFIG.VERSION }, { capabilities: MCP_CONFIG.CAPABILITIES });
@@ -27707,6 +29216,8 @@ class SpecialistsServer {
       start_specialist: startSpecialistSchema,
       poll_specialist: pollSpecialistSchema,
       stop_specialist: stopSpecialistSchema,
+      steer_specialist: steerSpecialistSchema,
+      follow_up_specialist: followUpSpecialistSchema,
       specialist_init: specialistInitSchema
     };
     this.toolSchemas = schemaMap;
@@ -27779,15 +29290,15 @@ var next = process.argv[3];
 function wantsHelp() {
   return next === "--help" || next === "-h";
 }
-async function run16() {
+async function run18() {
   if (sub === "install") {
     if (wantsHelp()) {
       console.log([
         "",
         "Usage: specialists install",
         "",
-        "Full-stack setup: installs pi, beads, dolt, registers the MCP server,",
-        "and installs session hooks and skills for Claude Code.",
+        "Project setup: checks pi/bd/xt prerequisites, registers the MCP server,",
+        "and installs specialists-specific project hooks.",
         "",
         "No flags — just run it.",
         ""
@@ -27808,18 +29319,24 @@ async function run16() {
         "",
         "Usage: specialists list [options]",
         "",
-        "List available specialists across all scopes.",
+        "List specialists in the current project.",
+        "",
+        "What it shows:",
+        "  - specialist name",
+        "  - model",
+        "  - short description",
         "",
         "Options:",
-        "  --scope <project|user>   Filter by scope",
-        "  --category <name>        Filter by category tag",
-        "  --json                   Output as JSON array",
+        "  --category <name>   Filter by category tag",
+        "  --json              Output as JSON array",
         "",
         "Examples:",
         "  specialists list",
-        "  specialists list --scope project",
         "  specialists list --category analysis",
         "  specialists list --json",
+        "",
+        "Project model:",
+        "  Specialists are project-only. User-scope discovery is deprecated.",
         ""
       ].join(`
 `));
@@ -27849,15 +29366,27 @@ async function run16() {
     if (wantsHelp()) {
       console.log([
         "",
-        "Usage: specialists init",
+        "Usage: specialists init [--force-workflow]",
+        "",
+        "Bootstrap a project for specialists. This is the sole onboarding command.",
+        "",
+        "What it does:",
+        "  • creates specialists/ for project .specialist.yaml files",
+        "  • creates .specialists/ runtime dirs (jobs/, ready/)",
+        "  • adds .specialists/ to .gitignore",
+        "  • injects the managed workflow block into AGENTS.md and CLAUDE.md",
+        "  • registers the Specialists MCP server at project scope",
         "",
-        "Initialize specialists in the current project:",
-        "  • Creates specialists/           — put .specialist.yaml files here",
-        "  • Creates .specialists/          — runtime data (gitignored)",
-        "  • Adds .specialists/ to .gitignore",
-        "  • Scaffolds AGENTS.md            — context injected into Claude sessions",
+        "Options:",
+        "  --force-workflow   Overwrite existing managed workflow blocks",
+        "",
+        "Examples:",
+        "  specialists init",
+        "  specialists init --force-workflow",
         "",
-        "Safe to run on an existing project (skips already-present items).",
+        "Notes:",
+        "  setup and install are deprecated; use specialists init.",
+        "  Safe to run again; existing project state is preserved where possible.",
         ""
       ].join(`
 `));
@@ -27904,24 +29433,31 @@ async function run16() {
         "",
         "Usage: specialists run <name> [options]",
         "",
-        "Run a specialist. Streams output to stdout by default.",
-        "Reads prompt from stdin if --prompt is not provided.",
+        "Run a specialist in foreground or background.",
+        "",
+        "Primary modes:",
+        "  tracked:  specialists run <name> --bead <id>",
+        '  ad-hoc:   specialists run <name> --prompt "..."',
         "",
         "Options:",
-        "  --prompt <text>    Prompt to send to the specialist (required unless piped)",
-        "  --model <model>    Override the model for this run only",
-        "  --background       Run async; prints job ID and exits immediately",
-        "  --no-beads         Skip creating a beads issue for this run",
+        "  --bead <id>          Use an existing bead as the prompt source",
+        "  --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)",
+        "  --background         Start async and return a job id",
+        "  --follow             Run in background and stream output live",
+        "  --model <model>      Override the configured model for this run",
         "",
         "Examples:",
+        "  specialists run bug-hunt --bead unitAI-55d",
+        "  specialists run bug-hunt --bead unitAI-55d --context-depth 2 --background",
+        "  specialists run sync-docs --follow",
         '  specialists run code-review --prompt "Audit src/api.ts"',
-        '  specialists run code-review --prompt "..." --background',
-        "  cat brief.md | specialists run deep-analysis",
-        '  specialists run code-review --model anthropic/claude-opus-4-6 --prompt "..."',
+        "  cat brief.md | specialists run report-generator",
         "",
-        "See also:",
-        "  specialists feed --help   (tail events for a background job)",
-        "  specialists result --help (read background job output)",
+        "Rules:",
+        "  Use --bead for tracked work.",
+        "  Use --prompt for quick ad-hoc work.",
         ""
       ].join(`
 `));
@@ -27936,11 +29472,17 @@ async function run16() {
         "",
         "Usage: specialists status [options]",
         "",
-        "Show system health: pi runtime, beads installation, MCP registration,",
-        "and all active background jobs.",
+        "Show current runtime state.",
+        "",
+        "Sections include:",
+        "  - discovered specialists",
+        "  - pi provider/runtime health",
+        "  - beads availability",
+        "  - MCP registration hints",
+        "  - active background jobs",
         "",
         "Options:",
-        "  --json    Output as JSON",
+        "  --json   Output machine-readable JSON",
         "",
         "Examples:",
         "  specialists status",
@@ -27982,20 +29524,24 @@ async function run16() {
       console.log([
         "",
         "Usage: specialists feed <job-id> [options]",
-        "       specialists feed --job <job-id> [options]",
+        "       specialists feed -f [--forever]",
         "",
-        "Print events emitted by a background job.",
+        "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:",
-        "  --follow, -f    Stay open and stream new events as they arrive",
-        "                  (exits automatically when job completes)",
+        "  -f, --follow   Follow live updates",
+        "  --forever      Keep following in global mode even when all jobs complete",
         "",
         "Examples:",
-        "  specialists feed job_a1b2c3d4",
-        "  specialists feed job_a1b2c3d4 --follow",
-        "  specialists feed --job job_a1b2c3d4 -f",
-        "",
-        "Event types: tool_use · tool_result · text · agent_end · error",
+        "  specialists feed 49adda",
+        "  specialists feed 49adda --follow",
+        "  specialists feed -f",
+        "  specialists feed -f --forever",
         ""
       ].join(`
 `));
@@ -28004,6 +29550,65 @@ async function run16() {
     const { run: handler } = await Promise.resolve().then(() => (init_feed(), exports_feed));
     return handler();
   }
+  if (sub === "steer") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        'Usage: specialists steer <job-id> "<message>"',
+        "",
+        "Send a mid-run steering message to a running background specialist job.",
+        "The agent receives the message after its current tool calls finish,",
+        "before the next LLM call.",
+        "",
+        'Pi RPC steer command: {"type":"steer","message":"..."}',
+        'Response: {"type":"response","command":"steer","success":true}',
+        "",
+        "Examples:",
+        '  specialists steer a1b2c3 "focus only on supervisor.ts"',
+        '  specialists steer a1b2c3 "skip tests, just fix the bug"',
+        "",
+        "Notes:",
+        "  - Only works for jobs started with --background.",
+        "  - Delivery is best-effort: the agent processes it on its next turn.",
+        ""
+      ].join(`
+`));
+      return;
+    }
+    const { run: handler } = await Promise.resolve().then(() => (init_steer(), exports_steer));
+    return handler();
+  }
+  if (sub === "follow-up") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        'Usage: specialists follow-up <job-id> "<message>"',
+        "",
+        "Send a follow-up prompt to a waiting keep-alive specialist session.",
+        "The Pi session retains full conversation history between turns.",
+        "",
+        "Requires: job started with --keep-alive --background.",
+        "",
+        "Examples:",
+        '  specialists follow-up a1b2c3 "Now write the fix for the bug you found"',
+        '  specialists follow-up a1b2c3 "Focus only on the auth module"',
+        "",
+        "Workflow:",
+        "  specialists run bug-hunt --bead <id> --keep-alive --background",
+        "  # → 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",
+        "",
+        "See also: specialists steer (mid-run redirect)",
+        ""
+      ].join(`
+`));
+      return;
+    }
+    const { run: handler } = await Promise.resolve().then(() => (init_follow_up(), exports_follow_up));
+    return handler();
+  }
   if (sub === "stop") {
     if (wantsHelp()) {
       console.log([
@@ -28033,15 +29638,20 @@ async function run16() {
         "",
         "Usage: specialists doctor",
         "",
-        "Health check for your specialists installation:",
-        "  1. pi installed and has at least one active provider",
-        "  2. All 7 Claude Code hooks present and wired in settings.json",
-        "  3. MCP server registered (claude mcp get specialists)",
-        "  4. .specialists/jobs/ and .specialists/ready/ dirs exist",
-        "  5. No zombie jobs (running status but dead PID)",
+        "Diagnose bootstrap and runtime problems.",
+        "",
+        "Checks:",
+        "  1. pi installed and has active providers",
+        "  2. beads installed and .beads/ present",
+        "  3. xtrm-tools availability",
+        "  4. Specialists MCP registration in .mcp.json",
+        "  5. .specialists/ runtime directories",
+        "  6. hook wiring expectations",
+        "  7. zombie job detection",
         "",
-        "Prints fix hints for each failure.",
-        "Auto-creates missing runtime directories.",
+        "Behavior:",
+        "  - prints fix hints for failing checks",
+        "  - auto-creates missing runtime directories when possible",
         "",
         "Examples:",
         "  specialists doctor",
@@ -28094,7 +29704,7 @@ Run 'specialists help' to see available commands.`);
   const server = new SpecialistsServer;
   await server.start();
 }
-run16().catch((error2) => {
+run18().catch((error2) => {
   logger.error(`Fatal error: ${error2}`);
   process.exit(1);
 });