viber-channel 0.7.1 → 0.8.0

package/lib/bridge_core.ts

@@ -22,7 +22,7 @@ import {
 	RefreshNetworkError,
 	refreshConversationToken,
 } from "./conversation.js";
-import { ConversationTokenExpiredError, fetchMessages, postMessage } from "./messages.js";
+import { ackMessage, ConversationTokenExpiredError, fetchMessages, postMessage } from "./messages.js";
 import { buildSseUrl } from "./urls.js";
 import { cfAccessHeaders } from "./cfAccess.js";
 import { sessionFilePath, writeHandle } from "./channel_session.js";
@@ -534,8 +534,49 @@ export async function sseLoop(opts: {
 	const primeHistory = options.awaitInvite !== true;
 	let primed = false;
 
+	// #346 read-ACK bookkeeping. Tracked SEPARATELY from handledIds so a transient
+	// ACK failure is RETRIED on the next reconnect/catch-up instead of being lost
+	// forever (codex step-02 review): handledIds gates the reply (at-most-once),
+	// ackedIds gates the ACK (at-least-once-until-confirmed). ackInFlightIds avoids
+	// spamming concurrent ACKs for the same message within a run.
+	const ackedIds = new Set<string>();
+	const ackInFlightIds = new Set<string>();
+
+	// Emit a read-acknowledgement for a web→agent message. Run by the bridge CODE
+	// (not the LLM), fire-and-forget, BEFORE any reply — so the web "reçu" checkmark
+	// has zero impact on agent reply latency. Only role=user|user_voice with no
+	// sender_instance_id qualify (mirrors the Worker; the Worker is the source of
+	// truth and 404s anything else). Idempotent server-side, so re-acking on
+	// reconnect is safe; we only mark ackedIds on a confirmed success so a failed
+	// ACK is retried. Never throws (ackMessage swallows).
+	// TODO(#346/#280 s19): when addressed_to is revived (per-instance targeting),
+	// gate this on "this instance is an intended recipient" — otherwise an agent Y
+	// receiving the per-conversation SSE fan-out would ACK a message addressed to
+	// agent X, lighting "reçu" while X never received it. Mirror the same guard in
+	// the Worker's insertMessageAck qualification. N/A today: addressed_to is
+	// dormant and fan-out is per-conversation, so every connected bridge truly
+	// receives the message (consistent with decision A = delivered-to-bridge).
+	function ackInboundReceipt(msg: ConversationMessage): void {
+		if (msg.role !== "user" && msg.role !== "user_voice") return;
+		if (msg.sender_instance_id) return;
+		const idStr = msg.id !== undefined && msg.id !== null ? String(msg.id) : undefined;
+		if (!idStr) return;
+		if (ackedIds.has(idStr) || ackInFlightIds.has(idStr)) return;
+		ackInFlightIds.add(idStr);
+		void ackMessage(baseUrl, runtime.id, runtime.token, idStr, signal)
+			.then((ok) => {
+				if (ok) ackedIds.add(idStr);
+				else process.stderr.write(`${logPrefix} ack failed for message ${idStr} (will retry on reconnect)\n`);
+			})
+			.finally(() => ackInFlightIds.delete(idStr));
+	}
+
 	async function handleInboundMessage(msg: ConversationMessage): Promise<boolean> {
 		const idStr = msg.id !== undefined && msg.id !== null ? String(msg.id) : undefined;
+		// Confirm receipt to the web INDEPENDENTLY of handled/reply state, BEFORE the
+		// handledIds early-return — so a previously-failed ACK is retried when this
+		// message comes back through catch-up on reconnect (codex step-02 review).
+		ackInboundReceipt(msg);
 		if (idStr && handledIds.has(idStr)) return false;
 		if (!shouldHandleMessage(msg, ownInstanceKey, ownPostedIds, options)) {
 			if (idStr) handledIds.add(idStr); // skip decision is final — role won't change
@@ -575,6 +616,10 @@ export async function sseLoop(opts: {
 		const seed = (msg: ConversationMessage): void => {
 			const idStr = msg.id !== undefined && msg.id !== null ? String(msg.id) : undefined;
 			if (idStr) handledIds.add(idStr);
+			// #346: a bridge that was offline still RECEIVED these messages on
+			// reconnect — ACK seeded web→agent messages so offline→online shows
+			// "reçu" even though we won't reply to backlog.
+			ackInboundReceipt(msg);
 		};
 
 		// FIRST await-invite pass: bound the replay to the TRIGGER only — forward
@@ -796,14 +841,23 @@ export function buildAgentIdentityInstructions(opts: {
 
 /**
  * Read the agent identity from the spawn env and build the identity line.
- * `VIBER_AGENT_NAME_EXPLICIT === "1"` gates whether `VIBER_CODEX_BRIDGE_LABEL`
- * is treated as an explicit name (the label is always set — even for auto ids —
- * so the separate flag is the only safe signal). Shared by every bridge.
+ * `VIBER_AGENT_NAME_EXPLICIT === "1"` gates whether the spawn label is treated as
+ * an explicit name (the label is always set — even for auto ids — so the separate
+ * flag is the only safe signal). Shared by every runtime:
+ *   - the codex/gemma bridges set `VIBER_CODEX_BRIDGE_LABEL`;
+ *   - a Claude terminal session (#328) has no bridge — its label is
+ *     `VIBER_CHANNEL_LABEL` (set by buildClaudeLaunchSpec) — so fall back to it.
  */
 export function agentIdentityFromEnv(): string {
 	const explicit = process.env.VIBER_AGENT_NAME_EXPLICIT === "1";
+	// A BLANK bridge label counts as absent (defense in depth, #328): the terminal
+	// launcher wipes an inherited VIBER_CODEX_BRIDGE_LABEL to "", so a Claude
+	// session falls through to its own VIBER_CHANNEL_LABEL instead of a leaked
+	// parent bridge name.
+	const bridgeLabel = process.env.VIBER_CODEX_BRIDGE_LABEL?.trim();
+	const label = bridgeLabel || process.env.VIBER_CHANNEL_LABEL;
 	return buildAgentIdentityInstructions({
-		explicitName: explicit ? process.env.VIBER_CODEX_BRIDGE_LABEL : undefined,
+		explicitName: explicit ? label : undefined,
 		role: process.env.VIBER_AGENT_ROLE,
 	});
 }

package/lib/capabilities.ts

@@ -0,0 +1,41 @@
+/**
+ * Control-plane capabilities help (#332).
+ *
+ * An agent connected via the channel does not otherwise know that a `vibe-master`
+ * control plane exists on the machine, nor how to spawn other agents with it. Per
+ * the issue + JP: this must be DISCOVERABLE ON DEMAND, never injected into every
+ * conversation. So the channel exposes a `capabilities` MCP tool that returns
+ * this text only when the agent chooses to call it; the channel instructions
+ * carry just a one-line pointer to the tool, not its contents.
+ *
+ * Pure (no I/O) so it is trivially testable and identical across hosts.
+ */
+
+export function capabilitiesText(): string {
+	return [
+		"Viber control plane (vibe-master) — orchestrate other agents from this machine.",
+		"",
+		"vibe-master is a CLI + TUI (installed on the operator machine) that spawns and",
+		"supervises agents which appear in the Viber web UI and answer in their own",
+		"conversations. Use it when you want to delegate to another agent (e.g. a Codex",
+		"reviewer, a second Claude, or a Gemma chat).",
+		"",
+		"Runtimes: codex (background, via vctl) · gemma (background) · claude (terminal).",
+		"(--runtime defaults to codex. Gemma is conversational/read-only only — it",
+		" rejects --permission read-write.)",
+		"",
+		"Spawn one agent (CLI, non-interactive):",
+		"  vibe-master spawn --permission <read-only|read-write> \\",
+		"                    [--runtime codex|claude|gemma] [--name <id>]",
+		"  → only --permission is required; --runtime and --name are optional",
+		"    (--name auto-generated if omitted). Prints the agent id; it registers",
+		"    in Viber and comes online.",
+		"",
+		"Interactive: `vibe-master tui` (menu: + Add agent → runtime → permission → name).",
+		"Inspect / stop: `vibe-master list` · `vibe-master kill <id>`.",
+		"",
+		"Talk to a spawned agent from here with list_agents + message_agent.",
+		"Requires vibe-master installed on the machine (see the Install page on the web).",
+		"Run `vibe-master --help` for the full command reference.",
+	].join("\n");
+}

package/lib/lockfile.ts

@@ -14,8 +14,8 @@
  * 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
+ * #259 adds the per-instance axis: when a launcher 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

package/lib/messages.ts

@@ -95,6 +95,37 @@ export async function fetchMessages(
   return Array.isArray(body.messages) ? body.messages : [];
 }
 
+/**
+ * POST /api/conversations/:id/messages/:messageId/ack — read-acknowledgement (#346).
+ *
+ * The bridge CODE (not the LLM) confirms receipt of a web→agent message so the
+ * web UI can show a "reçu" checkmark, with zero impact on agent reply latency.
+ *
+ * Best-effort and NON-BLOCKING: never throws. Any failure (network, 401 expired
+ * token, 404 for a message the Worker deems non-ackable) resolves to `false` so
+ * the message-handling flow is never disrupted by the ACK. Idempotence is owned
+ * by the Worker (PK + INSERT OR IGNORE), so re-acking on reconnect is safe.
+ */
+export async function ackMessage(
+  baseUrl: string,
+  conversationId: string,
+  conversationToken: string,
+  messageId: string | number,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  const url = `${baseUrl}/api/conversations/${conversationId}/messages/${messageId}/ack`;
+  try {
+    const resp = await fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${conversationToken}`, ...cfAccessHeaders() },
+      signal,
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
 export interface MessagePostSuccess {
   ok: true;
   message_id: string;

package/lib/version_check.ts

@@ -0,0 +1,124 @@
+/**
+ * viber-channel stale-version guard (#330).
+ *
+ * A globally-installed `viber-channel` that a user placed by hand (old docs) can
+ * fall far behind npm `latest`. When a later refactor removes/renames a lib file,
+ * that stale install crashes with a raw `Cannot find module './lib/…'` instead of
+ * anything actionable. We can't fix an ALREADY-broken old install from here (its
+ * code predates this guard), so the useful move is PREVENTION: on every startup
+ * that still runs, check whether the installed version is behind `latest` and, if
+ * so, print a clear one-line nudge to update — BEFORE the user ever hits a
+ * breaking refactor. Best-effort and non-fatal: any error (offline, timeout, odd
+ * registry response) is swallowed so the channel starts normally.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const NPM_LATEST_URL = "https://registry.npmjs.org/viber-channel/latest";
+const DEFAULT_TIMEOUT_MS = 1500;
+
+/** Parse a `major.minor.patch` string to a numeric tuple; non-numeric → 0. */
+function parseVersion(v: string): [number, number, number] {
+	const parts = v
+		.trim()
+		.replace(/^v/, "")
+		.split(".")
+		.map((p) => Number.parseInt(p, 10));
+	return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+}
+
+/** True iff `local` is strictly older than `latest` (major.minor.patch order). */
+export function isOlder(local: string, latest: string): boolean {
+	const a = parseVersion(local);
+	const b = parseVersion(latest);
+	for (let i = 0; i < 3; i++) {
+		if (a[i] < b[i]) return true;
+		if (a[i] > b[i]) return false;
+	}
+	return false;
+}
+
+/** Read this package's own version from its package.json (best-effort → null). */
+export function readLocalVersion(
+	readFile: (p: string) => string = (p) => readFileSync(p, "utf-8"),
+	dir: string = import.meta.dir,
+): string | null {
+	try {
+		const pkg = JSON.parse(readFile(join(dir, "..", "package.json")));
+		return typeof pkg.version === "string" ? pkg.version : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Fetch npm `latest` version with a short timeout; null on any failure. */
+export async function fetchLatestVersion(
+	timeoutMs: number = DEFAULT_TIMEOUT_MS,
+	fetchImpl: typeof fetch = fetch,
+): Promise<string | null> {
+	const ctrl = new AbortController();
+	const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+	try {
+		const res = await fetchImpl(NPM_LATEST_URL, { signal: ctrl.signal });
+		if (!res.ok) return null;
+		const body = (await res.json()) as { version?: unknown };
+		return typeof body.version === "string" ? body.version : null;
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+export interface StaleCheck {
+	local: string;
+	latest: string;
+	stale: boolean;
+}
+
+/** Compare the installed version against npm latest. Null when either is unknown. */
+export async function checkStaleVersion(opts?: {
+	localVersion?: string | null;
+	fetchLatest?: () => Promise<string | null>;
+}): Promise<StaleCheck | null> {
+	// Honor an EXPLICIT localVersion (incl. null = "unknown"); only read the real
+	// package.json when the caller didn't pass the key at all.
+	const local =
+		opts && "localVersion" in opts ? opts.localVersion : readLocalVersion();
+	if (!local) return null;
+	const latest = opts?.fetchLatest
+		? await opts.fetchLatest()
+		: await fetchLatestVersion();
+	if (!latest) return null;
+	return { local, latest, stale: isOlder(local, latest) };
+}
+
+/** The one-line nudge printed to stderr when the install is behind. */
+export function staleWarning(local: string, latest: string): string {
+	return (
+		`[viber-channel] version ${local} is behind latest ${latest}. ` +
+		`Update to avoid a broken install: bun add -g viber-channel@latest`
+	);
+}
+
+/**
+ * Best-effort: warn on stderr when this install is behind npm latest. Never
+ * throws, never blocks longer than the fetch timeout. Called at startup.
+ */
+export async function warnIfStale(opts?: {
+	localVersion?: string | null;
+	fetchLatest?: () => Promise<string | null>;
+	write?: (msg: string) => void;
+}): Promise<void> {
+	try {
+		const check = await checkStaleVersion(opts);
+		if (check?.stale) {
+			(opts?.write ?? ((m) => process.stderr.write(`${m}\n`)))(
+				staleWarning(check.local, check.latest),
+			);
+		}
+	} catch {
+		/* best-effort — never break startup on a version check */
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "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

@@ -16,9 +16,9 @@
  *
  *   claude --dangerously-load-development-channels server:<name>
  *
- * Two PowerShell launchers wrap the right flag:
- *   - viber.ps1       → server:viber-channel (staging)
- *   - viber-dev.ps1   → server:viber-dev-channel (this repo, dev)
+ * For dev in this repo, vibe-master-dev.ps1 (the multi-agent TUI launcher) wraps
+ * the flag: `server:viber-dev-channel` against the dev backend. Staging sessions
+ * use the plain user-scoped `viber-channel` registration with no launcher flag.
  *
  * CLI subcommand: `bunx viber-channel connect <claim_url>` runs the one-shot
  * claim flow that writes .viber/auth.json without requiring any Claude Code
@@ -54,6 +54,9 @@ import {
   type TokenRefreshScheduler,
 } from "./lib/token_refresh.ts";
 import { awaitStableStartup } from "./lib/startup_gate.ts";
+import { agentIdentityFromEnv } from "./lib/bridge_core.ts";
+import { warnIfStale } from "./lib/version_check.ts";
+import { capabilitiesText } from "./lib/capabilities.ts";
 
 // ---- CLI subcommand dispatch (must happen before lock acquire + loadAuth) ----
 //
@@ -98,6 +101,11 @@ import { awaitStableStartup } from "./lib/startup_gate.ts";
       );
       process.exit(1);
     }
+    // #330: this is the exact path that crashed on a stale hand-placed install
+    // (`bunx viber-channel connect` → missing ./lib/peers.ts). Await the check
+    // here so the "you're behind, update" nudge shows BEFORE the connect work
+    // (best-effort — never throws, short timeout).
+    await warnIfStale();
     try {
       await runConnect(claimUrl);
       process.exit(0);
@@ -108,6 +116,11 @@ import { awaitStableStartup } from "./lib/startup_gate.ts";
   }
 }
 
+// Server path (fell through the dispatch block): warn if this install is behind
+// npm latest, but fire-and-forget so it never delays mcp.connect — the nudge
+// lands on stderr shortly after startup (#330).
+void warnIfStale();
+
 // Lock file path: %APPDATA%/viber/ (Windows) or ~/.config/viber/ (Linux/Mac).
 // Namespaced by (VIBER_BASE_URL, client_fingerprint, VIBER_CHANNEL_SESSION_ID) so:
 //   - channels at different backends (staging + dev) coexist (different base_url);
@@ -319,7 +332,7 @@ import {
   RefreshHttpError,
   RefreshNetworkError,
 } from "./lib/conversation.ts";
-import { ConversationTokenExpiredError } from "./lib/messages.ts";
+import { ackMessage, ConversationTokenExpiredError } from "./lib/messages.ts";
 import {
   listAgents as libListAgents,
   messageAgent as libMessageAgent,
@@ -340,18 +353,32 @@ const mcp = new Server(
       experimental: { "claude/channel": {} },
       tools: {},
     },
+    // #369 truncation fix: Claude Code truncates long MCP `instructions`
+    // ("…[truncated]") and this blob was ~3 KB → the TAIL was dropped before the
+    // agent saw it (that hid the agent's name #328, and threatened the #332
+    // pointer + exit-intent). So: CRITICAL lines are FRONT-LOADED (identity →
+    // core reply → actions/questions → anti-deadlock → capabilities → exit) and
+    // the nice-to-have style notes live at the tail where a cut is harmless.
+    // Condensed vs the old prose (same substance — reviewed). Identity is "" for
+    // JP's own session (no explicit-name flag) → the identity LINE is filtered
+    // out for him; the rest of the (now shorter, reordered) blob applies to every
+    // session including his.
     instructions: [
-      'Voice transcripts arrive as <channel source="viber-channel"> events carrying the user\'s microphone speech.',
-      "Reply with send_message. You are talking to a human who both LISTENS (the `text` is read aloud by TTS) AND READS it on screen (the `text` is ALSO rendered as Markdown in the UI). So aim for both: it must sound natural read aloud AND be easy to read. Lead with the answer, no preamble or recap.",
-      "USE light Markdown in `text` when it makes the message easier to read: short bullet lists (`- `), numbered steps (`1.`), checklists, **bold** for key terms. A short list reads aloud just fine — a spoken list is natural. Don't cram several points into one dense paragraph; break them out. Avoid heavy/awkward-to-speak markup (big tables, code blocks, long fenced snippets) in `text` — that belongs in the artifact.",
-      "ACTIONS and QUESTIONS belong in `text`, made visible — never bury them in the artifact. If you need a decision, ask it clearly in `text` (a short bullet list of the options is good); the artifact may hold supporting detail but the question itself must be in `text` where it jumps out.",
-      "The `artifact` is for HEAVY or LONG content only: big code, large tables, long multi-point analyses, review dumps, JSON, file lists. When you use an artifact, keep `text` a brief spoken summary that points to it ('details on the side') — don't read the heavy content aloud.",
-      "Write identifiers LITERALLY with their real characters (288, auth.json, viber-dev.dgypx.dev, CONVERSATION_TOKEN) — never spell them out as 'point'/'dash' and never as awkward digit-by-digit text. A lone long token or path is better placed in the artifact than spoken.",
-      "Artifact 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 send executable JS.",
-      "NO EMOJI in `text` — it is read aloud, so an emoji becomes spoken noise (a check mark is read as 'check mark'). Use plain Markdown (bullets, bold) for structure instead. Emoji are tolerable only inside an artifact (not spoken).",
-      "Rule of thumb: short and conversational, but readable — break points into a list rather than a wall of text; reserve the artifact for what is genuinely long or heavy.",
+      agentIdentityFromEnv(),
+      // --- critical: front-loaded so truncation can never drop them ---
+      'Voice transcripts arrive as <channel source="viber-channel"> events (the user\'s microphone speech). Reply with send_message. The `text` is BOTH read aloud (TTS) AND shown as Markdown — make it natural aloud AND easy to read; lead with the answer, no preamble.',
+      "Put ACTIONS and QUESTIONS in `text`, visibly — never bury them in the artifact. Use light Markdown (short bullet/numbered lists, **bold**) to stay readable; a short spoken list is fine.",
+      // #343 anti-deadlock (hands-free: the user is NOT watching the terminal).
+      "CRITICAL — while this channel is active, NEVER block on a terminal prompt or AskUserQuestion: the user is hands-free and cannot see the terminal, so it deadlocks. Put EVERY question or choice in send_message `text` and take the answer from the next voice transcript.",
+      // #332 discoverability pointer (the how-to lives in the capabilities tool).
+      "To orchestrate or spawn OTHER agents (Codex, Claude, Gemma) on this machine, call the `capabilities` tool for how — only when relevant.",
       "On exit intent (bye, au revoir, stop) call stop_conversation(), speak a brief farewell, and stop.",
-    ].join(" "),
+      // --- nice-to-have style notes (safe near the tail) ---
+      "The `artifact` (format: markdown default, or code/json/html) is for HEAVY/LONG content (big code, large tables, long analyses, JSON, file lists); keep `text` a brief spoken summary that points to it ('details on the side'). Scripts/event handlers are stripped server-side.",
+      "NO EMOJI in `text` (read aloud — an emoji becomes spoken noise). Write identifiers LITERALLY (288, auth.json, viber-dev.dgypx.dev) — never spell out dots/dashes; a lone long token or path is better placed in the artifact.",
+    ]
+      .filter((line) => line.length > 0)
+      .join(" "),
   }
 );
 
@@ -438,6 +465,20 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         additionalProperties: false,
       },
     },
+    {
+      name: "capabilities",
+      description:
+        "On-demand: learn what the Viber control plane (vibe-master) can do on this " +
+        "machine — how to spawn and supervise OTHER agents (Codex, Claude, Gemma). " +
+        "Call this only when orchestrating other agents is relevant; it is not part " +
+        "of the default context. Returns a short usage reference.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {},
+        required: [],
+        additionalProperties: false,
+      },
+    },
   ],
 }));
 
@@ -478,6 +519,11 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
     return libMessageAgent(channelToolsCtx, args);
   }
 
+  // #332: on-demand control-plane discovery — static help, no runtime state.
+  if (request.params.name === "capabilities") {
+    return { content: [{ type: "text" as const, text: capabilitiesText() }] };
+  }
+
   if (request.params.name !== "send_message") {
     return {
       isError: true,
@@ -829,7 +875,7 @@ try {
 // ---- Channel ready banner ----
 
 process.stderr.write(
-  `[viber-channel] Channel ready: 3 tools (send_message, list_agents, message_agent), SSE on /api/conversations/${CONVERSATION_ID}/events\n`
+  `[viber-channel] Channel ready: 4 tools (send_message, list_agents, message_agent, capabilities), SSE on /api/conversations/${CONVERSATION_ID}/events\n`
 );
 
 // Channel liveness is proven by the INSTANCE heartbeat (#311, started above), not
@@ -876,6 +922,43 @@ async function pushTranscript(text: string, lang: string): Promise<void> {
 // mechanism, surfaced by the #254 Active section that keeps the UI open).
 const messageDedup = new MessageDedup();
 
+// #346 read-ACK bookkeeping for the Claude MCP channel (mirrors bridge_core's
+// ackInboundReceipt, which only covers the Codex/Gemma bridges). Tracks confirmed
+// ACKs so we don't re-POST on SSE replay; in-flight set avoids a double-POST race.
+const ackedMessageIds = new Set<string>();
+const ackInFlightMessageIds = new Set<string>();
+
+/**
+ * Emit a read-acknowledgement for a web→agent message received on the main
+ * conversation (#346). Run by the channel CODE (not the LLM), fire-and-forget,
+ * so the web "reçu" checkmark has zero impact on reply latency. Only
+ * role=user|user_voice with no sender_instance_id qualify (mirrors the Worker,
+ * which is the source of truth and 404s anything else). Idempotent server-side,
+ * so re-acking on reconnect is safe; ackedMessageIds is only set on a confirmed
+ * success so a failed ACK is retried on the next delivery. Never throws.
+ */
+function ackInboundReceipt(msg: {
+  id?: string | number | null;
+  role?: string;
+  sender_instance_id?: string | null;
+}): void {
+  if (msg.role !== "user" && msg.role !== "user_voice") return;
+  if (msg.sender_instance_id) return;
+  // The SSE "message" payload carries the D1 id as a NUMBER (MessageResponse.id).
+  // Coerce like bridge_core's ackInboundReceipt — a strict string check would
+  // bail on every real message and never ack.
+  const idStr = msg.id !== undefined && msg.id !== null ? String(msg.id) : undefined;
+  if (!idStr) return;
+  if (ackedMessageIds.has(idStr) || ackInFlightMessageIds.has(idStr)) return;
+  ackInFlightMessageIds.add(idStr);
+  void ackMessage(BASE_URL, CONVERSATION_ID, CONVERSATION_TOKEN, idStr)
+    .then((ok) => {
+      if (ok) ackedMessageIds.add(idStr);
+      else process.stderr.write(`[viber-channel] ack failed for message ${idStr} (will retry on next delivery)\n`);
+    })
+    .finally(() => ackInFlightMessageIds.delete(idStr));
+}
+
 /**
  * Forward a saved conversation message from the event bus to Claude.
  *
@@ -1084,6 +1167,9 @@ async function sseLoop(): Promise<void> {
                 sender_instance_id?: string | null;
               };
               if (msg.content) {
+                // #346: confirm receipt to the web BEFORE forwarding to the LLM
+                // and independently of any reply — decoupled from reply latency.
+                ackInboundReceipt(msg);
                 await pushMessage(msg);
               } else {
                 process.stderr.write(`[viber-channel] 'message' event has empty content\n`);