@staix/agent-mem 0.20.0 → 0.20.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "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.20.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.20.1. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -223,6 +223,53 @@ export function manifest() {
     commands: Object.keys(COMMANDS) };
 }
 
+/** Setup apply errors can contain configuration paths or native output. Classify only
+ * this explicit operation into fixed text; never include the caught message or cause. */
+function markedSetupApplyError(parsed: ReturnType<typeof parseCommand>, error: unknown): Error | undefined {
+  const target = parsed.positionals[0];
+  if (parsed.path.length !== 1 || parsed.path[0] !== "setup" || parsed.options["--apply"] !== true || parsed.options["--undo"] === true
+    || parsed.positionals.length !== 1 || target === "console" || !COMMANDS.setup?.args?.[0]?.values?.includes(target!)) return undefined;
+  const detail = error && typeof error === "object" ? error as { message?: unknown; code?: unknown; exitCode?: unknown } : {};
+  const text = typeof detail.message === "string" ? detail.message : "";
+  const code = typeof detail.code === "string" ? detail.code : "";
+  let cause = "setup_apply_failed", next = "Review the setup preview and saved setup ownership state before retrying.", partial = true;
+  if (text === "Memory operation unavailable or refused; no partial result is shown.") {
+    cause = "setup_policy_refused"; next = "Review setup policy with the person and keep denied configuration private."; partial = false;
+  } else if (/^installed (?:claude|codex|kimi|pi|qwen|jcode|opencode|gemini|agy) CLI does not expose MCP registration; no registration command was run$/.test(text)) {
+    cause = "native_capability_unverified"; next = "Verify that the installed client can start and exposes MCP administration, then rerun setup preview."; partial = false;
+  } else if (/^(?:claude|codex|pi|qwen|gemini) MCP registration timed out in staging; no native output disclosed$/.test(text)) {
+    cause = "native_registration_timeout"; next = "Check that the installed client starts promptly, then rerun setup preview."; partial = false;
+  } else if (/^qwen MCP registration rejected command arguments in staging; no native output disclosed$/.test(text)) {
+    cause = "native_arguments_rejected"; next = "Check the installed client's supported MCP command syntax, then rerun setup preview."; partial = false;
+  } else if (/^(?:claude|codex|pi|qwen|gemini) MCP registration failed in staging; no native output disclosed$/.test(text)) {
+    cause = "native_registration_failed"; next = "Check the installed client's MCP administration locally, then rerun setup preview."; partial = false;
+  } else if (/^(?:claude|codex|pi|qwen|gemini) native registration (?:produced no configuration|produced invalid configuration; no configuration published|did not produce the planned amem server|changed unrelated MCP servers; no configuration published)$/.test(text)
+    || text === "codex native registration changed unrelated settings; no configuration published") {
+    cause = "native_result_mismatch"; next = "Review the installed client's configuration format and version, then rerun setup preview."; partial = false;
+  } else if (text === "setup receipt version is unsupported; run setup or undo with the release that wrote it") {
+    cause = "setup_receipt_version_unsupported"; next = "Run setup or undo with the amem release that wrote the receipt."; partial = false;
+  } else if (/^setup-owned .+ changed; refusing to overwrite it$/.test(text) || text === "Pi amem-session extension already exists and is not this setup's file"
+    || text === "previous-runtime hook settings are customized; review hook configuration before retrying setup"
+    || /^setup receipt (?:does not match this installation|target mismatch|invalid|directory ownership invalid)$/.test(text)) {
+    cause = "setup_ownership_conflict"; next = "Review the managed entries and saved setup receipt before retrying; keep unrelated configuration intact."; partial = false;
+  } else if (/^setup is busy(?: or its lock is unreadable|; retry after the active setup exits)$/.test(text)) {
+    cause = "setup_busy"; next = "Wait for the active setup to finish, then rerun setup preview."; partial = false;
+  } else if (/^setup configuration changed (?:while reading|before removal|before publication|during preparation)$/.test(text)) {
+    cause = "setup_configuration_changed"; next = "Wait for other configuration writers to finish, then rerun setup preview.";
+  } else if (/^setup (?:configuration (?:must be an object|does not parse as a JSON object|does not parse as TOML|unavailable or oversized)|hook (?:groups|handlers) must be arrays|TOML unavailable or unsupported; no configuration changed)$/.test(text)) {
+    cause = "setup_configuration_unavailable"; next = "Review the configuration's supported format and size, then rerun setup preview."; partial = false;
+  } else if (["EACCES", "EPERM", "EROFS"].includes(code)) {
+    cause = "setup_filesystem_permissions"; next = "Review the setup file and directory permissions, then rerun setup preview.";
+  } else if (["ENOSPC", "EDQUOT"].includes(code)) {
+    cause = "setup_storage_capacity"; next = "Check available storage and quotas, then rerun setup preview.";
+  } else if (["EIO", "ENOENT", "ENOTDIR", "EISDIR", "EMFILE", "ENFILE"].includes(code)) {
+    cause = "setup_filesystem_unavailable"; next = "Check that the setup configuration and storage are available, then rerun setup preview.";
+  }
+  const safe = new Error(`Setup apply failed [cause: ${cause}]. Next step: ${next} Recheck with amem setup ${target} --json before another apply.${partial ? " Some setup changes may already be applied; review current state before retrying." : ""}`);
+  if (typeof detail.exitCode === "number" && Number.isSafeInteger(detail.exitCode)) Object.assign(safe, { exitCode: detail.exitCode });
+  return safe;
+}
+
 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);
@@ -262,9 +309,11 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     if (marked && error instanceof AgentUsageError) throw error;
     if (marked) {
       // parseCommand is pure: when it rejects argv, the error it raised is a usage error, not memory data.
-      let usage: Error | undefined;
-      try { parseCommand(argv); } catch (parseError) { usage = parseError as Error; }
+      let usage: Error | undefined, parsed: ReturnType<typeof parseCommand> | undefined;
+      try { parsed = parseCommand(argv); } catch (parseError) { usage = parseError as Error; }
       if (usage) throw Object.assign(new Error(usage.message), (error as { exitCode?: number }).exitCode === undefined ? {} : { exitCode: (error as { exitCode?: number }).exitCode });
+      const setupError = parsed && markedSetupApplyError(parsed, error);
+      if (setupError) throw setupError;
     }
     // Marked administrative failures must not reveal a target's private state or native errors.
     if (marked) throw Error("Memory operation unavailable or refused; no partial result is shown.");

package/src/setup-drift.ts

@@ -26,7 +26,7 @@ export interface SetupDriftReport {
 }
 
 interface ReceiptChange { key: string; path: string; before: ConfigImage; after: ConfigImage }
-interface Receipt { version: 1; target: SetupTarget; phase: "prepared" | "applied"; changes: ReceiptChange[] }
+interface Receipt { version: 1 | 2; target: SetupTarget; phase: "prepared" | "applied"; changes: ReceiptChange[] }
 const JOURNAL_BYTES = 12 * SETUP_CONFIG_BYTES;
 // ponytail: at most 32 MiB of receipt/config input per doctor call; use metadata-only receipts before widening.
 const READ_BYTES = 32 * 1024 * 1024;
@@ -60,14 +60,14 @@ function parseImage(value: unknown): ConfigImage {
 }
 
 function parseReceipt(value: unknown, target: SetupTarget, expectedPaths: readonly string[]): Receipt {
-  if (!plain(value) || value.version !== 1 || value.target !== target || !/^[a-f0-9]{64}$/.test(String(value.intent)) || !["applied", "prepared"].includes(String(value.phase)) || !Array.isArray(value.changes) || value.changes.length !== expectedPaths.length && !(target === "jcode" && value.changes.length === 1)) throw Error("invalid receipt");
+  if (!plain(value) || (value.version !== 1 && value.version !== 2) || value.target !== target || !/^[a-f0-9]{64}$/.test(String(value.intent)) || !["applied", "prepared"].includes(String(value.phase)) || !Array.isArray(value.changes) || value.changes.length !== expectedPaths.length && !(target === "jcode" && value.changes.length === 1)) throw Error("invalid receipt");
   const changes: ReceiptChange[] = [];
   for (let index = 0; index < value.changes.length; index++) {
     const item: unknown = value.changes[index];
     if (!plain(item) || item.key !== `${target}:${index}` || typeof item.path !== "string" || !isAbsolute(item.path) || item.path.length > 4096 || item.path.includes("\0")) throw Error("invalid receipt");
     changes.push({ key: `${target}:${index}`, path: item.path, before: parseImage(item.before), after: parseImage(item.after) });
   }
-  return { version: 1, target, phase: value.phase as Receipt["phase"], changes };
+  return { version: value.version as 1 | 2, target, phase: value.phase as Receipt["phase"], changes };
 }
 
 function workspaceRoot(cwd: string): string | undefined {

package/src/setup-jcode.ts

@@ -1,6 +1,6 @@
 import type { ConfigImage } from "./setup-owned.ts";
 import { createJsonMcpCodec } from "./setup-json.ts";
-import { setTomlPath } from "./setup-toml.ts";
+import { restoreRemovedItems, setTomlPath } from "./setup-toml.ts";
 
 const codec = createJsonMcpCodec({ canonicalKey: "servers", aliases: ["mcpServers"], label: "Jcode" });
 export function readJcodeMcp(image: ConfigImage): unknown { return codec.read(image); }
@@ -27,13 +27,14 @@ function commands(value: unknown): 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 {
+export function putJcodeHooks(before: ConfigImage, command: string, previous: readonly 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);
+    const current = commands(hooks[event]), existing = previous.length ? current.filter(value => !previous.includes(value)) : current;
+    if (existing.includes(command) && existing.length === current.length) continue;
+    const next = existing.includes(command) ? existing : [...existing, command];
+    text = setTomlPath(text, ["hooks", event], next.length === 1 && !existing.length ? command : next);
   }
   return tomlImage(text, before.mode);
 }
@@ -43,8 +44,14 @@ function ownedCommands(before: ConfigImage, after: ConfigImage): Map<string, str
   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;
 }
+/** True only when the receipt removes an original command, requiring a restoring reader. */
+export function jcodeRetiresOriginalHook(before: ConfigImage, after: ConfigImage): boolean {
+  return [...ownedCommands(after, before).values()].some(commands => commands.length > 0);
+}
 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))); }
+  try { const hooks = hooksTable(tomlText(current)) ?? {}; const original = hooksTable(tomlText(before)) ?? {}, installed = hooksTable(tomlText(after)) ?? {};
+    return [...ownedCommands(before, after)].every(([event, owned]) => owned.every(item => commands(hooks[event]).includes(item))
+      && commands(original[event]).filter(item => !commands(installed[event]).includes(item)).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. */
@@ -56,8 +63,10 @@ export function restoreJcodeHooks(before: ConfigImage, after: ConfigImage, curre
   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];
+    const prior = original[event], priorCommands = commands(prior), installed = commands((hooksTable(tomlText(after)) ?? {})[event]);
+    const removed = priorCommands.filter(item => !installed.includes(item));
+    if (!live.some(item => mine.includes(item)) && !removed.length) continue;
+    const kept = restoreRemovedItems(priorCommands, installed, live.filter(item => !mine.includes(item)), value => value);
     // 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;

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, jcodeHooksManaged, restoreJcodeHooks } from "./setup-jcode.ts";
+import { SETUP_CONFIG_BYTES, insertTomlArrayItems, restoreRemovedItems, setTomlPath, updateTomlArray } from "./setup-toml.ts";
+import { readJcodeMcp, putJcodeMcp, restoreJcodeMcp, jcodeHooksManaged, jcodeRetiresOriginalHook, 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 }
@@ -82,6 +82,38 @@ function restoreJsonHooks(before: ConfigImage, after: ConfigImage, current: Conf
     }
     if (!next.length && object(b.hooks ?? {})[event] === undefined) delete groups[event]; else groups[event] = next;
   }
+  // Replacement removes adopted rows too; restore their original position/group,
+  // keeping current groups, native metadata and unrelated handlers intact.
+  const removed = added(installed, original, row => row.id);
+  c.hooks = groups;
+  if (removed.some(row => hooks(c, strict).some(value => value.command === row.command && !original.some(old => old.id === value.id))))
+    throw Error("setup-owned hook changed; refusing to overwrite it");
+  for (const [event, raw] of Object.entries(object(b.hooks ?? {}))) {
+    if (strict && qwenHookControls.has(event)) continue;
+    const entries = (rows: readonly unknown[]) => rows.flatMap(value => { const group = object(value);
+      return (group.hooks as unknown[]).flatMap(value => { const row = hook(event, group, value, strict); return row ? [{ group, sourceGroup: group, value, row }] : []; }); });
+    const beforeRows = entries(raw as unknown[]), afterRows = entries((object(a.hooks ?? {})[event] as unknown[] | undefined) ?? []);
+    const liveGroups = (groups[event] as Record<string, unknown>[] | undefined) ?? [], liveRows = entries(liveGroups), existing = new Set(liveRows);
+    const order = restoreRemovedItems(beforeRows, afterRows, liveRows, value => value.row.id), placed = new Map<Record<string, unknown>, Record<string, unknown>>();
+    const originalIds = new Map((raw as Record<string, unknown>[]).map(group => [group, new Set(beforeRows.filter(row => row.group === group && afterRows.some(installed => installed.row.id === row.row.id)).map(row => row.row.id))]));
+    for (let index = 0; index < order.length; index++) {
+      const row = order[index]!; if (existing.has(row)) continue;
+      const source = row.group, ids = originalIds.get(source)!;
+      const next = order.slice(index + 1).find(value => existing.has(value) && ids.has(value.row.id));
+      const prior = order.slice(0, index).reverse().find(value => existing.has(value) ? ids.has(value.row.id) : value.sourceGroup === source);
+      let group = placed.get(source) ?? next?.group ?? prior?.group;
+      if (!group) {
+        group = { ...source, hooks: [] };
+        const following = order.slice(index + 1).find(value => existing.has(value))?.group;
+        liveGroups.splice(following ? liveGroups.indexOf(following) : liveGroups.length, 0, group);
+      }
+      const handlers = group.hooks as unknown[], nextAt = next?.group === group ? handlers.indexOf(next.value) : -1;
+      const priorAt = prior?.group === group ? handlers.indexOf(prior.value) : -1;
+      handlers.splice(nextAt >= 0 ? nextAt : priorAt >= 0 ? priorAt + 1 : handlers.length, 0, row.value);
+      placed.set(source, group); row.group = group;
+    }
+    if (order.length) groups[event] = liveGroups;
+  }
   if (!Object.keys(groups).length && b.hooks === undefined) delete c.hooks; else if (c.hooks !== undefined) c.hooks = groups;
   return finishJson(c, current, before);
 }
@@ -96,10 +128,15 @@ function restoreKimi(before: ConfigImage, after: ConfigImage, current: ConfigIma
     if (at >= 0) c.splice(at, 1);
     else if (c.some(value => value.command === row.command && !b.some(old => kimiKey(old) === kimiKey(value)))) throw Error("setup-owned Kimi hook changed; refusing to overwrite it");
   }
+  const withoutInstalled = [...c];
+  for (const row of added(a, b, kimiKey)) if (c.some(value => value.command === row.command && !b.some(old => kimiKey(old) === kimiKey(value))))
+    throw Error("setup-owned Kimi hook changed; refusing to overwrite it");
+  c.splice(0, c.length, ...restoreRemovedItems(b, a, c, kimiKey));
   if (isDeepStrictEqual(c, kimiHooks(current))) return current;
   const original = toml(before);
   const value = !c.length && original.hooks === undefined ? undefined : c;
-  const result = value === undefined ? setTomlPath(text(current), ["hooks"], undefined) : updateTomlArray(text(current), ["hooks"], value);
+  const retired = updateTomlArray(text(current), ["hooks"], withoutInstalled);
+  const result = value === undefined ? setTomlPath(retired, ["hooks"], undefined) : insertTomlArrayItems(retired, ["hooks"], value);
   if (before.bytes === null && Object.keys(object(Bun.TOML.parse(result))).length === 0) return { ...before, mode: current.mode };
   return rendered(result, current);
 }
@@ -131,18 +168,37 @@ export function restoreOwned(target: string, index: number, before: ConfigImage,
   if (current.bytes === before.bytes) return current;
   throw Error("setup-owned Pi extension changed; refusing to overwrite it");
 }
+/** Only removal of an original/adopted hook needs receipt v2; added-only receipts remain v1-readable. */
+export function retiresOriginalHook(target: string, index: number, before: ConfigImage, after: ConfigImage): boolean {
+  if (target === "qwen" && index === 0 || ["claude", "codex"].includes(target) && index === 1) {
+    const strict = target === "qwen";
+    return added(hooks(json(after), strict), hooks(json(before), strict), row => row.id).length > 0;
+  }
+  if (index !== 1) return false;
+  if (target === "kimi") return added(kimiHooks(after), kimiHooks(before), kimiKey).length > 0;
+  if (target === "jcode") return jcodeRetiresOriginalHook(before, after);
+  return target === "pi" && before.bytes !== null && before.bytes !== after.bytes;
+}
 export function managedAfter(target: string, index: number, before: ConfigImage, after: ConfigImage, current: ConfigImage): boolean {
   if (target === "qwen" && index === 0) {
     const needed = added(hooks(json(before), true), hooks(json(after), true), row => row.id), live = hooks(json(current), true);
-    return isDeepStrictEqual(mcpRecord(target, after), mcpRecord(target, current)) && needed.every(row => live.some(value => value.id === row.id));
+    const retired = added(hooks(json(after), true), hooks(json(before), true), row => row.id), installed = hooks(json(after), true);
+    return isDeepStrictEqual(mcpRecord(target, after), mcpRecord(target, current)) && needed.every(row => live.some(value => value.id === row.id))
+      && retired.every(row => live.filter(value => value.id === row.id).length <= installed.filter(value => value.id === row.id).length);
   }
   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));
+    const retired = added(hooks(json(after)), hooks(json(before)), row => row.id), installed = hooks(json(after));
+    return needed.every(row => live.some(value => value.id === row.id))
+      && retired.every(row => live.filter(value => value.id === row.id).length <= installed.filter(value => value.id === row.id).length);
+  }
+  if (target === "kimi") {
+    const original = kimiHooks(before), installed = kimiHooks(after), live = kimiHooks(current);
+    return added(original, installed, kimiKey).every(row => live.some(value => kimiKey(value) === kimiKey(row)))
+      && added(installed, original, kimiKey).every(row => live.filter(value => kimiKey(value) === kimiKey(row)).length <= installed.filter(value => kimiKey(value) === kimiKey(row)).length);
   }
-  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;
 }
 

package/src/setup-toml.ts

@@ -217,6 +217,26 @@ function arrayElements(text: string, open: number): { close: number; elements: A
   }
   return error();
 }
+/** Reinsert only rows removed by this installer, anchored to surviving original rows.
+ * Current rows stay in their own order; unrelated additions/deletions are never reversed. */
+export function restoreRemovedItems<T>(before: readonly T[], after: readonly T[], current: readonly T[], key: (value: T) => string): T[] {
+  const counts = (rows: readonly T[]) => { const found = new Map<string, number>(); for (const row of rows) found.set(key(row), (found.get(key(row)) ?? 0) + 1); return found; };
+  const original = counts(before), installed = counts(after), live = counts(current), seen = new Map<string, number>();
+  const ordinals = before.map(row => { const id = key(row), ordinal = seen.get(id) ?? 0; seen.set(id, ordinal + 1); return ordinal; });
+  const result = [...current];
+  const anchor = (index: number) => { const id = key(before[index]!); let ordinal = ordinals[index]!;
+    return result.findIndex(row => key(row) === id && ordinal-- === 0); };
+  for (let index = 0; index < before.length; index++) {
+    const row = before[index]!, id = key(row), retained = installed.get(id) ?? 0;
+    if (retained) { installed.set(id, retained - 1); continue; }
+    if ((live.get(id) ?? 0) >= original.get(id)!) continue;
+    let at = result.length, found = false;
+    for (let next = index + 1; next < before.length; next++) { const position = anchor(next); if (position >= 0) { at = position; found = true; break; } }
+    if (!found) for (let prior = index - 1; prior >= 0; prior--) { const position = anchor(prior); if (position >= 0) { at = position + 1; break; } }
+    result.splice(at, 0, row); live.set(id, (live.get(id) ?? 0) + 1);
+  }
+  return result;
+}
 /** Keep an ordered subsequence of existing elements, optionally adding new elements only at the tail. */
 function arrayEdit(before: readonly unknown[], after: readonly unknown[]): { keep: Set<number>; append: readonly unknown[] } {
   const old = before.map(value => JSON.stringify(shape(value))), next = after.map(value => JSON.stringify(shape(value)));
@@ -294,3 +314,41 @@ export function updateTomlArray(text: string, path: readonly string[], expectedA
   if (!isDeepStrictEqual(shape(parse(output)), shape(expected))) return error();
   return output;
 }
+
+/** Insert restored rows without deleting/reordering or reserializing surviving TOML elements. */
+export function insertTomlArrayItems(text: string, path: readonly string[], expectedArray: readonly unknown[]): string {
+  if (!path.length || path.length > 8 || path.some(key => typeof key !== "string" || Buffer.byteLength(key) > 256 || /[\p{Cc}\p{Cf}]/u.test(key)) || !Array.isArray(expectedArray)) return error();
+  const original = parse(text), current = at(original, path); shape(original); shape(expectedArray);
+  if (current === undefined || Array.isArray(current) && current.length === 0) return updateTomlArray(text, path, expectedArray);
+  if (!Array.isArray(current)) return error();
+  const key = (value: unknown) => JSON.stringify(shape(value)), pending = new Map<number, unknown[]>(); let cursor = 0;
+  for (const value of expectedArray) {
+    if (cursor < current.length && key(value) === key(current[cursor])) cursor++;
+    else pending.set(cursor, [...(pending.get(cursor) ?? []), value]);
+  }
+  if (cursor !== current.length) return error(); // Every original element must survive in order.
+  if (!pending.size) return text;
+  const units = statements(text), assignment = units.find(unit => !unit.header && unit.path.length === path.length && prefix(path, unit.path));
+  const eol = text.includes("\r\n") ? "\r\n" : "\n", changes: Replacement[] = [];
+  if (assignment) {
+    let open = assignment.equal! + 1; while (/\s/.test(text[open] ?? "")) open++;
+    const array = arrayElements(text, open); if (array.elements.length !== current.length) return error();
+    for (const [index, values] of pending) if (index < current.length) {
+      const start = index ? array.elements[index - 1]!.comma! + 1 : open + 1;
+      changes.push({ start, end: start, text: ` ${values.map(inline).join(", ")}, ` });
+    }
+  } else {
+    const headers = units.filter(unit => unit.header && unit.array && unit.path.length === path.length && prefix(path, unit.path));
+    if (headers.length !== current.length) return error();
+    for (const [index, values] of pending) if (index < current.length) {
+      const header = headers[index]!, prior = units[units.indexOf(header) - 1], start = prior?.end ?? 0;
+      changes.push({ start, end: start, text: `${start && text[start - 1] !== "\n" ? eol : ""}${appendedTables(path, values, eol)}` });
+    }
+  }
+  let output = replace(text, changes);
+  const tail = pending.get(current.length);
+  if (tail?.length) output = updateTomlArray(output, path, [...(at(parse(output), path) as unknown[]), ...tail]);
+  const expected = parse(text); edit(expected, path, [...expectedArray]);
+  if (!isDeepStrictEqual(shape(parse(output)), shape(expected))) return error();
+  return output;
+}

package/src/setup.ts

@@ -1,7 +1,7 @@
 import { cliAttribution } from "./memory/cli-attribution.ts";
 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 { managedAfter, mcpRecord, putMcpRecord, restoreOwned, retiresOriginalHook, sameImage, type ConfigImage } from "./setup-owned.ts";
 import { opencodeServer } from "./setup-opencode.ts";
 import { assertGeminiHome, assertGeminiRuntime, GEMINI_REMOVE, geminiAddCommand } from "./setup-gemini.ts";
 import { resolveSetupPaths, opencodeConfigRoot } from "./setup-paths.ts";
@@ -34,7 +34,7 @@ type Image = ConfigImage;
 interface PlannedHook { event: string; command: string; timeout: number }
 interface Change { key: string; path: string; before: Image; after: Image; start?: Image }
 interface DirectoryIdentity { dev: number; ino: number }
-interface Receipt { createdDirectory?: DirectoryIdentity; version: 1; target: SetupTarget; intent: string; phase: "prepared" | "applied"; changes: Change[] }
+interface Receipt { createdDirectory?: DirectoryIdentity; version: 1 | 2; 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. */
@@ -205,12 +205,13 @@ 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 === "jcode" ? ["jcode-hooks-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"] : []), ...(["claude", "codex", "kimi", "pi", "qwen", "jcode"].includes(target) ? ["root-hooks-v2"] : []), ...(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 && !(target === "jcode" && value.changes.length === 1)) throw Error("setup receipt does not match this installation");
+  if (value.version !== 1 && value.version !== 2) throw Error("setup receipt version is unsupported; run setup or undo with the release that wrote it");
+  if (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]); 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");
@@ -353,10 +354,28 @@ function hasHook(rows: readonly unknown[], command: string, timeout: number): bo
       && 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 {
+function hookDocument(before: Image, events: readonly string[], commandFor: (event: string) => string, timeout = 1, previousFor?: (event: string) => readonly string[]): 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 rawRows = hooks[event] ?? []; if (!Array.isArray(rawRows)) throw Error("setup hook groups must be arrays");
+    let rows: unknown[] = rawRows;
+    const previous = previousFor?.(event);
+    if (previous?.length) rows = rows.flatMap(value => {
+      const group = record(value); if (!Array.isArray(group.hooks)) throw Error("setup hook handlers must be arrays");
+      let removed = false;
+      const kept = group.hooks.filter(h => {
+        const handler = record(h);
+        if (handler.type !== "command" || !previous.includes(String(handler.command))) return true;
+        // ponytail: upgrade generated shapes only; customized controls require review.
+        // Upgrade path: lexical command-only migration with native control validation.
+        if (![undefined, "", "*"].includes(group.matcher as string | undefined) || handler.timeout !== timeout
+          || Object.keys(group).some(key => !["matcher", "hooks", "trusted_hash", "trustedHash"].includes(key))
+          || Object.keys(handler).some(key => !["type", "command", "timeout", "trusted_hash", "trustedHash"].includes(key)))
+          throw Error("previous-runtime hook settings are customized; review hook configuration before retrying setup");
+        removed = true; return false;
+      });
+      return removed ? kept.length ? [{ ...group, hooks: kept }] : [] : [value];
+    });
     const command = commandFor(event);
     if (!hasHook(rows, command, timeout)) rows.push({ hooks: [{ type: "command", command, timeout }] });
     hooks[event] = rows;
@@ -366,6 +385,20 @@ function hookDocument(before: Image, events: readonly string[], commandFor: (eve
 function piExtension(bun: string, entry: string): string {
   return `// amem setup managed session-end ingest; no resident worker or instruction injection.\nimport { spawnSync } from 'node:child_process';\nexport default function (pi) {\n  pi.on('session_shutdown', (_event, ctx) => {\n    try { spawnSync(${JSON.stringify(bun)}, ['--smol', ${JSON.stringify(entry)}, 'ingest', 'pi'], { cwd: ctx.cwd, stdio: 'ignore', timeout: 2500 }); } catch {}\n  });\n}\n`;
 }
+/** Bind old hooks to exact current/receipted MCP launchers, including an adopted baseline.
+ * The feature intent tag forces one repair of receipts from the old add-only installer. */
+function previousRuntimes(target: SetupTarget, images: readonly Image[], bun: string, entry: string): { bun: string; entry: string }[] {
+  const found = new Map<string, { bun: string; entry: string }>();
+  for (const image of images) {
+    const value = mcpRecord(target, image);
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const server = value as Record<string, unknown>, args = server.args;
+    if (typeof server.command === "string" && isAbsolute(server.command) && Array.isArray(args) && args.length === 3
+      && args[0] === "--smol" && typeof args[1] === "string" && isAbsolute(args[1]) && args[2] === "mcp"
+      && (server.command !== bun || args[1] !== entry)) found.set(JSON.stringify([server.command, args[1]]), { bun: server.command, entry: args[1] });
+  }
+  return [...found.values()];
+}
 interface Prepared { value: Receipt; expected: Image[]; unchanged: boolean }
 function restoreChange(value: Receipt, change: Change, index: number, live: Image): Image {
   const start = value.phase === "prepared" && change.start && !sameImage(change.start, change.before) ? change.start : undefined;
@@ -388,6 +421,9 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
     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 previousMcp = prior?.changes[0];
+  const previous = previousRuntimes(target, [expected[0]!, ...(previousMcp && previousMcp.path === c.paths[target][0] ? [previousMcp.before, previousMcp.after, ...(previousMcp.start ? [previousMcp.start] : [])] : [])], c.bun, c.entry);
+  const oldLaunches = previous.map(runtime => `${quote(runtime.bun)} --smol ${quote(runtime.entry)}`);
   const staging = mkdtempSync(join(realPath(tmpdir()), "amem-setup-"));
   try {
     const { env, staged } = stagingEnvironment(c, target, options, staging);
@@ -442,7 +478,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));
+      changes[1]!.after = putJcodeHooks(changes[1]!.before, jcodeHookCommand(c.bun, c.entry), previous.map(runtime => jcodeHookCommand(runtime.bun, runtime.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));
@@ -452,25 +488,36 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
       changes[0]!.after = objectImage(document, changes[0]!.before);
     }
     const capture = (kind: string) => `${quote(c.bun)} --smol ${quote(c.entry)} ingest ${kind} --json`;
-    if (target === "claude") changes[1]!.after = hookDocument(changes[1]!.before, HOOK_EVENTS, event => `${quote(c.bun)} --smol ${quote(c.entry)} hook ${event}`);
-    if (target === "codex") changes[1]!.after = hookDocument(changes[1]!.before, ["SessionEnd"], () => capture("codex"), 3);
+    if (target === "claude") changes[1]!.after = hookDocument(changes[1]!.before, HOOK_EVENTS, event => `${quote(c.bun)} --smol ${quote(c.entry)} hook ${event}`, 1, event => oldLaunches.map(launch => `${launch} hook ${event}`));
+    if (target === "codex") changes[1]!.after = hookDocument(changes[1]!.before, ["SessionEnd"], () => capture("codex"), 3, () => oldLaunches.map(launch => `${launch} ingest codex --json`));
     // Qwen's user MCP and hooks share settings.json: publish and journal one combined image.
-    if (target === "qwen") changes[0]!.after = hookDocument(changes[0]!.after, ["SessionEnd"], () => capture("qwen"), 3);
+    if (target === "qwen") changes[0]!.after = hookDocument(changes[0]!.after, ["SessionEnd"], () => capture("qwen"), 3, () => oldLaunches.map(launch => `${launch} ingest qwen --json`));
     if (target === "kimi") {
       const old = changes[1]!.before.bytes === null ? "" : Buffer.from(changes[1]!.before.bytes!, "base64").toString("utf8");
-      const parsed = toml(old), hooks = parsed.hooks ?? [];
-      if (!Array.isArray(hooks)) throw Error("Kimi hooks must be an array");
+      const parsed = toml(old), rawHooks = parsed.hooks ?? [];
+      if (!Array.isArray(rawHooks)) throw Error("Kimi hooks must be an array");
+      let hooks: unknown[] = rawHooks;
+      if (oldLaunches.length) hooks = hooks.filter(h => {
+        const row = record(h);
+        if (row.event !== "SessionEnd" || !oldLaunches.some(launch => row.command === `${launch} ingest kimi --json`)) return true;
+        if (![undefined, "", "*"].includes(row.matcher as string | undefined) || row.timeout !== 3
+          || Object.keys(row).some(key => !["event", "command", "matcher", "timeout"].includes(key)))
+          throw Error("previous-runtime hook settings are customized; review hook configuration before retrying setup");
+        return false;
+      });
+      const retired = updateTomlArray(old, ["hooks"], hooks);
       if (!hooks.some(h => record(h).event === "SessionEnd" && record(h).command === capture("kimi"))) hooks.push({ event: "SessionEnd", command: capture("kimi"), timeout: 3 });
-      changes[1]!.after = image(updateTomlArray(old, ["hooks"], hooks), changes[1]!.before.mode);
+      changes[1]!.after = image(updateTomlArray(retired, ["hooks"], hooks), changes[1]!.before.mode);
     }
     if (target === "pi") {
       const content = piExtension(c.bun, c.entry);
-      if (!prior && changes[1]!.before.bytes !== null && changes[1]!.before.bytes !== image(content).bytes) throw Error("Pi amem-session extension already exists and is not this setup's file");
+      if (!prior && changes[1]!.before.bytes !== null && changes[1]!.before.bytes !== image(content).bytes
+        && !previous.some(runtime => changes[1]!.before.bytes === image(piExtension(runtime.bun, runtime.entry)).bytes)) throw Error("Pi amem-session extension already exists and is not this setup's file");
       changes[1]!.after = image(content, changes[1]!.before.mode);
     }
     // Never publish an image that this installer's own read/undo boundary cannot reopen.
     if (changes.some(change => change.after.bytes !== null && Buffer.from(change.after.bytes, "base64").byteLength > MAX)) throw Error("planned setup configuration exceeds the size bound; no configuration published");
-    return { value: { version: 1, target, intent: intent(c, target), phase: "prepared", changes, ...(prior?.createdDirectory ? { createdDirectory: prior.createdDirectory } : {}) }, expected, unchanged: false };
+    return { value: { version: previous.length && changes.some((change, index) => retiresOriginalHook(target, index, change.before, change.after)) ? 2 : 1, target, intent: intent(c, target), phase: "prepared", changes, ...(prior?.createdDirectory ? { createdDirectory: prior.createdDirectory } : {}) }, expected, unchanged: false };
   } finally { rmSync(staging, { recursive: true, force: true }); }
 }
 function save(c: ReturnType<typeof context>, value: Receipt): void { write(journal(c, value.target), image(JSON.stringify(value) + "\n")); }