viber-channel 0.5.2 → 0.6.0

package/viber-codex-bridge.ts

@@ -0,0 +1,1247 @@
+#!/usr/bin/env bun
+/**
+ * viber-codex-bridge — Codex runtime bridge for issue #252.
+ *
+ * Joins an existing Viber conversation as a distinct instance, forwards user
+ * messages into a bridge-owned persistent Codex app-server thread, and posts
+ * Codex's final assistant reply back into Viber.
+ */
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { authFilePath, loadAuth } from "./lib/auth.ts";
+import {
+  ConversationMintError,
+  RefreshHttpError,
+  RefreshNetworkError,
+  defaultLabel,
+  reattachConversation,
+  refreshConversationToken,
+  type ConversationMintResponse,
+} from "./lib/conversation.ts";
+import { sessionFilePath, writeHandle } from "./lib/channel_session.ts";
+import { clientFingerprint } from "./lib/fingerprint.ts";
+import { acquireInstance, registerInstance } from "./lib/instance.ts";
+import type { AuthJson } from "./lib/auth.ts";
+import { postMessage, fetchMessages, ConversationTokenExpiredError } from "./lib/messages.ts";
+import { buildSseUrl } from "./lib/urls.ts";
+import {
+  runPersistentControlStream,
+  type PersistentControlStream,
+  ControlStreamStopped,
+  ControlStreamAuthError,
+} from "./lib/control_stream.ts";
+import { cfAccessHeaders } from "./lib/cfAccess.ts";
+import { createTokenRefreshScheduler, type TokenRefreshScheduler } from "./lib/token_refresh.ts";
+import { lockFilePath } from "./lib/lockfile.ts";
+
+const BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
+const LOCK_DIR =
+  process.env.APPDATA
+    ? join(process.env.APPDATA, "viber")
+    : join(process.env.HOME ?? "/tmp", ".config", "viber");
+
+interface BridgeOptions {
+  conversationId: string;
+  once: boolean;
+  newThread: boolean;
+  reuseAuthInstance: boolean;
+  includeAgentMessages: boolean;
+  echoContent: boolean;
+  /**
+   * #280 step-03: instead of a CLI/env conversation id, subscribe to the
+   * instance control stream and wait for a server-pushed `join` event. The
+   * conversation id + token arrive in-band — nothing is hand-carried.
+   */
+  awaitInvite: boolean;
+}
+
+interface ConversationMessage {
+  id?: string | number | null;
+  content?: string;
+  role?: string;
+  source?: string;
+  sender_instance_id?: string | null;
+}
+
+interface JsonRpcMessage {
+  id?: string | number;
+  method?: string;
+  params?: unknown;
+  result?: unknown;
+  error?: { code?: number; message?: string; data?: unknown };
+}
+
+interface PendingRequest {
+  resolve: (value: unknown) => void;
+  reject: (err: Error) => void;
+}
+
+interface TurnWaiter {
+  threadId: string;
+  turnId: string;
+  deltas: string[];
+  resolve: (value: string) => void;
+  reject: (err: Error) => void;
+  timeout: ReturnType<typeof setTimeout>;
+}
+
+interface ThreadState {
+  schema_version: 1;
+  threads: Record<string, {
+    thread_id: string;
+    conversation_id: string;
+    project_id: number;
+    client_fingerprint: string;
+    cwd: string;
+    viber_instance_id?: string;
+    updated_at: string;
+  }>;
+}
+
+interface ConversationRuntime {
+  id: string;
+  token: string;
+  expiresAt: number;
+  scheduler?: TokenRefreshScheduler;
+}
+
+class BridgeShutdownError extends Error {
+  constructor(message: string, public readonly exitCode: number) {
+    super(message);
+    this.name = "BridgeShutdownError";
+  }
+}
+
+interface BridgeLock {
+  path: string;
+  release: () => void;
+}
+
+function usage(): string {
+  return [
+    "viber-codex-bridge — join an existing Viber conversation as a Codex bridge",
+    "",
+    "USAGE",
+    "  bun run viber-codex-bridge.ts --conversation <conversation_id>",
+    "  viber-codex-bridge --conversation <conversation_id>",
+    "",
+    "OPTIONS",
+    "  --conversation <id>  Existing conversation id to join. Wins over VIBER_TARGET_CONVERSATION_ID.",
+    "  --once               Exit after posting the first fixed response.",
+    "  --new-thread         Start a fresh bridge-owned Codex thread and persist it for this conversation.",
+    "  --include-agent-messages",
+    "                       React to non-user messages from other instances too.",
+    "  --echo-content       Reply by echoing the exact received message content.",
+    "  --reuse-auth-instance",
+    "                       Reuse auth.json's persisted instance_token. Off by default because it",
+    "                       can rotate another live agent's membership token.",
+    "  -h, --help           Show this help.",
+    "",
+    "ENV",
+    "  VIBER_TARGET_CONVERSATION_ID  Fallback conversation id.",
+    "  VIBER_CODEX_BRIDGE_REPLY      Fixed reply text for the canal-nu test.",
+    "  VIBER_CODEX_BRIDGE_STATE      Optional path for the bridge-owned Codex thread state file.",
+  ].join("\n");
+}
+
+export function parseArgs(argv: string[], env: NodeJS.ProcessEnv = process.env): BridgeOptions {
+  let conversationId = env.VIBER_TARGET_CONVERSATION_ID?.trim() ?? "";
+  let once = false;
+  let newThread = false;
+  let reuseAuthInstance = false;
+  let includeAgentMessages = false;
+  let echoContent = false;
+  let awaitInvite = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      process.stdout.write(`${usage()}\n`);
+      process.exit(0);
+    }
+    if (arg === "--once") {
+      once = true;
+      continue;
+    }
+    if (arg === "--new-thread") {
+      newThread = true;
+      continue;
+    }
+    if (arg === "--reuse-auth-instance") {
+      reuseAuthInstance = true;
+      continue;
+    }
+    if (arg === "--include-agent-messages") {
+      includeAgentMessages = true;
+      continue;
+    }
+    if (arg === "--echo-content") {
+      echoContent = true;
+      continue;
+    }
+    if (arg === "--await-invite") {
+      awaitInvite = true;
+      continue;
+    }
+    if (arg === "--conversation") {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("-")) {
+        throw new Error("Missing value for --conversation");
+      }
+      conversationId = value.trim();
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--conversation=")) {
+      conversationId = arg.slice("--conversation=".length).trim();
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  // In await-invite mode the conversation id is delivered by the server's pushed
+  // `join`, so it must NOT be required up front (#280 step-03).
+  if (conversationId.length === 0 && !awaitInvite) {
+    throw new Error(
+      "Missing target conversation id. Pass --conversation <id>, set VIBER_TARGET_CONVERSATION_ID, or use --await-invite.",
+    );
+  }
+
+  return { conversationId, once, newThread, reuseAuthInstance, includeAgentMessages, echoContent, awaitInvite };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function headers(conversationToken: string, fingerprint: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${conversationToken}`,
+    "X-Client-Fingerprint": fingerprint,
+    ...cfAccessHeaders(),
+  };
+}
+
+function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (typeof err === "object" && err !== null && "code" in err && err.code === "EPERM") return true;
+    return false;
+  }
+}
+
+// `sessionId` is the lock identity axis. #280 step-12 keys it per AGENT
+// (`codex-agent:<instanceId>`) so multiple agents share one conversation; before
+// that it was per conversation. Callers pass the full namespaced string.
+function acquireBridgeLock(baseUrl: string, fingerprint: string, sessionId: string): BridgeLock {
+  mkdirSync(LOCK_DIR, { recursive: true });
+  const path = lockFilePath(baseUrl, fingerprint, sessionId, LOCK_DIR);
+  const release = (): void => {
+    try {
+      unlinkSync(path);
+    } catch {
+      // Best effort: the file may already be gone.
+    }
+  };
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      writeFileSync(path, `${process.pid}\n`, { flag: "wx" });
+      process.stderr.write(`[viber-codex-bridge] lock acquired: ${path}\n`);
+      return { path, release };
+    } catch (err) {
+      if (typeof err !== "object" || err === null || !("code" in err) || err.code !== "EEXIST") {
+        throw err;
+      }
+
+      let existingPid = Number.NaN;
+      try {
+        existingPid = Number.parseInt(readFileSync(path, "utf-8").trim(), 10);
+      } catch {
+        release();
+        continue;
+      }
+
+      if (!Number.isFinite(existingPid) || !isProcessAlive(existingPid)) {
+        release();
+        continue;
+      }
+
+      throw new BridgeShutdownError(
+        `Another viber-codex-bridge already holds the lock ${sessionId} (PID ${existingPid})`,
+        1,
+      );
+    }
+  }
+
+  throw new BridgeShutdownError(`Failed to acquire viber-codex-bridge lock ${sessionId}`, 1);
+}
+
+export function shouldHandleMessage(
+  msg: ConversationMessage,
+  ownInstanceKey: string,
+  ownPostedIds: Set<string>,
+  options: BridgeOptions,
+): boolean {
+  if (msg.id !== undefined && msg.id !== null && ownPostedIds.has(String(msg.id))) return false;
+  if (msg.sender_instance_id && msg.sender_instance_id === ownInstanceKey) return false;
+  if (typeof msg.content !== "string" || msg.content.trim().length === 0) return false;
+
+  // Human browser text is role=user; persisted voice transcripts are
+  // role=user_voice; other agents (role=channel, etc.) only when enabled.
+  if (msg.role === "user" || msg.role === "user_voice") return true;
+  return options.includeAgentMessages;
+}
+
+function senderLabel(msg: ConversationMessage): string {
+  if (msg.sender_instance_id) return `instance ${msg.sender_instance_id.slice(0, 8)}`;
+  if (msg.role) return msg.role;
+  if (msg.source) return msg.source;
+  return "unknown";
+}
+
+function buildReply(receivedContent: string, msg: ConversationMessage | undefined, options: BridgeOptions): string {
+  if (!options.echoContent) {
+    return process.env.VIBER_CODEX_BRIDGE_REPLY ??
+      "Codex bridge received the message and can reply through Viber.";
+  }
+  const sender = msg ? senderLabel(msg) : "transcription";
+  return `Codex received from ${sender}: "${receivedContent}"`;
+}
+
+function safeErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function refreshLeadSeconds(): number | undefined {
+  const raw = process.env.VIBER_REFRESH_LEAD_SECONDS;
+  if (raw === undefined) return undefined;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    process.stderr.write(`[viber-codex-bridge] invalid VIBER_REFRESH_LEAD_SECONDS=${raw}, ignoring\n`);
+    return undefined;
+  }
+  process.stderr.write(`[viber-codex-bridge] token refresh lead overridden to ${parsed}s\n`);
+  return parsed;
+}
+
+function startTokenRefresh(
+  runtime: ConversationRuntime,
+  fingerprint: string,
+  requestShutdown: (err: BridgeShutdownError) => void,
+): TokenRefreshScheduler {
+  const leadSeconds = refreshLeadSeconds();
+  const scheduler = createTokenRefreshScheduler(
+    async () => {
+      const maxAttempts = 5;
+      const headroomSeconds = 10;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          const refreshed = await refreshConversationToken(BASE_URL, runtime.id, runtime.token, fingerprint);
+          runtime.token = refreshed.conversation_token;
+          runtime.expiresAt = refreshed.expires_at;
+          process.stderr.write(`[viber-codex-bridge] token refreshed for conversation ${runtime.id}\n`);
+          return { expiresAt: refreshed.expires_at };
+        } catch (err) {
+          const retryable =
+            (err instanceof RefreshHttpError && err.retryable) ||
+            err instanceof RefreshNetworkError;
+          if (!retryable || attempt === maxAttempts) throw err;
+
+          const proposedDelay = Math.min(30 * 2 ** (attempt - 1), 120);
+          const remaining = runtime.expiresAt - Date.now() / 1000;
+          if (remaining - proposedDelay < headroomSeconds) throw err;
+          process.stderr.write(
+            `[viber-codex-bridge] token refresh attempt ${attempt} failed (${safeErrorMessage(err)}); retry in ${proposedDelay}s (${Math.round(remaining)}s until expiry)\n`,
+          );
+          await sleep(proposedDelay * 1000);
+        }
+      }
+      throw new Error("token refresh: retry loop exhausted without resolution");
+    },
+    async (err) => {
+      process.stderr.write(`[viber-codex-bridge] token refresh failed: ${safeErrorMessage(err)}\n`);
+      requestShutdown(new BridgeShutdownError("conversation token refresh failed", 3));
+    },
+    leadSeconds !== undefined ? { leadSeconds, log: (line) => process.stderr.write(`${line}\n`) } : {
+      log: (line) => process.stderr.write(`${line}\n`),
+    },
+  );
+  scheduler.start(runtime.expiresAt);
+  runtime.scheduler = scheduler;
+  return scheduler;
+}
+
+// #280 step-12: the state file is per AGENT. Several agents on one machine each own
+// their own file, so concurrent read-modify-write of a single shared JSON can't drop
+// another agent's thread entry (Codex review P2-A). An explicit
+// VIBER_CODEX_BRIDGE_STATE override still wins (single file, caller's responsibility).
+function stateFilePath(instanceId?: string, cwd: string = process.cwd()): string {
+  const override = process.env.VIBER_CODEX_BRIDGE_STATE;
+  if (override !== undefined && override.trim() !== "") return override;
+  // Full instance id in the filename (server-issued opaque hex): a truncated id
+  // could collide and reintroduce the shared-file write race this split avoids.
+  const name =
+    instanceId && instanceId.trim() !== ""
+      ? `codex-bridge-threads-${instanceId}.json`
+      : "codex-bridge-threads.json";
+  return join(dirname(authFilePath(cwd)), name);
+}
+
+// #280 step-12: the key is per (conversation, AGENT), not per conversation. With
+// several agents sharing one conversation, a conversation-only key would make them
+// resume/clobber the same Codex thread. Including the instance id gives each agent
+// its own persisted thread.
+export function stateKey(
+  projectId: number,
+  fingerprint: string,
+  conversationId: string,
+  instanceId: string,
+): string {
+  return `${projectId}:${fingerprint}:${conversationId}:${instanceId}`;
+}
+
+function readThreadState(path: string): ThreadState {
+  if (!existsSync(path)) return { schema_version: 1, threads: {} };
+  const parsed = JSON.parse(readFileSync(path, "utf-8")) as ThreadState;
+  if (parsed.schema_version !== 1 || typeof parsed.threads !== "object" || parsed.threads === null) {
+    throw new Error(`Unsupported Codex bridge state file at ${path}`);
+  }
+  return parsed;
+}
+
+function writeThreadState(path: string, state: ThreadState): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+}
+
+function extractThreadId(response: unknown): string {
+  if (
+    typeof response === "object" &&
+    response !== null &&
+    "thread" in response &&
+    typeof (response as { thread?: { id?: unknown } }).thread?.id === "string"
+  ) {
+    return (response as { thread: { id: string } }).thread.id;
+  }
+  throw new Error("Codex app-server response did not include thread.id");
+}
+
+// --- Agent permission tiers (#280 step-11) -------------------------------
+//
+// An agent's capability level is chosen at launch via VIBER_AGENT_TIER, not
+// hardcoded. One knob maps to the (sandbox, instructions) pair so the three
+// Codex call sites (thread/start, thread/resume, turn/start) cannot drift.
+//
+//   chat  (default) — answer only; no file read, no write, no shell.
+//   read            — may READ the workspace (review plans/code); no write, no shell.
+//   write           — read + write; DEFERRED behind the #252 safe-mode gate.
+//
+// A `read-only` Codex sandbox already permits reads — only the instructions
+// forbade them — so `read` keeps the read-only sandbox and just relaxes the
+// instructions. `write` would additionally need a workspace-write sandbox; it is
+// intentionally not enabled yet (falls back to `chat` with a warning).
+type AgentTier = "chat" | "read" | "write";
+
+function resolveAgentTier(): AgentTier {
+  const raw = (process.env.VIBER_AGENT_TIER ?? "chat").trim().toLowerCase();
+  if (raw === "chat" || raw === "read") return raw;
+  if (raw === "write") {
+    // #280 step-17: write enables a workspace-write sandbox — the agent can edit
+    // files and run state-changing commands WITHOUT approval. Enabled by explicit
+    // operator choice at launch (the #252 read-only gate is lifted deliberately).
+    process.stderr.write(
+      "[viber-codex-bridge] VIBER_AGENT_TIER=write — workspace-write sandbox ACTIVE: this agent can " +
+        "edit files and run state-changing commands WITHOUT approval (operator-authorized at launch).\n",
+    );
+    return "write";
+  }
+  process.stderr.write(
+    `[viber-codex-bridge] unknown VIBER_AGENT_TIER="${raw}"; falling back to "chat"\n`,
+  );
+  return "chat";
+}
+
+const VOICE_CONCISE_LINE =
+  "Keep replies concise because they are returned to a voice/text conversation.";
+
+function instructionsForTier(tier: AgentTier): string {
+  if (tier === "write") {
+    return [
+      "You are a bridge-owned Codex agent connected to Viber, in READ-WRITE mode.",
+      "You MAY read files, create/modify files within the workspace, and run commands (including state-changing ones) to carry out the user's requests.",
+      "The sandbox is workspace-write: writes are confined to the workspace and network access is blocked at the OS level.",
+      "There is NO human approval step, so be deliberate: make only the changes the user asked for, and avoid destructive commands unless explicitly requested.",
+      VOICE_CONCISE_LINE,
+    ].join("\n");
+  }
+  if (tier === "read") {
+    return [
+      "You are a bridge-owned Codex agent connected to Viber, in READ collaboration mode.",
+      "You MAY read files and run read-only commands (e.g. cat, ls, grep, sed -n) to inspect code, plans, and docs, and reason about them.",
+      "The sandbox is read-only: file writes and network access are blocked at the OS level, so any modification or network call will simply fail — do not attempt to write or modify files, and do not run state-changing or destructive commands.",
+      "If the user asks for workspace changes, explain that the bridge is in read-only mode.",
+      VOICE_CONCISE_LINE,
+    ].join("\n");
+  }
+  // chat — most restrictive (default)
+  return [
+    "You are a bridge-owned Codex agent connected to Viber for an initial persistence validation.",
+    "For now, answer and reason only. Do not run shell commands. Do not read files. Do not write or modify files.",
+    "If the user asks for workspace changes, explain that the bridge is currently in read-only validation mode.",
+    VOICE_CONCISE_LINE,
+  ].join("\n");
+}
+
+// Approval policy per tier. `read`/`write` use "never" so Codex runs its commands
+// WITHOUT a human approver (there is none on the bridge) — the SANDBOX is the real
+// guardrail (read-only blocks writes/network; workspace-write confines writes to
+// the workspace and still blocks network). `chat` keeps "on-request" (no exec anyway).
+function approvalForTier(tier: AgentTier): "never" | "on-request" {
+  return tier === "chat" ? "on-request" : "never";
+}
+
+// Codex OS sandbox per tier. `write` widens to workspace-write (edits confined to
+// the workspace, network still blocked); chat/read stay read-only.
+function sandboxForTier(tier: AgentTier): "read-only" | "workspace-write" {
+  return tier === "write" ? "workspace-write" : "read-only";
+}
+
+const AGENT_TIER: AgentTier = resolveAgentTier();
+const AGENT_INSTRUCTIONS: string = instructionsForTier(AGENT_TIER);
+const AGENT_APPROVAL_POLICY: "never" | "on-request" = approvalForTier(AGENT_TIER);
+const AGENT_SANDBOX: "read-only" | "workspace-write" = sandboxForTier(AGENT_TIER);
+
+class CodexAppServer {
+  private child: ChildProcessWithoutNullStreams;
+  private nextId = 1;
+  private stdoutBuffer = "";
+  private pending = new Map<string, PendingRequest>();
+  private turnWaiters = new Map<string, TurnWaiter>();
+
+  constructor() {
+    const codexBin = process.env.VIBER_CODEX_BIN?.trim() || "codex";
+    this.child = spawn(codexBin, ["app-server"], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    this.child.stdout.setEncoding("utf-8");
+    this.child.stderr.setEncoding("utf-8");
+    this.child.stdout.on("data", (chunk: string) => this.handleStdout(chunk));
+    this.child.stderr.on("data", (chunk: string) => {
+      process.stderr.write(`[codex-app-server] ${chunk}`);
+    });
+    this.child.on("exit", (code, signal) => {
+      const err = new Error(`Codex app-server exited (${code ?? signal ?? "unknown"})`);
+      for (const pending of this.pending.values()) pending.reject(err);
+      this.pending.clear();
+      for (const waiter of this.turnWaiters.values()) {
+        clearTimeout(waiter.timeout);
+        waiter.reject(err);
+      }
+      this.turnWaiters.clear();
+    });
+  }
+
+  async initialize(): Promise<void> {
+    await this.request("initialize", {
+      clientInfo: { name: "viber-codex-bridge", title: "Viber Codex Bridge", version: "0.1.0" },
+      capabilities: { experimentalApi: true },
+    });
+    this.notify("initialized");
+  }
+
+  async ensureThread(options: {
+    auth: AuthJson;
+    fingerprint: string;
+    conversationId: string;
+    instanceKey: string;
+    newThread: boolean;
+  }): Promise<string> {
+    const path = stateFilePath(options.instanceKey);
+    const state = readThreadState(path);
+    const key = stateKey(
+      options.auth.project_id,
+      options.fingerprint,
+      options.conversationId,
+      options.instanceKey,
+    );
+    const existing = state.threads[key]?.thread_id;
+
+    if (existing && !options.newThread) {
+      try {
+        process.stderr.write(`[viber-codex-bridge] codex: resuming persisted thread ${existing}\n`);
+        const resumed = await this.request("thread/resume", {
+          threadId: existing,
+          cwd: process.cwd(),
+          runtimeWorkspaceRoots: [process.cwd()],
+          approvalPolicy: AGENT_APPROVAL_POLICY,
+          sandbox: AGENT_SANDBOX,
+          developerInstructions: AGENT_INSTRUCTIONS,
+          excludeTurns: true,
+        });
+        return extractThreadId(resumed);
+      } catch (err) {
+        process.stderr.write(
+          `[viber-codex-bridge] codex: resume failed (${safeErrorMessage(err)}), starting a fresh thread\n`,
+        );
+      }
+    }
+
+    process.stderr.write("[viber-codex-bridge] codex: starting fresh bridge-owned thread\n");
+    const started = await this.request("thread/start", {
+      cwd: process.cwd(),
+      runtimeWorkspaceRoots: [process.cwd()],
+      approvalPolicy: AGENT_APPROVAL_POLICY,
+      sandbox: AGENT_SANDBOX,
+      developerInstructions: AGENT_INSTRUCTIONS,
+      ephemeral: false,
+      threadSource: "user",
+      sessionStartSource: options.newThread ? "clear" : "startup",
+    });
+    const threadId = extractThreadId(started);
+    state.threads[key] = {
+      thread_id: threadId,
+      conversation_id: options.conversationId,
+      project_id: options.auth.project_id,
+      client_fingerprint: options.fingerprint,
+      cwd: process.cwd(),
+      viber_instance_id: options.instanceKey,
+      updated_at: new Date().toISOString(),
+    };
+    writeThreadState(path, state);
+    process.stderr.write(`[viber-codex-bridge] codex: persisted thread ${threadId} in ${path}\n`);
+    return threadId;
+  }
+
+  async runTurn(threadId: string, content: string): Promise<string> {
+    const response = await this.request("turn/start", {
+      threadId,
+      input: [{ type: "text", text: content, text_elements: [] }],
+      cwd: process.cwd(),
+      runtimeWorkspaceRoots: [process.cwd()],
+      approvalPolicy: AGENT_APPROVAL_POLICY,
+      sandboxPolicy:
+        AGENT_SANDBOX === "workspace-write"
+          ? { type: "workspaceWrite", networkAccess: false }
+          : { type: "readOnly", networkAccess: false },
+      developerInstructions: AGENT_INSTRUCTIONS,
+      responsesapiClientMetadata: { source: "viber-codex-bridge" },
+    });
+    const turnId = this.extractTurnId(response);
+    return await this.waitForTurn(threadId, turnId);
+  }
+
+  close(): void {
+    this.child.kill();
+  }
+
+  private request(method: string, params: unknown): Promise<unknown> {
+    const id = this.nextId++;
+    const payload = JSON.stringify({ id, method, params });
+    return new Promise((resolve, reject) => {
+      this.pending.set(String(id), { resolve, reject });
+      this.child.stdin.write(`${payload}\n`, (err) => {
+        if (err) {
+          this.pending.delete(String(id));
+          reject(err);
+        }
+      });
+    });
+  }
+
+  private notify(method: string, params?: unknown): void {
+    const msg = params === undefined ? { method } : { method, params };
+    this.child.stdin.write(`${JSON.stringify(msg)}\n`);
+  }
+
+  private handleStdout(chunk: string): void {
+    this.stdoutBuffer += chunk;
+    while (true) {
+      const newline = this.stdoutBuffer.indexOf("\n");
+      if (newline === -1) return;
+      const line = this.stdoutBuffer.slice(0, newline).trim();
+      this.stdoutBuffer = this.stdoutBuffer.slice(newline + 1);
+      if (line.length === 0) continue;
+
+      let msg: JsonRpcMessage;
+      try {
+        msg = JSON.parse(line) as JsonRpcMessage;
+      } catch (err) {
+        process.stderr.write(`[viber-codex-bridge] codex: ignored malformed JSON line: ${safeErrorMessage(err)}\n`);
+        continue;
+      }
+      this.handleMessage(msg);
+    }
+  }
+
+  private handleMessage(msg: JsonRpcMessage): void {
+    if (msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+      const pending = this.pending.get(String(msg.id));
+      if (!pending) return;
+      this.pending.delete(String(msg.id));
+      if (msg.error) pending.reject(new Error(msg.error.message ?? JSON.stringify(msg.error)));
+      else pending.resolve(msg.result);
+      return;
+    }
+
+    if (msg.id !== undefined && msg.method) {
+      this.handleServerRequest(msg);
+      return;
+    }
+
+    if (msg.method === "item/agentMessage/delta") {
+      const params = msg.params as { threadId?: string; turnId?: string; delta?: string };
+      const waiter = this.turnWaiters.get(`${params.threadId}:${params.turnId}`);
+      if (waiter && typeof params.delta === "string") waiter.deltas.push(params.delta);
+      return;
+    }
+
+    if (msg.method === "turn/completed") {
+      const params = msg.params as { threadId?: string; turn?: { id?: string; status?: unknown; error?: unknown } };
+      const turnId = params.turn?.id;
+      const waiter = this.turnWaiters.get(`${params.threadId}:${turnId}`);
+      if (!waiter) return;
+      clearTimeout(waiter.timeout);
+      this.turnWaiters.delete(`${params.threadId}:${turnId}`);
+      const status = params.turn?.status;
+      if (
+        status === "failed" ||
+        (typeof status === "object" && status !== null && "type" in status && status.type === "failed")
+      ) {
+        waiter.reject(new Error(`Codex turn failed: ${JSON.stringify(params.turn?.error ?? status)}`));
+      } else {
+        waiter.resolve(waiter.deltas.join("").trim());
+      }
+      return;
+    }
+
+    if (msg.method === "error" || msg.method === "warning" || msg.method === "configWarning") {
+      process.stderr.write(`[viber-codex-bridge] codex ${msg.method}: ${JSON.stringify(msg.params)}\n`);
+    }
+  }
+
+  private handleServerRequest(msg: JsonRpcMessage): void {
+    process.stderr.write(`[viber-codex-bridge] codex: auto-declining server request ${msg.method}\n`);
+    let result: unknown = { decision: "decline" };
+    if (msg.method === "item/commandExecution/requestApproval") result = { decision: "decline" };
+    else if (msg.method === "item/fileChange/requestApproval") result = { decision: "decline" };
+    else if (msg.method === "execCommandApproval" || msg.method === "applyPatchApproval") {
+      result = { decision: "denied" };
+    }
+    this.child.stdin.write(`${JSON.stringify({ id: msg.id, result })}\n`);
+  }
+
+  private extractTurnId(response: unknown): string {
+    if (
+      typeof response === "object" &&
+      response !== null &&
+      "turn" in response &&
+      typeof (response as { turn?: { id?: unknown } }).turn?.id === "string"
+    ) {
+      return (response as { turn: { id: string } }).turn.id;
+    }
+    throw new Error("Codex app-server response did not include turn.id");
+  }
+
+  private waitForTurn(threadId: string, turnId: string): Promise<string> {
+    const key = `${threadId}:${turnId}`;
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.turnWaiters.delete(key);
+        reject(new Error("Codex turn timed out after 10 minutes"));
+      }, 10 * 60 * 1000);
+      this.turnWaiters.set(key, { threadId, turnId, deltas: [], resolve, reject, timeout });
+    });
+  }
+}
+
+async function postBridgeReply(
+  runtime: ConversationRuntime,
+  text: string,
+  ownPostedIds: Set<string>,
+): Promise<void> {
+  let result;
+  try {
+    result = await postMessage(BASE_URL, runtime.id, runtime.token, text);
+  } catch (err) {
+    // A 401 here means the conversation token expired and the refresh path
+    // failed; surface it as a controlled shutdown (exit code 3) so the
+    // per-message catch in sseLoop does not swallow it as a generic failure.
+    if (err instanceof ConversationTokenExpiredError) {
+      throw new BridgeShutdownError("conversation token expired", 3);
+    }
+    throw err;
+  }
+  if (!result.ok) {
+    throw new Error(`postMessage failed: ${result.detail}`);
+  }
+  ownPostedIds.add(String(result.message_id));
+  process.stderr.write(`[viber-codex-bridge] posted reply: ${result.message_id}\n`);
+}
+
+async function acquireBridgeInstance(
+  baseUrl: string,
+  auth: AuthJson,
+  fingerprint: string,
+  label: string,
+  options: BridgeOptions,
+): Promise<{ instance_token: string; instance_key: string }> {
+  if (process.env.VIBER_INSTANCE_TOKEN !== undefined && process.env.VIBER_INSTANCE_TOKEN.trim() !== "") {
+    process.stderr.write("[viber-codex-bridge] instance: using VIBER_INSTANCE_TOKEN from env\n");
+    return acquireInstance(baseUrl, auth, fingerprint);
+  }
+
+  if (options.reuseAuthInstance) {
+    process.stderr.write(
+      "[viber-codex-bridge] instance: reusing auth file instance because --reuse-auth-instance was set\n",
+    );
+    return acquireInstance(baseUrl, auth, fingerprint);
+  }
+
+  process.stderr.write("[viber-codex-bridge] instance: registering fresh bridge instance\n");
+  const reg = await registerInstance(baseUrl, auth.project_id, auth.project_token, fingerprint, label, "codex");
+  process.stderr.write(`[viber-codex-bridge] instance: registered fresh bridge instance (id=${reg.instance_id})\n`);
+  return { instance_token: reg.instance_token, instance_key: reg.instance_id };
+}
+
+function loadBridgeAuthAndFingerprint(): { auth: AuthJson; fingerprint: string } {
+  const auth = loadAuth();
+  const fingerprint = clientFingerprint(process.cwd());
+  if (fingerprint !== auth.client_fingerprint) {
+    throw new Error(
+      `Folder fingerprint mismatch — ${authFilePath()} was issued for a different machine/folder.`,
+    );
+  }
+  return { auth, fingerprint };
+}
+
+async function acquireTargetConversation(
+  targetConversationId: string,
+  options: BridgeOptions,
+  auth: AuthJson,
+  fingerprint: string,
+): Promise<{
+  minted: ConversationMintResponse;
+  fingerprint: string;
+  instanceKey: string;
+  auth: AuthJson;
+  bridgeLock: BridgeLock;
+}> {
+  mkdirSync(LOCK_DIR, { recursive: true });
+
+  const label = process.env.VIBER_CODEX_BRIDGE_LABEL ?? `Codex bridge • ${defaultLabel(process.cwd())}`;
+  const acquired = await acquireBridgeInstance(BASE_URL, auth, fingerprint, label, options);
+  let instanceToken = acquired.instance_token;
+  let instanceKey = acquired.instance_key;
+  let sessionPath = sessionFilePath(BASE_URL, `${instanceKey}:codex:${targetConversationId}`, LOCK_DIR);
+  // #280 step-12: take the per-agent lock BEFORE reattach. reattach rotates the
+  // per-membership token, so a losing duplicate launch of the SAME identity must be
+  // stopped before it can rotate the winner's token (Codex review P2-B).
+  let bridgeLock = acquireBridgeLock(BASE_URL, fingerprint, `codex-agent:${instanceKey}`);
+
+  process.stderr.write(
+    `[viber-codex-bridge] joining conversation ${targetConversationId} (project=${auth.project_id}, session=${sessionPath})\n`,
+  );
+
+  // Release the lock on ANY failure after acquisition — success/401-recovery return
+  // it to main() (which releases it in its finally); only thrown escapes leak it.
+  try {
+   try {
+    const minted = await reattachConversation(
+      BASE_URL,
+      auth.project_id,
+      instanceToken,
+      fingerprint,
+      targetConversationId,
+    );
+    writeHandle(sessionPath, minted.conversation_id);
+    process.stderr.write(`[viber-codex-bridge] join OK, conv_id=${minted.conversation_id}\n`);
+    return { minted, fingerprint, instanceKey, auth, bridgeLock };
+  } catch (err) {
+    if (err instanceof ConversationMintError && err.status === 401) {
+      process.stderr.write(
+        "[viber-codex-bridge] instance token rejected (401 revoked) — re-registering a fresh instance once\n",
+      );
+      const reg = await registerInstance(BASE_URL, auth.project_id, auth.project_token, fingerprint, label);
+      instanceToken = reg.instance_token;
+      instanceKey = reg.instance_id;
+      // Identity changed → re-key the lock onto the new instance. Acquire the new
+      // lock BEFORE releasing the old one: if acquisition throws, the old lock is
+      // still held and the outer catch releases exactly it (no dangling reference).
+      const reLock = acquireBridgeLock(BASE_URL, fingerprint, `codex-agent:${instanceKey}`);
+      bridgeLock.release();
+      bridgeLock = reLock;
+      sessionPath = sessionFilePath(BASE_URL, `${instanceKey}:codex:${targetConversationId}`, LOCK_DIR);
+      const minted = await reattachConversation(
+        BASE_URL,
+        auth.project_id,
+        instanceToken,
+        fingerprint,
+        targetConversationId,
+      );
+      writeHandle(sessionPath, minted.conversation_id);
+      process.stderr.write(`[viber-codex-bridge] join OK, conv_id=${minted.conversation_id}\n`);
+      return { minted, fingerprint, instanceKey, auth, bridgeLock };
+    }
+    throw err;
+   }
+  } catch (fatal) {
+    bridgeLock.release();
+    throw fatal;
+  }
+}
+
+async function sseLoop(
+  minted: ConversationMintResponse,
+  runtime: ConversationRuntime,
+  fingerprint: string,
+  ownInstanceKey: string,
+  codex: CodexAppServer,
+  codexThreadId: string,
+  options: BridgeOptions,
+  signal: AbortSignal,
+): Promise<void> {
+  const sseUrl = buildSseUrl(minted.ws_url, minted.conversation_id);
+  const ownPostedIds = new Set<string>();
+  const handledIds = new Set<string>();
+  // First reconcile pass only SEEDS (marks existing messages as seen without
+  // replying) so the bridge doesn't answer the whole history when it joins.
+  let primed = false;
+
+  // Reply to one inbound message exactly once. Shared by the live SSE handler
+  // and the reconnect catch-up; `handledIds` makes it idempotent. Returns true
+  // when options.once is satisfied (caller should stop).
+  async function handleInboundMessage(msg: ConversationMessage): Promise<boolean> {
+    const idStr = msg.id !== undefined && msg.id !== null ? String(msg.id) : undefined;
+    if (idStr && handledIds.has(idStr)) return false;
+    if (!shouldHandleMessage(msg, ownInstanceKey, ownPostedIds, options)) {
+      if (idStr) handledIds.add(idStr); // skip decision is final — role won't change
+      return false;
+    }
+    if (idStr) handledIds.add(idStr);
+    process.stderr.write(`[viber-codex-bridge] message received: ${msg.content!.slice(0, 80)}\n`);
+    try {
+      const reply = options.echoContent
+        ? buildReply(msg.content!, msg, options)
+        : await codexReply(codex, codexThreadId, msg.content!);
+      await postBridgeReply(runtime, reply, ownPostedIds);
+    } catch (err) {
+      if (err instanceof BridgeShutdownError) throw err;
+      process.stderr.write(`[viber-codex-bridge] failed to handle message: ${safeErrorMessage(err)}\n`);
+    }
+    return options.once === true;
+  }
+
+  // On every (re)connect the conversation SSE has NO replay, so re-read the
+  // message list and process anything missed while disconnected (#280 step-06).
+  // The first pass seeds handledIds without replying (don't answer history).
+  async function reconcileMessages(): Promise<boolean> {
+    let msgs: Array<Record<string, unknown>>;
+    try {
+      msgs = await fetchMessages(minted.ws_url, minted.conversation_id, runtime.token);
+    } catch (err) {
+      if (err instanceof ConversationTokenExpiredError) throw err;
+      process.stderr.write(`[viber-codex-bridge] catch-up fetch failed: ${safeErrorMessage(err)}\n`);
+      return false;
+    }
+    for (const raw of msgs) {
+      const msg = raw as unknown as ConversationMessage;
+      if (!primed) {
+        const idStr = msg.id !== undefined && msg.id !== null ? String(msg.id) : undefined;
+        if (idStr) handledIds.add(idStr);
+        continue;
+      }
+      if (await handleInboundMessage(msg)) return true;
+    }
+    if (!primed) {
+      primed = true;
+      process.stderr.write(`[viber-codex-bridge] primed: ${handledIds.size} existing message(s) marked seen\n`);
+    }
+    return false;
+  }
+
+  while (true) {
+    try {
+      if (signal.aborted) throw signal.reason;
+      const requestHeaders = headers(runtime.token, fingerprint);
+      requestHeaders["Accept"] = "text/event-stream";
+      process.stderr.write(`[viber-codex-bridge] connecting to SSE: ${sseUrl}\n`);
+
+      const resp = await fetch(sseUrl, { headers: requestHeaders, signal });
+      if (resp.status === 401) throw new ConversationTokenExpiredError();
+      if (!resp.ok || !resp.body) throw new Error(`SSE connection failed: HTTP ${resp.status}`);
+
+      process.stderr.write("[viber-codex-bridge] SSE connected\n");
+      // Catch up on anything published while we were (re)connecting before we
+      // start reading live events — the SSE stream has no replay.
+      if (await reconcileMessages()) return;
+      const reader = resp.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+
+        while (true) {
+          const eventEnd = buffer.indexOf("\n\n");
+          if (eventEnd === -1) break;
+
+          const eventBlock = buffer.slice(0, eventEnd);
+          buffer = buffer.slice(eventEnd + 2);
+          if (eventBlock.startsWith(":")) continue;
+
+          let eventType = "";
+          let data = "";
+          for (const line of eventBlock.split("\n")) {
+            if (line.startsWith("event: ")) eventType = line.slice(7);
+            else if (line.startsWith("data: ")) data = line.slice(6);
+          }
+
+          if (eventType === "connected") {
+            process.stderr.write("[viber-codex-bridge] SSE stream ready\n");
+            continue;
+          }
+
+          if (eventType === "stop") {
+            process.stderr.write("[viber-codex-bridge] received stop signal, exiting\n");
+            throw new BridgeShutdownError("received stop signal", 0);
+          }
+
+          if (eventType === "transcription" && data) {
+            let item: { text?: string };
+            try {
+              item = JSON.parse(data) as { text?: string };
+            } catch (err) {
+              process.stderr.write(
+                `[viber-codex-bridge] ignored malformed transcription SSE payload: ${safeErrorMessage(err)}\n`,
+              );
+              continue;
+            }
+            if (typeof item.text === "string" && item.text.trim().length > 0) {
+              process.stderr.write(`[viber-codex-bridge] transcription received: ${item.text.slice(0, 80)}\n`);
+              try {
+                const reply = options.echoContent
+                  ? buildReply(item.text, undefined, options)
+                  : await codexReply(codex, codexThreadId, item.text);
+                await postBridgeReply(runtime, reply, ownPostedIds);
+              } catch (err) {
+                if (err instanceof BridgeShutdownError) throw err;
+                process.stderr.write(`[viber-codex-bridge] failed to handle transcription: ${safeErrorMessage(err)}\n`);
+              }
+              if (options.once) return;
+            }
+            continue;
+          }
+
+          if (eventType === "message" && data) {
+            let msg: ConversationMessage;
+            try {
+              msg = JSON.parse(data) as ConversationMessage;
+            } catch (err) {
+              process.stderr.write(
+                `[viber-codex-bridge] ignored malformed message SSE payload: ${safeErrorMessage(err)}\n`,
+              );
+              continue;
+            }
+            if (await handleInboundMessage(msg)) return;
+          }
+        }
+      }
+
+      process.stderr.write("[viber-codex-bridge] SSE stream ended, reconnecting...\n");
+    } catch (err) {
+      if (err instanceof BridgeShutdownError) throw err;
+      if (signal.aborted) {
+        const reason = signal.reason;
+        if (reason instanceof BridgeShutdownError) throw reason;
+        throw new BridgeShutdownError("bridge shutdown requested", 0);
+      }
+      if (err instanceof ConversationTokenExpiredError) {
+        process.stderr.write("[viber-codex-bridge] conversation token expired, exiting\n");
+        throw new BridgeShutdownError("conversation token expired", 3);
+      }
+      process.stderr.write(`[viber-codex-bridge] SSE failed: ${String(err)}, retrying in 2s...\n`);
+      await sleep(2000);
+    }
+  }
+}
+
+async function codexReply(codex: CodexAppServer, threadId: string, content: string): Promise<string> {
+  const reply = await codex.runTurn(threadId, content);
+  if (reply.length > 0) return reply;
+  throw new Error("Codex completed the turn but returned an empty reply.");
+}
+
+/**
+ * Await-invite mode (#280 step-03/step-20): acquire the instance, then run a
+ * PERSISTENT control stream and resolve on the first server-pushed `join`. The
+ * stream is kept open for the agent's whole life (returned as `controlStream`)
+ * so server-side presence keeps seeing it online and re-invitable — closing it
+ * after the first join is the bug step-20 fixes (Codex P1-3). A `stop` (revoke)
+ * or 401 aborts the bridge via the shutdown controller; transient drops reconnect
+ * with backoff inside the runner.
+ */
+export async function acquireConversationViaInvite(
+  options: BridgeOptions,
+  auth: AuthJson,
+  fingerprint: string,
+  shutdown: AbortController,
+): Promise<{
+  minted: ConversationMintResponse;
+  instanceKey: string;
+  bridgeLock: BridgeLock;
+  controlStream: PersistentControlStream;
+}> {
+  mkdirSync(LOCK_DIR, { recursive: true });
+  const label = process.env.VIBER_CODEX_BRIDGE_LABEL ?? `Codex bridge • ${defaultLabel(process.cwd())}`;
+  const acquired = await acquireBridgeInstance(BASE_URL, auth, fingerprint, label, options);
+  const instanceKey = acquired.instance_key;
+  // #280 step-12: per-agent lock, held for the whole wait + lifetime (returned to
+  // main()). Two processes with the SAME identity can't both await an invite.
+  const bridgeLock = acquireBridgeLock(BASE_URL, fingerprint, `codex-agent:${instanceKey}`);
+  process.stderr.write(
+    `[viber-codex-bridge] await-invite: waiting for a pushed join on control stream (instance ${instanceKey.slice(0, 8)})\n`,
+  );
+
+  const controlStream = runPersistentControlStream(
+    {
+      baseUrl: BASE_URL,
+      instanceId: instanceKey,
+      instanceToken: acquired.instance_token,
+      signal: shutdown.signal,
+    },
+    {
+      log: (m) => process.stderr.write(m),
+      onJoin: (minted) => {
+        const sessionPath = sessionFilePath(BASE_URL, `${instanceKey}:codex:${minted.conversation_id}`, LOCK_DIR);
+        writeHandle(sessionPath, minted.conversation_id);
+      },
+      // A revoke / 401 that arrives AFTER the first join (mid-conversation) must
+      // still stop the bridge — abort the shutdown controller the sseLoop watches.
+      onStop: (reason) => {
+        if (shutdown.signal.aborted) return;
+        shutdown.abort(
+          reason === "unauthorized"
+            ? new BridgeShutdownError("instance token revoked or invalid", 3)
+            : new BridgeShutdownError("instance revoked", 0),
+        );
+      },
+    },
+  );
+
+  try {
+    const minted = await controlStream.firstJoin;
+    process.stderr.write(
+      `[viber-codex-bridge] await-invite: joined ${minted.conversation_id} via pushed invite (control stream stays open)\n`,
+    );
+    return { minted, instanceKey, bridgeLock, controlStream };
+  } catch (err) {
+    // First-join never arrived: revoke / 401 / abort. The runner's loop has
+    // already returned for each of these (it settles firstJoin's rejection at the
+    // same point it exits), so observe `done` to avoid an unhandled background
+    // promise, then release the lock (the success path returns it to main()).
+    await controlStream.done.catch(() => {});
+    bridgeLock.release();
+    if (err instanceof ControlStreamStopped) throw new BridgeShutdownError("instance revoked", 0);
+    if (err instanceof ControlStreamAuthError) {
+      throw new BridgeShutdownError("instance token revoked or invalid", 3);
+    }
+    if (shutdown.signal.aborted) throw new BridgeShutdownError("bridge shutdown requested", 0);
+    throw err;
+  }
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
+  const options = parseArgs(argv);
+  let runtime: ConversationRuntime | null = null;
+  let codex: CodexAppServer | null = null;
+  let bridgeLock: BridgeLock | null = null;
+  let controlStream: PersistentControlStream | null = null;
+  const shutdown = new AbortController();
+
+  try {
+    const { auth, fingerprint } = loadBridgeAuthAndFingerprint();
+    let minted: ConversationMintResponse;
+    let instanceKey: string;
+    if (options.awaitInvite) {
+      // #280 step-03: no hand-carried conversation id — the server pushes it.
+      // The control stream stays open for life (step-20) → keep its handle.
+      const res = await acquireConversationViaInvite(options, auth, fingerprint, shutdown);
+      minted = res.minted;
+      instanceKey = res.instanceKey;
+      bridgeLock = res.bridgeLock;
+      controlStream = res.controlStream;
+    } else {
+      const res = await acquireTargetConversation(
+        options.conversationId,
+        options,
+        auth,
+        fingerprint,
+      );
+      minted = res.minted;
+      instanceKey = res.instanceKey;
+      bridgeLock = res.bridgeLock;
+    }
+    // #280 step-12: the lock (acquired inside the helpers above, per AGENT / instance
+    // id, BEFORE any token-rotating reattach) lets multiple agents share one
+    // conversation while still blocking a double-launch of the same identity.
+    runtime = {
+      id: minted.conversation_id,
+      token: minted.conversation_token,
+      expiresAt: minted.expires_at,
+    };
+    startTokenRefresh(runtime, fingerprint, (err) => {
+      if (!shutdown.signal.aborted) shutdown.abort(err);
+    });
+    process.stderr.write(
+      `[viber-codex-bridge] ready: joined ${minted.conversation_id} as instance ${instanceKey.slice(0, 8)}\n`,
+    );
+
+    codex = new CodexAppServer();
+    await codex.initialize();
+    const codexThreadId = await codex.ensureThread({
+      auth,
+      fingerprint,
+      conversationId: minted.conversation_id,
+      instanceKey,
+      newThread: options.newThread,
+    });
+    process.stderr.write(
+      `[viber-codex-bridge] codex safety: tier=${AGENT_TIER}, sandbox=${AGENT_SANDBOX}, approvalPolicy=${AGENT_APPROVAL_POLICY}, network=false, ` +
+        `instructions=${
+          AGENT_TIER === "write"
+            ? "read+write/run commands (workspace)"
+            : AGENT_TIER === "read"
+              ? "read+read-only commands/no write"
+              : "no shell/no file read/write"
+        }\n`,
+    );
+    process.stderr.write(`[viber-codex-bridge] codex ready: thread ${codexThreadId}\n`);
+    await sseLoop(minted, runtime, fingerprint, instanceKey, codex, codexThreadId, options, shutdown.signal);
+  } finally {
+    runtime?.scheduler?.cancel();
+    // Stop the persistent control stream and wait for its loop to exit so it
+    // doesn't outlive the process (step-20). Abort is idempotent.
+    if (!shutdown.signal.aborted) shutdown.abort();
+    await controlStream?.done.catch(() => {});
+    codex?.close();
+    bridgeLock?.release();
+  }
+}
+
+if (import.meta.main) {
+  try {
+    await main();
+  } catch (err) {
+    process.stderr.write(`[viber-codex-bridge] ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(err instanceof BridgeShutdownError ? err.exitCode : 1);
+  }
+}