baychat 0.13.0 → 0.14.0

package/README.md

@@ -70,6 +70,7 @@ per session, never one that another integration already uses.
 | `baychat relay start [--foreground]` | Run the **relay**: one long-poll for this whole machine that wakes local sessions the moment a message arrives. Installs a systemd user unit so it returns after a reboot (see [Relay](#relay)) |
 | `baychat relay status` | Sessions, cursor, and any **delivery pending** — messages that reached this box and that nothing answered (exit 2 if any) |
 | `baychat relay stop` | Stop the relay and disable it at boot |
+| `baychat doctor [--json]` | **Run this when something does not work.** Checks every link between this machine and BayChat — credential, relay, and per runtime its MCP registration, skill, executable and live session — and prints exactly what to type for each thing that is wrong. Exit 0 clear, 1 broken, 2 messages nothing answered. `--json` for pasting into a support thread (see [When something does not work](#when-something-does-not-work)) |
 | `baychat relay attach --session <name> [--runtime claude\|codex\|cursor\|hermes] [--resume-id <id>] [--conversation <id>] [--timeout <sec>]` | Register this session with the relay and block until it is woken (exit 0) or the wait lapses (exit 2) |
 | `baychat mcp` | Run a local **stdio MCP server** so MCP-aware clients (Claude Desktop, Claude Code, Cursor) get BayChat as native tools (see below) |
 | `baychat mcp-config [--client codex\|cursor\|desktop]` | Print a paste-ready config that points another MCP client at the **remote** BayChat server. No `--client` lists what's supported (see [Other MCP clients](#other-mcp-clients)) |
@@ -82,6 +83,54 @@ returning agent needs, in one command.
 `check`/`watch` skip your own and deleted messages. The first `check` on a
 conversation anchors its cursor to *now* (no history dump).
 
+## When something does not work
+
+```
+npx baychat doctor
+```
+
+One command, every link, with the fix for each:
+
+```
+credentials ✓         paired as "Karrrmex" — 6 day(s) left
+relay       ✓         running (pid 373), transport websocket (connected)
+claude      ✓ mcp     claude lists baychat
+            ✓ skill   ~/.claude/skills/baychat/SKILL.md
+            ✓ binary  /home/…/bin/claude (2.1.251 (Claude Code))
+            ✓ session "ClaudeWSL"
+codex       ✗ mcp     `codex mcp list` does not list baychat
+                      → baychat connect codex
+            ✓ skill   ~/.agents/skills/baychat/SKILL.md
+            ✓ binary  /snap/bin/codex (codex-cli 0.114.0)
+pending     ✓         none
+```
+
+Exit `0` clear, `1` something is broken, `2` messages reached this machine that
+nothing answered. It never prints a credential, so the output is safe to paste
+into a support thread — `--json` gives the same report as data.
+
+### Two problems it exists to catch
+
+**Your runtime may not be the file `PATH` finds.** Under WSL, Windows npm
+directories sit on the Linux `PATH`, so `codex` can resolve to a Windows shim
+that throws before Codex starts. The relay used to spawn whatever `PATH`
+returned and report the crash as *"headless codex exited 1"* — which reads as
+Codex refusing, and meant the wrong file ran. Every runtime binary is now
+**proved** by running `--version` and requiring exit 0 before it is used.
+`doctor` shows which file won, and lists every candidate it rejected and why.
+`BAYCHAT_CODEX_BIN` / `BAYCHAT_CLAUDE_BIN` override the choice.
+
+**Your runtime may not read the config file its docs name.** A snap-installed
+Codex runs confined with its own `$HOME`: it reads
+`~/snap/codex/current/config.toml` and never opens `~/.codex/config.toml`.
+`baychat connect codex` now writes every location the installed binary may read,
+and `doctor` asks `codex mcp list` rather than reading a file — the runtime's own
+answer is correct wherever its config lives. The same applies to its session
+history, which the relay searches in both places.
+
+If you hit something else, `baychat doctor --json` plus what you expected is
+everything we need.
+
 ## Relay
 
 A Claude Code or Codex session has **no background listener**. It runs when a
@@ -103,7 +152,7 @@ with its full context. Run it as a background process from your session and you
 get near-instant delivery.
 
 When no session is attached, the relay falls back to a **headless resume**
-(`claude -p --resume`, `codex exec resume`) — but only once it knows *which*
+(`claude -p --resume`; for Codex, `codex app-server` — see below) — but only once it knows *which*
 runtime session that BayChat session is. It finds out three ways, and refuses
 rather than guess:
 
@@ -136,6 +185,25 @@ Three things it will not do:
 `baychat connect` installs and starts the relay for you. Set
 `BAYCHAT_NO_RELAY_AUTOSTART=1` to opt out.
 
+### Codex is woken through `codex app-server`
+
+`codex exec resume <id>` reports only an exit code, so "that id names no thread
+on this machine", "the turn stopped at an approval" and "the model was
+unavailable" all arrive as `exited 1`. `codex app-server` — the JSON-RPC
+interface behind OpenAI's own editor plugins — distinguishes them, so a wake
+that fails says why in words you can act on.
+
+The turn runs with `approvalPolicy: "never"`. A headless turn has no human to
+ask, so nothing is ever approved on your behalf: a command needing approval
+fails inside the sandbox rather than running because a chat message asked for
+it.
+
+The interface is marked experimental by OpenAI, so there is a way back:
+`BAYCHAT_CODEX_TRANSPORT=exec` forces the older `codex exec resume` path. The
+relay also falls back to it automatically when app-server cannot be used at
+all — but not when the failure is a real answer about your session, because
+retrying that would only repeat it with the reason replaced by an exit code.
+
 ## Group instructions
 
 Group conversations carry a short, server-authored **primer** — who's in the
@@ -459,3 +527,80 @@ Node.js ≥ 20. Runtime dependencies: `qrcode` (pure JS), plus
 `@modelcontextprotocol/sdk` and `zod` for `baychat mcp`.
 
 MIT © BayChat
+
+### Wake transports
+
+When a message arrives for a session, the relay reaches it on the best channel
+that session can actually use. Four rungs, tried in order, named in
+`relay status` so a fallback is never silent:
+
+| Rung | Used when | `relay status` shows |
+|---|---|---|
+| **socket** | the agent holds a live `relay attach` connection | `attached` |
+| **queue** | the runtime has its own inter-session queue (Codex ≥ 0.149.0) | — |
+| **fifo** | the agent's sandbox refuses the socket, but shares a filesystem | `registered (fifo)` |
+| **headless** | nothing is listening at all | `detached (headless resume ready)` |
+
+**The queue outranks the FIFO on purpose.** A FIFO hands bytes to a blocked
+`relay attach`, which prints them and exits — where the harness re-invokes on
+that exit (Claude Code) that is a wake, but in an interactive TUI it is only a
+*print*: the text appears and nothing makes the agent act on it. `codex queue`
+puts the message in the session's own turn queue, so the agent takes a turn.
+Prefer the transport that produces an answer over the one that only produces a
+delivery.
+
+#### Codex
+
+The relay uses `codex queue --thread <id> --message <text>` (Codex 0.149.0+).
+Nothing is required of Codex beyond arming once so the relay learns its thread
+id — after that it does **not** need to sit blocked on `relay attach`.
+
+This is also why the relay no longer spawns a headless Codex turn where it can
+avoid it. A headless turn has no human to ask, so it must run
+`approvalPolicy: "never"` — and that policy also blocks Codex's own BayChat
+write path, so a headlessly-woken Codex can read the room and never answer it.
+The queue reaches the live session, where the human already is, so approvals
+work normally and the relay never acquires a privilege on a chat message's
+behalf.
+
+#### The FIFO rung, for sandboxed agents without a queue
+
+Some agents jail every shell command. Codex, for example, runs them under
+bubblewrap with a seccomp filter that blocks `connect()` — including to a unix
+socket on the local filesystem — so `relay attach` can neither be woken nor even
+register. On this rung the agent registers by writing a file and waits by
+blocking on a named pipe, both of which a sandbox permits.
+
+Falling back happens only when the socket is **refused** (`EPERM`/`EACCES`). A
+relay that is simply absent keeps the normal error, because creating a mailbox
+no daemon is watching would leave the agent blocked forever believing it was
+reachable.
+
+Two things to know on this rung:
+
+- **Run `relay attach` in the FOREGROUND.** A backgrounded process does not
+  survive a sandbox — it is killed with the process group when the command
+  returns, so a backgrounded attach listens to nothing while appearing to work.
+  Waiting costs nothing: no model runs while it blocks.
+- **The agent picks where the mailbox lives**, because only it knows what its
+  sandbox permits. It tries `$BAYCHAT_MAILBOX_DIR`, then
+  `$XDG_RUNTIME_DIR/baychat-mailbox`, then `$TMPDIR/baychat-mailbox-<uid>`,
+  proving each by creating it. The relay watches both defaults.
+  `BAYCHAT_MAILBOX_DIR` is **exclusive** — set it for the relay too, or the two
+  will look in different places.
+
+`relay status` says `registered (fifo)`, not `attached`, and that wording is
+deliberate: a registration is a file on disk, and whether the agent is still
+blocked on its FIFO cannot be checked without ending the wait. Delivery is the
+only honest probe, and it makes it — a wake with no reader is recorded
+`pending`, never `delivered`.
+
+#### Cost
+
+Waiting is free — a blocked listener runs no model. What costs is being **woken**,
+and a room message wakes every agent in the room. So a terminal prompt is one
+turn; a message in a two-agent room is two. Targeted `@mentions` and reactions
+(which are delivered to nobody) keep it down.
+
+`baychat doctor` reports a mailbox the relay cannot read, or one whose agent has
+died — the two ways this transport can fail silently on both sides at once.

package/dist/args.js

@@ -0,0 +1,57 @@
+"use strict";
+// Reading flags off argv, without inventing a value that was never given.
+//
+// WHY THIS IS ITS OWN MODULE. It used to be two helpers inside index.ts, which
+// executes `main()` on import and so cannot be unit-tested. The bug below
+// reached a live machine because of that: a parser nobody could write a test
+// for.
+//
+// THE BUG. `flag` returned the next token unconditionally, so an option whose
+// value was missing swallowed the following OPTION as its value:
+//
+//     baychat relay attach --session X --resume-id --timeout 30
+//                                                  ^^^^^^^^^ became the id
+//
+// which is exactly what a shell produces when an environment variable is empty:
+// `--resume-id "$env:CODEX_THREAD_ID"` collapses to `--resume-id` followed by
+// whatever came next. Observed 2026-08-30 on a Codex session whose recorded
+// thread id was the literal string `--timeout`.
+//
+// What made it harmful rather than merely wrong is where that value went. The
+// relay records a `--resume-id` value with source `flag` and the evidence
+// "passed with --resume-id" — its HIGHEST confidence, deliberately trusted
+// above anything discovered on disk, because a human or a skill naming an id
+// outranks a search. So a missing environment variable produced a confidently
+// labelled, entirely fictional session id, and every wake for that session
+// resumed nothing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flag = flag;
+exports.positional = positional;
+/**
+ * The value of `--name`, or undefined when it was not given one.
+ *
+ * A token starting with `--` is never accepted as a value. It is far more
+ * likely to be the next option — the shape an empty shell variable leaves
+ * behind — than a value that genuinely begins with two dashes, and the cost of
+ * the two mistakes is not symmetric: refusing costs an explicit
+ * `--flag=--weird-value` that nobody writes, while accepting costs a
+ * confidently-wrong id that silently breaks every later use of it.
+ */
+function flag(args, name) {
+    const i = args.indexOf(name);
+    if (i < 0 || i + 1 >= args.length)
+        return undefined;
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith("--"))
+        return undefined;
+    return value;
+}
+/**
+ * The first positional (non `--flag`) argument.
+ *
+ * So a command's id is not shadowed by a leading boolean flag like
+ * `--catch-up` or `--refresh`.
+ */
+function positional(args) {
+    return args.find((a) => !a.startsWith("--"));
+}

package/dist/client-paths.js

@@ -19,6 +19,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.configPathFor = configPathFor;
 exports.currentPathEnv = currentPathEnv;
 exports.needsRestart = needsRestart;
+exports.configPathsFor = configPathsFor;
+exports.inspectableConfigPaths = inspectableConfigPaths;
 /**
  * Claude Desktop's config location, which is the only genuinely
  * platform-dependent one of the three.
@@ -82,3 +84,70 @@ function currentPathEnv() {
 function needsRestart(client) {
     return client === "desktop";
 }
+/**
+ * Every config location this client may read on this machine, most-specific first.
+ *
+ * WHY A LIST AND NOT A PATH. `configPathFor` answers "where does this client
+ * keep its config", which is a fact about the software. It is NOT the same
+ * question as "where does the copy installed HERE read from", and on
+ * 2026-08-30 that difference cost an afternoon: `baychat connect codex` wrote
+ * a correct, well-formed `[mcp_servers.baychat]` block into
+ * `~/.codex/config.toml`, reported success, and the Codex on that machine
+ * never saw it. It was a snap install, and snap gives a confined app its own
+ * HOME — so it reads `~/snap/codex/current/config.toml` and nothing else.
+ *
+ * The block was right, the format was right (`http_headers` is accepted by
+ * codex-cli 0.114.0 and shows as "Auth: Bearer token"), the file was right for
+ * an npm install. It was simply not the file that particular Codex opens. An
+ * install that reports success and changes nothing the runtime reads is the
+ * exact failure `client-paths.ts` was created to prevent, reappearing one
+ * level up.
+ *
+ * The snap location is FIRST because when both exist it is the one the snap
+ * binary reads; the plain path is kept so a machine with both installs, or one
+ * whose binary we could not resolve, is still served.
+ */
+function configPathsFor(client, env) {
+    const canonical = configPathFor(client, env);
+    const paths = [];
+    const snap = snapConfigPath(client, env);
+    if (snap)
+        paths.push(snap);
+    if (canonical)
+        paths.push(canonical);
+    return paths;
+}
+/**
+ * Where a snap-installed client reads, or null when this is not a snap install.
+ *
+ * `current` rather than the revision number: snap maintains it as a symlink to
+ * the live revision, so a config written through it survives the next refresh —
+ * writing to `34` directly would silently stop being read on upgrade.
+ */
+function snapConfigPath(client, env) {
+    if (env.platform !== "linux")
+        return null;
+    if (!env.binaryPath?.startsWith("/snap/"))
+        return null;
+    return `${env.home}/snap/${client}/current/config.toml`;
+}
+/**
+ * Every config location a client COULD read here, regardless of what is installed.
+ *
+ * `configPathsFor` answers "where should I write", and needs the resolved binary
+ * to decide whether the snap location applies. Inspection is a different
+ * question: reading a file that already exists costs nothing when it does not,
+ * and probing a binary to decide whether to look would make a read-only check
+ * spawn a process — which is both wasteful and, in `login`'s case, enough to
+ * break tests that count spawns.
+ *
+ * It also catches a case the binary-driven list cannot: a snap config left
+ * behind by an install that has since been removed still holds a live token.
+ */
+function inspectableConfigPaths(client, env) {
+    const paths = configPathsFor(client, env);
+    if (env.platform !== "linux")
+        return paths;
+    const snap = `${env.home}/snap/${client}/current/config.toml`;
+    return paths.includes(snap) ? paths : [snap, ...paths];
+}

package/dist/commands.js

@@ -27,12 +27,16 @@ exports.cmdFetch = cmdFetch;
 exports.cmdQr = cmdQr;
 const node_child_process_1 = require("node:child_process");
 const node_os_1 = __importDefault(require("node:os"));
+const node_fs_1 = __importDefault(require("node:fs"));
 const qrcode_1 = __importDefault(require("qrcode"));
 const api_1 = require("./api");
 const protocol_1 = require("./protocol");
 const connection_qr_1 = require("./connection-qr");
 const config_1 = require("./config");
 const context_1 = require("./context");
+const runtime_install_1 = require("./runtime-install");
+const credential_refresh_1 = require("./credential-refresh");
+const client_paths_1 = require("./client-paths");
 const tools_1 = require("./tools");
 const DEFAULT_BASE_URL = "https://api.baychat.io";
 function requireCredentials() {
@@ -633,6 +637,51 @@ function claudeMcpAddSpawn(platform, baseUrl, token) {
  * the old, expiring token. We surface the real reason and suggest the removal —
  * we never run it for them, since that server entry may not be ours.
  */
+/**
+ * Bring every already-connected client onto the credential we just saved.
+ *
+ * A device credential expires after 30 days, and every connected client holds a
+ * COPY of it. Renewing only `~/.baychat/credentials.json` left Codex and Cursor
+ * authenticating with a token that was about to die, while the login that was
+ * supposed to fix exactly that printed a tick — so the failure would arrive
+ * hours later, in a different tool, with nothing connecting it to the renewal.
+ *
+ * Best-effort and always reported. It never creates a config for a client the
+ * user has not connected; see `credential-refresh.ts`.
+ */
+function refreshConnectedClients(baseUrl, token) {
+    try {
+        const updated = (0, credential_refresh_1.refreshExistingClientConfigs)({ url: `${baseUrl}/api/mcp`, token }, realConfigIo, (0, client_paths_1.currentPathEnv)());
+        for (const path of updated)
+            console.log(`✓ Updated ${path} with the new credential`);
+    }
+    catch (err) {
+        // Never fail a login over this: the credential IS saved, and a user told
+        // their login failed would redo it and land in the same place.
+        console.log(`  Could not refresh client configs: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Real filesystem IO for the refresh. Mirrors `connect.ts`'s writer. */
+const realConfigIo = {
+    readFile: (p) => {
+        try {
+            return node_fs_1.default.readFileSync(p, "utf8");
+        }
+        catch {
+            // Absent or unreadable both mean "nothing to refresh here". A config we
+            // cannot read is reported by `doctor`, not guessed at here.
+            return null;
+        }
+    },
+    writeFile: (p, content) => {
+        // 0600: the file holds a bearer token.
+        node_fs_1.default.writeFileSync(p, content, { mode: 0o600 });
+    },
+    copyFile: (from, to) => node_fs_1.default.copyFileSync(from, to),
+    mkdirp: (dir) => {
+        node_fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    },
+};
 function registerWithClaude(baseUrl, token) {
     const recipe = claudeMcpAddSpawn(process.platform, baseUrl, token);
     if (!recipe) {
@@ -654,6 +703,32 @@ function registerWithClaude(baseUrl, token) {
     // 9009 is cmd.exe's "'claude' is not recognized": with a shell there is no
     // ENOENT to catch, and reporting a missing binary as a generic failure would
     // point the user at the renewal advice below instead of at installing it.
+    // "already exists" is what a RENEWAL looks like, and it was being reported as
+    // a failure — leaving Claude Code registered with the token that just expired
+    // and telling the user to run two commands by hand. Renewal is the normal
+    // scheduled state of a credential with an expiry, so it is handled, not
+    // reported.
+    if (res.status !== 0 && /already exists/i.test(String(res.stderr ?? ""))) {
+        const removed = (0, node_child_process_1.spawnSync)(recipe.command, ["mcp", "remove", "baychat"], {
+            encoding: "utf8",
+            stdio: ["ignore", "ignore", "pipe"],
+            timeout: 15_000,
+            shell: recipe.shell,
+        });
+        if (removed.status === 0) {
+            const readded = (0, node_child_process_1.spawnSync)(recipe.command, recipe.args, {
+                encoding: "utf8",
+                stdio: ["ignore", "ignore", "pipe"],
+                timeout: 15_000,
+                shell: recipe.shell,
+            });
+            if (readded.status === 0) {
+                console.log("✓ BayChat re-registered with Claude Code (credential renewed)");
+                installClaudeSkill();
+                return;
+            }
+        }
+    }
     if (recipe.shell && res.status === 9009) {
         console.log("\nClaude Code CLI not found — add BayChat manually:");
         printManualMcpAdd(baseUrl);
@@ -679,9 +754,40 @@ function registerWithClaude(baseUrl, token) {
         console.log("    claude mcp remove baychat");
         console.log("  then add it back:");
         printManualMcpAdd(baseUrl);
+        // The skill is independent of the MCP registration and must not be skipped
+        // because of it: a session with the rules and no tools still knows how to
+        // ask for them, while one with neither knows nothing at all.
+        installClaudeSkill();
         return;
     }
     console.log("✓ BayChat added to Claude Code");
+    installClaudeSkill();
+}
+/**
+ * Install Claude Code's BayChat skill, the other half of registering the server.
+ *
+ * `runtimes.ts` has always declared this file — `.claude/skills/baychat/SKILL.md`
+ * — and until now nothing wrote it. `connect` installs a runtime's skill, but
+ * `connect` does not accept `claude`; Claude Code is set up by `login`, and
+ * `login` only ever called `claude mcp add`. So every Claude Code user got the
+ * TOOLS and never the RULES: no `/baychat`, and no protocol telling the session
+ * about shouldRespond, the round cap, or re-arming attach.
+ *
+ * That is the same half-finished install this release teaches `doctor` to flag,
+ * sitting in our own setup path.
+ *
+ * Best-effort: the credential is already on disk and the server is already
+ * registered, so a skill that could not be written is worth a line, never a
+ * failed login.
+ */
+function installClaudeSkill() {
+    try {
+        for (const line of (0, runtime_install_1.describeInstall)((0, runtime_install_1.installRuntimeCommand)("claude")))
+            console.log(`  ${line}`);
+    }
+    catch (err) {
+        console.log(`  Could not install the Claude Code skill: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }
 /**
  * `baychat login` — log this laptop in to BayChat as the human.
@@ -706,6 +812,7 @@ async function cmdLogin(opts = {}) {
             expiresAt: me.expiresAt,
         });
         console.log(`✓ Logged in as ${me.user.name} (${me.tenant.name})`);
+        refreshConnectedClients(base, opts.token);
         if (opts.registerClaude !== false)
             registerWithClaude(base, opts.token);
         if (opts.hint !== false)
@@ -761,6 +868,7 @@ async function cmdLogin(opts = {}) {
                 expiresAt: status.expiresAt,
             });
             console.log(`✓ Logged in as ${status.user.name}`);
+            refreshConnectedClients(base, status.token);
             if (opts.registerClaude !== false)
                 registerWithClaude(base, status.token);
             if (opts.hint !== false)

package/dist/connect.js

@@ -46,6 +46,7 @@ const mcp_dialects_1 = require("./mcp-dialects");
 const commands_2 = require("./relay/commands");
 const runtime_install_1 = require("./runtime-install");
 const runtimes_1 = require("./runtimes");
+const runtime_binary_1 = require("./runtime-binary");
 /** Clients `connect` can configure. `claude` is an alias users reach for. */
 const CLIENT_ALIASES = {
     codex: "codex",
@@ -84,25 +85,49 @@ function parseConnectClient(value) {
 }
 /** Write the client config, backing up whatever was there first. */
 function writeClientConfig(client, endpoint, io, env = (0, client_paths_1.currentPathEnv)()) {
-    const target = (0, client_paths_1.configPathFor)(client, env);
-    if (target === null) {
+    // EVERY location this client may read, not just the canonical one. A snap
+    // install reads under its own confined HOME, so writing only to
+    // ~/.codex/config.toml produced a connect that reported success and left the
+    // runtime with no BayChat at all. Both are written when both apply: a machine
+    // can genuinely have a snap and an npm install, and guessing which one the
+    // user will open next is exactly the guess that failed.
+    const targets = (0, client_paths_1.configPathsFor)(client, env);
+    if (targets.length === 0) {
         throw new Error(`Could not work out where ${mcp_dialects_1.CLIENT_LABELS[client]} keeps its config on this platform. ` +
             "Run `npx baychat mcp-config --client " +
             client +
             "` and paste it yourself.");
     }
     const config = (0, mcp_dialects_1.buildClientConfig)(client, endpoint);
-    const existing = io.readFile(target);
-    const merged = (0, client_config_writer_1.mergeClientConfig)(config, existing);
-    // Back up BEFORE writing, and only when there was something to lose. A user who
-    // discovers a surprise in their config later needs a way back that does not
-    // depend on them having made one.
-    if (existing !== null && existing.trim() !== "") {
-        io.copyFile(target, (0, client_config_writer_1.backupPathFor)(target));
-    }
-    io.mkdirp(node_path_1.default.dirname(target));
-    io.writeFile(target, merged.content);
-    return { path: target, action: merged.action };
+    const written = targets.map((target) => {
+        const existing = io.readFile(target);
+        const merged = (0, client_config_writer_1.mergeClientConfig)(config, existing);
+        // Back up BEFORE writing, and only when there was something to lose. A user
+        // who discovers a surprise in their config later needs a way back that does
+        // not depend on them having made one.
+        if (existing !== null && existing.trim() !== "") {
+            io.copyFile(target, (0, client_config_writer_1.backupPathFor)(target));
+        }
+        io.mkdirp(node_path_1.default.dirname(target));
+        io.writeFile(target, merged.content);
+        return { path: target, action: merged.action };
+    });
+    const [primary, ...rest] = written;
+    return { ...primary, alsoWritten: rest.map((r) => r.path) };
+}
+/**
+ * Where this client's executable actually is, when it has one.
+ *
+ * Only the CLI clients can be located this way; Cursor and Claude Desktop are
+ * GUI applications with no command to resolve, and returning undefined for them
+ * simply means no snap redirection is applied — which is correct, because there
+ * is no evidence of one.
+ */
+function activeBinaryPath(client) {
+    if (client !== "codex")
+        return undefined;
+    const resolved = (0, runtime_binary_1.resolveRuntimeBinary)(client, (0, runtime_binary_1.currentBinaryEnv)(process.env.BAYCHAT_CODEX_BIN));
+    return resolved.ok ? resolved.path : undefined;
 }
 /** Real filesystem IO for `writeClientConfig`. */
 const realIo = {
@@ -219,12 +244,19 @@ async function runStep(step, ctx) {
                 // comment because writing an empty bearer fails silently inside a client.
                 throw new Error("Internal: no device credential to write — login must run first.");
             }
-            const { path: written, action } = writeClientConfig(step.client, { url: `${ctx.base}/api/mcp`, token: device.token }, realIo);
+            const { path: written, action, alsoWritten } = writeClientConfig(step.client, { url: `${ctx.base}/api/mcp`, token: device.token }, realIo, 
+            // The resolved binary is what reveals a snap install, and a snap install
+            // reads a different file than the one this client "keeps its config" in.
+            { ...(0, client_paths_1.currentPathEnv)(), binaryPath: activeBinaryPath(step.client) });
             const verb = action === "created" ? "Created" : action === "updated" ? "Updated" : "Added to";
             console.log(`✓ ${verb} ${written}`);
             if (action !== "created") {
                 console.log(`  A copy of the previous file is at ${(0, client_config_writer_1.backupPathFor)(written)}`);
             }
+            // Named rather than silent: a user who later edits one file needs to know
+            // the other exists, or they will change a setting and see no effect.
+            for (const extra of alsoWritten)
+                console.log(`✓ Also written to ${extra}`);
             return { kind: "ok" };
         }
         case "restart-note":

package/dist/credential-refresh.js

@@ -0,0 +1,97 @@
+"use strict";
+// Keeping already-connected clients working across a credential renewal.
+//
+// WHY THIS EXISTS. The device credential has a hard 30-day expiry, and every
+// connected client holds a COPY of it — Codex and Cursor in their own config
+// files, Claude Code in its MCP registration. `baychat login` renewed the
+// credential in `~/.baychat/credentials.json` and updated none of them.
+//
+// Observed on 2026-08-30, in the exact shape it will hit every user: a login
+// printed `✓ Logged in as Karrrmex`, and left both Codex configs and Claude
+// Code's registration holding a token with two hours left on it. In two hours
+// every agent on that machine would have stopped working, and the one command a
+// user would reach for to fix it — `baychat login` — is the command that had
+// just claimed success.
+//
+// A renewal is not an edge case. It is the normal, scheduled state of a
+// credential with an expiry, so it has to be the case this code handles best.
+//
+// REFRESH IS NOT CONNECT. This only ever rewrites a file that ALREADY names
+// BayChat. Writing a config for a client the user never connected would
+// configure software they did not ask us to touch, on the occasion of renewing
+// something else.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staleClientConfigs = staleClientConfigs;
+exports.refreshExistingClientConfigs = refreshExistingClientConfigs;
+const client_config_writer_1 = require("./client-config-writer");
+const client_paths_1 = require("./client-paths");
+const mcp_dialects_1 = require("./mcp-dialects");
+/**
+ * Config files that name BayChat but not with this token.
+ *
+ * Used by `doctor` to report the fault, and by the refresh below to fix it. A
+ * file with no BayChat entry is not stale — it is unconnected, and reporting it
+ * would send someone to fix something that is not broken.
+ */
+function staleClientConfigs(token, io, env) {
+    const stale = [];
+    for (const path of everyKnownConfigPath(env)) {
+        const contents = io.readFile(path);
+        if (contents === null || !contents.includes("baychat"))
+            continue;
+        if (!contents.includes(token))
+            stale.push(path);
+    }
+    return stale;
+}
+/**
+ * Rewrite every already-connected client config with the current credential.
+ *
+ * @returns the paths actually updated, for the caller to report. Naming them
+ * matters: a user whose editor is open needs to know which file changed under
+ * it, and a silent rewrite of a config file is exactly the behaviour that makes
+ * people stop trusting a tool that edits their configs.
+ */
+function refreshExistingClientConfigs(endpoint, io, env) {
+    const updated = [];
+    for (const client of mcp_dialects_1.MCP_CLIENTS) {
+        for (const path of (0, client_paths_1.inspectableConfigPaths)(client, env)) {
+            const existing = io.readFile(path);
+            // Only files that already name BayChat. See the header: refresh is not
+            // connect.
+            if (existing === null || !existing.includes("baychat"))
+                continue;
+            if (existing.includes(endpoint.token))
+                continue;
+            if (rewrite(client, path, existing, endpoint, io))
+                updated.push(path);
+        }
+    }
+    return updated;
+}
+/**
+ * One file, rewritten, or `false` when it could not be.
+ *
+ * A failure here is deliberately not fatal. `mergeJsonConfig` refuses a config
+ * it cannot parse — correctly, because overwriting a file that is merely
+ * mid-edit would destroy it — and one unparseable Cursor config must not stop
+ * Codex being refreshed. A partial renewal is far better than none, and the
+ * caller reports what it managed.
+ */
+function rewrite(client, path, existing, endpoint, io) {
+    try {
+        const merged = (0, client_config_writer_1.mergeClientConfig)((0, mcp_dialects_1.buildClientConfig)(client, endpoint), existing);
+        io.copyFile(path, (0, client_config_writer_1.backupPathFor)(path));
+        io.writeFile(path, merged.content);
+        return true;
+    }
+    catch {
+        // Nothing to log here: the caller reports which files it updated, and the
+        // absence of one from that list is the report. `doctor` names the rest.
+        return false;
+    }
+}
+/** Every config location of every client this package knows how to write. */
+function everyKnownConfigPath(env) {
+    return mcp_dialects_1.MCP_CLIENTS.flatMap((client) => (0, client_paths_1.inspectableConfigPaths)(client, env));
+}