viber-channel 0.5.2 → 0.6.0

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 };
+}

package/lib/conversation.ts

@@ -1,31 +1,49 @@
 import { basename } from "node:path";
 import { cfAccessHeaders } from "./cfAccess.js";
 import { ConversationTokenExpiredError } from "./messages.js";
+import { readHandle, writeHandle } from "./channel_session.js";
 
 export interface ConversationMintResponse {
   conversation_id: string;
   conversation_token: string;
   ws_url: string;
   expires_at: number;
-  new_project_token?: string;
-  new_project_token_expires_at?: number | null;
 }
 
-export class ReverifyRequiredError extends Error {
-  url: string;
-  reason: string;
-  constructor(url: string, reason: string) {
-    super(`Re-verification required: ${reason}`);
-    this.name = "ReverifyRequiredError";
-    this.url = url;
-    this.reason = reason;
+/**
+ * Thrown by `reattachConversation` when the server returns a 409 indicating
+ * the requested conversation cannot be reattached (not found, wrong owner,
+ * wrong project, fingerprint mismatch, revoked, or race condition).
+ * The caller should fall back to `mintConversation`.
+ */
+export class ReattachFailedError extends Error {
+  /** The `detail` code from the 409 body, e.g. `reattach_not_found` */
+  code: string;
+  constructor(code: string) {
+    super(`Reattach failed: ${code}`);
+    this.name = "ReattachFailedError";
+    this.code = code;
+  }
+}
+
+/**
+ * Non-2xx from the conversation mint/join endpoint. `.status` lets the caller
+ * react to a 401 (the instance_token was revoked → re-acquire a new instance
+ * and retry, #269) distinctly from other failures.
+ */
+export class ConversationMintError extends Error {
+  status: number;
+  constructor(status: number, detail: string) {
+    super(`Failed to mint conversation token (HTTP ${status}): ${detail}`);
+    this.name = "ConversationMintError";
+    this.status = status;
   }
 }
 
 export async function mintConversation(
   baseUrl: string,
   projectId: number,
-  projectToken: string,
+  instanceToken: string,
   fingerprint: string,
   label: string,
   /**
@@ -51,7 +69,7 @@ export async function mintConversation(
   const resp = await fetch(`${baseUrl}/api/projects/${projectId}/conversations`, {
     method: "POST",
     headers: {
-      Authorization: `Bearer ${projectToken}`,
+      Authorization: `Bearer ${instanceToken}`,
       "X-Client-Fingerprint": fingerprint,
       "Content-Type": "application/json",
       ...cfAccessHeaders(),
@@ -59,21 +77,54 @@ export async function mintConversation(
     body: JSON.stringify(requestBody),
   });
   if (!resp.ok) {
-    if (resp.status === 403) {
-      let body: { type?: string; reverify_url?: string; reason?: string };
+    const detail = await resp.text();
+    throw new ConversationMintError(resp.status, detail);
+  }
+  return (await resp.json()) as ConversationMintResponse;
+}
+
+/**
+ * POST /api/projects/:id/conversations with `reattach_conversation_id` body field.
+ *
+ * On 201 returns the same `ConversationMintResponse` as `mintConversation`.
+ * On 409 throws `ReattachFailedError` with the `detail` code from the body.
+ * On any other non-2xx throws a generic Error.
+ *
+ * Reattach failure (409) is NEVER fatal — the caller should fall back to mint.
+ */
+export async function reattachConversation(
+  baseUrl: string,
+  projectId: number,
+  instanceToken: string,
+  fingerprint: string,
+  conversationId: string,
+): Promise<ConversationMintResponse> {
+  const resp = await fetch(`${baseUrl}/api/projects/${projectId}/conversations`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${instanceToken}`,
+      "X-Client-Fingerprint": fingerprint,
+      "Content-Type": "application/json",
+      ...cfAccessHeaders(),
+    },
+    body: JSON.stringify({ reattach_conversation_id: conversationId }),
+  });
+
+  if (!resp.ok) {
+    if (resp.status === 409) {
+      let code = "unknown";
       try {
-        body = (await resp.json()) as typeof body;
+        const body = (await resp.json()) as { detail?: string };
+        if (typeof body.detail === "string") code = body.detail;
       } catch {
-        body = {};
+        // ignore — code stays "unknown"
       }
-      if (body.type === "reverify_required" && typeof body.reverify_url === "string") {
-        throw new ReverifyRequiredError(body.reverify_url, body.reason ?? "unknown");
-      }
-      throw new Error(`Failed to mint conversation token (HTTP 403): ${JSON.stringify(body)}`);
+      throw new ReattachFailedError(code);
     }
     const detail = await resp.text();
-    throw new Error(`Failed to mint conversation token (HTTP ${resp.status}): ${detail}`);
+    throw new Error(`Failed to reattach conversation (HTTP ${resp.status}): ${detail}`);
   }
+
   return (await resp.json()) as ConversationMintResponse;
 }
 
@@ -179,3 +230,89 @@ export function defaultLabel(folderPath: string): string {
   const ts = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
   return `${folder} • ${ts}`;
 }
+
+/**
+ * Default reattach window in seconds — matches the server's CONVERSATION_TTL_SECONDS.
+ * A handle older than this points at an expired conversation that cannot be reattached.
+ */
+export const DEFAULT_REATTACH_WINDOW_SECONDS = 3600;
+
+/**
+ * Decide whether to reattach to the persisted conversation or mint a fresh one.
+ *
+ * Decision logic:
+ *   1. Read the handle from `sessionPath`. If present AND `now - saved_at < reattachWindowSeconds`,
+ *      attempt `reattachConversation`.
+ *   2. On reattach success: use it.
+ *   3. On `ReattachFailedError` (409): log and fall back to `mintConversation`.
+ *   4. On no/stale handle: `mintConversation` directly.
+ *   5. After either success: write the (possibly new) conversation_id back to `sessionPath`.
+ *
+ * @param sessionPath   Path returned by `sessionFilePath(baseUrl, fingerprint, sessionId, dir)`
+ * @param baseUrl       Backend base URL
+ * @param projectId     Project ID from auth.json
+ * @param instanceToken  Bearer token from auth.json
+ * @param fingerprint   Client fingerprint from auth.json
+ * @param label         Conversation label (used only when minting)
+ * @param targetConversationId  Optional target for the attach-to-project flow (passed to mint)
+ * @param reattachWindowSeconds Override the default TTL-based window (for testing / env override)
+ * @param log           Optional stderr writer, defaults to process.stderr.write
+ */
+export async function acquireConversation(
+  sessionPath: string,
+  baseUrl: string,
+  projectId: number,
+  instanceToken: string,
+  fingerprint: string,
+  label: string,
+  targetConversationId?: string | null,
+  reattachWindowSeconds: number = DEFAULT_REATTACH_WINDOW_SECONDS,
+  log: (msg: string) => void = (msg) => process.stderr.write(msg),
+): Promise<ConversationMintResponse> {
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const handle = readHandle(sessionPath);
+
+  // Branch on `handle` directly so TS narrows it to non-null inside — readHandle
+  // guarantees a finite saved_at, so handleAge is always a number here.
+  if (handle !== null) {
+    const handleAge = nowSeconds - handle.saved_at;
+    if (handleAge < reattachWindowSeconds) {
+      log(`[viber-channel] startup: session handle found (conv_id=${handle.conversation_id}, age=${handleAge}s < ${reattachWindowSeconds}s window), attempting reattach\n`);
+      try {
+        const result = await reattachConversation(baseUrl, projectId, instanceToken, fingerprint, handle.conversation_id);
+        log(`[viber-channel] startup: reattach OK, conv_id=${result.conversation_id}\n`);
+        try {
+          writeHandle(sessionPath, result.conversation_id);
+        } catch (writeErr) {
+          // Best-effort — a failed write degrades to "next startup mints fresh"
+          // rather than crashing the channel. Disk full, AV lock, read-only mount.
+          log(`[viber-channel] Warning: failed to write session handle after reattach: ${String(writeErr)}\n`);
+        }
+        return result;
+      } catch (err) {
+        // Reattach failure is NEVER fatal. Everything (ReattachFailedError 409,
+        // unexpected 5xx, network errors from a thrown fetch) falls through to
+        // mint below, which surfaces a 401 to the caller if the token is dead.
+        const reason = err instanceof ReattachFailedError ? err.code : String(err);
+        log(`[viber-channel] startup: reattach failed (${reason}), falling back to mint\n`);
+        // Fall through to mint below
+      }
+    } else {
+      log(`[viber-channel] startup: session handle stale (conv_id=${handle.conversation_id}, age=${handleAge}s >= ${reattachWindowSeconds}s window), minting fresh\n`);
+    }
+  } else {
+    log(`[viber-channel] startup: no session handle found, minting fresh\n`);
+  }
+
+  // Mint a new conversation
+  const result = await mintConversation(baseUrl, projectId, instanceToken, fingerprint, label, targetConversationId ?? null);
+  log(`[viber-channel] startup: mint OK, conv_id=${result.conversation_id}\n`);
+  try {
+    writeHandle(sessionPath, result.conversation_id);
+  } catch (writeErr) {
+    // Best-effort — a failed write degrades to "next startup mints fresh"
+    // rather than crashing the channel. Disk full, AV lock, read-only mount.
+    log(`[viber-channel] Warning: failed to write session handle after mint: ${String(writeErr)}\n`);
+  }
+  return result;
+}

package/lib/instance.ts

@@ -0,0 +1,137 @@
+/**
+ * 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;
+}
+
+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);
+    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);
+  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 };
+}