@staix/agent-mem 0.17.0 → 0.19.0

package/src/memory/doctor.ts

@@ -1,8 +1,11 @@
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { indexFileName } from "./index-file.ts";
+import { assertFormatFloor } from "./formats.ts";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { Database } from "bun:sqlite";
-import { sessionStartBrief } from "../session-brief.ts";
+import { sessionStartBrief, type BriefOptions } from "../session-brief.ts";
+import { openCuratedForRead } from "./curated-read.ts";
 import { pendingSummary } from "./candidate-pending.ts";
 import { readCaptureDrops } from "./metrics.ts";
 import { walkShards } from "./catalog.ts";
@@ -11,10 +14,11 @@ import { readSelector } from "./generation.ts";
 import { processLiveness, withGitTimeout } from "./platform.ts";
 import { endLikeSignal, STOP_SIGNALS } from "./sync-cadence.ts";
 import { boundRepoRoot } from "./repo-scope.ts";
-import { facts, label, PLAIN, type Style } from "./style.ts";
-import { shardDir } from "./shard.ts";
+import { facts, label, PLAIN, singleLine, type Style } from "./style.ts";
+import { aliasedKeys, shardDir } from "./shard.ts";
 import type { MemoryStore, View } from "./store.ts";
 import { nextSyncAt, readSyncState, remoteConfigured, syncDue, usableState } from "./sync-cadence.ts";
+import { readSetupDrift } from "../setup-drift.ts";
 
 /**
  * F15, `amem doctor`: one report over the memory home. It writes nothing into the home. Every check that needs a store (the notes, the brief, the index proof) runs on a
@@ -41,6 +45,8 @@ const MAX_IDS = 10;
 
 export interface DoctorOptions {
   home: string; homeSource: string; cwd: string; project: string; aliases: readonly string[]; now: number;
+  /** Test seam for setup path resolution; the CLI uses the process environment. */
+  env?: Readonly<Record<string, string | undefined>>;
   /** Opens this project's curated store on `base`, the way the other person reads do (a split home through its project shard). Doctor passes a private scratch base, never the live home. */
   openCurated: (base: string) => MemoryStore;
   /** The cadence command the person runs from their own shell; shown in the report, never installed. */
@@ -59,6 +65,8 @@ export interface DoctorReport {
     drops: Section;
     /** #188, additive: present only when the project's curated logs hold forget or prune operations. Informational; status is always ok. */
     masked?: Section;
+    /** #202, additive: applied native setup registrations checked against the shared path resolver. */
+    setup?: Section;
   };
 }
 
@@ -93,7 +101,22 @@ function curatedPresent(home: string, project: string, layout: Layout): boolean
 /** What a scratch copy leaves out: databases, locks, repositories, the machine-local capture and work trees, spools and ingest cursors. */
 const SKIP = /\.db(-wal|-shm)?$|\.lock$|\.tmp$|^\.git$|\.git$|^spool$|^ingest$|^readers$/;
 class TooBig extends Error {}
-function copyTree(from: string, to: string, budget: { bytes: number }, skipNames: ReadonlySet<string> = new Set()): void {
+interface CopyBudget { bytes: number; verify?: (() => void)[] }
+function observedCopy(from: string, to: string, budget: CopyBudget): void {
+  budget.bytes += statSync(from).size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
+  if (budget.verify) {
+    const stamp = () => { const s = lstatSync(from, { bigint: true }); if (!s.isFile()) throw Error("recap source is not a plain file"); return `${s.dev}:${s.ino}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`; };
+    const before = stamp(); budget.verify.push(() => { if (stamp() !== before) throw Error("recap source changed"); });
+  }
+  copyFileSync(from, to);
+}
+function observeDirectory(from: string, budget: CopyBudget, keep: (name: string) => boolean): void {
+  if (!budget.verify) return;
+  const stamp = () => { const s = lstatSync(from, { bigint: true }); if (!s.isDirectory()) throw Error("recap source directory changed"); return JSON.stringify([String(s.dev), String(s.ino), readdirSync(from).filter(keep).sort()]); };
+  const before = stamp(); budget.verify.push(() => { if (stamp() !== before) throw Error("recap source directory changed"); });
+}
+function copyTree(from: string, to: string, budget: CopyBudget, skipNames: ReadonlySet<string> = new Set()): void {
+  observeDirectory(from, budget, name => !(SKIP.test(name) && !(basename(from) === "public-prune-objects" && /^[a-f0-9]{40}\.git$/.test(name))) && !skipNames.has(name));
   mkdirSync(to, { recursive: true, mode: 0o700 });
   for (const name of readdirSync(from)) {
     const proofObject = basename(from) === "public-prune-objects" && /^[a-f0-9]{40}\.git$/.exec(name)?.[0] === name;
@@ -102,25 +125,24 @@ function copyTree(from: string, to: string, budget: { bytes: number }, skipNames
     if (proofObject && !stat.isFile()) throw new Error("a public prune object is not a plain file");
     if (stat.isSymbolicLink()) throw new Error("the memory home holds a link where a plain file or directory is expected");
     if (stat.isDirectory()) copyTree(source, join(to, name), budget, skipNames);
-    else if (stat.isFile()) { budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig(); copyFileSync(source, join(to, name)); }
+    else if (stat.isFile()) observedCopy(source, join(to, name), budget);
   }
 }
 
 /** The curated side of the home, without any database: the logs of this project (and its aliases), and the small files that bind them. */
-function copyCurated(options: DoctorOptions, layout: Layout, scratch: string, budget: { bytes: number }): void {
+function copyCurated(options: Pick<DoctorOptions, "home" | "project" | "aliases">, layout: Layout, scratch: string, budget: CopyBudget): void {
   const home = options.home;
+  observeDirectory(home, budget, name => !SKIP.test(name) && regularFile(join(home, name)));
   for (const name of readdirSync(home)) {      // top-level plain files: machine.json, shards.json, profile.json, aliases.jsonl, lifecycle.jsonl, the configuration
     if (SKIP.test(name) || !regularFile(join(home, name))) continue;
-    const stat = statSync(join(home, name)); budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
-    copyFileSync(join(home, name), join(scratch, name));
+    observedCopy(join(home, name), join(scratch, name), budget);
   }
   const selected = readSelector(home).selector;
   if (selected?.schema === "agent-mem.profile/v2") {
     const name = `${selected.pruneInputSetHash}.json`, source = join(home, "public-prune-input-sets", name), stat = lstatSync(source);
     if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error("the committed public prune view is not a plain file");
-    budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
     const directory = join(scratch, "public-prune-input-sets"); mkdirSync(directory, { mode: 0o700 });
-    copyFileSync(source, join(directory, name)); chmodSync(join(directory, name), 0o600);
+    observedCopy(source, join(directory, name), budget); chmodSync(join(directory, name), 0o600);
   }
   if (layout === "split") {
     for (const key of [options.project, ...options.aliases]) {
@@ -135,22 +157,59 @@ function copyCurated(options: DoctorOptions, layout: Layout, scratch: string, bu
 }
 
 /** The work logs of this project and its aliases, in a private base of their own: the brief opens a work list read-write and migrates its index. */
-function copyWork(options: DoctorOptions, base: string, budget: { bytes: number }): boolean {
+function copyWork(options: Pick<DoctorOptions, "home" | "project" | "aliases">, base: string, budget: CopyBudget): boolean {
   let any = false;
-  for (const name of ["machine.json", "aliases.jsonl", "lifecycle.jsonl"]) if (regularFile(join(options.home, name))) { mkdirSync(base, { recursive: true, mode: 0o700 }); copyFileSync(join(options.home, name), join(base, name)); }
+  for (const name of ["machine.json", "aliases.jsonl", "lifecycle.jsonl"]) if (regularFile(join(options.home, name))) { mkdirSync(base, { recursive: true, mode: 0o700 }); observedCopy(join(options.home, name), join(base, name), budget); }
   for (const key of [options.project, ...options.aliases]) {
     const dir = shardDir(options.home, key), log = join(dir, "work", "log");
     if (!regularDir(log)) continue;
     copyTree(log, join(base, "projects", dir.split("/").pop()!, "work", "log"), budget);
-    if (regularFile(join(dir, "project.json"))) copyFileSync(join(dir, "project.json"), join(base, "projects", dir.split("/").pop()!, "project.json"));
+    if (regularFile(join(dir, "project.json"))) observedCopy(join(dir, "project.json"), join(base, "projects", dir.split("/").pop()!, "project.json"), budget);
     any = true;
   }
   return any;
 }
 
+/** Reuse doctor's bounded private inputs for an on-demand brief, never a live store or reader lease. */
+export async function withBriefSnapshot<T>(home: string, project: string, read: (inputs: NonNullable<BriefOptions["measureOnly"]>) => Promise<T>): Promise<T> {
+  const aliases = aliasedKeys(home, project), selection = readSelector(home).revision, layout = layoutOf(home), guard = guardScratch();
+  let scratch: string | undefined, curated: MemoryStore | undefined;
+  const budget: CopyBudget = { bytes: 0, verify: [] };
+  const inputDirectories = [join(home, "projects"), ...(layout === "split" ? [join(home, "user")] : [join(home, "log"), join(home, "local")]),
+    ...(layout === "generation" ? [join(home, "generations")] : []),
+    ...[project, ...aliases].flatMap(key => { const dir = shardDir(home, key); return [dir, join(dir, "work"), join(dir, "work", "log")]; })];
+  const checkDirectories = () => {
+    for (const dir of inputDirectories) { const stat = lstatSync(dir, { throwIfNoEntry: false }); if (stat && !stat.isDirectory()) throw Error("recap input is not a plain directory"); }
+  };
+  const check = () => {
+    checkDirectories();
+    if (readSelector(home).revision !== selection || layoutOf(home) !== layout || JSON.stringify(aliasedKeys(home, project)) !== JSON.stringify(aliases)) throw Error("recap binding changed");
+    for (const verify of budget.verify!) verify();
+  };
+  try {
+    checkDirectories();
+    scratch = mkdtempSync(join(tmpdir(), `amem-doctor-${process.pid}-`)); chmodSync(scratch, 0o700); guard.adopt(scratch);
+    const options = { home, project, aliases }, workBase = join(scratch, "work-base"); mkdirSync(workBase, { mode: 0o700 });
+    copyWork(options, workBase, budget);
+    if (curatedPresent(home, project, layout)) {
+      const copy = join(scratch, "home"); mkdirSync(copy, { mode: 0o700 }); copyCurated(options, layout, copy, budget);
+      curated = openCuratedForRead(copy, project);
+      if (!curated) throw Error("recap curated snapshot unavailable");
+    }
+    check();
+    const result = await read({ ...(curated ? { curated } : {}), workBase });
+    check(); return result;
+  } catch (error) {
+    if (error instanceof TooBig) throw Error("recap snapshot exceeds the 64 MiB copy limit");
+    throw error;
+  } finally {
+    try { curated?.close(); } finally { try { if (scratch) rmSync(scratch, { recursive: true, force: true }); } finally { guard.release(); } }
+  }
+}
+
 /** A snapshot of the live shared-v1 index (a read-only connection, so no checkpoint, no lease), or false when there is none. */
 function snapshotIndex(live: string, to: string): boolean {
-  const file = join(live, "index.db");
+  const file = join(live, indexFileName(false));
   if (!regularFile(file)) return false;
   const forms: (() => Database)[] = [
     () => new Database(file, { readonly: true }),
@@ -383,7 +442,11 @@ function guardScratch(): { adopt: (dir: string) => void; release: () => void } {
  * a lone signal waits at most one call for the signal handler, which then removes the scratch copy and ends doctor.
  */
 export const DOCTOR_GIT_TIMEOUT_MS = 5_000;
-export function doctorReport(options: DoctorOptions): Promise<DoctorReport> { return withGitTimeout(DOCTOR_GIT_TIMEOUT_MS, () => runDoctor(options)); }
+export function doctorReport(options: DoctorOptions): Promise<DoctorReport> {
+  // Doctor reads every surface below, live or through a scratch copy: a floor on any of them refuses the whole report before anything is read (#199 AC5).
+  for (const surface of ["curated", "capture", "candidates", "work-lists"] as const) assertFormatFloor(options.home, surface);
+  return withGitTimeout(DOCTOR_GIT_TIMEOUT_MS, () => runDoctor(options));
+}
 async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   let scratch: string | undefined, unguard: (() => void) | undefined;
   let duplicates: Section, stale: Section, index: Section;
@@ -407,7 +470,7 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
       } else {
         const home = join(scratch, "home"); mkdirSync(home, { mode: 0o700 });
         copyCurated(options, layout, home, budget);
-        const snapshotted = layout === "shared-v1" && snapshotIndex(options.home, join(home, "index.db"));
+        const snapshotted = layout === "shared-v1" && snapshotIndex(options.home, join(home, indexFileName(false)));
         curated = options.openCurated(home);
         const rows = curated.list({ project: options.project, limit: LIST_ALL });
         await tick();
@@ -428,10 +491,13 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
     candidates = summary === null ? unavailable("candidates.db exists but cannot be read")
       : { status: summary.dueWithin7Days ? "attention" : "ok", ...summary, ...(summary.dueWithin7Days ? { hint: "run amem review walk" } : {}) };
   } catch (error) { candidates = unavailable(message(error)); }
+  let setup: Section;
+  try { setup = { ...readSetupDrift({ home: options.home, ...(options.env ? { env: options.env } : {}), cwd: options.cwd }) }; }
+  catch { setup = unavailable("setup registrations could not be checked"); }
   let sections: DoctorReport["sections"];
   try {
     await tick();
-    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options), drops: dropsSection(options), ...maskedSection(curated) };
+    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options), drops: dropsSection(options), setup, ...maskedSection(curated) };
     await tick();   // a signal that arrived during the last synchronous stage is handled while the guard is still installed
   } finally { try { curated?.close(); } finally { try { if (scratch) rmSync(scratch, { recursive: true, force: true }); } finally { unguard?.(); } } }
   return { schema: DOCTOR_SCHEMA, status: worst(Object.values(sections).map(section => section.status)), home: { path: options.home, source: options.homeSource }, project: options.project, sections };
@@ -441,6 +507,7 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
 const SECTION_TITLE: Record<keyof DoctorReport["sections"], string> = {
   duplicates: "duplicate notes", stale: "stale path references", candidates: "review candidates", capture: "capture per CLI", brief: "session brief",
   index: "index equals rebuild", readers: "reader leases", policy: "policy in effect", cadence: "ingest and sync cadence", drops: "recent capture drops",
+  setup: "native setup registrations",
   masked: "forgotten or pruned entries (informational)",
 };
 
@@ -461,6 +528,10 @@ function sectionDetail(name: string, detail: Record<string, unknown>, s: Style):
     const counts = Object.entries((detail.counts ?? {}) as Record<string, number>);
     return [counts.length ? `${counts.map(([reason, n]) => `${reason.replaceAll("_", " ")} ${n}`).join(", ")} (recent metrics tail)` : "none in the recent metrics tail"].map(line => detail.malformedLines ? `${line}; ${detail.malformedLines} malformed lines skipped` : line);
   }
+  if (name === "setup" && Array.isArray(detail.entries)) {
+    return (detail.entries as { target?: unknown; file?: unknown; entry?: unknown; reason?: unknown; expectedFile?: unknown }[]).map(item =>
+      singleLine(`${item.target} ${item.file}${item.expectedFile ? ` -> ${item.expectedFile}` : ""} ${item.entry}: ${item.reason}`));
+  }
   if (name === "brief" && typeof detail.tokens === "number") return [`${detail.tokens} of ${detail.budget} tokens${detail.coverage ? `, coverage ${facts(detail.coverage as Record<string, unknown>) || "complete"}` : ""}`];
   const { examples, ...rest } = detail;
   const line = facts(rest);

package/src/memory/formats.ts

@@ -0,0 +1,65 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync, readSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Format floors (#199 AC5). `formats.json` in the memory home is an append-only JSON array of `{ surface, minReader, since }` records: a
+ * person appends one to stop releases older than `minReader` from reading that surface (`home` covers every surface). This package never
+ * writes the file, so no writer raises a floor implicitly. Each surface checks its floor before it creates, opens or writes anything, and a
+ * reader below it refuses with `code: "format_floor"`; a file this version cannot read refuses with `code: "format_floor_unreadable"`.
+ * A record naming a surface this version does not know is not its concern. Releases before this one do not read the file.
+ */
+export const FORMATS_FILE = "formats.json";
+export const FORMAT_SURFACES = ["curated", "capture", "hook-spool", "candidates", "work-lists", "sync"] as const;
+export type FormatSurface = typeof FORMAT_SURFACES[number];
+export interface FormatFloor { surface: string; minReader: string; since: string }
+const MAX_BYTES = 64 * 1024, SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;
+
+export class FormatFloorError extends Error {
+  constructor(readonly code: "format_floor" | "format_floor_unreadable", message: string, readonly floor?: FormatFloor & { reader: string }) { super(message); this.name = "FormatFloorError"; }
+}
+/**
+ * This release's version, read once when the module loads, so a long-running process whose install is replaced in place keeps comparing its own
+ * version. Undefined when it cannot be read: then every applicable floor refuses.
+ */
+const READER_VERSION: string | undefined = (() => {
+  try { const { version } = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version?: unknown }; return typeof version === "string" && SEMVER.test(version) ? version : undefined; }
+  catch { return undefined; }
+})();
+const parts = (version: string) => SEMVER.exec(version)!.slice(1, 4).map(Number);
+function below(reader: string, floor: string): boolean {
+  const a = parts(reader), b = parts(floor);
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i]! < b[i]!;
+  return false;
+}
+
+/** Bounded read of the floor records: undefined when there is no file; anything that is not a regular file of valid records refuses. */
+export function readFormatFloors(home: string): FormatFloor[] | undefined {
+  const file = join(home, FORMATS_FILE), unreadable = (why: string) => new FormatFloorError("format_floor_unreadable", `${file}: ${why}; nothing was read or written. Fix or restore the file (it is append-only and written by a person).`);
+  let fd: number;
+  try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT" || (error as NodeJS.ErrnoException).code === "ENOTDIR") return undefined; throw unreadable("not a readable regular file"); }
+  let text: string;
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_BYTES) throw unreadable("not a regular file of at most 64 KiB");
+    const data = Buffer.alloc(MAX_BYTES + 1); let size = 0, n: number;
+    while (size < data.length && (n = readSync(fd, data, size, data.length - size, null)) > 0) size += n;
+    if (size > MAX_BYTES) throw unreadable("not a regular file of at most 64 KiB");
+    text = data.subarray(0, size).toString("utf8");
+  } finally { closeSync(fd); }
+  let value: unknown;
+  try { value = JSON.parse(text); } catch { throw unreadable("not JSON"); }
+  if (!Array.isArray(value) || !value.every(record => record && typeof record === "object" && !Array.isArray(record)
+    && typeof record.surface === "string" && typeof record.minReader === "string" && SEMVER.test(record.minReader) && typeof record.since === "string")) throw unreadable("not an array of { surface, minReader, since } records");
+  return value.map(({ surface, minReader, since }) => ({ surface, minReader, since }));
+}
+
+/** Refuse before touching `surface` when the home records a floor above this release. */
+export function assertFormatFloor(home: string, surface: FormatSurface): void {
+  const floors = readFormatFloors(home);
+  if (!floors) return;
+  const reader = READER_VERSION ?? "unknown";
+  for (const floor of floors) if ((floor.surface === surface || floor.surface === "home") && (READER_VERSION === undefined || below(READER_VERSION, floor.minReader))) {
+    throw new FormatFloorError("format_floor", `amem ${reader} is below the ${surface} format floor ${floor.minReader} (since ${floor.since}) recorded in ${join(home, FORMATS_FILE)}; nothing was read or written. Upgrade amem to ${floor.minReader} or later.`, { ...floor, reader });
+  }
+}

package/src/memory/index-file.ts

@@ -0,0 +1,15 @@
+/** Bumped when the index's tables change: an index with another version is dropped and rebuilt from the logs. */
+export const INDEX_VERSION = 3; // 3: suggest, confirm and reject ops (an older index skipped them)
+/** The version that released 0.14.0 through 0.18.0 build into the unversioned names below; it keeps them so this release shares their warm index. */
+const SHARED_INDEX_VERSION = 3;
+
+/**
+ * The derived curated index file of a profile directory, one per `INDEX_VERSION` (#199 AC4): two releases with different index versions on
+ * one home each keep their own file instead of dropping and rebuilding the other's. Version 3 keeps the released names (`index.db`, and
+ * `index-v2.db` for the v2 public-prune view, whose `v2` is that view's format, not the index version); every later version names its own,
+ * `index-v<N>.db` or `index-v2-i<N>.db`. An older version's file is left as it is.
+ */
+export function indexFileName(foreignPruneFormat: boolean, version: number = INDEX_VERSION): string {
+  const base = foreignPruneFormat ? "index-v2" : "index";
+  return version === SHARED_INDEX_VERSION ? `${base}.db` : foreignPruneFormat ? `${base}-i${version}.db` : `${base}-v${version}.db`;
+}

package/src/memory/metrics.ts

@@ -1,8 +1,9 @@
 import { closeSync, constants, fstatSync, openSync, readSync, appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import type { HookRssSources } from "../hook-resources.ts";
 import { join } from "node:path";
 
 /** Rolling resource samples; importing this leaf never loads a memory store or capacity probe. */
-export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
+export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; rssSources?: HookRssSources; rssScope?: "owned-images"; transcriptOffset?: number; transcriptStopReason?: "cap" | "deadline" | "spool_full"; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
 const METRICS_MAX_BYTES = 64 * 1024, METRICS_KEEP = 200;
 
 export function metricsPath(base: string): string {
@@ -36,8 +37,8 @@ export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[]
 }
 
 
-export type CaptureDropReason = "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten";
-const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten"];
+export type CaptureDropReason = "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten" | "unknown_schema_expired" | "transcript_line_bound";
+const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired", "transcript_line_bound"];
 /** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. Fails open to no counts: hooks never deny over metrics. */
 export function captureDropSummary(base: string): Partial<Record<CaptureDropReason, number>> {
   const read = readCaptureDrops(base);

package/src/memory/public-prune-activation.ts

@@ -2,6 +2,7 @@
  * Checkpoints are fault seams after intent, shard marker, selector and intent removal.
  * A caller resumes an interrupted operation from its immutable direct-profile journal. */
 import { createHash } from "node:crypto";
+import { indexFileName } from "./index-file.ts";
 import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { canonicalJSON, fsyncDirectory, hashJSON, readSelector, withProfileLock, writeProfileJSON, type BoundProfile } from "./generation.ts";
@@ -105,7 +106,7 @@ function immutable(file: string, text: string): void {
   linkSync(temp, file); fsyncDirectory(base); unlinkSync(temp); fsyncDirectory(base);
 }
 function syncIndex(profile: BoundProfile): void {
-  const file = join(profile.dir, "index-v2.db"); owned(file); const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  const file = join(profile.dir, indexFileName(true)); owned(file); const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
   try { fsyncSync(fd); } finally { closeSync(fd); } fsyncDirectory(profile.dir);
 }
 function nextProfile(realm: Realm, intent: Intent): BoundProfile {

package/src/memory/search-fts.ts

@@ -1,4 +1,4 @@
-import { rankedScoreSql, rankedScoreSqlDetails, type ScoreFactors } from "./search-score.ts";
+import { captureEventWeightSql, rankedScoreSql, rankedScoreSqlDetails, type ScoreFactors } from "./search-score.ts";
 import { Database } from "bun:sqlite";
 import { chmodSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -204,8 +204,8 @@ export class ScreenedSearchIndex<T> {
       if ((db.query("SELECT sqlite_compileoption_used('TEMP_STORE=3') AS memoryOnly").get() as { memoryOnly: number }).memoryOnly) throw Error("disk-backed search unavailable");
       db.run("PRAGMA temp_store = FILE");
       db.run(this.available
-        ? "CREATE VIRTUAL TABLE temp.docs USING fts5(body, ref UNINDEXED, tier UNINDEXED, at UNINDEXED, payload UNINDEXED, expires UNINDEXED)"
-        : "CREATE TEMP TABLE docs (body TEXT, ref TEXT, tier TEXT, at TEXT, payload TEXT, expires REAL)");
+        ? "CREATE VIRTUAL TABLE temp.docs USING fts5(body, ref UNINDEXED, tier UNINDEXED, at UNINDEXED, payload UNINDEXED, expires UNINDEXED, event UNINDEXED, session UNINDEXED)"
+        : "CREATE TEMP TABLE docs (body TEXT, ref TEXT, tier TEXT, at TEXT, payload TEXT, expires REAL, event TEXT, session TEXT)");
       db.run("PRAGMA temp.cache_size = -2048");
       // A platform spill minimum can exceed cache_size (macOS: 20,000 pages).
       // Spill at the cache target so dirty TEMP pages cannot accumulate behind that minimum.
@@ -214,13 +214,13 @@ export class ScreenedSearchIndex<T> {
     } catch (error) { db?.close(); throw error; }
   }
 
-  append(rows: readonly { body: string; ref: string; tier: string; at: string; value: T; expiresAt?: string | null }[]): void {
-    const insert = this.db.query("INSERT INTO docs (body, ref, tier, at, payload, expires) VALUES (?, ?, ?, ?, ?, ?)");
+  append(rows: readonly { body: string; ref: string; tier: string; at: string; value: T; expiresAt?: string | null; event?: string; session?: string }[]): void {
+    const insert = this.db.query("INSERT INTO docs (body, ref, tier, at, payload, expires, event, session) VALUES (?, ?, ?, ?, ?, ?, ?, ?)");
     this.db.transaction(() => {
       for (const row of rows) {
         const deadline = row.expiresAt == null ? null : Date.parse(row.expiresAt);
         // Invalid deadlines fail closed; this sentinel predates every representable Date.
-        insert.run(row.body, row.ref, row.tier, row.at, JSON.stringify(row.value), deadline !== null && !Number.isFinite(deadline) ? Number.MIN_SAFE_INTEGER : deadline);
+        insert.run(row.body, row.ref, row.tier, row.at, JSON.stringify(row.value), deadline !== null && !Number.isFinite(deadline) ? Number.MIN_SAFE_INTEGER : deadline, row.event ?? null, row.session ?? null);
       }
     })();
   }
@@ -242,6 +242,31 @@ export class ScreenedSearchIndex<T> {
     });
   }
 
+  /** Weighted capture-only fill after the caller fixes the legacy noncapture slots. The caller has already screened every row before append. */
+  bestCaptureGroups(query: string, limit: number, now: number, useFts = this.available, explain = false): { value: T; score: number; scoreDetails?: ScoreFactors }[] {
+    if (!Number.isSafeInteger(limit) || limit < 1 || useFts && !ftsTerms(query)) return [];
+    const instant = new Date(now).toISOString(), score = useFts ? SCREENED_SCORE : SCREENED_SUBSTRING_SCORE;
+    const weight = captureEventWeightSql("event");
+    const factors = explain ? rankedScoreSqlDetails(useFts ? "bm25(docs)" : "-1.0", useFts) : undefined;
+    const columns = factors ? `, ${factors.rawBm25Rank} AS rawBm25Rank, ${factors.tierFactor} AS tierFactor, ${factors.recencyFactor} AS recencyFactor` : "";
+    const where = "WHERE tier = 'capture' AND (expires IS NULL OR expires > ?)" + (useFts ? " AND docs MATCH ?" : "");
+    const selected: { value: T; score: number; scoreDetails?: ScoreFactors }[] = [], groups = new Set<string>();
+    // Sort once in SQLite-owned TEMP storage, then stream past duplicate sessions without growing JS pages or re-sorting OFFSET windows.
+    const statement = this.db.query(`SELECT payload, ref, event, session, ${score} AS score${columns} FROM docs ${where} ORDER BY score * ${weight} DESC, ref`);
+    const orderedArgs = [instant, ...(explain ? [instant] : []), now, ...(useFts ? [ftsTerms(query)] : [])];
+    for (const row of statement.iterate(...orderedArgs) as Iterable<{ payload: string; ref: string; event: string | null; session: string | null; score: number; rawBm25Rank?: number | null; tierFactor?: number | null; recencyFactor?: number | null }>) {
+      const session = typeof row.session === "string" && /^[a-f0-9]{16}$/.test(row.session) ? row.session : undefined;
+      const group = session ? `session:${session}` : `row:${row.ref}`;
+      if (groups.has(group)) continue;
+      groups.add(group);
+      const hit: { value: T; score: number; scoreDetails?: ScoreFactors } = { value: JSON.parse(row.payload) as T, score: row.score };
+      if (explain) hit.scoreDetails = { rawBm25Rank: row.rawBm25Rank ?? null, tierFactor: row.tierFactor ?? null, recencyFactor: row.recencyFactor ?? null, finalScore: row.score, matchMode: useFts ? "fts5" : "substring" };
+      selected.push(hit);
+      if (selected.length === limit) break;
+    }
+    return selected;
+  }
+
   close(): void {
     if (this.closed) return;
     this.closed = true;
@@ -250,6 +275,7 @@ export class ScreenedSearchIndex<T> {
 }
 
 interface RawCaptureRow { id: number; at: string; project: string; agent: string; event: string; tool: string | null; paths: string; status: string | null; excerpt: string; session?: string | null; subagent?: number | null }
+export interface CaptureSearchOptions { weightEvents?: boolean; onePerSession?: boolean; now?: number }
 
 /**
  * The capture leg of #13 search: BM25 over the excerpts of one capture shard (`machine/<id>` of a project shard,
@@ -257,21 +283,43 @@ interface RawCaptureRow { id: number; at: string; project: string; agent: string
  * Rows older than `notBefore` (an ISO time) are left out; the store passes the shard's retention cutoff, so an expired
  * row is not recalled before a later append evicts it.
  */
-export function captureSearch(dir: string, q: string, limit: number, notBefore?: string): { row: CaptureRow; rank: number }[] {
+export function captureSearch(dir: string, q: string, limit: number, notBefore?: string, options: CaptureSearchOptions = {}): { row: CaptureRow; rank: number }[] {
   const match = ftsTerms(q);
-  if (!match || !fts5Available() || !existsSync(join(dir, "capture.db"))) return [];
+  if (!match || !Number.isSafeInteger(limit) || limit < 1 || !fts5Available() || !existsSync(join(dir, "capture.db"))) return [];
+  const weightEvents = options.weightEvents !== false, onePerSession = options.onePerSession ?? weightEvents;
+  const eventWeight = captureEventWeightSql("r.event");
+  const weightedOrder = `bm25(fts) * ${eventWeight}, r.id`;
+  const selected: { row: CaptureRow; rank: number }[] = [], groups = new Set<string>();
   let db: Database | undefined;
   try {
     db = new Database(join(dir, "capture.db"), { readonly: true });
     db.run("PRAGMA busy_timeout = 3000");
     if (!db.query("SELECT 1 FROM sqlite_master WHERE name = 'fts' AND type = 'table'").get()) return [];
-    // `notBefore` (retention cutoff, `since`) runs inside the query: rows past it never take a LIMIT slot.
-    const rows = (notBefore === undefined
-      ? db.query(`SELECT r.*, bm25(fts) AS rank FROM fts JOIN rows r ON r.id = fts.rowid WHERE fts MATCH ? ORDER BY rank LIMIT ?`).all(match, limit)
-      : db.query(`SELECT r.*, bm25(fts) AS rank FROM fts JOIN rows r ON r.id = fts.rowid WHERE fts MATCH ? AND r.at >= ? ORDER BY rank LIMIT ?`).all(match, notBefore, limit)) as (RawCaptureRow & { rank: number })[];
-    return rows.map((r) => ({ row: { id: r.id, at: r.at, project: r.project, agent: r.agent, event: r.event, tool: r.tool, paths: JSON.parse(r.paths) as string[], status: r.status, excerpt: r.excerpt,
-      // #173 attribution, mirrored from capture-input.ts captureAttribution (this module stays import-light for the ablation harness).
-      ...(typeof r.session === "string" && /^[a-f0-9]{16}$/.test(r.session) ? { session: r.session } : {}), ...(r.subagent === 1 ? { subagent: true as const } : {}) }, rank: r.rank }));
+    // Filter first, then sort once. In the grouped path the first row of each session is
+    // its best complete-score match, so stopping at limit cannot hide a better unread row.
+    const matchWhere = notBefore === undefined ? "fts MATCH ?" : "fts MATCH ? AND r.at >= ?";
+    const args: (string | number)[] = notBefore === undefined ? [match] : [match, notBefore];
+    const order = onePerSession
+      ? `${rankedScoreSql("bm25(fts)")} * ${weightEvents ? eventWeight : "1.0"} DESC, r.id`
+      : weightEvents ? weightedOrder : "rank";
+    // The capture tier is an existing score input, projected only for the shared SQL recipe.
+    const sql = `SELECT r.*, ${onePerSession ? "'capture' AS tier, " : ""}bm25(fts) AS rank FROM fts JOIN rows r ON r.id = fts.rowid WHERE ${matchWhere} ORDER BY ${order}${onePerSession ? "" : " LIMIT ?"}`;
+    args.push(onePerSession ? new Date(options.now ?? Date.now()).toISOString() : limit);
+    const statement = db.query(sql);
+    const rows = (onePerSession ? statement.iterate(...args) : statement.all(...args)) as Iterable<RawCaptureRow & { rank: number }>;
+    for (const r of rows) {
+      const session = typeof r.session === "string" && /^[a-f0-9]{16}$/.test(r.session) ? r.session : undefined;
+      if (onePerSession && session) {
+        if (groups.has(session)) continue;
+        groups.add(session);
+      }
+      const row: CaptureRow = { id: r.id, at: r.at, project: r.project, agent: r.agent, event: r.event, tool: r.tool, paths: JSON.parse(r.paths) as string[], status: r.status, excerpt: r.excerpt,
+        // #173 attribution, mirrored from capture-input.ts captureAttribution (this module stays import-light for the ablation harness).
+        ...(session ? { session } : {}), ...(r.subagent === 1 ? { subagent: true as const } : {}) };
+      selected.push({ row, rank: r.rank });
+      if (selected.length === limit) break;
+    }
+    return selected;
   } catch { return []; }
   finally { db?.close(); }
 }

package/src/memory/search-score.ts

@@ -14,6 +14,17 @@ type ScoreExpr = { op: "rank" | "tier" | "age" } | { op: "constant"; value: numb
 const MONTH_DAYS = 30;
 const TIER_WEIGHTS: Readonly<Record<string, number>> = { long: 1, capture: 0.5 };
 const DEFAULT_TIER_WEIGHT = 0.9;
+// ponytail: fixed 1.25x ceiling for conversational capture, not a learned relevance model.
+// Raise it only with fresh S/M no-loss and private-capture evidence; curated tier factors stay unchanged.
+export const CAPTURE_CONVERSATION_WEIGHT = 1.25;
+const CONVERSATIONAL_CAPTURE_EVENTS = ["Stop", "UserPromptSubmit", "Title", "Recap", "Compact"] as const;
+export function captureEventWeight(event: string): number {
+  return (CONVERSATIONAL_CAPTURE_EVENTS as readonly string[]).includes(event) ? CAPTURE_CONVERSATION_WEIGHT : 1;
+}
+/** Only fixed internal SQL identifiers are supplied by callers; event values remain stored data. */
+export function captureEventWeightSql(eventColumn: string): string {
+  return `(CASE WHEN ${eventColumn} IN (${CONVERSATIONAL_CAPTURE_EVENTS.map(event => `'${event}'`).join(", ")}) THEN ${CAPTURE_CONVERSATION_WEIGHT} ELSE 1.0 END)`;
+}
 const TIER_FACTOR: ScoreExpr = { op: "tier" };
 const DENOMINATOR: ScoreExpr = { op: "add", left: { op: "constant", value: 1 }, right: { op: "max", left: { op: "constant", value: 0 }, right: { op: "age" } } };
 const RECENCY_FACTOR: ScoreExpr = { op: "reciprocal", value: DENOMINATOR };
@@ -53,6 +64,9 @@ function sql(expr: ScoreExpr, rank: string): string {
 export function rankedScore(rank: number, tier: string, at: string, now: number): number {
   return numeric(SCORE, rank, tier, at, now);
 }
+export function captureWeightedScore(rank: number, event: string, at: string, now: number): number {
+  return rankedScore(rank, "capture", at, now) * captureEventWeight(event);
+}
 /** SQL uses fixed internal identifiers and bound clock values, never interpolated row/query input. */
 export function rankedScoreSql(rank = "bm25(docs)"): string { return sql(SCORE, rank); }
 export function rankedScoreSqlDetails(rank = "bm25(docs)", useFts = true): { rawBm25Rank: string; tierFactor: string; recencyFactor: string } {

package/src/memory/shard.ts

@@ -1,4 +1,5 @@
 import { assertNoPublicPruneIntent, readPublicPruneView } from "./public-prune-view.ts";
+import { indexFileName } from "./index-file.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -145,7 +146,7 @@ export function assertCuratedShardPaths(memoryDir: string, opts: { project?: str
   check(dir, true);
   for (const folder of ["log", "local", "legacy", "legacy/log", "legacy/local", "legacy-main", "legacy-main/log", "legacy-main/local"]) check(join(dir, folder), true);
   for (const name of ["project.json", "generation.json", "generation-seal.json", "migration-sources.json", "machine.json", "legacy/machine.json", "legacy-main/machine.json", "prune-translations.jsonl"]) check(join(dir, name), false);
-  for (const database of ["index.db", "index-v2.db", "search.db", "mutation-lock.db"]) for (const suffix of ["", "-wal", "-shm", "-journal"]) check(join(dir, database + suffix), false);
+  for (const database of new Set(["index.db", "index-v2.db", indexFileName(false), indexFileName(true), "search.db", "mutation-lock.db"])) for (const suffix of ["", "-wal", "-shm", "-journal"]) check(join(dir, database + suffix), false);
 }
 
 /** Open one already-sealed shard without consulting the legacy home or the catalog. */