@topolo/cli 0.13.27 → 0.13.28

package/dist/index.js

@@ -308,7 +308,7 @@ import { Command, Help } from "commander";
 import { createInterface } from "readline/promises";
 import { stdin as input } from "process";
 
-// node_modules/@topolo/sdk/dist/index.js
+// node_modules/.pnpm/@topolo+sdk@0.24.1/node_modules/@topolo/sdk/dist/index.js
 function record(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -328,8 +328,8 @@ function validTopoloActionAccessPolicy(value) {
 }
 var TopoloSdkError = class extends Error {
   code;
-  constructor(code, message3) {
-    super(message3);
+  constructor(code, message2) {
+    super(message2);
     this.name = "TopoloSdkError";
     this.code = code;
   }
@@ -450,8 +450,8 @@ var TopoloAuthError = class extends TopoloSdkError {
   requestId;
   retryAfter;
   details;
-  constructor(message3, code = "auth_error", options = {}) {
-    super(canonicalTopoloServiceErrorCode(code) ?? "auth_error", message3);
+  constructor(message2, code = "auth_error", options = {}) {
+    super(canonicalTopoloServiceErrorCode(code) ?? "auth_error", message2);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
@@ -473,10 +473,10 @@ var TopoloPermissionError = class extends TopoloSdkError {
   requestId;
   retryAfter;
   details;
-  constructor(message3, required, options = {}) {
+  constructor(message2, required, options = {}) {
     super(
       canonicalTopoloServiceErrorCode(options.code) ?? serviceErrorCode(options.body, "permission_denied"),
-      message3
+      message2
     );
     this.name = "TopoloPermissionError";
     this.required = canonicalTopoloRequired(required);
@@ -517,8 +517,8 @@ function extractTopoloServiceErrorMessage(body) {
   candidates.push(record5.message, record5.error_description);
   if (typeof nested === "string" && !canonicalTopoloServiceErrorCode(nested)) candidates.push(nested);
   for (const candidate of candidates) {
-    const message3 = sanitizeTopoloServiceMessage(candidate);
-    if (message3) return message3;
+    const message2 = sanitizeTopoloServiceMessage(candidate);
+    if (message2) return message2;
   }
   return void 0;
 }
@@ -592,8 +592,8 @@ function validationIssueDetails(issues) {
   }
   return paths.length ? { paths, issues } : { issues };
 }
-function issue(path, message3) {
-  const text4 = sanitizeTopoloServiceMessage(message3);
+function issue(path, message2) {
+  const text4 = sanitizeTopoloServiceMessage(message2);
   if (!path && !text4) return null;
   return { ...path ? { path } : {}, ...text4 ? { message: text4 } : {} };
 }
@@ -613,8 +613,8 @@ function canonicalTopoloValidationIssues(values) {
 function flattenedValidationIssues(formErrors, fieldErrors) {
   const issues = [];
   if (Array.isArray(formErrors)) {
-    for (const message3 of formErrors) {
-      const projected = issue(void 0, message3);
+    for (const message2 of formErrors) {
+      const projected = issue(void 0, message2);
       if (projected) issues.push(projected);
     }
   }
@@ -623,8 +623,8 @@ function flattenedValidationIssues(formErrors, fieldErrors) {
       const path = canonicalTopoloValidationPath(key);
       if (!path) continue;
       const list = Array.isArray(messages) && messages.length ? messages : [void 0];
-      for (const message3 of list) {
-        const projected = issue(path, message3);
+      for (const message2 of list) {
+        const projected = issue(path, message2);
         if (projected) issues.push(projected);
       }
     }
@@ -704,8 +704,8 @@ function topoloErrorHint(error) {
   return void 0;
 }
 var TopoloConfirmationRequiredError = class extends TopoloSdkError {
-  constructor(message3) {
-    super("confirmation_required", message3);
+  constructor(message2) {
+    super("confirmation_required", message2);
     this.name = "TopoloConfirmationRequiredError";
   }
 };
@@ -717,8 +717,8 @@ var TopoloHttpError = class extends TopoloSdkError {
   requestId;
   retryAfter;
   details;
-  constructor(service, path, status, body, message3, options = {}) {
-    super(serviceErrorCode(body, "http_error"), message3 ?? `HTTP ${status} from ${service}${path}`);
+  constructor(service, path, status, body, message2, options = {}) {
+    super(serviceErrorCode(body, "http_error"), message2 ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
@@ -740,8 +740,8 @@ function topoloRetryAfterSeconds(value, now = Date.now()) {
 var TopoloRateLimitError = class extends TopoloHttpError {
   retryable = true;
   retryAfterSeconds;
-  constructor(service, path, body, message3, options = {}) {
-    super(service, path, 429, body, message3, options);
+  constructor(service, path, body, message2, options = {}) {
+    super(service, path, 429, body, message2, options);
     this.name = "TopoloRateLimitError";
     if (this.code === "http_error") this.code = "rate_limited";
     this.retryAfterSeconds = topoloRetryAfterSeconds(this.retryAfter);
@@ -749,8 +749,8 @@ var TopoloRateLimitError = class extends TopoloHttpError {
 };
 var TopoloReauthRequiredError = class extends TopoloAuthError {
   reauthorization;
-  constructor(message3, reauthorization, options = {}) {
-    super(message3, "reauth_required", { status: 401, service: "auth", path: "/api/developer-oauth/token", ...options });
+  constructor(message2, reauthorization, options = {}) {
+    super(message2, "reauth_required", { status: 401, service: "auth", path: "/api/developer-oauth/token", ...options });
     this.name = "TopoloReauthRequiredError";
     this.reauthorization = Object.freeze({ ...reauthorization });
   }
@@ -1718,8 +1718,8 @@ var ASSURANCE_LEVELS = /* @__PURE__ */ new Set(["authenticated", "workload_ident
 var HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
 var ActorEnvelopeValidationError = class extends Error {
   path;
-  constructor(path, message3) {
-    super(`${path}: ${message3}`);
+  constructor(path, message2) {
+    super(`${path}: ${message2}`);
     this.name = "ActorEnvelopeValidationError";
     this.path = path;
   }
@@ -1916,8 +1916,8 @@ function textArray(value, path) {
 function optionalTextFields(value, path, keys) {
   return Object.fromEntries(keys.flatMap((key) => value[key] === void 0 ? [] : [[key, text2(value[key], `${path}.${key}`)]]));
 }
-function fail(path, message3) {
-  throw new ActorEnvelopeValidationError(path, message3);
+function fail(path, message2) {
+  throw new ActorEnvelopeValidationError(path, message2);
 }
 function parseTopoloActionUploadContract(value) {
   if (!isRecord3(value) || value.profile !== "inline-base64" && value.profile !== "url-session") {
@@ -2372,7 +2372,7 @@ var TopoloClient = class _TopoloClient {
     }
     if (!res.ok) {
       const durationMs = Date.now() - startedAt;
-      const message3 = describeError(parsed, `HTTP ${res.status}`);
+      const message2 = describeError(parsed, `HTTP ${res.status}`);
       const publicCode = extractTopoloServiceErrorCode(parsed) ?? "http_error";
       this.emit({
         phase: "error",
@@ -2412,7 +2412,7 @@ var TopoloClient = class _TopoloClient {
           resolvedService.serviceKey,
           opts.path,
           parsed,
-          message3,
+          message2,
           errorContext
         );
       }
@@ -2421,7 +2421,7 @@ var TopoloClient = class _TopoloClient {
         opts.path,
         res.status,
         parsed,
-        message3,
+        message2,
         errorContext
       );
     }
@@ -4409,7 +4409,7 @@ async function pollUntilApproved(params) {
 // src/commands/auth-lock.ts
 import { createHash as createHash3 } from "crypto";
 
-// node_modules/@topolo/sdk/dist/node/credential-store.js
+// node_modules/.pnpm/@topolo+sdk@0.24.1/node_modules/@topolo/sdk/dist/node/credential-store.js
 import { mkdir as mkdir2, readFile as readFile2, chmod as chmod2, lstat, readdir as readdir2 } from "fs/promises";
 import { existsSync as existsSync2, mkdirSync, lstatSync, readdirSync, readFileSync as readFileSync2, openSync, writeFileSync, fsyncSync, closeSync, renameSync, unlinkSync, rmdirSync, linkSync } from "fs";
 import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
@@ -4426,8 +4426,8 @@ import { homedir as homedir3, platform as hostPlatform } from "os";
 import { dirname as dirname3, join } from "path";
 var TopoloSdkError2 = class extends Error {
   code;
-  constructor(code, message3) {
-    super(message3);
+  constructor(code, message2) {
+    super(message2);
     this.name = "TopoloSdkError";
     this.code = code;
   }
@@ -4548,8 +4548,8 @@ var TopoloAuthError2 = class extends TopoloSdkError2 {
   requestId;
   retryAfter;
   details;
-  constructor(message3, code = "auth_error", options = {}) {
-    super(canonicalTopoloServiceErrorCode2(code) ?? "auth_error", message3);
+  constructor(message2, code = "auth_error", options = {}) {
+    super(canonicalTopoloServiceErrorCode2(code) ?? "auth_error", message2);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
@@ -4647,8 +4647,8 @@ function validationIssueDetails2(issues) {
   }
   return paths.length ? { paths, issues } : { issues };
 }
-function issue2(path, message3) {
-  const text3 = sanitizeTopoloServiceMessage2(message3);
+function issue2(path, message2) {
+  const text3 = sanitizeTopoloServiceMessage2(message2);
   if (!path && !text3) return null;
   return { ...path ? { path } : {}, ...text3 ? { message: text3 } : {} };
 }
@@ -4668,8 +4668,8 @@ function canonicalTopoloValidationIssues2(values) {
 function flattenedValidationIssues2(formErrors, fieldErrors) {
   const issues = [];
   if (Array.isArray(formErrors)) {
-    for (const message3 of formErrors) {
-      const projected = issue2(void 0, message3);
+    for (const message2 of formErrors) {
+      const projected = issue2(void 0, message2);
       if (projected) issues.push(projected);
     }
   }
@@ -4678,8 +4678,8 @@ function flattenedValidationIssues2(formErrors, fieldErrors) {
       const path = canonicalTopoloValidationPath2(key);
       if (!path) continue;
       const list = Array.isArray(messages) && messages.length ? messages : [void 0];
-      for (const message3 of list) {
-        const projected = issue2(path, message3);
+      for (const message2 of list) {
+        const projected = issue2(path, message2);
         if (projected) issues.push(projected);
       }
     }
@@ -4713,8 +4713,8 @@ var TopoloHttpError2 = class extends TopoloSdkError2 {
   requestId;
   retryAfter;
   details;
-  constructor(service, path, status, body, message3, options = {}) {
-    super(serviceErrorCode2(body, "http_error"), message3 ?? `HTTP ${status} from ${service}${path}`);
+  constructor(service, path, status, body, message2, options = {}) {
+    super(serviceErrorCode2(body, "http_error"), message2 ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
@@ -4736,8 +4736,8 @@ function topoloRetryAfterSeconds2(value, now = Date.now()) {
 var TopoloRateLimitError2 = class extends TopoloHttpError2 {
   retryable = true;
   retryAfterSeconds;
-  constructor(service, path, body, message3, options = {}) {
-    super(service, path, 429, body, message3, options);
+  constructor(service, path, body, message2, options = {}) {
+    super(service, path, 429, body, message2, options);
     this.name = "TopoloRateLimitError";
     if (this.code === "http_error") this.code = "rate_limited";
     this.retryAfterSeconds = topoloRetryAfterSeconds2(this.retryAfter);
@@ -4745,8 +4745,8 @@ var TopoloRateLimitError2 = class extends TopoloHttpError2 {
 };
 var TopoloReauthRequiredError2 = class extends TopoloAuthError2 {
   reauthorization;
-  constructor(message3, reauthorization, options = {}) {
-    super(message3, "reauth_required", { status: 401, service: "auth", path: "/api/developer-oauth/token", ...options });
+  constructor(message2, reauthorization, options = {}) {
+    super(message2, "reauth_required", { status: 401, service: "auth", path: "/api/developer-oauth/token", ...options });
     this.name = "TopoloReauthRequiredError";
     this.reauthorization = Object.freeze({ ...reauthorization });
   }
@@ -6287,12 +6287,12 @@ function renewalFailure(error) {
   if (error instanceof TopoloReauthRequiredError2) return error;
   if (error instanceof TopoloSdkError2 && error.code === "config_unreadable") return error;
   if ((error instanceof TopoloAuthError2 || error instanceof TopoloHttpError2) && error.status === 429) {
-    const message3 = "Topolo sign-in renewal is temporarily rate limited by Auth. Retry after the Retry-After interval; the saved sign-in has been retained.";
+    const message2 = "Topolo sign-in renewal is temporarily rate limited by Auth. Retry after the Retry-After interval; the saved sign-in has been retained.";
     return new TopoloRateLimitError2(
       "auth",
       path,
-      { code: "rate_limited", retryable: true, message: message3 },
-      message3,
+      { code: "rate_limited", retryable: true, message: message2 },
+      message2,
       { requestId: error.requestId, retryAfter: error.retryAfter }
     );
   }
@@ -8065,8 +8065,8 @@ var API_KEYS_LIST_ACTION = "app_topolo_auth.api_keys.list";
 var CUSTODY_ENVIRONMENT_NAMES = ["production", "staging", "development", "local"];
 var CustodyError = class extends Error {
   code;
-  constructor(code, message3) {
-    super(message3);
+  constructor(code, message2) {
+    super(message2);
     this.name = "CustodyError";
     this.code = code;
   }
@@ -8886,7 +8886,7 @@ import { spawnSync as spawnSync5 } from "child_process";
 import { existsSync as existsSync6 } from "fs";
 import { readFile as readFile9, rm as rm3 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { dirname as dirname7, join as join11, resolve as resolve4 } from "path";
+import { dirname as dirname7, join as join12, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { createRequire } from "module";
 
@@ -8901,7 +8901,231 @@ import { spawnSync as spawnSync3 } from "child_process";
 import { existsSync as existsSync4 } from "fs";
 import { readFile as readFile4 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { isAbsolute as isAbsolute2, join as join7, resolve as resolve3 } from "path";
+import { isAbsolute as isAbsolute2, join as join8, resolve as resolve3 } from "path";
+
+// src/commands/host-json.ts
+import { createHash as createHash5 } from "crypto";
+import { chmod as chmod4, lstat as lstat3, mkdir as mkdir4, open as open2, readdir as readdir4, unlink } from "fs/promises";
+import { basename as basename3, join as join7 } from "path";
+import {
+  applyEdits,
+  modify,
+  parse as parseJsonc,
+  printParseErrorCode,
+  visit
+} from "jsonc-parser";
+var BOM = "\uFEFF";
+var RESERVED_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var JSONC_OPTIONS = { allowTrailingComma: true, disallowComments: false, allowEmptyContent: true };
+var HOST_JSON_BACKUP_RETENTION = 3;
+function printable(text3) {
+  return text3.replace(
+    /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g,
+    (character) => "\\u" + character.charCodeAt(0).toString(16).padStart(4, "0")
+  );
+}
+function printableLines(text3) {
+  return text3.split("\n").map((line) => line.split("	").map(printable).join("	")).join("\n");
+}
+function quotedKey(key) {
+  return '"' + printable(key.replace(/["\\]/g, "\\$&")) + '"';
+}
+function malformedHostConfigError(verb, target, reason) {
+  return new Error(
+    "Cannot " + verb + " malformed " + target.label + " configuration at " + printable(target.path) + ": " + reason + " Topolo did not change this file. Fix it in an editor, or move it aside (for example rename it to " + printable(target.path) + ".bak) and run the command again."
+  );
+}
+function lineColumn(text3, offset) {
+  const before = text3.slice(0, offset).split("\n");
+  return "line " + before.length + ", column " + (before[before.length - 1].length + 1);
+}
+function objectOrThrow(value, verb, target) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    const found = value === null ? "null" : Array.isArray(value) ? "an array" : typeof value;
+    throw malformedHostConfigError(verb, target, "the top level must be a JSON object ({ ... }), but it is " + found + ".");
+  }
+  return value;
+}
+function assertSafeKeys(body, verb, target) {
+  const objects = [];
+  let problem;
+  visit(body, {
+    onObjectBegin: () => {
+      objects.push(/* @__PURE__ */ new Set());
+    },
+    onObjectEnd: () => {
+      objects.pop();
+    },
+    onObjectProperty: (property, offset) => {
+      if (problem) return;
+      const keys = objects[objects.length - 1];
+      if (RESERVED_KEYS.has(property)) {
+        problem = "it contains the reserved key " + quotedKey(property) + " at " + lineColumn(body, offset) + ". Remove or rename that key.";
+      } else if (keys.has(property)) {
+        problem = "it contains the duplicate key " + quotedKey(property) + " (again at " + lineColumn(body, offset) + "). Keep one " + quotedKey(property) + " entry, merging what you need from the other, and remove the duplicate.";
+      }
+      keys.add(property);
+    }
+  }, JSONC_OPTIONS);
+  if (problem) throw malformedHostConfigError(verb, target, problem);
+}
+function parseHostJson(text3, target, verb = "update") {
+  const bom = text3?.startsWith(BOM) ? BOM : "";
+  const body = (text3 ?? "").slice(bom.length);
+  if (!body.trim()) return { kind: "empty", value: {}, bom, body };
+  let value;
+  let kind = "strict";
+  try {
+    value = JSON.parse(body);
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    const errors = [];
+    value = parseJsonc(body, errors, JSONC_OPTIONS);
+    if (errors.length) {
+      const first = errors[0];
+      throw malformedHostConfigError(
+        verb,
+        target,
+        "invalid JSON at " + lineColumn(body, first.offset) + " (" + printParseErrorCode(first.error) + ")."
+      );
+    }
+    if (target.syntax !== "jsonc") {
+      throw malformedHostConfigError(
+        verb,
+        target,
+        "it is not strict JSON: it contains comments or trailing commas, which this file must not have."
+      );
+    }
+    kind = value === void 0 ? "empty" : "jsonc";
+  }
+  assertSafeKeys(body, verb, target);
+  if (kind === "empty") return { kind, value: {}, bom, body };
+  return { kind, value: objectOrThrow(value, verb, target), bom, body };
+}
+function hostServers(document, rootKey, target, verb = "update") {
+  const servers = document.value[rootKey];
+  if (servers === void 0) return void 0;
+  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+    throw malformedHostConfigError(verb, target, 'the "' + rootKey + '" entry must be a JSON object of MCP servers.');
+  }
+  return servers;
+}
+function editsInPlace(document, target) {
+  return target.syntax === "jsonc" && document.body.trim() !== "";
+}
+function stableJson(value) {
+  return JSON.stringify(value, (_key, item) => item && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item);
+}
+function editHostServer(document, rootKey, name, entry, target) {
+  const servers = hostServers(document, rootKey, target) ?? {};
+  const nextServers = { ...servers };
+  if (entry === void 0) delete nextServers[name];
+  else nextServers[name] = entry;
+  const serialized = JSON.stringify({ ...document.value, [rootKey]: nextServers }, null, 2) + "\n";
+  let text3;
+  if (!editsInPlace(document, target)) {
+    text3 = serialized;
+  } else if (document.kind === "empty") {
+    text3 = document.bom + document.body.trimEnd() + "\n" + serialized;
+  } else {
+    const edits = modify(document.body, [rootKey, name], entry, {
+      formattingOptions: { insertSpaces: true, tabSize: 2, eol: "\n" }
+    });
+    text3 = document.bom + applyEdits(document.body, edits);
+  }
+  const after = parseHostJson(text3, target);
+  const afterServers = Object(hostServers(after, rootKey, target));
+  const preserved = Object.keys(document.value).every((key) => key === rootKey || stableJson(after.value[key]) === stableJson(document.value[key])) && Object.keys(after.value).every((key) => key === rootKey || Object.hasOwn(document.value, key)) && Object.keys(servers).every((key) => key === name || stableJson(afterServers[key]) === stableJson(servers[key])) && Object.keys(afterServers).every((key) => key === name || Object.hasOwn(servers, key)) && (entry === void 0 ? !Object.hasOwn(afterServers, name) : stableJson(afterServers[name]) === stableJson(entry));
+  if (!preserved) {
+    throw malformedHostConfigError("update", target, "Topolo could not edit it without changing other entries.");
+  }
+  return text3;
+}
+function backupTimestamp(now = /* @__PURE__ */ new Date()) {
+  return now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+}
+function hostJsonBackupLocation(homeDir, host, configPath2) {
+  const hash = createHash5("sha256").update(configPath2).digest("hex").slice(0, 12);
+  return {
+    directory: join7(homeDir, ".topolo", "backups", host),
+    prefix: basename3(configPath2) + "." + hash + ".backup-"
+  };
+}
+var HOST_JSON_BACKUP_MAX_SEQUENCE = 999999999;
+var HOST_JSON_BACKUP_MIN_AGE_MS = 3e4;
+function backupSequence(name, prefix) {
+  const match = name.startsWith(prefix) ? /^(\d{6,9})-\d{8}T\d{6}Z$/.exec(name.slice(prefix.length)) : null;
+  return match ? Number(match[1]) : void 0;
+}
+function privateFolderError() {
+  return Object.assign(new Error("not a private directory"), { code: "ENOTPRIVATE" });
+}
+async function privateBackupFolder(homeDir, directory) {
+  const levels = [
+    [join7(homeDir, ".topolo"), 18],
+    [join7(homeDir, ".topolo", "backups"), 63],
+    [directory, 63]
+  ];
+  await mkdir4(homeDir, { recursive: true, mode: 448 });
+  for (const [level, loose] of levels) {
+    try {
+      await mkdir4(level, { mode: 448 });
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+    const folder = await lstat3(level);
+    if (!folder.isDirectory() || folder.uid !== (process.getuid?.() ?? folder.uid)) throw privateFolderError();
+    if (folder.mode & loose) await chmod4(level, folder.mode & 511 & ~loose);
+  }
+}
+async function removeOwnedBackup(file) {
+  try {
+    const info = await lstat3(file);
+    if (info.isFile() && Date.now() - info.mtimeMs >= HOST_JSON_BACKUP_MIN_AGE_MS) await unlink(file);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+async function writeHostJsonBackup(target, contents, homeDir, host, now = /* @__PURE__ */ new Date()) {
+  const { directory, prefix } = hostJsonBackupLocation(homeDir, host, target.path);
+  try {
+    await privateBackupFolder(homeDir, directory);
+    const sequences = () => readdir4(directory).then((names) => names.map((name) => ({ name, sequence: backupSequence(name, prefix) })).filter((item) => item.sequence !== void 0));
+    let sequence = Math.max(0, ...(await sequences()).map((item) => item.sequence)) + 1;
+    let written;
+    for (let attempt = 1; !written; attempt += 1) {
+      if (sequence > HOST_JSON_BACKUP_MAX_SEQUENCE) {
+        throw new Error("backup numbers are used up; remove the old backups in that folder");
+      }
+      const candidate = join7(directory, prefix + String(sequence).padStart(6, "0") + "-" + backupTimestamp(now));
+      try {
+        const handle = await open2(candidate, "wx", 384);
+        try {
+          await handle.writeFile(contents, "utf8");
+        } finally {
+          await handle.close();
+        }
+        written = candidate;
+      } catch (error) {
+        if (error.code !== "EEXIST" || attempt >= 100) throw error;
+        sequence += 1;
+      }
+    }
+    const older = (await sequences()).sort((left, right) => left.sequence - right.sequence);
+    older.splice(Math.max(0, older.length - HOST_JSON_BACKUP_RETENTION));
+    for (const item of older) {
+      if (join7(directory, item.name) !== written) await removeOwnedBackup(join7(directory, item.name));
+    }
+    return written;
+  } catch (error) {
+    const code = error.code;
+    throw new Error(
+      "Cannot back up " + target.label + " configuration at " + printable(target.path) + " before editing it: the private backup folder " + printable(directory) + " could not be used (" + (code ?? printable(error.message)) + "). Topolo did not change this file. Make sure that folder and its parent folders are directories you own (not links), or move the configuration aside, and run the command again."
+    );
+  }
+}
+
+// src/commands/agent-host.ts
 var SUPPORTED_AGENT_IDS = [
   "claude",
   "claude-desktop",
@@ -8950,7 +9174,7 @@ function resolveAgentHostTarget(options) {
   return Object.freeze({
     homeDir,
     ...options.projectDir ? { projectDir: resolve3(options.projectDir) } : {},
-    codexHome: codexHome ?? join7(homeDir, ".codex")
+    codexHome: codexHome ?? join8(homeDir, ".codex")
   });
 }
 var RESERVED_OPERATOR_REGISTRATION = ["topolo", "platform"].join("-");
@@ -8971,23 +9195,23 @@ function stableNodeCommand() {
 function agentSkillPath(agent, homeDir = homedir4(), projectDir, codexHome) {
   switch (agent) {
     case "claude":
-      return projectDir ? join7(projectDir, ".claude", "skills", "topolo", "SKILL.md") : join7(homeDir, ".claude", "skills", "topolo", "SKILL.md");
+      return projectDir ? join8(projectDir, ".claude", "skills", "topolo", "SKILL.md") : join8(homeDir, ".claude", "skills", "topolo", "SKILL.md");
     case "claude-desktop":
-      return join7(homeDir, ".claude", "skills", "topolo", "SKILL.md");
+      return join8(homeDir, ".claude", "skills", "topolo", "SKILL.md");
     case "codex":
-      return join7(codexHome ?? join7(homeDir, ".codex"), "skills", "topolo", "SKILL.md");
+      return join8(codexHome ?? join8(homeDir, ".codex"), "skills", "topolo", "SKILL.md");
     case "cursor":
-      return join7(projectDir ?? homeDir, ".cursor", "rules", "topolo.mdc");
+      return join8(projectDir ?? homeDir, ".cursor", "rules", "topolo.mdc");
     case "grok":
-      return join7(projectDir ?? homeDir, ".grok", "skills", "topolo", "SKILL.md");
+      return join8(projectDir ?? homeDir, ".grok", "skills", "topolo", "SKILL.md");
     case "gemini":
-      return join7(projectDir ?? homeDir, ".gemini", "skills", "topolo", "SKILL.md");
+      return join8(projectDir ?? homeDir, ".gemini", "skills", "topolo", "SKILL.md");
     case "copilot":
-      return projectDir ? join7(projectDir, ".github", "skills", "topolo", "SKILL.md") : join7(homeDir, ".copilot", "skills", "topolo", "SKILL.md");
+      return projectDir ? join8(projectDir, ".github", "skills", "topolo", "SKILL.md") : join8(homeDir, ".copilot", "skills", "topolo", "SKILL.md");
     case "windsurf":
-      return projectDir ? join7(projectDir, ".windsurf", "rules", "topolo.md") : void 0;
+      return projectDir ? join8(projectDir, ".windsurf", "rules", "topolo.md") : void 0;
     case "cline":
-      return join7(projectDir ?? homeDir, ".cline", "skills", "topolo", "SKILL.md");
+      return join8(projectDir ?? homeDir, ".cline", "skills", "topolo", "SKILL.md");
     case "goose":
     case "amazon-q":
       return void 0;
@@ -8996,7 +9220,7 @@ function agentSkillPath(agent, homeDir = homedir4(), projectDir, codexHome) {
 function agentConfigPaths(agent, homeDir = homedir4(), projectDir, codexHome) {
   switch (agent) {
     case "claude":
-      return [{ path: projectDir ? join7(projectDir, ".mcp.json") : join7(homeDir, ".claude.json"), format: "json", rootKey: "mcpServers" }];
+      return [{ path: projectDir ? join8(projectDir, ".mcp.json") : join8(homeDir, ".claude.json"), format: "json", rootKey: "mcpServers" }];
     case "claude-desktop":
       return [{
         path: claudeDesktopConfigPath(homeDir),
@@ -9004,56 +9228,56 @@ function agentConfigPaths(agent, homeDir = homedir4(), projectDir, codexHome) {
         rootKey: "mcpServers"
       }];
     case "codex":
-      return [{ path: join7(codexHome ?? join7(homeDir, ".codex"), "config.toml"), format: "toml" }];
+      return [{ path: join8(codexHome ?? join8(homeDir, ".codex"), "config.toml"), format: "toml" }];
     case "cursor":
       return [{
-        path: projectDir ? join7(projectDir, ".cursor", "mcp.json") : join7(homeDir, ".cursor", "mcp.json"),
+        path: projectDir ? join8(projectDir, ".cursor", "mcp.json") : join8(homeDir, ".cursor", "mcp.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "grok":
       return [{
-        path: projectDir ? join7(projectDir, ".grok", "config.toml") : join7(homeDir, ".grok", "config.toml"),
+        path: projectDir ? join8(projectDir, ".grok", "config.toml") : join8(homeDir, ".grok", "config.toml"),
         format: "toml"
       }];
     case "gemini":
       return [{
-        path: projectDir ? join7(projectDir, ".gemini", "settings.json") : join7(homeDir, ".gemini", "settings.json"),
+        path: projectDir ? join8(projectDir, ".gemini", "settings.json") : join8(homeDir, ".gemini", "settings.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "copilot":
       return projectDir ? [
-        { path: join7(projectDir, ".mcp.json"), format: "json", rootKey: "mcpServers" },
-        { path: join7(projectDir, ".vscode", "mcp.json"), format: "json", rootKey: "servers" }
+        { path: join8(projectDir, ".mcp.json"), format: "json", rootKey: "mcpServers" },
+        { path: join8(projectDir, ".vscode", "mcp.json"), format: "json", rootKey: "servers", syntax: "jsonc" }
       ] : [
         {
-          path: join7(homeDir, ".copilot", "mcp-config.json"),
+          path: join8(homeDir, ".copilot", "mcp-config.json"),
           format: "json",
           rootKey: "mcpServers"
         },
-        { path: vscodeUserConfigPath(homeDir), format: "json", rootKey: "servers" }
+        { path: vscodeUserConfigPath(homeDir), format: "json", rootKey: "servers", syntax: "jsonc" }
       ];
     case "windsurf":
       return [{
-        path: join7(homeDir, ".codeium", "windsurf", "mcp_config.json"),
+        path: join8(homeDir, ".codeium", "windsurf", "mcp_config.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "cline":
       return [{
-        path: projectDir ? join7(projectDir, ".cline", "mcp.json") : join7(homeDir, ".cline", "mcp.json"),
+        path: projectDir ? join8(projectDir, ".cline", "mcp.json") : join8(homeDir, ".cline", "mcp.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "goose":
-      return [{ path: join7(homeDir, ".config", "goose", "config.yaml"), format: "yaml" }];
+      return [{ path: join8(homeDir, ".config", "goose", "config.yaml"), format: "yaml" }];
     case "amazon-q":
       if (projectDir) {
-        return [{ path: join7(projectDir, ".amazonq", "mcp.json"), format: "json", rootKey: "mcpServers" }];
+        return [{ path: join8(projectDir, ".amazonq", "mcp.json"), format: "json", rootKey: "mcpServers" }];
       }
       return [{
-        path: existsSync4(join7(homeDir, ".aws", "amazonq", "mcp.json")) ? join7(homeDir, ".aws", "amazonq", "mcp.json") : join7(homeDir, ".aws", "amazonq", "default.json"),
+        path: existsSync4(join8(homeDir, ".aws", "amazonq", "mcp.json")) ? join8(homeDir, ".aws", "amazonq", "mcp.json") : join8(homeDir, ".aws", "amazonq", "default.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
@@ -9089,7 +9313,7 @@ function agentConfigExists(agent, homeDir = homedir4(), projectDir, codexHome) {
   return agentConfigPaths(agent, homeDir, projectDir, codexHome).some((config) => existsSync4(config.path));
 }
 async function assertClaudeProjectScope(homeDir, projectDir, name) {
-  const path = join7(homeDir, ".claude.json");
+  const path = join8(homeDir, ".claude.json");
   let contents;
   try {
     contents = await readFile4(path, "utf8");
@@ -9099,10 +9323,9 @@ async function assertClaudeProjectScope(homeDir, projectDir, name) {
   }
   let config;
   try {
-    config = JSON.parse(contents);
-    if (!config || typeof config !== "object" || Array.isArray(config)) throw new Error();
+    config = parseHostJson(contents, { path, label: "Claude", syntax: "json" }).value;
   } catch {
-    throw new Error("Cannot verify malformed Claude scope configuration at " + path + ".");
+    throw new Error("Cannot verify malformed Claude scope configuration at " + path + ". Fix it, or move it aside, and run the command again.");
   }
   const object = (value) => {
     if (value === void 0) return void 0;
@@ -9117,21 +9340,21 @@ async function assertClaudeProjectScope(homeDir, projectDir, name) {
   }
 }
 function claudeDesktopConfigPath(homeDir) {
-  if (process.platform === "darwin") return join7(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-  if (process.platform === "win32") return join7(process.env.APPDATA ?? join7(homeDir, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
-  return join7(process.env.XDG_CONFIG_HOME ?? join7(homeDir, ".config"), "Claude", "claude_desktop_config.json");
+  if (process.platform === "darwin") return join8(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  if (process.platform === "win32") return join8(process.env.APPDATA ?? join8(homeDir, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+  return join8(process.env.XDG_CONFIG_HOME ?? join8(homeDir, ".config"), "Claude", "claude_desktop_config.json");
 }
 function vscodeUserConfigPath(homeDir) {
-  if (process.platform === "darwin") return join7(homeDir, "Library", "Application Support", "Code", "User", "mcp.json");
-  if (process.platform === "win32") return join7(process.env.APPDATA ?? join7(homeDir, "AppData", "Roaming"), "Code", "User", "mcp.json");
-  return join7(process.env.XDG_CONFIG_HOME ?? join7(homeDir, ".config"), "Code", "User", "mcp.json");
+  if (process.platform === "darwin") return join8(homeDir, "Library", "Application Support", "Code", "User", "mcp.json");
+  if (process.platform === "win32") return join8(process.env.APPDATA ?? join8(homeDir, "AppData", "Roaming"), "Code", "User", "mcp.json");
+  return join8(process.env.XDG_CONFIG_HOME ?? join8(homeDir, ".config"), "Code", "User", "mcp.json");
 }
 async function readAgentRegistrations(agent, homeDir = homedir4(), projectDir, codexHome) {
   const registrations = [];
   for (const config of agentConfigPaths(agent, homeDir, projectDir, codexHome)) {
     if (!existsSync4(config.path)) continue;
     if (config.format === "json") {
-      registrations.push(...await readJsonRegistrations(config.path, config.rootKey ?? "mcpServers", agent));
+      registrations.push(...await readJsonRegistrations(config, agent));
     } else if (config.format === "toml") {
       registrations.push(...await readTomlRegistrations(config.path, agent));
     } else {
@@ -9140,14 +9363,12 @@ async function readAgentRegistrations(agent, homeDir = homedir4(), projectDir, c
   }
   return registrations.filter((registration, index, all) => all.findIndex((candidate) => candidate.name === registration.name) === index);
 }
-async function readJsonRegistrations(path, rootKey, agent) {
-  let parsed;
-  try {
-    parsed = JSON.parse(await readFile4(path, "utf8"));
-  } catch (error) {
-    throw new Error("Cannot read malformed " + (agent === "claude" ? "Claude" : AGENT_LABELS[agent]) + " configuration at " + path + ": " + message(error));
-  }
-  const servers = parsed[rootKey];
+function hostConfigLabel(agent) {
+  return agent === "claude" ? "Claude" : AGENT_LABELS[agent];
+}
+async function readJsonRegistrations(config, agent) {
+  const target = { path: config.path, label: hostConfigLabel(agent), syntax: config.syntax ?? "json" };
+  const servers = parseHostJson(await readFile4(config.path, "utf8"), target, "read").value[config.rootKey ?? "mcpServers"];
   if (!servers || typeof servers !== "object" || Array.isArray(servers)) return [];
   return Object.entries(servers).filter(([name]) => isPublicRegistrationName(name)).flatMap(([name, value]) => normalizeRegistration(name, value));
 }
@@ -9398,39 +9619,62 @@ function normalizeRegistration(name, value) {
   const env = candidate.env && typeof candidate.env === "object" && !Array.isArray(candidate.env) ? stringEntries(candidate.env) : {};
   return [{ name, command: candidate.command, args, env }];
 }
-function message(error) {
-  return error instanceof Error ? error.message : String(error);
-}
 
 // src/commands/agent-config.ts
 import { existsSync as existsSync5 } from "fs";
-import { lstat as lstat3, mkdir as mkdir4, open as open2, readFile as readFile5, rename as rename3, unlink, writeFile as writeFile2 } from "fs/promises";
+import { lstat as lstat4, mkdir as mkdir5, open as open3, readFile as readFile5, rename as rename3, unlink as unlink2, writeFile as writeFile2 } from "fs/promises";
 import { randomUUID as randomUUID4 } from "crypto";
 import { dirname as dirname5 } from "path";
 async function installAgentSkill(agent, source, homeDir, projectDir, codexHome) {
   const path = agentSkillPath(agent, homeDir, projectDir, codexHome);
   if (!path) return { installed: false };
   const contents = formatSkillForAgent(agent, source);
-  await atomicWrite(path, contents);
-  return { path, installed: true };
+  return { path, installed: true, changed: await atomicWrite(path, contents) };
 }
 async function registerAgentConfig(agent, mcp, homeDir, registration, projectDir, codexHome) {
   if (agent === "claude" && projectDir) await assertClaudeProjectScope(homeDir, projectDir, registration.name);
-  for (const config of agentConfigPaths(agent, homeDir, projectDir, codexHome)) {
-    if (config.format === "json") {
-      await registerJson(config, agent, mcp, registration);
-    } else if (config.format === "toml") {
-      await registerToml(config.path, agent, mcp, registration);
-    } else {
-      await registerGoose(config.path, mcp, registration);
+  return editHostConfigs(agentConfigPaths(agent, homeDir, projectDir, codexHome), async (config) => {
+    if (config.format === "json") return registerJson(config, agent, mcp, registration, homeDir);
+    if (config.format === "toml") return { changed: await registerToml(config.path, agent, mcp, registration) };
+    return { changed: await registerGoose(config.path, mcp, registration) };
+  });
+}
+var HostConfigPartialError = class extends Error {
+  constructor(reason, changed, backups) {
+    super(
+      reason.message + (changed.length ? " Before this, the same run had already changed: " + changed.map(printable).join(", ") + "." : "") + (backups.length ? " Backups written: " + backups.map(printable).join(", ") + "." : "")
+    );
+    this.reason = reason;
+    this.changed = changed;
+    this.backups = backups;
+  }
+  reason;
+  changed;
+  backups;
+};
+async function editHostConfigs(configs, edit) {
+  const changed = [];
+  const backups = [];
+  for (const config of configs) {
+    let result;
+    try {
+      result = await edit(config);
+    } catch (error) {
+      const partial = error instanceof HostConfigPartialError ? error : void 0;
+      const written = [...backups, ...partial?.backups ?? []];
+      if (!changed.length && !written.length) throw error;
+      throw new HostConfigPartialError(partial?.reason ?? error, changed, written);
     }
+    if (result.backup) backups.push(result.backup);
+    if (result.changed) changed.push(config.path);
   }
+  return backups;
 }
 var SHARED_HUB_AGENTS = ["claude", "codex"];
 async function registerAgentHttpConfig(agent, homeDir, registration, codexHome) {
   const [config] = agentConfigPaths(agent, homeDir, void 0, codexHome);
   if (agent === "claude") {
-    await writeJsonServer(config, agent, registration.name, {
+    await writeJsonServer(config, agent, registration.name, homeDir, {
       type: "http",
       url: registration.url,
       headers: registration.headers
@@ -9444,17 +9688,15 @@ async function registerAgentHttpConfig(agent, homeDir, registration, codexHome)
   await atomicWrite(config.path, text3 + block, before);
 }
 async function unregisterAgentConfig(agent, homeDir, name, projectDir, codexHome) {
-  for (const config of agentConfigPaths(agent, homeDir, projectDir, codexHome)) {
-    if (!existsSync5(config.path)) continue;
-    if (config.format === "json") {
-      await unregisterJson(config, agent, name);
-    } else if (config.format === "toml") {
+  const configs = agentConfigPaths(agent, homeDir, projectDir, codexHome).filter((config) => existsSync5(config.path));
+  return editHostConfigs(configs, async (config) => {
+    if (config.format === "json") return editJsonServer(config, agent, name, void 0, homeDir);
+    if (config.format === "toml") {
       const text3 = withoutMcpServerSections(await readFile5(config.path, "utf8"), name);
-      await atomicWrite(config.path, text3 ? text3 + "\n" : "");
-    } else {
-      await unregisterGoose(config.path, name);
+      return { changed: await atomicWrite(config.path, text3 ? text3 + "\n" : "") };
     }
-  }
+    return { changed: await unregisterGoose(config.path, name) };
+  });
 }
 function registrationEnvironment(agent, registration) {
   let privateAliases = {};
@@ -9486,56 +9728,36 @@ function registrationEnvironment(agent, registration) {
     ...privateAliases
   };
 }
-async function registerJson(config, agent, mcp, registration) {
+async function registerJson(config, agent, mcp, registration, homeDir) {
   const entry = {
     command: mcp.command,
     args: mcp.args,
     env: registrationEnvironment(agent, registration)
   };
   if (agent === "claude" || agent === "claude-desktop" || (config.rootKey ?? "mcpServers") === "servers") entry.type = "stdio";
-  await writeJsonServer(config, agent, registration.name, entry);
+  return writeJsonServer(config, agent, registration.name, homeDir, entry);
 }
-async function writeJsonServer(config, agent, name, entry) {
-  const before = await fileSnapshot(config.path);
-  let parsed = {};
-  if (before.contents !== void 0) {
-    try {
-      parsed = JSON.parse(before.contents);
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Expected an object.");
-    } catch (error) {
-      throw new Error(
-        "Cannot update malformed " + (agent === "claude" ? "Claude" : AGENT_LABELS[agent]) + " configuration at " + config.path + ": " + (error instanceof Error ? error.message : String(error))
-      );
-    }
-  }
-  const rootKey = config.rootKey ?? "mcpServers";
-  const existingServers = parsed[rootKey];
-  if (existingServers !== void 0 && (!existingServers || typeof existingServers !== "object" || Array.isArray(existingServers))) {
-    throw new Error("Cannot update malformed " + AGENT_LABELS[agent] + " MCP configuration at " + config.path + ".");
-  }
-  const servers = existingServers ?? {};
-  servers[name] = entry;
-  parsed[rootKey] = servers;
-  await atomicWrite(config.path, JSON.stringify(parsed, null, 2) + "\n", before);
+async function writeJsonServer(config, agent, name, homeDir, entry) {
+  return editJsonServer(config, agent, name, entry, homeDir);
 }
-async function unregisterJson(config, agent, name) {
-  let parsed;
+async function editJsonServer(config, agent, name, entry, homeDir) {
+  const target = { path: config.path, label: hostConfigLabel(agent), syntax: config.syntax ?? "json" };
+  const rootKey = config.rootKey ?? "mcpServers";
+  const before = await fileSnapshot(config.path);
+  const document = parseHostJson(before.contents, target);
+  if (entry === void 0) {
+    const servers = document.value[rootKey];
+    if (!servers || typeof servers !== "object" || Array.isArray(servers) || !Object.hasOwn(servers, name)) return { changed: false };
+  }
+  const contents = editHostServer(document, rootKey, name, entry, target);
+  if (contents === before.contents) return { changed: false };
+  const backup = editsInPlace(document, target) ? await writeHostJsonBackup(target, before.contents, homeDir, agent) : void 0;
   try {
-    parsed = JSON.parse(await readFile5(config.path, "utf8"));
+    return { changed: await atomicWrite(config.path, contents, before), ...backup ? { backup } : {} };
   } catch (error) {
-    throw new Error(
-      "Cannot update malformed " + AGENT_LABELS[agent] + " configuration at " + config.path + ": " + (error instanceof Error ? error.message : String(error))
-    );
-  }
-  const rootKey = config.rootKey ?? "mcpServers";
-  const existingServers = parsed[rootKey];
-  if (existingServers !== void 0 && (!existingServers || typeof existingServers !== "object" || Array.isArray(existingServers))) {
-    throw new Error("Cannot update malformed " + AGENT_LABELS[agent] + " MCP configuration at " + config.path + ".");
+    if (backup) throw new HostConfigPartialError(error, [], [backup]);
+    throw error;
   }
-  const servers = existingServers ?? {};
-  delete servers[name];
-  parsed[rootKey] = servers;
-  await atomicWrite(config.path, JSON.stringify(parsed, null, 2) + "\n");
 }
 async function registerToml(path, agent, mcp, registration) {
   const before = await fileSnapshot(path);
@@ -9545,7 +9767,7 @@ async function registerToml(path, agent, mcp, registration) {
   const environment = registrationEnvironment(agent, registration);
   const environmentText = Object.entries(environment).map(([key, value]) => JSON.stringify(key) + " = " + JSON.stringify(value)).join(", ");
   const block = agent === "grok" ? "\n\n[mcp_servers." + registration.name + "]\ncommand = " + JSON.stringify(mcp.command) + args + "\nenv = { " + environmentText + " }\n" : "\n\n[mcp_servers." + registration.name + "]\ncommand = " + JSON.stringify(mcp.command) + args + "\n\n[mcp_servers." + registration.name + ".env]\n" + Object.entries(environment).map(([key, value]) => key + " = " + JSON.stringify(value)).join("\n") + "\n";
-  await atomicWrite(path, text3 + block, before);
+  return atomicWrite(path, text3 + block, before);
 }
 async function registerGoose(path, mcp, registration) {
   const existing = existsSync5(path) ? await readFile5(path, "utf8") : "";
@@ -9562,11 +9784,11 @@ async function registerGoose(path, mcp, registration) {
     "    envs:",
     ...Object.entries(environment).map(([key, value]) => "      " + key + ": " + yamlScalar(value))
   ].join("\n");
-  await atomicWrite(path, insertGooseExtension(withoutTopolo, block));
+  return atomicWrite(path, insertGooseExtension(withoutTopolo, block));
 }
 async function unregisterGoose(path, name) {
   const existing = await readFile5(path, "utf8");
-  await atomicWrite(path, removeGooseExtension(existing, name));
+  return atomicWrite(path, removeGooseExtension(existing, name));
 }
 function removeGooseExtension(text3, name) {
   const lines = text3.split(/\r?\n/);
@@ -9622,7 +9844,7 @@ async function fileSnapshot(path) {
   const parents = [];
   for (let parent = dirname5(path); ; parent = dirname5(parent)) {
     try {
-      const stat3 = await lstat3(parent);
+      const stat3 = await lstat4(parent);
       if (!stat3.isDirectory() || stat3.isSymbolicLink()) throw new Error("Host destination contains a symbolic link or non-directory at " + parent + ".");
       parents.push({ path: parent, identity: [stat3.dev, stat3.ino].join(":") });
     } catch (error) {
@@ -9631,10 +9853,10 @@ async function fileSnapshot(path) {
     if (dirname5(parent) === parent) break;
   }
   try {
-    const stat3 = await lstat3(path);
+    const stat3 = await lstat4(path);
     if (!stat3.isFile() || stat3.isSymbolicLink() || stat3.nlink !== 1) throw new Error("Host configuration must be a single regular file at " + path + ".");
     const contents = await readFile5(path, "utf8");
-    if (fileIdentity(await lstat3(path)) !== fileIdentity(stat3)) throw new Error("Host configuration changed while reading at " + path + ".");
+    if (fileIdentity(await lstat4(path)) !== fileIdentity(stat3)) throw new Error("Host configuration changed while reading at " + path + ".");
     return { contents, identity: fileIdentity(stat3), parents };
   } catch (error) {
     if (error.code === "ENOENT") return { parents };
@@ -9650,12 +9872,12 @@ async function assertSnapshot(path, before) {
 async function atomicWrite(path, contents, before) {
   before ??= await fileSnapshot(path);
   await assertSnapshot(path, before);
-  if (before.contents === contents) return;
-  await mkdir4(dirname5(path), { recursive: true });
+  if (before.contents === contents) return false;
+  await mkdir5(dirname5(path), { recursive: true });
   const destination = await fileSnapshot(path);
   await assertSnapshot(path, before);
   const temporaryPath = path + ".topolo-" + randomUUID4() + ".tmp";
-  const handle = await open2(temporaryPath, "wx", 384);
+  const handle = await open3(temporaryPath, "wx", 384);
   let temporaryIdentity;
   let handleClosed = false;
   let temporaryPending = true;
@@ -9667,7 +9889,7 @@ async function atomicWrite(path, contents, before) {
     await handle.close();
     handleClosed = true;
     await assertSnapshot(path, destination);
-    const temporary = await lstat3(temporaryPath);
+    const temporary = await lstat4(temporaryPath);
     if (!temporary.isFile() || temporary.isSymbolicLink() || temporary.nlink !== 1 || [temporary.dev, temporary.ino].join(":") !== temporaryIdentity) {
       throw new Error("Host temporary file custody changed before rename at " + path + ".");
     }
@@ -9675,20 +9897,21 @@ async function atomicWrite(path, contents, before) {
     temporaryPending = false;
     const installed = await fileSnapshot(path);
     if (installed.contents !== contents) throw new Error("Host configuration read-back failed at " + path + ".");
+    return true;
   } finally {
     if (!handleClosed) await handle.close();
     if (temporaryPending && temporaryIdentity) {
       let cleanupOwned = false;
       try {
         const parentsOwned = await Promise.all(destination.parents.map(async (parent) => {
-          const current2 = await lstat3(parent.path);
+          const current2 = await lstat4(parent.path);
           return current2.isDirectory() && !current2.isSymbolicLink() && [current2.dev, current2.ino].join(":") === parent.identity;
         }));
-        const current = await lstat3(temporaryPath);
+        const current = await lstat4(temporaryPath);
         cleanupOwned = parentsOwned.every(Boolean) && current.isFile() && !current.isSymbolicLink() && current.nlink === 1 && [current.dev, current.ino].join(":") === temporaryIdentity;
       } catch {
       }
-      if (cleanupOwned) await unlink(temporaryPath);
+      if (cleanupOwned) await unlink2(temporaryPath);
     }
   }
 }
@@ -9710,12 +9933,12 @@ function withoutMcpServerSections(text3, name) {
 // src/commands/mcp-hub-setup.ts
 import { realpathSync } from "fs";
 import { readFile as readFile8 } from "fs/promises";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 
 // src/lib/mcp-hub-config.ts
 import { randomBytes } from "crypto";
-import { lstat as lstat4, mkdir as mkdir5, open as open3, readFile as readFile6, rename as rename4, unlink as unlink2 } from "fs/promises";
-import { dirname as dirname6, join as join8 } from "path";
+import { lstat as lstat5, mkdir as mkdir6, open as open4, readFile as readFile6, rename as rename4, unlink as unlink3 } from "fs/promises";
+import { dirname as dirname6, join as join9 } from "path";
 var MCP_HUB_DEFAULT_PORT = 7337;
 var MCP_HUB_ENVIRONMENTS = ["production", "staging", "development", "local"];
 var RESERVED_NAME = ["topolo", "platform"].join("-");
@@ -9723,7 +9946,7 @@ var NAME_PATTERN = /^topolo(-[a-z0-9][a-z0-9_-]*)?$/;
 var TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/;
 function mcpHubPaths(credentialStorePath = configPath()) {
   const directory = dirname6(credentialStorePath);
-  return { config: join8(directory, "mcp-hub.json"), token: join8(directory, "mcp-hub.token") };
+  return { config: join9(directory, "mcp-hub.json"), token: join9(directory, "mcp-hub.token") };
 }
 function mcpHubUrl(port, name) {
   return `http://127.0.0.1:${port}/mcp/${name}`;
@@ -9820,9 +10043,9 @@ function upsertMcpHubIdentity(config, identity) {
   return { ...config, identities };
 }
 async function writePrivateFile(path, contents) {
-  await mkdir5(dirname6(path), { recursive: true, mode: 448 });
+  await mkdir6(dirname6(path), { recursive: true, mode: 448 });
   const temporary = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
-  const handle = await open3(temporary, "wx", 384);
+  const handle = await open4(temporary, "wx", 384);
   try {
     await handle.writeFile(contents, "utf8");
   } finally {
@@ -9831,7 +10054,7 @@ async function writePrivateFile(path, contents) {
   try {
     await rename4(temporary, path);
   } catch (error) {
-    await unlink2(temporary).catch(() => void 0);
+    await unlink3(temporary).catch(() => void 0);
     throw error;
   }
 }
@@ -9839,7 +10062,7 @@ async function writeMcpHubConfig(path, config) {
   await writePrivateFile(path, serializeMcpHubConfig(config));
 }
 async function assertPrivateTokenFile(path) {
-  const stat3 = await lstat4(path);
+  const stat3 = await lstat5(path);
   if (!stat3.isFile() || stat3.isSymbolicLink() || stat3.nlink !== 1) {
     throw new Error(`MCP hub token at ${path} must be a single regular file.`);
   }
@@ -9868,9 +10091,9 @@ async function ensureMcpHubToken(path) {
   } catch (error) {
     if (!/is missing at/.test(error.message)) throw error;
   }
-  await mkdir5(dirname6(path), { recursive: true, mode: 448 });
+  await mkdir6(dirname6(path), { recursive: true, mode: 448 });
   const token = randomBytes(32).toString("base64url");
-  const handle = await open3(path, "wx", 384);
+  const handle = await open4(path, "wx", 384);
   try {
     await handle.writeFile(token + "\n", "utf8");
   } finally {
@@ -9882,7 +10105,7 @@ async function ensureMcpHubToken(path) {
 // src/lib/mcp-hub-service.ts
 import { spawnSync as spawnSync4 } from "child_process";
 import { readFile as readFile7 } from "fs/promises";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 var MCP_HUB_LAUNCHD_LABEL = "io.topolo.mcp-hub";
 var MCP_HUB_SYSTEMD_UNIT = "topolo-mcp-hub.service";
 var PASSTHROUGH_ENVIRONMENT = ["TOPOLO_CONFIG_PATH", "XDG_CONFIG_HOME"];
@@ -9896,7 +10119,7 @@ function serviceKindFor(platform4) {
   return void 0;
 }
 function mcpHubServicePath(kind, homeDir, xdgConfigHome) {
-  return kind === "launchd" ? join9(homeDir, "Library", "LaunchAgents", `${MCP_HUB_LAUNCHD_LABEL}.plist`) : join9(xdgConfigHome || join9(homeDir, ".config"), "systemd", "user", MCP_HUB_SYSTEMD_UNIT);
+  return kind === "launchd" ? join10(homeDir, "Library", "LaunchAgents", `${MCP_HUB_LAUNCHD_LABEL}.plist`) : join10(xdgConfigHome || join10(homeDir, ".config"), "systemd", "user", MCP_HUB_SYSTEMD_UNIT);
 }
 function serviceEnvironment(environment) {
   const selected = {};
@@ -9991,7 +10214,7 @@ async function installMcpHubService(options) {
     };
   }
   const path = mcpHubServicePath(kind, options.homeDir, options.xdgConfigHome);
-  const spec = kind === "launchd" ? { ...options.spec, logPath: options.spec.logPath ?? join9(options.homeDir, "Library", "Logs", "topolo-mcp-hub.log") } : options.spec;
+  const spec = kind === "launchd" ? { ...options.spec, logPath: options.spec.logPath ?? join10(options.homeDir, "Library", "Logs", "topolo-mcp-hub.log") } : options.spec;
   const contents = kind === "launchd" ? renderLaunchdPlist(spec) : renderSystemdUnit(spec);
   const changed = await readExisting(path) !== contents;
   if (changed) await writePrivateFile(path, contents);
@@ -10173,7 +10396,7 @@ async function installSharedAgentSurfaces(options, dependencies) {
 function defaultSharedSetupDependencies(skillsDir, realHome) {
   return {
     paths: () => mcpHubPaths(),
-    skillSource: () => readFile8(join10(skillsDir, "topolo", "SKILL.md"), "utf8"),
+    skillSource: () => readFile8(join11(skillsDir, "topolo", "SKILL.md"), "utf8"),
     platform: process.platform,
     realHome,
     nodeCommand: stableNodeCommand,
@@ -10194,10 +10417,10 @@ function formatSharedSetup(result) {
     lines.push(`  skill -> ${row.skillPath}`);
     lines.push(row.mcp === "config-file" ? `  HTTP MCP registered: ${row.registrations.join(", ")}` : `  HTTP MCP registration FAILED: ${row.detail}`);
   }
-  for (const entry of result.skipped) lines.push(`Skipped ${entry.name} (${AGENT_LABELS[entry.agent]}): ${entry.reason}`);
+  for (const entry of result.skipped) lines.push(`Skipped ${printable(entry.name)} (${AGENT_LABELS[entry.agent]}): ${entry.reason}`);
   if (result.service) lines.push(`Service (${result.service.kind}): ${result.service.detail}`);
   lines.push("", "Next: restart the agents, then run `topolo doctor --shared`.");
-  return lines.join("\n");
+  return printableLines(lines.join("\n"));
 }
 
 // src/commands/skills.ts
@@ -10207,7 +10430,7 @@ function skillsSourceDir() {
   const distCandidate = resolve4(here, "../skills");
   const srcCandidate = resolve4(here, "../../skills");
   for (const candidate of [distCandidate, srcCandidate]) {
-    if (existsSync6(join11(candidate, "topolo", "SKILL.md"))) return candidate;
+    if (existsSync6(join12(candidate, "topolo", "SKILL.md"))) return candidate;
   }
   return distCandidate;
 }
@@ -10265,26 +10488,30 @@ async function installForAgent(agent, sourceDir, mcp, opts) {
       return { agent, skillInstalled: false, mcp: "failed", detail: err instanceof Error ? err.message : String(err) };
     }
   }
-  const source = await readFile9(join11(sourceDir, "topolo", "SKILL.md"), "utf8");
+  const source = await readFile9(join12(sourceDir, "topolo", "SKILL.md"), "utf8");
   const skill = await installAgentSkill(agent, source, homeDir, projectDir, codexHome);
   if (!registration) {
     return { agent, skillPath: skill.path, skillInstalled: skill.installed, mcp: "skipped" };
   }
+  let backups = [];
   try {
-    await registerAgentConfig(agent, mcp, homeDir, registration, projectDir, codexHome);
+    backups = await registerAgentConfig(agent, mcp, homeDir, registration, projectDir, codexHome);
     const installed = (await readAgentRegistrations(agent, homeDir, projectDir, codexHome)).find((entry) => entry.name === registration.name);
     const expectedEnvironment = registrationEnvironment(agent, registration);
     if (!installed || installed.command !== mcp.command || JSON.stringify(installed.args) !== JSON.stringify(mcp.args) || Object.entries(expectedEnvironment).some(([key, value]) => installed.env[key] !== value)) {
       throw new Error(`Host configuration did not retain the ${registration.name} MCP registration.`);
     }
-    return { agent, skillPath: skill.path, skillInstalled: skill.installed, mcp: "config-file" };
+    return { agent, skillPath: skill.path, skillInstalled: skill.installed, mcp: "config-file", ...backups.length ? { backups } : {} };
   } catch (err) {
+    if (err instanceof HostConfigPartialError) backups = err.backups;
+    const skillNote = skill.changed ? " This run also wrote the Topolo skill at " + printable(skill.path) + "." : "";
     return {
       agent,
       skillPath: skill.path,
       skillInstalled: skill.installed,
       mcp: "failed",
-      detail: err instanceof Error ? err.message : String(err)
+      detail: (err instanceof Error ? err.message : String(err)) + skillNote,
+      ...backups.length ? { backups } : {}
     };
   }
 }
@@ -10351,11 +10578,7 @@ function registerSkillsCommand(program2) {
         ...opts,
         homeDir: opts.agentHome ? resolve4(opts.agentHome) : void 0
       });
-      emit(
-        { removed },
-        mode,
-        () => removed.map((r) => `${AGENT_LABELS2[r.agent]}: ${r.name} removed=${r.registrationRemoved}, skill removed=${r.skillRemoved}`).join("\n")
-      );
+      emit({ removed }, mode, () => formatUninstall(removed));
     } catch (err) {
       fail2(err, mode);
     }
@@ -10363,7 +10586,7 @@ function registerSkillsCommand(program2) {
 }
 async function installAgentSurfaces(opts) {
   const sourceDir = skillsSourceDir();
-  if (!existsSync6(join11(sourceDir, "topolo", "SKILL.md"))) {
+  if (!existsSync6(join12(sourceDir, "topolo", "SKILL.md"))) {
     throw new Error("Bundled skill file not found. Reinstall the CLI: npm install -g @topolo/cli");
   }
   const mcp = resolveMcpCommand();
@@ -10413,19 +10636,19 @@ function registerSetupCommand(program2) {
 function assertSharedSetupSucceeded(result) {
   const failed = result.installed.filter((row) => row.mcp === "failed");
   if (failed.length) {
-    throw new Error(failed.map((row) => `${AGENT_LABELS2[row.agent]}: ${row.detail}`).join("; "));
+    throw new Error(printableLines(failed.map((row) => `${AGENT_LABELS2[row.agent]}: ${row.detail}`).join("; ")));
   }
 }
 function assertAgentSetupSucceeded(results) {
   const failed = results.filter((result) => result.mcp === "failed");
   if (failed.length) {
-    throw new Error(failed.map((result) => `${AGENT_LABELS2[result.agent]}: ${result.detail ?? "MCP registration failed"}`).join("; "));
+    throw new Error(printableLines(failed.map((result) => `${AGENT_LABELS2[result.agent]}: ${result.detail ?? "MCP registration failed"}`).join("; ")));
   }
 }
 async function agentSurfaceStatus(options = {}) {
   const target = resolveAgentHostTarget({ homeDir: options.homeDir, projectDir: options.project, codexHome: options.codexHome });
   const { homeDir, projectDir, codexHome } = target;
-  const sourceSkill = await readFile9(join11(skillsSourceDir(), "topolo", "SKILL.md"), "utf8");
+  const sourceSkill = await readFile9(join12(skillsSourceDir(), "topolo", "SKILL.md"), "utf8");
   const agents = resolveTargets({
     agent: options.agent,
     all: options.all,
@@ -10457,15 +10680,19 @@ async function uninstallAgentSurfaces(options) {
   for (const agent of resolveTargets({ ...options, homeDir, project: projectDir, codexHome })) {
     const before = await readAgentRegistrations(agent, homeDir, projectDir, codexHome);
     const registrationRemoved = before.some((entry) => entry.name === name);
-    await unregisterAgentConfig(agent, homeDir, name, projectDir, codexHome);
+    const backups = await unregisterAgentConfig(agent, homeDir, name, projectDir, codexHome);
     const remaining = await readAgentRegistrations(agent, homeDir, projectDir, codexHome);
     const skillPath = agentSkillPath(agent, homeDir, projectDir, codexHome);
     const skillRemoved = remaining.length === 0 && Boolean(skillPath && existsSync6(skillPath));
     if (skillRemoved && skillPath) await rm3(dirname7(skillPath), { recursive: true, force: true });
-    removed.push({ agent, name, registrationRemoved, skillRemoved });
+    removed.push({ agent, name, registrationRemoved, skillRemoved, ...backups.length ? { backups } : {} });
   }
   return removed;
 }
+function formatUninstall(removed) {
+  return printableLines(removed.map((r) => `${AGENT_LABELS2[r.agent]}: ${r.name} removed=${r.registrationRemoved}, skill removed=${r.skillRemoved}` + (r.backups ?? []).map((path) => `
+  previous configuration backed up -> ${path}`).join("")).join("\n"));
+}
 function formatInstall(results, mcp) {
   const lines = [];
   const mcpStr = [mcp.command, ...mcp.args].join(" ");
@@ -10476,17 +10703,18 @@ function formatInstall(results, mcp) {
     else if (r.mcp === "config-file") lines.push(`  MCP registered by editing the config file (${mcpStr})`);
     else if (r.mcp === "skipped") lines.push("  MCP registration skipped (--no-mcp)");
     else lines.push(`  MCP registration FAILED: ${r.detail ?? "unknown error"}`);
+    for (const backup of r.backups ?? []) lines.push(`  previous configuration backed up -> ${backup}`);
   }
   lines.push("");
   lines.push("Next: run `topolo auth login` if you have not, then restart the agent.");
   lines.push("The MCP reads that credential \u2014 no API key needed. Available tools are");
   lines.push("scoped to your role, permissions, and organization at runtime.");
-  return lines.join("\n");
+  return printableLines(lines.join("\n"));
 }
 function formatStatus(rows) {
-  return rows.map(
-    (r) => `${AGENT_LABELS2[r.agent]}: skill ${!r.skillPath ? "host-managed" : r.skillInstalled ? r.skillCurrent ? "current" : "stale" : "not installed"} (${r.skillPath ?? "native host surface"}), ${r.agent} CLI ${r.cliAvailable ? "available" : "not found"}, MCP registrations: ${r.registrations.map((registration) => registration.name).join(", ") || "none"}`
-  ).join("\n");
+  return printableLines(rows.map(
+    (r) => `${AGENT_LABELS2[r.agent]}: skill ${!r.skillPath ? "host-managed" : r.skillInstalled ? r.skillCurrent ? "current" : "stale" : "not installed"} (${r.skillPath ?? "native host surface"}), ${r.agent} CLI ${r.cliAvailable ? "available" : "not found"}, MCP registrations: ${r.registrations.map((registration) => printable(registration.name)).join(", ") || "none"}`
+  ).join("\n"));
 }
 
 // src/commands/doctor.ts
@@ -10527,7 +10755,7 @@ var defaultSharedDoctorDependencies = () => ({
   fileExists: async (path) => access(path).then(() => true, () => false),
   environment: process.env
 });
-function message2(error) {
+function message(error) {
   return error instanceof Error ? error.message : String(error);
 }
 async function runSharedDoctor(options, dependencies) {
@@ -10544,7 +10772,7 @@ async function runSharedDoctor(options, dependencies) {
     config = { ...config, identities: selected };
     checks.push({ name: "hub-config", ok: true, detail: `${paths.config}: port ${config.port}, ${selected.length} identities` });
   } catch (error) {
-    checks.push({ name: "hub-config", ok: false, detail: message2(error) });
+    checks.push({ name: "hub-config", ok: false, detail: message(error) });
     return done();
   }
   let token;
@@ -10552,7 +10780,7 @@ async function runSharedDoctor(options, dependencies) {
     token = await readMcpHubToken(paths.token);
     checks.push({ name: "hub-token", ok: true, detail: `${paths.token} is private (0600)` });
   } catch (error) {
-    checks.push({ name: "hub-token", ok: false, detail: message2(error) });
+    checks.push({ name: "hub-token", ok: false, detail: message(error) });
     return done();
   }
   const target = resolveAgentHostTarget({ homeDir: options.agentHome, codexHome: options.codexHome });
@@ -10569,14 +10797,14 @@ async function runSharedDoctor(options, dependencies) {
     if (response.status !== 200) throw new Error(`hub /health answered ${response.status}`);
     checks.push({ name: "hub", ok: true, detail: `listening on 127.0.0.1:${config.port}` });
   } catch (error) {
-    checks.push({ name: "hub", ok: false, detail: `hub is not reachable on 127.0.0.1:${config.port}: ${message2(error)}` });
+    checks.push({ name: "hub", ok: false, detail: `hub is not reachable on 127.0.0.1:${config.port}: ${message(error)}` });
     return done();
   }
   const explicit = [...options.agent ?? [], ...options.claude ? ["claude"] : [], ...options.codex ? ["codex"] : []];
   const agents = (explicit.length ? explicit : [...SHARED_HUB_AGENTS]).filter((agent) => SHARED_HUB_AGENTS.includes(agent));
   for (const agent of agents) {
     const registrations = await readAgentRegistrations(agent, target.homeDir, void 0, target.codexHome).catch((error) => {
-      checks.push({ name: "registration", ok: false, detail: `${agent}: ${message2(error)}` });
+      checks.push({ name: "registration", ok: false, detail: `${agent}: ${message(error)}` });
       return void 0;
     });
     if (!registrations) continue;
@@ -10599,13 +10827,13 @@ async function runSharedDoctor(options, dependencies) {
       );
       checks.push({ name: "mcp", ok: true, detail: `${identity.name}: ${detail}` });
     } catch (error) {
-      checks.push({ name: "mcp", ok: false, detail: `${identity.name}: ${message2(error)}` });
+      checks.push({ name: "mcp", ok: false, detail: `${identity.name}: ${message(error)}` });
     }
   }
   return done();
 }
 function formatSharedDoctor(result) {
-  return result.checks.map((check) => `${check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`).join("\n");
+  return result.checks.map((check) => `${check.ok ? "PASS" : "FAIL"} ${check.name}: ${printableLines(check.detail)}`).join("\n");
 }
 
 // src/commands/doctor.ts
@@ -10736,7 +10964,7 @@ function normalizeDoctorContext(value) {
   return context;
 }
 function formatDoctor(result) {
-  return result.checks.map((check) => `${check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`).join("\n");
+  return result.checks.map((check) => `${check.ok ? "PASS" : "FAIL"} ${check.name}: ${printableLines(check.detail)}`).join("\n");
 }
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
@@ -11322,7 +11550,7 @@ function registerInstallationsCommand(program2) {
 import { createTopoloMcpLocalHandler } from "@topolo/mcp/local";
 
 // src/lib/mcp-hub-server.ts
-import { createHash as createHash5, timingSafeEqual } from "crypto";
+import { createHash as createHash6, timingSafeEqual } from "crypto";
 import { stat as stat2 } from "fs/promises";
 import { createServer } from "http";
 var MCP_HUB_HOST = "127.0.0.1";
@@ -11333,11 +11561,11 @@ var STRIPPED_HEADERS = /* @__PURE__ */ new Set(["authorization", "x-api-key", "c
 function json(status, body, headers = {}) {
   return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", ...headers } });
 }
-function refusal(status, message3, headers = {}) {
-  return json(status, { jsonrpc: "2.0", error: { code: -32e3, message: message3 }, id: null }, headers);
+function refusal(status, message2, headers = {}) {
+  return json(status, { jsonrpc: "2.0", error: { code: -32e3, message: message2 }, id: null }, headers);
 }
 function digest(value) {
-  return createHash5("sha256").update(value, "utf8").digest();
+  return createHash6("sha256").update(value, "utf8").digest();
 }
 function bearerTokenMatches(header, token) {
   const match = /^Bearer[ \t]+(\S+)[ \t]*$/i.exec(header ?? "");