@topolo/cli 0.13.12 → 0.13.15

package/dist/index.js

@@ -269,8 +269,8 @@ function generateRequestId() {
 }
 var TopoloSdkError = class extends Error {
   code;
-  constructor(code, message2) {
-    super(message2);
+  constructor(code, message3) {
+    super(message3);
     this.name = "TopoloSdkError";
     this.code = code;
   }
@@ -391,8 +391,8 @@ var TopoloAuthError = class extends TopoloSdkError {
   requestId;
   retryAfter;
   details;
-  constructor(message2, code = "auth_error", options = {}) {
-    super(canonicalTopoloServiceErrorCode(code) ?? "auth_error", message2);
+  constructor(message3, code = "auth_error", options = {}) {
+    super(canonicalTopoloServiceErrorCode(code) ?? "auth_error", message3);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
@@ -414,10 +414,10 @@ var TopoloPermissionError = class extends TopoloSdkError {
   requestId;
   retryAfter;
   details;
-  constructor(message2, required, options = {}) {
+  constructor(message3, required, options = {}) {
     super(
       canonicalTopoloServiceErrorCode(options.code) ?? serviceErrorCode(options.body, "permission_denied"),
-      message2
+      message3
     );
     this.name = "TopoloPermissionError";
     this.required = canonicalTopoloRequired(required);
@@ -458,8 +458,8 @@ function extractTopoloServiceErrorMessage(body) {
   candidates.push(record4.message, record4.error_description);
   if (typeof nested === "string" && !canonicalTopoloServiceErrorCode(nested)) candidates.push(nested);
   for (const candidate of candidates) {
-    const message2 = sanitizeTopoloServiceMessage(candidate);
-    if (message2) return message2;
+    const message3 = sanitizeTopoloServiceMessage(candidate);
+    if (message3) return message3;
   }
   return void 0;
 }
@@ -533,8 +533,8 @@ function validationIssueDetails(issues) {
   }
   return paths.length ? { paths, issues } : { issues };
 }
-function issue(path, message2) {
-  const text3 = sanitizeTopoloServiceMessage(message2);
+function issue(path, message3) {
+  const text3 = sanitizeTopoloServiceMessage(message3);
   if (!path && !text3) return null;
   return { ...path ? { path } : {}, ...text3 ? { message: text3 } : {} };
 }
@@ -554,8 +554,8 @@ function canonicalTopoloValidationIssues(values) {
 function flattenedValidationIssues(formErrors, fieldErrors) {
   const issues = [];
   if (Array.isArray(formErrors)) {
-    for (const message2 of formErrors) {
-      const projected = issue(void 0, message2);
+    for (const message3 of formErrors) {
+      const projected = issue(void 0, message3);
       if (projected) issues.push(projected);
     }
   }
@@ -564,8 +564,8 @@ function flattenedValidationIssues(formErrors, fieldErrors) {
       const path = canonicalTopoloValidationPath(key);
       if (!path) continue;
       const list = Array.isArray(messages) && messages.length ? messages : [void 0];
-      for (const message2 of list) {
-        const projected = issue(path, message2);
+      for (const message3 of list) {
+        const projected = issue(path, message3);
         if (projected) issues.push(projected);
       }
     }
@@ -645,8 +645,8 @@ function topoloErrorHint(error) {
   return void 0;
 }
 var TopoloConfirmationRequiredError = class extends TopoloSdkError {
-  constructor(message2) {
-    super("confirmation_required", message2);
+  constructor(message3) {
+    super("confirmation_required", message3);
     this.name = "TopoloConfirmationRequiredError";
   }
 };
@@ -658,8 +658,8 @@ var TopoloHttpError = class extends TopoloSdkError {
   requestId;
   retryAfter;
   details;
-  constructor(service, path, status, body, message2, options = {}) {
-    super(serviceErrorCode(body, "http_error"), message2 ?? `HTTP ${status} from ${service}${path}`);
+  constructor(service, path, status, body, message3, options = {}) {
+    super(serviceErrorCode(body, "http_error"), message3 ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
@@ -681,8 +681,8 @@ function topoloRetryAfterSeconds(value, now = Date.now()) {
 var TopoloRateLimitError = class extends TopoloHttpError {
   retryable = true;
   retryAfterSeconds;
-  constructor(service, path, body, message2, options = {}) {
-    super(service, path, 429, body, message2, options);
+  constructor(service, path, body, message3, options = {}) {
+    super(service, path, 429, body, message3, options);
     this.name = "TopoloRateLimitError";
     if (this.code === "http_error") this.code = "rate_limited";
     this.retryAfterSeconds = topoloRetryAfterSeconds(this.retryAfter);
@@ -1262,8 +1262,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, message2) {
-    super(`${path}: ${message2}`);
+  constructor(path, message3) {
+    super(`${path}: ${message3}`);
     this.name = "ActorEnvelopeValidationError";
     this.path = path;
   }
@@ -1380,8 +1380,8 @@ function parseAccountableSubject(value) {
 }
 async function sha256CanonicalValue(value) {
   const bytes = new TextEncoder().encode(canonicalJson(value));
-  const digest = await crypto.subtle.digest("SHA-256", bytes);
-  return `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+  const digest2 = await crypto.subtle.digest("SHA-256", bytes);
+  return `sha256:${Array.from(new Uint8Array(digest2), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
 }
 function parseIdentity(value, path) {
   const identity = record2(value, path);
@@ -1460,8 +1460,8 @@ function textArray(value, path) {
 function optionalTextFields(value, path, keys) {
   return Object.fromEntries(keys.flatMap((key) => value[key] === void 0 ? [] : [[key, text(value[key], `${path}.${key}`)]]));
 }
-function fail(path, message2) {
-  throw new ActorEnvelopeValidationError(path, message2);
+function fail(path, message3) {
+  throw new ActorEnvelopeValidationError(path, message3);
 }
 function parseTopoloActionUploadContract(value) {
   if (!isRecord3(value) || value.profile !== "inline-base64" && value.profile !== "url-session") {
@@ -1897,7 +1897,7 @@ var TopoloClient = class _TopoloClient {
     }
     if (!res.ok) {
       const durationMs = Date.now() - startedAt;
-      const message2 = describeError(parsed, `HTTP ${res.status}`);
+      const message3 = describeError(parsed, `HTTP ${res.status}`);
       const publicCode = extractTopoloServiceErrorCode(parsed) ?? "http_error";
       this.emit({
         phase: "error",
@@ -1937,7 +1937,7 @@ var TopoloClient = class _TopoloClient {
           resolvedService.serviceKey,
           opts.path,
           parsed,
-          message2,
+          message3,
           errorContext
         );
       }
@@ -1946,7 +1946,7 @@ var TopoloClient = class _TopoloClient {
         opts.path,
         res.status,
         parsed,
-        message2,
+        message3,
         errorContext
       );
     }
@@ -3902,8 +3902,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, message2) {
-    super(message2);
+  constructor(code, message3) {
+    super(message3);
     this.name = "TopoloSdkError";
     this.code = code;
   }
@@ -4024,8 +4024,8 @@ var TopoloAuthError2 = class extends TopoloSdkError2 {
   requestId;
   retryAfter;
   details;
-  constructor(message2, code = "auth_error", options = {}) {
-    super(canonicalTopoloServiceErrorCode2(code) ?? "auth_error", message2);
+  constructor(message3, code = "auth_error", options = {}) {
+    super(canonicalTopoloServiceErrorCode2(code) ?? "auth_error", message3);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
@@ -4123,8 +4123,8 @@ function validationIssueDetails2(issues) {
   }
   return paths.length ? { paths, issues } : { issues };
 }
-function issue2(path, message2) {
-  const text2 = sanitizeTopoloServiceMessage2(message2);
+function issue2(path, message3) {
+  const text2 = sanitizeTopoloServiceMessage2(message3);
   if (!path && !text2) return null;
   return { ...path ? { path } : {}, ...text2 ? { message: text2 } : {} };
 }
@@ -4144,8 +4144,8 @@ function canonicalTopoloValidationIssues2(values) {
 function flattenedValidationIssues2(formErrors, fieldErrors) {
   const issues = [];
   if (Array.isArray(formErrors)) {
-    for (const message2 of formErrors) {
-      const projected = issue2(void 0, message2);
+    for (const message3 of formErrors) {
+      const projected = issue2(void 0, message3);
       if (projected) issues.push(projected);
     }
   }
@@ -4154,8 +4154,8 @@ function flattenedValidationIssues2(formErrors, fieldErrors) {
       const path = canonicalTopoloValidationPath2(key);
       if (!path) continue;
       const list = Array.isArray(messages) && messages.length ? messages : [void 0];
-      for (const message2 of list) {
-        const projected = issue2(path, message2);
+      for (const message3 of list) {
+        const projected = issue2(path, message3);
         if (projected) issues.push(projected);
       }
     }
@@ -4189,8 +4189,8 @@ var TopoloHttpError2 = class extends TopoloSdkError2 {
   requestId;
   retryAfter;
   details;
-  constructor(service, path, status, body, message2, options = {}) {
-    super(serviceErrorCode2(body, "http_error"), message2 ?? `HTTP ${status} from ${service}${path}`);
+  constructor(service, path, status, body, message3, options = {}) {
+    super(serviceErrorCode2(body, "http_error"), message3 ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
@@ -4212,8 +4212,8 @@ function topoloRetryAfterSeconds2(value, now = Date.now()) {
 var TopoloRateLimitError2 = class extends TopoloHttpError2 {
   retryable = true;
   retryAfterSeconds;
-  constructor(service, path, body, message2, options = {}) {
-    super(service, path, 429, body, message2, options);
+  constructor(service, path, body, message3, options = {}) {
+    super(service, path, 429, body, message3, options);
     this.name = "TopoloRateLimitError";
     if (this.code === "http_error") this.code = "rate_limited";
     this.retryAfterSeconds = topoloRetryAfterSeconds2(this.retryAfter);
@@ -4221,8 +4221,8 @@ var TopoloRateLimitError2 = class extends TopoloHttpError2 {
 };
 var TopoloReauthRequiredError = class extends TopoloAuthError2 {
   reauthorization;
-  constructor(message2, reauthorization, options = {}) {
-    super(message2, "reauth_required", { status: 401, service: "auth", path: "/api/developer-oauth/token", ...options });
+  constructor(message3, reauthorization, options = {}) {
+    super(message3, "reauth_required", { status: 401, service: "auth", path: "/api/developer-oauth/token", ...options });
     this.name = "TopoloReauthRequiredError";
     this.reauthorization = Object.freeze({ ...reauthorization });
   }
@@ -5228,12 +5228,12 @@ function renewalFailure(error) {
   if (error instanceof ConfigOwnershipError) return new ConfigOwnershipError();
   if (error instanceof TopoloReauthRequiredError) return error;
   if ((error instanceof TopoloAuthError2 || error instanceof TopoloHttpError2) && error.status === 429) {
-    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.";
+    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.";
     return new TopoloRateLimitError2(
       "auth",
       path,
-      { code: "rate_limited", retryable: true, message: message2 },
-      message2,
+      { code: "rate_limited", retryable: true, message: message3 },
+      message3,
       { requestId: error.requestId, retryAfter: error.retryAfter }
     );
   }
@@ -6520,6 +6520,363 @@ function formatActionPlan(plan) {
   return lines.join("\n");
 }
 
+// src/lib/credential-custody.ts
+import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
+import { constants as constants2 } from "fs";
+import { chmod as chmod3, lstat as lstat2, mkdir as mkdir3, open, rename as rename2, rm as rm2 } from "fs/promises";
+import { basename as basename2, isAbsolute, join as join5, normalize, sep } from "path";
+var CUSTODY_SCHEMA_VERSION = 1;
+var CUSTODY_API_KEY_FILE = "api-key.json";
+var CUSTODY_METADATA_FILE = "custody.json";
+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);
+    this.name = "CustodyError";
+    this.code = code;
+  }
+};
+async function writeCredentialCustody(request, deps) {
+  if (request.confirm !== true) {
+    throw new CustodyError(
+      "custody_confirmation_required",
+      "Writing a credential into custody requires --confirm. The custody file will hold the plaintext key."
+    );
+  }
+  const appId = requiredText(request.appId, "--app");
+  const apiKeyId = requiredText(request.apiKeyId, "--api-key-id");
+  const platform4 = deps.platform ?? process.platform;
+  const uid = deps.uid === void 0 ? currentUid() : deps.uid;
+  if (platform4 === "win32" || uid === null) {
+    throw new CustodyError("custody_platform_unsupported", "Credential custody files require POSIX ownership and permissions.");
+  }
+  const directory = custodyDirectory(request.outDir);
+  const leaf = basename2(directory);
+  if (CUSTODY_ENVIRONMENT_NAMES.includes(leaf) && leaf !== deps.environment) {
+    throw new CustodyError(
+      "custody_environment_mismatch",
+      `--out names the ${leaf} environment but the credential is for ${deps.environment}.`
+    );
+  }
+  await ensureCustodyDirectory(directory, uid);
+  const apiKeyPath = join5(directory, CUSTODY_API_KEY_FILE);
+  const custodyPath = join5(directory, CUSTODY_METADATA_FILE);
+  const existing = [await destinationExists(apiKeyPath), await destinationExists(custodyPath)];
+  if (existing.some(Boolean) && request.replace !== true) {
+    throw new CustodyError(
+      "custody_file_exists",
+      `Custody files already exist in ${directory}. Pass --replace to overwrite them.`
+    );
+  }
+  const identity = await deps.identity();
+  const organizationId = identity.organization?.id;
+  if (!organizationId) {
+    throw new CustodyError(
+      "custody_organization_required",
+      "Credential custody requires an organization context. Pin one with TOPOLO_CONTEXT=org:<organizationId>."
+    );
+  }
+  const key = findListedKey(await deps.listApiKeys(appId), apiKeyId);
+  assertKeyUsable(key, appId, organizationId, (deps.now ?? Date.now)());
+  const secret = await deps.store.load(request.reference);
+  if (typeof secret !== "string" || !secret || /\s/.test(secret)) {
+    throw new CustodyError(
+      "custody_secret_unsupported_type",
+      "The protected reference does not hold a single API key string."
+    );
+  }
+  try {
+    await assertSecretIsKey(deps.introspectKey, secret, key);
+    const custody = {
+      schemaVersion: CUSTODY_SCHEMA_VERSION,
+      appId: key.appId,
+      scopes: [...key.scopes],
+      organizationId: key.organizationId,
+      environment: deps.environment,
+      apiKeyId: key.id,
+      expiresAt: key.expiresAt,
+      keyDigest: `sha256:${createHash3("sha256").update(secret, "utf8").digest("hex")}`,
+      createdAt: key.createdAt
+    };
+    await writeCustodyFiles(directory, [
+      [CUSTODY_API_KEY_FILE, `${JSON.stringify({ schemaVersion: CUSTODY_SCHEMA_VERSION, apiKey: secret })}
+`],
+      [CUSTODY_METADATA_FILE, `${JSON.stringify(custody, null, 2)}
+`]
+    ]);
+    try {
+      await deps.store.delete(request.reference);
+    } catch {
+      throw new CustodyError(
+        "custody_reference_release_failed",
+        `Custody files were written to ${directory}, but the local protected reference could not be deleted. Run \`topolo actions release-secret <reference> --confirm\`.`
+      );
+    }
+    return {
+      written: true,
+      replaced: existing.some(Boolean),
+      directory,
+      files: { apiKey: apiKeyPath, custody: custodyPath },
+      custody,
+      reference: { released: true, upstreamRevoked: false }
+    };
+  } catch (error) {
+    throw withheldIfSecretLeaks(error, secret);
+  }
+}
+function requiredText(value, flag) {
+  const text2 = value?.trim();
+  if (!text2) throw new CustodyError("custody_invalid_input", `${flag} is required.`);
+  return text2;
+}
+function currentUid() {
+  return typeof process.getuid === "function" ? process.getuid() : null;
+}
+function custodyDirectory(value) {
+  const raw = value?.trim();
+  if (!raw || !isAbsolute(raw)) {
+    throw new CustodyError("custody_path_not_absolute", "--out must be an absolute directory path.");
+  }
+  const normalized = normalize(raw);
+  const directory = normalized.endsWith(sep) ? normalized.slice(0, -1) : normalized;
+  if (!directory) {
+    throw new CustodyError("custody_dir_insecure", "--out must name a dedicated directory, not the filesystem root.");
+  }
+  return directory;
+}
+async function lstatOrNull(path) {
+  try {
+    return await lstat2(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function ensureCustodyDirectory(directory, uid) {
+  const components = directory.split(sep).filter(Boolean);
+  let current = sep;
+  assertSecureAncestor(current, await lstat2(current), uid);
+  for (let index = 0; index < components.length; index += 1) {
+    current = join5(current, components[index]);
+    const last = index === components.length - 1;
+    let stats = await lstatOrNull(current);
+    if (!stats) {
+      await mkdir3(current, { mode: 448 });
+      await chmod3(current, 448);
+      stats = await lstat2(current);
+    }
+    if (stats.isSymbolicLink()) {
+      throw new CustodyError("custody_path_symlink", `Custody path component ${current} is a symbolic link.`);
+    }
+    if (!stats.isDirectory()) {
+      throw new CustodyError("custody_path_not_directory", `Custody path component ${current} is not a directory.`);
+    }
+    if (last) assertPrivateDirectory(current, stats, uid);
+    else assertSecureAncestor(current, stats, uid);
+  }
+}
+function assertPrivateDirectory(path, stats, uid) {
+  if (stats.uid !== uid || (stats.mode & 511) !== 448) {
+    throw new CustodyError(
+      "custody_dir_insecure",
+      `Custody directory ${path} must be owned by the current user with mode 0700.`
+    );
+  }
+}
+function assertSecureAncestor(path, stats, uid) {
+  const rootSticky = stats.uid === 0 && (stats.mode & 512) !== 0;
+  if (stats.uid !== 0 && stats.uid !== uid || (stats.mode & 18) !== 0 && !rootSticky) {
+    throw new CustodyError(
+      "custody_parent_insecure",
+      `Custody parent ${path} must be owned by root or the current user and must not be group- or world-writable.`
+    );
+  }
+}
+async function destinationExists(path) {
+  const stats = await lstatOrNull(path);
+  if (!stats) return false;
+  if (stats.isSymbolicLink()) {
+    throw new CustodyError("custody_path_symlink", `Custody file ${path} is a symbolic link.`);
+  }
+  if (!stats.isFile()) {
+    throw new CustodyError("custody_path_not_regular", `Custody file ${path} is not a regular file.`);
+  }
+  return true;
+}
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function findListedKey(result, apiKeyId) {
+  const data = isRecord5(result) && isRecord5(result.data) ? result.data : result;
+  const keys = isRecord5(data) ? data.keys : void 0;
+  if (!Array.isArray(keys)) {
+    throw new CustodyError("custody_metadata_unavailable", "Auth api_keys.list did not return a key inventory.");
+  }
+  const match = keys.find((key) => isRecord5(key) && key.id === apiKeyId);
+  if (!match) {
+    throw new CustodyError(
+      "custody_key_not_found",
+      `API key ${apiKeyId} is not visible to this credential in api_keys.list.`
+    );
+  }
+  const { id, appId, organizationId, scopes, expiresAt, createdAt, status } = match;
+  if (typeof id !== "string" || typeof appId !== "string" || typeof organizationId !== "string" || !Array.isArray(scopes) || !scopes.every((scope) => typeof scope === "string") || !(expiresAt === null || typeof expiresAt === "number") || typeof createdAt !== "number" || typeof status !== "string") {
+    throw new CustodyError("custody_metadata_unavailable", `Auth returned incomplete metadata for API key ${apiKeyId}.`);
+  }
+  return { id, appId, organizationId, scopes, expiresAt, createdAt, status };
+}
+function assertKeyUsable(key, appId, organizationId, nowMs) {
+  if (key.appId !== appId) {
+    throw new CustodyError("custody_app_mismatch", `API key ${key.id} belongs to ${key.appId}, not ${appId}.`);
+  }
+  if (key.organizationId !== organizationId) {
+    throw new CustodyError(
+      "custody_organization_mismatch",
+      `API key ${key.id} belongs to another organization than the verified credential.`
+    );
+  }
+  if (key.status !== "active") {
+    throw new CustodyError("custody_key_inactive", `API key ${key.id} is ${key.status}, not active.`);
+  }
+  if (key.expiresAt !== null && key.expiresAt * 1e3 <= nowMs) {
+    throw new CustodyError("custody_key_expired", `API key ${key.id} has expired.`);
+  }
+}
+async function assertSecretIsKey(introspectKey, secret, key) {
+  let identity;
+  try {
+    identity = await introspectKey(secret);
+  } catch (error) {
+    const code = error.code;
+    const status = error.status;
+    const detail = [typeof code === "string" ? code : null, typeof status === "number" ? `HTTP ${status}` : null].filter(Boolean).join(", ");
+    throw new CustodyError(
+      "custody_key_verification_failed",
+      `Auth could not verify the protected key${detail ? ` (${detail})` : ""}. Nothing was written.`
+    );
+  }
+  if (identity.kind !== "api_key" || identity.apiKey?.id !== key.id || identity.apiKey.appId !== key.appId || identity.organization?.id !== key.organizationId) {
+    throw new CustodyError(
+      "custody_key_mismatch",
+      `The protected reference does not hold API key ${key.id} for ${key.appId}. Nothing was written.`
+    );
+  }
+  const introspected = [...identity.apiKey.scopes].sort();
+  const listed = [...key.scopes].sort();
+  if (introspected.length !== listed.length || introspected.some((scope, index) => scope !== listed[index])) {
+    throw new CustodyError(
+      "custody_metadata_mismatch",
+      `Auth introspection and api_keys.list disagree on the scopes of API key ${key.id}. Nothing was written.`
+    );
+  }
+}
+async function writeCustodyFiles(directory, files) {
+  const staged = [];
+  try {
+    for (const [name, content] of files) {
+      const temporary = join5(directory, `.${name}.${process.pid}.${randomUUID3()}.tmp`);
+      staged.push([temporary, join5(directory, name)]);
+      const handle = await open(
+        temporary,
+        constants2.O_WRONLY | constants2.O_CREAT | constants2.O_EXCL | constants2.O_NOFOLLOW,
+        384
+      );
+      try {
+        await handle.chmod(384);
+        await handle.writeFile(content, "utf8");
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+    }
+    for (const [temporary, destination] of staged) await rename2(temporary, destination);
+  } finally {
+    await Promise.all(staged.map(([temporary]) => rm2(temporary, { force: true })));
+  }
+}
+function withheldIfSecretLeaks(error, secret) {
+  const variants = [secret, encodeURIComponent(secret)];
+  const record3 = error;
+  const parts = [String(error), String(record3?.message), String(record3?.stack)];
+  for (const value of [record3?.body, record3?.details]) {
+    try {
+      parts.push(String(value), JSON.stringify(value ?? null));
+    } catch {
+    }
+  }
+  if (!parts.some((part) => variants.some((variant) => part.includes(variant)))) return error;
+  return new CustodyError(
+    "custody_error_withheld",
+    "Credential custody failed; the underlying error was withheld because it referenced the protected credential."
+  );
+}
+
+// src/commands/credentials.ts
+function registerCredentialsCommand(program2) {
+  const credentials = program2.command("credentials").description("Move protected credentials into operator-owned custody without displaying them");
+  credentials.command("write-custody <reference>").description(
+    "Write the API key behind a protected topolo-secret reference into a 0700 custody directory, then delete the reference"
+  ).option("--out <dir>", "Absolute custody directory (created 0700, or an existing 0700 directory you own)").option("--app <appId>", "Application id the key must belong to").option("--api-key-id <id>", "Auth API key id the reference must hold (data.key.id from api_keys.create)").option("--confirm", "Acknowledge writing the plaintext key to disk").option("--replace", "Atomically replace existing custody files").option("--json", "Output JSON").option("--no-json", "Output human-readable text").addHelpText(
+    "after",
+    '\nThe reference is resolved through the same OS protected store that `actions call` and the stdio MCP use,\nbound to the verified principal, organization, API key identity and environment. Key metadata is read back\nfrom Auth api_keys.list and the key is verified by Auth introspection before anything is written.\nWrites api-key.json ({"schemaVersion":1,"apiKey":...}) and custody.json (metadata plus sha256 keyDigest),\nboth 0600 via temporary file and rename. Output never contains the key. Deleting the local reference does\nnot revoke the upstream key; use app_topolo_auth.api_keys.revoke for that.\nKeep one key per environment with --out <dir>/<environment>; a directory named after an environment must\nmatch the credential environment (topolo --env <environment>).'
+  ).action(async (reference, opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const environment = selectedEnvironment();
+      let client;
+      const topolo = () => client ??= buildClient({ environment }).then((built) => {
+        if (!built) throw new Error("No credential configured. Run `topolo auth login`.");
+        return built;
+      });
+      let verified;
+      const identity = () => verified ??= topolo().then((built) => built.client.introspect());
+      const result = await writeCredentialCustody(
+        {
+          reference,
+          outDir: opts.out,
+          appId: opts.app,
+          apiKeyId: opts.apiKeyId,
+          confirm: opts.confirm === true,
+          replace: opts.replace === true
+        },
+        {
+          environment,
+          identity,
+          store: createProtectedActionSecretStore({ environment, identity }),
+          listApiKeys: async (appId) => (await topolo()).client.readAction(API_KEYS_LIST_ACTION, { appId }),
+          introspectKey: async (secret) => {
+            const profile = resolvedProfileConfig(await readConfig(), environment);
+            return createTopolo({
+              credential: { kind: "api_key", apiKey: secret },
+              environment,
+              agent: { clientName: "topolo-cli", clientVersion: CLI_VERSION },
+              serviceUrls: profile.serviceUrls
+            }).client.introspect();
+          }
+        }
+      );
+      emit(result, mode, () => formatCustodyResult(result));
+    } catch (error) {
+      fail2(error, mode);
+    }
+  });
+}
+function formatCustodyResult(result) {
+  return [
+    `${result.replaced ? "Replaced" : "Wrote"} credential custody in ${result.directory}`,
+    `API key file:  ${result.files.apiKey} (0600)`,
+    `Custody file:  ${result.files.custody} (0600)`,
+    `Key:           ${result.custody.apiKeyId} (${result.custody.appId}, ${result.custody.environment})`,
+    `Organization:  ${result.custody.organizationId}`,
+    `Scopes:        ${result.custody.scopes.join(", ") || "-"}`,
+    `Expires at:    ${result.custody.expiresAt === null ? "never" : new Date(result.custody.expiresAt * 1e3).toISOString()}`,
+    `Digest:        ${result.custody.keyDigest}`,
+    "Local protected reference released. The upstream key is NOT revoked; use app_topolo_auth.api_keys.revoke for that."
+  ].join("\n");
+}
+
 // src/commands/apps-public.ts
 function publicApplicationRows(catalog) {
   return catalog.filter((entry) => entry.launchable || entry.surfaceKind === "application").map((entry) => ({
@@ -6809,7 +7166,7 @@ function normalizeList(values, fallback = []) {
 
 // src/commands/integrations.ts
 import { readdir as readdir3, readFile as readFile3, stat } from "fs/promises";
-import { join as join5, relative } from "path";
+import { join as join6, relative } from "path";
 function registerIntegrationsCommand(program2) {
   const integrations = program2.command("integrations").description("Generate and validate Topolo integration handoffs.");
   integrations.command("prompt").description("Print an agent prompt for adding a Topolo integration.").argument("<integration>", "Integration prompt id, currently login-with-topolo").option("--framework <framework>", "auto, authjs, express, or generic", "auto").option("--json", "Emit JSON output").action((integration, options) => {
@@ -6952,7 +7309,7 @@ function detectFramework(packageJson, haystack) {
 }
 async function readPackageJson(repoRoot) {
   try {
-    return JSON.parse(await readFile3(join5(repoRoot, "package.json"), "utf8"));
+    return JSON.parse(await readFile3(join6(repoRoot, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -6964,7 +7321,7 @@ async function collectFiles(repoRoot) {
     if (result.length > 2e3) return;
     const entries = await readdir3(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join5(dir, entry.name);
+      const fullPath = join6(dir, entry.name);
       if (entry.isDirectory()) {
         if ([".git", "node_modules", "dist", "build", ".next", "coverage"].includes(entry.name)) continue;
         await walk(fullPath);
@@ -6991,11 +7348,11 @@ function formatCheckResult(result) {
 }
 
 // src/commands/skills.ts
-import { spawnSync as spawnSync4 } from "child_process";
+import { spawnSync as spawnSync5 } from "child_process";
 import { existsSync as existsSync6 } from "fs";
-import { readFile as readFile6, rm as rm2 } from "fs/promises";
+import { readFile as readFile9, rm as rm3 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { dirname as dirname6, join as join7, resolve as resolve3 } from "path";
+import { dirname as dirname7, join as join11, resolve as resolve3 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { createRequire } from "module";
 
@@ -7004,7 +7361,7 @@ 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, join as join6, resolve as resolve2 } from "path";
+import { isAbsolute as isAbsolute2, join as join7, resolve as resolve2 } from "path";
 var SUPPORTED_AGENT_IDS = [
   "claude",
   "claude-desktop",
@@ -7047,13 +7404,13 @@ var AGENT_NAME_FOR = {
 function resolveAgentHostTarget(options) {
   const homeDir = resolve2(options.homeDir ?? homedir4());
   const codexHome = options.codexHome ?? (options.homeDir === void 0 ? process.env.CODEX_HOME || void 0 : void 0);
-  if (codexHome !== void 0 && (!codexHome.trim() || !isAbsolute(codexHome))) {
+  if (codexHome !== void 0 && (!codexHome.trim() || !isAbsolute2(codexHome))) {
     throw new Error("Codex home must be an absolute nonempty directory.");
   }
   return Object.freeze({
     homeDir,
     ...options.projectDir ? { projectDir: resolve2(options.projectDir) } : {},
-    codexHome: codexHome ?? join6(homeDir, ".codex")
+    codexHome: codexHome ?? join7(homeDir, ".codex")
   });
 }
 var RESERVED_OPERATOR_REGISTRATION = ["topolo", "platform"].join("-");
@@ -7062,7 +7419,7 @@ function isPublicRegistrationName(name) {
 }
 function selectStableNodeCommand(whichOutput, fallback = process.execPath) {
   const candidate = whichOutput?.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
-  return candidate && isAbsolute(candidate) ? candidate : fallback;
+  return candidate && isAbsolute2(candidate) ? candidate : fallback;
 }
 function stableNodeCommand() {
   const probe = spawnSync3(process.platform === "win32" ? "where" : "which", ["node"], {
@@ -7074,23 +7431,23 @@ function stableNodeCommand() {
 function agentSkillPath(agent, homeDir = homedir4(), projectDir, codexHome) {
   switch (agent) {
     case "claude":
-      return projectDir ? join6(projectDir, ".claude", "skills", "topolo", "SKILL.md") : join6(homeDir, ".claude", "skills", "topolo", "SKILL.md");
+      return projectDir ? join7(projectDir, ".claude", "skills", "topolo", "SKILL.md") : join7(homeDir, ".claude", "skills", "topolo", "SKILL.md");
     case "claude-desktop":
-      return join6(homeDir, ".claude", "skills", "topolo", "SKILL.md");
+      return join7(homeDir, ".claude", "skills", "topolo", "SKILL.md");
     case "codex":
-      return join6(codexHome ?? join6(homeDir, ".codex"), "skills", "topolo", "SKILL.md");
+      return join7(codexHome ?? join7(homeDir, ".codex"), "skills", "topolo", "SKILL.md");
     case "cursor":
-      return join6(projectDir ?? homeDir, ".cursor", "rules", "topolo.mdc");
+      return join7(projectDir ?? homeDir, ".cursor", "rules", "topolo.mdc");
     case "grok":
-      return join6(projectDir ?? homeDir, ".grok", "skills", "topolo", "SKILL.md");
+      return join7(projectDir ?? homeDir, ".grok", "skills", "topolo", "SKILL.md");
     case "gemini":
-      return join6(projectDir ?? homeDir, ".gemini", "skills", "topolo", "SKILL.md");
+      return join7(projectDir ?? homeDir, ".gemini", "skills", "topolo", "SKILL.md");
     case "copilot":
-      return projectDir ? join6(projectDir, ".github", "skills", "topolo", "SKILL.md") : join6(homeDir, ".copilot", "skills", "topolo", "SKILL.md");
+      return projectDir ? join7(projectDir, ".github", "skills", "topolo", "SKILL.md") : join7(homeDir, ".copilot", "skills", "topolo", "SKILL.md");
     case "windsurf":
-      return projectDir ? join6(projectDir, ".windsurf", "rules", "topolo.md") : void 0;
+      return projectDir ? join7(projectDir, ".windsurf", "rules", "topolo.md") : void 0;
     case "cline":
-      return join6(projectDir ?? homeDir, ".cline", "skills", "topolo", "SKILL.md");
+      return join7(projectDir ?? homeDir, ".cline", "skills", "topolo", "SKILL.md");
     case "goose":
     case "amazon-q":
       return void 0;
@@ -7099,7 +7456,7 @@ function agentSkillPath(agent, homeDir = homedir4(), projectDir, codexHome) {
 function agentConfigPaths(agent, homeDir = homedir4(), projectDir, codexHome) {
   switch (agent) {
     case "claude":
-      return [{ path: projectDir ? join6(projectDir, ".mcp.json") : join6(homeDir, ".claude.json"), format: "json", rootKey: "mcpServers" }];
+      return [{ path: projectDir ? join7(projectDir, ".mcp.json") : join7(homeDir, ".claude.json"), format: "json", rootKey: "mcpServers" }];
     case "claude-desktop":
       return [{
         path: claudeDesktopConfigPath(homeDir),
@@ -7107,31 +7464,31 @@ function agentConfigPaths(agent, homeDir = homedir4(), projectDir, codexHome) {
         rootKey: "mcpServers"
       }];
     case "codex":
-      return [{ path: join6(codexHome ?? join6(homeDir, ".codex"), "config.toml"), format: "toml" }];
+      return [{ path: join7(codexHome ?? join7(homeDir, ".codex"), "config.toml"), format: "toml" }];
     case "cursor":
       return [{
-        path: projectDir ? join6(projectDir, ".cursor", "mcp.json") : join6(homeDir, ".cursor", "mcp.json"),
+        path: projectDir ? join7(projectDir, ".cursor", "mcp.json") : join7(homeDir, ".cursor", "mcp.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "grok":
       return [{
-        path: projectDir ? join6(projectDir, ".grok", "config.toml") : join6(homeDir, ".grok", "config.toml"),
+        path: projectDir ? join7(projectDir, ".grok", "config.toml") : join7(homeDir, ".grok", "config.toml"),
         format: "toml"
       }];
     case "gemini":
       return [{
-        path: projectDir ? join6(projectDir, ".gemini", "settings.json") : join6(homeDir, ".gemini", "settings.json"),
+        path: projectDir ? join7(projectDir, ".gemini", "settings.json") : join7(homeDir, ".gemini", "settings.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "copilot":
       return projectDir ? [
-        { path: join6(projectDir, ".mcp.json"), format: "json", rootKey: "mcpServers" },
-        { path: join6(projectDir, ".vscode", "mcp.json"), format: "json", rootKey: "servers" }
+        { path: join7(projectDir, ".mcp.json"), format: "json", rootKey: "mcpServers" },
+        { path: join7(projectDir, ".vscode", "mcp.json"), format: "json", rootKey: "servers" }
       ] : [
         {
-          path: join6(homeDir, ".copilot", "mcp-config.json"),
+          path: join7(homeDir, ".copilot", "mcp-config.json"),
           format: "json",
           rootKey: "mcpServers"
         },
@@ -7139,24 +7496,24 @@ function agentConfigPaths(agent, homeDir = homedir4(), projectDir, codexHome) {
       ];
     case "windsurf":
       return [{
-        path: join6(homeDir, ".codeium", "windsurf", "mcp_config.json"),
+        path: join7(homeDir, ".codeium", "windsurf", "mcp_config.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "cline":
       return [{
-        path: projectDir ? join6(projectDir, ".cline", "mcp.json") : join6(homeDir, ".cline", "mcp.json"),
+        path: projectDir ? join7(projectDir, ".cline", "mcp.json") : join7(homeDir, ".cline", "mcp.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "goose":
-      return [{ path: join6(homeDir, ".config", "goose", "config.yaml"), format: "yaml" }];
+      return [{ path: join7(homeDir, ".config", "goose", "config.yaml"), format: "yaml" }];
     case "amazon-q":
       if (projectDir) {
-        return [{ path: join6(projectDir, ".amazonq", "mcp.json"), format: "json", rootKey: "mcpServers" }];
+        return [{ path: join7(projectDir, ".amazonq", "mcp.json"), format: "json", rootKey: "mcpServers" }];
       }
       return [{
-        path: existsSync4(join6(homeDir, ".aws", "amazonq", "mcp.json")) ? join6(homeDir, ".aws", "amazonq", "mcp.json") : join6(homeDir, ".aws", "amazonq", "default.json"),
+        path: existsSync4(join7(homeDir, ".aws", "amazonq", "mcp.json")) ? join7(homeDir, ".aws", "amazonq", "mcp.json") : join7(homeDir, ".aws", "amazonq", "default.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
@@ -7192,7 +7549,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 = join6(homeDir, ".claude.json");
+  const path = join7(homeDir, ".claude.json");
   let contents;
   try {
     contents = await readFile4(path, "utf8");
@@ -7220,14 +7577,14 @@ async function assertClaudeProjectScope(homeDir, projectDir, name) {
   }
 }
 function claudeDesktopConfigPath(homeDir) {
-  if (process.platform === "darwin") return join6(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-  if (process.platform === "win32") return join6(process.env.APPDATA ?? join6(homeDir, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
-  return join6(process.env.XDG_CONFIG_HOME ?? join6(homeDir, ".config"), "Claude", "claude_desktop_config.json");
+  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");
 }
 function vscodeUserConfigPath(homeDir) {
-  if (process.platform === "darwin") return join6(homeDir, "Library", "Application Support", "Code", "User", "mcp.json");
-  if (process.platform === "win32") return join6(process.env.APPDATA ?? join6(homeDir, "AppData", "Roaming"), "Code", "User", "mcp.json");
-  return join6(process.env.XDG_CONFIG_HOME ?? join6(homeDir, ".config"), "Code", "User", "mcp.json");
+  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");
 }
 async function readAgentRegistrations(agent, homeDir = homedir4(), projectDir, codexHome) {
   const registrations = [];
@@ -7286,7 +7643,7 @@ async function readTomlRegistrations(path, agent) {
     if (!section || !isPublicRegistrationName(section.name) || !line || line.startsWith("#")) continue;
     const assignment = line.match(/^([A-Za-z0-9_]+)\s*=\s*(.+)$/);
     if (!assignment) continue;
-    if (!section.env && assignment[1] !== "command" && assignment[1] !== "args" && assignment[1] !== "env") continue;
+    if (!section.env && !["command", "args", "env", "url", "http_headers"].includes(assignment[1])) continue;
     pending = { key: assignment[1], value: assignment[2] };
     if (isTomlValueComplete(pending.value)) {
       applyTomlAssignment(path, agent, section, pending, registrations);
@@ -7294,7 +7651,7 @@ async function readTomlRegistrations(path, agent) {
     }
   }
   if (pending) throw new Error("Cannot read unsupported MCP value in " + AGENT_LABELS[agent] + " configuration at " + path + ".");
-  return [...registrations.values()].filter((registration) => registration.command);
+  return [...registrations.values()].filter((registration) => registration.command || registration.url);
 }
 async function readGooseRegistrations(path) {
   const text2 = await readFile4(path, "utf8");
@@ -7368,11 +7725,18 @@ function applyTomlAssignment(path, agent, section, assignment, registrations) {
     registration.args = value;
   }
   if (!section.env && assignment.key === "env" && value && typeof value === "object" && !Array.isArray(value)) {
-    registration.env = Object.fromEntries(Object.entries(value).filter(
-      (entry) => typeof entry[1] === "string"
-    ));
+    registration.env = stringEntries(value);
+  }
+  if (!section.env && assignment.key === "url" && typeof value === "string") registration.url = value;
+  if (!section.env && assignment.key === "http_headers" && value && typeof value === "object" && !Array.isArray(value)) {
+    registration.headers = stringEntries(value);
   }
 }
+function stringEntries(value) {
+  return Object.fromEntries(Object.entries(value).filter(
+    (entry) => typeof entry[1] === "string"
+  ));
+}
 function stripTomlComment(line) {
   let quote;
   let escaped = false;
@@ -7485,9 +7849,13 @@ function splitTomlArray(value) {
 function normalizeRegistration(name, value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return [];
   const candidate = value;
+  if (typeof candidate.command !== "string" && typeof candidate.url === "string") {
+    const headers = candidate.headers && typeof candidate.headers === "object" && !Array.isArray(candidate.headers) ? stringEntries(candidate.headers) : {};
+    return [{ name, command: "", args: [], env: {}, url: candidate.url, headers }];
+  }
   if (typeof candidate.command !== "string") return [];
   const args = Array.isArray(candidate.args) && candidate.args.every((arg) => typeof arg === "string") ? candidate.args : [];
-  const env = candidate.env && typeof candidate.env === "object" && !Array.isArray(candidate.env) ? Object.fromEntries(Object.entries(candidate.env).filter((entry) => typeof entry[1] === "string")) : {};
+  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) {
@@ -7496,8 +7864,8 @@ function message(error) {
 
 // src/commands/agent-config.ts
 import { existsSync as existsSync5 } from "fs";
-import { lstat as lstat2, mkdir as mkdir3, open, readFile as readFile5, rename as rename2, unlink, writeFile as writeFile2 } from "fs/promises";
-import { randomUUID as randomUUID3 } from "crypto";
+import { lstat as lstat3, mkdir as mkdir4, open as open2, readFile as readFile5, rename as rename3, unlink, 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);
@@ -7518,6 +7886,23 @@ async function registerAgentConfig(agent, mcp, homeDir, registration, projectDir
     }
   }
 }
+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, {
+      type: "http",
+      url: registration.url,
+      headers: registration.headers
+    });
+    return;
+  }
+  const before = await fileSnapshot(config.path);
+  const text2 = withoutMcpServerSections(before.contents ?? "", registration.name);
+  const headers = Object.entries(registration.headers).map(([key, value]) => JSON.stringify(key) + " = " + JSON.stringify(value)).join(", ");
+  const block = "\n\n[mcp_servers." + registration.name + "]\nurl = " + JSON.stringify(registration.url) + "\nhttp_headers = { " + headers + " }\n";
+  await atomicWrite(config.path, text2 + block, before);
+}
 async function unregisterAgentConfig(agent, homeDir, name, projectDir, codexHome) {
   for (const config of agentConfigPaths(agent, homeDir, projectDir, codexHome)) {
     if (!existsSync5(config.path)) continue;
@@ -7559,6 +7944,15 @@ function registrationEnvironment(agent, registration) {
   };
 }
 async function registerJson(config, agent, mcp, registration) {
+  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);
+}
+async function writeJsonServer(config, agent, name, entry) {
   const before = await fileSnapshot(config.path);
   let parsed = {};
   if (before.contents !== void 0) {
@@ -7577,13 +7971,7 @@ async function registerJson(config, agent, mcp, registration) {
     throw new Error("Cannot update malformed " + AGENT_LABELS[agent] + " MCP configuration at " + config.path + ".");
   }
   const servers = existingServers ?? {};
-  const entry = {
-    command: mcp.command,
-    args: mcp.args,
-    env: registrationEnvironment(agent, registration)
-  };
-  if (agent === "claude" || agent === "claude-desktop" || rootKey === "servers") entry.type = "stdio";
-  servers[registration.name] = entry;
+  servers[name] = entry;
   parsed[rootKey] = servers;
   await atomicWrite(config.path, JSON.stringify(parsed, null, 2) + "\n", before);
 }
@@ -7684,27 +8072,27 @@ function formatSkillForAgent(agent, source) {
   }
   return "---\ntrigger: model_decision\ndescription: Use Topolo MCP for Topolo platform operations.\n---\n\n" + body;
 }
-function fileIdentity(stat2) {
-  return [stat2.dev, stat2.ino, stat2.size, stat2.mtimeMs, stat2.ctimeMs, stat2.mode, stat2.nlink].join(":");
+function fileIdentity(stat3) {
+  return [stat3.dev, stat3.ino, stat3.size, stat3.mtimeMs, stat3.ctimeMs, stat3.mode, stat3.nlink].join(":");
 }
 async function fileSnapshot(path) {
   const parents = [];
   for (let parent = dirname5(path); ; parent = dirname5(parent)) {
     try {
-      const stat2 = await lstat2(parent);
-      if (!stat2.isDirectory() || stat2.isSymbolicLink()) throw new Error("Host destination contains a symbolic link or non-directory at " + parent + ".");
-      parents.push({ path: parent, identity: [stat2.dev, stat2.ino].join(":") });
+      const stat3 = await lstat3(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) {
       if (error.code !== "ENOENT") throw error;
     }
     if (dirname5(parent) === parent) break;
   }
   try {
-    const stat2 = await lstat2(path);
-    if (!stat2.isFile() || stat2.isSymbolicLink() || stat2.nlink !== 1) throw new Error("Host configuration must be a single regular file at " + path + ".");
+    const stat3 = await lstat3(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 lstat2(path)) !== fileIdentity(stat2)) throw new Error("Host configuration changed while reading at " + path + ".");
-    return { contents, identity: fileIdentity(stat2), parents };
+    if (fileIdentity(await lstat3(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 };
     throw error;
@@ -7720,11 +8108,11 @@ async function atomicWrite(path, contents, before) {
   before ??= await fileSnapshot(path);
   await assertSnapshot(path, before);
   if (before.contents === contents) return;
-  await mkdir3(dirname5(path), { recursive: true });
+  await mkdir4(dirname5(path), { recursive: true });
   const destination = await fileSnapshot(path);
   await assertSnapshot(path, before);
-  const temporaryPath = path + ".topolo-" + randomUUID3() + ".tmp";
-  const handle = await open(temporaryPath, "wx", 384);
+  const temporaryPath = path + ".topolo-" + randomUUID4() + ".tmp";
+  const handle = await open2(temporaryPath, "wx", 384);
   let temporaryIdentity;
   let handleClosed = false;
   let temporaryPending = true;
@@ -7736,11 +8124,11 @@ async function atomicWrite(path, contents, before) {
     await handle.close();
     handleClosed = true;
     await assertSnapshot(path, destination);
-    const temporary = await lstat2(temporaryPath);
+    const temporary = await lstat3(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 + ".");
     }
-    await rename2(temporaryPath, path);
+    await rename3(temporaryPath, path);
     temporaryPending = false;
     const installed = await fileSnapshot(path);
     if (installed.contents !== contents) throw new Error("Host configuration read-back failed at " + path + ".");
@@ -7750,10 +8138,10 @@ async function atomicWrite(path, contents, before) {
       let cleanupOwned = false;
       try {
         const parentsOwned = await Promise.all(destination.parents.map(async (parent) => {
-          const current2 = await lstat2(parent.path);
+          const current2 = await lstat3(parent.path);
           return current2.isDirectory() && !current2.isSymbolicLink() && [current2.dev, current2.ino].join(":") === parent.identity;
         }));
-        const current = await lstat2(temporaryPath);
+        const current = await lstat3(temporaryPath);
         cleanupOwned = parentsOwned.every(Boolean) && current.isFile() && !current.isSymbolicLink() && current.nlink === 1 && [current.dev, current.ino].join(":") === temporaryIdentity;
       } catch {
       }
@@ -7763,11 +8151,11 @@ async function atomicWrite(path, contents, before) {
 }
 function withoutMcpServerSections(text2, name) {
   const section = "[mcp_servers." + name + "]";
-  const environmentSection = "[mcp_servers." + name + ".env]";
+  const subsectionPrefix = "[mcp_servers." + name + ".";
   let skipping = false;
   return text2.split(/\r?\n/).filter((line) => {
     const trimmed = line.trim();
-    if (trimmed === section || trimmed === environmentSection) {
+    if (trimmed === section || trimmed.startsWith(subsectionPrefix) && trimmed.endsWith("]")) {
       skipping = true;
       return false;
     }
@@ -7776,14 +8164,505 @@ function withoutMcpServerSections(text2, name) {
   }).join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
 }
 
+// src/commands/mcp-hub-setup.ts
+import { realpathSync } from "fs";
+import { readFile as readFile8 } from "fs/promises";
+import { join as join10 } 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";
+var MCP_HUB_DEFAULT_PORT = 7337;
+var MCP_HUB_ENVIRONMENTS = ["production", "staging", "development", "local"];
+var RESERVED_NAME = ["topolo", "platform"].join("-");
+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") };
+}
+function mcpHubUrl(port, name) {
+  return `http://127.0.0.1:${port}/mcp/${name}`;
+}
+function emptyMcpHubConfig() {
+  return { port: MCP_HUB_DEFAULT_PORT, identities: [] };
+}
+function validateMcpHubPort(value) {
+  const port = typeof value === "string" && /^\d+$/.test(value.trim()) ? Number(value.trim()) : value;
+  if (typeof port !== "number" || !Number.isInteger(port) || port < 1024 || port > 65535) {
+    throw new Error("MCP hub port must be an integer from 1024 to 65535.");
+  }
+  return port;
+}
+function validateMcpHubIdentity(value, where = "identity") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`MCP hub ${where} must be an object.`);
+  }
+  const record3 = value;
+  const unknown = Object.keys(record3).filter((key) => !["name", "env", "context"].includes(key));
+  if (unknown.length) throw new Error(`MCP hub ${where} has unsupported field(s): ${unknown.join(", ")}.`);
+  const name = record3.name;
+  if (typeof name !== "string" || !NAME_PATTERN.test(name) || name === RESERVED_NAME) {
+    throw new Error(`MCP hub ${where} name must be topolo or topolo-<name> (and not reserved).`);
+  }
+  const environment = record3.env;
+  if (typeof environment !== "string" || !MCP_HUB_ENVIRONMENTS.includes(environment)) {
+    throw new Error(`MCP hub identity ${name} env must be one of ${MCP_HUB_ENVIRONMENTS.join(", ")}.`);
+  }
+  const context = record3.context;
+  if (context !== void 0 && (typeof context !== "string" || !context.trim() || /[\r\n]/.test(context))) {
+    throw new Error(`MCP hub identity ${name} context must be a non-empty single-line selector.`);
+  }
+  return {
+    name,
+    environment,
+    ...context !== void 0 ? { context: context.trim() } : {}
+  };
+}
+function parseMcpHubConfig(text2, source) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text2);
+  } catch (error) {
+    throw new Error(`Cannot read malformed MCP hub configuration at ${source}: ${error.message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`MCP hub configuration at ${source} must be a JSON object.`);
+  }
+  const record3 = parsed;
+  const unknown = Object.keys(record3).filter((key) => !["version", "port", "identities"].includes(key));
+  if (unknown.length) {
+    throw new Error(`MCP hub configuration at ${source} has unsupported field(s): ${unknown.join(", ")}.`);
+  }
+  if (record3.version !== 1) throw new Error(`MCP hub configuration at ${source} must declare "version": 1.`);
+  const port = record3.port === void 0 ? MCP_HUB_DEFAULT_PORT : validateMcpHubPort(record3.port);
+  if (record3.identities !== void 0 && !Array.isArray(record3.identities)) {
+    throw new Error(`MCP hub configuration at ${source} identities must be an array.`);
+  }
+  const identities = (record3.identities ?? []).map((entry, index) => validateMcpHubIdentity(entry, `identity #${index + 1}`));
+  const seen = /* @__PURE__ */ new Set();
+  for (const identity of identities) {
+    if (seen.has(identity.name)) {
+      throw new Error(`MCP hub configuration at ${source} declares ${identity.name} more than once.`);
+    }
+    seen.add(identity.name);
+  }
+  return { port, identities };
+}
+function serializeMcpHubConfig(config) {
+  return JSON.stringify({
+    version: 1,
+    port: config.port,
+    identities: config.identities.map((identity) => ({
+      name: identity.name,
+      env: identity.environment,
+      ...identity.context ? { context: identity.context } : {}
+    }))
+  }, null, 2) + "\n";
+}
+async function readMcpHubConfig(path) {
+  let text2;
+  try {
+    text2 = await readFile6(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return emptyMcpHubConfig();
+    throw error;
+  }
+  return parseMcpHubConfig(text2, path);
+}
+function upsertMcpHubIdentity(config, identity) {
+  const identities = config.identities.filter((entry) => entry.name !== identity.name);
+  identities.push(identity);
+  identities.sort((left, right) => left.name.localeCompare(right.name));
+  return { ...config, identities };
+}
+async function writePrivateFile(path, contents) {
+  await mkdir5(dirname6(path), { recursive: true, mode: 448 });
+  const temporary = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  const handle = await open3(temporary, "wx", 384);
+  try {
+    await handle.writeFile(contents, "utf8");
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename4(temporary, path);
+  } catch (error) {
+    await unlink2(temporary).catch(() => void 0);
+    throw error;
+  }
+}
+async function writeMcpHubConfig(path, config) {
+  await writePrivateFile(path, serializeMcpHubConfig(config));
+}
+async function assertPrivateTokenFile(path) {
+  const stat3 = await lstat4(path);
+  if (!stat3.isFile() || stat3.isSymbolicLink() || stat3.nlink !== 1) {
+    throw new Error(`MCP hub token at ${path} must be a single regular file.`);
+  }
+  if ((stat3.mode & 63) !== 0) {
+    throw new Error(`MCP hub token at ${path} is readable by other users. Delete it and rerun \`topolo setup --shared\` to issue a new one.`);
+  }
+}
+async function readMcpHubToken(path) {
+  try {
+    await assertPrivateTokenFile(path);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`MCP hub token is missing at ${path}. Run \`topolo setup --shared\`.`);
+    }
+    throw error;
+  }
+  const token = (await readFile6(path, "utf8")).trim();
+  if (!TOKEN_PATTERN.test(token)) {
+    throw new Error(`MCP hub token at ${path} is malformed. Delete it and rerun \`topolo setup --shared\`.`);
+  }
+  return token;
+}
+async function ensureMcpHubToken(path) {
+  try {
+    return { token: await readMcpHubToken(path), created: false };
+  } catch (error) {
+    if (!/is missing at/.test(error.message)) throw error;
+  }
+  await mkdir5(dirname6(path), { recursive: true, mode: 448 });
+  const token = randomBytes(32).toString("base64url");
+  const handle = await open3(path, "wx", 384);
+  try {
+    await handle.writeFile(token + "\n", "utf8");
+  } finally {
+    await handle.close();
+  }
+  return { token, created: true };
+}
+
+// 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";
+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"];
+var runCommand = (command, args) => {
+  const result = spawnSync4(command, args, { encoding: "utf8", stdio: ["ignore", "ignore", "pipe"] });
+  return { status: result.status, stderr: result.stderr ?? "" };
+};
+function serviceKindFor(platform4) {
+  if (platform4 === "darwin") return "launchd";
+  if (platform4 === "linux") return "systemd";
+  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);
+}
+function serviceEnvironment(environment) {
+  const selected = {};
+  for (const key of PASSTHROUGH_ENVIRONMENT) {
+    const value = environment[key];
+    if (value) selected[key] = value;
+  }
+  return selected;
+}
+function xml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function serviceArguments(spec) {
+  return [spec.nodeCommand, spec.cliEntry, "mcp", "serve", "--port", String(spec.port)];
+}
+function renderLaunchdPlist(spec) {
+  const environment = Object.entries(spec.environment);
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    "  <key>Label</key>",
+    `  <string>${MCP_HUB_LAUNCHD_LABEL}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    ...serviceArguments(spec).map((argument) => `    <string>${xml(argument)}</string>`),
+    "  </array>",
+    ...environment.length ? [
+      "  <key>EnvironmentVariables</key>",
+      "  <dict>",
+      ...environment.flatMap(([key, value]) => [`    <key>${xml(key)}</key>`, `    <string>${xml(value)}</string>`]),
+      "  </dict>"
+    ] : [],
+    "  <key>RunAtLoad</key>",
+    "  <true/>",
+    "  <key>KeepAlive</key>",
+    "  <true/>",
+    "  <key>ProcessType</key>",
+    "  <string>Background</string>",
+    ...spec.logPath ? [
+      "  <key>StandardOutPath</key>",
+      `  <string>${xml(spec.logPath)}</string>`,
+      "  <key>StandardErrorPath</key>",
+      `  <string>${xml(spec.logPath)}</string>`
+    ] : [],
+    "</dict>",
+    "</plist>",
+    ""
+  ].join("\n");
+}
+function systemdQuote(value) {
+  return '"' + value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%") + '"';
+}
+function renderSystemdUnit(spec) {
+  return [
+    "[Unit]",
+    "Description=Topolo shared local MCP hub",
+    "After=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    `ExecStart=${serviceArguments(spec).map(systemdQuote).join(" ")}`,
+    ...Object.entries(spec.environment).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`),
+    "Restart=always",
+    "RestartSec=2",
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    ""
+  ].join("\n");
+}
+async function readExisting(path) {
+  try {
+    return await readFile7(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+function require0(result, what) {
+  if (result.status !== 0) throw new Error(`${what} failed: ${result.stderr.trim() || `exit ${result.status}`}`);
+}
+async function installMcpHubService(options) {
+  const kind = serviceKindFor(options.platform);
+  if (!kind) {
+    return {
+      kind: "unsupported",
+      changed: false,
+      activated: false,
+      detail: `No user service manager is supported on ${options.platform}; run \`topolo mcp serve\` yourself.`
+    };
+  }
+  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 contents = kind === "launchd" ? renderLaunchdPlist(spec) : renderSystemdUnit(spec);
+  const changed = await readExisting(path) !== contents;
+  if (changed) await writePrivateFile(path, contents);
+  if (!options.activate) {
+    return { kind, path, changed, activated: false, detail: `${kind} unit written; not activated for an alternate agent home.` };
+  }
+  const run = options.run;
+  if (kind === "launchd") {
+    const domain = `gui/${options.uid ?? process.getuid()}`;
+    const target = `${domain}/${MCP_HUB_LAUNCHD_LABEL}`;
+    const loaded = run("launchctl", ["print", target]).status === 0;
+    if (loaded && !changed) {
+      return { kind, path, changed, activated: true, detail: `${MCP_HUB_LAUNCHD_LABEL} already loaded with this definition.` };
+    }
+    if (loaded) run("launchctl", ["bootout", target]);
+    require0(run("launchctl", ["bootstrap", domain, path]), "launchctl bootstrap");
+    return { kind, path, changed, activated: true, detail: `${MCP_HUB_LAUNCHD_LABEL} ${loaded ? "reloaded" : "loaded"} (KeepAlive).` };
+  }
+  require0(run("systemctl", ["--user", "daemon-reload"]), "systemctl --user daemon-reload");
+  require0(run("systemctl", ["--user", "enable", MCP_HUB_SYSTEMD_UNIT]), "systemctl --user enable");
+  require0(run("systemctl", ["--user", changed ? "restart" : "start", MCP_HUB_SYSTEMD_UNIT]), `systemctl --user ${changed ? "restart" : "start"}`);
+  return { kind, path, changed, activated: true, detail: `${MCP_HUB_SYSTEMD_UNIT} enabled and ${changed ? "restarted" : "running"} (Restart=always).` };
+}
+
+// src/commands/mcp-hub-setup.ts
+function resolveCliEntry(argvEntry = process.argv[1]) {
+  if (!argvEntry) throw new Error("Cannot locate the running topolo CLI entry for the hub service.");
+  return realpathSync(argvEntry);
+}
+function resolveSharedTargets(options) {
+  const explicit = [...options.agent ?? [], ...options.claude ? ["claude"] : [], ...options.codex ? ["codex"] : []];
+  if (!explicit.length) return [...SHARED_HUB_AGENTS];
+  const unsupported = explicit.filter((agent) => !SHARED_HUB_AGENTS.includes(agent));
+  if (unsupported.length) {
+    throw new Error(
+      `The shared MCP hub supports Claude Code and Codex only (not ${unsupported.join(", ")}). Register other hosts with \`topolo setup\` (stdio).`
+    );
+  }
+  return [...new Set(explicit)];
+}
+async function importStdioIdentities(agents, homeDir, codexHome) {
+  const found = /* @__PURE__ */ new Map();
+  const skipped = [];
+  for (const agent of agents) {
+    for (const registration of await readAgentRegistrations(agent, homeDir, void 0, codexHome)) {
+      if (registration.url) continue;
+      if (registration.env.TOPOLO_CONFIG_PATH || registration.env.TOPOLO_AGENT_INSTALLATION_ID) {
+        skipped.push({ agent, name: registration.name, reason: "uses a private config path or agent installation; keep it on stdio" });
+        continue;
+      }
+      let identity;
+      try {
+        identity = validateMcpHubIdentity({
+          name: registration.name,
+          env: registration.env.TOPOLO_ENV || "production",
+          ...registration.env.TOPOLO_CONTEXT ? { context: registration.env.TOPOLO_CONTEXT } : {}
+        });
+      } catch (error) {
+        skipped.push({ agent, name: registration.name, reason: error.message });
+        continue;
+      }
+      const previous = found.get(identity.name);
+      if (previous && JSON.stringify(previous.identity) !== JSON.stringify(identity)) {
+        skipped.push({ agent, name: identity.name, reason: `conflicts with the ${AGENT_LABELS[previous.agent]} registration of the same name` });
+        continue;
+      }
+      found.set(identity.name, { identity, agent });
+    }
+  }
+  return { identities: [...found.values()].map((entry) => entry.identity), skipped };
+}
+function sameHeaders(left, right) {
+  return JSON.stringify(Object.entries(left ?? {}).sort()) === JSON.stringify(Object.entries(right).sort());
+}
+function hubHeaders(token, agent) {
+  return { Authorization: `Bearer ${token}`, "X-Topolo-Agent": AGENT_NAME_FOR[agent] };
+}
+async function installSharedAgentSurfaces(options, dependencies) {
+  if (options.project) {
+    throw new Error("--shared registers user-scope servers only: the hub token must never be written into project files.");
+  }
+  if (options.installationId) {
+    throw new Error("--shared cannot bind an agent installation; keep installation-bound MCPs on stdio.");
+  }
+  const agents = resolveSharedTargets(options);
+  const target = resolveAgentHostTarget({ homeDir: options.homeDir, codexHome: options.codexHome });
+  const paths = dependencies.paths();
+  let config = await readMcpHubConfig(paths.config);
+  if (options.port !== void 0) config = { ...config, port: validateMcpHubPort(options.port) };
+  const skipped = [];
+  if (options.importStdio) {
+    const imported = await importStdioIdentities(agents, target.homeDir, target.codexHome);
+    skipped.push(...imported.skipped);
+    for (const identity of imported.identities) config = upsertMcpHubIdentity(config, identity);
+  }
+  if (!options.importStdio || options.name) {
+    const name = options.name?.trim() || "topolo";
+    const context = options.context?.trim();
+    if (name !== "topolo" && !context) throw new Error("Named registrations require --context <context>.");
+    if (name === "topolo" && context) {
+      throw new Error("Pinned contexts require --name topolo-<name> so the active topolo registration remains independent.");
+    }
+    config = upsertMcpHubIdentity(config, validateMcpHubIdentity({
+      name,
+      env: options.environment?.trim() || dependencies.environment.TOPOLO_ENV || "production",
+      ...context ? { context } : {}
+    }));
+  }
+  await writeMcpHubConfig(paths.config, config);
+  const { token, created } = await ensureMcpHubToken(paths.token);
+  const source = await dependencies.skillSource();
+  const installed = [];
+  for (const agent of agents) {
+    const skill = await installAgentSkill(agent, source, target.homeDir, void 0, target.codexHome);
+    try {
+      const headers = hubHeaders(token, agent);
+      for (const identity of config.identities) {
+        await registerAgentHttpConfig(agent, target.homeDir, {
+          name: identity.name,
+          url: mcpHubUrl(config.port, identity.name),
+          headers
+        }, target.codexHome);
+      }
+      const registrations = await readAgentRegistrations(agent, target.homeDir, void 0, target.codexHome);
+      const missing = config.identities.filter((identity) => {
+        const entry = registrations.find((registration) => registration.name === identity.name);
+        return !entry || entry.url !== mcpHubUrl(config.port, identity.name) || !sameHeaders(entry.headers, headers);
+      });
+      if (missing.length) {
+        throw new Error(`Host configuration did not retain the shared hub registration for ${missing.map((identity) => identity.name).join(", ")}.`);
+      }
+      installed.push({
+        agent,
+        skillPath: skill.path,
+        skillInstalled: skill.installed,
+        mcp: "config-file",
+        registrations: config.identities.map((identity) => identity.name)
+      });
+    } catch (error) {
+      installed.push({
+        agent,
+        skillPath: skill.path,
+        skillInstalled: skill.installed,
+        mcp: "failed",
+        registrations: [],
+        detail: error.message
+      });
+    }
+  }
+  const service = options.service === false ? void 0 : await installMcpHubService({
+    platform: dependencies.platform,
+    homeDir: target.homeDir,
+    xdgConfigHome: target.homeDir === dependencies.realHome ? dependencies.environment.XDG_CONFIG_HOME : void 0,
+    spec: {
+      nodeCommand: dependencies.nodeCommand(),
+      cliEntry: dependencies.cliEntry(),
+      port: config.port,
+      environment: serviceEnvironment(dependencies.environment)
+    },
+    activate: target.homeDir === dependencies.realHome,
+    run: dependencies.run,
+    ...dependencies.uid !== void 0 ? { uid: dependencies.uid } : {}
+  });
+  return {
+    hub: {
+      port: config.port,
+      configPath: paths.config,
+      tokenPath: paths.token,
+      tokenCreated: created,
+      identities: config.identities
+    },
+    installed,
+    skipped,
+    ...service ? { service } : {}
+  };
+}
+function defaultSharedSetupDependencies(skillsDir, realHome) {
+  return {
+    paths: () => mcpHubPaths(),
+    skillSource: () => readFile8(join10(skillsDir, "topolo", "SKILL.md"), "utf8"),
+    platform: process.platform,
+    realHome,
+    nodeCommand: stableNodeCommand,
+    cliEntry: () => resolveCliEntry(),
+    environment: process.env,
+    run: runCommand
+  };
+}
+function formatSharedSetup(result) {
+  const lines = [
+    `Shared MCP hub: http://127.0.0.1:${result.hub.port}/mcp/<name> (${result.hub.identities.length} identities)`,
+    `  config -> ${result.hub.configPath}`,
+    `  token  -> ${result.hub.tokenPath}${result.hub.tokenCreated ? " (new)" : ""}`
+  ];
+  for (const row of result.installed) {
+    lines.push(`${AGENT_LABELS[row.agent]}:`);
+    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}`);
+  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");
+}
+
 // src/commands/skills.ts
 var AGENT_LABELS2 = AGENT_LABELS;
 function skillsSourceDir() {
-  const here = dirname6(fileURLToPath3(import.meta.url));
+  const here = dirname7(fileURLToPath3(import.meta.url));
   const distCandidate = resolve3(here, "../skills");
   const srcCandidate = resolve3(here, "../../skills");
   for (const candidate of [distCandidate, srcCandidate]) {
-    if (existsSync6(join7(candidate, "topolo", "SKILL.md"))) return candidate;
+    if (existsSync6(join11(candidate, "topolo", "SKILL.md"))) return candidate;
   }
   return distCandidate;
 }
@@ -7793,7 +8672,7 @@ function resolveMcpCommand() {
 }
 function agentBinaryExists(agent) {
   return agentCliNames(agent).some((bin) => {
-    const probe = spawnSync4(process.platform === "win32" ? "where" : "which", [bin], {
+    const probe = spawnSync5(process.platform === "win32" ? "where" : "which", [bin], {
       stdio: "ignore"
     });
     return probe.status === 0;
@@ -7841,7 +8720,7 @@ async function installForAgent(agent, sourceDir, mcp, opts) {
       return { agent, skillInstalled: false, mcp: "failed", detail: err instanceof Error ? err.message : String(err) };
     }
   }
-  const source = await readFile6(join7(sourceDir, "topolo", "SKILL.md"), "utf8");
+  const source = await readFile9(join11(sourceDir, "topolo", "SKILL.md"), "utf8");
   const skill = await installAgentSkill(agent, source, homeDir, projectDir, codexHome);
   if (!opts.withMcp) {
     return { agent, skillPath: skill.path, skillInstalled: skill.installed, mcp: "skipped" };
@@ -7938,7 +8817,7 @@ function registerSkillsCommand(program2) {
 }
 async function installAgentSurfaces(opts) {
   const sourceDir = skillsSourceDir();
-  if (!existsSync6(join7(sourceDir, "topolo", "SKILL.md"))) {
+  if (!existsSync6(join11(sourceDir, "topolo", "SKILL.md"))) {
     throw new Error("Bundled skill file not found. Reinstall the CLI: npm install -g @topolo/cli");
   }
   const mcp = resolveMcpCommand();
@@ -7956,9 +8835,22 @@ async function installAgentSurfaces(opts) {
   return { results, mcp };
 }
 function registerSetupCommand(program2) {
-  program2.command("setup").description("Install the Topolo skill and deterministic local MCP server for supported agent hosts").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent <host...>", "Target one or more hosts by id").option("--all", "Configure every supported local host").option("--project <dir>", "Write project-scoped host files under <dir> where supported").option("--codex-home <dir>", "Use an explicit native Codex home instead of <agent-home>/.codex").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Register a named pinned MCP, such as topolo-acme").option("--context <context>", "Pin the named MCP to an exact context returned by topolo context ls").option("--installation <id>", "Bind the MCP runtime to a registered external-agent installation").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
+  program2.command("setup").description("Install the Topolo skill and deterministic local MCP server for supported agent hosts").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent <host...>", "Target one or more hosts by id").option("--all", "Configure every supported local host").option("--project <dir>", "Write project-scoped host files under <dir> where supported").option("--codex-home <dir>", "Use an explicit native Codex home instead of <agent-home>/.codex").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Register a named pinned MCP, such as topolo-acme").option("--context <context>", "Pin the named MCP to an exact context returned by topolo context ls").option("--installation <id>", "Bind the MCP runtime to a registered external-agent installation").option("--shared", "Opt in: register Claude Code and Codex against the shared local MCP hub (one process) instead of stdio").option("--port <port>", "With --shared: hub port on 127.0.0.1 (default 7337)").option("--import-stdio", "With --shared: also move every existing stdio topolo/topolo-* registration onto the hub").option("--no-service", "With --shared: do not install the launchd/systemd keep-alive unit").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
+      if (opts.shared) {
+        const shared = await installSharedAgentSurfaces({
+          ...opts,
+          installationId: opts.installation,
+          homeDir: opts.agentHome
+        }, defaultSharedSetupDependencies(skillsSourceDir(), homedir5()));
+        assertSharedSetupSucceeded(shared);
+        emit(shared, mode, () => formatSharedSetup(shared));
+        return;
+      }
+      if (opts.port !== void 0 || opts.importStdio || opts.service === false) {
+        throw new Error("--port, --import-stdio and --no-service apply only with --shared.");
+      }
       const { results, mcp } = await installAgentSurfaces({
         ...opts,
         installationId: opts.installation,
@@ -7971,6 +8863,12 @@ 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("; "));
+  }
+}
 function assertAgentSetupSucceeded(results) {
   const failed = results.filter((result) => result.mcp === "failed");
   if (failed.length) {
@@ -7980,7 +8878,7 @@ function assertAgentSetupSucceeded(results) {
 async function agentSurfaceStatus(options = {}) {
   const target = resolveAgentHostTarget({ homeDir: options.homeDir, projectDir: options.project, codexHome: options.codexHome });
   const { homeDir, projectDir, codexHome } = target;
-  const sourceSkill = await readFile6(join7(skillsSourceDir(), "topolo", "SKILL.md"), "utf8");
+  const sourceSkill = await readFile9(join11(skillsSourceDir(), "topolo", "SKILL.md"), "utf8");
   const agents = resolveTargets({
     agent: options.agent,
     all: options.all,
@@ -7990,7 +8888,7 @@ async function agentSurfaceStatus(options = {}) {
   });
   return Promise.all(agents.map(async (agent) => {
     const skillPath = agentSkillPath(agent, homeDir, projectDir, codexHome);
-    const installedSkill = skillPath && existsSync6(skillPath) ? await readFile6(skillPath, "utf8") : void 0;
+    const installedSkill = skillPath && existsSync6(skillPath) ? await readFile9(skillPath, "utf8") : void 0;
     const registrations = (await readAgentRegistrations(agent, homeDir, projectDir, codexHome)).filter((registration) => !options.name || registration.name === options.name);
     return {
       agent,
@@ -8016,7 +8914,7 @@ async function uninstallAgentSurfaces(options) {
     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 rm2(dirname6(skillPath), { recursive: true, force: true });
+    if (skillRemoved && skillPath) await rm3(dirname7(skillPath), { recursive: true, force: true });
     removed.push({ agent, name, registrationRemoved, skillRemoved });
   }
   return removed;
@@ -8045,14 +8943,128 @@ function formatStatus(rows) {
 }
 
 // src/commands/doctor.ts
-import { access } from "fs/promises";
+import { access as access2 } from "fs/promises";
 import { homedir as homedir6 } from "os";
 import { resolve as resolve4 } from "path";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { Client as Client2 } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+// src/commands/mcp-hub-doctor.ts
+import { access } from "fs/promises";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+async function verifyHubIdentity(url, headers, fetchImplementation = fetch) {
+  const client = new Client({ name: "topolo-cli-doctor", version: CLI_VERSION });
+  const transport = new StreamableHTTPClientTransport(new URL(url), {
+    requestInit: { headers },
+    fetch: fetchImplementation
+  });
+  try {
+    await client.connect(transport);
+    const tools = await client.listTools();
+    if (!tools.tools.some((tool) => tool.name === "topolo_whoami")) {
+      throw new Error("hub identity connected but did not advertise topolo_whoami.");
+    }
+    const identity = await client.callTool({ name: "topolo_whoami", arguments: {} });
+    if (identity.isError) throw new Error("topolo_whoami returned an error through the hub.");
+    return `handshake and topolo_whoami succeeded; ${tools.tools.length} tools advertised`;
+  } finally {
+    await client.close();
+  }
+}
+var defaultSharedDoctorDependencies = () => ({
+  paths: () => mcpHubPaths(),
+  platform: process.platform,
+  fetch,
+  verifyIdentity: (url, headers) => verifyHubIdentity(url, headers),
+  fileExists: async (path) => access(path).then(() => true, () => false),
+  environment: process.env
+});
+function message2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function runSharedDoctor(options, dependencies) {
+  const checks = [];
+  const done = () => ({ ok: checks.every((check) => check.ok), cliVersion: CLI_VERSION, checks });
+  const paths = dependencies.paths();
+  let config;
+  try {
+    config = await readMcpHubConfig(paths.config);
+    const selected = options.name ? config.identities.filter((identity) => identity.name === options.name) : config.identities;
+    if (!selected.length) {
+      throw new Error(options.name ? `${options.name} is not a hub identity in ${paths.config}.` : `No identities are configured in ${paths.config}. Run \`topolo setup --shared\`.`);
+    }
+    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) });
+    return done();
+  }
+  let token;
+  try {
+    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) });
+    return done();
+  }
+  const target = resolveAgentHostTarget({ homeDir: options.agentHome, codexHome: options.codexHome });
+  const kind = serviceKindFor(dependencies.platform);
+  if (kind) {
+    const path = mcpHubServicePath(kind, target.homeDir, options.agentHome ? void 0 : dependencies.environment.XDG_CONFIG_HOME);
+    const present = await dependencies.fileExists(path);
+    checks.push({ name: "service", ok: present, detail: present ? `${kind} unit at ${path}` : `${kind} unit missing at ${path}` });
+  }
+  try {
+    const response = await dependencies.fetch(`http://127.0.0.1:${config.port}/health`, {
+      headers: { authorization: `Bearer ${token}` }
+    });
+    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)}` });
+    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)}` });
+      return void 0;
+    });
+    if (!registrations) continue;
+    const headers = hubHeaders(token, agent);
+    for (const identity of config.identities) {
+      const entry = registrations.find((registration) => registration.name === identity.name);
+      const exact = entry?.url === mcpHubUrl(config.port, identity.name) && entry.headers?.Authorization === headers.Authorization;
+      checks.push({
+        name: "registration",
+        ok: exact,
+        detail: `${agent}: ${identity.name} ${exact ? "points at the hub with the current token" : "is missing, stdio, or uses a stale hub URL/token"}`
+      });
+    }
+  }
+  for (const identity of config.identities) {
+    try {
+      const detail = await dependencies.verifyIdentity(
+        mcpHubUrl(config.port, identity.name),
+        { Authorization: `Bearer ${token}`, "X-Topolo-Agent": "topolo-doctor" }
+      );
+      checks.push({ name: "mcp", ok: true, detail: `${identity.name}: ${detail}` });
+    } catch (error) {
+      checks.push({ name: "mcp", ok: false, detail: `${identity.name}: ${message2(error)}` });
+    }
+  }
+  return done();
+}
+function formatSharedDoctor(result) {
+  return result.checks.map((check) => `${check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`).join("\n");
+}
+
+// src/commands/doctor.ts
 var defaultDependencies = {
   resolveMcp: resolveMcpCommand,
-  verifyFile: (path) => access(path),
+  verifyFile: (path) => access2(path),
   verifyAuthentication: async (context, environment) => {
     const topolo = await buildClient({ context, environment });
     if (!topolo) throw new Error(context ? `No credential configured for ${context}. Run \`topolo auth login\` for that context.` : "No credential configured. Run `topolo auth login`.");
@@ -8092,7 +9104,7 @@ async function runDoctor(dependencies = defaultDependencies, target) {
   return { ok: checks.every((check) => check.ok), cliVersion: CLI_VERSION, checks };
 }
 async function verifyMcpProtocol(command, args, env = definedEnvironment(process.env)) {
-  const client = new Client({ name: "topolo-cli-doctor", version: CLI_VERSION });
+  const client = new Client2({ name: "topolo-cli-doctor", version: CLI_VERSION });
   const transport = new StdioClientTransport({ command, args, stderr: "pipe", env });
   try {
     await client.connect(transport);
@@ -8132,7 +9144,7 @@ async function resolveInstalledDoctorTarget(options) {
     preflightChecks.push({
       name: "registration",
       ok: exact,
-      detail: `${row.agent}: ${exact ? `${name} uses the bundled launcher` : `${name} is missing or does not use the bundled launcher`}`
+      detail: `${row.agent}: ${exact ? `${name} uses the bundled launcher` : registration?.url ? `${name} is registered with the shared MCP hub; run \`topolo doctor --shared\`` : `${name} is missing or does not use the bundled launcher`}`
     });
   }
   const context = options.context !== void 0 ? normalizeDoctorContext(options.context) : selected?.env.TOPOLO_CONTEXT;
@@ -8150,9 +9162,15 @@ function definedEnvironment(environment) {
   return Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== void 0));
 }
 function registerDoctorCommand(program2) {
-  program2.command("doctor").description("Verify installed agent surfaces, exact credential, and MCP protocol end to end").option("--name <name>", "Verify one installed MCP registration (defaults to topolo)").option("--context <context>", "Verify one exact personal or organization context").option("--environment <env>", "Override the context environment").option("--claude", "Verify Claude Code only").option("--codex", "Verify Codex only").option("--agent <host...>", "Verify one or more hosts by id").option("--all", "Verify every supported local host").option("--project <dir>", "Inspect project-scoped host files under <dir>").option("--agent-home <dir>", "Inspect an alternate agent home").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
+  program2.command("doctor").description("Verify installed agent surfaces, exact credential, and MCP protocol end to end").option("--name <name>", "Verify one installed MCP registration (defaults to topolo)").option("--context <context>", "Verify one exact personal or organization context").option("--environment <env>", "Override the context environment").option("--claude", "Verify Claude Code only").option("--codex", "Verify Codex only").option("--agent <host...>", "Verify one or more hosts by id").option("--all", "Verify every supported local host").option("--project <dir>", "Inspect project-scoped host files under <dir>").option("--agent-home <dir>", "Inspect an alternate agent home").option("--shared", "Verify the shared local MCP hub end to end for every hub identity (or --name)").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
+      if (opts.shared) {
+        const shared = await runSharedDoctor(opts, defaultSharedDoctorDependencies());
+        if (!shared.ok) throw new Error(formatSharedDoctor(shared));
+        emit(shared, mode, () => formatSharedDoctor(shared));
+        return;
+      }
       const target = await resolveInstalledDoctorTarget(opts);
       const result = await runDoctor(defaultDependencies, target);
       if (!result.ok) throw new Error(formatDoctor(result));
@@ -8749,6 +9767,248 @@ function registerInstallationsCommand(program2) {
   });
 }
 
+// src/commands/mcp.ts
+import { createTopoloMcpLocalHandler } from "@topolo/mcp/local";
+
+// src/lib/mcp-hub-server.ts
+import { createHash as createHash4, timingSafeEqual } from "crypto";
+import { stat as stat2 } from "fs/promises";
+import { createServer } from "http";
+var MCP_HUB_HOST = "127.0.0.1";
+var MCP_HUB_MAX_BODY_BYTES = 4 * 1024 * 1024;
+var DEFAULT_AGENT_LABEL = "topolo-mcp-hub";
+var AGENT_LABELS3 = /* @__PURE__ */ new Set([...Object.values(AGENT_NAME_FOR), "topolo-doctor"]);
+var STRIPPED_HEADERS = /* @__PURE__ */ new Set(["authorization", "x-api-key", "cookie", "host", "origin"]);
+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 digest(value) {
+  return createHash4("sha256").update(value, "utf8").digest();
+}
+function bearerTokenMatches(header, token) {
+  const match = /^Bearer[ \t]+(\S+)[ \t]*$/i.exec(header ?? "");
+  if (!match) return false;
+  return timingSafeEqual(digest(match[1]), digest(token));
+}
+function loopbackHosts(port) {
+  return /* @__PURE__ */ new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
+}
+function loopbackOrigins(port) {
+  return new Set([...loopbackHosts(port)].map((host) => `http://${host}`));
+}
+function agentLabel(value) {
+  const label = value?.trim().toLowerCase() ?? "";
+  return AGENT_LABELS3.has(label) ? label : DEFAULT_AGENT_LABEL;
+}
+function createMcpHubHandler(options) {
+  const hosts = loopbackHosts(options.port);
+  const origins = loopbackOrigins(options.port);
+  const now = options.now ?? Date.now;
+  const log = options.log ?? (() => void 0);
+  const handlers = /* @__PURE__ */ new Map();
+  function handlerFor(identity, agentName) {
+    const key = JSON.stringify([identity.name, identity.environment, identity.context ?? null, agentName]);
+    let handler = handlers.get(key);
+    if (!handler) {
+      handler = options.createIdentityHandler(identity, agentName);
+      handlers.set(key, handler);
+    }
+    return handler;
+  }
+  async function forward(request, url, identity) {
+    const headers = new Headers();
+    request.headers.forEach((value, name) => {
+      if (!STRIPPED_HEADERS.has(name.toLowerCase())) headers.set(name, value);
+    });
+    const body = request.method === "GET" || request.method === "HEAD" ? void 0 : await request.arrayBuffer();
+    const forwarded = new Request(`http://${MCP_HUB_HOST}:${options.port}${url.pathname}`, {
+      method: request.method,
+      headers,
+      ...body ? { body } : {}
+    });
+    return handlerFor(identity, agentLabel(request.headers.get("x-topolo-agent"))).fetch(forwarded);
+  }
+  async function route(request) {
+    const host = request.headers.get("host")?.toLowerCase();
+    if (!host || !hosts.has(host)) return refusal(403, "Host is not a loopback address for this hub.");
+    const origin = request.headers.get("origin");
+    if (origin !== null && !origins.has(origin.toLowerCase())) {
+      return refusal(403, "Cross-origin requests to the Topolo MCP hub are refused.");
+    }
+    if (!bearerTokenMatches(request.headers.get("authorization"), options.token)) {
+      return refusal(401, "Missing or invalid Topolo MCP hub token.", { "www-authenticate": 'Bearer realm="topolo-mcp-hub"' });
+    }
+    const url = new URL(request.url);
+    let config;
+    try {
+      config = await options.loadConfig();
+    } catch {
+      return refusal(500, "The Topolo MCP hub configuration is invalid. Run `topolo doctor --shared`.");
+    }
+    if (url.pathname === "/health") {
+      if (request.method !== "GET") return refusal(405, "Use GET for /health.", { allow: "GET" });
+      return json(200, { ok: true, identities: config.identities.map((identity2) => identity2.name) });
+    }
+    const match = /^\/mcp\/([^/]+)$/.exec(url.pathname);
+    const identity = match ? config.identities.find((entry) => entry.name === match[1]) : void 0;
+    if (!identity) return refusal(404, "No Topolo MCP identity is mounted at this path.");
+    try {
+      return await forward(request, url, identity);
+    } catch {
+      return refusal(500, "The Topolo MCP identity failed unexpectedly.");
+    }
+  }
+  return async (request) => {
+    const started = now();
+    const response = await route(request);
+    log(`${request.method} ${new URL(request.url).pathname} ${response.status} ${now() - started}ms`);
+    return response;
+  };
+}
+function createMcpHubConfigLoader(path) {
+  let cached;
+  return async () => {
+    let signature = "missing";
+    try {
+      const info = await stat2(path);
+      signature = [info.ino, info.size, info.mtimeMs].join(":");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    if (cached?.signature === signature) return cached.config;
+    const config = await readMcpHubConfig(path);
+    cached = { signature, config };
+    return config;
+  };
+}
+async function readBody(request, limit) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > limit) throw new Error("Request body exceeds the hub limit.");
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+function toWebRequest(request, body, port) {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (value === void 0) continue;
+    headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+  }
+  return new Request(`http://${MCP_HUB_HOST}:${port}${request.url ?? "/"}`, {
+    method: request.method ?? "GET",
+    headers,
+    ...body && body.length ? { body } : {}
+  });
+}
+async function writeWebResponse(response, target) {
+  const headers = {};
+  response.headers.forEach((value, name) => {
+    headers[name] = value;
+  });
+  const body = Buffer.from(await response.arrayBuffer());
+  target.writeHead(response.status, headers);
+  target.end(body);
+}
+async function startMcpHub(options) {
+  const server = createServer();
+  await new Promise((resolve5, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, MCP_HUB_HOST, () => {
+      server.off("error", reject);
+      resolve5();
+    });
+  });
+  const port = server.address().port;
+  const handle = createMcpHubHandler({ ...options, port });
+  const limit = options.maxBodyBytes ?? MCP_HUB_MAX_BODY_BYTES;
+  server.on("request", (request, response) => {
+    void (async () => {
+      let body;
+      try {
+        body = request.method === "GET" || request.method === "HEAD" ? void 0 : await readBody(request, limit);
+      } catch {
+        await writeWebResponse(refusal(413, "Request body is too large for the Topolo MCP hub."), response);
+        request.resume();
+        return;
+      }
+      let webRequest;
+      try {
+        webRequest = toWebRequest(request, body, port);
+      } catch {
+        await writeWebResponse(refusal(400, "Malformed request."), response);
+        return;
+      }
+      await writeWebResponse(await handle(webRequest), response);
+    })().catch(() => {
+      response.destroy();
+    });
+  });
+  return {
+    port,
+    server,
+    close: () => new Promise((resolve5) => {
+      server.close(() => resolve5());
+      server.closeAllConnections();
+    })
+  };
+}
+
+// src/commands/mcp.ts
+var createLocalIdentityHandler = (identity, agentName) => createTopoloMcpLocalHandler({
+  identity: { environment: identity.environment, context: identity.context ?? null },
+  agentName
+});
+var defaultServeDependencies = () => ({
+  paths: () => mcpHubPaths(),
+  start: startMcpHub,
+  createIdentityHandler: createLocalIdentityHandler,
+  log: (line) => process.stderr.write(`${(/* @__PURE__ */ new Date()).toISOString()} topolo mcp hub: ${line}
+`),
+  onSignal: (signal, listener) => {
+    process.once(signal, listener);
+  },
+  exit: (code) => process.exit(code)
+});
+async function serveMcpHub(options, dependencies) {
+  const paths = dependencies.paths();
+  const config = await readMcpHubConfig(paths.config);
+  const port = options.port !== void 0 ? validateMcpHubPort(options.port) : config.port;
+  const { token } = await ensureMcpHubToken(paths.token);
+  const hub = await dependencies.start({
+    port,
+    token,
+    loadConfig: createMcpHubConfigLoader(paths.config),
+    createIdentityHandler: dependencies.createIdentityHandler,
+    log: dependencies.log
+  });
+  dependencies.log(
+    `listening on http://127.0.0.1:${hub.port}/mcp/<name> with ${config.identities.length} identities (${config.identities.map((identity) => identity.name).join(", ") || "none yet"}); config ${paths.config}`
+  );
+  const stop = () => {
+    dependencies.log("stopping");
+    void hub.close().then(() => dependencies.exit(0));
+  };
+  dependencies.onSignal("SIGINT", stop);
+  dependencies.onSignal("SIGTERM", stop);
+  return hub;
+}
+function registerMcpCommand(program2, dependencies = defaultServeDependencies) {
+  const mcp = program2.command("mcp").description("Run the shared local Topolo MCP hub (one process for every agent thread and identity)");
+  mcp.command("serve").description("Serve every identity in mcp-hub.json at http://127.0.0.1:<port>/mcp/<name> (loopback only, bearer token required)").option("--port <port>", "Port on 127.0.0.1 (defaults to the port in mcp-hub.json, 7337)").action(async (opts) => {
+    try {
+      await serveMcpHub(opts, dependencies());
+    } catch (error) {
+      fail2(error, resolveOutputMode(false));
+    }
+  });
+}
+
 // src/index.ts
 import { Agent, setGlobalDispatcher } from "undici";
 setGlobalDispatcher(new Agent({ connect: { timeout: 3e4 } }));
@@ -8774,6 +10034,7 @@ program.hook("preAction", async (thisCommand, actionCommand) => {
   if (opts.env || environmentWasStated) return;
   for (let node = actionCommand; node; node = node.parent) {
     if (node.name() === "agent-packs") return;
+    if (node.name() === "mcp" && node.parent === program) return;
   }
   const authenticated = await authenticatedEnvironments();
   if (authenticated.length < 2) return;
@@ -8796,6 +10057,7 @@ Or set it once for the whole session:
 registerAuthCommands(program);
 registerWhoamiCommand(program);
 registerActionsCommand(program);
+registerCredentialsCommand(program);
 registerApiCommand(program);
 registerAppsCommand(program);
 registerOAuthCommands(program);
@@ -8809,6 +10071,7 @@ registerResourcesCommand(program);
 registerWorkspacesCommand(program);
 registerInstallationsCommand(program);
 registerAgentPacksCommand(program);
+registerMcpCommand(program);
 var helpCommands = [program];
 for (const command of helpCommands) {
   command.configureHelp({