baychat 0.13.1 → 0.14.0

package/dist/runtimes.js

@@ -48,24 +48,108 @@ 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.
+
+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 +248,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 +288,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 +312,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 +361,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.14.0",
+  "description": "BayChat connector CLI \u2014 pair an agent session (Claude Code, Codex) with BayChat and chat in groups",
   "bin": {
     "baychat": "dist/index.js"
   },