@remnic/core 1.1.12 → 1.1.14

package/src/recall-audit-anomaly.ts

@@ -0,0 +1,297 @@
+/**
+ * Recall-audit anomaly detector (issue #565 PR 5/5).
+ *
+ * Given a sequence of `RecallAuditEntry` records for a single principal /
+ * session, classify the series and emit `AnomalyFlag`s for suspicious
+ * patterns. Intended to run on both:
+ *
+ * 1. The MCP / HTTP access layers — every `recall` / `memory_search` /
+ *    `memory_timeline` call appends an audit entry and the detector is
+ *    invoked against the tail of the series (streaming mode).
+ * 2. The existing Openclaw hook (already writes `transcripts/*.jsonl`) —
+ *    the detector can be invoked out-of-band over the same entries.
+ *
+ * See the threat model §5 (gap: recall-audit was only on the Openclaw
+ * hook) and §6.3 (anomaly signals) for the patterns below.
+ *
+ * The module is pure: no I/O, no clock. Callers pass the entries +
+ * configured thresholds; the detector returns a deterministic classification.
+ *
+ * Patterns detected:
+ *
+ * - `repeat-query` — the same normalized query text issued more than N
+ *   times in the window. Covers the ADAM "exploitation" phase where the
+ *   attacker re-queries a high-signal token until it plateaus.
+ * - `namespace-walk` — the same principal's queries visit more than N
+ *   distinct candidate memory namespaces in the window. Suggests the
+ *   attacker is enumerating the namespace tree for leaks.
+ * - `high-cardinality-return` — a single recall surfaced more than N
+ *   candidate memory IDs in one response. Covers the "one query, dump
+ *   everything" exfiltration path.
+ * - `rapid-fire` — more than N recalls in the window irrespective of
+ *   content. Blunt instrument; useful when nothing else fires.
+ *
+ * Each flag carries the entry indices that support it so an audit UI can
+ * highlight the underlying evidence.
+ */
+
+import type { RecallAuditEntry } from "./recall-audit.js";
+
+export type AnomalyKind =
+  | "repeat-query"
+  | "namespace-walk"
+  | "high-cardinality-return"
+  | "rapid-fire";
+
+export type AnomalySeverity = "info" | "warn" | "alert";
+
+export interface AnomalyFlag {
+  kind: AnomalyKind;
+  severity: AnomalySeverity;
+  /** Human-readable rationale, e.g. `"query 'alex' repeated 12 times in 60s"`. */
+  message: string;
+  /** Indices into the supplied `entries` array that triggered the flag. */
+  entryIndices: number[];
+  /**
+   * Optional extra signal the caller can use to key metrics. For
+   * `repeat-query` this is the normalized query text; for
+   * `namespace-walk` it is the namespace count; etc.
+   */
+  signal?: string | number;
+}
+
+export interface AnomalyDetectorConfig {
+  /** Detector feature-flag. Defaults to false — ships disabled. */
+  enabled?: boolean;
+  /**
+   * Rolling window in ms. The detector only considers entries whose `ts`
+   * falls within `[now - windowMs, now]`. Default 5 minutes.
+   */
+  windowMs?: number;
+  /**
+   * Threshold for `repeat-query`: a normalized query repeated more than
+   * this many times in the window trips the flag. Default 5.
+   */
+  repeatQueryLimit?: number;
+  /**
+   * Threshold for `namespace-walk`: more than this many distinct
+   * candidate namespaces in the window trips the flag. Default 3.
+   */
+  namespaceWalkLimit?: number;
+  /**
+   * Threshold for `high-cardinality-return`: more than this many
+   * `candidateMemoryIds` in a single entry trips the flag. Default 50.
+   */
+  highCardinalityReturnLimit?: number;
+  /**
+   * Threshold for `rapid-fire`: more than this many entries in the
+   * window trips the flag. Default 30. (Matches the default
+   * `recallCrossNamespaceBudgetHardLimit` from PR 4.)
+   */
+  rapidFireLimit?: number;
+}
+
+export const DEFAULT_ANOMALY_DETECTOR_CONFIG: Required<AnomalyDetectorConfig> =
+  Object.freeze({
+    enabled: false,
+    windowMs: 5 * 60_000,
+    repeatQueryLimit: 5,
+    namespaceWalkLimit: 3,
+    highCardinalityReturnLimit: 50,
+    rapidFireLimit: 30,
+  });
+
+export interface AnomalyDetectorInput {
+  entries: readonly RecallAuditEntry[];
+  /** Current time in epoch ms. Entries older than `now - windowMs` are ignored. */
+  now: number;
+  config?: AnomalyDetectorConfig;
+}
+
+export interface AnomalyDetectorResult {
+  /** All flags ordered by descending severity then kind. */
+  flags: AnomalyFlag[];
+  /** Number of entries inside the active window (after filtering). */
+  windowEntryCount: number;
+  /** Window size actually used, in ms. */
+  windowMs: number;
+}
+
+function effectiveConfig(
+  raw: AnomalyDetectorConfig | undefined,
+): Required<AnomalyDetectorConfig> {
+  const base = { ...DEFAULT_ANOMALY_DETECTOR_CONFIG };
+  if (!raw) return base;
+  const out = { ...base };
+  if (typeof raw.enabled === "boolean") out.enabled = raw.enabled;
+  if (
+    typeof raw.windowMs === "number" &&
+    Number.isFinite(raw.windowMs) &&
+    raw.windowMs > 0
+  ) {
+    out.windowMs = raw.windowMs;
+  }
+  for (const key of [
+    "repeatQueryLimit",
+    "namespaceWalkLimit",
+    "highCardinalityReturnLimit",
+    "rapidFireLimit",
+  ] as const) {
+    const v = raw[key];
+    if (typeof v === "number" && Number.isFinite(v) && v > 0) {
+      const floored = Math.floor(v);
+      // Guard against fractional inputs (e.g. 0.5) that floor to 0 and
+      // turn every detector into a flood-on-anything trigger.
+      out[key] = floored >= 1 ? floored : base[key];
+    }
+  }
+  return out;
+}
+
+/**
+ * Normalize query text so cosmetic variation doesn't defeat the
+ * repeat-query detector. Lowercase, collapse whitespace, trim.
+ */
+export function normalizeQueryText(raw: string): string {
+  if (typeof raw !== "string") return "";
+  return raw.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+const SEVERITY_ORDER: Record<AnomalySeverity, number> = {
+  alert: 0,
+  warn: 1,
+  info: 2,
+};
+
+function parseTsMs(ts: string): number | null {
+  const n = new Date(ts).getTime();
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Run the detector against a series of audit entries. Pure; no side
+ * effects.
+ */
+export function detectRecallAnomalies(
+  input: AnomalyDetectorInput,
+): AnomalyDetectorResult {
+  const cfg = effectiveConfig(input.config);
+  const cutoff = input.now - cfg.windowMs;
+
+  // Filter to the active window, preserving original indices so flags
+  // can reference the caller's entries array directly.
+  const windowed: { entry: RecallAuditEntry; index: number }[] = [];
+  for (let i = 0; i < input.entries.length; i++) {
+    const entry = input.entries[i]!;
+    const tsMs = parseTsMs(entry.ts);
+    if (tsMs === null) continue;
+    if (tsMs >= cutoff && tsMs <= input.now) {
+      windowed.push({ entry, index: i });
+    }
+  }
+
+  if (!cfg.enabled) {
+    return { flags: [], windowEntryCount: windowed.length, windowMs: cfg.windowMs };
+  }
+
+  const flags: AnomalyFlag[] = [];
+
+  // 1) repeat-query: bucket by normalized queryText.
+  {
+    const byQuery = new Map<string, number[]>();
+    for (const { entry, index } of windowed) {
+      const key = normalizeQueryText(entry.queryText);
+      if (key.length === 0) continue;
+      const arr = byQuery.get(key);
+      if (arr) arr.push(index);
+      else byQuery.set(key, [index]);
+    }
+    for (const [query, indices] of byQuery) {
+      if (indices.length > cfg.repeatQueryLimit) {
+        flags.push({
+          kind: "repeat-query",
+          severity: "warn",
+          message: `query "${query}" repeated ${indices.length} times in ${cfg.windowMs}ms`,
+          entryIndices: indices.slice(),
+          signal: query,
+        });
+      }
+    }
+  }
+
+  // 2) namespace-walk: distinct namespaces extracted from candidateMemoryIds.
+  //    Candidate IDs that begin with `<namespace>/` disclose the namespace
+  //    directly. IDs without a slash prefix (e.g. bare filenames) do not
+  //    disclose a namespace, but a recall whose result list mixes
+  //    prefixed AND unprefixed IDs is itself suspicious — it suggests
+  //    the backend leaked memories from both the caller's own namespace
+  //    and named tenants. We track unprefixed IDs under a reserved
+  //    sentinel namespace so they still contribute to the count when a
+  //    trail is all-unprefixed (common for older audit entries sourced
+  //    from filenames).
+  {
+    const namespaces = new Set<string>();
+    const indices: number[] = [];
+    for (const { entry, index } of windowed) {
+      if (!Array.isArray(entry.candidateMemoryIds)) continue;
+      let touchedAny = false;
+      for (const id of entry.candidateMemoryIds) {
+        if (typeof id !== "string" || id.length === 0) continue;
+        const slash = id.indexOf("/");
+        if (slash > 0) {
+          namespaces.add(id.slice(0, slash));
+        } else {
+          namespaces.add("__unprefixed__");
+        }
+        touchedAny = true;
+      }
+      if (touchedAny) indices.push(index);
+    }
+    if (namespaces.size > cfg.namespaceWalkLimit) {
+      flags.push({
+        kind: "namespace-walk",
+        severity: "alert",
+        message: `queries touched ${namespaces.size} distinct namespaces in ${cfg.windowMs}ms`,
+        entryIndices: indices,
+        signal: namespaces.size,
+      });
+    }
+  }
+
+  // 3) high-cardinality-return: one entry's candidateMemoryIds > limit.
+  {
+    for (const { entry, index } of windowed) {
+      const ids = Array.isArray(entry.candidateMemoryIds)
+        ? entry.candidateMemoryIds
+        : [];
+      if (ids.length > cfg.highCardinalityReturnLimit) {
+        flags.push({
+          kind: "high-cardinality-return",
+          severity: "alert",
+          message: `single recall returned ${ids.length} candidate memory IDs`,
+          entryIndices: [index],
+          signal: ids.length,
+        });
+      }
+    }
+  }
+
+  // 4) rapid-fire: windowed count alone.
+  if (windowed.length > cfg.rapidFireLimit) {
+    flags.push({
+      kind: "rapid-fire",
+      severity: "warn",
+      message: `${windowed.length} recall entries in ${cfg.windowMs}ms`,
+      entryIndices: windowed.map((w) => w.index),
+      signal: windowed.length,
+    });
+  }
+
+  flags.sort((a, b) => {
+    const s = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    if (s !== 0) return s;
+    return a.kind.localeCompare(b.kind);
+  });
+
+  return { flags, windowEntryCount: windowed.length, windowMs: cfg.windowMs };
+}

package/src/recall-audit.test.ts

@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, mkdir, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  appendRecallAuditEntry,
+  buildRecallAuditPath,
+  pruneRecallAuditEntries,
+} from "./recall-audit.js";
+
+test("appendRecallAuditEntry writes a daily per-session JSONL audit shard", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-recall-audit-"));
+  const entry = {
+    ts: "2026-04-12T14:30:12.445Z",
+    sessionKey: "agent/main:session/1",
+    agentId: "main",
+    trigger: "before_prompt_build",
+    queryText: "How did the CI outage resolve?",
+    candidateMemoryIds: ["mem_1", "mem_2"],
+    summary: "CI recovered after the flaky worker drain.",
+    injectedChars: 48,
+    toggleState: "enabled" as const,
+    latencyMs: 123,
+  };
+
+  const filePath = await appendRecallAuditEntry(root, entry);
+  assert.equal(
+    filePath,
+    buildRecallAuditPath(root, entry.ts, entry.sessionKey),
+  );
+  const raw = await readFile(filePath, "utf8");
+  const lines = raw.trim().split("\n");
+  assert.equal(lines.length, 1);
+  assert.deepEqual(JSON.parse(lines[0] ?? "{}"), entry);
+});
+
+test("pruneRecallAuditEntries removes day directories older than retention", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-recall-prune-"));
+  const keepDir = path.join(root, "transcripts", "2026-04-11");
+  const deleteDir = path.join(root, "transcripts", "2026-04-01");
+  await mkdir(keepDir, { recursive: true });
+  await mkdir(deleteDir, { recursive: true });
+
+  const removed = await pruneRecallAuditEntries(root, 5, new Date("2026-04-12T12:00:00.000Z"));
+  assert.deepEqual(removed, [deleteDir]);
+
+  assert.equal((await stat(keepDir)).isDirectory(), true);
+  await assert.rejects(stat(deleteDir));
+});

package/src/recall-audit.ts

@@ -0,0 +1,72 @@
+import type { Dirent } from "node:fs";
+import { appendFile, mkdir, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+
+export interface RecallAuditEntry {
+  ts: string;
+  sessionKey: string;
+  agentId: string;
+  trigger: string;
+  queryText: string;
+  candidateMemoryIds: string[];
+  summary: string | null;
+  injectedChars: number;
+  toggleState: "enabled" | "disabled-primary" | "disabled-secondary";
+  latencyMs?: number;
+  plannerMode?: string;
+  requestedMode?: string;
+  fallbackUsed?: boolean;
+}
+
+function formatIsoDate(ts: string): string {
+  const normalized = new Date(ts);
+  if (Number.isNaN(normalized.getTime())) {
+    return new Date().toISOString().slice(0, 10);
+  }
+  return normalized.toISOString().slice(0, 10);
+}
+
+export function buildRecallAuditPath(rootDir: string, ts: string, sessionKey: string): string {
+  const safeSessionKey = encodeURIComponent(sessionKey);
+  return path.join(rootDir, "transcripts", formatIsoDate(ts), `${safeSessionKey}.jsonl`);
+}
+
+export async function appendRecallAuditEntry(
+  rootDir: string,
+  entry: RecallAuditEntry,
+): Promise<string> {
+  const filePath = buildRecallAuditPath(rootDir, entry.ts, entry.sessionKey);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await appendFile(filePath, `${JSON.stringify(entry)}\n`, "utf8");
+  return filePath;
+}
+
+export async function pruneRecallAuditEntries(
+  rootDir: string,
+  retentionDays: number,
+  now: Date = new Date(),
+): Promise<string[]> {
+  const transcriptsDir = path.join(rootDir, "transcripts");
+  const removed: string[] = [];
+  const cutoff = new Date(now);
+  cutoff.setUTCHours(0, 0, 0, 0);
+  cutoff.setUTCDate(cutoff.getUTCDate() - Math.max(1, Math.floor(retentionDays)));
+  let entries: Dirent[];
+  try {
+    entries = await readdir(transcriptsDir, { withFileTypes: true });
+  } catch {
+    return removed;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.name)) continue;
+    const day = new Date(`${entry.name}T00:00:00.000Z`);
+    if (Number.isNaN(day.getTime()) || day >= cutoff) continue;
+    const dirPath = path.join(transcriptsDir, entry.name);
+    await rm(dirPath, { recursive: true, force: true });
+    removed.push(dirPath);
+  }
+
+  return removed;
+}

package/src/recall-budget-config.test.ts

@@ -0,0 +1,87 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+
+test("parseConfig applies recall timeout and qmd recall cache defaults", () => {
+  const config = parseConfig({});
+
+  assert.equal(config.recallOuterTimeoutMs, 75_000);
+  assert.equal(config.recallCoreDeadlineMs, 75_000);
+  assert.equal(config.recallEnrichmentDeadlineMs, 25_000);
+  assert.equal(config.qmdRecallCacheTtlMs, 60_000);
+  assert.equal(config.qmdRecallCacheStaleTtlMs, 10 * 60_000);
+  assert.equal(config.qmdRecallCacheMaxEntries, 128);
+});
+
+test("parseConfig respects explicit recall timeout and qmd recall cache settings", () => {
+  const config = parseConfig({
+    recallOuterTimeoutMs: 18_000,
+    recallCoreDeadlineMs: 9_000,
+    recallEnrichmentDeadlineMs: 2_500,
+    qmdRecallCacheTtlMs: 5_000,
+    qmdRecallCacheStaleTtlMs: 45_000,
+    qmdRecallCacheMaxEntries: 32,
+  });
+
+  assert.equal(config.recallOuterTimeoutMs, 18_000);
+  assert.equal(config.recallCoreDeadlineMs, 9_000);
+  assert.equal(config.recallEnrichmentDeadlineMs, 2_500);
+  assert.equal(config.qmdRecallCacheTtlMs, 5_000);
+  assert.equal(config.qmdRecallCacheStaleTtlMs, 45_000);
+  assert.equal(config.qmdRecallCacheMaxEntries, 32);
+});
+
+test("parseConfig preserves zero qmd recall cache entries to disable caching", () => {
+  const config = parseConfig({
+    qmdRecallCacheMaxEntries: 0,
+  });
+
+  assert.equal(config.qmdRecallCacheMaxEntries, 0);
+});
+
+test("parseConfig preserves zero recall timeout settings to disable those limits", () => {
+  const config = parseConfig({
+    recallOuterTimeoutMs: 0,
+    recallCoreDeadlineMs: 0,
+    recallEnrichmentDeadlineMs: 0,
+  });
+
+  assert.equal(config.recallOuterTimeoutMs, 0);
+  assert.equal(config.recallCoreDeadlineMs, 0);
+  assert.equal(config.recallEnrichmentDeadlineMs, 0);
+});
+
+test("parseConfig applies MMR defaults (enabled, lambda=0.7, topN=40)", () => {
+  const config = parseConfig({});
+  assert.equal(config.recallMmrEnabled, true);
+  assert.equal(config.recallMmrLambda, 0.7);
+  assert.equal(config.recallMmrTopN, 40);
+});
+
+test("parseConfig honors explicit MMR overrides", () => {
+  const config = parseConfig({
+    recallMmrEnabled: false,
+    recallMmrLambda: 0.3,
+    recallMmrTopN: 25,
+  });
+  assert.equal(config.recallMmrEnabled, false);
+  assert.equal(config.recallMmrLambda, 0.3);
+  assert.equal(config.recallMmrTopN, 25);
+});
+
+test("parseConfig clamps MMR lambda into [0, 1]", () => {
+  const tooLow = parseConfig({ recallMmrLambda: -0.5 });
+  assert.equal(tooLow.recallMmrLambda, 0);
+  const tooHigh = parseConfig({ recallMmrLambda: 1.7 });
+  assert.equal(tooHigh.recallMmrLambda, 1);
+});
+
+test("parseConfig preserves recallMmrTopN=0 as a true zero limit", () => {
+  // AGENTS.md §4 ("Config is runtime API"): `0` limits are compatibility
+  // guarantees. The write-time representation of `recallMmrTopN=0` must be
+  // preserved, and the read-time behavior in applyMmrToQmdResults must
+  // honor the zero limit by skipping MMR entirely (see orchestrator.ts).
+  const config = parseConfig({ recallMmrTopN: 0 });
+  assert.equal(config.recallMmrTopN, 0);
+});

package/src/recall-disclosure-escalation.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Tests for the disclosure auto-escalation policy (issue #677 PR 4/4).
+ * Pure helper, exhaustive coverage of the decision tree.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  DISCLOSURE_ESCALATION_MODES,
+  DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD,
+  decideDisclosureEscalation,
+  isDisclosureEscalationMode,
+} from "./recall-disclosure-escalation.js";
+
+test("isDisclosureEscalationMode accepts the two valid modes only", () => {
+  assert.equal(isDisclosureEscalationMode("manual"), true);
+  assert.equal(isDisclosureEscalationMode("auto"), true);
+  assert.equal(isDisclosureEscalationMode("AUTO"), false);
+  assert.equal(isDisclosureEscalationMode(""), false);
+  assert.equal(isDisclosureEscalationMode(undefined), false);
+  assert.equal(isDisclosureEscalationMode(42), false);
+});
+
+test("DISCLOSURE_ESCALATION_MODES is the single source of truth", () => {
+  assert.deepStrictEqual([...DISCLOSURE_ESCALATION_MODES], ["manual", "auto"]);
+});
+
+test("manual mode never escalates regardless of confidence", () => {
+  const decision = decideDisclosureEscalation({
+    mode: "manual",
+    threshold: 0.5,
+    originalDisclosure: "chunk",
+    callerProvidedDisclosure: false,
+    topKConfidence: 0.0,
+  });
+  assert.equal(decision.effective, "chunk");
+  assert.equal(decision.escalated, false);
+  assert.match(decision.reason, /manual/);
+});
+
+test("auto + caller-explicit disclosure does not escalate (respects caller)", () => {
+  const decision = decideDisclosureEscalation({
+    mode: "auto",
+    threshold: 0.5,
+    originalDisclosure: "chunk",
+    callerProvidedDisclosure: true,
+    topKConfidence: 0.0,
+  });
+  assert.equal(decision.effective, "chunk");
+  assert.equal(decision.escalated, false);
+  assert.match(decision.reason, /caller-explicit/);
+});
+
+test("auto + section/raw original is not auto-promoted", () => {
+  for (const original of ["section", "raw"] as const) {
+    const decision = decideDisclosureEscalation({
+      mode: "auto",
+      threshold: 0.5,
+      originalDisclosure: original,
+      callerProvidedDisclosure: false,
+      topKConfidence: 0.0,
+    });
+    assert.equal(decision.effective, original);
+    assert.equal(decision.escalated, false);
+    assert.match(decision.reason, /not-eligible/);
+  }
+});
+
+test("auto + chunk + low confidence escalates to section", () => {
+  const decision = decideDisclosureEscalation({
+    mode: "auto",
+    threshold: 0.5,
+    originalDisclosure: "chunk",
+    callerProvidedDisclosure: false,
+    topKConfidence: 0.3,
+  });
+  assert.equal(decision.effective, "section");
+  assert.equal(decision.escalated, true);
+  assert.match(decision.reason, /top-k-confidence=0.300<0.5/);
+});
+
+test("auto + chunk + high confidence stays at chunk", () => {
+  const decision = decideDisclosureEscalation({
+    mode: "auto",
+    threshold: 0.5,
+    originalDisclosure: "chunk",
+    callerProvidedDisclosure: false,
+    topKConfidence: 0.9,
+  });
+  assert.equal(decision.effective, "chunk");
+  assert.equal(decision.escalated, false);
+  assert.match(decision.reason, />=0.5/);
+});
+
+test("auto + chunk + confidence equal to threshold stays at chunk (strict less-than)", () => {
+  const decision = decideDisclosureEscalation({
+    mode: "auto",
+    threshold: 0.5,
+    originalDisclosure: "chunk",
+    callerProvidedDisclosure: false,
+    topKConfidence: 0.5,
+  });
+  assert.equal(decision.effective, "chunk");
+  assert.equal(decision.escalated, false);
+});
+
+test("auto + missing topK confidence does not escalate", () => {
+  const decision = decideDisclosureEscalation({
+    mode: "auto",
+    threshold: 0.5,
+    originalDisclosure: "chunk",
+    callerProvidedDisclosure: false,
+    topKConfidence: undefined,
+  });
+  assert.equal(decision.effective, "chunk");
+  assert.equal(decision.escalated, false);
+  assert.match(decision.reason, /no-top-k-confidence/);
+});
+
+test("auto + non-finite topK confidence does not escalate", () => {
+  for (const bad of [NaN, Infinity, -Infinity]) {
+    const decision = decideDisclosureEscalation({
+      mode: "auto",
+      threshold: 0.5,
+      originalDisclosure: "chunk",
+      callerProvidedDisclosure: false,
+      topKConfidence: bad,
+    });
+    assert.equal(decision.effective, "chunk");
+    assert.equal(decision.escalated, false);
+  }
+});
+
+test("auto + invalid threshold falls back to default and still uses confidence signal", () => {
+  // threshold out of range → fallback to DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD (0.5).
+  // Confidence 0.3 < 0.5 → escalate.
+  const decision = decideDisclosureEscalation({
+    mode: "auto",
+    threshold: -1,
+    originalDisclosure: "chunk",
+    callerProvidedDisclosure: false,
+    topKConfidence: 0.3,
+  });
+  assert.equal(decision.effective, "section");
+  assert.equal(decision.escalated, true);
+  assert.match(
+    decision.reason,
+    new RegExp(`<${DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD}`),
+  );
+});
+
+test("auto + threshold above 1 falls back to default", () => {
+  const decision = decideDisclosureEscalation({
+    mode: "auto",
+    threshold: 999,
+    originalDisclosure: "chunk",
+    callerProvidedDisclosure: false,
+    topKConfidence: 0.4,
+  });
+  assert.equal(decision.effective, "section");
+  assert.equal(decision.escalated, true);
+});
+
+test("auto + zero confidence (no results) escalates", () => {
+  const decision = decideDisclosureEscalation({
+    mode: "auto",
+    threshold: 0.5,
+    originalDisclosure: "chunk",
+    callerProvidedDisclosure: false,
+    topKConfidence: 0,
+  });
+  assert.equal(decision.effective, "section");
+  assert.equal(decision.escalated, true);
+});
+
+test("decision.reason is always a non-empty string", () => {
+  // Guard against accidentally returning an empty reason — operator
+  // telemetry depends on it.
+  const branches = [
+    { mode: "manual" as const, callerProvidedDisclosure: false, topKConfidence: 0.3 },
+    { mode: "auto" as const, callerProvidedDisclosure: true, topKConfidence: 0.3 },
+    { mode: "auto" as const, callerProvidedDisclosure: false, topKConfidence: undefined },
+    { mode: "auto" as const, callerProvidedDisclosure: false, topKConfidence: 0.3 },
+    { mode: "auto" as const, callerProvidedDisclosure: false, topKConfidence: 0.9 },
+  ];
+  for (const branch of branches) {
+    const decision = decideDisclosureEscalation({
+      threshold: 0.5,
+      originalDisclosure: "chunk",
+      ...branch,
+    });
+    assert.equal(typeof decision.reason, "string");
+    assert.ok(decision.reason.length > 0, `empty reason for branch ${JSON.stringify(branch)}`);
+  }
+});