viber-channel 0.8.7 → 0.8.9

package/lib/bridge_core.ts

@@ -15,6 +15,7 @@
  */
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { createTokenRefreshScheduler, type TokenRefreshScheduler } from "./token_refresh.js";
+import type { ApiBaseUrlResolver } from "./base_urls.js";
 import { lockFilePath } from "./lockfile.js";
 import {
 	type ConversationMintResponse,
@@ -46,6 +47,21 @@ export interface ConversationMessage {
 	sender_instance_id?: string | null;
 }
 
+/**
+ * Persistent cross-run dedup watermark for ONE conversation (#429, mirror of
+ * `DmWatermark` in dm_stream.ts). Holds the highest message id already DELIVERED
+ * (replied to) in a prior run of this conversation's stream. The caller keeps one
+ * per `convId` and passes it back on every re-join, so it SURVIVES the
+ * abort+restart cycle `runConversationStream` does on a re-pushed join — unlike
+ * the run-scoped `handledIds` (fresh + empty each run). Without it the first
+ * await-invite pass re-forwards (re-replies to) the most recent trigger on every
+ * re-spawn/rejoin. Mutated in place. `0` = nothing delivered yet.
+ */
+export interface BridgeWatermark {
+	/** Highest delivered (replied-to) message id (0 = nothing delivered yet). */
+	lastId: number;
+}
+
 /** One live conversation stream's mutable runtime state (token rotates). */
 export interface ConversationRuntime {
 	id: string;
@@ -163,15 +179,21 @@ export function isProcessAlive(pid: number): boolean {
  * bridge's log lines under its own tag.
  */
 export function acquireBridgeLock(opts: {
-	baseUrl: string;
+	/**
+	 * #480: the LOGICAL backend identity, NOT the API transport host. The lock
+	 * path must stay stable when agent traffic is redirected, otherwise a running
+	 * agent stops recognizing its own lock and the #311/#293 duplicate window
+	 * re-opens. Injected rather than read from the env so this stays pure.
+	 */
+	identityBaseUrl: string;
 	fingerprint: string;
 	sessionId: string;
 	lockDir: string;
 	logPrefix: string;
 }): BridgeLock {
-	const { baseUrl, fingerprint, sessionId, lockDir, logPrefix } = opts;
+	const { identityBaseUrl, fingerprint, sessionId, lockDir, logPrefix } = opts;
 	mkdirSync(lockDir, { recursive: true });
-	const path = lockFilePath(baseUrl, fingerprint, sessionId, lockDir);
+	const path = lockFilePath(identityBaseUrl, fingerprint, sessionId, lockDir);
 	const release = (): void => {
 		try {
 			unlinkSync(path);
@@ -235,11 +257,12 @@ function refreshLeadSeconds(logPrefix: string): number | undefined {
 export function startTokenRefresh(opts: {
 	runtime: ConversationRuntime;
 	fingerprint: string;
-	baseUrl: string;
+	/** #480 — long-lived scheduler: read the host per refresh, never capture it. */
+	getBaseUrl: () => string;
 	requestShutdown: (err: BridgeShutdownError) => void;
 	logPrefix: string;
 }): TokenRefreshScheduler {
-	const { runtime, fingerprint, baseUrl, requestShutdown, logPrefix } = opts;
+	const { runtime, fingerprint, getBaseUrl, requestShutdown, logPrefix } = opts;
 	const leadSeconds = refreshLeadSeconds(logPrefix);
 	const scheduler = createTokenRefreshScheduler(
 		async () => {
@@ -247,7 +270,7 @@ export function startTokenRefresh(opts: {
 			const headroomSeconds = 10;
 			for (let attempt = 1; attempt <= maxAttempts; attempt++) {
 				try {
-					const refreshed = await refreshConversationToken(baseUrl, runtime.id, runtime.token, fingerprint);
+					const refreshed = await refreshConversationToken(getBaseUrl(), runtime.id, runtime.token, fingerprint);
 					runtime.token = refreshed.conversation_token;
 					runtime.expiresAt = refreshed.expires_at;
 					process.stderr.write(`${logPrefix} token refreshed for conversation ${runtime.id}\n`);
@@ -333,6 +356,32 @@ export function decideTurnPostAction(opts: {
 	return "auto-post";
 }
 
+/**
+ * #429 cross-run dedup, mirror of dm_stream's `forwardMessage` guard (L146-147).
+ * True when this id was already DELIVERED in a prior run and must be skipped on a
+ * re-join. The D1 message id is `INTEGER PRIMARY KEY AUTOINCREMENT` (migration
+ * 0009) → strictly increasing, never reused, so anything at or below the watermark
+ * was already handled. `Number.isSafeInteger` (not `isFinite`) gate: an id beyond
+ * 2^53 — where `Number()` loses precision and could collide — falls through to
+ * normal handling instead of being mis-gated. No watermark / absent / NaN id →
+ * never skips. Pure + exported for unit tests (pattern `decideTurnPostAction`).
+ */
+export function watermarkShouldSkip(numId: number, watermark?: BridgeWatermark): boolean {
+	return !!watermark && Number.isSafeInteger(numId) && numId <= watermark.lastId;
+}
+
+/**
+ * #429 advance the cross-run watermark after a SUCCESSFUL delivery (mirror of
+ * dm_stream L166-168). Monotone: only ever moves forward, so a brief overlap of
+ * two streams during supersession can't regress it. Same `Number.isSafeInteger`
+ * gate; a NaN/absent/unsafe id is never watermarked. Pure + exported.
+ */
+export function watermarkAdvance(numId: number, watermark?: BridgeWatermark): void {
+	if (watermark && Number.isSafeInteger(numId) && numId > watermark.lastId) {
+		watermark.lastId = numId;
+	}
+}
+
 /** Bearer + fingerprint + CF Access headers for a conversation request. */
 function conversationHeaders(conversationToken: string, fingerprint: string): Record<string, string> {
 	return {
@@ -378,9 +427,25 @@ export interface ConversationStreamDeps {
 	options: SseLoopOptions;
 	/** Registry of live streams (keyed by conversation id) — re-join supersedes. */
 	activeStreams: Map<string, AbortController>;
+	/**
+	 * Registry of persistent per-conversation watermarks (#429). Keyed by
+	 * conversation id. UNLIKE `activeStreams`, this MUST survive the abort+restart
+	 * on re-join (never deleted in the stream's finally) — that persistence is the
+	 * whole point of the cross-run dedup.
+	 */
+	watermarks: Map<string, BridgeWatermark>;
 	/** Global shutdown signal — aborting it stops every stream. */
 	parentSignal: AbortSignal;
-	baseUrl: string;
+	/**
+	 * #480: the API host as STATE, not a string. Passing the resolver rather than
+	 * a captured value is what lets a long-lived stream follow the host the server
+	 * announces mid-run; a `string` here would freeze the bootstrap host for the
+	 * whole run. It also removes the swap hazard a second `string` field next to
+	 * `identityBaseUrl` would create.
+	 */
+	api: ApiBaseUrlResolver;
+	/** Logical backend identity — what the session handle is keyed on (#480). */
+	identityBaseUrl: string;
 	lockDir: string;
 	logPrefix: string;
 	/** Session-handle tag distinguishing runtimes in the handle path (codex/gemma). */
@@ -405,7 +470,9 @@ export async function runConversationStream(
 	minted: ConversationMintResponse,
 	deps: ConversationStreamDeps,
 ): Promise<void> {
-	const { fingerprint, instanceKey, options, activeStreams, parentSignal, baseUrl, lockDir, logPrefix, sessionTag, makeRunTurn } = deps;
+	const { fingerprint, instanceKey, options, activeStreams, watermarks, parentSignal, api, identityBaseUrl, lockDir, logPrefix, sessionTag, makeRunTurn } = deps;
+	// #480: a FUNCTION, not a captured string — the host can change mid-stream.
+	const baseUrl = (): string => api.current();
 	const convId = minted.conversation_id;
 	if (parentSignal.aborted) return;
 
@@ -430,12 +497,14 @@ export async function runConversationStream(
 		parentSignal.addEventListener("abort", onParentAbort, { once: true });
 		// Per-conversation resume handle, keyed by conversation id so a secondary DM
 		// never clobbers the main conversation's handle.
-		writeHandle(sessionFilePath(baseUrl, `${instanceKey}:${sessionTag}:${convId}`, lockDir), convId);
+		// #480: keyed on the identity, not the transport host — a redirected agent
+		// must find the SAME handle and resume its conversation, not mint a new one.
+		writeHandle(sessionFilePath(identityBaseUrl, `${instanceKey}:${sessionTag}:${convId}`, lockDir), convId);
 		// Token-refresh failure aborts ONLY this stream, not the whole bridge.
 		startTokenRefresh({
 			runtime,
 			fingerprint,
-			baseUrl,
+			getBaseUrl: baseUrl,
 			requestShutdown: (err) => {
 				if (!ctrl.signal.aborted) ctrl.abort(err);
 			},
@@ -443,7 +512,15 @@ export async function runConversationStream(
 		});
 		const runTurn = await makeRunTurn(convId, runtime, ctrl.signal);
 		process.stderr.write(`${logPrefix} stream ready for ${convId}\n`);
-		await sseLoop({ minted, runtime, fingerprint, ownInstanceKey: instanceKey, options, signal: ctrl.signal, baseUrl, logPrefix, runTurn });
+		// Get-or-create the persistent watermark for this conversation. It lives in
+		// the caller-owned `watermarks` registry so it SURVIVES this stream's
+		// abort+restart on re-join (the finally below deliberately does NOT delete it).
+		let watermark = watermarks.get(convId);
+		if (!watermark) {
+			watermark = { lastId: 0 };
+			watermarks.set(convId, watermark);
+		}
+		await sseLoop({ minted, runtime, fingerprint, ownInstanceKey: instanceKey, options, signal: ctrl.signal, getBaseUrl: baseUrl, logPrefix, runTurn, watermark });
 	} finally {
 		parentSignal.removeEventListener("abort", onParentAbort);
 		runtime.scheduler?.cancel();
@@ -481,11 +558,26 @@ export async function sseLoop(opts: {
 	ownInstanceKey: string;
 	options: SseLoopOptions;
 	signal: AbortSignal;
-	baseUrl: string;
+	/** #480 — the loop outlives the announcement; read the host per use. */
+	getBaseUrl: () => string;
 	logPrefix: string;
 	runTurn: RunTurn;
+	/**
+	 * Persistent cross-run watermark for this conversation (#429). When present,
+	 * a re-join skips re-replying to any message id already delivered in a prior
+	 * run. Unused in step-01 (plumbing only); the guard/advance lands in step-02.
+	 * `runConversationStream` always passes it; a direct test caller may omit it.
+	 */
+	watermark?: BridgeWatermark;
+	/** Injectable for tests; defaults to global fetch (mirror dm_stream). */
+	fetchImpl?: typeof fetch;
+	/** Injectable catch-up fetch; defaults to messages.ts `fetchMessages`. */
+	fetchMessagesImpl?: typeof fetchMessages;
 }): Promise<void> {
-	const { minted, runtime, fingerprint, ownInstanceKey, options, signal, baseUrl, logPrefix, runTurn } = opts;
+	const { minted, runtime, fingerprint, ownInstanceKey, options, signal, getBaseUrl, logPrefix, runTurn, watermark } = opts;
+	const baseUrl = getBaseUrl; // called at each use below
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const fetchMessagesImpl = opts.fetchMessagesImpl ?? fetchMessages;
 	const sseUrl = buildSseUrl(minted.ws_url, minted.conversation_id);
 	const ownPostedIds = new Set<string>();
 
@@ -522,7 +614,7 @@ export async function sseLoop(opts: {
 				process.stderr.write(`${logPrefix} turn on ${runtime.id} produced no text and used no outbound tool; nothing to deliver\n`);
 				return false;
 			case "auto-post":
-				await postBridgeReply({ baseUrl, runtime, text: reply, ownPostedIds, signal, logPrefix });
+				await postBridgeReply({ baseUrl: baseUrl(), runtime, text: reply, ownPostedIds, signal, logPrefix });
 				return false;
 		}
 	}
@@ -563,7 +655,7 @@ export async function sseLoop(opts: {
 		if (!idStr) return;
 		if (ackedIds.has(idStr) || ackInFlightIds.has(idStr)) return;
 		ackInFlightIds.add(idStr);
-		void ackMessage(baseUrl, runtime.id, runtime.token, idStr, signal)
+		void ackMessage(baseUrl(), runtime.id, runtime.token, idStr, signal, fetchImpl)
 			.then((ok) => {
 				if (ok) ackedIds.add(idStr);
 				else process.stderr.write(`${logPrefix} ack failed for message ${idStr} (will retry on reconnect)\n`);
@@ -573,10 +665,18 @@ export async function sseLoop(opts: {
 
 	async function handleInboundMessage(msg: ConversationMessage): Promise<boolean> {
 		const idStr = msg.id !== undefined && msg.id !== null ? String(msg.id) : undefined;
+		// TRUTHY check (not `!== undefined`): idStr === "" must yield NaN, not
+		// Number("") === 0, so a blank id never satisfies the `<= lastId` guard.
+		const numId = idStr ? Number(idStr) : Number.NaN;
 		// 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);
+		// #429 cross-run dedup: a re-join re-delivers the trigger; skip replying to
+		// anything already delivered in a prior run. Placed AFTER ackInboundReceipt
+		// so the #346 read-ACK still fires on a re-delivered trigger, only the reply
+		// is suppressed (mirror of dm_stream; handledIds still gates the intra-run dup).
+		if (watermarkShouldSkip(numId, watermark)) return false;
 		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
@@ -590,6 +690,12 @@ export async function sseLoop(opts: {
 		try {
 			const aborted = await replyForTurn(msg.content!, msg);
 			if (aborted) return false;
+			// #429 advance ONLY after a non-aborted reply (delivered — incl.
+			// suppress-outbound and skip-empty). INSIDE the try, after the abort
+			// check, never in catch/finally: a thrown reply (caught below) is a
+			// failed delivery → NO advance, so it retries on the next re-join
+			// (at-least-once, same asymmetry as dm_stream's watermark).
+			watermarkAdvance(numId, watermark);
 		} catch (err) {
 			if (err instanceof BridgeShutdownError) throw err;
 			process.stderr.write(`${logPrefix} failed to handle message: ${safeErrorMessage(err)}\n`);
@@ -607,7 +713,7 @@ export async function sseLoop(opts: {
 			// is the SSE/voice host (the CF tunnel in staging/prod). Using ws_url here
 			// 404s whenever the SSE host differs from the API host (masked in dev where
 			// they collapse to one origin). The SSE subscription still uses ws_url.
-			msgs = await fetchMessages(baseUrl, minted.conversation_id, runtime.token);
+			msgs = await fetchMessagesImpl(baseUrl(), minted.conversation_id, runtime.token);
 		} catch (err) {
 			if (err instanceof ConversationTokenExpiredError) throw err;
 			process.stderr.write(`${logPrefix} catch-up fetch failed: ${safeErrorMessage(err)}\n`);
@@ -660,7 +766,7 @@ export async function sseLoop(opts: {
 			requestHeaders.Accept = "text/event-stream";
 			process.stderr.write(`${logPrefix} connecting to SSE: ${sseUrl}\n`);
 
-			const resp = await fetch(sseUrl, { headers: requestHeaders, signal });
+			const resp = await fetchImpl(sseUrl, { headers: requestHeaders, signal });
 			if (resp.status === 401) throw new ConversationTokenExpiredError();
 			if (!resp.ok || !resp.body) throw new Error(`SSE connection failed: HTTP ${resp.status}`);
 
@@ -774,9 +880,69 @@ export function sanitizeAgentRole(raw: string | undefined): string {
 			return code < 0x20 || code === 0x7f ? " " : ch;
 		})
 		.join("");
-	const stripped = noCtrl.replace(/\s+/g, " ").trim();
-	if (stripped.length <= MAX_ROLE_LENGTH) return stripped;
-	return stripped.slice(0, MAX_ROLE_LENGTH).trimEnd();
+	const stripped = normalizeEscapables(noCtrl.replace(/\s+/g, " ").trim());
+	return capUtf16Safe(stripped, MAX_ROLE_LENGTH);
+}
+
+/**
+ * Normalize the two characters `JSON.stringify` expands MOST in practice (#479): a quote
+ * becomes an apostrophe, a backslash a forward slash. Both stay readable —
+ * `C:\Users` → `C:/Users`, `the "taskman" skill` → `the 'taskman' skill` — and
+ * neither `'` nor `/` is escaped, so a 600-char role can no longer encode to 1200
+ * and blow the instructions budget. Removing them outright would corrupt paths and
+ * citations; rewriting them keeps the meaning and bounds the length.
+ *
+ * They are not the ONLY expanding inputs: control characters (already turned into
+ * spaces by the callers) and a LONE SURROGATE (escaped as `\udXXX` — six chars for
+ * one code unit) also grow. Unpaired surrogates are therefore dropped here, and
+ * `capUtf16Safe` below makes sure the length cap never creates a new one. Between
+ * the two, no input can make the encoded text longer than the raw text.
+ */
+function normalizeEscapables(text: string): string {
+	return dropLoneSurrogates(text).replaceAll('"', "'").replaceAll("\\", "/");
+}
+
+/**
+ * Drop UNPAIRED surrogates (#479 opus review). `capUtf16Safe` stops the cap from
+ * CREATING one, but an unpaired unit already present in the input would sail
+ * through and encode to `\udXXX` — six chars for one unit, so a 600-char role could
+ * still reach ~3600 encoded. Dropping them closes the last expansion path, which is
+ * what makes IDENTITY_BUDGET exact for ANY input and the clip a true never-path.
+ * A lone surrogate carries no text anyway: it is a broken half-character.
+ */
+function dropLoneSurrogates(text: string): string {
+	let out = "";
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		const isHigh = code >= 0xd800 && code <= 0xdbff;
+		const isLow = code >= 0xdc00 && code <= 0xdfff;
+		if (isHigh) {
+			const next = text.charCodeAt(i + 1);
+			if (next >= 0xdc00 && next <= 0xdfff) {
+				out += text[i] + text[i + 1];
+				i++;
+			}
+			continue; // unpaired high → dropped
+		}
+		if (isLow) continue; // unpaired low → dropped
+		out += text[i];
+	}
+	return out;
+}
+
+/**
+ * Cap `text` to `max` UTF-16 units WITHOUT leaving a lone surrogate behind
+ * (codex-479 review): a plain `slice` can cut an emoji in half, and a lone
+ * surrogate is itself escaped by `JSON.stringify` (`\udXXX`) — the very expansion
+ * the normalization above exists to prevent, plus an unpaired code unit in the
+ * prompt. The cap stays in UTF-16 units so `IDENTITY_BUDGET` remains exact.
+ */
+function capUtf16Safe(text: string, max: number): string {
+	if (text.length <= max) return text;
+	const cut = text.slice(0, max);
+	const last = cut.charCodeAt(cut.length - 1);
+	const orphanHighSurrogate = last >= 0xd800 && last <= 0xdbff;
+	return (orphanHighSurrogate ? cut.slice(0, -1) : cut).trimEnd();
 }
 
 /** Max explicit-name length after sanitization (chars). */
@@ -797,8 +963,8 @@ export function sanitizeAgentName(raw: string | undefined): string {
 			return code < 0x20 || code === 0x7f ? " " : ch;
 		})
 		.join("");
-	const stripped = noCtrl.replace(/\s+/g, " ").trim();
-	return stripped.length <= MAX_NAME_LENGTH ? stripped : stripped.slice(0, MAX_NAME_LENGTH).trimEnd();
+	const stripped = normalizeEscapables(noCtrl.replace(/\s+/g, " ").trim());
+	return capUtf16Safe(stripped, MAX_NAME_LENGTH);
 }
 
 /**
@@ -824,6 +990,13 @@ export function sanitizeAgentName(raw: string | undefined): string {
 export function buildAgentIdentityInstructions(opts: {
 	explicitName?: string;
 	role?: string;
+	/**
+	 * Hard ceiling (chars) for the RENDERED line (#479). The MCP client truncates
+	 * long `instructions`, so the identity line must not eat the channel-contract
+	 * budget: the caller reserves a slice and we fit into it OURSELVES rather than
+	 * letting the client cut wherever it lands. Omitted = no ceiling.
+	 */
+	budget?: number;
 }): string {
 	const name = sanitizeAgentName(opts.explicitName);
 	const role = sanitizeAgentRole(opts.role);
@@ -835,8 +1008,57 @@ export function buildAgentIdentityInstructions(opts: {
 	const nameClause = name
 		? ` Your explicit spawn name is ${JSON.stringify(name)}; if asked your name, answer with it.`
 		: " You do not have an explicit agent name, so do not invent one if asked.";
-	const roleClause = role ? ` Your assigned role is ${JSON.stringify(role)}.` : "";
-	return `${guard}${nameClause}${roleClause}`;
+
+	// The guard and the name are NEVER trimmed (#328: an agent that lost its name
+	// is the bug this line exists to prevent; a half-quoted guard would weaken the
+	// "descriptive DATA" framing). Only the role clause absorbs the budget.
+	const fixed = `${guard}${nameClause}`;
+	const roleClause = role ? renderRoleClause(role, budgetForRole(opts.budget, fixed.length)) : "";
+	return `${fixed}${roleClause}`;
+}
+
+/** Chars left for the role clause once guard + name are reserved. */
+function budgetForRole(budget: number | undefined, fixedLength: number): number {
+	if (budget === undefined) return Number.POSITIVE_INFINITY;
+	return budget - fixedLength;
+}
+
+/**
+ * Render ` Your assigned role is "<role>".` within `available` chars, or "" when
+ * even the empty envelope does not fit (#479).
+ *
+ * Clipping happens on the role text BEFORE serialization, by CODE POINT — never
+ * on the serialized string (codex review): cutting encoded text can split an
+ * escape sequence (`é`) or a surrogate pair and leave the JSON string
+ * unterminated, which is exactly what would break out of the quoted-data framing.
+ * So we search the longest code-point prefix whose `JSON.stringify` still fits.
+ */
+function renderRoleClause(role: string, available: number): string {
+	const wrap = (encoded: string): string => ` Your assigned role is ${encoded}.`;
+	if (wrap(JSON.stringify("")).length > available) return "";
+	const full = wrap(JSON.stringify(role));
+	if (full.length <= available) return full;
+
+	// Binary-search the longest fitting prefix. Code points, not UTF-16 units, so a
+	// non-BMP character is never cut in half.
+	const points = Array.from(role);
+	let lo = 0;
+	let hi = points.length;
+	while (lo < hi) {
+		const mid = Math.ceil((lo + hi) / 2);
+		if (wrap(JSON.stringify(points.slice(0, mid).join(""))).length <= available) lo = mid;
+		else hi = mid - 1;
+	}
+	const clipped = wrap(JSON.stringify(points.slice(0, lo).join("").trimEnd()));
+	// Never silent: a clip means the operator's role prompt did not fully reach the
+	// agent. Lengths only — the role itself is not logged (it can be long, and the
+	// log is not the place for it).
+	process.stderr.write(
+		`[viber-channel] identity: role clause CLIPPED to fit the instructions budget ` +
+			`(${points.length} code points → ${lo}; clause ${full.length} → ${clipped.length} chars, ` +
+			`available ${available}). Shorten the role prompt to avoid losing its tail.\n`,
+	);
+	return clipped;
 }
 
 /**
@@ -848,7 +1070,7 @@ export function buildAgentIdentityInstructions(opts: {
  *   - 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 {
+export function agentIdentityFromEnv(budget?: number): 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
@@ -859,6 +1081,10 @@ export function agentIdentityFromEnv(): string {
 	return buildAgentIdentityInstructions({
 		explicitName: explicit ? label : undefined,
 		role: process.env.VIBER_AGENT_ROLE,
+		// #479: the MCP surface passes IDENTITY_BUDGET so the line cannot eat the
+		// channel contract. The bridges pass nothing — their developer instructions
+		// are not truncated, so a full role is safe there.
+		budget,
 	});
 }
 
@@ -869,6 +1095,8 @@ export interface BridgeIdentity {
 	instanceKey: string;
 	instanceToken: string;
 	bridgeLock: BridgeLock;
+	/** #480 — host announced at register, when this call actually registered. */
+	apiBaseUrlAnnounced?: string;
 }
 
 /**
@@ -909,7 +1137,10 @@ export async function acquireBridgeInstance(opts: {
  * both await an invite. Mirrors the Codex bridge's acquireBridgeIdentity, generic.
  */
 export async function acquireBridgeIdentity(opts: {
+	/** Transport host — what we fetch (#480). */
 	baseUrl: string;
+	/** Logical backend identity — keys the bridge lock (#480). */
+	identityBaseUrl: string;
 	auth: AuthJson;
 	fingerprint: string;
 	label: string;
@@ -919,17 +1150,22 @@ export async function acquireBridgeIdentity(opts: {
 	sessionTag: string;
 	reuseAuthInstance: boolean;
 }): Promise<BridgeIdentity> {
-	const { baseUrl, fingerprint, lockDir, logPrefix, sessionTag } = opts;
+	const { identityBaseUrl, fingerprint, lockDir, logPrefix, sessionTag } = opts;
 	mkdirSync(lockDir, { recursive: true });
 	const acquired = await acquireBridgeInstance(opts);
 	const bridgeLock = acquireBridgeLock({
-		baseUrl,
+		identityBaseUrl,
 		fingerprint,
 		sessionId: `${sessionTag}-agent:${acquired.instance_key}`,
 		lockDir,
 		logPrefix,
 	});
-	return { instanceKey: acquired.instance_key, instanceToken: acquired.instance_token, bridgeLock };
+	return {
+		instanceKey: acquired.instance_key,
+		instanceToken: acquired.instance_token,
+		bridgeLock,
+		apiBaseUrlAnnounced: acquired.api_base_url,
+	};
 }
 
 /** Live helpers a runtime adapter uses inside onStart (e.g. the Codex tool host). */
@@ -947,7 +1183,10 @@ export interface BridgeHelpers {
 
 /** A runtime's adapter for the shared await-invite bridge. */
 export interface AwaitInviteAdapter {
-	baseUrl: string;
+	/** #480 — API host as state (see ConversationStreamDeps.api). */
+	api: ApiBaseUrlResolver;
+	/** Logical backend identity — keys the lock + session handle (#480). */
+	identityBaseUrl: string;
 	lockDir: string;
 	logPrefix: string;
 	/** Lock + session-handle tag distinguishing runtimes (codex / gemma). */
@@ -978,16 +1217,25 @@ export interface AwaitInviteAdapter {
  * makeRunTurn). Throws BridgeShutdownError so the caller maps it to an exit code.
  */
 export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise<void> {
-	const { baseUrl, lockDir, logPrefix, sessionTag, label, kind, options, auth, fingerprint, makeRunTurn, onStart, onShutdown } = adapter;
+	const { api, identityBaseUrl, lockDir, logPrefix, sessionTag, label, kind, options, auth, fingerprint, makeRunTurn, onStart, onShutdown } = adapter;
+	const baseUrl = (): string => api.current();
 	const shutdown = new AbortController();
 	let bridgeLock: BridgeLock | null = null;
 	let controlStream: PersistentControlStream | null = null;
 	const activeStreams = new Map<string, AbortController>();
+	// Persistent per-conversation watermarks (#429). Lives for the WHOLE bridge run
+	// (never cleared per-stream) so a conversation's watermark survives the
+	// abort+restart on re-join. Bounded growth: one `{lastId}` per convId seen —
+	// acceptable (consensus reviewers, step-01 invariant).
+	const watermarks = new Map<string, BridgeWatermark>();
 	const streamTasks = new Set<Promise<void>>();
 	let voiceBaseUrl = "";
 	let instanceKey = "";
 
 	const startConversation = (minted: ConversationMintResponse): void => {
+		// A pushed join is the only announcement a bridge that reuses a persisted
+		// token ever sees (no register call ⇒ nothing announced there).
+		api.offer(minted.api_base_url);
 		if (!voiceBaseUrl) voiceBaseUrl = minted.ws_url;
 		process.stderr.write(`${logPrefix} join pushed for ${minted.conversation_id} — starting stream\n`);
 		// `let task!` (not const): the `.finally` closure reads `task`; with a const
@@ -998,8 +1246,10 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 			instanceKey,
 			options,
 			activeStreams,
+			watermarks,
 			parentSignal: shutdown.signal,
-			baseUrl,
+			api,
+			identityBaseUrl,
 			lockDir,
 			logPrefix,
 			sessionTag,
@@ -1021,11 +1271,14 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 
 	try {
 		const identity = await acquireBridgeIdentity({
-			baseUrl, auth, fingerprint, label, kind, lockDir, logPrefix, sessionTag,
+			baseUrl: baseUrl(), identityBaseUrl, auth, fingerprint, label, kind, lockDir, logPrefix, sessionTag,
 			reuseAuthInstance: options.reuseAuthInstance ?? false,
 		});
 		bridgeLock = identity.bridgeLock;
 		instanceKey = identity.instanceKey;
+		// #480: adopt BEFORE the control stream and the heartbeat start — they are
+		// this bridge's two longest-lived flows and the whole point of the change.
+		api.offer(identity.apiBaseUrlAnnounced);
 
 		const helpers: BridgeHelpers = {
 			startConversation,
@@ -1039,7 +1292,9 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 
 		process.stderr.write(`${logPrefix} await-invite: control stream open, waiting for joins (instance ${identity.instanceKey.slice(0, 8)})\n`);
 		controlStream = runPersistentControlStream(
-			{ baseUrl, instanceId: identity.instanceKey, instanceToken: identity.instanceToken, signal: shutdown.signal },
+			// Evaluated here, i.e. AFTER api.offer() above — so the stream opens on
+			// the announced host rather than the bootstrap one.
+			{ getBaseUrl: baseUrl, instanceId: identity.instanceKey, instanceToken: identity.instanceToken, signal: shutdown.signal },
 			{
 				log: (m) => process.stderr.write(m),
 				onJoin: (minted) => startConversation(minted),
@@ -1052,12 +1307,12 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 					);
 				},
 				onBeatNow: () => {
-					void sendInstanceHeartbeat(baseUrl, identity.instanceKey, identity.instanceToken);
+					void sendInstanceHeartbeat(baseUrl(), identity.instanceKey, identity.instanceToken);
 				},
 			},
 		);
 		const ihb = startInstanceHeartbeat({
-			baseUrl,
+			getBaseUrl: baseUrl,
 			instanceId: identity.instanceKey,
 			getInstanceToken: () => identity.instanceToken,
 		});

package/lib/bridge_tool_host.ts

@@ -29,6 +29,7 @@ import {
   type AgentToolsContext,
   type AgentToolResult,
 } from "./agent_tools.js";
+import { CONTRACT_STYLE_NEUTRAL, CONTRACT_STYLE_TOOLS } from "./channel_instructions.js";
 
 /** The three channel tools, named so codex (and the elicitation whitelist) match. */
 export const BRIDGE_TOOL_NAMES = ["send_message", "list_agents", "message_agent"] as const;
@@ -44,17 +45,32 @@ export const TOOL_DEFS = [
   {
     name: "send_message",
     description:
-      "Reply to the USER. This is the ONLY way to reach the user — they do NOT see your runtime/stdout, so never answer there. " +
-      "Post your reply into the current Viber conversation. `text` is the conversational reply — " +
-      "read aloud AND shown as Markdown, so keep it short and natural but use light Markdown (short " +
-      "lists, numbered steps, **bold**) for readability; put actions/questions here, visibly. " +
-      "`artifact` is optional HEAVY/LONG content (big code, large tables, long analyses, json, " +
-      "sanitized html) shown in a side viewer; when used, keep `text` a brief summary pointing to it. " +
-      "Calling this IS your reply for the turn.",
+      // #479 codex review: this used to claim send_message was "the ONLY way to
+      // reach the user". False on THIS surface — the bridge auto-posts a turn's
+      // text when no outbound tool succeeded, and the system prompt says so. Two
+      // contradictory statements about delivery is exactly the defect #479 fixes
+      // elsewhere, so the wording is non-exclusive here.
+      "Reply to the USER by posting into the current Viber conversation. Your runtime/stdout is NOT the user — never treat it as the reply. " +
+      "Calling this delivers your reply for the turn (and suppresses the bridge's auto-post fallback). " +
+      // #479 volet 2: the SAME contract fragments Claude gets. They used to exist
+      // only in the MCP `instructions` blob, which never reaches codex/gemma at all
+      // — so NO EMOJI and the literal-identifier rule were simply absent here.
+      CONTRACT_STYLE_NEUTRAL +
+      " " +
+      CONTRACT_STYLE_TOOLS,
     inputSchema: {
       type: "object",
       properties: {
-        text: { type: "string", description: "Spoken/conversational reply. Plain sentences." },
+        // #479: this used to read "Plain sentences." — a leftover of the retired
+        // "no markdown" rule, contradicting the description right above it, which
+        // asks for light Markdown. The contract has ONE wording now.
+        text: {
+          type: "string",
+          description:
+            "Spoken/conversational reply: read aloud AND shown as Markdown. Short and natural, light " +
+            "Markdown (short lists, **bold**) for readability. Actions and questions go here, visibly. " +
+            "NO emoji (it is read aloud). Write identifiers LITERALLY (288, auth.json).",
+        },
         artifact: {
           type: "object",
           properties: {