@staix/agent-mem 0.18.0 → 0.19.0

package/src/setup-jcode.ts

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

package/src/setup-owned.ts

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

package/src/setup-paths.ts

@@ -0,0 +1,76 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { canonicalPath, realPath } from "./memory/platform.ts";
+import { geminiSettingsPath } from "./setup-gemini.ts";
+import type { SetupTarget } from "./setup.ts";
+
+export type SetupEnvironment = Readonly<Record<string, string | undefined>>;
+export interface SetupRedirect {
+  target: "claude" | "codex";
+  from: string;
+  to: string;
+  reason: string;
+}
+export interface SetupPaths {
+  home: string;
+  paths: Record<SetupTarget, string[]>;
+  /** Pre-redirect targets, only for validating receipts made by an older setup version. */
+  legacyPaths: Record<SetupTarget, string[]>;
+  redirects: SetupRedirect[];
+}
+
+/** Same fallback as setup inventory; assertOpencodeLayout separately rejects relative XDG_CONFIG_HOME. */
+export function opencodeConfigRoot(env: SetupEnvironment, home: string): string {
+  const value = env.XDG_CONFIG_HOME;
+  return value === undefined || value === "" || !isAbsolute(value) ? join(home, ".config") : value;
+}
+
+/** Path recognition only: no app import, probe, directory creation or config read. */
+function orcaHome(root: string, kind: "claude" | "codex", env: SetupEnvironment, home: string): boolean {
+  const userData = canonicalPath(resolve(env.ORCA_USER_DATA_PATH?.trim() || join(home, "Library", "Application Support", "orca")));
+  const parts = relative(userData, canonicalPath(root)).split(sep);
+  return kind === "claude"
+    ? parts.length === 3 && parts[0] === "claude-profiles" && !!parts[1] && parts[2] === "home"
+    : parts.length === 3 && parts[0] === "codex-accounts" && !!parts[1] && parts[2] === "home"
+      || parts.length === 2 && parts[0] === "codex-runtime-home" && parts[1] === "home";
+}
+
+/** Shared setup/doctor resolution. Publication still applies setup's named-directory/link guards. */
+export function resolveSetupPaths(env: SetupEnvironment = process.env, givenHome?: string, workspaceRoot?: string): SetupPaths {
+  const home = givenHome ?? realPath(resolve(env.HOME?.trim() || homedir()));
+  const root = (key: string, fallback: string) => {
+    const setting = env[key];
+    const present = key === "JCODE_HOME" ? setting !== undefined : key === "QWEN_HOME" ? !!setting : !!setting?.trim();
+    if (!present) return join(home, fallback);
+    const expanded = key === "QWEN_HOME" && /^~(?:[/\\]|$)/.test(setting!) ? join(home, ...setting!.slice(2).split(/[/\\]/)) : setting!;
+    const given = resolve(expanded), withinHome = relative(resolve(env.HOME?.trim() || homedir()), given);
+    return withinHome !== ".." && !withinHome.startsWith("../") && !isAbsolute(withinHome) ? join(home, withinHome) : given;
+  };
+  const claude = root("CLAUDE_CONFIG_DIR", ".claude"), codex = root("CODEX_HOME", ".codex"), kimi = root("KIMI_CODE_HOME", ".kimi-code");
+  const pi = root("PI_CODING_AGENT_DIR", ".pi/agent"), qwen = root("QWEN_HOME", ".qwen");
+  const paths: SetupPaths["paths"] = {
+    claude: [env.CLAUDE_CONFIG_DIR?.trim() ? join(claude, ".claude.json") : join(home, ".claude.json"), join(claude, "settings.json")],
+    codex: [join(codex, "config.toml"), join(codex, "hooks.json")],
+    kimi: [join(kimi, "mcp.json"), join(kimi, "config.toml")],
+    pi: [join(pi, "mcp.json"), join(pi, "extensions", "amem-session.ts")],
+    qwen: [join(qwen, "settings.json")],
+    // #203: config.toml carries the jcode [hooks] capture entries.
+    jcode: [join(root("JCODE_HOME", ".jcode"), "mcp.json"), join(root("JCODE_HOME", ".jcode"), "config.toml")],
+    opencode: [join(opencodeConfigRoot(env, home), "opencode", "opencode.json")],
+    gemini: [geminiSettingsPath(env, home)],
+    agy: workspaceRoot ? [join(workspaceRoot, ".agents", "mcp_config.json")] : [],
+  };
+  const redirects: SetupRedirect[] = [];
+  const legacyPaths = Object.fromEntries(Object.entries(paths).map(([target, files]) => [target, [...files]])) as SetupPaths["paths"];
+  const redirect = (target: SetupRedirect["target"], index: number, to: string) => {
+    const from = paths[target][index]!;
+    paths[target][index] = to;
+    redirects.push({ target, from, to, reason: "Orca re-syncs this managed file from the personal source" });
+  };
+  if (orcaHome(claude, "claude", env, home)) redirect("claude", 1, join(home, ".claude", "settings.json"));
+  if (orcaHome(codex, "codex", env, home)) {
+    redirect("codex", 0, join(home, ".codex", "config.toml"));
+    redirect("codex", 1, join(home, ".codex", "hooks.json"));
+  }
+  return { home, paths, legacyPaths, redirects };
+}

package/src/setup.ts

@@ -3,7 +3,11 @@ import { configuredPolicy } from "./memory/config.ts";
 import { SETUP_CONFIG_BYTES, updateTomlArray } from "./setup-toml.ts";
 import { managedAfter, mcpRecord, putMcpRecord, restoreOwned, sameImage, type ConfigImage } from "./setup-owned.ts";
 import { opencodeServer } from "./setup-opencode.ts";
-import { assertGeminiHome, assertGeminiRuntime, GEMINI_REMOVE, geminiAddCommand, geminiSettingsPath } from "./setup-gemini.ts";
+import { assertGeminiHome, assertGeminiRuntime, GEMINI_REMOVE, geminiAddCommand } from "./setup-gemini.ts";
+import { resolveSetupPaths, opencodeConfigRoot } from "./setup-paths.ts";
+import { JCODE_CAPTURE_EVENTS, putJcodeHooks } from "./setup-jcode.ts";
+/** jcode parses hook command lines shell-style and runs them directly (no shell), so single quotes group each path. */
+const jcodeHookCommand = (bun: string, entry: string) => `${quote(bun)} --smol ${quote(entry)} hook jcode`;
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, renameSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
@@ -33,6 +37,8 @@ interface DirectoryIdentity { dev: number; ino: number }
 interface Receipt { createdDirectory?: DirectoryIdentity; version: 1; target: SetupTarget; intent: string; phase: "prepared" | "applied"; changes: Change[] }
 export interface SetupContext {
   env?: Env; bun?: string; entry?: string; stdinTTY?: boolean; cwd?: string;
+  /** `--root`: an absolute amem install root to register instead of the running one (#199). Ignored when `entry` is given. */
+  root?: string;
   /** @deprecated Retained for source compatibility; explicit apply/undo modes do not prompt. */
   confirm?: (plan: SetupPlan) => Promise<boolean>;
   /** Host-only race fixture, called after temporary-file fsync and before the final comparison/rename. */
@@ -41,7 +47,7 @@ export interface SetupContext {
   native?: (argv: readonly string[], env: Env, cwd: string) => void;
 }
 export interface SetupPlan {
-  targets: SetupTarget[]; mode: "preview" | "apply" | "undo";
+  targets: SetupTarget[]; mode: "preview" | "apply" | "undo"; root?: InstallRoot;
   actions: { target: SetupTarget; version?: ClientVersion; files: string[]; receipt: string; cwd?: string; registration: string[] | null; lifecycle: string; available: boolean; hooks: PlannedHook[]; mcpChange: "add" | "replace" | "restore" | "unchanged"; commands: string[][]; state: string }[];
   notes: string[];
 }
@@ -129,39 +135,48 @@ function workspaceBinding(options: SetupContext): WorkspaceBinding {
 }
 function context(options: SetupContext, workspace?: WorkspaceBinding) {
   const env = options.env ?? process.env, home = realPath(resolve(env.HOME?.trim() || homedir()));
-  const root = (key: string, fallback: string) => {
-    const setting = env[key];
-    const present = key === "JCODE_HOME" ? setting !== undefined : key === "QWEN_HOME" ? !!setting : !!setting?.trim();
-    if (!present) return join(home, fallback);
-    const expanded = key === "QWEN_HOME" && /^~(?:[/\\]|$)/.test(setting!) ? join(home, ...setting!.slice(2).split(/[/\\]/)) : setting!;
-    const given = resolve(expanded), withinHome = relative(resolve(env.HOME?.trim() || homedir()), given);
-    // Canonicalize the HOME alias only; named configuration-directory symlinks must still be refused.
-    return withinHome !== ".." && !withinHome.startsWith("../") && !isAbsolute(withinHome) ? join(home, withinHome) : given;
-  };
-  const claude = root("CLAUDE_CONFIG_DIR", ".claude"), codex = root("CODEX_HOME", ".codex"), kimi = root("KIMI_CODE_HOME", ".kimi-code"), pi = root("PI_CODING_AGENT_DIR", ".pi/agent"), qwen = root("QWEN_HOME", ".qwen");
-  const paths: Record<SetupTarget, string[]> = {
-    claude: [env.CLAUDE_CONFIG_DIR?.trim() ? join(claude, ".claude.json") : join(home, ".claude.json"), join(claude, "settings.json")],
-    codex: [join(codex, "config.toml"), join(codex, "hooks.json")],
-    kimi: [join(kimi, "mcp.json"), join(kimi, "config.toml")],
-    pi: [join(pi, "mcp.json"), join(pi, "extensions", "amem-session.ts")],
-    qwen: [join(qwen, "settings.json")],
-    // Absolute JCODE_HOME spellings stay literal; unset uses the platform-home default.
-    jcode: [join(root("JCODE_HOME", ".jcode"), "mcp.json")],
-    // xdg-basedir 5.1.0: XDG_CONFIG_HOME verbatim when set and non-empty, else ~/.config (OpenCode v1.18.35 packages/core/src/global.ts).
-    opencode: [join(opencodeConfigRoot(env, home), "opencode", "opencode.json")],
-    // Gemini CLI's own user settings, never Antigravity's <home>/.gemini/config/mcp_config.json.
-    gemini: [geminiSettingsPath(env, home)],
-    agy: workspace ? [join(workspace.root, ".agents", "mcp_config.json")] : [],
-  };
+  const { paths, legacyPaths, redirects } = resolveSetupPaths(env, home, workspace?.root);
   const requestedBun = options.bun ?? "bun", bun = requestedBun === "bun" ? Bun.which("bun", { PATH: env.PATH ?? process.env.PATH }) : requestedBun;
-  const entry = options.entry ?? fileURLToPath(new URL("../bin/amem.js", import.meta.url));
+  const install = options.entry === undefined && options.root !== undefined ? installRoot(options.root) : undefined;
+  const entry = options.entry ?? (install ? join(install.path, "bin", "amem.js") : fileURLToPath(new URL("../bin/amem.js", import.meta.url)));
   if (!bun || !isAbsolute(bun) || !isAbsolute(entry)) throw Error("setup needs a PATH-resolved absolute Bun runtime and an absolute installed entry");
   // The trusted native fixture may use a temporary package; ordinary CLI installation must outlive bunx's cache.
   if (!options.native) {
     const roots = [resolve(tmpdir()), realPath(tmpdir())], entries = [resolve(entry), realPath(entry)];
     if (roots.some(root => entries.some(file => { const part = relative(root, file); return part !== ".." && !part.startsWith("../") && !isAbsolute(part); }))) throw Error("setup refuses a temporary package entry; install amem in a persistent location first");
   }
-  return { env, home, paths, bun, entry, workspace, state: join(canonicalPath(memoryHome({ ...env, AGENTHUB_HOME: env.AGENTHUB_HOME?.trim() || join(home, ".agenthub") })), "setup") };
+  return { env, home, paths, legacyPaths, redirects, bun, entry, root: install, workspace, state: join(canonicalPath(memoryHome({ ...env, AGENTHUB_HOME: env.AGENTHUB_HOME?.trim() || join(home, ".agenthub") })), "setup") };
+}
+export interface InstallRoot { path: string; version: string }
+const PACKAGE_JSON_MAX = 64 * 1024;
+/**
+ * An amem install root to register, such as `<install>/releases/<version>/` (#199). It 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. The root must
+ * hold a regular `package.json` named `@staix/agent-mem` (read on one non-following, non-blocking descriptor, at most 64 KiB) and a regular
+ * `bin/amem.js`.
+ */
+export function installRoot(root: string): InstallRoot {
+  if (!isAbsolute(root)) throw Error("setup --root must be an absolute path");
+  const refused = (why: string) => Error(`setup --root ${root}: ${why}`);
+  let path: string;
+  try { path = realPath(root); } catch { throw refused("not found"); }
+  let fd: number;
+  try { fd = openSync(join(path, "package.json"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); } catch { throw refused("no readable package.json"); }
+  let text: string;
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > PACKAGE_JSON_MAX) throw refused("package.json is not a regular file of at most 64 KiB");
+    const data = Buffer.alloc(PACKAGE_JSON_MAX + 1); let size = 0, n: number;
+    while (size < data.length && (n = readSync(fd, data, size, data.length - size, null)) > 0) size += n;
+    if (size > PACKAGE_JSON_MAX) throw refused("package.json is not a regular file of at most 64 KiB");
+    text = data.subarray(0, size).toString("utf8");
+  } finally { closeSync(fd); }
+  let pkg: unknown;
+  try { pkg = JSON.parse(text); } catch { throw refused("package.json is not JSON"); }
+  const { name, version } = (pkg && typeof pkg === "object" ? pkg : {}) as { name?: unknown; version?: unknown };
+  if (name !== "@staix/agent-mem" || typeof version !== "string") throw refused("not an @staix/agent-mem install root");
+  if (!lstatSync(join(path, "bin", "amem.js"), { throwIfNoEntry: false })?.isFile()) throw refused("no regular bin/amem.js");
+  return { path, version };
 }
 function command(target: SetupTarget, bun: string, entry: string): string[] | null {
   if (target === "kimi" || target === "jcode" || target === "opencode" || target === "agy") return null;
@@ -174,11 +189,6 @@ function command(target: SetupTarget, bun: string, entry: string): string[] | nu
  * (no trim) and falls back to ~/.config only when it is unset or empty. A relative value would resolve against
  * OpenCode's own cwd, so setup refuses it rather than guess. An absolute value keeps its literal spelling.
  */
-function opencodeConfigRoot(env: Env, home: string): string {
-  const value = env.XDG_CONFIG_HOME;
-  // A relative value is refused in assertOpencodeLayout; the path here only has to be well-formed for inventory.
-  return value === undefined || value === "" || !isAbsolute(value) ? join(home, ".config") : value;
-}
 function assertJcodeHome(env: Env): void {
   if (env.JCODE_HOME !== undefined && !isAbsolute(env.JCODE_HOME)) throw Error("setup requires an absolute JCODE_HOME; unset it to use the default");
 }
@@ -195,14 +205,15 @@ function assertOpencodeLayout(c: ReturnType<typeof context>, mode: SetupPlan["mo
   for (const name of ["opencode.jsonc", "config.json"]) if (read(join(dir, name)).bytes !== null) throw Error(`OpenCode setup supports one strict-JSON global opencode.json; ${name} beside it is merged too and is not supported`);
   if ([c.bun, c.entry].some(value => /\{(?:env|file):/.test(value))) throw Error("OpenCode substitutes {env:} and {file:} in configuration; setup cannot register this runtime exactly");
 }
-function intent(c: ReturnType<typeof context>, target: SetupTarget): string { return digest([1, target, c.paths[target], c.bun, c.entry, ...(["codex", "kimi", "qwen"].includes(target) ? ["capture-json-v1"] : []), ...(target === "agy" ? [c.workspace!.root] : [])]); }
+function intent(c: ReturnType<typeof context>, target: SetupTarget): string { return digest([1, target, c.paths[target], c.bun, c.entry, ...(["codex", "kimi", "qwen"].includes(target) ? ["capture-json-v1"] : []), ...(target === "jcode" ? ["jcode-hooks-v1"] : []), ...(target === "agy" ? [c.workspace!.root] : [])]); }
 function journal(c: ReturnType<typeof context>, target: SetupTarget): string { return join(c.state, target === "agy" ? `agy-${digest(c.workspace!.root)}.json` : `${target}.json`); }
 function receipt(c: ReturnType<typeof context>, target: SetupTarget, requireRuntime = false): Receipt | undefined {
   const raw = read(journal(c, target), JOURNAL_MAX); if (raw.bytes === null) return;
   const value = record(JSON.parse(Buffer.from(raw.bytes, "base64").toString("utf8")));
-  if (value.version !== 1 || value.target !== target || typeof value.intent !== "string" || !/^[a-f0-9]{64}$/.test(value.intent) || requireRuntime && value.intent !== intent(c, target) || !["prepared", "applied"].includes(String(value.phase)) || !Array.isArray(value.changes) || value.changes.length !== c.paths[target].length) throw Error("setup receipt does not match this installation");
+  if (value.version !== 1 || value.target !== target || typeof value.intent !== "string" || !/^[a-f0-9]{64}$/.test(value.intent) || requireRuntime && value.intent !== intent(c, target) || !["prepared", "applied"].includes(String(value.phase)) || !Array.isArray(value.changes) || value.changes.length !== c.paths[target].length && !(target === "jcode" && value.changes.length === 1)) throw Error("setup receipt does not match this installation");
   for (let i = 0; i < value.changes.length; i++) {
-    const change = record(value.changes[i]); if (change.path !== c.paths[target][i] || change.key !== `${target}:${i}`) throw Error("setup receipt target mismatch");
+    const change = record(value.changes[i]); const currentPath = c.paths[target][i], legacyRedirect = c.redirects.some(row => row.target === target && row.from === change.path && row.to === currentPath);
+    if (change.path !== currentPath && !legacyRedirect || change.key !== `${target}:${i}`) throw Error("setup receipt target mismatch");
     for (const key of ["before", "after", ...(change.start !== undefined ? ["start"] : [])]) {
       const v = record(change[key]);
       if (!Number.isInteger(v.mode) || Number(v.mode) < 0 || Number(v.mode) > 0o777 || v.bytes !== null && (typeof v.bytes !== "string" || v.bytes.length > 2 * MAX || Buffer.from(v.bytes, "base64").toString("base64") !== v.bytes)) throw Error("setup receipt invalid");
@@ -215,12 +226,13 @@ function receipt(c: ReturnType<typeof context>, target: SetupTarget, requireRunt
   return value as unknown as Receipt;
 }
 function plannedHooks(c: ReturnType<typeof context>, target: SetupTarget): PlannedHook[] {
-  if (target === "jcode" || target === "opencode" || target === "gemini" || target === "agy") return [];
+  if (target === "jcode") return JCODE_CAPTURE_EVENTS.map(event => ({ event, command: jcodeHookCommand(c.bun, c.entry), timeout: 1 }));
+  if (target === "opencode" || target === "gemini" || target === "agy") return [];
   const launch = `${quote(c.bun)} --smol ${quote(c.entry)}`;
   return target === "claude" ? HOOK_EVENTS.map(event => ({ event, command: `${launch} hook ${event}`, timeout: 1 }))
     : [{ event: target === "pi" ? "session_shutdown" : "SessionEnd", command: `${launch} ingest ${target}${target === "pi" ? "" : " --json"}`, timeout: target === "pi" ? 2.5 : 3 }];
 }
-const lifecycle = (target: SetupTarget) => target === "jcode" || target === "opencode" || target === "gemini" || target === "agy" ? "MCP only; native capture unavailable" : target === "claude" ? "seven bounded native hooks" : target === "pi" ? "session_shutdown incremental ingest" : "SessionEnd incremental ingest";
+const lifecycle = (target: SetupTarget) => target === "opencode" || target === "gemini" || target === "agy" ? "MCP only; native capture unavailable" : target === "jcode" ? "post_tool and turn_end capture hooks" : target === "claude" ? "seven bounded native hooks" : target === "pi" ? "session_shutdown incremental ingest" : "SessionEnd incremental ingest";
 export function planSetup(target: string, mode: SetupPlan["mode"] = "preview", options: SetupContext = {}): SetupPlan {
   if (target !== "all" && !SETUP_TARGETS.includes(target as SetupTarget)) throw Error("usage: amem setup claude|codex|kimi|pi|qwen|jcode|opencode|gemini|agy|all [--apply|--undo]");
   const targets: SetupTarget[] = target === "all" ? [...SETUP_ALL_TARGETS] : [target as SetupTarget];
@@ -231,34 +243,55 @@ export function planSetup(target: string, mode: SetupPlan["mode"] = "preview", o
   if (targets.includes("gemini") && (target === "gemini" || available(c, "gemini", options))) assertGeminiHome(c.env);
   if (mode !== "undo" && targets.includes("gemini")) assertGeminiRuntime(c.bun, c.entry);
   const pluginNotes: string[] = [];
+  for (const row of c.redirects.filter(row => targets.includes(row.target))) {
+    pluginNotes.push(`${row.target}: ${row.from} -> ${row.to}. ${row.reason}; start a new Orca session to receive the change.`);
+  }
   if (targets.includes("claude")) {
-    const settings = json(read(c.paths.claude[1]!));
+    const settingsPath = mode === "undo" ? receipt(c, "claude", false)?.changes[1]?.path ?? c.paths.claude[1]! : c.paths.claude[1]!;
+    const settings = json(read(settingsPath));
     // The settings-derived ids are computed outside the registry guard, so a broken installed_plugins.json cannot hide them.
     const ids = new Set<string>();
     try { for (const key of Object.keys(record(settings.enabledPlugins ?? {}))) ids.add(key); } catch { /* Optional plugin metadata must never prevent setup or recovery. */ }
-    try { for (const key of Object.keys(record(json(read(join(dirname(c.paths.claude[1]!), "plugins", "installed_plugins.json"))).plugins ?? {}))) ids.add(key); } catch { /* Optional plugin metadata must never prevent setup or recovery; authoritative settings/receipts keep their guards. */ }
+    try { for (const key of Object.keys(record(json(read(join(dirname(settingsPath), "plugins", "installed_plugins.json"))).plugins ?? {}))) ids.add(key); } catch { /* Optional plugin metadata must never prevent setup or recovery; authoritative settings/receipts keep their guards. */ }
     for (const id of [...ids].filter(key => /^agent-mem(?:@[A-Za-z0-9._-]+)?$/.test(key))) pluginNotes.push(`Installed Claude plugin ${id} detected: if enabled, direct setup would duplicate its MCP server and seven hooks. Choose plugin installation or direct setup; disable/uninstall the plugin before applying direct setup.`);
   }
   if (targets.includes("qwen")) pluginNotes.push("Qwen capture supports the verified 0.26.1 native format. For custom advanced.runtimeOutputDir, export the matching QWEN_RUNTIME_DIR for manual and SessionEnd ingest.");
-  if (targets.includes("jcode")) pluginNotes.push("Jcode setup registers MCP only. Native saved sessions do not prove per-message project scope, so capture and ingest hooks are unavailable; no hook or config.toml is installed.");
+  if (targets.includes("jcode")) pluginNotes.push("Jcode setup registers MCP and adds `amem hook jcode` to the post_tool and turn_end lifecycle hooks in JCODE_HOME/config.toml, keeping any existing command for those events (array form). Each event is scoped by its own JCODE_HOOK_CWD; events with no cwd, or outside a project, are skipped. Saved sessions and journals are still not ingested (no per-message origin), and user prompts are not captured.");
   if (targets.includes("gemini")) pluginNotes.push("Gemini CLI setup registers MCP only, at user scope in ~/.gemini/settings.json (GEMINI_CLI_HOME moves it), through the native gemini mcp add in a private staging HOME. Antigravity's ~/.gemini/config/mcp_config.json is never touched. A workspace .gemini/settings.json defining mcpServers.amem overrides this entry. No hook or ingest is installed: see docs/gemini-cli.md for why transcripts are not ingested.");
   if (targets.includes("opencode")) pluginNotes.push("OpenCode setup registers MCP only in the global strict-JSON opencode.json (mcp.amem, a local server started in the session's project directory). No plugin or ingest hook is installed: see docs/opencode.md for why transcripts are not ingested. A project opencode.json defining mcp.amem overrides this entry.");
   if (c.workspace) {
     pluginNotes.push(`Antigravity MCP is pinned to this repository only: ${c.workspace.root}. Restart the CLI/IDE and use one workspace; no global or plugin definitions are replaced, and same-name definitions elsewhere are unsupported. Native capture is unavailable; no hooks are installed. Only strict JSON is supported; JSONC is refused. Native TUI/IDE presence and live behavior are unverified; availability means this direct configuration operation is supported.`);
     if (!c.workspace.ignored) pluginNotes.push("WARNING: .agents/mcp_config.json is not Git-ignored; it contains absolute local paths. Setup will refuse it if it becomes tracked.");
   }
+  if (c.root) pluginNotes.push(`Registers the install root ${c.root.path} (amem ${c.root.version}) for hooks and MCP; current registrations change only on --apply.`);
   if (target === "all") pluginNotes.push("Antigravity is repository-scoped and excluded from all; run amem setup agy explicitly inside its repository.");
   if (targets.includes("jcode")) pluginNotes.push("Launch Jcode with JCODE_DISABLE_CLAUDE_MCP=1 and without a same-name project override: imported Claude stdio entries can replace this private amem binding with a shared daemon-cwd server. Use a new workspace-bound session when changing projects.");
-  return { targets, mode, actions: targets.map(target => {
-    const prior = receipt(c, target, false); for (const file of c.paths[target]) read(file);
-    const original = read(c.paths[target][0]!);
+  return { targets, mode, ...(c.root ? { root: c.root } : {}), actions: targets.map(target => {
+    const prior = receipt(c, target, false), files = mode === "undo" && prior ? prior.changes.map(change => change.path) : c.paths[target];
+    for (const file of files) read(file);
+    if (mode === "undo" && prior?.changes.some((change, index) => change.path !== c.paths[target][index])) {
+      pluginNotes.push(`${target}: undo restores the historical receipt files, not the new personal source: ${prior.changes.map(change => change.path).join(", ")}`);
+    }
+    const original = read(files[0]!);
     const document: Record<string, unknown> = target === "agy" ? {} : target === "codex" ? toml(original.bytes === null ? "" : Buffer.from(original.bytes, "base64").toString("utf8")) : json(original);
     const hasAmem = target === "jcode" || target === "opencode" || target === "agy" ? mcpRecord(target, original) !== undefined : Object.hasOwn(record(document[target === "codex" ? "mcp_servers" : "mcpServers"] ?? {}), "amem");
+    if (!prior && mode !== "undo" && (target === "claude" || target === "codex")) {
+      try {
+        const server = mcpRecord(target, original);
+        const sameBinding = server && typeof server === "object" && !Array.isArray(server)
+          && (server as Record<string, unknown>).command === c.bun
+          && isDeepStrictEqual((server as Record<string, unknown>).args, ["--smol", c.entry, "mcp"])
+          && (server as Record<string, unknown>).enabled !== false;
+        const hookFile = json(read(c.paths[target][1]!)), groups = record(hookFile.hooks ?? {});
+        const sameHook = plannedHooks(c, target).some(row => Array.isArray(groups[row.event]) && hasHook(groups[row.event] as unknown[], row.command, row.timeout));
+        if (sameBinding || sameHook) pluginNotes.push(`${target}: matching amem entries are already present without a setup receipt; apply will not duplicate matching hook commands, and undo preserves the original entries.`);
+      } catch { /* Advisory only: preparing the real change retains the existing configuration validation. */ }
+    }
     const unchanged = !!prior && prior.phase === "applied" && prior.intent === intent(c, target) && prior.changes.every((change, index) => { try { const live = read(change.path); restoreChange(prior, change, index, live); return managedAfter(target, index, change.before, change.after, live); } catch { return false; } });
     const add = command(target, c.bun, c.entry), remove = target === "gemini" ? [...GEMINI_REMOVE] : [target, "mcp", "remove", ...(target === "claude" || target === "qwen" ? ["--scope", "user"] : []), "amem"];
     const installed = available(c, target, options), version = installed && target !== "agy" && mode !== "undo" ? probeClientVersion(c, target, options) : undefined;
     if (version?.matches === false) pluginNotes.push(`WARNING: ${target} version ${version.output}; layout verified on ${version.verified}. Apply remains guarded by native configuration validation.`);
-    return { target, available: installed, ...(version ? { version } : {}), files: c.paths[target], receipt: journal(c, target), ...(target === "agy" ? { cwd: c.workspace!.root } : {}), registration: mode === "undo" ? null : add, lifecycle: mode === "undo" ? "restore original MCP/hook files" : lifecycle(target), hooks: mode === "undo" || unchanged ? [] : plannedHooks(c, target), mcpChange: mode === "undo" ? prior ? "restore" : "unchanged" : unchanged ? "unchanged" : hasAmem ? "replace" : "add", commands: mode === "undo" || prior?.intent === intent(c, target) || !add || !installed ? [] : [...(hasAmem ? [remove] : []), add], state: prior && prior.intent !== intent(c, target) ? "runtime changed; managed entries will update" : prior?.phase ?? "not installed" };
+    return { target, available: installed, ...(version ? { version } : {}), files, receipt: journal(c, target), ...(target === "agy" ? { cwd: c.workspace!.root } : {}), registration: mode === "undo" ? null : add, lifecycle: mode === "undo" ? "restore original MCP/hook files" : lifecycle(target), hooks: mode === "undo" || unchanged ? [] : plannedHooks(c, target), mcpChange: mode === "undo" ? prior ? "restore" : "unchanged" : unchanged ? "unchanged" : hasAmem ? "replace" : "add", commands: mode === "undo" || prior?.intent === intent(c, target) || !add || !installed ? [] : [...(hasAmem ? [remove] : []), add], state: prior && prior.intent !== intent(c, target) ? "runtime changed; managed entries will update" : prior?.phase ?? "not installed" };
   }), notes: [...pluginNotes, ...(/\/[^/]*\d+\.\d+[^/]*\/(?:bin\/)?bun$/.test(c.bun) ? ["this bun path is version-specific; rerun setup --apply after changing Bun"] : []), "Preview only unless --apply or --undo is passed; explicit modes apply without a prompt.", "Native registration commands run in a private staging HOME; only the listed configuration files are published.", "Original file bytes restore exactly when untouched; otherwise undo preserves CLI-owned changes and restores only managed entries, refusing edits to those entries.", "No AGENTS.md, CLAUDE.md or rule files are edited.", `A private ${join(c.state, "setup.lock")} serializes mutations; temporary ${join(realPath(tmpdir()), "amem-setup-*")} staging homes are removed.`, "Codex requires its native /hooks review before newly registered hooks run; setup does not grant hook trust. Runtime registrations use the PATH-resolved absolute Bun path without resolving its stable symlink; setup all reports and skips missing clients."] };
 }
 /** Native probes and registration share one private HOME, cwd and configuration layout. */
@@ -312,12 +345,20 @@ function native(argv: readonly string[], env: Env, cwd: string): void {
     throw Error(`${argv[0]} MCP registration ${reason} in staging; no native output disclosed`);
   }
 }
+function hasHook(rows: readonly unknown[], command: string, timeout: number): boolean {
+  return rows.some(row => {
+    if (!row || typeof row !== "object" || Array.isArray(row)) return false;
+    const group = record(row);
+    return [undefined, "", "*"].some(value => value === group.matcher) && Array.isArray(group.hooks)
+      && group.hooks.some((h: unknown) => { const value = record(h); return value.type === "command" && value.command === command && value.timeout === timeout; });
+  });
+}
 function hookDocument(before: Image, events: readonly string[], commandFor: (event: string) => string, timeout = 1): Image {
   const document = json(before), hooks = document.hooks === undefined ? {} : record(document.hooks);
   for (const event of events) {
     const rows = hooks[event] ?? []; if (!Array.isArray(rows)) throw Error("setup hook groups must be arrays");
     const command = commandFor(event);
-    if (!rows.some(row => [undefined, "", "*"].includes(row?.matcher) && Array.isArray(row?.hooks) && row.hooks.some((h: unknown) => { const value = record(h); return value.type === "command" && value.command === command && value.timeout === timeout; }))) rows.push({ hooks: [{ type: "command", command, timeout }] });
+    if (!hasHook(rows, command, timeout)) rows.push({ hooks: [{ type: "command", command, timeout }] });
     hooks[event] = rows;
   }
   document.hooks = hooks; return objectImage(document, before);
@@ -341,7 +382,10 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
   if (target === "opencode") assertOpencodeLayout(c, "apply");
   if (target === "gemini") assertGeminiHome(c.env);
   const prior = receipt(c, target, false), expected = c.paths[target].map(path => read(path));
-  const restored = prior ? prior.changes.map((change, index) => restoreChange(prior, change, index, expected[index]!)) : expected;
+  // Only a same-file before-image can restore a target. A newly authoritative personal source owns its current bytes.
+  // Mapped per current path: a pre-#203 jcode receipt covers mcp.json only, so config.toml starts from its live image.
+  const restored = c.paths[target].map((path, index) => { const change = prior?.changes[index];
+    return prior && change && change.path === path ? restoreChange(prior, change, index, expected[index]!) : expected[index]!; });
   if (prior?.phase === "applied" && prior.intent === intent(c, target) && prior.changes.every((change, index) => managedAfter(target, index, change.before, change.after, expected[index]!))) return { value: prior, expected, unchanged: true };
   const changes: Change[] = c.paths[target].map((path, i) => ({ key: `${target}:${i}`, path, before: restored[i]!, after: restored[i]!, start: expected[i]! }));
   const staging = mkdtempSync(join(realPath(tmpdir()), "amem-setup-"));
@@ -398,6 +442,7 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
     } else if (target === "jcode") {
       // Shared native pools use the daemon cwd; amem must bind the calling session's project.
       changes[0]!.after = putMcpRecord(target, changes[0]!.before, { command: c.bun, args: ["--smol", c.entry, "mcp"], shared: false });
+      changes[1]!.after = putJcodeHooks(changes[1]!.before, jcodeHookCommand(c.bun, c.entry));
     } else if (target === "opencode") {
       // `opencode mcp add` is interactive for local servers and has no remove; edit the owned entry directly.
       changes[0]!.after = putMcpRecord(target, changes[0]!.before, opencodeServer(c.bun, c.entry));