baychat 0.14.0 → 0.15.0

package/dist/args.js

@@ -27,6 +27,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.flag = flag;
 exports.positional = positional;
+exports.rejectUnknownFlags = rejectUnknownFlags;
 /**
  * The value of `--name`, or undefined when it was not given one.
  *
@@ -55,3 +56,17 @@ function flag(args, name) {
 function positional(args) {
     return args.find((a) => !a.startsWith("--"));
 }
+/**
+ * Refuse a flag this subcommand does not implement.
+ *
+ * Silently ignoring one is the worst option available: `relay status --json`
+ * printed the human table, exited as if it had honoured the request, and left
+ * the caller to discover the absence by parsing prose. A wrong answer that
+ * looks right survives far longer than an error.
+ */
+function rejectUnknownFlags(args, allowed, usage) {
+    const unknown = args.filter((a) => a.startsWith("--") && !allowed.includes(a));
+    if (unknown.length === 0)
+        return;
+    throw new Error(`unknown option${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}\nUsage: ${usage}`);
+}

package/dist/doctor.js

@@ -410,7 +410,8 @@ function skillCheck(runtime, env) {
         return { name: "skill", status: "skip", detail: spec.fallback ?? "no command mechanism" };
     }
     const file = `${env.home}/${spec.command.dir}/${spec.command.file}`;
-    if (env.readText(file) === null) {
+    const installed = env.readText(file);
+    if (installed === null) {
         return {
             name: "skill",
             status: "fail",
@@ -418,7 +419,25 @@ function skillCheck(runtime, env) {
             remedy: setupCommand(runtime),
         };
     }
-    return { name: "skill", status: "pass", detail: display(file, env) };
+    // PRESENT IS NOT CURRENT. Existence was the whole check, so a skill installed
+    // months ago passed while telling its agent something this package has since
+    // corrected — and `npm publish` does not rewrite an installed file, so the
+    // stale copy simply stays. That is not hypothetical: the file on the machine
+    // where this was written still said Codex exports no thread id and should
+    // background its attach, both of which cost an afternoon of unreachability.
+    //
+    // A doc that is wrong is worse than one that is missing, because a missing one
+    // sends the agent looking.
+    const current = (0, runtimes_1.renderCommandFor)(runtime);
+    if (current !== null && installed.trim() !== current.trim()) {
+        return {
+            name: "skill",
+            status: "fail",
+            detail: `${display(file, env)} is out of date — it does not match the skill this version installs`,
+            remedy: setupCommand(runtime),
+        };
+    }
+    return { name: "skill", status: "pass", detail: `${display(file, env)} (current)` };
 }
 function binaryCheck(runtime, env) {
     const command = HAS_BINARY[runtime];

package/dist/index.js

@@ -254,23 +254,30 @@ async function main() {
             const rest = args.filter((a) => a !== sub);
             switch (sub) {
                 case "start":
+                    (0, args_1.rejectUnknownFlags)(rest, ["--foreground"], "baychat relay start [--foreground]");
                     await (0, commands_2.cmdRelayStart)({ foreground: args.includes("--foreground") });
                     return 0;
                 case "status":
+                    (0, args_1.rejectUnknownFlags)(rest, [], "baychat relay status");
                     return await (0, commands_2.cmdRelayStatus)();
                 case "stop":
+                    (0, args_1.rejectUnknownFlags)(rest, [], "baychat relay stop");
                     return await (0, commands_2.cmdRelayStop)();
                 case "attach": {
                     const session = (0, args_1.flag)(rest, "--session");
                     if (!session) {
                         throw new Error("Usage: baychat relay attach --session <name> [--runtime claude|codex|hermes] [--resume-id <id>] [--timeout <sec>]");
                     }
+                    (0, args_1.rejectUnknownFlags)(rest, ["--session", "--runtime", "--resume-id", "--timeout", "--owner-pid"], "baychat relay attach --session <name> [--runtime claude|codex|hermes] [--resume-id <id>] [--timeout <sec>]");
                     const timeoutSec = numberFlag(rest, "--timeout");
                     return await (0, commands_2.cmdRelayAttach)({
                         session,
                         runtime: (0, args_1.flag)(rest, "--runtime") ?? "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
+                        // an ancestor and hands it to a child that has been detached.
+                        ownerPid: numberFlag(rest, "--owner-pid"),
                     });
                 }
                 default:

package/dist/relay/adapters.js

@@ -64,8 +64,24 @@ function buildWakePrompt(session, conversationId, batch, reArm) {
 function reArmLines(session, reArm) {
     if (!reArm)
         return [];
-    const command = `  ${reArm.node} ${reArm.cli} relay attach --session "${session}" --runtime ${reArm.runtime}`;
-    if (reArm.transport === "fifo") {
+    const attach = `${reArm.node} ${reArm.cli} relay attach --session "${session}" --runtime ${reArm.runtime}`;
+    const command = `  ${attach}`;
+    // BOUNDED, and it has to be. A foreground attach blocks until a message
+    // arrives — `cmdRelayAttach` installs a timer only when `--timeout` is given,
+    // and the mailbox path blocks in `readFile(fifo)` with no deadline at all. Told
+    // to run that unbounded inside a HEADLESS turn, the session cannot finish, and
+    // the daemon sits on it to its own 10-minute limit. Registration takes
+    // milliseconds; the wait is not what this is for. Same policy the skill
+    // generator states for `arm-once` — see `reachabilityFor` in runtimes.ts.
+    const boundedCommand = `  ${attach} --timeout 30`;
+    // FOREGROUND for the fifo rung — and for Codex on ANY transport.
+    //
+    // Branching on transport alone was not enough: a detached Codex whose recorded
+    // transport is "socket" or absent fell through to the background text, which
+    // is the instruction that started this whole outage. Codex's sandbox kills a
+    // backgrounded process when the tool command returns, so the runtime — not the
+    // rung — decides this.
+    if (reArm.transport === "fifo" || reArm.runtime === "codex") {
         return [
             "",
             "To stay reachable, run this IN THE FOREGROUND before ending your turn. It",
@@ -73,7 +89,9 @@ function reArmLines(session, reArm) {
             "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.",
-            command,
+            "`--timeout 30` is part of the command, not a suggestion: registering is the",
+            "point, and an unbounded wait would hold this turn open for no benefit.",
+            boundedCommand,
         ];
     }
     return [

package/dist/relay/commands.js

@@ -43,18 +43,22 @@ exports.attachViaMailbox = attachViaMailbox;
 exports.renderSessionLine = renderSessionLine;
 exports.cmdRelayAttach = cmdRelayAttach;
 exports.resolveRuntimeBin = resolveRuntimeBin;
+exports.decideRuntimeBin = decideRuntimeBin;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const net = __importStar(require("net"));
+const path = __importStar(require("path"));
 const util_1 = require("util");
 const adapters_1 = require("./adapters");
 const autostart_1 = require("./autostart");
 const runtime_binary_1 = require("../runtime-binary");
+const owner_pid_1 = require("./owner-pid");
+const parent_watch_1 = require("./parent-watch");
 const daemon_1 = require("./daemon");
 const resume_1 = require("./resume");
 const mailbox_1 = require("./mailbox");
 const socket_1 = require("./socket");
-const parent_watch_1 = require("./parent-watch");
+const parent_watch_2 = require("./parent-watch");
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 /** Connect to a running daemon, or explain that there isn't one. */
 async function connectOrFail() {
@@ -209,24 +213,98 @@ async function cmdRelayStatus() {
     console.log(`  polls: ${status.polls}   delivered: ${status.delivered}   cursor: ${status.cursor ?? "—"}`);
     if (status.lastError)
         console.log(`  last error: ${status.lastError}`);
+    // Computed before the session list so a line can report its own last failure.
+    const byName = new Map(status.sessions.map((s) => [s.name, s]));
+    /**
+     * Why this failure no longer stands, or undefined if it still does.
+     *
+     * Returns the REASON rather than a boolean so the line can say what cleared
+     * it. "(stale)" with no cause is the same species of unexamined claim this
+     * command exists to stop printing.
+     */
+    const staleReason = (p) => {
+        const session = byName.get(p.session);
+        // No session at all means nothing has been repaired — that is live, not stale.
+        if (!session)
+            return undefined;
+        // TWO WITNESSES, AND ONLY TWO. Everything weaker was tried and was wrong.
+        //
+        // A live SOCKET is demonstrably reachable — the attach is holding it now, so
+        // whatever this entry records is no longer true. `attached` alone is not
+        // that: the daemon sets it for a mailbox REGISTRATION too, and the fifo rung
+        // itself refuses to trust one, proving a reader with ENXIO on every write.
+        if (session.attached && session.transport !== "fifo")
+            return "an attach is holding the socket now";
+        // A delivery that actually LANDED after the failure. `registeredAt` was used
+        // for this and should not have been: it proves `relay attach` was rerun, and
+        // the npm/snap outage was made entirely of attaches that registered
+        // perfectly and then failed every single delivery.
+        const delivered = session.lastDeliveredAt;
+        if (delivered !== undefined && Date.parse(delivered) > Date.parse(p.at)) {
+            return `a later delivery landed at ${delivered}`;
+        }
+        return undefined;
+    };
+    const lastFailureFor = new Map();
+    for (const p of status.pending) {
+        if (!staleReason(p))
+            lastFailureFor.set(p.session, p.reason);
+    }
     console.log(`\nSessions (${status.sessions.length}):`);
     if (status.sessions.length === 0) {
         console.log("  none — a session registers itself by running `baychat relay attach`");
     }
     for (const s of status.sessions) {
-        const state = sessionState(s);
+        const state = sessionState(s, lastFailureFor.get(s.name));
         console.log(`  ${s.name}  [${s.runtime}]  ${state}`);
         console.log(`     ${resumeLabel(s)}`);
     }
+    // HELD is a THIRD state and prints as itself.
+    //
+    // These messages reached this box, were not delivered, and are not a failure:
+    // the agent is mid-turn and they go over the moment it re-arms. Folding them
+    // into pending would paint a working relay red; leaving them out is what we
+    // came from — before this they lived only in the daemon's heap, so a restart
+    // lost them silently and `relay status` never mentioned they had existed.
+    //
+    // Deliberately does NOT affect the exit code. A monitor should page on
+    // pending, never on an agent that is simply busy.
+    const held = status.held ?? [];
+    if (held.length > 0) {
+        const total = held.reduce((n, h) => n + h.count, 0);
+        console.log(`\nHELD (${total}) — waiting for a busy session to re-arm, not lost:`);
+        for (const h of held) {
+            console.log(`  ${h.heldAt}  ${h.session}  ${h.count} message(s) in ${h.conversationId}`);
+        }
+    }
     // Pending is the point of the whole command: these are messages that reached
     // this machine and that nobody answered.
+    //
+    // But a failure the operator has already FIXED must stop shouting. Pending
+    // records are never removed, so before this a single bad afternoon left the
+    // command exiting 2 forever — and a status that is permanently red is a status
+    // nobody reads. An entry that predates its session's current registration
+    // describes a session that has since been repaired: still worth printing as
+    // history, no longer worth alerting on.
     if (status.pending.length > 0) {
-        console.log(`\nDELIVERY PENDING (${status.pending.length}) — reached this box, not answered:`);
+        const live = status.pending.filter((p) => !staleReason(p));
+        const stale = status.pending.length - live.length;
+        const heading = live.length > 0
+            ? `DELIVERY PENDING (${live.length}) — reached this box, not answered:`
+            : `DELIVERY PENDING (0 live, ${stale} historical) — every one has been superseded by a later success:`;
+        console.log(`\n${heading}`);
         for (const p of status.pending.slice(-10)) {
-            console.log(`  ${p.at}  ${p.session}  msg ${p.messageId}`);
+            const why = staleReason(p);
+            console.log(`  ${p.at}  ${p.session}  msg ${p.messageId}${why ? `  (stale — ${why})` : ""}`);
             console.log(`     ${p.reason}`);
         }
-        return 2; // distinct exit code so a monitor can alert on it
+        if (live.length > 0 && stale > 0) {
+            console.log(`  (${stale} older entr${stale === 1 ? "y" : "ies"} marked stale — superseded by a later success.)`);
+        }
+        // Distinct exit code so a monitor can alert on it — but only for failures
+        // that still stand.
+        if (live.length > 0)
+            return 2;
     }
     return 0;
 }
@@ -340,19 +418,51 @@ async function attachViaMailbox(opts) {
         resumeEvidence: opts.resume.ok ? opts.resume.evidence : undefined,
         resumeCwd: opts.resume.ok ? opts.resume.cwd : undefined,
         cwd: process.cwd(),
-        // Resolved HERE, inside the session, for the same reason the socket rung
-        // does it: the binary a session was launched with is knowable here and
-        // nowhere else.
-        runtimeBin: resolveRuntimeBin(opts.runtime),
+        // Resolved inside the session, for the same reason the socket rung does it:
+        // the binary a session was launched with is knowable here and nowhere else.
+        // Passed in rather than re-probed — see `decideRuntimeBin`.
+        runtimeBin: opts.runtimeBin,
         fifo,
         pid: process.pid,
+        // The SESSION's pid, not this attach's and not its shell's. `pid` above dies
+        // with every wake, and `process.ppid` is a throwaway wrapper that exits in
+        // seconds — recording either told the daemon a live session had gone, and it
+        // spawned a headless duplicate. See `currentOwnerPid`.
+        ownerPid: opts.ownerPid ?? (0, owner_pid_1.currentOwnerPid)(opts.runtime),
         registeredAt: new Date().toISOString(),
     });
-    await (0, mailbox_1.awaitWakeFifo)(fifo);
+    const timeoutMs = opts.timeoutMs;
+    // NON-BLOCKING, because the obvious version cannot be cancelled.
+    //
+    // `readFile(fifo)` blocks in `open(2)` inside the libuv threadpool. No signal
+    // reaches it, and — measured — `process.exit()` does not end the process
+    // either: Node waits for that worker, so a "timeout" printed there is a lie the
+    // caller then hangs behind. An earlier fix here claimed a bound and shipped
+    // exactly that; the test missed it by never reaching the read.
+    //
+    // `O_RDONLY | O_NONBLOCK` opens a FIFO with no writer IMMEDIATELY, and reads
+    // then return nothing until the daemon writes. Polling that is genuinely
+    // cancellable: the deadline is a plain loop condition, the process can exit on
+    // its own, and there is nothing left blocked behind it.
+    const deadline = timeoutMs === undefined ? Number.POSITIVE_INFINITY : Date.now() + timeoutMs;
+    try {
+        await (0, mailbox_1.awaitWakeFifo)(fifo, Math.min(timeoutMs ?? 30_000, 30_000));
+    }
+    catch (err) {
+        // The relay never made the FIFO. Bounded arm-once treats that as its timeout
+        // rather than an error: the registration above still happened, which is the
+        // point of arming once.
+        if (timeoutMs === undefined)
+            throw err;
+        console.log(err instanceof Error ? err.message : String(err));
+        return 2;
+    }
     console.log(`Attached as "${opts.session}" over a mailbox FIFO (${fifo}). Waiting for messages…`);
-    // Opening for read blocks until the daemon opens for write. That block IS the
-    // wait, and it costs nothing: no model is running while it holds.
-    const raw = await fs.promises.readFile(fifo, "utf8");
+    const raw = await readWakeBounded(fifo, deadline);
+    if (raw === "timeout") {
+        console.log("No new messages before timeout. Registered and reachable — the relay will wake this session.");
+        return 2;
+    }
     const frame = JSON.parse(raw.trim());
     console.log(`WAKE ${frame.messages.length} message(s) in ${frame.conversationId}:`);
     for (const m of frame.messages) {
@@ -361,8 +471,49 @@ async function attachViaMailbox(opts) {
     }
     return 0;
 }
+/**
+ * Wait for one wake frame on a FIFO, without ever blocking uninterruptibly.
+ *
+ * Returns "timeout" instead of throwing: for `arm-once` a timeout is the normal
+ * ending, not a failure — registration already happened, and the relay owns
+ * every later wake.
+ */
+async function readWakeBounded(fifo, deadline, pollMs = 25) {
+    const handle = await fs.promises.open(fifo, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+    try {
+        const buf = Buffer.alloc(64 * 1024);
+        let acc = "";
+        for (;;) {
+            let bytes = 0;
+            try {
+                ({ bytesRead: bytes } = await handle.read(buf, 0, buf.length, null));
+            }
+            catch (err) {
+                // EAGAIN is "no writer has written yet" on a non-blocking FIFO, which is
+                // the normal state of this wait. Anything else is a real fault.
+                if (err.code !== "EAGAIN")
+                    throw err;
+            }
+            // A read of 0 is NOT end-of-input here. With no writer attached a
+            // non-blocking FIFO reports EOF, and the writer we are waiting for has not
+            // arrived yet — treating it as the end would turn every wait into an
+            // instant empty answer.
+            if (bytes > 0) {
+                acc += buf.subarray(0, bytes).toString("utf8");
+                if (acc.includes("\n"))
+                    return acc;
+            }
+            if (Date.now() >= deadline)
+                return "timeout";
+            await new Promise((r) => setTimeout(r, pollMs));
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
 /** The state half of one `relay status` session line. */
-function sessionState(s) {
+function sessionState(s, lastWakeFailure) {
     // "registered", not "attached", for the FIFO rung — and the difference is not
     // pedantry. A socket attach IS a held connection, so `attached` is an
     // observation. A mailbox registration is a file on disk; whether the agent is
@@ -370,8 +521,50 @@ function sessionState(s) {
     // a reader blocked in open() holds no descriptor for /proc to see and opening
     // the write end to look would signal EOF. Delivery is the only honest probe,
     // and it makes it: a wake with no reader is recorded pending, never delivered.
+    // A live SOCKET outranks a past failure: the attach is holding it right now.
+    // A FIFO REGISTRATION does not, and must not short-circuit the check below —
+    // that is the same "a registration is not a reader" rule `staleReason` applies
+    // to the pending list, and leaving it out here meant a session whose last wake
+    // died still printed a clean `registered (fifo)` on the one line a human reads.
+    if (s.attached && s.transport !== "fifo")
+        return "attached";
+    if (s.attached && !lastWakeFailure)
+        return "registered (fifo)";
     if (s.attached)
-        return s.transport === "fifo" ? "registered (fifo)" : "attached";
+        return `registered (fifo) — LAST WAKE FAILED, not reachable: ${lastWakeFailure}`;
+    // "headless resume ready" is a claim about a PRECONDITION — that we hold an id
+    // — and for a long time it was printed even while every wake using that id had
+    // failed. A non-engineer reads "ready" as "fine", so the one line that answers
+    // "is anything listening?" was the line most likely to mislead. If a wake has
+    // actually been tried and failed since this session registered, say THAT: an
+    // outcome outranks a precondition.
+    if (lastWakeFailure)
+        return `detached — LAST WAKE FAILED, not reachable: ${lastWakeFailure}`;
+    // INTERRUPTED, NOT GONE — and this line used to read "headless resume ready",
+    // which sounds fine and is now actively false.
+    //
+    // Stopping a task in the driving harness kills its background `relay attach`
+    // from OUTSIDE the process: no self-detach line is printed, nothing fails, the
+    // registration simply stops having a listener. And interrupting your own agent
+    // is an ORDINARY thing to do — every other fault in this release needed an
+    // unusual machine; this one needs Ctrl+C.
+    //
+    // "Headless resume ready" is wrong here for a specific reason: the daemon will
+    // NOT resume a session whose owning process is still alive — that is the
+    // no-clone guard — so a wake is held as pending instead. Reachable is exactly
+    // what this session is not.
+    //
+    // SCOPED TO RUNTIMES WITH NO LIVE-SESSION QUEUE. Codex is deliberately
+    // `arm-once`: its bounded attach exits and the session is SUPPOSED to sit
+    // detached with a live owner, because rung 2 hands the message to
+    // `codex queue` — which reaches the live session, and is tried BEFORE the
+    // no-clone guard is ever consulted. Warning there would alarm every healthy
+    // Codex on the machine, and a warning that fires when nothing is wrong is how
+    // a real one stops being read.
+    const hasLiveQueue = (0, adapters_1.adapterFor)(s.runtime).queueMessage !== undefined;
+    if (!hasLiveQueue && s.ownerPid !== undefined && (0, parent_watch_1.processIsAlive)(s.ownerPid)) {
+        return "detached — NOTHING IS LISTENING, re-arm: the session is alive but its attach is gone (interrupted?), so a wake will be held, not resumed";
+    }
     return s.resumeId ? "detached (headless resume ready)" : "detached (no resume id)";
 }
 /**
@@ -380,8 +573,8 @@ function sessionState(s) {
  * Exported so the rung's wording is testable: a fallback nobody can see in
  * `status` is a silent fallback, which is the thing this transport must not be.
  */
-function renderSessionLine(target) {
-    return `  ${target.name}  [${target.runtime}]  ${sessionState(target)}`;
+function renderSessionLine(target, lastWakeFailure) {
+    return `  ${target.name}  [${target.runtime}]  ${sessionState(target, lastWakeFailure)}`;
 }
 async function cmdRelayAttach(opts) {
     if (!(0, adapters_1.isKnownRuntime)(opts.runtime)) {
@@ -389,13 +582,35 @@ async function cmdRelayAttach(opts) {
         return 1;
     }
     const runtime = opts.runtime;
+    // 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
+    // anyway looks like success and hands the daemon back exactly the guess this
+    // setting exists to prevent — which is how a confined snap `codex` came to be
+    // spawned for an npm session and every wake died "no rollout found".
+    // Probed ONCE, here, and carried to whichever transport wins below.
+    const runtimeBin = decideRuntimeBin(runtime);
+    if (!runtimeBin.ok) {
+        console.log(`BAYCHAT_${runtime.toUpperCase()}_BIN is set but unusable: ${runtimeBin.reason}`);
+        console.log("Not attaching. Fix it or unset it — nothing was registered, so the relay will not report this session as reachable.");
+        return 1;
+    }
     const resume = await resolveAttachResumeId(runtime, opts.resumeId, opts.discovery);
     const sockPath = (0, socket_1.socketPath)();
     const probe = await (0, socket_1.probeSocketDetailed)(sockPath);
     if (shouldFallBackToMailbox(probe)) {
         console.log(`Relay socket refused (${probe.alive ? "" : (probe.code ?? "denied")}) — this session is sandboxed.`);
         console.log("Falling back to a mailbox FIFO, which a sandbox permits. `relay status` will show this session as attached (fifo).");
-        return attachViaMailbox({ session: opts.session, runtime, resume });
+        return attachViaMailbox({
+            session: opts.session,
+            runtime,
+            resume,
+            runtimeBin: runtimeBin.bin,
+            ownerPid: opts.ownerPid,
+            // Honoured on BOTH transports now. It was socket-only, which made
+            // `--timeout 30` a no-op precisely where a sandboxed session needs it.
+            timeoutMs: opts.timeoutMs,
+        });
     }
     if (!probe.alive) {
         console.log((0, socket_1.describeProbeFailure)(sockPath, probe));
@@ -414,7 +629,7 @@ async function cmdRelayAttach(opts) {
         // this process must go with it — otherwise it keeps the socket open, the
         // daemon keeps believing the session is live, and the next wake is written
         // into a corpse and recorded as delivered. See ./parent-watch.ts.
-        const parentWatch = (0, parent_watch_1.watchParent)(process.ppid, () => {
+        const parentWatch = (0, parent_watch_2.watchParent)(process.ppid, () => {
             console.log("Session that started this attach has exited — detaching so the relay stops treating it as live.");
             sock.end();
             resolve(3);
@@ -468,9 +683,12 @@ async function cmdRelayAttach(opts) {
             resumeEvidence: resume.ok ? resume.evidence : undefined,
             resumeCwd: resume.ok ? resume.cwd : undefined,
             cwd: process.cwd(),
-            // Resolved HERE, inside the session, because this is the only process that
-            // can answer it correctly — see SessionTarget.runtimeBin.
-            runtimeBin: resolveRuntimeBin(runtime),
+            // Decided once above, not re-probed here — see `decideRuntimeBin`.
+            runtimeBin: runtimeBin.bin,
+            // See SessionTarget.ownerPid: the runtime process that owns this session —
+            // 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),
         });
     });
 }
@@ -510,19 +728,59 @@ function resolveRuntimeBin(runtime) {
     // `resolveRuntimeBinary` tries the platform's real extension order and PROVES
     // each candidate by running it, which is the same question this function was
     // always asking — just answered correctly.
+    const decided = decideRuntimeBin(runtime);
+    return decided.ok ? decided.bin : undefined;
+}
+/**
+ * What to record for this runtime, or why the attach must not proceed.
+ *
+ * ONE probe, and the caller carries the answer. `resolveRuntimeBinary` SPAWNS
+ * each candidate to prove it, so asking twice is not merely wasteful: the second
+ * answer can differ from the first. An attach that passed the override guard and
+ * then re-probed could still register `runtimeBin: undefined` — the exact state
+ * the guard exists to prevent, reached by way of the guard.
+ */
+function decideRuntimeBin(runtime) {
     const override = process.env[`BAYCHAT_${runtime.toUpperCase()}_BIN`];
     const resolved = (0, runtime_binary_1.resolveRuntimeBinary)(runtime, (0, runtime_binary_1.currentBinaryEnv)(override));
-    if (!resolved.ok)
-        return undefined;
+    if (!resolved.ok) {
+        // An explicit override is a user ASSERTION. If it cannot be proven, stop —
+        // see the guard in `cmdRelayAttach`. Absence of one is not an assertion, so
+        // a plain failed probe keeps the best-effort fallback.
+        if (override)
+            return { ok: false, reason: (0, runtime_binary_1.summarizeResolutionFailure)(resolved) };
+        return { ok: true, bin: managedRuntimeBin(runtime) };
+    }
     try {
         // Resolve symlinks: ~/.local/bin/claude is typically a link into a versioned
         // directory, and recording the link means a later version bump silently
         // repoints every wake. The real path is what this session is actually running.
-        return fs.realpathSync(resolved.path);
+        return { ok: true, bin: fs.realpathSync(resolved.path) };
     }
     catch {
         // A path we just ran but cannot realpath is still the right answer.
-        return resolved.path;
+        return { ok: true, bin: resolved.path };
+    }
+}
+function managedRuntimeBin(runtime) {
+    if (runtime !== "codex")
+        return undefined;
+    const root = process.env.CODEX_MANAGED_PACKAGE_ROOT?.trim();
+    if (!root)
+        return undefined;
+    const candidate = path.join(root, "bin", "codex.js");
+    // PROVEN, not assumed. `statSync().isFile()` was the whole check here, so any
+    // file at that path counted — including one that cannot be spawned. Recording
+    // an unrunnable path is the failure this fallback exists to prevent, so it is
+    // put through the same prover an override gets: spawn it, ask its version.
+    const proved = (0, runtime_binary_1.resolveRuntimeBinary)(runtime, (0, runtime_binary_1.currentBinaryEnv)(candidate));
+    if (!proved.ok)
+        return undefined;
+    try {
+        return fs.realpathSync(proved.path);
+    }
+    catch {
+        return proved.path;
     }
 }
 /**