@aloud/runner 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloud/runner",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Run Aloud usability studies in a real browser on your own machine, so a study can reach localhost and anything else behind your network.",
   "license": "ISC",
   "repository": {

package/src/cli.ts

@@ -9,6 +9,7 @@
 import { createInterface } from "node:readline/promises";
 import { spawn } from "node:child_process";
 import { startApproval, waitForApproval, type ApprovalStart } from "./protocol/approval";
+import { readRunnerPresence, waitForRunnerCheckIn } from "./protocol/presence";
 import {
   clearMcpCredentials,
   mcpCredentialsPath,
@@ -101,7 +102,7 @@ function printHelp(): void {
       "  aloud start [--once] [--quiet] [--no-update]",
       "                                  Update, then wait for studies and run them here",
       "  aloud status                    What is set up, and whether it is running",
-      "  aloud allow <host>              Let studies open this host from this machine",
+      "  aloud allow <host>              Approve a private or local host on this machine",
       "  aloud mcp                       Serve MCP to an editor, using the saved credential",
       "  aloud mcp connect               Connect an editor, approving it in your browser",
       "  aloud logout                    Forget the token on this machine",
@@ -224,7 +225,8 @@ async function connectWith(server: string, token: string): Promise<number> {
 
   const reporter = new TerminalReporter(process.stdout, token);
   process.stdout.write(`\nConnected as ${credentials.runnerName}.\n`);
-  process.stdout.write(`Allowed here: ${credentials.allowedHosts.join(", ")}\n`);
+  process.stdout.write("Public sites: automatic for the study that names them.\n");
+  process.stdout.write(`Private/local: ${credentials.allowedHosts.join(", ") || "nothing approved"}\n`);
   reporter.privacyNote();
   process.stdout.write("Run `aloud start` and leave it running.\n\n");
   return 0;
@@ -366,6 +368,21 @@ async function setup(): Promise<number> {
   );
   out(`  chromium       ${checks.chromiumInstalled ? "ready" : "downloads on first start, about 350 MB"}`);
   out(`  running        ${running ? `yes (pid ${running.pid})` : "no"}`);
+  out(
+    `  Aloud sees      ${
+      signedIn.state === "ok"
+        ? signedIn.online
+          ? `yes${signedIn.lastVersion ? ` (v${signedIn.lastVersion})` : ""}${
+              signedIn.lastSeenAt ? `, checked in ${when(signedIn.lastSeenAt)}` : ""
+            }`
+          : running
+            ? "not yet. The local process exists, but no current check-in is confirmed"
+            : "no"
+        : signedIn.state === "unreachable"
+          ? "unknown, the server did not answer"
+          : "no"
+    }`,
+  );
   out();
 
   // Each step is a command plus the lines that qualify it. Only the command gets a number, or a
@@ -373,7 +390,17 @@ async function setup(): Promise<number> {
   // into a shell.
   // A person in a terminal gets setup done, not a list of things to go and do. An agent, which has
   // no terminal, gets the list. Same command, and the difference is who can answer a prompt.
-  if (process.stdin.isTTY) return interactiveSetup({ installed, stale, latest, signedIn, running, credentials });
+  if (process.stdin.isTTY) {
+    return interactiveSetup({
+      installed,
+      stale,
+      latest,
+      signedIn,
+      running,
+      credentials,
+      chromiumInstalled: checks.chromiumInstalled,
+    });
+  }
 
   const steps: string[][] = [];
   if (!installed) {
@@ -405,6 +432,28 @@ async function setup(): Promise<number> {
     return 1;
   }
 
+  if (steps.length === 0 && running && signedIn.state === "ok" && !signedIn.online) {
+    out("The runner process exists locally, but Aloud has not confirmed a current check-in.");
+    out(`Read ${join(dirname(credentialsPath()), "runner.log")} and run \`aloud status\` again.`);
+    out("Do not report this machine ready until `Aloud sees` says yes.");
+    out();
+    return 1;
+  }
+
+  if (
+    steps.length === 0 &&
+    running &&
+    signedIn.state === "ok" &&
+    signedIn.online &&
+    signedIn.lastVersion !== RUNNER_VERSION
+  ) {
+    out(`The live process is checking in as v${signedIn.lastVersion ?? "unknown"}, not v${RUNNER_VERSION}.`);
+    out(`Restart it with:  kill ${running.pid} && aloud start`);
+    out("Do not report the update complete until `aloud status` shows the expected version.");
+    out();
+    return 1;
+  }
+
   if (steps.length === 0) {
     out("Nothing to do. This machine is set up and waiting for studies.");
     out();
@@ -458,9 +507,10 @@ async function interactiveSetup(state: {
   installed: boolean;
   stale: boolean;
   latest: string | null;
-  signedIn: { state: string };
+  signedIn: SignedInState;
   running: RunningState | null;
   credentials: Credentials | null;
+  chromiumInstalled: boolean;
 }): Promise<number> {
   const out = (line = "") => process.stdout.write(line + "\n");
   const server = state.credentials?.server ?? DEFAULT_SERVER;
@@ -503,13 +553,35 @@ async function interactiveSetup(state: {
         out("Start it when you are ready, and leave it running:  aloud start");
         return 1;
       }
-      return startDetached(out);
+      return startDetached(out, { waitForConfirmation: state.chromiumInstalled });
+    }
+
+    if (
+      state.signedIn.state === "ok" &&
+      state.signedIn.online &&
+      state.signedIn.lastVersion === RUNNER_VERSION
+    ) {
+      out("");
+      out("Set up and confirmed by Aloud. This machine is waiting for eligible studies.");
+      out("");
+      return 0;
+    }
+
+    if (state.signedIn.state === "ok" && state.signedIn.online) {
+      out("");
+      out(
+        `The live process is checking in as v${state.signedIn.lastVersion ?? "unknown"}, not v${RUNNER_VERSION}.`,
+      );
+      out(`Restart it with:  kill ${state.running.pid} && aloud start`);
+      out("");
+      return 1;
     }
 
     out("");
-    out("Set up. This machine is waiting for studies.");
+    out("The runner process exists locally, but Aloud has not confirmed a current check-in.");
+    out(`Read ${join(dirname(credentialsPath()), "runner.log")} and run \`aloud status\` again.`);
     out("");
-    return 0;
+    return 1;
   } finally {
     rl.close();
   }
@@ -540,9 +612,16 @@ async function run(command: string, args: readonly string[], out: (line?: string
  * Output goes to a file rather than nowhere, because the first start downloads Chromium and a
  * silent five minutes is indistinguishable from a hang.
  */
-async function startDetached(out: (line?: string) => void): Promise<number> {
+async function startDetached(
+  out: (line?: string) => void,
+  options: { waitForConfirmation: boolean },
+): Promise<number> {
   const log = join(dirname(credentialsPath()), "runner.log");
   await mkdir(dirname(log), { recursive: true, mode: 0o700 });
+  const credentials = await readCredentials();
+  const before = credentials
+    ? await readRunnerPresence({ server: credentials.server, token: credentials.token })
+    : null;
   const handle = openSync(log, "a");
   const child = spawn(process.execPath, [process.argv[1] ?? "", "start"], {
     detached: true,
@@ -556,9 +635,40 @@ async function startDetached(out: (line?: string) => void): Promise<number> {
   out("  Check it    aloud status");
   out(`  Stop it     kill ${child.pid}`);
   out("");
-  out("The first start downloads Chromium, about 350 MB, once. Studies will wait until it is done.");
+  if (!options.waitForConfirmation) {
+    out("The runner is preparing Chromium in the background. It is started locally, but not yet");
+    out("confirmed by Aloud. The Machines page updates automatically after its first check-in.");
+    out("");
+    return 0;
+  }
+
+  if (!credentials || before?.state !== "ok") {
+    out("Started locally, but Aloud could not establish a before-start status to confirm this launch.");
+    out(`Read ${log} and run \`aloud status\`; do not call it ready until \`Aloud sees\` says yes.`);
+    out("");
+    return 1;
+  }
+
+  out("Waiting for Aloud to confirm the first check-in…");
+  const confirmation = await waitForRunnerCheckIn({
+    server: credentials.server,
+    token: credentials.token,
+    previousLastSeenAt: before.presence.lastSeenAt,
+  });
+  if (confirmation === "confirmed") {
+    out("Confirmed by Aloud. This machine is online and waiting for eligible studies.");
+    out("");
+    return 0;
+  }
+
+  if (confirmation === "revoked") {
+    out("Aloud refused the saved connection. Run `aloud login` to approve this machine again.");
+  } else {
+    out("The process started, but Aloud did not confirm a check-in within 15 seconds.");
+    out(`Read ${log} and run \`aloud status\`; do not call it ready until \`Aloud sees\` says yes.`);
+  }
   out("");
-  return 0;
+  return 1;
 }
 
 /**
@@ -569,21 +679,30 @@ async function startDetached(out: (line?: string) => void): Promise<number> {
  * presence sent an agent off to `aloud start`, which died on its first poll with a 401 and no
  * explanation of what to do. This is the same endpoint `login` checks a token against.
  */
-async function signedInState(
-  credentials: Credentials | null,
-): Promise<{ state: "none" } | { state: "ok"; name: string } | { state: "revoked" } | { state: "unreachable"; server: string }> {
+type SignedInState =
+  | { state: "none" }
+  | {
+      state: "ok";
+      name: string;
+      online: boolean;
+      lastSeenAt: string | null;
+      lastVersion: string | null;
+    }
+  | { state: "revoked" }
+  | { state: "unreachable"; server: string };
+
+async function signedInState(credentials: Credentials | null): Promise<SignedInState> {
   if (!credentials) return { state: "none" };
-  try {
-    const response = await fetch(new URL("api/runner/me", credentials.server + "/"), {
-      headers: { authorization: `Bearer ${credentials.token}` },
-      signal: AbortSignal.timeout(5_000),
-    });
-    if (response.status === 401 || response.status === 403) return { state: "revoked" };
-    if (!response.ok) return { state: "unreachable", server: credentials.server };
-    return { state: "ok", name: credentials.runnerName };
-  } catch {
-    return { state: "unreachable", server: credentials.server };
-  }
+  const result = await readRunnerPresence({ server: credentials.server, token: credentials.token });
+  if (result.state === "revoked") return { state: "revoked" };
+  if (result.state === "unreachable") return { state: "unreachable", server: credentials.server };
+  return {
+    state: "ok",
+    name: credentials.runnerName,
+    online: result.presence.online,
+    lastSeenAt: result.presence.lastSeenAt,
+    lastVersion: result.presence.lastVersion,
+  };
 }
 
 /**
@@ -823,6 +942,7 @@ async function status(): Promise<number> {
   });
   const checks = await preflight();
   const running = await readRunning();
+  const signedIn = await signedInState(credentials);
 
   process.stdout.write("\n");
   if (!credentials) {
@@ -830,7 +950,10 @@ async function status(): Promise<number> {
   } else {
     process.stdout.write(`Signed in       ${credentials.runnerName}\n`);
     process.stdout.write(`Server          ${credentials.server}\n`);
-    process.stdout.write(`Allowed here    ${credentials.allowedHosts.join(", ") || "nothing yet"}\n`);
+    process.stdout.write("Public sites    automatic per study\n");
+    process.stdout.write(
+      `Private/local  ${credentials.allowedHosts.join(", ") || "nothing approved"}\n`,
+    );
   }
   process.stdout.write(
     `Chromium        ${checks.chromiumInstalled ? `ready (${checks.chromiumPath})` : "not installed yet"}\n`,
@@ -838,11 +961,27 @@ async function status(): Promise<number> {
   process.stdout.write(
     `Running         ${running ? `yes, since ${when(running.startedAt)} (pid ${running.pid})` : "no. Run `aloud start`."}\n`,
   );
+  process.stdout.write(
+    `Aloud sees      ${
+      signedIn.state === "ok"
+        ? signedIn.online
+          ? `yes${signedIn.lastVersion ? ` (v${signedIn.lastVersion})` : ""}${
+              signedIn.lastSeenAt ? `, checked in ${when(signedIn.lastSeenAt)}` : ""
+            }`
+          : "no current check-in"
+        : signedIn.state === "unreachable"
+          ? "unknown, server did not answer"
+          : "no"
+    }\n`,
+  );
   process.stdout.write("\n");
 
   // Zero means "a study started now would run here", which is the only question worth asking of
-  // this command. Signed in and installed but stopped is not ready, and used to exit 0 anyway.
-  return credentials && checks.chromiumInstalled && running ? 0 : 1;
+  // this command. A local PID without a server-confirmed claim poll is not ready either: that exact
+  // disagreement is what previously made setup and the Machines page contradict one another.
+  return credentials && checks.chromiumInstalled && running && signedIn.state === "ok" && signedIn.online
+    ? 0
+    : 1;
 }
 
 /* --------------------------------- allow --------------------------------- */
@@ -850,7 +989,7 @@ async function status(): Promise<number> {
 async function allow(argv: readonly string[]): Promise<number> {
   const host = argv.find((arg) => !arg.startsWith("-"));
   if (!host) {
-    process.stderr.write("Which host? For example: aloud allow staging.acme.com\n");
+    process.stderr.write("Which private or local host? For example: aloud allow internal.acme.test\n");
     return 1;
   }
 
@@ -862,8 +1001,9 @@ async function allow(argv: readonly string[]): Promise<number> {
 
   const next = normaliseHosts([...credentials.allowedHosts, host]);
   await writeCredentials({ ...credentials, allowedHosts: next });
-  process.stdout.write(`\nStudies on this machine may now open: ${next.join(", ")}\n`);
-  process.stdout.write("Nothing the server sends can change that list. Only this command can.\n\n");
+  process.stdout.write(`\nPrivate/local access approved for: ${next.join(", ")}\n`);
+  process.stdout.write("A running runner syncs this on its next poll; otherwise the next start does.\n");
+  process.stdout.write("Public sites work automatically per study. Nothing the server sends can widen this private list.\n\n");
   return 0;
 }
 
@@ -909,11 +1049,6 @@ async function start(argv: readonly string[]): Promise<number> {
   }
 
   const local = policyOf(credentials, argv);
-  if (local.allowedHosts.length === 0) {
-    process.stderr.write("This machine is not allowed to open anything. Try `aloud allow localhost`.\n");
-    return 1;
-  }
-
   const client = new RunnerClient({
     server: credentials.server,
     token: credentials.token,
@@ -935,15 +1070,44 @@ async function start(argv: readonly string[]): Promise<number> {
   // The `finally` below covers every ordinary ending. This covers the second Ctrl-C, which calls
   // `process.exit` and unwinds nothing. Synchronous, because an exit handler cannot await.
   process.on("exit", () => clearRunningSync());
+  let attemptedIdleUpdate: string | null = null;
 
   try {
     await runLoop({
       client,
       local,
+      loadLocalPolicy: async () => {
+        const current = await readCredentials();
+        return current && current.runnerId === credentials.runnerId
+          ? policyOf(current, argv)
+          : policyFrom({ allowedHosts: [], allowPrivateNetwork: false });
+      },
       ui: reporter,
       webUrl: `${credentials.server}/app`,
       once: argv.includes("--once"),
       signal: controller.signal,
+      onUpdateRequested: async (policy) => {
+        if (attemptedIdleUpdate === policy.recommended) return false;
+        attemptedIdleUpdate = policy.recommended;
+        reporter.note(`Runner ${policy.recommended} is ready. Updating now while this machine is idle.`);
+        // The replacement must be able to write its own PID before it starts polling. Clearing this
+        // process's marker is the handoff; the exit cleanup checks the PID and cannot erase the
+        // replacement's record afterwards.
+        await clearRunning();
+        const result = await updateBeforeStart(credentials, argv, {
+          versionPolicy: async () => policy,
+        });
+        if (result !== null) return true;
+
+        // An optional update can fail while this release remains compatible. Resume this exact
+        // process and make status truthful again rather than silently leaving no runner behind.
+        await writeRunning({
+          pid: process.pid,
+          startedAt: new Date().toISOString(),
+          server: credentials.server,
+        });
+        return false;
+      },
     });
     return 0;
   } catch (error) {

package/src/config/policy.ts

@@ -13,7 +13,7 @@ import { normaliseHosts } from "@aloud/core";
  * ever edits this file.
  */
 export interface LocalPolicy {
-  /** Hosts this machine will open. Written at login, changed only by `aloud allow`. */
+  /** Private/local hosts this machine will open. Public access is ephemeral and lease-scoped. */
   allowedHosts: string[];
   /**
    * Whether private and loopback addresses may be opened at all.

package/src/discovery.ts

@@ -5,6 +5,7 @@ import {
   evaluateTargetUrl,
   hostPermitted,
   intersectHosts,
+  targetNetworkAccess,
   type DeviceContext,
   type DiscoveryLink,
   type DiscoveryPage,
@@ -26,14 +27,22 @@ export async function discoverProduct(
   job: StudySetupJob,
   local: LocalPolicy,
 ): Promise<ProductDiscoveryEvidence> {
-  const effectiveHosts = intersectHosts(job.allowedHosts, local.allowedHosts);
+  const access = await targetNetworkAccess(job.url);
+  if (access.kind === "blocked") throw new Error(`Refusing product discovery: ${access.reason}`);
+  const effectiveHosts =
+    access.kind === "public"
+      ? job.allowedHosts.some((host) => hostPermitted(access.hostname, [host]))
+        ? [access.hostname]
+        : []
+      : intersectHosts(job.allowedHosts, local.allowedHosts);
   if (effectiveHosts.length === 0) {
     throw new Error(
-      `Product discovery wants ${job.allowedHosts.join(", ")}, but this machine allows ` +
+      `Private product discovery wants ${job.allowedHosts.join(", ")}, but this machine allows ` +
         `${local.allowedHosts.join(", ") || "nothing"}.`,
     );
   }
-  await assertTarget(job.url, effectiveHosts, local);
+  const allowPrivateNetwork = access.kind === "private" && local.allowPrivateNetwork;
+  await assertTarget(job.url, effectiveHosts, allowPrivateNetwork);
 
   const browser = await chromium.launch({
     args: ["--disable-dev-shm-usage"],
@@ -51,7 +60,7 @@ export async function discoverProduct(
   });
 
   try {
-    await guardRequests(context, effectiveHosts, local);
+    await guardRequests(context, effectiveHosts, allowPrivateNetwork);
     const start = canonicalUrl(job.url);
     const origin = new URL(start).origin;
     const queued = [start];
@@ -63,7 +72,7 @@ export async function discoverProduct(
       if (seen.has(url)) continue;
       seen.add(url);
       try {
-        await assertTarget(url, effectiveHosts, local);
+        await assertTarget(url, effectiveHosts, allowPrivateNetwork);
         const page = await context.newPage();
         try {
           page.setDefaultTimeout(PAGE_TIMEOUT_MS);
@@ -73,7 +82,7 @@ export async function discoverProduct(
           } catch {
             // Some products poll forever. The DOM is still useful after DOMContentLoaded.
           }
-          await assertTarget(page.url(), effectiveHosts, local);
+          await assertTarget(page.url(), effectiveHosts, allowPrivateNetwork);
           const captured = await extractPage(page);
           pages.push(captured);
 
@@ -102,10 +111,10 @@ export async function discoverProduct(
   }
 }
 
-async function assertTarget(url: string, allowedDomains: string[], local: LocalPolicy): Promise<void> {
+async function assertTarget(url: string, allowedDomains: string[], allowPrivateNetwork: boolean): Promise<void> {
   const verdict = await evaluateTargetUrl(url, {
     allowedDomains,
-    allowPrivateNetwork: local.allowPrivateNetwork,
+    allowPrivateNetwork,
   });
   if (!verdict.allowed) throw new Error(`Refusing product discovery: ${verdict.reason}`);
 }
@@ -113,7 +122,7 @@ async function assertTarget(url: string, allowedDomains: string[], local: LocalP
 async function guardRequests(
   context: BrowserContext,
   allowedDomains: string[],
-  local: LocalPolicy,
+  allowPrivateNetwork: boolean,
 ): Promise<void> {
   await context.route("**/*", async (route) => {
     const request = route.request();
@@ -135,15 +144,16 @@ async function guardRequests(
       await route.abort("blockedbyclient");
       return;
     }
-    if (request.resourceType() === "document") {
-      const verdict = await evaluateTargetUrl(url.toString(), {
-        allowedDomains,
-        allowPrivateNetwork: local.allowPrivateNetwork,
-      });
-      if (!verdict.allowed) {
-        await route.abort("blockedbyclient");
-        return;
-      }
+    // Discovery is narrower than a participant browser and keeps every request on the product
+    // domain. Resolve all of them, not only documents: a same-host private subresource or DNS
+    // rebind must not turn automatic public discovery into local-network access.
+    const verdict = await evaluateTargetUrl(url.toString(), {
+      allowedDomains,
+      allowPrivateNetwork,
+    });
+    if (!verdict.allowed) {
+      await route.abort("blockedbyclient");
+      return;
     }
     await route.continue();
   });

package/src/loop.ts

@@ -5,6 +5,7 @@ import { executeLease, type ExecuteResult, type RunReporter } from "./run/execut
 import type { StageRouting } from "./model/proxy-adapter";
 import type { LocalPolicy } from "./config/policy";
 import { discoverProduct } from "./discovery";
+import { runnerVersionPolicyFrom, type RunnerVersionPolicy } from "./version";
 
 /**
  * Claim, run, repeat.
@@ -22,17 +23,20 @@ const FAST_WINDOW_MS = 30_000;
 const IDLE_AFTER_MS = 5 * 60_000;
 
 interface ClaimResponse {
-  kind?: "study_run" | "product_discovery";
+  kind?: "study_run" | "product_discovery" | "runner_update";
   lease?: JobLease;
   run?: StudyRun;
   setupJob?: StudySetupJob;
   productId?: string;
   routing?: Partial<Record<string, StageRouting>>;
+  runnerVersionPolicy?: unknown;
 }
 
 export interface LoopDeps {
   client: RunnerClient;
   local: LocalPolicy;
+  /** Reloads durable private routes before a job, so `aloud allow` needs no process restart. */
+  loadLocalPolicy?: () => Promise<LocalPolicy>;
   ui: RunReporter & { waiting?(url: string): void };
   webUrl: string;
   /** Claim one lease, run it, and stop. For CI, and for `aloud start --once`. */
@@ -42,6 +46,8 @@ export interface LoopDeps {
   now?: () => number;
   signal?: AbortSignal;
   workers?: Parameters<typeof executeLease>[0]["workers"];
+  /** Install and relaunch an update only while no study is claimed. True stops this old loop. */
+  onUpdateRequested?: (policy: RunnerVersionPolicy) => Promise<boolean>;
 }
 
 export async function runLoop(deps: LoopDeps): Promise<ExecuteResult[]> {
@@ -56,9 +62,13 @@ export async function runLoop(deps: LoopDeps): Promise<ExecuteResult[]> {
 
   while (!deps.signal?.aborted) {
     let claim: ClaimResponse | null = null;
+    const pollLocal = deps.loadLocalPolicy ? await deps.loadLocalPolicy() : deps.local;
     try {
       const response = await deps.client.request<ClaimResponse>("api/runner/claim", {
         method: "POST",
+        // The machine owns private-network policy. Mirroring it on every outbound poll makes one
+        // `aloud allow` command sufficient and repairs a missed sync without human intervention.
+        body: { localAllowedHosts: pollLocal.allowedHosts },
         // A poll should fail fast and come back, not block for a minute holding the loop.
         retry: false,
         ...(deps.signal ? { signal: deps.signal } : {}),
@@ -78,11 +88,18 @@ export async function runLoop(deps: LoopDeps): Promise<ExecuteResult[]> {
       throw error;
     }
 
+    if (claim?.kind === "runner_update") {
+      const policy = runnerVersionPolicyFrom(claim.runnerVersionPolicy);
+      if (policy && deps.onUpdateRequested && (await deps.onUpdateRequested(policy))) break;
+      await sleep(POLL_NORMAL_MS);
+      continue;
+    }
+
     if (claim?.kind === "product_discovery" && claim.setupJob) {
       lastActivityAt = now();
       deps.ui.note(`Learning what ${new URL(claim.setupJob.url).hostname} does from its public pages.`);
       try {
-        const evidence = await discoverProduct(claim.setupJob, deps.local);
+        const evidence = await discoverProduct(claim.setupJob, pollLocal);
         await deps.client.request("api/runner/discovery", {
           method: "POST",
           body: { setupJobId: claim.setupJob.id, evidence },
@@ -132,7 +149,7 @@ export async function runLoop(deps: LoopDeps): Promise<ExecuteResult[]> {
       run: claim.run,
       productId: claim.productId ?? "",
       routing: (claim.routing ?? {}) as never,
-      local: deps.local,
+      local: pollLocal,
       spool,
       ui: deps.ui,
       ...(deps.workers ? { workers: deps.workers } : {}),

package/src/protocol/presence.ts

@@ -0,0 +1,83 @@
+import { RUNNER_VERSION, RUNNER_VERSION_HEADER } from "../version";
+
+export interface RunnerPresence {
+  online: boolean;
+  lastSeenAt: string | null;
+  lastVersion: string | null;
+}
+
+export type PresenceRead =
+  | { state: "ok"; presence: RunnerPresence }
+  | { state: "revoked" }
+  | { state: "unreachable" };
+
+/** Reads server-confirmed presence without itself updating the runner's last-seen clock. */
+export async function readRunnerPresence(input: {
+  server: string;
+  token: string;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}): Promise<PresenceRead> {
+  const fetchImpl = input.fetchImpl ?? fetch;
+  try {
+    const response = await fetchImpl(new URL("api/runner/me", input.server + "/"), {
+      headers: {
+        authorization: `Bearer ${input.token}`,
+        accept: "application/json",
+        [RUNNER_VERSION_HEADER]: RUNNER_VERSION,
+      },
+      signal: AbortSignal.timeout(input.timeoutMs ?? 5_000),
+    });
+    if (response.status === 401 || response.status === 403) return { state: "revoked" };
+    if (!response.ok) return { state: "unreachable" };
+    const body = (await response.json().catch(() => ({}))) as Partial<RunnerPresence>;
+    return {
+      state: "ok",
+      presence: {
+        online: body.online === true,
+        lastSeenAt: typeof body.lastSeenAt === "string" ? body.lastSeenAt : null,
+        lastVersion: typeof body.lastVersion === "string" ? body.lastVersion : null,
+      },
+    };
+  } catch {
+    return { state: "unreachable" };
+  }
+}
+
+/**
+ * Waits for a newly launched process to make a claim poll the control plane has actually recorded.
+ *
+ * A PID is local evidence only. Requiring `lastSeenAt` to change prevents a recent heartbeat from a
+ * previous process being mistaken for confirmation of this launch.
+ */
+export async function waitForRunnerCheckIn(input: {
+  server: string;
+  token: string;
+  previousLastSeenAt: string | null;
+  expectedVersion?: string;
+  fetchImpl?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  timeoutMs?: number;
+  pollMs?: number;
+}): Promise<"confirmed" | "revoked" | "timeout"> {
+  const now = input.now ?? Date.now;
+  const sleep = input.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const deadline = now() + (input.timeoutMs ?? 15_000);
+
+  for (;;) {
+    const result = await readRunnerPresence(input);
+    if (result.state === "revoked") return "revoked";
+    if (
+      result.state === "ok" &&
+      result.presence.online &&
+      result.presence.lastSeenAt !== null &&
+      result.presence.lastSeenAt !== input.previousLastSeenAt &&
+      result.presence.lastVersion === (input.expectedVersion ?? RUNNER_VERSION)
+    ) {
+      return "confirmed";
+    }
+    if (now() >= deadline) return "timeout";
+    await sleep(Math.min(input.pollMs ?? 750, Math.max(0, deadline - now())));
+  }
+}