@aloud/runner 0.3.0 → 0.3.2

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,
@@ -31,7 +32,14 @@ import {
 } from "./config/credentials";
 import { policyFrom, type LocalPolicy } from "./config/policy";
 import { clearRunning, readRunning, runningPath, writeRunning, type RunningState } from "./config/running";
-import { RUNNER_VERSION } from "./version";
+import {
+  RUNNER_VERSION,
+  compareRunnerVersions,
+  runnerUpdateFor,
+  runnerVersionPolicyFrom,
+  type RunnerUpdate,
+  type RunnerVersionPolicy,
+} from "./version";
 import { RunnerClient } from "./protocol/client";
 import { installChromium, preflight } from "./preflight";
 import { TerminalReporter } from "./ui/output";
@@ -57,6 +65,11 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
       return allow(rest);
     case "setup":
       return setup();
+    case "version":
+    case "--version":
+    case "-v":
+      process.stdout.write(RUNNER_VERSION + "\n");
+      return 0;
     case "mcp":
       // `aloud mcp` is the server an MCP host launches; `aloud mcp connect` is how it gets a
       // credential in the first place. Same word, because from the outside they are one feature.
@@ -86,12 +99,14 @@ function printHelp(): void {
       "",
       "  aloud setup                     What to do next, for a person or an agent",
       "  aloud login [--token <token>]   Connect this machine, approving it in your browser",
-      "  aloud start [--once] [--quiet]  Wait for studies and run them here",
+      "  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 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",
+      "  aloud --version                 Print the installed runner version",
       "",
       `Server: ${DEFAULT_SERVER}  (override with ALOUD_SERVER)`,
       "",
@@ -329,7 +344,7 @@ async function setup(): Promise<number> {
   const running = await readRunning();
   const installed = onPath("aloud");
   const latest = await latestVersion();
-  const stale = latest !== null && latest !== RUNNER_VERSION;
+  const stale = latest !== null && compareRunnerVersions(latest, RUNNER_VERSION) === 1;
   const signedIn = await signedInState(credentials);
 
   const out = (line = "") => process.stdout.write(line + "\n");
@@ -352,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
@@ -359,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) {
@@ -369,11 +409,11 @@ async function setup(): Promise<number> {
   }
   if (signedIn.state === "revoked") {
     steps.push([
-      `Create a new token at ${credentials?.server ?? DEFAULT_SERVER}/app/settings/runners`,
-      "The saved one was revoked and cannot be reused.",
+      "aloud login",
+      "The saved connection was revoked. This prints a new browser-approval link and code.",
     ]);
   }
-  if (signedIn.state === "none" || signedIn.state === "revoked") {
+  if (signedIn.state === "none") {
     steps.push([
       "aloud login",
       "Prints a link and a short code, then waits. Give both to the person; they approve in",
@@ -391,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();
@@ -418,7 +480,7 @@ async function setup(): Promise<number> {
     );
   }
   out("  - The package is `@aloud/runner`, exactly. If that name does not resolve, stop and say so.");
-  out("    Do not install a similarly named package, and do not hand the token to anything else.");
+  out("    Do not install a similarly named package.");
   out("  - There is nothing secret for you to handle. `aloud login` prints a link and a code,");
   out("    and the credential goes straight to this machine. Never ask anyone for a token.");
   out("  - `aloud start` does not exit. Run it in a background shell and do not block on it.");
@@ -444,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;
@@ -489,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();
   }
@@ -526,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,
@@ -542,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;
 }
 
 /**
@@ -555,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,
+  };
 }
 
 /**
@@ -624,6 +756,182 @@ async function latestVersion(): Promise<string | null> {
   }
 }
 
+/**
+ * The release policy belongs to the control plane this machine is connected to, not to npm.
+ *
+ * That distinction lets a self-hosted deployment deliberately lag the hosted service and lets the
+ * hosted service publish a runner before recommending it. The response is validated before any
+ * part of it reaches an install command; even a compromised control plane can select only an exact
+ * numeric release of the official scoped package.
+ */
+async function serverVersionPolicy(credentials: Credentials): Promise<RunnerVersionPolicy | null> {
+  try {
+    const client = new RunnerClient({ server: credentials.server, token: credentials.token });
+    const response = await client.request<{ runnerVersionPolicy?: unknown }>("api/runner/me", {
+      retry: false,
+    });
+    return runnerVersionPolicyFrom(response.body?.runnerVersionPolicy);
+  } catch {
+    // Startup still reaches the ordinary authenticated claim below. A revoked token, unreachable
+    // server, or old self-hosted control plane will be explained there; an update convenience must
+    // not replace the runner's established connection behavior.
+    return null;
+  }
+}
+
+/**
+ * Updates before any browser or lease exists, then starts the newly installed bundle.
+ *
+ * `null` means the current process should continue. A number means startup has been handed to the
+ * replacement process, or could not safely continue because the server requires that replacement.
+ */
+export interface StartUpdateDependencies {
+  versionPolicy(credentials: Credentials): Promise<RunnerVersionPolicy | null>;
+  npmPrefix(): Promise<{ path: string; writable: boolean | null } | null>;
+  install(target: string, write: (text: string) => void): Promise<boolean>;
+  installedEntry(target: string): Promise<string | null>;
+  relaunch(entry: string, argv: readonly string[]): Promise<number>;
+  stdout(text: string): void;
+  stderr(text: string): void;
+}
+
+export async function updateBeforeStart(
+  credentials: Credentials,
+  argv: readonly string[],
+  overrides: Partial<StartUpdateDependencies> = {},
+): Promise<number | null> {
+  const stdout = overrides.stdout ?? ((text: string) => process.stdout.write(text));
+  const stderr = overrides.stderr ?? ((text: string) => process.stderr.write(text));
+  const policy = await (overrides.versionPolicy ?? serverVersionPolicy)(credentials);
+  if (!policy) return null;
+  const update = runnerUpdateFor(policy);
+  if (!update) return null;
+
+  if (argv.includes("--no-update")) {
+    if (!update.required) return null;
+    stderr(
+      `Runner ${RUNNER_VERSION} cannot start studies on this server; ${policy.minimum} or newer is required.\n` +
+        `Automatic updates were disabled. Remove --no-update or run npm install -g @aloud/runner@${update.target}.\n`,
+    );
+    return 1;
+  }
+
+  stdout(`\nUpdating Aloud runner ${RUNNER_VERSION} → ${update.target} before it starts.\n`);
+  const prefix = await (overrides.npmPrefix ?? npmPrefix)();
+  if (prefix?.writable === false) {
+    return failedAutomaticUpdate(
+      update,
+      policy,
+      `npm's global install directory (${prefix.path}) is not writable by this user.`,
+      stderr,
+    );
+  }
+
+  const installed = overrides.install
+    ? await overrides.install(update.target, stdout)
+    : await run(
+        "npm",
+        ["install", "-g", `@aloud/runner@${update.target}`],
+        (line = "") => stdout(line + "\n"),
+      );
+  if (!installed) {
+    return failedAutomaticUpdate(update, policy, "npm did not complete the update.", stderr);
+  }
+
+  // Do not relaunch `process.argv[1]`: a runner started through npx or a project-local shim can
+  // live somewhere entirely different from the global package npm just replaced. Resolve npm's
+  // canonical global root and verify the exact installed version before handing it any work.
+  const entry = await (overrides.installedEntry ?? installedRunnerEntry)(update.target);
+  if (!entry) {
+    return failedAutomaticUpdate(
+      update,
+      policy,
+      `npm completed, but the installed @aloud/runner@${update.target} could not be verified.`,
+      stderr,
+    );
+  }
+
+  stdout(`\nUpdated to ${update.target}. Starting it now.\n\n`);
+  return (overrides.relaunch ?? relaunchUpdatedRunner)(entry, argv);
+}
+
+function failedAutomaticUpdate(
+  update: RunnerUpdate,
+  policy: RunnerVersionPolicy,
+  reason: string,
+  stderr: (text: string) => void,
+): number | null {
+  const command = `npm install -g @aloud/runner@${update.target}`;
+  if (update.required) {
+    stderr(
+      `\n${reason}\nRunner ${RUNNER_VERSION} is below this server's minimum ${policy.minimum}, so nothing was started.\n` +
+        `Do not use sudo. Fix npm's global prefix, then run: ${command}\n`,
+    );
+    return 1;
+  }
+  stderr(
+    `\n${reason}\nRunner ${RUNNER_VERSION} is still compatible, so it will start without updating.\n` +
+      `To update it later, run: ${command}\n\n`,
+  );
+  return null;
+}
+
+/** Finds the exact global bundle npm just installed, independently of how this process was run. */
+async function installedRunnerEntry(target: string): Promise<string | null> {
+  const root = await commandOutput("npm", ["root", "--global"]);
+  if (!root) return null;
+
+  const directory = join(root, "@aloud", "runner");
+  const entry = join(directory, "dist", "cli.js");
+  try {
+    const manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8")) as {
+      version?: unknown;
+    };
+    return manifest.version === target && existsSync(entry) ? entry : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Captures one short command result without involving a shell. */
+async function commandOutput(command: string, args: readonly string[]): Promise<string | null> {
+  return new Promise((resolve) => {
+    const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "ignore"] });
+    let output = "";
+    let settled = false;
+    const finish = (value: string | null) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    child.stdout?.on("data", (chunk: Buffer) => (output += chunk.toString("utf8")));
+    child.on("error", () => finish(null));
+    child.on("close", (code: number | null) => finish(code === 0 && output.trim() ? output.trim() : null));
+  });
+}
+
+/** The old bundle stays only as a transparent parent while the verified new bundle runs. */
+async function relaunchUpdatedRunner(entry: string, argv: readonly string[]): Promise<number> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (code: number) => {
+      if (settled) return;
+      settled = true;
+      resolve(code);
+    };
+    const child = spawn(process.execPath, [entry, "start", ...argv, "--no-update"], {
+      stdio: "inherit",
+    });
+    child.on("error", (error: Error) => {
+      process.stderr.write(`The runner updated but could not relaunch: ${error.message}\nRun \`aloud start\` again.\n`);
+      finish(1);
+    });
+    child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
+      finish(code ?? (signal ? 130 : 1));
+    });
+  });
+}
+
 /* --------------------------------- status --------------------------------- */
 
 async function status(): Promise<number> {
@@ -633,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) {
@@ -648,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 --------------------------------- */
@@ -689,6 +1014,21 @@ async function start(argv: readonly string[]): Promise<number> {
     return 1;
   }
 
+  // Two starts using one runner identity can claim two studies while status reports only the last
+  // pid written. Refuse before updating or polling; a restart has to stop the existing process
+  // first, which also guarantees we never replace its package while it is inside an active study.
+  const existing = await readRunning();
+  if (existing && existing.pid !== process.pid) {
+    process.stderr.write(
+      `Aloud runner is already running as pid ${existing.pid}. Stop that process before starting another.\n` +
+        `To restart it: kill ${existing.pid} && aloud start\n`,
+    );
+    return 1;
+  }
+
+  const updated = await updateBeforeStart(credentials, argv);
+  if (updated !== null) return updated;
+
   const reporter = new TerminalReporter(process.stdout, credentials.token, !argv.includes("--quiet"));
 
   // Preflight runs before the first claim, deliberately. A missing Chromium makes

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