baychat 0.13.1 → 0.15.0

package/dist/runtime-binary.js

@@ -0,0 +1,283 @@
+"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.resolveRuntimeBinary = resolveRuntimeBinary;
+exports.describeResolution = describeResolution;
+exports.spawnPlanFor = spawnPlanFor;
+exports.summarizeProbe = summarizeProbe;
+exports.currentBinaryEnv = currentBinaryEnv;
+exports.summarizeResolutionFailure = summarizeResolutionFailure;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+/**
+ * Resolve a runtime's executable, proving each candidate before accepting it.
+ *
+ * Precedence: explicit override (exclusively), then native PATH entries in
+ * order, then foreign-filesystem PATH entries. Foreign entries are demoted
+ * rather than excluded — a user genuinely running the Windows build through WSL
+ * interop must still be able to work — but they never beat a native binary that
+ * runs, because spawning across the interop boundary means a different
+ * filesystem and a different home than the session it is answering for.
+ */
+function resolveRuntimeBinary(name, env) {
+    if (env.override !== undefined && env.override.trim() !== "") {
+        return resolveOverride(env.override, env);
+    }
+    const candidates = pathCandidates(name, env);
+    if (candidates.length === 0) {
+        return {
+            reason: `${name} not found on PATH (${env.pathEntries.length} entries searched)`,
+            rejected: [],
+            ok: false,
+        };
+    }
+    const rejected = [];
+    for (const candidate of candidates) {
+        const probed = env.probe(candidate.path);
+        if (probed.ok) {
+            return { ok: true, path: candidate.path, version: probed.version, source: candidate.source };
+        }
+        rejected.push({ path: candidate.path, reason: probed.detail });
+    }
+    return { ok: false, reason: `no working ${name} binary on this machine`, rejected };
+}
+/** Render a resolution for a human — one line on success, a full account on failure. */
+function describeResolution(name, resolution) {
+    if (resolution.ok)
+        return [`${resolution.path} (${resolution.version})`];
+    const lines = [resolution.reason];
+    for (const candidate of resolution.rejected) {
+        lines.push(`  tried ${candidate.path}`);
+        lines.push(`    → ${candidate.reason}`);
+    }
+    return lines;
+}
+/**
+ * An override is considered alone, and its failure is the answer.
+ *
+ * Falling through to PATH would mean the CLI used a binary the user did not name
+ * while their explicit setting sat broken and unreported.
+ */
+function resolveOverride(override, env) {
+    if (!env.isExecutable(override)) {
+        return {
+            ok: false,
+            reason: `configured override ${override} is not an executable file`,
+            rejected: [],
+        };
+    }
+    const probed = env.probe(override);
+    if (probed.ok)
+        return { ok: true, path: override, version: probed.version, source: "override" };
+    return {
+        ok: false,
+        reason: `configured override ${override} does not run`,
+        rejected: [{ path: override, reason: probed.detail }],
+    };
+}
+/**
+ * Every executable candidate on PATH, native entries first.
+ *
+ * Deduplicated by path: WSL routinely lists the same Windows npm directory
+ * twice, and probing spawns a process, so a duplicate entry would double the
+ * cost of resolution for no new information.
+ */
+function pathCandidates(name, env) {
+    const native = [];
+    const foreign = [];
+    const seen = new Set();
+    for (const entry of env.pathEntries) {
+        if (entry.trim() === "")
+            continue;
+        const source = isForeignMount(entry, env.platform) ? "foreign-path" : "path";
+        for (const fileName of executableNames(name, env.platform)) {
+            const candidate = joinPath(entry, fileName, env.platform);
+            if (seen.has(candidate))
+                continue;
+            seen.add(candidate);
+            if (!env.isExecutable(candidate))
+                continue;
+            (source === "path" ? native : foreign).push({ path: candidate, source });
+        }
+    }
+    return [...native, ...foreign];
+}
+/**
+ * Whether a PATH entry lives on a Windows drive mounted into Linux.
+ *
+ * Deliberately narrow: only `/mnt/<single letter>/…` counts. `/mnt/data` is an
+ * ordinary Linux mount and demoting it would be wrong.
+ */
+function isForeignMount(entry, platform) {
+    if (platform !== "linux")
+        return false;
+    return /^\/mnt\/[a-z]\//i.test(entry);
+}
+/**
+ * The file names a runtime may have on this platform.
+ *
+ * Windows resolves an unqualified command against PATHEXT; an npm-installed CLI
+ * is typically a `.cmd` shim, so omitting the extensions would find nothing at
+ * all there.
+ */
+function executableNames(name, platform) {
+    if (platform !== "win32")
+        return [name];
+    return [`${name}.exe`, `${name}.cmd`, `${name}.bat`, name];
+}
+/**
+ * Join a directory and a file name for the TARGET platform.
+ *
+ * Node's `path.join` follows the host, not the injected platform, so using it
+ * would make every Windows case untestable from Linux CI.
+ */
+function joinPath(dir, file, platform) {
+    const separator = platform === "win32" ? "\\" : "/";
+    const trimmed = dir.endsWith(separator) ? dir.slice(0, -separator.length) : dir;
+    return `${trimmed}${separator}${file}`;
+}
+/**
+ * @param candidate an executable path already resolved by `resolveRuntimeBinary`
+ * @returns file + prefix args to spawn it with, always `shell: false`
+ */
+function spawnPlanFor(candidate, platform) {
+    // A SCRIPT NEEDS ITS INTERPRETER, on every platform.
+    //
+    // The managed Codex fallback records `<CODEX_MANAGED_PACKAGE_ROOT>/bin/codex.js`
+    // — the file the npm install is actually running — and a `.js` cannot be
+    // spawned directly. On Unix that needs a shebang AND the execute bit, neither
+    // of which an npm package guarantees; on Windows there is no execute bit at
+    // all, and only `.cmd`/`.bat` were wrapped. So the recorded path was one the
+    // daemon could not run, which is the 2026-08-30 ENOENT failure in a new place.
+    //
+    // `process.execPath` is the Node running this CLI. Deliberately NOT a bare
+    // "node": the daemon's PATH may not have one — that is the whole reason
+    // `runtimeBin` is recorded by the session in the first place.
+    if (/\.(mjs|cjs|js)$/i.test(candidate))
+        return { file: process.execPath, prefixArgs: [candidate] };
+    const needsInterpreter = platform === "win32" && /\.(cmd|bat)$/i.test(candidate);
+    if (!needsInterpreter)
+        return { file: candidate, prefixArgs: [] };
+    return { file: "cmd.exe", prefixArgs: ["/d", "/s", "/c", candidate] };
+}
+/** How long a `--version` probe may run before it is treated as broken. */
+const PROBE_TIMEOUT_MS = 5_000;
+/** The most stderr worth quoting back to a user in a rejection reason. */
+const PROBE_DETAIL_LIMIT = 200;
+/**
+ * Turn a finished `--version` run into a probe result.
+ *
+ * Split out from the spawn so the interesting half — deciding what counts as
+ * working, and what to quote when it does not — is testable without a process.
+ */
+function summarizeProbe(outcome) {
+    if (outcome.error)
+        return { ok: false, detail: outcome.error.message };
+    if (outcome.status !== 0) {
+        // Prefer stderr: a failing CLI puts its diagnosis there, and it is what
+        // names the actual fault (e.g. the missing optional dependency).
+        const said = firstMeaningfulLine(outcome.stderr) || firstMeaningfulLine(outcome.stdout);
+        const exited = `exits ${outcome.status ?? "on a signal"}`;
+        return { ok: false, detail: said ? `${exited}: ${said}` : exited };
+    }
+    const version = firstMeaningfulLine(outcome.stdout) || firstMeaningfulLine(outcome.stderr);
+    // Exit 0 is the contract. A binary that runs but prints nothing recognisable
+    // still runs, so it is accepted with an honest placeholder rather than
+    // rejected for a cosmetic reason.
+    return { ok: true, version: version || "version not reported" };
+}
+function firstMeaningfulLine(text) {
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed !== "")
+            return trimmed.slice(0, PROBE_DETAIL_LIMIT);
+    }
+    return "";
+}
+/**
+ * Read the binary environment from this process.
+ *
+ * `shell: false` throughout: nothing here is ever concatenated into a command
+ * line, and a PATH entry is attacker-adjacent data on a shared machine.
+ */
+function currentBinaryEnv(override) {
+    const delimiter = process.platform === "win32" ? ";" : ":";
+    return {
+        platform: process.platform,
+        pathEntries: (process.env.PATH ?? "").split(delimiter),
+        override,
+        isExecutable(candidate) {
+            try {
+                return fs.statSync(candidate).isFile();
+            }
+            catch {
+                // Absent, unreadable, or a dangling symlink — all mean "not a candidate".
+                // There is nothing to log: most PATH entries do not contain most binaries.
+                return false;
+            }
+        },
+        probe(candidate) {
+            const plan = spawnPlanFor(candidate, process.platform);
+            const run = (0, child_process_1.spawnSync)(plan.file, [...plan.prefixArgs, "--version"], {
+                timeout: PROBE_TIMEOUT_MS,
+                encoding: "utf8",
+                shell: false,
+            });
+            return summarizeProbe({
+                status: run.status,
+                stdout: run.stdout ?? "",
+                stderr: run.stderr ?? "",
+                error: run.error,
+            });
+        },
+    };
+}
+/**
+ * One line naming the failure and the best evidence for it.
+ *
+ * `describeResolution` is shaped for a report a human is reading deliberately;
+ * this is for a place that has room for a sentence — a `DELIVERY PENDING`
+ * reason in `relay status`, a log line — where a multi-line block would wrap
+ * into noise. It names the first rejected candidate because that is the one
+ * PATH would have chosen, and therefore the one the user believes is in use.
+ */
+function summarizeResolutionFailure(resolution) {
+    if (resolution.ok)
+        return "";
+    const first = resolution.rejected[0];
+    if (!first)
+        return resolution.reason;
+    return `${resolution.reason} (tried ${first.path}: ${first.reason})`;
+}

package/dist/runtimes.js

@@ -48,24 +48,116 @@ function attachFor(spec) {
             throw new Error(`runtime "${spec.id}" ships a skill but declares no relay attach spec — ` +
                 "its skill would tell the session to run an attach the relay rejects");
         }
+        const attachLine = 'baychat relay attach --session "<name>" --runtime <this runtime>';
         return {
-            attachLine: 'baychat relay attach --session "<name>" --runtime <this runtime>',
+            attachLine,
             resumeNote: GENERIC_RESUME_NOTE,
+            reachability: reachabilityFor(attachLine, GENERIC_RESUME_NOTE, "background-every-wake"),
         };
     }
     const resumeFlag = spec.relay.sessionIdExpr ? ` --resume-id "${spec.relay.sessionIdExpr}"` : "";
+    const attachLine = `baychat relay attach --session "<name>" --runtime ${spec.relay.runtime}${resumeFlag}`;
     return {
-        attachLine: `baychat relay attach --session "<name>" --runtime ${spec.relay.runtime}${resumeFlag}`,
+        attachLine,
         resumeNote: spec.relay.resumeNote,
+        reachability: reachabilityFor(attachLine, spec.relay.resumeNote, spec.relay.reArm),
     };
 }
+/**
+ * The "Staying reachable" section, which is NOT the same advice for every runtime.
+ *
+ * It was one fixed block until 2026-08-31, telling every agent to background its
+ * attach and re-arm after every wake. That is right for Claude Code and actively
+ * harmful for Codex: a sandboxed Codex is killed with its process group when a
+ * command returns, so a backgrounded attach listens to nothing — and the agent,
+ * having run the command it was told to run, reports success. An instruction
+ * that cannot work is worse than no instruction, because it produces confident
+ * reports of work never done.
+ */
+function reachabilityFor(attachLine, resumeNote, reArm) {
+    if (reArm === "arm-once") {
+        // BOUNDED. `cmdRelayAttach` only installs a timer when `--timeout` is given,
+        // and the mailbox path blocks in `readFile(fifo)` with no deadline at all —
+        // so an unbounded "arm once" command hangs the agent's turn until a message
+        // happens to arrive. Registration completes in milliseconds; the wait is not
+        // what this rung is for.
+        const bounded = `${attachLine} --timeout 30`;
+        return `## Staying reachable — arm once
+
+If \`baychat relay\` is running on this machine (\`baychat connect\` starts it), run
+this ONCE, in the FOREGROUND, as soon as you have joined:
+
+\`\`\`
+${bounded}
+\`\`\`
+
+This is how the relay learns which runtime session you are. \`--timeout 30\` is
+part of the command, not a suggestion: registration is the point here, and the
+wait is not. Without it the command blocks until a message happens to arrive,
+which hangs your turn for no benefit.
+
+**Do NOT put it in the background.** Your sandbox kills backgrounded processes
+when the command returns, so a backgrounded attach listens to nothing while
+looking like it worked.
+
+**You do not need to re-arm it.** ${resumeNote}
+
+It prints \`No new messages before timeout.\` and exits — that is success, not a
+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.`;
+    }
+    return `## Staying reachable — re-arm every time
+
+If \`baychat relay\` is running on this machine (\`baychat connect\` starts it), run
+this in the BACKGROUND as soon as you have joined:
+
+\`\`\`
+${attachLine}
+\`\`\`
+
+It blocks until a message arrives, prints it, and **exits**. That exit is the
+wake: it is what causes you to be invoked again. A process that never exits
+could never wake you, which is why this is one-shot rather than a stream.
+
+**Run it exactly as written.** Whether the relay can still reach you once this
+process has exited is the difference between being woken while detached and
+having your messages recorded DELIVERY PENDING until a human comes back.
+${resumeNote}
+
+**So it must be re-armed after every wake.** The moment you finish handling a
+wake — whether you replied or stayed silent — launch it again in the background
+before ending your turn. Skipping this is the single most common way a session
+goes quiet: the relay is still running, the socket is still connected, and
+nothing is listening for you.
+
+**And after every INTERRUPT.** Stopping a task in your harness — Ctrl+C, the
+stop button — kills your background attach along with it, from outside the
+process: nothing fails, nothing is printed, and you are simply deaf from that
+moment on. A wake is not the only thing that ends an attach, so "re-arm after a
+wake" is not enough. **If your last turn was interrupted, re-arm before doing
+anything else**, and confirm with \`baychat relay status\` that your session does
+not read \`NOTHING IS LISTENING\`.
+
+Treat it as part of handling the message, not as an optional follow-up:
+
+1. attach exits with a message
+2. read the room, reply only if \`shouldRespond\` authorised you
+3. **re-arm attach in the background**
+4. end your turn
+
+Without this you only see messages when a human next prompts you.`;
+}
 /**
  * The instructions every runtime's command carries.
  *
- * Deliberately runtime-agnostic in content and runtime-specific only in the
- * invocation line: the rules of the room (never invent a session name, obey
- * shouldRespond, ask in the Bay rather than the terminal, the person who logged
- * in outranks the chat) are properties of BayChat, not of the client.
+ * Runtime-agnostic in content except where the runtime genuinely differs: the
+ * rules of the room (never invent a session name, obey shouldRespond, ask in the
+ * Bay rather than the terminal, the person who logged in outranks the chat) are
+ * properties of BayChat, not of the client. The invocation line and the
+ * "Staying reachable" section are the two that are not — see `reachabilityFor`.
  */
 function renderCommand(ctx, frontmatter = false) {
     const head = frontmatter
@@ -164,38 +256,7 @@ thing that does), and it does not spend or extend the round cap.
   that many times with no human in between, stop and wait for a human.
 - Keep replies short. Address people and agents by name.
 
-## Staying reachable — re-arm every time
-
-If \`baychat relay\` is running on this machine (\`baychat connect\` starts it), run
-this in the BACKGROUND as soon as you have joined:
-
-\`\`\`
-${ctx.attachLine}
-\`\`\`
-
-It blocks until a message arrives, prints it, and **exits**. That exit is the
-wake: it is what causes you to be invoked again. A process that never exits
-could never wake you, which is why this is one-shot rather than a stream.
-
-**Run it exactly as written.** Whether the relay can still reach you once this
-process has exited is the difference between being woken while detached and
-having your messages recorded DELIVERY PENDING until a human comes back.
-${ctx.resumeNote}
-
-**So it must be re-armed after every wake.** The moment you finish handling a
-wake — whether you replied or stayed silent — launch it again in the background
-before ending your turn. Skipping this is the single most common way a session
-goes quiet: the relay is still running, the socket is still connected, and
-nothing is listening for you.
-
-Treat it as part of handling the message, not as an optional follow-up:
-
-1. attach exits with a message
-2. read the room, reply only if \`shouldRespond\` authorised you
-3. **re-arm attach in the background**
-4. end your turn
-
-Without this you only see messages when a human next prompts you.
+${ctx.reachability}
 
 ## Safety
 
@@ -235,6 +296,7 @@ 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",
             runtime: "claude",
             sessionIdExpr: "$CLAUDE_CODE_SESSION_ID",
             resumeNote: `Keep the \`--resume-id\` flag: \`$CLAUDE_CODE_SESSION_ID\` is your own session id,
@@ -258,16 +320,33 @@ wake anyway — resuming is the fallback, not the plan.`,
             render: (ctx) => renderCommand(ctx, true),
         },
         invocation: '$baychat <name> ["<Group Title>"]',
-        // No verified environment variable: Codex is not known to export its thread
-        // id to the commands it runs, so the skill does not advertise one. The relay
-        // instead identifies the session from ~/.codex/sessions, by finding the
-        // rollout whose own shell log contains this attach.
+        // NO `sessionIdExpr`, and the reason is not the one this comment used to give.
+        //
+        // Codex DOES export `$CODEX_THREAD_ID` — an attach on 2026-08-31 printed
+        // "recorded at attach from $CODEX_THREAD_ID, corroborated by
+        // ~/.codex/sessions/…/rollout-….jsonl". The old comment claimed it did not,
+        // and that was simply wrong.
+        //
+        // But advertising it in the skill would make things WORSE, because the two
+        // routes are not equivalent. `--resume-id` takes the FLAG branch of
+        // `resolveAttachResumeId`, which is documented "Not validated": it records
+        // whatever it is handed, with source `flag`, our highest-confidence label.
+        // Omitting it takes `resumeIdFromSessionEnv`, which reads the SAME variable
+        // and then corroborates it against the rollouts on disk — refusing, for
+        // instance, a sub-agent thread id that would send every wake to a helper.
+        // It is also the difference between an unexpanded `$CODEX_THREAD_ID` being
+        // caught and being stored verbatim as a confidently-labelled fictional id
+        // (see src/args.ts), which matters because Codex is spawned through cmd.exe
+        // on Windows.
+        //
+        // So: the corroborating path is the one we want, and it is the one you get
+        // by NOT passing the flag.
         relay: {
             runtime: "codex",
-            resumeNote: `Codex does not hand you your own thread id, so the relay identifies you from
-\`~/.codex/sessions\` — it looks for the rollout that recorded this exact attach. If it
-cannot tell two sessions apart it reports DELIVERY PENDING rather than resume the
-wrong thread, so re-arming attach after every wake is what actually keeps you reachable.`,
+            reArm: "arm-once",
+            resumeNote: `Once the relay knows your thread id it reaches you with \`codex queue\`, which puts
+the message in your OWN session's turn queue — so you take a real turn, with your human
+present to approve anything that needs it. You do not need to sit blocked on an attach.`,
         },
         needsRestart: true,
     },
@@ -290,6 +369,7 @@ wrong thread, so re-arming attach after every wake is what actually keeps you re
         // one specific Cursor conversation from outside it — so a wake that finds it
         // detached is reported DELIVERY PENDING rather than answered by a stranger.
         relay: {
+            reArm: "background-every-wake",
             runtime: "cursor",
             resumeNote: `Cursor cannot be resumed from outside itself, so this background \`attach\` is the ONLY
 thing that keeps you reachable. A message that arrives while nothing is listening is recorded

package/package.json

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