viber-channel 0.8.7 → 0.8.8

package/lib/bridge_core.ts

@@ -46,6 +46,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;
@@ -333,6 +348,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,6 +419,13 @@ 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;
@@ -405,7 +453,7 @@ 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, baseUrl, lockDir, logPrefix, sessionTag, makeRunTurn } = deps;
 	const convId = minted.conversation_id;
 	if (parentSignal.aborted) return;
 
@@ -443,7 +491,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, baseUrl, logPrefix, runTurn, watermark });
 	} finally {
 		parentSignal.removeEventListener("abort", onParentAbort);
 		runtime.scheduler?.cancel();
@@ -484,8 +540,21 @@ export async function sseLoop(opts: {
 	baseUrl: 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, baseUrl, logPrefix, runTurn, watermark } = opts;
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const fetchMessagesImpl = opts.fetchMessagesImpl ?? fetchMessages;
 	const sseUrl = buildSseUrl(minted.ws_url, minted.conversation_id);
 	const ownPostedIds = new Set<string>();
 
@@ -563,7 +632,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 +642,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 +667,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 +690,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 +743,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}`);
 
@@ -983,6 +1066,11 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 	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 = "";
@@ -998,6 +1086,7 @@ export async function runAwaitInviteBridge(adapter: AwaitInviteAdapter): Promise
 			instanceKey,
 			options,
 			activeStreams,
+			watermarks,
 			parentSignal: shutdown.signal,
 			baseUrl,
 			lockDir,

package/lib/fingerprint.ts

@@ -45,3 +45,14 @@ export function clientFingerprint(folderPath: string): string {
   const absPath = normalizePath(realpathSync(folderPath) as string);
   return createHash("sha256").update(`${machineId}:${absPath}`).digest("hex").slice(0, 32);
 }
+
+/**
+ * Per-MACHINE fingerprint (#460 Phase 2, step-07) — the runner is a machine-level
+ * principal, so unlike clientFingerprint it is folder-INDEPENDENT. 32 hex chars,
+ * matching the server's bound format (`/^[0-9a-zA-Z_-]{8,128}$/`). Deterministic:
+ * re-enrolling the same machine yields the same fingerprint (→ atomic rotation).
+ */
+export function machineFingerprint(): string {
+  const machineId = getMachineId();
+  return createHash("sha256").update(`runner:${machineId}`).digest("hex").slice(0, 32);
+}

package/lib/heartbeat.ts

@@ -15,7 +15,32 @@
 
 import { type HeartbeatResult, sendInstanceHeartbeat } from "./control_stream.ts";
 
-export const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
+/**
+ * #478 — 25s → 60s to cut CF Worker requests (the instance heartbeat was ~59% of
+ * all Worker traffic, the single dominant source). Every beat is one
+ * `POST /api/instances/:id/heartbeat` = one Worker request per agent, forever.
+ *
+ * The three server-side windows this must stay under were raised in the same
+ * change so a 60s cadence keeps the SAME safety margins it had at 25s:
+ *   - `VIBER_INSTANCE_PROBE_SUSPECT` (voice_pipeline.py) 8s → 75s. This is the
+ *     one that actually caused the observed ~10-13s effective cadence: the
+ *     sweeper probed (`beat_now`) every agent whose liveness was older than 8s,
+ *     i.e. every 15s sweep, and each probe forces an EXTRA beat on top of the
+ *     timer. With SUSPECT > the beat interval, a healthy agent is never probed
+ *     and the timer is the only beat. Cost: a CRASHED agent is force-offlined in
+ *     ~90-105s instead of ~13s — both probe stages are quantized to the 15s
+ *     sweep, so arming AND deadline-enforcement each cost up to one sweep on top
+ *     of SUSPECT + PROBE_TIMEOUT (Codex review of #478).
+ *   - `VIBER_INSTANCE_CONTROL_PRESENCE_TIMEOUT` 90s → 150s, so a single missed
+ *     beat still cannot force an agent offline (150 > 2 x 60).
+ *   - `LEASE_TTL_SECONDS` (viber-api) 90s → 180s, same reason for the #400 lease.
+ *
+ * NB do NOT "de-dupe" the `beat_now` answer client-side: an unanswered probe
+ * force-offlines the agent at its deadline (`_enforce_instance_probes` requires
+ * a beat at-or-after `requested_at`), so skipping it would false-offline a live
+ * agent. The probe is fixed by not suspecting healthy agents, not by ignoring it.
+ */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
 
 /**
  * #400 (recadrage) — consecutive INDETERMINATE lease beats tolerated before the
@@ -26,9 +51,11 @@ export const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
 export const DEFAULT_MAX_INDETERMINATE_LEASE_BEATS = 3;
 
 /**
- * Resolve the beat interval from the environment (seconds), defaulting to 25s.
- * Must stay comfortably under the server timeout (VIBER_CHANNEL_PRESENCE_TIMEOUT,
- * default 90s) so a single missed beat never trips the sweeper.
+ * Resolve the beat interval from the environment (seconds), defaulting to 60s.
+ * Must stay under HALF the server presence timeout
+ * (VIBER_INSTANCE_CONTROL_PRESENCE_TIMEOUT, default 150s since #478) so a single
+ * missed beat never trips the sweeper, and under VIBER_INSTANCE_PROBE_SUSPECT
+ * (default 75s) so a healthy agent is never `beat_now`-probed.
  */
 export function resolveHeartbeatIntervalMs(
   env: Record<string, string | undefined> = process.env,

package/lib/messages.ts

@@ -112,10 +112,11 @@ export async function ackMessage(
   conversationToken: string,
   messageId: string | number,
   signal?: AbortSignal,
+  fetchImpl: typeof fetch = fetch,
 ): Promise<boolean> {
   const url = `${baseUrl}/api/conversations/${conversationId}/messages/${messageId}/ack`;
   try {
-    const resp = await fetch(url, {
+    const resp = await fetchImpl(url, {
       method: "POST",
       headers: { Authorization: `Bearer ${conversationToken}`, ...cfAccessHeaders() },
       signal,

package/lib/runner_enroll.ts

@@ -0,0 +1,210 @@
+/**
+ * runner_enroll.ts — client side of the runner enrollment ceremony (#460 Phase 2,
+ * step-07/#472). Turns an enrollment URL into `.viber/runner.json` so the machine
+ * can run the resident spawn daemon.
+ *
+ * Invoked as:
+ *   bunx viber-channel enroll-runner "https://viber.dgypx.dev/connect/runner/<claim_id>#<wait_token>"
+ *
+ * The owner opens the enrollment in the web (JWT-owner, C2), which yields the
+ * URL above carrying the claim_id (path) + the wait_token (fragment — a secret
+ * that gates the CAS bind so a leaked confirm-link can't be pre-bound). The
+ * client here:
+ *   1. generates its OWN runner_token (kept local, never sent — only its SHA-256);
+ *   2. binds (fingerprint + token hash) via the wait_token;
+ *   3. prints the confirm URL for the human to approve the shown fingerprint;
+ *   4. polls consume until the runner is materialized;
+ *   5. writes `.viber/runner.json` (0600) with the raw token.
+ */
+
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { dirname, join } from "node:path";
+import { machineFingerprint } from "./fingerprint.js";
+import { cfAccessHeaders } from "./cfAccess.js";
+import { isTrustedViberOrigin } from "./urls.js";
+
+const POLL_INTERVAL_MS = 2000;
+const MAX_POLL_DURATION_MS = 10 * 60 * 1000;
+
+export interface ParsedEnrollUrl {
+  baseUrl: string;
+  claimId: string;
+  waitToken: string;
+}
+
+const CLAIM_ID_RE = /^[a-f0-9]{16,64}$/i; // server mints randomHex(16) = 32 hex
+const WAIT_TOKEN_RE = /^[a-f0-9]{64}$/; // server mints randomHex(32) = 64 hex
+
+/**
+ * Parse + HARDEN an enrollment URL (Codex review — adversarial inputs).
+ * Uses the WHATWG `URL` parser (canonicalizes `%2F`, `\`, `//`, ports) then:
+ *   - rejects userinfo (`user:pass@host` — no credential smuggling);
+ *   - requires https (or explicit localhost for dev);
+ *   - accepts EXACTLY `/connect/runner/<claim_id>` (claim id format-checked);
+ *   - takes the wait_token ONLY from the fragment, format-checked (64 hex).
+ * The fragment never reaches the server/logs (OAuth-implicit pattern); there is
+ * no query-param fallback on purpose (a `?wait_token=` would be logged).
+ */
+export function parseEnrollUrl(input: string): ParsedEnrollUrl {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new Error(`Invalid URL: ${input}`);
+  }
+  if (url.username || url.password) {
+    throw new Error("Enrollment URL must not contain credentials (userinfo).");
+  }
+  // The origin must be a KNOWN Viber host (or configured VIBER_BASE_URL / dev
+  // localhost). Rejects a forged `https://evil.example/...` that would otherwise
+  // capture the runner bearer (Codex review — https alone is not enough).
+  if (!isTrustedViberOrigin(url.origin)) {
+    throw new Error(`Untrusted enrollment origin: ${url.origin}. Expected a Viber host.`);
+  }
+  // Canonical pathname match (URL already decoded %2F etc. — a smuggled
+  // `/connect/runner/x%2F..` would NOT match this exact shape).
+  const match = url.pathname.match(/^\/connect\/runner\/([^/]+)\/?$/);
+  if (!match || !CLAIM_ID_RE.test(match[1])) {
+    throw new Error(
+      "Not a runner enrollment URL. Expected: https://<host>/connect/runner/<claim_id>#<wait_token>",
+    );
+  }
+  const waitToken = url.hash.replace(/^#/, "");
+  if (!WAIT_TOKEN_RE.test(waitToken)) {
+    throw new Error("Enrollment URL is missing/invalid wait_token fragment (#<64-hex>).");
+  }
+  return { baseUrl: url.origin, claimId: match[1], waitToken };
+}
+
+function sha256Hex(input: string): string {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function writeRunnerJson(
+  cwd: string,
+  data: { baseUrl: string; runnerId: string; runnerToken: string; machineFingerprint: string },
+): string {
+  const viberDir = join(cwd, ".viber");
+  mkdirSync(viberDir, { recursive: true });
+  const runnerPath = join(viberDir, "runner.json");
+  mkdirSync(dirname(runnerPath), { recursive: true });
+  const payload = {
+    schema_version: 1,
+    base_url: data.baseUrl,
+    runner_id: data.runnerId,
+    // The bearer — a local-code-execution capability. Stored client-side (the
+    // server keeps only its SHA-256). We request owner-only perms below, but note
+    // the real protection differs by OS (see chmod).
+    runner_token: data.runnerToken,
+    machine_fingerprint: data.machineFingerprint,
+  };
+  writeFileSync(runnerPath, JSON.stringify(payload, null, 2), { encoding: "utf-8", mode: 0o600 });
+  // Honesty (Opus review P1): `mode 0o600` + chmod are POSIX bits — effective on
+  // Linux/macOS (owner-read-only). On WINDOWS (JP's primary platform) NTFS uses
+  // ACLs, not POSIX bits, so this is essentially a no-op: the file inherits the
+  // user profile's ACL. That is the actual protection on Windows — not a claimed
+  // 0600. A stricter explicit ACL (icacls) is a documented follow-up.
+  try {
+    chmodSync(runnerPath, 0o600);
+  } catch {
+    /* best-effort — Windows / some filesystems reject chmod */
+  }
+
+  // Ensure `.viber/` is git-ignored so runner.json (the cleartext bearer) is not
+  // committed on a fresh external repo (mirrors connect.ts — Opus review P1).
+  const gitignorePath = join(cwd, ".gitignore");
+  let current = "";
+  if (existsSync(gitignorePath)) current = readFileSync(gitignorePath, "utf-8");
+  const alreadyIgnored = current
+    .split(/\r?\n/)
+    .some((line) => {
+      const t = line.trim();
+      return t === ".viber/" || t === ".viber";
+    });
+  if (!alreadyIgnored) {
+    const prefix = current === "" || current.endsWith("\n") ? "" : "\n";
+    appendFileSync(gitignorePath, `${prefix}.viber/\n`);
+  }
+  return runnerPath;
+}
+
+/**
+ * Run the enrollment ceremony. Writes `.viber/runner.json` on success; throws on
+ * any terminal outcome (rejected/superseded/expired/timeout).
+ */
+export async function runRunnerEnroll(
+  enrollUrl: string,
+  cwd: string = process.cwd(),
+  label?: string,
+): Promise<void> {
+  const { baseUrl, claimId, waitToken } = parseEnrollUrl(enrollUrl);
+  const fingerprint = machineFingerprint();
+
+  // Client-generated bearer — kept here, only its hash leaves the machine.
+  const runnerToken = randomBytes(32).toString("hex");
+  const tokenHash = sha256Hex(runnerToken);
+
+  process.stderr.write(`[viber-channel] runner fingerprint=${fingerprint.slice(0, 8)}…\n`);
+
+  const bindResp = await fetch(`${baseUrl}/api/connect/runner/${claimId}/bind`, {
+    method: "POST",
+    redirect: "error", // parity with the daemon — never send the secret across a redirect
+    headers: { "Content-Type": "application/json", ...cfAccessHeaders() },
+    body: JSON.stringify({
+      wait_token: waitToken,
+      machine_fingerprint: fingerprint,
+      proposed_runner_token_hash: tokenHash,
+      ...(label ? { label } : {}),
+    }),
+  });
+  if (!bindResp.ok) {
+    const body = await bindResp.text().catch(() => "");
+    throw new Error(`Bind failed (HTTP ${bindResp.status}): ${body}`);
+  }
+
+  process.stdout.write(
+    `\nApprove this machine in your browser (confirm the shown fingerprint):\n` +
+      `  ${baseUrl}/runners/enroll/${claimId}\n\n` +
+      `Polling for confirmation (up to 10 minutes)…\n`,
+  );
+
+  const consumeUrl = `${baseUrl}/api/connect/runner/${claimId}/consume`;
+  const deadline = Date.now() + MAX_POLL_DURATION_MS;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    const resp = await fetch(consumeUrl, {
+      method: "POST",
+      redirect: "error",
+      headers: { "Content-Type": "application/json", ...cfAccessHeaders() },
+      body: JSON.stringify({ wait_token: waitToken }),
+    });
+    if (resp.status === 200) {
+      const data = (await resp.json().catch(() => ({}))) as { runner_id?: string };
+      if (!data.runner_id || typeof data.runner_id !== "string") {
+        throw new Error("Consume succeeded but returned no runner_id — server response malformed.");
+      }
+      const path = writeRunnerJson(cwd, {
+        baseUrl,
+        runnerId: data.runner_id,
+        runnerToken,
+        machineFingerprint: fingerprint,
+      });
+      process.stdout.write(
+        `\n✓ Runner enrolled (id ${data.runner_id.slice(0, 8)}…). Wrote ${path}\n\n` +
+          `Start the runner daemon with:\n  bunx viber-channel run-runner\n\n`,
+      );
+      return;
+    }
+    if (resp.status === 425) continue; // not confirmed yet — keep polling
+    if (resp.status === 409) throw new Error("Superseded by a newer enrollment — re-enroll this machine.");
+    if (resp.status === 401) throw new Error("Invalid wait token — the enrollment URL is wrong or stale.");
+    const body = await resp.text().catch(() => "");
+    throw new Error(`Consume failed (HTTP ${resp.status}): ${body}`);
+  }
+  throw new Error(`Enrollment timed out after ${MAX_POLL_DURATION_MS / 60_000} minutes.`);
+}

package/lib/runner_exec.ts

@@ -0,0 +1,436 @@
+/**
+ * runner_exec.ts — local execution of a claimed spawn command (#460 Phase 2,
+ * step-09/#474). Replaces the step-07 reconcile() stub.
+ *
+ * Flow (per claimed command): validate the SERVER-VALIDATED role snapshot
+ * against the machine's local DEFAULT-DENY policy (permissions = template ∩
+ * local, never widened — C3) → report `starting` → shell
+ * `vibe-master team spawn` via an argv ARRAY (execFile, never a shell string —
+ * no injection) → report `succeeded`/`failed` (fencing-guarded). A 409 report
+ * (re-claim/cancel) → cooperative abort (don't overwrite a newer outcome — C4).
+ *
+ * Dependency-injected: `runTeamSpawn` (the launcher) and `apiFetch` are
+ * injectable so the flow is unit-testable without shelling or a live server.
+ */
+
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cfAccessHeaders } from "./cfAccess.js";
+
+/** A validated role from the server snapshot (allowlisted shape). */
+export interface SnapshotRole {
+  role: string;
+  runtime: string;
+  permission: string;
+  rolePrompt?: string;
+  model?: string;
+  count?: number;
+}
+
+export interface ClaimedCommand {
+  id: string;
+  fencing_token: number;
+  template_name: string;
+  template_spec: { roles: SnapshotRole[] };
+  prefix: string;
+  team_name: string | null;
+  env: string | null;
+}
+
+export interface RunnerAuthLite {
+  base_url: string;
+  runner_id: string;
+  runner_token: string;
+}
+
+/**
+ * Local default-deny policy (`.viber/runner-policy.json`, optional). The machine
+ * can only RESTRICT what a template asks for, never widen it. Conservative
+ * defaults when the file is absent.
+ */
+export interface RunnerPolicy {
+  allowedRuntimes: string[];
+  /** Ceiling permission the machine will grant. */
+  maxPermission: "read-only" | "read-write";
+  maxRoles: number;
+  allowedEnvs: string[];
+}
+
+const DEFAULT_POLICY: RunnerPolicy = {
+  allowedRuntimes: ["claude-code", "codex", "gemma", "claude"],
+  maxPermission: "read-write",
+  maxRoles: 8,
+  allowedEnvs: ["staging", "dev"],
+};
+
+const PERMISSION_RANK: Record<string, number> = { "read-only": 1, "read-write": 2 };
+
+// prefix/team_name become CLI argv. execFile already blocks SHELL injection, but
+// an unconstrained value like "--env" would be an ARGV-FLAG injection into
+// vibe-master. The server validates this too; the runner re-checks (defense in
+// depth) and REFUSES rather than pass a suspicious argv.
+const ARGV_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,31}$/;
+
+/** Thrown when a policy file is PRESENT but malformed — the caller must REFUSE
+ *  execution, never fall back to the permissive baseline (Codex review P1-4). */
+export class RunnerPolicyInvalidError extends Error {}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+/**
+ * Load the local policy. ABSENT file → the baseline (an operator who wrote no
+ * policy accepts the default). PRESENT but malformed (bad JSON / bad shape) →
+ * THROW: it is NOT fail-closed to silently grant read-write when the operator
+ * clearly intended to constrain but fat-fingered the file (Codex review P1-4).
+ */
+export function loadRunnerPolicy(cwd: string = process.cwd()): RunnerPolicy {
+  const path = join(cwd, ".viber", "runner-policy.json");
+  if (!existsSync(path)) return DEFAULT_POLICY;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    throw new RunnerPolicyInvalidError("runner-policy.json is not valid JSON");
+  }
+  if (typeof raw !== "object" || raw === null) {
+    throw new RunnerPolicyInvalidError("runner-policy.json must be an object");
+  }
+  const p = raw as Record<string, unknown>;
+  if (!isStringArray(p.allowedRuntimes)) throw new RunnerPolicyInvalidError("allowedRuntimes must be string[]");
+  if (p.maxPermission !== "read-only" && p.maxPermission !== "read-write") {
+    throw new RunnerPolicyInvalidError("maxPermission must be read-only|read-write");
+  }
+  if (typeof p.maxRoles !== "number" || !Number.isInteger(p.maxRoles) || p.maxRoles < 1) {
+    throw new RunnerPolicyInvalidError("maxRoles must be a positive integer");
+  }
+  if (!isStringArray(p.allowedEnvs)) throw new RunnerPolicyInvalidError("allowedEnvs must be string[]");
+  return {
+    allowedRuntimes: p.allowedRuntimes,
+    maxPermission: p.maxPermission,
+    maxRoles: p.maxRoles,
+    allowedEnvs: p.allowedEnvs,
+  };
+}
+
+/** Validate the server snapshot against the local policy. Returns null if OK, or
+ *  a human reason if the command must be REFUSED (default-deny). */
+export function validateAgainstPolicy(cmd: ClaimedCommand, policy: RunnerPolicy): string | null {
+  const roles = cmd.template_spec?.roles;
+  if (!Array.isArray(roles) || roles.length === 0) return "template has no roles";
+  // Cap on the TOTAL agent count, not just distinct roles (Codex): a role may
+  // carry a `count`, so sum(count ?? 1) is the real agent count. A bad count
+  // (non-positive-int) is itself a refusal.
+  let totalAgents = 0;
+  for (const r of roles) {
+    const n = r.count ?? 1;
+    if (typeof n !== "number" || !Number.isInteger(n) || n < 1) return `invalid role count for '${r.role}'`;
+    totalAgents += n;
+  }
+  if (totalAgents > policy.maxRoles) return `too many agents (${totalAgents} > ${policy.maxRoles})`;
+  if (cmd.env && !policy.allowedEnvs.includes(cmd.env)) return `env '${cmd.env}' not allowed locally`;
+  // Argv-injection guard (defense in depth): prefix/team_name must be plain names,
+  // never something that could be read as a flag by vibe-master.
+  if (!ARGV_NAME_RE.test(cmd.prefix)) return `invalid prefix '${cmd.prefix}'`;
+  if (cmd.team_name !== null && !ARGV_NAME_RE.test(cmd.team_name)) return `invalid team_name '${cmd.team_name}'`;
+  const cap = PERMISSION_RANK[policy.maxPermission] ?? 1;
+  for (const r of roles) {
+    if (!policy.allowedRuntimes.includes(r.runtime)) return `runtime '${r.runtime}' not allowed locally`;
+    const want = PERMISSION_RANK[r.permission];
+    if (want === undefined) return `unknown permission '${r.permission}'`;
+    if (want > cap) return `permission '${r.permission}' exceeds local ceiling '${policy.maxPermission}'`;
+  }
+  return null;
+}
+
+export type TeamSpawnRunner = (
+  args: string[],
+) => Promise<{ ok: boolean; recap: string }>;
+
+/**
+ * Build a CURATED child environment (Codex review, blocking): `execFile` would
+ * otherwise inherit ALL of process.env, exposing every local secret (GitHub,
+ * cloud, unrelated tokens) to the child. Pass only OS essentials + the Viber/CF
+ * vars vibe-master actually needs to spawn agents. Nothing else is inherited.
+ */
+// EXACT-NAME allowlist (Codex review — NOT a prefix sweep). Only OS essentials
+// plus the specific Viber/CF vars vibe-master needs to spawn agents. A generic
+// `VIBER_*`/`CF_ACCESS_*` sweep could pass an unrelated or overly-sensitive
+// secret through to child agents; naming each var keeps exactly what's exposed
+// visible and reviewable. (Extend this list — never a prefix — if step-11 live
+// QA shows vibe-master needs another var.)
+const CHILD_ENV_ALLOW = [
+  // OS essentials
+  "PATH", "Path", "HOME", "USERPROFILE", "SYSTEMROOT", "windir", "TEMP", "TMP", "TMPDIR", "LANG", "APPDATA", "LOCALAPPDATA", "ComSpec",
+  // Viber/CF vars vibe-master requires to reach the backend + CF-Access tunnel
+  "VIBER_BASE_URL", "VIBER_AUTH_FILE", "VIBER_CF_CLIENT_ID", "VIBER_CF_CLIENT_SECRET",
+  "CF_ACCESS_CLIENT_ID", "CF_ACCESS_CLIENT_SECRET",
+];
+
+export function buildChildEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const k of CHILD_ENV_ALLOW) {
+    const v = source[k];
+    if (v !== undefined) env[k] = v;
+  }
+  return env;
+}
+
+/** Redact long secret-like runs (hex/base64/token) from captured output before
+ *  it is reported to the server (Codex — the CLI/children may print secrets). */
+export function redactSecrets(text: string): string {
+  return text
+    .replace(/\b[0-9a-f]{32,}\b/gi, "[redacted-hex]")
+    .replace(/\b[A-Za-z0-9_-]{40,}\b/g, "[redacted-token]");
+}
+
+/** The base command that launches vibe-master. Defaults to the installed
+ *  `vibe-master` on PATH (production). `VIBE_MASTER_CMD` overrides it as a
+ *  space-separated token list so a DEV runner can point at the source
+ *  (`VIBE_MASTER_CMD="bun /path/vibe-master.ts"`) instead of a stale global
+ *  binary — the #460 dev-QA foot-gun ("dev must run from source"). Passed to
+ *  execFile as (bin, [...baseArgs, ...args]) — still an argv array, no shell. */
+export function vibeMasterBaseCmd(source: NodeJS.ProcessEnv = process.env): string[] {
+  const raw = source.VIBE_MASTER_CMD?.trim();
+  const parts = raw ? raw.split(/\s+/) : ["vibe-master"];
+  return parts.length > 0 ? parts : ["vibe-master"];
+}
+
+/** Default launcher: shell vibe-master via execFile with an ARGV ARRAY (never a
+ *  shell string), a CURATED env, bounded time + output, and process-tree kill on
+ *  timeout. The binary is resolved via VIBE_MASTER_CMD (default `vibe-master`). */
+export const execFileTeamSpawn: TeamSpawnRunner = (args) => {
+  const base = vibeMasterBaseCmd();
+  const bin = base[0] as string;
+  return new Promise((resolve) => {
+    execFile(
+      bin,
+      [...base.slice(1), ...args],
+      { timeout: 5 * 60 * 1000, killSignal: "SIGKILL", maxBuffer: 1024 * 1024, env: buildChildEnv() },
+      (err, stdout, stderr) => {
+        const recap = redactSecrets(`${stdout}\n${stderr}`.trim()).slice(0, 4000);
+        resolve({ ok: !err, recap });
+      },
+    );
+  });
+};
+
+/**
+ * Local idempotence by command_id (Codex review, blocking): fencing protects
+ * REPORTS, not the local SIDE EFFECT. If the runner crashes mid-spawn and a new
+ * daemon re-claims the same command, it must NOT relaunch (double team). A
+ * durable marker written BEFORE launch records "this command_id was started
+ * here"; a re-claim seeing the marker refuses to relaunch. (Full reconciliation
+ * — finding+adopting the already-spawned team — is a documented follow-up.)
+ */
+export interface InflightStore {
+  has(commandId: string): boolean;
+  mark(commandId: string): void;
+  clear(commandId: string): void;
+}
+
+function fsInflightStore(cwd: string = process.cwd()): InflightStore {
+  const dir = join(cwd, ".viber", "runner-inflight");
+  const path = (id: string) => join(dir, `${id}.json`);
+  return {
+    has: (id) => existsSync(path(id)),
+    mark: (id) => {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(path(id), JSON.stringify({ started: true }), { mode: 0o600 });
+    },
+    clear: (id) => rmSync(path(id), { force: true }),
+  };
+}
+
+/** Materialize the server-validated snapshot to a temp file the CLI reads via
+ *  `--spec-file`, returning its path + a cleanup. Exclusive create (`wx`, 0600),
+ *  unpredictable name — so vibe-master runs EXACTLY the authorized roles, never a
+ *  name-resolved local template (P1-1). */
+export interface SpecFileWriter {
+  (spec: { name: string; roles: SnapshotRole[] }): { path: string; cleanup: () => void };
+}
+
+function fsWriteSpec(cwd: string = process.cwd()): SpecFileWriter {
+  return (spec) => {
+    const dir = join(cwd, ".viber", "runner-specs");
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${randomBytes(16).toString("hex")}.json`);
+    // `wx` = exclusive create (fail if it somehow exists) + owner-only perms.
+    writeFileSync(path, JSON.stringify(spec), { flag: "wx", mode: 0o600 });
+    return { path, cleanup: () => rmSync(path, { force: true }) };
+  };
+}
+
+export interface ExecDeps {
+  runTeamSpawn?: TeamSpawnRunner;
+  policy?: RunnerPolicy;
+  apiFetch?: typeof fetch;
+  inflight?: InflightStore;
+  /** Injectable spec-file writer (tests). */
+  writeSpec?: SpecFileWriter;
+  /** Injectable local-log writer (tests). Returns the log path. */
+  writeLog?: (commandId: string, recap: string) => string;
+}
+
+/** Write the full launch recap to a 0600 LOCAL log (never sent to the server —
+ *  it may hold secrets). Returns the path recorded in the generic remote report.
+ *  Best-effort: a write failure returns a placeholder, never blocks the report. */
+export function writeRunnerLog(commandId: string, recap: string, cwd: string = process.cwd()): string {
+  const dir = join(cwd, ".viber", "runner-logs");
+  const path = join(dir, `${commandId}.log`);
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, recap, { mode: 0o600 });
+  } catch {
+    return "(local log unavailable)";
+  }
+  return path;
+}
+
+async function report(
+  auth: RunnerAuthLite,
+  cmdId: string,
+  body: Record<string, unknown>,
+  fetchImpl: typeof fetch,
+): Promise<number> {
+  const resp = await fetchImpl(`${auth.base_url}/api/runners/${auth.runner_id}/commands/${cmdId}/report`, {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      Authorization: `Bearer ${auth.runner_token}`,
+      "Content-Type": "application/json",
+      ...cfAccessHeaders(),
+    },
+    body: JSON.stringify(body),
+  });
+  return resp.status;
+}
+
+/**
+ * Execute one already-claimed command. Validates against local policy, reports
+ * starting → runs the team spawn → reports the outcome (fencing-guarded). A 409
+ * on the `starting` report means the claim is no longer ours (re-claim/cancel)
+ * → cooperative abort BEFORE spawning (never launch on a lost claim). Returns
+ * the terminal status the runner recorded (or "aborted").
+ */
+export async function executeClaim(
+  auth: RunnerAuthLite,
+  cmd: ClaimedCommand,
+  deps: ExecDeps = {},
+): Promise<"succeeded" | "failed" | "aborted"> {
+  const runTeamSpawn = deps.runTeamSpawn ?? execFileTeamSpawn;
+  const fetchImpl = deps.apiFetch ?? fetch;
+  const inflight = deps.inflight ?? fsInflightStore();
+
+  // P1-4: a PRESENT-but-invalid local policy REFUSES execution (never the
+  // permissive baseline). An absent policy resolves to the baseline in loader.
+  let policy: RunnerPolicy;
+  try {
+    policy = deps.policy ?? loadRunnerPolicy();
+  } catch (err) {
+    const reason = err instanceof RunnerPolicyInvalidError ? err.message : "invalid local policy";
+    await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "failed", error: `local policy invalid: ${reason}` }, fetchImpl);
+    return "failed";
+  }
+
+  const refusal = validateAgainstPolicy(cmd, policy);
+  if (refusal) {
+    await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "failed", error: `local policy: ${refusal}` }, fetchImpl);
+    return "failed";
+  }
+
+  // Local idempotence (C4): a marker for this command_id means a PRIOR run
+  // already started it here (crashed mid-spawn, now re-claimed). Do NOT relaunch.
+  // Keep the marker unless the failed report is ACCEPTED (2xx) — else a later
+  // re-claim must still see it (P1-2).
+  if (inflight.has(cmd.id)) {
+    const s = await report(
+      auth,
+      cmd.id,
+      { fencing_token: cmd.fencing_token, status: "failed", error: "prior partial run detected on this runner — not relaunched" },
+      fetchImpl,
+    );
+    if (s >= 200 && s < 300) inflight.clear(cmd.id);
+    return "failed";
+  }
+
+  // template_name is the positional <name> in argv: positive allowlist (no
+  // leading '-', no control char) — argv-flag-injection defense.
+  if (!/^[A-Za-z0-9_.][A-Za-z0-9 _.-]{0,63}$/.test(cmd.template_name)) {
+    await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "failed", error: "unsafe template_name" }, fetchImpl);
+    return "failed";
+  }
+
+  // Report starting FIRST. Launch ONLY on a 2xx accept (P1-3): 409 = claim lost
+  // (re-claim/cancel), ANY other status (401/403/500/network) = abort with NO
+  // side effect. Never spawn on a claim we don't provably hold.
+  const startingStatus = await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "starting" }, fetchImpl);
+  if (startingStatus < 200 || startingStatus >= 300) return "aborted";
+
+  // P1-1: execute EXACTLY the server-validated snapshot. Serialize the already-
+  // validated roles to a temp spec file and invoke `team spawn --spec-file` — so
+  // vibe-master runs THOSE roles, never a name-resolved local template. Serialize
+  // the validated object verbatim (no role rebuild). Cleaned up in `finally`.
+  const spec = { name: cmd.template_name, roles: cmd.template_spec.roles };
+  const { path: specPath, cleanup } = (deps.writeSpec ?? fsWriteSpec())(spec);
+  try {
+    // Allowlisted argv (C3): fixed flags + validated values, no free string.
+    const args = ["team", "spawn", "--spec-file", specPath, "--prefix", cmd.prefix];
+    if (cmd.team_name) args.push("--team", cmd.team_name);
+    if (cmd.env) args.push("--env", cmd.env);
+
+    inflight.mark(cmd.id); // durable "started here" BEFORE launch (C4)
+    const { ok, recap } = await runTeamSpawn(args);
+
+    // Generic remote report; full recap to a 0600 LOCAL log only (no secret leak).
+    const logPath = deps.writeLog ? deps.writeLog(cmd.id, recap) : writeRunnerLog(cmd.id, recap);
+    const finalStatus = await report(
+      auth,
+      cmd.id,
+      ok
+        ? { fencing_token: cmd.fencing_token, status: "succeeded", result: { message: "team spawn completed", log: logPath } }
+        : { fencing_token: cmd.fencing_token, status: "failed", error: "team spawn failed — see local runner log" },
+      fetchImpl,
+    );
+    // Clear the inflight marker ONLY when the TERMINAL report is accepted (2xx)
+    // (P1-2): on 409 (newer holder took over) or a network/other failure, KEEP
+    // the marker so a re-claim doesn't relaunch a command that already ran here.
+    if (finalStatus >= 200 && finalStatus < 300) {
+      inflight.clear(cmd.id);
+      return ok ? "succeeded" : "failed";
+    }
+    return "aborted"; // report not accepted (409/other) — marker kept for reconcile
+  } finally {
+    cleanup(); // remove the temp spec (may hold sensitive rolePrompts)
+  }
+}
+
+/**
+ * One reconcile pass: list claimable commands, claim the first, execute it.
+ * Returns the number of commands handled (0 if none). One command per pass —
+ * the daemon's coalescing + the lease keep it serial.
+ */
+export async function reconcileOnce(auth: RunnerAuthLite, deps: ExecDeps = {}): Promise<number> {
+  const fetchImpl = deps.apiFetch ?? fetch;
+  const listResp = await fetchImpl(`${auth.base_url}/api/runners/${auth.runner_id}/commands`, {
+    method: "GET",
+    redirect: "error",
+    headers: { Authorization: `Bearer ${auth.runner_token}`, ...cfAccessHeaders() },
+  });
+  if (!listResp.ok) return 0;
+  const { commands } = (await listResp.json()) as { commands: { id: string }[] };
+  if (!commands.length) return 0;
+
+  const first = commands[0];
+  const claimResp = await fetchImpl(
+    `${auth.base_url}/api/runners/${auth.runner_id}/commands/${first.id}/claim`,
+    { method: "POST", redirect: "error", headers: { Authorization: `Bearer ${auth.runner_token}`, ...cfAccessHeaders() } },
+  );
+  if (claimResp.status !== 200) return 0; // lost the claim — another pass will retry
+  const claimed = (await claimResp.json()) as ClaimedCommand;
+  await executeClaim(auth, claimed, deps);
+  return 1;
+}

package/lib/runner_stream.ts

@@ -0,0 +1,259 @@
+/**
+ * runner_stream.ts — the resident runner daemon loop (#460 Phase 2, step-07/#472).
+ *
+ * Holds a persistent SSE control stream to the server (wake channel, ADR C6) and,
+ * CRUCIALLY, treats that stream as a WAKE hint only — never the path of progress:
+ *   - it reconcile-pulls the durable command table UNCONDITIONALLY on every
+ *     (re)connection AND on a bounded periodic timer (with jitter), so a lost
+ *     wake-poke (server restart, reconnect) only adds latency, never blocks;
+ *   - the D1 command table is the source of truth (step-08), not the SSE event.
+ *
+ * step-07 SCOPE: this is the SKELETON — it establishes the stream, heartbeat and
+ * reconcile CADENCE. The actual command claim + local execution land in step-08
+ * (durable `spawn_commands`) and step-09 (local `runTeamLaunches`); here
+ * `reconcile()` is a no-op stub that logs "0 pending".
+ */
+
+import { readFileSync, rmSync } from "node:fs";
+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";
+
+/** Remove leftover temp spec files (`.viber/runner-specs/`) from a prior crash
+ *  at daemon start — they may hold sensitive rolePrompts (Codex P1-1). The
+ *  inflight markers are NOT cleaned (they must survive a restart by design). */
+function cleanStaleSpecFiles(cwd: string = process.cwd()): void {
+  try {
+    rmSync(join(cwd, ".viber", "runner-specs"), { recursive: true, force: true });
+  } catch {
+    /* best-effort — a leftover spec is harmless if this fails */
+  }
+}
+
+interface RunnerAuth {
+  base_url: string;
+  runner_id: string;
+  runner_token: string;
+  machine_fingerprint: string;
+}
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const RECONCILE_INTERVAL_MS = 60_000; // periodic safety-net pull (C6)
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+
+export function loadRunnerAuth(cwd: string = process.cwd()): RunnerAuth {
+  const path = join(cwd, ".viber", "runner.json");
+  const raw = JSON.parse(readFileSync(path, "utf-8")) as Partial<RunnerAuth>;
+  if (!raw.base_url || !raw.runner_id || !raw.runner_token || !raw.machine_fingerprint) {
+    throw new Error(`Invalid ${path}: missing runner fields. Re-run enroll-runner.`);
+  }
+  assertSafeBaseUrl(raw.base_url);
+  return raw as RunnerAuth;
+}
+
+function jitter(ms: number): number {
+  // ±20% so a fleet of runners restarting together (post-deploy reconnect storm)
+  // doesn't hit the reconcile endpoint in lockstep. CRYPTO entropy (Codex C6): a
+  // clock-derived spread gives NO decorrelation across processes that restart at
+  // the same instant. Re-evaluated per tick (see scheduleReconcile).
+  const spread = ms * 0.2;
+  const frac = randomBytes(2).readUInt16BE(0) / 0xffff; // [0,1] uniform
+  return ms - spread + frac * (2 * spread);
+}
+
+/** base_url must be a TRUSTED Viber origin (Codex review): https + no userinfo is
+ *  not enough — it still accepts https://evil.example, which a tampered
+ *  runner.json would use to capture the bearer. Pin to the known Viber hosts /
+ *  configured VIBER_BASE_URL / dev localhost. */
+function assertSafeBaseUrl(baseUrl: string): void {
+  let u: URL;
+  try {
+    u = new URL(baseUrl);
+  } catch {
+    throw new Error(`Invalid base_url in runner.json: ${baseUrl}`);
+  }
+  if (!isTrustedViberOrigin(u.origin)) {
+    throw new Error(`Untrusted base_url origin in runner.json: ${u.origin}. Re-enroll.`);
+  }
+}
+
+// Coalescing guard: the timer, an SSE poke, and a reconnect can all fire a
+// reconcile concurrently. With step-08's atomic claim that would risk wasted
+// double-claims, so at most ONE reconcile runs at a time; a request that arrives
+// while one is in flight is dropped (the running one covers it).
+let reconciling = false;
+
+/**
+ * Reconcile-pull the durable command table. step-07 stub — step-08 replaces the
+ * body with: claim pending commands (atomic lease), hand them to step-09's local
+ * 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> {
+  if (reconciling) return;
+  reconciling = true;
+  try {
+    const handled = await reconcileOnce(auth);
+    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`);
+  } finally {
+    reconciling = false;
+  }
+}
+
+/** 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). */
+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";
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Run the runner daemon forever. Opens the control SSE, reconcile-pulls on each
+ * (re)connect + periodic timer, and heartbeats. Reconnects with exponential
+ * backoff. A 401 (revoked runner) is terminal — the operator must re-enroll.
+ */
+export async function runPersistentRunnerStream(
+  cwd: string = process.cwd(),
+): Promise<void> {
+  const auth = loadRunnerAuth(cwd);
+  cleanStaleSpecFiles(cwd); // drop crash-leftover temp specs before we start
+  process.stderr.write(`[runner] starting daemon for runner ${auth.runner_id.slice(0, 8)}…\n`);
+
+  // Background cadences, independent of the SSE connection state (C6): even if
+  // the stream is down, these keep the runner live + reconciled.
+  let stopped = false;
+  let revoked = false;
+  // Shared abort so a heartbeat-detected revocation tears down the live SSE now,
+  // instead of waiting for the next reconnect.
+  let currentAbort: AbortController | null = null;
+  const heartbeatTimer = setInterval(() => {
+    void sendHeartbeat(auth).then((r) => {
+      if (r === "revoked") {
+        revoked = true;
+        stopped = true;
+        currentAbort?.abort();
+      }
+    });
+  }, HEARTBEAT_INTERVAL_MS);
+  // Reconcile timer is a RE-JITTERED recursive setTimeout (not setInterval): each
+  // tick draws a fresh crypto jitter so a fleet never re-synchronizes (Codex C6).
+  let reconcileTimer: ReturnType<typeof setTimeout>;
+  const scheduleReconcile = (): void => {
+    reconcileTimer = setTimeout(() => {
+      void safeReconcile(auth);
+      if (!stopped) scheduleReconcile();
+    }, jitter(RECONCILE_INTERVAL_MS));
+  };
+  scheduleReconcile();
+
+  let backoff = RECONNECT_BASE_MS;
+  try {
+    while (!stopped) {
+      try {
+        // 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);
+        // 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);
+        if (terminal || revoked) {
+          process.stderr.write("[runner] runner revoked (401) — re-enroll. Stopping.\n");
+          stopped = true;
+          break;
+        }
+        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);
+      } catch (err) {
+        if (revoked) break; // abort was our own revocation teardown, 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)
+        backoff = Math.min(backoff * 2, RECONNECT_MAX_MS);
+      }
+    }
+  } finally {
+    clearInterval(heartbeatTimer);
+    clearTimeout(reconcileTimer!);
+  }
+}
+
+/**
+ * Open the SSE control stream once. Returns true if the runner is revoked (401 —
+ * 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> {
+  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)
+    signal,
+    headers: {
+      Authorization: `Bearer ${auth.runner_token}`,
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache",
+      ...cfAccessHeaders(),
+    },
+  });
+  if (resp.status === 401) return true; // revoked — terminal
+  if (!resp.ok || !resp.body) {
+    throw new Error(`control stream HTTP ${resp.status}`);
+  }
+
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) return false; // server closed — recoverable, reconnect
+    buffer += decoder.decode(value, { stream: true });
+    // Parse complete SSE frames (blank-line separated).
+    let sep: number;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard SSE frame split
+    while ((sep = buffer.indexOf("\n\n")) !== -1) {
+      const frame = buffer.slice(0, sep);
+      buffer = buffer.slice(sep + 2);
+      const eventLine = frame.split("\n").find((l) => l.startsWith("event:"));
+      const event = eventLine?.slice("event:".length).trim();
+      if (event === "stop") return false; // server asked us to unwind
+      // Any wake-poke ("spawn_pending" etc.) or reconnect → reconcile-pull. The
+      // 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);
+      }
+    }
+  }
+}

package/lib/urls.ts

@@ -10,3 +10,36 @@
 export function buildSseUrl(voiceBaseUrl: string, conversationId: string): string {
   return `${voiceBaseUrl}/api/conversations/${conversationId}/events`;
 }
+
+/**
+ * Trusted Viber origins for the runner bearer (#460 step-07, Codex review).
+ * A runner_token is a local-code-exec capability, so it must only ever be sent
+ * to a KNOWN origin — validating "https + no userinfo" alone still accepts
+ * `https://evil.example`, letting a forged enrollment URL exfiltrate the bearer.
+ * Allowlist = the canonical prod + dev hosts, any localhost (dev), and the
+ * explicitly-configured `VIBER_BASE_URL` origin (self-host / dev override).
+ */
+export function isTrustedViberOrigin(origin: string): boolean {
+  let u: URL;
+  try {
+    u = new URL(origin);
+  } catch {
+    return false;
+  }
+  if (u.username || u.password) return false;
+  const host = u.hostname;
+  const isLocalhost = host === "localhost" || host === "127.0.0.1";
+  if (u.protocol === "http:" && isLocalhost) return true;
+  if (u.protocol !== "https:") return false;
+  if (host === "viber.dgypx.dev" || host === "viber-dev.dgypx.dev") return true;
+  // Explicitly-configured base (self-host / dev override) — matched by origin.
+  const configured = process.env.VIBER_BASE_URL;
+  if (configured) {
+    try {
+      if (new URL(configured).origin === u.origin) return true;
+    } catch {
+      /* ignore a malformed env */
+    }
+  }
+  return false;
+}

package/package.json

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

@@ -97,11 +97,46 @@ import { capabilitiesText } from "./lib/capabilities.ts";
       `viber-channel — voice + text MCP channel for Claude Code\n\n` +
       `USAGE\n` +
       `  bunx viber-channel connect <claim_url>   one-shot auth flow; writes .viber/auth.json\n` +
+      `  bunx viber-channel enroll-runner <url>   enroll this machine as a spawn runner (#460)\n` +
+      `  bunx viber-channel run-runner            start the resident runner daemon (#460)\n` +
       `  bunx viber-channel                       start the MCP server (used by Claude Code)\n\n` +
       `Get <claim_url> from https://viber.dgypx.dev/projects → Create connection.\n`,
     );
     process.exit(0);
   }
+  if (sub === "enroll-runner") {
+    // #460 Phase 2: enroll THIS machine as a spawn runner. URL carries the
+    // claim_id (path) + wait_token (fragment); the owner opens it from the web.
+    const enrollUrl = process.argv[3];
+    if (!enrollUrl) {
+      process.stderr.write(
+        `[viber-channel] Missing enrollment URL.\n` +
+        `Usage: bunx viber-channel enroll-runner "https://<host>/connect/runner/<claim_id>#<wait_token>"\n` +
+        `Get the URL from the Viber web UI → Runners → Enroll this machine.\n`,
+      );
+      process.exit(1);
+    }
+    await warnIfStale();
+    try {
+      const { runRunnerEnroll } = await import("./lib/runner_enroll.ts");
+      await runRunnerEnroll(enrollUrl, process.cwd(), process.argv[4]);
+      process.exit(0);
+    } catch (err) {
+      process.stderr.write(`[viber-channel] ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exit(1);
+    }
+  }
+  if (sub === "run-runner") {
+    // #460 Phase 2: start the resident runner daemon (reads .viber/runner.json).
+    try {
+      const { runPersistentRunnerStream } = await import("./lib/runner_stream.ts");
+      await runPersistentRunnerStream(process.cwd());
+      process.exit(0);
+    } catch (err) {
+      process.stderr.write(`[viber-channel] ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exit(1);
+    }
+  }
   if (sub === "connect") {
     const claimUrl = process.argv[3];
     if (!claimUrl) {