@wrongstack/tools 0.287.0 → 0.291.0

package/dist/builtin.js

@@ -337,8 +337,10 @@ function redactCommand(cmd) {
         const flag = match.slice(0, match.indexOf(expectDefined(delim)) + 1);
         return `${flag}[REDACTED]`;
       }
-      const flagEnd = match.match(/^--?[a-zA-Z][a-zA-Z0-9_-]*/)?.[0] ?? match;
-      return `${flagEnd}=**redacted**`;
+      if (match.startsWith("--")) {
+        return match;
+      }
+      return `${match.slice(0, 2)}[REDACTED]`;
     });
   }
   return result;
@@ -350,9 +352,14 @@ var init_redact_command = __esm({
     SENSITIVE_FLAG_PATTERNS = [
       // --flag=value  or  --flag "value"  (value captured up to next space or comma)
       /--(?:token|password|passwd|pwd|secret|api[-_]?key|api[-_]?secret|auth|credential|private[-_]?key|access[-_]?key|github[-_]?token|gh[-_]?token|bearer|jwt|oauth|pin|pincode|passphrase|access[-_]?token)(?:[=\s,][^\s]*)?/gi,
-      // -f "value" style short flags
-      /(?<!\w)-t(?:\s+|\s*=\s*)[^\s,]+/,
-      /(?<!\w)-(?:p|password)(?:\s+|\s*=\s*)[^\s,]+/gi,
+      // -t short flag (token): attached (-tVALUE), separated (-t VALUE), or -t=VALUE.
+      // (?<![-\w]) anchors to a token start so we don't match the `-t` inside `--token`.
+      // NOTE: synced with @wrongstack/core observability/redact-command.ts.
+      /(?<![-\w])-t(?:[=\s]+)?[^\s,-]+/,
+      // -p|-password|-a (redis auth) short flags: attached + separated + =value.
+      // Same token-start anchor; over-redaction is an accepted tradeoff for a
+      // redaction function. Synced with core copy.
+      /(?<![-\w])-(?:password|p|a)(?:[=\s]+)?[^\s,-]+/gi,
       // env var–style secrets: TOKEN=x, API_KEY=y, etc.
       /(?:TOKEN|API_KEY|API_SECRET|AUTH_TOKEN|GITHUB_TOKEN|GH_TOKEN|BEARER|JWT|OAUTH|CREDENTIAL|SECRET|PRIVATE_KEY|PASSWORD|PASSWD)\s*[=:]\s*[^\s,]+/gi,
       // Generic high-entropy look: base64 strings >32 chars or hex strings >32 digits — but only
@@ -799,7 +806,12 @@ var init_win32_resolve = __esm({
 
 // src/_spawn-stream.ts
 import { spawn as spawn2 } from "node:child_process";
-import { buildChildEnv } from "@wrongstack/core";
+import {
+  buildChildEnv,
+  emitProcessCompleted,
+  emitProcessOutput,
+  emitProcessStarted
+} from "@wrongstack/core";
 async function* spawnStream(opts) {
   const max = opts.maxBytes ?? 2e5;
   const flushAt = opts.flushBytes ?? 4 * 1024;
@@ -824,6 +836,19 @@ async function* spawnStream(opts) {
   });
   const registry = getProcessRegistry();
   const pid = child.pid;
+  const processStartedAt = Date.now();
+  let stdoutBytes = 0;
+  let stderrBytes = 0;
+  let telemetryCompleted = false;
+  emitProcessStarted({
+    ...pid !== void 0 ? { pid } : {},
+    parentPid: process.pid,
+    command: redactCommand(`${opts.cmd} ${opts.args.join(" ")}`),
+    args: redactCommand(opts.args.join(" ")).split(" ").filter(Boolean),
+    cwd: opts.cwd,
+    background: false,
+    startedAt: new Date(processStartedAt).toISOString()
+  });
   if (typeof pid === "number") {
     registry.register({
       pid,
@@ -852,6 +877,8 @@ async function* spawnStream(opts) {
   };
   const onOut = (c) => {
     const s = c.toString();
+    stdoutBytes += c.byteLength;
+    emitProcessOutput({ pid, stream: "stdout", chunk: c });
     if (stdout.length < max) stdout += s;
     spool.write(s);
     queue.push({ kind: "out", data: s });
@@ -864,6 +891,8 @@ async function* spawnStream(opts) {
   };
   const onErr = (c) => {
     const s = c.toString();
+    stderrBytes += c.byteLength;
+    emitProcessOutput({ pid, stream: "stderr", chunk: c });
     if (stderr.length < max) stderr += s;
     spool.write(s);
     queue.push({ kind: "err", data: s });
@@ -881,9 +910,25 @@ async function* spawnStream(opts) {
     queue.push({ kind: "error", data: e.message });
     wake();
   });
-  child.on("close", (code) => {
+  const completeTelemetry = (code, signal, timedOut = false) => {
+    if (telemetryCompleted) return;
+    telemetryCompleted = true;
+    emitProcessCompleted({
+      ...pid !== void 0 ? { pid } : {},
+      exitCode: code,
+      ...signal ? { signal } : {},
+      durationMs: Date.now() - processStartedAt,
+      stdoutBytes,
+      stderrBytes,
+      timedOut,
+      endedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  };
+  child.on("close", (code, signal) => {
     if (typeof pid === "number") registry.unregister(pid);
-    queue.push({ kind: "close", data: "", code: code ?? 0 });
+    const exitCode2 = code ?? (signal ? 1 : 0);
+    completeTelemetry(exitCode2, signal ?? void 0);
+    queue.push({ kind: "close", data: "", code: exitCode2, ...signal ? { signal } : {} });
     wake();
   });
   const onAbort = () => {
@@ -896,6 +941,7 @@ async function* spawnStream(opts) {
       }
     }
     queue.push({ kind: "close", data: "", code: 124 });
+    completeTelemetry(124, "SIGKILL", true);
     wake();
   };
   if (isWin) {
@@ -2503,13 +2549,14 @@ async function detectLanguageWorkspaces(options) {
   const target = options.target ? await canonicalInside(resolveFrom(cwd, options.target), projectRoot, "target") : void 0;
   const profiles = (options.profiles ?? languageProfileRegistry.list()).filter((profile) => !options.language || profile.id === options.language).slice().sort((a, b) => a.id.localeCompare(b.id));
   const limits = normalizeLimits(options.limits);
+  const extraIgnores = new Set(options.ignoredDirectories ?? []);
   const state = {
     entries: 0,
     truncated: false,
     sourcePaths: /* @__PURE__ */ new Map(),
     candidates: /* @__PURE__ */ new Map()
   };
-  await scanDirectory(projectRoot, 0, profiles, limits, state, options.signal);
+  await scanDirectory(projectRoot, 0, profiles, limits, state, extraIgnores, options.signal);
   addSourceFallbacks(projectRoot, profiles, state);
   if (target) addTargetEvidence(target, projectRoot, profiles, state);
   const workspaces = await Promise.all(
@@ -2523,7 +2570,7 @@ async function detectLanguageWorkspaces(options) {
     workspaces
   };
 }
-async function scanDirectory(directory, depth, profiles, limits, state, signal) {
+async function scanDirectory(directory, depth, profiles, limits, state, extraIgnores, signal) {
   signal?.throwIfAborted();
   if (depth > limits.maxDepth || state.entries >= limits.maxEntries) {
     state.truncated = true;
@@ -2546,20 +2593,20 @@ async function scanDirectory(directory, depth, profiles, limits, state, signal)
     const fullPath = path4.join(directory, entry.name);
     if (entry.isSymbolicLink()) continue;
     if (entry.isDirectory()) {
-      if (shouldIgnoreDirectory(entry.name, profiles)) continue;
+      if (shouldIgnoreDirectory(entry.name, profiles, extraIgnores)) continue;
       if (depth >= limits.maxDepth) {
         state.truncated = true;
         continue;
       }
-      await scanDirectory(fullPath, depth + 1, profiles, limits, state, signal);
+      await scanDirectory(fullPath, depth + 1, profiles, limits, state, extraIgnores, signal);
       continue;
     }
     if (!entry.isFile()) continue;
     collectFileEvidence(directory, fullPath, entry.name, profiles, state);
   }
 }
-function collectFileEvidence(directory, fullPath, basename8, profiles, state) {
-  const lower = basename8.toLowerCase();
+function collectFileEvidence(directory, fullPath, basename9, profiles, state) {
+  const lower = basename9.toLowerCase();
   const extension = path4.extname(lower);
   for (const profile of profiles) {
     const detector = profile.detectors.find(
@@ -2570,7 +2617,7 @@ function collectFileEvidence(directory, fullPath, basename8, profiles, state) {
       candidate.evidence.push({
         kind: detector.kind,
         path: fullPath,
-        value: basename8,
+        value: basename9,
         weight: detector.weight
       });
       if (detector.kind === "manifest" || detector.kind === "config") {
@@ -2680,8 +2727,8 @@ function getCandidate(state, profile, root) {
   }
   return candidate;
 }
-function shouldIgnoreDirectory(name, profiles) {
-  if (GLOBAL_IGNORES.has(name) || name.startsWith(".")) return true;
+function shouldIgnoreDirectory(name, profiles, extraIgnores) {
+  if (GLOBAL_IGNORES.has(name) || extraIgnores.has(name) || name.startsWith(".")) return true;
   return profiles.some((profile) => profile.ignoredDirectories.includes(name));
 }
 function normalizeLimits(input) {
@@ -4897,6 +4944,11 @@ function parseAuditOutput(json2, exitCode) {
 // src/bash.ts
 import { spawn as spawn3 } from "node:child_process";
 import * as os4 from "node:os";
+import {
+  emitProcessCompleted as emitProcessCompleted2,
+  emitProcessOutput as emitProcessOutput2,
+  emitProcessStarted as emitProcessStarted2
+} from "@wrongstack/core";
 
 // src/_env.ts
 import { buildChildEnv as buildChildEnv2 } from "@wrongstack/core";
@@ -5766,6 +5818,32 @@ var bashTool = {
         }
       }
       const pid2 = child2.pid;
+      let stdoutBytes2 = 0;
+      let stderrBytes2 = 0;
+      let telemetryCompleted2 = false;
+      emitProcessStarted2({
+        ...pid2 !== void 0 ? { pid: pid2 } : {},
+        parentPid: process.pid,
+        command: redactCommand(`${shell} ${args.join(" ")}`),
+        args: redactCommand(args.join(" ")).split(" ").filter(Boolean),
+        cwd: ctx.projectRoot,
+        background: true,
+        startedAt: new Date(startedAt).toISOString()
+      });
+      const completeBackground = (exitCode, signal) => {
+        if (telemetryCompleted2) return;
+        telemetryCompleted2 = true;
+        emitProcessCompleted2({
+          ...pid2 !== void 0 ? { pid: pid2 } : {},
+          exitCode,
+          ...signal ? { signal } : {},
+          durationMs: Date.now() - startedAt,
+          stdoutBytes: stdoutBytes2,
+          stderrBytes: stderrBytes2,
+          timedOut: false,
+          endedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      };
       if (typeof pid2 === "number") {
         registry.register({
           pid: pid2,
@@ -5778,7 +5856,10 @@ var bashTool = {
         });
         child2.on("close", () => registry.unregister(pid2));
       }
-      const onBgData = (chunk) => {
+      const onBgData = (chunk, stream) => {
+        if (stream === "stdout") stdoutBytes2 += chunk.byteLength;
+        else stderrBytes2 += chunk.byteLength;
+        emitProcessOutput2({ pid: pid2, stream, chunk });
         if (truncated) return;
         const remain = MAX_OUTPUT - buf2.length;
         if (remain > 0) {
@@ -5786,24 +5867,28 @@ var bashTool = {
         }
         if (buf2.length >= MAX_OUTPUT) {
           truncated = true;
-          child2.stdout?.off("data", onBgData);
-          child2.stderr?.off("data", onBgData);
+          child2.stdout?.off("data", onBgStdout);
+          child2.stderr?.off("data", onBgStderr);
         }
       };
-      child2.stdout?.on("data", onBgData);
-      child2.stderr?.on("data", onBgData);
+      const onBgStdout = (chunk) => onBgData(chunk, "stdout");
+      const onBgStderr = (chunk) => onBgData(chunk, "stderr");
+      child2.stdout?.on("data", onBgStdout);
+      child2.stderr?.on("data", onBgStderr);
       const cleanupBackground = () => {
-        child2.stdout?.off("data", onBgData);
-        child2.stderr?.off("data", onBgData);
+        child2.stdout?.off("data", onBgStdout);
+        child2.stderr?.off("data", onBgStderr);
       };
       child2.on("error", () => {
         cleanupBackground();
         if (typeof pid2 === "number") registry.unregister(pid2);
         registry.afterCall(Date.now() - startedAt, true, bypassBreaker);
+        completeBackground(1);
       });
-      child2.on("close", () => {
+      child2.on("close", (code, signal) => {
         cleanupBackground();
         registry.afterCall(Date.now() - startedAt, false, bypassBreaker);
+        completeBackground(code ?? (signal ? 1 : 0), signal ?? void 0);
       });
       if (typeof pid2 === "number") child2.unref();
       yield {
@@ -5843,6 +5928,32 @@ var bashTool = {
       }
     }
     const pid = child.pid;
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let telemetryCompleted = false;
+    emitProcessStarted2({
+      ...pid !== void 0 ? { pid } : {},
+      parentPid: process.pid,
+      command: redactCommand(`${shell} ${args.join(" ")}`),
+      args: redactCommand(args.join(" ")).split(" ").filter(Boolean),
+      cwd: ctx.projectRoot,
+      background: false,
+      startedAt: new Date(startedAt).toISOString()
+    });
+    const completeForeground = (exitCode, signal) => {
+      if (telemetryCompleted) return;
+      telemetryCompleted = true;
+      emitProcessCompleted2({
+        ...pid !== void 0 ? { pid } : {},
+        exitCode,
+        ...signal ? { signal } : {},
+        durationMs: Date.now() - startedAt,
+        stdoutBytes,
+        stderrBytes,
+        timedOut,
+        endedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    };
     if (typeof pid === "number") {
       registry.register({
         pid,
@@ -5944,8 +6055,11 @@ var bashTool = {
         child.stderr?.resume();
       }
     };
-    const onData = (chunk) => {
+    const onData = (chunk, stream) => {
       const text = chunk.toString();
+      if (stream === "stdout") stdoutBytes += chunk.byteLength;
+      else stderrBytes += chunk.byteLength;
+      emitProcessOutput2({ pid, stream, chunk });
       if (buf.length < MAX_OUTPUT) {
         buf += text.slice(0, MAX_OUTPUT - buf.length);
       }
@@ -5954,17 +6068,21 @@ var bashTool = {
       push({ kind: "data", text });
       pauseIfFlooded();
     };
-    child.stdout?.on("data", onData);
-    child.stderr?.on("data", onData);
+    const onStdoutData = (chunk) => onData(chunk, "stdout");
+    const onStderrData = (chunk) => onData(chunk, "stderr");
+    child.stdout?.on("data", onStdoutData);
+    child.stderr?.on("data", onStderrData);
     child.on("error", (err) => {
       for (const t of timers) clearTimeout(t);
       registry.afterCall(Date.now() - startedAt, true);
+      completeForeground(1);
       push({ kind: "error", err });
     });
-    child.on("close", (code) => {
+    child.on("close", (code, signal) => {
       for (const t of timers) clearTimeout(t);
       if (typeof pid === "number") registry.unregister(pid);
       registry.afterCall(Date.now() - startedAt, code !== 0 && code !== null);
+      completeForeground(timedOut ? 124 : code ?? (signal ? 1 : 0), signal ?? void 0);
       push({ kind: "end", code });
     });
     try {
@@ -6009,8 +6127,8 @@ ${hint}` : ""),
       for (const t of timers) clearTimeout(t);
       spool.finalize();
       if (isWin4) opts.signal.removeEventListener("abort", onAbort);
-      child.stdout?.off("data", onData);
-      child.stderr?.off("data", onData);
+      child.stdout?.off("data", onStdoutData);
+      child.stderr?.off("data", onStderrData);
       child.stdout?.destroy();
       child.stderr?.destroy();
       if (child.exitCode === null && !child.killed) {
@@ -7500,7 +7618,7 @@ import * as path13 from "node:path";
 import { resolveWstackPaths as resolveWstackPaths2 } from "@wrongstack/core";
 
 // src/codebase-index/schema.ts
-var SCHEMA_VERSION = 2;
+var SCHEMA_VERSION = 3;
 
 // src/codebase-index/lsp-kind.ts
 function lspKindToInternalKind(k) {
@@ -7543,7 +7661,7 @@ function tokenise(text) {
   return sanitised.toLowerCase().split(" ").filter(Boolean);
 }
 function splitName(name) {
-  return name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").trim();
+  return name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([\p{L}])(\d)/gu, "$1 $2").replace(/(\d)([\p{L}])/gu, "$1 $2").replace(/[_-]+/g, " ").trim();
 }
 function buildIndexableText(name, signature, docComment) {
   return [splitName(name), name, signature, docComment].filter(Boolean).join(" ");
@@ -7569,14 +7687,12 @@ function buildBm25Index(docs) {
   return new Bm25Index(documents, df, N, avgLen);
 }
 var Bm25Index = class {
-  constructor(documents, df, N, avgLen) {
+  constructor(documents, _df, N, avgLen) {
     this.documents = documents;
-    this.df = df;
     this.N = N;
     this.safeAvgLen = avgLen === 0 ? 1 : avgLen;
   }
   documents;
-  df;
   N;
   safeAvgLen;
   score(query, filter) {
@@ -7589,10 +7705,13 @@ var Bm25Index = class {
       for (const qTerm of qTokens) {
         let tf = 0;
         for (const t of doc.tokens) {
-          if (t === qTerm) tf++;
+          if (t.startsWith(qTerm)) tf++;
         }
         if (tf === 0) continue;
-        const dfVal = this.df[qTerm] ?? 0;
+        let dfVal = 0;
+        for (const candidate of this.documents) {
+          if (candidate.tokens.some((t) => t.startsWith(qTerm))) dfVal++;
+        }
         if (dfVal === 0) continue;
         const idf = Math.log((this.N - dfVal + 0.5) / (dfVal + 0.5) + 1);
         const lenRatio = B * (doc.len / this.safeAvgLen);
@@ -7625,6 +7744,29 @@ var Bm25Index = class {
 
 // src/codebase-index/writer.ts
 var DB_FILE = "index.db";
+function escapeLike(value) {
+  return value.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+function assignRefsToSymbols(refs, symbols) {
+  if (refs.length === 0 || symbols.length === 0) return [];
+  const ordered = [...symbols].sort((a, b) => a.line - b.line || a.col - b.col || a.id - b.id);
+  const seen = /* @__PURE__ */ new Set();
+  const assigned = [];
+  for (const ref of refs) {
+    let owner2;
+    for (const symbol of ordered) {
+      if (symbol.line > ref.line) break;
+      owner2 = symbol;
+    }
+    if (!owner2 && ref.callType === "import") owner2 = ordered[0];
+    if (!owner2 || owner2.id <= 0) continue;
+    const key = `${owner2.id}:${ref.toName}:${ref.callType}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    assigned.push({ ...ref, fromId: owner2.id });
+  }
+  return assigned;
+}
 function resolveIndexDir(projectRoot, override) {
   return override ?? resolveWstackPaths2({ projectRoot }).projectCodebaseIndex;
 }
@@ -7632,6 +7774,53 @@ function codebaseIndexDirOverride(ctx) {
   const v = ctx.meta?.["codebaseIndexDir"];
   return typeof v === "string" ? v : void 0;
 }
+var StorePool = class {
+  stores = /* @__PURE__ */ new Map();
+  key(projectRoot, indexDir) {
+    return `${projectRoot}\0${indexDir ?? ""}`;
+  }
+  /** Borrow a store. Creates it on first access for this key. */
+  acquire(projectRoot, opts) {
+    const k = this.key(projectRoot, opts?.indexDir);
+    let store = this.stores.get(k);
+    if (!store) {
+      store = new IndexStore(projectRoot, { indexDir: opts?.indexDir });
+      this.stores.set(k, store);
+    }
+    return store;
+  }
+  /** Return the store to the pool. The connection stays warm for subsequent
+   * operations on the same (projectRoot, indexDir). */
+  release(_store) {
+  }
+  /** Close every pooled connection and drain the pool. Call on shutdown. */
+  closeAll() {
+    for (const store of this.stores.values()) {
+      try {
+        store.close();
+      } catch {
+      }
+    }
+    this.stores.clear();
+  }
+  /** Remove one store from the pool. Used by tests that need isolation. */
+  evict(projectRoot, indexDir) {
+    const k = this.key(projectRoot, indexDir);
+    const store = this.stores.get(k);
+    if (store) {
+      try {
+        store.close();
+      } catch {
+      }
+      this.stores.delete(k);
+    }
+  }
+  /** True when the pool holds a connection for the given key. */
+  has(projectRoot, indexDir) {
+    return this.stores.has(this.key(projectRoot, indexDir));
+  }
+};
+var indexStorePool = new StorePool();
 var warningSilenced = false;
 function silenceSqliteExperimentalWarning() {
   if (warningSilenced) return;
@@ -7678,7 +7867,7 @@ function sleepSync(ms) {
   } catch {
   }
 }
-var IndexStore = class {
+var IndexStore = class _IndexStore {
   db;
   /** Absolute path to this project's index directory. */
   indexDir;
@@ -7730,10 +7919,7 @@ var IndexStore = class {
           const msg = lastError instanceof Error ? lastError.message : String(lastError);
           throw new LockError(`SQLite lock conflict after ${MAX_LOCK_RETRIES} retries: ${msg}`);
         }
-        const delay = Math.min(
-          LOCK_RETRY_BASE_DELAY_MS * 2 ** attempt,
-          LOCK_RETRY_MAX_DELAY_MS
-        );
+        const delay = Math.min(LOCK_RETRY_BASE_DELAY_MS * 2 ** attempt, LOCK_RETRY_MAX_DELAY_MS);
         sleepSync(delay);
       }
     }
@@ -7815,8 +8001,24 @@ var IndexStore = class {
     this.db.exec("CREATE INDEX IF NOT EXISTS idx_r_to_name ON refs(to_name)");
     this.db.exec("CREATE INDEX IF NOT EXISTS idx_r_call_type ON refs(call_type)");
     try {
-      this.db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS symbols_fts USING fts5(text, tokenize = 'unicode61')");
+      this.db.exec(
+        "CREATE VIRTUAL TABLE IF NOT EXISTS symbols_fts USING fts5(text, tokenize = 'unicode61')"
+      );
       this.ftsAvailable = true;
+      const symbolCount = Number(
+        this.db.prepare("SELECT COUNT(*) AS n FROM symbols").get()?.n ?? 0
+      );
+      const ftsCount = Number(
+        this.db.prepare("SELECT COUNT(*) AS n FROM symbols_fts").get()?.n ?? 0
+      );
+      if (symbolCount !== ftsCount) {
+        this.db.exec("DELETE FROM symbols_fts");
+        const insert = this.db.prepare("INSERT INTO symbols_fts(rowid, text) VALUES (?, ?)");
+        const rows = this.db.prepare("SELECT id, name, signature, doc_comment FROM symbols ORDER BY id").all();
+        for (const row of rows) {
+          insert.run(row.id, buildIndexableText(row.name, row.signature, row.doc_comment));
+        }
+      }
     } catch {
       this.ftsAvailable = false;
     }
@@ -7836,7 +8038,7 @@ var IndexStore = class {
     return this.runWithRetry(() => {
       this.db.exec("BEGIN IMMEDIATE");
       try {
-        const maxRows = this.db.prepare("SELECT MAX(id) AS m FROM symbols").all();
+        const maxRows = this.stmt("SELECT MAX(id) AS m FROM symbols").all();
         let nextId = (maxRows[0]?.m ?? 0) + 1;
         const stmt = this.db.prepare(
           `INSERT INTO symbols(id, lang, kind, name, file, line, col, signature, doc_comment, scope, text, file_fk)
@@ -7874,7 +8076,9 @@ var IndexStore = class {
   deleteSymbolsForFile(file) {
     this.runWithRetry(() => {
       if (this.ftsAvailable) {
-        this.stmt("DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_fk = ?)").run(file);
+        this.stmt(
+          "DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_fk = ?)"
+        ).run(file);
       }
       this.stmt("DELETE FROM symbols WHERE file_fk = ?").run(file);
     });
@@ -7886,9 +8090,21 @@ var IndexStore = class {
    */
   deleteFile(file) {
     this.runWithRetry(() => {
-      this.deleteRefsForFile(file);
-      this.deleteSymbolsForFile(file);
-      this.stmt("DELETE FROM files WHERE file = ?").run(file);
+      this.db.exec("BEGIN IMMEDIATE");
+      try {
+        if (this.ftsAvailable) {
+          this.db.prepare(
+            "DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_fk = ?)"
+          ).run(file);
+        }
+        this.db.prepare("DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file_fk = ?)").run(file);
+        this.db.prepare("DELETE FROM symbols WHERE file_fk = ?").run(file);
+        this.db.prepare("DELETE FROM files WHERE file = ?").run(file);
+        this.db.exec("COMMIT");
+      } catch (err) {
+        this.db.exec("ROLLBACK");
+        throw err;
+      }
     });
   }
   // ─── File metadata ──────────────────────────────────────────────────────────
@@ -7911,14 +8127,22 @@ var IndexStore = class {
     ).all(file);
     if (!rows.length) return null;
     const r = expectDefined2(rows[0]);
-    return { file: r.file, lang: r.lang, mtimeMs: r.mtime_ms, symbolCount: r.symbol_count, lastIndexed: r.last_indexed };
+    return {
+      file: r.file,
+      lang: r.lang,
+      mtimeMs: r.mtime_ms,
+      symbolCount: r.symbol_count,
+      lastIndexed: r.last_indexed
+    };
   }
   getAllFileMetas() {
-    return this.db.prepare(
-      "SELECT file, lang, mtime_ms, symbol_count, last_indexed FROM files"
-    ).all().map(
-      (r) => ({ file: r.file, lang: r.lang, mtimeMs: r.mtime_ms, symbolCount: r.symbol_count, lastIndexed: r.last_indexed })
-    );
+    return this.db.prepare("SELECT file, lang, mtime_ms, symbol_count, last_indexed FROM files").all().map((r) => ({
+      file: r.file,
+      lang: r.lang,
+      mtimeMs: r.mtime_ms,
+      symbolCount: r.symbol_count,
+      lastIndexed: r.last_indexed
+    }));
   }
   // ─── Search ──────────────────────────────────────────────────────────────────
   search(query, filter) {
@@ -7942,8 +8166,8 @@ var IndexStore = class {
       values.push(filter.lang);
     }
     if (filter?.file) {
-      conditions.push("file LIKE ?");
-      values.push(`%${filter.file}%`);
+      conditions.push("replace(file, '\\', '/') LIKE ? ESCAPE '\\'");
+      values.push(`%${escapeLike(filter.file.replace(/\\/g, "/"))}%`);
     }
     if (query.trim()) {
       const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
@@ -7981,9 +8205,11 @@ var IndexStore = class {
    * "users", camelCase-split text makes "complex" find "complexOperation").
    */
   searchRanked(query, filter, limit) {
+    const rawLimit = Number.isFinite(limit) ? Math.trunc(limit) : 20;
+    const safeLimit = Math.max(1, Math.min(rawLimit, 100));
     const tokens = tokenise(query);
     if (tokens.length === 0 || !this.ftsAvailable) {
-      return this.searchRankedFallback(query, filter, limit);
+      return this.searchRankedFallback(query, filter, safeLimit);
     }
     let effectiveKind = filter?.kind;
     if (filter?.lspKind !== void 0) {
@@ -8003,11 +8229,13 @@ var IndexStore = class {
       values.push(filter.lang);
     }
     if (filter?.file) {
-      conditions.push("s.file LIKE ?");
-      values.push(`%${filter.file}%`);
+      conditions.push("replace(s.file, '\\', '/') LIKE ? ESCAPE '\\'");
+      values.push(`%${escapeLike(filter.file.replace(/\\/g, "/"))}%`);
     }
     const where = conditions.join(" AND ");
-    const countRows = this.db.prepare(`SELECT COUNT(*) AS n FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid WHERE ${where}`).all(...values);
+    const countRows = this.db.prepare(
+      `SELECT COUNT(*) AS n FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid WHERE ${where}`
+    ).all(...values);
     const total = countRows[0] ? Number(countRows[0].n) : 0;
     if (total === 0) return { results: [], total: 0 };
     const rows = this.db.prepare(
@@ -8016,9 +8244,13 @@ var IndexStore = class {
                 snippet(symbols_fts, 0, '', '', '\u2026', 12) AS snippet
          FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid
          WHERE ${where}
-         ORDER BY bm25(symbols_fts)
+         ORDER BY
+           CASE WHEN lower(s.name) = lower(?) THEN 0
+                WHEN lower(s.name) LIKE lower(?) ESCAPE '\\' THEN 1
+                ELSE 2 END,
+           bm25(symbols_fts), lower(s.name), s.file, s.line, s.col, s.id
          LIMIT ?`
-    ).all(...values, limit);
+    ).all(...values, query.trim(), `${escapeLike(query.trim())}%`, safeLimit);
     return {
       results: rows.map((r) => ({
         id: r.id,
@@ -8048,10 +8280,28 @@ var IndexStore = class {
     }
     const candidateById = new Map(candidates.map((c) => [c.id, c]));
     const bm25 = buildBm25Index(
-      candidates.map((c) => ({ id: c.id, text: buildIndexableText(c.name, c.signature, c.docComment) }))
+      candidates.map((c) => ({
+        id: c.id,
+        text: buildIndexableText(c.name, c.signature, c.docComment)
+      }))
     );
     const scored = bm25.score(query, (id) => candidateById.has(id));
-    scored.sort((a, b) => b.score - a.score);
+    const q = query.trim().toLowerCase();
+    const rank = (id) => {
+      const name = candidateById.get(id)?.name.toLowerCase() ?? "";
+      if (name === q) return 0;
+      if (name.startsWith(q)) return 1;
+      return 2;
+    };
+    scored.sort((a, b) => {
+      const rankDiff = rank(a.id) - rank(b.id);
+      if (rankDiff !== 0) return rankDiff;
+      const scoreDiff = b.score - a.score;
+      if (scoreDiff !== 0) return scoreDiff;
+      const left = expectDefined2(candidateById.get(a.id));
+      const right = expectDefined2(candidateById.get(b.id));
+      return left.name.localeCompare(right.name) || left.file.localeCompare(right.file) || left.line - right.line || left.col - right.col || left.id - right.id;
+    });
     const qTokens = tokenise(query);
     const results = scored.slice(0, limit).map(({ id, score }) => {
       const c = expectDefined2(candidateById.get(id));
@@ -8060,9 +8310,7 @@ var IndexStore = class {
     return { results, total: candidates.length };
   }
   getAllIndexable() {
-    return this.db.prepare("SELECT id, text FROM symbols").all().map(
-      ({ id, text }) => ({ id, text })
-    );
+    return this.stmt("SELECT id, text FROM symbols").all().map(({ id, text }) => ({ id, text }));
   }
   /**
    * Largest symbol id currently in the table (0 when empty). New ids must be
@@ -8072,28 +8320,22 @@ var IndexStore = class {
    * `symbols.id`). Ids may have gaps — that is fine.
    */
   getMaxSymbolId() {
-    const rows = this.db.prepare("SELECT MAX(id) AS m FROM symbols").all();
+    const rows = this.stmt("SELECT MAX(id) AS m FROM symbols").all();
     return rows[0]?.m ?? 0;
   }
   // ─── Stats ───────────────────────────────────────────────────────────────────
   getStats() {
     const sizeBytes = this.sizeBytes();
-    const lastRows = this.db.prepare(
-      "SELECT value FROM metadata WHERE key = 'last_indexed'"
-    ).all();
+    const lastRows = this.db.prepare("SELECT value FROM metadata WHERE key = 'last_indexed'").all();
     const lastIndexed = lastRows.length ? Number(lastRows[0]?.value) : null;
-    const totalRows = this.db.prepare("SELECT COUNT(*) FROM symbols").all();
+    const totalRows = this.stmt("SELECT COUNT(*) FROM symbols").all();
     const totalSymbols = totalRows[0] ? Number(totalRows[0]["COUNT(*)"]) : 0;
-    const fileRows = this.db.prepare("SELECT COUNT(*) FROM files").all();
+    const fileRows = this.stmt("SELECT COUNT(*) FROM files").all();
     const totalFiles = fileRows[0] ? Number(fileRows[0]["COUNT(*)"]) : 0;
-    const langRows = this.db.prepare(
-      "SELECT lang, COUNT(*) FROM symbols GROUP BY lang"
-    ).all();
+    const langRows = this.stmt("SELECT lang, COUNT(*) FROM symbols GROUP BY lang").all();
     const byLang = {};
     for (const row of langRows) byLang[row.lang] = Number(row["COUNT(*)"]);
-    const kindRows = this.db.prepare(
-      "SELECT kind, COUNT(*) FROM symbols GROUP BY kind"
-    ).all();
+    const kindRows = this.stmt("SELECT kind, COUNT(*) FROM symbols GROUP BY kind").all();
     const byKind = {};
     for (const row of kindRows) byKind[row.kind] = Number(row["COUNT(*)"]);
     return {
@@ -8109,17 +8351,34 @@ var IndexStore = class {
   }
   setLastIndexed(ts2) {
     this.runWithRetry(() => {
-      this.db.prepare(
-        "INSERT OR REPLACE INTO metadata(key, value) VALUES('last_indexed', ?)"
-      ).run(String(ts2));
+      this.db.prepare("INSERT OR REPLACE INTO metadata(key, value) VALUES('last_indexed', ?)").run(String(ts2));
+    });
+  }
+  getMetadata(key) {
+    const rows = this.db.prepare("SELECT value FROM metadata WHERE key = ?").all(key);
+    return rows[0]?.value;
+  }
+  setMetadata(key, value) {
+    this.runWithRetry(() => {
+      this.db.prepare("INSERT OR REPLACE INTO metadata(key, value) VALUES(?, ?)").run(key, value);
     });
   }
   clearAll() {
     this.runWithRetry(() => {
-      this.db.exec("DELETE FROM symbols");
-      this.db.exec("DELETE FROM files");
-      this.db.exec("DELETE FROM refs");
-      if (this.ftsAvailable) this.db.exec("DELETE FROM symbols_fts");
+      this.db.exec("BEGIN IMMEDIATE");
+      try {
+        this.db.exec("DROP TABLE IF EXISTS refs");
+        this.db.exec("DROP TABLE IF EXISTS symbols");
+        this.db.exec("DROP TABLE IF EXISTS files");
+        this.db.exec("DROP TABLE IF EXISTS metadata");
+        if (this.ftsAvailable) this.db.exec("DROP TABLE IF EXISTS symbols_fts");
+        this.db.exec("COMMIT");
+        this.stmtCache.clear();
+        this.initSchema();
+      } catch (err) {
+        this.db.exec("ROLLBACK");
+        throw err;
+      }
     });
   }
   // ─── Ref CRUD ────────────────────────────────────────────────────────────────
@@ -8200,7 +8459,7 @@ var IndexStore = class {
           ).run(...options.deleteForFiles);
           this.db.prepare(`DELETE FROM symbols WHERE file IN (${placeholders})`).run(...options.deleteForFiles);
         }
-        const maxRows = this.db.prepare("SELECT MAX(id) AS m FROM symbols").all();
+        const maxRows = this.stmt("SELECT MAX(id) AS m FROM symbols").all();
         let nextId = (maxRows[0]?.m ?? 0) + 1;
         const symStmt = this.db.prepare(
           `INSERT INTO symbols(id, lang, kind, name, file, line, col, signature, doc_comment, scope, text, file_fk)
@@ -8210,6 +8469,7 @@ var IndexStore = class {
         const allInserted = [];
         const refsToInsert = [];
         for (const entry of entries) {
+          const insertedForEntry = [];
           for (const s of entry.symbols) {
             const id = nextId++;
             symStmt.run(
@@ -8227,9 +8487,11 @@ var IndexStore = class {
               s.file
             );
             ftsStmt?.run(id, buildIndexableText(s.name, s.signature, s.docComment));
-            allInserted.push({ ...s, id });
+            const inserted = { ...s, id };
+            allInserted.push(inserted);
+            insertedForEntry.push(inserted);
           }
-          for (const r of entry.refs) refsToInsert.push(r);
+          refsToInsert.push(...assignRefsToSymbols(entry.refs, insertedForEntry));
         }
         if (refsToInsert.length > 0) {
           const refStmt = this.db.prepare(
@@ -8267,9 +8529,7 @@ var IndexStore = class {
    */
   deleteRefsForFile(file) {
     this.runWithRetry(() => {
-      this.db.prepare(
-        "DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file = ?)"
-      ).run(file);
+      this.db.prepare("DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file = ?)").run(file);
     });
   }
   /**
@@ -8310,9 +8570,7 @@ var IndexStore = class {
    * Find all references FROM a given symbol (what does this symbol call/use?).
    */
   findRefsFrom(symbolId) {
-    return this.db.prepare(
-      "SELECT id, from_id, to_name, to_id, call_type, line FROM refs WHERE from_id = ?"
-    ).all(symbolId).map((r) => ({
+    return this.db.prepare("SELECT id, from_id, to_name, to_id, call_type, line FROM refs WHERE from_id = ?").all(symbolId).map((r) => ({
       id: r.id,
       fromId: r.from_id,
       toName: r.to_name,
@@ -8329,6 +8587,356 @@ var IndexStore = class {
       return 0;
     }
   }
+  // ─── CodeMap graph aggregation ──────────────────────────────────────────────
+  /**
+   * Derive a monorepo package name from an absolute file path.
+   * Handles both `packages/<name>/...` (workspace) and `src/<name>/...` layouts.
+   * Returns `undefined` for files outside any recognisable package structure.
+   */
+  static derivePackage(filePath) {
+    const f = filePath.replace(/\\/g, "/");
+    const pkgsIdx = f.indexOf("/packages/");
+    if (pkgsIdx !== -1) {
+      const rest = f.slice(pkgsIdx + "/packages/".length);
+      const seg = rest.split("/")[0];
+      return seg ? `@wrongstack/${seg}` : void 0;
+    }
+    const appsIdx = f.indexOf("/apps/");
+    if (appsIdx !== -1) {
+      const rest = f.slice(appsIdx + "/apps/".length);
+      const seg = rest.split("/")[0];
+      return seg ? `app:${seg}` : void 0;
+    }
+    return void 0;
+  }
+  static packageFromImport(moduleName) {
+    if (!moduleName.startsWith("@wrongstack/")) return void 0;
+    const parts = moduleName.split("/");
+    return parts[1] ? `@wrongstack/${parts[1]}` : void 0;
+  }
+  static resolveRelativeImport(fromFile, moduleName, indexedFiles) {
+    if (!moduleName.startsWith(".")) return void 0;
+    const normalizedFrom = fromFile.replace(/\\/g, "/");
+    const absolute = path13.posix.normalize(
+      path13.posix.join(path13.posix.dirname(normalizedFrom), moduleName)
+    );
+    const extension = path13.posix.extname(absolute);
+    const base = extension ? absolute.slice(0, -extension.length) : absolute;
+    const candidates = [
+      absolute,
+      ...[".ts", ".tsx", ".js", ".jsx", ".mts", ".cts"].map((ext) => `${base}${ext}`),
+      ...[".ts", ".tsx", ".js", ".jsx"].map((ext) => path13.posix.join(absolute, `index${ext}`)),
+      ...[".ts", ".tsx", ".js", ".jsx"].map((ext) => path13.posix.join(base, `index${ext}`))
+    ];
+    const indexedByPortablePath = new Map(
+      [...indexedFiles].map((file) => [file.replace(/\\/g, "/").toLocaleLowerCase(), file])
+    );
+    for (const candidate of candidates) {
+      const indexed = indexedByPortablePath.get(candidate.toLocaleLowerCase());
+      if (indexed) return indexed;
+    }
+    return void 0;
+  }
+  /**
+   * Package-level graph: each workspace package is a node; edges are derived
+   * from cross-package symbol references (a symbol in package A references a
+   * symbol resolved in package B). Node metadata includes symbol/file counts.
+   */
+  getPackageGraph() {
+    const symbols = this.db.prepare("SELECT file, id FROM symbols ORDER BY id").all();
+    const pkgNodes = /* @__PURE__ */ new Map();
+    const fileToPkg = /* @__PURE__ */ new Map();
+    const symbolToPkg = /* @__PURE__ */ new Map();
+    for (const s of symbols) {
+      const pkg = _IndexStore.derivePackage(s.file) ?? "(root)";
+      fileToPkg.set(s.file, pkg);
+      symbolToPkg.set(s.id, pkg);
+      const node = pkgNodes.get(pkg);
+      if (node) {
+        node.symbolCount = (node.symbolCount ?? 0) + 1;
+      } else {
+        pkgNodes.set(pkg, {
+          id: `pkg:${pkg}`,
+          label: pkg,
+          kind: "package",
+          package: pkg,
+          symbolCount: 1,
+          fileCount: 0
+        });
+      }
+    }
+    const files = this.db.prepare("SELECT DISTINCT file FROM files").all();
+    for (const { file } of files) {
+      const pkg = _IndexStore.derivePackage(file) ?? "(root)";
+      const node = pkgNodes.get(pkg);
+      if (node) node.fileCount = (node.fileCount ?? 0) + 1;
+    }
+    const refRows = this.db.prepare(
+      `SELECT r.from_id, r.to_id, r.call_type
+       FROM refs r
+       WHERE r.to_id IS NOT NULL`
+    ).all();
+    const edgeMap = /* @__PURE__ */ new Map();
+    for (const r of refRows) {
+      if (r.call_type === "import") continue;
+      const fromPkg = symbolToPkg.get(r.from_id);
+      const toPkg = symbolToPkg.get(r.to_id);
+      if (!fromPkg || !toPkg || fromPkg === toPkg) continue;
+      const key = `${fromPkg}\0${toPkg}`;
+      let e = edgeMap.get(key);
+      if (!e) {
+        e = { weight: 0, types: /* @__PURE__ */ new Map() };
+        edgeMap.set(key, e);
+      }
+      e.weight++;
+      e.types.set(r.call_type, (e.types.get(r.call_type) ?? 0) + 1);
+    }
+    const importRows = this.db.prepare(
+      `SELECT r.from_id, r.to_name
+       FROM refs r
+       WHERE r.call_type = 'import'`
+    ).all();
+    for (const r of importRows) {
+      const fromPkg = symbolToPkg.get(r.from_id);
+      const toPkg = _IndexStore.packageFromImport(r.to_name);
+      if (!fromPkg || !toPkg || fromPkg === toPkg || !pkgNodes.has(toPkg)) continue;
+      const key = `${fromPkg}\0${toPkg}`;
+      let edge = edgeMap.get(key);
+      if (!edge) {
+        edge = { weight: 0, types: /* @__PURE__ */ new Map() };
+        edgeMap.set(key, edge);
+      }
+      edge.weight++;
+      edge.types.set("import", (edge.types.get("import") ?? 0) + 1);
+    }
+    const edges = [];
+    for (const [key, e] of edgeMap) {
+      const [source, target] = key.split("\0");
+      let bestType = "call";
+      let bestCount = 0;
+      for (const [t, c] of e.types) {
+        if (c > bestCount) {
+          bestType = t;
+          bestCount = c;
+        }
+      }
+      edges.push({
+        source: `pkg:${source}`,
+        target: `pkg:${target}`,
+        weight: e.weight,
+        refType: bestType
+      });
+    }
+    return { nodes: [...pkgNodes.values()], edges };
+  }
+  /**
+   * File-level graph for a single package: each file is a node; edges are
+   * derived from cross-file symbol references within the package.
+   */
+  getFileGraph(packageFilter) {
+    const allFiles = this.db.prepare("SELECT DISTINCT file FROM symbols").all();
+    const pkgFilePaths = allFiles.filter((f) => (_IndexStore.derivePackage(f.file) ?? "(root)") === packageFilter).map((f) => f.file);
+    const localFiles = new Set(pkgFilePaths);
+    if (localFiles.size === 0) return { nodes: [], edges: [] };
+    const filePlaceholders = [...localFiles].map(() => "?").join(",");
+    const pkgSyms = this.db.prepare(
+      `SELECT file, id, name, kind, lang, line FROM symbols WHERE file IN (${filePlaceholders}) ORDER BY id`
+    ).all(...pkgFilePaths);
+    const fileNodes = /* @__PURE__ */ new Map();
+    const symToFile = /* @__PURE__ */ new Map();
+    const fileStats = /* @__PURE__ */ new Map();
+    for (const s of pkgSyms) {
+      symToFile.set(s.id, s.file);
+      const current = fileStats.get(s.file);
+      fileStats.set(s.file, {
+        count: (current?.count ?? 0) + 1,
+        lang: current?.lang ?? s.lang
+      });
+    }
+    const ensureFileNode = (file) => {
+      if (fileNodes.has(file)) return;
+      const stats = fileStats.get(file);
+      fileNodes.set(file, {
+        id: `file:${file}`,
+        label: file.replace(/\\/g, "/").split("/").pop() ?? file,
+        kind: "file",
+        package: _IndexStore.derivePackage(file) ?? "(root)",
+        file,
+        symbolCount: stats?.count ?? 0,
+        lang: stats?.lang,
+        external: !localFiles.has(file)
+      });
+    };
+    for (const file of localFiles) {
+      ensureFileNode(file);
+    }
+    const indexedFiles = new Set(allFiles.map((f) => f.file));
+    const refRows = this.db.prepare(
+      `SELECT r.from_id, r.to_id, r.call_type
+       FROM refs r
+       WHERE (r.from_id IN (SELECT id FROM symbols WHERE file IN (${filePlaceholders}))
+           OR r.to_id IN (SELECT id FROM symbols WHERE file IN (${filePlaceholders})))
+         AND r.to_id IS NOT NULL`
+    ).all(...pkgFilePaths, ...pkgFilePaths);
+    const knownSymIds = new Set(pkgSyms.map((s) => s.id));
+    const crossRefIds = /* @__PURE__ */ new Set();
+    for (const r of refRows) {
+      if (!knownSymIds.has(r.from_id)) crossRefIds.add(r.from_id);
+      if (!knownSymIds.has(r.to_id)) crossRefIds.add(r.to_id);
+    }
+    if (crossRefIds.size > 0) {
+      const crossPlaceholders = [...crossRefIds].map(() => "?").join(",");
+      const extras = this.db.prepare(
+        `SELECT id, file FROM symbols WHERE id IN (${crossPlaceholders})`
+      ).all(...crossRefIds);
+      for (const x of extras) {
+        symToFile.set(x.id, x.file);
+        if (!fileStats.has(x.file)) {
+          fileStats.set(x.file, { count: 0, lang: "ts" });
+        }
+      }
+    }
+    const edgeMap = /* @__PURE__ */ new Map();
+    for (const r of refRows) {
+      if (r.call_type === "import") continue;
+      const fromFile = symToFile.get(r.from_id);
+      const toFile = symToFile.get(r.to_id);
+      if (!fromFile || !toFile || fromFile === toFile) continue;
+      if (!localFiles.has(fromFile) && !localFiles.has(toFile)) continue;
+      ensureFileNode(fromFile);
+      ensureFileNode(toFile);
+      const key = `${fromFile}\0${toFile}`;
+      let e = edgeMap.get(key);
+      if (!e) {
+        e = { weight: 0, types: /* @__PURE__ */ new Map() };
+        edgeMap.set(key, e);
+      }
+      e.weight++;
+      e.types.set(r.call_type, (e.types.get(r.call_type) ?? 0) + 1);
+    }
+    const importRows = this.db.prepare(
+      `SELECT r.from_id, r.to_name
+       FROM refs r
+       WHERE r.call_type = 'import'
+         AND r.from_id IN (SELECT id FROM symbols WHERE file IN (${filePlaceholders}))`
+    ).all(...pkgFilePaths);
+    for (const r of importRows) {
+      const fromFile = symToFile.get(r.from_id);
+      if (!fromFile || !localFiles.has(fromFile)) continue;
+      const toFile = _IndexStore.resolveRelativeImport(fromFile, r.to_name, indexedFiles);
+      if (!toFile || fromFile === toFile) continue;
+      ensureFileNode(fromFile);
+      ensureFileNode(toFile);
+      const key = `${fromFile}\0${toFile}`;
+      let edge = edgeMap.get(key);
+      if (!edge) {
+        edge = { weight: 0, types: /* @__PURE__ */ new Map() };
+        edgeMap.set(key, edge);
+      }
+      edge.weight++;
+      edge.types.set("import", (edge.types.get("import") ?? 0) + 1);
+    }
+    const edges = [];
+    for (const [key, e] of edgeMap) {
+      const [source, target] = key.split("\0");
+      let bestType = "call";
+      let bestCount = 0;
+      for (const [t, c] of e.types) {
+        if (c > bestCount) {
+          bestType = t;
+          bestCount = c;
+        }
+      }
+      edges.push({
+        source: `file:${source}`,
+        target: `file:${target}`,
+        weight: e.weight,
+        refType: bestType
+      });
+    }
+    return { nodes: [...fileNodes.values()], edges };
+  }
+  /**
+   * Symbol-level graph for a single file: each symbol is a node; edges are
+   * derived from intra-file and cross-file symbol references (who calls whom).
+   */
+  getSymbolGraph(fileFilter) {
+    const syms = this.db.prepare(
+      "SELECT id, name, kind, lang, file, line, signature, scope FROM symbols WHERE file = ? ORDER BY line, id"
+    ).all(fileFilter);
+    if (syms.length === 0) return { nodes: [], edges: [] };
+    const symById = new Map(syms.map((symbol) => [symbol.id, symbol]));
+    const relatedIds = new Set(syms.map((symbol) => symbol.id));
+    const toGraphNode = (s) => ({
+      id: `sym:${s.id}`,
+      label: s.name,
+      kind: "symbol",
+      symbolId: s.id,
+      symbolKind: s.kind,
+      file: s.file,
+      package: _IndexStore.derivePackage(s.file) ?? "(root)",
+      lang: s.lang,
+      line: s.line,
+      signature: s.signature,
+      scope: s.scope,
+      external: s.file !== fileFilter
+    });
+    const symIds = new Set(syms.map((s) => s.id));
+    const refRows = this.db.prepare(
+      `SELECT r.from_id, r.to_id, r.to_name, r.call_type, r.line
+       FROM refs r
+       WHERE r.from_id IN (SELECT id FROM symbols WHERE file = ?)
+          OR r.to_id IN (SELECT id FROM symbols WHERE file = ?)`
+    ).all(fileFilter, fileFilter);
+    const edgeMap = /* @__PURE__ */ new Map();
+    for (const r of refRows) {
+      if (r.to_id === null) continue;
+      if (!symIds.has(r.from_id) && !symIds.has(r.to_id)) continue;
+      relatedIds.add(r.from_id);
+      relatedIds.add(r.to_id);
+      const key = `${r.from_id}\0${r.to_id}`;
+      let e = edgeMap.get(key);
+      if (!e) {
+        e = { weight: 0, types: /* @__PURE__ */ new Map() };
+        edgeMap.set(key, e);
+      }
+      e.weight++;
+      e.types.set(r.call_type, (e.types.get(r.call_type) ?? 0) + 1);
+    }
+    const edges = [];
+    for (const [key, e] of edgeMap) {
+      const [fromId, toId] = key.split("\0").map(Number);
+      let bestType = "call";
+      let bestCount = 0;
+      for (const [t, c] of e.types) {
+        if (c > bestCount) {
+          bestType = t;
+          bestCount = c;
+        }
+      }
+      edges.push({
+        source: `sym:${fromId}`,
+        target: `sym:${toId}`,
+        weight: e.weight,
+        refType: bestType
+      });
+    }
+    const loadedIds = new Set(syms.map((s) => s.id));
+    const missingIds = [...relatedIds].filter((id) => !loadedIds.has(id));
+    if (missingIds.length > 0) {
+      const placeholders = missingIds.map(() => "?").join(",");
+      const extras = this.db.prepare(
+        `SELECT id, name, kind, lang, file, line, signature, scope FROM symbols WHERE id IN (${placeholders})`
+      ).all(...missingIds);
+      for (const s of extras) symById.set(s.id, s);
+    }
+    const nodes = [...relatedIds].map((id) => symById.get(id)).filter((symbol) => symbol !== void 0).sort((a, b) => {
+      const aExternal = a.file === fileFilter ? 0 : 1;
+      const bExternal = b.file === fileFilter ? 0 : 1;
+      return aExternal - bExternal || a.file.localeCompare(b.file) || a.line - b.line || a.id - b.id;
+    }).map(toGraphNode);
+    return { nodes, edges };
+  }
   close() {
     this.stmtCache.clear();
     try {
@@ -8347,6 +8955,7 @@ import { Worker } from "node:worker_threads";
 import { expectDefined as expectDefined6 } from "@wrongstack/core";
 import * as fs14 from "node:fs/promises";
 import * as path19 from "node:path";
+import { availableParallelism } from "node:os";
 import { compileGlob as compileGlob2 } from "@wrongstack/core";
 
 // src/codebase-index/ts-parser.ts
@@ -8403,8 +9012,7 @@ function extToLang(ext) {
       return null;
   }
 }
-function getSignature(node, sourceFile) {
-  const printer = ts.createPrinter({});
+function getSignature(printer, node, sourceFile) {
   const raw = printer.printNode(ts.EmitHint.Unspecified, node, sourceFile);
   return raw.replace(/\s+/g, " ").slice(0, 500);
 }
@@ -8423,20 +9031,14 @@ function getJsDoc(node, sourceFile) {
   }
   return "";
 }
-function buildScope(node) {
-  const parts = [];
-  let current = node.parent;
-  while (current) {
-    if (ts.isClassDeclaration(current) || ts.isInterfaceDeclaration(current) || ts.isEnumDeclaration(current) || ts.isTypeAliasDeclaration(current)) {
-      parts.unshift(current.name?.text ?? "Anon");
-    } else if (ts.isMethodDeclaration(current) || ts.isGetAccessor(current) || ts.isSetAccessor(current) || ts.isPropertyDeclaration(current) || ts.isFunctionDeclaration(current)) {
-      if (current.name && ts.isIdentifier(current.name)) {
-        parts.unshift(current.name.text);
-      }
+function pushScopeName(node, parts) {
+  if (ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isEnumDeclaration(node) || ts.isTypeAliasDeclaration(node)) {
+    parts.push(node.name?.text ?? "Anon");
+  } else if (ts.isMethodDeclaration(node) || ts.isGetAccessor(node) || ts.isSetAccessor(node) || ts.isPropertyDeclaration(node) || ts.isFunctionDeclaration(node)) {
+    if (node.name && ts.isIdentifier(node.name)) {
+      parts.push(node.name.text);
     }
-    current = current.parent;
   }
-  return parts.join(".");
 }
 function parseSymbols(opts) {
   const { file, content, lang } = opts;
@@ -8447,41 +9049,39 @@ function parseSymbols(opts) {
     return { file, lang, symbols: [], mtimeMs: Date.now() };
   }
   const symbols = [];
-  function visit(node) {
+  const refs = [];
+  const printer = ts.createPrinter({});
+  function visit(node, funcDepth, scopeParts) {
     const kind = kindOf(node);
     if (kind) {
-      const nameNode = node.name;
-      if (!nameNode || !ts.isIdentifier(nameNode)) return;
-      const name = nameNode.text;
-      const pos = nameNode.getStart(sourceFile);
-      const { line, character } = sourceFile.getLineAndCharacterOfPosition(pos);
-      const scope = buildScope(node);
-      const signature = getSignature(node, sourceFile);
-      const docComment = getJsDoc(node, sourceFile);
-      const text = [name, signature, docComment].filter(Boolean).join(" | ");
-      symbols.push({
-        id: 0,
-        lang,
-        kind,
-        name,
-        file,
-        line: line + 1,
-        col: character,
-        signature,
-        docComment,
-        scope,
-        text
-      });
+      if ((kind === "const" || kind === "let" || kind === "var" || kind === "parameter") && funcDepth > 0) {
+      } else {
+        const nameNode = node.name;
+        if (!nameNode || !ts.isIdentifier(nameNode)) {
+          return;
+        }
+        const name = nameNode.text;
+        const pos2 = nameNode.getStart(sourceFile);
+        const { line: line2, character } = sourceFile.getLineAndCharacterOfPosition(pos2);
+        const scope = scopeParts.join(".");
+        const signature = getSignature(printer, node, sourceFile);
+        const docComment = getJsDoc(node, sourceFile);
+        const text = [name, signature, docComment].filter(Boolean).join(" | ");
+        symbols.push({
+          id: 0,
+          lang,
+          kind,
+          name,
+          file,
+          line: line2 + 1,
+          col: character,
+          signature,
+          docComment,
+          scope,
+          text
+        });
+      }
     }
-    ts.forEachChild(node, visit);
-  }
-  visit(sourceFile);
-  const refs = extractRefs(sourceFile);
-  return { file, lang, symbols, refs, mtimeMs: Date.now() };
-}
-function extractRefs(sourceFile) {
-  const refs = [];
-  function visit(node) {
     const pos = node.getStart(sourceFile);
     const { line } = sourceFile.getLineAndCharacterOfPosition(pos);
     const lineNum = line + 1;
@@ -8506,10 +9106,14 @@ function extractRefs(sourceFile) {
       const moduleName = getModuleName(node);
       if (moduleName) refs.push({ fromId: 0, toName: moduleName, callType: "import", line: lineNum });
     }
-    ts.forEachChild(node, visit);
+    const scopeIdx = scopeParts.length;
+    pushScopeName(node, scopeParts);
+    const childFuncDepth = ts.isFunctionLike(node) ? funcDepth + 1 : funcDepth;
+    ts.forEachChild(node, (child) => visit(child, childFuncDepth, scopeParts));
+    scopeParts.length = scopeIdx;
   }
-  visit(sourceFile);
-  return deduplicateRefs(refs);
+  visit(sourceFile, 0, []);
+  return { file, lang, symbols, refs: deduplicateRefs(refs), mtimeMs: Date.now() };
 }
 function getTypeName(name) {
   if (ts.isIdentifier(name)) return name.text;
@@ -9394,9 +9998,9 @@ function parseSymbols5(opts) {
 function regexParse2(opts) {
   const { file, content, lang } = opts;
   const symbols = [];
-  const basename8 = path17.basename(file).toLowerCase();
-  const isPackageJson = basename8 === "package.json";
-  const isTsconfig = basename8 === "tsconfig.json" || basename8 === "tsconfig.build.json";
+  const basename9 = path17.basename(file).toLowerCase();
+  const isPackageJson = basename9 === "package.json";
+  const isTsconfig = basename9 === "tsconfig.json" || basename9 === "tsconfig.build.json";
   const isJsonSchema = content.includes("$schema") || content.includes("$id") || content.includes("$ref");
   const isOpenApi = content.includes("openapi") || content.includes("swagger");
   const lines = content.split("\n");
@@ -9791,16 +10395,14 @@ async function loadGitignoreMatcher(projectRoot) {
 
 // src/codebase-index/indexer.ts
 var YIELD_EVERY_N = 50;
-var PARALLEL_BATCH = 20;
+var PARALLEL_BATCH = Math.min(availableParallelism() * 4, 40);
 function yieldEventLoop() {
   return new Promise((resolve14) => setImmediate(resolve14));
 }
 function throwIfAborted(signal) {
   if (!signal?.aborted) return;
   if (signal.reason instanceof Error) throw signal.reason;
-  throw new Error(
-    typeof signal.reason === "string" ? signal.reason : "Indexing cancelled"
-  );
+  throw new Error(typeof signal.reason === "string" ? signal.reason : "Indexing cancelled");
 }
 function isAbortError(err) {
   return err instanceof DOMException && err.name === "AbortError";
@@ -9816,8 +10418,20 @@ var DEFAULT_IGNORE = [
   "__snapshots__",
   ".nyc_output"
 ];
+var DEFAULT_IGNORE_FILES = /* @__PURE__ */ new Set(["package-lock.json", "pnpm-lock.yaml", "pnpm-lock.yml"]);
+var MAX_INDEX_FILE_BYTES = 5 * 1024 * 1024;
+function isWithinProject(projectRoot, file) {
+  const rel = path19.relative(projectRoot, file);
+  return rel !== "" && !rel.startsWith(`..${path19.sep}`) && rel !== ".." && !path19.isAbsolute(rel);
+}
+function isMissingPathError(err) {
+  const code = err?.code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
 async function findSourceFiles(projectRoot, ignore, isGitIgnored, signal) {
   const results = [];
+  const errors = [];
+  let complete = true;
   const ignoreSet = /* @__PURE__ */ new Set([...DEFAULT_IGNORE, ...ignore]);
   const globs = [
     { ext: ".ts", pat: compileGlob2("**/*.ts") },
@@ -9841,7 +10455,9 @@ async function findSourceFiles(projectRoot, ignore, isGitIgnored, signal) {
     let entries;
     try {
       entries = await fs14.readdir(dir, { withFileTypes: true });
-    } catch {
+    } catch (err) {
+      complete = false;
+      errors.push(`scan error: ${dir}: ${err instanceof Error ? err.message : String(err)}`);
       return;
     }
     dirCount++;
@@ -9853,8 +10469,8 @@ async function findSourceFiles(projectRoot, ignore, isGitIgnored, signal) {
         if (isGitIgnored(rel, true)) continue;
         await walk(full);
       } else if (e.isFile()) {
-        if (isGitIgnored(rel, false)) continue;
-        const ext = path19.extname(e.name);
+        if (DEFAULT_IGNORE_FILES.has(e.name) || isGitIgnored(rel, false)) continue;
+        const ext = path19.extname(e.name).toLowerCase();
         for (const { ext: extName, pat } of globs) {
           if (ext === extName && (pat.test(rel) || pat.test(e.name))) {
             results.push(full);
@@ -9865,7 +10481,7 @@ async function findSourceFiles(projectRoot, ignore, isGitIgnored, signal) {
     }
   };
   await walk(projectRoot);
-  return results;
+  return { files: results, complete, errors };
 }
 async function parseFile(file, content, lang) {
   switch (lang) {
@@ -9888,6 +10504,26 @@ async function parseFile(file, content, lang) {
       return { file, lang, symbols: [], mtimeMs: Date.now() };
   }
 }
+function assignRefsToSymbols2(refs, symbols) {
+  if (refs.length === 0 || symbols.length === 0) return [];
+  const ordered = [...symbols].sort((a, b) => a.line - b.line || a.col - b.col || a.id - b.id);
+  const seen = /* @__PURE__ */ new Set();
+  const assigned = [];
+  for (const ref of refs) {
+    let owner2;
+    for (const symbol of ordered) {
+      if (symbol.line > ref.line) break;
+      owner2 = symbol;
+    }
+    if (!owner2 && ref.callType === "import") owner2 = ordered[0];
+    if (!owner2 || owner2.id <= 0) continue;
+    const key = `${owner2.id}:${ref.toName}:${ref.callType}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    assigned.push({ ...ref, fromId: owner2.id });
+  }
+  return assigned;
+}
 async function runIndexer(_ctx, opts) {
   const store = new IndexStore(opts.projectRoot, { indexDir: opts.indexDir });
   try {
@@ -9900,7 +10536,9 @@ async function runIndexer(_ctx, opts) {
   }
 }
 async function runIndexerWithStore(store, opts) {
-  const { projectRoot, force = false, langs, ignore = [], signal } = opts;
+  const { projectRoot, langs, ignore = [], signal } = opts;
+  const relationGraphVersion = "2";
+  const force = (opts.force ?? false) || store.getMetadata("relation_graph_version") !== relationGraphVersion;
   const startMs = Date.now();
   const errors = [];
   const langStats = {};
@@ -9909,10 +10547,18 @@ async function runIndexerWithStore(store, opts) {
   const isGitIgnored = await loadGitignoreMatcher(projectRoot);
   let files;
   let discoveredFiles = null;
+  let discoveryComplete = true;
   if (opts.files && opts.files.length > 0) {
-    files = opts.files.map((f) => path19.resolve(projectRoot, f)).filter((f) => !isGitIgnored(path19.relative(projectRoot, f).replace(/\\/g, "/"), false));
+    files = opts.files.map((f) => path19.resolve(projectRoot, f)).filter((f) => {
+      if (!isWithinProject(projectRoot, f)) return false;
+      const rel = path19.relative(projectRoot, f).replace(/\\/g, "/");
+      return !rel.split("/").some((seg) => DEFAULT_IGNORE.includes(seg)) && !DEFAULT_IGNORE_FILES.has(path19.basename(f)) && !isGitIgnored(rel, false);
+    });
   } else {
-    files = await findSourceFiles(projectRoot, ignore, isGitIgnored, signal);
+    const discovery = await findSourceFiles(projectRoot, ignore, isGitIgnored, signal);
+    files = discovery.files;
+    errors.push(...discovery.errors);
+    discoveryComplete = discovery.complete;
     discoveredFiles = new Set(files);
   }
   if (langs && langs.length > 0) {
@@ -9927,46 +10573,79 @@ async function runIndexerWithStore(store, opts) {
   if (!force) {
     for (const meta of store.getAllFileMetas()) existingMeta.set(meta.file, meta);
   }
+  let filesSinceLastYield = 0;
   for (let batchStart = 0; batchStart < files.length; batchStart += PARALLEL_BATCH) {
     const batchEnd = Math.min(batchStart + PARALLEL_BATCH, files.length);
     const batchFiles = files.slice(batchStart, batchEnd);
     opts.onProgress?.(batchEnd, files.length);
-    if (batchStart > 0 && batchStart % YIELD_EVERY_N === 0) {
+    filesSinceLastYield += batchFiles.length;
+    if (filesSinceLastYield >= YIELD_EVERY_N) {
+      filesSinceLastYield = 0;
       await yieldEventLoop();
       throwIfAborted(signal);
     }
     const statOpts = signal ? { signal } : {};
     const statReadParse = await Promise.allSettled(
-      batchFiles.map(async (file) => {
-        let stat17;
-        try {
-          stat17 = await fs14.stat(file, statOpts);
-        } catch (e) {
-          if (isAbortError(e)) throw e;
-          return { file, stat: null, lang: "", parsed: null, error: `stat error: ${e instanceof Error ? e.message : String(e)}` };
-        }
-        if (!stat17.isFile()) return { file, stat: stat17, lang: "", parsed: null };
-        const lang = detectLang(file);
-        if (!lang) return { file, stat: stat17, lang: "", parsed: null };
-        const meta = existingMeta.get(file);
-        if (!force && meta && meta.mtimeMs === Math.floor(stat17.mtimeMs)) {
-          return { file, stat: stat17, lang, parsed: null, skippedMeta: meta };
-        }
-        let content;
-        try {
-          content = await fs14.readFile(file, { encoding: "utf8", signal });
-        } catch (e) {
-          if (isAbortError(e)) throw e;
-          return { file, stat: stat17, lang, parsed: null, error: `read error: ${e instanceof Error ? e.message : String(e)}` };
-        }
-        let parsed;
-        try {
-          parsed = await parseFile(file, content, lang);
-        } catch (e) {
-          return { file, stat: stat17, lang, parsed: null, error: `parse error: ${e instanceof Error ? e.message : String(e)}` };
+      batchFiles.map(
+        async (file) => {
+          let stat17;
+          try {
+            stat17 = await fs14.stat(file, statOpts);
+          } catch (e) {
+            if (isAbortError(e)) throw e;
+            return {
+              file,
+              stat: null,
+              lang: "",
+              parsed: null,
+              error: `stat error: ${e instanceof Error ? e.message : String(e)}`,
+              missing: isMissingPathError(e)
+            };
+          }
+          if (!stat17.isFile()) return { file, stat: stat17, lang: "", parsed: null };
+          const lang = detectLang(file);
+          if (!lang) return { file, stat: stat17, lang: "", parsed: null };
+          if (stat17.size > MAX_INDEX_FILE_BYTES) {
+            return {
+              file,
+              stat: stat17,
+              lang,
+              parsed: null,
+              error: `file too large (${stat17.size} bytes; max ${MAX_INDEX_FILE_BYTES})`
+            };
+          }
+          const meta = existingMeta.get(file);
+          if (!force && meta && meta.mtimeMs === Math.floor(stat17.mtimeMs)) {
+            return { file, stat: stat17, lang, parsed: null, skippedMeta: meta };
+          }
+          let content;
+          try {
+            content = await fs14.readFile(file, { encoding: "utf8", signal });
+          } catch (e) {
+            if (isAbortError(e)) throw e;
+            return {
+              file,
+              stat: stat17,
+              lang,
+              parsed: null,
+              error: `read error: ${e instanceof Error ? e.message : String(e)}`
+            };
+          }
+          let parsed;
+          try {
+            parsed = await parseFile(file, content, lang);
+          } catch (e) {
+            return {
+              file,
+              stat: stat17,
+              lang,
+              parsed: null,
+              error: `parse error: ${e instanceof Error ? e.message : String(e)}`
+            };
+          }
+          return { file, stat: stat17, lang, parsed, content };
         }
-        return { file, stat: stat17, lang, parsed, content };
-      })
+      )
     );
     const batchEntries = [];
     const deleteForFiles = [];
@@ -9981,8 +10660,8 @@ async function runIndexerWithStore(store, opts) {
       }
       const result = settled.value;
       if (result.error) {
-        if (result.stat) store.deleteFile(file);
-        if (result.error.includes("error:")) errors.push(result.error);
+        if (result.missing) store.deleteFile(file);
+        errors.push(`${file}: ${result.error}`);
         continue;
       }
       const { stat: stat17, lang, parsed } = result;
@@ -10006,6 +10685,8 @@ async function runIndexerWithStore(store, opts) {
         continue;
       }
       if (parsed.symbols.length === 0) {
+        store.deleteRefsForFile(file);
+        store.deleteSymbolsForFile(file);
         store.upsertFile({
           file,
           lang,
@@ -10016,15 +10697,11 @@ async function runIndexerWithStore(store, opts) {
         filesIndexed++;
         continue;
       }
-      const refs = [];
-      if (parsed.refs && parsed.refs.length > 0) {
-        for (const r of parsed.refs) refs.push({ ...r, fromId: 0 });
-      }
       batchEntries.push({
         file,
         lang,
         symbols: parsed.symbols,
-        refs,
+        refs: parsed.refs ?? [],
         mtimeMs: Math.floor(stat17.mtimeMs),
         symbolCount: parsed.symbols.length
       });
@@ -10032,34 +10709,12 @@ async function runIndexerWithStore(store, opts) {
     }
     if (batchEntries.length > 0) {
       try {
-        const inserted = store.commitBatch(batchEntries, { deleteForFiles });
-        let cursor = 0;
+        store.commitBatch(batchEntries, { deleteForFiles });
         for (const entry of batchEntries) {
           const count = entry.symbols.length;
-          const symbolsWithIds = inserted.slice(cursor, cursor + count);
-          cursor += count;
           symbolsIndexed += count;
           langStats[entry.lang] = (langStats[entry.lang] ?? 0) + count;
           filesIndexed++;
-          if (entry.refs.length > 0 && symbolsWithIds.length > 0) {
-            const refsByLine = /* @__PURE__ */ new Map();
-            for (let i = 0; i < symbolsWithIds.length; i++) {
-              const sym = symbolsWithIds[i];
-              let arr = refsByLine.get(sym.line);
-              if (!arr) {
-                arr = [];
-                refsByLine.set(sym.line, arr);
-              }
-              arr.push(i);
-            }
-            for (const ref of entry.refs) {
-              const indices = refsByLine.get(ref.line);
-              if (indices && indices.length > 0) {
-                const idx = indices.shift();
-                ref.fromId = symbolsWithIds[idx].id;
-              }
-            }
-          }
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -10073,23 +10728,7 @@ async function runIndexerWithStore(store, opts) {
             langStats[entry.lang] = (langStats[entry.lang] ?? 0) + symbolsWithIds.length;
             filesIndexed++;
             if (entry.refs.length > 0 && symbolsWithIds.length > 0) {
-              const refsByLine = /* @__PURE__ */ new Map();
-              for (const sym of symbolsWithIds) {
-                let arr = refsByLine.get(sym.line);
-                if (!arr) {
-                  arr = [];
-                  refsByLine.set(sym.line, arr);
-                }
-                arr.push(sym);
-              }
-              const fallbackBatch = [];
-              for (const ref of entry.refs) {
-                const syms = refsByLine.get(ref.line);
-                if (syms && syms.length > 0) {
-                  const sym = syms.shift();
-                  fallbackBatch.push({ ...ref, fromId: sym.id });
-                }
-              }
+              const fallbackBatch = assignRefsToSymbols2(entry.refs, symbolsWithIds);
               if (fallbackBatch.length > 0) store.insertRefsBatch(fallbackBatch);
             }
             store.upsertFile({
@@ -10100,19 +10739,23 @@ async function runIndexerWithStore(store, opts) {
               lastIndexed: Date.now()
             });
           } catch (innerErr) {
-            errors.push(`fallback write failed: ${entry.file}: ${innerErr instanceof Error ? innerErr.message : String(innerErr)}`);
+            errors.push(
+              `fallback write failed: ${entry.file}: ${innerErr instanceof Error ? innerErr.message : String(innerErr)}`
+            );
           }
         }
       }
     }
   }
-  if (discoveredFiles) {
+  if (discoveredFiles && discoveryComplete) {
     for (const [file_] of existingMeta) {
       if (!discoveredFiles.has(file_)) {
         store.deleteFile(file_);
       }
     }
   }
+  store.resolveRefs();
+  store.setMetadata("relation_graph_version", relationGraphVersion);
   const durationMs = Date.now() - startMs;
   store.setLastIndexed(Date.now());
   return {
@@ -10148,7 +10791,7 @@ async function indexService(args, hooks = {}) {
   });
 }
 function searchService(args) {
-  const store = new IndexStore(args.projectRoot, { indexDir: args.indexDir });
+  const store = indexStorePool.acquire(args.projectRoot, { indexDir: args.indexDir });
   try {
     return store.searchRanked(
       args.query,
@@ -10161,21 +10804,21 @@ function searchService(args) {
       args.limit
     );
   } finally {
-    store.close();
+    indexStorePool.release(store);
   }
 }
 function statsService(args) {
-  const store = new IndexStore(args.projectRoot, { indexDir: args.indexDir });
+  const store = indexStorePool.acquire(args.projectRoot, { indexDir: args.indexDir });
   try {
     return store.getStats();
   } finally {
-    store.close();
+    indexStorePool.release(store);
   }
 }
 
 // src/codebase-index/background-indexer.ts
 var DEFAULT_FULL_INDEX_TIMEOUT_MS = 24e4;
-var DEFAULT_QUERY_TIMEOUT_MS = 8e3;
+var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
 var _ready = false;
 var _indexing = false;
 var _currentFile = 0;
@@ -10244,14 +10887,22 @@ function ensureWorker() {
       if (!entry) return;
       pending.delete(msg.id);
       if (msg.ok) entry.resolve(msg.result);
-      else entry.reject(new Error(msg.error));
+      else {
+        const error = msg.errorName === "LockError" ? new LockError(msg.error) : new Error(msg.error);
+        if (msg.errorName && msg.errorName !== "Error") {
+          error.name = msg.errorName;
+        }
+        entry.reject(error);
+      }
     });
     w.on("error", (err) => {
+      if (worker !== w) return;
       worker = null;
       failAllPending(err);
     });
     w.on("exit", () => {
-      if (worker === w) worker = null;
+      if (worker !== w) return;
+      worker = null;
       failAllPending(new Error("codebase-index worker exited"));
     });
     worker = w;
@@ -10271,6 +10922,11 @@ function terminateWorker(reason) {
 function callIndexOp(op, args, opts) {
   const w = ensureWorker();
   if (!w) return callInline(op, args, opts);
+  if (opts.signal?.aborted) {
+    return Promise.reject(
+      opts.signal.reason instanceof Error ? opts.signal.reason : new Error("Indexing cancelled")
+    );
+  }
   return new Promise((resolve14, reject) => {
     const id = nextRpcId++;
     const timer = setTimeout(() => {
@@ -10285,8 +10941,7 @@ function callIndexOp(op, args, opts) {
     const onAbort = () => {
       w.postMessage({ type: "cancel", id });
     };
-    if (opts.signal?.aborted) onAbort();
-    else opts.signal?.addEventListener("abort", onAbort, { once: true });
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
     const cleanup = () => {
       clearTimeout(timer);
       opts.signal?.removeEventListener("abort", onAbort);
@@ -10430,7 +11085,7 @@ var codebaseIndexTool = {
   category: "Project",
   icon: "index",
   description: "Build or incrementally update the project-wide symbol index. This powers fast codebase search and understanding. By default it only processes files that have changed since the last indexing run.",
-  usageHint: "IMPORTANT FOR LARGE CODEBASES:\n\n- First run (or after major changes): consider `force: true` for a clean rebuild.\n- Normal usage: call without arguments for fast incremental updates.\n- Use `langs` to restrict to specific languages if you only care about certain parts of the project.\nThis tool is relatively expensive \u2014 do not call it on every turn. Use it when the index is stale or before heavy codebase-search sessions.",
+  usageHint: "CREATE OR REFRESH THE SEARCH INDEX:\n\n- When `codebase-stats` or `codebase-search` reports no persisted index, call this without arguments, then retry the search.\n- Normal and first-time usage: call without arguments for an incremental build.\n- Use `force: true` only for a corrupt/stale index or an explicitly requested clean rebuild.\n- Use `langs` to restrict to specific languages if you only care about certain parts of the project.\nThis tool is relatively expensive \u2014 do not call it on every turn. Use it when the index is stale or before heavy codebase-search sessions.",
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write.outside-project"],
@@ -10486,12 +11141,14 @@ var codebaseSearchTool = {
   name: "codebase-search",
   category: "Project",
   icon: "index",
-  description: "Search code symbols using a fast SQLite+BM25 index, with optional LSP fallback. Much more powerful and structured than raw `grep` for finding code by name or concept. Set `preferLsp: true` for live precision when the LSP plugin is active (supersedes codebase-lsp-search).",
-  usageHint: "PREFERRED FOR CODE UNDERSTANDING:\n\n- Use when you need to find where something is defined or used by name.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\nThis is generally better than `grep` when you are looking for symbols rather than arbitrary text patterns.",
+  description: "Search code symbols using a fast SQLite+BM25 index, with optional LSP fallback. Prefer this before broad `tree`, `glob`, or `grep` exploration when finding code by name or concept. Set `preferLsp: true` for live precision when the LSP plugin is active (supersedes codebase-lsp-search).",
+  usageHint: "FIRST CHOICE FOR INDEXABLE CODE UNDERSTANDING:\n\n- Call before broad `tree`, `glob`, or `grep` exploration when locating symbols, concepts, definitions, or candidate modules.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\n- If `indexStatus` reports no persisted data, run `codebase-index` and retry.\nUse `grep` afterwards for exact text, regexes, unsupported content, or concrete usage sites.",
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
-  timeoutMs: 1e4,
+  // The index host has its own 30s read watchdog. Leave enough headroom for
+  // worker teardown and structured timeout reporting.
+  timeoutMs: 35e3,
   inputSchema: {
     type: "object",
     properties: {
@@ -10501,11 +11158,34 @@ var codebaseSearchTool = {
       },
       kind: {
         type: "string",
-        description: "Filter by symbol kind: class, function, interface, method, const, let, var, property, type, enum"
+        enum: [
+          "class",
+          "interface",
+          "enum",
+          "type",
+          "function",
+          "method",
+          "var",
+          "const",
+          "let",
+          "property",
+          "parameter",
+          "namespace",
+          "object",
+          "literal",
+          "schema",
+          "struct",
+          "trait",
+          "impl",
+          "static",
+          "mod"
+        ],
+        description: "Filter by indexed symbol kind"
       },
       lang: {
         type: "string",
-        description: "Filter by language: ts, tsx, js, jsx"
+        enum: ["ts", "tsx", "js", "jsx", "go", "py", "rs", "json", "yaml"],
+        description: "Filter by indexed language"
       },
       lspKind: {
         type: "integer",
@@ -10530,20 +11210,12 @@ var codebaseSearchTool = {
   },
   async execute(input, ctx, execOpts) {
     const state = getIndexState();
-    if (!state.ready) {
-      return {
-        results: [],
-        total: 0,
-        query: input.query,
-        indexStatus: state.indexing ? `Indexing in progress (${state.currentFile}/${state.totalFiles} files) \u2014 retry in a moment.` : "Index not yet built. The codebase is being indexed at startup \u2014 search will be available shortly."
-      };
-    }
-    if (state.indexing) {
+    if (state.indexing && !state.ready) {
       return {
         results: [],
         total: 0,
         query: input.query,
-        indexStatus: `Index refresh in progress (${state.currentFile}/${state.totalFiles} files). Results may be incomplete.`
+        indexStatus: `Indexing in progress (${state.currentFile}/${state.totalFiles} files) \u2014 retry in a moment.`
       };
     }
     if (state.lastError) {
@@ -10556,21 +11228,37 @@ var codebaseSearchTool = {
         indexStatus: `Index build failed: ${state.lastError}. ${retryHint}`
       };
     }
-    const limit = Math.min(input.limit ?? 20, 100);
+    const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 20), 100));
     const { results, total } = await searchCodebaseIndex(
       {
         projectRoot: ctx.projectRoot,
         indexDir: codebaseIndexDirOverride(ctx),
         query: input.query,
-        kind: input.kind,
-        lang: input.lang,
+        kind: input.kind?.toLowerCase(),
+        lang: input.lang?.toLowerCase(),
         file: input.file,
         lspKind: input.lspKind,
         limit
       },
       { signal: execOpts?.signal }
     );
-    return { results, total, query: input.query };
+    let hasPersistedIndex = state.ready || total > 0;
+    if (!hasPersistedIndex) {
+      try {
+        const stats = await codebaseIndexStats(
+          { projectRoot: ctx.projectRoot, indexDir: codebaseIndexDirOverride(ctx) },
+          { signal: execOpts?.signal }
+        );
+        hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
+      } catch {
+      }
+    }
+    return {
+      results,
+      total,
+      query: input.query,
+      ...hasPersistedIndex ? {} : { indexStatus: "No persisted index data found. Run codebase-index to build it." }
+    };
   }
 };
 
@@ -10579,12 +11267,15 @@ var codebaseStatsTool = {
   name: "codebase-stats",
   category: "Project",
   icon: "index",
-  description: "Return health and statistics about the current symbol index (total symbols, files, language/kind breakdown, size, last update). Useful to decide whether to re-index.",
-  usageHint: "CALL BEFORE HEAVY CODEBASE-SEARCH WORK:\n\n- Use to see if the index is up-to-date or needs a refresh.\n- No arguments required.\n- Helps avoid wasting tokens on searches against a stale index.\nLightweight and safe to call frequently.",
+  description: "Check whether a persisted codebase index exists and report its health and statistics (symbols, files, language/kind breakdown, size, last update).",
+  usageHint: "CHECK ONCE BEFORE BROAD CODE EXPLORATION:\n\n- Call before broad `tree`, `glob`, or `grep` exploration to see whether index-backed search is available.\n- If it reports no persisted data, run `codebase-index`, then use `codebase-search`.\n- No arguments required.\nLightweight and safe to call frequently.",
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
-  timeoutMs: 5e3,
+  // The index host has its own 30s read watchdog. Keep the outer tool budget
+  // longer so the host can return a structured timeout instead of being
+  // pre-empted by the generic tool executor.
+  timeoutMs: 35e3,
   inputSchema: {
     type: "object",
     properties: {},
@@ -10592,7 +11283,8 @@ var codebaseStatsTool = {
   },
   async execute(_input, ctx, execOpts) {
     const idxState = getIndexState();
-    if (!idxState.ready) {
+    const indexPath = resolveIndexDir(ctx.projectRoot, codebaseIndexDirOverride(ctx));
+    if (idxState.indexing) {
       return {
         totalSymbols: 0,
         totalFiles: 0,
@@ -10600,22 +11292,47 @@ var codebaseStatsTool = {
         byKind: {},
         lastIndexed: null,
         sizeBytes: 0,
-        indexPath: "",
+        indexPath,
         version: SCHEMA_VERSION,
-        indexStatus: idxState.indexing ? `Indexing in progress (${idxState.currentFile}/${idxState.totalFiles} files).` : "Index not yet built."
+        statsAvailable: false,
+        indexing: {
+          currentFile: idxState.currentFile,
+          totalFiles: idxState.totalFiles
+        },
+        indexStatus: idxState.ready ? `Index refresh in progress (${idxState.currentFile}/${idxState.totalFiles} files). The persisted snapshot remains available to codebase-search; retry stats after refresh.` : `Startup indexing in progress (${idxState.currentFile}/${idxState.totalFiles} files). Do not start another index; retry stats or codebase-search after completion.`
       };
     }
-    const stats = await codebaseIndexStats(
-      { projectRoot: ctx.projectRoot, indexDir: codebaseIndexDirOverride(ctx) },
-      { signal: execOpts?.signal }
-    );
-    if (idxState.indexing) {
+    let stats;
+    try {
+      stats = await codebaseIndexStats(
+        { projectRoot: ctx.projectRoot, indexDir: codebaseIndexDirOverride(ctx) },
+        { signal: execOpts?.signal }
+      );
+    } catch (err) {
+      if (!(err instanceof IndexTimeoutError) && err?.name !== "IndexTimeoutError") {
+        throw err;
+      }
       return {
-        ...stats,
-        indexStatus: `Index refresh in progress (${idxState.currentFile}/${idxState.totalFiles} files). Stats may be incomplete.`
+        totalSymbols: 0,
+        totalFiles: 0,
+        byLang: {},
+        byKind: {},
+        lastIndexed: null,
+        sizeBytes: 0,
+        indexPath,
+        version: SCHEMA_VERSION,
+        statsAvailable: false,
+        indexStatus: "Index statistics timed out. Do not repeatedly retry stats; try codebase-search directly or use the appropriate grep/glob/tree fallback."
       };
     }
     const circuit = idxState.circuit;
+    const hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
+    let indexStatus;
+    if (circuit.state === "open") {
+      indexStatus = `${hasPersistedIndex ? "Indexing" : "No persisted index data found, and indexing"} is paused after repeated failures (last: ${circuit.lastFailure ?? "unknown"}); auto-retry in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s, or run /codebase-reindex. ` + (hasPersistedIndex ? "Stats reflect the last successful build." : "Build the index after recovery.");
+    } else if (!hasPersistedIndex) {
+      indexStatus = "No persisted index data found. Run codebase-index to build it before broad code exploration.";
+    }
     return {
       totalSymbols: stats.totalSymbols,
       totalFiles: stats.totalFiles,
@@ -10625,9 +11342,8 @@ var codebaseStatsTool = {
       sizeBytes: stats.sizeBytes,
       indexPath: stats.indexPath,
       version: stats.version,
-      ...circuit.state === "open" ? {
-        indexStatus: `Indexing is paused after repeated failures (last: ${circuit.lastFailure ?? "unknown"}); auto-retry in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s, or run /codebase-reindex. Stats reflect the last successful build.`
-      } : {}
+      statsAvailable: true,
+      ...indexStatus ? { indexStatus } : {}
     };
   }
 };
@@ -12146,6 +12862,11 @@ Compare this against your old_string and retry with the file's actual text.` : "
 
 // src/exec.ts
 import { spawn as spawn8 } from "node:child_process";
+import {
+  emitProcessCompleted as emitProcessCompleted3,
+  emitProcessOutput as emitProcessOutput3,
+  emitProcessStarted as emitProcessStarted3
+} from "@wrongstack/core";
 import { toErrorMessage as toErrorMessage3 } from "@wrongstack/core/utils/error";
 init_output_spool();
 init_util();
@@ -13254,12 +13975,30 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId, danger) {
       resolve14(result);
     };
     const startedAt = Date.now();
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let telemetryCompleted = false;
+    let timedOut = false;
     const spool = createOutputSpool({ tool: `exec-${cmd}`, thresholdBytes: MAX_OUTPUT2 });
     const resolved = resolveWin32Command(cmd);
     const needsShell = isWin3 && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
     const shim = needsShell ? buildWin32CmdShimInvocation(resolved, args) : null;
     const spawnCmd = shim?.command ?? resolved;
     const spawnArgs = shim?.args ?? args;
+    const emitCompletedOnce = (exitCode, pid2, signal2) => {
+      if (telemetryCompleted) return;
+      telemetryCompleted = true;
+      emitProcessCompleted3({
+        ...pid2 !== void 0 ? { pid: pid2 } : {},
+        exitCode,
+        ...signal2 ? { signal: signal2 } : {},
+        durationMs: Date.now() - startedAt,
+        stdoutBytes,
+        stderrBytes,
+        timedOut,
+        endedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    };
     let child;
     try {
       child = spawn8(spawnCmd, spawnArgs, {
@@ -13272,6 +14011,15 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId, danger) {
       });
     } catch (err) {
       spool.finalize();
+      emitProcessStarted3({
+        parentPid: process.pid,
+        command: redactCommand(`${cmd} ${args.join(" ")}`),
+        args: redactCommand(args.join(" ")).split(" ").filter(Boolean),
+        cwd,
+        background: false,
+        startedAt: new Date(startedAt).toISOString()
+      });
+      emitCompletedOnce(1, void 0);
       finish({
         command: cmd,
         args,
@@ -13284,6 +14032,15 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId, danger) {
       });
       return;
     }
+    emitProcessStarted3({
+      ...child.pid !== void 0 ? { pid: child.pid } : {},
+      parentPid: process.pid,
+      command: redactCommand(`${cmd} ${args.join(" ")}`),
+      args: redactCommand(args.join(" ")).split(" ").filter(Boolean),
+      cwd,
+      background: false,
+      startedAt: new Date(startedAt).toISOString()
+    });
     child.on("error", (err) => {
       const isAbort = err && err.code === "ABORT_ERR";
       const stderrText = isAbort ? `Aborted: ${err.message}` : err.message;
@@ -13292,6 +14049,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId, danger) {
       if (typeof pid === "number") registry.unregister(pid);
       registry.afterCall(Date.now() - startedAt, true);
       spool.finalize();
+      emitCompletedOnce(isAbort ? 124 : 1, child.pid, isAbort ? "ABORT" : void 0);
       finish({
         command: cmd,
         args,
@@ -13311,6 +14069,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId, danger) {
     }
     const timer = setTimeout(() => {
       killed = true;
+      timedOut = true;
       if (typeof pid === "number") registry.kill(pid);
       else child.kill("SIGTERM");
     }, timeout);
@@ -13325,11 +14084,15 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId, danger) {
     }
     child.stdout?.on("data", (chunk) => {
       const text = chunk.toString();
+      stdoutBytes += chunk.byteLength;
+      emitProcessOutput3({ pid, stream: "stdout", chunk });
       if (stdout.length < MAX_OUTPUT2) stdout += text;
       spool.write(text);
     });
     child.stderr?.on("data", (chunk) => {
       const text = chunk.toString();
+      stderrBytes += chunk.byteLength;
+      emitProcessOutput3({ pid, stream: "stderr", chunk });
       if (stderr.length < MAX_OUTPUT2) stderr += text;
       spool.write(text);
     });
@@ -13339,6 +14102,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId, danger) {
       if (typeof pid === "number") registry.unregister(pid);
       const durationMs = Date.now() - startedAt;
       const exitCode = killed ? 124 : code ?? 1;
+      emitCompletedOnce(exitCode, pid);
       registry.afterCall(durationMs, exitCode !== 0);
       const spooled = spool.finalize();
       finish({
@@ -13414,7 +14178,7 @@ function guardedLookup(hostname2, options, callback) {
 var pinnedAgent;
 function getPinnedDispatcher() {
   if (!pinnedAgent) {
-    pinnedAgent = new Agent({ connect: { lookup: guardedLookup } });
+    pinnedAgent = new Agent({ allowH2: false, connect: { lookup: guardedLookup } });
   }
   return pinnedAgent;
 }
@@ -13516,7 +14280,7 @@ async function assertNotPrivate(hostname2) {
         }
       }
     } catch (err) {
-      if (err instanceof Error && err.message.startsWith("fetch:")) throw err;
+      if (err instanceof ToolValidationError2) throw err;
     }
   }
 }
@@ -13864,7 +14628,7 @@ async function detectFixer(cwd) {
 init_util();
 import { spawn as spawn9 } from "node:child_process";
 import { statSync as statSync3 } from "node:fs";
-import { dirname as dirname12, resolve as resolve11, sep as sep4 } from "node:path";
+import { dirname as dirname12, resolve as resolve11, sep as sep5 } from "node:path";
 import { assessCommitSafety, buildChildEnv as buildChildEnv4 } from "@wrongstack/core";
 var TIMEOUT_MS2 = 3e4;
 var MAX_OUTPUT3 = 1e5;
@@ -14009,7 +14773,7 @@ function validateWorktreeInput(input, projectRoot) {
   if ((input.worktreeAction === "add" || input.worktreeAction === "remove") && input.worktreePath) {
     const root = resolve11(projectRoot);
     const abs = resolve11(root, input.worktreePath);
-    if (abs !== root && !abs.startsWith(root + sep4)) {
+    if (abs !== root && !abs.startsWith(root + sep5)) {
       return reject(`unsafe worktree path (escapes project root): ${input.worktreePath}`);
     }
   }
@@ -14172,8 +14936,8 @@ var WALK_CONCURRENCY = 16;
 var globTool = {
   name: "glob",
   category: "Filesystem",
-  description: "Find files matching a glob pattern. Fast way to discover relevant files before reading, grepping, or editing them.",
-  usageHint: "RECOMMENDED FOR SCOPING SEARCHES:\n\n- Use early to get a list of files you actually care about.\n- Combine with `path` and `limit`.\n- Default ignores common build/dependency directories.\nMuch more efficient than shell `find` for most use cases inside the agent.",
+  description: "Find files by path pattern. Use index-backed `codebase-search` first for code symbols or concepts when it is live.",
+  usageHint: "PATH DISCOVERY AND SEARCH SCOPING:\n\n- When `codebase-search` is live, use it first for code concepts; use `glob` for filenames, path patterns, and non-indexed files.\n- Combine with `path` and `limit`.\n- Default ignores common build/dependency directories.\nMuch more efficient than shell `find` for most use cases inside the agent.",
   selection: {
     doNotUseWhen: "you need to search inside file contents.",
     useInstead: ["grep"]
@@ -14361,8 +15125,8 @@ var NATIVE_MAX_FILE_BYTES = 1e6;
 var grepTool = {
   name: "grep",
   category: "Search",
-  description: "Search across files using a regular expression. This is one of the primary code search tools. Prefers ripgrep for speed and features when available.",
-  usageHint: 'POWERFUL CODE SEARCH TOOL:\n\n- `pattern` is a regular expression.\n- Use `output_mode: "content"` (default) to get matching lines with context.\n- Use `"files_with_matches"` when you only need the list of files.\n- Use `"count"` for quick statistics.\n- `glob` and `path` let you narrow the search scope significantly.\n- Always prefer this over `bash grep` when searching code.',
+  description: "Search exact file contents using a regular expression. Use index-backed `codebase-search` first for symbol or concept discovery when it is live. Prefers ripgrep for speed and features when available.",
+  usageHint: 'EXACT-TEXT AND REGEX SEARCH:\n\n- When `codebase-search` is live, use it first for symbols and concepts; use `grep` for exact text, regexes, unsupported content, and concrete usage sites.\n- `pattern` is a regular expression.\n- Use `output_mode: "content"` (default) to get matching lines with context.\n- Use `"files_with_matches"` when you only need the list of files.\n- Use `"count"` for quick statistics.\n- `glob` and `path` let you narrow the search scope significantly.\n- Always prefer this over `bash grep` when searching code.',
   selection: {
     doNotUseWhen: "you only need to locate files by name or path pattern.",
     useInstead: ["glob"]
@@ -15384,6 +16148,7 @@ function toYaml(data, indent = 0) {
 }
 
 // src/kanban.ts
+import { randomUUID } from "node:crypto";
 import { deserializeTaskGraph as deserializeTaskGraph2, loadTasks as loadTasks2, serializeTaskGraph } from "@wrongstack/core";
 import {
   addCheckToTask,
@@ -15401,7 +16166,7 @@ import {
   duplicateBoard,
   exportBoardAsMarkdown,
   exportBoardToTaskGraph,
-  generateBoardFromDescription,
+  createBoardFromText,
   getBoard as getBoard2,
   getKanbanOrchestrationSnapshot,
   getKanbanQueueHealth,
@@ -15423,7 +16188,9 @@ import {
   setTaskChain,
   splitTask,
   syncBoardFromTaskGraph as syncBoardFromTaskGraph2,
+  transitionTask,
   transferTaskToBoard,
+  touchKanbanPresence as touchKanbanPresence2,
   updateBoard as updateBoard2,
   updateCheckOnTask,
   updateColumn,
@@ -15435,17 +16202,21 @@ import {
 // src/session-kanban.ts
 import {
   deserializeTaskGraph,
+  GlobalMailbox,
   loadPlan,
   loadTasks,
   mutatePlan,
   mutateTasks
 } from "@wrongstack/core";
+import { resolveWstackPaths as resolveWstackPaths3 } from "@wrongstack/core/utils";
 import {
   createBoard,
   getBoard,
+  getKanbanDir,
   listBoards,
   removeBoard,
   syncBoardFromTaskGraph,
+  touchKanbanPresence,
   updateBoard
 } from "@wrongstack/kanban";
 var SESSION_BOARD_TAG = "session-work";
@@ -15657,8 +16428,8 @@ function projectSessionPlanToKanban(projectRoot, items, sessionId) {
 var kanbanTool = {
   name: "kanban",
   category: "Project",
-  description: "Manage project-scoped multi-kanban boards stored under .wrongstack/kanbans. Supports board/task/column CRUD, ready-task queues, dependency chains, split/merge, assignment metadata, provider/model/fallback routing hints, goal metrics, success checks, notes, links, and run status updates.",
-  usageHint: "Use this for durable project kanban state. Agents should call snapshot/ready_tasks, then claim_task before working. Use set_chain for ordered work, split_task/merge_tasks when task scope changes, assign_task with provider/model/fallback hints before spawning, mark_assignment when starting or finishing, and release_task if the claim cannot be worked.",
+  description: "Manage and audit project-scoped multi-kanban boards stored under .wrongstack/kanbans. Managed cards enforce fully specified details and adjacent Backlog \u2192 Todo \u2192 Running \u2192 Review \u2192 Done transitions with persistent comments and evidence. Successful board access records live agent/session presence.",
+  usageHint: "Use this for durable project kanban state. Reassess with get_board whenever evidence changes; agents may add, update, split, merge, reprioritize, or remove tasks so the board remains a live plan. Presence includes active/last-seen session and agent metadata. For managed boards, fully fill card details, use transition_task after every material step, attach truthful evidence, and never use update_task/move_task to bypass lifecycle guards. Worker completion enters Review; only passed acceptance criteria plus review evidence allow Done.",
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
@@ -15695,6 +16466,7 @@ var kanbanTool = {
           "transfer_task",
           "get_task",
           "update_task",
+          "transition_task",
           "move_task",
           "delete_task",
           "set_chain",
@@ -15725,6 +16497,7 @@ var kanbanTool = {
       targetColumnId: { type: "string" },
       title: { type: "string" },
       description: { type: "string" },
+      dueDate: { type: "string" },
       tags: { type: "array", items: { type: "string" } },
       labels: { type: "array", items: { type: "string" } },
       priority: { type: "string", enum: ["critical", "high", "medium", "low"] },
@@ -15771,6 +16544,18 @@ var kanbanTool = {
         type: "string",
         enum: ["assigned", "queued", "running", "completed", "failed", "cancelled"]
       },
+      lifecycleStage: {
+        type: "string",
+        enum: ["backlog", "todo", "running", "review", "done"]
+      },
+      transitionAction: { type: "string" },
+      transitionComment: { type: "string" },
+      attachmentUrl: { type: "string" },
+      attachmentTitle: { type: "string" },
+      attachmentType: {
+        type: "string",
+        enum: ["issue", "pr", "doc", "commit", "design", "file", "url", "other"]
+      },
       releaseStatus: { type: "string", enum: ["pending", "ready", "blocked"] },
       releaseReason: { type: "string" },
       clearAssignee: { type: "boolean" },
@@ -15841,591 +16626,649 @@ var kanbanTool = {
   async execute(input, ctx) {
     const projectRoot = ctx.projectRoot;
     if (!projectRoot) return fail("No project root is available.");
+    const withPresence = async (result) => {
+      const boardId = result.board?.id ?? input.boardId;
+      if (!result.ok || !boardId || !ctx.session?.id || !ctx.agentId) return result;
+      try {
+        const board = await touchKanbanPresence2(projectRoot, boardId, {
+          sessionId: ctx.session.id,
+          agentId: ctx.agentId,
+          agentName: ctx.agentName,
+          taskId: input.taskId ?? result.task?.id,
+          runTaskId: input.runTaskId
+        });
+        return board ? { ...result, board } : result;
+      } catch {
+        return result;
+      }
+    };
     try {
-      switch (input.action) {
-        case "list_boards": {
-          const boards = await listBoards2(projectRoot);
-          return { ok: true, message: `${boards.length} board(s).`, boards };
-        }
-        case "get_board": {
-          const board = await requireBoard(projectRoot, input.boardId);
-          return board ? okBoard(board) : fail("Board not found.");
-        }
-        case "create_board": {
-          if (!input.title) return fail("create_board requires title.");
-          const board = await createBoard2(projectRoot, {
-            title: input.title,
-            ...input.description !== void 0 ? { description: input.description } : {},
-            ...input.tags !== void 0 ? { tags: input.tags } : {},
-            ...input.generatedBy !== void 0 ? { generatedBy: input.generatedBy } : {}
-          });
-          return { ok: true, message: `Board created: ${board.title}`, board };
-        }
-        case "update_board": {
-          if (!input.boardId) return fail("update_board requires boardId.");
-          const board = await updateBoard2(projectRoot, input.boardId, {
-            ...input.title !== void 0 ? { title: input.title } : {},
-            ...input.description !== void 0 ? { description: input.description } : {},
-            ...input.tags !== void 0 ? { tags: input.tags } : {}
-          });
-          return board ? okBoard(board, "Board updated.") : fail("Board not found.");
-        }
-        case "duplicate_board": {
-          if (!input.boardId) return fail("duplicate_board requires boardId.");
-          const board = await duplicateBoard(projectRoot, input.boardId, {
-            ...input.title !== void 0 ? { title: input.title } : {},
-            ...input.generatedBy !== void 0 ? { generatedBy: input.generatedBy } : {},
-            ...input.includeTasks !== void 0 ? { includeTasks: input.includeTasks } : {},
-            ...input.includeCompletedTasks !== void 0 ? { includeCompletedTasks: input.includeCompletedTasks } : {},
-            ...input.preserveAssignment !== void 0 ? { preserveAssignment: input.preserveAssignment } : {}
-          });
-          return board ? okBoard(board, "Board duplicated.") : fail("Board not found.");
-        }
-        case "delete_board": {
-          if (!input.boardId) return fail("delete_board requires boardId.");
-          const removed = await removeBoard2(projectRoot, input.boardId);
-          return { ok: removed, message: removed ? "Board deleted." : "Board not found." };
-        }
-        case "generate_board": {
-          if (!input.description) return fail("generate_board requires description.");
-          const boardInput = generateBoardFromDescription({
-            description: input.description,
-            ...input.title !== void 0 ? { title: input.title } : {},
-            ...input.context !== void 0 ? { context: input.context } : {},
-            ...input.columns !== void 0 ? { columns: input.columns } : {}
-          });
-          const board = await createBoard2(projectRoot, boardInput);
-          for (const taskInput2 of parseLinesIntoTasks(
-            input.description,
-            board.columns[0]?.id ?? "backlog"
-          )) {
-            await addTask(projectRoot, board.id, taskInput2);
+      const result = await (async () => {
+        switch (input.action) {
+          case "list_boards": {
+            const boards = await listBoards2(projectRoot);
+            return { ok: true, message: `${boards.length} board(s).`, boards };
           }
-          return okBoard(await getBoard2(projectRoot, board.id) ?? board, "Board generated.");
-        }
-        case "export_markdown": {
-          const board = await requireBoard(projectRoot, input.boardId);
-          if (!board) return fail("Board not found.");
-          return {
-            ok: true,
-            message: "Board exported.",
-            board,
-            markdown: exportBoardAsMarkdown(board)
-          };
-        }
-        case "export_task_graph": {
-          if (!input.boardId) return fail("export_task_graph requires boardId.");
-          const exported = await exportBoardToTaskGraph(projectRoot, input.boardId, {
-            ...input.graphId !== void 0 ? { graphId: input.graphId } : {},
-            ...input.specId !== void 0 ? { specId: input.specId } : {},
-            ...input.title !== void 0 ? { title: input.title } : {},
-            ...input.preserveOriginTaskIds !== void 0 ? { preserveOriginTaskIds: input.preserveOriginTaskIds } : {},
-            ...input.includeArchived !== void 0 ? { includeArchived: input.includeArchived } : {}
-          });
-          if (!exported) return fail("Board not found.");
-          return {
-            ok: true,
-            message: `Task graph exported with ${exported.graph.nodes.size} node(s).`,
-            board: exported.board,
-            taskGraph: serializeTaskGraph(exported.graph)
-          };
-        }
-        case "sync_task_graph": {
-          if (!input.boardId || !input.taskGraph) {
-            return fail("sync_task_graph requires boardId and taskGraph.");
+          case "get_board": {
+            const board = await requireBoard(projectRoot, input.boardId);
+            return board ? okBoard(board) : fail("Board not found.");
           }
-          const graph = deserializeTaskGraph2(input.taskGraph);
-          const result = await syncBoardFromTaskGraph2(projectRoot, input.boardId, graph, {
-            ...input.title !== void 0 ? { title: input.title } : {},
-            ...input.description !== void 0 ? { description: input.description } : {},
-            ...input.tags !== void 0 ? { tags: input.tags } : {},
-            ...input.generatedBy !== void 0 ? { generatedBy: input.generatedBy } : {},
-            ...input.sourceSystem !== void 0 ? { sourceSystem: input.sourceSystem } : {},
-            ...input.phaseId !== void 0 ? { phaseId: input.phaseId } : {},
-            ...input.includeCompletedTasks !== void 0 ? { includeCompletedTasks: input.includeCompletedTasks } : {},
-            ...input.archiveMissingTasks !== void 0 ? { archiveMissingTasks: input.archiveMissingTasks } : {},
-            ...input.preserveManualDependencies !== void 0 ? { preserveManualDependencies: input.preserveManualDependencies } : {}
-          });
-          return result ? {
-            ok: true,
-            message: `Task graph synced: ${result.createdTaskIds.length} created, ${result.updatedTaskIds.length} updated, ${result.archivedTaskIds.length} archived.`,
-            board: result.board
-          } : fail("Board not found.");
-        }
-        case "create_from_graph": {
-          if (!input.taskGraph) return fail("create_from_graph requires taskGraph.");
-          const graph = deserializeTaskGraph2(input.taskGraph);
-          const { board } = await createBoardFromTaskGraph(projectRoot, graph, {
-            ...input.title !== void 0 ? { title: input.title } : {},
-            ...input.description !== void 0 ? { description: input.description } : {},
-            ...input.tags !== void 0 ? { tags: input.tags } : {},
-            ...input.generatedBy !== void 0 ? { generatedBy: input.generatedBy } : {},
-            ...input.sourceSystem !== void 0 ? { sourceSystem: input.sourceSystem } : {},
-            ...input.phaseId !== void 0 ? { phaseId: input.phaseId } : {},
-            ...input.includeCompletedTasks !== void 0 ? { includeCompletedTasks: input.includeCompletedTasks } : {}
-          });
-          return {
-            ok: true,
-            message: `Created board "${board.title}" from task graph with ${board.tasks.length} tasks.`,
-            board
-          };
-        }
-        case "import_session_tasks": {
-          const taskPath = ctx.meta?.["task.path"];
-          if (!taskPath) return fail("No session task file for this session.");
-          const file = await loadTasks2(taskPath);
-          if (!file || file.tasks.length === 0) return fail("No session tasks to import.");
-          const sessionId = ctx.session?.id ?? file.sessionId ?? "session";
-          const graph = deserializeTaskGraph2(taskFileToSerializedGraph(file.tasks, sessionId));
-          const tags = ["session", `session:${sessionId}`];
-          const existing = (await listBoards2(projectRoot)).find(
-            (b) => b.tags?.includes(`session:${sessionId}`)
-          );
-          if (existing) {
-            const result = await syncBoardFromTaskGraph2(projectRoot, existing.id, graph, {
+          case "create_board": {
+            if (!input.title) return fail("create_board requires title.");
+            const board = await createBoard2(projectRoot, {
+              title: input.title,
+              ...input.description !== void 0 ? { description: input.description } : {},
+              ...input.tags !== void 0 ? { tags: input.tags } : {},
+              ...input.generatedBy !== void 0 ? { generatedBy: input.generatedBy } : {}
+            });
+            return { ok: true, message: `Board created: ${board.title}`, board };
+          }
+          case "update_board": {
+            if (!input.boardId) return fail("update_board requires boardId.");
+            const board = await updateBoard2(projectRoot, input.boardId, {
+              ...input.title !== void 0 ? { title: input.title } : {},
+              ...input.description !== void 0 ? { description: input.description } : {},
+              ...input.tags !== void 0 ? { tags: input.tags } : {}
+            });
+            return board ? okBoard(board, "Board updated.") : fail("Board not found.");
+          }
+          case "duplicate_board": {
+            if (!input.boardId) return fail("duplicate_board requires boardId.");
+            const board = await duplicateBoard(projectRoot, input.boardId, {
+              ...input.title !== void 0 ? { title: input.title } : {},
+              ...input.generatedBy !== void 0 ? { generatedBy: input.generatedBy } : {},
+              ...input.includeTasks !== void 0 ? { includeTasks: input.includeTasks } : {},
+              ...input.includeCompletedTasks !== void 0 ? { includeCompletedTasks: input.includeCompletedTasks } : {},
+              ...input.preserveAssignment !== void 0 ? { preserveAssignment: input.preserveAssignment } : {}
+            });
+            return board ? okBoard(board, "Board duplicated.") : fail("Board not found.");
+          }
+          case "delete_board": {
+            if (!input.boardId) return fail("delete_board requires boardId.");
+            const removed = await removeBoard2(projectRoot, input.boardId);
+            return { ok: removed, message: removed ? "Board deleted." : "Board not found." };
+          }
+          case "generate_board": {
+            if (!input.description) return fail("generate_board requires description.");
+            const boardInput = createBoardFromText({
+              description: input.description,
+              ...input.title !== void 0 ? { title: input.title } : {},
+              ...input.context !== void 0 ? { context: input.context } : {},
+              ...input.columns !== void 0 ? { columns: input.columns } : {}
+            });
+            const board = await createBoard2(projectRoot, boardInput);
+            for (const taskInput2 of parseLinesIntoTasks(
+              input.description,
+              board.columns[0]?.id ?? "backlog"
+            )) {
+              await addTask(projectRoot, board.id, taskInput2);
+            }
+            return okBoard(await getBoard2(projectRoot, board.id) ?? board, "Board generated.");
+          }
+          case "export_markdown": {
+            const board = await requireBoard(projectRoot, input.boardId);
+            if (!board) return fail("Board not found.");
+            return {
+              ok: true,
+              message: "Board exported.",
+              board,
+              markdown: exportBoardAsMarkdown(board)
+            };
+          }
+          case "export_task_graph": {
+            if (!input.boardId) return fail("export_task_graph requires boardId.");
+            const exported = await exportBoardToTaskGraph(projectRoot, input.boardId, {
+              ...input.graphId !== void 0 ? { graphId: input.graphId } : {},
+              ...input.specId !== void 0 ? { specId: input.specId } : {},
+              ...input.title !== void 0 ? { title: input.title } : {},
+              ...input.preserveOriginTaskIds !== void 0 ? { preserveOriginTaskIds: input.preserveOriginTaskIds } : {},
+              ...input.includeArchived !== void 0 ? { includeArchived: input.includeArchived } : {}
+            });
+            if (!exported) return fail("Board not found.");
+            return {
+              ok: true,
+              message: `Task graph exported with ${exported.graph.nodes.size} node(s).`,
+              board: exported.board,
+              taskGraph: serializeTaskGraph(exported.graph)
+            };
+          }
+          case "sync_task_graph": {
+            if (!input.boardId || !input.taskGraph) {
+              return fail("sync_task_graph requires boardId and taskGraph.");
+            }
+            const graph = deserializeTaskGraph2(input.taskGraph);
+            const result2 = await syncBoardFromTaskGraph2(projectRoot, input.boardId, graph, {
+              ...input.title !== void 0 ? { title: input.title } : {},
+              ...input.description !== void 0 ? { description: input.description } : {},
+              ...input.tags !== void 0 ? { tags: input.tags } : {},
+              ...input.generatedBy !== void 0 ? { generatedBy: input.generatedBy } : {},
+              ...input.sourceSystem !== void 0 ? { sourceSystem: input.sourceSystem } : {},
+              ...input.phaseId !== void 0 ? { phaseId: input.phaseId } : {},
+              ...input.includeCompletedTasks !== void 0 ? { includeCompletedTasks: input.includeCompletedTasks } : {},
+              ...input.archiveMissingTasks !== void 0 ? { archiveMissingTasks: input.archiveMissingTasks } : {},
+              ...input.preserveManualDependencies !== void 0 ? { preserveManualDependencies: input.preserveManualDependencies } : {}
+            });
+            return result2 ? {
+              ok: true,
+              message: `Task graph synced: ${result2.createdTaskIds.length} created, ${result2.updatedTaskIds.length} updated, ${result2.archivedTaskIds.length} archived.`,
+              board: result2.board
+            } : fail("Board not found.");
+          }
+          case "create_from_graph": {
+            if (!input.taskGraph) return fail("create_from_graph requires taskGraph.");
+            const graph = deserializeTaskGraph2(input.taskGraph);
+            const { board } = await createBoardFromTaskGraph(projectRoot, graph, {
+              ...input.title !== void 0 ? { title: input.title } : {},
+              ...input.description !== void 0 ? { description: input.description } : {},
+              ...input.tags !== void 0 ? { tags: input.tags } : {},
+              ...input.generatedBy !== void 0 ? { generatedBy: input.generatedBy } : {},
+              ...input.sourceSystem !== void 0 ? { sourceSystem: input.sourceSystem } : {},
+              ...input.phaseId !== void 0 ? { phaseId: input.phaseId } : {},
+              ...input.includeCompletedTasks !== void 0 ? { includeCompletedTasks: input.includeCompletedTasks } : {}
+            });
+            return {
+              ok: true,
+              message: `Created board "${board.title}" from task graph with ${board.tasks.length} tasks.`,
+              board
+            };
+          }
+          case "import_session_tasks": {
+            const taskPath = ctx.meta?.["task.path"];
+            if (!taskPath) return fail("No session task file for this session.");
+            const file = await loadTasks2(taskPath);
+            if (!file || file.tasks.length === 0) return fail("No session tasks to import.");
+            const sessionId = ctx.session?.id ?? file.sessionId ?? "session";
+            const graph = deserializeTaskGraph2(taskFileToSerializedGraph(file.tasks, sessionId));
+            const tags = ["session", `session:${sessionId}`];
+            const existing = (await listBoards2(projectRoot)).find(
+              (b) => b.tags?.includes(`session:${sessionId}`)
+            );
+            if (existing) {
+              const result2 = await syncBoardFromTaskGraph2(projectRoot, existing.id, graph, {
+                sourceSystem: "session",
+                tags,
+                archiveMissingTasks: true,
+                includeCompletedTasks: true
+              });
+              return result2 ? {
+                ok: true,
+                message: `Synced ${file.tasks.length} session tasks into board "${result2.board.title}".`,
+                board: result2.board
+              } : fail("Session board vanished mid-sync.");
+            }
+            const { board } = await createBoardFromTaskGraph(projectRoot, graph, {
+              title: `Session tasks (${sessionId.slice(0, 8)})`,
               sourceSystem: "session",
-              tags,
-              archiveMissingTasks: true,
-              includeCompletedTasks: true
+              tags
             });
-            return result ? {
+            return {
               ok: true,
-              message: `Synced ${file.tasks.length} session tasks into board "${result.board.title}".`,
-              board: result.board
-            } : fail("Session board vanished mid-sync.");
+              message: `Imported ${file.tasks.length} session tasks into new board "${board.title}".`,
+              board
+            };
           }
-          const { board } = await createBoardFromTaskGraph(projectRoot, graph, {
-            title: `Session tasks (${sessionId.slice(0, 8)})`,
-            sourceSystem: "session",
-            tags
-          });
-          return {
-            ok: true,
-            message: `Imported ${file.tasks.length} session tasks into new board "${board.title}".`,
-            board
-          };
-        }
-        case "search_tasks": {
-          const tasks = await searchKanban(projectRoot, {
-            query: input.query,
-            boardId: input.boardId,
-            assignedAgent: input.agentId,
-            status: input.status,
-            priority: input.priority,
-            label: input.labels?.[0],
-            chainId: input.chainId
-          });
-          return { ok: true, message: `${tasks.length} task(s) matched.`, tasks };
-        }
-        case "ready_tasks": {
-          const tasks = await listReadyTasks(projectRoot, {
-            query: input.query,
-            boardId: input.boardId,
-            assignedAgent: input.agentId,
-            priority: input.priority,
-            label: input.labels?.[0],
-            chainId: input.chainId,
-            limit: input.limit
-          });
-          return { ok: true, message: `${tasks.length} ready task(s).`, tasks };
-        }
-        case "snapshot": {
-          const snapshot = await getKanbanOrchestrationSnapshot(projectRoot, {
-            query: input.query,
-            boardId: input.boardId,
-            assignedAgent: input.agentId,
-            status: input.status,
-            priority: input.priority,
-            label: input.labels?.[0],
-            chainId: input.chainId
-          });
-          return {
-            ok: true,
-            message: `${snapshot.ready.length} ready, ${snapshot.running.length} running, ${snapshot.blocked.length} blocked.`,
-            snapshot
-          };
-        }
-        case "add_column": {
-          if (!input.boardId || !input.title) return fail("add_column requires boardId and title.");
-          const result = await addColumn(projectRoot, input.boardId, {
-            title: input.title,
-            ...input.description !== void 0 ? { description: input.description } : {}
-          });
-          return result ? okBoard(result.board, "Column added.") : fail("Board not found.");
-        }
-        case "update_column": {
-          if (!input.boardId || !input.columnId)
-            return fail("update_column requires boardId and columnId.");
-          const board = await updateColumn(projectRoot, input.boardId, input.columnId, {
-            ...input.title !== void 0 ? { title: input.title } : {},
-            ...input.description !== void 0 ? { description: input.description } : {},
-            ...input.order !== void 0 ? { order: input.order } : {}
-          });
-          return board ? okBoard(board, "Column updated.") : fail("Column not found.");
-        }
-        case "delete_column": {
-          if (!input.boardId || !input.columnId)
-            return fail("delete_column requires boardId and columnId.");
-          const board = await removeColumn(projectRoot, input.boardId, input.columnId, {
-            moveTasksToColumnId: input.moveTasksToColumnId
-          });
-          return board ? okBoard(board, "Column deleted.") : fail("Column not found.");
-        }
-        case "add_task": {
-          if (!input.boardId || !input.title) return fail("add_task requires boardId and title.");
-          const result = await addTask(projectRoot, input.boardId, taskInput(input));
-          return result ? okTask(result.board, result.task, "Task added.") : fail("Board not found.");
-        }
-        case "split_task": {
-          if (!input.boardId || !input.taskId || !input.childTitles?.length) {
-            return fail("split_task requires boardId, taskId, and childTitles.");
+          case "search_tasks": {
+            const tasks = await searchKanban(projectRoot, {
+              query: input.query,
+              boardId: input.boardId,
+              assignedAgent: input.agentId,
+              status: input.status,
+              priority: input.priority,
+              label: input.labels?.[0],
+              chainId: input.chainId
+            });
+            return { ok: true, message: `${tasks.length} task(s) matched.`, tasks };
           }
-          const result = await splitTask(projectRoot, input.boardId, input.taskId, {
-            titles: input.childTitles,
-            ...input.targetColumnId !== void 0 ? { columnId: input.targetColumnId } : {},
-            ...input.inheritAssignment !== void 0 ? { inheritAssignment: input.inheritAssignment } : {},
-            ...input.inheritLabels !== void 0 ? { inheritLabels: input.inheritLabels } : {},
-            ...input.inheritSuccessCriteria !== void 0 ? { inheritSuccessCriteria: input.inheritSuccessCriteria } : {},
-            ...input.inheritGoalMetrics !== void 0 ? { inheritGoalMetrics: input.inheritGoalMetrics } : {},
-            ...input.inheritDependencies !== void 0 ? { inheritDependencies: input.inheritDependencies } : {},
-            ...input.chainChildren !== void 0 ? { chainChildren: input.chainChildren } : {},
-            ...input.rewireDependents !== void 0 ? { rewireDependents: input.rewireDependents } : {}
-          });
-          return result ? {
-            ok: true,
-            message: `${result.children.length} child task(s) created.`,
-            board: result.board,
-            task: result.parent,
-            children: result.children
-          } : fail("Task not found.");
-        }
-        case "merge_tasks": {
-          if (!input.boardId || !input.taskIds?.length || !input.title) {
-            return fail("merge_tasks requires boardId, taskIds, and title.");
+          case "ready_tasks": {
+            const tasks = await listReadyTasks(projectRoot, {
+              query: input.query,
+              boardId: input.boardId,
+              assignedAgent: input.agentId,
+              priority: input.priority,
+              label: input.labels?.[0],
+              chainId: input.chainId,
+              limit: input.limit
+            });
+            return { ok: true, message: `${tasks.length} ready task(s).`, tasks };
           }
-          const result = await mergeTasks(projectRoot, input.boardId, {
-            taskIds: input.taskIds,
-            title: input.title,
-            ...input.description !== void 0 ? { description: input.description } : {},
-            ...input.targetColumnId !== void 0 ? { targetColumnId: input.targetColumnId } : {},
-            ...input.preserveAssignment !== void 0 ? { preserveAssignment: input.preserveAssignment } : {},
-            ...input.closeSourceTasks !== void 0 ? { closeSourceTasks: input.closeSourceTasks } : {}
-          });
-          return result ? okTask(result.board, result.task, "Tasks merged.") : fail("Board or task not found.");
-        }
-        case "copy_task": {
-          if (!input.boardId || !input.taskId || !input.targetBoardId) {
-            return fail("copy_task requires boardId, taskId, and targetBoardId.");
+          case "snapshot": {
+            const snapshot = await getKanbanOrchestrationSnapshot(projectRoot, {
+              query: input.query,
+              boardId: input.boardId,
+              assignedAgent: input.agentId,
+              status: input.status,
+              priority: input.priority,
+              label: input.labels?.[0],
+              chainId: input.chainId
+            });
+            return {
+              ok: true,
+              message: `${snapshot.ready.length} ready, ${snapshot.running.length} running, ${snapshot.blocked.length} blocked.`,
+              snapshot
+            };
           }
-          const result = await copyTaskToBoard(
-            projectRoot,
-            input.boardId,
-            input.taskId,
-            input.targetBoardId,
-            {
-              ...input.targetColumnId !== void 0 ? { targetColumnId: input.targetColumnId } : {},
-              ...input.order !== void 0 ? { targetOrder: input.order } : {},
-              ...input.preserveAssignment !== void 0 ? { preserveAssignment: input.preserveAssignment } : {},
-              ...input.preserveDependencies !== void 0 ? { preserveDependencies: input.preserveDependencies } : {}
+          case "add_column": {
+            if (!input.boardId || !input.title) return fail("add_column requires boardId and title.");
+            const result2 = await addColumn(projectRoot, input.boardId, {
+              title: input.title,
+              ...input.description !== void 0 ? { description: input.description } : {}
+            });
+            return result2 ? okBoard(result2.board, "Column added.") : fail("Board not found.");
+          }
+          case "update_column": {
+            if (!input.boardId || !input.columnId)
+              return fail("update_column requires boardId and columnId.");
+            const board = await updateColumn(projectRoot, input.boardId, input.columnId, {
+              ...input.title !== void 0 ? { title: input.title } : {},
+              ...input.description !== void 0 ? { description: input.description } : {},
+              ...input.order !== void 0 ? { order: input.order } : {}
+            });
+            return board ? okBoard(board, "Column updated.") : fail("Column not found.");
+          }
+          case "delete_column": {
+            if (!input.boardId || !input.columnId)
+              return fail("delete_column requires boardId and columnId.");
+            const board = await removeColumn(projectRoot, input.boardId, input.columnId, {
+              moveTasksToColumnId: input.moveTasksToColumnId
+            });
+            return board ? okBoard(board, "Column deleted.") : fail("Column not found.");
+          }
+          case "add_task": {
+            if (!input.boardId || !input.title) return fail("add_task requires boardId and title.");
+            const result2 = await addTask(projectRoot, input.boardId, taskInput(input));
+            return result2 ? okTask(result2.board, result2.task, "Task added.") : fail("Board not found.");
+          }
+          case "split_task": {
+            if (!input.boardId || !input.taskId || !input.childTitles?.length) {
+              return fail("split_task requires boardId, taskId, and childTitles.");
             }
-          );
-          return result ? okTask(result.targetBoard, result.task, "Task copied to target board.") : fail("Board or task not found.");
-        }
-        case "transfer_task": {
-          if (!input.boardId || !input.taskId || !input.targetBoardId) {
-            return fail("transfer_task requires boardId, taskId, and targetBoardId.");
+            const result2 = await splitTask(projectRoot, input.boardId, input.taskId, {
+              titles: input.childTitles,
+              ...input.targetColumnId !== void 0 ? { columnId: input.targetColumnId } : {},
+              ...input.inheritAssignment !== void 0 ? { inheritAssignment: input.inheritAssignment } : {},
+              ...input.inheritLabels !== void 0 ? { inheritLabels: input.inheritLabels } : {},
+              ...input.inheritSuccessCriteria !== void 0 ? { inheritSuccessCriteria: input.inheritSuccessCriteria } : {},
+              ...input.inheritGoalMetrics !== void 0 ? { inheritGoalMetrics: input.inheritGoalMetrics } : {},
+              ...input.inheritDependencies !== void 0 ? { inheritDependencies: input.inheritDependencies } : {},
+              ...input.chainChildren !== void 0 ? { chainChildren: input.chainChildren } : {},
+              ...input.rewireDependents !== void 0 ? { rewireDependents: input.rewireDependents } : {}
+            });
+            return result2 ? {
+              ok: true,
+              message: `${result2.children.length} child task(s) created.`,
+              board: result2.board,
+              task: result2.parent,
+              children: result2.children
+            } : fail("Task not found.");
           }
-          const result = await transferTaskToBoard(
-            projectRoot,
-            input.boardId,
-            input.taskId,
-            input.targetBoardId,
-            {
+          case "merge_tasks": {
+            if (!input.boardId || !input.taskIds?.length || !input.title) {
+              return fail("merge_tasks requires boardId, taskIds, and title.");
+            }
+            const result2 = await mergeTasks(projectRoot, input.boardId, {
+              taskIds: input.taskIds,
+              title: input.title,
+              ...input.description !== void 0 ? { description: input.description } : {},
               ...input.targetColumnId !== void 0 ? { targetColumnId: input.targetColumnId } : {},
-              ...input.order !== void 0 ? { targetOrder: input.order } : {},
               ...input.preserveAssignment !== void 0 ? { preserveAssignment: input.preserveAssignment } : {},
-              ...input.preserveDependencies !== void 0 ? { preserveDependencies: input.preserveDependencies } : {}
+              ...input.closeSourceTasks !== void 0 ? { closeSourceTasks: input.closeSourceTasks } : {}
+            });
+            return result2 ? okTask(result2.board, result2.task, "Tasks merged.") : fail("Board or task not found.");
+          }
+          case "copy_task": {
+            if (!input.boardId || !input.taskId || !input.targetBoardId) {
+              return fail("copy_task requires boardId, taskId, and targetBoardId.");
             }
-          );
-          return result ? okTask(result.targetBoard, result.task, "Task transferred to target board.") : fail("Board or task not found.");
-        }
-        case "get_task": {
-          if (!input.boardId || !input.taskId) return fail("get_task requires boardId and taskId.");
-          const task = await getTask(projectRoot, input.boardId, input.taskId);
-          return task ? { ok: true, message: "Task loaded.", task } : fail("Task not found.");
-        }
-        case "update_task": {
-          if (!input.boardId || !input.taskId)
-            return fail("update_task requires boardId and taskId.");
-          const board = await updateTask(
-            projectRoot,
-            input.boardId,
-            input.taskId,
-            taskPatch(input)
-          );
-          return board ? okBoard(board, "Task updated.") : fail("Task not found.");
-        }
-        case "move_task": {
-          if (!input.boardId || !input.taskId || !input.targetColumnId) {
-            return fail("move_task requires boardId, taskId, and targetColumnId.");
+            const result2 = await copyTaskToBoard(
+              projectRoot,
+              input.boardId,
+              input.taskId,
+              input.targetBoardId,
+              {
+                ...input.targetColumnId !== void 0 ? { targetColumnId: input.targetColumnId } : {},
+                ...input.order !== void 0 ? { targetOrder: input.order } : {},
+                ...input.preserveAssignment !== void 0 ? { preserveAssignment: input.preserveAssignment } : {},
+                ...input.preserveDependencies !== void 0 ? { preserveDependencies: input.preserveDependencies } : {}
+              }
+            );
+            return result2 ? okTask(result2.targetBoard, result2.task, "Task copied to target board.") : fail("Board or task not found.");
           }
-          const board = await moveTask(
-            projectRoot,
-            input.boardId,
-            input.taskId,
-            input.targetColumnId,
-            input.order
-          );
-          return board ? okBoard(board, "Task moved.") : fail("Move failed.");
-        }
-        case "delete_task": {
-          if (!input.boardId || !input.taskId)
-            return fail("delete_task requires boardId and taskId.");
-          const board = await removeTask(projectRoot, input.boardId, input.taskId);
-          return board ? okBoard(board, "Task deleted.") : fail("Task not found.");
-        }
-        case "set_chain": {
-          if (!input.boardId || !input.taskIds?.length) {
-            return fail("set_chain requires boardId and taskIds.");
+          case "transfer_task": {
+            if (!input.boardId || !input.taskId || !input.targetBoardId) {
+              return fail("transfer_task requires boardId, taskId, and targetBoardId.");
+            }
+            const result2 = await transferTaskToBoard(
+              projectRoot,
+              input.boardId,
+              input.taskId,
+              input.targetBoardId,
+              {
+                ...input.targetColumnId !== void 0 ? { targetColumnId: input.targetColumnId } : {},
+                ...input.order !== void 0 ? { targetOrder: input.order } : {},
+                ...input.preserveAssignment !== void 0 ? { preserveAssignment: input.preserveAssignment } : {},
+                ...input.preserveDependencies !== void 0 ? { preserveDependencies: input.preserveDependencies } : {}
+              }
+            );
+            return result2 ? okTask(result2.targetBoard, result2.task, "Task transferred to target board.") : fail("Board or task not found.");
           }
-          const result = await setTaskChain(projectRoot, input.boardId, {
-            taskIds: input.taskIds,
-            ...input.chainId !== void 0 ? { chainId: input.chainId } : {},
-            ...input.enforceDependencies !== void 0 ? { enforceDependencies: input.enforceDependencies } : {}
-          });
-          return result ? {
-            ok: true,
-            message: `Chain set: ${result.chainId}`,
-            board: result.board,
-            chain: result.tasks
-          } : fail("Board or task not found.");
-        }
-        case "get_chain": {
-          if (!input.boardId || !(input.taskId || input.chainId)) {
-            return fail("get_chain requires boardId and taskId or chainId.");
+          case "get_task": {
+            if (!input.boardId || !input.taskId) return fail("get_task requires boardId and taskId.");
+            const task = await getTask(projectRoot, input.boardId, input.taskId);
+            return task ? { ok: true, message: "Task loaded.", task } : fail("Task not found.");
           }
-          const result = await getTaskChain(
-            projectRoot,
-            input.boardId,
-            input.taskId ?? input.chainId ?? ""
-          );
-          return result ? {
-            ok: true,
-            message: `Chain loaded: ${result.chainId}`,
-            board: result.board,
-            chain: result.tasks
-          } : fail("Chain not found.");
-        }
-        case "claim_task": {
-          const result = await claimReadyTask(projectRoot, {
-            ...input.boardId !== void 0 ? { boardId: input.boardId } : {},
-            ...input.taskId !== void 0 ? { taskId: input.taskId } : {},
-            ...assignmentInput(input),
-            status: input.assignmentStatus ?? "queued"
-          });
-          return result ? okTask(result.board, result.task, "Task claimed.") : fail("No ready kanban task matched the claim.");
-        }
-        case "release_task": {
-          if (!input.boardId || !input.taskId) {
-            return fail("release_task requires boardId and taskId.");
+          case "update_task": {
+            if (!input.boardId || !input.taskId)
+              return fail("update_task requires boardId and taskId.");
+            const board = await updateTask(
+              projectRoot,
+              input.boardId,
+              input.taskId,
+              taskPatch(input)
+            );
+            return board ? okBoard(board, "Task updated.") : fail("Task not found.");
           }
-          const board = await releaseTaskClaim(projectRoot, input.boardId, input.taskId, {
-            ...input.releaseStatus !== void 0 ? { status: input.releaseStatus } : {},
-            ...input.releaseReason !== void 0 ? { reason: input.releaseReason } : {},
-            ...input.clearAssignee !== void 0 ? { clearAssignee: input.clearAssignee } : {}
-          });
-          return board ? okBoard(board, "Task claim released.") : fail("Task not found.");
-        }
-        case "assign_task": {
-          if (!input.boardId || !input.taskId)
-            return fail("assign_task requires boardId and taskId.");
-          const board = await assignTask(
-            projectRoot,
-            input.boardId,
-            input.taskId,
-            assignmentInput(input)
-          );
-          return board ? okBoard(board, "Task assigned.") : fail("Task not found.");
-        }
-        case "mark_assignment": {
-          if (!input.boardId || !input.taskId)
-            return fail("mark_assignment requires boardId and taskId.");
-          const assignmentStatus = input.assignmentStatus ?? (input.status === "completed" ? "completed" : input.error ? "failed" : void 0);
-          const board = await updateTaskAssignment(projectRoot, input.boardId, input.taskId, {
-            ...assignmentStatus !== void 0 ? { status: assignmentStatus } : {},
-            ...input.subagentId !== void 0 ? { subagentId: input.subagentId } : {},
-            ...input.runTaskId !== void 0 ? { runTaskId: input.runTaskId } : {},
-            ...input.lastResult !== void 0 ? { lastResult: input.lastResult } : {},
-            ...input.error !== void 0 ? { error: input.error } : {},
-            ...input.agentId !== void 0 ? { agentId: input.agentId } : {},
-            ...input.leaseId !== void 0 ? { leaseId: input.leaseId } : {},
-            ...input.claimedAt !== void 0 ? { claimedAt: input.claimedAt } : {},
-            ...input.heartbeatAt !== void 0 ? { heartbeatAt: input.heartbeatAt } : {},
-            ...input.leaseExpiresAt !== void 0 ? { leaseExpiresAt: input.leaseExpiresAt } : {},
-            ...input.attempt !== void 0 ? { attempt: input.attempt } : {},
-            ...input.maxAttempts !== void 0 ? { maxAttempts: input.maxAttempts } : {}
-          });
-          return board ? okBoard(board, "Assignment updated.") : fail("Task not found.");
-        }
-        case "heartbeat_assignment": {
-          if (!input.boardId || !input.taskId) {
-            return fail("heartbeat_assignment requires boardId and taskId.");
+          case "transition_task": {
+            if (!input.boardId || !input.taskId || !input.lifecycleStage || !input.author || !input.transitionComment) {
+              return fail(
+                "transition_task requires boardId, taskId, lifecycleStage, author, and transitionComment."
+              );
+            }
+            const result2 = await transitionTask(projectRoot, input.boardId, input.taskId, {
+              to: input.lifecycleStage,
+              actor: input.author,
+              comment: input.transitionComment,
+              ...input.transitionAction !== void 0 ? { action: input.transitionAction } : {},
+              ...input.attachmentUrl !== void 0 ? {
+                attachment: {
+                  url: input.attachmentUrl,
+                  type: input.attachmentType ?? "url",
+                  ...input.attachmentTitle !== void 0 ? { title: input.attachmentTitle } : {}
+                }
+              } : {},
+              patch: taskPatch(input)
+            });
+            return result2 ? okTask(result2.board, result2.task, `Task advanced to ${result2.transition.to}.`) : fail("Board or task not found.");
           }
-          const board = await heartbeatTaskAssignment(projectRoot, input.boardId, input.taskId, {
-            ...input.heartbeatAt !== void 0 ? { heartbeatAt: input.heartbeatAt } : {},
-            ...input.leaseExpiresAt !== void 0 ? { leaseExpiresAt: input.leaseExpiresAt } : {}
-          });
-          return board ? okBoard(board, "Assignment heartbeat updated.") : fail("Task assignment not found.");
-        }
-        case "recover_stale": {
-          if (!input.boardId) return fail("recover_stale requires boardId.");
-          const policyFields = [
-            input.recoveryPolicyFailOnCostCeiling !== void 0,
-            input.recoveryPolicyReleaseOnFailureKinds !== void 0,
-            input.recoveryPolicyReleaseOnHeartbeatDue !== void 0,
-            input.recoveryPolicyRetryPolicyOverride !== void 0
-          ].some(Boolean);
-          const result = await recoverStaleTaskAssignments(projectRoot, input.boardId, {
-            ...input.recoveryMode !== void 0 ? { mode: input.recoveryMode } : {},
-            ...input.recoveryNow !== void 0 ? { now: input.recoveryNow } : {},
-            ...input.releaseReason !== void 0 ? { reason: input.releaseReason } : {},
-            ...input.clearAssignee !== void 0 ? { clearAssignee: input.clearAssignee } : {},
-            ...policyFields ? {
-              policy: {
-                ...input.recoveryPolicyFailOnCostCeiling !== void 0 ? { failWhenCostCeilingSet: input.recoveryPolicyFailOnCostCeiling } : {},
-                ...input.recoveryPolicyReleaseOnFailureKinds !== void 0 ? {
-                  releaseOnFailureKinds: input.recoveryPolicyReleaseOnFailureKinds
-                } : {},
-                ...input.recoveryPolicyReleaseOnHeartbeatDue !== void 0 ? {
-                  releaseOnHeartbeatDue: input.recoveryPolicyReleaseOnHeartbeatDue
-                } : {},
-                ...input.recoveryPolicyRetryPolicyOverride !== void 0 ? {
-                  retryPolicyOverride: input.recoveryPolicyRetryPolicyOverride
-                } : {}
-              }
-            } : {}
-          });
-          return result ? {
-            ok: true,
-            message: `Recovered ${result.tasks.length} stale assignment(s).`,
-            board: result.board,
-            recoveredTasks: result.tasks
-          } : { ok: true, message: "No stale assignment matched.", recoveredTasks: [] };
-        }
-        case "events": {
-          if (!input.boardId) return fail("events requires boardId.");
-          const eventList = await listKanbanEvents(projectRoot, input.boardId);
-          return {
-            ok: true,
-            message: `${eventList.length} event(s).`,
-            events: eventList
-          };
-        }
-        case "queue_health": {
-          const health = await getKanbanQueueHealth(projectRoot, {
-            ...input.boardId !== void 0 ? { boardId: input.boardId } : {}
-          });
-          return {
-            ok: true,
-            message: `Counts: ready=${health.counts.ready}, running=${health.counts.running}, stale=${health.staleAssignments.count}.`,
-            queueHealth: health
-          };
-        }
-        case "add_dependency": {
-          if (!input.boardId || !input.taskId || !input.dependencyTaskId) {
-            return fail("add_dependency requires boardId, taskId, and dependencyTaskId.");
+          case "move_task": {
+            if (!input.boardId || !input.taskId || !input.targetColumnId) {
+              return fail("move_task requires boardId, taskId, and targetColumnId.");
+            }
+            const board = await moveTask(
+              projectRoot,
+              input.boardId,
+              input.taskId,
+              input.targetColumnId,
+              input.order
+            );
+            return board ? okBoard(board, "Task moved.") : fail("Move failed.");
           }
-          const board = await addDependency(
-            projectRoot,
-            input.boardId,
-            input.taskId,
-            input.dependencyTaskId
-          );
-          return board ? okBoard(board, "Dependency added.") : fail("Task not found.");
-        }
-        case "add_goal_metric": {
-          if (!input.boardId || !input.taskId || !input.metricName) {
-            return fail("add_goal_metric requires boardId, taskId, and metricName.");
+          case "delete_task": {
+            if (!input.boardId || !input.taskId)
+              return fail("delete_task requires boardId and taskId.");
+            const board = await removeTask(projectRoot, input.boardId, input.taskId);
+            return board ? okBoard(board, "Task deleted.") : fail("Task not found.");
           }
-          const board = await addGoalMetricToTask(projectRoot, input.boardId, input.taskId, {
-            name: input.metricName,
-            ...input.metricStatus !== void 0 ? { status: input.metricStatus } : {},
-            ...input.metricTarget !== void 0 ? { target: input.metricTarget } : {},
-            ...input.metricCurrent !== void 0 ? { current: input.metricCurrent } : {},
-            ...input.metricUnit !== void 0 ? { unit: input.metricUnit } : {},
-            ...input.metricNotes !== void 0 ? { notes: input.metricNotes } : {}
-          });
-          return board ? okBoard(board, "Goal metric added.") : fail("Task not found.");
-        }
-        case "update_goal_metric": {
-          if (!input.boardId || !input.taskId || !input.metricId) {
-            return fail("update_goal_metric requires boardId, taskId, and metricId.");
+          case "set_chain": {
+            if (!input.boardId || !input.taskIds?.length) {
+              return fail("set_chain requires boardId and taskIds.");
+            }
+            const result2 = await setTaskChain(projectRoot, input.boardId, {
+              taskIds: input.taskIds,
+              ...input.chainId !== void 0 ? { chainId: input.chainId } : {},
+              ...input.enforceDependencies !== void 0 ? { enforceDependencies: input.enforceDependencies } : {}
+            });
+            return result2 ? {
+              ok: true,
+              message: `Chain set: ${result2.chainId}`,
+              board: result2.board,
+              chain: result2.tasks
+            } : fail("Board or task not found.");
           }
-          const board = await updateGoalMetricOnTask(
-            projectRoot,
-            input.boardId,
-            input.taskId,
-            input.metricId,
-            {
-              ...input.metricName !== void 0 ? { name: input.metricName } : {},
+          case "get_chain": {
+            if (!input.boardId || !(input.taskId || input.chainId)) {
+              return fail("get_chain requires boardId and taskId or chainId.");
+            }
+            const result2 = await getTaskChain(
+              projectRoot,
+              input.boardId,
+              input.taskId ?? input.chainId ?? ""
+            );
+            return result2 ? {
+              ok: true,
+              message: `Chain loaded: ${result2.chainId}`,
+              board: result2.board,
+              chain: result2.tasks
+            } : fail("Chain not found.");
+          }
+          case "claim_task": {
+            const result2 = await claimReadyTask(projectRoot, {
+              ...input.boardId !== void 0 ? { boardId: input.boardId } : {},
+              ...input.taskId !== void 0 ? { taskId: input.taskId } : {},
+              ...assignmentInput(input),
+              status: input.assignmentStatus ?? "queued"
+            });
+            return result2 ? okTask(result2.board, result2.task, "Task claimed.") : fail("No ready kanban task matched the claim.");
+          }
+          case "release_task": {
+            if (!input.boardId || !input.taskId) {
+              return fail("release_task requires boardId and taskId.");
+            }
+            const board = await releaseTaskClaim(projectRoot, input.boardId, input.taskId, {
+              ...input.releaseStatus !== void 0 ? { status: input.releaseStatus } : {},
+              ...input.releaseReason !== void 0 ? { reason: input.releaseReason } : {},
+              ...input.clearAssignee !== void 0 ? { clearAssignee: input.clearAssignee } : {}
+            });
+            return board ? okBoard(board, "Task claim released.") : fail("Task not found.");
+          }
+          case "assign_task": {
+            if (!input.boardId || !input.taskId)
+              return fail("assign_task requires boardId and taskId.");
+            const board = await assignTask(
+              projectRoot,
+              input.boardId,
+              input.taskId,
+              assignmentInput(input)
+            );
+            return board ? okBoard(board, "Task assigned.") : fail("Task not found.");
+          }
+          case "mark_assignment": {
+            if (!input.boardId || !input.taskId)
+              return fail("mark_assignment requires boardId and taskId.");
+            const assignmentStatus = input.assignmentStatus ?? (input.status === "completed" ? "completed" : input.error ? "failed" : void 0);
+            const board = await updateTaskAssignment(
+              projectRoot,
+              input.boardId,
+              input.taskId,
+              {
+                ...assignmentStatus !== void 0 ? { status: assignmentStatus } : {},
+                ...input.subagentId !== void 0 ? { subagentId: input.subagentId } : {},
+                ...input.runTaskId !== void 0 ? { runTaskId: input.runTaskId } : {},
+                ...input.lastResult !== void 0 ? { lastResult: input.lastResult } : {},
+                ...input.error !== void 0 ? { error: input.error } : {},
+                ...input.agentId !== void 0 ? { agentId: input.agentId } : {},
+                ...input.leaseId !== void 0 ? { leaseId: input.leaseId } : {},
+                ...input.claimedAt !== void 0 ? { claimedAt: input.claimedAt } : {},
+                ...input.heartbeatAt !== void 0 ? { heartbeatAt: input.heartbeatAt } : {},
+                ...input.leaseExpiresAt !== void 0 ? { leaseExpiresAt: input.leaseExpiresAt } : {},
+                ...input.attempt !== void 0 ? { attempt: input.attempt } : {},
+                ...input.maxAttempts !== void 0 ? { maxAttempts: input.maxAttempts } : {}
+              },
+              // Ownership fence: when expectedLeaseId is supplied, the write is
+              // applied only if the current assignment still holds this lease.
+              // This prevents a recovered+reassigned stale worker's terminal
+              // mark_assignment from overwriting the successor's state. The check
+              // is atomic inside updateTaskAssignment's mutateBoard lock.
+              input.expectedLeaseId !== void 0 ? { expectedLeaseId: input.expectedLeaseId } : {}
+            );
+            return board ? okBoard(board, "Assignment updated.") : fail("Task not found.");
+          }
+          case "heartbeat_assignment": {
+            if (!input.boardId || !input.taskId) {
+              return fail("heartbeat_assignment requires boardId and taskId.");
+            }
+            const board = await heartbeatTaskAssignment(projectRoot, input.boardId, input.taskId, {
+              ...input.heartbeatAt !== void 0 ? { heartbeatAt: input.heartbeatAt } : {},
+              ...input.leaseExpiresAt !== void 0 ? { leaseExpiresAt: input.leaseExpiresAt } : {},
+              // Ownership fence: when expectedLeaseId is supplied, the renewal
+              // is applied only if the current assignment still holds this lease.
+              // This prevents a recovered+reassigned stale worker's heartbeat
+              // from renewing the successor's lease. The check is atomic inside
+              // heartbeatTaskAssignment's mutateBoard lock.
+              ...input.expectedLeaseId !== void 0 ? { expectedLeaseId: input.expectedLeaseId } : {}
+            });
+            return board ? okBoard(board, "Assignment heartbeat updated.") : fail("Task assignment not found.");
+          }
+          case "recover_stale": {
+            if (!input.boardId) return fail("recover_stale requires boardId.");
+            const policyFields = [
+              input.recoveryPolicyFailOnCostCeiling !== void 0,
+              input.recoveryPolicyReleaseOnFailureKinds !== void 0,
+              input.recoveryPolicyReleaseOnHeartbeatDue !== void 0,
+              input.recoveryPolicyRetryPolicyOverride !== void 0
+            ].some(Boolean);
+            const result2 = await recoverStaleTaskAssignments(projectRoot, input.boardId, {
+              ...input.recoveryMode !== void 0 ? { mode: input.recoveryMode } : {},
+              ...input.recoveryNow !== void 0 ? { now: input.recoveryNow } : {},
+              ...input.releaseReason !== void 0 ? { reason: input.releaseReason } : {},
+              ...input.clearAssignee !== void 0 ? { clearAssignee: input.clearAssignee } : {},
+              ...policyFields ? {
+                policy: {
+                  ...input.recoveryPolicyFailOnCostCeiling !== void 0 ? { failWhenCostCeilingSet: input.recoveryPolicyFailOnCostCeiling } : {},
+                  ...input.recoveryPolicyReleaseOnFailureKinds !== void 0 ? {
+                    releaseOnFailureKinds: input.recoveryPolicyReleaseOnFailureKinds
+                  } : {},
+                  ...input.recoveryPolicyReleaseOnHeartbeatDue !== void 0 ? {
+                    releaseOnHeartbeatDue: input.recoveryPolicyReleaseOnHeartbeatDue
+                  } : {},
+                  ...input.recoveryPolicyRetryPolicyOverride !== void 0 ? {
+                    retryPolicyOverride: input.recoveryPolicyRetryPolicyOverride
+                  } : {}
+                }
+              } : {}
+            });
+            return result2 ? {
+              ok: true,
+              message: `Recovered ${result2.tasks.length} stale assignment(s).`,
+              board: result2.board,
+              recoveredTasks: result2.tasks
+            } : { ok: true, message: "No stale assignment matched.", recoveredTasks: [] };
+          }
+          case "events": {
+            if (!input.boardId) return fail("events requires boardId.");
+            const eventList = await listKanbanEvents(projectRoot, input.boardId);
+            return {
+              ok: true,
+              message: `${eventList.length} event(s).`,
+              events: eventList
+            };
+          }
+          case "queue_health": {
+            const health = await getKanbanQueueHealth(projectRoot, {
+              ...input.boardId !== void 0 ? { boardId: input.boardId } : {}
+            });
+            return {
+              ok: true,
+              message: `Counts: ready=${health.counts.ready}, running=${health.counts.running}, stale=${health.staleAssignments.count}.`,
+              queueHealth: health
+            };
+          }
+          case "add_dependency": {
+            if (!input.boardId || !input.taskId || !input.dependencyTaskId) {
+              return fail("add_dependency requires boardId, taskId, and dependencyTaskId.");
+            }
+            const board = await addDependency(
+              projectRoot,
+              input.boardId,
+              input.taskId,
+              input.dependencyTaskId
+            );
+            return board ? okBoard(board, "Dependency added.") : fail("Task not found.");
+          }
+          case "add_goal_metric": {
+            if (!input.boardId || !input.taskId || !input.metricName) {
+              return fail("add_goal_metric requires boardId, taskId, and metricName.");
+            }
+            const board = await addGoalMetricToTask(projectRoot, input.boardId, input.taskId, {
+              name: input.metricName,
               ...input.metricStatus !== void 0 ? { status: input.metricStatus } : {},
               ...input.metricTarget !== void 0 ? { target: input.metricTarget } : {},
               ...input.metricCurrent !== void 0 ? { current: input.metricCurrent } : {},
               ...input.metricUnit !== void 0 ? { unit: input.metricUnit } : {},
               ...input.metricNotes !== void 0 ? { notes: input.metricNotes } : {}
+            });
+            return board ? okBoard(board, "Goal metric added.") : fail("Task not found.");
+          }
+          case "update_goal_metric": {
+            if (!input.boardId || !input.taskId || !input.metricId) {
+              return fail("update_goal_metric requires boardId, taskId, and metricId.");
             }
-          );
-          return board ? okBoard(board, "Goal metric updated.") : fail("Metric not found.");
-        }
-        case "add_check": {
-          if (!input.boardId || !input.taskId || !input.checkDescription) {
-            return fail("add_check requires boardId, taskId, and checkDescription.");
+            const board = await updateGoalMetricOnTask(
+              projectRoot,
+              input.boardId,
+              input.taskId,
+              input.metricId,
+              {
+                ...input.metricName !== void 0 ? { name: input.metricName } : {},
+                ...input.metricStatus !== void 0 ? { status: input.metricStatus } : {},
+                ...input.metricTarget !== void 0 ? { target: input.metricTarget } : {},
+                ...input.metricCurrent !== void 0 ? { current: input.metricCurrent } : {},
+                ...input.metricUnit !== void 0 ? { unit: input.metricUnit } : {},
+                ...input.metricNotes !== void 0 ? { notes: input.metricNotes } : {}
+              }
+            );
+            return board ? okBoard(board, "Goal metric updated.") : fail("Metric not found.");
           }
-          const board = await addCheckToTask(projectRoot, input.boardId, input.taskId, {
-            description: input.checkDescription,
-            type: "manual",
-            status: input.checkStatus
-          });
-          return board ? okBoard(board, "Check added.") : fail("Task not found.");
-        }
-        case "update_check": {
-          if (!input.boardId || !input.taskId || !input.checkId) {
-            return fail("update_check requires boardId, taskId, and checkId.");
+          case "add_check": {
+            if (!input.boardId || !input.taskId || !input.checkDescription) {
+              return fail("add_check requires boardId, taskId, and checkDescription.");
+            }
+            const board = await addCheckToTask(projectRoot, input.boardId, input.taskId, {
+              description: input.checkDescription,
+              type: "manual",
+              status: input.checkStatus
+            });
+            return board ? okBoard(board, "Check added.") : fail("Task not found.");
           }
-          const board = await updateCheckOnTask(
-            projectRoot,
-            input.boardId,
-            input.taskId,
-            input.checkId,
-            {
-              ...input.checkDescription !== void 0 ? { description: input.checkDescription } : {},
-              ...input.checkStatus !== void 0 ? { status: input.checkStatus } : {}
+          case "update_check": {
+            if (!input.boardId || !input.taskId || !input.checkId) {
+              return fail("update_check requires boardId, taskId, and checkId.");
             }
-          );
-          return board ? okBoard(board, "Check updated.") : fail("Check not found.");
-        }
-        case "add_note": {
-          if (!input.boardId || !input.taskId || !input.note)
-            return fail("add_note requires boardId, taskId, and note.");
-          const board = await addNoteToTask(projectRoot, input.boardId, input.taskId, {
-            author: input.author ?? "agent",
-            content: input.note
-          });
-          return board ? okBoard(board, "Note added.") : fail("Task not found.");
-        }
-        case "add_link": {
-          if (!input.boardId || !input.taskId || !input.url)
-            return fail("add_link requires boardId, taskId, and url.");
-          const board = await addLinkToTask(projectRoot, input.boardId, input.taskId, {
-            url: input.url,
-            type: input.linkType ?? "url",
-            ...input.linkTitle !== void 0 ? { title: input.linkTitle } : {}
-          });
-          return board ? okBoard(board, "Link added.") : fail("Task not found.");
+            const board = await updateCheckOnTask(
+              projectRoot,
+              input.boardId,
+              input.taskId,
+              input.checkId,
+              {
+                ...input.checkDescription !== void 0 ? { description: input.checkDescription } : {},
+                ...input.checkStatus !== void 0 ? { status: input.checkStatus } : {}
+              }
+            );
+            return board ? okBoard(board, "Check updated.") : fail("Check not found.");
+          }
+          case "add_note": {
+            if (!input.boardId || !input.taskId || !input.note)
+              return fail("add_note requires boardId, taskId, and note.");
+            const board = await addNoteToTask(projectRoot, input.boardId, input.taskId, {
+              author: input.author ?? "agent",
+              content: input.note
+            });
+            return board ? okBoard(board, "Note added.") : fail("Task not found.");
+          }
+          case "add_link": {
+            if (!input.boardId || !input.taskId || !input.url)
+              return fail("add_link requires boardId, taskId, and url.");
+            const board = await addLinkToTask(projectRoot, input.boardId, input.taskId, {
+              url: input.url,
+              type: input.linkType ?? "url",
+              ...input.linkTitle !== void 0 ? { title: input.linkTitle } : {}
+            });
+            return board ? okBoard(board, "Link added.") : fail("Task not found.");
+          }
+          default:
+            return fail(`Unknown kanban action: ${input.action}`);
         }
-        default:
-          return fail(`Unknown kanban action: ${input.action}`);
-      }
+      })();
+      return withPresence(result);
     } catch (err) {
       return fail(err instanceof Error ? err.message : String(err));
     }
@@ -16449,6 +17292,7 @@ function taskInput(input) {
     title: input.title ?? "",
     columnId: input.columnId,
     description: input.description,
+    dueDate: input.dueDate,
     priority: input.priority,
     ...input.taskType !== void 0 ? { type: input.taskType } : {},
     status: input.status,
@@ -16457,7 +17301,67 @@ function taskInput(input) {
     ...input.assignee ?? assignment?.name ?? assignment?.agentId ? { assignee: input.assignee ?? assignment?.name ?? assignment?.agentId } : {},
     ...mergedDependsOn(input) ? { dependsOn: mergedDependsOn(input) } : {},
     ...input.estimatedHours !== void 0 ? { estimatedHours: input.estimatedHours } : {},
-    ...assignment ? { assignment } : {}
+    ...input.actualHours !== void 0 ? { actualHours: input.actualHours } : {},
+    ...assignment ? { assignment } : {},
+    ...input.order !== void 0 ? { order: input.order } : {},
+    // Sprint 3 durable task-level fields
+    ...input.retryPolicy !== void 0 ? { retryPolicy: input.retryPolicy } : {},
+    ...input.costCeilingUsd !== void 0 ? { costCeilingUsd: input.costCeilingUsd } : {},
+    // Relationships — chainId alone cannot construct a KanbanTaskChainRef,
+    // so chain/previousTaskId/nextTaskId must be set via update_task.
+    ...input.childTitles !== void 0 ? { childTaskIds: input.childTitles } : {},
+    // Detail objects
+    ...input.checkDescription !== void 0 ? {
+      successCriteria: [
+        {
+          id: randomUUID(),
+          description: input.checkDescription,
+          type: "manual",
+          status: input.checkStatus ?? "pending"
+        }
+      ]
+    } : {},
+    ...input.metricName !== void 0 ? {
+      goalMetrics: [
+        {
+          id: randomUUID(),
+          name: input.metricName,
+          status: input.metricStatus ?? "pending",
+          ...input.metricTarget !== void 0 ? { target: input.metricTarget } : {},
+          ...input.metricCurrent !== void 0 ? { current: input.metricCurrent } : {},
+          ...input.metricUnit !== void 0 ? { unit: input.metricUnit } : {},
+          ...input.metricNotes !== void 0 ? { notes: input.metricNotes } : {}
+        }
+      ]
+    } : {},
+    ...input.url !== void 0 ? {
+      links: [
+        {
+          url: input.url,
+          type: input.linkType ?? "url",
+          ...input.linkTitle !== void 0 ? { title: input.linkTitle } : {}
+        }
+      ]
+    } : {},
+    ...input.note !== void 0 ? {
+      notes: [
+        {
+          id: randomUUID(),
+          author: input.author ?? "agent",
+          content: input.note,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      ]
+    } : {},
+    // Origin tracking
+    ...input.graphId !== void 0 ? {
+      origin: {
+        system: input.sourceSystem ?? "kanban-tool",
+        ...input.graphId !== void 0 ? { graphId: input.graphId } : {},
+        ...input.specId !== void 0 ? { specId: input.specId } : {},
+        ...input.phaseId !== void 0 ? { phaseId: input.phaseId } : {}
+      }
+    } : {}
   };
 }
 function mergedDependsOn(input) {
@@ -16471,6 +17375,7 @@ function taskPatch(input) {
   return {
     title: input.title,
     description: input.description,
+    dueDate: input.dueDate,
     columnId: input.columnId,
     order: input.order,
     priority: input.priority,
@@ -17232,7 +18137,7 @@ import {
   mutateTasks as mutateTasks2,
   formatTaskList
 } from "@wrongstack/core";
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID2 } from "node:crypto";
 var planTool = {
   name: "plan",
   category: "Session",
@@ -17458,7 +18363,7 @@ var planTool = {
       try {
         const taskFile = await mutateTasks2(taskPath, sessionId, (f) => {
           f.tasks.push({
-            id: `task_${randomUUID()}`,
+            id: `task_${randomUUID2()}`,
             title: taskifyMeta.title,
             description: taskifyMeta.details || void 0,
             type: "feature",
@@ -18600,7 +19505,7 @@ import {
   mutatePlan as mutatePlan3,
   formatPlan as formatPlan2
 } from "@wrongstack/core";
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 function findTaskIndex(tasks, query) {
   const asNum = Number.parseInt(query, 10);
   if (!Number.isNaN(asNum)) {
@@ -18788,7 +19693,7 @@ var taskTool = {
             }
             const now = (/* @__PURE__ */ new Date()).toISOString();
             const newTask = {
-              id: `task_${Date.now()}_${randomUUID2().slice(0, 8)}`,
+              id: `task_${Date.now()}_${randomUUID3().slice(0, 8)}`,
               title: t.title,
               description: t.description,
               type: t.type || "feature",
@@ -18849,7 +19754,7 @@ var taskTool = {
             });
             if (match.description) {
               todos.push({
-                id: `todo_${ts2}_${randomUUID2().slice(0, 6)}`,
+                id: `todo_${ts2}_${randomUUID3().slice(0, 6)}`,
                 content: match.description.slice(0, 200),
                 status: "pending",
                 promotedFromTask: match.id
@@ -18858,7 +19763,7 @@ var taskTool = {
             if (input.subtasks && input.subtasks.length > 0) {
               for (const st of input.subtasks) {
                 todos.push({
-                  id: `todo_${ts2}_${randomUUID2().slice(0, 6)}`,
+                  id: `todo_${ts2}_${randomUUID3().slice(0, 6)}`,
                   content: st,
                   status: "pending",
                   promotedFromTask: match.id
@@ -19564,8 +20469,8 @@ var DEFAULT_IGNORE5 = [
 var treeTool = {
   name: "tree",
   category: "Filesystem",
-  description: "Display a directory tree of the project (or a subpath). This is the recommended way to explore the high-level structure of a codebase before reading specific files.",
-  usageHint: "BEST PRACTICE FOR INITIAL EXPLORATION:\n\n- Call early when working with an unfamiliar project or module.\n- Tune `depth` (default 3) and use `glob`/`exclude` to focus the view.\n- Prefer this over raw `bash find` or `glob` + manual reading when you need a quick structural overview.\nOutput is truncated for very large trees.",
+  description: "Display a project or subpath directory tree. Use it for structural layout; use index-backed `codebase-search` first for code understanding when it is live.",
+  usageHint: "DIRECTORY-LAYOUT EXPLORATION:\n\n- When `codebase-search` is live, use it first for symbols and concepts; use `tree` when the directory hierarchy itself matters.\n- Tune `depth` (default 3) and use `glob`/`exclude` to focus the view.\n- Prefer this over raw `bash find` or `glob` + manual reading when you need a quick structural overview.\nOutput is truncated for very large trees.",
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
@@ -19968,15 +20873,15 @@ var OPTIONAL_TOOLS = [
   toolUseTool,
   batchToolUseTool,
   toolHelpTool,
-  codebaseIndexTool,
-  codebaseSearchTool,
-  codebaseStatsTool,
   setWorkingDirTool
 ];
 var TIER1_TOOLS = [
   readTool,
   writeTool,
   editTool,
+  codebaseStatsTool,
+  codebaseSearchTool,
+  codebaseIndexTool,
   bashTool,
   grepTool,
   globTool,
@@ -20015,9 +20920,6 @@ var TIER3_TOOLS = [
   toolUseTool,
   batchToolUseTool,
   toolHelpTool,
-  codebaseIndexTool,
-  codebaseSearchTool,
-  codebaseStatsTool,
   setWorkingDirTool
 ];
 var builtinTools = [
@@ -20026,6 +20928,9 @@ var builtinTools = [
   readTool,
   writeTool,
   editTool,
+  codebaseStatsTool,
+  codebaseSearchTool,
+  codebaseIndexTool,
   replaceTool,
   globTool,
   grepTool,
@@ -20060,9 +20965,6 @@ var builtinTools = [
   toolUseTool,
   batchToolUseTool,
   toolHelpTool,
-  codebaseIndexTool,
-  codebaseSearchTool,
-  codebaseStatsTool,
   setWorkingDirTool
 ];
 export {