@aloud/runner 0.3.0 → 0.3.1

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}}
@@ -3381,8 +3385,39 @@ function alive(pid) {
 }
 
 // src/version.ts
-var RUNNER_VERSION = "0.3.0";
+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 {
@@ -7485,7 +7520,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 +9413,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 +9480,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 +9704,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 +9871,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 +10004,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 +10362,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 +10566,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 +10597,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 +10789,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();
@@ -10751,11 +10812,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",
@@ -10795,7 +10856,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.");
@@ -10935,6 +10996,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");
@@ -10992,6 +11186,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 +11296,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.1",
   "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": {

package/src/cli.ts

@@ -31,7 +31,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 +64,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 +98,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 +343,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");
@@ -369,11 +383,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",
@@ -418,7 +432,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.");
@@ -624,6 +638,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> {
@@ -689,6 +879,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/version.ts

@@ -10,7 +10,62 @@
  * 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.0";
+export const RUNNER_VERSION = "0.3.1";
 
 /** The header the server reads it from. */
 export const RUNNER_VERSION_HEADER = "x-aloud-runner-version";
+
+export interface RunnerVersionPolicy {
+  /** The oldest release that may claim new work. */
+  minimum: string;
+  /** The exact official release a start should move to when it can. */
+  recommended: string;
+}
+
+/** Strict because a server response eventually becomes part of an npm package specifier. */
+function versionParts(value: string): [number, number, number] | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
+  if (!match) return null;
+  const parts = [Number(match[1]), Number(match[2]), Number(match[3])] as [number, number, number];
+  return parts.every(Number.isSafeInteger) ? parts : null;
+}
+
+/** Numeric comparison, so 0.10.0 is newer than 0.9.9 rather than lexicographically smaller. */
+export function compareRunnerVersions(left: string, right: string): number | null {
+  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;
+}
+
+/** Parses only a coherent policy. A bad control-plane response never becomes an install command. */
+export function runnerVersionPolicyFrom(value: unknown): RunnerVersionPolicy | null {
+  if (!value || typeof value !== "object") return null;
+  const policy = value as { minimum?: unknown; recommended?: unknown };
+  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 };
+}
+
+export interface RunnerUpdate {
+  target: string;
+  /** Required means the installed release cannot claim work if updating fails. */
+  required: boolean;
+}
+
+/** What this installed runner should do with one valid server policy. Never chooses a downgrade. */
+export function runnerUpdateFor(
+  policy: RunnerVersionPolicy,
+  current: string = RUNNER_VERSION,
+): RunnerUpdate | null {
+  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 };
+}