viber-channel 0.8.19 → 0.8.21

package/lib/presence_record.ts

@@ -0,0 +1,358 @@
+/**
+ * presence_record.ts — the local presence record of one agent (#627 step-01).
+ *
+ * #627 moves agent presence off the per-agent network heartbeat: the machine's
+ * runner becomes the ONLY party that tells the server who is here and who left.
+ * To do that it must know, locally, which instances live on this machine. Each
+ * agent therefore drops one small JSON file per instance:
+ *
+ *   <lockDir>/presence/<backendKey>/<instance_id>.json
+ *
+ * - `lockDir` is `resolveLockDir()` — the same machine-wide directory as the
+ *   channel locks, so tests redirect it with `VIBER_LOCK_DIR` like everything else.
+ * - `backendKey` hashes the IDENTITY base URL **verbatim** (#480: never normalize
+ *   it — a trailing slash would move every record and the runner would see no one).
+ *   A runner only reads the directory of its own backend, so dev and staging
+ *   agents on the same machine never mix.
+ * - Temp files `<id>.json.<pid>.tmp` live in the same directory: a reader must
+ *   match `RECORD_FILE_RE` strictly.
+ *
+ * ⚠ This module is the ONLY place the path and the hash are computed. The runner
+ * (step-02/03) imports it; a second copy would be the drift this repo keeps paying
+ * for.
+ *
+ * Process identity. The record carries the pid of the process that holds the
+ * channel (this bun process — not claude.exe, not the launcher, whose PPID chain is
+ * broken by design, #512) and its start time, measured by `process_start.ts`. The
+ * runner measures the pid again with the SAME expression and compares with ZERO
+ * tolerance: any difference means the pid now belongs to another process. The
+ * probe is asynchronous, so `start_time_ms` is null for the first moments of an
+ * agent's life — a runner treats that as "cannot tell", never as a departure.
+ *
+ * End of life. The agent records a FACT, not a verdict: `state: "ended"` with an
+ * `ended_reason` code. Whether that end means "closed on purpose" (removed from the
+ * web) or "down" (greyed, relaunchable) is decided in ONE place, by the runner
+ * (step-03). The channel cannot tell a `/exit` from a crash of claude.exe, a window
+ * closed with the cross, or a reboot — all of them arrive as the same stdin EOF —
+ * and JP's rule is to grey rather than lose. A process that dies without running
+ * its exit path leaves an `active` record behind.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { assertHashKey } from "./hash_key.js";
+import { resolveLockDir } from "./lock_dir.js";
+import { processStartTimeAsync } from "./process_start.js";
+
+export const PRESENCE_SCHEMA_VERSION = 1;
+
+/** How often the live record is re-checked for a conversation change. */
+export const PRESENCE_REFRESH_MS = 15_000;
+
+const INSTANCE_ID_RE = /^[0-9a-f]{32}$/i;
+
+/** A record file name — and nothing else in the directory (temp files included). */
+export const RECORD_FILE_RE = /^[0-9a-f]{32}\.json$/;
+
+export type PresenceState = "active" | "ended";
+
+/**
+ * How an agent's life ended, as observed from inside it. Codes, not prose: the
+ * runner's policy (step-03) switches on them.
+ *
+ * - `revoked`        the server revoked the instance (stop event / control stop)
+ * - `lease-lost`     another holder took the conversation (#400)
+ * - `once-completed` a `--once` bridge finished its one message
+ * - `stdin-end`      claude's pipe closed: /exit, crash, window closed, reboot
+ * - `signal`         SIGINT / SIGTERM: Ctrl+C, console closed, shutdown
+ * - `shutdown`       any other bridge shutdown (token expired, refresh failed, …)
+ */
+export type PresenceEndReason =
+  | "revoked"
+  | "lease-lost"
+  | "once-completed"
+  | "stdin-end"
+  | "signal"
+  | "shutdown";
+
+const END_REASONS: ReadonlySet<string> = new Set<PresenceEndReason>([
+  "revoked",
+  "lease-lost",
+  "once-completed",
+  "stdin-end",
+  "signal",
+  "shutdown",
+]);
+
+export interface PresenceRecord {
+  schema_version: number;
+  instance_id: string;
+  pid: number;
+  /** The name the agent registered with (`{prefix}-{role}` for a runner launch);
+   *  the runner joins it to its registry entry (step-02). Null when unnamed. */
+  label: string | null;
+  /** The project the instance belongs to: a label is unique per project, not per
+   *  machine, so the runner joins on (project_id, label). Null when unknown. */
+  project_id: number | null;
+  /** The job object name the gateway imposed on this launch (`VIBER_JOB_NAME`, set
+   *  by vibe-master). Unique per ATTEMPT: the exact launch identity, which a name
+   *  is not. Null for an agent the gateway did not launch. */
+  job_name: string | null;
+  /** Epoch ms the carrier process started; null until the async probe answers. */
+  start_time_ms: number | null;
+  /** Epoch ms of the FIRST write. */
+  created_at: number;
+  /** Epoch ms of this write. */
+  written_at: number;
+  conversation_id: string | null;
+  state: PresenceState;
+  /** Set when `state` is "ended", null otherwise. */
+  ended_reason: PresenceEndReason | null;
+}
+
+/** Stable directory key of one backend: sha256 of the identity URL, verbatim. */
+export function presenceBackendKey(identityBaseUrl: string): string {
+  assertHashKey(identityBaseUrl, "presenceBackendKey(identityBaseUrl)", { allowEmpty: false });
+  return createHash("sha256").update(identityBaseUrl).digest("hex").slice(0, 16);
+}
+
+export function presenceDir(identityBaseUrl: string, lockDir: string = resolveLockDir()): string {
+  return join(lockDir, "presence", presenceBackendKey(identityBaseUrl));
+}
+
+export function isInstanceId(value: string): boolean {
+  return INSTANCE_ID_RE.test(value);
+}
+
+export function presenceRecordPath(
+  identityBaseUrl: string,
+  instanceId: string,
+  lockDir?: string,
+): string {
+  if (!isInstanceId(instanceId)) {
+    // The id becomes a file name: never let an unexpected value pick the path.
+    throw new Error(`presenceRecordPath: not an instance id: ${JSON.stringify(instanceId)}`);
+  }
+  return join(presenceDir(identityBaseUrl, lockDir), `${instanceId.toLowerCase()}.json`);
+}
+
+/** Atomic write: a reader sees the old record or the new one, never half of one. */
+export function writePresenceRecord(path: string, record: PresenceRecord): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(record), "utf8");
+  try {
+    renameSync(tmp, path);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // the tmp may already be gone; the rename error is the one that matters
+    }
+    throw err;
+  }
+}
+
+export type PresenceRead =
+  | { kind: "ok"; record: PresenceRecord }
+  | { kind: "absent" }
+  | { kind: "unreadable"; error: string };
+
+/**
+ * Read and validate one record. `unreadable` is NOT `absent`: a runner must never
+ * turn a file it could not parse into a departure (plan 627, design point 4).
+ */
+export function readPresenceRecord(path: string): PresenceRead {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { kind: "absent" };
+    return { kind: "unreadable", error: String(err) };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { kind: "unreadable", error: `invalid JSON: ${String(err)}` };
+  }
+  const record = asPresenceRecord(parsed);
+  return record === undefined
+    ? { kind: "unreadable", error: "invalid record shape" }
+    : { kind: "ok", record };
+}
+
+function isEpoch(v: unknown): boolean {
+  return typeof v === "number" && Number.isFinite(v) && v > 0;
+}
+
+function asPresenceRecord(value: unknown): PresenceRecord | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const v = value as Record<string, unknown>;
+  if (v.schema_version !== PRESENCE_SCHEMA_VERSION) return undefined;
+  const okId = typeof v.instance_id === "string" && isInstanceId(v.instance_id);
+  const okPid = typeof v.pid === "number" && Number.isInteger(v.pid) && v.pid > 0;
+  const okStart = v.start_time_ms === null || isEpoch(v.start_time_ms);
+  const okTimes = isEpoch(v.created_at) && isEpoch(v.written_at);
+  const okConv = v.conversation_id === null || typeof v.conversation_id === "string";
+  const okLabel = v.label === null || typeof v.label === "string";
+  const okJob = v.job_name === null || typeof v.job_name === "string";
+  const okProject = v.project_id === null || (typeof v.project_id === "number" && Number.isInteger(v.project_id));
+  const okState =
+    (v.state === "active" && v.ended_reason === null) ||
+    (v.state === "ended" && typeof v.ended_reason === "string" && END_REASONS.has(v.ended_reason));
+  if (!(okId && okPid && okLabel && okProject && okJob && okStart && okTimes && okConv && okState)) return undefined;
+  return v as unknown as PresenceRecord;
+}
+
+/** Back-off between start-time probes; the last value repeats. */
+export const PROBE_RETRY_DELAYS_MS: readonly number[] = [5_000, 15_000, 30_000, 60_000, 300_000];
+
+export interface PresenceRecordOptions {
+  identityBaseUrl: string;
+  instanceId: string;
+  /** The registered name; blank or absent → null. */
+  label?: string | null;
+  /** The project of the instance (auth.json `project_id`). */
+  projectId?: number | null;
+  /** The gateway-imposed job name; defaults to `VIBER_JOB_NAME` (blank → null). */
+  jobName?: string | null;
+  /** Read on every refresh: the agent may be re-bound to another conversation. */
+  getConversationId: () => string | null;
+  lockDir?: string;
+  pid?: number;
+  now?: () => number;
+  /** The carrier's start time; defaults to the async `process_start` probe. */
+  probeStartTime?: (pid: number) => Promise<number | undefined>;
+  probeRetryDelaysMs?: readonly number[];
+  sleep?: (ms: number) => Promise<void>;
+  refreshMs?: number;
+  log?: (line: string) => void;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+}
+
+export interface PresenceRecordHandle {
+  /** Record how this life ended. Synchronous: safe right before exit. */
+  markEnded: (reason: PresenceEndReason) => void;
+  /** Stop refreshing without touching the file. Idempotent. */
+  stop: () => void;
+  /** Settles once the start-time probe has been written (tests). */
+  ready: Promise<void>;
+}
+
+/**
+ * Write this agent's record now and keep it in step with its conversation.
+ *
+ * Failures are logged, never thrown: the record serves the runner, and an agent
+ * must not die because its presence file could not be written. The runner then
+ * simply does not see it — the conservative direction.
+ */
+export function startPresenceRecord(opts: PresenceRecordOptions): PresenceRecordHandle {
+  const log = opts.log ?? ((line: string) => process.stderr.write(line));
+  const now = opts.now ?? Date.now;
+  const pid = opts.pid ?? process.pid;
+  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>));
+
+  let path: string;
+  try {
+    path = presenceRecordPath(opts.identityBaseUrl, opts.instanceId, opts.lockDir);
+  } catch (err) {
+    log(`[presence] record disabled: ${String(err)}\n`);
+    return { markEnded: () => {}, stop: () => {}, ready: Promise.resolve() };
+  }
+
+  const createdAt = now();
+  const label = opts.label?.trim() ? opts.label.trim() : null;
+  const rawJob = opts.jobName !== undefined ? opts.jobName : (process.env.VIBER_JOB_NAME ?? null);
+  const jobName = rawJob?.trim() ? rawJob.trim() : null;
+  let startTime: number | null = null;
+  let lastConversation: string | null | undefined;
+  let ended = false;
+  let timer: unknown;
+
+  const build = (state: PresenceState, reason: PresenceEndReason | null): PresenceRecord => ({
+    schema_version: PRESENCE_SCHEMA_VERSION,
+    instance_id: opts.instanceId.toLowerCase(),
+    pid,
+    label,
+    project_id: opts.projectId ?? null,
+    job_name: jobName,
+    start_time_ms: startTime,
+    created_at: createdAt,
+    written_at: now(),
+    conversation_id: opts.getConversationId(),
+    state,
+    ended_reason: reason,
+  });
+
+  const write = (state: PresenceState, reason: PresenceEndReason | null, attempts = 1): void => {
+    const record = build(state, reason);
+    for (let i = 1; i <= attempts; i++) {
+      try {
+        writePresenceRecord(path, record);
+        lastConversation = record.conversation_id;
+        return;
+      } catch (err) {
+        // A rename can fail transiently on Windows (antivirus, a concurrent reader).
+        if (i === attempts) log(`[presence] write failed (${path}): ${String(err)}\n`);
+      }
+    }
+  };
+
+  const stop = (): void => {
+    if (timer !== undefined) clearTimer(timer);
+    timer = undefined;
+  };
+
+  write("active", null);
+  timer = setTimer(() => {
+    if (ended) return;
+    if (opts.getConversationId() !== lastConversation) write("active", null);
+  }, opts.refreshMs ?? PRESENCE_REFRESH_MS);
+
+  // A record without a start time is never vouched for, so its agent would stay
+  // paused (step-06) for good: the probe is RETRIED until it answers (Opus, step-03).
+  const probe = opts.probeStartTime ?? ((p: number) => processStartTimeAsync(p));
+  const retryDelays = opts.probeRetryDelaysMs ?? PROBE_RETRY_DELAYS_MS;
+  const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => {
+    const t = setTimeout(r, ms);
+    (t as { unref?: () => void }).unref?.();
+  }));
+  const ready = (async () => {
+    for (let attempt = 0; !ended; attempt++) {
+      let ms: number | undefined;
+      try {
+        ms = await probe(pid);
+      } catch (err) {
+        log(`[presence] start-time probe failed: ${String(err)}\n`);
+      }
+      if (ms !== undefined) {
+        startTime = ms;
+        if (!ended) write("active", null);
+        return;
+      }
+      if (attempt === 0) log("[presence] start time unknown — retrying; the runner will not vouch for this record until then\n");
+      await sleep(retryDelays[Math.min(attempt, retryDelays.length - 1)] as number);
+    }
+  })();
+
+  return {
+    markEnded: (reason: PresenceEndReason) => {
+      if (ended) return;
+      ended = true;
+      stop();
+      // The last write of this life: one retry is worth it.
+      write("ended", reason, 2);
+    },
+    stop,
+    ready,
+  };
+}

package/lib/process_start.ts

@@ -22,8 +22,8 @@
  * Returning `undefined` anywhere keeps the caller's conservative answer, but it is now
  * the exception rather than the rule off Windows.
  */
-import { execSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { exec, execSync } from "./hidden_proc.js";
+import { readdirSync, readFileSync } from "node:fs";
 
 /**
  * Filesystem mtimes and OS start-times do not share a clock granularity, and a real
@@ -77,22 +77,48 @@ function powershellCommand(): string {
     : `"${OS_ROOT_AT_STARTUP}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"`;
 }
 
+/**
+ * The ONE Windows probe command. #627 compares the start time an agent records for
+ * itself with the one its runner measures later, with ZERO tolerance — which is only
+ * sound because both come from this exact expression (see viber-gateway
+ * `start_time.ts` for the measurement that proved two renderings disagree).
+ */
+function win32StartTimeCommand(pid: number): string {
+  return (
+    `${powershellCommand()} -NoProfile -Command "$p = Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}'; ` +
+    `if ($p) { [int64]($p.CreationDate.ToUniversalTime() - [datetime]'1970-01-01').TotalMilliseconds }"`
+  );
+}
+
+function parseEpochLine(out: string): number | undefined {
+  const line = out.split(/\r?\n/).find((l) => l.trim() !== "");
+  if (line === undefined) return undefined;
+  const ms = Number.parseInt(line.trim(), 10);
+  return Number.isFinite(ms) && ms > 0 ? ms : undefined;
+}
+
 function startTimeWin32(pid: number): number | undefined {
   try {
-    const out = execSync(
-      `${powershellCommand()} -NoProfile -Command "$p = Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}'; ` +
-        `if ($p) { [int64]($p.CreationDate.ToUniversalTime() - [datetime]'1970-01-01').TotalMilliseconds }"`,
-      { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] },
+    return parseEpochLine(
+      execSync(win32StartTimeCommand(pid), {
+        encoding: "utf8",
+        timeout: 3000,
+        stdio: ["ignore", "pipe", "ignore"],
+      }),
     );
-    const line = out.split(/\r?\n/).find((l) => l.trim() !== "");
-    if (line === undefined) return undefined;
-    const ms = Number.parseInt(line.trim(), 10);
-    return Number.isFinite(ms) && ms > 0 ? ms : undefined;
   } catch {
     return undefined;
   }
 }
 
+function startTimeWin32Async(pid: number): Promise<number | undefined> {
+  return new Promise((resolve) => {
+    exec(win32StartTimeCommand(pid), { encoding: "utf8", timeout: 3000 }, (err, stdout) => {
+      resolve(err ? undefined : parseEpochLine(stdout));
+    });
+  });
+}
+
 /** Linux: field 22 of /proc/<pid>/stat (ticks since boot) + /proc/stat btime. */
 function startTimeLinux(pid: number): number | undefined {
   try {
@@ -154,3 +180,99 @@ export function classifyLegacyHolder(input: {
   if (startedAt > fileMtimeMs + tolerance) return "recycled";
   return "legacy-holder";
 }
+
+/**
+ * Same answer as `processStartTime`, without blocking the event loop (#627). An agent
+ * records its own start time at startup; a synchronous PowerShell probe there would
+ * stall the channel for the probe's whole duration.
+ */
+export async function processStartTimeAsync(
+  pid: number,
+  now: () => number = Date.now,
+): Promise<number | undefined> {
+  if (!Number.isInteger(pid) || pid <= 0) return undefined;
+  const raw =
+    process.platform === "win32"
+      ? await startTimeWin32Async(pid)
+      : process.platform === "linux"
+        ? startTimeLinux(pid)
+        : undefined;
+  if (raw === undefined) return undefined;
+  if (raw > now() + START_TIME_TOLERANCE_MS) return undefined;
+  return raw;
+}
+
+/**
+ * Every live process's start time, in ONE probe (#627 step-03). The runner checks all
+ * its agents' records each heartbeat; one probe per record would cost a PowerShell
+ * launch each.
+ *
+ * ⚠ The per-process expression is the SAME as `win32StartTimeCommand`'s, applied to
+ * `$_`: the runner compares the result with the record's self-measured start time with
+ * ZERO tolerance, which only holds if both sides are one expression.
+ *
+ * ⚠ Returns `undefined` — "the instrument did not see" — unless the enumeration
+ * contains THIS process with a start time (the positive control). A caller must then
+ * conclude nothing: an empty or partial table would read every agent as dead.
+ */
+export async function enumerateStartTimes(
+  selfPid: number = process.pid,
+): Promise<Map<number, number | undefined> | undefined> {
+  const table =
+    process.platform === "win32"
+      ? await enumerateWin32()
+      : process.platform === "linux"
+        ? enumerateLinux()
+        : undefined;
+  if (table === undefined) return undefined;
+  if (table.get(selfPid) === undefined) return undefined; // control failed
+  return table;
+}
+
+/**
+ * How long one enumeration may take. The runner's heartbeat waits for it, and the
+ * runner goes offline after 90 s without a beat (`ONLINE_WINDOW_SECONDS`): at 30 s
+ * a slow PowerShell could stretch the beat to 60 s. Past this bound the beat leaves
+ * WITHOUT a roster ("nothing reported") rather than late (Opus, step-03 review).
+ */
+export const ENUMERATION_TIMEOUT_MS = 10_000;
+
+function enumerateWin32(): Promise<Map<number, number | undefined> | undefined> {
+  const command =
+    `${powershellCommand()} -NoProfile -NonInteractive -Command "Get-CimInstance Win32_Process | ForEach-Object { ` +
+    `$p = $_; if ($p.CreationDate) { '' + $p.ProcessId + ' ' + [int64]($p.CreationDate.ToUniversalTime() - [datetime]'1970-01-01').TotalMilliseconds } ` +
+    `else { '' + $p.ProcessId + ' -' } }"`;
+  return new Promise((resolve) => {
+    exec(command, { encoding: "utf8", timeout: ENUMERATION_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }, (err, stdout) => {
+      if (err) return resolve(undefined);
+      resolve(parseStartTimeTable(stdout));
+    });
+  });
+}
+
+/** `<pid> <epoch-ms>` or `<pid> -` per line. Exported for its witness. */
+export function parseStartTimeTable(text: string): Map<number, number | undefined> | undefined {
+  const table = new Map<number, number | undefined>();
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.trim().match(/^(\d+) (\d+|-)$/);
+    if (!m) continue;
+    const pid = Number.parseInt(m[1] as string, 10);
+    const ms = m[2] === "-" ? undefined : Number.parseInt(m[2] as string, 10);
+    table.set(pid, ms !== undefined && Number.isFinite(ms) && ms > 0 ? ms : undefined);
+  }
+  return table.size === 0 ? undefined : table;
+}
+
+function enumerateLinux(): Map<number, number | undefined> | undefined {
+  try {
+    const table = new Map<number, number | undefined>();
+    for (const name of readdirSync("/proc")) {
+      if (!/^\d+$/.test(name)) continue;
+      const pid = Number.parseInt(name, 10);
+      table.set(pid, startTimeLinux(pid));
+    }
+    return table.size === 0 ? undefined : table;
+  } catch {
+    return undefined;
+  }
+}

package/lib/runner_enroll.ts

@@ -85,9 +85,9 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-function writeRunnerJson(
+export function writeRunnerJson(
   cwd: string,
-  data: { baseUrl: string; runnerId: string; runnerToken: string; machineFingerprint: string },
+  data: { baseUrl: string; identityBaseUrl: string; runnerId: string; runnerToken: string; machineFingerprint: string },
 ): string {
   const viberDir = join(cwd, ".viber");
   mkdirSync(viberDir, { recursive: true });
@@ -96,6 +96,10 @@ function writeRunnerJson(
   const payload = {
     schema_version: 1,
     base_url: data.baseUrl,
+    // #627: the WEB host the machine enrolled on, verbatim — the backend identity its
+    // agents hash their presence records under. `base_url` may be the announced API
+    // host (#480) and is not an identity.
+    identity_base_url: data.identityBaseUrl,
     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
@@ -184,12 +188,13 @@ export async function runRunnerEnroll(
       body: JSON.stringify({ wait_token: waitToken }),
     });
     if (resp.status === 200) {
-      const data = (await resp.json().catch(() => ({}))) as { runner_id?: string };
+      const data = (await resp.json().catch(() => ({}))) as { runner_id?: string; api_base_url?: 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,
+        baseUrl: runnerBaseUrl(baseUrl, data.api_base_url),
+        identityBaseUrl: baseUrl,
         runnerId: data.runner_id,
         runnerToken,
         machineFingerprint: fingerprint,
@@ -208,3 +213,20 @@ export async function runRunnerEnroll(
   }
   throw new Error(`Enrollment timed out after ${MAX_POLL_DURATION_MS / 60_000} minutes.`);
 }
+
+/**
+ * #632: the host the runner TALKS to. The enrollment URL is the WEB host, which sits behind
+ * Cloudflare Access and answers the runner with a 302 to a login page (measured in qa, #613).
+ * The server announces its agent API host; take it when it is a trusted Viber origin, else keep
+ * the web host (an older server announces nothing, and that is the pre-#632 behaviour).
+ */
+export function runnerBaseUrl(webBaseUrl: string, announced: string | undefined): string {
+  if (typeof announced !== "string") return webBaseUrl;
+  let origin: string;
+  try {
+    origin = new URL(announced).origin;
+  } catch {
+    return webBaseUrl;
+  }
+  return isTrustedViberOrigin(origin) ? origin : webBaseUrl;
+}