@zosmaai/pi-llm-wiki 0.12.0 → 0.12.2

package/dist/extensions/llm-wiki/lib/subagent.js

@@ -1,13 +1,42 @@
-import { agentLoop, } from "@earendil-works/pi-agent-core";
+import { runAgentLoop, } from "@earendil-works/pi-agent-core";
+let cachedDefaultStreamFn;
+/**
+ * The default pi-ai stream function (dispatches to registered API providers).
+ * It moved from the package root to the `./compat` subpath in pi-ai 0.85, so
+ * it is resolved lazily — a static import of either path breaks the other pi
+ * version at load time. Cached after the first resolution.
+ */
+async function resolveDefaultStreamFn() {
+    if (cachedDefaultStreamFn)
+        return cachedDefaultStreamFn;
+    const root = await import("@earendil-works/pi-ai");
+    const rootFn = root.streamSimple;
+    if (rootFn) {
+        cachedDefaultStreamFn = rootFn;
+        return rootFn;
+    }
+    // pi-ai >= 0.85 exposes streamSimple via the ./compat subpath. The
+    // specifier is a variable so static tooling (vite in vitest, jiti in pi)
+    // cannot resolve a subpath that does not exist in pi < 0.85; at runtime
+    // this branch is only reached when the root import lacks streamSimple.
+    const compatSpecifier = "@earendil-works/pi-ai/compat";
+    const compat = await import(compatSpecifier);
+    cachedDefaultStreamFn = compat.streamSimple;
+    return cachedDefaultStreamFn;
+}
 /**
  * Run a sub-agent loop to completion.
  *
  * Returns nothing useful directly — by design, results are collected by the
  * `tools` the caller passes (their `execute` accumulates into caller-owned
  * state). This keeps the runner generic across every background task type.
+ *
+ * Rejections from the loop (provider errors, auth failures, a streamFn that
+ * throws) reject this promise, so `BackgroundRuntime.launchTask`'s try/catch
+ * degrades them to a warning toast.
  */
 export async function runSubAgent(args) {
-    const { model, apiKey, headers, systemPrompt, userPrompt, tools, maxTokens, signal } = args;
+    const { model, apiKey, headers, systemPrompt, userPrompt, tools, maxTokens, signal, streamFn, env, } = args;
     const text = userPrompt.trim();
     if (!text)
         return;
@@ -32,10 +61,21 @@ export async function runSubAgent(args) {
         convertToLlm: (msgs) => msgs,
         toolExecution: "sequential",
         ...(reasoning ? { reasoning: "high" } : {}),
+        // Provider-scoped env from auth resolution (issue #222). pi-agent-core
+        // spreads the config into the stream options, where pi-ai >= 0.85 honors
+        // it; the conditional spread keeps this compiling on pi < 0.85.
+        ...(env ? { env } : {}),
     };
-    const stream = agentLoop(prompts, context, config, signal);
-    for await (const _event of stream) {
-        // Drain events; tool `execute` callbacks collect results caller-side.
-    }
-    await stream.result();
+    // Drive the loop directly instead of agentLoop(): agentLoop() wraps the
+    // loop in a detached promise (`void runAgentLoop(...).then(...)` with no
+    // .catch), so a rejection from the stream path — e.g. "No API provider
+    // registered for api: X" for a model from an extension-registered provider
+    // — escaped as an uncaughtException and killed the whole pi process while
+    // this function's stream drain hung forever (issue #222). runAgentLoop is
+    // the same loop with the rejection propagating to THIS promise.
+    // pi >= 0.85 requires streamFn explicitly (its internal fallback throws
+    // unless the host configured a default), so we always pass one: the
+    // provider-specific function when available, else pi-ai's default.
+    const activeStreamFn = streamFn ?? (await resolveDefaultStreamFn());
+    await runAgentLoop(prompts, context, config, async () => { }, signal, activeStreamFn);
 }

package/dist/extensions/llm-wiki/lib/tools.js

@@ -5,15 +5,16 @@ import { bootstrapVault } from "./bootstrap.js";
 import { launchEmbedPages, reindexEmbeddings, resolveEmbedder } from "./embeddings.js";
 import { scheduleReindex } from "./indexing.js";
 import { runIngestSynthesis } from "./ingest-worker.js";
-import { createKnowledgeDocument, serializeKnowledgeDocument, writeKnowledgeDocumentFile, } from "./knowledge-document.js";
+import { createKnowledgeDocument, parseMarkdownFrontmatter, serializeKnowledgeDocument, writeKnowledgeDocumentFile, } from "./knowledge-document.js";
 import { applyWikilinkGate, buildResolvedBacklinks, buildWikilinkIndex, } from "./knowledge-links.js";
 import { repairLegacyKnowledgeDocuments } from "./legacy-repair.js";
 import { appendEvent, rebuildMetadata, rebuildMetadataLight } from "./metadata.js";
+import { readQmdIndexStatus, reindexQmdVault } from "./qmd-indexing.js";
 import { captureFile, captureText, captureUrl } from "./source-packet.js";
 import { loadTaskConfig, parseModelRef, resolveWikilinkValidation } from "./task-config.js";
 import { detectVaultFormat, fmtDate, getVaultPaths, readJson, resolveVaultPaths, slugify, writeJson, } from "./utils.js";
 import { assertWritableVault, compareCodePoint, discoverKnowledgeDocuments, inspectVaultFormat, inspectWritableVault, } from "./vault-format.js";
-import { getWikiStatus, searchRegistry } from "./wiki-service.js";
+import { getWikiStatus, reindexWiki, searchRegistry } from "./wiki-service.js";
 /**
  * All LLM Wiki custom tools.
  */
@@ -323,6 +324,8 @@ export function registerWikiIngest(pi, runtime) {
                                 model: resolved.model,
                                 apiKey: resolved.apiKey,
                                 headers: resolved.headers,
+                                streamFn: resolved.streamFn,
+                                env: resolved.env,
                                 paths,
                                 sourceId: s.id,
                                 manifest: s.manifest,
@@ -410,6 +413,10 @@ export function registerWikiIngest(pi, runtime) {
     });
 }
 // ─── 4. wiki_ensure_page ────────────────────────────────
+// Frontmatter fields wiki_ensure_page generates or derives itself (title also
+// determines the filename). Model-supplied values for these are ignored rather
+// than merged (issue #241).
+const RESERVED_FRONTMATTER = new Set(["type", "title", "created", "updated", "sources", "id"]);
 export function registerWikiEnsurePage(pi, runtime) {
     pi.registerTool({
         name: "wiki_ensure_page",
@@ -419,13 +426,16 @@ export function registerWikiEnsurePage(pi, runtime) {
         promptGuidelines: [
             "Use wiki_ensure_page before creating pages to avoid duplicates.",
             "Search existing pages first with wiki_search.",
+            "Content may begin with a YAML frontmatter block; its fields are merged into the page frontmatter, and generated fields are reserved.",
         ],
         parameters: Type.Object({
             type: Type.String({
                 description: "Page type: entity | concept | synthesis | analysis | requirement | skill | case (built-in) or any user-defined type from llm-wiki.customTypes config",
             }),
             title: Type.String({ description: "Page title" }),
-            content: Type.Optional(Type.String({ description: "Optional initial content (otherwise uses template)" })),
+            content: Type.Optional(Type.String({
+                description: "Optional Markdown body. May begin with a YAML frontmatter block, whose fields are merged into the page frontmatter; generated fields (type, title, created, updated, sources) are reserved and ignored.",
+            })),
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const paths = getPaths(ctx.cwd);
@@ -465,6 +475,24 @@ export function registerWikiEnsurePage(pi, runtime) {
             }
             const today = fmtDate();
             let body = params.content ?? buildPageBody(type, params.title);
+            // #241: models sometimes pass a YAML frontmatter block inside content.
+            // Consume it (with the same hardened parser used for page reads) and merge
+            // its fields into the generated frontmatter, instead of writing the block
+            // verbatim into the body (duplicate frontmatter, and the model's fields
+            // silently never took effect). Generated fields are reserved; a
+            // frontmatter-only content falls back to the template body.
+            const extraFrontmatter = {};
+            if (body.trimStart().startsWith("---")) {
+                const parsed = parseMarkdownFrontmatter(body, `${folder}/${slug}.md`);
+                if (parsed.ok) {
+                    for (const [key, value] of Object.entries(parsed.mapping)) {
+                        if (!RESERVED_FRONTMATTER.has(key)) {
+                            extraFrontmatter[key] = value;
+                        }
+                    }
+                    body = parsed.body.trim() ? parsed.body : buildPageBody(type, params.title);
+                }
+            }
             // Pre-write wikilink gate (#172): validate/normalize caller-supplied content.
             const mode = resolveWikilinkValidation(loadTaskConfig(ctx.cwd));
             let wikilinkIssues = [];
@@ -494,6 +522,7 @@ export function registerWikiEnsurePage(pi, runtime) {
                 title: params.title,
                 created: today,
                 updated: today,
+                ...extraFrontmatter,
             }, body);
             mkdirSync(join(paths.wiki, folder), { recursive: true });
             writeKnowledgeDocumentFile(pagePath, doc);
@@ -740,8 +769,9 @@ export function registerWikiLint(pi, runtime) {
  * Run the wiki health scan (issue #77 extracted it from the tool body so it can
  * run off-thread via `dispatchReported`). Returns the human-readable summary.
  */
-function runWikiLint(paths, autoFix) {
+async function runWikiLint(paths, autoFix) {
     assertWritableVault(paths);
+    const qmdStatus = await readQmdIndexStatus(paths);
     let repair;
     if (autoFix) {
         let projection = rebuildMetadata(paths);
@@ -891,6 +921,20 @@ function runWikiLint(paths, autoFix) {
         });
         rebuildMetadataLight(paths);
     }
+    const qmdFindings = [];
+    if (qmdStatus.state === "stale") {
+        const components = JSON.stringify(qmdStatus.repairComponents.length > 0 ? qmdStatus.repairComponents : ["lexical"]);
+        qmdFindings.push(`- QMD index stale (${qmdStatus.indexedManifestHash ? "manifest or model changed" : ""}): repair with \`wiki_reindex(scope="changed", components=${components}, vault="active")\``);
+    }
+    else if (qmdStatus.state === "recovering") {
+        qmdFindings.push(`- QMD swap interrupted (${qmdStatus.swapPhase ?? ""}): restart recovery via \`wiki_reindex(vault="active")\``);
+    }
+    else if (qmdStatus.state === "error") {
+        qmdFindings.push(`- QMD index error: ${qmdStatus.issues[0]?.message ?? "repair with wiki_reindex"} — \`wiki_reindex(scope="changed", components=${JSON.stringify(qmdStatus.repairComponents.length > 0 ? qmdStatus.repairComponents : ["lexical"])}, vault="active")\``);
+    }
+    else if (qmdStatus.state === "missing") {
+        qmdFindings.push("- QMD index not built yet (informational): run wiki_reindex to build it");
+    }
     return [
         "🧹 **LLM Wiki lint complete**",
         "",
@@ -904,6 +948,10 @@ function runWikiLint(paths, autoFix) {
         reportPath ? `📄 Report: \`${reportPath}\`` : "",
         repair?.manifestPath ? `🛟 Repair manifest: \`${repair.manifestPath}\`` : "",
         gaps.length ? `💡 ${gaps.length} knowledge gap(s) tracked` : "",
+        "",
+        "## QMD Index",
+        `- State: ${qmdStatus.state}`,
+        ...qmdFindings,
     ]
         .filter(Boolean)
         .join("\n");
@@ -927,7 +975,7 @@ export function registerWikiStatus(pi) {
                     isError: true,
                 };
             }
-            const status = getWikiStatus(paths);
+            const status = await getWikiStatus(paths);
             const config = readJson(join(paths.dotWiki, "config.json"), {});
             const backlinks = readJson(join(paths.meta, "backlinks.json"), {});
             const orphanCount = Object.entries(backlinks).filter(([, inbound]) => inbound.length === 0).length;
@@ -954,6 +1002,10 @@ export function registerWikiStatus(pi) {
                 `Gaps: ${gaps.gaps?.length || 0}`,
                 `Health: ${health}`,
                 `Last updated: ${status.lastUpdated || "Never"}`,
+                `QMD index: ${status.qmd.state}`,
+                `QMD documents: ${status.qmd.totalDocuments} (${status.qmd.canonicalDocuments} canonical, ${status.qmd.evidenceDocuments} evidence)`,
+                `QMD embeddings pending: ${status.qmd.needsEmbedding}`,
+                `QMD package: ${status.qmd.qmdVersion}`,
                 ...diagLines,
             ];
             return {
@@ -968,6 +1020,7 @@ export function registerWikiStatus(pi) {
                     gaps: gaps.gaps?.length || 0,
                     health,
                     blockingDiagnostics: status.blockingDiagnostics,
+                    qmd: status.qmd,
                 },
             };
         },
@@ -1009,6 +1062,22 @@ export function registerWikiRebuildMeta(pi, runtime) {
                         return `⚠️ LLM Wiki: rebuild had issues — ${result.diagnostics.map((d) => `${d.code}: ${d.message}`).join("; ")}`;
                     }
                     const warnings = result.diagnostics.filter((diagnostic) => diagnostic.severity === "warning");
+                    // After a successful projection, keep the generated QMD index in sync
+                    // (model-free lexical pass). A QMD failure is a warning, never a
+                    // projection failure.
+                    const qmdResult = await reindexQmdVault(paths, {
+                        scope: "changed",
+                        components: ["lexical"],
+                        force: false,
+                    });
+                    if (!qmdResult.ok) {
+                        warnings.push({
+                            severity: "warning",
+                            code: "qmd_index_error",
+                            path: paths.qmd,
+                            message: qmdResult.errors[0]?.message ?? "QMD indexing failed",
+                        });
+                    }
                     if (warnings.length > 0) {
                         return `⚠️ LLM Wiki: metadata rebuilt with warnings — ${warnings
                             .map((diagnostic) => `${diagnostic.code}: ${diagnostic.message}`)
@@ -1091,6 +1160,97 @@ export function registerWikiReindexEmbeddings(pi, runtime) {
         },
     });
 }
+export function registerWikiReindex(pi) {
+    pi.registerTool({
+        name: "wiki_reindex",
+        label: "Wiki Reindex QMD",
+        description: "Rebuild or repair the generated QMD index (meta/qmd) for the vault. " +
+            "Lexical indexing is model-free; selecting vectors may download " +
+            "approximately 2 GB of models on first use. Repair stale/error state. " +
+            "Active recall still uses the legacy heuristic until Phase 3.",
+        promptSnippet: "Rebuild the QMD search index",
+        promptGuidelines: [
+            "Use wiki_reindex to repair a stale, error, or recovering QMD index.",
+            "Lexical-only reindexing never loads a model.",
+            "Vector reindexing may download approximately 2 GB of models on first use.",
+        ],
+        parameters: Type.Object({
+            scope: Type.Optional(Type.Union([Type.Literal("changed"), Type.Literal("all")], { default: "changed" })),
+            components: Type.Optional(Type.Array(Type.Union([Type.Literal("lexical"), Type.Literal("vectors")]), {
+                minItems: 1,
+                uniqueItems: true,
+                default: ["lexical", "vectors"],
+            })),
+            force: Type.Optional(Type.Boolean({ default: false })),
+            vault: Type.Optional(Type.Union([
+                Type.Literal("active"),
+                Type.Literal("personal"),
+                Type.Literal("project"),
+                Type.Literal("all"),
+            ], { default: "active" })),
+        }),
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            const paths = getPaths(ctx.cwd);
+            const vaultCheck = inspectWritableVault(paths);
+            if (!vaultCheck.ok) {
+                return {
+                    content: [
+                        { type: "text", text: `Wiki vault error: ${vaultCheck.diagnostics[0].message}` },
+                    ],
+                    details: {
+                        error: vaultCheck.diagnostics[0].code,
+                        diagnostics: vaultCheck.diagnostics,
+                    },
+                    isError: true,
+                };
+            }
+            const scope = params.scope ?? "changed";
+            const components = params.components ?? ["lexical", "vectors"];
+            const force = params.force === true;
+            const vault = params.vault ?? "active";
+            const lexicalOnly = components.length === 1 && components[0] === "lexical";
+            // Warn before any vector work so the operator expects a large download.
+            if (components.includes("vectors") && signal && signal.aborted) {
+                return {
+                    content: [{ type: "text", text: "QMD reindex cancelled before it started." }],
+                    details: { cancelled: true },
+                    isError: true,
+                };
+            }
+            const result = await reindexWiki(paths, {
+                scope,
+                components,
+                force,
+                vault,
+                signal,
+            });
+            const ok = result.results.every((r) => r.result.ok);
+            const lines = [
+                ok ? "✅ QMD indexing complete" : "⚠️ QMD indexing completed with errors",
+                ...result.results.map((r) => {
+                    const st = r.result.status;
+                    return `- ${r.label} (${r.root}): state=${st.state}, documents=${st.totalDocuments}, indexed=${r.result.documents.indexed}, updated=${r.result.documents.updated}, removed=${r.result.documents.removed}, vectors=${r.result.vectors.generated}`;
+                }),
+            ];
+            if (lexicalOnly)
+                lines.push("Model-free lexical indexing — no model was downloaded.");
+            if (components.includes("vectors")) {
+                lines.push("⚠️ Vector indexing may download approximately 2 GB of models on first use.");
+            }
+            for (const r of result.results) {
+                for (const e of r.result.errors)
+                    lines.push(`- [${r.label}] ${e.code}: ${e.message}`);
+                for (const w of r.result.warnings)
+                    lines.push(`- [${r.label}] ${w.code}: ${w.message}`);
+            }
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+                details: { scope, components, ...result },
+                ...(ok ? {} : { isError: true }),
+            };
+        },
+    });
+}
 export function registerWikiLogEvent(pi) {
     pi.registerTool({
         name: "wiki_log_event",

package/dist/extensions/llm-wiki/lib/utils.js

@@ -162,30 +162,44 @@ export function resolveVaultRoot(cwd) {
 }
 /** Get all vault paths for the new (.llm-wiki) layout. */
 export function getVaultPaths(root) {
+    const meta = join(root, ".llm-wiki", "meta");
+    const qmd = join(meta, "qmd");
     return {
         root,
         raw: join(root, ".llm-wiki", "raw"),
         rawSources: join(root, ".llm-wiki", "raw", "sources"),
         rawTrajectories: join(root, ".llm-wiki", "raw", "trajectories"),
         wiki: join(root, ".llm-wiki", "wiki"),
-        meta: join(root, ".llm-wiki", "meta"),
+        meta,
         dotWiki: join(root, ".llm-wiki"),
         outputs: join(root, ".llm-wiki", "outputs"),
         discoveries: join(root, ".llm-wiki", ".discoveries"),
+        qmd,
+        qmdCurrent: join(qmd, "current"),
+        qmdDocuments: join(qmd, "documents"),
+        qmdManifest: join(qmd, "manifest.json"),
+        qmdSwap: join(qmd, "swap.json"),
     };
 }
 /** Get all vault paths for the legacy (.wiki) layout. */
 export function getLegacyVaultPaths(root) {
+    const meta = join(root, "meta");
+    const qmd = join(meta, "qmd");
     return {
         root,
         raw: join(root, "raw"),
         rawSources: join(root, "raw", "sources"),
         rawTrajectories: join(root, "raw", "trajectories"),
         wiki: join(root, "wiki"),
-        meta: join(root, "meta"),
+        meta,
         dotWiki: join(root, ".wiki"),
         outputs: join(root, "outputs"),
         discoveries: join(root, ".discoveries"),
+        qmd,
+        qmdCurrent: join(qmd, "current"),
+        qmdDocuments: join(qmd, "documents"),
+        qmdManifest: join(qmd, "manifest.json"),
+        qmdSwap: join(qmd, "swap.json"),
     };
 }
 /**

package/dist/extensions/llm-wiki/lib/wiki-service.js

@@ -1,11 +1,13 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { readJson } from "./utils.js";
-import { compareCodePoint, discoverKnowledgeDocuments, inspectVaultFormat, } from "./vault-format.js";
+import { awaitQmdIndexQueue, readQmdIndexStatus, reindexQmdVault, } from "./qmd-indexing.js";
+import { QMD_PACKAGE_VERSION, resolveQmdModels } from "./qmd-store.js";
+import { getPersonalWikiPaths, isPersonalVault, readJson } from "./utils.js";
+import { compareCodePoint, discoverKnowledgeDocuments, inspectVaultFormat, inspectWritableVault, } from "./vault-format.js";
 /**
  * Search the registry for matching concepts.
  *
- * Matches ID, semantic title, type, category, domain, tags, aliases, and recall triggers.
+ * Matches ID, title, type, state, status, category, domain, tags, aliases, and recall triggers.
  * Preserves unknown types as strings.
  */
 export function searchRegistry(paths, query, typeFilter) {
@@ -55,6 +57,16 @@ function matchesField(id, entry, query) {
         .toLowerCase()
         .includes(query))
         return true;
+    // Match state
+    if (String(entry.state || "")
+        .toLowerCase()
+        .includes(query))
+        return true;
+    // Match status
+    if (String(entry.status || "")
+        .toLowerCase()
+        .includes(query))
+        return true;
     // Match category/domain
     if (String(entry.category || "")
         .toLowerCase()
@@ -96,9 +108,10 @@ function matchesField(id, entry, query) {
 /**
  * Get a status snapshot of the wiki.
  *
- * Reports resolved knowledge_format, page counts, and blocking diagnostics.
+ * Reports resolved knowledge_format, page counts, blocking diagnostics, and
+ * generated QMD index status (read without opening any QMD store).
  */
-export function getWikiStatus(paths) {
+export async function getWikiStatus(paths) {
     const vaultState = inspectVaultFormat(paths);
     const diagnostics = [...vaultState.diagnostics];
     // Also check discovery for current concept health
@@ -124,5 +137,91 @@ export function getWikiStatus(paths) {
         byType,
         blockingDiagnostics: diagnostics.filter((d) => d.severity === "error"),
         lastUpdated: registry?.last_updated || "",
+        qmd: await readQmdIndexStatus(paths),
     };
 }
+function blockedReindexResult(scope, components, code, message) {
+    return {
+        ok: false,
+        scope,
+        components,
+        documents: { indexed: 0, updated: 0, unchanged: 0, removed: 0 },
+        vectors: { generated: 0, skipped: 0, errors: 0 },
+        elapsedMs: 0,
+        status: {
+            state: "error",
+            qmdVersion: QMD_PACKAGE_VERSION,
+            models: resolveQmdModels(),
+            totalDocuments: 0,
+            canonicalDocuments: 0,
+            evidenceDocuments: 0,
+            needsEmbedding: 0,
+            hasVectorIndex: false,
+            repairComponents: [],
+            issues: [{ code, message }],
+        },
+        warnings: [],
+        errors: [{ code, message }],
+    };
+}
+/**
+ * Reindex QMD stores for selected vaults, sequentially. Validates each vault
+ * immediately before work. One vault's failure does not prevent the others.
+ */
+export async function reindexWiki(activePaths, input) {
+    const scope = input.scope ?? "changed";
+    const components = input.components ?? ["lexical", "vectors"];
+    const force = input.force ?? false;
+    const vault = input.vault ?? "active";
+    const signal = input.signal;
+    const onProgress = input.onProgress;
+    const personalPaths = getPersonalWikiPaths();
+    const activeIsPersonal = isPersonalVault(activePaths);
+    const targets = [];
+    switch (vault) {
+        case "active":
+            targets.push({ paths: activePaths, label: activeIsPersonal ? "personal" : "active" });
+            break;
+        case "personal":
+            targets.push({ paths: personalPaths, label: "personal" });
+            break;
+        case "project":
+            if (!activeIsPersonal)
+                targets.push({ paths: activePaths, label: "project" });
+            break;
+        case "all":
+            if (!activeIsPersonal)
+                targets.push({ paths: activePaths, label: "project" });
+            targets.push({ paths: personalPaths, label: "personal" });
+            break;
+    }
+    const seen = new Set();
+    const results = [];
+    for (const target of targets) {
+        if (seen.has(target.paths.root))
+            continue;
+        seen.add(target.paths.root);
+        const check = inspectWritableVault(target.paths);
+        if (!check.ok) {
+            results.push({
+                root: target.paths.root,
+                label: target.label,
+                result: blockedReindexResult(scope, components, check.diagnostics[0]?.code ?? "config_invalid_knowledge_format", check.diagnostics[0]?.message ?? "Vault is not writable"),
+            });
+            continue;
+        }
+        const result = await reindexQmdVault(target.paths, {
+            scope,
+            components,
+            force,
+            signal,
+            onProgress: (p) => onProgress?.({ vault: target.paths.root, progress: p }),
+        });
+        results.push({ root: target.paths.root, label: target.label, result });
+    }
+    return { vault, results };
+}
+/** Test-only: drain/await in-process QMD reindex queue work for a vault root. */
+export function awaitWikiQmdIndexQueue(root) {
+    return awaitQmdIndexQueue(root);
+}

package/dist/mcp/index.js

@@ -13,10 +13,11 @@ import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
+import { recoverQmdIndex } from "../extensions/llm-wiki/lib/qmd-indexing.js";
 import { loadTaskConfig, resolveWikilinkValidation, } from "../extensions/llm-wiki/lib/task-config.js";
 import { getVaultPaths, resolveVaultPaths } from "../extensions/llm-wiki/lib/utils.js";
 import { createExecApi } from "./exec.js";
-import { bootstrapOperation, captureSourceOperation, recallOperation, retroOperation, searchOperation, statusOperation, } from "./operations.js";
+import { bootstrapOperation, captureSourceOperation, recallOperation, reindexOperation, retroOperation, searchOperation, statusOperation, } from "./operations.js";
 const execApi = createExecApi();
 // ─── Vault Detection ────────────────────────────────────
 /** Resolve vault paths, same as Pi extension. */
@@ -48,7 +49,7 @@ const server = new McpServer({
 // ---- wiki_bootstrap ----
 //
 // Registered first, and the only tool not gated on an existing vault: the
-// other five fail closed with a message naming this one, which an MCP-only
+// other tools fail closed with a message naming this one, which an MCP-only
 // client could not act on while it was extension-only (issue #130).
 server.registerTool("wiki_bootstrap", {
     description: "Create an LLM Wiki vault at this server's wiki root (WIKI_ROOT, or the working directory). Writes config, schema, templates and metadata scaffolding. Run this first when no vault exists; safe to re-run on an existing vault, where it updates the config and rebuilds metadata without touching pages.",
@@ -182,6 +183,56 @@ server.registerTool("wiki_status", {
         ],
     };
 });
+// ---- wiki_reindex ----
+server.registerTool("wiki_reindex", {
+    description: "Rebuild or repair the generated QMD search index (meta/qmd) for the vault. " +
+        "Lexical indexing is model-free; selecting vectors may download approximately 2 GB " +
+        "of models on first use. Options: scope (changed|all), components (lexical|vectors), " +
+        "force, vault (active|personal|project|all).",
+    inputSchema: z.object({
+        scope: z.enum(["changed", "all"]).optional().default("changed").describe("changed or all"),
+        components: z
+            .array(z.enum(["lexical", "vectors"]))
+            .min(1)
+            .optional()
+            .describe("Index components (lexical|vectors)"),
+        force: z.boolean().optional().describe("Force full rebuild of selected components"),
+        vault: z
+            .enum(["active", "personal", "project", "all"])
+            .optional()
+            .default("active")
+            .describe("Which vaults to reindex"),
+    }),
+}, async ({ scope, components, force, vault }) => {
+    if (!hasVault()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No wiki vault found. Set WIKI_ROOT or run wiki_bootstrap first.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const paths = getPaths();
+    const result = await reindexOperation(paths, {
+        scope,
+        components,
+        force,
+        vault,
+    });
+    const ok = result.results.every((r) => r.result.ok);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+        ...(ok ? {} : { isError: true }),
+    };
+});
 // ---- wiki_retro ----
 server.registerTool("wiki_retro", {
     description: "Save an atomic insight from a completed task into the wiki. Creates a source page.",
@@ -276,6 +327,19 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("🧠 LLM Wiki MCP Server running on stdio");
+    // Fire-and-forget QMD index recovery AFTER the transport is connected so
+    // clients are never blocked. A busy/live lock just logs a warning and MCP
+    // continues with current state untouched.
+    if (hasVault()) {
+        const paths = getPaths();
+        recoverQmdIndex(paths)
+            .then((result) => {
+            if (!result.ok) {
+                console.error(`[llm-wiki] QMD recovery skipped: ${result.diagnostics[0]?.message ?? "locked"}`);
+            }
+        })
+            .catch((err) => console.error(`[llm-wiki] QMD recovery failed: ${err.message}`));
+    }
 }
 main().catch((err) => {
     console.error("MCP Server error:", err);