@staix/agent-mem 0.18.0 → 0.19.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Bounded project memory tools and seven deterministic capture hooks, without a resident worker.",
   "mcpServers": {
     "agent-mem": {

package/README.md

@@ -2,7 +2,7 @@
 
 Curated memory with append-only JSONL logs, a derived SQLite index, short- and long-term tiers, a typed graph, goals with leases, and git sync between machines. Extracted from [agent-hub](https://github.com/STAIxBWLB/agent-hub), with compatible storage and entry IDs.
 
-Version: 0.18.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.19.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 
@@ -32,9 +32,11 @@ From a checkout, install development dependencies with `bun install` and run `bu
 
 ## Setup / plugin
 
+For Orca-managed Claude and Codex homes, setup writes the personal source that Orca copies into new sessions. Claude hooks go to `$HOME/.claude/settings.json`, while its MCP entry stays in the profile's `.claude.json`. Codex MCP and hooks go to `$HOME/.codex/config.toml` and `hooks.json`. Detection requires an exact managed-home shape under `ORCA_USER_DATA_PATH` (default `~/Library/Application Support/orca`); a similar directory elsewhere is unchanged. Preview lists each redirect and its reason. Start a new Orca session after applying. Existing matching managed-copy receipts migrate on apply; undo restores the files and bytes recorded for that installation. Codex hooks still require the person's native `/hooks` review; setup never grants trust or writes `trusted_hash`.
+
 `amem setup agy` registers MCP only in the current git repository's `.agents/mcp_config.json`, with an explicit absolute repository cwd and a private receipt per repository. `setup all` excludes agy; run it separately in each repository. Setup refuses tracked config files and JSONC, and warns when the file is not ignored. Restart Antigravity after applying, use one workspace per session, and ensure no global, plugin or running server is also named `amem`. No global configuration, ingest command or hook is installed. Undo removes `.agents` only when setup created it and it is still empty; pre-existing or nonempty directories remain. Older receipts still restore their configuration without directory cleanup. See the [Antigravity contract and capture limitation](docs/antigravity.md).
 
-`amem setup jcode` registers MCP only, using Jcode v0.99.1's global `JCODE_HOME/mcp.json` (default `~/.jcode/mcp.json`). An explicitly set `JCODE_HOME` must be absolute for amem setup: empty, relative and literal `~` values are refused. Unset uses the default, and absolute values retain their literal spelling without trimming. It owns only `servers.amem`, sets `shared: false` for a workspace-bound session, and preserves unrelated configuration bytes. Jcode has no native MCP add/remove command in this release, so setup edits the owned entry directly. No Jcode ingest command or capture hook is installed: saved messages lack per-message origin while the session cwd can change. Launch Jcode with `JCODE_DISABLE_CLAUDE_MCP=1` and without a same-name project override, which could otherwise replace the private binding. Use a new workspace-bound session when changing projects. See the [Jcode contract and capture limitation](docs/jcode.md).
+`amem setup jcode` registers MCP only, using Jcode v0.99.1's global `JCODE_HOME/mcp.json` (default `~/.jcode/mcp.json`). An explicitly set `JCODE_HOME` must be absolute for amem setup: empty, relative and literal `~` values are refused. Unset uses the default, and absolute values retain their literal spelling without trimming. It owns only `servers.amem`, sets `shared: false` for a workspace-bound session, and preserves unrelated configuration bytes. Jcode has no native MCP add/remove command in this release, so setup edits the owned entry directly. Setup also adds `amem hook jcode` to the `post_tool` and `turn_end` lifecycle hooks in `JCODE_HOME/config.toml`, keeping an existing user command for those events (array form). Each captured row is scoped by that event's `JCODE_HOOK_CWD`; events with no cwd or outside a Git repository are skipped. There is still no `amem ingest jcode`: saved messages lack per-message origin while the session cwd can change. Launch Jcode with `JCODE_DISABLE_CLAUDE_MCP=1` and without a same-name project override, which could otherwise replace the private binding. Use a new workspace-bound session when changing projects. See the [Jcode contract and capture limitation](docs/jcode.md).
 
 `amem setup gemini` registers MCP only, at user scope in Gemini CLI 0.61.0's `~/.gemini/settings.json` (`GEMINI_CLI_HOME`, which must be absolute, moves it). It runs the native `gemini mcp add --scope user` (and `remove` for an earlier entry) in a private staging `HOME`, owns only `mcpServers.amem` and keeps every unrelated setting. Antigravity's `~/.gemini/config/mcp_config.json` is a different client's file and is never read or written; `amem setup agy` stays per repository. A workspace `.gemini/settings.json` that defines `mcpServers.amem` overrides the user entry. Setup refuses settings that are not strict JSON (Gemini allows comments, but setup's exact undo needs strict JSON) and runtime paths containing `$`, which Gemini expands. No hook, ingest command or `GEMINI.md` edit: see [the Gemini CLI contract](docs/gemini-cli.md) for why transcripts are not ingested. `setup all` includes Gemini CLI when it is installed.
 
@@ -55,7 +57,9 @@ amem setup all --undo
 
 `--apply` and `--undo` are explicit writes; the default remains a read-only plan. They do not require a TTY prompt, and an agent marker supplies identity rather than a tool refusal. Follow workspace authorization for changes to machine configuration. Native Claude, Codex, Pi and Qwen MCP registration commands run in a private temporary HOME before the listed files are published; current Kimi Code uses its MCP JSON file. No AGENTS.md, CLAUDE.md or rule files are edited. Repeated apply is a no-op even after routine CLI metadata writes. Registrations use the absolute Bun path found on PATH, preserving its stable symlink rather than a versioned Cellar target; temporary package entries (such as bunx caches) are refused; reapply refreshes moved package/runtime locations automatically. Private receipts restore original bytes, permissions and absent-file state when files are untouched. When a CLI updates its own metadata, undo restores only the managed MCP entry and hook rows while preserving those updates; edits to those managed entries refuse rather than overwrite. Config files have an 8 MiB bound and generated TOML is validated before publication.
 
-Claude receives its seven bounded hooks. Codex, Kimi and Qwen receive SessionEnd incremental ingest; Pi receives a session_shutdown extension. [Codex's native `/hooks` review](https://learn.chatgpt.com/docs/hooks) remains a pending person step: setup never grants or bypasses hook trust. Native registration requires a CLI exposing `mcp` administration (Claude, Codex, Pi and Qwen are checked through their help before any registration command); current Kimi Code uses its documented config files. `setup all` skips and reports missing CLIs; an individual missing target refuses. Setup does not download tools or start a resident worker.
+Claude receives its seven bounded hooks; Jcode receives `post_tool` and `turn_end` capture hooks. Codex, Kimi and Qwen receive SessionEnd incremental ingest; Pi receives a session_shutdown extension. [Codex's native `/hooks` review](https://learn.chatgpt.com/docs/hooks) remains a pending person step: setup never grants or bypasses hook trust. Native registration requires a CLI exposing `mcp` administration (Claude, Codex, Pi and Qwen are checked through their help before any registration command); current Kimi Code uses its documented config files. `setup all` skips and reports missing CLIs; an individual missing target refuses. Setup does not download tools or start a resident worker.
+
+To keep several releases side by side, install each under its own root (for example `<install>/releases/<version>/`) and register one with `amem setup <target> --root <abs path> --apply`. The root is resolved to its real path, so a `current` link registers the release it names, and replacing another install never changes what the registered hooks and MCP server load. `amem manifest --json` prints the version, the MCP tools (read-only ones as `{ name, readOnly: true }`) and the commands of an install. See [versions on one machine](docs/contracts.md#versions-on-one-machine-199).
 
 For a Claude Code plugin installation instead of direct setup registration:
 
@@ -161,7 +165,7 @@ amem setup console --apply   # write $AGENTHUB_HOME/console/plugins/amem.json
 amem setup console --undo    # remove it (only when it points at this install)
 ```
 
-The manifest holds the absolute path and sha256 of `src/ui/plugin.ts`, in a 0700 directory and a 0600 file, as acon requires. acon refuses a module whose hash changed, so run `amem setup console --apply` again after upgrading amem. `setup all` does not include it.
+The manifest holds the absolute path and sha256 of `src/ui/plugin.ts` (of the `--root` install root when given), in a 0700 directory and a 0600 file, as acon requires. acon refuses a module whose hash changed, so run `amem setup console --apply` again after upgrading amem. `setup all` does not include it.
 
 - Reads are screened. Search, Timeline and Work lists call the in-process `amem_search`, `amem_timeline` and `amem_work_state_read` handlers for the chosen project and forward every option the tool declares, so console search returns exactly the `amem_search` set for the same query. Goals and the review queue pass the configured policy; a candidate that fails it, or whose target fails it, is not shown (the panel counts it and points to `amem review walk`). The console never shows unscreened content, also not to the person. It runs in no repository, so a repository's `.amem/config` narrowing does not apply; the machine's `amem.config.json` does.
 - Recap computes the current SessionStart brief only on its own panel snapshots, using machine policy. Curated and work inputs use bounded private scratch copies; capture is read-only, and no live reader lease is taken. It shows the full context, coverage, partial status, token upper bound and generation time; it is not a stored copy of a prior session's injected brief. The console has no repository binding, so the repository section is absent. No recap or new capture field is stored in the memory home.
@@ -328,6 +332,8 @@ Hook capture rows carry two optional fields: `session`, a 16-hex hash of Claude
 
 ## Doctor and the sync cadence
 
+Doctor checks applied setup receipts against the resolved configuration files. Its additive `setup` section names a target, file and entry when MCP or capture wiring is missing or changed, or when the receipt points at a different setup path. It reports missing Codex hook trust records as review-needed; a present record is not proof that its digest is valid. Configuration contents and stored trust hashes are never included in the report, and these checks write nothing into the memory home.
+
 `amem doctor`, `amem status` and `amem setup` print a readable report: an overall state, one labelled row per check (`OK`, `ATTENTION`, `SKIPPED`, `UNAVAILABLE`) and the next actions. Color appears only on an interactive terminal and is turned off by `NO_COLOR` or `TERM=dumb`. Add `--json` for the machine-readable object (for `status` and `setup` this was the default before #125). Setup also shows each available native client's version against its recorded layout verification version; the advisory probe uses a private staging home, reports unknown or unrecognised versions without blocking apply, and is skipped for Antigravity and undo.
 
 **Changed default (#134):** `amem ingest`, `amem migrate`, `amem prune`, `amem capacity apply` (including `--split`) and `amem vault-candidates` now print readable states, labelled facts and next actions. Ingest uses that format only when stdout is a terminal; ingest stays JSON when stdout is not a terminal, because native hooks read it. New Codex, Kimi and Qwen hook registrations explicitly request `--json`. Pass `--json` for automation and saved artifacts; it retains the previous objects and serialization without ANSI, including compact JSON for ingest. Capacity preview and confirmation receipts use the selected format. Exit codes, capture-only ingest and policy screening are unchanged; migrate and prune retain reader-admission and split-marker fences.
@@ -538,3 +544,13 @@ The first explicit v2 `amem sync` primes a private create-once publisher boundar
 Sync validates all selected history and complete raw Git proof, and checks each realm's aggregate input/archive capacity before atomic publication. It then fsyncs immutable inputs and commits the root map before ordinary/native imports, preventing an unmasked first import. Already-v2 map advances preserve generation/format and monotone ancestry, use a forward-only intent and rebind existing readers without requiring them to close. A reader waits at most 3000 ms for a v2 writer; an unresolved intent, incompatible marker pair or missing committed proof reports unavailable. The same `--resume` command completes an interrupted advance forward. Read and capture never activate, prime a boundary or repair a pending operation.
 
 `SyncResult.pruneApplication` reports transport durability, complete-proof count, neutral projection activity, native application, held count and phase separately. Transport durability alone does not establish completed local application. Historical multi-realm translations and older unsupported lineage retain "held, not applied" warnings, so agent-mem#15 AC4 remains open. The [full contract](docs/generation-neutral-prune-witness.md) states the owned-source integrity and resource ceilings; this source behavior does not establish release or live-host verification.
+
+## Claude transcript summaries
+
+At Stop and SessionEnd, amem also reads up to 256 KiB of new bytes from Claude Code's `transcript_path`. It captures native session titles (`Title`), away recaps (`Recap`, without the config suffix), and compaction summaries (`Compact`). The existing policy, secret, PII, deny-path and private-span screens and excerpt caps apply. Other transcript lines are skipped before JSON parsing. No network, model call or resident process is added.
+
+Private cursors under `hook-transcripts/` store only a session hash, file identity, byte offset, timestamp carry, untimed-content hashes with fallback times, and the last title hash. Repeated titles are skipped; deterministic spool receipts prevent duplicate replay after rotation/truncation. New summary events use `hook-v3-` spool names (format 3), which older readers ignore. Byte, time or spool limits leave remaining lines for a later Stop/SessionEnd invocation. A single line larger than the 256 KiB ceiling is skipped and counted as `transcript_line_bound` rather than buffered. An unreadable or busy transcript leaves ordinary hook capture available.
+
+The follow-up bound is a benchmark parameter, not a production retry loop. Backlogs advance on later Stop/SessionEnd calls of the same session. Anything unread after its last hook remains uncaptured, so a cold install on a long session keeps only what its remaining hooks can scan; committed rows are not lost.
+
+Search gives these events the existing 1.25 conversation weight and session grouping. The brief selects up to two newest screened main-session Recap/Compact rows first, then fills from the existing chronological rows, under the same record, byte and token caps. With no summaries the output is unchanged. See [verification evidence](docs/bench/transcript-summaries-201.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,8 @@
     "@staix/agent-mem-v012": "npm:@staix/agent-mem@0.12.0",
     "@staix/agent-mem-v013": "npm:@staix/agent-mem@0.13.0",
     "@staix/agent-mem-v015": "npm:@staix/agent-mem@0.15.0",
-    "@staix/agent-mem-v017": "npm:@staix/agent-mem@0.17.0"
+    "@staix/agent-mem-v017": "npm:@staix/agent-mem@0.17.0",
+    "@staix/agent-mem-v018": "npm:@staix/agent-mem@0.18.0"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/cli.ts

@@ -10,7 +10,7 @@ import { createRecallStalenessProbe } from "./memory/recall-staleness.ts";
 import { recordMemoryUse } from "./memory/use-telemetry.ts";
 import { DecayApplyError } from "./memory/decay-review.ts";
 import { createMemoryMcp } from "./mcp-memory.ts";
-import { serveMcp, writeConfirmed } from "./mcp.ts";
+import { MCP_TOOLS, serveMcp, writeConfirmed } from "./mcp.ts";
 import { createStandalonePolicy } from "./memory/policy.ts";
 import { configuredPolicy, configuredPolicyOptions, loadAmemConfig, repoConfigRoot } from "./memory/config.ts";
 import { vaultCandidates, vaultCandidatesText, vaultCandidatesAllText } from "./memory/vault.ts";
@@ -28,7 +28,7 @@ import { aliasedKeys, appendAlias, appendUnalias, listAliases, readShardedSelect
 import { capacityReport, capacityText, capacityApplyText, capacitySplitText } from "./memory/capacity.ts";
 import { readCaptureConfigFile, writeCaptureConfigFile, type CaptureConfig } from "./memory/capture.ts";
 
-import { commandHelp, parseCommand } from "./commands-table.ts";
+import { COMMANDS, commandHelp, parseCommand } from "./commands-table.ts";
 import { completionScript } from "./completion.ts";
 import { memoryHome, resolveMemoryHome } from "./memory/home.ts";
 import { realPath } from "./memory/platform.ts";
@@ -180,6 +180,16 @@ class CliPartialApplyError extends Error {
   }
 }
 
+/**
+ * `amem manifest`: what this install serves, read by installers (dotfiles#320) without a compiled list. A tool is a plain name, or
+ * `{ name, readOnly: true }` when its MCP annotation says it changes nothing. No memory data, so it needs no home.
+ */
+export function manifest() {
+  return { name: "@staix/agent-mem", version: VERSION,
+    mcp: { server: "amem", tools: MCP_TOOLS.map(tool => tool.annotations.readOnlyHint ? { name: tool.name, readOnly: true as const } : tool.name) },
+    commands: Object.keys(COMMANDS) };
+}
+
 export async function runCli(argv: readonly string[], context: CliContext = {}): Promise<string> {
   // Native capture and the MCP server retain their existing surfaces and attribution.
   if (argv[0] === "hook" || argv[0] === "ingest" || argv.length === 1 && argv[0] === "mcp") return runCliCommand(argv, context);
@@ -228,8 +238,17 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     throw error;
   });
 }
+/**
+ * Every lazily imported module outside the CLI-only commands (relative to this file), loaded at `amem mcp` start (#199). A later `import()`
+ * then hits the module cache, so an install replaced in place under a running server never mixes two versions in one process.
+ * `test/coexistence.test.ts` fails when a new lazy import is neither listed here nor named there as CLI-only.
+ */
+export const MCP_PRELOAD = ["./memory/store.ts", "./memory/capture.ts", "./memory/sync.ts", "./memory/shard-sync.ts", "./memory/public-prune-advance.ts"] as const;
+// The boundary check admits only literal specifiers, so the list above is spelled out again here; the test compares the two.
+const preloadMcp = () => Promise.all([import("./memory/store.ts"), import("./memory/capture.ts"), import("./memory/sync.ts"), import("./memory/shard-sync.ts"), import("./memory/public-prune-advance.ts")]);
 async function runCliCommand(argv: readonly string[], context: CliContext): Promise<string> {
   if (argv.length === 1 && argv[0] === "mcp") {
+    await preloadMcp();
     const memory = createMemoryMcp({ cwd: context.cwd ?? process.cwd(), base: memoryHome(context.env ?? process.env) });
     await serveMcp({ tools: memory.tools, close: memory.close, onEmitted: memory.onEmitted, version: VERSION });
     return "";
@@ -260,6 +279,7 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   try {
     parsed = parseCommand(argv);
     if (parsed.path[0] === "version") return `amem ${VERSION}`;
+    if (parsed.path[0] === "manifest") return JSON.stringify(manifest(), null, parsed.options["--json"] === true ? undefined : 2);
     if (parsed.path[0] === "completion") {
       if (parsed.positionals.length !== 1) throw new Error("usage: amem completion zsh|bash|fish");
       return completionScript(parsed.positionals[0]!);
@@ -271,15 +291,18 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   const { definition, options, rawArgs: args } = parsed;
   const identity = cliAttribution() ?? { actor: "person" as const, peer: "person" }, actor = identity.actor;
   if (parsed.path[0] === "setup") {
-    if (parsed.positionals.length !== 1 || options["--apply"] === true && options["--undo"] === true) throw new Error("usage: amem setup claude|codex|kimi|pi|qwen|jcode|opencode|gemini|agy|all|console [--apply|--undo]");
+    if (parsed.positionals.length !== 1 || options["--apply"] === true && options["--undo"] === true) throw new Error("usage: amem setup claude|codex|kimi|pi|qwen|jcode|opencode|gemini|agy|all|console [--root <abs path>] [--apply|--undo]");
     if (parsed.positionals[0] === "console") {
       const { consoleSetup, consoleSetupText } = await import("./setup-console.ts");
-      const mode = options["--apply"] === true ? "apply" : options["--undo"] === true ? "undo" : "preview", result = consoleSetup(mode, context.env ?? process.env);
+      const mode = options["--apply"] === true ? "apply" : options["--undo"] === true ? "undo" : "preview";
+      const root = typeof options["--root"] === "string" ? (await import("./setup.ts")).installRoot(options["--root"]).path : undefined;
+      const result = root === undefined ? consoleSetup(mode, context.env ?? process.env) : consoleSetup(mode, context.env ?? process.env, join(root, "src", "ui", "plugin.ts"));
       return options["--json"] === true ? JSON.stringify(result, null, 2) : consoleSetupText(result, mode);
     }
     const { runSetup } = await import("./setup.ts");
     return runSetup(parsed.positionals[0]!, options["--apply"] === true ? "apply" : options["--undo"] === true ? "undo" : "preview", {
       env: context.env ?? process.env, stdinTTY: context.stdinTTY ?? process.stdin.isTTY, cwd: context.cwd ?? process.cwd(),
+      ...(typeof options["--root"] === "string" ? { root: options["--root"] } : {}),
       ...(context.setupConfirm ? { confirm: context.setupConfirm } : {}), json: options["--json"] === true, style: outputStyle(context),
     });
   }

package/src/commands-table.ts

@@ -25,8 +25,10 @@ export const GLOBAL_OPTIONS = { "--help": flag("Show help") };
 export const ROOT_OPTIONS = { "--version": flag("Show version"), ...json };
 export const COMMANDS: Record<string, CommandDefinition> = {
   consolidate: { description: "Queue deterministic project-local consolidation candidates; curated notes change only after explicit acceptance", mutates: true, options: { ...json, "--project": text("The current project's key; another project is refused (run from its directory)") } },
-  setup: { description: "Preview reversible MCP setup and supported capture hooks for native coding CLIs, or the acon console plugin manifest (console); apply and undo use explicit flags", options: { ...json, "--apply": flag("Apply the previewed setup"), "--undo": flag("Restore the original configuration") }, args: [{ name: "target", values: ["claude", "codex", "kimi", "pi", "qwen", "jcode", "opencode", "gemini", "agy", "all", "console"] }] },
+  setup: { description: "Preview reversible MCP setup and supported capture hooks for native coding CLIs, or the acon console plugin manifest (console); apply and undo use explicit flags", options: { ...json, "--apply": flag("Apply the previewed setup"), "--undo": flag("Restore the original configuration"),
+    "--root": { description: "Register this absolute install root (such as <install>/releases/<version>/, resolved to its real path) instead of the running one", value: "path" } }, args: [{ name: "target", values: ["claude", "codex", "kimi", "pi", "qwen", "jcode", "opencode", "gemini", "agy", "all", "console"] }] },
   mcp: { description: "Run the project-bound MCP stdio server for this session" },
+  manifest: { description: "Describe this install: package name, version, MCP server and tools (read-only ones marked), commands", options: json },
   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", "qwen"] }] },
   "vault-candidates": { description: "List screened durable curated vault candidates (per project, or across projects)", options: { ...json, "--limit": text("Maximum candidates per project (1..100)"),

package/src/hook-contract.ts

@@ -1,3 +1,12 @@
 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;
+export interface HookTranscriptProgress { offset?: number; stopReason?: "cap" | "deadline" | "spool_full" }
+export function isHookTranscriptProgress(value: unknown): value is HookTranscriptProgress {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const row = value as Record<string, unknown>;
+  return Object.keys(row).every(key => key === "offset" || key === "stopReason")
+    && (row.offset !== undefined || row.stopReason !== undefined)
+    && (row.offset === undefined || Number.isSafeInteger(row.offset) && (row.offset as number) >= 0)
+    && (row.stopReason === undefined || ["cap", "deadline", "spool_full"].includes(row.stopReason as string));
+}

package/src/hook-jcode.ts

@@ -0,0 +1,56 @@
+import { dirname, isAbsolute, join } from "node:path";
+import { lstatSync } from "node:fs";
+
+// Jcode v0.99.1 lifecycle observers (crates/jcode-base/src/hooks.rs apply_event_env; docs/HOOKS.md). Observers get no
+// stdin and their stdout is discarded; every field arrives in the environment. Only post_tool and turn_end are captured:
+// post_tool carries TOOL_NAME, TOOL_INPUT (16 KiB, may be cut mid-JSON), TOUCHED_PATHS, STATUS and ERROR (1000 chars);
+// turn_end carries STATUS and LAST_ASSISTANT_TEXT (4000 chars). JCODE_HOOK_CWD is the session working directory at event
+// time, the per-event origin that saved sessions lack (docs/jcode.md).
+type Env = Readonly<Record<string, string | undefined>>;
+export const JCODE_HOOK_EVENTS = ["post_tool", "turn_end"] as const;
+const FIELD_BYTES = 16 * 1024 + 64, TOUCHED_PATHS = 32;
+
+export interface JcodeHookCapture { event: "PostToolUse" | "PostToolUseFailure" | "Stop"; cwd: string; input: Record<string, unknown> }
+
+const bounded = (value: string | undefined): value is string => typeof value === "string" && Buffer.byteLength(value) <= FIELD_BYTES;
+/** A jcode session may sit in $HOME or /tmp. Without an enclosing `.git` (directory or worktree file) there is no project to
+ * scope by, so the event is skipped rather than keyed by a directory name. No Git process: the hook resolver decides the key. */
+function insideRepository(cwd: string): boolean {
+  for (let dir = cwd, depth = 0; depth < 64; depth++) {
+    if (lstatSync(join(dir, ".git"), { throwIfNoEntry: false })) return true;
+    const parent = dirname(dir); if (parent === dir) return false; dir = parent;
+  }
+  return false;
+}
+
+/** Maps one jcode observer environment onto the Claude-shaped hook input the spool already screens and normalizes.
+ * Anything missing, oversized or inconsistent returns undefined: the event is skipped, never guessed. */
+export function jcodeHookCapture(env: Env): JcodeHookCapture | undefined {
+  const event = env.JCODE_HOOK_EVENT, cwd = env.JCODE_HOOK_CWD, session = env.JCODE_HOOK_SESSION_ID, status = env.JCODE_HOOK_STATUS;
+  if (event !== "post_tool" && event !== "turn_end") return undefined;
+  if (!bounded(cwd) || !cwd || !isAbsolute(cwd) || /[\x00-\x1f]/.test(cwd)) return undefined;
+  try { if (!lstatSync(cwd).isDirectory()) return undefined; } catch { return undefined; }
+  if (!insideRepository(cwd)) return undefined;
+  if (session !== undefined && (!bounded(session) || session.length > 256)) return undefined;
+  if (status !== "ok" && status !== "error") return undefined;
+  const base: Record<string, unknown> = { cwd, ...(session ? { session_id: session } : {}) };
+  if (event === "turn_end") {
+    const text = env.JCODE_HOOK_LAST_ASSISTANT_TEXT;
+    if (text !== undefined && !bounded(text)) return undefined;
+    // A turn without assistant text (tool-only, or an error before any text) has nothing to recall.
+    if (!text?.trim()) return undefined;
+    return { event: "Stop", cwd, input: { ...base, hook_event_name: "Stop", last_assistant_message: text } };
+  }
+  const tool = env.JCODE_HOOK_TOOL_NAME, raw = env.JCODE_HOOK_TOOL_INPUT, touched = env.JCODE_HOOK_TOUCHED_PATHS, error = env.JCODE_HOOK_ERROR;
+  if (!bounded(tool) || !tool || tool.length > 128 || /[\x00-\x1f]/.test(tool)) return undefined;
+  if ([raw, touched, error].some(value => value !== undefined && !bounded(value))) return undefined;
+  // TOOL_INPUT is cut at 16 KiB, so a long input is not valid JSON; keep the call with its touched paths only.
+  let parsed: Record<string, unknown> = {};
+  if (raw) try { const value: unknown = JSON.parse(raw); if (value && typeof value === "object" && !Array.isArray(value)) parsed = value as Record<string, unknown>; } catch { /* truncated */ }
+  // The spool reads file_path, path and paths; touched paths already name those inputs, so keep only the ones not present.
+  const named = new Set([parsed.file_path, parsed.path, ...(Array.isArray(parsed.paths) ? parsed.paths : [])].filter((p): p is string => typeof p === "string"));
+  const paths = [...new Set((touched ?? "").split("\n").filter(path => path && isAbsolute(path) && !named.has(path)))].slice(0, TOUCHED_PATHS);
+  const toolInput = { ...parsed, ...(paths.length ? { paths: [...(Array.isArray(parsed.paths) ? parsed.paths : []), ...paths] } : {}) };
+  const failed = status === "error", name = failed ? "PostToolUseFailure" : "PostToolUse";
+  return { event: name, cwd, input: { ...base, hook_event_name: name, tool_name: tool, tool_input: toolInput, ...(failed ? { error: error ?? "" } : { tool_response: "" }) } };
+}

package/src/hook-native.ts

@@ -1,7 +1,10 @@
 import { createHash, randomBytes } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { combineRssSources, processImageMemory, rssSource, selectHookRss, type HookRssReading, type HookRssSources } from "./hook-resources.ts";
 
-export interface HookNativeUsage { rssKB: number; rawRssKB: number }
+export interface HookNativeUsage {
+  rssKB: number; rawRssKB: number; rssSources?: HookRssSources;
+  observe?: () => { started(pid: number): void; finished(reading: HookRssReading): void };
+}
 // 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.
@@ -10,12 +13,13 @@ const SUPERVISOR = [
   // 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; }',
+  "rss() { [ -r \"/proc/$leader/status\" ] || return 0; trap '' PIPE; hwm=0; virtual=0; while read -r key value unit rest; do case \"$key\" in VmPeak:) virtual=$value ;; VmHWM:) hwm=$value; break ;; esac; done < \"/proc/$leader/status\"; printf \"%s:RSS:%s:%s\\n\" \"$marker\" \"$hwm\" \"$virtual\" >&2; trap - PIPE; }",
+  'reap() { if owned; then rss; 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"',
+  '"$@" </dev/null 2>/dev/null; code=$?; rss; printf "\\n%s:%s\\n" "$marker" "$code"',
   'read -r ignored || :',
   'wait "$watchdog"',
 ].join("; ");
@@ -25,16 +29,66 @@ export async function hookNative(argv: readonly string[], env: NodeJS.ProcessEnv
   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`;
+  let observer: ReturnType<NonNullable<HookNativeUsage["observe"]>> | undefined, observationFailed = false;
+  try { observer = usage.observe?.(); } catch { observationFailed = true; }
   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" });
+    { env, detached: true, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+  // A real owned image cannot disappear from provenance if collection/cleanup throws.
+  usage.rssSources = combineRssSources(usage.rssSources);
+  usage.rssSources.unavailable++;
+  try { observer?.started(child.pid); } catch { observationFailed = true; }
   let exited = false, ownPeak = 0;
-  const exit = child.exited.then(code => { exited = true; return code; });
+  let reportedPeak = 0, reportedVirtual = 0, ownVirtual = 0, receiptValid = true;
+  const rssReader = child.stderr.getReader();
+  // A separate numeric channel survives a late parent read after the watchdog exits.
+  // Command stderr remains discarded, as before; only the fixed supervisor writes here.
+  const rssReceipt = (async () => {
+    let pending = "", bytes = 0;
+    try {
+      for (;;) {
+        const next = await rssReader.read(); if (next.done) break;
+        bytes += next.value.byteLength;
+        if (bytes > 4096) { receiptValid = false; break; }
+        pending += new TextDecoder("utf-8", { fatal: true }).decode(next.value);
+        for (;;) {
+          const newline = pending.indexOf("\n"); if (newline < 0) break;
+          const line = pending.slice(0, newline); pending = pending.slice(newline + 1);
+          const prefix = `${marker}:RSS:`, value = line.startsWith(prefix) ? line.slice(prefix.length) : "";
+          const fields = /^(\d+):(\d+)$/.exec(value);
+          const peak = fields ? Number(fields[1]) : -1, virtual = fields ? Number(fields[2]) : -1;
+          if (Number.isSafeInteger(peak) && peak >= 0 && Number.isSafeInteger(virtual) && virtual >= 0) {
+            reportedPeak = Math.max(reportedPeak, peak); reportedVirtual = Math.max(reportedVirtual, virtual);
+          } else receiptValid = false;
+        }
+      }
+      if (pending) receiptValid = false;
+    } catch { receiptValid = false; }
+    finally { await rssReader.cancel().catch(() => {}); rssReader.releaseLock(); }
+  })();
+  let usageRecorded = false;
+  const recordUsage = () => {
+    if (usageRecorded) return;
+    usageRecorded = true;
+    const raw = (child.resourceUsage()?.maxRSS ?? 0) / 1024;
+    const selected = selectHookRss(process.platform, Math.max(ownPeak, receiptValid ? reportedPeak : 0), raw, Math.max(ownVirtual, receiptValid ? reportedVirtual : 0));
+    usage.rawRssKB = Math.max(usage.rawRssKB, raw);
+    usage.rssKB = Math.max(usage.rssKB, selected.kb);
+    usage.rssSources!.unavailable--;
+    usage.rssSources = combineRssSources(usage.rssSources, rssSource(selected));
+    try { observer?.finished(selected); } catch { observationFailed = true; }
+    if (observationFailed) usage.rssSources.unavailable++;
+  };
+  const exit = child.exited.then(code => {
+    exited = true;
+    // Reaped platform rusage is final before pipe cleanup; publish it while the worker is alive.
+    // Linux still needs the authenticated terminal receipt consumed below.
+    if (process.platform !== "linux") recordUsage();
+    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. */ }
+    const image = processImageMemory(child.pid);
+    ownPeak = Math.max(ownPeak, image.hwmKB ?? 0); ownVirtual = Math.max(ownVirtual, image.virtualKB ?? 0);
     try { process.kill(-child.pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch { /* already exited */ } }
   };
   const reader = child.stdout.getReader();
@@ -75,11 +129,10 @@ export async function hookNative(argv: readonly string[], env: NodeJS.ProcessEnv
     // 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;
+    await rssReceipt;
+    recordUsage();
     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));
   }
 }
 

package/src/hook-project.ts

@@ -1,3 +1,4 @@
+import { combineRssSources } from "./hook-resources.ts";
 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";
@@ -12,6 +13,8 @@ import { hookNative, type HookNativeUsage } from "./hook-native.ts";
 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 }
+/** One-invocation parent/child transport, not an authentication token or a reusable cache. */
+export interface HookProjectReceipt { cwd: string; base: string; scope: string; validity?: string; binary: string; project: string }
 function read(file: string): Binding | undefined {
   let fd: number | undefined;
   try {
@@ -103,7 +106,21 @@ function prepareHookProject(options: ResolverOptions) {
     }
     checkDeadline();
   };
-  return { binary, verifyBinary, resolve(gitRead: ProjectGitRead, assertComplete?: () => void): string {
+  return { binary, verifyBinary,
+    receipt(project: string): HookProjectReceipt | undefined {
+      verify();
+      return scope === undefined ? undefined : { cwd, base, scope, validity, binary: binary.revision, project };
+    },
+    accept(value: unknown): string {
+      if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("project receipt unavailable");
+      const receipt = value as HookProjectReceipt;
+      if (Object.keys(receipt).some(key => !["cwd", "base", "scope", "validity", "binary", "project"].includes(key))
+        || receipt.cwd !== cwd || receipt.base !== base || receipt.scope !== scope || scope === undefined
+        || receipt.validity !== validity || receipt.binary !== binary.revision || typeof receipt.project !== "string"
+        || !receipt.project || Buffer.byteLength(receipt.project) > 64 * 1024) throw new Error("project receipt changed");
+      verify(); return receipt.project;
+    },
+    resolve(gitRead: ProjectGitRead, assertComplete?: () => void): string {
     checkDeadline();
     if (hit && cached) {
       assertComplete?.(); verify();
@@ -128,6 +145,11 @@ export function resolveHookProject(options: ResolverOptions): string {
   return prepared.resolve(options.gitRead ?? hookGit(options.timeRemaining, prepared.binary.file), options.assertComplete);
 }
 
+/** Revalidate a fresh result delivered by our parent, without launching a native child. */
+export function acceptHookProjectReceipt(value: unknown, options: ResolverOptions): string {
+  return prepareHookProject(options).accept(value);
+}
+
 /** 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 {
@@ -146,7 +168,7 @@ function cacheableLocal(cwd: string, project: string): boolean {
 
 /** 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> {
+export async function resolveHookProjectAsync(options: { cwd: string; base: string; scope?: string; timeRemaining: () => number; maintainCache?: boolean; prefetch?: boolean; onResolved?: (receipt: HookProjectReceipt | undefined) => void }, 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 });
@@ -159,7 +181,7 @@ export async function resolveHookProjectAsync(options: { cwd: string; base: stri
     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 };
+    const abort = new AbortController(), own: HookNativeUsage = { rssKB: 0, rawRssKB: 0, observe: usage.observe };
     active.add(key); overlaps.push([...active]);
     const result = hookNative(argv, memoryGitEnv(env, { repositoryIsolation: true }), options.timeRemaining, own, abort.signal)
       .finally(() => { active.delete(key); });
@@ -178,7 +200,7 @@ export async function resolveHookProjectAsync(options: { cwd: string; base: stri
           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; }
+      if (!needed) { if (failure) throw failure; if (result !== undefined) { options.onResolved?.(prepared.receipt(result)); 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
@@ -202,5 +224,6 @@ export async function resolveHookProjectAsync(options: { cwd: string; base: stri
       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));
     }
+    usage.rssSources = combineRssSources(...[...pending.values()].map(child => child.usage.rssSources));
   }
 }

package/src/hook-resources.ts

@@ -1,15 +1,57 @@
 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;
+export const HOOK_RSS_COVERAGE = "images: bun+supervisor; descendants: not measured" as const;
+
+export interface HookRssReading { kb: number; rawKB: number; source: "VmHWM" | "vmpeak-bound" | "platform-rusage" | "raw-fallback" | "unavailable"; known: boolean }
+export interface HookRssSources { vmhwm: number; vmpeakBound: number; platformRusage: number; rawFallback: number; unavailable: number }
+const positive = (value: number | undefined): value is number => value !== undefined && Number.isSafeInteger(value) && value > 0;
+
+/** A raw fallback stays conservative, but is explicitly insufficient to certify a Linux image peak. */
+export function selectHookRss(platform: string, imageKB: number | undefined, rawKB: number, virtualKB?: number): HookRssReading {
+  const raw = positive(rawKB) ? rawKB : 0;
+  if (platform === "linux" && positive(imageKB)) return { kb: imageKB, rawKB: raw, source: "VmHWM", known: true };
+  if (platform === "linux" && positive(virtualKB)) return { kb: virtualKB, rawKB: raw, source: "vmpeak-bound", known: true };
+  if (platform !== "linux" && raw) return { kb: Math.max(raw, positive(imageKB) ? imageKB : 0), rawKB: raw, source: "platform-rusage", known: true };
+  return { kb: raw, rawKB: raw, source: raw ? "raw-fallback" : "unavailable", known: false };
+}
+
+export function processImageMemory(pid: number | "self"): { hwmKB?: number; virtualKB?: number } {
+  if (process.platform !== "linux" || pid !== "self" && (!Number.isSafeInteger(pid) || pid <= 0)) return {};
+  try {
+    const text = readFileSync(`/proc/${pid}/status`, "utf8");
+    const field = (match: RegExpExecArray | null) => { const value = Number(match?.[1]); return positive(value) ? value : undefined; };
+    return { hwmKB: field(/^VmHWM:\s+(\d+)\s+kB$/m.exec(text)), virtualKB: field(/^VmPeak:\s+(\d+)\s+kB$/m.exec(text)) };
+  } catch { /* Missing or exited processes are unknown, never a fabricated zero peak. */ }
+  return {};
+}
+export const processImageRssKB = (pid: number | "self"): number | undefined => processImageMemory(pid).hwmKB;
+
+export function hookRssReading(): HookRssReading {
+  const image = processImageMemory("self");
+  return selectHookRss(process.platform, image.hwmKB, process.resourceUsage().maxRSS, image.virtualKB);
+}
+export const hookPeakRssKB = (): number => hookRssReading().kb;
+export const emptyRssSources = (): HookRssSources => ({ vmhwm: 0, vmpeakBound: 0, platformRusage: 0, rawFallback: 0, unavailable: 0 });
+export function rssSource(reading: HookRssReading): HookRssSources {
+  const value = emptyRssSources();
+  value[reading.source === "VmHWM" ? "vmhwm" : reading.source === "vmpeak-bound" ? "vmpeakBound" : reading.source === "platform-rusage" ? "platformRusage" : reading.source === "raw-fallback" ? "rawFallback" : "unavailable"] = 1;
+  return value;
+}
+export function combineRssSources(...values: (HookRssSources | undefined)[]): HookRssSources {
+  const result = emptyRssSources();
+  for (const value of values) if (value) for (const key of Object.keys(result) as (keyof HookRssSources)[]) result[key] += value[key];
+  return result;
+}
+export function countedRssSources(kb: number, value?: HookRssSources): HookRssSources {
+  const result = combineRssSources(value);
+  if (kb > 0 && Object.values(result).every(count => count === 0)) result.unavailable++;
+  return result;
+}
+export function validRssSources(value: unknown): value is HookRssSources {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const row = value as Record<string, unknown>, keys = Object.keys(emptyRssSources());
+  return Object.keys(row).length === keys.length && keys.every(key => Number.isSafeInteger(row[key]) && (row[key] as number) >= 0 && (row[key] as number) <= 1024);
+}
+export function rssSourcesKnown(value: HookRssSources): boolean {
+  return value.rawFallback === 0 && value.unavailable === 0 && value.vmhwm + value.vmpeakBound + value.platformRusage > 0;
 }