@aloud/runner 0.2.5 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloud/runner",
-  "version": "0.2.5",
+  "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

@@ -8,6 +8,13 @@
  */
 import { createInterface } from "node:readline/promises";
 import { spawn } from "node:child_process";
+import { startApproval, waitForApproval, type ApprovalStart } from "./protocol/approval";
+import {
+  clearMcpCredentials,
+  mcpCredentialsPath,
+  readMcpCredentials,
+  writeMcpCredentials,
+} from "./config/mcp-credentials";
 import { mkdir } from "node:fs/promises";
 import { accessSync, constants, existsSync, openSync, readFileSync, unlinkSync } from "node:fs";
 import { hostname } from "node:os";
@@ -24,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";
@@ -50,8 +64,17 @@ 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":
-      await startStdioServer();
+      // `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.
+      if (rest[0] === "connect") return connectMcp(rest.slice(1));
+      if (rest[0] === "disconnect") return disconnectMcp();
+      await startStdioServer((await mcpOptions()) ?? undefined);
       return 0;
     case "help":
     case "--help":
@@ -74,12 +97,15 @@ function printHelp(): void {
       "aloud - run usability studies on this machine",
       "",
       "  aloud setup                     What to do next, for a person or an agent",
-      "  aloud login [--token <token>]   Connect this machine to your workspace",
-      "  aloud start [--once] [--quiet]  Wait for studies and run them here",
+      "  aloud login [--token <token>]   Connect this machine, approving it in your browser",
+      "  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                       Connect an MCP host to the Aloud web workspace",
+      "  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)`,
       "",
@@ -96,6 +122,7 @@ function policyOf(credentials: Credentials, argv: readonly string[]): LocalPolic
   return policyFrom({
     allowedHosts: credentials.allowedHosts,
     allowPrivateNetwork: credentials.allowPrivateNetwork,
+    syntheticEmailTemplate: process.env.UTA_SYNTHETIC_EMAIL_TEMPLATE ?? null,
     ...(concurrency !== null ? { maxConcurrentSessions: concurrency } : {}),
   });
 }
@@ -104,44 +131,63 @@ function policyOf(credentials: Credentials, argv: readonly string[]): LocalPolic
 
 async function login(argv: readonly string[]): Promise<number> {
   const server = stringOption(argv, "--server") ?? DEFAULT_SERVER;
-  let token = stringOption(argv, "--token");
-
-  if (!token) {
-    // An agent runs commands in a shell with nothing attached to stdin, so the prompt below would
-    // read end-of-file and the token would come back empty. That used to surface as "that does not
-    // look like a runner token", which blames the wrong thing and tells nobody what to do. This is
-    // the single step of setup that a person has to perform, so it is worth saying so precisely.
-    if (!process.stdin.isTTY) {
-      process.stderr.write(
-        [
-          "",
-          "There is no terminal attached here, so there is nowhere to paste a token.",
-          "",
-          "If you are an agent: stop and hand this back. The person runs `aloud login` in their",
-          "own terminal and pastes the token at the prompt. Do not ask them to paste it to you.",
-          "",
-          "To connect without a terminal, set both of these instead and skip login entirely:",
-          `  export ALOUD_SERVER=${server}`,
-          "  export ALOUD_RUNNER_TOKEN=utar_...",
-          "",
-          `A token comes from ${server}/app/settings/runners and is shown once.`,
-          "",
-        ].join("\n"),
-      );
-      return 1;
-    }
+  const token = stringOption(argv, "--token");
 
-    process.stdout.write(`\nOpen ${server}/app/settings/runners and create a runner.\n`);
-    process.stdout.write("It shows you a token once. Paste it here.\n\n");
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    try {
-      token = (await rl.question("Token: ")).trim();
-    } finally {
-      rl.close();
-    }
+  // A token on the command line is for CI, where there is nobody to click anything. Everything else
+  // goes through an approval, including a terminal: it is fewer steps even when someone is watching.
+  if (token) return connectWith(server, token);
+
+  let started: ApprovalStart;
+  try {
+    started = await startApproval({ server, kind: "runner", name: hostname() });
+  } catch (error) {
+    process.stderr.write(`\n${(error as Error).message}\n\n`);
+    return 1;
   }
 
-  if (!token?.startsWith("utar_")) {
+  process.stdout.write("\nTo connect this machine, open this page and approve it:\n\n");
+  process.stdout.write(`  ${started.approveUrl}\n\n`);
+  process.stdout.write("Then type this code on that page:\n\n");
+  process.stdout.write(`  ${started.userCode}\n\n`);
+  // Said explicitly because the thing running this is often not a person, and the old flow trained
+  // agents to go looking for a token to paste. There is nothing to paste any more.
+  process.stdout.write("Waiting for approval. Nothing here needs a terminal, and there is no token\n");
+  process.stdout.write("to paste: if you are an agent, give the person the link and the code above.\n\n");
+
+  // Opening a browser is a courtesy for whoever is sitting here. It is never attempted when nobody
+  // is, and a failure is ignored, because the printed URL is the thing that actually matters.
+  if (process.stdout.isTTY) openInBrowser(started.approveUrl);
+
+  const outcome = await waitForApproval(started, {
+    server,
+    onWaiting: (seconds) => process.stdout.write(`  still waiting (${seconds}s)\n`),
+  }).catch((error: Error) => {
+    process.stderr.write(`\n${error.message}\n`);
+    return null;
+  });
+
+  if (!outcome) return 1;
+  if (outcome.status === "denied") {
+    process.stderr.write("\nThat request was refused. Nothing was connected.\n\n");
+    return 1;
+  }
+  if (outcome.status === "expired") {
+    process.stderr.write("\nThat request expired before anyone approved it. Run `aloud login` again.\n\n");
+    return 1;
+  }
+
+  return connectWith(server, outcome.secret);
+}
+
+/**
+ * Writes the credential and says what this machine may now do.
+ *
+ * Shared by both paths on purpose: a token that arrived through an approval and one passed on the
+ * command line have to end up in exactly the same state on disk, or the two ways of connecting
+ * diverge in ways nobody notices until one of them breaks.
+ */
+async function connectWith(server: string, token: string): Promise<number> {
+  if (!token.startsWith("utar_")) {
     process.stderr.write("That does not look like a runner token. They start with utar_.\n");
     return 1;
   }
@@ -184,6 +230,93 @@ async function login(argv: readonly string[]): Promise<number> {
   return 0;
 }
 
+/** Best effort, and deliberately silent about failing. The URL was already printed. */
+function openInBrowser(url: string): void {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(command, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+    // No browser here. That is what the printed link is for.
+  }
+}
+
+/**
+ * Connects an MCP host, through the same approval as a machine.
+ *
+ * The difference from a runner is only what the approval mints. Everything a person experiences,
+ * and everything an agent has to do, is identical: a link, a code, and a wait. Nobody edits a
+ * config file to hold a token, which was the last place a credential still had to be carried by
+ * hand after `aloud login` stopped needing one.
+ */
+async function connectMcp(argv: readonly string[]): Promise<number> {
+  const server = stringOption(argv, "--server") ?? DEFAULT_SERVER;
+
+  let started: ApprovalStart;
+  try {
+    started = await startApproval({ server, kind: "mcp", name: hostname() });
+  } catch (error) {
+    process.stderr.write(`\n${(error as Error).message}\n\n`);
+    return 1;
+  }
+
+  process.stdout.write("\nTo connect this editor to your workspace, open this page and approve it:\n\n");
+  process.stdout.write(`  ${started.approveUrl}\n\n`);
+  process.stdout.write("Then type this code on that page:\n\n");
+  process.stdout.write(`  ${started.userCode}\n\n`);
+  process.stdout.write("Waiting for approval. There is no token to paste anywhere.\n\n");
+  if (process.stdout.isTTY) openInBrowser(started.approveUrl);
+
+  const outcome = await waitForApproval(started, {
+    server,
+    onWaiting: (seconds) => process.stdout.write(`  still waiting (${seconds}s)\n`),
+  }).catch((error: Error) => {
+    process.stderr.write(`\n${error.message}\n`);
+    return null;
+  });
+
+  if (!outcome) return 1;
+  if (outcome.status === "denied") {
+    process.stderr.write("\nThat request was refused. Nothing was connected.\n\n");
+    return 1;
+  }
+  if (outcome.status === "expired") {
+    process.stderr.write("\nThat request expired. Run `aloud mcp connect` again.\n\n");
+    return 1;
+  }
+
+  await writeMcpCredentials({ server, token: outcome.secret });
+
+  process.stdout.write(`\nConnected. The credential is in ${mcpCredentialsPath()}, not in any config file.\n`);
+  process.stdout.write("Point your MCP host at `aloud mcp` and it will find it.\n\n");
+  return 0;
+}
+
+async function disconnectMcp(): Promise<number> {
+  const removed = await clearMcpCredentials();
+  process.stdout.write(
+    removed
+      ? `Forgot the MCP credential at ${mcpCredentialsPath()}.\nRevoke it in the web app too, if you want it dead everywhere.\n`
+      : "There was no MCP credential here to forget.\n",
+  );
+  return 0;
+}
+
+/**
+ * The credential `aloud mcp` runs with, if there is one.
+ *
+ * The environment wins, so CI and self-hosting keep working exactly as they did. A missing file is
+ * not an error here: `startStdioServer` falls back to the environment and produces the message that
+ * explains what to set.
+ */
+async function mcpOptions(): Promise<{ server: string; token: string } | null> {
+  const credentials = await readMcpCredentials().catch(() => null);
+  if (!credentials) return null;
+  if (process.env.ALOUD_MCP_TOKEN?.trim()) return null;
+  return { server: credentials.server, token: credentials.token };
+}
+
 async function logout(): Promise<number> {
   const removed = await clearCredentials();
   process.stdout.write(removed ? `Forgot the token at ${credentialsPath()}.\n` : "There was nothing to forget.\n");
@@ -210,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");
@@ -250,15 +383,15 @@ 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",
-      "Needs a terminal. If you are an agent, hand this step to the person: they run it",
-      "themselves and paste the token at the prompt. Do not ask them to paste it to you.",
+      "Prints a link and a short code, then waits. Give both to the person; they approve in",
+      "their browser. Nothing to paste, and no terminal needed. It finishes on its own.",
     ]);
   }
   if (!running) {
@@ -299,9 +432,9 @@ 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("  - The token is a credential. It belongs in this terminal, never in your transcript,");
-  out("    a file, an .env, or a commit. Get one at https://usealoud.com/app/settings/runners");
+  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.");
   out();
   if (!credentials) {
@@ -350,14 +483,12 @@ async function interactiveSetup(state: {
     if (state.signedIn.state !== "ok") {
       out("");
       if (state.signedIn.state === "revoked") {
-        out(`The token saved here was revoked, so this machine needs a new one.`);
+        out("The credential saved here was revoked, so this machine needs connecting again.");
       }
-      out(`Create a token at ${server}/app/settings/runners`);
-      out("It is shown once. Copy it, then paste it below.");
-      out("");
-      const token = (await rl.question("Token: ")).trim();
       rl.close();
-      const code = await login(["--token", token, "--server", server]);
+      // Straight into the approval. There is no token to ask anybody for any more, so there is
+      // nothing to prompt for either.
+      const code = await login(["--server", server]);
       if (code !== 0) return code;
     } else {
       rl.close();
@@ -507,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> {
@@ -572,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/config/mcp-credentials.ts

@@ -0,0 +1,83 @@
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * The MCP grant, at ~/.aloud/mcp.json, mode 0600.
+ *
+ * Kept in its own file rather than beside the runner token, because they are different credentials
+ * with different lifetimes: a machine can be revoked without cutting off an editor, and an editor
+ * can be disconnected without stopping studies. Same rules as `credentials.ts` otherwise, including
+ * the refusal to read a file other users can see.
+ *
+ * This exists so nobody has to paste a token into an MCP host's config file. `aloud mcp connect`
+ * puts it here, and `aloud mcp` reads it.
+ */
+export interface McpCredentials {
+  server: string;
+  token: string;
+}
+
+export class McpCredentialsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "McpCredentialsError";
+  }
+}
+
+export function mcpCredentialsPath(home = homedir()): string {
+  return join(home, ".aloud", "mcp.json");
+}
+
+export async function readMcpCredentials(path = mcpCredentialsPath()): Promise<McpCredentials | null> {
+  let raw: string;
+  try {
+    const info = await stat(path);
+    // eslint-disable-next-line no-bitwise
+    if ((info.mode & 0o077) !== 0) {
+      throw new McpCredentialsError(
+        `${path} can be read by other users on this machine. Fix it with:\n  chmod 600 ${path}`,
+      );
+    }
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (error instanceof McpCredentialsError) throw error;
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+
+  let parsed: Partial<McpCredentials>;
+  try {
+    parsed = JSON.parse(raw) as Partial<McpCredentials>;
+  } catch {
+    throw new McpCredentialsError(`${path} is not valid JSON. Delete it and run \`aloud mcp connect\` again.`);
+  }
+  if (!parsed.token || !parsed.server) {
+    throw new McpCredentialsError(`${path} is missing fields. Delete it and run \`aloud mcp connect\` again.`);
+  }
+
+  return { server: parsed.server.replace(/\/+$/, ""), token: parsed.token };
+}
+
+/** `mode` on writeFile only applies at creation, so the chmod is the part that actually holds. */
+export async function writeMcpCredentials(
+  credentials: McpCredentials,
+  path = mcpCredentialsPath(),
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path, JSON.stringify(credentials, null, 2) + "\n", { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+export async function clearMcpCredentials(path = mcpCredentialsPath()): Promise<boolean> {
+  try {
+    await writeFile(path, "", { mode: 0o600, flag: constants.O_WRONLY | constants.O_TRUNC });
+    const { unlink } = await import("node:fs/promises");
+    await unlink(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}

package/src/config/policy.ts

@@ -25,6 +25,8 @@ export interface LocalPolicy {
   allowPrivateNetwork: boolean;
   /** The server does not know how much memory this machine has. This is a local decision. */
   maxConcurrentSessions: number;
+  /** Runner-local QA inbox/catch-all; never supplied by the control plane. */
+  syntheticEmailTemplate: string | null;
 }
 
 export const DEFAULT_MAX_CONCURRENT_SESSIONS = 3;
@@ -33,6 +35,7 @@ export function policyFrom(input: {
   allowedHosts?: readonly string[];
   allowPrivateNetwork?: boolean;
   maxConcurrentSessions?: number;
+  syntheticEmailTemplate?: string | null;
 }): LocalPolicy {
   return {
     allowedHosts: normaliseHosts(input.allowedHosts ?? []),
@@ -40,6 +43,7 @@ export function policyFrom(input: {
     // Clamped rather than trusted: three browsers is already a lot on a laptop, and a typo of 300
     // should not take the machine down.
     maxConcurrentSessions: clamp(input.maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS, 1, 8),
+    syntheticEmailTemplate: input.syntheticEmailTemplate?.trim() || null,
   };
 }
 

package/src/model/proxy-adapter.ts

@@ -107,6 +107,7 @@ export class ProxyModelAdapter implements ModelAdapter {
       system: request.system,
       prompt: request.prompt,
       responseShape: request.responseShape,
+      responseSchema: request.responseSchema,
       maxOutputTokens: request.maxOutputTokens,
       temperature: request.temperature,
       images,