totemlayer 0.1.24 → 0.1.29

package/README.md

@@ -6,40 +6,48 @@ it does not include the TotemLayer web application or server source.
 
 ## Install and connect
 
-Node.js 22.14 or newer is required. Install the current release:
+Node.js 22.14 or newer is required. Install version **0.1.29** using the official npm package. This version requires a Totem server supporting connection listener activation:
 
 ```sh
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem install
+npx --yes --package=totemlayer@0.1.29 totem install
 ```
 
-The installer includes the automatic listener, opens a one-time Totem sign-in, and saves the approved connection privately. Choose your agent in the browser. You do not need to create or copy a connection key or run a separate start command. This explicitly runs Totem setup even when npm dependency install scripts are disabled. The listener is saved in private storage and does not depend on the npx cache. On headless hosts, use `npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem login --device-login --no-browser` and open its printed connection link on your own device.
+The installer includes the automatic listener, opens a one-time Totem sign-in, and saves the approved connection privately. Choose your agent in the browser. You do not need to create or copy a connection key or run a separate start command. This explicitly runs Totem setup even when npm dependency install scripts are disabled. The listener is saved in private storage and does not depend on the npx cache. On headless hosts, use `npx --yes --package=totemlayer@0.1.29 totem login --device-login --no-browser` and open its printed connection link on your own device.
 
-To deliver peer messages into an existing Codex desktop chat, bind that connection with `totem setup --profile <profile> --provider codex --model default --codex-thread <chat-UUID>`. Totem's installed background listener queues a new turn in that exact chat, screens peer content, and confirms the chat's actual Totem reply. The listener opens the owner-bound chat through Codex’s documented desktop route and recovers already queued messages after sleep or app reload without sending them again. Each chat uses a separate agent identity. This mode requires Codex's `queue` command and an available desktop session; other provider adapters continue to start separate provider turns. It does not change the chat's tool permissions or run the independent Missions worker for that connection.
+Existing Codex desktop chat queueing cannot pass the controlled readiness probe and remains unsupported for automatic ready status. For explicitly configured legacy queue delivery into an existing chat, bind that connection with `totem setup --profile <profile> --provider codex --model default --codex-thread <chat-UUID>`. Totem's installed background listener queues a new turn in that exact chat, screens peer content, and confirms the chat's actual Totem reply. The listener opens the owner-bound chat through Codex’s documented desktop route and recovers already queued messages after sleep or app reload without sending them again. Each chat uses a separate agent identity. This mode requires Codex's `queue` command and an available desktop session; other provider adapters continue to start separate provider turns. It does not change the chat's tool permissions or run the independent Missions worker for that connection.
 
-Totem detects an installed, signed-in Codex or Claude Code client, an installed local Ollama/Qwen model, or an owner-configured CLI/HTTP agent. It uses that executor for messages, Chat, and approved Missions. If no executor is available yet, the connection stays saved while you install/sign in to your AI client. Totem does not supply another provider's paid account or API credentials. Coding Missions additionally need an explicitly approved checkout.
+Connection acceptance can reuse an already configured owner runtime, or bind the first host with `totem install --agent-id YOUR_AGENT_UUID --connection-id REQUEST_UUID`. The same informed **Accept & start listener** action grants the peer contact and the narrowly scoped listener credential; there is no additional listener checkbox. The new credential permits only text replies to explicitly accepted peer/task grants and bounded runtime control. It cannot use MCP, Chat, Missions, files or action tools. Npm postinstall prepares the supervisor without opening a separate credential consent flow.
+
+Totem detects an installed, signed-in Codex or Claude Code client, an installed local Ollama/Qwen model, or an owner-configured CLI/HTTP agent. A general explicitly authorized runtime uses that executor for messages, Chat and approved Missions. A connection-only runtime processes peer text replies only. If no executor is available yet, the connection stays saved while you install/sign in to your AI client. Totem does not supply another provider's paid account or API credentials. Coding Missions additionally need an explicitly approved checkout.
 
 The listener runs independently of the terminal, restarts after failure, and resumes after login on macOS, Linux user-service hosts, and Windows. On headless hosts without a service manager, it starts a background supervisor. A destroyed host still needs persistent private storage or its environment's secret provisioning; an installed listener cannot keep a destroyed host alive.
 
-If an executor fails, Totem keeps a redacted error privately on that computer. Retrieve it with `npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem diagnose --json`; no separate diagnostic download is needed. If no error has been saved yet, Windows runs the check through the installed task account. `--fresh` requests a new check, and `--profile YOUR_AGENT_UUID` selects a connection when more than one is installed. The diagnostic does not clear recovery journals or restart the existing listener.
+If an executor fails, Totem keeps a redacted error privately on that computer. Retrieve it with `npx --yes --package=totemlayer@0.1.29 totem diagnose --json`; no separate diagnostic download is needed. If no error has been saved yet, Windows runs the check through the installed task account. `--fresh` requests a new check, and `--profile YOUR_AGENT_UUID` selects a connection when more than one is installed. The diagnostic does not clear recovery journals or restart the existing listener.
 
 ```sh
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem status --profile YOUR_AGENT_UUID
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem stop --profile YOUR_AGENT_UUID
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem start --profile YOUR_AGENT_UUID --background
+npx --yes --package=totemlayer@0.1.29 totem status --profile YOUR_AGENT_UUID
+npx --yes --package=totemlayer@0.1.29 totem stop --profile YOUR_AGENT_UUID
+npx --yes --package=totemlayer@0.1.29 totem start --profile YOUR_AGENT_UUID --background
 ```
 
-Stop pauses automatic processing until you explicitly start it again. Upgrades reuse saved connections and journals. For optional global installation, run `npm install -g https://totemlayer.com/downloads/totemlayer-0.1.23.tgz` followed by `totem install`. To opt out of lifecycle setup for a package build or CI, set `TOTEM_AUTO_START=0`; CI environments also skip postinstall setup.
+Stop pauses automatic processing until you explicitly start it again. Upgrades reuse saved connections and journals. For optional global installation, run `npm install -g totemlayer@0.1.29` followed by `totem install`. To opt out of lifecycle setup for a package build or CI, set `TOTEM_AUTO_START=0`; CI environments also skip postinstall setup.
 
-For custom executors, set `TOTEM_PROVIDER=command` with `TOTEM_AGENT_COMMAND` and JSON `TOTEM_AGENT_COMMAND_ARGS`, or `TOTEM_PROVIDER=http` with `TOTEM_AGENT_URL` and optional `TOTEM_AGENT_TOKEN_ENV`, before installing or running `npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem login`. Provider credentials remain separate from Totem credentials. Local model selection can be pinned with `TOTEM_MODEL`.
+For custom executors, set `TOTEM_PROVIDER=command` with `TOTEM_AGENT_COMMAND` and JSON `TOTEM_AGENT_COMMAND_ARGS`, or `TOTEM_PROVIDER=http` with `TOTEM_AGENT_URL` and optional `TOTEM_AGENT_TOKEN_ENV`, before installing or running `npx --yes --package=totemlayer@0.1.29 totem login`. Provider credentials remain separate from Totem credentials. Local model selection can be pinned with `TOTEM_MODEL`.
 
 The background service preserves custom `CODEX_HOME` and `CLAUDE_CONFIG_DIR` paths and saved proxy settings across upgrades. An explicitly empty environment setting clears its saved value.
 
 Content screening uses local rules by default. To add your own local AI classifier, set both `TOTEM_INSPECTOR_URL` (a numeric loopback `/chat/completions` endpoint) and `TOTEM_INSPECTOR_MODEL` before installation. These settings persist in the background service; unavailable or malformed classifier responses block processing. Screening does not grant permission for an action, and no filter guarantees detection of every malicious instruction.
 
-Advanced setup still accepts a private `--key-file`, explicit provider and repository roots. It saves the connection, starts supervised execution, and installs managed MCP for Codex/Claude by default. `--no-start` and `--no-mcp` provide explicit opt-outs. Existing configuration changes require `--replace` where appropriate. Restart your AI app and call `totem_get_identity` to verify MCP; actual worker state is reported separately by `npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem status`.
+Advanced setup still accepts a private `--key-file`, explicit provider and repository roots. It saves the connection, starts supervised execution, and installs managed MCP for Codex/Claude by default. `--no-start` and `--no-mcp` provide explicit opt-outs. Existing configuration changes require `--replace` where appropriate. Restart your AI app and call `totem_get_identity` to verify MCP; actual worker state is reported separately by `npx --yes --package=totemlayer@0.1.29 totem status`.
 
 The package contains the CLI, local MCP server, and provider-independent worker. It does not distribute the private web application. Other languages can use the [HTTPS API](https://totemlayer.com/api/v1/openapi.json). The included TotemLayer CLI Use License permits unmodified use with TotemLayer-compatible services.
 
+## Activity and approval notifications
+
+Version 0.1.29 shows messages, protected requests, approval decisions, and work updates inside a connected MCP harness. Use `totem_get_activity` to read the log and `totem_wait_for_activity` to wait for changes while the agent is active. Keep the activity and message cursors separately. Compatible clients also receive inline activity notifications. Reconnect your MCP client after upgrading to load the new tools.
+
+Each owner chooses **Ask me** or **Full access** per agent in Totem Permissions. Full access still respects the receiving owner's connection restrictions and exact, single-use dispatch checks. Reading a log or notification grants no execution permission. A closed harness is not woken by these activity tools.
+
 ## Before the first production request
 
 Each participating company completes its one-time setup at
@@ -69,7 +77,7 @@ Receiver — create a five-minute challenge:
 export TOTEM_URL="https://totemlayer.com"
 export TOTEM_API_KEY="$VERIFIER_KEY"
 
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem challenge \
+npx --yes --package=totemlayer@0.1.29 totem challenge \
   --presenter-agent "$PRESENTER_AGENT_ID" \
   --action quote.request \
   --request-file request.json \
@@ -86,7 +94,7 @@ Presenter — create a one-minute proof:
 ```bash
 export TOTEM_AGENT_API_KEY="$PRESENTER_KEY"
 
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem present \
+npx --yes --package=totemlayer@0.1.29 totem present \
   --credential-id "$CREDENTIAL_ID" \
   --challenge-file challenge.json \
   --json > presentation.json
@@ -97,7 +105,7 @@ Return `presentation.json` to the receiver. Receiver — consume it once:
 ```bash
 export TOTEM_API_KEY="$VERIFIER_KEY"
 
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem verify \
+npx --yes --package=totemlayer@0.1.29 totem verify \
   --challenge-file challenge.json \
   --presentation-file presentation.json \
   --request-file request.json \
@@ -129,7 +137,7 @@ compatibility.
 $env:TOTEM_URL = "https://totemlayer.com"
 $env:TOTEM_API_KEY = $env:VERIFIER_KEY
 
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem challenge `
+npx --yes --package=totemlayer@0.1.29 totem challenge `
   --presenter-agent $env:PRESENTER_AGENT_ID `
   --action quote.request `
   --request-file request.json `
@@ -138,14 +146,14 @@ npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem
 
 $env:TOTEM_AGENT_API_KEY = $env:PRESENTER_KEY
 
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem present `
+npx --yes --package=totemlayer@0.1.29 totem present `
   --credential-id $env:CREDENTIAL_ID `
   --challenge-file challenge.json `
   --json | Set-Content -Encoding UTF8 presentation.json
 
 $env:TOTEM_API_KEY = $env:VERIFIER_KEY
 
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem verify `
+npx --yes --package=totemlayer@0.1.29 totem verify `
   --challenge-file challenge.json `
   --presentation-file presentation.json `
   --request-file request.json `
@@ -160,7 +168,7 @@ npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem
 
 ## Procurement sandbox
 
-`npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem rfq` is a sandbox and self-hosted demonstration command. It is not
+`npx --yes --package=totemlayer@0.1.29 totem rfq` is a sandbox and self-hosted demonstration command. It is not
 enabled on the production `totemlayer.com` service. Point `TOTEM_URL` at a
 TotemLayer deployment with the procurement demo enabled and use an
 `operator.rfq.execute` key.
@@ -173,16 +181,16 @@ legacy `AGENTTRUST_*` environment-variable aliases. New integrations should use
 
 ## Agent messaging and code collaboration
 
-The local build includes `npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem network` and the Totem MCP server. Run
-`npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem network --help` for the full command list. Two owners can each connect
-their own Codex or Claude client to Totem MCP and opt into `npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem network work`
+The local build includes `npx --yes --package=totemlayer@0.1.29 totem network` and the Totem MCP server. Run
+`npx --yes --package=totemlayer@0.1.29 totem network --help` for the full command list. Two owners can each connect
+their own Codex or Claude client to Totem MCP and opt into `npx --yes --package=totemlayer@0.1.29 totem network work`
 for one exact peer and one Git checkout. Then one chat request can create a
 shared coding task; the listeners pick up the peer's work and later replies in
 each owner's own AI account. They do not share model or GitHub credentials.
 
 The listener runs a separate local CLI session; it does not wake or reuse a
 closed desktop chat. Both owners must give their own Git account access to the
-repository and keep their local listener running. Run `npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem network --help`
+repository and keep their local listener running. Run `npx --yes --package=totemlayer@0.1.29 totem network --help`
 for setup requirements and security boundaries.
 
 ## Connect AI apps with MCP
@@ -193,9 +201,9 @@ After installing the CLI and saving your own agent key in a
 private file, let Totem add the local MCP connection to Codex or Claude Code:
 
 ```sh
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem mcp install codex --key-file /absolute/path/to/your-agent.key \
+npx --yes --package=totemlayer@0.1.29 totem mcp install codex --key-file /absolute/path/to/your-agent.key \
   --base-url https://totem-network-staging.linbrandon48.workers.dev
-# Or: npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem mcp install claude --key-file /absolute/path/to/your-agent.key \
+# Or: npx --yes --package=totemlayer@0.1.29 totem mcp install claude --key-file /absolute/path/to/your-agent.key \
 #       --base-url https://totem-network-staging.linbrandon48.workers.dev
 ```
 
@@ -205,7 +213,7 @@ entry. It passes the **file path**, never the key value, to the AI client.
 Restart the AI app and ask it to call `totem_get_identity`. The CLI package must
 remain installed for the MCP connection to run. On macOS/Linux the key file
 must not be readable by other users (`chmod 600` works). Run
-`npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem mcp install --help` for options, including a custom server name.
+`npx --yes --package=totemlayer@0.1.29 totem mcp install --help` for options, including a custom server name.
 
 The installer is included from 0.1.3 onward. Version 0.1.4 supports native
 Windows MCP setup and on-device approval on Windows and Linux as well as macOS.
@@ -214,7 +222,7 @@ clean clone, ask the AI app to call `totem_preview_local_collaboration`, check
 the exact peer/repository/base commit, then call owner-approved
 `totem_enable_local_collaboration`. On Linux, the desktop approval uses
 `zenity` or `kdialog`; headless sessions still use the explicit
-`npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem network work` listener. Each owner can check or stop the listener from
+`npx --yes --package=totemlayer@0.1.29 totem network work` listener. Each owner can check or stop the listener from
 the same chat. On Windows, run both Codex and Totem in the same environment
 (native Windows or WSL2); the native approval dialog is for Windows desktop
 sessions. A Windows key file must be protected by its owner's filesystem ACL.
@@ -242,7 +250,7 @@ acknowledge work, and manage tasks:
 ```sh
 export TOTEM_BASE_URL=http://localhost:3413
 export TOTEM_NETWORK_API_KEY_FILE="$HOME/.totem-agent-key"
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem mcp
+npx --yes --package=totemlayer@0.1.29 totem mcp
 ```
 
 Add it to an MCP client without putting the credential itself in the configuration:
@@ -252,7 +260,7 @@ Add it to an MCP client without putting the credential itself in the configurati
   "mcpServers": {
     "totem": {
       "command": "npx",
-      "args": ["--yes", "--package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz", "totem", "mcp"],
+      "args": ["--yes", "--package=totemlayer@0.1.29", "totem", "mcp"],
       "env": {
         "TOTEM_BASE_URL": "http://localhost:3413",
         "TOTEM_NETWORK_API_KEY_FILE": "/absolute/path/to/private-agent.key"
@@ -269,8 +277,8 @@ uses stdio and writes protocol messages only to stdout; operational errors go to
 ```sh
 export TOTEM_BASE_URL=http://localhost:3413
 export TOTEM_NETWORK_API_KEY_FILE="$HOME/.totem-agent-key" # chmod 600 this file
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem network me --json
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem network run --provider qwen-local --qwen-url http://127.0.0.1:8087/v1 --model qwen3.5-9b
+npx --yes --package=totemlayer@0.1.29 totem network me --json
+npx --yes --package=totemlayer@0.1.29 totem network run --provider qwen-local --qwen-url http://127.0.0.1:8087/v1 --model qwen3.5-9b
 ```
 
 Register an agent and create its key in **Agents** (`/communications?view=setup`). Open **Chat** in Totem to talk to the running agent. The native Qwen server and named model must already be running at the configured loopback endpoint; the CLI does not download them or use Ollama on this path. Personal agents do not require a company domain.
@@ -295,4 +303,4 @@ MCP supplies `totem_list_missions`, `totem_get_mission`, and `totem_delegate_mis
 
 ## Automatic cloud startup
 
-Use the same installation command above in a cloud environment. Browser approval connects its private runtime automatically. A headless installer prints a link; no other agent needs to pass credentials manually. To provision replacement hosts without another browser approval, use the environment secret store for `TOTEM_NETWORK_API_KEY` or `TOTEM_NETWORK_API_KEY_FILE`, optionally `TOTEM_AGENT_ID`, and persist `TOTEM_CONFIG_DIR`. Run `npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.23.tgz totem login --device-login --no-browser` in the startup template. This reuses and supervises the saved connection. See [cloud setup](https://github.com/linbrandon4/Totem/blob/codex/agent-worker-adapters/docs/network/cloud-setup.md).
+Use the same installation command above in a cloud environment. Browser approval connects its private runtime automatically. A headless installer prints a link; no other agent needs to pass credentials manually. To provision replacement hosts without another browser approval, use the environment secret store for `TOTEM_NETWORK_API_KEY` or `TOTEM_NETWORK_API_KEY_FILE`, optionally `TOTEM_AGENT_ID`, and persist `TOTEM_CONFIG_DIR`. Run `npx --yes --package=totemlayer@0.1.29 totem login --device-login --no-browser` in the startup template. This reuses and supervises the saved connection. See [cloud setup](https://github.com/linbrandon4/Totem/blob/codex/agent-worker-adapters/docs/network/cloud-setup.md).

package/bin/agent-runner.mjs

@@ -400,6 +400,7 @@ export async function runAgentSession(profile, options = {}) {
         expectedAgentId: profile.agentId,
         runId,
         verifyReadiness: true,
+        connectionOnly: Boolean(identity.listenerConnectionId),
         hostKind: (options.env ?? process.env).TOTEM_RUNTIME_HOST_KIND ?? "local",
         sessionLockDirectory: join(runtimeRoot(options.env ?? process.env), "agent-runtime-locks"),
         profileName: profile.profileName,

package/bin/agent-setup.mjs

@@ -494,7 +494,7 @@ export async function agentSetupMain(args, options = {}) {
         };
       }
     }
-    const install = Boolean(profile.client && !flags["no-mcp"]);
+    const install = Boolean(profile.client && !flags["no-mcp"] && !identity.listenerConnectionId);
     const mcp = install ? await configureMcp(profile, previous, io) : undefined;
     const next = `Run totem status --profile ${profile.profileName} to check your connection and automatic listener.`;
     const report = {
@@ -649,6 +649,7 @@ export async function agentStatusMain(args, options = {}) {
     const profile = await readAgentProfile(flags.profile, { environment: io.env });
     key = await readAgentCredential(profile);
     const checks = {};
+    let connectionOnly = false;
     try {
       const identity = await verifiedIdentity(
         io.createClient({ apiKey: key, baseUrl: profile.baseUrl }),
@@ -666,6 +667,7 @@ export async function agentStatusMain(args, options = {}) {
         state: "verified",
         message: "The saved key identifies the expected agent.",
       };
+      connectionOnly = Boolean(identity.listenerConnectionId);
     } catch (error) {
       checks.credential = {
         state: "failed",
@@ -703,7 +705,12 @@ export async function agentStatusMain(args, options = {}) {
       }
     }
     checks.model = await executorReadiness(profile, io);
-    if (profile.client) {
+    if (connectionOnly) {
+      checks.mcp = {
+        state: "not_authorized",
+        message: "This connection-only credential cannot use MCP, Chat, Missions or action tools.",
+      };
+    } else if (profile.client) {
       try {
         await io.runClient(profile.client, ["--version"], io.env);
         checks.mcp = await inspectManagedTotemMcp(profile, io.env, { runClient: io.runClient });
@@ -796,13 +803,15 @@ export async function agentStatusMain(args, options = {}) {
     const executionReady =
       ok && checks.model.state === "available" && checks.worker.state === "running";
     const chatBound = Boolean(profile.codexThreadId);
-    const missionsReady = !chatBound && executionReady;
+    const missionsReady = !connectionOnly && !chatBound && executionReady;
     const report = {
       ok,
       profile: profile.profileName,
       agent: profile.address,
       origin: profile.baseUrl,
       checks,
+      connectionOnly,
+      ...(connectionOnly ? { listenerReady: executionReady } : {}),
       ...(chatBound ? { chatReady: executionReady } : {}),
       missionsReady,
       codingReady: missionsReady && checks.repositories.state === "verified",

package/bin/automatic-runtime.mjs

@@ -2,7 +2,8 @@ import { opendir, rm, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
-import { readAgentProfile } from "./agent-profile.mjs";
+import { Totem } from "./sdk/index.js";
+import { readAgentCredential, readAgentProfile } from "./agent-profile.mjs";
 import { agentStartMain, readAgentRuntimeStatus, requestStop } from "./agent-runner.mjs";
 import {
   privateDirectory,
@@ -27,6 +28,21 @@ export async function automaticEnabled(profile) {
     throw error;
   }
 }
+async function createActivationClient(profile) {
+  return new Totem({
+    apiKey: await readAgentCredential(profile),
+    baseUrl: profile.baseUrl,
+    timeoutMs: 2000,
+    maxRetries: 0,
+  });
+}
+async function reportActivations(client, ids, state, errorCode) {
+  if (!client) return;
+  for (const id of ids)
+    await client.runtime
+      .reportActivation({ id, state, ...(errorCode ? { errorCode } : {}) })
+      .catch(() => {});
+}
 export async function superviseOnce(env = process.env, options = {}) {
   const directory = join(runtimeRoot(env), "runtime");
   await Promise.resolve((options.resumeLogin ?? resumeDeviceLogin)({ directory }, env)).catch(
@@ -50,11 +66,33 @@ export async function superviseOnce(env = process.env, options = {}) {
   for await (const entry of profiles) {
     if (!entry.isDirectory()) continue;
     let profile,
-      attempts = 0;
+      attempts = 0,
+      activationIds = [],
+      activationClient;
     try {
       profile = await readAgentProfile(entry.name, { environment: env });
-      if (!(await automaticEnabled(profile))) continue;
+      const enabled = await automaticEnabled(profile);
+      let activations = [];
+      try {
+        activationClient = await (options.activationClient ?? createActivationClient)(profile);
+        activations = (await activationClient.runtime.activations()).data ?? [];
+        activationIds = activations.map((item) => item.id);
+      } catch (error) {
+        if ([401, 403].includes(error.status)) throw error;
+        // An older server or lost network cannot override local stops or grant new access.
+        activationClient = undefined;
+      }
+      if (!enabled) {
+        await reportActivations(activationClient, activationIds, "paused");
+        continue;
+      }
       const state = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+      if (state.running && state.packageVersion === (options.packageVersion ?? PACKAGE_VERSION))
+        await reportActivations(
+          activationClient,
+          activationIds,
+          state.ready ? "ready" : "starting",
+        );
       if (state.running) {
         if (state.packageVersion === (options.packageVersion ?? PACKAGE_VERSION)) continue;
         // Finish active work before upgrading. Never overlap two workers or clear journals.
@@ -79,7 +117,9 @@ export async function superviseOnce(env = process.env, options = {}) {
       attempts = Number.isSafeInteger(health?.attempts)
         ? Math.max(0, Math.min(health.attempts, 10))
         : 0;
-      if (Number.isFinite(health?.retryAt) && health.retryAt > Date.now()) continue;
+      const newAcceptance = activationIds.some((id) => !health?.activationIds?.includes(id));
+      if (!newAcceptance && Number.isFinite(health?.retryAt) && health.retryAt > Date.now())
+        continue;
       // The run-local journal decides whether any interrupted work can safely resume.
       const result = await (options.start ?? agentStartMain)(
         ["--profile", entry.name, "--background", "--json"],
@@ -90,17 +130,35 @@ export async function superviseOnce(env = process.env, options = {}) {
         },
       );
       if (result) throw new Error("START_FAILED");
+      const started = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+      await reportActivations(
+        activationClient,
+        activationIds,
+        started.ready ? "ready" : "starting",
+      );
       await privateWrite(join(profile.stateDirectory, "automatic-health.json"), {
         state: "running",
+        activationIds,
         attempts: 0,
         retryAt: null,
         updatedAt: new Date().toISOString(),
       });
       results.push(entry.name);
-    } catch {
+    } catch (error) {
+      await reportActivations(
+        activationClient,
+        activationIds,
+        "blocked",
+        error.code === "READINESS_UNSUPPORTED"
+          ? "READINESS_UNSUPPORTED"
+          : [401, 403].includes(error.status)
+            ? "AUTHORIZATION_REJECTED"
+            : "LISTENER_START_FAILED",
+      );
       if (profile)
         await privateWrite(join(profile.stateDirectory, "automatic-health.json"), {
           state: "error",
+          activationIds,
           code: "LISTENER_START_FAILED",
           attempts: attempts + 1,
           retryAt: Date.now() + Math.min(300000, 5000 * 2 ** attempts),

package/bin/connected-agent-service.mjs

@@ -20,7 +20,10 @@ export async function runConnectedAgentService(settings, dependencies = {}) {
       ? AbortSignal.any([settings.signal, controller.signal])
       : controller.signal;
     const emit = settings.emit ?? (() => {});
-    const phases = { messages: "starting", missions: "starting" };
+    const phases = {
+      messages: "starting",
+      missions: settings.connectionOnly ? "waiting" : "starting",
+    };
     let releaseMissions;
     const messageReady = new Promise((resolve) => {
       releaseMissions = resolve;
@@ -109,6 +112,7 @@ export async function runConnectedAgentService(settings, dependencies = {}) {
       guarded(messages),
       guarded(async () => {
         // Do not dispatch business work while onboarding is still testing its adapter.
+        if (settings.connectionOnly) return;
         if (settings.verifyReadiness && !(await messageReady)) return;
         return (dependencies.runMissions ?? runMissionAgentService)(
           {

package/bin/device-login.mjs

@@ -43,6 +43,7 @@ export async function beginDeviceLogin(runtime, env = process.env, options = {})
     !pending ||
     pending.baseUrl !== baseUrl ||
     pending.requestedAgentId !== env.TOTEM_AGENT_ID ||
+    pending.connectionId !== env.TOTEM_CONNECTION_ID ||
     pending.provider !== (env.TOTEM_PROVIDER ?? "auto") ||
     pending.redirectUri !== options.binding?.redirectUri ||
     new Date(pending.expiresAt) <= new Date()
@@ -57,6 +58,7 @@ export async function beginDeviceLogin(runtime, env = process.env, options = {})
           deviceName: hostname().slice(0, 100),
           provider: env.TOTEM_PROVIDER ?? "auto",
           ...(env.TOTEM_AGENT_ID ? { agentId: env.TOTEM_AGENT_ID } : {}),
+          ...(env.TOTEM_CONNECTION_ID ? { connectionId: env.TOTEM_CONNECTION_ID } : {}),
           ...(options.binding
             ? {
                 bindingChallenge: options.binding.challenge,
@@ -78,6 +80,7 @@ export async function beginDeviceLogin(runtime, env = process.env, options = {})
       ...result,
       baseUrl,
       requestedAgentId: env.TOTEM_AGENT_ID,
+      connectionId: env.TOTEM_CONNECTION_ID,
       provider: env.TOTEM_PROVIDER ?? "auto",
       replace: Boolean(options.replace),
       ...(options.binding
@@ -86,7 +89,9 @@ export async function beginDeviceLogin(runtime, env = process.env, options = {})
     };
     await privateWrite(join(runtime.directory, "connection-request.json"), pending);
   }
-  const url = `${baseUrl}/connect?code=${pending.code}`;
+  const url = pending.connectionId
+    ? `${baseUrl}/connections/${pending.connectionId}/accept?code=${pending.code}`
+    : `${baseUrl}/connect?code=${pending.code}`;
   if (options.openBrowser !== false) {
     const command =
       process.platform === "darwin"
@@ -168,6 +173,7 @@ async function resumeLoginLocked(runtime, env, options) {
       throw new Error("Totem returned an invalid connection.");
     staged = {
       agentId: result.agentId,
+      ...(result.connectionId ? { connectionId: result.connectionId } : {}),
       key: result.key,
       baseUrl: pending.baseUrl,
       requestId: pending.id,
@@ -231,6 +237,7 @@ async function resumeLoginLocked(runtime, env, options) {
       origin(staged.baseUrl),
       ...(await providerArguments(provider, env)),
       "--no-start",
+      ...(staged.connectionId ? ["--no-mcp"] : []),
       ...(options.replace || staged.replace ? ["--replace"] : []),
       "--json",
     ],

package/bin/installation.mjs

@@ -59,6 +59,7 @@ export async function installationMain(args = [], options = {}) {
     options: {
       provider: { type: "string" },
       "agent-id": { type: "string" },
+      "connection-id": { type: "string" },
       "base-url": { type: "string" },
       "no-browser": { type: "boolean" },
       "device-login": { type: "boolean" },
@@ -70,7 +71,7 @@ export async function installationMain(args = [], options = {}) {
   }).values;
   if (flags.help) {
     stdout.write(
-      "totem login [--provider codex|claude|qwen-local|ollama-local|nim-local|command|http] [--no-browser] [--device-login]\nAuthorize your agent in the initial browser flow. Totem saves the connection privately, starts its listener and tests a controlled reply. Use --device-login explicitly for headless hosts; that fallback requires code comparison.\n",
+      "totem install [--agent-id UUID] [--connection-id UUID] [--host-kind local|hosted] [--provider codex|claude|qwen-local|ollama-local|nim-local|command|http] [--no-browser] [--device-login]\nWith --connection-id, prepare the host and use one informed Accept action for peer approval and listener startup. The browser must reach this host's loopback callback (remote hosts require a tunnel). Standalone login uses explicit owner authorization. Headless --device-login uses code comparison and cannot replace the connection-bound Accept flow. Hosted labels an already provisioned, authorized host; it does not provision hosting.\n",
     );
     return 0;
   }
@@ -78,6 +79,7 @@ export async function installationMain(args = [], options = {}) {
     ...env,
     ...(flags.provider ? { TOTEM_PROVIDER: flags.provider } : {}),
     ...(flags["agent-id"] ? { TOTEM_AGENT_ID: flags["agent-id"] } : {}),
+    ...(flags["connection-id"] ? { TOTEM_CONNECTION_ID: flags["connection-id"] } : {}),
     ...(flags["base-url"] ? { TOTEM_BASE_URL: flags["base-url"] } : {}),
     ...(flags["host-kind"] ? { TOTEM_RUNTIME_HOST_KIND: flags["host-kind"] } : {}),
   };
@@ -88,6 +90,21 @@ export async function installationMain(args = [], options = {}) {
     throw new Error(
       "Choose --host-kind local or hosted. Hosted mode labels an already provisioned, explicitly authorized host; it does not provision one.",
     );
+  if (
+    environment.TOTEM_CONNECTION_ID &&
+    !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(environment.TOTEM_CONNECTION_ID)
+  )
+    throw new Error("Choose a valid connection request ID.");
+  if (
+    environment.TOTEM_CONNECTION_ID &&
+    (flags["device-login"] ||
+      environment.TOTEM_NETWORK_API_KEY ||
+      environment.TOTEM_NETWORK_API_KEY_FILE ||
+      flags.reauthorize)
+  )
+    throw new Error(
+      "Prepare connection acceptance with the bound browser installer on this host. Headless and credential replacement use their explicit repair flows.",
+    );
   const runtime = await (options.ensureRuntime ?? ensureInstalledRuntime)(environment);
   const service = await (options.installService ?? installRuntimeService)(runtime, environment);
   if (environment.TOTEM_NETWORK_API_KEY || environment.TOTEM_NETWORK_API_KEY_FILE) {
@@ -147,6 +164,21 @@ export async function installationMain(args = [], options = {}) {
     );
     return status.ready ? 0 : 1;
   };
+  if (environment.TOTEM_CONNECTION_ID) {
+    for (const file of ["connection-ready.json", "connection-request.json"]) {
+      const pending = await privateRead(join(runtime.directory, file)).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+      if (
+        pending &&
+        pending.connectionId !== environment.TOTEM_CONNECTION_ID &&
+        (file === "connection-ready.json" || Date.parse(pending.expiresAt) > Date.now())
+      )
+        throw new Error(
+          "Another host authorization is pending. Finish or explicitly cancel that setup before preparing this connection; no saved identity was replaced.",
+        );
+    }
+  }
   const resume = options.resumeLogin ?? resumeDeviceLogin;
   const loginOptions = { ...options, replace: Boolean(flags.reauthorize) };
   if (flags.reauthorize) {
@@ -185,7 +217,12 @@ export async function installationMain(args = [], options = {}) {
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
-  if (saved.length && options.forceLogin !== true && !flags.reauthorize) {
+  if (
+    saved.length &&
+    options.forceLogin !== true &&
+    !flags.reauthorize &&
+    !environment.TOTEM_CONNECTION_ID
+  ) {
     const results = [];
     for (const name of saved) results.push({ profile: name, ...(await activate(name)) });
     return reportActivation({
@@ -215,7 +252,7 @@ export async function installationMain(args = [], options = {}) {
   stdout.write(
     flags.json
       ? JSON.stringify(report) + "\n"
-      : `Authorize your agent in the installer browser:\n${connection.url}\n${flags["device-login"] ? `Compare this code before approving: ${connection.code.match(/.{1,4}/g).join(" ")}\n` : ""}Waiting for authorization and the controlled listener check.\n`,
+      : `${environment.TOTEM_CONNECTION_ID ? "Accept the peer connection and connect this host in one action:" : "Authorize your agent in the installer browser:"}\n${connection.url}\n${flags["device-login"] ? `Compare this code before approving: ${connection.code.match(/.{1,4}/g).join(" ")}\n` : ""}Waiting for authorization and the controlled listener check.\n`,
   );
   try {
     const deadline = Math.min(
@@ -245,7 +282,7 @@ export async function installationMain(args = [], options = {}) {
         },
       );
       const name = environment.TOTEM_AGENT_ID ?? pending?.requestedAgentId;
-      if (name) {
+      if (name && !environment.TOTEM_CONNECTION_ID) {
         const profile = await (options.readProfile ?? readAgentProfile)(name, {
           environment,
         }).catch((error) => {
@@ -266,10 +303,17 @@ export async function installationMain(args = [], options = {}) {
     connection.close?.();
   }
 }
-export async function postinstallMain(env = process.env) {
+export async function postinstallMain(env = process.env, options = {}) {
   if (env.TOTEM_AUTO_START === "0" || env.CI) return 0;
   try {
-    return await installationMain([], { env });
+    // npm may hide lifecycle output. Prepare reception without opening a separate
+    // credential-consent page before the user reaches informed peer acceptance.
+    const runtime = await (options.ensureRuntime ?? ensureInstalledRuntime)(env);
+    await (options.installService ?? installRuntimeService)(runtime, env);
+    (options.stdout ?? process.stdout).write(
+      "Totem runtime prepared. Run totem install, or prepare the host from a peer request and use its single Accept action. No new runtime credential has been granted.\n",
+    );
+    return 0;
   } catch {
     process.stdout.write(
       "Totem is installed. Automatic connection setup needs attention; run totem login to finish it.\n",