@aloud/runner 0.3.1 → 0.3.2

package/dist/cli.js

@@ -3152,6 +3152,83 @@ async function waitForApproval(start2, deps) {
   }
 }
 
+// src/version.ts
+var RUNNER_VERSION = "0.3.2";
+var RUNNER_VERSION_HEADER = "x-aloud-runner-version";
+function versionParts(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
+  if (!match) return null;
+  const parts = [Number(match[1]), Number(match[2]), Number(match[3])];
+  return parts.every(Number.isSafeInteger) ? parts : null;
+}
+function compareRunnerVersions(left, right) {
+  const a = versionParts(left);
+  const b = versionParts(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] > b[index]) return 1;
+    if (a[index] < b[index]) return -1;
+  }
+  return 0;
+}
+function runnerVersionPolicyFrom(value) {
+  if (!value || typeof value !== "object") return null;
+  const policy = value;
+  if (typeof policy.minimum !== "string" || typeof policy.recommended !== "string") return null;
+  const order = compareRunnerVersions(policy.recommended, policy.minimum);
+  if (order === null || order < 0) return null;
+  return { minimum: policy.minimum, recommended: policy.recommended };
+}
+function runnerUpdateFor(policy, current = RUNNER_VERSION) {
+  const recommendedOrder = compareRunnerVersions(policy.recommended, current);
+  const minimumOrder = compareRunnerVersions(policy.minimum, current);
+  if (recommendedOrder === null || minimumOrder === null) return null;
+  if (recommendedOrder <= 0) return null;
+  return { target: policy.recommended, required: minimumOrder > 0 };
+}
+
+// src/protocol/presence.ts
+async function readRunnerPresence(input) {
+  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 ?? 5e3)
+    });
+    if (response.status === 401 || response.status === 403) return { state: "revoked" };
+    if (!response.ok) return { state: "unreachable" };
+    const body = await response.json().catch(() => ({}));
+    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" };
+  }
+}
+async function waitForRunnerCheckIn(input) {
+  const now = input.now ?? Date.now;
+  const sleep = input.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const deadline = now() + (input.timeoutMs ?? 15e3);
+  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())));
+  }
+}
+
 // src/config/mcp-credentials.ts
 import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
@@ -3384,41 +3461,6 @@ function alive(pid) {
   }
 }
 
-// src/version.ts
-var RUNNER_VERSION = "0.3.1";
-var RUNNER_VERSION_HEADER = "x-aloud-runner-version";
-function versionParts(value) {
-  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
-  if (!match) return null;
-  const parts = [Number(match[1]), Number(match[2]), Number(match[3])];
-  return parts.every(Number.isSafeInteger) ? parts : null;
-}
-function compareRunnerVersions(left, right) {
-  const a = versionParts(left);
-  const b = versionParts(right);
-  if (!a || !b) return null;
-  for (let index = 0; index < a.length; index += 1) {
-    if (a[index] > b[index]) return 1;
-    if (a[index] < b[index]) return -1;
-  }
-  return 0;
-}
-function runnerVersionPolicyFrom(value) {
-  if (!value || typeof value !== "object") return null;
-  const policy = value;
-  if (typeof policy.minimum !== "string" || typeof policy.recommended !== "string") return null;
-  const order = compareRunnerVersions(policy.recommended, policy.minimum);
-  if (order === null || order < 0) return null;
-  return { minimum: policy.minimum, recommended: policy.recommended };
-}
-function runnerUpdateFor(policy, current = RUNNER_VERSION) {
-  const recommendedOrder = compareRunnerVersions(policy.recommended, current);
-  const minimumOrder = compareRunnerVersions(policy.minimum, current);
-  if (recommendedOrder === null || minimumOrder === null) return null;
-  if (recommendedOrder <= 0) return null;
-  return { target: policy.recommended, required: minimumOrder > 0 };
-}
-
 // src/protocol/client.ts
 var LeaseLostError = class extends Error {
   constructor(message) {
@@ -10802,8 +10844,21 @@ async function setup() {
   );
   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();
-  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 = [];
   if (!installed) {
     steps.push(["npm install -g @aloud/runner"]);
@@ -10832,6 +10887,20 @@ async function setup() {
     out();
     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 ${join6(dirname5(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();
@@ -10905,12 +10974,28 @@ 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 ${join6(dirname5(credentialsPath()), "runner.log")} and run \`aloud status\` again.`);
     out("");
-    return 0;
+    return 1;
   } finally {
     rl.close();
   }
@@ -10930,9 +11015,11 @@ async function run(command, args, out) {
     child.on("close", (code) => resolve(code === 0));
   });
 }
-async function startDetached(out) {
+async function startDetached(out, options) {
   const log = join6(dirname5(credentialsPath()), "runner.log");
   await mkdir5(dirname5(log), { recursive: true, mode: 448 });
+  const credentials = await readCredentials();
+  const before = credentials ? await readRunnerPresence({ server: credentials.server, token: credentials.token }) : null;
   const handle = openSync(log, "a");
   const child = spawn2(process.execPath, [process.argv[1] ?? "", "start"], {
     detached: true,
@@ -10945,23 +11032,50 @@ async function startDetached(out) {
   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\u2026");
+  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;
 }
 async function signedInState(credentials) {
   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(5e3)
-    });
-    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
+  };
 }
 async function npmPrefix() {
   const path = await new Promise((resolve) => {
@@ -11136,6 +11250,7 @@ async function status() {
   });
   const checks = await preflight();
   const running = await readRunning();
+  const signedIn = await signedInState(credentials);
   process.stdout.write("\n");
   if (!credentials) {
     process.stdout.write("Signed in       no. Run `aloud login`.\n");
@@ -11153,10 +11268,14 @@ async function status() {
   );
   process.stdout.write(
     `Running         ${running ? `yes, since ${when(running.startedAt)} (pid ${running.pid})` : "no. Run `aloud start`."}
+`
+  );
+  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"}
 `
   );
   process.stdout.write("\n");
-  return credentials && checks.chromiumInstalled && running ? 0 : 1;
+  return credentials && checks.chromiumInstalled && running && signedIn.state === "ok" && signedIn.online ? 0 : 1;
 }
 async function allow(argv) {
   const host = argv.find((arg) => !arg.startsWith("-"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloud/runner",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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,
@@ -366,6 +367,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 +389,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 +431,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 +506,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 +552,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 +611,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 +634,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 +678,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 +941,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) {
@@ -838,11 +957,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 --------------------------------- */

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

package/src/version.ts

@@ -10,7 +10,7 @@
  * package.json beside it to read, and importing one into the source trips the composite build's
  * rootDir. `version.test.ts` asserts this matches, so the drift this invites cannot survive CI.
  */
-export const RUNNER_VERSION = "0.3.1";
+export const RUNNER_VERSION = "0.3.2";
 
 /** The header the server reads it from. */
 export const RUNNER_VERSION_HEADER = "x-aloud-runner-version";