@wrongstack/core 0.9.7 → 0.9.19

package/dist/coordination/index.js

@@ -1,5 +1,5 @@
 import { randomUUID, randomBytes } from 'crypto';
-import * as fsp4 from 'fs/promises';
+import * as fsp5 from 'fs/promises';
 import * as path4 from 'path';
 import { EventEmitter } from 'events';
 
@@ -11,16 +11,16 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 async function atomicWrite(targetPath, content, opts = {}) {
   const dir = path4.dirname(targetPath);
-  await fsp4.mkdir(dir, { recursive: true });
+  await fsp5.mkdir(dir, { recursive: true });
   const tmp = path4.join(dir, `.${path4.basename(targetPath)}.${randomBytes(6).toString("hex")}.tmp`);
   try {
     if (typeof content === "string") {
-      await fsp4.writeFile(tmp, content, { flag: "wx", encoding: opts.encoding ?? "utf8" });
+      await fsp5.writeFile(tmp, content, { flag: "wx", encoding: opts.encoding ?? "utf8" });
     } else {
-      await fsp4.writeFile(tmp, content, { flag: "wx" });
+      await fsp5.writeFile(tmp, content, { flag: "wx" });
     }
     try {
-      const fh = await fsp4.open(tmp, "r+");
+      const fh = await fsp5.open(tmp, "r+");
       try {
         await fh.sync();
       } finally {
@@ -30,37 +30,37 @@ async function atomicWrite(targetPath, content, opts = {}) {
     }
     let mode;
     try {
-      const stat3 = await fsp4.stat(targetPath);
+      const stat3 = await fsp5.stat(targetPath);
       mode = stat3.mode & 511;
     } catch {
       mode = opts.mode;
     }
     if (mode !== void 0) {
-      await fsp4.chmod(tmp, mode);
+      await fsp5.chmod(tmp, mode);
     }
     await renameWithRetry(tmp, targetPath);
   } catch (err) {
     try {
-      await fsp4.unlink(tmp);
+      await fsp5.unlink(tmp);
     } catch {
     }
     throw err;
   }
 }
 async function ensureDir(dir) {
-  await fsp4.mkdir(dir, { recursive: true });
+  await fsp5.mkdir(dir, { recursive: true });
 }
 var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
 async function renameWithRetry(from, to) {
   if (process.platform !== "win32") {
-    await fsp4.rename(from, to);
+    await fsp5.rename(from, to);
     return;
   }
   const delays = [10, 25, 60, 120, 250];
   let lastErr;
   for (let i = 0; i <= delays.length; i++) {
     try {
-      await fsp4.rename(from, to);
+      await fsp5.rename(from, to);
       return;
     } catch (err) {
       lastErr = err;
@@ -76,7 +76,7 @@ async function renameWithRetry(from, to) {
 async function acquireDirectorStateLock(lockPath, processId = process.pid) {
   let existing;
   try {
-    existing = await fsp4.readFile(lockPath, "utf8");
+    existing = await fsp5.readFile(lockPath, "utf8");
   } catch {
   }
   if (existing) {
@@ -100,7 +100,7 @@ async function acquireDirectorStateLock(lockPath, processId = process.pid) {
 }
 async function releaseDirectorStateLock(lockPath) {
   try {
-    await fsp4.unlink(lockPath);
+    await fsp5.unlink(lockPath);
   } catch {
   }
 }
@@ -631,6 +631,106 @@ var FleetUsageAggregator = class {
   }
 };
 
+// src/coordination/subagent-nicknames.ts
+var NICKNAME_POOL = {
+  // Physics & fundamental sciences
+  "einstein": { name: "Einstein", domain: "physics" },
+  "newton": { name: "Newton", domain: "physics" },
+  "feynman": { name: "Feynman", domain: "physics" },
+  "dirac": { name: "Dirac", domain: "physics" },
+  "bohr": { name: "Bohr", domain: "physics" },
+  "planck": { name: "Planck", domain: "physics" },
+  "curie": { name: "Curie", domain: "physics" },
+  "fermi": { name: "Fermi", domain: "physics" },
+  "heisenberg": { name: "Heisenberg", domain: "physics" },
+  "schrodinger": { name: "Schr\xF6dinger", domain: "physics" },
+  // Mathematics
+  "euclid": { name: "Euclid", domain: "math" },
+  "gauss": { name: "Gauss", domain: "math" },
+  "turing": { name: "Turing", domain: "math" },
+  "poincare": { name: "Poincar\xE9", domain: "math" },
+  "riemann": { name: "Riemann", domain: "math" },
+  "hilbert": { name: "Hilbert", domain: "math" },
+  "pythagoras": { name: "Pythagoras", domain: "math" },
+  // Computing & information theory
+  "von-neumann": { name: "Von Neumann", domain: "computing" },
+  "shannon": { name: "Shannon", domain: "computing" },
+  "hopper": { name: "Hopper", domain: "computing" },
+  "backus": { name: "Backus", domain: "computing" },
+  "knuth": { name: "Knuth", domain: "computing" },
+  "torvalds": { name: "Torvalds", domain: "computing" },
+  "stallman": { name: "Stallman", domain: "computing" },
+  "berners-lee": { name: "Berners-Lee", domain: "computing" },
+  "babbage": { name: "Babbage", domain: "computing" },
+  "lovelace": { name: "Lovelace", domain: "computing" },
+  "klein": { name: "Klein", domain: "computing" },
+  // Electronics & electrical engineering
+  "edison": { name: "Edison", domain: "ee" },
+  "tesla": { name: "Tesla", domain: "ee" },
+  "faraday": { name: "Faraday", domain: "ee" },
+  "maxwell": { name: "Maxwell", domain: "ee" },
+  "ohm": { name: "Ohm", domain: "ee" },
+  "bell": { name: "Bell", domain: "ee" },
+  "marconi": { name: "Marconi", domain: "ee" },
+  "lamarr": { name: "Lamarr", domain: "ee" },
+  // General science / multi-disciplinary
+  "darwin": { name: "Darwin", domain: "biology" },
+  "mendel": { name: "Mendel", domain: "biology" },
+  "pasteur": { name: "Pasteur", domain: "biology" },
+  "hawking": { name: "Hawking", domain: "cosmology" },
+  "sagan": { name: "Sagan", domain: "cosmology" },
+  // Chemistry / materials
+  "lavoisier": { name: "Lavoisier", domain: "chemistry" },
+  "mendeleev": { name: "Mendeleev", domain: "chemistry" }
+};
+var ALL_NICKNAMES = Object.values(NICKNAME_POOL);
+var DOMAIN_PREFERENCES = {
+  "security": ["shannon", "turing", "lamarr", "stallman"],
+  "bug-hunter": ["darwin", "curie", "feynman", "fermi"],
+  "refactor": ["gauss", "hilbert", "euclid", "planck"],
+  "audit-log": ["sagan", "hawking", "poincare", "newton"],
+  "planner": ["hilbert", "gauss", "turing", "euclid"],
+  "researcher": ["sagan", "hawking", "darwin", "pasteur"],
+  "explorer": ["marconi", "bell", "columbus", "polo"],
+  "testing": ["pasteur", "curie", "fermi", "bohr"],
+  "frontend": ["lovelace", "hopper", "babbage", "backus"],
+  "backend": ["torvalds", "stallman", "von-neumann", "backus"],
+  "database": ["turing", "shannon", "backus", "knuth"],
+  "devops": ["tesla", "edison", "faraday", "bell"],
+  "security-scanner": ["shannon", "turing", "lamarr", "stallman"],
+  "refactor-planner": ["gauss", "hilbert", "planck", "newton"],
+  "architect": ["von-neumann", "turing", "gauss", "hilbert"],
+  "critic": ["einstein", "feynman", "dirac", "bohr"],
+  "e2e": ["hopper", "bell", "marconi", "tesla"],
+  "performance": ["knuth", "gauss", "planck", "feynman"],
+  "chaos": ["tesla", "edison", "curie", "fermi"],
+  "cost": ["oh", "bell", "marconi", "tesla"],
+  // default fallback
+  "default": ["einstein", "newton", "curie", "tesla", "edison", "turing", "shannon", "hopper", "knuth", "stallman"]
+};
+function assignNickname(role, used) {
+  const preferences = [
+    ...DOMAIN_PREFERENCES[role] ?? [],
+    ...DOMAIN_PREFERENCES["default"] ?? []
+  ];
+  for (const key of preferences) {
+    if (!used.has(key)) {
+      return `${NICKNAME_POOL[key].name} (${formatRole(role)})`;
+    }
+  }
+  for (const entry of ALL_NICKNAMES) {
+    const key = Object.entries(NICKNAME_POOL).find(([, v]) => v.name === entry.name)?.[0];
+    if (key && !used.has(key)) {
+      return `${entry.name} (${formatRole(role)})`;
+    }
+  }
+  const counter = used.size + 1;
+  return `Scientist #${counter} (${formatRole(role)})`;
+}
+function formatRole(role) {
+  return role.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+
 // src/types/errors.ts
 var ERROR_CODES = {
   // Provider
@@ -3341,11 +3441,46 @@ Working rules:
 - When in doubt, flag as medium rather than ignoring potential issues`
   // Budgets are set by the orchestrator per task — see fleet.ts header.
 };
+var CRITIC_AGENT = {
+  id: "critic",
+  name: "Critic",
+  role: "critic",
+  prompt: `You are the Critic agent. Your job is to evaluate code quality,
+architectural decisions, and proposed changes against project conventions,
+engineering standards, and known quality gates. You do not write code \u2014
+you judge it.
+
+Scope:
+- Evaluate bug severity and fix quality from Bug Hunter reports
+- Score refactoring plans from Refactor Planner (risk, completeness, trade-offs)
+- Flag gaps in test coverage, error handling, and edge case coverage
+- Assess whether a proposed change aligns with existing project patterns
+- Detect over-engineering or under-engineering relative to the problem scope
+
+Input format you accept:
+{ "task": "evaluate | score | review", "subject": "bug_report | refactor_plan | diff", "focus": "correctness | maintainability | risk | all" }
+
+Output: Markdown critic report:
+- ## Overall Score (0-10 with rationale)
+- ## Strengths (what's solid)
+- ## Weaknesses (what needs work)
+- ## Specific Concerns (with file:line when applicable)
+- ## Verdict: **Approve / Needs Revision / Reject**
+
+Working rules:
+- Be specific \u2014 "looks fine" is not a review. Cite concrete evidence.
+- When scoring, explain the delta from a perfect score.
+- If you have no basis to evaluate a concern, say so rather than speculating.
+- Prioritise correctness over style; correctness issues block approval.
+- Score thresholds: \u22657 = Approve, 4-6 = Needs Revision, <4 = Reject`
+  // Budgets are set by the orchestrator per task — see fleet.ts header.
+};
 var FLEET_ROSTER = {
   "audit-log": AUDIT_LOG_AGENT,
   "bug-hunter": BUG_HUNTER_AGENT,
   "refactor-planner": REFACTOR_PLANNER_AGENT,
   "security-scanner": SECURITY_SCANNER_AGENT,
+  "critic": CRITIC_AGENT,
   ...Object.fromEntries(
     ALL_AGENT_DEFINITIONS.map((d) => [d.config.role, d.config])
   )
@@ -3355,6 +3490,7 @@ var FLEET_ROSTER_BUDGETS = {
   "bug-hunter": { timeoutMs: 10 * 60 * 60 * 1e3, maxIterations: 8e3, maxToolCalls: 2e4 },
   "refactor-planner": { timeoutMs: 7.5 * 60 * 60 * 1e3, maxIterations: 6e3, maxToolCalls: 18e3 },
   "security-scanner": { timeoutMs: 10 * 60 * 60 * 1e3, maxIterations: 8e3, maxToolCalls: 2e4 },
+  "critic": { timeoutMs: 5 * 60 * 60 * 1e3, maxIterations: 4e3, maxToolCalls: 12e3 },
   ...Object.fromEntries(
     ALL_AGENT_DEFINITIONS.map((d) => [d.config.role, d.budget])
   )
@@ -4428,7 +4564,6 @@ function makeFleetSessionTool(director) {
       type: "object",
       properties: {
         subagentId: { type: "string", description: "Subagent id to read the transcript of." },
-        /** Number of trailing lines to return (last N JSONL lines). Default: all. */
         tail: { type: "number", description: "Number of trailing JSONL lines to return. Omit for the full transcript." }
       },
       required: ["subagentId"]
@@ -4464,8 +4599,6 @@ function makeFleetHealthTool(director) {
             id: s.id,
             status: s.status,
             lastEventAt: usage?.lastEventAt,
-            // Budget pressure: fraction of each limit consumed if we have it.
-            // BudgetWarning events carry used/limit ratios; surface them here.
             budgetPressure: {
               iterations: usage?.iterations,
               toolCalls: usage?.toolCalls,
@@ -4477,6 +4610,415 @@ function makeFleetHealthTool(director) {
     }
   };
 }
+function makeCollabDebugTool(director) {
+  return {
+    name: "collab_debug",
+    description: "Start a collaborative debugging session: BugHunter, RefactorPlanner, and Critic run in parallel on the same target files. BugHunter finds bugs and emits bug.found events. RefactorPlanner listens for bug.found and emits refactor.plan events. Critic evaluates both and emits critic.evaluation events. Returns a structured report with overall verdict (approve / needs_revision / reject).",
+    permission: "auto",
+    mutating: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        targetPaths: {
+          type: "array",
+          items: { type: "string" },
+          description: "File paths / glob patterns to scan for bugs."
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Timeout in ms. Default: 600000 (10 minutes)."
+        }
+      },
+      required: ["targetPaths"]
+    },
+    async execute(input) {
+      const i = input;
+      if (!i.targetPaths?.length) {
+        return { error: "collab_debug: targetPaths is required and must be non-empty." };
+      }
+      const options = {
+        targetPaths: i.targetPaths,
+        timeoutMs: i.timeoutMs
+      };
+      try {
+        const report = await director.spawnCollab(options);
+        return {
+          sessionId: report.sessionId,
+          overallVerdict: report.overallVerdict,
+          bugCount: report.bugs.length,
+          planCount: report.refactorPlans.length,
+          evaluationCount: report.evaluations.length,
+          summary: report.summary,
+          bugs: report.bugs,
+          refactorPlans: report.refactorPlans,
+          evaluations: report.evaluations
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: "collab_debug failed: " + msg };
+      }
+    }
+  };
+}
+function makeFleetEmitTool(director) {
+  return {
+    name: "fleet_emit",
+    description: "Emit a structured event on the FleetBus. Use this when you find a bug (bug.found), complete a refactor plan (refactor.plan), or finish an evaluation (critic.evaluation). Events are routed to other agents in the collab session.",
+    permission: "auto",
+    mutating: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          description: "Event type: bug.found | refactor.plan | critic.evaluation"
+        },
+        payload: {
+          type: "object",
+          description: "Event payload matching the event type."
+        }
+      },
+      required: ["type", "payload"]
+    },
+    async execute(input) {
+      const i = input;
+      director.fleet.emit({
+        subagentId: director.id,
+        ts: Date.now(),
+        type: i.type,
+        payload: i.payload
+      });
+      return { ok: true, event: i.type };
+    }
+  };
+}
+var CollabSession = class extends EventEmitter {
+  sessionId;
+  options;
+  snapshot;
+  director;
+  fleetBus;
+  subagentIds = /* @__PURE__ */ new Map();
+  // role → subagentId
+  bugs = /* @__PURE__ */ new Map();
+  plans = /* @__PURE__ */ new Map();
+  evaluations = /* @__PURE__ */ new Map();
+  disposers = new Array();
+  settled = false;
+  timeoutMs;
+  constructor(director, fleetBus, options) {
+    super();
+    this.sessionId = randomUUID();
+    this.options = options;
+    this.director = director;
+    this.fleetBus = fleetBus;
+    this.timeoutMs = options.timeoutMs ?? 10 * 60 * 1e3;
+    if (options.prebuiltSnapshot) {
+      this.snapshot = options.prebuiltSnapshot;
+    } else {
+      this.snapshot = {
+        id: this.sessionId,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        files: []
+      };
+    }
+  }
+  /**
+   * Read the target files from disk and populate the snapshot.
+   * Call this after construction if you did not provide a prebuiltSnapshot
+   * and want the session to operate on real file contents.
+   */
+  async buildSnapshot() {
+    if (this.snapshot.files.length > 0) return this.snapshot;
+    for (const filePath of this.options.targetPaths) {
+      try {
+        const content = await fsp5.readFile(filePath, "utf8");
+        const ext = filePath.split(".").pop() ?? "";
+        const language = ext === "ts" || ext === "tsx" ? "typescript" : ext === "js" || ext === "jsx" ? "javascript" : ext === "md" ? "markdown" : ext === "json" ? "json" : void 0;
+        this.snapshot.files.push({ path: filePath, content, language });
+      } catch {
+        this.snapshot.files.push({ path: filePath, content: "", language: void 0 });
+      }
+    }
+    return this.snapshot;
+  }
+  /**
+   * Start the collaborative session: snapshot files, spawn all three agents,
+   * wire up event routing, and wait for completion.
+   */
+  async start() {
+    if (this.settled) throw new Error("session already settled");
+    this.settled = true;
+    await this.buildSnapshot();
+    this.wireFleetBus();
+    const [bugHunterId, refactorPlannerId, criticId] = await Promise.all([
+      this.spawnAgent("bug-hunter", this.buildBugHunterTask()),
+      this.spawnAgent("refactor-planner", this.buildRefactorPlannerTask()),
+      this.spawnAgent("critic", this.buildCriticTask())
+    ]);
+    this.subagentIds.set("bug-hunter", bugHunterId);
+    this.subagentIds.set("refactor-planner", refactorPlannerId);
+    this.subagentIds.set("critic", criticId);
+    const timeout = new Promise((_, reject) => {
+      setTimeout(
+        () => reject(new Error(`CollabSession timed out after ${this.timeoutMs}ms`)),
+        this.timeoutMs
+      );
+    });
+    let results;
+    try {
+      results = await Promise.race([
+        Promise.all([
+          this.director.awaitTasks([bugHunterId]),
+          this.director.awaitTasks([refactorPlannerId]),
+          this.director.awaitTasks([criticId])
+        ]),
+        timeout
+      ]);
+    } catch (err) {
+      this.cleanup();
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.emit("session.error", error);
+      throw error;
+    }
+    for (const result of results.flat()) {
+      await this.parseAndEmit(result);
+    }
+    const report = this.assembleReport();
+    this.cleanup();
+    this.emit("session.done", report);
+    return report;
+  }
+  /**
+   * Parse a completed agent's final text output and route the structured
+   * findings onto the FleetBus. Agents are instructed to emit one JSON object
+   * per finding / plan / evaluation; we scan the output for balanced JSON
+   * objects (tolerating prose, markdown, and ```json fences around them) and
+   * dispatch each by its discriminating key. The wired FleetBus listeners then
+   * collect them into the bugs / plans / evaluations maps.
+   *
+   * Failed or empty results are ignored, and a single malformed object never
+   * aborts the collation pass — see {@link extractJsonObjects}.
+   */
+  async parseAndEmit(result) {
+    if (result.status !== "success" || result.result == null) return;
+    const text = typeof result.result === "string" ? result.result : JSON.stringify(result.result);
+    for (const obj of this.extractJsonObjects(text)) {
+      const type = "finding" in obj ? "bug.found" : "plan" in obj ? "refactor.plan" : "evaluation" in obj ? "critic.evaluation" : null;
+      if (!type) continue;
+      this.fleetBus.emit({
+        subagentId: result.subagentId,
+        taskId: result.taskId,
+        ts: Date.now(),
+        type,
+        payload: obj
+      });
+    }
+  }
+  /**
+   * Extract every top-level JSON object embedded in free-form agent text.
+   * Scans for balanced braces while respecting string literals and escape
+   * sequences, so prose, markdown headers, and code fences around the JSON
+   * are skipped. Malformed spans are dropped silently rather than thrown.
+   */
+  extractJsonObjects(text) {
+    const objects = [];
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+      const ch = text[i];
+      if (inString) {
+        if (escaped) escaped = false;
+        else if (ch === "\\") escaped = true;
+        else if (ch === '"') inString = false;
+        continue;
+      }
+      if (ch === '"') {
+        inString = true;
+      } else if (ch === "{") {
+        if (depth === 0) start = i;
+        depth++;
+      } else if (ch === "}" && depth > 0) {
+        depth--;
+        if (depth === 0 && start >= 0) {
+          const candidate = text.slice(start, i + 1);
+          try {
+            const parsed = JSON.parse(candidate);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+              objects.push(parsed);
+            }
+          } catch {
+          }
+          start = -1;
+        }
+      }
+    }
+    return objects;
+  }
+  async spawnAgent(role, taskBrief) {
+    const cfg = {
+      id: `${role}-${this.sessionId}`,
+      name: role,
+      role
+      // No fleet_emit tool — agents output structured JSON, the Director parses
+      // results and emits FleetBus events. This keeps the agent simple and the
+      // routing deterministic.
+    };
+    const subagentId = await this.director.spawn(cfg);
+    await this.director.assign({
+      id: randomUUID(),
+      subagentId,
+      description: taskBrief
+    });
+    return subagentId;
+  }
+  buildBugHunterTask() {
+    this.options.targetPaths.join(", ");
+    const scratchpad = this.director.sharedScratchpadPath ?? "/tmp";
+    const fileContents = this.snapshot.files.map((f) => `=== ${f.path} ===
+${f.content}`).join("\n\n");
+    return `You are BugHunter. Scan the following files for bugs and code smells.
+
+Target files:
+${fileContents}
+
+For each bug found, write ONE valid JSON line to the scratchpad with this exact structure:
+{ "finding": { "id": "<uuid>", "type": "<pattern>", "severity": "<critical|high|medium|low>", "location": { "file": "<path>", "line": <n> }, "description": "<explain>", "suggestedFix": "<optional>" } }.
+After scanning all files, write your full markdown bug report to the shared scratchpad at:
+${scratchpad}/bug-hunter-report-${this.sessionId}.md`;
+  }
+  buildRefactorPlannerTask() {
+    const scratchpad = this.director.sharedScratchpadPath ?? "/tmp";
+    const fileContents = this.snapshot.files.map((f) => `=== ${f.path} ===
+${f.content}`).join("\n\n");
+    return `You are RefactorPlanner. Plan refactorings for the following files.
+
+Target files:
+${fileContents}
+
+Listen for bug.found events from BugHunter on the fleet bus. For each bug, create a refactor plan and write one JSON line per plan:
+{ "plan": { "id": "<uuid>", "basedOnBugIds": ["<bug-id>"], "phases": [...], "riskScore": "<low|medium|high>", "estimatedChangeCount": <n>, "rollbackStrategy": "<text>" } }.
+After planning, write your full markdown plan to:
+${scratchpad}/refactor-plan-${this.sessionId}.md`;
+  }
+  buildCriticTask() {
+    const scratchpad = this.director.sharedScratchpadPath ?? "/tmp";
+    const fileContents = this.snapshot.files.map((f) => `=== ${f.path} ===
+${f.content}`).join("\n\n");
+    return `You are Critic. Evaluate bug findings and refactor plans as they arrive via fleet bus events.
+
+Target files:
+${fileContents}
+
+Subscribe to bug.found events (from BugHunter) and refactor.plan events (from RefactorPlanner). For each subject, write one JSON line per evaluation:
+{ "evaluation": { "id": "<uuid>", "subjectType": "<bug_finding|refactor_plan>", "subjectId": "<id>", "score": <0-10>, "verdict": "<approve|needs_revision|reject>", "strengths": [...], "weaknesses": [...], "concerns": [...] } }.
+After all evaluations, write your markdown critic report to:
+${scratchpad}/critic-report-${this.sessionId}.md`;
+  }
+  wireFleetBus() {
+    const d1 = this.fleetBus.filter("bug.found", (e) => {
+      const payload = e.payload;
+      if (payload?.finding) {
+        this.bugs.set(payload.finding.id, payload.finding);
+        this.emit("bug.found", payload);
+      }
+    });
+    this.disposers.push(d1);
+    const d2 = this.fleetBus.filter("refactor.plan", (e) => {
+      const payload = e.payload;
+      if (payload?.plan) {
+        this.plans.set(payload.plan.id, payload.plan);
+        this.emit("refactor.plan", payload);
+      }
+    });
+    this.disposers.push(d2);
+    const d3 = this.fleetBus.filter("critic.evaluation", (e) => {
+      const payload = e.payload;
+      if (payload?.evaluation) {
+        this.evaluations.set(payload.evaluation.id, payload.evaluation);
+        this.emit("critic.evaluation", payload);
+      }
+    });
+    this.disposers.push(d3);
+  }
+  assembleReport() {
+    const bugList = Array.from(this.bugs.values());
+    const planList = Array.from(this.plans.values());
+    const evalList = Array.from(this.evaluations.values());
+    const verdictOrder = {
+      approve: 0,
+      needs_revision: 1,
+      reject: 2
+    };
+    const overallVerdict = evalList.reduce(
+      (worst, eval_) => {
+        const w = verdictOrder[worst];
+        const c = verdictOrder[eval_.verdict];
+        return c > w ? eval_.verdict : worst;
+      },
+      "approve"
+    );
+    const summary = this.buildMarkdownSummary(bugList, planList, evalList, overallVerdict);
+    return {
+      sessionId: this.sessionId,
+      startedAt: this.snapshot.createdAt,
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      targetPaths: this.options.targetPaths,
+      bugs: bugList,
+      refactorPlans: planList,
+      evaluations: evalList,
+      overallVerdict,
+      summary
+    };
+  }
+  buildMarkdownSummary(bugs, plans, evals, overallVerdict) {
+    const lines = [
+      `## Collaborative Debugging Report \u2014 ${this.sessionId}`,
+      "",
+      `**Target:** ${this.options.targetPaths.join(", ")}`,
+      `**Overall Verdict:** **${overallVerdict.toUpperCase()}**`,
+      ""
+    ];
+    if (bugs.length > 0) {
+      lines.push("### Bugs Found", "");
+      for (const b of bugs) {
+        lines.push(
+          `- **[${b.severity.toUpperCase()}]** \`${b.location.file}:${b.location.line}\` \u2014 ${b.description}`
+        );
+      }
+      lines.push("");
+    }
+    if (plans.length > 0) {
+      lines.push("### Refactor Plans", "");
+      for (const p of plans) {
+        lines.push(`- **Phase plan** (risk: ${p.riskScore}, ~${p.estimatedChangeCount} changes)`);
+        for (const phase of p.phases) {
+          lines.push(`  - Phase ${phase.number}: ${phase.title} [${phase.risk}]`);
+        }
+      }
+      lines.push("");
+    }
+    if (evals.length > 0) {
+      lines.push("### Critic Evaluations", "");
+      for (const e of evals) {
+        lines.push(`- [${e.subjectType}] score=${e.score}/10 \u2014 **${e.verdict.toUpperCase()}**`);
+        for (const c of e.concerns) {
+          if (c.severity === "blocking") {
+            lines.push(`  - ${c.description}`);
+          }
+        }
+      }
+      lines.push("");
+    }
+    return lines.join("\n");
+  }
+  cleanup() {
+    for (const dispose of this.disposers) dispose();
+    this.disposers.length = 0;
+  }
+};
 
 // src/coordination/director.ts
 var FleetSpawnBudgetError = class extends Error {
@@ -4555,6 +5097,8 @@ var Director = class {
   subagentBridges = /* @__PURE__ */ new Map();
   /** Tracks per-spawn config + assigned task ids for manifest writing. */
   manifestEntries = /* @__PURE__ */ new Map();
+  /** Tracks assigned nicknames so the same name is never reused in one fleet. */
+  _usedNicknames = /* @__PURE__ */ new Set();
   manifestPath;
   roster;
   directorPreamble;
@@ -4632,7 +5176,7 @@ var Director = class {
     }, opts.checkpointDebounceMs ?? 250) : null;
     this.fleetManager = opts.fleetManager;
     if (this.sharedScratchpadPath) {
-      void fsp4.mkdir(this.sharedScratchpadPath, { recursive: true }).catch(
+      void fsp5.mkdir(this.sharedScratchpadPath, { recursive: true }).catch(
         (err) => this.logShutdownError("shared_scratchpad_mkdir", err)
       );
     }
@@ -4848,9 +5392,21 @@ var Director = class {
       }
     }
     let result;
+    const needsNickname = config.name === config.role || !config.name || config.name === "subagent";
+    if (needsNickname) {
+      const role = config.role ?? "subagent";
+      if (this.fleetManager) {
+        this.fleetManager.assignNicknameAndRecord("", config, priceLookup);
+      } else {
+        config.name = assignNickname(role, this._usedNicknames);
+        this._usedNicknames.add(config.name.split(" ")[0].toLowerCase().replace(/[^a-z0-9-]/g, "-"));
+      }
+    }
     result = await this.coordinator.spawn(config);
     if (this.fleetManager) {
-      this.fleetManager.recordSpawn(result.subagentId, config, priceLookup);
+      if (!needsNickname) {
+        this.fleetManager.recordSpawn(result.subagentId, config, priceLookup);
+      }
     } else {
       this.spawnCount += 1;
       this.subagentMeta.set(result.subagentId, {
@@ -5006,7 +5562,7 @@ var Director = class {
       })),
       usage: this.usage.snapshot()
     };
-    await fsp4.mkdir(path4.dirname(this.manifestPath), { recursive: true });
+    await fsp5.mkdir(path4.dirname(this.manifestPath), { recursive: true });
     await atomicWrite(this.manifestPath, JSON.stringify(manifest, null, 2), { mode: 384 });
     return this.manifestPath;
   }
@@ -5175,7 +5731,7 @@ var Director = class {
     const filePath = path4.join(this.sessionsRoot, this.directorRunId, `${subagentId}.jsonl`);
     let raw;
     try {
-      raw = await fsp4.readFile(filePath, "utf8");
+      raw = await fsp5.readFile(filePath, "utf8");
     } catch {
       return null;
     }
@@ -5286,7 +5842,9 @@ var Director = class {
       makeFleetStatusTool(this),
       makeFleetUsageTool(this),
       makeFleetSessionTool(this),
-      makeFleetHealthTool(this)
+      makeFleetHealthTool(this),
+      makeCollabDebugTool(this),
+      makeFleetEmitTool(this)
     ];
     return t;
   }
@@ -5298,6 +5856,17 @@ var Director = class {
   async acquireCheckpointLock() {
     return this.stateCheckpoint ? this.stateCheckpoint.acquireLock() : true;
   }
+  /**
+   * Start a collaborative debugging session: BugHunter, RefactorPlanner,
+   * and Critic run in parallel on the same target files, with findings
+   * flowing through the FleetBus (bug.found → refactor.plan →
+   * critic.evaluation). Returns a structured CollabDebugReport when all
+   * three agents complete or the session times out.
+   */
+  async spawnCollab(options) {
+    const session = new CollabSession(this, this.fleet, options);
+    return session.start();
+  }
   /**
    * Resume from a prior checkpoint snapshot (loaded via
    * `loadDirectorState()`). Re-attach to the fleet mid-flight so
@@ -5578,7 +6147,7 @@ async function readSubagentPartial(opts, subagentId) {
     candidates.push(path4.join(opts.sessionsRoot, opts.directorRunId, `${subagentId}.jsonl`));
   } else {
     try {
-      const entries = await fsp4.readdir(opts.sessionsRoot, { withFileTypes: true });
+      const entries = await fsp5.readdir(opts.sessionsRoot, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.isDirectory()) {
           candidates.push(path4.join(opts.sessionsRoot, entry.name, `${subagentId}.jsonl`));
@@ -5591,7 +6160,7 @@ async function readSubagentPartial(opts, subagentId) {
   for (const file of candidates) {
     let raw;
     try {
-      raw = await fsp4.readFile(file, "utf8");
+      raw = await fsp5.readFile(file, "utf8");
     } catch {
       continue;
     }
@@ -5887,9 +6456,11 @@ function isEmptyMessage(msg) {
 var DefaultSessionStore = class {
   dir;
   events;
+  secretScrubber;
   constructor(opts) {
     this.dir = opts.dir;
     this.events = opts.events;
+    this.secretScrubber = opts.secretScrubber;
   }
   /** Join session ID to its absolute path within the store directory. */
   sessionPath(id, ext) {
@@ -5906,7 +6477,7 @@ var DefaultSessionStore = class {
     const file = path4.join(shardDir, `${id}.jsonl`);
     let handle;
     try {
-      handle = await fsp4.open(file, "a", 384);
+      handle = await fsp5.open(file, "a", 384);
     } catch (err) {
       throw new Error(
         `Failed to open session file: ${err instanceof Error ? err.message : String(err)}`,
@@ -5914,7 +6485,11 @@ var DefaultSessionStore = class {
       );
     }
     try {
-      return new FileSessionWriter(id, handle, startedAt, meta, this.events, { dir: shardDir, filePath: file });
+      return new FileSessionWriter(id, handle, startedAt, meta, this.events, {
+        dir: shardDir,
+        filePath: file,
+        secretScrubber: this.secretScrubber
+      });
     } catch (err) {
       await handle.close().catch(() => {
       });
@@ -5926,7 +6501,7 @@ var DefaultSessionStore = class {
     const data = await this.load(id);
     let handle;
     try {
-      handle = await fsp4.open(file, "a", 384);
+      handle = await fsp5.open(file, "a", 384);
     } catch (err) {
       throw new Error(
         `Failed to open session "${id}" for append: ${err instanceof Error ? err.message : String(err)}`,
@@ -5944,7 +6519,7 @@ var DefaultSessionStore = class {
           provider: data.metadata.provider
         },
         this.events,
-        { resumed: true, dir: this.dir, filePath: file }
+        { resumed: true, dir: this.dir, filePath: file, secretScrubber: this.secretScrubber }
       );
       return { writer, data };
     } catch (err) {
@@ -5955,7 +6530,7 @@ var DefaultSessionStore = class {
   }
   async load(id) {
     const file = this.sessionPath(id, ".jsonl");
-    const raw = await fsp4.readFile(file, "utf8");
+    const raw = await fsp5.readFile(file, "utf8");
     const lines = raw.split("\n").filter((l) => l.trim());
     const events = [];
     for (const line of lines) {
@@ -5990,7 +6565,7 @@ var DefaultSessionStore = class {
   /** Recursively collect all session IDs from shard subdirectories. */
   async collectSessionIds(dir) {
     const ids = [];
-    const entries = await fsp4.readdir(dir, { withFileTypes: true });
+    const entries = await fsp5.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
       const full = path4.join(dir, entry.name);
       if (entry.isDirectory()) {
@@ -6004,11 +6579,11 @@ var DefaultSessionStore = class {
   async summaryFor(id) {
     const manifest = this.sessionPath(id, ".summary.json");
     try {
-      const raw = await fsp4.readFile(manifest, "utf8");
+      const raw = await fsp5.readFile(manifest, "utf8");
       return JSON.parse(raw);
     } catch {
       const full = this.sessionPath(id, ".jsonl");
-      const stat3 = await fsp4.stat(full);
+      const stat3 = await fsp5.stat(full);
       const summary = await this.summarize(id, stat3.mtime.toISOString());
       await atomicWrite(manifest, JSON.stringify(summary), { mode: 384 }).catch((err) => {
         console.warn(
@@ -6020,8 +6595,8 @@ var DefaultSessionStore = class {
     }
   }
   async delete(id) {
-    await fsp4.unlink(this.sessionPath(id, ".jsonl"));
-    await fsp4.unlink(this.sessionPath(id, ".summary.json")).catch(() => void 0);
+    await fsp5.unlink(this.sessionPath(id, ".jsonl"));
+    await fsp5.unlink(this.sessionPath(id, ".summary.json")).catch(() => void 0);
   }
   async clearHistory(id) {
     await this.ensureShardDir(id);
@@ -6035,8 +6610,8 @@ var DefaultSessionStore = class {
       provider: "unknown"
     })}
 `;
-    await fsp4.writeFile(file, record, "utf8");
-    await fsp4.unlink(meta).catch(() => void 0);
+    await fsp5.writeFile(file, record, "utf8");
+    await fsp5.unlink(meta).catch(() => void 0);
   }
   async summarize(id, mtime) {
     try {
@@ -6150,6 +6725,7 @@ var FileSessionWriter = class {
     this.resumed = opts.resumed ?? false;
     this.manifestFile = opts.dir ? path4.join(opts.dir, `${id}.summary.json`) : "";
     this.filePath = opts.filePath ?? "";
+    this.secretScrubber = opts.secretScrubber;
     this.summary = {
       id,
       title: "(empty session)",
@@ -6178,6 +6754,29 @@ var FileSessionWriter = class {
   resumed;
   appendFailCount = 0;
   lastAppendWarnAt = 0;
+  secretScrubber;
+  /**
+   * Scrub secrets out of conversation-turn events before they are observed
+   * for the summary, written to the JSONL log, or surfaced on resume. Only
+   * `user_input` / `llm_response` carry free-form user/model text; other event
+   * types either have no secret-bearing content or are already scrubbed
+   * upstream (tool results). Returns the event unchanged when no scrubber is
+   * configured.
+   */
+  scrubEvent(event) {
+    const s = this.secretScrubber;
+    if (!s) return event;
+    if (event.type === "user_input") {
+      return {
+        ...event,
+        content: typeof event.content === "string" ? s.scrub(event.content) : s.scrubObject(event.content)
+      };
+    }
+    if (event.type === "llm_response") {
+      return { ...event, content: s.scrubObject(event.content) };
+    }
+    return event;
+  }
   promptIndex = 0;
   pendingFileSnapshots = [];
   /** Tracks open tool_use IDs during the current run to serialize on close for resume. */
@@ -6199,7 +6798,7 @@ var FileSessionWriter = class {
 `;
     try {
       if (this.filePath) {
-        await fsp4.writeFile(this.filePath, record, { flag: "a", mode: 384 });
+        await fsp5.writeFile(this.filePath, record, { flag: "a", mode: 384 });
       }
     } catch {
     }
@@ -6210,9 +6809,10 @@ var FileSessionWriter = class {
       this.initDone = true;
       await this.writeSessionStartLazy();
     }
-    this.observeForSummary(event);
+    const scrubbed = this.scrubEvent(event);
+    this.observeForSummary(scrubbed);
     try {
-      await this.handle.appendFile(`${JSON.stringify(event)}
+      await this.handle.appendFile(`${JSON.stringify(scrubbed)}
 `, "utf8");
     } catch (err) {
       this.appendFailCount++;
@@ -6292,7 +6892,7 @@ var FileSessionWriter = class {
   }
   async truncateToCheckpoint(targetPromptIndex) {
     if (!this.filePath) return 0;
-    const raw = await fsp4.readFile(this.filePath, "utf8");
+    const raw = await fsp5.readFile(this.filePath, "utf8");
     const lines = raw.split("\n");
     const kept = [];
     let removedCount = 0;
@@ -6330,13 +6930,13 @@ var FileSessionWriter = class {
     }
     const truncated = kept.join("\n");
     const tmpPath = `${this.filePath}.rewind.tmp`;
-    await fsp4.writeFile(tmpPath, truncated + "\n", "utf8");
+    await fsp5.writeFile(tmpPath, truncated + "\n", "utf8");
     try {
       await this.handle.close();
-      await fsp4.rename(tmpPath, this.filePath);
-      this.handle = await fsp4.open(this.filePath, "a", 384);
+      await fsp5.rename(tmpPath, this.filePath);
+      this.handle = await fsp5.open(this.filePath, "a", 384);
     } catch (err) {
-      await fsp4.unlink(tmpPath).catch(() => void 0);
+      await fsp5.unlink(tmpPath).catch(() => void 0);
       throw err;
     }
     await this.append({
@@ -6362,7 +6962,7 @@ var FileSessionWriter = class {
       provider: this.meta.provider ?? "unknown"
     })}
 `;
-    await fsp4.writeFile(this.filePath, record, "utf8");
+    await fsp5.writeFile(this.filePath, record, "utf8");
   }
 };
 function userInputTitle(content) {
@@ -6488,6 +7088,8 @@ var FleetManager = class {
   pendingTasks = /* @__PURE__ */ new Map();
   subagentMeta = /* @__PURE__ */ new Map();
   priceLookups = /* @__PURE__ */ new Map();
+  /** Tracks which nickname keys are already assigned — prevents collisions. */
+  _usedNicknames = /* @__PURE__ */ new Set();
   /** The coordinator (wired via setCoordinator by Director after construction). */
   coordinator = null;
   constructor(opts = {}) {
@@ -6568,6 +7170,30 @@ var FleetManager = class {
     }
     return null;
   }
+  /**
+   * Assign a memorable nickname (e.g. "Einstein (Bug Hunter)") to the config,
+   * record it so the same name is never reused, then record the spawn.
+   *
+   * Call this INSTEAD of `recordSpawn` when you want automatic nicknames.
+   * The nickname is written back to `config.name` BEFORE the coordinator
+   * sees the config, so the manifest, logs, and fleet UI all show it.
+   */
+  assignNicknameAndRecord(subagentId, config, priceLookup) {
+    const role = config.role ?? "subagent";
+    const nickname = assignNickname(role, this._usedNicknames);
+    const baseKey = nickname.split(" ")[0].toLowerCase().replace(/[^a-z0-9-]/g, "-");
+    this._usedNicknames.add(baseKey);
+    config.name = nickname;
+    this.recordSpawn(subagentId, config, priceLookup);
+    return nickname;
+  }
+  /**
+   * Returns the set of already-assigned nickname keys — useful for debugging
+   * and testing.
+   */
+  get usedNicknames() {
+    return this._usedNicknames;
+  }
   /**
    * Records a spawn: increments counter, stores metadata, updates state checkpoint,
    * and schedules a debounced manifest write. Call AFTER the coordinator
@@ -6626,7 +7252,7 @@ var FleetManager = class {
       })),
       usage: this.usage.snapshot()
     };
-    await fsp4.mkdir(path4.dirname(this.manifestPath), { recursive: true });
+    await fsp5.mkdir(path4.dirname(this.manifestPath), { recursive: true });
     await atomicWrite(this.manifestPath, JSON.stringify(manifest, null, 2), { mode: 384 });
     return this.manifestPath;
   }
@@ -6738,6 +7364,6 @@ var FleetManager = class {
   }
 };
 
-export { ACP_AGENTS, AGENTS_BY_PHASE, AGENT_CATALOG, TOOLS as AGENT_TOOL_PRESETS, ALL_AGENT_DEFINITIONS, ALL_FLEET_AGENTS, AUDIT_LOG_AGENT, BUG_HUNTER_AGENT, BUILD_AGENTS, BudgetExceededError, BudgetThresholdSignal, DEFAULT_DIRECTOR_PREAMBLE, DEFAULT_DISPATCH_ROLE, DEFAULT_SUBAGENT_BASELINE, DELIVERY_AGENTS, DISCOVERY_AGENTS, DOMAIN_AGENTS, DefaultMultiAgentCoordinator, Director, FLEET_ROSTER, FLEET_ROSTER_BUDGETS, FLEET_ROSTER_WITHACP, FleetBus, FleetCostCapError, FleetManager, FleetSpawnBudgetError, FleetUsageAggregator, HEAVY_BUDGET, InMemoryAgentBridge, InMemoryBridgeTransport, KNOWLEDGE_AGENTS, LIGHT_BUDGET, MEDIUM_BUDGET, META_AGENTS, NULL_FLEET_BUS, PLANNING_AGENTS, REFACTOR_PLANNER_AGENT, REVIEW_AGENTS, SECURITY_SCANNER_AGENT, SubagentBudget, VERIFY_AGENTS, applyRosterBudget, attachAutoExtend, composeDirectorPrompt, composeSubagentPrompt, createDelegateTool, createMessage, dispatchAgent, getAgentDefinition, makeAgentSubagentRunner, makeDirectorSessionFactory, makeLLMClassifier, rosterSummaryFromConfigs, scoreAgents };
+export { ACP_AGENTS, AGENTS_BY_PHASE, AGENT_CATALOG, TOOLS as AGENT_TOOL_PRESETS, ALL_AGENT_DEFINITIONS, ALL_FLEET_AGENTS, AUDIT_LOG_AGENT, BUG_HUNTER_AGENT, BUILD_AGENTS, BudgetExceededError, BudgetThresholdSignal, DEFAULT_DIRECTOR_PREAMBLE, DEFAULT_DISPATCH_ROLE, DEFAULT_SUBAGENT_BASELINE, DELIVERY_AGENTS, DISCOVERY_AGENTS, DOMAIN_AGENTS, DefaultMultiAgentCoordinator, Director, FLEET_ROSTER, FLEET_ROSTER_BUDGETS, FLEET_ROSTER_WITHACP, FleetBus, FleetCostCapError, FleetManager, FleetSpawnBudgetError, FleetUsageAggregator, HEAVY_BUDGET, InMemoryAgentBridge, InMemoryBridgeTransport, KNOWLEDGE_AGENTS, LIGHT_BUDGET, MEDIUM_BUDGET, META_AGENTS, NULL_FLEET_BUS, PLANNING_AGENTS, REFACTOR_PLANNER_AGENT, REVIEW_AGENTS, SECURITY_SCANNER_AGENT, SubagentBudget, VERIFY_AGENTS, applyRosterBudget, attachAutoExtend, composeDirectorPrompt, composeSubagentPrompt, createDelegateTool, createMessage, dispatchAgent, getAgentDefinition, makeAgentSubagentRunner, makeAskTool, makeAssignTool, makeAwaitTasksTool, makeCollabDebugTool, makeDirectorSessionFactory, makeFleetEmitTool, makeFleetHealthTool, makeFleetSessionTool, makeFleetStatusTool, makeFleetUsageTool, makeLLMClassifier, makeRollUpTool, makeSpawnTool, makeTerminateTool, rosterSummaryFromConfigs, scoreAgents };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map