@staix/agent-mem 0.17.0 → 0.19.0

package/src/hook-rss-wire.ts

@@ -0,0 +1,85 @@
+import { combineRssSources, processImageMemory, rssSource, selectHookRss, type HookRssReading, type HookRssSources } from "./hook-resources.ts";
+
+const SOURCES = ["VmHWM", "vmpeak-bound", "platform-rusage", "raw-fallback", "unavailable"] as const;
+export const rssSourceCode = (value: HookRssReading): number => SOURCES.indexOf(value.source);
+function reading(kb: unknown, raw: unknown, code: unknown): HookRssReading | undefined {
+  if (!Number.isSafeInteger(kb) || (kb as number) < 0 || !Number.isSafeInteger(raw) || (raw as number) < 0 || !Number.isSafeInteger(code) || (code as number) < 0 || (code as number) >= SOURCES.length) return;
+  const source = SOURCES[code as number]!;
+  if ((code as number) < 3 && (kb as number) <= 0) return;
+  return { kb: kb as number, rawKB: raw as number, source, known: (code as number) < 3 };
+}
+type Image = ReturnType<typeof processImageMemory>;
+interface Native { pid: number; image?: Image; result?: HookRssReading }
+
+/** Bounded numeric progress survives worker timeout; no native arguments or project data enter it. */
+export class HookWorkerRss {
+  private entered = false;
+  private invalid = false;
+  private readonly native = new Map<number, Native>();
+  private readonly active = new Set<number>();
+  private readonly overlaps: number[][] = [];
+  private image: Image = {};
+  private self?: HookRssReading;
+  constructor(private readonly pid: number) {}
+  invalidate(): void { this.invalid = true; }
+  frame(value: unknown): void {
+    if (!Array.isArray(value)) { this.invalid = true; return; }
+    const [kind, id, pid] = value;
+    if (kind === 0 && value.length === 1 && !this.entered) { this.entered = true; return; }
+    if (!this.entered) { this.invalid = true; return; }
+    if (kind === 3 && value.length === 4) {
+      const selected = reading(value[1], value[2], value[3]);
+      if (!selected) this.invalid = true; else this.self = selected;
+      return;
+    }
+    if (!Number.isSafeInteger(id) || id < 1 || id > 64) { this.invalid = true; return; }
+    if (kind === 1 && value.length === 3 && Number.isSafeInteger(pid) && pid >= 0) {
+      const prior = this.native.get(id);
+      if (!prior && this.native.size < 64 && pid === 0) {
+        this.native.set(id, { pid }); this.active.add(id); this.overlaps.push([...this.active]); return;
+      }
+      if (prior && prior.pid === 0 && !prior.result && pid > 0) { prior.pid = pid; return; }
+    }
+    if (kind === 2 && value.length === 6) {
+      const prior = this.native.get(id), selected = reading(value[2], value[3], value[4]);
+      // Reserved final slot must remain zero, so protocol extensions cannot be misread.
+      if (prior && !prior.result && selected && value[5] === 0) { prior.result = selected; this.active.delete(id); return; }
+    }
+    this.invalid = true;
+  }
+  captureLive(read: typeof processImageMemory = processImageMemory): void {
+    const retain = (before: Image | undefined, after: Image): Image => ({
+      hwmKB: Math.max(before?.hwmKB ?? 0, after.hwmKB ?? 0) || undefined,
+      virtualKB: Math.max(before?.virtualKB ?? 0, after.virtualKB ?? 0) || undefined,
+    });
+    this.image = retain(this.image, read(this.pid));
+    for (const id of this.active) {
+      const value = this.native.get(id)!;
+      if (value.pid > 0) value.image = retain(value.image, read(value.pid));
+    }
+  }
+  finish(rawWorkerKB: number, platform = process.platform): { rssKB: number; rawRssKB: number; rssSources: HookRssSources } {
+    const self = this.self;
+    const hwm = Math.max(this.image.hwmKB ?? 0, self?.source === "VmHWM" ? self.kb : 0);
+    const virtual = Math.max(this.image.virtualKB ?? 0, self?.source === "vmpeak-bound" ? self.kb : 0);
+    const ownRaw = platform !== "linux" && self?.source === "platform-rusage" ? self.kb : rawWorkerKB;
+    const own = selectHookRss(platform, hwm, ownRaw, virtual);
+    const sources = [rssSource(own)];
+    const native = new Map<number, HookRssReading>();
+    for (const [id, value] of this.native) {
+      const given = value.result;
+      const selected = given && !given.known && !value.image?.hwmKB && !value.image?.virtualKB ? given : selectHookRss(platform,
+        Math.max(value.image?.hwmKB ?? 0, given?.source === "VmHWM" ? given.kb : 0), given?.rawKB ?? 0,
+        Math.max(value.image?.virtualKB ?? 0, given?.source === "vmpeak-bound" ? given.kb : 0));
+      native.set(id, selected); sources.push(rssSource(selected));
+    }
+    let nativeKB = 0;
+    for (const group of this.overlaps) {
+      nativeKB = Math.max(nativeKB, group.reduce((sum, id) => sum + native.get(id)!.kb, 0));
+    }
+    const rssSources = combineRssSources(...sources);
+    if (this.invalid) rssSources.unavailable++;
+    const combined = own.kb + nativeKB;
+    return { rssKB: platform === "linux" ? combined : Math.max(combined, rawWorkerKB), rawRssKB: rawWorkerKB, rssSources };
+  }
+}

package/src/hook-spool.ts

@@ -1,31 +1,45 @@
+import { assertFormatFloor, FormatFloorError } from "./memory/formats.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, opendirSync, readSync, renameSync, rmSync, writeFileSync, type Stats } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import type { CaptureAppend, CaptureInput } from "./memory/capture.ts";
-import { normalizeCaptureFields, type NormalizedCaptureFields } from "./memory/capture-input.ts";
+import { CAPTURE_MAX_EXCERPT, clipCaptureUtf8, normalizeCaptureFields, toolCaptureExcerpt, toolInputLine, type CaptureFields, type NormalizedCaptureFields } from "./memory/capture-input.ts";
 import { canonicalPath, realPath } from "./memory/platform.ts";
 import { createStandalonePolicy, type StandalonePolicyOptions } from "./memory/policy.ts";
 import { configuredPolicyOptions, loadAmemConfig, repoConfigRoot } from "./memory/config.ts";
 import { fold } from "./memory/policy.ts";
+import { stripPrivateSpans } from "./memory/private-spans.ts";
 import { looksSecret } from "./memory/screen.ts";
 import { appendMetrics, type CaptureDropReason } from "./memory/metrics.ts";
 import { projectState } from "./memory/lifecycle.ts";
 import { HOOK_EVENTS, HOOK_INPUT_BYTES } from "./hook-contract.ts";
 
-const SCHEMA = "agent-mem.hook-capture/v1";
+// #199: v1 records (closed key set, no format field) are read, never written. Every 0.14-0.17 decoder deletes a record it cannot verify,
+// so a record that adds a field publishes under a name the v1 pattern does not match (`hook-v2-`); old versions then ignore it
+// (they still count it toward their file and byte caps). A later format that adds fields takes a new prefix again.
+// #203: format 3 (`hook-v3-`) carries every record 0.18.0 cannot decode, today jcode-agent rows; 0.14-0.18 match neither
+// `hook-` nor `hook-v2-` for it, so they leave it alone. Claude native rows stay format 2, byte for byte, so 0.18.0 keeps draining them.
+const SCHEMA = "agent-mem.hook-capture/v1", FAMILY = "agent-mem.hook-capture", FORMAT = 2, PREFIX = "hook-v2-", FORMAT_V3 = 3, PREFIX_V3 = "hook-v3-";
 const RECORD_BYTES = HOOK_INPUT_BYTES + 8192, MAX_FILES = 256, MAX_BYTES = 2 * 1024 * 1024;
 const DRAIN_FILES = 32, DRAIN_BYTES = 256 * 1024;
 // ponytail: a finite native admission reserve covers deferred replay, not unlimited locked intake.
 // Upgrade: coordinated append-only capacity accounting and observable backpressure at exhaustion.
 const CAPACITY_FILES = 32, CAPACITY_BYTES = 256 * 1024;
-const namePattern = /^(hook-([a-f0-9]{64})-([a-f0-9]{64})-([a-f0-9]{32})\.json)(?:\.draining-[a-f0-9]{24})?$/;
+const namePattern = /^(hook-(?:v[23]-)?([a-f0-9]{64})-([a-f0-9]{64})-([a-f0-9]{32})\.json)(?:\.draining-[a-f0-9]{24})?$/;
 const hash = (value: string | Uint8Array) => createHash("sha256").update(value).digest("hex");
-interface Record { schema: typeof SCHEMA; cwd: string; scope: string | null; root?: string; nonce: string; capture: NormalizedCaptureFields }
+interface Record { schema: string; format?: number; cwd: string; scope: string | null; root?: string; nonce: string; capture: NormalizedCaptureFields }
 export interface PendingHookCapture { name: string; cwd: string; receipt: string; deferred?: true; backlog?: true }
 export class HookSpoolFull extends Error { constructor() { super("hook storage full"); } }
-interface Options { cwd: string; base: string; policy?: StandalonePolicyOptions; deferAtCapacity?: true }
+/** #203: the agent a staged record belongs to. Claude hooks and jcode lifecycle observers share this spool, budget and replay. */
+export const HOOK_AGENTS = ["claude", "jcode"] as const;
+export type HookAgent = typeof HOOK_AGENTS[number];
+interface Options { cwd: string; base: string; policy?: StandalonePolicyOptions; deferAtCapacity?: true; agent?: HookAgent }
 const directory = (base: string) => join(base, "hook-spool");
+/** A hook below the home's hook-spool floor (#199 AC5) stages, drains and maintains nothing; it still never denies a native action. */
+function belowFloor(base: string): boolean {
+  try { assertFormatFloor(base, "hook-spool"); return false; } catch (error) { if (error instanceof FormatFloorError) return true; throw error; }
+}
 function physicalRoot(cwd: string): string {
   const stat = lstatSync(cwd);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("hook root unavailable");
@@ -264,21 +278,26 @@ function claimOwned(base: string, name: string, file: OwnedFile): OwnedFile | un
   const owned = { ...file, file: claim };
   return owns(owned) ? owned : undefined;
 }
-function decoded(file: OwnedFile): { value: Record; bytes: Buffer } | undefined {
+/** `unknown`: a valid envelope (cwd, nonce, scope) under an unknown or newer schema. It stays pending until the TTL, never read as corrupt. */
+function decoded(file: OwnedFile): { value: Record; bytes: Buffer; unknown?: true } | undefined {
   if (file.initial.size > RECORD_BYTES) return undefined; // Positively oversized: do not materialize its body.
   const bytes = Buffer.alloc(file.initial.size);
   if (readSync(file.fd, bytes, 0, bytes.length, 0) !== bytes.length || !owns(file)) throw new Error("hook record changed");
   try {
     const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) as Record;
-    if (!value || typeof value !== "object" || Array.isArray(value) || ![5, 6].includes(Object.keys(value).length)
-      || Object.keys(value).some(key => !["schema", "cwd", "scope", "root", "nonce", "capture"].includes(key))
-      || value.root !== undefined && (typeof value.root !== "string" || !/^[a-f0-9]{64}$/.test(value.root))
-      || value.schema !== SCHEMA || typeof value.cwd !== "string" || !/^[a-f0-9]{32}$/.test(value.nonce)
+    if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.cwd !== "string" || typeof value.nonce !== "string" || !/^[a-f0-9]{32}$/.test(value.nonce)
       || value.scope !== null && (typeof value.scope !== "string" || !/^[a-f0-9]{64}$/.test(value.scope))) return undefined;
+    const v1 = value.schema === SCHEMA && !("format" in value), v3 = value.schema === FAMILY && value.format === FORMAT_V3;
+    const current = value.schema === FAMILY && value.format === FORMAT || v3;
+    if (!v1 && !current) return typeof value.schema === "string" ? { value, bytes, unknown: true } : undefined;
+    const keys = current ? 1 : 0;
+    if (![5 + keys, 6 + keys].includes(Object.keys(value).length)
+      || Object.keys(value).some(key => !["schema", "cwd", "scope", "root", "nonce", "capture", ...current ? ["format"] : []].includes(key))
+      || value.root !== undefined && (typeof value.root !== "string" || !/^[a-f0-9]{64}$/.test(value.root))) return undefined;
     const c = value.capture;
     if (!c || typeof c !== "object" || Array.isArray(c) || Object.keys(c).length < 8 || Object.keys(c).length > 10
       || Object.keys(c).some(key => !["at", "agent", "event", "tool", "paths", "status", "excerpt", "bytes", "session", "subagent"].includes(key))
-      || c.agent !== "claude" || !(HOOK_EVENTS as readonly string[]).includes(c.event)
+      || !(HOOK_AGENTS as readonly string[]).includes(c.agent) || (c.agent === "claude" && !["Title", "Recap", "Compact"].includes(c.event)) === v3 || ![...HOOK_EVENTS, "Title", "Recap", "Compact"].includes(c.event)
       || typeof c.at !== "string" || !Number.isFinite(Date.parse(c.at)) || typeof c.excerpt !== "string"
       || !Array.isArray(c.paths) || c.paths.some(path => typeof path !== "string")) return undefined;
     const normalized = normalizeCaptureFields({ agent: c.agent, event: c.event, at: c.at, paths: c.paths, excerpt: c.excerpt,
@@ -394,7 +413,11 @@ function retireUnresolved(base: string, _admittingCwd: string | undefined, inven
         const record = decoded(file);
         const valid = record && hash(record.value.cwd) === match[2] && record.value.nonce === match[4] && (record.value.scope ?? "0".repeat(64)) === match[3];
         let reason: CaptureDropReason | undefined;
-        if (valid) {
+        if (valid && record.unknown) {
+          // #199: a newer writer's record waits for a reader that knows it, then leaves with a counted reason, never at once.
+          if (Date.now() - row.modified < RETIRE_AFTER_MS) continue;
+          reason = "unknown_schema_expired";
+        } else if (valid) {
           if (Date.now() - Date.parse(record.value.capture.at) < RETIRE_AFTER_MS) continue;
           try { const cwd = lstatSync(record.value.cwd); if (!cwd.isDirectory() || cwd.isSymbolicLink()) reason = "cwd_removed"; }
           catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") reason = "cwd_removed"; }
@@ -425,7 +448,7 @@ function retireUnresolved(base: string, _admittingCwd: string | undefined, inven
  * discard a valid pending record; only positively invalid publications leave admission. */
 export function quarantineHookScope(options: { cwd: string; base: string; scope: string }): { retired: number } {
   let retired = 0;
-  if (!/^[a-f0-9]{64}$/.test(options.scope)) return { retired };
+  if (belowFloor(options.base) || !/^[a-f0-9]{64}$/.test(options.scope)) return { retired };
   const cwd = realPath(options.cwd), base = canonicalPath(options.base), cwdHash = hash(cwd);
   trimQuarantine(base);
   const rows = entries(base).filter(row => {
@@ -451,7 +474,7 @@ export function quarantineHookScope(options: { cwd: string; base: string; scope:
 
 /** Only screened normalized capture fields are retained, never the native input envelope. */
 export async function stageHookCapture(event: string, input: unknown, options: Options): Promise<PendingHookCapture | undefined> {
-  if (!(HOOK_EVENTS as readonly string[]).includes(event) || options.policy?.host) return undefined;
+  if (!(HOOK_EVENTS as readonly string[]).includes(event) || options.policy?.host || belowFloor(options.base)) return undefined;
   const policy = createStandalonePolicy(configuredPolicyOptions(options.base, options.cwd, options.policy));
   if (!await policy.screen(input)) return undefined;
   const value = structuredClone(input) as {[key: string]: unknown};
@@ -465,19 +488,47 @@ export async function stageHookCapture(event: string, input: unknown, options: O
   // F4: the person's configured caps apply at staging. Replay (`decoded`) re-normalizes with the built-in caps, which are the ceiling, so a record
   // staged under a tighter cap still verifies after the cap is raised or removed.
   const configured = loadAmemConfig(base, repoConfigRoot(cwd)).config;   // the repository's .amem/config narrows here too
+  const toolEvent = event === "PreToolUse" || event === "PostToolUse" || event === "PostToolUseFailure";
+  const contentText = typeof content === "string" ? content : JSON.stringify(content) ?? "";
+  const excerpt = toolEvent
+    ? clipCaptureUtf8(toolCaptureExcerpt(toolInputLine(tool), contentText), Math.min(CAPTURE_MAX_EXCERPT, configured.excerptBytes ?? CAPTURE_MAX_EXCERPT))
+    : contentText;
   // #173: attribution. Only a fixed-width hash of the native session id is kept, never the id or transcript path;
   // a non-empty agent_id marks a subagent (or in-process teammate) event. Both are read from the already-screened input.
   const session = typeof value.session_id === "string" && value.session_id.length > 0 && value.session_id.length <= 256 ? hash(`amem-session\0${value.session_id}`).slice(0, 16) : undefined;
   const subagent = typeof value.agent_id === "string" && value.agent_id.length > 0;
-  const capture = normalizeCaptureFields({ agent: "claude", event, paths, status: event === "PostToolUseFailure" ? "failed" : "ok",
+  const capture = normalizeCaptureFields({ agent: options.agent ?? "claude", event, paths, status: event === "PostToolUseFailure" ? "failed" : "ok",
     ...(session ? { session } : {}), ...(subagent ? { subagent: true } : {}),
-    ...(typeof value.tool_name === "string" ? { tool: value.tool_name } : {}), excerpt: typeof content === "string" ? content : JSON.stringify(content) },
+    ...(typeof value.tool_name === "string" ? { tool: value.tool_name } : {}), excerpt },
     undefined,
-    (text: string) => looksSecret(text) || configured.piiPatterns.some(pattern => fold(text).includes(fold(pattern))),   // the configured patterns redact the excerpt, as the store does
+    (text: string) => looksSecret(text) || configured.piiPatterns.some(pattern => fold(text).includes(fold(pattern))),   // keep the normalizer's screen as well as the full envelope and bounded tool text screens
     { excerptBytes: configured.excerptBytes, paths: configured.capturePaths, ...(configured.denyPaths.length ? { denyPaths: configured.denyPaths } : {}) });
+  // The unchanged normalizer screen and final whole-capture policy also cover the joined input/content.
+  // Enriched tool rows are refused rather than persisting the normalizer's redaction marker.
+  if (toolEvent && capture.excerpt === "[secret-screened]") return undefined;
   if (!await policy.screen({ cwd, capture })) return undefined;
-  const scope = hookCaptureScope(cwd, base) ?? null, nonce = randomBytes(16).toString("hex");
-  const record: Record = { schema: SCHEMA, cwd, scope, root: physicalRoot(cwd), nonce, capture }, bytes = JSON.stringify(record);
+  return publishCapture(event, capture, { ...options, cwd, base });
+}
+
+/** Transcript text is screened in full before caps, then shares the ordinary durable spool. */
+export async function stageTranscriptCapture(input: CaptureFields, options: Options, receiptIdentity?: string): Promise<PendingHookCapture | undefined> {
+  if (options.policy?.host || belowFloor(options.base) || input.agent !== "claude" || !["Title", "Recap", "Compact"].includes(input.event)) return;
+  const cwd = realPath(options.cwd), base = canonicalPath(options.base);
+  const policy = createStandalonePolicy(configuredPolicyOptions(base, cwd, options.policy));
+  if (!await policy.screen({ cwd, input })) return;
+  const configured = loadAmemConfig(base, repoConfigRoot(cwd)).config;
+  const capture = normalizeCaptureFields({ ...input, excerpt: clipCaptureUtf8(stripPrivateSpans(input.excerpt ?? ""), Math.min(CAPTURE_MAX_EXCERPT, configured.excerptBytes ?? CAPTURE_MAX_EXCERPT)) }, undefined,
+    text => looksSecret(text) || configured.piiPatterns.some(pattern => fold(text).includes(fold(pattern))),
+    { excerptBytes: configured.excerptBytes, paths: configured.capturePaths, denyPaths: configured.denyPaths });
+  if (capture.excerpt === "[secret-screened]" || !await policy.screen({ cwd, capture })) return;
+  return publishCapture(input.event, capture, { ...options, cwd, base }, hash(receiptIdentity === undefined ? JSON.stringify(capture) : JSON.stringify([capture, receiptIdentity])).slice(0, 32));
+}
+
+function publishCapture(event: string, capture: NormalizedCaptureFields, options: Options, nonce = randomBytes(16).toString("hex")): PendingHookCapture {
+  const { cwd, base } = options;
+  const scope = hookCaptureScope(cwd, base) ?? null;
+  const v3 = capture.agent !== "claude" || ["Title", "Recap", "Compact"].includes(event);
+  const record: Record = { schema: FAMILY, format: v3 ? FORMAT_V3 : FORMAT, cwd, scope, root: physicalRoot(cwd), nonce, capture }, bytes = JSON.stringify(record);
   if (Buffer.byteLength(bytes) > RECORD_BYTES) throw new Error("hook record bound");
   const dir = directory(base), writing = join(dir, ".writing"); privateDirectory(dir); privateDirectory(writing);
   let destination = dir, deferred = false, backlog = false;
@@ -506,7 +557,7 @@ export async function stageHookCapture(event: string, input: unknown, options: O
       deferred = true;
     }
   }
-  const name = `hook-${hash(cwd)}-${scope ?? "0".repeat(64)}-${nonce}.json`, temporary = join(writing, name);
+  const name = `${v3 ? PREFIX_V3 : PREFIX}${hash(cwd)}-${scope ?? "0".repeat(64)}-${nonce}.json`, temporary = join(writing, name);
   try { writeFileSync(temporary, bytes, { mode: 0o600, flag: "wx" }); renameSync(temporary, join(destination, name)); }
   finally { rmSync(temporary, { force: true }); }
   return { name, cwd, receipt: hash(bytes), ...(deferred ? { deferred: true as const } : {}), ...(backlog ? { backlog: true as const } : {}) };
@@ -524,6 +575,7 @@ export function hookCapturePending(base: string, name: string): boolean {
 export async function drainHookCaptures(options: Options & { project: string; expectedScope?: string; current?: string; timeRemaining?: () => number },
   append: (input: CaptureInput, receipt: string) => CaptureAppend): Promise<{ captured: string[]; blocked: number }> {
   const cwd = realPath(options.cwd), base = canonicalPath(options.base), stamp = hookCaptureScope(cwd, base), captured: string[] = [];
+  if (belowFloor(base)) return { captured, blocked: 1 };
   if (!stamp || options.expectedScope !== undefined && options.expectedScope !== stamp) return { captured, blocked: 1 };
   // F4: the configured policy applies at drain too. `options.policy` carries it, so the anchored line below (a test diagnostic matches its exact text) stays as it was.
   options = { ...options, policy: configuredPolicyOptions(base, cwd, options.policy) };
@@ -548,6 +600,14 @@ export async function drainHookCaptures(options: Options & { project: string; ex
       if (!record || record.value.cwd !== cwd || record.value.scope !== null && record.value.scope !== stamp || record.value.nonce !== match[4]) {
         retireClaim(base, claim, false); blocked++; continue;
       }
+      // #199: an unknown or newer schema stays claimed and pending (later passes reclaim it) until the TTL, then retires with a counted reason.
+      // ponytail: pending unknown records still take drain slots oldest first; a writer that adds fields uses a new prefix, so this is the fallback only.
+      if (record.unknown) {
+        if (Date.now() - row.modified < RETIRE_AFTER_MS) { blocked++; continue; }
+        appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", captureDrops: 1, captureDropReason: "unknown_schema_expired" }]);
+        if (!retireClaim(base, claim, false)) blocked++;
+        continue;
+      }
       const value = record.value, c = value.capture;
       if (value.scope === null) { blocked++; continue; }
       // #15 T5: a project the person archived or forgot takes no new capture. Retire the record here with a counted reason instead of leaving it pending:

package/src/hook-transcript.ts

@@ -0,0 +1,189 @@
+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 } 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 }
+interface Options { cwd: string; base: string; deadline: number; policy?: StandalonePolicyOptions }
+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"];
+    while (start < length && performance.now() < options.deadline) {
+      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 staged = await 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);
+            if (staged && title) cursor.title = title;
+          } 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 && performance.now() >= options.deadline) 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); }
+  }
+}