@staix/agent-mem 0.18.0 → 0.19.0

package/src/hooks.ts

@@ -1,16 +1,18 @@
 import { fileURLToPath } from "node:url";
-import { resolveHookProjectAsync } from "./hook-project.ts";
-import { hookProcessSignature } from "./hook-native.ts";
+import { resolveHookProjectAsync, type HookProjectReceipt } from "./hook-project.ts";
+import { hookProcessSignature, type HookNativeUsage } from "./hook-native.ts";
 import { resolveAlias } from "./memory/aliases.ts";
-import { hookPeakRssKB } from "./hook-resources.ts";
+import { combineRssSources, countedRssSources, emptyRssSources, hookRssReading, rssSource, type HookRssSources } from "./hook-resources.ts";
+import { HookWorkerRss } from "./hook-rss-wire.ts";
 import { appendMetrics, captureDropSummary } from "./memory/metrics.ts";
-import { stageHookCapture, hookCaptureScope, HookSpoolFull, type PendingHookCapture } from "./hook-spool.ts";
+import { stageHookCapture, drainHookCaptures, hookCaptureScope, quarantineHookScope, HookSpoolFull, type HookAgent, type PendingHookCapture } from "./hook-spool.ts";
+import { jcodeHookCapture } from "./hook-jcode.ts";
 import { memoryHome } from "./memory/home.ts";
 import { canonicalPath, realPath } from "./memory/platform.ts";
 import { createStandalonePolicy, type MemoryPolicy, type StandalonePolicyOptions } from "./memory/policy.ts";
 import { configuredPolicyOptions, loadAmemConfig, repoConfigRoot } from "./memory/config.ts";
 
-import { HOOK_EVENTS, HOOK_INPUT_BYTES, HOOK_CONTEXT_BYTES, HOOK_OUTPUT_BYTES } from "./hook-contract.ts";
+import { HOOK_EVENTS, HOOK_INPUT_BYTES, HOOK_CONTEXT_BYTES, HOOK_OUTPUT_BYTES, isHookTranscriptProgress, type HookTranscriptProgress } from "./hook-contract.ts";
 export { HOOK_EVENTS, HOOK_INPUT_BYTES, HOOK_CONTEXT_BYTES, HOOK_OUTPUT_BYTES, type HookEvent } from "./hook-contract.ts";
 // Leave 10ms of the external 150ms R2 budget for teardown and the metrics write.
 const HANDLER_MS = 140;
@@ -25,7 +27,7 @@ function handlerMs(host?: HookHostPorts): number {
   if (!Number.isSafeInteger(value) || value < 1 || value > 10_000) throw new TypeError("invalid hook host deadline");
   return value;
 }
-export interface HookOptions { cwd: string; base?: string; policy?: StandalonePolicyOptions; maxTokens?: number; startedAt?: number }
+export interface HookOptions { cwd: string; base?: string; policy?: StandalonePolicyOptions; maxTokens?: number; startedAt?: number; agent?: HookAgent }
 export interface HookReceipt {
   captured: boolean; skipped: boolean;
   /** Screened capture is durable but still awaits project-bound replay. */
@@ -66,62 +68,111 @@ async function before<T>(work: Promise<T>, deadline: number): Promise<T | undefi
 }
 const publicBefore = async (policy: MemoryPolicy, value: unknown, deadline: number) => await before(policy.screen(value), deadline) === true;
 
-async function boundedOutput(stream: ReadableStream<Uint8Array>): Promise<string | undefined> {
-  const reader = stream.getReader(), chunks: Uint8Array[] = []; let length = 0;
+async function boundedOutput(stream: ReadableStream<Uint8Array>, onRss?: (value: unknown) => void, onTranscript?: (value: unknown) => void): Promise<string | undefined> {
+  const reader = stream.getReader(), decoder = new TextDecoder("utf-8", { fatal: true });
+  let length = 0, pending = "", body = "";
+  const line = (text: string) => {
+    if (!text) return;
+    const value = JSON.parse(text) as { rss?: unknown; transcript?: unknown };
+    if (onRss && Object.hasOwn(value, "rss")) onRss(value.rss);
+    else if (onTranscript && Object.hasOwn(value, "transcript")) onTranscript(value.transcript);
+    else { if (body) throw new Error("worker output bound"); body = text; }
+  };
   try {
     for (;;) {
       const next = await reader.read(); if (next.done) break;
       if (length + next.value.byteLength > HOOK_OUTPUT_BYTES) return undefined;
-      chunks.push(next.value); length += next.value.byteLength;
+      length += next.value.byteLength; pending += decoder.decode(next.value, { stream: true });
+      for (;;) { const at = pending.indexOf("\n"); if (at < 0) break; line(pending.slice(0, at)); pending = pending.slice(at + 1); }
     }
-    return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
-  } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+    pending += decoder.decode(); if (pending) line(pending);
+    return body;
+  } catch { return undefined; }
+  finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+}
+
+/** Native handles always belong to the CLI that writes the metric, never a killable worker. */
+async function parentProject(options: HookOptions, base: string, deadline: number) {
+  const cwd = realPath(options.cwd);
+  const scope = hookCaptureScope(cwd, base);
+  const usage: HookNativeUsage = { rssKB: 0, rawRssKB: 0, rssSources: emptyRssSources() };
+  let project: string | undefined, receipt: HookProjectReceipt | undefined;
+  try {
+    project = await resolveHookProjectAsync({ cwd, base, scope, timeRemaining: () => deadline - performance.now(), maintainCache: true, prefetch: true,
+      onResolved: value => { receipt = value; } }, usage);
+  } catch { /* All native finally/reap barriers have completed before this returns. */ }
+  if (project === undefined && scope !== undefined) try { quarantineHookScope({ cwd, base, scope }); }
+  catch { /* Failed maintenance cannot change native fail-open behavior or its accounting. */ }
+  return { cwd, scope, project, receipt, usage };
 }
 
-/** Native metadata and cold indexes are bounded in a short-lived owned child, never a resident worker.
+/** Only capture work uses a short-lived owned child; native handles remain in this CLI.
  * Host callbacks cannot cross this boundary; a host needing them calls sessionStartBrief in-process instead. */
-async function hookWorker(options: HookOptions, base: string, deadline: number, pending: PendingHookCapture, event: string): Promise<{ context: string; rssKB: number; rawRssKB: number; captured: boolean; valid: boolean }> {
+async function hookWorker(options: HookOptions, base: string, deadline: number, pending: PendingHookCapture, event: string, transcript?: unknown): Promise<{ context: string; rssKB: number; rawRssKB: number; captured: boolean; valid: boolean; rssSources?: HookRssSources; transcript?: HookTranscriptProgress }> {
   const workDeadline = deadline - WORKER_CLEANUP_MS;
   if (options.policy?.host || workDeadline - performance.now() < 5) return { context: unavailable, rssKB: 0, rawRssKB: 0, captured: false, valid: false };
-  const configuredBrief = loadAmemConfig(base, repoConfigRoot(options.cwd)).config.briefBytes;
-  const maxTokens = Math.min(HOOK_CONTEXT_BYTES, configuredBrief ?? HOOK_CONTEXT_BYTES, Math.max(1, options.maxTokens ?? HOOK_CONTEXT_BYTES));
-  // The worker reads the configuration itself (same base, same cwd), so it screens with exactly the policy the parent did.
-  const payload = JSON.stringify({ cwd: options.cwd, base, current: pending.name, event, maxTokens, ownedGroup: true, deadlineAt: performance.timeOrigin + workDeadline,
-    policy: { denyPaths: options.policy?.denyPaths, piiPatterns: options.policy?.piiPatterns } });
-  const child = Bun.spawn([process.execPath, "--smol", fileURLToPath(new URL("./session-brief-worker.ts", import.meta.url))],
-    { cwd: options.cwd, env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", AMEM_HOME: base }, detached: true, stdin: Buffer.from(payload), stdout: "pipe", stderr: "ignore" });
-  let exited = false;
-  const result = { context: unavailable, rssKB: 0, rawRssKB: 0, captured: false, valid: false };
-  const exit = child.exited.then(code => { exited = true; return code; });
-  const stop = () => {
-    if (exited) return;
-    // The still-live leader is the detached process we just spawned, so its group is ours.
-    // Kill its native metadata children too; never signal a group after observing leader exit.
-    try { process.kill(-child.pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch { /* Already exited. */ } }
-  };
-  let timer: ReturnType<typeof setTimeout> | undefined;
+  const metadata = await parentProject(options, base, workDeadline);
+  if (!metadata.receipt && transcript === undefined || workDeadline - performance.now() < 5) return { context: unavailable, ...metadata.usage, captured: false, valid: false, ...(transcript !== undefined ? { transcript: { stopReason: "deadline" as const } } : {}) };
+  const result = { context: unavailable, ...metadata.usage, captured: false, valid: false,
+    rssSources: combineRssSources(metadata.usage.rssSources), transcript: undefined as HookTranscriptProgress | undefined };
+  let owned: ReturnType<typeof Bun.spawn> | undefined, exited = false;
   try {
-    const answer = await Promise.race([
-      Promise.all([exit, boundedOutput(child.stdout)]),
-      new Promise<undefined>(resolve => { timer = setTimeout(() => { stop(); resolve(undefined); }, Math.max(1, workDeadline - performance.now())); }),
-    ]);
-    if (!answer || !answer[1]) return result;
-    const parsed = JSON.parse(answer[1]) as { context?: unknown; captured?: unknown; valid?: unknown; complete?: unknown; rssKB?: unknown };
-    if (parsed.complete !== true) return result;
-    if (typeof parsed.rssKB === "number" && Number.isSafeInteger(parsed.rssKB) && parsed.rssKB > 0) result.rssKB = parsed.rssKB;
-    if (typeof parsed.context === "string" && Buffer.byteLength(parsed.context) <= maxTokens) result.context = parsed.context;
-    result.captured = parsed.captured === true; result.valid = parsed.valid === true;
-    return result;
-  } catch { return result; }
+    const configuredBrief = loadAmemConfig(base, repoConfigRoot(options.cwd)).config.briefBytes;
+    const maxTokens = Math.min(HOOK_CONTEXT_BYTES, configuredBrief ?? HOOK_CONTEXT_BYTES, Math.max(1, options.maxTokens ?? HOOK_CONTEXT_BYTES));
+    // The worker reads the configuration itself (same base, same cwd), so it screens with exactly the policy the parent did.
+    const payload = JSON.stringify({ cwd: options.cwd, base, current: pending.name, event, identity: metadata.receipt, transcript, maxTokens, ownedGroup: true, deadlineAt: performance.timeOrigin + workDeadline,
+      policy: { denyPaths: options.policy?.denyPaths, piiPatterns: options.policy?.piiPatterns } });
+    const child = Bun.spawn([process.execPath, "--smol", fileURLToPath(new URL("./session-brief-worker.ts", import.meta.url))],
+      { cwd: options.cwd, env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", AMEM_HOME: base }, detached: true, stdin: Buffer.from(payload), stdout: "pipe", stderr: "ignore" });
+    owned = child;
+    result.rssSources.unavailable++;
+    const exit = child.exited.then(code => { exited = true; return code; });
+    const tracker = new HookWorkerRss(child.pid);
+    const output = boundedOutput(child.stdout, value => tracker.frame(value), value => {
+      if (!isHookTranscriptProgress(value)) throw new Error("worker transcript progress bound");
+      if (value.offset !== undefined && result.transcript?.offset !== undefined && value.offset < result.transcript.offset) throw new Error("worker transcript progress regressed");
+      result.transcript = { ...result.transcript, ...value };
+    });
+    const stop = () => {
+      if (exited) return;
+      tracker.captureLive();
+      // The still-live leader is the detached process we just spawned, so its group is ours.
+      // The capture-only worker owns no native helper; those handles were reaped in this parent.
+      try { process.kill(-child.pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch { /* Already exited. */ } }
+    };
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const answer = await Promise.race([
+        Promise.all([exit, output]),
+        new Promise<undefined>(resolve => { timer = setTimeout(() => { if (transcript !== undefined) result.transcript ??= { stopReason: "deadline" }; stop(); resolve(undefined); }, Math.max(1, workDeadline - performance.now())); }),
+      ]);
+      if (!answer || !answer[1]) return result;
+      const parsed = JSON.parse(answer[1]) as { context?: unknown; captured?: unknown; valid?: unknown; complete?: unknown; rssKB?: unknown; rssTelemetryValid?: unknown };
+      if (parsed.complete !== true) return result;
+      if (parsed.rssTelemetryValid !== true) tracker.invalidate();
+      if (typeof parsed.rssKB === "number" && Number.isSafeInteger(parsed.rssKB) && parsed.rssKB > 0) result.rssKB = parsed.rssKB;
+      if (typeof parsed.context === "string" && Buffer.byteLength(parsed.context) <= maxTokens) result.context = parsed.context;
+      result.captured = parsed.captured === true; result.valid = parsed.valid === true;
+      return result;
+    } catch { return result; }
+    finally {
+      if (timer) clearTimeout(timer);
+      stop();
+      await exit;
+      // Bun subprocess usage is bytes; process.resourceUsage below is KiB.
+      const workerRawKB = (child.resourceUsage()?.maxRSS ?? 0) / 1024;
+      result.rawRssKB = metadata.usage.rawRssKB + workerRawKB;
+      if (await output === undefined) tracker.invalidate();
+      const accounting = tracker.finish(workerRawKB);
+      result.rssKB = metadata.usage.rssKB + accounting.rssKB; result.rssSources = combineRssSources(metadata.usage.rssSources, accounting.rssSources);
+    }
+  } catch { result.valid = false; return result; }
   finally {
-    if (timer) clearTimeout(timer);
-    stop();
-    await exit;
-    // Bun subprocess usage is bytes; process.resourceUsage below is KiB.
-    result.rawRssKB = (child.resourceUsage()?.maxRSS ?? 0) / 1024;
-    // Darwin self samples can precede final residency; use the reaped peak as a floor.
-    // Linux wait4 inherits launcher high-water, so retain the proven per-image sampler there.
-    result.rssKB = process.platform === "darwin" ? Math.max(result.rssKB, result.rawRssKB) : result.rssKB || result.rawRssKB;
+    // Even setup or accounting failure after spawn cannot leave an owned image live.
+    if (owned) {
+      if (!exited) try { process.kill(-owned.pid, "SIGKILL"); } catch { try { owned.kill("SIGKILL"); } catch { /* Already gone. */ } }
+      await owned.exited;
+    }
   }
 }
 
@@ -143,7 +194,7 @@ async function sessionInParent(input: unknown, options: HookOptions, base: strin
   catch (error) { if (!(error instanceof HookSpoolFull)) throw error; full = true; }
   if (!pending && !full) return undefined;
   const cwd = realPath(options.cwd), scope = hookCaptureScope(cwd, base);
-  const remaining = () => deadline - performance.now(), usage = { rssKB: 0, rawRssKB: 0 };
+  const remaining = () => deadline - performance.now(), usage: HookNativeUsage = { rssKB: 0, rawRssKB: 0, rssSources: emptyRssSources() };
   const result = { context: unavailable, captured: false, valid: false, pending: !!pending, dropped: false, ...usage };
   if (remaining() <= 0) { result.dropped = !pending; return result; }
   if (sessionSource(input) === "resume") {
@@ -158,7 +209,7 @@ async function sessionInParent(input: unknown, options: HookOptions, base: strin
   try {
     // Independent native reads and module loading share the same deadline, not three serial cold starts.
     // Separate usage ports conservatively sum concurrent helper peaks instead of hiding overlap.
-    const projectUsage = { rssKB: 0, rawRssKB: 0 }, signatureUsage = { rssKB: 0, rawRssKB: 0 };
+    const projectUsage: HookNativeUsage = { rssKB: 0, rawRssKB: 0 }, signatureUsage: HookNativeUsage = { rssKB: 0, rawRssKB: 0 };
     // Reaping native groups and serializing the fail-open result stay inside the handler deadline.
     const nativeRemaining = () => remaining() - 15;
     const metadata = await Promise.allSettled([
@@ -168,6 +219,7 @@ async function sessionInParent(input: unknown, options: HookOptions, base: strin
     ] as const);
     usage.rssKB = projectUsage.rssKB + signatureUsage.rssKB;
     usage.rawRssKB = projectUsage.rawRssKB + signatureUsage.rawRssKB;
+    usage.rssSources = combineRssSources(projectUsage.rssSources, signatureUsage.rssSources);
     const [identity, owner, briefModule] = metadata;
     if (identity.status !== "fulfilled" || owner.status !== "fulfilled" || briefModule.status !== "fulfilled") throw new Error("hook metadata unavailable");
     const project = resolveAlias(base, identity.value);
@@ -185,20 +237,22 @@ async function sessionInParent(input: unknown, options: HookOptions, base: strin
     result.valid = result.context.length > 0;
     return result;
   } catch { result.dropped = !pending; return result; }
-  finally { result.rssKB = usage.rssKB; result.rawRssKB = usage.rawRssKB; }
+  finally { result.rssKB = usage.rssKB; result.rawRssKB = usage.rawRssKB; result.rssSources = usage.rssSources; }
 }
 
 /** A full pending tier must still be drainable. Recover bounded old records before retrying
  * publication; this path uses one helper too, and the current normalized event stays pending. */
 async function captureAndWork(event: string, input: unknown, options: HookOptions, base: string, deadline: number) {
   if (event === "SessionStart") return sessionInParent(input, options, base, deadline);
-  let result: Awaited<ReturnType<typeof hookWorker>> | undefined;
+  const transcript = (event === "Stop" || event === "SessionEnd") && input !== null && typeof input === "object" && "transcript_path" in input && typeof input.transcript_path === "string" ? input : undefined;
+  const work = (pending: PendingHookCapture) => hookWorker({ ...options, cwd: pending.cwd }, base, deadline, pending, event, transcript);
+  let result: Awaited<ReturnType<typeof work>> | undefined;
   let pending: PendingHookCapture | undefined;
   try { pending = await stageHookCapture(event, input, { ...options, base, deferAtCapacity: true }); }
   catch (error) {
     if (!(error instanceof HookSpoolFull)) throw error;
     const cwd = realPath(options.cwd);
-    result = await hookWorker({ ...options, cwd }, base, deadline, { name: "", receipt: "", cwd }, event);
+    result = await work({ name: "", receipt: "", cwd });
     try { pending = await stageHookCapture(event, input, { ...options, base, deferAtCapacity: true }); }
     catch (retryError) {
       // A concurrent publisher can refill the soft tier. Capture admission cannot discard
@@ -208,7 +262,7 @@ async function captureAndWork(event: string, input: unknown, options: HookOption
     }
   }
   if (!pending) return result ? { ...result, pending: false } : undefined;
-  result ??= await hookWorker({ ...options, cwd: pending.cwd }, base, deadline, pending, event);
+  result ??= await work(pending);
   return { ...result, pending: !result.captured };
 }
 
@@ -217,6 +271,8 @@ export async function runHook(event: string, input: unknown, options: HookOption
   const now = performance.now(), started = options.startedAt !== undefined && Number.isFinite(options.startedAt) && options.startedAt <= now ? options.startedAt : now;
   const deadline = started + handlerMs(host);
   let base: string | undefined, captured = false, childRssKB = 0, childRawRssKB = 0, pending = false, dropped = false;
+  let childSources = emptyRssSources();
+  let transcriptProgress: HookTranscriptProgress | undefined;
   try {
     base = canonicalPath(options.base ?? memoryHome());
     if (!(HOOK_EVENTS as readonly string[]).includes(event)) return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: true };
@@ -225,15 +281,17 @@ export async function runHook(event: string, input: unknown, options: HookOption
     const result = await captureAndWork(event, input, options, base, deadline - 3);
     if (!result) return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: true };
     captured = result.captured; pending = result.pending; dropped = "dropped" in result && result.dropped === true;
-    childRssKB = result.rssKB; childRawRssKB = result.rawRssKB;
+    childRssKB = result.rssKB; childRawRssKB = result.rawRssKB; childSources = result.rssSources ?? emptyRssSources();
+    transcriptProgress = "transcript" in result ? result.transcript : undefined;
     if (!result.valid) return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: true };
     if (event !== "SessionStart") return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: false };
     if (!await publicBefore(policy, { context: result.context }, deadline)) return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: false };
     return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: false, output: { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: result.context } } };
   } catch { return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: true }; }
   finally {
-    if (base) try { appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", wallMs: performance.now() - started,
-      rssMB: (hookPeakRssKB() + childRssKB) / 1024, rawRssMB: (process.resourceUsage().maxRSS + childRawRssKB) / 1024, ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]); } catch { /* Metrics never change the native tool outcome. */ }
+    if (base) try { const self = hookRssReading(); appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", wallMs: performance.now() - started,
+      rssMB: (self.kb + childRssKB) / 1024, rssSources: combineRssSources(rssSource(self), countedRssSources(childRssKB, childSources)), rssScope: "owned-images", rawRssMB: (process.resourceUsage().maxRSS + childRawRssKB) / 1024,
+      ...(transcriptProgress ? { transcriptOffset: transcriptProgress.offset, transcriptStopReason: transcriptProgress.stopReason } : {}), ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]); } catch { /* Metrics never change the native tool outcome. */ }
   }
 }
 
@@ -242,8 +300,18 @@ export async function hookMain(args: readonly string[], startedAt = performance.
   const deadlineMs = handlerMs(host);
   let cleanup: (() => Promise<void>) | undefined;
   let childRssKB = 0, childRawRssKB = 0, dropped = false;
+  let childSources = emptyRssSources();
+  let transcriptProgress: HookTranscriptProgress | undefined;
   try {
     if (args.length !== 1) return "";
+    if (args[0] === "jcode") {
+      // #203: jcode observers have no stdin and discard stdout; the event and its cwd arrive in the environment.
+      const jcode = jcodeHookCapture(process.env);
+      if (!jcode) return "";
+      const result = await captureAndWork(jcode.event, jcode.input, { cwd: jcode.cwd, agent: "jcode" }, canonicalPath(memoryHome()), startedAt + deadlineMs - 3);
+      if (result) { childRssKB = result.rssKB; childRawRssKB = result.rawRssKB; childSources = result.rssSources ?? emptyRssSources(); dropped = "dropped" in result && result.dropped === true; }
+      return "";
+    }
     const reader = Bun.stdin.stream().getReader();
     cleanup = async () => { await reader.cancel().catch(() => {}); reader.releaseLock(); };
     const chunks: Uint8Array[] = []; let length = 0;
@@ -260,7 +328,8 @@ export async function hookMain(args: readonly string[], startedAt = performance.
       const base = canonicalPath(memoryHome());
       const result = await captureAndWork(args[0]!, input, { cwd: process.cwd() }, base, startedAt + deadlineMs - 3);
       if (!result) return "";
-      childRssKB = result.rssKB; childRawRssKB = result.rawRssKB; dropped = "dropped" in result && result.dropped === true;
+      childRssKB = result.rssKB; childRawRssKB = result.rawRssKB; childSources = result.rssSources ?? emptyRssSources(); dropped = "dropped" in result && result.dropped === true;
+      transcriptProgress = "transcript" in result ? result.transcript : undefined;
       if (!result.valid || args[0] !== "SessionStart") return "";
       return JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: result.context } });
     }
@@ -269,8 +338,10 @@ export async function hookMain(args: readonly string[], startedAt = performance.
   finally {
     await cleanup?.();
     try {
+      const self = hookRssReading();
       appendMetrics(canonicalPath(memoryHome()), [{ at: new Date().toISOString(), kind: "hook", wallMs: performance.now() - startedAt,
-        rssMB: (hookPeakRssKB() + childRssKB) / 1024, rawRssMB: (process.resourceUsage().maxRSS + childRawRssKB) / 1024, ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]);
+        rssMB: (self.kb + childRssKB) / 1024, rssSources: combineRssSources(rssSource(self), countedRssSources(childRssKB, childSources)), rssScope: "owned-images", rawRssMB: (process.resourceUsage().maxRSS + childRawRssKB) / 1024,
+        ...(transcriptProgress ? { transcriptOffset: transcriptProgress.offset, transcriptStopReason: transcriptProgress.stopReason } : {}), ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]);
     } catch { /* Invalid input and unavailable homes still fail open. */ }
   }
 }

package/src/memory/candidates.ts

@@ -1,3 +1,4 @@
+import { assertFormatFloor } from "./formats.ts";
 import { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { chmodSync, mkdirSync } from "node:fs";
@@ -146,6 +147,7 @@ export class CandidateStore {
     if (options.reconcile?.aliases.length) this.reconcile = { canonical: options.reconcile.canonical, aliases: [...options.reconcile.aliases] };
     if (options.memoryDir !== undefined && options.home !== undefined) throw new Error("choose a home or an exact memory directory");
     this.dir = options.memoryDir ?? (options.home === undefined ? memoryHome() : join(options.home, "memory"));
+    assertFormatFloor(this.dir, "candidates");
     this.now = options.now ?? Date.now;
     mkdirSync(this.dir, { recursive: true, mode: 0o700 }); chmodSync(this.dir, 0o700);
     this.path = join(this.dir, "candidates.db");

package/src/memory/capture.ts

@@ -1,3 +1,4 @@
+import { assertFormatFloor } from "./formats.ts";
 import { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
 import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, opendirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -49,6 +50,7 @@ export const CAPTURE_EVICT_MAX_BATCHES = 4;
 /** Wall-time bound for one invocation's eviction: with the batch bound, an append stays inside R2 after a cap shrink. */
 export const CAPTURE_EVICT_MAX_MS = 25;
 export const CAPTURE_DRAIN_MAX_LINES = 1000;
+const BRIEF_SUMMARY_CANDIDATES = 32;
 const SPOOL = "spool.jsonl";
 const DRAINING = "spool.jsonl.draining";
 const SPOOL_DIR = "spool";
@@ -210,6 +212,7 @@ export class CaptureStore {
     const maxReadRows = opts.maxReadRows ?? 128;
     if (this.readOnly && (!Number.isSafeInteger(maxReadRows) || maxReadRows < 1 || maxReadRows >= Number.MAX_SAFE_INTEGER)) throw new Error("invalid capture read row bound");
     this.base = opts.memoryDir ?? memoryBase(opts.home);
+    assertFormatFloor(this.base, "capture");
     const machine = opts.machine ?? (this.readOnly ? this.existingMachine() : machineId(this.base).id);
     if (this.readOnly && !/^[a-f0-9]{16}$/.test(machine)) throw new Error("capture machine identity unavailable");
     this.requestedKey = opts.project;
@@ -288,6 +291,7 @@ export class CaptureStore {
       db.run("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
       // #173: additive nullable columns. Older readers use explicit or `SELECT *` column names and ignore extras.
       addAttributionColumns(db);
+      this.ensureBriefSummaryIndex(true);
       this.ensureFts();
     } catch (error) {
       if (!lockError(error)) { db.close(); throw error; }
@@ -383,6 +387,12 @@ export class CaptureStore {
   }
 
   private mcpReady = false;
+  private briefReady = false;
+  private prepareBriefSummaryIndex(): void {
+    if (this.readOnly || this.briefReady) return;
+    try { this.ensureBriefSummaryIndex(false); this.briefReady = true; }
+    catch { /* Optional summary coverage remains partial; query engines remain independent. */ }
+  }
   /** One-time MCP read cost only: hooks neither create this derived index nor scan history to fill it. */
   private ensureMcpFts(): boolean {
     if (this.readOnly) return !!this.db.query("SELECT 1 FROM sqlite_master WHERE name = 'mcp_fts' AND type = 'table'").get();
@@ -637,6 +647,41 @@ export class CaptureStore {
     return rows.map(toRow);
   }
 
+  /** Generic SQLite index maintenance also covers older writers sharing this file. */
+  private ensureBriefSummaryIndex(bounded: boolean): void {
+    if (this.db.query("SELECT 1 FROM sqlite_master WHERE name='rows_brief_summaries_v1' AND type='index'").get()) return;
+    const build = () => {
+      if (bounded) {
+        const count = (this.db.query("SELECT COUNT(*) AS n FROM (SELECT 1 FROM rows LIMIT 129)").get() as { n: number }).n;
+        if (count > 128) return;
+      }
+      this.db.run("CREATE INDEX IF NOT EXISTS rows_brief_summaries_v1 ON rows(project,at,id) WHERE event IN ('Recap','Compact') AND (subagent IS NULL OR subagent != 1)");
+    };
+    // Keep the small-store decision and build atomic against a concurrent older writer.
+    if (bounded) this.db.transaction(build).immediate(); else build();
+  }
+
+  /** Index reads return at most33 bodies. Legacy fallback reads at most128 recent rows. */
+  readBriefSummaries(limit = BRIEF_SUMMARY_CANDIDATES): { rows: CaptureRow[]; partial: boolean } {
+    this.checkReadBinding();
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > BRIEF_SUMMARY_CANDIDATES) throw new Error("invalid brief summary limit");
+    const indexed = !!this.db.query("SELECT 1 FROM sqlite_master WHERE name='rows_brief_summaries_v1' AND type='index'").get();
+    let rows: RawRow[], partial = false;
+    if (indexed) {
+      rows = this.db.query("SELECT * FROM rows INDEXED BY rows_brief_summaries_v1 WHERE project=? AND event IN ('Recap','Compact') AND (subagent IS NULL OR subagent != 1) ORDER BY at DESC,id DESC LIMIT ?")
+        .all(this.key, limit + 1) as RawRow[];
+    } else {
+      // ponytail: a large legacy store stays partial within128 rows until an off-hook
+      // query builds the partial index; never scan or build the history on a hook.
+      const hasSubagent = (this.db.query("PRAGMA table_info(rows)").all() as { name: string }[]).some(column => column.name === "subagent");
+      const subagent = hasSubagent ? " AND (subagent IS NULL OR subagent != 1)" : "";
+      rows = this.db.query(`SELECT * FROM (SELECT * FROM rows INDEXED BY rows_at ORDER BY at DESC,id DESC LIMIT 128) WHERE project=? AND event IN ('Recap','Compact')${subagent} ORDER BY at DESC,id DESC LIMIT ?`)
+        .all(this.key, limit + 1) as RawRow[];
+      partial = this.db.query("SELECT id FROM rows INDEXED BY rows_at ORDER BY at DESC,id DESC LIMIT 129").all().length > 128;
+    }
+    return { rows: rows.slice(0, limit).map(toRow), partial: partial || rows.length > limit };
+  }
+
   /** Exact-project, bounded body pages; MCP screens before filling its public candidate window. */
   readPage(window: ReadWindow & { query?: string; match?: "substring" }): { rows: CaptureRow[]; next?: ReadRef; engine?: "fts5" | "substring" } {
     this.checkReadBinding();
@@ -645,6 +690,7 @@ export class CaptureStore {
       if (window.query !== undefined) throw new Error("recent capture brief does not support query indexes");
       where.push("id IN (SELECT value FROM json_each(?))"); bind.push(JSON.stringify(this.recentReadIds));
     }
+    if (window.query !== undefined) this.prepareBriefSummaryIndex();
     const engine = window.query === undefined ? undefined : window.match !== "substring" && this.ensureMcpFts() ? "fts5" : "substring";
     const plan = captureReadPlan(window, engine, where, bind);
     if (!plan) return { rows: [], engine };

package/src/memory/catalog.ts

@@ -1,4 +1,5 @@
 import { Database } from "bun:sqlite";
+import { indexFileName } from "./index-file.ts";
 import { chmodSync, existsSync, lstatSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { memoryBase } from "./home.ts";
@@ -48,7 +49,7 @@ function curatedStats(base: string, hash: string, key: string, captured: boolean
   if (!existsSync(join(dir, "generation.json")) && !existsSync(join(dir, "generation-seal.json"))) return { entries: 0, lastAt: null };
   const store = openShardStore({ memoryDir: base, project: key, deferPromotions: true, lifecycle: "ignore" });
   try {
-    const db = new Database(join(dir, store.profile.foreignPruneFormat ? "index-v2.db" : "index.db"), { readonly: true });
+    const db = new Database(join(dir, indexFileName(!!store.profile.foreignPruneFormat)), { readonly: true });
     try {
       db.run("PRAGMA busy_timeout = 0");
       const row = db.query("SELECT COUNT(*) AS n, MAX(at) AS last FROM entries WHERE scope = 'project' AND project = ?" + (store.profile.foreignPruneFormat ? " AND id NOT IN (SELECT id FROM generation_targets)" : "")).get(key) as { n: number; last: string | null };

package/src/memory/doctor.ts

@@ -1,4 +1,6 @@
 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";
@@ -12,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 { 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
@@ -42,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. */
@@ -60,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;
   };
 }
 
@@ -202,7 +209,7 @@ export async function withBriefSnapshot<T>(home: string, project: string, read:
 
 /** 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 }),
@@ -435,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;
@@ -459,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();
@@ -480,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 };
@@ -493,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)",
 };
 
@@ -513,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 });
+  }
+}