@staix/agent-mem 0.18.0 → 0.19.0

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" | "unknown_schema_expired";
-const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired"];
+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-score.ts

@@ -17,12 +17,13 @@ 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 event === "Stop" || event === "UserPromptSubmit" ? CAPTURE_CONVERSATION_WEIGHT : 1;
+  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 ('Stop', 'UserPromptSubmit') THEN ${CAPTURE_CONVERSATION_WEIGHT} ELSE 1.0 END)`;
+  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" } } };

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. */

package/src/memory/store.ts

@@ -1,4 +1,6 @@
+import { assertFormatFloor } from "./formats.ts";
 import { readPublicPruneView } from "./public-prune-view.ts";
+import { INDEX_VERSION, indexFileName } from "./index-file.ts";
 import { readShardLegacySnapshot } from "./shard-bridge.ts";
 import { cliAttribution } from "./cli-attribution.ts";
 import { Database } from "bun:sqlite";
@@ -77,8 +79,6 @@ export type Entry = NoteEntry | OpEntry | GoalEntry;
 export const GOAL_STATES = ["open", "active", "blocked", "done", "dropped"] as const;
 export type GoalState = (typeof GOAL_STATES)[number];
 export const DEFAULT_LEASE_MS = 4 * 3600_000;
-/** Bumped when the index's tables change: an index with another version is dropped and rebuilt from the logs. */
-const INDEX_VERSION = 3; // 3: suggest, confirm and reject ops (an older index skipped them)
 export const SUGGESTED = ["contradicts", "same_topic"] as const;
 export type Suggested = (typeof SUGGESTED)[number];
 export interface Suggestion { id: string; at: string; from: string; to: string; rel: Suggested; status: "suggested" | "confirmed" | "rejected" }
@@ -233,6 +233,7 @@ export class MemoryStore {
     this.reconcile = opts.reconcile && opts.reconcile.aliases.length ? { canonical: opts.reconcile.canonical, aliases: [...opts.reconcile.aliases] } : undefined;
     if (opts.memoryDir !== undefined && (opts.home !== undefined || typeof opts.memoryDir !== "string" || !opts.memoryDir.trim())) throw new Error("choose a memory home or one explicit memory directory");
     const home = bootstrap?.profile.home ?? opts.memoryDir ?? (opts.home === undefined ? memoryHome() : join(opts.home, "memory"));
+    assertFormatFloor(home, "curated");
     if (!bootstrap && lstatSync(join(home, "shards.json"), { throwIfNoEntry: false })) throw new Error("memory home has a curated split; hosts must use openShardStore({ project }) or openShardStore({ user: true }); finish an incomplete split with amem migrate --shards --resume");
     this.profile = bootstrap?.profile ?? resolveProfile(home, opts.profile);
     if (bootstrap && (this.profile.kind !== "generation" || !this.profile.generation
@@ -253,7 +254,7 @@ export class MemoryStore {
     if (!bootstrap || bootstrap.authoring === true) this.releaseReaderLease = registerReaderLease(this.profile.home, this.profile.sharded ? {scope:"shard"} : {});
     let openedDb: Database | undefined, openedMutation: Database | undefined, openedSearch: SearchIndex | undefined;
     try {
-      const indexFile = join(this.dir, this.profile.foreignPruneFormat ? "index-v2.db" : "index.db");
+      const indexFile = join(this.dir, indexFileName(!!this.profile.foreignPruneFormat));
       if (this.profile.foreignPruneFormat) for (const suffix of ["", "-wal", "-shm", "-journal"]) {
         const stat = lstatSync(indexFile + suffix, {throwIfNoEntry:false});
         if (stat && (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid?.())) throw new Error("v2 index path unavailable");
@@ -280,7 +281,7 @@ export class MemoryStore {
       // One derived FTS copy per profile: a generation handle and a shared-v1 handle on one home never resync-fight.
       this.searchIndex = openedSearch = new SearchIndex(this.profile.sharded ? join(this.dir, "search.db") : join(home, this.profile.kind === "generation" ? `search-${this.profile.generation}.db` : "search.db"));
       this.memoryBaseDir = home;
-      try { chmodSync(join(this.dir, this.profile.foreignPruneFormat ? "index-v2.db" : "index.db"), 0o600); } catch { /* best effort */ }
+      try { chmodSync(indexFile, 0o600); } catch { /* best effort */ }
       if (this.profile.kind === "generation") this.generationIndex = new GenerationIndex({ profile: this.profile, db, now: this.now,
         apply: (line, source) => this.apply(line, source), withMutation: work => this.withMutation(work),
         ...(bootstrap ? { limits: bootstrap.limits } : {}), ...(bootstrap?.commit ? { commit: bootstrap.commit } : {}) });
@@ -1633,6 +1634,7 @@ export function openShardStore(opts: StoreOptions & { project?: string; user?: b
   if (opts.user === true && opts.project !== undefined || opts.user !== true && !opts.project) throw new Error("choose exactly one project or the user shard");
   if (opts.memoryDir !== undefined && (opts.home !== undefined || typeof opts.memoryDir !== "string" || !opts.memoryDir.trim())) throw new Error("choose a memory home or one explicit memory directory");
   const home = opts.memoryDir ?? (opts.home === undefined ? memoryHome() : join(opts.home, "memory"));
+  assertFormatFloor(home, "curated");
   assertCuratedShardPaths(home, opts);
   // Lifecycle refusal must remain before admission creates any lease/fence file.
   if (opts.user !== true && opts.lifecycle !== "ignore") assertProjectActive(home, opts.project!);

package/src/memory/sync.ts

@@ -1,3 +1,4 @@
+import { assertFormatFloor } from "./formats.ts";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, rmSync, writeFileSync, writeSync, type BigIntStats } from "node:fs";
 import { createHash } from "node:crypto";
 import { dirname, join, relative, sep } from "node:path";
@@ -284,6 +285,7 @@ function captureShardSyncBinding(store: MemoryStore, selection: boolean): string
 }
 
 export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Promise<SyncResult> {
+  assertFormatFloor(store.profile.home, "sync");
   if (store.profile.sharded) {
     try {
       // Refresh only through the existing proved monotone profile rebind before pinning this attempt.

package/src/memory/work-lists.ts

@@ -1,3 +1,4 @@
+import { assertFormatFloor } from "./formats.ts";
 import { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
 import { appendFileSync, chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readSync, readdirSync } from "node:fs";
@@ -131,6 +132,7 @@ export class WorkListStore {
       || !Number.isSafeInteger(this.busyTimeoutMs) || this.busyTimeoutMs < 0 || this.busyTimeoutMs > 3000) throw new Error("invalid work-list budget");
     this.checkBudget();
     const base = canonicalPath(options.base);
+    assertFormatFloor(base, "work-lists");
     this.project = options.exact === true ? options.project : resolveAlias(base, options.project);
     regular(join(base, "projects"), true); regular(shardDir(base, this.project), true);
     this.checkBudget();

package/src/session-brief-worker.ts

@@ -1,12 +1,12 @@
 import type { BriefOptions } from "./session-brief.ts";
 import type { CaptureStore } from "./memory/capture.ts";
-import { resolveHookProjectAsync } from "./hook-project.ts";
-import { hookPeakRssKB } from "./hook-resources.ts";
+import { acceptHookProjectReceipt } from "./hook-project.ts";
+import { writeSync } from "node:fs";
+import { hookRssReading, hookPeakRssKB } from "./hook-resources.ts";
+import { rssSourceCode } from "./hook-rss-wire.ts";
 import { resolveAlias } from "./memory/aliases.ts";
-import { HOOK_EVENTS, HOOK_INPUT_BYTES } from "./hook-contract.ts";
-import { drainHookCaptures, hookCaptureScope, quarantineHookScope } from "./hook-spool.ts";
-import { createStandalonePolicy } from "./memory/policy.ts";
-import { configuredPolicyOptions } from "./memory/config.ts";
+import { HOOK_EVENTS, HOOK_INPUT_BYTES, type HookTranscriptProgress } from "./hook-contract.ts";
+import { drainHookCaptures, hookCaptureScope } from "./hook-spool.ts";
 
 async function readOptions(): Promise<string> {
   const reader = Bun.stdin.stream().getReader(), chunks: Uint8Array[] = []; let bytes = 0;
@@ -25,62 +25,63 @@ async function readOptions(): Promise<string> {
 // Fixed package helper, launched and reaped by each native hook; never registered or resident.
 if (import.meta.main) {
   let owned = false;
-  const nativeUsage = { rssKB: 0, rawRssKB: 0 };
+  let rssTelemetryValid = true;
+  const frame = (rss: number[]) => { try { writeSync(1, JSON.stringify({ rss }) + "\n"); } catch { rssTelemetryValid = false; } };
+  const progress = (transcript: HookTranscriptProgress) => { try { writeSync(1, JSON.stringify({ transcript }) + "\n"); } catch { rssTelemetryValid = false; } };
+  frame([0]);
   const stop = (): never => {
+    if (!rssTelemetryValid) frame([4]);
+    const self = hookRssReading(); frame([3, self.kb, self.rawKB, rssSourceCode(self)]);
     // This leader is still alive in the detached group created by hookWorker.
-    // Native Git uses a separate owned async supervisor with its own native watchdog;
-    // a blocked Git cannot prevent this worker's JS deadline from firing.
+    // Native Git is owned and reaped by the CLI parent, never by this worker.
     if (owned) try { process.kill(-process.pid, "SIGKILL"); } catch { /* No group exists in a direct, non-owned invocation. */ }
     process.exit(0);
   };
   const emit = async (result: unknown) => {
-    const body = JSON.stringify({ ...(result as object), complete: true });
-    const rssKB = hookPeakRssKB() + nativeUsage.rssKB;
+    const body = JSON.stringify({ ...(result as object), complete: true, rssTelemetryValid });
+    const rssKB = hookPeakRssKB();
     await Bun.stdout.write(body.slice(0, -1) + `,"rssKB":${rssKB}}\n`);
     stop();
   };
   try {
-    const options = JSON.parse(await readOptions()) as BriefOptions & { current: string; event: string; deadlineAt: number; ownedGroup: boolean };
+    const options = JSON.parse(await readOptions()) as BriefOptions & { current: string; event: string; identity?: unknown; transcript?: unknown; deadlineAt: number; ownedGroup: boolean };
     if (!Number.isFinite(options.deadlineAt) || options.ownedGroup !== true) process.exit(0);
     owned = true;
     const remaining = () => options.deadlineAt - (performance.timeOrigin + performance.now());
-    if (remaining() <= 0) stop();
-    setTimeout(stop, remaining()).unref();
-    const policy = createStandalonePolicy(configuredPolicyOptions(options.base!, options.cwd, options.policy)), event = options.event;
+    const deadlineStop = () => { if (options.transcript !== undefined) progress({ stopReason: "deadline" }); stop(); };
+    if (remaining() <= 0) deadlineStop();
+    setTimeout(deadlineStop, remaining()).unref();
+    const event = options.event;
     if (!(HOOK_EVENTS as readonly string[]).includes(event)) stop();
     const expectedScope = hookCaptureScope(options.cwd, options.base!);
-    let project: string;
-    // Overlap the shared resolver's existing origin/metadata reads on a cold cache;
-    // serial native launches can exhaust every hook before any binding or replay is published.
-    // ponytail: cold identity must still fit one hook deadline. Revalidated durable
-    // identity progress is the upgrade if slower native reads keep exhausting that slice.
-    try { project = resolveAlias(options.base!, await resolveHookProjectAsync({ cwd: options.cwd, base: options.base!, scope: expectedScope, timeRemaining: remaining, maintainCache: event !== "SessionStart", prefetch: true }, nativeUsage)); }
-    catch {
-      if (expectedScope !== undefined) quarantineHookScope({ cwd: options.cwd, base: options.base!, scope: expectedScope });
-      project = stop();
+    // A receipt is single-use parent IPC. This worker must never launch a native helper.
+    if (event === "SessionStart") stop();
+    let project: string | undefined;
+    try { project = resolveAlias(options.base!, acceptHookProjectReceipt(options.identity, { cwd: options.cwd, base: options.base!, scope: expectedScope, timeRemaining: remaining })); } catch { /* Independently bound transcript intake can still proceed. */ }
+    if ((event === "Stop" || event === "SessionEnd") && options.transcript !== undefined
+      && (project !== undefined || expectedScope !== undefined && hookCaptureScope(options.cwd, options.base!) === expectedScope)) {
+      try {
+        const { scanHookTranscriptTail } = await import("./hook-transcript.ts");
+        const scanned = await scanHookTranscriptTail(options.transcript, { cwd: options.cwd, base: options.base!, policy: options.policy,
+          deadline: Math.min(performance.now() + remaining() - 20, performance.now() + 60) });
+        if (scanned) progress(scanned);
+      } catch { /* Ordinary durable capture is independent. */ }
     }
+    if (project === undefined) stop();
     let captured = false;
-    // Normal SessionStart keeps the parent's durable stage for later replay and spends
-    // its short-lived worker on context. An empty current name is mandatory full-tier recovery.
-    if (expectedScope !== undefined && (event !== "SessionStart" || !options.current)) {
+    // An empty current name selects bounded full-tier recovery; SessionStart stays in the parent.
+    if (expectedScope !== undefined) {
       const { CaptureStore } = await import("./memory/capture.ts");
       let store: CaptureStore | undefined;
       try {
-        const drained = await drainHookCaptures({ ...options, base: options.base!, project, expectedScope, timeRemaining: remaining }, (input, receipt) => {
-          store ??= new CaptureStore({ memoryDir: options.base!, project, busyTimeoutMs: 0, cwd: options.cwd });
+        const drained = await drainHookCaptures({ ...options, base: options.base!, project: project!, expectedScope, timeRemaining: remaining }, (input, receipt) => {
+          store ??= new CaptureStore({ memoryDir: options.base!, project: project!, busyTimeoutMs: 0, cwd: options.cwd });
           return store.append(input, { receipt });
         });
         captured = drained.captured.includes(options.current);
       } finally { store?.close(); }
     }
     if (hookCaptureScope(options.cwd, options.base!) !== expectedScope) stop();
-    if (event === "SessionStart") {
-      const { sessionStartBrief } = await import("./session-brief.ts");
-      const result = await sessionStartBrief({ ...options, project,
-        timeRemaining: () => options.deadlineAt - (performance.timeOrigin + performance.now()) });
-      const valid = await policy.screen({ context: result.context });
-      if (hookCaptureScope(options.cwd, options.base!) !== expectedScope) stop();
-      await emit({ ...result, captured, valid });
-    } else await emit({ context: "", captured, valid: true });
+    await emit({ context: "", captured, valid: true });
   } catch { if (owned) stop(); process.exitCode = 1; }
 }

package/src/session-brief.ts

@@ -152,13 +152,13 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
     let candidateLine: string | undefined;
     const line = pendingLine(pendingSummary(base, [project, ...aliases], (options.now ?? Date.now)()));
     if (line !== undefined && Buffer.byteLength(line) + 1 <= remaining) { remaining -= Buffer.byteLength(line) + 1; candidateLine = line; }
-    const add = async (section: Section, shown: { data: unknown; partial: boolean }, evidence: boolean) => {
-      if (!await screen(shown.data)) return;
+    const add = async (section: Section, shown: { data: unknown; partial: boolean }, evidence: boolean): Promise<boolean> => {
+      if (!await screen(shown.data)) return false;
       coverage[section] = shown.partial ? "partial" : coverage[section] ?? "complete";
       const line = JSON.stringify({ section, evidence, data: shown.data });
       const size = Buffer.byteLength(line) + 1;
-      if (Buffer.byteLength(line) > RECORD_BYTES || size > remaining) { coverage[section] = "partial"; return; }
-      lines.push(line); remaining -= size;
+      if (Buffer.byteLength(line) > RECORD_BYTES || size > remaining) { coverage[section] = "partial"; return false; }
+      lines.push(line); remaining -= size; return true;
     };
     const run = async (section: Section, work: () => Promise<void>) => {
       const firstLine = lines.length, priorRemaining = remaining;
@@ -193,14 +193,15 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
         }
       });
       const recent = async <T>(section: "curated" | "capture", read: (window: ReadWindow) => { rows: T[]; next?: ReadRef },
-        display: (row: T) => { data: unknown; partial: boolean }) => {
-        let after: ReadWindow["after"], selected = 0, complete = false;
+        display: (row: T) => { data: unknown; partial: boolean }, selectedBefore = 0, skipCaptureIds: ReadonlySet<number> = new Set()) => {
+        let after: ReadWindow["after"], selected = selectedBefore, complete = false;
         for (let pageNumber = 0; pageNumber < MAX_PAGES; pageNumber++) {
           guard();
           if (options.nativeSession && options.timeRemaining && options.timeRemaining() <= 0) throw new Error("brief deadline");
           const page = read({ project, limit: PAGE_ROWS, after });
           for (const row of page.rows) {
             if ((row as { project?: unknown }).project !== project) { coverage[section] = "partial"; continue; }
+            if (section === "capture" && skipCaptureIds.has((row as { id: number }).id)) continue;
             // #173: subagent capture stays searchable but never enters the session brief.
             if (section === "capture" && (row as { subagent?: unknown }).subagent === true) continue;
             if (!await screen(row)) continue;
@@ -249,7 +250,18 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
         }
         const capture = new CaptureStore({ memoryDir: base, project, cwd, ...(options.nativeSession || options.measureOnly ? { readOnly: true, busyTimeoutMs: options.measureOnly ? 1000 : 0, maxReadRows: 128, recentReadRows: true } : {}) }); closers.push(() => capture.close());
         if (capture.recentReadTruncated) coverage.capture = "partial";
-        await recent("capture", window => capture.readPage(window), captureDisplay);
+        const summaries = capture.readBriefSummaries(), summaryIds = new Set<number>();
+        if (summaries.partial) coverage.capture = "partial";
+        let selectedSummaries = 0;
+        for (const row of summaries.rows) {
+          if (row.project !== project) continue;
+          if (row.subagent === true) { summaryIds.add(row.id); continue; }
+          if (selectedSummaries >= 2) break;
+          if (!await screen(row)) { summaryIds.add(row.id); continue; }
+          summaryIds.add(row.id);
+          if (await add("capture", captureDisplay(row), false)) selectedSummaries++;
+        }
+        await recent("capture", window => capture.readPage(window), captureDisplay, selectedSummaries, summaryIds);
       });
       guard();
       const context = [header(coverage, reasons), ...(candidateLine ? [candidateLine] : []), ...lines].join("\n");

package/src/setup-drift.ts

@@ -0,0 +1,217 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import type { SetupTarget } from "./setup.ts";
+import { SETUP_CONFIG_BYTES } from "./setup-toml.ts";
+import { managedAfter, managedHookEntries, mcpRecord, type ConfigImage } from "./setup-owned.ts";
+import { resolveSetupPaths, type SetupEnvironment } from "./setup-paths.ts";
+import { HOOK_EVENTS } from "./hook-contract.ts";
+import { realPath } from "./memory/platform.ts";
+
+export type SetupDriftStatus = "ok" | "attention" | "skipped" | "unavailable";
+export interface SetupDriftEntry {
+  target: SetupTarget;
+  file: string;
+  entry: string;
+  reason: string;
+  kind: "drift" | "unavailable" | "review-needed";
+  expectedFile?: string;
+}
+export interface SetupDriftReport {
+  status: SetupDriftStatus;
+  checked: number;
+  entries: SetupDriftEntry[];
+  reason?: string;
+}
+
+interface ReceiptChange { key: string; path: string; before: ConfigImage; after: ConfigImage }
+interface Receipt { version: 1; target: SetupTarget; phase: "prepared" | "applied"; changes: ReceiptChange[] }
+const JOURNAL_BYTES = 12 * SETUP_CONFIG_BYTES;
+// ponytail: at most 32 MiB of receipt/config input per doctor call; use metadata-only receipts before widening.
+const READ_BYTES = 32 * 1024 * 1024;
+const hash = (value: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const plain = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+
+function safeImage(path: string, max = SETUP_CONFIG_BYTES, budget?: { remaining: number }): ConfigImage {
+  let cursor = resolve(path);
+  while (true) {
+    try { if (lstatSync(cursor).isSymbolicLink()) throw Error("unsafe"); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    const parent = dirname(cursor); if (parent === cursor) break; cursor = parent;
+  }
+  let fd: number;
+  try { fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { bytes: null, mode: 0o600 }; throw error; }
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1 || before.size > max || budget && before.size > budget.remaining) throw Error("unsafe");
+    if (budget) budget.remaining -= before.size;
+    const data = Buffer.alloc(before.size + 1), size = readSync(fd, data, 0, data.length, 0), after = fstatSync(fd);
+    if (size !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ino !== before.ino || after.dev !== before.dev) throw Error("changed");
+    return { bytes: data.subarray(0, size).toString("base64"), mode: before.mode & 0o777 };
+  } finally { closeSync(fd); }
+}
+
+function parseImage(value: unknown): ConfigImage {
+  if (!plain(value) || !Number.isInteger(value.mode) || Number(value.mode) < 0 || Number(value.mode) > 0o777) throw Error("invalid receipt");
+  if (value.bytes !== null && (typeof value.bytes !== "string" || value.bytes.length > 2 * SETUP_CONFIG_BYTES || Buffer.from(value.bytes, "base64").toString("base64") !== value.bytes)) throw Error("invalid receipt");
+  return { bytes: value.bytes as string | null, mode: Number(value.mode) };
+}
+
+function parseReceipt(value: unknown, target: SetupTarget, expectedPaths: readonly string[]): Receipt {
+  if (!plain(value) || value.version !== 1 || value.target !== target || !/^[a-f0-9]{64}$/.test(String(value.intent)) || !["applied", "prepared"].includes(String(value.phase)) || !Array.isArray(value.changes) || value.changes.length !== expectedPaths.length && !(target === "jcode" && value.changes.length === 1)) throw Error("invalid receipt");
+  const changes: ReceiptChange[] = [];
+  for (let index = 0; index < value.changes.length; index++) {
+    const item: unknown = value.changes[index];
+    if (!plain(item) || item.key !== `${target}:${index}` || typeof item.path !== "string" || !isAbsolute(item.path) || item.path.length > 4096 || item.path.includes("\0")) throw Error("invalid receipt");
+    changes.push({ key: `${target}:${index}`, path: item.path, before: parseImage(item.before), after: parseImage(item.after) });
+  }
+  return { version: 1, target, phase: value.phase as Receipt["phase"], changes };
+}
+
+function workspaceRoot(cwd: string): string | undefined {
+  let current = realPath(resolve(cwd));
+  while (true) {
+    try {
+      const marker = lstatSync(join(current, ".git"));
+      if (marker.isDirectory() || marker.isFile()) return realPath(current);
+    } catch { /* Continue toward the filesystem root. */ }
+    const parent = dirname(current); if (parent === current) return undefined; current = parent;
+  }
+}
+
+const shellQuote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+function launch(record: unknown): string | undefined {
+  if (!plain(record) || typeof record.command !== "string" || !Array.isArray(record.args) || !record.args.every(arg => typeof arg === "string")) return undefined;
+  const args = [...record.args as string[]];
+  if (args.at(-1) === "mcp") args.pop();
+  return [shellQuote(record.command), ...args.map(arg => arg === "--smol" ? arg : shellQuote(arg))].join(" ");
+}
+
+function expectedManagedHookCommands(target: SetupTarget, after: ConfigImage): { event: string; command: string }[] {
+  if (["jcode", "opencode", "gemini", "agy"].includes(target)) return [];
+  const base = launch(mcpRecord(target, after));
+  if (!base) return [];
+  if (target === "claude") return HOOK_EVENTS.map(event => ({ event, command: `${base} hook ${event}` }));
+  if (target === "pi") return [];
+  return [{ event: "SessionEnd", command: `${base} ingest ${target}${target === "codex" || target === "kimi" || target === "qwen" ? " --json" : ""}` }];
+}
+
+/** Codex stores trust in config.toml under hooks.state, keyed by hooks.json path and handler position. */
+function codexMissingTrust(hooksPath: string, hooksImage: ConfigImage, configImage: ConfigImage, expected: { event: string; command: string }[]): string[] {
+  if (hooksImage.bytes === null || configImage.bytes === null) return [];
+  const hooksDocument: unknown = JSON.parse(Buffer.from(hooksImage.bytes, "base64").toString("utf8"));
+  const configDocument: unknown = Bun.TOML.parse(Buffer.from(configImage.bytes, "base64").toString("utf8"));
+  if (!plain(hooksDocument) || !plain(configDocument)) throw Error("invalid Codex configuration");
+  const groups: unknown[] = plain(hooksDocument.hooks) && Array.isArray(hooksDocument.hooks.SessionEnd) ? hooksDocument.hooks.SessionEnd : [];
+  const stateRoot: Record<string, unknown> = plain(configDocument.hooks) && plain(configDocument.hooks.state) ? configDocument.hooks.state : Object.create(null);
+  const wanted = new Set(expected.filter(row => row.event === "SessionEnd").map(row => row.command));
+  const missing: string[] = [];
+  for (let groupIndex = 0; groupIndex < groups.length; groupIndex++) {
+    const group = groups[groupIndex]; if (!plain(group) || !Array.isArray(group.hooks)) continue;
+    for (let handlerIndex = 0; handlerIndex < group.hooks.length; handlerIndex++) {
+      const handler = group.hooks[handlerIndex];
+      if (!plain(handler) || typeof handler.command !== "string" || !wanted.has(handler.command)) continue;
+      const key = `${hooksPath}:session_end:${groupIndex}:${handlerIndex}`;
+      const state = stateRoot[key];
+      // Presence is not proof that the stored digest still matches; amem only detects a missing record.
+      if (!plain(state) || typeof state.trusted_hash !== "string" || !state.trusted_hash || state.enabled === false) missing.push(key);
+    }
+  }
+  return missing;
+}
+
+function entry(target: SetupTarget, file: string, name: string, reason: string, kind: SetupDriftEntry["kind"]): SetupDriftEntry {
+  return { target, file, entry: name, reason, kind };
+}
+
+/** Read setup receipts and only the resolver-selected native config files. This function never writes. */
+export function readSetupDrift(options: { home: string; env?: SetupEnvironment; cwd?: string }): SetupDriftReport {
+  const env = options.env ?? process.env;
+  const root = workspaceRoot(options.cwd ?? process.cwd());
+  let resolved: ReturnType<typeof resolveSetupPaths>;
+  try { resolved = resolveSetupPaths(env, undefined, root); }
+  catch { return { status: "unavailable", checked: 0, entries: [], reason: "setup paths could not be resolved" }; }
+  const entries: SetupDriftEntry[] = [], budget = { remaining: READ_BYTES };
+  let checked = 0, unavailable = false, anyReceipt = false;
+  for (const target of Object.keys(resolved.paths) as SetupTarget[]) {
+    const expectedPaths = resolved.paths[target];
+    if (!expectedPaths.length) continue;
+    const receiptPath = join(options.home, "setup", target === "agy" ? `agy-${hash(root)}.json` : `${target}.json`);
+    let raw: ConfigImage;
+    try { raw = safeImage(receiptPath, JOURNAL_BYTES, budget); }
+    catch {
+      entries.push(entry(target, receiptPath, "receipt", "receipt cannot be read safely or exceeds the read bound", "unavailable")); unavailable = true;
+      continue;
+    }
+    if (raw.bytes === null) continue;
+    let receipt: Receipt;
+    try {
+      const value: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(raw.bytes, "base64")));
+      if (plain(value) && value.target === target && value.phase === "prepared") continue;
+      anyReceipt = true; checked++;
+      receipt = parseReceipt(value, target, expectedPaths);
+    } catch {
+      entries.push(entry(target, receiptPath, "receipt", "receipt is invalid or unavailable", "unavailable")); unavailable = true; continue;
+    }
+    // Never open a manifest-selected file before the full set of paths matches the shared resolver.
+    const mismatches = receipt.changes.filter((change, index) => change.path !== expectedPaths[index]);
+    if (mismatches.length) {
+      for (const change of mismatches) entries.push({ ...entry(target, change.path, change.key,
+        "manifest path no longer matches the resolved target; referenced files were not opened", "drift"),
+        expectedFile: expectedPaths[receipt.changes.indexOf(change)] });
+      continue;
+    }
+    const liveImages: (ConfigImage | undefined)[] = [];
+    for (const change of receipt.changes) {
+      let current: ConfigImage;
+      try { current = safeImage(change.path, SETUP_CONFIG_BYTES, budget); }
+      catch {
+        liveImages.push(undefined);
+        entries.push(entry(target, change.path, change.key, "resolved configuration cannot be read safely", "unavailable")); unavailable = true; continue;
+      }
+      liveImages.push(current);
+      const isMcp = change.key === `${target}:0`;
+      if (isMcp) {
+        const name = target === "codex" ? "mcp_servers.amem" : target === "jcode" ? "servers.amem" : target === "opencode" ? "mcp.amem" : "mcpServers.amem";
+        try {
+          const expected = mcpRecord(target, change.after);
+          if (expected === undefined) throw Error("receipt has no MCP registration");
+          if (!isDeepStrictEqual(expected, mcpRecord(target, current))) entries.push(entry(target, change.path, name, "managed MCP registration is missing or changed", "drift"));
+        } catch { entries.push(entry(target, change.path, name, "managed MCP registration could not be checked", "unavailable")); unavailable = true; }
+      }
+      const hasHookSurface = target === "qwen" && change.key === `${target}:0` || target === "claude" && change.key === `${target}:1` || target === "codex" && change.key === `${target}:1` || target === "kimi" && change.key === `${target}:1`;
+      if (hasHookSurface) {
+        try {
+          const expected = expectedManagedHookCommands(target, receipt.changes[0]!.after);
+          for (const row of managedHookEntries(target, change.before, change.after, current, expected)) {
+            if (!row.present) entries.push(entry(target, change.path, row.entry, "managed hook is missing or changed", "drift"));
+          }
+        } catch { entries.push(entry(target, change.path, "hooks", "managed hooks could not be checked", "unavailable")); unavailable = true; }
+      }
+      if (target === "pi" && change.key === "pi:1" && !managedAfter(target, 1, change.before, change.after, current)) entries.push(entry(target, change.path, "session_shutdown extension", "managed hook extension is missing or changed", "drift"));
+      // #203: jcode's capture hooks are command elements in config.toml [hooks]; a pre-#203 receipt has no such change.
+      if (target === "jcode" && change.key === "jcode:1" && !managedAfter(target, 1, change.before, change.after, current)) entries.push(entry(target, change.path, "hooks", "managed hook is missing or changed", "drift"));
+      if (target === "codex" && change.key === "codex:1") {
+        // Codex owns trust state. Doctor checks only whether an entry exists; it never writes or verifies trusted_hash.
+        const runtimePaths = resolved.redirects.some(row => row.target === "codex") ? resolved.legacyPaths.codex : expectedPaths;
+        const configPath = runtimePaths[0]!, hooksPath = runtimePaths[1]!;
+        try {
+          const configImage = configPath === receipt.changes[0]!.path ? liveImages[0] : safeImage(configPath, SETUP_CONFIG_BYTES, budget);
+          if (!configImage) throw Error("Codex config is unavailable");
+          const hookImage = hooksPath === change.path ? current : safeImage(hooksPath, SETUP_CONFIG_BYTES, budget);
+          const expected = expectedManagedHookCommands(target, receipt.changes[0]!.after);
+          if (hooksPath !== change.path && (hookImage.bytes === null || configImage.bytes === null || managedHookEntries(target, change.before, change.after, hookImage, expected).some(row => !row.present))) {
+            entries.push(entry(target, hooksPath, "hooks.SessionEnd", "personal hook source is waiting for the managed runtime copy; start a new Orca session, then review the hook", "review-needed"));
+          } else {
+            for (const key of codexMissingTrust(hooksPath, hookImage, configImage, expected)) entries.push(entry(target, configPath, `hooks.state.${key}`, "Codex hook has no enabled trust record; treat it as untrusted and review it in Codex", "review-needed"));
+          }
+        } catch { entries.push(entry(target, configPath, "hooks.state", "Codex hook trust could not be checked safely", "unavailable")); unavailable = true; }
+      }
+    }
+  }
+  const status: SetupDriftStatus = entries.some(value => value.kind === "drift" || value.kind === "review-needed") ? "attention"
+    : unavailable ? "unavailable" : anyReceipt ? "ok" : "skipped";
+  return { status, checked, entries, ...(!anyReceipt && !entries.length ? { reason: "no applied setup receipts found" } : {}) };
+}