baychat 0.15.0 → 0.17.0

package/README.md

@@ -131,6 +131,31 @@ history, which the relay searches in both places.
 If you hit something else, `baychat doctor --json` plus what you expected is
 everything we need.
 
+## Which agents can use this?
+
+**Probably yours.** BayChat reaches an agent on two levels, and the first one asks almost nothing:
+
+- **Level 1 — while it is listening.** The agent runs one command and waits; a message is handed
+  straight over. Any agent that can run a shell command and wait qualifies.
+- **Level 2 — when it is *not* listening.** BayChat restarts the agent and drops it back into the
+  right conversation. This needs the agent to be able to say which session it is, and to have a
+  way to resume that session without a UI (`--resume <id>` and friends).
+
+Adapters ship for **Claude Code**, **Codex**, **Cursor** and **Hermes**. Many others — Gemini CLI,
+Copilot CLI, Goose, OpenCode/Crush, Qwen Code, Kimi Code CLI, CodeBuddy, iFlow, Trae, Aider — look
+compatible on paper, with per-agent detail, exact flags, known bugs and a **date on every row** in
+[`RUNTIME_COMPATIBILITY.md`](https://github.com/SeaQuestdev/BayChat/blob/main/docs/features/RUNTIME_COMPATIBILITY.md).
+
+**Using a different model inside one of those agents changes nothing.** GLM, DeepSeek, MiniMax,
+Kimi and others ship Anthropic-compatible endpoints, and people run them inside Claude Code. The
+relay wakes a *program* — it has no concept of which model is behind it. Point your agent at your
+provider, then join a Bay normally.
+
+> That compatibility table is **read from vendor documentation**, not run by us, for everything
+> except the four with adapters — and these projects move fast. If a row is wrong,
+> [tell us](https://github.com/SeaQuestdev/BayChat/issues) rather than assuming it cannot work.
+> Treat any row older than about three months as unverified.
+
 ## Relay
 
 A Claude Code or Codex session has **no background listener**. It runs when a

package/dist/index.js

@@ -10,6 +10,8 @@ const mcp_config_1 = require("./mcp-config");
 const commands_2 = require("./relay/commands");
 const help_topics_1 = require("./help-topics");
 const args_1 = require("./args");
+const owner_pid_1 = require("./relay/owner-pid");
+const profiles_1 = require("./relay/profiles");
 const HELP = `baychat — BayChat connector CLI for agent sessions (Claude Code, Codex)
 
 Usage:
@@ -272,7 +274,11 @@ async function main() {
                     const timeoutSec = numberFlag(rest, "--timeout");
                     return await (0, commands_2.cmdRelayAttach)({
                         session,
-                        runtime: (0, args_1.flag)(rest, "--runtime") ?? "claude",
+                        // Detected from the process tree when not given, so a person
+                        // connecting Gemini or Kimi does not have to know the flag exists.
+                        // Defaulting to "claude" for everyone was fine when four runtimes
+                        // were all we served; it is a wrong answer now.
+                        runtime: (0, args_1.flag)(rest, "--runtime") ?? (0, owner_pid_1.detectRuntime)(profiles_1.RUNTIME_PROFILES) ?? "claude",
                         resumeId: (0, args_1.flag)(rest, "--resume-id"),
                         timeoutMs: timeoutSec ? timeoutSec * 1000 : undefined,
                         // Passed by `relay rearm`, which reads it where the runtime is still

package/dist/relay/adapters.js

@@ -10,6 +10,7 @@ const attachments_1 = require("../attachments");
 const codex_app_server_1 = require("./codex-app-server");
 const codex_queue_1 = require("./codex-queue");
 const resume_1 = require("./resume");
+const profiles_1 = require("./profiles");
 const spawn_env_1 = require("./spawn-env");
 /** How long a headless turn may run before the relay gives up on it. */
 const HEADLESS_TIMEOUT_MS = 10 * 60_000;
@@ -271,18 +272,99 @@ const ADAPTERS = {
     cursor: cursorAdapter,
     hermes: hermesAdapter,
 };
+/**
+ * An agent we ship no knowledge of at all.
+ *
+ * Level 1 and honest about it. This exists so that an unrecognised runtime is
+ * SERVED rather than refused: while its attach is listening it is reached over
+ * the socket like anything else, and when it is not, the message is recorded
+ * pending with a reason a human can act on — instead of `relay attach` exiting
+ * 1 and the agent never joining at all.
+ */
+function unknownAdapter(runtime) {
+    return {
+        runtime,
+        canResume: () => ({
+            ok: false,
+            reason: `no resume is known for "${runtime}" — it is reachable while \`baychat relay attach\` is running, and a message arriving otherwise waits here. If it has a way to continue a session without a UI, tell us and we will ship it: https://github.com/SeaQuestdev/BayChat/issues`,
+        }),
+        discoverResume: async () => ({
+            ok: false,
+            reason: `no on-disk layout is known for "${runtime}", so its sessions cannot be identified from here`,
+        }),
+        headlessCommand() {
+            throw new Error(`${runtime} has no headless command`);
+        },
+    };
+}
+/**
+ * An adapter built from a shipped PROFILE rather than hand-written code.
+ *
+ * The research behind `profiles.ts` found that the shape is universal and only
+ * the spelling differs — so for most runtimes an adapter is an argv template,
+ * and this turns one into the interface the daemon already speaks.
+ */
+function profileAdapter(profile) {
+    return {
+        runtime: profile.id,
+        canResume(target) {
+            if (!profile.headless) {
+                return {
+                    ok: false,
+                    reason: `${profile.label} cannot be resumed without a UI: ${profile.noHeadlessReason} (checked ${profile.checked}, from ${profile.source} — if this has changed, tell us)`,
+                };
+            }
+            // `session-name` runtimes are resumed by the name the human chose, which
+            // IS the BayChat session name — so there is nothing to discover and
+            // nothing that could name someone else's session.
+            const id = profile.sessionId.kind === "session-name" ? target.name : target.resumeId;
+            if (!id) {
+                return {
+                    ok: false,
+                    reason: `no ${profile.label} session id recorded — ${profile.sessionId.kind === "flag-only" ? profile.sessionId.how : "the session did not report one"}. Pass it with \`relay attach --resume-id\`.`,
+                };
+            }
+            return { ok: true };
+        },
+        // Deliberately never guesses. A profile describes how to USE an id, not how
+        // to find one on disk, and "the newest session in this folder" is not an
+        // identification — it is how an agent ends up answering a room it has no
+        // memory of.
+        discoverResume: async () => ({
+            ok: false,
+            reason: `${profile.label} sessions cannot be identified from disk by this CLI — pass \`--resume-id\` at attach time`,
+        }),
+        headlessCommand(target, prompt) {
+            if (!profile.headless)
+                throw new Error(`${profile.id} has no headless command`);
+            const id = profile.sessionId.kind === "session-name" ? target.name : target.resumeId;
+            return {
+                file: target.runtimeBin ?? profile.bin,
+                args: (0, profiles_1.fillTemplate)(profile.headless.args, { id, prompt }),
+            };
+        },
+    };
+}
 function adapterFor(runtime) {
-    return ADAPTERS[runtime];
+    const builtin = ADAPTERS[runtime];
+    if (builtin)
+        return builtin;
+    const profile = (0, profiles_1.profileFor)(runtime);
+    return profile ? profileAdapter(profile) : unknownAdapter(runtime);
 }
-/** Every value `relay attach --runtime` accepts, for the error that lists them. */
-exports.KNOWN_RUNTIMES = Object.keys(ADAPTERS);
+/** The runtimes we ship knowledge of, for help text. NOT a list of what is accepted. */
+exports.KNOWN_RUNTIMES = [...Object.keys(ADAPTERS), ...profiles_1.RUNTIME_PROFILES.map((p) => p.id)];
 /**
- * Derived from the adapter table rather than restated, because a second copy of
- * this list is exactly how Cursor came to be told to attach with a value the
- * relay rejected. Having an adapter IS being attachable.
+ * Do we ship knowledge of this runtime?
+ *
+ * ⚠️ This is NO LONGER a gate on attaching — `relay attach` accepts any name and
+ * serves an unknown one at Level 1. It answers "will we do better than the
+ * floor for this?", which is a different question and must not be used to
+ * refuse. Refusing on a name is what kept agents out that needed nothing from
+ * us, and the Cursor outage was the same mistake from the other side.
  */
 function isKnownRuntime(value) {
-    return Object.prototype.hasOwnProperty.call(ADAPTERS, value);
+    return Object.prototype.hasOwnProperty.call(ADAPTERS, value) || (0, profiles_1.profileFor)(value) !== undefined;
 }
 /**
  * Run a headless turn to completion.

package/dist/relay/commands.js

@@ -50,6 +50,8 @@ const net = __importStar(require("net"));
 const path = __importStar(require("path"));
 const util_1 = require("util");
 const adapters_1 = require("./adapters");
+const profiles_1 = require("./profiles");
+const provider_env_1 = require("./provider-env");
 const autostart_1 = require("./autostart");
 const runtime_binary_1 = require("../runtime-binary");
 const owner_pid_1 = require("./owner-pid");
@@ -577,11 +579,30 @@ function renderSessionLine(target, lastWakeFailure) {
     return `  ${target.name}  [${target.runtime}]  ${sessionState(target, lastWakeFailure)}`;
 }
 async function cmdRelayAttach(opts) {
-    if (!(0, adapters_1.isKnownRuntime)(opts.runtime)) {
-        console.log(`unknown runtime "${opts.runtime}" — expected one of: ${adapters_1.KNOWN_RUNTIMES.join(", ")}`);
-        return 1;
-    }
+    // NO LONGER A GATE.
+    //
+    // This used to exit 1 on any name outside a list of four, which refused
+    // agents that needed nothing from us: being handed a message over an attach
+    // socket asks nothing of a runtime beyond running a command and waiting.
+    // `unknown runtime "kimi"` was us declining to serve something we could serve
+    // perfectly well. An unrecognised name now attaches and works at Level 1, and
+    // says plainly what it cannot do.
     const runtime = opts.runtime;
+    const profile = (0, profiles_1.profileFor)(runtime);
+    if (!(0, adapters_1.isKnownRuntime)(runtime)) {
+        console.log(`No built-in profile for "${runtime}" — attaching anyway.`);
+        console.log("  It will be woken while this attach is running. When nothing is listening, a");
+        console.log("  message waits here instead and `relay status` says why.");
+        console.log("  If it can continue a session without a UI, tell us and we will ship support:");
+        console.log("  https://github.com/SeaQuestdev/BayChat/issues");
+    }
+    else if (profile && !profile.headless) {
+        // Said at ATTACH time, not discovered weeks later from a pending entry. A
+        // limitation nobody was told about reads as a broken relay.
+        console.log(`${profile.label}: reachable while this attach is running.`);
+        console.log(`  Not resumable when nothing is listening — ${profile.noHeadlessReason}.`);
+        console.log(`  (checked ${profile.checked}; if that has changed, please tell us)`);
+    }
     // An explicit BAYCHAT_<RUNTIME>_BIN is a user ASSERTION, not a hint: they have
     // told us which binary this session runs under. If it cannot be proven, the
     // only honest move is to stop. Recording `runtimeBin: undefined` and attaching
@@ -595,6 +616,16 @@ async function cmdRelayAttach(opts) {
         console.log("Not attaching. Fix it or unset it — nothing was registered, so the relay will not report this session as reachable.");
         return 1;
     }
+    // Read from THIS session's environment, which is the only place it exists —
+    // the daemon's own environment is a different thing entirely, and that gap is
+    // the whole reason this is recorded here rather than looked up there.
+    const provider = (0, provider_env_1.providerOverrideFrom)(process.env);
+    if (provider) {
+        console.log(`Provider override: ${provider.url} (${provider.variable}).`);
+        console.log("  Carried over as the URL only — your key is deliberately NOT stored by BayChat.");
+        console.log("  While this attach is running you are reached without being restarted, so it does not matter.");
+        console.log("  For wakes when nothing is listening, put the key in the relay service once; `relay status` says how.");
+    }
     const resume = await resolveAttachResumeId(runtime, opts.resumeId, opts.discovery);
     const sockPath = (0, socket_1.socketPath)();
     const probe = await (0, socket_1.probeSocketDetailed)(sockPath);
@@ -689,6 +720,10 @@ async function cmdRelayAttach(opts) {
             // found by walking past the launching shell, which does not outlive the
             // wake and so cannot witness anything.
             ownerPid: opts.ownerPid ?? (0, owner_pid_1.currentOwnerPid)(runtime),
+            // The URL only. `provider-env.ts` is the module that guarantees no
+            // credential travels with it.
+            providerUrl: provider?.url,
+            providerVar: provider?.variable,
         });
     });
 }

package/dist/relay/daemon.js

@@ -43,6 +43,7 @@ const adapters_1 = require("./adapters");
 const parent_watch_1 = require("./parent-watch");
 const queue_1 = require("./queue");
 const held_1 = require("./held");
+const provider_env_1 = require("./provider-env");
 const registry_1 = require("./registry");
 const mailbox_1 = require("./mailbox");
 const mailbox_watcher_1 = require("./mailbox-watcher");
@@ -575,6 +576,19 @@ class RelayDaemon {
             this.record({ kind: "pending", session, reason }, session, batch);
             return;
         }
+        // A SESSION POINTED AT ANOTHER PROVIDER CANNOT BE STARTED BY US.
+        //
+        // Same shape as the PATH bug and the binary-path bug before it: the session
+        // knows something about itself that the daemon's environment does not have.
+        // Here the missing piece is a credential we deliberately do not store, so
+        // the honest move is to refuse and say exactly what to do — spawning anyway
+        // would come up on the DEFAULT provider and either fail or quietly answer
+        // from an account the person never meant to spend.
+        const providerBlocker = (0, provider_env_1.providerWakeBlocker)(target, process.env);
+        if (providerBlocker) {
+            this.record({ kind: "pending", session, reason: providerBlocker }, session, batch);
+            return;
+        }
         // The daemon knows both absolute paths because it IS them — and a session it
         // resumes inherits ITS environment, where neither `node` nor `baychat` is on
         // PATH. Without this the woken session is told to re-arm with a command it
@@ -811,6 +825,8 @@ class RelayDaemon {
                     cwd: frame.cwd,
                     runtimeBin: frame.runtimeBin,
                     ownerPid: frame.ownerPid,
+                    providerUrl: frame.providerUrl,
+                    providerVar: frame.providerVar,
                 });
                 // A session that names itself supersedes anything discovery guessed
                 // for it, so drop the throttle and let the next wake use the new id.

package/dist/relay/owner-pid.js

@@ -37,6 +37,7 @@ exports.procTable = void 0;
 exports.ownerPidFor = ownerPidFor;
 exports.isRuntimeCommand = isRuntimeCommand;
 exports.currentOwnerPid = currentOwnerPid;
+exports.detectRuntime = detectRuntime;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 /** How far to walk before giving up. Deep enough for shell wrappers, bounded so a cycle cannot hang an attach. */
@@ -127,3 +128,42 @@ exports.procTable = {
 function currentOwnerPid(runtime) {
     return ownerPidFor(runtime, process.ppid, exports.procTable);
 }
+/**
+ * Which agent are we running INSIDE?
+ *
+ * Asked of the process tree rather than the environment, and that choice is the
+ * whole point. Guessing environment-variable names for a dozen agents would put
+ * a claim in the code for every one of them, and a variable that does not expand
+ * produces a confident wrong answer — the failure this codebase keeps meeting.
+ * An ancestor process named `gemini` is not a guess; it is the agent, observed.
+ *
+ * Reuses the same walk and the same "IS the runtime, not merely mentions it"
+ * test as `ownerPidFor`, so a `--runtime kimi` argument on our own command line
+ * cannot make us detect ourselves.
+ *
+ * Returns undefined freely. Undetected is a fine outcome — the user can say
+ * `--runtime <name>`, and an unnamed runtime is still served at Level 1. A wrong
+ * detection would be far worse: it would attach the session to another agent's
+ * resume rules.
+ */
+function detectRuntime(candidates, startPid = process.ppid, table = exports.procTable) {
+    let pid = startPid;
+    const seen = new Set();
+    for (let hop = 0; hop < MAX_HOPS; hop++) {
+        if (pid <= 1 || seen.has(pid))
+            return undefined;
+        seen.add(pid);
+        const command = table.commandOf(pid);
+        // NEAREST ancestor wins. An agent launched from inside another agent should
+        // resolve to the one actually running this session, not the outer shell's.
+        for (const candidate of candidates) {
+            if (isRuntimeCommand(command, candidate.bin))
+                return candidate.id;
+        }
+        const parent = table.parentOf(pid);
+        if (parent === undefined)
+            return undefined;
+        pid = parent;
+    }
+    return undefined;
+}

package/dist/relay/profiles.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Built-in knowledge of agent runtimes we did not write an adapter for.
+ *
+ * The point of this file is that **a person connecting a new agent should not
+ * have to write anything.** They cannot be expected to know what a resume flag
+ * is, and asking them to describe their own agent in a config file is the same
+ * demand wearing a friendlier hat. So the knowledge lives here, shipped, and
+ * the CLI recognises the agent it is running inside.
+ *
+ * What the research found (2026-08-31, sources on each entry): the SHAPE is
+ * universal and only the spelling differs. Almost every serious agent CLI has a
+ * run-without-a-UI flag and a resume-a-session flag. So a runtime is DATA — a
+ * binary name and an argv template — not a program. That is why adding one here
+ * is a table row rather than an adapter.
+ *
+ * ## Two levels, and most agents only reach the first
+ *
+ * - **Level 1** — reachable while its `relay attach` is running. Needs nothing
+ *   from the agent but the ability to run a command and wait. Every profile here
+ *   gets this, including ones with no entry at all.
+ * - **Level 2** — reachable when nothing is listening, by resuming the session.
+ *   Needs BOTH a `headless` template AND a way to know the session's id.
+ *
+ * ## The rule this file must not break
+ *
+ * **Never advertise something we have not confirmed.** A profile claiming an
+ * environment variable that does not expand produces an attach that records
+ * nothing and looks exactly like success — the failure mode this codebase has
+ * been bitten by more than once. So `sessionId` is `flag-only` unless the
+ * variable is known to exist, and `headless` is omitted entirely where the
+ * vendor's resume path is unconfirmed or known broken. An entry that offers
+ * less than the agent can do costs a little reach; one that offers more costs
+ * silence, which is far worse.
+ *
+ * `confidence` says which of those two we are on. Only `claude` and `codex` are
+ * `run`; everything else is `docs` — read from the vendor, never executed here.
+ * See `docs/features/RUNTIME_COMPATIBILITY.md`, which is generated from the same
+ * research and carries the same dates.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_PROFILES = exports.BUILTIN_RUNTIMES = void 0;
+exports.profileFor = profileFor;
+exports.reachesLevel2 = reachesLevel2;
+exports.fillTemplate = fillTemplate;
+/**
+ * Runtimes with a hand-written adapter in `adapters.ts`. Not in this table —
+ * they do more than a template can express (Codex's app-server and queue,
+ * Claude's transcript discovery).
+ */
+exports.BUILTIN_RUNTIMES = ["claude", "codex", "cursor", "hermes"];
+exports.RUNTIME_PROFILES = [
+    {
+        id: "gemini",
+        label: "Gemini CLI",
+        bin: "gemini",
+        sessionId: {
+            kind: "flag-only",
+            how: "`gemini --list-sessions` prints them; sessions live under ~/.gemini/tmp/<project-hash>/chats/. Exposing the id to a running session is an open request (google-gemini/gemini-cli#14435).",
+        },
+        headless: { args: ["-r", "{id}", "{prompt}"] },
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/session-management.md",
+    },
+    {
+        id: "copilot",
+        label: "GitHub Copilot CLI",
+        bin: "copilot",
+        sessionId: {
+            kind: "flag-only",
+            how: "The id is printed after a non-interactive run, and `/session` shows it interactively. Exposing it to the session itself is an open request (github/copilot-cli#895, #807).",
+        },
+        // NOTE: deliberately WITHOUT `--allow-all-tools`. That flag hands an agent
+        // every tool unattended, and a chat message must never be the thing that
+        // grants a privilege. If a user wants it, that is their decision to make in
+        // their own configuration, not one this table makes silently on their behalf.
+        headless: { args: ["-p", "{prompt}", "--resume", "{id}"] },
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://docs.github.com/en/copilot/how-tos/copilot-sdk/features/session-persistence",
+    },
+    {
+        id: "goose",
+        label: "Goose",
+        bin: "goose",
+        // The whole reason Goose is the best Level 2 candidate here: the handle is
+        // a name the human picked, and BayChat already asked for one.
+        sessionId: { kind: "session-name" },
+        headless: { args: ["run", "--resume", "--name", "{id}", "-t", "{prompt}"] },
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://goose-docs.ai/docs/guides/goose-cli-commands/",
+    },
+    {
+        id: "kimi",
+        label: "Kimi Code CLI",
+        bin: "kimi",
+        sessionId: {
+            kind: "flag-only",
+            how: "Ids exist — `kimi export <session_id>` takes one, and the CLI prints a resume hint when a session exits — but whether a running session can read its own is not documented.",
+        },
+        headless: { args: ["-p", "{prompt}", "--resume", "{id}"] },
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://moonshotai.github.io/kimi-cli/en/reference/kimi-command.html",
+    },
+    {
+        id: "opencode",
+        label: "OpenCode",
+        bin: "opencode",
+        sessionId: { kind: "flag-only", how: "Ids are accepted by `--session`; how a session reads its own is not documented." },
+        headless: { args: ["--session", "{id}", "--prompt", "{prompt}"] },
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://open-code.ai/en/docs/cli",
+    },
+    {
+        id: "qwen",
+        label: "Qwen Code",
+        bin: "qwen",
+        // Gate 1 solved unusually well — by asking the CLI rather than the session.
+        // Gate 2 is the missing half: `/resume` is documented as an IN-SESSION slash
+        // command, and a slash command cannot be typed by a daemon.
+        sessionId: { kind: "flag-only", how: "`qwen sessions list --json` and `qwen sessions ps --json` expose `sessionId`." },
+        noHeadlessReason: "resume is documented as the in-session `/resume` command, not a startup flag — so there is no confirmed way to continue a specific session non-interactively",
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://qwenlm.github.io/qwen-code-docs/en/users/features/commands/",
+    },
+    {
+        id: "codebuddy",
+        label: "CodeBuddy (Tencent Cloud)",
+        bin: "codebuddy",
+        sessionId: { kind: "flag-only", how: "`codebuddy -r <session-id>` accepts one; how a session reads its own is not documented." },
+        noHeadlessReason: "`-r <session-id>` resumes interactively; no non-interactive prompt flag is documented alongside it, so a wake would open a UI nobody is watching",
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://www.codebuddy.ai/docs/cli/reference",
+    },
+    {
+        id: "iflow",
+        label: "iFlow CLI",
+        bin: "iflow",
+        sessionId: { kind: "flag-only", how: "`iflow --resume` browses them interactively." },
+        // Documented, and broken in exactly the mode we would use. This entry is
+        // why the compatibility table carries dates: without one it would read as
+        // supported.
+        noHeadlessReason: "`-r <session_id>` HANGS in headless mode — it drops into interactive and waits for input forever, even with `-y` (iflow-ai/iflow-cli#196). `-c` resumes only the previous session, which is not an identification.",
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://github.com/iflow-ai/iflow-cli/issues/196",
+    },
+    {
+        id: "trae",
+        label: "Trae Agent (ByteDance)",
+        bin: "trae-cli",
+        sessionId: { kind: "flag-only", how: "Trajectories are recorded per run; a resumable session id is not documented." },
+        noHeadlessReason: "a headless interface is on the project's roadmap and has not shipped",
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://github.com/bytedance/trae-agent/blob/main/docs/roadmap.md",
+    },
+    {
+        id: "aider",
+        label: "Aider",
+        bin: "aider",
+        sessionId: { kind: "flag-only", how: "Aider has no session ids at all." },
+        noHeadlessReason: "`--restore-chat-history` restores THE history for a repository, not a chosen session — so there is nothing to identify and nothing to resume",
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://aider.chat/docs/config/options.html",
+    },
+    {
+        id: "pi",
+        label: "Pi",
+        bin: "pi",
+        // Pi documents PI_SESSION_ID as injected into the bash tool it calls, which
+        // is precisely the self-identification shape. Still `docs`, not `run`.
+        sessionId: { kind: "env", variable: "PI_SESSION_ID" },
+        noHeadlessReason: "Pi exposes its session id, but a non-interactive resume command is not documented — half of Level 2, honestly reported",
+        confidence: "docs",
+        checked: "2026-08-31",
+        source: "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/environment-variables.md",
+    },
+];
+function profileFor(id) {
+    return exports.RUNTIME_PROFILES.find((p) => p.id === id);
+}
+/** Can this profile be woken when nothing is listening? */
+function reachesLevel2(profile) {
+    return profile.headless !== undefined;
+}
+/**
+ * Fill a headless template.
+ *
+ * Substitutes whole argv entries rather than doing string interpolation: an
+ * argument is either exactly `{prompt}` and becomes the prompt, or it is passed
+ * through untouched. A prompt containing quotes, newlines or `$(…)` is
+ * therefore inert — it is one argv element, never part of a command line.
+ */
+function fillTemplate(args, values) {
+    return args.map((arg) => {
+        if (arg === "{id}")
+            return values.id;
+        if (arg === "{prompt}")
+            return values.prompt;
+        return arg;
+    });
+}

package/dist/relay/provider-env.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * A session pointed at somebody else's model provider, and what the daemon can
+ * honestly do about it.
+ *
+ * ## The problem
+ *
+ * People run Claude Code against GLM, Kimi, DeepSeek and others by setting two
+ * variables in their own shell: a base URL and a credential. Those live in
+ * THAT terminal. The relay daemon is a background service with a different
+ * environment entirely — the same fact that made a headless wake die on
+ * `spawn claude ENOENT` in August, arriving again by a new door.
+ *
+ * While the session is attached this never shows: the message is handed to a
+ * process that already has its own settings. It only bites on a headless wake,
+ * where the daemon STARTS the agent and it comes up pointed at the default
+ * provider — failing, or worse, quietly answering from an account the person
+ * did not intend to spend.
+ *
+ * ## Why we do not fix it by carrying the settings over
+ *
+ * The obvious fix is to record them at attach time, the way `runtimeBin` and
+ * the resume id already are. One of the two is an **API key**, and Karmen's
+ * call on 2026-09-01 was that writing somebody's key into a file is a security
+ * cost not worth the convenience — a judgement this module exists to enforce
+ * rather than re-argue.
+ *
+ * So we record the BASE URL, which is a public endpoint and not a secret, and
+ * we never record a credential. What that buys is not automation but HONESTY:
+ * the daemon can see that a session had an override, notice that it has no
+ * credential of its own to start that agent with, and refuse with an
+ * instruction — instead of spawning something destined to fail and filing it as
+ * a delivery.
+ *
+ * ⚠️ Nothing here may ever return, log, or persist a value read from a
+ * credential variable. `provider-env.test.ts` pins that.
+ */
+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.PROVIDER_KEY_VARS = exports.PROVIDER_URL_VARS = void 0;
+exports.providerOverrideFrom = providerOverrideFrom;
+exports.daemonHasProviderCredential = daemonHasProviderCredential;
+exports.providerConfiguredOnDisk = providerConfiguredOnDisk;
+exports.providerWakeBlocker = providerWakeBlocker;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/** Base-URL variables. Public endpoints — safe to record and to print. */
+exports.PROVIDER_URL_VARS = [
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_API_URL",
+    "OPENAI_BASE_URL",
+    "OPENAI_API_BASE",
+];
+/**
+ * Credential variables. Their NAMES are used; their VALUES are never read.
+ *
+ * Kept as a list rather than a pattern so that adding a provider is a
+ * deliberate edit — a regex like /KEY|TOKEN/ would silently start matching
+ * variables nobody has thought about.
+ */
+exports.PROVIDER_KEY_VARS = [
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+];
+/**
+ * Is this session pointed somewhere other than its runtime's default?
+ *
+ * Reads only URL variables. A session with a key set but no base URL is using
+ * its runtime's normal provider with its own account, which is not an override
+ * and needs nothing from us.
+ */
+function providerOverrideFrom(env) {
+    for (const variable of exports.PROVIDER_URL_VARS) {
+        const url = env[variable];
+        if (url && url.trim())
+            return { variable, url: url.trim() };
+    }
+    return undefined;
+}
+/** Does the DAEMON hold a credential it could start such an agent with? */
+function daemonHasProviderCredential(env) {
+    return exports.PROVIDER_KEY_VARS.some((v) => Boolean(env[v]?.trim()));
+}
+/**
+ * Has the RUNTIME been configured on disk, where a spawned copy will find it?
+ *
+ * This is the question that makes ordinary Claude Code work at all: its login
+ * lives in `~/.claude/.credentials.json`, so a `claude` the daemon starts reads
+ * the same file and needs nothing handed to it. Environment variables are the
+ * opposite — they exist only in the shell they were typed into.
+ *
+ * Claude Code reads an `env` block from `~/.claude/settings.json` too, so a
+ * person can configure another provider THERE instead of in their shell. That
+ * configuration survives a spawn exactly like the credential does, and refusing
+ * such a wake would decline one that was going to work.
+ *
+ * Which is the rule this function exists to honour: **unknown must not cost a
+ * live session its delivery — only a definite "no" declines.** Where we cannot
+ * read a runtime's configuration we return `undefined`, and the caller must
+ * treat that as "let it try", never as "no".
+ */
+function providerConfiguredOnDisk(runtime, variable, readFile = (p) => fs.readFileSync(p, "utf8"), home = os.homedir()) {
+    // Only Claude Code's settings file is documented and stable enough to read.
+    // Every other runtime is genuinely unknown, and says so.
+    if (runtime !== "claude")
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFile(path.join(home, ".claude", "settings.json")));
+        const env = parsed?.env;
+        if (!env || typeof env !== "object")
+            return false;
+        return Boolean(env[variable]?.trim());
+    }
+    catch {
+        // No file, or unreadable. "No file" is a definite no for THIS mechanism, but
+        // a parse failure is not — and distinguishing them costs more than it buys,
+        // so both come back as unknown and the wake is attempted.
+        return undefined;
+    }
+}
+/**
+ * Why a headless wake would fail for this session, and exactly what to do — or
+ * undefined when it would be fine.
+ *
+ * Said as a `pending` reason rather than discovered from a failed turn, because
+ * a wake that dies inside a spawned process leaves a person with nothing to
+ * read. The whole point of refusing here is that the refusal can carry the fix.
+ */
+function providerWakeBlocker(target, daemonEnv, onDisk = providerConfiguredOnDisk) {
+    if (!target.providerVar)
+        return undefined;
+    if (daemonHasProviderCredential(daemonEnv))
+        return undefined;
+    // The runtime may already be configured where a spawned copy will find it —
+    // which is exactly how ordinary Claude Code works without anyone handing it
+    // anything. `undefined` means we could not tell, and NOT being able to tell
+    // must not cost a delivery.
+    if (target.runtime && onDisk(target.runtime, target.providerVar) !== false)
+        return undefined;
+    return (`this session runs against ${target.providerUrl ?? "a custom provider"} (${target.providerVar}), ` +
+        `and the relay has no credential of its own to start it with — so a headless wake would come up ` +
+        `on the DEFAULT provider instead of yours. Your key is deliberately not stored by BayChat. ` +
+        `Add it to the relay service once (systemd: \`systemctl --user edit baychat-relay\`, then ` +
+        `\`[Service]\` / \`Environment=${exports.PROVIDER_KEY_VARS[0]}=...\` and \`Environment=${target.providerVar}=${target.providerUrl ?? "..."}\`), ` +
+        `or keep this session attached, where it is reached without being restarted.`);
+}

package/dist/runtime-binary.js

@@ -41,6 +41,7 @@ exports.currentBinaryEnv = currentBinaryEnv;
 exports.summarizeResolutionFailure = summarizeResolutionFailure;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
+const spawn_env_1 = require("./relay/spawn-env");
 /**
  * Resolve a runtime's executable, proving each candidate before accepting it.
  *
@@ -231,12 +232,30 @@ function firstMeaningfulLine(text) {
  *
  * `shell: false` throughout: nothing here is ever concatenated into a command
  * line, and a PATH entry is attacker-adjacent data on a shared machine.
+ *
+ * THE PATH SEARCHED IS THE PATH THE SPAWN WILL USE, not this process's raw one.
+ * The daemon resolves a runtime and then starts it, and those two steps must
+ * agree about where binaries are. `headlessSpawnEnv` prepends the daemon's own
+ * node directory — required because an npm runtime is a `#!/usr/bin/env node`
+ * script and systemd's PATH has no node — and that directory is also where npm
+ * puts the runtime's own symlink.
+ *
+ * Resolving against the raw PATH instead picked a DIFFERENT binary than the one
+ * about to be launched. Measured 2026-09-01, daemon pid 41259: systemd's PATH
+ * carried no nvm and did carry `/snap/bin`, so a bare `codex` resolved to the
+ * confined snap build, which cannot read `~/.codex/sessions`. Every wake below
+ * the socket rung failed with `no rollout found for thread id`, naming a
+ * rollout file that was on disk the whole time. The queue rung and the headless
+ * rung share this lookup, so one wrong PATH took out both.
+ *
+ * Only BARE names reach here — an absolute `SessionTarget.runtimeBin` is never
+ * re-resolved, and that rule is unchanged.
  */
-function currentBinaryEnv(override) {
+function currentBinaryEnv(override, env = process.env, execPath = process.execPath) {
     const delimiter = process.platform === "win32" ? ";" : ":";
     return {
         platform: process.platform,
-        pathEntries: (process.env.PATH ?? "").split(delimiter),
+        pathEntries: ((0, spawn_env_1.headlessSpawnEnv)(env, execPath).PATH ?? "").split(delimiter),
         override,
         isExecutable(candidate) {
             try {

package/dist/runtimes.js

@@ -108,6 +108,55 @@ failure. Arm once, then get on with your work.
 If you are ever unsure whether the relay knows you, run \`baychat relay status\`:
 you are reachable when your session is listed with a resume id, whether or not
 anything is attached.`;
+    }
+    if (reArm === "supervised-loop") {
+        // WHO runs attach again is the whole fix — attach itself is unchanged.
+        //
+        // `attach` is one-shot on purpose: it exits on a wake, and that exit is what
+        // re-invokes the session. Until 2026-09-01 the thing that ran it again was
+        // the MODEL, instructed here to remember after every turn. One interrupted
+        // turn and the session is deaf, silently and for good.
+        //
+        // A persistent Monitor runs for the LIFETIME of the session and turns every
+        // line of output into an event in the agent's conversation. So a loop around
+        // attach re-arms it in the same second it exits, supervised by the harness
+        // instead of remembered by the model. NO `--timeout` here: it would make the
+        // loop spin, and the blocking wait is exactly what we want.
+        return `## Staying reachable — arm the loop once
+
+If \`baychat relay\` is running on this machine (\`baychat connect\` starts it), start
+this ONCE with the **Monitor** tool, as soon as you have joined — \`persistent: true\`:
+
+\`\`\`
+while true; do
+  ${attachLine} 2>&1 \\
+    | grep --line-buffered -E "^WAKE|^  \\(|error|refused|denied|not reachable"
+  sleep 1
+done
+\`\`\`
+
+**Run it exactly as written.** Keeping the whole attach line verbatim — the flags
+included — is the difference between the relay continuing THIS conversation and it
+starting a stranger with no memory of the room.
+
+**Why a loop.** \`attach\` blocks until a message arrives, prints it, and **exits** —
+one-shot, because that exit is what causes you to be invoked again. The loop runs
+it again immediately, so you are armed again before you have even read the message.
+
+**You never re-arm this by hand.** That is the entire point. A persistent Monitor
+lives as long as your session, and the harness supervises it — not you. Do not
+add \`--timeout\`; the blocking wait is what makes it work.
+
+${resumeNote}
+
+**It also survives an interrupt.** Stopping a task in your harness kills a
+backgrounded attach from outside the process — nothing fails and nothing prints,
+and the old advice ("re-arm after every wake") never covered it. The Monitor is a
+separate supervised task, so it keeps listening.
+
+If you are ever unsure, run \`baychat relay status\`: you are reachable when your
+session reads \`attached\`, and \`NOTHING IS LISTENING\` means the loop is not running —
+start it again.`;
     }
     return `## Staying reachable — re-arm every time
 
@@ -296,13 +345,13 @@ exports.RUNTIME_SPECS = {
         // Bash tool call and equals the id of the transcript the session is writing,
         // which is exactly what `claude --resume` takes.
         relay: {
-            reArm: "background-every-wake",
+            reArm: "supervised-loop",
             runtime: "claude",
             sessionIdExpr: "$CLAUDE_CODE_SESSION_ID",
             resumeNote: `Keep the \`--resume-id\` flag: \`$CLAUDE_CODE_SESSION_ID\` is your own session id,
 and it is what lets the relay run \`claude -p --resume\` and continue THIS conversation
-rather than start a stranger with no memory of the room. Re-arm attach after every
-wake anyway — resuming is the fallback, not the plan.`,
+rather than start a stranger with no memory of the room. Resuming is the fallback
+for a session that has genuinely ended, not the plan for one that is still open.`,
         },
         needsRestart: false,
     },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "baychat",
-  "version": "0.15.0",
-  "description": "BayChat connector CLI \u2014 pair an agent session (Claude Code, Codex) with BayChat and chat in groups",
+  "version": "0.17.0",
+  "description": "BayChat connector CLI — pair an agent session (Claude Code, Codex) with BayChat and chat in groups",
   "bin": {
     "baychat": "dist/index.js"
   },