@nklisch/pi-enhanced 0.4.4 → 0.5.0

package/node_modules/@nklisch/pi-astral-pocket/src/store.ts

@@ -1,65 +1,43 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-
 import { resolveProjectIdentity } from "./scope.js";
-
-const PINNED_START = "<!-- pocket:pinned:start -->";
-const PINNED_END = "<!-- pocket:pinned:end -->";
-const DIGEST_START = "<!-- pocket:digest:start -->";
-const DIGEST_END = "<!-- pocket:digest:end -->";
-const RECENT_NOTES_CAP = 20;
-const NOTE_EXCERPT = 320;
-const FULL_NOTE_EXCERPT = 4_000;
-const DIGEST_NOTE_CAP = 200;
-const DIGEST_NOTE_BYTES = 2_000;
-
-export function defaultAgentDir(): string {
-  return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
-}
-
-export function pocketRoot(agentDir: string = defaultAgentDir()): string {
-  return join(agentDir, "astral-pocket");
-}
-
-export function notesDir(root: string): string {
-  return join(root, "notes");
-}
-
-function atomicWrite(path: string, contents: string): void {
-  const temporary = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
-  writeFileSync(temporary, contents, "utf8");
-  renameSync(temporary, path);
-}
-
-export function ensureLayout(root: string): void {
-  mkdirSync(notesDir(root), { recursive: true });
-  const registry = join(root, "POCKET.md");
-  if (!existsSync(registry)) atomicWrite(registry, renderRegistry([]));
-  if (!existsSync(join(root, "SUMMARY.md"))) atomicWrite(join(root, "SUMMARY.md"), renderSummary(root, []));
-}
-
+import { isExcludedSession, type SessionExclusion } from "./sessions.js";
+
+export const LEARNING_VERSION = 1;
+export const EXTRACTION_POLICY_VERSION = "repository-learning-1";
+export const MAX_TITLE_CHARS = 160;
+export const MAX_BODY_CHARS = 1_600;
+export const MAX_EVIDENCE_CHARS = 500;
+export type LearningKind = "navigation" | "pitfall";
 export type NoteScope = "project" | "global";
-
 export interface NoteInput {
+  kind: LearningKind;
   title: string;
   body: string;
+  evidence?: string;
   keywords?: string[];
-  project?: string;
+  project: string;
   projectId?: string;
-  scope?: NoteScope;
+  scope?: "project";
   source?: "agent" | "distilled";
 }
-
-export interface GeneratedNoteInput extends NoteInput {
+export interface GeneratedSource {
   sessionId: string;
   sourcePath: string;
   sourceUpdatedAt: string;
   sourceSize: number;
   sourceRevision: string;
 }
-
 interface StoredNote {
   fileName: string;
   title: string;
@@ -71,219 +49,429 @@ interface StoredNote {
   source: string;
   created: string;
   updated: string;
+  kind: string;
+  version: string;
+  retired: boolean;
+  evidence: string;
+  policy: string;
+  sessionId: string;
+  sourcePath: string;
 }
-
-function slugify(text: string): string {
-  const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
-  return slug || "note";
+export function defaultAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
 }
-
-function stamp(date: Date): string {
-  return date.toISOString().replace(/[:.]/g, "-");
+export function pocketRoot(agentDir = defaultAgentDir()): string {
+  return join(agentDir, "astral-pocket");
 }
-
-function extractSection(markdown: string, start: string, end: string): string | null {
-  const i = markdown.indexOf(start);
-  const j = markdown.indexOf(end);
-  if (i === -1 || j === -1 || j < i) return null;
-  return markdown.slice(i + start.length, j).trim();
+export function notesDir(root: string): string {
+  return join(root, "notes");
 }
-
-function field(text: string, name: string): string {
-  const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] ?? "";
-  return frontmatter.match(new RegExp(`^${name}: (.*)$`, "m"))?.[1]?.trim() ?? "";
+function atomicWrite(path: string, contents: string): void {
+  const temporary = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+  writeFileSync(temporary, contents, "utf8");
+  renameSync(temporary, path);
 }
-
-function noteTimestamp(note: StoredNote): number {
-  const parsed = Date.parse(note.updated || note.created);
-  return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
+export function ensureLayout(root: string): void {
+  mkdirSync(notesDir(root), { recursive: true });
+  if (!existsSync(join(root, "POCKET.md"))) rebuildDerivedStore(root);
 }
-
-function compareNotesByTime(a: StoredNote, b: StoredNote): number {
-  const aTime = noteTimestamp(a);
-  const bTime = noteTimestamp(b);
-  if (aTime !== bTime) return aTime < bTime ? -1 : 1;
-  // Prefer deliberate and legacy notes at a time tie so a batch of generated
-  // notes cannot crowd them out solely because session hashes sort later.
-  const manualRank = Number(a.source !== "distilled") - Number(b.source !== "distilled");
-  return manualRank || a.fileName.localeCompare(b.fileName);
+function field(text: string, name: string): string {
+  const frontmatter =
+    text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] ?? "";
+  return (
+    frontmatter.match(new RegExp(`^${name}: (.*)$`, "m"))?.[1]?.trim() ?? ""
+  );
 }
-
 function readStoredNotes(root: string): StoredNote[] {
   if (!existsSync(notesDir(root))) return [];
   const notes: StoredNote[] = [];
-  for (const fileName of readdirSync(notesDir(root)).filter((name) => name.endsWith(".md"))) {
+  for (const fileName of readdirSync(notesDir(root)).filter((name) =>
+    name.endsWith(".md"),
+  )) {
     try {
       const text = readFileSync(join(notesDir(root), fileName), "utf8");
-      const heading = text.match(/^# (.+)$/m)?.[1] ?? fileName;
-      const headingAt = text.search(/^# .+$/m);
+      const content = text
+        .replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/, "")
+        .trim();
       const project = field(text, "project");
       const declaredScope = field(text, "scope");
-      const scope: NoteScope | "unknown" = declaredScope === "global"
-        ? "global"
-        : declaredScope === "project" || (declaredScope === "" && project !== "" && project !== "unknown")
-          ? "project"
-          : "unknown";
+      const scope =
+        declaredScope === "global"
+          ? "global"
+          : declaredScope === "project" ||
+              (!declaredScope && project && project !== "unknown")
+            ? "project"
+            : "unknown";
       notes.push({
         fileName,
-        title: heading,
         text,
-        body: headingAt >= 0 ? text.slice(headingAt).replace(/^# .+\n+/, "").trim() : text.trim(),
+        title: content.match(/^# (.+)$/m)?.[1] ?? fileName,
+        body: content.replace(/^# .+\r?\n+/, "").trim(),
         project,
-        projectId: field(text, "project_id") || (scope === "project" && project !== "" && project !== "unknown" ? resolveProjectIdentity(project) : ""),
+        projectId:
+          field(text, "project_id") ||
+          (scope === "project" && project
+            ? resolveProjectIdentity(project)
+            : ""),
         scope,
         source: field(text, "source") || "legacy",
         created: field(text, "created"),
-        updated: field(text, "updated") || field(text, "source_updated_at") || field(text, "created"),
+        updated: field(text, "updated") || field(text, "created"),
+        kind: field(text, "kind"),
+        version: field(text, "learning_version"),
+        retired: field(text, "retired") === "true",
+        evidence: field(text, "evidence"),
+        policy: field(text, "extraction_policy"),
+        sessionId: field(text, "session_id"),
+        sourcePath: field(text, "source_path"),
       });
     } catch {
-      // One unreadable note must not hide the remaining canonical note files.
+      /* One unreadable note must not hide the remaining canonical files. */
     }
   }
-  return notes.sort(compareNotesByTime);
+  return notes.sort(
+    (a, b) =>
+      b.updated.localeCompare(a.updated) ||
+      a.fileName.localeCompare(b.fileName),
+  );
+}
+
+/** A narrow rejection of obvious preference text, not a semantic classifier.
+ * The explicit contract and extraction prompt carry the broader exclusions. */
+function clearPreference(text: string): boolean {
+  return /\b(?:user|maintainer|author)\s+(?:explicitly\s+)?(?:prefers?|wants?|likes?)\b|\buser preferences?\b|\bprefer (?:concise|terse|verbose)\b/i.test(
+    text,
+  );
+}
+export function validateLearning(
+  input: Pick<NoteInput, "kind" | "title" | "body" | "evidence" | "keywords">,
+): void {
+  if (input.kind !== "navigation" && input.kind !== "pitfall")
+    throw new Error(
+      "Learning kind must be navigation or pitfall, never preferences or policy",
+    );
+  for (const [label, value, cap] of [
+    ["title", input.title, MAX_TITLE_CHARS],
+    ["body", input.body, MAX_BODY_CHARS],
+  ] as const) {
+    if (typeof value !== "string" || !value.trim() || value.length > cap)
+      throw new Error(`${label} must contain 1-${cap} characters`);
+  }
+  if (/[\r\n]/.test(input.title))
+    throw new Error("Title must be a single line");
+  if (
+    input.evidence !== undefined &&
+    (typeof input.evidence !== "string" ||
+      input.evidence.length > MAX_EVIDENCE_CHARS ||
+      /[\r\n]/.test(input.evidence))
+  )
+    throw new Error(
+      "Evidence must be a single-line pointer of at most 500 characters",
+    );
+  if (
+    input.keywords &&
+    (input.keywords.length > 5 ||
+      input.keywords.some(
+        (v) => typeof v !== "string" || v.length > 64 || /[\r\n]/.test(v),
+      ))
+  )
+    throw new Error(
+      "Use at most 5 single-line keywords of at most 64 characters",
+    );
+  if (clearPreference(`${input.title}\n${input.body}`))
+    throw new Error(
+      "Pocket stores repository navigation and pitfalls, not user preferences",
+    );
+}
+function eligible(note: StoredNote): boolean {
+  if (
+    note.retired ||
+    note.scope !== "project" ||
+    !note.projectId ||
+    note.version !== String(LEARNING_VERSION)
+  )
+    return false;
+  if (note.source === "distilled" && note.policy !== EXTRACTION_POLICY_VERSION)
+    return false;
+  try {
+    validateLearning({ ...note, kind: note.kind as LearningKind });
+    return true;
+  } catch {
+    return false;
+  }
 }
-
-function noteMarkdown(input: NoteInput, metadata: string[], created: Date, updated: Date = created): string {
+function noteMarkdown(
+  input: NoteInput,
+  metadata: string[],
+  created: string,
+  updated: string,
+): string {
   return [
     "---",
-    `created: ${created.toISOString()}`,
-    `updated: ${updated.toISOString()}`,
-    `project: ${input.project ?? "unknown"}`,
-    `project_id: ${input.projectId ?? ""}`,
-    `scope: ${input.scope ?? "project"}`,
+    `learning_version: ${LEARNING_VERSION}`,
+    `kind: ${input.kind}`,
+    "retired: false",
+    `created: ${created}`,
+    `updated: ${updated}`,
+    `project: ${input.project}`,
+    `project_id: ${input.projectId ?? resolveProjectIdentity(input.project)}`,
+    "scope: project",
     `keywords: [${(input.keywords ?? []).join(", ")}]`,
     `source: ${input.source ?? "agent"}`,
+    ...(input.evidence ? [`evidence: ${input.evidence}`] : []),
     ...metadata,
     "---",
     "",
-    `# ${input.title}`,
+    `# ${input.title.trim()}`,
     "",
     input.body.trim(),
     "",
   ].join("\n");
 }
-
-function uniqueManualFile(root: string, input: NoteInput, now: Date): string {
-  const base = `${stamp(now)}-${slugify(input.title)}`;
-  let fileName = `${base}.md`;
-  let suffix = 2;
-  while (existsSync(join(notesDir(root), fileName))) fileName = `${base}-${suffix++}.md`;
-  return fileName;
-}
-
-/** Write one deliberate note. Call inside the POCKET.md mutation queue. */
-export function writeNote(root: string, input: NoteInput, now: Date = new Date()): string {
-  ensureLayout(root);
-  const fileName = uniqueManualFile(root, input, now);
-  atomicWrite(join(notesDir(root), fileName), noteMarkdown(input, [], now));
+function validateNote(input: NoteInput): void {
+  validateLearning(input);
+  if (input.scope !== undefined && input.scope !== "project")
+    throw new Error("New notes are project-only");
+  if (
+    !input.project ||
+    /[\r\n]/.test(input.project) ||
+    /[\r\n]/.test(input.projectId ?? "")
+  )
+    throw new Error("A single-line repository identity is required");
+}
+/** Mutations accept canonical filenames, never arbitrary paths supplied by a tool. */
+function ownedNote(
+  root: string,
+  fileName: string,
+  projectId: string,
+): StoredNote {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*\.md$/.test(fileName))
+    throw new Error("Use a note filename, not a path");
+  const note = readStoredNotes(root).find((n) => n.fileName === fileName);
+  if (!note || note.scope !== "project" || note.projectId !== projectId)
+    throw new Error("Note does not belong to the current repository");
+  return note;
+}
+export function retireNote(
+  root: string,
+  fileName: string,
+  projectId: string,
+  now = new Date(),
+): void {
+  const note = ownedNote(root, fileName, projectId);
+  const frontmatter = note.text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!frontmatter) throw new Error("Note has no editable metadata");
+  const metadata = frontmatter[1]
+    .split(/\r?\n/)
+    .filter((line) => !/^(retired|updated): /.test(line));
+  const text = [
+    "---",
+    "retired: true",
+    `updated: ${now.toISOString()}`,
+    ...metadata,
+    "---",
+    note.text.slice(frontmatter[0].length),
+  ].join("\n");
+  atomicWrite(join(notesDir(root), fileName), text);
   rebuildDerivedStore(root);
-  return fileName;
 }
-
-export function generatedNoteFile(sessionId: string): string {
-  const identity = createHash("sha256").update(sessionId).digest("hex").slice(0, 24);
-  return `session-${identity}.md`;
+export interface NoteMutation {
+  replace?: string;
+  supersedes?: string[];
 }
-
-/** Replace the one generated note owned by a session revision. */
-export function writeGeneratedNote(root: string, input: GeneratedNoteInput, now: Date = new Date()): string {
+/** Call inside the POCKET.md mutation queue. Manual replacement never edits session-owned files. */
+export function writeNote(
+  root: string,
+  input: NoteInput,
+  now = new Date(),
+  mutation: NoteMutation = {},
+): string {
+  validateNote(input);
   ensureLayout(root);
-  const fileName = generatedNoteFile(input.sessionId);
-  const existingPath = join(notesDir(root), fileName);
-  let created = now;
-  if (existsSync(existingPath)) {
-    const previousCreated = field(readFileSync(existingPath, "utf8"), "created");
-    if (previousCreated && !Number.isNaN(Date.parse(previousCreated))) created = new Date(previousCreated);
-  }
-  atomicWrite(existingPath, noteMarkdown(input, [
-    `session_id: ${input.sessionId}`,
-    `source_path: ${input.sourcePath}`,
-    `source_updated_at: ${input.sourceUpdatedAt}`,
-    `source_size: ${input.sourceSize}`,
-    `source_revision: ${input.sourceRevision}`,
-  ], created, now));
+  const projectId = input.projectId ?? resolveProjectIdentity(input.project);
+  const previous = mutation.replace
+    ? ownedNote(root, mutation.replace, projectId)
+    : undefined;
+  if (previous?.source === "distilled")
+    throw new Error(
+      "Retire generated notes or supersede them with a manual note instead",
+    );
+  for (const file of mutation.supersedes ?? [])
+    ownedNote(root, file, projectId);
+  const slug = input.title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .slice(0, 48);
+  const fileName =
+    previous?.fileName ??
+    `${now.toISOString().replace(/[:.]/g, "-")}-${slug}-${Math.random().toString(16).slice(2, 8)}.md`;
+  atomicWrite(
+    join(notesDir(root), fileName),
+    noteMarkdown(
+      { ...input, source: "agent" },
+      [],
+      previous?.created || now.toISOString(),
+      now.toISOString(),
+    ),
+  );
+  for (const file of mutation.supersedes ?? [])
+    if (file !== fileName) retireNote(root, file, projectId, now);
   rebuildDerivedStore(root);
   return fileName;
 }
-
-export function removeGeneratedNote(root: string, sessionId: string): boolean {
-  const path = join(notesDir(root), generatedNoteFile(sessionId));
-  if (!existsSync(path)) return false;
-  rmSync(path);
+export function generatedNoteFile(sessionId: string, index?: number): string {
+  const identity = createHash("sha256")
+    .update(sessionId)
+    .digest("hex")
+    .slice(0, 24);
+  return `session-${identity}${index === undefined ? "" : `-${index + 1}`}.md`;
+}
+/** Replace the bounded set owned by this session; retain retirement tombstones so
+ * re-extraction cannot resurrect a learning deliberately removed by the agent. */
+export function replaceGeneratedNotes(
+  root: string,
+  inputs: NoteInput[],
+  source: GeneratedSource,
+  now = new Date(),
+): string[] {
+  inputs.forEach(validateNote);
+  ensureLayout(root);
+  const previous = readStoredNotes(root).filter(
+    (n) => n.source === "distilled" && n.sessionId === source.sessionId,
+  );
+  if (previous.some((note) => note.retired))
+    return previous
+      .filter((note) => !note.retired)
+      .map((note) => note.fileName);
+  const files: string[] = [];
+  inputs.forEach((input, index) => {
+    const fileName = generatedNoteFile(source.sessionId, index);
+    const old = previous.find((n) => n.fileName === fileName);
+    atomicWrite(
+      join(notesDir(root), fileName),
+      noteMarkdown(
+        { ...input, source: "distilled" },
+        [
+          `extraction_policy: ${EXTRACTION_POLICY_VERSION}`,
+          `session_id: ${source.sessionId}`,
+          `source_path: ${source.sourcePath}`,
+          `source_updated_at: ${source.sourceUpdatedAt}`,
+          `source_size: ${source.sourceSize}`,
+          `source_revision: ${source.sourceRevision}`,
+        ],
+        old?.created || now.toISOString(),
+        now.toISOString(),
+      ),
+    );
+    files.push(fileName);
+  });
+  for (const note of previous)
+    if (!note.retired && !files.includes(note.fileName))
+      rmSync(join(notesDir(root), note.fileName));
+  // Only retire a legacy generated file when its provenance confirms ownership;
+  // a matching filename alone must never delete a manually authored note.
+  const legacyFile = generatedNoteFile(source.sessionId);
+  const legacy = readStoredNotes(root).find(
+    (note) => note.fileName === legacyFile,
+  );
+  if (legacy?.source === "distilled" && !legacy.retired)
+    rmSync(join(notesDir(root), legacyFile));
   rebuildDerivedStore(root);
-  return true;
+  return files;
 }
-
 function registryLine(note: StoredNote): string {
-  const project = note.scope === "global"
-    ? "global"
-    : (note.project.split("/").filter(Boolean).pop() ?? note.project) || "unknown";
-  const date = (note.updated || note.created).slice(0, 10) || "unknown-date";
-  return `- [${note.title}](notes/${note.fileName}) — ${note.scope} — ${project} — ${date}`;
+  return `- [${note.title}](notes/${note.fileName}) — ${note.scope} — ${note.retired ? "retired" : eligible(note) ? note.kind : "historical/unclassified"} — ${note.updated || note.created}`;
 }
-
-function renderRegistry(notes: StoredNote[]): string {
-  return [
-    "# Astral Pocket Registry",
-    "",
-    "Derived from the canonical Markdown files in `notes/`. Search this first.",
-    "",
-    ...notes.map(registryLine),
-    "",
-  ].join("\n");
+export function rebuildDerivedStore(root: string): void {
+  atomicWrite(
+    join(root, "POCKET.md"),
+    [
+      "# Astral Pocket Registry",
+      "",
+      "Derived from canonical notes; historical entries are not active learning.",
+      "",
+      ...readStoredNotes(root).map(registryLine),
+      "",
+    ].join("\n"),
+  );
 }
-
 export function countNotes(root: string): number {
   return readStoredNotes(root).length;
 }
-
-export function readRegistryLines(root: string): string[] {
-  const registry = join(root, "POCKET.md");
-  if (!existsSync(registry)) return [];
-  return readFileSync(registry, "utf8").split("\n").filter((line) => line.startsWith("- ["));
-}
-
-/** Rebuildable indexes are rendered from note files, never treated as note authority. */
-export function rebuildDerivedStore(root: string): void {
-  const notes = readStoredNotes(root);
-  atomicWrite(join(root, "POCKET.md"), renderRegistry(notes));
-  atomicWrite(join(root, "SUMMARY.md"), renderSummary(root, notes.map(registryLine)));
-}
-
-export const rerenderSummary = rebuildDerivedStore;
-
-function renderSummary(root: string, registryLines: string[]): string {
-  const summaryPath = join(root, "SUMMARY.md");
-  const existing = existsSync(summaryPath) ? readFileSync(summaryPath, "utf8") : "";
-  const pinned = extractSection(existing, PINNED_START, PINNED_END) ?? "";
-  const digest = extractSection(existing, DIGEST_START, DIGEST_END) ??
-    "_No digest yet. It is filled in by the distiller pass; until then, rely on Recent notes and search POCKET.md._";
-  const recent = registryLines.slice(-RECENT_NOTES_CAP);
+/** Source-level exclusion deliberately trades later automatic discoveries for
+ * predictable retirement: a model can paraphrase both a title and its body. */
+export function retiredSessionIds(
+  root: string,
+  projectId?: string,
+): Set<string> {
+  return new Set(
+    readStoredNotes(root)
+      .filter(
+        (n) =>
+          n.retired &&
+          n.source === "distilled" &&
+          n.sessionId &&
+          (projectId === undefined || n.projectId === projectId),
+      )
+      .map((n) => n.sessionId),
+  );
+}
+function card(note: StoredNote): string {
   return [
-    "# Astral Pocket Summary", "", PINNED_START, pinned, PINNED_END, "",
-    "## Durable digest", "", DIGEST_START, digest, DIGEST_END, "",
-    "## Recent notes", "", ...(recent.length > 0 ? recent : ["_No notes yet._"]), "",
+    `### ${note.title}`,
+    `${(note.updated || note.created).slice(0, 10)} · ${note.kind} · [source](notes/${note.fileName})`,
+    note.body,
+    ...(note.evidence ? [`Evidence: ${note.evidence}`] : []),
   ].join("\n");
 }
-
-export function updateDigest(root: string, digest: string): boolean {
-  const summaryPath = join(root, "SUMMARY.md");
-  if (!existsSync(summaryPath)) return false;
-  const existing = readFileSync(summaryPath, "utf8");
-  const i = existing.indexOf(DIGEST_START);
-  const j = existing.indexOf(DIGEST_END);
-  if (i === -1 || j === -1 || j < i) return false;
-  atomicWrite(summaryPath, `${existing.slice(0, i + DIGEST_START.length)}\n${digest.trim()}\n${existing.slice(j)}`);
-  return true;
-}
-
-export function readSummaryCapped(root: string, capBytes = 12_000): string {
-  const summaryPath = join(root, "SUMMARY.md");
-  if (!existsSync(summaryPath)) return "";
-  const text = readFileSync(summaryPath, "utf8");
-  return text.length <= capBytes ? text : `${text.slice(0, capBytes)}\n\n_(summary truncated; search POCKET.md for older material)_`;
+/** Deterministic complete cards. Consider every eligible source; manual learning
+ * wins over automatic extraction, with kind interleaving to retain navigation. */
+export function readScopedSummary(
+  root: string,
+  projectId: string,
+  capChars = 6_000,
+): string {
+  const notes = readStoredNotes(root).filter(
+    (n) => eligible(n) && n.projectId === projectId,
+  );
+  const ranked = notes.sort(
+    (a, b) =>
+      Number(a.source === "distilled") - Number(b.source === "distilled") ||
+      b.updated.localeCompare(a.updated) ||
+      a.fileName.localeCompare(b.fileName),
+  );
+  const ordered: StoredNote[] = [];
+  for (const automatic of [false, true]) {
+    const navigation = ranked.filter(
+      (n) =>
+        (n.source === "distilled") === automatic && n.kind === "navigation",
+    );
+    const pitfalls = ranked.filter(
+      (n) => (n.source === "distilled") === automatic && n.kind === "pitfall",
+    );
+    for (let i = 0; i < Math.max(navigation.length, pitfalls.length); i++) {
+      if (navigation[i]) ordered.push(navigation[i]);
+      if (pitfalls[i]) ordered.push(pitfalls[i]);
+    }
+  }
+  const heading = "# Current repository learning\n\n";
+  const footer = (skipped: number) =>
+    `\n\n${skipped} active learning(s) skipped. Use pocket_recall for relevant source excerpts.`;
+  if (heading.length + footer(notes.length).length > capChars) return "";
+  let text = heading;
+  let included = 0;
+  for (const note of ordered) {
+    const addition = `${included ? "\n\n" : ""}${card(note)}`;
+    if (
+      text.length + addition.length + footer(notes.length).length <=
+      capChars
+    ) {
+      text += addition;
+      included++;
+    }
+  }
+  return text + footer(notes.length - included);
 }
-
 export interface PocketSearchHit {
   noteFile: string;
   title: string;
@@ -293,9 +481,9 @@ export interface PocketSearchHit {
   source: string;
   scope: NoteScope | "unknown";
   date: string;
+  historical: boolean;
+  retired: boolean;
 }
-
-/** Search complete canonical note content, then truncate only the returned excerpt. */
 export function searchPocket(
   root: string,
   query: string,
@@ -303,125 +491,55 @@ export function searchPocket(
   limit: number,
   full = false,
   recallScope: "current" | "all" = "current",
+  includeHistory = false,
+  excludeSession?: SessionExclusion,
 ): PocketSearchHit[] {
   const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
-  if (terms.length === 0) return [];
-  const cap = full ? FULL_NOTE_EXCERPT : NOTE_EXCERPT;
-  const hits = readStoredNotes(root)
-    .filter((note) => recallScope === "all" || note.scope === "global" || (note.scope === "project" && note.projectId === currentProject))
-    .filter((note) => terms.every((term) => note.text.toLowerCase().includes(term))).map((note) => {
-    const lowerBody = note.body.toLowerCase();
-    const bodyMatches = terms.map((term) => lowerBody.indexOf(term)).filter((at) => at >= 0);
-    const at = bodyMatches.length > 0 ? Math.min(...bodyMatches) : 0;
-    const start = Math.max(0, at - Math.floor(cap / 4));
-    const excerpt = note.body.slice(start, start + cap).trim();
-    return {
-      noteFile: note.fileName,
-      title: note.title,
-      excerpt: excerpt.length < note.body.slice(start).trim().length ? `${excerpt}…` : excerpt,
-      project: note.project,
-      projectId: note.projectId,
-      source: note.source,
-      scope: note.scope,
-      date: note.updated || note.created,
-    };
-  });
-  hits.sort((a, b) => {
-    const projectRank = Number(b.projectId === currentProject) - Number(a.projectId === currentProject);
-    const globalRank = Number(b.scope === "global") - Number(a.scope === "global");
-    return projectRank || globalRank || b.date.localeCompare(a.date) || b.noteFile.localeCompare(a.noteFile);
-  });
-  return hits.slice(0, Math.max(1, limit));
-}
-
-export interface DigestSnapshot {
-  fingerprint: string;
-  promptSource: string;
-  noteCount: number;
-}
-
-export type DigestScope = { kind: "project"; projectId: string } | { kind: "global" };
-
-export function digestScopeKey(scope: DigestScope): string {
-  return scope.kind === "global"
-    ? "global"
-    : `project:${createHash("sha256").update(scope.projectId).digest("hex").slice(0, 24)}`;
-}
-
-function digestPath(root: string, scope: DigestScope): string {
-  return join(root, "digests", `${digestScopeKey(scope).replace(":", "-")}.md`);
-}
-
-export function scopedDigestExists(root: string, scope: DigestScope): boolean {
-  return existsSync(digestPath(root, scope));
-}
-
-function successfulDigestFingerprint(root: string, scope: DigestScope): string | undefined {
-  try {
-    const state = JSON.parse(readFileSync(join(root, "distilled.json"), "utf8")) as { digestFingerprints?: Record<string, unknown> };
-    const value = state.digestFingerprints?.[digestScopeKey(scope)];
-    return typeof value === "string" ? value : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-export function updateScopedDigest(root: string, scope: DigestScope, digest: string): void {
-  mkdirSync(join(root, "digests"), { recursive: true });
-  atomicWrite(digestPath(root, scope), `${digest.trim()}\n`);
-}
-
-/** Build injected context only from the current project and explicit global notes. */
-export function readScopedSummary(root: string, projectId: string, capBytes = 12_000): string {
-  const renderLayer = (scope: DigestScope, heading: string, layerCap: number): string => {
-    const notes = readStoredNotes(root).filter((note) =>
-      scope.kind === "global" ? note.scope === "global" : note.scope === "project" && note.projectId === scope.projectId,
-    );
-    let digest = "";
-    const currentFingerprint = createDigestSnapshot(root, scope).fingerprint;
-    if (successfulDigestFingerprint(root, scope) === currentFingerprint) {
-      try { digest = readFileSync(digestPath(root, scope), "utf8").trim(); } catch { /* derived cache may lag */ }
-    }
-    const recent = notes.slice(-RECENT_NOTES_CAP).map(registryLine);
-    const layer = [
-      `## ${heading}`,
-      "",
-      digest || "_No digest is available; use the source-linked recent notes below._",
-      "",
-      "### Recent source notes",
-      ...(recent.length > 0 ? recent : ["_None._"]),
-    ].join("\n");
-    return layer.length <= layerCap
-      ? layer
-      : `${layer.slice(0, layerCap)}\n_(layer truncated; use pocket_recall for source notes)_`;
-  };
-  const globalCap = Math.max(1_500, Math.floor(capBytes / 4));
-  const projectCap = Math.max(1_500, capBytes - globalCap - 40);
-  return [
-    "# Astral Pocket Summary",
-    "",
-    renderLayer({ kind: "project", projectId }, "Current repository memory", projectCap),
-    "",
-    renderLayer({ kind: "global" }, "Explicit global memory", globalCap),
-  ].join("\n");
-}
-
-/** Bounded, source-linked digest input built from notes rather than SUMMARY.md. */
-export function createDigestSnapshot(root: string, scope: DigestScope): DigestSnapshot {
-  const notes = readStoredNotes(root)
-    .filter((note) => scope.kind === "global" ? note.scope === "global" : note.scope === "project" && note.projectId === scope.projectId)
-    .slice(-DIGEST_NOTE_CAP);
-  const promptSource = notes.map((note) => [
-    `NOTE: notes/${note.fileName}`,
-    `TITLE: ${note.title}`,
-    `PROJECT: ${note.project || "unknown"}`,
-    `SOURCE: ${note.source || "legacy"}`,
-    `DATE: ${note.updated || note.created || "unknown"}`,
-    note.body.slice(0, DIGEST_NOTE_BYTES),
-  ].join("\n")).join("\n\n");
-  return {
-    fingerprint: createHash("sha256").update(promptSource).digest("hex"),
-    promptSource,
-    noteCount: notes.length,
-  };
+  if (!terms.length) return [];
+  const cap = full ? 4_000 : 320;
+  return readStoredNotes(root)
+    .filter(
+      (n) =>
+        !isExcludedSession(
+          { id: n.sessionId, path: n.sourcePath },
+          excludeSession,
+        ),
+    )
+    .filter((n) => includeHistory || eligible(n))
+    .filter(
+      (n) =>
+        recallScope === "all" ||
+        n.projectId === currentProject ||
+        (includeHistory && n.scope === "global"),
+    )
+    .filter((n) => terms.every((term) => n.text.toLowerCase().includes(term)))
+    .sort(
+      (a, b) =>
+        Number(b.projectId === currentProject) -
+          Number(a.projectId === currentProject) ||
+        b.updated.localeCompare(a.updated) ||
+        a.fileName.localeCompare(b.fileName),
+    )
+    .slice(0, Math.max(1, limit))
+    .map((n) => {
+      const matches = terms
+        .map((term) => n.body.toLowerCase().indexOf(term))
+        .filter((at) => at >= 0);
+      const start = Math.max(
+        0,
+        (matches.length ? Math.min(...matches) : 0) - Math.floor(cap / 4),
+      );
+      return {
+        noteFile: n.fileName,
+        title: n.title,
+        excerpt: `${start ? "…" : ""}${n.body.slice(start, start + cap)}${start + cap < n.body.length ? "…" : ""}`,
+        project: n.project,
+        projectId: n.projectId,
+        scope: n.scope,
+        source: n.source,
+        date: n.updated || n.created,
+        historical: !eligible(n) || n.projectId !== currentProject,
+        retired: n.retired,
+      };
+    });
 }