@topolo/cli 0.13.26 → 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);
 }
@@ -326,78 +326,10 @@ function validTopoloActionAccessPolicy(value) {
   }
   return true;
 }
-function record2(value) {
-  return !!value && typeof value === "object" && !Array.isArray(value);
-}
-function text(value, limit = 512) {
-  return typeof value === "string" && value.trim() ? value.trim().slice(0, limit) : null;
-}
-function strings2(value) {
-  return Array.isArray(value) ? value.slice(0, 8).flatMap((item) => {
-    const result = text(item);
-    return result ? [result] : [];
-  }) : [];
-}
-function pairs(value, first, second) {
-  return Array.isArray(value) ? value.slice(0, 8).flatMap((item) => {
-    if (!record2(item)) return [];
-    const a = text(item[first], 160);
-    const b = text(item[second]);
-    return a && b ? [{ [first]: a, [second]: b }] : [];
-  }) : [];
-}
-function docs(value) {
-  const result = text(value, 2048);
-  if (!result) return null;
-  try {
-    const url = new URL(result);
-    return url.protocol === "https:" && !url.username && !url.password ? url.href : null;
-  } catch {
-    return null;
-  }
-}
-function normalizeApplicationGuide(value) {
-  if (!record2(value) || value.schemaVersion !== 1 || value.source !== "published_application_manifest") return null;
-  const purpose = text(value.purpose, 2048);
-  const gettingStarted = strings2(value.gettingStarted);
-  const docsUrl = docs(value.docsUrl);
-  return {
-    schemaVersion: 1,
-    source: "published_application_manifest",
-    publishedAt: text(value.publishedAt, 160),
-    purpose,
-    problemStatement: text(value.problemStatement, 2048),
-    solutionStatement: text(value.solutionStatement, 2048),
-    benefits: strings2(value.benefits),
-    features: pairs(value.features, "title", "description"),
-    gettingStarted,
-    worksWellWith: pairs(value.worksWellWith, "appId", "reason"),
-    docsUrl,
-    missingFields: [...!purpose ? ["purpose"] : [], ...!docsUrl ? ["docsUrl"] : [], ...!gettingStarted.length ? ["gettingStarted"] : []]
-  };
-}
-function applyAuthHeaders(headers, credential) {
-  if (credential.kind === "api_key") {
-    headers.set("X-Api-Key", credential.apiKey);
-    return;
-  }
-  headers.set("Authorization", `${credential.kind === "dpop_access_token" ? "DPoP" : "Bearer"} ${credential.accessToken}`);
-}
-function applyAuditHeaders(headers, agent, requestId) {
-  headers.set("X-Topolo-Client", `${agent.clientName}/${agent.clientVersion}`);
-  if (agent.agentName) headers.set("X-Topolo-Agent", agent.agentName);
-  headers.set("X-Topolo-Request-Id", requestId);
-}
-function generateRequestId() {
-  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
-    return crypto.randomUUID();
-  }
-  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
-}
 var TopoloSdkError = class extends Error {
   code;
-  constructor(code, message3) {
-    super(message3);
+  constructor(code, message2) {
+    super(message2);
     this.name = "TopoloSdkError";
     this.code = code;
   }
@@ -518,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;
@@ -541,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);
@@ -585,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;
 }
@@ -660,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 } : {} };
 }
@@ -681,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);
     }
   }
@@ -691,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);
       }
     }
@@ -772,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";
   }
 };
@@ -785,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;
@@ -808,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);
@@ -817,158 +749,12 @@ 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 });
   }
 };
-var ACTION_SECRET_PREFIX = "topolo-secret:";
-function isActionSecretReference(value) {
-  return typeof value === "string" && value.startsWith(ACTION_SECRET_PREFIX);
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function sensitive(key, value) {
-  const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
-  if (normalized === "capability") {
-    if (typeof value !== "string") return value !== null && value !== void 0 && typeof value !== "boolean" && typeof value !== "number";
-    const text4 = value.trim();
-    return Boolean(text4) && !/^[a-z][a-z0-9_-]{0,31}$/.test(text4);
-  }
-  return ["authorization", "cookie", "setcookie", "proxyauthorization"].includes(normalized) || /(token|secret|password|privatekey|apikey|backupcodes?|recoverycodes?)$/.test(normalized);
-}
-function maskActionSecrets(value, secrets) {
-  let masked = value;
-  for (const [secret, reference] of secrets) {
-    const encoded = encodeURIComponent(secret);
-    const variants = [.../* @__PURE__ */ new Set([secret, encoded])].map((item) => item.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
-    masked = masked.replace(new RegExp(variants.join("|"), "g"), (match) => match === secret ? reference : encodeURIComponent(reference));
-  }
-  return masked;
-}
-async function resolveActionSecrets(value, store, secrets) {
-  if (isActionSecretReference(value)) {
-    if (!store) throw new TopoloSdkError("action_secret_store_required", "Protected action references require a secret store.");
-    const resolved = await store.load(value);
-    if (typeof resolved !== "string" || !resolved) throw new TopoloSdkError("action_secret_unsupported_type", "Protected action handoff requires a nonempty string credential.");
-    secrets.set(resolved, value);
-    return resolved;
-  }
-  if (Array.isArray(value)) return Promise.all(value.map((item) => resolveActionSecrets(item, store, secrets)));
-  if (!isRecord(value)) return value;
-  return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, item]) => [key, await resolveActionSecrets(item, store, secrets)])));
-}
-async function protectActionResult(value, store, options = {}) {
-  const secrets = /* @__PURE__ */ new Map();
-  function documentation(item, key) {
-    if (options.preserveActionSchemas === true && ["inputSchema", "outputSchema", "input_schema", "output_schema"].includes(key) && isRecord(item)) return true;
-    if (options.preserveActionContracts === true && ["agentContract", "agent_contract"].includes(key) && isRecord(item)) return true;
-    return options.preserveAgentGuidance === true && key === "agentGuidance" && isRecord(item) && item.schemaVersion === 1 && typeof item.kind === "string" && ["action-guide", "product-guide", "concept"].includes(item.kind);
-  }
-  function localizationMap(path) {
-    const location = path.join("/");
-    if (options.localizationAction === "sources.verify") return location === "data/hashes";
-    if (options.localizationAction === "values.bulk_upsert") return location === "data/sourceHashes";
-    return ["translation.release.prepare", "translation.release.import", "translation.release.get"].includes(options.localizationAction ?? "") && /^data\/bundle\/catalogs\/\*\/(sources|(?:packs|provenance)\/[^/]+)$/.test(location);
-  }
-  async function protect(item, key = "", path = []) {
-    if (documentation(item, key)) return item;
-    if (isActionSecretReference(item)) return item;
-    if (Array.isArray(item) && /(?:backup|recovery)codes$/.test(key.toLowerCase().replace(/[^a-z0-9]/g, ""))) {
-      return Promise.all(item.map((child) => protect(child, key, [...path, "*"])));
-    }
-    if (sensitive(key, item)) {
-      const reference = store ? await store.save(item) : "[REDACTED]";
-      if (typeof item === "string" && item) secrets.set(item, reference);
-      return reference;
-    }
-    if (Array.isArray(item)) return Promise.all(item.map((child) => protect(child, "", [...path, "*"])));
-    if (!isRecord(item)) return item;
-    return Object.fromEntries(await Promise.all(Object.entries(item).map(async ([name, child]) => [name, await protect(child, localizationMap(path) ? "" : name, [...path, name])])));
-  }
-  const protectedValue = await protect(value);
-  async function protectEmbedded(item, key = "") {
-    if (documentation(item, key)) return item;
-    if (typeof item === "string" && !isActionSecretReference(item) && maskActionSecrets(item, secrets) !== item) {
-      return store ? store.save(item) : maskActionSecrets(item, secrets);
-    }
-    if (Array.isArray(item)) return Promise.all(item.map((child) => protectEmbedded(child)));
-    if (!isRecord(item)) return item;
-    return Object.fromEntries(await Promise.all(Object.entries(item).map(async ([key2, child]) => [key2, await protectEmbedded(child, key2)])));
-  }
-  return protectEmbedded(protectedValue);
-}
-function maskActionSecretValue(value, secrets) {
-  if (value instanceof Error) return maskActionSecretError(value, secrets);
-  if (typeof value === "string") return maskActionSecrets(value, secrets);
-  if (Array.isArray(value)) return value.map((item) => maskActionSecretValue(item, secrets));
-  if (!isRecord(value)) return value;
-  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskActionSecretValue(item, secrets)]));
-}
-function maskActionSecretError(error, secrets) {
-  if (!(error instanceof Error)) return maskActionSecretValue(error, secrets);
-  const masked = Object.create(Object.getPrototypeOf(error));
-  for (const key of Object.getOwnPropertyNames(error)) {
-    const descriptor = Object.getOwnPropertyDescriptor(error, key);
-    if ("value" in descriptor) descriptor.value = maskActionSecretValue(descriptor.value, secrets);
-    Object.defineProperty(masked, key, descriptor);
-  }
-  return masked;
-}
-var encoder = new TextEncoder();
-function encodeBase64Url(value) {
-  const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
-}
-function encodeJson(value) {
-  return encodeBase64Url(encoder.encode(JSON.stringify(value)));
-}
-async function sha256Base64Url(value) {
-  return encodeBase64Url(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
-}
-function publicJwk(privateJwk) {
-  const { crv, kty, x, y } = privateJwk;
-  if (kty !== "EC" || crv !== "P-256" || !x || !y || !privateJwk.d) {
-    throw new TypeError("A private P-256 JSON Web Key is required for DPoP signing.");
-  }
-  return { crv, kty, x, y };
-}
-function canonicalTargetUrl(value) {
-  const url = new URL(value);
-  return `${url.origin}${url.pathname}`;
-}
-async function calculateDpopJkt(privateJwk) {
-  const jwk = publicJwk(privateJwk);
-  return sha256Base64Url(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y }));
-}
-async function createDpopProof(input2) {
-  const jwk = publicJwk(input2.privateJwk);
-  const key = await crypto.subtle.importKey(
-    "jwk",
-    input2.privateJwk,
-    { name: "ECDSA", namedCurve: "P-256" },
-    false,
-    ["sign"]
-  );
-  const header = encodeJson({ alg: "ES256", typ: "dpop+jwt", jwk });
-  const claims = encodeJson({
-    jti: crypto.randomUUID(),
-    iat: Math.floor(Date.now() / 1e3),
-    htm: input2.method.toUpperCase(),
-    htu: canonicalTargetUrl(input2.targetUrl),
-    ath: await sha256Base64Url(input2.accessToken)
-  });
-  const signature = await crypto.subtle.sign(
-    { name: "ECDSA", hash: "SHA-256" },
-    key,
-    encoder.encode(`${header}.${claims}`)
-  );
-  return `${header}.${claims}.${encodeBase64Url(signature)}`;
-}
 var TOPOLO_FIRST_PARTY_ORIGINS = Object.freeze({
   production: Object.freeze([
     "https://admin.topolo.app",
@@ -1191,83 +977,347 @@ var LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::
 function isRuntimeEnvironment(value) {
   return typeof value === "string" && TOPOLO_RUNTIME_ENVIRONMENTS.includes(value);
 }
-function originIsFirstParty(url, environment) {
-  if (environment === "local") {
-    return (url.protocol === "http:" || url.protocol === "https:") && LOOPBACK_HOSTNAMES.has(url.hostname);
-  }
-  if (url.protocol !== "https:") return false;
-  return FIRST_PARTY_ORIGIN_SETS[environment].has(url.origin);
+function originIsFirstParty(url, environment) {
+  if (environment === "local") {
+    return (url.protocol === "http:" || url.protocol === "https:") && LOOPBACK_HOSTNAMES.has(url.hostname);
+  }
+  if (url.protocol !== "https:") return false;
+  return FIRST_PARTY_ORIGIN_SETS[environment].has(url.origin);
+}
+function requireTopoloRuntimeEnvironment(environment) {
+  if (!isRuntimeEnvironment(environment)) {
+    throw new TopoloSdkError(
+      "environment_required",
+      'Refusing to send a Topolo credential: the runtime environment is not resolved. Pass environment: "production" | "staging" | "development" | "local".'
+    );
+  }
+  return environment;
+}
+function assertTopoloServiceUrlEnvironment(service, value, environment) {
+  const resolved = requireTopoloRuntimeEnvironment(environment);
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TopoloSdkError("invalid_service_url", `Invalid URL configured for Topolo service "${service}".`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password || !originIsFirstParty(url, resolved)) {
+    throw new TopoloSdkError(
+      "environment_mismatch",
+      `Refusing Topolo service "${service}": ${url.origin} is not a first-party ${resolved} service origin.`
+    );
+  }
+  return url.origin;
+}
+function topoloServiceOrigins(serviceUrls, environment) {
+  return Object.fromEntries(
+    Object.entries(serviceUrls ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([service, value]) => [
+      service,
+      assertTopoloServiceUrlEnvironment(service, value, environment)
+    ])
+  );
+}
+var REDIRECT_STATUSES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
+async function fetchWithCredentialBoundary(fetchImpl, environment, service, target, init) {
+  const url = new URL(String(target));
+  const origin = assertTopoloServiceUrlEnvironment(service, url.toString(), environment);
+  const response = await fetchImpl(url.toString(), { ...init, redirect: "manual" });
+  let responseOrigin = origin;
+  try {
+    if (response.url) responseOrigin = new URL(response.url).origin;
+  } catch {
+    responseOrigin = "";
+  }
+  if (response.redirected === true || responseOrigin !== origin) {
+    await response.body?.cancel().catch(() => void 0);
+    throw new TopoloSdkError(
+      "credential_redirect_refused",
+      `Refusing a redirected response from Topolo service "${service}"; credentials are never forwarded.`
+    );
+  }
+  if (REDIRECT_STATUSES.has(response.status)) {
+    const location = response.headers.get("Location");
+    let destination = null;
+    if (location !== null) {
+      try {
+        destination = new URL(location, url).origin;
+      } catch {
+        destination = null;
+      }
+    }
+    if (location !== null && destination !== origin) {
+      await response.body?.cancel().catch(() => void 0);
+      throw new TopoloSdkError(
+        "credential_redirect_refused",
+        `Refusing a redirect from Topolo service "${service}" to another origin; credentials are never forwarded.`
+      );
+    }
+  }
+  return response;
+}
+var MARKETING_ORIGINS = Object.freeze({
+  development: "https://topolo.dev",
+  staging: "https://stg.topolo.us",
+  production: "https://topolo.io"
+});
+function isOnePublicMarketingAction(entry) {
+  return entry.appId === "app_topolo_one" && entry.target === "marketing" && entry.authorizationMode === "public";
+}
+function publicMarketingOrigin(entry, environment) {
+  const selected = requireTopoloRuntimeEnvironment(environment);
+  const origin = selected === "local" ? void 0 : MARKETING_ORIGINS[selected];
+  if (!isOnePublicMarketingAction(entry) || !origin || entry.apiBaseUrl !== origin && entry.apiBaseUrl !== origin + "/") {
+    throw new TopoloSdkError("environment_mismatch", "Public action target does not match the registered application, target and environment.");
+  }
+  return origin;
+}
+async function fetchPublicMarketingAction(fetchImpl, entry, environment, target, init) {
+  const origin = publicMarketingOrigin(entry, environment);
+  if (target.origin !== origin || target.protocol !== "https:" || target.username || target.password || target.port) {
+    throw new TopoloSdkError("service_path_origin_mismatch", "Public action path changes the registered target origin.");
+  }
+  init.signal?.throwIfAborted();
+  const headers = new Headers({
+    Accept: "application/json",
+    "X-Topolo-Action-Id": entry.actionId,
+    "X-Topolo-Action-Name": entry.name
+  });
+  const contentType = new Headers(init.headers).get("Content-Type");
+  if (contentType) headers.set("Content-Type", contentType);
+  const response = await fetchImpl(target.toString(), {
+    method: init.method,
+    headers,
+    body: init.body,
+    signal: init.signal,
+    credentials: "omit",
+    redirect: "manual",
+    referrerPolicy: "no-referrer"
+  });
+  let responseOrigin = origin;
+  try {
+    if (response.url) responseOrigin = new URL(response.url).origin;
+  } catch {
+    responseOrigin = "";
+  }
+  if (response.redirected || responseOrigin !== origin || response.status >= 300 && response.status < 400) {
+    await response.body?.cancel().catch(() => void 0);
+    throw new TopoloSdkError("public_action_redirect_refused", "Public action redirects are refused.");
+  }
+  return response;
+}
+function record2(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function text(value, limit = 512) {
+  return typeof value === "string" && value.trim() ? value.trim().slice(0, limit) : null;
+}
+function strings2(value) {
+  return Array.isArray(value) ? value.slice(0, 8).flatMap((item) => {
+    const result = text(item);
+    return result ? [result] : [];
+  }) : [];
+}
+function pairs(value, first, second) {
+  return Array.isArray(value) ? value.slice(0, 8).flatMap((item) => {
+    if (!record2(item)) return [];
+    const a = text(item[first], 160);
+    const b = text(item[second]);
+    return a && b ? [{ [first]: a, [second]: b }] : [];
+  }) : [];
+}
+function docs(value) {
+  const result = text(value, 2048);
+  if (!result) return null;
+  try {
+    const url = new URL(result);
+    return url.protocol === "https:" && !url.username && !url.password ? url.href : null;
+  } catch {
+    return null;
+  }
+}
+function normalizeApplicationGuide(value) {
+  if (!record2(value) || value.schemaVersion !== 1 || value.source !== "published_application_manifest") return null;
+  const purpose = text(value.purpose, 2048);
+  const gettingStarted = strings2(value.gettingStarted);
+  const docsUrl = docs(value.docsUrl);
+  return {
+    schemaVersion: 1,
+    source: "published_application_manifest",
+    publishedAt: text(value.publishedAt, 160),
+    purpose,
+    problemStatement: text(value.problemStatement, 2048),
+    solutionStatement: text(value.solutionStatement, 2048),
+    benefits: strings2(value.benefits),
+    features: pairs(value.features, "title", "description"),
+    gettingStarted,
+    worksWellWith: pairs(value.worksWellWith, "appId", "reason"),
+    docsUrl,
+    missingFields: [...!purpose ? ["purpose"] : [], ...!docsUrl ? ["docsUrl"] : [], ...!gettingStarted.length ? ["gettingStarted"] : []]
+  };
+}
+function applyAuthHeaders(headers, credential) {
+  if (credential.kind === "api_key") {
+    headers.set("X-Api-Key", credential.apiKey);
+    return;
+  }
+  headers.set("Authorization", `${credential.kind === "dpop_access_token" ? "DPoP" : "Bearer"} ${credential.accessToken}`);
+}
+function applyAuditHeaders(headers, agent, requestId) {
+  headers.set("X-Topolo-Client", `${agent.clientName}/${agent.clientVersion}`);
+  if (agent.agentName) headers.set("X-Topolo-Agent", agent.agentName);
+  headers.set("X-Topolo-Request-Id", requestId);
+}
+function generateRequestId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+var ACTION_SECRET_PREFIX = "topolo-secret:";
+function isActionSecretReference(value) {
+  return typeof value === "string" && value.startsWith(ACTION_SECRET_PREFIX);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sensitive(key, value) {
+  const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+  if (normalized === "capability") {
+    if (typeof value !== "string") return value !== null && value !== void 0 && typeof value !== "boolean" && typeof value !== "number";
+    const text4 = value.trim();
+    return Boolean(text4) && !/^[a-z][a-z0-9_-]{0,31}$/.test(text4);
+  }
+  return ["authorization", "cookie", "setcookie", "proxyauthorization"].includes(normalized) || /(token|secret|password|privatekey|apikey|backupcodes?|recoverycodes?)$/.test(normalized);
+}
+function maskActionSecrets(value, secrets) {
+  let masked = value;
+  for (const [secret, reference] of secrets) {
+    const encoded = encodeURIComponent(secret);
+    const variants = [.../* @__PURE__ */ new Set([secret, encoded])].map((item) => item.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    masked = masked.replace(new RegExp(variants.join("|"), "g"), (match) => match === secret ? reference : encodeURIComponent(reference));
+  }
+  return masked;
+}
+async function resolveActionSecrets(value, store, secrets) {
+  if (isActionSecretReference(value)) {
+    if (!store) throw new TopoloSdkError("action_secret_store_required", "Protected action references require a secret store.");
+    const resolved = await store.load(value);
+    if (typeof resolved !== "string" || !resolved) throw new TopoloSdkError("action_secret_unsupported_type", "Protected action handoff requires a nonempty string credential.");
+    secrets.set(resolved, value);
+    return resolved;
+  }
+  if (Array.isArray(value)) return Promise.all(value.map((item) => resolveActionSecrets(item, store, secrets)));
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, item]) => [key, await resolveActionSecrets(item, store, secrets)])));
+}
+async function protectActionResult(value, store, options = {}) {
+  const secrets = /* @__PURE__ */ new Map();
+  function documentation(item, key) {
+    if (options.preserveActionSchemas === true && ["inputSchema", "outputSchema", "input_schema", "output_schema"].includes(key) && isRecord(item)) return true;
+    if (options.preserveActionContracts === true && ["agentContract", "agent_contract"].includes(key) && isRecord(item)) return true;
+    return options.preserveAgentGuidance === true && key === "agentGuidance" && isRecord(item) && item.schemaVersion === 1 && typeof item.kind === "string" && ["action-guide", "product-guide", "concept"].includes(item.kind);
+  }
+  function localizationMap(path) {
+    const location = path.join("/");
+    if (options.localizationAction === "sources.verify") return location === "data/hashes";
+    if (options.localizationAction === "values.bulk_upsert") return location === "data/sourceHashes";
+    return ["translation.release.prepare", "translation.release.import", "translation.release.get"].includes(options.localizationAction ?? "") && /^data\/bundle\/catalogs\/\*\/(sources|(?:packs|provenance)\/[^/]+)$/.test(location);
+  }
+  async function protect(item, key = "", path = []) {
+    if (documentation(item, key)) return item;
+    if (isActionSecretReference(item)) return item;
+    if (Array.isArray(item) && /(?:backup|recovery)codes$/.test(key.toLowerCase().replace(/[^a-z0-9]/g, ""))) {
+      return Promise.all(item.map((child) => protect(child, key, [...path, "*"])));
+    }
+    if (sensitive(key, item)) {
+      const reference = store ? await store.save(item) : "[REDACTED]";
+      if (typeof item === "string" && item) secrets.set(item, reference);
+      return reference;
+    }
+    if (Array.isArray(item)) return Promise.all(item.map((child) => protect(child, "", [...path, "*"])));
+    if (!isRecord(item)) return item;
+    return Object.fromEntries(await Promise.all(Object.entries(item).map(async ([name, child]) => [name, await protect(child, localizationMap(path) ? "" : name, [...path, name])])));
+  }
+  const protectedValue = await protect(value);
+  async function protectEmbedded(item, key = "") {
+    if (documentation(item, key)) return item;
+    if (typeof item === "string" && !isActionSecretReference(item) && maskActionSecrets(item, secrets) !== item) {
+      return store ? store.save(item) : maskActionSecrets(item, secrets);
+    }
+    if (Array.isArray(item)) return Promise.all(item.map((child) => protectEmbedded(child)));
+    if (!isRecord(item)) return item;
+    return Object.fromEntries(await Promise.all(Object.entries(item).map(async ([key2, child]) => [key2, await protectEmbedded(child, key2)])));
+  }
+  return protectEmbedded(protectedValue);
+}
+function maskActionSecretValue(value, secrets) {
+  if (value instanceof Error) return maskActionSecretError(value, secrets);
+  if (typeof value === "string") return maskActionSecrets(value, secrets);
+  if (Array.isArray(value)) return value.map((item) => maskActionSecretValue(item, secrets));
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskActionSecretValue(item, secrets)]));
+}
+function maskActionSecretError(error, secrets) {
+  if (!(error instanceof Error)) return maskActionSecretValue(error, secrets);
+  const masked = Object.create(Object.getPrototypeOf(error));
+  for (const key of Object.getOwnPropertyNames(error)) {
+    const descriptor = Object.getOwnPropertyDescriptor(error, key);
+    if ("value" in descriptor) descriptor.value = maskActionSecretValue(descriptor.value, secrets);
+    Object.defineProperty(masked, key, descriptor);
+  }
+  return masked;
+}
+var encoder = new TextEncoder();
+function encodeBase64Url(value) {
+  const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function encodeJson(value) {
+  return encodeBase64Url(encoder.encode(JSON.stringify(value)));
 }
-function requireTopoloRuntimeEnvironment(environment) {
-  if (!isRuntimeEnvironment(environment)) {
-    throw new TopoloSdkError(
-      "environment_required",
-      'Refusing to send a Topolo credential: the runtime environment is not resolved. Pass environment: "production" | "staging" | "development" | "local".'
-    );
-  }
-  return environment;
+async function sha256Base64Url(value) {
+  return encodeBase64Url(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
 }
-function assertTopoloServiceUrlEnvironment(service, value, environment) {
-  const resolved = requireTopoloRuntimeEnvironment(environment);
-  let url;
-  try {
-    url = new URL(value);
-  } catch {
-    throw new TopoloSdkError("invalid_service_url", `Invalid URL configured for Topolo service "${service}".`);
-  }
-  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password || !originIsFirstParty(url, resolved)) {
-    throw new TopoloSdkError(
-      "environment_mismatch",
-      `Refusing Topolo service "${service}": ${url.origin} is not a first-party ${resolved} service origin.`
-    );
+function publicJwk(privateJwk) {
+  const { crv, kty, x, y } = privateJwk;
+  if (kty !== "EC" || crv !== "P-256" || !x || !y || !privateJwk.d) {
+    throw new TypeError("A private P-256 JSON Web Key is required for DPoP signing.");
   }
-  return url.origin;
+  return { crv, kty, x, y };
 }
-function topoloServiceOrigins(serviceUrls, environment) {
-  return Object.fromEntries(
-    Object.entries(serviceUrls ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([service, value]) => [
-      service,
-      assertTopoloServiceUrlEnvironment(service, value, environment)
-    ])
-  );
+function canonicalTargetUrl(value) {
+  const url = new URL(value);
+  return `${url.origin}${url.pathname}`;
 }
-var REDIRECT_STATUSES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
-async function fetchWithCredentialBoundary(fetchImpl, environment, service, target, init) {
-  const url = new URL(String(target));
-  const origin = assertTopoloServiceUrlEnvironment(service, url.toString(), environment);
-  const response = await fetchImpl(url.toString(), { ...init, redirect: "manual" });
-  let responseOrigin = origin;
-  try {
-    if (response.url) responseOrigin = new URL(response.url).origin;
-  } catch {
-    responseOrigin = "";
-  }
-  if (response.redirected === true || responseOrigin !== origin) {
-    await response.body?.cancel().catch(() => void 0);
-    throw new TopoloSdkError(
-      "credential_redirect_refused",
-      `Refusing a redirected response from Topolo service "${service}"; credentials are never forwarded.`
-    );
-  }
-  if (REDIRECT_STATUSES.has(response.status)) {
-    const location = response.headers.get("Location");
-    let destination = null;
-    if (location !== null) {
-      try {
-        destination = new URL(location, url).origin;
-      } catch {
-        destination = null;
-      }
-    }
-    if (location !== null && destination !== origin) {
-      await response.body?.cancel().catch(() => void 0);
-      throw new TopoloSdkError(
-        "credential_redirect_refused",
-        `Refusing a redirect from Topolo service "${service}" to another origin; credentials are never forwarded.`
-      );
-    }
-  }
-  return response;
+async function calculateDpopJkt(privateJwk) {
+  const jwk = publicJwk(privateJwk);
+  return sha256Base64Url(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y }));
+}
+async function createDpopProof(input2) {
+  const jwk = publicJwk(input2.privateJwk);
+  const key = await crypto.subtle.importKey(
+    "jwk",
+    input2.privateJwk,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"]
+  );
+  const header = encodeJson({ alg: "ES256", typ: "dpop+jwt", jwk });
+  const claims = encodeJson({
+    jti: crypto.randomUUID(),
+    iat: Math.floor(Date.now() / 1e3),
+    htm: input2.method.toUpperCase(),
+    htu: canonicalTargetUrl(input2.targetUrl),
+    ath: await sha256Base64Url(input2.accessToken)
+  });
+  const signature = await crypto.subtle.sign(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    encoder.encode(`${header}.${claims}`)
+  );
+  return `${header}.${claims}.${encodeBase64Url(signature)}`;
 }
 var APP_API_URLS = {
   auth: "https://auth.topolo.app",
@@ -1668,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;
   }
@@ -1866,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") {
@@ -2140,7 +2190,17 @@ var TopoloClient = class _TopoloClient {
    * use and for the generic `topolo api` / MCP passthrough tool.
    */
   async request(opts) {
+    return this.requestWithTarget(opts);
+  }
+  async requestWithTarget(opts, publicAction) {
     requireTopoloRuntimeEnvironment(this.environment);
+    const publicOrigin = publicAction ? publicMarketingOrigin(publicAction, this.environment) : void 0;
+    if (publicOrigin && (opts.actorEnvelope !== void 0 || opts.resource !== void 0)) {
+      throw new TopoloSdkError("public_action_context_not_supported", "Public marketing actions do not accept actor or resource authority.");
+    }
+    if (publicOrigin && (!opts.path.startsWith("/") || opts.path.startsWith("//") || opts.path.includes("\\"))) {
+      throw new TopoloSdkError("service_path_origin_mismatch", "Public action paths must be origin-relative paths.");
+    }
     const method = opts.method ?? "GET";
     if (this.requireConfirmForWrites && WRITE_METHODS.has(method) && !opts.confirm) {
       throw new TopoloConfirmationRequiredError(
@@ -2149,7 +2209,7 @@ var TopoloClient = class _TopoloClient {
     }
     const actionId = requestActionId(opts.headers);
     const taskId = opts.actorEnvelope?.delegation?.taskId ?? this.actorContext?.taskId;
-    let requestCredential = await this.loadCurrentCredential({
+    let requestCredential = publicOrigin ? void 0 : await this.loadCurrentCredential({
       service: normalizeLookupKey(opts.service),
       method,
       path: opts.path,
@@ -2157,7 +2217,7 @@ var TopoloClient = class _TopoloClient {
       ...taskId ? { taskId } : {},
       ...opts.resource ? { resource: opts.resource } : {}
     });
-    const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: this.validatedServiceOrigin(opts.service, opts.baseUrl) } : await this.resolveRequestService(opts.service);
+    const resolvedService = publicOrigin ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: publicOrigin } : opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: this.validatedServiceOrigin(opts.service, opts.baseUrl) } : await this.resolveRequestService(opts.service);
     const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
     if (url.origin !== new URL(baseUrl).origin) {
@@ -2178,17 +2238,21 @@ var TopoloClient = class _TopoloClient {
     headers.set("Accept", "application/json");
     if (opts.body !== void 0) headers.set("Content-Type", "application/json");
     const platformAppId = resolveConfiguredAppId(resolvedService.serviceKey, this.appIds);
-    if (platformAppId) headers.set("X-App-ID", platformAppId);
-    const actorEnvelope = opts.actorEnvelope === void 0 ? void 0 : parseActorEnvelope(opts.actorEnvelope);
+    if (platformAppId && !publicOrigin) headers.set("X-App-ID", platformAppId);
+    const actorEnvelope = publicOrigin || opts.actorEnvelope === void 0 ? void 0 : parseActorEnvelope(opts.actorEnvelope);
     const requestId = actorEnvelope?.action.requestId ?? generateRequestId();
-    applyAuditHeaders(headers, this.agent, requestId);
-    if (opts.headers) {
+    if (!publicOrigin) applyAuditHeaders(headers, this.agent, requestId);
+    if (publicAction) {
+      headers.set(TOPOLO_ACTION_ID_HEADER, publicAction.actionId);
+      headers.set(TOPOLO_ACTION_NAME_HEADER, publicAction.name);
+    }
+    if (opts.headers && !publicOrigin) {
       for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
     }
     if (actorEnvelope) {
       headers.set(TOPOLO_ACTOR_ENVELOPE_HEADER, encodeActorEnvelopeHeader(actorEnvelope));
     }
-    if (opts.resource) {
+    if (opts.resource && !publicOrigin) {
       const resourceType = opts.resource.resourceType.trim();
       const resourceId = opts.resource.resourceId.trim();
       if (!resourceType || !resourceId) {
@@ -2213,8 +2277,8 @@ var TopoloClient = class _TopoloClient {
       const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
       try {
         const requestHeaders = new Headers(headers);
-        applyAuthHeaders(requestHeaders, requestCredential);
-        if (requestCredential.kind === "dpop_access_token") {
+        if (requestCredential) applyAuthHeaders(requestHeaders, requestCredential);
+        if (requestCredential?.kind === "dpop_access_token") {
           requestHeaders.set("DPoP", await createDpopProof({
             accessToken: requestCredential.accessToken,
             method,
@@ -2222,12 +2286,13 @@ var TopoloClient = class _TopoloClient {
             privateJwk: requestCredential.privateJwk
           }));
         }
-        return await this.credentialedFetch(resolvedService.serviceKey, urlStr, {
+        const init = {
           method,
           headers: requestHeaders,
           body: opts.rawBody ?? (opts.body !== void 0 ? JSON.stringify(opts.body) : null),
           signal
-        });
+        };
+        return publicOrigin ? await fetchPublicMarketingAction((input2, requestInit) => this.fetchImpl(input2, requestInit), publicAction, this.environment, url, init) : await this.credentialedFetch(resolvedService.serviceKey, urlStr, init);
       } catch (error) {
         if (timedOut) {
           throw new TopoloSdkError(
@@ -2235,6 +2300,9 @@ var TopoloClient = class _TopoloClient {
             `Topolo request timed out after ${this.timeoutMs}ms. Verify current state before retrying a mutation.`
           );
         }
+        if (publicOrigin && opts.signal?.aborted) {
+          throw new TopoloSdkError("request_cancelled", "Public action request was cancelled.");
+        }
         throw error;
       } finally {
         clearTimeout(timeoutId);
@@ -2257,7 +2325,7 @@ var TopoloClient = class _TopoloClient {
     try {
       const attemptedCredential = requestCredential;
       res = await fetchWithReadRetry();
-      if (res.status === 401 && attemptedCredential.kind === "access_token" && this.refreshCredential) {
+      if (res.status === 401 && attemptedCredential?.kind === "access_token" && this.refreshCredential) {
         await res.body?.cancel().catch(() => void 0);
         const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
         if (refreshed) {
@@ -2304,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",
@@ -2344,7 +2412,7 @@ var TopoloClient = class _TopoloClient {
           resolvedService.serviceKey,
           opts.path,
           parsed,
-          message3,
+          message2,
           errorContext
         );
       }
@@ -2353,7 +2421,7 @@ var TopoloClient = class _TopoloClient {
         opts.path,
         res.status,
         parsed,
-        message3,
+        message2,
         errorContext
       );
     }
@@ -2411,6 +2479,9 @@ var TopoloClient = class _TopoloClient {
     return fetchWithCredentialBoundary((input2, requestInit) => this.fetchImpl(input2, requestInit), this.environment, service, target, init);
   }
   validatedActionEntry(entry) {
+    if (isOnePublicMarketingAction(entry)) {
+      return { ...entry, apiBaseUrl: publicMarketingOrigin(entry, this.environment) };
+    }
     if (!entry.apiBaseUrl) return entry;
     return {
       ...entry,
@@ -2652,7 +2723,7 @@ var TopoloClient = class _TopoloClient {
         "TopoloAuth did not return an action catalog for the current credential."
       );
     }
-    const entries = raw.map((item) => normalizeActionCatalogEntry(item)).filter((entry) => Boolean(entry)).map((entry) => this.validatedActionEntry(entry));
+    const entries = raw.map((item) => normalizeActionCatalogEntry(item)).filter((entry) => Boolean(entry));
     return {
       actions: entries,
       page: normalizeCatalogPage(
@@ -2717,11 +2788,18 @@ var TopoloClient = class _TopoloClient {
     const raw = res.data?.action ?? res.action;
     const match = normalizeActionCatalogEntry(raw);
     if (!match) throw new TopoloSdkError("unknown_action", `Unknown or unavailable Topolo action "${action}".`);
+    if (isOnePublicMarketingAction(match) && match.actionId !== actionId) {
+      throw new TopoloSdkError("action_contract_mismatch", "Public action catalog response does not match the requested action ID.");
+    }
     return this.validatedActionEntry(match);
   }
   async callAction(action, input2 = {}, options = {}) {
-    const entry = await this.getAction(action);
-    return this.executeResolvedAction(entry, input2, options);
+    const entry = Object.freeze({ ...await this.getAction(action) });
+    const publicAction = isOnePublicMarketingAction(entry);
+    if (publicAction && entry.actionId !== action.trim()) {
+      throw new TopoloSdkError("action_contract_mismatch", "Public action catalog response does not match the requested action ID.");
+    }
+    return this.executeResolvedAction(entry, input2, options, false, publicAction);
   }
   async issueExternalAgentCredential(input2) {
     const actionId = "app_topolo_auth.principal_credentials.issue";
@@ -2865,7 +2943,15 @@ var TopoloClient = class _TopoloClient {
     }
     return this.executeResolvedAction(entry, input2, options);
   }
-  async executeResolvedAction(entry, input2, options, preserveSensitiveResult = false) {
+  async executeResolvedAction(entry, input2, options, preserveSensitiveResult = false, allowPublicMarketing = false) {
+    if (isOnePublicMarketingAction(entry)) {
+      if (!allowPublicMarketing) {
+        throw new TopoloSdkError("public_action_entrypoint_required", "Public marketing actions require callAction.");
+      }
+      if (options.actorEnvelope !== void 0 || options.resource !== void 0) {
+        throw new TopoloSdkError("public_action_context_not_supported", "Public marketing actions do not accept actor or resource authority.");
+      }
+    }
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     if (agentAccess === "off") {
       throw new TopoloPermissionError(
@@ -2894,7 +2980,8 @@ var TopoloClient = class _TopoloClient {
       );
     }
     const mapped = mapActionInput(entry, input2);
-    const resolvedActorEnvelope = options.actorEnvelope ?? await this.buildVerifiedAgentActorEnvelope(entry.actionId, input2, options.resource);
+    const publicAction = isOnePublicMarketingAction(entry);
+    const resolvedActorEnvelope = publicAction ? void 0 : options.actorEnvelope ?? await this.buildVerifiedAgentActorEnvelope(entry.actionId, input2, options.resource);
     if (resolvedActorEnvelope) {
       const actorEnvelope = parseActorEnvelope(resolvedActorEnvelope);
       if (actorEnvelope.action.actionId !== entry.actionId) {
@@ -2911,8 +2998,9 @@ var TopoloClient = class _TopoloClient {
     const service = entry.appSlug || entry.appId;
     let result;
     try {
-      result = await this.request({
+      result = await this.requestWithTarget({
         service,
+        signal: options.signal,
         ...entry.apiBaseUrl ? { baseUrl: entry.apiBaseUrl } : {},
         method: entry.method,
         path: mapped.path,
@@ -2925,7 +3013,7 @@ var TopoloClient = class _TopoloClient {
           [TOPOLO_ACTION_NAME_HEADER]: entry.name
         },
         confirm: options.confirm === true || entry.readOnly && !entry.destructive && !entry.requiresConfirmation
-      });
+      }, publicAction ? entry : void 0);
     } catch (error) {
       throw maskActionSecretError(error, this.actionSecrets);
     }
@@ -4321,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";
@@ -4338,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;
   }
@@ -4460,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;
@@ -4559,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 } : {} };
 }
@@ -4580,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);
     }
   }
@@ -4590,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);
       }
     }
@@ -4625,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;
@@ -4648,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);
@@ -4657,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 });
   }
@@ -6199,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 }
     );
   }
@@ -7977,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;
   }
@@ -8798,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";
 
@@ -8813,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",
@@ -8862,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("-");
@@ -8883,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;
@@ -8908,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),
@@ -8916,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"
       }];
@@ -9001,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");
@@ -9011,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;
@@ -9029,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 {
@@ -9052,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));
 }
@@ -9310,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
@@ -9356,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 = {};
@@ -9398,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);
@@ -9457,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") : "";
@@ -9474,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/);
@@ -9534,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) {
@@ -9543,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 };
@@ -9562,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;
@@ -9579,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 + ".");
     }
@@ -9587,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);
     }
   }
 }
@@ -9622,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("-");
@@ -9635,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}`;
@@ -9732,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 {
@@ -9743,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;
   }
 }
@@ -9751,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.`);
   }
@@ -9780,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 {
@@ -9794,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"];
@@ -9808,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 = {};
@@ -9903,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);
@@ -10085,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,
@@ -10106,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
@@ -10119,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;
 }
@@ -10177,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 } : {}
     };
   }
 }
@@ -10263,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);
     }
@@ -10275,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();
@@ -10325,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,
@@ -10369,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(" ");
@@ -10388,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
@@ -10439,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) {
@@ -10456,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;
@@ -10464,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 });
@@ -10481,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;
@@ -10511,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
@@ -10648,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);
@@ -11234,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";
@@ -11245,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 ?? "");