@jaggerxtrm/specialists 3.4.3 → 3.5.0

package/config/hooks/specialists-complete.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// specialists-complete — Claude Code UserPromptSubmit hook
+// specialists-complete — Claude Code UserPromptSubmit/PostToolUse hook
 // Checks .specialists/ready/ for completed background job markers and injects
-// completion banners into Claude's context.
+// completion/failure banners into Claude's context.
 //
 // Installed by: specialists install
 
@@ -32,16 +32,26 @@ for (const jobId of markers) {
   try {
     let specialist = jobId;
     let elapsed = '';
+    let completionStatus = 'done';
+    let errorMessage = '';
 
     if (existsSync(statusPath)) {
       const status = JSON.parse(readFileSync(statusPath, 'utf-8'));
       specialist = status.specialist ?? jobId;
       elapsed = status.elapsed_s !== undefined ? `, ${status.elapsed_s}s` : '';
+      completionStatus = status.status ?? 'done';
+      errorMessage = status.error ? ` — ${status.error}` : '';
     }
 
-    banners.push(
-      `[Specialist '${specialist}' completed (job ${jobId}${elapsed}). Run: specialists result ${jobId}]`
-    );
+    if (completionStatus === 'error') {
+      banners.push(
+        `[Specialist '${specialist}' failed (job ${jobId}${elapsed}${errorMessage}). Run: specialists feed ${jobId} --follow]`
+      );
+    } else {
+      banners.push(
+        `[Specialist '${specialist}' completed (job ${jobId}${elapsed}). Run: specialists result ${jobId}]`
+      );
+    }
 
     // Delete marker so it only fires once
     unlinkSync(markerPath);
@@ -53,7 +63,7 @@ for (const jobId of markers) {
 
 if (banners.length === 0) process.exit(0);
 
-// UserPromptSubmit hooks inject content via JSON
+// UserPromptSubmit/PostToolUse hooks inject content via JSON
 process.stdout.write(JSON.stringify({
   type: 'inject',
   content: banners.join('\n'),

package/config/skills/using-specialists/SKILL.md

@@ -5,10 +5,9 @@ description: >
   ask whether to delegate. Consult before any: code review, security audit, deep bug
   investigation, test generation, multi-file refactor, or architecture analysis. Also
   use for the mechanics of delegation: --bead workflow, --context-depth, background
-  jobs, MCP tool (`use_specialist`), specialists init,
-  or specialists doctor. Don't wait for the user to say "use a specialist" — proactively
+  jobs, and MCP tool (`use_specialist`). Don't wait for the user to say "use a specialist" — proactively
   evaluate whether delegation makes sense.
-version: 3.6
+version: 3.7
 ---
 
 # Specialists Usage
@@ -51,7 +50,6 @@ links results back to the tracker, and creates an audit trail.
 ### CLI commands
 
 ```bash
-specialists init                              # first-time project setup
 specialists list                              # discover available specialists
 specialists run <name> --bead <id>            # foreground run (streams output)
 specialists run <name> --prompt "..."         # ad-hoc (no bead tracking)
@@ -64,7 +62,6 @@ specialists stop <job-id>                     # cancel a job
 specialists edit <name>                       # edit a specialist's YAML config
 specialists status --job <job-id>             # single-job detail view
 specialists clean                             # purge old job directories
-specialists doctor                            # health check
 ```
 
 ### Typical flow
@@ -265,7 +262,6 @@ git diff --stat       # review what changed
 If a specialist stalls or errors, surface it. Don't quietly do the work yourself.
 ```bash
 specialists feed <job-id>          # see what happened
-specialists doctor                 # check for systemic issues
 ```
 
 Options when a specialist fails:
@@ -288,14 +284,14 @@ python3 .agents/skills/sync-docs/scripts/drift_detector.py update-sync <file>
 
 ## MCP Tools (Claude Code)
 
-Available after `specialists init` and session restart.
-
 | Tool | Purpose |
 |------|---------|
 | `use_specialist` | Foreground run; pass `bead_id` for tracked work and get final output directly in conversation context |
 
 MCP is intentionally minimal. Use CLI commands for orchestration, monitoring, steering,
 resume, and cancellation.
+If you encounter legacy `start_specialist`, treat it as deprecated and migrate to
+`specialists run <name> --prompt "..." --background`.
 
 ---
 
@@ -311,17 +307,10 @@ resume, and cancellation.
 
 ---
 
-## Setup and Troubleshooting
-
-```bash
-specialists init        # first-time setup: creates .specialists/, wires AGENTS.md/CLAUDE.md
-specialists doctor      # health check: hooks, MCP, zombie jobs
-specialists edit <name> # edit a specialist's YAML config
-```
+## Troubleshooting
 
 - **"specialist not found"** → `specialists list` (project-scope only)
 - **Job hangs** → `specialists steer <id> "finish up"` or `specialists stop <id>`
-- **MCP tools missing** → `specialists init` then restart Claude Code
 - **YAML skipped** → stderr shows `[specialists] skipping <file>: <reason>`
 - **Stall timeout** → specialist hit 120s inactivity. Check `specialists feed <id>`, then retry or switch specialist.
 - **`--prompt` and `--bead` conflict** → use bead notes: `bd update <id> --notes "INSTRUCTION: ..."` then `--bead` only.

package/dist/index.js

@@ -18531,16 +18531,22 @@ class SpecialistRunner {
       system_prompt_present: !!prompt.system
     });
     let agentsMd = prompt.system ?? "";
-    if (options.inputBeadId) {
+    {
+      const beadInstructions = options.inputBeadId ? `
+- Your task bead is: ${options.inputBeadId}
+- Claim it: \`bd update ${options.inputBeadId} --claim\`
+- Do NOT create new beads or sub-issues — this bead IS your task.
+- Do NOT run \`bd create\` — the orchestrator manages issue tracking.
+- Close when done: \`bd close ${options.inputBeadId} --reason="..."\`` : "";
       agentsMd += `
 
 ---
-## Specialist Run Context
-You are running as a specialist with bead ${options.inputBeadId} as your task.
-- Claim this bead directly: \`bd update ${options.inputBeadId} --claim\`
-- Do NOT create new beads or sub-issues — this bead IS your task.
-- Do NOT run \`bd create\` — the orchestrator manages issue tracking.
-- Close the bead when done: \`bd close ${options.inputBeadId} --reason="..."\`
+## Specialist Run Context (OVERRIDES CLAUDE.md / AGENTS.md)
+You are a specialist agent. The following rules OVERRIDE any conflicting instructions in CLAUDE.md or AGENTS.md:
+- Do NOT run \`specialists init\` or \`sp init\` — these are user-only bootstrap commands that will corrupt the project.
+- Do NOT run \`specialists setup\` or \`specialists install\`.
+- The edit-gate (bd create before editing) does NOT apply inside a specialist run.
+- GitNexus impact warnings (HIGH/CRITICAL risk) are INFORMATIONAL ONLY — do NOT stop or wait for confirmation. Proceed with the fix regardless of risk level. The orchestrator has already approved the work by dispatching you.${beadInstructions}
 ---
 `;
     }
@@ -19150,7 +19156,7 @@ __export(exports_init, {
   run: () => run5
 });
 import { copyFileSync, cpSync, existsSync as existsSync6, mkdirSync, readdirSync as readdirSync2, readFileSync as readFileSync3, renameSync, writeFileSync } from "node:fs";
-import { basename as basename2, join as join6 } from "node:path";
+import { join as join6 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function ok(msg) {
   console.log(`  ${green3("✓")} ${msg}`);
@@ -19297,6 +19303,7 @@ function ensureProjectHookWiring(cwd) {
     }
   }
   addHook("UserPromptSubmit", "node .claude/hooks/specialists-complete.mjs");
+  addHook("PostToolUse", "node .claude/hooks/specialists-complete.mjs");
   addHook("SessionStart", "node .claude/hooks/specialists-session-start.mjs");
   if (changed) {
     saveJson(settingsPath, settings);
@@ -19344,11 +19351,18 @@ function installProjectSkills(cwd) {
     skip(`${totalSkipped} skill location${totalSkipped === 1 ? "" : "s"} already exist (not overwritten)`);
   }
 }
-function createUserDirs(cwd) {
+function createSpecialistsDirs(cwd) {
+  const defaultDir = join6(cwd, ".specialists", "default");
   const userDir = join6(cwd, ".specialists", "user");
-  if (!existsSync6(userDir)) {
-    mkdirSync(userDir, { recursive: true });
-    ok("created .specialists/user/ for custom specialists");
+  let created = 0;
+  for (const dir of [defaultDir, userDir]) {
+    if (!existsSync6(dir)) {
+      mkdirSync(dir, { recursive: true });
+      created++;
+    }
+  }
+  if (created > 0) {
+    ok("created .specialists/default/ and .specialists/user/");
   }
 }
 function createRuntimeDirs(cwd) {
@@ -19418,74 +19432,26 @@ function ensureAgentsMd(cwd) {
     ok("created AGENTS.md with Specialists section");
   }
 }
-function hasPiSessionEnv() {
-  return Boolean(process.env.PI_SESSION_ID || process.env.PI_RPC_SOCKET || process.env.PI_AGENT_SESSION || process.env.PI_CODING_AGENT);
-}
-function readLinuxProcFile(path) {
-  try {
-    return readFileSync3(path, "utf-8");
-  } catch {
-    return null;
-  }
-}
-function getLinuxParentPid(pid) {
-  const status = readLinuxProcFile(`/proc/${pid}/status`);
-  if (!status)
-    return null;
-  const ppidLine = status.split(`
-`).find((line) => line.startsWith("PPid:"));
-  if (!ppidLine)
-    return null;
-  const value = Number(ppidLine.replace("PPid:", "").trim());
-  return Number.isFinite(value) && value > 0 ? value : null;
-}
-function hasPiAncestorProcess(maxDepth = 8) {
-  let pid = process.ppid;
-  let depth = 0;
-  while (pid && depth < maxDepth) {
-    const cmdline = readLinuxProcFile(`/proc/${pid}/cmdline`);
-    if (!cmdline)
-      break;
-    const command = cmdline.replace(/\0/g, " ").trim();
-    const executable = basename2(command.split(" ")[0] ?? "");
-    const isPiExecutable = executable === "pi" || executable === "pi-coding-agent" || executable.startsWith("pi-");
-    if (isPiExecutable || command.includes("@mariozechner/pi-coding-agent")) {
-      return true;
-    }
-    pid = getLinuxParentPid(pid);
-    depth++;
-  }
-  return false;
-}
-function hasExistingDefaultSpecialists(cwd) {
-  const defaultDir = join6(cwd, ".specialists", "default");
-  const legacyNestedDir = join6(defaultDir, "specialists");
-  const hasFlat = existsSync6(defaultDir) && readdirSync2(defaultDir).some((file) => file.endsWith(".specialist.yaml"));
-  if (hasFlat)
-    return true;
-  return existsSync6(legacyNestedDir) && readdirSync2(legacyNestedDir).some((file) => file.endsWith(".specialist.yaml"));
-}
-function shouldSkipDefaultSyncInPiSession(cwd) {
-  if (process.env.SPECIALISTS_INIT_FORCE_DEFAULT_SYNC === "1")
-    return false;
-  if (!hasExistingDefaultSpecialists(cwd))
-    return false;
-  return hasPiSessionEnv() || hasPiAncestorProcess();
-}
-async function run5() {
+async function run5(opts = {}) {
   const cwd = process.cwd();
+  const forceInit = process.env.SPECIALISTS_INIT_FORCE === "1";
+  const inAgentSession = !forceInit && (!process.stdin.isTTY || !!process.env.SPECIALISTS_TMUX_SESSION || !!process.env.SPECIALISTS_JOB_ID || !!process.env.PI_SESSION_ID || !!process.env.PI_RPC_SOCKET);
+  if (inAgentSession) {
+    console.error("specialists init requires an interactive terminal. This is a user-only bootstrap command — do not invoke from scripts or agent sessions.");
+    process.exit(1);
+  }
   console.log(`
 ${bold4("specialists init")}
 `);
-  const skipDefaultSync = shouldSkipDefaultSyncInPiSession(cwd);
-  if (skipDefaultSync) {
-    skip("pi session detected with existing default specialists; skipped .specialists/default sync");
-  } else {
+  const { syncDefaults = false } = opts;
+  if (syncDefaults) {
     migrateLegacySpecialists(cwd, "default");
     copyCanonicalSpecialists(cwd);
+  } else {
+    skip(".specialists/default/ not synced (pass --sync-defaults to write canonical specialists)");
   }
   migrateLegacySpecialists(cwd, "user");
-  createUserDirs(cwd);
+  createSpecialistsDirs(cwd);
   createRuntimeDirs(cwd);
   ensureGitignore(cwd);
   ensureAgentsMd(cwd);
@@ -19504,7 +19470,7 @@ ${bold4("Done!")}
   console.log("");
   console.log(`  ${dim4(".specialists/ structure:")}`);
   console.log(`  .specialists/`);
-  console.log(`  ├── default/           ${dim4("# canonical specialists (from init)")}`);
+  console.log(`  ├── default/           ${dim4("# canonical specialists (from init --sync-defaults)")}`);
   console.log(`  ├── user/              ${dim4("# your custom specialists")}`);
   console.log(`  ├── jobs/              ${dim4("# runtime (gitignored)")}`);
   console.log(`  └── ready/             ${dim4("# runtime (gitignored)")}`);
@@ -19520,7 +19486,7 @@ var init_init = __esm(() => {
   AGENTS_BLOCK = `
 ## Specialists
 
-Call \`specialists init\` once per project, then use CLI commands via Bash.
+Use CLI commands via Bash to run and monitor specialists:
 
 Core specialist commands (CLI-first in pi):
 - \`specialists list\`
@@ -19824,7 +19790,7 @@ __export(exports_config, {
 });
 import { existsSync as existsSync9 } from "node:fs";
 import { readdir as readdir2, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
-import { basename as basename3, join as join9 } from "node:path";
+import { basename as basename2, join as join9 } from "node:path";
 function usage() {
   return [
     "Usage:",
@@ -19933,7 +19899,7 @@ async function getAcrossFiles(files, keyPath) {
     const content = await readFile3(file, "utf-8");
     const doc2 = $parseDocument(content);
     const value = doc2.getIn(keyPath);
-    const name = getSpecialistNameFromPath(basename3(file));
+    const name = getSpecialistNameFromPath(basename2(file));
     console.log(`${yellow7(name)}: ${formatValue(value)}`);
   }
 }
@@ -20201,6 +20167,10 @@ class Supervisor {
   readyDir() {
     return join10(this.opts.jobsDir, "..", "ready");
   }
+  writeReadyMarker(id) {
+    mkdirSync2(this.readyDir(), { recursive: true });
+    writeFileSync3(join10(this.readyDir(), id), "", "utf-8");
+  }
   readStatus(id) {
     const path = this.statusPath(id);
     if (!existsSync10(path))
@@ -20367,6 +20337,58 @@ class Supervisor {
     let closeFn;
     let fifoReadStream;
     let fifoReadline;
+    let keepAliveSession = false;
+    let latestOutput = "";
+    let keepAliveExitResolved = false;
+    let resolveKeepAliveExit;
+    const keepAliveExitPromise = new Promise((resolve2) => {
+      resolveKeepAliveExit = resolve2;
+    });
+    const finishKeepAlive = (exit) => {
+      if (keepAliveExitResolved)
+        return;
+      keepAliveExitResolved = true;
+      resolveKeepAliveExit?.(exit);
+    };
+    const handleResumeTurn = async (task) => {
+      if (!resumeFn)
+        return;
+      const now = Date.now();
+      setStatus({ status: "running", current_event: "starting", last_event_at_ms: now });
+      lastActivityMs = now;
+      silenceWarnEmitted = false;
+      try {
+        const output = await resumeFn(task);
+        latestOutput = output;
+        mkdirSync2(this.jobDir(id), { recursive: true });
+        writeFileSync3(this.resultPath(id), output, "utf-8");
+        const waitingAt = Date.now();
+        setStatus({
+          status: "waiting",
+          current_event: "waiting",
+          elapsed_s: Math.round((waitingAt - startedAtMs) / 1000),
+          last_event_at_ms: waitingAt
+        });
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        setStatus({ status: "error", error: error2.message });
+        finishKeepAlive({ kind: "fatal", error: error2 });
+      }
+    };
+    const closeKeepAliveSession = async () => {
+      if (!closeFn) {
+        finishKeepAlive({ kind: "closed" });
+        return;
+      }
+      try {
+        await closeFn();
+        finishKeepAlive({ kind: "closed" });
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        setStatus({ status: "error", error: error2.message });
+        finishKeepAlive({ kind: "fatal", error: error2 });
+      }
+    };
     const thresholds = {
       ...STALL_DETECTION_DEFAULTS,
       ...this.opts.stallDetection
@@ -20412,7 +20434,13 @@ class Supervisor {
         }
       }
     }, 1e4);
-    const sigtermHandler = () => killFn?.();
+    const sigtermHandler = () => {
+      if (keepAliveSession) {
+        closeKeepAliveSession();
+        return;
+      }
+      killFn?.();
+    };
     process.once("SIGTERM", sigtermHandler);
     try {
       const result = await runner.run(runOptions, (delta) => {
@@ -20464,48 +20492,21 @@ class Supervisor {
             if (parsed?.type === "steer" && typeof parsed.message === "string") {
               steerFn?.(parsed.message).catch(() => {});
             } else if (parsed?.type === "resume" && typeof parsed.task === "string") {
-              if (resumeFn) {
-                setStatus({ status: "running", current_event: "starting" });
-                resumeFn(parsed.task).then((output) => {
-                  mkdirSync2(this.jobDir(id), { recursive: true });
-                  writeFileSync3(this.resultPath(id), output, "utf-8");
-                  setStatus({
-                    status: "waiting",
-                    current_event: "waiting",
-                    elapsed_s: Math.round((Date.now() - startedAtMs) / 1000),
-                    last_event_at_ms: Date.now()
-                  });
-                }).catch((err) => {
-                  setStatus({ status: "error", error: err?.message ?? String(err) });
-                });
-              }
+              handleResumeTurn(parsed.task);
             } else if (parsed?.type === "prompt" && typeof parsed.message === "string") {
               console.error('[specialists] DEPRECATED: FIFO message {type:"prompt"} is deprecated. Use {type:"resume", task:"..."} instead.');
-              if (resumeFn) {
-                setStatus({ status: "running", current_event: "starting" });
-                resumeFn(parsed.message).then((output) => {
-                  mkdirSync2(this.jobDir(id), { recursive: true });
-                  writeFileSync3(this.resultPath(id), output, "utf-8");
-                  setStatus({
-                    status: "waiting",
-                    current_event: "waiting",
-                    elapsed_s: Math.round((Date.now() - startedAtMs) / 1000),
-                    last_event_at_ms: Date.now()
-                  });
-                }).catch((err) => {
-                  setStatus({ status: "error", error: err?.message ?? String(err) });
-                });
-              }
+              handleResumeTurn(parsed.message);
             } else if (parsed?.type === "close") {
-              closeFn?.().catch(() => {});
+              closeKeepAliveSession();
             }
           } catch {}
         });
         fifoReadline.on("error", () => {});
       }, (rFn, cFn) => {
+        keepAliveSession = true;
         resumeFn = rFn;
         closeFn = cFn;
-        setStatus({ status: "waiting", current_event: "waiting" });
+        setStatus({ status: "waiting", current_event: "waiting", last_event_at_ms: Date.now() });
       }, (tool, args, toolCallId) => {
         currentTool = tool;
         currentToolArgs = args;
@@ -20531,43 +20532,62 @@ class Supervisor {
         toolStartMs = undefined;
         toolDurationWarnEmitted = false;
       });
-      const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
+      latestOutput = result.output;
       mkdirSync2(this.jobDir(id), { recursive: true });
-      writeFileSync3(this.resultPath(id), result.output, "utf-8");
+      writeFileSync3(this.resultPath(id), latestOutput, "utf-8");
+      if (keepAliveSession) {
+        setStatus({
+          status: "waiting",
+          current_event: "waiting",
+          elapsed_s: Math.round((Date.now() - startedAtMs) / 1000),
+          last_event_at_ms: Date.now(),
+          model: result.model,
+          backend: result.backend,
+          bead_id: result.beadId
+        });
+        const keepAliveExit = await keepAliveExitPromise;
+        if (keepAliveExit.kind === "fatal") {
+          throw keepAliveExit.error;
+        }
+      }
+      const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
+      const finalResult = {
+        ...result,
+        output: latestOutput
+      };
       const inputBeadId = runOptions.inputBeadId;
-      const ownsBead = Boolean(result.beadId && !inputBeadId);
+      const ownsBead = Boolean(finalResult.beadId && !inputBeadId);
       const shouldWriteExternalBeadNotes = runOptions.beadsWriteNotes ?? true;
-      const shouldAppendReadOnlyResultToInputBead = Boolean(inputBeadId && result.permissionRequired === "READ_ONLY" && this.opts.beadsClient);
-      if (ownsBead && result.beadId) {
-        this.opts.beadsClient?.updateBeadNotes(result.beadId, formatBeadNotes(result));
+      const shouldAppendReadOnlyResultToInputBead = Boolean(inputBeadId && finalResult.permissionRequired === "READ_ONLY" && this.opts.beadsClient);
+      if (ownsBead && finalResult.beadId) {
+        this.opts.beadsClient?.updateBeadNotes(finalResult.beadId, formatBeadNotes(finalResult));
       } else if (shouldWriteExternalBeadNotes) {
         if (shouldAppendReadOnlyResultToInputBead && inputBeadId) {
-          this.opts.beadsClient?.updateBeadNotes(inputBeadId, formatBeadNotes(result));
-        } else if (result.beadId) {
-          this.opts.beadsClient?.updateBeadNotes(result.beadId, formatBeadNotes(result));
+          this.opts.beadsClient?.updateBeadNotes(inputBeadId, formatBeadNotes(finalResult));
+        } else if (finalResult.beadId) {
+          this.opts.beadsClient?.updateBeadNotes(finalResult.beadId, formatBeadNotes(finalResult));
         }
       }
-      if (result.beadId) {
+      if (finalResult.beadId) {
         if (!inputBeadId) {
-          this.opts.beadsClient?.closeBead(result.beadId, "COMPLETE", result.durationMs, result.model);
+          this.opts.beadsClient?.closeBead(finalResult.beadId, "COMPLETE", finalResult.durationMs, finalResult.model);
         }
       }
       setStatus({
         status: "done",
         elapsed_s: elapsed,
         last_event_at_ms: Date.now(),
-        model: result.model,
-        backend: result.backend,
-        bead_id: result.beadId
+        model: finalResult.model,
+        backend: finalResult.backend,
+        bead_id: finalResult.beadId
       });
       appendTimelineEvent(createRunCompleteEvent("COMPLETE", elapsed, {
-        model: result.model,
-        backend: result.backend,
-        bead_id: result.beadId,
-        output: result.output
+        model: finalResult.model,
+        backend: finalResult.backend,
+        bead_id: finalResult.beadId,
+        output: finalResult.output
       }));
-      mkdirSync2(this.readyDir(), { recursive: true });
-      writeFileSync3(join10(this.readyDir(), id), "", "utf-8");
+      this.writeReadyMarker(id);
       return id;
     } catch (err) {
       const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
@@ -20580,6 +20600,7 @@ class Supervisor {
       appendTimelineEvent(createRunCompleteEvent("ERROR", elapsed, {
         error: errorMsg
       }));
+      this.writeReadyMarker(id);
       throw err;
     } finally {
       if (stuckIntervalId !== undefined)
@@ -20794,6 +20815,9 @@ function createTmuxSession(name, cwd, cmd, extraEnv = {}) {
     throw new Error(`Failed to create tmux session "${name}": ${errorOutput}`);
   }
 }
+function killTmuxSession(name) {
+  spawnSync7("tmux", ["kill-session", "-t", name], { encoding: "utf8", stdio: "pipe" });
+}
 var TMUX_SESSION_PREFIX = "sp";
 var init_tmux_utils = () => {};
 
@@ -21628,7 +21652,14 @@ var exports_feed = {};
 __export(exports_feed, {
   run: () => run12
 });
-import { existsSync as existsSync14, readFileSync as readFileSync10 } from "node:fs";
+import {
+  closeSync as closeSync2,
+  existsSync as existsSync14,
+  openSync as openSync2,
+  readFileSync as readFileSync10,
+  readdirSync as readdirSync6,
+  statSync as statSync2
+} from "node:fs";
 import { join as join15 } from "node:path";
 function getHumanEventKey(event) {
   switch (event.type) {
@@ -21692,31 +21723,55 @@ function parseSince(value) {
   }
   return;
 }
-function isTerminalJobStatus(jobsDir, jobId) {
+function readFileFresh(filePath) {
+  try {
+    const fd = openSync2(filePath, "r");
+    try {
+      return readFileSync10(fd, "utf-8");
+    } finally {
+      closeSync2(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+function readStatusJson(jobsDir, jobId) {
   const statusPath = join15(jobsDir, jobId, "status.json");
+  const raw = readFileFresh(statusPath);
+  if (!raw)
+    return null;
   try {
-    const status = JSON.parse(readFileSync10(statusPath, "utf-8"));
-    return status.status === "done" || status.status === "error";
+    return JSON.parse(raw);
   } catch {
-    return false;
+    return null;
   }
 }
-function makeJobMetaReader(jobsDir) {
+function isTerminalJobStatus(jobsDir, jobId) {
+  const status = readStatusJson(jobsDir, jobId);
+  return status?.status === "done" || status?.status === "error";
+}
+function readJobMeta(jobsDir, jobId) {
+  const status = readStatusJson(jobsDir, jobId);
+  if (!status)
+    return { startedAtMs: Date.now() };
+  return {
+    model: typeof status.model === "string" ? status.model : undefined,
+    backend: typeof status.backend === "string" ? status.backend : undefined,
+    beadId: typeof status.bead_id === "string" ? status.bead_id : undefined,
+    startedAtMs: typeof status.started_at_ms === "number" ? status.started_at_ms : Date.now()
+  };
+}
+function makeJobMetaReader(jobsDir, options = {}) {
+  const useCache = options.useCache ?? true;
+  if (!useCache) {
+    return (jobId) => readJobMeta(jobsDir, jobId);
+  }
   const cache = new Map;
   return (jobId) => {
-    if (cache.has(jobId))
-      return cache.get(jobId);
-    const statusPath = join15(jobsDir, jobId, "status.json");
-    let meta = { startedAtMs: Date.now() };
-    try {
-      const status = JSON.parse(readFileSync10(statusPath, "utf-8"));
-      meta = {
-        model: status.model,
-        backend: status.backend,
-        beadId: status.bead_id,
-        startedAtMs: status.started_at_ms ?? Date.now()
-      };
-    } catch {}
+    const cached2 = cache.get(jobId);
+    if (cached2)
+      return cached2;
+    const meta = readJobMeta(jobsDir, jobId);
     cache.set(jobId, meta);
     return meta;
   };
@@ -21725,6 +21780,7 @@ function parseArgs8(argv) {
   let jobId;
   let specialist;
   let since;
+  let from = 0;
   let limit = 100;
   let follow = false;
   let forever = false;
@@ -21742,6 +21798,11 @@ function parseArgs8(argv) {
       since = parseSince(argv[++i]);
       continue;
     }
+    if (argv[i] === "--from" && argv[i + 1]) {
+      const parsedFrom = parseInt(argv[++i], 10);
+      from = Number.isFinite(parsedFrom) && parsedFrom >= 0 ? parsedFrom : 0;
+      continue;
+    }
     if (argv[i] === "--limit" && argv[i + 1]) {
       limit = parseInt(argv[++i], 10);
       continue;
@@ -21761,7 +21822,7 @@ function parseArgs8(argv) {
     if (!jobId && !argv[i].startsWith("--"))
       jobId = argv[i];
   }
-  return { jobId, specialist, since, limit, follow, forever, json };
+  return { jobId, specialist, since, from, limit, follow, forever, json };
 }
 function printSnapshot(merged, options, jobsDir) {
   if (merged.length === 0) {
@@ -21806,36 +21867,106 @@ function printSnapshot(merged, options, jobsDir) {
 function isCompletionEvent(event) {
   return isRunCompleteEvent(event);
 }
+function isEventAtOrAfterCursor(event, from) {
+  if (from <= 0)
+    return true;
+  const seq = event.seq;
+  if (typeof seq !== "number")
+    return true;
+  return seq >= from;
+}
+function filterMergedEventsByCursor(merged, from) {
+  if (from <= 0)
+    return merged;
+  return merged.filter(({ event }) => isEventAtOrAfterCursor(event, from));
+}
+function listMatchingJobIds(jobsDir, options) {
+  if (!existsSync14(jobsDir))
+    return [];
+  const jobIds = [];
+  for (const entry of readdirSync6(jobsDir)) {
+    const jobDir = join15(jobsDir, entry);
+    try {
+      if (!statSync2(jobDir).isDirectory())
+        continue;
+    } catch {
+      continue;
+    }
+    if (options.jobId && entry !== options.jobId)
+      continue;
+    if (options.specialist) {
+      const status = readStatusJson(jobsDir, entry);
+      const specialist = typeof status?.specialist === "string" ? status.specialist : undefined;
+      if (specialist !== options.specialist)
+        continue;
+    }
+    jobIds.push(entry);
+  }
+  return jobIds;
+}
+function readJobEventsFresh(jobsDir, jobId) {
+  const eventsPath = join15(jobsDir, jobId, "events.jsonl");
+  const content = readFileFresh(eventsPath);
+  if (!content)
+    return [];
+  const events = [];
+  for (const line of content.split(`
+`)) {
+    if (!line.trim())
+      continue;
+    const parsed = parseTimelineEvent(line);
+    if (parsed)
+      events.push(parsed);
+  }
+  events.sort((a, b) => a.t - b.t);
+  return events;
+}
+function readFilteredBatchesFresh(jobsDir, options) {
+  const batches = [];
+  for (const jobId of listMatchingJobIds(jobsDir, options)) {
+    const status = readStatusJson(jobsDir, jobId);
+    const specialist = typeof status?.specialist === "string" ? status.specialist : "unknown";
+    const beadId = typeof status?.bead_id === "string" ? status.bead_id : undefined;
+    const events = readJobEventsFresh(jobsDir, jobId);
+    if (events.length === 0)
+      continue;
+    batches.push({ jobId, specialist, beadId, events });
+  }
+  return batches;
+}
 async function followMerged(jobsDir, options) {
   const colorMap = new JobColorMap;
-  const getJobMeta = makeJobMetaReader(jobsDir);
+  const getJobMeta = makeJobMetaReader(jobsDir, { useCache: false });
   const lastSeenT = new Map;
+  const trackedJobs = new Set(listMatchingJobIds(jobsDir, options).filter((jobId) => !isTerminalJobStatus(jobsDir, jobId)));
   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, {
+  const filteredBatches = () => readFilteredBatchesFresh(jobsDir, options);
+  const initial = filterMergedEventsByCursor(queryTimeline(jobsDir, {
     jobId: options.jobId,
     specialist: options.specialist,
     since: options.since,
     limit: options.limit
-  });
+  }), options.from);
   printSnapshot(initial, { ...options, json: options.json }, jobsDir);
   for (const batch of filteredBatches()) {
     if (batch.events.length > 0) {
       const maxT = Math.max(...batch.events.map((event) => event.t));
       lastSeenT.set(batch.jobId, maxT);
     }
-    if (batch.events.some(isCompletionEvent) || isTerminalJobStatus(jobsDir, batch.jobId)) {
+    if (trackedJobs.has(batch.jobId) && batch.events.some(isCompletionEvent)) {
       completedJobs.add(batch.jobId);
     }
   }
-  const initialBatchCount = filteredBatches().length;
-  if (!options.forever && initialBatchCount > 0 && completedJobs.size === initialBatchCount) {
+  if (!options.forever && trackedJobs.size === 0) {
     if (!options.json) {
       process.stderr.write(dim7(`All jobs complete.
 `));
     }
     return;
   }
+  if (!options.forever && trackedJobs.size > 0 && completedJobs.size === trackedJobs.size) {
+    return;
+  }
   if (!options.json) {
     process.stderr.write(dim7(`Following... (Ctrl+C to stop)
 `));
@@ -21845,11 +21976,21 @@ async function followMerged(jobsDir, options) {
   await new Promise((resolve2) => {
     const interval = setInterval(() => {
       const batches = filteredBatches();
+      for (const jobId of listMatchingJobIds(jobsDir, options)) {
+        if (!isTerminalJobStatus(jobsDir, jobId)) {
+          trackedJobs.add(jobId);
+        }
+      }
+      for (const jobId of trackedJobs) {
+        if (isTerminalJobStatus(jobsDir, jobId)) {
+          completedJobs.add(jobId);
+        }
+      }
       const newEvents = [];
       for (const batch of batches) {
         const lastT = lastSeenT.get(batch.jobId) ?? 0;
         for (const event of batch.events) {
-          if (event.t > lastT) {
+          if (event.t > lastT && isEventAtOrAfterCursor(event, options.from)) {
             newEvents.push({
               jobId: batch.jobId,
               specialist: batch.specialist,
@@ -21862,7 +22003,7 @@ async function followMerged(jobsDir, options) {
           const maxT = Math.max(...batch.events.map((e) => e.t));
           lastSeenT.set(batch.jobId, maxT);
         }
-        if (batch.events.some(isCompletionEvent) || isTerminalJobStatus(jobsDir, batch.jobId)) {
+        if (trackedJobs.has(batch.jobId) && (batch.events.some(isCompletionEvent) || isTerminalJobStatus(jobsDir, batch.jobId))) {
           completedJobs.add(batch.jobId);
         }
       }
@@ -21892,7 +22033,7 @@ async function followMerged(jobsDir, options) {
           console.log(formatEventLine(event, { jobId, specialist: specialistDisplay, beadId, colorize }));
         }
       }
-      if (!options.forever && batches.length > 0 && completedJobs.size === batches.length) {
+      if (!options.forever && trackedJobs.size > 0 && completedJobs.size === trackedJobs.size) {
         clearInterval(interval);
         resolve2();
       }
@@ -21906,16 +22047,19 @@ async function run12() {
     console.log(dim7("No jobs directory found."));
     return;
   }
+  if (options.from > 0 && !options.json) {
+    console.log(dim7(`Showing events from seq ${options.from}`));
+  }
   if (options.follow) {
     await followMerged(jobsDir, options);
     return;
   }
-  const merged = queryTimeline(jobsDir, {
+  const merged = filterMergedEventsByCursor(queryTimeline(jobsDir, {
     jobId: options.jobId,
     specialist: options.specialist,
     since: options.since,
     limit: options.limit
-  });
+  }), options.from);
   printSnapshot(merged, options, jobsDir);
 }
 var init_feed = __esm(() => {
@@ -22159,10 +22303,10 @@ __export(exports_clean, {
 });
 import {
   existsSync as existsSync16,
-  readdirSync as readdirSync6,
+  readdirSync as readdirSync7,
   readFileSync as readFileSync12,
   rmSync as rmSync2,
-  statSync as statSync2
+  statSync as statSync3
 } from "node:fs";
 import { join as join19 } from "node:path";
 function parseTtlDaysFromEnvironment() {
@@ -22218,10 +22362,10 @@ function parseOptions(argv) {
 }
 function readDirectorySizeBytes(directoryPath) {
   let totalBytes = 0;
-  const entries = readdirSync6(directoryPath, { withFileTypes: true });
+  const entries = readdirSync7(directoryPath, { withFileTypes: true });
   for (const entry of entries) {
     const entryPath = join19(directoryPath, entry.name);
-    const stats = statSync2(entryPath);
+    const stats = statSync3(entryPath);
     if (stats.isDirectory()) {
       totalBytes += readDirectorySizeBytes(entryPath);
       continue;
@@ -22245,7 +22389,7 @@ function readCompletedJobDirectory(baseDirectory, entry) {
   }
   if (!COMPLETED_STATUSES.has(statusData.status))
     return null;
-  const directoryStats = statSync2(directoryPath);
+  const directoryStats = statSync3(directoryPath);
   return {
     id: entry.name,
     directoryPath,
@@ -22255,7 +22399,7 @@ function readCompletedJobDirectory(baseDirectory, entry) {
   };
 }
 function collectCompletedJobDirectories(jobsDirectoryPath) {
-  const entries = readdirSync6(jobsDirectoryPath, { withFileTypes: true });
+  const entries = readdirSync7(jobsDirectoryPath, { withFileTypes: true });
   const completedJobs = [];
   for (const entry of entries) {
     const completedJob = readCompletedJobDirectory(jobsDirectoryPath, entry);
@@ -22372,14 +22516,25 @@ async function run18() {
 `);
     process.exit(1);
   }
+  const tmuxSession = status.tmux_session;
   try {
     process.kill(status.pid, "SIGTERM");
     process.stdout.write(`${green11("✓")} Sent SIGTERM to PID ${status.pid} (job ${jobId})
 `);
+    if (tmuxSession) {
+      killTmuxSession(tmuxSession);
+      process.stdout.write(`${dim10(`  tmux session ${tmuxSession} killed`)}
+`);
+    }
   } catch (err) {
     if (err.code === "ESRCH") {
       process.stderr.write(`${red6(`Process ${status.pid} not found.`)} Job may have already completed.
 `);
+      if (tmuxSession) {
+        killTmuxSession(tmuxSession);
+        process.stdout.write(`${dim10(`  tmux session ${tmuxSession} killed`)}
+`);
+      }
     } else {
       process.stderr.write(`${red6("Error:")} ${err.message}
 `);
@@ -22390,6 +22545,7 @@ async function run18() {
 var green11 = (s) => `\x1B[32m${s}\x1B[0m`, red6 = (s) => `\x1B[31m${s}\x1B[0m`, dim10 = (s) => `\x1B[2m${s}\x1B[0m`;
 var init_stop = __esm(() => {
   init_supervisor();
+  init_tmux_utils();
 });
 
 // src/cli/attach.ts
@@ -22678,7 +22834,7 @@ __export(exports_doctor, {
   run: () => run21
 });
 import { spawnSync as spawnSync10 } from "node:child_process";
-import { existsSync as existsSync17, mkdirSync as mkdirSync3, readFileSync as readFileSync14, readdirSync as readdirSync7 } from "node:fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync3, readFileSync as readFileSync14, readdirSync as readdirSync8 } from "node:fs";
 import { join as join22 } from "node:path";
 function ok3(msg) {
   console.log(`  ${green13("✓")} ${msg}`);
@@ -22850,7 +23006,7 @@ function checkZombieJobs() {
   }
   let entries;
   try {
-    entries = readdirSync7(jobsDir);
+    entries = readdirSync8(jobsDir);
   } catch {
     entries = [];
   }
@@ -30577,34 +30733,39 @@ async function run24() {
     if (wantsHelp()) {
       console.log([
         "",
-        "Usage: specialists init [--force-workflow]",
+        "Usage: specialists init [--sync-defaults]",
         "",
         "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",
+        "What it does (always safe, idempotent):",
+        "  • creates .specialists/user/ for custom specialists",
+        "  • creates .specialists/jobs/ and .specialists/ready/ runtime dirs",
+        "  • adds runtime dirs to .gitignore",
+        "  • injects the Specialists section into AGENTS.md",
+        "  • registers the Specialists MCP server at project scope (.mcp.json)",
+        "  • installs hooks to .claude/hooks/ and wires .claude/settings.json",
+        "  • installs skills to .claude/skills/ and .pi/skills/",
         "",
         "Options:",
-        "  --force-workflow   Overwrite existing managed workflow blocks",
+        "  --sync-defaults    Also copy canonical specialists to .specialists/default/.",
+        "                     Human-only: rewrites default specialist YAML files.",
         "",
         "Examples:",
-        "  specialists init",
-        "  specialists init --force-workflow",
+        "  specialists init                 # safe for agents to call",
+        "  specialists init --sync-defaults # human-only: sync canonical specialists",
         "",
         "Notes:",
         "  setup and install are deprecated; use specialists init.",
-        "  Safe to run again; existing project state is preserved where possible.",
+        "  MCP missing → specialists init (safe for anyone to call).",
+        "  Specialists missing → specialists init --sync-defaults (human-only).",
         ""
       ].join(`
 `));
       return;
     }
+    const syncDefaults = process.argv.includes("--sync-defaults");
     const { run: handler } = await Promise.resolve().then(() => (init_init(), exports_init));
-    return handler();
+    return handler({ syncDefaults });
   }
   if (sub === "validate") {
     if (wantsHelp()) {
@@ -30812,11 +30973,13 @@ async function run24() {
         "  specialists feed -f              Follow all jobs globally",
         "",
         "Options:",
+        "  --from <n>     Show only events with seq >= <n>",
         "  -f, --follow   Follow live updates",
         "  --forever      Keep following in global mode even when all jobs complete",
         "",
         "Examples:",
         "  specialists feed 49adda",
+        "  specialists feed 49adda --from 15",
         "  specialists feed 49adda --follow",
         "  specialists feed -f",
         "  specialists feed -f --forever",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "3.4.3",
+  "version": "3.5.0",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "type": "module",

package/config/hooks/specialists-session-start.mjs

@@ -1,120 +0,0 @@
-#!/usr/bin/env node
-// specialists-session-start — Claude Code SessionStart hook
-// Injects specialists context at the start of every session:
-//   • using-specialists skill (behavioral delegation guide)
-//   • Active background jobs (if any)
-//   • Available specialists list
-//   • Key CLI commands reminder
-//
-// Installed by: specialists init
-// Hook type: SessionStart
-
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-
-const cwd     = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-const jobsDir = join(cwd, '.specialists', 'jobs');
-const lines   = [];
-
-// ── 0. using-specialists skill ─────────────────────────────────────────────
-// Inject the behavioral delegation guide so Claude knows when and how to
-// use specialists without waiting for the user to ask.
-const skillPath = join(cwd, '.specialists', 'default', 'skills', 'using-specialists', 'SKILL.md');
-if (existsSync(skillPath)) {
-  const raw = readFileSync(skillPath, 'utf-8');
-  // Strip YAML frontmatter (--- ... ---) if present
-  const content = raw.startsWith('---')
-    ? raw.replace(/^---[\s\S]*?---\n?/, '').trimStart()
-    : raw;
-  lines.push(content);
-}
-
-// ── 1. Active background jobs ──────────────────────────────────────────────
-if (existsSync(jobsDir)) {
-  let entries = [];
-  try { entries = readdirSync(jobsDir); } catch { /* ignore */ }
-
-  const activeJobs = [];
-  for (const jobId of entries) {
-    const statusPath = join(jobsDir, jobId, 'status.json');
-    if (!existsSync(statusPath)) continue;
-    try {
-      const s = JSON.parse(readFileSync(statusPath, 'utf-8'));
-      if (s.status === 'running' || s.status === 'starting') {
-        const elapsed = s.elapsed_s !== undefined ? ` (${s.elapsed_s}s)` : '';
-        activeJobs.push(
-          `  • ${s.specialist ?? jobId}  [${s.status}]${elapsed}  →  specialists result ${jobId}`
-        );
-      }
-    } catch { /* malformed status.json */ }
-  }
-
-  if (activeJobs.length > 0) {
-    lines.push('## Specialists — Active Background Jobs');
-    lines.push('');
-    lines.push(...activeJobs);
-    lines.push('');
-    lines.push('Use `specialists feed <job-id> --follow` to stream events, or `specialists result <job-id>` when done.');
-    lines.push('');
-  }
-}
-
-// ── 2. Available specialists (read YAML dirs directly) ────────────────────
-function readSpecialistNames(dir) {
-  if (!existsSync(dir)) return [];
-  try {
-    return readdirSync(dir)
-      .filter(f => f.endsWith('.specialist.yaml'))
-      .map(f => f.replace('.specialist.yaml', ''));
-  } catch {
-    return [];
-  }
-}
-
-const defaultNames = readSpecialistNames(join(cwd, '.specialists', 'default', 'specialists'));
-const userNames    = readSpecialistNames(join(cwd, '.specialists', 'user', 'specialists'));
-
-// User takes precedence on name collision; merge and sort
-const allNames = [...new Set([...userNames, ...defaultNames])].sort();
-
-if (allNames.length > 0) {
-  lines.push('## Specialists — Available');
-  lines.push('');
-  if (defaultNames.length > 0) {
-    lines.push(`default (${defaultNames.length}): ${defaultNames.join(', ')}`);
-  }
-  if (userNames.length > 0) {
-    const extraUser = userNames.filter(n => !defaultNames.includes(n));
-    if (extraUser.length > 0) {
-      lines.push(`user    (${extraUser.length}): ${extraUser.join(', ')}`);
-    }
-  }
-  lines.push('');
-}
-
-// ── 3. Key commands reminder ───────────────────────────────────────────────
-lines.push('## Specialists — Session Quick Reference');
-lines.push('');
-lines.push('```');
-lines.push('specialists list                                   # discover available specialists');
-lines.push('specialists run <name> --prompt "..."              # run foreground (streams output)');
-lines.push('process start "specialists run <name> --prompt "..."" name="sp-<name>" # async via process extension');
-lines.push('specialists run <name> --prompt "..."              # foreground stream');
-lines.push('specialists feed <job-id> --follow                 # tail live events');
-lines.push('specialists result <job-id>                        # read final output');
-lines.push('specialists status                                 # system health');
-lines.push('specialists doctor                                 # troubleshoot issues');
-lines.push('```');
-lines.push('');
-lines.push('MCP tools: specialist_init · use_specialist · start_specialist · feed_specialist · run_parallel');
-
-// ── Output ─────────────────────────────────────────────────────────────────
-if (lines.length === 0) process.exit(0);
-
-process.stdout.write(JSON.stringify({
-  hookSpecificOutput: {
-    hookEventName: 'SessionStart',
-    additionalSystemPrompt: lines.join('\n'),
-  },
-}) + '\n');