viber-channel 0.5.3 → 0.7.0

package/lib/dm_stream.ts

@@ -0,0 +1,287 @@
+/**
+ * dm_stream — consume an agent↔agent DM conversation's SSE stream (#288 step-04).
+ *
+ * When the control stream pushes a `join` (a peer opened a DM with us, step-02),
+ * the channel runs ONE of these per DM, IN PARALLEL with the main conversation
+ * SSE — coexistence, not takeover (the reviewed step-04 decision): the main
+ * conversation keeps working while DMs are surfaced alongside it.
+ *
+ * This is intentionally narrow: it only forwards `message` events to `onMessage`
+ * (the caller maps them to a Claude notification with provenance). `stop` ends
+ * the stream; transient drops reconnect with backoff; a 401 ends it (the DM
+ * token expired — the peer can re-open the DM, which re-pushes a fresh join).
+ *
+ * Side-effect-free and runtime-agnostic so it can be unit-tested with a mock
+ * fetch — mirrors the shape of control_stream.ts.
+ */
+import { cfAccessHeaders } from "./cfAccess.js";
+import { buildSseUrl } from "./urls.js";
+import { ConversationTokenExpiredError, fetchMessages } from "./messages.js";
+
+/** A conversation message as it arrives on the SSE `message` event. */
+export interface DmMessage {
+  content: string;
+  id?: string;
+  source?: string;
+  sender_instance_id?: string | null;
+  artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
+}
+
+/** Signature of the catch-up fetch (mirrors messages.ts `fetchMessages`). */
+export type FetchMessagesFn = (
+  baseUrl: string,
+  conversationId: string,
+  conversationToken: string,
+) => Promise<Array<Record<string, unknown>>>;
+
+export interface DmStreamOptions {
+  wsUrl: string;
+  conversationId: string;
+  conversationToken: string;
+  onMessage: (msg: DmMessage) => void | Promise<void>;
+  log?: (msg: string) => void;
+  signal?: AbortSignal;
+  /** Backoff before reconnecting after a transient drop. Default 2000ms. */
+  reconnectDelayMs?: number;
+  /**
+   * Cap on CONSECUTIVE connection errors before giving up (#291 step-04). A
+   * clean end (normal SSE recycle) resets the counter, so a healthy stream that
+   * recycles forever never trips it; only a persistent failure (5xx/network)
+   * does. When the cap is hit the stream stops — the peer re-opening the DM
+   * re-pushes a fresh join, so it is not a permanent dead end. Default 8.
+   */
+  maxConsecutiveErrors?: number;
+  /** Injectable for tests; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /**
+   * Injectable catch-up fetch; defaults to messages.ts `fetchMessages`. On each
+   * (re)connect the DM SSE has NO replay, so we re-read the message list and
+   * forward anything published while we were disconnected (#291 step-03).
+   */
+  fetchMessagesImpl?: FetchMessagesFn;
+}
+
+/** 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 });
+  });
+}
+
+/**
+ * Forward one message to `onMessage` exactly once. `handledIds` makes this
+ * idempotent across the catch-up fetch AND the live SSE (a message can arrive
+ * by both paths around a reconnect) — dedup keys on the message id, coerced to
+ * a string so a numeric API id and a string SSE id match (#291 review, Codex).
+ *
+ * Unlike the codex bridge, dm_stream does NOT prime/seed history: a DM is
+ * freshly opened by the peer, so the message that TRIGGERED the join must be
+ * delivered, not swallowed (#291 prime-on-join). Own messages are filtered
+ * downstream in the onMessage handler (self-echo), so forwarding all unseen
+ * messages here is safe.
+ */
+async function forwardMessage(
+  opts: DmStreamOptions,
+  handledIds: Set<string>,
+  msg: DmMessage,
+): Promise<void> {
+  const idStr =
+    msg.id !== undefined && msg.id !== null && String(msg.id).length > 0
+      ? String(msg.id)
+      : undefined;
+  if (idStr && handledIds.has(idStr)) return; // already forwarded (live or catch-up)
+  // Content guard BEFORE consuming the id: a content-less payload must not burn
+  // its id in handledIds, or a later (correctly-populated) catch-up of the same
+  // id would be suppressed forever (review: Opus #4).
+  if (!msg.content) return;
+  // Normalize id to a string so downstream meta (message_id) is set consistently
+  // regardless of whether it arrived as a number (GET) or string (SSE).
+  const normalized: DmMessage = idStr ? { ...msg, id: idStr } : msg;
+  // onMessage errors must NOT look like a connection failure (which would
+  // trigger an endless fast reconnect) — catch them separately. Mark the id
+  // handled ONLY after a successful delivery: at-least-once beats at-most-once
+  // for a delivery-reliability fix, so a transient handler failure is retried on
+  // the next catch-up rather than silently dropped (review: Codex exactly-once).
+  try {
+    await opts.onMessage(normalized);
+    if (idStr) handledIds.add(idStr);
+  } catch (handlerErr) {
+    opts.log?.(
+      `[dm-stream] onMessage handler error: ${handlerErr instanceof Error ? handlerErr.message : String(handlerErr)}\n`,
+    );
+  }
+}
+
+/**
+ * Catch up on messages published before/while we were (re)connecting. Runs
+ * AFTER the SSE subscription is established (resp.ok) but BEFORE reading live
+ * events, mirroring the codex bridge: the subscription is registered server-side
+ * by the time the response resolves, so any message published between this fetch
+ * and the first live read is still delivered on the stream — `handledIds` dedups
+ * the overlap. A 401 here means the DM token expired → surface as a terminal
+ * DmStreamAuthError (same as the SSE 401). Other fetch failures are logged and
+ * swallowed (the live stream may still deliver).
+ */
+async function catchUp(opts: DmStreamOptions, handledIds: Set<string>): Promise<void> {
+  const doFetch = opts.fetchMessagesImpl ?? fetchMessages;
+  let msgs: Array<Record<string, unknown>>;
+  try {
+    msgs = await doFetch(opts.wsUrl, opts.conversationId, opts.conversationToken);
+  } catch (err) {
+    if (err instanceof ConversationTokenExpiredError) throw new DmStreamAuthError();
+    opts.log?.(
+      `[dm-stream] ${opts.conversationId} catch-up fetch failed: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return;
+  }
+  for (const raw of msgs) {
+    // Abort is terminal: this DM session ends here. Any ids already added to
+    // handledIds are intentionally dropped — a future DM uses a fresh
+    // runDmStream with its own handledIds (review: Opus #2).
+    if (opts.signal?.aborted) return;
+    await forwardMessage(opts, handledIds, raw as unknown as DmMessage);
+  }
+}
+
+/**
+ * One SSE connection attempt: yields each parsed `message` payload until the
+ * stream ends, `stop` arrives, or the signal aborts. Returns "stop" if the
+ * server signalled stop, "end" on a clean close (caller reconnects), and throws
+ * on 401 (token expired) or connection failure. `handledIds` is shared across
+ * reconnects so catch-up and live delivery stay idempotent.
+ */
+async function consumeOnce(
+  opts: DmStreamOptions,
+  handledIds: Set<string>,
+): Promise<"stop" | "end"> {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const url = buildSseUrl(opts.wsUrl, opts.conversationId);
+  const resp = await doFetch(url, {
+    headers: {
+      Authorization: `Bearer ${opts.conversationToken}`,
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache",
+      ...cfAccessHeaders(),
+    },
+    signal: opts.signal,
+  });
+  if (resp.status === 401) throw new DmStreamAuthError();
+  if (!resp.ok || !resp.body) {
+    throw new Error(`DM stream connection failed: HTTP ${resp.status}`);
+  }
+
+  // Subscription is live → replay anything missed before reading live events.
+  await catchUp(opts, handledIds);
+
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) return "end";
+      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);
+        if (block.startsWith(":")) continue; // keepalive comment
+
+        let event = "";
+        const dataLines: string[] = [];
+        for (const line of block.split("\n")) {
+          if (line.startsWith(":")) continue; // per-line comment / keepalive
+          if (line.startsWith("event:")) event = line.slice(6).trimStart();
+          // SSE allows multiple `data:` lines per event → join with "\n".
+          else if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+        }
+        if (event === "stop") return "stop";
+        const data = dataLines.join("\n");
+        if (event !== "message" || !data) continue;
+        let msg: DmMessage | null = null;
+        try {
+          msg = JSON.parse(data) as DmMessage;
+        } catch {
+          opts.log?.(`[dm-stream] ignored malformed message payload\n`);
+        }
+        if (msg) await forwardMessage(opts, handledIds, msg);
+      }
+    }
+  } finally {
+    try {
+      await reader.cancel();
+    } catch {
+      /* already closed / aborted */
+    }
+  }
+}
+
+/** Raised when the DM SSE returns 401 — the DM conversation_token has expired. */
+export class DmStreamAuthError extends Error {
+  constructor() {
+    super("DM stream unauthorized (conversation token expired)");
+    this.name = "DmStreamAuthError";
+  }
+}
+
+/**
+ * Run a DM conversation SSE for as long as it stays open, reconnecting on
+ * transient drops. Resolves when the stream terminates for good (stop, 401, or
+ * abort). Never throws — terminal reasons are logged.
+ */
+export async function runDmStream(opts: DmStreamOptions): Promise<void> {
+  const log = opts.log ?? (() => {});
+  const delayMs = opts.reconnectDelayMs ?? 2000;
+  const maxErrors = opts.maxConsecutiveErrors ?? 8;
+  const signal = opts.signal;
+  // Shared across reconnects so catch-up + live delivery dedup by message id.
+  const handledIds = new Set<string>();
+  // CONSECUTIVE connection errors. A clean end resets it to 0, so a normally
+  // recycling stream never trips the cap — only a persistent failure does.
+  let consecutiveErrors = 0;
+
+  while (true) {
+    if (signal?.aborted) return;
+    try {
+      const reason = await consumeOnce(opts, handledIds);
+      consecutiveErrors = 0; // clean end (or stop) → reset the retry budget
+      if (reason === "stop") {
+        log(`[dm-stream] ${opts.conversationId} stopped\n`);
+        return;
+      }
+      // Clean end → reconnect after backoff.
+    } catch (err) {
+      if (err instanceof DmStreamAuthError) {
+        log(`[dm-stream] ${opts.conversationId} token expired — ending (peer can re-open)\n`);
+        return;
+      }
+      if (signal?.aborted) return;
+      consecutiveErrors += 1;
+      log(
+        `[dm-stream] ${opts.conversationId}: ${err instanceof Error ? err.message : String(err)}, reconnecting (${consecutiveErrors}/${maxErrors})...\n`,
+      );
+      if (consecutiveErrors >= maxErrors) {
+        log(
+          `[dm-stream] ${opts.conversationId} giving up after ${maxErrors} consecutive errors — ending (peer can re-open)\n`,
+        );
+        return;
+      }
+    }
+    if (signal?.aborted) return;
+    await abortableDelay(delayMs, signal);
+  }
+}

package/lib/fingerprint.ts

@@ -8,7 +8,7 @@ import { realpathSync } from "node:fs";
 // computed at bootstrap time and at channel start time would never match.
 export function normalizePath(absPath: string): string {
   if (process.platform !== "win32") return absPath;
-  // C:\Users\jeanp\... → /c/Users/jeanp/...
+  // C:\Users\<user>\... → /c/Users/<user>/...
   let p = absPath.replace(/\\/g, "/");
   const driveMatch = p.match(/^([A-Za-z]):\/(.*)$/);
   if (driveMatch) {

package/lib/heartbeat.ts

@@ -0,0 +1,95 @@
+/**
+ * Instance liveness heartbeat scheduler (#311) — shared by every channel-kind
+ * client (viber-channel.ts AND viber-codex-bridge.ts).
+ *
+ * An agent (instance) is online as long as its instance heartbeat is fresh; the
+ * server's sweeper purges any instance whose heartbeat goes stale. So EVERY
+ * channel client must beat, or the sweeper will (correctly, by its rules) drop
+ * it from the Agents sidebar and signal its streams to stop. This module
+ * centralizes the beat so the two clients can't diverge.
+ *
+ * The token is read through a getter on every tick so the beat follows token
+ * refresh (#237) without re-wiring. (The legacy per-conversation heartbeat #298
+ * was removed in #315 once "Active" derived from instance liveness.)
+ */
+
+import { sendInstanceHeartbeat } from "./control_stream.ts";
+
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
+
+/**
+ * Resolve the beat interval from the environment (seconds), defaulting to 25s.
+ * Must stay comfortably under the server timeout (VIBER_CHANNEL_PRESENCE_TIMEOUT,
+ * default 90s) so a single missed beat never trips the sweeper.
+ */
+export function resolveHeartbeatIntervalMs(
+  env: Record<string, string | undefined> = process.env,
+): number {
+  const raw = env.VIBER_CHANNEL_HEARTBEAT_INTERVAL_SECONDS;
+  const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
+  return Number.isFinite(n) && n > 0 ? n * 1000 : DEFAULT_HEARTBEAT_INTERVAL_MS;
+}
+
+export interface HeartbeatHandle {
+  /** Cancel the scheduler. Idempotent. */
+  stop: () => void;
+}
+
+export interface InstanceHeartbeatOptions {
+  baseUrl: string;
+  instanceId: string;
+  /** Current instance token — read each tick (follows refresh). */
+  getInstanceToken: () => string;
+  intervalMs?: number;
+  log?: (line: string) => void;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+  /** Injectable beat fn for tests. Defaults to sendInstanceHeartbeat. */
+  beat?: (baseUrl: string, instanceId: string, instanceToken: string) => Promise<boolean>;
+}
+
+/**
+ * Start beating the INSTANCE control-stream liveness (#311). Instance-scoped: an
+ * agent is online as long as its instance heartbeat is fresh, independent of any
+ * conversation (it can be in await-invite with no conversation, or in several).
+ * Single-flight + unref'd timer so the beat never keeps a doomed process alive on
+ * its own.
+ */
+export function startInstanceHeartbeat(opts: InstanceHeartbeatOptions): HeartbeatHandle {
+  const intervalMs = opts.intervalMs ?? resolveHeartbeatIntervalMs();
+  const log = opts.log ?? ((line: string) => process.stderr.write(line));
+  const setTimer =
+    opts.setTimer ?? ((fn: () => void, ms: number) => setInterval(fn, ms) as unknown);
+  const clearTimer =
+    opts.clearTimer ??
+    ((h: unknown) => clearInterval(h as ReturnType<typeof setInterval>));
+  const beat = opts.beat ?? sendInstanceHeartbeat;
+
+  let inFlight = false;
+  const handle = setTimer(() => {
+    if (inFlight) return;
+    inFlight = true;
+    void beat(opts.baseUrl, opts.instanceId, opts.getInstanceToken())
+      .then((ok) => {
+        if (!ok) {
+          log("[viber-channel] instance heartbeat failed (will retry next interval)\n");
+        }
+      })
+      .finally(() => {
+        inFlight = false;
+      });
+  }, intervalMs);
+
+  if (handle && typeof (handle as { unref?: () => void }).unref === "function") {
+    (handle as { unref: () => void }).unref();
+  }
+
+  let stopped = false;
+  return {
+    stop: () => {
+      if (stopped) return;
+      stopped = true;
+      clearTimer(handle);
+    },
+  };
+}

package/lib/instance.ts

@@ -0,0 +1,164 @@
+/**
+ * instance.ts — acquire and use the server-issued per-instance identity (#269).
+ *
+ * The instance_token is the durable, opaque per-agent credential (D4) the channel
+ * presents to JOIN a conversation. It replaces the locally-computed
+ * client_fingerprint as the identity source. Acquisition is self-healing: an
+ * existing install with no instance_token registers one on first run with its
+ * stable project_token (no forced manual reconnect).
+ */
+import { cfAccessHeaders } from "./cfAccess.js";
+import { authFilePath, persistInstanceCredentials, type AuthJson } from "./auth.js";
+
+export interface RegisterInstanceResponse {
+  instance_id: string;
+  instance_token: string;
+}
+
+/**
+ * Non-2xx from POST /api/projects/:id/instances. `.status` lets the caller
+ * distinguish a revoked/invalid project_token (401 → reconnect) from a transient
+ * server error.
+ */
+export class InstanceRegisterError extends Error {
+  status: number;
+  constructor(status: number, detail: string) {
+    super(`Failed to register instance (HTTP ${status}): ${detail}`);
+    this.name = "InstanceRegisterError";
+    this.status = status;
+  }
+}
+
+/**
+ * POST /api/projects/:id/instances — mint a durable per-instance identity.
+ * Authenticated by the stable project_token (the orchestrator credential);
+ * the worker also wants X-Client-Fingerprint as a stored signal. Returns the
+ * opaque instance_token + its server id.
+ */
+export async function registerInstance(
+  baseUrl: string,
+  projectId: number,
+  projectToken: string,
+  fingerprint: string,
+  label?: string,
+  kind?: string,
+): Promise<RegisterInstanceResponse> {
+  const body: Record<string, string> = {};
+  if (label !== undefined) body.label = label;
+  if (kind !== undefined) body.kind = kind; // runtime: "claude-code" | "codex" | … (#280)
+  const resp = await fetch(`${baseUrl}/api/projects/${projectId}/instances`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${projectToken}`,
+      "X-Client-Fingerprint": fingerprint,
+      "Content-Type": "application/json",
+      ...cfAccessHeaders(),
+    },
+    body: JSON.stringify(body),
+  });
+  if (!resp.ok) {
+    const detail = await resp.text().catch(() => "");
+    throw new InstanceRegisterError(resp.status, detail);
+  }
+  return (await resp.json()) as RegisterInstanceResponse;
+}
+
+/**
+ * The control-plane `kind` for instances this process registers, from
+ * `VIBER_INSTANCE_KIND` (set by the spawn path — vibe-master's agent_spec, #318
+ * step-01). undefined when unset → the worker defaults to "claude-code", the
+ * historical behavior for a plain channel session. A bridge runtime (codex,
+ * gemma, hermes) sets it so its instance is tagged correctly in the control
+ * plane instead of mislabelled claude-code.
+ */
+export function instanceKindFromEnv(): string | undefined {
+  const raw = process.env.VIBER_INSTANCE_KIND;
+  return raw !== undefined && raw.trim() !== "" ? raw.trim() : undefined;
+}
+
+export interface AcquiredInstance {
+  instance_token: string;
+  /**
+   * Stable per-instance key used to namespace the conversation handle. The
+   * server `instance_id` when known; otherwise the `instance_token` itself
+   * (env-injected agents may not carry the id). Both are 1:1 with the instance
+   * and durable, so either isolates the handle correctly.
+   */
+  instance_key: string;
+  /**
+   * The real server-issued `instance_id`, or undefined when only a bare token is
+   * known (env-injected token without VIBER_INSTANCE_ID, or a persisted token with
+   * no persisted id). Distinct from `instance_key` — which may be the TOKEN as a
+   * namespacing fallback. Use THIS for the self-echo guard + sender attribution:
+   * the token must never be compared against server instance ids in
+   * `sender_instance_id`; undefined → the self-echo guard fails open (delivers everything).
+   */
+  instance_id?: string;
+}
+
+/**
+ * Resolve this channel's instance identity (#269), in priority order:
+ *   1. `VIBER_INSTANCE_TOKEN` env (orchestrator-injected, folder-less agents) —
+ *      used verbatim; `VIBER_INSTANCE_ID` keys the handle if also provided, else
+ *      the token does.
+ *   2. `VIBER_CHANNEL_LABEL` env (#280 step-25 — launcher-named agent session):
+ *      register a FRESH instance carrying that label, NOT persisted — reusing or
+ *      overwriting the shared auth.json identity would evict the user's main
+ *      channel session (the #252 instance-collision gotcha).
+ *   3. `auth.json` `instance_token` — reused (durable identity, D4 → same id).
+ *   4. register a NEW instance with the stable project_token, persisted back to
+ *      auth.json (self-healing migration — no forced manual reconnect).
+ */
+export async function acquireInstance(
+  baseUrl: string,
+  auth: AuthJson,
+  fingerprint: string,
+  log: (msg: string) => void = (m) => process.stderr.write(m),
+  cwd: string = process.cwd(),
+): Promise<AcquiredInstance> {
+  const envToken = process.env.VIBER_INSTANCE_TOKEN;
+  if (envToken !== undefined && envToken.trim() !== "") {
+    const token = envToken.trim();
+    const envId = process.env.VIBER_INSTANCE_ID;
+    const realId = envId !== undefined && envId.trim() !== "" ? envId.trim() : undefined;
+    const key = realId ?? token;
+    log(`[viber-channel] instance: using VIBER_INSTANCE_TOKEN (env-injected)\n`);
+    return { instance_token: token, instance_key: key, instance_id: realId };
+  }
+
+  const envLabel = process.env.VIBER_CHANNEL_LABEL;
+  if (envLabel !== undefined && envLabel.trim() !== "") {
+    const label = envLabel.trim();
+    log(`[viber-channel] instance: registering fresh labelled instance "${label}"\n`);
+    const reg = await registerInstance(
+      baseUrl,
+      auth.project_id,
+      auth.project_token,
+      fingerprint,
+      label,
+      instanceKindFromEnv(),
+    );
+    return { instance_token: reg.instance_token, instance_key: reg.instance_id, instance_id: reg.instance_id };
+  }
+
+  if (auth.instance_token !== undefined && auth.instance_token.trim() !== "") {
+    const realId =
+      auth.instance_id !== undefined && auth.instance_id.trim() !== "" ? auth.instance_id : undefined;
+    const key = realId ?? auth.instance_token;
+    log(`[viber-channel] instance: reusing persisted instance_token (id=${auth.instance_id ?? "?"})\n`);
+    return { instance_token: auth.instance_token, instance_key: key, instance_id: realId };
+  }
+
+  log(`[viber-channel] instance: none found — registering a new one via the project_token\n`);
+  const reg = await registerInstance(
+    baseUrl,
+    auth.project_id,
+    auth.project_token,
+    fingerprint,
+    undefined,
+    instanceKindFromEnv(),
+  );
+  persistInstanceCredentials(authFilePath(cwd), reg.instance_id, reg.instance_token, log);
+  log(`[viber-channel] instance: registered + persisted (id=${reg.instance_id})\n`);
+  return { instance_token: reg.instance_token, instance_key: reg.instance_id, instance_id: reg.instance_id };
+}

package/lib/lockfile.ts

@@ -48,3 +48,39 @@ export function lockFilePath(
     .slice(0, 8);
   return join(lockDir, `channel-${suffix}.lock`);
 }
+
+/**
+ * Resolve the lock's session-id axis from the environment (#259/#269/#293).
+ *
+ * Priority (first non-empty wins):
+ *   1. `VIBER_CHANNEL_SESSION_ID` — explicit per-launch id (launchers, #259).
+ *   2. `VIBER_INSTANCE_TOKEN` → `inst-<hash>` — env-injected fleet agents (#269).
+ *   3. `VIBER_CHANNEL_LABEL` → `label-<hash>` — a deliberate 2nd agent in the SAME
+ *      folder (#293): the label already gives it a fresh instance identity, so
+ *      derive a distinct lock from it too. Without this it would share the 1st
+ *      agent's lock and be rejected as a duplicate.
+ *   4. `""` — plain bunx client / accidental respawn: shares the per-folder lock
+ *      so accidental duplicates stay blocked (#166).
+ *
+ * Tokens/labels are HASHED (never raw) because the result is logged as a prefix.
+ */
+export function lockSessionId(env: NodeJS.ProcessEnv): string {
+  // A non-blank explicit id wins verbatim. A BLANK one (set to "" / whitespace)
+  // is treated as ABSENT so it falls through to the token/label tiers — otherwise
+  // `VIBER_CHANNEL_SESSION_ID="" + VIBER_CHANNEL_LABEL=x` would yield "" and the
+  // labelled 2nd agent would still collide (review: Opus #1 / Codex).
+  const explicit = env.VIBER_CHANNEL_SESSION_ID;
+  if (explicit !== undefined && explicit.trim() !== "") return explicit;
+  const token = env.VIBER_INSTANCE_TOKEN?.trim();
+  if (token !== undefined && token !== "") {
+    // Trim before hashing (consistent with acquireInstance, which uses the
+    // trimmed token as the identity) so the lock and the identity derive from
+    // the same effective value.
+    return `inst-${createHash("sha256").update(token).digest("hex").slice(0, 16)}`;
+  }
+  const label = env.VIBER_CHANNEL_LABEL;
+  if (label !== undefined && label.trim() !== "") {
+    return `label-${createHash("sha256").update(label.trim()).digest("hex").slice(0, 16)}`;
+  }
+  return "";
+}

package/lib/messages.ts

@@ -71,6 +71,30 @@ export function parseArtifact(raw: unknown): ParseArtifactResult {
   return { ok: true, artifact: { content, format: rawArtifact.format as ArtifactFormat } };
 }
 
+/**
+ * GET /api/conversations/:id/messages with a conversation_token (multi-auth).
+ *
+ * Used by the bridge to CATCH UP on messages it missed while its SSE was
+ * disconnected (#280 step-06): the conversation SSE has no replay, so on each
+ * reconnect the bridge re-reads the message list and processes any it hasn't
+ * seen. Returns the raw message array (ascending id) or throws on failure /
+ * `ConversationTokenExpiredError` on 401 so the caller can refresh + retry.
+ */
+export async function fetchMessages(
+  baseUrl: string,
+  conversationId: string,
+  conversationToken: string,
+): Promise<Array<Record<string, unknown>>> {
+  const resp = await fetch(`${baseUrl}/api/conversations/${conversationId}/messages`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${conversationToken}`, ...cfAccessHeaders() },
+  });
+  if (resp.status === 401) throw new ConversationTokenExpiredError();
+  if (!resp.ok) throw new Error(`fetchMessages failed: HTTP ${resp.status}`);
+  const body = (await resp.json()) as { messages?: Array<Record<string, unknown>> };
+  return Array.isArray(body.messages) ? body.messages : [];
+}
+
 export interface MessagePostSuccess {
   ok: true;
   message_id: string;
@@ -97,6 +121,13 @@ export async function postMessage(
   conversationToken: string,
   text: string,
   artifact?: Artifact,
+  /**
+   * Optional abort signal (#303 step-12.03): the codex bridge passes its stream's
+   * signal so a reply in flight is cancelled atomically if the stream is aborted
+   * (re-join / revoke / shutdown) — closing the check-then-post window that a bare
+   * `signal.aborted` guard before the call cannot.
+   */
+  signal?: AbortSignal,
 ): Promise<MessagePostResult> {
   if (!text || text.trim().length === 0) {
     return {
@@ -118,6 +149,7 @@ export async function postMessage(
         ...cfAccessHeaders(),
       },
       body: JSON.stringify(artifact ? { content: text, artifact } : { content: text }),
+      signal,
     });
   } catch (err) {
     return {