@jaggerxtrm/specialists 3.6.0 → 3.6.1

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

@@ -9,7 +9,7 @@ description: >
   workflow, --context-depth, background jobs, MCP tool (`use_specialist`),
   or specialists doctor. Don't wait for the user to say
   "use a specialist" — proactively evaluate whether delegation makes sense.
-version: 4.5
+version: 4.6
 synced_at: zz22-docs
 ---
 
@@ -40,6 +40,7 @@ Specialists are autonomous AI agents that run independently — fresh context, d
 7. **Merge through epics, not manual git.** Use `sp epic merge <epic-id>` for wave-bound chains or `sp merge <chain-root-bead>` for standalone chains. Never use manual `git merge` for specialist work.
 8. **No destructive operations by specialists.** No `rm -rf`, no force pushes, no database drops, no credential rotation, no mass deletes, no history rewrites. Surface destructive requirements to the user.
 9. **Executor does not run tests.** Executor runs lint + tsc only. Tests are the reviewer's and test-runner's responsibility in the chained pipeline.
+10. **Keep specialists alive through the review cycle.** Never `sp stop` an executor or debugger before the reviewer delivers its verdict. The specialist stays in `waiting` so you can `resume` it — to commit changes, apply fixes from reviewer feedback, or continue work. Only stop after final reviewer PASS and confirmed commit.
 
 ---
 
@@ -426,21 +427,27 @@ The review → fix loop is the mechanism for iterative quality improvement withi
 ### Standard loop
 
 ```
-1. Executor claims impl bead, provisions --worktree, implements, closes bead.
-   -> Job: exec-job
+1. Executor provisions --worktree, implements, enters waiting.
+   -> Job: exec-job (KEEP ALIVE — do not stop)
 
 2. Reviewer enters same worktree via --job exec-job.
-   -> Reads task bead from exec-job status.json automatically.
+   -> sp ps shows the chain:
+      feature/unitAI-impl-executor · unitAI-impl
+        ◐ exec-job   executor   waiting
+        └ ◐ rev-job   reviewer   starting
    -> Auto-appends verdict (PASS/PARTIAL/FAIL) to bead notes.
 
-3a. PASS: orchestrator closes parent task bead.
+3a. PASS:
+    -> Resume executor: "Reviewer PASS. Commit your changes."
+    -> Verify commit landed on branch (git log)
+    -> Stop reviewer, then stop executor
+    -> Merge via sp merge
 
 3b. PARTIAL/FAIL:
-    -> Create fix bead as child of impl bead.
-    -> Run executor --bead fix-bead --job exec-job --context-depth 2.
-    -> Fix executor sees: fix-bead + impl (with reviewer verdict) + explore.
-    -> Fix executor closes fix-bead on completion.
-    -> Return to step 2 (reviewer on same job).
+    -> Resume the SAME executor: "Reviewer PARTIAL. Fix: <specific findings>"
+    -> Executor retains full conversation context — no re-dispatch needed
+    -> Executor applies fixes, enters waiting again
+    -> Return to step 2 (new reviewer on same --job)
 
 4. Repeat until PASS.
 ```
@@ -448,33 +455,51 @@ The review → fix loop is the mechanism for iterative quality improvement withi
 ### Commands
 
 ```bash
-# Step 1 — Executor with worktree
+# Step 1 — Executor with worktree (enters waiting after first turn)
 specialists run executor --worktree --bead unitAI-impl --context-depth 2 --background
 # -> Job started: exec-job (e.g. 49adda)
+# DO NOT sp stop — executor stays alive for the entire review cycle
 
-# Step 2 — Reviewer enters same worktree (--prompt required when no --bead)
+# Step 2 — Reviewer enters same worktree
 specialists run reviewer --job 49adda --keep-alive --background --prompt "Review impl changes"
 # -> Job started: rev-job
 specialists result rev-job
-# PARTIAL → go to step 3b
 
-# Step 3b — Create fix bead + run fix executor in same worktree
-bd create --title "Fix: address reviewer findings on impl" --type bug --priority 1
-# -> unitAI-fix1
-bd dep add fix1 impl
-specialists run executor --bead fix1 --job 49adda --context-depth 2 --background
-
-# Re-review
+# Step 3a — PASS: resume executor to commit, then stop both
+specialists resume 49adda "Reviewer PASS. Git add and commit your changes."
+# Wait for commit, verify with: git log feature/unitAI-impl-executor --oneline -1
+specialists stop rev-job
+specialists stop 49adda
+sp merge unitAI-impl --rebuild
+
+# Step 3b — PARTIAL: resume executor with fix instructions (same session, full context)
+specialists resume 49adda "Reviewer PARTIAL. Fix: <paste specific findings here>"
+# Executor applies fixes, enters waiting again
+# Dispatch new reviewer:
 specialists run reviewer --job 49adda --keep-alive --background --prompt "Re-review after fix"
-# PASS → close parent
+# Repeat until PASS
+
+# After final PASS + commit + stop:
 bd close unitAI-task --reason "Reviewer PASS. All findings addressed."
 ```
 
+### Why resume instead of re-dispatch
+
+Resuming the original executor/debugger is **always preferred** over dispatching a new fix executor:
+
+- **Full context**: the specialist remembers what it changed and why — no re-discovery
+- **No new bead needed**: no fix bead creation, no dep wiring overhead
+- **Same worktree**: no `--job` coordination needed, it's already there
+- **Cheaper**: one resumed turn vs a full new specialist session with context injection
+
+Only dispatch a new fix executor when the original specialist is dead (crashed, stopped prematurely, or context exhausted at >80%).
+
 ### Key invariants
-- Reviewer never re-opens the impl bead — it was closed by the executor. The reviewer's verdict lives on the bead notes as appended output.
-- Each fix iteration creates a **new child bead** — never reopen or re-claim the completed impl bead.
-- The fix executor inherits the full context chain: fix-bead + impl (executor output + reviewer findings) + explore, via `--context-depth 2`.
-- Multiple reviewer → fix cycles are expected for complex changes. The worktree is stable across all cycles.
+- **Never stop the executor/debugger before reviewer verdict.** The specialist stays in `waiting` throughout the review cycle. Stopping prematurely kills the resume path and risks uncommitted changes.
+- **Executors do not auto-commit.** After reviewer PASS, you must resume the executor with explicit commit instructions. Verify the commit landed before stopping.
+- Each fix iteration uses `resume` on the same specialist — not a new child bead or new executor.
+- Multiple reviewer → resume → re-review cycles are expected. The worktree and specialist session are stable across all cycles.
+- Only stop after: (1) reviewer PASS, (2) executor committed, (3) commit verified on branch.
 
 ---
 
@@ -648,7 +673,7 @@ Run `specialists list` to see what's available. Match by task type:
 ### Specialist selection notes
 
 - **executor does not run tests** — it runs `lint + tsc` only. Tests belong to the reviewer or test-runner phase.
-- **executor enters `waiting` after first turn** — `interactive: true` is now default. If executor bails early (e.g. GitNexus CRITICAL risk warning), orchestrator can `resume` with "proceed, this is additive" instead of re-dispatching. Always `stop` executor explicitly when work is complete.
+- **executor enters `waiting` after first turn** — `interactive: true` is now default. **Never stop the executor before reviewer verdict.** Keep it alive so you can: (1) resume with fix instructions if reviewer says PARTIAL, (2) resume with "commit your changes" after reviewer PASS. Executors do not auto-commit — you must explicitly resume them to commit. Only `sp stop` after the commit is verified on the branch.
 - **explorer** is READ_ONLY — its output auto-appends to the input bead's notes. No implementation.
 - **reviewer** is best dispatched via `--job <exec-job> --prompt "..."` — it enters the same worktree to see exactly what was written. `--job` alone is not enough; `--prompt` or `--bead` is always required.
 - **debugger** over **explorer** when you need root cause analysis — GitNexus call-chain tracing, ranked hypotheses, evidence-backed remediation.
@@ -775,23 +800,27 @@ specialists steer a1b2c3 "Do NOT audit. Write the actual file to disk now."
 
 | Specialist | Enters `waiting` after | What to send via `resume` |
 |-----------|----------------------|--------------------------|
-| **executor** | First turn completion (may be partial if bailed early) | "proceed, this is additive", "address the risk warning and continue", or "done, close bead" |
+| **executor** | First turn completion (may be partial if bailed early) | "proceed, this is additive", "Reviewer PARTIAL. Fix: <findings>", or "Reviewer PASS. Git add and commit your changes." |
 | **researcher** | Delivering research findings | Follow-up question, new angle, or "done, thanks" |
 | **reviewer** | Delivering verdict (PASS/PARTIAL/FAIL) | Your response, clarification, or "accepted, close out" |
 | **overthinker** | Phase 4 conclusion | Follow-up question, counter-argument, or "done, thanks" |
-| **debugger** | Phase 3 fix attempt or Phase 4 verify result | Follow-up fix, "try different approach", or "done" |
+| **debugger** | Phase 3 fix attempt or Phase 4 verify result | Follow-up fix, "try different approach", "Reviewer PASS. Git add and commit your changes.", or "done" |
 | **sync-docs** | Audit report or targeted update result | "approve", "deny", or specific instructions |
 
 > **Warning:** A job in `waiting` looks identical to a stalled job. **Always check with `sp ps`
 > before killing a keep-alive job.**
 
+> **Critical:** Never stop an executor or debugger before the reviewer delivers its verdict.
+> Stopping prematurely: (1) kills the resume path for fix loops, (2) risks uncommitted changes
+> (executors don't auto-commit), and (3) forces dispatching a new specialist instead of resuming.
+
 ```bash
 # Check before stopping
 specialists ps d4e5f6
 # -> status: waiting  ← healthy, expecting input
 
 specialists resume d4e5f6 "What about backward compatibility?"
-specialists stop d4e5f6   # only when truly done iterating
+specialists stop d4e5f6   # only when truly done iterating — after reviewer PASS + commit verified
 ```
 
 ---

package/dist/index.js

@@ -17792,7 +17792,7 @@ import { createHash } from "crypto";
 import { spawn } from "child_process";
 import { existsSync as existsSync2, mkdirSync, writeFileSync } from "fs";
 import { homedir, tmpdir } from "os";
-import { isAbsolute, resolve, sep, join as join2 } from "path";
+import { isAbsolute, resolve, sep, join as join2, dirname } from "path";
 function mapPermissionToTools(level) {
   switch (level?.toUpperCase()) {
     case "READ_ONLY":
@@ -17807,6 +17807,16 @@ function mapPermissionToTools(level) {
       return;
   }
 }
+function resolveGlobalNodeModulesDir() {
+  const candidates = [
+    process.env.PI_NPM_GLOBAL_DIR,
+    process.env.NPM_CONFIG_PREFIX ? join2(process.env.NPM_CONFIG_PREFIX, "lib", "node_modules") : undefined,
+    process.env.npm_config_prefix ? join2(process.env.npm_config_prefix, "lib", "node_modules") : undefined,
+    process.env.NVM_BIN ? join2(dirname(process.env.NVM_BIN), "lib", "node_modules") : undefined,
+    join2(homedir(), ".nvm/versions/node", process.version, "lib", "node_modules")
+  ].filter((candidate) => Boolean(candidate));
+  return candidates.find((candidate) => existsSync2(candidate));
+}
 function asNumber(value) {
   if (typeof value === "number" && Number.isFinite(value))
     return value;
@@ -18089,13 +18099,15 @@ class PiAgentSession {
     const ssPath = join2(piExtDir, "service-skills");
     if (existsSync2(ssPath))
       args.push("-e", ssPath);
-    const npmGlobalDir = join2(homedir(), ".nvm/versions/node", process.version, "lib/node_modules");
-    const gitnexusPath = join2(npmGlobalDir, "pi-gitnexus");
-    if (existsSync2(gitnexusPath))
-      args.push("-e", gitnexusPath);
-    const serenaPath = join2(npmGlobalDir, "pi-serena-tools");
-    if (existsSync2(serenaPath))
-      args.push("-e", serenaPath);
+    const npmGlobalDir = resolveGlobalNodeModulesDir();
+    if (npmGlobalDir) {
+      const gitnexusPath = join2(npmGlobalDir, "pi-gitnexus");
+      if (existsSync2(gitnexusPath))
+        args.push("-e", gitnexusPath);
+      const serenaPath = join2(npmGlobalDir, "pi-serena-tools");
+      if (existsSync2(serenaPath))
+        args.push("-e", serenaPath);
+    }
     if (this.options.systemPrompt) {
       args.push("--append-system-prompt", this.options.systemPrompt);
     }
@@ -19607,7 +19619,7 @@ var init_runner = __esm(() => {
 
 // src/specialist/hooks.ts
 import { appendFile, mkdir } from "fs/promises";
-import { dirname } from "path";
+import { dirname as dirname2 } from "path";
 
 class HookEmitter {
   tracePath;
@@ -19615,7 +19627,7 @@ class HookEmitter {
   ready;
   constructor(options) {
     this.tracePath = options.tracePath;
-    this.ready = mkdir(dirname(options.tracePath), { recursive: true }).then(() => {});
+    this.ready = mkdir(dirname2(options.tracePath), { recursive: true }).then(() => {});
   }
   async emit(hook, invocationId, specialistName, specialistVersion, payload) {
     await this.ready;
@@ -19669,11 +19681,11 @@ __export(exports_version, {
 });
 import { createRequire } from "module";
 import { fileURLToPath } from "url";
-import { dirname as dirname2, join as join4 } from "path";
+import { dirname as dirname3, join as join4 } from "path";
 import { existsSync as existsSync4 } from "fs";
 async function run2() {
   const req = createRequire(import.meta.url);
-  const here = dirname2(fileURLToPath(import.meta.url));
+  const here = dirname3(fileURLToPath(import.meta.url));
   const bundlePkgPath = join4(here, "..", "package.json");
   const sourcePkgPath = join4(here, "..", "..", "package.json");
   let pkg;
@@ -19691,7 +19703,7 @@ var init_version = () => {};
 
 // src/specialist/job-root.ts
 import { spawnSync as spawnSync3 } from "child_process";
-import { dirname as dirname3, join as join5, resolve as resolve3 } from "path";
+import { dirname as dirname4, join as join5, resolve as resolve3 } from "path";
 function resolveCommonGitRoot(cwd) {
   const result = spawnSync3("git", ["rev-parse", "--git-common-dir"], {
     cwd,
@@ -19703,7 +19715,7 @@ function resolveCommonGitRoot(cwd) {
   const gitCommonDir = result.stdout?.trim();
   if (!gitCommonDir)
     return;
-  return dirname3(resolve3(cwd, gitCommonDir));
+  return dirname4(resolve3(cwd, gitCommonDir));
 }
 function resolveJobsDir(cwd = process.cwd()) {
   const commonRoot = resolveCommonGitRoot(cwd) ?? cwd;
@@ -23548,7 +23560,7 @@ __export(exports_init, {
 });
 import { copyFileSync, cpSync, existsSync as existsSync9, lstatSync, mkdirSync as mkdirSync4, readdirSync as readdirSync3, readFileSync as readFileSync6, readlinkSync, renameSync as renameSync2, symlinkSync, writeFileSync as writeFileSync4 } from "fs";
 import { spawnSync as spawnSync9 } from "child_process";
-import { basename as basename3, dirname as dirname4, join as join10, relative, resolve as resolve4 } from "path";
+import { basename as basename3, dirname as dirname5, join as join10, relative, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function ok(msg) {
   console.log(`  ${green4("\u2713")} ${msg}`);
@@ -23724,7 +23736,7 @@ function installProjectHooks(cwd) {
         skippedLinks++;
         continue;
       }
-      const currentTarget = resolve4(dirname4(claudeHookPath), readlinkSync(claudeHookPath));
+      const currentTarget = resolve4(dirname5(claudeHookPath), readlinkSync(claudeHookPath));
       if (currentTarget !== xtrmDest) {
         skippedLinks++;
         continue;
@@ -23752,10 +23764,20 @@ function ensureProjectHookWiring(cwd) {
     mkdirSync4(settingsDir, { recursive: true });
   }
   const settings = loadJson(settingsPath, {});
+  if (!settings.hooks || typeof settings.hooks !== "object") {
+    settings.hooks = {};
+  }
+  const hooksObj = settings.hooks;
   let changed = false;
+  for (const event of ["UserPromptSubmit", "PostToolUse", "SessionStart"]) {
+    if (Array.isArray(settings[event])) {
+      delete settings[event];
+      changed = true;
+    }
+  }
   function addHook(event, command) {
-    const eventList = settings[event] ?? [];
-    settings[event] = eventList;
+    const eventList = hooksObj[event] ?? [];
+    hooksObj[event] = eventList;
     const alreadyWired = eventList.some((entry) => entry?.hooks?.some?.((h) => h?.command === command));
     if (!alreadyWired) {
       eventList.push({ matcher: "", hooks: [{ type: "command", command }] });
@@ -23774,10 +23796,10 @@ function ensureProjectHookWiring(cwd) {
 }
 function ensureRootSymlink(rootPath, expectedTargetPath) {
   if (!existsSync9(rootPath)) {
-    mkdirSync4(dirname4(rootPath), { recursive: true });
-    const relTarget = relative(dirname4(rootPath), expectedTargetPath);
+    mkdirSync4(dirname5(rootPath), { recursive: true });
+    const relTarget = relative(dirname5(rootPath), expectedTargetPath);
     symlinkSync(relTarget, rootPath);
-    ok(`created ${basename3(dirname4(rootPath))}/${basename3(rootPath)} \u2192 ${relTarget}`);
+    ok(`created ${basename3(dirname5(rootPath))}/${basename3(rootPath)} \u2192 ${relTarget}`);
     return;
   }
   const stats = lstatSync(rootPath);
@@ -23785,7 +23807,7 @@ function ensureRootSymlink(rootPath, expectedTargetPath) {
     throw new Error(`${rootPath} must be a symlink to ${expectedTargetPath}. Aborting.`);
   }
   const linkTarget = readlinkSync(rootPath);
-  const resolvedTarget = resolve4(dirname4(rootPath), linkTarget);
+  const resolvedTarget = resolve4(dirname5(rootPath), linkTarget);
   const resolvedExpected = resolve4(expectedTargetPath);
   if (resolvedTarget !== resolvedExpected) {
     throw new Error(`${rootPath} points to ${linkTarget}, expected ${expectedTargetPath}. Aborting.`);
@@ -23807,7 +23829,7 @@ function ensureActiveSkillSymlink(defaultSkillPath, activeLinkPath) {
   if (!stats.isSymbolicLink()) {
     throw new Error(`${activeLinkPath} already exists and is not a symlink.`);
   }
-  const currentTarget = resolve4(dirname4(activeLinkPath), readlinkSync(activeLinkPath));
+  const currentTarget = resolve4(dirname5(activeLinkPath), readlinkSync(activeLinkPath));
   if (currentTarget !== resolve4(defaultSkillPath)) {
     throw new Error(`${activeLinkPath} points to an unexpected target.`);
   }
@@ -25408,7 +25430,6 @@ async function parseArgs6(argv) {
   let outputMode = "human";
   let contextDepth = 1;
   let worktree = false;
-  let noWorktree = false;
   let reuseJobId;
   let forceJob = false;
   let epicId;
@@ -25465,8 +25486,8 @@ async function parseArgs6(argv) {
       continue;
     }
     if (token === "--no-worktree") {
-      noWorktree = true;
-      continue;
+      console.error("Error: --no-worktree has been removed. " + "Edit-capable specialists now auto-provision worktrees. " + "Use --job <id> to reuse an existing worktree.");
+      process.exit(1);
     }
     if (token === "--job" && argv[i + 1]) {
       reuseJobId = argv[++i];
@@ -25508,8 +25529,8 @@ async function parseArgs6(argv) {
       process.stdin.on("end", () => resolve6(buf.trim()));
     });
   }
-  if (!prompt && !beadId) {
-    console.error("Error: provide --prompt, pipe stdin, or use --bead <id>.");
+  if (!prompt && !beadId && !reuseJobId) {
+    console.error("Error: provide --prompt, pipe stdin, use --bead <id>, or provide --job <id> for bead inference.");
     process.exit(1);
   }
   return {
@@ -25527,7 +25548,6 @@ async function parseArgs6(argv) {
     worktree,
     reuseJobId,
     forceJob,
-    noWorktree,
     epicId
   };
 }
@@ -25578,7 +25598,8 @@ function resolveWorkingDirectory(args, jobsDir, permissionRequired, readStatus)
     return {
       workingDirectory: worktreePath,
       reusedFromJobId: args.reuseJobId,
-      worktreeOwnerJobId
+      worktreeOwnerJobId,
+      inferredBeadId: targetStatus.bead_id
     };
   }
   return {};
@@ -25661,12 +25682,11 @@ async function run11() {
   const requiresWorktree = specialist.specialist.execution.requires_worktree ?? true;
   const perm = permission === "LOW" || permission === "MEDIUM" || permission === "HIGH" ? permission : "READ_ONLY";
   const editCapable = perm === "MEDIUM" || perm === "HIGH";
-  if (editCapable && requiresWorktree && !args.worktree && !args.reuseJobId && !args.noWorktree) {
-    process.stderr.write(`Error: specialist '${args.name}' has permission_required=${perm} and can edit files.
-` + `Edit-capable specialists must run in isolation. Use one of:
-` + `  --worktree      provision an isolated worktree (recommended)
-` + `  --job <id>      reuse an existing job's worktree
-` + `  --no-worktree   bypass this guard (you accept last-writer-wins risk)
+  const shouldAutoProvisionWorktree = editCapable && requiresWorktree && !args.reuseJobId;
+  const useWorktree = args.worktree || shouldAutoProvisionWorktree;
+  if (shouldAutoProvisionWorktree && !args.beadId) {
+    process.stderr.write(`Error: specialist '${args.name}' has permission_required=${perm} and requires worktree isolation.
+` + `Provide --bead <id> for automatic worktree provisioning, or use --job <id> to reuse an existing worktree.
 `);
     process.exit(1);
   }
@@ -25728,12 +25748,47 @@ async function run11() {
   let prompt = args.prompt;
   let variables;
   let epicId;
-  if (args.beadId) {
-    const bead = beadReader.readBead(args.beadId);
+  let effectiveBeadId = args.beadId;
+  const runner = new SpecialistRunner({
+    loader,
+    hooks,
+    circuitBreaker,
+    beadsClient
+  });
+  const beadsWriteNotes = args.noBeadNotes ? false : specialist.specialist.beads_write_notes ?? true;
+  const jobsDir = resolveJobsDir();
+  const statusReader = new Supervisor({
+    runner,
+    runOptions: {
+      name: args.name,
+      prompt
+    },
+    jobsDir
+  });
+  const {
+    workingDirectory,
+    reusedFromJobId,
+    worktreeOwnerJobId,
+    inferredBeadId
+  } = resolveWorkingDirectory({
+    ...args,
+    worktree: useWorktree
+  }, jobsDir, perm, (jobId2) => statusReader.readStatus(jobId2));
+  await statusReader.dispose();
+  if (!effectiveBeadId && inferredBeadId) {
+    effectiveBeadId = inferredBeadId;
+    console.error(`[input bead auto-resolved from job ${args.reuseJobId}: ${inferredBeadId}]`);
+  }
+  if (effectiveBeadId) {
+    const bead = beadReader.readBead(effectiveBeadId);
     if (!bead) {
-      throw new Error(`Unable to read bead '${args.beadId}' via bd show --json`);
+      const inferredFromJob = !args.beadId && inferredBeadId && effectiveBeadId === inferredBeadId;
+      if (inferredFromJob) {
+        throw new Error(`Unable to read inferred bead '${effectiveBeadId}' from --job '${args.reuseJobId}' via bd show --json`);
+      }
+      throw new Error(`Unable to read bead '${effectiveBeadId}' via bd show --json`);
     }
-    const blockers = args.contextDepth > 0 ? beadReader.getCompletedBlockers(args.beadId, args.contextDepth) : [];
+    const blockers = args.contextDepth > 0 ? beadReader.getCompletedBlockers(effectiveBeadId, args.contextDepth) : [];
     if (blockers.length > 0) {
       process.stderr.write(dim9(`
 [context: ${blockers.length} completed dep${blockers.length > 1 ? "s" : ""} injected]
@@ -25743,11 +25798,11 @@ async function run11() {
     prompt = beadContext;
     epicId = args.epicId ?? bead.parent;
     variables = {
+      ...variables ?? {},
       bead_context: beadContext,
-      bead_id: args.beadId
+      bead_id: effectiveBeadId
     };
-  }
-  if (!args.beadId && args.epicId) {
+  } else if (args.epicId) {
     epicId = args.epicId;
   }
   if (args.reuseJobId) {
@@ -25756,28 +25811,10 @@ async function run11() {
       reviewed_job_id: args.reuseJobId
     };
   }
-  const runner = new SpecialistRunner({
-    loader,
-    hooks,
-    circuitBreaker,
-    beadsClient
-  });
-  const beadsWriteNotes = args.noBeadNotes ? false : specialist.specialist.beads_write_notes ?? true;
-  const jobsDir = resolveJobsDir();
-  const statusReader = new Supervisor({
-    runner,
-    runOptions: {
-      name: args.name,
-      prompt
-    },
-    jobsDir
-  });
-  const {
-    workingDirectory,
-    reusedFromJobId,
-    worktreeOwnerJobId
-  } = resolveWorkingDirectory(args, jobsDir, perm, (jobId2) => statusReader.readStatus(jobId2));
-  await statusReader.dispose();
+  if (!prompt && !effectiveBeadId) {
+    console.error("Error: provide --prompt, pipe stdin, use --bead <id>, or provide --job <id> for bead inference.");
+    process.exit(1);
+  }
   let stopTailer;
   const supervisor = new Supervisor({
     runner,
@@ -25786,7 +25823,7 @@ async function run11() {
       prompt,
       variables,
       backendOverride: args.model,
-      inputBeadId: args.beadId,
+      inputBeadId: effectiveBeadId,
       epicId,
       keepAlive: args.keepAlive,
       noKeepAlive: args.noKeepAlive,
@@ -25806,13 +25843,13 @@ async function run11() {
       process.stderr.write(dim9(`[job started: ${id}]
 `));
       if (args.outputMode !== "raw") {
-        stopTailer = startEventTailer(id, jobsDir, args.outputMode, args.name, args.beadId);
+        stopTailer = startEventTailer(id, jobsDir, args.outputMode, args.name, effectiveBeadId);
       }
     }
   });
-  if (args.beadId && workingDirectory) {
+  if (effectiveBeadId && workingDirectory) {
     try {
-      execSync2(`bd kv set "bead-claim:${args.beadId}" "active"`, {
+      execSync2(`bd kv set "bead-claim:${effectiveBeadId}" "active"`, {
         cwd: workingDirectory,
         stdio: "pipe",
         timeout: 5000
@@ -25832,9 +25869,9 @@ ${bold10(`Running ${cyan6(args.name)}`)}
     stopTailer?.();
   }
   stopTailer?.();
-  if (args.beadId && workingDirectory) {
+  if (effectiveBeadId && workingDirectory) {
     try {
-      execSync2(`bd kv clear "bead-claim:${args.beadId}"`, {
+      execSync2(`bd kv clear "bead-claim:${effectiveBeadId}"`, {
         cwd: workingDirectory,
         stdio: "pipe",
         timeout: 5000
@@ -27982,7 +28019,7 @@ ${JSON.stringify(recoveryDigest, null, 2)}`
           }
         }
         const canResumeCoordinator = this.coordinatorResumesInFlight < MAX_IN_FLIGHT_COORDINATOR_RESUMES;
-        const shouldResumeCoordinator = changes.length > 0 && coordinatorStatus?.status === "waiting" && !this.resumePending && canResumeCoordinator && Boolean(this.coordinatorJobId) && Boolean(this.coordinatorController);
+        const shouldResumeCoordinator = changes.length > 0 && coordinatorStatus?.status === "waiting" && !TERMINAL_NODE_STATUSES.has(this.status) && !this.resumePending && canResumeCoordinator && Boolean(this.coordinatorJobId) && Boolean(this.coordinatorController);
         if (changes.length > 0 && !shouldResumeCoordinator) {
           const skipReasons = [];
           if (coordinatorStatus?.status !== "waiting")
@@ -33300,7 +33337,7 @@ __export(exports_doctor, {
 import { createHash as createHash4 } from "crypto";
 import { spawnSync as spawnSync21 } from "child_process";
 import { existsSync as existsSync25, lstatSync as lstatSync2, mkdirSync as mkdirSync6, readdirSync as readdirSync13, readFileSync as readFileSync22, readlinkSync as readlinkSync2, writeFileSync as writeFileSync9 } from "fs";
-import { dirname as dirname5, join as join28, relative as relative2, resolve as resolve7 } from "path";
+import { dirname as dirname6, join as join28, relative as relative2, resolve as resolve7 } from "path";
 function ok3(msg) {
   console.log(`  ${green14("\u2713")} ${msg}`);
 }
@@ -33410,8 +33447,9 @@ function checkHooks() {
     fix("specialists install");
     return false;
   }
-  const userPromptSubmit = settings.UserPromptSubmit ?? [];
-  const sessionStart = settings.SessionStart ?? [];
+  const hooksObj = settings.hooks ?? {};
+  const userPromptSubmit = hooksObj.UserPromptSubmit ?? settings.UserPromptSubmit ?? [];
+  const sessionStart = hooksObj.SessionStart ?? settings.SessionStart ?? [];
   const wiredCommands = new Set([...userPromptSubmit, ...sessionStart].flatMap((entry) => (entry.hooks ?? []).map((hook) => hook.command ?? "")));
   for (const name of HOOK_NAMES) {
     const expectedRelative = `node .specialists/default/hooks/${name}`;
@@ -33474,7 +33512,7 @@ function isSymlinkTo(linkPath, expectedTargetPath) {
     return { ok: false, reason: "not-symlink" };
   try {
     const rawTarget = readlinkSync2(linkPath);
-    const resolvedTarget = resolve7(dirname5(linkPath), rawTarget);
+    const resolvedTarget = resolve7(dirname6(linkPath), rawTarget);
     const resolvedExpected = resolve7(expectedTargetPath);
     if (resolvedTarget !== resolvedExpected) {
       return { ok: false, reason: "wrong-target", target: rawTarget };
@@ -33569,7 +33607,7 @@ function checkSkillDrift() {
   for (const check2 of skillRootChecks) {
     const state = isSymlinkTo(check2.root, check2.expected);
     if (state.ok) {
-      ok3(`${relative2(CWD, check2.root)} -> ${relative2(dirname5(check2.root), check2.expected)}`);
+      ok3(`${relative2(CWD, check2.root)} -> ${relative2(dirname6(check2.root), check2.expected)}`);
       continue;
     }
     rootLinksOk = false;
@@ -41731,7 +41769,7 @@ async function run29() {
         "Primary modes:",
         "  tracked:    specialists run <name> --bead <id>",
         '  ad-hoc:     specialists run <name> --prompt "..."',
-        "  worktree:   specialists run <name> --bead <id> --worktree",
+        "  explicit wt specialists run <name> --bead <id> --worktree",
         "  reuse job:  specialists run <name> --bead <id> --job <prior-job-id>",
         "",
         "Options:",
@@ -41742,7 +41780,7 @@ async function run29() {
         "  --no-bead-notes      Do not append completion notes to an external --bead",
         "  --model <model>      Override the configured model for this run",
         "  --keep-alive         Keep session alive for follow-up prompts",
-        "  --worktree           Provision (or reuse) a bd-managed worktree derived from --bead.",
+        "  --worktree           Explicitly provision (or reuse) a bd-managed worktree derived from --bead.",
         "                       Requires --bead. Mutually exclusive with --job.",
         "  --job <id>           Reuse the workspace of a prior job (must have been started with",
         "                       --worktree). Caller bead context remains authoritative.",
@@ -41758,7 +41796,7 @@ async function run29() {
         "",
         "Rules:",
         "  Use --bead for tracked work.",
-        "  Use --worktree to isolate the run in its own git branch/directory.",
+        "  MEDIUM/HIGH specialists auto-provision a worktree when requires_worktree=true.",
         "  Use --job to reuse a prior worktree without re-provisioning.",
         "  --worktree and --job are mutually exclusive.",
         "  --worktree requires --bead to derive a deterministic branch name.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "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",