viber-channel 0.8.6 → 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/dm_stream.ts

@@ -27,6 +27,21 @@ export interface DmMessage {
   artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
 }
 
+/**
+ * Persistent cross-run dedup watermark for ONE DM conversation (#427). Holds the
+ * highest message id already DELIVERED to the agent in a prior `runDmStream`.
+ * The caller keeps one of these per conversation and passes it back on every
+ * (re-)join, so it SURVIVES the abort+restart cycle that `startDmStream` does on
+ * a re-pushed join. Mutated in place. Without it every re-join allocates a fresh
+ * `handledIds`, re-fetches the full history, and replays every already-delivered
+ * message (the "pong loop" the agent saw) — the run-scoped `handledIds` cannot
+ * catch that because it is empty at the start of each run.
+ */
+export interface DmWatermark {
+  /** Highest delivered message id (0 = nothing delivered yet). */
+  lastId: number;
+}
+
 /** Signature of the catch-up fetch (mirrors messages.ts `fetchMessages`). */
 export type FetchMessagesFn = (
   baseUrl: string,
@@ -66,6 +81,16 @@ export interface DmStreamOptions {
    * forward anything published while we were disconnected (#291 step-03).
    */
   fetchMessagesImpl?: FetchMessagesFn;
+  /**
+   * Cross-run dedup watermark (#427). The run-scoped `handledIds` only dedups
+   * WITHIN a single run; a re-join starts a fresh run with an empty set and the
+   * catch-up re-fetches the whole history. Supplying a caller-owned watermark
+   * (persisted across joins) suppresses ids already delivered in a prior run,
+   * while ids ABOVE the watermark still fire — so a message that arrived during
+   * detachment is preserved (#291 trigger-on-join). Advanced only after a
+   * successful delivery. Omitted → no cross-run dedup (legacy behaviour).
+   */
+  watermark?: DmWatermark;
 }
 
 /** Resolve after `ms`, or early when `signal` aborts. */
@@ -106,6 +131,20 @@ async function forwardMessage(
       ? String(msg.id)
       : undefined;
   if (idStr && handledIds.has(idStr)) return; // already forwarded (live or catch-up)
+  // Cross-run dedup (#427): the message id is `INTEGER PRIMARY KEY AUTOINCREMENT`
+  // in D1 (migration 0009), so the server assigns a STRICTLY INCREASING, never-
+  // reused id at insert — a genuinely new message always outranks everything
+  // already delivered. Hence any id at or below the watermark was already
+  // DELIVERED in a prior run and a re-join's full-history re-fetch must not replay
+  // it; ids ABOVE the watermark are new (incl. a trigger that arrived while
+  // detached) and still fire (#291). The AUTOINCREMENT guarantee is why a
+  // watermark is sufficient and a per-id Set is not needed (review: Opus/Codex).
+  // Use isSafeInteger (not isFinite) so an id beyond 2^53 — where Number() loses
+  // precision and could collide — falls through to normal handling + the in-run
+  // handledIds filter rather than silently mis-gating. The watermark only ever
+  // advances AFTER a successful delivery, so a NaN/absent id is never watermarked.
+  const numId = idStr !== undefined ? Number(idStr) : Number.NaN;
+  if (opts.watermark && Number.isSafeInteger(numId) && numId <= opts.watermark.lastId) return;
   // Content guard BEFORE consuming the id: a content-less payload must not burn
   // its id in handledIds, or a later (correctly-populated) catch-up of the same
   // id would be suppressed forever (review: Opus #4).
@@ -121,6 +160,12 @@ async function forwardMessage(
   try {
     await opts.onMessage(normalized);
     if (idStr) handledIds.add(idStr);
+    // Advance the cross-run watermark ONLY after a successful delivery (#427,
+    // Opus guard): a crash mid-handling leaves the id un-watermarked so the next
+    // catch-up retries it — at-least-once over at-most-once, same as handledIds.
+    if (opts.watermark && Number.isSafeInteger(numId) && numId > opts.watermark.lastId) {
+      opts.watermark.lastId = numId;
+    }
   } catch (handlerErr) {
     opts.log?.(
       `[dm-stream] onMessage handler error: ${handlerErr instanceof Error ? handlerErr.message : String(handlerErr)}\n`,

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.`);
+}