@zosmaai/pi-llm-wiki 0.11.4 → 0.11.6

package/dist/extensions/llm-wiki/lib/ingest-worker.js

@@ -2,9 +2,11 @@ import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { Type } from "typebox";
 import { createKnowledgeDocument, patchKnowledgeDocument, readKnowledgeDocumentFile, serializeKnowledgeDocument, writeKnowledgeDocumentFile, } from "./knowledge-document.js";
+import { auditWikilinks, buildWikilinkIndex, } from "./knowledge-links.js";
 import { appendEvent, rebuildMetadataLight } from "./metadata.js";
 import { runSubAgent } from "./subagent.js";
-import { fmtDate, slugify } from "./utils.js";
+import { resolveWikilinkValidation } from "./task-config.js";
+import { fmtDate, readJson, slugify } from "./utils.js";
 import { VaultWriteError, assertWritableVault } from "./vault-format.js";
 /**
  * Background ingest synthesis (issue #65, part of epic #63).
@@ -141,32 +143,22 @@ function getHeadings(lang) {
         contradiction: "⚠️ **Contradiction**",
     };
 }
-function buildEntityPageBody(title, description, sourceId, lang) {
+function buildEntityPageBody(title, description, sourceId) {
     const desc = description.trim() || "One-line description.";
-    const h = getHeadings(lang);
     return `# ${title}
 
 ${desc}
 
-## ${h.overview}
-
-[Key facts]
-
 ## Links
 
 - [${sourceId}](/sources/${sourceId}.md)`;
 }
-function buildConceptPageBody(title, definition, sourceId, lang) {
+function buildConceptPageBody(title, definition, sourceId) {
     const def = definition.trim() || "One-line definition.";
-    const h = getHeadings(lang);
     return `# ${title}
 
 ${def}
 
-## ${h.definition}
-
-[Clear explanation]
-
 ## Links
 
 - [${sourceId}](/sources/${sourceId}.md)`;
@@ -241,12 +233,29 @@ export function buildIngestedSourcePage(manifest, data, date, lang) {
     }, body);
     return serializeKnowledgeDocument(doc);
 }
+/**
+ * Build the wikilink index used by the pre-write gate: every existing page id
+ * (from the registry) plus the page ids this commit is about to create, so a
+ * link to a sibling created in the same ingest resolves instead of
+ * false-positiving as missing.
+ */
+function buildIngestAuditIndex(paths, sourceId, data) {
+    const registry = readJson(join(paths.meta, "registry.json"), {
+        pages: {},
+    });
+    const newIds = [
+        `sources/${sourceId}`,
+        ...data.entities.filter((e) => slugify(e.title)).map((e) => `entities/${slugify(e.title)}`),
+        ...data.concepts.filter((c) => slugify(c.title)).map((c) => `concepts/${slugify(c.title)}`),
+    ];
+    return buildWikilinkIndex([...Object.keys(registry.pages), ...newIds]);
+}
 /**
  * Persist a synthesis deterministically: rewrite the source page (status →
  * ingested), create missing entity/concept pages (existing pages are linked,
  * never overwritten), and log the event. Pure file I/O — no LLM, no network.
  */
-export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(), lang) {
+export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(), lang, wikilinkValidation) {
     const result = {
         sourceId,
         sourcePage: join(paths.wiki, "sources", `${sourceId}.md`),
@@ -265,6 +274,20 @@ export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(
         }
         throw error;
     }
+    // Pre-write wikilink gate (issue #172, Layer 2). Applies only to the
+    // model-authored source body; entity/concept pages are generated templates.
+    const mode = resolveWikilinkValidation({ wikilinkValidation });
+    let sourceBody = buildIngestedSourcePageBody(manifest, data, date, lang);
+    if (mode !== "off") {
+        const audit = auditWikilinks(sourceBody, buildIngestAuditIndex(paths, sourceId, data), sourceId, mode);
+        if (mode === "strict" && audit.diagnostics.length > 0) {
+            return { ok: false, sourceId, diagnostics: audit.diagnostics };
+        }
+        if (mode === "normalize")
+            sourceBody = audit.body;
+        if (audit.diagnostics.length > 0)
+            result.wikilinkDiagnostics = audit.diagnostics;
+    }
     // Patch existing documents so unknown fields, legacy sources, and titles survive.
     let sourceDocument;
     if (existsSync(result.sourcePage)) {
@@ -273,7 +296,7 @@ export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(
             return { ok: false, sourceId, diagnostics: parsed.diagnostics };
         sourceDocument = patchKnowledgeDocument(parsed.document, {
             fields: { status: "ingested", updated: date },
-            body: buildIngestedSourcePageBody(manifest, data, date, lang),
+            body: sourceBody,
         });
     }
     else {
@@ -286,7 +309,7 @@ export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(
             captured: String(manifest.captured || date),
             status: "ingested",
             updated: date,
-        }, buildIngestedSourcePageBody(manifest, data, date, lang));
+        }, sourceBody);
     }
     mkdirSync(join(paths.wiki, "sources"), { recursive: true });
     writeKnowledgeDocumentFile(result.sourcePage, sourceDocument);
@@ -307,7 +330,7 @@ export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(
                 description: e.description.trim() || "One-line description.",
                 created: date,
                 updated: date,
-            }, buildEntityPageBody(e.title, e.description, sourceId, lang), [{ id: sourceId, resource: `/sources/${sourceId}.md` }]);
+            }, buildEntityPageBody(e.title, e.description, sourceId), [{ id: sourceId, resource: `/sources/${sourceId}.md` }]);
             writeKnowledgeDocumentFile(pagePath, entityDoc);
             result.entitiesCreated.push(slug);
         }
@@ -329,7 +352,7 @@ export function commitSynthesis(paths, sourceId, manifest, data, date = fmtDate(
                 description: c.definition.trim() || "One-line definition.",
                 created: date,
                 updated: date,
-            }, buildConceptPageBody(c.title, c.definition, sourceId, lang), [{ id: sourceId, resource: `/sources/${sourceId}.md` }]);
+            }, buildConceptPageBody(c.title, c.definition, sourceId), [{ id: sourceId, resource: `/sources/${sourceId}.md` }]);
             writeKnowledgeDocumentFile(pagePath, conceptDoc);
             result.conceptsCreated.push(slug);
         }
@@ -365,7 +388,7 @@ Rules:
  * synthesis.
  */
 export async function runIngestSynthesis(args) {
-    const { model, apiKey, headers, paths, sourceId, manifest, extracted, maxChars, signal, synthesisLanguage, } = args;
+    const { model, apiKey, headers, paths, sourceId, manifest, extracted, maxChars, signal, synthesisLanguage, synthesisMaxTokens, wikilinkValidation, } = args;
     const content = extracted.slice(0, maxChars ?? 24_000);
     if (!content.trim())
         return undefined;
@@ -380,7 +403,7 @@ export async function runIngestSynthesis(args) {
         description: "Persist the structured synthesis of this source into wiki pages. Call exactly once.",
         parameters: CommitSynthesisSchema,
         execute: async (_id, params) => {
-            const outcome = commitSynthesis(paths, sourceId, manifest, params, undefined, synthesisLanguage);
+            const outcome = commitSynthesis(paths, sourceId, manifest, params, undefined, synthesisLanguage, wikilinkValidation);
             if (!outcome.ok) {
                 return {
                     content: [{ type: "text", text: `Failed: ${outcome.diagnostics[0].message}` }],
@@ -402,6 +425,7 @@ export async function runIngestSynthesis(args) {
         systemPrompt,
         userPrompt,
         tools: [commitTool],
+        maxTokens: synthesisMaxTokens ?? 16384,
         signal,
     });
     if (committed)

package/dist/extensions/llm-wiki/lib/knowledge-document.js

@@ -383,6 +383,22 @@ export function serializeKnowledgeDocument(document) {
     const body = document.body.replace(/\r\n?/g, "\n").replace(/\n*$/, "");
     return body ? `---\n${yaml}---\n\n${body}\n` : `---\n${yaml}---\n`;
 }
+/** Escape wikilink alias pipes so generated content remains valid in Markdown tables. */
+function escapeWikilinkAliasPipes(body) {
+    let inFence = false;
+    return body
+        .split("\n")
+        .map((line) => {
+        if (/^\s*(`{3,}|~{3,})/.test(line)) {
+            inFence = !inFence;
+            return line;
+        }
+        if (inFence)
+            return line;
+        return line.replace(/\[\[([^\]\n]*?)(?<!\\)\|([^\]\n]*?)\]\]/g, "[[$1\\|$2]]");
+    })
+        .join("\n");
+}
 export function createKnowledgeDocument(path, fields, body, sources) {
     if (Object.hasOwn(fields, "sources")) {
         throw new Error("Pass canonical sources as the fourth argument");
@@ -402,7 +418,7 @@ export function createKnowledgeDocument(path, fields, body, sources) {
     const sourcesUnion = sources
         ? { kind: "canonical", value: sources }
         : { kind: "absent" };
-    const normalizedBody = body.replace(/\r\n?/g, "\n").replace(/\n*$/, "");
+    const normalizedBody = escapeWikilinkAliasPipes(body.replace(/\r\n?/g, "\n")).replace(/\n*$/, "");
     return {
         id: path.replace(/\.md$/, ""),
         path,
@@ -425,7 +441,9 @@ export function patchKnowledgeDocument(document, patch) {
             }
         }
     }
-    const newBody = patch.body ?? document.body;
+    const newBody = patch.body
+        ? escapeWikilinkAliasPipes(patch.body.replace(/\r\n?/g, "\n"))
+        : document.body;
     return {
         ...document,
         frontmatter: newFrontmatter,

package/dist/extensions/llm-wiki/lib/knowledge-links.js

@@ -1,14 +1,18 @@
 import { fromMarkdown } from "mdast-util-from-markdown";
+import { slugify } from "./utils.js";
 import { compareCodePoint } from "./vault-format.js";
 function diag(severity, code, path, message) {
     return { severity, code, path, message };
 }
+function normalizeWikilinkTarget(target) {
+    return target.trim().replace(/\\$/, "");
+}
 export function extractKnowledgeLinks(body) {
     const markdown = [];
     const wikilinks = [];
-    // Extract legacy wikilinks
+    // Extract legacy wikilinks. A table-safe alias uses an escaped pipe: [[target\\|alias]].
     for (const match of body.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) {
-        wikilinks.push({ target: match[1].trim(), offset: match.index ?? 0 });
+        wikilinks.push({ target: normalizeWikilinkTarget(match[1]), offset: match.index ?? 0 });
     }
     // Parse with CommonMark AST
     let tree;
@@ -72,10 +76,59 @@ export function extractKnowledgeLinks(body) {
 export function extractLegacyWikilinks(body) {
     const links = [];
     for (const match of body.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) {
-        links.push({ target: match[1].trim(), offset: match.index ?? 0 });
+        links.push({ target: normalizeWikilinkTarget(match[1]), offset: match.index ?? 0 });
     }
     return links;
 }
+export function buildWikilinkIndex(ids) {
+    const byExact = new Map();
+    const byNormPath = new Map();
+    const byNormSlug = new Map();
+    function push(map, key, value) {
+        const existing = map.get(key);
+        if (existing)
+            existing.push(value);
+        else
+            map.set(key, [value]);
+    }
+    for (const id of ids) {
+        byExact.set(id.normalize("NFC"), id);
+        const segments = id.split("/");
+        const normFull = segments.map((s) => slugify(s)).join("/");
+        const normBase = slugify(segments[segments.length - 1]);
+        push(byNormPath, normFull, id);
+        push(byNormSlug, normBase, id);
+    }
+    return { byExact, byNormPath, byNormSlug };
+}
+export function resolveWikilink(target, index) {
+    const cleaned = target.trim().replace(/\\$/, "");
+    if (!cleaned)
+        return { kind: "missing", target: "" };
+    // Fast path: exact NFC match
+    const exact = index.byExact.get(cleaned.normalize("NFC"));
+    if (exact)
+        return { kind: "resolved", id: exact };
+    // Normalized full path (fixes case/space/slug drift in folder-qualified links)
+    const normFull = cleaned
+        .split("/")
+        .map((s) => slugify(s))
+        .join("/");
+    const pathHits = index.byNormPath.get(normFull);
+    if (pathHits && pathHits.length === 1)
+        return { kind: "resolved", id: pathHits[0] };
+    if (pathHits && pathHits.length > 1)
+        return { kind: "ambiguous", target: cleaned, candidates: pathHits };
+    // Bare title: match by slugified basename (handles [[zosma harness]] → entities/zosma-harness)
+    if (!cleaned.includes("/")) {
+        const baseHits = index.byNormSlug.get(slugify(cleaned));
+        if (baseHits && baseHits.length === 1)
+            return { kind: "resolved", id: baseHits[0] };
+        if (baseHits && baseHits.length > 1)
+            return { kind: "ambiguous", target: cleaned, candidates: baseHits };
+    }
+    return { kind: "missing", target: cleaned };
+}
 function resolveMarkdownTarget(target, sourceId) {
     // Strip query and fragment (earliest delimiter)
     const qIndex = target.indexOf("?");
@@ -153,14 +206,7 @@ function resolveMarkdownTarget(target, sourceId) {
     }
     return { kind: "empty" };
 }
-function resolveWikilinkTarget(target) {
-    // Wikilinks are already bundle-relative concept IDs
-    const cleaned = target.trim();
-    if (!cleaned)
-        return { kind: "empty" };
-    return { kind: "concept", id: cleaned };
-}
-export function buildResolvedBacklinks(sourceId, body, knownIds) {
+export function buildResolvedBacklinks(sourceId, body, index) {
     const diagnostics = [];
     const unresolved = [];
     const targets = new Set();
@@ -175,32 +221,92 @@ export function buildResolvedBacklinks(sourceId, body, knownIds) {
             diagnostics.push(diag("warning", "link_unresolved", `${sourceId}.md`, `Malformed percent-encoded link: ${link.target}`));
         }
         else if (resolved.kind === "concept") {
-            const normalizedId = resolved.id.normalize("NFC");
-            if (knownIds.has(normalizedId)) {
-                targets.add(normalizedId);
+            const canonical = index.byExact.get(resolved.id.normalize("NFC"));
+            if (canonical) {
+                targets.add(canonical);
             }
             else {
-                unresolved.push({ target: normalizedId, syntax: "markdown" });
-                diagnostics.push(diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved link: ${normalizedId}`));
+                unresolved.push({ target: resolved.id, syntax: "markdown" });
+                diagnostics.push(diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved link: ${resolved.id}`));
             }
         }
         // external and empty are silently ignored
     }
-    // Process wikilinks
+    // Process wikilinks (lenient: exact → normalized path → bare title)
     for (const link of allLinks.wikilinks) {
-        const resolved = resolveWikilinkTarget(link.target);
-        if (resolved.kind === "concept") {
-            const normalizedId = resolved.id.normalize("NFC");
-            if (knownIds.has(normalizedId)) {
-                targets.add(normalizedId);
-            }
-            else {
-                unresolved.push({ target: normalizedId, syntax: "wikilink" });
-                diagnostics.push(diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved wikilink: ${normalizedId}`));
-            }
+        const res = resolveWikilink(link.target, index);
+        if (res.kind === "resolved") {
+            targets.add(res.id);
+        }
+        else if (res.kind === "ambiguous") {
+            diagnostics.push(diag("warning", "link_ambiguous", `${sourceId}.md`, `Ambiguous wikilink: ${res.target} (candidates: ${res.candidates.join(", ")})`));
+        }
+        else {
+            unresolved.push({ target: res.target, syntax: "wikilink" });
+            diagnostics.push(diag("warning", "link_unresolved", `${sourceId}.md`, `Unresolved wikilink: ${res.target}`));
         }
     }
     // Sort and deduplicate
     const sorted = [...targets].sort(compareCodePoint);
     return { targets: sorted, unresolved, diagnostics };
 }
+const WIKILINK_REPLACE_RE = /\[\[([^\]|]+)(\|[^\]]*)?\]\]/g;
+/**
+ * Audit a markdown body's wikilinks against the page index.
+ *
+ * - Collects `link_unresolved` / `link_ambiguous` diagnostics for every link
+ *   that does not resolve to exactly one page (skipped for "off").
+ * - In "normalize" mode, additionally rewrites each link that DOES resolve to
+ *   its canonical page id. Only the target token is replaced (the parser's own
+ *   regex is reused), so `|alias`, escaping, and surrounding text are preserved.
+ *
+ * Pure: no I/O. The caller supplies the index (typically `buildWikilinkIndex`
+ * over existing page ids plus the ids created by the same commit).
+ */
+export function auditWikilinks(body, index, sourceId, mode) {
+    if (mode === "off")
+        return { diagnostics: [], body, changed: false };
+    const diagnostics = [];
+    for (const { target } of extractKnowledgeLinks(body).wikilinks) {
+        const resolved = resolveWikilink(target, index);
+        if (resolved.kind === "ambiguous") {
+            diagnostics.push({
+                severity: "warning",
+                code: "link_ambiguous",
+                path: sourceId,
+                message: `Wikilink target "${target}" matches multiple pages (${resolved.candidates.join(", ")}).`,
+            });
+        }
+        else if (resolved.kind === "missing") {
+            diagnostics.push({
+                severity: "warning",
+                code: "link_unresolved",
+                path: sourceId,
+                message: `Wikilink target "${target}" does not match any page.`,
+            });
+        }
+    }
+    let out = body;
+    if (mode === "normalize") {
+        out = body.replace(WIKILINK_REPLACE_RE, (full, raw, alias) => {
+            const resolved = resolveWikilink(normalizeWikilinkTarget(raw), index);
+            return resolved.kind === "resolved" ? `[[${resolved.id}${alias ?? ""}]]` : full;
+        });
+    }
+    return { diagnostics, body: out, changed: out !== body };
+}
+/**
+ * Apply the pre-write wikilink gate to a body. Wraps {@link auditWikilinks}:
+ * blocks (ok:false) only in strict mode with issues, rewrites in normalize mode,
+ * and always returns the diagnostics so callers can surface them (warn/normalize).
+ */
+export function applyWikilinkGate(body, index, sourceId, mode) {
+    if (mode === "off")
+        return { ok: true, body, diagnostics: [] };
+    const audit = auditWikilinks(body, index, sourceId, mode);
+    return {
+        ok: !(mode === "strict" && audit.diagnostics.length > 0),
+        body: mode === "normalize" ? audit.body : body,
+        diagnostics: audit.diagnostics,
+    };
+}

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

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
-import { buildResolvedBacklinks } from "./knowledge-links.js";
+import { buildResolvedBacklinks, buildWikilinkIndex, } from "./knowledge-links.js";
 import { isPathWithin, readJson } from "./utils.js";
 import { assertWritableVault, compareCodePoint, discoverKnowledgeDocuments, inspectVaultFormat, } from "./vault-format.js";
 /** Rebuild the complete metadata layer with fail-closed semantics. */
@@ -24,8 +24,8 @@ export function rebuildMetadata(paths) {
     // Step 3: Build registry from documents + raw fallbacks
     const registry = buildRegistry(paths, documents);
     // Step 4: Build backlinks from discovered documents
-    const knownIds = new Set(documents.map((d) => d.id));
-    const backlinks = buildBacklinks(documents, knownIds, allDiagnostics);
+    const wikilinkIndex = buildWikilinkIndex(documents.map((d) => d.id));
+    const backlinks = buildBacklinks(documents, wikilinkIndex, allDiagnostics);
     const eventSource = readEventSource(join(paths.meta, "events.jsonl"));
     const eventLogResult = eventSource.available ? buildOkfLog(eventSource.content) : undefined;
     if (eventLogResult)
@@ -157,7 +157,7 @@ function getSemanticTitle(doc) {
     return doc.id.split("/").pop() || "Untitled";
 }
 /** Build backlinks from discovered documents using shared link resolution. */
-function buildBacklinks(documents, knownIds, diagnostics) {
+function buildBacklinks(documents, index, diagnostics) {
     const inbound = {};
     // Initialize parsed concept IDs with empty arrays
     for (const doc of documents) {
@@ -165,7 +165,7 @@ function buildBacklinks(documents, knownIds, diagnostics) {
     }
     // Resolve links for each document
     for (const doc of documents) {
-        const result = buildResolvedBacklinks(doc.id, doc.body, knownIds);
+        const result = buildResolvedBacklinks(doc.id, doc.body, index);
         diagnostics.push(...result.diagnostics);
         for (const target of result.targets) {
             if (inbound[target] && !inbound[target].includes(doc.id)) {
@@ -386,7 +386,7 @@ export function buildDirectoryIndexes(documents, config) {
             lines.push("## Directories");
             lines.push("");
             for (const subDir of [...dirs].sort(compareCodePoint)) {
-                const encoded = `${encodeRelativePath(subDir)}/`;
+                const encoded = encodeRelativePath(`${subDir}/index.md`);
                 lines.push(`- [${escapeLabel(subDir)}/](${encoded})`);
             }
         }

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

@@ -256,9 +256,11 @@ export function registerObservationReminder(pi, reminderState, options) {
         return true;
     };
     let turnsSinceLastReminder = 0;
+    let agentEndsInUserTurn = 0;
     pi.on("session_start", async () => {
         turnsSinceLastReminder = 0;
         reminderState.observeDoneThisSession = false;
+        agentEndsInUserTurn = 0;
     });
     // After compaction, reset turn counter so reminders resume
     // BUT preserve observeDoneThisSession — if the model already called
@@ -266,10 +268,18 @@ export function registerObservationReminder(pi, reminderState, options) {
     pi.on("session_compact", async () => {
         turnsSinceLastReminder = 0;
     });
+    // A retry re-runs the agent within the same user turn, and pi does not
+    // forward `willRetry` to extensions (zosmaai/pi-llm-wiki#151). Only the
+    // user-role message_start separates real user turns from retried agent
+    // runs, so the per-turn agent_end count resets there.
+    pi.on("message_start", async (event) => {
+        if (event.message.role === "user")
+            agentEndsInUserTurn = 0;
+    });
     pi.on("agent_end", async (event, _ctx) => {
-        // Skip reminder on retries — willRetry means pi will re-run the agent,
-        // and queuing another reminder would duplicate them (issue: connection
-        // errors cause multiple retries, each firing agent_end).
+        // Legacy guard: this pi build does not forward `willRetry` to extension
+        // events, but keep the check in case a future one does. The dedup that
+        // actually works is the per-turn agent_end count below.
         if ("willRetry" in event && event.willRetry)
             return;
         // No wiki applies here: never nag, and never accumulate a pending reminder
@@ -281,6 +291,12 @@ export function registerObservationReminder(pi, reminderState, options) {
             return;
         if (reminderState.observeDoneThisSession)
             return;
+        // One agent_end per user turn may queue a reminder. A rate-limit storm
+        // re-runs the agent several times within the same turn, each firing
+        // agent_end, so count them and let only the first through.
+        agentEndsInUserTurn++;
+        if (agentEndsInUserTurn > 1)
+            return;
         pi.sendMessage({
             customType: "wiki-observe-reminder",
             content: buildReminderText(),
@@ -288,5 +304,8 @@ export function registerObservationReminder(pi, reminderState, options) {
         }, {
             deliverAs: "nextTurn",
         });
+        // Reset the interval counter after queueing: without it the count stays
+        // at/above the threshold and every later agent_end queues a reminder.
+        turnsSinceLastReminder = 0;
     });
 }

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

@@ -1,9 +1,11 @@
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { Type } from "typebox";
 import { scheduleReindex } from "./indexing.js";
 import { createKnowledgeDocument, writeKnowledgeDocumentFile } from "./knowledge-document.js";
+import { applyWikilinkGate, buildWikilinkIndex } from "./knowledge-links.js";
 import { appendEvent, rebuildMetadataLight } from "./metadata.js";
-import { fmtDate, resolveVaultPaths } from "./utils.js";
+import { loadTaskConfig, resolveWikilinkValidation } from "./task-config.js";
+import { fmtDate, readJson, resolveVaultPaths } from "./utils.js";
 import { assertWritableVault, inspectWritableVault } from "./vault-format.js";
 /**
  * Save an atomic insight into the wiki as a single markdown file.
@@ -115,9 +117,34 @@ export function registerWikiRetro(pi, runtime) {
                     isError: true,
                 };
             }
+            // Pre-write wikilink gate (#172): validate/normalize caller-supplied body.
+            const mode = resolveWikilinkValidation(loadTaskConfig(ctx.cwd ?? process.cwd()));
+            let body = params.body;
+            let wikilinkIssues = [];
+            if (mode !== "off") {
+                const registry = readJson(join(paths.meta, "registry.json"), { pages: {} });
+                const gate = applyWikilinkGate(body, buildWikilinkIndex(Object.keys(registry.pages)), `sources/${params.slug}`, mode);
+                wikilinkIssues = gate.diagnostics.map((d) => d.message);
+                if (!gate.ok) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Rejected write — unresolved/ambiguous wikilinks:\n${wikilinkIssues
+                                    .map((m) => `- ${m}`)
+                                    .join("\n")}`,
+                            },
+                        ],
+                        details: { error: "link_validation", issues: wikilinkIssues },
+                        isError: true,
+                    };
+                }
+                if (mode === "normalize")
+                    body = gate.body;
+            }
             let result;
             try {
-                result = saveInsight(paths, params.slug, params.title, params.body, params.category, {
+                result = saveInsight(paths, params.slug, params.title, body, params.category, {
                     rebuild: !runtime,
                 });
             }
@@ -134,6 +161,9 @@ export function registerWikiRetro(pi, runtime) {
             if (runtime) {
                 scheduleReindex(runtime, { hasUI: ctx.hasUI, ui: ctx.ui }, paths);
             }
+            const gateNote = wikilinkIssues.length
+                ? `\n\n⚠️ ${wikilinkIssues.length} wikilink issue(s):\n${wikilinkIssues.map((m) => `- ${m}`).join("\n")}`
+                : "";
             return {
                 content: [
                     {
@@ -144,13 +174,17 @@ export function registerWikiRetro(pi, runtime) {
                             `- Page: \`${result.sourcePagePath}\``,
                             "",
                             "This insight will be auto-surfaced by wiki_recall in future sessions.",
-                        ].join("\n"),
+                            gateNote,
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
                     },
                 ],
                 details: {
                     slug: params.slug,
                     title: params.title,
                     category: params.category || null,
+                    wikilinkIssues,
                 },
             };
         },

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

@@ -64,11 +64,11 @@ export class Runtime {
             };
         }
         const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-        if (!auth.ok || !auth.apiKey) {
+        if (!auth.ok) {
             const provider = model.provider ?? "unknown";
             return { ok: false, reason: `no API key for provider "${provider}"` };
         }
-        return { ok: true, model, apiKey: auth.apiKey, headers: auth.headers };
+        return { ok: true, model, apiKey: auth.apiKey ?? "", headers: auth.headers };
     }
     /**
      * Fire-and-forget a background task.