@remnic/core 9.69.48 → 9.69.49

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

@@ -0,0 +1,51 @@
+/**
+ * Session-end experience extraction config (issue #2979) — the
+ * `sessionExperience` block.
+ *
+ * Parsed like `recallNavigation`: shape-validated, fail-closed on unknown
+ * keys, no silent clamping. Defaults OFF (a machine-generated memory write
+ * from the completed session must be an explicit operator opt-in); the
+ * `conservative` preset pins `enabled: false`.
+ */
+
+import { coerceBool } from "../connectors/coerce.js";
+
+export interface SessionExperienceConfig {
+  /**
+   * Master switch for session-end Situation/Approach/Reflection episode
+   * extraction. Default false.
+   */
+  enabled: boolean;
+}
+
+export const SESSION_EXPERIENCE_CONFIG_DEFAULTS: SessionExperienceConfig = {
+  enabled: false,
+};
+
+function parseFlag(src: Record<string, unknown>, key: string, fallback: boolean): boolean {
+  const value = src[key];
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceBool(value);
+  if (coerced === undefined) {
+    throw new Error(
+      `sessionExperience.${key} must be a boolean (or "true"/"false"/"1"/"0"); got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+export function parseSessionExperienceConfig(raw: unknown): SessionExperienceConfig {
+  if (raw === undefined || raw === null) return { ...SESSION_EXPERIENCE_CONFIG_DEFAULTS };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`sessionExperience must be an object; got ${JSON.stringify(raw)}`);
+  }
+  const src = raw as Record<string, unknown>;
+  const { enabled: _enabled, ...unknown } = src;
+  const unknownKey = Object.keys(unknown)[0];
+  if (unknownKey !== undefined) {
+    throw new Error(`sessionExperience contains unknown key ${JSON.stringify(unknownKey)}`);
+  }
+  return {
+    enabled: parseFlag(src, "enabled", SESSION_EXPERIENCE_CONFIG_DEFAULTS.enabled),
+  };
+}

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

@@ -0,0 +1,139 @@
+/**
+ * Session-end experience extraction through the real flush lifecycle
+ * (issue #2979): `flushSession(reason: "session_end")` drains the buffer
+ * and then derives at most one agent-experience episode; `before_reset`
+ * must not write one; gate off must write nothing anywhere.
+ */
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+import { Orchestrator } from "../orchestrator.js";
+import {
+  cleanupDir,
+  makeHarmonicLifecycleConfig,
+  markdownFilesUnder,
+  mkTempMemoryDir,
+  singleFactResult,
+  stubExtraction,
+} from "../testing/orchestrator-lite.js";
+
+async function sessionEndMemories(memoryDir: string): Promise<string[]> {
+  const matches: string[] = [];
+  for (const file of await markdownFilesUnder(`${memoryDir}/procedures`)) {
+    if ((await readFile(file, "utf8")).includes("Reflection: ")) matches.push(file);
+  }
+  return matches;
+}
+
+async function withOrchestrator(
+  label: string,
+  overrides: Record<string, unknown>,
+  run: (orchestrator: Orchestrator, memoryDir: string) => Promise<void>,
+): Promise<void> {
+  const memoryDir = await mkTempMemoryDir(label);
+  let orchestrator: Orchestrator | undefined;
+  try {
+    orchestrator = new Orchestrator(makeHarmonicLifecycleConfig(memoryDir, overrides));
+    stubExtraction(orchestrator, (turns) => singleFactResult("The harmonic probe fact persists."));
+    await run(orchestrator, memoryDir);
+  } finally {
+    await orchestrator?.destroy().catch(() => undefined);
+    await cleanupDir(memoryDir);
+  }
+}
+
+const SESSION = "session-end-experience";
+
+const SUCCESS_TURNS: Array<[role: "user" | "assistant", content: string]> = [
+  ["user", "Fix the flaky payments integration test that times out after thirty seconds."],
+  ["assistant", "I will reproduce the timeout and inspect the payments test setup."],
+  ["assistant", "Added the missing await to the setup call. Verified: the payments test passes now."],
+];
+
+test("session_end flush writes exactly one pending_review agent-experience episode", async () => {
+  await withOrchestrator(
+    "sx-e2e-on",
+    { sessionExperience: { enabled: true } },
+    async (orchestrator, memoryDir) => {
+      for (const [role, content] of SUCCESS_TURNS) {
+        await orchestrator.processTurn(role, content, SESSION);
+      }
+      await orchestrator.flushSession(SESSION, { reason: "session_end" });
+      const experiences = await sessionEndMemories(memoryDir);
+      assert.equal(experiences.length, 1, "one session = at most one experience episode");
+      const body = await readFile(experiences[0], "utf8");
+      assert.match(body, /Situation: Fix the flaky payments integration test/);
+      assert.match(body, /Approach: /);
+      assert.match(body, /Reflection: /);
+      assert.match(body, /status: pending_review/);
+      assert.match(body, /subject: agent/);
+      assert.match(body, /category: procedure/);
+      assert.match(body, /experience_session_hash/);
+      // A second session_end drain sees an empty buffer and must not duplicate.
+      await orchestrator.flushSession(SESSION, { reason: "session_end" });
+      assert.equal((await sessionEndMemories(memoryDir)).length, 1, "replay must not duplicate");
+    },
+  );
+});
+
+test("a failed session_end records the failure reflection", async () => {
+  await withOrchestrator(
+    "sx-e2e-fail",
+    { sessionExperience: { enabled: true } },
+    async (orchestrator, memoryDir) => {
+      await orchestrator.processTurn(
+        "user",
+        "Migrate the billing export job to the new queue library before the release cut.",
+        SESSION,
+      );
+      await orchestrator.processTurn(
+        "assistant",
+        "The migration failed: the new queue library cannot serialize the billing payload format.",
+        SESSION,
+      );
+      await orchestrator.flushSession(SESSION, { reason: "session_end" });
+      const experiences = await sessionEndMemories(memoryDir);
+      assert.equal(experiences.length, 1);
+      const body = await readFile(experiences[0], "utf8");
+      assert.match(body, /experience_outcome: failure|experience_outcome=failure/);
+      assert.match(body, /fail/i);
+    },
+  );
+});
+
+test("gate off (default): a session_end flush writes no experience anywhere", async () => {
+  await withOrchestrator("sx-e2e-off", {}, async (orchestrator, memoryDir) => {
+    for (const [role, content] of SUCCESS_TURNS) {
+      await orchestrator.processTurn(role, content, SESSION);
+    }
+    await orchestrator.flushSession(SESSION, { reason: "session_end" });
+    assert.equal((await sessionEndMemories(memoryDir)).length, 0, "gate off must write nothing");
+    for (const file of await markdownFilesUnder(memoryDir)) {
+      const body = await readFile(file, "utf8");
+      assert.doesNotMatch(
+        body,
+        /Reflection: /,
+        `no experience body may appear anywhere while gated off (saw ${file})`,
+      );
+    }
+  });
+});
+
+test("before_reset drains the buffer but writes no experience episode", async () => {
+  await withOrchestrator(
+    "sx-e2e-reset",
+    { sessionExperience: { enabled: true } },
+    async (orchestrator, memoryDir) => {
+      for (const [role, content] of SUCCESS_TURNS) {
+        await orchestrator.processTurn(role, content, SESSION);
+      }
+      await orchestrator.flushSession(SESSION, { reason: "before_reset" });
+      assert.equal(
+        (await sessionEndMemories(memoryDir)).length,
+        0,
+        "experiences are session_end-only in v1",
+      );
+    },
+  );
+});

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