@topolo/cli 0.13.22 → 0.13.23

package/README.md

@@ -58,8 +58,16 @@ topolo auth login             # OAuth device flow — no client id needed; appro
 topolo auth login --api-key topo_live_...  # or store an API key directly (headless/service)
 topolo auth status            # shows which source is active
 topolo auth logout            # clears the stored credential
+topolo auth lock              # shows who holds the sign-in renewal lock and how to recover
 ```
 
+If every command fails with `state_conflict` after about 15 seconds, the lock
+that serializes sign-in renewal is held or was left behind. `topolo auth lock`
+shows its state and the next step; an empty lock left by an interrupted writer
+is recovered with `topolo auth lock --reconcile <generation>`, which keeps the
+old lock in a private quarantine as evidence. Credentials are not read or
+changed.
+
 `topolo auth login` uses a **built-in first-party OAuth client per environment**,
 so any Topolo user can sign in without registering a client — what they can do
 is decided by their permissions. `--client-id doac_...` (or

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.25/node_modules/@topolo/sdk/dist/index.js
 function record(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -1968,7 +1968,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 +1991,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) {
@@ -3989,7 +3989,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 +4017,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.25/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";
@@ -4810,7 +4794,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() {
@@ -4829,7 +4813,7 @@ async function writeConfig(config) {
   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 {
@@ -5126,6 +5110,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 +5174,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;
@@ -5732,110 +5872,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 +5931,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 +5944,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 +6005,213 @@ 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;
+  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>).",
@@ -6890,7 +7131,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 +7207,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 +7963,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 +7978,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 +8019,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 +8188,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 +9281,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 +9409,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 +9426,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 +9569,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 +9745,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,
@@ -10155,7 +10396,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 +10411,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 +10542,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 +10577,8 @@ async function startMcpHub(options) {
   return {
     port,
     server,
-    close: () => new Promise((resolve5) => {
-      server.close(() => resolve5());
+    close: () => new Promise((resolve6) => {
+      server.close(() => resolve6());
       server.closeAllConnections();
     })
   };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@topolo/cli",
   "packageManager": "pnpm@10.17.1",
-  "version": "0.13.22",
-  "topoloPublishedVersion": "0.13.22",
+  "version": "0.13.23",
+  "topoloPublishedVersion": "0.13.23",
   "description": "Public command-line interface for Topolo customer organizations, developers, and agents.",
   "license": "UNLICENSED",
   "author": "Topolo",

package/postinstall.mjs

@@ -1,16 +1,16 @@
+// Plain guidance for the person installing. Install output must never tell an
+// AI assistant to act on its own: `topolo setup` edits other tools' config files.
 const message = [
   'Topolo CLI installed successfully.',
   '',
-  'AI assistant: continue this onboarding automatically:',
-  '  1. Run: topolo setup',
+  'Next steps, when you choose to run them:',
+  '  1. topolo setup        connects your local AI tools to Topolo (edits their config files)',
   '     (Use --all only when every supported local host should be configured.)',
-  '  2. Authenticate: topolo auth login',
-  '  3. Verify: topolo doctor',
+  '  2. topolo auth login   signs in through your browser',
+  '  3. topolo doctor       checks the result',
   '',
   'The setup command detects native config files for Claude Code/Desktop, Codex, Cursor, Grok Build, Gemini CLI, GitHub Copilot/VS Code, Windsurf, Cline, Goose, and Amazon Q Developer.',
-  'If multiple contexts are listed, use the exact intended context returned by the CLI; do not guess organization IDs.',
   'JetBrains AI Assistant and web-only connectors use their own UI or remote connector setup and are not edited by this local installer.',
-  'Only pause for the browser sign-in or an operating-system permission prompt.',
 ].join('\n');
 
 process.stdout.write(`${message}\n`);