@remnic/core 9.45.4 → 9.46.0

package/src/ambient-provenance.ts

@@ -0,0 +1,229 @@
+/**
+ * Ambient-capture provenance for extraction (issue #2294).
+ *
+ * Always-on capture devices — wearable recorders, room microphones — hand the
+ * extraction engine speech the user never authored: television and film
+ * dialogue, podcasts, radio, music with spoken segments, and conversations the
+ * user merely walked past. The extraction prompt otherwise reads every turn as
+ * first-person user input, so a scripted line about a relative's birthday or a
+ * medical diagnosis lands as a high-confidence personal fact and auto-promotes
+ * into recall. That output is plausible, personally relevant, and wrong, which
+ * makes it materially worse than a missed fact.
+ *
+ * This module owns both halves of the fix:
+ *
+ * 1. The prompt text that teaches the model to separate the user's own speech
+ *    from background media, drop high-consequence personal claims it cannot
+ *    attribute to the user, and score the remainder speculatively. One source
+ *    of truth, shared by the cloud, direct-client, and local-LLM prompts so the
+ *    three paths cannot drift.
+ * 2. A deterministic backstop — `clampAmbientCaptureConfidence` — for when the
+ *    model ignores the prompt anyway. It clamps ONLY high-impact personal facts
+ *    (family, milestones, medical) to the speculative ceiling. Clamping every
+ *    ambient fact would gut the wearable integration, which is explicitly not
+ *    the goal; clamping this class costs a birthday landing in the review queue
+ *    instead of active recall.
+ *
+ * The provenance signal itself is `BufferTurn.ambientCapture`, set by the
+ * ingesting subsystem (the wearable memory pass), never by tool arguments.
+ */
+
+import type { ExtractionResult } from "./types.js";
+
+/**
+ * Upper bound of the speculative confidence tier, matching the tier table in
+ * the extraction prompt ("Speculative (0.00-0.39)"). A fact at or below this
+ * value cannot auto-promote through the wearable trust bands.
+ */
+export const SPECULATIVE_CONFIDENCE_CEILING = 0.39;
+
+/**
+ * Appended to the speculative tier definition when the input is ambient
+ * capture, so the tier itself carries the rule rather than relying on the
+ * separate section below being obeyed in isolation.
+ */
+export const AMBIENT_SPECULATIVE_TIER_CLAUSE =
+  " Speculative also applies to any fact whose only evidence is ambient or background audio from an always-on capture device, even when the content is concrete and specific.";
+
+/**
+ * Full provenance section for the cloud and direct-client extraction prompts.
+ */
+export const AMBIENT_CAPTURE_PROMPT_SECTION = `
+Source provenance — always-on capture audio:
+- This transcript came from an always-on capture device (a wearable recorder or room microphone). It may contain audio the user did not author: television, film, podcasts, radio, advertisements, music with spoken segments, and conversations the user merely overheard or walked past.
+- Separate the user's own speech from background media before extracting anything. Narrative, scripted, performed, or third-person speech — a show's dialogue, a podcast host, an ad read, a lecture playing in the room — is media, not user input. Never attribute it to the user or to anyone the user knows.
+- High-consequence personal claims must be dropped entirely unless the user's own voice is clearly identifiable as their source: family relationships, personal milestones (births, birthdays, anniversaries, weddings, funerals, divorces), and any medical or health detail. Omit them; do not emit them at reduced confidence as a compromise.
+- When you cannot tell whether a statement was spoken by the user or captured passively, skip it or set its confidence in the speculative tier (0.00-0.39). Never resolve that doubt upward.`;
+
+/**
+ * Compact variant for the local-LLM prompt, which is deliberately small to fit
+ * 4k-8k context windows.
+ */
+export const AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT = `
+Ambient capture:
+- This transcript came from an always-on capture device and may contain TV, film, podcast, music, or overheard speech the user did not author.
+- Treat narrative, scripted, or third-person speech as media, not user input.
+- Drop family, milestone (birth, birthday, anniversary, wedding, funeral), and medical claims unless the user's own voice is clearly the source.
+- Otherwise, when unsure whether the user said it, set confidence in the speculative tier (0.00-0.39).`;
+
+/**
+ * Single rule for prompts that already have their own rule list and only need
+ * the ambient warning (the meeting scribe, whose transcript is the same
+ * wearable audio).
+ */
+export const AMBIENT_CAPTURE_PROMPT_RULE =
+  "- The transcript may contain ambient audio nobody in the meeting authored: television, podcasts, music, or a passing conversation. Treat scripted, performed, or third-person speech as background media and never record it as a decision, commitment, or question.";
+
+/**
+ * Categories that are personal-claim-shaped by construction, independent of any
+ * vocabulary: `moment` is defined as an emotionally significant event or
+ * milestone, and on ambient audio a `relationship` claim is a link the model
+ * inferred between people it overheard. Non-lexical, so they still catch harm
+ * the term lists below miss.
+ */
+const HIGH_IMPACT_CATEGORIES: Record<string, true> = { moment: true, relationship: true };
+
+/**
+ * Kinship, milestone, and health vocabulary. Deliberately broad: a false
+ * positive costs one ambient fact a trip through the review queue, a false
+ * negative puts a fabricated medical claim into active recall. The list cannot
+ * be exhaustive and is not the primary defense — the prompt is, and the
+ * category signal above plus the trust-band cap in the wearable pass catch
+ * classes no word list enumerates. Extend it when a miss is observed.
+ *
+ * Word-bounded alternation only — no nesting, no backtracking risk.
+ */
+const HIGH_IMPACT_TOPIC_PATTERN =
+  /\b(?:mother|mothers|mom|moms|mum|father|fathers|dad|dads|sister|sisters|brother|brothers|son|sons|daughter|daughters|wife|wives|husband|husbands|spouse|fiance|fiancee|grandmother|grandfather|grandma|grandpa|grandparent|grandparents|grandson|granddaughter|grandchild|grandchildren|aunt|uncle|cousin|niece|nephew|stepmother|stepfather|stepson|stepdaughter|stepchild|godmother|godfather|birthday|birthdays|anniversary|anniversaries|wedding|weddings|honeymoon|married|marriage|divorce|divorced|widow|widowed|funeral|memorial service|engagement party|baby shower|christening|bar mitzvah|pregnant|pregnancy|miscarriage|miscarried|newborn|gave birth|stillbirth|infertility|ivf|menopause|diagnosis|diagnosed|prognosis|tested positive|cancer|carcinoma|leukemia|tumor|tumour|biopsy|chemotherapy|chemo|radiation therapy|remission|hospice|palliative|terminal illness|surgery|surgeon|hospital|hospitalized|hospitalised|icu|emergency room|ambulance|stroke|heart attack|cardiac|arrhythmia|afib|seizure|epilepsy|asthma|allergy|allergic|diabetes|diabetic|insulin|cholesterol|blood pressure|hypertension|dementia|alzheimer|alzheimers|parkinson|parkinsons|hiv|aids diagnosis|medication|medications|prescription|prescribed|dosage|symptom|symptoms|illness|disease|disorder|syndrome|therapy|therapist|psychiatrist|psychologist|antidepressant|depression|anxiety|bipolar|schizophrenia|adhd|autism|ptsd|overdose|relapse|sobriety|rehab|addiction|alcoholism|concussion|transplant|dialysis|immunocompromised|mental health|covid|covid-19|coronavirus|flu|influenza|pneumonia|bronchitis|infection|infected|fever|migraine|ulcer|hernia|appendicitis|sepsis|sick leave|urgent care|broken leg|broken arm|broken wrist|broken hip|broken rib|broken ribs|sprained|dislocated|torn ligament|torn acl|whiplash|burn unit|chronic pain|disability|wheelchair|hearing aid|blind in|vaccinated|vaccination|immunization|blood test|scan results|mri|ct scan|x-ray|deaf|deafness|blind|blindness|mute|nonverbal|paralyzed|paralysed|paraplegic|quadriplegic|amputee|amputation|prosthetic|multiple sclerosis|lupus|crohn|celiac|fibromyalgia|cystic fibrosis|sickle cell|cerebral palsy|down syndrome|muscular dystrophy|chronic fatigue|chronic illness|terminally ill|life support|coma|special needs|caregiver|nursing home|assisted living|treatment|treatments|in treatment|medical leave|oncologist|cardiologist|neurologist|pediatrician|pediatric|als|copd|epilepsy|seizures|hospitalization|infirm|frail|bedridden|home health|physical therapy|occupational therapy|speech therapy)\b/i;
+
+/**
+ * Bodily-harm and affliction SHAPES rather than nouns: "broke her leg", "tore
+ * his ACL", "caught something at the office". A vocabulary of conditions can
+ * never be complete, so this matches the sentence form instead — a verb of
+ * injury or contagion pointed at a person's POSSESSION. Articles are excluded
+ * on purpose: "the build broke the deploy pipeline" is not an injury.
+ */
+const AFFLICTION_SHAPE_PATTERN =
+  /\b(?:broke|broken|fractured|sprained|dislocated|tore|torn|bruised|burned|scalded|injured|hurt)\s+(?:his|her|their|my|your|our)\s+\w+|\b(?:caught|contracted|came down with|is recovering from|was rushed to|passed away|died of|died from)\b/i;
+
+/**
+ * Words that are personal only when someone possesses them: "child process",
+ * "parent component", "sibling node", and "customer family" are everyday
+ * technical speech, while "his child" and "Rachel's parents" are not.
+ */
+const POSSESSED_KINSHIP_PATTERN =
+  /(?:\b(?:my|your|his|her|their|our)|'s)\s+(?:child|children|kid|kids|parent|parents|partner|family|sibling|siblings|in-law|in-laws|relatives)\b/i;
+
+/** Tags that mark a fact as belonging to the same high-impact classes. */
+const HIGH_IMPACT_TAGS: Record<string, true> = {
+  disability: true,
+  family: true,
+  health: true,
+  medical: true,
+  medication: true,
+  diagnosis: true,
+  birthday: true,
+  anniversary: true,
+  marriage: true,
+  pregnancy: true,
+  "mental-health": true,
+};
+
+/**
+ * True when this claim is personal in a way whose fabrication causes real
+ * harm — a family relationship, a personal milestone, or a medical detail.
+ *
+ * Read by every ambient guard: the post-extraction confidence clamp below, the
+ * wearable trust-band cap, and the meeting trust-band cap. A fact this flags
+ * can never auto-approve, on any path, however the boosts add up.
+ *
+ * Takes the shape rather than `ExtractedFact` so meeting candidates — which
+ * carry no tags — pass without a synthetic empty array.
+ *
+ * `personRefs` comes from `collectPersonEntityRefs` over the same extraction:
+ * pass it whenever the entity list is available, so personhood is read from
+ * the extractor's own `type: "person"` metadata instead of inferred from how
+ * it happened to spell the ref.
+ */
+export function isHighImpactPersonalFact(
+  fact: {
+    category: string;
+    content: string;
+    tags?: readonly string[];
+    entityRef?: string;
+  },
+  personRefs?: ReadonlySet<string>,
+): boolean {
+  // The strongest non-lexical signal: a claim ABOUT A PERSON is high-impact
+  // whatever condition, relationship, or milestone the sentence names. This is
+  // what covers wording no list anticipates ("Dana is deaf").
+  if (isPersonRef(fact.entityRef, personRefs)) return true;
+  if (HIGH_IMPACT_CATEGORIES[fact.category] === true) return true;
+  if (HIGH_IMPACT_TOPIC_PATTERN.test(fact.content)) return true;
+  if (AFFLICTION_SHAPE_PATTERN.test(fact.content)) return true;
+  if (POSSESSED_KINSHIP_PATTERN.test(fact.content)) return true;
+  for (const tag of fact.tags ?? []) {
+    if (HIGH_IMPACT_TAGS[tag.trim().toLowerCase()] === true) return true;
+  }
+  return false;
+}
+
+/**
+ * Normalize an entity reference for comparison: casefold, strip a leading
+ * type prefix, and collapse separators. `Person-Jane_Doe`, `person:jane-doe`,
+ * and `jane doe` all reduce to `jane-doe`.
+ */
+function normalizeEntityRef(ref: string): string {
+  return ref
+    .trim()
+    .toLowerCase()
+    .replace(/^(?:person|people)[-:_\s]+/, "")
+    .replace(/[\s_]+/g, "-");
+}
+
+/**
+ * Names of every `type: "person"` entity in an extraction, normalized for
+ * lookup. Personhood is the extractor's own metadata, not a guess from the
+ * shape of `entityRef` — the prompt asks for `person-jane-doe` but the field is
+ * optional and models routinely emit a bare `jane-doe`.
+ */
+export function collectPersonEntityRefs(result: {
+  entities: ReadonlyArray<{ name: string; type: string }>;
+}): ReadonlySet<string> {
+  const refs = new Set<string>();
+  for (const entity of result.entities) {
+    if (entity.type !== "person") continue;
+    const normalized = normalizeEntityRef(entity.name);
+    if (normalized.length > 0) refs.add(normalized);
+  }
+  return refs;
+}
+
+/** True when this ref names a person, by metadata or by explicit prefix. */
+function isPersonRef(ref: string | undefined, personRefs?: ReadonlySet<string>): boolean {
+  if (ref === undefined || ref.trim().length === 0) return false;
+  if (/^(?:person|people)[-:_]/i.test(ref.trim())) return true;
+  return personRefs !== undefined && personRefs.has(normalizeEntityRef(ref));
+}
+
+/**
+ * Deterministic backstop applied after extraction on ambient-capture input:
+ * hold high-impact personal facts at or below the speculative ceiling so they
+ * cannot auto-promote to active recall on a model's unsupported confidence.
+ *
+ * Returns the input unchanged when nothing needs clamping, so the non-ambient
+ * path pays one predicate per fact and allocates nothing.
+ */
+export function clampAmbientCaptureConfidence(
+  result: ExtractionResult,
+): ExtractionResult {
+  let clampedAny = false;
+  const personRefs = collectPersonEntityRefs(result);
+  const facts = result.facts.map((fact) => {
+    if (fact.confidence <= SPECULATIVE_CONFIDENCE_CEILING) return fact;
+    if (!isHighImpactPersonalFact(fact, personRefs)) return fact;
+    clampedAny = true;
+    return { ...fact, confidence: SPECULATIVE_CONFIDENCE_CEILING };
+  });
+  return clampedAny ? { ...result, facts } : result;
+}

package/src/buffer-turn-helpers.ts

@@ -9,6 +9,18 @@ export interface BufferTurnOwner {
   sessionOwnerPrincipal?: string;
 }
 
+export interface AmbientCaptureProvenance {
+  /**
+   * True when this turn's content came from an always-on ambient capture
+   * device (a wearable recorder, a room microphone) and may therefore carry
+   * speech the user never authored: TV, podcasts, music, overheard
+   * conversation (issue #2294). Set by the ingesting subsystem, never from
+   * tool arguments — extraction reads it to warn the model about media audio
+   * and to clamp high-impact personal facts to the speculative tier.
+   */
+  ambientCapture?: boolean;
+}
+
 export function describeError(err: unknown): string {
   if (err instanceof Error) return err.message;
   if (err === null) return "null";
@@ -46,6 +58,9 @@ export function copyBufferTurn(turn: BufferTurn): BufferTurn {
   if (typeof turn.sourceConnector === "string") {
     copy.sourceConnector = turn.sourceConnector;
   }
+  if (typeof turn.ambientCapture === "boolean") {
+    copy.ambientCapture = turn.ambientCapture;
+  }
   return copy;
 }
 
@@ -61,7 +76,8 @@ export function bufferTurnsEqual(left: BufferTurn | undefined, right: BufferTurn
     left.providerThreadId === right.providerThreadId &&
     left.turnFingerprint === right.turnFingerprint &&
     left.persistProcessedFingerprint === right.persistProcessedFingerprint &&
-    left.sourceConnector === right.sourceConnector
+    left.sourceConnector === right.sourceConnector &&
+    left.ambientCapture === right.ambientCapture
   );
 }
 

package/src/compat/checks.test.ts

@@ -154,7 +154,11 @@ test("memory prompt section registration must be on the plugin api object", asyn
 
   const hookCheck = checkById(checks, "hook-registration-core");
   assert.equal(hookCheck.level, "error");
-  assert.match(hookCheck.message, /before_prompt_build|before_agent_start/);
+  assert.match(hookCheck.message, /before_prompt_build/);
+  assert.doesNotMatch(
+    `${hookCheck.message} ${hookCheck.remediation ?? ""}`,
+    /before_agent_start/,
+  );
 });
 
 test("memory prompt section registration on api satisfies recall hook requirement", async () => {
@@ -173,6 +177,46 @@ test("memory prompt section registration on api satisfies recall hook requiremen
   assert.equal(hookCheck.level, "ok");
 });
 
+test("memory prompt section remediation requests only missing required hooks", async () => {
+  const checks = await runFixture({
+    enginesNode: ">=22.12.0",
+    currentNodeVersion: "v22.12.0",
+    indexSource: [
+      "api.registerService({ start: async () => {} });",
+      "api.registerMemoryPromptSection(() => null);",
+      "registerCli(api, orchestrator);",
+    ].join("\n"),
+  });
+
+  const hookCheck = checkById(checks, "hook-registration-core");
+  assert.equal(hookCheck.level, "error");
+  assert.match(`${hookCheck.message} ${hookCheck.remediation ?? ""}`, /agent_end/);
+  assert.doesNotMatch(
+    `${hookCheck.message} ${hookCheck.remediation ?? ""}`,
+    /before_prompt_build|before_agent_start|gateway_start/,
+  );
+});
+
+test("memory prompt section remediation requests startup only when absent", async () => {
+  const checks = await runFixture({
+    enginesNode: ">=22.12.0",
+    currentNodeVersion: "v22.12.0",
+    indexSource: [
+      "api.on('agent_end', async () => {});",
+      "api.registerMemoryPromptSection(() => null);",
+      "registerCli(api, orchestrator);",
+    ].join("\n"),
+  });
+
+  const hookCheck = checkById(checks, "hook-registration-core");
+  assert.equal(hookCheck.level, "error");
+  assert.match(`${hookCheck.message} ${hookCheck.remediation ?? ""}`, /startup wiring/);
+  assert.doesNotMatch(
+    `${hookCheck.message} ${hookCheck.remediation ?? ""}`,
+    /before_prompt_build|before_agent_start/,
+  );
+});
+
 test("service start detection ignores nested start properties", async () => {
   const checks = await runFixture({
     enginesNode: ">=22.12.0",

package/src/compat/checks.ts

@@ -4,8 +4,7 @@ import type { CompatCheckOptions, CompatCheckResult, CompatReport, CompatRunner
 import { compareVersions } from "../version-utils.js";
 import { launchProcess } from "../runtime/child-process.js";
 
-const REQUIRED_HOOKS_LEGACY = ["before_agent_start", "agent_end"];
-const REQUIRED_HOOKS_NEW = ["before_prompt_build", "agent_end"];
+const REQUIRED_HOOKS = ["before_prompt_build", "agent_end"];
 const OPENCLAW_REMNIC_PLUGIN_ID = "openclaw-remnic";
 const OPENCLAW_REMNIC_LEGACY_PLUGIN_ID = "openclaw-engram";
 
@@ -698,22 +697,16 @@ export async function runCompatChecks(options: CompatCheckOptions): Promise<Comp
     const indexRaw = await readFile(indexPath, "utf-8");
     const structuralSource = stripCommentsAndStrings(indexRaw);
     const hooks = parseHookRegistrations(indexRaw);
-    const missingLegacy = REQUIRED_HOOKS_LEGACY.filter((hook) => !hooks.has(hook));
-    const missingNew = REQUIRED_HOOKS_NEW.filter((hook) => !hooks.has(hook));
+    const missingHooks = REQUIRED_HOOKS.filter((hook) => !hooks.has(hook));
     // registerMemoryPromptSection is a valid alternative to the recall hook only
     // when it is registered on the OpenClaw plugin API object.
     const hasMemoryPromptSection = hasMemoryPromptSectionRegistration(structuralSource);
-    const missingLegacyAdj = hasMemoryPromptSection
-      ? missingLegacy.filter((h) => h !== "before_agent_start")
-      : missingLegacy;
-    const missingNewAdj = hasMemoryPromptSection
-      ? missingNew.filter((h) => h !== "before_prompt_build")
-      : missingNew;
-    // Accept whichever hook set has fewer missing entries
-    const missingHooks = missingNewAdj.length <= missingLegacyAdj.length ? missingNewAdj : missingLegacyAdj;
+    const missingRequiredHooks = hasMemoryPromptSection
+      ? missingHooks.filter((hook) => hook !== "before_prompt_build")
+      : missingHooks;
     const hasGatewayStartHook = hooks.has("gateway_start");
     const hasServiceStart = hasServiceStartRegistration(structuralSource);
-    if (missingHooks.length === 0 && (hasGatewayStartHook || hasServiceStart)) {
+    if (missingRequiredHooks.length === 0 && (hasGatewayStartHook || hasServiceStart)) {
       checks.push({
         id: "hook-registration-core",
         title: "Core hook registration",
@@ -722,18 +715,25 @@ export async function runCompatChecks(options: CompatCheckOptions): Promise<Comp
       });
     } else {
       const missingParts: string[] = [];
-      if (missingHooks.length > 0) {
-        missingParts.push(`hooks: ${missingHooks.join(", ")}`);
+      if (missingRequiredHooks.length > 0) {
+        missingParts.push(`hooks: ${missingRequiredHooks.join(", ")}`);
       }
       if (!hasGatewayStartHook && !hasServiceStart) {
         missingParts.push("startup wiring: gateway_start hook or api.registerService({ start })");
       }
+      const remediationParts: string[] = [];
+      if (missingRequiredHooks.length > 0) {
+        remediationParts.push(`registers ${missingRequiredHooks.join(", ")}`);
+      }
+      if (!hasGatewayStartHook && !hasServiceStart) {
+        remediationParts.push("registers gateway_start or api.registerService({ start })");
+      }
       checks.push({
         id: "hook-registration-core",
         title: "Core hook registration",
         level: "error",
         message: `Missing expected registration(s): ${missingParts.join("; ")}`,
-        remediation: "Ensure src/index.ts registers before_prompt_build (or before_agent_start) and agent_end, plus either gateway_start or api.registerService({ start }).",
+        remediation: `Ensure src/index.ts ${remediationParts.join(" and ")}.`,
       });
     }
 

package/src/external-wiki-cli.ts

@@ -1,4 +1,4 @@
-import { type ExternalWikiRoot, searchExternalWikis } from "./external-wiki-search.js";
+import { type ExternalWikiRoot, type ExternalWikiSearchResult, searchExternalWikis } from "./external-wiki-search.js";
 
 interface ExternalWikiCliIo {
   readonly stdout: { write(chunk: string): unknown };
@@ -13,28 +13,25 @@ export async function runExternalWikiCliCommand(
   args: readonly string[],
   io: ExternalWikiCliIo
 ): Promise<number> {
-  if (args.length === 0 || args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
+  if (args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
     io.stdout.write(USAGE);
     return 0;
   }
-  if (args[0] !== "search") {
-    io.stderr.write(`external-wiki: unknown command '${args[0]}'\n${USAGE}`);
-    return 2;
-  }
+  const searchArgs = args[0] === "search" ? args.slice(1) : args;
 
   let limit: number | undefined;
   let wikiId: string | undefined;
   let maxCharsPerHit: number | undefined;
   let json = false;
   const queryParts: string[] = [];
-  for (let index = 1; index < args.length; index += 1) {
-    const argument = args[index];
+  for (let index = 0; index < searchArgs.length; index += 1) {
+    const argument = searchArgs[index];
     if (argument === "--json") {
       json = true;
       continue;
     }
     if (argument === "--limit" || argument === "--wiki-id" || argument === "--max-chars-per-hit") {
-      const value = args[index + 1];
+      const value = searchArgs[index + 1];
       if (value === undefined || value.startsWith("--")) {
         io.stderr.write(`external-wiki: ${argument} requires a value\n`);
         return 2;
@@ -68,25 +65,36 @@ export async function runExternalWikiCliCommand(
 
   const query = queryParts.join(" ").trim();
   if (query.length === 0) {
-    io.stderr.write(`external-wiki: query is required\n${USAGE}`);
-    return 2;
+    io.stderr.write("external-wiki: provide a search query\n");
+    return 1;
+  }
+  const enabled = roots.filter((root) => root.enabled !== false);
+  if (enabled.length === 0) {
+    io.stderr.write("external-wiki: no enabled wiki roots configured\n");
+    return 1;
   }
 
-  const result = await searchExternalWikis(roots, { query, limit, wikiId, maxCharsPerHit });
+  let result: ExternalWikiSearchResult;
+  try {
+    result = await searchExternalWikis(enabled, { query, limit, wikiId, maxCharsPerHit });
+  } catch (error) {
+    io.stderr.write(`external-wiki: ${error instanceof Error ? error.message : "search failed"}\n`);
+    return 1;
+  }
   if (json) {
     io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     return 0;
   }
 
-  io.stdout.write(`External wiki results for "${result.query}" (${result.count})\n`);
-  for (const hit of result.hits) {
-    const citation = hit.citations[0];
-    const location = citation ? `${citation.path}:${citation.lineStart}-${citation.lineEnd}` : hit.path;
-    io.stdout.write(`${hit.rank}. [${hit.wikiId}] ${hit.title} (${location})\n`);
-    io.stdout.write(`   ${hit.snippet.replace(/\s+/g, " ").trim()}\n`);
-  }
   if (result.degradedWikiIds.length > 0) {
-    io.stderr.write(`external-wiki: degraded roots: ${result.degradedWikiIds.join(", ")}\n`);
+    io.stderr.write(`Warning: degraded roots: ${result.degradedWikiIds.join(", ")}\n`);
+  }
+  if (result.hits.length === 0) {
+    io.stdout.write("No results.\n");
+    return 0;
+  }
+  for (const hit of result.hits) {
+    io.stdout.write(`[${hit.wikiId}] ${hit.path} (score ${hit.score})\n${hit.snippet}\n\n`);
   }
   return 0;
 }

package/src/external-wiki-search.test.ts

@@ -257,7 +257,7 @@ test("external wiki search fails open to filesystem candidates when a dedicated
   }
 });
 
-test("external wiki CLI searches multi-word queries and renders cited JSON or text", async () => {
+test("external wiki CLI preserves text contracts and supports cited JSON", async () => {
   const root = await createWiki("cli", {
     "INDEX.md": "- [[wiki/agents|Agent Planning]] - planner fan-out with citations\n",
     "wiki/agents.md": "# Agent Planning\n\nPlanner fan-out uses cited retrieval evidence.\n",
@@ -286,7 +286,7 @@ test("external wiki CLI searches multi-word queries and renders cited JSON or te
       stderr: { write: () => undefined },
     });
     assert.equal(textCode, 0);
-    assert.match(textOutput.join(""), /\[cli\] Agent Planning \(wiki\/agents\.md:\d+-\d+\)/);
+    assert.match(textOutput.join(""), /\[cli\] wiki\/agents\.md \(score [\d.]+\)/);
 
     const invalidErrors: string[] = [];
     const invalidCode = await runExternalWikiCliCommand([root], ["search", "--limit", "0", "query"], {
@@ -295,6 +295,72 @@ test("external wiki CLI searches multi-word queries and renders cited JSON or te
     });
     assert.equal(invalidCode, 2);
     assert.match(invalidErrors.join(""), /--limit must be an integer from 1 to 20/);
+
+    const noQueryErrors: string[] = [];
+    const noQueryCode = await runExternalWikiCliCommand([root], ["search"], {
+      stdout: { write: () => undefined },
+      stderr: { write: (chunk) => noQueryErrors.push(chunk) },
+    });
+    assert.equal(noQueryCode, 1);
+    assert.equal(noQueryErrors.join(""), "external-wiki: provide a search query\n");
+
+    const disabledErrors: string[] = [];
+    const disabledCode = await runExternalWikiCliCommand([{ ...root, enabled: false }], ["search", "planner"], {
+      stdout: { write: () => undefined },
+      stderr: { write: (chunk) => disabledErrors.push(chunk) },
+    });
+    assert.equal(disabledCode, 1);
+    assert.equal(disabledErrors.join(""), "external-wiki: no enabled wiki roots configured\n");
+
+    const emptyOutput: string[] = [];
+    const emptyCode = await runExternalWikiCliCommand([root], ["search", "unmatched-token"], {
+      stdout: { write: (chunk) => emptyOutput.push(chunk) },
+      stderr: { write: () => undefined },
+    });
+    assert.equal(emptyCode, 0);
+    assert.equal(emptyOutput.join(""), "No results.\n");
+
+    const searchErrors: string[] = [];
+    const searchErrorCode = await runExternalWikiCliCommand([root], ["search", "planner", "--wiki-id", "missing"], {
+      stdout: { write: () => undefined },
+      stderr: { write: (chunk) => searchErrors.push(chunk) },
+    });
+    assert.equal(searchErrorCode, 1);
+    assert.equal(searchErrors.join(""), "external-wiki: unknown external wiki: missing\n");
+
+    const legacyOutput: string[] = [];
+    const legacyCode = await runExternalWikiCliCommand([root], ["planner", "fan-out"], {
+      stdout: { write: (chunk) => legacyOutput.push(chunk) },
+      stderr: { write: () => undefined },
+    });
+    assert.equal(legacyCode, 0);
+    assert.match(legacyOutput.join(""), /^\[cli\] wiki\/agents\.md \(score [\d.]+\)/);
+
+    const degradedErrors: string[] = [];
+    const degradedCode = await runExternalWikiCliCommand(
+      [root, { ...root, id: "broken", rootDir: path.join(root.rootDir, "missing") }],
+      ["search", "planner"],
+      {
+        stdout: { write: () => undefined },
+        stderr: { write: (chunk) => degradedErrors.push(chunk) },
+      }
+    );
+    assert.equal(degradedCode, 0);
+    assert.equal(degradedErrors.join(""), "Warning: degraded roots: broken\n");
+
+    const allDegradedOutput: string[] = [];
+    const allDegradedErrors: string[] = [];
+    const allDegradedCode = await runExternalWikiCliCommand(
+      [{ ...root, id: "broken", rootDir: path.join(root.rootDir, "missing") }],
+      ["search", "planner"],
+      {
+        stdout: { write: (chunk) => allDegradedOutput.push(chunk) },
+        stderr: { write: (chunk) => allDegradedErrors.push(chunk) },
+      }
+    );
+    assert.equal(allDegradedCode, 0);
+    assert.equal(allDegradedOutput.join(""), "No results.\n");
+    assert.equal(allDegradedErrors.join(""), "Warning: degraded roots: broken\n");
   } finally {
     await removeWikis([root]);
   }

package/src/external-wiki.ts

@@ -170,9 +170,18 @@ function normalizeCatalogPath(target: string, config: ExternalWikiRoot, base: Ca
   }
 
   const pagesDir = path.posix.normalize(config.pagesDir);
-  const baseDir = base === "index" ? path.posix.dirname(config.indexFile) : pagesDir;
-  const rootRelativeTarget = path.posix.normalize(path.posix.join(baseDir, withoutFragment));
-  const relative = path.posix.relative(pagesDir, rootRelativeTarget);
+  let relative: string;
+  if (base === "index") {
+    const baseDir = path.posix.dirname(config.indexFile);
+    const rootRelativeTarget = path.posix.normalize(path.posix.join(baseDir, withoutFragment));
+    relative = path.posix.relative(pagesDir, rootRelativeTarget);
+  } else {
+    const pagesPrefix = pagesDir === "." ? "" : `${pagesDir}/`;
+    const stripped = pagesPrefix.length > 0 && withoutFragment.startsWith(pagesPrefix)
+      ? withoutFragment.slice(pagesPrefix.length)
+      : withoutFragment;
+    relative = path.posix.normalize(stripped);
+  }
   if (
     relative === ".." ||
     relative.startsWith("../") ||
@@ -416,38 +425,3 @@ export async function readExternalWikiPage(
     bytes: page.bytes,
   };
 }
-
-export async function runExternalWikiCliCommand(
-  roots: readonly ExternalWikiRoot[],
-  rest: readonly string[],
-  io: { stdout: NodeJS.WritableStream; stderr: NodeJS.WritableStream },
-): Promise<number> {
-  const { searchExternalWikis } = await import("./external-wiki-search.js");
-  const query = rest.filter((a) => !a.startsWith("-")).join(" ").trim();
-  if (!query) {
-    io.stderr.write("external-wiki: provide a search query\n");
-    return 1;
-  }
-  const enabled = roots.filter((r) => r.enabled !== false);
-  if (enabled.length === 0) {
-    io.stderr.write("external-wiki: no enabled wiki roots configured\n");
-    return 1;
-  }
-  try {
-    const result = await searchExternalWikis(enabled, { query });
-    if (result.hits.length === 0) {
-      io.stdout.write("No results.\n");
-      return 0;
-    }
-    for (const hit of result.hits) {
-      io.stdout.write(`[${hit.wikiId}] ${hit.path} (score ${hit.score})\n${hit.snippet}\n\n`);
-    }
-    if (result.degradedWikiIds.length > 0) {
-      io.stderr.write(`Warning: degraded roots: ${result.degradedWikiIds.join(", ")}\n`);
-    }
-    return 0;
-  } catch (error) {
-    io.stderr.write(`external-wiki: ${error instanceof Error ? error.message : "search failed"}\n`);
-    return 1;
-  }
-}