@sabaiway/agent-workflow-kit 14.24.0 → 14.25.0

package/tools/init-project.mjs

@@ -0,0 +1,400 @@
+import { closeSync, lstatSync, openSync, readFileSync, readdirSync, readlinkSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { resolveGitHooksPath } from './commit-guard.mjs';
+import { dirCovers } from './declared-paths.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
+import { preflightInit } from './init-preflight.mjs';
+import { buildRecommendations, hostFacts } from './recommendations.mjs';
+import { compareSemver } from './semver-lite.mjs';
+import { EXPECTED_WORKFLOW_VERSION } from './velocity-profile.mjs';
+import { LANE_CONSOLE, VARIANT_LANES, consoleArgv, isProtectedPath, laneOf, routeLine, writesOf } from './write-lanes.mjs';
+
+const INSIDE_LINE = 'you are inside an agent; run this in your own terminal';
+const APPLY_PROMPT = 'apply? y/N: ';
+const RUN_NONE = 'y applies every preview above (a sudo install asks once more on its own line); run none of their commands yourself';
+const RESTART_LINE = 'restart the agent from this folder: init changed its configuration';
+const SETTINGS = ['.claude/settings.json', '.claude/settings.local.json', '.mcp.json', '.git/config'];
+const FILE_DIRS = ['.claude/agents', '.claude/hooks'];
+// The record key whose state is the sorted *.json names of its directory, so a created file is a change.
+const JSON_NAMES = '*.json';
+const DANGLING = new Set(['ENOENT', 'ENOTDIR', 'ELOOP']);
+const INSTALL_VARIANT = 'sandbox-provision.installable';
+const DEFAULT_IO = { lstat: lstatSync, stat: statSync, readlink: readlinkSync, readFile: readFileSync, readdir: readdirSync,
+  openSync, closeSync, geteuid: process.geteuid };
+const isYes = (answer) => answer === 'y' || answer === 'Y';
+
+const readStat = (path, io) => {
+  try {
+    return io.lstat(path);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    throw error;
+  }
+};
+
+export const findProject = ({ cwd, lstat = lstatSync }) => {
+  const candidates = [];
+  const visit = (root) => {
+    const io = { lstat };
+    if (readStat(join(root, 'docs/ai'), io)?.isDirectory()) {
+      const shape = readStat(join(root, 'docs/ai/.workflow-version'), io) ? 'stamped' : 'pre-versioned';
+      candidates.push({ root, shape });
+    }
+    const parent = dirname(root);
+    if (!readStat(join(root, '.git'), io) && parent !== root) visit(parent);
+  };
+  visit(resolve(cwd));
+  return { candidates };
+};
+
+const readEntries = (dir, io) => readStat(dir, io)?.isDirectory() ? io.readdir(dir).sort() : [];
+const collectPaths = ({ root, home, hooksDir }, io) => {
+  const paths = [join(home, '.claude/settings.json')];
+  if (root === null) return paths;
+  const docs = join(root, 'docs/ai');
+  paths.push(...SETTINGS.map((path) => join(root, path)), join(docs, '.workflow-version'), join(docs, JSON_NAMES));
+  for (const dir of [...FILE_DIRS.map((path) => join(root, path)), hooksDir]) {
+    paths.push(dir, ...readEntries(dir, io).map((name) => join(dir, name)));
+  }
+  paths.push(...readEntries(docs, io).filter((name) => name.endsWith('.json')).map((name) => join(docs, name)));
+  return paths;
+};
+
+const fileState = (path, io) => `file:${Buffer.from(io.readFile(path)).toString('hex')}`;
+const otherState = (stat) => `other:${stat.mode}:${stat.rdev}`;
+const entryState = (path, io) => {
+  const stat = io.lstat(path);
+  if (stat.isDirectory()) return 'directory';
+  if (stat.isSymbolicLink()) return `link:${io.readlink(path)}`;
+  return stat.isFile() ? fileState(path, io) : otherState(stat);
+};
+// A directory reads as its sorted entries with each entry's own state, one level deep, so a changed file in it is a change.
+const statState = (path, stat, io) => {
+  if (stat.isDirectory()) return `directory:${JSON.stringify(io.readdir(path).sort().map((name) => [name, entryState(join(path, name), io)]))}`;
+  return stat.isFile() ? fileState(path, io) : otherState(stat);
+};
+const followedState = (path, io) => {
+  try {
+    return statState(path, io.stat(path), io);
+  } catch (error) {
+    if (DANGLING.has(error.code)) return 'absent';
+    throw error;
+  }
+};
+const readState = (path, io) => {
+  if (basename(path) === JSON_NAMES) {
+    const names = readStat(dirname(path), io)?.isDirectory() ? io.readdir(dirname(path)).filter((name) => name.endsWith('.json')) : null;
+    return names === null ? 'absent' : `names:${JSON.stringify(names.sort())}`;
+  }
+  const stat = readStat(path, io);
+  if (stat === null) return 'absent';
+  if (stat.isSymbolicLink()) return `link:${io.readlink(path)}:${followedState(path, io)}`;
+  return statState(path, stat, io);
+};
+const stateOf = (path, io) => {
+  try {
+    return readState(path, io);
+  } catch (error) {
+    throw new Error(`${path} could not be read: ${error.code ?? error.message}`);
+  }
+};
+const recordPaths = (paths, io) => new Map([...new Set(paths)].map((path) => [path, stateOf(path, io)]));
+const findChanged = (record, io) => [...record].find(([path, state]) => {
+  try {
+    return readState(path, io) !== state;
+  } catch {
+    return true;
+  }
+})?.[0];
+// After an apply a path that cannot be read is recorded as such, so the next comparison stops the batch on it.
+const refreshState = (path, io) => {
+  try {
+    return readState(path, io);
+  } catch (error) {
+    return `unreadable:${error.code ?? error.message}`;
+  }
+};
+const DIRECTORY = 'directory:';
+const entriesOf = (state) => (state === 'absent' ? [] : JSON.parse(state.slice(DIRECTORY.length)));
+// A recorded parent moves only by the written entry, so an entry created or removed beside it still stops the batch.
+const refreshParent = (record, path, io) => {
+  const [parent, name, current] = [dirname(path), basename(path), refreshState(dirname(path), io)];
+  const recorded = record.get(parent);
+  if (!(recorded === 'absent' || recorded.startsWith(DIRECTORY)) || !current.startsWith(DIRECTORY)) return;
+  const merged = [...entriesOf(recorded).filter(([entry]) => entry !== name), ...entriesOf(current).filter(([entry]) => entry === name)];
+  record.set(parent, DIRECTORY + JSON.stringify(merged.sort(([a], [b]) => (a < b ? -1 : 1))));
+};
+const refreshWrites = (record, paths, io) => {
+  for (const path of paths) {
+    record.set(path, refreshState(path, io));
+    if (record.has(dirname(path))) refreshParent(record, path, io);
+    if (readStat(path, io)?.isDirectory()) {
+      for (const watched of record.keys()) {
+        if (watched.startsWith(path + sep)) record.set(watched, refreshState(watched, io));
+      }
+      for (const child of readEntries(path, io).map((name) => join(path, name))) record.set(child, refreshState(child, io));
+    }
+  }
+};
+
+const findMasks = (paths, facts, io, print) => {
+  const masks = new Set();
+  const root = facts.root ?? facts.cwd;
+  for (const path of new Set(paths)) {
+    if (!isProtectedPath(path, { root, home: facts.home, hooksDir: join(root, '.git/hooks') })) continue;
+    const stat = readStat(path, io);
+    if (!stat?.isFile() || stat.size !== 0 || (stat.mode & 0o222) !== 0) continue;
+    masks.add(path);
+    print(`${path}: an empty read-only file — a running agent command's mask (run init again once it ends) or litter a sandbox left (remove it, then run init again)`);
+  }
+  return masks;
+};
+
+const launch = async (context, argv, stdio) => {
+  try {
+    const result = await context.spawn(argv, { cwd: context.facts.root ?? context.cwd, env: context.spawnEnv, stdio });
+    if (!result || typeof result !== 'object') return { status: null, stdout: '', stderr: 'empty answer', valid: false };
+    return {
+      status: result.status ?? null,
+      stdout: String(result.stdout ?? ''),
+      stderr: String(result.stderr ?? result.error?.message ?? result.signal ?? ''),
+      valid: typeof result.status === 'number' && !result.error && !result.signal,
+    };
+  } catch (error) {
+    return { status: null, stdout: '', stderr: String(error.code ?? error.message ?? error), valid: false };
+  }
+};
+
+// Outside a project only the host-scoped variants reach the queue: an apply-only one or one judged over a claude dir.
+const reachesQueue = (variant, facts) => {
+  if (facts.root !== null) return true;
+  const argv = consoleArgv(variant, facts);
+  return Boolean(argv) && (argv.preview === null || argv.preview.includes('--claude-dir'));
+};
+const isMasked = (variant, context) => (writesOf(variant, context.facts) ?? [])
+  .some((write) => [...context.masks].some((mask) => dirCovers(write, mask)));
+
+// context.items keeps the console items of the advisor's latest return, before the queue's filters.
+const getQueue = async (context) => {
+  const { items } = await context.recommend(context.facts.root, { keySet: context.keySet });
+  context.items = items.filter(({ variant }) => laneOf(variant) === LANE_CONSOLE);
+  return context.items.filter(({ variant }) => reachesQueue(variant, context.facts) && !isMasked(variant, context));
+};
+
+const printNotPending = (context) => {
+  const plain = routeLine('velocity-core');
+  const variants = Object.keys(VARIANT_LANES).filter((variant) => laneOf(variant) === LANE_CONSOLE && routeLine(variant)?.length > plain.length);
+  const keys = new Set();
+  for (const variant of variants) {
+    const key = variant.split('.')[0];
+    if (keys.has(key)) continue;
+    keys.add(key);
+    if (!reachesQueue(variant, context.facts) || context.items.some((item) => item.key === key)) continue;
+    const preview = consoleArgv(variant, context.facts)?.preview;
+    const index = preview?.indexOf('--claude-dir') ?? -1;
+    const judged = index < 0 ? '' : ` (judged ${preview[index + 1]})`;
+    context.print(`not pending in this console: ${key}${judged}`);
+  }
+};
+
+const printNote = (context, key) => {
+  const lines = String(context.io.readFile(join(context.facts.toolsDir, '../references/modes/recommendations.md'), 'utf8')).split('\n');
+  const start = lines.findIndex((line) => line.startsWith(`- \`${key}\` — `));
+  if (start < 0) return;
+  const end = lines.findIndex((line, index) => index > start && !line.startsWith(' ') && !line.startsWith('\t'));
+  for (const line of lines.slice(start, end < 0 ? lines.length : end)) context.print(line);
+};
+
+const previewQueue = async (context, queue) => {
+  const batch = [];
+  for (const item of queue) {
+    const argv = consoleArgv(item.variant, context.facts);
+    if (!argv?.preview) continue;
+    context.print(`preview: ${item.variant}`);
+    const result = await launch(context, argv.preview, 'pipe');
+    const success = result.valid && (result.status === 0 || (result.status === 3 && result.stdout.includes('status=missing-binaries')));
+    if (!success) {
+      context.print(`preview refused (exit ${result.status}): ${item.variant}`);
+      if (result.stdout) context.print(result.stdout);
+      if (result.stderr) context.print(result.stderr);
+      continue;
+    }
+    context.print(result.stdout);
+    const tuple = result.stdout.match(/--apply\s+(\S+)/)?.[1];
+    const facts = { ...context.facts, tuple };
+    batch.push({ ...item, applyArgv: consoleArgv(item.variant, facts).apply, writes: writesOf(item.variant, facts) });
+    printNote(context, item.key);
+  }
+  for (const item of queue.filter(({ variant }) => consoleArgv(variant, context.facts) === null)) {
+    context.print(`listed, not applied here: ${item.variant} — ${item.what}`);
+  }
+  return batch;
+};
+
+const isConfiguration = (path, root) => root !== null && (
+  SETTINGS.slice(0, 3).some((rel) => path === join(root, rel))
+  || ['.claude/agents', '.claude/hooks'].some((rel) => path === join(root, rel) || path.startsWith(join(root, rel) + sep))
+);
+
+// The record is the state the first preview reads: taken before any preview, compared before each apply.
+const takeRecord = (context, queue) => {
+  const previewable = queue.filter(({ variant }) => consoleArgv(variant, context.facts)?.preview);
+  if (previewable.length === 0) return new Map();
+  const paths = [...collectPaths(context.facts, context.io), ...previewable.flatMap(({ variant }) => writesOf(variant, context.facts))];
+  try {
+    return recordPaths(paths, context.io);
+  } catch (error) {
+    for (const item of previewable) context.print(`not applied: ${item.variant} — ${error.message}`);
+    return null;
+  }
+};
+
+const runPass = async (context, queue) => {
+  const record = takeRecord(context, queue);
+  if (record === null) return { code: 1, successes: 0, variants: [] };
+  const batch = await previewQueue(context, queue);
+  if (batch.length === 0) return { code: 0, successes: 0, variants: [] };
+  const before = new Map(record);
+  const outcome = { code: 0, successes: 0, variants: batch.map((item) => item.variant) };
+  context.print(RUN_NONE);
+  if (!isYes(await context.terminal.ask(APPLY_PROMPT))) return outcome;
+  for (const [index, item] of batch.entries()) {
+    if (item.variant === INSTALL_VARIANT && !isYes(await context.terminal.ask('the sandbox install may ask for your sudo password: y runs it, Enter skips: '))) continue;
+    const changed = findChanged(record, context.io);
+    if (changed) {
+      for (const later of batch.slice(index)) context.print(`not applied: ${later.variant} — ${changed} changed outside this batch`);
+      outcome.code = 1;
+      break;
+    }
+    const result = await launch(context, item.applyArgv, ['inherit', 'pipe', 'inherit']);
+    if (result.stdout) context.print(result.stdout);
+    const success = result.valid && (result.status === 0 || (result.status === 5 && result.stdout.includes('install completed')));
+    if (!success) {
+      context.print(`apply failed (exit ${result.status}): ${item.variant}`);
+      if (result.stderr) context.print(result.stderr);
+      for (const later of batch.slice(index + 1)) context.print(`not applied: ${later.variant} — an earlier apply failed`);
+      outcome.code = 1;
+      break;
+    }
+    outcome.successes += 1;
+    refreshWrites(record, item.writes, context.io);
+  }
+  if (outcome.successes > 0) {
+    const afterPaths = [...collectPaths(context.facts, context.io), ...record.keys()];
+    context.restart ||= afterPaths.some((path) => isConfiguration(path, context.facts.root)
+      && refreshState(path, context.io) !== (before.get(path) ?? 'absent'));
+  }
+  return outcome;
+};
+
+const selectRoot = async (context) => {
+  const { candidates } = findProject({ cwd: context.cwd, lstat: context.io.lstat });
+  if (candidates.length === 0) {
+    context.print("no agent-workflow project here — the project items apply when init runs from that project's folder");
+    return { root: null };
+  }
+  if (candidates.length === 1) return candidates[0];
+  candidates.forEach(({ root }, index) => context.print(`  ${index + 1}. ${root}`));
+  const answer = await context.terminal.ask(`which project? 1-${candidates.length}, Enter skips: `);
+  return candidates.find((_, index) => String(index + 1) === answer) ?? null;
+};
+
+const gateStamp = (candidate, context) => {
+  if (candidate.root === null) return null;
+  const stamp = (() => {
+    try {
+      return String(context.io.readFile(join(candidate.root, 'docs/ai/.workflow-version'), 'utf8')).trim();
+    } catch {
+      return null;
+    }
+  })();
+  if (candidate.shape === 'stamped' && stamp === EXPECTED_WORKFLOW_VERSION) return candidate.root;
+  if (compareSemver(stamp, EXPECTED_WORKFLOW_VERSION) === 1) {
+    context.print(`this project's stamp ${stamp} is ahead of this kit's lineage ${EXPECTED_WORKFLOW_VERSION} — update the kit, then init again`);
+  } else {
+    context.print('run /agent-workflow-kit upgrade, then init again');
+  }
+  return null;
+};
+
+export const runInitProject = async (deps) => {
+  const { terminal } = deps;
+  if (terminal.isTTY !== true) {
+    terminal.print("project step skipped: no terminal — run init in a console from the project's folder");
+    return { code: 0 };
+  }
+  const io = { ...DEFAULT_IO, ...deps.io };
+  const print = (line) => terminal.print(line);
+  if (!preflightInit({ ...deps, root: null, io }).ok) {
+    print(INSIDE_LINE);
+    return { code: 0 };
+  }
+  const spawnEnv = { ...deps.env };
+  delete spawnEnv.GIT_DIR;
+  delete spawnEnv.GIT_WORK_TREE;
+  const context = { ...deps, io, print, spawnEnv, masks: new Set(), keySet: false, restart: false };
+  const candidate = await selectRoot(context);
+  if (candidate === null) return { code: 0 };
+  if (!preflightInit({ ...deps, root: candidate.root, io }).ok) {
+    print(INSIDE_LINE);
+    return { code: 0 };
+  }
+  const root = gateStamp(candidate, context);
+  // The hooks dir git itself reports (a linked worktree's or core.hooksPath), as the advisor reads it.
+  const hooksDir = root === null ? null : (deps.gitHooksPath ?? resolveGitHooksPath)(root) ?? join(root, '.git/hooks');
+  context.facts = { toolsDir: deps.toolsDir, root, env: deps.env, home: deps.home, platform: deps.platform, tuple: undefined, hooksDir };
+  context.recommend ??= (root, facts) => buildRecommendations({ cwd: root ?? deps.cwd,
+    deps: { ...io, env: deps.env, getenv: deps.env, home: deps.home, platform: deps.platform,
+      jevHost: { ...hostFacts(), home: deps.home, platform: deps.platform }, ...facts } });
+  const queue = await getQueue(context);
+  const maskPaths = [...collectPaths(context.facts, io), ...queue.flatMap(({ variant }) => writesOf(variant, context.facts) ?? [])];
+  context.masks = findMasks(maskPaths, { ...context.facts, cwd: deps.cwd }, io, print);
+  const state = { queue: queue.filter(({ variant }) => !isMasked(variant, context)) };
+  for (const item of state.queue.filter(({ variant }) => consoleArgv(variant, context.facts)?.preview === null)) {
+    print(item.what);
+    print(`it writes: ${writesOf(item.variant, context.facts).join(', ')}`);
+    printNote(context, item.key);
+    if (!isYes(await terminal.ask('y runs its command on this terminal, Enter skips: '))) continue;
+    const result = await launch(context, consoleArgv(item.variant, context.facts).apply, 'inherit');
+    if (result.valid && result.status === 0) {
+      context.keySet = true;
+      state.queue = await getQueue(context);
+    }
+  }
+  state.queue = state.queue.filter(({ variant }) => consoleArgv(variant, context.facts)?.preview !== null);
+  printNotPending(context);
+  const first = await runPass(context, state.queue);
+  const outcome = { code: first.code };
+  if (first.code === 0 && first.successes > 0) {
+    const next = (await getQueue(context)).filter(({ variant }) => !first.variants.includes(variant) && consoleArgv(variant, context.facts)?.preview);
+    outcome.code = (await runPass(context, next)).code;
+  }
+  if (context.restart) print(RESTART_LINE);
+  return outcome;
+};
+
+export const main = async (argv = process.argv.slice(2), deps = {}) => {
+  if (argv.length > 0) {
+    (deps.errlog ?? console.error)('Usage: node init-project.mjs');
+    return 2;
+  }
+  const readline = deps.terminal ? null : createInterface({ input: process.stdin, output: process.stdout });
+  const terminal = deps.terminal ?? { isTTY: process.stdin.isTTY === true && process.stdout.isTTY === true,
+    ask: (prompt) => readline.question(prompt), print: (line) => console.log(line) };
+  try {
+    const result = await runInitProject({ cwd: process.cwd(), env: process.env, home: homedir(), platform: process.platform,
+      toolsDir: dirname(fileURLToPath(import.meta.url)), terminal,
+      spawn: (args, options) => spawnSync(process.execPath, args.slice(1), { ...options, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER }),
+      ...deps });
+    return result.code;
+  } finally {
+    readline?.close();
+  }
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = await main();

package/tools/mcp.mjs

@@ -16,7 +16,7 @@
 //     would be a client error on every startup;
 //   • merge-don't-clobber — foreign servers, foreign settings keys and existing allow rules are
 //     preserved; re-apply adds nothing twice; the file's EOL is kept;
-//   • a same-name entry that STRUCTURALLY DIFFERS is REFUSED unwritten (key order is ignored, so a
+//   • without `--replace`, a same-name entry that STRUCTURALLY DIFFERS is REFUSED unwritten (key order is ignored, so a
 //     re-serialized identical entry is the SAME registration) — silently changing what an MCP server
 //     launches is exactly what consent must not slide past; the recovery is named;
 //   • the preflight is READ-ONLY: an absent `.claude/` is a NAMED state, and the dir is created on
@@ -32,11 +32,16 @@
 // Exit codes: 0 done / dry-run (incl. the hand-apply masked state); 1 precondition STOP; 2 usage.
 // Dependency-free beyond the kit's own exports, Node >= 22. No side effects on import.
 
-import { lstatSync } from 'node:fs';
+import {
+  lstatSync, openSync, closeSync, fstatSync, writeFileSync, ftruncateSync, fsyncSync,
+  renameSync, constants,
+} from 'node:fs';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assertCreatableDirSafe, writeContainedFileAtomic } from './atomic-write.mjs';
 import { isDirectRun } from './direct-run.mjs';
+import { describeNonRegular } from './fs-read-nofollow.mjs';
+import { assertContainedRealPath } from './fs-safe.mjs';
 import {
   CLAUDE_DIR_REL,
   ENABLED_KEY,
@@ -67,16 +72,16 @@ const LF = '\n';
 const JSON_INDENT = 2;
 
 export const MCP_TOOL = fileURLToPath(import.meta.url);
-export const applyMcpCommand = (root) => `node ${q(MCP_TOOL)} --apply --cwd ${q(root)}`;
+export const applyMcpCommand = (root, replace = false) => `node ${q(MCP_TOOL)}${replace ? ' --replace' : ''} --apply --cwd ${q(root)}`;
 
-const USAGE = `usage: mcp [--dry-run | --apply] [--cwd <dir>] [--help]
+const USAGE = `usage: mcp [--dry-run | --apply] [--replace] [--cwd <dir>] [--help]
 
 Registers this kit's stdio MCP server in ONE project: the "${SERVER_NAME}" entry in
 ${MCP_JSON_REL}, and "${ENABLED_KEY}" + the two tool allow rules in ${SETTINGS_REL}.
 Default is --dry-run (a preview that prints the exact entry and writes nothing).
---apply writes: ${MCP_JSON_REL} first, then ${SETTINGS_REL}; merge-don't-clobber, EOL kept.
+--apply writes: ${MCP_JSON_REL} first, then ${SETTINGS_REL}; merge-don't-clobber, EOL kept. An existing target is written in place; --replace replaces a differing entry only with --apply.
 
-An existing "${SERVER_NAME}" entry that STRUCTURALLY DIFFERS is refused unwritten (key
+Without --replace, an existing "${SERVER_NAME}" entry that STRUCTURALLY DIFFERS is refused unwritten (key
 order is ignored). Where ${MCP_JSON_REL} is a device node, FIFO or socket — an OS sandbox
 mask is the usual cause — the entry to merge is printed and nothing is written.
 Never writes settings.local.json; never commits.`;
@@ -122,7 +127,7 @@ const assertTargetUsable = (target, { maskedAllowed = false } = {}) => {
   }
 };
 
-export const preflightMcp = ({ cwd }, deps = {}) => {
+export const preflightMcp = ({ cwd, replace = false }, deps = {}) => {
   const root = resolve(cwd ?? deps.cwd ?? process.cwd());
   // The ROOT is judged BEFORE the registration is read, not merely before the first write: reading
   // first would follow the very link this refuses, which is exactly what the shipped claim denies.
@@ -152,7 +157,7 @@ export const preflightMcp = ({ cwd }, deps = {}) => {
   }
   assertTargetUsable(registration.mcpJson, { maskedAllowed: true });
   assertTargetUsable(registration.settings);
-  if (registration.mcpJson.differs) {
+  if (registration.mcpJson.differs && !replace) {
     throw makeMcpError(
       MCP_DIFFERS,
       `${MCP_JSON_REL} already carries an "${SERVER_NAME}" server entry that STRUCTURALLY DIFFERS from this kit copy's registration — refusing to change what it launches; review that entry and remove or rename it, then re-run`,
@@ -173,8 +178,53 @@ export const planMcp = (registration) => ({
 
 // ── the writer ─────────────────────────────────────────────────────────────────────────
 
-export const writeMcp = ({ cwd, dryRun = true } = {}, deps = {}) => {
-  const preflight = preflightMcp({ cwd: cwd ?? deps.cwd ?? process.cwd() }, deps);
+const writeTarget = (root, target, body, deps, stop) => {
+  const leaf = lstatNoFollow(target.abs, deps.lstat);
+  if (target.state === STATE.ABSENT) {
+    const assertAbsent = (dst) => {
+      if (lstatNoFollow(dst, deps.lstat) !== null) {
+        throw Object.assign(new Error('EEXIST'), { code: 'EEXIST' });
+      }
+    };
+    assertAbsent(target.abs);
+    const rename = (tmp, dst) => {
+      assertAbsent(dst);
+      (deps.rename ?? renameSync)(tmp, dst);
+    };
+    return writeContainedFileAtomic(root, target.abs, body, { ...deps, rename }, { stop, label: target.rel });
+  }
+  if (leaf?.isSymbolicLink()) {
+    throw stop(`${target.rel} is a symlink — refusing to replace it (a write would clobber the link target)`);
+  }
+  try {
+    assertContainedRealPath(root, target.abs, deps);
+  } catch (err) {
+    throw stop(String(err?.message ?? err).replace(/^\[agent-workflow-kit\] /, ''));
+  }
+  const flags = deps.constants ?? constants;
+  if (!flags.O_NOFOLLOW || !flags.O_NONBLOCK) {
+    throw stop('this platform exposes no usable O_NOFOLLOW|O_NONBLOCK open flags — refusing to open (fail closed)');
+  }
+  const fd = (deps.open ?? openSync)(target.abs, flags.O_WRONLY | flags.O_NOFOLLOW | flags.O_NONBLOCK);
+  try {
+    const stat = (deps.fstat ?? fstatSync)(fd);
+    if (!stat.isFile()) {
+      throw stop(`${target.rel} is a ${describeNonRegular(stat)} — refusing to write through it`);
+    }
+    if (leaf === null || stat.dev !== leaf.dev || stat.ino !== leaf.ino) {
+      throw stop('the leaf changed identity between lstat and open (fail closed)');
+    }
+    const bytes = Buffer.from(body, 'utf8');
+    (deps.writeFile ?? writeFileSync)(fd, bytes);
+    (deps.ftruncate ?? ftruncateSync)(fd, bytes.length);
+    (deps.fsync ?? fsyncSync)(fd);
+  } finally {
+    (deps.close ?? closeSync)(fd);
+  }
+};
+
+export const writeMcp = ({ cwd, dryRun = true, replace = false } = {}, deps = {}) => {
+  const preflight = preflightMcp({ cwd: cwd ?? deps.cwd ?? process.cwd(), replace }, deps);
   const base = { ...preflight, dryRun, wrote: false };
   if (preflight.masked) return { ...base, fragments: renderFragments(preflight.registration) };
   if (dryRun) return base;
@@ -182,7 +232,7 @@ export const writeMcp = ({ cwd, dryRun = true } = {}, deps = {}) => {
   const { root, registration, plan } = preflight;
   const stop = (message) => makeMcpError(MCP_SYMLINK, message);
   if (plan.writeMcpJson) {
-    writeContainedFileAtomic(root, registration.mcpJson.abs, plan.mcpBody, deps, { stop, label: MCP_JSON_REL });
+    writeTarget(root, registration.mcpJson, plan.mcpBody, deps, stop);
   }
   if (plan.writeSettings) {
     // A settings failure AFTER the entry landed leaves a STANDING registration on disk that never
@@ -194,12 +244,12 @@ export const writeMcp = ({ cwd, dryRun = true } = {}, deps = {}) => {
       // The ONE write the preflight deliberately does not do: creating `.claude/` is a mutation, so
       // it belongs on the apply lane only — a preview that made a directory would not be a preview.
       assertCreatableDirSafe(join(root, CLAUDE_DIR_REL), deps, { stop, noun: SETTINGS_REL });
-      writeContainedFileAtomic(root, registration.settings.abs, plan.settingsBody, deps, { stop, label: SETTINGS_REL });
+      writeTarget(root, registration.settings, plan.settingsBody, deps, stop);
     } catch (err) {
       // Reaching here always leaves a STANDING registration on disk — either this run wrote the
       // entry (`writeMcpJson`) or the preflight found it already current (`matches`), and those two
       // are exhaustive, so the note is unconditional rather than guarded by a branch nothing can
-      // take. A differing entry never reaches the writer at all; it STOPs in the preflight.
+      // take. Without --replace, a differing entry STOPs in the preflight.
       throw Object.assign(err, { message: `${err.message}\n${HIDDEN_MODE_LINE}` });
     }
   }
@@ -221,7 +271,9 @@ const indented = (text) => text.trimEnd().split(LF).map((line) => `    ${line}`)
 
 const mcpJsonLine = (result) => {
   if (!result.plan.writeMcpJson) return `  - ${MCP_JSON_REL}: already current`;
-  const verb = result.dryRun ? 'would add' : 'added';
+  const verb = result.registration.mcpJson.differs
+    ? (result.dryRun ? 'would replace' : 'replaced')
+    : (result.dryRun ? 'would add' : 'added');
   return `  - ${MCP_JSON_REL}: ${verb} the "${SERVER_NAME}" stdio entry`;
 };
 
@@ -264,24 +316,29 @@ export const formatResult = (result) => {
       : 'agent-workflow MCP registration — APPLY',
     mcpJsonLine(result),
     settingsLine(result),
+    ...(result.registration.mcpJson.differs ? [
+      '  the entry standing in .mcp.json now:',
+      indented(JSON.stringify(result.registration.mcpJson.existing, null, JSON_INDENT)),
+    ] : []),
     '  the entry this registration declares (re-serialized here; the same structured value goes into the file):',
     indented(JSON.stringify(result.registration.entry, null, JSON_INDENT)),
     POSTURE_LINE,
     HIDDEN_MODE_LINE,
   ];
-  if (result.dryRun) lines.push(`  to apply: ${applyMcpCommand(result.root)}`);
+  if (result.dryRun) lines.push(`  to apply: ${applyMcpCommand(result.root, result.registration.mcpJson.differs)}`);
   return lines.join(LF);
 };
 
 // ── CLI ────────────────────────────────────────────────────────────────────────────────
 
 export const parseArgs = (argv) => {
-  const opts = { dryRunFlag: false, apply: false, cwd: undefined, help: false };
+  const opts = { dryRunFlag: false, apply: false, replace: false, cwd: undefined, help: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') opts.help = true;
     else if (arg === '--dry-run') opts.dryRunFlag = true;
     else if (arg === '--apply') opts.apply = true;
+    else if (arg === '--replace') opts.replace = true;
     else if (arg === '--cwd') {
       i += 1;
       // An EMPTY (or whitespace) value passes both guards above, and `resolve('')` silently means the
@@ -296,7 +353,7 @@ export const parseArgs = (argv) => {
     }
   }
   if (opts.dryRunFlag && opts.apply) throw fail(EXIT_USAGE, '--dry-run and --apply cannot be used together');
-  return { help: opts.help, dryRun: !opts.apply, cwd: opts.cwd };
+  return { help: opts.help, dryRun: !opts.apply, replace: opts.replace, cwd: opts.cwd };
 };
 
 export const main = (argv = process.argv.slice(2), deps = {}) => {
@@ -308,10 +365,11 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       log(USAGE);
       return EXIT_OK;
     }
-    log(formatResult(writeMcp({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), dryRun: args.dryRun }, deps)));
+    log(formatResult(writeMcp({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), dryRun: args.dryRun, replace: args.replace }, deps)));
     return EXIT_OK;
   } catch (err) {
-    errlog(err?.message ?? String(err));
+    const message = err?.message ?? String(err);
+    errlog(err?.code && err.name !== 'McpError' && !message.includes(err.code) ? `${err.code}: ${message}` : message);
     if (err?.exitCode === EXIT_USAGE) errlog(USAGE);
     return err?.exitCode ?? EXIT_PRECONDITION;
   }