viber-channel 0.8.19 → 0.8.21

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/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";
@@ -308,8 +316,12 @@ export async function postBridgeReply(opts: {
 	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, opts.fetchImpl ?? fetch);
@@ -529,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;
 }
 
 /**
@@ -598,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();
@@ -651,8 +665,11 @@ 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;
@@ -722,7 +739,7 @@ export async function sseLoop(opts: {
 				rearmFailureNotice();
 				return false;
 			case "auto-post":
-				await postBridgeReply({ baseUrl: baseUrl(), runtime, text: reply, ownPostedIds, signal, logPrefix, fetchImpl });
+				await postBridgeReply({ baseUrl: baseUrl(), runtime, text: reply, ownPostedIds, signal, logPrefix, fetchImpl, gate: deps.gate });
 				rearmFailureNotice();
 				return false;
 		}
@@ -801,6 +818,7 @@ export async function sseLoop(opts: {
 				signal,
 				logPrefix,
 				fetchImpl,
+				gate: deps.gate,
 			});
 			lastAnnouncedCause = key;
 		} catch (notifyErr) {
@@ -837,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 {
@@ -956,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) {
@@ -1344,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. */
@@ -1396,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
@@ -1419,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) => {
@@ -1441,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);
@@ -1452,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 });
 
@@ -1468,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));
@@ -1499,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/bridge_spawn.ts

@@ -14,7 +14,7 @@
  * the bridge's default "register a fresh instance" path.
  */
 
-import { spawn as nodeSpawn } from "node:child_process";
+import { spawn as nodeSpawn } from "./hidden_proc.js";
 import type { AgentSpec, ChildHandle, SpawnFn } from "./supervisor.ts";
 
 /** Minimal child surface the adapter consumes (matches node's ChildProcess). */

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`;
 }
 
 /**

package/lib/coverage_watch.ts

@@ -0,0 +1,244 @@
+/**
+ * coverage_watch.ts — the agent side of runner-owned presence (#627 step-06).
+ *
+ * JP's decision: no per-session heartbeat any more. An agent of this version never
+ * beats on the network; its machine's RUNNER vouches for it and relays, after each
+ * acknowledged beat, a local COVERAGE file (`runner_roster.ts`):
+ *
+ *   <presenceDir>/<instance_id>.coverage.json
+ *     { lease_active: true|false|null, beat_id, conversation_id, written_at }
+ *
+ * Every 15 s this module re-reads it (a local read, zero network) and decides:
+ *
+ *   - fresh coverage, lease true          → ACTIVE;
+ *   - lease false                         → the conversation was taken over: the
+ *                                           channel closes, as before (#400);
+ *   - lease null                          → the existing tolerance: 3 indeterminate
+ *                                           answers from 3 DISTINCT beats, then close;
+ *                                           the same file read twice counts once;
+ *   - coverage older than 120 s, absent,
+ *     or for another conversation         → PAUSED: nothing is sent, nothing is
+ *                                           delivered, until a fresh coverage returns.
+ *
+ * Why 120 s (plan 627, table of delays): pause (120) + one reread (15) = 135 s <
+ * the 210 s lease — so an old holder has stopped writing before anyone else can
+ * take its conversation. The conversation writes carry no fencing token; this
+ * ordering IS the guard.
+ *
+ * An agent STARTS paused, until its first coverage. An agent in await-invite has no
+ * conversation: there is no lease to follow, only the runner's freshness.
+ *
+ * Freshness is judged on the LOCAL clock of the coverage write (`written_at`),
+ * never on the server's beat id.
+ */
+import { readFileSync } from "node:fs";
+import { DEFAULT_MAX_INDETERMINATE_LEASE_BEATS } from "./heartbeat.js";
+import { runnerStatePath, readRunnerState } from "./runner_registry.js";
+import { coveragePath } from "./runner_roster.js";
+
+export const COVERAGE_REREAD_MS = 15_000;
+export const PAUSE_AFTER_MS = 120_000;
+/** The #400 tolerance, ONE definition (Opus M3). */
+export const MAX_INDETERMINATE_LEASES = DEFAULT_MAX_INDETERMINATE_LEASE_BEATS;
+
+export const REASON_NO_RUNNER = "aucun runner connecté pour ce backend";
+export const REASON_LEASE_UNCONFIRMED = "bail non confirmé par le runner";
+
+/**
+ * The pause gate the channel consults before sending or delivering anything.
+ * `waitActive()` resolves at once when active; while paused it resolves on resume.
+ */
+/**
+ * #627 — the channel's pause decision when it may have NO instance identity. An
+ * agent the server gave no instance id has no presence record, so no runner can
+ * ever cover it: pausing it would be a silent, permanent wait. It then runs as
+ * before #627 (no pause, and no lease either), which the channel logs LOUDLY once.
+ * With an identity, the gate decides; before the gate exists, it is starting.
+ */
+export function channelPauseReason(identity: "pending" | "none" | PresenceGate): string | null {
+  if (identity === "none") return null;
+  if (identity === "pending") return REASON_STARTING;
+  return identity.reason();
+}
+
+export const REASON_STARTING = "canal en démarrage";
+
+export class PresenceGate {
+  private pauseReason: string | null;
+  private waiters: Array<() => void> = [];
+
+  /** Pending waiters (tests). */
+  pendingWaiters(): number {
+    return this.waiters.length;
+  }
+
+  constructor(initialReason: string | null) {
+    this.pauseReason = initialReason;
+  }
+
+  /** null when active; otherwise why the agent is paused. */
+  reason(): string | null {
+    return this.pauseReason;
+  }
+
+  isPaused(): boolean {
+    return this.pauseReason !== null;
+  }
+
+  /** Resolves when active — or when `signal` aborts, so a paused agent can still shut down. */
+  waitActive(signal?: AbortSignal): Promise<void> {
+    if (this.pauseReason === null || signal?.aborted) return Promise.resolve();
+    return new Promise((resolve) => {
+      // The abort listener is REMOVED on a normal resume, so repeated pauses do not
+      // pile listeners on one long-lived signal (Codex, step-06 review).
+      const onAbort = (): void => {
+        // An aborted waiter leaves the list too: streams stopped during a long pause
+        // must not pile up (Codex, step-06 review).
+        const i = this.waiters.indexOf(done);
+        if (i >= 0) this.waiters.splice(i, 1);
+        done();
+      };
+      const done = (): void => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      };
+      this.waiters.push(done);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+
+  set(reason: string | null): void {
+    this.pauseReason = reason;
+    if (reason === null) for (const w of this.waiters.splice(0)) w();
+  }
+}
+
+interface CoverageFile {
+  lease_active: boolean | null;
+  beat_id: string;
+  conversation_id: string | null;
+  written_at: number;
+}
+
+function readCoverage(path: string): CoverageFile | null {
+  try {
+    const v = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    const lease = v.lease_active;
+    if (!(lease === true || lease === false || lease === null)) return null;
+    if (typeof v.beat_id !== "string" || v.beat_id === "") return null;
+    if (!(v.conversation_id === null || typeof v.conversation_id === "string")) return null;
+    if (typeof v.written_at !== "number") return null;
+    return { lease_active: lease, beat_id: v.beat_id, conversation_id: v.conversation_id, written_at: v.written_at };
+  } catch {
+    return null;
+  }
+}
+
+export interface CoverageWatchOptions {
+  identityBaseUrl: string;
+  instanceId: string;
+  /** Read on every tick: the agent may be re-bound to another conversation. */
+  getConversationId: () => string | null;
+  /** The conversation was definitely lost: close, exactly as the old heartbeat did. */
+  onLeaseLost: () => void;
+  lockDir?: string;
+  now?: () => number;
+  rereadMs?: number;
+  pauseAfterMs?: number;
+  maxIndeterminate?: number;
+  log?: (line: string) => void;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+}
+
+export interface CoverageWatch {
+  gate: PresenceGate;
+  /** One evaluation, now (the timer calls it; tests too). */
+  tick: () => void;
+  stop: () => void;
+}
+
+export function startCoverageWatch(opts: CoverageWatchOptions): CoverageWatch {
+  const now = opts.now ?? Date.now;
+  const pauseAfter = opts.pauseAfterMs ?? PAUSE_AFTER_MS;
+  const maxIndeterminate = opts.maxIndeterminate ?? MAX_INDETERMINATE_LEASES;
+  const log = opts.log ?? ((line: string) => process.stderr.write(line));
+  const setTimer =
+    opts.setTimer ??
+    ((fn: () => void, ms: number) => {
+      const h = setInterval(fn, ms);
+      (h as { unref?: () => void }).unref?.();
+      return h as unknown;
+    });
+  const clearTimer = opts.clearTimer ?? ((h: unknown) => clearInterval(h as ReturnType<typeof setInterval>));
+
+  const gate = new PresenceGate(REASON_NO_RUNNER);
+  const covPath = coveragePath(opts.identityBaseUrl, opts.instanceId.toLowerCase(), opts.lockDir);
+  const runnerPath = runnerStatePath(opts.identityBaseUrl, opts.lockDir);
+  const countedNullBeats = new Set<string>();
+  let lost = false;
+
+  const pause = (reason: string): void => {
+    if (gate.reason() !== reason) log(`[presence] paused: ${reason}\n`);
+    gate.set(reason);
+  };
+  const resume = (): void => {
+    if (gate.isPaused()) log("[presence] resumed: covered by the runner\n");
+    gate.set(null);
+  };
+  const loseLease = (why: string): void => {
+    if (lost) return;
+    lost = true;
+    log(`[presence] conversation lease lost (${why}) — closing\n`);
+    gate.set(REASON_LEASE_UNCONFIRMED);
+    opts.onLeaseLost();
+  };
+
+  const tick = (): void => {
+    if (lost) return;
+    const t = now();
+    const cov = readCoverage(covPath);
+    const fresh = cov !== null && t - cov.written_at <= pauseAfter;
+    if (!fresh) {
+      const runner = readRunnerState(runnerPath);
+      const runnerFresh = runner?.last_beat_ok_at !== null && runner !== null && t - (runner.last_beat_ok_at as number) <= pauseAfter;
+      pause(runnerFresh ? REASON_LEASE_UNCONFIRMED : REASON_NO_RUNNER);
+      return;
+    }
+    const conversation = opts.getConversationId();
+    if (conversation === null) {
+      // await-invite: no lease to follow — the runner's word is enough.
+      resume();
+      return;
+    }
+    if (cov.conversation_id !== conversation) {
+      pause(REASON_LEASE_UNCONFIRMED); // a lease renewed for ANOTHER conversation proves nothing
+      return;
+    }
+    if (cov.lease_active === false) {
+      loseLease("taken over");
+      return;
+    }
+    if (cov.lease_active === null) {
+      if (!countedNullBeats.has(cov.beat_id)) {
+        countedNullBeats.add(cov.beat_id);
+        if (countedNullBeats.size >= maxIndeterminate) {
+          loseLease(`${countedNullBeats.size} indeterminate beats`);
+          return;
+        }
+      }
+      resume(); // tolerated, as the old heartbeat did
+      return;
+    }
+    countedNullBeats.clear();
+    resume();
+  };
+
+  tick();
+  const timer = setTimer(tick, opts.rereadMs ?? COVERAGE_REREAD_MS);
+  return {
+    gate,
+    tick,
+    stop: () => clearTimer(timer),
+  };
+}

package/lib/fingerprint.ts

@@ -1,4 +1,4 @@
-import { execSync } from "node:child_process";
+import { execSync } from "./hidden_proc.js";
 import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
 

package/lib/hidden_proc.ts

@@ -0,0 +1,99 @@
+/**
+ * hidden_proc.ts — the ONLY door to `node:child_process` and `Bun.spawn*` in this package (#638).
+ * vibe-master and viber-gateway re-export it, so there is ONE `hide()` for the three packages.
+ *
+ * The Viber app (`viber-gateway.exe`) is a GUI-subsystem binary: it has no console. On Windows a
+ * console child of a console-less parent gets a NEW, VISIBLE console unless the spawn passes
+ * `windowsHide: true`. The runner heartbeat (every 30 s) enumerates processes through PowerShell,
+ * so each beat flashed a window.
+ *
+ * Measured (#638 step-01, bun 1.3.14, compiled `--windows-hide-console` exe started through WMI):
+ *
+ * ```
+ * execFileSync / execSync / exec / Bun.spawnSync   hide=false -> child console visible=True
+ *                                                  hide=true  -> child hwnd=0 (NO console at all)
+ * ```
+ *
+ * `hwnd=0` is a console WITHOUT a window (CREATE_NO_WINDOW), and it is inherited: the `exec` rows are
+ * already a GRANDCHILD (`cmd.exe /c powershell`) and read `hwnd=0` too. So hiding the first edge may be
+ * enough for console descendants — but not for a Bun/Node parent that spawns with its own flags.
+ * Measured again for a Bun parent (step-03): compiled GUI exe -> Bun console child spawned with
+ * hide=true -> its grandchild spawned WITHOUT hide reads `hwnd=0 visible=False`; child hide=false ->
+ * grandchild `visible=True`. So hiding the first edge is enough for console descendants.
+ * Every spawn still goes through this helper BY DECISION (plan 638, defence in depth): the next first
+ * edge is written by someone who has not read this.
+ * No-op outside Windows.
+ */
+import * as cp from "node:child_process";
+
+/** Every option object that reaches `child_process` passes here. Exported for its witness. */
+export function hide<T extends object>(opts: T | undefined): T & { windowsHide: true } {
+  return { ...(opts ?? ({} as T)), windowsHide: true };
+}
+
+type Backend = Pick<typeof cp, "exec" | "execSync" | "execFile" | "execFileSync" | "spawn">;
+
+/**
+ * `execFile` / `execFileSync` / `spawn` accept `args` OR options in 2nd place (and `execFile` a
+ * callback anywhere). Split them so a call without `args` still carries its options through `hide`.
+ */
+function splitArgs(rest: unknown[]): { args: readonly string[]; tail: unknown[] } {
+  return Array.isArray(rest[0]) ? { args: rest[0] as readonly string[], tail: rest.slice(1) } : { args: [], tail: rest };
+}
+
+function optsAndCallback(tail: unknown[]): { opts: object | undefined; cb: unknown } {
+  const cb = tail.find((t) => typeof t === "function");
+  const opts = tail.find((t) => t !== null && typeof t === "object") as object | undefined;
+  return { opts, cb };
+}
+
+/** The wrappers over a given backend. Exported so the witness can hand a recording fake (a
+ *  `mock.module` of `node:child_process` leaks into every other test file of the run). */
+export function hiddenOver(b: Backend): Backend {
+  return {
+    exec: ((command: string, ...rest: unknown[]) => {
+      const { opts, cb } = optsAndCallback(rest);
+      return b.exec(command, hide(opts as cp.ExecOptions | undefined), cb as Parameters<typeof cp.exec>[2]);
+    }) as typeof cp.exec,
+    execSync: ((command: string, options?: cp.ExecSyncOptions) => b.execSync(command, hide(options))) as typeof cp.execSync,
+    execFile: ((file: string, ...rest: unknown[]) => {
+      const { args, tail } = splitArgs(rest);
+      const { opts, cb } = optsAndCallback(tail);
+      return b.execFile(file, args, hide(opts as cp.ExecFileOptions | undefined), cb as Parameters<typeof cp.execFile>[3]);
+    }) as typeof cp.execFile,
+    execFileSync: ((file: string, ...rest: unknown[]) => {
+      const { args, tail } = splitArgs(rest);
+      return b.execFileSync(file, args, hide(tail[0] as cp.ExecFileSyncOptions | undefined));
+    }) as typeof cp.execFileSync,
+    spawn: ((command: string, ...rest: unknown[]) => {
+      const { args, tail } = splitArgs(rest);
+      return b.spawn(command, args, hide(tail[0] as cp.SpawnOptions | undefined));
+    }) as typeof cp.spawn,
+  };
+}
+
+export const { exec, execSync, execFile, execFileSync, spawn } = hiddenOver(cp);
+
+// ── Bun.spawn* (the channel, vibe-master and the gateway all run on Bun) ──
+
+type BunSpawn = typeof Bun.spawn;
+type BunSpawnSync = typeof Bun.spawnSync;
+
+/**
+ * Both forms of `Bun.spawn*`: `(cmd[], opts)` and `({ cmd, ...opts })` — in the second the options live
+ * in the FIRST argument, so hiding only the second would silently leave it visible.
+ */
+function hiddenArgs(cmd: unknown, opts: unknown): [unknown, unknown?] {
+  return Array.isArray(cmd) ? [cmd, hide(opts as object | undefined)] : [hide(cmd as object)];
+}
+
+/** The wrappers over a given `Bun`. Exported so the witness can hand a recording fake. */
+export function hiddenBunOver(b: { spawn: BunSpawn; spawnSync: BunSpawnSync }): { bunSpawn: BunSpawn; bunSpawnSync: BunSpawnSync } {
+  const call = (f: (...a: unknown[]) => unknown) => (cmd: unknown, opts?: unknown) => f(...hiddenArgs(cmd, opts));
+  return {
+    bunSpawn: call(b.spawn as (...a: unknown[]) => unknown) as BunSpawn,
+    bunSpawnSync: call(b.spawnSync as (...a: unknown[]) => unknown) as BunSpawnSync,
+  };
+}
+
+export const { bunSpawn, bunSpawnSync } = hiddenBunOver(Bun);

package/lib/parent_watchdog.ts

@@ -20,7 +20,7 @@
  * still alive". `signal 0` probes existence without delivering a signal.
  */
 
-import { execSync } from "node:child_process";
+import { execSync } from "./hidden_proc.js";
 
 /**
  * Shim processes that sit BETWEEN the real agent (e.g. claude.exe) and us in the