totemlayer 0.1.68 → 0.1.75

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.68.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.75.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.68.tgz
+npm install --global --ignore-scripts https://totemlayer.com/downloads/totemlayer-0.1.75.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:
@@ -61,23 +61,19 @@ Reload the client if needed, discover the available tools, and call `totem_get_i
 
 ## Automatic listener setup
 
-Run the guided installer on the host where your agent will execute work:
+Run inside the intended existing native Codex chat, keeping its current model:
 
 ```sh
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.68.tgz totem install
+npx --yes --ignore-scripts --package=https://totemlayer.com/downloads/totemlayer-0.1.75.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.
+Version 0.1.75 uses the strict installer. Read [setup.md](https://totemlayer.com/setup.md) in full first. The strict controller verifies the bundled full guide, exact native session/model and authenticated MCP identity, preserves pauses and existing permissions, and reuses the same connection. It configures exactly one supervised five-second receiver and requires observed recovery, native wake and separate peer-message and website-owner-chat reply receipts. Saved configuration or a readiness echo cannot mark setup complete. Missing or unsupported capabilities return an incomplete result.
 
-For manual setup, use `totem mcp install` with a supported client and the private key file; see `totem mcp install --help` for client-specific options. Where existing-chat delivery is supported, select the actual chat explicitly; no other chat is inferred from a shared identity. `--no-start` keeps that MCP entry tools-only across reconnects. Generic configuration examples and hosted HTTP connections cannot install a listener on a remote computer.
+The supervised setup job returns promptly so its bound chat can receive checks. Run `totem install --status` to inspect progress. It resumes on startup/failure and reports into that same chat. Do not start a second installer or change models to finish setup. The current built-in strict local adapter supports Codex's durable existing session API; other apps use the native MCP/receiver path in setup.md and must report their actual limitations.
 
-For a host without a browser:
+For approval from any phone browser, append `--device-login --no-browser`. The owner compares the displayed code and approves; the receiver stays on the agent's actual available host. iOS/Android chat apps use their own supported custom MCP flow. A mobile browser or remote MCP URL cannot install a desktop service or guarantee background wake in a suspended app. API fallback requires an observed missing custom-MCP capability, or the owner's explicit API choice, and the same receiving checks.
 
-```sh
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.68.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 lifecycle installation only prints guidance. It never starts a receiver or requests authorization before the strict controller knows the intended model/session and pause state. Explicit `totem login` authenticates only; it is not strict setup completion. Connection-only/no-start is an explicit owner opt-out and remains receiving-incomplete.
 
 ## Check or pause your listener
 
@@ -92,7 +88,7 @@ totem diagnose --json
 
 Check the observed receive, wake, and reply results. Stop pauses automatic processing until you start it again. The host must stay awake and online. Upgrades retain saved connections and recovery records. Hosted Context processing is temporarily paused.
 
-Local connections register automatic startup for the signed-in user: launchd on macOS, Task Scheduler on Windows, or a current-user Startup shortcut when task registration is unavailable. The supervisor restarts crashed children with backoff. Startup registration is verified separately from current readiness. Windows/macOS startup policy, deliberate pauses, revoked credentials, sleep, logout and shutdown still apply; no administrator access or new agent permissions are granted.
+Installing the npm package does not register background startup by default. Run `totem install` inside the intended agent to enable it explicitly after its setup checks. Local connections register automatic startup for the signed-in user: launchd on macOS, Task Scheduler on Windows, or a current-user Startup shortcut when task registration is unavailable. The supervisor restarts crashed children with backoff. Startup registration is verified separately from current readiness. Windows/macOS startup policy, deliberate pauses, revoked credentials, sleep, logout and shutdown still apply; no administrator access or new agent permissions are granted.
 
 Connection acceptance and action execution have separate limits. An informed **Accept & start listener** action can enable text replies for that connection; it does not grant access to files, Missions, or arbitrary tools. An explicitly authorized general runtime can process the work its owner permits. Coding work also needs a tool-enabled agent session and approved repository access.
 
@@ -106,7 +102,7 @@ Local and hosted MCP tool arguments may contain at most 10,000 combined object m
 
 Compatible clients show native owner-review notifications for pending requests. Accepting a notification only opens Totem's authenticated review; the owner still approves or denies the exact action. Already-approved Full access requests do not prompt. Other clients receive logs and the same review link.
 
-A hosted HTTP connection cannot install a service or wake a closed task. Supported local installers prepare the bound listener; reconnect repairs only enabled listeners and preserves credentials, pauses and explicit chat bindings. Codex requires its public app-server session API, queue command and a callback from the exact bound chat. It creates a dedicated saved inbox chat when none is bound. A queued message alone does not prove readiness. Claude MCP tools work, but automatic interactive Claude chat creation reports HARNESS_UNSUPPORTED; no text-only responder is substituted. Verify closed-app behavior on the actual awake, online host.
+A hosted HTTP connection cannot install a service or wake a closed task. Supported local installers prepare the bound listener; reconnect repairs only enabled listeners and preserves credentials, pauses and explicit chat bindings. Codex requires its public app-server session API, queue command and a callback from the exact bound chat. The strict installer requires the intended existing chat; other explicitly selected setup paths can create a dedicated inbox when supported. A queued message alone does not prove readiness. Claude MCP tools work, but automatic interactive Claude chat creation reports HARNESS_UNSUPPORTED; no text-only responder is substituted. Verify closed-app behavior on the actual awake, online host.
 
 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

@@ -1,3 +1,4 @@
+import { assertWindowsPrivatePath } from "./windows-private-path.mjs";
 import { constants } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
@@ -90,8 +91,10 @@ async function directories(path, privateRoot, create = false) {
       info = await lstat(current);
     }
     if (info.isSymbolicLink() || !info.isDirectory()) fail();
-    if (current === privateRoot || current.startsWith(`${privateRoot}${sep}`))
+    if (current === privateRoot || current.startsWith(`${privateRoot}${sep}`)) {
       privateDirectory(info);
+      await assertWindowsPrivatePath(current);
+    }
   }
 }
 
@@ -108,6 +111,7 @@ function privateFile(info, maximum) {
 }
 
 async function boundedPrivateRead(path, maximum) {
+  await assertWindowsPrivatePath(path);
   const info = await lstat(path);
   privateFile(info, maximum);
   const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
@@ -136,6 +140,7 @@ async function writePrivate(path, contents) {
     0o600,
   );
   try {
+    await assertWindowsPrivatePath(path);
     await file.writeFile(contents);
     await file.sync();
   } finally {

package/bin/agent-runner.mjs

@@ -1,3 +1,4 @@
+import { assertWindowsPrivatePath } from "./windows-private-path.mjs";
 import { processIdentity } from "./runtime-lock.mjs";
 import { startupDiagnostic } from "./startup-diagnostics.mjs";
 import { spawn } from "node:child_process";
@@ -86,8 +87,10 @@ async function directoryTree(path, privateRoot) {
     const info = await lstat(current);
     if (!info.isDirectory() || info.isSymbolicLink())
       throw new Error("The agent status directory must not contain symbolic links.");
-    if (current === privateRoot || current.startsWith(`${privateRoot}${sep}`))
+    if (current === privateRoot || current.startsWith(`${privateRoot}${sep}`)) {
       privateEntry(info, true);
+      await assertWindowsPrivatePath(current);
+    }
   }
 }
 
@@ -110,6 +113,7 @@ async function runtimeDirectory(profile, create = false) {
 }
 
 async function readPrivateJson(path) {
+  await assertWindowsPrivatePath(path);
   await verifyRuntimeDirectory(dirname(path));
   for (let attempt = 0; ; attempt += 1) {
     const info = await lstat(path);
@@ -268,6 +272,13 @@ export async function readAgentRuntimeStatus(profile, { isAlive = alive, now = D
     ...(typeof record.packageVersion === "string" ? { packageVersion: record.packageVersion } : {}),
     updatedAt: record.updatedAt,
     ...(record.listenerHeartbeatAt ? { listenerHeartbeatAt: record.listenerHeartbeatAt } : {}),
+    ...(Number.isFinite(record.receiveCheckAt) ? { receiveCheckAt: record.receiveCheckAt } : {}),
+    ...(Number.isFinite(record.measuredCheckSeconds)
+      ? { measuredCheckSeconds: record.measuredCheckSeconds }
+      : {}),
+    ...(Number.isFinite(record.receiverIntervalSeconds)
+      ? { receiverIntervalSeconds: record.receiverIntervalSeconds }
+      : {}),
     ...(/^[A-Z][A-Z0-9_]{0,79}$/.test(record.errorCode ?? "")
       ? { errorCode: record.errorCode }
       : {}),
@@ -509,7 +520,11 @@ export async function runAgentSession(profile, options = {}) {
         verifyReadiness: true,
         connectionOnly: Boolean(identity.listenerConnectionId),
         hostKind: (options.env ?? process.env).TOTEM_RUNTIME_HOST_KIND ?? "local",
-        sessionLockDirectory: join(runtimeRoot(options.env ?? process.env), "agent-runtime-locks"),
+        sessionLockDirectory: join(
+          (options.env ?? process.env).TOTEM_HOST_LOCK_ROOT ??
+            runtimeRoot(options.env ?? process.env),
+          "agent-runtime-locks",
+        ),
         profileName: profile.profileName,
         profileConfigDirectory: dirname(dirname(dirname(dirname(profile.stateDirectory)))),
         address: profile.address,
@@ -544,6 +559,17 @@ export async function runAgentSession(profile, options = {}) {
         signal: controller.signal,
         emit: (event) => {
           if (!acceptingEvents) return;
+          if (event.type === "receive_check") {
+            const at = event.data?.checkedAt;
+            if (Number.isFinite(at) && at > (status.receiveCheckAt ?? 0)) {
+              if (Number.isFinite(status.receiveCheckAt))
+                status.measuredCheckSeconds = (at - status.receiveCheckAt) / 1000;
+              status.receiveCheckAt = at;
+              status.receiverIntervalSeconds = event.data.intervalSeconds;
+              void persist();
+            }
+            return;
+          }
           const state = eventState(event);
           if (state) emit(state);
         },

package/bin/agent-setup.mjs

@@ -1,3 +1,4 @@
+import { assertWindowsPrivatePath } from "./windows-private-path.mjs";
 import { startupDiagnostic } from "./startup-diagnostics.mjs";
 import { execFile } from "node:child_process";
 import { readFile, stat } from "node:fs/promises";
@@ -156,6 +157,7 @@ function credential(value) {
 }
 
 async function keyFromFile(path) {
+  await assertWindowsPrivatePath(path);
   try {
     const info = await stat(path);
     if (!info.isFile() || !info.size || info.size > KEY_LIMIT)

package/bin/automatic-runtime.mjs

@@ -51,6 +51,8 @@ async function reportActivations(client, ids, state, errorCode) {
       .catch(() => {});
 }
 export async function superviseOnce(env = process.env, options = {}) {
+  const { resumeStrictSetupJobs } = await import("./strict-setup-jobs.mjs");
+  await (options.resumeSetupJobs ?? resumeStrictSetupJobs)(env);
   const directory = join(runtimeRoot(env), "runtime");
   await Promise.resolve((options.resumeLogin ?? resumeDeviceLogin)({ directory }, env)).catch(
     async (error) => {
@@ -94,6 +96,13 @@ export async function superviseOnce(env = process.env, options = {}) {
         await reportActivations(activationClient, activationIds, "paused");
         continue;
       }
+      const healthPath = join(profile.stateDirectory, "automatic-health.json");
+      const health = await privateRead(healthPath).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+      attempts = Number.isSafeInteger(health?.attempts)
+        ? Math.max(0, Math.min(health.attempts, 10))
+        : 0;
       let state = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
       if (state.running && state.phase === "unresponsive") {
         await (options.recoverStalled ?? stopStalledAgent)(profile, state.runId);
@@ -101,12 +110,21 @@ export async function superviseOnce(env = process.env, options = {}) {
         if (state.running) continue;
         if (!(await automaticEnabled(profile))) continue;
       }
-      if (state.running && state.packageVersion === (options.packageVersion ?? PACKAGE_VERSION))
+      if (state.running && state.packageVersion === (options.packageVersion ?? PACKAGE_VERSION)) {
         await reportActivations(
           activationClient,
           activationIds,
           state.ready ? "ready" : "starting",
         );
+        if (state.ready && (health?.state !== "running" || attempts))
+          await privateWrite(healthPath, {
+            state: "running",
+            activationIds,
+            attempts: 0,
+            retryAt: null,
+            updatedAt: new Date().toISOString(),
+          });
+      }
       if (state.running) {
         if (state.packageVersion === (options.packageVersion ?? PACKAGE_VERSION)) continue;
         // Finish active work before upgrading. Never overlap two workers or clear journals.
@@ -123,14 +141,6 @@ export async function superviseOnce(env = process.env, options = {}) {
         }
         if (!stopped || !(await automaticEnabled(profile))) continue;
       }
-      const health = await privateRead(join(profile.stateDirectory, "automatic-health.json")).catch(
-        (error) => {
-          if (error.code !== "ENOENT") throw error;
-        },
-      );
-      attempts = Number.isSafeInteger(health?.attempts)
-        ? Math.max(0, Math.min(health.attempts, 10))
-        : 0;
       if (health?.retryable === false) {
         await reportActivations(
           activationClient,
@@ -167,11 +177,12 @@ export async function superviseOnce(env = process.env, options = {}) {
         activationIds,
         started.ready ? "ready" : "starting",
       );
-      await privateWrite(join(profile.stateDirectory, "automatic-health.json"), {
+      await privateWrite(healthPath, {
         state: started.ready ? "running" : "starting",
         activationIds,
-        attempts: 0,
-        retryAt: null,
+        // Starting a native chat is not proof that its asynchronous readiness check passed.
+        attempts: started.ready ? 0 : attempts + 1,
+        retryAt: started.ready ? null : Date.now() + Math.min(300000, 5000 * 2 ** attempts),
         updatedAt: new Date().toISOString(),
       });
       results.push(entry.name);

package/bin/codex-chat-bridge.mjs

@@ -1,3 +1,4 @@
+import { withAgentObservation, observeInspector } from "./observability.mjs";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -9,6 +10,7 @@ import { Totem } from "./sdk/index.js";
 import { privateRead } from "./runtime-installation.mjs";
 import { wakeCodexDesktop } from "./codex-desktop-wake.mjs";
 import { reserveChatPrompt } from "./chat-prompt-limit.mjs";
+import { observeSetupDispatch, recordSetupPeerReply } from "./setup-receipts.mjs";
 
 const execute = promisify(execFile);
 const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
@@ -261,6 +263,14 @@ export async function queueCodexChatMessage({
     return { state: "uncertain" };
   }
   await journal.save(key, { state: "queued", threadId: settings.codexThreadId });
+  await observeSetupDispatch({
+    directory: settings.stateDirectory,
+    identity,
+    sessionId: settings.codexThreadId,
+    kind: "peer",
+    id: message.id,
+    text: message.content?.text,
+  });
   return { state: "queued" };
 }
 
@@ -315,7 +325,7 @@ export async function loadCodexChatSession({
     identity.environment !== profile.environment
   )
     throw error("AGENT_IDENTITY_MISMATCH");
-  return { profile, client, identity, inspector };
+  return { profile, client, identity, inspector: observeInspector(inspector) };
 }
 
 /** The linked chat's reply client uses the saved identity and the same output guard. */
@@ -331,6 +341,7 @@ export async function completeCodexChatMessage({
 }) {
   if (!UUID.test(messageId ?? "")) throw error("AGENT_IDENTITY_MISMATCH");
   const {
+    profile,
     client,
     identity,
     inspector: policy,
@@ -343,43 +354,66 @@ export async function completeCodexChatMessage({
   inspector = policy;
   const message = await client.messages.get(messageId);
   if (message.to !== identity.address) throw error("AGENT_IDENTITY_MISMATCH");
-  await inspectNetworkMessage(inspector, client, message);
-  if (readOnly) {
-    if (ackOnly || text !== undefined) throw error("INVALID_PEER_REPLY");
-    return {
-      state: "ready",
-      message: {
-        id: message.id,
-        from: message.from,
-        to: message.to,
-        conversationId: message.conversationId,
-        inReplyToId: message.inReplyToId,
-        content: message.content,
-      },
-    };
-  }
-  if (ackOnly && text !== undefined) throw error("INVALID_PEER_REPLY");
-  if (ackOnly && !message.inReplyToId) throw error("INVALID_PEER_REPLY");
-  if (!ackOnly && message.inReplyToId) {
-    const activeTask = await activeTaskForReply(client, message, identity);
-    if (!activeTask) throw error("INVALID_PEER_REPLY");
-  }
-  let reply;
-  if (!ackOnly) {
-    if (typeof text !== "string" || !text.trim() || text.length > 32768)
-      throw error("INVALID_PEER_REPLY");
-    reply = await inspector.runAction({ id: messageId, text }, (inspected) =>
-      client.messages.reply(inspected.id, inspected.text, {
-        idempotencyKey: `codex-chat:reply:${messageId}`,
-      }),
-    );
-  }
-  await client.messages.ack(messageId);
-  return {
-    state: "confirmed",
-    messageId,
-    ...(reply ? { replyId: reply.id, conversationId: reply.conversationId } : {}),
-  };
+  return withAgentObservation(
+    {
+      client,
+      agentId: identity.id,
+      sessionId: message.conversationId,
+      traceId: "message:" + message.id,
+      input: message.content,
+      output: text,
+      name: readOnly ? "agent.request.read" : "agent.conversation",
+      metadata: { provider: "codex", usageSource: "unavailable" },
+    },
+    async () => {
+      await inspectNetworkMessage(inspector, client, message);
+      if (readOnly) {
+        if (ackOnly || text !== undefined) throw error("INVALID_PEER_REPLY");
+        return {
+          state: "ready",
+          message: {
+            id: message.id,
+            from: message.from,
+            to: message.to,
+            conversationId: message.conversationId,
+            inReplyToId: message.inReplyToId,
+            content: message.content,
+          },
+        };
+      }
+      if (ackOnly && text !== undefined) throw error("INVALID_PEER_REPLY");
+      if (ackOnly && !message.inReplyToId) throw error("INVALID_PEER_REPLY");
+      if (!ackOnly && message.inReplyToId) {
+        const activeTask = await activeTaskForReply(client, message, identity);
+        if (!activeTask) throw error("INVALID_PEER_REPLY");
+      }
+      let reply;
+      if (!ackOnly) {
+        if (typeof text !== "string" || !text.trim() || text.length > 32768)
+          throw error("INVALID_PEER_REPLY");
+        reply = await inspector.runAction({ id: messageId, text }, (inspected) =>
+          client.messages.reply(inspected.id, inspected.text, {
+            idempotencyKey: `codex-chat:reply:${messageId}`,
+          }),
+        );
+      }
+      await client.messages.ack(messageId);
+      if (reply)
+        await recordSetupPeerReply({
+          profile,
+          identity,
+          message,
+          reply,
+          client,
+          sessionId: environment.CODEX_THREAD_ID,
+        });
+      return {
+        state: "confirmed",
+        messageId,
+        ...(reply ? { replyId: reply.id, conversationId: reply.conversationId } : {}),
+      };
+    },
+  );
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/bin/codex-desktop-wake.mjs

@@ -1,22 +1,49 @@
-import {execFile} from "node:child_process";
-import {promisify} from "node:util";
-import {join} from "node:path";
-import {localClientEnvironment} from "./platform-client.mjs";
-const execute=promisify(execFile);
-const UUID=/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { join } from "node:path";
+import { localClientEnvironment } from "./platform-client.mjs";
+const execute = promisify(execFile);
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
 /** Load the owner-selected existing chat using Codex's documented app route; no prompt or authority is added. */
-export async function wakeCodexDesktop({threadId,signal,environment=process.env},options={}){
- if(!UUID.test(threadId??""))throw Object.assign(new Error("AGENT_IDENTITY_MISMATCH"),{code:"AGENT_IDENTITY_MISMATCH"});
- const env=localClientEnvironment(environment);
- for(const name of Object.keys(env))if(/^(?:TOTEM|AGENTTRUST)_|^(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)$/i.test(name))delete env[name];
- const uri=`codex://threads/${threadId}?hostId=local`,platform=options.platform??process.platform;
- let command,args;
- if(platform==="darwin"){command="/usr/bin/open";args=["-g",uri];}
- else if(platform==="win32"){command=env.SystemRoot||env.SYSTEMROOT?join(env.SystemRoot??env.SYSTEMROOT,"explorer.exe"):"explorer.exe";args=[uri];}
- else if(platform==="linux"){command="xdg-open";args=[uri];}
- else throw Object.assign(new Error("AGENT_CLI_INCOMPATIBLE"),{code:"AGENT_CLI_INCOMPATIBLE"});
- const pending=(options.execute??execute)(command,args,{env,signal,timeout:15000,maxBuffer:65536,windowsHide:true});
- pending.child?.stdin?.end();
- await pending;
- return {state:"requested",threadId};
+export async function wakeCodexDesktop(
+  { threadId, signal, environment = process.env },
+  options = {},
+) {
+  if (!UUID.test(threadId ?? ""))
+    throw Object.assign(new Error("AGENT_IDENTITY_MISMATCH"), { code: "AGENT_IDENTITY_MISMATCH" });
+  const env = localClientEnvironment(environment);
+  for (const name of Object.keys(env))
+    if (
+      /^(?:TOTEM|AGENTTRUST)_|^(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)$/i.test(
+        name,
+      )
+    )
+      delete env[name];
+  const uri = `codex://threads/${threadId}?hostId=local`,
+    platform = options.platform ?? process.platform;
+  let command, args;
+  if (platform === "darwin") {
+    command = "/usr/bin/open";
+    args = ["-g", uri];
+  } else if (platform === "win32") {
+    command =
+      env.SystemRoot || env.SYSTEMROOT
+        ? join(env.SystemRoot ?? env.SYSTEMROOT, "explorer.exe")
+        : "explorer.exe";
+    args = [uri];
+  } else if (platform === "linux") {
+    command = "xdg-open";
+    args = [uri];
+  } else
+    throw Object.assign(new Error("AGENT_CLI_INCOMPATIBLE"), { code: "AGENT_CLI_INCOMPATIBLE" });
+  const pending = (options.execute ?? execute)(command, args, {
+    env,
+    signal,
+    timeout: 15000,
+    maxBuffer: 65536,
+    windowsHide: true,
+  });
+  pending.child?.stdin?.end();
+  await pending;
+  return { state: "requested", threadId };
 }

package/bin/codex-human-chat-bridge.mjs

@@ -1,9 +1,11 @@
 import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { withAgentObservation } from "./observability.mjs";
 import { readAgentProfile } from "./agent-profile.mjs";
 import { defaultCodexQueue, loadCodexChatSession } from "./codex-chat-bridge.mjs";
 import { customerInspector } from "./local-inspector.mjs";
 import { privateRead, privateWrite } from "./runtime-installation.mjs";
+import { observeSetupDispatch, recordSetupOwnerChat } from "./setup-receipts.mjs";
 import { reserveChatPrompt } from "./chat-prompt-limit.mjs";
 import { wakeCodexDesktop } from "./codex-desktop-wake.mjs";
 
@@ -142,38 +144,72 @@ export async function queueCodexChatCommand({
     return { state: "uncertain" };
   }
   await privateWrite(file, { ...record, state: "queued" });
+  await observeSetupDispatch({
+    directory: profile.stateDirectory,
+    identity,
+    sessionId: profile.codexThreadId,
+    kind: "ownerChat",
+    id: command.id,
+    text: command.text,
+  });
   return { state: "queued" };
 }
 
 /** Only the linked native chat can read or complete its leased website request. */
 export async function completeCodexChatCommand({ commandId, text, readOnly = false, ...options }) {
-  const { profile, client, inspector } = await loadCodexChatSession(options);
+  const { profile, client, identity, inspector } = await loadCodexChatSession(options);
   const saved = await privateRead(pathFor(profile, commandId));
   const command = { id: commandId, chatId: saved.chatId, commandEventId: saved.commandEventId };
   checkBinding(saved, profile, command);
   const { event, run } = await readCodexChatCommand(client, command);
-  await inspector.assertAllowed("input", event.text);
-  if (readOnly) {
-    if (text !== undefined) throw failure("INVALID_PEER_REPLY");
-    // Prove current lease ownership before the native chat acts, rather than
-    // trusting a private token that another runtime may have superseded.
-    if (run.state === "running") await client.chatCommands.renew(commandId, saved.leaseToken);
-    return { state: run.state, commandId, text: event.text };
-  }
-  if (run.state !== "running" && run.state !== "completed") throw failure("CHAT_LEASE_LOST");
-  if (typeof text !== "string" || !text.trim() || text.length > 32768)
-    throw failure("INVALID_PEER_REPLY");
-  const result = await inspector.runAction(
-    { text },
-    (inspected) =>
-      client.chatCommands.complete(
+  return withAgentObservation(
+    {
+      client,
+      agentId: profile.agentId,
+      sessionId: saved.chatId,
+      traceId: "chat:" + commandId,
+      input: event.text,
+      output: text,
+      name: readOnly ? "agent.request.read" : "agent.conversation",
+      metadata: { provider: "codex", usageSource: "unavailable" },
+    },
+    async () => {
+      await inspector.assertAllowed("input", event.text);
+      if (readOnly) {
+        if (text !== undefined) throw failure("INVALID_PEER_REPLY");
+        // Prove current lease ownership before the native chat acts, rather than
+        // trusting a private token that another runtime may have superseded.
+        if (run.state === "running") await client.chatCommands.renew(commandId, saved.leaseToken);
+        return { state: run.state, commandId, text: event.text };
+      }
+      if (run.state !== "running" && run.state !== "completed") throw failure("CHAT_LEASE_LOST");
+      if (typeof text !== "string" || !text.trim() || text.length > 32768)
+        throw failure("INVALID_PEER_REPLY");
+      const leaseRenewed = run.state === "running";
+      if (leaseRenewed) await client.chatCommands.renew(commandId, saved.leaseToken);
+      const result = await inspector.runAction(
+        { text },
+        (inspected) =>
+          client.chatCommands.complete(
+            commandId,
+            { leaseToken: saved.leaseToken, text: inspected.text },
+            { idempotencyKey: `codex-chat:complete:${commandId}` },
+          ),
+        { task: event.text },
+      );
+      await recordSetupOwnerChat({
+        profile,
+        identity,
         commandId,
-        { leaseToken: saved.leaseToken, text: inspected.text },
-        { idempotencyKey: `codex-chat:complete:${commandId}` },
-      ),
-    { task: event.text },
+        saved,
+        result,
+        text: event.text,
+        leaseRenewed,
+        sessionId: (options.environment ?? process.env).CODEX_THREAD_ID,
+      });
+      return { state: result.run.state, commandId, eventId: result.event.id };
+    },
   );
-  return { state: result.run.state, commandId, eventId: result.event.id };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {