@aloud/runner 0.3.2 → 0.3.3

package/README.md

@@ -23,7 +23,7 @@ The first `aloud start` downloads Chromium, about 350 MB, once.
 | `aloud login [--token <token>]` | Connect this machine to your workspace |
 | `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 allow <host>` | Approve a private or local host on 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 |
@@ -34,6 +34,9 @@ Starting with 0.3.1, `aloud start` asks the connected Aloud server which officia
 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.
 
+Starting with 0.3.3, a runner that is already waiting does the same update automatically while it
+is idle. A customer does not have to notice a release, stop the process, or start it again.
+
 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
@@ -53,10 +56,14 @@ the web app without deleting existing study history.
 
 ## What it will open
 
-A machine starts allowed to open `localhost` only. Anything else has to be added here, with
-`aloud allow <host>`, and that list lives on this machine in `~/.aloud/credentials.json`. Nothing
-the server sends can add to it, so a study offered for a host you never allowed is refused rather
-than run.
+Public websites work automatically. The runner grants only the public domain named by the current
+lease, checks DNS again immediately before launch and on every later network request, and forces
+private-network access off for that study. The grant disappears with the lease and is never written
+to `~/.aloud/credentials.json`.
+
+Localhost, private IPs, and names that resolve inside a private network remain explicit. Add those
+once with `aloud allow <host>`; that list lives only on this machine. Nothing the server sends can
+widen it, and cloud metadata and link-local targets are always refused.
 
 The token is stored in that same file at mode 0600, and `aloud logout` deletes it. Revoking a
 machine from the web app takes effect immediately, including for a study already running.

package/dist/cli.js

@@ -866,6 +866,22 @@ async function evaluateTargetUrl(rawUrl, options = {}) {
   }
   return { allowed: true, hostname: hostname2, addresses };
 }
+async function targetNetworkAccess(rawUrl, resolver) {
+  const verdict = await evaluateTargetUrl(rawUrl, {
+    allowPrivateNetwork: false,
+    ...resolver ? { resolver } : {}
+  });
+  if (verdict.allowed) return { kind: "public", hostname: verdict.hostname };
+  let hostname2 = null;
+  try {
+    hostname2 = new URL(rawUrl).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  } catch {
+  }
+  if ((verdict.code === "loopback" || verdict.code === "private_network") && hostname2) {
+    return { kind: "private", hostname: hostname2, code: verdict.code, reason: verdict.reason };
+  }
+  return { kind: "blocked", hostname: hostname2, code: verdict.code, reason: verdict.reason };
+}
 function normaliseHosts(hosts) {
   return [...new Set(hosts.map((host) => host.toLowerCase().replace(/^\*\./, "").trim()).filter(Boolean))];
 }
@@ -3153,7 +3169,7 @@ async function waitForApproval(start2, deps) {
 }
 
 // src/version.ts
-var RUNNER_VERSION = "0.3.2";
+var RUNNER_VERSION = "0.3.3";
 var RUNNER_VERSION_HEADER = "x-aloud-runner-version";
 function versionParts(value) {
   const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
@@ -3661,7 +3677,8 @@ var TerminalReporter = class {
     this.say("");
     this.say(`  Chromium          ${input.chromium ? GREEN + "ready" + RESET : YELLOW + "not installed yet" + RESET}`);
     this.say(`  Connection        ${input.server}`);
-    this.say(`  Allowed here      ${input.allowedHosts.join(", ") || "nothing yet - run `aloud allow <host>`"}`);
+    this.say(`  Public sites      ${GREEN}automatic per study${RESET}`);
+    this.say(`  Private/local     ${input.allowedHosts.join(", ") || "nothing approved"}`);
     this.say("");
   }
   waiting(url) {
@@ -8146,6 +8163,26 @@ var VISUAL_SIGNATURE_STYLE = `
     box-shadow: none !important;
   }
 `;
+async function browserRequestRefusal(rawUrl, options, resourceType, resolver) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return `Not a valid request URL: ${rawUrl}`;
+  }
+  if (url.protocol === "data:" || url.protocol === "blob:") return null;
+  if (url.protocol !== "http:" && url.protocol !== "https:" && url.protocol !== "ws:" && url.protocol !== "wss:") {
+    return `Only HTTP(S) and WebSocket network requests are supported, got ${url.protocol}`;
+  }
+  const evaluatedUrl = url.protocol === "ws:" || url.protocol === "wss:" ? `${url.protocol === "wss:" ? "https:" : "http:"}//${url.host}${url.pathname}${url.search}` : rawUrl;
+  const restrictDocument = resourceType === "document" && options.blockOffDomainNavigation && options.allowedDomains.length > 0;
+  const verdict = await evaluateTargetUrl(evaluatedUrl, {
+    ...restrictDocument ? { allowedDomains: options.allowedDomains } : {},
+    allowPrivateNetwork: options.allowPrivateNetwork ?? false,
+    ...resolver ? { resolver } : {}
+  });
+  return verdict.allowed ? null : verdict.reason;
+}
 function digestOf(payload) {
   return createHash4("sha256").update(payload.title + " " + payload.controls + " " + payload.text + " " + payload.scrollY).digest("hex").slice(0, 24);
 }
@@ -8206,17 +8243,19 @@ var PlaywrightBrowserWorker = class {
         if (typeof window.__aloudRecordSubmit === "function") window.__aloudRecordSubmit();
       }, true);
     `);
-    if (this.options.blockOffDomainNavigation && this.options.allowedDomains.length > 0) {
-      const allowed = this.options.allowedDomains;
-      await this.context.route("**/*", async (route) => {
-        const url = route.request().url();
-        if (route.request().resourceType() === "document" && !isDomainAllowed(url, allowed)) {
-          await route.abort("blockedbyclient");
-          return;
-        }
-        await route.continue();
-      });
-    }
+    await this.context.route("**/*", async (route) => {
+      const request = route.request();
+      const refusal = await browserRequestRefusal(
+        request.url(),
+        this.options,
+        request.resourceType()
+      );
+      if (refusal) {
+        await route.abort("blockedbyclient");
+        return;
+      }
+      await route.continue();
+    });
     await this.page.goto(startUrl, { waitUntil: "domcontentloaded" });
     await this.settle();
     const capture = await this.capture();
@@ -8831,26 +8870,37 @@ var SnapshotRefused = class extends Error {
 async function sanitiseSnapshot(snapshot, lease, local, nowIso, resolver) {
   const granted = normaliseHosts(lease.allowedHosts);
   const permitted = normaliseHosts(local.allowedHosts);
-  const effective = intersectHosts(granted, permitted);
-  if (effective.length === 0) {
-    throw new SnapshotRefused(
-      `This study wants ${granted.join(", ") || "nothing"}, and this machine allows ${permitted.join(", ") || "nothing"}. Nothing in common, so nothing will be opened. Add a host with \`aloud allow <host>\` if that is wrong.`
-    );
-  }
   const startUrl = snapshot.study?.startUrl;
   if (typeof startUrl !== "string" || startUrl.length === 0) {
     throw new SnapshotRefused("This study has no start URL.");
   }
-  const verdict = leasePermits({ ...lease, allowedHosts: effective }, startUrl, nowIso);
+  const verdict = leasePermits({ ...lease, allowedHosts: granted }, startUrl, nowIso);
   if (!verdict.allowed) throw new SnapshotRefused(verdict.reason);
+  const access = await targetNetworkAccess(startUrl, resolver);
+  if (access.kind === "blocked") throw new SnapshotRefused(access.reason);
+  let effective;
+  let allowPrivateNetwork;
+  if (access.kind === "public") {
+    effective = granted.some((entry2) => hostPermitted(access.hostname, [entry2])) ? [access.hostname] : [];
+    allowPrivateNetwork = false;
+  } else {
+    effective = intersectHosts(granted, permitted);
+    allowPrivateNetwork = local.allowPrivateNetwork;
+  }
+  if (effective.length === 0) {
+    throw new SnapshotRefused(
+      `This private or local study wants ${granted.join(", ") || "nothing"}, and this machine allows ${permitted.join(", ") || "nothing"}. Nothing in common, so nothing will be opened. Add the private host with \`aloud allow <host>\` if that is intentional.`
+    );
+  }
   const target = await evaluateTargetUrl(startUrl, {
     allowedDomains: effective,
-    allowPrivateNetwork: local.allowPrivateNetwork,
+    allowPrivateNetwork,
     ...resolver ? { resolver } : {}
   });
   if (!target.allowed) throw new SnapshotRefused(target.reason);
   return {
     allowedHosts: effective,
+    allowPrivateNetwork,
     snapshot: {
       ...snapshot,
       environment: {
@@ -8965,7 +9015,7 @@ async function executeLease(deps) {
   const workers = new GuardedWorkerFactory(
     deps.workers ?? new PlaywrightWorkerFactory(),
     effective.allowedHosts,
-    deps.local
+    { ...deps.local, allowPrivateNetwork: effective.allowPrivateNetwork }
   );
   coordinator = new RunCoordinator(
     {
@@ -9135,13 +9185,16 @@ var MAX_PAGES = 6;
 var MAX_LINKS_PER_PAGE = 200;
 var PAGE_TIMEOUT_MS = 15e3;
 async function discoverProduct(job, local) {
-  const effectiveHosts = intersectHosts(job.allowedHosts, local.allowedHosts);
+  const access = await targetNetworkAccess(job.url);
+  if (access.kind === "blocked") throw new Error(`Refusing product discovery: ${access.reason}`);
+  const effectiveHosts = access.kind === "public" ? job.allowedHosts.some((host) => hostPermitted(access.hostname, [host])) ? [access.hostname] : [] : intersectHosts(job.allowedHosts, local.allowedHosts);
   if (effectiveHosts.length === 0) {
     throw new Error(
-      `Product discovery wants ${job.allowedHosts.join(", ")}, but this machine allows ${local.allowedHosts.join(", ") || "nothing"}.`
+      `Private product discovery wants ${job.allowedHosts.join(", ")}, but this machine allows ${local.allowedHosts.join(", ") || "nothing"}.`
     );
   }
-  await assertTarget(job.url, effectiveHosts, local);
+  const allowPrivateNetwork = access.kind === "private" && local.allowPrivateNetwork;
+  await assertTarget(job.url, effectiveHosts, allowPrivateNetwork);
   const browser = await chromium2.launch({
     args: ["--disable-dev-shm-usage"],
     handleSIGINT: false,
@@ -9157,7 +9210,7 @@ async function discoverProduct(job, local) {
     serviceWorkers: "block"
   });
   try {
-    await guardRequests(context, effectiveHosts, local);
+    await guardRequests(context, effectiveHosts, allowPrivateNetwork);
     const start2 = canonicalUrl(job.url);
     const origin = new URL(start2).origin;
     const queued = [start2];
@@ -9168,7 +9221,7 @@ async function discoverProduct(job, local) {
       if (seen.has(url)) continue;
       seen.add(url);
       try {
-        await assertTarget(url, effectiveHosts, local);
+        await assertTarget(url, effectiveHosts, allowPrivateNetwork);
         const page = await context.newPage();
         try {
           page.setDefaultTimeout(PAGE_TIMEOUT_MS);
@@ -9177,7 +9230,7 @@ async function discoverProduct(job, local) {
             await page.waitForLoadState("networkidle", { timeout: 1500 });
           } catch {
           }
-          await assertTarget(page.url(), effectiveHosts, local);
+          await assertTarget(page.url(), effectiveHosts, allowPrivateNetwork);
           const captured = await extractPage(page);
           pages.push(captured);
           const candidates = prioritiseDiscoveryLinks(captured.links, origin).map((link) => canonicalUrl(link.href)).filter((href) => !seen.has(href) && !queued.includes(href));
@@ -9198,14 +9251,14 @@ async function discoverProduct(job, local) {
     await browser.close();
   }
 }
-async function assertTarget(url, allowedDomains, local) {
+async function assertTarget(url, allowedDomains, allowPrivateNetwork) {
   const verdict = await evaluateTargetUrl(url, {
     allowedDomains,
-    allowPrivateNetwork: local.allowPrivateNetwork
+    allowPrivateNetwork
   });
   if (!verdict.allowed) throw new Error(`Refusing product discovery: ${verdict.reason}`);
 }
-async function guardRequests(context, allowedDomains, local) {
+async function guardRequests(context, allowedDomains, allowPrivateNetwork) {
   await context.route("**/*", async (route) => {
     const request = route.request();
     let url;
@@ -9223,15 +9276,13 @@ async function guardRequests(context, allowedDomains, local) {
       await route.abort("blockedbyclient");
       return;
     }
-    if (request.resourceType() === "document") {
-      const verdict = await evaluateTargetUrl(url.toString(), {
-        allowedDomains,
-        allowPrivateNetwork: local.allowPrivateNetwork
-      });
-      if (!verdict.allowed) {
-        await route.abort("blockedbyclient");
-        return;
-      }
+    const verdict = await evaluateTargetUrl(url.toString(), {
+      allowedDomains,
+      allowPrivateNetwork
+    });
+    if (!verdict.allowed) {
+      await route.abort("blockedbyclient");
+      return;
     }
     await route.continue();
   });
@@ -9320,9 +9371,13 @@ async function runLoop(deps) {
   deps.ui.waiting?.(deps.webUrl);
   while (!deps.signal?.aborted) {
     let claim = null;
+    const pollLocal = deps.loadLocalPolicy ? await deps.loadLocalPolicy() : deps.local;
     try {
       const response = await deps.client.request("api/runner/claim", {
         method: "POST",
+        // The machine owns private-network policy. Mirroring it on every outbound poll makes one
+        // `aloud allow` command sufficient and repairs a missed sync without human intervention.
+        body: { localAllowedHosts: pollLocal.allowedHosts },
         // A poll should fail fast and come back, not block for a minute holding the loop.
         retry: false,
         ...deps.signal ? { signal: deps.signal } : {}
@@ -9340,11 +9395,17 @@ async function runLoop(deps) {
       }
       throw error;
     }
+    if (claim?.kind === "runner_update") {
+      const policy = runnerVersionPolicyFrom(claim.runnerVersionPolicy);
+      if (policy && deps.onUpdateRequested && await deps.onUpdateRequested(policy)) break;
+      await sleep(POLL_NORMAL_MS);
+      continue;
+    }
     if (claim?.kind === "product_discovery" && claim.setupJob) {
       lastActivityAt = now();
       deps.ui.note(`Learning what ${new URL(claim.setupJob.url).hostname} does from its public pages.`);
       try {
-        const evidence = await discoverProduct(claim.setupJob, deps.local);
+        const evidence = await discoverProduct(claim.setupJob, pollLocal);
         await deps.client.request("api/runner/discovery", {
           method: "POST",
           body: { setupJobId: claim.setupJob.id, evidence },
@@ -9387,7 +9448,7 @@ async function runLoop(deps) {
       run: claim.run,
       productId: claim.productId ?? "",
       routing: claim.routing ?? {},
-      local: deps.local,
+      local: pollLocal,
       spool,
       ui: deps.ui,
       ...deps.workers ? { workers: deps.workers } : {},
@@ -10642,7 +10703,7 @@ function printHelp() {
       "  aloud start [--once] [--quiet] [--no-update]",
       "                                  Update, then wait for studies and run them here",
       "  aloud status                    What is set up, and whether it is running",
-      "  aloud allow <host>              Let studies open this host from this machine",
+      "  aloud allow <host>              Approve a private or local host on this machine",
       "  aloud mcp                       Serve MCP to an editor, using the saved credential",
       "  aloud mcp connect               Connect an editor, approving it in your browser",
       "  aloud logout                    Forget the token on this machine",
@@ -10742,7 +10803,8 @@ async function connectWith(server, token) {
   process.stdout.write(`
 Connected as ${credentials.runnerName}.
 `);
-  process.stdout.write(`Allowed here: ${credentials.allowedHosts.join(", ")}
+  process.stdout.write("Public sites: automatic for the study that names them.\n");
+  process.stdout.write(`Private/local: ${credentials.allowedHosts.join(", ") || "nothing approved"}
 `);
   reporter.privacyNote();
   process.stdout.write("Run `aloud start` and leave it running.\n\n");
@@ -11259,8 +11321,11 @@ async function status() {
 `);
     process.stdout.write(`Server          ${credentials.server}
 `);
-    process.stdout.write(`Allowed here    ${credentials.allowedHosts.join(", ") || "nothing yet"}
-`);
+    process.stdout.write("Public sites    automatic per study\n");
+    process.stdout.write(
+      `Private/local  ${credentials.allowedHosts.join(", ") || "nothing approved"}
+`
+    );
   }
   process.stdout.write(
     `Chromium        ${checks.chromiumInstalled ? `ready (${checks.chromiumPath})` : "not installed yet"}
@@ -11280,7 +11345,7 @@ async function status() {
 async function allow(argv) {
   const host = argv.find((arg) => !arg.startsWith("-"));
   if (!host) {
-    process.stderr.write("Which host? For example: aloud allow staging.acme.com\n");
+    process.stderr.write("Which private or local host? For example: aloud allow internal.acme.test\n");
     return 1;
   }
   const credentials = await readCredentials();
@@ -11291,9 +11356,10 @@ async function allow(argv) {
   const next = normaliseHosts([...credentials.allowedHosts, host]);
   await writeCredentials({ ...credentials, allowedHosts: next });
   process.stdout.write(`
-Studies on this machine may now open: ${next.join(", ")}
+Private/local access approved for: ${next.join(", ")}
 `);
-  process.stdout.write("Nothing the server sends can change that list. Only this command can.\n\n");
+  process.stdout.write("A running runner syncs this on its next poll; otherwise the next start does.\n");
+  process.stdout.write("Public sites work automatically per study. Nothing the server sends can widen this private list.\n\n");
   return 0;
 }
 async function start(argv) {
@@ -11326,10 +11392,6 @@ To restart it: kill ${existing.pid} && aloud start
     }
   }
   const local = policyOf(credentials, argv);
-  if (local.allowedHosts.length === 0) {
-    process.stderr.write("This machine is not allowed to open anything. Try `aloud allow localhost`.\n");
-    return 1;
-  }
   const client = new RunnerClient({
     server: credentials.server,
     token: credentials.token,
@@ -11346,14 +11408,35 @@ To restart it: kill ${existing.pid} && aloud start
   installSignalHandlers(controller, reporter);
   await writeRunning({ pid: process.pid, startedAt: (/* @__PURE__ */ new Date()).toISOString(), server: credentials.server });
   process.on("exit", () => clearRunningSync());
+  let attemptedIdleUpdate = null;
   try {
     await runLoop({
       client,
       local,
+      loadLocalPolicy: async () => {
+        const current = await readCredentials();
+        return current && current.runnerId === credentials.runnerId ? policyOf(current, argv) : policyFrom({ allowedHosts: [], allowPrivateNetwork: false });
+      },
       ui: reporter,
       webUrl: `${credentials.server}/app`,
       once: argv.includes("--once"),
-      signal: controller.signal
+      signal: controller.signal,
+      onUpdateRequested: async (policy) => {
+        if (attemptedIdleUpdate === policy.recommended) return false;
+        attemptedIdleUpdate = policy.recommended;
+        reporter.note(`Runner ${policy.recommended} is ready. Updating now while this machine is idle.`);
+        await clearRunning();
+        const result = await updateBeforeStart(credentials, argv, {
+          versionPolicy: async () => policy
+        });
+        if (result !== null) return true;
+        await writeRunning({
+          pid: process.pid,
+          startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          server: credentials.server
+        });
+        return false;
+      }
     });
     return 0;
   } catch (error) {

package/package.json

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

package/src/cli.ts

@@ -102,7 +102,7 @@ function printHelp(): void {
       "  aloud start [--once] [--quiet] [--no-update]",
       "                                  Update, then wait for studies and run them here",
       "  aloud status                    What is set up, and whether it is running",
-      "  aloud allow <host>              Let studies open this host from this machine",
+      "  aloud allow <host>              Approve a private or local host on this machine",
       "  aloud mcp                       Serve MCP to an editor, using the saved credential",
       "  aloud mcp connect               Connect an editor, approving it in your browser",
       "  aloud logout                    Forget the token on this machine",
@@ -225,7 +225,8 @@ async function connectWith(server: string, token: string): Promise<number> {
 
   const reporter = new TerminalReporter(process.stdout, token);
   process.stdout.write(`\nConnected as ${credentials.runnerName}.\n`);
-  process.stdout.write(`Allowed here: ${credentials.allowedHosts.join(", ")}\n`);
+  process.stdout.write("Public sites: automatic for the study that names them.\n");
+  process.stdout.write(`Private/local: ${credentials.allowedHosts.join(", ") || "nothing approved"}\n`);
   reporter.privacyNote();
   process.stdout.write("Run `aloud start` and leave it running.\n\n");
   return 0;
@@ -949,7 +950,10 @@ async function status(): Promise<number> {
   } else {
     process.stdout.write(`Signed in       ${credentials.runnerName}\n`);
     process.stdout.write(`Server          ${credentials.server}\n`);
-    process.stdout.write(`Allowed here    ${credentials.allowedHosts.join(", ") || "nothing yet"}\n`);
+    process.stdout.write("Public sites    automatic per study\n");
+    process.stdout.write(
+      `Private/local  ${credentials.allowedHosts.join(", ") || "nothing approved"}\n`,
+    );
   }
   process.stdout.write(
     `Chromium        ${checks.chromiumInstalled ? `ready (${checks.chromiumPath})` : "not installed yet"}\n`,
@@ -985,7 +989,7 @@ async function status(): Promise<number> {
 async function allow(argv: readonly string[]): Promise<number> {
   const host = argv.find((arg) => !arg.startsWith("-"));
   if (!host) {
-    process.stderr.write("Which host? For example: aloud allow staging.acme.com\n");
+    process.stderr.write("Which private or local host? For example: aloud allow internal.acme.test\n");
     return 1;
   }
 
@@ -997,8 +1001,9 @@ async function allow(argv: readonly string[]): Promise<number> {
 
   const next = normaliseHosts([...credentials.allowedHosts, host]);
   await writeCredentials({ ...credentials, allowedHosts: next });
-  process.stdout.write(`\nStudies on this machine may now open: ${next.join(", ")}\n`);
-  process.stdout.write("Nothing the server sends can change that list. Only this command can.\n\n");
+  process.stdout.write(`\nPrivate/local access approved for: ${next.join(", ")}\n`);
+  process.stdout.write("A running runner syncs this on its next poll; otherwise the next start does.\n");
+  process.stdout.write("Public sites work automatically per study. Nothing the server sends can widen this private list.\n\n");
   return 0;
 }
 
@@ -1044,11 +1049,6 @@ async function start(argv: readonly string[]): Promise<number> {
   }
 
   const local = policyOf(credentials, argv);
-  if (local.allowedHosts.length === 0) {
-    process.stderr.write("This machine is not allowed to open anything. Try `aloud allow localhost`.\n");
-    return 1;
-  }
-
   const client = new RunnerClient({
     server: credentials.server,
     token: credentials.token,
@@ -1070,15 +1070,44 @@ async function start(argv: readonly string[]): Promise<number> {
   // The `finally` below covers every ordinary ending. This covers the second Ctrl-C, which calls
   // `process.exit` and unwinds nothing. Synchronous, because an exit handler cannot await.
   process.on("exit", () => clearRunningSync());
+  let attemptedIdleUpdate: string | null = null;
 
   try {
     await runLoop({
       client,
       local,
+      loadLocalPolicy: async () => {
+        const current = await readCredentials();
+        return current && current.runnerId === credentials.runnerId
+          ? policyOf(current, argv)
+          : policyFrom({ allowedHosts: [], allowPrivateNetwork: false });
+      },
       ui: reporter,
       webUrl: `${credentials.server}/app`,
       once: argv.includes("--once"),
       signal: controller.signal,
+      onUpdateRequested: async (policy) => {
+        if (attemptedIdleUpdate === policy.recommended) return false;
+        attemptedIdleUpdate = policy.recommended;
+        reporter.note(`Runner ${policy.recommended} is ready. Updating now while this machine is idle.`);
+        // The replacement must be able to write its own PID before it starts polling. Clearing this
+        // process's marker is the handoff; the exit cleanup checks the PID and cannot erase the
+        // replacement's record afterwards.
+        await clearRunning();
+        const result = await updateBeforeStart(credentials, argv, {
+          versionPolicy: async () => policy,
+        });
+        if (result !== null) return true;
+
+        // An optional update can fail while this release remains compatible. Resume this exact
+        // process and make status truthful again rather than silently leaving no runner behind.
+        await writeRunning({
+          pid: process.pid,
+          startedAt: new Date().toISOString(),
+          server: credentials.server,
+        });
+        return false;
+      },
     });
     return 0;
   } catch (error) {

package/src/config/policy.ts

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

package/src/discovery.ts

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

package/src/loop.ts

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

package/src/run/execute.ts

@@ -145,7 +145,7 @@ export async function executeLease(deps: ExecuteDeps): Promise<ExecuteResult> {
   const workers = new GuardedWorkerFactory(
     deps.workers ?? new PlaywrightWorkerFactory(),
     effective.allowedHosts,
-    deps.local,
+    { ...deps.local, allowPrivateNetwork: effective.allowPrivateNetwork },
   );
 
   coordinator = new RunCoordinator(

package/src/run/sanitise.ts

@@ -1,8 +1,10 @@
 import {
   evaluateTargetUrl,
+  hostPermitted,
   intersectHosts,
   leasePermits,
   normaliseHosts,
+  targetNetworkAccess,
   type JobLease,
   type StudySnapshot,
 } from "@aloud/core";
@@ -31,6 +33,8 @@ export class SnapshotRefused extends Error {
 export interface SanitisedSnapshot {
   snapshot: StudySnapshot;
   allowedHosts: string[];
+  /** False for an automatic public grant, which keeps DNS rebinding out of the local network. */
+  allowPrivateNetwork: boolean;
 }
 
 export async function sanitiseSnapshot(
@@ -44,38 +48,56 @@ export async function sanitiseSnapshot(
   const granted = normaliseHosts(lease.allowedHosts);
   const permitted = normaliseHosts(local.allowedHosts);
 
-  // The server already did this intersection. Doing it again here is the point: a server that got
-  // it wrong, or lied about it, changes nothing on this machine.
-  const effective = intersectHosts(granted, permitted);
-  if (effective.length === 0) {
-    throw new SnapshotRefused(
-      `This study wants ${granted.join(", ") || "nothing"}, and this machine allows ` +
-        `${permitted.join(", ") || "nothing"}. Nothing in common, so nothing will be opened. ` +
-        "Add a host with `aloud allow <host>` if that is wrong.",
-    );
-  }
-
   const startUrl = snapshot.study?.startUrl;
   if (typeof startUrl !== "string" || startUrl.length === 0) {
     throw new SnapshotRefused("This study has no start URL.");
   }
 
-  // Checked against the *effective* list, not the one the lease claimed.
-  const verdict = leasePermits({ ...lease, allowedHosts: effective }, startUrl, nowIso);
+  // The lease is still the outer boundary. Automatic access never invents a host the lease did not
+  // name; it only decides whether that lease host needs a durable local permission as well.
+  const verdict = leasePermits({ ...lease, allowedHosts: granted }, startUrl, nowIso);
   if (!verdict.allowed) throw new SnapshotRefused(verdict.reason);
 
+  const access = await targetNetworkAccess(startUrl, resolver);
+  if (access.kind === "blocked") throw new SnapshotRefused(access.reason);
+
+  let effective: string[];
+  let allowPrivateNetwork: boolean;
+  if (access.kind === "public") {
+    // A covering lease entry proves the start host was in scope, but the browser receives only the
+    // exact start hostname. A hostile lease cannot smuggle an unrelated domain—or a broad parent
+    // that grants sibling subdomains—into the automatic browser policy.
+    effective = granted.some((entry) => hostPermitted(access.hostname, [entry]))
+      ? [access.hostname]
+      : [];
+    allowPrivateNetwork = false;
+  } else {
+    // Private and loopback access still needs both halves of the durable permission. The server can
+    // offer it, but cannot make this intersection non-empty.
+    effective = intersectHosts(granted, permitted);
+    allowPrivateNetwork = local.allowPrivateNetwork;
+  }
+  if (effective.length === 0) {
+    throw new SnapshotRefused(
+      `This private or local study wants ${granted.join(", ") || "nothing"}, and this machine allows ` +
+        `${permitted.join(", ") || "nothing"}. Nothing in common, so nothing will be opened. ` +
+        "Add the private host with `aloud allow <host>` if that is intentional.",
+    );
+  }
+
   // And then the same check the browser worker will make, so a refusal happens before anything is
   // launched rather than three browsers in. Cloud metadata endpoints are refused unconditionally
   // in here, regardless of the private-network setting.
   const target = await evaluateTargetUrl(startUrl, {
     allowedDomains: effective,
-    allowPrivateNetwork: local.allowPrivateNetwork,
+    allowPrivateNetwork,
     ...(resolver ? { resolver } : {}),
   });
   if (!target.allowed) throw new SnapshotRefused(target.reason);
 
   return {
     allowedHosts: effective,
+    allowPrivateNetwork,
     snapshot: {
       ...snapshot,
       environment: {

package/src/ui/output.ts

@@ -39,7 +39,8 @@ export class TerminalReporter implements RunReporter {
     this.say("");
     this.say(`  Chromium          ${input.chromium ? GREEN + "ready" + RESET : YELLOW + "not installed yet" + RESET}`);
     this.say(`  Connection        ${input.server}`);
-    this.say(`  Allowed here      ${input.allowedHosts.join(", ") || "nothing yet - run `aloud allow <host>`"}`);
+    this.say(`  Public sites      ${GREEN}automatic per study${RESET}`);
+    this.say(`  Private/local     ${input.allowedHosts.join(", ") || "nothing approved"}`);
     this.say("");
   }
 

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.2";
+export const RUNNER_VERSION = "0.3.3";
 
 /** The header the server reads it from. */
 export const RUNNER_VERSION_HEADER = "x-aloud-runner-version";