@staix/agent-mem 0.18.0 → 0.20.0

package/src/session-brief-worker.ts

@@ -1,86 +1,138 @@
 import type { BriefOptions } from "./session-brief.ts";
 import type { CaptureStore } from "./memory/capture.ts";
-import { resolveHookProjectAsync } from "./hook-project.ts";
-import { hookPeakRssKB } from "./hook-resources.ts";
+import { acceptHookProjectReceipt } from "./hook-project.ts";
+import { writeSync } from "node:fs";
+import { hookRssReading, hookPeakRssKB } from "./hook-resources.ts";
+import { rssSourceCode } from "./hook-rss-wire.ts";
 import { resolveAlias } from "./memory/aliases.ts";
-import { HOOK_EVENTS, HOOK_INPUT_BYTES } from "./hook-contract.ts";
-import { drainHookCaptures, hookCaptureScope, quarantineHookScope } from "./hook-spool.ts";
-import { createStandalonePolicy } from "./memory/policy.ts";
-import { configuredPolicyOptions } from "./memory/config.ts";
+import { HOOK_EVENTS, HOOK_INPUT_BYTES, type HookTranscriptProgress } from "./hook-contract.ts";
+import { drainHookCaptures, hookCaptureScope, hookReplayBudget } from "./hook-spool.ts";
+/** Existing allowance for the scan's own cursor commit; the parent also retains its cleanup reserve. */
+const SCAN_COMMIT_MS = 20;
 
-async function readOptions(): Promise<string> {
-  const reader = Bun.stdin.stream().getReader(), chunks: Uint8Array[] = []; let bytes = 0;
-  try {
+/** #226: options arrive as newline-delimited JSON. A transcript hook first sends the scan options, then (after native
+ * metadata) the drain options; other hooks send only the drain options. Total input stays bounded. */
+function optionLines(): () => Promise<string | undefined> {
+  const reader = Bun.stdin.stream().getReader(), decoder = new TextDecoder("utf-8", { fatal: true });
+  let pending = "", bytes = 0, done = false;
+  return async () => {
     for (;;) {
-      const next = await reader.read(); if (next.done) break;
+      const at = pending.indexOf("\n");
+      if (at >= 0) { const line = pending.slice(0, at); pending = pending.slice(at + 1); return line; }
+      if (done) { const rest = pending; pending = ""; return rest || undefined; }
+      const next = await reader.read();
+      if (next.done) { done = true; pending += decoder.decode(); continue; }
       bytes += next.value.byteLength;
-      // Native input is at most64KiB; leave bounded room for fixed host options and policy literals.
-      if (bytes > HOOK_INPUT_BYTES + 32 * 1024) throw new Error("input bound");
-      chunks.push(next.value);
+      // Native input is at most 64 KiB, sent at most twice (scan, then drain); leave bounded room for fixed options.
+      if (bytes > 2 * HOOK_INPUT_BYTES + 32 * 1024) throw new Error("input bound");
+      pending += decoder.decode(next.value, { stream: true });
     }
-    return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
-  } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+  };
 }
 
 // Fixed package helper, launched and reaped by each native hook; never registered or resident.
 if (import.meta.main) {
-  let owned = false;
-  const nativeUsage = { rssKB: 0, rawRssKB: 0 };
-  const stop = (): never => {
-    // This leader is still alive in the detached group created by hookWorker.
-    // Native Git uses a separate owned async supervisor with its own native watchdog;
-    // a blocked Git cannot prevent this worker's JS deadline from firing.
-    if (owned) try { process.kill(-process.pid, "SIGKILL"); } catch { /* No group exists in a direct, non-owned invocation. */ }
+  let owned = false, rssTelemetryValid = true;
+  let lastProgress: HookTranscriptProgress | undefined;
+  const frame = (rss: number[]) => { try { writeSync(1, JSON.stringify({ rss }) + "\n"); } catch { rssTelemetryValid = false; } };
+  const progress = (transcript: HookTranscriptProgress) => {
+    lastProgress = { ...lastProgress, ...transcript, ...(lastProgress?.stopReason === "unavailable" ? { stopReason: "unavailable" as const } : {}) };
+    try { writeSync(1, JSON.stringify({ transcript: lastProgress }) + "\n"); } catch { rssTelemetryValid = false; }
+  };
+  const drain = (value: { startMs?: number; drained: number }) => { try { writeSync(1, JSON.stringify({ drain: value }) + "\n"); } catch { rssTelemetryValid = false; } };
+  frame([0]);
+  const stop: () => never = () => {
+    if (!rssTelemetryValid) frame([4]);
+    const self = hookRssReading(); frame([3, self.kb, self.rawKB, rssSourceCode(self)]);
+    if (owned) try { process.kill(-process.pid, "SIGKILL"); } catch { /* A direct unowned invocation has no group. */ }
     process.exit(0);
   };
   const emit = async (result: unknown) => {
-    const body = JSON.stringify({ ...(result as object), complete: true });
-    const rssKB = hookPeakRssKB() + nativeUsage.rssKB;
+    const body = JSON.stringify({ ...(result as object), complete: true, rssTelemetryValid });
+    const rssKB = hookPeakRssKB();
     await Bun.stdout.write(body.slice(0, -1) + `,"rssKB":${rssKB}}\n`);
     stop();
   };
+  // Ordinary hooks preload only the store, as before. They must not pay for a transcript module they never use.
+  let captureReady = false;
+  const captureModule = import("./memory/capture.ts");
+  captureModule.then(() => { captureReady = true; }, () => { /* Reported when the final drain awaits it. */ });
+  const next = optionLines(), now = () => performance.timeOrigin + performance.now();
+  let store: CaptureStore | undefined;
   try {
-    const options = JSON.parse(await readOptions()) as BriefOptions & { current: string; event: string; deadlineAt: number; ownedGroup: boolean };
-    if (!Number.isFinite(options.deadlineAt) || options.ownedGroup !== true) process.exit(0);
+    const line = await next();
+    if (line === undefined) stop();
+    const first = JSON.parse(line) as Record<string, unknown>;
+    type Scan = { cwd: string; base: string; transcript: unknown; policy?: BriefOptions["policy"]; deadlineAt: number };
+    type DrainOptions = BriefOptions & { current: string; event: string; identity?: unknown; deadlineAt: number; ownedGroup: boolean; hookStartAt?: number };
+    const scan = first.scan as Scan | undefined;
+    const deadlineAt = scan?.deadlineAt ?? first.deadlineAt;
+    if (!Number.isFinite(deadlineAt) || first.ownedGroup !== true) stop();
     owned = true;
-    const remaining = () => options.deadlineAt - (performance.timeOrigin + performance.now());
-    if (remaining() <= 0) stop();
-    setTimeout(stop, remaining()).unref();
-    const policy = createStandalonePolicy(configuredPolicyOptions(options.base!, options.cwd, options.policy)), event = options.event;
-    if (!(HOOK_EVENTS as readonly string[]).includes(event)) stop();
-    const expectedScope = hookCaptureScope(options.cwd, options.base!);
-    let project: string;
-    // Overlap the shared resolver's existing origin/metadata reads on a cold cache;
-    // serial native launches can exhaust every hook before any binding or replay is published.
-    // ponytail: cold identity must still fit one hook deadline. Revalidated durable
-    // identity progress is the upgrade if slower native reads keep exhausting that slice.
-    try { project = resolveAlias(options.base!, await resolveHookProjectAsync({ cwd: options.cwd, base: options.base!, scope: expectedScope, timeRemaining: remaining, maintainCache: event !== "SessionStart", prefetch: true }, nativeUsage)); }
-    catch {
-      if (expectedScope !== undefined) quarantineHookScope({ cwd: options.cwd, base: options.base!, scope: expectedScope });
-      project = stop();
-    }
-    let captured = false;
-    // Normal SessionStart keeps the parent's durable stage for later replay and spends
-    // its short-lived worker on context. An empty current name is mandatory full-tier recovery.
-    if (expectedScope !== undefined && (event !== "SessionStart" || !options.current)) {
-      const { CaptureStore } = await import("./memory/capture.ts");
-      let store: CaptureStore | undefined;
-      try {
-        const drained = await drainHookCaptures({ ...options, base: options.base!, project, expectedScope, timeRemaining: remaining }, (input, receipt) => {
-          store ??= new CaptureStore({ memoryDir: options.base!, project, busyTimeoutMs: 0, cwd: options.cwd });
-          return store.append(input, { receipt });
-        });
-        captured = drained.captured.includes(options.current);
-      } finally { store?.close(); }
-    }
-    if (hookCaptureScope(options.cwd, options.base!) !== expectedScope) stop();
-    if (event === "SessionStart") {
-      const { sessionStartBrief } = await import("./session-brief.ts");
-      const result = await sessionStartBrief({ ...options, project,
-        timeRemaining: () => options.deadlineAt - (performance.timeOrigin + performance.now()) });
-      const valid = await policy.screen({ context: result.context });
-      if (hookCaptureScope(options.cwd, options.base!) !== expectedScope) stop();
-      await emit({ ...result, captured, valid });
-    } else await emit({ context: "", captured, valid: true });
+    const end = deadlineAt as number;
+    if (now() >= end) { if (scan) progress({ stopReason: "deadline" }); stop(); }
+    setTimeout(() => { if (scan) progress({ stopReason: "deadline" }); stop(); }, end - now()).unref();
+
+    // Read the native receipt while scan setup runs. Publication callbacks await it only when replay can proceed.
+    const drainLine = scan ? next() : Promise.resolve(line);
+    const ready = (async () => {
+      const text = await drainLine;
+      if (text === undefined) return undefined;
+      const options = JSON.parse(text) as DrainOptions;
+      if (options.ownedGroup !== true || options.deadlineAt !== end || !(HOOK_EVENTS as readonly string[]).includes(options.event) || options.event === "SessionStart") return undefined;
+      const expectedScope = hookCaptureScope(options.cwd, options.base!);
+      let project: string | undefined;
+    try { project = resolveAlias(options.base!, acceptHookProjectReceipt(options.identity, { cwd: options.cwd, base: options.base!, scope: expectedScope, timeRemaining: () => end - now() })); } catch { /* A bound scan may still stage without a project. */ }
+      return { options, expectedScope, project };
+    })();
+    let receiptReady = false;
+    ready.then(() => { receiptReady = true; }, () => { /* The final drain reports failure inside the owned helper. */ });
+    const budget = hookReplayBudget();
+    let drainedCount = 0, captured = false, drainStarted = false;
+    const replay = async (until: number, waitForReady = true) => {
+      // Scanning must not wait on native metadata or cold store imports between summary lines.
+      // The final replay may await them; publication/backpressure callbacks only use ready resources.
+      if (!waitForReady && (!receiptReady || !captureReady)) return false;
+      if (!budget.files || !budget.bytes || until - now() < 8) return false;
+      const context = await ready;
+      if (!context?.project || context.expectedScope === undefined || Math.min(end, until) - now() < 8) return false;
+      const { options, expectedScope, project } = context;
+      const { CaptureStore } = await captureModule;
+      const remaining = () => Math.min(end, until) - now();
+      if (remaining() < 8) return false;
+      if (!drainStarted) {
+        drain({ startMs: Math.round(now() - (options.hookStartAt ?? end)), drained: drainedCount });
+        drainStarted = true;
+      }
+      const drained = await drainHookCaptures({ ...options, base: options.base!, project, expectedScope, timeRemaining: remaining, replayBudget: budget }, (input, receipt) => {
+        store ??= new CaptureStore({ memoryDir: options.base!, project, busyTimeoutMs: 0, cwd: options.cwd });
+        const appended = store.append(input, { receipt });
+        drain({ drained: ++drainedCount }); // DB commit or durable capture-spool acknowledgement, as in the existing contract.
+        return appended;
+      });
+      captured ||= drained.captured.includes(options.current);
+      return drained.captured.length > 0;
+    };
+    let context: Awaited<typeof ready>;
+    try {
+      if (scan && hookCaptureScope(scan.cwd, scan.base) !== undefined) {
+        const scanEnd = end - SCAN_COMMIT_MS;
+        if (scanEnd - now() < 5) progress({ stopReason: "deadline" });
+        else try {
+          const { scanHookTranscriptTail } = await import("./hook-transcript.ts");
+          const scanned = await scanHookTranscriptTail(scan.transcript, {
+            cwd: scan.cwd, base: scan.base, policy: scan.policy, deadline: performance.now() + (scanEnd - now()),
+            // Same existing oldest-first drain and one shared budget, never a new 32-file allowance per publication.
+            onPublication: async () => { await replay(scanEnd, false); },
+            onBackpressure: () => replay(scanEnd, false),
+          });
+          if (scanned) progress(scanned);
+        } catch { progress({ stopReason: "unavailable" }); }
+      }
+      context = await ready;
+      await replay(end); // Newly staged summaries get their final commit opportunity in this hook too.
+    } finally { store?.close(); }
+    if (!context?.project || hookCaptureScope(context.options.cwd, context.options.base!) !== context.expectedScope) stop();
+    await emit({ context: "", captured, valid: true });
   } catch { if (owned) stop(); process.exitCode = 1; }
 }

package/src/session-brief.ts

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

package/src/setup-drift.ts

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

package/src/setup-jcode.ts

@@ -1,7 +1,72 @@
 import type { ConfigImage } from "./setup-owned.ts";
 import { createJsonMcpCodec } from "./setup-json.ts";
+import { setTomlPath } from "./setup-toml.ts";
 
 const codec = createJsonMcpCodec({ canonicalKey: "servers", aliases: ["mcpServers"], label: "Jcode" });
 export function readJcodeMcp(image: ConfigImage): unknown { return codec.read(image); }
 export function putJcodeMcp(image: ConfigImage, value: unknown): ConfigImage { return codec.put(image, value); }
 export function restoreJcodeMcp(before: ConfigImage, after: ConfigImage, current: ConfigImage): ConfigImage { return codec.restore(before, after, current); }
+
+// #203: jcode v0.99.1 `[hooks]` in <JCODE_HOME>/config.toml (crates/jcode-config-types HooksConfig). Each event accepts a
+// command string or an ordered array of strings; observers in an array all run. amem owns only its own command element.
+export const JCODE_CAPTURE_EVENTS = ["post_tool", "turn_end"] as const;
+const tomlText = (image: ConfigImage) => image.bytes === null ? "" : new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(image.bytes, "base64"));
+const tomlImage = (value: string, mode: number): ConfigImage => ({ bytes: Buffer.from(value).toString("base64"), mode });
+function hooksTable(text: string): Record<string, unknown> | undefined {
+  let document: unknown;
+  try { document = Bun.TOML.parse(text); } catch { throw Error("Jcode config.toml does not parse as TOML"); }
+  const hooks = (document as Record<string, unknown>).hooks;
+  if (hooks === undefined) return undefined;
+  if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) throw Error("Jcode [hooks] must be a table");
+  return hooks as Record<string, unknown>;
+}
+function commands(value: unknown): string[] {
+  if (value === undefined) return [];
+  if (typeof value === "string") return value.trim() ? [value] : [];
+  if (Array.isArray(value) && value.every(item => typeof item === "string")) return value as string[];
+  throw Error("Jcode hook commands must be a string or an array of strings");
+}
+/** Adds `command` to each capture event, keeping any existing user command ahead of it (array form). */
+export function putJcodeHooks(before: ConfigImage, command: string): ConfigImage {
+  let text = tomlText(before);
+  const hooks = hooksTable(text) ?? {};
+  for (const event of JCODE_CAPTURE_EVENTS) {
+    const existing = commands(hooks[event]);
+    if (existing.includes(command)) continue;
+    text = setTomlPath(text, ["hooks", event], existing.length ? [...existing, command] : command);
+  }
+  return tomlImage(text, before.mode);
+}
+/** amem's command elements, per event, that `after` added over `before` (the receipt proves ownership, not the runtime). */
+function ownedCommands(before: ConfigImage, after: ConfigImage): Map<string, string[]> {
+  const b = hooksTable(tomlText(before)) ?? {}, a = hooksTable(tomlText(after)) ?? {}, owned = new Map<string, string[]>();
+  for (const event of JCODE_CAPTURE_EVENTS) { const prior = commands(b[event]); owned.set(event, commands(a[event]).filter(item => !prior.includes(item))); }
+  return owned;
+}
+export function jcodeHooksManaged(before: ConfigImage, after: ConfigImage, current: ConfigImage): boolean {
+  try { const hooks = hooksTable(tomlText(current)) ?? {}; return [...ownedCommands(before, after)].every(([event, owned]) => owned.every(item => commands(hooks[event]).includes(item))); }
+  catch { return false; }
+}
+/** Exact restore when untouched; otherwise removes only amem's command elements, keeping user commands and later edits. */
+export function restoreJcodeHooks(before: ConfigImage, after: ConfigImage, current: ConfigImage): ConfigImage {
+  if (current.bytes === after.bytes) return { ...before, mode: current.mode };
+  if (current.bytes === before.bytes) return current;
+  const original = hooksTable(tomlText(before)) ?? {}, owned = ownedCommands(before, after);
+  let text = tomlText(current);
+  const hooks = hooksTable(text) ?? {};
+  for (const event of JCODE_CAPTURE_EVENTS) {
+    const live = commands(hooks[event]), mine = owned.get(event) ?? [];
+    if (!live.some(item => mine.includes(item))) continue;
+    const kept = live.filter(item => !mine.includes(item)), prior = original[event];
+    // Return the user's original spelling when only amem's element was added; otherwise keep the remaining array.
+    const value = !kept.length ? (prior !== undefined && !commands(prior).length ? prior : undefined)
+      : kept.length === 1 && typeof prior === "string" && prior === kept[0] ? prior : kept;
+    text = setTomlPath(text, ["hooks", event], value);
+  }
+  if (hooksTable(tomlText(before)) === undefined) {
+    const left = hooksTable(text);
+    if (left !== undefined && !Object.keys(left).length) text = setTomlPath(text, ["hooks"], undefined);
+  }
+  if (before.bytes === null && !Object.keys(Bun.TOML.parse(text) as object).length) return { ...before, mode: current.mode };
+  return tomlImage(text, current.mode);
+}

package/src/setup-owned.ts

@@ -1,6 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import { SETUP_CONFIG_BYTES, setTomlPath, updateTomlArray } from "./setup-toml.ts";
-import { readJcodeMcp, putJcodeMcp, restoreJcodeMcp } from "./setup-jcode.ts";
+import { readJcodeMcp, putJcodeMcp, restoreJcodeMcp, jcodeHooksManaged, restoreJcodeHooks } from "./setup-jcode.ts";
 import { readAgyMcp, putAgyMcp, restoreAgyMcp } from "./setup-agy.ts";
 import { readOpencodeMcp, putOpencodeMcp, restoreOpencodeMcp } from "./setup-opencode.ts";
 export interface ConfigImage { bytes: string | null; mode: number }
@@ -119,6 +119,7 @@ export function restoreOwned(target: string, index: number, before: ConfigImage,
   if (target === "agy" && index === 0) return restoreAgyMcp(before, after, current);
   if (target === "opencode" && index === 0) return restoreOpencodeMcp(before, after, current);
   if (target === "jcode" && index === 0) return restoreJcodeMcp(before, after, current);
+  if (target === "jcode" && index === 1) return restoreJcodeHooks(before, after, current);
   if (sameImage(current, after)) return before;
   if (sameImage(current, before)) return current;
   // Qwen keeps both managed surfaces in one settings file and one receipt image.
@@ -136,6 +137,7 @@ export function managedAfter(target: string, index: number, before: ConfigImage,
     return isDeepStrictEqual(mcpRecord(target, after), mcpRecord(target, current)) && needed.every(row => live.some(value => value.id === row.id));
   }
   if (index === 0) return isDeepStrictEqual(mcpRecord(target, after), mcpRecord(target, current));
+  if (target === "jcode") return jcodeHooksManaged(before, after, current);
   if (target === "claude" || target === "codex") {
     const needed = added(hooks(json(before)), hooks(json(after)), row => row.id), live = hooks(json(current));
     return needed.every(row => live.some(value => value.id === row.id));
@@ -143,3 +145,18 @@ export function managedAfter(target: string, index: number, before: ConfigImage,
   if (target === "kimi") return added(kimiHooks(before), kimiHooks(after), kimiKey).every(row => kimiHooks(current).some(value => kimiKey(value) === kimiKey(row)));
   return current.bytes === after.bytes;
 }
+
+/** Read-only receipt diagnostics; use the same hook identity rules as semantic undo. */
+export function managedHookEntries(target: string, before: ConfigImage, after: ConfigImage, current: ConfigImage,
+  expected: readonly { event: string; command: string }[]): { entry: string; present: boolean }[] {
+  if (target === "kimi") {
+    const original = kimiHooks(before), installed = kimiHooks(after), live = kimiHooks(current);
+    const ours = new Set(added(original, installed, kimiKey).map(kimiKey));
+    return installed.filter(row => ours.has(kimiKey(row)) || expected.some(value => value.event === row.event && value.command === row.command))
+      .map(row => ({ entry: `hooks.${String(row.event)}`, present: live.some(value => kimiKey(value) === kimiKey(row)) }));
+  }
+  const strict = target === "qwen", original = hooks(json(before), strict), installed = hooks(json(after), strict), live = hooks(json(current), strict);
+  const ours = new Set(added(original, installed, row => row.id).map(row => row.id));
+  return installed.filter(row => ours.has(row.id) || expected.some(value => value.event === row.event && value.command === row.command))
+    .map(row => ({ entry: `hooks.${row.event}`, present: live.some(value => value.id === row.id) }));
+}