totemlayer 0.1.41 → 0.1.44

package/README.md

@@ -4,9 +4,9 @@ Connect your agent to Totem, exchange messages, coordinate approved work, and ve
 
 ## 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.41.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.44.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.
 
-The connection responds to MCP initialization while browser sign-in is pending. `totem_get_connection_status` reports progress; normal tools become available after the exact approved identity is pinned privately. The listener is installed and starts automatically, preserving explicit pauses and existing permissions. Existing-chat delivery is verified separately; the background executor is not evidence of waking the original chat. Remote HTTP connectors alone cannot install local software.
+The connection responds to MCP initialization while browser sign-in is pending. `totem_get_connection_status` reports progress; normal tools become available after the exact approved identity is pinned privately. Before receiving work, the Codex connection verifies the saved identity, durable chat binding, automatic startup, and an exact-chat command callback. It creates a dedicated saved Totem inbox chat when none is bound. Reconnects reuse that chat; explicit owner-selected chats and pauses are preserved. Missing capabilities leave work queued with a setup blocker. Remote HTTP connectors alone cannot install local software.
 
 ## Connect any MCP client
 
@@ -24,7 +24,7 @@ The hosted connection needs no local installation. Sign in to Totem, select your
 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.41.tgz
+npm install --global --ignore-scripts https://totemlayer.com/downloads/totemlayer-0.1.44.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:
@@ -43,7 +43,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.41.tgz totem install
+npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.44.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.
@@ -53,7 +53,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.41.tgz totem login --device-login --no-browser
+npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.44.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.
@@ -85,7 +85,7 @@ Local and hosted MCP tool arguments may contain at most 10,000 combined object m
 
 For pending incoming requests, these tools ask compatible MCP clients to display a native owner-review notification. The notification opens the authenticated receiving-owner review in Totem. Accepting the notification never approves an action; the owner must inspect and approve or deny the exact request. Full access requests that are already approved do not prompt. Clients without MCP elicitation support receive the same logs and an owner-review link.
 
-A hosted HTTP MCP connection needs an active harness turn to read activity; it cannot install a service on the laptop. Supported local client installers also prepare the identity-bound listener by default. Reconnecting local MCP repairs an existing enabled listener, but never changes a saved chat binding, credentials or owner pause. On hosts that support existing-chat delivery, that chat needs an explicitly bound listener profile. Its readiness check queues a bounded challenge and requires a callback from that exact chat using its existing tools and identity. A queued message or app-opening request alone never reports readiness. Closed-app behavior must be verified on the receiving host; an unavailable callback leaves the listener blocked. The host must remain awake and online.
+A hosted HTTP MCP connection needs an active harness turn to read activity; it cannot install a service on the laptop. Supported local client installers also prepare the identity-bound listener by default. Reconnecting local MCP repairs an existing enabled listener, but never changes a saved chat binding, credentials or owner pause. Supported Codex hosts create and verify a dedicated saved chat when no chat is bound. Existing explicit bindings are retained. Codex must support the public app-server session API and queue command. Claude MCP tools remain available, but automatic interactive Claude chat creation is currently unsupported and reports HARNESS_UNSUPPORTED; no text-only responder is substituted. Its readiness check queues a bounded challenge and requires a callback from that exact chat using its existing tools and identity. A queued message or app-opening request alone never reports readiness. Closed-app behavior must be verified on the receiving host; an unavailable callback leaves the listener blocked. The host must remain awake and online.
 
 Follow the owner's instructions before sending messages, sharing code, or delegating Missions. For collaboration, agree on the repository, base commit, separate branches, file scopes, and acceptance criteria. Report the resulting commit and validation evidence.
 

package/bin/agent-profile.mjs

@@ -189,6 +189,7 @@ async function normalizedSettings(input, directory) {
     "ollamaUrl",
     "nimUrl",
     "codexThreadId",
+    "interactiveRequired",
   ]);
   if (Object.keys(input).some((key) => !allowed.has(key))) fail();
   const baseUrl = origin(input.baseUrl);
@@ -223,6 +224,7 @@ async function normalizedSettings(input, directory) {
   const qwenUrl = `${endpoint.origin}/v1`;
   if (input.client !== undefined && !["codex", "claude"].includes(input.client)) fail();
   let codexThreadId;
+  if (input.interactiveRequired !== undefined && input.interactiveRequired !== true) fail();
   if (input.codexThreadId !== undefined) {
     if (
       provider !== "codex" ||
@@ -281,6 +283,7 @@ async function normalizedSettings(input, directory) {
     ),
     ...(input.client === undefined ? {} : { client: input.client }),
     ...(codexThreadId === undefined ? {} : { codexThreadId }),
+    ...(input.interactiveRequired === true ? { interactiveRequired: true } : {}),
   };
 }
 
@@ -404,6 +407,64 @@ export async function withAgentProfileLock(profile, operation) {
   }
 }
 
+/** Narrow startup migration; retain the exact credential generation and all scopes. */
+export async function bindInteractiveProfile(profile, threadId, options = {}) {
+  if (threadId !== undefined && (!UUID.test(threadId) || profile.provider !== "codex")) fail();
+  return withAgentProfileLock(profile, async () => {
+    const binding = profileBindings.get(profile);
+    const { readAgentRuntimeStatus, requestStop } = await import("./agent-runner.mjs");
+    const readStatus = options.readStatus ?? readAgentRuntimeStatus;
+    const status = await readStatus(profile);
+    if (status.running) {
+      if (!["waiting", "connected", "blocked", "reconnecting"].includes(status.phase))
+        throw Object.assign(new Error("Finish the current work before binding this listener."), {
+          code: "HARNESS_BUSY",
+        });
+      await (options.stop ?? requestStop)(profile, status.runId);
+      const deadline = Date.now() + (options.stopTimeoutMs ?? 15000);
+      while ((await readStatus(profile)).running) {
+        if (Date.now() >= deadline)
+          throw Object.assign(new Error("The previous listener has not stopped."), {
+            code: "HARNESS_BUSY",
+          });
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+    }
+    const record = JSON.parse(binding.serialized);
+    if (record.codexThreadId && threadId && record.codexThreadId !== threadId) fail();
+    const input = Object.fromEntries(
+      Object.entries(record).filter(
+        ([key]) => !["version", "profileName", "credentialGeneration"].includes(key),
+      ),
+    );
+    const settings = await normalizedSettings(
+      { ...input, interactiveRequired: true, ...(threadId ? { codexThreadId: threadId } : {}) },
+      binding.directory,
+    );
+    const serialized = JSON.stringify({
+      version: 1,
+      profileName: profile.profileName,
+      ...settings,
+      credentialGeneration: record.credentialGeneration,
+    });
+    const temporary = join(binding.directory, `.harness-${randomUUID()}.tmp`);
+    try {
+      await writePrivate(temporary, serialized);
+      await readAgentCredential(profile);
+      await rename(temporary, join(binding.directory, "profile.json"));
+    } finally {
+      await unlink(temporary).catch(() => {});
+    }
+    return publicProfile(
+      profile.profileName,
+      binding.directory,
+      settings,
+      record.credentialGeneration,
+      serialized,
+    );
+  });
+}
+
 export async function saveAgentProfile(profileName = "default", input, credential, options = {}) {
   let lock;
   let lockPath;

package/bin/agent-runner.mjs

@@ -287,6 +287,14 @@ function eventState(event) {
 
 /** Only fixed labels and validated IDs leave the local worker; model output never becomes a log. */
 export async function runAgentSession(profile, options = {}) {
+  if (
+    profile.interactiveRequired &&
+    (!profile.codexThreadId ||
+      !(await (await import("./harness-bootstrap.mjs")).harnessStartupReady(profile)))
+  )
+    throw Object.assign(new Error("The interactive harness has not been bound."), {
+      code: "HARNESS_SETUP_REQUIRED",
+    });
   const intervalMs = options.statusIntervalMs ?? 1000;
   if (!Number.isInteger(intervalMs) || intervalMs < 10 || intervalMs > 60_000)
     throw new Error("Invalid agent status interval.");
@@ -521,6 +529,15 @@ export async function agentStartMain(args, options = {}) {
     return 0;
   }
   const profile = await readAgentProfile(parsed.profile, { environment });
+  if (
+    profile.interactiveRequired &&
+    (!profile.codexThreadId ||
+      !(await (await import("./harness-bootstrap.mjs")).harnessStartupReady(profile)))
+  )
+    throw Object.assign(
+      new Error("This listener is waiting for its owner-bound interactive harness."),
+      { code: "HARNESS_SETUP_REQUIRED" },
+    );
   if (!options.automatic) {
     const { setAutomaticEnabled } = await import("./automatic-runtime.mjs");
     await setAutomaticEnabled(profile, true);

package/bin/agent-setup.mjs

@@ -462,6 +462,7 @@ export async function agentSetupMain(args, options = {}) {
           repositoryRoots,
           ...(["codex", "claude"].includes(mode) ? { client: mode } : {}),
           ...(codexThreadId === undefined ? {} : { codexThreadId }),
+          ...(previous?.interactiveRequired ? { interactiveRequired: true } : {}),
         },
         key,
         {

package/bin/automatic-runtime.mjs

@@ -176,7 +176,7 @@ export async function superviseOnce(env = process.env, options = {}) {
   return results;
 }
 const execute = promisify(execFile);
-async function processIdentity(pid) {
+export async function processIdentity(pid) {
   if (!Number.isSafeInteger(pid) || pid <= 1) return null;
   try {
     process.kill(pid, 0);

package/bin/harness-bootstrap.mjs

@@ -0,0 +1,344 @@
+import { spawn, execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { StringDecoder } from "node:string_decoder";
+import {
+  localClientEnvironment,
+  installedClientInvocation,
+  streamingClientInvocation,
+} from "./platform-client.mjs";
+import { privateDirectory, privateRead, privateWrite } from "./runtime-installation.mjs";
+import { bindInteractiveProfile, readAgentCredential } from "./agent-profile.mjs";
+import { automaticEnabled, acquireSupervisorLock } from "./automatic-runtime.mjs";
+import { checkCodexQueueSupport } from "./executor-readiness.mjs";
+
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+const VERSION = JSON.parse(
+  await readFile(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+const failure = (code) =>
+  Object.assign(
+    new Error("Interactive harness setup needs attention. Check this connection's setup status."),
+    { code },
+  );
+const profileFingerprint = async (profile) =>
+  createHash("sha256")
+    .update(
+      JSON.stringify([
+        profile.agentId,
+        profile.address,
+        profile.environment,
+        profile.baseUrl,
+        profile.provider,
+        createHash("sha256")
+          .update(await readAgentCredential(profile))
+          .digest("hex"),
+      ]),
+    )
+    .digest("hex");
+export async function pendingHarnessMigration(profile) {
+  const receipt = await privateRead(join(profile.stateDirectory, "harness-bootstrap.json")).catch(
+    (error) => {
+      if (error.code !== "ENOENT") throw error;
+    },
+  );
+  return Boolean(
+    profile.interactiveRequired &&
+    profile.codexThreadId &&
+    receipt?.version === 1 &&
+    receipt.binding === (await profileFingerprint(profile)) &&
+    ["created", "bound"].includes(receipt.state) &&
+    receipt.threadId === profile.codexThreadId,
+  );
+}
+
+// A service can start its supervisor immediately while registration is still in
+// progress. Only a verified registration may release the interactive consumer.
+export async function confirmHarnessStartup(profile) {
+  if (!(await pendingHarnessMigration(profile))) throw failure("HARNESS_SETUP_REQUIRED");
+  await privateWrite(join(profile.stateDirectory, "harness-startup.json"), {
+    version: VERSION,
+    binding: await profileFingerprint(profile),
+    threadId: profile.codexThreadId,
+  });
+}
+export async function harnessStartupReady(profile) {
+  const record = await privateRead(join(profile.stateDirectory, "harness-startup.json")).catch(
+    (error) => {
+      if (error.code !== "ENOENT") throw error;
+    },
+  );
+  return Boolean(
+    record?.version === VERSION &&
+    record.threadId === profile.codexThreadId &&
+    record.binding === (await profileFingerprint(profile)) &&
+    (await pendingHarnessMigration(profile)),
+  );
+}
+
+function hostEnvironment(environment) {
+  const env = localClientEnvironment(environment);
+  for (const key of Object.keys(env))
+    if (
+      /^(TOTEM|AGENTTRUST)_|^(OPENAI_API_KEY|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)$/i.test(key)
+    )
+      delete env[key];
+  return env;
+}
+function hostInvocation(args, env, options) {
+  if ((options.platform ?? process.platform) !== "win32") return { command: "codex", args };
+  return installedClientInvocation("codex", args, env);
+}
+/** Use the public metadata API; this short-lived process never runs a model turn.
+ * The saved chat must separately prove wake/reply through the actual harness. */
+export function connectCodexHarness(environment = process.env, options = {}) {
+  const env = hostEnvironment(environment);
+  const args = ["app-server", "--stdio"];
+  let invocation = hostInvocation(args, env, options);
+  if ((options.platform ?? process.platform) === "win32") {
+    if (invocation.args.includes("-EncodedCommand"))
+      invocation = streamingClientInvocation("codex", args, env);
+  }
+  const child = (options.spawn ?? spawn)(invocation.command, invocation.args, {
+    env,
+    stdio: ["pipe", "pipe", "ignore"],
+    windowsHide: true,
+  });
+  let nextId = 0,
+    buffer = "",
+    closed = false;
+  const pending = new Map();
+  const decoder = new StringDecoder("utf8");
+  let closePromise,
+    finishClose,
+    closeTimer,
+    processClosed = false;
+  const close = () => {
+    if (closePromise) return closePromise;
+    closed = true;
+    closePromise = new Promise((resolve) => {
+      finishClose = resolve;
+    });
+    for (const item of pending.values()) {
+      clearTimeout(item.timer);
+      item.reject(failure("HARNESS_UNAVAILABLE"));
+    }
+    pending.clear();
+    options.signal?.removeEventListener("abort", close);
+    // EOF lets npm's Node wrapper wait for its native Codex child to exit.
+    // Killing only the wrapper leaks the native child and its Windows DB locks.
+    closeTimer = setTimeout(() => {
+      if ((options.platform ?? process.platform) === "win32" && Number.isSafeInteger(child.pid)) {
+        execFile(
+          "taskkill.exe",
+          ["/PID", String(child.pid), "/T", "/F"],
+          { windowsHide: true, timeout: 3000 },
+          () => finishClose(),
+        );
+      } else {
+        child.kill();
+        finishClose();
+      }
+    }, options.closeTimeoutMs ?? 2500);
+    child.stdin.end();
+    if (processClosed) {
+      clearTimeout(closeTimer);
+      finishClose();
+    }
+    return closePromise;
+  };
+  child.once("error", close);
+  child.once("close", () => {
+    processClosed = true;
+    close();
+    clearTimeout(closeTimer);
+    finishClose();
+  });
+  child.stdin.on("error", close);
+  options.signal?.addEventListener("abort", close, { once: true });
+  if (options.signal?.aborted) close();
+  child.stdout.on("data", (data) => {
+    buffer += decoder.write(data);
+    if (Buffer.byteLength(buffer) > 262144) {
+      close();
+      return;
+    }
+    let end;
+    while ((end = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, end);
+      buffer = buffer.slice(end + 1);
+      if (!line.trim()) continue;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        close();
+        return;
+      }
+      // Bootstrap performs no model turns or tool operations. Never auto-approve
+      // an unsolicited request or copy its payload to an owner-visible channel.
+      if (message.method && message.id !== undefined) {
+        child.stdin.write(
+          JSON.stringify({
+            id: message.id,
+            error: { code: -32601, message: "Bootstrap does not handle execution requests" },
+          }) + "\n",
+        );
+        continue;
+      }
+      const item = pending.get(message.id);
+      if (!item) continue;
+      pending.delete(message.id);
+      clearTimeout(item.timer);
+      if (message.error) item.reject(failure("HARNESS_UNAVAILABLE"));
+      else item.resolve(message.result);
+    }
+  });
+  const request = (method, params = {}) =>
+    new Promise((resolve, reject) => {
+      if (closed) {
+        reject(failure("HARNESS_UNAVAILABLE"));
+        return;
+      }
+      const id = ++nextId,
+        timer = setTimeout(() => {
+          pending.delete(id);
+          reject(failure("HARNESS_UNAVAILABLE"));
+        }, options.timeoutMs ?? 15000);
+      pending.set(id, { resolve, reject, timer });
+      child.stdin.write(JSON.stringify({ id, method, params }) + "\n", (error) => {
+        if (error) {
+          pending.delete(id);
+          clearTimeout(timer);
+          reject(failure("HARNESS_UNAVAILABLE"));
+        }
+      });
+    });
+  return {
+    request,
+    close,
+    async initialize() {
+      await request("initialize", {
+        clientInfo: { name: "totem_listener", title: "Totem listener", version: "1" },
+      });
+      child.stdin.write(JSON.stringify({ method: "initialized", params: {} }) + "\n");
+    },
+  };
+}
+
+/** No receiving begins until a durable, exact host session exists and is checked. */
+export async function ensureInteractiveHarness(profile, environment = process.env, options = {}) {
+  if (!(await (options.enabled ?? automaticEnabled)(profile))) return profile;
+  let release;
+  try {
+    release = await acquireSupervisorLock(join(profile.stateDirectory, "harness-setup"));
+  } catch {
+    throw failure("HARNESS_BUSY");
+  }
+  try {
+    return await prepareHarness(profile, environment, options);
+  } finally {
+    await release();
+  }
+}
+
+async function prepareHarness(profile, environment, options) {
+  options.signal?.throwIfAborted();
+  const update = options.bindProfile ?? bindInteractiveProfile;
+  // Persist the requirement first. The normal supervisor must not race setup by
+  // starting the old, unbound conversation-only receiver after a crash.
+  if (!profile.interactiveRequired) profile = await update(profile, undefined, options);
+  if (profile.provider !== "codex") throw failure("HARNESS_UNSUPPORTED");
+  await (options.checkQueue ?? checkCodexQueueSupport)(environment);
+  const fingerprint = await profileFingerprint(profile);
+  const path = join(profile.stateDirectory, "harness-bootstrap.json");
+  let receipt = await privateRead(path).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  if (
+    receipt &&
+    (receipt.version !== 1 ||
+      receipt.binding !== fingerprint ||
+      !["creating", "created", "bound"].includes(receipt.state) ||
+      (receipt.state !== "creating" && !UUID.test(receipt.threadId ?? "")))
+  )
+    throw failure("HARNESS_SETUP_REQUIRED");
+  if (profile.codexThreadId && receipt?.threadId && profile.codexThreadId !== receipt.threadId)
+    throw failure("HARNESS_SETUP_REQUIRED");
+  const rpc = (options.connect ?? connectCodexHarness)(environment, options);
+  try {
+    await rpc.initialize();
+    const cwd = join(profile.stateDirectory, "harness-workspace");
+    if (receipt?.state === "creating") {
+      // Recover only metadata in this identity's dedicated workspace. A lost
+      // creation reply never permits another thread/start or a global search.
+      const list = await rpc.request("thread/list", {
+        cwd,
+        archived: false,
+        sourceKinds: [],
+        limit: 2,
+      });
+      if (
+        list?.data?.length !== 1 ||
+        list.nextCursor ||
+        !UUID.test(list.data[0]?.id ?? "") ||
+        list.data[0].cwd !== cwd ||
+        list.data[0].ephemeral !== false
+      )
+        throw failure("HARNESS_CREATE_UNCERTAIN");
+      receipt = {
+        version: 1,
+        binding: fingerprint,
+        state: "created",
+        threadId: list.data[0].id,
+        createdLocally: true,
+      };
+      await privateWrite(path, receipt);
+    }
+    let threadId = profile.codexThreadId ?? receipt?.threadId;
+    if (!threadId) {
+      await privateDirectory(cwd);
+      await privateWrite(path, { version: 1, binding: fingerprint, state: "creating" });
+      // Omit model, sandbox and approval overrides: the owner's configured
+      // policy and instructions remain authoritative for the new host session.
+      const result = await rpc.request("thread/start", { cwd });
+      if (
+        !UUID.test(result?.thread?.id ?? "") ||
+        result.thread.ephemeral !== false ||
+        result.thread.cwd !== cwd
+      )
+        throw failure("HARNESS_CREATE_UNCERTAIN");
+      threadId = result.thread.id;
+      receipt = {
+        version: 1,
+        binding: fingerprint,
+        state: "created",
+        threadId,
+        createdLocally: true,
+      };
+      await privateWrite(path, receipt);
+    }
+    if (receipt?.state === "created")
+      await rpc.request("thread/name/set", { threadId, name: "Totem inbox" });
+    const checked = await rpc.request("thread/read", { threadId });
+    if (
+      checked?.thread?.id !== threadId ||
+      checked.thread.ephemeral !== false ||
+      checked.thread.archived === true ||
+      (receipt?.createdLocally && checked.thread.cwd !== cwd)
+    )
+      throw failure("HARNESS_SETUP_REQUIRED");
+    if (!profile.codexThreadId) profile = await update(profile, threadId, options);
+    await privateWrite(path, {
+      version: 1,
+      binding: fingerprint,
+      state: "bound",
+      threadId,
+      createdLocally: receipt?.createdLocally === true,
+    });
+    return profile;
+  } finally {
+    await rpc.close();
+  }
+}

package/bin/installation.mjs

@@ -2,7 +2,7 @@ import { parseArgs } from "node:util";
 import { readFile, stat } from "node:fs/promises";
 import { privateRead, privateWrite } from "./runtime-installation.mjs";
 import { join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { ensureInstalledRuntime, installRuntimeService } from "./runtime-installation.mjs";
 import { beginDeviceLogin } from "./device-login.mjs";
 import { resumeDeviceLogin } from "./device-login.mjs";
@@ -22,6 +22,16 @@ 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)
+    return {
+      state: "needs_attention",
+      ready: false,
+      ...service,
+      entry: runtime.cli,
+      code: "HARNESS_SETUP_REQUIRED",
+      message:
+        "Automatic startup is not registered. Incoming work remains queued until host setup succeeds.",
+    };
   const { verifyExecutorReady } = await import("./executor-readiness.mjs");
   try {
     if (profile.codexThreadId) await (options.verifyExecutor ?? verifyExecutorReady)(profile, env);
@@ -35,11 +45,32 @@ export async function activateConnection(profile, env = process.env, options = {
         "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");
-  const result = await (options.start ?? agentStartMain)(
-    ["--profile", profile.profileName, "--background", "--json"],
-    { env, automatic: true, stdout: { write() {} } },
-  );
+  if (profile.interactiveRequired) {
+    const { confirmHarnessStartup } = await import("./harness-bootstrap.mjs");
+    await confirmHarnessStartup(profile);
+  }
+  const start =
+    options.start ??
+    (
+      await import(
+        pathToFileURL(
+          join(
+            runtime.root,
+            "runtime-packages",
+            runtime.version,
+            "node_modules",
+            "totemlayer",
+            "bin",
+            "agent-runner.mjs",
+          ),
+        )
+      )
+    ).agentStartMain;
+  const result = await start(["--profile", profile.profileName, "--background", "--json"], {
+    env,
+    automatic: true,
+    stdout: { write() {} },
+  });
   if (result) throw new Error("The listener could not start. Check totem status for this profile.");
   const status = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
   return {

package/bin/mcp-runtime.mjs

@@ -4,6 +4,7 @@ import { Totem } from "./sdk/index.js";
 import { readAgentCredential, readAgentProfile } from "./agent-profile.mjs";
 import { runtimeRoot } from "./runtime-installation.mjs";
 import { automaticEnabled } from "./automatic-runtime.mjs";
+import { ensureInteractiveHarness } from "./harness-bootstrap.mjs";
 
 function listenerBinding(profile) {
   return {
@@ -81,7 +82,6 @@ export async function ensureMcpListener(config, environment = process.env, optio
           "MCP tools are connected, but this identity has no saved listener on this computer. The owner must run totem setup with this agent's private key and selected executor once. Hosted MCP cannot install a local listener.",
       };
     const setup = options.setup ?? (await import("./agent-setup.mjs")).agentSetupMain;
-    let output = "";
     const result = await setup(
       [
         "--profile",
@@ -100,11 +100,8 @@ export async function ensureMcpListener(config, environment = process.env, optio
       ],
       {
         env: environment,
-        stdout: {
-          write(chunk) {
-            output = (output + chunk).slice(-65536);
-          },
-        },
+        deferActivation: true,
+        stdout: { write() {} },
         stderr: { write() {} },
       },
     );
@@ -116,9 +113,6 @@ export async function ensureMcpListener(config, environment = process.env, optio
           "MCP tools are connected. The listener setup did not confirm readiness; inspect totem status. No repository or peer permission was added.",
       };
     profile = await readAgentProfile(identity.id, { environment });
-    const created = JSON.parse(output);
-    if (!created.automatic) throw new Error("Listener setup did not return its startup status.");
-    return { ...created.automatic, ...listenerBinding(profile) };
   }
   if (!(await automaticEnabled(profile)))
     return {
@@ -129,6 +123,21 @@ export async function ensureMcpListener(config, environment = process.env, optio
         "This listener was explicitly stopped. Its opt-out remains in effect; totem start can resume it.",
     };
   const activate = options.activate ?? (await import("./installation.mjs")).activateConnection;
+  if (["codex", "claude"].includes(profile.client ?? profile.provider)) {
+    try {
+      profile = await (options.ensureHarness ?? ensureInteractiveHarness)(profile, environment);
+    } catch (error) {
+      return {
+        state: "needs_attention",
+        ready: false,
+        persistent: false,
+        ...listenerBinding(profile),
+        code: error.code ?? "HARNESS_SETUP_REQUIRED",
+        message:
+          "The owner-bound interactive harness has not passed setup. Incoming work remains queued; no text-only receiver was started.",
+      };
+    }
+  }
   const status = await activate(profile, environment);
   return { ...status, ...listenerBinding(profile) };
 }
@@ -149,14 +158,26 @@ export async function readMcpListenerStatus(config, environment, initial, option
       throw new Error("Listener binding changed");
     const status = { ...initial, ready: false, checkedAt: new Date().toISOString() };
     if (!(await automaticEnabled(profile))) return { ...status, state: "paused" };
+    if (initial.state === "needs_attention" && initial.code?.startsWith("HARNESS_")) return status;
     const readStatus =
       options.readStatus ?? (await import("./agent-runner.mjs")).readAgentRuntimeStatus;
     const current = await readStatus(profile);
     return {
       ...status,
       ...current,
-      state: !current.running ? "offline" : current.ready ? "ready" : "needs_attention",
-      ready: Boolean(current.running && current.ready),
+      state: !current.running
+        ? "offline"
+        : current.ready &&
+            (!profile.interactiveRequired || profile.codexThreadId) &&
+            initial.persistent
+          ? "ready"
+          : "needs_attention",
+      ready: Boolean(
+        current.running &&
+        current.ready &&
+        initial.persistent &&
+        (!profile.interactiveRequired || profile.codexThreadId),
+      ),
     };
   } catch {
     return {

package/bin/mcp.mjs

@@ -7,7 +7,7 @@ import { Totem } from "./sdk/index.js";
 import { inspectLocalRepository, verifyLocalRepoClaim } from "./repository.mjs";
 import { createApprovalReview } from "./mcp-approval-review.mjs";
 import { loadMcpIdentityBinding, createMcpIdentityGuard } from "./mcp-identity-binding.mjs";
-const VERSION = "0.1.41";
+const VERSION = "0.1.44";
 const MAX_KEY_BYTES = 8 * 1024;
 const MAX_ATTACHMENT_BYTES = 2 * 1024 * 1024;
 const MAX_TOOL_INPUT_ELEMENTS = 10_000;

package/bin/plugin-connect.mjs

@@ -12,6 +12,7 @@ import { readAgentCredential, readAgentProfile } from "./agent-profile.mjs";
 import { automaticEnabled, acquireSupervisorLock } from "./automatic-runtime.mjs";
 import { readAgentRuntimeStatus } from "./agent-runner.mjs";
 import { runtimeErrorCode } from "./runtime-diagnostics.mjs";
+import { ensureInteractiveHarness, pendingHarnessMigration } from "./harness-bootstrap.mjs";
 import {
   runtimeRoot,
   privateDirectory,
@@ -97,6 +98,8 @@ export function createPluginConnector(selection, options = {}) {
     setup,
     registered = false;
   let state = { state: "connecting", ready: false, persistent: false };
+  let harnessBlocked;
+  const migratedProfiles = new WeakSet();
   const readProfile = options.readProfile ?? readAgentProfile;
   const readCredential = options.readCredential ?? readAgentCredential;
   const readStatus = options.readStatus ?? readAgentRuntimeStatus;
@@ -166,15 +169,24 @@ export function createPluginConnector(selection, options = {}) {
       throw unavailable();
   }
   async function pinProfile(profile) {
-    const { value, key } = await profileBinding(profile);
+    const handedOff = profile;
+    if (migratedProfiles.has(profile)) profile = await verifyBinding();
+    const initial = await profileBinding(profile);
+    const key = initial.key;
     await verifyIdentity(profile, key);
-    if (binding && !same(binding, value)) throw unavailable();
+    const resumable = async (old) =>
+      old.codexThreadId === null &&
+      same({ ...old, codexThreadId: initial.value.codexThreadId }, initial.value) &&
+      (await pendingHarnessMigration(profile));
+    if (binding && !same(binding, initial.value) && !(await resumable(binding)))
+      throw unavailable();
     const disk = await privateRead(bindingPath).catch((error) => {
       if (error.code !== "ENOENT") throw error;
     });
-    if (disk && !same(assertBinding(disk), value)) throw unavailable();
-    if (!disk) await privateWrite(bindingPath, value);
-    binding = value;
+    if (disk && !same(assertBinding(disk), initial.value) && !(await resumable(disk)))
+      throw unavailable();
+    if (!disk || !same(disk, initial.value)) await privateWrite(bindingPath, initial.value);
+    binding = initial.value;
     apiKey = key;
     if (!registered) {
       createTotemMcpServer(
@@ -189,6 +201,17 @@ export function createPluginConnector(selection, options = {}) {
       );
       registered = true;
     }
+    // Check/prepare the actual host before starting any background consumer.
+    // This migration cannot change identity, keys, repository scopes or policy.
+    profile = await (options.ensureHarness ?? ensureInteractiveHarness)(profile, env, {
+      signal: controller.signal,
+    });
+    const { value } = await profileBinding(profile);
+    if (!same({ ...initial.value, codexThreadId: value.codexThreadId }, value)) throw unavailable();
+    if (!disk || !same(disk, value)) await privateWrite(bindingPath, value);
+    binding = value;
+    apiKey = key;
+    if (handedOff !== profile) migratedProfiles.add(handedOff);
     state = { state: "starting", ready: false, persistent: false };
   }
   function activationStatus(value) {
@@ -209,14 +232,22 @@ export function createPluginConnector(selection, options = {}) {
         state = { ...state };
         delete state.code;
         if (!(await isEnabled(profile))) state = { ...state, state: "paused", ready: false };
+        else if (harnessBlocked)
+          state = { ...state, state: "needs_attention", ready: false, code: harnessBlocked };
         else if (inherited.TOTEM_AUTO_START === "0" || inherited.CI)
           state = { ...state, state: "disabled_by_request", ready: false };
         else {
           const current = await readStatus(profile);
           state = {
             ...state,
-            state: current.running ? (current.ready ? "ready" : "needs_attention") : "offline",
-            ready: Boolean(current.running && current.ready),
+            state: !current.running
+              ? "offline"
+              : current.ready && binding.codexThreadId && state.persistent
+                ? "ready"
+                : "needs_attention",
+            ready: Boolean(
+              current.running && current.ready && binding.codexThreadId && state.persistent,
+            ),
             ...(current.errorCode && !current.ready
               ? { code: runtimeErrorCode({ code: current.errorCode }) }
               : {}),
@@ -246,7 +277,12 @@ export function createPluginConnector(selection, options = {}) {
               : "separate_restricted_runtime",
           }
         : {}),
-      currentChatWakeVerified: false,
+      currentChatWakeVerified: Boolean(
+        binding?.codexThreadId &&
+        state.ready &&
+        inherited.CODEX_THREAD_ID === binding.codexThreadId,
+      ),
+      boundChatWakeVerified: Boolean(binding?.codexThreadId && state.ready),
       message:
         state.state === "sign_in_required"
           ? "Finish the owner authorization in the opened browser. This installs the listener for the selected identity."
@@ -254,9 +290,11 @@ export function createPluginConnector(selection, options = {}) {
             ? "This listener was explicitly paused. The plugin preserves that choice."
             : state.ready && !state.persistent
               ? "The listener can respond now, but automatic startup at login is not configured on this host. Check its service manager or host permissions before relying on restart recovery."
-              : state.ready
-                ? "The saved listener passed receive, wake and reply verification. This does not verify delivery into the current chat or grant new work permissions."
-                : "MCP access is separate from listener readiness. Check the selected client's sign-in and this connection's setup; no identity or permissions were replaced.",
+              : harnessBlocked
+                ? "Interactive harness setup is incomplete. Incoming work remains queued until the owner-bound chat and its host tools pass readiness. Check this client's supported session integration; no restricted responder was substituted."
+                : state.ready
+                  ? "The owner-bound chat passed receive, wake and reply verification. Its existing host permissions still control every action."
+                  : "MCP access is separate from listener readiness. Check the selected client's sign-in and this connection's setup; no identity or permissions were replaced.",
     };
   }
   server.registerTool(
@@ -304,10 +342,10 @@ export function createPluginConnector(selection, options = {}) {
       if (saved) {
         binding = assertBinding(saved);
         const profile = await readProfile(binding.profile, { environment: env });
-        const current = await profileBinding(profile);
-        if (!same(binding, current.value)) throw unavailable();
         await pinProfile(profile);
-        state = activationStatus(await (options.activate ?? activateConnection)(profile, env));
+        state = activationStatus(
+          await (options.activate ?? activateConnection)(await verifyBinding(), env),
+        );
       } else {
         let partial = "";
         await (options.install ?? installationMain)(
@@ -329,7 +367,7 @@ export function createPluginConnector(selection, options = {}) {
             installService: async () => ({ persistent: false }),
             onProfile: pinProfile,
             activateConnection: async (profile) => {
-              await verifyBinding();
+              profile = await verifyBinding();
               state = activationStatus(
                 await (options.activate ?? activateConnection)(profile, env),
               );
@@ -377,9 +415,21 @@ export function createPluginConnector(selection, options = {}) {
           };
       }
     } catch (error) {
+      harnessBlocked = [
+        "HARNESS_SETUP_REQUIRED",
+        "HARNESS_UNSUPPORTED",
+        "HARNESS_UNAVAILABLE",
+        "HARNESS_BUSY",
+        "HARNESS_CREATE_UNCERTAIN",
+        "AGENT_CLI_INCOMPATIBLE",
+      ].includes(error.code)
+        ? error.code
+        : undefined;
       state = {
         state: "needs_attention",
-        code: error.code === "PLUGIN_BINDING_CHANGED" ? error.code : "CONNECTION_SETUP_REQUIRED",
+        code:
+          harnessBlocked ??
+          (error.code === "PLUGIN_BINDING_CHANGED" ? error.code : "CONNECTION_SETUP_REQUIRED"),
         ready: false,
         persistent: false,
       };

package/bin/runtime-diagnostics.mjs

@@ -54,6 +54,11 @@ export const RUNTIME_ERROR_CODES = new Set([
   "INBOX_CAPACITY_REACHED",
   "WORK_RATE_LIMITED",
   "INTERNAL_ERROR",
+  "HARNESS_SETUP_REQUIRED",
+  "HARNESS_UNSUPPORTED",
+  "HARNESS_UNAVAILABLE",
+  "HARNESS_BUSY",
+  "HARNESS_CREATE_UNCERTAIN",
 ]);
 export function runtimeErrorCode(error) {
   const code = MISSION_ERROR_CODES.get(error?.code) ?? error?.code;

package/bin/runtime-installation.mjs

@@ -72,6 +72,14 @@ export async function ensureInstalledRuntime(env = process.env) {
   const modules = join(root, "runtime-packages", metadata.version, "node_modules");
   const destination = join(modules, "totemlayer");
   await privateDirectory(runtime);
+  // Installation and service activation can happen in separate MCP callbacks.
+  // Retain the upgrade until registration has actually reloaded the supervisor.
+  const refreshPath = join(runtime, "service-refresh.json");
+  if (previousVersion && previousVersion !== metadata.version)
+    await privateWrite(refreshPath, { version: metadata.version });
+  const refresh = await privateRead(refreshPath).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
   await privateDirectory(modules);
   let exists = false;
   try {
@@ -204,7 +212,7 @@ if (process.env.TOTEM_RUNTIME_ENV_LOADED === entry) {
     supervisor,
     directory: runtime,
     version: metadata.version,
-    upgraded: Boolean(previousVersion && previousVersion !== metadata.version),
+    upgraded: refresh?.version === metadata.version,
   };
 }
 const xml = (value) =>
@@ -293,23 +301,51 @@ export async function installRuntimeService(runtime, env = process.env, options
   const run = options.execute ?? execute;
   const node = process.execPath;
   const home = env.HOME ?? env.USERPROFILE ?? homedir();
-  if (runtime.upgraded && platform !== "win32") {
+  const acknowledged = async (result) => {
+    if (runtime.version)
+      await privateWrite(join(runtime.directory, "service-refresh.json"), { version: null });
+    return result;
+  };
+  if (runtime.upgraded) {
     try {
       const status = await privateRead(join(runtime.directory, "supervisor.json"));
-      const { readSupervisorOwner } = await import("./automatic-runtime.mjs");
+      const { readSupervisorOwner, processIdentity } = await import("./automatic-runtime.mjs");
       const owner = (await readSupervisorOwner(join(runtime.directory, "supervisor.lock")))?.owner;
-      if (Number.isSafeInteger(status.pid) && status.pid > 1 && owner?.pid === status.pid) {
-        const processInfo = await run("ps", ["-p", String(status.pid), "-o", "args="], {
+      if (
+        Number.isSafeInteger(status.pid) &&
+        status.pid > 1 &&
+        owner?.pid === status.pid &&
+        owner.identity &&
+        (await (options.processIdentity ?? processIdentity)(status.pid)) === owner.identity
+      ) {
+        const invocation =
+          platform === "win32"
+            ? powershellInvocation(
+                `(Get-CimInstance Win32_Process -Filter 'ProcessId=${status.pid}').CommandLine`,
+                env,
+              )
+            : { command: "ps", args: ["-p", String(status.pid), "-o", "args="] };
+        const processInfo = await run(invocation.command, invocation.args, {
           encoding: "utf8",
           timeout: 3000,
           maxBuffer: 8192,
         });
-        if (processInfo.stdout.trim() === `${node} ${runtime.supervisor}`) {
-          process.kill(status.pid, "SIGTERM");
+        const args = [...processInfo.stdout.trim().matchAll(/"([^"]*)"|(\S+)/g)].map(
+          (match) => match[1] ?? match[2],
+        );
+        const exact =
+          platform === "win32"
+            ? args.length === 2 &&
+              args[0].toLowerCase() === node.toLowerCase() &&
+              args[1].toLowerCase() === runtime.supervisor.toLowerCase()
+            : processInfo.stdout.trim() === `${node} ${runtime.supervisor}`;
+        if (exact) {
+          const signal = options.processSignal ?? process.kill;
+          signal(status.pid, "SIGTERM");
           const deadline = Date.now() + 20000;
           while (Date.now() < deadline) {
             try {
-              process.kill(status.pid, 0);
+              signal(status.pid, 0);
             } catch (error) {
               if (error.code === "ESRCH") break;
               throw error;
@@ -424,12 +460,17 @@ export async function installRuntimeService(runtime, env = process.env, options
         startupCode = "STARTUP_DISABLED";
         throw new Error("Automatic startup was disabled by the owner.");
       }
-      // Preserve an already running supervisor; its launcher uses current.json after restart.
+      // Restart the registered entry in place. Unregister/bootstrap races with
+      // launchd's own KeepAlive recovery and can temporarily lose registration.
       try {
-        await run("launchctl", ["print", `${domain}/${label}`]);
+        const loaded = await run("launchctl", ["print", `${domain}/${label}`]);
+        if (
+          !loaded.stdout.includes(`program = ${node}`) ||
+          !loaded.stdout.includes(runtime.supervisor)
+        )
+          throw new Error("The loaded launch agent does not match this runtime.");
         if (runtime.upgraded) {
-          await run("launchctl", ["bootout", `${domain}/${label}`]);
-          await run("launchctl", ["bootstrap", domain, path]);
+          await run("launchctl", ["kickstart", "-k", `${domain}/${label}`]);
         }
       } catch {
         await run("launchctl", ["bootstrap", domain, path]);
@@ -441,7 +482,7 @@ export async function installRuntimeService(runtime, env = process.env, options
         !verified.stdout.includes(runtime.supervisor)
       )
         throw new Error("The loaded launch agent does not match this runtime.");
-      return { mode: "launchd", persistent: true, label, path };
+      return acknowledged({ mode: "launchd", persistent: true, label, path });
     }
     if (platform === "linux") {
       const path = join(home, ".config", "systemd", "user", unit);
@@ -462,12 +503,12 @@ 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]);
-      return { mode: "systemd-user", persistent: true, label: unit, path };
+      return acknowledged({ mode: "systemd-user", persistent: true, label: unit, path });
     }
     if (platform === "win32") {
       windowsRegistration = await windowsStartup(runtime, node, task, env, run);
       if (windowsRegistration.mode === "scheduled-task")
-        return { mode: "scheduled-task", persistent: true, label: task };
+        return acknowledged({ mode: "scheduled-task", persistent: true, label: task });
     }
   } catch {
     /* Ephemeral/headless hosts often have no user service manager. */
@@ -481,7 +522,7 @@ export async function installRuntimeService(runtime, env = process.env, options
   child.on("error", () => {});
   child.unref();
   return windowsRegistration?.mode === "startup-shortcut"
-    ? { mode: "startup-shortcut", persistent: true, label: task }
+    ? acknowledged({ mode: "startup-shortcut", persistent: true, label: task })
     : {
         mode: "background-supervisor",
         persistent: false,

package/bin/totem.mjs

@@ -239,9 +239,9 @@ function compactDigest(value) {
 function help() {
   writeBrand();
   writeHelpBody(`Start here
-  Install once          npm install --global https://totemlayer.com/downloads/totemlayer-0.1.41.tgz
+  Install once          npm install --global https://totemlayer.com/downloads/totemlayer-0.1.44.tgz
   Confirm installation totem --version
-  Run one-off           npx --yes --package https://totemlayer.com/downloads/totemlayer-0.1.41.tgz totem --help
+  Run one-off           npx --yes --package https://totemlayer.com/downloads/totemlayer-0.1.44.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.41",
+  "version": "0.1.44",
   "description": "Cross-platform CLI for TotemLayer agent identity and authorization",
   "type": "module",
   "bin": {