@staix/agent-mem 0.18.0 → 0.20.0

package/src/hook-transcript.ts

@@ -0,0 +1,205 @@
+import { assertFormatFloor } from "./memory/formats.ts";
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalPath, realPath } from "./memory/platform.ts";
+import { configuredPolicyOptions } from "./memory/config.ts";
+import { createStandalonePolicy, type StandalonePolicyOptions } from "./memory/policy.ts";
+import { HookSpoolFull, stageTranscriptCapture, type PendingHookCapture } from "./hook-spool.ts";
+import { appendMetrics } from "./memory/metrics.ts";
+import type { HookTranscriptProgress } from "./hook-contract.ts";
+
+export const HOOK_TRANSCRIPT_BYTES = 256 * 1024;
+const hash = (value: string) => createHash("sha256").update(value).digest("hex");
+type SummaryEvent = "Title" | "Recap" | "Compact";
+interface Cursor { offset: number; dev: string; ino: string; size: number; title: string; at: string; readStart: number; readAt: string; skipping: number }
+/** `deadline` is the hard end of the scan. With `workBudgetMs`, the line loop gets that budget measured from the end of setup
+ * (policy, cursor database, read), never past `deadline` (#226 task 110: on a slow runner setup ate a fixed window). */
+interface Options { cwd: string; base: string; deadline: number; workBudgetMs?: number; policy?: StandalonePolicyOptions;
+  /** Worker-local replay opportunities; no text crosses these callbacks. */
+  onPublication?: (pending: PendingHookCapture) => Promise<void>;
+  onBackpressure?: () => Promise<boolean>;
+}
+const object = (value: unknown): Record<string, unknown> | undefined => value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+const timestamp = (value: unknown) => typeof value === "string" && Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : undefined;
+
+/** Claude's three free texts only; ordinary transcript lines never enter JSON.parse. */
+export function transcriptSummary(line: string): { event: SummaryEvent; text: string; at?: string; subagent?: true } | undefined {
+  if (!line.includes('"ai-title"') && !line.includes('"away_summary"') && !line.includes('"isCompactSummary"')) return undefined;
+  const row = object(JSON.parse(line)); if (!row) return undefined;
+  let event: SummaryEvent, text: unknown;
+  if (row.type === "ai-title") { event = "Title"; text = row.aiTitle; }
+  else if (row.type === "system" && row.subtype === "away_summary") { event = "Recap"; text = row.content; }
+  else if (row.type === "user" && row.isCompactSummary === true) {
+    event = "Compact"; text = object(row.message)?.content;
+    if (Array.isArray(text)) text = text.flatMap(part => { const value = object(part); return value?.type === "text" && typeof value.text === "string" ? [value.text] : []; }).join("\n");
+  } else return undefined;
+  if (typeof text !== "string" || !text.trim()) return undefined;
+  const visibleText = event === "Recap" ? text.replace(/\s*\(disable recaps in \/config\)\s*$/, "") : text;
+  return { event, text: visibleText, ...(timestamp(row.timestamp) ? { at: timestamp(row.timestamp)! } : {}), ...(row.isSidechain === true || typeof row.agentId === "string" && row.agentId.length > 0 ? { subagent: true as const } : {}) };
+}
+
+/** Read only a top-level timestamp token, without parsing ordinary message bodies. */
+function transcriptTimestamp(line: string): string | undefined {
+  if (!line.includes('"timestamp"')) return;
+  let depth = 0, at: string | undefined;
+  for (let index = 0; index < line.length; index++) {
+    const character = line[index];
+    if (character === '"') {
+      const start = index++;
+      for (; index < line.length; index++) {
+        if (line[index] === "\\") index++;
+        else if (line[index] === '"') break;
+      }
+      if (depth === 1 && line.slice(start, index + 1) === '"timestamp"') {
+        const value = /^\s*:\s*"([^"\\]+)"/.exec(line.slice(index + 1));
+        if (value) at = timestamp(value[1]);
+      }
+    } else if (character === "{" || character === "[") depth++;
+    else if (character === "}" || character === "]") depth--;
+  }
+  return at;
+}
+
+function privateDirectory(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(dir);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("transcript cursor unavailable");
+  chmodSync(dir, 0o700);
+}
+function cursorDatabase(file: string, dev: string, ino: string, size: number): Database {
+  const fd = openSync(file, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+  try {
+    const stat = fstatSync(fd), named = lstatSync(file);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024 || named.isSymbolicLink() || stat.dev !== named.dev || stat.ino !== named.ino) throw new Error("transcript cursor unavailable");
+    chmodSync(file, 0o600);
+    for (const suffix of ["-journal", "-wal", "-shm"]) {
+      const sidecar = lstatSync(file + suffix, { throwIfNoEntry: false });
+      if (sidecar && (!sidecar.isFile() || sidecar.isSymbolicLink() || sidecar.nlink !== 1 || sidecar.size > 1024 * 1024)) throw new Error("transcript cursor unavailable");
+      if (sidecar) chmodSync(file + suffix, 0o600);
+    }
+  } finally { closeSync(fd); }
+  const db = new Database(file);
+  try {
+    db.run("PRAGMA busy_timeout = 0");
+    db.transaction(() => {
+      db.run("CREATE TABLE IF NOT EXISTS fallback (digest TEXT PRIMARY KEY, at TEXT NOT NULL)");
+      db.run("CREATE TABLE IF NOT EXISTS cursor (id INTEGER PRIMARY KEY CHECK(id=1), offset INTEGER NOT NULL, dev TEXT NOT NULL, ino TEXT NOT NULL, size INTEGER NOT NULL, title TEXT NOT NULL, at TEXT NOT NULL, readStart INTEGER NOT NULL, readAt TEXT NOT NULL, skipping INTEGER NOT NULL CHECK(skipping IN (0,1)))");
+      // One durable initialization commit; persist fallback time and known identity before publication.
+      db.query("INSERT OR IGNORE INTO cursor VALUES (1,0,?,?,?,'','',0,?,0)").run(dev, ino, size, new Date().toISOString());
+    }).immediate();
+    return db;
+  } catch (error) { db.close(); throw error; }
+}
+
+/** Private per-session transaction serializes screens and cursor advancement. No path or raw id is persisted. */
+export async function scanHookTranscriptTail(input: unknown, options: Options): Promise<HookTranscriptProgress | undefined> {
+  const value = object(input);
+  if (!value || options.policy?.host || typeof value.transcript_path !== "string" || typeof value.session_id !== "string" || !value.session_id || value.session_id.length > 256) return;
+  if (performance.now() >= options.deadline) return { stopReason: "deadline" };
+  const cwd = realPath(options.cwd), base = canonicalPath(options.base);
+  assertFormatFloor(base, "hook-spool");
+  if (value.cwd !== undefined && (typeof value.cwd !== "string" || realPath(value.cwd) !== cwd)) return;
+  const policy = createStandalonePolicy(configuredPolicyOptions(base, cwd, options.policy));
+  if (!await policy.screen(value)) return;
+  const session = hash(`amem-session\0${value.session_id}`).slice(0, 16);
+  if (lstatSync(value.transcript_path).isSymbolicLink()) throw new Error("transcript unavailable");
+  const transcript = realPath(value.transcript_path);
+  // Parent aliases must not hide a configured deny path behind an allowed spelling.
+  if (!await policy.screen({ transcript_path: transcript })) return;
+  const fd = openSync(transcript, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  let db: Database | undefined;
+  try {
+    const stat = fstatSync(fd), named = lstatSync(value.transcript_path);
+    if (!stat.isFile() || stat.nlink !== 1 || named.isSymbolicLink() || stat.dev !== named.dev || stat.ino !== named.ino) return;
+    const dir = join(base, "hook-transcripts"); privateDirectory(dir);
+    db = cursorDatabase(join(dir, `${session}.db`), String(stat.dev), String(stat.ino), stat.size); db.run("BEGIN IMMEDIATE");
+    let cursor = db.query("SELECT * FROM cursor WHERE id=1").get() as Cursor;
+    if (!Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || !Number.isSafeInteger(cursor.size) || cursor.size < 0 || cursor.at !== "" && !timestamp(cursor.at)
+      || !Number.isSafeInteger(cursor.readStart) || cursor.readStart < 0 || !timestamp(cursor.readAt) || ![0, 1].includes(cursor.skipping) || !/^(?:[a-f0-9]{64})?$/.test(cursor.title)) throw new Error("transcript cursor unavailable");
+    const reset = cursor.dev !== String(stat.dev) || cursor.ino !== String(stat.ino) || stat.size < cursor.size || stat.size < cursor.offset;
+    if (reset || cursor.offset !== cursor.readStart || cursor.size === 0 && stat.size > 0) {
+      // Commit reset metadata before staging too: titles without a native timestamp
+      // retain their fallback time if the process dies between publication and cursor advance.
+      if (reset) { cursor.offset = 0; cursor.at = ""; cursor.skipping = 0; }
+      db.query("UPDATE cursor SET offset=?,dev=?,ino=?,size=?,at=?,readStart=?,readAt=?,skipping=? WHERE id=1")
+        .run(cursor.offset, String(stat.dev), String(stat.ino), stat.size, cursor.at, cursor.offset, new Date().toISOString(), cursor.skipping);
+      db.run("COMMIT"); db.run("BEGIN IMMEDIATE");
+      cursor = db.query("SELECT * FROM cursor WHERE id=1").get() as Cursor;
+    }
+    const bytes = Buffer.alloc(Math.min(HOOK_TRANSCRIPT_BYTES, Math.max(0, stat.size - cursor.offset)));
+    const length = readSync(fd, bytes, 0, bytes.length, cursor.offset);
+    const after = fstatSync(fd), live = lstatSync(value.transcript_path);
+    if (length !== bytes.length || after.size < stat.size || live.dev !== stat.dev || live.ino !== stat.ino || realPath(value.transcript_path) !== transcript) return;
+    let start = 0, stopReason: HookTranscriptProgress["stopReason"];
+    const workStart = performance.now();
+    // The caller's deadline is read live (a caller may move it); the work budget only adds an earlier end after setup.
+    const due = () => performance.now() >= options.deadline || options.workBudgetMs !== undefined && performance.now() - workStart >= options.workBudgetMs;
+    while (start < length && !due()) {
+      const newline = bytes.indexOf(10, start);
+      if (cursor.skipping) {
+        start = newline < 0 ? length : newline + 1;
+        if (newline >= 0) cursor.skipping = 0;
+        continue;
+      }
+      if (newline < 0) {
+        // ponytail: a JSONL line exceeding the invocation's 256 KiB ceiling is
+        // lost, not buffered in memory/home. Upgrade with a bounded streaming extractor.
+        if (start === 0 && length === HOOK_TRANSCRIPT_BYTES && stat.size - cursor.offset > length) {
+          cursor.skipping = 1; start = length;
+          appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", captureDrops: 1, captureDropReason: "transcript_line_bound" }]);
+        }
+        break;
+      }
+      let line: string;
+      try { line = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(start, newline)); }
+      catch { start = newline + 1; continue; }
+      let summary: ReturnType<typeof transcriptSummary>;
+      try { summary = transcriptSummary(line); } catch { /* Malformed native JSON is not capture. */ }
+      if (summary && !await policy.screen(JSON.parse(line))) summary = undefined;
+      if (summary) {
+        const title = summary.event === "Title" ? hash(summary.text) : "";
+        if (!title || title !== cursor.title) {
+          try {
+            let at = summary.at ?? cursor.at;
+            if (!at) {
+              // Native timestamps normally identify summaries. Untimed content retains its
+              // first fallback across rotation, so an unchanged row cannot get a new receipt.
+              const digest = hash(JSON.stringify([summary.event, summary.text, summary.subagent ?? false]));
+              db.query("INSERT OR IGNORE INTO fallback VALUES (?,?)").run(digest, cursor.readAt);
+              at = (db.query("SELECT at FROM fallback WHERE digest=?").get(digest) as { at: string }).at;
+              if (!timestamp(at)) throw new Error("transcript cursor unavailable");
+            }
+            const publish = () => stageTranscriptCapture({ agent: "claude", event: summary!.event, excerpt: summary!.text, at, session,
+              ...(summary!.subagent || typeof value.agent_id === "string" && value.agent_id.length > 0 ? { subagent: true } : {}) }, { cwd, base, policy: options.policy, deferAtCapacity: true }, summary!.event === "Title" ? `title:${cursor.offset + start}` : undefined);
+            let staged: PendingHookCapture | undefined;
+            try { staged = await publish(); }
+            catch (error) {
+              if (!(error instanceof HookSpoolFull) || due() || !options.onBackpressure || !await options.onBackpressure() || due()) throw error;
+              staged = await publish(); // Same line/receipt, no second read or cursor advance on backpressure.
+            }
+            if (staged && title) cursor.title = title;
+            if (staged) await options.onPublication?.(staged);
+          } catch (error) {
+            // Advance only through durable/refused rows; a full spool retries this line
+            // after the ordinary hook worker drains earlier publications.
+            if (error instanceof HookSpoolFull) { stopReason = "spool_full"; break; }
+            throw error;
+          }
+        }
+      }
+      // Carry timestamps without parsing ordinary messages (including across invocation boundaries).
+      const at = transcriptTimestamp(line); if (at) cursor.at = at;
+      start = newline + 1;
+    }
+    if (!stopReason && start < length && due()) stopReason = "deadline";
+    if (!stopReason && cursor.offset + start < stat.size && length === HOOK_TRANSCRIPT_BYTES) stopReason = "cap";
+    assertFormatFloor(base, "hook-spool");
+    db.query("UPDATE cursor SET offset=?,dev=?,ino=?,size=?,title=?,at=?,skipping=? WHERE id=1").run(cursor.offset + start, String(stat.dev), String(stat.ino), stat.size, cursor.title, cursor.at, cursor.skipping);
+    db.run("COMMIT");
+    return { offset: cursor.offset + start, ...(stopReason ? { stopReason } : {}) };
+  } finally {
+    try { if (db) { try { db.run("ROLLBACK"); } catch { /* Already committed. */ } db.close(); } } finally { closeSync(fd); }
+  }
+}

package/src/hooks.ts

@@ -1,19 +1,21 @@
 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;
+export const HANDLER_MS = 140;
 // A timed-out child must be reaped and metrics flushed inside the unchanged handler/R2 budgets.
 // ponytail: reserve measured native teardown variance; an asynchronous hard-deadline transport
 // through storage/cleanup is the upgrade, not a longer external deadline.
@@ -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,161 @@ 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, register?: (cancel: () => void) => void, onDrain?: (value: unknown) => void): Promise<string | undefined> {
+  const reader = stream.getReader(), decoder = new TextDecoder("utf-8", { fatal: true });
+  // #226: after a bounded reap the parent abandons this pipe; cancelling it leaves no pending read holding the event loop.
+  register?.(() => { reader.cancel().catch(() => {}); });
+  let length = 0, pending = "", body = "";
+  const line = (text: string) => {
+    if (!text) return;
+    const value = JSON.parse(text) as { rss?: unknown; transcript?: unknown; drain?: unknown };
+    if (onRss && Object.hasOwn(value, "rss")) onRss(value.rss);
+    else if (onTranscript && Object.hasOwn(value, "transcript")) onTranscript(value.transcript);
+    else if (onDrain && Object.hasOwn(value, "drain")) onDrain(value.drain);
+    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 };
+}
+
+/** #226: after SIGKILL the parent waits at most this long for the owned worker's exit and output. A worker stuck in
+ * uninterruptible I/O (fsync) can outlive the hook; the kill is already sent, its pipe is cancelled and its handle unref'd,
+ * so nothing keeps this process alive and nothing stays resident. R1 judges it after a fixed 2 s post-exit window. */
+const REAP_BOUND_MS = 10;
+async function boundedWait<T>(work: Promise<T>): Promise<{ value?: T; late: boolean }> {
+  let timer: ReturnType<typeof setTimeout> | undefined, late = false;
+  const value = await Promise.race([work, new Promise<undefined>(resolve => { timer = setTimeout(() => { late = true; resolve(undefined); }, REAP_BOUND_MS); })]);
+  if (timer) clearTimeout(timer);
+  return late ? { late } : { value: value as T, late };
 }
+/** Owned children killed but still alive when the hook returned; recorded in the hook metric. */
+let abandonedChildren = 0;
+/** Transcript hooks whose worker was killed before its drain finished; their staged records stay durable and pending. */
+let drainSkipped = 0;
+/** #226 instrumentation: the last worker drain's start (ms after hook start) and committed record count. */
+let lastDrain: { startMs: number; drained: number } | undefined;
+/** Hook start on the performance clock, set by the entry points, so a worker can report times relative to it. */
+let hookStartedAt = performance.now();
 
-/** 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.
+ * #226 (ruling b): a transcript hook boots that one worker at hook start, in parallel with native metadata. The worker
+ * scans as soon as its first stdin line (scan options) arrives and drains after the second (the native receipt). At the
+ * deadline the parent kills it and waits at most REAP_BOUND_MS; a kill skips that call's drain (counted, never a drop).
  * 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 early = transcript !== undefined;
+  const policy = { denyPaths: options.policy?.denyPaths, piiPatterns: options.policy?.piiPatterns };
+  let owned: Bun.Subprocess<"pipe", "pipe", "ignore"> | undefined, exited = false, killed = false, cancelOutput: (() => void) | undefined;
+  let tracker: HookWorkerRss | undefined, output: Promise<string | undefined> | undefined, exit: Promise<number> | undefined;
+  const result = { context: unavailable, rssKB: 0, rawRssKB: 0, captured: false, valid: false, rssSources: emptyRssSources(), transcript: undefined as HookTranscriptProgress | undefined };
+  const drainProgress: { startMs?: number; drained?: number } = {};
+  const spawn = () => {
+    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: "pipe", stdout: "pipe", stderr: "ignore" });
+    owned = child;
+    exit = child.exited.then(code => { exited = true; return code; });
+    tracker = new HookWorkerRss(child.pid);
+    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");
+      // A reported scan fault stays reported: a later worker deadline frame cannot turn it into accepted progress (#221).
+      result.transcript = { ...result.transcript, ...value, ...(result.transcript?.stopReason === "unavailable" ? { stopReason: "unavailable" as const } : {}) };
+    }, cancel => { cancelOutput = cancel; }, value => {
+      // #226 instrumentation: bounded numeric drain progress; anything else is ignored, never trusted.
+      const row = value as { startMs?: unknown; drained?: unknown } | null;
+      if (row && typeof row.startMs === "number" && Number.isFinite(row.startMs) && row.startMs >= 0 && row.startMs < 10_000) drainProgress.startMs = row.startMs;
+      if (row && Number.isSafeInteger(row.drained) && (row.drained as number) >= 0 && (row.drained as number) <= 1024) drainProgress.drained = row.drained as number;
+    });
+    return child;
+  };
+  const send = (line: object) => { try { owned!.stdin.write(JSON.stringify(line) + "\n"); owned!.stdin.flush(); } catch { /* A dead worker reports nothing. */ } };
+  const close = () => { try { owned?.stdin.end(); } catch { /* Already closed. */ } };
   const stop = () => {
-    if (exited) return;
+    if (!owned || exited) return;
+    tracker!.captureLive();
+    killed = true;
     // 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. */ } }
+    // The capture-only worker owns no native helper; those handles were reaped in this parent.
+    try { process.kill(-owned.pid, "SIGKILL"); } catch { try { owned.kill("SIGKILL"); } catch { /* Already exited. */ } }
   };
-  let timer: ReturnType<typeof setTimeout> | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined, metadata: Awaited<ReturnType<typeof parentProject>> | undefined;
   try {
+    if (early) {
+      spawn();
+      send({ ownedGroup: true, scan: { cwd: options.cwd, base, transcript, policy, deadlineAt: performance.timeOrigin + workDeadline } });
+    }
+    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));
+    metadata = await parentProject(options, base, workDeadline);
+    result.rssKB = metadata.usage.rssKB; result.rawRssKB = metadata.usage.rawRssKB; result.rssSources = combineRssSources(metadata.usage.rssSources);
+    if (!early && (!metadata.receipt || workDeadline - performance.now() < 5)) return result;
+    if (!owned) spawn();
+    result.rssSources.unavailable++;
+    // The worker reads the configuration itself (same base, same cwd), so it screens with exactly the policy the parent did.
+    // Without a receipt the worker still finishes the scan and reports it, but drains nothing.
+    send({ cwd: options.cwd, base, current: pending.name, event, identity: metadata.receipt, maxTokens, ownedGroup: true, deadlineAt: performance.timeOrigin + workDeadline, hookStartAt: performance.timeOrigin + hookStartedAt, policy });
+    close();
     const answer = await Promise.race([
-      Promise.all([exit, boundedOutput(child.stdout)]),
+      Promise.all([exit!, output!]),
       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 };
+    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 (typeof parsed.rssKB === "number" && Number.isSafeInteger(parsed.rssKB) && parsed.rssKB > 0) result.rssKB = parsed.rssKB;
+    if (parsed.rssTelemetryValid !== true) tracker!.invalidate();
     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; }
+  } 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;
+    close();
+    if (owned) {
+      stop();
+      // #226: bounded reap; a worker stuck in uninterruptible I/O is abandoned after REAP_BOUND_MS, never awaited.
+      const reaped = exited || !(await boundedWait(exit!)).late;
+      const body = reaped ? await boundedWait(output!) : { late: true };
+      if (!reaped || body.late) { cancelOutput?.(); owned.unref(); }
+      if (!reaped) abandonedChildren++;
+      // Bun subprocess usage is bytes; process.resourceUsage is KiB. Not reaped: the last live sample is the RSS (ruling Q2).
+      const workerRawKB = reaped ? (owned.resourceUsage()?.maxRSS ?? 0) / 1024 : 0;
+      if (reaped ? body.late || body.value === undefined : !tracker!.hasLiveSample()) tracker!.invalidate();
+      const accounting = tracker!.finish(workerRawKB);
+      const usage = metadata?.usage ?? { rssKB: 0, rawRssKB: 0, rssSources: emptyRssSources() };
+      result.rssKB = usage.rssKB + accounting.rssKB; result.rawRssKB = usage.rawRssKB + workerRawKB; result.rssSources = combineRssSources(usage.rssSources, accounting.rssSources);
+      if (drainProgress.startMs !== undefined) lastDrain = { startMs: drainProgress.startMs, drained: drainProgress.drained ?? 0 };
+      if (early && killed) {
+        // #221: a kill without accepted progress is a deadline stop; a kill also skips this call's drain (ruling b).
+        if (result.transcript?.offset === undefined && result.transcript?.stopReason !== "unavailable") result.transcript = { stopReason: "deadline" };
+        if (!result.valid) drainSkipped++;
+      }
+    } else if (early) result.transcript ??= { stopReason: "deadline" };
   }
 }
 
@@ -143,7 +244,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 +259,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 +269,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 +287,27 @@ 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;
+  // #221: a transcript-bearing hook that ends without worker progress reports `deadline` only on positive evidence:
+  // the remaining time, measured at that exit, is below the worker's own start threshold. Policy, floor or invalid-input
+  // exits keep reporting nothing, so they cannot pass for bounded progress.
+  const deadlineEvidence = () => transcript !== undefined && deadline - WORKER_CLEANUP_MS - performance.now() < 5;
+  const withDeadline = <T extends { transcript?: HookTranscriptProgress }>(value: T): T => value.transcript === undefined && deadlineEvidence() ? { ...value, transcript: { stopReason: "deadline" } } : value;
+  const work = async (pending: PendingHookCapture) => withDeadline(await 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
@@ -207,8 +316,12 @@ async function captureAndWork(event: string, input: unknown, options: HookOption
       return { ...result, pending: false, dropped: true };
     }
   }
-  if (!pending) return result ? { ...result, pending: false } : undefined;
-  result ??= await hookWorker({ ...options, cwd: pending.cwd }, base, deadline, pending, event);
+  if (!pending) {
+    if (result) return { ...result, pending: false };
+    // Staging declined (policy, floor, invalid input) or ran out of time: only measured time makes it a deadline stop.
+    return deadlineEvidence() ? { context: unavailable, rssKB: 0, rawRssKB: 0, captured: false, valid: false, pending: false, transcript: { stopReason: "deadline" as const } } : undefined;
+  }
+  result ??= await work(pending);
   return { ...result, pending: !result.captured };
 }
 
@@ -216,7 +329,10 @@ async function captureAndWork(event: string, input: unknown, options: HookOption
 export async function runHook(event: string, input: unknown, options: HookOptions, host?: HookHostPorts): Promise<HookReceipt> {
   const now = performance.now(), started = options.startedAt !== undefined && Number.isFinite(options.startedAt) && options.startedAt <= now ? options.startedAt : now;
   const deadline = started + handlerMs(host);
+  hookStartedAt = started;
   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,25 +341,38 @@ 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 } : {}), ...(abandonedChildren ? { abandonedChildren } : {}), ...(drainSkipped ? { drainSkipped } : {}), ...(lastDrain ? { drainStartMs: lastDrain.startMs, drained: lastDrain.drained } : {}), ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]); } catch { /* Metrics never change the native tool outcome. */ }
   }
 }
 
 /** Bounded stdin and a fixed overall handler budget; failures produce no native decision and exit successfully. */
 export async function hookMain(args: readonly string[], startedAt = performance.now(), host?: HookHostPorts): Promise<string> {
   const deadlineMs = handlerMs(host);
+  hookStartedAt = startedAt;
   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 +389,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 +399,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 } : {}), ...(abandonedChildren ? { abandonedChildren } : {}), ...(drainSkipped ? { drainSkipped } : {}), ...(lastDrain ? { drainStartMs: lastDrain.startMs, drained: lastDrain.drained } : {}), ...(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");