@zosmaai/pi-llm-wiki 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -6,6 +6,12 @@
 - **Personal wiki created at doubled path `~/.llm-wiki/.llm-wiki/…`**: `getPersonalWikiRoot()` returned the dot-dir itself (`~/.llm-wiki`) while `getVaultPaths()` then appended another `.llm-wiki/` segment, so the personal vault was written to `~/.llm-wiki/.llm-wiki/wiki/…`. Fixed by aligning `getPersonalWikiRoot()` with the same "root = parent of `.llm-wiki/`" contract used by project vaults. `WIKI_HOME` continues to override the parent.
 
 ### Added
+- **Visible wiki activity + background/reported mutations** (Issue #77): the wiki was effectively invisible — recall was appended only to the **system prompt**, the observe/retro reminder was sent with `display: false`, and the lone user-facing cue was a static status line. The wiki now surfaces what it does, and mutating work is pushed off the agent's critical path.
+  - **Visible surfaces**: a one-time **session notice** (`buildSessionNotice`) announces the full loop — retrieval (recall → `wiki_search` → `read`, all synchronous because the LLM consumes their output) and capture (`wiki_observe` → `wiki_retro`, background + reported); the periodic reminder is now `display: true` and names **both** capture tools (`buildReminderText`); and the status line becomes **recall-aware** (`🧠 LLM Wiki — recalled N page(s) for this task`) when auto-recall matches.
+  - **Background + reported principle**: only `wiki_search` / `read` / `wiki_recall` stay synchronous. Heavy mutations — `wiki_rebuild_meta`, `wiki_reindex_embeddings`, `wiki_lint` — now dispatch to the background runtime and **report a visible completion message** instead of blocking the turn; `wiki_ingest` gained a persistent completion report alongside its toast. New `Runtime.report()` / `Runtime.launchReported()` primitives and a `dispatchReported()` tool helper (with a synchronous fallback when no runtime is available, preserving prior behavior and unit tests).
+  - **`notices` setting** (namespaced `llm-wiki`, default **on**): set `false` to restore the previous quiet behavior — static status line and silently-injected (`display: false`) reminders/reports.
+  - **Fixed** a dangling reference to a non-existent `wiki_read` tool in the links-first recall output (now points at `read`).
+  - **16 tests** (`test/visible-activity.test.ts`, `test/background-tools.test.ts`): `notices` parsing/defaulting, reminder + session-notice content, `Runtime.report`/`launchReported` (display gating, no-pi no-op, error isolation, null-summary skip), and `wiki_rebuild_meta` background-dispatch + report vs synchronous fallback.
 - **Model selection surface for background tasks** (Issue #69, part of epic #63): the wiki background lane (ingest synthesis, etc.) now has a user-facing surface to choose its model, defaulting to the **session model** with zero config.
   - **`/wiki-model` slash command**: run with no argument for an interactive picker (lists `modelRegistry.getAvailable()`); `/wiki-model provider/id` to set directly (scriptable, no UI needed); `/wiki-model session` (or `clear`/`default`/`reset`) to revert to the session model. The choice is **persisted** to project settings (`.pi/settings.json` under `llm-wiki.taskModel`, preserving other keys) and applied immediately, with a status-bar label of the active model.
   - **Per-call `model` override** on heavy tools (`wiki_ingest`): an optional `'provider/id'` param that overrides the configured `taskModel` for that one call. Precedence is **override > configured taskModel > session model**; each layer is applied only when the model is in the registry, and a missing/unknown layer warns (when UI is available) and falls through — so a bad ref degrades gracefully instead of failing.

package/extensions/llm-wiki/index.ts

@@ -8,6 +8,7 @@ import {
   registerWikiModelCommand,
 } from "./lib/model-command.js";
 import {
+  buildSessionNotice,
   createReminderState,
   registerObservationReminder,
   registerWikiObserve,
@@ -21,6 +22,7 @@ import {
 } from "./lib/recall.js";
 import { registerWikiRetro } from "./lib/retro.js";
 import { registerBackgroundRuntime } from "./lib/runtime.js";
+import { noticesEnabled } from "./lib/task-config.js";
 import {
   registerWikiBootstrap,
   registerWikiCaptureSource,
@@ -71,9 +73,9 @@ export default function (pi: ExtensionAPI) {
   registerWikiIngest(pi, runtime);
   registerWikiEnsurePage(pi, runtime);
   registerWikiSearch(pi);
-  registerWikiLint(pi);
+  registerWikiLint(pi, runtime);
   registerWikiStatus(pi);
-  registerWikiRebuildMeta(pi);
+  registerWikiRebuildMeta(pi, runtime);
   registerWikiReindexEmbeddings(pi, runtime);
   registerWikiLogEvent(pi);
   registerWikiWatch(pi);
@@ -85,7 +87,12 @@ export default function (pi: ExtensionAPI) {
   registerWikiModelCommand(pi, runtime);
   const reminderState = createReminderState();
   registerWikiObserve(pi, runtime, reminderState);
-  registerObservationReminder(pi, reminderState);
+  // Visible observe/retro reminder by default (issue #77); silenced when the
+  // user sets `llm-wiki.notices: false`. Resolver reads the live config so the
+  // setting takes effect without a restart.
+  registerObservationReminder(pi, reminderState, {
+    display: () => noticesEnabled(runtime.config),
+  });
 
   installGuardrails(pi, runtime);
 
@@ -151,6 +158,17 @@ export default function (pi: ExtensionAPI) {
     runtime.ensureConfig(process.cwd());
     const modelLabel = formatActiveModelLabel(runtime.config, (ctx.model as { id?: string })?.id);
     ctx.ui.setStatus(MODEL_STATUS_KEY, `🧠 wiki model: ${modelLabel}`);
+
+    // One-time, user-visible session notice announcing the full wiki loop
+    // (issue #77). Without this, recall/observe/retro are invisible — they
+    // live only in the system prompt. Queued for the first prompt so it never
+    // interrupts; silenced when `llm-wiki.notices: false`.
+    if (noticesEnabled(runtime.config)) {
+      pi.sendMessage(
+        { customType: "wiki-session-notice", content: buildSessionNotice(), display: true },
+        { deliverAs: "nextTurn" },
+      );
+    }
   });
 
   // ─── Layered recall + topic inference hook ──────────
@@ -158,7 +176,7 @@ export default function (pi: ExtensionAPI) {
   // 1. If wiki was just auto-created, inject a directive to infer topic/mode
   //    from the user's first prompt and update config via wiki_bootstrap.
   // 2. Search both personal + project vaults for relevant pages.
-  pi.on("before_agent_start", async (event, _ctx) => {
+  pi.on("before_agent_start", async (event, ctx) => {
     const paths = resolveVaultPaths(process.cwd());
     if (!existsSync(join(paths.dotWiki, "config.json"))) {
       return;
@@ -227,6 +245,16 @@ Then call wiki_bootstrap with the inferred topic and mode to finalize the setup.
         if (recallContext) {
           injectedContext += `\n\n${recallContext}`;
         }
+        // Recall-aware status line (issue #77): make it visible that recall
+        // actually fired and how many pages matched. Purely a UI signal — no
+        // added model context. Honors the `notices` opt-out.
+        if (ctx?.hasUI && noticesEnabled(runtime.config)) {
+          const n = results.length;
+          ctx.ui.setStatus(
+            "llm-wiki",
+            `\u{1F9E0} LLM Wiki — recalled ${n} page${n === 1 ? "" : "s"} for this task`,
+          );
+        }
       }
     }
 

package/extensions/llm-wiki/lib/observation.ts

@@ -283,17 +283,64 @@ export function registerWikiObserve(
 
 // ─── Turn-End Reminder ─────────────────────────────────
 
+/**
+ * Build the one-time, user-visible session notice (issue #77) that announces
+ * the full wiki loop so the user can SEE the wiki is active and what it offers:
+ *
+ *   retrieval (sync, on the LLM's critical path): recall → search → read
+ *   capture  (background + reported):              observe → retro
+ *
+ * Shown once per session when `notices` are enabled; silenced otherwise.
+ */
+export function buildSessionNotice(): string {
+  return [
+    "\u{1F9E0} **LLM Wiki active.**",
+    "Retrieval (inline): recall runs automatically each turn — use `wiki_search` to query",
+    "and `read` to open pages.",
+    "Capture (background + reported): `wiki_observe` for timestamped notes,",
+    "`wiki_retro` for durable insights. All other wiki actions run in the background and",
+    "report when done. Silence these notices with `llm-wiki.notices: false`.",
+  ].join(" ");
+}
+
+/**
+ * Build the periodic observe/retro reminder text. Mentions BOTH capture tools
+ * (issue #77): `wiki_observe` for timestamped session observations and
+ * `wiki_retro` for distilled, durable insights at task end.
+ */
+export function buildReminderText(): string {
+  return [
+    "**Wiki capture reminder:** If the work in this session produced non-trivial",
+    "decisions, findings, constraints, or completions worth preserving across sessions,",
+    "record them now: call `wiki_observe` for timestamped observations, or `wiki_retro`",
+    "to save a distilled insight. Both are searchable via `wiki_recall` and compound",
+    "your wiki's knowledge over time.",
+    "",
+    "One item per call. Separate distinct findings into multiple calls.",
+  ].join(" ");
+}
+
 /**
  * Track observation cadence and send turn-end reminders.
  * After every N significant turns, reminds the model to call wiki_observe
  * for non-trivial findings (same pattern as memex-retro reminders).
+ *
+ * `options.display` (issue #77) controls whether the reminder is shown to the
+ * user (`true`, the default) or injected silently into model context only
+ * (`false`). Pass a resolver so the live `notices` config is read at send time.
  */
 export function registerObservationReminder(
   pi: ExtensionAPI,
   reminderState: ReminderState,
-  options?: { turnsBetweenReminders?: number },
+  options?: { turnsBetweenReminders?: number; display?: boolean | (() => boolean) },
 ): void {
   const REMINDER_INTERVAL = options?.turnsBetweenReminders ?? 5;
+  const resolveDisplay = (): boolean => {
+    const d = options?.display;
+    if (typeof d === "function") return d();
+    if (typeof d === "boolean") return d;
+    return true;
+  };
   let turnsSinceLastReminder = 0;
 
   pi.on("session_start", async () => {
@@ -315,15 +362,8 @@ export function registerObservationReminder(
     pi.sendMessage(
       {
         customType: "wiki-observe-reminder",
-        content: [
-          "**Wiki observation reminder:** If the work in this session produced non-trivial ",
-          "decisions, findings, constraints, or completions worth preserving across sessions,",
-          "call `wiki_observe` to record them. Observations are searchable via `wiki_recall`",
-          "and compound your wiki's knowledge over time.",
-          "",
-          "One observation per call. Separate distinct findings into multiple calls.",
-        ].join(" "),
-        display: false,
+        content: buildReminderText(),
+        display: resolveDisplay(),
       },
       {
         deliverAs: "nextTurn",

package/extensions/llm-wiki/lib/recall.ts

@@ -781,7 +781,7 @@ export function formatRecallContext(
 
     lines.push(
       "",
-      "Call `read` (or `wiki_read`) on the links you need to pull full content." +
+      "Call `read` on the links you need to pull their full content." +
         " Add new findings via wiki_ensure_page or wiki_retro.",
       "",
     );

package/extensions/llm-wiki/lib/runtime.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { TASK_DEFAULTS, type TaskConfig, loadTaskConfig } from "./task-config.js";
+import { TASK_DEFAULTS, type TaskConfig, loadTaskConfig, noticesEnabled } from "./task-config.js";
 
 /**
  * Background-task runtime for the LLM Wiki (issue #64, part of #63).
@@ -53,6 +53,13 @@ export class Runtime {
   config: TaskConfig = { ...TASK_DEFAULTS };
   configLoaded = false;
 
+  /**
+   * Extension API handle, attached at registration. Used by `report()` to emit
+   * visible completion messages for background actions (issue #77). Optional so
+   * the Runtime stays unit-testable without a live `pi`.
+   */
+  pi?: ExtensionAPI;
+
   /** Labels of tasks currently in flight (single-flight guard per label). */
   private inFlightLabels = new Set<string>();
   /** All in-flight task promises, keyed for await-at-exit and dedupe. */
@@ -176,6 +183,44 @@ export class Runtime {
     return promise;
   }
 
+  /**
+   * Report a completed background action to the user (issue #77).
+   *
+   * Every mutating wiki action runs off the agent's critical path; this is how
+   * the work becomes visible. Emits a `wiki-action-report` custom message,
+   * shown in the UI when notices are enabled (the `notices` config, default
+   * on) and otherwise injected silently. Delivered as `nextTurn` so it never
+   * interrupts or triggers a turn. Never throws — reporting must not crash the
+   * background task that called it.
+   */
+  report(summary: string, opts?: { display?: boolean }): void {
+    if (!this.pi || !summary) return;
+    const display = opts?.display ?? noticesEnabled(this.config);
+    try {
+      this.pi.sendMessage(
+        { customType: "wiki-action-report", content: summary, display },
+        { deliverAs: "nextTurn" },
+      );
+    } catch {
+      // Reporting is best-effort; a stale/torn-down session must not propagate.
+    }
+  }
+
+  /**
+   * Run a mutating action in the background and report its result (issue #77).
+   *
+   * Thin wrapper over `launchTask`: `work` performs the off-thread mutation and
+   * returns a one-line human summary (or null to stay silent). On success the
+   * summary is surfaced via `report()`. Single-flight, error-isolated, and
+   * awaited-at-exit exactly like `launchTask`.
+   */
+  launchReported(ctx: LaunchCtx, label: string, work: () => Promise<string | null>): Promise<void> {
+    return this.launchTask(ctx, label, async () => {
+      const summary = await work();
+      if (summary) this.report(summary);
+    });
+  }
+
   /**
    * Await all in-flight background tasks. Call at compaction / session exit so
    * background work is not lost. Never rejects — task errors are already
@@ -198,6 +243,9 @@ export class Runtime {
  */
 export function registerBackgroundRuntime(pi: ExtensionAPI): Runtime {
   const runtime = new Runtime();
+  // Attach the API so background tasks can emit visible completion reports
+  // (issue #77). Done here (not in the constructor) to keep Runtime testable.
+  runtime.pi = pi;
 
   pi.on("turn_start", (_event, ctx) => {
     runtime.ensureConfig(ctx.cwd);

package/extensions/llm-wiki/lib/task-config.ts

@@ -69,10 +69,28 @@ export interface TaskConfig {
    * previews inline. Clamped to a non-negative integer.
    */
   recallLinksThreshold?: number;
+
+  /**
+   * Surface wiki activity in the UI (issue #77). When enabled (the default),
+   * the status line reflects recall hits and the periodic observe/retro
+   * reminder is shown to the user (`display: true`) instead of being injected
+   * silently. Set to `false` to restore the previous quiet behavior — a static
+   * status line and a hidden (`display: false`) reminder — for users who do
+   * not want any chat-level wiki notices.
+   */
+  notices?: boolean;
 }
 
 export const TASK_DEFAULTS: TaskConfig = {};
 
+/**
+ * Resolve whether user-facing wiki notices are enabled (issue #77). Defaults
+ * to `true`; only an explicit `notices: false` disables them.
+ */
+export function noticesEnabled(config: TaskConfig | undefined): boolean {
+  return config?.notices !== false;
+}
+
 const SETTINGS_KEY = "llm-wiki";
 
 function readModelSpec(value: unknown): { provider: string; id: string } | undefined {
@@ -115,6 +133,10 @@ function readNamespacedConfig(path: string): Partial<TaskConfig> {
     if (typeof threshold === "number" && Number.isFinite(threshold)) {
       out.recallLinksThreshold = Math.max(0, Math.floor(threshold));
     }
+
+    if (typeof section.notices === "boolean") {
+      out.notices = section.notices;
+    }
     return out;
   } catch {
     return {};

package/extensions/llm-wiki/lib/tools.ts

@@ -44,6 +44,55 @@ function requireVault(paths: VaultPaths): { ok: true } | { ok: false; reason: st
   return { ok: true };
 }
 
+type WikiToolResult = {
+  content: { type: "text"; text: string }[];
+  details: Record<string, unknown>;
+  isError?: boolean;
+};
+
+type ToolCtx = {
+  cwd?: string;
+  hasUI: boolean;
+  ui?: { notify: (message: string, type?: string) => void };
+};
+
+/**
+ * Dispatch a heavy mutating action to the background runtime and report its
+ * result (issue #77). The agent turn is never blocked: `work` runs off-thread
+ * and the returned one-line summary is surfaced to the user via
+ * `runtime.report()`. Returns an immediate, non-blocking tool result.
+ *
+ * When no runtime is available (unit tests / degraded mode), `work` runs
+ * synchronously and its summary is returned inline, preserving prior behavior.
+ * Retrieval tools (search/read/recall/status) never use this — the model needs
+ * their output inline.
+ */
+async function dispatchReported(
+  runtime: Runtime | undefined,
+  ctx: ToolCtx,
+  opts: {
+    label: string;
+    /** Immediate, non-blocking acknowledgement shown while work runs. */
+    started: string;
+    /** Off-thread work; resolves to the human-readable completion summary. */
+    work: () => Promise<string>;
+    details?: Record<string, unknown>;
+  },
+): Promise<WikiToolResult> {
+  if (!runtime) {
+    const summary = await opts.work();
+    return {
+      content: [{ type: "text", text: summary }],
+      details: { background: false, ...opts.details },
+    };
+  }
+  runtime.launchReported({ hasUI: ctx.hasUI, ui: ctx.ui }, opts.label, opts.work);
+  return {
+    content: [{ type: "text", text: opts.started }],
+    details: { background: true, ...opts.details },
+  };
+}
+
 // ─── 1. wiki_bootstrap ──────────────────────────────────
 
 export function registerWikiBootstrap(pi: ExtensionAPI): void {
@@ -381,14 +430,15 @@ export function registerWikiIngest(pi: ExtensionAPI, runtime?: Runtime): void {
                 ];
                 launchEmbedPages(runtime, launchCtx, paths, pageIds, `embed:ingest:${s.id}`);
               }
+              const summary = committed
+                ? `LLM Wiki: ingested ${s.id} → ${committed.entitiesCreated.length} entit${committed.entitiesCreated.length === 1 ? "y" : "ies"}, ${committed.conceptsCreated.length} concept${committed.conceptsCreated.length === 1 ? "" : "s"}`
+                : `LLM Wiki: ${s.id} produced no synthesis`;
               if (ctx.hasUI) {
-                ctx.ui.notify(
-                  committed
-                    ? `LLM Wiki: ingested ${s.id} → ${committed.entitiesCreated.length} entit${committed.entitiesCreated.length === 1 ? "y" : "ies"}, ${committed.conceptsCreated.length} concept${committed.conceptsCreated.length === 1 ? "" : "s"}`
-                    : `LLM Wiki: ${s.id} produced no synthesis`,
-                  committed ? "info" : "warning",
-                );
+                ctx.ui.notify(summary, committed ? "info" : "warning");
               }
+              // Persistent, user-visible completion report (issue #77) in
+              // addition to the transient toast above. Notices-gated.
+              runtime.report(committed ? `✅ ${summary}` : `⚠️ ${summary}`);
             });
           }
           return {
@@ -672,7 +722,7 @@ export function registerWikiSearch(pi: ExtensionAPI): void {
 
 // ─── 6. wiki_lint ───────────────────────────────────────
 
-export function registerWikiLint(pi: ExtensionAPI): void {
+export function registerWikiLint(pi: ExtensionAPI, runtime?: Runtime): void {
   pi.registerTool({
     name: "wiki_lint",
     label: "Wiki Lint",
@@ -699,138 +749,143 @@ export function registerWikiLint(pi: ExtensionAPI): void {
         };
       }
 
-      const pages = findWikiPages(paths.wiki);
-      const registry = buildRegistry(paths);
-      buildBacklinks(paths, registry); // ensures backlinks.json is current
-
-      const findings: string[] = [];
-      let orphans = 0;
-      let missingPages = 0;
-      let contradictions = 0;
-      const gaps: Array<{ topic: string; mentionedBy: string[] }> = [];
-
-      const allPageIds = new Set(pages.map((p) => p.relative));
-      const linkCounts: Record<string, number> = {};
-
-      for (const page of pages) {
-        const links = extractWikilinks(page.content);
-        for (const link of links) {
-          if (!allPageIds.has(link)) {
-            missingPages++;
-            findings.push(`Missing page: [[${link}]] (in [[${page.relative}]])`);
-            const existing = gaps.find((g) => g.topic === link);
-            if (existing) {
-              if (!existing.mentionedBy.includes(page.relative))
-                existing.mentionedBy.push(page.relative);
-            } else {
-              gaps.push({ topic: link, mentionedBy: [page.relative] });
-            }
-          } else {
-            linkCounts[link] = (linkCounts[link] || 0) + 1;
-          }
-        }
-      }
+      // Full-vault scan (+ optional auto-fix writes + reindex) is O(pages):
+      // run it in the background and report the health summary (issue #77).
+      return dispatchReported(runtime, ctx as ToolCtx, {
+        label: `lint:${paths.root}`,
+        started:
+          "\u{1F9F9} LLM Wiki: lint started in the background — the health report will be posted when it completes.",
+        work: async () => runWikiLint(paths, params.auto_fix === true),
+      });
+    },
+  });
+}
 
-      for (const page of pages) {
-        if (!linkCounts[page.relative] || linkCounts[page.relative] === 0) {
-          orphans++;
-          findings.push(`Orphan: [[${page.relative}]] has no inbound links`);
+/**
+ * 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: VaultPaths, autoFix: boolean): string {
+  const pages = findWikiPages(paths.wiki);
+  const registry = buildRegistry(paths);
+  buildBacklinks(paths, registry); // ensures backlinks.json is current
+
+  const findings: string[] = [];
+  let orphans = 0;
+  let missingPages = 0;
+  let contradictions = 0;
+  const gaps: Array<{ topic: string; mentionedBy: string[] }> = [];
+
+  const allPageIds = new Set(pages.map((p) => p.relative));
+  const linkCounts: Record<string, number> = {};
+
+  for (const page of pages) {
+    const links = extractWikilinks(page.content);
+    for (const link of links) {
+      if (!allPageIds.has(link)) {
+        missingPages++;
+        findings.push(`Missing page: [[${link}]] (in [[${page.relative}]])`);
+        const existing = gaps.find((g) => g.topic === link);
+        if (existing) {
+          if (!existing.mentionedBy.includes(page.relative))
+            existing.mentionedBy.push(page.relative);
+        } else {
+          gaps.push({ topic: link, mentionedBy: [page.relative] });
         }
+      } else {
+        linkCounts[link] = (linkCounts[link] || 0) + 1;
       }
+    }
+  }
 
-      for (const page of pages) {
-        if (page.content.includes("⚠️ **Contradiction")) {
-          contradictions++;
-          findings.push(`Contradiction flagged in [[${page.relative}]]`);
-        }
-      }
+  for (const page of pages) {
+    if (!linkCounts[page.relative] || linkCounts[page.relative] === 0) {
+      orphans++;
+      findings.push(`Orphan: [[${page.relative}]] has no inbound links`);
+    }
+  }
 
-      let fixesApplied = 0;
-      if (params.auto_fix) {
-        for (const gap of gaps) {
-          if (gap.mentionedBy.length >= 2) {
-            const folder = gap.topic.includes("/") ? gap.topic.split("/")[0] : "concepts";
-            const name = gap.topic.includes("/") ? gap.topic.split("/").pop()! : gap.topic;
-            const pagePath = join(paths.wiki, folder, `${name}.md`);
-            if (!existsSync(pagePath)) {
-              mkdirSync(join(paths.wiki, folder), { recursive: true });
-              writeFileSync(
-                pagePath,
-                `---\ntype: concept\ncreated: ${fmtDate()}\nupdated: ${fmtDate()}\nsources: []\nstatus: stub\n---\n\n# ${name.replace(/-/g, " ")}\n\n_Stub auto-created by lint. Expand with content from: ${gap.mentionedBy.map((r) => `[[${r}]]`).join(", ")}_\n`,
-                "utf-8",
-              );
-              fixesApplied++;
-            }
-          }
+  for (const page of pages) {
+    if (page.content.includes("⚠️ **Contradiction")) {
+      contradictions++;
+      findings.push(`Contradiction flagged in [[${page.relative}]]`);
+    }
+  }
+
+  let fixesApplied = 0;
+  if (autoFix) {
+    for (const gap of gaps) {
+      if (gap.mentionedBy.length >= 2) {
+        const folder = gap.topic.includes("/") ? gap.topic.split("/")[0] : "concepts";
+        const name = gap.topic.includes("/") ? gap.topic.split("/").pop()! : gap.topic;
+        const pagePath = join(paths.wiki, folder, `${name}.md`);
+        mkdirSync(join(paths.wiki, folder), { recursive: true });
+        try {
+          // Atomic create-if-absent: the `wx` flag fails with EEXIST instead of
+          // overwriting, avoiding the existsSync→write TOCTOU race (CodeQL).
+          writeFileSync(
+            pagePath,
+            `---\ntype: concept\ncreated: ${fmtDate()}\nupdated: ${fmtDate()}\nsources: []\nstatus: stub\n---\n\n# ${name.replace(/-/g, " ")}\n\n_Stub auto-created by lint. Expand with content from: ${gap.mentionedBy.map((r) => `[[${r}]]`).join(", ")}_\n`,
+            { encoding: "utf-8", flag: "wx" },
+          );
+          fixesApplied++;
+        } catch (err) {
+          // Page already exists — nothing to fix. Re-throw anything else.
+          if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
         }
       }
+    }
+  }
 
-      writeJson(join(paths.discoveries, "gaps.json"), {
-        gaps,
-        generated: new Date().toISOString(),
-      });
-
-      const reportLines = [
-        "# Wiki Lint Report",
-        `Generated: ${fmtDate()}`,
-        "",
-        "## Summary",
-        `- Total pages: ${pages.length}`,
-        `- Orphans: ${orphans}`,
-        `- Missing pages: ${missingPages}`,
-        `- Contradictions: ${contradictions}`,
-        params.auto_fix ? `- Fixes applied: ${fixesApplied}` : "",
-        "",
-        "## Findings",
-        findings.length > 0 ? findings.map((f) => `- ${f}`).join("\n") : "✅ No issues found!",
-        "",
-      ].filter(Boolean);
-
-      const reportPath = join(paths.outputs, `lint-${fmtDate()}.md`);
-      mkdirSync(paths.outputs, { recursive: true });
-      writeFileSync(reportPath, `${reportLines.join("\n")}\n`, "utf-8");
-
-      appendEvent(paths, {
-        kind: "lint",
-        orphans,
-        missing_pages: missingPages,
-        contradictions,
-        auto_fix: params.auto_fix ?? false,
-      });
-
-      rebuildMetadataLight(paths);
+  writeJson(join(paths.discoveries, "gaps.json"), {
+    gaps,
+    generated: new Date().toISOString(),
+  });
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: [
-              "🧹 **Lint complete**",
-              "",
-              `- Pages: ${pages.length}`,
-              `- Orphans: ${orphans}`,
-              `- Missing: ${missingPages}`,
-              `- Contradictions: ${contradictions}`,
-              params.auto_fix ? `- Auto-fixes: ${fixesApplied}` : "",
-              "",
-              `📄 Report: \`${reportPath}\``,
-              gaps.length > 0 ? `💡 ${gaps.length} knowledge gap(s) tracked` : "",
-            ]
-              .filter(Boolean)
-              .join("\n"),
-          },
-        ],
-        details: {
-          pages: pages.length,
-          orphans,
-          missingPages,
-          contradictions,
-          reportPath,
-          gaps: gaps.length,
-        } as Record<string, unknown>,
-      };
-    },
+  const reportLines = [
+    "# Wiki Lint Report",
+    `Generated: ${fmtDate()}`,
+    "",
+    "## Summary",
+    `- Total pages: ${pages.length}`,
+    `- Orphans: ${orphans}`,
+    `- Missing pages: ${missingPages}`,
+    `- Contradictions: ${contradictions}`,
+    autoFix ? `- Fixes applied: ${fixesApplied}` : "",
+    "",
+    "## Findings",
+    findings.length > 0 ? findings.map((f) => `- ${f}`).join("\n") : "✅ No issues found!",
+    "",
+  ].filter(Boolean);
+
+  const reportPath = join(paths.outputs, `lint-${fmtDate()}.md`);
+  mkdirSync(paths.outputs, { recursive: true });
+  writeFileSync(reportPath, `${reportLines.join("\n")}\n`, "utf-8");
+
+  appendEvent(paths, {
+    kind: "lint",
+    orphans,
+    missing_pages: missingPages,
+    contradictions,
+    auto_fix: autoFix,
   });
+
+  rebuildMetadataLight(paths);
+
+  return [
+    "🧹 **LLM Wiki lint complete**",
+    "",
+    `- Pages: ${pages.length}`,
+    `- Orphans: ${orphans}`,
+    `- Missing: ${missingPages}`,
+    `- Contradictions: ${contradictions}`,
+    autoFix ? `- Auto-fixes: ${fixesApplied}` : "",
+    "",
+    `📄 Report: \`${reportPath}\``,
+    gaps.length > 0 ? `💡 ${gaps.length} knowledge gap(s) tracked` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
 }
 
 // ─── 7. wiki_status ─────────────────────────────────────
@@ -912,7 +967,7 @@ export function registerWikiStatus(pi: ExtensionAPI): void {
 
 // ─── 8. wiki_rebuild_meta ───────────────────────────────
 
-export function registerWikiRebuildMeta(pi: ExtensionAPI): void {
+export function registerWikiRebuildMeta(pi: ExtensionAPI, runtime?: Runtime): void {
   pi.registerTool({
     name: "wiki_rebuild_meta",
     label: "Wiki Rebuild Meta",
@@ -931,24 +986,23 @@ export function registerWikiRebuildMeta(pi: ExtensionAPI): void {
         };
       }
 
-      rebuildMetadata(paths);
-      appendEvent(paths, { kind: "rebuild_meta" });
-
-      const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
-        version: "1.0",
-        last_updated: "",
-        pages: {},
+      // Heavy O(pages) rebuild — dispatch off the agent's critical path and
+      // report on completion (issue #77).
+      return dispatchReported(runtime, ctx as ToolCtx, {
+        label: `rebuild_meta:${paths.root}`,
+        started:
+          "\u{1F9E0} LLM Wiki: metadata rebuild started in the background — the result will be reported when it completes.",
+        work: async () => {
+          rebuildMetadata(paths);
+          appendEvent(paths, { kind: "rebuild_meta" });
+          const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
+            version: "1.0",
+            last_updated: "",
+            pages: {},
+          });
+          return `✅ LLM Wiki: metadata rebuilt — ${Object.keys(registry.pages).length} pages indexed.`;
+        },
       });
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: `✅ Metadata rebuilt. ${Object.keys(registry.pages).length} pages indexed.`,
-          },
-        ],
-        details: { pageCount: Object.keys(registry.pages).length } as Record<string, unknown>,
-      };
     },
   });
 }
@@ -998,28 +1052,24 @@ export function registerWikiReindexEmbeddings(pi: ExtensionAPI, runtime?: Runtim
         };
       }
 
-      const stats = await reindexEmbeddings(paths, embedder, { force: params.force === true });
-      appendEvent(paths, {
-        kind: "reindex_embeddings",
-        embedded: stats.embedded,
-        skipped: stats.skipped,
-        pruned: stats.pruned,
-        model: embedder.model,
+      // Embedding is network-bound and O(pages) — run it in the background and
+      // report the stats on completion (issue #77).
+      return dispatchReported(runtime, ctx as ToolCtx, {
+        label: `reindex_embeddings:${paths.root}`,
+        started: `\u{1F9E0} LLM Wiki: embedding reindex started in the background (${embedder.model}) — stats will be reported when it completes.`,
+        details: { enabled: true, model: embedder.model },
+        work: async () => {
+          const stats = await reindexEmbeddings(paths, embedder, { force: params.force === true });
+          appendEvent(paths, {
+            kind: "reindex_embeddings",
+            embedded: stats.embedded,
+            skipped: stats.skipped,
+            pruned: stats.pruned,
+            model: embedder.model,
+          });
+          return `✅ LLM Wiki: embeddings reindexed (${embedder.model}) — ${stats.embedded} embedded, ${stats.skipped} fresh, ${stats.pruned} pruned.`;
+        },
       });
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: `✅ Embeddings reindexed (${embedder.model}): ${stats.embedded} embedded, ${stats.skipped} fresh, ${stats.pruned} pruned.`,
-          },
-        ],
-        details: {
-          enabled: true,
-          ...stats,
-          model: embedder.model,
-        } as Record<string, unknown>,
-      };
     },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Self-maintaining LLM Wiki for Pi — Karpathy-pattern knowledge base with immutable source capture, automated ingestion, search, linting, and Obsidian-compatible vault. auto-updating personal & company wiki.",
   "keywords": [
     "pi",