@staix/agent-mem 0.17.0 → 0.19.0

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 } : {}) });
@@ -1094,6 +1095,7 @@ export class MemoryStore {
     for (const store of this.readStores()) store.syncSearchIndex();
     const now = this.now();
     const hits: SearchHit[] = [];
+    let captureShard: string | undefined, captureNotBefore: string | undefined;
     // The project filter runs inside the FTS query (its rows plus shared ones), so a busy sibling project can never
     // starve this project's LIMIT.
     // Superseded, forgotten, expired and `since` rows are filtered after FTS, so a fixed candidate cap could be filled
@@ -1122,13 +1124,17 @@ export class MemoryStore {
     // #15 D4/T1: the capture tier is project-scoped; without a project key there is no shard to recall from.
     if (f.includeCapture !== false && f.project) {
       const shard = shardMachineDir(this.memoryBaseDir, resolveAlias(this.memoryBaseDir, f.project), this.machine.id);
+      captureShard = shard;
       // The retention cutoff and `since` run in the capture query, so neither expired nor old rows take a candidate slot.
       // An out-of-range retention_days gives no cutoff rather than failing the whole search (eviction keeps its own check).
       const override = f.captureRetentionDays, days = typeof override === "number" && Number.isFinite(override) && override > 0 ? override : readCaptureConfig(shard, this.memoryBaseDir).retentionDays;
       const cutoff = new Date(now - days * 24 * 3600_000);
       const retained = Number.isFinite(cutoff.getTime()) ? cutoff.toISOString() : undefined;
       const since = f.since && Number.isFinite(Date.parse(f.since)) ? new Date(Date.parse(f.since)).toISOString() : undefined;
-      for (const { row, rank } of captureSearch(shard, q, Math.max(limit * 4, 32), since && (!retained || since > retained) ? since : retained)) {
+      captureNotBefore = since && (!retained || since > retained) ? since : retained;
+      // First reproduce the old unweighted BM25 candidate window. Only these baseline capture slots may change;
+      // curated membership and positions are not affected by conversational weighting or session collapse.
+      for (const { row, rank } of captureSearch(shard, q, Math.max(limit * 4, 32), captureNotBefore, { weightEvents: false, onePerSession: false })) {
         const selected: SearchHit = { source: "capture", score: rankedScore(rank, "capture", row.at, now), capture: row };
         if (f.explain) selected.scoreDetails = rankedScoreDetails("capture", rank, "capture", row.at, now, selected.score);
         hits.push(selected);
@@ -1144,7 +1150,23 @@ export class MemoryStore {
     }
     const ref = (h: SearchHit): string => h.view?.id ?? String(h.capture?.id ?? 0).padStart(12, "0");
     hits.sort((a, b) => b.score - a.score || ref(a).localeCompare(ref(b)));
-    return { engine: "fts5", hits: hits.slice(0, limit) };
+    const baseline = hits.slice(0, limit), captureSlots = baseline.filter(hit => hit.source === "capture").length;
+    if (!captureSlots || !captureShard) return { engine: "fts5", hits: baseline };
+    // Stream session representatives in complete weighted-score order; the legacy
+    // baseline above still owns noncapture slots and exposed scores remain unweighted.
+    const weighted = captureSearch(captureShard, q, captureSlots, captureNotBefore,
+      { weightEvents: true, onePerSession: true, now });
+    const replacements = weighted.map(({ row, rank }) => {
+      const score = rankedScore(rank, "capture", row.at, now), hit: SearchHit = { source: "capture", score, capture: row };
+      if (f.explain) hit.scoreDetails = rankedScoreDetails("capture", rank, "capture", row.at, now, score);
+      return hit;
+    });
+    let nextCapture = 0;
+    const selected = baseline.flatMap(hit => {
+      if (hit.source !== "capture") return [hit];
+      const replacement = replacements[nextCapture++]; return replacement ? [replacement] : [];
+    });
+    return { engine: "fts5", hits: selected };
   }
 
   /** Bring the derived FTS copy level with the curated rows when a prune, a crash, a lock or a rebuild drifted them apart. */
@@ -1612,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

@@ -17,6 +17,8 @@ import type { MemoryStore, View } from "./memory/store.ts";
 import { WorkListStore, type WorkListFields, type WorkListView } from "./memory/work-lists.ts";
 
 export interface BriefOptions { cwd: string; base?: string; project?: string; maxTokens?: number; policy?: StandalonePolicyOptions;
+  /** Repository-less hosts use only machine policy and omit the repo section, even if their home lies inside a repository. */
+  repository?: false;
   /** Host-only monotonic budget probe. The native hook still owns the hard child deadline. */
   timeRemaining?: () => number;
   /** Host-only parent CLI path: precomputed owned process identity and zero-wait stores. */
@@ -26,7 +28,7 @@ export interface BriefOptions { cwd: string; base?: string; project?: string; ma
   /** Test seam for the pending-candidate line's clock. */
   now?: () => number;
   /**
-   * `amem doctor` only (F15): size the brief without writing to the memory home. No reader lease is taken. The caller supplies the two sections that would otherwise
+   * Read-only diagnostic/console projection: build the brief without writing to the memory home. No reader lease is taken. The caller supplies the two sections that would otherwise
    * open a store read-write: `curated` is a store opened on a private copy of the logs (absent: the project has no curated notes, an empty complete section) and
    * `workBase` is a private base holding a copy of the project's and its aliases' work logs (absent: the work section is `unavailable`, never claimed complete).
    * The capture section opens this machine's capture database read-only, and only when it exists.
@@ -104,7 +106,7 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
   try {
     if (options.nativeSession && typeof options.timeRemaining !== "function") return result;
     const cwdForConfig = options.cwd, baseForConfig = canonicalPath(options.base ?? memoryHome());
-    const configuredBrief = loadAmemConfig(baseForConfig, repoConfigRoot(cwdForConfig)).config.briefBytes;
+    const configuredBrief = loadAmemConfig(baseForConfig, options.repository === false ? undefined : repoConfigRoot(cwdForConfig)).config.briefBytes;
     // A caller's explicit budget wins over the default; the person's configured budget can only lower either.
     const maximum = Math.min(options.maxTokens ?? DEFAULT_TOKENS, configuredBrief ?? Number.MAX_SAFE_INTEGER);
     if (!Number.isSafeInteger(maximum) || maximum < 1) return result;
@@ -112,7 +114,7 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
     const requested = options.project ?? memoryProjectKey(cwd, { repositoryIsolation: true }), project = resolveAlias(base, requested);
     // #15 T5: a project the person archived or forgot yields no brief at all, before any lease, store or screen is opened.
     if (projectState(base, project) !== "active") return result;
-    const policy = createStandalonePolicy(configuredPolicyOptions(base, cwd, options.policy)), release = options.measureOnly ? Object.assign(() => {}, { verify: () => {} }) : registerReaderLease(base, options.nativeSession ? { signature: options.nativeSession.signature, busyTimeoutMs: 0 } : undefined);
+    const policy = createStandalonePolicy(configuredPolicyOptions(base, options.repository === false ? undefined : cwd, options.policy)), release = options.measureOnly ? Object.assign(() => {}, { verify: () => {} }) : registerReaderLease(base, options.nativeSession ? { signature: options.nativeSession.signature, busyTimeoutMs: 0 } : undefined);
     closers.push(release);
     const selection = readSelector(base).revision;
     const sharded = !!lstatSync(join(base, "shards.json"), { throwIfNoEntry: false });
@@ -138,7 +140,7 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
     const coverage: BriefResult["coverage"] = { work: "complete", curated: "complete", capture: "complete" };
     // #15 T4: the bound repository's `.amem/log.jsonl`, only when the repository IS this project (AC3). The `lstat` probe comes FIRST and on every path (the SessionStart
     // worker builds this brief without `nativeSession`): a repository with no `.amem/log.jsonl` at or above the cwd costs a few syscalls and no git process.
-    const repoRoot = !repoLogNearby(cwd) ? undefined : options.projectFromCwd ? nearestRepoRootWithLog(cwd) : boundRepoRoot(cwd, base, project);
+    const repoRoot = options.repository === false || !repoLogNearby(cwd) ? undefined : options.projectFromCwd ? nearestRepoRootWithLog(cwd) : boundRepoRoot(cwd, base, project);
     if (repoLogPresent(repoRoot)) coverage.repo = "complete";
     const lines: string[] = [];
     const reasons: Partial<Record<Section, string>> = {};
@@ -150,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;
@@ -179,7 +181,7 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
       await run("work", async () => {
         const measured = options.measureOnly;
         if (measured && !measured.workBase) { coverage.work = "unavailable"; return; }
-        if (measured && !lstatSync(join(shardDir(measured.workBase!, project), "work", "log"), { throwIfNoEntry: false })) return;   // no work log: the real brief shows an empty list
+        if (measured && ![project, ...aliases].some(key => lstatSync(join(shardDir(measured.workBase!, key), "work", "log"), { throwIfNoEntry: false }))) return;   // no work log: the real brief shows an empty list
         const work = new WorkListStore({ base: measured?.workBase ?? base, project, aliases, policy: screen, ...(options.nativeSession ? { busyTimeoutMs: 0, timeRemaining: options.timeRemaining } : {}) }); closers.push(() => work.close());
         // Complete operation rows AND the composed view are screened before closed-item filtering or display caps.
         const views = await work.read(undefined, true); guard();
@@ -191,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;
@@ -247,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" } : {}) };
+}