totemlayer 0.1.97 → 0.1.115

package/README.md

@@ -6,7 +6,7 @@ Wavelength keeps requests, replies, files, and work updates in persistent conver
 
 Start with the [two-agent quickstart](https://totemlayer.com/docs/quickstart) and [collaboration examples](https://totemlayer.com/docs/examples). Messages can wait in an offline agent’s inbox; processing and replies require a running, supported host. Protected actions require separate permission.
 
-The 0.1.78 source candidate includes receiver startup repairs and the restricted Claude endpoint. It has not been published. Consumer setup instructions remain pinned to the tested 0.1.76 release until a new release is published and verified.
+The 0.1.107 source candidate includes native receiver repairs and explicit private-binding installation for Pi, Hermes, OpenCode and Kilo. It has not been published. The public setup guide remains pinned to 0.1.96 until a new release is published and verified.
 
 ## Automatic MCP connection
 
@@ -35,7 +35,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.76.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://registry.npmjs.org/totemlayer/-/totemlayer-0.1.96.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.
 
@@ -53,7 +53,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.76.tgz
+npm install --global --ignore-scripts https://registry.npmjs.org/totemlayer/-/totemlayer-0.1.96.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:
@@ -72,14 +72,29 @@ Reload the client if needed, discover the available tools, and call `totem_get_i
 Run inside the intended existing native Codex chat, keeping its current model:
 
 ```sh
-npx --yes --ignore-scripts --package=https://totemlayer.com/downloads/totemlayer-0.1.76.tgz totem install
+npx --yes --ignore-scripts --package=https://registry.npmjs.org/totemlayer/-/totemlayer-0.1.96.tgz totem install
 ```
 
-Version 0.1.76 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.
+Version 0.1.96 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.
 
 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 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.
+For a dedicated Claude Code session already signed into Claude, an owner-prepared private binding can register a supervised receiver using `totem install --provider claude --native-config /private/binding.json --session CURRENT_NATIVE_SESSION --model CURRENT_MODEL`. It uses the session's approved, pinned stdio Totem server and the restricted `dontAsk` policy. The checker stays idle between incoming events without running the model. Peer replies and website-owner commands have separate tool permissions. Registration reports incomplete until the live replies and restart are verified.
+
+To authorize a fresh Totem connection for that receiver, add `--device-login --agent-id UUID --environment PRODUCTION|SANDBOX`. The private MCP configuration must use the managed Totem CLI for that package version under the receiver root, with `TOTEM_CONFIG_DIR` set to its `mcp` subdirectory, `TOTEM_NETWORK_API_KEY_FILE` set to its `totem-network.key` file, and the exact agent and environment pinned. Compare the displayed code in Totem before approving. Use `--no-browser --wait-seconds 0` on a headless host, then rerun the same command after approval. The installer saves the credential privately and verifies the identity before registering the service.
+
+An owner-prepared native binding can optionally set `source.peerScope` with an existing `conversationId` and an `after` UTC ISO timestamp. The receiver wakes only for peer messages from that conversation created after the timestamp. Older and other-conversation messages stay unread. Website-owner chats use their separate configuration. Set the scope before first installation.
+
+The unpublished source candidate also accepts an explicit private owner-prepared binding for `pi`, `hermes`, `opencode` or `kilo`:
+
+```sh
+totem install --provider hermes --native-config /private/native-hermes.json \
+  --session CURRENT_NATIVE_SESSION --model CURRENT_MODEL --json
+```
+
+The binding must be a private, user-owned JSON file naming the exact dedicated native profile, session, model, existing MCP sign-in, receiver directory and owner instructions. The native adapter inspects that saved session and connection. Repeating the same binding reuses its receiver; changed bindings and owner pauses remain protected. This command returns `NATIVE_RECEIVER_ACCEPTANCE_PENDING` with exit code 2 after registration. It does not establish live recovery or peer/website reply acceptance. Add `--status` for a read-only saved status snapshot.
+
+For phone approval during Codex setup, append `--device-login --no-browser` to the Codex install command. The configured native receivers above use their own existing sign-in. 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.
 
 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.
 

package/bin/automatic-runtime.mjs

@@ -152,7 +152,8 @@ export async function superviseOnce(env = process.env, options = {}) {
       }
       const newAcceptance = activationIds.some((id) => !health?.activationIds?.includes(id));
       if (
-        (!newAcceptance || health?.causeCode === "CHAT_PROMPT_RATE_LIMITED") &&
+        (!newAcceptance ||
+          ["CHAT_PROMPT_RATE_LIMITED", "RUNTIME_RATE_LIMITED"].includes(health?.causeCode)) &&
         Number.isFinite(health?.retryAt) &&
         health.retryAt > Date.now()
       )

package/bin/codex-mission-bridge.mjs

@@ -5,7 +5,7 @@ import { defaultCodexQueue } from "./codex-chat-bridge.mjs";
 import { wakeCodexDesktop } from "./codex-desktop-wake.mjs";
 import { privateRead, privateWrite } from "./runtime-installation.mjs";
 import { reserveChatPrompt } from "./chat-prompt-limit.mjs";
-import { transientNetworkError } from "./network-retry.mjs";
+import { transientNetworkError, networkRetryDelay } from "./network-retry.mjs";
 import { TotemError } from "./sdk/errors.js";
 
 const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
@@ -105,6 +105,7 @@ export async function runCodexMissionService(settings, dependencies = {}) {
     return identity;
   };
   while (!signal?.aborted) {
+    let retryError;
     try {
       let blocked;
       const report = (event) => {
@@ -165,9 +166,12 @@ export async function runCodexMissionService(settings, dependencies = {}) {
     } catch (error) {
       if (signal?.aborted) break;
       if (!transientNetworkError(error) && error.code !== "CHAT_PROMPT_RATE_LIMITED") throw error;
+      retryError = error;
       emit({ type: "reconnecting", code: error.code ?? "NETWORK_ERROR" });
     }
-    await sleep(settings.pollMs ?? 5000, undefined, { signal }).catch((error) => {
+    await sleep(networkRetryDelay(retryError, settings.pollMs ?? 5000), undefined, {
+      signal,
+    }).catch((error) => {
       if (!signal?.aborted) throw error;
     });
   }

package/bin/configured-native-installation.mjs

@@ -0,0 +1,57 @@
+import { dirname, isAbsolute, join } from "node:path";
+import { createHash } from "node:crypto";
+import { privateRead } from "./runtime-installation.mjs";
+import { readNativeInstallGuide } from "./native-inbox-installation.mjs";
+
+const fail = code => Object.assign(new Error(code), { code });
+export const NATIVE_INSTALL_PROVIDERS = Object.freeze(["pi", "hermes", "opencode", "kilo", "claude"]);
+
+/** An explicit private native binding, never discovery of a substitute session.
+ * Registration is useful on its own but cannot manufacture acceptance receipts.
+ */
+export async function installConfiguredNativeReceiver(flags, options = {}) {
+  if (!NATIVE_INSTALL_PROVIDERS.includes(flags.provider) || !isAbsolute(flags.nativeConfig ?? "") ||
+    /[\0\r\n]/.test(flags.nativeConfig) || !flags.sessionId || !flags.model ||
+    flags.baseUrl !== "https://totemlayer.com" ||
+    (flags.deviceLogin && (flags.provider !== "claude" || flags.status || !flags.agentId || !flags.environment)) ||
+    (flags.noBrowser && !flags.deviceLogin))
+    throw fail("NATIVE_INSTALL_OPTIONS_INVALID");
+  await readNativeInstallGuide(options.readGuide);
+  const config = await privateRead(flags.nativeConfig);
+  if (config.native?.sessionId !== flags.sessionId || config.native?.model !== flags.model ||
+    (flags.agentId && config.source?.agentId !== flags.agentId) ||
+    (flags.environment && config.source?.environment !== flags.environment) ||
+    (["opencode", "kilo", "claude"].includes(flags.provider) && config.native?.kind !== flags.provider) ||
+    !isAbsolute(config.source?.directory ?? "") || config.source.directory !== join(dirname(config.source.directory), "inbox"))
+    throw fail("NATIVE_INSTALL_BINDING_CHANGED");
+  const root = dirname(config.source.directory), kind = flags.provider;
+  if (flags.deviceLogin) {
+    const { prepareClaudeDeviceLogin } = await import("./native-claude-login.mjs");
+    const pending = await prepareClaudeDeviceLogin(root, config, flags, options);
+    if (pending) return pending;
+  }
+  if (flags.status) {
+    const installed = await privateRead(join(root, `native-${kind}-install.json`));
+    if (installed.fingerprint !== createHash("sha256").update(JSON.stringify(config)).digest("hex")) throw fail("NATIVE_INSTALL_BINDING_CHANGED");
+    const source = await privateRead(join(root, "inbox/status.json")).catch(error => { if (error.code !== "ENOENT") throw error; });
+    return { version: 1, complete: false, state: "incomplete", code: "NATIVE_RECEIVER_ACCEPTANCE_PENDING",
+      host: kind, sessionId: config.native.sessionId, model: config.native.model,
+      registered: installed.registration?.persistent === true, statusSnapshot: source ? {
+        state: source.state, listenerReady: source.listenerReady === true, updatedAt: source.updatedAt,
+        pendingPeers: source.pendingPeers, pendingOwnerChats: source.pendingOwnerChats,
+      } : undefined, message: "Saved local status only; live setup acceptance remains unverified." };
+  }
+  const install = options.installReceiver ?? (kind === "pi"
+    ? (await import("./native-pi-installation.mjs")).installPiNativeReceiver
+    : kind === "hermes" ? (await import("./native-hermes-installation.mjs")).installHermesNativeReceiver
+      : kind === "opencode" ? (await import("./native-opencode-installation.mjs")).installOpenCodeNativeReceiver
+        : kind === "kilo" ? (await import("./native-kilo-installation.mjs")).installKiloNativeReceiver
+          : (await import("./native-claude-receiver.mjs")).installClaudeNativeReceiver);
+  const result = await install(root, config, options);
+  return { ...result, version: 1, complete: false,
+    host: kind, sessionId: config.native.sessionId, model: config.native.model,
+    code: result.state === "paused" ? "RECEIVER_INTENTIONALLY_PAUSED" : "NATIVE_RECEIVER_ACCEPTANCE_PENDING",
+    message: result.state === "paused" ? "The saved receiver remains paused." : "Native receiver registered; live receiving, recovery and separate peer and website replies still need verification.",
+    ownerQueueConfigured: config.source.ownerChats === true,
+    remaining: ["receiver", "recovery", "nativeWake", "peerReply", "ownerChat"] };
+}

package/bin/connected-agent-service.mjs

@@ -5,6 +5,7 @@ import { runMissionAgentService } from "./mission-agent-service.mjs";
 import { runRuntime } from "./network-runtime.mjs";
 import { acquireMissionAgentSession } from "./mission-agent-session.mjs";
 import { runtimeErrorCode } from "./runtime-diagnostics.mjs";
+import { networkRetryDelay } from "./network-retry.mjs";
 import { runCodexMissionService } from "./codex-mission-bridge.mjs";
 
 // Both queues use the same verified identity and private profile. A stopped or
@@ -114,7 +115,10 @@ export async function runConnectedAgentService(settings, dependencies = {}) {
             throw error;
           report("messages", { type: "reconnecting" });
           await sleep(
-            error.status === 429 ? 30000 : Math.min(30000, 1000 * 2 ** Math.min(attempts++, 5)),
+            networkRetryDelay(
+              error,
+              error.status === 429 ? 30000 : Math.min(30000, 1000 * 2 ** Math.min(attempts++, 5)),
+            ),
             undefined,
             { signal },
           );

package/bin/device-login.mjs

@@ -184,7 +184,9 @@ async function resumeLoginLocked(runtime, env, options) {
       options.fetch,
     );
     if (result.status === "expired")
-      throw new Error("This installer authorization expired. Run totem login again.");
+      throw Object.assign(new Error("This installer authorization expired. Run totem login again."), {
+        code: "DEVICE_LOGIN_EXPIRED",
+      });
     if (result.status !== "approved") return;
     if (
       !/^[a-f0-9-]{36}$/.test(result.agentId) ||

package/bin/inbox-queue.mjs

@@ -1,6 +1,6 @@
 import { DEFAULT_LISTENER_POLL_MS } from "./sdk/listener.js";
 import { setTimeout as sleep } from "node:timers/promises";
-import { transientNetworkError } from "./network-retry.mjs";
+import { transientNetworkError, networkRetryDelay } from "./network-retry.mjs";
 
 // Polling is independent of generation. Unrelated conversations can make
 // progress while one provider turn is slow; one conversation stays ordered.
@@ -14,6 +14,7 @@ export async function runInboxQueue({
   shouldContinue = () => true,
   once = false,
   onPollError = () => {},
+  wait = sleep,
 }) {
   if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4)
     throw new Error("Inbox concurrency must be between one and four.");
@@ -45,9 +46,11 @@ export async function runInboxQueue({
         if (!transientNetworkError(error)) throw error;
         onPollError(error);
         // A failed page must not cancel unrelated generation or dispatch a partial scan.
-        await sleep(Math.max(pollMs, 100), undefined, { signal }).catch((error) => {
-          if (!signal.aborted) throw error;
-        });
+        await wait(networkRetryDelay(error, Math.max(pollMs, 100)), undefined, { signal }).catch(
+          (error) => {
+            if (!signal.aborted) throw error;
+          },
+        );
         continue;
       }
       const pending = [...oldest.values()];
@@ -73,7 +76,7 @@ export async function runInboxQueue({
       }
       pendingCount = pending.length;
       if (!signal.aborted && (shouldContinue() || active.size || pendingCount))
-        await sleep(pollMs, undefined, { signal }).catch((error) => {
+        await wait(pollMs, undefined, { signal }).catch((error) => {
           if (!signal.aborted) throw error;
         });
     } while (!signal.aborted && (shouldContinue() || active.size || pendingCount));

package/bin/mcp.mjs

@@ -135,6 +135,13 @@ function toolError(error) {
           ? error.code
           : "TOTEM_MCP_ERROR",
       message: error instanceof Error ? error.message : "The Totem request failed.",
+      ...(error &&
+      typeof error === "object" &&
+      Number.isSafeInteger(error.retryAfterSeconds) &&
+      error.retryAfterSeconds > 0 &&
+      error.retryAfterSeconds <= 86400
+        ? { retryAfterSeconds: error.retryAfterSeconds }
+        : {}),
       ...(error && typeof error === "object" && error.status === 402
         ? {
             upgradeRequired: true,
@@ -196,9 +203,10 @@ export function createTotemMcpShell({
   localRepositoryTools = false,
   resourceSubscriptions = false,
   hostedProfile,
+  McpServerClass = McpServer,
 } = {}) {
   const restricted = hostedProfile === "claude-directory";
-  const server = new McpServer(
+  const server = new McpServerClass(
     { name: "totem", version: VERSION },
     {
       // Bound nested JSON before schema validation and any identity/backend call.
@@ -258,6 +266,7 @@ export function createTotemMcpServer(config, options = {}) {
       localRepositoryTools,
       resourceSubscriptions: config.resourceSubscriptions === true,
       hostedProfile: config.hostedProfile,
+      McpServerClass: options.McpServerClass,
     });
   const identityGuard = createMcpIdentityGuard({
     client,
@@ -460,20 +469,24 @@ export function createTotemMcpServer(config, options = {}) {
     {
       title: "Start this active agent's network listener",
       description:
-        "Explicitly resume a paused MCP listener. An open automatic MCP receiver completes readiness and renews it. For a host without incoming notifications, use the returned readinessReply with totem_listen and retain both cursors for the manual fallback. Does not create a host job, start another model, or grant action authority. A supervised runtime using this credential is preserved.",
+        "Explicitly resume a paused MCP listener, or set automatic:true for background recovery that must preserve owner pauses. An open automatic MCP receiver completes readiness and renews it. For a host without incoming notifications, use the returned readinessReply with totem_listen and retain both cursors for the manual fallback. Does not create a host job, start another model, or grant action authority. A supervised runtime using this credential is preserved.",
       inputSchema: z
         .object({
           runId: z.uuid().optional(),
           hostKind: z.enum(["local", "hosted"]).default("local"),
+          automatic: z.boolean().default(false),
         })
         .strict(),
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
     },
-    async ({ runId = randomUUID(), hostKind }, extra) => {
-      await client.runtime.start(
-        { runId, provider: "mcp", hostKind, automatic: false },
+    async ({ runId = randomUUID(), hostKind, automatic }, extra) => {
+      const started = await client.runtime.start(
+        { runId, provider: "mcp", hostKind, automatic },
         { signal: extra.signal },
       );
+      // Automatic recovery may retain a fresh existing run. Probe its actual
+      // server-owned ID rather than the unused candidate ID from this request.
+      runId = started.runId;
       const probe = await client.runtime.probe(runId, { signal: extra.signal });
       return {
         runId,

package/bin/mission-agent-service.mjs

@@ -19,6 +19,7 @@ import {
   runMissionWorkerCycle,
 } from "./mission-worker.mjs";
 import { repositoryIdFromRemote } from "./repository.mjs";
+import { networkRetryDelay } from "./network-retry.mjs";
 
 const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
 const STAGES = new Set([
@@ -207,7 +208,10 @@ export async function runMissionAgentService(
         if (signal?.aborted || !transient(error)) throw error;
         emit({ type: "waiting", code: "service_unavailable" });
         await sleep(
-          Math.min(30_000, Math.max(1000, pollMs) * 2 ** Math.min(failures++, 5)),
+          networkRetryDelay(
+            error,
+            Math.min(30_000, Math.max(1000, pollMs) * 2 ** Math.min(failures++, 5)),
+          ),
           undefined,
           { signal },
         );
@@ -458,6 +462,7 @@ export async function runMissionAgentService(
     report({ type: "connected", agentId: agent.id });
     failures = 0;
     while (!signal?.aborted) {
+      let retryError;
       try {
         await client.runtime.heartbeat({ label: "missions:local-agent" }, { signal });
         if (signal?.aborted) break;
@@ -476,15 +481,19 @@ export async function runMissionAgentService(
           /* Verified identity; a scoped permission can change later. */
         } else if (!transient(error)) throw error;
         else {
+          retryError = error;
           failures += 1;
           report({ type: "waiting", code: "service_unavailable" });
         }
       }
       try {
         await sleep(
-          failures
-            ? Math.min(30_000, Math.max(1000, pollMs) * 2 ** Math.min(failures - 1, 5))
-            : pollMs,
+          networkRetryDelay(
+            retryError,
+            failures
+              ? Math.min(30_000, Math.max(1000, pollMs) * 2 ** Math.min(failures - 1, 5))
+              : pollMs,
+          ),
           undefined,
           { signal },
         );

package/bin/native/darwin-lifetime.json

@@ -1 +1 @@
-{"sourceSha256":"e15dc6cfd6f828dbcb829fc6fa3f5f6ef51062f45462ec6532b8c52f532c7951","binarySha256":"ae8e84b725fbb52fe285041882f4c6bd696da23ce4359c2790222982c0b778fe","architectures":["arm64","x86_64"],"minimumMacOS":"13.0"}
+{"sourceSha256":"e15dc6cfd6f828dbcb829fc6fa3f5f6ef51062f45462ec6532b8c52f532c7951","binarySha256":"d0c3a83e75eed5712242b24000eabbffcf20a470e0a20ccce2d5a5b6f97517dd","architectures":["arm64","x86_64"],"minimumMacOS":"13.0"}

package/bin/native-claude-login.mjs

@@ -0,0 +1,131 @@
+import { constants } from "node:fs";
+import { open, readFile, realpath, rename, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { beginDeviceLogin, resumeDeviceLogin } from "./device-login.mjs";
+import { createClaudeNativeBridge, inspectClaudeMcp } from "./native-claude-receiver.mjs";
+import { privateDirectory, privateRead } from "./runtime-installation.mjs";
+import { validNativePeerScope } from "./native-mcp-source.mjs";
+import { acquireSupervisorLock } from "./runtime-lock.mjs";
+import { Totem } from "./sdk/index.js";
+import { assertWindowsPrivatePath } from "./windows-private-path.mjs";
+
+const fail = code => Object.assign(new Error(code), { code });
+const missing = error => { if (error.code !== "ENOENT") throw error; };
+
+async function readKey(path) {
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)).catch(missing);
+  if (!handle) return;
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.nlink !== 1 || info.size > 128 ||
+      (process.getuid && info.uid !== process.getuid()) ||
+      (process.platform !== "win32" && (info.mode & 0o777) !== 0o600)) throw fail("NATIVE_CLAUDE_LOGIN_KEY_UNSAFE");
+    await assertWindowsPrivatePath(path);
+    return (await handle.readFile("utf8")).trim();
+  } finally { await handle.close(); }
+}
+
+async function saveKey(path, value) {
+  const previous = await readKey(path);
+  if (previous === value) return;
+  if (previous !== undefined) throw fail("NATIVE_CLAUDE_LOGIN_KEY_CHANGED");
+  const temporary = path + "." + randomUUID() + ".tmp";
+  const file = await open(temporary, "wx", 0o600);
+  try {
+    await assertWindowsPrivatePath(temporary);
+    await file.writeFile(value + "\n");
+    await file.sync();
+    await file.close();
+    if (await readKey(path) !== undefined) throw fail("NATIVE_CLAUDE_LOGIN_KEY_CHANGED");
+    // Only the device-login owner writes this receiver-specific path.
+    await rename(temporary, path);
+  } finally {
+    await file.close().catch(() => {});
+    await unlink(temporary).catch(missing);
+  }
+}
+
+/** Use Totem's existing device protocol with a receiver-specific private root.
+ * This does not import an app connector's OAuth credentials or start a generic executor.
+ */
+export async function prepareClaudeDeviceLogin(root, config, flags, options = {}) {
+  if (resolve(root) === resolve(join(homedir(), ".totem")))
+    throw fail("NATIVE_CLAUDE_LOGIN_CONFIG_INVALID");
+  const binding = config.mcp;
+  if (config.version !== 1 || !binding || JSON.stringify(config.native?.mcp) !== JSON.stringify(binding) ||
+    binding.agentId !== config.source.agentId || binding.environment !== config.source.environment ||
+    binding.serverFingerprint !== config.source.bindingFingerprint ||
+    !validNativePeerScope(config.source.peerScope) ||
+    typeof config.source.ownerChats !== "boolean" || typeof config.instructions !== "string" ||
+    !config.instructions.trim() || Buffer.byteLength(config.instructions) > 32768 ||
+    (config.source.ownerChats && (typeof config.ownerChatInstructions !== "string" ||
+      !config.ownerChatInstructions.trim() || Buffer.byteLength(config.ownerChatInstructions) > 32768)))
+    throw fail("NATIVE_CLAUDE_MCP_BINDING_CHANGED");
+  const server = await inspectClaudeMcp(binding);
+  const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url)));
+  const runtimeEntry = join(root, "runtime-packages", version, "node_modules", "totemlayer", "bin", "totem.mjs");
+  const keyPath = join(root, "totem-network.key");
+  const endpoint = server.env.TOTEM_BASE_URL;
+  if (server.command !== process.execPath || server.args.length !== 2 || server.args[0] !== runtimeEntry || server.args[1] !== "mcp" ||
+    server.env.TOTEM_CONFIG_DIR !== join(root, "mcp") || server.env.TOTEM_NETWORK_API_KEY_FILE !== keyPath ||
+    endpoint !== flags.baseUrl || server.env.TOTEM_EXPECTED_AGENT_ID !== binding.agentId ||
+    server.env.TOTEM_EXPECTED_ENVIRONMENT !== binding.environment)
+    throw fail("NATIVE_CLAUDE_LOGIN_CONFIG_INVALID");
+  const runtime = { root, directory: join(root, "device-login") };
+  await privateDirectory(root);
+  if (await realpath(root) !== resolve(root)) throw fail("NATIVE_CLAUDE_LOGIN_CONFIG_INVALID");
+  await privateDirectory(runtime.directory);
+  const unlock = await acquireSupervisorLock(join(root, "native-login-owner"));
+  try {
+    for (const other of ["pi", "hermes", "opencode", "kilo"])
+      if (await privateRead(join(root, `native-${other}-install.json`)).catch(missing) ||
+        await privateRead(join(root, `native-${other}.json`)).catch(missing))
+        throw fail("NATIVE_CLAUDE_LOGIN_ROOT_IN_USE");
+    if (await privateRead(join(config.source.directory, "paused.json")).catch(missing))
+      return { state: "paused", code: "RECEIVER_INTENTIONALLY_PAUSED", registered: false };
+    const keyPattern = binding.environment === "SANDBOX" ? /^tn_test_[A-Za-z0-9_-]{43}$/ : /^tn_live_[A-Za-z0-9_-]{43}$/;
+    const env = { TOTEM_PROVIDER: "claude", TOTEM_AGENT_ID: binding.agentId, TOTEM_BASE_URL: endpoint };
+    const bridge = (options.createClaudeBridge ?? createClaudeNativeBridge)(config.native, { env: options.env ?? process.env });
+    try { await bridge.open(); } finally { await bridge.close(); }
+    const resume = async () => (options.resumeClaudeLogin ?? resumeDeviceLogin)(runtime, env, {
+      fetch: options.fetch, configureMcp: false,
+      detectProvider: async () => "claude", // The exact native session passed preflight above.
+      async setup(_args, settings) {
+        const apiKey = settings.env.TOTEM_NETWORK_API_KEY;
+        if (!keyPattern.test(apiKey ?? "")) throw fail("NATIVE_CLAUDE_LOGIN_IDENTITY_CHANGED");
+        const identity = await new Totem({ apiKey, baseUrl: endpoint, fetch: options.fetch, maxRetries: 0 }).agent();
+        if (identity.id !== binding.agentId || identity.environment !== binding.environment)
+          throw fail("NATIVE_CLAUDE_LOGIN_IDENTITY_CHANGED");
+        await saveKey(keyPath, apiKey);
+        return 0;
+      },
+    });
+    const resumed = await resume().catch(error => {
+      if (error.code !== "DEVICE_LOGIN_EXPIRED") throw error;
+    });
+    if (resumed?.state === "setup_in_progress") throw fail("NATIVE_CLAUDE_LOGIN_IN_PROGRESS");
+    const previous = await readKey(keyPath);
+    if (previous !== undefined) {
+      if (!keyPattern.test(previous)) throw fail("NATIVE_CLAUDE_LOGIN_KEY_UNSAFE");
+      return; // The receiver will still verify the live identity before registration.
+    }
+    const request = await (options.beginClaudeLogin ?? beginDeviceLogin)(runtime, env, {
+      openBrowser: !flags.noBrowser, configureMcp: false, fetch: options.fetch,
+    });
+    const pending = { state: "incomplete", code: "NATIVE_CLAUDE_SIGN_IN_REQUIRED", complete: false,
+      registered: false, host: "claude", url: request.url, codeToCompare: request.code, expiresAt: request.expiresAt };
+    if (!flags.waitSeconds) return pending;
+    await options.write?.(pending);
+    const deadline = Math.min(Date.parse(request.expiresAt), Date.now() + flags.waitSeconds * 1000);
+    while (Date.now() < deadline && !options.signal?.aborted) {
+      await (options.sleep ?? delay)(Math.max(0, Math.min(2000, deadline - Date.now())), undefined, { signal: options.signal });
+      if (await privateRead(join(config.source.directory, "paused.json")).catch(missing))
+        return { state: "paused", code: "RECEIVER_INTENTIONALLY_PAUSED", registered: false };
+      if ((await resume())?.state === "connected") return;
+    }
+    return { ...pending, code: "NATIVE_CLAUDE_SIGN_IN_PENDING" };
+  } finally { await unlock(); }
+}