viber-channel 0.5.2 → 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,24 +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;
   }
 }
 
@@ -59,21 +63,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 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 = {};
-      }
-      if (body.type === "reverify_required" && typeof body.reverify_url === "string") {
-        throw new ReverifyRequiredError(body.reverify_url, body.reason ?? "unknown");
+        // ignore — code stays "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 +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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.5.2",
+  "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,10 +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) ----
 //
@@ -74,15 +82,71 @@ import {
 }
 
 // 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 {
@@ -147,8 +211,17 @@ function releaseLock(): void {
 // 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", () => { 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); });
 
@@ -166,6 +239,7 @@ process.on("SIGTERM", () => { scheduler?.cancel(); 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();
@@ -174,20 +248,19 @@ process.stdin.on("end", () => {
 
 // ---- 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);
@@ -197,11 +270,9 @@ if (computedFp !== auth.client_fingerprint) {
 
 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";
@@ -221,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.",
@@ -337,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`);
 
@@ -362,33 +440,45 @@ 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;
@@ -481,20 +571,29 @@ try {
   );
   scheduler.start(minted.expires_at);
 } 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);
-  }
+  // 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);
 }
 
@@ -539,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.
  *
@@ -556,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" };
@@ -632,7 +742,8 @@ 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);