totemlayer 0.1.44 → 0.1.63

package/bin/agent-setup.mjs

@@ -1,6 +1,7 @@
+import { startupDiagnostic } from "./startup-diagnostics.mjs";
 import { execFile } from "node:child_process";
 import { readFile, stat } from "node:fs/promises";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { parseArgs, promisify, stripVTControlCharacters } from "node:util";
 
@@ -12,6 +13,7 @@ import { installedClientInvocation, localClientEnvironment } from "./platform-cl
 import { inspectLocalRepository } from "./repository.mjs";
 import { Totem } from "./sdk/index.js";
 import { detectInstalledProvider } from "./provider-detection.mjs";
+import { privateRead, privateWrite } from "./runtime-installation.mjs";
 import { RUNTIME_ERROR_CODES } from "./runtime-diagnostics.mjs";
 import { checkCodexQueueSupport, CODEX_QUEUE_UNAVAILABLE_MESSAGE } from "./executor-readiness.mjs";
 
@@ -23,6 +25,7 @@ const IDENTITY_TIMEOUT_MS = 15000;
 export const AGENT_SETUP_HELP = `Connect your agent once
 
   totem setup [--profile default] [--provider qwen-local|ollama-local|nim-local|codex|claude|command|http]
+    [--connection-only]
     [--key-file <private-file>] [--base-url <Totem-origin>] [--agent-id <expected-id>]
     [--repo-root <checkout>]... [--model qwen3.5-9b]
     [--qwen-url http://127.0.0.1:8087/v1] [--install-mcp] [--replace] [--json]
@@ -35,7 +38,8 @@ In a terminal, setup can ask for a hidden connection key. Otherwise use --key-fi
 or provision TOTEM_NETWORK_API_KEY through your cloud environment secret store.
 Keys are never accepted as command arguments. Repeating unchanged setup is safe.
 --replace explicitly replaces this profile's connection settings and credential.
---repo-root approves a checkout for this profile; omit it for connection-only setup.
+--connection-only verifies and saves identity without an executor or worker startup.
+--repo-root approves a checkout for coding Missions; omit it to grant no checkout access.
 --install-mcp connects Codex or Claude using the saved private key-file path.
 Setup automatically detects the installed executor, connects its MCP tools, and
 starts a supervised listener for messages, human Chat, and approved Missions.
@@ -76,6 +80,7 @@ function parse(args, status = false) {
           "agent-token-env": { type: "string" },
           "codex-thread": { type: "string" },
           "install-mcp": { type: "boolean" },
+          "connection-only": { type: "boolean" },
           "no-start": { type: "boolean" },
           "no-mcp": { type: "boolean" },
           replace: { type: "boolean" },
@@ -102,6 +107,24 @@ function parse(args, status = false) {
     !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(options["codex-thread"])
   )
     fail("The owner-selected Codex chat ID must be a valid UUID.");
+  if (
+    options["connection-only"] &&
+    [
+      "provider",
+      "model",
+      "repo-root",
+      "install-mcp",
+      "qwen-url",
+      "ollama-url",
+      "nim-url",
+      "command",
+      "command-arg",
+      "agent-url",
+      "agent-token-env",
+      "codex-thread",
+    ].some((name) => options[name] !== undefined)
+  )
+    fail("Use --connection-only without executor, MCP installation, or repository options.");
   return options;
 }
 
@@ -215,10 +238,7 @@ function dependencies(options) {
     ask,
     readSecret: readHiddenCredential,
     runClient: async (client, args, environment) => {
-      const invocation =
-        process.platform === "win32"
-          ? installedClientInvocation(client, args, environment)
-          : { command: client, args };
+      const invocation = installedClientInvocation(client, args, environment);
       const pending = execute(invocation.command, invocation.args, {
         env: localClientEnvironment(environment),
         timeout: 5000,
@@ -338,7 +358,9 @@ export async function agentSetupMain(args, options = {}) {
         fail("The saved profile could not be read safely. Inspect it before replacing it.");
     }
     const interactive = Boolean(io.stdin.isTTY && !flags.json);
-    let mode = flags.provider ?? previous?.client ?? previous?.provider;
+    let mode = flags["connection-only"]
+      ? "none"
+      : (flags.provider ?? previous?.client ?? previous?.provider);
     if (!mode || mode === "auto")
       mode = await (io.detectProvider ?? detectInstalledProvider)(io.env);
     if (!mode && interactive) {
@@ -347,28 +369,38 @@ export async function agentSetupMain(args, options = {}) {
     }
     if (!mode)
       fail(
-        "Install and sign in to an AI client, or choose an installed local model with --provider. Totem will connect and start it automatically.",
+        "Use --connection-only to verify and save your connection without an executor. For automatic processing, choose --provider with an authenticated AI client, installed local model, custom command, or HTTPS agent endpoint.",
       );
     if (
-      !["qwen-local", "ollama-local", "nim-local", "codex", "claude", "command", "http"].includes(
-        mode,
-      )
+      ![
+        "none",
+        "qwen-local",
+        "ollama-local",
+        "nim-local",
+        "codex",
+        "claude",
+        "command",
+        "http",
+      ].includes(mode)
     )
       fail("Choose qwen-local, ollama-local, nim-local, codex, claude, command, or http.");
     if (flags["codex-thread"] !== undefined && mode !== "codex")
       fail("Choose --provider codex before binding an existing Codex chat.");
     const codexThreadId =
       mode === "codex" ? (flags["codex-thread"] ?? previous?.codexThreadId) : undefined;
-    const adapterSettings = Object.fromEntries(
-      [
-        ["command", flags.command ?? previous?.command],
-        ["commandArgs", flags["command-arg"] ?? previous?.commandArgs],
-        ["agentUrl", flags["agent-url"] ?? previous?.agentUrl],
-        ["agentTokenEnv", flags["agent-token-env"] ?? previous?.agentTokenEnv],
-        ["ollamaUrl", flags["ollama-url"] ?? previous?.ollamaUrl],
-        ["nimUrl", flags["nim-url"] ?? previous?.nimUrl],
-      ].filter(([, value]) => value !== undefined),
-    );
+    const connectionOnly = mode === "none";
+    const adapterSettings = connectionOnly
+      ? {}
+      : Object.fromEntries(
+          [
+            ["command", flags.command ?? previous?.command],
+            ["commandArgs", flags["command-arg"] ?? previous?.commandArgs],
+            ["agentUrl", flags["agent-url"] ?? previous?.agentUrl],
+            ["agentTokenEnv", flags["agent-token-env"] ?? previous?.agentTokenEnv],
+            ["ollamaUrl", flags["ollama-url"] ?? previous?.ollamaUrl],
+            ["nimUrl", flags["nim-url"] ?? previous?.nimUrl],
+          ].filter(([, value]) => value !== undefined),
+        );
     if (isExternalModelProvider(mode)) {
       try {
         validateModelAdapter(mode, adapterSettings);
@@ -387,7 +419,7 @@ export async function agentSetupMain(args, options = {}) {
         "This profile is bound to another origin. Choose a new profile or explicitly use --replace with a key for the new origin.",
       );
     let selectedRoots = flags["repo-root"];
-    if (!selectedRoots && !previous && interactive) {
+    if (!connectionOnly && !selectedRoots && !previous && interactive) {
       const chosen = await io.ask(
         "Checkout to approve for coding Missions (leave blank for connection only): ",
         io,
@@ -462,7 +494,9 @@ export async function agentSetupMain(args, options = {}) {
           repositoryRoots,
           ...(["codex", "claude"].includes(mode) ? { client: mode } : {}),
           ...(codexThreadId === undefined ? {} : { codexThreadId }),
-          ...(previous?.interactiveRequired ? { interactiveRequired: true } : {}),
+          ...(!connectionOnly && previous?.interactiveRequired
+            ? { interactiveRequired: true }
+            : {}),
         },
         key,
         {
@@ -487,14 +521,24 @@ export async function agentSetupMain(args, options = {}) {
     let automatic;
     // Installer handoff defers activation without turning an owner-approved new
     // connection into a persistent opt-out. An existing pause stays untouched.
-    if (!flags["no-start"] && !io.deferActivation) {
+    if (!connectionOnly && !flags["no-start"] && !io.deferActivation) {
       try {
         const activate =
           io.activateConnection ?? (await import("./installation.mjs")).activateConnection;
         automatic = await activate(profile, io.env);
         if (automatic.entry) io.env = { ...io.env, TOTEM_RUNTIME_ENTRY: automatic.entry };
-      } catch {
+      } catch (error) {
+        const diagnostic = startupDiagnostic(error);
+        if (!diagnostic.retryable)
+          await privateWrite(join(profile.stateDirectory, "automatic-health.json"), {
+            state: "needs_attention",
+            code: "LISTENER_START_FAILED",
+            ...diagnostic,
+            retryAt: null,
+            updatedAt: new Date().toISOString(),
+          });
         automatic = {
+          ...diagnostic,
           state: "needs_attention",
           message:
             "Your connection is saved. The automatic listener could not confirm startup; run totem status to inspect it.",
@@ -503,27 +547,32 @@ export async function agentSetupMain(args, options = {}) {
     }
     const install = Boolean(profile.client && !flags["no-mcp"] && !identity.listenerConnectionId);
     const mcp = install ? await configureMcp(profile, previous, io) : undefined;
-    const next = `Run totem status --profile ${profile.profileName} to check your connection and automatic listener.`;
+    const next = connectionOnly
+      ? `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",
       profile: profile.profileName,
       agent: identity.address,
       origin: baseUrl,
       connection: "verified",
-      mode,
+      mode: connectionOnly ? "connection-only" : mode,
       approvedRepositories: repositoryRoots.length,
-      worker:
-        automatic?.state ??
-        (io.deferActivation && !flags["no-start"] ? "activation_pending" : "disabled_by_request"),
+      worker: connectionOnly
+        ? "not_configured"
+        : (automatic?.state ??
+          (io.deferActivation && !flags["no-start"]
+            ? "activation_pending"
+            : "disabled_by_request")),
       ...(automatic ? { automatic } : {}),
       ...(mcp ? { mcp } : {}),
-      next,
+      next: automatic?.retryable === false ? automatic.recovery : next,
     };
     io.stdout.write(
       safeOutput(
         flags.json
           ? report
-          : `Connected ${identity.address} at ${baseUrl}.\n${mcp ? `${mcp.message}\n` : ""}${next}\n`,
+          : `Connected ${identity.address} at ${baseUrl}.\n${mcp ? `${mcp.message}\n` : ""}${automatic?.state === "needs_attention" ? `${automatic.message ?? "Listener startup needs attention."}\n${automatic.cause ?? ""}\n${automatic.recovery ?? ""}\n` : ""}${report.next}\n`,
         key,
       ) + (flags.json ? "\n" : ""),
     );
@@ -540,6 +589,11 @@ export async function agentSetupMain(args, options = {}) {
 
 async function executorReadiness(profile, io) {
   const provider = profile.client ?? profile.provider;
+  if (provider === "none")
+    return {
+      state: "not_configured",
+      message: "Connection-only profile. No executor is selected.",
+    };
   if (!isExternalModelProvider(provider)) return modelReadiness(profile, io);
   try {
     validateModelAdapter(provider, profile);
@@ -692,7 +746,7 @@ export async function agentStatusMain(args, options = {}) {
       state: profile.repositoryRoots.length ? "verified" : "not_configured",
       message: profile.repositoryRoots.length
         ? "Approved repository origins match their saved checkouts."
-        : "Connection-only profile. Add an explicit --repo-root with setup before coding Missions.",
+        : "No checkout is approved. Add an explicit --repo-root with setup before coding Missions.",
     };
     for (const approved of profile.repositoryRoots) {
       try {
@@ -731,11 +785,17 @@ export async function agentStatusMain(args, options = {}) {
         };
       }
     }
-    checks.worker = {
-      state: "not_checked",
-      message: "Run totem start for this profile to receive approved work.",
-    };
-    if (io.readRuntimeStatus) {
+    checks.worker =
+      profile.provider === "none"
+        ? {
+            state: "not_configured",
+            message: "Connection-only profile. Automatic receiving is not configured.",
+          }
+        : {
+            state: "not_checked",
+            message: "Run totem start for this profile to receive approved work.",
+          };
+    if (profile.provider !== "none" && io.readRuntimeStatus) {
       try {
         const worker = await io.readRuntimeStatus(profile);
         const phases = [
@@ -787,19 +847,22 @@ export async function agentStatusMain(args, options = {}) {
                       : `Check ${profile.provider === "codex" ? "codex login status and the installed Codex CLI version" : profile.provider === "claude" ? "claude auth status and the installed Claude CLI version" : "the configured adapter and model endpoint"}, then restart this profile.`,
               }
             : {}),
+          ...(worker.causeCode ? startupDiagnostic(worker) : {}),
           ...(phase ? { phase } : {}),
           message:
-            state === "running"
-              ? "The listener passed its controlled receive, wake and reply check and reports a current process heartbeat."
-              : phase === "reconnecting"
-                ? "The worker is reconnecting to Totem. Check server availability and let this process retry; do not start another worker."
-                : phase === "stopping"
-                  ? "The worker is stopping and preserving progress. Wait for it to stop before changing setup or restarting."
-                  : phase === "blocked"
-                    ? "The running worker has an execution blocker. Check its error code; starting another worker will not resolve an uncertain run."
-                    : phase === "unresponsive"
-                      ? "The worker process is present but its status is stale. Inspect or stop it before starting another worker."
-                      : "The local worker is not confirmed ready. Check it with totem start for this profile.",
+            worker.causeCode === "HOST_APPROVAL_DENIED"
+              ? "Automatic startup is paused because the host denied approval. Owner action is required."
+              : state === "running"
+                ? "The listener passed its controlled receive, wake and reply check and reports a current process heartbeat."
+                : phase === "reconnecting"
+                  ? "The worker is reconnecting to Totem. Check server availability and let this process retry; do not start another worker."
+                  : phase === "stopping"
+                    ? "The worker is stopping and preserving progress. Wait for it to stop before changing setup or restarting."
+                    : phase === "blocked"
+                      ? "The running worker has an execution blocker. Check its error code; starting another worker will not resolve an uncertain run."
+                      : phase === "unresponsive"
+                        ? "The worker process is present but its status is stale. Inspect or stop it before starting another worker."
+                        : "The local worker is not confirmed ready. Check it with totem start for this profile.",
         };
       } catch {
         checks.worker = {
@@ -808,6 +871,26 @@ export async function agentStatusMain(args, options = {}) {
         };
       }
     }
+    if (profile.provider !== "none" && checks.worker.state !== "running") {
+      const health = await privateRead(join(profile.stateDirectory, "automatic-health.json")).catch(
+        (error) => {
+          if (error.code !== "ENOENT") throw error;
+        },
+      );
+      if (health?.code === "LISTENER_START_FAILED")
+        checks.worker = {
+          ...checks.worker,
+          state: "needs_attention",
+          errorCode: health.code,
+          ...startupDiagnostic(health),
+          ...(health.retryable === false
+            ? {
+                message:
+                  "Automatic startup is paused because the host denied approval. Owner action is required.",
+              }
+            : {}),
+        };
+    }
     const ok = checks.credential.state === "verified";
     const executionReady =
       ok && checks.model.state === "available" && checks.worker.state === "running";
@@ -828,7 +911,10 @@ export async function agentStatusMain(args, options = {}) {
     const output = flags.json
       ? report
       : `${profile.address} at ${profile.baseUrl}\n${Object.entries(checks)
-          .map(([name, check]) => `${name}: ${check.state}. ${check.message}`)
+          .map(
+            ([name, check]) =>
+              `${name}: ${check.state}. ${check.message}${check.cause ? ` Cause: ${check.cause}` : ""}${check.recovery ? ` Recovery: ${check.recovery}` : ""}`,
+          )
           .join("\n")}\n`;
     io.stdout.write(safeOutput(output, key) + (flags.json ? "\n" : ""));
     return ok ? 0 : 1;

package/bin/automatic-runtime.mjs

@@ -1,3 +1,5 @@
+import { startupDiagnostic } from "./startup-diagnostics.mjs";
+import { DEFAULT_LISTENER_POLL_MS } from "./sdk/listener.js";
 import { opendir, rm, readFile, lstat, rename, readdir, unlink, rmdir } from "node:fs/promises";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -23,8 +25,10 @@ const PACKAGE_VERSION = JSON.parse(
 
 export async function setAutomaticEnabled(profile, enabled) {
   await privateWrite(join(profile.stateDirectory, "automatic.json"), { enabled });
+  if (enabled) await rm(join(profile.stateDirectory, "automatic-health.json"), { force: true });
 }
 export async function automaticEnabled(profile) {
+  if (profile.provider === "none") return false;
   try {
     return (await privateRead(join(profile.stateDirectory, "automatic.json"))).enabled === true;
   } catch (error) {
@@ -50,11 +54,11 @@ async function reportActivations(client, ids, state, errorCode) {
 export async function superviseOnce(env = process.env, options = {}) {
   const directory = join(runtimeRoot(env), "runtime");
   await Promise.resolve((options.resumeLogin ?? resumeDeviceLogin)({ directory }, env)).catch(
-    async () => {
+    async (error) => {
       await privateWrite(join(directory, "setup-health.json"), {
         state: "error",
         code: "SETUP_NEEDS_ATTENTION",
-        recovery: "Run totem login to inspect authorization and adapter setup.",
+        ...startupDiagnostic(error),
         updatedAt: new Date().toISOString(),
       });
     },
@@ -75,6 +79,7 @@ export async function superviseOnce(env = process.env, options = {}) {
       activationClient;
     try {
       profile = await readAgentProfile(entry.name, { environment: env });
+      if (profile.provider === "none") continue;
       const enabled = await automaticEnabled(profile);
       let activations = [];
       try {
@@ -121,6 +126,15 @@ export async function superviseOnce(env = process.env, options = {}) {
       attempts = Number.isSafeInteger(health?.attempts)
         ? Math.max(0, Math.min(health.attempts, 10))
         : 0;
+      if (health?.retryable === false) {
+        await reportActivations(
+          activationClient,
+          activationIds,
+          "blocked",
+          "LISTENER_START_FAILED",
+        );
+        continue;
+      }
       const newAcceptance = activationIds.some((id) => !health?.activationIds?.includes(id));
       if (!newAcceptance && Number.isFinite(health?.retryAt) && health.retryAt > Date.now())
         continue;
@@ -133,7 +147,10 @@ export async function superviseOnce(env = process.env, options = {}) {
           stdout: { write() {} },
         },
       );
-      if (result) throw new Error("START_FAILED");
+      if (result) {
+        const failure = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+        throw Object.assign(new Error("START_FAILED"), failure);
+      }
       const started = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
       await reportActivations(
         activationClient,
@@ -149,6 +166,7 @@ export async function superviseOnce(env = process.env, options = {}) {
       });
       results.push(entry.name);
     } catch (error) {
+      const diagnostic = startupDiagnostic(error);
       await reportActivations(
         activationClient,
         activationIds,
@@ -164,10 +182,11 @@ export async function superviseOnce(env = process.env, options = {}) {
           state: "error",
           activationIds,
           code: "LISTENER_START_FAILED",
+          ...diagnostic,
           attempts: attempts + 1,
-          retryAt: Date.now() + Math.min(300000, 5000 * 2 ** attempts),
-          recovery:
-            "Inspect totem status. Reauthorize expired/revoked credentials with totem login --reauthorize, or repair the selected adapter.",
+          retryAt: diagnostic.retryable
+            ? Date.now() + Math.min(300000, 5000 * 2 ** attempts)
+            : null,
           updatedAt: new Date().toISOString(),
         }).catch(() => {});
       /* One offline/revoked connection cannot stop other profiles. */
@@ -317,7 +336,7 @@ export async function automaticRuntimeMain(env = process.env, options = {}) {
         updatedAt: new Date().toISOString(),
       });
       await superviseOnce(environment, options);
-      await sleep(options.intervalMs ?? 5000, undefined, {
+      await sleep(options.intervalMs ?? DEFAULT_LISTENER_POLL_MS, undefined, {
         signal: options.signal
           ? AbortSignal.any([controller.signal, options.signal])
           : controller.signal,

package/bin/chat-prompt-limit.mjs

@@ -0,0 +1,67 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import {
+  privateDirectory,
+  privateRead,
+  privateWrite,
+  runtimeRoot,
+} from "./runtime-installation.mjs";
+
+const MINUTE = 60000;
+const HOUR = 60 * MINUTE;
+// Shared by inbox deliveries and readiness checks, across runs and credentials.
+export async function reserveChatPrompt({ configDirectory, threadId, kind, now = Date.now() }) {
+  if (!/^[a-f0-9-]{36}$/.test(threadId ?? "") || !["message", "readiness"].includes(kind))
+    throw new Error("Invalid automatic chat prompt binding.");
+  const root = runtimeRoot(configDirectory ? { TOTEM_CONFIG_DIR: configDirectory } : process.env);
+  await privateDirectory(root);
+  await privateDirectory(join(root, "runtime"));
+  const directory = join(root, "runtime", "chat-prompt-limits");
+  await privateDirectory(directory);
+  const key = createHash("sha256").update(threadId).digest("hex");
+  const { acquireSupervisorLock } = await import("./automatic-runtime.mjs");
+  let release;
+  try {
+    release = await acquireSupervisorLock(join(directory, key));
+  } catch {
+    throw Object.assign(new Error("An automatic chat prompt is already being reserved."), {
+      code: "CHAT_PROMPT_RATE_LIMITED",
+    });
+  }
+  try {
+    const file = join(directory, `${key}.json`);
+    const saved = await privateRead(file).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+      return { attempts: [] };
+    });
+    if (
+      !Array.isArray(saved.attempts) ||
+      saved.attempts.length > 60 ||
+      saved.attempts.some(
+        (item) => !Number.isFinite(item.at) || !["message", "readiness"].includes(item.kind),
+      )
+    )
+      throw new Error("Automatic chat prompt history needs inspection.");
+    const attempts = saved.attempts.filter((item) => now - item.at < HOUR);
+    const readiness = attempts.filter((item) => item.kind === "readiness");
+    const last = Math.max(-Infinity, ...attempts.map((item) => item.at));
+    const lastReadiness = Math.max(-Infinity, ...readiness.map((item) => item.at));
+    const retryAt = Math.max(
+      last + 10000,
+      attempts.length >= 60 ? Math.min(...attempts.map((item) => item.at)) + HOUR : 0,
+      kind === "readiness" ? lastReadiness + 5 * MINUTE : 0,
+      kind === "readiness" && readiness.length >= 6
+        ? Math.min(...readiness.map((item) => item.at)) + HOUR
+        : 0,
+    );
+    if (now < retryAt)
+      throw Object.assign(
+        new Error("Automatic prompts are cooling down. Unsent work stays in the durable inbox."),
+        { code: "CHAT_PROMPT_RATE_LIMITED", retryAt },
+      );
+    // Reserve before wake/queue. A failed or uncertain attempt still consumes its budget.
+    await privateWrite(file, { attempts: [...attempts, { at: now, kind }] });
+  } finally {
+    await release();
+  }
+}

package/bin/codex-chat-bridge.mjs

@@ -8,6 +8,7 @@ import { installedClientInvocation, localClientEnvironment } from "./platform-cl
 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";
 
 const execute = promisify(execFile);
 const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
@@ -50,7 +51,7 @@ export async function defaultCodexQueue({ threadId, prompt, signal, environment
   await pending;
 }
 
-async function activeTaskForReply(client, message, identity, signal) {
+export async function activeTaskForReply(client, message, identity, signal) {
   // Connection credentials may receive bounded replies, but cannot read task or
   // conversation APIs. Preserve their acknowledgement-only notification path.
   if (identity.listenerConnectionId) return null;
@@ -241,6 +242,12 @@ export async function queueCodexChatMessage({
     );
   if (payloadBytes(prompt) > 7000) prompt = deliveryPrompt(settings, message, true, activeTask);
   if (payloadBytes(prompt) > 7000) throw error("INSPECTION_LIMIT");
+  await reserveChatPrompt({
+    configDirectory: settings.profileConfigDirectory,
+    threadId: settings.codexThreadId,
+    kind: "message",
+    now: now(),
+  });
   await loadChat();
   await journal.save(key, { state: "pending", threadId: settings.codexThreadId });
   try {
@@ -257,18 +264,13 @@ export async function queueCodexChatMessage({
   return { state: "queued" };
 }
 
-/** The linked chat's reply client uses the saved identity and the same output guard. */
-export async function completeCodexChatMessage({
+/** Callbacks inherit exactly the saved owner-selected chat and authenticated identity. */
+export async function loadCodexChatSession({
   profileName,
-  messageId,
-  text,
-  ackOnly = false,
-  readOnly = false,
   environment = process.env,
   createClient = (input) => new Totem(input),
   inspector,
 }) {
-  if (!UUID.test(messageId ?? "")) throw error("AGENT_IDENTITY_MISMATCH");
   const profile = await readAgentProfile(profileName, { environment });
   if (!inspector) {
     const root = dirname(dirname(dirname(dirname(profile.stateDirectory))));
@@ -313,6 +315,32 @@ export async function completeCodexChatMessage({
     identity.environment !== profile.environment
   )
     throw error("AGENT_IDENTITY_MISMATCH");
+  return { profile, client, identity, inspector };
+}
+
+/** The linked chat's reply client uses the saved identity and the same output guard. */
+export async function completeCodexChatMessage({
+  profileName,
+  messageId,
+  text,
+  ackOnly = false,
+  readOnly = false,
+  environment = process.env,
+  createClient = (input) => new Totem(input),
+  inspector,
+}) {
+  if (!UUID.test(messageId ?? "")) throw error("AGENT_IDENTITY_MISMATCH");
+  const {
+    client,
+    identity,
+    inspector: policy,
+  } = await loadCodexChatSession({
+    profileName,
+    environment,
+    createClient,
+    inspector,
+  });
+  inspector = policy;
   const message = await client.messages.get(messageId);
   if (message.to !== identity.address) throw error("AGENT_IDENTITY_MISMATCH");
   await inspectNetworkMessage(inspector, client, message);

package/bin/codex-chat-readiness.mjs

@@ -8,6 +8,7 @@ import { defaultCodexQueue } from "./codex-chat-bridge.mjs";
 import { wakeCodexDesktop } from "./codex-desktop-wake.mjs";
 import { privateDirectory, privateRead } from "./runtime-installation.mjs";
 import { Totem } from "./sdk/index.js";
+import { reserveChatPrompt } from "./chat-prompt-limit.mjs";
 
 const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
 const CHALLENGE = /^[a-f0-9]{64}$/;
@@ -225,6 +226,12 @@ export async function verifyCodexChatReadiness(
     assertRecord(pending, profile, runId, now(), probe.challenge);
     activeSignal.throwIfAborted();
     if (fresh) {
+      await reserveChatPrompt({
+        configDirectory: profileRoot(profile),
+        threadId: profile.codexThreadId,
+        kind: "readiness",
+        now: now(),
+      });
       // This reservation survives both known failures and unknown external outcomes.
       await (options.wake ?? wakeCodexDesktop)({
         threadId: profile.codexThreadId,