@aloud/runner 0.3.0 → 0.3.2

package/README.md

@@ -9,7 +9,7 @@ outbound only: nothing listens on a port, and the server holds no address for th
 ```sh
 npm install -g @aloud/runner
 
-aloud login          # paste the token from usealoud.com/app/settings/runners
+aloud login          # approve this machine in your browser
 aloud start          # waits for studies and runs them here
 ```
 
@@ -19,12 +19,25 @@ The first `aloud start` downloads Chromium, about 350 MB, once.
 
 | Command | What it does |
 | --- | --- |
+| `aloud setup` | Inspect this machine and complete whatever setup remains |
 | `aloud login [--token <token>]` | Connect this machine to your workspace |
-| `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, what is not, and whether it is running |
 | `aloud allow <host>` | Let studies open this host from this machine |
 | `aloud mcp` | Connect an MCP host to the web workspace selected by its MCP access token |
 | `aloud logout` | Forget the token on this machine |
+| `aloud --version` | Print the installed runner version |
+
+## Updates
+
+Starting with 0.3.1, `aloud start` asks the connected Aloud server which official runner release
+it recommends. If a newer one is available, it installs that exact `@aloud/runner` version and
+relaunches it before claiming work. It never replaces code during an active study.
+
+If an optional update cannot be installed, the terminal says why and a still-compatible runner may
+continue. If the server requires the update, nothing starts and the command exits non-zero with the
+manual repair command. `--no-update` is available for managed environments, but it cannot make an
+incompatible runner claim work.
 
 ## MCP access
 

package/dist/cli.js

@@ -2286,7 +2286,7 @@ var init_registry = __esm({
     PinnedPromptVersions = {
       product_discovery: "1.0.0",
       study_design: "1.0.0",
-      persona_derivation: "2.1.0",
+      persona_derivation: "2.2.0",
       success_criteria: "2.0.0",
       participant_decision: "2.2.0",
       participant_reaction: "1.2.0",
@@ -2685,6 +2685,11 @@ What the site appears to be, from its public pages:
 The flow being tested: {{targetFlow}}
 The goal each participant will be given: {{goal}}
 
+The device for this study is fixed by the operator: {{deviceDescription}} ({{device}}).
+Every person will use that device for this study. Do not put anyone on another device in their role,
+jobToBeDone, background, attentionBias, derivedFrom, rationale, or any other prose. Device is not a
+persona choice and must not appear as a field in your reply.
+
 Audience segments relevant to this particular goal:
 {{relevantAudiences}}
 
@@ -2707,7 +2712,6 @@ For each person give:
 - "familiarityWithProduct", "familiarityWithDomain", "technicalConfidence", "patience", "urgency":
   each one of very_low, low, moderate, high, very_high
 - "emotionalStance": curious, neutral, sceptical, hurried, anxious, or enthusiastic
-- "device": desktop or mobile_web
 - "background": two sentences of context that would change their behaviour
 - "attentionBias": what this person notices or cares about that the others would not
 - "completionOriented": true for exactly the one completion-oriented person, false for everyone else
@@ -2724,9 +2728,9 @@ Return JSON: {"personas": [ ... ]}
 `.trim();
     personaDerivationPrompt = definePrompt(
       "persona_derivation",
-      "2.1.0",
+      "2.2.0",
       personaSource,
-      (vars) => personaSource.replace("{{productSignals}}", s(vars.productSignals)).replace("{{targetFlow}}", s(vars.targetFlow)).replace("{{goal}}", s(vars.goal)).replace("{{relevantAudiences}}", s(vars.relevantAudiences) || "The intended audience is not yet known.").replace("{{count}}", s(vars.count))
+      (vars) => personaSource.replace("{{productSignals}}", s(vars.productSignals)).replace("{{targetFlow}}", s(vars.targetFlow)).replace("{{goal}}", s(vars.goal)).replace("{{deviceDescription}}", s(vars.deviceDescription)).replace("{{device}}", s(vars.device)).replace("{{relevantAudiences}}", s(vars.relevantAudiences) || "The intended audience is not yet known.").replace("{{count}}", s(vars.count))
     );
     criteriaSource = `
 A team wants to test this goal on their website: {{goal}}
@@ -3148,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";
@@ -3380,10 +3461,6 @@ function alive(pid) {
   }
 }
 
-// src/version.ts
-var RUNNER_VERSION = "0.3.0";
-var RUNNER_VERSION_HEADER = "x-aloud-runner-version";
-
 // src/protocol/client.ts
 var LeaseLostError = class extends Error {
   constructor(message) {
@@ -7485,7 +7562,7 @@ function buildRunLimits(input) {
   const { synthesis, snapshot } = input;
   if (snapshot.cast.some((persona) => persona.completionOriented === true)) {
     limits.push(
-      "One participant was deliberately completion-oriented to exercise more of the task path. They still used only visible controls, documented friction, and could stop at a genuine blocker; their persistence is a study-design choice, not a population estimate."
+      "One participant was deliberately assigned the resilient goal-finisher role to exercise more of the task path. They were highly motivated to finish, but still used only visible controls, documented friction, and could stop at a genuine blocker; their persistence is a study-design choice, not a population estimate."
     );
   }
   if (synthesis.usableSessions.length < snapshot.cast.length) {
@@ -9378,7 +9455,6 @@ var PersonaProposalResponse = z24.object({
       patience: Level,
       urgency: Level,
       emotionalStance: z24.enum(["curious", "neutral", "sceptical", "hurried", "anxious", "enthusiastic"]),
-      device: DeviceContext,
       background: z24.string().max(1200).default(""),
       attentionBias: z24.string().max(400).default(""),
       completionOriented: z24.boolean().default(false),
@@ -9446,6 +9522,15 @@ init_src();
 init_src();
 var DAY_MS = 24 * 60 * 60 * 1e3;
 
+// ../app/src/services/runner-lease.ts
+init_src();
+
+// ../app/src/services/run-finalize.ts
+init_src();
+
+// ../app/src/services/runner-lease.ts
+var DEFAULT_LEASE_SECONDS = 20 * 60;
+
 // ../app/src/application.ts
 var PreflightFailedError = class extends Error {
   constructor(preflight2) {
@@ -9661,10 +9746,6 @@ init_src();
 // ../app/src/services/recommendations.ts
 init_src();
 
-// ../app/src/services/runner-lease.ts
-init_src();
-var DEFAULT_LEASE_SECONDS = 20 * 60;
-
 // ../app/src/services/scheduling.ts
 init_src();
 
@@ -9832,7 +9913,7 @@ function text(value) {
 function json(value) {
   return text(JSON.stringify(value, null, 2));
 }
-async function handleTool(context, name, input, execute) {
+async function handleTool(context, name, input, execute, prepare) {
   const { app, actor, workspaceId } = context;
   switch (name) {
     case "create_study": {
@@ -9965,6 +10046,21 @@ async function handleTool(context, name, input, execute) {
     }
     case "start_study": {
       const parsed = StartStudyInput.parse(input);
+      const blocked = await prepare?.(parsed.studyId, parsed.idempotencyKey);
+      if (blocked) {
+        return {
+          ...json({
+            started: false,
+            reason: "runner_not_ready",
+            code: blocked.code,
+            blockedHost: blocked.blockedHost,
+            message: blocked.message,
+            runId: blocked.existingRunId ?? null,
+            note: blocked.existingRunId ? "The existing run was not duplicated. Fix the named machine condition and call start_study again with the same runId and idempotencyKey." : "No run was created. Fix the named machine condition and call start_study again with the same runId and idempotencyKey."
+          }),
+          isError: true
+        };
+      }
       let outcome;
       try {
         outcome = await app.startRun(actor, {
@@ -10308,7 +10404,7 @@ function createMcpServer(options) {
 function backendFor(options) {
   if ("backend" in options) return options.backend;
   return {
-    callTool: (name, input) => handleTool(options.context, name, input, options.execute),
+    callTool: (name, input) => handleTool(options.context, name, input, options.execute, options.prepare),
     readResource: (parsed) => readResource(options.context, parsed)
   };
 }
@@ -10512,6 +10608,11 @@ async function main(argv = process.argv.slice(2)) {
       return allow(rest);
     case "setup":
       return setup();
+    case "version":
+    case "--version":
+    case "-v":
+      process.stdout.write(RUNNER_VERSION + "\n");
+      return 0;
     case "mcp":
       if (rest[0] === "connect") return connectMcp(rest.slice(1));
       if (rest[0] === "disconnect") return disconnectMcp();
@@ -10538,12 +10639,14 @@ function printHelp() {
       "",
       "  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)`,
       ""
@@ -10728,7 +10831,7 @@ async function setup() {
   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");
   out();
@@ -10741,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"]);
@@ -10751,11 +10867,11 @@ async function setup() {
   }
   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",
@@ -10771,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();
@@ -10795,7 +10925,7 @@ async function setup() {
     );
   }
   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.");
@@ -10844,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();
   }
@@ -10869,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,
@@ -10884,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) => {
@@ -10935,6 +11110,139 @@ async function latestVersion() {
     return null;
   }
 }
+async function serverVersionPolicy(credentials) {
+  try {
+    const client = new RunnerClient({ server: credentials.server, token: credentials.token });
+    const response = await client.request("api/runner/me", {
+      retry: false
+    });
+    return runnerVersionPolicyFrom(response.body?.runnerVersionPolicy);
+  } catch {
+    return null;
+  }
+}
+async function updateBeforeStart(credentials, argv, overrides = {}) {
+  const stdout = overrides.stdout ?? ((text2) => process.stdout.write(text2));
+  const stderr = overrides.stderr ?? ((text2) => process.stderr.write(text2));
+  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.
+Automatic updates were disabled. Remove --no-update or run npm install -g @aloud/runner@${update.target}.
+`
+    );
+    return 1;
+  }
+  stdout(`
+Updating Aloud runner ${RUNNER_VERSION} \u2192 ${update.target} before it starts.
+`);
+  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);
+  }
+  const entry2 = await (overrides.installedEntry ?? installedRunnerEntry)(update.target);
+  if (!entry2) {
+    return failedAutomaticUpdate(
+      update,
+      policy,
+      `npm completed, but the installed @aloud/runner@${update.target} could not be verified.`,
+      stderr
+    );
+  }
+  stdout(`
+Updated to ${update.target}. Starting it now.
+
+`);
+  return (overrides.relaunch ?? relaunchUpdatedRunner)(entry2, argv);
+}
+function failedAutomaticUpdate(update, policy, reason, stderr) {
+  const command = `npm install -g @aloud/runner@${update.target}`;
+  if (update.required) {
+    stderr(
+      `
+${reason}
+Runner ${RUNNER_VERSION} is below this server's minimum ${policy.minimum}, so nothing was started.
+Do not use sudo. Fix npm's global prefix, then run: ${command}
+`
+    );
+    return 1;
+  }
+  stderr(
+    `
+${reason}
+Runner ${RUNNER_VERSION} is still compatible, so it will start without updating.
+To update it later, run: ${command}
+
+`
+  );
+  return null;
+}
+async function installedRunnerEntry(target) {
+  const root = await commandOutput("npm", ["root", "--global"]);
+  if (!root) return null;
+  const directory = join6(root, "@aloud", "runner");
+  const entry2 = join6(directory, "dist", "cli.js");
+  try {
+    const manifest = JSON.parse(readFileSync(join6(directory, "package.json"), "utf8"));
+    return manifest.version === target && existsSync2(entry2) ? entry2 : null;
+  } catch {
+    return null;
+  }
+}
+async function commandOutput(command, args) {
+  return new Promise((resolve) => {
+    const child = spawn2(command, [...args], { stdio: ["ignore", "pipe", "ignore"] });
+    let output = "";
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    child.stdout?.on("data", (chunk) => output += chunk.toString("utf8"));
+    child.on("error", () => finish(null));
+    child.on("close", (code) => finish(code === 0 && output.trim() ? output.trim() : null));
+  });
+}
+async function relaunchUpdatedRunner(entry2, argv) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      resolve(code);
+    };
+    const child = spawn2(process.execPath, [entry2, "start", ...argv, "--no-update"], {
+      stdio: "inherit"
+    });
+    child.on("error", (error) => {
+      process.stderr.write(`The runner updated but could not relaunch: ${error.message}
+Run \`aloud start\` again.
+`);
+      finish(1);
+    });
+    child.on("close", (code, signal) => {
+      finish(code ?? (signal ? 130 : 1));
+    });
+  });
+}
 async function status() {
   const credentials = await loadCredentials().catch((error) => {
     process.stderr.write(error.message + "\n");
@@ -10942,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");
@@ -10959,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("-"));
@@ -10992,6 +11305,17 @@ async function start(argv) {
     process.stderr.write("Not signed in. Run `aloud login` first.\n");
     return 1;
   }
+  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.
+To restart it: kill ${existing.pid} && aloud start
+`
+    );
+    return 1;
+  }
+  const updated = await updateBeforeStart(credentials, argv);
+  if (updated !== null) return updated;
   const reporter = new TerminalReporter(process.stdout, credentials.token, !argv.includes("--quiet"));
   const checks = await preflight();
   if (!checks.chromiumInstalled) {
@@ -11091,5 +11415,6 @@ if (entry.endsWith("cli.ts") || entry.endsWith("cli.js") || entry.endsWith("/alo
 }
 export {
   CredentialsError,
-  main
+  main,
+  updateBeforeStart
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloud/runner",
-  "version": "0.3.0",
+  "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": {
@@ -17,7 +17,7 @@
     ".": "./src/index.ts",
     "./*": "./src/*.ts"
   },
-  "bin": { "aloud": "./dist/cli.js" },
+  "bin": { "aloud": "dist/cli.js" },
   "files": ["dist/cli.js", "src", "README.md"],
   "engines": { "node": ">=20" },
   "scripts": {