@remnic/core 9.69.47 → 9.69.49

package/src/experience/session-experience.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Session-end agent-experience extraction (issue #2979).
+ *
+ * Deterministic Situation/Approach/Reflection episode extraction from a
+ * completed session transcript, plus the privacy/trust gate: with
+ * `sessionExperience.enabled` off the run performs ZERO storage calls
+ * (not even reads), and when on it writes at most one agent-subject,
+ * `pending_review` procedure memory per session key.
+ */
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { parseConfig } from "../config.js";
+import type { BufferTurn, MemoryFile, PluginConfig } from "../types.js";
+import type { SealedMemoryEnvelope } from "../write-envelope.js";
+import { StorageManager } from "../index.js";
+import {
+  SESSION_EXPERIENCE_CONFIG_DEFAULTS,
+  parseSessionExperienceConfig,
+} from "./session-experience-config.js";
+import {
+  extractExperienceEpisode,
+  runSessionExperienceExtraction,
+} from "./session-experience.js";
+
+function turn(role: "user" | "assistant", content: string): BufferTurn {
+  return { role, content, timestamp: "2026-01-15T10:00:00.000Z" };
+}
+
+/** A representative successful coding session transcript. */
+function successSession(): BufferTurn[] {
+  return [
+    turn("user", "Fix the failing integration test in the payments module. The test times out after 30 seconds."),
+    turn("assistant", "I will inspect the payments test file and reproduce the timeout locally first."),
+    turn("assistant", "The timeout came from an unawaited database call in the test setup. I added the missing await."),
+    turn("assistant", "Verified: the payments integration test passes now and the full suite is green."),
+  ];
+}
+
+/** A representative failed session transcript (refusal/failure is signal). */
+function failureSession(): BufferTurn[] {
+  return [
+    turn("user", "Migrate the billing export job to the new queue library before the release cut."),
+    turn("assistant", "I will port the export job onto the new queue client and run the smoke suite."),
+    turn("assistant", "The migration failed: the new queue library cannot serialize the billing payload format."),
+  ];
+}
+
+/** Minimal structural stand-in for StorageManager; records every call. */
+function recordingStorage(existing: MemoryFile[] = []) {
+  const calls: { readAllMemories: number; writeSealedMemory: SealedMemoryEnvelope[] } = {
+    readAllMemories: 0,
+    writeSealedMemory: [],
+  };
+  const storage = {
+    async readAllMemories() {
+      calls.readAllMemories += 1;
+      return existing;
+    },
+    async writeSealedMemory(envelope: SealedMemoryEnvelope) {
+      calls.writeSealedMemory.push(envelope);
+      return { id: "written-once" };
+    },
+  };
+  return { storage, calls };
+}
+
+function enabledConfig(memoryDir: string): PluginConfig {
+  return parseConfig({ memoryDir, sessionExperience: { enabled: true } });
+}
+
+test("extractExperienceEpisode derives the situation/approach/reflection classes from a session transcript", () => {
+  const episode = extractExperienceEpisode(successSession());
+  assert.ok(episode, "a representative session must yield an episode");
+  assert.match(episode.situation, /Fix the failing integration test/);
+  assert.match(episode.situation, /payments/i);
+  assert.match(episode.approach, /inspect the payments test file/);
+  assert.equal(episode.outcomeKind, "success");
+  assert.match(episode.reflection, /succeed|pass/i);
+  // Deterministic: identical transcript, identical episode.
+  assert.deepEqual(extractExperienceEpisode(successSession()), episode);
+});
+
+test("extractExperienceEpisode records failure as signal, not a skip", () => {
+  const episode = extractExperienceEpisode(failureSession());
+  assert.ok(episode);
+  assert.equal(episode.outcomeKind, "failure");
+  assert.match(episode.reflection, /fail/i);
+  assert.match(episode.reflection, /cannot serialize the billing payload/);
+});
+
+test("extractExperienceEpisode returns null without a task or without agent work", () => {
+  assert.equal(extractExperienceEpisode([]), null);
+  assert.equal(extractExperienceEpisode([turn("assistant", "Working on it. Verified the fix.")]), null);
+  assert.equal(extractExperienceEpisode([turn("user", "Please fix the flaky payments test soon.")]), null);
+});
+
+test("gate off performs zero storage calls — nothing is read, nothing is written", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-sx-off-"));
+  try {
+    const config = parseConfig({ memoryDir });
+    assert.equal(config.sessionExperience.enabled, false);
+    const { storage, calls } = recordingStorage();
+    const result = await runSessionExperienceExtraction({
+      turns: successSession(),
+      sessionKey: "session-off",
+      config,
+      storage,
+    });
+    assert.deepEqual(result, { written: false, skippedReason: "session_experience_disabled" });
+    assert.equal(calls.readAllMemories, 0, "gate off must not even read storage");
+    assert.equal(calls.writeSealedMemory.length, 0, "gate off must not compose or write anything");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("gate on writes exactly one pending_review agent-subject procedure memory per session", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-sx-on-"));
+  try {
+    const { storage, calls } = recordingStorage();
+    const result = await runSessionExperienceExtraction({
+      turns: successSession(),
+      sessionKey: "session-on",
+      config: enabledConfig(memoryDir),
+      storage,
+    });
+    assert.equal(result.written, true);
+    assert.equal(calls.writeSealedMemory.length, 1, "at most one experience per session");
+    const envelope = calls.writeSealedMemory[0];
+    assert.equal(envelope.category, "procedure");
+    assert.equal(envelope.subject, "agent");
+    assert.equal(envelope.source, "session-experience");
+    assert.ok(envelope.structuredAttributes?.experience_session_hash, "dedupe hash must be stamped");
+    assert.equal(envelope.structuredAttributes?.experience_outcome, "success");
+    assert.match(envelope.content, /Situation: Fix the failing integration test/);
+    assert.match(envelope.content, /Approach: /);
+    assert.match(envelope.content, /Reflection: /);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a repeated session_end for the same session key dedupes to zero new writes", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-sx-dup-"));
+  try {
+    const realStorage = new StorageManager(memoryDir);
+    await realStorage.ensureDirectories();
+    try {
+      const first = await runSessionExperienceExtraction({
+        turns: successSession(),
+        sessionKey: "session-dedupe",
+        config: enabledConfig(memoryDir),
+        storage: realStorage,
+      });
+      assert.equal(first.written, true);
+      const second = await runSessionExperienceExtraction({
+        turns: successSession(),
+        sessionKey: "session-dedupe",
+        config: enabledConfig(memoryDir),
+        storage: realStorage,
+      });
+      assert.deepEqual(second, { written: false, skippedReason: "duplicate_session" });
+      const experiences = (await realStorage.readAllMemories()).filter(
+        (m) => m.frontmatter.structuredAttributes?.experience_session_hash !== undefined,
+      );
+      assert.equal(experiences.length, 1, "replay must not duplicate the episode");
+      assert.equal(experiences[0]?.frontmatter.status, "pending_review", "trust-mode review by default");
+      assert.equal(experiences[0]?.frontmatter.subject, "agent");
+      assert.equal(experiences[0]?.frontmatter.category, "procedure");
+    } finally {
+      // StorageManager holds no explicit dispose; the temp dir removal below
+      // is the cleanup.
+    }
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("deadline and abort are honored before any write", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-sx-dl-"));
+  try {
+    const { storage, calls } = recordingStorage();
+    const deadline = await runSessionExperienceExtraction({
+      turns: successSession(),
+      sessionKey: "session-deadline",
+      config: enabledConfig(memoryDir),
+      storage,
+      deadlineMs: Date.now() - 1,
+    });
+    assert.deepEqual(deadline, { written: false, skippedReason: "deadline_elapsed" });
+    const controller = new AbortController();
+    controller.abort();
+    const aborted = await runSessionExperienceExtraction({
+      turns: successSession(),
+      sessionKey: "session-abort",
+      config: enabledConfig(memoryDir),
+      storage,
+      abortSignal: controller.signal,
+    });
+    assert.deepEqual(aborted, { written: false, skippedReason: "aborted" });
+    assert.equal(calls.writeSealedMemory.length, 0);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("sessionExperience config: default off, opt-in parse, unknown keys fail closed, conservative pins off", () => {
+  assert.deepEqual(SESSION_EXPERIENCE_CONFIG_DEFAULTS, { enabled: false });
+  assert.deepEqual(parseSessionExperienceConfig(undefined), { enabled: false });
+  assert.deepEqual(parseSessionExperienceConfig({}), { enabled: false });
+  assert.deepEqual(parseSessionExperienceConfig({ enabled: true }), { enabled: true });
+  assert.throws(() => parseSessionExperienceConfig("yes"), /sessionExperience must be an object/);
+  assert.throws(
+    () => parseSessionExperienceConfig({ enabled: true, maxEpisodes: 2 }),
+    /unknown key "maxEpisodes"/,
+  );
+  const memoryDir = "/tmp/remnic-sx-preset";
+  assert.equal(parseConfig({ memoryDir }).sessionExperience.enabled, false);
+  assert.equal(
+    parseConfig({ memoryDir, memoryOsPreset: "conservative" }).sessionExperience.enabled,
+    false,
+    "the conservative preset pins session-end experience extraction off",
+  );
+  assert.equal(
+    parseConfig({ memoryDir, memoryOsPreset: "balanced", sessionExperience: { enabled: true } })
+      .sessionExperience.enabled,
+    true,
+  );
+});

package/src/experience/session-experience.ts

@@ -0,0 +1,240 @@
+/**
+ * Session-end agent-experience extraction (issue #2979).
+ *
+ * At `session_end` the completed session's buffered turns are distilled —
+ * deterministically, no LLM — into at most ONE Situation/Approach/Reflect
+ * "experience episode" memory (agent-subject, category `procedure`,
+ * `pending_review`), mirroring OpenViking's experience-memory schema at the
+ * granularity Remnic's trust model allows: a machine-derived write that
+ * stays behind the existing sealed-envelope write path and never activates
+ * itself.
+ *
+ * Determinism: the episode is a pure function of the turn list — same
+ * transcript, same episode. Refusal/failure is signal, not a skip: a
+ * session whose terminal assistant turn records a failure gets a failure
+ * reflection.
+ *
+ * v1 heuristics (same tier as procedure-miner's `pseudoStepsFromCluster`):
+ * situation = first substantive user turn (task shape); approach = first
+ * sentences of the assistant turns; reflection = terminal outcome evidence.
+ */
+
+import { createHash } from "node:crypto";
+
+import { log } from "../logger.js";
+import type { BufferTurn, MemoryFile, MemoryStatus, PluginConfig } from "../types.js";
+import { composeSalvagedEnvelope } from "../salvage-envelope.js";
+import type { SealedMemoryEnvelope } from "../write-envelope.js";
+
+export type SessionExperienceOutcomeKind = "success" | "failure" | "inconclusive";
+
+/** The OpenViking Situation/Approach/Reflect classes, Remnic spelling. */
+export interface ExperienceEpisode {
+  /** Task shape: what the session was asked to do. */
+  situation: string;
+  /** What the agent tried, in order. */
+  approach: string;
+  /** Outcome and what to do differently. */
+  reflection: string;
+  outcomeKind: SessionExperienceOutcomeKind;
+}
+
+export type SessionExperienceSkippedReason =
+  | "session_experience_disabled"
+  | "aborted"
+  | "deadline_elapsed"
+  | "duplicate_session"
+  | "insufficient_signal";
+
+export type SessionExperienceRunResult =
+  | { written: true; episode: ExperienceEpisode; memoryId: string }
+  | { written: false; skippedReason: SessionExperienceSkippedReason };
+
+/** The subset of StorageManager the experience write needs (test-friendly). */
+export interface SessionExperienceStorage {
+  readAllMemories(): Promise<MemoryFile[]>;
+  writeSealedMemory(
+    envelope: SealedMemoryEnvelope,
+    extras?: { status?: MemoryStatus },
+  ): Promise<{ id?: string }>;
+}
+
+export interface SessionExperienceRunOptions {
+  turns: readonly BufferTurn[];
+  sessionKey: string;
+  config: PluginConfig;
+  storage: SessionExperienceStorage;
+  abortSignal?: AbortSignal;
+  /** Shared flush deadline (epoch ms); skipped when already elapsed. */
+  deadlineMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic derivation
+// ---------------------------------------------------------------------------
+
+const SITUATION_MAX_CHARS = 280;
+const SNIPPET_MAX_CHARS = 160;
+const APPROACH_MAX_SNIPPETS = 3;
+const MIN_SITUATION_CHARS = 16;
+
+/** Terminal-outcome markers, scanned over ASSISTANT turns only (last first). */
+const FAILURE_MARKER =
+  /\b(?:failed|failing|failure|cannot|can't|unable to|blocked|refused|refusal)\b/i;
+const SUCCESS_MARKER =
+  /\b(?:succeeded|verified|tests? pass(?:ed|ing)?|fixed|resolved|completed successfully|shipped)\b/i;
+
+function collapse(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function capAtWordBoundary(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const slice = text.slice(0, maxChars);
+  const lastSpace = slice.lastIndexOf(" ");
+  return `${(lastSpace > maxChars * 0.6 ? slice.slice(0, lastSpace) : slice).trim()}…`;
+}
+
+function firstSentence(text: string): string {
+  const match = collapse(text).match(/^[^.!?]*[.!?]/);
+  return collapse(match ? match[0] : text);
+}
+
+function sentenceContaining(text: string, marker: RegExp): string {
+  const flat = collapse(text);
+  for (const sentence of flat.split(/(?<=[.!?])\s+/)) {
+    if (marker.test(sentence)) return sentence;
+  }
+  return flat;
+}
+
+function classifyOutcome(assistantTurns: string[]): { outcomeKind: SessionExperienceOutcomeKind; evidence: string } {
+  for (let i = assistantTurns.length - 1; i >= 0; i -= 1) {
+    const turn = assistantTurns[i];
+    if (FAILURE_MARKER.test(turn)) {
+      return { outcomeKind: "failure", evidence: sentenceContaining(turn, FAILURE_MARKER) };
+    }
+    if (SUCCESS_MARKER.test(turn)) {
+      return { outcomeKind: "success", evidence: sentenceContaining(turn, SUCCESS_MARKER) };
+    }
+  }
+  return { outcomeKind: "inconclusive", evidence: "" };
+}
+
+function reflectionFor(outcomeKind: SessionExperienceOutcomeKind, evidence: string): string {
+  if (outcomeKind === "failure") {
+    return `The session failed: "${capAtWordBoundary(evidence, SNIPPET_MAX_CHARS)}". Change that step before retrying the same approach.`;
+  }
+  if (outcomeKind === "success") {
+    return `The session succeeded: "${capAtWordBoundary(evidence, SNIPPET_MAX_CHARS)}". The approach above worked for this situation.`;
+  }
+  return "No terminal outcome signal appears in the transcript; treat the approach above as unverified.";
+}
+
+/**
+ * Derive the single experience episode a completed session yields, or `null`
+ * when the transcript carries no learnable signal (no task, or no agent work).
+ */
+export function extractExperienceEpisode(turns: readonly BufferTurn[]): ExperienceEpisode | null {
+  const userTurns = turns.filter((turn) => turn.role === "user").map((turn) => collapse(turn.content)).filter(Boolean);
+  const situationSource = userTurns.find((content) => content.length >= MIN_SITUATION_CHARS);
+  if (situationSource === undefined) return null;
+
+  const assistantTurns = turns
+    .filter((turn) => turn.role === "assistant")
+    .map((turn) => collapse(turn.content))
+    .filter(Boolean);
+  if (assistantTurns.length === 0) return null;
+
+  const snippets: string[] = [];
+  for (const turn of assistantTurns) {
+    const sentence = firstSentence(turn);
+    if (sentence.length === 0 || snippets.includes(sentence)) continue;
+    snippets.push(capAtWordBoundary(sentence, SNIPPET_MAX_CHARS));
+    if (snippets.length >= APPROACH_MAX_SNIPPETS) break;
+  }
+  if (snippets.length === 0) return null;
+
+  const { outcomeKind, evidence } = classifyOutcome(assistantTurns);
+  return {
+    situation: capAtWordBoundary(situationSource, SITUATION_MAX_CHARS),
+    approach: snippets.join("; "),
+    reflection: reflectionFor(outcomeKind, evidence),
+    outcomeKind,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Gated write
+// ---------------------------------------------------------------------------
+
+const EXPERIENCE_SOURCE = "session-experience";
+
+function sessionKeyHash(sessionKey: string): string {
+  return createHash("sha256").update(sessionKey).digest("hex");
+}
+
+async function hasExistingExperience(
+  storage: SessionExperienceStorage,
+  hash: string,
+): Promise<boolean> {
+  const memories = await storage.readAllMemories();
+  return memories.some((m) => m.frontmatter.structuredAttributes?.experience_session_hash === hash);
+}
+
+/**
+ * Run session-end experience extraction for one session. With the gate off
+ * this touches NOTHING — no reads, no envelope, no write. On write the
+ * episode lands as one `pending_review` agent-subject `procedure` memory
+ * (trust-mode review; promotion is the operator's call), deduped per
+ * session key so a replayed session_end cannot double-write.
+ */
+export async function runSessionExperienceExtraction(
+  options: SessionExperienceRunOptions,
+): Promise<SessionExperienceRunResult> {
+  if (options.config.sessionExperience?.enabled !== true) {
+    return { written: false, skippedReason: "session_experience_disabled" };
+  }
+  if (options.abortSignal?.aborted === true) {
+    return { written: false, skippedReason: "aborted" };
+  }
+  if (typeof options.deadlineMs === "number" && Date.now() >= options.deadlineMs) {
+    return { written: false, skippedReason: "deadline_elapsed" };
+  }
+
+  const hash = sessionKeyHash(options.sessionKey);
+  if (await hasExistingExperience(options.storage, hash)) {
+    return { written: false, skippedReason: "duplicate_session" };
+  }
+
+  const episode = extractExperienceEpisode(options.turns);
+  if (episode === null) {
+    return { written: false, skippedReason: "insufficient_signal" };
+  }
+
+  // Machine-derived from buffered turns — salvage-mode envelope, warn-logged
+  // drops (issue #1989 PR4 convention for machine-generated writes).
+  const envelope = composeSalvagedEnvelope(
+    EXPERIENCE_SOURCE,
+    {
+      content: `Situation: ${episode.situation}\nApproach: ${episode.approach}\nReflection: ${episode.reflection}`,
+      category: "procedure",
+      subject: "agent",
+      confidence: 0.6,
+      tags: ["session-experience", `experience-${episode.outcomeKind}`],
+      structuredAttributes: {
+        experience_situation: episode.situation,
+        experience_approach: episode.approach,
+        experience_reflection: episode.reflection,
+        experience_outcome: episode.outcomeKind,
+        experience_session_hash: hash,
+      },
+    },
+    { source: EXPERIENCE_SOURCE },
+  );
+  const written = await options.storage.writeSealedMemory(envelope, { status: "pending_review" });
+  log.debug(
+    `${EXPERIENCE_SOURCE}: wrote episode for session hash ${hash.slice(0, 12)}… (outcome ${episode.outcomeKind})`,
+  );
+  return { written: true, episode, memoryId: typeof written.id === "string" ? written.id : "" };
+}

package/src/orchestration/generic-recall-paths.ts

@@ -10,6 +10,7 @@ import {
   isMeetingRecordPath,
 } from "./orchestrator-helpers.js";
 import { isJournalDayPath } from "../activity/journal.js";
+import { DIRECTORY_SIDECAR_BASENAME } from "../directory-sidecars.js";
 import { OKF_RESERVED_BASENAMES } from "../okf/type-mapping.js";
 
 
@@ -244,7 +245,10 @@ export function isGenericRecallExcludedPath(
   return (
     isSearchExcludedPath(filePath, policy, source) ||
     isTopLevelArchivePath(filePath, policy, source) ||
-    OKF_RESERVED_BASENAMES[path.basename(filePath)] === true
+    OKF_RESERVED_BASENAMES[path.basename(filePath)] === true ||
+    // Derived per-directory sidecars (#2977): recall-excluded like OKF index
+    // files, still searchable. Basename-only, the same accepted tradeoff.
+    path.basename(filePath) === DIRECTORY_SIDECAR_BASENAME
   );
 }
 

package/src/orchestration/session-context.ts

@@ -22,6 +22,7 @@ import { StorageManager } from "../index.js";
 import { LocalLlmClient } from "../local-llm.js";
 import { log } from "../logger.js";
 import { canWriteNamespace, defaultNamespaceForPrincipal, recallNamespacesForPrincipal, resolvePrincipal } from "../namespaces/principal.js";
+import { runSessionExperienceExtraction } from "../experience/session-experience.js";
 import { ExtractionDeadlineError } from "./extraction-run.js";
 import type { ExtractionRunResult } from "./extraction-run.js";
 import type { EntitySynthesisCoordinator } from "./entity-synthesis-coordinator.js";
@@ -527,6 +528,9 @@ export class SessionContextCoordinator {
           })
             .catch(reject);
         });
+        if (options.reason === "session_end" && this.deps.config.sessionExperience?.enabled === true) {
+          await this.extractSessionEndExperience(turnsForSession, sessionKey, options);
+        }
       } finally {
         if (
           retainedTurnsForOtherSessions.length > 0 &&
@@ -553,6 +557,52 @@ export class SessionContextCoordinator {
     }
   }
 
+  /**
+   * Session-end experience extraction (issue #2979): derive at most one
+   * Situation/Approach/Reflect episode from the drained session's turns.
+   * Best-effort by contract — a failure here must never fail the flush
+   * (the fact extraction already committed). Honors the shared abort signal
+   * and flush deadline; the write itself is gated, deduped per session, and
+   * lands as `pending_review` inside `runSessionExperienceExtraction`.
+   */
+  private async extractSessionEndExperience(
+    turns: BufferTurn[],
+    sessionKey: string,
+    options: SessionFlushOptions,
+  ): Promise<void> {
+    try {
+      const explicitNamespace =
+        typeof options.writeNamespaceOverride === "string" && options.writeNamespaceOverride.trim().length > 0
+          ? options.writeNamespaceOverride.trim()
+          : undefined;
+      // Same precedence as the extraction write path: explicit override →
+      // scope-profile plan → principal + coding overlay.
+      const namespace =
+        explicitNamespace ??
+        options.scopeProfileWritePlan?.writeNamespace ??
+        this.deps.applyCodingNamespaceOverlay(
+          sessionKey,
+          defaultNamespaceForPrincipal(this.deps.resolvePrincipal(sessionKey), this.deps.config),
+        );
+      const storage = await this.deps.orchestratorSelf.getStorageForNamespace(namespace);
+      const result = await runSessionExperienceExtraction({
+        turns,
+        sessionKey,
+        config: this.deps.config,
+        storage,
+        abortSignal: options.abortSignal,
+        deadlineMs: options.extractionDeadlineMs,
+      });
+      if (result.written) {
+        log.info(`session-experience: recorded ${result.episode.outcomeKind} episode for session end`);
+      } else {
+        log.debug(`session-experience skipped: ${result.skippedReason}`);
+      }
+    } catch (error) {
+      log.warn(`session-experience extraction failed (non-fatal): ${error}`);
+    }
+  }
+
   /** Lazily construct the CorrectionService for passive capture. Stateless
    *  across requests (per #1580 design); cached for the orchestrator's life. */
   passiveCorrectionService(): CorrectionService {

package/src/recall-context-composition.test.ts

@@ -2,6 +2,9 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import {
+  boundRecallContextComposition,
+  composeMissingMemoryContext,
+  composeRecallContext,
   formatCuriosityFooter,
   renderMemoryContextPrompt,
   selectCuriosityQuestion,
@@ -88,3 +91,66 @@ test("renderMemoryContextPrompt caps context before its footer deterministically
   assert.ok(rendered);
   assert.equal(rendered.body, "ab\n\n---\n\nfooter");
 });
+
+test("#2972 healthy recall carries no degradation marker", () => {
+  const composition = boundRecallContextComposition({
+    context: "A remembered deployment decision.",
+    maxChars: 512,
+  });
+
+  assert.equal("degradation" in composition, false);
+  assert.ok(!JSON.stringify(composition).includes("degradation"));
+});
+
+test("#2972 budget-clipped context is marked degraded, not silently cut", () => {
+  const composition = boundRecallContextComposition({
+    context: "x".repeat(100),
+    maxChars: 20,
+  });
+
+  assert.equal(composition.degradation?.state, "degraded");
+  assert.equal(composition.degradation?.reason, "budget-clipped");
+  assert.equal(composition.degradation?.budget?.fullChars, 100);
+  assert.ok(
+    (composition.degradation?.budget?.deliveredChars ?? 0) <
+      (composition.degradation?.budget?.fullChars ?? 0),
+  );
+});
+
+test("#2972 a fitting compact context is preferred over clipping the tail", () => {
+  const composition = boundRecallContextComposition({
+    context: "full-form entry one\n\nfull-form entry two",
+    compactContext: "entry one\nentry two",
+    maxChars: 30,
+  });
+
+  assert.equal(composition.context, "entry one\nentry two");
+  assert.equal(composition.degradation?.state, "degraded");
+  assert.equal(composition.degradation?.reason, "budget-compacted");
+  assert.equal(composition.degradation?.budget?.deliveredChars, 19);
+});
+
+test("#2972 a compact form that is not shallower than the full context is ignored", () => {
+  const composition = boundRecallContextComposition({
+    context: "x".repeat(50),
+    compactContext: "y".repeat(60),
+    maxChars: 10,
+  });
+
+  assert.equal(composition.degradation?.reason, "budget-clipped");
+});
+
+test("#2972 backend failure yields an explicit missing note, never an empty string", () => {
+  const composition = composeMissingMemoryContext({ detail: "backend_unavailable" });
+  const body = composeRecallContext(composition);
+
+  assert.ok(body.length > 0);
+  assert.match(body, /memory context unavailable/i);
+  assert.equal(composition.degradation?.state, "missing");
+  assert.equal(composition.degradation?.reason, "backend-unavailable");
+  assert.equal(composition.degradation?.detail, "backend_unavailable");
+
+  const rendered = renderMemoryContextPrompt({ ...composition, maxChars: 512 });
+  assert.ok(rendered);
+  assert.match(rendered.body, /memory context unavailable/i);
+});