viber-channel 0.5.0 → 0.5.2

package/lib/connect.ts

@@ -19,6 +19,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { clientFingerprint } from "./fingerprint.js";
+import { cfAccessHeaders } from "./cfAccess.js";
 
 interface InitResponse {
   confirm_url: string;
@@ -141,7 +142,7 @@ export async function runConnect(
 
   const initResp = await fetch(`${baseUrl}/api/connect/${claimId}`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...cfAccessHeaders() },
     body: JSON.stringify({ client_fingerprint: fingerprint }),
   });
   if (!initResp.ok) {
@@ -158,7 +159,7 @@ export async function runConnect(
   const deadline = Date.now() + MAX_POLL_DURATION_MS;
   while (Date.now() < deadline) {
     await sleep(POLL_INTERVAL_MS);
-    const pollResp = await fetch(pollUrl);
+    const pollResp = await fetch(pollUrl, { headers: cfAccessHeaders() });
     if (!pollResp.ok) {
       const body = await pollResp.text().catch(() => "");
       throw new Error(`Poll failed (HTTP ${pollResp.status}): ${body}`);

package/lib/conversation.ts

@@ -1,5 +1,6 @@
 import { basename } from "node:path";
 import { cfAccessHeaders } from "./cfAccess.js";
+import { ConversationTokenExpiredError } from "./messages.js";
 
 export interface ConversationMintResponse {
   conversation_id: string;
@@ -76,6 +77,100 @@ export async function mintConversation(
   return (await resp.json()) as ConversationMintResponse;
 }
 
+export interface RefreshTokenResponse {
+  conversation_token: string;
+  expires_at: number;
+}
+
+/**
+ * HTTP failure from /refresh-token (any non-401 non-2xx). `.retryable` lets
+ * the scheduler distinguish a transient server hiccup (5xx, 408, 409) from a
+ * permanent state mismatch (4xx other than 401), so it can back off and try
+ * again instead of immediately ending the channel.
+ */
+export class RefreshHttpError extends Error {
+  status: number;
+  detail: string;
+  retryable: boolean;
+  constructor(status: number, detail: string) {
+    super(`Refresh failed (HTTP ${status}): ${detail}`);
+    this.name = "RefreshHttpError";
+    this.status = status;
+    this.detail = detail;
+    // 5xx, 408 (timeout), 409 (concurrent-refresh race) — server/transient.
+    // 4xx others (403 fingerprint mismatch, etc.) are permanent.
+    this.retryable = status >= 500 || status === 408 || status === 409;
+  }
+}
+
+/**
+ * Wrapper for `fetch` failures (DNS, connection reset, TLS, etc.). Always
+ * retryable — by definition we never got a server response to classify.
+ */
+export class RefreshNetworkError extends Error {
+  cause: unknown;
+  retryable: true = true as const;
+  constructor(cause: unknown) {
+    super(`Refresh failed: network error: ${String(cause)}`);
+    this.name = "RefreshNetworkError";
+    this.cause = cause;
+  }
+}
+
+/**
+ * POST /api/conversations/:conversationId/refresh-token
+ *
+ * Rotates the per-conversation token in place. Worker updates the row's
+ * token+expiry and returns the new pair. The caller (scheduler) propagates
+ * the new token to module state so subsequent requests use it.
+ *
+ * @throws ConversationTokenExpiredError on HTTP 401 (token is unknown or has
+ *   already been rotated away from the value sent in the Authorization header)
+ * @throws RefreshHttpError on any other non-2xx status — inspect `.retryable`
+ * @throws RefreshNetworkError on fetch-level failure (always retryable)
+ */
+export async function refreshConversationToken(
+  baseUrl: string,
+  conversationId: string,
+  currentToken: string,
+  fingerprint: string,
+): Promise<RefreshTokenResponse> {
+  let resp: Response;
+  try {
+    resp = await fetch(
+      `${baseUrl}/api/conversations/${conversationId}/refresh-token`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${currentToken}`,
+          "X-Client-Fingerprint": fingerprint,
+          "Content-Type": "application/json",
+          ...cfAccessHeaders(),
+        },
+        body: "{}",
+      },
+    );
+  } catch (err) {
+    throw new RefreshNetworkError(err);
+  }
+
+  if (resp.status === 401) {
+    throw new ConversationTokenExpiredError();
+  }
+
+  if (!resp.ok) {
+    let detail = "";
+    try {
+      detail = await resp.text();
+    } catch {
+      // ignore
+    }
+    throw new RefreshHttpError(resp.status, detail);
+  }
+
+  return (await resp.json()) as RefreshTokenResponse;
+}
+
 export function defaultLabel(folderPath: string): string {
   const folder = basename(folderPath);
   // Local time, not UTC — the user sees this label in the UI; UTC was confusing.

package/lib/lockfile.ts

@@ -0,0 +1,25 @@
+/**
+ * lockfile.ts — derive the channel's lock file path from VIBER_BASE_URL.
+ *
+ * The lock prevents two instances of the channel from racing on stdin when
+ * Claude Code accidentally spawns duplicates. But two channels targeting
+ * *different* backends (e.g. staging + dev) are legitimately different
+ * processes — they shouldn't share a lock.
+ *
+ * Namespacing the lock by base URL lets them coexist.
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+
+/**
+ * Return the lock file path for a given base URL, under `lockDir`.
+ *
+ * The filename is `channel-{8-hex}.lock` where the hex is a stable SHA-256
+ * prefix of the base URL. Two callers with the same base URL get the same
+ * path (same process collision still detected); different base URLs get
+ * different paths (no false collision).
+ */
+export function lockFilePath(baseUrl: string, lockDir: string): string {
+  const suffix = createHash("sha256").update(baseUrl).digest("hex").slice(0, 8);
+  return join(lockDir, `channel-${suffix}.lock`);
+}

package/lib/messages.ts

@@ -15,6 +15,62 @@ export class ConversationTokenExpiredError extends Error {
   }
 }
 
+export type ArtifactFormat = "markdown" | "code" | "json" | "html";
+
+export interface Artifact {
+  content: string;
+  format?: ArtifactFormat;
+}
+
+const ALLOWED_ARTIFACT_FORMATS: readonly ArtifactFormat[] = [
+  "markdown",
+  "code",
+  "json",
+  "html",
+];
+
+export type ParseArtifactResult =
+  | { ok: true; artifact: Artifact | undefined }
+  | { ok: false; error: string };
+
+/**
+ * Validate and normalize a raw `artifact` value coming from MCP tool input.
+ *
+ * - `undefined` / `null` → `{ ok: true, artifact: undefined }` (no artifact attached).
+ * - Anything else must be a plain object with a non-empty trimmed `content` string and,
+ *   optionally, a `format` from the whitelist (`markdown` | `code` | `json` | `html`).
+ *   An omitted `format` is normalized to `"markdown"`.
+ *
+ * Kept as a pure function so the CallTool handler in viber-channel.ts stays small
+ * and the validation rules are unit-testable on their own.
+ */
+export function parseArtifact(raw: unknown): ParseArtifactResult {
+  if (raw === undefined || raw === null) {
+    return { ok: true, artifact: undefined };
+  }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, error: "artifact must be an object" };
+  }
+  const rawArtifact = raw as Record<string, unknown>;
+  const content = rawArtifact.content;
+  if (typeof content !== "string" || content.trim().length === 0) {
+    return { ok: false, error: "artifact.content must be a non-empty string" };
+  }
+  if (rawArtifact.format === undefined) {
+    return { ok: true, artifact: { content, format: "markdown" } };
+  }
+  if (
+    typeof rawArtifact.format !== "string" ||
+    !ALLOWED_ARTIFACT_FORMATS.includes(rawArtifact.format as ArtifactFormat)
+  ) {
+    return {
+      ok: false,
+      error: `artifact.format must be one of ${ALLOWED_ARTIFACT_FORMATS.join(", ")}`,
+    };
+  }
+  return { ok: true, artifact: { content, format: rawArtifact.format as ArtifactFormat } };
+}
+
 export interface MessagePostSuccess {
   ok: true;
   message_id: string;
@@ -40,6 +96,7 @@ export async function postMessage(
   conversationId: string,
   conversationToken: string,
   text: string,
+  artifact?: Artifact,
 ): Promise<MessagePostResult> {
   if (!text || text.trim().length === 0) {
     return {
@@ -60,7 +117,7 @@ export async function postMessage(
         "Content-Type": "application/json",
         ...cfAccessHeaders(),
       },
-      body: JSON.stringify({ content: text }),
+      body: JSON.stringify(artifact ? { content: text, artifact } : { content: text }),
     });
   } catch (err) {
     return {

package/lib/token_refresh.ts

@@ -0,0 +1,104 @@
+/**
+ * Token refresh scheduler — single-responsibility module.
+ *
+ * Fires a `refresh()` callback shortly before the conversation token expires,
+ * re-schedules itself on success, and routes failures to `onFailure()`. No
+ * knowledge of the worker, MCP server, or any channel module state.
+ */
+
+export interface TokenRefreshState {
+  /** Unix seconds — the new expiry returned by the refresh callback. */
+  expiresAt: number;
+}
+
+export interface TokenRefreshDeps {
+  /** Returns current time in unix seconds. Defaults to Date.now()/1000. */
+  now?: () => number;
+  /** Schedules a callback after `ms` milliseconds. Defaults to setTimeout. */
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  /** Cancels a previously-scheduled timer. Defaults to clearTimeout. */
+  clearTimer?: (h: unknown) => void;
+  /** Seconds before expiry to trigger the refresh. Default 300 (5 minutes). */
+  leadSeconds?: number;
+  /** Log sink. Defaults to writing to process.stderr with a newline. */
+  log?: (line: string) => void;
+}
+
+export interface TokenRefreshScheduler {
+  /** Start the scheduler with the initial token expiry (unix seconds). */
+  start: (initialExpiresAt: number) => void;
+  /** Cancel any pending refresh. Idempotent. Stops re-scheduling. */
+  cancel: () => void;
+}
+
+const DEFAULT_LEAD_SECONDS = 300;
+
+type SchedulerState = "active" | "cancelled";
+
+export function createTokenRefreshScheduler(
+  refresh: () => Promise<TokenRefreshState>,
+  onFailure: (err: unknown) => void | Promise<void>,
+  deps: TokenRefreshDeps = {},
+): TokenRefreshScheduler {
+  const now = deps.now ?? (() => Date.now() / 1000);
+  const setTimer =
+    deps.setTimer ??
+    ((fn: () => void, ms: number) => setTimeout(fn, ms) as unknown);
+  const clearTimer = deps.clearTimer ?? ((h: unknown) => clearTimeout(h as ReturnType<typeof setTimeout>));
+  const leadSeconds = deps.leadSeconds ?? DEFAULT_LEAD_SECONDS;
+  const log = deps.log ?? ((line: string) => process.stderr.write(`${line}\n`));
+
+  let handle: unknown = null;
+  let state: SchedulerState = "active";
+
+  const scheduleAt = (expiresAt: number): void => {
+    if (state === "cancelled") return;
+    const delayMs = Math.max(0, (expiresAt - leadSeconds - now()) * 1000);
+    handle = setTimer(fire, delayMs);
+  };
+
+  const fire = (): void => {
+    handle = null;
+    // void intentional — timer callback cannot be async.
+    void runRefresh();
+  };
+
+  const runRefresh = async (): Promise<void> => {
+    try {
+      const result = await refresh();
+      if (state === "cancelled") return;
+      const ttlSeconds = Math.max(0, result.expiresAt - now());
+      const nextSeconds = Math.max(0, ttlSeconds - leadSeconds);
+      const ttlMin = Math.round(ttlSeconds / 60);
+      const nextMin = Math.round(nextSeconds / 60);
+      log(
+        `[viber-channel] token refreshed, next refresh in ${nextMin}m (ttl ${ttlMin}m)`,
+      );
+      scheduleAt(result.expiresAt);
+    } catch (err) {
+      try {
+        await onFailure(err);
+      } catch {
+        // Failure callback owns its own error path; swallow.
+      }
+    }
+  };
+
+  return {
+    start(initialExpiresAt: number): void {
+      if (state === "cancelled") return;
+      if (handle !== null) {
+        clearTimer(handle);
+        handle = null;
+      }
+      scheduleAt(initialExpiresAt);
+    },
+    cancel(): void {
+      state = "cancelled";
+      if (handle !== null) {
+        clearTimer(handle);
+        handle = null;
+      }
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Voice + text MCP channel between a Claude Code session and the Viber UI (https://viber.dgypx.dev). Push transcripts to Claude; send_message tool delivers text back to the UI.",
   "type": "module",
   "bin": {

package/viber-channel.ts

@@ -1,13 +1,28 @@
 #!/usr/bin/env bun
 /**
- * viber-channel MCP channel server (#217)
+ * viber-channel MCP channel server (#217, #232)
  *
  * Reads .viber/auth.json for authentication, then connects to
  * /api/conversations/<id>/events SSE stream and pushes transcripts and
  * messages as channel events.
  *
- * Start Claude with:
- *   claude --dangerously-load-development-channels server:viber-channel
+ * Launch via Claude Code — two MCP server names are in use:
+ *   - server:viber-channel       — npm-published build (bunx viber-channel@latest),
+ *                                  staging backend (viber.dgypx.dev), wired by
+ *                                  external consumers via `claude mcp add`.
+ *   - server:viber-dev-channel   — local-source build, dev backend
+ *                                  (viber-dev.dgypx.dev). Defined in this repo's
+ *                                  committed .mcp.json (or override locally).
+ *
+ *   claude --dangerously-load-development-channels server:<name>
+ *
+ * Two PowerShell launchers wrap the right flag:
+ *   - viber.ps1       → server:viber-channel (staging)
+ *   - viber-dev.ps1   → server:viber-dev-channel (this repo, dev)
+ *
+ * CLI subcommand: `bunx viber-channel connect <claim_url>` runs the one-shot
+ * claim flow that writes .viber/auth.json without requiring any Claude Code
+ * recipe in CLAUDE.md.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -15,6 +30,11 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprot
 import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { runConnect } from "./lib/connect.ts";
+import { lockFilePath } from "./lib/lockfile.ts";
+import {
+  createTokenRefreshScheduler,
+  type TokenRefreshScheduler,
+} from "./lib/token_refresh.ts";
 
 // ---- CLI subcommand dispatch (must happen before lock acquire + loadAuth) ----
 //
@@ -53,13 +73,16 @@ import { runConnect } from "./lib/connect.ts";
   }
 }
 
-// Lock file path: %APPDATA%/viber/ (Windows) or ~/.config/viber/ (Linux/Mac)
+// Lock file path: %APPDATA%/viber/ (Windows) or ~/.config/viber/ (Linux/Mac).
+// Namespaced by VIBER_BASE_URL so channels targeting different backends
+// (staging + dev) coexist on the same machine — only same-backend duplicates
+// still collide, which is the intended guard.
 const LOCK_DIR =
   process.env.APPDATA
     ? join(process.env.APPDATA, "viber")
     : join(process.env.HOME ?? "/tmp", ".config", "viber");
-// TODO: rename to channel.lock once all installations have transitioned off the old name
-const LOCK_FILE = join(LOCK_DIR, "watchdog.lock");
+const LOCK_BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
+const LOCK_FILE = lockFilePath(LOCK_BASE_URL, LOCK_DIR);
 
 function isProcessAlive(pid: number): boolean {
   try {
@@ -119,10 +142,15 @@ function releaseLock(): void {
   }
 }
 
+// Token-refresh scheduler — null until the initial mint succeeds. Declared at
+// module scope so the early exit handlers below (which fire before the mint
+// completes on slow boots) can cancel it idempotently via optional-chaining.
+let scheduler: TokenRefreshScheduler | null = null;
+
 // Best-effort cleanup — on Windows, signals may not fire (TerminateProcess)
-process.on("exit", releaseLock);
-process.on("SIGINT", () => { releaseLock(); process.exit(0); });
-process.on("SIGTERM", () => { releaseLock(); process.exit(0); });
+process.on("exit", () => { scheduler?.cancel(); releaseLock(); });
+process.on("SIGINT", () => { scheduler?.cancel(); releaseLock(); process.exit(0); });
+process.on("SIGTERM", () => { scheduler?.cancel(); releaseLock(); process.exit(0); });
 
 // stdin EOF — Claude Code closes its end of the pipe when the session
 // terminates (or the parent process is killed via TerminateProcess on
@@ -130,13 +158,16 @@ process.on("SIGTERM", () => { releaseLock(); process.exit(0); });
 // the bun subprocess outlives Claude Code and leaks (the orphan that
 // taunts us on every restart). The MCP transport uses stdin too, but
 // it doesn't propagate close as a process exit, so we wire it ourselves.
+//
+// NOTE: we deliberately listen to `end` only, not `close`. On Windows/Bun,
+// registering an MCP `StdioServerTransport` reader appears to trigger a
+// spurious `close` event ~2 ms after the transport's read loop starts,
+// which would kill the channel mid-mint before MCP traffic even begins.
+// `end` fires on real EOF (parent closes write end) and is sufficient for
+// orphan detection. See plan #236 step-09 for the diagnosis.
 process.stdin.on("end", () => {
   process.stderr.write("[viber-channel] stdin closed (parent exited), shutting down\n");
-  releaseLock();
-  process.exit(0);
-});
-process.stdin.on("close", () => {
-  process.stderr.write("[viber-channel] stdin close event, shutting down\n");
+  scheduler?.cancel();
   releaseLock();
   process.exit(0);
 });
@@ -164,8 +195,15 @@ if (computedFp !== auth.client_fingerprint) {
 
 // ---- Imports for mint ----
 
-import { defaultLabel, mintConversation, ReverifyRequiredError } from "./lib/conversation.ts";
-import { postMessage, ConversationTokenExpiredError } from "./lib/messages.ts";
+import {
+  defaultLabel,
+  mintConversation,
+  refreshConversationToken,
+  RefreshHttpError,
+  RefreshNetworkError,
+  ReverifyRequiredError,
+} from "./lib/conversation.ts";
+import { postMessage, ConversationTokenExpiredError, parseArtifact } from "./lib/messages.ts";
 import { cfAccessHeaders } from "./lib/cfAccess.ts";
 
 const BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
@@ -181,10 +219,13 @@ const mcp = new Server(
       tools: {},
     },
     instructions: [
-      'Voice transcripts arrive as <channel source="viber-channel">.',
-      "Each event contains transcriptions from the user's microphone.",
-      "Process the transcript and respond with speak(). Do NOT launch any watchdog or call check_voice().",
-      "On exit intent (bye, au revoir, stop) → call stop_conversation(), speak farewell, stop.",
+      'Voice transcripts arrive as <channel source="viber-channel"> events carrying the user\'s microphone speech.',
+      "Reply with send_message. The `text` field is read aloud to the user, so keep it a short, natural spoken sentence — no markdown symbols, no bullet lists, no tables, no code blocks.",
+      "Put technical content (code, lists, JSON, tables, command output, long file paths) in the optional `artifact` field with the matching `format`; it renders in a side viewer the user can read.",
+      "Available formats: `markdown` (default), `code`, `json`, `html`.",
+      "Use `html` only when the rendering needs structural HTML markdown can't express (styled cards, badges, mixed layouts). Scripts and event handlers are stripped server-side; don't try to send executable JS.",
+      "Rule of thumb: if it would sound bad read aloud, it belongs in the artifact, not the text.",
+      "On exit intent (bye, au revoir, stop) call stop_conversation(), speak a brief farewell, and stop.",
     ].join(" "),
   }
 );
@@ -196,14 +237,37 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "send_message",
       description:
-        "Send a message into the Viber conversation this channel is bound to. The user sees it in the web UI in real-time. Use this to deliver Claude's responses to the user without typing.",
+        "Send a message into the Viber conversation this channel is bound to. " +
+        "`text` is the spoken/conversational reply (read aloud — keep it short and natural, no markdown). " +
+        "`artifact` is optional and carries technical content (markdown, code, JSON, or sanitized HTML) rendered in a side viewer. " +
+        "Use `html` only when structural HTML markdown can't express is required; scripts and event handlers are stripped before display.",
       inputSchema: {
         type: "object" as const,
         properties: {
           text: {
             type: "string",
             minLength: 1,
-            description: "Message text to send to the user's conversation",
+            description: "Spoken/conversational reply. Plain sentences, no markdown symbols or lists.",
+          },
+          artifact: {
+            type: "object",
+            description: "Optional technical content rendered in the artifact viewer alongside the spoken text.",
+            properties: {
+              content: {
+                type: "string",
+                minLength: 1,
+                description: "Artifact body — markdown, code, JSON, or HTML.",
+              },
+              format: {
+                type: "string",
+                enum: ["markdown", "code", "json", "html"],
+                description:
+                  "Render format for the artifact body. Defaults to markdown if omitted. " +
+                  "Use `html` only when structural HTML is required (styled cards, badges, mixed layouts); " +
+                  "scripts, event handlers, iframes, and inline styles are stripped server-side before rendering.",
+              },
+            },
+            required: ["content"],
           },
         },
         required: ["text"],
@@ -232,9 +296,18 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
     };
   }
 
+  const parsed = parseArtifact(args.artifact);
+  if (!parsed.ok) {
+    return {
+      isError: true,
+      content: [{ type: "text" as const, text: `Invalid input: ${parsed.error}` }],
+    };
+  }
+  const artifact = parsed.artifact;
+
   let result;
   try {
-    result = await postMessage(BASE_URL, CONVERSATION_ID, CONVERSATION_TOKEN, text);
+    result = await postMessage(BASE_URL, CONVERSATION_ID, CONVERSATION_TOKEN, text, artifact);
   } catch (err) {
     if (err instanceof ConversationTokenExpiredError) {
       // Notify Claude (and the user) that the channel token has expired
@@ -320,6 +393,93 @@ try {
   CONVERSATION_TOKEN = minted.conversation_token;
   VOICE_BASE_URL = minted.ws_url;
   CONVERSATION_ID = minted.conversation_id;
+
+  // Schedule silent token refresh ahead of expiry (#237 step-03). On success
+  // we mutate CONVERSATION_TOKEN in place — getHeaders() reads it by closure,
+  // so subsequent SSE reconnects and send_message calls pick up the new token
+  // automatically. On failure we fall through to the existing
+  // handleConversationTokenExpired path (notification + exit code 3).
+  //
+  // VIBER_REFRESH_LEAD_SECONDS overrides the default 300s lead window — used
+  // for shortening the refresh-before-expiry gap during E2E manual testing
+  // (set close to TTL to force a refresh seconds after startup). Out of band
+  // for normal operation; the scheduler module's default applies when unset.
+  const leadOverride = process.env.VIBER_REFRESH_LEAD_SECONDS;
+  const leadSeconds = leadOverride ? Number.parseInt(leadOverride, 10) : undefined;
+  if (leadOverride !== undefined) {
+    if (!Number.isFinite(leadSeconds) || (leadSeconds as number) < 0) {
+      process.stderr.write(
+        `[viber-channel] Invalid VIBER_REFRESH_LEAD_SECONDS=${leadOverride}, ignoring.\n`
+      );
+    } else {
+      process.stderr.write(
+        `[viber-channel] token refresh lead overridden to ${leadSeconds}s via VIBER_REFRESH_LEAD_SECONDS\n`
+      );
+    }
+  }
+  const validLead =
+    leadSeconds !== undefined && Number.isFinite(leadSeconds) && leadSeconds >= 0
+      ? leadSeconds
+      : undefined;
+
+  // Track the current token's expiry so the retry path can refuse to retry
+  // past it. Updated only after a successful refresh — failed attempts leave
+  // it pointing at the still-valid current token.
+  let currentExpiresAt = minted.expires_at;
+
+  scheduler = createTokenRefreshScheduler(
+    async () => {
+      // Retry transient failures (5xx, 408, 409, network) with exponential
+      // backoff so a momentary blip during the 5-min lead window doesn't kill
+      // a channel whose token is still valid. Permanent failures (401, 403)
+      // surface immediately.
+      const MAX_ATTEMPTS = 5;
+      const HEADROOM_SECONDS = 10;
+      for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+          const refreshed = await refreshConversationToken(
+            BASE_URL,
+            CONVERSATION_ID,
+            CONVERSATION_TOKEN,
+            auth.client_fingerprint,
+          );
+          // SSE connection: the server accepts the new token immediately on
+          // subsequent requests, and any in-flight fetch still has the old
+          // token attached at the header level — the server keeps the open
+          // stream alive on the old token until its natural close. Safe to
+          // overwrite the module variable here.
+          CONVERSATION_TOKEN = refreshed.conversation_token;
+          currentExpiresAt = refreshed.expires_at;
+          return { expiresAt: refreshed.expires_at };
+        } catch (err) {
+          const retryable =
+            (err instanceof RefreshHttpError && err.retryable) ||
+            err instanceof RefreshNetworkError;
+          if (!retryable || attempt === MAX_ATTEMPTS) throw err;
+          // Bound retries by token validity: never sleep past expiry, leave
+          // a small headroom so the post-sleep request has time to land.
+          const proposedDelay = Math.min(30 * 2 ** (attempt - 1), 120);
+          const remaining = currentExpiresAt - Date.now() / 1000;
+          if (remaining - proposedDelay < HEADROOM_SECONDS) throw err;
+          process.stderr.write(
+            `[viber-channel] token refresh attempt ${attempt} failed (${String(err)}); retry in ${proposedDelay}s (${Math.round(remaining)}s until expiry)\n`,
+          );
+          await new Promise((r) => setTimeout(r, proposedDelay * 1000));
+        }
+      }
+      // Unreachable — the loop above either returns the refreshed state or
+      // throws on attempt === MAX_ATTEMPTS.
+      throw new Error("token refresh: retry loop exhausted without resolution");
+    },
+    async (err) => {
+      process.stderr.write(`[viber-channel] token refresh failed: ${String(err)}\n`);
+      // We don't call scheduler.cancel() here — we're inside the scheduler's
+      // failure path, and handleConversationTokenExpired ends the process anyway.
+      await handleConversationTokenExpired(mcp);
+    },
+    validLead !== undefined ? { leadSeconds: validLead } : undefined,
+  );
+  scheduler.start(minted.expires_at);
 } catch (err) {
   if (err instanceof ReverifyRequiredError) {
     await mcp.notification({
@@ -379,19 +539,36 @@ async function pushTranscript(text: string, lang: string): Promise<void> {
   });
 }
 
-/** Forward a saved conversation message from the event bus to Claude. */
-async function pushMessage(msg: { text: string; id?: string | null; source?: string }): Promise<void> {
-  process.stderr.write(`[viber-channel] pushMessage ENTER: "${msg.text.slice(0, 60)}"\n`);
+/**
+ * Forward a saved conversation message from the event bus to Claude.
+ *
+ * Wire field name is `content` — the SSE payload mirrors the Worker's
+ * `MessageResponse` shape (viber-api/src/db/types.ts), republished verbatim by
+ * Python (`ws_server.internal_notify_message` → `publish_to_conversation`).
+ * The optional `artifact` field is accepted here and threaded through the meta
+ * so downstream consumers (step-03 React viewer) can opt-in without a second
+ * round-trip; the channel itself does no special rendering of it yet.
+ */
+async function pushMessage(msg: {
+  content: string;
+  id?: string | null;
+  source?: string;
+  artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
+}): Promise<void> {
+  process.stderr.write(`[viber-channel] pushMessage ENTER: "${msg.content.slice(0, 60)}"\n`);
   // MCP notification handler (Claude Code v2.1.143) validates meta with Zod;
   // null fields are rejected as invalid type. Omit message_id when missing.
-  const meta: Record<string, string> = { source: msg.source ?? "conversation" };
+  const meta: Record<string, unknown> = { source: msg.source ?? "conversation" };
   if (typeof msg.id === "string" && msg.id.length > 0) {
     meta.message_id = msg.id;
   }
+  if (msg.artifact && typeof msg.artifact === "object" && typeof msg.artifact.content === "string") {
+    meta.artifact = msg.artifact;
+  }
   try {
     await mcp.notification({
       method: "notifications/claude/channel",
-      params: { content: msg.text, meta },
+      params: { content: msg.content, meta },
     });
     process.stderr.write(`[viber-channel] pushMessage OK\n`);
   } catch (err) {
@@ -456,6 +633,7 @@ async function sseLoop(): Promise<void> {
 
         case "stop":
           process.stderr.write(`[viber-channel] Received stop signal, exiting.\n`);
+          scheduler?.cancel();
           releaseLock();
           process.exit(0);
           break;
@@ -477,11 +655,21 @@ async function sseLoop(): Promise<void> {
           process.stderr.write(`[viber-channel] SSE event 'message' received, data_len=${data.length}\n`);
           if (data) {
             try {
-              const msg = JSON.parse(data) as { text: string; id?: string; source?: string; role?: string; timestamp?: string };
-              if (msg.text) {
+              // Wire shape mirrors viber-api `MessageResponse` (db/types.ts):
+              // primary text is `content`, not `text`. `artifact` is threaded
+              // through opaquely so step-03 (React viewer) can consume it.
+              const msg = JSON.parse(data) as {
+                content: string;
+                id?: string;
+                source?: string;
+                role?: string;
+                timestamp?: string;
+                artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
+              };
+              if (msg.content) {
                 await pushMessage(msg);
               } else {
-                process.stderr.write(`[viber-channel] 'message' event has empty text\n`);
+                process.stderr.write(`[viber-channel] 'message' event has empty content\n`);
               }
             } catch (err) {
               process.stderr.write(`[viber-channel] Failed to parse message data: ${String(err)}\n`);