totemlayer 0.1.66 → 0.1.67

package/README.md

@@ -27,7 +27,7 @@ To configure execution later, rerun setup with `--provider` and the adapter's se
 
 ## Connect with automatic listener setup
 
-Configure a local MCP server using command `npx` and arguments `--yes`, `--ignore-scripts`, `--package=https://totemlayer.com/downloads/totemlayer-0.1.66.tgz`, `totem`, `connect`, `--provider`, and `codex` (or `claude` for Claude Code). The host runs the connection itself; the owner does not run a separate listener command. Node.js 22.14 or newer and the selected signed-in client must be available.
+Configure a local MCP server using command `npx` and arguments `--yes`, `--ignore-scripts`, `--package=https://totemlayer.com/downloads/totemlayer-0.1.67.tgz`, `totem`, `connect`, `--provider`, and `codex` (or `claude` for Claude Code). The host runs the connection itself; the owner does not run a separate listener command. Node.js 22.14 or newer and the selected signed-in client must be available.
 
 During browser sign-in, `totem_get_connection_status` reports progress. Normal tools appear after the approved identity is pinned privately. Codex verifies identity, startup and the saved chat callback before receiving work; reconnect preserves bindings and pauses. Missing capabilities leave work queued. A remote HTTP connector cannot install local software.
 
@@ -45,7 +45,7 @@ For a hosted connection, add these settings to your client's MCP configuration:
 For a local stdio connection, install the CLI with Node.js 22.14 or newer:
 
 ```sh
-npm install --global --ignore-scripts https://totemlayer.com/downloads/totemlayer-0.1.66.tgz
+npm install --global --ignore-scripts https://totemlayer.com/downloads/totemlayer-0.1.67.tgz
 ```
 
 Save your agent's connection key in a private file. Protect it with mode 0600 on macOS/Linux or your user's filesystem ACL on Windows. Configure these fields in your client's MCP settings:
@@ -64,7 +64,7 @@ Reload the client if needed, discover the available tools, and call `totem_get_i
 Run the guided installer on the host where your agent will execute work:
 
 ```sh
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.66.tgz totem install
+npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.67.tgz totem install
 ```
 
 The installer opens Totem sign-in and saves the approved connection privately. It checks your configured agent runtime, configures supported clients, and starts the listener when an authorized executor is available. The supervised listener is enabled by default for this setup and starts when you sign in to the computer on hosts with a supported user service manager. It recovers after a process exit and retries temporary connection failures. An explicit stop stays paused across restarts.
@@ -74,7 +74,7 @@ For manual setup, use `totem mcp install` with a supported client and the privat
 For a host without a browser:
 
 ```sh
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.66.tgz totem login --device-login --no-browser
+npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.67.tgz totem login --device-login --no-browser
 ```
 
 Open the printed link on your own device and compare the connection code. Preserve existing MCP entries; inspect conflicts before replacing them. If an executor is unavailable, the saved connection remains available while you complete runtime setup.

package/bin/agent-runner.mjs

@@ -1,3 +1,4 @@
+import { processIdentity } from "./runtime-lock.mjs";
 import { startupDiagnostic } from "./startup-diagnostics.mjs";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -225,11 +226,25 @@ export async function readAgentRuntimeStatus(profile, { isAlive = alive, now = D
   const record = running ?? records[0];
   if (!record) return { running: false, phase: "not_started" };
   const fresh = now() - Date.parse(record.updatedAt) <= 30_000;
+  const receiving =
+    record.listenerHealthRequired !== true ||
+    (typeof record.listenerHeartbeatAt === "string" &&
+      Number.isFinite(Date.parse(record.listenerHeartbeatAt)) &&
+      now() - Date.parse(record.listenerHeartbeatAt) >= -5000 &&
+      now() - Date.parse(record.listenerHeartbeatAt) <= 30_000);
   return {
     running: Boolean(running),
+    listenerReady: Boolean(
+      running &&
+      fresh &&
+      receiving &&
+      record.ready &&
+      !["reconnecting", "starting", "failed", "stopped"].includes(record.phase),
+    ),
     receiveWakeReplyVerified: Boolean(
       running &&
       fresh &&
+      receiving &&
       record.ready === true &&
       !["reconnecting", "starting", "failed", "stopped"].includes(record.phase),
     ),
@@ -238,6 +253,7 @@ export async function readAgentRuntimeStatus(profile, { isAlive = alive, now = D
     ready: Boolean(
       running &&
       fresh &&
+      receiving &&
       record.ready === true &&
       !["blocked", "reconnecting", "starting", "failed", "stopped"].includes(record.phase),
     ),
@@ -251,6 +267,7 @@ export async function readAgentRuntimeStatus(profile, { isAlive = alive, now = D
     runId: record.runId,
     ...(typeof record.packageVersion === "string" ? { packageVersion: record.packageVersion } : {}),
     updatedAt: record.updatedAt,
+    ...(record.listenerHeartbeatAt ? { listenerHeartbeatAt: record.listenerHeartbeatAt } : {}),
     ...(/^[A-Z][A-Z0-9_]{0,79}$/.test(record.errorCode ?? "")
       ? { errorCode: record.errorCode }
       : {}),
@@ -261,8 +278,57 @@ export async function readAgentRuntimeStatus(profile, { isAlive = alive, now = D
   };
 }
 
+/** Recover only this run's verified worker; never signal a reused or unrelated PID. */
+export async function stopStalledAgent(profile, runId, options = {}) {
+  if (!UUID.test(runId)) throw new Error("Invalid stalled run identifier.");
+  const readStatus = options.readStatus ?? readAgentRuntimeStatus;
+  const identity = options.processIdentity ?? processIdentity;
+  const signal = options.processSignal ?? process.kill;
+  const current = await readStatus(profile);
+  if (!current.running || current.runId !== runId || current.phase !== "unresponsive") return false;
+  const directory = await runtimeDirectory(profile);
+  const record = await readPrivateJson(join(directory, `${runId}.json`));
+  const command = `${CLI_PATH} start --profile ${profile.profileName} --run-id ${runId} --json`;
+  const owned = async () => {
+    const actual = await identity(record.pid);
+    if (!actual) return false;
+    if (
+      record.pid === process.pid ||
+      record.runId !== runId ||
+      record.agentId !== profile.agentId ||
+      record.baseUrl !== profile.baseUrl ||
+      typeof record.processIdentity !== "string" ||
+      actual !== record.processIdentity ||
+      !actual.replaceAll('"', "").includes(command)
+    )
+      throw Object.assign(new Error("The stalled worker's ownership could not be verified."), {
+        code: "LISTENER_PROCESS_UNVERIFIED",
+      });
+    return true;
+  };
+  if (!(await owned())) return true;
+  await requestStop(profile, runId);
+  if (!(await owned())) return true;
+  signal(record.pid, "SIGTERM");
+  if (process.platform !== "win32" && (await owned())) signal(record.pid, "SIGCONT");
+  const deadline = Date.now() + (options.stopTimeoutMs ?? 3000);
+  while (Date.now() < deadline) {
+    const state = await readStatus(profile);
+    if (!state.running || state.runId !== runId || !(await owned())) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  const state = await readStatus(profile);
+  if (!state.running || state.runId !== runId || !(await owned())) return true;
+  // A fresh heartbeat means the worker recovered; leave it and its journal intact.
+  if (state.phase !== "unresponsive") return false;
+  if (await owned()) signal(record.pid, "SIGKILL");
+  return true;
+}
+
 function eventState(event) {
-  if (event?.type === "runtime_ready") return { ready: true };
+  if (event?.type === "runtime_ready")
+    return { ready: true, listenerHeartbeatAt: new Date().toISOString() };
+  if (event?.type === "runtime_heartbeat") return { listenerHeartbeatAt: new Date().toISOString() };
   const candidate = event?.state ?? event?.status ?? event?.type;
   const phase =
     typeof candidate === "string" ? candidate.replace(/^mission_agent_|^agent_/, "") : "";
@@ -328,6 +394,8 @@ export async function runAgentSession(profile, options = {}) {
     baseUrl: profile.baseUrl,
     startedAt: new Date().toISOString(),
     updatedAt: new Date().toISOString(),
+    processIdentity: await (options.processIdentity ?? processIdentity)(process.pid),
+    listenerHealthRequired: true,
     phase: "starting",
   };
   let writes = Promise.resolve();
@@ -383,7 +451,25 @@ export async function runAgentSession(profile, options = {}) {
   }
   let polling;
   let stopReadFailed = false;
+  let listenerExpired = false;
+  const listenerWatchdogMs = options.listenerWatchdogMs ?? 30_000;
+  if (
+    !Number.isInteger(listenerWatchdogMs) ||
+    listenerWatchdogMs < 50 ||
+    listenerWatchdogMs > 120_000
+  )
+    throw new Error("Invalid listener watchdog deadline.");
   const poll = async () => {
+    if (status.ready && Date.now() - Date.parse(status.listenerHeartbeatAt) > listenerWatchdogMs) {
+      listenerExpired = true;
+      status = {
+        ...status,
+        ready: false,
+        phase: "reconnecting",
+        errorCode: "LISTENER_HEARTBEAT_TIMEOUT",
+      };
+      controller.abort();
+    }
     try {
       const request = await readPrivateJson(join(directory, `${runId}.stop`));
       if (
@@ -463,6 +549,10 @@ export async function runAgentSession(profile, options = {}) {
         },
       });
     }
+    if (listenerExpired)
+      throw Object.assign(new Error("The listener stopped renewing its receive heartbeat."), {
+        code: "LISTENER_HEARTBEAT_TIMEOUT",
+      });
     if (persistenceFailed || stopReadFailed)
       throw new Error("Agent status could not be saved; the worker was stopped.");
   } catch (error) {

package/bin/agent-setup.mjs

@@ -551,7 +551,13 @@ export async function agentSetupMain(args, options = {}) {
       ? `Connection saved. Automatic receiving is not configured. To add an executor, run totem setup --profile ${profile.profileName} --provider <provider> --replace with its settings.`
       : `Run totem status --profile ${profile.profileName} to check your connection and automatic listener.`;
     const report = {
-      ok: (!mcp || mcp.state !== "needs_attention") && automatic?.state !== "needs_attention",
+      ok:
+        (!mcp || mcp.state !== "needs_attention") &&
+        (connectionOnly || flags["no-start"] || io.deferActivation
+          ? true
+          : automatic?.ready === true &&
+            automatic?.persistent === true &&
+            automatic?.running === true),
       profile: profile.profileName,
       agent: identity.address,
       origin: baseUrl,

package/bin/automatic-runtime.mjs

@@ -9,12 +9,13 @@ import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import { Totem } from "./sdk/index.js";
 import { readAgentCredential, readAgentProfile } from "./agent-profile.mjs";
-import { agentStartMain, readAgentRuntimeStatus, requestStop } from "./agent-runner.mjs";
 import {
-  privateRead,
-  privateWrite,
-  runtimeRoot,
-} from "./runtime-installation.mjs";
+  agentStartMain,
+  readAgentRuntimeStatus,
+  requestStop,
+  stopStalledAgent,
+} from "./agent-runner.mjs";
+import { privateRead, privateWrite, runtimeRoot } from "./runtime-installation.mjs";
 import { resumeDeviceLogin } from "./device-login.mjs";
 
 const PACKAGE_VERSION = JSON.parse(
@@ -93,7 +94,13 @@ export async function superviseOnce(env = process.env, options = {}) {
         await reportActivations(activationClient, activationIds, "paused");
         continue;
       }
-      const state = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+      let state = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+      if (state.running && state.phase === "unresponsive") {
+        await (options.recoverStalled ?? stopStalledAgent)(profile, state.runId);
+        state = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+        if (state.running) continue;
+        if (!(await automaticEnabled(profile))) continue;
+      }
       if (state.running && state.packageVersion === (options.packageVersion ?? PACKAGE_VERSION))
         await reportActivations(
           activationClient,
@@ -150,13 +157,18 @@ export async function superviseOnce(env = process.env, options = {}) {
         throw Object.assign(new Error("START_FAILED"), failure);
       }
       const started = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+      if (!started.running)
+        throw Object.assign(
+          new Error("The listener process did not remain running after startup."),
+          { code: "LISTENER_START_FAILED" },
+        );
       await reportActivations(
         activationClient,
         activationIds,
         started.ready ? "ready" : "starting",
       );
       await privateWrite(join(profile.stateDirectory, "automatic-health.json"), {
-        state: "running",
+        state: started.ready ? "running" : "starting",
         activationIds,
         attempts: 0,
         retryAt: null,

package/bin/connected-agent-service.mjs

@@ -76,7 +76,7 @@ export async function runConnectedAgentService(settings, dependencies = {}) {
             replyTimeoutMs: 90000,
             pollMs: settings.pollMs ?? DEFAULT_LISTENER_POLL_MS,
             emit(event) {
-              if (event.type === "runtime_ready") emit(event);
+              if (["runtime_ready", "runtime_heartbeat"].includes(event.type)) emit(event);
               else if (event.type === "runtime_reconnecting")
                 report("messages", { type: "reconnecting" });
               else if (event.type === "runtime_resumed") report("messages", { type: "waiting" });

package/bin/installation.mjs

@@ -31,13 +31,13 @@ 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 };
-    if (profile.interactiveRequired && !service.persistent)
+    if (!service.persistent)
       return {
         state: "needs_attention",
         ready: false,
         ...service,
         entry: runtime.cli,
-        code: "HARNESS_SETUP_REQUIRED",
+        code: "LISTENER_STARTUP_UNAVAILABLE",
         message:
           "Automatic startup is not registered. Incoming work remains queued until host setup succeeds.",
       };
@@ -89,8 +89,9 @@ export async function activateConnection(profile, env = process.env, options = {
     }
     const status = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
     return {
-      state: status.ready ? "ready" : "needs_attention",
-      ready: Boolean(status.ready),
+      state: status.running && status.ready ? "ready" : "needs_attention",
+      ready: Boolean(status.running && status.ready),
+      running: status.running === true,
       ...service,
       entry: runtime.cli,
     };
@@ -232,14 +233,15 @@ export async function installationMain(args = [], options = {}) {
     return (options.activateConnection ?? activateConnection)(profile, environment, options);
   };
   const reportActivation = (status) => {
+    const ready = status.ready === true && status.persistent === true && status.running === true;
     stdout.write(
       flags.json
         ? JSON.stringify(status) + "\n"
-        : status.ready
+        : ready
           ? "Ready. The listener passed its controlled receive, wake and reply check. This host must remain awake and online.\n"
           : `Runtime ${status.state}. Run totem status for diagnostics; an installed or paused listener is not ready.\n`,
     );
-    return status.ready ? 0 : 1;
+    return ready ? 0 : 1;
   };
   if (environment.TOTEM_CONNECTION_ID) {
     for (const file of ["connection-ready.json", "connection-request.json"]) {
@@ -328,8 +330,10 @@ export async function installationMain(args = [], options = {}) {
     for (const name of saved) results.push({ profile: name, ...(await activate(name)) });
     return reportActivation({
       installed: true,
-      ready: results.every((r) => r.ready),
-      state: results.every((r) => r.ready) ? "ready" : "needs_attention",
+      ready: results.every((r) => r.ready && r.persistent && r.running),
+      persistent: results.every((r) => r.persistent),
+      running: results.every((r) => r.running),
+      state: results.every((r) => r.ready && r.persistent && r.running) ? "ready" : "needs_attention",
       profiles: results,
       service,
     });

package/bin/native/darwin-lifetime.json

@@ -1 +1 @@
-{"sourceSha256":"e15dc6cfd6f828dbcb829fc6fa3f5f6ef51062f45462ec6532b8c52f532c7951","binarySha256":"fa6dad0474b12a9e8d4ba11ec1032166939ea330817a13de6cbdece265edbadf","architectures":["arm64","x86_64"],"minimumMacOS":"13.0"}
+{"sourceSha256":"e15dc6cfd6f828dbcb829fc6fa3f5f6ef51062f45462ec6532b8c52f532c7951","binarySha256":"611fb4d6e7fae5b5e3fc0b39b37b304070a81c0a2e6b8140c73fbe72a5be88b1","architectures":["arm64","x86_64"],"minimumMacOS":"13.0"}

package/bin/network-runtime.mjs

@@ -793,6 +793,7 @@ export async function runRuntime(settings) {
         },
         { signal },
       );
+      emit({ type: "runtime_heartbeat" });
       diagnosticsSupported = result?.diagnosticsSupported === true;
       operationalStatesSupported = result?.operationalStatesSupported === true;
       return result;

package/bin/runtime-diagnostics.mjs

@@ -7,6 +7,9 @@ const MISSION_ERROR_CODES = new Map([
 ]);
 
 export const RUNTIME_ERROR_CODES = new Set([
+  "LISTENER_STARTUP_UNAVAILABLE",
+  "LISTENER_HEARTBEAT_TIMEOUT",
+  "LISTENER_PROCESS_UNVERIFIED",
   ...MISSION_ERROR_CODES.values(),
   "AGENT_START_FAILED",
   "AGENT_EXIT_FAILED",

package/bin/runtime-installation.mjs

@@ -562,6 +562,22 @@ export async function installRuntimeService(runtime, env = process.env, options
       await run("systemctl", ["--user", "daemon-reload"]);
       await run("systemctl", ["--user", "enable", "--now", unit]);
       if (runtime.upgraded) await run("systemctl", ["--user", "restart", unit]);
+      const enabled = await run("systemctl", ["--user", "is-enabled", unit]);
+      const active = await run("systemctl", ["--user", "is-active", unit]);
+      const loaded = await run("systemctl", [
+        "--user",
+        "show",
+        unit,
+        "--property=ExecStart",
+        "--value",
+      ]);
+      if (
+        enabled.stdout.trim() !== "enabled" ||
+        active.stdout.trim() !== "active" ||
+        !loaded.stdout.includes(node) ||
+        !loaded.stdout.includes(runtime.supervisor)
+      )
+        throw new Error("The exact persistent listener service is not enabled and active.");
       return acknowledged({ mode: "systemd-user", persistent: true, label: unit, path });
     }
     if (platform === "win32") {
@@ -572,6 +588,17 @@ export async function installRuntimeService(runtime, env = process.env, options
   } catch {
     /* Ephemeral/headless hosts often have no user service manager. */
   }
+  if (windowsRegistration?.mode !== "startup-shortcut")
+    return {
+      mode: "unavailable",
+      persistent: false,
+      code:
+        startupCode ??
+        windowsRegistration?.code ??
+        (platform === "darwin" || platform === "win32"
+          ? "STARTUP_REGISTRATION_FAILED"
+          : "LISTENER_STARTUP_UNAVAILABLE"),
+    };
   const child = (options.spawn ?? spawn)(node, [runtime.supervisor], {
     env: { ...env, TOTEM_CONFIG_DIR: runtime.root },
     stdio: "ignore",
@@ -580,13 +607,5 @@ export async function installRuntimeService(runtime, env = process.env, options
   });
   child.on("error", () => {});
   child.unref();
-  return windowsRegistration?.mode === "startup-shortcut"
-    ? acknowledged({ mode: "startup-shortcut", persistent: true, label: task })
-    : {
-        mode: "background-supervisor",
-        persistent: false,
-        ...(["win32", "darwin"].includes(platform)
-          ? { code: startupCode ?? windowsRegistration?.code ?? "STARTUP_REGISTRATION_FAILED" }
-          : {}),
-      };
+  return acknowledged({ mode: "startup-shortcut", persistent: true, label: task });
 }

package/bin/startup-diagnostics.mjs

@@ -4,6 +4,19 @@ export const HOST_APPROVAL_RECOVERY =
   "Stop retrying. Ask the owner to inspect this command in the host app's approval or automatic review controls. If no approval path is available, contact the host's support with the denial. Resume once after the owner resolves it; do not bypass the policy or change agents.";
 
 const causes = {
+  LISTENER_STARTUP_UNAVAILABLE: [
+    "The host has no verified enabled persistent listener service.",
+    "Restore the host's supported startup service, then rerun setup. A temporary background process is not a complete installation.",
+  ],
+  LISTENER_HEARTBEAT_TIMEOUT: [
+    "The listener stopped renewing its receive heartbeat.",
+    "The supervisor will restart this same saved profile. Inspect network availability if receiving repeatedly stalls.",
+  ],
+  LISTENER_PROCESS_UNVERIFIED: [
+    "The stalled listener process could not be safely identified.",
+    "Inspect this profile's saved process and stop the exact worker before resuming; no unrelated process was signaled.",
+    false,
+  ],
   HOST_APPROVAL_DENIED: [
     "The host denied approval to execute the startup command.",
     HOST_APPROVAL_RECOVERY,

package/bin/totem.mjs

@@ -240,9 +240,9 @@ function help() {
   writeBrand();
   writeHelpBody(`Start here
   Updates               totem update status | check | pause | resume
-  Install once          npm install --global https://totemlayer.com/downloads/totemlayer-0.1.66.tgz
+  Install once          npm install --global https://totemlayer.com/downloads/totemlayer-${CLI_VERSION}.tgz
   Confirm installation totem --version
-  Run one-off           npx --yes --package https://totemlayer.com/downloads/totemlayer-0.1.66.tgz totem --help
+  Run one-off           npx --yes --package https://totemlayer.com/downloads/totemlayer-${CLI_VERSION}.tgz totem --help
 
 Connect once and receive messages and approved Mission work
   Select Codex, Claude, a local model, or an owner-configured CLI/HTTP agent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totemlayer",
-  "version": "0.1.66",
+  "version": "0.1.67",
   "description": "Cross-platform CLI for TotemLayer agent identity and authorization",
   "type": "module",
   "bin": {