@staix/agent-mem 0.5.0 → 0.7.0

package/src/commands-table.ts

@@ -1,3 +1,4 @@
+import { HOOK_EVENTS } from "./hook-contract.ts";
 import { GOAL_STATES, KINDS } from "./memory/store.ts";
 
 export interface OptionDefinition { description: string; value?: "text" | "path" | readonly string[] }
@@ -7,36 +8,71 @@ export interface CommandDefinition {
   options?: Record<string, OptionDefinition>;
   args?: readonly ArgumentDefinition[];
   commands?: Record<string, CommandDefinition>;
-  mutates?: boolean | "apply" | "label";
+  /** `confirm`: previews without `--confirm` (a read), and mutates with it (#15 T5: gc, project forget, capacity apply). */
+  mutates?: boolean | "apply" | "label" | "confirm";
   policyFree?: boolean;
   defaultCommand?: string;
 }
 const flag = (description: string): OptionDefinition => ({ description });
 const text = (description: string): OptionDefinition => ({ description, value: "text" });
 const json = { "--json": flag("Print JSON where supported") };
-const policy = { "--policy-free": flag("Explicitly bypass host privacy policy") };
+const history = { "--history": flag("Read retained supersession/expiry history; forgotten text stays hidden"), "--as-of": text("Past canonical UTC date or timestamp; current forget/prune masks still apply") };
+const policy = { "--policy-free": flag("Accepted and ignored: the configured privacy policy always applies") };
 const filters = { ...json, "--tier": { description: "Memory tier", value: ["short", "long"] } as OptionDefinition,
   "--kind": { description: "Note kind", value: KINDS }, "--peer": text("Author peer"), "--machine": text("Machine ID"),
   "--since": text("ISO date or time"), "--limit": text("Maximum results") };
 export const GLOBAL_OPTIONS = { "--help": flag("Show help") };
 export const ROOT_OPTIONS = { "--version": flag("Show version"), ...json };
 export const COMMANDS: Record<string, CommandDefinition> = {
+  setup: { description: "Preview reversible MCP and hook setup for native coding CLIs; apply and undo are person-only", options: { "--apply": flag("Apply after terminal confirmation"), "--undo": flag("Restore original configuration after confirmation") }, args: [{ name: "target", values: ["claude", "codex", "kimi", "pi", "all"] }] },
   mcp: { description: "Run the project-bound MCP stdio server for this session" },
-  "vault-candidates": { description: "List screened durable curated vault candidates", options: { ...json, "--limit": text("Maximum candidates (1..100)") } },
-  list: { description: "List memory", options: filters },
-  search: { description: "Search memory", options: filters, args: [{ name: "words", variadic: true }] },
-  show: { description: "Show a note", options: json, args: [{ name: "id" }] },
-  graph: { description: "Show a graph", options: { ...json, "--hops": { description: "Graph depth", value: ["1", "2"] } }, args: [{ name: "id-or-node" }] },
+  hook: { description: "Run a fail-open, context-only Claude Code hook", args: [{ name: "event", values: [...HOOK_EVENTS] }] },
+  ingest: { description: "Incrementally capture native session transcripts without a watcher", options: { ...json, "--since": text("ISO date or time") }, args: [{ name: "kind", values: ["codex", "kimi", "pi"] }] },
+  "vault-candidates": { description: "List screened durable curated vault candidates (per project, or across projects)", options: { ...json, "--limit": text("Maximum candidates per project (1..100)"),
+    "--all-projects": flag("List every active project's candidates; the reply says it crossed projects"), "--project": text("List one named project's candidates") } },
+  list: { description: "List memory", options: { ...filters, ...history } },
+  search: { description: "Search memory", options: { ...filters, ...history, "--all-projects": flag("Search every active project; the reply says it crossed projects"),
+    "--include-archived": flag("With --all-projects, also read archived projects") }, args: [{ name: "words", variadic: true }] },
+  brief: { description: "Read intent/path memory: fails first, then decisions and contracts; untrusted data within a UTF-8 byte cap", options: { ...json,
+    "--for": text("Explicit intent"), "--paths": text("Repeatable named path"), "--symbols": text("Repeatable named symbol"), "--bytes": text("Complete brief-body byte cap (1..8192, default 2048)") } },
+  projects: { description: "List the project shards of this memory home (#15 D3)", options: { ...json, "--all": flag("Include forgotten projects (archived ones are always listed)") } },
+  usage: { description: "Totals and the largest project shards", options: { ...json, "--limit": text("Largest shards to list (1..100)"), "--all": flag("Include forgotten projects") } },
+  eval: { description: "Replay a local question set against the ranked store.search (the ranking MCP and hub recall use, not the `search` command's substring filter) and report recall@k and MRR (no model, no network; the built-in synthetic set without --set)", options: { ...json,
+    "--set": { description: "A question set file (amem.eval/v1); with entries it is self-contained, without them its ids name entries of this project", value: "path" }, "--k": text("Cutoffs, comma separated (default 1,5,10; each 1..100)") } },
+  gc: { description: "Apply each shard's retention and cap across shards in bounded batches (preview without --confirm)", mutates: "confirm", options: {
+    ...json, "--confirm": flag("Evict now; without it, preview only"), "--batches": text("evict() windows per shard in this run (1..1000, default 1)") } },
+  project: { description: "Per-project lifecycle and export (#15 D3): one project only", options: json, commands: {
+    export: { description: "Write one project's capture, curated notes, goals and work lists to a new bundle file (never overwrites)", options: { "--to": { description: "Destination file, outside the memory home", value: "path" }, ...policy },
+      args: [{ name: "key" }] },
+    archive: { description: "Take a cold project out of recall (append-only op; unarchive brings it back)", args: [{ name: "key" }], mutates: true },
+    unarchive: { description: "Bring an archived project back into recall (append-only op)", args: [{ name: "key" }], mutates: true },
+    forget: { description: "Forget one project for good (append-only op; preview without --confirm)", options: { "--confirm": flag("Record the forget after the preview") }, args: [{ name: "key" }], mutates: "confirm" },
+  } },
+  show: { description: "Show a note", options: { ...json, ...history }, args: [{ name: "id" }] },
+  graph: { description: "Show a graph", options: { ...json, ...history, "--hops": { description: "Graph depth", value: ["1", "2"] } }, args: [{ name: "id-or-node" }] },
   suggestions: { description: "List pending suggestions", options: json },
   confirm: { description: "Confirm a suggestion", options: json, args: [{ name: "id" }], mutates: true },
   reject: { description: "Reject a suggestion", options: json, args: [{ name: "id" }], mutates: true },
-  promote: { description: "Promote a note", options: { ...json, ...policy }, args: [{ name: "id" }], mutates: true, policyFree: true },
+  promote: { description: "Promote a note (--to repo: append its screened line to this repository's .amem/log.jsonl)", options: { ...json, ...policy, "--to": { description: "Promote into the repository scope", value: ["repo"] },
+    "--confirm": flag("With --to repo: append the previewed line"), "--confirm-public": text("With --to repo, unless the repository is verified private: the first 8 characters of the entry id") }, args: [{ name: "id" }], mutates: true, policyFree: true },
+  repo: { description: "The repository scope (#15 D6): this repository's .amem/log.jsonl", options: json, defaultCommand: "status", commands: {
+    status: { description: "Show the repository log, its entries and what the screen withheld" },
+    attributes: { description: "Add the merge=union entry for .amem/log.jsonl to .gitattributes (preview without --confirm; never committed)", mutates: "confirm", options: { "--confirm": flag("Write after the preview") } },
+  } },
   demote: { description: "Demote a note", options: json, args: [{ name: "id" }], mutates: true },
   forget: { description: "Forget a note", options: json, args: [{ name: "id" }], mutates: true },
+  note: { description: "Write notes as the person (F6)", options: json, commands: {
+    add: { description: "Add one curated note: text as arguments, `-` to type it on the terminal until end of input, or no text to open $EDITOR. A fail note takes --approach, --symptom, --cause, --evidence (repeatable) and --retry-when", mutates: true, options: {
+      "--kind": { description: "Note kind (default finding)", value: KINDS }, "--tier": { description: "Memory tier (default long)", value: ["short", "long"] },
+      "--scope": { description: "Scope (default project)", value: ["project", "shared"] }, "--title": text("One-line title"),
+      "--approach": text("fail: what was tried"), "--symptom": text("fail: what went wrong"), "--cause": text("fail: why"), "--evidence": text("fail: a reference (repeatable)"), "--retry-when": text("fail: what would make the approach worth retrying") },
+      args: [{ name: "text", variadic: true }] },
+  } },
   supersede: { description: "Replace a note", options: json, args: [{ name: "old-id" }, { name: "new-id" }], mutates: true },
   rebuild: { description: "Rebuild the derived index", options: json, mutates: true },
   dedupe: { description: "Preview duplicate reconciliation", options: { ...json, "--apply": flag("Append reconciliation operations") }, mutates: "apply" },
-  sync: { description: "Sync a private remote", options: { ...json, ...policy, "--remote": text("Private git URL") }, mutates: true, policyFree: true },
+  sync: { description: "Sync a private remote (--if-due: only when the schedule and the failure backoff allow it; --force ignores both)", options: { ...json, ...policy, "--remote": text("Private git URL"),
+    "--if-due": flag("Sync only when due (hourly after a success, 15 minutes doubling to a day after failures); stops after 30 seconds"), "--force": flag("With --if-due: ignore the schedule and the backoff") }, mutates: true, policyFree: true },
   machine: { description: "Show or label this machine", options: { ...json, "--label": text("Machine label") }, mutates: "label" },
   import: { description: "Import external memory", options: { ...json, ...policy, "--db": { description: "SQLite database file", value: "path" }, "--limit": text("Maximum observations"), "--restart": flag("Restart import cursor") }, mutates: true, policyFree: true,
     commands: { "claude-mem": { description: "Import claude-mem observations" } } },
@@ -44,7 +80,7 @@ export const COMMANDS: Record<string, CommandDefinition> = {
     list: { description: "List goals", options: { "--all": flag("Include completed goals") } },
     show: { description: "Show a goal", args: [{ name: "id" }] },
     new: { description: "Create a goal", options: { "--milestone": text("Milestone"), "--depends": text("Dependency goal ID"), "--shared": flag("Share across projects") }, args: [{ name: "title", variadic: true }], mutates: true },
-    link: { description: "Link through ahub goal link", args: [{ name: "id" }, { name: "task-id" }], mutates: true },
+    link: { description: "Link a goal to a task of a host that has a task board (not available in amem alone)", args: [{ name: "id" }, { name: "task-id" }], mutates: true },
     state: { description: "Set goal state", args: [{ name: "id" }, { name: "state", values: GOAL_STATES }], mutates: true },
     done: { description: "Complete a goal", args: [{ name: "id" }], mutates: true },
     take: { description: "Take a goal lease", options: { "--force": flag("Override the prior lease") }, args: [{ name: "id" }], mutates: true },
@@ -52,25 +88,30 @@ export const COMMANDS: Record<string, CommandDefinition> = {
   review: { description: "Review machine-local non-evidentiary candidates", options: json, defaultCommand: "list", commands: {
     list: { description: "List review candidates", options: {
       "--status": { description: "Candidate status", value: ["pending", "accepting", "accepted", "rejected", "all"] },
-      "--kind": { description: "Candidate kind", value: ["correction", "fail", "decay", "memory"] }, "--limit": text("Maximum candidates (1..500)"),
+      "--kind": { description: "Candidate kind", value: ["correction", "fail", "decay", "memory", "promotion"] }, "--limit": text("Maximum candidates (1..500)"),
     } },
-    accept: { description: "Accept one candidate through the current memory policy", options: { ...policy, "--kind": { description: "Explicit standalone candidate kind for selected profiles", value: ["memory"] } }, args: [{ name: "full-candidate-id" }], mutates: true, policyFree: true },
+    accept: { description: "Accept one candidate through the current memory policy", options: { ...policy, "--kind": { description: "Require the selected candidate kind", value: ["correction", "fail", "decay", "memory", "promotion"] } }, args: [{ name: "full-candidate-id" }], mutates: true, policyFree: true },
     reject: { description: "Reject one candidate", args: [{ name: "full-candidate-id" }], mutates: true },
+    walk: { description: "Walk the pending candidates one by one: accept, edit (as a new note), reject, skip or quit", mutates: true, options: { "--kind": { description: "Candidate kind", value: ["correction", "fail", "decay", "memory", "promotion"] } } },
   } },
+  decay: { description: "Preview old live long-term notes unprotected by open goals; apply only after person review", mutates: "apply", options: {
+    ...json, "--days": text("Age in whole days (default 90)"), "--apply": flag("Show the exact revision preview and ask before applying"), "--forget": flag("Explicitly forget instead of demoting; confirmation names this action") }, args: [{ name: "id", variadic: true }] },
   migrate: { description: "Select a person-approved generation or deactivate it", mutates: true, options: {
     ...json, "--dry-run": flag("Read-only migration receipt"), "--generation": text("Explicit 32-hex generation ID"),
     "--resume": flag("Resume the recorded migration"), "--deactivate": flag("Select shared v1 without deleting a generation"),
     "--shards": flag("Migrate the curated home into project and user shards"),
   } },
   status: { description: "Report shard migration and pending old-layout appends", options: json },
+  doctor: { description: "One read-only report (F15): duplicates and stale notes, pending candidates, capture freshness per CLI, the brief's token cost, index equals rebuild, reader leases, the policy in effect, ingest and sync cadence", options: json },
   prune: { description: "Plan or apply exact-entry durable expiry in a generation", mutates: true, options: {
     ...json, "--cutoff": text("Canonical UTC expiry cutoff"), "--dry-run": flag("Print a local sealed plan without writes"),
     "--user": flag("Select the user shard explicitly after a curated split (default: current project)"),
     "--apply": flag("Apply the exact local plan"), "--plan": { description: "Sealed local plan JSON file", value: "path" },
   } },
   capacity: { description: "Report capture use and propose R6 bounds (R7)", options: { ...json, "--disk-share": text("Disk-share bound for the proposal (default 0.02)") }, commands: {
-    apply: { description: "Write the proposed (or given) bounds to the home capture config", mutates: true, options: {
-      ...json, "--cap-mb": text("Capture cap in MB"), "--retention-days": text("Capture retention in days"), "--confirm": flag("Write after the preview") } },
+    apply: { description: "Write the proposed (or given) bounds to the home capture config, or with --split each shard's share of the global budget", mutates: true, options: {
+      ...json, "--cap-mb": text("Capture cap in MB"), "--retention-days": text("Capture retention in days"), "--confirm": flag("Write after the preview"),
+      "--split": flag("Write the per-shard split of the global budget to each shard's own config") } },
   } },
   alias: { description: "Person-reviewed project key aliases (#15 D2)", options: json, defaultCommand: "list", commands: {
     list: { description: "List alias ops" },
@@ -149,5 +190,5 @@ export function commandHelp(): string {
   return ["usage: amem <command> [options]", "  [--help] [--version] [--json]", ...completionDefinitions().filter(row => row.path.length).map(row => {
     const names = [...row.path, ...row.args.map(arg => `<${arg.name}>`)].join(" ");
     return `  ${names}${Object.entries(row.options).map(([name, option]) => ` [${name}${option.value === undefined ? "" : ` <${Array.isArray(option.value) ? option.value.join("|") : option.value}>`}]`).join("")}`;
-  }), "--policy-free: use ahub memory for the host's privacy policy.", "Mutating commands require a terminal on stdin. Agents use the hub's hub_memory_* tools."].join("\n");
+  }), "--policy-free: accepted and ignored; the configured privacy policy (amem.config.json in the memory home, narrowed by .amem/config) always applies.", "Mutating commands require a terminal on stdin. Agents use the `amem mcp` server; the person reviews what agents propose with `amem review`."].join("\n");
 }

package/src/hook-contract.ts

@@ -0,0 +1,3 @@
+export const HOOK_EVENTS = ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "Stop", "SessionEnd"] as const;
+export type HookEvent = typeof HOOK_EVENTS[number];
+export const HOOK_INPUT_BYTES = 64 * 1024, HOOK_CONTEXT_BYTES = 1200, HOOK_OUTPUT_BYTES = 8192;

package/src/hook-git.ts

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { realPath } from "./memory/platform.ts";
+import { memoryGitArgv, memoryGitEnv } from "./memory/platform.ts";
+import type { ProjectGitRead } from "./memory/project.ts";
+
+/** Synchronous compatibility port for library callers, with shared Git hardening and
+ * bounded output. Its deadline check precedes each read but cannot interrupt a blocked
+ * spawnSync. Native hook workers use resolveHookProjectAsync and hookNative instead,
+ * keeping the JS deadline responsive and the native self-watchdog independent of Bun. */
+export function hookGit(timeRemaining: () => number, binary?: string): ProjectGitRead {
+  return (args, env) => {
+    const remaining = timeRemaining();
+    if (!Number.isFinite(remaining) || remaining <= 0) throw new Error("Git project identity unavailable");
+    const argv = memoryGitArgv(args); argv[0] = binary ?? hookGitBinary(env).file;
+    const result = Bun.spawnSync(argv, {
+      env: memoryGitEnv(env), stdin: "ignore", stdout: "pipe", stderr: "ignore", maxBuffer: 64 * 1024,
+    });
+    if (result.stdout.byteLength >= 64 * 1024) throw new Error("Git project identity unavailable");
+    return { status: result.exitCode, signal: result.signalCode ? String(result.signalCode) : undefined,
+      stdout: new TextDecoder("utf-8", { fatal: true }).decode(result.stdout) };
+  };
+}
+
+/** Only bypass Apple's selected /usr/bin/git shim, never a caller's custom PATH binary.
+ * Resolve the root-owned developer selection on disk, without launching xcrun on the hook deadline. */
+export function hookGitBinary(env: NodeJS.ProcessEnv = process.env): { file: string; revision: string } {
+  let file = realPath(Bun.which("git", { PATH: env.PATH ?? process.env.PATH ?? "" }) ?? (() => { throw new Error("Git unavailable"); })());
+  if (process.platform === "darwin" && file === "/usr/bin/git" && !env.DEVELOPER_DIR) {
+    try {
+      const selected = "/var/db/xcode_select_link", link = lstatSync(selected);
+      if (link.isSymbolicLink() && link.uid === 0) {
+        const candidate = realPath(join(realPath(selected), "usr", "bin", "git")), stat = lstatSync(candidate);
+        if (stat.isFile() && stat.uid === 0 && (stat.mode & 0o111)) file = candidate;
+      }
+    } catch { /* A missing/unproven selection keeps the PATH-selected Git and its normal refusal. */ }
+  }
+  const stat = lstatSync(file);
+  if (!stat.isFile() || !(stat.mode & 0o111)) throw new Error("Git unavailable");
+  return { file, revision: createHash("sha256").update(`${file}:${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}`).digest("hex") };
+}

package/src/hook-native.ts

@@ -0,0 +1,92 @@
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+export interface HookNativeUsage { rssKB: number; rawRssKB: number }
+// One native supervisor, with a native sleep watchdog rather than another Bun boot.
+// The leader waits for its watchdog even after stdin EOF, so losing the calling CLI
+// cannot let the owned command outlive the same remaining per-call deadline.
+const SUPERVISOR = [
+  'marker=$1; seconds=$2; shift 2; leader=$$',
+  // Fixed ps plus the unguessable invocation marker guards an externally killed/reused
+  // leader too. Normal completion never exits the leader before its group is reaped.
+  'owned() { identity=$(/bin/ps -ww -p "$leader" -o pgid=,command=) || return 1; case "$identity" in *"$marker"*) ;; *) return 1 ;; esac; set -f; set -- $identity; [ "$1" = "$leader" ]; }',
+  'reap() { if owned; then kill -KILL "-$leader"; fi; }',
+  '[ -x /bin/sleep ] && [ -x /bin/ps ] && owned || exit 125',
+  'trap reap EXIT HUP INT TERM',
+  '( /bin/sleep "$seconds" & sleeper=$!; kill -0 "$sleeper" 2>/dev/null || { reap; exit 125; }; printf "\\n%s:ARMED\\n" "$marker"; wait "$sleeper"; reap ) & watchdog=$!',
+  'kill -0 "$watchdog" 2>/dev/null || { reap; exit 125; }',
+  '"$@" </dev/null; code=$?; printf "\\n%s:%s\\n" "$marker" "$code"',
+  'read -r ignored || :',
+  'wait "$watchdog"',
+].join("; ");
+
+export async function hookNative(argv: readonly string[], env: NodeJS.ProcessEnv, timeRemaining: () => number, usage: HookNativeUsage, signal?: AbortSignal): Promise<{ status: number; stdout: string }> {
+  if (signal?.aborted) throw new Error("native metadata cancelled");
+  const remaining = timeRemaining();
+  if (!Number.isFinite(remaining) || remaining <= 1) throw new Error("native metadata deadline");
+  const marker = `AMEM_META_${randomBytes(16).toString("hex")}`, prefix = `\n${marker}:`, armedFrame = `${prefix}ARMED\n`;
+  const child = Bun.spawn(["/bin/sh", "-c", SUPERVISOR, "amem-hook-native", marker, String(remaining / 1000), ...argv],
+    { env, detached: true, stdin: "pipe", stdout: "pipe", stderr: "ignore" });
+  let exited = false, ownPeak = 0;
+  const exit = child.exited.then(code => { exited = true; return code; });
+  const stop = () => {
+    if (exited) return;
+    if (process.platform === "linux") try {
+      const match = /^VmHWM:\s+(\d+)\s+kB$/m.exec(readFileSync(`/proc/${child.pid}/status`, "utf8"));
+      if (match && Number.isSafeInteger(Number(match[1]))) ownPeak = Number(match[1]);
+    } catch { /* Fall back conservatively to reaped rusage. */ }
+    try { process.kill(-child.pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch { /* already exited */ } }
+  };
+  const reader = child.stdout.getReader();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let aborted: (() => void) | undefined;
+  try {
+    const read = async () => {
+      let text = "", bytes = 0, armed = false;
+      const decoder = new TextDecoder("utf-8", { fatal: true });
+      for (;;) {
+        const next = await reader.read();
+        if (next.done) throw new Error("native metadata incomplete");
+        bytes += next.value.byteLength;
+        if (bytes > 64 * 1024 + 128) throw new Error("native metadata bound");
+        text += decoder.decode(next.value, { stream: true });
+        if (text.includes(armedFrame)) { text = text.replace(armedFrame, ""); armed = true; }
+        const at = text.indexOf(prefix);
+        if (at < 0) continue;
+        const code = /^(\d{1,3})\n/.exec(text.slice(at + prefix.length));
+        if (!code || !armed) continue;
+        const status = Number(code[1]);
+        if (status > 255 || Buffer.byteLength(text.slice(0, at)) >= 64 * 1024) throw new Error("native metadata invalid");
+        return { status, stdout: text.slice(0, at) };
+      }
+    };
+    return await Promise.race([read(), new Promise<never>((_, reject) => {
+      timer = setTimeout(() => { stop(); reject(new Error("native metadata deadline")); }, remaining);
+    }), new Promise<never>((_, reject) => {
+      aborted = () => { stop(); reject(new Error("native metadata cancelled")); };
+      signal?.addEventListener("abort", aborted, { once: true });
+      if (signal?.aborted) aborted();
+    })]);
+  } finally {
+    if (aborted) signal?.removeEventListener("abort", aborted);
+    if (timer) clearTimeout(timer);
+    stop();
+    // SIGKILL was delivered to every member before waiting for our owned leader.
+    // Init can briefly retain zombie grandchildren; they cannot execute, and only
+    // their adopting reaper can remove those PIDs (we cannot waitpid a non-child).
+    await exit;
+    try { child.stdin.end(); } catch { /* pipe closed with the owned leader */ }
+    await reader.cancel().catch(() => {}); reader.releaseLock();
+    const raw = (child.resourceUsage()?.maxRSS ?? 0) / 1024;
+    usage.rawRssKB = Math.max(usage.rawRssKB, raw);
+    usage.rssKB = Math.max(usage.rssKB, process.platform === "linux" ? ownPeak || raw : Math.max(ownPeak, raw));
+  }
+}
+
+/** Same pinned ps format/hash as the shared process identity helper, with bounded owned native work. */
+export async function hookProcessSignature(timeRemaining: () => number, usage: HookNativeUsage): Promise<string> {
+  const result = await hookNative(["/bin/ps", "-p", String(process.pid), "-o", "lstart=,comm="],
+    { PATH: process.env.PATH ?? "", LC_ALL: "C", TZ: "UTC" }, timeRemaining, usage);
+  if (result.status !== 0 || !result.stdout.trim()) throw new Error("native process identity unavailable");
+  return createHash("sha256").update(result.stdout.trim()).digest("hex");
+}

package/src/hook-project.ts

@@ -0,0 +1,206 @@
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, opendirSync, readSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { hookGit, hookGitBinary } from "./hook-git.ts";
+import { hookCaptureScope } from "./hook-spool.ts";
+import { canonicalPath, realPath } from "./memory/platform.ts";
+import { memoryProjectKey, type ProjectGitRead } from "./memory/project.ts";
+import { memoryGitArgv, memoryGitEnv } from "./memory/platform.ts";
+import { hookNative, type HookNativeUsage } from "./hook-native.ts";
+
+// Bump the derived cache schema if the shared native project-key mapping changes.
+const SCHEMA = "agent-mem.hook-project/v1", CACHE_BYTES = 4096, CACHE_CWDS = 128;
+const hash = (text: string) => createHash("sha256").update(text).digest("hex");
+interface Binding { schema: typeof SCHEMA; cwd: string; scope: string; validity: string; binary: string; project: string }
+function read(file: string): Binding | undefined {
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > CACHE_BYTES || stat.mode & 0o077 || stat.uid !== process.getuid?.()) return undefined;
+    const bytes = Buffer.alloc(stat.size);
+    if (readSync(fd, bytes, 0, bytes.length, 0) !== bytes.length) return undefined;
+    const after = lstatSync(file);
+    if (after.dev !== stat.dev || after.ino !== stat.ino || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs) return undefined;
+    const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).sort().join() !== "binary,cwd,project,schema,scope,validity"
+      || value.schema !== SCHEMA || typeof value.cwd !== "string" || typeof value.scope !== "string" || !/^[a-f0-9]{64}$/.test(value.scope)
+      || typeof value.validity !== "string" || !/^[a-f0-9]{64}$/.test(value.validity) || typeof value.binary !== "string" || !/^[a-f0-9]{64}$/.test(value.binary) || typeof value.project !== "string" || !value.project || value.project.length > 2048 || /[\x00-\x1f\x7f]/.test(value.project)) return undefined;
+    return value;
+  } catch { return undefined; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+function publish(dir: string, file: string, value: Binding, maintain: boolean): void {
+  let temporary: string | undefined;
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(dir); if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+    chmodSync(dir, 0o700);
+    // Only old, owned publication names are eligible; a recent writer keeps its temp.
+    if (maintain) {
+      const scan = opendirSync(dir);
+      try {
+        for (let count = 0; count < CACHE_CWDS * 2; count++) {
+          const entry = scan.readSync(); if (!entry) break;
+          if (!/^\.[a-f0-9]{64}-[a-f0-9]{24}$/.test(entry.name)) continue;
+          const stale = join(dir, entry.name), before = lstatSync(stale, { throwIfNoEntry: false });
+          if (!before?.isFile() || before.nlink !== 1 || before.uid !== process.getuid?.() || Date.now() - before.mtimeMs < 60_000) continue;
+          const after = lstatSync(stale, { throwIfNoEntry: false });
+          if (after?.dev === before.dev && after.ino === before.ino && after.size === before.size && after.mtimeMs === before.mtimeMs) rmSync(stale);
+        }
+      } finally { scan.closeSync(); }
+    }
+    // ponytail: 128 cached cwd identities, one bounded derived value each. New cwd misses
+    // still resolve natively; a future cache policy may retire old entries without touching capture.
+    if (!lstatSync(file, { throwIfNoEntry: false })) {
+      const entries = opendirSync(dir);
+      try { for (let count = 0; count <= CACHE_CWDS; count++) { if (!entries.readSync()) break; if (count === CACHE_CWDS - 1) return; } }
+      finally { entries.closeSync(); }
+    }
+    const text = JSON.stringify(value); if (Buffer.byteLength(text) > CACHE_BYTES) return;
+    temporary = join(dir, `.${hash(value.cwd)}-${randomBytes(12).toString("hex")}`);
+    writeFileSync(temporary, text, { mode: 0o600, flag: "wx" }); renameSync(temporary, file);
+  } catch { /* Derived cache I/O never changes a successfully resolved identity. */ }
+  finally { if (temporary) try { rmSync(temporary, { force: true }); } catch { /* Cache cleanup stays advisory too. */ } }
+}
+interface ResolverOptions { cwd: string; base: string; scope?: string; timeRemaining: () => number; maintainCache?: boolean; gitRead?: ProjectGitRead; assertComplete?: () => void; env?: NodeJS.ProcessEnv }
+
+/** Prepare filesystem/cache binding once; suspended native reads replay only the shared resolver. */
+function prepareHookProject(options: ResolverOptions) {
+  const checkDeadline = () => {
+    const remaining = options.timeRemaining();
+    if (!Number.isFinite(remaining) || remaining <= 0) throw new Error("project deadline");
+  };
+  checkDeadline();
+  const cwd = realPath(options.cwd), base = canonicalPath(options.base), binary = hookGitBinary(options.env);
+  const scope = options.scope;
+  if (scope !== undefined && (!scope || hookCaptureScope(cwd, base) !== scope)) throw new Error("project scope changed");
+  const cwdStat = lstatSync(cwd);
+  const prefixConfig = join(dirname(dirname(binary.file)), "etc", "gitconfig");
+  // Unknown semantic scope cannot certify a reusable identity, but native Git can still
+  // resolve the current project for a read-only brief. Never read or publish cache in this case.
+  const validity = scope === undefined ? undefined : hookCaptureScope(cwd, base, true, prefixConfig);
+  const dir = join(base, "hook-project"), named = lstatSync(dir, { throwIfNoEntry: false });
+  const file = join(dir, `${hash(cwd)}.json`);
+  const cached = scope !== undefined && (!named || named.isDirectory() && !named.isSymbolicLink() && !(named.mode & 0o077)) ? read(file) : undefined;
+  const hit = cached?.cwd === cwd && cached.scope === scope && validity && cached.validity === validity && cached.binary === binary.revision && cacheableLocal(cwd, cached.project);
+  const verifyBinary = () => {
+    checkDeadline();
+    const currentBinary = hookGitBinary(options.env);
+    if (currentBinary.file !== binary.file || currentBinary.revision !== binary.revision) throw new Error("project binary changed");
+    checkDeadline();
+  };
+  const verify = () => {
+    verifyBinary();
+    // A known strong binding includes every semantic field. Only the uncached,
+    // unknown-validity case also needs its independent semantic scope check.
+    if (scope === undefined) {
+      const currentCwd = lstatSync(cwd);
+      if (realPath(options.cwd) !== cwd || currentCwd.dev !== cwdStat.dev || currentCwd.ino !== cwdStat.ino) throw new Error("project cwd changed");
+    } else {
+      const currentValidity = hookCaptureScope(cwd, base, true, prefixConfig);
+      if (currentValidity !== validity || !validity && hookCaptureScope(cwd, base) !== scope) throw new Error("project scope changed");
+    }
+    checkDeadline();
+  };
+  return { binary, verifyBinary, resolve(gitRead: ProjectGitRead, assertComplete?: () => void): string {
+    checkDeadline();
+    if (hit && cached) {
+      assertComplete?.(); verify();
+      return cached.project;
+    }
+    const project = memoryProjectKey(cwd, { repositoryIsolation: true, strictGitErrors: true, gitRead });
+    // The synchronous resolver can catch an unknown native read internally. Fence that
+    // suspended pass before any completion checks, cache publication or returned key.
+    assertComplete?.(); verify();
+    if (scope !== undefined && validity && cacheableLocal(cwd, project)) {
+      checkDeadline();
+      publish(dir, file, { schema: SCHEMA, cwd, scope, validity, binary: binary.revision, project }, options.maintainCache === true);
+    }
+    checkDeadline();
+    return project;
+  } };
+}
+
+/** Cache only a successful shared native resolver result, before alias resolution. */
+export function resolveHookProject(options: ResolverOptions): string {
+  const prepared = prepareHookProject(options);
+  return prepared.resolve(options.gitRead ?? hookGit(options.timeRemaining, prepared.binary.file), options.assertComplete);
+}
+
+/** A local key's superproject chain depends on outer Git indexes. Cache only ordinary
+ * standalone roots; linked/submodule/local nested layouts retain the native resolver. */
+function cacheableLocal(cwd: string, project: string): boolean {
+  if (!/.+@[a-f0-9]{8}$/.test(project)) return true;
+  if (!project.endsWith(`@${hash(cwd).slice(0, 8)}`)) return false;
+  try {
+    const git = lstatSync(join(cwd, ".git"));
+    if (!git.isDirectory() || git.isSymbolicLink()) return false;
+    for (let folder = dirname(cwd), depth = 0; depth < 32; folder = dirname(folder), depth++) {
+      if (lstatSync(join(folder, ".git"), { throwIfNoEntry: false })) return false;
+      if (folder === dirname(folder)) return true;
+    }
+  } catch { /* Unprovable ancestry keeps native resolution. */ }
+  return false;
+}
+
+/** Replay the shared synchronous resolver only after every requested native read is known.
+ * A suspended/partially resolved pass can never publish a cache entry or return a guessed key. */
+export async function resolveHookProjectAsync(options: { cwd: string; base: string; scope?: string; timeRemaining: () => number; maintainCache?: boolean; prefetch?: boolean }, usage: HookNativeUsage): Promise<string> {
+  const reads = new Map<string, ReturnType<ProjectGitRead>>();
+  const env = { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", AMEM_HOME: options.base };
+  const prepared = prepareHookProject({ ...options, env });
+  const suspended = new Error("native identity suspended");
+  const pending = new Map<string, { abort: AbortController; result: Promise<ReturnType<ProjectGitRead>>; usage: HookNativeUsage }>();
+  const active = new Set<string>(), overlaps: string[][] = [];
+  let prefetched = false;
+  const query = (args: string[]) => {
+    const key = JSON.stringify(args), existing = pending.get(key); if (existing) return existing.result;
+    if (pending.size >= 64) throw new Error("native identity query bound");
+    prepared.verifyBinary(); // No awaited native read may execute a replaced binary.
+    const argv = memoryGitArgv(args); argv[0] = prepared.binary.file;
+    const abort = new AbortController(), own = { rssKB: 0, rawRssKB: 0 };
+    active.add(key); overlaps.push([...active]);
+    const result = hookNative(argv, memoryGitEnv(env, { repositoryIsolation: true }), options.timeRemaining, own, abort.signal)
+      .finally(() => { active.delete(key); });
+    // Speculative failures have no authority until the shared resolver requests that read.
+    void result.catch(() => {});
+    pending.set(key, { abort, result, usage: own }); return result;
+  };
+  try {
+    for (let count = 0; count < 64; count++) {
+      let needed: { key: string; args: string[] } | undefined;
+      let result: string | undefined, failure: unknown;
+      try {
+        result = prepared.resolve((args) => {
+          const key = JSON.stringify(args);
+          const value = reads.get(key); if (value) return value;
+          needed ??= { key, args }; throw suspended;
+        }, () => { if (needed) throw suspended; });
+      } catch (error) { failure = error; }
+      if (!needed) { if (failure) throw failure; if (result !== undefined) return result; throw suspended; }
+      const request = needed as { key: string; args: string[] };
+      const demanded = query(request.args);
+      // A native read is requested only on a real cache miss. Prefetch the portable
+      // resolver's ordinary-repository metadata alongside origin, never an alternate
+      // identity algorithm. Only memoryProjectKey decides which replies it consumes.
+      if (options.prefetch === true && !prefetched && request.args.length === 5 && request.args[0] === "-C" && request.args.slice(2).join(" ") === "remote get-url origin") {
+        prefetched = true;
+        void query(["-C", request.args[1]!, "rev-parse", "--path-format=absolute", "--git-common-dir", "--git-dir", "--is-bare-repository", "--show-toplevel", "--show-superproject-working-tree"]);
+      }
+      reads.set(request.key, await demanded);
+    }
+    throw new Error("native identity query bound");
+  } finally {
+    // Never leave an unused prefetch or its descendants behind, even if origin alone
+    // resolved the key or a requested read failed. Abort still uses the owned reaper.
+    for (const child of pending.values()) child.abort.abort();
+    await Promise.allSettled([...pending.values()].map(child => child.result));
+    // Per-call peaks arrive at reap. Conservatively sum all calls whose owned
+    // lifetimes overlapped, rather than hiding concurrent helpers behind max().
+    for (const group of overlaps) {
+      usage.rssKB = Math.max(usage.rssKB, group.reduce((sum, key) => sum + pending.get(key)!.usage.rssKB, 0));
+      usage.rawRssKB = Math.max(usage.rawRssKB, group.reduce((sum, key) => sum + pending.get(key)!.usage.rawRssKB, 0));
+    }
+  }
+}

package/src/hook-resources.ts

@@ -0,0 +1,15 @@
+import { readFileSync } from "node:fs";
+
+/** Linux rusage includes the pre-exec launcher's inherited high-water value. VmHWM belongs
+ * to this process image, so a large test runner cannot be mistaken for resident hook memory.
+ * Unavailable telemetry falls back conservatively to rusage, never to zero. */
+export function hookPeakRssKB(): number {
+  if (process.platform === "linux") {
+    try {
+      const text = readFileSync("/proc/self/status", "utf8");
+      const match = /^VmHWM:\s+(\d+)\s+kB$/m.exec(text), peak = match && Number(match[1]);
+      if (peak && Number.isSafeInteger(peak) && peak > 0) return peak;
+    } catch { /* Non-proc Linux hosts retain the conservative historical measurement. */ }
+  }
+  return process.resourceUsage().maxRSS;
+}