@zosmaai/pi-llm-wiki 0.9.0 → 0.9.2

package/extensions/llm-wiki/index.ts

@@ -2,12 +2,9 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { installGuardrails } from "./lib/guardrails.js";
+import { registerWikiModelCommand } from "./lib/model-command.js";
 import {
-  MODEL_STATUS_KEY,
-  formatActiveModelLabel,
-  registerWikiModelCommand,
-} from "./lib/model-command.js";
-import {
+  buildSessionNotice,
   createReminderState,
   registerObservationReminder,
   registerWikiObserve,
@@ -21,6 +18,7 @@ import {
 } from "./lib/recall.js";
 import { registerWikiRetro } from "./lib/retro.js";
 import { registerBackgroundRuntime } from "./lib/runtime.js";
+import { loadTaskConfig, noticesEnabled, trajectoriesEnabled } from "./lib/task-config.js";
 import {
   registerWikiBootstrap,
   registerWikiCaptureSource,
@@ -34,6 +32,12 @@ import {
   registerWikiStatus,
   registerWikiWatch,
 } from "./lib/tools.js";
+import { registerWikiTrajectoriesCommand } from "./lib/trajectories-command.js";
+import {
+  registerWikiCaptureTrajectory,
+  registerWikiDistillSkills,
+  registerWikiRecallSkill,
+} from "./lib/trajectory.js";
 import {
   ensureVaultStructure,
   fmtDate,
@@ -42,11 +46,13 @@ import {
   resolveVaultPaths,
   writeJson,
 } from "./lib/utils.js";
+import { applySessionStartStatus } from "./lib/visible-status.js";
 
 /**
  * @zosmaai/pi-llm-wiki — LLM Wiki extension for Pi
  *
- * Registers 12 custom tools and installs guardrails:
+ * Registers 13 custom tools and installs guardrails (+3 agent-trajectory tools
+ * when `llm-wiki.trajectories` is enabled — opt-in, off by default, issue #80):
  * - wiki_recall (layered: personal + project vaults)
  * - wiki_retro (lightweight: single markdown file)
  * - wiki_capture_source (full 4-layer pipeline)
@@ -71,21 +77,43 @@ 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);
   registerWikiRecall(pi, runtime);
   registerWikiRetro(pi, runtime);
+  // Agent working-memory (issue #80): capture what the agent *did* (its
+  // tool-call trajectory), distill it into reusable skills, and recall past
+  // skills/cases. OPT-IN, default OFF — registered ONLY when enabled so the 3
+  // tools cost nothing in the system prompt for users who don't opt in.
+  //
+  // Gate on loadTaskConfig(process.cwd()) at factory time, NOT runtime.config:
+  // runtime.config is empty ({}) until ensureConfig runs in a later hook, so a
+  // runtime.config gate here would read as permanently off. Toggling the flag
+  // via /wiki-trajectories reloads the extension, re-running this gate.
+  const trajectoriesOn = trajectoriesEnabled(loadTaskConfig(process.cwd()));
+  if (trajectoriesOn) {
+    registerWikiCaptureTrajectory(pi);
+    registerWikiDistillSkills(pi);
+    registerWikiRecallSkill(pi);
+  }
+  // Activation surface for the above (always available so users can turn it on).
+  registerWikiTrajectoriesCommand(pi);
   // Model selection surface (issue #69): /wiki-model command to view/set the
   // background task model. The taskModel config field + resolveModel already
   // exist; this exposes them to the user (default stays the session model).
   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);
 
@@ -99,6 +127,10 @@ export default function (pi: ExtensionAPI) {
     try {
       const migration = migrateDoubledPersonalVault();
       if (migration && migration.moved.length > 0) {
+        // INTENTIONALLY NOT gated by `noticesEnabled` (issues #77, #84): this is
+        // a one-shot data-integrity recovery signal, not chat-noise. If the
+        // user has a broken doubled-dotdir layout we want them to see that it
+        // was fixed, even in quiet mode.
         ctx.ui.setStatus(
           "llm-wiki",
           `🧠 Personal wiki layout fixed: flattened ${migration.moved.length} entries out of ${migration.from} (see CHANGELOG)`,
@@ -140,17 +172,35 @@ export default function (pi: ExtensionAPI) {
       writeFileSync(join(vaultPaths.dotWiki, "WIKI_SCHEMA.md"), schema, "utf-8");
 
       needsTopicInference = true;
+      // INTENTIONALLY NOT gated by `noticesEnabled` (issues #77, #84): one-shot
+      // first-run setup signal. The user needs to know the wiki was just
+      // auto-created, regardless of quiet mode.
       ctx.ui.setStatus("llm-wiki", "🧠 Wiki created (inferring topic from first prompt…)");
       return;
     }
 
-    ctx.ui.setStatus("llm-wiki", "🧠 LLM Wiki (13 tools, observe + recall active)");
-
-    // Surface the active background task model (issue #69). Defaults to the
-    // session model when no taskModel is configured.
+    // Surface the "wiki active" badge and the active background task model
+    // (issue #69), both gated by `llm-wiki.notices` (issue #77, regression
+    // fixed in #83, helper extracted in #84). `ensureConfig` MUST run first so
+    // the gate sees the loaded project settings.
     runtime.ensureConfig(process.cwd());
-    const modelLabel = formatActiveModelLabel(runtime.config, (ctx.model as { id?: string })?.id);
-    ctx.ui.setStatus(MODEL_STATUS_KEY, `🧠 wiki model: ${modelLabel}`);
+    applySessionStartStatus({
+      ui: ctx.ui,
+      runtime,
+      trajectoriesOn,
+      sessionModelId: (ctx.model as { id?: string })?.id,
+    });
+
+    // 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 +208,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;
@@ -223,10 +273,23 @@ Then call wiki_bootstrap with the inferred topic and mode to finalize the setup.
         // large vault never floods the system prompt with inline previews.
         // includePersonal=false here mirrors the auto-injection search scope.
         const linksOnly = shouldUseLinksFirst(vaultPageCount(paths, false), runtime.config);
-        const recallContext = formatRecallContext(results, { linksOnly });
+        const recallContext = formatRecallContext(results, {
+          linksOnly,
+          skillInlineMax: runtime.config?.recallSkillInlineMax,
+        });
         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/metadata.ts

@@ -19,7 +19,16 @@ import {
  */
 
 export interface RegistryEntry {
-  type: "source" | "entity" | "concept" | "synthesis" | "analysis";
+  type:
+    | "source"
+    | "entity"
+    | "concept"
+    | "synthesis"
+    | "analysis"
+    | "requirement"
+    | "trajectory"
+    | "skill"
+    | "case";
   title: string;
   created: string;
   updated: string;
@@ -98,6 +107,30 @@ export function buildRegistry(paths: VaultPaths): Registry {
     }
   }
 
+  // Scan raw trajectory packets (agent working-memory). These are catalogued
+  // under the `trajectories/` namespace so distillation and recall can find
+  // them even before a canonical case/skill page has been written.
+  if (existsSync(paths.rawTrajectories)) {
+    for (const entry of readdirSync(paths.rawTrajectories)) {
+      const manifestPath = join(paths.rawTrajectories, entry, "manifest.json");
+      if (!existsSync(manifestPath)) continue;
+
+      const manifest = readJson<Record<string, unknown>>(manifestPath, {});
+      const id = String(manifest.id || entry);
+      const trajectoryPage = `trajectories/${id}`;
+
+      if (!pages[trajectoryPage]) {
+        pages[trajectoryPage] = {
+          type: "trajectory",
+          title: String(manifest.title || id),
+          created: String(manifest.captured || fmtDate()),
+          updated: String(manifest.captured || fmtDate()),
+          ...manifest,
+        };
+      }
+    }
+  }
+
   return {
     version: "1.0",
     last_updated: new Date().toISOString(),

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

@@ -33,7 +33,7 @@ export interface RecallResult {
   type: string;
   /** First N chars of page content for context */
   preview: string;
-  /** Relative path from wiki root */
+  /** Absolute filesystem path to the page (resolvable by the `read` tool). */
   path: string;
   /** Vault source label for dual-vault results */
   vaultLabel?: string;
@@ -743,24 +743,105 @@ function linkSnippet(preview: string): string {
   return oneLine.length > LINKS_SNIPPET_MAX ? `${oneLine.slice(0, LINKS_SNIPPET_MAX)}…` : oneLine;
 }
 
+/**
+ * Default cap on chars of a skill/case body inlined directly into a recall
+ * block. Overridable per-vault via `recallSkillInlineMax` (0 disables inlining).
+ * Mirrors `DEFAULT_RECALL_LINKS_THRESHOLD` — the sibling context-window lever.
+ */
+export const DEFAULT_RECALL_SKILL_INLINE_MAX = 1600;
+
+/**
+ * Skills/working-memory carve-out from links-first: short, high-value
+ * procedural pages (`skill`/`case`) are meant to be APPLIED immediately, so we
+ * inline their body directly rather than make the agent expand a link it often
+ * skips (adherence > context-economy for these page types). Returns null for
+ * non-skill pages or when the body can't be read.
+ */
+function isSkillOrCase(r: RecallResult): boolean {
+  return (
+    r.type === "skill" ||
+    r.type === "case" ||
+    r.id.startsWith("skills/") ||
+    r.id.startsWith("cases/")
+  );
+}
+
+/**
+ * Inlined body for a skill/case page, or null. `max <= 0` disables inlining and
+ * short-circuits BEFORE any filesystem access, so a vault that opts out keeps
+ * recall page-body-I/O-free (issue #68's cheap-recall invariant). Otherwise the
+ * read is bounded: it fires only for skill/case results (which exist only when
+ * the trajectories feature is on) and only the top-N ranked hits.
+ */
+function inlineSkillBody(r: RecallResult, max = DEFAULT_RECALL_SKILL_INLINE_MAX): string | null {
+  if (max <= 0) return null;
+  if (!isSkillOrCase(r)) return null;
+  if (!r.path || !existsSync(r.path)) return null;
+  // Normalize CRLF first so the LF-anchored frontmatter strip below works on
+  // Windows-authored / git-autocrlf'd vaults (otherwise the raw YAML leaks in).
+  let body = readFileSync(r.path, "utf-8").replace(/\r\n/g, "\n");
+  body = body.replace(/^---\n[\s\S]*?\n---\n/, "").trim(); // strip YAML frontmatter
+  if (!body) return null;
+  if (body.length > max) {
+    body = `${body.slice(0, max)}\n…(truncated — \`read\` the path above for the full page)`;
+  }
+  return body;
+}
+
+/**
+ * A backtick fence guaranteed longer than any backtick run inside `body`.
+ * Skill/case pages routinely embed their own fenced code blocks; CommonMark
+ * closes a fenced block only on a fence of length >= the opener, so opening
+ * with (longest inner run + 1, min 3) keeps an inlined body from terminating
+ * the wrapper early — and stays safe even when truncation cuts mid-fence.
+ */
+function codeFenceFor(body: string): string {
+  let longest = 0;
+  for (const run of body.match(/`+/g) ?? []) longest = Math.max(longest, run.length);
+  return "`".repeat(Math.max(3, longest + 1));
+}
+
+/** Indented, fence-safe lines wrapping an inlined skill/case body. */
+function inlineBlockLines(body: string, indent: string): string[] {
+  const fence = codeFenceFor(body);
+  return [
+    "",
+    `${indent}${fence}`,
+    ...body.split("\n").map((line) => `${indent}${line}`),
+    `${indent}${fence}`,
+  ];
+}
+
 /**
  * Format recall results as a compact system-prompt section.
  *
  * Two render modes (issue #68):
- * - Default / `linksOnly: false` — preview-inline (unchanged for small vaults).
+ * - Default / `linksOnly: false` — preview-inline. For ordinary pages this is
+ *   byte-for-byte the pre-fix small-vault rendering (no regression); the
+ *   resolvable read-path + new footer copy are confined to links-first, where
+ *   there is no inline content and the agent MUST resolve a link.
  * - `linksOnly: true` — stage-1 "links-first": a ranked list of links carrying
- *   id, title, type, score, and a single short snippet. The agent expands the
- *   links it wants on demand via `read` (stage 2). Used above the vault-size
- *   threshold to keep large vaults from flooding context.
+ *   id, title, type, score, and a single short snippet, each with a resolvable
+ *   `read <path>`. The agent expands the links it wants on demand (stage 2).
+ *   Used above the vault-size threshold to keep large vaults from flooding context.
+ *
+ * `skillInlineMax` (default `DEFAULT_RECALL_SKILL_INLINE_MAX`) caps how much of a
+ * skill/case body is inlined; 0 disables inlining (pure links-first for those too).
  */
 export function formatRecallContext(
   results: RecallResult[],
-  opts: { linksOnly?: boolean } = {},
+  opts: { linksOnly?: boolean; skillInlineMax?: number } = {},
 ): string {
   if (results.length === 0) return "";
 
+  const skillInlineMax = opts.skillInlineMax ?? DEFAULT_RECALL_SKILL_INLINE_MAX;
   const hasLayered = results.some((r) => r.vaultLabel);
   const label = hasLayered ? " (personal + project)" : "";
+  // Salience nudge: when a distilled skill/case matches, tell the agent to
+  // apply it BEFORE experimenting (the dominant cost is recall non-adherence).
+  const hasSkill = results.some(isSkillOrCase);
+  const skillNudge =
+    "⚠\ufe0f A distilled skill/case below matches this task — read and APPLY it BEFORE experimenting on your own.";
 
   if (opts.linksOnly) {
     const lines: string[] = [
@@ -770,6 +851,7 @@ export function formatRecallContext(
       "",
     ];
 
+    if (hasSkill) lines.splice(1, 0, "", skillNudge);
     results.forEach((r, i) => {
       const vaultTag = r.vaultLabel ? ` ${r.vaultLabel}` : "";
       const snippet = linkSnippet(r.preview);
@@ -777,11 +859,18 @@ export function formatRecallContext(
       lines.push(
         `${i + 1}. **[[${r.id}]]** — *${r.type}* — score ${r.score.toFixed(1)}${vaultTag} — ${r.title}${tail}`,
       );
+      // Surface a read-resolvable path so expansion is a single, first-try
+      // `read` (issue: wikilink ids aren't resolvable by the file read tool).
+      if (r.path) lines.push(`   ↳ \`read ${r.path}\``);
+      // Skills/case carve-out: inline the body so the agent doesn't have to
+      // (and often won't) expand the link before acting.
+      const inl = inlineSkillBody(r, skillInlineMax);
+      if (inl) lines.push(...inlineBlockLines(inl, "   "));
     });
 
     lines.push(
       "",
-      "Call `read` (or `wiki_read`) on the links you need to pull full content." +
+      "Call `read` on the exact path shown under each link to pull its full content." +
         " Add new findings via wiki_ensure_page or wiki_retro.",
       "",
     );
@@ -796,10 +885,20 @@ export function formatRecallContext(
     "",
   ];
 
+  if (hasSkill) lines.splice(1, 0, "", skillNudge);
   for (const r of results) {
     const vaultTag = r.vaultLabel ? ` ${r.vaultLabel}` : "";
     lines.push(`- **[[${r.id}]]** — *${r.type}* — ${r.title}${vaultTag}`);
-    if (r.preview) {
+    // Skills/case carve-out: inline the body (adherence > context-economy). Only
+    // here does the default path deviate from the pre-fix small-vault render —
+    // and only when a skill/case matched (i.e. the trajectories feature is on),
+    // so ordinary pages stay byte-for-byte unchanged (#68 no-regression promise).
+    const inl = inlineSkillBody(r, skillInlineMax);
+    if (inl) {
+      // Resolvable path so a truncated inline body is one `read` away.
+      if (r.path) lines.push(`  ↳ \`read ${r.path}\``);
+      lines.push(...inlineBlockLines(inl, "  "));
+    } else if (r.preview) {
       // Truncate preview to one line
       const preview = r.preview.length > 120 ? `${r.preview.slice(0, 120)}…` : r.preview;
       lines.push(`  ${preview}`);

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);