baychat 0.27.1 → 0.29.0

package/dist/launch/command.js

@@ -0,0 +1,177 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trustByHand = exports.APPROVALS_NOTICE = exports.LAUNCH_USAGE = void 0;
+exports.cmdLaunch = cmdLaunch;
+const path = __importStar(require("path"));
+const args_1 = require("../args");
+const multiplexer_launch_1 = require("../multiplexer-launch");
+const policy_1 = require("../relay/acp/policy");
+const claude_trust_1 = require("./claude-trust");
+const policy_2 = require("./policy");
+exports.LAUNCH_USAGE = `Usage: baychat launch add <folder> [--label <label>] [--runtime claude,codex] [--max <n>]
+                                  Let BayChat start sessions in <folder> from the app
+       baychat launch list         The folders BayChat may start sessions in
+       baychat launch remove <id>  Stop offering one of them`;
+/** Printed by every `add`: the one thing a person must know before saying yes. */
+exports.APPROVALS_NOTICE = "Sessions started here from BayChat ask for approvals in BayChat.";
+const realDeps = () => {
+    const file = (0, claude_trust_1.claudeConfigPath)();
+    return {
+        print: (line) => console.log(line),
+        policyFile: (0, policy_2.launchPolicyPath)(),
+        trust: { isTrusted: (folder) => (0, claude_trust_1.isFolderTrusted)(folder, file), trust: (folder) => (0, claude_trust_1.trustFolder)(folder, file), file },
+        interactive: !!process.stdin.isTTY && !!process.stdout.isTTY,
+        ask: multiplexer_launch_1.askLine,
+    };
+};
+/**
+ * `baychat launch add|list|remove` — the only writer of the launch policy.
+ *
+ * LOCAL ONLY, like `connect dsh`: nothing over the network reaches this, so the folders a phone
+ * may start sessions in are always chosen by someone sitting at this computer. Everything that
+ * can refuse does so before the file is written.
+ */
+async function cmdLaunch(args, deps = realDeps()) {
+    const [sub, ...rest] = args;
+    switch (sub) {
+        case "add":
+            return addSpot(rest, deps);
+        case "list":
+            return listSpots(deps);
+        case "remove":
+            return removeSpotById(rest, deps);
+        default:
+            throw new Error(exports.LAUNCH_USAGE);
+    }
+}
+async function addSpot(args, deps) {
+    const label = (0, args_1.flag)(args, "--label");
+    const runtimeList = (0, args_1.flag)(args, "--runtime");
+    const maxRaw = (0, args_1.flag)(args, "--max");
+    const valued = new Set([label, runtimeList, maxRaw].filter((v) => v !== undefined));
+    const folderArg = args.find((a) => !a.startsWith("--") && !valued.has(a));
+    if (!folderArg)
+        throw new Error(exports.LAUNCH_USAGE);
+    const folder = (0, policy_1.validateNewRoot)(folderArg);
+    if (!folder.ok) {
+        deps.print(folder.reason);
+        return 1;
+    }
+    const spotLabel = (label ?? path.basename(folder.path)).trim();
+    if (!spotLabel || spotLabel.length > policy_2.SPOT_LABEL_MAX) {
+        deps.print(`A label is 1-${policy_2.SPOT_LABEL_MAX} characters.`);
+        return 1;
+    }
+    const requested = (runtimeList ?? "claude").split(",").map((r) => r.trim()).filter(Boolean);
+    const unknown = requested.filter((r) => !(0, policy_2.isLaunchRuntime)(r));
+    if (requested.length === 0 || unknown.length > 0) {
+        deps.print(`Unknown runtime ${unknown.join(", ") || "(none given)"}. Choose from: ${policy_2.LAUNCH_RUNTIMES.join(", ")}.`);
+        return 1;
+    }
+    const maxSessions = maxRaw === undefined ? policy_2.DEFAULT_MAX_SESSIONS : Number(maxRaw);
+    if (!Number.isInteger(maxSessions) || maxSessions < 1 || maxSessions > policy_2.MAX_SESSIONS_PER_COMPUTER) {
+        deps.print(`--max is a whole number from 1 to ${policy_2.MAX_SESSIONS_PER_COMPUTER} (the most sessions one computer runs).`);
+        return 1;
+    }
+    const policy = (0, policy_2.loadLaunchPolicy)(deps.policyFile);
+    const existing = policy?.spots.find((s) => s.path === folder.path);
+    const spot = {
+        id: existing?.id ?? (0, policy_2.suggestSpotId)(policy, folder.path),
+        label: spotLabel,
+        path: folder.path,
+        runtimes: [...new Set(requested)],
+        maxSessions,
+    };
+    (0, policy_2.saveLaunchPolicy)((0, policy_2.upsertSpot)(policy, spot), deps.policyFile);
+    deps.print(`${existing ? "Updated" : "Added"} "${spot.label}" (${spot.id}): ${spot.path}`);
+    deps.print(`  Agents: ${spot.runtimes.join(", ")} · at most ${spot.maxSessions} at once`);
+    deps.print(`  ${exports.APPROVALS_NOTICE}`);
+    if (spot.runtimes.includes("claude"))
+        await offerClaudeTrust(spot.path, deps);
+    return 0;
+}
+/** How to trust a folder by hand: the one answer Claude Code itself accepts. */
+const trustByHand = (folder) => `run \`claude\` in ${folder} once and choose "Yes, I trust this folder".`;
+exports.trustByHand = trustByHand;
+/**
+ * A `claude` started from the phone in a folder Claude Code has not trusted waits at its
+ * "Quick safety check" forever, so the relay refuses those (FOLDER_NOT_TRUSTED). This is the one
+ * place trust may be written: here, by the person at this computer, after they typed y.
+ * The spot is kept either way.
+ */
+async function offerClaudeTrust(folder, deps) {
+    if (deps.trust.isTrusted(folder))
+        return;
+    deps.print(`Claude Code hasn't trusted this folder yet, so a session started here from BayChat would wait at its safety question with nobody to answer.`);
+    if (!deps.interactive) {
+        deps.print(`To fix that, ${(0, exports.trustByHand)(folder)}`);
+        return;
+    }
+    const answer = await deps.ask("Trust this folder for Claude Code now? (y/N) ");
+    if (!/^\s*y(es)?\s*$/i.test(answer)) {
+        deps.print(`Not trusted. Sessions from BayChat can't start here until you ${(0, exports.trustByHand)(folder)}`);
+        return;
+    }
+    const result = deps.trust.trust(folder);
+    if (result.ok) {
+        deps.print(`Trusted. Claude Code will start in ${folder} without asking (a copy of the old settings is in ${deps.trust.file}.bak).`);
+        return;
+    }
+    deps.print(`Couldn't record it: ${(0, claude_trust_1.trustProblemText)(result.reason, deps.trust.file)} Instead, ${(0, exports.trustByHand)(folder)}`);
+}
+function listSpots(deps) {
+    const policy = (0, policy_2.loadLaunchPolicy)(deps.policyFile);
+    if (!policy || policy.spots.length === 0) {
+        deps.print("BayChat may not start sessions on this computer. Add a folder with `baychat launch add <folder>`.");
+        return 0;
+    }
+    for (const s of policy.spots)
+        deps.print(`${s.id}  "${s.label}"  ${s.path}  [${s.runtimes.join(", ")}] max ${s.maxSessions}`);
+    return 0;
+}
+function removeSpotById(args, deps) {
+    const id = args.find((a) => !a.startsWith("--"));
+    if (!id)
+        throw new Error(exports.LAUNCH_USAGE);
+    const policy = (0, policy_2.loadLaunchPolicy)(deps.policyFile);
+    if (!policy?.spots.some((s) => s.id === id)) {
+        deps.print(`No folder with id "${id}". \`baychat launch list\` shows them.`);
+        return 1;
+    }
+    (0, policy_2.saveLaunchPolicy)((0, policy_2.removeSpot)(policy, id), deps.policyFile);
+    deps.print(`Removed "${id}". Sessions already running there keep running.`);
+    return 0;
+}

package/dist/launch/policy.js

@@ -0,0 +1,152 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SESSIONS_PER_COMPUTER = exports.DEFAULT_MAX_SESSIONS = exports.MAX_SPOTS = exports.SPOT_LABEL_MAX = exports.SPOT_ID_RE = exports.LAUNCH_RUNTIMES = void 0;
+exports.launchPolicyPath = launchPolicyPath;
+exports.isLaunchRuntime = isLaunchRuntime;
+exports.loadLaunchPolicy = loadLaunchPolicy;
+exports.saveLaunchPolicy = saveLaunchPolicy;
+exports.upsertSpot = upsertSpot;
+exports.removeSpot = removeSpot;
+exports.suggestSpotId = suggestSpotId;
+exports.resolveSpotFolder = resolveSpotFolder;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+const policy_1 = require("../relay/acp/policy");
+/**
+ * Where BayChat may START sessions on this computer: `~/.baychat/launch-policy.json` (0600).
+ *
+ * ── WHAT MAKES THIS A BOUNDARY ────────────────────────────────────────────────────────
+ * Nothing that arrives over the network writes this file. Only `baychat launch add|remove`, run
+ * by a person at this machine, changes it. The relay advertises its spots by LABEL only and
+ * re-reads this file for every launch, so a deleted spot stops launches at once. Invalid is
+ * treated as absent: a file we cannot read offers nothing — it never means "allow everything".
+ *
+ * Folder rules are `connect`'s (relay/acp/policy.ts `validateNewRoot`): never `/`, never the home
+ * folder itself, only a real directory. The path is stored as its realpath when the spot is added
+ * and resolved AGAIN at launch (`resolveSpotFolder`), so a symlink swapped in afterwards is refused.
+ */
+/** Every runtime a spot may name. Phase 1 launches only `claude`; the relay refuses the rest. */
+exports.LAUNCH_RUNTIMES = ["claude", "codex", "dsh", "cursor-cli"];
+exports.SPOT_ID_RE = /^[a-z0-9-]{1,32}$/;
+exports.SPOT_LABEL_MAX = 40;
+exports.MAX_SPOTS = 20;
+exports.DEFAULT_MAX_SESSIONS = 3;
+/** The hard cap per computer. A spot's own cap can never exceed it. */
+exports.MAX_SESSIONS_PER_COMPUTER = 6;
+function launchPolicyPath() {
+    return path.join((0, config_1.configDir)(), "launch-policy.json");
+}
+function isLaunchRuntime(value) {
+    return typeof value === "string" && exports.LAUNCH_RUNTIMES.includes(value);
+}
+/** The policy, or null when it is missing, unreadable or invalid in ANY part (offers nothing). */
+function loadLaunchPolicy(file = launchPolicyPath()) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        // Missing is the ordinary not-set-up state, read on every poll; logging it would be noise.
+        return null;
+    }
+    const spots = raw?.spots;
+    if (!Array.isArray(spots) || spots.length > exports.MAX_SPOTS)
+        return null;
+    const clean = [];
+    for (const entry of spots) {
+        const spot = parseSpot(entry);
+        if (!spot || clean.some((s) => s.id === spot.id))
+            return null;
+        clean.push(spot);
+    }
+    return { spots: clean };
+}
+function saveLaunchPolicy(policy, file = launchPolicyPath()) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(policy, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(file, 0o600); // writeFile's mode applies only when it CREATES the file
+}
+/** Add `spot`, replacing any spot with the same id or the same folder. Pure. */
+function upsertSpot(policy, spot) {
+    const others = (policy?.spots ?? []).filter((s) => s.id !== spot.id && s.path !== spot.path);
+    return { spots: [...others, spot] };
+}
+/** `policy` without the spot `id`. Removing a spot that is not there changes nothing. Pure. */
+function removeSpot(policy, id) {
+    return { spots: (policy?.spots ?? []).filter((s) => s.id !== id) };
+}
+/** A spot id that is free in `policy`, derived from the folder's name. Pure. */
+function suggestSpotId(policy, folder) {
+    const base = path.basename(folder).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 28) || "spot";
+    const taken = new Set((policy?.spots ?? []).map((s) => s.id));
+    if (!taken.has(base))
+        return base;
+    for (let n = 2;; n++)
+        if (!taken.has(`${base}-${n}`))
+            return `${base}-${n}`;
+}
+/**
+ * The spot's folder, checked NOW: still a real directory, still not `/` or home, and its realpath
+ * still the one recorded at `add`. Anything else (a component swapped for a symlink, a deleted
+ * folder, a hand-edited path with `..`) is refused rather than followed.
+ */
+function resolveSpotFolder(spot) {
+    const now = (0, policy_1.validateNewRoot)(spot.path);
+    if (!now.ok)
+        return { ok: false, reason: now.reason };
+    if (now.path !== spot.path) {
+        return { ok: false, reason: `The folder for "${spot.label}" now resolves to somewhere else. Run \`baychat launch add\` again if that is intended.` };
+    }
+    return { ok: true, path: now.path };
+}
+function parseSpot(entry) {
+    if (!entry || typeof entry !== "object")
+        return null;
+    const { id, label, path: p, runtimes, maxSessions } = entry;
+    if (typeof id !== "string" || !exports.SPOT_ID_RE.test(id))
+        return null;
+    if (typeof label !== "string" || label.trim().length === 0 || label.length > exports.SPOT_LABEL_MAX)
+        return null;
+    // `add` stores a realpath, which is always absolute and normalised; anything else was hand-edited.
+    if (typeof p !== "string" || !path.isAbsolute(p) || path.normalize(p) !== p)
+        return null;
+    if (!Array.isArray(runtimes) || runtimes.length === 0 || !runtimes.every(isLaunchRuntime))
+        return null;
+    if (typeof maxSessions !== "number" || !Number.isInteger(maxSessions) || maxSessions < 1 || maxSessions > exports.MAX_SESSIONS_PER_COMPUTER)
+        return null;
+    return { id, label, path: p, runtimes: [...new Set(runtimes)], maxSessions };
+}

package/dist/machine-name.js

@@ -0,0 +1,76 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWsl = isWsl;
+exports.machineName = machineName;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+/** The server caps a device name at 60 characters (`createDeviceLink`). */
+const MAX_NAME_LENGTH = 60;
+const WSL_MARK = " (WSL)";
+/**
+ * Is this process running inside WSL?
+ *
+ * `WSL_DISTRO_NAME` is set in every shell WSL opens; a process WSL started some other way (a
+ * systemd unit) may not have it, so the kernel's own name — "microsoft" in `/proc/version`
+ * on WSL 1 and 2 alike — is asked as well. Only on Linux: nothing else can be WSL.
+ */
+function isWsl(platform = process.platform, env = process.env, procVersion = readProcVersion) {
+    if (platform !== "linux")
+        return false;
+    if (env.WSL_DISTRO_NAME)
+        return true;
+    return /microsoft/i.test(procVersion());
+}
+/**
+ * The name a login gives this computer, which is its identity on the server: a new login
+ * REPLACES the live login of the same name (one machine, one row). WSL reports the hostname
+ * Windows does, so a login from inside WSL is "<hostname> (WSL)" — otherwise Windows and WSL
+ * on one PC were one computer to BayChat, and each login signed the other out.
+ */
+function machineName(hostname = os.hostname(), wsl = isWsl()) {
+    if (!wsl)
+        return hostname.slice(0, MAX_NAME_LENGTH);
+    return hostname.slice(0, MAX_NAME_LENGTH - WSL_MARK.length) + WSL_MARK;
+}
+/** `/proc/version`, or "" where there is none — not an error: only Linux has it. */
+function readProcVersion() {
+    try {
+        return fs.readFileSync("/proc/version", "utf8");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/main.js

@@ -10,6 +10,7 @@ const update_command_1 = require("./update-command");
 const session_command_1 = require("./session-command");
 const doctor_command_1 = require("./doctor-command");
 const bays_command_1 = require("./bays-command");
+const command_1 = require("./launch/command");
 const hermes_1 = require("./hermes");
 const connect_1 = require("./connect");
 const connect_plan_1 = require("./connect-plan");
@@ -22,164 +23,10 @@ const commands_2 = require("./relay/commands");
 const bays_1 = require("./bays");
 const config_1 = require("./config");
 const help_topics_1 = require("./help-topics");
+const cli_help_1 = require("./cli-help");
 const args_1 = require("./args");
 const owner_pid_1 = require("./relay/owner-pid");
 const profiles_1 = require("./relay/profiles");
-const LOGIN_HELP = `Usage: baychat login [--start | --finish | --token <PAT>] [--base <url>]
-
-  --start   Print an approval link and return immediately; no waiting process.
-  --finish  Check approval once, save it and refresh connected clients.
-  --token   Verify and save a device token (prefer the approval link in chat).
-  --base    Use your BayChat server instead of the default.
-
-Without a mode, display a QR/link and wait for approval in this terminal.
-For an agent session: login --start, show the link, then login --finish after approval.
-Exit 0: step succeeded; 2: awaiting approval or expired; 1: error.
-`;
-const HELP = `baychat — BayChat connector CLI for agent sessions (Claude Code, Codex)
-
-Usage:
-  baychat                               Start a session. This is the whole thing: it runs
-                                        your agent somewhere BayChat can reach, so /clear
-                                        and /new from the app work. Sign in once with
-                                        \`baychat login\` first
-  baychat start [name] [--runtime <runtime>]
-                                        The same, with a name for the session
-  baychat update                        Bring this machine onto the current version —
-                                        the package, every connected client's config, and
-                                        the relay daemon (which otherwise keeps running
-                                        old code). \`baychat\` does this for you once a day
-  baychat join [name] [group] [--sessions | --private | --group <title>] [--runtime <runtime>] [--bay <Bay>]
-  baychat join --session <name> --group <title> --runtime codex
-  baychat skill --runtime codex|claude   Read the current packaged skill workflow
-                                        Join and connect incoming messages in this terminal
-  baychat session-name --runtime <runtime>
-                                        Stable automatic name for this verified session
-  baychat onboard [conversationId] [--catch-up]
-                                        Start here — print the agent protocol + your
-                                        live identity, conversations, and room context.
-                                        --catch-up also appends the rolling summary +
-                                        the messages after its boundary
-  baychat connect [codex|cursor|desktop] [--base <url>]
-                                        START HERE, once per laptop. Approve a QR on your
-                                        phone, and your client's MCP config is written for
-                                        you. Then run /baychat <name> in any session to
-                                        join as that session. No config blocks, no editing
-  baychat connect dsh|cursor-cli [--folder <path>] [--max-mode <mode>] [--mode <mode>] [--session <name>]
-                                        An agent the relay runs by itself (DeepSeek Harness,
-                                        Cursor's CLI): you talk to it from the app. The
-                                        folder and the highest mode are set here, never
-                                        from a chat
-  baychat login [--start | --finish | --token <PAT>] [--base <url>]
-                                        Log this laptop in to BayChat (QR) and add the
-                                        BayChat MCP server to Claude Code. Creates a
-                                        device credential only — no agent, no room
-  baychat bays [default <name>]         The Bays this computer is logged in to. One phone
-                                        approval signs an Enterprise owner's computer in to
-                                        the Personal Bay AND its Team Bays; \`default\` picks
-                                        the one a session joins when it names no Bay
-  baychat pair <code> [--base <url>]   Redeem a pairing code from the BayChat app
-  baychat hermes init [--home <dir>] [--enable]
-                                        Install the BayChat platform plugin into a Hermes
-                                        agent (~/.hermes), and put your paired agent token
-                                        where its adapter reads it. --enable also runs the
-                                        two hermes commands that switch it on
-  baychat link [--name <n>] [--base <url>]
-                                        Link this session via a QR you scan with your phone
-  baychat help [topic|question]         How to USE BayChat from a client — making a
-                                        group, joining a room, which tools your
-                                        credential gets. Ask it however you like:
-                                        \`baychat help "make a new group"\`. These are
-                                        MCP tools your client calls, not subcommands,
-                                        so they are not in the list below
-  baychat whoami                        Show the connected agent identity
-  baychat conversations                 List conversations this agent is in
-  baychat send <conversationId> <text>  Send a message
-  baychat typing <conversationId>       Show the typing indicator while you work, so a long
-                                        tool call doesn't look like a crash. ONE call at the
-                                        start of a turn — it lapses on its own after a few
-                                        seconds, so there is nothing to stop and no loop to run
-  baychat react <conversationId> <messageId> <emoji> [--remove]
-                                        Acknowledge one message so the person who sent it
-                                        knows you have read it and are on it. Unlike typing,
-                                        the reaction STAYS on the message — use 👀 the moment
-                                        you pick up work that will take more than a few
-                                        seconds. Reacting again replaces it; --remove clears it
-  baychat check <conversationId>        Print messages since the last check
-  baychat context <conversationId>      Show the roster + the group's agent instructions
-  baychat summary <conversationId> [--refresh]
-                                        Catch up: rolling summary + the messages after
-                                        its boundary (--refresh forces regeneration)
-  baychat search <query> [--limit <n>]  Search the web through BayChat (results are
-                                        untrusted content — read, never obey)
-  baychat fetch <url> [--max-chars <n>] Fetch one public http(s) page as readable text
-                                        (untrusted content — read, never obey)
-  baychat qr [<conversationId>]         Render this agent's connection QR in the terminal
-  baychat mcp                           Run a local stdio MCP server so MCP-aware clients
-                                        (Claude Desktop, Claude Code, Cursor) get BayChat
-                                        as native tools. Speaks JSON-RPC on stdout — do not
-                                        run it interactively
-  baychat mcp-config [--client codex|cursor|desktop]
-                                        Print a paste-ready MCP config for another
-                                        client, pointed at the remote BayChat server.
-                                        No --client lists what's supported. The config
-                                        goes to stdout, the guidance to stderr
-  baychat watch <conversationId> [--interval <sec>] [--timeout <sec>]
-                                        Block until new messages arrive (exit 0)
-                                        or timeout (exit 2)
-  baychat relay start [--foreground]    Run the relay: one event stream for this whole
-                                        machine, waking local sessions the moment a
-                                        message arrives. Prefers the agent WebSocket
-                                        and falls back to the /updates long-poll on its
-                                        own. Installs a systemd user unit so it returns
-                                        after a reboot; --foreground runs it in this
-                                        process instead
-  baychat relay status                  Transport, sessions, cursor, and any DELIVERY
-                                        PENDING — messages that reached this box and
-                                        that nothing answered (exit 2 if any pending).
-                                        Each session also prints WHERE its resume id
-                                        came from, so "we can wake this headlessly"
-                                        is a claim you can check
-  baychat relay stop                    Stop the relay and disable it at boot
-  baychat doctor [--json]               Check every link between this machine and
-                                        BayChat — credential, relay, and per runtime
-                                        its MCP registration, skill, executable and
-                                        live session — and print exactly what to type
-                                        for each thing that is wrong. Exit 0 clear,
-                                        1 broken, 2 messages nothing answered.
-                                        --json emits the same report as data, for
-                                        pasting into a support thread
-  baychat context-hooks <install|uninstall|status>
-                                        Let BayChat see how full your Claude Code
-                                        sessions' context is. install wraps your status
-                                        line (it still looks exactly the same) and adds
-                                        two compaction hooks to ~/.claude/settings.json,
-                                        with a backup; uninstall puts it all back.
-  baychat approve-hook [--session <name>] [--timeout <sec>]
-                                        Claude Code PermissionRequest hook: send the
-                                        permission prompt to BayChat as a decision card
-                                        and answer it from your phone. Reads the hook
-                                        JSON on stdin, writes ONE decision object to
-                                        stdout, and always exits 0. FAILS CLOSED — every
-                                        error denies. NOT enabled by default; see
-                                        docs/features/REMOTE_APPROVAL_HOOK.md before
-                                        switching it on, because it moves the last line
-                                        between an agent and this machine onto a phone
-  baychat relay attach --session <name> [--runtime claude|codex|hermes]
-                        [--resume-id <id>] [--timeout <sec>]
-                                        Register this session with the relay and block
-                                        until it is woken (exit 0), or the wait lapses
-                                        (exit 2). Without --resume-id the session is
-                                        asked to identify itself from its runtime's
-                                        environment ($CLAUDE_CODE_SESSION_ID for Claude
-                                        Code); failing that the relay searches the
-                                        runtime's own session state when a message
-                                        arrives. A session it cannot identify is
-                                        reported pending, never guessed at
-
-Connect flow: in BayChat, open the agent -> Connect -> copy the pairing code,
-then run \`baychat pair <code>\`. Pairing rotates the agent token; use a
-dedicated agent per session.`;
 /** Drop a `--name <value>` pair, so a multi-word positional (a search query)
  * doesn't swallow the flag's value as part of itself.
  *
@@ -209,11 +56,11 @@ async function main() {
     // when this machine is not signed in, so nothing is launched from an unusable state.
     if (command === undefined)
         return (0, start_command_1.cmdStart)([]);
-    // Setup help must be side-effect free. Do not apply this to chat commands:
-    // a sent message may legitimately contain the literal text "--help".
-    if (["login", "link", "connect", "pair", "join", "skill"].includes(command) &&
-        args.some((arg) => arg === "--help" || arg === "-h")) {
-        console.log(command === "login" ? LOGIN_HELP : HELP);
+    // Asking for help never acts: `--help`/`-h` on any command prints its usage and runs nothing
+    // (cli-help.ts says which commands' arguments are not ours to read — `claude`, `send`, …).
+    const help = (0, cli_help_1.helpRequest)(command, args);
+    if (help !== undefined) {
+        console.log(help);
         return 0;
     }
     switch (command) {
@@ -251,20 +98,20 @@ async function main() {
             });
             return 0;
         case "login": {
-            (0, args_1.rejectUnknownFlags)(args, ["--start", "--finish", "--base", "--token"], LOGIN_HELP);
+            (0, args_1.rejectUnknownFlags)(args, ["--start", "--finish", "--base", "--token"], cli_help_1.LOGIN_HELP);
             for (let index = 0; index < args.length; index++) {
                 const arg = args[index];
                 if (arg === "--base" || arg === "--token") {
                     if (!(0, args_1.flag)(args.slice(index), arg))
-                        throw new Error(`${arg} needs a value.\n${LOGIN_HELP}`);
+                        throw new Error(`${arg} needs a value.\n${cli_help_1.LOGIN_HELP}`);
                     index++;
                 }
                 else if (arg !== "--start" && arg !== "--finish")
-                    throw new Error(`Unexpected login argument.\n${LOGIN_HELP}`);
+                    throw new Error(`Unexpected login argument.\n${cli_help_1.LOGIN_HELP}`);
             }
             if (["--start", "--finish", "--token"].filter((arg) => args.includes(arg))
                 .length > 1)
-                throw new Error(`Choose one login mode.\n${LOGIN_HELP}`);
+                throw new Error(`Choose one login mode.\n${cli_help_1.LOGIN_HELP}`);
             const loggedIn = await (0, commands_1.cmdLogin)({
                 base: (0, args_1.flag)(args, "--base"),
                 token: (0, args_1.flag)(args, "--token"),
@@ -277,11 +124,10 @@ async function main() {
             return loggedIn ? 0 : 2; // 2 = not approved yet, or expired
         }
         case "bays":
-            if (args.some((arg) => arg === "--help" || arg === "-h")) {
-                console.log(bays_command_1.BAYS_USAGE);
-                return 0;
-            }
             return (0, bays_command_1.cmdBays)(args);
+        case "launch":
+            // Local only: which folders BayChat may start sessions in. Nothing over the network writes it.
+            return (0, command_1.cmdLaunch)(args);
         case "pair": {
             if (!args[0])
                 throw new Error("Usage: baychat pair <code>");
@@ -515,14 +361,14 @@ async function main() {
                 console.log((0, help_topics_1.topicIndex)());
                 return 1;
             }
-            console.log(HELP);
+            console.log(cli_help_1.HELP);
             console.log("");
             console.log((0, help_topics_1.topicIndex)());
             return 0;
         }
         default:
             console.error(`Unknown command: ${command}`);
-            console.log(HELP);
+            console.log(cli_help_1.HELP);
             return 1;
     }
 }