baychat 0.8.1 → 0.9.0

package/README.md

@@ -66,6 +66,10 @@ per session, never one that another integration already uses.
 | `baychat search <query> [--limit <n>]` | Search the web through BayChat — ranked results with title, URL, and snippet (see [Tools](#tools)) |
 | `baychat fetch <url> [--max-chars <n>]` | Fetch one public `http(s)` page through BayChat and print its readable text (see [Tools](#tools)) |
 | `baychat watch <conv> [--interval <sec>] [--timeout <sec>]` | Block until new messages arrive (exit 0) or timeout (exit 2) |
+| `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 relay attach --session <name> [--runtime claude\|codex\|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)) |
 
@@ -77,6 +81,45 @@ 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).
 
+## Relay
+
+A Claude Code or Codex session has **no background listener**. It runs when a
+human prompts it, so a message sent from a phone sits unread until someone
+happens to type in the terminal — even though the server delivered it instantly
+and flagged it correctly. WebSockets do not fix this: a socket still needs a
+process holding it, and that process still has to wake the session.
+
+`baychat relay` is that process.
+
+```
+baychat relay start                    # systemd user unit, survives reboot
+baychat relay attach --session my-sess --conversation <conv>
+```
+
+`attach` blocks until a message lands, prints it, and **exits 0**. That exit is
+the wake — a harness that launched it in the background re-invokes the session
+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`) if it has a resume id for that
+session. Pass `--resume-id` on attach so it can.
+
+Three things it will not do:
+
+- **It never decides who replies.** The wake carries the messages and tells the
+  session to re-check `shouldRespond` itself. Reply policy stays server-side.
+- **It never runs two turns for one session at once.** An interactive wake and a
+  headless resume answering the same room as the same identity is the failure
+  mode; a per-session lock makes it impossible. Messages arriving mid-turn
+  coalesce into one follow-up batch.
+- **It never claims an answer it cannot evidence.** No resume id, a self-hosted
+  runtime with no local resume, or a headless turn that exited non-zero — all
+  are recorded as `DELIVERY PENDING` and shown by `relay status`, which exits 2.
+
+`baychat connect` installs and starts the relay for you. Set
+`BAYCHAT_NO_RELAY_AUTOSTART=1` to opt out.
+
 ## Group instructions
 
 Group conversations carry a short, server-authored **primer** — who's in the

package/dist/client-config-writer.js

@@ -0,0 +1,149 @@
+"use strict";
+// Writing BayChat into a client's MCP config file, in place, without breaking it.
+//
+// `baychat mcp-config` PRINTS a config and asks the user to paste it. That is not
+// an install: it demands the user know what TOML is, where their client keeps its
+// config, and which half of the printed text is the part to paste. `baychat
+// connect` writes the file itself, and this module is the part that touches it.
+//
+// THE ONE RULE: NEVER DESTROY WHAT IS ALREADY THERE. These files hold the user's
+// other MCP servers, their editor settings, and in Codex's case a lot more
+// besides. A naive write costs someone their whole configuration, and they will
+// discover it later, in another tool, with no idea what did it. Everything below
+// exists to make that impossible:
+//
+//   - The merge is a SPLICE, not a rewrite: exactly the `baychat` server entry is
+//     replaced, byte-for-byte around it.
+//   - It is IDEMPOTENT: running connect twice replaces the block, never appends a
+//     second one (a duplicate `[mcp_servers.baychat]` makes the file invalid TOML,
+//     so an append-only implementation would break the client on the second run).
+//   - JSON is parsed and re-serialised; a file that does not parse is REFUSED
+//     rather than overwritten, because the only safe response to "I do not
+//     understand this file" is to keep your hands off it.
+//   - Callers back up first (`backupPathFor`), so there is always a way back.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeTomlConfig = mergeTomlConfig;
+exports.mergeJsonConfig = mergeJsonConfig;
+exports.mergeClientConfig = mergeClientConfig;
+exports.backupPathFor = backupPathFor;
+exports.expandHome = expandHome;
+/**
+ * The TOML table header this owns, and the only span it may replace.
+ *
+ * Sub-tables (`[mcp_servers.baychat.env]`) belong to the same server and are
+ * replaced with it; a header for any OTHER server ends the span.
+ */
+const TOML_TABLE = "mcp_servers.baychat";
+/** Matches a top-level TOML table header line, capturing its dotted key. */
+const TOML_HEADER = /^\s*\[\s*([^\]]+?)\s*\]\s*$/;
+/**
+ * Splice the BayChat server block into an existing TOML file.
+ *
+ * @param existing current file content, or null when the file does not exist yet
+ * @param body the `[mcp_servers.baychat]` block to install
+ */
+function mergeTomlConfig(existing, body) {
+    const block = body.trimEnd();
+    if (existing === null || existing.trim() === "") {
+        return { content: `${block}\n`, action: "created" };
+    }
+    const lines = existing.split("\n");
+    let start = -1;
+    let end = lines.length;
+    for (let i = 0; i < lines.length; i += 1) {
+        const match = TOML_HEADER.exec(lines[i] ?? "");
+        if (!match)
+            continue;
+        const key = (match[1] ?? "").replace(/\s+/g, "");
+        const ours = key === TOML_TABLE || key.startsWith(`${TOML_TABLE}.`);
+        if (start === -1) {
+            if (ours)
+                start = i;
+            continue;
+        }
+        // Inside our span: a header that is not ours closes it.
+        if (!ours) {
+            end = i;
+            break;
+        }
+    }
+    if (start === -1) {
+        // Not present — append, keeping exactly one blank line as a separator so the
+        // result is readable whether or not the file ended with a newline.
+        const prefix = existing.endsWith("\n") ? existing.replace(/\n+$/, "\n") : `${existing}\n`;
+        return { content: `${prefix}\n${block}\n`, action: "appended" };
+    }
+    const before = lines.slice(0, start);
+    const after = lines.slice(end);
+    const merged = [...before, ...block.split("\n"), ...after].join("\n");
+    return { content: merged.endsWith("\n") ? merged : `${merged}\n`, action: "updated" };
+}
+/**
+ * Merge the BayChat server entry into a JSON MCP config (Cursor, Claude Desktop).
+ *
+ * @throws when the existing file is present but not valid JSON, or is not a JSON
+ * object. Overwriting in that case would silently discard whatever the user had —
+ * including a file that is merely mid-edit. Refusing lets the CLI say which file
+ * to look at.
+ */
+function mergeJsonConfig(existing, body) {
+    // `body` is ours, produced by buildClientConfig — a parse failure here is a bug
+    // in this package, not user input, so it is allowed to throw plainly.
+    const incoming = JSON.parse(body);
+    const entry = incoming.mcpServers?.baychat;
+    if (entry === undefined) {
+        throw new Error("Generated config has no mcpServers.baychat entry — this is a bug.");
+    }
+    if (existing === null || existing.trim() === "") {
+        return { content: `${JSON.stringify(incoming, null, 2)}\n`, action: "created" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(existing);
+    }
+    catch {
+        throw new Error("Your existing config is not valid JSON, so it was left untouched. Fix or move it, then run this again.");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Your existing config is not a JSON object, so it was left untouched. Fix or move it, then run this again.");
+    }
+    const current = parsed;
+    const servers = { ...(current.mcpServers ?? {}) };
+    const had = Object.prototype.hasOwnProperty.call(servers, "baychat");
+    servers.baychat = entry;
+    const merged = { ...current, mcpServers: servers };
+    return {
+        content: `${JSON.stringify(merged, null, 2)}\n`,
+        action: had ? "updated" : "appended",
+    };
+}
+/** Merge by dialect. Keeps the format decision in one place. */
+function mergeClientConfig(config, existing) {
+    return config.format === "toml"
+        ? mergeTomlConfig(existing, config.body)
+        : mergeJsonConfig(existing, config.body);
+}
+/**
+ * Where to copy a file before rewriting it.
+ *
+ * Deliberately a FIXED name rather than a timestamp: a user who runs connect ten
+ * times should end up with one backup they can find, not ten they have to date.
+ * The pre-edit state is the only one worth keeping.
+ */
+function backupPathFor(path) {
+    return `${path}.baychat-backup`;
+}
+/**
+ * Expand a leading `~` to the given home directory.
+ *
+ * The dialect table stores display paths (`~/.codex/config.toml`) because that is
+ * what a human reads; writing needs a real path. Only a LEADING `~/` is expanded —
+ * a tilde anywhere else is a legitimate filename character.
+ */
+function expandHome(path, home) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/"))
+        return `${home}/${path.slice(2)}`;
+    return path;
+}

package/dist/client-paths.js

@@ -0,0 +1,84 @@
+"use strict";
+// Where each MCP client actually keeps its config on disk.
+//
+// WHY THIS IS NOT `CLIENT_FILES`. That table in `mcp-dialects.ts` holds strings
+// written for a human to read — `"~/.cursor/mcp.json (or a project
+// .cursor/mcp.json)"`, `"claude_desktop_config.json (Settings → Developer → Edit
+// Config)"`. Perfect for a printed instruction, useless for `writeFileSync`: one
+// carries a parenthetical, the other is not a path at all. Treating them as paths
+// would have created a file literally named `claude_desktop_config.json (Settings
+// → Developer → Edit Config)` in the working directory, and the user's real
+// config would never have been touched — an install that reports success and
+// changes nothing.
+//
+// So writing gets its own table, resolved per platform, and returns null when we
+// genuinely do not know. Guessing a path is worse than declining: a wrong guess
+// writes a file no client reads, and the user is left debugging a config that
+// looks correct.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configPathFor = configPathFor;
+exports.currentPathEnv = currentPathEnv;
+exports.needsRestart = needsRestart;
+/**
+ * Claude Desktop's config location, which is the only genuinely
+ * platform-dependent one of the three.
+ *
+ * Returns null on an unrecognised platform, and on Windows without `APPDATA` —
+ * there is no sound fallback for either, and inventing one writes a file nothing
+ * will read.
+ */
+function claudeDesktopPath(env) {
+    if (env.platform === "darwin") {
+        return `${env.home}/Library/Application Support/Claude/claude_desktop_config.json`;
+    }
+    if (env.platform === "win32") {
+        if (!env.appData)
+            return null;
+        return `${env.appData}\\Claude\\claude_desktop_config.json`;
+    }
+    if (env.platform === "linux") {
+        const base = env.xdgConfigHome && env.xdgConfigHome.trim() !== ""
+            ? env.xdgConfigHome
+            : `${env.home}/.config`;
+        return `${base}/Claude/claude_desktop_config.json`;
+    }
+    return null;
+}
+/**
+ * The absolute config path to write for a client, or null when it cannot be
+ * determined on this platform.
+ *
+ * Codex and Cursor keep theirs in the home directory on every platform. Cursor
+ * also supports a per-project `.cursor/mcp.json`; the global file is chosen
+ * deliberately, because `connect` is establishing this machine's identity, not
+ * one repository's.
+ */
+function configPathFor(client, env) {
+    switch (client) {
+        case "codex":
+            return `${env.home}/.codex/config.toml`;
+        case "cursor":
+            return `${env.home}/.cursor/mcp.json`;
+        case "desktop":
+            return claudeDesktopPath(env);
+    }
+}
+/** Read the path environment from the current process. */
+function currentPathEnv() {
+    return {
+        home: process.env.HOME || process.env.USERPROFILE || "",
+        platform: process.platform,
+        appData: process.env.APPDATA,
+        xdgConfigHome: process.env.XDG_CONFIG_HOME,
+    };
+}
+/**
+ * Whether this client needs a restart to pick up a changed config.
+ *
+ * Only stated where it is true, so the instruction carries weight. A CLI that
+ * tells everyone to restart trains them to ignore it — and Codex and Cursor read
+ * their MCP config per session, so most users need nothing.
+ */
+function needsRestart(client) {
+    return client === "desktop";
+}

package/dist/commands.js

@@ -651,8 +651,10 @@ async function cmdLogin(opts = {}) {
             expiresAt: me.expiresAt,
         });
         console.log(`✓ Logged in as ${me.user.name} (${me.tenant.name})`);
-        registerWithClaude(base, opts.token);
-        console.log("\n  Run /baychat <name> in any session.");
+        if (opts.registerClaude !== false)
+            registerWithClaude(base, opts.token);
+        if (opts.hint !== false)
+            console.log("\n  Run /baychat <name> in any session.");
         return true;
     }
     // The hostname labels this laptop in the approve UI; the server caps the field
@@ -704,8 +706,10 @@ async function cmdLogin(opts = {}) {
                 expiresAt: status.expiresAt,
             });
             console.log(`✓ Logged in as ${status.user.name}`);
-            registerWithClaude(base, status.token);
-            console.log("\n  Run /baychat <name> in any session.");
+            if (opts.registerClaude !== false)
+                registerWithClaude(base, status.token);
+            if (opts.hint !== false)
+                console.log("\n  Run /baychat <name> in any session.");
             return true;
         }
     }

package/dist/connect-plan.js

@@ -0,0 +1,122 @@
+"use strict";
+// What `baychat connect <client>` should DO, decided before anything is done.
+//
+// ONE LOGIN PER LAPTOP, THEN NOTHING. `connect` shows the device-link QR once,
+// writes the DEVICE credential into the client's MCP config, and stops. Every
+// coding session afterwards joins a room by itself:
+//
+//     /baychat <name>      -> join_session({ session: "<name>" })
+//
+// which mints (or reattaches) that session's own agent and puts it in a chat.
+// Same name, same agent, same history.
+//
+// WHY THE DEVICE CREDENTIAL AND NOT AN AGENT TOKEN. An agent token pins the
+// client to ONE pre-made agent in ONE room, so every new session would need
+// another trip to the phone for another code — a recurring chore dressed up as an
+// install. The device credential represents the PERSON, and the session tools it
+// unlocks let each session create its own identity on demand. That is the whole
+// difference between setting something up once and setting it up forever.
+//
+// Agent tokens and pairing codes are not gone; they are the path for EXTERNAL and
+// LEGACY runtimes (a self-hosted gateway, anything driving the Agent API itself),
+// which have no MCP client to configure and no session concept. `baychat pair`
+// still serves them.
+//
+// The two halves people conflate remain distinct, and this module keeps them so:
+//
+//   1. CONNECT THIS LAPTOP - a device credential. Authorising a machine to act as
+//      you, the way WhatsApp Web authorises a browser. Creates NO agent and puts
+//      nobody in a room. Lives under Account -> Devices in the app.
+//   2. JOIN A SESSION - `/baychat <name>` inside the client, per session. This is
+//      what actually ends with something able to speak, and it needs no QR, no
+//      code, and no pre-created agent.
+//
+// Steps are computed from observed state here, as data, and the executor only
+// carries them out - so the sequencing is testable without a network, a terminal,
+// or a phone.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceStateFrom = deviceStateFrom;
+exports.planConnect = planConnect;
+exports.planNeedsPhoneApproval = planNeedsPhoneApproval;
+exports.expiryNudge = expiryNudge;
+exports.describeConnection = describeConnection;
+const THREE_DAYS_MS = 3 * 86_400_000;
+/** Read the on-disk credential into a state, without judging what to do about it. */
+function deviceStateFrom(device, now = Date.now()) {
+    if (!device)
+        return { kind: "absent" };
+    const expires = new Date(device.expiresAt).getTime();
+    // An unparseable expiry is treated as expired. Treating it as live would send
+    // the user into a flow that fails at the first authenticated call, with an
+    // error that points at the server rather than at their credential.
+    if (Number.isNaN(expires) || expires <= now) {
+        return { kind: "expired", userName: device.user.name };
+    }
+    return { kind: "live", userName: device.user.name, msLeft: expires - now };
+}
+/**
+ * The ordered steps for one `connect` run.
+ *
+ * `needsRestart` is injected rather than imported so the sequencing can be tested
+ * against both answers without reaching for a specific client.
+ */
+function planConnect(input) {
+    const { client, device, needsRestart } = input;
+    const steps = [];
+    if (device.kind === "absent" || device.kind === "expired") {
+        steps.push({ kind: "device-login", reason: device.kind });
+    }
+    else {
+        steps.push({ kind: "device-ok", userName: device.userName, msLeft: device.msLeft });
+    }
+    // No code, no room, no agent. The config carries the device credential, and the
+    // session tools it unlocks let `/baychat <name>` do the rest, per session.
+    steps.push({ kind: "write-config", client });
+    if (needsRestart)
+        steps.push({ kind: "restart-note", client });
+    return steps;
+}
+/** Whether the plan will ask the user to approve a QR on their phone. */
+function planNeedsPhoneApproval(steps) {
+    return steps.some((s) => s.kind === "device-login");
+}
+/** The expiry nudge for a live credential, or null when it is not due yet. */
+function expiryNudge(device) {
+    if (device.kind !== "live")
+        return null;
+    if (device.msLeft >= THREE_DAYS_MS)
+        return null;
+    const hours = Math.max(1, Math.round(device.msLeft / 3_600_000));
+    return `Your laptop login expires in about ${hours}h — run \`npx baychat login\` to renew.`;
+}
+/**
+ * Describe the finished state.
+ *
+ * The note is the one thing a user cannot infer from a successful install: the
+ * command connected a LAPTOP, and nothing is in a room yet. Without that line the
+ * obvious reading of "✓ done" is that an agent is now listening somewhere, and the
+ * user waits for a reply that was never going to come.
+ *
+ * Revocation is coherent under this design, which is a reason to prefer it:
+ * revoking the laptop under Account → Devices cuts every session it opened,
+ * because they all speak through its credential.
+ */
+function describeConnection(input) {
+    const { device, agentName, groupTitle } = input;
+    const laptop = device.kind === "live"
+        ? `connected as ${device.userName} (${Math.floor(device.msLeft / 86_400_000)}d left)`
+        : device.kind === "expired"
+            ? `login expired — run \`npx baychat connect\` again`
+            : "not connected";
+    const agent = agentName === null
+        ? "none yet — run /baychat <name> in a session"
+        : groupTitle
+            ? `${agentName} in ${groupTitle}`
+            : agentName;
+    return {
+        laptop,
+        agent,
+        note: "Each session makes its own agent: run /baychat <name> inside the client. " +
+            "The same name always reattaches to the same agent and history.",
+    };
+}

package/dist/connect.js

@@ -0,0 +1,219 @@
+"use strict";
+// `baychat connect <client>` — one command, once per laptop.
+//
+// WHAT IT DOES. Shows the device-link QR, waits for the phone to approve it, and
+// writes the DEVICE credential into the client's MCP config. Then it stops.
+//
+// WHAT IT DELIBERATELY DOES NOT DO. Ask for a code. Ask which room. Create an
+// agent. All three used to be here, and all three were the same mistake: they
+// bound the client to one pre-made agent in one conversation, so every new
+// coding session needed another trip to the phone. Setup you repeat is not setup.
+//
+// Instead, each session names itself, inside the client:
+//
+//     /baychat <name>     ->  join_session({ session: "<name>" })
+//
+// which mints or reattaches that session's own agent and puts it in a chat. The
+// session tools that make this possible are exactly what a device credential
+// unlocks — which is why the config carries that credential and not an agent
+// token.
+//
+// Pairing codes still exist, for EXTERNAL and LEGACY runtimes: a self-hosted
+// gateway, or anything driving the Agent API directly. Those have no MCP client
+// to configure and no session concept, so `baychat pair <code>` remains their
+// path. It is not this one.
+//
+// FILE SAFETY. This edits config a user already has, so the merge is a splice
+// rather than a rewrite, it is idempotent, unparseable JSON is refused rather
+// than overwritten, the previous file is backed up first, and the result is 0600
+// because it holds a bearer token. See client-config-writer.ts.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderConnectMenu = renderConnectMenu;
+exports.parseConnectClient = parseConnectClient;
+exports.writeClientConfig = writeClientConfig;
+exports.cmdConnect = cmdConnect;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const client_config_writer_1 = require("./client-config-writer");
+const client_paths_1 = require("./client-paths");
+const commands_1 = require("./commands");
+const config_1 = require("./config");
+const connect_plan_1 = require("./connect-plan");
+const mcp_dialects_1 = require("./mcp-dialects");
+const commands_2 = require("./relay/commands");
+/** Clients `connect` can configure. `claude` is an alias users reach for. */
+const CLIENT_ALIASES = {
+    codex: "codex",
+    cursor: "cursor",
+    desktop: "desktop",
+    "claude-desktop": "desktop",
+};
+/** What `baychat connect` prints with no client: the menu. Names no credential. */
+function renderConnectMenu() {
+    const rows = mcp_dialects_1.MCP_CLIENTS.map((c) => `  npx baychat connect ${c.padEnd(8)}→ ${mcp_dialects_1.CLIENT_LABELS[c]}`);
+    return [
+        "Connect this laptop to BayChat, once, and configure your client:",
+        "",
+        ...rows,
+        "",
+        "You approve a QR on your phone. After that, in any coding session:",
+        "",
+        "  /baychat <name>        join BayChat as a session called <name>",
+        "",
+        "Claude Code needs no config — `npx baychat login` sets it up for you.",
+    ].join("\n");
+}
+/**
+ * Narrow a client argument.
+ *
+ * @throws on anything unsupported, listing what is supported. A typo must not
+ * fall through to a default and configure the wrong client.
+ */
+function parseConnectClient(value) {
+    const match = CLIENT_ALIASES[value.trim().toLowerCase()];
+    if (!match) {
+        throw new Error(`Unknown client "${value}" — supported: ${mcp_dialects_1.MCP_CLIENTS.join(", ")}. ` +
+            "Claude Code is registered automatically by `npx baychat login`.");
+    }
+    return match;
+}
+/** 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) {
+        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 };
+}
+/** Real filesystem IO for `writeClientConfig`. */
+const realIo = {
+    readFile: (p) => {
+        try {
+            return node_fs_1.default.readFileSync(p, "utf8");
+        }
+        catch (err) {
+            // ENOENT is the ordinary "first run" case. Anything else — a permission
+            // problem, a directory where a file should be — must not be silently read
+            // as "no config", because that would overwrite a file we simply could not
+            // open.
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    },
+    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 });
+    },
+};
+/**
+ * `baychat connect <client>`.
+ *
+ * @returns 0 on success, 2 when the laptop login expired without approval.
+ */
+async function cmdConnect(clientArg, opts = {}) {
+    if (clientArg === undefined) {
+        console.log(renderConnectMenu());
+        return 0;
+    }
+    const client = parseConnectClient(clientArg);
+    const base = (opts.base || process.env.BAYCHAT_API_URL || config_1.DEFAULT_API_URL).replace(/\/$/, "");
+    const steps = (0, connect_plan_1.planConnect)({
+        client,
+        device: (0, connect_plan_1.deviceStateFrom)((0, config_1.loadDeviceCredentials)()),
+        needsRestart: (0, client_paths_1.needsRestart)(client),
+    });
+    for (const step of steps) {
+        const outcome = await runStep(step, { base, client });
+        if (outcome.kind === "abort")
+            return outcome.code;
+    }
+    const summary = (0, connect_plan_1.describeConnection)({
+        device: (0, connect_plan_1.deviceStateFrom)((0, config_1.loadDeviceCredentials)()),
+        agentName: null,
+        groupTitle: null,
+    });
+    console.log("");
+    console.log(`  Laptop:  ${summary.laptop}`);
+    console.log(`  Sessions: ${summary.agent}`);
+    console.log("");
+    console.log(`  ${summary.note}`);
+    // The relay is what makes a joined session hear messages without being
+    // prompted. Best-effort by design: it reports what it did (or didn't) and
+    // never fails the connect it is tacked onto.
+    console.log(`  ${await (0, commands_2.ensureRelayInstalled)()}`);
+    return 0;
+}
+async function runStep(step, ctx) {
+    switch (step.kind) {
+        case "device-login": {
+            console.log(step.reason === "expired"
+                ? "Your laptop login has expired. Reconnecting this laptop…\n"
+                : "Connecting this laptop — approve the QR on your phone.\n");
+            // registerClaude is left ON only for the desktop/claude clients; for any
+            // other client, editing Claude's config unasked is a surprise.
+            const ok = await (0, commands_1.cmdLogin)({
+                base: ctx.base,
+                registerClaude: ctx.client === "desktop",
+                hint: false,
+            });
+            if (!ok) {
+                console.log("\nLaptop not connected — run `npx baychat connect` again when ready.");
+                return { kind: "abort", code: 2 };
+            }
+            console.log("✓ Laptop connected.\n");
+            return { kind: "ok" };
+        }
+        case "device-ok": {
+            console.log(`✓ Laptop already connected as ${step.userName}.`);
+            const nudge = (0, connect_plan_1.expiryNudge)({ kind: "live", userName: step.userName, msLeft: step.msLeft });
+            if (nudge)
+                console.log(`  ${nudge}`);
+            console.log("");
+            return { kind: "ok" };
+        }
+        case "write-config": {
+            // The DEVICE credential, deliberately — it is what unlocks the session tools
+            // (`join_session`, `list_sessions`, `end_session`) that let each session
+            // create its own identity. An agent token would pin this client to one
+            // agent in one room forever.
+            const device = (0, config_1.loadDeviceCredentials)();
+            if (!device) {
+                // Unreachable via planConnect, which logs in first; a guard rather than a
+                // 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 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)}`);
+            }
+            return { kind: "ok" };
+        }
+        case "restart-note":
+            console.log(`\n  Quit and reopen ${mcp_dialects_1.CLIENT_LABELS[step.client]} — it reads its config at startup.`);
+            return { kind: "ok" };
+    }
+}