@jaggerxtrm/specialists 3.14.1 → 3.15.0

package/dist/index.js

@@ -17571,7 +17571,8 @@ var init_schema = __esm(() => {
     extensions: objectType({
       serena: booleanType().optional(),
       gitnexus: booleanType().optional()
-    }).passthrough().optional()
+    }).passthrough().optional(),
+    expected_output_keys: arrayType(stringType()).optional()
   }).passthrough();
   PromptSchema2 = objectType({
     system: stringType().optional(),
@@ -17801,6 +17802,22 @@ var init_loader = __esm(() => {
   init_canonical_asset_resolver();
 });
 
+// src/specialist/job-file-output.ts
+function normalizeMode(value) {
+  return (value ?? "").trim().toLowerCase();
+}
+function detectJobFileOutputMode(env = process.env) {
+  const normalized = normalizeMode(env.SPECIALISTS_JOB_FILE_OUTPUT);
+  if (normalized === "on" || normalized === "1" || normalized === "true")
+    return "on";
+  if (normalized === "off" || normalized === "0" || normalized === "false")
+    return "off";
+  return "off";
+}
+function isJobFileOutputEnabled(env = process.env) {
+  return detectJobFileOutputMode(env) === "on";
+}
+
 // src/specialist/templateEngine.ts
 function renderTemplate(template, variables) {
   return template.replace(/\$([a-zA-Z_][a-zA-Z0-9_]*)/g, (match, key) => {
@@ -18019,12 +18036,21 @@ import { isAbsolute, resolve, sep, join as join2, dirname } from "path";
 function loadSharedToolCatalogIndex() {
   if (cachedToolCatalogIndex)
     return cachedToolCatalogIndex;
+  const overridePath = resolve(process.cwd(), ".specialists", "catalog", "index.json");
   try {
-    const indexPath = resolve(process.cwd(), ".specialists", "catalog", "index.json");
-    cachedToolCatalogIndex = loadToolCatalogIndex(readFileSync(indexPath, "utf8"));
+    cachedToolCatalogIndex = loadToolCatalogIndex(readFileSync(overridePath, "utf8"));
     return cachedToolCatalogIndex;
   } catch {
-    return;
+    try {
+      const canonicalDir = resolveCanonicalAssetDir("catalog");
+      if (!canonicalDir)
+        return;
+      const canonicalPath = resolve(canonicalDir, "index.json");
+      cachedToolCatalogIndex = loadToolCatalogIndex(readFileSync(canonicalPath, "utf8"));
+      return cachedToolCatalogIndex;
+    } catch {
+      return;
+    }
   }
 }
 function probeExtensionHealth(packageName) {
@@ -18370,6 +18396,10 @@ class PiAgentSession {
       "--no-extensions",
       ...providerArgs,
       "--no-session",
+      "--offline",
+      "--no-context-files",
+      "--no-prompt-templates",
+      "--no-themes",
       ...extraArgs
     ];
     const toolsFlag = resolvePermissionTools({
@@ -18429,7 +18459,8 @@ class PiAgentSession {
     this.proc = spawn("pi", args, {
       stdio: ["pipe", "pipe", "pipe"],
       cwd: sessionCwd,
-      env: worktreeBoundary ? { ...baseEnv, [WORKTREE_BOUNDARY_ENV_KEY]: worktreeBoundary } : baseEnv
+      env: worktreeBoundary ? { ...baseEnv, [WORKTREE_BOUNDARY_ENV_KEY]: worktreeBoundary } : baseEnv,
+      detached: true
     });
     const donePromise = new Promise((resolve2, reject) => {
       this._doneResolve = resolve2;
@@ -18854,14 +18885,17 @@ class PiAgentSession {
     this._clearStallTimer();
     this.proc?.stdin?.end();
     if (this.proc) {
+      const proc = this.proc;
       await new Promise((resolve2) => {
-        this.proc.on("close", () => resolve2());
+        proc.on("close", () => resolve2());
         setTimeout(() => {
-          if (this.proc && !this._killed) {
-            this.proc.kill();
+          if (proc.exitCode === null && proc.pid != null) {
+            try {
+              process.kill(-proc.pid, "SIGKILL");
+            } catch {}
           }
           resolve2();
-        }, 2000);
+        }, 8000);
       });
     }
   }
@@ -18882,8 +18916,17 @@ class PiAgentSession {
       entry.reject(killError);
     }
     this._pendingRequests.clear();
-    this.proc?.kill();
+    const proc = this.proc;
     this.proc = undefined;
+    proc?.kill();
+    const pid = proc?.pid;
+    if (pid != null) {
+      setTimeout(() => {
+        try {
+          process.kill(-pid, "SIGKILL");
+        } catch {}
+      }, 8000).unref();
+    }
     this._doneReject?.(killError);
   }
   getStderr() {
@@ -18919,6 +18962,7 @@ class PiAgentSession {
 var SessionKilledError, StallTimeoutError, TEST_COMMAND_STALL_TIMEOUT_MS = 300000, GITNEXUS_IMPACT_STALL_TIMEOUT_MS = 300000, TEST_COMMAND_PATTERNS, cachedToolCatalogIndex, WRITE_BOUNDARY_TOOL_NAMES, WORKTREE_BOUNDARY_ENV_KEY = "SPECIALISTS_WORKTREE_BOUNDARY";
 var init_session = __esm(() => {
   init_backendMap();
+  init_canonical_asset_resolver();
   init_manifest_resolver();
   init_tool_catalog();
   SessionKilledError = class SessionKilledError extends Error {
@@ -19877,22 +19921,25 @@ class SqliteClient {
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `, [jobId, seq, specialist, beadId ?? null, event.t, event.type, eventJson]);
   }
+  findActiveJob(beadId, specialist) {
+    return this.db.query(`
+      SELECT
+        job_id,
+        status,
+        updated_at_ms,
+        CAST(JSON_EXTRACT(status_json, '$.pid') AS INTEGER) AS pid
+      FROM specialist_jobs
+      WHERE bead_id = ?
+        AND specialist = ?
+        AND status IN ('starting', 'running', 'waiting')
+      ORDER BY updated_at_ms DESC
+      LIMIT 1
+    `).get(beadId, specialist);
+  }
   claimJobStart(status, event) {
     return claimJobStartWithStore({
       transaction: (callback) => this.db.transaction(callback)(),
-      findActiveJob: (beadId, specialist) => this.db.query(`
-          SELECT
-            job_id,
-            status,
-            updated_at_ms,
-            CAST(JSON_EXTRACT(status_json, '$.pid') AS INTEGER) AS pid
-          FROM specialist_jobs
-          WHERE bead_id = ?
-            AND specialist = ?
-            AND status IN ('starting', 'running')
-          ORDER BY updated_at_ms DESC
-          LIMIT 1
-        `).get(beadId, specialist),
+      findActiveJob: (beadId, specialist) => this.findActiveJob(beadId, specialist),
       writeStatusRow: (nextStatus) => this.writeStatusRow(nextStatus),
       writeEventRow: (jobId, specialist, beadId, nextEvent) => this.writeEventRow(jobId, specialist, beadId, nextEvent),
       cancelStaleClaim: (jobId) => {
@@ -20097,6 +20144,21 @@ class SqliteClient {
       this.writeStatusRow(status);
     }, "upsertStatus");
   }
+  markSpecialistJobCancelled(jobId, reason) {
+    withRetry(() => {
+      const transaction = this.db.transaction(() => {
+        const nowMs = Date.now();
+        this.db.run(`
+          UPDATE specialist_jobs
+          SET status = 'cancelled',
+              status_json = JSON_PATCH(status_json, JSON_OBJECT('status', 'cancelled', 'cancelled_reason', ?)),
+              updated_at_ms = ?
+          WHERE job_id = ?
+        `, [reason, nowMs, jobId]);
+      });
+      transaction();
+    }, "markSpecialistJobCancelled");
+  }
   upsertEpicRun(epic) {
     withRetry(() => {
       this.writeEpicRunRow(epic);
@@ -20597,6 +20659,16 @@ class SqliteClient {
       }
     }, "readLatestToolEvent");
   }
+  getLastActivityTimestampMs(jobId) {
+    return withRetry(() => {
+      const row = this.db.query(`
+        SELECT MAX(t) AS last_activity_ms
+        FROM specialist_events
+        WHERE job_id = ? AND type IN ('tool', 'think')
+      `).get(jobId);
+      return typeof row?.last_activity_ms === "number" ? row.last_activity_ms : null;
+    }, "getLastActivityTimestampMs");
+  }
   aggregateJobMetrics(jobId) {
     return withRetry(() => {
       const jobRow = this.db.query(`
@@ -21901,6 +21973,40 @@ function runScript(command, cwd) {
     return { name: scriptName, output: e.stdout ?? e.message ?? "", exitCode: e.status ?? 1 };
   }
 }
+function buildReviewedGitnexusSummary(opts) {
+  const jobId = opts.reusedFromJobId?.trim();
+  if (!jobId)
+    return "";
+  try {
+    const client = createObservabilitySqliteClient(opts.cwd);
+    if (!client)
+      return "";
+    const events = client.readEvents(jobId);
+    let runComplete = null;
+    for (let i = events.length - 1;i >= 0; i -= 1) {
+      const ev = events[i];
+      if (ev?.type === "run_complete") {
+        runComplete = ev;
+        break;
+      }
+    }
+    if (!runComplete?.gitnexus_summary)
+      return "";
+    const gs = runComplete.gitnexus_summary;
+    const files = (gs.files_touched ?? []).slice(0, 20).join(", ") || "(none)";
+    const symbols = (gs.symbols_analyzed ?? []).slice(0, 20).join(", ") || "(none)";
+    const risk = gs.highest_risk ?? "UNKNOWN";
+    const invocations = gs.tool_invocations ?? 0;
+    return `<gitnexus_summary reviewed_job_id="${jobId}">
+  files_touched: ${files}
+  symbols_analyzed: ${symbols}
+  highest_risk: ${risk}
+  tool_invocations: ${invocations}
+</gitnexus_summary>`;
+  } catch {
+    return "";
+  }
+}
 function formatScriptOutput(results) {
   const withOutput = results.filter((r) => r.output.trim());
   if (withOutput.length === 0)
@@ -21972,7 +22078,7 @@ function validateBeforeRun(spec, permissionLevel) {
       }
     } else {
       const binary = run.split(" ")[0];
-      if (!commandExists(binary)) {
+      if (binary && !SHELL_BUILTINS.has(binary) && !commandExists(binary)) {
         errors5.push(`  \u2717 skills.scripts: command not found on PATH: ${binary}`);
       }
     }
@@ -22394,6 +22500,13 @@ ${buildBeadBoundaryInstruction(runCwd, options.worktreeBoundary)}`.trim() : this
       ...options.reusedFromJobId ? { reused_from_job_id: options.reusedFromJobId } : {},
       ...options.worktreeOwnerJobId ? { worktree_owner_job_id: options.worktreeOwnerJobId } : {}
     };
+    const gitnexusSummary = buildReviewedGitnexusSummary({
+      reusedFromJobId: options.reusedFromJobId,
+      cwd: runCwd
+    });
+    if (gitnexusSummary) {
+      lineageVariables.gitnexus_summary = gitnexusSummary;
+    }
     const beadTemplateVariables = {
       prompt: resolvedPrompt,
       bead_id: options.inputBeadId ?? "",
@@ -22806,7 +22919,7 @@ ${outputContractWarnings.map((msg) => `  \u26A0 ${msg}`).join(`
 `)}
 `);
     }
-    if (output_file) {
+    if (output_file && isJobFileOutputEnabled()) {
       await writeFile(output_file, output, "utf-8").catch(() => {});
     }
     await hooks.emit("post_execute", invocationId, metadata.name, metadata.version, {
@@ -22848,13 +22961,42 @@ ${outputContractWarnings.map((msg) => `  \u26A0 ${msg}`).join(`
     return jobId;
   }
 }
-var PERMISSION_GATED_TOOLS, RETRY_BASE_DELAY_MS = 1000, RETRY_MAX_JITTER = 0.2, BASE_OUTPUT_SCHEMA, IMPACT_REPORT_SCHEMA, OUTPUT_TYPE_SCHEMA_EXTENSIONS, OUTPUT_TYPE_GUIDANCE;
+var SHELL_BUILTINS, PERMISSION_GATED_TOOLS, RETRY_BASE_DELAY_MS = 1000, RETRY_MAX_JITTER = 0.2, BASE_OUTPUT_SCHEMA, IMPACT_REPORT_SCHEMA, OUTPUT_TYPE_SCHEMA_EXTENSIONS, OUTPUT_TYPE_GUIDANCE;
 var init_runner = __esm(() => {
   init_session();
   init_circuitBreaker();
   init_mandatory_rules();
+  init_observability_sqlite();
   init_beads();
   init_memory_retrieval();
+  SHELL_BUILTINS = new Set([
+    "if",
+    "then",
+    "else",
+    "elif",
+    "fi",
+    "for",
+    "while",
+    "until",
+    "do",
+    "done",
+    "case",
+    "esac",
+    "select",
+    "in",
+    "function",
+    "return",
+    "break",
+    "continue",
+    ":",
+    ".",
+    "true",
+    "false",
+    "[",
+    "[[",
+    "{",
+    "("
+  ]);
   PERMISSION_GATED_TOOLS = {
     bash: ["LOW", "MEDIUM", "HIGH"],
     edit: ["MEDIUM", "HIGH"],
@@ -23355,6 +23497,7 @@ var RULE_TIERS, SPEC_TIERS;
 var init_list_rules = __esm(() => {
   init_mandatory_rules();
   RULE_TIERS = [
+    { rel: ".specialists/user/mandatory-rules", tier: "user" },
     { rel: ".specialists/mandatory-rules", tier: "overlay" },
     { rel: ".specialists/default/mandatory-rules", tier: "default" },
     { rel: "config/mandatory-rules", tier: "config" }
@@ -23366,22 +23509,6 @@ var init_list_rules = __esm(() => {
   ];
 });
 
-// src/specialist/job-file-output.ts
-function normalizeMode(value) {
-  return (value ?? "").trim().toLowerCase();
-}
-function detectJobFileOutputMode(env = process.env) {
-  const normalized = normalizeMode(env.SPECIALISTS_JOB_FILE_OUTPUT);
-  if (normalized === "on" || normalized === "1" || normalized === "true")
-    return "on";
-  if (normalized === "off" || normalized === "0" || normalized === "false")
-    return "off";
-  return "off";
-}
-function isJobFileOutputEnabled(env = process.env) {
-  return detectJobFileOutputMode(env) === "on";
-}
-
 // src/specialist/timeline-events.ts
 function summarizeToolResult(resultContent) {
   if (!resultContent)
@@ -23746,25 +23873,24 @@ function resolveChainId(status) {
   return;
 }
 function evaluateEpicMergeReadiness(input) {
-  const isEligibleState = input.epicStatus === "merge_ready";
   const blockingChains = input.chainStatuses.filter((chain) => chain.hasRunningJob).map((chain) => chain.chainId);
-  const isReady = isEligibleState && blockingChains.length === 0;
-  if (!isEligibleState) {
+  const isReady = blockingChains.length === 0;
+  if (!isReady) {
     return {
       epicId: input.epicId,
       epicStatus: input.epicStatus,
       isReady,
       blockingChains,
-      summary: `Epic ${input.epicId} is ${input.epicStatus}; expected merge_ready before publication.`
+      summary: `Epic ${input.epicId} is blocked by active chains: ${blockingChains.join(", ")}.`
     };
   }
-  if (blockingChains.length > 0) {
+  if (input.epicStatus === "merged" || input.epicStatus === "abandoned") {
     return {
       epicId: input.epicId,
       epicStatus: input.epicStatus,
       isReady,
       blockingChains,
-      summary: `Epic ${input.epicId} is blocked by active chains: ${blockingChains.join(", ")}.`
+      summary: `Epic ${input.epicId} is ${input.epicStatus}; live chains are terminal.`
     };
   }
   return {
@@ -23772,7 +23898,7 @@ function evaluateEpicMergeReadiness(input) {
     epicStatus: input.epicStatus,
     isReady,
     blockingChains,
-    summary: `Epic ${input.epicId} is merge-ready and all chains are terminal.`
+    summary: `Epic ${input.epicId} is live-ready and all chains are terminal.`
   };
 }
 function appendEpicTransitionAudit(statusJson, entry) {
@@ -23796,9 +23922,6 @@ function appendEpicTransitionAudit(statusJson, entry) {
     transitions: [...previous, entry]
   });
 }
-function summarizeEpicTransition(epicId, from, to) {
-  return `Epic ${epicId}: ${from} -> ${to}`;
-}
 var EPIC_TERMINAL_STATES, VALID_EPIC_TRANSITIONS;
 var init_epic_lifecycle = __esm(() => {
   EPIC_TERMINAL_STATES = ["merged", "failed", "abandoned"];
@@ -23990,79 +24113,55 @@ function evaluatePrepReadiness(prepJobs) {
     blocker_job_ids: [...running, ...failed].map((job) => job.id)
   };
 }
-function toReadinessState(persistedState, prep, chains) {
-  if (persistedState === "merged")
-    return "merged";
-  if (persistedState === "abandoned")
-    return "abandoned";
-  const hasBlockingPrep = prep.running > 0;
-  const hasFailedPrep = prep.failed > 0;
+function deriveEpicReadinessState(prep, chains) {
+  const hasActivePrep = prep.running > 0;
   const hasPendingChain = chains.some((chain) => chain.state === "pending");
   const hasBlockedChain = chains.some((chain) => chain.state === "blocked");
+  const hasFailedPrep = prep.failed > 0;
   const hasFailedChain = chains.some((chain) => chain.state === "failed");
   const allChainsPass = chains.length === 0 || chains.every((chain) => chain.state === "pass");
+  if (hasActivePrep || hasPendingChain)
+    return "resolving";
   if (hasFailedPrep || hasFailedChain)
     return "failed";
-  if (persistedState === "failed" && allChainsPass)
-    return "merge_ready";
-  if (persistedState === "failed")
-    return "failed";
-  if (hasBlockingPrep || hasPendingChain)
-    return persistedState === "resolving" ? "resolving" : "unresolved";
   if (hasBlockedChain)
-    return persistedState === "resolving" ? "resolving" : "blocked";
+    return "blocked";
   if (allChainsPass)
     return "merge_ready";
   return "blocked";
 }
-function toNextState(persistedState, readinessState) {
+function deriveEpicNextState(persistedState, readinessState) {
   if (persistedState === "merged" || persistedState === "abandoned")
     return persistedState;
-  if (readinessState === "failed") {
-    if (persistedState === "merge_ready") {
-      return transitionEpicState("merge_ready", "failed");
-    }
-    if (persistedState === "resolving") {
-      return transitionEpicState("resolving", "failed");
-    }
-    return persistedState;
-  }
-  if (readinessState === "merge_ready") {
-    if (persistedState === "failed")
-      return "merge_ready";
-    if (persistedState === "open")
-      return transitionEpicState("open", "resolving");
-    if (persistedState === "resolving")
-      return transitionEpicState("resolving", "merge_ready");
-    return persistedState;
-  }
-  if (persistedState === "open" && (readinessState === "unresolved" || readinessState === "resolving" || readinessState === "blocked")) {
-    return transitionEpicState("open", "resolving");
-  }
-  if (persistedState === "merge_ready" && (readinessState === "unresolved" || readinessState === "resolving" || readinessState === "blocked")) {
-    return transitionEpicState("merge_ready", "resolving");
-  }
-  return persistedState;
+  if (readinessState === "merge_ready")
+    return "merge_ready";
+  if (readinessState === "failed")
+    return "failed";
+  return "resolving";
 }
-function buildSummaryLine(epicId, readinessState, prep, chains) {
+function buildSummaryLine(epicId, persistedState, readinessState, prep, chains) {
   const chainPass = chains.filter((chain) => chain.state === "pass").length;
   const chainTotal = chains.length;
-  const blockedChains = chains.filter((chain) => chain.state === "blocked" || chain.state === "pending").map((chain) => chain.chain_id);
+  const blockedChains = chains.filter((chain) => chain.state === "blocked" || chain.state === "pending" || chain.state === "failed").map((chain) => chain.chain_id);
+  const failedChains = chains.filter((chain) => chain.state === "failed").map((chain) => chain.chain_id);
   const prepSegment = `prep done=${prep.done}/${prep.total} running=${prep.running} failed=${prep.failed}`;
   const chainSegment = `chains pass=${chainPass}/${chainTotal}`;
-  if (blockedChains.length > 0) {
-    return `Epic ${epicId}: ${readinessState} (${prepSegment}; ${chainSegment}; blocked=${blockedChains.join(", ")})`;
-  }
-  return `Epic ${epicId}: ${readinessState} (${prepSegment}; ${chainSegment})`;
+  const stateSegment = persistedState === readinessState ? readinessState : `${readinessState} (stored=${persistedState})`;
+  const segments = [prepSegment, chainSegment];
+  if (blockedChains.length > 0)
+    segments.push(`blocked=${blockedChains.join(", ")}`);
+  if (failedChains.length > 0)
+    segments.push(`failed=${failedChains.join(", ")}`);
+  return `Epic ${epicId}: ${stateSegment} (${segments.join("; ")})`;
 }
 function evaluateEpicReadinessSummary(input) {
   const prep = evaluatePrepReadiness(input.prepJobs);
   const chains = input.chainInputs.map((chain) => evaluateChainReadiness(chain.chain_id, chain.jobs, chain.chain_root_bead_id));
-  const readinessState = toReadinessState(input.persistedState, prep, chains);
-  const nextState = toNextState(input.persistedState, readinessState);
+  const readinessState = deriveEpicReadinessState(prep, chains);
+  const nextState = deriveEpicNextState(input.persistedState, readinessState);
   const blockers = [
     ...prep.blocker_job_ids.map((jobId) => `prep:${jobId}`),
-    ...chains.filter((chain) => chain.state === "pending" || chain.state === "blocked").map((chain) => `chain:${chain.chain_id}`)
+    ...chains.filter((chain) => chain.state === "pending" || chain.state === "blocked" || chain.state === "failed").map((chain) => `chain:${chain.chain_id}`)
   ];
   return {
     epic_id: input.epicId,
@@ -24073,7 +24172,7 @@ function evaluateEpicReadinessSummary(input) {
     prep,
     chains,
     blockers,
-    summary: buildSummaryLine(input.epicId, readinessState, prep, chains)
+    summary: buildSummaryLine(input.epicId, input.persistedState, readinessState, prep, chains)
   };
 }
 function loadEpicReadinessSummary(sqlite, epicId) {
@@ -24113,7 +24212,7 @@ function loadEpicReadinessSummary(sqlite, epicId) {
 function syncEpicStateFromReadiness(sqlite, summary) {
   const now = Date.now();
   const existing = sqlite.readEpicRun(summary.epic_id);
-  const healedFromFailed = summary.persisted_state === "failed" && summary.readiness_state === "merge_ready";
+  const recoveredFromLegacyFailure = summary.persisted_state === "failed" && summary.readiness_state === "merge_ready";
   const nextRecord = {
     epic_id: summary.epic_id,
     status: summary.next_state,
@@ -24128,21 +24227,20 @@ function syncEpicStateFromReadiness(sqlite, summary) {
       chains: summary.chains,
       summary: summary.summary,
       evaluated_at_ms: now,
-      note: healedFromFailed ? "epic reconciler: healed failed -> merge_ready after chain merge" : undefined
+      note: recoveredFromLegacyFailure ? "derived readiness healed legacy failed row after live chains turned pass" : undefined
     })
   };
-  if (summary.can_transition || healedFromFailed || !existing) {
+  if (summary.can_transition || recoveredFromLegacyFailure || !existing) {
     sqlite.upsertEpicRun(nextRecord);
   }
   return nextRecord;
 }
 var ACTIVE_JOB_STATUSES, TERMINAL_JOB_STATUSES, REVIEWER_VERDICT_REGEX;
 var init_epic_readiness = __esm(() => {
-  init_epic_lifecycle();
   init_process_liveness();
   ACTIVE_JOB_STATUSES = new Set(["starting", "running", "waiting"]);
   TERMINAL_JOB_STATUSES = new Set(["done", "error"]);
-  REVIEWER_VERDICT_REGEX = /Verdict:\s*(PASS|PARTIAL|FAIL)/i;
+  REVIEWER_VERDICT_REGEX = /Verdict:\s*\**\s*(PASS|PARTIAL|FAIL)\s*\**/i;
 });
 
 // src/specialist/chain-identity.ts
@@ -24419,8 +24517,20 @@ function runAutoCommitCheckpoint(options) {
     return { status: "failed", reason: String(error2) };
   }
 }
+function gitnexusHasEmbeddings(cwd) {
+  try {
+    const metaPath = join9(cwd, ".gitnexus", "meta.json");
+    const raw = readFileSync8(metaPath, "utf-8");
+    const meta = JSON.parse(raw);
+    return typeof meta.stats?.embeddings === "number" && meta.stats.embeddings > 0;
+  } catch {
+    return false;
+  }
+}
 function startDetachedGitnexusAnalyze(cwd) {
-  const child = spawn2("npx", ["gitnexus", "analyze"], {
+  const baseArgs = ["gitnexus", "analyze", "--skip-agents-md", "--no-stats"];
+  const args = gitnexusHasEmbeddings(cwd) ? [...baseArgs, "--embeddings"] : baseArgs;
+  const child = spawn2("npx", args, {
     cwd,
     detached: true,
     stdio: "ignore"
@@ -24707,6 +24817,55 @@ class Supervisor {
       return [];
     }
   }
+  listChainJobIds(chainId) {
+    try {
+      if (this.isDisposed) {
+        throw this.createDisposedSqliteError("listChainJobIds");
+      }
+      return this.withSqliteOperation("listChainJobIds", (client) => client.listChainJobIds(chainId)) ?? [];
+    } catch (error2) {
+      console.warn(`[supervisor] SQLite listChainJobIds failed: ${String(error2)}`);
+      return [];
+    }
+  }
+  readResult(id) {
+    try {
+      if (this.isDisposed) {
+        throw this.createDisposedSqliteError("readResult");
+      }
+      const sqliteResult = this.withSqliteOperation("readResult", (client) => client.readResult(id));
+      if (sqliteResult)
+        return sqliteResult;
+    } catch (error2) {
+      if (!(error2 instanceof Error && error2.message.includes("supervisor is disposed"))) {
+        console.warn(`[supervisor] SQLite readResult failed, falling back to file state: ${String(error2)}`);
+      }
+    }
+    const path = this.resultPath(id);
+    if (!existsSync10(path))
+      return null;
+    try {
+      return readFileSync8(path, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+  finalizeWaitingJob(id) {
+    const currentStatus = this.readStatus(id);
+    if (!currentStatus)
+      return null;
+    if (currentStatus.status !== "waiting")
+      return currentStatus;
+    if (currentStatus.fifo_path) {
+      writeFileSync3(currentStatus.fifo_path, JSON.stringify({ type: "close" }) + `
+`, { flag: "a" });
+    }
+    const finalized = this.updateJobStatus(id, "done");
+    if (!finalized)
+      return null;
+    this.aggregateJobMetricsBestEffort(id);
+    return finalized;
+  }
   emitMetaEvent(jobId, model, backend) {
     if (this.isDisposed)
       return;
@@ -25165,8 +25324,24 @@ class Supervisor {
       }));
     };
     const shouldAutoCloseReadOnlyKeepAlive = (output) => isReadOnlySpecialist && TERMINAL_COMPLIANCE_VERDICT_REGEX.test(output);
+    const shouldAutoFinalizeKeepAlive = (output) => PASS_COMPLIANCE_VERDICT_REGEX.test(output);
     const shouldWriteExternalBeadNotes = runOptions.beadsWriteNotes ?? true;
     let skipFinalKeepAliveInputBeadAppend = false;
+    let lastGitnexusAnalyzedSha;
+    const triggerGitnexusAnalyzeIfNeeded = (sha, source) => {
+      if (!isGitnexusAnalyzeRequired(runOptions.permissionRequired))
+        return;
+      if (sha && lastGitnexusAnalyzedSha === sha)
+        return;
+      try {
+        startDetachedGitnexusAnalyze(runOptions.workingDirectory ?? process.cwd());
+        appendTimelineEvent(createMetaEvent("gitnexus_analyze_started", source));
+        if (sha)
+          lastGitnexusAnalyzedSha = sha;
+      } catch (err) {
+        appendTimelineEvent(createMetaEvent("gitnexus_analyze_start_failed", `${source}: ${String(err?.message ?? err)}`));
+      }
+    };
     const appendResultToInputBead = (params) => {
       const inputBeadId = runOptions.inputBeadId;
       const shouldAppendResultToInputBead = Boolean(shouldWriteExternalBeadNotes && inputBeadId && this.opts.beadsClient);
@@ -25189,12 +25364,14 @@ class Supervisor {
       const appendError = `[bead-append-failed] ${appendResult.error ?? "Unknown error"}`;
       appendTimelineEvent(createMetaEvent("bead_append_failed", appendError));
       setStatus({ current_event: "bead_append_failed", last_event_at_ms: Date.now() });
-      try {
-        appendFileSync(this.resultPath(id), `
+      if (this.isJobFileOutputEnabled) {
+        try {
+          appendFileSync(this.resultPath(id), `
 
 ${appendError}
 `, "utf-8");
-      } catch {}
+        } catch {}
+      }
       return false;
     };
     const applyAutoCommitCheckpoint = (target, autoCommitPolicy2) => {
@@ -25225,6 +25402,7 @@ ${appendError}
         commit_sha: autoCommitResult.sha,
         committed_files: autoCommitResult.files
       }));
+      triggerGitnexusAnalyzeIfNeeded(autoCommitResult.sha, "checkpoint");
     };
     const handleResumeTurn = async (task) => {
       if (!resumeFn)
@@ -25236,8 +25414,10 @@ ${appendError}
       try {
         const output = await resumeFn(task);
         latestOutput = output;
-        mkdirSync4(this.jobDir(id), { recursive: true });
-        writeFileSync3(this.resultPath(id), output, "utf-8");
+        if (this.isJobFileOutputEnabled) {
+          mkdirSync4(this.jobDir(id), { recursive: true });
+          writeFileSync3(this.resultPath(id), output, "utf-8");
+        }
         try {
           this.withSqliteOperation("upsertResult:resume_turn", (client) => client.upsertResult(id, output));
         } catch (error2) {
@@ -25249,7 +25429,9 @@ ${appendError}
           beadId: statusSnapshot.bead_id,
           output
         });
-        const isWaitingTurn = !shouldAutoCloseReadOnlyKeepAlive(output);
+        const passFinalize = shouldAutoFinalizeKeepAlive(output);
+        const readOnlyClose = shouldAutoCloseReadOnlyKeepAlive(output);
+        const isWaitingTurn = !readOnlyClose && !passFinalize;
         applyAutoCommitCheckpoint(isWaitingTurn ? "waiting" : "terminal", autoCommitPolicy);
         appendResultToInputBead({
           output,
@@ -25676,6 +25858,8 @@ ${appendError}
       if (keepAliveSession) {
         if (shouldAutoCloseReadOnlyKeepAlive(finalResult.output)) {
           await closeKeepAliveSession();
+        } else if (shouldAutoFinalizeKeepAlive(finalResult.output)) {
+          await closeKeepAliveSession();
         } else {
           appendResultToInputBead({
             output: finalResult.output,
@@ -25791,24 +25975,7 @@ ${appendError}
         throw new Error("[supervisor] SQLite upsertStatusWithEventAndResult failed: database client unavailable");
       }
       this.aggregateJobMetricsBestEffort(id);
-      if (isGitnexusAnalyzeRequired(finalResult.permissionRequired)) {
-        try {
-          startDetachedGitnexusAnalyze(runOptions.workingDirectory ?? process.cwd());
-          appendTimelineEventFileOnly({
-            t: Date.now(),
-            type: TIMELINE_EVENT_TYPES.META,
-            model: "gitnexus_analyze_started",
-            backend: "supervisor"
-          });
-        } catch (err) {
-          appendTimelineEventFileOnly({
-            t: Date.now(),
-            type: TIMELINE_EVENT_TYPES.META,
-            model: "gitnexus_analyze_start_failed",
-            backend: String(err?.message ?? err)
-          });
-        }
-      }
+      triggerGitnexusAnalyzeIfNeeded(statusSnapshot.last_auto_commit_sha, "terminal");
       this.writeReadyMarker(id);
       return id;
     } catch (err) {
@@ -25897,7 +26064,7 @@ ${appendError}
     }
   }
 }
-var JOB_TTL_DAYS, STALL_DETECTION_DEFAULTS, GITNEXUS_RISK_ORDER, MODEL_CONTEXT_WINDOWS, TERMINAL_COMPLIANCE_VERDICT_REGEX, AUTO_COMMIT_NOISE_PREFIXES, STATUS_WATCHDOG_INTERVAL_MS = 5000, STATUS_WATCHDOG_STALE_AFTER_MS = 30000;
+var JOB_TTL_DAYS, STALL_DETECTION_DEFAULTS, GITNEXUS_RISK_ORDER, MODEL_CONTEXT_WINDOWS, TERMINAL_COMPLIANCE_VERDICT_REGEX, PASS_COMPLIANCE_VERDICT_REGEX, AUTO_COMMIT_NOISE_PREFIXES, STATUS_WATCHDOG_INTERVAL_MS = 5000, STATUS_WATCHDOG_STALE_AFTER_MS = 30000;
 var init_supervisor = __esm(() => {
   init_job_root();
   init_timeline_events();
@@ -25925,8 +26092,9 @@ var init_supervisor = __esm(() => {
     { matcher: (model) => model.includes("qwen3.5") || model.includes("glm-5"), windowTokens: 128000 },
     { matcher: (model) => model.includes("claude"), windowTokens: 200000 }
   ];
-  TERMINAL_COMPLIANCE_VERDICT_REGEX = /## Compliance Verdict[\s\S]*?- Verdict: (PASS|PARTIAL|FAIL)/i;
-  AUTO_COMMIT_NOISE_PREFIXES = [".xtrm/", ".wolf/", ".specialists/jobs/", ".beads/"];
+  TERMINAL_COMPLIANCE_VERDICT_REGEX = /## Compliance Verdict[\s\S]*?- Verdict:\s*\**\s*(PASS|PARTIAL|FAIL)\s*\**/i;
+  PASS_COMPLIANCE_VERDICT_REGEX = /## Compliance Verdict[\s\S]*?- Verdict:\s*\**\s*PASS\s*\**/i;
+  AUTO_COMMIT_NOISE_PREFIXES = [".xtrm/", ".wolf/", ".specialists/jobs/", ".beads/", ".pi/"];
 });
 
 // src/cli/list.ts
@@ -26652,8 +26820,20 @@ function assertXtrmPrerequisites(cwd) {
   const hasXtCli = isInstalled("xt");
   if (hasXtrmDir && hasXtCli)
     return;
-  console.error("specialists requires xtrm. Run: npm install -g xtrm-tools && xt install");
-  process.exit(1);
+  if (!hasXtCli) {
+    console.error("specialists init: missing xt CLI.");
+    console.error("1. Install xtrm-tools globally: npm install -g xtrm-tools");
+    console.error("2. Run xt install");
+    console.error("3. Run xt init in this repo");
+    console.error("4. Verify xt is available: xt --version");
+    process.exit(1);
+  }
+  if (!hasXtrmDir) {
+    console.error("specialists init: missing .xtrm/ in this repo.");
+    console.error("1. Run xt init in this repo");
+    console.error("2. Verify xt is available: xt --version");
+    process.exit(1);
+  }
 }
 function warnMissingOptionalPrerequisites() {
   const optionalTools = [
@@ -27103,22 +27283,51 @@ function ensureObservabilityDb(cwd) {
   }
   ensureGitignoreHasObservabilityDbEntries(location.gitRoot);
 }
+function extractSpecialistsBlockSpan(existing) {
+  const start = existing.indexOf("<!-- specialists:start -->");
+  if (start === -1)
+    return null;
+  const endMarker = "<!-- specialists:end -->";
+  const endMarkerIndex = existing.indexOf(endMarker, start);
+  if (endMarkerIndex === -1)
+    return null;
+  return { start, end: endMarkerIndex + endMarker.length };
+}
 function ensureAgentsMd(cwd) {
   const agentsPath = join11(cwd, "AGENTS.md");
-  if (existsSync12(agentsPath)) {
-    const existing = readFileSync10(agentsPath, "utf-8");
-    if (existing.includes(AGENTS_MARKER)) {
-      skip("AGENTS.md already has Specialists section");
-    } else {
-      writeFileSync4(agentsPath, existing.trimEnd() + `
-
-` + AGENTS_BLOCK, "utf-8");
-      ok("appended Specialists section to AGENTS.md");
-    }
-  } else {
+  if (!existsSync12(agentsPath)) {
     writeFileSync4(agentsPath, AGENTS_BLOCK, "utf-8");
     ok("created AGENTS.md with Specialists section");
+    return;
   }
+  const existing = readFileSync10(agentsPath, "utf-8");
+  const span = extractSpecialistsBlockSpan(existing);
+  if (span) {
+    const next = existing.slice(0, span.start) + AGENTS_BLOCK + existing.slice(span.end);
+    if (next === existing) {
+      skip("AGENTS.md already has Specialists section");
+      return;
+    }
+    writeFileSync4(agentsPath, next, "utf-8");
+    ok("updated Specialists section in AGENTS.md");
+    return;
+  }
+  if (existing.includes(AGENTS_MARKER)) {
+    const markerIndex = existing.indexOf(AGENTS_MARKER);
+    const nextH2Match = /^## /m.exec(existing.slice(markerIndex + AGENTS_MARKER.length));
+    const nextH2Index = nextH2Match ? markerIndex + AGENTS_MARKER.length + nextH2Match.index : existing.length;
+    const next = existing.slice(0, markerIndex).trimEnd() + `
+
+` + AGENTS_BLOCK + (nextH2Index < existing.length ? `
+` + existing.slice(nextH2Index) : "");
+    writeFileSync4(agentsPath, next, "utf-8");
+    ok("migrated Specialists section in AGENTS.md");
+    return;
+  }
+  writeFileSync4(agentsPath, existing.trimEnd() + `
+
+` + AGENTS_BLOCK, "utf-8");
+  ok("appended Specialists section to AGENTS.md");
 }
 function readJsonObject(path) {
   if (!existsSync12(path))
@@ -27315,6 +27524,7 @@ var init_init = __esm(() => {
   init_memory_retrieval();
   init_canonical_asset_resolver();
   AGENTS_BLOCK = `
+<!-- specialists:start -->
 ## Specialists
 
 Use CLI commands via Bash to run and monitor specialists:
@@ -27340,6 +27550,7 @@ Canonical tracked flow:
 5. Close/update bead with outcome
 
 Add custom specialists to \`.specialists/user/\` to extend defaults.
+<!-- specialists:end -->
 `.trimStart();
   GITIGNORE_ENTRIES = [
     ".specialists/jobs/",
@@ -28373,6 +28584,37 @@ function resolveScriptSpecialistName(name) {
     return "changelog-drafter";
   return name;
 }
+function collectRequiredOutputKeys(spec) {
+  const keys = new Set;
+  const declared = spec.specialist.execution.expected_output_keys;
+  if (Array.isArray(declared)) {
+    for (const value of declared) {
+      if (typeof value === "string" && value.length > 0)
+        keys.add(value);
+    }
+  }
+  if (spec.specialist.execution.response_format === "json") {
+    const required2 = spec.specialist.prompt.output_schema?.required;
+    if (Array.isArray(required2)) {
+      for (const value of required2) {
+        if (typeof value === "string" && value.length > 0)
+          keys.add(value);
+      }
+    }
+  }
+  return Array.from(keys);
+}
+function detectTemplateFieldMisuse(template, specPrompt) {
+  if (!specPrompt)
+    return null;
+  if (template.length > TEMPLATE_FIELD_MISUSE_MAX_LEN)
+    return null;
+  if (!TEMPLATE_FIELD_IDENTIFIER_RE.test(template))
+    return null;
+  if (!Object.prototype.hasOwnProperty.call(specPrompt, template))
+    return null;
+  return template;
+}
 async function runScriptSpecialist(input2, options) {
   const traceId = randomUUID();
   const startedAt = Date.now();
@@ -28383,6 +28625,25 @@ async function runScriptSpecialist(input2, options) {
     const skillPaths = options.trust?.allowSkills ? collectSkillPaths(spec) : [];
     const skillSources = options.trust?.allowSkills ? computeSkillSources(spec) : undefined;
     const template = input2.template ?? spec.specialist.prompt.task_template;
+    if (input2.template !== undefined) {
+      const misusedField = detectTemplateFieldMisuse(input2.template, spec.specialist.prompt);
+      if (misusedField !== null) {
+        const modelCandidates2 = collectModelCandidates(input2, spec, options);
+        return {
+          success: false,
+          error: `template field misuse: input.template equals spec.prompt.${misusedField} key name (${input2.template.length} chars). The 'template' input field expects the literal template body, not a spec key. To use the spec's default, omit 'template'; to use a non-default template body, pass its full text inline.`,
+          error_type: "template_field_misuse",
+          meta: {
+            specialist: resolvedSpecialist,
+            requested_specialist: input2.requested_specialist ?? input2.specialist,
+            resolved_specialist: resolvedSpecialist,
+            model: modelCandidates2[0],
+            duration_ms: Date.now() - startedAt,
+            trace_id: traceId
+          }
+        };
+      }
+    }
     const prompt = applyOutputContract(renderTaskTemplate(template, input2.variables ?? {}), spec);
     const modelCandidates = collectModelCandidates(input2, spec, options);
     const promptLimitBytes = resolvePromptLimitBytes(spec);
@@ -28432,11 +28693,12 @@ async function runScriptSpecialist(input2, options) {
         writeTraceRow(observability2, resolvedSpecialist, model, traceId, parsed.text, durationMs2, skillSources, options.onAuditFailure);
       if (parsed.kind === "success") {
         let parsed_json;
-        if (spec.specialist.execution.response_format === "json") {
+        const expectedKeys = collectRequiredOutputKeys(spec);
+        const shouldParseJson = spec.specialist.execution.response_format === "json" || expectedKeys.length > 0;
+        if (shouldParseJson) {
           try {
             parsed_json = JSON.parse(stripMarkdownFences(parsed.text));
-            const required2 = Array.isArray(spec.specialist.prompt.output_schema?.required) ? spec.specialist.prompt.output_schema.required.filter((value) => typeof value === "string") : [];
-            for (const key of required2) {
+            for (const key of expectedKeys) {
               if (parsed_json === null || typeof parsed_json !== "object" || !(key in parsed_json))
                 throw new Error(`Missing required output field: ${key}`);
             }
@@ -28586,7 +28848,7 @@ function classifyAttempt(attempt) {
 function isRetryableModelFailure(stderr, text) {
   return stderr.includes("0 tokens") || stderr.includes("quota") || stderr.includes("rate limit") || stderr.includes("403") || stderr.includes("401") || stderr.includes("insufficient_quota") || !text && !stderr.trim();
 }
-var CompatGuardError, DEFAULT_PENDING_LINE_LIMIT_BYTES, DEFAULT_ASSISTANT_TEXT_LIMIT_BYTES, DEFAULT_STDERR_LIMIT_BYTES, DEFAULT_PROMPT_LIMIT_BYTES;
+var CompatGuardError, DEFAULT_PENDING_LINE_LIMIT_BYTES, DEFAULT_ASSISTANT_TEXT_LIMIT_BYTES, DEFAULT_STDERR_LIMIT_BYTES, DEFAULT_PROMPT_LIMIT_BYTES, TEMPLATE_FIELD_MISUSE_MAX_LEN = 30, TEMPLATE_FIELD_IDENTIFIER_RE;
 var init_script_runner = __esm(() => {
   init_observability_sqlite();
   CompatGuardError = class CompatGuardError extends Error {
@@ -28601,6 +28863,7 @@ var init_script_runner = __esm(() => {
   DEFAULT_ASSISTANT_TEXT_LIMIT_BYTES = 4 * 1024 * 1024;
   DEFAULT_STDERR_LIMIT_BYTES = 1 * 1024 * 1024;
   DEFAULT_PROMPT_LIMIT_BYTES = 4 * 1024 * 1024;
+  TEMPLATE_FIELD_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 });
 
 // src/cli/validate.ts
@@ -29203,12 +29466,22 @@ function createUserFork(source, targetName) {
 }
 async function resolveTargets(args) {
   const loader = new SpecialistLoader;
-  const allSpecialists = (await loader.list()).filter((specialist) => specialist.scope !== "package");
+  const listedSpecialists = await loader.list();
+  const allSpecialists = listedSpecialists.filter((specialist) => specialist.scope !== "package");
   if (args.all) {
     return allSpecialists;
   }
   const match = allSpecialists.find((specialist) => specialist.name === args.name && (args.scope === undefined || specialist.scope === args.scope));
   if (!match) {
+    const packageMatch = args.scope === undefined ? listedSpecialists.find((specialist) => specialist.name === args.name && specialist.scope === "package") : undefined;
+    if (packageMatch) {
+      fail(`Error: specialist "${args.name}" lives in [package] tier and cannot be edited directly.
+` + `  Fork to user tier first:
+
+` + `    ${yellow8(`specialists edit ${args.name} --fork-from ${args.name}`)}
+
+` + `  Then re-run your edit command.`);
+    }
     const hint = args.scope ? ` (scope: ${args.scope})` : "";
     fail(`Error: specialist "${args.name}" not found${hint}
   Run ${yellow8("specialists list")} to see available specialists`);
@@ -29686,7 +29959,7 @@ var init_config = __esm(() => {
 });
 
 // src/specialist/worktree.ts
-import { existsSync as existsSync16, symlinkSync as symlinkSync2, mkdirSync as mkdirSync8 } from "fs";
+import { existsSync as existsSync16, symlinkSync as symlinkSync2, mkdirSync as mkdirSync8, rmSync as rmSync2 } from "fs";
 import { join as join16, resolve as resolve9 } from "path";
 import { spawnSync as spawnSync11, execFileSync as execFileSync2 } from "child_process";
 function deriveBranchName(beadId, specialistName) {
@@ -29726,9 +29999,52 @@ function provisionWorktree(options) {
   const worktreeName = deriveWorktreeName(options.beadId, options.specialistName);
   const worktreePath = resolve9(join16(worktreeBase, worktreeName));
   createWorktreeViaBd(worktreePath, branch, commonRoot);
+  normalizeParentHooksPath(commonRoot);
+  try {
+    rmSync2(join16(worktreePath, ".beads"), { recursive: true, force: true });
+    markBeadsSkipWorktree(worktreePath);
+  } catch {}
   symlinkPiNpmCache(commonRoot, worktreePath);
   return { branch, worktreePath, reused: false };
 }
+function normalizeParentHooksPath(mainRepoRoot) {
+  try {
+    const result = spawnSync11("git", ["-C", mainRepoRoot, "config", "--get", "core.hooksPath"], {
+      stdio: "pipe",
+      encoding: "utf8"
+    });
+    if (result.status !== 0)
+      return;
+    const current = (result.stdout ?? "").trim();
+    if (!current)
+      return;
+    if (resolve9(current) === current)
+      return;
+    if (current !== ".beads/hooks" && current !== "./.beads/hooks")
+      return;
+    const absolute = join16(mainRepoRoot, ".beads", "hooks");
+    spawnSync11("git", ["-C", mainRepoRoot, "config", "core.hooksPath", absolute], { stdio: "pipe" });
+  } catch {}
+}
+function markBeadsSkipWorktree(worktreePath) {
+  try {
+    const trackedResult = spawnSync11("git", ["-C", worktreePath, "ls-files", "--", ".beads"], {
+      cwd: worktreePath,
+      stdio: "pipe",
+      encoding: "utf8"
+    });
+    if (trackedResult.status !== 0)
+      return;
+    const trackedPaths = (trackedResult.stdout ?? "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    if (trackedPaths.length === 0)
+      return;
+    spawnSync11("git", ["-C", worktreePath, "update-index", "--skip-worktree", "--", ...trackedPaths], {
+      cwd: worktreePath,
+      stdio: "pipe",
+      encoding: "utf8"
+    });
+  } catch {}
+}
 function symlinkPiNpmCache(commonRoot, worktreePath) {
   const source = join16(commonRoot, ".pi", "npm");
   const target = join16(worktreePath, ".pi", "npm");
@@ -29775,7 +30091,7 @@ var init_worktree = __esm(() => {
 });
 
 // src/specialist/epic-reconciler.ts
-import { mkdirSync as mkdirSync9, openSync as openSync2, readFileSync as readFileSync15, rmSync as rmSync2, writeFileSync as writeFileSync7 } from "fs";
+import { mkdirSync as mkdirSync9, openSync as openSync2, readFileSync as readFileSync15, rmSync as rmSync3, writeFileSync as writeFileSync7 } from "fs";
 import { join as join17 } from "path";
 function buildEpicLockPath(epicId) {
   const location = resolveObservabilityDbLocation();
@@ -29803,7 +30119,7 @@ function withEpicAdvisoryLock(epicId, action) {
   } finally {
     if (lockFd !== null) {
       try {
-        rmSync2(lockPath, { force: true });
+        rmSync3(lockPath, { force: true });
       } catch {}
     }
   }
@@ -30015,11 +30331,25 @@ import { join as join18 } from "path";
 function parseOptions(argv) {
   let target = "";
   let rebuild = false;
-  for (const argument of argv) {
+  let targetBranch = "";
+  for (let index = 0;index < argv.length; index += 1) {
+    const argument = argv[index];
     if (argument === "--rebuild") {
       rebuild = true;
       continue;
     }
+    if (argument === "--target-branch") {
+      const branchName = argv[index + 1];
+      if (!branchName || branchName.startsWith("-")) {
+        throw new Error("Missing value for --target-branch");
+      }
+      if (targetBranch) {
+        throw new Error("Only one target branch is supported");
+      }
+      targetBranch = branchName;
+      index += 1;
+      continue;
+    }
     if (argument.startsWith("-")) {
       throw new Error(`Unknown option: ${argument}`);
     }
@@ -30031,7 +30361,7 @@ function parseOptions(argv) {
   if (!target) {
     throw new Error("Missing merge target");
   }
-  return { target, rebuild };
+  return { target, rebuild, targetBranch: targetBranch ? validateTargetBranchRef(targetBranch) : undefined };
 }
 function runCommand(command, args, cwd = process.cwd()) {
   return spawnSync12(command, args, {
@@ -30040,7 +30370,17 @@ function runCommand(command, args, cwd = process.cwd()) {
     stdio: ["ignore", "pipe", "pipe"]
   });
 }
-function resolveDefaultBranchName(cwd = process.cwd()) {
+function validateTargetBranchRef(targetBranch, cwd = process.cwd()) {
+  const verification = runCommand("git", ["rev-parse", "--verify", `${targetBranch}^{commit}`], cwd);
+  if (verification.status !== 0) {
+    const detail = verification.stderr.trim() || verification.stdout.trim() || "unknown git ref error";
+    throw new Error(`Invalid --target-branch '${targetBranch}': ${detail}`);
+  }
+  return targetBranch;
+}
+function resolveDefaultBranchName(cwd = process.cwd(), overrideBranch) {
+  if (overrideBranch)
+    return overrideBranch;
   const symbolicRef = runCommand("git", ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], cwd);
   if (symbolicRef.status === 0) {
     const remoteHeadRef = symbolicRef.stdout.trim();
@@ -30170,7 +30510,7 @@ function checkEpicUnresolvedGuard(chainRootBeadId) {
     return {
       blocked: false,
       epicId: membership.epicId,
-      message: `Warning: unable to verify epic ${membership.epicId} status (observability DB unavailable). Proceeding with chain merge.`
+      message: `Warning: unable to verify epic ${membership.epicId} readiness (observability DB unavailable). Proceeding with chain merge.`
     };
   }
   try {
@@ -30186,12 +30526,25 @@ function checkEpicUnresolvedGuard(chainRootBeadId) {
     if (!isEpicUnresolvedState(status)) {
       return { blocked: false, epicId: membership.epicId, epicStatus: status };
     }
+    const summary = loadEpicReadinessSummary(sqliteClient, membership.epicId);
+    const chain = summary.chains.find((entry) => entry.chain_root_bead_id === chainRootBeadId || entry.chain_id === chainRootBeadId);
+    if (!chain) {
+      return {
+        blocked: true,
+        epicId: membership.epicId,
+        epicStatus: status,
+        message: `Chain ${chainRootBeadId} belongs to epic ${membership.epicId} but has no derived readiness record. Use 'sp epic status ${membership.epicId}' to inspect migration state.`
+      };
+    }
+    if (chain.state === "pass") {
+      return { blocked: false, epicId: membership.epicId, epicStatus: status };
+    }
     return {
       blocked: true,
       epicId: membership.epicId,
       epicStatus: status,
-      message: `Chain ${chainRootBeadId} belongs to unresolved epic ${membership.epicId} (status: ${status}).
-Use 'sp epic merge ${membership.epicId}' to publish all chains together, or 'sp epic status ${membership.epicId}' to inspect the epic state.`
+      message: `Chain ${chainRootBeadId} blocked by derived readiness: ${chain.blocking_reason ?? chain.state}.
+Use 'sp epic status ${membership.epicId}' to inspect epic state.`
     };
   } finally {
     sqliteClient.close();
@@ -30466,8 +30819,8 @@ function parseNameStatusLine(line) {
 function isNoisePath(path) {
   return NOISE_PATH_PREFIXES.some((prefix) => path.startsWith(prefix));
 }
-function isBranchAlreadyPublished(branch, cwd = process.cwd()) {
-  const baseBranch = resolveDefaultBranchName(cwd);
+function isBranchAlreadyPublished(branch, cwd = process.cwd(), targetBranch) {
+  const baseBranch = resolveDefaultBranchName(cwd, targetBranch);
   const ancestorCheck = runCommand("git", ["merge-base", "--is-ancestor", branch, baseBranch], cwd);
   if (ancestorCheck.status === 0) {
     return true;
@@ -30478,8 +30831,8 @@ function isBranchAlreadyPublished(branch, cwd = process.cwd()) {
   }
   return cherryPickCount.stdout.trim() === "0";
 }
-function previewBranchMergeDelta(branch, cwd = process.cwd()) {
-  const baseBranch = resolveDefaultBranchName(cwd);
+function previewBranchMergeDelta(branch, cwd = process.cwd(), targetBranch) {
+  const baseBranch = resolveDefaultBranchName(cwd, targetBranch);
   const mergeBase = runCommand("git", ["merge-base", baseBranch, branch], cwd);
   if (mergeBase.status !== 0) {
     throw new Error(`Unable to compute merge base for '${baseBranch}' and '${branch}'.`);
@@ -30503,12 +30856,12 @@ function previewBranchMergeDelta(branch, cwd = process.cwd()) {
     substantiveFiles
   };
 }
-function evaluateMergeWorthiness(preview, branch, cwd = process.cwd()) {
+function evaluateMergeWorthiness(preview, branch, cwd = process.cwd(), targetBranch) {
   if (preview.files.length === 0) {
-    return isBranchAlreadyPublished(branch, cwd) ? { shouldMerge: false, reason: "already-published" } : { shouldMerge: false, reason: "empty-delta" };
+    return isBranchAlreadyPublished(branch, cwd, targetBranch) ? { shouldMerge: false, reason: "already-published" } : { shouldMerge: false, reason: "empty-delta" };
   }
   if (preview.substantiveFiles.length === 0) {
-    return isBranchAlreadyPublished(branch, cwd) ? { shouldMerge: false, reason: "already-published" } : { shouldMerge: false, reason: "noise-only-delta" };
+    return isBranchAlreadyPublished(branch, cwd, targetBranch) ? { shouldMerge: false, reason: "already-published" } : { shouldMerge: false, reason: "noise-only-delta" };
   }
   return { shouldMerge: true, reason: "ok" };
 }
@@ -30525,9 +30878,9 @@ function throwWorthinessBlockError(target, preview, decision) {
   throw new Error(`Refusing merge for '${target.branch}': ${reason}.
 ` + `Diagnostics: ${summary}`);
 }
-function assertBranchMergeWorthiness(target, cwd = process.cwd()) {
-  const preview = previewBranchMergeDelta(target.branch, cwd);
-  const decision = evaluateMergeWorthiness(preview, target.branch, cwd);
+function assertBranchMergeWorthiness(target, cwd = process.cwd(), targetBranch) {
+  const preview = previewBranchMergeDelta(target.branch, cwd, targetBranch);
+  const decision = evaluateMergeWorthiness(preview, target.branch, cwd, targetBranch);
   if (decision.reason === "already-published" || decision.shouldMerge)
     return decision;
   throwWorthinessBlockError(target, preview, decision);
@@ -30553,8 +30906,8 @@ function getCurrentHeadBranch(cwd = process.cwd()) {
 function tryAbortRebase(cwd = process.cwd()) {
   runCommand("git", ["rebase", "--abort"], cwd);
 }
-function rebaseBranchOntoMaster(branch, worktreePath) {
-  const baseBranch = resolveDefaultBranchName(worktreePath);
+function rebaseBranchOntoMaster(branch, worktreePath, targetBranch) {
+  const baseBranch = resolveDefaultBranchName(worktreePath, targetBranch);
   const checkedOutBranch = getCurrentHeadBranch(worktreePath);
   if (checkedOutBranch !== branch) {
     throw new Error(`Expected branch '${branch}' in worktree '${worktreePath}', found '${checkedOutBranch}'.`);
@@ -30588,6 +30941,11 @@ ${conflicts.map((file) => `- ${file}`).join(`
   throw new Error(`Merge conflict while merging '${branch}'.${context}`);
 }
 function runTypecheckGate(cwd = process.cwd()) {
+  const hasTypeScriptConfig = existsSync17(join18(cwd, "tsconfig.json")) || readdirSync6(cwd).some((entry) => entry.startsWith("tsconfig") && entry.endsWith(".json"));
+  if (!hasTypeScriptConfig) {
+    console.log("TypeScript gate: skipped (no tsconfig)");
+    return;
+  }
   const tsc = runCommand("bunx", ["tsc", "--noEmit"], cwd);
   if (tsc.status === 0)
     return;
@@ -30623,7 +30981,7 @@ function printSummary(steps, rebuild) {
 }
 function printUsageAndExit(message) {
   console.error(message);
-  console.error("Usage: specialists|sp merge <target-bead-id> [--rebuild]");
+  console.error("Usage: specialists|sp merge <target-bead-id> [--rebuild] [--target-branch <name>]");
   process.exit(1);
 }
 function syncEpicStateAfterMerge(target) {
@@ -30641,6 +30999,7 @@ function syncEpicStateAfterMerge(target) {
 }
 function runMergePlan(targets, options) {
   const mainRepoRoot = resolveMainWorktreeRoot();
+  const targetBranch = options.targetBranch ? validateTargetBranchRef(options.targetBranch, mainRepoRoot) : undefined;
   const shelved = options.mode === "direct" ? (() => {
     const dirtyState = classifyMainRepoDirtyState(targets.map((target) => target.branch), mainRepoRoot);
     if (dirtyState.overlappingPaths.length > 0) {
@@ -30654,7 +31013,7 @@ ${formatDirtyConflictMessage(dirtyState.overlappingPaths)}
   const mergedSteps = [];
   try {
     for (const target of targets) {
-      const worthiness = assertBranchMergeWorthiness(target, mainRepoRoot);
+      const worthiness = assertBranchMergeWorthiness(target, mainRepoRoot, targetBranch);
       if (worthiness.reason === "already-published") {
         mergedSteps.push({
           beadId: target.beadId,
@@ -30663,7 +31022,7 @@ ${formatDirtyConflictMessage(dirtyState.overlappingPaths)}
         });
         continue;
       }
-      rebaseBranchOntoMaster(target.branch, target.worktreePath);
+      rebaseBranchOntoMaster(target.branch, target.worktreePath, targetBranch);
       mergeBranch(target.branch, mainRepoRoot);
       runTypecheckGate(mainRepoRoot);
       syncEpicStateAfterMerge(target);
@@ -30755,18 +31114,21 @@ async function run13() {
     printUsageAndExit(message);
   }
   const targets = resolveMergeTargets(options.target);
-  const mergedSteps = runMergePlan(targets, { rebuild: options.rebuild });
+  const mergedSteps = runMergePlan(targets, { rebuild: options.rebuild, targetBranch: options.targetBranch });
   printSummary(mergedSteps, options.rebuild);
 }
 var TERMINAL_STATUSES, NOISE_PATH_PREFIXES, MERGE_DIRTY_IGNORE_PREFIXES;
 var init_merge = __esm(() => {
   init_observability_sqlite();
+  init_epic_readiness();
   init_epic_reconciler();
   init_epic_lifecycle();
   TERMINAL_STATUSES = new Set(["done", "error", "cancelled"]);
   NOISE_PATH_PREFIXES = [".xtrm/reports/", ".wolf/", ".specialists/jobs/"];
   MERGE_DIRTY_IGNORE_PREFIXES = [
     ...NOISE_PATH_PREFIXES,
+    ".beads/",
+    ".xtrm/skills/active/",
     "dist/"
   ];
 });
@@ -30864,15 +31226,37 @@ function formatEventLine(event, options) {
   const detailParts = [];
   let detail = "";
   if (event.type === "meta") {
-    detailParts.push(`model=${event.model}`);
-    detailParts.push(`backend=${event.backend}`);
-    if (event.source)
-      detailParts.push(`source=${event.source}`);
+    if (event.model === "gitnexus_analyze_started") {
+      detailParts.push("gitnexus=analyze_started");
+      detailParts.push(`source=${event.backend}`);
+    } else if (event.model === "gitnexus_analyze_start_failed") {
+      detailParts.push("gitnexus=analyze_start_failed");
+      detailParts.push(`reason=${event.backend}`);
+    } else {
+      detailParts.push(`model=${event.model}`);
+      detailParts.push(`backend=${event.backend}`);
+      if (event.source)
+        detailParts.push(`source=${event.source}`);
+    }
   } else if (event.type === "tool") {
     detail = formatToolDetail(event);
   } else if (event.type === "error") {
     detailParts.push(`source=${event.source}`);
     detailParts.push(`error=${event.error_message}`);
+  } else if (event.type === "auto_commit_success" || event.type === "auto_commit_skipped" || event.type === "auto_commit_failed") {
+    const status = event.type.replace("auto_commit_", "");
+    detailParts.push(`status=${status}`);
+    if (event.commit_sha)
+      detailParts.push(`commit=${event.commit_sha.slice(0, 12)}`);
+    if (event.committed_files) {
+      detailParts.push(`files=${event.committed_files.length}`);
+      if (event.committed_files.length > 0) {
+        const filePreview = event.committed_files.slice(0, 3).join(",");
+        detailParts.push(`paths=${filePreview}${event.committed_files.length > 3 ? ",\u2026" : ""}`);
+      }
+    }
+    if (event.reason)
+      detailParts.push(`reason=${event.reason}`);
   } else if (event.type === "run_complete") {
     detailParts.push(`status=${event.status}`);
     detailParts.push(`elapsed=${formatElapsed(event.elapsed_s)}`);
@@ -30997,17 +31381,21 @@ var init_format_helpers = __esm(() => {
     turn_summary: "TURN+",
     compaction: "CMPCT",
     retry: "RETRY",
-    error: "ERROR"
+    error: "ERROR",
+    auto_commit_success: "AUTO+",
+    auto_commit_skipped: "AUTO-",
+    auto_commit_failed: "AUTO!"
   };
 });
 
 // src/cli/run.ts
 var exports_run = {};
 __export(exports_run, {
-  run: () => run14
+  run: () => run14,
+  buildInjectedReviewerDiffVariables: () => buildInjectedReviewerDiffVariables
 });
 import { join as join19 } from "path";
-import { readFileSync as readFileSync17 } from "fs";
+import { existsSync as existsSync18, readFileSync as readFileSync17, readdirSync as readdirSync7, statSync as statSync3, writeFileSync as writeFileSync8 } from "fs";
 import { randomBytes } from "crypto";
 import { spawn as cpSpawn, execSync as execSync4 } from "child_process";
 async function parseArgs7(argv) {
@@ -31182,12 +31570,58 @@ function resolveEpicIdForBead(sqliteClient, beadId) {
     return;
   return bead.parent;
 }
-function assertNoStaleBaseSiblings(beadId, forceStaleBase) {
-  const sqliteClient = createObservabilitySqliteClient();
-  if (!sqliteClient)
+function ensureObservabilityDb2(cwd = process.cwd()) {
+  const existing = createObservabilitySqliteClient(cwd);
+  if (existing) {
+    existing.close();
     return;
-  try {
-    const epicId = resolveEpicIdForBead(sqliteClient, beadId);
+  }
+  const location = resolveObservabilityDbLocation(cwd);
+  const bootstrapped = createObservabilitySqliteClientAtPath(location.dbPath);
+  if (!bootstrapped)
+    return;
+  bootstrapped.close();
+}
+function resolveNewestJobIdFromDb(cwd, jobsDir, specialist, previousLatest, minStartedAtMs) {
+  const sqliteClient = createObservabilitySqliteClient(cwd);
+  if (!sqliteClient)
+    return "";
+  try {
+    const newest = sqliteClient.listStatuses().filter((status) => {
+      if (status.specialist !== specialist || status.id === previousLatest || status.started_at_ms < minStartedAtMs)
+        return false;
+      return existsSync18(join19(jobsDir, status.id, "status.json"));
+    }).sort((left, right) => right.started_at_ms - left.started_at_ms || left.id.localeCompare(right.id))[0];
+    return newest?.id ?? "";
+  } catch {
+    return "";
+  } finally {
+    sqliteClient.close();
+  }
+}
+function resolveNewestJobIdFromJobsDir(jobsDir, previousLatest, minMtimeMs) {
+  try {
+    const entries = readdirSync7(jobsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && /^[a-f0-9]{6}$/.test(entry.name) && entry.name !== previousLatest).map((entry) => {
+      const dirPath = join19(jobsDir, entry.name);
+      const statusPath = join19(dirPath, "status.json");
+      const stats = statSync3(dirPath);
+      const statusStats = statSync3(statusPath);
+      return {
+        id: entry.name,
+        mtimeMs: Math.max(stats.mtimeMs, statusStats.mtimeMs)
+      };
+    }).filter((entry) => entry.mtimeMs >= minMtimeMs).sort((left, right) => right.mtimeMs - left.mtimeMs || left.id.localeCompare(right.id));
+    return entries[0]?.id ?? "";
+  } catch {
+    return "";
+  }
+}
+function assertNoStaleBaseSiblings(beadId, forceStaleBase) {
+  const sqliteClient = createObservabilitySqliteClient();
+  if (!sqliteClient)
+    return;
+  try {
+    const epicId = resolveEpicIdForBead(sqliteClient, beadId);
     if (!epicId)
       return;
     const siblingChains = sqliteClient.listEpicChainsWithLatestJob(epicId).filter((chain) => chain.chain_root_bead_id !== beadId && Boolean(chain.branch));
@@ -31417,7 +31851,7 @@ function buildInjectedReviewerDiffVariables(cwd, maxFiles = 20) {
   for (const src of sources) {
     const stat2 = read(src.statCmd);
     const files = read(src.namesCmd).split(`
-`).map((line) => line.trim()).filter(Boolean).slice(0, maxFiles);
+`).map((line) => line.trim()).filter(Boolean).slice(0, maxFiles).filter((file) => !AUTO_COMMIT_NOISE_PREFIXES.some((prefix) => file.startsWith(prefix)));
     if (files.length === 0)
       continue;
     let remaining = MAX_TOTAL_HUNKS_CHARS;
@@ -31457,6 +31891,7 @@ ${truncated}` : `### ${file}
 }
 async function run14() {
   const args = await parseArgs7(process.argv.slice(3));
+  ensureObservabilityDb2(process.cwd());
   const loader = new SpecialistLoader;
   const specialist = await loader.get(args.name).catch((err) => {
     process.stderr.write(`Error: ${err?.message ?? err}
@@ -31475,6 +31910,25 @@ async function run14() {
 `);
     process.exit(1);
   }
+  if (args.beadId && !args.reuseJobId) {
+    const sqliteClient = createObservabilitySqliteClient();
+    if (sqliteClient) {
+      try {
+        const existing = sqliteClient.findActiveJob(args.beadId, args.name);
+        if (existing?.job_id) {
+          process.stderr.write(`Error: existing ${existing.status ?? "unknown"} job '${existing.job_id}' already targets bead '${args.beadId}' specialist '${args.name}'.
+` + `To resume the keep-alive session: specialists run ${args.name} --job ${existing.job_id} ...
+` + `To inspect: specialists ps ${existing.job_id} --json
+` + `To cancel: specialists stop ${existing.job_id}
+`);
+          sqliteClient.close();
+          process.exit(1);
+        }
+      } finally {
+        sqliteClient.close();
+      }
+    }
+  }
   if (args.background) {
     const jobsDir2 = resolveJobsDir();
     const latestPath = join19(jobsDir2, "latest");
@@ -31486,27 +31940,50 @@ async function run14() {
       }
     })();
     const cwd = process.cwd();
+    const launchStartedAt = Date.now();
     const innerArgs = process.argv.slice(2).filter((a) => a !== "--background");
     const cmd = `${process.execPath} ${process.argv[1]} ${innerArgs.map(shellQuote2).join(" ")}`;
+    const tmuxCmd = `/bin/bash -lc ${shellQuote2(`cd ${shellQuote2(cwd)} && exec ${cmd}`)}`;
     let childPid;
+    let childExitCode;
+    let childExitPromise;
+    let handoffPath;
     if (isTmuxAvailable()) {
       const suffix = randomBytes(3).toString("hex");
       const sessionName = buildSessionName(args.name, suffix);
-      createTmuxSession(sessionName, cwd, cmd);
+      handoffPath = join19(jobsDir2, `.bg-job-id-${sessionName}`);
+      createTmuxSession(sessionName, cwd, tmuxCmd, { [JOB_ID_HANDOFF_PATH_ENV]: handoffPath });
     } else {
       const child = cpSpawn(process.execPath, [process.argv[1], ...innerArgs], {
         detached: true,
-        stdio: "ignore",
+        stdio: ["ignore", "ignore", "pipe"],
         cwd,
         env: process.env
       });
+      const childStderr = child.stderr;
+      if (childStderr) {
+        childStderr.setEncoding("utf8");
+        childStderr.on("data", (chunk) => {
+          process.stderr.write(chunk);
+        });
+      }
+      childExitPromise = new Promise((resolve10) => {
+        child.on("exit", (code) => {
+          childExitCode = code ?? 1;
+          resolve10();
+        });
+      });
       child.unref();
       childPid = child.pid;
     }
-    const deadline = Date.now() + 5000;
+    const pollTimeoutMs = isTmuxAvailable() ? 15000 : 5000;
+    const deadline = Date.now() + pollTimeoutMs;
     let jobId2 = "";
     while (Date.now() < deadline) {
-      await new Promise((r) => setTimeout(r, 100));
+      await Promise.race([
+        new Promise((r) => setTimeout(r, 100)),
+        childExitPromise
+      ]);
       try {
         const current = readFileSync17(latestPath, "utf-8").trim();
         if (current && current !== oldLatest) {
@@ -31514,6 +31991,26 @@ async function run14() {
           break;
         }
       } catch {}
+      if (!jobId2 && handoffPath) {
+        try {
+          const handoff = readFileSync17(handoffPath, "utf-8").trim();
+          if (/^[a-f0-9]{6}$/.test(handoff)) {
+            jobId2 = handoff;
+            break;
+          }
+        } catch {}
+      }
+      if (childExitCode !== undefined)
+        break;
+    }
+    if (!jobId2 && childExitCode !== undefined && childExitCode !== 0) {
+      process.exit(childExitCode);
+    }
+    if (!jobId2) {
+      jobId2 = resolveNewestJobIdFromDb(cwd, jobsDir2, args.name, oldLatest, launchStartedAt - 1000);
+    }
+    if (!jobId2) {
+      jobId2 = resolveNewestJobIdFromJobsDir(jobsDir2, oldLatest, launchStartedAt - 1000);
     }
     if (jobId2) {
       process.stdout.write(`${jobId2}
@@ -31640,6 +32137,13 @@ async function run14() {
     onJobStarted: ({ id }) => {
       process.stderr.write(dim9(`[job started: ${id}]
 `));
+      const handoffPath = process.env[JOB_ID_HANDOFF_PATH_ENV];
+      if (handoffPath) {
+        try {
+          writeFileSync8(handoffPath, `${id}
+`, "utf-8");
+        } catch {}
+      }
       if (args.outputMode !== "raw") {
         stopTailer = startEventTailer(id, jobsDir, args.outputMode, args.name, effectiveBeadId);
       }
@@ -31701,7 +32205,7 @@ ${green9("\u2713")} ${footer}
 `));
   process.exit(0);
 }
-var bold11 = (s) => `\x1B[1m${s}\x1B[0m`, dim9 = (s) => `\x1B[2m${s}\x1B[0m`, green9 = (s) => `\x1B[32m${s}\x1B[0m`, cyan6 = (s) => `\x1B[36m${s}\x1B[0m`, BLOCKED_JOB_REUSE_STATUSES;
+var bold11 = (s) => `\x1B[1m${s}\x1B[0m`, dim9 = (s) => `\x1B[2m${s}\x1B[0m`, green9 = (s) => `\x1B[32m${s}\x1B[0m`, cyan6 = (s) => `\x1B[36m${s}\x1B[0m`, JOB_ID_HANDOFF_PATH_ENV = "SPECIALISTS_BG_JOB_ID_PATH", BLOCKED_JOB_REUSE_STATUSES;
 var init_run = __esm(() => {
   init_loader();
   init_runner();
@@ -31712,6 +32216,7 @@ var init_run = __esm(() => {
   init_job_root();
   init_worktree();
   init_observability_sqlite();
+  init_observability_db();
   init_merge();
   init_format_helpers();
   init_tmux_utils();
@@ -31769,7 +32274,7 @@ var init_node_resolve = __esm(() => {
 });
 
 // src/specialist/job-control.ts
-import { existsSync as existsSync18, readFileSync as readFileSync18, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync19, readFileSync as readFileSync18, writeFileSync as writeFileSync9 } from "fs";
 import { join as join20 } from "path";
 
 class JobControl {
@@ -31845,7 +32350,7 @@ class JobControl {
         return sqliteResult;
     } catch {}
     const resultPath = this.resultPath(jobId);
-    if (!existsSync18(resultPath))
+    if (!existsSync19(resultPath))
       return null;
     try {
       return readFileSync18(resultPath, "utf-8");
@@ -31881,7 +32386,7 @@ class JobControl {
     }
     const jsonLine = `${JSON.stringify(payload)}
 `;
-    writeFileSync8(status.fifo_path, jsonLine, { flag: "a" });
+    writeFileSync9(status.fifo_path, jsonLine, { flag: "a" });
   }
   resultPath(jobId) {
     return join20(this.jobsDir, jobId, "result.txt");
@@ -33959,7 +34464,7 @@ var exports_node = {};
 __export(exports_node, {
   handleNodeCommand: () => handleNodeCommand
 });
-import { existsSync as existsSync19, readFileSync as readFileSync19, readdirSync as readdirSync7 } from "fs";
+import { existsSync as existsSync20, readFileSync as readFileSync19, readdirSync as readdirSync8 } from "fs";
 import { randomUUID as randomUUID2 } from "crypto";
 import { spawnSync as spawnSync14 } from "child_process";
 import { basename as basename5, join as join21, resolve as resolve10 } from "path";
@@ -34152,9 +34657,9 @@ function discoverNodeConfigs(cwd) {
   const discoveredByName = new Map;
   for (const directory of NODE_DISCOVERY_DIRS) {
     const absoluteDir = resolve10(cwd, directory.path);
-    if (!existsSync19(absoluteDir))
+    if (!existsSync20(absoluteDir))
       continue;
-    const files = readdirSync7(absoluteDir).filter((fileName) => fileName.endsWith(NODE_CONFIG_SUFFIX));
+    const files = readdirSync8(absoluteDir).filter((fileName) => fileName.endsWith(NODE_CONFIG_SUFFIX));
     for (const fileName of files) {
       const path = join21(absoluteDir, fileName);
       const name = toNodeName(fileName);
@@ -34174,7 +34679,7 @@ function getNodeDiscoverySummary() {
 }
 function resolveNodeConfigPath(cwd, input2) {
   const explicitPath = resolve10(cwd, input2);
-  if (existsSync19(explicitPath)) {
+  if (existsSync20(explicitPath)) {
     return { name: toNodeName(explicitPath), path: explicitPath, source: "repo" };
   }
   const normalizedName = input2.endsWith(NODE_CONFIG_SUFFIX) ? input2.slice(0, -NODE_CONFIG_SUFFIX.length) : input2;
@@ -34824,7 +35329,6 @@ var exports_epic = {};
 __export(exports_epic, {
   handleEpicSyncCommand: () => handleEpicSyncCommand,
   handleEpicStatusCommand: () => handleEpicStatusCommand,
-  handleEpicResolveCommand: () => handleEpicResolveCommand,
   handleEpicMergeCommand: () => handleEpicMergeCommand,
   handleEpicListCommand: () => handleEpicListCommand,
   handleEpicCommand: () => handleEpicCommand,
@@ -34858,7 +35362,9 @@ function parseMergeOptions(argv) {
   let rebuild = false;
   let json = false;
   let pr = false;
-  for (const argument of argv) {
+  let targetBranch = "";
+  for (let index = 0;index < argv.length; index += 1) {
+    const argument = argv[index];
     if (argument === "--rebuild") {
       rebuild = true;
       continue;
@@ -34871,11 +35377,23 @@ function parseMergeOptions(argv) {
       pr = true;
       continue;
     }
+    if (argument === "--target-branch") {
+      const branchName = argv[index + 1];
+      if (!branchName || branchName.startsWith("-")) {
+        throw new Error("Missing value for --target-branch");
+      }
+      if (targetBranch) {
+        throw new Error("Only one target branch is supported");
+      }
+      targetBranch = branchName;
+      index += 1;
+      continue;
+    }
     if (argument.startsWith("-") && argument !== "--rebuild" && argument !== "--json" && argument !== "--pr") {
       throw new Error(`Unknown option: ${argument}`);
     }
   }
-  return { epicId, rebuild, json, pr };
+  return { epicId, rebuild, json, pr, targetBranch: targetBranch || undefined };
 }
 function parseListOptions(argv) {
   let unresolvedOnly = false;
@@ -34909,25 +35427,6 @@ function parseStatusOptions(argv) {
   }
   return { epicId, json };
 }
-function parseResolveOptions(argv) {
-  const epicId = parseEpicId(argv);
-  let dryRun = false;
-  let json = false;
-  for (const argument of argv) {
-    if (argument === "--dry-run") {
-      dryRun = true;
-      continue;
-    }
-    if (argument === "--json") {
-      json = true;
-      continue;
-    }
-    if (argument.startsWith("-") && argument !== "--dry-run" && argument !== "--json") {
-      throw new Error(`Unknown option: ${argument}`);
-    }
-  }
-  return { epicId, dryRun, json };
-}
 function parseSyncOptions(argv) {
   const epicId = parseEpicId(argv);
   let apply = false;
@@ -35072,12 +35571,9 @@ function gatherEpicContext(options) {
 }
 function validateEpicMergeReadiness(context) {
   const epicState = context.epicRecord?.status ?? "open";
-  if (isEpicTerminalState(epicState)) {
+  if (epicState === "merged" || epicState === "abandoned") {
     throw new Error(`Epic ${context.epicId} is already in terminal state '${epicState}'. No further merges allowed.`);
   }
-  if (epicState !== "resolving" && epicState !== "merge_ready") {
-    throw new Error(`Epic ${context.epicId} is in state '${epicState}'. Must be 'resolving' or 'merge_ready' before publication.`);
-  }
   const chainStatuses = [...context.chainJobStatuses.entries()].map(([chainId, status]) => ({
     chainId,
     hasRunningJob: status.hasRunningJob
@@ -35115,11 +35611,12 @@ function updateEpicState(epicId, fromState, toState) {
     sqlite.close();
   }
 }
-function mergeEpicChains(context, rebuild, pr) {
+function mergeEpicChains(context, rebuild, pr, targetBranch) {
   return executePublicationPlan(context.chainTargets, {
     rebuild,
     mode: pr ? "pr" : "direct",
-    publicationLabel: `epic-${context.epicId}`
+    publicationLabel: `epic-${context.epicId}`,
+    targetBranch
   });
 }
 function printEpicMergeSummary(result, rebuild, pr) {
@@ -35203,75 +35700,6 @@ async function handleEpicListCommand(argv) {
     sqlite.close();
   }
 }
-async function handleEpicResolveCommand(argv) {
-  let options;
-  try {
-    options = parseResolveOptions(argv);
-  } catch (error2) {
-    const message = error2 instanceof Error ? error2.message : String(error2);
-    console.error(message);
-    console.error("Usage: specialists epic resolve <epic-id> [--dry-run] [--json]");
-    process.exit(1);
-  }
-  const sqlite = createObservabilitySqliteClient();
-  if (!sqlite) {
-    const message = "Observability SQLite database not available. Run `sp db setup` first.";
-    if (options.json) {
-      console.log(JSON.stringify({ error: message }, null, 2));
-    } else {
-      console.error(message);
-    }
-    process.exit(1);
-  }
-  try {
-    const now = Date.now();
-    const existing = sqlite.readEpicRun(options.epicId);
-    const fromState = existing?.status ?? "open";
-    let toState;
-    try {
-      toState = transitionEpicState(fromState, "resolving");
-    } catch (error2) {
-      const message = error2 instanceof Error ? error2.message : String(error2);
-      if (options.json) {
-        console.log(JSON.stringify({ epic_id: options.epicId, from_state: fromState, error: message }, null, 2));
-      } else {
-        console.error(`Resolve blocked: ${message}`);
-      }
-      process.exit(1);
-      return;
-    }
-    if (!options.dryRun) {
-      sqlite.upsertEpicRun({
-        epic_id: options.epicId,
-        status: toState,
-        status_json: JSON.stringify({
-          epic_id: options.epicId,
-          status: toState,
-          previous_status: fromState,
-          transitioned_at_ms: now
-        }),
-        updated_at_ms: now
-      });
-    }
-    const transitionSummary = summarizeEpicTransition(options.epicId, fromState, toState);
-    if (options.json) {
-      console.log(JSON.stringify({
-        epic_id: options.epicId,
-        from_state: fromState,
-        to_state: toState,
-        dry_run: options.dryRun,
-        summary: transitionSummary
-      }, null, 2));
-      return;
-    }
-    console.log(transitionSummary);
-    if (options.dryRun) {
-      console.log("(dry-run: no state persisted)");
-    }
-  } finally {
-    sqlite.close();
-  }
-}
 async function handleEpicMergeCommand(argv) {
   let options;
   try {
@@ -35280,7 +35708,7 @@ async function handleEpicMergeCommand(argv) {
     const message = error2 instanceof Error ? error2.message : String(error2);
     console.error(message);
     console.error("");
-    console.error("Usage: specialists epic merge <epic-id> [--rebuild] [--pr] [--json]");
+    console.error("Usage: specialists epic merge <epic-id> [--rebuild] [--pr] [--json] [--target-branch <name>]");
     process.exit(1);
   }
   let context;
@@ -35308,20 +35736,12 @@ async function handleEpicMergeCommand(argv) {
     process.exit(1);
   }
   const fromState = currentState;
-  if (currentState === "resolving") {
-    const nextState = transitionEpicState(currentState, "merge_ready");
-    updateEpicState(context.epicId, currentState, nextState);
-    if (!options.json) {
-      console.log(summarizeEpicTransition(context.epicId, currentState, nextState));
-    }
-    currentState = nextState;
-  }
   let mergedChains = [];
   let mergeError;
   let toState = currentState;
   let pullRequestUrl;
   try {
-    const publicationResult = mergeEpicChains(context, options.rebuild, options.pr);
+    const publicationResult = mergeEpicChains(context, options.rebuild, options.pr, options.targetBranch);
     mergedChains = publicationResult.steps;
     pullRequestUrl = publicationResult.pullRequestUrl;
     toState = options.pr ? currentState : transitionEpicState(currentState, "merged");
@@ -35488,12 +35908,7 @@ async function handleEpicStatusCommand(argv) {
     }
     console.log("");
     console.log(`Epic: ${options.epicId}`);
-    if (epicRecord) {
-      console.log(`State: ${epicRecord.status}`);
-      console.log(`Updated: ${new Date(epicRecord.updated_at_ms).toISOString()}`);
-    } else {
-      console.log("State: (not tracked in SQLite, defaults to open)");
-    }
+    console.log(`State: ${epicRecord?.status ?? "(derived)"}`);
     console.log(`Readiness: ${readiness.isReady ? "ready" : "blocked"}`);
     console.log(`Summary: ${readiness.summary}`);
     console.log("");
@@ -35522,22 +35937,21 @@ async function handleEpicCommand(argv) {
   if (!subcommand || subcommand === "--help" || subcommand === "-h") {
     console.log([
       "",
-      "Usage: specialists epic <list|status|resolve|sync|abandon|merge> [options]",
+      "Usage: specialists epic <list|status|sync|abandon|merge> [options]",
       "",
       "Commands:",
-      "  list [--unresolved] [--json]                    List epics with lifecycle and readiness summary",
-      "  status <epic-id> [--json]                       Show epic state, chain statuses, and merge readiness",
-      "  resolve <epic-id> [--dry-run] [--json]          Transition epic from open to resolving",
-      "  sync <epic-id> [--apply] [--json]                Reconcile epic drift (dry-run by default)",
+      "  list [--unresolved] [--json]                    List epics with readiness summary",
+      "  status <epic-id> [--json]                       Show derived readiness and chain status",
+      "  sync <epic-id> [--apply] [--json]               Reconcile epic drift (dry-run by default)",
       "  abandon <epic-id> --reason <text> [--force] [--json]  Transition epic to abandoned",
       "  merge <epic-id> [--rebuild] [--pr] [--json]     Publish epic-owned chains in dependency order",
       "",
-      "Epic lifecycle states:",
-      "  open        \u2192 resolving \u2192 merge_ready \u2192 merged",
-      "  (any)       \u2192 failed / abandoned (terminal)",
+      "Epic readiness:",
+      "  status reflects derived readiness from live chain state",
+      "  persisted epic state is compatibility metadata only",
       "",
       "Merge behavior:",
-      "  - Requires epic state: resolving or merge_ready",
+      "  - Requires derived readiness: ready chains only",
       "  - All chain jobs must be terminal before publication",
       "  - Chains merged in topological dependency order",
       "  - Use --pr to publish via pull request instead of direct merge",
@@ -35547,13 +35961,13 @@ async function handleEpicCommand(argv) {
       "Examples:",
       "  specialists epic list",
       "  specialists epic list --unresolved --json",
-      "  specialists epic resolve unitAI-3f7b",
       "  specialists epic status unitAI-3f7b --json",
       "  specialists epic sync unitAI-3f7b",
       "  specialists epic sync unitAI-3f7b --apply",
       '  specialists epic abandon unitAI-3f7b --reason "scope changed"',
       "  specialists epic merge unitAI-3f7b --rebuild",
       "  specialists epic merge unitAI-3f7b --pr",
+      "  specialists epic merge unitAI-3f7b --target-branch feature/foo",
       ""
     ].join(`
 `));
@@ -35563,10 +35977,6 @@ async function handleEpicCommand(argv) {
     await handleEpicListCommand(argv.slice(1));
     return;
   }
-  if (subcommand === "resolve") {
-    await handleEpicResolveCommand(argv.slice(1));
-    return;
-  }
   if (subcommand === "sync") {
     await handleEpicSyncCommand(argv.slice(1));
     return;
@@ -35584,7 +35994,7 @@ async function handleEpicCommand(argv) {
     return;
   }
   console.error(`Unknown epic subcommand: ${subcommand}`);
-  console.error("Usage: specialists epic <list|status|resolve|sync|abandon|merge>");
+  console.error("Usage: specialists epic <list|status|sync|abandon|merge>");
   process.exit(1);
 }
 var RUNNING_STATUSES;
@@ -35598,7 +36008,7 @@ var init_epic = __esm(() => {
 
 // src/cli/version-check.ts
 import { spawnSync as spawnSync16 } from "child_process";
-import { existsSync as existsSync20, mkdirSync as mkdirSync10, readFileSync as readFileSync20, writeFileSync as writeFileSync9 } from "fs";
+import { existsSync as existsSync21, mkdirSync as mkdirSync10, readFileSync as readFileSync20, writeFileSync as writeFileSync10 } from "fs";
 import { dirname as dirname9, join as join22 } from "path";
 import { createRequire as createRequire3 } from "module";
 function readBundledPackageVersion(requireFn = require3) {
@@ -35621,7 +36031,7 @@ function shouldRunVersionCheck() {
   return true;
 }
 function readCache() {
-  if (!existsSync20(CACHE_PATH))
+  if (!existsSync21(CACHE_PATH))
     return null;
   try {
     return JSON.parse(readFileSync20(CACHE_PATH, "utf8"));
@@ -35634,7 +36044,7 @@ function readCachedVersionCheck() {
 }
 function writeCache(cache) {
   mkdirSync10(dirname9(CACHE_PATH), { recursive: true });
-  writeFileSync9(CACHE_PATH, `${JSON.stringify(cache, null, 2)}
+  writeFileSync10(CACHE_PATH, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
 function isFresh(cache) {
@@ -35731,7 +36141,7 @@ __export(exports_status, {
   detectJobOutputMode: () => detectJobOutputMode
 });
 import { spawnSync as spawnSync17 } from "child_process";
-import { existsSync as existsSync21, readFileSync as readFileSync21 } from "fs";
+import { existsSync as existsSync22, readFileSync as readFileSync21 } from "fs";
 import { join as join23 } from "path";
 function ok2(msg) {
   console.log(`  ${green8("\u2713")} ${msg}`);
@@ -35830,7 +36240,7 @@ function countJobEvents(sqliteClient, jobsDir, jobId) {
     return 0;
   }
   const eventsFile = join23(jobsDir, jobId, "events.jsonl");
-  if (!existsSync21(eventsFile))
+  if (!existsSync22(eventsFile))
     return 0;
   const raw = readFileSync21(eventsFile, "utf-8").trim();
   if (!raw)
@@ -35867,7 +36277,7 @@ function getLatestContextSnapshot(sqliteClient, jobsDir, jobId) {
     return null;
   }
   const eventsFile = join23(jobsDir, jobId, "events.jsonl");
-  if (!existsSync21(eventsFile))
+  if (!existsSync22(eventsFile))
     return null;
   const lines = readFileSync21(eventsFile, "utf-8").split(`
 `);
@@ -35974,12 +36384,12 @@ async function run15() {
 `).slice(1).map((line) => line.split(/\s+/)[0]).filter(Boolean)) : new Set;
     const bdInstalled = isInstalled2("bd");
     const bdVersion = bdInstalled ? cmd("bd", ["--version"]) : null;
-    const beadsPresent = existsSync21(join23(process.cwd(), ".beads"));
+    const beadsPresent = existsSync22(join23(process.cwd(), ".beads"));
     const specialistsBin = cmd("which", ["specialists"]);
     const jobsDir = resolveJobsDir();
     const jobFileOutputMode = detectJobFileOutputMode();
     let jobs = [];
-    if (existsSync21(jobsDir)) {
+    if (existsSync22(jobsDir)) {
       supervisor = new Supervisor({
         runner: null,
         runOptions: null,
@@ -36145,14 +36555,346 @@ var init_status = __esm(() => {
   init_version_check();
 });
 
+// src/specialist/process-health.ts
+import { existsSync as existsSync23, readdirSync as readdirSync9, readFileSync as readFileSync22, readlinkSync as readlinkSync2 } from "fs";
+import { join as join24 } from "path";
+function parseThreshold(raw, fallback) {
+  if (!raw)
+    return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0)
+    return fallback;
+  return parsed;
+}
+function getProcessHealthThresholds(env = process.env) {
+  const warnPct = parseThreshold(env.SPECIALISTS_HEALTH_WARN_PCT, DEFAULT_WARN_PCT);
+  const refusePct = parseThreshold(env.SPECIALISTS_HEALTH_REFUSE_PCT, DEFAULT_REFUSE_PCT);
+  return { warnPct, refusePct };
+}
+function readMemAvailableBytes(meminfoPath) {
+  try {
+    const content = readFileSync22(meminfoPath, "utf-8");
+    const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(content);
+    if (!match)
+      return 0;
+    return Number(match[1]) * 1024;
+  } catch {
+    return 0;
+  }
+}
+function readProcStringOrNull(path) {
+  try {
+    return readFileSync22(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function readProcCwdOrNull(pid, procRoot) {
+  try {
+    return readlinkSync2(join24(procRoot, String(pid), "cwd"));
+  } catch {
+    return null;
+  }
+}
+function parseStat(stat2) {
+  const closeParen = stat2.lastIndexOf(")");
+  if (closeParen < 0)
+    return null;
+  const fields = stat2.slice(closeParen + 2).trim().replace(/\s+/g, " ").split(" ");
+  const ppid = Number(fields[1]);
+  const utimeTicks = Number(fields[11]);
+  const stimeTicks = Number(fields[12]);
+  const startTimeTicks = Number(fields[19]);
+  if (![ppid, utimeTicks, stimeTicks, startTimeTicks].every(Number.isFinite))
+    return null;
+  return { ppid, utimeTicks, stimeTicks, startTimeTicks };
+}
+function readProcUptimeSecondsOrNull(procRoot) {
+  try {
+    const match = /^(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)$/.exec(readFileSync22(join24(procRoot, "uptime"), "utf-8").trim());
+    if (!match)
+      return null;
+    return Number(match[1]);
+  } catch {
+    return null;
+  }
+}
+function readProcessLiveness(pid, procRoot) {
+  if (!existsSync23(join24(procRoot, String(pid))))
+    return "dead";
+  try {
+    process.kill(pid, 0);
+    return "alive";
+  } catch (error2) {
+    if (error2 instanceof Error && "code" in error2 && error2.code === "ESRCH")
+      return "dead";
+    return "alive";
+  }
+}
+function readProcessSnapshot(pid, procRoot, uptimeSeconds) {
+  const basePath = join24(procRoot, String(pid));
+  const cmdlineRaw = readProcStringOrNull(join24(basePath, "cmdline"));
+  if (!cmdlineRaw)
+    return null;
+  const cmdline = cmdlineRaw.replace(/\0/g, " ").trim();
+  if (!cmdline)
+    return null;
+  const comm = (readProcStringOrNull(join24(basePath, "comm")) ?? "").trim();
+  const stat2 = readProcStringOrNull(join24(basePath, "stat"));
+  const parsedStat = stat2 ? parseStat(stat2) : null;
+  if (!parsedStat)
+    return null;
+  const status = readProcStringOrNull(join24(basePath, "status")) ?? "";
+  const rssMatch = /VmRSS:\s+(\d+)\s+kB/m.exec(status);
+  const rssBytes = rssMatch ? Number(rssMatch[1]) * 1024 : 0;
+  const cwd = readProcCwdOrNull(pid, procRoot);
+  const cpuSeconds = (parsedStat.utimeTicks + parsedStat.stimeTicks) / CLOCK_TICKS_PER_SECOND;
+  const ageSeconds = Math.max(0, uptimeSeconds - parsedStat.startTimeTicks / CLOCK_TICKS_PER_SECOND);
+  const cpuPct = ageSeconds > 0 ? cpuSeconds / ageSeconds * 100 : 0;
+  return { pid, ppid: parsedStat.ppid, cmdline, comm, cwd, rssBytes, cpuPct, ageSeconds };
+}
+function listPids(procRoot) {
+  if (!existsSync23(procRoot))
+    return [];
+  const pids = [];
+  for (const entry of readdirSync9(procRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory())
+      continue;
+    const pid = Number(entry.name);
+    if (Number.isInteger(pid) && pid > 0)
+      pids.push(pid);
+  }
+  return pids;
+}
+function getWorktreeFromCwd(cwd) {
+  if (!cwd)
+    return null;
+  const marker = "/.worktrees/";
+  const index = cwd.indexOf(marker);
+  if (index < 0)
+    return null;
+  const tail = cwd.slice(index + marker.length);
+  const slash = tail.indexOf("/");
+  return cwd.slice(0, index + marker.length + (slash < 0 ? tail.length : slash));
+}
+function basename6(command) {
+  return command.split("/").pop() ?? command;
+}
+function isShellWrapper(command) {
+  return ["sh", "bash", "zsh", "fish"].includes(basename6(command));
+}
+function isSpecialistRunCommand(cmdline) {
+  const tokens = cmdline.split(/\s+/).filter(Boolean);
+  if (tokens.length === 0 || isShellWrapper(tokens[0]))
+    return false;
+  const commandIndex = tokens.findIndex((token) => ["specialists", "sp"].includes(basename6(token)));
+  return commandIndex >= 0 && tokens[commandIndex + 1] === "run";
+}
+function isPiAgentProcess(snapshot) {
+  return snapshot.cmdline.includes("pi-coding-agent");
+}
+function isPiOrphanCandidate(snapshot) {
+  return snapshot.comm === "pi" || isPiAgentProcess(snapshot);
+}
+function isDeletedCwdToolProcess(snapshot) {
+  if (!snapshot.cwd?.includes("(deleted)"))
+    return false;
+  return isPiOrphanCandidate(snapshot) || isSpecialistRunCommand(snapshot.cmdline) || snapshot.cmdline.includes("gitnexus") || snapshot.cmdline.includes("serena") || snapshot.cmdline.includes("tsserver");
+}
+function classifyProcess(snapshot) {
+  const { cmdline, ppid } = snapshot;
+  if (cmdline.includes("dolt sql-server"))
+    return "dolt";
+  if (cmdline.includes("serena") && (cmdline.includes("language-server") || cmdline.includes("lsp")))
+    return "serena-lsp";
+  if (isDeletedCwdToolProcess(snapshot))
+    return "orphan";
+  if ((isPiOrphanCandidate(snapshot) || cmdline.includes("gitnexus") && cmdline.includes("mcp")) && ppid === 1)
+    return "orphan";
+  if (isPiAgentProcess(snapshot) || isSpecialistRunCommand(cmdline))
+    return "specialist";
+  return null;
+}
+function getOrphanReason(snapshot) {
+  if (snapshot.cmdline.includes("dolt sql-server"))
+    return "dolt-worktree-local";
+  if (isDeletedCwdToolProcess(snapshot))
+    return "deleted-worktree-process";
+  if (snapshot.cmdline.includes("gitnexus") && snapshot.cmdline.includes("mcp") && snapshot.ppid === 1)
+    return "gitnexus-orphan";
+  if (isPiOrphanCandidate(snapshot) && snapshot.ppid === 1)
+    return "pi-orphan";
+  return null;
+}
+function toProcessHealthProcess(snapshot, kind) {
+  return {
+    pid: snapshot.pid,
+    ppid: snapshot.ppid,
+    kind,
+    role: kind,
+    cmdline: snapshot.cmdline,
+    cwd: snapshot.cwd,
+    rssBytes: snapshot.rssBytes,
+    cpuPct: snapshot.cpuPct,
+    ageSeconds: snapshot.ageSeconds,
+    worktree: getWorktreeFromCwd(snapshot.cwd)
+  };
+}
+function collectProcessHealth(options = {}) {
+  const procRoot = options.procRoot ?? "/proc";
+  const meminfoPath = options.meminfoPath ?? "/proc/meminfo";
+  const uptimeSeconds = readProcUptimeSecondsOrNull(procRoot) ?? (options.nowMs ?? Date.now()) / 1000;
+  const thresholds = getProcessHealthThresholds();
+  const memAvailableBytes = readMemAvailableBytes(meminfoPath);
+  const processes = [];
+  for (const pid of listPids(procRoot)) {
+    const snapshot = readProcessSnapshot(pid, procRoot, uptimeSeconds);
+    if (!snapshot)
+      continue;
+    const kind = classifyProcess(snapshot);
+    if (!kind)
+      continue;
+    const process3 = toProcessHealthProcess(snapshot, kind);
+    if (kind === "orphan")
+      process3.reason = getOrphanReason(snapshot) ?? undefined;
+    processes.push(process3);
+  }
+  const specialistProcesses = processes.filter((process3) => process3.kind === "specialist");
+  const doltProcesses = processes.filter((process3) => process3.kind === "dolt");
+  const serenaProcesses = processes.filter((process3) => process3.kind === "serena-lsp");
+  const orphanProcesses = processes.filter((process3) => process3.kind === "orphan");
+  const serenaMap = new Map;
+  for (const process3 of serenaProcesses) {
+    const workspace = process3.worktree ?? process3.cwd ?? "unknown";
+    if (!serenaMap.has(workspace))
+      serenaMap.set(workspace, []);
+    serenaMap.get(workspace).push(process3);
+  }
+  const warnLimitBytes = Math.floor(memAvailableBytes * (thresholds.warnPct / 100));
+  const refuseLimitBytes = Math.floor(memAvailableBytes * (thresholds.refusePct / 100));
+  const totalRssBytes = processes.reduce((sum, process3) => sum + process3.rssBytes, 0);
+  const totalCpuPct = processes.reduce((sum, process3) => sum + process3.cpuPct, 0);
+  const thresholdPct = memAvailableBytes > 0 ? totalRssBytes / memAvailableBytes * 100 : 0;
+  const statusReasons = [];
+  if (thresholdPct >= thresholds.refusePct)
+    statusReasons.push(`rss >= refuse threshold (${thresholds.refusePct}%)`);
+  else if (thresholdPct >= thresholds.warnPct)
+    statusReasons.push(`rss >= warn threshold (${thresholds.warnPct}%)`);
+  if (doltProcesses.length > 1)
+    statusReasons.push(`dolt sql-server count ${doltProcesses.length} > expected 1`);
+  if (orphanProcesses.length > 0)
+    statusReasons.push(`orphan process count ${orphanProcesses.length} > 0`);
+  const status = thresholdPct >= thresholds.refusePct ? "REFUSE" : statusReasons.length > 0 ? "WARN" : "OK";
+  return {
+    status,
+    statusReasons,
+    memAvailableBytes,
+    totalRssBytes,
+    totalCpuPct,
+    specialistCount: specialistProcesses.length,
+    doltCount: doltProcesses.length,
+    serenaLspCount: serenaProcesses.length,
+    orphanCount: orphanProcesses.length,
+    thresholdPct,
+    warnPct: thresholds.warnPct,
+    refusePct: thresholds.refusePct,
+    warnLimitBytes,
+    refuseLimitBytes,
+    specialistProcesses,
+    doltProcesses,
+    serenaWorkspaces: [...serenaMap.entries()].map(([workspace, workspaceProcesses]) => ({
+      workspace,
+      count: workspaceProcesses.length,
+      rssBytes: workspaceProcesses.reduce((sum, process3) => sum + process3.rssBytes, 0),
+      processes: workspaceProcesses
+    })).sort((left, right) => right.rssBytes - left.rssBytes),
+    orphanProcesses
+  };
+}
+function withReason(process3, reason) {
+  return { ...process3, reason };
+}
+function hasDeletedCwd(process3) {
+  return Boolean(process3.cwd?.includes("(deleted)"));
+}
+function collectOrphanProcesses(options = {}) {
+  const health = collectProcessHealth(options);
+  const reaped = new Map;
+  for (const process3 of health.orphanProcesses)
+    reaped.set(process3.pid, process3);
+  for (const process3 of health.doltProcesses) {
+    if (hasDeletedCwd(process3))
+      reaped.set(process3.pid, withReason(process3, "dolt-worktree-local"));
+  }
+  for (const process3 of health.specialistProcesses) {
+    if (hasDeletedCwd(process3))
+      reaped.set(process3.pid, withReason(process3, "deleted-worktree-process"));
+  }
+  for (const workspace of health.serenaWorkspaces) {
+    for (const process3 of workspace.processes) {
+      if (hasDeletedCwd(process3))
+        reaped.set(process3.pid, withReason(process3, "deleted-worktree-process"));
+    }
+  }
+  return [...reaped.values()].sort((left, right) => left.pid - right.pid);
+}
+function collectStaleSpecialistJobs(options = {}) {
+  const procRoot = options.procRoot ?? "/proc";
+  const nowMs = options.nowMs ?? Date.now();
+  const minKeepAliveAgeMs = options.minKeepAliveAgeMs ?? 30 * 60 * 1000;
+  const observabilityClient = options.observabilityClient ?? createObservabilitySqliteClient();
+  const statuses = observabilityClient?.listStatuses() ?? [];
+  const staleStatuses = statuses.filter((status) => ["starting", "running", "waiting"].includes(status.status));
+  const uptimeSeconds = readProcUptimeSecondsOrNull(procRoot) ?? nowMs / 1000;
+  const candidates = [];
+  for (const status of staleStatuses) {
+    const pid = status.pid;
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+      continue;
+    const ageMs = Math.max(0, nowMs - (status.updated_at_ms ?? nowMs));
+    const snapshot = readProcessSnapshot(pid, procRoot, uptimeSeconds);
+    if (!snapshot) {
+      if (readProcessLiveness(pid, procRoot) === "dead" && ageMs >= minKeepAliveAgeMs) {
+        candidates.push({ jobId: status.id, pid, beadId: status.bead_id ?? null, specialist: status.specialist, cwd: null, ageMs, reason: "dead-pid" });
+        continue;
+      }
+      const basePath = join24(procRoot, String(pid));
+      const cmdlineRaw = readProcStringOrNull(join24(basePath, "cmdline"));
+      const statRaw = readProcStringOrNull(join24(basePath, "stat"));
+      const parsedStat = statRaw ? parseStat(statRaw) : null;
+      if (status.status === "waiting" && parsedStat?.ppid === 1 && cmdlineRaw && isSpecialistRunCommand(cmdlineRaw.replace(/\0/g, " "))) {
+        candidates.push({ jobId: status.id, pid, beadId: status.bead_id ?? null, specialist: status.specialist, cwd: readProcCwdOrNull(pid, procRoot), ageMs, reason: "orphaned-keep-alive" });
+      }
+      continue;
+    }
+    if (status.status === "waiting" && snapshot.ppid === 1 && isSpecialistRunCommand(snapshot.cmdline) && ageMs >= minKeepAliveAgeMs) {
+      candidates.push({ jobId: status.id, pid, beadId: status.bead_id ?? null, specialist: status.specialist, cwd: snapshot.cwd, ageMs, reason: "orphaned-keep-alive" });
+      continue;
+    }
+    if (status.status !== "running" && status.status !== "waiting")
+      continue;
+    if (ageMs < minKeepAliveAgeMs)
+      continue;
+    const lastActivityMs = observabilityClient?.getLastActivityTimestampMs?.(status.id) ?? null;
+    if (lastActivityMs !== null && nowMs - lastActivityMs < minKeepAliveAgeMs)
+      continue;
+    candidates.push({ jobId: status.id, pid, beadId: status.bead_id ?? null, specialist: status.specialist, cwd: snapshot.cwd, ageMs, reason: "dead-toolchain" });
+  }
+  return candidates.sort((left, right) => left.pid - right.pid);
+}
+var DEFAULT_WARN_PCT = 70, DEFAULT_REFUSE_PCT = 85, CLOCK_TICKS_PER_SECOND = 100;
+var init_process_health = __esm(() => {
+  init_observability_sqlite();
+});
+
 // src/cli/ps.ts
 var exports_ps = {};
 __export(exports_ps, {
   run: () => run16
 });
 import { spawnSync as spawnSync18 } from "child_process";
-import { existsSync as existsSync22, readdirSync as readdirSync8, readFileSync as readFileSync22 } from "fs";
-import { join as join24 } from "path";
+import { existsSync as existsSync24, readdirSync as readdirSync10, readFileSync as readFileSync23 } from "fs";
+import { join as join25 } from "path";
 function loadBeadIdsForCurrentUser() {
   const ids = new Set;
   try {
@@ -36182,12 +36924,30 @@ function parseSinceArg(value) {
   return Date.now() - ms;
 }
 function parseArgs8(argv) {
+  const allowedBooleanFlags = new Set([
+    "--json",
+    "--all",
+    "--follow",
+    "-f",
+    "--include-terminal",
+    "--include-merged",
+    "--include-cleaned",
+    "--active",
+    "--running",
+    "--mine",
+    "--health"
+  ]);
+  const valueFlags = new Set(["--node", "--bead", "--since"]);
   let nodeId;
   let beadFilter;
   let sinceMs;
   const positional = [];
   for (let i = 0;i < argv.length; i += 1) {
     const token = argv[i];
+    if (token.startsWith("-") && !allowedBooleanFlags.has(token) && !valueFlags.has(token)) {
+      const hint = token === "--ps" ? " Did you mean `sp clean --ps`?" : "";
+      throw new Error(`Unknown ps option: ${token}.${hint}`);
+    }
     if (token === "--node" && argv[i + 1]) {
       nodeId = argv[i + 1];
       i += 1;
@@ -36213,39 +36973,44 @@ function parseArgs8(argv) {
     all: argv.includes("--all"),
     follow: argv.includes("--follow") || argv.includes("-f"),
     includeTerminal,
-    running: argv.includes("--running"),
+    includeCleaned: argv.includes("--include-cleaned"),
+    active: argv.includes("--active"),
+    running: argv.includes("--running") || argv.includes("--active"),
     mine: argv.includes("--mine"),
+    health: argv.includes("--health"),
     beadFilter,
     sinceMs,
     nodeId,
     inspectId: positional[0]
   };
 }
-function isVisibleStatus(status, all) {
-  if (all)
-    return true;
-  return ACTIVE_STATES.includes(status);
+function isPsCleaned(job) {
+  const typed = job;
+  return Boolean(typed.ps_hidden_at ?? typed.ps_hidden_from_dashboard_at);
+}
+function isDefaultActionableTerminal(job) {
+  return job.status === "error" || job.status === "cancelled";
 }
 function readStatusesFromFiles(jobsDir) {
-  if (!existsSync22(jobsDir))
+  if (!existsSync24(jobsDir))
     return [];
   const statuses = [];
-  for (const entry of readdirSync8(jobsDir)) {
-    const statusPath = join24(jobsDir, entry, "status.json");
-    if (!existsSync22(statusPath))
+  for (const entry of readdirSync10(jobsDir)) {
+    const statusPath = join25(jobsDir, entry, "status.json");
+    if (!existsSync24(statusPath))
       continue;
     try {
-      statuses.push(JSON.parse(readFileSync22(statusPath, "utf-8")));
+      statuses.push(JSON.parse(readFileSync23(statusPath, "utf-8")));
     } catch {}
   }
   return statuses.sort((a, b) => b.started_at_ms - a.started_at_ms);
 }
 function readLastToolEventFromFile(jobsDir, jobId) {
-  const eventsPath = join24(jobsDir, jobId, "events.jsonl");
-  if (!existsSync22(eventsPath))
+  const eventsPath = join25(jobsDir, jobId, "events.jsonl");
+  if (!existsSync24(eventsPath))
     return;
   try {
-    const lines = readFileSync22(eventsPath, "utf-8").split(`
+    const lines = readFileSync23(eventsPath, "utf-8").split(`
 `);
     for (let index = lines.length - 1;index >= 0; index -= 1) {
       const line = lines[index]?.trim();
@@ -36536,7 +37301,7 @@ function statusLabel(status) {
 }
 function epicStateLabel(state) {
   if (state === "merge_ready")
-    return green8("merge_ready");
+    return green8("pass");
   if (state === "merged")
     return dim8("merged");
   if (state === "failed")
@@ -36544,10 +37309,10 @@ function epicStateLabel(state) {
   if (state === "blocked")
     return yellow10("blocked");
   if (state === "resolving")
-    return cyan5("resolving");
+    return cyan5("merge_ready");
   if (state === "abandoned")
     return dim8("abandoned");
-  return magenta3("unresolved");
+  return magenta3("no pass yet");
 }
 function withPidLiveness(statuses) {
   return statuses.map((job) => ({
@@ -36704,6 +37469,50 @@ function renderTreeNodes(nodes, beadTitles, prefix, renderedJobIds) {
     }
   }
 }
+function formatProcessRow(process3) {
+  const cwd = process3.cwd ?? "--";
+  const rssMb = `${(process3.rssBytes / (1024 * 1024)).toFixed(1)}MB`;
+  const cpu = `${process3.cpuPct.toFixed(1)}%`;
+  const age = `${Math.floor(process3.ageSeconds / 60)}m`;
+  return `  ${String(process3.pid).padEnd(7)} ${process3.role.padEnd(14)} ${rssMb.padEnd(8)} ${cpu.padEnd(7)} ${age.padEnd(5)} ${cwd}`;
+}
+function renderProcessHealthBlock(report, includeDetails) {
+  const percent = report.thresholdPct.toFixed(1);
+  const severity = report.status === "REFUSE" ? red2("REFUSE") : report.status === "WARN" ? yellow10("WARN") : green8("OK");
+  console.log(bold10(cyan5("System health")));
+  console.log(`  ${severity} rss=${(report.totalRssBytes / (1024 * 1024)).toFixed(1)}MB avail=${(report.memAvailableBytes / (1024 * 1024)).toFixed(1)}MB used=${percent}% warn=${report.warnPct}% refuse=${report.refusePct}% cpu=${report.totalCpuPct.toFixed(1)}%`);
+  console.log(`  specialists=${report.specialistCount} dolt=${report.doltCount} serena-lsp=${report.serenaLspCount} orphans=${report.orphanCount}`);
+  if (report.statusReasons.length > 0)
+    console.log(`  alerts=${report.statusReasons.join("; ")}`);
+  if (!includeDetails) {
+    console.log("");
+    return;
+  }
+  if (report.doltProcesses.length > 0) {
+    console.log(bold10("  Dolt sql-server"));
+    for (const process3 of report.doltProcesses)
+      console.log(formatProcessRow(process3));
+  }
+  if (report.serenaWorkspaces.length > 0) {
+    console.log(bold10("  Serena LSP"));
+    for (const workspace of report.serenaWorkspaces) {
+      console.log(`  ${workspace.workspace} \xB7 ${workspace.count} procs \xB7 ${(workspace.rssBytes / (1024 * 1024)).toFixed(1)}MB`);
+      for (const process3 of workspace.processes)
+        console.log(formatProcessRow(process3));
+    }
+  }
+  if (report.specialistProcesses.length > 0) {
+    console.log(bold10("  Specialists"));
+    for (const process3 of report.specialistProcesses)
+      console.log(formatProcessRow(process3));
+  }
+  if (report.orphanProcesses.length > 0) {
+    console.log(bold10("  Orphans"));
+    for (const process3 of report.orphanProcesses)
+      console.log(formatProcessRow(process3));
+  }
+  console.log("");
+}
 function resolveEpicReadinessMap(jobs, includeTerminal) {
   const epicIds = new Set(jobs.map((job) => job.epic_id).filter((epicId) => Boolean(epicId)));
   const sqlite = createObservabilitySqliteClient();
@@ -36730,12 +37539,12 @@ function resolveEpicReadinessMap(jobs, includeTerminal) {
     sqlite.close();
   }
 }
-function renderHuman(jobs, nodes, trees, all, includeTerminal, epicReadiness) {
+function renderHuman(jobs, nodes, trees, all, includeTerminal, epicReadiness, health, includeHealthDetails) {
   const beadTitles = buildBeadTitleCache(jobs);
   const renderedJobIds = new Set;
   const epicGroups = buildEpicGroups(jobs, epicReadiness);
   const renderedEpicIds = new Set(epicGroups.map((epic) => epic.epic_id));
-  console.log("");
+  renderProcessHealthBlock(health, includeHealthDetails);
   for (const epic of epicGroups) {
     const prepCount = epic.prep_jobs.length;
     const chainCount = epic.chains.length;
@@ -36744,9 +37553,9 @@ function renderHuman(jobs, nodes, trees, all, includeTerminal, epicReadiness) {
     const persistedState = readiness?.persisted_state ?? "open";
     const prepSummary = readiness?.prep ? `prep ${readiness.prep.done}/${readiness.prep.total} done${readiness.prep.running > 0 ? ` ${readiness.prep.running} running` : ""}${readiness.prep.failed > 0 ? ` ${readiness.prep.failed} failed` : ""}` : `prep ${prepCount}`;
     const chainSummary = readiness?.chains ? `chains ${readiness.chains.filter((chain) => chain.state === "pass").length}/${readiness.chains.length} pass` : `chains ${chainCount}`;
-    const epicBanner = bold10(cyan5(`\u250F\u2501 EPIC ${epic.epic_id} \u2501 ${String(readinessState).toUpperCase()} \u2501 ${prepSummary} \u2501 ${chainSummary}`));
+    const epicBanner = bold10(cyan5(`\u250F\u2501 EPIC ${epic.epic_id} \u2501 ${epicStateLabel(readiness?.readiness_state)} \u2501 ${prepSummary} \u2501 ${chainSummary}`));
     console.log(epicBanner);
-    console.log(`  ${dim8(`state:${persistedState}`)} \xB7 ${epicStateLabel(readiness?.readiness_state)}`);
+    console.log(`  ${dim8(`derived:${readinessState}`)} \xB7 ${dim8(`stored:${persistedState}`)}`);
     console.log(`  ${bold10("Prep")}`);
     if (epic.prep_jobs.length === 0) {
       console.log(dim8("    (none)"));
@@ -36891,7 +37700,7 @@ ${job.id}  ${job.specialist}  ${getStatusIcon(toJobNode(job))} ${statusLabel(job
   console.log(`
   ${dim8(inspectActions.join(" | "))}`);
 }
-function renderJson(jobs, nodes, trees, _all, epicReadiness, args) {
+function renderJson(jobs, nodes, trees, _all, epicReadiness, args, health) {
   console.log(JSON.stringify({
     generated_at_ms: Date.now(),
     include_terminal: args.includeTerminal,
@@ -36929,7 +37738,8 @@ function renderJson(jobs, nodes, trees, _all, epicReadiness, args) {
     nodes,
     trees,
     epics: buildEpicGroups(jobs, epicReadiness),
-    epic_readiness: Object.fromEntries([...epicReadiness.entries()].map(([epicId, summary]) => [epicId, summary]))
+    epic_readiness: Object.fromEntries([...epicReadiness.entries()].map(([epicId, summary]) => [epicId, summary])),
+    process_health: health
   }, null, 2));
 }
 function dedupeStatusesById(statuses) {
@@ -36963,30 +37773,31 @@ function render(args) {
       return false;
     if (mineBeadIds && (!job.bead_id || !mineBeadIds.has(job.bead_id)))
       return false;
-    const epicTerminal = readinessState === "merged" || readinessState === "abandoned";
-    if (epicTerminal && !args.includeTerminal && !args.all)
-      return false;
+    const cleaned = isPsCleaned(job);
     if (args.all)
       return true;
-    if (job.is_dead)
+    if (cleaned && !args.includeCleaned)
       return false;
-    if (isVisibleStatus(job.status, false))
+    if (cleaned && args.includeCleaned && TERMINAL_STATES.includes(job.status))
       return true;
-    if (!job.epic_id)
-      return false;
-    if (!TERMINAL_STATES.includes(job.status))
+    if (job.is_dead)
       return false;
-    if (epicTerminal)
+    if (ACTIVE_STATES.includes(job.status))
+      return true;
+    if (args.active)
       return false;
-    return true;
+    if (args.includeTerminal && TERMINAL_STATES.includes(job.status))
+      return true;
+    return isDefaultActionableTerminal(job);
   });
   const nodes = groupByNode(visibleStatuses);
   const trees = groupByTree(visibleStatuses);
+  const health = collectProcessHealth();
   if (args.json) {
-    renderJson(visibleStatuses, nodes, trees, args.all, epicReadiness, args);
+    renderJson(visibleStatuses, nodes, trees, args.all, epicReadiness, args, health);
     return;
   }
-  renderHuman(visibleStatuses, nodes, trees, args.all, args.includeTerminal, epicReadiness);
+  renderHuman(visibleStatuses, nodes, trees, args.all, args.includeTerminal, epicReadiness, health, args.health);
 }
 function renderBuffered(args) {
   const lines = [];
@@ -37046,6 +37857,7 @@ var init_ps = __esm(() => {
   init_timeline_events();
   init_node_resolve();
   init_epic_readiness();
+  init_process_health();
   ACTIVE_STATES = ["starting", "running", "waiting"];
   TERMINAL_STATES = ["done", "error", "cancelled"];
   BEAD_TITLE_CACHE = new Map;
@@ -37064,8 +37876,8 @@ var exports_result = {};
 __export(exports_result, {
   run: () => run17
 });
-import { existsSync as existsSync23, readFileSync as readFileSync23 } from "fs";
-import { join as join25 } from "path";
+import { existsSync as existsSync25, readFileSync as readFileSync24 } from "fs";
+import { join as join26 } from "path";
 function parseArgs9(argv) {
   let jobId;
   let nodeId;
@@ -37155,10 +37967,10 @@ function readTimelineEventsForResult(sqliteClient, jobsDir, jobId) {
       return sqliteClient.readEvents(jobId);
     } catch {}
   }
-  const eventsPath = join25(jobsDir, jobId, "events.jsonl");
-  if (!existsSync23(eventsPath))
+  const eventsPath = join26(jobsDir, jobId, "events.jsonl");
+  if (!existsSync25(eventsPath))
     return [];
-  return readFileSync23(eventsPath, "utf-8").split(`
+  return readFileSync24(eventsPath, "utf-8").split(`
 `).map((line) => line.trim()).filter(Boolean).map((line) => parseTimelineEvent(line)).filter((event) => event !== null);
 }
 function deriveStartupSnapshot(status, events) {
@@ -37277,7 +38089,7 @@ async function run17() {
       error: error2
     }, null, 2));
   };
-  const jobsDir = join25(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join26(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const sqliteClient = createObservabilitySqliteClient();
   const emitHumanResult = (output2, status, startupContext, trailingFooter) => {
@@ -37312,7 +38124,7 @@ async function run17() {
       const resolvedNodeId = args.nodeId ? resolveNodeRefWithClient(args.nodeId, sqliteClient) : resolveSingleActiveNodeRef(sqliteClient);
       return resolveJobIdFromNodeMember(sqliteClient, resolvedNodeId, args.memberKey);
     })();
-    const resultPath = join25(jobsDir, jobId, "result.txt");
+    const resultPath = join26(jobsDir, jobId, "result.txt");
     const readResultOutput = () => {
       try {
         const sqliteResult = sqliteClient?.readResult(jobId) ?? null;
@@ -37321,8 +38133,8 @@ async function run17() {
       } catch (error2) {
         console.warn(`SQLite result read failed for job ${jobId}; falling back to result.txt`, error2);
       }
-      if (existsSync23(resultPath)) {
-        return readFileSync23(resultPath, "utf-8");
+      if (existsSync25(resultPath)) {
+        return readFileSync24(resultPath, "utf-8");
       }
       try {
         const events2 = readTimelineEventsForResult(sqliteClient, jobsDir, jobId);
@@ -37507,10 +38319,10 @@ var init_result = __esm(() => {
 });
 
 // src/specialist/timeline-query.ts
-import { existsSync as existsSync24, readdirSync as readdirSync9, readFileSync as readFileSync24 } from "fs";
-import { basename as basename6, join as join26 } from "path";
+import { existsSync as existsSync26, readdirSync as readdirSync11, readFileSync as readFileSync25 } from "fs";
+import { basename as basename7, join as join27 } from "path";
 function readJobEvents(jobDir) {
-  const jobId = basename6(jobDir);
+  const jobId = basename7(jobDir);
   try {
     const sqliteEvents = createObservabilitySqliteClient()?.readEvents(jobId) ?? [];
     if (sqliteEvents.length > 0) {
@@ -37520,10 +38332,10 @@ function readJobEvents(jobDir) {
   } catch {}
   if (process.env.SPECIALISTS_JOB_FILE_OUTPUT !== "on")
     return [];
-  const eventsPath = join26(jobDir, "events.jsonl");
-  if (!existsSync24(eventsPath))
+  const eventsPath = join27(jobDir, "events.jsonl");
+  if (!existsSync26(eventsPath))
     return [];
-  const content = readFileSync24(eventsPath, "utf-8");
+  const content = readFileSync25(eventsPath, "utf-8");
   const lines = content.split(`
 `).filter(Boolean);
   const events = [];
@@ -37535,9 +38347,21 @@ function readJobEvents(jobDir) {
   events.sort(compareTimelineEvents);
   return events;
 }
-function readAllJobEvents(jobsDir) {
+function readAllJobEvents(jobsDir, jobId) {
   const sqliteClient = createObservabilitySqliteClient();
   try {
+    if (jobId !== undefined && sqliteClient) {
+      const events = sqliteClient.readEvents(jobId);
+      if (events.length === 0)
+        return [];
+      const status = typeof sqliteClient.getStatus === "function" ? sqliteClient.getStatus(jobId) : undefined;
+      return [{
+        jobId,
+        specialist: status?.specialist ?? "unknown",
+        beadId: status?.bead_id,
+        events
+      }];
+    }
     const statuses = typeof sqliteClient?.listStatuses === "function" ? sqliteClient.listStatuses() : [];
     if (statuses.length > 0 && sqliteClient) {
       return statuses.flatMap((status) => {
@@ -37555,12 +38379,12 @@ function readAllJobEvents(jobsDir) {
   } catch {}
   if (process.env.SPECIALISTS_JOB_FILE_OUTPUT !== "on")
     return [];
-  if (!existsSync24(jobsDir))
+  if (!existsSync26(jobsDir))
     return [];
   const batches = [];
-  const entries = readdirSync9(jobsDir);
+  const entries = readdirSync11(jobsDir);
   for (const entry of entries) {
-    const jobDir = join26(jobsDir, entry);
+    const jobDir = join27(jobsDir, entry);
     try {
       const stat2 = __require("fs").statSync(jobDir);
       if (!stat2.isDirectory())
@@ -37568,20 +38392,20 @@ function readAllJobEvents(jobsDir) {
     } catch {
       continue;
     }
-    const jobId = entry;
-    const statusPath = join26(jobDir, "status.json");
+    const jobId2 = entry;
+    const statusPath = join27(jobDir, "status.json");
     let specialist = "unknown";
     let beadId;
-    if (existsSync24(statusPath)) {
+    if (existsSync26(statusPath)) {
       try {
-        const status = JSON.parse(readFileSync24(statusPath, "utf-8"));
+        const status = JSON.parse(readFileSync25(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 });
+      batches.push({ jobId: jobId2, specialist, beadId, events });
     }
   }
   return batches;
@@ -37626,14 +38450,9 @@ function filterTimelineEvents(merged, filter) {
   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);
+  const batches = readAllJobEvents(jobsDir, filter.jobId);
+  const filteredBatches = filter.specialist !== undefined ? batches.filter((b) => b.specialist === filter.specialist) : batches;
+  const merged = mergeTimelineEvents(filteredBatches);
   return filterTimelineEvents(merged, filter);
 }
 var init_timeline_query = __esm(() => {
@@ -37671,13 +38490,13 @@ __export(exports_feed, {
 });
 import {
   closeSync as closeSync2,
-  existsSync as existsSync25,
+  existsSync as existsSync27,
   openSync as openSync3,
-  readFileSync as readFileSync25,
-  readdirSync as readdirSync10,
-  statSync as statSync3
+  readFileSync as readFileSync26,
+  readdirSync as readdirSync12,
+  statSync as statSync4
 } from "fs";
-import { join as join27 } from "path";
+import { join as join28 } from "path";
 function getHumanEventKey(event) {
   switch (event.type) {
     case "meta":
@@ -37839,7 +38658,7 @@ function readFileFresh(filePath) {
   let fd = null;
   try {
     fd = openSync3(filePath, "r");
-    return readFileSync25(fd, "utf-8");
+    return readFileSync26(fd, "utf-8");
   } catch {
     return null;
   } finally {
@@ -37856,7 +38675,7 @@ function readStatusJson(sqliteClient, jobsDir, jobId) {
   } catch (error2) {
     console.warn(`SQLite status read failed for job ${jobId}; falling back to status.json`, error2);
   }
-  const statusPath = join27(jobsDir, jobId, "status.json");
+  const statusPath = join28(jobsDir, jobId, "status.json");
   const raw = readFileFresh(statusPath);
   if (!raw)
     return null;
@@ -37866,13 +38685,15 @@ function readStatusJson(sqliteClient, jobsDir, jobId) {
     return null;
   }
 }
-function isTerminalJobStatus(sqliteClient, jobsDir, jobId) {
-  const status = readStatusJson(sqliteClient, jobsDir, jobId);
-  return status?.status === "done" || status?.status === "error" || status?.status === "cancelled";
-}
 function isKeepAliveJobStatus(status) {
   return status?.status === "waiting";
 }
+function isTerminalStatus(status) {
+  return status?.status === "done" || status?.status === "error" || status?.status === "cancelled";
+}
+function isTerminalEquivalentForFollow(status, isGlobalFollow) {
+  return isTerminalStatus(status ?? null) || isGlobalFollow && isKeepAliveJobStatus(status ?? null);
+}
 function isJobCompleteForFollow(sqliteClient, jobsDir, jobId, events) {
   const status = readStatusJson(sqliteClient, jobsDir, jobId);
   if (isKeepAliveJobStatus(status)) {
@@ -37978,8 +38799,13 @@ function parseArgs10(argv) {
 }
 function printSnapshot(sqliteClient, merged, options, jobsDir) {
   if (merged.length === 0) {
-    if (!options.json)
-      console.log(dim8("No events found."));
+    if (!options.json) {
+      if (options.jobId && sqliteClient) {
+        console.log(dim8(`job ${options.jobId} not found in .specialists/db/observability.db`));
+      } else {
+        console.log(dim8("No events found."));
+      }
+    }
     return;
   }
   const colorMap = new JobColorMap;
@@ -38065,13 +38891,13 @@ function filterMergedEventsByNode(sqliteClient, jobsDir, merged, nodeId) {
   });
 }
 function listMatchingJobIds(sqliteClient, jobsDir, options) {
-  if (!existsSync25(jobsDir))
+  if (!existsSync27(jobsDir))
     return [];
   const jobIds = [];
-  for (const entry of readdirSync10(jobsDir)) {
-    const jobDir = join27(jobsDir, entry);
+  for (const entry of readdirSync12(jobsDir)) {
+    const jobDir = join28(jobsDir, entry);
     try {
-      if (!statSync3(jobDir).isDirectory())
+      if (!statSync4(jobDir).isDirectory())
         continue;
     } catch {
       continue;
@@ -38106,7 +38932,7 @@ function readJobEventsFresh(sqliteClient, jobsDir, jobId) {
   } catch (error2) {
     console.warn(`SQLite events read failed for job ${jobId}; falling back to events.jsonl`, error2);
   }
-  const eventsPath = join27(jobsDir, jobId, "events.jsonl");
+  const eventsPath = join28(jobsDir, jobId, "events.jsonl");
   const content = readFileFresh(eventsPath);
   if (!content)
     return [];
@@ -38130,10 +38956,10 @@ function readJobEventsIncremental(sqliteClient, jobsDir, jobId, afterSeq, fileCa
   } catch (error2) {
     console.warn(`SQLite incremental events read failed for job ${jobId}; falling back to events.jsonl`, error2);
   }
-  const eventsPath = join27(jobsDir, jobId, "events.jsonl");
+  const eventsPath = join28(jobsDir, jobId, "events.jsonl");
   let stats;
   try {
-    stats = statSync3(eventsPath);
+    stats = statSync4(eventsPath);
   } catch {
     return [];
   }
@@ -38167,7 +38993,11 @@ async function followMerged(sqliteClient, jobsDir, options) {
   const fileEventCache = new Map;
   const initialMatchingJobIds = listMatchingJobIds(sqliteClient, jobsDir, options);
   const hasInitialMatchingJobs = initialMatchingJobIds.length > 0;
-  const trackedJobs = new Set(initialMatchingJobIds.filter((jobId) => !isTerminalJobStatus(sqliteClient, jobsDir, jobId)));
+  const isGlobalFollow = options.jobId === undefined;
+  const trackedJobs = new Set(initialMatchingJobIds.filter((jobId) => {
+    const status = readStatusJson(sqliteClient, jobsDir, jobId);
+    return !isTerminalStatus(status) && !(isGlobalFollow && isKeepAliveJobStatus(status));
+  }));
   const completedJobs = new Set;
   const filteredBatches = () => readFilteredBatchesFresh(sqliteClient, jobsDir, options);
   const initial = filterMergedEventsByCursor(filterMergedEventsByNode(sqliteClient, jobsDir, queryTimeline(jobsDir, {
@@ -38213,14 +39043,11 @@ async function followMerged(sqliteClient, jobsDir, options) {
       for (const jobId of currentJobIds) {
         const status = readStatusJson(sqliteClient, jobsDir, jobId);
         statusByJobId.set(jobId, status);
-        const isTerminal2 = status?.status === "done" || status?.status === "error" || status?.status === "cancelled";
-        if (!isKeepAliveJobStatus(status) && isTerminal2) {
+        if (isTerminalEquivalentForFollow(status, isGlobalFollow)) {
           completedJobs.add(jobId);
           continue;
         }
-        if (!isTerminal2) {
-          trackedJobs.add(jobId);
-        }
+        trackedJobs.add(jobId);
       }
       const newEvents = [];
       for (const jobId of currentJobIds) {
@@ -38240,8 +39067,7 @@ async function followMerged(sqliteClient, jobsDir, options) {
           if (isKeepAliveJobStatus(status ?? null)) {
             continue;
           }
-          const isTerminal2 = status?.status === "done" || status?.status === "error" || status?.status === "cancelled";
-          if (events.some(isRunCompleteEvent) || isTerminal2) {
+          if (events.some(isRunCompleteEvent) || isTerminalStatus(status ?? null) || isGlobalFollow && isKeepAliveJobStatus(status ?? null)) {
             completedJobs.add(jobId);
           }
         }
@@ -38290,7 +39116,7 @@ async function followMerged(sqliteClient, jobsDir, options) {
       if (!options.forever && trackedJobs.size > 0) {
         const allTrackedTerminal = [...trackedJobs].every((jobId) => {
           const status = statusByJobId.get(jobId) ?? readStatusJson(sqliteClient, jobsDir, jobId);
-          return status?.status === "done" || status?.status === "error" || status?.status === "cancelled";
+          return isTerminalEquivalentForFollow(status, isGlobalFollow);
         });
         if (completedJobs.size === trackedJobs.size || allTrackedTerminal) {
           clearInterval(interval);
@@ -38304,9 +39130,13 @@ async function run18() {
   const options = parseArgs10(process.argv.slice(3));
   const sqliteClient = createObservabilitySqliteClient();
   try {
-    const jobsDir = join27(process.cwd(), ".specialists", "jobs");
-    if (!existsSync25(jobsDir)) {
-      console.log(dim8("No jobs directory found."));
+    const jobsDir = join28(process.cwd(), ".specialists", "jobs");
+    if (!existsSync27(jobsDir)) {
+      if (options.jobId && sqliteClient) {
+        console.log(dim8(`job ${options.jobId} not found in .specialists/db/observability.db`));
+      } else {
+        console.log(dim8("No jobs directory found."));
+      }
       return;
     }
     const resolvedOptions = {
@@ -38344,7 +39174,7 @@ var exports_steer = {};
 __export(exports_steer, {
   run: () => run19
 });
-import { writeFileSync as writeFileSync10 } from "fs";
+import { writeFileSync as writeFileSync11 } from "fs";
 async function run19() {
   const jobId = process.argv[3];
   const message = process.argv[4];
@@ -38375,7 +39205,7 @@ async function run19() {
     try {
       const payload = JSON.stringify({ type: "steer", message }) + `
 `;
-      writeFileSync10(status.fifo_path, payload, { flag: "a" });
+      writeFileSync11(status.fifo_path, payload, { flag: "a" });
       process.stdout.write(`${green10("\u2713")} Steer message sent to job ${jobId}
 `);
     } catch (err) {
@@ -38398,7 +39228,7 @@ var exports_resume = {};
 __export(exports_resume, {
   run: () => run20
 });
-import { writeFileSync as writeFileSync11 } from "fs";
+import { writeFileSync as writeFileSync12 } from "fs";
 async function run20() {
   const jobId = process.argv[3];
   const task = process.argv[4];
@@ -38415,9 +39245,9 @@ async function run20() {
       process.exit(1);
     }
     if (status.status !== "waiting") {
-      process.stderr.write(`${red5("Error:")} Job ${jobId} is not in waiting state (status: ${status.status}).
+      process.stderr.write(`${red5("Error:")} Job ${jobId} is already finalized (${status.status}).
 `);
-      process.stderr.write(`resume is only valid for keep-alive jobs in waiting state. Use steer for running jobs.
+      process.stderr.write(`resume only works for true waiting jobs. Finalized work is terminal; use sp ps to inspect chain state.
 `);
       process.exit(1);
     }
@@ -38429,7 +39259,7 @@ async function run20() {
     try {
       const payload = JSON.stringify({ type: "resume", task }) + `
 `;
-      writeFileSync11(status.fifo_path, payload, { flag: "a" });
+      writeFileSync12(status.fifo_path, payload, { flag: "a" });
       process.stdout.write(`${green11("\u2713")} Resume sent to job ${jobId}
 `);
       process.stdout.write(`  Use 'specialists feed ${jobId} --follow' to watch the response.
@@ -38461,15 +39291,15 @@ async function run21() {
 }
 
 // src/specialist/worktree-gc.ts
-import { existsSync as existsSync26, readdirSync as readdirSync11, readFileSync as readFileSync26 } from "fs";
-import { join as join28 } from "path";
+import { existsSync as existsSync28, readdirSync as readdirSync13, readFileSync as readFileSync27 } from "fs";
+import { join as join29 } from "path";
 import { spawnSync as spawnSync19 } from "child_process";
 function readJobStatus2(jobDir) {
-  const statusPath = join28(jobDir, "status.json");
-  if (!existsSync26(statusPath))
+  const statusPath = join29(jobDir, "status.json");
+  if (!existsSync28(statusPath))
     return null;
   try {
-    return JSON.parse(readFileSync26(statusPath, "utf-8"));
+    return JSON.parse(readFileSync27(statusPath, "utf-8"));
   } catch {
     return null;
   }
@@ -38491,7 +39321,7 @@ function collectWorktreeGcCandidates(jobsDir) {
       const worktreePath = status.worktree_path;
       if (!worktreePath)
         return null;
-      if (!existsSync26(worktreePath))
+      if (!existsSync28(worktreePath))
         return null;
       return {
         jobId: status.id,
@@ -38503,13 +39333,13 @@ function collectWorktreeGcCandidates(jobsDir) {
   }
   if (!getFileFallbackEnabled())
     return [];
-  if (!existsSync26(jobsDir))
+  if (!existsSync28(jobsDir))
     return [];
   const candidates = [];
-  for (const entry of readdirSync11(jobsDir, { withFileTypes: true })) {
+  for (const entry of readdirSync13(jobsDir, { withFileTypes: true })) {
     if (!entry.isDirectory())
       continue;
-    const status = readJobStatus2(join28(jobsDir, entry.name));
+    const status = readJobStatus2(join29(jobsDir, entry.name));
     if (!status)
       continue;
     if (isActive(status.status))
@@ -38519,7 +39349,7 @@ function collectWorktreeGcCandidates(jobsDir) {
     const { worktree_path: worktreePath, branch } = status;
     if (!worktreePath)
       continue;
-    if (!existsSync26(worktreePath))
+    if (!existsSync28(worktreePath))
       continue;
     candidates.push({
       jobId: status.id,
@@ -38565,8 +39395,32 @@ var exports_clean = {};
 __export(exports_clean, {
   run: () => run22
 });
-import { existsSync as existsSync27, readFileSync as readFileSync27, readdirSync as readdirSync12, rmSync as rmSync3, statSync as statSync4 } from "fs";
-import { join as join29 } from "path";
+import { existsSync as existsSync29, readFileSync as readFileSync28, readdirSync as readdirSync14, rmSync as rmSync4, statSync as statSync5 } from "fs";
+import { join as join30 } from "path";
+function parseDuration2(raw) {
+  const match = /^(\d+)(ms|s|m|h|d)$/i.exec(raw.trim());
+  if (!match)
+    return null;
+  const amount = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const multipliers = {
+    ms: 1,
+    s: 1000,
+    m: 60000,
+    h: 3600000,
+    d: 86400000
+  };
+  return amount * multipliers[unit];
+}
+function parseBeforeArgument2(raw) {
+  const durationMs = parseDuration2(raw);
+  if (durationMs !== null)
+    return Date.now() - durationMs;
+  const isoMs = Date.parse(raw);
+  if (Number.isFinite(isoMs))
+    return isoMs;
+  throw new Error(`Invalid --before value '${raw}'. Use ISO date or duration like 7d.`);
+}
 function parseTtlDaysFromEnvironment() {
   const rawValue = process.env.SPECIALISTS_JOB_TTL_DAYS ?? process.env.JOB_TTL_DAYS;
   if (!rawValue)
@@ -38583,6 +39437,11 @@ function parseOptions2(argv) {
   let aggressivePrune = false;
   let staleProcessesOnly = false;
   let staleAfterHours = DEFAULT_STALE_AFTER_HOURS;
+  let reapOrphans = false;
+  let psDashboard = false;
+  let observability = false;
+  let observabilityBeforeMs = null;
+  let includeEpics = false;
   for (let index = 0;index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === "--all") {
@@ -38597,6 +39456,34 @@ function parseOptions2(argv) {
       staleProcessesOnly = true;
       continue;
     }
+    if (argument === "--reap-orphans") {
+      reapOrphans = true;
+      continue;
+    }
+    if (argument === "--ps") {
+      psDashboard = true;
+      continue;
+    }
+    if (argument === "--observability") {
+      observability = true;
+      continue;
+    }
+    if (argument === "--include-epics") {
+      includeEpics = true;
+      continue;
+    }
+    if (argument === "--before") {
+      const value = argv[index + 1];
+      if (!value)
+        throw new Error("Missing value for --before");
+      observabilityBeforeMs = parseBeforeArgument2(value);
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("--before=")) {
+      observabilityBeforeMs = parseBeforeArgument2(argument.slice("--before=".length));
+      continue;
+    }
     if (argument === "--aggressive-prune") {
       aggressivePrune = true;
       continue;
@@ -38644,20 +39531,35 @@ function parseOptions2(argv) {
   if (staleProcessesOnly && (removeAllCompleted || keepRecentCount !== null)) {
     throw new Error("--processes cannot be combined with --all or --keep");
   }
-  return { removeAllCompleted, dryRun, keepRecentCount, aggressivePrune, staleProcessesOnly, staleAfterHours };
+  if (reapOrphans && (removeAllCompleted || keepRecentCount !== null || staleProcessesOnly || psDashboard)) {
+    throw new Error("--reap-orphans cannot be combined with --all, --keep, --processes, or --ps");
+  }
+  if (psDashboard && (removeAllCompleted || keepRecentCount !== null || staleProcessesOnly || aggressivePrune || observability)) {
+    throw new Error("--ps cannot be combined with --all, --keep, --processes, --aggressive-prune, or --observability");
+  }
+  if (observability && (removeAllCompleted || keepRecentCount !== null || staleProcessesOnly || reapOrphans || psDashboard || aggressivePrune)) {
+    throw new Error("--observability cannot be combined with --all, --keep, --processes, --reap-orphans, --ps, or --aggressive-prune");
+  }
+  if (!observability && (observabilityBeforeMs !== null || includeEpics)) {
+    throw new Error("--before and --include-epics require --observability");
+  }
+  if (observability && observabilityBeforeMs === null) {
+    throw new Error("--observability requires --before <iso|duration>");
+  }
+  return { removeAllCompleted, dryRun, keepRecentCount, aggressivePrune, staleProcessesOnly, staleAfterHours, reapOrphans, psDashboard, observability, observabilityBeforeMs, includeEpics };
 }
 function readDirectorySizeBytes(directoryPath) {
   let totalBytes = 0;
-  for (const entry of readdirSync12(directoryPath, { withFileTypes: true })) {
-    const entryPath = join29(directoryPath, entry.name);
-    const stats = statSync4(entryPath);
+  for (const entry of readdirSync14(directoryPath, { withFileTypes: true })) {
+    const entryPath = join30(directoryPath, entry.name);
+    const stats = statSync5(entryPath);
     totalBytes += stats.isDirectory() ? readDirectorySizeBytes(entryPath) : stats.size;
   }
   return totalBytes;
 }
 function containsProtectedSqliteArtifact(directoryPath) {
-  for (const entry of readdirSync12(directoryPath, { withFileTypes: true })) {
-    const entryPath = join29(directoryPath, entry.name);
+  for (const entry of readdirSync14(directoryPath, { withFileTypes: true })) {
+    const entryPath = join30(directoryPath, entry.name);
     if (entry.isDirectory()) {
       if (containsProtectedSqliteArtifact(entryPath))
         return true;
@@ -38678,15 +39580,15 @@ function getJobTimestamps(status) {
 function readCompletedJobDirectory(baseDirectory, entry) {
   if (!entry.isDirectory())
     return null;
-  const directoryPath = join29(baseDirectory, entry.name);
+  const directoryPath = join30(baseDirectory, entry.name);
   if (containsProtectedSqliteArtifact(directoryPath))
     return null;
-  const statusFilePath = join29(directoryPath, "status.json");
-  if (!existsSync27(statusFilePath))
+  const statusFilePath = join30(directoryPath, "status.json");
+  if (!existsSync29(statusFilePath))
     return null;
   let statusData;
   try {
-    statusData = JSON.parse(readFileSync27(statusFilePath, "utf-8"));
+    statusData = JSON.parse(readFileSync28(statusFilePath, "utf-8"));
   } catch {
     return null;
   }
@@ -38700,8 +39602,8 @@ function collectCompletedJobs(jobsDirectoryPath) {
   const statuses = sqliteClient?.listStatuses() ?? [];
   if (statuses.length > 0) {
     return statuses.filter((status) => COMPLETED_STATUSES.has(status.status)).map((status) => {
-      const directoryPath = join29(jobsDirectoryPath, status.id);
-      if (!existsSync27(directoryPath) || containsProtectedSqliteArtifact(directoryPath))
+      const directoryPath = join30(jobsDirectoryPath, status.id);
+      if (!existsSync29(directoryPath) || containsProtectedSqliteArtifact(directoryPath))
         return null;
       const { createdAtMs, completedAtMs } = getJobTimestamps(status);
       return { id: status.id, directoryPath, completedAtMs, createdAtMs, sizeBytes: readDirectorySizeBytes(directoryPath) };
@@ -38709,7 +39611,7 @@ function collectCompletedJobs(jobsDirectoryPath) {
   }
   if (process.env.SPECIALISTS_JOB_FILE_OUTPUT !== "on")
     return [];
-  return readdirSync12(jobsDirectoryPath, { withFileTypes: true }).map((entry) => readCompletedJobDirectory(jobsDirectoryPath, entry)).filter((job) => job !== null);
+  return readdirSync14(jobsDirectoryPath, { withFileTypes: true }).map((entry) => readCompletedJobDirectory(jobsDirectoryPath, entry)).filter((job) => job !== null);
 }
 function selectJobsToRemove(completedJobs, options, protectedJobIds) {
   const jobsByNewest = [...completedJobs].sort((left, right) => {
@@ -38781,6 +39683,17 @@ function renderSummary(removedCount, freedBytes, dryRun) {
   const noun = removedCount === 1 ? "directory" : "directories";
   return `${action} ${removedCount} job ${noun} (${formatBytes2(freedBytes)} freed)`;
 }
+function printObservabilityPruneReport(report) {
+  console.log(report.dryRun ? "Would prune observability SQLite rows:" : "Pruned observability SQLite rows:");
+  console.log(`  before: ${new Date(report.beforeMs).toISOString()}`);
+  console.log(`  events cutoff: ${new Date(report.eventsCutoffMs).toISOString()}`);
+  console.log(`  specialist_events: ${report.deletedEvents}`);
+  console.log(`  specialist_results: ${report.deletedResults}`);
+  console.log(`  specialist_jobs: ${report.deletedJobs}`);
+  console.log(`  extracted jobs: ${report.extractedJobs}`);
+  console.log(`  epic_runs: ${report.deletedEpicRuns}${report.includeEpics ? "" : " (skipped, use --include-epics)"}`);
+  console.log(`  skipped active-chain jobs: ${report.skippedActiveChainJobs}`);
+}
 function printDryRunPlan(jobs) {
   if (jobs.length === 0)
     return;
@@ -38812,15 +39725,142 @@ function printWorktreeGcSummary(removed, skipped) {
 }
 function printUsageAndExit2(message) {
   console.error(message);
-  console.error("Usage: specialists|sp clean [--all] [--keep <n>] [--aggressive-prune] [--processes [--stale-after <hours>]] [--dry-run]");
+  console.error("Usage: specialists|sp clean [--all] [--keep <n>] [--aggressive-prune] [--processes [--stale-after <hours>]] [--reap-orphans] [--observability --before <iso|duration> [--include-epics]] [--dry-run]");
   process.exit(1);
 }
+function findOrphanProcesses() {
+  return collectOrphanProcesses().map((process3) => ({
+    pid: process3.pid,
+    ppid: process3.ppid,
+    comm: process3.cmdline.split(" ")[0] ?? process3.role,
+    cmdline: process3.cmdline,
+    cwd: process3.cwd,
+    reason: process3.reason ?? "pi-orphan"
+  }));
+}
+async function killOrphanProcesses(orphans, dryRun) {
+  if (dryRun)
+    return orphans.length;
+  let killed = 0;
+  for (const orphan of orphans) {
+    try {
+      process.kill(orphan.pid, "SIGTERM");
+    } catch {}
+  }
+  if (orphans.length > 0)
+    await new Promise((resolve11) => setTimeout(resolve11, 1500));
+  for (const orphan of orphans) {
+    try {
+      process.kill(orphan.pid, 0);
+      try {
+        process.kill(orphan.pid, "SIGKILL");
+      } catch {}
+    } catch {}
+    killed += 1;
+  }
+  return killed;
+}
+function printOrphanPlan(orphans) {
+  if (orphans.length === 0) {
+    console.log("No orphan/stale leaked processes found.");
+    return;
+  }
+  const action = "Would reap";
+  console.log(`${action} ${orphans.length} orphan/stale leaked process(es):`);
+  for (const orphan of orphans) {
+    const cwdSuffix = orphan.cwd ? ` cwd=${orphan.cwd}` : "";
+    console.log(`  - pid=${orphan.pid} ppid=${orphan.ppid} reason=${orphan.reason} comm=${orphan.comm}${cwdSuffix}`);
+  }
+}
+function printStaleJobPlan(jobs) {
+  if (jobs.length === 0) {
+    console.log("No stale specialist jobs found.");
+    return;
+  }
+  console.log(`Would reap ${jobs.length} stale specialist job(s):`);
+  for (const job of jobs) {
+    const ageMinutes = Math.round(job.ageMs / 60000);
+    const bead = job.beadId ? ` bead=${job.beadId}` : "";
+    const cwd = job.cwd ? ` cwd=${job.cwd}` : "";
+    console.log(`  - job=${job.jobId} pid=${job.pid}${bead} age=${ageMinutes}m reason=${job.reason}${cwd}`);
+  }
+}
+async function reapStaleSpecialistJobs(jobs, dryRun) {
+  const sqliteClient = createObservabilitySqliteClient();
+  if (!sqliteClient)
+    return 0;
+  if (dryRun)
+    return jobs.length;
+  let reapedCount = 0;
+  for (const job of jobs) {
+    if (job.reason === "orphaned-keep-alive") {
+      try {
+        process.kill(job.pid, "SIGTERM");
+      } catch {}
+      await new Promise((resolve11) => setTimeout(resolve11, 500));
+      try {
+        process.kill(job.pid, 0);
+        try {
+          process.kill(job.pid, "SIGKILL");
+        } catch {}
+      } catch {}
+    }
+    sqliteClient.markSpecialistJobCancelled(job.jobId, `cleanup: stale-reaper:${job.reason}`);
+    reapedCount += 1;
+  }
+  return reapedCount;
+}
+function printOrphanSummary(killedCount) {
+  if (killedCount === 0)
+    return;
+  const noun = killedCount === 1 ? "process" : "processes";
+  console.log(`Reaped ${killedCount} orphan/stale leaked ${noun}.`);
+}
+function printStaleJobSummary(reapedCount) {
+  const noun = reapedCount === 1 ? "job" : "jobs";
+  console.log(`Reaped ${reapedCount} stale specialist ${noun}.`);
+}
 function deleteJobDirectories(jobs) {
   for (const job of jobs) {
-    rmSync3(job.directoryPath, { recursive: true, force: true });
+    rmSync4(job.directoryPath, { recursive: true, force: true });
   }
   return jobs.length;
 }
+function isPsHidden(status) {
+  const typed = status;
+  return Boolean(typed.ps_hidden_at ?? typed.ps_hidden_from_dashboard_at);
+}
+function selectPsDashboardCleanCandidates(statuses) {
+  return statuses.filter((status) => COMPLETED_STATUSES.has(status.status) && !isPsHidden(status));
+}
+function printPsDashboardCleanPlan(statuses) {
+  if (statuses.length === 0) {
+    console.log("No terminal ps rows to hide.");
+    return;
+  }
+  console.log(`Would hide ${statuses.length} terminal row(s) from default ps:`);
+  for (const status of statuses) {
+    const bead = status.bead_id ? ` bead=${status.bead_id}` : "";
+    const branch = status.branch ? ` branch=${status.branch}` : "";
+    console.log(`  - ${status.id} ${status.specialist} status=${status.status}${bead}${branch}`);
+  }
+}
+function hidePsDashboardRows(statuses, dryRun) {
+  const sqliteClient = createObservabilitySqliteClient();
+  if (!sqliteClient)
+    return 0;
+  if (dryRun)
+    return statuses.length;
+  const now = Date.now();
+  for (const status of statuses) {
+    sqliteClient.upsertStatus({
+      ...status,
+      ps_hidden_at: now,
+      ps_hidden_reason: "sp clean --ps"
+    });
+  }
+  return statuses.length;
+}
 function removeStaleProcesses(statuses, dryRun) {
   const sqliteClient = createObservabilitySqliteClient();
   if (!sqliteClient)
@@ -38849,13 +39889,54 @@ async function run22() {
     const message = error2 instanceof Error ? error2.message : String(error2);
     printUsageAndExit2(message);
   }
-  const jobsDirectoryPath = resolveJobsDir();
-  if (!existsSync27(jobsDirectoryPath)) {
-    console.log("No jobs directory found.");
+  if (options.reapOrphans) {
+    const orphans = findOrphanProcesses();
+    const staleJobs = collectStaleSpecialistJobs();
+    if (options.dryRun) {
+      printOrphanPlan(orphans);
+      printStaleJobPlan(staleJobs);
+      return;
+    }
+    if (orphans.length === 0 && staleJobs.length === 0) {
+      console.log("No orphan/stale leaked processes found.");
+      return;
+    }
+    printOrphanPlan(orphans);
+    printStaleJobPlan(staleJobs);
+    const killedCount = await killOrphanProcesses(orphans, false);
+    const staleCount = await reapStaleSpecialistJobs(staleJobs, false);
+    printOrphanSummary(killedCount);
+    printStaleJobSummary(staleCount);
     return;
   }
+  const jobsDirectoryPath = resolveJobsDir();
   const sqliteClient = createObservabilitySqliteClient();
   const statuses = sqliteClient?.listStatuses() ?? [];
+  if (options.observability) {
+    if (!sqliteClient)
+      throw new Error("Failed to initialize observability SQLite schema. Run `specialists db setup` first.");
+    const report = sqliteClient.pruneObservabilityData({
+      beforeMs: options.observabilityBeforeMs,
+      includeEpics: options.includeEpics,
+      apply: !options.dryRun
+    });
+    printObservabilityPruneReport(report);
+    return;
+  }
+  if (options.psDashboard) {
+    const candidates = selectPsDashboardCleanCandidates(statuses);
+    if (options.dryRun) {
+      printPsDashboardCleanPlan(candidates);
+      return;
+    }
+    const hiddenCount = hidePsDashboardRows(candidates, false);
+    console.log(`Hid ${hiddenCount} terminal row(s) from default ps.`);
+    return;
+  }
+  if (!existsSync29(jobsDirectoryPath)) {
+    console.log("No jobs directory found.");
+    return;
+  }
   const worktreeCandidates = collectWorktreeGcCandidates(jobsDirectoryPath);
   const protectedJobIds = options.keepRecentCount !== null && !options.aggressivePrune && sqliteClient ? new Set(sqliteClient.listReferencedChainRootJobIds()) : new Set;
   if (options.staleProcessesOnly) {
@@ -38894,6 +39975,7 @@ var MS_PER_DAY = 86400000, DEFAULT_TTL_DAYS = 7, DEFAULT_STALE_AFTER_HOURS = 24,
 var init_clean = __esm(() => {
   init_job_root();
   init_observability_sqlite();
+  init_process_health();
   init_worktree_gc();
   COMPLETED_STATUSES = new Set(["done", "error", "cancelled"]);
   STALE_PROCESS_STATUSES = new Set(["running", "starting", "waiting"]);
@@ -39095,7 +40177,7 @@ async function run24() {
       process.exit(1);
     }
     if (status.status === "done" || status.status === "error" || status.status === "cancelled") {
-      process.stderr.write(`${dim11(`Job ${jobId} is already ${status.status}.`)}
+      process.stderr.write(`${dim11(`Job ${jobId} already finalized (${status.status}).`)}
 `);
       return;
     }
@@ -39183,21 +40265,127 @@ var init_stop = __esm(() => {
   init_tmux_utils();
 });
 
+// src/cli/finalize.ts
+var exports_finalize = {};
+__export(exports_finalize, {
+  run: () => run25
+});
+function createFinalizeSupervisor(jobsDir) {
+  const runner = {
+    run: async () => {
+      throw new Error("finalize supervisor runner is not used");
+    }
+  };
+  const runOptions = {};
+  return new Supervisor({ runner, runOptions, jobsDir });
+}
+function parseFinalizeArgs(argv) {
+  const jobId = argv.find((token) => !token.startsWith("-"));
+  return { jobId };
+}
+function findReviewerPassInChain(supervisor, chainId) {
+  const jobIds = supervisor.listChainJobIds(chainId);
+  for (const id of jobIds) {
+    const status = supervisor.readStatus(id);
+    if (!status || status.specialist !== "reviewer")
+      continue;
+    const output2 = supervisor.readResult(id) ?? "";
+    if (PASS_COMPLIANCE_VERDICT_REGEX2.test(output2)) {
+      return { reviewerJobId: id };
+    }
+  }
+  return null;
+}
+async function run25() {
+  const parsed = parseFinalizeArgs(process.argv.slice(3));
+  const jobId = parsed.jobId;
+  if (!jobId) {
+    console.error("Usage: specialists|sp finalize <job-id>");
+    process.exit(1);
+  }
+  const jobsDir = resolveJobsDir();
+  const supervisor = createFinalizeSupervisor(jobsDir);
+  try {
+    const status = supervisor.readStatus(jobId);
+    if (!status) {
+      console.error(`No job found: ${jobId}`);
+      process.exit(1);
+    }
+    const chainId = status.chain_id ?? status.chain_root_job_id;
+    if (!chainId) {
+      process.stderr.write(`${red7("Error:")} Job ${jobId} has no chain identity (chain_id missing).
+`);
+      process.exit(1);
+    }
+    const reviewerPass = findReviewerPassInChain(supervisor, chainId);
+    if (!reviewerPass) {
+      process.stderr.write(`${red7("Error:")} No reviewer with PASS compliance verdict found in chain ${chainId}.
+`);
+      process.stderr.write(`${dim12("finalize only closes keep-alive chains after reviewer PASS.")}
+`);
+      process.exit(1);
+    }
+    const chainJobIds = supervisor.listChainJobIds(chainId);
+    const finalized = [];
+    const skipped = [];
+    for (const id of chainJobIds) {
+      const memberStatus = supervisor.readStatus(id);
+      if (!memberStatus) {
+        skipped.push({ id, reason: "missing" });
+        continue;
+      }
+      if (memberStatus.status !== "waiting") {
+        skipped.push({ id, reason: memberStatus.status });
+        continue;
+      }
+      const result = supervisor.finalizeWaitingJob(id);
+      if (result) {
+        finalized.push(id);
+      } else {
+        skipped.push({ id, reason: "finalize-failed" });
+      }
+    }
+    if (finalized.length === 0) {
+      process.stderr.write(`${red7("Error:")} No waiting keep-alive jobs to finalize in chain ${chainId}.
+`);
+      process.exit(1);
+    }
+    process.stdout.write(`${green13("\u2713")} Finalized chain ${chainId} (reviewer PASS: ${reviewerPass.reviewerJobId})
+`);
+    for (const id of finalized) {
+      process.stdout.write(`  ${green13("\u2713")} ${id}
+`);
+    }
+    for (const { id, reason } of skipped) {
+      process.stdout.write(`  ${dim12(`\xB7 ${id} (${reason})`)}
+`);
+    }
+  } finally {
+    await supervisor.dispose();
+  }
+}
+var green13 = (s) => `\x1B[32m${s}\x1B[0m`, red7 = (s) => `\x1B[31m${s}\x1B[0m`, dim12 = (s) => `\x1B[2m${s}\x1B[0m`, PASS_COMPLIANCE_VERDICT_REGEX2;
+var init_finalize = __esm(() => {
+  init_supervisor();
+  init_job_root();
+  PASS_COMPLIANCE_VERDICT_REGEX2 = /## Compliance Verdict[\s\S]*?- Verdict:\s*\**\s*PASS\s*\**/i;
+});
+
 // src/cli/attach.ts
 var exports_attach = {};
 __export(exports_attach, {
-  run: () => run25
+  run: () => run26
 });
 import { execFileSync as execFileSync3, spawnSync as spawnSync21 } from "child_process";
-import { readFileSync as readFileSync28 } from "fs";
-import { join as join30 } from "path";
+import { readFileSync as readFileSync29 } from "fs";
+import { join as join31 } from "path";
 function exitWithError(message) {
   console.error(message);
   process.exit(1);
 }
 function readStatus(statusPath, jobId) {
   try {
-    return JSON.parse(readFileSync28(statusPath, "utf-8"));
+    return JSON.parse(readFileSync29(statusPath, "utf-8"));
   } catch (error2) {
     if (error2 && typeof error2 === "object" && "code" in error2 && error2.code === "ENOENT") {
       exitWithError(`Job \`${jobId}\` not found. Run \`specialists status\` to see active jobs in current mode.`);
@@ -39206,13 +40394,13 @@ function readStatus(statusPath, jobId) {
     exitWithError(`Failed to read status for job \`${jobId}\`: ${details}`);
   }
 }
-async function run25() {
+async function run26() {
   const [jobId] = process.argv.slice(3);
   if (!jobId) {
     exitWithError("Usage: specialists attach <job-id>  (normal runtime is DB-backed; job files are legacy/operator-only)");
   }
-  const jobsDir = join30(process.cwd(), ".specialists", "jobs");
-  const statusPath = join30(jobsDir, jobId, "status.json");
+  const jobsDir = join31(process.cwd(), ".specialists", "jobs");
+  const statusPath = join31(jobsDir, jobId, "status.json");
   const status = readStatus(statusPath, jobId);
   if (status.status === "done" || status.status === "error") {
     exitWithError(`Job \`${jobId}\` has already completed (status: ${status.status}). Use \`specialists result ${jobId}\` to read output.`);
@@ -39234,15 +40422,15 @@ async function run25() {
 var init_attach = () => {};
 
 // src/specialist/drift-detector.ts
-import { existsSync as existsSync28, readFileSync as readFileSync29, readdirSync as readdirSync13, rmSync as rmSync4 } from "fs";
-import { join as join31, resolve as resolve11, relative as relative3 } from "path";
+import { existsSync as existsSync30, readFileSync as readFileSync30, readdirSync as readdirSync15, rmSync as rmSync5 } from "fs";
+import { join as join32, resolve as resolve11, relative as relative3 } from "path";
 function listFiles(root) {
-  if (!existsSync28(root))
+  if (!existsSync30(root))
     return [];
   const out = [];
   const visit2 = (dir) => {
-    for (const entry of readdirSync13(dir, { withFileTypes: true })) {
-      const full = join31(dir, entry.name);
+    for (const entry of readdirSync15(dir, { withFileTypes: true })) {
+      const full = join32(dir, entry.name);
       if (entry.isDirectory()) {
         visit2(full);
         continue;
@@ -39277,14 +40465,14 @@ function detectDriftForRepo(repoRoot) {
       { scope: "user", dir: resolve11(repoRoot, ".specialists/user") }
     ];
     for (const { scope, dir } of scopes) {
-      if (!existsSync28(dir))
+      if (!existsSync30(dir))
         continue;
       for (const file of listFiles(dir)) {
         const rel = relPath(file, dir);
-        const canonicalPath = join31(asset.canonicalDir, rel);
-        if (!existsSync28(canonicalPath))
+        const canonicalPath = join32(asset.canonicalDir, rel);
+        if (!existsSync30(canonicalPath))
           continue;
-        const bytesEqual = readFileSync29(file).equals(readFileSync29(canonicalPath));
+        const bytesEqual = readFileSync30(file).equals(readFileSync30(canonicalPath));
         findings.push(makeFinding(repoRoot, asset.kind, scope, file, canonicalPath, bytesEqual));
       }
     }
@@ -39303,12 +40491,12 @@ function detectDriftUnderRoot(root) {
       repos.push({ root: dir, findings });
       return;
     }
-    for (const entry of readdirSync13(dir, { withFileTypes: true })) {
+    for (const entry of readdirSync15(dir, { withFileTypes: true })) {
       if (!entry.isDirectory())
         continue;
       if (entry.name === "node_modules" || entry.name === ".git")
         continue;
-      visit2(join31(dir, entry.name));
+      visit2(join32(dir, entry.name));
     }
   };
   visit2(resolve11(root));
@@ -39330,7 +40518,7 @@ function pruneStaleDefaults(repoRoot, dryRun) {
   const targets = detectDriftForRepo(repoRoot).filter((f) => f.scope === "default" && f.bytes_equal === true).map((f) => f.path);
   if (!dryRun) {
     for (const target of targets)
-      rmSync4(target, { recursive: true, force: true });
+      rmSync5(target, { recursive: true, force: true });
   }
   return targets;
 }
@@ -39348,7 +40536,7 @@ var init_drift_detector = __esm(() => {
 // src/cli/prune-stale-defaults.ts
 var exports_prune_stale_defaults = {};
 __export(exports_prune_stale_defaults, {
-  run: () => run26
+  run: () => run27
 });
 import { resolve as resolve12 } from "path";
 function parseArgs11(argv) {
@@ -39382,7 +40570,7 @@ function printHelp() {
   console.log("  --dry-run  List stale default snapshots without pruning");
   console.log("  --root     Repo root to scan");
 }
-async function run26(argv = process.argv.slice(3)) {
+async function run27(argv = process.argv.slice(3)) {
   const { dryRun, root, help } = parseArgs11(argv);
   if (help) {
     printHelp();
@@ -39409,33 +40597,39 @@ var init_prune_stale_defaults = __esm(() => {
 // src/cli/quickstart.ts
 var exports_quickstart = {};
 __export(exports_quickstart, {
-  run: () => run27
+  run: () => run28
 });
 function section2(title) {
   const bar = "\u2500".repeat(60);
   return `
 ${bold12(cyan7(title))}
-${dim12(bar)}`;
+${dim13(bar)}`;
 }
 function cmd2(s) {
   return yellow11(s);
 }
 function flag(s) {
-  return green13(s);
+  return green14(s);
 }
-async function run27() {
+async function run28() {
   const lines = [
     "",
     bold12("specialists  \xB7  Quick Start Guide"),
-    dim12("One MCP server. Multiple AI backends. Intelligent orchestration."),
-    dim12("Tip: sp is a shorter alias \u2014 sp run, sp list, sp feed etc. work identically."),
+    dim13("One MCP server. Multiple AI backends. Intelligent orchestration."),
+    dim13("Tip: sp is a shorter alias \u2014 sp run, sp list, sp feed etc. work identically."),
     ""
   ];
   lines.push(section2("1. Installation"));
   lines.push("");
+  lines.push(`  ${bold12("Prerequisite: Bun")}   ${cmd2("bun --version")}           # verify Bun >=1.0.0`);
+  lines.push(`  ${cmd2("curl -fsSL https://bun.sh/install | bash")}   # install Bun if missing`);
+  lines.push(`  ${cmd2("npm install -g xtrm-tools")}                 # install runtime prerequisite`);
+  lines.push(`  ${cmd2("xt install")}                               # install xtrm-managed assets`);
+  lines.push(`  ${cmd2("xt init")}                                  # initialize .xtrm/ in this repo`);
+  lines.push(`  ${dim13("sp list, sp doctor --check-drift, sp prune-stale-defaults are Category A and do NOT require xt or .xtrm/")}`);
   lines.push(`  ${cmd2("npm install -g @jaggerxtrm/specialists")}    # install globally`);
-  lines.push(`  ${cmd2("specialists init")}                         # project setup:`);
-  lines.push(`  ${dim12("                                            #   creates dirs, wires MCP + hooks, injects context")}`);
+  lines.push(`  ${cmd2("sp init")}                                  # project setup:`);
+  lines.push(`  ${dim13("                                            #   creates dirs, wires MCP + hooks, injects context")}`);
   lines.push("");
   lines.push(`  Verify everything is healthy:`);
   lines.push(`  ${cmd2("specialists status")}                        # shows pi, beads, MCP, active jobs`);
@@ -39443,13 +40637,14 @@ async function run27() {
   lines.push(section2("2. Initialize a Project"));
   lines.push("");
   lines.push(`  Run once per project root:`);
-  lines.push(`  ${cmd2("specialists init")}                          # creates .specialists/, wires MCP + AGENTS.md`);
+  lines.push(`  ${cmd2("sp init")}                                  # creates .specialists/, wires MCP + AGENTS.md`);
+  lines.push(`  ${dim13("  # requires xt init first so .xtrm/ already exists")}`);
   lines.push("");
   lines.push(`  What this creates:`);
-  lines.push(`  ${dim12(".specialists/default/")} \u2014 canonical specialists (from init)`);
-  lines.push(`  ${dim12(".specialists/user/")}    \u2014 custom .specialist.json files`);
-  lines.push(`  ${dim12(".specialists/jobs|ready")} \u2014 runtime data \u2014 gitignored`);
-  lines.push(`  ${dim12("AGENTS.md")}          \u2014 context block injected into Claude sessions`);
+  lines.push(`  ${dim13(".specialists/default/")} \u2014 canonical specialists (from init)`);
+  lines.push(`  ${dim13(".specialists/user/")}    \u2014 custom .specialist.json files`);
+  lines.push(`  ${dim13(".specialists/jobs|ready")} \u2014 runtime data \u2014 gitignored`);
+  lines.push(`  ${dim13("AGENTS.md")}          \u2014 context block injected into Claude sessions`);
   lines.push("");
   lines.push(section2("3. Discover Specialists"));
   lines.push("");
@@ -39466,17 +40661,17 @@ async function run27() {
   lines.push(section2("4. Running a Specialist"));
   lines.push("");
   lines.push(`  ${bold12("Foreground")} (streams output to stdout):`);
-  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--prompt")} ${dim12('"Review src/api.ts for security issues"')}`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--prompt")} ${dim13('"Review src/api.ts for security issues"')}`);
   lines.push("");
   lines.push(`  ${bold12("Tracked run")} (linked to a beads issue for workflow integration):`);
-  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--bead")} ${dim12("unitAI-abc")}`);
-  lines.push(`  ${dim12("  # uses bead description as prompt, tracks result in issue")}`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--bead")} ${dim13("unitAI-abc")}`);
+  lines.push(`  ${dim13("  # uses bead description as prompt, tracks result in issue")}`);
   lines.push("");
   lines.push(`  Override model for one run:`);
-  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--model")} ${dim12("anthropic/claude-opus-4-6")} ${flag("--prompt")} ${dim12('"..."')}`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--model")} ${dim13("anthropic/claude-opus-4-6")} ${flag("--prompt")} ${dim13('"..."')}`);
   lines.push("");
   lines.push(`  Run without beads issue tracking:`);
-  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--no-beads")} ${flag("--prompt")} ${dim12('"..."')}`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--no-beads")} ${flag("--prompt")} ${dim13('"..."')}`);
   lines.push("");
   lines.push(`  Pipe a prompt from stdin:`);
   lines.push(`  ${cmd2("cat my-brief.md | specialists run code-review")}`);
@@ -39484,7 +40679,7 @@ async function run27() {
   lines.push(section2("5. Async Job Lifecycle"));
   lines.push("");
   lines.push(`  ${bold12("MCP pattern")}: ${cmd2("use_specialist")} (foreground, returns result directly)`);
-  lines.push(`  ${bold12("CLI pattern")}: ${cmd2('specialists run <name> --prompt "..."')} prints ${dim12("[job started: <id>]")} to stderr`);
+  lines.push(`  ${bold12("CLI pattern")}: ${cmd2('specialists run <name> --prompt "..."')} prints ${dim13("[job started: <id>]")} to stderr`);
   lines.push(`  ${bold12("Shell pattern")}: ${cmd2('specialists run <name> --prompt "..." &')} for native backgrounding`);
   lines.push("");
   lines.push(`  ${bold12("Watch progress")} \u2014 stream events as they arrive:`);
@@ -39496,11 +40691,11 @@ async function run27() {
   lines.push("");
   lines.push(`  ${bold12("Steer a running job")} \u2014 redirect the agent mid-run without cancelling:`);
   lines.push(`  ${cmd2("specialists steer job_a1b2c3d4")} ${flag('"focus only on supervisor.ts"')}`);
-  lines.push(`  ${dim12("  # delivered after current tool calls finish, before the next LLM call")}`);
+  lines.push(`  ${dim13("  # delivered after current tool calls finish, before the next LLM call")}`);
   lines.push("");
   lines.push(`  ${bold12("Keep-alive multi-turn")} \u2014 start with ${flag("--keep-alive")}, then follow up:`);
   lines.push(`  ${cmd2("specialists run debugger")} ${flag("--bead unitAI-abc --keep-alive")}`);
-  lines.push(`  ${dim12("  # \u2192 status: waiting after first turn")}`);
+  lines.push(`  ${dim13("  # \u2192 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`);
@@ -39508,23 +40703,23 @@ async function run27() {
   lines.push(`  ${bold12("Cancel a job")}:`);
   lines.push(`  ${cmd2("specialists stop job_a1b2c3d4")}            # sends SIGTERM to the agent process`);
   lines.push("");
-  lines.push(`  ${bold12("Job files")} in ${dim12(".specialists/jobs/<job-id>/")}:`);
-  lines.push(`  ${dim12("status.json")}   \u2014 id, specialist, status, pid, started_at, elapsed_s, current_tool`);
-  lines.push(`  ${dim12("events.jsonl")} \u2014 one JSON event per line (tool_use, text, agent_end, error \u2026)`);
-  lines.push(`  ${dim12("result.txt")}    \u2014 final output (written when status=done)`);
-  lines.push(`  ${dim12("steer.pipe")}    \u2014 named FIFO for mid-run steering (removed on job completion)`);
+  lines.push(`  ${bold12("Job files")} in ${dim13(".specialists/jobs/<job-id>/")}:`);
+  lines.push(`  ${dim13("status.json")}   \u2014 id, specialist, status, pid, started_at, elapsed_s, current_tool`);
+  lines.push(`  ${dim13("events.jsonl")} \u2014 one JSON event per line (tool_use, text, agent_end, error \u2026)`);
+  lines.push(`  ${dim13("result.txt")}    \u2014 final output (written when status=done)`);
+  lines.push(`  ${dim13("steer.pipe")}    \u2014 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")} ${dim12("anthropic/claude-sonnet-4-6")}`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--description")} ${dim12('"Updated description"')}`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--timeout")} ${dim12("120000")}`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--permission")} ${dim12("HIGH")}`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--tags")} ${dim12("analysis,security,review")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim13("anthropic/claude-sonnet-4-6")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--description")} ${dim13('"Updated description"')}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--timeout")} ${dim13("120000")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--permission")} ${dim13("HIGH")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--tags")} ${dim13("analysis,security,review")}`);
   lines.push("");
   lines.push(`  Preview without writing:`);
-  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim12("...")} ${flag("--dry-run")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim13("...")} ${flag("--dry-run")}`);
   lines.push("");
   lines.push(section2("7. .specialist.json Schema"));
   lines.push("");
@@ -39571,12 +40766,12 @@ async function run27() {
     "    priority: 2                  # 0=critical \u2026 4=backlog"
   ];
   for (const l of schemaLines) {
-    lines.push(`  ${dim12(l)}`);
+    lines.push(`  ${dim13(l)}`);
   }
   lines.push("");
   lines.push(section2("8. Hook System"));
   lines.push("");
-  lines.push(`  Specialists emits lifecycle events to ${dim12(".specialists/trace.jsonl")}:`);
+  lines.push(`  Specialists emits lifecycle events to ${dim13(".specialists/trace.jsonl")}:`);
   lines.push("");
   lines.push(`  ${bold12("Hook point")}              ${bold12("When fired")}`);
   lines.push(`  ${yellow11("specialist:start")}       before the agent session begins`);
@@ -39585,7 +40780,7 @@ async function run27() {
   lines.push(`  ${yellow11("specialist:error")}       on failure or timeout`);
   lines.push("");
   lines.push(`  Each event line in trace.jsonl:`);
-  lines.push(`  ${dim12('{"t":"<ISO>","hook":"specialist:done","specialist":"code-review","durationMs":4120}')}`);
+  lines.push(`  ${dim13('{"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 .")}`);
@@ -39610,7 +40805,7 @@ async function run27() {
   lines.push("");
   lines.push(`  ${bold12("Tracked run with beads integration:")}`);
   lines.push(`  ${cmd2("specialists run deep-analysis --bead unitAI-abc")}`);
-  lines.push(`  ${dim12("  # prompt from bead, result tracked in bead")}`);
+  lines.push(`  ${dim13("  # prompt from bead, result tracked in bead")}`);
   lines.push("");
   lines.push(`  ${bold12("Steer a job mid-run:")}`);
   lines.push(`  ${cmd2('specialists steer <job-id> "focus only on the auth module"')}`);
@@ -39625,20 +40820,21 @@ async function run27() {
   lines.push(`  ${bold12("Override model for a single run:")}`);
   lines.push(`  ${cmd2('specialists run code-review --model anthropic/claude-opus-4-6 --prompt "..."')}`);
   lines.push("");
-  lines.push(dim12("\u2500".repeat(62)));
-  lines.push(`  ${dim12("specialists help")}     command list         ${dim12("specialists <cmd> --help")}   per-command flags`);
-  lines.push(`  ${dim12("specialists status")}   health check         ${dim12("specialists models")}         available models`);
+  lines.push(dim13("\u2500".repeat(62)));
+  lines.push(`  ${dim13("specialists help")}     command list         ${dim13("specialists <cmd> --help")}   per-command flags`);
+  lines.push(`  ${dim13("specialists status")}   health check         ${dim13("specialists models")}         available models`);
   lines.push("");
   console.log(lines.join(`
 `));
 }
-var bold12 = (s) => `\x1B[1m${s}\x1B[0m`, dim12 = (s) => `\x1B[2m${s}\x1B[0m`, yellow11 = (s) => `\x1B[33m${s}\x1B[0m`, cyan7 = (s) => `\x1B[36m${s}\x1B[0m`, blue4 = (s) => `\x1B[34m${s}\x1B[0m`, green13 = (s) => `\x1B[32m${s}\x1B[0m`;
+var bold12 = (s) => `\x1B[1m${s}\x1B[0m`, dim13 = (s) => `\x1B[2m${s}\x1B[0m`, yellow11 = (s) => `\x1B[33m${s}\x1B[0m`, cyan7 = (s) => `\x1B[36m${s}\x1B[0m`, blue4 = (s) => `\x1B[34m${s}\x1B[0m`, green14 = (s) => `\x1B[32m${s}\x1B[0m`;
 
 // src/cli/doctor.ts
 var exports_doctor = {};
 __export(exports_doctor, {
   setStatusError: () => setStatusError,
-  run: () => run28,
+  run: () => run29,
+  resolvePackageAssetDir: () => resolvePackageAssetDir,
   renderProcessSummary: () => renderProcessSummary,
   parseVersionTuple: () => parseVersionTuple,
   compareVersions: () => compareVersions2,
@@ -39646,22 +40842,22 @@ __export(exports_doctor, {
 });
 import { createHash as createHash5 } from "crypto";
 import { spawnSync as spawnSync22 } from "child_process";
-import { existsSync as existsSync29, lstatSync as lstatSync2, mkdirSync as mkdirSync11, readdirSync as readdirSync14, readFileSync as readFileSync30, readlinkSync as readlinkSync2, writeFileSync as writeFileSync12 } from "fs";
-import { dirname as dirname10, join as join32, relative as relative4, resolve as resolve13 } from "path";
+import { existsSync as existsSync31, lstatSync as lstatSync2, mkdirSync as mkdirSync11, readdirSync as readdirSync16, readFileSync as readFileSync31, readlinkSync as readlinkSync3, writeFileSync as writeFileSync13 } from "fs";
+import { dirname as dirname10, join as join33, relative as relative4, resolve as resolve13 } from "path";
 function ok3(msg) {
-  console.log(`  ${green14("\u2713")} ${msg}`);
+  console.log(`  ${green15("\u2713")} ${msg}`);
 }
 function warn3(msg) {
   console.log(`  ${yellow12("\u25CB")} ${msg}`);
 }
 function fail4(msg) {
-  console.log(`  ${red7("\u2717")} ${msg}`);
+  console.log(`  ${red8("\u2717")} ${msg}`);
 }
 function fix(msg) {
-  console.log(`    ${dim13("\u2192 fix:")} ${yellow12(msg)}`);
+  console.log(`    ${dim14("\u2192 fix:")} ${yellow12(msg)}`);
 }
 function hint(msg) {
-  console.log(`    ${dim13(msg)}`);
+  console.log(`    ${dim14(msg)}`);
 }
 function section3(label) {
   const line = "\u2500".repeat(Math.max(0, 38 - label.length));
@@ -39676,10 +40872,10 @@ function isInstalled3(bin) {
   return spawnSync22("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
 }
 function loadJson2(path) {
-  if (!existsSync29(path))
+  if (!existsSync31(path))
     return null;
   try {
-    return JSON.parse(readFileSync30(path, "utf8"));
+    return JSON.parse(readFileSync31(path, "utf8"));
   } catch {
     return null;
   }
@@ -39701,7 +40897,7 @@ function checkPi() {
     fix("pi config   (add at least one API key)");
     return false;
   }
-  ok3(`pi ${vStr}  \u2014  ${providers.size} provider${providers.size > 1 ? "s" : ""} active  ${dim13(`(${[...providers].join(", ")})`)}`);
+  ok3(`pi ${vStr}  \u2014  ${providers.size} provider${providers.size > 1 ? "s" : ""} active  ${dim14(`(${[...providers].join(", ")})`)}`);
   return true;
 }
 function checkSpAlias() {
@@ -39721,8 +40917,8 @@ function checkBd() {
     fix("install beads (bd) first");
     return false;
   }
-  ok3(`bd installed  ${dim13(sp("bd", ["--version"]).stdout || "")}`);
-  if (existsSync29(join32(CWD, ".beads")))
+  ok3(`bd installed  ${dim14(sp("bd", ["--version"]).stdout || "")}`);
+  if (existsSync31(join33(CWD, ".beads")))
     ok3(".beads/ present in project");
   else
     warn3(".beads/ not found in project");
@@ -39735,22 +40931,22 @@ function checkXt() {
     fix("install xtrm-tools first");
     return false;
   }
-  ok3(`xt installed  ${dim13(sp("xt", ["--version"]).stdout || "")}`);
+  ok3(`xt installed  ${dim14(sp("xt", ["--version"]).stdout || "")}`);
   return true;
 }
 function checkHooks() {
   section3("Claude Code hooks  (2 expected)");
   let allPresent = true;
   for (const name of HOOK_NAMES) {
-    const canonicalPath = join32(HOOKS_DIR, name);
-    if (!existsSync29(canonicalPath)) {
-      fail4(`${relative4(CWD, canonicalPath)}  ${red7("missing")}`);
+    const canonicalPath = join33(HOOKS_DIR, name);
+    if (!existsSync31(canonicalPath)) {
+      fail4(`${relative4(CWD, canonicalPath)}  ${red8("missing")}`);
       fix("specialists init");
       allPresent = false;
     } else {
       ok3(relative4(CWD, canonicalPath));
     }
-    const claudeHookPath = join32(CLAUDE_HOOKS_DIR, name);
+    const claudeHookPath = join33(CLAUDE_HOOKS_DIR, name);
     const symlinkState = isSymlinkTo(claudeHookPath, canonicalPath);
     if (symlinkState.ok) {
       ok3(`${relative4(CWD, claudeHookPath)} -> ${relative4(dirname10(claudeHookPath), canonicalPath)}`);
@@ -39825,14 +41021,14 @@ function checkVersion() {
 }
 function hashFile(path) {
   const hash = createHash5("sha256");
-  hash.update(readFileSync30(path));
+  hash.update(readFileSync31(path));
   return hash.digest("hex");
 }
 function collectFileHashes(rootDir) {
   const hashes = new Map;
   const visit2 = (dir) => {
-    for (const entry of readdirSync14(dir, { withFileTypes: true })) {
-      const fullPath = join32(dir, entry.name);
+    for (const entry of readdirSync16(dir, { withFileTypes: true })) {
+      const fullPath = join33(dir, entry.name);
       if (entry.isDirectory()) {
         visit2(fullPath);
         continue;
@@ -39843,12 +41039,12 @@ function collectFileHashes(rootDir) {
       hashes.set(relPath2, hashFile(fullPath));
     }
   };
-  if (existsSync29(rootDir))
+  if (existsSync31(rootDir))
     visit2(rootDir);
   return hashes;
 }
 function isSymlinkTo(linkPath, expectedTargetPath) {
-  if (!existsSync29(linkPath))
+  if (!existsSync31(linkPath))
     return { ok: false, reason: "missing" };
   let stats;
   try {
@@ -39859,7 +41055,7 @@ function isSymlinkTo(linkPath, expectedTargetPath) {
   if (!stats.isSymbolicLink())
     return { ok: false, reason: "not-symlink" };
   try {
-    const rawTarget = readlinkSync2(linkPath);
+    const rawTarget = readlinkSync3(linkPath);
     const resolvedTarget = resolve13(dirname10(linkPath), rawTarget);
     const resolvedExpected = resolve13(expectedTargetPath);
     if (resolvedTarget !== resolvedExpected) {
@@ -39870,19 +41066,23 @@ function isSymlinkTo(linkPath, expectedTargetPath) {
     return { ok: false, reason: "broken" };
   }
 }
+function resolvePackageAssetDir(relativePath) {
+  return resolveCanonicalAssetDir(relativePath) ?? (existsSync31(join33(CWD, "config", relativePath)) ? join33(CWD, "config", relativePath) : null);
+}
 function checkSkillDrift() {
-  section3("Skill drift  (.xtrm skill sync)");
-  if (!existsSync29(CONFIG_SKILLS_DIR)) {
-    fail4("config/skills/ missing");
-    fix("restore config/skills/ from git");
+  section3("Category A  package-live skill sync");
+  const canonicalSkillsDir = resolvePackageAssetDir("skills");
+  if (!canonicalSkillsDir) {
+    fail4("package canonical skills source missing");
+    fix("restore config/skills/ or install package assets");
     return false;
   }
-  if (!existsSync29(XTRM_DEFAULT_SKILLS_DIR)) {
+  if (!existsSync31(XTRM_DEFAULT_SKILLS_DIR)) {
     fail4(".xtrm/skills/default/ missing");
     fix("specialists init --sync-skills");
     return false;
   }
-  const canonicalHashes = collectFileHashes(CONFIG_SKILLS_DIR);
+  const canonicalHashes = collectFileHashes(canonicalSkillsDir);
   const defaultHashes = collectFileHashes(XTRM_DEFAULT_SKILLS_DIR);
   const drifted = [];
   const missingInDefault = [];
@@ -39901,10 +41101,10 @@ function checkSkillDrift() {
       extraInDefault.push(relPath2);
   }
   if (drifted.length === 0 && missingInDefault.length === 0 && extraInDefault.length === 0) {
-    ok3("config/skills/ and .xtrm/skills/default/ are in sync");
+    ok3(`${relative4(CWD, canonicalSkillsDir)} and .xtrm/skills/default/ are in sync`);
   } else {
     if (drifted.length > 0) {
-      fail4(`${drifted.length} drifted file${drifted.length === 1 ? "" : "s"} between config/skills and .xtrm/skills/default`);
+      fail4(`${drifted.length} drifted file${drifted.length === 1 ? "" : "s"} between ${relative4(CWD, canonicalSkillsDir)} and .xtrm/skills/default`);
       hint(`example: ${drifted.slice(0, 3).join(", ")}${drifted.length > 3 ? ", ..." : ""}`);
     }
     if (missingInDefault.length > 0) {
@@ -39917,39 +41117,47 @@ function checkSkillDrift() {
     }
     fix("specialists init --sync-skills");
   }
+  const defaultSkills = readdirSync16(XTRM_DEFAULT_SKILLS_DIR, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   let linksOk = true;
-  for (const scope of ["claude", "pi"]) {
-    const activeRoot = join32(XTRM_ACTIVE_SKILLS_DIR, scope);
-    if (!existsSync29(activeRoot)) {
-      fail4(`${relative4(CWD, activeRoot)}/ missing`);
-      fix("specialists init --sync-skills");
-      linksOk = false;
+  for (const skillName of defaultSkills) {
+    const activeLinkPath = join33(XTRM_ACTIVE_SKILLS_DIR, skillName);
+    const expectedTarget = join33(XTRM_DEFAULT_SKILLS_DIR, skillName);
+    const state = isSymlinkTo(activeLinkPath, expectedTarget);
+    if (state.ok)
       continue;
+    linksOk = false;
+    const relLink = relative4(CWD, activeLinkPath);
+    if (state.reason === "missing") {
+      fail4(`${relLink} missing`);
+    } else if (state.reason === "not-symlink") {
+      fail4(`${relLink} is not a symlink`);
+    } else if (state.reason === "wrong-target") {
+      fail4(`${relLink} points to ${state.target ?? "unknown target"}`);
+    } else {
+      fail4(`${relLink} is broken`);
     }
-    const defaultSkills = readdirSync14(XTRM_DEFAULT_SKILLS_DIR, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-    for (const skillName of defaultSkills) {
-      const activeLinkPath = join32(activeRoot, skillName);
-      const expectedTarget = join32(XTRM_DEFAULT_SKILLS_DIR, skillName);
-      const state = isSymlinkTo(activeLinkPath, expectedTarget);
-      if (state.ok)
-        continue;
-      linksOk = false;
-      const relLink = relative4(CWD, activeLinkPath);
-      if (state.reason === "missing") {
-        fail4(`${relLink} missing`);
-      } else if (state.reason === "not-symlink") {
-        fail4(`${relLink} is not a symlink`);
-      } else if (state.reason === "wrong-target") {
-        fail4(`${relLink} points to ${state.target ?? "unknown target"}`);
-      } else {
-        fail4(`${relLink} is broken`);
-      }
-      fix("specialists init --sync-skills");
+    fix("specialists init --sync-skills");
+  }
+  const legacyActiveRoots = [
+    { scope: "claude", root: join33(XTRM_ACTIVE_SKILLS_DIR, "claude") },
+    { scope: "pi", root: join33(XTRM_ACTIVE_SKILLS_DIR, "pi") }
+  ];
+  for (const { root } of legacyActiveRoots) {
+    if (!existsSync31(root))
+      continue;
+    if (isSymlinkTo(root, XTRM_ACTIVE_SKILLS_DIR).ok)
+      continue;
+    const relRoot = relative4(CWD, root);
+    if (lstatSync2(root).isDirectory()) {
+      warn3(`${relRoot}/ legacy scoped layout found`);
+    } else {
+      warn3(`${relRoot} legacy scoped layout found`);
     }
+    fix("specialists init --sync-skills");
   }
   const skillRootChecks = [
-    { root: join32(CLAUDE_DIR, "skills"), expected: ACTIVE_CLAUDE_SKILLS_DIR },
-    { root: join32(PI_DIR, "skills"), expected: ACTIVE_PI_SKILLS_DIR }
+    { root: join33(CLAUDE_DIR, "skills"), expected: XTRM_ACTIVE_SKILLS_DIR },
+    { root: join33(PI_DIR, "skills"), expected: XTRM_ACTIVE_SKILLS_DIR }
   ];
   let rootLinksOk = true;
   for (const check2 of skillRootChecks) {
@@ -39973,13 +41181,15 @@ function checkSkillDrift() {
   }
   return drifted.length === 0 && missingInDefault.length === 0 && linksOk && rootLinksOk;
 }
-function checkManagedMirror(label, sourceDir, mirrorDir, fixHint) {
-  if (!existsSync29(sourceDir)) {
-    warn3(`${label} source missing: ${relative4(CWD, sourceDir)}`);
+function checkManagedMirror(label, canonicalRelativePath, mirrorDir, fixHint) {
+  const sourceDir = resolvePackageAssetDir(canonicalRelativePath);
+  const sourceLabel = sourceDir ? relative4(CWD, sourceDir) : `package canonical ${canonicalRelativePath}`;
+  if (!sourceDir) {
+    warn3(`${label} source missing: package canonical ${canonicalRelativePath}`);
     fix(fixHint);
     return false;
   }
-  if (!existsSync29(mirrorDir)) {
+  if (!existsSync31(mirrorDir)) {
     fail4(`${label} mirror missing: ${relative4(CWD, mirrorDir)}`);
     fix(fixHint);
     return false;
@@ -39990,7 +41200,7 @@ function checkManagedMirror(label, sourceDir, mirrorDir, fixHint) {
   const missing = [...sourceHashes.keys()].filter((relPath2) => !mirrorHashes.has(relPath2));
   const extra = [...mirrorHashes.keys()].filter((relPath2) => !sourceHashes.has(relPath2));
   if (drifted.length === 0 && missing.length === 0 && extra.length === 0) {
-    ok3(`${label} mirror in sync`);
+    ok3(`${label} mirror in sync against ${sourceLabel}`);
     return true;
   }
   if (drifted.length > 0) {
@@ -40009,33 +41219,33 @@ function checkManagedMirror(label, sourceDir, mirrorDir, fixHint) {
   return false;
 }
 function checkManagedAssetMirrors() {
-  section3("Managed mirrors  (specialists / mandatory-rules / nodes)");
-  const specialistsOk = checkManagedMirror("specialists", CONFIG_SPECIALISTS_DIR, DEFAULT_SPECIALISTS_DIR, "specialists init --sync-defaults");
-  const rulesOk = checkManagedMirror("mandatory-rules", CONFIG_MANDATORY_RULES_DIR, join32(DEFAULT_SPECIALISTS_DIR, "mandatory-rules"), "specialists init --sync-defaults");
-  const nodesOk = checkManagedMirror("nodes", CONFIG_NODES_DIR, join32(DEFAULT_SPECIALISTS_DIR, "nodes"), "specialists init --sync-defaults");
+  section3("Category B  xtrm-managed asset mirrors");
+  const specialistsOk = checkManagedMirror("specialists", "specialists", DEFAULT_SPECIALISTS_DIR, "specialists init --sync-defaults");
+  const rulesOk = checkManagedMirror("mandatory-rules", "mandatory-rules", join33(DEFAULT_SPECIALISTS_DIR, "mandatory-rules"), "specialists init --sync-defaults");
+  const nodesOk = checkManagedMirror("nodes", "nodes", join33(DEFAULT_SPECIALISTS_DIR, "nodes"), "specialists init --sync-defaults");
   return specialistsOk && rulesOk && nodesOk;
 }
 function checkUserOverlayDrift() {
   section3("User specialist overlays");
-  if (!existsSync29(USER_SPECIALISTS_DIR)) {
+  if (!existsSync31(USER_SPECIALISTS_DIR)) {
     ok3("no user overlays present");
     return true;
   }
-  const overlays = readdirSync14(USER_SPECIALISTS_DIR).filter((name) => name.endsWith(".specialist.json"));
+  const overlays = readdirSync16(USER_SPECIALISTS_DIR).filter((name) => name.endsWith(".specialist.json"));
   if (overlays.length === 0) {
     ok3("no user overlays present");
     return true;
   }
   let allOk = true;
   for (const name of overlays) {
-    const userPath = join32(USER_SPECIALISTS_DIR, name);
-    const defaultPath = join32(DEFAULT_SPECIALISTS_DIR, name);
+    const userPath = join33(USER_SPECIALISTS_DIR, name);
+    const defaultPath = join33(DEFAULT_SPECIALISTS_DIR, name);
     const userSpec = loadJson2(userPath);
     if (!userSpec) {
       warn3(`${name}: failed to parse \u2014 skipping drift check`);
       continue;
     }
-    if (!existsSync29(defaultPath)) {
+    if (!existsSync31(defaultPath)) {
       ok3(`${name}: user-only overlay (no default to drift from)`);
       continue;
     }
@@ -40063,18 +41273,18 @@ function checkUserOverlayDrift() {
 }
 function checkRuntimeDirs() {
   section3(".specialists/ runtime directories");
-  const rootDir = join32(CWD, ".specialists");
-  const jobsDir = join32(rootDir, "jobs");
-  const readyDir = join32(rootDir, "ready");
+  const rootDir = join33(CWD, ".specialists");
+  const jobsDir = join33(rootDir, "jobs");
+  const readyDir = join33(rootDir, "ready");
   let allOk = true;
-  if (!existsSync29(rootDir)) {
+  if (!existsSync31(rootDir)) {
     warn3(".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 (!existsSync29(subDir)) {
+      if (!existsSync31(subDir)) {
         warn3(`.specialists/${label}/ missing \u2014 auto-creating`);
         mkdirSync11(subDir, { recursive: true });
         ok3(`.specialists/${label}/ created`);
@@ -40088,8 +41298,8 @@ function checkRuntimeDirs() {
 function checkClaudeMdFragments() {
   section3("CLAUDE.md fragments");
   const projectRoot = process.cwd();
-  const claudeMd = join32(projectRoot, "CLAUDE.md");
-  if (!existsSync29(claudeMd)) {
+  const claudeMd = join33(projectRoot, "CLAUDE.md");
+  if (!existsSync31(claudeMd)) {
     warn3("No CLAUDE.md in project root \u2014 skipping fragment check");
     return true;
   }
@@ -40215,10 +41425,10 @@ function compareVersions2(left, right) {
 }
 function setStatusError(statusPath) {
   try {
-    const raw = readFileSync30(statusPath, "utf8");
+    const raw = readFileSync31(statusPath, "utf8");
     const status = JSON.parse(raw);
     status.status = "error";
-    writeFileSync12(statusPath, `${JSON.stringify(status, null, 2)}
+    writeFileSync13(statusPath, `${JSON.stringify(status, null, 2)}
 `, "utf8");
   } catch {}
 }
@@ -40257,7 +41467,7 @@ function cleanupProcesses(jobsDir, dryRun) {
   }
   let entries;
   try {
-    entries = readdirSync14(jobsDir);
+    entries = readdirSync16(jobsDir);
   } catch {
     entries = [];
   }
@@ -40269,11 +41479,11 @@ function cleanupProcesses(jobsDir, dryRun) {
     zombieJobIds: []
   };
   for (const jobId of entries) {
-    const statusPath = join32(jobsDir, jobId, "status.json");
-    if (!existsSync29(statusPath))
+    const statusPath = join33(jobsDir, jobId, "status.json");
+    if (!existsSync31(statusPath))
       continue;
     try {
-      const status = JSON.parse(readFileSync30(statusPath, "utf8"));
+      const status = JSON.parse(readFileSync31(statusPath, "utf8"));
       result.total += 1;
       if (status.status !== "running" && status.status !== "starting")
         continue;
@@ -40358,8 +41568,8 @@ function resolveWatchdogMode() {
 function checkZombieJobs() {
   section3("Background jobs");
   hint(`watchdog mode: ${resolveWatchdogMode()}`);
-  const jobsDir = join32(CWD, ".specialists", "jobs");
-  if (!existsSync29(jobsDir)) {
+  const jobsDir = join33(CWD, ".specialists", "jobs");
+  if (!existsSync31(jobsDir)) {
     hint("No .specialists/jobs/ \u2014 skipping");
     return true;
   }
@@ -40369,7 +41579,7 @@ function checkZombieJobs() {
     return true;
   }
   for (const jobId of result.zombieJobIds) {
-    warn3(`${jobId}  ${yellow12("ZOMBIE")}  ${dim13("pid not found for running job")}`);
+    warn3(`${jobId}  ${yellow12("ZOMBIE")}  ${dim14("pid not found for running job")}`);
     fix(`Edit .specialists/jobs/${jobId}/status.json  \u2192  set "status": "error"`);
   }
   if (result.zombies === 0) {
@@ -40377,7 +41587,7 @@ function checkZombieJobs() {
   }
   return result.zombies === 0;
 }
-async function run28(argv = process.argv.slice(3)) {
+async function run29(argv = process.argv.slice(3)) {
   const subcommand = argv[0];
   if (subcommand === "orphans") {
     runDoctorOrphans();
@@ -40411,37 +41621,32 @@ ${bold13("specialists doctor")}
   const allOk = piOk && spOk && bdOk && xtOk && hooksOk && mcpOk && versionOk && skillDriftOk && mirrorOk && userOverlayOk && dirsOk && jobsOk && fragmentsOk;
   console.log("");
   if (allOk) {
-    console.log(`  ${green14("\u2713")} ${bold13("All checks passed")}  \u2014 specialists is healthy`);
+    console.log(`  ${green15("\u2713")} ${bold13("All checks passed")}  \u2014 specialists is healthy`);
   } else {
     console.log(`  ${yellow12("\u25CB")} ${bold13("Some checks failed")}  \u2014 follow the fix hints above`);
-    console.log(`  ${dim13("specialists init fixes hook + MCP registration; specialists init --sync-skills fixes skill drift/symlink issues; specialists init --sync-defaults fixes managed mirrors.")}`);
+    console.log(`  ${dim14("specialists init fixes hook + MCP registration; specialists init --sync-skills fixes skill drift/symlink issues; specialists init --sync-defaults fixes managed mirrors.")}`);
   }
   console.log("");
 }
-var bold13 = (s) => `\x1B[1m${s}\x1B[0m`, dim13 = (s) => `\x1B[2m${s}\x1B[0m`, green14 = (s) => `\x1B[32m${s}\x1B[0m`, yellow12 = (s) => `\x1B[33m${s}\x1B[0m`, red7 = (s) => `\x1B[31m${s}\x1B[0m`, CWD, CLAUDE_DIR, PI_DIR, XTRM_SKILLS_DIR, XTRM_DEFAULT_SKILLS_DIR, XTRM_ACTIVE_SKILLS_DIR, ACTIVE_CLAUDE_SKILLS_DIR, ACTIVE_PI_SKILLS_DIR, CONFIG_SKILLS_DIR, CONFIG_SPECIALISTS_DIR, CONFIG_MANDATORY_RULES_DIR, CONFIG_NODES_DIR, SPECIALISTS_DIR, DEFAULT_SPECIALISTS_DIR, USER_SPECIALISTS_DIR, HOOKS_DIR, CLAUDE_HOOKS_DIR, SETTINGS_FILE, MCP_FILE2, HOOK_NAMES;
+var bold13 = (s) => `\x1B[1m${s}\x1B[0m`, dim14 = (s) => `\x1B[2m${s}\x1B[0m`, green15 = (s) => `\x1B[32m${s}\x1B[0m`, yellow12 = (s) => `\x1B[33m${s}\x1B[0m`, red8 = (s) => `\x1B[31m${s}\x1B[0m`, CWD, CLAUDE_DIR, PI_DIR, XTRM_SKILLS_DIR, XTRM_DEFAULT_SKILLS_DIR, XTRM_ACTIVE_SKILLS_DIR, SPECIALISTS_DIR, DEFAULT_SPECIALISTS_DIR, USER_SPECIALISTS_DIR, HOOKS_DIR, CLAUDE_HOOKS_DIR, SETTINGS_FILE, MCP_FILE2, HOOK_NAMES;
 var init_doctor = __esm(() => {
   init_observability_sqlite();
+  init_canonical_asset_resolver();
   init_drift_detector();
   init_version_check();
   CWD = process.cwd();
-  CLAUDE_DIR = join32(CWD, ".claude");
-  PI_DIR = join32(CWD, ".pi");
-  XTRM_SKILLS_DIR = join32(CWD, ".xtrm", "skills");
-  XTRM_DEFAULT_SKILLS_DIR = join32(XTRM_SKILLS_DIR, "default");
-  XTRM_ACTIVE_SKILLS_DIR = join32(XTRM_SKILLS_DIR, "active");
-  ACTIVE_CLAUDE_SKILLS_DIR = join32(XTRM_ACTIVE_SKILLS_DIR, "claude");
-  ACTIVE_PI_SKILLS_DIR = join32(XTRM_ACTIVE_SKILLS_DIR, "pi");
-  CONFIG_SKILLS_DIR = join32(CWD, "config", "skills");
-  CONFIG_SPECIALISTS_DIR = join32(CWD, "config", "specialists");
-  CONFIG_MANDATORY_RULES_DIR = join32(CWD, "config", "mandatory-rules");
-  CONFIG_NODES_DIR = join32(CWD, "config", "nodes");
-  SPECIALISTS_DIR = join32(CWD, ".specialists");
-  DEFAULT_SPECIALISTS_DIR = join32(SPECIALISTS_DIR, "default");
-  USER_SPECIALISTS_DIR = join32(SPECIALISTS_DIR, "user");
-  HOOKS_DIR = join32(CWD, ".xtrm", "hooks", "specialists");
-  CLAUDE_HOOKS_DIR = join32(CLAUDE_DIR, "hooks");
-  SETTINGS_FILE = join32(CLAUDE_DIR, "settings.json");
-  MCP_FILE2 = join32(CWD, ".mcp.json");
+  CLAUDE_DIR = join33(CWD, ".claude");
+  PI_DIR = join33(CWD, ".pi");
+  XTRM_SKILLS_DIR = join33(CWD, ".xtrm", "skills");
+  XTRM_DEFAULT_SKILLS_DIR = join33(XTRM_SKILLS_DIR, "default");
+  XTRM_ACTIVE_SKILLS_DIR = join33(XTRM_SKILLS_DIR, "active");
+  SPECIALISTS_DIR = join33(CWD, ".specialists");
+  DEFAULT_SPECIALISTS_DIR = join33(SPECIALISTS_DIR, "default");
+  USER_SPECIALISTS_DIR = join33(SPECIALISTS_DIR, "user");
+  HOOKS_DIR = join33(CWD, ".xtrm", "hooks", "specialists");
+  CLAUDE_HOOKS_DIR = join33(CLAUDE_DIR, "hooks");
+  SETTINGS_FILE = join33(CLAUDE_DIR, "settings.json");
+  MCP_FILE2 = join33(CWD, ".mcp.json");
   HOOK_NAMES = [
     "specialists-complete.mjs",
     "specialists-session-start.mjs"
@@ -40451,9 +41656,9 @@ var init_doctor = __esm(() => {
 // src/cli/setup.ts
 var exports_setup = {};
 __export(exports_setup, {
-  run: () => run29
+  run: () => run30
 });
-async function run29() {
+async function run30() {
   console.log("");
   console.log(yellow13("\u26A0 DEPRECATED: `specialists setup` is deprecated"));
   console.log("");
@@ -40468,26 +41673,26 @@ async function run29() {
   console.log("  Options:");
   console.log("    --force-workflow   Overwrite existing workflow blocks");
   console.log("");
-  console.log(`  ${dim14("Run: specialists init --help for full details")}`);
+  console.log(`  ${dim15("Run: specialists init --help for full details")}`);
   console.log("");
 }
-var bold14 = (s) => `\x1B[1m${s}\x1B[0m`, yellow13 = (s) => `\x1B[33m${s}\x1B[0m`, dim14 = (s) => `\x1B[2m${s}\x1B[0m`;
+var bold14 = (s) => `\x1B[1m${s}\x1B[0m`, yellow13 = (s) => `\x1B[33m${s}\x1B[0m`, dim15 = (s) => `\x1B[2m${s}\x1B[0m`;
 
 // src/cli/serve-hot-reload.ts
-import { existsSync as existsSync30, readdirSync as readdirSync15, statSync as statSync5, watch as fsWatch } from "fs";
-import { join as join33 } from "path";
+import { existsSync as existsSync32, readdirSync as readdirSync17, statSync as statSync6, watch as fsWatch } from "fs";
+import { join as join34 } from "path";
 function specialistNameFromFile(file) {
   const match = file.match(/^(.+)\.specialist\.(json|yaml)$/);
   return match ? match[1] : null;
 }
 function snapshotMtimes(dir) {
   const out = new Map;
-  if (!existsSync30(dir))
+  if (!existsSync32(dir))
     return out;
-  const entries = readdirSync15(dir).filter((name) => specialistNameFromFile(name) !== null);
+  const entries = readdirSync17(dir).filter((name) => specialistNameFromFile(name) !== null);
   for (const name of entries) {
     try {
-      out.set(name, statSync5(join33(dir, name)).mtimeMs);
+      out.set(name, statSync6(join34(dir, name)).mtimeMs);
     } catch {}
   }
   return out;
@@ -40544,7 +41749,7 @@ function createUserDirWatcher(opts) {
       for (const file of changed)
         queue(file);
     }, opts.pollMs);
-  } else if (existsSync30(opts.userDir)) {
+  } else if (existsSync32(opts.userDir)) {
     try {
       watcher = fsWatch(opts.userDir, { persistent: false }, (_eventType, filename) => {
         queue(filename ? String(filename) : null);
@@ -40576,7 +41781,7 @@ var init_serve_hot_reload = () => {};
 var exports_serve = {};
 __export(exports_serve, {
   startServe: () => startServe,
-  run: () => run30,
+  run: () => run31,
   recordAuditFailure: () => recordAuditFailure,
   evaluateReadiness: () => evaluateReadiness2,
   createReadinessState: () => createReadinessState,
@@ -40587,9 +41792,9 @@ import { randomUUID as randomUUID3 } from "crypto";
 import { once } from "events";
 import { spawnSync as spawnSync23 } from "child_process";
 import { access, readdir as readdir2, readFile as readFile5, constants } from "fs/promises";
-import { existsSync as existsSync31 } from "fs";
+import { existsSync as existsSync33 } from "fs";
 import { homedir as homedir3 } from "os";
-import { join as join34 } from "path";
+import { join as join35 } from "path";
 function createReadinessState() {
   return { shuttingDown: false, auditFailures: [], dbWriteFailuresTotal: 0 };
 }
@@ -40605,7 +41810,7 @@ function pruneAuditFailures(state, now = Date.now()) {
   }
 }
 async function checkUserDirSpecs(userDir) {
-  if (!existsSync31(userDir))
+  if (!existsSync33(userDir))
     return "empty";
   const entries = await readdir2(userDir).catch(() => []);
   const specFiles = entries.filter((name) => name.endsWith(".specialist.json") || name.endsWith(".specialist.yaml"));
@@ -40614,7 +41819,7 @@ async function checkUserDirSpecs(userDir) {
   let validCount = 0;
   for (const file of specFiles) {
     try {
-      const content = await readFile5(join34(userDir, file), "utf-8");
+      const content = await readFile5(join35(userDir, file), "utf-8");
       const json = file.endsWith(".json") ? content : null;
       if (!json)
         continue;
@@ -40632,7 +41837,7 @@ async function evaluateReadiness2(opts) {
   if (opts.state.auditFailures.length > opts.auditFailureThreshold) {
     return { ready: false, reason: "degraded:audit" };
   }
-  const piConfigPath = opts.piConfigPath ?? join34(homedir3(), ".pi", "agent", "auth.json");
+  const piConfigPath = opts.piConfigPath ?? join35(homedir3(), ".pi", "agent", "auth.json");
   try {
     await access(piConfigPath, constants.R_OK);
   } catch {
@@ -40653,7 +41858,7 @@ async function evaluateReadiness2(opts) {
       warning = canaryFailure;
     }
   }
-  const userDir = join34(opts.projectDir, ".specialists", "user");
+  const userDir = join35(opts.projectDir, ".specialists", "user");
   const userDirResult = await checkUserDirSpecs(userDir);
   if (userDirResult === "empty")
     return { ready: false, reason: "empty_user_dir" };
@@ -40774,7 +41979,7 @@ async function startServe(argv = process.argv.slice(3)) {
     return createObservabilitySqliteClient(args.projectDir);
   })();
   const readinessState = createReadinessState();
-  const userDir = join34(args.projectDir, ".specialists", "user");
+  const userDir = join35(args.projectDir, ".specialists", "user");
   const hotReload = createUserDirWatcher({ loader, userDir, pollMs: args.reloadPollMs });
   let active = 0;
   const children = new Set;
@@ -40939,7 +42144,7 @@ async function startServe(argv = process.argv.slice(3)) {
   console.log(`sp serve listening on ${args.port}`);
   return { server, args, db, readinessState };
 }
-async function run30(argv = process.argv.slice(3)) {
+async function run31(argv = process.argv.slice(3)) {
   await startServe(argv);
 }
 var AUDIT_WINDOW_MS = 60000, DEFAULT_REQUIRED_PI_FLAGS;
@@ -40957,7 +42162,7 @@ var init_serve = __esm(() => {
 var exports_script = {};
 __export(exports_script, {
   scriptCli: () => scriptCli,
-  run: () => run31,
+  run: () => run32,
   parseArgs: () => parseArgs13,
   mapExitCode: () => mapExitCode
 });
@@ -41074,7 +42279,7 @@ function runUnderLock(lockPath, argv) {
     return 75;
   return flock.status ?? 1;
 }
-async function run31(argv = process.argv.slice(3)) {
+async function run32(argv = process.argv.slice(3)) {
   const args = parseArgs13(argv);
   if (args.singleInstance && !process.env.SP_SCRIPT_NO_LOCK) {
     process.exit(runUnderLock(args.singleInstance, argv));
@@ -41098,13 +42303,13 @@ var init_script = __esm(() => {
 // src/cli/help.ts
 var exports_help = {};
 __export(exports_help, {
-  run: () => run32
+  run: () => run33
 });
 function formatCommands(entries) {
   const width = Math.max(...entries.map(([cmd3]) => cmd3.length));
   return entries.map(([cmd3, desc]) => `  ${cmd3.padEnd(width)}   ${desc}`);
 }
-async function run32() {
+async function run33() {
   const lines = [
     "",
     "Specialists lets you run project-scoped specialist agents with a bead-first workflow.",
@@ -41113,7 +42318,7 @@ async function run32() {
     "  specialists|sp [command]",
     "  specialists|sp [command] --help",
     "",
-    dim15("  sp is a shorter alias \u2014 sp run, sp list, sp feed etc. all work identically."),
+    dim16("  sp is a shorter alias \u2014 sp run, sp list, sp feed etc. all work identically."),
     "",
     bold15("Common flows:"),
     "",
@@ -41195,13 +42400,13 @@ async function run32() {
     "  specialists init --help        Bootstrap behavior and workflow injection",
     "  specialists feed --help        Job event streaming details",
     "",
-    dim15("Project model: specialists are project-only; user-scope discovery is deprecated."),
+    dim16("Project model: specialists are project-only; user-scope discovery is deprecated."),
     ""
   ];
   console.log(lines.join(`
 `));
 }
-var bold15 = (s) => `\x1B[1m${s}\x1B[0m`, dim15 = (s) => `\x1B[2m${s}\x1B[0m`, CORE_COMMANDS, EXTENDED_COMMANDS, WORKTREE_COMMANDS;
+var bold15 = (s) => `\x1B[1m${s}\x1B[0m`, dim16 = (s) => `\x1B[2m${s}\x1B[0m`, CORE_COMMANDS, EXTENDED_COMMANDS, WORKTREE_COMMANDS;
 var init_help = __esm(() => {
   CORE_COMMANDS = [
     ["init", "Bootstrap a project: dirs, workflow injection, project MCP registration"],
@@ -41218,7 +42423,7 @@ var init_help = __esm(() => {
     ["epic", "Epic lifecycle management: list/status/resolve wave-bound chain groups"],
     ["feed", "Tail job events; use -f to follow all jobs"],
     ["result", "Print final output of a completed job; --wait polls until done, --timeout <ms> sets a limit"],
-    ["clean", "Purge completed job directories (TTL, --all, --keep, --dry-run)"],
+    ["clean", "Clean job dirs, dashboard history (--ps), and orphan processes"],
     ["merge", "Publish one standalone chain (refuses unresolved epic chains)"],
     ["end", "Session-close publish helper; chain-aware and epic-aware with optional --pr mode"],
     ["epic list", "Enumerate epics with lifecycle state and merge readiness summary"],
@@ -41231,7 +42436,7 @@ var init_help = __esm(() => {
     ["attach", "Attach terminal to a running background job tmux session"],
     ["report", "Generate/show/list/diff session reports in .xtrm/reports/"],
     ["status", "Show health, MCP state, and active jobs"],
-    ["ps", "Show urgency-sorted worktree view with ctx% and NEXT action; --json, --all, --follow, --running, --bead <id>, --since <dur>, --mine, --include-terminal"],
+    ["ps", "Show actionable dashboard (active + unresolved terminal problems); --json, --all, --follow, --active, --health, --include-terminal, --include-cleaned"],
     ["doctor", "Diagnose installation/runtime problems; --check-drift reports stale .specialists/default/ snapshots"],
     ["prune-stale-defaults", "Prune redundant .specialists/default/ snapshots (byte-identical to package canonical); --dry-run, --root <path>"],
     ["quickstart", "Full getting-started guide"],
@@ -48756,12 +49961,21 @@ process.on("uncaughtException", (err) => {
   console.error("[specialists] [ERROR] Fatal error:", err);
   process.exit(1);
 });
+if (typeof globalThis.Bun === "undefined") {
+  console.error([
+    "[specialists] [ERROR] Bun runtime required (>=1.0.0).",
+    "[specialists] Install Bun: https://bun.sh/install",
+    "[specialists] Example: curl -fsSL https://bun.sh/install | bash"
+  ].join(`
+`));
+  process.exit(1);
+}
 var sub = process.argv[2];
 var next = process.argv[3];
 function wantsHelp() {
   return next === "--help" || next === "-h";
 }
-async function run33() {
+async function run34() {
   if (sub === "install") {
     if (wantsHelp()) {
       console.log([
@@ -48893,6 +50107,12 @@ async function run33() {
         "  \u2022 installs hooks to .claude/hooks/ and wires .claude/settings.json",
         "  \u2022 syncs skills into .xtrm/skills/default/ and wires active symlinks",
         "",
+        "Prereq:",
+        "  Bun >=1.0.0 required before xtrm-tools setup.",
+        "  Install order: Bun -> xtrm-tools -> xt install -> xt init ->",
+        "  @jaggerxtrm/specialists -> sp init.",
+        "  sp list, sp doctor --check-drift, sp prune-stale-defaults do not require xt.",
+        "",
         "Options:",
         "  --sync-defaults    Also copy canonical specialists to .specialists/default/.",
         "                     Human-only: rewrites default specialist YAML files.",
@@ -49207,31 +50427,29 @@ async function run33() {
     if (wantsHelp()) {
       console.log([
         "",
-        "Usage: specialists epic <list|status|resolve|merge> [options]",
+        "Usage: specialists epic <list|status|sync|abandon|merge> [options]",
         "",
         "Epic lifecycle management for wave-bound chain groups.",
         "",
         "Commands:",
-        "  list [--unresolved] [--json]                Enumerate epics with lifecycle state and readiness",
-        "  status <epic-id> [--json]                   Show chains, blockers, and merge readiness",
-        "  resolve <epic-id> [--dry-run] [--json]      Transition epic from open -> resolving",
+        "  list [--unresolved] [--json]                Enumerate epics with readiness",
+        "  status <epic-id> [--json]                   Show derived readiness and chain status",
+        "  sync <epic-id> [--apply] [--json]           Reconcile epic drift (dry-run by default)",
+        "  abandon <epic-id> --reason <text> [--force] [--json]  Transition epic to abandoned",
         "  merge <epic-id> [--rebuild] [--pr] [--json] Publish epic chains (direct merge or PR mode)",
         "",
         "Options:",
-        "  --unresolved    Filter list to non-terminal (open, resolving, merge_ready) epics",
-        "  --dry-run       Preview transition without persisting",
+        "  --unresolved    Filter list to open epics only",
         "  --json          Machine-readable JSON output",
         "",
-        "Lifecycle states:",
-        "  open -> resolving -> merge_ready -> merged",
-        "  (failed, abandoned are terminal)",
+        "Readiness:",
+        "  status is derived from live chain readiness",
+        "  persisted lifecycle state is compatibility metadata only",
         "",
         "Examples:",
         "  specialists epic list",
         "  specialists epic list --unresolved",
         "  specialists epic status unitAI-epic1",
-        "  specialists epic resolve unitAI-epic1",
-        "  specialists epic resolve unitAI-epic1 --dry-run",
         "  specialists epic merge unitAI-epic1 --pr",
         ""
       ].join(`
@@ -49277,14 +50495,18 @@ async function run33() {
         "",
         "Usage: specialists ps [options]",
         "",
-        "Process dashboard \u2014 shows active specialist jobs grouped by worktree chain.",
-        "Dead jobs (PID gone) are filtered by default. Includes context%, bead title,",
-        "and next-action hints on every row.",
+        "Process dashboard \u2014 shows active jobs plus unresolved terminal problems.",
+        "Cleaned dashboard history and dead jobs are filtered by default. Includes",
+        "context%, bead title, and next-action hints on every row.",
         "",
         "Options:",
-        "  --json       Structured JSON output with trees[].children[] schema",
-        "  --all        Include terminal (done/error) and dead jobs",
-        "  --follow, -f Live-refresh view with spinner animation",
+        "  --json              Structured JSON output with trees[].children[] schema",
+        "  --all               Include every row, including cleaned/dead/terminal history",
+        "  --follow, -f        Live-refresh view with spinner animation",
+        "  --health            Show detailed process health tables (default is aggregate only)",
+        "  --active            Show active jobs only; hide unresolved terminal problems",
+        "  --include-terminal  Include terminal history that has not been cleaned",
+        "  --include-cleaned   Include rows hidden by sp clean --ps",
         "",
         "Output columns:",
         "  st           Status icon: \u25C9 running, \u25D0 waiting/starting, \u25CB done/error",
@@ -49302,9 +50524,17 @@ async function run33() {
         "",
         "Node refs accept any unique prefix.",
         "",
+        "Dashboard cleanup:",
+        "  sp clean --ps --dry-run previews terminal rows to hide from default ps.",
+        "  sp clean --ps hides terminal rows without deleting DB history or changing status.",
+        "  Use --include-cleaned or --all to audit cleaned rows later.",
+        "",
         "Examples:",
-        "  specialists ps              Active jobs only (dead filtered out)",
-        "  specialists ps --all        All jobs including dead and terminal",
+        "  specialists ps              Active + unresolved terminal problems",
+        "  specialists ps --active     Active jobs only",
+        "  specialists ps --include-terminal  Include uncleaned terminal history",
+        "  specialists ps --include-cleaned   Show rows hidden by sp clean --ps",
+        "  specialists ps --all        Full audit view including cleaned/dead/history",
         "  specialists ps --json       Machine-readable tree output",
         "  specialists ps --node research  Filter dashboard to one node run",
         "  specialists ps --follow     Live dashboard with auto-refresh",
@@ -49465,24 +50695,52 @@ async function run33() {
       console.log([
         "",
         "Usage: specialists clean [--all] [--keep <n>] [--dry-run]",
+        "       specialists clean --ps [--dry-run]",
+        "       specialists clean --reap-orphans [--dry-run]",
+        "       specialists clean --observability --before <iso|duration> [--include-epics] [--dry-run]",
         "",
-        "Purge completed job directories from .specialists/jobs/.",
+        "Clean specialist runtime artifacts and dashboard visibility.",
         "",
         "Default behavior:",
-        "  - removes done/error jobs older than SPECIALISTS_JOB_TTL_DAYS",
+        "  - removes done/error job directories older than SPECIALISTS_JOB_TTL_DAYS",
         "  - TTL defaults to 7 days if env is unset",
         "  - never removes SQLite artifacts (*.db, *.db-wal, *.db-shm)",
+        "  - never prunes observability.db rows unless --observability is explicit",
+        "",
+        "Dashboard cleanup:",
+        "  - --ps soft-hides terminal rows from default sp ps",
+        "  - --ps does not delete SQLite rows or change job status",
+        "  - sp ps --include-cleaned / --all restore audit visibility",
+        "",
+        "Observability cleanup:",
+        "  - --observability prunes terminal SQLite rows via the DB prune path",
+        "  - requires --before <iso|duration>; examples: 30d, 2026-01-01T00:00:00Z",
+        "  - preserves active/waiting/running jobs and memories_* tables",
         "",
         "Options:",
-        "  --all        Remove all done/error jobs regardless of age",
-        "  --keep <n>   Keep only the N most recent done/error jobs",
-        "  --dry-run    Show what would be removed without deleting",
+        "  --all           Remove all done/error job directories regardless of age",
+        "  --keep <n>      Keep only the N most recent done/error job directories",
+        "  --dry-run       Preview filesystem, dashboard, or process cleanup",
+        "  --ps            Hide terminal rows from default ps without deleting DB history",
+        "  --observability Prune terminal observability.db rows (requires --before)",
+        "  --before <value> Cutoff for --observability (ISO date or duration like 30d)",
+        "  --include-epics Also prune eligible terminal epic_runs with --observability",
+        "  --reap-orphans  Reap orphan/stale leaked tool processes; detects",
+        "                  dead-pid (PID gone), orphaned-keep-alive (PID alive,",
+        "                  ppid=1, status=waiting), dead-toolchain (PID alive but",
+        "                  no tool/think events in last 30min); all require 30min",
+        "                  min-age threshold",
         "",
         "Examples:",
         "  specialists clean",
         "  specialists clean --all",
         "  specialists clean --keep 20",
         "  specialists clean --dry-run",
+        "  specialists clean --ps --dry-run",
+        "  specialists clean --ps",
+        "  specialists clean --observability --before 30d --dry-run",
+        "  specialists clean --observability --before 30d",
+        "  specialists clean --reap-orphans --dry-run",
         ""
       ].join(`
 `));
@@ -49495,7 +50753,7 @@ async function run33() {
     if (wantsHelp()) {
       console.log([
         "",
-        "Usage: specialists merge <target-bead-id> [--rebuild]",
+        "Usage: specialists merge <target-bead-id> [--target-branch <name>] [--rebuild]",
         "",
         "Publish a chain root bead branch. Epic publication belongs to `sp epic merge`.",
         "",
@@ -49504,6 +50762,9 @@ async function run33() {
         "  - unresolved epic member: refuses and points to `sp epic merge <epic-id>`",
         "  - runs `bunx tsc --noEmit` after each merge and stops on failure",
         "  - stops on first merge conflict and reports conflicting files",
+        "  - --target-branch overrides origin/HEAD as rebase target; useful for",
+        "    chains forked from non-main branches",
+        "  - ignores dirty .beads/issues.jsonl and .xtrm/skills/active/**",
         "  - NOTE: for epic publication with lifecycle management, use `sp epic merge`",
         "",
         "Options:",
@@ -49574,6 +50835,28 @@ async function run33() {
     const { run: handler } = await Promise.resolve().then(() => (init_stop(), exports_stop));
     return handler();
   }
+  if (sub === "finalize") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists finalize <job-id>",
+        "",
+        "Finalize waiting keep-alive job after reviewer PASS.",
+        "Reads SQLite-first compliance verdict from observability.db specialist_results.",
+        "Falls back to result.txt when SPECIALISTS_JOB_FILE_OUTPUT=on.",
+        "Accepts any chain member job-id and finalizes full keep-alive chain.",
+        "Refuses non-waiting or non-PASS jobs.",
+        "",
+        "Examples:",
+        "  specialists finalize job_a1b2c3d4",
+        ""
+      ].join(`
+`));
+      return;
+    }
+    const { run: handler } = await Promise.resolve().then(() => (init_finalize(), exports_finalize));
+    return handler();
+  }
   if (sub === "attach") {
     if (wantsHelp()) {
       process.stdout.write([
@@ -49635,7 +50918,10 @@ async function run33() {
         "",
         "Subcommands:",
         "  orphans   Read-only orphan scan: membership/jobs/epics/worktree pointers",
-        "  --check-drift, --drift   Report stale .specialists/default/ snapshots vs package canonical",
+        "  --check-drift, --drift   Compare .specialists/default/ snapshots against package canonical",
+        "                            Category A (specialists runtime) and Category B",
+        "                            (filesystem skills/hooks) are distinct; doctor",
+        "                            covers Category A only",
         "",
         "Examples:",
         "  specialists doctor",
@@ -49667,7 +50953,7 @@ async function run33() {
     if (wantsHelp()) {
       console.log([
         "",
-        "Usage: specialists serve [--port <n>] [--concurrency <n>] [--shutdown-grace-ms <n>] [--project-dir <path>] [--db-path <observability.db>] [--readiness-canary off|warn|require] [--log-level off|info|debug]",
+        "Usage: specialists serve [--port <n>] [--concurrency <n>] [--shutdown-grace-ms <n>] [--project-dir <path>]",
         "",
         "HTTP wrapper for script-class specialists.",
         "",
@@ -49723,7 +51009,7 @@ Run 'specialists help' to see available commands.`);
   const server = new SpecialistsServer;
   await server.start();
 }
-run33().catch((error2) => {
+run34().catch((error2) => {
   logger.error(`Fatal error: ${error2}`);
   process.exit(1);
 });