@topolo/cli 0.8.0 → 0.8.2

package/README.md

@@ -78,6 +78,17 @@ topolo doctor            # verifies auth, handshake, tool discovery, and identit
 ```
 
 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`:
+
+```bash
+topolo setup --name topolo-acme --context org:org_acme --env production
+topolo doctor --context org:org_acme --env production
+```
+
+This creates separately named Claude Code and Codex registrations using the
+same exact nested MCP executable. `topolo-platform` is reserved for the
+restricted operator toolchain.
 
 ## Cross-org isolation
 

package/dist/index.js

@@ -4273,6 +4273,7 @@ import { fileURLToPath as fileURLToPath2 } from "url";
 import { createRequire } from "module";
 var AGENT_LABELS = { claude: "Claude Code", codex: "Codex" };
 var AGENT_NAME_FOR = { claude: "claude-code", codex: "codex" };
+var RESERVED_OPERATOR_REGISTRATION = ["topolo", "platform"].join("-");
 function skillsSourceDir() {
   const here = dirname3(fileURLToPath2(import.meta.url));
   const distCandidate = resolve(here, "../skills");
@@ -4325,7 +4326,7 @@ function withoutMcpServerSections(text, name) {
     return !skipping;
   }).join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
 }
-async function registerClaudeViaConfig(mcp, homeDir) {
+async function registerClaudeViaConfig(mcp, homeDir, registration) {
   const path = join4(homeDir, ".claude.json");
   let config = {};
   if (existsSync2(path)) {
@@ -4336,33 +4337,60 @@ async function registerClaudeViaConfig(mcp, homeDir) {
     }
   }
   const servers = config.mcpServers ?? {};
-  servers.topolo = {
+  servers[registration.name] = {
     type: "stdio",
     command: mcp.command,
     args: mcp.args,
-    env: { TOPOLO_AGENT_NAME: AGENT_NAME_FOR.claude }
+    env: registrationEnvironment(AGENT_NAME_FOR.claude, registration)
   };
   config.mcpServers = servers;
   await atomicWrite(path, `${JSON.stringify(config, null, 2)}
 `);
 }
-async function registerCodexViaConfig(mcp, homeDir) {
+async function registerCodexViaConfig(mcp, homeDir, registration) {
   const path = join4(homeDir, ".codex", "config.toml");
   let text = "";
   if (existsSync2(path)) text = await readFile3(path, "utf8");
-  text = withoutMcpServerSections(text, "topolo");
+  text = withoutMcpServerSections(text, registration.name);
   const argsToml = mcp.args.length ? `
 args = [${mcp.args.map((a) => `"${a}"`).join(", ")}]` : "";
   const block = `
 
-[mcp_servers.topolo]
-command = "${mcp.command}"${argsToml}
+[mcp_servers.${registration.name}]
+command = ${JSON.stringify(mcp.command)}${argsToml}
 
-[mcp_servers.topolo.env]
-TOPOLO_AGENT_NAME = "${AGENT_NAME_FOR.codex}"
-`;
+[mcp_servers.${registration.name}.env]
+` + Object.entries(registrationEnvironment(AGENT_NAME_FOR.codex, registration)).map(([key, value]) => `${key} = ${JSON.stringify(value)}`).join("\n") + "\n";
   await atomicWrite(path, `${text}${block}`);
 }
+function registrationEnvironment(agentName, registration) {
+  return {
+    TOPOLO_AGENT_NAME: agentName,
+    ...registration.context ? { TOPOLO_CONTEXT: registration.context, TOPOLO_ENV: registration.environment } : {}
+  };
+}
+function resolveMcpRegistration(options) {
+  const name = options.name?.trim() || "topolo";
+  const context = options.context?.trim();
+  const environment = options.environment?.trim() || process.env.TOPOLO_ENV || "production";
+  if (name === RESERVED_OPERATOR_REGISTRATION) {
+    throw new Error("That registration name is reserved for restricted operator tooling.");
+  }
+  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 && /[\r\n]/.test(context)) throw new Error("Context must be a single-line identifier.");
+  if (!["production", "staging", "development", "local"].includes(environment)) {
+    throw new Error("Environment must be production, staging, development, or local.");
+  }
+  return { name, ...context ? { context } : {}, environment };
+}
 async function unregisterFromConfig(agent, homeDir) {
   if (agent === "claude") {
     const path2 = join4(homeDir, ".claude.json");
@@ -4388,8 +4416,8 @@ async function installForAgent(agent, sourceDir, mcp, opts) {
     return { agent, skillPath, skillInstalled: true, mcp: "skipped" };
   }
   try {
-    if (agent === "claude") await registerClaudeViaConfig(mcp, opts.homeDir);
-    else await registerCodexViaConfig(mcp, opts.homeDir);
+    if (agent === "claude") await registerClaudeViaConfig(mcp, opts.homeDir, opts.registration);
+    else await registerCodexViaConfig(mcp, opts.homeDir, opts.registration);
     return { agent, skillPath, skillInstalled: true, mcp: "config-file" };
   } catch (err) {
     return {
@@ -4408,7 +4436,7 @@ function resolveTargets(opts) {
 }
 function registerSkillsCommand(program2) {
   const skills = program2.command("skills").description("Install the Topolo agent skill + MCP server into Claude Code / Codex");
-  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("--project <dir>", "Install the Claude skill into <dir>/.claude instead of ~/.claude").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").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(
+  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("--project <dir>", "Install the Claude skill into <dir>/.claude instead of ~/.claude").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("--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) => {
       const mode = resolveOutputMode(opts.json);
       try {
@@ -4465,19 +4493,21 @@ 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 homeDir = opts.homeDir ?? homedir2();
   const results = [];
   for (const agent of resolveTargets(opts)) {
     results.push(await installForAgent(agent, sourceDir, mcp, {
       withMcp: opts.mcp !== false,
       projectDir: opts.project,
-      homeDir
+      homeDir,
+      registration
     }));
   }
   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-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").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-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("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
       const { results, mcp } = await installAgentSurfaces({ ...opts, homeDir: opts.agentHome });
@@ -4568,9 +4598,10 @@ async function verifyMcpProtocol(command, args) {
   }
 }
 function registerDoctorCommand(program2) {
-  program2.command("doctor").description("Verify the CLI credential and bundled MCP server end to end").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
+  program2.command("doctor").description("Verify the CLI credential and bundled MCP server end to end").option("--context <context>", "Verify one exact personal or organization context").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
+      if (opts.context !== void 0) applyDoctorContext(opts.context);
       const result = await runDoctor();
       if (!result.ok) throw new Error(formatDoctor(result));
       emit(result, mode, () => formatDoctor(result));
@@ -4579,6 +4610,16 @@ function registerDoctorCommand(program2) {
     }
   });
 }
+function normalizeDoctorContext(value) {
+  const context = value.trim();
+  if (!context || /[\r\n]/.test(context)) {
+    throw new Error("Context must be a non-empty single-line identifier.");
+  }
+  return context;
+}
+function applyDoctorContext(value, environment = process.env) {
+  environment.TOPOLO_CONTEXT = normalizeDoctorContext(value);
+}
 function formatDoctor(result) {
   return result.checks.map((check) => `${check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`).join("\n");
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@topolo/cli",
-  "version": "0.8.0",
-  "topoloPublishedVersion": "0.8.0",
+  "version": "0.8.2",
+  "topoloPublishedVersion": "0.8.2",
   "description": "Public command-line interface for Topolo customer organizations, developers, and agents.",
   "type": "module",
   "bin": {

package/skills/topolo/SKILL.md

@@ -60,8 +60,15 @@ topolo whoami --json
 ```
 
 For concurrent agents or multiple MCP connections, never coordinate by changing
-one shared active context. Register one named `topolo-mcp` process per context
-with both `TOPOLO_ENV` and `TOPOLO_CONTEXT`. The context selector accepts an
+one shared active context. Register each pinned context through the CLI so it
+uses the exact bundled MCP instead of a global binary:
+
+```bash
+topolo setup --name topolo-acme --context org:org_acme --env production
+topolo doctor --context org:org_acme --env production
+```
+
+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
 reads and refreshes only its pinned credential without changing the CLI or web