@staix/agent-mem 0.11.0 → 0.12.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -2,7 +2,7 @@
 
 Curated memory with append-only JSONL logs, a derived SQLite index, short- and long-term tiers, a typed graph, goals with leases, and git sync between machines. Extracted from [agent-hub](https://github.com/STAIxBWLB/agent-hub), with compatible storage and entry IDs.
 
-Version: 0.11.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.12.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 
@@ -114,7 +114,7 @@ A repository may add `.amem/config` (same shape, only `denyPaths`, `piiPatterns`
 
 `amem note add [--kind decision|finding|contract|fail] [--tier short|long] [--scope project|shared] [--title T] [text... | -]` writes one curated note as the person (agent-mem#40 F6). The text is the arguments, `-` to read it from the terminal until end of input, or nothing to open `$VISUAL` (an empty one is skipped) or `$EDITOR` on a private temporary file (the command is run without a shell: an existing path with spaces works as is, otherwise quotes and backslashes split it, and Ctrl-C reaches the editor while it runs). `-` reads the text you type on the terminal until end of input: `note add` needs a terminal on stdin, so it cannot read a pipe, and that differs from a literal reading of "from stdin" in the issue. A `fail` note takes its five fields instead of free text: `--approach`, `--symptom`, `--cause`, `--evidence` (repeatable) and `--retry-when`. All five are required, and the command names the ones that are missing; with none given it opens a labelled template in the editor. The configured policy screens the title and text first, and a refusal never echoes them. Like every ordinary command it needs a terminal and refuses an agent session.
 
-The SessionStart brief carries one line when candidates wait, for example `2 candidates pending, oldest expires in 27 days` (agent-mem#40 F7). It holds numbers only, is read-only (the hook never marks anything shown), comes out of the brief's own byte budget, and is left out when it does not fit. `amem status` adds a `candidates` object (or `unavailable` when `candidates.db` exists but cannot be read, never a false zero) and a warning when any is within 7 days of expiry. `amem review walk` needs a terminal on both stdin and stdout (it refuses when stdout is redirected to a file or a pipe, because nobody would see what it asks about). It prints each pending candidate, oldest first, and only then asks accept, edit, reject, skip or quit: accept goes through the normal policy, edit opens the text in your editor and writes it as your own note (a candidate proposed as a fail note opens the labelled template), and what it prints has control characters removed. Nothing expires unseen: a candidate counts as shown only when `review walk` has printed it (the plain `review list` prints no content and runs in scripts, and the brief line cannot know you read it, so neither marks anything). A candidate is kept past its 30 days until it has been shown, and then for 7 more days. When 500 unseen candidates wait, a new one is refused with a named error (an MCP tool reports a fixed "the review queue is full, ask the person to run `amem review`" reply) instead of dropping an unseen one.
+The SessionStart brief carries one line when candidates wait, for example `2 candidates pending, oldest expires in 27 days` (agent-mem#40 F7). It holds numbers only, is read-only (the hook never marks anything shown), comes out of the brief's own byte budget, and is left out when it does not fit. `amem status --json` adds a `candidates` object (bare `amem status` shows the same as a labelled row and next action) (or `unavailable` when `candidates.db` exists but cannot be read, never a false zero) and a warning when any is within 7 days of expiry. `amem review walk` needs a terminal on both stdin and stdout (it refuses when stdout is redirected to a file or a pipe, because nobody would see what it asks about). It prints each pending candidate, oldest first, and only then asks accept, edit, reject, skip or quit: accept goes through the normal policy, edit opens the text in your editor and writes it as your own note (a candidate proposed as a fail note opens the labelled template), and what it prints has control characters removed. Nothing expires unseen: a candidate counts as shown only when `review walk` has printed it (the plain `review list` prints no content and runs in scripts, and the brief line cannot know you read it, so neither marks anything). A candidate is kept past its 30 days until it has been shown, and then for 7 more days. When 500 unseen candidates wait, a new one is refused with a named error (an MCP tool reports a fixed "the review queue is full, ask the person to run `amem review`" reply) instead of dropping an unseen one.
 
 ## Candidate review
 
@@ -290,6 +290,8 @@ Successful native project identities have a private, bounded derived cache (128
 
 ## Doctor and the sync cadence
 
+`amem doctor`, `amem status` and `amem setup` print a readable report: an overall state, one labelled row per check (`OK`, `ATTENTION`, `SKIPPED`, `UNAVAILABLE`) and the next actions. Color appears only on an interactive terminal and is turned off by `NO_COLOR` or `TERM=dumb`. Add `--json` for the machine-readable object (for `status` and `setup` this was the default before #125).
+
 `amem doctor` prints one read-only report of this project's memory: duplicate and stale notes, pending candidates, capture freshness and hook registration for each CLI (a CLI with no hook is `manual`), the SessionStart brief's token cost, whether the index equals a rebuild of the logs, reader leases and the policy in effect. `amem doctor --json` is a stable machine-readable form (`amem.doctor/v1`). It writes nothing into the memory home (every check runs on a temporary copy of the logs) and creates nothing in a home you never used.
 
 Intake runs at the end of each Codex, Kimi, Pi and Qwen session once `amem setup <cli> --apply` has registered it. Sync is off unless you ask for it: amem registers no sync hook and runs nothing between sessions. To sync on your own schedule, call `amem sync --if-due` from your shell (for example an EXIT trap in `~/.zshrc`; it needs a terminal). It syncs at most hourly, backs off 15 minutes doubling to a day after failures, stops after 30 seconds, and does nothing without a remote set by `amem sync --remote <private git url>`. `--force` skips the schedule and the backoff.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "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

@@ -49,6 +49,8 @@ import { markShown, pendingSummary } from "./memory/candidate-pending.ts";
 import { buildNote, FAIL_TEMPLATE, hasFailLabel, noteAdd, parseFailTemplate, type FailFields } from "./memory/note-add.ts";
 import { runEditor } from "./memory/editor.ts";
 import { doctorReport, doctorText } from "./memory/doctor.ts";
+import { statusText, type StatusView } from "./memory/status-text.ts";
+import { colorEnabled, style, type Style } from "./memory/style.ts";
 import { endLikeSignal, nextSyncAt, readSyncState, recordSyncAttempt, remoteConfigured, syncDue, stopSignal, syncOutcome, usableState, SYNC_IF_DUE_DEADLINE_MS, type StopCause } from "./memory/sync-cadence.ts";
 
 export const PERSON_ONLY = "amem is for the person: an agent reads memory through its `amem mcp` server (see `amem --help`); the person reviews what agents propose with `amem review`";
@@ -200,7 +202,7 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     const { runSetup } = await import("./setup.ts");
     return runSetup(parsed.positionals[0]!, options["--apply"] === true ? "apply" : options["--undo"] === true ? "undo" : "preview", {
       env: context.env ?? process.env, stdinTTY: context.stdinTTY ?? process.stdin.isTTY, cwd: context.cwd ?? process.cwd(),
-      ...(context.setupConfirm ? { confirm: context.setupConfirm } : {}),
+      ...(context.setupConfirm ? { confirm: context.setupConfirm } : {}), json: options["--json"] === true, style: outputStyle(context),
     });
   }
   const goal = parsed.path[0] === "goal", review = parsed.path[0] === "review", sub = goal || review ? parsed.path[1]! : parsed.path[0]!;
@@ -287,7 +289,7 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     // F1: say where the memory lives and which configuration is in effect. The migration fields keep their names and shape; `home` and `config` are added.
     const where = resolveMemoryHome(), loaded = loadAmemConfig(where.home, repoConfigRoot(policyCwd));
     const { config, source } = loaded;
-    return JSON.stringify({ home: { path: where.home, source: where.source },
+    const status = { home: { path: where.home, source: where.source },
       config: { machine: source.machine, repo: source.repo, denyPaths: config.denyPaths.length, piiPatterns: config.piiPatterns.length,
         ...(config.briefBytes !== undefined ? { briefBytes: config.briefBytes } : {}), ...(config.excerptBytes !== undefined ? { excerptBytes: config.excerptBytes } : {}),
         ...(config.capturePaths !== undefined ? { capturePaths: config.capturePaths } : {}), ...(Object.keys(config.capture).length ? { capture: config.capture } : {}) },
@@ -295,14 +297,15 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
       candidates: (() => { const bound = boundProject(), summary = pendingSummary(where.home, [bound, ...aliasedKeys(where.home, bound)], Date.now(), true);
         if (summary === null) return { unavailable: "candidates.db exists but cannot be read" };
         return { ...summary, ...(summary.dueWithin7Days ? { warning: `${summary.dueWithin7Days} candidate${summary.dueWithin7Days === 1 ? "" : "s"} within 7 days of expiry: run \`amem review walk\`` } : {}) }; })(),
-      ...shardMigrationStatus(where.home) }, null, 2);
+      ...shardMigrationStatus(where.home) };
+    return options["--json"] ? JSON.stringify(status, null, 2) : statusText(status as unknown as StatusView, outputStyle(context));
   }
   if (sub === "doctor") {
     // F15: one read-only report; see src/memory/doctor.ts for exactly what "read-only" covers.
     const where = resolveMemoryHome(), project = boundProject();
     const report = await doctorReport({ home: where.home, homeSource: where.source, cwd: policyCwd, project, aliases: aliasedKeys(where.home, project), now: Date.now(),
       openCurated: base => curatedStoreAt(base, project, { deferPromotions: true }) });
-    return options["--json"] ? JSON.stringify(report, null, 2) : doctorText(report);
+    return options["--json"] ? JSON.stringify(report, null, 2) : doctorText(report, outputStyle(context));
   }
   if (sub === "prune") {
     const applying = options["--apply"] === true;
@@ -777,6 +780,9 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     ? `${output}\n(legacy malformed lines skipped: ${receipt.bridgeStatus.skippedRows})` : output;
 }
 
+/** Color for human output only on an interactive stdout without NO_COLOR or TERM=dumb (#125). */
+function outputStyle(context: CliContext): Style { return style(colorEnabled(context.env ?? process.env, context.stdoutTTY ?? process.stdout.isTTY)); }
+
 export function formatCliError(error: unknown): string { return error instanceof DecayApplyError ? error.render() : `amem: ${(error as Error).message}`; }
 
 /** A completed write means rendered output, never evidence of host delivery or citation. */

package/src/commands-table.ts

@@ -25,7 +25,7 @@ export const GLOBAL_OPTIONS = { "--help": flag("Show help") };
 export const ROOT_OPTIONS = { "--version": flag("Show version"), ...json };
 export const COMMANDS: Record<string, CommandDefinition> = {
   consolidate: { description: "Queue deterministic project-local consolidation candidates; curated notes change only after person review", mutates: true, options: { ...json, "--project": text("The current project's key; another project is refused (run from its directory)") } },
-  setup: { description: "Preview reversible MCP setup and supported capture hooks for native coding CLIs; apply and undo are person-only", options: { "--apply": flag("Apply after terminal confirmation"), "--undo": flag("Restore original configuration after confirmation") }, args: [{ name: "target", values: ["claude", "codex", "kimi", "pi", "qwen", "jcode", "agy", "all"] }] },
+  setup: { description: "Preview reversible MCP setup and supported capture hooks for native coding CLIs; apply and undo are person-only", options: { ...json, "--apply": flag("Apply after terminal confirmation"), "--undo": flag("Restore original configuration after confirmation") }, args: [{ name: "target", values: ["claude", "codex", "kimi", "pi", "qwen", "jcode", "agy", "all"] }] },
   mcp: { description: "Run the project-bound MCP stdio server for this session" },
   hook: { description: "Run a fail-open, context-only Claude Code hook", args: [{ name: "event", values: [...HOOK_EVENTS] }] },
   ingest: { description: "Incrementally capture native session transcripts without a watcher", options: { ...json, "--since": text("ISO date or time") }, args: [{ name: "kind", values: ["codex", "kimi", "pi", "qwen"] }] },

package/src/memory/doctor.ts

@@ -10,6 +10,7 @@ import { readSelector } from "./generation.ts";
 import { processLiveness, withGitTimeout } from "./platform.ts";
 import { endLikeSignal, STOP_SIGNALS } from "./sync-cadence.ts";
 import { boundRepoRoot } from "./repo-scope.ts";
+import { facts, label, PLAIN, type Style } from "./style.ts";
 import { shardDir } from "./shard.ts";
 import type { MemoryStore, View } from "./store.ts";
 import { nextSyncAt, readSyncState, remoteConfigured, syncDue, usableState } from "./sync-cadence.ts";
@@ -403,13 +404,46 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   return { schema: DOCTOR_SCHEMA, status: worst(Object.values(sections).map(section => section.status)), home: { path: options.home, source: options.homeSource }, project: options.project, sections };
 }
 
-export function doctorText(report: DoctorReport): string {
-  const mark = (status: SectionStatus) => status === "ok" ? "ok         " : status === "attention" ? "ATTENTION  " : status === "skipped" ? "skipped    " : "unavailable";
-  const lines = [`amem doctor: ${report.status}`, `home ${report.home.path} (${report.home.source}), project ${report.project}`];
-  for (const [name, section] of Object.entries(report.sections)) {
-    const { status, hint, reason, ...detail } = section as Section & { hint?: string; reason?: string };
-    lines.push(`${mark(status)} ${name}: ${JSON.stringify(detail)}${reason ? `  (${reason})` : ""}`);
-    if (hint) lines.push(`            -> ${hint}`);
+/** Section order and one-line descriptions for the person-facing report (#125). */
+const SECTION_TITLE: Record<keyof DoctorReport["sections"], string> = {
+  duplicates: "duplicate notes", stale: "stale path references", candidates: "review candidates", capture: "capture per CLI", brief: "session brief",
+  index: "index equals rebuild", readers: "reader leases", policy: "policy in effect", cadence: "ingest and sync cadence",
+};
+
+function sectionDetail(name: string, detail: Record<string, unknown>, s: Style): string[] {
+  if (name === "capture" && detail.clis && typeof detail.clis === "object") {
+    return Object.entries(detail.clis as Record<string, Record<string, unknown>>).map(([cli, row]) => {
+      const capture = String(row.capture), mark = capture === "fresh" ? s.ok(capture) : capture === "stale" ? s.attention(capture) : s.dim(capture);
+      return `${cli.padEnd(7)} hook ${row.hook}${row.setup ? ` (${row.setup})` : ""}, capture ${mark}${row.lastCaptureAt ? ` (last ${row.lastCaptureAt})` : ""}, ${row.rows} rows`;
+    });
+  }
+  if (name === "cadence") {
+    const sync = (detail.sync ?? {}) as Record<string, unknown>, ingest = (detail.ingest ?? {}) as Record<string, string>;
+    return [`ingest ${Object.entries(ingest).map(([cli, how]) => `${cli} ${how}`).join(", ")}`,
+      `sync remote ${sync.remote}${sync.remote === "configured" ? `, last ok ${sync.lastOkAt ?? "never"}, failures ${sync.failures}${sync.due ? ", due" : ""}` : ""}`];
+  }
+  if (name === "brief" && typeof detail.tokens === "number") return [`${detail.tokens} of ${detail.budget} tokens${detail.coverage ? `, coverage ${facts(detail.coverage as Record<string, unknown>) || "complete"}` : ""}`];
+  const { examples, ...rest } = detail;
+  const line = facts(rest);
+  return [...(line ? [line] : []), ...(Array.isArray(examples) && examples.length ? [`examples ${examples.map(item => Array.isArray(item) ? item.join("=") : String(item)).join(", ")}`] : [])];
+}
+
+/** The person-facing report: overall state, one labelled row per section, then the next actions. `amem doctor --json` keeps the full report. */
+export function doctorText(report: DoctorReport, s: Style = PLAIN): string {
+  const entries = Object.entries(report.sections) as [keyof DoctorReport["sections"], Section & { hint?: string; reason?: string }][];
+  const count = (status: SectionStatus) => entries.filter(([, section]) => section.status === status).length;
+  const summary = facts({ attention: count("attention"), unavailable: count("unavailable"), skipped: count("skipped") });
+  const lines = [`${s.bold("amem doctor:")} ${report.status === "ok" ? s.ok(report.status) : report.status === "attention" ? s.attention(report.status) : s.error(report.status)}${summary ? `  (${summary})` : `  (all ${entries.length} checks ok)`}`,
+    `home     ${report.home.path} ${s.dim(`(${report.home.source})`)}`, `project  ${report.project}`, ""];
+  const actions: string[] = [];
+  for (const [name, section] of entries) {
+    const { status, hint, reason, ...detail } = section;
+    lines.push(`${label(s, status)} ${name}: ${s.dim(SECTION_TITLE[name])}`);
+    for (const line of sectionDetail(name, detail, s)) lines.push(`            ${line}`);
+    if (reason) lines.push(`            ${s.dim(`reason: ${reason}`)}`);
+    if (hint) actions.push(`${name}: ${hint}`);
+    if (name === "capture" && detail.clis) for (const [cli, row] of Object.entries(detail.clis as Record<string, { hint?: string }>)) if (row.hint) actions.push(`capture ${cli}: ${row.hint}`);
   }
+  lines.push("", actions.length ? "Next actions:" : "Next actions: none", ...actions.map(action => `  - ${action}`));
   return lines.join("\n");
 }

package/src/memory/status-text.ts

@@ -0,0 +1,47 @@
+import { facts, label, PLAIN, type Style } from "./style.ts";
+
+/** The `amem status` object as the CLI builds it; `amem status --json` prints it unchanged. */
+export interface StatusView {
+  home: { path: string; source: string };
+  config: { machine: string | null; repo: string | null; denyPaths: number; piiPatterns: number } & Record<string, unknown>;
+  candidates: { unavailable: string } | ({ count: number; oldestExpiresInDays: number | null; dueWithin7Days: number; unshown: number; warning?: string });
+  active: boolean; generation?: string; phase?: string;
+  pending: Record<string, unknown> & { rows: number };
+  deadLeasesRemoved?: { lease: string; at: string }[]; refusals?: string[];
+}
+
+/** Person-facing `amem status` (#125): overall state, the effective home and policy, the counts that matter, then next actions. Zero counters are summarized, never listed. */
+export function statusText(status: StatusView, s: Style = PLAIN): string {
+  const actions: string[] = [], warnings: string[] = [];
+  const candidates = status.candidates;
+  let candidateLine: string, candidateState: "ok" | "attention" | "unavailable";
+  if ("unavailable" in candidates) { candidateState = "unavailable"; candidateLine = candidates.unavailable; warnings.push(candidates.unavailable); }
+  else {
+    candidateState = candidates.dueWithin7Days ? "attention" : "ok";
+    candidateLine = candidates.count ? `${candidates.count} pending${candidates.unshown ? ` (${candidates.unshown} never shown)` : ""}${candidates.oldestExpiresInDays !== null ? `, oldest expires in ${candidates.oldestExpiresInDays} days` : ""}` : "none pending";
+    if (candidates.warning) actions.push(candidates.warning);
+    else if (candidates.count) actions.push("review pending candidates: amem review walk");
+  }
+  const refusals = status.refusals ?? [];
+  const interrupted = status.phase === "captured" && !status.active;   // authoring refuses until activation (generation-index.ts)
+  const migrationState: "ok" | "attention" = refusals.length || status.pending.rows || interrupted ? "attention" : "ok";
+  if (interrupted) actions.push("a shard migration stopped after capture and authoring is refused until it activates: amem migrate --shards --resume");
+  if (refusals.length) warnings.push(...refusals.map(reason => `migration refusal: ${reason}`));
+  if (status.pending.rows && !interrupted) actions.push(`${status.pending.rows} old-layout rows wait for the shard migration: amem migrate --shards --resume carries them (amem migrate --shards --dry-run previews first)`);
+  const overall = candidateState === "unavailable" ? "unavailable" : candidateState === "attention" || migrationState === "attention" ? "attention" : "ok";
+  const { machine, repo, denyPaths, piiPatterns, ...limits } = status.config;
+  const pendingCounts = facts(Object.fromEntries(Object.entries(status.pending).filter(([key]) => !key.endsWith("Ids"))));
+  const lines = [
+    `${s.bold("amem status:")} ${overall === "ok" ? s.ok(overall) : overall === "attention" ? s.attention(overall) : s.error(overall)}`,
+    `home     ${status.home.path} ${s.dim(`(${status.home.source})`)}`,
+    "",
+    `${label(s, "ok")} policy: machine ${machine ?? "none (defaults)"}, repo ${repo ?? "none"}; ${denyPaths} deny paths, ${piiPatterns} PII patterns${facts(limits) ? `; ${facts(limits)}` : ""}`,
+    `${label(s, candidateState)} candidates: ${candidateLine}`,
+    `${label(s, migrationState)} layout: ${status.active ? `shards active${status.generation ? ` (generation ${status.generation.slice(0, 8)})` : ""}` : status.phase ? `shard migration ${status.phase}${interrupted ? ", not active" : ""}` : "single home"}; ${pendingCounts ? `pending ${pendingCounts}` : "no pending old-layout appends"}`,
+    ...(status.deadLeasesRemoved?.length ? [`            ${s.dim(`${status.deadLeasesRemoved.length} dead reader leases removed`)}`] : []),
+    ...(warnings.length ? ["", "Warnings:", ...warnings.map(warning => `  - ${s.attention(warning)}`)] : []),
+    "", actions.length ? "Next actions:" : "Next actions: none", ...actions.map(action => `  - ${action}`),
+    s.dim("Full report: amem status --json; health checks: amem doctor"),
+  ];
+  return lines.join("\n");
+}

package/src/memory/style.ts

@@ -0,0 +1,37 @@
+/**
+ * A tiny, dependency-free text style for person-facing CLI output (#125).
+ * Color is decoration only: every caller also prints a textual label, so plain output carries the same facts.
+ * JSON output never passes through this module.
+ */
+export interface Style {
+  readonly color: boolean;
+  ok(text: string): string;
+  attention(text: string): string;
+  error(text: string): string;
+  dim(text: string): string;
+  bold(text: string): string;
+}
+
+/** Color only for an interactive stdout, and never with NO_COLOR (any value, per no-color.org) or TERM=dumb. */
+export function colorEnabled(env: Readonly<Record<string, string | undefined>>, isTTY: boolean | undefined): boolean {
+  return isTTY === true && env.NO_COLOR === undefined && env.TERM !== "dumb";
+}
+
+const wrap = (on: boolean, open: number, close: number) => (text: string) => on ? `\x1b[${open}m${text}\x1b[${close}m` : text;
+export function style(color: boolean): Style {
+  return { color, ok: wrap(color, 32, 39), attention: wrap(color, 33, 39), error: wrap(color, 31, 39), dim: wrap(color, 2, 22), bold: wrap(color, 1, 22) };
+}
+export const PLAIN: Style = style(false);
+
+/** Status label, padded so the columns line up; the word is always present. */
+export function label(s: Style, state: "ok" | "attention" | "skipped" | "unavailable" | "error"): string {
+  const word = { ok: "OK", attention: "ATTENTION", skipped: "SKIPPED", unavailable: "UNAVAILABLE", error: "ERROR" }[state].padEnd(11);
+  return state === "ok" ? s.ok(word) : state === "attention" ? s.attention(word) : state === "skipped" ? s.dim(word) : s.error(word);
+}
+
+/** "key value" pairs, leaving out zero, empty and null values; returns "" when nothing material is left. */
+export function facts(values: Record<string, unknown>): string {
+  return Object.entries(values).filter(([, value]) => value !== 0 && value !== null && value !== undefined && value !== false && value !== ""
+    && !(Array.isArray(value) && value.length === 0) && !(typeof value === "object" && !Array.isArray(value) && Object.keys(value as object).length === 0))
+    .map(([key, value]) => `${key} ${typeof value === "object" ? Array.isArray(value) ? value.join(", ") : JSON.stringify(value) : String(value)}`).join(", ");
+}

package/src/setup-toml.ts

@@ -162,11 +162,11 @@ function editTomlPath(text: string, path: readonly string[], value: unknown | un
       changes.push({ start: position, end: position, text: `${newline}${key} = ${inline(value)}${eol}` });
     }
     output = replace(text, changes);
-    // Removing the only child of an implicit table must retain its parsed empty parent value.
-    for (let depth = path.length - 1; depth > 0; depth--) {
-      const parent = path.slice(0, depth), wanted = at(expected, parent);
-      if (plain(wanted) && !Object.keys(wanted).length && at(parse(output), parent) === undefined) output += `${output && !output.endsWith("\n") ? eol : ""}[${parent.map(part => JSON.stringify(part)).join(".")}]${eol}`;
-    }
+  }
+  // Removing the only child of an implicit table must retain its parsed empty parent value.
+  for (let depth = path.length - 1; depth > 0; depth--) {
+    const parent = path.slice(0, depth), wanted = at(expected, parent);
+    if (plain(wanted) && !Object.keys(wanted).length && at(parse(output), parent) === undefined) output += `${output && !output.endsWith("\n") ? eol : ""}[${parent.map(part => JSON.stringify(part)).join(".")}]${eol}`;
   }
   if (!isDeepStrictEqual(shape(parse(output)), shape(expected))) return error();
   return output;

package/src/setup.ts

@@ -10,6 +10,7 @@ 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, 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;
@@ -152,7 +153,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");
@@ -227,7 +229,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);
@@ -284,16 +291,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") {
+        // 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(withoutAmem(document), withoutAmem(installed))) throw Error("native registration changed unrelated settings; no configuration published");
+        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.
@@ -425,16 +449,54 @@ 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);
+/** 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})`)}`);
+    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 (asks before writing); --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");
+}
+
+/** What the default confirmation prints before its prompt: 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 (mode === "preview") return options.json ? JSON.stringify(plan, null, 2) : setupPlanText(plan, s);
   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");
+    process.stdout.write(setupConfirmationText(shown, options.json === true, s) + "\n\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);
+  if (!await confirm(plan)) return options.json ? JSON.stringify({ cancelled: true }) : "setup cancelled; nothing changed";
+  const result = mode === "apply" ? applySetup(plan, options) : undoSetup(plan, options);
+  return options.json ? JSON.stringify(result, null, 2) : setupResultText(result, s);
 }