viber-channel 0.5.3 → 0.6.0

package/README.md

@@ -37,12 +37,40 @@ claude mcp add viber-channel --scope user \
 
 Restart Claude Code in the project directory. The channel acquires a single-instance lock under `%APPDATA%/viber/` (or `~/.config/viber/` on Linux/macOS), mints a conversation against the Worker, and subscribes to the conversation-scoped SSE stream.
 
+## Codex bridge experiment
+
+Issue #252 adds a Codex bridge as a sibling process to the Claude Code MCP channel. The bridge joins an existing Viber conversation as its own fresh Viber instance, listens to SSE events, forwards user/user_voice messages into a bridge-owned persistent `codex app-server` thread, and posts Codex's final reply back to Viber.
+
+Launch it against a conversation that already exists:
+
+```bash
+bun run viber-codex-bridge.ts --conversation <conversation_id>
+```
+
+Or via env fallback:
+
+```bash
+VIBER_TARGET_CONVERSATION_ID=<conversation_id> bun run viber-codex-bridge.ts
+```
+
+For one-shot validation, add `--once`; the bridge exits after the first Codex reply.
+
+The bridge persists its Codex thread id in `.viber/codex-bridge-threads.json` by default, keyed by project/fingerprint/conversation. Restarting the bridge resumes that thread, so Codex context carries across Viber turns. To reset/respawn the bridge-owned Codex session, start with `--new-thread`.
+
+Initial validation runs conservatively: `sandbox=read-only`, `approvalPolicy=on-request`, network disabled for turns, and developer instructions tell Codex not to run shell commands or read/write files. This is a validation posture, not a complete security boundary yet; hard permission enforcement must be designed before widening the bridge beyond read-only. Widen permissions only after the voice round-trip and memory test are validated.
+
+By default the bridge registers a fresh instance and does not persist it into the shared auth file. This avoids rotating another live agent's per-membership conversation token. For diagnostics only, `--reuse-auth-instance` restores the shared-auth behavior.
+
+For an agent-to-agent proof, add `--include-agent-messages --echo-content`. The bridge then reacts to non-user messages from other instances and replies with the exact content it received.
+
 ## Configuration
 
 | Env var | Default | Purpose |
 |---|---|---|
 | `VIBER_BASE_URL` | `https://viber.dgypx.dev` | Worker base URL (staging today; switch later if a separate prod hostname appears). |
 | `VIBER_CHANNEL_LABEL` | folder basename | Human-readable name for the conversation in the UI. |
+| `VIBER_CODEX_BIN` | `codex` | Codex executable used by `viber-codex-bridge` to spawn `codex app-server`. |
+| `VIBER_CODEX_BRIDGE_STATE` | `.viber/codex-bridge-threads.json` | Optional path for the bridge-owned Codex thread state file. |
 | `VIBER_CF_CLIENT_ID` / `VIBER_CF_CLIENT_SECRET` | unset | CF Access service-token headers (only needed when targeting a CF Access-protected hostname without a public bypass policy). |
 
 ## Source

package/lib/auth.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { chmodSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 
 export interface AuthJson {
@@ -20,6 +20,17 @@ export interface AuthJson {
    * the first successful mint, but doing so is not required for correctness.
    */
   target_conversation_id?: string | null;
+  /**
+   * Server-issued per-instance identity (#269). Both optional + additive, so
+   * `schema_version` stays **1**: an existing auth.json with neither field is
+   * valid and self-heals on first run (the channel registers an instance with
+   * its stable project_token and writes these back). `instance_token` is the
+   * durable, opaque per-agent credential (D4); `instance_id` is its server id,
+   * used to namespace the conversation handle (replacing the local fingerprint
+   * + VIBER_CHANNEL_SESSION_ID axes, #259).
+   */
+  instance_token?: string;
+  instance_id?: string;
 }
 
 /**
@@ -68,3 +79,41 @@ export function loadAuth(cwd: string = process.cwd()): AuthJson {
   }
   return auth;
 }
+
+/**
+ * Merge server-issued instance credentials into the auth file in place (#269
+ * self-healing migration). Reads the current JSON, sets `instance_id` +
+ * `instance_token`, and writes it back — preserving every other field and the
+ * `schema_version` (still 1; the fields are additive + optional).
+ *
+ * Best-effort: a write failure is logged, not fatal. The channel keeps the
+ * in-memory token for this run and simply re-registers on the next run (which
+ * yields a new instance — acceptable, the old one is just never reused).
+ */
+export function persistInstanceCredentials(
+  path: string,
+  instanceId: string,
+  instanceToken: string,
+  log: (msg: string) => void = (m) => process.stderr.write(m),
+): void {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const obj = JSON.parse(raw) as AuthJson;
+    obj.instance_id = instanceId;
+    obj.instance_token = instanceToken;
+    // mode 0o600: the file holds long-lived secrets (project_token + now the
+    // instance_token) — owner-read-only on POSIX (no-op on Windows). `mode` only
+    // applies when CREATING the file, so chmod afterwards too, to tighten an
+    // already-loose auth.json from an older version (best-effort).
+    writeFileSync(path, `${JSON.stringify(obj, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+    try {
+      chmodSync(path, 0o600);
+    } catch {
+      /* best-effort — some filesystems (or Windows) reject chmod */
+    }
+  } catch (err) {
+    log(
+      `[viber-channel] Warning: failed to persist instance credentials to \`${path}\`: ${String(err)}\n`,
+    );
+  }
+}

package/lib/bridge_spawn.ts

@@ -0,0 +1,105 @@
+/**
+ * Bridge spawn adapter (#280 step-12, slice 3).
+ *
+ * Turns an `AgentSpec` into a real launched `viber-codex-bridge` child process and
+ * adapts it to the Supervisor's `ChildHandle`. The node `spawn` primitive is
+ * injected so the mapping (command, args, env, lifecycle wiring) is unit-testable
+ * without launching anything.
+ *
+ * Per-agent identity (critical): each child must register its OWN Viber instance.
+ * The supervisor process may itself have been launched with VIBER_INSTANCE_TOKEN /
+ * VIBER_INSTANCE_ID in its environment; if those leaked into every child, all
+ * agents would share one instance identity and evict each other's membership (the
+ * known shared-auth gotcha). So the adapter strips them from the child env, forcing
+ * the bridge's default "register a fresh instance" path.
+ */
+
+import { spawn as nodeSpawn } from "node:child_process";
+import type { AgentSpec, ChildHandle, SpawnFn } from "./supervisor.ts";
+
+/** Minimal child surface the adapter consumes (matches node's ChildProcess). */
+export interface SpawnedProcess {
+	readonly pid?: number;
+	kill(signal?: NodeJS.Signals): boolean;
+	once(
+		event: "exit",
+		listener: (code: number | null, signal: NodeJS.Signals | null) => void,
+	): unknown;
+	/**
+	 * Launch failures (ENOENT for a missing command, EACCES, …) arrive here as an
+	 * async event — NOT a synchronous throw — so the adapter must listen for it or
+	 * a failed launch would leave the agent "running" with a dead child.
+	 */
+	once(event: "error", listener: (err: Error) => void): unknown;
+}
+
+/** The spawn primitive (injected; defaults to node's child_process.spawn). */
+export type NodeSpawnLike = (
+	command: string,
+	args: string[],
+	options: {
+		env: NodeJS.ProcessEnv;
+		stdio: ("ignore" | "inherit" | "pipe")[];
+	},
+) => SpawnedProcess;
+
+export interface BridgeSpawnOptions {
+	/** Launcher command. Default: the `viber-codex-bridge` bin on PATH. */
+	command?: string;
+	/** Args prepended before each agent's own args (e.g. a script path for `bun`). */
+	baseArgs?: string[];
+	/** Spawn primitive (injected for tests). Default: node child_process.spawn. */
+	spawnImpl?: NodeSpawnLike;
+}
+
+/**
+ * Build a `SpawnFn` for the Supervisor that launches the Codex bridge per agent.
+ *
+ * `AgentSpec.tier` → `VIBER_AGENT_TIER`; `AgentSpec.args` → bridge CLI flags;
+ * `AgentSpec.env` is merged last (so a spec can override). `VIBER_INSTANCE_TOKEN`
+ * / `VIBER_INSTANCE_ID` are stripped unless the spec explicitly re-supplies them.
+ */
+export function createBridgeSpawn(opts: BridgeSpawnOptions = {}): SpawnFn {
+	const command = opts.command ?? "viber-codex-bridge";
+	const baseArgs = opts.baseArgs ?? [];
+	const spawnImpl = opts.spawnImpl ?? (nodeSpawn as unknown as NodeSpawnLike);
+
+	return (spec: AgentSpec): ChildHandle => {
+		const env: NodeJS.ProcessEnv = { ...process.env };
+		// Force a fresh per-agent instance (see file header).
+		delete env.VIBER_INSTANCE_TOKEN;
+		delete env.VIBER_INSTANCE_ID;
+		env.VIBER_AGENT_TIER = spec.tier;
+		// Surface the agent id as the bridge's Viber instance label so distinct
+		// agents are identifiable in the control plane (participants strip / recipient
+		// picker) instead of all showing the same generic "Codex bridge" label.
+		env.VIBER_CODEX_BRIDGE_LABEL = spec.agentId;
+		if (spec.env) Object.assign(env, spec.env);
+
+		const child = spawnImpl(command, [...baseArgs, ...spec.args], {
+			env,
+			// stdin + stdout ignored, stderr inherited. stdout must NOT be inherited:
+			// if viber-channel runs over stdio MCP transport, the parent's stdout is
+			// the protocol wire and a child's stray stdout line would corrupt it.
+			stdio: ["ignore", "ignore", "inherit"],
+		});
+
+		return {
+			pid: child.pid,
+			kill: (signal?: NodeJS.Signals) => child.kill(signal),
+			onExit: (cb) => {
+				// Deliver exactly one terminal callback whether the child exits or
+				// fails to launch ("error"). A launch failure maps to a crash
+				// (null code/signal) so the supervisor runs its backoff path.
+				let fired = false;
+				const fire = (code: number | null, signal: NodeJS.Signals | null): void => {
+					if (fired) return;
+					fired = true;
+					cb(code, signal);
+				};
+				child.once("exit", (code, signal) => fire(code, signal));
+				child.once("error", () => fire(null, null));
+			},
+		};
+	};
+}

package/lib/channel_session.ts

@@ -5,16 +5,17 @@
  * conversation_id here. A respawned channel process reads this file to find the
  * existing conversation instead of minting a new one — avoiding duplicates (#257).
  *
- * Namespaced by `(VIBER_BASE_URL, client_fingerprint, VIBER_CHANNEL_SESSION_ID)` so:
+ * Namespaced by `(VIBER_BASE_URL, instance_key)` since #269, where `instance_key`
+ * is the server-issued `instance_id` (or the `instance_token` when the id is
+ * unknown, e.g. an env-injected agent). This replaces the old
+ * `(client_fingerprint, VIBER_CHANNEL_SESSION_ID)` namespacing so:
  * - dev and staging channels coexist on the same machine without colliding;
- * - two *different* projects on the same backend each have their own handle and
- *   never reattach to each other's conversation — the fingerprint axis is the
- *   only thing that isolates them for a normal bunx client (#267), where the
- *   sessionId is always "";
- * - two concurrent launches of the *same* project (each with its own session id
- *   set by viber-dev.ps1 / viber.ps1) each have their own handle (#259);
- * - channel respawns within one launch inherit the same session id and find
- *   the same handle — reattach still works (#257).
+ * - two *different* instances (different projects, OR two parallel agents of the
+ *   same project) each have their own handle and never reattach to each other's
+ *   conversation — the instance is the isolation axis now, no fingerprint or
+ *   session id required (#259);
+ * - channel respawns reusing the same persisted instance_token inherit the same
+ *   instance_id and find the same handle — reattach still works (#257).
  */
 import { createHash } from "node:crypto";
 import { join } from "node:path";
@@ -26,22 +27,24 @@ export interface ChannelHandle {
 }
 
 /**
- * Return the session file path for a given base URL, fingerprint, and session
- * id, under `dir`.
+ * Return the session file path for a given base URL and instance key, under `dir`.
  *
  * The filename is `channel-session-{8-hex}.json` where the hex is a stable
- * SHA-256 prefix of `${baseUrl}\n${fingerprint}\n${sessionId}` — the same input
- * shape as `lockFilePath`, so the lock and session files sit side by side for
- * the same `(baseUrl, fingerprint, sessionId)` triple.
+ * SHA-256 prefix of `${baseUrl}\n${instanceKey}`. Since #269 the handle is
+ * namespaced by the **server-issued instance** (its `instance_id`, or the
+ * `instance_token` when the id is unknown) instead of the local
+ * `(fingerprint, sessionId)` pair: one durable instance ⇒ one handle. Two
+ * parallel agents of the same project hold distinct instances, so they get
+ * distinct handles and never reattach to each other's conversation — without
+ * relying on `VIBER_CHANNEL_SESSION_ID`.
  */
 export function sessionFilePath(
   baseUrl: string,
-  fingerprint: string,
-  sessionId: string,
+  instanceKey: string,
   dir: string,
 ): string {
   const suffix = createHash("sha256")
-    .update(`${baseUrl}\n${fingerprint}\n${sessionId}`)
+    .update(`${baseUrl}\n${instanceKey}`)
     .digest("hex")
     .slice(0, 8);
   return join(dir, `channel-session-${suffix}.json`);

package/lib/connect.ts

@@ -12,6 +12,7 @@
 
 import {
   appendFileSync,
+  chmodSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -106,7 +107,15 @@ function writeAuthJson(
     auth.target_conversation_id = data.target_conversation_id;
   }
 
-  writeFileSync(authPath, JSON.stringify(auth, null, 2), "utf-8");
+  // mode 0o600: auth.json holds the project_token (and later the instance_token)
+  // — owner-read-only on POSIX (no-op on Windows). chmod afterwards too, since
+  // `mode` only applies on file creation (tightens an older loose auth.json).
+  writeFileSync(authPath, JSON.stringify(auth, null, 2), { encoding: "utf-8", mode: 0o600 });
+  try {
+    chmodSync(authPath, 0o600);
+  } catch {
+    /* best-effort — some filesystems (or Windows) reject chmod */
+  }
   writeFileSync(join(viberDir, "readme.md"), data.readme_md, "utf-8");
 
   // Append `.viber/` to .gitignore if not already present.

package/lib/control_stream.ts

@@ -0,0 +1,307 @@
+/**
+ * control_stream — subscribe to an instance-scoped server→agent control stream
+ * (#280 step-01/03).
+ *
+ * The control stream (`GET /api/instances/<id>/events`, authenticated by the
+ * instance_token) is how the server pushes commands to an agent BEFORE it is in
+ * any conversation. Today it carries:
+ *   - `connected` — open marker
+ *   - `ping`      — keepalive
+ *   - `stop`      — the instance was revoked; the agent should exit
+ *   - `join`      — admit this agent to a conversation; the payload IS a
+ *                   ConversationMintResponse (conversation_id, conversation_token,
+ *                   ws_url, expires_at), so it feeds the conversation SSE loop
+ *                   directly with no copy-pasted ids or tokens (the step-03 payoff).
+ *
+ * This module is intentionally side-effect-free and runtime-agnostic (no Codex /
+ * Claude specifics) so both bridges can consume it and it can be unit-tested with
+ * a mock fetch.
+ */
+import { cfAccessHeaders } from "./cfAccess.js";
+import type { ConversationMintResponse } from "./conversation.js";
+
+/** One parsed Server-Sent Event from the control stream. */
+export interface ControlEvent {
+  event: string;
+  data: string;
+}
+
+/** Build the instance control-stream SSE URL. */
+export function buildControlStreamUrl(baseUrl: string, instanceId: string): string {
+  return `${baseUrl}/api/instances/${instanceId}/events`;
+}
+
+export interface ControlStreamOptions {
+  baseUrl: string;
+  instanceId: string;
+  instanceToken: string;
+  signal?: AbortSignal;
+  /** Injectable for tests; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Thrown when the control stream is rejected with 401 — the instance_token is
+ * revoked or invalid, so the agent must re-register (a fresh instance_id).
+ */
+export class ControlStreamAuthError extends Error {
+  constructor() {
+    super("control stream unauthorized (instance token revoked or invalid)");
+    this.name = "ControlStreamAuthError";
+  }
+}
+
+/**
+ * Async generator that connects to the instance control stream and yields each
+ * parsed `{ event, data }`. One connection attempt — the caller decides whether
+ * to reconnect (the server keeps the stream open with `ping` keepalives). Throws
+ * `ControlStreamAuthError` on 401; the AbortSignal ends it cleanly.
+ */
+export async function* subscribeControlStream(
+  opts: ControlStreamOptions,
+): AsyncGenerator<ControlEvent> {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const url = buildControlStreamUrl(opts.baseUrl, opts.instanceId);
+
+  const resp = await doFetch(url, {
+    headers: {
+      Authorization: `Bearer ${opts.instanceToken}`,
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache",
+      ...cfAccessHeaders(),
+    },
+    signal: opts.signal,
+  });
+  if (resp.status === 401) throw new ControlStreamAuthError();
+  if (!resp.ok || !resp.body) {
+    throw new Error(`control stream connection failed: HTTP ${resp.status}`);
+  }
+
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      // Normalise CRLF → LF: the SSE spec allows \r\n line/record separators and
+      // some servers (incl. Cloudflare) emit them; without this the `\n\n` split
+      // never matches and a trailing `\r` corrupts every field value.
+      buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+      while (true) {
+        const eventEnd = buffer.indexOf("\n\n");
+        if (eventEnd === -1) break;
+        const block = buffer.slice(0, eventEnd);
+        buffer = buffer.slice(eventEnd + 2);
+
+        let event = "";
+        let data = "";
+        for (const line of block.split("\n")) {
+          if (line.startsWith(":")) continue; // comment line (keepalive)
+          if (line.startsWith("event: ")) event = line.slice(7);
+          else if (line.startsWith("data: ")) data = line.slice(6);
+        }
+        if (event) yield { event, data };
+      }
+    }
+  } finally {
+    // Release the reader (and cancel the body) so an early `break`/`return` by
+    // the consumer — e.g. waitForJoin resolving on the first join — or an abort
+    // doesn't leak the underlying connection until GC.
+    try {
+      await reader.cancel();
+    } catch {
+      /* already closed / aborted */
+    }
+  }
+}
+
+/** Raised when the control stream is signalled `stop` (instance revoked). */
+export class ControlStreamStopped extends Error {
+  constructor() {
+    super("control stream received stop (instance revoked)");
+    this.name = "ControlStreamStopped";
+  }
+}
+
+/**
+ * Parse a `join` event's data into a validated `ConversationMintResponse`, or
+ * null if it is malformed / missing fields (the caller skips it and waits for
+ * the next). Shared by waitForJoin and runPersistentControlStream.
+ */
+function parseJoinPayload(
+  data: string,
+  log: (msg: string) => void,
+): ConversationMintResponse | null {
+  let payload: Partial<ConversationMintResponse>;
+  try {
+    payload = JSON.parse(data) as Partial<ConversationMintResponse>;
+  } catch {
+    log("[control-stream] ignored malformed join payload\n");
+    return null;
+  }
+  if (
+    typeof payload.conversation_id === "string" &&
+    typeof payload.conversation_token === "string" &&
+    typeof payload.ws_url === "string" &&
+    typeof payload.expires_at === "number"
+  ) {
+    return payload as ConversationMintResponse;
+  }
+  log("[control-stream] ignored join payload with missing fields\n");
+  return null;
+}
+
+/**
+ * Consume the control stream until the first `join` event and return its payload
+ * as a `ConversationMintResponse` — ready to feed the conversation SSE loop. A
+ * `stop` event before any join throws `ControlStreamStopped`. `connected`/`ping`
+ * are ignored (keepalive). Malformed `join` data is skipped (waits for the next).
+ *
+ * NOTE: this CLOSES the stream on the first join (the generator returns). For the
+ * control-plane DM model — where presence must survive after joining — use
+ * runPersistentControlStream instead, which keeps the stream open for life.
+ */
+export async function waitForJoin(
+  opts: ControlStreamOptions,
+  log: (msg: string) => void = () => {},
+): Promise<ConversationMintResponse> {
+  for await (const ev of subscribeControlStream(opts)) {
+    if (ev.event === "stop") throw new ControlStreamStopped();
+    if (ev.event !== "join") continue; // connected / ping / unknown → ignore
+    const minted = parseJoinPayload(ev.data, log);
+    if (minted) return minted;
+  }
+  // Stream ended without a join — the caller reconnects.
+  throw new Error("control stream ended before a join event");
+}
+
+/** Resolve after `ms`, or early when `signal` aborts. */
+function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export interface PersistentControlStreamHandlers {
+  /** Called for EACH pushed join (the conversation to admit this agent into). */
+  onJoin?: (minted: ConversationMintResponse) => void;
+  /**
+   * Called once when the stream terminates for a NON-transient reason:
+   *   "stopped"      — a `stop` event arrived (the instance was revoked)
+   *   "unauthorized" — the control stream returned 401 (token revoked/invalid)
+   * The agent should shut down. NOT called on transient drops (those reconnect).
+   */
+  onStop?: (reason: "stopped" | "unauthorized") => void;
+  log?: (msg: string) => void;
+  /** Backoff before reconnecting after a drop / clean end. Default 2000ms. */
+  reconnectDelayMs?: number;
+}
+
+export interface PersistentControlStream {
+  /**
+   * Resolves with the FIRST pushed join — the caller starts the conversation
+   * from it. Rejects with ControlStreamStopped / ControlStreamAuthError if the
+   * stream ends (revoke / 401) before any join, or a generic Error on abort.
+   */
+  firstJoin: Promise<ConversationMintResponse>;
+  /** Resolves when the run loop exits (abort, stop, or auth error). */
+  done: Promise<void>;
+}
+
+/**
+ * Run the instance control stream for the agent's WHOLE lifetime (hub-and-spoke:
+ * ONE persistent server→agent link). Unlike waitForJoin — which returns on the
+ * first join and CLOSES the stream — this keeps the stream open AFTER the first
+ * join so server-side presence (#280 step-02) keeps seeing the agent online and
+ * re-invitable (step-20, Codex P1-3). Reconnects with backoff on transient drops;
+ * a `stop` (revoke) or 401 ends the loop via onStop. The AbortSignal ends it.
+ */
+export function runPersistentControlStream(
+  opts: ControlStreamOptions,
+  handlers: PersistentControlStreamHandlers = {},
+): PersistentControlStream {
+  const log = handlers.log ?? (() => {});
+  const delayMs = handlers.reconnectDelayMs ?? 2000;
+  const signal = opts.signal;
+
+  let firstSettled = false;
+  let resolveFirst!: (m: ConversationMintResponse) => void;
+  let rejectFirst!: (err: unknown) => void;
+  const firstJoin = new Promise<ConversationMintResponse>((res, rej) => {
+    resolveFirst = res;
+    rejectFirst = rej;
+  });
+  // Mark settled synchronously so the rejection on abort never fires after a
+  // resolve (and vice-versa) — and so an unobserved firstJoin still rejects once.
+  const settleFirstResolve = (m: ConversationMintResponse) => {
+    if (firstSettled) return;
+    firstSettled = true;
+    resolveFirst(m);
+  };
+  const settleFirstReject = (err: unknown) => {
+    if (firstSettled) return;
+    firstSettled = true;
+    rejectFirst(err);
+  };
+
+  const done = (async () => {
+    try {
+      while (true) {
+        if (signal?.aborted) {
+          settleFirstReject(new Error("control stream aborted before join"));
+          return;
+        }
+        try {
+          for await (const ev of subscribeControlStream(opts)) {
+            if (ev.event === "stop") {
+              settleFirstReject(new ControlStreamStopped());
+              handlers.onStop?.("stopped");
+              return;
+            }
+            if (ev.event !== "join") continue; // connected / ping / unknown
+            const minted = parseJoinPayload(ev.data, log);
+            if (!minted) continue;
+            handlers.onJoin?.(minted);
+            settleFirstResolve(minted);
+          }
+          // Clean end (server closed the SSE) → reconnect after backoff.
+        } catch (err) {
+          if (err instanceof ControlStreamAuthError) {
+            settleFirstReject(err);
+            handlers.onStop?.("unauthorized");
+            return;
+          }
+          if (signal?.aborted) {
+            settleFirstReject(new Error("control stream aborted before join"));
+            return;
+          }
+          log(
+            `[control-stream] ${err instanceof Error ? err.message : String(err)}, reconnecting...\n`,
+          );
+        }
+        if (signal?.aborted) {
+          settleFirstReject(new Error("control stream aborted before join"));
+          return;
+        }
+        await abortableDelay(delayMs, signal);
+      }
+    } finally {
+      // Defensive: never leave an awaiter of firstJoin hanging if the loop exits.
+      settleFirstReject(new Error("control stream ended before a join event"));
+    }
+  })();
+
+  return { firstJoin, done };
+}