@jaggerxtrm/specialists 3.16.0 → 3.17.0

package/dist/index.js

@@ -7895,7 +7895,7 @@ var require_core = __commonJS((exports) => {
     constructor(opts = {}) {
       this.schemas = {};
       this.refs = {};
-      this.formats = {};
+      this.formats = Object.create(null);
       this._compilations = new Set;
       this._loading = {};
       this._cache = new Map;
@@ -17734,6 +17734,7 @@ var init_schema = __esm(() => {
       stall_detection: StallDetectionSchema,
       mandatory_rules: MandatoryRulesSchema,
       output_file: stringType().optional(),
+      notes_mode: enumType(["full-trail", "final-only"]).default("full-trail"),
       beads_integration: enumType(["auto", "always", "never"]).default("auto"),
       beads_write_notes: booleanType().default(true)
     }).passthrough()
@@ -17926,6 +17927,14 @@ function detectJobFileOutputMode(env = process.env) {
 function isJobFileOutputEnabled(env = process.env) {
   return detectJobFileOutputMode(env) === "on";
 }
+async function writeJobFileOutput(path, content, mode) {
+  const { appendFile, writeFile } = await import("fs/promises");
+  if (mode === "append") {
+    await appendFile(path, content, "utf-8");
+    return;
+  }
+  await writeFile(path, content, "utf-8");
+}
 
 // src/specialist/templateEngine.ts
 function renderTemplate(template, variables) {
@@ -22088,7 +22097,6 @@ __export(exports_runner, {
   SpecialistRunner: () => SpecialistRunner
 });
 import { createHash as createHash2 } from "crypto";
-import { writeFile } from "fs/promises";
 import { execSync as execSync2, spawnSync as spawnSync4 } from "child_process";
 import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
 import { basename as basename2, resolve as resolve4 } from "path";
@@ -23061,8 +23069,8 @@ ${outputContractWarnings.map((msg) => `  \u26A0 ${msg}`).join(`
 `)}
 `);
     }
-    if (output_file && isJobFileOutputEnabled()) {
-      await writeFile(output_file, output, "utf-8").catch(() => {});
+    if (output_file && !options.suppressRunnerFileOutput) {
+      await writeJobFileOutput(output_file, output, "overwrite").catch(() => {});
     }
     await hooks.emit("post_execute", invocationId, metadata.name, metadata.version, {
       status: "COMPLETE",
@@ -23916,6 +23924,14 @@ function createRunCompleteEvent(status, elapsed_s, options) {
     ...options
   };
 }
+function createControlSignalEvent(action, options) {
+  return {
+    t: Date.now(),
+    type: TIMELINE_EVENT_TYPES.CONTROL_SIGNAL,
+    action,
+    ...options
+  };
+}
 function createAutoCommitEvent(status, options) {
   const type = status === "success" ? TIMELINE_EVENT_TYPES.AUTO_COMMIT_SUCCESS : status === "skipped" ? TIMELINE_EVENT_TYPES.AUTO_COMMIT_SKIPPED : TIMELINE_EVENT_TYPES.AUTO_COMMIT_FAILED;
   return {
@@ -23991,6 +24007,7 @@ var init_timeline_events = __esm(() => {
     AUTO_COMMIT_SUCCESS: "auto_commit_success",
     AUTO_COMMIT_SKIPPED: "auto_commit_skipped",
     AUTO_COMMIT_FAILED: "auto_commit_failed",
+    CONTROL_SIGNAL: "control_signal",
     DONE: "done",
     AGENT_END: "agent_end"
   };
@@ -24498,24 +24515,37 @@ function getCurrentGitSha() {
   const sha = result.stdout?.trim();
   return sha || undefined;
 }
-function formatBeadNotes(result) {
-  const statusLabel = result.status === "waiting" ? "WAITING \u2014 more output may follow" : result.status.toUpperCase();
-  const metadata = [
-    `timestamp=${result.timestamp}`,
-    `status=${result.status}`,
-    `prompt_hash=${result.promptHash ?? "unknown"}`,
-    `git_sha=${getCurrentGitSha() ?? "unknown"}`,
-    `elapsed_ms=${result.durationMs !== undefined ? Math.round(result.durationMs) : "unknown"}`,
-    `model=${result.model}`,
-    `backend=${result.backend}`
-  ].join(`
-`);
-  return `### Specialist Output \u2014 ${result.specialist} (job ${result.jobId}) [${statusLabel}]
+function normalizeHandoffModel(model) {
+  return model.split("/").at(-1) ?? model;
+}
+function formatHandoffBlock(result, options) {
+  const statusToken = options.final ? `FINAL \xB7 ${result.status === "cancelled" ? "CANCELLED" : result.status === "error" ? "ERROR" : "DONE"}` : result.status === "waiting" ? "WAITING" : "WORKING";
+  const model = normalizeHandoffModel(result.model);
+  const header = options.final ? `## ${result.specialist} \xB7 ${model} \xB7 [${statusToken}]` : `### ${result.specialist} \xB7 ${model} \xB7 [turn ${result.turnIndex ?? "unknown"} \xB7 ${statusToken}]`;
+  const tokenUsage = result.tokenUsage;
+  const gitSha = getCurrentGitSha();
+  const footerParts = [
+    options.final ? "final" : `turn ${result.turnIndex ?? "unknown"}`,
+    result.durationMs !== undefined ? `${Math.round(result.durationMs)} ms` : undefined,
+    tokenUsage?.input_tokens && tokenUsage?.output_tokens ? `${tokenUsage.input_tokens} to ${tokenUsage.output_tokens} tok` : tokenUsage?.input_tokens ? `${tokenUsage.input_tokens} tok in` : tokenUsage?.output_tokens ? `${tokenUsage.output_tokens} tok out` : undefined,
+    result.timestamp ? new Date(result.timestamp).toISOString().slice(0, 16).replace("T", " ") : undefined,
+    gitSha ? `git ${gitSha.slice(0, 8)}` : undefined
+  ].filter((part) => Boolean(part));
+  const footer = footerParts.length > 0 ? `_${footerParts.join(" \xB7 ")}_` : "";
+  return `
 
-${result.output}
+${header}
 
----
-${metadata}`;
+${result.output}${footer ? `
+
+${footer}` : ""}`;
+}
+function shouldPersistHandoffBlock(params) {
+  if (!params.output.trim())
+    return false;
+  if (params.notesMode === "final-only" && !params.final)
+    return false;
+  return true;
 }
 function getModelContextWindow(model) {
   if (!model)
@@ -24912,10 +24942,6 @@ class Supervisor {
   observabilityDbPath() {
     return resolveObservabilityDbLocation(this.opts.runOptions?.workingDirectory ?? process.cwd()).dbPath;
   }
-  shouldWriteJobFiles() {
-    const mode = String(process.env.SPECIALISTS_JOB_FILE_OUTPUT ?? "").trim().toLowerCase();
-    return mode === "" || mode === "on" || mode === "true" || mode === "1";
-  }
   eventsPath(id) {
     return join9(this.jobDir(id), "events.jsonl");
   }
@@ -24932,6 +24958,45 @@ class Supervisor {
       is_dead: isJobDead(status)
     };
   }
+  reconcileDeadStatus(id, status) {
+    if (!isJobDead(status) || status.status !== "running" && status.status !== "starting") {
+      return this.withComputedLiveness(status);
+    }
+    if (!Number.isFinite(status.started_at_ms)) {
+      return this.withComputedLiveness(status);
+    }
+    const now = Date.now();
+    const recoveredStatus = {
+      ...status,
+      status: "error",
+      current_event: undefined,
+      error: "Process crashed or was killed",
+      last_event_at_ms: now
+    };
+    const elapsed = Math.max(0, Math.round((now - status.started_at_ms) / 1000));
+    const runCompleteEvent = createRunCompleteEvent("ERROR", elapsed, {
+      error: recoveredStatus.error,
+      exit_reason: "crashed"
+    });
+    if (this.sqliteClient) {
+      const persisted = this.withSqliteOperation("upsertStatusWithEvent:readStatus", (client) => {
+        client.upsertStatusWithEvent(recoveredStatus, runCompleteEvent);
+        return true;
+      });
+      if (persisted === undefined) {
+        throw new Error("[supervisor] SQLite upsertStatusWithEvent failed during readStatus recovery: database client unavailable");
+      }
+    } else {
+      this.writeStatusFileOnly(id, recoveredStatus);
+      if (this.isJobFileOutputEnabled) {
+        const eventsPath = this.eventsPath(id);
+        mkdirSync4(this.jobDir(id), { recursive: true });
+        appendFileSync(eventsPath, JSON.stringify(runCompleteEvent) + `
+`, "utf-8");
+      }
+    }
+    return this.withComputedLiveness(recoveredStatus);
+  }
   readStatus(id) {
     try {
       if (this.isDisposed) {
@@ -24939,7 +25004,7 @@ class Supervisor {
       }
       const sqliteStatus = this.withSqliteOperation("readStatus", (client) => client.readStatus(id));
       if (sqliteStatus)
-        return this.withComputedLiveness(sqliteStatus);
+        return this.reconcileDeadStatus(id, sqliteStatus);
     } catch (error2) {
       if (!(error2 instanceof Error && error2.message.includes("supervisor is disposed"))) {
         console.warn(`[supervisor] SQLite readStatus failed, falling back to file state: ${String(error2)}`);
@@ -24950,7 +25015,7 @@ class Supervisor {
       return null;
     try {
       const status = JSON.parse(readFileSync8(path, "utf-8"));
-      return this.withComputedLiveness(status);
+      return this.reconcileDeadStatus(id, status);
     } catch {
       return null;
     }
@@ -24983,7 +25048,7 @@ class Supervisor {
         throw this.createDisposedSqliteError("readResult");
       }
       const sqliteResult = this.withSqliteOperation("readResult", (client) => client.readResult(id));
-      if (sqliteResult)
+      if (typeof sqliteResult === "string" && sqliteResult.trim().length > 0)
         return sqliteResult;
     } catch (error2) {
       if (!(error2 instanceof Error && error2.message.includes("supervisor is disposed"))) {
@@ -25013,25 +25078,52 @@ class Supervisor {
     if (!finalized)
       return null;
     this.aggregateJobMetricsBestEffort(id);
+    if (finalized.bead_id && this.opts.beadsClient) {
+      const outputPath = this.resultPath(id);
+      const output = existsSync10(outputPath) ? readFileSync8(outputPath, "utf-8") || this.readResult(id) || "" : this.readResult(id) || "";
+      if (output.trim()) {
+        this.opts.beadsClient.updateBeadNotes(finalized.bead_id, formatHandoffBlock({
+          output,
+          model: finalized.model ?? "unknown",
+          backend: finalized.backend ?? "unknown",
+          specialist: finalized.specialist,
+          jobId: id,
+          status: "done",
+          timestamp: new Date().toISOString()
+        }, { final: true }));
+      }
+    }
     return finalized;
   }
+  appendEventBestEffort(jobId, operation, event) {
+    try {
+      const status = this.readStatus(jobId);
+      const persisted = this.withSqliteOperation(operation, (client) => {
+        client.appendEvent(jobId, status?.specialist ?? "unknown", status?.bead_id, event);
+        return true;
+      });
+      if (persisted === undefined) {
+        console.warn(`[supervisor] SQLite ${operation} skipped: database client unavailable`);
+      }
+    } catch (error2) {
+      console.warn(`[supervisor] SQLite ${operation} failed: ${String(error2)}`);
+    }
+  }
   emitMetaEvent(jobId, model, backend) {
     if (this.isDisposed)
       return;
-    const event = createMetaEvent(model, backend);
-    const persisted = this.withSqliteOperation("appendEvent", (client) => {
-      const status = this.readStatus(jobId);
-      client.appendEvent(jobId, status?.specialist ?? "unknown", status?.bead_id, event);
-      return true;
-    });
-    if (persisted === undefined) {
-      throw new Error("[supervisor] SQLite appendEvent failed: database client unavailable");
-    }
+    this.appendEventBestEffort(jobId, "appendEvent", createMetaEvent(model, backend));
+  }
+  emitControlEvent(jobId, action, options) {
+    if (this.isDisposed)
+      return;
+    this.appendEventBestEffort(jobId, "appendEvent", createControlSignalEvent(action, options));
   }
   updateJobStatus(id, status, error2) {
     const currentStatus = this.readStatus(id);
     if (!currentStatus)
       return null;
+    const previousStatus = currentStatus.status;
     const updatedStatus = {
       ...currentStatus,
       status,
@@ -25039,7 +25131,10 @@ class Supervisor {
       error: error2,
       last_event_at_ms: Date.now()
     };
-    this.writeStatusFile(id, updatedStatus);
+    this.writeStatusFile(id, updatedStatus, { sqliteFailureMode: "warn" });
+    if (previousStatus !== status) {
+      this.appendEventBestEffort(id, "appendEvent:status_change", createStatusChangeEvent(status, previousStatus));
+    }
     return this.withComputedLiveness(updatedStatus);
   }
   aggregateJobMetricsBestEffort(jobId) {
@@ -25109,41 +25204,49 @@ class Supervisor {
     writeFileSync3(tmp, JSON.stringify(normalizedStatus, null, 2), "utf-8");
     renameSync(tmp, path);
   }
-  writeStatusFile(id, data) {
+  writeStatusFile(id, data, options = {}) {
     const normalizedStatus = this.withStatusLineageDefaults(id, data);
     this.writeStatusFileOnly(id, normalizedStatus);
-    const persisted = this.withSqliteOperation("upsertStatus", (client) => {
-      client.upsertStatus(normalizedStatus);
-      const chainId = resolveChainId(normalizedStatus);
-      if (!normalizedStatus.epic_id || !chainId) {
-        return true;
-      }
-      client.upsertEpicRun({
-        epic_id: normalizedStatus.epic_id,
-        status: "open",
-        updated_at_ms: Date.now(),
-        status_json: JSON.stringify({
+    try {
+      const persisted = this.withSqliteOperation("upsertStatus", (client) => {
+        client.upsertStatus(normalizedStatus);
+        const chainId = resolveChainId(normalizedStatus);
+        if (!normalizedStatus.epic_id || !chainId) {
+          return true;
+        }
+        client.upsertEpicRun({
           epic_id: normalizedStatus.epic_id,
           status: "open",
-          source: "supervisor",
+          updated_at_ms: Date.now(),
+          status_json: JSON.stringify({
+            epic_id: normalizedStatus.epic_id,
+            status: "open",
+            source: "supervisor",
+            chain_id: chainId,
+            chain_root_bead_id: normalizedStatus.chain_root_bead_id ?? null,
+            chain_root_job_id: normalizedStatus.chain_root_job_id ?? normalizedStatus.id
+          })
+        });
+        client.upsertEpicChainMembership({
           chain_id: chainId,
-          chain_root_bead_id: normalizedStatus.chain_root_bead_id ?? null,
-          chain_root_job_id: normalizedStatus.chain_root_job_id ?? normalizedStatus.id
-        })
-      });
-      client.upsertEpicChainMembership({
-        chain_id: chainId,
-        epic_id: normalizedStatus.epic_id,
-        chain_root_bead_id: normalizedStatus.chain_root_bead_id,
-        chain_root_job_id: normalizedStatus.chain_root_job_id ?? normalizedStatus.id,
-        updated_at_ms: Date.now()
+          epic_id: normalizedStatus.epic_id,
+          chain_root_bead_id: normalizedStatus.chain_root_bead_id,
+          chain_root_job_id: normalizedStatus.chain_root_job_id ?? normalizedStatus.id,
+          updated_at_ms: Date.now()
+        });
+        const readiness = loadEpicReadinessSummary(client, normalizedStatus.epic_id);
+        syncEpicStateFromReadiness(client, readiness);
+        return true;
       });
-      const readiness = loadEpicReadinessSummary(client, normalizedStatus.epic_id);
-      syncEpicStateFromReadiness(client, readiness);
-      return true;
-    });
-    if (persisted === undefined) {
-      throw new Error("[supervisor] SQLite upsertStatus failed: database client unavailable");
+      if (persisted === undefined) {
+        throw new Error("[supervisor] SQLite upsertStatus failed: database client unavailable");
+      }
+    } catch (error2) {
+      if (options.sqliteFailureMode === "warn") {
+        console.warn(`[supervisor] SQLite upsertStatus failed: ${String(error2)}`);
+        return;
+      }
+      throw error2;
     }
   }
   gc() {
@@ -25475,6 +25578,10 @@ 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;
+    const notesMode = runOptions.notesMode ?? "full-trail";
+    const outputFile = runOptions.output_file;
+    let lastTurnSummaryTextContent = "";
+    let lastTurnSummaryIndex = 0;
     let skipFinalKeepAliveInputBeadAppend = false;
     let lastGitnexusAnalyzedSha;
     const triggerGitnexusAnalyzeIfNeeded = (sha, source) => {
@@ -25491,12 +25598,10 @@ class Supervisor {
         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);
-      if (!shouldAppendResultToInputBead || !inputBeadId || !this.opts.beadsClient)
+    const writeUnifiedHandoff = (params) => {
+      if (!shouldPersistHandoffBlock({ output: params.output, notesMode, final: params.final }))
         return false;
-      const notes = formatBeadNotes({
+      const rendered = formatHandoffBlock({
         output: params.output,
         promptHash: params.promptHash,
         durationMs: params.durationMs,
@@ -25505,24 +25610,42 @@ class Supervisor {
         specialist: runOptions.name,
         jobId: id,
         status: params.status,
-        timestamp: new Date().toISOString()
-      });
-      const appendResult = this.opts.beadsClient.updateBeadNotes(inputBeadId, notes);
-      if (appendResult.ok)
-        return true;
-      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() });
-      if (this.isJobFileOutputEnabled) {
-        try {
-          appendFileSync(this.resultPath(id), `
+        timestamp: new Date().toISOString(),
+        tokenUsage: params.tokenUsage,
+        turnIndex: params.turnIndex
+      }, { final: params.final });
+      const inputBeadId = runOptions.inputBeadId;
+      if (shouldWriteExternalBeadNotes && inputBeadId && this.opts.beadsClient) {
+        const noteText = notesMode === "final-only" && !params.final ? "" : rendered;
+        if (noteText) {
+          const appendResult = this.opts.beadsClient.updateBeadNotes(inputBeadId, noteText);
+          if (!appendResult.ok) {
+            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() });
+            if (this.isJobFileOutputEnabled) {
+              try {
+                appendFileSync(this.resultPath(id), `
 
 ${appendError}
 `, "utf-8");
+              } catch {}
+            }
+          }
+        }
+      }
+      if (outputFile) {
+        try {
+          if (notesMode === "final-only") {
+            writeFileSync3(outputFile, rendered, "utf-8");
+          } else {
+            appendFileSync(outputFile, rendered, "utf-8");
+          }
         } catch {}
       }
-      return false;
+      return true;
     };
+    const appendResultToInputBead = (params) => writeUnifiedHandoff(params);
     const applyAutoCommitCheckpoint = (target, autoCommitPolicy2) => {
       const autoCommitResult = runAutoCommitCheckpoint({
         autoCommitPolicy: autoCommitPolicy2,
@@ -25558,14 +25681,24 @@ ${appendError}
         return;
       const now = Date.now();
       lastActivityMs = now;
+      const previousStatus = statusSnapshot.status;
       setStatus({ status: "running", current_event: "starting", last_event_at_ms: now });
+      if (previousStatus !== "running") {
+        appendTimelineEvent(createStatusChangeEvent("running", previousStatus));
+      }
+      appendTimelineEvent(createControlSignalEvent("resume_consumed", {
+        source: "runtime",
+        previous_status: previousStatus,
+        next_status: "running",
+        task_preview: task.replace(/\s+/g, " ").slice(0, 240)
+      }));
       silenceWarnEmitted = false;
       try {
         const output = await resumeFn(task);
         latestOutput = output;
         if (this.isJobFileOutputEnabled) {
           mkdirSync4(this.jobDir(id), { recursive: true });
-          writeFileSync3(this.resultPath(id), output, "utf-8");
+          writeFileSync3(this.resultPath(id), lastTurnSummaryTextContent || output, "utf-8");
         }
         try {
           this.withSqliteOperation("upsertResult:resume_turn", (client) => client.upsertResult(id, output));
@@ -25582,11 +25715,14 @@ ${appendError}
         const readOnlyClose = shouldAutoCloseReadOnlyKeepAlive(output);
         const isWaitingTurn = !readOnlyClose && !passFinalize;
         applyAutoCommitCheckpoint(isWaitingTurn ? "waiting" : "terminal", autoCommitPolicy);
-        appendResultToInputBead({
+        writeUnifiedHandoff({
           output,
           model: statusSnapshot.model ?? "unknown",
           backend: statusSnapshot.backend ?? "unknown",
-          status: isWaitingTurn ? "waiting" : "done"
+          status: isWaitingTurn ? "waiting" : "done",
+          final: false,
+          turnIndex: runMetrics.turns,
+          tokenUsage: runMetrics.token_usage
         });
         if (!isWaitingTurn) {
           closeKeepAliveSession();
@@ -25663,11 +25799,14 @@ ${appendError}
       if (keepAliveSession) {
         const hasPendingKeepAliveOutput = Boolean(latestOutput && statusSnapshot.status === "waiting" && !shouldAutoCloseReadOnlyKeepAlive(latestOutput));
         if (hasPendingKeepAliveOutput) {
-          const appendSucceeded = appendResultToInputBead({
+          const appendSucceeded = writeUnifiedHandoff({
             output: latestOutput,
             model: statusSnapshot.model ?? "unknown",
             backend: statusSnapshot.backend ?? "unknown",
-            status: "cancelled"
+            status: "cancelled",
+            final: false,
+            turnIndex: runMetrics.turns,
+            tokenUsage: runMetrics.token_usage
           });
           if (appendSucceeded) {
             skipFinalKeepAliveInputBeadAppend = true;
@@ -25679,7 +25818,7 @@ ${appendError}
       killFn?.();
     };
     process.once("SIGTERM", sigtermHandler);
-    const runOptionsWithBoundary = runOptions.workingDirectory ? { ...runOptions, worktreeBoundary: runOptions.workingDirectory } : runOptions;
+    const runOptionsWithBoundary = runOptions.workingDirectory ? { ...runOptions, worktreeBoundary: runOptions.workingDirectory, suppressRunnerFileOutput: true } : { ...runOptions, suppressRunnerFileOutput: true };
     try {
       const result = await runner.run(runOptionsWithBoundary, (delta) => {
         const toolMatch = delta.match(/\u2699 (.+?)\u2026/);
@@ -25847,7 +25986,20 @@ ${appendError}
             context_pct: contextUtilization?.context_pct,
             context_health: contextUtilization?.context_health
           });
+          lastTurnSummaryIndex = metricEvent.turn_index;
+          lastTurnSummaryTextContent = turnTextAccumulator;
           appendTimelineEvent(createTurnSummaryEvent(metricEvent.turn_index, metricEvent.token_usage, metricEvent.finish_reason, turnTextAccumulator || undefined, contextUtilization?.context_pct, contextUtilization?.context_health));
+          if (!keepAliveSession && !runOptions.keepAlive) {
+            writeUnifiedHandoff({
+              output: turnTextAccumulator,
+              model: statusSnapshot.model ?? "unknown",
+              backend: statusSnapshot.backend ?? "unknown",
+              status: "done",
+              final: false,
+              turnIndex: metricEvent.turn_index,
+              tokenUsage: metricEvent.token_usage ?? runMetrics.token_usage
+            });
+          }
           turnTextAccumulator = "";
           return;
         }
@@ -25891,16 +26043,33 @@ ${appendError}
           try {
             const parsed = JSON.parse(line);
             if (parsed?.type === "steer" && typeof parsed.message === "string") {
-              steerFn?.(parsed.message).catch(() => {});
+              appendTimelineEvent(createControlSignalEvent("steer_consumed", {
+                source: "runtime",
+                previous_status: statusSnapshot.status,
+                message_preview: parsed.message.replace(/\s+/g, " ").slice(0, 240)
+              }));
+              steerFn?.(parsed.message).catch((error2) => {
+                appendTimelineEvent(createControlSignalEvent("steer_failed", {
+                  source: "runtime",
+                  previous_status: statusSnapshot.status,
+                  error_message: error2 instanceof Error ? error2.message : String(error2)
+                }));
+              });
             } else if (parsed?.type === "resume" && typeof parsed.task === "string") {
               handleResumeTurn(parsed.task);
             } else if (parsed?.type === "prompt" && typeof parsed.message === "string") {
               console.error('[specialists] DEPRECATED: FIFO message {type:"prompt"} is deprecated. Use {type:"resume", task:"..."} instead.');
               handleResumeTurn(parsed.message);
             } else if (parsed?.type === "close") {
+              appendTimelineEvent(createControlSignalEvent("close_consumed", { source: "runtime", previous_status: statusSnapshot.status }));
               closeKeepAliveSession();
             }
-          } catch {}
+          } catch (error2) {
+            appendTimelineEvent(createControlSignalEvent("fifo_parse_error", {
+              source: "runtime",
+              error_message: error2 instanceof Error ? error2.message : String(error2)
+            }));
+          }
         });
         fifoReadline.on("error", (error2) => {
           console.error(`[supervisor] FIFO read error: ${String(error2)}`);
@@ -25976,7 +26145,7 @@ ${appendError}
       latestOutput = result.output;
       if (this.isJobFileOutputEnabled) {
         mkdirSync4(this.jobDir(id), { recursive: true });
-        writeFileSync3(this.resultPath(id), latestOutput, "utf-8");
+        writeFileSync3(this.resultPath(id), lastTurnSummaryTextContent || latestOutput, "utf-8");
       }
       const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
       const finalResult = {
@@ -26010,13 +26179,16 @@ ${appendError}
         } else if (shouldAutoFinalizeKeepAlive(finalResult.output)) {
           await closeKeepAliveSession();
         } else {
-          appendResultToInputBead({
+          writeUnifiedHandoff({
             output: finalResult.output,
             model: finalResult.model,
             backend: finalResult.backend,
             status: "waiting",
+            final: false,
+            turnIndex: runMetrics.turns,
             promptHash: finalResult.promptHash,
-            durationMs: finalResult.durationMs
+            durationMs: finalResult.durationMs,
+            tokenUsage: finalResult.metrics?.token_usage
           });
           skipFinalKeepAliveInputBeadAppend = true;
           setWaitingStatus({
@@ -26035,18 +26207,21 @@ ${appendError}
       const appendedStatus = keepAliveSession && !shouldAutoCloseReadOnlyKeepAlive(finalResult.output) ? "waiting" : "done";
       const shouldSkipFinalInputBeadAppend = keepAliveSession && skipFinalKeepAliveInputBeadAppend;
       if (!shouldSkipFinalInputBeadAppend) {
-        appendResultToInputBead({
-          output: finalResult.output,
+        writeUnifiedHandoff({
+          output: lastTurnSummaryTextContent || finalResult.output,
           model: finalResult.model,
           backend: finalResult.backend,
           status: appendedStatus,
+          final: true,
+          turnIndex: lastTurnSummaryIndex || runMetrics.turns,
           promptHash: finalResult.promptHash,
-          durationMs: finalResult.durationMs
+          durationMs: finalResult.durationMs,
+          tokenUsage: finalResult.metrics?.token_usage
         });
       }
       if (ownsBead && finalResult.beadId) {
-        this.opts.beadsClient?.updateBeadNotes(finalResult.beadId, formatBeadNotes({
-          output: finalResult.output,
+        this.opts.beadsClient?.updateBeadNotes(finalResult.beadId, formatHandoffBlock({
+          output: lastTurnSummaryTextContent || finalResult.output,
           promptHash: finalResult.promptHash,
           durationMs: finalResult.durationMs,
           model: finalResult.model,
@@ -26054,11 +26229,13 @@ ${appendError}
           specialist: runOptions.name,
           jobId: id,
           status: "done",
-          timestamp: new Date().toISOString()
-        }));
+          timestamp: new Date().toISOString(),
+          tokenUsage: finalResult.metrics?.token_usage,
+          turnIndex: lastTurnSummaryIndex || runMetrics.turns
+        }, { final: true }));
       } else if (shouldWriteExternalBeadNotes && !inputBeadId && finalResult.beadId) {
-        this.opts.beadsClient?.updateBeadNotes(finalResult.beadId, formatBeadNotes({
-          output: finalResult.output,
+        this.opts.beadsClient?.updateBeadNotes(finalResult.beadId, formatHandoffBlock({
+          output: lastTurnSummaryTextContent || finalResult.output,
           promptHash: finalResult.promptHash,
           durationMs: finalResult.durationMs,
           model: finalResult.model,
@@ -26066,8 +26243,10 @@ ${appendError}
           specialist: runOptions.name,
           jobId: id,
           status: "done",
-          timestamp: new Date().toISOString()
-        }));
+          timestamp: new Date().toISOString(),
+          tokenUsage: finalResult.metrics?.token_usage,
+          turnIndex: lastTurnSummaryIndex || runMetrics.turns
+        }, { final: true }));
       }
       if (finalResult.beadId) {
         const liveJobs = this.listLiveJobsForBead(finalResult.beadId).filter((liveJobId) => liveJobId !== id);
@@ -26171,7 +26350,10 @@ ${appendError}
         output: latestOutput || errorMsg,
         model: statusSnapshot.model ?? "unknown",
         backend: statusSnapshot.backend ?? "unknown",
-        status: "error"
+        status: "error",
+        final: false,
+        turnIndex: runMetrics.turns,
+        tokenUsage: runMetrics.token_usage
       });
       this.writeReadyMarker(id);
       throw err;
@@ -30132,11 +30314,13 @@ async function launchSpecialist(opts) {
       keepAlive: opts.args.keepAlive,
       noKeepAlive: opts.args.noKeepAlive,
       beadsWriteNotes: opts.beadsWriteNotes,
+      notesMode: opts.specialist.specialist.notes_mode,
       forceJob: opts.args.forceJob,
       permissionRequired: opts.perm,
       workingDirectory: opts.workingDirectory,
       reusedFromJobId: opts.reusedFromJobId,
-      worktreeOwnerJobId: opts.worktreeOwnerJobId
+      worktreeOwnerJobId: opts.worktreeOwnerJobId,
+      output_file: opts.specialist.specialist.output_file
     },
     beadsClient: opts.beadsClient,
     stallDetection: opts.specialist.specialist.stall_detection,
@@ -39646,6 +39830,7 @@ var init_stdin_buffer = __esm(() => {
 import * as fs2 from "fs";
 import { createRequire as createRequire3 } from "module";
 import * as path2 from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
 
 class ProcessTerminal {
   wasRaw = false;
@@ -39730,17 +39915,23 @@ class ProcessTerminal {
     if (process.platform !== "win32")
       return;
     try {
-      const koffi = cjsRequire("koffi");
-      const k32 = koffi.load("kernel32.dll");
-      const GetStdHandle = k32.func("void* __stdcall GetStdHandle(int)");
-      const GetConsoleMode = k32.func("bool __stdcall GetConsoleMode(void*, _Out_ uint32_t*)");
-      const SetConsoleMode = k32.func("bool __stdcall SetConsoleMode(void*, uint32_t)");
-      const STD_INPUT_HANDLE = -10;
-      const ENABLE_VIRTUAL_TERMINAL_INPUT = 512;
-      const handle = GetStdHandle(STD_INPUT_HANDLE);
-      const mode = new Uint32Array(1);
-      GetConsoleMode(handle, mode);
-      SetConsoleMode(handle, mode[0] | ENABLE_VIRTUAL_TERMINAL_INPUT);
+      const arch = process.arch;
+      if (arch !== "x64" && arch !== "arm64")
+        return;
+      const moduleDir = path2.dirname(fileURLToPath4(import.meta.url));
+      const nativePath = path2.join("native", "win32", "prebuilds", `win32-${arch}`, "win32-console-mode.node");
+      const candidates = [
+        path2.join(moduleDir, "..", nativePath),
+        path2.join(moduleDir, nativePath),
+        path2.join(path2.dirname(process.execPath), nativePath)
+      ];
+      for (const modulePath of candidates) {
+        try {
+          const helper = cjsRequire(modulePath);
+          helper.enableVirtualTerminalInput?.();
+          return;
+        } catch {}
+      }
     } catch {}
   }
   async drainInput(maxMs = 1000, idleMs = 50) {
@@ -40309,6 +40500,16 @@ var init_control = __esm(() => {
 function formatTime(t) {
   return new Date(t).toISOString().slice(11, 19);
 }
+function formatDateTime(t) {
+  const d = new Date(t);
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, "0");
+  const dd = String(d.getDate()).padStart(2, "0");
+  const hh = String(d.getHours()).padStart(2, "0");
+  const mi = String(d.getMinutes()).padStart(2, "0");
+  const ss = String(d.getSeconds()).padStart(2, "0");
+  return `${yyyy}-${mm}-${dd} ${hh}:${mi}:${ss}`;
+}
 function formatElapsed(seconds) {
   if (seconds < 60)
     return `${seconds}s`;
@@ -40415,6 +40616,26 @@ function formatEventLine(event, options2) {
   } else if (event.type === "error") {
     detailParts.push(`source=${event.source}`);
     detailParts.push(`error=${event.error_message}`);
+  } else if (event.type === "control_signal") {
+    detailParts.push(`action=${event.action}`);
+    detailParts.push(`source=${event.source}`);
+    if (event.previous_status || event.next_status) {
+      detailParts.push(`status=${event.previous_status ?? "?"}->${event.next_status ?? "?"}`);
+    }
+    if (event.pid !== undefined)
+      detailParts.push(`pid=${event.pid}`);
+    if (event.signal)
+      detailParts.push(`signal=${event.signal}`);
+    if (event.force !== undefined)
+      detailParts.push(`force=${event.force}`);
+    if (event.reason)
+      detailParts.push(`reason=${event.reason}`);
+    if (event.message_preview)
+      detailParts.push(`message="${event.message_preview}"`);
+    if (event.task_preview)
+      detailParts.push(`task="${event.task_preview}"`);
+    if (event.error_message)
+      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}`);
@@ -40518,6 +40739,8 @@ function formatEventInline(event) {
     }
     case "stale_warning":
       return yellow10(`[warning] ${event.reason}: ${Math.round(event.silence_ms / 1000)}s silent`);
+    case "control_signal":
+      return dim9(`[control] ${event.action}`);
     case "error":
       return red2(`[error] ${event.source}: ${event.error_message}`);
     default:
@@ -40556,7 +40779,8 @@ var init_format_helpers = __esm(() => {
     error: "ERROR",
     auto_commit_success: "AUTO+",
     auto_commit_skipped: "AUTO-",
-    auto_commit_failed: "AUTO!"
+    auto_commit_failed: "AUTO!",
+    control_signal: "CTRL"
   };
 });
 
@@ -40614,7 +40838,7 @@ function createFinalizeSupervisor(jobsDir) {
     throw new Error("finalize supervisor runner is not used");
   } };
   const runOptions = {};
-  return new Supervisor({ runner, runOptions, jobsDir });
+  return new Supervisor({ runner, runOptions, jobsDir, beadsClient: new BeadsClient });
 }
 function findReviewerPassInChain(supervisor, chainId) {
   for (const id of supervisor.listChainJobIds(chainId)) {
@@ -40628,13 +40852,27 @@ function findReviewerPassInChain(supervisor, chainId) {
 }
 async function stopJob(jobId, opts = {}) {
   const jobsDir = opts.jobsDir ?? resolveJobsDir(process.cwd());
-  const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
+  const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir, beadsClient: new BeadsClient });
   try {
     const status = supervisor.readStatus(jobId);
     if (!status)
       throw new Error(`No job found: ${jobId}`);
     if (status.status === "done" || status.status === "error" || status.status === "cancelled") {
       process.stderr.write(`${dim10(`Job ${jobId} already finalized (${status.status}).`)}
+`);
+      return;
+    }
+    let statusForBeadClose = status;
+    let finalizedFromWaiting = false;
+    if (status.status === "waiting" && status.bead_id) {
+      const finalized = supervisor.finalizeWaitingJob(jobId);
+      if (finalized) {
+        statusForBeadClose = finalized;
+        finalizedFromWaiting = true;
+      }
+    }
+    if (!finalizedFromWaiting && (statusForBeadClose.status === "done" || statusForBeadClose.status === "error" || statusForBeadClose.status === "cancelled")) {
+      process.stderr.write(`${dim10(`Job ${jobId} already finalized (${statusForBeadClose.status}).`)}
 `);
       return;
     }
@@ -40644,8 +40882,18 @@ async function stopJob(jobId, opts = {}) {
     const tmuxSession = status.tmux_session;
     const isAlreadyDead = !isProcessAlive(pid, status.started_at_ms);
     const force = opts.force ?? false;
+    supervisor.emitControlEvent(jobId, "stop_requested", {
+      source: "cli",
+      pid,
+      previous_status: status.status,
+      force,
+      reason: isAlreadyDead ? "pid_already_dead" : "operator_stop",
+      signal: force ? "SIGTERM/SIGKILL" : "SIGTERM",
+      tmux_session: tmuxSession
+    });
     if (force && isAlreadyDead) {
-      supervisor.updateJobStatus(jobId, "error");
+      supervisor.updateJobStatus(jobId, "error", `Force stop requested; PID ${pid} already dead`);
+      supervisor.emitControlEvent(jobId, "stop_marked_error", { source: "cli", pid, previous_status: status.status, next_status: "error", force, reason: "pid_already_dead" });
       supervisor.aggregateJobMetricsBestEffort(jobId);
       tryKillProcessGroup(pid);
       process.stdout.write(`${green10("\u2713")} Marked ${jobId} as error (PID ${pid} already dead)
@@ -40653,15 +40901,18 @@ async function stopJob(jobId, opts = {}) {
     } else {
       const terminalStatus = resolveTerminalStatus(jobId);
       supervisor.updateJobStatus(jobId, terminalStatus);
+      supervisor.emitControlEvent(jobId, "status_marked_before_signal", { source: "cli", pid, previous_status: status.status, next_status: terminalStatus, force });
       supervisor.aggregateJobMetricsBestEffort(jobId);
       try {
         process.kill(pid, "SIGTERM");
+        supervisor.emitControlEvent(jobId, "signal_sent", { source: "cli", pid, signal: "SIGTERM", force, next_status: terminalStatus });
         process.stdout.write(`${green10("\u2713")} Marked ${jobId} as ${terminalStatus} and sent SIGTERM to PID ${pid}
 `);
         if (force) {
           const exited = await waitForProcessExit(pid, 5000);
           if (!exited) {
-            supervisor.updateJobStatus(jobId, "error");
+            supervisor.updateJobStatus(jobId, "error", `Force stop escalated; PID ${pid} ignored SIGTERM`);
+            supervisor.emitControlEvent(jobId, "force_stop_escalated", { source: "cli", pid, signal: "SIGKILL", previous_status: terminalStatus, next_status: "error", force: true, reason: "sigterm_timeout" });
             tryKillProcessGroup(pid);
             process.stderr.write(`${red3("Force stop:")} PID ${pid} ignored SIGTERM, marked ${jobId} as error and killed process group.
 `);
@@ -40670,7 +40921,8 @@ async function stopJob(jobId, opts = {}) {
       } catch (err) {
         if (err.code === "ESRCH") {
           if (force) {
-            supervisor.updateJobStatus(jobId, "error");
+            supervisor.updateJobStatus(jobId, "error", `Force stop escalated; PID ${pid} ignored SIGTERM`);
+            supervisor.emitControlEvent(jobId, "force_stop_escalated", { source: "cli", pid, signal: "SIGKILL", previous_status: terminalStatus, next_status: "error", force: true, reason: "sigterm_timeout" });
             tryKillProcessGroup(pid);
             process.stdout.write(`${green10("\u2713")} Marked ${jobId} as error (PID ${pid} already gone)
 `);
@@ -40684,12 +40936,13 @@ async function stopJob(jobId, opts = {}) {
       }
     }
     if (tmuxSession) {
+      supervisor.emitControlEvent(jobId, "tmux_kill_requested", { source: "cli", pid, tmux_session: tmuxSession });
       killTmuxSession(tmuxSession);
       process.stdout.write(`${dim10(`  tmux session ${tmuxSession} killed`)}
 `);
     }
     if (status.bead_id) {
-      const finalStatus = supervisor.readStatus(jobId)?.status ?? "cancelled";
+      const finalStatus = supervisor.readStatus(jobId)?.status ?? statusForBeadClose.status ?? "cancelled";
       const beads = new BeadsClient;
       const liveJobs = supervisor.listLiveJobsForBead(status.bead_id).filter((liveJobId) => liveJobId !== jobId);
       if (opts.closeBeadAnyway || liveJobs.length === 0) {
@@ -40774,7 +41027,7 @@ async function appendBeadNote(beadId, text, opts = {}) {
   if (!beadId || !text)
     return { ok: false, error: "beads unavailable or empty payload" };
   return await new Promise((resolve9) => {
-    const child = spawn5("bd", ["update", beadId, "--notes", text], {
+    const child = spawn5("bd", ["update", beadId, "--append-notes", text], {
       stdio: ["ignore", "ignore", "pipe"]
     });
     const timer = opts.timeoutMs ? setTimeout(() => {
@@ -47152,7 +47405,7 @@ var init_epic = __esm(() => {
 // src/cli/version-check.ts
 import { spawnSync as spawnSync16 } from "child_process";
 import { existsSync as existsSync22, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync13 } from "fs";
-import { dirname as dirname11, join as join26 } from "path";
+import { dirname as dirname12, join as join26 } from "path";
 import { createRequire as createRequire4 } from "module";
 function readBundledPackageVersion(requireFn = require3) {
   for (const candidate of ["../package.json", "../../package.json"]) {
@@ -47186,7 +47439,7 @@ function readCachedVersionCheck() {
   return readCache();
 }
 function writeCache(cache) {
-  mkdirSync11(dirname11(CACHE_PATH), { recursive: true });
+  mkdirSync11(dirname12(CACHE_PATH), { recursive: true });
   writeFileSync13(CACHE_PATH, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
@@ -49110,8 +49363,32 @@ function deriveStartupSnapshot(status, events) {
   return Object.keys(merged).length > 0 ? merged : null;
 }
 function deriveApiError(events) {
-  const errorEvent = [...events].reverse().find((event) => event.type === "error");
-  return errorEvent?.error_message ?? null;
+  for (const event of [...events].reverse()) {
+    if (event.type === "error")
+      return event.error_message;
+    if (event.type === "run_complete" && event.error)
+      return event.error;
+    if (event.type === "control_signal" && event.error_message)
+      return event.error_message;
+  }
+  return null;
+}
+function deriveTerminalReason(events) {
+  for (const event of [...events].reverse()) {
+    if (event.type === "run_complete") {
+      return event.error ?? event.exit_reason ?? event.status;
+    }
+    if (event.type === "control_signal") {
+      return event.error_message ?? event.reason ?? event.action;
+    }
+    if (event.type === "status_change") {
+      return `status ${event.previous_status ?? "?"} -> ${event.status}`;
+    }
+  }
+  return null;
+}
+function logHint(jobId) {
+  return ` Inspect with: specialists log ${jobId} --limit 200`;
 }
 function formatPayloadPreamble(payloadJson) {
   if (!payloadJson)
@@ -49269,7 +49546,7 @@ async function run18() {
           const apiError2 = status2.error ?? deriveApiError(events2);
           const output3 = readResultOutput();
           if (!output3) {
-            const message = apiError2 ? `Job ${jobId} failed: ${apiError2}` : `Result not found for job ${jobId}`;
+            const message = apiError2 ? `Job ${jobId} failed: ${apiError2}.${logHint(jobId)}` : `Result not found for job ${jobId}.${logHint(jobId)}`;
             if (args.json) {
               emitJson(status2, null, message, startupContext2);
             } else {
@@ -49288,11 +49565,28 @@ async function run18() {
         }
         if (status2.status === "error") {
           const startupContext2 = deriveStartupSnapshot(status2, readTimelineEventsForResult(sqliteClient, jobsDir, jobId));
-          const message = `Job ${jobId} failed: ${status2.error ?? "unknown error"}`;
+          const events2 = readTimelineEventsForResult(sqliteClient, jobsDir, jobId);
+          const reason = status2.error ?? deriveApiError(events2) ?? deriveTerminalReason(events2) ?? "unknown error";
+          const message = `Job ${jobId} failed: ${reason}.${logHint(jobId)}`;
+          if (args.json) {
+            emitJson(status2, null, message, startupContext2);
+          } else {
+            process.stderr.write(`${red4(`Job ${jobId} failed:`)} ${reason}
+${dim12(logHint(jobId).trim())}
+`);
+          }
+          process.exit(1);
+        }
+        if (status2.status === "cancelled") {
+          const events2 = readTimelineEventsForResult(sqliteClient, jobsDir, jobId);
+          const startupContext2 = deriveStartupSnapshot(status2, events2);
+          const reason = status2.error ?? deriveTerminalReason(events2) ?? "cancelled";
+          const message = `Job ${jobId} cancelled: ${reason}.${logHint(jobId)}`;
           if (args.json) {
             emitJson(status2, null, message, startupContext2);
           } else {
-            process.stderr.write(`${red4(`Job ${jobId} failed:`)} ${status2.error ?? "unknown error"}
+            process.stderr.write(`${red4(`Job ${jobId} cancelled:`)} ${reason}
+${dim12(logHint(jobId).trim())}
 `);
           }
           process.exit(1);
@@ -49368,14 +49662,30 @@ async function run18() {
       }
       return;
     }
+    if (status.status === "cancelled") {
+      const events2 = readTimelineEventsForResult(sqliteClient, jobsDir, jobId);
+      const startupContext2 = deriveStartupSnapshot(status, events2);
+      const reason = status.error ?? deriveTerminalReason(events2) ?? "cancelled";
+      const message = `Job ${jobId} cancelled: ${reason}.${logHint(jobId)}`;
+      if (args.json) {
+        emitJson(status, null, message, startupContext2);
+      } else {
+        process.stderr.write(`${red4(`Job ${jobId} cancelled:`)} ${reason}
+${dim12(logHint(jobId).trim())}
+`);
+      }
+      process.exit(1);
+    }
     if (status.status === "error") {
       const events2 = readTimelineEventsForResult(sqliteClient, jobsDir, jobId);
       const startupContext2 = deriveStartupSnapshot(status, events2);
-      const message = `Job ${jobId} failed: ${status.error ?? deriveApiError(events2) ?? "unknown error"}`;
+      const reason = status.error ?? deriveApiError(events2) ?? deriveTerminalReason(events2) ?? "unknown error";
+      const message = `Job ${jobId} failed: ${reason}.${logHint(jobId)}`;
       if (args.json) {
         emitJson(status, null, message, startupContext2);
       } else {
-        process.stderr.write(`${red4(`Job ${jobId} failed:`)} ${status.error ?? deriveApiError(events2) ?? "unknown error"}
+        process.stderr.write(`${red4(`Job ${jobId} failed:`)} ${reason}
+${dim12(logHint(jobId).trim())}
 `);
       }
       process.exit(1);
@@ -49384,7 +49694,7 @@ async function run18() {
     const apiError = status.error ?? deriveApiError(events);
     const output2 = readResultOutput();
     if (!output2) {
-      const message = apiError ? `Job ${jobId} failed: ${apiError}` : `Result not found for job ${jobId}`;
+      const message = apiError ? `Job ${jobId} failed: ${apiError}.${logHint(jobId)}` : `Result not found for job ${jobId}.${logHint(jobId)}`;
       if (args.json) {
         emitJson(status, null, message);
       } else {
@@ -50250,13 +50560,482 @@ var init_feed2 = __esm(() => {
   init_format_helpers();
 });
 
+// src/cli/log.ts
+var exports_log = {};
+__export(exports_log, {
+  run: () => run20
+});
+import { existsSync as existsSync28, readdirSync as readdirSync14, statSync as statSync7 } from "fs";
+import { basename as basename9, join as join32 } from "path";
+function parseSince2(value) {
+  if (value.includes("T") || value.includes("-"))
+    return new Date(value).getTime();
+  const match = value.match(/^(\d+)([smhd])$/);
+  if (!match)
+    return;
+  const n = Number(match[1]);
+  const unit = match[2];
+  const ms = { s: 1000, m: 60000, h: 3600000, d: 86400000 };
+  return Date.now() - n * ms[unit];
+}
+function parseArgs12(argv) {
+  let jobId;
+  let specialist;
+  let beadId;
+  let nodeId;
+  let repo;
+  let since;
+  let limit = 200;
+  let follow2 = false;
+  let json = false;
+  let allEvents = false;
+  for (let i = 0;i < argv.length; i += 1) {
+    const token = argv[i];
+    if ((token === "--job" || token === "--job-id") && argv[i + 1]) {
+      jobId = argv[++i];
+      continue;
+    }
+    if (token === "--specialist" && argv[i + 1]) {
+      specialist = argv[++i];
+      continue;
+    }
+    if ((token === "--bead" || token === "--bead-id") && argv[i + 1]) {
+      beadId = argv[++i];
+      continue;
+    }
+    if (token === "--node" && argv[i + 1]) {
+      nodeId = argv[++i];
+      continue;
+    }
+    if (token === "--repo" && argv[i + 1]) {
+      repo = argv[++i];
+      continue;
+    }
+    if (token === "--since" && argv[i + 1]) {
+      since = parseSince2(argv[++i]);
+      continue;
+    }
+    if (token === "--limit" && argv[i + 1]) {
+      limit = Math.max(1, Number(argv[++i]) || limit);
+      continue;
+    }
+    if (token === "--follow" || token === "-f") {
+      follow2 = true;
+      continue;
+    }
+    if (token === "--json") {
+      json = true;
+      continue;
+    }
+    if (token === "--all-events" || token === "--verbose") {
+      allEvents = true;
+      continue;
+    }
+    if (!token.startsWith("-") && !jobId) {
+      jobId = token;
+      continue;
+    }
+    throw new Error(`Unknown option: ${token}`);
+  }
+  return { jobId, specialist, beadId, nodeId, repo, since, limit, follow: follow2, json, allEvents };
+}
+function discoverDbTargets(cwd, repoFilter) {
+  const cwdLocation = resolveObservabilityDbLocation(cwd);
+  if (existsSync28(cwdLocation.dbPath)) {
+    const repo = basename9(cwdLocation.gitRoot);
+    if (!repoFilter || repo === repoFilter) {
+      return [{ repo, root: cwdLocation.gitRoot, dbPath: cwdLocation.dbPath, source: "cwd" }];
+    }
+    return [];
+  }
+  const targets = [];
+  let entries = [];
+  try {
+    entries = readdirSync14(cwd);
+  } catch {
+    return [];
+  }
+  for (const entry of entries) {
+    const root = join32(cwd, entry);
+    try {
+      if (!statSync7(root).isDirectory())
+        continue;
+    } catch {
+      continue;
+    }
+    const dbPath = join32(root, ".specialists", "db", "observability.db");
+    if (!existsSync28(dbPath))
+      continue;
+    if (repoFilter && entry !== repoFilter)
+      continue;
+    targets.push({ repo: entry, root, dbPath, source: "child" });
+  }
+  return targets.sort((a, b) => a.repo.localeCompare(b.repo));
+}
+function matches(status, options2) {
+  if (options2.jobId && status.id !== options2.jobId)
+    return false;
+  if (options2.specialist && status.specialist !== options2.specialist)
+    return false;
+  if (options2.beadId && status.bead_id !== options2.beadId)
+    return false;
+  if (options2.nodeId && status.node_id !== options2.nodeId)
+    return false;
+  return true;
+}
+function isRuntimeEvent(event) {
+  if (RUNTIME_EVENT_TYPES.has(event.type))
+    return true;
+  if (event.type === "meta") {
+    return Boolean(event.model.startsWith("gitnexus_") || event.model.startsWith("bead_") || event.backend === "supervisor");
+  }
+  return false;
+}
+function toRows(target, statuses, options2, readEvents) {
+  const rows = [];
+  for (const status of statuses) {
+    if (!matches(status, options2))
+      continue;
+    const rowPath = status.worktree_path ?? target.root;
+    const events = readEvents(status.id).filter((event) => {
+      if (options2.since !== undefined && event.t < options2.since)
+        return false;
+      if (options2.allEvents)
+        return true;
+      return isRuntimeEvent(event);
+    });
+    for (const event of events) {
+      rows.push({
+        jobId: status.id,
+        specialist: status.specialist,
+        beadId: status.bead_id,
+        nodeId: status.node_id,
+        repo: target.repo,
+        path: rowPath,
+        dbPath: target.dbPath,
+        branch: status.branch,
+        status: status.status,
+        pid: status.pid,
+        model: status.model,
+        backend: status.backend,
+        chainId: status.chain_id,
+        chainRootJobId: status.chain_root_job_id,
+        chainRootBeadId: status.chain_root_bead_id,
+        event
+      });
+    }
+    if (events.length === 0 && (options2.jobId || options2.beadId || options2.specialist || options2.nodeId)) {
+      rows.push({
+        jobId: status.id,
+        specialist: status.specialist,
+        beadId: status.bead_id,
+        nodeId: status.node_id,
+        repo: target.repo,
+        path: rowPath,
+        dbPath: target.dbPath,
+        branch: status.branch,
+        status: status.status,
+        pid: status.pid,
+        model: status.model,
+        backend: status.backend,
+        chainId: status.chain_id,
+        chainRootJobId: status.chain_root_job_id,
+        chainRootBeadId: status.chain_root_bead_id,
+        event: { t: status.last_event_at_ms ?? status.started_at_ms, type: "status_snapshot" }
+      });
+    }
+  }
+  rows.sort((a, b) => a.event.t - b.event.t || a.jobId.localeCompare(b.jobId) || (a.event.seq ?? 0) - (b.event.seq ?? 0));
+  const displayRows = options2.json ? rows : collapseDisplayDuplicates(rows);
+  return displayRows.slice(Math.max(0, displayRows.length - options2.limit));
+}
+function normalizedEventForDisplay(event) {
+  const normalized = { ...event };
+  delete normalized.t;
+  delete normalized.seq;
+  if (event.type === "run_complete")
+    delete normalized.elapsed_s;
+  return normalized;
+}
+function displayDuplicateKey(row) {
+  return JSON.stringify({
+    jobId: row.jobId,
+    event: normalizedEventForDisplay(row.event)
+  });
+}
+function collapseDisplayDuplicates(rows) {
+  const collapsed = [];
+  const lastByKey = new Map;
+  for (const row of rows) {
+    const key = displayDuplicateKey(row);
+    const previous = lastByKey.get(key);
+    if (previous && row.event.t - previous.event.t <= DISPLAY_DUPLICATE_WINDOW_MS)
+      continue;
+    collapsed.push(row);
+    lastByKey.set(key, row);
+  }
+  return collapsed;
+}
+function compact(value, max = 240) {
+  const raw = typeof value === "string" ? value : JSON.stringify(value);
+  const flat = (raw ?? "").replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+}
+function eventDetail(event) {
+  if (event.type === "run_start")
+    return "started";
+  if (event.type === "control_signal") {
+    return [
+      `action=${event.action}`,
+      `source=${event.source}`,
+      event.previous_status || event.next_status ? `status=${event.previous_status ?? "?"}->${event.next_status ?? "?"}` : null,
+      event.pid !== undefined ? `pid=${event.pid}` : null,
+      event.signal ? `signal=${event.signal}` : null,
+      event.force !== undefined ? `force=${event.force}` : null,
+      event.reason ? `reason=${compact(event.reason, 160)}` : null,
+      event.message_preview ? `message="${compact(event.message_preview, 180)}"` : null,
+      event.task_preview ? `task="${compact(event.task_preview, 180)}"` : null,
+      event.error_message ? `error=${compact(event.error_message, 180)}` : null
+    ].filter(Boolean).join(" ");
+  }
+  if (event.type === "status_change") {
+    return `status=${event.previous_status ?? "?"}->${event.status}`;
+  }
+  if (event.type === "run_complete") {
+    return [
+      `status=${event.status}`,
+      `elapsed=${formatElapsed(event.elapsed_s)}`,
+      event.exit_reason ? `exit=${event.exit_reason}` : null,
+      event.finish_reason ? `finish=${event.finish_reason}` : null,
+      event.error ? `error=${compact(event.error, 500)}` : null,
+      ...formatTokenUsageSummary(event.token_usage ?? event.metrics?.token_usage),
+      event.tool_calls ? `tools=${event.tool_calls.length}` : null
+    ].filter(Boolean).join(" ");
+  }
+  if (event.type === "tool") {
+    const args = event.args ? ` args=${compact(event.args, 300)}` : "";
+    const result = event.result_summary ? ` result=${compact(event.result_summary, 300)}` : "";
+    return `tool=${event.tool} phase=${event.phase}${event.is_error ? " error=true" : ""}${args}${result}`;
+  }
+  if (event.type === "error")
+    return `source=${event.source} error=${compact(event.error_message, 500)}`;
+  if (event.type === "meta")
+    return `model=${event.model} backend=${event.backend}${event.source ? ` source=${event.source}` : ""}`;
+  if (event.type === "stale_warning")
+    return `reason=${event.reason} silence_ms=${event.silence_ms} threshold_ms=${event.threshold_ms}${event.tool ? ` tool=${event.tool}` : ""}`;
+  if (event.type === "token_usage")
+    return `${formatTokenUsageSummary(event.token_usage).join(" ")} source=${event.source}`;
+  if (event.type === "turn_summary")
+    return `turn=${event.turn_index}${event.finish_reason ? ` finish=${event.finish_reason}` : ""}${event.context_pct !== undefined ? ` context=${event.context_pct.toFixed(2)}%` : ""}${event.text_content ? ` text="${compact(event.text_content, 160)}"` : ""}`;
+  if (event.type === "auto_commit_success" || event.type === "auto_commit_skipped" || event.type === "auto_commit_failed")
+    return `reason=${event.reason ?? ""}${event.commit_sha ? ` commit=${event.commit_sha}` : ""}${event.committed_files ? ` files=${event.committed_files.join(",")}` : ""}`.trim();
+  if (event.type === "finish_reason")
+    return `reason=${event.finish_reason} source=${event.source}`;
+  if (event.type === "compaction" || event.type === "retry")
+    return `phase=${event.phase}`;
+  if (event.type === "message")
+    return `phase=${event.phase} role=${event.role}`;
+  if (event.type === "turn")
+    return `phase=${event.phase}`;
+  return compact(event, 500);
+}
+function eventColor(event) {
+  switch (event.type) {
+    case "run_complete":
+      return event.status === "ERROR" ? red2 : event.status === "CANCELLED" ? yellow10 : green9;
+    case "stale_warning":
+    case "control_signal":
+    case "auto_commit_skipped":
+      return yellow10;
+    case "error":
+    case "extension_error":
+    case "auto_commit_failed":
+      return red2;
+    case "auto_commit_success":
+      return green9;
+    default:
+      return dim9;
+  }
+}
+function eventLabel(event) {
+  const rawType = event.type;
+  if (rawType === "status_snapshot")
+    return "SNAP";
+  switch (event.type) {
+    case "run_start":
+      return "START";
+    case "run_complete":
+      return event.status;
+    case "status_change":
+      return "STATUS";
+    case "control_signal":
+      return "CTRL";
+    case "stale_warning":
+      return "WARN";
+    case "auto_commit_success":
+      return "AUTO+";
+    case "auto_commit_skipped":
+      return "AUTO-";
+    case "auto_commit_failed":
+      return "AUTO!";
+    default:
+      return rawType.toUpperCase().slice(0, 6);
+  }
+}
+function formatWorktree(row) {
+  const base = row.path ? basename9(row.path) : row.repo ?? "-";
+  if (!row.repo || base === row.repo)
+    return base;
+  return `${row.repo}/${base}`;
+}
+function statusColor2(status) {
+  switch (status) {
+    case "done":
+      return green9;
+    case "error":
+      return red2;
+    case "cancelled":
+      return yellow10;
+    case "running":
+      return cyan6;
+    case "waiting":
+      return yellow10;
+    case "starting":
+      return yellow10;
+    default:
+      return dim9;
+  }
+}
+function printRow(row, json) {
+  if (json) {
+    console.log(JSON.stringify({
+      timestamp: new Date(row.event.t).toISOString(),
+      job_id: row.jobId,
+      specialist: row.specialist,
+      bead_id: row.beadId ?? null,
+      node_id: row.nodeId ?? null,
+      repo: row.repo ?? null,
+      path: row.path ?? null,
+      db_path: row.dbPath ?? null,
+      branch: row.branch ?? null,
+      worktree: formatWorktree(row),
+      status: row.status ?? null,
+      pid: row.pid ?? null,
+      model: row.model ?? null,
+      backend: row.backend ?? null,
+      chain_id: row.chainId ?? null,
+      chain_root_job_id: row.chainRootJobId ?? null,
+      chain_root_bead_id: row.chainRootBeadId ?? null,
+      event: row.event
+    }));
+    return;
+  }
+  const color = eventColor(row.event);
+  const label = color(bold11(eventLabel(row.event).padEnd(6)));
+  const status = row.status ?? "-";
+  const statusSegment = statusColor2(row.status)(`status=${status}`);
+  const head = [
+    dim9(formatDateTime(row.event.t)),
+    label,
+    row.jobId,
+    bold11(row.specialist),
+    dim9(`bead=${row.beadId ?? "-"}`),
+    row.nodeId ? dim9(`node=${row.nodeId}`) : null,
+    dim9(`worktree=${formatWorktree(row)}`),
+    statusSegment,
+    row.pid !== undefined ? dim9(`pid=${row.pid}`) : null
+  ].filter(Boolean).join(" ");
+  console.log(`${head} ${eventDetail(row.event)}`.trim());
+}
+async function run20(argv = process.argv.slice(3)) {
+  let options2;
+  try {
+    options2 = parseArgs12(argv);
+  } catch (error2) {
+    console.error(error2 instanceof Error ? error2.message : String(error2));
+    console.error("Usage: specialists|sp log [job-id] [--specialist <name>] [--bead <id>] [--node <id>] [--since <5m|iso>] [--limit <n>] [-f|--follow] [--json] [--all-events]");
+    process.exit(1);
+  }
+  const targets = discoverDbTargets(process.cwd(), options2.repo);
+  if (targets.length === 0) {
+    const suffix = options2.repo ? ` for repo '${options2.repo}'` : "";
+    console.error(`No specialists observability DB found${suffix}. Run from a repo root or a parent containing repos with .specialists/db/observability.db.`);
+    process.exit(1);
+  }
+  const clients = targets.map((target) => ({ target, client: createObservabilitySqliteClientAtPath(target.dbPath) }));
+  if (clients.every((entry) => !entry.client)) {
+    console.error("Observability SQLite DB is unavailable. Run: specialists db setup");
+    process.exit(1);
+  }
+  const printed = new Set;
+  const printSnapshot2 = () => {
+    const rows = clients.flatMap(({ target, client }) => {
+      if (!client)
+        return [];
+      return toRows(target, client.listStatuses(), options2, (jobId) => client.readEvents(jobId));
+    });
+    rows.sort((a, b) => a.event.t - b.event.t || (a.repo ?? "").localeCompare(b.repo ?? "") || a.jobId.localeCompare(b.jobId) || (a.event.seq ?? 0) - (b.event.seq ?? 0));
+    const limitedRows = rows.slice(Math.max(0, rows.length - options2.limit));
+    for (const row of limitedRows) {
+      const key = `${row.repo ?? ""}:${row.jobId}:${row.event.seq ?? row.event.t}:${row.event.type}`;
+      if (printed.has(key))
+        continue;
+      printed.add(key);
+      printRow(row, options2.json);
+    }
+    if (limitedRows.length === 0 && !options2.json && printed.size === 0)
+      console.error("No matching specialist log rows.");
+  };
+  try {
+    printSnapshot2();
+    if (!options2.follow)
+      return;
+    if (!options2.json)
+      console.error(`Following specialist runtime logs across ${targets.length} repo${targets.length === 1 ? "" : "s"}... (Ctrl+C to stop)`);
+    await new Promise((resolve11) => {
+      const interval = setInterval(printSnapshot2, 750);
+      const stop = () => {
+        clearInterval(interval);
+        resolve11();
+      };
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+    });
+  } finally {
+    for (const { client } of clients)
+      client?.close();
+  }
+}
+var DISPLAY_DUPLICATE_WINDOW_MS = 2000, RUNTIME_EVENT_TYPES;
+var init_log = __esm(() => {
+  init_observability_sqlite();
+  init_observability_db();
+  init_format_helpers();
+  RUNTIME_EVENT_TYPES = new Set([
+    "run_start",
+    "run_complete",
+    "status_change",
+    "control_signal",
+    "stale_warning",
+    "error",
+    "extension_error",
+    "model_change",
+    "retry",
+    "compaction",
+    "auto_commit_success",
+    "auto_commit_skipped",
+    "auto_commit_failed",
+    "status_snapshot"
+  ]);
+});
+
 // src/cli/steer.ts
 var exports_steer = {};
 __export(exports_steer, {
-  run: () => run20
+  run: () => run21
 });
 import { writeFileSync as writeFileSync14 } from "fs";
-async function run20() {
+async function run21() {
   const jobId = process.argv[3];
   const message = process.argv[4];
   if (!jobId || !message) {
@@ -50287,6 +51066,12 @@ async function run20() {
       const payload = JSON.stringify({ type: "steer", message }) + `
 `;
       writeFileSync14(status.fifo_path, payload, { flag: "a" });
+      supervisor.emitControlEvent(jobId, "steer_sent", {
+        source: "cli",
+        previous_status: status.status,
+        fifo_path: status.fifo_path,
+        message_preview: message.replace(/\s+/g, " ").slice(0, 240)
+      });
       process.stdout.write(`${green11("\u2713")} Steer message sent to job ${jobId}
 `);
     } catch (err) {
@@ -50307,10 +51092,10 @@ var init_steer = __esm(() => {
 // src/cli/resume.ts
 var exports_resume = {};
 __export(exports_resume, {
-  run: () => run21
+  run: () => run22
 });
 import { writeFileSync as writeFileSync15 } from "fs";
-async function run21() {
+async function run22() {
   const jobId = process.argv[3];
   const task = process.argv[4];
   if (!jobId || !task) {
@@ -50337,19 +51122,31 @@ async function run21() {
 `);
       process.exit(1);
     }
-    try {
-      const payload = JSON.stringify({ type: "resume", task }) + `
+    const payload = JSON.stringify({ type: "resume", task }) + `
 `;
+    try {
       writeFileSync15(status.fifo_path, payload, { flag: "a" });
-      process.stdout.write(`${green12("\u2713")} Resume sent to job ${jobId}
-`);
-      process.stdout.write(`  Use 'specialists feed ${jobId} --follow' to watch the response.
-`);
     } catch (err) {
       process.stderr.write(`${red6("Error:")} Failed to write to steer pipe: ${err?.message}
 `);
       process.exit(1);
     }
+    try {
+      supervisor.emitControlEvent(jobId, "resume_sent", {
+        source: "cli",
+        previous_status: status.status,
+        next_status: "running",
+        fifo_path: status.fifo_path,
+        task_preview: task.replace(/\s+/g, " ").slice(0, 240)
+      });
+    } catch (err) {
+      process.stderr.write(`Warning: resume delivered, but telemetry could not be recorded: ${err?.message ?? String(err)}
+`);
+    }
+    process.stdout.write(`${green12("\u2713")} Resume sent to job ${jobId}
+`);
+    process.stdout.write(`  Use 'specialists feed ${jobId} --follow' to watch the response.
+`);
   } finally {
     await supervisor.dispose();
   }
@@ -50363,21 +51160,21 @@ var init_resume = __esm(() => {
 // src/cli/follow-up.ts
 var exports_follow_up = {};
 __export(exports_follow_up, {
-  run: () => run22
+  run: () => run23
 });
-async function run22() {
+async function run23() {
   process.stderr.write("\x1B[33m\u26A0 DEPRECATED:\x1B[0m `specialists follow-up` is deprecated. Use `specialists resume` instead.\n\n");
   const { run: resumeRun } = await Promise.resolve().then(() => (init_resume(), exports_resume));
   return resumeRun();
 }
 
 // src/specialist/worktree-gc.ts
-import { existsSync as existsSync28, readdirSync as readdirSync14, readFileSync as readFileSync28 } from "fs";
-import { join as join32 } from "path";
+import { existsSync as existsSync29, readdirSync as readdirSync15, readFileSync as readFileSync28 } from "fs";
+import { join as join33 } from "path";
 import { spawnSync as spawnSync19 } from "child_process";
 function readJobStatus2(jobDir) {
-  const statusPath = join32(jobDir, "status.json");
-  if (!existsSync28(statusPath))
+  const statusPath = join33(jobDir, "status.json");
+  if (!existsSync29(statusPath))
     return null;
   try {
     return JSON.parse(readFileSync28(statusPath, "utf-8"));
@@ -50402,7 +51199,7 @@ function collectWorktreeGcCandidates(jobsDir) {
       const worktreePath = status.worktree_path;
       if (!worktreePath)
         return null;
-      if (!existsSync28(worktreePath))
+      if (!existsSync29(worktreePath))
         return null;
       return {
         jobId: status.id,
@@ -50414,13 +51211,13 @@ function collectWorktreeGcCandidates(jobsDir) {
   }
   if (!getFileFallbackEnabled())
     return [];
-  if (!existsSync28(jobsDir))
+  if (!existsSync29(jobsDir))
     return [];
   const candidates = [];
-  for (const entry of readdirSync14(jobsDir, { withFileTypes: true })) {
+  for (const entry of readdirSync15(jobsDir, { withFileTypes: true })) {
     if (!entry.isDirectory())
       continue;
-    const status = readJobStatus2(join32(jobsDir, entry.name));
+    const status = readJobStatus2(join33(jobsDir, entry.name));
     if (!status)
       continue;
     if (isActive(status.status))
@@ -50430,7 +51227,7 @@ function collectWorktreeGcCandidates(jobsDir) {
     const { worktree_path: worktreePath, branch } = status;
     if (!worktreePath)
       continue;
-    if (!existsSync28(worktreePath))
+    if (!existsSync29(worktreePath))
       continue;
     candidates.push({
       jobId: status.id,
@@ -50474,10 +51271,10 @@ var init_worktree_gc = __esm(() => {
 // src/cli/clean.ts
 var exports_clean = {};
 __export(exports_clean, {
-  run: () => run23
+  run: () => run24
 });
-import { existsSync as existsSync29, readFileSync as readFileSync29, readdirSync as readdirSync15, rmSync as rmSync4, statSync as statSync7 } from "fs";
-import { join as join33 } from "path";
+import { existsSync as existsSync30, readFileSync as readFileSync29, readdirSync as readdirSync16, rmSync as rmSync4, statSync as statSync8 } from "fs";
+import { join as join34 } from "path";
 function parseDuration2(raw) {
   const match = /^(\d+)(ms|s|m|h|d)$/i.exec(raw.trim());
   if (!match)
@@ -50631,16 +51428,16 @@ function parseOptions2(argv) {
 }
 function readDirectorySizeBytes(directoryPath) {
   let totalBytes = 0;
-  for (const entry of readdirSync15(directoryPath, { withFileTypes: true })) {
-    const entryPath = join33(directoryPath, entry.name);
-    const stats = statSync7(entryPath);
+  for (const entry of readdirSync16(directoryPath, { withFileTypes: true })) {
+    const entryPath = join34(directoryPath, entry.name);
+    const stats = statSync8(entryPath);
     totalBytes += stats.isDirectory() ? readDirectorySizeBytes(entryPath) : stats.size;
   }
   return totalBytes;
 }
 function containsProtectedSqliteArtifact(directoryPath) {
-  for (const entry of readdirSync15(directoryPath, { withFileTypes: true })) {
-    const entryPath = join33(directoryPath, entry.name);
+  for (const entry of readdirSync16(directoryPath, { withFileTypes: true })) {
+    const entryPath = join34(directoryPath, entry.name);
     if (entry.isDirectory()) {
       if (containsProtectedSqliteArtifact(entryPath))
         return true;
@@ -50661,11 +51458,11 @@ function getJobTimestamps(status) {
 function readCompletedJobDirectory(baseDirectory, entry) {
   if (!entry.isDirectory())
     return null;
-  const directoryPath = join33(baseDirectory, entry.name);
+  const directoryPath = join34(baseDirectory, entry.name);
   if (containsProtectedSqliteArtifact(directoryPath))
     return null;
-  const statusFilePath = join33(directoryPath, "status.json");
-  if (!existsSync29(statusFilePath))
+  const statusFilePath = join34(directoryPath, "status.json");
+  if (!existsSync30(statusFilePath))
     return null;
   let statusData;
   try {
@@ -50683,8 +51480,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 = join33(jobsDirectoryPath, status.id);
-      if (!existsSync29(directoryPath) || containsProtectedSqliteArtifact(directoryPath))
+      const directoryPath = join34(jobsDirectoryPath, status.id);
+      if (!existsSync30(directoryPath) || containsProtectedSqliteArtifact(directoryPath))
         return null;
       const { createdAtMs, completedAtMs } = getJobTimestamps(status);
       return { id: status.id, directoryPath, completedAtMs, createdAtMs, sizeBytes: readDirectorySizeBytes(directoryPath) };
@@ -50692,7 +51489,7 @@ function collectCompletedJobs(jobsDirectoryPath) {
   }
   if (process.env.SPECIALISTS_JOB_FILE_OUTPUT !== "on")
     return [];
-  return readdirSync15(jobsDirectoryPath, { withFileTypes: true }).map((entry) => readCompletedJobDirectory(jobsDirectoryPath, entry)).filter((job) => job !== null);
+  return readdirSync16(jobsDirectoryPath, { withFileTypes: true }).map((entry) => readCompletedJobDirectory(jobsDirectoryPath, entry)).filter((job) => job !== null);
 }
 function selectJobsToRemove(completedJobs, options2, protectedJobIds) {
   const jobsByNewest = [...completedJobs].sort((left, right) => {
@@ -50962,7 +51759,7 @@ function removeStaleProcesses(statuses, dryRun) {
   }
   return updatedCount;
 }
-async function run23() {
+async function run24() {
   let options2;
   try {
     options2 = parseOptions2(process.argv.slice(3));
@@ -51014,7 +51811,7 @@ async function run23() {
     console.log(`Hid ${hiddenCount} terminal row(s) from default ps.`);
     return;
   }
-  if (!existsSync29(jobsDirectoryPath)) {
+  if (!existsSync30(jobsDirectoryPath)) {
     console.log("No jobs directory found.");
     return;
   }
@@ -51067,7 +51864,7 @@ var init_clean = __esm(() => {
 // src/cli/end.ts
 var exports_end = {};
 __export(exports_end, {
-  run: () => run24
+  run: () => run25
 });
 import { spawnSync as spawnSync20 } from "child_process";
 function parseOptions3(argv) {
@@ -51151,7 +51948,7 @@ async function publishChain(beadId, options2) {
     console.log("Publication mode: direct merge");
   }
 }
-async function run24() {
+async function run25() {
   let options2;
   try {
     options2 = parseOptions3(process.argv.slice(3));
@@ -51192,7 +51989,7 @@ var init_end = __esm(() => {
 // src/cli/stop.ts
 var exports_stop = {};
 __export(exports_stop, {
-  run: () => run25
+  run: () => run26
 });
 function parseStopArgs(argv) {
   let jobId;
@@ -51215,7 +52012,7 @@ function parseStopArgs(argv) {
   }
   return { jobId, force, closeBeadAnyway };
 }
-async function run25() {
+async function run26() {
   let parsed;
   try {
     parsed = parseStopArgs(process.argv.slice(3));
@@ -51243,13 +52040,13 @@ var init_stop = __esm(() => {
 // src/cli/finalize.ts
 var exports_finalize = {};
 __export(exports_finalize, {
-  run: () => run26
+  run: () => run27
 });
 function parseFinalizeArgs(argv) {
   const jobId = argv.find((token) => !token.startsWith("-"));
   return { jobId };
 }
-async function run26() {
+async function run27() {
   const parsed = parseFinalizeArgs(process.argv.slice(3));
   const jobId = parsed.jobId;
   if (!jobId) {
@@ -51271,9 +52068,9 @@ var init_finalize = __esm(() => {
 // src/cli/attach-tui.ts
 var exports_attach_tui = {};
 __export(exports_attach_tui, {
-  run: () => run27
+  run: () => run28
 });
-async function run27(target, deps = {}) {
+async function run28(target, deps = {}) {
   const piTui = await Promise.resolve().then(() => (init_dist2(), exports_dist));
   const { TUI: TUI2, ProcessTerminal: ProcessTerminal2, Container: Container2, Input: Input2, matchesKey: matchesKey2, Key: Key2 } = piTui;
   const terminal = new ProcessTerminal2;
@@ -51393,7 +52190,7 @@ var init_attach_tui = __esm(() => {
 // src/cli/attach.ts
 var exports_attach = {};
 __export(exports_attach, {
-  run: () => run28
+  run: () => run29
 });
 import readline3 from "readline";
 function exitWithError(message) {
@@ -51510,7 +52307,7 @@ function pickTarget(targets) {
     render2();
   });
 }
-async function run28(deps = {}) {
+async function run29(deps = {}) {
   const [jobId] = process.argv.slice(3);
   if (!jobId) {
     if (!process.stdout.isTTY || !process.stdin.isTTY)
@@ -51526,8 +52323,8 @@ async function run28(deps = {}) {
 }
 async function attachTarget(target, deps) {
   const runTui = deps.runTui ?? (async (resolvedTarget) => {
-    const { run: run29 } = await Promise.resolve().then(() => (init_attach_tui(), exports_attach_tui));
-    return run29(resolvedTarget, deps);
+    const { run: run30 } = await Promise.resolve().then(() => (init_attach_tui(), exports_attach_tui));
+    return run30(resolvedTarget, deps);
   });
   return runTui(target);
 }
@@ -51536,15 +52333,15 @@ var init_attach = __esm(() => {
 });
 
 // src/specialist/drift-detector.ts
-import { existsSync as existsSync30, readFileSync as readFileSync30, readdirSync as readdirSync16, rmSync as rmSync5 } from "fs";
-import { join as join34, resolve as resolve11, relative as relative3 } from "path";
+import { existsSync as existsSync31, readFileSync as readFileSync30, readdirSync as readdirSync17, rmSync as rmSync5 } from "fs";
+import { join as join35, resolve as resolve11, relative as relative3 } from "path";
 function listFiles(root) {
-  if (!existsSync30(root))
+  if (!existsSync31(root))
     return [];
   const out = [];
   const visit2 = (dir) => {
-    for (const entry of readdirSync16(dir, { withFileTypes: true })) {
-      const full = join34(dir, entry.name);
+    for (const entry of readdirSync17(dir, { withFileTypes: true })) {
+      const full = join35(dir, entry.name);
       if (entry.isDirectory()) {
         visit2(full);
         continue;
@@ -51579,12 +52376,12 @@ function detectDriftForRepo(repoRoot) {
       { scope: "user", dir: resolve11(repoRoot, ".specialists/user") }
     ];
     for (const { scope, dir } of scopes) {
-      if (!existsSync30(dir))
+      if (!existsSync31(dir))
         continue;
       for (const file of listFiles(dir)) {
         const rel = relPath(file, dir);
-        const canonicalPath = join34(asset.canonicalDir, rel);
-        if (!existsSync30(canonicalPath))
+        const canonicalPath = join35(asset.canonicalDir, rel);
+        if (!existsSync31(canonicalPath))
           continue;
         const bytesEqual = readFileSync30(file).equals(readFileSync30(canonicalPath));
         findings.push(makeFinding(repoRoot, asset.kind, scope, file, canonicalPath, bytesEqual));
@@ -51605,12 +52402,12 @@ function detectDriftUnderRoot(root) {
       repos.push({ root: dir, findings });
       return;
     }
-    for (const entry of readdirSync16(dir, { withFileTypes: true })) {
+    for (const entry of readdirSync17(dir, { withFileTypes: true })) {
       if (!entry.isDirectory())
         continue;
       if (entry.name === "node_modules" || entry.name === ".git")
         continue;
-      visit2(join34(dir, entry.name));
+      visit2(join35(dir, entry.name));
     }
   };
   visit2(resolve11(root));
@@ -51650,10 +52447,10 @@ var init_drift_detector = __esm(() => {
 // src/cli/prune-stale-defaults.ts
 var exports_prune_stale_defaults = {};
 __export(exports_prune_stale_defaults, {
-  run: () => run29
+  run: () => run30
 });
 import { resolve as resolve12 } from "path";
-function parseArgs12(argv) {
+function parseArgs13(argv) {
   let dryRun = false;
   let root = process.cwd();
   let help = false;
@@ -51690,8 +52487,8 @@ function printHelp() {
   console.log("  --keep-diverged   Preserve diverged .specialists/default entries");
   console.log("  --root            Repo root to scan");
 }
-async function run29(argv = process.argv.slice(3)) {
-  const { dryRun, root, help, keepDiverged } = parseArgs12(argv);
+async function run30(argv = process.argv.slice(3)) {
+  const { dryRun, root, help, keepDiverged } = parseArgs13(argv);
   if (help) {
     printHelp();
     return;
@@ -51722,7 +52519,7 @@ var init_prune_stale_defaults = __esm(() => {
 // src/cli/quickstart.ts
 var exports_quickstart = {};
 __export(exports_quickstart, {
-  run: () => run30
+  run: () => run31
 });
 function section2(title) {
   const bar = "\u2500".repeat(60);
@@ -51736,7 +52533,7 @@ function cmd2(s) {
 function flag(s) {
   return green13(s);
 }
-async function run30() {
+async function run31() {
   const lines = [
     "",
     bold12("specialists  \xB7  Quick Start Guide"),
@@ -51958,7 +52755,7 @@ var bold12 = (s) => `\x1B[1m${s}\x1B[0m`, dim13 = (s) => `\x1B[2m${s}\x1B[0m`, y
 var exports_doctor = {};
 __export(exports_doctor, {
   setStatusError: () => setStatusError,
-  run: () => run31,
+  run: () => run32,
   resolvePackageAssetDir: () => resolvePackageAssetDir,
   renderProcessSummary: () => renderProcessSummary,
   parseVersionTuple: () => parseVersionTuple,
@@ -51967,8 +52764,8 @@ __export(exports_doctor, {
 });
 import { createHash as createHash5 } from "crypto";
 import { spawnSync as spawnSync21 } from "child_process";
-import { existsSync as existsSync31, lstatSync as lstatSync2, mkdirSync as mkdirSync12, readdirSync as readdirSync17, readFileSync as readFileSync31, readlinkSync as readlinkSync3, writeFileSync as writeFileSync16 } from "fs";
-import { dirname as dirname12, join as join35, relative as relative4, resolve as resolve13 } from "path";
+import { existsSync as existsSync32, lstatSync as lstatSync2, mkdirSync as mkdirSync12, readdirSync as readdirSync18, readFileSync as readFileSync31, readlinkSync as readlinkSync3, writeFileSync as writeFileSync16 } from "fs";
+import { dirname as dirname13, join as join36, relative as relative4, resolve as resolve13 } from "path";
 function ok3(msg) {
   console.log(`  ${green14("\u2713")} ${msg}`);
 }
@@ -51997,7 +52794,7 @@ function isInstalled3(bin) {
   return spawnSync21("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
 }
 function loadJson2(path3) {
-  if (!existsSync31(path3))
+  if (!existsSync32(path3))
     return null;
   try {
     return JSON.parse(readFileSync31(path3, "utf8"));
@@ -52043,7 +52840,7 @@ function checkBd() {
     return false;
   }
   ok3(`bd installed  ${dim14(sp("bd", ["--version"]).stdout || "")}`);
-  if (existsSync31(join35(CWD, ".beads")))
+  if (existsSync32(join36(CWD, ".beads")))
     ok3(".beads/ present in project");
   else
     warn3(".beads/ not found in project");
@@ -52063,18 +52860,18 @@ function checkHooks() {
   section3("Claude Code hooks  (2 expected)");
   let allPresent = true;
   for (const name of HOOK_NAMES) {
-    const canonicalPath = join35(HOOKS_DIR, name);
-    if (!existsSync31(canonicalPath)) {
+    const canonicalPath = join36(HOOKS_DIR, name);
+    if (!existsSync32(canonicalPath)) {
       fail4(`${relative4(CWD, canonicalPath)}  ${red7("missing")}`);
       fix("specialists init");
       allPresent = false;
     } else {
       ok3(relative4(CWD, canonicalPath));
     }
-    const claudeHookPath = join35(CLAUDE_HOOKS_DIR, name);
+    const claudeHookPath = join36(CLAUDE_HOOKS_DIR, name);
     const symlinkState = isSymlinkTo(claudeHookPath, canonicalPath);
     if (symlinkState.ok) {
-      ok3(`${relative4(CWD, claudeHookPath)} -> ${relative4(dirname12(claudeHookPath), canonicalPath)}`);
+      ok3(`${relative4(CWD, claudeHookPath)} -> ${relative4(dirname13(claudeHookPath), canonicalPath)}`);
       continue;
     }
     allPresent = false;
@@ -52152,8 +52949,8 @@ function hashFile(path3) {
 function collectFileHashes(rootDir) {
   const hashes = new Map;
   const visit2 = (dir) => {
-    for (const entry of readdirSync17(dir, { withFileTypes: true })) {
-      const fullPath = join35(dir, entry.name);
+    for (const entry of readdirSync18(dir, { withFileTypes: true })) {
+      const fullPath = join36(dir, entry.name);
       if (entry.isDirectory()) {
         visit2(fullPath);
         continue;
@@ -52164,12 +52961,12 @@ function collectFileHashes(rootDir) {
       hashes.set(relPath2, hashFile(fullPath));
     }
   };
-  if (existsSync31(rootDir))
+  if (existsSync32(rootDir))
     visit2(rootDir);
   return hashes;
 }
 function isSymlinkTo(linkPath, expectedTargetPath) {
-  if (!existsSync31(linkPath))
+  if (!existsSync32(linkPath))
     return { ok: false, reason: "missing" };
   let stats;
   try {
@@ -52181,7 +52978,7 @@ function isSymlinkTo(linkPath, expectedTargetPath) {
     return { ok: false, reason: "not-symlink" };
   try {
     const rawTarget = readlinkSync3(linkPath);
-    const resolvedTarget = resolve13(dirname12(linkPath), rawTarget);
+    const resolvedTarget = resolve13(dirname13(linkPath), rawTarget);
     const resolvedExpected = resolve13(expectedTargetPath);
     if (resolvedTarget !== resolvedExpected) {
       return { ok: false, reason: "wrong-target", target: rawTarget };
@@ -52192,7 +52989,7 @@ function isSymlinkTo(linkPath, expectedTargetPath) {
   }
 }
 function resolvePackageAssetDir(relativePath) {
-  return resolveCanonicalAssetDir(relativePath) ?? (existsSync31(join35(CWD, "config", relativePath)) ? join35(CWD, "config", relativePath) : null);
+  return resolveCanonicalAssetDir(relativePath) ?? (existsSync32(join36(CWD, "config", relativePath)) ? join36(CWD, "config", relativePath) : null);
 }
 function checkSkillDrift() {
   section3("Category A  package-live skill sync");
@@ -52202,7 +52999,7 @@ function checkSkillDrift() {
     fix("restore config/skills/ or install package assets");
     return false;
   }
-  if (!existsSync31(XTRM_DEFAULT_SKILLS_DIR)) {
+  if (!existsSync32(XTRM_DEFAULT_SKILLS_DIR)) {
     fail4(".xtrm/skills/default/ missing");
     fix("specialists init --sync-skills");
     return false;
@@ -52242,11 +53039,11 @@ function checkSkillDrift() {
     }
     fix("specialists init --sync-skills");
   }
-  const defaultSkills = readdirSync17(XTRM_DEFAULT_SKILLS_DIR, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  const defaultSkills = readdirSync18(XTRM_DEFAULT_SKILLS_DIR, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   let linksOk = true;
   for (const skillName of defaultSkills) {
-    const activeLinkPath = join35(XTRM_ACTIVE_SKILLS_DIR, skillName);
-    const expectedTarget = join35(XTRM_DEFAULT_SKILLS_DIR, skillName);
+    const activeLinkPath = join36(XTRM_ACTIVE_SKILLS_DIR, skillName);
+    const expectedTarget = join36(XTRM_DEFAULT_SKILLS_DIR, skillName);
     const state = isSymlinkTo(activeLinkPath, expectedTarget);
     if (state.ok)
       continue;
@@ -52264,11 +53061,11 @@ function checkSkillDrift() {
     fix("specialists init --sync-skills");
   }
   const legacyActiveRoots = [
-    { scope: "claude", root: join35(XTRM_ACTIVE_SKILLS_DIR, "claude") },
-    { scope: "pi", root: join35(XTRM_ACTIVE_SKILLS_DIR, "pi") }
+    { scope: "claude", root: join36(XTRM_ACTIVE_SKILLS_DIR, "claude") },
+    { scope: "pi", root: join36(XTRM_ACTIVE_SKILLS_DIR, "pi") }
   ];
   for (const { root } of legacyActiveRoots) {
-    if (!existsSync31(root))
+    if (!existsSync32(root))
       continue;
     if (isSymlinkTo(root, XTRM_ACTIVE_SKILLS_DIR).ok)
       continue;
@@ -52281,14 +53078,14 @@ function checkSkillDrift() {
     fix("specialists init --sync-skills");
   }
   const skillRootChecks = [
-    { root: join35(CLAUDE_DIR, "skills"), expected: XTRM_ACTIVE_SKILLS_DIR },
-    { root: join35(PI_DIR, "skills"), expected: XTRM_ACTIVE_SKILLS_DIR }
+    { root: join36(CLAUDE_DIR, "skills"), expected: XTRM_ACTIVE_SKILLS_DIR },
+    { root: join36(PI_DIR, "skills"), expected: XTRM_ACTIVE_SKILLS_DIR }
   ];
   let rootLinksOk = true;
   for (const check2 of skillRootChecks) {
     const state = isSymlinkTo(check2.root, check2.expected);
     if (state.ok) {
-      ok3(`${relative4(CWD, check2.root)} -> ${relative4(dirname12(check2.root), check2.expected)}`);
+      ok3(`${relative4(CWD, check2.root)} -> ${relative4(dirname13(check2.root), check2.expected)}`);
       continue;
     }
     rootLinksOk = false;
@@ -52314,7 +53111,7 @@ function checkManagedMirror(label, canonicalRelativePath, mirrorDir, fixHint) {
     fix(fixHint);
     return false;
   }
-  if (!existsSync31(mirrorDir)) {
+  if (!existsSync32(mirrorDir)) {
     fail4(`${label} mirror missing: ${relative4(CWD, mirrorDir)}`);
     fix(fixHint);
     return false;
@@ -52346,31 +53143,31 @@ function checkManagedMirror(label, canonicalRelativePath, mirrorDir, fixHint) {
 function checkManagedAssetMirrors() {
   section3("Category B  xtrm-managed asset mirrors");
   const specialistsOk = checkManagedMirror("specialists", "specialists", DEFAULT_SPECIALISTS_DIR, "sp prune-stale-defaults --apply");
-  const rulesOk = checkManagedMirror("mandatory-rules", "mandatory-rules", join35(DEFAULT_SPECIALISTS_DIR, "mandatory-rules"), "sp prune-stale-defaults --apply");
-  const nodesOk = checkManagedMirror("nodes", "nodes", join35(DEFAULT_SPECIALISTS_DIR, "nodes"), "sp prune-stale-defaults --apply");
+  const rulesOk = checkManagedMirror("mandatory-rules", "mandatory-rules", join36(DEFAULT_SPECIALISTS_DIR, "mandatory-rules"), "sp prune-stale-defaults --apply");
+  const nodesOk = checkManagedMirror("nodes", "nodes", join36(DEFAULT_SPECIALISTS_DIR, "nodes"), "sp prune-stale-defaults --apply");
   return specialistsOk && rulesOk && nodesOk;
 }
 function checkUserOverlayDrift() {
   section3("User specialist overlays");
-  if (!existsSync31(USER_SPECIALISTS_DIR)) {
+  if (!existsSync32(USER_SPECIALISTS_DIR)) {
     ok3("no user overlays present");
     return true;
   }
-  const overlays = readdirSync17(USER_SPECIALISTS_DIR).filter((name) => name.endsWith(".specialist.json"));
+  const overlays = readdirSync18(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 = join35(USER_SPECIALISTS_DIR, name);
-    const defaultPath = join35(DEFAULT_SPECIALISTS_DIR, name);
+    const userPath = join36(USER_SPECIALISTS_DIR, name);
+    const defaultPath = join36(DEFAULT_SPECIALISTS_DIR, name);
     const userSpec = loadJson2(userPath);
     if (!userSpec) {
       warn3(`${name}: failed to parse \u2014 skipping drift check`);
       continue;
     }
-    if (!existsSync31(defaultPath)) {
+    if (!existsSync32(defaultPath)) {
       ok3(`${name}: user-only overlay (no default to drift from)`);
       continue;
     }
@@ -52398,18 +53195,18 @@ function checkUserOverlayDrift() {
 }
 function checkRuntimeDirs() {
   section3(".specialists/ runtime directories");
-  const rootDir = join35(CWD, ".specialists");
-  const jobsDir = join35(rootDir, "jobs");
-  const readyDir = join35(rootDir, "ready");
+  const rootDir = join36(CWD, ".specialists");
+  const jobsDir = join36(rootDir, "jobs");
+  const readyDir = join36(rootDir, "ready");
   let allOk = true;
-  if (!existsSync31(rootDir)) {
+  if (!existsSync32(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 (!existsSync31(subDir)) {
+      if (!existsSync32(subDir)) {
         warn3(`.specialists/${label}/ missing \u2014 auto-creating`);
         mkdirSync12(subDir, { recursive: true });
         ok3(`.specialists/${label}/ created`);
@@ -52423,8 +53220,8 @@ function checkRuntimeDirs() {
 function checkClaudeMdFragments() {
   section3("CLAUDE.md fragments");
   const projectRoot = process.cwd();
-  const claudeMd = join35(projectRoot, "CLAUDE.md");
-  if (!existsSync31(claudeMd)) {
+  const claudeMd = join36(projectRoot, "CLAUDE.md");
+  if (!existsSync32(claudeMd)) {
     warn3("No CLAUDE.md in project root \u2014 skipping fragment check");
     return true;
   }
@@ -52592,7 +53389,7 @@ function cleanupProcesses(jobsDir, dryRun) {
   }
   let entries;
   try {
-    entries = readdirSync17(jobsDir);
+    entries = readdirSync18(jobsDir);
   } catch {
     entries = [];
   }
@@ -52604,8 +53401,8 @@ function cleanupProcesses(jobsDir, dryRun) {
     zombieJobIds: []
   };
   for (const jobId of entries) {
-    const statusPath = join35(jobsDir, jobId, "status.json");
-    if (!existsSync31(statusPath))
+    const statusPath = join36(jobsDir, jobId, "status.json");
+    if (!existsSync32(statusPath))
       continue;
     try {
       const status = JSON.parse(readFileSync31(statusPath, "utf8"));
@@ -52693,8 +53490,8 @@ function resolveWatchdogMode() {
 function checkZombieJobs() {
   section3("Background jobs");
   hint(`watchdog mode: ${resolveWatchdogMode()}`);
-  const jobsDir = join35(CWD, ".specialists", "jobs");
-  if (!existsSync31(jobsDir)) {
+  const jobsDir = join36(CWD, ".specialists", "jobs");
+  if (!existsSync32(jobsDir)) {
     hint("No .specialists/jobs/ \u2014 skipping");
     return true;
   }
@@ -52712,7 +53509,7 @@ function checkZombieJobs() {
   }
   return result.zombies === 0;
 }
-async function run31(argv = process.argv.slice(3)) {
+async function run32(argv = process.argv.slice(3)) {
   const subcommand = argv[0];
   if (subcommand === "orphans") {
     runDoctorOrphans();
@@ -52760,18 +53557,18 @@ var init_doctor = __esm(() => {
   init_drift_detector();
   init_version_check();
   CWD = process.cwd();
-  CLAUDE_DIR = join35(CWD, ".claude");
-  PI_DIR = join35(CWD, ".pi");
-  XTRM_SKILLS_DIR = join35(CWD, ".xtrm", "skills");
-  XTRM_DEFAULT_SKILLS_DIR = join35(XTRM_SKILLS_DIR, "default");
-  XTRM_ACTIVE_SKILLS_DIR = join35(XTRM_SKILLS_DIR, "active");
-  SPECIALISTS_DIR = join35(CWD, ".specialists");
-  DEFAULT_SPECIALISTS_DIR = join35(SPECIALISTS_DIR, "default");
-  USER_SPECIALISTS_DIR = join35(SPECIALISTS_DIR, "user");
-  HOOKS_DIR = join35(CWD, ".xtrm", "hooks", "specialists");
-  CLAUDE_HOOKS_DIR = join35(CLAUDE_DIR, "hooks");
-  SETTINGS_FILE = join35(CLAUDE_DIR, "settings.json");
-  MCP_FILE2 = join35(CWD, ".mcp.json");
+  CLAUDE_DIR = join36(CWD, ".claude");
+  PI_DIR = join36(CWD, ".pi");
+  XTRM_SKILLS_DIR = join36(CWD, ".xtrm", "skills");
+  XTRM_DEFAULT_SKILLS_DIR = join36(XTRM_SKILLS_DIR, "default");
+  XTRM_ACTIVE_SKILLS_DIR = join36(XTRM_SKILLS_DIR, "active");
+  SPECIALISTS_DIR = join36(CWD, ".specialists");
+  DEFAULT_SPECIALISTS_DIR = join36(SPECIALISTS_DIR, "default");
+  USER_SPECIALISTS_DIR = join36(SPECIALISTS_DIR, "user");
+  HOOKS_DIR = join36(CWD, ".xtrm", "hooks", "specialists");
+  CLAUDE_HOOKS_DIR = join36(CLAUDE_DIR, "hooks");
+  SETTINGS_FILE = join36(CLAUDE_DIR, "settings.json");
+  MCP_FILE2 = join36(CWD, ".mcp.json");
   HOOK_NAMES = [
     "specialists-complete.mjs",
     "specialists-session-start.mjs"
@@ -52781,9 +53578,9 @@ var init_doctor = __esm(() => {
 // src/cli/setup.ts
 var exports_setup = {};
 __export(exports_setup, {
-  run: () => run32
+  run: () => run33
 });
-async function run32() {
+async function run33() {
   console.log("");
   console.log(yellow13("\u26A0 DEPRECATED: `specialists setup` is deprecated"));
   console.log("");
@@ -52804,20 +53601,20 @@ async function run32() {
 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 existsSync32, readdirSync as readdirSync18, statSync as statSync8, watch as fsWatch } from "fs";
-import { join as join36 } from "path";
+import { existsSync as existsSync33, readdirSync as readdirSync19, statSync as statSync9, watch as fsWatch } from "fs";
+import { join as join37 } 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 (!existsSync32(dir))
+  if (!existsSync33(dir))
     return out;
-  const entries = readdirSync18(dir).filter((name) => specialistNameFromFile(name) !== null);
+  const entries = readdirSync19(dir).filter((name) => specialistNameFromFile(name) !== null);
   for (const name of entries) {
     try {
-      out.set(name, statSync8(join36(dir, name)).mtimeMs);
+      out.set(name, statSync9(join37(dir, name)).mtimeMs);
     } catch {}
   }
   return out;
@@ -52874,7 +53671,7 @@ function createUserDirWatcher(opts) {
       for (const file of changed)
         queue(file);
     }, opts.pollMs);
-  } else if (existsSync32(opts.userDir)) {
+  } else if (existsSync33(opts.userDir)) {
     try {
       watcher = fsWatch(opts.userDir, { persistent: false }, (_eventType, filename) => {
         queue(filename ? String(filename) : null);
@@ -52906,7 +53703,7 @@ var init_serve_hot_reload = () => {};
 var exports_serve = {};
 __export(exports_serve, {
   startServe: () => startServe,
-  run: () => run33,
+  run: () => run34,
   recordAuditFailure: () => recordAuditFailure,
   evaluateReadiness: () => evaluateReadiness2,
   createReadinessState: () => createReadinessState,
@@ -52917,9 +53714,9 @@ import { randomUUID as randomUUID3 } from "crypto";
 import { once } from "events";
 import { spawnSync as spawnSync22 } from "child_process";
 import { access, readdir as readdir2, readFile as readFile5, constants } from "fs/promises";
-import { existsSync as existsSync33 } from "fs";
+import { existsSync as existsSync34 } from "fs";
 import { homedir as homedir5 } from "os";
-import { join as join37 } from "path";
+import { join as join38 } from "path";
 function createReadinessState() {
   return { shuttingDown: false, auditFailures: [], dbWriteFailuresTotal: 0 };
 }
@@ -52935,7 +53732,7 @@ function pruneAuditFailures(state, now = Date.now()) {
   }
 }
 async function checkUserDirSpecs(userDir) {
-  if (!existsSync33(userDir))
+  if (!existsSync34(userDir))
     return "empty";
   const entries = await readdir2(userDir).catch(() => []);
   const specFiles = entries.filter((name) => name.endsWith(".specialist.json") || name.endsWith(".specialist.yaml"));
@@ -52944,7 +53741,7 @@ async function checkUserDirSpecs(userDir) {
   let validCount = 0;
   for (const file of specFiles) {
     try {
-      const content = await readFile5(join37(userDir, file), "utf-8");
+      const content = await readFile5(join38(userDir, file), "utf-8");
       const json = file.endsWith(".json") ? content : null;
       if (!json)
         continue;
@@ -52962,7 +53759,7 @@ async function evaluateReadiness2(opts) {
   if (opts.state.auditFailures.length > opts.auditFailureThreshold) {
     return { ready: false, reason: "degraded:audit" };
   }
-  const piConfigPath = opts.piConfigPath ?? join37(homedir5(), ".pi", "agent", "auth.json");
+  const piConfigPath = opts.piConfigPath ?? join38(homedir5(), ".pi", "agent", "auth.json");
   try {
     await access(piConfigPath, constants.R_OK);
   } catch {
@@ -52983,7 +53780,7 @@ async function evaluateReadiness2(opts) {
       warning = canaryFailure;
     }
   }
-  const userDir = join37(opts.projectDir, ".specialists", "user");
+  const userDir = join38(opts.projectDir, ".specialists", "user");
   const userDirResult = await checkUserDirSpecs(userDir);
   if (userDirResult === "empty")
     return { ready: false, reason: "empty_user_dir" };
@@ -52991,7 +53788,7 @@ async function evaluateReadiness2(opts) {
     return { ready: false, reason: "invalid_spec_in_user_dir" };
   return warning ? { ready: true, warning } : { ready: true };
 }
-function parseArgs13(argv) {
+function parseArgs14(argv) {
   let port = 8000;
   let concurrency = 4;
   let queueTimeoutMs = 5000;
@@ -53095,7 +53892,7 @@ async function waitForSlot(limit, timeoutMs, getActive) {
   return true;
 }
 async function startServe(argv = process.argv.slice(3)) {
-  const args = parseArgs13(argv);
+  const args = parseArgs14(argv);
   const loader = new SpecialistLoader({ projectDir: args.projectDir });
   const dbLocation = resolveObservabilityDbLocation(args.projectDir);
   const dbPath = args.dbPath ?? dbLocation.dbPath;
@@ -53104,7 +53901,7 @@ async function startServe(argv = process.argv.slice(3)) {
     return createObservabilitySqliteClient(args.projectDir);
   })();
   const readinessState = createReadinessState();
-  const userDir = join37(args.projectDir, ".specialists", "user");
+  const userDir = join38(args.projectDir, ".specialists", "user");
   const hotReload = createUserDirWatcher({ loader, userDir, pollMs: args.reloadPollMs });
   let active = 0;
   const children = new Set;
@@ -53269,7 +54066,7 @@ async function startServe(argv = process.argv.slice(3)) {
   console.log(`sp serve listening on ${args.port}`);
   return { server, args, db, readinessState };
 }
-async function run33(argv = process.argv.slice(3)) {
+async function run34(argv = process.argv.slice(3)) {
   await startServe(argv);
 }
 var AUDIT_WINDOW_MS = 60000, DEFAULT_REQUIRED_PI_FLAGS;
@@ -53287,8 +54084,8 @@ var init_serve = __esm(() => {
 var exports_script = {};
 __export(exports_script, {
   scriptCli: () => scriptCli,
-  run: () => run34,
-  parseArgs: () => parseArgs14,
+  run: () => run35,
+  parseArgs: () => parseArgs15,
   mapExitCode: () => mapExitCode
 });
 import { spawnSync as spawnSync23 } from "child_process";
@@ -53298,7 +54095,7 @@ function parseVar(entry) {
     throw new Error(`Invalid --vars entry: ${entry}`);
   return [entry.slice(0, index), entry.slice(index + 1)];
 }
-function parseArgs14(argv) {
+function parseArgs15(argv) {
   if (argv.length === 0)
     throw new Error("Missing specialist name");
   const specialist = argv[0];
@@ -53404,8 +54201,8 @@ function runUnderLock(lockPath, argv) {
     return 75;
   return flock.status ?? 1;
 }
-async function run34(argv = process.argv.slice(3)) {
-  const args = parseArgs14(argv);
+async function run35(argv = process.argv.slice(3)) {
+  const args = parseArgs15(argv);
   if (args.singleInstance && !process.env.SP_SCRIPT_NO_LOCK) {
     process.exit(runUnderLock(args.singleInstance, argv));
   }
@@ -53422,19 +54219,19 @@ var scriptCli;
 var init_script = __esm(() => {
   init_loader();
   init_script_runner();
-  scriptCli = { parseArgs: parseArgs14, mapExitCode };
+  scriptCli = { parseArgs: parseArgs15, mapExitCode };
 });
 
 // src/cli/help.ts
 var exports_help = {};
 __export(exports_help, {
-  run: () => run35
+  run: () => run36
 });
 function formatCommands(entries) {
   const width = Math.max(...entries.map(([cmd3]) => cmd3.length));
   return entries.map(([cmd3, desc]) => `  ${cmd3.padEnd(width)}   ${desc}`);
 }
-async function run35() {
+async function run36() {
   const lines = [
     "",
     "Specialists lets you run project-scoped specialist agents with a bead-first workflow.",
@@ -53476,14 +54273,15 @@ async function run35() {
     "  Async patterns",
     "    MCP:   use_specialist (foreground, returns result directly)",
     '    CLI:   specialists run <name> --prompt "..."       # job ID prints on stderr',
-    "           specialists ps|feed|result <job-id>           # observe/progress/final output",
+    "           specialists ps|feed|log|result <job-id>       # observe/progress/debug/final output",
     '    Shell: specialists run <name> --prompt "..." &      # native shell backgrounding',
     "",
     "  Background workflow",
     '    specialists run executor --background --prompt "..."   # \u2192 prints job-id',
     "    specialists list --live                                # \u2192 interactive session picker",
     "    specialists attach <job-id>                            # \u2192 legacy tmux attach only",
-    "    specialists feed <job-id> --follow                     # \u2192 structured event stream",
+    "    specialists feed <job-id> --follow                     # \u2192 compact structured event stream",
+    "    specialists log <job-id> -f                             # \u2192 full runtime/control/error log",
     "    specialists merge <bead-id> [--rebuild]                # \u2192 publish standalone chain only",
     "    specialists epic merge <epic-id> [--pr]                 # \u2192 publish epic-owned chains",
     "    specialists end [--pr]                                   # \u2192 session-close publish helper",
@@ -53507,7 +54305,8 @@ async function run35() {
     "  specialists run debugger --bead unitAI-123",
     '  specialists run codebase-explorer --prompt "Map the CLI architecture"',
     "  specialists ps abc123 --json                    # check job status",
-    "  specialists feed -f                             # stream all job events",
+    "  specialists feed -f                             # stream compact job events",
+    "  specialists log --specialist reviewer -f         # full runtime/debug log",
     "  specialists chat explorer --bead unitAI-123     # live TUI: feed + result + input",
     '  specialists steer <job-id> "focus only on supervisor.ts"',
     '  specialists resume <job-id> "now write the fix"',
@@ -53530,7 +54329,8 @@ async function run35() {
     "  specialists steer --help       Mid-run steering details",
     "  specialists resume --help      Multi-turn keep-alive details",
     "  specialists init --help        Bootstrap behavior and workflow injection",
-    "  specialists feed --help        Job event streaming details",
+    "  specialists feed --help        Compact job event streaming details",
+    "  specialists log --help         Full runtime/control/error log details",
     "  specialists chat <name> ...     Interactive TUI launch/control surface",
     "",
     dim16("Project model: specialists are project-only; user-scope discovery is deprecated."),
@@ -53554,7 +54354,8 @@ var init_help = __esm(() => {
     ["release", "Deprecated alias: proxy to xt release prepare/publish"],
     ["node", "Run and inspect NodeSupervisor nodes (run/status)"],
     ["epic", "Epic lifecycle management: list/status/resolve wave-bound chain groups"],
-    ["feed", "Tail job events; use -f to follow all jobs"],
+    ["feed", "Tail compact job events; use -f to follow all jobs"],
+    ["log", "Full runtime logs with job/bead/repo/path metadata; -f follows control/error events"],
     ["chat", "Launch an interactive TUI: feed-style timeline, status row, result, and steer/resume input"],
     ["result", "Print final output of a completed job; --wait polls until done, --timeout <ms> sets a limit"],
     ["clean", "Clean job dirs, dashboard history (--ps), and orphan processes"],
@@ -61109,7 +61910,7 @@ var next = process.argv[3];
 function wantsHelp() {
   return next === "--help" || next === "-h";
 }
-async function run36() {
+async function run37() {
   if (sub === "install") {
     if (wantsHelp()) {
       console.log([
@@ -61763,6 +62564,48 @@ async function run36() {
     const { run: handler } = await Promise.resolve().then(() => (init_feed2(), exports_feed));
     return handler();
   }
+  if (sub === "log") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists log [job-id] [options]",
+        "       specialists log -f [--specialist <name>] [--bead <id>]",
+        "",
+        "Runtime-oriented specialist log stream. From a repo root it reads that repo;",
+        "from a parent directory it aggregates child repos with observability DBs.",
+        "Unlike feed, it does not suppress",
+        "control/lifecycle rows and every row includes timestamp, job, specialist,",
+        "bead, compact worktree, status, pid, and runtime event detail.",
+        "",
+        "Options:",
+        "  --job <id>          Filter to one job id",
+        "  --specialist <name> Filter by specialist role",
+        "  --bead <id>         Filter by bead id",
+        "  --node <id>         Filter by node id",
+        "  --repo <name>       In parent/global mode, filter to one child repo",
+        "  --since <5m|iso>    Show rows after a relative/ISO timestamp",
+        "  --limit <n>         Max rows per snapshot (default 200)",
+        "  -f, --follow        Continue polling for new rows",
+        "  --json              Emit NDJSON rows with full event payloads",
+        "  --all-events        Include agent-internal feed events (tool/turn/text/etc.)",
+        "",
+        "Examples:",
+        "  specialists log 49adda",
+        "  specialists log --bead unitAI-123 --limit 500",
+        "  specialists log --specialist reviewer -f",
+        "  specialists log -f --json",
+        "",
+        "Default output is runtime-only; use --all-events for raw agent internals.",
+        "Use feed for compact human progress; use log for debugging crashes,",
+        "dispatch/resume/steer/stop signals, and terminal error provenance.",
+        ""
+      ].join(`
+`));
+      return;
+    }
+    const { run: handler } = await Promise.resolve().then(() => (init_log(), exports_log));
+    return handler();
+  }
   if (sub === "steer") {
     if (wantsHelp()) {
       console.log([
@@ -62158,7 +63001,7 @@ Run 'specialists help' to see available commands.`);
   const server = new SpecialistsServer;
   await server.start();
 }
-run36().catch((error2) => {
+run37().catch((error2) => {
   logger.error(`Fatal error: ${error2}`);
   process.exit(1);
 });