totemlayer 0.1.44 → 0.1.63

package/bin/installation.mjs

@@ -1,3 +1,4 @@
+import { startupDiagnostic } from "./startup-diagnostics.mjs";
 import { parseArgs } from "node:util";
 import { readFile, stat } from "node:fs/promises";
 import { privateRead, privateWrite } from "./runtime-installation.mjs";
@@ -13,72 +14,103 @@ import { setTimeout as sleep } from "node:timers/promises";
 import { detectInstalledProvider, providerArguments } from "./provider-detection.mjs";
 
 export async function activateConnection(profile, env = process.env, options = {}) {
-  const runtime = await (options.ensureRuntime ?? ensureInstalledRuntime)(env);
-  const { automaticEnabled, setAutomaticEnabled } = await import("./automatic-runtime.mjs");
-  const enabled = await automaticEnabled(profile);
-  if (enabled) await setAutomaticEnabled(profile, true);
-  const service = await (options.installService ?? installRuntimeService)(runtime, {
-    ...env,
-    ...(profile.agentTokenEnv ? { TOTEM_AGENT_TOKEN_ENV: profile.agentTokenEnv } : {}),
-  });
-  if (!enabled) return { state: "paused", ...service, entry: runtime.cli };
-  if (profile.interactiveRequired && !service.persistent)
-    return {
-      state: "needs_attention",
-      ready: false,
-      ...service,
-      entry: runtime.cli,
-      code: "HARNESS_SETUP_REQUIRED",
-      message:
-        "Automatic startup is not registered. Incoming work remains queued until host setup succeeds.",
-    };
-  const { verifyExecutorReady } = await import("./executor-readiness.mjs");
+  const health = await privateRead(join(profile.stateDirectory, "automatic-health.json")).catch(
+    (error) => {
+      if (error.code !== "ENOENT") throw error;
+    },
+  );
+  if (health?.retryable === false)
+    return { state: "needs_attention", ready: false, ...startupDiagnostic(health) };
   try {
-    if (profile.codexThreadId) await (options.verifyExecutor ?? verifyExecutorReady)(profile, env);
-  } catch (error) {
+    const runtime = await (options.ensureRuntime ?? ensureInstalledRuntime)(env);
+    const { automaticEnabled } = await import("./automatic-runtime.mjs");
+    const enabled = await automaticEnabled(profile);
+
+    const service = await (options.installService ?? installRuntimeService)(runtime, {
+      ...env,
+      ...(profile.agentTokenEnv ? { TOTEM_AGENT_TOKEN_ENV: profile.agentTokenEnv } : {}),
+    });
+    if (!enabled) return { state: "paused", ...service, entry: runtime.cli };
+    if (profile.interactiveRequired && !service.persistent)
+      return {
+        state: "needs_attention",
+        ready: false,
+        ...service,
+        entry: runtime.cli,
+        code: "HARNESS_SETUP_REQUIRED",
+        message:
+          "Automatic startup is not registered. Incoming work remains queued until host setup succeeds.",
+      };
+    const { verifyExecutorReady } = await import("./executor-readiness.mjs");
+    try {
+      if (profile.codexThreadId)
+        await (options.verifyExecutor ?? verifyExecutorReady)(profile, env);
+    } catch (error) {
+      if (!startupDiagnostic(error).retryable) throw error;
+      return {
+        state: "needs_attention",
+        ...service,
+        entry: runtime.cli,
+        code: error.code ?? "EXECUTOR_NOT_READY",
+        ...startupDiagnostic(error),
+        message:
+          "Your connection is saved, but the selected agent could not complete its startup check. Run totem status to inspect the blocker.",
+      };
+    }
+    if (profile.interactiveRequired) {
+      const { confirmHarnessStartup } = await import("./harness-bootstrap.mjs");
+      await confirmHarnessStartup(profile);
+    }
+    const start =
+      options.start ??
+      (
+        await import(
+          pathToFileURL(
+            join(
+              runtime.root,
+              "runtime-packages",
+              runtime.version,
+              "node_modules",
+              "totemlayer",
+              "bin",
+              "agent-runner.mjs",
+            ),
+          )
+        )
+      ).agentStartMain;
+    const result = await start(["--profile", profile.profileName, "--background", "--json"], {
+      env,
+      automatic: true,
+      stdout: { write() {} },
+    });
+    if (result) {
+      const failure = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+      throw Object.assign(new Error("The listener could not start."), failure);
+    }
+    const status = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
     return {
-      state: "needs_attention",
+      state: status.ready ? "ready" : "needs_attention",
+      ready: Boolean(status.ready),
       ...service,
       entry: runtime.cli,
-      code: error.code ?? "EXECUTOR_NOT_READY",
-      message:
-        "Your connection is saved, but the selected agent could not complete its startup check. Run totem status to inspect the blocker.",
     };
+  } catch (error) {
+    const diagnostic = startupDiagnostic(error);
+    if (!diagnostic.retryable)
+      await privateWrite(join(profile.stateDirectory, "automatic-health.json"), {
+        state: "needs_attention",
+        code: "LISTENER_START_FAILED",
+        ...diagnostic,
+        retryAt: null,
+        updatedAt: new Date().toISOString(),
+      });
+    throw Object.assign(
+      new Error(
+        `The listener could not start. ${diagnostic.cause} Recovery: ${diagnostic.recovery}`,
+      ),
+      { ...diagnostic, cause: error },
+    );
   }
-  if (profile.interactiveRequired) {
-    const { confirmHarnessStartup } = await import("./harness-bootstrap.mjs");
-    await confirmHarnessStartup(profile);
-  }
-  const start =
-    options.start ??
-    (
-      await import(
-        pathToFileURL(
-          join(
-            runtime.root,
-            "runtime-packages",
-            runtime.version,
-            "node_modules",
-            "totemlayer",
-            "bin",
-            "agent-runner.mjs",
-          ),
-        )
-      )
-    ).agentStartMain;
-  const result = await start(["--profile", profile.profileName, "--background", "--json"], {
-    env,
-    automatic: true,
-    stdout: { write() {} },
-  });
-  if (result) throw new Error("The listener could not start. Check totem status for this profile.");
-  const status = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
-  return {
-    state: status.ready ? "ready" : "needs_attention",
-    ready: Boolean(status.ready),
-    ...service,
-    entry: runtime.cli,
-  };
 }
 
 export async function installationMain(args = [], options = {}) {

package/bin/isolated-agent-entry.mjs

@@ -0,0 +1,35 @@
+// Linux's private network namespace can reach only this relay and the parent broker socket.
+import { createServer } from "node:net";
+import { createConnection } from "node:net";
+import { spawn } from "node:child_process";
+
+const config = JSON.parse(process.env.AGENT_SESSION_CONFIG);
+const server = createServer();
+const sockets = new Set();
+server.on("connection", (socket) => {
+  sockets.add(socket);
+  const parent = createConnection(config.socketPath);
+  socket.pipe(parent).pipe(socket);
+  parent.on("error", () => socket.destroy());
+  socket.on("error", () => parent.destroy());
+  socket.on("close", () => {
+    sockets.delete(socket);
+    parent.destroy();
+  });
+});
+await new Promise((resolve) => server.listen(16443, "127.0.0.1", resolve));
+const env = { ...process.env };
+delete env.AGENT_SESSION_CONFIG;
+const child = spawn(config.command, config.args, {
+  env,
+  cwd: config.cwd,
+  stdio: "inherit",
+  shell: false,
+});
+const stop = (code) => {
+  process.exitCode = code ?? 1;
+  for (const socket of sockets) socket.destroy();
+  server.close();
+};
+child.on("error", () => stop(1));
+child.on("exit", stop);

package/bin/local-mcp.mjs

@@ -1,5 +1,8 @@
-import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
+import { Totem } from "./sdk/index.js";
+import { createAutomaticMcpListener } from "./mcp-listener.mjs";
+import { createMcpIdentityGuard } from "./mcp-identity-binding.mjs";
 
 import {
   managedCollaborationStatus,
@@ -76,25 +79,54 @@ export async function mcpMain(environment = process.env) {
   try {
     const config = await loadTotemMcpConfig(environment);
     let listener = { state: "checking", ready: false };
+    const client = new Totem(config);
+    const transport = new StdioServerTransport();
+    const automaticEnabled = async () => {
+      const status = await (
+        await import("./mcp-runtime.mjs")
+      ).ensureMcpListener(config, environment, {
+        keyFile: environment.TOTEM_NETWORK_API_KEY_FILE?.trim(),
+        connectionOnly: true,
+      });
+      return ["setup_required", "managed"].includes(status.state);
+    };
     const registerListener = (server, client, register) => {
       register(
         server,
         "totem_get_listener_status",
         {
-          title: "Check this computer's Totem listener",
+          title: "Check this agent host’s Totem listener",
           description:
             "Show local listener setup, explicit stop, login recovery and readiness. MCP connectivity alone is not receive/wake/reply readiness and grants no work permission.",
           inputSchema: z.object({}).strict(),
           annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
         },
         async () =>
-          (await import("./mcp-runtime.mjs")).readMcpListenerStatus(config, environment, listener),
+          automatic?.status().listenerReady
+            ? automatic.status()
+            : (await import("./mcp-runtime.mjs")).readMcpListenerStatus(
+                config,
+                environment,
+                listener,
+              ),
       );
       registerLocalCollaborationTools(server, client, register, {
         ...config,
         localKeyFile: environment.TOTEM_NETWORK_API_KEY_FILE?.trim(),
       });
     };
+    const automatic = createAutomaticMcpListener({
+      client,
+      authorize: createMcpIdentityGuard({ client, ...config }),
+      enabled: automaticEnabled,
+      hostKind: environment.TOTEM_MCP_HOST_KIND === "hosted" ? "hosted" : "local",
+      notify: (logger, data) =>
+        transport.send({
+          jsonrpc: "2.0",
+          method: "notifications/message",
+          params: { level: "info", logger, data },
+        }),
+    });
     serveStdio(
       () =>
         createTotemMcpServer({
@@ -103,8 +135,15 @@ export async function mcpMain(environment = process.env) {
           localKeyFile: environment.TOTEM_NETWORK_API_KEY_FILE?.trim(),
           registerLocalTools: registerListener,
         }),
-      { onerror: (error) => console.error(`Totem MCP: ${error.message}`) },
+      { transport, onerror: (error) => console.error(`Totem MCP: ${error.message}`) },
     );
+    const closed = transport.onclose;
+    transport.onclose = () => {
+      void automatic.stop();
+      closed?.();
+    };
+    automatic.start();
+    process.stdin.once("end", () => void automatic?.stop());
     console.error("Totem MCP server is ready on stdio.");
     // Do not delay the MCP handshake. Reconnect repairs only an already bound
     // profile; creating a host/executor binding remains part of explicit install.

package/bin/mcp-config.d.mts

@@ -0,0 +1,11 @@
+export function buildMcpConfig(options?: {
+  baseUrl?: string;
+  transport?: string;
+  format?: string;
+  name?: string;
+  keyFile?: string;
+  expectedAgentId?: string;
+  expectedEnvironment?: string;
+  command?: string;
+  args?: string[];
+}): Record<string, Record<string, Record<string, unknown>>>;

package/bin/mcp-config.mjs

@@ -0,0 +1,56 @@
+/** Connection settings only. No model selection, client detection, or runtime installation. */
+export function buildMcpConfig({
+  baseUrl = "https://totemlayer.com",
+  transport = "http",
+  format = "generic",
+  name = "totem",
+  keyFile,
+  expectedAgentId,
+  expectedEnvironment,
+  command = "totem",
+  args = ["mcp"],
+} = {}) {
+  const url = new URL(baseUrl);
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== "/" ||
+    (url.protocol !== "https:" &&
+      !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+  )
+    throw new Error("Use a credential-free HTTPS origin, or HTTP loopback for development.");
+  if (!["http", "stdio"].includes(transport)) throw new Error("Choose --transport http or stdio.");
+  if (!["generic", "muse"].includes(format)) throw new Error("Choose --format generic or muse.");
+  if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name))
+    throw new Error("Choose a valid MCP server name.");
+  if (transport === "stdio" && !keyFile) throw new Error("Pass --key-file for a stdio connection.");
+  if (expectedAgentId && !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(expectedAgentId))
+    throw new Error("Use a valid agent UUID.");
+  if (expectedEnvironment && !["PRODUCTION", "SANDBOX"].includes(expectedEnvironment))
+    throw new Error("Choose PRODUCTION or SANDBOX.");
+  const endpoint = new URL("/mcp", url);
+  if (expectedAgentId) endpoint.searchParams.set("agent", expectedAgentId);
+  if (expectedEnvironment) endpoint.searchParams.set("environment", expectedEnvironment);
+  const server =
+    transport === "http"
+      ? { url: endpoint.toString() }
+      : {
+          command,
+          args,
+          env: {
+            TOTEM_BASE_URL: url.origin,
+            TOTEM_NETWORK_API_KEY_FILE: keyFile,
+            ...(expectedAgentId ? { TOTEM_EXPECTED_AGENT_ID: expectedAgentId } : {}),
+            ...(expectedEnvironment ? { TOTEM_EXPECTED_ENVIRONMENT: expectedEnvironment } : {}),
+          },
+        };
+  return format === "muse"
+    ? {
+        mcp_servers: {
+          [name]: { transport: transport === "http" ? "streamable_http" : "stdio", ...server },
+        },
+      }
+    : { mcpServers: { [name]: { ...(transport === "http" ? { type: "http" } : {}), ...server } } };
+}

package/bin/mcp-install.mjs

@@ -1,3 +1,5 @@
+import { parseArgs } from "node:util";
+import { buildMcpConfig } from "./mcp-config.mjs";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { stat, lstat } from "node:fs/promises";
@@ -15,21 +17,33 @@ const SERVER_ENTRY = fileURLToPath(new URL("./totem.mjs", import.meta.url));
 export const MCP_INSTALL_HELP = `Connect Totem to an AI app
 
 Usage:
+  totem mcp install claude             Add hosted MCP and open one OAuth approval
+  totem mcp install codex              Add hosted MCP and open one OAuth approval
+  totem mcp install generic            HTTP settings for other hosts
+  totem mcp config                     HTTP settings for any MCP client
+  totem mcp config --transport stdio --key-file /absolute/path/to/agent.key
+  totem mcp config --format muse       Muse Code settings
   totem mcp install generic --key-file /absolute/path/to/agent.key
   totem mcp install codex --key-file /absolute/path/to/agent.key
   totem mcp install claude --key-file /absolute/path/to/agent.key
 
 Options:
   --base-url <origin>  Totem origin (default: https://totemlayer.com)
-  --name <name>        MCP server name (default: totem-local)
-  --key-file <path>    Existing private agent key file (required)
+  --name <name>        MCP name (default: totem, or totem-local with --key-file)
+  --key-file <path>    Use an existing private agent key for local stdio instead
   --agent-id <UUID>    Require this credential-derived agent identity
   --environment <env> Require PRODUCTION or SANDBOX
   --codex-thread <ID>   Bind a new Codex listener to this owner-selected chat
   --no-start           Configure tools only; do not start a local listener
   --help               Show this guide
 
-This installs a user-level local stdio MCP connection. It never puts the key
+Without --key-file, this uses the client's native hosted MCP and OAuth support.
+The client saves credentials privately. No Totem website guide, copied key,
+local worker, or model change is required. Existing connections are preserved.
+The host may require reloading tools after adding a server. Call
+totem_get_identity in that host to verify the selected identity and access.
+
+With --key-file, this installs a user-level local stdio MCP connection. It never puts the key
 value in a command, client config, or repository. It will not overwrite an
 existing MCP server. Restart the AI app afterward and ask for totem_get_identity.
 Use --agent-id and --environment to reject an unintended agent or environment.
@@ -82,8 +96,7 @@ function parseInstallArgs(args, environment) {
     values[option] = value;
   }
   const keyFile = values["--key-file"] ?? environment.TOTEM_NETWORK_API_KEY_FILE;
-  if (!keyFile) fail("Pass --key-file with the path to your own Totem agent key file.");
-  const name = values["--name"] ?? DEFAULT_NAME;
+  const name = values["--name"] ?? (keyFile ? DEFAULT_NAME : "totem");
   if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name))
     fail(
       "The MCP name must be 1-64 letters, numbers, hyphens or underscores and start with a letter.",
@@ -118,7 +131,7 @@ function parseInstallArgs(args, environment) {
     codexThreadId: values["--codex-thread"],
     configDirectory: environment.TOTEM_CONFIG_DIR ? runtimeRoot(environment) : undefined,
     noStart: values["--no-start"] === true || environment.TOTEM_AUTO_START === "0",
-    keyFile: resolve(keyFile),
+    keyFile: keyFile ? resolve(keyFile) : undefined,
     name,
     baseUrl: url.origin,
     ...loadMcpIdentityBinding({
@@ -152,16 +165,46 @@ async function validateKeyFile(path, platform) {
     fail("The Totem agent key file must be private (mode 0600). Fix its permissions and retry.");
 }
 
+export async function configureTotemMcp(args, environment = process.env, runtime = {}) {
+  const flags = parseArgs({
+    args,
+    strict: true,
+    options: {
+      transport: { type: "string", default: "http" },
+      format: { type: "string", default: "generic" },
+      name: { type: "string", default: "totem" },
+      "base-url": { type: "string" },
+      "key-file": { type: "string" },
+      "agent-id": { type: "string" },
+      environment: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+  }).values;
+  if (flags.help) return MCP_INSTALL_HELP;
+  const keyFile = flags["key-file"] ?? environment.TOTEM_NETWORK_API_KEY_FILE;
+  const config = buildMcpConfig({
+    baseUrl: flags["base-url"] ?? environment.TOTEM_BASE_URL ?? DEFAULT_ORIGIN,
+    transport: flags.transport,
+    format: flags.format,
+    name: flags.name,
+    keyFile: keyFile ? resolve(keyFile) : undefined,
+    expectedAgentId: flags["agent-id"] ?? environment.TOTEM_EXPECTED_AGENT_ID,
+    expectedEnvironment: flags.environment ?? environment.TOTEM_EXPECTED_ENVIRONMENT,
+    command: process.execPath,
+    args: [runtime.serverEntry ?? SERVER_ENTRY, "mcp"],
+  });
+  if (flags.transport === "stdio")
+    await validateKeyFile(resolve(keyFile), runtime.platform ?? process.platform);
+  return JSON.stringify(config, null, 2) + "\n";
+}
+
 function runClient(command, args, environment, runtime) {
-  const invocation =
-    runtime.platform === "win32"
-      ? installedClientInvocation(command, args, environment)
-      : { command, args };
+  const invocation = installedClientInvocation(command, args, environment, runtime);
   const result = runtime.spawnProcess(invocation.command, invocation.args, {
     encoding: "utf8",
     env: environment,
-    stdio: ["ignore", "pipe", "pipe"],
-    timeout: 20_000,
+    stdio: runtime.stdio ?? ["ignore", "pipe", "pipe"],
+    timeout: runtime.timeoutMs ?? 20_000,
   });
   if (result.error?.code === "ENOENT")
     fail(
@@ -171,10 +214,98 @@ function runClient(command, args, environment, runtime) {
   return result;
 }
 
+function hostedEntryMatches(result, client, endpoint) {
+  if (result.status !== 0) return false;
+  if (client === "codex") {
+    try {
+      const entry = JSON.parse(result.stdout);
+      const transport = entry.transport;
+      return (
+        entry.enabled !== false &&
+        !entry.disabled_reason &&
+        transport?.type === "streamable_http" &&
+        transport.url === endpoint &&
+        !transport.bearer_token_env_var &&
+        Object.keys(transport.http_headers ?? {}).length === 0 &&
+        Object.keys(transport.env_http_headers ?? {}).length === 0
+      );
+    } catch {
+      return false;
+    }
+  }
+  // Claude currently exposes human-readable get output rather than a JSON export.
+  const output = String(result.stdout ?? "").replace(/\u001b\[[0-9;]*m/g, "");
+  const field = (name) => output.match(new RegExp(`^\\s*${name}:\\s*(.*)$`, "mi"))?.[1]?.trim();
+  return (
+    field("Type") === "http" &&
+    field("URL") === endpoint &&
+    !/^.*(?:disabled|rejected|pending approval)/im.test(field("Status") ?? "") &&
+    !/^\s*(?:Headers?|Authorization|Environment|headersHelper):/im.test(output)
+  );
+}
+
+async function installHostedTotemMcp(options, environment, runtime) {
+  const config = buildMcpConfig({
+    baseUrl: options.baseUrl,
+    name: options.name,
+    expectedAgentId: options.expectedAgentId,
+    expectedEnvironment: options.expectedEnvironment,
+  });
+  if (options.client === "generic") return JSON.stringify(config, null, 2) + "\n";
+  if (options.codexThreadId)
+    fail(
+      "--codex-thread requires local stdio setup with --key-file. Hosted MCP does not bind a desktop chat.",
+    );
+  const endpoint = config.mcpServers[options.name].url;
+  const env = localClientEnvironment(environment);
+  const getArgs = ["mcp", "get", options.name, ...(options.client === "codex" ? ["--json"] : [])];
+  const inspect = () => runClient(options.client, getArgs, env, runtime);
+  let entry = inspect();
+  if (entry.status === 0 && !hostedEntryMatches(entry, options.client, endpoint))
+    fail(
+      `${options.name} already exists with different or disabled settings. It was preserved; inspect that exact connection before continuing.`,
+    );
+  if (entry.status !== 0) {
+    if (!/no mcp server|not found|does not exist/i.test(`${entry.stderr}\n${entry.stdout}`))
+      fail("The client could not check its existing MCP settings. No configuration was changed.");
+    const args =
+      options.client === "claude"
+        ? ["mcp", "add", "--transport", "http", "--scope", "user", options.name, endpoint]
+        : ["mcp", "add", options.name, "--url", endpoint];
+    if (runClient(options.client, args, env, runtime).status !== 0)
+      fail(
+        "The host could not save Totem's MCP connection. Check its MCP configuration permissions.",
+      );
+    entry = inspect();
+    if (!hostedEntryMatches(entry, options.client, endpoint))
+      fail(
+        "Totem's saved MCP settings could not be verified. No sign-in was started; inspect the exact entry before retrying.",
+      );
+  }
+  const connected =
+    options.client === "claude" &&
+    /^\s*Status:\s*(?:✔\s*)?Connected\s*$/im.test(
+      String(entry.stdout ?? "").replace(/\u001b\[[0-9;]*m/g, ""),
+    );
+  if (!connected) {
+    const login = runClient(options.client, ["mcp", "login", options.name], env, {
+      ...runtime,
+      timeoutMs: 600_000,
+      stdio: "inherit",
+    });
+    if (login.status !== 0)
+      fail(
+        `Totem's settings are saved, but approval is incomplete. Finish this server's native MCP sign-in in ${options.client}; do not create another connection or switch identities. Older hosts may require their MCP sign-in panel.`,
+      );
+  }
+  return `Totem's hosted MCP settings are saved in ${options.client}. ${connected ? "The existing authenticated connection was reused." : "The client's OAuth approval completed; credentials stay in its private store."} Reload this host's tools if needed, then call totem_get_identity to verify the agent, organization and environment. Check incoming chat delivery separately.\n`;
+}
+
 export async function installTotemMcp(args, environment = process.env, runtime = {}) {
   const options = parseInstallArgs(args, environment);
   if (options.help) return MCP_INSTALL_HELP;
   runtime = { platform: process.platform, spawnProcess: spawnSync, ...runtime };
+  if (!options.keyFile) return installHostedTotemMcp(options, environment, runtime);
   await validateKeyFile(options.keyFile, runtime.platform);
 
   if (options.client === "generic")

package/bin/mcp-listener.d.mts

@@ -0,0 +1,22 @@
+import type { Totem } from "./sdk/index.js";
+export function createAutomaticMcpListener(options: {
+  client: Totem;
+  authorize?: (signal: AbortSignal) => Promise<unknown>;
+  enabled?: () => Promise<boolean>;
+  notify: (logger: string, data: unknown, cursor?: string) => Promise<void>;
+  hostKind?: "local" | "hosted";
+  pollMs?: number;
+  cursors?: { cursor?: string; messageCursor?: string };
+  signal?: AbortSignal;
+}): {
+  start(): void;
+  stop(): Promise<void>;
+  done(): Promise<void>;
+  status(): {
+    state: string;
+    listenerReady: boolean;
+    executionAuthorized: boolean;
+    runId?: string;
+    code?: string;
+  };
+};

package/bin/mcp-listener.mjs

@@ -0,0 +1,4 @@
+export {
+  createAutomaticNetworkListener as createAutomaticMcpListener,
+  readTotemActivity,
+} from "./sdk/listener.js";

package/bin/mcp-runtime.mjs

@@ -17,7 +17,7 @@ function listenerBinding(profile) {
 
 /** Recover only the exact credential-bound profile. MCP transport grants no new host authority. */
 export async function ensureMcpListener(config, environment = process.env, options = {}) {
-  if (environment.TOTEM_AUTO_START === "0" || environment.CI)
+  if (environment.TOTEM_AUTO_START === "0" || (environment.CI && !options.connectionOnly))
     return { state: "disabled_by_request", ready: false, persistent: false };
   if (!options.keyFile)
     return {
@@ -122,6 +122,8 @@ export async function ensureMcpListener(config, environment = process.env, optio
       message:
         "This listener was explicitly stopped. Its opt-out remains in effect; totem start can resume it.",
     };
+  if (options.connectionOnly)
+    return { state: "managed", ready: false, ...listenerBinding(profile) };
   const activate = options.activate ?? (await import("./installation.mjs")).activateConnection;
   if (["codex", "claude"].includes(profile.client ?? profile.provider)) {
     try {