@topolo/cli 0.13.15 → 0.13.16

package/README.md

@@ -74,27 +74,50 @@ OAuth errors, and never extends the original device-code expiry.
 ### Contexts
 
 A user can act in their personal space or any organization they belong to. Each
-context has its own credential; the CLI (and the MCP) run in the active one.
+context has its own credential. Name the one to act as with `--context <key>` or
+`TOPOLO_CONTEXT`; without a pin the CLI (and the MCP) use the stored context only
+while it is the only one signed in for the environment.
 These credentials are independent from the shared web preference: switching a
 CLI/MCP context never moves the browser session, and a web switch never changes
 an already-issued CLI/MCP token or its refresh chain.
 
 ```bash
-topolo context ls                          # personal + your orgs, and which is active
-topolo context use <organization|personal> # switch (validated + a fresh token minted server-side)
+topolo context ls                          # personal + your orgs, and which is the stored default
+topolo context use <organization|personal> # set the stored default (validated + a fresh token minted server-side)
+topolo --context org:org_acme whoami       # pin one command to one context
 ```
 
+**No implicit default context.** Once several contexts are signed in for an
+environment, every account command without `--context`/`TOPOLO_CONTEXT` refuses
+with "the context is no longer safe to assume", exactly like the
+multi-environment `--env` guard. `topolo context use` stays available for anyone
+who wants a stored default, but nothing relies on it implicitly.
+
+`topolo auth login` stores the approved sign-in under its own context key and
+never moves the stored default (`--use` opts in; the environment's first sign-in
+becomes the default). It prints which user and organization were approved. To
+re-authorise one context, name it:
+
+```bash
+topolo --env production --context org:org_acme auth login
+```
+
+If the browser approves a different user or organization, the CLI warns that
+`org:org_acme` was not renewed and exits 1.
+
 ### Wire into agent hosts
 
 ```bash
-topolo setup             # detects installed local hosts and registers the exact bundled MCP
+topolo setup             # registers the exact bundled MCP, pinned to the only signed-in context
 topolo setup --all       # configure every supported local host
 topolo doctor            # verifies auth, handshake, tool discovery, and identity
 ```
 
 The MCP reads the same credential `topolo auth login` writes — no API key to paste.
-For concurrent agents pinned to different organizations, use an exact context
-key returned by `topolo context ls --json`:
+Every registration setup writes pins `TOPOLO_ENV` and `TOPOLO_CONTEXT`. Without
+`--context`, setup pins the only signed-in context, and refuses when there are
+none or several. For each additional organization, use an exact context key
+returned by `topolo context ls --json`:
 
 ```bash
 topolo setup --name topolo-acme --context org:org_acme --env production
@@ -133,12 +156,14 @@ topolo mcp serve [--port 7337]         # what the keep-alive unit runs; foregrou
 `setup --shared`:
 
 1. Adds the identity (`{name, env, context}`, exactly what a stdio entry pins
-   with `TOPOLO_ENV` + `TOPOLO_CONTEXT`; omit `--context` only for the default
-   `topolo` identity that follows the active context) to `mcp-hub.json` next to
+   with `TOPOLO_ENV` + `TOPOLO_CONTEXT`; both are always pinned, and without
+   `--context` the only signed-in context is pinned) to `mcp-hub.json` next to
    the credential store (`~/.config/topolo/mcp-hub.json`, or the directory of
    `TOPOLO_CONFIG_PATH`). `--import-stdio` converts existing stdio entries and
-   skips ones the hub cannot serve (private `TOPOLO_CONFIG_PATH` profiles,
-   agent installations, invalid or conflicting definitions).
+   skips ones the hub cannot serve (entries with no `TOPOLO_CONTEXT` pin,
+   private `TOPOLO_CONFIG_PATH` profiles, agent installations, invalid or
+   conflicting definitions). Add a skipped unpinned entry back with
+   `--name <name> --context <context>`.
 2. Creates `mcp-hub.token` (256-bit, mode 0600) once and reuses it.
 3. Registers **every** hub identity with Claude Code and Codex at user scope,
    replacing same-name stdio entries. `--project` is refused so the token can
@@ -199,8 +224,9 @@ Hub behaviour and security:
 ## Cross-org isolation
 
 The CLI **never accepts an `orgId` argument**. Every command is scoped to the
-active context embedded in the credential (personal or a specific org); to act
-in a different organization you switch context with `topolo context use`, which
+context embedded in the credential (personal or a specific org); to act
+in a different organization you pin that context's own stored credential
+(`--context`), or create one with `topolo context use`, which
 mints a new context-scoped credential — you can never target another org by
 passing an id. The context remains bound through refresh rotation and is not
 re-hydrated from the user's current web selection. This is enforced in two places:

package/dist/index.js

@@ -5599,6 +5599,70 @@ function resolveOAuthClientId(config, environment = selectedEnvironment()) {
   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) {
@@ -5705,7 +5769,14 @@ var CLI_VERSION = readCliVersion();
 // src/commands/auth.ts
 function registerAuthCommands(program2) {
   const auth = program2.command("auth").description("Manage Topolo credentials");
-  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("--json", "Output JSON").option("--no-json", "Output human-readable text").action(
+  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>).",
+    "It never changes the stored default context unless you pass --use, or it is the",
+    "first context signed in for the environment. To re-authorise one context, name it:",
+    "  topolo --env <env> --context <context> auth login",
+    "and the CLI warns (and exits 1) if the browser approves a different user or org."
+  ].join("\n")).action(
     async (opts) => {
       const mode = resolveOutputMode(opts.json);
       const environment = selectedEnvironment();
@@ -5739,7 +5810,9 @@ Visit ${apiKeyIssuanceUrl(environment)} to mint one, or configure an OAuth clien
           environment,
           scope: opts.scope,
           mode,
-          openBrowser: opts.browser !== false
+          openBrowser: opts.browser !== false,
+          makeDefault: opts.use === true,
+          requestedContext: process.env.TOPOLO_CONTEXT?.trim() || void 0
         });
       } catch (err) {
         fail2(err, mode);
@@ -5856,18 +5929,44 @@ async function runDeviceFlow(options) {
     ...token.refresh_token ? { refreshToken: token.refresh_token } : {},
     expiresAt: Math.floor(Date.now() / 1e3) + token.expires_in
   };
-  const context = await resolveLoginContext(
+  const { context, identity } = await resolveLoginContext(
     credential,
     resolved.serviceUrls,
     options.clientId,
     options.environment
   );
+  const approvedKey = contextKey(context.contextType, context.organizationId);
   const updated = await readConfig();
-  await writeConfig(writeContextCredential(updated, options.environment, context));
+  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));
+  const defaultChanged = makeDefault && previousDefault !== approvedKey;
+  const requested = options.requestedContext ? requestedContextKey(updated, options.environment, options.requestedContext) : void 0;
+  const requestedRenewed = requested === void 0 || identity !== null && loginMatches(requested, context);
+  const approved = {
+    contextKey: approvedKey,
+    user: identity ? { email: identity.user.email, name: identity.user.name } : null,
+    organization: context.contextType === "organization" ? { id: context.organizationId, slug: context.organizationSlug ?? null, name: context.organizationName ?? null } : null
+  };
+  const who = identity ? identity.user.email : "an identity that could not be verified";
+  const where = context.contextType === "organization" ? `${context.organizationName || context.organizationSlug || context.organizationId} (${approvedKey})` : `personal context (${approvedKey})`;
+  if (!requestedRenewed) {
+    process.stderr.write(
+      `
+  \u26A0 You asked to re-authorise "${options.requestedContext}", but the browser approved ${who} in ${where}.
+    "${options.requestedContext}" was NOT renewed. The approval was stored under ${approvedKey} only.
+    Sign the browser in as the user for "${options.requestedContext}" and run this again.
+`
+    );
+    process.exitCode = 1;
+  }
   emit(
     {
-      ok: true,
+      ok: requestedRenewed,
       environment: options.environment,
+      approved,
+      ...options.requestedContext ? { requestedContext: options.requestedContext, requestedContextRenewed: requestedRenewed } : {},
+      defaultContext: { changed: defaultChanged, key: makeDefault ? approvedKey : previousDefault ?? null },
       credential: {
         kind: "access_token",
         expiresIn: token.expires_in,
@@ -5875,10 +5974,34 @@ async function runDeviceFlow(options) {
       }
     },
     options.mode,
-    () => "\n  \u2713 Signed in. Run `topolo whoami` to see your identity."
+    () => [
+      "",
+      `  \u2713 Signed in to Topolo ${environmentLabel(options.environment)}.`,
+      `    Approved as:  ${who}${identity?.user.name ? ` (${identity.user.name})` : ""}`,
+      `    Context:      ${where}`,
+      defaultChanged ? `    Default:      ${approvedKey} is now this environment's stored default context.` : `    Default:      unchanged${previousDefault ? ` (${previousDefault})` : ""}. Nothing acts as ${approvedKey} unless pinned.`,
+      `    Use it with:  topolo --env ${options.environment} --context ${approvedKey} <command>`
+    ].join("\n")
   );
 }
+function profileDefault(config, environment) {
+  return config.profiles?.[environment]?.activeContext;
+}
+function requestedContextKey(config, environment, selector) {
+  try {
+    return matchContextSelector(config, environment, selector) ?? selector.trim();
+  } catch {
+    return selector.trim();
+  }
+}
+function loginMatches(requested, context) {
+  const wanted = requested.toLowerCase();
+  if (wanted === contextKey(context.contextType, context.organizationId).toLowerCase()) return true;
+  if (context.contextType !== "organization") return false;
+  return [context.organizationId, context.organizationSlug, context.organizationName].some((value) => String(value || "").trim().toLowerCase() === wanted);
+}
 async function resolveLoginContext(credential, serviceUrls, clientId, environment) {
+  let identity = null;
   try {
     const topolo = createTopolo({
       credential,
@@ -5886,21 +6009,24 @@ async function resolveLoginContext(credential, serviceUrls, clientId, environmen
       agent: { clientName: "topolo-cli", clientVersion: CLI_VERSION },
       serviceUrls
     });
-    const me = await topolo.identity.whoami();
-    const org = me.organization;
+    identity = await topolo.identity.whoami();
+    const org = identity.organization;
     if (org?.id) {
       return {
-        contextType: "organization",
-        organizationId: org.id,
-        organizationSlug: org.slug,
-        organizationName: org.name,
-        credential,
-        oauthClientId: clientId
+        identity,
+        context: {
+          contextType: "organization",
+          organizationId: org.id,
+          organizationSlug: org.slug,
+          organizationName: org.name,
+          credential,
+          oauthClientId: clientId
+        }
       };
     }
   } catch {
   }
-  return { contextType: "personal", credential, oauthClientId: clientId };
+  return { identity, context: { contextType: "personal", credential, oauthClientId: clientId } };
 }
 function tryOpenBrowser(url) {
   try {
@@ -5937,10 +6063,10 @@ function startSpinner() {
 // src/client.ts
 async function buildClient(options) {
   const environment = options?.environment ?? selectedEnvironment();
-  const context = options?.context ?? process.env.TOPOLO_CONTEXT?.trim();
+  const config = await readConfig();
+  const context = commandContextKey(config, environment, options?.context?.trim() || process.env.TOPOLO_CONTEXT);
   const credential = context ? await refreshContextCredentialIfNeeded(environment, context) : await refreshCredentialIfNeeded(environment);
   if (!credential) return null;
-  const config = await readConfig();
   const profile = resolvedProfileConfig(config, environment);
   const topolo = createTopolo({
     credential,
@@ -6384,11 +6510,10 @@ function tryOpenApproval(url) {
 async function actionExecutionContext(topolo) {
   const environment = selectedEnvironment();
   const config = await readConfig();
-  const profile = profileForEnvironment(config, environment);
   const source = credentialSourceFromConfig(config, environment);
   return createTopoloAgentExecutionContext({
     environment,
-    contextKey: source.startsWith("env:") ? null : process.env.TOPOLO_CONTEXT?.trim() || profile.activeContext || null,
+    contextKey: source.startsWith("env:") ? null : commandContextKey(config, environment) ?? null,
     identity: await topolo.identity.whoami(),
     serviceUrls: resolvedProfileConfig(config, environment).serviceUrls
   });
@@ -7129,13 +7254,14 @@ function createOAuthClientPayload(options) {
 }
 async function authFetchJson(path, init = {}) {
   const environment = selectedEnvironment();
-  const credential = await refreshCredentialIfNeeded(environment);
+  const config = await readConfig();
+  const context = commandContextKey(config, environment);
+  const credential = context ? await refreshContextCredentialIfNeeded(environment, context) : await refreshCredentialIfNeeded(environment);
   if (!credential) {
     const err = new Error("Topolo credentials are required.");
     err.code = "auth_error";
     throw err;
   }
-  const config = await readConfig();
   const profile = resolvedProfileConfig(config, environment);
   const authBaseUrl = (profile.serviceUrls?.auth ?? "https://auth.topolo.app").replace(/\/+$/, "");
   const headers = new Headers(init.headers);
@@ -7356,6 +7482,12 @@ import { dirname as dirname7, join as join11, resolve as resolve3 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { createRequire } from "module";
 
+// src/lib/command-context.ts
+function withProgramContext(opts, command) {
+  const context = opts.context ?? command.optsWithGlobals().context;
+  return context === void 0 ? opts : { ...opts, context };
+}
+
 // src/commands/agent-host.ts
 import { spawnSync as spawnSync3 } from "child_process";
 import { existsSync as existsSync4 } from "fs";
@@ -7939,7 +8071,10 @@ function registrationEnvironment(agent, registration) {
     TOPOLO_AGENT_NAME: AGENT_NAME_FOR[agent],
     ...registration.configPath ? { TOPOLO_CONFIG_PATH: registration.configPath } : {},
     ...registration.installationId ? { TOPOLO_AGENT_INSTALLATION_ID: registration.installationId } : {},
-    ...registration.context ? { TOPOLO_CONTEXT: registration.context, TOPOLO_ENV: registration.environment } : {},
+    // Every registration pins its environment, and its context unless it is
+    // bound to an installation, so no MCP ever follows a stored default.
+    TOPOLO_ENV: registration.environment,
+    ...registration.context ? { TOPOLO_CONTEXT: registration.context } : {},
     ...privateAliases
   };
 }
@@ -8211,14 +8346,13 @@ function validateMcpHubIdentity(value, where = "identity") {
     throw new Error(`MCP hub identity ${name} env must be one of ${MCP_HUB_ENVIRONMENTS.join(", ")}.`);
   }
   const context = record3.context;
-  if (context !== void 0 && (typeof context !== "string" || !context.trim() || /[\r\n]/.test(context))) {
+  if (context === void 0) {
+    throw new Error(`MCP hub identity ${name} must pin a context (a key from \`topolo context ls\`).`);
+  }
+  if (typeof context !== "string" || !context.trim() || /[\r\n]/.test(context)) {
     throw new Error(`MCP hub identity ${name} context must be a non-empty single-line selector.`);
   }
-  return {
-    name,
-    environment,
-    ...context !== void 0 ? { context: context.trim() } : {}
-  };
+  return { name, environment, context: context.trim() };
 }
 function parseMcpHubConfig(text2, source) {
   let parsed;
@@ -8257,7 +8391,7 @@ function serializeMcpHubConfig(config) {
     identities: config.identities.map((identity) => ({
       name: identity.name,
       env: identity.environment,
-      ...identity.context ? { context: identity.context } : {}
+      context: identity.context
     }))
   }, null, 2) + "\n";
 }
@@ -8500,12 +8634,21 @@ async function importStdioIdentities(agents, homeDir, codexHome) {
         skipped.push({ agent, name: registration.name, reason: "uses a private config path or agent installation; keep it on stdio" });
         continue;
       }
+      if (!registration.env.TOPOLO_CONTEXT) {
+        skipped.push({
+          agent,
+          name: registration.name,
+          reason: "is not pinned to a context; add it with `topolo setup --shared --name <name> --context <context>`"
+        });
+        continue;
+      }
       let identity;
       try {
         identity = validateMcpHubIdentity({
           name: registration.name,
+          // A stdio entry without TOPOLO_ENV has always meant production.
           env: registration.env.TOPOLO_ENV || "production",
-          ...registration.env.TOPOLO_CONTEXT ? { context: registration.env.TOPOLO_CONTEXT } : {}
+          context: registration.env.TOPOLO_CONTEXT
         });
       } catch (error) {
         skipped.push({ agent, name: registration.name, reason: error.message });
@@ -8547,16 +8690,9 @@ async function installSharedAgentSurfaces(options, dependencies) {
   }
   if (!options.importStdio || options.name) {
     const name = options.name?.trim() || "topolo";
-    const context = options.context?.trim();
-    if (name !== "topolo" && !context) throw new Error("Named registrations require --context <context>.");
-    if (name === "topolo" && context) {
-      throw new Error("Pinned contexts require --name topolo-<name> so the active topolo registration remains independent.");
-    }
-    config = upsertMcpHubIdentity(config, validateMcpHubIdentity({
-      name,
-      env: options.environment?.trim() || dependencies.environment.TOPOLO_ENV || "production",
-      ...context ? { context } : {}
-    }));
+    const env = normalizeEnvironment(options.environment?.trim() || dependencies.environment.TOPOLO_ENV || "production");
+    const { context } = await withPinnedContext({ context: options.context, environment: env }, dependencies.readCredentialStore);
+    config = upsertMcpHubIdentity(config, validateMcpHubIdentity({ name, env, context }));
   }
   await writeMcpHubConfig(paths.config, config);
   const { token, created } = await ensureMcpHubToken(paths.token);
@@ -8635,7 +8771,8 @@ function defaultSharedSetupDependencies(skillsDir, realHome) {
     nodeCommand: stableNodeCommand,
     cliEntry: () => resolveCliEntry(),
     environment: process.env,
-    run: runCommand
+    run: runCommand,
+    readCredentialStore: readConfig
   };
 }
 function formatSharedSetup(result) {
@@ -8688,11 +8825,10 @@ function resolveMcpRegistration(options) {
   if (name !== "topolo" && !/^topolo-[a-z0-9][a-z0-9_-]*$/.test(name)) {
     throw new Error("Named registrations must use a topolo-<name> identifier.");
   }
-  if (context && name === "topolo") {
-    throw new Error("Pinned contexts require --name topolo-<name> so the active topolo registration remains independent.");
-  }
-  if (name !== "topolo" && !context) {
-    throw new Error("Named registrations require --context <context>.");
+  if (!context && !options.installationId?.trim()) {
+    throw new Error(
+      "MCP registrations must pin a context: pass --context <context> (see `topolo context ls`), or --installation <id>."
+    );
   }
   if (context && /[\r\n]/.test(context)) throw new Error("Context must be a single-line identifier.");
   if (!["production", "staging", "development", "local"].includes(environment)) {
@@ -8713,24 +8849,25 @@ function resolveMcpRegistration(options) {
 }
 async function installForAgent(agent, sourceDir, mcp, opts) {
   const { homeDir, projectDir, codexHome } = opts.target;
-  if (opts.withMcp && agent === "claude" && projectDir) {
+  const registration = opts.registration;
+  if (registration && agent === "claude" && projectDir) {
     try {
-      await assertClaudeProjectScope(homeDir, projectDir, opts.registration.name);
+      await assertClaudeProjectScope(homeDir, projectDir, registration.name);
     } catch (err) {
       return { agent, skillInstalled: false, mcp: "failed", detail: err instanceof Error ? err.message : String(err) };
     }
   }
   const source = await readFile9(join11(sourceDir, "topolo", "SKILL.md"), "utf8");
   const skill = await installAgentSkill(agent, source, homeDir, projectDir, codexHome);
-  if (!opts.withMcp) {
+  if (!registration) {
     return { agent, skillPath: skill.path, skillInstalled: skill.installed, mcp: "skipped" };
   }
   try {
-    await registerAgentConfig(agent, mcp, homeDir, opts.registration, projectDir, codexHome);
-    const installed = (await readAgentRegistrations(agent, homeDir, projectDir, codexHome)).find((registration) => registration.name === opts.registration.name);
-    const expectedEnvironment = registrationEnvironment(agent, opts.registration);
+    await registerAgentConfig(agent, mcp, homeDir, registration, projectDir, codexHome);
+    const installed = (await readAgentRegistrations(agent, homeDir, projectDir, codexHome)).find((entry) => entry.name === registration.name);
+    const expectedEnvironment = registrationEnvironment(agent, registration);
     if (!installed || installed.command !== mcp.command || JSON.stringify(installed.args) !== JSON.stringify(mcp.args) || Object.entries(expectedEnvironment).some(([key, value]) => installed.env[key] !== value)) {
-      throw new Error(`Host configuration did not retain the ${opts.registration.name} MCP registration.`);
+      throw new Error(`Host configuration did not retain the ${registration.name} MCP registration.`);
     }
     return { agent, skillPath: skill.path, skillInstalled: skill.installed, mcp: "config-file" };
   } catch (err) {
@@ -8767,7 +8904,8 @@ function resolveTargets(opts) {
 function registerSkillsCommand(program2) {
   const skills = program2.command("skills").description("Install the Topolo agent skill + MCP server into supported agent hosts");
   skills.command("install").description("Copy the skill file and register the topolo MCP server (credential-free)").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent <host...>", "Target one or more hosts by id (for example cursor gemini)").option("--all", "Configure every supported local host").option("--project <dir>", "Write project-scoped host files under <dir> where supported").option("--codex-home <dir>", "Use an explicit native Codex home instead of <agent-home>/.codex").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Register a named pinned MCP, such as topolo-acme").option("--context <context>", "Pin the named MCP to an exact context returned by topolo context ls").option("--installation <id>", "Bind the MCP runtime to a registered external-agent installation").option("--no-mcp", "Copy the skill file but do not register the MCP server").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(
-    async (opts) => {
+    async (opts, command) => {
+      opts = withProgramContext(opts, command);
       const mode = resolveOutputMode(opts.json);
       try {
         const { results, mcp } = await installAgentSurfaces({
@@ -8821,13 +8959,13 @@ async function installAgentSurfaces(opts) {
     throw new Error("Bundled skill file not found. Reinstall the CLI: npm install -g @topolo/cli");
   }
   const mcp = resolveMcpCommand();
-  const registration = resolveMcpRegistration(opts);
   const target = resolveAgentHostTarget({ homeDir: opts.homeDir, projectDir: opts.project, codexHome: opts.codexHome });
   const { homeDir, projectDir, codexHome } = target;
+  const agents = resolveTargets({ ...opts, homeDir, project: projectDir, codexHome });
+  const registration = opts.mcp === false ? null : resolveMcpRegistration(await withPinnedContext({ ...opts }, opts.readCredentialStore));
   const results = [];
-  for (const agent of resolveTargets({ ...opts, homeDir, project: projectDir, codexHome })) {
+  for (const agent of agents) {
     results.push(await installForAgent(agent, sourceDir, mcp, {
-      withMcp: opts.mcp !== false,
       target,
       registration
     }));
@@ -8835,7 +8973,8 @@ async function installAgentSurfaces(opts) {
   return { results, mcp };
 }
 function registerSetupCommand(program2) {
-  program2.command("setup").description("Install the Topolo skill and deterministic local MCP server for supported agent hosts").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent <host...>", "Target one or more hosts by id").option("--all", "Configure every supported local host").option("--project <dir>", "Write project-scoped host files under <dir> where supported").option("--codex-home <dir>", "Use an explicit native Codex home instead of <agent-home>/.codex").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Register a named pinned MCP, such as topolo-acme").option("--context <context>", "Pin the named MCP to an exact context returned by topolo context ls").option("--installation <id>", "Bind the MCP runtime to a registered external-agent installation").option("--shared", "Opt in: register Claude Code and Codex against the shared local MCP hub (one process) instead of stdio").option("--port <port>", "With --shared: hub port on 127.0.0.1 (default 7337)").option("--import-stdio", "With --shared: also move every existing stdio topolo/topolo-* registration onto the hub").option("--no-service", "With --shared: do not install the launchd/systemd keep-alive unit").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
+  program2.command("setup").description("Install the Topolo skill and deterministic local MCP server for supported agent hosts").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent <host...>", "Target one or more hosts by id").option("--all", "Configure every supported local host").option("--project <dir>", "Write project-scoped host files under <dir> where supported").option("--codex-home <dir>", "Use an explicit native Codex home instead of <agent-home>/.codex").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Register a named pinned MCP, such as topolo-acme").option("--context <context>", "Pin the named MCP to an exact context returned by topolo context ls").option("--installation <id>", "Bind the MCP runtime to a registered external-agent installation").option("--shared", "Opt in: register Claude Code and Codex against the shared local MCP hub (one process) instead of stdio").option("--port <port>", "With --shared: hub port on 127.0.0.1 (default 7337)").option("--import-stdio", "With --shared: also move every existing stdio topolo/topolo-* registration onto the hub").option("--no-service", "With --shared: do not install the launchd/systemd keep-alive unit").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts, command) => {
+    opts = withProgramContext(opts, command);
     const mode = resolveOutputMode(opts.json);
     try {
       if (opts.shared) {
@@ -8905,7 +9044,7 @@ async function uninstallAgentSurfaces(options) {
   const target = resolveAgentHostTarget({ homeDir: options.homeDir, projectDir: options.project, codexHome: options.codexHome });
   const { homeDir, projectDir, codexHome } = target;
   const name = options.name?.trim() || "topolo";
-  resolveMcpRegistration({ name, ...name === "topolo" ? {} : { context: "uninstall-validation" } });
+  resolveMcpRegistration({ name, context: "uninstall-validation" });
   const removed = [];
   for (const agent of resolveTargets({ ...options, homeDir, project: projectDir, codexHome })) {
     const before = await readAgentRegistrations(agent, homeDir, projectDir, codexHome);
@@ -9162,7 +9301,8 @@ function definedEnvironment(environment) {
   return Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== void 0));
 }
 function registerDoctorCommand(program2) {
-  program2.command("doctor").description("Verify installed agent surfaces, exact credential, and MCP protocol end to end").option("--name <name>", "Verify one installed MCP registration (defaults to topolo)").option("--context <context>", "Verify one exact personal or organization context").option("--environment <env>", "Override the context environment").option("--claude", "Verify Claude Code only").option("--codex", "Verify Codex only").option("--agent <host...>", "Verify one or more hosts by id").option("--all", "Verify every supported local host").option("--project <dir>", "Inspect project-scoped host files under <dir>").option("--agent-home <dir>", "Inspect an alternate agent home").option("--shared", "Verify the shared local MCP hub end to end for every hub identity (or --name)").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
+  program2.command("doctor").description("Verify installed agent surfaces, exact credential, and MCP protocol end to end").option("--name <name>", "Verify one installed MCP registration (defaults to topolo)").option("--context <context>", "Verify one exact personal or organization context").option("--environment <env>", "Override the context environment").option("--claude", "Verify Claude Code only").option("--codex", "Verify Codex only").option("--agent <host...>", "Verify one or more hosts by id").option("--all", "Verify every supported local host").option("--project <dir>", "Inspect project-scoped host files under <dir>").option("--agent-home <dir>", "Inspect an alternate agent home").option("--shared", "Verify the shared local MCP hub end to end for every hub identity (or --name)").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts, command) => {
+    opts = withProgramContext(opts, command);
     const mode = resolveOutputMode(opts.json);
     try {
       if (opts.shared) {
@@ -9810,7 +9950,7 @@ function createMcpHubHandler(options) {
   const log = options.log ?? (() => void 0);
   const handlers = /* @__PURE__ */ new Map();
   function handlerFor(identity, agentName) {
-    const key = JSON.stringify([identity.name, identity.environment, identity.context ?? null, agentName]);
+    const key = JSON.stringify([identity.name, identity.environment, identity.context, agentName]);
     let handler = handlers.get(key);
     if (!handler) {
       handler = options.createIdentityHandler(identity, agentName);
@@ -9961,7 +10101,7 @@ async function startMcpHub(options) {
 
 // src/commands/mcp.ts
 var createLocalIdentityHandler = (identity, agentName) => createTopoloMcpLocalHandler({
-  identity: { environment: identity.environment, context: identity.context ?? null },
+  identity: { environment: identity.environment, context: identity.context },
   agentName
 });
 var defaultServeDependencies = () => ({
@@ -10027,10 +10167,18 @@ try {
 var environmentWasStated = Boolean(inheritedEnvironment) || environmentArgSeen;
 program.name("topolo").description(
   "Use Topolo from your terminal: sign in, find your apps, and run actions.\n\nQuick start (copy a command, then press Enter):\n  topolo auth login       # Sign in with your browser\n  topolo whoami           # See who you are signed in as\n  topolo apps --no-json   # List your apps as a readable table\n  topolo auth --help      # See sign-in commands\n  topolo help apps        # See app commands and options"
-).version(CLI_VERSION).option("--env <environment>", "Topolo environment: production, staging, development, or local").addHelpText("beforeAll", '\nEvery command starts with "topolo". Running "topolo" alone prints help; it does not open an interactive prompt.\n').addHelpText("afterAll", "\nHelp notation: [brackets] mean optional; <angle brackets> mark a value to replace. Do not type the brackets.");
+).version(CLI_VERSION).option("--env <environment>", "Topolo environment: production, staging, development, or local").option("--context <context>", "Topolo context to act as: personal, org:<id>, or a signed-in organization slug or name (or set TOPOLO_CONTEXT)").addHelpText("beforeAll", '\nEvery command starts with "topolo". Running "topolo" alone prints help; it does not open an interactive prompt.\n').addHelpText("afterAll", "\nHelp notation: [brackets] mean optional; <angle brackets> mark a value to replace. Do not type the brackets.");
 program.hook("preAction", async (thisCommand, actionCommand) => {
   const opts = thisCommand.opts();
   if (opts.env) process.env.TOPOLO_ENV = normalizeEnvironment(opts.env);
+  if (opts.context !== void 0) {
+    const context = opts.context.trim();
+    if (!context || /[\r\n]/.test(context)) {
+      process.stderr.write("--context must be a non-empty single-line identifier.\n");
+      process.exit(2);
+    }
+    process.env.TOPOLO_CONTEXT = context;
+  }
   if (opts.env || environmentWasStated) return;
   for (let node = actionCommand; node; node = node.parent) {
     if (node.name() === "agent-packs") return;

package/package.json

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

package/skills/topolo/SKILL.md

@@ -67,8 +67,16 @@ TOPOLO_CONTEXT=org:org_acme topolo --env production whoami --json
 TOPOLO_CONTEXT=org:org_acme topolo --env production actions --service brand --json
 ```
 
-The CLI keeps this pin through credential refresh and never changes the shared
-active context. A missing pinned credential does not select another context.
+`topolo --context <key> <command>` pins one command the same way. The CLI keeps
+this pin through credential refresh and never changes the stored default
+context. A missing pinned credential does not select another context.
+
+There is no implicit default: when several contexts are signed in for an
+environment, any command or MCP without `--context`/`TOPOLO_CONTEXT` refuses
+("the context is no longer safe to assume"). Pin the context; do not run
+`topolo context use` to work around the refusal. `topolo auth login` never moves
+the stored default and prints which user and organization were approved; check
+that line, because the browser may approve a different account than intended.
 
 For concurrent agents or multiple MCP connections, never coordinate by changing
 one shared active context. Register each pinned context through the CLI so it
@@ -79,6 +87,8 @@ topolo setup --name topolo-acme --context org:org_acme --env production
 topolo doctor --name topolo-acme
 ```
 
+Every registration setup writes pins `TOPOLO_ENV` and `TOPOLO_CONTEXT`; without
+`--context` it pins the only signed-in context and refuses when there are several.
 The context selector accepts an
 exact key returned by `topolo context ls --json` (such as `personal` or
 `org:<orgId>`) or a unique stored organization id, slug, or name. Each process