@staix/agent-mem 0.17.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/mcp-memory.ts

@@ -201,11 +201,12 @@ export function createMemoryMcp(options: MemoryMcpOptions): MemoryMcp {
         try {
           const words = query.toLowerCase().split(/\s+/).filter(Boolean);
           const captureState: { engine?: "fts5" | "substring" } = {};
-          let batch: { body: string; ref: string; tier: string; at: string; value: SearchValue; expiresAt?: string | null }[] = [];
+          let batch: { body: string; ref: string; tier: string; at: string; value: SearchValue; expiresAt?: string | null; event?: string; session?: string }[] = [];
           const append = (value: SearchValue) => {
             const row = value.source === "capture" ? value.capture : value.view;
             batch.push(value.source === "capture"
-              ? { value, ref: `capture:${value.capture.id}`, at: row.at, tier: "capture", body: `${value.capture.excerpt}\n${value.capture.paths.join(" ")}\n${value.capture.event}` }
+              ? { value, ref: `capture:${value.capture.id}`, at: row.at, tier: "capture", body: `${value.capture.excerpt}\n${value.capture.paths.join(" ")}\n${value.capture.event}`,
+                event: value.capture.event, ...(typeof value.capture.session === "string" && /^[a-f0-9]{16}$/.test(value.capture.session) ? { session: value.capture.session } : {}) }
               : { value, ref: value.source === "repo" ? `repo:${value.view.id}` : value.view.id, at: row.at, tier: value.source === "repo" ? "long" : value.view.tier, body: `${value.view.title ?? ""}\n${value.view.text}\n${value.view.about.join(" ")}`, expiresAt: value.source === "curated" ? value.view.expiresAt : null });
             if (batch.length === READ_PAGE) { index.append(batch); batch = []; }
           };
@@ -223,7 +224,16 @@ export function createMemoryMcp(options: MemoryMcpOptions): MemoryMcp {
           const repoNotes = (await repoRows()).filter(view => (!since || Date.parse(view.at) >= Date.parse(since)) && (useFts || words.every(word => `${view.title ?? ""}\n${view.text}\n${view.about.join(" ")}`.toLowerCase().includes(word))));
           for (const view of repoNotes) append({ source: "repo", evidence: false, view });
           if (batch.length) index.append(batch);
-          const selected = index.best(query, limit, store.readNow(), useFts, args.explain === true).map(({ value, score, scoreDetails }) => {
+          const now = store.readNow(), baseline = index.best(query, limit, now, useFts, args.explain === true);
+          const captureSlots = baseline.filter(hit => hit.value.source === "capture").length;
+          const weightedCapture = captureSlots ? index.bestCaptureGroups(query, captureSlots, now, useFts, args.explain === true) : [];
+          let captureIndex = 0;
+          // Keep every baseline noncapture slot and position. Only its capture slots receive weighted,
+          // one-per-session rows from the separately screened TEMP corpus; exhausted slots are omitted.
+          const selected = baseline.flatMap(hit => {
+            if (hit.value.source !== "capture") return [hit];
+            const replacement = weightedCapture[captureIndex++]; return replacement ? [replacement] : [];
+          }).map(({ value, score, scoreDetails }) => {
             const hit = { ...value, score };
             return scoreDetails ? { ...hit, scoreDetails: { source: value.source, ...scoreDetails } } : hit;
           });

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";
@@ -38,6 +39,7 @@ export type CandidateInput = { project: string } & (
 export type CandidateStatus = "pending" | "accepting" | "accepted" | "rejected";
 export interface Candidate { id: string; createdAt: string; status: CandidateStatus; input: CandidateInput; acceptedNoteId: string | null }
 export interface ConsolidationReview { status: Exclude<CandidateStatus, "pending">; acceptedNoteId: string | null }
+const KINDS: readonly string[] = ["correction", "fail", "decay", "memory", "promotion", "consolidation", "model-answer"] satisfies CandidateInput["kind"][];
 export interface CandidateFilter { project: string; status?: CandidateStatus | "all"; kind?: CandidateInput["kind"]; limit?: number }
 export interface CounterKey { entryId: string; project: string; task?: string | null; turn?: string | null; session?: string | null; deliveryId: string }
 export interface CounterValues { rendered?: number | null; delivered?: number | null; cited?: number | null }
@@ -145,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");
@@ -187,8 +190,12 @@ export class CandidateStore {
       this.db.query("DELETE FROM counters WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY at DESC, rowid DESC) AS rank FROM counters) WHERE rank > ?)").run(COUNTER_RETENTION.count);
     }).immediate();
   }
-  private decode(row: { id: string; payload: string; at: number; status: CandidateStatus; note_id: string | null }): Candidate {
-    const input = JSON.parse(row.payload) as CandidateInput; validate(input);
+  /** #199: rows of a kind this version does not know (a newer writer's) are skipped and counted here, never thrown. */
+  skippedUnknownKinds = 0;
+  private decode(row: { id: string; payload: string; at: number; status: CandidateStatus; note_id: string | null }): Candidate | undefined {
+    const input = JSON.parse(row.payload) as CandidateInput;
+    if (input && typeof input === "object" && !KINDS.includes(input.kind)) { this.skippedUnknownKinds++; return undefined; }
+    validate(input);
     if (hash({ schema: "agent-mem.candidate/v1", input }) !== row.id) throw new Error("candidate content hash mismatch");
     return { id: row.id, createdAt: new Date(row.at).toISOString(), status: row.status, input, acceptedNoteId: row.note_id };
   }
@@ -230,14 +237,16 @@ export class CandidateStore {
     return row ? { status: row.status, acceptedNoteId: row.note_id } : undefined;
   }
   list(filter: CandidateFilter): Candidate[] {
-    if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !["correction", "fail", "decay", "memory", "promotion", "consolidation", "model-answer"].includes(filter.kind)) throw new Error("invalid candidate filter");
+    if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !KINDS.includes(filter.kind)) throw new Error("invalid candidate filter");
     const limit = filter.limit ?? CANDIDATE_RETENTION.count;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > CANDIDATE_RETENTION.count) throw new Error("candidate limit must be 1..500");
     this.prune();
     const where = ["project IN (SELECT value FROM json_each(?))"], bind: (string | number)[] = [this.scope(filter.project)];
     if (filter.status === undefined) where.push("status IN ('pending', 'accepting')"); else if (filter.status !== "all") { where.push("status = ?"); bind.push(filter.status); }
     if (filter.kind) { where.push("kind = ?"); bind.push(filter.kind); }
-    return (this.db.query(`SELECT * FROM candidates WHERE ${where.join(" AND ")} ORDER BY at DESC, rowid DESC LIMIT ?`).all(...bind, limit) as Parameters<CandidateStore["decode"]>[0][]).map(row => this.decode(row));
+    // #199: unknown kinds are skipped before LIMIT, so a newer writer's rows never displace a supported candidate; they are still counted.
+    this.skippedUnknownKinds += (this.db.query(`SELECT count(*) AS n FROM candidates WHERE ${where.join(" AND ")} AND kind NOT IN (SELECT value FROM json_each(?))`).get(...bind, JSON.stringify(KINDS)) as { n: number }).n;
+    return (this.db.query(`SELECT * FROM candidates WHERE ${where.join(" AND ")} AND kind IN (SELECT value FROM json_each(?)) ORDER BY at DESC, rowid DESC LIMIT ?`).all(...bind, JSON.stringify(KINDS), limit) as Parameters<CandidateStore["decode"]>[0][]).flatMap(row => this.decode(row) ?? []);
   }
   recordCounter(key: CounterKey, values: CounterValues, verdict: CandidateVerdict): string {
     publicOnly(verdict); const normalized = counterKey(key);

package/src/memory/capture-input.ts

@@ -4,6 +4,9 @@ import { stripPrivateSpans } from "./private-spans.ts";
 
 export const CAPTURE_MAX_EXCERPT = 2000;
 export const CAPTURE_MAX_PATHS = 32;
+export const TOOL_INPUT_LINE_BYTES = 512;
+const TOOL_INPUT_ORDER = ["command", "pattern", "query", "url", "description", "prompt", "skill", "subject"] as const;
+const TOOL_INPUT_OMIT = new Set(["content", "old_string", "new_string", "edits"]);
 const ROW_OVERHEAD_BYTES = 96;
 /** The session key is a fixed-width hash prefix, so it adds a bounded amount covered by the row overhead. */
 export const SESSION_KEY = /^[a-f0-9]{16}$/;
@@ -22,6 +25,37 @@ export interface NormalizedCaptureFields {
   session?: string; subagent?: true;
 }
 
+/** Clip a string at a UTF-8 boundary without splitting a code point. */
+export function clipCaptureUtf8(text: string, maximumBytes: number): string {
+  let out = "", bytes = 0;
+  for (const character of text) {
+    const size = Buffer.byteLength(character);
+    if (bytes + size > maximumBytes) break;
+    out += character; bytes += size;
+  }
+  return out;
+}
+
+/** Deterministic, value-only summary of Claude tool_input. Strip private spans before clipping. */
+export function toolInputLine(input: unknown): string {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return "";
+  const fields = Object.entries(input as Record<string, unknown>)
+    .filter(([key, value]) => typeof value === "string" && !TOOL_INPUT_OMIT.has(key.toLowerCase()) && value.length > 0);
+  const byKey = new Map(fields);
+  const known = TOOL_INPUT_ORDER.filter(key => byKey.has(key));
+  const other = fields.map(([key]) => key).filter(key => !(TOOL_INPUT_ORDER as readonly string[]).includes(key)).sort();
+  const values = [...known, ...other].map(key => clipCaptureUtf8(
+    stripPrivateSpans(byKey.get(key) as string).replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, " "), TOOL_INPUT_LINE_BYTES,
+  )).filter(Boolean);
+  return clipCaptureUtf8(values.join(" | "), TOOL_INPUT_LINE_BYTES).trimEnd();
+}
+
+/** Remove private content before joining tool input and content into the persisted excerpt. */
+export function toolCaptureExcerpt(inputLine: string, content: string): string {
+  const visibleContent = stripPrivateSpans(content);
+  return inputLine ? visibleContent ? `${inputLine}\n${visibleContent}` : inputLine : visibleContent;
+}
+
 /** Pure capture shaping; no store, project lookup or filesystem operation is loaded or invoked here. */
 /** The caps a person's configuration may lower (F4); the built-in caps are the ceiling, so a larger value is ignored. */
 export interface CaptureCaps { excerptBytes?: number; paths?: number; denyPaths?: readonly string[] }

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/cross-project.ts

@@ -44,9 +44,10 @@ export function searchAllProjects(base: string, query: string, opts: { limit?: n
       }
     } finally { store?.close(); }
     if (opts.includeCapture !== false) {
+      // #196 fixes selected-project store/MCP capture slots; this separate cross-project merge keeps its legacy cohort.
       for (const dir of shard.machineDirs) {
         const days = readCaptureConfig(dir, base).retentionDays, cutoff = new Date(now - days * 24 * 3600_000);
-        for (const { row, rank } of captureSearch(dir, query, Math.max(limit * 4, 32), Number.isFinite(cutoff.getTime()) ? cutoff.toISOString() : undefined)) {
+        for (const { row, rank } of captureSearch(dir, query, Math.max(limit * 4, 32), Number.isFinite(cutoff.getTime()) ? cutoff.toISOString() : undefined, { weightEvents: false, onePerSession: false })) {
           hits.push({ source: "capture", score: -rank * 0.5, capture: row as CaptureRow, project: shard.key });
         }
       }