@staix/agent-mem 0.11.0 → 0.13.0

package/src/setup.ts

@@ -1,21 +1,28 @@
+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 { 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";
 import { homedir, tmpdir } from "node:os";
-import { createInterface } from "node:readline/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { HOOK_EVENTS } from "./hook-contract.ts";
 import { memoryHome } from "./memory/home.ts";
+import { label, PLAIN, singleLine, type Style } from "./memory/style.ts";
 import { canonicalPath, memoryGitEnv, memoryGitSync, processLiveness, processSignature, realPath } from "./memory/platform.ts";
 
 export const SETUP_TARGETS = ["claude", "codex", "kimi", "pi", "qwen", "jcode", "agy"] as const;
 /** Workspace-scoped Antigravity setup is always selected explicitly. */
 export const SETUP_ALL_TARGETS = SETUP_TARGETS.filter(target => target !== "agy");
 export type SetupTarget = typeof SETUP_TARGETS[number];
+// Only recorded layout verification versions belong here; null means no version was recorded.
+const SETUP_VERIFIED_VERSIONS: Readonly<Record<SetupTarget, string | null>> = {
+  claude: null, codex: "0.165.0", kimi: null, pi: null, qwen: "0.26.1", jcode: "0.99.1", agy: null,
+};
+interface ClientVersion { output: string | null; verified: string | null; matches: boolean | null }
 type Env = Readonly<Record<string, string | undefined>>;
 type Image = ConfigImage;
 interface PlannedHook { event: string; command: string; timeout: number }
@@ -24,7 +31,7 @@ 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;
-  /** Trusted confirmation seam; ordinary CLI use always asks the person through stdin. */
+  /** @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. */
   beforePublish?: (file: string) => void;
@@ -33,7 +40,7 @@ export interface SetupContext {
 }
 export interface SetupPlan {
   targets: SetupTarget[]; mode: "preview" | "apply" | "undo";
-  actions: { target: SetupTarget; files: string[]; receipt: string; cwd?: string; registration: string[] | null; lifecycle: string; available: boolean; hooks: PlannedHook[]; mcpChange: "add" | "replace" | "restore" | "unchanged"; commands: string[][]; state: string }[];
+  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[];
 }
 const MAX = SETUP_CONFIG_BYTES, JOURNAL_MAX = 12 * MAX;
@@ -152,7 +159,8 @@ function context(options: SetupContext, workspace?: WorkspaceBinding) {
 }
 function command(target: SetupTarget, bun: string, entry: string): string[] | null {
   if (target === "kimi" || target === "jcode" || target === "agy") return null;
-  return [target, "mcp", "add", ...(target === "claude" || target === "qwen" ? ["--scope", "user", "--transport", "stdio"] : []), "amem", "--", bun, "--smol", entry, "mcp"];
+  if (target === "qwen") return [target, "mcp", "add", "--scope", "user", "--transport", "stdio", "amem", bun, "--", "--smol", entry, "mcp"];
+  return [target, "mcp", "add", ...(target === "claude" ? ["--scope", "user", "--transport", "stdio"] : []), "amem", "--", bun, "--smol", entry, "mcp"];
 }
 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");
@@ -161,7 +169,7 @@ function assertJcodeRuntime(c: ReturnType<typeof context>): void {
   assertJcodeHome(c.env);
   if ([c.bun, c.entry].some(value => value.includes("${"))) throw Error("Jcode interpolates environment placeholders in MCP command paths; 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, ...(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 === "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;
@@ -184,7 +192,7 @@ function plannedHooks(c: ReturnType<typeof context>, target: SetupTarget): Plann
   if (target === "jcode" || 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}`, timeout: target === "pi" ? 2.5 : 3 }];
+    : [{ 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 === "agy" ? "MCP only; native capture unavailable" : 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 {
@@ -217,8 +225,43 @@ export function planSetup(target: string, mode: SetupPlan["mode"] = "preview", o
     const hasAmem = target === "jcode" || target === "agy" ? mcpRecord(target, original) !== undefined : Object.hasOwn(record(document[target === "codex" ? "mcp_servers" : "mcpServers"] ?? {}), "amem");
     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, "mcp", "remove", ...(target === "claude" || target === "qwen" ? ["--scope", "user"] : []), "amem"];
-    return { target, available: available(c, target, options), 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 || !available(c, target, options) ? [] : [...(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 confirmed in a person's terminal.", "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."] };
+    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" };
+  }), 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. */
+function stagingEnvironment(c: ReturnType<typeof context>, target: SetupTarget, options: SetupContext, staging: string) {
+  const env: Record<string, string | undefined> = { ...c.env, HOME: staging, AMEM_HOME: join(staging, "memory"), AGENTHUB_HOME: join(staging, "hub"), CODEX_HOME: join(staging, ".codex"), KIMI_CODE_HOME: join(staging, ".kimi-code"), PI_CODING_AGENT_DIR: join(staging, ".pi", "agent"), QWEN_HOME: join(staging, ".qwen"), JCODE_HOME: join(staging, ".jcode") };
+  Object.assign(env, { XDG_CONFIG_HOME: join(staging, ".config"), XDG_DATA_HOME: join(staging, ".local", "share"), XDG_CACHE_HOME: join(staging, ".cache"), XDG_STATE_HOME: join(staging, ".local", "state"), TMPDIR: join(staging, "tmp"), TMP: join(staging, "tmp"), TEMP: join(staging, "tmp") });
+  env.QWEN_RUNTIME_DIR = join(staging, "qwen-runtime");
+  env.QWEN_CODE_SYSTEM_SETTINGS_PATH = join(staging, "qwen-system-settings.json");
+  env.QWEN_CODE_SYSTEM_DEFAULTS_PATH = join(staging, "qwen-system-defaults.json");
+  mkdirSync(env.TMPDIR!, { mode: 0o700 });
+  if (c.env.CLAUDE_CONFIG_DIR?.trim()) env.CLAUDE_CONFIG_DIR = join(staging, ".claude"); else delete env.CLAUDE_CONFIG_DIR;
+  // The staging workspace is a trusted private binding, not a Git repository or the real caller cwd.
+  const staged = context({ ...options, env, cwd: staging }, target === "agy" ? { root: staging, ignored: true, assertCurrent() {} } : undefined);
+  // Codex refuses an explicit CODEX_HOME that does not exist, even for mcp add.
+  mkdirSync(dirname(staged.paths[target][0]!), { recursive: true, mode: 0o700 });
+  return { env, staged };
+}
+/** Advisory only: never queried by apply/undo or persisted in the ownership receipt. */
+function probeClientVersion(c: ReturnType<typeof context>, target: SetupTarget, options: SetupContext): ClientVersion {
+  const verified = SETUP_VERIFIED_VERSIONS[target];
+  let output: string | null = null;
+  // Like the help probe, trusted native fixtures do not invoke installed executables.
+  if (!options.native) {
+    let staging: string | undefined;
+    try {
+      staging = mkdtempSync(join(realPath(tmpdir()), "amem-setup-"));
+      const { env } = stagingEnvironment(c, target, options, staging);
+      const result = spawnSync(target, ["--version"], { cwd: staging, env: { ...env }, encoding: "utf8", timeout: 1000, maxBuffer: 4096, stdio: ["ignore", "pipe", "pipe"] });
+      if (result.status === 0 && !result.error) output = Array.from(singleLine(result.stdout).trim()).slice(0, 256).join("") || null;
+    } catch { /* An absent, failed or timed-out native version never prevents setup. */ }
+    finally { if (staging) try { rmSync(staging, { recursive: true, force: true }); } catch { output = null; } }
+  }
+  const observed = output?.match(/(?:^|\s)v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)(?=\s|$)/)?.[1];
+  return { output, verified, matches: observed === undefined || verified === null ? null : observed === verified };
 }
 function verifyNativeMcp(target: SetupTarget, env: Env, cwd: string): void {
   // In older free-form Pi CLIs, an unknown subcommand can be treated as a model prompt.
@@ -227,7 +270,12 @@ function verifyNativeMcp(target: SetupTarget, env: Env, cwd: string): void {
 }
 function native(argv: readonly string[], env: Env, cwd: string): void {
   const result = spawnSync(argv[0]!, argv.slice(1), { cwd, env: { ...env }, encoding: "utf8", timeout: 10_000, maxBuffer: MAX, stdio: ["ignore", "pipe", "pipe"] });
-  if (result.status !== 0) throw Error(`${argv[0]} MCP registration failed in staging; no native output disclosed`);
+  if (result.status !== 0) {
+    const timedOut = (result.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT";
+    const argumentsRejected = argv[0] === "qwen" && `${result.stderr ?? ""}\n${result.stdout ?? ""}`.includes("Not enough non-option arguments:");
+    const reason = timedOut ? "timed out" : argumentsRejected ? "rejected command arguments" : "failed";
+    throw Error(`${argv[0]} MCP registration ${reason} in staging; no native output disclosed`);
+  }
 }
 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);
@@ -261,17 +309,7 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
   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-"));
   try {
-    const env: Record<string, string | undefined> = { ...c.env, HOME: staging, AMEM_HOME: join(staging, "memory"), AGENTHUB_HOME: join(staging, "hub"), CODEX_HOME: join(staging, ".codex"), KIMI_CODE_HOME: join(staging, ".kimi-code"), PI_CODING_AGENT_DIR: join(staging, ".pi", "agent"), QWEN_HOME: join(staging, ".qwen"), JCODE_HOME: join(staging, ".jcode") };
-    Object.assign(env, { XDG_CONFIG_HOME: join(staging, ".config"), XDG_DATA_HOME: join(staging, ".local", "share"), XDG_CACHE_HOME: join(staging, ".cache"), XDG_STATE_HOME: join(staging, ".local", "state"), TMPDIR: join(staging, "tmp"), TMP: join(staging, "tmp"), TEMP: join(staging, "tmp") });
-    env.QWEN_RUNTIME_DIR = join(staging, "qwen-runtime");
-    env.QWEN_CODE_SYSTEM_SETTINGS_PATH = join(staging, "qwen-system-settings.json");
-    env.QWEN_CODE_SYSTEM_DEFAULTS_PATH = join(staging, "qwen-system-defaults.json");
-    mkdirSync(env.TMPDIR!, { mode: 0o700 });
-    if (c.env.CLAUDE_CONFIG_DIR?.trim()) env.CLAUDE_CONFIG_DIR = join(staging, ".claude"); else delete env.CLAUDE_CONFIG_DIR;
-    // The staging workspace is a trusted private binding, not a Git repository or the real caller cwd.
-    const staged = context({ ...options, env, cwd: staging }, target === "agy" ? { root: staging, ignored: true, assertCurrent() {} } : undefined);
-    // Codex refuses an explicit CODEX_HOME that does not exist, even for mcp add.
-    mkdirSync(dirname(staged.paths[target][0]!), { recursive: true, mode: 0o700 });
+    const { env, staged } = stagingEnvironment(c, target, options, staging);
     for (let i = 0; i < changes.length; i++) if (expected[i]!.bytes !== null) write(staged.paths[target][i]!, expected[i]!);
     const argv = command(target, c.bun, c.entry);
     if (argv && prior?.intent === intent(c, target)) {
@@ -284,16 +322,33 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
       if (servers && Object.hasOwn(record(servers), "amem")) (options.native ?? native)([target, "mcp", "remove", ...(target === "claude" || target === "qwen" ? ["--scope", "user"] : []), "amem"], env, staging);
       (options.native ?? native)(argv, env, staging);
       changes[0]!.after = { ...read(staged.paths[target][0]!), mode: changes[0]!.before.mode };
-      if (changes[0]!.after.bytes === null) throw Error("native registration produced no configuration");
+      if (changes[0]!.after.bytes === null) throw Error(`${target} native registration produced no configuration`);
       const installedText = Buffer.from(changes[0]!.after.bytes!, "base64").toString("utf8");
-      const installed = target === "codex" ? toml(installedText) : json(changes[0]!.after);
-      const installedServer = record(record(installed[target === "codex" ? "mcp_servers" : "mcpServers"]).amem);
-      if (installedServer.command !== c.bun || JSON.stringify(installedServer.args) !== JSON.stringify(["--smol", c.entry, "mcp"]) || installedServer.enabled === false) throw Error("native registration did not produce the planned amem server");
+      let installed: Record<string, unknown>, installedServer: Record<string, unknown>;
+      try {
+        installed = target === "codex" ? toml(installedText) : json(changes[0]!.after);
+        installedServer = record(record(installed[target === "codex" ? "mcp_servers" : "mcpServers"]).amem);
+      } catch { throw Error(`${target} native registration produced invalid configuration; no configuration published`); }
+      if (installedServer.command !== c.bun || JSON.stringify(installedServer.args) !== JSON.stringify(["--smol", c.entry, "mcp"]) || installedServer.enabled === false) throw Error(`${target} native registration did not produce the planned amem server`);
       const serverKey = target === "codex" ? "mcp_servers" : "mcpServers";
       const withoutAmem = (value: Record<string, unknown>) => { const copy = { ...value }, servers = { ...record(value[serverKey] ?? {}) }; delete servers.amem; copy[serverKey] = servers; return copy; };
-      if (!isDeepStrictEqual(withoutAmem(document)[serverKey], withoutAmem(installed)[serverKey])) throw Error("native registration changed unrelated MCP servers; no configuration published");
+      const originalUnrelated = withoutAmem(document), installedUnrelated = withoutAmem(installed);
       if (target === "codex") {
-        if (!isDeepStrictEqual(withoutAmem(document), withoutAmem(installed))) throw Error("native registration changed unrelated settings; no configuration published");
+        // Restore the omitted default only in this detached comparison, never in native output.
+        const originalServers = record(originalUnrelated[serverKey]), installedServers = record(installedUnrelated[serverKey]);
+        for (const [name, value] of Object.entries(originalServers)) {
+          if (!Object.hasOwn(installedServers, name)) continue;
+          const before = record(value), after = installedServers[name];
+          if (typeof before.command === "string" && Object.hasOwn(before, "args") && Array.isArray(before.args) && before.args.length === 0
+              && after && typeof after === "object" && !Array.isArray(after) && !Object.hasOwn(after, "args")) {
+            installedServers[name] = { ...after, args: [] };
+          }
+        }
+      }
+      if (!isDeepStrictEqual(originalUnrelated[serverKey], installedUnrelated[serverKey])) throw Error(`${target} native registration changed unrelated MCP servers; no configuration published`);
+      if (target === "codex") {
+        if (!isDeepStrictEqual(originalUnrelated, installedUnrelated)) throw Error("codex native registration changed unrelated settings; no configuration published");
+        changes[0]!.after = putMcpRecord(target, changes[0]!.before, installedServer);
       } else {
         // Keep all unrelated JSON settings from the original; use only the CLI-generated server record.
         // Qwen's restored image also retires its previous managed hook on a runtime upgrade.
@@ -311,7 +366,7 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
       servers.amem = { command: c.bun, args: ["--smol", c.entry, "mcp"] }; document.mcpServers = servers;
       changes[0]!.after = objectImage(document, changes[0]!.before);
     }
-    const capture = (kind: string) => `${quote(c.bun)} --smol ${quote(c.entry)} ingest ${kind}`;
+    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);
     // Qwen's user MCP and hooks share settings.json: publish and journal one combined image.
@@ -367,7 +422,7 @@ function contextForPlan(plan: SetupPlan, options: SetupContext) {
 function publishGuard(c: ReturnType<typeof context>, target: SetupTarget, options: SetupContext) {
   return target === "agy" ? (file: string) => { options.beforePublish?.(file); c.workspace!.assertCurrent(); } : options.beforePublish;
 }
-/** Caller enforces person markers/TTY and confirmation; CLI-owned unrelated fields remain live. */
+/** CLI-owned unrelated fields remain live. */
 function applyUnlocked(plan: SetupPlan, options: SetupContext = {}): SetupApplyResult {
   const c = contextForPlan(plan, options), skipped: { target: SetupTarget; reason: string }[] = [];
   const targets = plan.targets.filter(target => { if (available(c, target, options)) return true; if (plan.targets.length === 1) throw Error(`${target} CLI is not installed`); skipped.push({ target, reason: "CLI not installed" }); return false; });
@@ -425,16 +480,51 @@ export function undoSetup(plan: SetupPlan, options: SetupContext = {}): { restor
   return withSetupLock(options, () => undoUnlocked(plan, options));
 }
 
-export async function runSetup(target: string, mode: SetupPlan["mode"], options: SetupContext = {}): Promise<string> {
-  const plan = planSetup(target, mode, options);
-  if (mode === "preview") return JSON.stringify(plan, null, 2);
-  if (!(options.stdinTTY ?? process.stdin.isTTY)) throw Error("setup --apply/--undo require a terminal on stdin");
-  const confirm = options.confirm ?? (async (shown: SetupPlan) => {
-    process.stdout.write(JSON.stringify(shown, null, 2) + "\n");
-    const terminal = createInterface({ input: process.stdin, output: process.stdout });
-    try { return (await terminal.question(`Type yes to ${mode} the listed configuration changes: `)).trim() === "yes"; }
-    finally { terminal.close(); }
-  });
-  if (!await confirm(plan)) return JSON.stringify({ cancelled: true });
-  return JSON.stringify(mode === "apply" ? applySetup(plan, options) : undoSetup(plan, options), null, 2);
+/** Person-facing setup plan (#125): each target once, with its effective files, MCP and hook changes, then skipped clients and notes. `--json` keeps the raw plan. */
+export function setupPlanText(plan: SetupPlan, s: Style = PLAIN): string {
+  const verb = plan.mode === "undo" ? "undo" : plan.mode === "apply" ? "apply" : "preview";
+  // Undo restores every target with a receipt whether or not its CLI is still installed (undoUnlocked), so undo never collapses an action.
+  const full = (action: SetupPlan["actions"][number]) => plan.mode === "undo" || action.available;
+  const skipped = plan.actions.filter(action => !full(action)), changing = plan.actions.filter(action => full(action) && action.mcpChange !== "unchanged");
+  const lines = [`${s.bold(`amem setup ${verb}:`)} ${plan.targets.length} target${plan.targets.length === 1 ? "" : "s"}, ${changing.length} with ${plan.mode === "undo" ? "restores" : "MCP changes"}${skipped.length ? `, ${skipped.length} skipped` : ""}`, ""];
+  for (const action of plan.actions) {
+    if (!full(action)) { lines.push(`${label(s, "skipped")} ${s.bold(action.target)}: CLI not installed`); continue; }
+    const state = action.mcpChange === "unchanged" ? "ok" : "attention";
+    const what = action.mcpChange === "unchanged" ? plan.mode === "undo" ? "no setup receipt; nothing to restore" : "already set up; no change" : action.mcpChange === "restore" ? `restore original MCP/hook files${action.available ? "" : " (CLI not installed)"}` : `MCP ${action.mcpChange}`;
+    lines.push(`${label(s, state)} ${s.bold(action.target)}: ${what} ${s.dim(`(${action.state})`)}`);
+    if (action.version) {
+      const reported = action.version.output === null ? "unknown" : action.version.verified && action.version.matches === null ? `unrecognised (${action.version.output})` : action.version.output;
+      lines.push(`            version ${reported}; ${action.version.verified ? `verified ${action.version.verified}` : "unverified (no verified version recorded)"}`);
+    }
+    for (const file of action.files) lines.push(`            file     ${file}`);
+    if (action.cwd) lines.push(`            cwd      ${action.cwd}`);
+    lines.push(`            receipt  ${action.receipt}`);
+    if (action.available && action.registration) lines.push(`            command  ${action.registration.map(quote).join(" ")}`);
+    for (const hook of action.hooks) lines.push(`            hook     ${hook.event}: ${hook.command} (timeout ${hook.timeout})`);
+    if (action.available && !action.hooks.length && plan.mode !== "undo") lines.push(`            hook     ${s.dim("none")}`);
+    lines.push(`            ${s.dim(action.lifecycle)}`);
+  }
+  const warnings = plan.notes.filter(note => /^WARNING|detected|version-specific/.test(note)), notes = plan.notes.filter(note => !warnings.includes(note));
+  if (skipped.length) lines.push("", `Skipped clients: ${skipped.map(action => action.target).join(", ")} (not installed)`);
+  if (warnings.length) lines.push("", "Warnings:", ...warnings.map(note => `  - ${s.attention(note)}`));
+  lines.push("", "Notes:", ...notes.map(note => `  - ${note}`));
+  if (plan.mode === "preview") lines.push("", `Next: amem setup ${plan.targets.length === 1 ? plan.targets[0] : "all"} --apply writes without a prompt; --json prints the full plan`);
+  return lines.join("\n");
+}
+
+function setupResultText(result: SetupApplyResult | { restored: SetupTarget[] }, s: Style): string {
+  if ("restored" in result) return `${label(s, "ok")} restored: ${result.restored.join(", ") || "none"}`;
+  return [`${label(s, "ok")} applied: ${result.applied.join(", ") || "none"}`, `${label(s, "ok")} unchanged: ${result.unchanged.join(", ") || "none"}`,
+    ...(result.skipped ?? []).map(item => `${label(s, "skipped")} ${item.target}: ${item.reason}`)].join("\n");
+}
+
+/** Compatibility formatter for confirmation-style callers: the raw plan under `--json`, the readable plan otherwise. */
+export function setupConfirmationText(plan: SetupPlan, json: boolean, s: Style = PLAIN): string { return json ? JSON.stringify(plan, null, 2) : setupPlanText(plan, s); }
+
+export async function runSetup(target: string, mode: SetupPlan["mode"], options: SetupContext & { json?: boolean; style?: Style } = {}): Promise<string> {
+  const plan = planSetup(target, mode, options), s = options.json ? PLAIN : options.style ?? PLAIN;
+  if (cliAttribution()?.actor === "agent" && !configuredPolicy(memoryHome(options.env ?? process.env), options.cwd ?? process.cwd()).screenStandalone(JSON.parse(JSON.stringify(plan)))) throw Error("Memory operation unavailable or refused; no partial result is shown.");
+  if (mode === "preview") return options.json ? JSON.stringify(plan, null, 2) : setupPlanText(plan, s);
+  const result = mode === "apply" ? applySetup(plan, options) : undoSetup(plan, options);
+  return options.json ? JSON.stringify(result, null, 2) : setupResultText(result, s);
 }