totemlayer 0.1.15 → 0.1.17

package/README.md

@@ -9,26 +9,26 @@ it does not include the TotemLayer web application or server source.
 Node.js 22.14 or newer is required. Install the current release:
 
 ```sh
-npm install --global --foreground-scripts https://totemlayer.com/downloads/totemlayer-0.1.12.tgz
+npx totemlayer@latest 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. If installation scripts were disabled, run `totem login` once. On headless hosts, use `totem 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 totemlayer@latest login --no-browser` and open its printed connection link on your own device.
 
 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.
 
 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.
 
 ```sh
-totem status --profile YOUR_AGENT_UUID
-totem stop --profile YOUR_AGENT_UUID
-totem start --profile YOUR_AGENT_UUID --background
+npx totemlayer@latest status --profile YOUR_AGENT_UUID
+npx totemlayer@latest stop --profile YOUR_AGENT_UUID
+npx totemlayer@latest start --profile YOUR_AGENT_UUID --background
 ```
 
-Stop pauses automatic processing until you explicitly start it again. Upgrades reuse saved connections and journals. To opt out of automatic 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` 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 `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 totemlayer@latest login`. Provider credentials remain separate from Totem credentials. Local model selection can be pinned with `TOTEM_MODEL`.
 
-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 `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 totemlayer@latest 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.
 
@@ -61,7 +61,7 @@ Receiver — create a five-minute challenge:
 export TOTEM_URL="https://totemlayer.com"
 export TOTEM_API_KEY="$VERIFIER_KEY"
 
-totem challenge \
+npx totemlayer@latest challenge \
   --presenter-agent "$PRESENTER_AGENT_ID" \
   --action quote.request \
   --request-file request.json \
@@ -78,7 +78,7 @@ Presenter — create a one-minute proof:
 ```bash
 export TOTEM_AGENT_API_KEY="$PRESENTER_KEY"
 
-totem present \
+npx totemlayer@latest present \
   --credential-id "$CREDENTIAL_ID" \
   --challenge-file challenge.json \
   --json > presentation.json
@@ -89,7 +89,7 @@ Return `presentation.json` to the receiver. Receiver — consume it once:
 ```bash
 export TOTEM_API_KEY="$VERIFIER_KEY"
 
-totem verify \
+npx totemlayer@latest verify \
   --challenge-file challenge.json \
   --presentation-file presentation.json \
   --request-file request.json \
@@ -121,7 +121,7 @@ compatibility.
 $env:TOTEM_URL = "https://totemlayer.com"
 $env:TOTEM_API_KEY = $env:VERIFIER_KEY
 
-totem challenge `
+npx totemlayer@latest challenge `
   --presenter-agent $env:PRESENTER_AGENT_ID `
   --action quote.request `
   --request-file request.json `
@@ -130,14 +130,14 @@ totem challenge `
 
 $env:TOTEM_AGENT_API_KEY = $env:PRESENTER_KEY
 
-totem present `
+npx totemlayer@latest present `
   --credential-id $env:CREDENTIAL_ID `
   --challenge-file challenge.json `
   --json | Set-Content -Encoding UTF8 presentation.json
 
 $env:TOTEM_API_KEY = $env:VERIFIER_KEY
 
-totem verify `
+npx totemlayer@latest verify `
   --challenge-file challenge.json `
   --presentation-file presentation.json `
   --request-file request.json `
@@ -152,7 +152,7 @@ totem verify `
 
 ## Procurement sandbox
 
-`totem rfq` is a sandbox and self-hosted demonstration command. It is not
+`npx totemlayer@latest 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.
@@ -165,16 +165,16 @@ legacy `AGENTTRUST_*` environment-variable aliases. New integrations should use
 
 ## Agent messaging and code collaboration
 
-The local build includes `totem network` and the Totem MCP server. Run
-`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 `totem network work`
+The local build includes `npx totemlayer@latest network` and the Totem MCP server. Run
+`npx totemlayer@latest 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 totemlayer@latest 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 `totem network --help`
+repository and keep their local listener running. Run `npx totemlayer@latest network --help`
 for setup requirements and security boundaries.
 
 ## Connect AI apps with MCP
@@ -185,9 +185,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
-totem mcp install codex --key-file /absolute/path/to/your-agent.key \
+npx totemlayer@latest mcp install codex --key-file /absolute/path/to/your-agent.key \
   --base-url https://totem-network-staging.linbrandon48.workers.dev
-# Or: totem mcp install claude --key-file /absolute/path/to/your-agent.key \
+# Or: npx totemlayer@latest mcp install claude --key-file /absolute/path/to/your-agent.key \
 #       --base-url https://totem-network-staging.linbrandon48.workers.dev
 ```
 
@@ -197,7 +197,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
-`totem mcp install --help` for options, including a custom server name.
+`npx totemlayer@latest 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.
@@ -206,7 +206,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
-`totem network work` listener. Each owner can check or stop the listener from
+`npx totemlayer@latest 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.
@@ -234,7 +234,7 @@ acknowledge work, and manage tasks:
 ```sh
 export TOTEM_BASE_URL=http://localhost:3413
 export TOTEM_NETWORK_API_KEY_FILE="$HOME/.totem-agent-key"
-totem mcp
+npx totemlayer@latest mcp
 ```
 
 Add it to an MCP client without putting the credential itself in the configuration:
@@ -243,8 +243,8 @@ Add it to an MCP client without putting the credential itself in the configurati
 {
   "mcpServers": {
     "totem": {
-      "command": "totem",
-      "args": ["mcp"],
+      "command": "npx",
+      "args": ["--yes", "totemlayer@latest", "mcp"],
       "env": {
         "TOTEM_BASE_URL": "http://localhost:3413",
         "TOTEM_NETWORK_API_KEY_FILE": "/absolute/path/to/private-agent.key"
@@ -261,24 +261,14 @@ 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
-totem network me --json
-totem network run --provider qwen-local --qwen-url http://127.0.0.1:8087/v1 --model qwen3.5-9b
+npx totemlayer@latest network me --json
+npx totemlayer@latest 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.
 
 Commands include `me`, `send`, `inbox`, `reply`, `ack`, `listen`, `chat list`, `chat show`, and `chat updates`. Output is JSON; `--json` also emits errors as JSON on stdout. `listen` is an at-least-once unread stream with explicit acknowledgment. `run` calls a real loopback model, maintains heartbeat and leases, and keeps a private replay journal. Use `--allow-agent <exact-address>` to allow its bounded `ask_agent` tool. No arbitrary shell or external action tools are installed.
 
-`run` and local Mission workers include a customer-side inspector before model input
-and Totem-controlled actions. Built-in rules are a baseline; set both
-`TOTEM_INSPECTOR_URL=http://127.0.0.1:9000/v1/chat/completions` and
-`TOTEM_INSPECTOR_MODEL=<installed-security-classifier>` for additional local
-classification. Configured classifier failures block processing. The classifier must
-return JSON `{"decision":"allow"}` or `{"decision":"block"}` as assistant content.
-Unsupported binary message files are blocked. See `docs/network/customer-inspector.md`
-in the source repository for coverage and limits. This does not encrypt ordinary CLI
-messages or intercept tools inside independent external agent processes.
-
 Packing this package inside the source repository builds and embeds the current Totem SDK through
 `prepack`. The MCP server uses the declared Model Context Protocol and Zod runtime dependencies;
 installation automatically configures the listener; use `TOTEM_AUTO_START=0` for CI. See
@@ -297,4 +287,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 `totem 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 totemlayer@latest 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

@@ -9,6 +9,7 @@ import { parseArgs } from "node:util";
 import { readAgentCredential, readAgentProfile, withAgentProfileLock } from "./agent-profile.mjs";
 import { localClientEnvironment } from "./platform-client.mjs";
 import { Totem } from "./sdk/index.js";
+import { RUNTIME_ERROR_CODES, runtimeErrorCode } from "./runtime-diagnostics.mjs";
 
 const CLI_PATH = fileURLToPath(new URL("./totem.mjs", import.meta.url));
 const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
@@ -29,7 +30,7 @@ const LABELS = {
   reconnecting: "Connection interrupted. Waiting to reconnect from saved progress.",
   working: "Working on an assigned Mission task.",
   waiting: "Connected and waiting for approved work.",
-  blocked: "A Mission needs attention. Open Missions to review the blocker.",
+  blocked: "Agent execution needs attention. Check status for the blocker.",
   stopping: "Stopping the agent and saving its progress…",
   stopped: "Agent stopped. Saved progress will be checked when it starts again.",
   failed:
@@ -230,6 +231,7 @@ export async function readAgentRuntimeStatus(profile, { isAlive = alive, now = D
         : "interrupted",
     runId: record.runId,
     updatedAt: record.updatedAt,
+    ...(RUNTIME_ERROR_CODES.has(record.blockerCode) ? { blockerCode: record.blockerCode } : {}),
     ...(UUID.test(record.missionId ?? "") ? { missionId: record.missionId } : {}),
     ...(UUID.test(record.workItemId ?? "") ? { workItemId: record.workItemId } : {}),
   };
@@ -254,6 +256,7 @@ function eventState(event) {
   if (!["connected", "working", "waiting", "blocked"].includes(phase)) return null;
   return {
     phase,
+    blockerCode: phase === "blocked" ? runtimeErrorCode({ code: event.code }) : undefined,
     ...(UUID.test(event.missionId ?? "") ? { missionId: event.missionId } : {}),
     ...(UUID.test(event.workItemId ?? "") ? { workItemId: event.workItemId } : {}),
   };
@@ -311,6 +314,7 @@ export async function runAgentSession(profile, options = {}) {
         phase: status.phase,
         message: LABELS[status.phase],
         ...(status.missionId ? { missionId: status.missionId } : {}),
+        ...(status.blockerCode ? { blockerCode: status.blockerCode } : {}),
       });
     } catch {
       persistenceFailed = true;

package/bin/agent-setup.mjs

@@ -12,10 +12,12 @@ import { installedClientInvocation, localClientEnvironment } from "./platform-cl
 import { inspectLocalRepository } from "./repository.mjs";
 import { Totem } from "./sdk/index.js";
 import { detectInstalledProvider } from "./provider-detection.mjs";
+import { RUNTIME_ERROR_CODES } from "./runtime-diagnostics.mjs";
 
 const execute = promisify(execFile);
 const ORIGIN = "https://totemlayer.com";
 const KEY_LIMIT = 8192;
+const IDENTITY_TIMEOUT_MS = 15000;
 
 export const AGENT_SETUP_HELP = `Connect your agent once
 
@@ -195,7 +197,8 @@ function dependencies(options) {
     stdin: process.stdin,
     stdout: process.stdout,
     stderr: process.stderr,
-    createClient: (config) => new Totem({ ...config, timeoutMs: 5000, maxRetries: 0 }),
+    createClient: (config) =>
+      new Totem({ ...config, timeoutMs: IDENTITY_TIMEOUT_MS, maxRetries: 0 }),
     fetch: globalThis.fetch,
     inspectRepository: inspectLocalRepository,
     installMcp: installTotemMcp,
@@ -224,20 +227,43 @@ function safeOutput(value, secret) {
 }
 
 function identityError(error) {
-  return error?.status === 401 || error?.status === 403
-    ? "The connection key was rejected. For a saved profile, rerun setup with --replace to enter a new key, or use --replace --key-file with the replacement key."
-    : "Totem identity could not be verified. Check the origin, connection key, and server availability.";
+  if (error?.status === 401 || error?.status === 403)
+    return [
+      "The connection key was rejected. For a saved profile, rerun setup with --replace to enter a new key, or use --replace --key-file with the replacement key.",
+      "CONNECTION_KEY_REJECTED",
+    ];
+  if (["TIMEOUT", "CANCELED"].includes(error?.code))
+    return [
+      "Totem identity verification timed out. Check connectivity and retry status; this does not mean the key was rejected.",
+      "IDENTITY_TIMEOUT",
+    ];
+  if (error?.code === "NETWORK_ERROR")
+    return [
+      "Totem identity verification could not reach the saved origin. Check connectivity, proxy and TLS settings.",
+      "IDENTITY_NETWORK_ERROR",
+    ];
+  if (error?.status >= 500)
+    return [
+      "Totem identity verification encountered a server error. Retry status; this does not mean the key was rejected.",
+      "IDENTITY_SERVER_ERROR",
+    ];
+  if (error?.code === "INVALID_RESPONSE")
+    return [
+      "The saved origin returned an invalid identity response. Check the origin and server availability.",
+      "IDENTITY_INVALID_RESPONSE",
+    ];
+  return [
+    "Totem identity could not be verified. Check the saved origin and server availability.",
+    "IDENTITY_VERIFICATION_FAILED",
+  ];
 }
 
 async function verifiedIdentity(client) {
   let identity;
   try {
-    identity = await client.agent({ signal: AbortSignal.timeout(5000) });
+    identity = await client.agent({ signal: AbortSignal.timeout(IDENTITY_TIMEOUT_MS) });
   } catch (error) {
-    fail(
-      identityError(error),
-      error?.status === 401 || error?.status === 403 ? "CONNECTION_KEY_REJECTED" : undefined,
-    );
+    fail(...identityError(error));
   }
   if (
     !identity ||
@@ -248,7 +274,10 @@ async function verifiedIdentity(client) {
     !["SANDBOX", "PRODUCTION"].includes(identity.environment) ||
     (identity.status && !["ACTIVE", "OFFLINE"].includes(identity.status))
   )
-    fail("Totem did not return an active agent identity. Check this agent in Totem.");
+    fail(
+      "Totem did not return an active agent identity. Check this agent in Totem.",
+      "IDENTITY_INVALID_RESPONSE",
+    );
   return identity;
 }
 
@@ -600,6 +629,7 @@ export async function agentStatusMain(args, options = {}) {
       )
         fail(
           "The saved key no longer matches this profile's agent. Run setup with a separate profile or explicitly replace it.",
+          "AGENT_IDENTITY_MISMATCH",
         );
       checks.credential = {
         state: "verified",
@@ -608,6 +638,9 @@ export async function agentStatusMain(args, options = {}) {
     } catch (error) {
       checks.credential = {
         state: "failed",
+        code: error?.setupSafe
+          ? (error.code ?? "IDENTITY_VERIFICATION_FAILED")
+          : "IDENTITY_VERIFICATION_FAILED",
         message: error?.setupSafe
           ? error.message
           : "The saved agent identity could not be verified.",
@@ -688,6 +721,7 @@ export async function agentStatusMain(args, options = {}) {
             : "needs_attention";
         checks.worker = {
           state,
+          ...(RUNTIME_ERROR_CODES.has(worker?.blockerCode) ? { code: worker.blockerCode } : {}),
           ...(phase ? { phase } : {}),
           message:
             state === "running"
@@ -697,7 +731,7 @@ export async function agentStatusMain(args, options = {}) {
                 : phase === "stopping"
                   ? "The worker is stopping and preserving progress. Wait for it to stop before changing setup or restarting."
                   : phase === "blocked"
-                    ? "The running worker has a Mission blocker. Open Missions to resolve it; starting another worker will not resolve the blocker."
+                    ? "The running worker has an execution blocker. Check its error code; starting another worker will not resolve an uncertain run."
                     : phase === "unresponsive"
                       ? "The worker process is present but its status is stale. Inspect or stop it before starting another worker."
                       : "The local worker is not confirmed ready. Check it with totem start for this profile.",

package/bin/connected-agent-service.mjs

@@ -11,13 +11,17 @@ export async function runConnectedAgentService(settings, dependencies = {}) {
     : controller.signal;
   const emit = settings.emit ?? (() => {});
   const phases = { messages: "starting", missions: "starting" };
+  const blockers = {};
   const report = (queue, event) => {
     phases[queue] = event.type === "completed" ? "waiting" : event.type;
+    if (event.type === "blocked") blockers[queue] = { code: event.code, messageId: event.messageId };
+    else delete blockers[queue];
     const values = Object.values(phases);
     const type =
       ["reconnecting", "starting", "blocked", "working"].find((phase) => values.includes(phase)) ??
       "waiting";
-    emit({ ...event, type });
+    const blocked = type === "blocked" ? blockers.messages ?? blockers.missions : undefined;
+    emit({ ...event, type, ...(blocked ?? {}) });
   };
   const messages = async () => {
     let attempts = 0;
@@ -36,7 +40,9 @@ export async function runConnectedAgentService(settings, dependencies = {}) {
               attempts = 0;
               report("messages", { type: "waiting" });
             } else if (event.type === "runtime_error")
-              report("messages", { type: "blocked", code: event.error?.code });
+              report("messages", { type: "blocked", code: event.error?.code, messageId: event.messageId });
+            else if (event.type === "message_started")
+              report("messages", { type: "working", messageId: event.data?.messageId });
             else if (["message_handled", "chat_completed"].includes(event.type))
               report("messages", { type: "waiting" });
           },

package/bin/executor-readiness.mjs

@@ -0,0 +1,67 @@
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { modelReply } from "./network-runtime.mjs";
+import { privateRead, privateWrite } from "./runtime-installation.mjs";
+import { runtimeErrorCode } from "./runtime-diagnostics.mjs";
+
+export async function verifyExecutorReady(profile, env = process.env, options = {}) {
+  const version =
+    options.version ??
+    JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
+  const file = join(profile.stateDirectory, "executor-readiness.json");
+  const binding = JSON.stringify([
+    profile.agentId,
+    profile.provider,
+    profile.client,
+    profile.model,
+    profile.command,
+    profile.commandArgs,
+    profile.agentUrl,
+    profile.qwenUrl,
+    profile.ollamaUrl,
+    profile.nimUrl,
+  ]);
+  const previous = await privateRead(file).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+    return null;
+  });
+  if (previous?.version === version && previous.binding === binding && previous.ready === true)
+    return previous;
+  let response;
+  try {
+    response = await (options.generate ?? modelReply)({
+      provider: profile.client ?? profile.provider,
+      model: profile.client && profile.provider === "qwen-local" ? "default" : profile.model,
+      origin: profile.ollamaUrl ?? "http://127.0.0.1:11434",
+      qwenUrl: profile.qwenUrl,
+      nimUrl: profile.nimUrl,
+      adapterSettings: { ...profile, environment: env },
+      messages: [
+        {
+          role: "user",
+          content:
+            "This is a connection readiness check. Reply READY. No tools, file reads or external actions are authorized.",
+        },
+      ],
+      tools: [],
+      signal: options.signal ?? new AbortController().signal,
+      timeoutMs: 30000,
+    });
+  } catch (error) {
+    await privateWrite(file, {
+      version,
+      binding,
+      ready: false,
+      code: runtimeErrorCode(error),
+      checkedAt: new Date().toISOString(),
+    });
+    throw error;
+  }
+  if (typeof response?.content !== "string" || !response.content.trim())
+    throw Object.assign(new Error("The selected executor did not complete its readiness check."), {
+      code: "INVALID_AGENT_RESULT",
+    });
+  const record = { version, binding, ready: true, checkedAt: new Date().toISOString() };
+  await privateWrite(file, record);
+  return record;
+}

package/bin/inbox-queue.mjs

@@ -1,4 +1,5 @@
 import { setTimeout as sleep } from "node:timers/promises";
+import { transientNetworkError } from "./network-retry.mjs";
 
 // Polling is independent of generation. Unrelated conversations can make
 // progress while one provider turn is slow; one conversation stays ordered.
@@ -11,6 +12,7 @@ export async function runInboxQueue({
   concurrency = 2,
   shouldContinue = () => true,
   once = false,
+  onPollError = () => {},
 }) {
   if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4)
     throw new Error("Inbox concurrency must be between one and four.");
@@ -24,17 +26,28 @@ export async function runInboxQueue({
   try {
     do {
       const oldest = new Map();
-      for await (const message of messages(signal)) {
+      try {
+        for await (const message of messages(signal)) {
+          if (signal.aborted) break;
+          if (
+            active.has(message.id) ||
+            conversations.has(message.conversationId) ||
+            attempted.has(message.id)
+          )
+            continue;
+          if (!(await eligible(message))) continue;
+          // The server yields oldest first. Preserve that order within a chat.
+          if (!oldest.has(message.conversationId)) oldest.set(message.conversationId, message);
+        }
+      } catch (error) {
         if (signal.aborted) break;
-        if (
-          active.has(message.id) ||
-          conversations.has(message.conversationId) ||
-          attempted.has(message.id)
-        )
-          continue;
-        if (!(await eligible(message))) continue;
-        // The server yields oldest first. Preserve that order within a chat.
-        if (!oldest.has(message.conversationId)) oldest.set(message.conversationId, message);
+        if (!transientNetworkError(error)) throw error;
+        onPollError(error);
+        // A failed page must not cancel unrelated generation or dispatch a partial scan.
+        await sleep(Math.max(pollMs, 100), undefined, { signal }).catch((error) => {
+          if (!signal.aborted) throw error;
+        });
+        continue;
       }
       const pending = [...oldest.values()];
       // Give both the backlog and recent conversations a slot, rather than

package/bin/installation.mjs

@@ -17,11 +17,41 @@ export async function activateConnection(profile, env = process.env, options = {
     ...(profile.agentTokenEnv ? { TOTEM_AGENT_TOKEN_ENV: profile.agentTokenEnv } : {}),
   });
   if (!enabled) return { state: "paused", ...service, entry: runtime.cli };
+  const { verifyExecutorReady } = await import("./executor-readiness.mjs");
+  try {
+    await (options.verifyExecutor ?? verifyExecutorReady)(profile, env);
+  } catch (error) {
+    return {
+      state: "needs_attention",
+      ...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.",
+    };
+  }
   const { agentStartMain } = await import("./agent-runner.mjs");
-  await (options.start ?? agentStartMain)(
+  const started = await (options.start ?? agentStartMain)(
     ["--profile", profile.profileName, "--background", "--json"],
     { env, automatic: true, stdout: { write() {} } },
   );
+  if (started !== 0)
+    return {
+      state: "needs_attention",
+      ...service,
+      entry: runtime.cli,
+      code: "WORKER_START_FAILED",
+    };
+  const { readAgentRuntimeStatus } = await import("./agent-runner.mjs");
+  const state = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+  if (!state.running || !["connected", "working", "waiting"].includes(state.phase))
+    return {
+      state: "needs_attention",
+      ...service,
+      entry: runtime.cli,
+      code: state.blockerCode ?? "WORKER_NOT_READY",
+      phase: state.phase,
+    };
   return { state: "running", ...service, entry: runtime.cli };
 }
 
@@ -108,25 +138,47 @@ export async function installationMain(args = [], options = {}) {
   // An upgrade reuses private profiles and starts their existing connections.
   const { opendir } = await import("node:fs/promises");
   let saved = false;
+  const savedProfiles = [];
   try {
     const profiles = await opendir(join(runtime.root, "connections"));
     for await (const entry of profiles)
       if (
         entry.isDirectory() &&
         (!environment.TOTEM_AGENT_ID || entry.name === environment.TOTEM_AGENT_ID)
-      )
+      ) {
         saved = true;
+        savedProfiles.push(entry.name);
+      }
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
   if (saved && options.forceLogin !== true) {
-    const report = { installed: true, connection: "saved", automatic: true, service };
+    const { readAgentProfile } = await import("./agent-profile.mjs");
+    const results = [];
+    for (const name of savedProfiles) {
+      const profile = await readAgentProfile(name, { environment });
+      results.push({
+        profile: name,
+        ...(await (options.activateConnection ?? activateConnection)(profile, environment)),
+      });
+    }
+    const ready = results.every((result) => ["running", "paused"].includes(result.state));
+    const report = {
+      installed: true,
+      connection: "saved",
+      automatic: true,
+      ready,
+      profiles: results,
+      service,
+    };
     stdout.write(
       flags.json
         ? JSON.stringify(report) + "\n"
-        : "Totem's automatic listener is installed and reuses your saved connections.\n",
+        : ready
+          ? "Totem's automatic listener reuses your saved connections; startup checks passed.\n"
+          : "Totem is installed, but an agent failed its startup check. Run totem status to inspect it.\n",
     );
-    return 0;
+    return ready ? 0 : 1;
   }
   const connection = await (options.beginLogin ?? beginDeviceLogin)(runtime, environment, {
     openBrowser: !flags["no-browser"] && environment.TOTEM_NO_BROWSER !== "1",