viber-channel 0.8.17 → 0.8.20

package/lib/agent_tools.ts

@@ -78,6 +78,16 @@ export interface AgentToolsContext {
    * signal); the Codex bridge returns its per-turn stream signal (#303 parity).
    */
   abortSignal?(): AbortSignal | undefined;
+  /**
+   * #627: why this agent is PAUSED, or null when it may write. A paused agent has no
+   * confirmed conversation lease, so it must not post anything; the tool says why.
+   */
+  pauseReason?(): string | null;
+}
+
+function pausedResult(ctx: AgentToolsContext): AgentToolResult | null {
+  const reason = ctx.pauseReason?.() ?? null;
+  return reason === null ? null : errorText(`Paused — ${reason}. Nothing was sent; it resumes on its own when the runner covers this agent again.`);
 }
 
 function text(s: string): AgentToolResult {
@@ -164,6 +174,8 @@ export async function messageAgent(
   if (!ctx.instanceToken() || !ctx.voiceBaseUrl()) {
     return errorText("Channel not ready: no instance identity yet.");
   }
+  const paused = pausedResult(ctx);
+  if (paused !== null) return paused;
   const peerId = args.instance_id;
   const body = args.text;
   if (typeof peerId !== "string" || peerId.trim().length === 0) {
@@ -183,7 +195,10 @@ export async function messageAgent(
   if (!outcome.ok) {
     let friendly: string;
     if (outcome.detail === "target_offline") {
-      friendly = "That agent is offline right now — it must be running to receive a DM.";
+      // #627: a just-launched agent comes online with its runner's first beat (≤ 30 s).
+      friendly =
+        "That agent is offline right now — it must be running to receive a DM. " +
+        "If it was just launched, it comes online with its runner's next beat (within 30 s): retry then.";
     } else if (outcome.detail === "dm_unavailable_retry") {
       friendly = "Could not open the DM due to a transient conflict — try message_agent again.";
     } else {
@@ -237,6 +252,8 @@ export async function sendMessage(
   if (!ctx.sendConversationToken() || !ctx.sendConversationId()) {
     return errorText("Channel not ready: no conversation yet.");
   }
+  const paused = pausedResult(ctx);
+  if (paused !== null) return paused;
   const body = args.text;
   if (typeof body !== "string" || body.trim().length === 0) {
     return errorText("Invalid input: text must be a non-empty string");

package/lib/auth.ts

@@ -1,5 +1,5 @@
 import { chmodSync, readFileSync, writeFileSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { basename, isAbsolute, join } from "node:path";
 
 export interface AuthJson {
   schema_version: number;
@@ -63,15 +63,81 @@ export function isDevBackend(
  * silently authenticated against the dev backend with STAGING creds (`-32000`)
  * because only `VIBER_BASE_URL` was set and the auth file defaulted to staging.
  */
-export function authFilePath(cwd: string = process.cwd()): string {
+export function authFilePath(
+  cwd: string = process.cwd(),
+  baseUrl: string = process.env.VIBER_BASE_URL ?? "",
+): string {
+  const qa = isQaBackend(baseUrl);
   const override = process.env.VIBER_AUTH_FILE;
   if (override !== undefined && override.trim() !== "") {
+    assertAuthFileMatchesBackend(basename(override), qa);
     return isAbsolute(override) ? override : join(cwd, override);
   }
-  const file = isDevBackend() ? "dev.auth.json" : "auth.json";
+  const file = isDevBackend(baseUrl) ? "dev.auth.json" : qa ? QA_AUTH_FILE : "auth.json";
   return join(cwd, ".viber", file);
 }
 
+/**
+ * #613: the auth file `connect` must write for a claim URL. The CLAIM decides
+ * for qa: `connect https://viber-qa.dgypx.dev/connect/<id>` run with no
+ * VIBER_BASE_URL would otherwise derive the file from the (empty) env and write
+ * qa credentials into `auth.json`, overwriting STAGING's. A set env that
+ * contradicts the claim (qa vs not qa) is refused. Non-qa claims keep the
+ * pre-#613 behavior (file derived from the env) unchanged.
+ */
+export function connectAuthPath(
+  claimBaseUrl: string,
+  cwd: string = process.cwd(),
+  envBaseUrl: string = process.env.VIBER_BASE_URL ?? "",
+): string {
+  const claimQa = isQaBackend(claimBaseUrl);
+  if (envBaseUrl.trim() !== "" && claimQa !== isQaBackend(envBaseUrl)) {
+    throw new Error(
+      `claim URL ${claimBaseUrl} and VIBER_BASE_URL=${envBaseUrl} disagree on the qa backend; refusing to write credentials`,
+    );
+  }
+  return authFilePath(cwd, claimQa ? claimBaseUrl : envBaseUrl);
+}
+
+/** #613: the qa web host. Matched EXACTLY (hostname), never by substring. */
+export const QA_WEB_HOST = "viber-qa.dgypx.dev";
+export const QA_AUTH_FILE = "qa.auth.json";
+
+/**
+ * #613: true only when `VIBER_BASE_URL` is the qa web host. Same raw-env
+ * classification rule as {@link isDevBackend} (never the API transport host),
+ * but an exact hostname match: a substring test would let any host containing
+ * "qa" read qa credentials, or a qa host fall through to STAGING's auth.json.
+ */
+export function isQaBackend(
+  baseUrl: string = process.env.VIBER_BASE_URL ?? "",
+): boolean {
+  try {
+    return new URL(baseUrl).hostname === QA_WEB_HOST;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * #613: a `VIBER_AUTH_FILE` override still wins, but a CONTRADICTORY one is
+ * refused instead of resolved in silence: qa credentials against another
+ * backend, or another env's well-known file against the qa backend. Custom
+ * file names stay allowed on both sides.
+ */
+function assertAuthFileMatchesBackend(file: string, qa: boolean): void {
+  if (!qa && file === QA_AUTH_FILE) {
+    throw new Error(
+      `VIBER_AUTH_FILE points at ${QA_AUTH_FILE} but VIBER_BASE_URL is not https://${QA_WEB_HOST}`,
+    );
+  }
+  if (qa && (file === "auth.json" || file === "dev.auth.json")) {
+    throw new Error(
+      `VIBER_BASE_URL is the qa backend but VIBER_AUTH_FILE points at ${file} (another env's credentials)`,
+    );
+  }
+}
+
 export function loadAuth(cwd: string = process.cwd()): AuthJson {
   const path = authFilePath(cwd);
   let raw: string;

package/lib/bridge_core.ts

@@ -32,12 +32,12 @@ import type { AuthJson } from "./auth.js";
 import { acquireInstance, registerInstance, instanceKindFromEnv, maybeAttachTeam, type AcquiredInstance } from "./instance.js";
 import {
 	runPersistentControlStream,
-	sendInstanceHeartbeat,
 	ControlStreamStopped,
 	ControlStreamAuthError,
 	type PersistentControlStream,
 } from "./control_stream.js";
-import { startInstanceHeartbeat } from "./heartbeat.js";
+import { type PresenceGate, startCoverageWatch } from "./coverage_watch.js";
+import { type PresenceEndReason, type PresenceRecordHandle, startPresenceRecord } from "./presence_record.js";
 
 /** A conversation message as it arrives over the conversation SSE / message list. */
 export interface ConversationMessage {
@@ -71,11 +71,19 @@ export interface ConversationRuntime {
 	scheduler?: TokenRefreshScheduler;
 }
 
-/** A controlled bridge exit carrying the process exit code to propagate. */
+/**
+ * A controlled bridge exit carrying the process exit code to propagate.
+ *
+ * `endReason` (#627) names the cause for the presence record. It is set ONLY where
+ * the cause is known (revocation, lease lost, --once done). The class alone says
+ * nothing about intent: it also carries failures (token expired, refresh failed),
+ * which must leave the agent relaunchable.
+ */
 export class BridgeShutdownError extends Error {
 	constructor(
 		message: string,
 		public readonly exitCode: number,
+		public readonly endReason: PresenceEndReason = "shutdown",
 	) {
 		super(message);
 		this.name = "BridgeShutdownError";
@@ -306,11 +314,17 @@ export async function postBridgeReply(opts: {
 	ownPostedIds: Set<string>;
 	signal?: AbortSignal;
 	logPrefix: string;
+	/** Fetch seam (#606) — see postMessage. Defaults to the global fetch. */
+	fetchImpl?: typeof fetch;
+	/** #627: a reply finished during a pause waits for the resume before it is posted. */
+	gate?: PresenceGate;
 }): Promise<void> {
 	const { baseUrl, runtime, text, ownPostedIds, signal, logPrefix } = opts;
+	await opts.gate?.waitActive(signal);
+	if (signal?.aborted) return;
 	let result;
 	try {
-		result = await postMessage(baseUrl, runtime.id, runtime.token, text, undefined, signal);
+		result = await postMessage(baseUrl, runtime.id, runtime.token, text, undefined, signal, opts.fetchImpl ?? fetch);
 	} catch (err) {
 		if (err instanceof ConversationTokenExpiredError) {
 			throw new BridgeShutdownError("conversation token expired", 3);
@@ -345,6 +359,93 @@ export function decideTurnPostAction(opts: {
 	return "auto-post";
 }
 
+/** Max length of the runtime cause quoted verbatim in a channel failure notice. */
+const FAILURE_CAUSE_MAX = 400;
+
+/** Transport degradation observed during a turn (#606 step-02, codex only). */
+export type TurnDegradation = { events: number; lastStatus?: number };
+
+/**
+ * #606 — the text a bridge posts on the CHANNEL when a turn fails.
+ *
+ * The whole point of the issue is that a failed turn was written to stderr only,
+ * so the model filled the silence with an INVENTED cause. This text therefore
+ * quotes what the runtime said, VERBATIM and truncated, and adds nothing of its
+ * own: no classification, no advice, no guess. Pure (no clock, no network) so it
+ * is testable without a harness.
+ */
+export function failureNoticeText(err: unknown, degradation?: TurnDegradation): string {
+	const raw = safeErrorMessage(err).replace(/\s+/g, " ").trim();
+	const cause = raw.length > FAILURE_CAUSE_MAX ? `${raw.slice(0, FAILURE_CAUSE_MAX)}...` : raw || "(aucun detail)";
+	let text = `Tour echoue, aucune reponse produite. Cause rapportee par le runtime: ${cause}`;
+	if (degradation && degradation.events > 0) {
+		const status = degradation.lastStatus ? `, dernier statut HTTP ${degradation.lastStatus}` : "";
+		text += ` (transport degrade: ${degradation.events} evenement(s) avant l'echec${status})`;
+	}
+	return text;
+}
+
+/**
+ * #606 — the dedup signature of a failure cause.
+ *
+ * A blown quota fails EVERY subsequent turn: without dedup the fix that makes a
+ * failure speak would flood the channel. Two failures of the same cause must
+ * therefore yield the SAME key, so the volatile identifiers a runtime stamps on
+ * each attempt (turnId, threadId, cf-ray, timestamps, long hex ids) are stripped.
+ *
+ * The degradation COUNT is deliberately reduced to its presence, never its value:
+ * keying on the number would make every different N a "new cause" and re-open the
+ * flood the dedup exists to close.
+ */
+export function failureCauseKey(err: unknown, degradation?: TurnDegradation): string {
+	const normalized = safeErrorMessage(err)
+		.replace(/"(?:turnId|threadId|conversationId|requestId)"\s*:\s*"[^"]*"/g, "")
+		// STOPS at a JSON delimiter (review codex P2a). `\S+` here crossed the
+		// closing quote and ate everything up to the next SPACE — measured: two
+		// errors differing only by httpStatusCode 503 vs 429 collapsed onto
+		// `Codex turn failed: {"message":"Request failed,` because the status sat
+		// AFTER the cf-ray. A normalisation that eats the discriminator gags the
+		// second outage: the exact defect this key exists to avoid.
+		.replace(/cf-ray:\s*[^\s",}\]]+/gi, "")
+		.replace(/\d{4}-\d{2}-\d{2}T[\d:.]+Z?/g, "")
+		// The RESET INSTANT of a quota, in the two shapes our own log carries for
+		// the same outage (review codex, .raw l.95 vs l.111): with the date and
+		// without. Stripping only the clock left them on different keys, so the
+		// same cause announced twice.
+		.replace(
+			/\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\s+\d{1,2}(?:st|nd|rd|th)?,?\s*\d{4}\b/gi,
+			"",
+		)
+		.replace(/\b\d{1,2}:\d{2}(:\d{2})?\s*(AM|PM)?\b/gi, "")
+		.replace(/\b[0-9a-f]{12,}\b/gi, "")
+		.replace(/\s+/g, " ")
+		.trim();
+	const degraded = degradation && degradation.events > 0 ? "|degraded" : "";
+	// WHOLE, neither truncated nor hashed (review codex, both passes). Slicing to a
+	// display bound made the key lose identity past that bound — two errors sharing
+	// a long prefix became one cause and the second was silenced. A digest fixed
+	// that but kept a residual collision, which costs a SUPPRESSED notice: the
+	// defect this key exists to prevent, made rare instead of impossible.
+	// There is no size constraint to trade against: the key is one closure variable
+	// holding one cause at a time. Keeping the normalised string entire removes the
+	// class rather than shrinking it — a display concern must not decide identity,
+	// which is the whole lesson of P2b.
+	return `${normalized}${degraded}`;
+}
+
+/**
+ * #606 step-02 — read the transport degradation a runtime attached to the error
+ * it threw. The failing turn never returns a TurnResult, so the count cannot ride
+ * on one; the codex bridge stamps it on the Error itself. Any runtime that stamps
+ * nothing (gemma: a single fetch, no intermediate transport events to observe)
+ * simply yields undefined, and the notice omits the clause.
+ */
+export function readTurnDegradation(err: unknown): TurnDegradation | undefined {
+	const d = (err as { degradation?: unknown })?.degradation as TurnDegradation | undefined;
+	if (!d || typeof d.events !== "number" || d.events <= 0) return undefined;
+	return { events: d.events, lastStatus: typeof d.lastStatus === "number" ? d.lastStatus : undefined };
+}
+
 /**
  * #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
@@ -440,6 +541,8 @@ export interface ConversationStreamDeps {
 	/** Session-handle tag distinguishing runtimes in the handle path (codex/gemma). */
 	sessionTag: string;
 	makeRunTurn: MakeRunTurn;
+	/** #627: the pause gate — inbound turns and replies wait while the agent is paused. */
+	gate?: PresenceGate;
 }
 
 /**
@@ -509,7 +612,7 @@ export async function runConversationStream(
 			watermark = { lastId: 0 };
 			watermarks.set(convId, watermark);
 		}
-		await sseLoop({ minted, runtime, fingerprint, ownInstanceKey: instanceKey, options, signal: ctrl.signal, getBaseUrl: baseUrl, logPrefix, runTurn, watermark });
+		await sseLoop({ minted, runtime, fingerprint, ownInstanceKey: instanceKey, options, signal: ctrl.signal, getBaseUrl: baseUrl, logPrefix, runTurn, watermark, gate: deps.gate });
 	} finally {
 		parentSignal.removeEventListener("abort", onParentAbort);
 		runtime.scheduler?.cancel();
@@ -562,14 +665,45 @@ export async function sseLoop(opts: {
 	fetchImpl?: typeof fetch;
 	/** Injectable catch-up fetch; defaults to messages.ts `fetchMessages`. */
 	fetchMessagesImpl?: typeof fetchMessages;
+	/** #627: the pause gate (see ConversationStreamDeps.gate). */
+	gate?: PresenceGate;
 }): Promise<void> {
 	const { minted, runtime, fingerprint, ownInstanceKey, options, signal, getBaseUrl, logPrefix, runTurn, watermark } = opts;
+	const deps = { gate: opts.gate };
 	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>();
 
+	// #606 anti-flood state: the cause key of the LAST failure actually announced
+	// on the channel. A blown quota fails every subsequent turn, so announcing each
+	// one would replace a silence bug with a spam bug. Closure state, owned by this
+	// loop — no module singleton (.claude/rules/architecture.md §7).
+	// Cross-RUN note. This comment CLAIMED the key survives a re-join; it does not,
+	// and N.11 measures the opposite (review codex, prose-has-no-test: the code was
+	// right, the sentence was false). What actually happens: the watermark
+	// deliberately does NOT advance on a failed reply (at-least-once retry, see
+	// below), so a re-join replays the message and fails again — and since each
+	// sseLoop call owns a FRESH closure, that re-join announces once more. Same for
+	// a process restart. Deliberate: a bridge that comes back and hits the same wall
+	// is information. Within one join, the key is what stops the flood.
+	let lastAnnouncedCause: string | undefined;
+
+	/**
+	 * #606 — a DELIVERED turn means the previous cause is over: rearm the notice.
+	 *
+	 * Lives HERE, on the turn outcome, and not at a caller. Review F2 measured why:
+	 * written at the text caller only, the VOICE path never rearmed, so
+	 * text-fails → voice-recovers → text-fails-again left the third failure GAGGED
+	 * — the issue's own defect, reproduced by the issue's fix. Placing it on the
+	 * outcome removes the class instead of patching the two paths that exist today.
+	 * An ABORTED turn never gets here: teardown says nothing about runtime health.
+	 */
+	function rearmFailureNotice(): void {
+		lastAnnouncedCause = undefined;
+	}
+
 	// Run one turn for `content` via the injected runtime, then auto-post its
 	// reply UNLESS an outbound tool already posted this turn (anti-double-post).
 	// Returns true when the reply was dropped because the stream was aborted
@@ -598,12 +732,15 @@ export async function sseLoop(opts: {
 				return true;
 			case "suppress-outbound":
 				process.stderr.write(`${logPrefix} outbound tool posted this turn on ${runtime.id}; suppressing final auto-post\n`);
+				rearmFailureNotice();
 				return false;
 			case "skip-empty":
 				process.stderr.write(`${logPrefix} turn on ${runtime.id} produced no text and used no outbound tool; nothing to deliver\n`);
+				rearmFailureNotice();
 				return false;
 			case "auto-post":
-				await postBridgeReply({ baseUrl: baseUrl(), runtime, text: reply, ownPostedIds, signal, logPrefix });
+				await postBridgeReply({ baseUrl: baseUrl(), runtime, text: reply, ownPostedIds, signal, logPrefix, fetchImpl, gate: deps.gate });
+				rearmFailureNotice();
 				return false;
 		}
 	}
@@ -652,6 +789,50 @@ export async function sseLoop(opts: {
 			.finally(() => ackInFlightIds.delete(idStr));
 	}
 
+
+	/**
+	 * #606 — say a failed turn on the CHANNEL, best-effort.
+	 *
+	 * Deliberately unable to make things worse:
+	 *  - the transport may be the very thing that broke (the measured case was a
+	 *    503 storm), so a failing notice is swallowed to stderr, NEVER retried and
+	 *    never rethrown — one failure must not become two;
+	 *  - it posts through postBridgeReply, so the notice id lands in ownPostedIds
+	 *    like any other reply and cannot feed itself back through handleInboundMessage;
+	 *  - the cause key is recorded only AFTER a post that actually succeeded, so a
+	 *    lost notice does not silence the next one.
+	 */
+	async function announceTurnFailure(err: unknown): Promise<void> {
+		const degradation = readTurnDegradation(err);
+		const key = failureCauseKey(err, degradation);
+		if (key === lastAnnouncedCause) {
+			process.stderr.write(`${logPrefix} failure notice suppressed (same cause as the previous one)\n`);
+			return;
+		}
+		try {
+			await postBridgeReply({
+				baseUrl: baseUrl(),
+				runtime,
+				text: failureNoticeText(err, degradation),
+				ownPostedIds,
+				signal,
+				logPrefix,
+				fetchImpl,
+				gate: deps.gate,
+			});
+			lastAnnouncedCause = key;
+		} catch (notifyErr) {
+			// Includes BridgeShutdownError from an expired token: swallowed here on
+			// purpose. CONSEQUENCE, named because it is not obvious (review F3): a
+			// token expiry first met BY THE NOTICE is discovered later, on the next
+			// turn, instead of shutting the bridge down now. Accepted — this path
+			// runs while ALREADY handling a failure; escalating a
+			// shutdown from the notice would turn "the agent could not answer" into
+			// "the agent died", which is a worse report than the one we came to give.
+			process.stderr.write(`${logPrefix} failure notice could not be posted: ${safeErrorMessage(notifyErr)}\n`);
+		}
+	}
+
 	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
@@ -674,6 +855,15 @@ export async function sseLoop(opts: {
 		// AT-MOST-ONCE: mark handled BEFORE the reply so a runtime failure does not
 		// re-feed the same message on reconnect (no reply storm). A failed reply is
 		// dropped for this run — deliberately asymmetric with dm_stream's conduit.
+		// #627: while paused, the message is DEFERRED (never dropped): the turn starts
+		// once the runner covers this agent again. The wait comes BEFORE the message is
+		// marked handled: a stream stopped during the pause leaves it unhandled, and the
+		// persistent watermark un-advanced, so the re-join replays it (Codex, step-06).
+		if (deps.gate?.isPaused()) {
+			process.stderr.write(`${logPrefix} paused (${deps.gate.reason()}): message deferred\n`);
+			await deps.gate.waitActive(signal);
+			if (signal.aborted) return false;
+		}
 		if (idStr) handledIds.add(idStr);
 		process.stderr.write(`${logPrefix} message received: ${msg.content!.slice(0, 80)}\n`);
 		try {
@@ -688,6 +878,7 @@ export async function sseLoop(opts: {
 		} catch (err) {
 			if (err instanceof BridgeShutdownError) throw err;
 			process.stderr.write(`${logPrefix} failed to handle message: ${safeErrorMessage(err)}\n`);
+			await announceTurnFailure(err);
 		}
 		return options.once === true;
 	}
@@ -792,7 +983,8 @@ export async function sseLoop(opts: {
 
 					if (eventType === "stop") {
 						process.stderr.write(`${logPrefix} received stop signal, exiting\n`);
-						throw new BridgeShutdownError("received stop signal", 0);
+						// #627: the same server stop as claude's `stop` event → the same cause.
+						throw new BridgeShutdownError("received stop signal", 0, "revoked");
 					}
 
 					if (eventType === "transcription" && data) {
@@ -810,6 +1002,12 @@ export async function sseLoop(opts: {
 							} catch (err) {
 								if (err instanceof BridgeShutdownError) throw err;
 								process.stderr.write(`${logPrefix} failed to handle transcription: ${safeErrorMessage(err)}\n`);
+								// #606: a VOICE turn that fails was the second silent swallow in this
+								// same chain — found while building the tests, not by the grep on
+								// "failed to handle message", which only ever proved the uniqueness of
+								// the TEXT path. A user speaking to a dead runtime deserves the same
+								// notice as one typing to it.
+								await announceTurnFailure(err);
 							}
 							if (options.once) return;
 						}
@@ -1174,6 +1372,8 @@ export interface BridgeHelpers {
 	parentSignal: AbortSignal;
 	/** Request a controlled bridge shutdown (e.g. codex's app-server died). */
 	requestShutdown: (err: BridgeShutdownError) => void;
+	/** #627: why the agent is paused (null = may write) — for the tool host. */
+	pauseReason: () => string | null;
 }
 
 /** A runtime's adapter for the shared await-invite bridge. */
@@ -1226,6 +1426,10 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 	const streamTasks = new Set<Promise<void>>();
 	let voiceBaseUrl = "";
 	let instanceKey = "";
+	// #627: the local presence record read by the machine's runner.
+	let presence: PresenceRecordHandle | undefined;
+	// #627: the pause gate, fed by the runner's local coverage (no network heartbeat).
+	let gate: PresenceGate | undefined;
 
 	const startConversation = (minted: ConversationMintResponse): void => {
 		// A pushed join is the only announcement a bridge that reuses a persisted
@@ -1249,11 +1453,12 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 			logPrefix,
 			sessionTag,
 			makeRunTurn,
+			gate,
 		})
 			.then(() => {
 				// --once: one handled message completes the bridge cleanly.
 				if (options.once && !shutdown.signal.aborted) {
-					shutdown.abort(new BridgeShutdownError("once: completed", 0));
+					shutdown.abort(new BridgeShutdownError("once: completed", 0, "once-completed"));
 				}
 			})
 			.catch((err) => {
@@ -1271,6 +1476,21 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 		});
 		bridgeLock = identity.bridgeLock;
 		instanceKey = identity.instanceKey;
+		// Await-invite bridges may hold several conversations; the beat sends none,
+		// so the record carries none either.
+		presence = startPresenceRecord({ identityBaseUrl, instanceId: identity.instanceKey, label, projectId: auth.project_id, getConversationId: () => null, lockDir });
+		// #627: no network heartbeat — the runner vouches for this bridge. An await-invite
+		// bridge follows no single conversation lease, only its runner's freshness.
+		const watch = startCoverageWatch({
+			identityBaseUrl,
+			instanceId: identity.instanceKey,
+			getConversationId: () => null,
+			onLeaseLost: () => shutdown.abort(new BridgeShutdownError("conversation lease lost (taken over)", 0, "lease-lost")),
+			lockDir,
+			log: (m) => process.stderr.write(`${logPrefix} ${m}`),
+		});
+		gate = watch.gate;
+		shutdown.signal.addEventListener("abort", () => watch.stop(), { once: true });
 		// #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);
@@ -1282,6 +1502,7 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 			requestShutdown: (err) => {
 				if (!shutdown.signal.aborted) shutdown.abort(err);
 			},
+			pauseReason: () => gate?.reason() ?? null,
 		};
 		await onStart?.({ identity: { instanceKey: identity.instanceKey, instanceToken: identity.instanceToken }, helpers });
 
@@ -1298,25 +1519,21 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 					shutdown.abort(
 						reason === "unauthorized"
 							? new BridgeShutdownError("instance token revoked or invalid", 3)
-							: new BridgeShutdownError("instance revoked", 0),
+							: new BridgeShutdownError("instance revoked", 0, "revoked"),
 					);
 				},
-				onBeatNow: () => {
-					void sendInstanceHeartbeat(baseUrl(), identity.instanceKey, identity.instanceToken);
-				},
+				// #627: an old server may still probe; this agent never beats on the network —
+				// its runner answers for it (Python no longer probes a runner-covered agent).
+				onBeatNow: () => {},
 			},
 		);
-		const ihb = startInstanceHeartbeat({
-			getBaseUrl: baseUrl,
-			instanceId: identity.instanceKey,
-			getInstanceToken: () => identity.instanceToken,
-		});
-		shutdown.signal.addEventListener("abort", () => ihb.stop(), { once: true });
 		controlStream.firstJoin.catch(() => {});
 		await controlStream.done;
 		const reason = shutdown.signal.reason;
 		if (reason instanceof BridgeShutdownError) throw reason;
 	} finally {
+		// Read BEFORE the bare abort below replaces an unset reason.
+		endBridgePresence(presence, shutdown.signal.aborted ? shutdown.signal.reason : undefined);
 		if (!shutdown.signal.aborted) shutdown.abort();
 		const pending = [...streamTasks];
 		for (const ctrl of activeStreams.values()) ctrl.abort(new BridgeShutdownError("bridge shutdown", 0));
@@ -1329,3 +1546,15 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 
 // Re-export control-stream error types so runtimes can map them if needed.
 export { ControlStreamStopped, ControlStreamAuthError };
+
+/**
+ * #627 — record how a bridge ended. A `BridgeShutdownError` is an end the bridge
+ * went through → `ended` with its `endReason` (failures default to "shutdown").
+ * Anything else — an unexpected throw — leaves the record active, like a crash.
+ * The runner, not this function, decides what either means.
+ */
+export function endBridgePresence(presence: PresenceRecordHandle | undefined, reason: unknown): void {
+	if (presence === undefined) return;
+	if (reason instanceof BridgeShutdownError) presence.markEnded(reason.endReason);
+	else presence.stop();
+}

package/lib/connect.ts

@@ -19,7 +19,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, isAbsolute, join, relative } from "node:path";
-import { authFilePath } from "./auth.js";
+import { connectAuthPath, isQaBackend } from "./auth.js";
 import { clientFingerprint } from "./fingerprint.js";
 import { cfAccessHeaders } from "./cfAccess.js";
 
@@ -50,6 +50,21 @@ interface TerminalResponse {
 
 type PollResponse = ConsumedResponse | PendingResponse | TerminalResponse;
 
+const DEFAULT_NEXT_STEPS =
+  `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` +
+  `  2. Restart Claude Code in this directory.\n\n`;
+
+// #613: qa never runs the published channel — the default advice would be wrong
+// at the exact moment of the qa gesture.
+export const QA_NEXT_STEPS =
+  `Next steps (qa):\n` +
+  `  1. Run the channel FROM SOURCE in the Gateway worktree: register viber-qa-channel\n` +
+  `     in its local .mcp.json (bun ./viber-channel/viber-channel.ts,\n` +
+  `     VIBER_BASE_URL=https://viber-qa.dgypx.dev). NEVER bunx viber-channel@latest.\n` +
+  `  2. See plans/613-env-qa (mount procedure).\n\n`;
+
 const POLL_INTERVAL_MS = 2000;
 const MAX_POLL_DURATION_MS = 10 * 60 * 1000;
 
@@ -77,6 +92,7 @@ function writeAuthJson(
   cwd: string,
   data: ConsumedResponse,
   fingerprint: string,
+  authPath: string,
 ): void {
   const viberDir = join(cwd, ".viber");
   mkdirSync(viberDir, { recursive: true });
@@ -85,7 +101,7 @@ function writeAuthJson(
   // 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);
+  // #613: `authPath` comes from connectAuthPath (the claim decides for qa).
   mkdirSync(dirname(authPath), { recursive: true });
 
   const auth: Record<string, unknown> = {
@@ -159,6 +175,8 @@ export async function runConnect(
   cwd: string = process.cwd(),
 ): Promise<void> {
   const { baseUrl, claimId } = parseClaimUrl(claimUrl);
+  // #613: resolved BEFORE any network call, so a contradiction fails early.
+  const authPath = connectAuthPath(baseUrl, cwd);
 
   const fingerprint = clientFingerprint(cwd);
   process.stderr.write(
@@ -191,14 +209,11 @@ export async function runConnect(
     }
     const data = (await pollResp.json()) as PollResponse;
     if (data.status === "consumed") {
-      writeAuthJson(cwd, data, fingerprint);
+      writeAuthJson(cwd, data, fingerprint, authPath);
       process.stdout.write(
         `\n✓ Connected as ${data.user_email} to project '${data.project_name}'.\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` +
-          `  2. Restart Claude Code in this directory.\n\n`,
+          `  Wrote ${authPath}\n\n` +
+          (isQaBackend(baseUrl) ? QA_NEXT_STEPS : DEFAULT_NEXT_STEPS),
       );
       return;
     }

package/lib/control_stream.ts

@@ -26,9 +26,10 @@ export interface ControlEvent {
   data: string;
 }
 
-/** Build the instance control-stream SSE URL. */
+/** Build the instance control-stream SSE URL. `presence=runner` (#627): this agent's
+ *  runner vouches for it, so its connect must not count as liveness on the server. */
 export function buildControlStreamUrl(baseUrl: string, instanceId: string): string {
-  return `${baseUrl}/api/instances/${instanceId}/events`;
+  return `${baseUrl}/api/instances/${instanceId}/events?presence=runner`;
 }
 
 /**