viber-channel 0.8.19 → 0.8.21

package/lib/runner_stream.ts

@@ -19,7 +19,8 @@ import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { cfAccessHeaders } from "./cfAccess.js";
 import { isTrustedViberOrigin } from "./urls.js";
-import { reconcileOnce } from "./runner_exec.js";
+import { type ExecDeps, reconcileOnce } from "./runner_exec.js";
+import { runRosterBeat } from "./runner_roster.js";
 
 /** Remove leftover temp spec files (`.viber/runner-specs/`) from a prior crash
  *  at daemon start — they may hold sensitive rolePrompts (Codex P1-1). The
@@ -37,10 +38,25 @@ interface RunnerAuth {
   runner_id: string;
   runner_token: string;
   machine_fingerprint: string;
+  /** #627: the enrolled web host (absent before #627). */
+  identity_base_url?: string;
+}
+
+/** #632: what the app's notification-area icon shows. */
+export interface RunnerHooks {
+  /** true once the control stream is open, false whenever it closes. */
+  onConnection?: (up: boolean) => void;
 }
 
 const HEARTBEAT_INTERVAL_MS = 30_000;
-const RECONCILE_INTERVAL_MS = 60_000; // periodic safety-net pull (C6)
+/**
+ * Periodic safety-net pull (C6). #627 (JP): commands travel by SSE — the runner already
+ * gets a `spawn_pending` wake-poke, and it pulls at EVERY (re)connect. What is left for
+ * this timer is the one case the stream cannot report: an SSE that LOOKS open but is
+ * dead behind the tunnel or a proxy. 10 min bounds that case for almost nothing, where
+ * 60 s cost a Worker request a minute per machine.
+ */
+export const RECONCILE_INTERVAL_MS = 10 * 60_000;
 const RECONNECT_BASE_MS = 1_000;
 const RECONNECT_MAX_MS = 30_000;
 
@@ -92,11 +108,11 @@ let reconciling = false;
  * executor. Coalesced + self-contained error handling so a reconcile failure
  * NEVER propagates into the SSE stream's reconnect/backoff logic.
  */
-async function safeReconcile(auth: RunnerAuth): Promise<void> {
+async function safeReconcile(auth: RunnerAuth, deps: ExecDeps = {}): Promise<void> {
   if (reconciling) return;
   reconciling = true;
   try {
-    const handled = await reconcileOnce(auth);
+    const handled = await reconcileOnce(auth, deps);
     if (handled > 0) process.stderr.write(`[runner] reconcile: handled ${handled} command(s)\n`);
   } catch (err) {
     process.stderr.write(`[runner] reconcile error (non-fatal): ${String(err)}\n`);
@@ -107,32 +123,31 @@ async function safeReconcile(auth: RunnerAuth): Promise<void> {
 
 /** Heartbeat. Returns "revoked" on a 401 (the runner was revoked) so the caller
  *  can tear down mid-stream (revocation is otherwise only seen at reconnect —
- *  Opus/Codex review). Any other failure is swallowed (best-effort presence). */
+ *  Opus/Codex review). Any other failure is swallowed (best-effort presence).
+ *
+ *  #627: the beat now carries the machine's ROSTER — the only presence signal of
+ *  the agents this runner vouches for (`runner_roster.ts`). */
 async function sendHeartbeat(auth: RunnerAuth): Promise<"ok" | "revoked"> {
-  try {
-    const resp = await fetch(`${auth.base_url}/api/runners/${auth.runner_id}/heartbeat`, {
-      method: "POST",
-      // redirect:"error" — never follow a redirect while carrying the bearer, so
-      // a tampered base_url / hostile redirect can't exfiltrate it (Codex review).
-      redirect: "error",
-      headers: {
-        Authorization: `Bearer ${auth.runner_token}`,
-        "Content-Type": "application/json",
-        ...cfAccessHeaders(),
-      },
-      body: JSON.stringify({
-        capabilities: { runtimes: ["claude-code", "codex", "gemma"], platform: process.platform, version: 1 },
-      }),
-    });
-    return resp.status === 401 ? "revoked" : "ok";
-  } catch {
-    /* best-effort — durable presence is the server's last_seen; a missed beat is fine */
-    return "ok";
-  }
+  return runRosterBeat(auth, { headers: cfAccessHeaders });
 }
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  // #632: abortable, so the app's Quit does not wait out a reconnect backoff of up to 30 s
+  // (`632-review-codex`).
+  // The abort listener is REMOVED when the sleep ends normally: otherwise every reconnect of a
+  // long-lived runner would leave one more on the signal (`632-review-codex`).
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const onAbort = (): void => {
+      clearTimeout(t);
+      resolve();
+    };
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
 }
 
 /**
@@ -142,6 +157,9 @@ function sleep(ms: number): Promise<void> {
  */
 export async function runPersistentRunnerStream(
   cwd: string = process.cwd(),
+  deps: ExecDeps = {},
+  signal?: AbortSignal,
+  hooks: RunnerHooks = {},
 ): Promise<void> {
   const auth = loadRunnerAuth(cwd);
   cleanStaleSpecFiles(cwd); // drop crash-leftover temp specs before we start
@@ -168,11 +186,16 @@ export async function runPersistentRunnerStream(
   let reconcileTimer: ReturnType<typeof setTimeout>;
   const scheduleReconcile = (): void => {
     reconcileTimer = setTimeout(() => {
-      void safeReconcile(auth);
+      void safeReconcile(auth, deps);
       if (!stopped) scheduleReconcile();
     }, jitter(RECONCILE_INTERVAL_MS));
   };
   scheduleReconcile();
+  // #632: the app's Quit. Unwinds the loop the way a revocation does, minus the message.
+  signal?.addEventListener("abort", () => {
+    stopped = true;
+    currentAbort?.abort();
+  });
 
   let backoff = RECONNECT_BASE_MS;
   try {
@@ -181,13 +204,14 @@ export async function runPersistentRunnerStream(
         // Reconcile UNCONDITIONALLY before/at each (re)connect — a poke missed
         // while disconnected is recovered here (C6). safeReconcile is coalesced +
         // self-contained (its errors never trigger the SSE backoff below).
-        await safeReconcile(auth);
+        await safeReconcile(auth, deps);
         // Close the tiny window where a heartbeat-detected revocation fired
         // against the PREVIOUS (now-null) controller: bail before opening a new
         // stream (Opus nit).
         if (stopped) break;
         currentAbort = new AbortController();
-        const terminal = await streamOnce(auth, currentAbort.signal);
+        const terminal = await streamOnce(auth, currentAbort.signal, deps, hooks);
+        hooks.onConnection?.(false);
         if (terminal || revoked) {
           process.stderr.write("[runner] runner revoked (401) — re-enroll. Stopping.\n");
           stopped = true;
@@ -196,11 +220,12 @@ export async function runPersistentRunnerStream(
         backoff = RECONNECT_BASE_MS; // clean close → reset backoff
         // Floor between reconnections on a CLEAN close, so a server that
         // accepts-then-immediately-closes (200 → done) can't spin a tight loop.
-        if (!stopped) await sleep(RECONNECT_BASE_MS);
+        if (!stopped) await sleep(RECONNECT_BASE_MS, signal);
       } catch (err) {
-        if (revoked) break; // abort was our own revocation teardown, not an error
+        hooks.onConnection?.(false);
+        if (revoked || stopped) break; // abort was our own teardown (revocation or Quit), not an error
         process.stderr.write(`[runner] stream error: ${String(err)} — reconnecting in ${backoff}ms\n`);
-        await sleep(backoff); // error path: single backoff sleep (no double floor)
+        await sleep(backoff, signal); // error path: single backoff sleep (no double floor)
         backoff = Math.min(backoff * 2, RECONNECT_MAX_MS);
       }
     }
@@ -215,7 +240,12 @@ export async function runPersistentRunnerStream(
  * terminal), false on a clean/recoverable close (caller reconnects). Each `spawn`
  * wake-poke triggers a reconcile-pull; the event itself carries no authority.
  */
-async function streamOnce(auth: RunnerAuth, signal: AbortSignal): Promise<boolean> {
+async function streamOnce(
+  auth: RunnerAuth,
+  signal: AbortSignal,
+  deps: ExecDeps = {},
+  hooks: RunnerHooks = {},
+): Promise<boolean> {
   const resp = await fetch(`${auth.base_url}/api/runners/${auth.runner_id}/events`, {
     method: "GET",
     redirect: "error", // never follow a redirect carrying the bearer (Codex review)
@@ -231,6 +261,7 @@ async function streamOnce(auth: RunnerAuth, signal: AbortSignal): Promise<boolea
   if (!resp.ok || !resp.body) {
     throw new Error(`control stream HTTP ${resp.status}`);
   }
+  hooks.onConnection?.(true);
 
   const reader = resp.body.getReader();
   const decoder = new TextDecoder();
@@ -252,7 +283,7 @@ async function streamOnce(auth: RunnerAuth, signal: AbortSignal): Promise<boolea
       // event is a HINT; the durable table is the truth. safeReconcile is
       // coalesced + self-contained (never throws into this stream).
       if (event && event !== "ping" && event !== "connected") {
-        await safeReconcile(auth);
+        await safeReconcile(auth, deps);
       }
     }
   }

package/lib/urls.ts

@@ -8,7 +8,9 @@
  * Introduced in #221 step-05 to replace the legacy /api/voice-events endpoint.
  */
 export function buildSseUrl(voiceBaseUrl: string, conversationId: string): string {
-  return `${voiceBaseUrl}/api/conversations/${conversationId}/events`;
+  // #627: `presence=runner` — the connect is no liveness proof for an agent of this
+  // version; only its runner's roster brings it online.
+  return `${voiceBaseUrl}/api/conversations/${conversationId}/events?presence=runner`;
 }
 
 /**

package/package.json

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

@@ -51,13 +51,11 @@ import {
   ExplicitTargetUnavailableError,
   type ConversationMintResponse,
 } from "./lib/conversation.ts";
-import { startInstanceHeartbeat } from "./lib/heartbeat.ts";
+import { channelPauseReason, type PresenceGate, startCoverageWatch } from "./lib/coverage_watch.ts";
+import { type PresenceEndReason, type PresenceRecordHandle, startPresenceRecord } from "./lib/presence_record.ts";
 import { startParentWatchdog } from "./lib/parent_watchdog.ts";
 import { acquireInstance, maybeAttachTeam, registerInstance } from "./lib/instance.ts";
-import {
-  runPersistentControlStream,
-  sendInstanceHeartbeat,
-} from "./lib/control_stream.ts";
+import { runPersistentControlStream } from "./lib/control_stream.ts";
 import { type DmWatermark, runDmStream } from "./lib/dm_stream.ts";
 import { isOwnMessage } from "./lib/self_echo.ts";
 import {
@@ -329,6 +327,32 @@ let scheduler: TokenRefreshScheduler | null = null;
 // the gate can observe an in-flight shutdown and abort conversation creation.
 let shuttingDown = false;
 
+// #627: this agent's local presence record, read by the machine's runner. Each
+// exit path records HOW it ended; the runner alone decides what that means
+// (closed or down). A death that skips these paths leaves the record active.
+let presence: PresenceRecordHandle | undefined;
+function endPresence(reason: PresenceEndReason): void {
+  presence?.markEnded(reason);
+}
+// #627: the pause gate. Until the runner covers this agent, it neither sends nor
+// delivers anything (it STARTS paused); see lib/coverage_watch.ts.
+let presenceIdentity: "pending" | "none" | PresenceGate = "pending";
+function pauseReason(): string | null {
+  return channelPauseReason(presenceIdentity);
+}
+let resolveGateReady: () => void = () => {};
+const gateReady = new Promise<void>((r) => {
+  resolveGateReady = r;
+});
+/** Inbound delivery waits while paused: DEFERRED, never dropped (#627). */
+async function waitDeliverable(what: string): Promise<void> {
+  if (pauseReason() !== null) {
+    process.stderr.write(`[viber-channel] paused (${pauseReason()}): ${what} deferred\n`);
+  }
+  await gateReady;
+  if (presenceIdentity !== "pending" && presenceIdentity !== "none") await presenceIdentity.waitActive();
+}
+
 // 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,
@@ -336,8 +360,8 @@ process.on("exit", () => { scheduler?.cancel(); releaseLock(); });
 // 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); });
+process.on("SIGINT", () => { endPresence("signal"); scheduler?.cancel(); releaseLock(); process.exit(0); });
+process.on("SIGTERM", () => { endPresence("signal"); scheduler?.cancel(); releaseLock(); process.exit(0); });
 
 // stdin EOF — Claude Code closes its end of the pipe when the session
 // terminates (or the parent process is killed via TerminateProcess on
@@ -355,6 +379,7 @@ process.on("SIGTERM", () => { scheduler?.cancel(); releaseLock(); process.exit(0
 process.stdin.on("end", () => {
   shuttingDown = true;
   process.stderr.write("[viber-channel] stdin closed (parent exited), shutting down\n");
+  endPresence("stdin-end");
   scheduler?.cancel();
   releaseLock();
   process.exit(0);
@@ -452,6 +477,7 @@ const channelToolsCtx: AgentToolsContext = {
   // send_message posts into the main conversation for the Claude MCP.
   sendConversationId: () => CONVERSATION_ID,
   sendConversationToken: () => CONVERSATION_TOKEN,
+  pauseReason: () => pauseReason(),
   // Stream the opened DM so the peer's reply surfaces here (deduped by the Map;
   // a re-join replaces the stream). ws_url is the main conversation's voice host.
   startDmStream: (dm) =>
@@ -782,6 +808,13 @@ try {
   // conversation stays bound to its own SSE, option A). A `stop` (revoke) is
   // logged only: the conversation-token path already fails closed.
   if (OWN_INSTANCE_ID !== "") {
+    presence = startPresenceRecord({
+      identityBaseUrl: WEB_URL,
+      instanceId: OWN_INSTANCE_ID,
+      label: process.env.VIBER_CHANNEL_LABEL ?? null,
+      projectId: auth.project_id,
+      getConversationId: () => CONVERSATION_ID || null,
+    });
     const controlStream = runPersistentControlStream(
       { getBaseUrl: apiBase, instanceId: OWN_INSTANCE_ID, instanceToken },
       {
@@ -789,38 +822,42 @@ try {
         onJoin: (pushed) => startDmStream(pushed),
         onStop: (reason) =>
           process.stderr.write(`[viber-channel] control stream stopped (${reason})\n`),
-        // #311: the server is probing — answer with an immediate instance heartbeat.
-        onBeatNow: () => {
-          void sendInstanceHeartbeat(apiBase(), OWN_INSTANCE_ID, INSTANCE_TOKEN);
-        },
+        // #627: this agent never beats on the network — its runner answers for it
+        // (Python no longer probes a runner-covered agent; an old server may still).
+        onBeatNow: () => {},
       },
     );
     // Presence-only consumer: firstJoin ALWAYS settles (rejected at loop end) —
     // observe it so an ignored join/stop never becomes an unhandled rejection.
     controlStream.firstJoin.catch(() => {});
     controlStream.done.catch(() => {});
-    // #311: beat the INSTANCE control-stream liveness so the server's sweeper
-    // never keeps this agent "online" after it dies (the control SSE can stay
-    // half-open behind the tunnel). The instance_token is durable (#269/#274),
-    // read via closure so a re-register is picked up. unref'd internally.
-    const instanceHeartbeat = startInstanceHeartbeat({
-      getBaseUrl: apiBase,
+    // #627: NO network heartbeat any more (JP's decision). The machine's runner
+    // vouches for this agent and relays its conversation lease through a local
+    // coverage file; this watch re-reads it every 15 s, PAUSES the agent when it goes
+    // stale (no write without a confirmed lease), and closes the channel on a lost
+    // lease exactly as the old heartbeat did (#400).
+    const watch = startCoverageWatch({
+      identityBaseUrl: WEB_URL,
       instanceId: OWN_INSTANCE_ID,
-      getInstanceToken: () => INSTANCE_TOKEN,
-      // #400 (recadrage): renew this agent's conversation lease each beat. If the
-      // server reports the lease was taken over (a new holder), or too many
-      // consecutive indeterminate beats, close the channel — never stay a second
-      // live agent on a conversation another agent now owns.
       getConversationId: () => CONVERSATION_ID || null,
       onLeaseLost: () => {
+        endPresence("lease-lost");
         scheduler?.cancel();
         releaseLock();
         process.exit(0);
       },
     });
-    // Stop beating once the control stream ends (revoke / 401 / abort) so a
-    // doomed instance doesn't keep beating (Opus review).
-    controlStream.done.finally(() => instanceHeartbeat.stop());
+    presenceIdentity = watch.gate;
+    resolveGateReady();
+    controlStream.done.finally(() => watch.stop());
+  } else {
+    // #627: no instance identity → no presence record → no runner can cover this
+    // channel. Never a silent, permanent pause: it runs as before #627, and says so.
+    presenceIdentity = "none";
+    resolveGateReady();
+    process.stderr.write(
+      "[viber-channel] WARNING: no instance id from the server — this channel cannot be covered by a runner; running WITHOUT presence or lease (#627)\n",
+    );
   }
 
   // Schedule silent token refresh ahead of expiry (#237 step-03). On success
@@ -972,6 +1009,7 @@ function sleep(ms: number): Promise<void> {
 
 async function pushTranscript(text: string, lang: string): Promise<void> {
   process.stderr.write(`[viber-channel] Speech detected: "${text}"\n`);
+  await waitDeliverable("transcript");
   await mcp.notification({
     method: "notifications/claude/channel",
     params: {
@@ -1047,6 +1085,7 @@ async function pushMessage(
   // conversation's voice/text flow.
   origin?: { conversationId: string },
 ): Promise<void> {
+  await waitDeliverable("message");
   process.stderr.write(`[viber-channel] pushMessage ENTER: "${msg.content.slice(0, 60)}"\n`);
   // Never echo this channel's OWN posted messages back to Claude (#280 step-16):
   // send_message posts as this instance, and the conversation SSE replays it.
@@ -1204,6 +1243,7 @@ async function sseLoop(): Promise<void> {
         case "stop":
           process.stderr.write(`[viber-channel] Received stop signal, clearing session handle and exiting.\n`);
           clearHandle(SESSION_FILE);
+          endPresence("revoked");
           scheduler?.cancel();
           releaseLock();
           process.exit(0);

package/viber-codex-bridge.ts

@@ -6,7 +6,8 @@
  * messages into a bridge-owned persistent Codex app-server thread, and posts
  * Codex's final assistant reply back into Viber.
  */
-import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { spawn } from "./lib/hidden_proc.js";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -28,6 +29,7 @@ import {
   acquireBridgeLock as coreAcquireBridgeLock,
   agentIdentityFromEnv,
   BridgeShutdownError,
+  endBridgePresence,
   type BridgeLock,
   type BridgeWatermark,
   type ConversationMessage,
@@ -115,6 +117,8 @@ import {
   ControlStreamAuthError,
 } from "./lib/control_stream.ts";
 import { startInstanceHeartbeat } from "./lib/heartbeat.ts";
+import { type PresenceGate, REASON_NO_RUNNER as REASON_STARTING, startCoverageWatch } from "./lib/coverage_watch.ts";
+import { startPresenceRecord } from "./lib/presence_record.ts";
 import { startBridgeToolHost, type BridgeToolHost } from "./lib/bridge_tool_host.ts";
 import type { AgentToolsContext } from "./lib/agent_tools.ts";
 import type { OpenDmResult } from "./lib/peers.ts";
@@ -1277,6 +1281,9 @@ async function acquireBridgeIdentity(
  * main() no longer uses it — it drives MULTI-conversation joins via its own
  * control stream (acquireBridgeIdentity + startConversationStream per join).
  */
+// ⚠ #627: this REFERENCE path still starts the pre-#627 network heartbeat. main() has
+// not used it since #303. Do NOT wire it back without replacing that heartbeat by
+// `startCoverageWatch` — a per-session beat is exactly what #627 removed.
 export async function acquireConversationViaInvite(
   options: BridgeOptions,
   auth: AuthJson,
@@ -1314,7 +1321,7 @@ export async function acquireConversationViaInvite(
         shutdown.abort(
           reason === "unauthorized"
             ? new BridgeShutdownError("instance token revoked or invalid", 3)
-            : new BridgeShutdownError("instance revoked", 0),
+            : new BridgeShutdownError("instance revoked", 0, "revoked"),
         );
       },
       // #311: answer the server's liveness probe with an immediate heartbeat.
@@ -1348,7 +1355,7 @@ export async function acquireConversationViaInvite(
     // promise, then release the lock (the success path returns it to main()).
     await controlStream.done.catch(() => {});
     bridgeLock.release();
-    if (err instanceof ControlStreamStopped) throw new BridgeShutdownError("instance revoked", 0);
+    if (err instanceof ControlStreamStopped) throw new BridgeShutdownError("instance revoked", 0, "revoked");
     if (err instanceof ControlStreamAuthError) {
       throw new BridgeShutdownError("instance token revoked or invalid", 3);
     }
@@ -1371,6 +1378,8 @@ function setupCodexRuntime(deps: {
   getVoiceBaseUrl: () => string;
   startConversation: (minted: ConversationMintResponse) => void;
   requestShutdown: (err: BridgeShutdownError) => void;
+  /** #627: why the bridge is paused (null = may write). */
+  pauseReason: () => string | null;
 }): { codex: CodexAppServer; toolHost: BridgeToolHost } {
   const { tracker } = deps;
   const bridgeToolsCtx: AgentToolsContext = {
@@ -1381,6 +1390,7 @@ function setupCodexRuntime(deps: {
     sendConversationId: () => tracker.conversationId(),
     sendConversationToken: () => tracker.conversationToken(),
     abortSignal: () => tracker.signalForPost(),
+    pauseReason: () => deps.pauseReason(),
     // message_agent opened a DM — stream it so the peer's reply drives a turn.
     startDmStream: (dm: OpenDmResult) => {
       deps.startConversation({
@@ -1499,6 +1509,7 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
           getVoiceBaseUrl: helpers.getVoiceBaseUrl,
           startConversation: helpers.startConversation,
           requestShutdown: helpers.requestShutdown,
+          pauseReason: helpers.pauseReason,
         });
         codex = rt.codex;
         toolHost = rt.toolHost;
@@ -1521,6 +1532,8 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
     let codex: CodexAppServer | null = null;
     let toolHost: BridgeToolHost | null = null;
     const res = await acquireTargetConversation(options.conversationId, options, auth, fingerprint);
+    // #627: filled once the coverage watch starts (below); until then the bridge is paused.
+    const gateRef: { gate?: PresenceGate } = {};
     // `satisfies` (not `as const`) so an omitted field is a COMPILE error here,
     // at construction, instead of surfacing as `undefined` inside the stream.
     // #480 found this the hard way: `identityBaseUrl` was missing and the session
@@ -1554,6 +1567,7 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
       requestShutdown: (err) => {
         if (!shutdown.signal.aborted) shutdown.abort(err);
       },
+      pauseReason: () => gateRef.gate?.reason() ?? REASON_STARTING,
     });
     codex = rt.codex;
     toolHost = rt.toolHost;
@@ -1566,22 +1580,42 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
     // it expires after the TTL while the agent is alive and the conversation
     // falsely frees → another agent could load onto it. On a definite loss (a new
     // holder took over), shut down so we never double-attach.
-    const ihb = startInstanceHeartbeat({
-      getBaseUrl: apiBase,
+    // #627: the local presence record read by the machine's runner.
+    let streamEnd: unknown;
+    const presence = startPresenceRecord({
+      identityBaseUrl: IDENTITY_URL,
+      instanceId: res.instanceKey,
+      label: process.env.VIBER_CODEX_BRIDGE_LABEL ?? null,
+      projectId: auth.project_id,
+      getConversationId: () => res.minted.conversation_id,
+      lockDir: LOCK_DIR(),
+    });
+    // #627: no network heartbeat — the runner vouches for this bridge and relays the
+    // lease of its ONE conversation through the local coverage file.
+    const watch = startCoverageWatch({
+      identityBaseUrl: IDENTITY_URL,
       instanceId: res.instanceKey,
-      getInstanceToken: () => res.instanceToken,
       getConversationId: () => res.minted.conversation_id,
       onLeaseLost: () =>
         shutdown.abort(
-          new BridgeShutdownError("conversation lease lost (taken over)", 0),
+          new BridgeShutdownError("conversation lease lost (taken over)", 0, "lease-lost"),
         ),
+      lockDir: LOCK_DIR(),
+      log: (m) => process.stderr.write(`${LOG_PREFIX} ${m}`),
     });
-    shutdown.signal.addEventListener("abort", () => ihb.stop(), { once: true });
+    gateRef.gate = watch.gate;
+    shutdown.signal.addEventListener("abort", () => watch.stop(), { once: true });
     try {
       // Await the one conversation directly so a fatal error (token expiry → exit 3)
       // propagates, preserving the pre-#303 exit semantics.
-      await coreRunConversationStream(res.minted, { ...runTurnDeps, makeRunTurn: makeCodexAdapter(codex, res.instanceKey) });
+      await coreRunConversationStream(res.minted, { ...runTurnDeps, gate: watch.gate, makeRunTurn: makeCodexAdapter(codex, res.instanceKey) });
+    } catch (err) {
+      // #627: on this path the one conversation's end IS the bridge's end, so a
+      // stop thrown by the stream (not an abort) must reach the presence record.
+      streamEnd = err;
+      throw err;
     } finally {
+      endBridgePresence(presence, shutdown.signal.aborted ? shutdown.signal.reason : streamEnd);
       if (!shutdown.signal.aborted) shutdown.abort();
       for (const ctrl of activeStreams.values()) ctrl.abort(new BridgeShutdownError("bridge shutdown", 0));
       codex?.close();