flavor-code 1.3.12 → 1.3.13

package/dist/{chunk-QC5OYQTB.js → chunk-W2D2MLY2.js}

@@ -66,12 +66,12 @@ function normalizeProviderError(error) {
 
 // src/utils/async.ts
 function withTimeout(promise, ms) {
-  return new Promise((resolve28, reject) => {
+  return new Promise((resolve29, reject) => {
     let settled = false;
     const timer = setTimeout(() => {
       if (settled) return;
       settled = true;
-      resolve28({ timedOut: true, value: void 0 });
+      resolve29({ timedOut: true, value: void 0 });
     }, ms);
     timer.unref?.();
     promise.then(
@@ -79,7 +79,7 @@ function withTimeout(promise, ms) {
         if (!settled) {
           settled = true;
           clearTimeout(timer);
-          resolve28({ timedOut: false, value });
+          resolve29({ timedOut: false, value });
         }
       },
       (error) => {
@@ -94,13 +94,13 @@ function withTimeout(promise, ms) {
 }
 function awaitWithSignal(promise, signal) {
   signal.throwIfAborted();
-  return new Promise((resolve28, reject) => {
+  return new Promise((resolve29, reject) => {
     const onAbort = () => reject(signal.reason);
     signal.addEventListener("abort", onAbort, { once: true });
     promise.then(
       (value) => {
         signal.removeEventListener("abort", onAbort);
-        resolve28(value);
+        resolve29(value);
       },
       (error) => {
         signal.removeEventListener("abort", onAbort);
@@ -3224,6 +3224,7 @@ var MVP_COMMANDS = [
   "mcp",
   "commit",
   "review",
+  "explain",
   "ide",
   "memory",
   "remember",
@@ -3262,6 +3263,7 @@ var COMMAND_DESCRIPTIONS = {
   evolve: "Self-improvement loop: capture failures, suggest fixes, verify with tests",
   commit: "Generate a commit message for staged changes and commit after confirmation",
   review: "Review uncommitted changes for bugs and risks before committing",
+  explain: "Explain a symbol for newcomers (AST graph + source + git history)",
   mcp: "Manage MCP servers",
   ide: "Show the connected IDE and editor context",
   memory: "Show long-term project memory",
@@ -3338,6 +3340,12 @@ function parseSlashCommand(input, dynamicCommands = [], skillCommands = [], mana
     const focus = args.join(" ").trim();
     return focus.length === 0 ? { name } : { name, focus };
   }
+  if (name === "explain") {
+    const [query, ...focusParts] = args;
+    if (query === void 0) return { name };
+    const focus = focusParts.join(" ").trim();
+    return focus.length === 0 ? { name, query } : { name, query, focus };
+  }
   if (name === "loop") {
     const goal = args.join(" ").trim();
     if (!goal) return { name: "invalid", command: name, message: "Use /loop <goal>." };
@@ -3941,6 +3949,14 @@ var FlavorSession = class {
       this.#notice(await required(this.#services.gitCommit, "commit")(command.hint, signal));
     } else if (command.name === "review") {
       this.#notice(await required(this.#services.gitReview, "review")(command.focus, signal));
+    } else if (command.name === "explain") {
+      const result = await required(this.#services.explain, "explain")(
+        command.query,
+        command.focus,
+        signal,
+        (chunk) => this.#services.output({ type: "text", text: chunk })
+      );
+      if (result !== "") this.#notice(result);
     } else if (command.name === "mcp") {
       this.#notice(await this.#services.mcp(command, signal));
     } else if (command.name === "pals") {
@@ -4107,9 +4123,9 @@ var FlavorSession = class {
   }
   #waitForPlanningIdle(key) {
     if (!this.#activePlanning.has(key)) return Promise.resolve();
-    return new Promise((resolve28) => {
+    return new Promise((resolve29) => {
       const check = () => {
-        if (!this.#activePlanning.has(key)) resolve28();
+        if (!this.#activePlanning.has(key)) resolve29();
         else this.#planningIdleWaiters.add(check);
       };
       this.#planningIdleWaiters.add(check);
@@ -4457,12 +4473,12 @@ var BrokerStateError = class extends Error {
 };
 var WINDOWS_PIPE_PREFIX = "\\\\.\\pipe\\";
 function canConnect(address) {
-  return new Promise((resolve28) => {
+  return new Promise((resolve29) => {
     const socket = new Socket();
     const finish = (connected) => {
       socket.removeAllListeners();
       socket.destroy();
-      resolve28(connected);
+      resolve29(connected);
     };
     socket.once("connect", () => finish(true));
     socket.once("error", () => finish(false));
@@ -4511,7 +4527,7 @@ var PalBrokerServer = class {
     this.authToken ??= await loadOrCreatePalAuthToken(this.authHome === void 0 ? {} : { home: this.authHome });
     try {
       await this.prepareAddress();
-      await new Promise((resolve28, reject) => {
+      await new Promise((resolve29, reject) => {
         const onError = (error) => {
           this.server.off("listening", onListening);
           reject(error);
@@ -4520,7 +4536,7 @@ var PalBrokerServer = class {
           this.server.off("error", onError);
           this.started = true;
           this.ownsAddress = true;
-          resolve28();
+          resolve29();
         };
         this.server.once("error", onError);
         this.server.once("listening", onListening);
@@ -4548,7 +4564,7 @@ var PalBrokerServer = class {
     const ownsAddress = this.ownsAddress;
     for (const connection of this.connections) connection.socket.destroy();
     if (this.started) {
-      await new Promise((resolve28) => this.server.close(() => resolve28()));
+      await new Promise((resolve29) => this.server.close(() => resolve29()));
       this.started = false;
     }
     this.ownsAddress = false;
@@ -4567,8 +4583,8 @@ var PalBrokerServer = class {
     });
     if (this.endpointLock === void 0) throw new Error(`Pals endpoint '${this.address}' is active or owned`);
     try {
-      const stat9 = await lstat3(this.address);
-      if (!stat9.isSocket()) throw new Error(`Refusing to unlink '${this.address}' because it is not a socket`);
+      const stat10 = await lstat3(this.address);
+      if (!stat10.isSocket()) throw new Error(`Refusing to unlink '${this.address}' because it is not a socket`);
       await unlink3(this.address);
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
@@ -4581,8 +4597,8 @@ var PalBrokerServer = class {
   }
   async unlinkKnownSocket() {
     try {
-      const stat9 = await lstat3(this.address);
-      if (stat9.isSocket()) await unlink3(this.address);
+      const stat10 = await lstat3(this.address);
+      if (stat10.isSocket()) await unlink3(this.address);
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
     }
@@ -5217,15 +5233,15 @@ var PalBrokerState = class {
 // src/pals/broker-cli.ts
 var startupAttempts = /* @__PURE__ */ new Map();
 function delay(milliseconds) {
-  return new Promise((resolve28) => setTimeout(resolve28, milliseconds));
+  return new Promise((resolve29) => setTimeout(resolve29, milliseconds));
 }
 function canConnect2(address) {
-  return new Promise((resolve28) => {
+  return new Promise((resolve29) => {
     const socket = new Socket2();
     const finish = (connected) => {
       socket.removeAllListeners();
       socket.destroy();
-      resolve28(connected);
+      resolve29(connected);
     };
     socket.once("connect", () => finish(true));
     socket.once("error", () => finish(false));
@@ -5268,8 +5284,8 @@ async function runPalBroker(options) {
   const sweepIntervalMs = options.sweepIntervalMs ?? 5e3;
   const idleShutdownMs = options.idleShutdownMs ?? 3e4;
   let resolveClosed;
-  const closed = new Promise((resolve28) => {
-    resolveClosed = resolve28;
+  const closed = new Promise((resolve29) => {
+    resolveClosed = resolve29;
   });
   let closing;
   const timer = setInterval(() => {
@@ -5312,7 +5328,7 @@ async function ensureOnce(options) {
 import { readFile as readFile22 } from "fs/promises";
 import { createHash as createHash18, randomUUID as randomUUID20 } from "crypto";
 import { homedir as homedir2, release as osRelease, tmpdir as tmpdir4, version as osVersion } from "os";
-import { basename as basename6, join as join25, relative as relative20, resolve as resolve27, sep as sep20 } from "path";
+import { basename as basename6, join as join26, relative as relative20, resolve as resolve28, sep as sep20 } from "path";
 
 // src/agent/subagents.ts
 import { z as z5 } from "zod";
@@ -7164,10 +7180,10 @@ function sanitize(message2, secrets) {
 }
 function waitForRetry(delayMs, signal) {
   if (signal?.aborted) return Promise.reject(signal.reason);
-  return new Promise((resolve28, reject) => {
+  return new Promise((resolve29, reject) => {
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve28();
+      resolve29();
     }, delayMs);
     const onAbort = () => {
       clearTimeout(timer);
@@ -7778,10 +7794,10 @@ function serializeToolInput(input) {
 }
 function waitForRetry2(delayMs, signal) {
   if (signal?.aborted) return Promise.reject(signal.reason);
-  return new Promise((resolve28, reject) => {
+  return new Promise((resolve29, reject) => {
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve28();
+      resolve29();
     }, delayMs);
     const onAbort = () => {
       clearTimeout(timer);
@@ -8987,7 +9003,7 @@ function decoratePayload(payload, envelope) {
   return envelope === void 0 ? payload : { ...payload, ...envelope };
 }
 function runShellHandler(descriptor, event, signal) {
-  return new Promise((resolve28, reject) => {
+  return new Promise((resolve29, reject) => {
     const child = spawn4(descriptor.command, [...descriptor.args ?? []], {
       env: { ...process.env, ...descriptor.env },
       shell: false,
@@ -9030,7 +9046,7 @@ function runShellHandler(descriptor, event, signal) {
         return;
       }
       try {
-        resolve28(HookDecisionSchema.parse(JSON.parse(stdout)));
+        resolve29(HookDecisionSchema.parse(JSON.parse(stdout)));
       } catch (error) {
         reject(error);
       }
@@ -9227,14 +9243,14 @@ async function createIslandControlServer(options) {
       void dispatch(line, socket, options, token);
     });
   });
-  await new Promise((resolve28, reject) => {
+  await new Promise((resolve29, reject) => {
     const onError = (error) => {
       server.removeListener("listening", onListening);
       reject(error);
     };
     const onListening = () => {
       server.removeListener("error", onError);
-      resolve28();
+      resolve29();
     };
     server.once("error", onError);
     server.once("listening", onListening);
@@ -9305,11 +9321,11 @@ function write(socket, payload) {
   }
 }
 function closeServer(server) {
-  return new Promise((resolve28) => {
+  return new Promise((resolve29) => {
     try {
-      server.close(() => resolve28());
+      server.close(() => resolve29());
     } catch {
-      resolve28();
+      resolve29();
     }
   });
 }
@@ -10494,7 +10510,7 @@ var USAGE = [
   "  clear     reset signals, done markers, and verified markers"
 ].join("\n");
 function runCommand(command, cwd, timeoutMs) {
-  return new Promise((resolve28) => {
+  return new Promise((resolve29) => {
     const isWindows = process.platform === "win32";
     const child = spawn5(isWindows ? "cmd.exe" : "/bin/sh", isWindows ? ["/d", "/s", "/c", command] : ["-c", command], {
       cwd,
@@ -10504,7 +10520,7 @@ function runCommand(command, cwd, timeoutMs) {
     let stderr = "";
     const timer = setTimeout(() => {
       child.kill();
-      resolve28({ ok: false, stdout, stderr: `${stderr}
+      resolve29({ ok: false, stdout, stderr: `${stderr}
 [killed: exceeded ${timeoutMs}ms]`, code: "timeout" });
     }, timeoutMs);
     child.stdout.on("data", (chunk) => {
@@ -10515,12 +10531,12 @@ function runCommand(command, cwd, timeoutMs) {
     });
     child.on("error", (error) => {
       clearTimeout(timer);
-      resolve28({ ok: false, stdout, stderr: `${stderr}
+      resolve29({ ok: false, stdout, stderr: `${stderr}
 ${error.message}`, code: "spawn" });
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve28({ ok: code === 0, stdout, stderr, code: code ?? "unknown" });
+      resolve29({ ok: code === 0, stdout, stderr, code: code ?? "unknown" });
     });
   });
 }
@@ -14036,8 +14052,8 @@ var OAuthCallbackAuthProvider = class {
   async #startCallbackServer(expectedState, signal) {
     let serverResolve;
     let serverReject;
-    const codePromise = new Promise((resolve28, reject) => {
-      serverResolve = resolve28;
+    const codePromise = new Promise((resolve29, reject) => {
+      serverResolve = resolve29;
       serverReject = reject;
     });
     const server = createServer3((req, res) => {
@@ -14071,7 +14087,7 @@ var OAuthCallbackAuthProvider = class {
       );
       serverResolve(code);
     });
-    return new Promise((resolve28, reject) => {
+    return new Promise((resolve29, reject) => {
       server.once("error", (error) => {
         reject(new Error(`OAuth callback server failed: ${error.message}`));
       });
@@ -14088,7 +14104,7 @@ var OAuthCallbackAuthProvider = class {
         signal.addEventListener("abort", () => {
           serverReject(new Error("OAuth flow aborted"));
         }, { once: true });
-        resolve28({ redirectUri, promise: codePromise });
+        resolve29({ redirectUri, promise: codePromise });
       });
     });
   }
@@ -17227,8 +17243,8 @@ var LspConnection = class {
     const id = this.#nextId++;
     const request = { jsonrpc: "2.0", id, method, params };
     const timeout = AbortSignal.timeout(LSP_REQUEST_TIMEOUT_MS);
-    const promise = new Promise((resolve28, reject) => {
-      this.#pending.set(id, { resolve: resolve28, reject });
+    const promise = new Promise((resolve29, reject) => {
+      this.#pending.set(id, { resolve: resolve29, reject });
       timeout.addEventListener("abort", () => {
         if (this.#pending.has(id)) {
           this.#pending.delete(id);
@@ -17632,19 +17648,19 @@ async function changeSummary(workspace) {
   };
 }
 async function stagedDiff(workspace, maxChars = 96e3) {
-  const stat9 = await git2(workspace, ["diff", "--staged", "--stat"]);
+  const stat10 = await git2(workspace, ["diff", "--staged", "--stat"]);
   const diff = await git2(workspace, ["diff", "--staged", "--no-ext-diff", "--no-color"]);
   if (!diff.ok) throw gitFailure(diff, "diff --staged");
   const text = diff.stdout;
   return {
     diff: text.length > maxChars ? `${text.slice(0, maxChars)}
 \u2026[diff truncated]` : text,
-    stat: stat9.stdout.trim(),
+    stat: stat10.stdout.trim(),
     truncated: text.length > maxChars
   };
 }
 async function uncommittedDiff(workspace, maxChars = 96e3) {
-  const stat9 = await git2(workspace, ["diff", "HEAD", "--stat"]);
+  const stat10 = await git2(workspace, ["diff", "HEAD", "--stat"]);
   const diff = await git2(workspace, ["diff", "HEAD", "--no-ext-diff", "--no-color"]);
   if (!diff.ok && !diff.stderr.includes("unknown revision")) throw gitFailure(diff, "diff HEAD");
   const summary2 = await changeSummary(workspace);
@@ -17652,7 +17668,7 @@ async function uncommittedDiff(workspace, maxChars = 96e3) {
   return {
     diff: text.length > maxChars ? `${text.slice(0, maxChars)}
 \u2026[diff truncated]` : text,
-    stat: stat9.stdout.trim(),
+    stat: stat10.stdout.trim(),
     untracked: summary2.untrackedFiles
   };
 }
@@ -17793,6 +17809,232 @@ function formatReviewReport(report) {
   return lines.join("\n");
 }
 
+// src/explain/service.ts
+async function resolveExplainTarget(graph, query) {
+  const trimmed = query.trim();
+  if (trimmed.includes("#")) {
+    const hit = await graph.relations(trimmed).catch(() => void 0);
+    if (hit?.origin !== void 0) return { kind: "resolved", node: hit.origin };
+  }
+  const hits = await graph.search(trimmed, 10);
+  if (hits.length === 0) return { kind: "not-found", query: trimmed };
+  if (hits.length === 1) return { kind: "resolved", node: hits[0] };
+  return { kind: "ambiguous", candidates: hits };
+}
+function explainCandidateLabel(candidate) {
+  return candidate.id;
+}
+async function selectExplainCandidate(candidates, questions, signal) {
+  const shown = candidates.slice(0, 3);
+  const answers = await questions.ask([{
+    header: "Symbol",
+    question: "Multiple symbols match. Which one should /explain cover? (Pick one, or type a more exact name.)",
+    options: [
+      ...shown.map((candidate) => ({
+        label: explainCandidateLabel(candidate),
+        description: `${candidate.kind} \xB7 ${candidate.filePath}:${candidate.startLine}-${candidate.endLine}`
+      })),
+      { label: "Cancel", description: "Abort /explain without choosing." }
+    ]
+  }], signal);
+  const answer = (answers[0] ?? "").trim();
+  if (answer === "Cancel" || answer === "") return { kind: "cancelled" };
+  const picked = shown.find((candidate) => explainCandidateLabel(candidate) === answer);
+  if (picked !== void 0) return { kind: "picked", node: picked };
+  return { kind: "typed", query: answer };
+}
+var MAX_SOURCE_CHARS = 2e4;
+function buildExplainPrompt(input) {
+  const source = input.anchorSource.length > MAX_SOURCE_CHARS ? `${input.anchorSource.slice(0, MAX_SOURCE_CHARS)}
+\u2026 (truncated)` : input.anchorSource;
+  const line = (n) => `- ${n.name} \u2014 ${n.filePath}:${n.startLine}`;
+  return [
+    "You are a senior engineer onboarding a new team member. Explain the following code symbol clearly and concretely; never invent behavior that is not in the shown evidence.",
+    `Answer in ${input.language}.`,
+    "Structure the answer with short markdown sections:",
+    "1. \u5B83\u662F\u505A\u4EC0\u4E48\u7684 \u2014 one paragraph, plain language, beginner first.",
+    "2. \u5173\u952E\u5B9E\u73B0\u70B9 \u2014 2-5 bullets tied to concrete lines/branches in the source.",
+    "3. \u8C01\u8C03\u7528\u5B83 / \u5B83\u8C03\u7528\u8C01 \u2014 use the relation lists; explain the data flow in one or two sentences.",
+    "4. \u4E3A\u4EC0\u4E48\u8FD9\u6837\u5199 \u2014 infer from the recent commit subjects when possible; say '\u4E0D\u786E\u5B9A' instead of guessing.",
+    "5. \u65B0\u4EBA\u6CE8\u610F\u4E8B\u9879 \u2014 pitfalls, guards or invariants worth knowing.",
+    ...input.focus === void 0 || input.focus.trim() === "" ? [] : [`The user specifically asks about: ${input.focus.trim()}`],
+    "",
+    `Symbol: ${input.anchor.id} (${input.anchor.kind}${input.anchor.signature ? `, signature: ${input.anchor.signature}` : ""})`,
+    "",
+    `Source (${input.anchor.filePath}:${input.anchor.startLine}-${input.anchor.endLine}):`,
+    source,
+    "",
+    `Callers:
+${input.callers.map(line).join("\n") || "- (none)"}`,
+    `Callees:
+${input.callees.map(line).join("\n") || "- (none)"}`,
+    "",
+    `Recent commits touching the file:
+${input.history.map((h) => `- ${h.date} ${h.author}: ${h.subject}`).join("\n") || "- (no history)"}`
+  ].join("\n");
+}
+async function explainWithModel(options, prompt, signal, onText) {
+  const { adapter, model } = options.registry.get(options.modelId());
+  let text = "";
+  for await (const event of adapter.stream({
+    model,
+    messages: [{ role: "user", content: prompt }],
+    tools: [],
+    signal
+  })) {
+    if (event.type === "text") {
+      text += event.text;
+      onText?.(event.text);
+    } else if (event.type === "error") throw new Error(`explain generation failed: ${event.error.message}`);
+    else if (event.type === "done") break;
+  }
+  const cleaned = text.trim();
+  if (cleaned === "") throw new Error("explain generation returned no text");
+  return cleaned;
+}
+var HISTORY_LIMIT = 8;
+var MAX_RESOLVE_ROUNDS = 2;
+async function runExplain(deps, query, focus, signal) {
+  if (query === void 0) {
+    return "Usage: /explain <symbol | file.ts#symbol> [what to focus on]. Example: /explain src/order.ts#cancelOrder error handling";
+  }
+  if (!(await deps.graph.status()).available) {
+    return "The code graph is not built yet \u2014 run /ast init, then try /explain again.";
+  }
+  let target = await resolveExplainTarget(deps.graph, query);
+  for (let round = 1; round <= MAX_RESOLVE_ROUNDS; round += 1) {
+    if (target.kind !== "ambiguous") break;
+    if (deps.questions === void 0) {
+      return `"${query}" is ambiguous. Use the exact node id, e.g. /explain ${target.candidates[0]?.id ?? "path/file.ts#name"}.`;
+    }
+    const selection = await selectExplainCandidate(target.candidates, deps.questions, signal);
+    if (selection.kind === "cancelled") return "/explain cancelled \u2014 no symbol was selected.";
+    if (selection.kind === "picked") {
+      target = { kind: "resolved", node: selection.node };
+      break;
+    }
+    target = await resolveExplainTarget(deps.graph, selection.query);
+    if (round === MAX_RESOLVE_ROUNDS && target.kind === "ambiguous") {
+      return `"${selection.query}" is still ambiguous. Pick one node id explicitly: /explain ${target.candidates[0]?.id ?? "path/file.ts#name"}`;
+    }
+  }
+  if (target.kind === "not-found") {
+    return `No matching symbol for "${target.query}" \u2014 check the name, or refresh the graph with /ast sync.`;
+  }
+  if (target.kind !== "resolved") {
+    return `"${query}" is ambiguous. Pick one node id explicitly: /explain ${target.candidates[0]?.id ?? "path/file.ts#name"}`;
+  }
+  const anchor = target.node;
+  signal.throwIfAborted();
+  deps.notify?.(`Explaining ${anchor.id} \u2026`);
+  const { callers, callees } = await deps.graph.relations(anchor.id, 1);
+  const raw = await deps.readFile(anchor.filePath).catch(() => "");
+  const lines = raw.split("\n");
+  const anchorSource = lines.slice(Math.max(0, anchor.startLine - 1), anchor.endLine).join("\n") || raw;
+  const history = deps.history === void 0 ? [] : await deps.history(anchor.filePath, HISTORY_LIMIT).catch(() => []);
+  try {
+    if (deps.onText !== void 0) deps.onText(`Explain ${anchor.id}
+
+`);
+    const explanation = await explainWithModel(
+      { registry: deps.registry, modelId: deps.modelId },
+      buildExplainPrompt({
+        anchor,
+        anchorSource,
+        callers: callers.map((n) => ({ name: n.name, filePath: n.filePath, startLine: n.startLine })),
+        callees: callees.map((n) => ({ name: n.name, filePath: n.filePath, startLine: n.startLine })),
+        history,
+        ...focus === void 0 ? {} : { focus },
+        language: deps.language
+      }),
+      signal,
+      deps.onText
+    );
+    return deps.onText === void 0 ? `Explain ${anchor.id}
+
+${explanation}` : "";
+  } catch (error) {
+    if (signal.aborted) throw error;
+    return `/explain failed: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+
+// src/desktop/astgraph-service.ts
+import { stat as stat8 } from "fs/promises";
+import { createRequire as nodeCreateRequire } from "module";
+import { join as join22, resolve as resolve22 } from "path";
+var FIELDS = "id, kind, name, qualified_name, file_path, language, start_line, end_line, signature";
+var DesktopAstGraphService = class {
+  #path;
+  constructor(workspace) {
+    this.#path = join22(resolve22(workspace), ".flavor", "astgraph", "index.db");
+  }
+  async status() {
+    if ((await stat8(this.#path).catch(() => void 0))?.isFile() !== true) {
+      return { available: false, path: this.#path, files: 0, nodes: 0, edges: 0 };
+    }
+    return this.#read((db) => {
+      const count = (table) => Number(db.prepare(`SELECT COUNT(*) AS count FROM ${table}`).get().count);
+      const metadata = db.prepare("SELECT value FROM project_metadata WHERE key = 'last_index'").get();
+      let indexedAt;
+      try {
+        const at = Number(JSON.parse(metadata?.value ?? "{}").at);
+        if (Number.isFinite(at)) indexedAt = new Date(at).toISOString();
+      } catch {
+      }
+      return { available: true, path: this.#path, files: count("files"), nodes: count("nodes"), edges: count("edges"), ...indexedAt === void 0 ? {} : { indexedAt } };
+    });
+  }
+  async search(query, limit = 40) {
+    const value = query.trim().slice(0, 200);
+    if (value.length === 0 || !(await this.status()).available) return [];
+    return this.#read((db) => db.prepare(`SELECT ${FIELDS} FROM nodes WHERE lower(name) LIKE ? OR lower(qualified_name) LIKE ? ORDER BY CASE WHEN lower(name) = ? THEN 0 ELSE 1 END, name LIMIT ?`).all(`%${value.toLowerCase()}%`, `%${value.toLowerCase()}%`, value.toLowerCase(), Math.min(Math.max(limit, 1), 100)).map(mapNode));
+  }
+  async relations(id, hops = 2) {
+    if (!/^[A-Za-z0-9._:/#@+~-]{1,512}$/.test(id)) throw new Error("Invalid AST node id");
+    if (!(await this.status()).available) return { callers: [], callees: [], impact: [] };
+    return this.#read((db) => {
+      const originRow = db.prepare(`SELECT ${FIELDS} FROM nodes WHERE id = ?`).get(id);
+      const linked = (direction) => {
+        const source = direction === "callers" ? "e.source" : "e.target";
+        const predicate = direction === "callers" ? "e.target = ?" : "e.source = ?";
+        return db.prepare(`SELECT DISTINCT n.${FIELDS.split(", ").join(", n.")} FROM edges e JOIN nodes n ON n.id = ${source} WHERE ${predicate} AND e.kind IN ('calls','imports') LIMIT 100`).all(id).map(mapNode);
+      };
+      const seen = /* @__PURE__ */ new Map();
+      let frontier = [id];
+      for (let hop = 1; hop <= Math.min(Math.max(hops, 1), 4) && frontier.length > 0 && seen.size < 200; hop += 1) {
+        const next = [];
+        for (const current of frontier) {
+          const rows = db.prepare("SELECT source AS other FROM edges WHERE target = ? UNION SELECT target AS other FROM edges WHERE source = ? LIMIT 200").all(current, current);
+          for (const row of rows) if (row.other !== id && !seen.has(row.other)) {
+            seen.set(row.other, hop);
+            next.push(row.other);
+          }
+        }
+        frontier = next;
+      }
+      const impact = [...seen].flatMap(([nodeId, hop]) => {
+        const row = db.prepare(`SELECT ${FIELDS} FROM nodes WHERE id = ?`).get(nodeId);
+        return row === void 0 ? [] : [{ ...mapNode(row), hop }];
+      });
+      return { ...originRow === void 0 ? {} : { origin: mapNode(originRow) }, callers: linked("callers"), callees: linked("callees"), impact };
+    });
+  }
+  #read(run) {
+    const sqlite = nodeCreateRequire(import.meta.url)("node:sqlite");
+    const db = new sqlite.DatabaseSync(this.#path, { readOnly: true });
+    try {
+      return run(db);
+    } finally {
+      db.close();
+    }
+  }
+};
+function mapNode(value) {
+  const row = value;
+  return { id: String(row.id), kind: String(row.kind), name: String(row.name), qualifiedName: String(row.qualified_name), filePath: String(row.file_path), language: String(row.language), startLine: Number(row.start_line), endLine: Number(row.end_line), ...row.signature == null ? {} : { signature: String(row.signature) } };
+}
+
 // src/git/tools.ts
 import { z as z28 } from "zod";
 var GitHistoryInput = z28.object({
@@ -17887,7 +18129,7 @@ var QuestionBridge = class {
     }
   }
   #askLocally(questions, signal) {
-    return new Promise((resolve28, reject) => {
+    return new Promise((resolve29, reject) => {
       const onAbort = () => {
         this.#pending = void 0;
         this.#active = false;
@@ -17901,7 +18143,7 @@ var QuestionBridge = class {
           this.#pending = void 0;
           this.#active = false;
           this.#onChange?.();
-          resolve28(answers);
+          resolve29(answers);
         },
         reject: (error) => {
           signal.removeEventListener("abort", onAbort);
@@ -17994,7 +18236,7 @@ function createTodoWriteTool() {
 // src/tools/managed.ts
 import { randomUUID as randomUUID16 } from "crypto";
 import { link as link2, lstat as lstat11, mkdir as mkdir17, readFile as readFile19, readdir as readdir8, unlink as unlink5, writeFile as writeFile10 } from "fs/promises";
-import { dirname as dirname18, join as join22, resolve as resolve22 } from "path";
+import { dirname as dirname18, join as join23, resolve as resolve23 } from "path";
 import { z as z31 } from "zod";
 var MANAGED_TOOL_VERSION = 1;
 var MAX_RECORD_BYTES = 256 * 1024;
@@ -18036,9 +18278,9 @@ var ManagedToolStore = class {
   #entries = /* @__PURE__ */ new Map();
   #diagnostics = [];
   constructor(options) {
-    this.#workspace = resolve22(options.workspace);
-    this.#projectRoot = join22(this.#workspace, ".flavor", "tools");
-    this.#globalRoot = join22(resolve22(options.home), ".flavor-code", "tools");
+    this.#workspace = resolve23(options.workspace);
+    this.#projectRoot = join23(this.#workspace, ".flavor", "tools");
+    this.#globalRoot = join23(resolve23(options.home), ".flavor-code", "tools");
     this.#now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
   }
   get diagnostics() {
@@ -18085,7 +18327,7 @@ var ManagedToolStore = class {
       version: MANAGED_TOOL_VERSION,
       createdAt: this.#now()
     });
-    const path = join22(this.directory(input.scope), filename(input.name));
+    const path = join23(this.directory(input.scope), filename(input.name));
     const definition = compileDefinition(record, input.scope, this.#workspace);
     await writeExclusive(path, `${JSON.stringify(record, void 0, 2)}
 `);
@@ -18110,7 +18352,7 @@ var ManagedToolStore = class {
     if (!parsed.success) return [];
     const matches = this.#matching(parsed.data.name).filter((entry2) => parsed.data.scope === void 0 || entry2.scope === parsed.data.scope);
     if (matches.length > 0) return matches.map((entry2) => entry2.path);
-    return [join22(this.directory(parsed.data.scope ?? "project"), filename(parsed.data.name))];
+    return [join23(this.directory(parsed.data.scope ?? "project"), filename(parsed.data.name))];
   }
   async #loadDirectory(scope2) {
     const root = this.directory(scope2);
@@ -18123,7 +18365,7 @@ var ManagedToolStore = class {
       return;
     }
     for (const name of names) {
-      const path = join22(root, name);
+      const path = join23(root, name);
       try {
         const info = await lstat11(path);
         if (!info.isFile() || info.isSymbolicLink()) throw new Error("Managed tool record must be a regular file");
@@ -19042,7 +19284,7 @@ ${total}`;
 // src/memory/store.ts
 import { createHash as createHash16 } from "crypto";
 import { readFile as readFile20, rm as rm9 } from "fs/promises";
-import { resolve as resolve23, join as join23, relative as relative17, sep as sep17 } from "path";
+import { resolve as resolve24, join as join24, relative as relative17, sep as sep17 } from "path";
 
 // src/memory/similarity.ts
 function normalizeForSimilarity(value) {
@@ -19144,10 +19386,10 @@ var MemoryStore = class {
   constructor(options) {
     if (!Number.isSafeInteger(options.maxEntries) || options.maxEntries < 1) throw new Error("maxEntries must be an integer of at least 1");
     if (!Number.isSafeInteger(options.maxEntryChars) || options.maxEntryChars < 1) throw new Error("maxEntryChars must be an integer of at least 1");
-    this.workspace = resolve23(options.workspace);
-    this.#memoryRoot = join23(this.workspace, ".flavor", "memory");
-    this.path = join23(this.#memoryRoot, "MEMORY.md");
-    this.#behaviorPath = join23(this.#memoryRoot, "behavior.json");
+    this.workspace = resolve24(options.workspace);
+    this.#memoryRoot = join24(this.workspace, ".flavor", "memory");
+    this.path = join24(this.#memoryRoot, "MEMORY.md");
+    this.#behaviorPath = join24(this.#memoryRoot, "behavior.json");
     this.#maxEntries = options.maxEntries;
     this.#maxEntryChars = options.maxEntryChars;
   }
@@ -19370,7 +19612,7 @@ var MemoryStore = class {
   }
   #resolveContentPath(contentPath) {
     if (!/^tasks\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.md$/.test(contentPath)) throw new Error("Invalid memory content path");
-    const path = resolve23(this.#memoryRoot, ...contentPath.split("/"));
+    const path = resolve24(this.#memoryRoot, ...contentPath.split("/"));
     const rel = relative17(this.#memoryRoot, path);
     if (rel === ".." || rel.startsWith(`..${sep17}`)) throw new Error("Memory content path escapes the memory directory");
     return path;
@@ -19841,8 +20083,8 @@ function createExecutionEnvironment(workspace, config) {
 }
 
 // src/ide/client.ts
-import { readFile as readFile21, readdir as readdir9, stat as stat8 } from "fs/promises";
-import { basename as basename5, join as join24, relative as relative18, resolve as resolve24, sep as sep18 } from "path";
+import { readFile as readFile21, readdir as readdir9, stat as stat9 } from "fs/promises";
+import { basename as basename5, join as join25, relative as relative18, resolve as resolve25, sep as sep18 } from "path";
 var FlavorIdeClient = class {
   #workspace;
   #home;
@@ -19853,8 +20095,8 @@ var FlavorIdeClient = class {
   #sessionId;
   #eventTail = Promise.resolve();
   constructor(options) {
-    this.#workspace = resolve24(options.workspace);
-    this.#home = resolve24(options.home);
+    this.#workspace = resolve25(options.workspace);
+    this.#home = resolve25(options.home);
     this.#environment = options.environment ?? process.env;
     this.#fetch = options.fetch ?? fetch;
   }
@@ -19938,7 +20180,7 @@ var FlavorIdeClient = class {
       };
       if (await this.#healthy(configured)) return configured;
     }
-    const directory = join24(this.#home, ".flavor-code", "ide");
+    const directory = join25(this.#home, ".flavor-code", "ide");
     let entries;
     try {
       entries = (await readdir9(directory)).filter((name) => name.endsWith(".lock"));
@@ -19946,9 +20188,9 @@ var FlavorIdeClient = class {
       return void 0;
     }
     const candidates = (await Promise.all(entries.map(async (name) => {
-      const path = join24(directory, name);
+      const path = join25(directory, name);
       try {
-        const [contents, info] = await Promise.all([readFile21(path, "utf8"), stat8(path)]);
+        const [contents, info] = await Promise.all([readFile21(path, "utf8"), stat9(path)]);
         const lock = parseLockfile(contents);
         return lock === void 0 ? void 0 : { lock, modified: info.mtimeMs };
       } catch {
@@ -20052,8 +20294,8 @@ function parsePort(value) {
   return Number.isInteger(port) && port > 0 && port <= 65535 ? port : void 0;
 }
 function isWithin8(parent, child) {
-  const base = normalize(resolve24(parent));
-  const target = normalize(resolve24(child));
+  const base = normalize(resolve25(parent));
+  const target = normalize(resolve25(child));
   return target === base || target.startsWith(`${base}${sep18}`);
 }
 function normalize(path) {
@@ -20083,8 +20325,8 @@ var JobRegistry = class {
     const id = `job-${randomUUID17().slice(0, 12)}`;
     const now = (/* @__PURE__ */ new Date()).toISOString();
     let settle;
-    const done = new Promise((resolve28) => {
-      settle = resolve28;
+    const done = new Promise((resolve29) => {
+      settle = resolve29;
     });
     const record = {
       id,
@@ -20207,8 +20449,8 @@ function snapshot2(job) {
 
 // src/terminal/service.ts
 import { randomUUID as randomUUID18 } from "crypto";
-import { createRequire as nodeCreateRequire } from "module";
-import { isAbsolute as isAbsolute11, relative as relative19, resolve as resolve25, sep as sep19 } from "path";
+import { createRequire as nodeCreateRequire2 } from "module";
+import { isAbsolute as isAbsolute11, relative as relative19, resolve as resolve26, sep as sep19 } from "path";
 var TerminalService = class {
   #root;
   #factory;
@@ -20216,7 +20458,7 @@ var TerminalService = class {
   #maxOutputChars;
   #sessions = /* @__PURE__ */ new Map();
   constructor(workspace, options = {}) {
-    this.#root = resolve25(workspace);
+    this.#root = resolve26(workspace);
     this.#factory = options.factory ?? defaultFactory;
     this.#jobs = options.jobs;
     this.#maxOutputChars = options.maxOutputChars ?? 2e5;
@@ -20321,7 +20563,7 @@ function snapshot3(record) {
 }
 function defaultFactory(shell, args, options) {
   try {
-    const pty = nodeCreateRequire(import.meta.url)("node-pty");
+    const pty = nodeCreateRequire2(import.meta.url)("node-pty");
     return pty.spawn(shell, args, { ...options, name: "xterm-256color" });
   } catch (error) {
     throw new Error(`Pseudo-terminal backend is unavailable: ${error instanceof Error ? error.message : String(error)}`);
@@ -20334,7 +20576,7 @@ function cleanEnvironment(environment) {
   return Object.fromEntries(Object.entries(environment).filter((entry2) => entry2[1] !== void 0));
 }
 function workspacePath(root, input) {
-  const path = resolve25(root, input);
+  const path = resolve26(root, input);
   const delta = relative19(root, path);
   if (delta === ".." || delta.startsWith(`..${sep19}`) || isAbsolute11(delta)) throw new Error("Terminal cwd is outside the workspace");
   return path;
@@ -20342,7 +20584,7 @@ function workspacePath(root, input) {
 
 // src/tools/terminal.ts
 import { z as z33 } from "zod";
-import { resolve as resolve26 } from "path";
+import { resolve as resolve27 } from "path";
 var Id = z33.string().regex(/^term-[a-f0-9-]+$/);
 var OpenInput = z33.object({ cwd: z33.string().optional(), shell: z33.string().optional(), args: z33.array(z33.string()).optional(), columns: z33.coerce.number().int().min(10).max(500).optional(), rows: z33.coerce.number().int().min(2).max(300).optional() });
 var OptionalBoolean = z33.union([z33.boolean(), z33.string().refine((value) => value === "true" || value === "false")]);
@@ -20356,8 +20598,8 @@ function createTerminalTools(terminals, workspace = process.cwd()) {
       name: "TerminalOpen",
       description: "Open a persistent interactive pseudo-terminal in the workspace",
       inputSchema: OpenInput,
-      paths: (input) => [resolve26(workspace, input.cwd ?? ".")],
-      permissions: (input) => ({ paths: [resolve26(workspace, input.cwd ?? ".")], command: input.shell ?? "system-shell", args: input.args ?? [], cwd: resolve26(workspace, input.cwd ?? ".") }),
+      paths: (input) => [resolve27(workspace, input.cwd ?? ".")],
+      permissions: (input) => ({ paths: [resolve27(workspace, input.cwd ?? ".")], command: input.shell ?? "system-shell", args: input.args ?? [], cwd: resolve27(workspace, input.cwd ?? ".") }),
       execute: async (input, _signal, context) => terminals.open({
         owner: owner(context),
         ...input.cwd === void 0 ? {} : { cwd: input.cwd },
@@ -20583,8 +20825,8 @@ var PalClient = class {
       let disconnectTimer;
       await Promise.race([
         this.request({ version: 1, type: "disconnect", requestId: randomUUID19() }).catch(() => void 0),
-        new Promise((resolve28) => {
-          disconnectTimer = setTimeout(resolve28, Math.min(this.requestTimeoutMs, 250));
+        new Promise((resolve29) => {
+          disconnectTimer = setTimeout(resolve29, Math.min(this.requestTimeoutMs, 250));
         })
       ]);
       if (disconnectTimer !== void 0) clearTimeout(disconnectTimer);
@@ -20630,7 +20872,7 @@ var PalClient = class {
     return presence;
   }
   openSocket() {
-    return new Promise((resolve28, reject) => {
+    return new Promise((resolve29, reject) => {
       let settled = false;
       const rejectConnection = (error) => {
         if (settled) return;
@@ -20653,7 +20895,7 @@ var PalClient = class {
         settled = true;
         if (this.connectingReject === rejectConnection) this.connectingReject = void 0;
         socket.off("error", onInitialError);
-        resolve28();
+        resolve29();
       };
       const onInitialError = (error) => {
         socket.off("connect", onConnect);
@@ -20684,12 +20926,12 @@ var PalClient = class {
     if (this.closed || socket === void 0 || socket.destroyed || !socket.writable) {
       return Promise.reject(new Error(this.closed ? "Pal client is closed" : "Pal client is not connected"));
     }
-    return new Promise((resolve28, reject) => {
+    return new Promise((resolve29, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(request.requestId);
         reject(new Error(`Pal request '${request.type}' timed out`));
       }, this.requestTimeoutMs);
-      this.pending.set(request.requestId, { resolve: resolve28, reject, timer });
+      this.pending.set(request.requestId, { resolve: resolve29, reject, timer });
       let frame;
       try {
         frame = encodeControlFrame(BrokerRequestSchema.parse(request));
@@ -21093,8 +21335,8 @@ var ApprovalBridge = class {
   }
 };
 async function createProductionRuntime(options) {
-  const workspace = resolve27(options.workspace ?? process.cwd());
-  const home = resolve27(options.home ?? homedir2());
+  const workspace = resolve28(options.workspace ?? process.cwd());
+  const home = resolve28(options.home ?? homedir2());
   const environment = options.environment ?? process.env;
   const ide = new FlavorIdeClient({ workspace, home, environment });
   const ideReady = ide.initialize();
@@ -21318,8 +21560,8 @@ async function createProductionRuntime(options) {
   const registeredProviders = registration.registered;
   let effectiveLlm = registration.effectiveLlm;
   const pluginHost = new PluginHost({
-    globalPluginDirs: [join25(home, ".flavor-code", "plugins")],
-    projectPluginDirs: [join25(workspace, ".flavor", "plugins")],
+    globalPluginDirs: [join26(home, ".flavor-code", "plugins")],
+    projectPluginDirs: [join26(workspace, ".flavor", "plugins")],
     config,
     // Existing project plugins (including astgraph and superharness) use Node.js
     // built-ins. The Worker/vm sandbox deliberately blocks those imports, so it
@@ -21427,7 +21669,7 @@ async function createProductionRuntime(options) {
       const address = palSocketAddress({
         platform: process.platform,
         userScope: home,
-        runtimeDir: join25(tmpdir4(), `flavor-code-pals-${createHash18("sha256").update(home).digest("hex").slice(0, 16)}`)
+        runtimeDir: join26(tmpdir4(), `flavor-code-pals-${createHash18("sha256").update(home).digest("hex").slice(0, 16)}`)
       });
       const baseCollaborationClient = collaboration.client ?? collaboration.createClient?.({
         instanceId: collaboration.instanceId,
@@ -21538,8 +21780,8 @@ async function createProductionRuntime(options) {
       diagnostics.push(`MCP servers could not start: ${message(error)}`);
     });
     const skills = new SkillRegistry({
-      globalRoots: [join25(home, ".flavor-code", "skills")],
-      projectRoots: [join25(workspace, ".flavor", "skills"), ...pluginSkillRoots],
+      globalRoots: [join26(home, ".flavor-code", "skills")],
+      projectRoots: [join26(workspace, ".flavor", "skills"), ...pluginSkillRoots],
       authorizeResource: async () => true,
       disabledNames: config.skills.disabled
     });
@@ -21547,7 +21789,7 @@ async function createProductionRuntime(options) {
     skillsReady.catch(() => void 0);
     tools.push(createSkillTool(skills), createSkillResourceTool(skills));
     if (options.extraTools !== void 0) tools.push(...options.extraTools);
-    const flavor = await optionalText2(join25(workspace, "FLAVOR.md"));
+    const flavor = await optionalText2(join26(workspace, "FLAVOR.md"));
     const instructionBaseline = await workspaceInstructions.baseline();
     let memoryContext;
     if (memoryStore !== void 0) {
@@ -22125,7 +22367,7 @@ async function createProductionRuntime(options) {
         evolveService.toolDefinition(),
         ...mcpTools
       ];
-      const loopFlavor = await optionalText2(join25(input.workspace, "FLAVOR.md"));
+      const loopFlavor = await optionalText2(join26(input.workspace, "FLAVOR.md"));
       const loopInstructionBaseline = await loopInstructions.baseline();
       const loopEnvironment = createPromptEnvironment({
         now: /* @__PURE__ */ new Date(),
@@ -22485,6 +22727,22 @@ async function createProductionRuntime(options) {
         modelId: () => harness.subagentModelId,
         notify: (message2) => emitOutput({ type: "notice", message: message2 })
       }, focus, signal),
+      explain: (query, focus, signal, onText) => runExplain({
+        graph: new DesktopAstGraphService(workspace),
+        readFile: async (path) => {
+          const root = resolve28(workspace);
+          const abs = resolve28(root, path);
+          if (abs !== root && !abs.startsWith(root + sep20)) throw new Error(`path outside workspace: ${path}`);
+          return readFile22(abs, "utf8");
+        },
+        history: async (path, limit) => fileHistory(workspace, path, limit),
+        questions,
+        registry,
+        modelId: () => harness.subagentModelId,
+        language,
+        notify: (message2) => emitOutput({ type: "notice", message: message2 }),
+        ...onText === void 0 ? {} : { onText }
+      }, query, focus, signal),
       audit: async (toolFilter) => {
         try {
           const raw = await readFile22(auditLogger.path, "utf8");
@@ -22674,7 +22932,7 @@ ${renderMemoryDocument(entries)}`;
           return `Provider "${providerName}" is missing authorizationUrl, tokenUrl, or clientId.`;
         }
         try {
-          const tokenStore = createFileTokenStore(join25(home, ".flavor-code", "auth.json"));
+          const tokenStore = createFileTokenStore(join26(home, ".flavor-code", "auth.json"));
           const credentialId = oauthCredentialId(oauthConfig.tokenUrl, oauthConfig.clientId);
           await migrateLegacyOAuthToken(tokenStore, providerName, credentialId);
           const oauth = new OAuthCallbackAuthProvider({
@@ -22721,7 +22979,7 @@ ${renderMemoryDocument(entries)}`;
         }
       },
       async logout() {
-        const tokenStore = createFileTokenStore(join25(home, ".flavor-code", "auth.json"));
+        const tokenStore = createFileTokenStore(join26(home, ".flavor-code", "auth.json"));
         const tokens = await tokenStore.load();
         const hadCredentials = Object.keys(tokens).length > 0 || effectiveLlm !== void 0;
         if (!hadCredentials) {
@@ -22997,8 +23255,8 @@ async function workspaceFingerprint(workspace) {
   let remaining = 5 * 1024 * 1024;
   for (const name of untracked.stdout.split("\0").filter(Boolean).sort()) {
     if (name === ".flavor/loops" || name.startsWith(".flavor/loops/")) continue;
-    const path = resolve27(workspace, name);
-    const relativePath = relative20(resolve27(workspace), path);
+    const path = resolve28(workspace, name);
+    const relativePath = relative20(resolve28(workspace), path);
     if (relativePath === ".." || relativePath.startsWith(`..${sep20}`)) continue;
     hash.update(name);
     if (remaining <= 0) continue;
@@ -23216,7 +23474,7 @@ async function registerConfiguredAdapters(providers, registry, environment, diag
   const configured = { ...providers };
   if (configured.openai === void 0 && environment.OPENAI_API_KEY) configured.openai = { type: "openai", apiKey: environment.OPENAI_API_KEY };
   if (configured.anthropic === void 0 && environment.ANTHROPIC_API_KEY) configured.anthropic = { type: "anthropic", apiKey: environment.ANTHROPIC_API_KEY };
-  const oauthTokenStore = createFileTokenStore(join25(home, ".flavor-code", "auth.json"));
+  const oauthTokenStore = createFileTokenStore(join26(home, ".flavor-code", "auth.json"));
   const registered = [];
   let effectiveLlm;
   for (const [name, provider] of Object.entries(configured)) {