viber-channel 0.5.1 → 0.5.3

package/lib/auth.ts

@@ -1,5 +1,5 @@
-import { readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 
 export interface AuthJson {
   schema_version: number;
@@ -9,7 +9,6 @@ export interface AuthJson {
   project_token: string;
   client_fingerprint: string;
   issued_at: string;
-  rotates_after?: string;
   /**
    * Optional — when present, the CLI must pass this id to the conversation
    * mint endpoint so the worker UPDATES the existing standalone conversation
@@ -24,30 +23,30 @@ export interface AuthJson {
 }
 
 /**
- * Atomically update the project_token in .viber/auth.json.
- * Writes to a tmp file first, then renames (atomic on POSIX; also atomic on Windows for same-volume).
+ * Resolve the auth file path.
+ *
+ * Defaults to `<cwd>/.viber/auth.json`. The optional `VIBER_AUTH_FILE` env var
+ * overrides it — absolute paths are used verbatim, relative paths are resolved
+ * against `cwd`. This lets a local launcher point the channel at an alternate
+ * credential file (e.g. `.viber/dev.auth.json`) WITHOUT swapping `auth.json`,
+ * so the default consumer flow (env var unset) is completely unaffected.
  */
-export function updateAuthToken(folderPath: string, currentAuth: AuthJson, newToken: string): AuthJson {
-  const path = join(folderPath, ".viber", "auth.json");
-  const tmp = `${path}.tmp`;
-  const updated: AuthJson = {
-    ...currentAuth,
-    project_token: newToken,
-    issued_at: new Date().toISOString(),
-  };
-  writeFileSync(tmp, JSON.stringify(updated, null, 2), "utf-8");
-  renameSync(tmp, path);
-  return updated;
+export function authFilePath(cwd: string = process.cwd()): string {
+  const override = process.env.VIBER_AUTH_FILE;
+  if (override !== undefined && override.trim() !== "") {
+    return isAbsolute(override) ? override : join(cwd, override);
+  }
+  return join(cwd, ".viber", "auth.json");
 }
 
 export function loadAuth(cwd: string = process.cwd()): AuthJson {
-  const path = join(cwd, ".viber", "auth.json");
+  const path = authFilePath(cwd);
   let raw: string;
   try {
     raw = readFileSync(path, "utf-8");
   } catch {
     process.stderr.write(
-      `[viber-channel] No \`.viber/auth.json\` found in this folder.\n` +
+      `[viber-channel] No auth file found at \`${path}\`.\n` +
       `Run the connect flow first: visit https://viber.dgypx.dev/projects → Create connection.\n`
     );
     process.exit(1);
@@ -56,15 +55,15 @@ export function loadAuth(cwd: string = process.cwd()): AuthJson {
   try {
     auth = JSON.parse(raw) as AuthJson;
   } catch (err) {
-    process.stderr.write(`[viber-channel] Malformed .viber/auth.json: ${String(err)}\n`);
+    process.stderr.write(`[viber-channel] Malformed auth file \`${path}\`: ${String(err)}\n`);
     process.exit(1);
   }
   if (auth.schema_version !== 1) {
-    process.stderr.write(`[viber-channel] Unsupported auth schema version: ${auth.schema_version}\n`);
+    process.stderr.write(`[viber-channel] Unsupported auth schema version ${auth.schema_version} in \`${path}\`\n`);
     process.exit(1);
   }
   if (!auth.project_token) {
-    process.stderr.write(`[viber-channel] Empty project_token in .viber/auth.json\n`);
+    process.stderr.write(`[viber-channel] Empty project_token in \`${path}\`\n`);
     process.exit(1);
   }
   return auth;

package/lib/channel_errors.ts

@@ -5,8 +5,8 @@ import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
  *
  * The CONVERSATION_TOKEN minted at startup has a 1h TTL. After expiry, the
  * server starts responding with 401. We notify the user and exit with code 3
- * (distinct from reverify exit code 2) so the process manager / user can
- * distinguish the cause.
+ * (distinct from the startup/mint failure exit code 1) so the process manager /
+ * user can distinguish the cause.
  *
  * We do NOT attempt to re-mint inline — the project_token is tied to the
  * original auth flow. The user must restart the channel to get a fresh token.

package/lib/channel_session.ts

@@ -0,0 +1,104 @@
+/**
+ * channel_session.ts — persist the channel's active conversation handle to disk.
+ *
+ * When a channel process mints or reattaches to a conversation, it writes the
+ * conversation_id here. A respawned channel process reads this file to find the
+ * existing conversation instead of minting a new one — avoiding duplicates (#257).
+ *
+ * Namespaced by `(VIBER_BASE_URL, client_fingerprint, VIBER_CHANNEL_SESSION_ID)` so:
+ * - dev and staging channels coexist on the same machine without colliding;
+ * - two *different* projects on the same backend each have their own handle and
+ *   never reattach to each other's conversation — the fingerprint axis is the
+ *   only thing that isolates them for a normal bunx client (#267), where the
+ *   sessionId is always "";
+ * - two concurrent launches of the *same* project (each with its own session id
+ *   set by viber-dev.ps1 / viber.ps1) each have their own handle (#259);
+ * - channel respawns within one launch inherit the same session id and find
+ *   the same handle — reattach still works (#257).
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, unlinkSync } from "node:fs";
+
+export interface ChannelHandle {
+  conversation_id: string;
+  saved_at: number; // unix seconds
+}
+
+/**
+ * Return the session file path for a given base URL, fingerprint, and session
+ * id, under `dir`.
+ *
+ * The filename is `channel-session-{8-hex}.json` where the hex is a stable
+ * SHA-256 prefix of `${baseUrl}\n${fingerprint}\n${sessionId}` — the same input
+ * shape as `lockFilePath`, so the lock and session files sit side by side for
+ * the same `(baseUrl, fingerprint, sessionId)` triple.
+ */
+export function sessionFilePath(
+  baseUrl: string,
+  fingerprint: string,
+  sessionId: string,
+  dir: string,
+): string {
+  const suffix = createHash("sha256")
+    .update(`${baseUrl}\n${fingerprint}\n${sessionId}`)
+    .digest("hex")
+    .slice(0, 8);
+  return join(dir, `channel-session-${suffix}.json`);
+}
+
+/**
+ * Read a persisted handle from `path`.
+ *
+ * Returns `null` — NEVER throws — when the file is absent, unreadable,
+ * contains invalid JSON, or the parsed object does not match the expected
+ * shape.
+ */
+export function readHandle(path: string): ChannelHandle | null {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      parsed === null ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed)
+    ) {
+      return null;
+    }
+    const obj = parsed as Record<string, unknown>;
+    if (typeof obj.conversation_id !== "string" || obj.conversation_id.length === 0) return null;
+    if (!Number.isFinite(obj.saved_at)) return null;
+    return { conversation_id: obj.conversation_id, saved_at: obj.saved_at as number };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the conversation handle to `path`.
+ *
+ * Overwrites any existing file. Propagates write errors (matches how
+ * `acquireLock` in viber-channel.ts propagates `writeFileSync` failures —
+ * the caller decides whether to handle them).
+ */
+export function writeHandle(path: string, conversationId: string): void {
+  const handle: ChannelHandle = {
+    conversation_id: conversationId,
+    saved_at: Math.floor(Date.now() / 1000),
+  };
+  writeFileSync(path, JSON.stringify(handle), "utf-8");
+}
+
+/**
+ * Remove the handle file at `path`.
+ *
+ * Best-effort — swallows errors if the file is absent, mirroring
+ * `releaseLock()` in viber-channel.ts.
+ */
+export function clearHandle(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {
+    // Best-effort — file may already be gone
+  }
+}

package/lib/connect.ts

@@ -17,7 +17,8 @@ import {
   readFileSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { authFilePath } from "./auth.js";
 import { clientFingerprint } from "./fingerprint.js";
 import { cfAccessHeaders } from "./cfAccess.js";
 
@@ -33,7 +34,6 @@ interface ConsumedResponse {
   user_email: string;
   project_token: string;
   issued_at: string;
-  rotates_after?: string;
   target_conversation_id?: string | null;
   readme_md: string;
 }
@@ -80,6 +80,13 @@ function writeAuthJson(
   const viberDir = join(cwd, ".viber");
   mkdirSync(viberDir, { recursive: true });
 
+  // Honor VIBER_AUTH_FILE so connecting with the override set writes the
+  // credentials to the same file the channel will read (e.g. dev.auth.json),
+  // instead of silently writing auth.json while the channel reads elsewhere.
+  // readme.md + .gitignore stay in <cwd>/.viber regardless.
+  const authPath = authFilePath(cwd);
+  mkdirSync(dirname(authPath), { recursive: true });
+
   const auth: Record<string, unknown> = {
     schema_version: 1,
     project_id: data.project_id,
@@ -88,7 +95,6 @@ function writeAuthJson(
     project_token: data.project_token,
     client_fingerprint: fingerprint,
     issued_at: data.issued_at,
-    rotates_after: data.rotates_after,
   };
   // Only emit target_conversation_id when the server explicitly returned a
   // non-null value (attach-to-project flow). Absent / null → omit to keep
@@ -100,11 +106,7 @@ function writeAuthJson(
     auth.target_conversation_id = data.target_conversation_id;
   }
 
-  writeFileSync(
-    join(viberDir, "auth.json"),
-    JSON.stringify(auth, null, 2),
-    "utf-8",
-  );
+  writeFileSync(authPath, JSON.stringify(auth, null, 2), "utf-8");
   writeFileSync(join(viberDir, "readme.md"), data.readme_md, "utf-8");
 
   // Append `.viber/` to .gitignore if not already present.
@@ -123,6 +125,20 @@ function writeAuthJson(
     const prefix = current === "" || current.endsWith("\n") ? "" : "\n";
     appendFileSync(gitignorePath, `${prefix}.viber/\n`);
   }
+
+  // The `.viber/` entry only covers credentials inside `.viber/`. If
+  // VIBER_AUTH_FILE points the auth file elsewhere, it is NOT auto-ignored —
+  // warn loudly so a project_token doesn't get committed by a later `git add`.
+  const relFromViber = relative(viberDir, authPath);
+  const insideViber =
+    relFromViber !== "" && !relFromViber.startsWith("..") && !isAbsolute(relFromViber);
+  if (!insideViber) {
+    process.stderr.write(
+      `[viber-channel] Warning: VIBER_AUTH_FILE points outside .viber/ (${authPath}).\n` +
+        `  This file holds your project token and is NOT covered by the .viber/ .gitignore entry.\n` +
+        `  Make sure it is git-ignored so the token is not committed.\n`,
+    );
+  }
 }
 
 /**
@@ -169,7 +185,7 @@ export async function runConnect(
       writeAuthJson(cwd, data, fingerprint);
       process.stdout.write(
         `\n✓ Connected as ${data.user_email} to project '${data.project_name}'.\n` +
-          `  Wrote ${join(cwd, ".viber", "auth.json")}\n\n` +
+          `  Wrote ${authFilePath(cwd)}\n\n` +
           `Next steps:\n` +
           `  1. Register the channel MCP server (one-time per machine):\n` +
           `       claude mcp add viber-channel --scope user -- bunx viber-channel@latest\n` +

package/lib/conversation.ts

@@ -1,23 +1,28 @@
 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;
   }
 }
 
@@ -58,24 +63,151 @@ 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 Error(`Failed to mint conversation token (HTTP ${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,
+  projectToken: string,
+  fingerprint: string,
+  conversationId: string,
+): Promise<ConversationMintResponse> {
+  const resp = await fetch(`${baseUrl}/api/projects/${projectId}/conversations`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${projectToken}`,
+      "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;
 }
 
+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.
@@ -84,3 +216,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 projectToken  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,
+  projectToken: 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, projectToken, 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, projectToken, 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/lockfile.ts

@@ -1,25 +1,50 @@
 /**
- * lockfile.ts — derive the channel's lock file path from VIBER_BASE_URL.
+ * lockfile.ts — derive the channel's lock file path from VIBER_BASE_URL, the
+ * client fingerprint, and an optional per-launch session id.
  *
  * The lock prevents two instances of the channel from racing on stdin when
- * Claude Code accidentally spawns duplicates. But two channels targeting
+ * Claude Code accidentally spawns duplicates. Two channels targeting
  * *different* backends (e.g. staging + dev) are legitimately different
- * processes — they shouldn't share a lock.
+ * processes — they shouldn't share a lock; namespacing by base URL lets
+ * them coexist.
  *
- * Namespacing the lock by base URL lets them coexist.
+ * #267 adds the project axis: the lock is namespaced by `client_fingerprint`
+ * (deterministic per machine + folder, from .viber/auth.json). Two *different*
+ * projects on the same backend therefore never share a lock — this is the only
+ * axis that isolates them for a normal bunx client, where sessionId is always
+ * "" (the #259 sessionId axis below provides no isolation there).
+ *
+ * #259 adds the per-instance axis: when the launcher (e.g. viber-dev.ps1)
+ * supplies a per-launch session id via VIBER_CHANNEL_SESSION_ID, the lock is
+ * additionally namespaced by it, so two concurrent launches of the *same*
+ * project each get their own lock. Channel respawns within one launch inherit
+ * the same env var and reuse the same lock — accidental duplicates are still
+ * blocked.
  */
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 
 /**
- * Return the lock file path for a given base URL, under `lockDir`.
+ * Return the lock file path for a given base URL, fingerprint, and session id,
+ * 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).
+ * prefix of `${baseUrl}\n${fingerprint}\n${sessionId}` (newline-separated so
+ * distinct concatenations cannot collide).
+ *
+ * When `sessionId === ""` (external bunx clients), the hash is stable on
+ * `${baseUrl}\n${fingerprint}\n` — so each project (distinct fingerprint)
+ * still converges on its own consistent path.
  */
-export function lockFilePath(baseUrl: string, lockDir: string): string {
-  const suffix = createHash("sha256").update(baseUrl).digest("hex").slice(0, 8);
+export function lockFilePath(
+  baseUrl: string,
+  fingerprint: string,
+  sessionId: string,
+  lockDir: string,
+): string {
+  const suffix = createHash("sha256")
+    .update(`${baseUrl}\n${fingerprint}\n${sessionId}`)
+    .digest("hex")
+    .slice(0, 8);
   return join(lockDir, `channel-${suffix}.lock`);
 }

package/lib/message_dedup.ts

@@ -0,0 +1,47 @@
+/**
+ * MessageDedup (#254 follow-up) — drops the persisted echo of a user transcript.
+ *
+ * When a web UI is open, Python delivers the user's voice transcript to the
+ * channel TWICE: an ephemeral copy (`id: null`) the instant it is transcribed
+ * (the conversation event-bus path from #221), then the persisted copy (real
+ * `id`) once the browser saves it to the DB and the Worker republishes it.
+ * Both carry identical content, so Claude sees the utterance twice.
+ *
+ * This tracks recently-seen ephemeral (id-less) messages and reports a later
+ * id-bearing message with the same content as a duplicate. The channel forwards
+ * each utterance exactly once:
+ *   - ephemeral message            → recorded, forwarded
+ *   - persisted echo of it         → dropped
+ *   - persisted message with no prior ephemeral (assistant/ai/channel) → forwarded
+ *   - a genuine repeat (new ephemeral of the same text) → forwarded
+ *
+ * Content-only, time-bounded matching: a persisted message is only dropped if an
+ * ephemeral with the same trimmed content was seen within `ttlMs`.
+ */
+export class MessageDedup {
+	private readonly recent = new Map<string, number>();
+
+	constructor(private readonly ttlMs: number = 15_000) {}
+
+	/**
+	 * Records ephemeral (id-less) messages; returns `true` for a persisted
+	 * (id-bearing) message that echoes a recent ephemeral one — i.e. drop it.
+	 */
+	isDuplicate(msg: { id?: string | null; content: string }, now: number = Date.now()): boolean {
+		this.prune(now);
+		const key = msg.content.trim();
+		if (!key) return false;
+		const hasId = typeof msg.id === "string" && msg.id.length > 0;
+		if (!hasId) {
+			this.recent.set(key, now);
+			return false;
+		}
+		return this.recent.has(key);
+	}
+
+	private prune(now: number): void {
+		for (const [key, ts] of this.recent) {
+			if (now - ts > this.ttlMs) this.recent.delete(key);
+		}
+	}
+}

package/lib/startup_gate.ts

@@ -0,0 +1,19 @@
+/**
+ * Startup stability gate (#257).
+ *
+ * Defers work by `delayMs` milliseconds, then reports whether the process
+ * is still alive (true = proceed, false = shutting down detected).
+ *
+ * A process whose stdin pipe closes during the window exits via the existing
+ * `end` handler BEFORE the timer resolves in practice — but the flag check
+ * is a defensive guard in case the timer wins the race.
+ */
+export async function awaitStableStartup(
+  delayMs: number,
+  isShuttingDown: () => boolean,
+): Promise<boolean> {
+  if (delayMs > 0) {
+    await new Promise<void>((r) => setTimeout(r, delayMs));
+  }
+  return !isShuttingDown();
+}

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.1",
+  "version": "0.5.3",
   "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

@@ -31,6 +31,18 @@ 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 { sessionFilePath, clearHandle } from "./lib/channel_session.ts";
+import { clientFingerprint } from "./lib/fingerprint.ts";
+import { MessageDedup } from "./lib/message_dedup.ts";
+import {
+  acquireConversation,
+  DEFAULT_REATTACH_WINDOW_SECONDS,
+} from "./lib/conversation.ts";
+import {
+  createTokenRefreshScheduler,
+  type TokenRefreshScheduler,
+} from "./lib/token_refresh.ts";
+import { awaitStableStartup } from "./lib/startup_gate.ts";
 
 // ---- CLI subcommand dispatch (must happen before lock acquire + loadAuth) ----
 //
@@ -70,15 +82,71 @@ import { lockFilePath } from "./lib/lockfile.ts";
 }
 
 // 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.
+// Namespaced by (VIBER_BASE_URL, client_fingerprint, VIBER_CHANNEL_SESSION_ID) so:
+//   - channels at different backends (staging + dev) coexist (different base_url);
+//   - two DIFFERENT projects on the same backend never collide — the fingerprint
+//     (deterministic per machine + folder) is the only axis that isolates them
+//     for a normal bunx client, where the session id is always "" (#267);
+//   - two concurrent launches of the SAME project coexist when each launcher
+//     supplies a per-launch session id (#259);
+//   - channel respawns within one launch inherit the same session id and
+//     re-acquire the same lock — accidental duplicates still blocked (#166).
+//
+// LOCK_FINGERPRINT is computed from the current folder (process.cwd()) rather
+// than read from auth.json so the lock paths are available before loadAuth();
+// it is verified equal to auth.client_fingerprint below — a mismatch exits.
 const LOCK_DIR =
   process.env.APPDATA
     ? join(process.env.APPDATA, "viber")
     : join(process.env.HOME ?? "/tmp", ".config", "viber");
 const LOCK_BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
-const LOCK_FILE = lockFilePath(LOCK_BASE_URL, LOCK_DIR);
+const LOCK_SESSION_ID = process.env.VIBER_CHANNEL_SESSION_ID ?? "";
+const LOCK_FINGERPRINT = clientFingerprint(process.cwd());
+const LOCK_FILE = lockFilePath(LOCK_BASE_URL, LOCK_FINGERPRINT, LOCK_SESSION_ID, LOCK_DIR);
+const SESSION_FILE = sessionFilePath(LOCK_BASE_URL, LOCK_FINGERPRINT, LOCK_SESSION_ID, LOCK_DIR);
+
+// VIBER_REATTACH_WINDOW_SECONDS overrides the default TTL-based window.
+// A handle older than this cannot point at a live conversation — skip reattach.
+// Parsed once, mirroring the VIBER_REFRESH_LEAD_SECONDS pattern below: validate
+// finite && >= 0, log invalid→ignore, log override, fall back to the default.
+const REATTACH_WINDOW_SECONDS: number = (() => {
+  const raw = process.env.VIBER_REATTACH_WINDOW_SECONDS;
+  if (raw === undefined) return DEFAULT_REATTACH_WINDOW_SECONDS;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    process.stderr.write(
+      `[viber-channel] Invalid VIBER_REATTACH_WINDOW_SECONDS=${raw}, ignoring.\n`
+    );
+    return DEFAULT_REATTACH_WINDOW_SECONDS;
+  }
+  process.stderr.write(
+    `[viber-channel] reattach window overridden to ${parsed}s via VIBER_REATTACH_WINDOW_SECONDS\n`
+  );
+  return parsed;
+})();
+
+// VIBER_STABILITY_DELAY_MS: how long to wait after mcp.connect() before
+// creating a conversation. A doomed process (broken-pipe respawn) dies during
+// this window via the stdin "end" handler, setting shuttingDown=true — the gate
+// then skips acquireConversation and the conversation is never created.
+// Default: 500ms (observed broken-pipe deaths are ~0s; 500ms is imperceptible).
+// Set to 0 to disable (useful for tests / custom launchers).
+const DEFAULT_STABILITY_DELAY_MS = 500;
+const STABILITY_DELAY_MS: number = (() => {
+  const raw = process.env.VIBER_STABILITY_DELAY_MS;
+  if (raw === undefined) return DEFAULT_STABILITY_DELAY_MS;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    process.stderr.write(
+      `[viber-channel] Invalid VIBER_STABILITY_DELAY_MS=${raw}, ignoring.\n`
+    );
+    return DEFAULT_STABILITY_DELAY_MS;
+  }
+  process.stderr.write(
+    `[viber-channel] stability delay overridden to ${parsed}ms via VIBER_STABILITY_DELAY_MS\n`
+  );
+  return parsed;
+})();
 
 function isProcessAlive(pid: number): boolean {
   try {
@@ -138,10 +206,24 @@ 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;
+
+// Stability gate flag (#257): set true as soon as any shutdown path begins so
+// the gate can observe an in-flight shutdown and abort conversation creation.
+let shuttingDown = false;
+
 // 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(); });
+// NOTE: shuttingDown is NOT set here. SIGINT/SIGTERM call process.exit(0) synchronously,
+// so the event loop ends before any setTimeout (the stability gate) can observe the flag.
+// Only the stdin `end` handler sets shuttingDown=true, because it does NOT call
+// process.exit() synchronously — it fires before the MCP transport's read loop begins,
+// giving the gate's setTimeout a chance to run and check the flag.
+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
@@ -157,27 +239,28 @@ process.on("SIGTERM", () => { releaseLock(); process.exit(0); });
 // `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", () => {
+  shuttingDown = true;
   process.stderr.write("[viber-channel] stdin closed (parent exited), shutting down\n");
+  scheduler?.cancel();
   releaseLock();
   process.exit(0);
 });
 
 // ---- Auth from .viber/auth.json ----
 
-import { loadAuth, updateAuthToken } from "./lib/auth.ts";
+import { authFilePath, loadAuth } from "./lib/auth.ts";
 import { handleConversationTokenExpired } from "./lib/channel_errors.ts";
 import { buildSseUrl } from "./lib/urls.ts";
 
-let auth = loadAuth();
+const auth = loadAuth();
 
 // ---- Fingerprint verification ----
-
-import { clientFingerprint } from "./lib/fingerprint.ts";
-
-const computedFp = clientFingerprint(process.cwd());
-if (computedFp !== auth.client_fingerprint) {
+//
+// LOCK_FINGERPRINT (computed above from process.cwd()) is the same value; this
+// re-checks it against the fingerprint stored in auth.json and exits on drift.
+if (LOCK_FINGERPRINT !== auth.client_fingerprint) {
   process.stderr.write(
-    `[viber-channel] Folder fingerprint mismatch — \`.viber/auth.json\` was issued for a different machine/folder.\n` +
+    `[viber-channel] Folder fingerprint mismatch — \`${authFilePath()}\` was issued for a different machine/folder.\n` +
     `Re-run the connect flow at https://viber.dgypx.dev/projects.\n`
   );
   process.exit(1);
@@ -185,7 +268,12 @@ if (computedFp !== auth.client_fingerprint) {
 
 // ---- Imports for mint ----
 
-import { defaultLabel, mintConversation, ReverifyRequiredError } from "./lib/conversation.ts";
+import {
+  defaultLabel,
+  refreshConversationToken,
+  RefreshHttpError,
+  RefreshNetworkError,
+} from "./lib/conversation.ts";
 import { postMessage, ConversationTokenExpiredError, parseArtifact } from "./lib/messages.ts";
 import { cfAccessHeaders } from "./lib/cfAccess.ts";
 
@@ -204,6 +292,7 @@ const mcp = new Server(
     instructions: [
       '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.",
+      "Exception for inline identifiers: when mentioning a file name, hostname, variable, or other short token inline (auth.json, viber-dev.dgypx.dev, CONVERSATION_TOKEN), write the literal form with its real dots and dashes — do NOT spell them out as 'point' or 'dash'. The 'no markdown' rule is about visual clutter (`**bold**`, `- bullets`, code fences, tables, long path lists), not the punctuation that's naturally part of identifiers.",
       "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.",
@@ -320,8 +409,14 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
   };
 });
 
-// Prevent duplicate instances (#166)
-process.stderr.write(`[viber-channel] startup: pid=${process.pid}, acquiring lock\n`);
+// Prevent duplicate instances (#166); fingerprint namespacing for different
+// projects (#267); session-id namespacing for concurrent launches of the same
+// project (#259). The fingerprint and session-id prefixes are logged so a user
+// with multiple channels can tell their stderr logs apart.
+const sessionIdLogged = LOCK_SESSION_ID === "" ? "<unset>" : LOCK_SESSION_ID.slice(0, 8);
+process.stderr.write(
+  `[viber-channel] startup: pid=${process.pid}, fp=${LOCK_FINGERPRINT.slice(0, 8)}, sessionId=${sessionIdLogged}, acquiring lock\n`,
+);
 const blockingPid = acquireLock();
 process.stderr.write(`[viber-channel] startup: lock acquired (blockingPid=${blockingPid})\n`);
 
@@ -345,52 +440,160 @@ if (blockingPid !== null) {
   process.exit(1);
 }
 
-// ---- Mint conversation token (after mcp.connect so reverify notifications can be sent) ----
+// ---- Stability gate (#257): defer conversation creation so a doomed process exits first ----
+//
+// Claude Code respawns the channel on transport reconnects; a process that dies
+// within the first second (broken-pipe) had already created a conversation
+// because acquireConversation() ran immediately. The gate delays that call so
+// the stdin "end" handler can set shuttingDown=true and let process.exit(0)
+// race the timer. If the gate sees shuttingDown, it exits without creating a
+// conversation. A healthy process proceeds after STABILITY_DELAY_MS with no
+// user-perceptible delay (the user has not spoken yet at that point).
+
+process.stderr.write(`[viber-channel] startup: stability gate (${STABILITY_DELAY_MS}ms)...\n`);
+const gateOpen = await awaitStableStartup(STABILITY_DELAY_MS, () => shuttingDown);
+if (!gateOpen) {
+  process.stderr.write(`[viber-channel] startup: stability gate detected shutdown — skipping conversation creation\n`);
+  process.exit(0);
+}
+process.stderr.write(`[viber-channel] startup: stability gate passed (${STABILITY_DELAY_MS}ms), acquiring conversation\n`);
+
+// ---- Acquire conversation token (reattach or mint, after mcp.connect so a token-rejected notification can be sent) ----
 
 let CONVERSATION_TOKEN: string;
 let VOICE_BASE_URL: string;
 let CONVERSATION_ID: string;
 
-process.stderr.write(`[viber-channel] startup: calling mintConversation (project=${auth.project_id}, target=${auth.target_conversation_id ?? "null"})\n`);
+process.stderr.write(`[viber-channel] startup: acquiring conversation (project=${auth.project_id}, target=${auth.target_conversation_id ?? "null"}, session=${SESSION_FILE})\n`);
 try {
-  const minted = await mintConversation(
+  const minted = await acquireConversation(
+    SESSION_FILE,
     BASE_URL,
     auth.project_id,
     auth.project_token,
     auth.client_fingerprint,
     label,
     auth.target_conversation_id ?? null,
+    REATTACH_WINDOW_SECONDS,
   );
-  process.stderr.write(`[viber-channel] startup: mint OK, conv_id=${minted.conversation_id}\n`);
 
-  // Apply token rotation if the server issued a new project_token
-  if (minted.new_project_token) {
-    try {
-      auth = updateAuthToken(process.cwd(), auth, minted.new_project_token);
-    } catch (err) {
-      process.stderr.write(`[viber-channel] Warning: failed to update .viber/auth.json: ${String(err)}\n`);
-      // Don't exit — token is valid in memory; auth.json will be stale but channel keeps running
-    }
-  }
+  // project_token is now a stable, long-lived handshake credential (#274). It is
+  // never rotated by the mint response, so auth.json is never rewritten here.
 
   CONVERSATION_TOKEN = minted.conversation_token;
   VOICE_BASE_URL = minted.ws_url;
   CONVERSATION_ID = minted.conversation_id;
-} catch (err) {
-  if (err instanceof ReverifyRequiredError) {
-    await mcp.notification({
-      method: "notifications/claude/channel",
-      params: {
-        content: `⚠️ Re-verification required (reason: ${err.reason}). Visit ${err.url} to re-authenticate, then restart this channel.`,
-        meta: { source: "system", type: "reverify_required", url: err.url },
-      },
-    });
-    process.exit(2);
+
+  // 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) {
+  // The conversation mint failed. With the stable-token model (#274) a revoked
+  // or otherwise invalid project_token yields HTTP 401 — there is no reverify
+  // dance and no rotation, so the only recovery is to re-run the connect flow.
+  // Network errors and unexpected 5xx land here too; the message stays generic
+  // enough to cover them while pointing at the most common cause. The stderr
+  // line below is invisible in the Claude Code UI, which only sees the MCP
+  // server die ("tools fetch failed") — surface an actionable notification so
+  // the user knows what to do instead of failing opaquely. Clean exit, no retry.
   process.stderr.write(`[viber-channel] ${String(err)}\n`);
   process.stderr.write(
-    `[viber-channel] If your project_token is no longer valid, run the connect flow again at https://viber.dgypx.dev/projects.\n`
+    `[viber-channel] If your project_token is no longer valid, run the connect flow again at ${BASE_URL}/projects.\n`
   );
+  await mcp.notification({
+    method: "notifications/claude/channel",
+    params: {
+      content:
+        `⚠️ Could not start the voice channel: ${String(err)}. ` +
+        `If your project_token was revoked, reconnect at ${BASE_URL}/projects and run ` +
+        `\`bunx viber-channel connect <url>\` again, then restart this channel. ` +
+        `Otherwise this may be a temporary network issue — restart the channel to retry.`,
+      meta: { source: "system", type: "project_token_invalid" },
+    },
+  });
   process.exit(1);
 }
 
@@ -435,6 +638,11 @@ async function pushTranscript(text: string, lang: string): Promise<void> {
   });
 }
 
+// Drops the persisted echo of a user transcript already delivered ephemerally
+// (the conversation event bus delivers it twice when a web UI is open — #221
+// mechanism, surfaced by the #254 Active section that keeps the UI open).
+const messageDedup = new MessageDedup();
+
 /**
  * Forward a saved conversation message from the event bus to Claude.
  *
@@ -452,6 +660,12 @@ async function pushMessage(msg: {
   artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
 }): Promise<void> {
   process.stderr.write(`[viber-channel] pushMessage ENTER: "${msg.content.slice(0, 60)}"\n`);
+  if (messageDedup.isDuplicate(msg)) {
+    process.stderr.write(
+      `[viber-channel] dropping duplicate persisted message (already delivered ephemerally)\n`,
+    );
+    return;
+  }
   // 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, unknown> = { source: msg.source ?? "conversation" };
@@ -528,7 +742,9 @@ async function sseLoop(): Promise<void> {
           break;
 
         case "stop":
-          process.stderr.write(`[viber-channel] Received stop signal, exiting.\n`);
+          process.stderr.write(`[viber-channel] Received stop signal, clearing session handle and exiting.\n`);
+          clearHandle(SESSION_FILE);
+          scheduler?.cancel();
           releaseLock();
           process.exit(0);
           break;