@topolo/cli 0.13.22 → 0.13.24

package/dist/index.js

@@ -308,7 +308,7 @@ import { Command, Help } from "commander";
 import { createInterface } from "readline/promises";
 import { stdin as input } from "process";
 
-// node_modules/@topolo/sdk/dist/index.js
+// node_modules/.pnpm/@topolo+sdk@0.23.26/node_modules/@topolo/sdk/dist/index.js
 function record(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -815,6 +815,14 @@ var TopoloRateLimitError = class extends TopoloHttpError {
     this.retryAfterSeconds = topoloRetryAfterSeconds(this.retryAfter);
   }
 };
+var TopoloReauthRequiredError = class extends TopoloAuthError {
+  reauthorization;
+  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 });
+  }
+};
 var ACTION_SECRET_PREFIX = "topolo-secret:";
 function isActionSecretReference(value) {
   return typeof value === "string" && value.startsWith(ACTION_SECRET_PREFIX);
@@ -1968,7 +1976,7 @@ var TopoloClient = class _TopoloClient {
         } catch (error) {
           const transportFailure = !(error instanceof TopoloSdkError) && !opts.signal?.aborted;
           if (!transportFailure || attempt === maxAttempts) throw error;
-          await new Promise((resolve5) => setTimeout(resolve5, 250));
+          await new Promise((resolve6) => setTimeout(resolve6, 250));
         }
       }
       throw new TopoloSdkError("network_error", "Topolo read retry loop exhausted.");
@@ -1991,7 +1999,7 @@ var TopoloClient = class _TopoloClient {
         const delayMs = header === void 0 ? RATE_LIMIT_READ_DEFAULT_DELAY_MS * (retry + 1) : (seconds ?? Infinity) * 1e3;
         if (delayMs > RATE_LIMIT_READ_RETRY_MAX_DELAY_MS || opts.signal?.aborted) break;
         await res.body?.cancel().catch(() => void 0);
-        await new Promise((resolve5) => setTimeout(resolve5, delayMs));
+        await new Promise((resolve6) => setTimeout(resolve6, delayMs));
         res = await fetchWithReadRetry();
       }
     } catch (err) {
@@ -2115,7 +2123,10 @@ var TopoloClient = class _TopoloClient {
     this.refreshInFlight ??= this.refreshCredential().then((credential) => {
       if (credential) this.credential = credential;
       return credential;
-    }).catch(() => null).finally(() => {
+    }).catch((error) => {
+      if (error instanceof TopoloReauthRequiredError) throw error;
+      return null;
+    }).finally(() => {
       this.refreshInFlight = null;
     });
     return this.refreshInFlight;
@@ -3489,6 +3500,19 @@ var TopoloOAuth = class {
     if (params.clientSecret) body.set("client_secret", params.clientSecret);
     return this.#postForm("/api/developer-oauth/token", body);
   }
+  /**
+   * RFC 7009 token revocation. A refresh token is revoked only for the client
+   * it was issued to, so pass that client's id. Auth answers 200 for a token it
+   * does not know, so success means "no longer usable", not "was revoked now".
+   */
+  async revokeToken(params) {
+    const body = new URLSearchParams();
+    body.set("token", params.token);
+    body.set("client_id", params.clientId);
+    if (params.tokenTypeHint) body.set("token_type_hint", params.tokenTypeHint);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    await this.#postForm("/api/tokens/revoke", body);
+  }
   async #postForm(path, body) {
     const url = new URL(path, this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`);
     const res = await this.fetchImpl(url.toString(), {
@@ -3989,7 +4013,7 @@ function createTopolo(options) {
 async function pollUntilApproved(params) {
   let interval = Math.max(params.intervalSeconds ?? 5, 1);
   while (Date.now() < params.expiresAtMs) {
-    await new Promise((resolve5) => setTimeout(resolve5, Math.min(interval * 1e3, params.expiresAtMs - Date.now())));
+    await new Promise((resolve6) => setTimeout(resolve6, Math.min(interval * 1e3, params.expiresAtMs - Date.now())));
     if (Date.now() >= params.expiresAtMs) break;
     try {
       return await params.oauth.pollDeviceToken({
@@ -4017,32 +4041,16 @@ async function pollUntilApproved(params) {
   throw new Error("Device code expired. Run `topolo auth login` again.");
 }
 
-// src/lib/open-browser.ts
-import { spawn } from "child_process";
-import { platform } from "os";
-function tryOpenBrowser(url) {
-  try {
-    const os = platform();
-    const cmd = os === "darwin" ? "open" : os === "win32" ? "start" : "xdg-open";
-    const args = os === "win32" ? ["", url] : [url];
-    const child = spawn(cmd, args, {
-      detached: true,
-      stdio: "ignore",
-      ...os === "win32" ? { shell: true } : {}
-    });
-    child.unref();
-    return true;
-  } catch {
-    return false;
-  }
-}
+// src/commands/auth-lock.ts
+import { createHash as createHash3 } from "crypto";
 
-// node_modules/@topolo/sdk/dist/node/credential-store.js
+// node_modules/.pnpm/@topolo+sdk@0.23.26/node_modules/@topolo/sdk/dist/node/credential-store.js
 import { mkdir as mkdir2, readFile as readFile2, chmod as chmod2, lstat, readdir as readdir2 } from "fs/promises";
 import { existsSync as existsSync2, mkdirSync, lstatSync, readdirSync, readFileSync as readFileSync2, openSync, writeFileSync, fsyncSync, closeSync, renameSync, unlinkSync, rmdirSync, linkSync } from "fs";
 import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
 import { constants, fstatSync, readSync } from "fs";
-import { homedir as homedir2, platform as platform2 } from "os";
+import { resolve as resolve2 } from "path";
+import { homedir as homedir2, platform } from "os";
 import { dirname as dirname2, join as join3 } from "path";
 import { createHash, randomUUID } from "crypto";
 import { join as join2 } from "path";
@@ -4370,7 +4378,7 @@ var TopoloRateLimitError2 = class extends TopoloHttpError2 {
     this.retryAfterSeconds = topoloRetryAfterSeconds2(this.retryAfter);
   }
 };
-var TopoloReauthRequiredError = class extends TopoloAuthError2 {
+var TopoloReauthRequiredError2 = class extends TopoloAuthError2 {
   reauthorization;
   constructor(message3, reauthorization, options = {}) {
     super(message3, "reauth_required", { status: 401, service: "auth", path: "/api/developer-oauth/token", ...options });
@@ -4520,6 +4528,19 @@ var TopoloOAuth2 = class {
     if (params.clientSecret) body.set("client_secret", params.clientSecret);
     return this.#postForm("/api/developer-oauth/token", body);
   }
+  /**
+   * RFC 7009 token revocation. A refresh token is revoked only for the client
+   * it was issued to, so pass that client's id. Auth answers 200 for a token it
+   * does not know, so success means "no longer usable", not "was revoked now".
+   */
+  async revokeToken(params) {
+    const body = new URLSearchParams();
+    body.set("token", params.token);
+    body.set("client_id", params.clientId);
+    if (params.tokenTypeHint) body.set("token_type_hint", params.tokenTypeHint);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    await this.#postForm("/api/tokens/revoke", body);
+  }
   async #postForm(path, body) {
     const url = new URL(path, this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`);
     const res = await this.fetchImpl(url.toString(), {
@@ -4810,7 +4831,7 @@ var ENVIRONMENT_DEFAULT_SERVICE_URLS = TOPOLO_ENVIRONMENT_SERVICE_URLS;
 function configPath() {
   const override = process.env.TOPOLO_CONFIG_PATH;
   if (override) return override;
-  const base = process.env.XDG_CONFIG_HOME || (platform2() === "win32" ? join3(homedir2(), "AppData", "Roaming") : join3(homedir2(), ".config"));
+  const base = process.env.XDG_CONFIG_HOME || (platform() === "win32" ? join3(homedir2(), "AppData", "Roaming") : join3(homedir2(), ".config"));
   return join3(base, "topolo", "config.json");
 }
 async function readConfig() {
@@ -4818,18 +4839,22 @@ async function readConfig() {
   if (!existsSync2(path)) return {};
   try {
     const raw = await readFile2(path, "utf8");
-    return JSON.parse(raw);
+    const parsed = JSON.parse(raw);
+    return isConfigObject(parsed) ? parsed : {};
   } catch {
     return {};
   }
 }
+function isConfigObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 async function writeConfig(config) {
   const path = configPath();
   await mkdir2(dirname2(path), { recursive: true });
   await withConfigWriteLock(async (_assertOwned, persist) => {
     await persist((current) => protectStoredGrants(config, current), { allowCreate: true });
   });
-  if (platform2() !== "win32") {
+  if (platform() !== "win32") {
     try {
       await chmod2(path, 384);
     } catch {
@@ -4854,10 +4879,21 @@ function retiredEntry(config, refreshToken) {
   const entry = config.retiredRefreshTokens?.[refreshTokenFingerprint(refreshToken)];
   return entry && typeof entry === "object" ? entry : void 0;
 }
-function retire(config, refreshToken, reason) {
+function retire(config, refreshToken, reason, inFlight = false) {
   const now = nowSeconds();
-  const entries = Object.entries({ ...config.retiredRefreshTokens ?? {}, [refreshTokenFingerprint(refreshToken)]: { reason, at: now } }).filter(([key, value]) => /^[a-f0-9]{32}$/.test(key) && value && Number.isFinite(value.at) && value.at > now - RETIRED_RETENTION_SECONDS).sort(([, a], [, b]) => b.at - a.at).slice(0, RETIRED_MAX_ENTRIES);
-  config.retiredRefreshTokens = Object.fromEntries(entries);
+  const entry = inFlight ? { reason, at: now, inFlight: true } : { reason, at: now };
+  const held = new Set(allSlots(config).map(slotRefreshToken).filter((token) => Boolean(token)).map(refreshTokenFingerprint));
+  const valid = Object.entries({ ...config.retiredRefreshTokens ?? {}, [refreshTokenFingerprint(refreshToken)]: entry }).filter(([key, value]) => /^[a-f0-9]{32}$/.test(key) && value && Number.isFinite(value.at));
+  const kept = valid.filter(([key]) => held.has(key));
+  const others = valid.filter(([key, value]) => !held.has(key) && value.at > now - RETIRED_RETENTION_SECONDS).sort(([, a], [, b]) => b.at - a.at).slice(0, Math.max(0, RETIRED_MAX_ENTRIES - kept.length));
+  config.retiredRefreshTokens = Object.fromEntries([...kept, ...others]);
+}
+function clearInFlight(config, refreshToken) {
+  const fingerprint = refreshTokenFingerprint(refreshToken);
+  if (!config.retiredRefreshTokens?.[fingerprint]?.inFlight) return;
+  const { [fingerprint]: _withdrawn, ...rest } = config.retiredRefreshTokens;
+  if (Object.keys(rest).length) config.retiredRefreshTokens = rest;
+  else delete config.retiredRefreshTokens;
 }
 function environmentSlots(config, environment) {
   const slots = [];
@@ -4939,6 +4975,20 @@ function loginCommand(environment, key) {
   const use = environment === "production" ? "topolo context use" : `topolo --env ${environment} context use`;
   return `${base} && ${use} ${key.slice(4)}`;
 }
+function slotUsers(profile, key) {
+  const context = key === DEFAULT_SLOT ? void 0 : profile.contexts?.[key];
+  const credentials = [context?.credential, key === DEFAULT_SLOT || profile.activeContext === key ? profile.credential : void 0];
+  const users = [
+    context?.userId,
+    ...credentials.map((credential) => credential?.kind === "access_token" ? accessTokenSubject(credential.accessToken) : void 0),
+    profile.reauthorization?.[key]?.expectedSubject
+  ];
+  return new Set(users.filter((user) => typeof user === "string" && user.length > 0));
+}
+function mismatchState(entry) {
+  if (!entry.mismatch) return "unavailable";
+  return entry.mismatch.differentUser ? "user_mismatch" : "organization_mismatch";
+}
 function contextLabel(key) {
   return key === DEFAULT_SLOT ? "default" : key;
 }
@@ -4950,6 +5000,8 @@ function reauthRequired(environment, key, entry, state) {
   let action;
   if (state === "awaiting_approval" && pending) {
     action = ` Approve the new sign-in: open ${pending.verificationUriComplete ?? pending.verificationUri} and confirm code ${pending.userCode} (expires ${new Date(pending.expiresAt * 1e3).toISOString()}). The next call resumes once approved.`;
+  } else if (state === "user_mismatch") {
+    action = ` The last approval was by a different user than the one signed in to ${contextLabel(key)}; it was discarded. Approve again as that user, or sign out first to replace this sign-in.`;
   } else if (state === "organization_mismatch") {
     action = ` The last approval was for ${entry?.mismatch?.approvedContext ?? "another context"}, not ${contextLabel(key)}; approve again with that organization selected.`;
   } else if (state === "denied") {
@@ -4957,7 +5009,7 @@ function reauthRequired(environment, key, entry, state) {
   } else {
     action = "";
   }
-  return new TopoloReauthRequiredError(`${head}${action} Or sign in again: ${command} (context ${contextLabel(key)}).`, {
+  return new TopoloReauthRequiredError2(`${head}${action} Or sign in again: ${command} (context ${contextLabel(key)}).`, {
     environment,
     context: contextLabel(key),
     reason,
@@ -5035,18 +5087,94 @@ function writeContextCredential(config, environment, ctx, makeActive = true) {
   }
   return writeProfileConfig(config, environment, next);
 }
-function clearProfileCredential(config, environment) {
-  const next = { ...config };
+function clearEnvironmentSignIn(config, environment) {
+  const next = clone(config);
   if (environment === "production") {
     delete next.credential;
     delete next.oauthClientId;
   }
-  const profiles = { ...config.profiles ?? {} };
-  const profile = { ...profiles[environment] ?? {} };
-  delete profile.credential;
-  delete profile.oauthClientId;
-  profiles[environment] = profile;
-  return { ...next, profiles };
+  const profile = next.profiles?.[environment];
+  if (profile) {
+    delete profile.credential;
+    delete profile.oauthClientId;
+    delete profile.activeContext;
+    delete profile.contexts;
+    delete profile.reauthorization;
+  }
+  return next;
+}
+async function signOut(environment, options = {}) {
+  const result = { environment, contexts: [], revoked: 0, revocationFailed: 0 };
+  if (!existsSync2(configPath())) return result;
+  let grants = [];
+  let profile = {};
+  const collect = (config, found, keys) => {
+    const owner = profileForEnvironment(config, environment);
+    for (const slot of environmentSlots(config, environment)) {
+      const credential = slot.holder.credential;
+      if (!credential) continue;
+      keys?.add(slot.key);
+      if (credential.kind !== "access_token") continue;
+      const clientId = slot.holder.oauthClientId ?? owner.oauthClientId;
+      found.set(credential.accessToken, {
+        accessToken: credential.accessToken,
+        ...credential.refreshToken ? { refreshToken: credential.refreshToken } : {},
+        ...clientId ? { clientId } : {}
+      });
+    }
+  };
+  await withConfigWriteLock(async (_assertOwned, persist) => {
+    let found = /* @__PURE__ */ new Map();
+    await persist((current) => {
+      profile = profileForEnvironment(current, environment);
+      const keys = /* @__PURE__ */ new Set();
+      found = /* @__PURE__ */ new Map();
+      collect(current, found, keys);
+      for (const key of Object.keys(current.profiles?.[environment]?.reauthorization ?? {})) keys.add(key);
+      result.contexts = [...keys].map(contextLabel).sort();
+      return clearEnvironmentSignIn(current, environment);
+    });
+    const directory = dirname2(configPath());
+    for (const name of readdirSync(directory)) {
+      if (!name.startsWith(".credential-write-")) continue;
+      const path = join3(directory, name);
+      try {
+        const entry = lstatSync(path);
+        if (!entry.isFile() || entry.nlink !== 1) continue;
+        try {
+          const leftover = JSON.parse(readFileSync2(path, "utf8"));
+          if (isConfigObject(leftover)) collect(leftover, found);
+        } catch {
+        }
+        unlinkSync(path);
+      } catch {
+      }
+    }
+    grants = [...found.values()];
+  });
+  if (options.revoke === false || !grants.length) return result;
+  let oauth;
+  try {
+    oauth = boundedOAuth(authServiceUrls(profile, environment, "sign-out"));
+  } catch {
+    result.revocationFailed = grants.length;
+    return result;
+  }
+  const outcomes = await Promise.all(grants.map(async (grant) => {
+    try {
+      if (!grant.clientId) return false;
+      if (grant.refreshToken) {
+        await oauth.revokeToken({ clientId: grant.clientId, token: grant.refreshToken, tokenTypeHint: "refresh_token" });
+      }
+      await oauth.revokeToken({ clientId: grant.clientId, token: grant.accessToken, tokenTypeHint: "access_token" });
+      return true;
+    } catch {
+      return false;
+    }
+  }));
+  result.revoked = outcomes.filter(Boolean).length;
+  result.revocationFailed = outcomes.length - result.revoked;
+  return result;
 }
 function credentialSourceFromConfig(config, environment = selectedEnvironment()) {
   const prefix = envVarPrefix(environment);
@@ -5069,8 +5197,8 @@ async function resolveCredential(environment = selectedEnvironment()) {
 }
 var REFRESH_SKEW_SECONDS = 60;
 var CONFIG_LOCK_RETRY_MS = 25;
-var CONFIG_LOCK_DEFAULT_TIMEOUT_MS = 15e3;
-var AUTH_EXCHANGE_TIMEOUT_MS = 1e4;
+var CONFIG_LOCK_DEFAULT_TIMEOUT_MS = 3e4;
+var AUTH_EXCHANGE_TIMEOUT_MS = 2e4;
 function configLockTimeoutMs() {
   const value = Number(process.env.TOPOLO_CONFIG_LOCK_TIMEOUT_MS);
   return Number.isFinite(value) && value >= 1e3 && value <= 12e4 ? value : CONFIG_LOCK_DEFAULT_TIMEOUT_MS;
@@ -5078,6 +5206,8 @@ function configLockTimeoutMs() {
 function boundedOAuth(serviceUrls) {
   const fetchImpl = (input2, init) => globalThis.fetch(input2, {
     ...init,
+    // Never re-POST a refresh token, device code or revoked token to another origin.
+    redirect: "error",
     signal: init?.signal ?? AbortSignal.timeout(AUTH_EXCHANGE_TIMEOUT_MS)
   });
   return new TopoloOAuth2({ serviceUrls, fetch: fetchImpl });
@@ -5126,6 +5256,61 @@ function readOwnerMarker(lockPath, name) {
   if (owner.version !== 1 || Object.keys(owner).sort().join(",") !== "identity,pid,version" || name !== "owner-" + owner.identity + ".json" || !Number.isSafeInteger(owner.pid) || owner.pid <= 0) throw new ConfigOwnershipError();
   return { bytes, pid: owner.pid };
 }
+function inspectConfigLockAt(path, ignoreOwnFence = false) {
+  const lockPath = path + ".lock";
+  let state = "UNKNOWN";
+  let reason = "UNVERIFIED_CUSTODY";
+  let witness = "unverified";
+  try {
+    const parent = lstatSync(dirname2(lockPath));
+    if (!parent.isDirectory() || parent.isSymbolicLink() || parent.uid !== process.getuid?.() || parent.mode & 18) throw new ConfigOwnershipError();
+    const parentIdentity = [parent.dev, parent.ino, parent.uid, parent.mode];
+    if (!existsSync2(lockPath)) {
+      try {
+        lstatSync(lockPath);
+        throw new ConfigOwnershipError();
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+      state = "FREE";
+      reason = "ABSENT";
+      witness = [parentIdentity, "absent"];
+    } else {
+      const directory = privateLockDirectory(lockPath);
+      const entries = readdirSync(lockPath).sort();
+      witness = [parentIdentity, lockIdentity(directory), entries];
+      if (entries.length === 0) reason = "EMPTY_OWNER_UNKNOWN";
+      else if (entries.length === 1 && OWNER_MARKER_NAME.test(entries[0])) {
+        const { bytes, pid } = readOwnerMarker(lockPath, entries[0]);
+        witness = [witness, createHash2("sha256").update(bytes).digest("hex")];
+        try {
+          process.kill(pid, 0);
+          state = "LIVE";
+          reason = "OWNER_PID_EXISTS";
+        } catch {
+        }
+      }
+      if (JSON.stringify(lockIdentity(lstatSync(lockPath))) !== JSON.stringify(lockIdentity(directory)) || JSON.stringify(readdirSync(lockPath).sort()) !== JSON.stringify(entries)) throw new ConfigOwnershipError();
+    }
+    if (!ignoreOwnFence && lockEntryExists(lockPath + ".reconcile")) {
+      state = "UNKNOWN";
+      reason = "RECONCILIATION_IN_PROGRESS";
+    }
+  } catch {
+    state = "UNKNOWN";
+    reason = "UNVERIFIED_CUSTODY";
+  }
+  return {
+    configPath: path,
+    lockPath,
+    state,
+    reason,
+    generation: createHash2("sha256").update(JSON.stringify([path, witness])).digest("hex")
+  };
+}
+async function inspectConfigLock() {
+  return inspectConfigLockAt(resolve2(configPath()));
+}
 function writePrivateLockRecord(path, bytes) {
   const fd = openSync(path, "wx", 384);
   try {
@@ -5135,6 +5320,107 @@ function writePrivateLockRecord(path, bytes) {
     closeSync(fd);
   }
 }
+async function reconcileConfigLock(input2) {
+  const path = resolve2(configPath());
+  const before = inspectConfigLockAt(path);
+  if (!input2 || typeof input2 !== "object") throw new ConfigOwnershipError();
+  const inputFields = Object.getOwnPropertyDescriptors(input2);
+  if (Reflect.ownKeys(inputFields).length !== 2 || typeof inputFields.expectedGeneration?.value !== "string" || !inputFields.review || !Object.prototype.hasOwnProperty.call(inputFields.review, "value")) throw new ConfigOwnershipError();
+  const supplied = inputFields.review.value;
+  if (!supplied || typeof supplied !== "object") throw new ConfigOwnershipError();
+  const fields = Object.getOwnPropertyDescriptors(supplied);
+  const names = ["kind", "configPath", "generation", "quiescenceEvidenceSha256", "reviewedBy", "expiresAt"];
+  if (Reflect.ownKeys(fields).length !== names.length || names.some((name) => !fields[name] || !Object.prototype.hasOwnProperty.call(fields[name], "value") || typeof fields[name].value !== "string")) throw new ConfigOwnershipError();
+  const expectedGeneration = inputFields.expectedGeneration.value;
+  const review = Object.freeze({
+    kind: fields.kind.value,
+    configPath: fields.configPath.value,
+    generation: fields.generation.value,
+    quiescenceEvidenceSha256: fields.quiescenceEvidenceSha256.value,
+    reviewedBy: fields.reviewedBy.value,
+    expiresAt: fields.expiresAt.value
+  });
+  const expiry = Date.parse(review.expiresAt);
+  if (review.kind !== "quiescent-empty-quarantine" || review.configPath !== path || review.generation !== expectedGeneration || before.generation !== expectedGeneration || !/^[a-f0-9]{64}$/.test(review.quiescenceEvidenceSha256) || typeof review.reviewedBy !== "string" || !/^[a-zA-Z0-9_.:-]{1,80}$/.test(review.reviewedBy) || !Number.isFinite(expiry) || expiry <= Date.now() || expiry > Date.now() + 15 * 6e4 || before.state !== "UNKNOWN" || before.reason !== "EMPTY_OWNER_UNKNOWN") throw new ConfigOwnershipError();
+  const lockPath = before.lockPath;
+  const fence = lockPath + ".reconcile";
+  const identity = randomUUID2();
+  const markerName = "owner-" + identity + ".json";
+  const marker = JSON.stringify({ version: 1, identity, pid: process.pid });
+  const quarantine = join3(dirname2(lockPath), ".credential-reconcile-" + identity);
+  const captured = join3(quarantine, "lock");
+  const receiptPath = join3(quarantine, "receipt.json");
+  let capturedLock = false;
+  let preserveFence = false;
+  try {
+    mkdirSync(fence, { mode: 448 });
+  } catch {
+    throw new ConfigOwnershipError();
+  }
+  const fenceDirectory = privateLockDirectory(fence);
+  const fenceMarker = join3(fence, markerName);
+  const assertFence = () => {
+    const entry = privateLockDirectory(fence);
+    if (entry.dev !== fenceDirectory.dev || entry.ino !== fenceDirectory.ino || readdirSync(fence).length !== 1 || readdirSync(fence)[0] !== markerName || readPrivateLockMarker(fenceMarker) !== marker) throw new ConfigOwnershipError();
+  };
+  try {
+    writePrivateLockRecord(fenceMarker, marker);
+    assertFence();
+    const current = inspectConfigLockAt(path, true);
+    if (current.state !== "UNKNOWN" || current.reason !== "EMPTY_OWNER_UNKNOWN" || current.generation !== before.generation || Date.now() >= expiry) throw new ConfigOwnershipError();
+    const directory = privateLockDirectory(lockPath);
+    mkdirSync(quarantine, { mode: 448 });
+    writePrivateLockRecord(receiptPath, JSON.stringify({
+      schemaVersion: 1,
+      disposition: "PENDING_CAPTURE",
+      classificationBefore: "UNKNOWN",
+      before,
+      review,
+      directoryIdentity: [directory.dev, directory.ino, directory.uid, directory.mode],
+      quiescence: "caller-reviewed; legacy and bare writers not globally enforced by SDK",
+      configCredentialOrOAuthEffectsByThisAPI: "none"
+    }, null, 2));
+    assertFence();
+    if (inspectConfigLockAt(path, true).generation !== before.generation || Date.now() >= expiry) throw new ConfigOwnershipError();
+    renameSync(lockPath, captured);
+    capturedLock = true;
+    const entry = privateLockDirectory(captured);
+    if (entry.dev !== directory.dev || entry.ino !== directory.ino || readdirSync(captured).length || lockEntryExists(lockPath) || Date.now() >= expiry) throw new ConfigOwnershipError();
+    assertFence();
+    writePrivateLockRecord(join3(quarantine, "outcome.json"), JSON.stringify({
+      disposition: "CAPTURE_VERIFIED_PENDING_FENCE_CLOSURE",
+      classificationBefore: "UNKNOWN",
+      fenceClosureVerified: false,
+      noDeathOrPriorRemoteEffectResolutionInferred: true
+    }));
+  } catch (error) {
+    if (!capturedLock) throw error instanceof ConfigOwnershipError ? error : new ConfigOwnershipError();
+    preserveFence = true;
+    return { outcome: "UNRESOLVED_CAPTURE", before, quarantinePath: quarantine, receiptPath, fenceRetained: true };
+  } finally {
+    if (!preserveFence) {
+      try {
+        assertFence();
+        const capturedMarker = join3(quarantine, markerName);
+        if (!lockEntryExists(quarantine)) mkdirSync(quarantine, { mode: 448 });
+        renameSync(fenceMarker, capturedMarker);
+        const entry = privateLockDirectory(fence);
+        if (entry.dev !== fenceDirectory.dev || entry.ino !== fenceDirectory.ino || readdirSync(fence).length || readPrivateLockMarker(capturedMarker) !== marker) {
+          try {
+            linkSync(capturedMarker, fenceMarker);
+          } catch {
+          }
+          throw new ConfigOwnershipError();
+        }
+        rmdirSync(fence);
+      } catch {
+        if (capturedLock) return { outcome: "UNRESOLVED_CAPTURE", before, quarantinePath: quarantine, receiptPath, fenceRetained: true };
+        throw new ConfigOwnershipError();
+      }
+    }
+  }
+  return { outcome: "QUARANTINED_UNKNOWN_EMPTY", before, quarantinePath: quarantine, receiptPath, fenceRetained: false };
+}
 function deadOwnerMarker(lockPath, ignoreOwnFence = false) {
   try {
     if (!ignoreOwnFence && lockEntryExists(lockPath + ".reconcile")) return null;
@@ -5209,6 +5495,12 @@ function reclaimDeadOwnerLock(lockPath, markerName, marker) {
   return reclaimed;
 }
 var RELEASE_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+function unreadableConfig(path) {
+  return new TopoloSdkError2(
+    "config_unreadable",
+    `The Topolo configuration at ${path} is not a valid JSON object, so it was left unchanged. Repair or move it, then retry.`
+  );
+}
 var PERSIST_ATTEMPTS = 3;
 async function withConfigWriteLock(operation) {
   const lockPath = `${configPath()}.lock`;
@@ -5291,11 +5583,14 @@ async function withConfigWriteLock(operation) {
         const before = snapshot();
         let current = {};
         if (before !== null) {
+          let parsed = {};
           try {
-            current = JSON.parse(before);
-          } catch (error) {
-            if (!options.allowCreate) throw error;
+            if (before.trim()) parsed = JSON.parse(before);
+          } catch {
+            throw unreadableConfig(path);
           }
+          if (!isConfigObject(parsed)) throw unreadableConfig(path);
+          current = parsed;
         }
         const updated = update(current);
         const fd = openSync(temporary, "wx", 384);
@@ -5377,7 +5672,8 @@ async function withConfigWriteLock(operation) {
 function renewalFailure(error) {
   const path = "/api/developer-oauth/token";
   if (error instanceof ConfigOwnershipError) return new ConfigOwnershipError();
-  if (error instanceof TopoloReauthRequiredError) return error;
+  if (error instanceof TopoloReauthRequiredError2) return error;
+  if (error instanceof TopoloSdkError2 && error.code === "config_unreadable") return error;
   if ((error instanceof TopoloAuthError2 || error instanceof TopoloHttpError2) && error.status === 429) {
     const message3 = "Topolo sign-in renewal is temporarily rate limited by Auth. Retry after the Retry-After interval; the saved sign-in has been retained.";
     return new TopoloRateLimitError2(
@@ -5453,6 +5749,35 @@ function singleFlight(key, run) {
   renewalsInFlight.set(key, started);
   return started;
 }
+var GATEWAY_STATUSES = /* @__PURE__ */ new Set([502, 504, 520, 521, 522, 523, 524, 525, 526, 527, 530]);
+var NOT_SENT_CODES = /* @__PURE__ */ new Set([
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "EAI_NONAME",
+  "ECONNREFUSED",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "EADDRNOTAVAIL",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "CERT_HAS_EXPIRED",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "ERR_TLS_CERT_ALTNAME_INVALID"
+]);
+function answeredWithoutRotation(error) {
+  if (error instanceof TopoloAuthError2 || error instanceof TopoloHttpError2) return !GATEWAY_STATUSES.has(Number(error.status));
+  for (let cause = error, depth = 0; cause && depth < 4; cause = cause.cause, depth += 1) {
+    const code = cause.code;
+    if (typeof code === "string" && NOT_SENT_CODES.has(code)) return true;
+  }
+  return false;
+}
+function usableTokenResponse(tokens) {
+  if (!tokens || typeof tokens !== "object") return false;
+  const value = tokens;
+  return typeof value.access_token === "string" && value.access_token.length > 0 && typeof value.expires_in === "number" && Number.isFinite(value.expires_in) && (value.refresh_token === void 0 || typeof value.refresh_token === "string" && value.refresh_token.length > 0);
+}
 async function renewTarget(environment, target, options) {
   const observedProfile = profileForEnvironment(await readConfig(), environment);
   const observedTarget = resolveTarget(observedProfile, target);
@@ -5474,6 +5799,7 @@ async function renewTarget(environment, target, options) {
       if (options.force && observed.kind === "access_token" && observed.accessToken !== credential.accessToken && credential.expiresAt !== void 0 && credential.expiresAt > now) return { credential };
       if (!options.force && credential.expiresAt && credential.expiresAt - REFRESH_SKEW_SECONDS > now) return { credential };
       const sent = credential.refreshToken;
+      const subject = accessTokenSubject(credential.accessToken) ?? resolved.context?.userId;
       const endGrant = async (reason) => {
         await persist((current) => {
           const next = clone(current);
@@ -5481,35 +5807,67 @@ async function renewTarget(environment, target, options) {
           touched.add(resolved.key);
           retire(next, sent, reason);
           for (const key of touched) {
-            setReauthorization(next, environment, key, (existing) => ({ ...existing, reason, since: existing?.since ?? nowSeconds() }));
+            setReauthorization(next, environment, key, (existing) => ({
+              ...subject ? { expectedSubject: subject } : {},
+              ...existing,
+              reason,
+              since: existing?.since ?? nowSeconds()
+            }));
           }
           return next;
         });
         return { reauthorize: resolved.key };
       };
+      const outcomeUnknown = async () => {
+        if (!options.force && credential.expiresAt && credential.expiresAt > nowSeconds()) return { credential };
+        return endGrant("rotated_grant_lost");
+      };
       const retired = retiredEntry(config, sent);
       if (retired) {
         return endGrant(retired.reason === "rotated" ? "rotated_grant_lost" : retired.reason);
       }
       const serviceUrls = authServiceUrls(profile, environment, target.kind === "active" ? "credential refresh" : "context refresh");
+      const oauth = boundedOAuth(serviceUrls);
+      try {
+        await persist((current) => {
+          const next = clone(current);
+          retire(next, sent, "rotated", true);
+          return next;
+        });
+      } catch (error) {
+        throw error instanceof TopoloSdkError2 ? renewalFailure(error) : new TopoloSdkError2("config_write_failed", "The Topolo configuration could not be updated, so the sign-in was not renewed. Nothing was sent to Auth; the saved sign-in has been retained.");
+      }
       let tokens;
       try {
-        tokens = await boundedOAuth(serviceUrls).refreshToken({ clientId: resolved.oauthClientId, refreshToken: sent });
+        tokens = await oauth.refreshToken({ clientId: resolved.oauthClientId, refreshToken: sent });
       } catch (error) {
         if (isTerminalRefusal(error)) return endGrant(error.code);
+        if (!answeredWithoutRotation(error)) return outcomeUnknown();
+        try {
+          await persist((current) => {
+            const next = clone(current);
+            clearInFlight(next, sent);
+            return next;
+          });
+        } catch (persistError) {
+          throw renewalFailure(persistError);
+        }
         throw renewalFailure(error);
       }
+      if (!usableTokenResponse(tokens)) return outcomeUnknown();
+      const issued = tokens;
       const refreshed = {
         kind: "access_token",
-        accessToken: tokens.access_token,
-        refreshToken: tokens.refresh_token ?? sent,
-        expiresAt: nowSeconds() + tokens.expires_in
+        accessToken: issued.access_token,
+        refreshToken: issued.refresh_token ?? sent,
+        expiresAt: nowSeconds() + issued.expires_in
       };
       try {
         await persist((current) => {
           const next = clone(current);
           replaceGrant(next, environment, sent, refreshed);
-          if (tokens.refresh_token && tokens.refresh_token !== sent) retire(next, sent, "rotated");
+          if (issued.refresh_token && issued.refresh_token !== sent) retire(next, sent, "rotated");
+          else clearInFlight(next, sent);
           return next;
         });
       } catch (error) {
@@ -5529,17 +5887,30 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment(), op
 async function refreshContextCredentialIfNeeded(environment, key, options = {}) {
   return renewTarget(environment, { kind: "context", key }, options);
 }
-function decodeTokenOrganization(accessToken) {
+function accessTokenClaims(accessToken) {
   try {
-    const payload = accessToken.split(".")[1];
-    if (!payload) return { known: false, organizationId: null };
+    const payload = accessToken?.split(".")[1];
+    if (!payload) return null;
     const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-    const org = claims.orgId ?? claims.organizationId ?? claims.org_id ?? null;
-    return { known: true, organizationId: typeof org === "string" && org ? org : null };
+    return claims && typeof claims === "object" && !Array.isArray(claims) ? claims : null;
   } catch {
-    return { known: false, organizationId: null };
+    return null;
   }
 }
+function accessTokenSubject(accessToken) {
+  const sub = accessTokenClaims(accessToken)?.sub;
+  return typeof sub === "string" && sub ? sub : void 0;
+}
+function accessTokenExpiry(accessToken) {
+  const exp = accessTokenClaims(accessToken)?.exp;
+  return typeof exp === "number" && Number.isSafeInteger(exp) && exp > 0 ? exp : void 0;
+}
+function decodeTokenOrganization(accessToken) {
+  const claims = accessTokenClaims(accessToken);
+  if (!claims) return { known: false, organizationId: null };
+  const org = claims.orgId ?? claims.organizationId ?? claims.org_id ?? null;
+  return { known: true, organizationId: typeof org === "string" && org ? org : null };
+}
 async function continueReauthorization(environment, key) {
   return withConfigWriteLock(async (_assertOwned, persist) => {
     const config = await readConfig();
@@ -5596,7 +5967,21 @@ async function continueReauthorization(environment, key) {
         };
         const organization = decodeTokenOrganization(tokens.access_token);
         const approvedKey = organization.known ? organization.organizationId ? `org:${organization.organizationId}` : "personal" : null;
+        const approvedSubject = accessTokenSubject(tokens.access_token);
         const matches = key === DEFAULT_SLOT || approvedKey === key;
+        const destination = matches ? key : approvedKey;
+        const destinationUsers = destination ? slotUsers(profile, destination) : /* @__PURE__ */ new Set();
+        if (state.expectedSubject) destinationUsers.add(state.expectedSubject);
+        if ([...destinationUsers].some((user) => user !== approvedSubject)) {
+          const updated = {
+            ...state,
+            mismatch: { approvedContext: "a different user", at: nowSeconds(), differentUser: true }
+          };
+          delete updated.pending;
+          await save(() => updated);
+          throw reauthRequired(environment, key, updated, "user_mismatch");
+        }
+        const signedInAs = approvedSubject ? { userId: approvedSubject } : {};
         await persist((current) => {
           const next = clone(current);
           const nextProfile = (next.profiles ??= {})[environment] ??= {};
@@ -5610,7 +5995,8 @@ async function continueReauthorization(environment, key) {
               nextProfile.contexts = { ...nextProfile.contexts ?? {}, [key]: {
                 ...existing ?? (key.startsWith("org:") ? { contextType: "organization", organizationId: key.slice(4) } : { contextType: "personal" }),
                 credential: approved,
-                oauthClientId: clientId
+                oauthClientId: clientId,
+                ...signedInAs
               } };
               if (nextProfile.activeContext === key) nextProfile.credential = approved;
             }
@@ -5621,7 +6007,8 @@ async function continueReauthorization(environment, key) {
               nextProfile.contexts = { ...nextProfile.contexts ?? {}, [approvedKey]: {
                 ...existing ?? (approvedKey.startsWith("org:") ? { contextType: "organization", organizationId: approvedKey.slice(4) } : { contextType: "personal" }),
                 credential: approved,
-                oauthClientId: clientId
+                oauthClientId: clientId,
+                ...signedInAs
               } };
               if (nextProfile.activeContext === approvedKey) nextProfile.credential = approved;
             }
@@ -5645,7 +6032,7 @@ async function continueReauthorization(environment, key) {
       throw reauthRequired(environment, key, state, pending.denied ? "denied" : "awaiting_approval");
     }
     if (state.startRetryAt && state.startRetryAt > now) {
-      throw reauthRequired(environment, key, state, state.mismatch ? "organization_mismatch" : "unavailable");
+      throw reauthRequired(environment, key, state, mismatchState(state));
     }
     try {
       const started = await oauth.requestDeviceCode({ clientId });
@@ -5666,7 +6053,7 @@ async function continueReauthorization(environment, key) {
       await save(() => state);
       throw reauthRequired(environment, key, state, "awaiting_approval");
     } catch (error) {
-      if (error instanceof TopoloReauthRequiredError || error instanceof ConfigOwnershipError) throw error;
+      if (error instanceof TopoloReauthRequiredError2 || error instanceof ConfigOwnershipError) throw error;
       const retryAfter = Number(error.retryAfter);
       state = { ...state, startRetryAt: now + Math.max(30, Number.isFinite(retryAfter) ? retryAfter : 0) };
       delete state.pending;
@@ -5684,7 +6071,7 @@ async function awaitReauthorization(environment, key, options = {}) {
     try {
       return await continueReauthorization(environment, slotKey);
     } catch (error) {
-      if (!(error instanceof TopoloReauthRequiredError)) throw error;
+      if (!(error instanceof TopoloReauthRequiredError2)) throw error;
       const prompt = error.reauthorization;
       if (prompt.userCode !== lastCode) {
         lastCode = prompt.userCode;
@@ -5732,110 +6119,6 @@ function resolvedProfileConfig(config, environment = selectedEnvironment()) {
   };
 }
 
-// src/config.ts
-async function authenticatedEnvironments(configOrPromise = readConfig()) {
-  const config = await configOrPromise;
-  const found = /* @__PURE__ */ new Set();
-  if (config.credential) found.add("production");
-  for (const environment of TOPOLO_ENVIRONMENTS) {
-    const profile = config.profiles?.[environment];
-    if (!profile) continue;
-    if (profile.credential || Object.keys(profile.contexts ?? {}).length > 0) {
-      found.add(environment);
-    }
-  }
-  return TOPOLO_ENVIRONMENTS.filter((environment) => found.has(environment));
-}
-function environmentLabel(environment = selectedEnvironment()) {
-  return environment;
-}
-function developerConsoleUrl(environment = selectedEnvironment()) {
-  if (environment === "production") return "https://developers.topolo.app";
-  if (environment === "development") return "https://developers.topolo.dev";
-  return "https://developers.stg.topolo.us";
-}
-function oauthClientRegistrationUrl(environment = selectedEnvironment()) {
-  return `${developerConsoleUrl(environment)}/developers/oauth-clients`;
-}
-function apiKeyIssuanceUrl(environment = selectedEnvironment()) {
-  return `${developerConsoleUrl(environment)}/credentials`;
-}
-var DEFAULT_CLI_CLIENT_IDS = {
-  production: "topolo-cli",
-  staging: "topolo-cli",
-  development: "topolo-cli"
-};
-function resolveOAuthClientId(config, environment = selectedEnvironment()) {
-  const envSpecific = process.env[`${envVarPrefix(environment)}_CLI_CLIENT_ID`];
-  if (envSpecific) return envSpecific;
-  if (process.env.TOPOLO_CLI_CLIENT_ID) return process.env.TOPOLO_CLI_CLIENT_ID;
-  return DEFAULT_CLI_CLIENT_IDS[environment] ?? profileForEnvironment(config, environment).oauthClientId;
-}
-function signedInContextKeys(config, environment) {
-  return Object.keys(profileForEnvironment(config, environment).contexts ?? {});
-}
-function matchContextSelector(config, environment, selector) {
-  const normalized = selector.trim().toLowerCase();
-  if (!normalized || /[\r\n]/.test(selector)) {
-    throw new Error("Context must be a non-empty single-line identifier.");
-  }
-  const contexts = Object.entries(profileForEnvironment(config, environment).contexts ?? {});
-  const exact = contexts.find(([key]) => key.toLowerCase() === normalized);
-  if (exact) return exact[0];
-  const matches = contexts.filter(([, context]) => [
-    context.organizationId,
-    context.organizationSlug,
-    context.organizationName
-  ].some((value) => String(value || "").trim().toLowerCase() === normalized));
-  if (matches.length > 1) {
-    throw new Error(`Context "${selector.trim()}" is ambiguous in ${environment}; use an exact key from \`topolo --env ${environment} context ls\`.`);
-  }
-  return matches[0]?.[0] ?? null;
-}
-function commandContextKey(config, environment, explicit = process.env.TOPOLO_CONTEXT) {
-  const selector = explicit?.trim();
-  if (selector) return matchContextSelector(config, environment, selector) ?? selector;
-  return implicitContextKey(config, environment) ?? void 0;
-}
-function implicitContextKey(config, environment) {
-  if (credentialSourceFromConfig(config, environment).startsWith("env:")) return null;
-  const keys = signedInContextKeys(config, environment);
-  if (keys.length > 1) throw new ContextNotSafeToAssumeError(environment, keys);
-  return keys[0] ?? null;
-}
-var ContextNotSafeToAssumeError = class extends Error {
-  constructor(environment, contexts) {
-    super(
-      `This machine is signed in to ${contexts.length} Topolo contexts in ${environment} (${contexts.join(", ")}), so the context is no longer safe to assume.
-
-State it explicitly:
-  topolo --env ${environment} --context <${contexts.join("|")}> ...
-
-Or set it once for the whole session:
-  export TOPOLO_CONTEXT=<${contexts.join("|")}>`
-    );
-    this.environment = environment;
-    this.contexts = contexts;
-    this.name = "ContextNotSafeToAssumeError";
-  }
-  environment;
-  contexts;
-};
-async function withPinnedContext(options, read = () => readConfig()) {
-  if (options.context?.trim() || options.installationId?.trim()) return options;
-  const environment = normalizeEnvironment(options.environment?.trim() || process.env.TOPOLO_ENV || "production");
-  const keys = signedInContextKeys(await read(), environment);
-  if (keys.length === 1) return { ...options, context: keys[0] };
-  if (!keys.length) {
-    throw new Error(
-      `No Topolo context is signed in for ${environment}, so there is nothing to pin. Run \`topolo --env ${environment} auth login\` first, or pass --context <context>.`
-    );
-  }
-  throw new Error(
-    `${keys.length} Topolo contexts are signed in for ${environment} (${keys.join(", ")}). Pass --context <context> to choose the one this MCP registration pins.`
-  );
-}
-
 // src/output.ts
 function resolveOutputMode(override) {
   if (override === true) return "json";
@@ -5895,6 +6178,7 @@ function normalizeError(err) {
     };
     const body = err.body;
     const status = err.status;
+    const localLockConflict = code === "state_conflict" && status === void 0 && body === void 0 && err.service === void 0;
     const suppliedDetails = err.details;
     return {
       message: status !== void 0 || body !== void 0 ? publicTopoloErrorMessage({ code, body, status, message: err.message }) : err.message,
@@ -5907,7 +6191,7 @@ function normalizeError(err) {
       // SDK HTTP errors already carry sanitized details; projecting them again
       // would drop form-level issues that have no field path.
       details: reauthorizationDetails(err) ?? (err instanceof TopoloHttpError || err instanceof TopoloAuthError || err instanceof TopoloPermissionError ? err.details : extractTopoloServiceErrorDetails(suppliedDetails === void 0 ? body : { details: suppliedDetails })),
-      hint: reauthorizationHint(err) ?? topoloErrorHint({ code, body }) ?? (code ? fallbackHintMap[code] : void 0),
+      hint: reauthorizationHint(err) ?? topoloErrorHint({ code, body }) ?? (localLockConflict ? "The saved sign-in is locked by another or an interrupted Topolo process. Run `topolo auth lock` to see who holds it and how to recover." : code ? fallbackHintMap[code] : void 0),
       exitCode: status === 401 || code === "auth_error" || code === "confirmation_required" ? 2 : status === 403 || code === "permission_denied" ? 3 : code === "immutable_drift" ? 4 : 1
     };
   }
@@ -5968,9 +6252,214 @@ function readCliVersion() {
 }
 var CLI_VERSION = readCliVersion();
 
+// src/commands/auth-lock.ts
+var QUIESCENCE_WAIT_MS = 2e3;
+var REVIEW_TTL_MS = 5 * 6e4;
+function lockGuidance(diagnostic) {
+  const { state, reason, lockPath, generation } = diagnostic;
+  if (state === "FREE") return "No lock is held. Sign-in renewal is not blocked.";
+  if (state === "LIVE") {
+    return `A running process holds the lock; a renewal normally finishes within 10 seconds. If it stays held after every Topolo CLI and MCP process has exited (after a restart the recorded process number can belong to another program), quit them all and move ${lockPath} aside.`;
+  }
+  if (reason === "EMPTY_OWNER_UNKNOWN") {
+    return `An empty lock was left by an interrupted writer. Close other Topolo CLI and MCP processes, then run:
+  topolo auth lock --reconcile ${generation}`;
+  }
+  if (reason === "RECONCILIATION_IN_PROGRESS") {
+    return `A lock recovery is running or was interrupted (${lockPath}.reconcile). Wait for it, or if no Topolo process is running, keep the fence for review and move both paths aside.`;
+  }
+  return `The lock's owner cannot be verified on this system (unexpected owner, permissions or platform). If no Topolo CLI or MCP process is running, move ${lockPath} aside.`;
+}
+function registerAuthLockCommand(auth) {
+  auth.command("lock").description("Inspect, and recover, the lock that serializes sign-in renewal").option("--reconcile <generation>", "Quarantine an empty lock left by an interrupted writer (generation from `topolo auth lock`)").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const diagnostic = await inspectConfigLock();
+      if (opts.reconcile === void 0) {
+        emit(
+          { lock: diagnostic, guidance: lockGuidance(diagnostic) },
+          mode,
+          () => [
+            `Lock:       ${diagnostic.lockPath}`,
+            `State:      ${diagnostic.state} (${diagnostic.reason})`,
+            `Generation: ${diagnostic.generation}`,
+            "",
+            lockGuidance(diagnostic)
+          ].join("\n")
+        );
+        return;
+      }
+      const generation = opts.reconcile.trim();
+      if (diagnostic.state !== "UNKNOWN" || diagnostic.reason !== "EMPTY_OWNER_UNKNOWN") {
+        throw new Error(`Only an empty lock left by an interrupted writer can be reconciled; this lock is ${diagnostic.state} (${diagnostic.reason}). ${lockGuidance(diagnostic)}`);
+      }
+      if (diagnostic.generation !== generation) {
+        throw new Error("The lock changed since it was inspected. Run `topolo auth lock` again and use the generation it prints.");
+      }
+      await new Promise((resolve6) => setTimeout(resolve6, QUIESCENCE_WAIT_MS));
+      const settled = await inspectConfigLock();
+      if (settled.generation !== generation) {
+        throw new Error("The lock changed while waiting, so another process is using it. Nothing was changed.");
+      }
+      const evidence = JSON.stringify({
+        observer: `topolo-cli/${CLI_VERSION}`,
+        before: diagnostic,
+        after: settled,
+        waitedMs: QUIESCENCE_WAIT_MS
+      });
+      const result = await reconcileConfigLock({
+        expectedGeneration: generation,
+        review: {
+          kind: "quiescent-empty-quarantine",
+          configPath: diagnostic.configPath,
+          generation,
+          quiescenceEvidenceSha256: createHash3("sha256").update(evidence).digest("hex"),
+          reviewedBy: "topolo-cli:auth-lock",
+          expiresAt: new Date(Date.now() + REVIEW_TTL_MS).toISOString()
+        }
+      });
+      const recovered = result.outcome === "QUARANTINED_UNKNOWN_EMPTY";
+      if (!recovered) process.exitCode = 1;
+      emit(
+        { ok: recovered, outcome: result.outcome, quarantinePath: result.quarantinePath, fenceRetained: result.fenceRetained },
+        mode,
+        () => recovered ? `Recovered: the empty lock was moved to ${result.quarantinePath}. Sign-in renewal can proceed.` : `Not recovered: the lock changed during capture. Evidence and the recovery fence were kept in ${result.quarantinePath} for review.`
+      );
+    } catch (error) {
+      fail2(error, mode);
+    }
+  });
+}
+
+// src/lib/open-browser.ts
+import { spawn } from "child_process";
+import { platform as platform2 } from "os";
+function tryOpenBrowser(url) {
+  try {
+    const os = platform2();
+    const cmd = os === "darwin" ? "open" : os === "win32" ? "start" : "xdg-open";
+    const args = os === "win32" ? ["", url] : [url];
+    const child = spawn(cmd, args, {
+      detached: true,
+      stdio: "ignore",
+      ...os === "win32" ? { shell: true } : {}
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/config.ts
+async function authenticatedEnvironments(configOrPromise = readConfig()) {
+  const config = await configOrPromise;
+  const found = /* @__PURE__ */ new Set();
+  if (config.credential) found.add("production");
+  for (const environment of TOPOLO_ENVIRONMENTS) {
+    const profile = config.profiles?.[environment];
+    if (!profile) continue;
+    if (profile.credential || Object.keys(profile.contexts ?? {}).length > 0) {
+      found.add(environment);
+    }
+  }
+  return TOPOLO_ENVIRONMENTS.filter((environment) => found.has(environment));
+}
+function environmentLabel(environment = selectedEnvironment()) {
+  return environment;
+}
+function developerConsoleUrl(environment = selectedEnvironment()) {
+  if (environment === "production") return "https://developers.topolo.app";
+  if (environment === "development") return "https://developers.topolo.dev";
+  return "https://developers.stg.topolo.us";
+}
+function oauthClientRegistrationUrl(environment = selectedEnvironment()) {
+  return `${developerConsoleUrl(environment)}/developers/oauth-clients`;
+}
+function apiKeyIssuanceUrl(environment = selectedEnvironment()) {
+  return `${developerConsoleUrl(environment)}/credentials`;
+}
+var DEFAULT_CLI_CLIENT_IDS = {
+  production: "topolo-cli",
+  staging: "topolo-cli",
+  development: "topolo-cli"
+};
+function resolveOAuthClientId(config, environment = selectedEnvironment()) {
+  const envSpecific = process.env[`${envVarPrefix(environment)}_CLI_CLIENT_ID`];
+  if (envSpecific) return envSpecific;
+  if (process.env.TOPOLO_CLI_CLIENT_ID) return process.env.TOPOLO_CLI_CLIENT_ID;
+  return DEFAULT_CLI_CLIENT_IDS[environment] ?? profileForEnvironment(config, environment).oauthClientId;
+}
+function signedInContextKeys(config, environment) {
+  return Object.keys(profileForEnvironment(config, environment).contexts ?? {});
+}
+function matchContextSelector(config, environment, selector) {
+  const normalized = selector.trim().toLowerCase();
+  if (!normalized || /[\r\n]/.test(selector)) {
+    throw new Error("Context must be a non-empty single-line identifier.");
+  }
+  const contexts = Object.entries(profileForEnvironment(config, environment).contexts ?? {});
+  const exact = contexts.find(([key]) => key.toLowerCase() === normalized);
+  if (exact) return exact[0];
+  const matches = contexts.filter(([, context]) => [
+    context.organizationId,
+    context.organizationSlug,
+    context.organizationName
+  ].some((value) => String(value || "").trim().toLowerCase() === normalized));
+  if (matches.length > 1) {
+    throw new Error(`Context "${selector.trim()}" is ambiguous in ${environment}; use an exact key from \`topolo --env ${environment} context ls\`.`);
+  }
+  return matches[0]?.[0] ?? null;
+}
+function commandContextKey(config, environment, explicit = process.env.TOPOLO_CONTEXT) {
+  const selector = explicit?.trim();
+  if (selector) return matchContextSelector(config, environment, selector) ?? selector;
+  return implicitContextKey(config, environment) ?? void 0;
+}
+function implicitContextKey(config, environment) {
+  if (credentialSourceFromConfig(config, environment).startsWith("env:")) return null;
+  if (profileForEnvironment(config, environment).credential?.kind === "api_key") return null;
+  const keys = signedInContextKeys(config, environment);
+  if (keys.length > 1) throw new ContextNotSafeToAssumeError(environment, keys);
+  return keys[0] ?? null;
+}
+var ContextNotSafeToAssumeError = class extends Error {
+  constructor(environment, contexts) {
+    super(
+      `This machine is signed in to ${contexts.length} Topolo contexts in ${environment} (${contexts.join(", ")}), so the context is no longer safe to assume.
+
+State it explicitly:
+  topolo --env ${environment} --context <${contexts.join("|")}> ...
+
+Or set it once for the whole session:
+  export TOPOLO_CONTEXT=<${contexts.join("|")}>`
+    );
+    this.environment = environment;
+    this.contexts = contexts;
+    this.name = "ContextNotSafeToAssumeError";
+  }
+  environment;
+  contexts;
+};
+async function withPinnedContext(options, read = () => readConfig()) {
+  if (options.context?.trim() || options.installationId?.trim()) return options;
+  const environment = normalizeEnvironment(options.environment?.trim() || process.env.TOPOLO_ENV || "production");
+  const keys = signedInContextKeys(await read(), environment);
+  if (keys.length === 1) return { ...options, context: keys[0] };
+  if (!keys.length) {
+    throw new Error(
+      `No Topolo context is signed in for ${environment}, so there is nothing to pin. Run \`topolo --env ${environment} auth login\` first, or pass --context <context>.`
+    );
+  }
+  throw new Error(
+    `${keys.length} Topolo contexts are signed in for ${environment} (${keys.join(", ")}). Pass --context <context> to choose the one this MCP registration pins.`
+  );
+}
+
 // src/commands/auth.ts
 function registerAuthCommands(program2) {
   const auth = program2.command("auth").description("Manage Topolo credentials");
+  registerAuthLockCommand(auth);
   auth.command("login").description("Authenticate with Topolo via OAuth device flow (default) or store an API key").option("--api-key <key>", "Store an API key directly, skipping the OAuth flow").option("--client-id <id>", "OAuth client_id (or set TOPOLO_CLI_CLIENT_ID)").option("--scope <scope>", "Scopes to request (space-separated)").option("--no-browser", "Print the approval URL without opening a browser").option("--use", "Also make the approved context this environment's stored default (as `topolo context use`)").option("--json", "Output JSON").option("--no-json", "Output human-readable text").addHelpText("after", [
     "",
     "The approved sign-in is stored under its own context key (personal or org:<id>).",
@@ -6021,16 +6510,37 @@ Visit ${apiKeyIssuanceUrl(environment)} to mint one, or configure an OAuth clien
       }
     }
   );
-  auth.command("logout").description("Remove stored credentials from this machine").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
+  auth.command("logout").description("Remove every stored sign-in for this environment and revoke it at Topolo").option("--json", "Output JSON").option("--no-json", "Output human-readable text").addHelpText("after", [
+    "",
+    "Removes the stored credential, every personal and organization context and any",
+    "pending re-authorization for the selected environment, then revokes each removed",
+    "OAuth sign-in at Topolo. Stored API keys are only removed from this machine.",
+    "TOPOLO_* credential environment variables are not affected."
+  ].join("\n")).action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     const environment = selectedEnvironment();
     try {
-      const config = await readConfig();
-      await writeConfig(clearProfileCredential(config, environment));
+      const result = await signOut(environment);
+      const source = credentialSourceFromConfig(await readConfig(), environment);
+      const environmentCredential = source.startsWith("env:") ? source.slice(4) : null;
+      if (result.revocationFailed > 0) process.exitCode = 1;
       emit(
-        { ok: true, environment },
+        {
+          ok: result.revocationFailed === 0,
+          removedLocally: true,
+          environment,
+          removed: result.contexts,
+          revoked: result.revoked,
+          revocationFailed: result.revocationFailed,
+          ...environmentCredential ? { environmentCredential } : {}
+        },
         mode,
-        () => `Logged out of Topolo ${environmentLabel(environment)}.`
+        () => [
+          result.contexts.length ? `Logged out of Topolo ${environmentLabel(environment)}: removed ${result.contexts.join(", ")}.` : `No stored sign-in for Topolo ${environmentLabel(environment)}.`,
+          ...result.revoked ? [`Revoked ${result.revoked} sign-in${result.revoked === 1 ? "" : "s"} at Topolo.`] : [],
+          ...result.revocationFailed ? [`Could not confirm revocation of ${result.revocationFailed} sign-in${result.revocationFailed === 1 ? "" : "s"} at Topolo; they are removed from this machine and expire on their own. Revoke them from your Topolo account to end them now.`] : [],
+          ...environmentCredential ? [`${environmentCredential} is still set, so commands keep using it until you unset it.`] : []
+        ].join("\n")
       );
     } catch (err) {
       fail2(err, mode);
@@ -6066,13 +6576,23 @@ Visit ${apiKeyIssuanceUrl(environment)} to mint one, or configure an OAuth clien
 async function storeApiKey(apiKey, environment, mode) {
   if (!apiKey) throw new Error("API key is required");
   const config = await readConfig();
-  await writeConfig(
-    writeProfileConfig(config, environment, {
-      credential: { kind: "api_key", apiKey }
-    })
-  );
+  const next = writeProfileConfig(config, environment, {
+    credential: { kind: "api_key", apiKey }
+  });
+  const profile = next.profiles?.[environment];
+  if (profile) delete profile.activeContext;
+  await writeConfig(next);
+  const overriddenBy = [];
+  const source = credentialSourceFromConfig(next, environment);
+  if (source.startsWith("env:")) overriddenBy.push(source.slice(4));
+  const pinned = process.env.TOPOLO_CONTEXT?.trim();
+  if (pinned) overriddenBy.push(`TOPOLO_CONTEXT=${pinned}`);
+  for (const name of overriddenBy) {
+    process.stderr.write(`Warning: ${name} is set, so commands use it instead of the stored API key until you unset it.
+`);
+  }
   emit(
-    { ok: true, environment, credential: { kind: "api_key" } },
+    { ok: true, environment, credential: { kind: "api_key" }, ...overriddenBy.length ? { overriddenBy } : {} },
     mode,
     () => `Stored API key for Topolo ${environmentLabel(environment)}. Run \`topolo whoami\` to verify.`
   );
@@ -6138,7 +6658,32 @@ async function runDeviceFlow(options) {
     options.environment
   );
   const approvedKey = contextKey(context.contextType, context.organizationId);
+  const approvedUser = identity?.user.id || accessTokenSubject(credential.accessToken);
+  if (approvedUser) context.userId = approvedUser;
   const updated = await readConfig();
+  const storedUser = contextUser(updated, options.environment, approvedKey);
+  if (storedUser && storedUser !== approvedUser) {
+    const who2 = identity ? identity.user.email : "an identity that could not be verified";
+    process.stderr.write(
+      `
+  \u26A0 The browser approved ${who2}, but ${approvedKey} on this machine belongs to a different user.
+    Nothing was stored. Approve as that user, or run \`topolo --env ${options.environment} auth logout\` first to replace it.
+`
+    );
+    process.exitCode = 1;
+    emit(
+      {
+        ok: false,
+        environment: options.environment,
+        error: "user_mismatch",
+        approved: { contextKey: approvedKey, user: identity ? { email: identity.user.email, name: identity.user.name } : null },
+        ...options.requestedContext ? { requestedContext: options.requestedContext, requestedContextRenewed: false } : {}
+      },
+      options.mode,
+      () => `  ${approvedKey} was not changed.`
+    );
+    return;
+  }
   const previousDefault = profileDefault(updated, options.environment);
   const makeDefault = options.makeDefault === true || signedInContextKeys(updated, options.environment).length === 0;
   await writeConfig(writeContextCredential(updated, options.environment, context, makeDefault));
@@ -6186,6 +6731,12 @@ async function runDeviceFlow(options) {
     ].join("\n")
   );
 }
+function contextUser(config, environment, key) {
+  const profile = config.profiles?.[environment];
+  const stored = profile?.contexts?.[key];
+  const credential = stored?.credential;
+  return stored?.userId ?? (credential?.kind === "access_token" ? accessTokenSubject(credential.accessToken) : void 0) ?? profile?.reauthorization?.[key]?.expectedSubject;
+}
 function profileDefault(config, environment) {
   return config.profiles?.[environment]?.activeContext;
 }
@@ -6890,7 +7441,7 @@ function formatActionPlan(plan) {
 }
 
 // src/lib/credential-custody.ts
-import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
+import { createHash as createHash4, 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";
@@ -6966,7 +7517,7 @@ async function writeCredentialCustody(request, deps) {
       environment: deps.environment,
       apiKeyId: key.id,
       expiresAt: key.expiresAt,
-      keyDigest: `sha256:${createHash3("sha256").update(secret, "utf8").digest("hex")}`,
+      keyDigest: `sha256:${createHash4("sha256").update(secret, "utf8").digest("hex")}`,
       createdAt: key.createdAt
     };
     await writeCustodyFiles(directory, [
@@ -7722,7 +8273,7 @@ import { spawnSync as spawnSync5 } from "child_process";
 import { existsSync as existsSync6 } from "fs";
 import { readFile as readFile9, rm as rm3 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { dirname as dirname7, join as join11, resolve as resolve3 } from "path";
+import { dirname as dirname7, join as join11, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { createRequire } from "module";
 
@@ -7737,7 +8288,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 as isAbsolute2, join as join7, resolve as resolve2 } from "path";
+import { isAbsolute as isAbsolute2, join as join7, resolve as resolve3 } from "path";
 var SUPPORTED_AGENT_IDS = [
   "claude",
   "claude-desktop",
@@ -7778,14 +8329,14 @@ var AGENT_NAME_FOR = {
   "amazon-q": "amazon-q"
 };
 function resolveAgentHostTarget(options) {
-  const homeDir = resolve2(options.homeDir ?? homedir4());
+  const homeDir = resolve3(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() || !isAbsolute2(codexHome))) {
     throw new Error("Codex home must be an absolute nonempty directory.");
   }
   return Object.freeze({
     homeDir,
-    ...options.projectDir ? { projectDir: resolve2(options.projectDir) } : {},
+    ...options.projectDir ? { projectDir: resolve3(options.projectDir) } : {},
     codexHome: codexHome ?? join7(homeDir, ".codex")
   });
 }
@@ -7947,7 +8498,7 @@ async function assertClaudeProjectScope(homeDir, projectDir, name) {
     }
     return value;
   };
-  const local = object(object(config.projects)?.[resolve2(projectDir)]);
+  const local = object(object(config.projects)?.[resolve3(projectDir)]);
   if (Object.hasOwn(object(config.mcpServers) ?? {}, name) || Object.hasOwn(object(local?.mcpServers) ?? {}, name)) {
     throw new Error("Claude MCP scope conflict for " + name + ": a user or local definition can override the project registration. Resolve that scope before setup.");
   }
@@ -9040,8 +9591,8 @@ function formatSharedSetup(result) {
 var AGENT_LABELS2 = AGENT_LABELS;
 function skillsSourceDir() {
   const here = dirname7(fileURLToPath3(import.meta.url));
-  const distCandidate = resolve3(here, "../skills");
-  const srcCandidate = resolve3(here, "../../skills");
+  const distCandidate = resolve4(here, "../skills");
+  const srcCandidate = resolve4(here, "../../skills");
   for (const candidate of [distCandidate, srcCandidate]) {
     if (existsSync6(join11(candidate, "topolo", "SKILL.md"))) return candidate;
   }
@@ -9168,7 +9719,7 @@ function registerSkillsCommand(program2) {
     const mode = resolveOutputMode(opts.json);
     try {
       const rows = await agentSurfaceStatus({
-        homeDir: opts.agentHome ? resolve3(opts.agentHome) : void 0,
+        homeDir: opts.agentHome ? resolve4(opts.agentHome) : void 0,
         codexHome: opts.codexHome,
         name: opts.name,
         agent: opts.agent,
@@ -9185,7 +9736,7 @@ function registerSkillsCommand(program2) {
     try {
       const removed = await uninstallAgentSurfaces({
         ...opts,
-        homeDir: opts.agentHome ? resolve3(opts.agentHome) : void 0
+        homeDir: opts.agentHome ? resolve4(opts.agentHome) : void 0
       });
       emit(
         { removed },
@@ -9328,7 +9879,7 @@ function formatStatus(rows) {
 // src/commands/doctor.ts
 import { access as access2 } from "fs/promises";
 import { homedir as homedir6 } from "os";
-import { resolve as resolve4 } from "path";
+import { resolve as resolve5 } from "path";
 import { Client as Client2 } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 
@@ -9504,7 +10055,7 @@ async function verifyMcpProtocol(command, args, env = definedEnvironment(process
 }
 async function resolveInstalledDoctorTarget(options) {
   const name = options.name?.trim() || "topolo";
-  const homeDir = options.agentHome ? resolve4(options.agentHome) : homedir6();
+  const homeDir = options.agentHome ? resolve5(options.agentHome) : homedir6();
   const expected = resolveMcpCommand();
   const requestedAgents = resolveTargets({
     ...options,
@@ -9610,12 +10161,12 @@ function credentialFromTokens(tokens) {
   const accessToken = tokens.accessToken || tokens.access_token;
   const refreshToken = tokens.refreshToken || tokens.refresh_token;
   const expiresIn = tokens.expiresIn || tokens.expires_in;
-  const expiresAtRaw = tokens.expiresAt || tokens.expires_at;
+  const expiresAt = (tokens.expiresAt || tokens.expires_at) ?? (expiresIn ? Math.floor(Date.now() / 1e3) + expiresIn : accessTokenExpiry(accessToken));
   return {
     kind: "access_token",
     accessToken,
     ...refreshToken ? { refreshToken } : {},
-    ...expiresAtRaw ? { expiresAt: expiresAtRaw } : expiresIn ? { expiresAt: Math.floor(Date.now() / 1e3) + expiresIn } : {}
+    ...expiresAt ? { expiresAt } : {}
   };
 }
 async function exchangeForContext(credential, serviceUrls, target) {
@@ -9845,6 +10396,8 @@ function registerContextCommand(program2) {
       }
       resolved.credential = newCredential;
       resolved.oauthClientId = existing?.oauthClientId ?? profile.oauthClientId;
+      const userId = accessTokenSubject(newCredential.accessToken);
+      if (userId) resolved.userId = userId;
       const updated = writeContextCredential(await readConfig(), environment, resolved, true);
       await writeConfig(updated);
       emit(
@@ -10155,7 +10708,7 @@ function registerInstallationsCommand(program2) {
 import { createTopoloMcpLocalHandler } from "@topolo/mcp/local";
 
 // src/lib/mcp-hub-server.ts
-import { createHash as createHash4, timingSafeEqual } from "crypto";
+import { createHash as createHash5, timingSafeEqual } from "crypto";
 import { stat as stat2 } from "fs/promises";
 import { createServer } from "http";
 var MCP_HUB_HOST = "127.0.0.1";
@@ -10170,7 +10723,7 @@ 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();
+  return createHash5("sha256").update(value, "utf8").digest();
 }
 function bearerTokenMatches(header, token) {
   const match = /^Bearer[ \t]+(\S+)[ \t]*$/i.exec(header ?? "");
@@ -10301,11 +10854,11 @@ async function writeWebResponse(response, target) {
 }
 async function startMcpHub(options) {
   const server = createServer();
-  await new Promise((resolve5, reject) => {
+  await new Promise((resolve6, reject) => {
     server.once("error", reject);
     server.listen(options.port, MCP_HUB_HOST, () => {
       server.off("error", reject);
-      resolve5();
+      resolve6();
     });
   });
   const port = server.address().port;
@@ -10336,8 +10889,8 @@ async function startMcpHub(options) {
   return {
     port,
     server,
-    close: () => new Promise((resolve5) => {
-      server.close(() => resolve5());
+    close: () => new Promise((resolve6) => {
+      server.close(() => resolve6());
       server.closeAllConnections();
     })
   };