diff --git a/apps/cli/src/main.test.ts b/apps/cli/src/main.test.ts
index b703a75e..53fd346f 100644
--- a/apps/cli/src/main.test.ts
+++ b/apps/cli/src/main.test.ts
@@ -1,9 +1,72 @@
+vi.mock("../../server/src/resource-probe.js", () => ({
+  resourceProbe: () => ({ footprintsMiB: new Map(), pressure: "normal", pressureKnown: true }),
+}));
+
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { expect, test, vi } from "vitest";
 import { startService } from "../../server/src/http.js";
 import type { JobLogRequest, JobLogs } from "../../../packages/protocol/src/jobs.js";
+import { activityFor } from "../../server/src/activities.js";
+import type { RunnerProgress } from "../../../packages/protocol/src/runners.js";
+
+test("operation and activity inspection retain phases in pretty and compact JSON", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-cli-phases-"));
+  const server = await startService({ home });
+  const argv = process.argv;
+  const exitCode = process.exitCode;
+  const output = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+  try {
+    const command = { type: "runner.run", bindingId: "binding" } as const;
+    const operation = server.store.accept(
+      "runner",
+      "runner",
+      command.type,
+      activityFor("runner", command),
+      "runner",
+    ).operation;
+    const result: RunnerProgress = {
+      bindingId: "binding",
+      environmentId: "linux",
+      leaseKey: operation.id,
+      stage: "finished",
+      phases: [{ name: "vm_start", startedAt: operation.createdAt, endedAt: operation.createdAt }],
+    };
+    server.store.update(operation, { status: "succeeded", result });
+    for (const command of ["operation", "activity"]) {
+      for (const flags of [[], ["--json"]]) {
+        output.mockClear();
+        vi.resetModules();
+        process.argv = [
+          process.execPath,
+          "vectis",
+          "--home",
+          home,
+          command,
+          "get",
+          "runner",
+          ...flags,
+        ];
+        await import("./main.js");
+        await vi.waitFor(() => expect(output).toHaveBeenCalledOnce());
+        const printed: unknown = JSON.parse(String(output.mock.calls[0]?.[0]));
+        expect(printed).toMatchObject(
+          command === "operation"
+            ? { result }
+            : { operations: [expect.objectContaining({ result })] },
+        );
+      }
+    }
+  } finally {
+    process.argv = argv;
+    process.exitCode = exitCode;
+    output.mockRestore();
+    vi.resetModules();
+    await server.close();
+    await rm(home, { recursive: true, force: true });
+  }
+});
 
 test("machine configure settles without --wait and status prints runner capacity", async () => {
   const home = await mkdtemp(join(tmpdir(), "vectis-cli-capacity-"));
@@ -21,6 +84,8 @@ test("machine configure settles without --wait and status prints runner capacity
       "configure",
       "--max-runners",
       "3",
+      "--memory-budget-mib",
+      "8192",
       "--key",
       "cli-configure",
       "--json",
@@ -29,14 +94,19 @@ test("machine configure settles without --wait and status prints runner capacity
     await vi.waitFor(() =>
       expect(output).toHaveBeenCalledWith(expect.stringContaining('"status":"succeeded"')),
     );
-    expect(server.service.snapshot().machine.maxRunners).toBe(3);
+    expect(server.service.snapshot().machine).toMatchObject({
+      maxRunners: 3,
+      memoryBudgetMiB: 8192,
+    });
     output.mockClear();
     vi.resetModules();
     process.argv = [process.execPath, "vectis", "--home", home, "status", "--json"];
     await import("./main.js");
     await vi.waitFor(() =>
       expect(output).toHaveBeenCalledWith(
-        expect.stringContaining('"runnerCapacity":{"max":3,"active":0,"available":0}'),
+        expect.stringContaining(
+          '"runnerCapacity":{"max":3,"active":0,"available":0,"environments":[],',
+        ),
       ),
     );
   } finally {
@@ -48,6 +118,59 @@ test("machine configure settles without --wait and status prints runner capacity
   }
 });
 
+test.each([
+  { args: ["--memory-budget-mib", "2048"], valid: true },
+  { args: ["--memory-budget-mib", "2047"], valid: false },
+  { args: ["--memory-budget-mib", "4096.5"], valid: false },
+  { args: ["--memory-budget-mib", "invalid"], valid: false },
+  { args: [], valid: false },
+])(
+  "machine configure parses memory-only and rejects invalid arguments: $args",
+  async ({ args, valid }) => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-cli-budget-"));
+    const server = await startService({ home });
+    const submit = vi.spyOn(server.service, "submit");
+    const argv = process.argv;
+    const exitCode = process.exitCode;
+    const output = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    try {
+      vi.resetModules();
+      process.argv = [
+        process.execPath,
+        "vectis",
+        "--home",
+        home,
+        "machine",
+        "configure",
+        ...args,
+        "--key",
+        "budget",
+        "--json",
+      ];
+      await import("./main.js");
+      await vi.waitFor(() => expect(output).toHaveBeenCalled());
+      if (valid) {
+        expect(submit).toHaveBeenCalledWith("budget", {
+          type: "machine.configure",
+          memoryBudgetMiB: 2048,
+        });
+        expect(output).toHaveBeenCalledWith(expect.stringContaining('"status":"succeeded"'));
+      } else {
+        expect(submit).not.toHaveBeenCalled();
+        expect(process.exitCode).toBe(1);
+        expect(output).toHaveBeenCalledWith(expect.stringContaining('"error":'));
+      }
+    } finally {
+      process.argv = argv;
+      process.exitCode = exitCode;
+      output.mockRestore();
+      submit.mockRestore();
+      await server.close();
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
+
 test.each([
   { actors: "7,7,8", approval: "required", expected: { ids: [7, 8] } },
   { actors: "any", approval: "automatic", expected: "any" },
@@ -577,3 +700,266 @@ test.each([
     await rm(home, { recursive: true, force: true });
   }
 });
+
+test.each([
+  { value: "0", valid: true },
+  { value: "1", valid: true },
+  { value: "4", valid: true },
+  { value: "-1", valid: false },
+  { value: "5", valid: false },
+  { value: "1.5", valid: false },
+  { value: "invalid", valid: false },
+])(
+  "environment configure parses --warm-pool $value through the shared command",
+  async ({ value, valid }) => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-cli-warm-"));
+    const server = await startService({ home });
+    const submit = vi.spyOn(server.service, "submit");
+    const argv = process.argv;
+    const exitCode = process.exitCode;
+    const output = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    try {
+      vi.resetModules();
+      process.argv = [
+        process.execPath,
+        "vectis",
+        "--home",
+        home,
+        "environment",
+        "configure",
+        "linux",
+        "--warm-pool",
+        value,
+        "--key",
+        "pool",
+        "--json",
+      ];
+      await import("./main.js");
+      await vi.waitFor(() => expect(output).toHaveBeenCalled());
+      if (valid)
+        expect(submit).toHaveBeenCalledWith("pool", {
+          type: "environment.configure",
+          id: "linux",
+          warmPool: Number(value),
+        });
+      else {
+        expect(submit).not.toHaveBeenCalled();
+        expect(process.exitCode).toBe(1);
+      }
+    } finally {
+      process.argv = argv;
+      process.exitCode = exitCode;
+      output.mockRestore();
+      submit.mockRestore();
+      await server.close();
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
+
+test("CLI status shows warm pool VMs without counting them as running jobs", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-cli-warm-status-"));
+  const server = await startService({ home });
+  const argv = process.argv;
+  const exitCode = process.exitCode;
+  const output = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+  try {
+    server.service.store.put("environment", "linux", {
+      id: "linux",
+      name: "Linux",
+      os: "linux",
+      state: "ready",
+      basePath: join(home, "base"),
+      cpu: 1,
+      memoryMiB: 512,
+      warmPool: 1,
+    });
+    server.service.store.put("instance", "warm", {
+      id: "warm",
+      environmentId: "linux",
+      status: "running",
+      role: "warm",
+      memoryMiB: 512,
+      pid: 0,
+      createdAt: new Date().toISOString(),
+    });
+    vi.resetModules();
+    process.argv = [process.execPath, "vectis", "--home", home, "status", "--json"];
+    await import("./main.js");
+    await vi.waitFor(() =>
+      expect(output).toHaveBeenCalledWith(expect.stringContaining('"role":"warm"')),
+    );
+    expect(output).toHaveBeenCalledWith(expect.stringContaining('"active":0'));
+  } finally {
+    process.argv = argv;
+    process.exitCode = exitCode;
+    output.mockRestore();
+    await server.close();
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test.each([
+  {
+    action: "enable",
+    extra: ["--size-gib", "30"],
+    expected: { type: "repository.cache", bindingId: "binding", enabled: true, sizeGiB: 30 },
+  },
+  {
+    action: "disable",
+    extra: [],
+    expected: { type: "repository.cache", bindingId: "binding", enabled: false },
+  },
+  { action: "clear", extra: [], expected: { type: "cache.clear", bindingId: "binding" } },
+])("repository cache $action submits the shared command", async ({ action, extra, expected }) => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-cli-cache-"));
+  const server = await startService({ home });
+  const submit = vi.spyOn(server.service, "submit");
+  const argv = process.argv;
+  const exitCode = process.exitCode;
+  const output = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+  try {
+    vi.resetModules();
+    process.argv = [
+      process.execPath,
+      "vectis",
+      "--home",
+      home,
+      "repository",
+      "cache",
+      action,
+      "binding",
+      ...extra,
+      "--key",
+      "cache",
+      "--json",
+    ];
+    await import("./main.js");
+    await vi.waitFor(() => expect(submit).toHaveBeenCalledWith("cache", expected));
+    await vi.waitFor(() =>
+      expect(output).toHaveBeenCalledWith(expect.stringContaining('"status":"failed"')),
+    );
+  } finally {
+    process.argv = argv;
+    process.exitCode = exitCode;
+    output.mockRestore();
+    submit.mockRestore();
+    await server.close();
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test.each([
+  { input: "demand", mode: "demand" },
+  { input: "scale-set", mode: "scale_set" },
+  { input: "scale_set", mode: undefined },
+  { input: "unknown", mode: undefined },
+])(
+  "repository capacity-mode parses $input and waits for the shared setting",
+  async ({ input, mode }) => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-cli-mode-"));
+    const server = await startService({ home });
+    const submit = vi.spyOn(server.service, "submit");
+    const argv = process.argv;
+    const exitCode = process.exitCode;
+    const output = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    try {
+      vi.resetModules();
+      process.argv = [
+        process.execPath,
+        "vectis",
+        "--home",
+        home,
+        "repository",
+        "capacity-mode",
+        "binding",
+        input,
+        "--key",
+        "capacity-mode",
+        "--json",
+      ];
+      await import("./main.js");
+      if (mode === undefined) {
+        await vi.waitFor(() =>
+          expect(output).toHaveBeenCalledWith(expect.stringContaining("invalid_capacity_mode")),
+        );
+        expect(submit).not.toHaveBeenCalled();
+      } else {
+        await vi.waitFor(() =>
+          expect(output).toHaveBeenCalledWith(expect.stringContaining('"status":"failed"')),
+        );
+        expect(submit).toHaveBeenCalledWith("capacity-mode", {
+          type: "repository.capacity-mode",
+          bindingId: "binding",
+          mode,
+        });
+        expect(server.service.snapshot().operations[0]?.status).toBe("failed");
+        expect(process.exitCode).toBe(1);
+      }
+    } finally {
+      process.argv = argv;
+      process.exitCode = exitCode;
+      output.mockRestore();
+      submit.mockRestore();
+      await server.close();
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
+
+test.each([false, true])(
+  "environment provision reads setup data and parses --no-runner=%s",
+  async (noRunner) => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-cli-provision-"));
+    const server = await startService({ home });
+    const submit = vi.spyOn(server.service, "submit");
+    const argv = process.argv;
+    const exitCode = process.exitCode;
+    const output = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    try {
+      const scriptPath = join(home, "setup.sh");
+      await writeFile(scriptPath, "printf 'guest setup text'\n");
+      vi.resetModules();
+      process.argv = [
+        process.execPath,
+        "vectis",
+        "--home",
+        home,
+        "environment",
+        "provision",
+        "derived",
+        "--from",
+        "parent",
+        "--image-directory",
+        join(home, "image"),
+        "--name",
+        "Derived tools",
+        "--setup-script",
+        scriptPath,
+        ...(noRunner ? ["--no-runner"] : []),
+        "--key",
+        "provision",
+        "--json",
+      ];
+      await import("./main.js");
+      await vi.waitFor(() =>
+        expect(submit).toHaveBeenCalledWith("provision", {
+          type: "environment.provision",
+          id: "derived",
+          from: "parent",
+          imageDirectory: join(home, "image"),
+          name: "Derived tools",
+          setupScript: "printf 'guest setup text'\n",
+          ...(noRunner ? { runner: false } : {}),
+        }),
+      );
+    } finally {
+      process.argv = argv;
+      process.exitCode = exitCode;
+      await server.close();
+      output.mockRestore();
+      submit.mockRestore();
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
diff --git a/apps/cli/src/main.ts b/apps/cli/src/main.ts
index a292a024..62732f29 100644
--- a/apps/cli/src/main.ts
+++ b/apps/cli/src/main.ts
@@ -57,17 +57,23 @@ async function main() {
       x64: { type: "string" },
       egress: { type: "string" },
       "max-runners": { type: "string" },
+      "memory-budget-mib": { type: "string" },
+      "warm-pool": { type: "string" },
       "job-id": { type: "string" },
       ref: { type: "string" },
       input: { type: "string", multiple: true },
       actors: { type: "string" },
       approval: { type: "string" },
+      "size-gib": { type: "string" },
       account: { type: "string" },
       binding: { type: "string" },
       owner: { type: "string" },
       name: { type: "string" },
       "disk-gib": { type: "string" },
       "image-directory": { type: "string" },
+      from: { type: "string" },
+      "setup-script": { type: "string" },
+      "no-runner": { type: "boolean" },
       "restore-path": { type: "string" },
       "open-terminal": { type: "boolean" },
       "iso-path": { type: "string" },
@@ -127,7 +133,7 @@ Service
   service status                Inspect the login service registration for this home
   service update                Adopt this runtime when idle; restore the previous one on failure
   service recover-update        Restore the previous runtime after an interrupted update
-  status                        Inspect the machine and recent operations
+  status                        Inspect the machine, unfinished work and bounded recent history
   storage                       Inspect image and VM disk usage
   doctor                        Inspect host and runtime prerequisites
   logs [--lines <count>]        Read the newest service log lines (default 200, at most 1000)
@@ -144,7 +150,9 @@ Cloud and GitHub
   login finish                  Complete an approved remote control login
   logout                        Revoke this CLI's remote access and remove its credentials
   machine list                  List your machines and when they were last seen
-  machine configure --max-runners <N>  Set concurrent runner limit (1-16, default 5)
+  machine configure [--max-runners <N>] [--memory-budget-mib <N>]
+                                Set runner limit (1-16, default 5) and shared VM memory budget
+                                Memory budget: 2048 MiB to host RAM, default 75% of host RAM
 
 Repositories and jobs
   repository readiness <owner/name> [--environment <id>]  Check readiness before connecting
@@ -153,9 +161,12 @@ Repositories and jobs
   repository connect <name>     Connect with --account <id> and --environment <id>, optional --owner <org>
   repository enable-auto <id>   Start runners automatically for matching queued jobs
   repository disable-auto <id>  Stop starting runners automatically
+  repository capacity-mode <id> demand|scale-set  Choose runner capacity mode (scale sets are preview)
   repository disconnect <id>    Stop future runners without interrupting running jobs
   runner run <binding-id>       Start one disposable runner, optionally only for --job-id <id>
   runner reconcile <operation-id>  Clean up an interrupted runner after verifying its VM stopped
+  repository cache enable|disable|clear <binding-id> [--size-gib N]
+                               Configure or clear an opt-in repository cache disk (default 20 GiB)
   repository access <binding-id> --actors any|<id,id,...> --approval automatic|required
                                Actor IDs are numeric GitHub user IDs: gh api users/<login> --jq .id
   job list <binding-id>         Read recent GitHub job states for a connected repository
@@ -177,6 +188,8 @@ Workflow migration
   migration publish <preview-id>  Create or recover its pull request; never merges
 
 Environments
+  environment provision <id>   Derive a new image with --from <id> --image-directory <new-path>
+                               [--name <name>] [--setup-script <file>] [--no-runner]
   environment prepare-linux <id>  Prepare Ubuntu 24.04 with --image-directory and --storage-path
   environment resume <setup-id>   Continue an interrupted Ubuntu preparation
   environment install-macos <id>  Install macOS 26 with --image-directory and --storage-path, optional --restore-path
@@ -191,16 +204,17 @@ Environments
   environment register --file <path>  Register an existing prepared environment JSON file
   environment list              List environments and effective network egress
   environment configure <id>    Set --cpu, --memory-mib, --storage-path, --x64 rosetta|off or --egress internet_only|open for future VMs
+                                --warm-pool <N> keeps 0-4 SSH-ready VMs (default 0, uses RAM)
   environment start <id>        Start a clean VM, optionally overriding --cpu, --memory-mib, --storage-path
   environment remove <id>       Remove an idle definition, preserving its disk
   instance stop <id>            Stop a VM owned by this service
   instance reconcile <id>       Recheck an interrupted VM safely
 
 Activities and operations
-  activity list                 List activities, newest first; filter with --kind, --status, --repository, --limit
+  activity list                 List unfinished and recent activities; filter with --kind, --status, --repository, --limit
   activity get <id>             Inspect one activity with the operations that belong to it
   activity cancel <id>          Cancel work an activity owns, or close one that only waits for you
-  operation get <id>            Inspect one operation
+  operation get <id>            Inspect one retained operation, including outside the status window
   operation wait <id>           Wait for an operation's terminal state; on --timeout, print it as it is
   operation cancel <id>         Cancel an active operation, or close one that only waits for you
   command --file <path>         Submit any protocol command as JSON
@@ -241,7 +255,7 @@ Options
   -h, --help                    Show this help
 
 Exit codes: 0 success, 1 failure or cancellation, 3 action required or still pending.
-Setting commands always wait: pause/resume, repository enable-auto/disable-auto,
+Setting commands always wait: pause/resume, repository enable-auto/disable-auto/capacity-mode, repository cache,
 environment register/configure/remove, instance stop/reconcile, operation cancel, and activity cancel.
 Their wait timeout reports wait_cancelled with exit code 3; the operation may still be running.
 Errors are JSON: {"error":{"code","message","nextStep"}}.
@@ -262,6 +276,14 @@ Documentation: https://vectis.kerd.dev/docs
       "invalid_arguments",
       "--egress is supported only by environment configure.",
     );
+  if (
+    values["warm-pool"] !== undefined &&
+    !(command === "environment" && subcommand === "configure")
+  )
+    throw new VectisError(
+      "invalid_arguments",
+      "--warm-pool is supported only by environment configure.",
+    );
   if (values.machine && ["service", "cloud", "login", "logout", "machine"].includes(command))
     throw new VectisError("invalid_target", "This command does not accept --machine.");
   if (
@@ -595,12 +617,17 @@ Documentation: https://vectis.kerd.dev/docs
   let request: Command;
   if (command === "pause" || command === "resume")
     request = { type: "machine.pause", paused: command === "pause" };
-  else if (command === "machine" && subcommand === "configure")
+  else if (command === "machine" && subcommand === "configure") {
+    if (values["max-runners"] === undefined && values["memory-budget-mib"] === undefined)
+      throw new VectisError("missing_argument", "Specify --max-runners or --memory-budget-mib.");
     request = decodeCommand({
       type: "machine.configure",
-      maxRunners: Number(values["max-runners"]),
+      ...(values["max-runners"] !== undefined ? { maxRunners: Number(values["max-runners"]) } : {}),
+      ...(values["memory-budget-mib"] !== undefined
+        ? { memoryBudgetMiB: Number(values["memory-budget-mib"]) }
+        : {}),
     });
-  else if (
+  } else if (
     command === "repository" &&
     (subcommand === "enable-auto" || subcommand === "disable-auto") &&
     id
@@ -610,7 +637,35 @@ Documentation: https://vectis.kerd.dev/docs
       bindingId: id,
       enabled: subcommand === "enable-auto",
     });
-  else if (command === "repository" && subcommand === "access" && id) {
+  else if (command === "repository" && subcommand === "cache" && positionals[3]) {
+    const bindingId = positionals[3];
+    if (id === "clear" && values["size-gib"] === undefined)
+      request = decodeCommand({ type: "cache.clear", bindingId });
+    else if (id === "enable" || (id === "disable" && values["size-gib"] === undefined))
+      request = decodeCommand({
+        type: "repository.cache",
+        bindingId,
+        enabled: id === "enable",
+        ...(values["size-gib"] === undefined ? {} : { sizeGiB: Number(values["size-gib"]) }),
+      });
+    else
+      throw new VectisError(
+        "invalid_cache_command",
+        "Use repository cache enable|disable|clear <binding-id>; --size-gib is only valid with enable.",
+      );
+  } else if (command === "repository" && subcommand === "capacity-mode" && id) {
+    const mode = positionals[3];
+    if (positionals.length !== 4 || (mode !== "demand" && mode !== "scale-set"))
+      throw new VectisError(
+        "invalid_capacity_mode",
+        "Use repository capacity-mode <binding-id> demand|scale-set.",
+      );
+    request = decodeCommand({
+      type: "repository.capacity-mode",
+      bindingId: id,
+      mode: mode === "scale-set" ? "scale_set" : "demand",
+    });
+  } else if (command === "repository" && subcommand === "access" && id) {
     if (
       !values.actors ||
       (values.actors !== "any" && !/^[1-9][0-9]*(,[1-9][0-9]*)*$/.test(values.actors))
@@ -754,6 +809,18 @@ Documentation: https://vectis.kerd.dev/docs
     request = decodeCommand({ type: "environment.finish-macos-setup", id });
   else if (command === "environment" && subcommand === "resume-macos" && id)
     request = decodeCommand({ type: "environment.resume-macos", id });
+  else if (command === "environment" && subcommand === "provision" && id)
+    request = decodeCommand({
+      type: "environment.provision",
+      id,
+      from: values.from,
+      imageDirectory: values["image-directory"],
+      ...(values.name !== undefined ? { name: values.name } : {}),
+      ...(values["setup-script"] !== undefined
+        ? { setupScript: await readFile(values["setup-script"], "utf8") }
+        : {}),
+      ...(values["no-runner"] ? { runner: false } : {}),
+    });
   else if (command === "environment" && subcommand === "prepare-linux" && id)
     request = decodeCommand({
       type: "environment.prepare-linux",
@@ -778,6 +845,7 @@ Documentation: https://vectis.kerd.dev/docs
     request = decodeCommand({
       type: "environment.configure",
       id,
+      ...(values["warm-pool"] !== undefined ? { warmPool: Number(values["warm-pool"]) } : {}),
       ...(values.x64 !== undefined ? { x64: values.x64 } : {}),
       ...(values.egress !== undefined ? { egress: values.egress } : {}),
       ...(values.cpu !== undefined ? { cpu: Number(values.cpu) } : {}),
diff --git a/apps/desktop/src/bridge.ts b/apps/desktop/src/bridge.ts
index 2c6b6adf..d1b1450d 100644
--- a/apps/desktop/src/bridge.ts
+++ b/apps/desktop/src/bridge.ts
@@ -7,6 +7,7 @@ export type DesktopAction =
   | "notifications.get"
   | "notifications.set"
   | "status"
+  | "activity"
   | "storage"
   | "doctor"
   | "logs"
diff --git a/apps/desktop/src/command-labels.ts b/apps/desktop/src/command-labels.ts
index 9427d8da..33c84690 100644
--- a/apps/desktop/src/command-labels.ts
+++ b/apps/desktop/src/command-labels.ts
@@ -1,4 +1,5 @@
 export const commandLabels: Record<string, string> = {
+  "environment.provision": "Provision derived environment",
   "environment.prepare-linux": "Prepare Linux image",
   "environment.resume": "Resume Linux preparation",
   "environment.install-macos": "Install macOS",
@@ -32,5 +33,5 @@ export const commandLabels: Record<string, string> = {
   "environment.remove": "Remove environment",
   "operation.cancel": "Close operation",
   "machine.pause": "Change VM intake",
-  "machine.configure": "Change concurrent VMs",
+  "machine.configure": "Change VM capacity",
 };
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 8630dee9..4592f527 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -231,6 +231,11 @@ else {
             case "status":
               data = await (await client()).status();
               break;
+            case "activity":
+              data = await (
+                await client()
+              ).activity(Schema.decodeUnknownSync(Schema.NonEmptyString)(input));
+              break;
             case "jobs": {
               const bindingId = Schema.decodeUnknownSync(Schema.NonEmptyString)(input);
               data = await (await client()).jobs(bindingId);
diff --git a/apps/desktop/src/renderer/components/activity-row.tsx b/apps/desktop/src/renderer/components/activity-row.tsx
index 641a3837..7e7f3441 100644
--- a/apps/desktop/src/renderer/components/activity-row.tsx
+++ b/apps/desktop/src/renderer/components/activity-row.tsx
@@ -5,15 +5,24 @@ import { GitHubIcon } from "@/components/github-icon";
 import { JobLog } from "@/components/job-log";
 import { Details, ExpandableRow, Mono } from "@/components/layout";
 import { OsTile } from "@/components/os-icon";
-import { JobStatus, OperationStatus, RunnerStage, StatusText } from "@/components/status";
+import { RunnerPhases } from "@/components/runner-phases";
+import {
+  JobStatus,
+  OperationStatus,
+  RunnerStage,
+  StatusBadge,
+  StatusText,
+} from "@/components/status";
 import { Button } from "@/components/ui/button";
 import { activityJob, activitySummary, activityTitle } from "@/lib/activities";
 import { formatDateTime, formatRelative } from "@/lib/format";
+import { resultCodePresentation } from "@/lib/result-code";
 import { isGeneratedStageMessage, activeRunnerStage } from "@/lib/runner-stage";
+import { runnerPhaseTimeline } from "@/lib/runner-phases";
 import { cancellableCommands, commandLabels } from "@/lib/operations";
 import { MigrationResult } from "@/views/migration-result";
 import { PreparationResult } from "@/views/preparation-result";
-import { useStateApi } from "@/state";
+import { useActivityDetail, useStateApi } from "@/state";
 
 function VectisTile() {
   return (
@@ -24,16 +33,19 @@ function VectisTile() {
 }
 
 export function ActivityRow({
-  activity,
+  activity: summary,
   defaultOpen = false,
 }: {
   activity: Activity;
   defaultOpen?: boolean;
 }) {
   const { snapshot, submit, perform } = useStateApi();
-  const operations = (snapshot?.operations ?? []).filter(
-    (operation) => operation.activityId === activity.id,
-  );
+  const [open, setOpen] = useState(defaultOpen);
+  const detail = useActivityDetail(summary.id, open);
+  const activity = detail?.activity ?? summary;
+  const operations =
+    detail?.operations.toReversed() ??
+    (snapshot?.operations ?? []).filter((operation) => operation.activityId === activity.id);
   // Operations arrive newest first; an activity reads as the story of what happened.
   const steps = [...operations].reverse();
   const deciding =
@@ -55,6 +67,7 @@ export function ActivityRow({
   const closable = activity.status === "action_required" && !preparation && !reconcilable;
   const stage = activeRunnerStage(activity, deciding, job?.status);
   const result: unknown = deciding?.result;
+  const codeStatus = resultCodePresentation(result);
   const nextStep =
     typeof result === "object" &&
     result &&
@@ -77,9 +90,17 @@ export function ActivityRow({
     typeof result.diagnostics === "string"
       ? result.diagnostics
       : undefined;
+  const timeline =
+    activity.subject.type === "runner" && deciding?.command === "runner.run"
+      ? runnerPhaseTimeline(result, {
+          active: running,
+          end: running ? Date.now() : Date.parse(activity.completedAt ?? activity.updatedAt),
+        })
+      : undefined;
   return (
     <ExpandableRow
       defaultOpen={defaultOpen}
+      onOpenChange={setOpen}
       leading={
         activity.kind === "github" ? (
           <span className="grid size-9 shrink-0 place-items-center rounded-xl bg-muted text-foreground/80">
@@ -101,6 +122,8 @@ export function ActivityRow({
           {job?.status && <JobStatus status={job.status} conclusion={job.conclusion ?? null} />}
           {stage ? (
             <RunnerStage stage={stage} />
+          ) : codeStatus && !runnerQuiet ? (
+            <StatusBadge tone={codeStatus.tone} label={codeStatus.label} />
           ) : (
             !runnerQuiet && <OperationStatus status={activity.status} />
           )}
@@ -128,6 +151,7 @@ export function ActivityRow({
           </pre>
         </div>
       )}
+      {timeline && <RunnerPhases timeline={timeline} />}
       {job && activity.bindingId && (
         <div className="flex flex-col gap-3">
           <div>
diff --git a/apps/desktop/src/renderer/components/layout.tsx b/apps/desktop/src/renderer/components/layout.tsx
index de4d472b..df944123 100644
--- a/apps/desktop/src/renderer/components/layout.tsx
+++ b/apps/desktop/src/renderer/components/layout.tsx
@@ -270,6 +270,7 @@ export function ExpandableRow({
   aside,
   actions,
   defaultOpen = false,
+  onOpenChange,
   children,
 }: {
   id?: string;
@@ -279,11 +280,13 @@ export function ExpandableRow({
   aside?: ReactNode;
   actions?: ReactNode;
   defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
   children: ReactNode;
 }) {
   return (
     <Collapsible
       defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
       className="rise-in scroll-mt-4"
       id={id ? sectionId(id) : undefined}
     >
diff --git a/apps/desktop/src/renderer/components/path-field.tsx b/apps/desktop/src/renderer/components/path-field.tsx
index 2e266281..15a9f3ce 100644
--- a/apps/desktop/src/renderer/components/path-field.tsx
+++ b/apps/desktop/src/renderer/components/path-field.tsx
@@ -13,6 +13,7 @@ export function PathField({
   required,
   placeholder,
   description,
+  fromChooser = (picked) => picked,
 }: {
   label: string;
   value: string;
@@ -22,6 +23,7 @@ export function PathField({
   required?: boolean;
   placeholder?: string;
   description?: string;
+  fromChooser?: (picked: string) => string;
 }) {
   const { perform, machineId } = useStateApi();
   const id = useId();
@@ -45,7 +47,7 @@ export function PathField({
           aria-label={`Choose ${label}`}
           onClick={() =>
             void perform(chooser).then((picked) => {
-              if (typeof picked === "string") onChange(picked);
+              if (typeof picked === "string") onChange(fromChooser(picked));
             })
           }
         >
diff --git a/apps/desktop/src/renderer/components/runner-phases.tsx b/apps/desktop/src/renderer/components/runner-phases.tsx
new file mode 100644
index 00000000..b84b7b95
--- /dev/null
+++ b/apps/desktop/src/renderer/components/runner-phases.tsx
@@ -0,0 +1,46 @@
+import { StatusText } from "@/components/status";
+import type { PhaseTimeline } from "@/lib/runner-phases";
+import { cn } from "@/lib/utils";
+
+export function RunnerPhases({ timeline }: { timeline: PhaseTimeline }) {
+  return (
+    <div className="flex max-w-[72ch] flex-col gap-2">
+      <p className="text-xs font-medium text-muted-foreground">Timing</p>
+      <ol className="grid grid-cols-[minmax(8rem,max-content)_1fr_minmax(4.5rem,max-content)] items-center gap-x-4 gap-y-1.5 text-xs">
+        {timeline.rows.map((row) => (
+          <li key={row.name} className="col-span-3 grid grid-cols-subgrid items-center">
+            <span className="flex min-w-0 flex-wrap items-baseline gap-x-2">
+              <span className="text-foreground/85">{row.label}</span>
+              {row.count > 1 && <span className="text-muted-foreground">{row.count} times</span>}
+              {row.state === "running" && <StatusText tone="running" label="Running" />}
+              {row.state === "unfinished" && <StatusText tone="idle" label="No end recorded" />}
+            </span>
+            <span aria-hidden className="relative h-1.5 rounded-full bg-hairline">
+              {row.segments.map((segment, index) => (
+                <span
+                  key={index}
+                  className={cn(
+                    "absolute inset-y-0 rounded-full",
+                    row.state === "running" ? "bg-running" : "bg-muted-foreground/45",
+                  )}
+                  style={{
+                    left: `${segment.offset * 100}%`,
+                    width: `max(3px, ${segment.width * 100}%)`,
+                  }}
+                />
+              ))}
+            </span>
+            <span className="text-right font-mono text-foreground/85 tabular-nums">
+              {row.duration}
+            </span>
+          </li>
+        ))}
+        <li className="col-span-3 grid grid-cols-subgrid items-center pt-1">
+          <span className="font-medium">Total</span>
+          <span aria-hidden />
+          <span className="text-right font-mono font-medium tabular-nums">{timeline.total}</span>
+        </li>
+      </ol>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/components/status.tsx b/apps/desktop/src/renderer/components/status.tsx
index 9e09199c..1e9a1f14 100644
--- a/apps/desktop/src/renderer/components/status.tsx
+++ b/apps/desktop/src/renderer/components/status.tsx
@@ -8,7 +8,9 @@ import {
   ClockIcon,
   TriangleAlertIcon,
 } from "lucide-react";
+import type { Instance } from "../../../../../packages/protocol/src/index.js";
 import { runnerStagePresentation, type RunnerStageKey } from "@/lib/runner-stage";
+import { instanceDisplay } from "@/lib/vm-capacity";
 import { cn } from "@/lib/utils";
 
 export const tones = {
@@ -61,21 +63,14 @@ export function OperationStatus({ status }: { status: keyof typeof operationStat
   return <StatusBadge tone={tone} label={label} />;
 }
 
-const instanceStates = {
-  starting: ["queued", "Starting"],
-  running: ["running", "Running"],
-  stopped: ["idle", "Stopped"],
-  interrupted: ["attention", "Interrupted"],
-} as const satisfies Record<string, readonly [Tone, string]>;
-
 export function InstanceStatus({
-  status,
+  instance,
   inline = false,
 }: {
-  status: keyof typeof instanceStates;
+  instance: Pick<Instance, "role" | "status">;
   inline?: boolean;
 }) {
-  const [tone, label] = instanceStates[status];
+  const { tone, label } = instanceDisplay(instance);
   return inline ? (
     <StatusText tone={tone} label={label} />
   ) : (
diff --git a/apps/desktop/src/renderer/lib/activity-detail.test.ts b/apps/desktop/src/renderer/lib/activity-detail.test.ts
new file mode 100644
index 00000000..40cd1e28
--- /dev/null
+++ b/apps/desktop/src/renderer/lib/activity-detail.test.ts
@@ -0,0 +1,65 @@
+import { expect, test } from "vitest";
+import type { ActivityDetail, Snapshot } from "../../../../../packages/protocol/src/index.js";
+import type { RunnerProgress } from "../../../../../packages/protocol/src/runners.js";
+import { mergeActivityDetail } from "./activity-detail.js";
+
+test("opening an old activity restores its omitted steps without losing current machine state", () => {
+  const result: RunnerProgress = {
+    bindingId: "binding",
+    environmentId: "linux",
+    leaseKey: "root",
+    stage: "finished",
+    phases: [{ name: "vm_start", startedAt: "2020-01-01", endedAt: "2020-01-02" }],
+  };
+  const detail: ActivityDetail = {
+    activity: {
+      id: "old",
+      kind: "vectis",
+      subject: { type: "command", command: "runner.run" },
+      rootOperationId: "root",
+      status: "succeeded",
+      message: "Done",
+      createdAt: "2020-01-01",
+      updatedAt: "2020-01-02",
+    },
+    operations: ["root", "child"].map((id) => ({
+      id,
+      key: id,
+      activityId: "old",
+      command: "runner.run",
+      result,
+      status: "succeeded",
+      message: "Done",
+      createdAt: "2020-01-01",
+      updatedAt: "2020-01-02",
+    })),
+  };
+  const snapshot: Snapshot = {
+    protocolVersion: 1,
+    revision: "service:42",
+    machine: { id: "host", name: "Host", paused: false },
+    environments: [],
+    instances: [],
+    activities: [],
+    operations: [
+      {
+        id: "other",
+        key: "other",
+        activityId: "other",
+        command: "job.scan",
+        status: "running",
+        message: "Running",
+        createdAt: "2026-10-16",
+        updatedAt: "2026-10-16",
+      },
+    ],
+  };
+  const merged = mergeActivityDetail(snapshot, detail);
+  expect(merged.activities).toEqual([detail.activity]);
+  expect(merged.operations.map(({ id }) => id)).toEqual(["other", "child", "root"]);
+  expect(merged.operations.find(({ id }) => id === "root")?.result).toEqual(result);
+  expect(merged.revision).toBe(snapshot.revision);
+  expect(merged.machine).toBe(snapshot.machine);
+  expect(snapshot.activities).toEqual([]);
+  expect(mergeActivityDetail(merged, detail)).toEqual(merged);
+});
diff --git a/apps/desktop/src/renderer/lib/activity-detail.ts b/apps/desktop/src/renderer/lib/activity-detail.ts
new file mode 100644
index 00000000..7b316a67
--- /dev/null
+++ b/apps/desktop/src/renderer/lib/activity-detail.ts
@@ -0,0 +1,15 @@
+import type { ActivityDetail, Snapshot } from "../../../../../packages/protocol/src/index.js";
+
+export function mergeActivityDetail(snapshot: Snapshot, detail: ActivityDetail): Snapshot {
+  return {
+    ...snapshot,
+    activities: [
+      detail.activity,
+      ...(snapshot.activities ?? []).filter((activity) => activity.id !== detail.activity.id),
+    ],
+    operations: [
+      ...snapshot.operations.filter((operation) => operation.activityId !== detail.activity.id),
+      ...detail.operations.toReversed(),
+    ],
+  };
+}
diff --git a/apps/desktop/src/renderer/lib/capacity-mode.test.ts b/apps/desktop/src/renderer/lib/capacity-mode.test.ts
new file mode 100644
index 00000000..5e9fb1ed
--- /dev/null
+++ b/apps/desktop/src/renderer/lib/capacity-mode.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import type { MachineRepositories } from "../../../../../packages/protocol/src/repositories.js";
+import { scaleSetPresentation, scaleSetUnavailableReason } from "./capacity-mode";
+
+const binding: MachineRepositories[number] = {
+  id: "binding",
+  repositoryId: 1,
+  repositoryName: "acme/app",
+  environmentId: "linux",
+  automatic: true,
+  capacityMode: "scale_set",
+};
+
+describe("scaleSetUnavailableReason", () => {
+  it("blocks switching restricted policies to a scale set", () => {
+    const demand = { ...binding, capacityMode: "demand" as const };
+    expect(scaleSetUnavailableReason(demand)).toBeUndefined();
+    expect(
+      scaleSetUnavailableReason({
+        ...demand,
+        access: { actors: { ids: [7] }, approval: "automatic" },
+      }),
+    ).toBeDefined();
+    expect(
+      scaleSetUnavailableReason({ ...demand, access: { actors: "any", approval: "required" } }),
+    ).toBeDefined();
+  });
+
+  it("never blocks leaving a scale set", () => {
+    expect(
+      scaleSetUnavailableReason({ ...binding, access: { actors: "any", approval: "required" } }),
+    ).toBeUndefined();
+  });
+});
+
+describe("scaleSetPresentation", () => {
+  it("summarizes assigned jobs and reserved runners while listening", () => {
+    expect(
+      scaleSetPresentation(
+        binding,
+        { bindingId: "binding", state: "listening", assignedJobs: 2, reservedRunners: 1 },
+        false,
+      ),
+    ).toEqual({
+      tone: "running",
+      label: "Listening",
+      detail: "2 jobs assigned · 1 runner reserved",
+    });
+    expect(
+      scaleSetPresentation(binding, { bindingId: "binding", state: "listening" }, false).detail,
+    ).toBe("No jobs assigned");
+  });
+
+  it("explains why a scale set is not listening", () => {
+    expect(scaleSetPresentation({ ...binding, automatic: false }, undefined, false)).toMatchObject({
+      label: "Stopped",
+      detail: "Turn on Automatic to receive jobs.",
+    });
+    expect(
+      scaleSetPresentation(binding, { bindingId: "binding", state: "stopped" }, true).detail,
+    ).toBe("New VMs are paused. Resume them in Overview.");
+    expect(scaleSetPresentation(binding, undefined, false).label).toBe("Status unavailable");
+  });
+
+  it("surfaces action required with the service message", () => {
+    expect(
+      scaleSetPresentation(
+        binding,
+        {
+          bindingId: "binding",
+          state: "action_required",
+          code: "x",
+          message: "Check the binding.",
+        },
+        false,
+      ),
+    ).toEqual({ tone: "attention", label: "Action required", detail: "Check the binding." });
+  });
+});
diff --git a/apps/desktop/src/renderer/lib/capacity-mode.ts b/apps/desktop/src/renderer/lib/capacity-mode.ts
new file mode 100644
index 00000000..13a2dc35
--- /dev/null
+++ b/apps/desktop/src/renderer/lib/capacity-mode.ts
@@ -0,0 +1,73 @@
+import type { MachineRepositories } from "../../../../../packages/protocol/src/repositories.js";
+import type {
+  CapacityMode,
+  ScaleSetState,
+} from "../../../../../packages/protocol/src/scale-sets.js";
+import { restrictiveAccess } from "../../../../../packages/github/src/access-policy.js";
+import type { Tone } from "@/components/status";
+
+type Binding = MachineRepositories[number];
+
+export function capacityMode(binding: Binding): CapacityMode {
+  return binding.capacityMode ?? "demand";
+}
+
+// The cloud refuses scale sets for restricted policies because scale set messages carry neither
+// the workflow actor nor an approval decision.
+export function scaleSetUnavailableReason(binding: Binding): string | undefined {
+  if (capacityMode(binding) === "scale_set" || !restrictiveAccess(binding.access)) return undefined;
+  return "Scale sets need open access: anyone who can run workflows, with no approval step.";
+}
+
+export interface ScaleSetPresentation {
+  tone: Tone;
+  label: string;
+  detail?: string;
+}
+
+function count(value: number, noun: string) {
+  return `${value} ${noun}${value === 1 ? "" : "s"}`;
+}
+
+export function scaleSetPresentation(
+  binding: Binding,
+  state: ScaleSetState | undefined,
+  paused: boolean,
+): ScaleSetPresentation {
+  if (!binding.automatic && state?.state !== "listening")
+    return { tone: "idle", label: "Stopped", detail: "Turn on Automatic to receive jobs." };
+  if (!state) return { tone: "idle", label: "Status unavailable" };
+  switch (state.state) {
+    case "connecting":
+      return { tone: "queued", label: "Connecting" };
+    case "listening": {
+      const assigned = state.assignedJobs ?? 0;
+      const reserved = state.reservedRunners ?? 0;
+      return {
+        tone: "running",
+        label: "Listening",
+        detail: [
+          assigned === 0 ? "No jobs assigned" : `${count(assigned, "job")} assigned`,
+          ...(reserved > 0 ? [`${count(reserved, "runner")} reserved`] : []),
+        ].join(" · "),
+      };
+    }
+    case "action_required":
+      return {
+        tone: "attention",
+        label: "Action required",
+        detail:
+          state.code === "scale_set_policy_unsupported"
+            ? "Restricted access cannot use scale sets. Switch to Demand or open access."
+            : (state.message ?? "Scale set listening stopped."),
+      };
+    case "stopped":
+      return {
+        tone: "idle",
+        label: "Stopped",
+        detail: paused
+          ? "New VMs are paused. Resume them in Overview."
+          : "Not listening right now.",
+      };
+  }
+}
diff --git a/apps/desktop/src/renderer/lib/operations.ts b/apps/desktop/src/renderer/lib/operations.ts
index fcf31b41..b5aa3d18 100644
--- a/apps/desktop/src/renderer/lib/operations.ts
+++ b/apps/desktop/src/renderer/lib/operations.ts
@@ -1,5 +1,8 @@
+import { commandLabels as sharedCommandLabels } from "../../command-labels.js";
+
 export const preparationCommands = [
   "environment.prepare-linux",
+  "environment.provision",
   "environment.resume",
   "environment.install-macos",
   "environment.resume-macos",
@@ -19,6 +22,7 @@ export const cancellableCommands = [
   "environment.install-windows",
   "environment.resume-windows",
   "environment.prepare-linux",
+  "environment.provision",
   "environment.resume",
   "runner.run",
   "run.rerun-failed",
@@ -30,11 +34,19 @@ export const cancellableCommands = [
   "migration.publish",
   "repository.connect",
 ];
-export { commandLabels } from "../../command-labels.js";
+export const commandLabels: Record<string, string> = {
+  ...sharedCommandLabels,
+  "repository.cache": "Configure repository cache",
+  "cache.clear": "Clear repository cache",
+  "repository.capacity-mode": "Change runner capacity mode",
+};
 // A setting is confirmed after it happened, so its message is what changed, not what was asked.
 export const settingLabels: Record<string, string> = {
+  "repository.capacity-mode": "Runner capacity mode updated",
   "repository.automatic": "Automatic runners updated",
   "repository.access": "Repository access updated",
+  "repository.cache": "Repository cache updated",
+  "cache.clear": "Repository cache cleared",
   "environment.configure": "Environment updated",
   "environment.register": "Environment registered",
   "environment.remove": "Environment removed",
@@ -42,5 +54,5 @@ export const settingLabels: Record<string, string> = {
   "instance.reconcile": "VM reconciled",
   "operation.cancel": "Operation closed",
   "machine.pause": "VM intake updated",
-  "machine.configure": "Concurrent VMs updated",
+  "machine.configure": "VM capacity updated",
 };
diff --git a/apps/desktop/src/renderer/lib/result-code.test.ts b/apps/desktop/src/renderer/lib/result-code.test.ts
new file mode 100644
index 00000000..36f64a2e
--- /dev/null
+++ b/apps/desktop/src/renderer/lib/result-code.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { resultCodePresentation } from "./result-code";
+
+describe("result code presentation", () => {
+  it("labels images that cannot mount repository caches", () => {
+    expect(resultCodePresentation({ code: "cache_volume_requires_guest_sudo" })).toEqual({
+      tone: "attention",
+      label: "Cache needs a newer image",
+    });
+  });
+  it("reads GitHub outages and rate limits as an external condition", () => {
+    for (const code of ["github_unavailable", "github_rate_limited"]) {
+      expect(resultCodePresentation({ code, nextStep: "Wait and retry." })).toEqual({
+        tone: "attention",
+        label: "GitHub degraded",
+      });
+    }
+  });
+
+  it("labels runner recovery outcomes", () => {
+    expect(resultCodePresentation({ code: "runner_recovery_pending" })).toEqual({
+      tone: "attention",
+      label: "Recovering after restart",
+    });
+    expect(resultCodePresentation({ code: "runner_interrupted" })?.tone).toBe("cancelled");
+    expect(resultCodePresentation({ code: "runner_registration_failed" })?.tone).toBe("danger");
+    expect(resultCodePresentation({ code: "runner_offline" })?.label).toBe("Runner offline");
+  });
+
+  it("ignores unknown codes, local failures and non-objects", () => {
+    expect(resultCodePresentation({ code: "toString" })).toBeUndefined();
+    expect(resultCodePresentation({ code: "job_refresh_failed" })).toBeUndefined();
+    expect(resultCodePresentation("github_unavailable")).toBeUndefined();
+    expect(resultCodePresentation(undefined)).toBeUndefined();
+  });
+});
diff --git a/apps/desktop/src/renderer/lib/result-code.ts b/apps/desktop/src/renderer/lib/result-code.ts
new file mode 100644
index 00000000..0baccfb7
--- /dev/null
+++ b/apps/desktop/src/renderer/lib/result-code.ts
@@ -0,0 +1,18 @@
+import type { Tone } from "@/components/status";
+
+const codes: Record<string, readonly [Tone, string]> = {
+  cache_volume_requires_guest_sudo: ["attention", "Cache needs a newer image"],
+  github_unavailable: ["attention", "GitHub degraded"],
+  github_rate_limited: ["attention", "GitHub degraded"],
+  runner_recovery_pending: ["attention", "Recovering after restart"],
+  runner_interrupted: ["cancelled", "Interrupted"],
+  runner_registration_failed: ["danger", "Registration failed"],
+  runner_offline: ["danger", "Runner offline"],
+};
+
+export function resultCodePresentation(result: unknown) {
+  if (typeof result !== "object" || !result || !("code" in result)) return undefined;
+  if (typeof result.code !== "string" || !Object.hasOwn(codes, result.code)) return undefined;
+  const [tone, label] = codes[result.code]!;
+  return { tone, label };
+}
diff --git a/apps/desktop/src/renderer/lib/runner-phases.test.ts b/apps/desktop/src/renderer/lib/runner-phases.test.ts
new file mode 100644
index 00000000..a8a4af45
--- /dev/null
+++ b/apps/desktop/src/renderer/lib/runner-phases.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import { formatDuration, runnerPhaseTimeline } from "./runner-phases";
+
+const at = (seconds: number) => new Date(Date.UTC(2026, 0, 1) + seconds * 1000).toISOString();
+const phase = (name: string, start: number, end?: number) => ({
+  name,
+  startedAt: at(start),
+  ...(end === undefined ? {} : { endedAt: at(end) }),
+});
+const base = { stage: "finished", leaseKey: "key" };
+
+describe("formatDuration", () => {
+  it.each([
+    [40, "< 0.1 s"],
+    [100, "0.1 s"],
+    [5_800, "5.8 s"],
+    [9_960, "10 s"],
+    [32_400, "32 s"],
+    [59_600, "1 min"],
+    [72_000, "1 min 12 s"],
+    [3_600_000, "1 h"],
+    [3_960_000, "1 h 6 min"],
+  ])("formats %d ms as %s", (ms, text) => {
+    expect(formatDuration(ms)).toBe(text);
+  });
+});
+
+describe("runnerPhaseTimeline", () => {
+  it("ignores results without phases", () => {
+    expect(runnerPhaseTimeline(base, { end: 0, active: false })).toBeUndefined();
+    expect(runnerPhaseTimeline({ ...base, phases: [] }, { end: 0, active: false })).toBeUndefined();
+    expect(runnerPhaseTimeline(undefined, { end: 0, active: false })).toBeUndefined();
+  });
+
+  it("measures the span, not the sum, when idle checks overlap waiting", () => {
+    const timeline = runnerPhaseTimeline(
+      {
+        ...base,
+        phases: [
+          phase("vm_start", 0, 5.8),
+          phase("registration", 5.8, 8.4),
+          phase("waiting_for_job", 8.4, 40.4),
+          phase("job_check", 10, 10.5),
+          phase("job_check", 20, 20.5),
+          phase("job", 40.4, 55.4),
+          phase("cleanup", 55.4, 57.1),
+        ],
+      },
+      { end: 999_999, active: false },
+    );
+    expect(timeline?.total).toBe("57 s");
+    expect(timeline?.rows.map((row) => [row.label, row.duration, row.count])).toEqual([
+      ["VM start", "5.8 s", 1],
+      ["Registration", "2.6 s", 1],
+      ["Waiting for job", "32 s", 1],
+      ["Job check", "1.0 s", 2],
+      ["Job", "15 s", 1],
+      ["Cleanup", "1.7 s", 1],
+    ]);
+    const checks = timeline?.rows.find((row) => row.name === "job_check");
+    expect(checks?.segments).toHaveLength(2);
+    expect(checks?.segments[0]?.offset).toBeCloseTo(10 / 57.1);
+  });
+
+  it("runs an open phase until now while the runner is active", () => {
+    const result = { ...base, phases: [phase("vm_start", 0, 6), phase("waiting_for_job", 6)] };
+    const now = Date.parse(at(18));
+    const running = runnerPhaseTimeline(result, { end: now, active: true });
+    expect(running?.rows.at(-1)).toMatchObject({ state: "running", duration: "12 s" });
+    expect(running?.total).toBe("18 s");
+    expect(runnerPhaseTimeline(result, { end: now, active: false })?.rows.at(-1)?.state).toBe(
+      "unfinished",
+    );
+  });
+
+  it("keeps phases from a newer service readable and drops invalid timestamps", () => {
+    const timeline = runnerPhaseTimeline(
+      {
+        ...base,
+        phases: [phase("snapshot_restore", 0, 2), { name: "vm_start", startedAt: "soon" }],
+      },
+      { end: 0, active: false },
+    );
+    expect(timeline?.rows.map((row) => row.label)).toEqual(["Snapshot restore"]);
+  });
+});
diff --git a/apps/desktop/src/renderer/lib/runner-phases.ts b/apps/desktop/src/renderer/lib/runner-phases.ts
new file mode 100644
index 00000000..6e97fcd5
--- /dev/null
+++ b/apps/desktop/src/renderer/lib/runner-phases.ts
@@ -0,0 +1,120 @@
+import { Schema } from "effect";
+import type { PhaseName } from "../../../../../packages/protocol/src/runners.js";
+
+const labels = {
+  queued_locally: "Queued locally",
+  job_check: "Job check",
+  vm_start: "VM start",
+  warm_takeover: "Warm takeover",
+  vm_start_and_guest_ready: "VM start and guest ready",
+  guest_ready: "Guest ready",
+  runner_install: "Runner install",
+  runner_preinstalled: "Runner preinstalled",
+  registration: "Registration",
+  waiting_for_job: "Waiting for job",
+  job: "Job",
+  cleanup: "Cleanup",
+} as const satisfies Record<PhaseName, string>;
+
+// Names stay plain strings so a newer service's phases still render.
+const PhasesResult = Schema.Struct({
+  phases: Schema.Array(
+    Schema.Struct({
+      name: Schema.String,
+      startedAt: Schema.String,
+      endedAt: Schema.optional(Schema.String),
+    }),
+  ),
+});
+const isPhasesResult = Schema.is(PhasesResult);
+
+export type PhaseState = "done" | "running" | "unfinished";
+
+export interface PhaseRow {
+  name: string;
+  label: string;
+  count: number;
+  durationMs: number;
+  duration: string;
+  state: PhaseState;
+  segments: Array<{ offset: number; width: number }>;
+}
+
+export interface PhaseTimeline {
+  rows: PhaseRow[];
+  totalMs: number;
+  total: string;
+}
+
+export function formatDuration(ms: number) {
+  if (ms < 100) return "< 0.1 s";
+  const tenths = Math.round(ms / 100);
+  if (tenths < 100) return `${(tenths / 10).toFixed(1)} s`;
+  const seconds = Math.round(ms / 1000);
+  if (seconds < 60) return `${seconds} s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return seconds % 60 ? `${minutes} min ${seconds % 60} s` : `${minutes} min`;
+  const hours = Math.floor(minutes / 60);
+  return minutes % 60 ? `${hours} h ${minutes % 60} min` : `${hours} h`;
+}
+
+const knownLabels: Partial<Record<string, string>> = labels;
+
+function phaseLabel(name: string) {
+  const known = Object.hasOwn(knownLabels, name) ? knownLabels[name] : undefined;
+  if (known) return known;
+  const words = name.replaceAll("_", " ");
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+// An open phase runs until `end` while the runner is active; otherwise its end was never recorded.
+export function runnerPhaseTimeline(
+  result: unknown,
+  { end, active }: { end: number; active: boolean },
+): PhaseTimeline | undefined {
+  if (!isPhasesResult(result)) return undefined;
+  const spans = result.phases
+    .map((phase) => {
+      const start = Date.parse(phase.startedAt);
+      const recordedEnd = phase.endedAt === undefined ? Number.NaN : Date.parse(phase.endedAt);
+      const open = Number.isNaN(recordedEnd);
+      return {
+        name: phase.name,
+        start,
+        end: Math.max(start, open ? end : recordedEnd),
+        open,
+      };
+    })
+    .filter((span) => !Number.isNaN(span.start))
+    .sort((a, b) => a.start - b.start);
+  const first = spans[0];
+  if (!first) return undefined;
+  const totalMs = Math.max(...spans.map((span) => span.end)) - first.start;
+
+  const rows = new Map<string, PhaseRow>();
+  for (const span of spans) {
+    const row = rows.get(span.name) ?? {
+      name: span.name,
+      label: phaseLabel(span.name),
+      count: 0,
+      durationMs: 0,
+      duration: "",
+      state: "done",
+      segments: [],
+    };
+    row.count += 1;
+    row.durationMs += span.end - span.start;
+    if (span.open) row.state = active ? "running" : "unfinished";
+    row.segments.push(
+      totalMs > 0
+        ? { offset: (span.start - first.start) / totalMs, width: (span.end - span.start) / totalMs }
+        : { offset: 0, width: 0 },
+    );
+    rows.set(span.name, row);
+  }
+  return {
+    rows: [...rows.values()].map((row) => ({ ...row, duration: formatDuration(row.durationMs) })),
+    totalMs,
+    total: formatDuration(totalMs),
+  };
+}
diff --git a/apps/desktop/src/renderer/lib/vm-capacity.test.ts b/apps/desktop/src/renderer/lib/vm-capacity.test.ts
new file mode 100644
index 00000000..722a7d68
--- /dev/null
+++ b/apps/desktop/src/renderer/lib/vm-capacity.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import {
+  budgetLimits,
+  committedShare,
+  defaultBudgetMiB,
+  derivedImageDirectory,
+  instanceDisplay,
+  isPoolInstance,
+  pressureDisplay,
+  setupScriptTooLarge,
+  stepBudget,
+  type MemoryBudget,
+} from "./vm-capacity";
+
+const budget: MemoryBudget = {
+  memoryBudgetMiB: 24576,
+  memoryCommittedMiB: 8192,
+  hostMemoryMiB: 32768,
+  pressure: "normal",
+  pressureKnown: true,
+};
+
+describe("memory budget", () => {
+  it("stays between 2 GiB and host memory, which the service enforces", () => {
+    expect(budgetLimits(32768)).toEqual({ min: 2048, max: 32768 });
+    expect(stepBudget(2048, -1, 32768)).toBe(2048);
+    expect(stepBudget(32000, 1, 32768)).toBe(32768);
+    expect(stepBudget(13824, 1, 32768)).toBe(14848);
+  });
+
+  it("matches the service default of 75% of host memory", () => {
+    expect(defaultBudgetMiB(18432)).toBe(13824);
+    expect(defaultBudgetMiB(16383.9)).toBe(12287);
+  });
+
+  it("does not report normal pressure when the host cannot measure it", () => {
+    expect(pressureDisplay({ ...budget, pressureKnown: false }).tone).toBe("unsupported");
+    expect(pressureDisplay({ ...budget, pressure: "critical" }).tone).toBe("danger");
+    expect(pressureDisplay({ ...budget, pressure: "warning" }).tone).toBe("attention");
+    expect(pressureDisplay(budget).tone).toBe("success");
+  });
+
+  it("clamps the committed share for the meter", () => {
+    expect(committedShare(budget)).toBe(1 / 3);
+    expect(committedShare({ ...budget, memoryCommittedMiB: 40000 })).toBe(1);
+  });
+});
+
+describe("pool instances", () => {
+  it("labels warm VMs separately from job VMs", () => {
+    expect(instanceDisplay({ status: "running", role: "warm" }).label).toBe("Warm");
+    expect(instanceDisplay({ status: "starting", role: "warming" }).label).toBe("Warming");
+    expect(instanceDisplay({ status: "running" }).label).toBe("Running");
+  });
+
+  it("treats a stopped former pool VM as stopped, not warm", () => {
+    expect(isPoolInstance({ status: "stopped", role: "warm" })).toBe(false);
+    expect(instanceDisplay({ status: "stopped", role: "warm" }).label).toBe("Stopped");
+  });
+});
+
+describe("derived environments", () => {
+  it("measures the setup script limit in UTF-8 bytes", () => {
+    expect(setupScriptTooLarge("a".repeat(65536))).toBe(false);
+    expect(setupScriptTooLarge("é".repeat(32769))).toBe(true);
+  });
+
+  it("puts the image in a new folder inside the chosen one", () => {
+    expect(derivedImageDirectory("/Volumes/VMs/", "ubuntu-custom")).toBe(
+      "/Volumes/VMs/ubuntu-custom",
+    );
+    expect(derivedImageDirectory("/", "ubuntu-custom")).toBe("/ubuntu-custom");
+  });
+});
diff --git a/apps/desktop/src/renderer/lib/vm-capacity.ts b/apps/desktop/src/renderer/lib/vm-capacity.ts
new file mode 100644
index 00000000..bae4d148
--- /dev/null
+++ b/apps/desktop/src/renderer/lib/vm-capacity.ts
@@ -0,0 +1,64 @@
+import type { Instance, RunnerCapacity } from "../../../../../packages/protocol/src/index.js";
+import type { Tone } from "@/components/status";
+
+export type MemoryBudget = NonNullable<RunnerCapacity["budget"]>;
+
+const minimumBudgetMiB = 2048;
+const budgetStepMiB = 1024;
+
+export function budgetLimits(hostMemoryMiB: number) {
+  return { min: minimumBudgetMiB, max: Math.max(minimumBudgetMiB, Math.floor(hostMemoryMiB)) };
+}
+
+export function defaultBudgetMiB(hostMemoryMiB: number) {
+  return Math.floor(hostMemoryMiB * 0.75);
+}
+
+export function stepBudget(currentMiB: number, direction: 1 | -1, hostMemoryMiB: number) {
+  const { min, max } = budgetLimits(hostMemoryMiB);
+  return Math.min(max, Math.max(min, currentMiB + direction * budgetStepMiB));
+}
+
+export function pressureDisplay(budget: MemoryBudget): { tone: Tone; label: string } {
+  if (budget.pressureKnown === false) return { tone: "unsupported", label: "Pressure unknown" };
+  if (budget.pressure === "critical") return { tone: "danger", label: "Memory pressure critical" };
+  if (budget.pressure === "warning") return { tone: "attention", label: "Memory pressure high" };
+  return { tone: "success", label: "Memory pressure normal" };
+}
+
+export function committedShare(budget: MemoryBudget) {
+  if (budget.memoryBudgetMiB <= 0) return 0;
+  return Math.min(1, Math.max(0, budget.memoryCommittedMiB / budget.memoryBudgetMiB));
+}
+
+export function isPoolInstance(instance: Pick<Instance, "role" | "status">) {
+  return !!instance.role && (instance.status === "starting" || instance.status === "running");
+}
+
+export function instanceDisplay(instance: Pick<Instance, "role" | "status">): {
+  tone: Tone;
+  label: string;
+} {
+  if (isPoolInstance(instance))
+    return instance.role === "warm"
+      ? { tone: "idle", label: "Warm" }
+      : { tone: "queued", label: "Warming" };
+  const states = {
+    starting: { tone: "queued", label: "Starting" },
+    running: { tone: "running", label: "Running" },
+    stopped: { tone: "idle", label: "Stopped" },
+    interrupted: { tone: "attention", label: "Interrupted" },
+  } as const satisfies Record<Instance["status"], { tone: Tone; label: string }>;
+  return states[instance.status];
+}
+
+export const setupScriptLimitBytes = 65536;
+
+export function setupScriptTooLarge(script: string) {
+  return new TextEncoder().encode(script).length > setupScriptLimitBytes;
+}
+
+export function derivedImageDirectory(picked: string, id: string) {
+  const parent = picked.replace(/\/+$/, "");
+  return id ? `${parent}/${id}` : parent;
+}
diff --git a/apps/desktop/src/renderer/state.tsx b/apps/desktop/src/renderer/state.tsx
index 8935f76a..38c00f0b 100644
--- a/apps/desktop/src/renderer/state.tsx
+++ b/apps/desktop/src/renderer/state.tsx
@@ -3,11 +3,13 @@ import { createContext, useContext, useEffect, useRef, useState, type ReactNode
 import { Schema } from "effect";
 import {
   commandActivity,
+  ActivityDetail,
   Operation,
   Snapshot,
   type Command,
 } from "../../../../packages/protocol/src/index.js";
 import type { DesktopAction } from "../bridge.js";
+import { mergeActivityDetail } from "@/lib/activity-detail";
 import { activityTitle, openActivity } from "@/lib/activities";
 import { notify } from "@/lib/notify";
 import { commandLabels, settingLabels } from "@/lib/operations";
@@ -33,6 +35,7 @@ export async function readJobLogs(input: JobLogRequest, machineId?: string) {
 // Reads never change anything, so they never need the views to look again.
 const reads: ReadonlySet<DesktopAction> = new Set([
   "status",
+  "activity",
   "notifications.get",
   "jobs",
   "job.logs",
@@ -93,7 +96,14 @@ export function StateProvider({ children }: { children: ReactNode }) {
           const value = Schema.decodeUnknownSync(Snapshot)(
             await request("status", undefined, machineId),
           );
-          if (!stopped) setSnapshot(value);
+          const route = new URL(window.location.hash.slice(1), "http://localhost");
+          const id = route.pathname === "/activities" ? route.searchParams.get("id") : null;
+          const detail = id
+            ? await request("activity", id, machineId)
+                .then((reply) => Schema.decodeUnknownSync(ActivityDetail)(reply))
+                .catch(() => undefined)
+            : undefined;
+          if (!stopped) setSnapshot(detail ? mergeActivityDetail(value, detail) : value);
         } catch {
           if (!stopped) setSnapshot(null);
         }
@@ -113,11 +123,13 @@ export function StateProvider({ children }: { children: ReactNode }) {
       if (document.visibilityState === "visible") void refresh();
     };
     document.addEventListener("visibilitychange", wake);
+    window.addEventListener("hashchange", wake);
     void refresh();
     return () => {
       stopped = true;
       clearTimeout(timer);
       document.removeEventListener("visibilitychange", wake);
+      window.removeEventListener("hashchange", wake);
     };
   }, [machineId]);
   useEffect(() => {
@@ -211,3 +223,27 @@ export function useStateApi() {
   if (!state) throw new Error("Missing desktop state.");
   return state;
 }
+
+export function useActivityDetail(id: string, open: boolean) {
+  const { snapshot, machineId } = useStateApi();
+  const [detail, setDetail] = useState<{ machineId: string | undefined; value: ActivityDetail }>();
+  const revision = snapshot?.revision;
+  useEffect(() => {
+    if (!open) return;
+    let stopped = false;
+    void request("activity", id, machineId)
+      .then((reply) => {
+        const value = Schema.decodeUnknownSync(ActivityDetail)(reply);
+        if (!stopped) setDetail({ machineId, value });
+      })
+      .catch(() => {
+        if (!stopped) setDetail(undefined);
+      });
+    return () => {
+      stopped = true;
+    };
+  }, [id, open, machineId, revision]);
+  return detail?.machineId === machineId && detail?.value.activity.id === id
+    ? detail.value
+    : undefined;
+}
diff --git a/apps/desktop/src/renderer/views/environments.tsx b/apps/desktop/src/renderer/views/environments.tsx
index 5d7dd2ed..5293369e 100644
--- a/apps/desktop/src/renderer/views/environments.tsx
+++ b/apps/desktop/src/renderer/views/environments.tsx
@@ -15,7 +15,13 @@ import {
 } from "@/components/layout";
 import { Reason, Resources } from "@/components/hint";
 import { OsTile } from "@/components/os-icon";
-import { formatMemory } from "@/lib/format";
+import { formatDateTime, formatMemory } from "@/lib/format";
+import {
+  derivedImageDirectory,
+  isPoolInstance,
+  setupScriptLimitBytes,
+  setupScriptTooLarge,
+} from "@/lib/vm-capacity";
 import {
   canRestrictNetwork,
   initialDraft,
@@ -51,7 +57,7 @@ import {
 import { Switch } from "@/components/ui/switch";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { useStateApi } from "@/state";
-import { PrepareEnvironment, RegisterEnvironment } from "./prepare-environment";
+import { PrepareEnvironment, RegisterEnvironment, TextField } from "./prepare-environment";
 
 export function Environments() {
   const { snapshot, machineId } = useStateApi();
@@ -118,11 +124,17 @@ function EnvironmentRow({ environment }: { environment: EnvironmentView }) {
   const network = networkDisplay(environment);
   const { submit, snapshot } = useStateApi();
   const [configuring, setConfiguring] = useState(false);
-  const running = snapshot?.instances.filter(
+  const [deriving, setDeriving] = useState(false);
+  const active = (snapshot?.instances ?? []).filter(
     (instance) =>
       instance.environmentId === environment.id &&
       (instance.status === "starting" || instance.status === "running"),
-  ).length;
+  );
+  const warm = active.filter(isPoolInstance).length;
+  const running = active.length - warm;
+  const parentId = environment.image?.parentId;
+  const parentName = snapshot?.environments.find((item) => item.id === parentId)?.name;
+  const parent = parentName ?? parentId;
   return (
     <ExpandableRow
       id={environment.id}
@@ -132,6 +144,8 @@ function EnvironmentRow({ environment }: { environment: EnvironmentView }) {
         <span className="inline-flex items-center gap-3">
           <Resources cpu={environment.cpu} memoryMiB={environment.memoryMiB} />
           {!!running && <span>{running} running</span>}
+          {!!warm && <span>{warm} warm</span>}
+          {parent && <span>Derived from {parent}</span>}
         </span>
       }
       actions={
@@ -168,8 +182,15 @@ function EnvironmentRow({ environment }: { environment: EnvironmentView }) {
               <DropdownMenuItem onClick={() => setConfiguring(true)}>
                 Resources and storage…
               </DropdownMenuItem>
+              <DropdownMenuItem
+                disabled={environment.state !== "ready"}
+                onClick={() => setDeriving(true)}
+              >
+                Create derived environment…
+              </DropdownMenuItem>
             </DropdownMenuContent>
           </DropdownMenu>
+          <DeriveEnvironment parent={environment} open={deriving} onOpenChange={setDeriving} />
           <ConfigureEnvironment
             environment={environment}
             open={configuring}
@@ -178,6 +199,7 @@ function EnvironmentRow({ environment }: { environment: EnvironmentView }) {
         </>
       }
     >
+      <WarmPoolField environment={environment} />
       <Details
         items={[
           ["Guest", osNames[environment.os]],
@@ -189,6 +211,25 @@ function EnvironmentRow({ environment }: { environment: EnvironmentView }) {
             environment.os === "linux" && (environment.x64 === "rosetta" ? "Rosetta on" : "Off"),
           ],
           ["Environment ID", <Mono key="id">{environment.id}</Mono>],
+          [
+            "Derived from",
+            parentId &&
+              (parentName ? (
+                <span key="parent">
+                  {parentName} <Mono>{parentId}</Mono>
+                </span>
+              ) : (
+                <Mono key="parent">{parentId}</Mono>
+              )),
+          ],
+          [
+            "Runner",
+            environment.image &&
+              (environment.image.runnerVersion
+                ? `Preinstalled, version ${environment.image.runnerVersion}`
+                : "Not preinstalled"),
+          ],
+          ["Provisioned", environment.image && formatDateTime(environment.image.provisionedAt)],
           ["Base image", <Mono key="base">{environment.basePath}</Mono>],
           [
             "VM directory",
@@ -352,3 +393,188 @@ function ConfigureEnvironment({
     </Dialog>
   );
 }
+
+const warmPoolSizes = ["0", "1", "2", "3", "4"] as const;
+
+function WarmPoolField({ environment }: { environment: EnvironmentView }) {
+  const { submit } = useStateApi();
+  const saved = environment.warmPool ?? 0;
+  const [pending, setPending] = useState<number>();
+  const ready = environment.state === "ready";
+  const change = async (warmPool: number) => {
+    setPending(warmPool);
+    await submit(
+      { type: "environment.configure", id: environment.id, warmPool },
+      warmPool
+        ? `Warm pool for ${environment.name} set to ${warmPool}`
+        : `Warm pool for ${environment.name} turned off`,
+    );
+    setPending(undefined);
+  };
+  const label = `${environment.id}-warm-pool`;
+  return (
+    <div className="flex flex-wrap items-center justify-between gap-x-6 gap-y-2">
+      <div className="min-w-0">
+        <p id={label} className="text-sm font-medium">
+          Warm pool
+        </p>
+        <p className="mt-0.5 text-xs text-muted-foreground">
+          Keeps booted VMs waiting so jobs start faster. Each warm VM uses memory while idle and
+          never holds job credentials.
+        </p>
+      </div>
+      <Tabs
+        value={String(pending ?? saved)}
+        onValueChange={(value: string) => {
+          const size = Number(value);
+          if (size !== (pending ?? saved)) void change(size);
+        }}
+      >
+        <TabsList aria-labelledby={label}>
+          {warmPoolSizes.map((size) => (
+            <TabsTrigger
+              key={size}
+              value={size}
+              className="w-9 tabular-nums"
+              disabled={!ready || pending !== undefined}
+              aria-label={size === "0" ? "Off" : `${size} warm ${size === "1" ? "VM" : "VMs"}`}
+            >
+              {size === "0" ? "Off" : size}
+            </TabsTrigger>
+          ))}
+        </TabsList>
+      </Tabs>
+    </div>
+  );
+}
+
+function DeriveEnvironment({
+  parent,
+  open,
+  onOpenChange,
+}: {
+  parent: EnvironmentView;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-h-[calc(100vh-4rem)] overflow-y-auto sm:max-w-xl">
+        <DialogHeader>
+          <DialogTitle>Create derived environment</DialogTitle>
+          <DialogDescription>
+            Starts from a copy of {parent.name} and saves the result as a new environment.{" "}
+            {parent.name} itself does not change.
+            {parent.os === "windows" &&
+              " Windows also gets Git with GNU tar, zstd, PowerShell 7 and a Defender policy exclusion."}{" "}
+            Other VMs must be stopped while it is provisioned.
+          </DialogDescription>
+        </DialogHeader>
+        <DeriveEnvironmentForm parent={parent} onDone={() => onOpenChange(false)} />
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function DeriveEnvironmentForm({
+  parent,
+  onDone,
+}: {
+  parent: EnvironmentView;
+  onDone: () => void;
+}) {
+  const { submit } = useStateApi();
+  const [id, setId] = useState(`${parent.id}-custom`);
+  const [imageDirectory, setImageDirectory] = useState("");
+  const [setupScript, setSetupScript] = useState("");
+  const [runner, setRunner] = useState(true);
+  const [pending, setPending] = useState(false);
+  const tooLarge = setupScriptTooLarge(setupScript);
+  return (
+    <form
+      className="flex flex-col gap-5"
+      onSubmit={(event) => {
+        event.preventDefault();
+        if (tooLarge) return;
+        const data = new FormData(event.currentTarget);
+        const name = String(data.get("name") ?? "").trim();
+        setPending(true);
+        void submit({
+          type: "environment.provision",
+          id,
+          from: parent.id,
+          imageDirectory,
+          runner,
+          ...(name ? { name } : {}),
+          ...(setupScript.trim() ? { setupScript } : {}),
+        })
+          .then((value) => value !== undefined && onDone())
+          .finally(() => setPending(false));
+      }}
+    >
+      <fieldset disabled={pending} className="contents">
+        <FieldGroup className="gap-4">
+          <div className="grid grid-cols-2 gap-4">
+            <Field>
+              <FieldLabel htmlFor={`${parent.id}-derived-id`}>Environment ID</FieldLabel>
+              <Input
+                id={`${parent.id}-derived-id`}
+                required
+                pattern="[a-zA-Z0-9][a-zA-Z0-9_.-]{0,79}"
+                value={id}
+                onChange={(event) => setId(event.target.value)}
+              />
+            </Field>
+            <TextField label="Name" name="name" defaultValue={`${parent.name} (custom)`} required />
+          </div>
+          <PathField
+            label="Image directory"
+            chooser="chooseDirectory"
+            required
+            value={imageDirectory}
+            onChange={setImageDirectory}
+            fromChooser={(picked) => derivedImageDirectory(picked, id)}
+            description="A new folder for the image. Choosing a folder adds the environment ID as a new folder inside it."
+          />
+          <Field>
+            <FieldLabel htmlFor={`${parent.id}-setup-script`}>Setup script (optional)</FieldLabel>
+            <textarea
+              id={`${parent.id}-setup-script`}
+              value={setupScript}
+              onChange={(event) => setSetupScript(event.target.value)}
+              rows={6}
+              spellCheck={false}
+              aria-invalid={tooLarge || undefined}
+              placeholder="# Commands to run once in the guest"
+              className="min-h-24 w-full resize-y rounded-2xl border border-input bg-input/30 px-3 py-2 font-mono text-[12px] transition-colors outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-[3px] aria-invalid:ring-destructive/20"
+            />
+            <FieldDescription>
+              {tooLarge
+                ? `The script is larger than ${setupScriptLimitBytes / 1024} KiB.`
+                : `Runs once inside the guest with ${parent.os === "windows" ? "Windows PowerShell" : "bash"}. If it fails, no environment is created.`}
+            </FieldDescription>
+          </Field>
+          <Field orientation="horizontal">
+            <div className="flex flex-1 flex-col gap-1">
+              <FieldLabel htmlFor={`${parent.id}-derived-runner`}>Preinstall runner</FieldLabel>
+              <FieldDescription>
+                Installs the GitHub Actions runner version this Vectis release uses, so jobs skip
+                the download.
+              </FieldDescription>
+            </div>
+            <Switch
+              id={`${parent.id}-derived-runner`}
+              checked={runner}
+              onCheckedChange={setRunner}
+            />
+          </Field>
+        </FieldGroup>
+        <div className="flex justify-end">
+          <Button type="submit" disabled={tooLarge}>
+            Create environment
+          </Button>
+        </div>
+      </fieldset>
+    </form>
+  );
+}
diff --git a/apps/desktop/src/renderer/views/overview.tsx b/apps/desktop/src/renderer/views/overview.tsx
index 3d9be4f8..f41523c9 100644
--- a/apps/desktop/src/renderer/views/overview.tsx
+++ b/apps/desktop/src/renderer/views/overview.tsx
@@ -16,6 +16,7 @@ import {
 } from "@/components/ui/dropdown-menu";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import { formatRelative } from "@/lib/format";
+import { isPoolInstance } from "@/lib/vm-capacity";
 import { useStateApi } from "@/state";
 import { GetStarted } from "./get-started";
 import { ApproveJobButton, useAwaitingApprovals } from "./repository-jobs";
@@ -41,6 +42,8 @@ export function Overview() {
   const approvals = useAwaitingApprovals(snapshot?.repositories ?? []);
   const instances = snapshot?.instances ?? [];
   const running = instances.filter((instance) => ["starting", "running"].includes(instance.status));
+  const jobVms = running.filter((instance) => !isPoolInstance(instance));
+  const warm = running.length - jobVms.length;
   const interrupted = instances.filter((instance) => instance.status === "interrupted");
   // Every operation starts a VM, so the full list grows without bound. A VM that still runs or
   // needs cleanup always stays visible; the rest of the room goes to the newest finished ones.
@@ -125,14 +128,16 @@ export function Overview() {
         />
         <StatCard
           label="Virtual machines"
-          value={running.length}
-          tone={running.length ? "running" : undefined}
+          value={jobVms.length}
+          tone={jobVms.length ? "running" : undefined}
           detail={
             interrupted.length
               ? `${interrupted.length} need cleanup`
-              : running.length
-                ? "Running now"
-                : "None running"
+              : warm
+                ? `${warm} warm for faster starts`
+                : jobVms.length
+                  ? "Running now"
+                  : "None running"
           }
         />
         <StatCard
@@ -243,7 +248,7 @@ function InstanceRow({ instance }: { instance: Instance }) {
       title={environment?.name ?? instance.environmentId}
       detail={
         <span className="inline-flex items-center gap-1.5">
-          <InstanceStatus status={instance.status} inline />
+          <InstanceStatus instance={instance} inline />
           <span>· {formatRelative(instance.createdAt)}</span>
         </span>
       }
diff --git a/apps/desktop/src/renderer/views/repositories.tsx b/apps/desktop/src/renderer/views/repositories.tsx
index 219d70dc..981dcf99 100644
--- a/apps/desktop/src/renderer/views/repositories.tsx
+++ b/apps/desktop/src/renderer/views/repositories.tsx
@@ -32,6 +32,7 @@ import { readinessFailure, summarizeReadiness } from "@/lib/readiness";
 import { request, useStateApi } from "@/state";
 import { ConnectRepository } from "./connect-repository";
 import { RepositoryAccessEditor } from "./repository-access";
+import { RepositoryCapacity } from "./repository-capacity";
 import { RepositoryJobs } from "./repository-jobs";
 
 type Binding = MachineRepositories[number];
@@ -296,6 +297,26 @@ export function Repositories() {
                       })}
                     </div>
                   </Section>
+                  <Section
+                    title="Capacity"
+                    hint={
+                      <Hint label="About capacity modes">
+                        Demand starts a runner for each queued job. Scale set registers a GitHub
+                        runner scale set for this Mac, and GitHub assigns jobs to it. Workflows stay
+                        the same. Scale sets are a GitHub preview.
+                      </Hint>
+                    }
+                  >
+                    <div className="flex flex-col divide-y divide-border rounded-xl ring-1 ring-border ring-inset">
+                      {bindings.map((binding) => (
+                        <RepositoryCapacity
+                          key={binding.id}
+                          binding={binding}
+                          repositoryName={first.repositoryName}
+                        />
+                      ))}
+                    </div>
+                  </Section>
                   <Section title="Access">
                     {bindings.map((binding) => (
                       <RepositoryAccessEditor
diff --git a/apps/desktop/src/renderer/views/repository-access.tsx b/apps/desktop/src/renderer/views/repository-access.tsx
index e4254a14..8796737a 100644
--- a/apps/desktop/src/renderer/views/repository-access.tsx
+++ b/apps/desktop/src/renderer/views/repository-access.tsx
@@ -1,5 +1,6 @@
 import { useState } from "react";
 import { PlusIcon, XIcon } from "lucide-react";
+import { restrictiveAccess } from "../../../../../packages/github/src/access-policy.js";
 import type { MachineRepositories } from "../../../../../packages/protocol/src/repositories.js";
 import type { RepositoryAccess } from "../../../../../packages/protocol/src/repository-access.js";
 import { Mono } from "@/components/layout";
@@ -28,6 +29,7 @@ export function RepositoryAccessEditor({
   const [error, setError] = useState<string>();
   const [saving, setSaving] = useState(false);
   const ids = draft.actors === "any" ? [] : draft.actors.ids;
+  const blockedByScaleSet = binding.capacityMode === "scale_set" && restrictiveAccess(draft);
   function add() {
     const result = addActorId(ids, text);
     if ("error" in result) return setError(result.error);
@@ -148,6 +150,12 @@ export function RepositoryAccessEditor({
           Jobs wait under Needs you until you start them.
         </p>
       </div>
+      {blockedByScaleSet && (
+        <p className="text-xs text-attention">
+          This environment uses a scale set, which needs open access. Switch it to Demand under
+          Capacity first.
+        </p>
+      )}
       <div className="flex items-center justify-between gap-3">
         <p className="max-w-[52ch] text-xs text-muted-foreground">
           Vectis checks the job again inside the VM after GitHub assigns it and stops the runner if
@@ -155,7 +163,7 @@ export function RepositoryAccessEditor({
         </p>
         <Button
           size="sm"
-          disabled={saving || !canSaveAccess(saved, draft)}
+          disabled={saving || blockedByScaleSet || !canSaveAccess(saved, draft)}
           onClick={() => void save()}
         >
           {saving ? "Saving" : "Save access"}
diff --git a/apps/desktop/src/renderer/views/repository-capacity.tsx b/apps/desktop/src/renderer/views/repository-capacity.tsx
new file mode 100644
index 00000000..8f849f40
--- /dev/null
+++ b/apps/desktop/src/renderer/views/repository-capacity.tsx
@@ -0,0 +1,79 @@
+import { useState } from "react";
+import type { MachineRepositories } from "../../../../../packages/protocol/src/repositories.js";
+import type { CapacityMode } from "../../../../../packages/protocol/src/scale-sets.js";
+import { OsIcon } from "@/components/os-icon";
+import { StatusText } from "@/components/status";
+import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { capacityMode, scaleSetPresentation, scaleSetUnavailableReason } from "@/lib/capacity-mode";
+import { useStateApi } from "@/state";
+
+type Binding = MachineRepositories[number];
+
+export function RepositoryCapacity({
+  binding,
+  repositoryName,
+}: {
+  binding: Binding;
+  repositoryName: string;
+}) {
+  const { submit, snapshot } = useStateApi();
+  const [pending, setPending] = useState<CapacityMode>();
+  const environment = snapshot?.environments.find((item) => item.id === binding.environmentId);
+  const label = environment?.name ?? binding.environmentId;
+  const mode = pending ?? capacityMode(binding);
+  const unavailable = scaleSetUnavailableReason(binding);
+  const presentation =
+    capacityMode(binding) === "scale_set"
+      ? scaleSetPresentation(
+          binding,
+          snapshot?.scaleSets?.find((state) => state.bindingId === binding.id),
+          !!snapshot?.machine.paused,
+        )
+      : undefined;
+  async function change(next: CapacityMode) {
+    setPending(next);
+    try {
+      await submit(
+        { type: "repository.capacity-mode", bindingId: binding.id, mode: next },
+        `${repositoryName} on ${label} now uses ${next === "scale_set" ? "a scale set" : "demand capacity"}`,
+      );
+    } finally {
+      setPending(undefined);
+    }
+  }
+  return (
+    <div className="flex flex-wrap items-center gap-x-3 gap-y-2 px-3.5 py-3">
+      {environment && <OsIcon os={environment.os} className="size-4" />}
+      <span className="min-w-0 flex-1">
+        <span className="block truncate font-medium">{label}</span>
+        <span className="mt-0.5 block text-xs text-muted-foreground">
+          {presentation ? (
+            <>
+              <StatusText tone={presentation.tone} label={presentation.label} />
+              {presentation.detail && <span> · {presentation.detail}</span>}
+            </>
+          ) : (
+            "A runner starts for each queued job."
+          )}
+        </span>
+      </span>
+      <Tabs
+        value={mode}
+        onValueChange={(value: CapacityMode) => {
+          if (value !== mode) void change(value);
+        }}
+      >
+        <TabsList aria-label={`Capacity for ${label}`}>
+          <TabsTrigger value="demand" disabled={pending !== undefined}>
+            Demand
+          </TabsTrigger>
+          <TabsTrigger value="scale_set" disabled={pending !== undefined || !!unavailable}>
+            Scale set
+            <span className="text-[11px] font-normal text-muted-foreground">Preview</span>
+          </TabsTrigger>
+        </TabsList>
+      </Tabs>
+      {unavailable && <p className="basis-full text-xs text-muted-foreground">{unavailable}</p>}
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/views/settings.tsx b/apps/desktop/src/renderer/views/settings.tsx
index 13c3128c..12ae39f3 100644
--- a/apps/desktop/src/renderer/views/settings.tsx
+++ b/apps/desktop/src/renderer/views/settings.tsx
@@ -4,9 +4,17 @@ import { defaultMaxRunners } from "../../../../../packages/protocol/src/index.js
 import { List, Page, Row, Section } from "@/components/layout";
 import { Button } from "@/components/ui/button";
 import { Switch } from "@/components/ui/switch";
+import { StatusText } from "@/components/status";
 import { formatMemory } from "@/lib/format";
 import { notify } from "@/lib/notify";
 import { getNotificationsEnabled, setNotificationsEnabled } from "@/lib/notification-preferences";
+import {
+  budgetLimits,
+  committedShare,
+  defaultBudgetMiB,
+  pressureDisplay,
+  stepBudget,
+} from "@/lib/vm-capacity";
 import { useStateApi } from "@/state";
 
 const limits = { min: 1, max: 16 } as const;
@@ -81,6 +89,7 @@ export function Settings() {
                 detail={`Your largest environment, ${largest.name}, uses ${largest.cpu} CPUs and ${formatMemory(largest.memoryMiB)}. Lower its CPU or memory to run more jobs at once.`}
               />
             )}
+          <MemoryBudgetRow />
           <Row
             title="Take on new VMs"
             detail="When off, running jobs finish and nothing new starts."
@@ -105,6 +114,106 @@ export function Settings() {
   );
 }
 
+function MemoryBudgetRow() {
+  const { snapshot, submit } = useStateApi();
+  const budget = snapshot?.runnerCapacity?.budget;
+  const custom = snapshot?.machine.memoryBudgetMiB;
+  const saved = budget?.memoryBudgetMiB;
+  const [value, setValue] = useState(saved);
+  const [saving, setSaving] = useState(false);
+  useEffect(() => setValue(saved), [saved]);
+  if (!budget || value === undefined) return null;
+  const { min, max } = budgetLimits(budget.hostMemoryMiB);
+  const fallback = defaultBudgetMiB(budget.hostMemoryMiB);
+  const pressure = pressureDisplay(budget);
+  const save = async (memoryBudgetMiB: number, success: string) => {
+    setSaving(true);
+    await submit({ type: "machine.configure", memoryBudgetMiB }, success);
+    setSaving(false);
+  };
+  return (
+    <Row
+      title="VM memory budget"
+      detail="New VMs start only when their memory fits this budget and the Mac is not under memory pressure. Memory a VM does not use is not taken from the Mac, and VMs share CPU cores."
+      trailing={
+        <div className="flex items-center gap-2">
+          <Button
+            variant="secondary"
+            size="icon-sm"
+            aria-label="Lower memory budget"
+            disabled={value <= min}
+            onClick={() => setValue(stepBudget(value, -1, budget.hostMemoryMiB))}
+          >
+            <MinusIcon />
+          </Button>
+          <span className="w-14 text-center tabular-nums" aria-live="polite">
+            {formatMemory(value)}
+          </span>
+          <Button
+            variant="secondary"
+            size="icon-sm"
+            aria-label="Raise memory budget"
+            disabled={value >= max}
+            onClick={() => setValue(stepBudget(value, 1, budget.hostMemoryMiB))}
+          >
+            <PlusIcon />
+          </Button>
+          <Button
+            size="sm"
+            className="ml-2"
+            disabled={value === saved || saving}
+            onClick={() => void save(value, `VM memory budget set to ${formatMemory(value)}`)}
+          >
+            Save
+          </Button>
+        </div>
+      }
+    >
+      <div className="flex flex-col gap-2">
+        <div
+          role="meter"
+          aria-label="Committed VM memory"
+          aria-valuemin={0}
+          aria-valuemax={budget.memoryBudgetMiB}
+          aria-valuenow={Math.min(budget.memoryCommittedMiB, budget.memoryBudgetMiB)}
+          aria-valuetext={`${formatMemory(Math.round(budget.memoryCommittedMiB))} of ${formatMemory(budget.memoryBudgetMiB)}`}
+          className="h-1.5 overflow-hidden rounded-full bg-muted"
+        >
+          <div
+            className="h-full origin-left rounded-full bg-running transition-transform duration-300 ease-out motion-reduce:transition-none"
+            style={{ transform: `scaleX(${committedShare(budget)})` }}
+          />
+        </div>
+        <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground">
+          <span className="tabular-nums">
+            {formatMemory(Math.round(budget.memoryCommittedMiB))} of{" "}
+            {formatMemory(budget.memoryBudgetMiB)} committed to running VMs
+          </span>
+          <StatusText {...pressure} />
+          <span className="tabular-nums">
+            {custom === undefined
+              ? `Default, 75% of ${formatMemory(Math.round(budget.hostMemoryMiB))}`
+              : `Default is ${formatMemory(fallback)}`}
+          </span>
+          {custom !== undefined && custom !== fallback && (
+            <Button
+              variant="link"
+              size="xs"
+              className="h-auto px-0"
+              disabled={saving}
+              onClick={() =>
+                void save(fallback, `VM memory budget reset to ${formatMemory(fallback)}`)
+              }
+            >
+              Use default
+            </Button>
+          )}
+        </div>
+      </div>
+    </Row>
+  );
+}
+
 function NotificationsSection() {
   const [enabled, setEnabled] = useState<boolean>();
   useEffect(() => {
diff --git a/apps/docs/blume.config.ts b/apps/docs/blume.config.ts
index 96125081..2ccd6a62 100644
--- a/apps/docs/blume.config.ts
+++ b/apps/docs/blume.config.ts
@@ -66,6 +66,7 @@ export default defineConfig({
           { label: "Prepare Ubuntu", root: "guides/linux-setup" },
           { label: "Install macOS", root: "guides/macos-setup" },
           { label: "Install Windows (experimental)", root: "guides/windows-setup" },
+          { label: "Derive an environment", root: "guides/environments" },
           { label: "Storage and resources", root: "guides/storage" },
         ],
       },
diff --git a/apps/docs/docs/guides/agents.md b/apps/docs/docs/guides/agents.md
index 55dc43c9..c3106f1f 100644
--- a/apps/docs/docs/guides/agents.md
+++ b/apps/docs/docs/guides/agents.md
@@ -65,6 +65,8 @@ The skill is a plain [`SKILL.md`](https://github.com/kerddotdev/vectis/blob/main
 
 To let an agent control another Mac, sign in once with `vectis login` and start the server with `vectis-mcp --machine <machine-id>`. A remote session never falls back to the local Mac.
 
+`vectis_status` returns a compact summary: machine and cloud state, runner capacity, environments, non-stopped instances, counts within the status window, and the newest 20 operations and activities with shortened messages. It omits full operation results. Read `vectis_activities` for unfinished activities and the newest 100 terminal activities, `vectis_activity` for one retained activity and all its steps, or `vectis_operation` for a full result. These detail tools query individual records, locally and remotely, and remain available when a record falls outside the status window. Tool results are returned once in `structuredContent`, with an empty `content` array.
+
 ## Rules agents follow
 
 - Humans approve pairing, sign-in and GitHub linking in the browser. Agents hand over the link and wait.
diff --git a/apps/docs/docs/guides/app.md b/apps/docs/docs/guides/app.md
index a8079d44..b805b21a 100644
--- a/apps/docs/docs/guides/app.md
+++ b/apps/docs/docs/guides/app.md
@@ -39,3 +39,9 @@ After signing in under **Connections > Other Macs**, the machine switcher at the
 ## Updates
 
 The app updates itself from GitHub Releases and restarts the service only when it is idle. See [Updates](/docs/get-started/install#updates).
+
+## Machine resource settings
+
+**Settings** controls the concurrent runner limit (1 to 16, default 5). The shared VM memory budget is also configurable through `vectis machine configure --memory-budget-mib <N>`, independently or alongside `--max-runners <N>`. It defaults to 75 percent of host RAM and accepts 2048 MiB to total host RAM. Lowering it gates future starts without stopping current VMs.
+
+Environment CPU and memory values are per-VM ceilings. CPU overcommit is allowed; memory admission uses measured VM usage with startup floors, and warning or critical host memory pressure blocks new VMs. `vectis status --json` exposes `runnerCapacity.budget` for the effective budget, committed memory, host RAM and pressure, plus `pressureKnown` to distinguish unknown pressure. See [VM storage and resources](/docs/guides/storage#shared-memory-budget) for accounting and recommended ceilings.
diff --git a/apps/docs/docs/guides/environments.md b/apps/docs/docs/guides/environments.md
new file mode 100644
index 00000000..26bb7920
--- /dev/null
+++ b/apps/docs/docs/guides/environments.md
@@ -0,0 +1,67 @@
+---
+title: Derive an environment
+description: Provision a new immutable image from an existing ready environment.
+---
+
+`environment.provision` boots a writable clone of a ready environment, preinstalls the pinned GitHub Actions runner, runs an optional setup script once, shuts down the guest cleanly and registers a new environment. It preserves the parent's base image and runner label. Connect repositories to the new environment ID to use its tools.
+
+```sh
+vectis environment provision ubuntu-project --from ubuntu-24-arm64 \
+  --image-directory /absolute/path/to/images/ubuntu-project \
+  --name "Ubuntu project tools" \
+  --setup-script /absolute/path/to/setup.sh \
+  --wait --timeout 3600000 --json
+```
+
+The image directory must be a new absolute path with an existing writable parent directory. Vectis refuses existing files and directories, including empty ones. The derived environment inherits CPU, memory, disposable VM storage, guest access and effective network settings. Provisioning needs an idle, unpaused machine without unresolved runners or guest setups, and uses the normal VM resource and free-memory checks.
+
+Without `--setup-script`, provisioning only preinstalls the runner and prepares the image for cloning. `--no-runner` skips preinstallation and does not advertise a baked runner in the new manifest; jobs use the verified download fallback. Scripts are limited to 64 KiB of UTF-8. The CLI reads the file and sends its contents as data; the service uploads it into a guest file. Bash runs it as the SSH user on Linux and macOS. Windows uses `powershell.exe` (Windows PowerShell 5.1), not PowerShell Core or Bash. A nonzero script exit fails the operation.
+
+Linux and macOS preinstall the runner in the SSH user's home without requiring sudo. On Linux, provisioning checks the runner's linked libraries and the system libraries required by the pinned runner before attempting dependency installation. Prepared Vectis images already contain these dependencies, so provisioning skips the installer and its package index refresh. If libraries are missing, provisioning attempts the installer only after `sudo -n true` succeeds; otherwise it fails with a diagnostic explaining the missing dependencies and sudo permission. Installer failures are fatal, and a successful installation must pass the library checks again.
+
+Linux provisioning checks `sudo -n true` before uploading setup scripts or downloading the runner, including with `--no-runner`. It needs passwordless sudo for identity cleanup, as fresh Vectis images provide. Older Linux images without it fail with `provision_requires_guest_sudo` and next step: "Prepare a new Linux environment with this Vectis version, then provision from it." Vectis never requests a guest password. Do not put credentials into setup scripts: remote submissions pass through the cloud command queue.
+
+## Runner and image manifest
+
+New Linux and Windows preparations retain the pinned runner too. Linux and macOS use `$HOME/.vectis-runner/<version>`, and Windows uses `C:\vectis\runner\<version>`. Linux preparation downloads and extracts the runner in a `vectis` login environment, then runs the dependency installer as root. Downloads retry and verify SHA-256 before extraction. The guest account owns the runner directory so the disposable VM can configure and run it in place.
+
+Linux preparation reports script failures through a serial-console marker with the failing step and exit status. The host stops the guest and reports `action_required` with `guest_preparation_failed` instead of waiting for the overall one-hour limit. Failures and timeouts retain up to 4 KiB of redacted serial output in the operation result's `diagnostics`, available through `operation get --json`; timeouts use `preparation_timeout`. The private `preparation.log` retains a larger bounded log. Resume with `environment resume <setup-id>` after fixing the reported cause.
+
+The optional `Environment.image` manifest records `parentId`, a `revision`, `runnerVersion` when installed, and `provisionedAt`. When `runnerVersion` matches Vectis's pinned version, jobs start that runner directly without copying or downloading it. Existing environments without that manifest, and manifests for other runner versions, retain the verified download path and its 600-second install timeout. A manifest is an installation record, not evidence of a successful GitHub job.
+
+Linux provisioning clears the temporary guest's machine ID, D-Bus machine ID, SSH host keys and stored instance ID before shutdown. The root boot unit replaces SSH host keys and the instance ID from the read-only `VECTISIDENTITY` disk before SSH starts, but does not reset `/etc/machine-id`. A provisioning boot can persist that machine ID, so the privileged cleanup is required to prevent sharing it among clones. macOS retains the existing per-bundle machine identifier, hardware model, auxiliary storage and pinned SSH identity, as ordinary bundle clones already do. Windows retains its existing guest identity behavior. Network enforcement is inherited: Linux and macOS NAT do not filter egress; Windows defaults to enforced internet-only access.
+
+## Cancellation, cleanup and parents
+
+```sh
+vectis operation get <operation-id> --json
+vectis operation cancel <operation-id> --json
+vectis environment remove ubuntu-project --json
+```
+
+Shutdown first uses the hypervisor: Apple Virtualization `requestStop()` for Linux and macOS, or QMP `system_powerdown` for Windows. Neither requires guest sudo. Vectis waits for the VM process to exit successfully before freezing the image, with a two-minute shutdown timeout. Guest shutdown commands are only a fallback when the hypervisor request is unavailable, such as with an older Apple helper; that fallback requires guest shutdown permission. Acknowledging a shutdown request is not evidence that the VM stopped.
+
+The operation reports cloning, booting, waiting for the guest, Linux sudo verification, provisioning, Linux identity cleanup, shutdown and freezing stages. Cancellation stops the owned VM and deletes the partial output. Script failure or a shutdown timeout never registers the image. A forced stop is used only for failure, cancellation or a shutdown timeout, and its disk is discarded. A failed attempt can be retried with a new operation key after cleanup.
+
+Guest command failures retain `exitCode` and a redacted `diagnostics` string in the operation result, available through `operation get --json`. Diagnostics contain the last 4 KiB of stderr followed by the last 4 KiB of stdout, within the 16 KiB diagnostic limit. Step markers such as `vectis-provision: download` identify the failing preinstallation or shutdown step. Connection failures retain the available SSH diagnostic instead of inventing a guest exit code. Diagnostics remain available when cleanup needs attention or is retried after a restart. Treat diagnostic output as potentially sensitive even after redaction.
+
+After a service crash, Vectis retains ownership records and requires verified VM exit before removing partial files. If cleanup is unconfirmed, the operation reports `action_required` and provisioning continues to reserve the host. Reconcile the interrupted instance and restart the service to retry cleanup. A completed registration is recovered without deleting its image.
+
+Windows derived images use QCOW2 overlays with an absolute parent backing path, plus cloned UEFI variables and TPM state. Keep the parent's files in place. All operating systems refuse `environment.remove` for a parent with registered derived environments; remove descendants first. Removing a definition preserves its disk, so any retained Windows overlays still require their backing files even after unregistering.
+
+## CLI, MCP and remote control
+
+MCP's `vectis_command` accepts the same command:
+
+```json
+{
+  "type": "environment.provision",
+  "id": "ubuntu-project",
+  "from": "ubuntu-24-arm64",
+  "imageDirectory": "/absolute/path/on/host/images/ubuntu-project",
+  "setupScript": "set -eu\nprintf 'ready\\n' > \"$HOME/project-ready\"",
+  "runner": true
+}
+```
+
+Remote provisioning follows the existing preparation commands: `--machine <id>` selects the host, `--image-directory` is a path on that host, and `--setup-script` is read on the calling CLI machine before submission. Cancellation uses the same remote operation contract. The existing cloud queue limits the entire serialized command to 64 KiB, including JSON escaping and field overhead; near-limit setup scripts must be submitted locally. Desktop recognizes provisioning activity and cancellation; the environment provisioning form is separate UI work.
diff --git a/apps/docs/docs/guides/limits.md b/apps/docs/docs/guides/limits.md
index 8735fe75..718b5268 100644
--- a/apps/docs/docs/guides/limits.md
+++ b/apps/docs/docs/guides/limits.md
@@ -7,43 +7,53 @@ These values describe the current release. Settings you can change are marked as
 
 ## Runners and capacity
 
-| Limit                                                | Value                                                                                                |
-| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| Time a runner waits for and runs a job               | 6 hours                                                                                              |
-| Time allowed for installing the runner in the guest  | 10 minutes                                                                                           |
-| Concurrent VMs                                       | 5 by default, 1 to 16 with `vectis machine configure --max-runners` or **Concurrent VMs** in the app |
-| CPU used by all starting and running VMs together    | At most the host's CPU cores                                                                         |
-| Memory used by all starting and running VMs together | At most 75% of the host's memory                                                                     |
-| Concurrent macOS VMs                                 | 2 (an Apple limit)                                                                                   |
-
-An automatic runner also waits while an environment is being prepared, while an interrupted instance is unresolved, and while the Mac is paused. A runner that has been accepted holds its slot, and its CPU and memory, before its VM starts.
+| Limit                                                | Value                                                                                                  |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Time a runner waits for and runs a job               | 6 hours                                                                                                |
+| Time allowed for installing the runner in the guest  | 10 minutes                                                                                             |
+| Idle runner drain when capacity is no longer needed  | 5 minutes, including manual runners without a requested job                                            |
+| GitHub reports a listening runner offline or missing | 2 consecutive minutes                                                                                  |
+| Continuous runner status read failures               | 15 minutes before offline recovery                                                                     |
+| Automatic interrupted-runner cleanup                 | 24 hours, retry delays doubling from 1 minute to 30 minutes                                            |
+| Concurrent VMs                                       | 5 by default, 1 to 16 with `vectis machine configure --max-runners` or **Concurrent VMs** in the app   |
+| CPU ceiling per VM                                   | At most the host's CPU cores; summed vCPUs may exceed host cores                                       |
+| Shared VM memory admission budget                    | 75% of host RAM by default; `machine configure --memory-budget-mib` accepts 2048 MiB to total host RAM |
+| Startup memory estimate                              | Linux 2048 MiB; macOS and Windows 4096 MiB; capped by each VM's ceiling                                |
+| Host memory pressure                                 | Warning or critical blocks new starts; unknown is reported and treated as normal                       |
+| Concurrent macOS VMs                                 | 2 (an Apple limit)                                                                                     |
+
+An automatic runner also waits while an environment is being prepared, while the Mac is paused, or when unresolved instances leave insufficient capacity. A runner that has been accepted holds its slot and startup memory estimate before its VM starts. Each non-stopped VM commits the larger of its measured process RSS and startup estimate; failed measurements fall back to its configured ceiling. Probes are cached for five seconds. `runnerCapacity.budget` reports the effective memory budget, committed memory, host RAM, pressure and whether pressure is known. The budget gates admission; it does not reclaim memory or stop VMs that later grow beyond it.
 
 ## Environments
 
+The warm pool is opt-in: `environment configure <id> --warm-pool <N>` accepts 0 to 4, default 0. Idle pool VMs consume host RAM and disk space under the same admission budget and pressure gate as other VMs. Pool filling leaves one runner slot and a startup memory estimate free, so the actual size can be smaller than requested, including zero at a one-runner limit. Owned warm VMs yield to jobs and count as reclaimable capacity, while their memory stays visible in `runnerCapacity.budget`. They contain no runner registration, JIT configuration or job credentials. Idle VMs are recycled after 30 minutes and drained on pause, disable or service shutdown. See [Runners and jobs](/docs/guides/runners#optional-warm-pool).
+
 | Environment | Default CPU | Default memory | Default disk |
 | ----------- | ----------- | -------------- | ------------ |
 | Ubuntu      | 2           | 4096 MiB       | 32 GiB       |
 | macOS       | 2           | 4096 MiB       | 64 GiB       |
 | Windows     | 4           | 8192 MiB       | 96 GiB       |
 
-Override them with `--cpu`, `--memory-mib` and `--disk-gib`. Minimum disk sizes are 16 GiB for Ubuntu, 40 GiB for macOS and 64 GiB for Windows. A VM's memory can never exceed 75% of the host's memory. See [Storage and resources](/docs/guides/storage).
+Override them with `--cpu`, `--memory-mib` and `--disk-gib`. Minimum disk sizes are 16 GiB for Ubuntu, 40 GiB for macOS and 64 GiB for Windows. A VM's configured memory ceiling can never exceed 75% of host memory. Ceilings remain fixed for a running VM, but unused memory is allocated lazily and summed ceilings may exceed host RAM. For a suitable host, consider Linux 8 vCPUs / 12288 MiB, Windows 8 / 16384 MiB, and macOS 6 / 12288 MiB; preparation defaults are unchanged. See [Storage and resources](/docs/guides/storage).
 
 ## Cloud and automation
 
-| Limit                                             | Value                                             |
-| ------------------------------------------------- | ------------------------------------------------- |
-| Active runner leases per Mac                      | 100                                               |
-| Lifetime of a runner's just-in-time configuration | 15 minutes                                        |
-| Automatic runner attempts per job                 | 3                                                 |
-| Wait after a failed attempt                       | 60 seconds                                        |
-| Unclaimed automatic runner request, Mac offline   | Expires after 2 minutes                           |
-| Unclaimed automatic runner request, Mac online    | Expires after 10 minutes                          |
-| Scan for jobs Vectis missed                       | At most every 5 minutes per repository connection |
-| Jobs listed per repository connection             | The latest 100                                    |
-| Lines returned by one service log read            | At most 1000                                      |
-| Runner diagnostics                                | At most 16 KiB                                    |
-| Pairing requests                                  | Expire after 10 minutes                           |
-| Controller grants                                 | Expire after 90 days                              |
+| Limit                                              | Value                                             |
+| -------------------------------------------------- | ------------------------------------------------- |
+| Active runner leases per Mac                       | 100                                               |
+| Lifetime of a runner's just-in-time configuration  | 15 minutes                                        |
+| Automatic runner failures per job                  | 3                                                 |
+| Total automatic runner attempts per job            | 10                                                |
+| Wait after an action-required or missing operation | 10 minutes                                        |
+| Wait after a failed attempt                        | 60 seconds                                        |
+| Unclaimed automatic runner request, Mac offline    | Expires after 2 minutes                           |
+| Unclaimed automatic runner request, Mac online     | Expires after 10 minutes                          |
+| Scan for jobs Vectis missed                        | At most every 5 minutes per repository connection |
+| Jobs listed per repository connection              | The latest 100                                    |
+| Lines returned by one service log read             | At most 1000                                      |
+| Runner diagnostics                                 | At most 16 KiB                                    |
+| Pairing requests                                   | Expire after 10 minutes                           |
+| Controller grants                                  | Expire after 90 days                              |
 
 ## History and retention
 
diff --git a/apps/docs/docs/guides/linux-setup.md b/apps/docs/docs/guides/linux-setup.md
index 2e88fc7e..6879b42c 100644
--- a/apps/docs/docs/guides/linux-setup.md
+++ b/apps/docs/docs/guides/linux-setup.md
@@ -3,7 +3,7 @@ title: Prepare a Linux environment
 description: Download and prepare Ubuntu on an Apple Silicon Mac with resumable local setup.
 ---
 
-The guided Linux path creates an Ubuntu 24.04 ARM64 base image with a local `vectis` user, pinned SSH access, Git, Docker and the official runner's dependencies. It runs through the same local service from desktop, CLI and MCP. It requires an Apple Silicon Mac and the configured Apple helper, which runs the VM through Apple Virtualization. The service converts the downloaded disk itself; `qemu-img` is not needed.
+The guided Linux path creates an Ubuntu 24.04 ARM64 base image with a local `vectis` user, pinned SSH access, Git, Docker the pinned Actions runner and its dependencies. It runs through the same local service from desktop, CLI and MCP. It requires an Apple Silicon Mac and the configured Apple helper, which runs the VM through Apple Virtualization. The service converts the downloaded disk itself; `qemu-img` is not needed.
 
 Choose existing writable directories for base images and disposable VMs. They may be on an external drive. The image volume needs at least 8 GiB free; actual usage grows as software is installed. Virtual disk capacity is separate from allocated host storage.
 
@@ -33,7 +33,7 @@ A prepared image is a runner host, not a copy of a GitHub-hosted runner. GitHub'
 
 So a prepared guest has Git, Docker, OpenSSH and the official runner's dependencies, the archive and shell tools that actions invoke (`tar`, `gzip`, `xz-utils`, `zip`, `unzip`, `zstd`, `p7zip-full`, `jq`, `curl`, `wget`, `rsync`, `shellcheck`), a C and C++ toolchain with the headers native modules build against (`gcc`, `g++`, `make`, `pkg-config`, `autoconf`, `automake`, `libtool`, `libssl-dev`, `libsqlite3-dev`, `libicu-dev`), and the shared libraries prebuilt binaries link against, `libatomic1` among them. Two packages differ from GitHub's list: `p7zip-rar` is left out because it is non-free, and `netcat` and `upx` are installed under their real package names. The complete inventory of a prepared image is in the guest at `/etc/vectis/toolchain-versions.txt`.
 
-Deliberately absent: language runtimes and their version managers, databases, browsers and drivers, cloud CLIs, Android and Java SDKs. A job that needs one installs it in a step, or runs in a container with `container:` in the workflow, which works because the guest runs Docker. Nothing a job installs survives it, since every VM starts from the same base image, and the base image itself cannot be customized yet.
+Deliberately absent: language runtimes and their version managers, databases, browsers and drivers, cloud CLIs, Android and Java SDKs. A job that needs one installs it in a step, or runs in a container with `container:` in the workflow, which works because the guest runs Docker. Nothing a job installs survives it, since every VM starts from the same base image. To bake shared tools into a new base, [derive an environment](/docs/guides/environments) with `environment.provision`; the original stays immutable.
 
 Docker container jobs (`container:`) and service containers (`services:`) are supported on the Ubuntu environment and covered by the environment validation workflow.
 
@@ -72,3 +72,5 @@ A stopped or failed setup reports `action_required` and its durable `setupId`. P
 After a service crash, the previous guest must have verifiable process-exit evidence before its disk can be rewritten. Vectis will not kill an unrelated process or assume that a stored PID still belongs to it. The private `preparation.log` remains in the operation's reported image directory for diagnosis.
 
 Completed setup registers the environment automatically. It does not connect a repository or prove a GitHub job has run. Continue with [Repositories and labels](/docs/guides/repositories), then [Runners and jobs](/docs/guides/runners).
+
+New preparations retain the pinned runner under `$HOME/.vectis-runner/<version>` as the guest user and record it in `Environment.image`. Jobs use it directly when the recorded version matches. [Environment provisioning](/docs/guides/environments) requires passwordless sudo for Linux identity cleanup and checks it before any runner download or setup script upload. Older images without it fail with `provision_requires_guest_sudo`; prepare a new Linux environment with this Vectis version, then provision from it. Shutdown uses the hypervisor and does not require guest sudo.
diff --git a/apps/docs/docs/guides/macos-setup.md b/apps/docs/docs/guides/macos-setup.md
index 0b3ea6ee..8e586e50 100644
--- a/apps/docs/docs/guides/macos-setup.md
+++ b/apps/docs/docs/guides/macos-setup.md
@@ -63,7 +63,7 @@ A macOS guest is whatever you install in its setup console. Vectis restores Appl
 
 One thing is not optional. Without a developer toolchain the guest has no working `git`, so `actions/checkout` fails on its first step and almost no workflow gets further. Verification refuses such a guest and tells you what to install. While the setup console is open, either run `xcode-select --install` for Apple's Command Line Tools, which bring `git`, `clang`, `make` and the macOS SDK, or install the full Xcode and open it once to accept its license. Jobs that build with Xcode, sign, or need a specific Xcode version need the full install, not the Command Line Tools.
 
-Everything else follows the same rule as the other guests: `actions/setup-*` actions download toolchains at job time, and anything your jobs always need, such as Homebrew formulas or a specific Ruby, belongs in the guest before you register the environment, or in a workflow step.
+Everything else follows the same rule as the other guests: `actions/setup-*` actions download toolchains at job time, and anything your jobs always need, such as Homebrew formulas or a specific Ruby, can be installed once into a [derived environment](/docs/guides/environments) with `environment.provision`, or installed in a workflow step.
 
 ## Interruption and recovery
 
@@ -85,3 +85,15 @@ vectis environment discard-macos <setup-id> --environment <environment-id> --jso
 ```
 
 Desktop offers the same confirmation beside the setup operation. This deletes the current attempt's owned image directory, including its guest disk and setup logs. It preserves downloaded or supplied source IPSWs, registered environments, and older interrupted attempt directories. Active or registered setups and directories without matching ownership metadata cannot be discarded.
+
+## Provision an existing guest
+
+Use [environment provisioning](/docs/guides/environments) to create a new `base.bundle` from a ready macOS environment. The runner is installed without sudo under `$HOME/.vectis-runner/<version>`, and optional setup scripts run as the SSH user with Bash. Provisioning does not install Xcode or change the parent bundle.
+
+Provisioning uses this bounded shutdown sequence instead of the virtual power button, which can open a confirmation dialog in a logged-in macOS session:
+
+1. Over SSH as the guest user, run `osascript -e 'tell application "loginwindow" to «event aevtshut»'`, then wait up to 60 seconds for the VM to stop. Apple's SDK identifies `shut` as `kAEShutDown`; `rsdn` is `kAEShowShutdownDialog` and would request confirmation. The command does not invoke sudo. [Apple documents the loginwindow shutdown event](https://developer.apple.com/library/archive/qa/qa1134/_index.html), but whether macOS 26 accepts it from the SSH session without Automation/TCC consent has not been verified. Guest applications can also cancel shutdown.
+2. If the VM is still running and `sudo -n true` succeeds, run `sudo -n /sbin/shutdown -h now` and wait up to another 60 seconds. SSH enrollment does not grant passwordless sudo, and provisioning never prompts for a password.
+3. If the guest remains running, complete two separate `sync` commands over SSH, wait 5 seconds, then force-stop the owned provisioning VM through the Apple helper. Each SSH command and helper stop has a 30-second limit. A failed or timed-out sync prevents image registration; failed or cancelled provisioning removes its partial output after confirmed VM cleanup. Unconfirmed cleanup requires inspection.
+
+The final operation result reports `shutdown` as `loginwindow`, `sudo`, or `forced_stop_after_sync`. The last value explicitly means the image was frozen after a forced stop following two successful syncs, not after an observed clean guest shutdown. This fallback applies only to the derived provisioning image, never ordinary runner VMs or user data. Inspect it with `vectis operation get <operation-id> --json`.
diff --git a/apps/docs/docs/guides/remote-control.md b/apps/docs/docs/guides/remote-control.md
index 41fad62e..3f2cd174 100644
--- a/apps/docs/docs/guides/remote-control.md
+++ b/apps/docs/docs/guides/remote-control.md
@@ -37,7 +37,7 @@ vectis operation cancel <operation-id> --machine <machine-id> --json
 
 An accepted command is durably queued, not completed. Hosts claim commands and report execution separately. Retry the same request key only with the same command. Cancellation before delivery prevents execution; cancellation after delivery requires the host to observe the request and finish cleanup. Already completed operations keep their actual outcome.
 
-Automatic runner requests that remain unclaimed are checked after two minutes and cancelled if their machine is offline; an online machine has at most ten minutes to claim. The queued job can then be requested by another eligible machine on the next demand pass, within the existing three-attempt limit.
+Automatic runner requests that remain unclaimed are checked after two minutes and cancelled if their machine is offline; an online machine has at most ten minutes to claim. The queued job can then be requested by another eligible machine on the next demand pass, after a 60-second retry delay. Expiry counts toward the three-failure budget; successful runners serving other jobs do not. Automatic admission has a separate cap of ten total attempts per job. Action-required or deleted previous operations can retry after ten minutes; only action-required operations count as failures.
 
 Read-only requests require an online host. Their cloud responses are bounded and expire after 60 seconds. Completed command details are retrieved from the host; when it is offline, the cloud summary explicitly reports that the full result remains local. GitHub logs and artifacts retain normal GitHub behavior.
 
diff --git a/apps/docs/docs/guides/repositories.md b/apps/docs/docs/guides/repositories.md
index 9e42d3b5..6ace4c5e 100644
--- a/apps/docs/docs/guides/repositories.md
+++ b/apps/docs/docs/guides/repositories.md
@@ -30,6 +30,26 @@ Readiness returns ordered checks with a status, an optional error code, a next s
 
 `repository list` shows each connection's ID (the binding ID used by other commands) and its `runsOn` label. Connecting the same repository and environment again reuses the connection.
 
+## Capacity mode
+
+Connections default to `demand`, which starts capacity for individually admitted queued jobs. The preview `scale_set` mode lets this Mac long-poll one GitHub runner scale set session and create runners from GitHub's assigned-job level. Automatic runners must be enabled in either mode.
+
+```sh
+vectis repository capacity-mode <binding-id> scale-set
+vectis repository enable-auto <binding-id>
+vectis repository list --json
+vectis status --json
+```
+
+`repository list` includes `capacityMode`; listener state and error codes appear in `status.scaleSets`. Use the reported label or scale set name, and check the workflow against the preview integration before relying on it. See [scale set capacity](/docs/guides/runners#scale-set-capacity-preview) for lifecycle and verification limits.
+
+Scale set preview requires actors `any` and approval `automatic`. Keep restrictive policies in demand mode; switching to scale sets refuses unsupported policies with `scale_set_policy_unsupported`. GitHub's external pull request approval remains a maintainer decision. Pausing, disabling automatic runners, disconnecting or changing mode stops new scale set intake and attempts to close its session without interrupting running jobs.
+
+```sh
+vectis repository disable-auto <binding-id>
+vectis repository capacity-mode <binding-id> demand
+```
+
 ## Who can use this Mac
 
 Each connection can limit the numeric GitHub user IDs that may use its runner capacity, and require a manual start. Existing connections allow any actor and use automatic approval unless a policy is set. Automatic runner admission must still be enabled separately.
@@ -90,3 +110,58 @@ Private repositories must disable fork pull request workflows or enable **Requir
 **App:** the connection's menu, **Disconnect repository**. **Web:** **Disable connection**. **CLI:** `vectis repository disconnect <binding-id>`.
 
 Disconnecting stops new runners for that connection. Running jobs finish normally. The GitHub App installation and your workflows stay as they are; jobs that still ask for the label wait until another connection provides it.
+
+## Repository cache volumes
+
+Cache volumes are opt-in. A connection can retain tool downloads and package caches between jobs on the same machine and environment:
+
+```sh
+vectis repository cache enable <binding-id> --size-gib 20
+vectis repository cache disable <binding-id>
+vectis repository cache clear <binding-id>
+```
+
+The default size cap is 20 GiB; `--size-gib` accepts whole GiB from 1 to 1024. Omitting it preserves the binding's existing size, or uses 20 for a new setting. Disable affects future jobs and preserves the existing cache. To resize, disable, wait for running jobs to finish, clear, then enable with the new size. Clearing refuses active or unreconciled cache instances. Disconnecting a repository deletes its saved generations and prevents running forks from writing back. A disconnect made in the cloud is applied when the host receives the authoritative binding list, including after reconnecting.
+
+The host stores a sparse raw `cache.img` under `<environment-storage>/cache/<environment-id>/<installation-id>-<repository-id>/`. Without a custom storage path, environment storage is `<home>/instances`. Numeric installation and repository IDs establish ownership; repository names do not. Environments are isolated to keep guest filesystems separate. Each VM receives an APFS clone of the current generation as its own writable **block device** in the instance directory. The host never mounts the guest filesystem or shares a host folder with it. APFS clone support is required; there is no full-copy fallback. The cap applies to each disk's logical capacity, not the total host storage: concurrent forks, one retained previous generation and changed copy-on-write blocks can use additional space.
+
+First use formats the cache inside the guest. Linux identifies the `VECTISCACHE` virtio device, checks its size and that it has no mounted filesystems, formats blank disks as ext4, then mounts at `/vectis-cache`. macOS excludes the root APFS physical store, requires a single other physical disk with the exact configured size, and initializes only a blank disk as APFS at `/Volumes/VECTISCACHE`. Unknown layouts and unexpected existing filesystems fail closed. Windows identifies the separate NVMe disk by serial `VECTISCACHE`, excludes boot and system disks, checks its size and initializes only RAW disks as NTFS. Windows assigns an available drive letter. Guest setup requires passwordless `sudo` on Linux/macOS or an elevated Windows runner account.
+
+Cache-enabled runners check `sudo -n true` on Linux/macOS or the effective administrator token on Windows immediately after guest readiness, before runner installation or GitHub registration. Older Linux images may lack passwordless sudo even though they can run jobs without a cache. A failed privilege check ends the operation as `failed` with `cache_volume_requires_guest_sudo`, discards the private fork and leaves the saved generation intact. Prepare or provision a new environment with this Vectis version, or disable the repository cache.
+
+Vectis remembers the observed privilege result for that environment image and guest identity across service restarts. Repository readiness reports `cache.guest_sudo` as attention for a failed probe while caching is enabled; an unprobed image reports unknown. New image manifests or a different image path or guest identity require a fresh probe. Known failures stop subsequent local requests before VM startup. The cloud demand scheduler does not retry this failure for the same GitHub job ID, including after the environment is repaired: start a runner manually for the queued job or rerun the GitHub job to create new demand.
+
+Before the runner listener starts, it exports these paths to jobs:
+
+| Variable               | Directory inside the cache |
+| ---------------------- | -------------------------- |
+| `RUNNER_TOOL_CACHE`    | `toolcache`                |
+| `npm_config_cache`     | `npm`                      |
+| `npm_config_store_dir` | `pnpm`                     |
+| `YARN_CACHE_FOLDER`    | `yarn`                     |
+| `PIP_CACHE_DIR`        | `pip`                      |
+| `GOMODCACHE`           | `gomod`                    |
+| `GOCACHE`              | `go-build`                 |
+
+Workflows and setup actions can override these variables. Cargo is deliberately unchanged: `CARGO_HOME` also contains executables and configuration. The runner itself and the checkout remain on the disposable boot disk.
+
+### Write-back authority
+
+The cloud grants `cacheWrite: true` only for a known job whose workflow run is a `push`, `schedule`, or `workflow_dispatch`, targets the repository's current default branch, and has `head_repository.id` equal to the binding's repository ID. The demand runner's job ID identifies the stored workflow run ID before preparation. Vectis reads `/actions/runs/{run_id}` and the verified repository's `default_branch` with a repository-scoped Actions read token, separate from the runner administration token. The run's `head_branch` must match that default branch, its repository and head repository IDs must match the binding, and its attempt must match the known job attempt. Unreadable or missing metadata denies write-back. Pull requests, `pull_request_target`, forks, other branches and runners started without a specific job ID always discard their forks. Scale set runners have no known workflow run at prepare time and always receive `cacheWrite: false`, including when cache volumes are enabled. They can read the saved generation but discard their changes. The job-started hook fences writable grants to their run ID and attempt so another queued job cannot reuse that grant.
+
+The event allowlist is exact:
+
+| Workflow event                                                                                                              | Write-back                                                               |
+| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `push`                                                                                                                      | Allowed only on the current default branch with the same head repository |
+| `schedule`                                                                                                                  | Allowed only on the current default branch with the same head repository |
+| `workflow_dispatch`                                                                                                         | Allowed only on the current default branch with the same head repository |
+| Every other event, including `pull_request`, `pull_request_target`, `workflow_run`, `repository_dispatch` and `merge_group` | Denied                                                                   |
+
+Runner operation results include `cache.attached`, `cache.writeBack` (`granted` or `denied`), an optional bounded `cache.reason`, and `cache.promoted`. These fields are available in operation and activity reads through the CLI, MCP and remote clients. A granted write-back does not mean promotion succeeded. For example, `metadata_access_denied` identifies denied metadata access, `non_default_branch` identifies a branch mismatch, and `promotion_failed` identifies a host promotion error. `promoted: true` is recorded only after the fork replaces the saved generation; a later flush error can still require reconciliation.
+
+A writable fork becomes the new generation only after the listener finishes normally, the guest successfully unmounts or offlines the cache, and the VM process exits. The host flushes the fork, atomically promotes it, then deletes the instance directory. Runner failures, cancellation and guest connection loss before promotion leave the current generation intact. A cleanup error after the rename can report `promoted: true` while still requiring reconciliation. A failed workflow step can still populate the cache if the runner lifecycle and unmount complete normally. Promotions are serialized by the host and use atomic rename. Concurrent writers use **last-completed-promotion wins**; changes from parallel forks are not merged. One previous generation is retained, and a missing current image can recover from it. Crashed instances never replay a promotion: reconcile them through the normal instance and runner commands.
+
+A cache is shared job input, not a secret store. Any admitted job, including an approved pull request, can read the generation attached to its own fork. Keep credentials and sensitive artifacts out of cache directories. Cache write restrictions do not approve fork workflows or bypass GitHub's maintainer approval policy. These paths and scripts have synthetic test coverage; real Linux, macOS and Windows guest verification is still required before claiming native cache reuse.
+
+Repository cache jobs use a cold VM start so the private cache disk is attached before boot. They do not claim generic warm pool VMs; idle pool VMs yield when the job needs their capacity. Jobs without a cache volume can still use the warm pool.
diff --git a/apps/docs/docs/guides/runners.md b/apps/docs/docs/guides/runners.md
index b89c25c5..1a3246d3 100644
--- a/apps/docs/docs/guides/runners.md
+++ b/apps/docs/docs/guides/runners.md
@@ -3,7 +3,22 @@ title: Runners and jobs
 description: Automatic and manual runners, reading job results, cancelling and recovering.
 ---
 
-Every job runs on its own runner in its own VM. Vectis boots a copy of the environment, registers a GitHub runner that accepts exactly one job, runs it, then deletes the VM and the registration.
+Every job runs on its own runner in its own VM. Vectis boots a copy of the environment or takes over an unused warm VM, registers a GitHub runner that accepts exactly one job, runs it, then deletes the VM and the registration.
+
+## Optional warm pool
+
+Keep up to four pre-booted, SSH-ready VMs per environment to skip cloning, booting and waiting for SSH when a job arrives. The pool is opt-in and defaults to zero on Linux, macOS and Windows:
+
+```sh
+vectis environment configure <environment-id> --warm-pool 1 --wait
+vectis environment configure <environment-id> --warm-pool 0 --wait
+```
+
+Warm VMs use real host RAM and disk space while idle. They follow the shared memory budget, normal-pressure gate and macOS two-VM limit. Vectis leaves a runner slot and another startup estimate free, and does not fill the pool while a runner is waiting for a VM or preparation is busy. The requested size is an upper bound, not a capacity guarantee. With a one-runner limit, no warm VM is kept.
+
+Idle warm VMs have no runner registration, JIT configuration or job credentials. Registration happens only after a runner atomically takes over the VM and checks SSH. Unhealthy VMs are stopped before falling back to a cold start; used job VMs never return to the pool. `status` and MCP snapshots distinguish idle pool instances with `role: "warm"` and background startup with `role: "warming"`, separately from the VM's lifecycle status. They are not running jobs. Reported runner capacity treats owned pool VMs as reclaimable while the budget still reports their RAM usage.
+
+Idle warm VMs are stopped and replaced after 30 minutes. A real job can reclaim warm VMs belonging to other environments when it needs memory or a macOS slot. Pausing, disabling the pool or shutting down the service drains idle VMs; changing environment defaults replaces them. After a crash, pool VMs require the same confirmed-exit reconciliation as other interrupted instances.
 
 ## Automatic runners
 
@@ -14,14 +29,47 @@ vectis repository enable-auto <binding-id>
 vectis repository disable-auto <binding-id>
 ```
 
-With automatic runners on, the Mac looks for queued jobs that match the connection's label every heartbeat, about every 30 seconds, and scans GitHub for missed jobs at most every five minutes. It starts runners when it is connected and not paused, one per queued job, and a new job also starts one right away instead of waiting for the next heartbeat.
+In the default `demand` capacity mode, with automatic runners on, the Mac looks for queued jobs that match the connection's label every heartbeat, about every 30 seconds, and scans GitHub for missed jobs at most every five minutes. It starts runners when it is connected and not paused, one per queued job, and a new job also starts one right away instead of waiting for the next heartbeat.
+
+A Mac runs up to five runners at once by default; change it in **Settings** or with `vectis machine configure --max-runners <N>` (1 to 16). CPU and memory settings on an environment are per-VM ceilings. CPU ceilings may add up to more than the host's cores; each VM must still fit the host's core count. Memory admission uses a shared budget, defaulting to 75 percent of host RAM, rather than adding up the ceilings. Set it with `vectis machine configure --memory-budget-mib <N>` (2048 MiB to total host RAM).
 
-A Mac runs up to five runners at once by default; change it in **Settings** or with `vectis machine configure --max-runners <N>` (1 to 16). The Mac also never starts more than its CPU and memory allow: all running and starting VMs together get at most every CPU core and 75 percent of the memory, and at most two macOS VMs run at a time. It counts with your largest ready environment, so with a 6 CPU environment on a 14 core Mac two jobs run at once, whatever the limit says. `vectis status` and the Settings view show how many fit right now; give the environment fewer CPUs or less memory with `vectis environment configure` to run more.
+Each non-stopped VM commits the larger of its measured process RSS and a startup floor: 2048 MiB for Linux, 4096 MiB for macOS or Windows, capped by that VM's memory ceiling. Measurements are cached for five seconds. An unavailable footprint measurement uses the configured ceiling; a fresh VM without a PID reserves its startup estimate. Accepted runners reserve the estimate before boot, conservatively using the largest ready estimate until their environment is known. Starting another VM must fit that estimate into the remaining budget, and host memory pressure must be normal. Warning or critical pressure returns `memory_pressure`; a full budget returns `memory_budget_exceeded`. Unknown pressure is treated as normal and reported with `pressureKnown: false`.
 
-Before booting a VM, and again before registering the runner, Vectis checks with GitHub that the job is still queued. GitHub may hand the runner a different job with the same labels. If the original job is still queued after a runner succeeded, or a minute after it failed, Vectis starts another, at most three times per job. It never retries an interrupted or cancelled runner on its own, with one exception: a job that waits for an environment approval or a concurrency group gets a runner once GitHub queues it.
+Capacity is calculated separately for each ready environment. `vectis status --json` includes `runnerCapacity.environments` and `runnerCapacity.budget` with the effective budget, committed memory, host RAM and pressure. The overall available count is the maximum environment count, not their sum. macOS retains its shared two-VM limit. Interrupted VMs hold memory until verified stopped. An action-required runner whose VM is verified stopped releases its local slot while cleanup remains unresolved. Existing VMs continue running when pressure rises or the budget is lowered; the budget gates new starts rather than enforcing a hard runtime memory cap.
+
+Generous ceilings let a build grow when resources are available: for example Linux with 8 vCPUs / 12288 MiB, Windows with 8 / 16384 MiB, or macOS with 6 / 12288 MiB, when the host supports them. Unused guest memory is allocated lazily, so a ceiling is not an immediate reservation. Touched memory can remain allocated until the disposable VM exits. These are recommendations, not changes to preparation defaults.
+
+In demand mode, before booting a VM, and again before registering the runner, Vectis checks with GitHub that the job is still queued. GitHub may hand the runner a different job with the same labels. If the original job is still queued after a runner succeeded, Vectis can request another runner without consuming the failure budget. Automatic admission stops after three failures or ten total attempts per job. Failures include failed operations, requests that expire before claim, and action-required operations. Failed and expired requests wait 60 seconds before retrying; action-required operations wait ten minutes. A deleted previous operation can retry after ten minutes without inventing a failure. A person's cancellation stays final unless GitHub queues the job again after an approval or concurrency wait.
 
 Automatic runners are off until you turn them on, per connection. These CLI commands wait for the setting to be applied without needing `--wait`, and return a nonzero exit code if it fails or needs attention.
 
+## Scale set capacity (preview)
+
+Each repository connection chooses a capacity mode independently. `demand` uses per-job admission and is the default. `scale_set` uses GitHub's runner scale set queue, with one host-owned session per binding. Enable the preview with:
+
+```sh
+vectis repository capacity-mode <binding-id> scale-set
+vectis repository enable-auto <binding-id>
+vectis status --json
+```
+
+The host long-polls with a queue-scoped token. The cloud keeps the GitHub App key and opens, refreshes and closes sessions. The token never goes to a guest or appears in status. GitHub's `totalAssignedJobs` is the capacity level, not a count to add for each notification. The host subtracts this binding's accepted and running scale set requests and limits new requests to the environment's free local capacity. Request keys and message progress are persisted before acknowledgement so queue redelivery cannot repeat an accepted request.
+
+Scale set runners request JIT configuration for their session generation without a job ID. GitHub assigns the job after registration. They skip demand-mode per-job queued checks and drain after five idle minutes, after confirming they are not busy. Scale set reservations use the same per-environment slots as demand runners, including the shared memory budget and host pressure. Runners without cache volumes can take an idle warm pool VM; cache-enabled runners cold-start with their private cache disk attached. Scale set grants always have `cacheWrite: false` because the workflow run is unknown at prepare time; changes to their private cache forks are discarded. The same VM resource limits and guest isolation apply to Linux, macOS and Windows. Linux and macOS NAT do not enforce egress filtering; Windows defaults to enforced internet-only egress.
+
+Preview scale sets support only unrestricted actors with automatic approval. Actor allowlists and required manual capacity approval need demand mode; they report `scale_set_policy_unsupported` rather than weakening policy. GitHub's maintainer approval rules for external pull requests still apply. A conflicting session reports `scale_set_session_conflict`; Vectis does not take over another listener's session. Unsupported responses and authorization failures also leave the listener `action_required` with a code.
+
+`status.scaleSets` reports `connecting`, `listening`, `action_required` or `stopped` per binding, plus the last assigned level and reserved runners when known. MCP `vectis_status` includes the same listener states. A queue 401 triggers one serialized cloud token refresh and a retry; transient failures use abortable backoff and honor `Retry-After`.
+
+Pause, disable automatic runners, disconnect the repository or switch back to demand to stop polling and attempt to close the session. Existing jobs finish normally. A failed session close is bounded and best effort; GitHub may retain it until expiry. After resolving a listener error, disable and re-enable automatic runners to retry.
+
+```sh
+vectis repository disable-auto <binding-id>
+vectis repository capacity-mode <binding-id> demand
+```
+
+These are setting commands and wait for confirmation without `--wait`. The equivalent MCP command is `vectis_command` with `{key, command: {type: "repository.capacity-mode", bindingId, mode: "scale_set"}}`; the protocol uses `scale_set`, while the CLI uses `scale-set`. Remote commands replay through the same local service path.
+
 ## Manual runners
 
 Start one runner yourself with **Start runner** on the connection, or:
@@ -31,11 +79,40 @@ vectis runner run <binding-id> --key <any-unique-key> --json
 vectis runner run <binding-id> --job-id <github-job-id> --json   # only if that job is still queued
 ```
 
-A manual runner without a job ID waits up to six hours for a job.
+A manual runner without a job ID waits for work and drains after 5 idle minutes. The listener has a six-hour maximum lifetime, including job execution.
 
 An automatic runner request that the Mac does not pick up expires so another Mac connected to the same repository can take the job: after 2 minutes with result code `machine_offline` if the Mac went offline, or after 10 minutes with `claim_timeout` if it stayed online. The job is requested again on the next heartbeat.
 
-A runner requested for a specific job is drained after 10 minutes of inactivity if that job no longer needs queued capacity. Vectis stops the VM and releases the runner lease, reporting the operation as `cancelled` with result code `runner_idle`; busy runners and runners whose jobs still need queued capacity keep listening.
+Every runner is drained after 5 minutes of inactivity if its requested job no longer needs queued capacity. Manual runners without a requested job drain after the same idle window. Vectis confirms the runner is not busy, stops the VM and releases the lease, reporting `cancelled` with result code `runner_idle`. Busy runners and runners whose jobs still need queued capacity keep listening.
+
+A locally listening runner that GitHub reports offline or missing for 2 consecutive minutes is stopped with retryable failure code `runner_offline`. Continuous status read failures for 15 minutes trigger the same recovery. Cleanup must be confirmed before the operation ends; unconfirmed cleanup stays `action_required`.
+
+## Read phase timings
+
+Inspect a runner with `vectis operation get <operation-id> --json`, or use `vectis activity get <activity-id> --json` to include its child operations. The runner operation's `result.phases` retains phase timestamps as `stage` changes. CLI output is always JSON; `--json` makes it compact. MCP `vectis_operation` and `vectis_activity` return these details, locally and through remote inspection, including retained operations outside the status window. MCP `vectis_status` returns a compact summary without operation results or phase timestamps; use the detail tools to read timings.
+
+Each phase has a `name`, an ISO UTC `startedAt`, and an optional `endedAt`. Subtract the timestamps to get its duration: `00:00:00.000Z` to `00:00:12.300Z` is 12.3 seconds. A closed phase measures an attempt, including a failed or cancelled one; use the operation status to determine its outcome. A missing end means the phase is still running or was interrupted before its end was recorded. Older operations may have no phases.
+
+| Phase                      | Measured interval                                                                                                                                              |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `queued_locally`           | Local operation acceptance to lifecycle task start, including local admission checks. This excludes waiting in GitHub or the cloud.                            |
+| `job_check`                | One check that the requested job still needs capacity, before startup, before registration, or while idle.                                                     |
+| `vm_start`                 | The `environment.start` child, including validation, cloning and spawning, until it confirms the VM is running.                                                |
+| `warm_takeover`            | Claim an idle pool VM; followed by a `guest_ready` SSH health check.                                                                                           |
+| `vm_start_and_guest_ready` | Rosetta startup, including guest address discovery, pinned SSH readiness, clock and architecture checks, and Rosetta verification inside `environment.start`.  |
+| `guest_ready`              | Guest readiness and the pinned SSH connection. After `vm_start_and_guest_ready`, this is a readiness recheck; the initial wait is already included in startup. |
+| `runner_install`           | Downloading, verifying and extracting the runner.                                                                                                              |
+| `runner_preinstalled`      | The environment manifest matches the pinned runner version, so installation is skipped.                                                                        |
+| `registration`             | Preparing the GitHub JIT registration and validating its grant.                                                                                                |
+| `waiting_for_job`          | Registration end to the guest's job-started hook timestamp, or listener exit if no job is observed.                                                            |
+| `job`                      | The guest's job-started hook timestamp until the guest listener exits.                                                                                         |
+| `cleanup`                  | Stopping the VM and releasing the runner, including registration reconciliation attempted by this task. Later recovery retries are not included.               |
+
+Runners record `runner_preinstalled` instead of `runner_install` when the environment manifest matches the pinned runner version. After policy verification, the guest job-started hook atomically writes epoch milliseconds to `vectis-actions-runner/_vectis/job-started`. The existing policy gate poll reads it every 10 seconds and once after listener exit, without adding guest connections. A late marker corrects an earlier busy observation, including for short jobs that finish between polls. Guest readiness verifies clock skew is within 60 seconds; the hook timestamp is clamped between registration end and observation time, capped at listener exit when already known.
+
+If the marker is missing, invalid or unreadable, job timing falls back to GitHub's busy-status poll, normally every 30 seconds. That fallback uses the host's observation time and can miss short jobs. Bash uses GNU `date` milliseconds or Perl `Time::HiRes` on macOS; a timestamp failure leaves the policy decision unchanged and uses the busy fallback. Windows uses PowerShell 5.1-compatible .NET timestamp and file APIs. The measured start is the hook boundary, and the end is listener exit, including runner teardown. Clock skew still affects guest timestamps; never infer job success or an exact GitHub queue duration from these timings.
+
+History is bounded to 16 entries. When idle checks repeat, the oldest completed `job_check` entries are removed to preserve startup and cleanup. Idle checks overlap `waiting_for_job` or `job`; do not sum overlapping phases as total elapsed time.
 
 ## Read job results
 
@@ -44,7 +121,7 @@ A runner operation that succeeded means the VM ran and was cleaned up. It does n
 - **App:** open a connection in **Repositories** to see its recent jobs.
 - **CLI:** `vectis job list <binding-id> --json` returns the latest 100 jobs with their GitHub status and conclusion.
 
-Job states arrive through GitHub webhooks. If one seems missing or stale:
+Job states arrive through GitHub webhooks. Vectis checks for failed deliveries every two minutes and requests one automatic redelivery per webhook, usually recovering missed updates within a few minutes without a connected Mac. If one still seems missing or stale:
 
 ```sh
 vectis job scan <binding-id> --wait             # find queued and running jobs Vectis missed
@@ -114,7 +191,7 @@ An unreachable guest is reported as such, with SSH's reason (timeout, no route,
 
 ## Recover after a crash
 
-If the Mac or the service stopped abruptly, an operation or VM can end up `action_required`. Vectis never guesses: it cleans up only after it has evidence that the VM process exited.
+If the Mac or the service stopped abruptly, an operation or VM can end up `action_required`. Interrupted runner operations report `runner_recovery_pending`. On startup and during periodic recovery, Vectis checks the owned VM's exit evidence. Once the instance is stopped or absent, it reconciles the cloud lease and releases the registration automatically. A VM that may still be running, or an unconfirmed cloud release, keeps the operation unresolved.
 
 If deleting an owned VM's files fails after its process exits, Vectis retains an exit receipt so reconciliation can retry the file cleanup.
 
@@ -125,8 +202,10 @@ vectis runner reconcile <operation-id> --wait
 
 The app offers the same actions as **Reconcile** in **Overview**. Until an interrupted VM is reconciled, the Mac starts no new VMs and offers no runner slots. Do not start new runners to work around an unresolved one.
 
-For `runner_cleanup_required`, the service retries runner reconciliation about every minute while connected to the cloud, for up to 30 minutes from the operation's last update. A stopped runner can still be busy on GitHub, usually for up to 15 minutes until GitHub releases its job. `runner_busy` leaves cleanup unresolved until a later retry succeeds. Once the retry window expires, the operation remains `action_required` and you can reconcile it manually.
+For interrupted runners, `runner_registration_uncertain` and `runner_cleanup_required`, recovery retries while connected to the cloud, with delays of 1, 2, 4, 8, 16 and then 30 minutes, capped at 30 minutes. The retry schedule survives service restarts. After 24 hours, the operation remains `action_required` with a message and a next step for manual reconciliation. A stopped runner can still be busy on GitHub, usually for up to 15 minutes until GitHub releases its job; `runner_busy` leaves cleanup unresolved until a later retry succeeds.
 
-A refused assignment retains its policy reason during cleanup. After manual or automatic reconciliation succeeds, the runner operation ends as `failed` with `runner_assignment_rejected` and the original refusal message. Other interrupted runners end as `cancelled`; this does not establish the GitHub job result.
+A refused assignment retains its policy reason during cleanup. After manual or automatic reconciliation succeeds, the runner operation ends as `failed` with `runner_assignment_rejected` and the original refusal message. Offline runners retain `failed` with `runner_offline` after delayed cleanup. Other interrupted runners end as `cancelled` with `runner_interrupted`; this does not establish the GitHub job result. Requests interrupted before startup or registration began end as `failed` with `runner_interrupted`.
 
 Runner reconciliation also works when registration stopped before creating a cloud lease. After confirming VM cleanup, Vectis records the request as released in the cloud so a delayed registration cannot create a duplicate runner. If the cloud cannot confirm this, the operation stays unresolved.
+
+Registration failures confirmed to have no remaining cloud registration end as retryable `failed` with `runner_registration_failed`. A lost response is reconciled before retrying; unavailable reconciliation stays `action_required`. Approval-required results retain their existing manual next steps.
diff --git a/apps/docs/docs/guides/storage.md b/apps/docs/docs/guides/storage.md
index d75c8fce..4bd02683 100644
--- a/apps/docs/docs/guides/storage.md
+++ b/apps/docs/docs/guides/storage.md
@@ -45,7 +45,17 @@ Override just one start without changing defaults:
 vectis environment start ubuntu --cpu 2 --memory-mib 4096 --wait --json
 ```
 
-Running instances keep the resources and location they started with. Changing a path does not move existing disks. Vectis validates the per-instance request and the combined CPU and memory reservations. Memory reservations may use at most 75 percent of host RAM; startup also checks available memory.
+Running instances keep the resources and location they started with. Changing a path does not move existing disks. CPU and memory settings are per-VM ceilings, fixed until the VM stops. Vectis allows CPU overcommit: their sum may exceed host cores, while each VM must fit the host core count. Unused guest memory is allocated lazily. For a suitable host, generous ceilings such as Linux 8 vCPUs / 12288 MiB, Windows 8 / 16384 MiB, and macOS 6 / 12288 MiB let builds grow without reserving the full ceiling at admission. A single VM ceiling still cannot exceed 75 percent of host RAM.
+
+## Shared memory budget
+
+`vectis machine configure --memory-budget-mib 36864` sets the shared admission budget, for example 36 GiB on a 48 GiB host. The allowed range is 2048 MiB to total host RAM; an unset budget defaults to 75 percent of host RAM. Combine it with `--max-runners <N>` or change either independently. These machine settings persist across service restarts and apply to local, MCP and remote commands.
+
+Admission counts every non-stopped VM at the larger of its measured process RSS and a startup floor: 2048 MiB for Linux, 4096 MiB for macOS or Windows, capped by its memory ceiling. Fresh VMs without a PID and accepted runners reserve that estimate before boot. An unavailable measurement falls back to the configured ceiling. Footprints and host pressure are cached for five seconds.
+
+A new VM starts only if its estimate fits the remaining budget and host memory pressure is normal. Warning or critical returns `memory_pressure`; insufficient budget returns `memory_budget_exceeded`, both with next steps. Unknown pressure is treated as normal and exposed as `pressureKnown: false`. Startup separately checks available host memory against the same estimate, rather than the full ceiling. Inspect `vectis status --json` for `runnerCapacity.budget` and per-environment slots.
+
+This budget gates new starts; running VMs can grow beyond it and are not stopped when it is lowered or pressure rises. Memory touched by a guest may remain allocated until the disposable VM exits. Free host memory or stop idle VMs before retrying a refused start. The two-macOS-VM limit remains unchanged.
 
 If a selected directory disappears, Vectis reports `storage_unavailable`. Reconnect the drive before retrying. It does not silently recreate a missing selected directory on the system disk. Storage is currently identified by path, so verify that the intended drive is mounted there.
 
diff --git a/apps/docs/docs/guides/troubleshooting.md b/apps/docs/docs/guides/troubleshooting.md
index 0632bc0a..50d9a549 100644
--- a/apps/docs/docs/guides/troubleshooting.md
+++ b/apps/docs/docs/guides/troubleshooting.md
@@ -16,6 +16,8 @@ Start with `vectis repository readiness --binding <binding-id> --json` (MCP `vec
 7. **Can the GitHub App reach the repository?** The App must be installed on the owner with access to the repository. Link GitHub again on the connect page to refresh what Vectis sees.
 8. **Did Vectis miss the job?** Run `vectis job scan <binding-id> --wait`.
 
+Jobs with more than 100 labels or a label longer than 100 characters are recorded but cannot match Vectis runners. Unknown GitHub job statuses are retained as waiting until a scan or refresh supplies a known status.
+
 ## An operation failed or needs you
 
 Every operation ends with a status, a message and, when you need to act, a `nextStep`:
@@ -27,18 +29,28 @@ vectis logs --lines 200 --json
 
 Displayed logs, stored operation details and retained runner and preparation diagnostics redact recognized credentials.
 
+For slow runners, inspect `result.phases` on the runner operation, either directly or inside `vectis activity get <activity-id> --json`. Compare `vm_start`, `guest_ready`, `runner_install` and `registration` to find startup costs; `cleanup` measures the stop and release attempt. Each duration is `endedAt - startedAt`. A missing end is still running or interrupted, and older records may omit phases. Job timing starts at the first GitHub busy observation, normally polled every 30 seconds, so short jobs can be missed. These local timings do not measure the full GitHub queue. See [Read phase timings](/docs/guides/runners#read-phase-timings) for the complete phase list, overlap and retention rules.
+
 The app shows the same in **Overview** and the service log in **Diagnostics**. `action_required` means completion is unconfirmed; follow its `nextStep`. Runner cleanup may still be retried automatically.
 
+GitHub reads, runner deletion and installation token creation retry transient failures up to four attempts within a 45-second budget per request. Retries respect GitHub rate limit headers. `github_unavailable` means GitHub remained unavailable; `github_rate_limited` means the rate limit could not be cleared within that budget. Wait and retry. Side-effecting POST requests are never automatically retried; an ambiguous run command keeps `run_command_unconfirmed`, and an ambiguous runner registration still requires reconciliation.
+
 An operation that stays in **Needs you** after you have read it, usually because the service restarted before it finished, can be closed with **Dismiss** in the app or `vectis operation cancel <operation-id>`. It ends as `cancelled` and nothing else changes. Two cases keep their own way out instead: an interrupted runner is reconciled once its VM is confirmed stopped, and an image preparation is resumed or discarded.
 
-For `runner_cleanup_required`, Vectis retries cleanup about every minute while connected to the cloud, for up to 30 minutes from the operation's last update. GitHub can keep a stopped runner busy until it releases the job, usually within 15 minutes; `runner_busy` means cleanup must wait. Failed retries leave the operation `action_required` and preserve its original update time. After the retry window, or for other interrupted runner states, use `vectis runner reconcile <operation-id>` once the VM is confirmed stopped.
+After a restart, interrupted runners report `runner_recovery_pending`. Once the VM is verified stopped or absent, Vectis automatically reconciles the cloud lease and releases the runner. Recovery also covers `runner_cleanup_required` and `runner_registration_uncertain`. Connected retries use exponential backoff from 1 minute to 30 minutes for up to 24 hours, preserving the schedule across service restarts. GitHub can keep a stopped runner busy until it releases the job, usually within 15 minutes; `runner_busy` means cleanup must wait. An unconfirmed VM exit or cloud release keeps the operation `action_required`. After the retry window, use `vectis runner reconcile <operation-id>` once the VM is confirmed stopped; the result includes this next step.
 
-If Vectis refused the assigned job, the cleanup result keeps the original reason in `cause`. Successful reconciliation ends that runner operation as `failed` with `runner_assignment_rejected` and the original refusal message. Other interrupted runners end as `cancelled`; check GitHub separately for the job result.
+If Vectis refused the assigned job, the cleanup result keeps the original reason in `cause`. Successful reconciliation ends that runner operation as `failed` with `runner_assignment_rejected` and the original refusal message. Offline runners end as retryable `failed` with `runner_offline`, including after delayed cleanup. Other interrupted runners end as `cancelled` with `runner_interrupted`; check GitHub separately for the job result. A request interrupted before startup began ends as `failed` with `runner_interrupted`.
 
 `vectis status --json` groups related operations into `activities`. A preparation keeps one activity across setup attempts; a runner activity includes its VM start and cleanup. Preparation status follows the latest attempt, while a runner follows its root operation. A successful discard cancels the preparation activity; the discard operation itself stays `succeeded`. Operation IDs and request keys stay unchanged.
 
+Status includes every unfinished operation and activity, including `action_required`, plus the newest 100 terminal operations and 100 terminal activities. It includes every non-stopped instance and the newest 20 stopped instances. These are display windows, not the complete retained history. Use `vectis operation get <id> --json` or `vectis activity get <id> --json` for an older retained record; waits poll only the requested operation. `vectis activity list` reads activity summaries directly. The desktop fetches an opened activity's full steps separately.
+
+Stopped instance records older than 24 hours are removed beyond the newest 20, using their stop time when available and creation time for older records. This removes only stopped records, not guest files, unfinished work or request-key receipts. Replaying a retained stop request still returns its original operation; an expired operation's key remains reserved.
+
 Runner activities keep two separate optional facts: `subject.requestedJob` is the job that requested capacity, and `subject.actualJob` is the job observed on that registered runner. GitHub can assign a different job. Each may include `name`, `workflowName` and `htmlUrl` when GitHub provides them; a missing actual job means its identity is still unknown. Job failure does not make a successful runner lifecycle fail, and job success does not hide a cleanup failure.
 
+Idle runners drain after 5 minutes when their requested job no longer needs capacity; manual runners without a requested job use the same window. GitHub reporting offline or missing for 2 consecutive minutes, or continuous status read failures for 15 minutes, stops a listening runner with `runner_offline`. Registration attempts with confirmed cleanup can fail retryably with `runner_registration_failed`; unresolved registration still requires reconciliation.
+
 Actual job observation continues after the runner operation finishes and across service restarts. The service watches up to 20 of the newest eligible leases for activities created within the last 48 hours, stopping when the actual job completes. Already stored observations remain in activity history.
 
 Use `vectis activity cancel <activity-id> --json` to request cancellation of every background task that activity still owns, then inspect its final status. It can also close an activity that only waits for a person, with the same preparation and runner recovery restrictions as `operation cancel`. The command works through remote control and MCP too.
diff --git a/apps/docs/docs/guides/windows-setup.md b/apps/docs/docs/guides/windows-setup.md
index 9976ef56..3ebc8290 100644
--- a/apps/docs/docs/guides/windows-setup.md
+++ b/apps/docs/docs/guides/windows-setup.md
@@ -69,11 +69,60 @@ The service reports success only after checking guest ARM64 architecture, clock
 
 ## What the guest contains
 
-The recipe is designed to install Windows unattended. Preparation installs one thing a workflow cannot do without: Git. It downloads the pinned MinGit ARM64 build published by Git for Windows, the same portable build GitHub's own runner images use, verifies its SHA-256, unpacks it into `C:\Program Files\MinGit` and puts it on the machine `Path`. MinGit's configuration includes the standard `C:\Program Files\Git` configuration, so installing MinGit there would create a circular include. Without Git, `actions/checkout` cannot check out the repository. The installed version is recorded in the guest at `C:\ProgramData\Vectis\toolchain.json` together with the Windows build.
+Fresh installation and `environment provision` install the same pinned, SHA-256-verified Windows toolchain. Provisioning runs under Windows PowerShell 5.1 and requires an elevated guest administrator:
 
-The download uses basic parsing to avoid the [Windows PowerShell 5.1 web-content confirmation prompt](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-webrequest?view=powershell-5.1). It still verifies the pinned SHA-256 before extracting Git.
+- [Git for Windows 2.55.0.5 ARM64](https://github.com/git-for-windows/git/releases/tag/v2.55.0.windows.5), including Bash at `C:\Program Files\Git\bin\bash.exe` and GNU tar at `C:\Program Files\Git\usr\bin\tar.exe`. Bash and Git are on the machine PATH. The installer includes Git LFS; Bash and GNU tar are part of its base payload. Optional desktop integration and automatic Git updates are omitted.
+- [zstd 1.5.7](https://github.com/facebook/zstd/releases/tag/v1.5.7) at `C:\Program Files\zstd`, on the machine PATH. This release has no Windows ARM64 build, so Vectis uses the official x64 executable through Windows 11 ARM64's x64 emulation and verifies that it runs.
+- [PowerShell 7.6.6 ARM64](https://github.com/PowerShell/PowerShell/releases/tag/v7.6.6), installed by MSI at `C:\Program Files\PowerShell\7`, with `pwsh` on the machine PATH. Automatic Microsoft Update integration and PowerShell remoting are not enabled. Windows PowerShell 5.1 remains the provisioning shell.
 
-Everything else comes from the workflow. Windows 11 provides PowerShell, `curl` and `tar`; `actions/setup-*` actions download their own toolchains at job time; build tools, SDKs and package managers are a job's own step. Nothing a job installs survives it, because every VM starts from the same base image.
+The [Actions cache toolkit prefers GNU tar at the standard Git installation path](https://github.com/actions/toolkit/blob/main/packages/cache/src/internal/tar.ts), and uses zstd when available. Windows' built-in bsdtar remains available, but is not the cache toolkit's preferred executable after provisioning. In a lead-reported measurement on the same Windows 11 ARM64 guest with a 679 MB pnpm store, GNU tar with zstd compressed the store in 6.5-6.8 seconds, compared with 11.7-14.0 seconds for bsdtar with gzip. These are local archive compression timings, not end-to-end Actions cache save or restore timings.
+
+Existing MinGit files stay in `C:\Program Files\MinGit` for callers using absolute paths. Only its exact machine PATH entries (`cmd` and `bin`, ignoring case and trailing slashes) are removed. The full Git's `bin`, `cmd` and `usr\bin` entries take priority, and other machine PATH entries are preserved. MinGit is no longer installed in fresh images. PATH checks accept multiple matches and verify only the first resolved Git, Bash, tar, zstd and pwsh executable. Both full Git `bin\git.exe` and `cmd\git.exe` are accepted; tar must resolve to the installed GNU tar.
+
+Downloads use basic parsing to avoid the [Windows PowerShell 5.1 web-content confirmation prompt](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-webrequest?view=powershell-5.1), with bounded retries and SHA-256 verification before installation or extraction. Repeating provisioning checks the pinned versions and required binaries before deciding whether to install them again. Temporary downloads are removed even on failure.
+
+Languages, build tools, SDKs and package managers still come from workflow steps or a custom provisioning script. Nothing installed during a job survives that job's disposable VM.
+
+## Disposable guest performance settings
+
+Vectis configures a Microsoft Defender policy exclusion for the entire `C:\` drive inside the disposable Windows guest. It takes effect at the next boot, including with Tamper Protection enabled; it has no effect during the preparation boot that writes the policy. Realtime protection may remain enabled after reboot while excluding `C:\` from scanning.
+
+The VM boundary isolates the host from untrusted job code. Each job gets a fresh disposable VM, so reducing guest antivirus scanning is an acceptable performance tradeoff for this CI environment. Host protection stays enabled. Do not apply these settings to the host or a general-purpose Windows machine.
+
+AMSI can nondeterministically reject Defender-changing PowerShell cmdlets with `ScriptContainedMaliciousContent`. Even a single `Add-MpPreference -ExclusionPath 'C:\'` command that succeeded once was blocked later in the same guest. Separating cmdlets into individual processes is not reliable. Vectis therefore never uses `Add-MpPreference` or `Set-MpPreference` for configuration.
+
+Fresh installation and provisioning write only registry policies through individual `reg.exe` commands in `cmd.exe`, before the toolchain script. The fresh-install seed stores each command in a separate `.cmd` file. Both exclusion writes are required:
+
+```cmd
+reg.exe add "HKLM\SOFTWARE\Policies\Microsoft\Windows Defender\Exclusions" /v Exclusions_Paths /t REG_DWORD /d 1 /f
+reg.exe add "HKLM\SOFTWARE\Policies\Microsoft\Windows Defender\Exclusions\Paths" /v "C:\\" /t REG_SZ /d 0 /f
+```
+
+The realtime, behavior, IOAV, script and on-access protection policy keys, cloud reporting and sample submission policies remain best-effort writes. [Tamper Protection can block or silently ignore attempts to disable protection](https://learn.microsoft.com/en-us/defender-endpoint/tamper-protection-overview). Modern Defender ignores `DisableAntiSpyware`. Successful policy writes do not prove realtime protection is off.
+
+The mandatory toolchain manifest records `Defender.Mode: policy-exclusion`, `Defender.PolicyExclusionPath: ["C:\\"]` and `Defender.AppliesAt: next-boot`. These fields describe configuration intent, not an observed effective exclusion. Preparation does not depend on `Get-MpPreference` or `Get-MpComputerStatus`: before reboot, a missing effective exclusion is expected. Read-only checks remain useful after boot.
+
+Windows Update is disabled through `NoAutoUpdate` policy and `wuauserv`; Windows Search indexing (`WSearch`) and SysMain are disabled and stopped. Vectis also attempts to disable and stop Update Orchestrator (`UsoSvc`) and Update Medic (`WaaSMedicSvc`). Windows can protect those two services: blocked changes produce a warning and their actual state is recorded rather than reported as disabled. HVCI / Memory Integrity's `Enabled` value is set to `0` when present; running HVCI is recorded as requiring a reboot, and needs a real guest check after reboot.
+
+The toolchain steps emit `vectis-provision: <step>` markers. Versions, Windows build, next-boot Defender policy configuration, service states, Update policy and HVCI state are merged into `C:\ProgramData\Vectis\toolchain.json`, preserving unrelated manifest fields.
+
+### Verify the next boot
+
+Provisioning ends with a hypervisor shutdown, with a guest shutdown fallback, and confirms the VM has exited before registering the derived image. Fresh installation does not reboot inside the bootstrap script: `windows-installation` observes its prepared marker, verifies the runner, issues `shutdown.exe /s /t 3`, waits for the VM to exit, and only then writes `image.json` and finalizes the environment. Both paths therefore save a stopped image after writing the policy. Every job boots a new instance from that image, applying the exclusion at that boot. Tools and custom setup scripts running before this shutdown do not yet benefit from a newly written exclusion.
+
+Vectis removes the obsolete `Vectis-VerifySecurity` startup task and its script and receipts when provisioning existing images. It does not reapply Defender settings or verify them automatically at runner start. The manifest records preparation-time configuration, not proof of the current boot's state.
+
+After the lead boots a newly provisioned image or clone, check in the guest:
+
+```powershell
+Get-MpComputerStatus | Select-Object RealTimeProtectionEnabled, IsTamperProtected
+(Get-MpPreference).ExclusionPath
+Get-Content C:\ProgramData\Vectis\toolchain.json -Raw
+Get-Service wuauserv, UsoSvc, WaaSMedicSvc, WSearch, SysMain
+Get-CimInstance -Namespace 'root\Microsoft\Windows\DeviceGuard' -ClassName Win32_DeviceGuard | Select-Object SecurityServicesRunning
+```
+
+After boot, `ExclusionPath` should contain `C:\`; realtime protection may remain `True` with Tamper Protection enabled. The lead confirmed this policy exclusion after reboot in the same Windows 11 ARM64 guest: with a 679 MB pnpm store, `pnpm install` took 24.5 seconds with the exclusion versus 91-100 seconds without it. This is measured guest evidence for that setup, not a timing guarantee for every job. Check running HVCI and service states separately, and measure dependency installation and cache save/restore timings for the workload being evaluated.
 
 ## Interruption and recovery
 
@@ -84,8 +133,12 @@ vectis environment resume-windows <setup-id> --json
 
 Closing the desktop does not cancel the service operation. Cancellation preserves the owned disk for diagnosis and resume. The previous VM must have a matching exit receipt before another attempt is admitted. An uncertain process state blocks new VM starts.
 
-An interrupted operation reports `action_required` with the setup ID and private directory. Its `setup.ppm` screenshot and `preparation.log` can help diagnose guest setup failures. The preparation log contains host runtime output, not the guest PowerShell error. The bootstrap records its failing stage, error message and script line in `C:\ProgramData\Vectis\diagnostic.json`. When SSH remains reachable, Vectis saves a bounded copy as `bootstrap-diagnostic.json` in the private setup directory before stopping the VM. Only the known stage appears in the operation message; the detailed error stays local. Older setup media may have only the generic failure marker. Keep screenshots, diagnostics and setup credentials local.
+An interrupted operation reports `action_required` with the setup ID and private directory. Its `setup.ppm` screenshot and `preparation.log` can help diagnose guest setup failures. The preparation log contains host runtime output; guest command failures also emit a bounded full PowerShell error record to stderr. The bootstrap records its failing stage, error message and script line in `C:\ProgramData\Vectis\diagnostic.json`. When SSH remains reachable, Vectis saves a bounded copy as `bootstrap-diagnostic.json` in the private setup directory before stopping the VM. Only the known stage appears in the operation message; the detailed error stays local. Older setup media may have only the generic failure marker. Keep screenshots, diagnostics and setup credentials local.
 
 Resume uses the same setup identity and disk, not a second fresh installation. It regenerates setup media from the current service recipe and retries a failed bootstrap once if SSH is reachable. A new bootstrap attempt clears old completion and failure markers before running. A changed environment configuration requires a separate setup.
 
 If SSH cannot start or the firewall blocks it, automatic bootstrap retry cannot reach the guest. The setup may need human console recovery; repeatedly resuming does not fix unreachable SSH. Preserve the setup disk and inspect its screenshot and local diagnostics before deciding how to recover. Do not treat a stopped or unreachable guest as a completed environment, or disable pinned host-key checking to reach it.
+
+## Derive a prepared image
+
+Fresh Windows preparations preinstall the verified pinned Actions runner at `C:\vectis\runner\<version>` and record its version in `Environment.image`, so jobs start it in place. Existing ready environments can gain the runner or repository tools with [environment provisioning](/docs/guides/environments). Setup scripts run as the guest SSH user under Windows PowerShell 5.1 (`powershell.exe`). A derived disk is a QCOW2 overlay: keep its parent backing image in place and remove registered descendants before their parent.
diff --git a/apps/mcp/src/server.test.ts b/apps/mcp/src/server.test.ts
index 36cdb232..49a9e5fe 100644
--- a/apps/mcp/src/server.test.ts
+++ b/apps/mcp/src/server.test.ts
@@ -8,6 +8,72 @@ import { createMcpServer } from "./server.js";
 import { startService } from "../../server/src/http.js";
 import { VectisClient } from "../../../packages/client/src/index.js";
 import { VectisError } from "../../../packages/protocol/src/index.js";
+import { activityFor } from "../../server/src/activities.js";
+import type { RunnerProgress } from "../../../packages/protocol/src/runners.js";
+
+test("MCP detail reads preserve runner phases while status stays compact", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-mcp-phases-"));
+  const service = await startService({ home });
+  const api = new VectisClient(service.connection);
+  const server = createMcpServer(async () => api);
+  const client = new Client({ name: "phase-test", version: "1" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  try {
+    const command = { type: "runner.run", bindingId: "binding" } as const;
+    const operation = service.store.accept(
+      "runner",
+      "runner",
+      command.type,
+      activityFor("runner", command),
+      "runner",
+    ).operation;
+    const result: RunnerProgress = {
+      bindingId: "binding",
+      environmentId: "linux",
+      leaseKey: operation.id,
+      stage: "finished",
+      phases: [{ name: "vm_start", startedAt: operation.createdAt, endedAt: operation.createdAt }],
+    };
+    service.store.update(operation, { status: "succeeded", result });
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    expect(
+      await client.callTool({ name: "vectis_operation", arguments: { id: operation.id } }),
+    ).toMatchObject({
+      content: [],
+      structuredContent: { result: { result } },
+    });
+    expect(
+      await client.callTool({ name: "vectis_activity", arguments: { id: "runner" } }),
+    ).toMatchObject({
+      content: [],
+      structuredContent: { result: { operations: [expect.objectContaining({ result })] } },
+    });
+    const status = await client.callTool({ name: "vectis_status", arguments: {} });
+    expect(status.isError).not.toBe(true);
+    expect(status.content).toEqual([]);
+    expect(status).toHaveProperty("structuredContent.result.operations", [
+      {
+        id: operation.id,
+        activityId: "runner",
+        command: "runner.run",
+        status: "succeeded",
+        updatedAt: expect.any(String),
+        message: expect.any(String),
+      },
+    ]);
+    expect(JSON.stringify(status)).not.toContain('"phases"');
+    expect(status).toHaveProperty(
+      "structuredContent.result.details",
+      expect.stringContaining("vectis_operation"),
+    );
+  } finally {
+    await client.close();
+    await server.close();
+    await service.close();
+    await rm(home, { recursive: true, force: true });
+  }
+});
 
 test("MCP discovers and executes the same authenticated commands as the CLI client", async () => {
   const home = await mkdtemp(join(tmpdir(), "vectis-mcp-"));
@@ -47,7 +113,14 @@ test("MCP discovers and executes the same authenticated commands as the CLI clie
       discovered.find((tool) => tool.name === "vectis_command")?.inputSchema,
     );
     const discovery = await client.callTool({ name: "vectis_capabilities", arguments: {} });
-    for (const name of ["run.rerun-failed", "run.cancel", "workflow.dispatch"]) {
+    for (const name of [
+      "run.rerun-failed",
+      "run.cancel",
+      "workflow.dispatch",
+      "repository.cache",
+      "cache.clear",
+      "repository.capacity-mode",
+    ]) {
       expect(schema).toContain(name);
       expect(JSON.stringify(discovery.structuredContent)).toContain(name);
     }
@@ -315,3 +388,81 @@ test("MCP job logs forwards the byte cursor and rejects invalid requests", async
     await rm(home, { recursive: true, force: true });
   }
 });
+
+test("MCP status bounds retained history and returns data only once", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-mcp-bounded-"));
+  const snapshotLimits = { operations: 21, activities: 21, stoppedInstances: 2 };
+  const service = await startService({ home, snapshotLimits });
+  const api = new VectisClient(service.connection);
+  const server = createMcpServer(async () => api);
+  const client = new Client({ name: "bounded-status-test", version: "1" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  try {
+    const command = { type: "job.scan", bindingId: "binding" } as const;
+    service.store.db.exec("BEGIN IMMEDIATE");
+    for (let index = 0; index < snapshotLimits.operations + 2; index++) {
+      const id = `history-${index}`;
+      const link = activityFor(id, command);
+      service.store.put("activity", id, link?.create);
+      service.store.put("operation", id, {
+        id,
+        key: id,
+        command: command.type,
+        activityId: id,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        status: index === 0 ? "action_required" : "succeeded",
+        result: { largeResult: "x".repeat(4096) },
+        message: "x".repeat(1024),
+      });
+    }
+    service.store.db.exec("COMMIT");
+    expect(Buffer.byteLength(JSON.stringify(await api.status()))).toBeGreaterThan(64 * 1024);
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    const result = await client.callTool({ name: "vectis_status", arguments: {} });
+    expect(result.isError).not.toBe(true);
+    expect(result.content).toEqual([]);
+    expect(Buffer.byteLength(JSON.stringify(result))).toBeLessThan(64 * 1024);
+    expect(result).toMatchObject({
+      structuredContent: {
+        result: {
+          operations: expect.any(Array),
+          activities: expect.any(Array),
+          counts: {
+            operations: { total: 22, byStatus: { action_required: 1, succeeded: 21 } },
+            activities: { total: 22, byStatus: { action_required: 1, succeeded: 21 } },
+          },
+          details: expect.stringContaining("vectis_operation"),
+        },
+      },
+    });
+    expect(result).toHaveProperty("structuredContent.result.operations.length", 20);
+    expect(result).toHaveProperty("structuredContent.result.activities.length", 20);
+    expect(JSON.stringify(result)).not.toContain("largeResult");
+    const status = vi.spyOn(api, "status").mockRejectedValue(new Error("Unexpected status read"));
+    const activities = await client.callTool({
+      name: "vectis_activities",
+      arguments: { status: "action_required" },
+    });
+    expect(activities).toMatchObject({
+      content: [],
+      structuredContent: { result: [{ id: "history-0" }] },
+    });
+    expect(status).not.toHaveBeenCalled();
+    status.mockRestore();
+    const full = await client.callTool({
+      name: "vectis_operation",
+      arguments: { id: "history-0" },
+    });
+    expect(full).toMatchObject({
+      content: [],
+      structuredContent: { result: { result: { largeResult: expect.any(String) } } },
+    });
+  } finally {
+    await client.close();
+    await server.close();
+    await service.close();
+    await rm(home, { recursive: true, force: true });
+  }
+});
diff --git a/apps/mcp/src/server.ts b/apps/mcp/src/server.ts
index 4a1d4d24..a5062a49 100644
--- a/apps/mcp/src/server.ts
+++ b/apps/mcp/src/server.ts
@@ -11,6 +11,7 @@ import {
   Identifier,
   capabilities,
   VectisError,
+  type Snapshot,
 } from "../../../packages/protocol/src/index.js";
 import { githubConnection } from "../../../packages/client/src/github.js";
 import {
@@ -47,6 +48,73 @@ const activitiesInput = Schema.Struct({
 const activitiesSchema = Schema.toJsonSchemaDocument(activitiesInput);
 const activitySchema = Schema.toJsonSchemaDocument(operationInput);
 const logSchema = Schema.toJsonSchemaDocument(LogRequest);
+const statusHistoryLimit = 20;
+
+function compactStatus(snapshot: Snapshot) {
+  const activities = snapshot.activities ?? [];
+  const counts = (items: readonly { status: string }[]) => {
+    const statuses: Record<string, number> = {};
+    for (const item of items) statuses[item.status] = (statuses[item.status] ?? 0) + 1;
+    return { total: items.length, byStatus: statuses };
+  };
+  return {
+    protocolVersion: snapshot.protocolVersion,
+    version: snapshot.version,
+    revision: snapshot.revision,
+    machine: snapshot.machine,
+    cloud: snapshot.cloud,
+    runnerCapacity: snapshot.runnerCapacity,
+    ...(snapshot.scaleSets === undefined ? {} : { scaleSets: snapshot.scaleSets }),
+    preparationBusy: snapshot.preparationBusy,
+    environments: snapshot.environments.map(({ id, name, os, state, cpu, memoryMiB, network }) => ({
+      id,
+      name,
+      os,
+      state,
+      cpu,
+      memoryMiB,
+      network,
+    })),
+    instances: snapshot.instances
+      .filter((instance) => instance.status !== "stopped")
+      .map(({ id, environmentId, status, createdAt }) => ({
+        id,
+        environmentId,
+        status,
+        createdAt,
+      })),
+    counts: {
+      scope: "bounded status window",
+      operations: counts(snapshot.operations),
+      activities: counts(activities),
+      instances: counts(snapshot.instances),
+    },
+    operations: [...snapshot.operations]
+      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+      .slice(0, statusHistoryLimit)
+      .map(({ id, activityId, command, status, updatedAt, message }) => ({
+        id,
+        activityId,
+        command,
+        status,
+        updatedAt,
+        message: message.slice(0, 300),
+      })),
+    activities: [...activities]
+      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+      .slice(0, statusHistoryLimit)
+      .map(({ id, kind, status, updatedAt, rootOperationId, message }) => ({
+        id,
+        kind,
+        status,
+        updatedAt,
+        rootOperationId,
+        message: message.slice(0, 300),
+      })),
+    details:
+      "Use vectis_activities to list recent and unfinished activities, vectis_activity for an activity's steps, and vectis_operation for full operation results.",
+  };
+}
 const tools = [
   {
     name: "vectis_github_accounts",
@@ -107,7 +175,7 @@ const tools = [
   {
     name: "vectis_status",
     description:
-      "Read the selected machine, environments, instances and operations. Requires a running Vectis service.",
+      "Read a compact machine summary, environments, non-stopped instances, counts within the bounded status window and the newest 20 operations and activities. Use vectis_activities, vectis_activity and vectis_operation for details.",
     inputSchema: emptyInput,
     annotations: { readOnlyHint: true },
   },
@@ -135,7 +203,7 @@ const tools = [
   {
     name: "vectis_activities",
     description:
-      "List what this machine was asked to do, newest first. An activity groups the operations of one intent: a guest preparation with its setup steps, or a runner with its VM. Filter by kind, status, repository or limit.",
+      "List unfinished activities and the newest 100 terminal activities, newest first, without fetching machine status. An activity groups the operations of one intent. Filter by kind, status, repository or limit; fetch older retained activity IDs with vectis_activity.",
     inputSchema: { ...activitiesSchema.schema, $defs: activitiesSchema.definitions },
     annotations: { readOnlyHint: true },
   },
@@ -323,7 +391,7 @@ export function createMcpServer(
           result = await (await connect()).doctor();
           break;
         case "vectis_status":
-          result = await (await connect()).status();
+          result = compactStatus(await (await connect()).status());
           break;
         case "vectis_operation": {
           const input = Schema.decodeUnknownSync(operationInput, { onExcessProperty: "error" })(
@@ -416,7 +484,7 @@ export function createMcpServer(
           );
       }
       return {
-        content: [{ type: "text", text: JSON.stringify(result) }],
+        content: [],
         structuredContent: { result },
       };
     } catch (error) {
@@ -431,7 +499,7 @@ export function createMcpServer(
       const result = { code: issue.code, message: issue.message, nextStep: issue.nextStep };
       return {
         isError: true,
-        content: [{ type: "text", text: JSON.stringify(result) }],
+        content: [],
         structuredContent: { error: result },
       };
     }
diff --git a/apps/server/src/activity-retention.test.ts b/apps/server/src/activity-retention.test.ts
index 5e5324cd..c19a4aae 100644
--- a/apps/server/src/activity-retention.test.ts
+++ b/apps/server/src/activity-retention.test.ts
@@ -5,9 +5,9 @@ import { afterEach, expect, test, vi } from "vitest";
 import type { Operation } from "../../../packages/protocol/src/index.js";
 import { VmRuntime } from "../../../packages/runner/src/runtime.js";
 import { activityFor } from "./activities.js";
-import { retainActivities } from "./activity-retention.js";
+import { retainActivities, retainInstances } from "./activity-retention.js";
 import { Service } from "./service.js";
-import { Store } from "./store.js";
+import { Store, type StoreOptions } from "./store.js";
 
 const day = 24 * 60 * 60 * 1000;
 const now = Date.parse("2026-09-21T12:00:00Z");
@@ -17,10 +17,10 @@ afterEach(async () => {
   cleanup.length = 0;
   vi.useRealTimers();
 });
-async function fixture() {
+async function fixture(options: StoreOptions = {}) {
   const home = await mkdtemp(join(tmpdir(), "vectis-retention-"));
   cleanup.push(() => rm(home, { recursive: true, force: true }));
-  const store = new Store(join(home, "state.sqlite"));
+  const store = new Store(join(home, "state.sqlite"), options);
   cleanup.push(() => store.close());
   const add = (id: string, age: number, status: Operation["status"] = "succeeded") => {
     const operation = store.accept(
@@ -181,3 +181,76 @@ test("the service sweeps after initialization and hourly, then releases its time
   expect(store.get("activity", "after-close")).toBeDefined();
   expect(vi.getTimerCount()).toBe(0);
 });
+
+test("instance retention keeps the stopped tail, recent stops and every non-stopped instance", async () => {
+  const { store } = await fixture();
+  const add = (id: string, age: number, status = "stopped") =>
+    store.put("instance", id, {
+      id,
+      environmentId: "env",
+      status,
+      pid: 0,
+      createdAt: new Date(now - age * day).toISOString(),
+    });
+  add("oldest", 10);
+  add("old-tail", 5);
+  add("recent", 0.5);
+  add("boundary", 1);
+  for (const status of ["starting", "running", "interrupted"]) add(status, 40, status);
+  const revision = store.snapshot().revision;
+  retainInstances(store, now, { maxAgeMs: day, keep: 2 });
+  expect(store.get("instance", "oldest")).toBeUndefined();
+  expect(store.get("instance", "old-tail")).toBeUndefined();
+  for (const id of ["recent", "boundary", "starting", "running", "interrupted"])
+    expect(store.get("instance", id)).toBeDefined();
+  expect(store.snapshot().revision).not.toBe(revision);
+  const unchanged = store.snapshot().revision;
+  retainInstances(store, now, { maxAgeMs: day, keep: 2 });
+  expect(store.snapshot().revision).toBe(unchanged);
+  retainInstances(store, now + 10 * day, { maxAgeMs: day, keep: 2 });
+  expect(store.get("instance", "boundary")).toBeDefined();
+  expect(store.get("instance", "recent")).toBeDefined();
+});
+
+test("a newly stopped old instance ages from its stop and duplicate stop requests keep their receipt", async () => {
+  const { store } = await fixture();
+  vi.useFakeTimers();
+  vi.setSystemTime(now);
+  const instance = {
+    id: "long-running",
+    environmentId: "env",
+    status: "running",
+    pid: 42,
+    createdAt: new Date(now - 40 * day).toISOString(),
+  };
+  store.put("instance", instance.id, instance);
+  store.put("instance", instance.id, { ...instance, status: "stopped", pid: 0 });
+  expect(store.get("instance", instance.id)).toMatchObject({
+    stoppedAt: new Date(now).toISOString(),
+  });
+  const receipt = store.accept("stop", "stop-fingerprint", "instance.stop").operation;
+  store.update(receipt, { status: "succeeded" });
+  retainInstances(store, now + day, { maxAgeMs: day, keep: 0 });
+  expect(store.get("instance", instance.id)).toBeDefined();
+  retainInstances(store, now + day + 1, { maxAgeMs: day, keep: 0 });
+  expect(store.get("instance", instance.id)).toBeUndefined();
+  expect(store.accept("stop", "stop-fingerprint", "instance.stop")).toMatchObject({
+    fresh: false,
+    operation: { id: receipt.id, status: "succeeded" },
+  });
+});
+
+test("retention sweeps records outside the bounded status window", async () => {
+  const { store, add } = await fixture({
+    snapshotLimits: { operations: 3, activities: 3, stoppedInstances: 2 },
+  });
+  for (let index = 0; index < 4; index++) add(`expired-${index}`, 40 + index);
+  add("visible", 0.5);
+  expect(store.snapshot().operations).toHaveLength(3);
+  expect(store.snapshot().activities).toHaveLength(3);
+  expect(store.snapshot().activities?.length).toBeLessThan(store.activitySummaries().length);
+  retainActivities(store, () => false, now);
+  expect(store.activitySummaries().map(({ id }) => id)).toEqual(["visible"]);
+  expect(store.operations().map(({ id }) => id)).toEqual(["visible"]);
+  expect(store.db.prepare("SELECT COUNT(*) AS count FROM requests").get()?.count).toBe(5);
+});
diff --git a/apps/server/src/activity-retention.ts b/apps/server/src/activity-retention.ts
index d39c0822..eb589079 100644
--- a/apps/server/src/activity-retention.ts
+++ b/apps/server/src/activity-retention.ts
@@ -7,6 +7,25 @@ const day = 24 * 60 * 60 * 1000;
 // arguments so a test can prove the rule without writing hundreds of rows to prove the constant.
 export type RetentionLimits = { maxAgeMs: number; keep: number };
 export const retentionLimits: RetentionLimits = { maxAgeMs: 30 * day, keep: 300 };
+export const instanceRetentionLimits: RetentionLimits = { maxAgeMs: day, keep: 20 };
+
+export function retainInstances(
+  store: Store,
+  now = Date.now(),
+  limits: RetentionLimits = instanceRetentionLimits,
+) {
+  const removed = store.db
+    .prepare(`DELETE FROM records WHERE kind='instance'
+    AND json_extract(body,'$.status')='stopped'
+    AND julianday(COALESCE(json_extract(body,'$.stoppedAt'),json_extract(body,'$.createdAt')))
+      < julianday(?)
+    AND id NOT IN (SELECT id FROM records WHERE kind='instance'
+      AND json_extract(body,'$.status')='stopped'
+      ORDER BY COALESCE(json_extract(body,'$.stoppedAt'),json_extract(body,'$.createdAt')) DESC,
+        rowid DESC LIMIT ?)`)
+    .run(new Date(now - limits.maxAgeMs).toISOString(), limits.keep);
+  if (removed.changes) store.touch();
+}
 
 export function retainActivities(
   store: Store,
@@ -14,8 +33,9 @@ export function retainActivities(
   now = Date.now(),
   limits: RetentionLimits = retentionLimits,
 ) {
-  const snapshot = store.snapshot();
-  const candidates = (snapshot.activities ?? [])
+  retainInstances(store, now);
+  const candidates = store
+    .activitySummaries()
     .flatMap((activity) =>
       isTerminal(activity.status) && activity.completedAt !== undefined
         ? [{ activity, completedAt: Date.parse(activity.completedAt) }]
@@ -37,7 +57,7 @@ export function retainActivities(
       throw error;
     }
   }
-  for (const operation of snapshot.operations) {
+  for (const operation of store.operations()) {
     if (
       operation.activityId === undefined &&
       isTerminal(operation.status) &&
diff --git a/apps/server/src/cache-guest-privilege.test.ts b/apps/server/src/cache-guest-privilege.test.ts
new file mode 100644
index 00000000..e55135ca
--- /dev/null
+++ b/apps/server/src/cache-guest-privilege.test.ts
@@ -0,0 +1,44 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test } from "vitest";
+import { Store } from "./store.js";
+import { cacheGuestPrivilege, recordCacheGuestPrivilege } from "./cache-guest-privilege.js";
+
+test("cache privilege observations survive restart and apply only to the probed image and guest user", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-cache-privilege-"));
+  const path = join(home, "state.sqlite");
+  const environment = {
+    id: "linux",
+    name: "Linux",
+    os: "linux",
+    state: "ready",
+    basePath: join(home, "base.img"),
+    cpu: 1,
+    memoryMiB: 512,
+  } as const;
+  let store = new Store(path);
+  try {
+    expect(cacheGuestPrivilege(store, environment)).toBeUndefined();
+    recordCacheGuestPrivilege(store, environment, false);
+    store.close();
+    store = new Store(path);
+    expect(cacheGuestPrivilege(store, environment)).toBe(false);
+    expect(cacheGuestPrivilege(store, { ...environment, cpu: 2 })).toBe(false);
+    expect(
+      cacheGuestPrivilege(store, { ...environment, basePath: join(home, "new.img") }),
+    ).toBeUndefined();
+    expect(cacheGuestPrivilege(store, { ...environment, sshUser: "new-user" })).toBeUndefined();
+    expect(
+      cacheGuestPrivilege(store, {
+        ...environment,
+        image: { revision: "new", provisionedAt: "now" },
+      }),
+    ).toBeUndefined();
+    recordCacheGuestPrivilege(store, environment, true);
+    expect(cacheGuestPrivilege(store, environment)).toBe(true);
+  } finally {
+    store.close();
+    await rm(home, { recursive: true, force: true });
+  }
+});
diff --git a/apps/server/src/cache-guest-privilege.ts b/apps/server/src/cache-guest-privilege.ts
new file mode 100644
index 00000000..cd35e3b7
--- /dev/null
+++ b/apps/server/src/cache-guest-privilege.ts
@@ -0,0 +1,30 @@
+import { Schema } from "effect";
+import type { Environment } from "../../../packages/protocol/src/index.js";
+import type { Store } from "./store.js";
+
+const Probe = Schema.Struct({ image: Schema.String, allowed: Schema.Boolean });
+
+function imageIdentity(environment: Environment) {
+  return JSON.stringify([
+    environment.os,
+    environment.basePath,
+    environment.image ?? null,
+    environment.sshUser ?? null,
+    environment.sshKeyPath ?? null,
+  ]);
+}
+
+export function cacheGuestPrivilege(store: Store, environment: Environment) {
+  const probe = store.get("cacheGuestPrivilege", environment.id);
+  return Schema.is(Probe)(probe) && probe.image === imageIdentity(environment)
+    ? probe.allowed
+    : undefined;
+}
+
+export function recordCacheGuestPrivilege(
+  store: Store,
+  environment: Environment,
+  allowed: boolean,
+) {
+  store.put("cacheGuestPrivilege", environment.id, { image: imageIdentity(environment), allowed });
+}
diff --git a/apps/server/src/http.test.ts b/apps/server/src/http.test.ts
index 0c80cec2..5e62d109 100644
--- a/apps/server/src/http.test.ts
+++ b/apps/server/src/http.test.ts
@@ -1,21 +1,28 @@
+vi.mock("./resource-probe.js", () => ({
+  resourceProbe: () => ({ footprintsMiB: new Map(), pressure: "normal", pressureKnown: true }),
+}));
+
 import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { tmpdir, totalmem } from "node:os";
 import { join } from "node:path";
 import { afterEach, expect, test, vi } from "vitest";
 import { startService } from "./http.js";
 import { VectisClient } from "../../../packages/client/src/index.js";
 import { Snapshot, VectisError } from "../../../packages/protocol/src/index.js";
 import { Schema } from "effect";
+import { activityFor } from "./activities.js";
+import type { RunnerProgress } from "../../../packages/protocol/src/runners.js";
+import type { StoreOptions } from "./store.js";
 
 const cleanup: Array<() => Promise<void>> = [];
 afterEach(async () => {
   for (const close of cleanup.reverse()) await close();
   cleanup.length = 0;
 });
-async function fixture() {
+async function fixture(options: StoreOptions = {}) {
   const home = await mkdtemp(join(tmpdir(), "vectis-test-"));
   cleanup.push(() => rm(home, { recursive: true, force: true }));
-  const server = await startService({ home });
+  const server = await startService({ home, ...options });
   cleanup.push(server.close);
   return { home, server, client: new VectisClient(server.connection) };
 }
@@ -29,6 +36,108 @@ test("an unpaired status snapshot decodes with a stable revision and no reposito
   expect((await client.status()).revision).toBe(snapshot.revision);
 });
 
+test("snapshot, activity and operation reads preserve runner phase timestamps", async () => {
+  const { client, server } = await fixture();
+  const command = { type: "runner.run", bindingId: "binding" } as const;
+  const operation = server.store.accept(
+    "runner",
+    "runner",
+    command.type,
+    activityFor("runner", command),
+    "runner",
+  ).operation;
+  const result: RunnerProgress = {
+    bindingId: "binding",
+    environmentId: "linux",
+    leaseKey: operation.id,
+    stage: "finished",
+    cache: { attached: true, writeBack: "granted", promoted: true },
+    phases: [{ name: "vm_start", startedAt: operation.createdAt, endedAt: operation.createdAt }],
+  };
+  server.store.update(operation, { status: "succeeded", result });
+  expect(
+    (await client.status()).operations.find((item) => item.id === operation.id)?.result,
+  ).toEqual(result);
+  expect((await client.operation(operation.id)).result).toEqual(result);
+  expect((await client.activity("runner")).operations[0]?.result).toEqual(result);
+});
+
+test("individual operations, keys and activities remain readable outside the status window", async () => {
+  const { client, server } = await fixture({
+    snapshotLimits: { operations: 3, activities: 3, stoppedInstances: 2 },
+  });
+  const command = { type: "runner.run", bindingId: "binding" } as const;
+  const id = "old-operation";
+  const key = "request:/with spaces?&=value";
+  const operation = server.store.accept(
+    key,
+    key,
+    command.type,
+    activityFor(id, command),
+    id,
+  ).operation;
+  const result: RunnerProgress = {
+    bindingId: "binding",
+    environmentId: "linux",
+    leaseKey: id,
+    stage: "finished",
+    phases: [{ name: "vm_start", startedAt: operation.createdAt, endedAt: operation.createdAt }],
+  };
+  server.store.put("operation", id, {
+    ...operation,
+    status: "succeeded",
+    updatedAt: "2020-01-01T00:00:00Z",
+    result,
+  });
+  for (let index = 0; index < 3; index++) {
+    const recentId = `recent-${index}`;
+    const recentCommand = { type: "job.scan", bindingId: "binding" } as const;
+    const recent = server.store.accept(
+      recentId,
+      recentId,
+      recentCommand.type,
+      activityFor(recentId, recentCommand),
+      recentId,
+    ).operation;
+    server.store.update(recent, { status: "succeeded" });
+  }
+  const status = await client.status();
+  expect(status.operations).toHaveLength(3);
+  expect(status.activities).toHaveLength(3);
+  expect(status.operations.some((item) => item.id === id)).toBe(false);
+  expect(status.activities?.some((item) => item.id === id)).toBe(false);
+  const snapshot = vi.spyOn(server.service, "snapshot").mockImplementation(() => {
+    throw new Error("Targeted reads must not use status");
+  });
+  const revision = server.store.snapshot().revision;
+  expect(await client.operation(id)).toMatchObject({ id, key, status: "succeeded", result });
+  expect(await client.operationByKey(key)).toEqual(await client.operation(id));
+  expect(await client.activity(id)).toMatchObject({
+    activity: { id, status: "succeeded" },
+    operations: [{ id, result }],
+  });
+  expect((await client.activities()).map((activity) => activity.id)).toContain(id);
+  for (const path of [
+    "/v1/operations/unknown",
+    "/v1/operations?key=unknown",
+    "/v1/activities/unknown",
+  ]) {
+    expect(
+      (
+        await fetch(`${server.connection.url}${path}`, {
+          headers: { Authorization: `Bearer ${server.connection.token}` },
+        })
+      ).status,
+    ).toBe(404);
+    expect((await fetch(`${server.connection.url}${path}`)).status).toBe(401);
+  }
+  await expect(client.operation("unknown")).rejects.toMatchObject({ code: "operation_missing" });
+  await expect(client.activity("unknown")).rejects.toMatchObject({ code: "activity_missing" });
+  expect(server.store.snapshot().revision).toBe(revision);
+  expect(snapshot).not.toHaveBeenCalled();
+  snapshot.mockRestore();
+});
+
 test("strict snapshot decoding accepts older services during an app update", async () => {
   const { client, server } = await fixture();
   const legacy = { ...server.service.snapshot() };
@@ -274,7 +383,12 @@ test("an accepted shutdown stops advertising readiness before the listener close
 
 test("machine runner limits reject invalid values and survive a service restart", async () => {
   const { home, server, client } = await fixture();
-  expect((await client.status()).runnerCapacity).toEqual({ max: 5, active: 0, available: 0 });
+  expect((await client.status()).runnerCapacity).toMatchObject({
+    max: 5,
+    active: 0,
+    available: 0,
+    environments: [],
+  });
   for (const maxRunners of [0, 17, -1, 1.5, "5"]) {
     const response = await fetch(server.connection.url + "/v1/commands", {
       method: "POST",
@@ -294,7 +408,12 @@ test("machine runner limits reject invalid values and survive a service restart"
     expect(operation.status).toBe("succeeded");
     const state = await client.status();
     expect(state.machine.maxRunners).toBe(maxRunners);
-    expect(state.runnerCapacity).toEqual({ max: maxRunners, active: 0, available: 0 });
+    expect(state.runnerCapacity).toMatchObject({
+      max: maxRunners,
+      active: 0,
+      available: 0,
+      environments: [],
+    });
     expect(state.activities).toEqual([]);
   }
   await server.close();
@@ -306,6 +425,62 @@ test("machine runner limits reject invalid values and survive a service restart"
   expect(state.runnerCapacity?.max).toBe(3);
 });
 
+test("machine memory budget validates host bounds, preserves other settings and survives restart", async () => {
+  const { home, server, client } = await fixture();
+  const hostMemoryMiB = Math.floor(totalmem() / 1024 ** 2);
+  for (const memoryBudgetMiB of [0, 2047, -1, 2048.5, "8192"]) {
+    const response = await fetch(server.connection.url + "/v1/commands", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${server.connection.token}` },
+      body: JSON.stringify({
+        key: `invalid-budget-${memoryBudgetMiB}`,
+        command: { type: "machine.configure", memoryBudgetMiB },
+      }),
+    });
+    expect(response.status).toBe(400);
+  }
+  expect(
+    await client.settle(
+      { type: "machine.configure", memoryBudgetMiB: hostMemoryMiB + 1 },
+      "too-large",
+    ),
+  ).toMatchObject({ status: "failed", result: { code: "invalid_resources" } });
+  expect(await client.settle({ type: "machine.configure" }, "empty")).toMatchObject({
+    status: "failed",
+    result: { code: "invalid_resources" },
+  });
+  for (const memoryBudgetMiB of [2048, hostMemoryMiB]) {
+    expect(
+      (
+        await client.settle(
+          { type: "machine.configure", memoryBudgetMiB },
+          `budget-${memoryBudgetMiB}`,
+        )
+      ).status,
+    ).toBe("succeeded");
+    expect((await client.status()).runnerCapacity?.budget).toMatchObject({
+      memoryBudgetMiB,
+      memoryCommittedMiB: 0,
+      pressure: "normal",
+      pressureKnown: true,
+    });
+  }
+  await client.settle({ type: "machine.configure", maxRunners: 3 }, "runners-only");
+  expect((await client.status()).machine).toMatchObject({
+    maxRunners: 3,
+    memoryBudgetMiB: hostMemoryMiB,
+  });
+  await client.settle({ type: "machine.configure", memoryBudgetMiB: 2048 }, "memory-only");
+  await server.close();
+  cleanup.pop();
+  const restarted = await startService({ home });
+  cleanup.push(restarted.close);
+  expect((await new VectisClient(restarted.connection).status()).machine).toMatchObject({
+    maxRunners: 3,
+    memoryBudgetMiB: 2048,
+  });
+});
+
 test("task failures are redacted in storage and the logs query before any display", async () => {
   const { home, server, client } = await fixture();
   const canary = "ghp_TaskFailureCanary123456789";
diff --git a/apps/server/src/http.ts b/apps/server/src/http.ts
index 6d01b5a4..030274a2 100644
--- a/apps/server/src/http.ts
+++ b/apps/server/src/http.ts
@@ -18,7 +18,7 @@ import {
 } from "../../../packages/protocol/src/index.js";
 import { runtimeDiagnostics } from "../../../packages/runner/src/diagnostics.js";
 import { storageReport } from "../../../packages/runner/src/storage.js";
-import { Store } from "./store.js";
+import { Store, snapshotLimits, type StoreOptions } from "./store.js";
 import { Service } from "./service.js";
 import { VmRuntime, type RuntimeOptions } from "../../../packages/runner/src/runtime.js";
 import { VectisClient } from "../../../packages/client/src/index.js";
@@ -53,12 +53,13 @@ async function body(request: IncomingMessage) {
   }
 }
 export async function startService(
-  options: RuntimeOptions & {
-    port?: number;
-    token?: string;
-    keychainHelper?: string;
-    onShutdown?: () => void;
-  },
+  options: RuntimeOptions &
+    StoreOptions & {
+      port?: number;
+      token?: string;
+      keychainHelper?: string;
+      onShutdown?: () => void;
+    },
 ) {
   privateHome(options.home);
   privateFile(join(options.home, "connection.json"));
@@ -90,7 +91,7 @@ export async function startService(
   const token = options.token ?? randomBytes(32).toString("hex");
   let store: Store;
   try {
-    store = new Store(join(options.home, "state.sqlite"));
+    store = new Store(join(options.home, "state.sqlite"), options);
   } catch (error) {
     await rm(lockPath, { force: true });
     throw error;
@@ -132,6 +133,7 @@ export async function startService(
   const reload = () => {
     const current = relayUpdate.then(async () => {
       if (closing || !connection) throw new Error("Service is not ready for cloud reload.");
+      await service.suspendScaleSets();
       await relay?.close();
       if (relay) {
         relay = undefined;
@@ -142,13 +144,21 @@ export async function startService(
         new VectisClient(connection),
         options.keychainHelper,
         (value) => {
-          if (!isDeepStrictEqual(cloud, value)) store.touch();
+          const changed = !isDeepStrictEqual(cloud, value);
           cloud = value;
+          if (changed) store.touch();
+        },
+        () => {
+          store.touch();
+          service.repositoriesChanged();
         },
-        () => store.touch(),
         (entries) => service.observeJobs(entries),
       );
-      if (relay) store.touch();
+      service.resumeScaleSets();
+      if (relay) {
+        store.touch();
+        service.repositoriesChanged();
+      }
     });
     relayUpdate = current.catch(() => {});
     return current;
@@ -275,6 +285,25 @@ export async function startService(
           });
         return reply(response, 200, { ...service.snapshot(), version: buildInfo().version, cloud });
       }
+      if (request.method === "GET" && request.url === "/v1/activities")
+        return reply(response, 200, store.activitySummaries(snapshotLimits.activities));
+      if (request.method === "GET" && request.url?.startsWith("/v1/operations?")) {
+        const key = new URL(request.url, "http://127.0.0.1").searchParams.get("key");
+        if (!key) throw new VectisError("invalid_request", "An operation key is required.");
+        return reply(response, 200, store.operationByKey(key));
+      }
+      if (request.method === "GET" && request.url?.startsWith("/v1/operations/"))
+        return reply(
+          response,
+          200,
+          store.operation(decodeURIComponent(request.url.slice("/v1/operations/".length))),
+        );
+      if (request.method === "GET" && request.url?.startsWith("/v1/activities/"))
+        return reply(
+          response,
+          200,
+          store.activity(decodeURIComponent(request.url.slice("/v1/activities/".length))),
+        );
       if (request.method === "GET" && request.url === "/v1/capabilities")
         return reply(response, 200, { protocolVersion: 1, capabilities });
       if (request.method === "POST" && request.url === "/v1/commands") {
@@ -299,11 +328,19 @@ export async function startService(
         error instanceof VectisError
           ? error
           : new VectisError("internal_error", "The service could not process the request.");
-      reply(response, issue.code === "idempotency_conflict" ? 409 : 400, {
-        code: issue.code,
-        message: redact(issue.message),
-        nextStep: redact(issue.nextStep),
-      });
+      reply(
+        response,
+        issue.code === "idempotency_conflict"
+          ? 409
+          : ["operation_missing", "activity_missing"].includes(issue.code)
+            ? 404
+            : 400,
+        {
+          code: issue.code,
+          message: redact(issue.message),
+          nextStep: redact(issue.nextStep),
+        },
+      );
     });
   });
   server.requestTimeout = 15000;
@@ -361,9 +398,9 @@ export async function startService(
   } catch (error) {
     storageAbort.abort();
     await storageInspection;
+    await service.close();
     await relay?.close();
     server.close();
-    await service.close();
     store.close();
     await rm(lockPath, { force: true });
     throw error;
diff --git a/apps/server/src/instance-start.test.ts b/apps/server/src/instance-start.test.ts
index 3d5f2673..3643a5b4 100644
--- a/apps/server/src/instance-start.test.ts
+++ b/apps/server/src/instance-start.test.ts
@@ -1,5 +1,10 @@
+vi.mock("./resource-probe.js", () => ({
+  resourceProbe: () => ({ footprintsMiB: new Map(), pressure: "normal", pressureKnown: true }),
+}));
+
+import { ChildProcess } from "node:child_process";
 import { mkdtemp, rm } from "node:fs/promises";
-import { cpus, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { expect, test, vi } from "vitest";
 import { VmRuntime } from "../../../packages/runner/src/runtime.js";
@@ -80,16 +85,17 @@ test("a booting VM keeps its resources, so a start beyond the budget is refused"
     os: "linux",
     state: "ready",
     basePath: join(home, "base.img"),
-    cpu: Math.floor(cpus().length / 2) + 1,
-    memoryMiB: 512,
+    cpu: 1,
+    memoryMiB: 4096,
   });
+  store.put("machine", "self", { ...store.snapshot().machine, memoryBudgetMiB: 2048 });
   try {
     const start = service.submit("start", { type: "environment.start", id: "test" });
     const second = service.submit("second", { type: "environment.start", id: "test" });
     await service.drain();
     expect(store.snapshot().operations.find((item) => item.id === second.id)).toMatchObject({
       status: "failed",
-      result: { code: "capacity_exceeded" },
+      result: { code: "memory_budget_exceeded" },
     });
     expect(store.snapshot().instances).toHaveLength(1);
     service.submit("cancel", { type: "operation.cancel", id: start.id });
@@ -109,7 +115,7 @@ test("a booting VM keeps its resources, so a start beyond the budget is refused"
   }
 });
 
-test("an interrupted instance from a previous service run blocks new VMs until reconciled", async () => {
+test("an interrupted instance reserves its own resources while another VM can start", async () => {
   const home = await mkdtemp(join(tmpdir(), "vectis-interrupted-start-"));
   const store = new Store(":memory:");
   store.put("instance", "lost", {
@@ -122,6 +128,13 @@ test("an interrupted instance from a previous service run blocks new VMs until r
   const runtime = new VmRuntime({ home });
   const service = new Service(store, runtime);
   const reconcile = vi.spyOn(runtime, "reconcile").mockResolvedValue(false);
+  const startVm = vi.spyOn(runtime, "start").mockImplementation(async (id) => ({
+    id,
+    process: new ChildProcess(),
+    directory: join(home, id),
+    settled: Promise.resolve(),
+  }));
+  const stopVm = vi.spyOn(runtime, "stop").mockResolvedValue(undefined);
   store.put("environment", "test", {
     id: "test",
     name: "Test",
@@ -136,14 +149,21 @@ test("an interrupted instance from a previous service run blocks new VMs until r
     expect(store.snapshot().instances[0]).toMatchObject({ id: "lost", status: "interrupted" });
     const start = service.submit("start", { type: "environment.start", id: "test" });
     await service.drain();
-    expect(store.snapshot().operations.find((item) => item.id === start.id)).toMatchObject({
-      status: "action_required",
-      result: { code: "reconciliation_required" },
-    });
-    expect(service.snapshot().runnerCapacity?.available).toBe(0);
+    await vi.waitFor(() =>
+      expect(store.snapshot().operations.find((item) => item.id === start.id)?.status).toBe(
+        "succeeded",
+      ),
+    );
+    expect(startVm).toHaveBeenCalledOnce();
+    expect(store.snapshot().instances.find((item) => item.id === "lost")?.status).toBe(
+      "interrupted",
+    );
+    expect(store.snapshot().instances.find((item) => item.id === start.id)?.status).toBe("running");
   } finally {
     await service.close();
     reconcile.mockRestore();
+    startVm.mockRestore();
+    stopVm.mockRestore();
     store.close();
     await rm(home, { recursive: true, force: true });
   }
diff --git a/apps/server/src/logs.test.ts b/apps/server/src/logs.test.ts
index 65e40a77..614a8a82 100644
--- a/apps/server/src/logs.test.ts
+++ b/apps/server/src/logs.test.ts
@@ -22,12 +22,10 @@ test("returns the newest lines and says when older lines were left out", async (
 
 test("reads at most the log tail without starting mid-line", async () => {
   home = await mkdtemp(join(tmpdir(), "vectis-logs-"));
-  const line = "x".repeat(99);
-  await writeFile(join(home, "service.log"), `${line}\n`.repeat(3000) + "last\n");
-  const log = await readServiceLog(home, 1000);
-  expect(log.truncated).toBe(true);
-  expect(log.lines.at(-1)).toBe("last");
-  expect(log.lines.every((entry) => entry === line || entry === "last")).toBe(true);
+  const line = "xxxxxxxxx";
+  await writeFile(join(home, "service.log"), `${line}\n`.repeat(4) + "last\n");
+  const log = await readServiceLog(home, 10, 32);
+  expect(log).toEqual({ lines: [line, line, "last"], truncated: true });
 });
 
 test("multiline private keys are redacted before selecting the requested lines", async () => {
@@ -45,13 +43,14 @@ test("multiline private keys are redacted before selecting the requested lines",
 test("a bounded tail never exposes a credential whose identifying prefix was cut off", async () => {
   home = await mkdtemp(join(tmpdir(), "vectis-logs-long-"));
   const canary = "LongLogCanary123456789";
-  await writeFile(join(home, "service.log"), `Authorization: Bearer ${canary.repeat(10000)}`);
-  expect(await readServiceLog(home, 10)).toEqual({ lines: [], truncated: true });
+  const tailBytes = 32;
+  await writeFile(join(home, "service.log"), `Authorization: Bearer ${canary.repeat(3)}`);
+  expect(await readServiceLog(home, 10, tailBytes)).toEqual({ lines: [], truncated: true });
   await writeFile(
     join(home, "service.log"),
-    `Authorization: Bearer ${canary.repeat(10000)}\nrunner-name exit 23\n`,
+    `Authorization: Bearer ${canary.repeat(3)}\nrunner-name exit 23\n`,
   );
-  expect(await readServiceLog(home, 10)).toEqual({
+  expect(await readServiceLog(home, 10, tailBytes)).toEqual({
     lines: ["runner-name exit 23"],
     truncated: true,
   });
diff --git a/apps/server/src/logs.ts b/apps/server/src/logs.ts
index e0dfb2ab..5602367f 100644
--- a/apps/server/src/logs.ts
+++ b/apps/server/src/logs.ts
@@ -3,9 +3,11 @@ import { open } from "node:fs/promises";
 import { join } from "node:path";
 import type { ServiceLog } from "../../../packages/protocol/src/logs.js";
 
-const tailBytes = 128 * 1024;
-
-export async function readServiceLog(home: string, lines: number): Promise<ServiceLog> {
+export async function readServiceLog(
+  home: string,
+  lines: number,
+  tailBytes = 128 * 1024,
+): Promise<ServiceLog> {
   let file;
   try {
     file = await open(join(home, "service.log"), "r");
diff --git a/apps/server/src/preparation-task.test.ts b/apps/server/src/preparation-task.test.ts
index ba0706e6..5336c49d 100644
--- a/apps/server/src/preparation-task.test.ts
+++ b/apps/server/src/preparation-task.test.ts
@@ -1,8 +1,27 @@
-import { expect, test } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test, vi } from "vitest";
 import { Service } from "./service.js";
 import { Store } from "./store.js";
 import { VmRuntime } from "../../../packages/runner/src/runtime.js";
 import type { LinuxPreparation } from "../../../packages/protocol/src/index.js";
+import {
+  prepareLinux,
+  preparationDirectory,
+} from "../../../packages/runner/src/linux-preparation.js";
+import { runPreparationGuest } from "../../../packages/runner/src/preparation-process.js";
+
+vi.mock("../../../packages/runner/src/linux-preparation.js", async (original) => ({
+  ...(await original<typeof import("../../../packages/runner/src/linux-preparation.js")>()),
+  prepareLinux: vi.fn(),
+  validatePreparation: vi.fn(),
+}));
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.resetAllMocks();
+});
 const configuration: LinuxPreparation = {
   id: "linux",
   name: "Linux",
@@ -62,3 +81,84 @@ test("resuming completed preparation cannot overwrite registered settings", asyn
     store.close();
   }
 });
+
+test.each(["failure marker", "timeout"] as const)(
+  "Linux preparation exposes serial diagnostics in the operation after %s",
+  async (mode) => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-preparation-task-"));
+    const store = new Store(join(home, "state.sqlite"));
+    const service = new Service(store, new VmRuntime({ home }));
+    const originalTimeout = AbortSignal.timeout;
+    vi.spyOn(AbortSignal, "timeout").mockImplementation((ms) =>
+      originalTimeout(ms === 3600000 ? 1000 : ms),
+    );
+    vi.mocked(prepareLinux).mockImplementation(async (preparation, _options, signal, progress) => {
+      const directory = preparationDirectory(preparation);
+      await mkdir(directory, { recursive: true });
+      const helper = join(home, "synthetic-helper");
+      await writeFile(
+        helper,
+        `#!${process.execPath}
+process.stdin.resume();
+process.stdin.on("end", () => process.exit(0));
+process.stderr.write("token=ServiceCanary123456789\\nvectis-provision: dependencies-install\\n");
+${mode === "failure marker" ? 'process.stderr.write("VECTIS_PREPARATION_FAILED_setup step=runner-dependencies exit=23\\n");' : ""}
+`,
+        { mode: 0o700 },
+      );
+      progress("booting");
+      try {
+        await runPreparationGuest(
+          {
+            helper,
+            directory,
+            id: preparation.id,
+            cpu: 2,
+            memoryMiB: 2048,
+            marker: "VECTIS_READY",
+            failureMarker: "VECTIS_PREPARATION_FAILED_setup",
+          },
+          signal,
+        );
+      } catch (error) {
+        progress("interrupted");
+        throw error;
+      }
+      throw new Error("Synthetic preparation must fail");
+    });
+    try {
+      const op = service.submit("prepare", {
+        type: "environment.prepare-linux",
+        ...configuration,
+        imageDirectory: home,
+        storagePath: home,
+      });
+      await service.drain();
+      await vi.waitFor(
+        () => {
+          expect(store.snapshot().operations.find((item) => item.id === op.id)?.status).toBe(
+            "action_required",
+          );
+        },
+        { timeout: 3000 },
+      );
+      const result = store.snapshot().operations.find((item) => item.id === op.id);
+      expect(result).toMatchObject({
+        status: "action_required",
+        result: {
+          phase: "interrupted",
+          code: mode === "timeout" ? "preparation_timeout" : "guest_preparation_failed",
+          diagnostics: expect.stringContaining(
+            "token=[redacted]\nvectis-provision: dependencies-install",
+          ),
+        },
+      });
+      expect(JSON.stringify(result)).not.toContain("ServiceCanary");
+      expect(store.snapshot().environments).toHaveLength(0);
+    } finally {
+      await service.close();
+      store.close();
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
diff --git a/apps/server/src/preparation-task.ts b/apps/server/src/preparation-task.ts
index 5bcded98..b0ba4971 100644
--- a/apps/server/src/preparation-task.ts
+++ b/apps/server/src/preparation-task.ts
@@ -12,7 +12,10 @@ import {
   preparationDirectory,
   validatePreparation,
 } from "../../../packages/runner/src/linux-preparation.js";
-import { preparationStopped } from "../../../packages/runner/src/preparation-process.js";
+import {
+  PreparationProcessError,
+  preparationStopped,
+} from "../../../packages/runner/src/preparation-process.js";
 import type { VmRuntime } from "../../../packages/runner/src/runtime.js";
 import type { Store } from "./store.js";
 
@@ -138,6 +141,7 @@ export async function startPreparation(
           phase: preparation.phase,
           directory: preparationDirectory(preparation),
           code: issue.code,
+          ...(error instanceof PreparationProcessError ? { diagnostics: error.diagnostics } : {}),
           nextStep: `Inspect prerequisites, then resume with environment resume ${preparation.id}. Partial downloads are retained.`,
         },
       });
diff --git a/apps/server/src/provision-task.test.ts b/apps/server/src/provision-task.test.ts
new file mode 100644
index 00000000..557e7771
--- /dev/null
+++ b/apps/server/src/provision-task.test.ts
@@ -0,0 +1,1095 @@
+import { spawn } from "node:child_process";
+import {
+  copyFile,
+  mkdtemp,
+  mkdir,
+  readFile,
+  realpath,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test, vi } from "vitest";
+import {
+  VectisError,
+  type Command,
+  type Environment,
+} from "../../../packages/protocol/src/index.js";
+import { executeGuest, GuestUnavailableError } from "../../../packages/runner/src/guest.js";
+import { readyGuest } from "../../../packages/runner/src/guest-ready.js";
+import { VmRuntime } from "../../../packages/runner/src/runtime.js";
+import { runnerVersion } from "../../../packages/runner/src/runner-release.js";
+import { windowsDefenderCommands } from "../../../packages/runner/src/windows-defender.js";
+import { windowsToolchainScript } from "../../../packages/runner/src/windows-toolchain.js";
+import { cloneProvisionImage } from "../../../packages/runner/src/provision-image.js";
+import { Service } from "./service.js";
+import { Store } from "./store.js";
+import { recoverProvisions, startProvision } from "./provision-task.js";
+
+vi.mock("../../../packages/runner/src/guest-ready.js", () => ({ readyGuest: vi.fn() }));
+vi.mock("../../../packages/runner/src/guest.js", async (original) => ({
+  ...(await original<typeof import("../../../packages/runner/src/guest.js")>()),
+  executeGuest: vi.fn(),
+}));
+vi.mock("../../../packages/runner/src/provision-image.js", () => ({
+  cloneProvisionImage: vi.fn(),
+}));
+
+const cleanups: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const cleanup of cleanups.reverse()) await cleanup();
+  cleanups.length = 0;
+  vi.restoreAllMocks();
+  vi.resetAllMocks();
+});
+
+async function fixture(configuration: { exitCode?: number; os?: Environment["os"] } = {}) {
+  const home = await mkdtemp(join(tmpdir(), "vectis-provision-"));
+  const store = new Store(join(home, "state.sqlite"));
+  const runtime = new VmRuntime({ home });
+  const service = new Service(store, runtime);
+  const parent: Environment = {
+    id: "parent",
+    name: "Parent",
+    os: configuration.os ?? "linux",
+    basePath: join(home, "parent.img"),
+    state: "ready",
+    cpu: 1,
+    memoryMiB: 512,
+    sshUser: "vectis",
+    sshKeyPath: join(home, "parent-key"),
+    sshHostKeyMode: "instance",
+  };
+  await writeFile(parent.basePath, "parent remains immutable");
+  store.put("environment", parent.id, parent);
+  const command: Extract<Command, { type: "environment.provision" }> = {
+    type: "environment.provision",
+    id: "derived",
+    from: "parent",
+    imageDirectory: join(home, "derived"),
+  };
+  let exit: (() => Promise<void>) | undefined;
+  const stop = vi.spyOn(runtime, "stop").mockImplementation(async () => {
+    await exit?.();
+  });
+  const shutdown = vi.spyOn(runtime, "requestShutdown").mockImplementation(async () => {
+    await exit?.();
+    return true;
+  });
+  vi.spyOn(runtime, "validate").mockResolvedValue();
+  const start = vi
+    .spyOn(runtime, "start")
+    .mockImplementation(async (id, environment, onExit, signal, options) => {
+      signal?.throwIfAborted();
+      expect(options).toEqual({ diskInPlace: true });
+      await writeFile(environment.basePath, "provisioning writes the clone");
+      const helper = join(home, "fake-helper.cjs");
+      await writeFile(
+        helper,
+        `process.stdin.resume(); process.stdin.on('end', () => process.exit(${configuration.exitCode ?? 0}));`,
+      );
+      const child = spawn(process.execPath, [helper], { stdio: ["pipe", "ignore", "ignore"] });
+      const settled = new Promise<void>((resolve) =>
+        child.once("close", () => {
+          onExit(true);
+          resolve();
+        }),
+      );
+      exit = async () => {
+        child.stdin.end();
+        await settled;
+      };
+      return {
+        id,
+        process: child,
+        settled,
+        directory: runtime.directoryFor(id, environment),
+        macAddress: "02:00:00:00:00:01",
+      };
+    });
+  vi.mocked(cloneProvisionImage).mockImplementation(async (environment, id, directory) => {
+    const basePath = join(directory, "disk.img");
+    await copyFile(environment.basePath, basePath);
+    return { ...environment, id, basePath };
+  });
+  vi.mocked(readyGuest).mockResolvedValue({
+    host: "192.0.2.2",
+    port: 22,
+    user: "vectis",
+    identityFile: join(home, "key"),
+    knownHostsFile: join(home, "hosts"),
+    hostKeyAlias: "test",
+  });
+  vi.mocked(executeGuest).mockImplementation(async (_connection, script) => {
+    if (
+      script.includes("poweroff") ||
+      script.includes("shutdown.exe") ||
+      script.includes("/sbin/shutdown") ||
+      script.includes("osascript")
+    )
+      await exit?.();
+    return { exitCode: 0, stdout: "", stderr: "", truncated: false };
+  });
+  cleanups.push(async () => {
+    await exit?.();
+    await service.close();
+    store.close();
+    await rm(home, { recursive: true, force: true });
+  });
+  async function submit(input = command) {
+    const accepted = service.submit("provision", input);
+    await service.drain();
+    return accepted;
+  }
+  async function completed(id: string) {
+    await vi.waitFor(() =>
+      expect(store.snapshot().operations.find((item) => item.id === id)?.status).not.toMatch(
+        /accepted|running/,
+      ),
+    );
+    return store.snapshot().operations.find((item) => item.id === id);
+  }
+  return {
+    home,
+    store,
+    runtime,
+    service,
+    parent,
+    command,
+    submit,
+    completed,
+    start,
+    stop,
+    shutdown,
+    exit: async () => exit?.(),
+  };
+}
+
+test("success freezes and registers a new manifest without changing the parent", async () => {
+  const { store, service, parent, command, submit, completed, stop } = await fixture();
+  const operation = await submit({
+    ...command,
+    name: "Repository tools",
+    setupScript: "printf 'setup'",
+  });
+  expect(await completed(operation.id)).toMatchObject({
+    status: "succeeded",
+    result: {
+      stage: "finished",
+      environment: {
+        id: "derived",
+        name: "Repository tools",
+        basePath: join(await realpath(command.imageDirectory), "disk.img"),
+        image: { parentId: "parent", runnerVersion, revision: operation.id },
+      },
+    },
+  });
+  expect(store.snapshot().environments).toHaveLength(2);
+  expect(store.snapshot().instances[0]?.status).toBe("stopped");
+  expect(store.list("provision")).toHaveLength(0);
+  expect(service.snapshot().preparationBusy).toBe(false);
+  expect(stop).not.toHaveBeenCalled();
+  expect(await readFile(parent.basePath, "utf8")).toBe("parent remains immutable");
+  const scripts = vi.mocked(executeGuest).mock.calls.map((call) => call[1]);
+  expect(scripts.join("\n")).not.toContain("printf 'setup'");
+  expect(scripts.some((script) => script.includes("setup.sh"))).toBe(true);
+});
+
+test("a guest script failure stops the owned VM and removes partial output", async () => {
+  const { command, store, submit, completed, stop } = await fixture();
+  vi.mocked(executeGuest)
+    .mockResolvedValueOnce({ exitCode: 0, stdout: "", stderr: "", truncated: false })
+    .mockResolvedValue({
+      exitCode: 1,
+      stdout: "",
+      stderr: "synthetic script failure",
+      truncated: false,
+    });
+  const operation = await submit();
+  expect(await completed(operation.id)).toMatchObject({
+    status: "failed",
+    result: {
+      code: "provision_script_failed",
+      exitCode: 1,
+      diagnostics: "== stderr\nsynthetic script failure\n== stdout\n",
+    },
+  });
+  expect(stop).toHaveBeenCalledWith(operation.id);
+  expect(store.snapshot().environments.map((item) => item.id)).toEqual(["parent"]);
+  await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+test.each([true, false])(
+  "Linux without sudo fails before downloads or setup, runner=%s",
+  async (runner) => {
+    const { command, store, submit, completed, stop, shutdown } = await fixture();
+    vi.mocked(executeGuest).mockResolvedValue({
+      exitCode: 1,
+      stdout: "",
+      stderr: "sudo: a password is required",
+      truncated: false,
+    });
+    const operation = await submit({ ...command, runner, setupScript: "echo must-not-run" });
+    expect(await completed(operation.id)).toMatchObject({
+      status: "failed",
+      result: {
+        code: "provision_requires_guest_sudo",
+        nextStep:
+          "Prepare a new Linux environment with this Vectis version, then provision from it.",
+        exitCode: 1,
+        diagnostics: expect.stringContaining("a password is required"),
+      },
+    });
+    expect(vi.mocked(executeGuest).mock.calls.map((call) => call[1])).toEqual(["sudo -n true"]);
+    expect(shutdown).not.toHaveBeenCalled();
+    expect(stop).toHaveBeenCalledWith(operation.id);
+    expect(store.snapshot().environments).toHaveLength(1);
+    await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+  },
+);
+
+test("Linux identity cleanup failure cannot freeze or register an image", async () => {
+  const { command, submit, completed, shutdown } = await fixture();
+  vi.mocked(executeGuest).mockImplementation(async (_connection, script) => ({
+    exitCode: script.includes("clear-identity") ? 23 : 0,
+    stdout: "",
+    stderr: "synthetic cleanup failure",
+    truncated: false,
+  }));
+  const operation = await submit();
+  expect(await completed(operation.id)).toMatchObject({
+    status: "failed",
+    result: { code: "provision_identity_reset_failed", exitCode: 23 },
+  });
+  expect(shutdown).not.toHaveBeenCalled();
+  await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+test.each(["linux", "windows"] as const)(
+  "%s uses guest shutdown only when the hypervisor request is unavailable",
+  async (os) => {
+    const { parent, store, submit, completed, shutdown, stop } = await fixture();
+    store.put("environment", parent.id, { ...parent, os });
+    shutdown.mockResolvedValue(false);
+    const operation = await submit();
+    expect(await completed(operation.id)).toMatchObject({ status: "succeeded" });
+    expect(shutdown).toHaveBeenCalledWith(operation.id);
+    const calls = vi.mocked(executeGuest).mock.calls;
+    expect(calls.at(-1)?.[1]).toContain("vectis-provision: shutdown");
+    expect(stop).not.toHaveBeenCalled();
+  },
+);
+
+test.each(["linux", "windows"] as const)(
+  "%s shutdown failures retain redacted output and the exit code after cleanup",
+  async (os) => {
+    const { parent, store, submit, completed, shutdown } = await fixture();
+    store.put("environment", parent.id, { ...parent, os });
+    shutdown.mockResolvedValue(false);
+    vi.mocked(executeGuest).mockImplementation(async (_connection, script) => ({
+      exitCode: script.includes("vectis-provision: shutdown") ? 23 : 0,
+      stdout: script.includes("vectis-provision: shutdown") ? "vectis-provision: shutdown" : "",
+      stderr: script.includes("vectis-provision: shutdown")
+        ? "Authorization: Bearer HiddenShutdownCanary\nsudo: a password is required"
+        : "",
+      truncated: false,
+    }));
+    const operation = await submit();
+    expect(await completed(operation.id)).toMatchObject({
+      status: "failed",
+      result: {
+        code: "guest_shutdown_failed",
+        exitCode: 23,
+        diagnostics:
+          "== stderr\nAuthorization: Bearer [redacted]\nsudo: a password is required\n== stdout\nvectis-provision: shutdown",
+      },
+    });
+    expect(store.snapshot().environments).toHaveLength(1);
+  },
+);
+
+test("macOS uses loginwindow without sudo or an ACPI request", async () => {
+  const { submit, completed, shutdown, stop } = await fixture({ os: "macos" });
+  const operation = await submit();
+  expect(await completed(operation.id)).toMatchObject({
+    status: "succeeded",
+    result: { shutdown: "loginwindow" },
+  });
+  const scripts = vi.mocked(executeGuest).mock.calls.map((call) => call[1]);
+  expect(scripts.at(-1)).toContain(
+    "osascript -e 'tell application \"loginwindow\" to «event aevtshut»'",
+  );
+  expect(scripts.join("\n")).not.toContain("sudo");
+  expect(shutdown).not.toHaveBeenCalled();
+  expect(stop).not.toHaveBeenCalled();
+});
+
+test("macOS accepts a lost SSH reply only after observing the guest stop", async () => {
+  const { submit, completed, exit, shutdown, stop } = await fixture({ os: "macos" });
+  vi.mocked(executeGuest).mockImplementation(async (_connection, script) => {
+    if (script.includes("osascript")) {
+      await exit();
+      throw new GuestUnavailableError("Connection closed by remote host");
+    }
+    return { exitCode: 0, stdout: "", stderr: "", truncated: false };
+  });
+  const operation = await submit();
+  expect(await completed(operation.id)).toMatchObject({
+    status: "succeeded",
+    result: { shutdown: "loginwindow" },
+  });
+  expect(shutdown).not.toHaveBeenCalled();
+  expect(stop).not.toHaveBeenCalled();
+});
+
+const guestSuccess = { exitCode: 0, stdout: "", stderr: "", truncated: false };
+const fastShutdown = { shutdownTimeoutMs: 10, shutdownCommandTimeoutMs: 100, syncDelayMs: 1 };
+
+test.each(["denied", "connection-lost", "no-effect"])(
+  "macOS loginwindow %s falls back to available passwordless sudo",
+  async (failure) => {
+    const { store, runtime, command, completed, shutdown, stop, exit } = await fixture({
+      os: "macos",
+    });
+    vi.mocked(executeGuest).mockImplementation(async (_connection, script) => {
+      if (script.includes("osascript")) {
+        if (failure === "connection-lost") throw new GuestUnavailableError("Connection reset");
+        if (failure === "denied") return { ...guestSuccess, exitCode: 1, stderr: "Not authorized" };
+      }
+      if (script.includes("/sbin/shutdown")) await exit();
+      return guestSuccess;
+    });
+    const { operation } = store.accept("sudo", "sudo", command.type);
+    await (
+      await startProvision(store, runtime, operation, command, fastShutdown)
+    ).done;
+    expect(await completed(operation.id)).toMatchObject({
+      status: "succeeded",
+      result: { shutdown: "sudo" },
+    });
+    expect(
+      vi
+        .mocked(executeGuest)
+        .mock.calls.slice(-2)
+        .map((call) => call[1]),
+    ).toEqual(["sudo -n true", expect.stringContaining("sudo -n /sbin/shutdown -h now")]);
+    expect(shutdown).not.toHaveBeenCalled();
+    expect(stop).not.toHaveBeenCalled();
+  },
+);
+
+test.each(["unavailable", "failed", "no-effect"])(
+  "macOS sudo %s freezes only after two syncs, a delay and a confirmed helper stop",
+  async (sudo) => {
+    const { store, runtime, command, completed, parent, stop, shutdown } = await fixture({
+      os: "macos",
+    });
+    vi.mocked(executeGuest).mockImplementation(async (_connection, script) => ({
+      ...guestSuccess,
+      exitCode:
+        (script === "sudo -n true" && sudo === "unavailable") ||
+        (script.includes("/sbin/shutdown") && sudo === "failed")
+          ? 1
+          : 0,
+    }));
+    const { operation } = store.accept("forced", "forced", command.type);
+    await (
+      await startProvision(store, runtime, operation, command, fastShutdown)
+    ).done;
+    expect(await completed(operation.id)).toMatchObject({
+      status: "succeeded",
+      message: expect.stringContaining("frozen after a forced stop following two guest syncs"),
+      result: { shutdown: "forced_stop_after_sync" },
+    });
+    const calls = vi.mocked(executeGuest).mock.calls;
+    expect(calls.slice(-2).map((call) => call[1])).toEqual(["sync", "sync"]);
+    expect(calls.some((call) => call[1].includes("/sbin/shutdown"))).toBe(sudo !== "unavailable");
+    expect(stop).toHaveBeenCalledOnce();
+    expect(stop.mock.invocationCallOrder[0]).toBeGreaterThan(
+      vi.mocked(executeGuest).mock.invocationCallOrder.at(-1) ?? 0,
+    );
+    expect(shutdown).not.toHaveBeenCalled();
+    expect(store.snapshot().instances[0]?.status).toBe("stopped");
+    expect(await readFile(parent.basePath, "utf8")).toBe("parent remains immutable");
+  },
+);
+
+test.each([1, 2])("macOS sync failure at attempt %s discards the image", async (failedSync) => {
+  const { store, runtime, command, completed, stop } = await fixture({ os: "macos" });
+  let syncs = 0;
+  vi.mocked(executeGuest).mockImplementation(async (_connection, script) => ({
+    ...guestSuccess,
+    exitCode: script === "sudo -n true" || (script === "sync" && ++syncs === failedSync) ? 23 : 0,
+    stderr: "synthetic sync failure",
+  }));
+  const { operation } = store.accept("sync-failure", "sync-failure", command.type);
+  await (
+    await startProvision(store, runtime, operation, command, fastShutdown)
+  ).done;
+  expect(await completed(operation.id)).toMatchObject({
+    status: "failed",
+    result: {
+      code: "provision_sync_failed",
+      exitCode: 23,
+      diagnostics: expect.stringContaining("synthetic sync failure"),
+    },
+  });
+  expect(stop).toHaveBeenCalledOnce();
+  expect(store.snapshot().environments).toHaveLength(1);
+  await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+test.each(["loginwindow", "sudo-probe", "sudo-shutdown", "sync", "helper-stop"])(
+  "macOS bounds a hung %s step and never freezes without sync and VM exit",
+  async (step) => {
+    const { store, runtime, command, completed, stop } = await fixture({ os: "macos" });
+    vi.mocked(executeGuest).mockImplementation(async (_connection, script, { signal }) => {
+      const hung =
+        (step === "loginwindow" && script.includes("osascript")) ||
+        (step === "sudo-probe" && script === "sudo -n true") ||
+        (step === "sudo-shutdown" && script.includes("/sbin/shutdown")) ||
+        (step === "sync" && script === "sync");
+      if (hung)
+        return new Promise((_resolve, reject) => {
+          signal.addEventListener(
+            "abort",
+            () => reject(new VectisError("guest_cancelled", "Synthetic timeout")),
+            { once: true },
+          );
+        });
+      return {
+        ...guestSuccess,
+        exitCode: script === "sudo -n true" && step !== "sudo-shutdown" ? 1 : 0,
+      };
+    });
+    if (step === "helper-stop") stop.mockImplementation(() => new Promise(() => {}));
+    const { operation } = store.accept("hung", "hung", command.type);
+    await (
+      await startProvision(store, runtime, operation, command, {
+        ...fastShutdown,
+        shutdownCommandTimeoutMs: 20,
+      })
+    ).done;
+    expect(await completed(operation.id)).toMatchObject({
+      status: step === "helper-stop" ? "action_required" : step === "sync" ? "failed" : "succeeded",
+    });
+    if (step === "sync" || step === "helper-stop") {
+      expect(store.snapshot().environments).toHaveLength(1);
+      expect(
+        store.snapshot().operations.find((item) => item.id === operation.id)?.result,
+      ).not.toMatchObject({ shutdown: "forced_stop_after_sync" });
+    } else
+      expect(
+        store.snapshot().operations.find((item) => item.id === operation.id)?.result,
+      ).toMatchObject({ shutdown: "forced_stop_after_sync" });
+  },
+);
+
+test("macOS bounds cleanup when the helper exits but VM settlement is unconfirmed", async () => {
+  const { store, runtime, command, completed, start } = await fixture({ os: "macos" });
+  const startVm = start.getMockImplementation();
+  if (!startVm) throw new Error("Missing fake runtime start");
+  start.mockImplementation(async (...args) => ({
+    ...(await startVm(...args)),
+    settled: new Promise<void>(() => {}),
+  }));
+  vi.mocked(executeGuest).mockResolvedValue(guestSuccess);
+  const { operation } = store.accept("unsettled", "unsettled", command.type);
+  await (
+    await startProvision(store, runtime, operation, command, fastShutdown)
+  ).done;
+  expect(await completed(operation.id)).toMatchObject({
+    status: "action_required",
+    result: { code: "provision_cleanup_required" },
+  });
+  expect(store.snapshot().environments).toHaveLength(1);
+  expect((await stat(command.imageDirectory)).isDirectory()).toBe(true);
+});
+
+test.each(["loginwindow", "shutdown-wait", "sync-delay"])(
+  "macOS cancellation during %s removes output without freezing",
+  async (stage) => {
+    const { store, runtime, command, completed, stop } = await fixture({ os: "macos" });
+    vi.mocked(executeGuest).mockImplementation(async (_connection, script, { signal }) => {
+      if (stage === "loginwindow" && script.includes("osascript"))
+        return new Promise((_resolve, reject) => {
+          signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+        });
+      return { ...guestSuccess, exitCode: script === "sudo -n true" ? 1 : 0 };
+    });
+    const { operation } = store.accept("cancel-macos", "cancel-macos", command.type);
+    const active = await startProvision(store, runtime, operation, command, {
+      ...fastShutdown,
+      shutdownTimeoutMs: stage === "shutdown-wait" ? 60000 : 10,
+      syncDelayMs: 5000,
+    });
+    await vi.waitFor(() => {
+      const calls = vi.mocked(executeGuest).mock.calls;
+      if (stage === "sync-delay")
+        expect(calls.filter((call) => call[1] === "sync")).toHaveLength(2);
+      else expect(calls.some((call) => call[1].includes("osascript"))).toBe(true);
+    });
+    active.abort.abort();
+    await active.done;
+    expect(await completed(operation.id)).toMatchObject({ status: "cancelled" });
+    expect(stop).toHaveBeenCalledOnce();
+    expect(store.snapshot().environments).toHaveLength(1);
+    await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+  },
+);
+
+test("macOS waits five seconds after both syncs before stopping the helper", async () => {
+  const { store, runtime, command, completed, stop } = await fixture({ os: "macos" });
+  let syncedAt = 0;
+  vi.mocked(executeGuest).mockImplementation(async (_connection, script) => {
+    if (script === "sync") syncedAt = Date.now();
+    return { ...guestSuccess, exitCode: script === "sudo -n true" ? 1 : 0 };
+  });
+  const stopVm = stop.getMockImplementation();
+  stop.mockImplementation(async (id) => {
+    expect(Date.now() - syncedAt).toBeGreaterThanOrEqual(5000);
+    await stopVm?.(id);
+  });
+  const { operation } = store.accept("sync-delay", "sync-delay", command.type);
+  await (
+    await startProvision(store, runtime, operation, command, { shutdownTimeoutMs: 10 })
+  ).done;
+  expect(await completed(operation.id)).toMatchObject({
+    status: "succeeded",
+    result: { shutdown: "forced_stop_after_sync" },
+  });
+}, 10000);
+
+test("macOS notices guest shutdown during the sync delay without claiming a forced stop", async () => {
+  const { store, runtime, command, completed, exit, stop } = await fixture({ os: "macos" });
+  let syncs = 0;
+  vi.mocked(executeGuest).mockImplementation(async (_connection, script) => {
+    if (script === "sync" && ++syncs === 2) await exit();
+    return { ...guestSuccess, exitCode: script === "sudo -n true" ? 1 : 0 };
+  });
+  const { operation } = store.accept("late-shutdown", "late-shutdown", command.type);
+  await (
+    await startProvision(store, runtime, operation, command, fastShutdown)
+  ).done;
+  expect(await completed(operation.id)).toMatchObject({
+    status: "succeeded",
+    result: { shutdown: "loginwindow" },
+  });
+  expect(stop).not.toHaveBeenCalled();
+});
+
+test("macOS rejects a failed helper exit even after successful syncs", async () => {
+  const { store, runtime, command, completed } = await fixture({ os: "macos", exitCode: 17 });
+  vi.mocked(executeGuest).mockResolvedValue(guestSuccess);
+  const { operation } = store.accept("bad-stop", "bad-stop", command.type);
+  await (
+    await startProvision(store, runtime, operation, command, fastShutdown)
+  ).done;
+  expect(await completed(operation.id)).toMatchObject({
+    status: "failed",
+    result: { code: "guest_shutdown_failed" },
+  });
+  expect(store.snapshot().environments).toHaveLength(1);
+  await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+test("setup upload failure retains bounded diagnostic tails before VM cleanup", async () => {
+  const { command, store, submit, completed, stop } = await fixture();
+  vi.mocked(executeGuest)
+    .mockResolvedValueOnce({ exitCode: 0, stdout: "", stderr: "", truncated: false })
+    .mockResolvedValue({
+      exitCode: 28,
+      stdout: `discarded-prefix\n${"漢".repeat(10000)}\nupload interrupted`,
+      stderr: `Authorization: Bearer ${"a".repeat(10000)}\nNo space left on device`,
+      truncated: true,
+    });
+  const inspectCleanup = stop.getMockImplementation();
+  stop.mockImplementation(async (id) => {
+    expect(store.snapshot().operations.find((item) => item.id === id)).toMatchObject({
+      result: { stage: "cleaning", exitCode: 28, diagnostics: expect.stringContaining("No space") },
+    });
+    await inspectCleanup?.(id);
+  });
+  const operation = await submit({ ...command, setupScript: "true" });
+  const finished = await completed(operation.id);
+  expect(finished).toMatchObject({
+    status: "failed",
+    result: {
+      code: "provision_script_failed",
+      exitCode: 28,
+      diagnostics: expect.stringContaining("upload interrupted"),
+    },
+  });
+  expect(JSON.stringify(finished?.result)).not.toContain("discarded-prefix");
+  expect(JSON.stringify(finished?.result)).not.toContain("a".repeat(100));
+  expect(Buffer.byteLength(JSON.stringify(finished?.result))).toBeLessThan(16384);
+});
+
+test("unconfirmed cleanup preserves the original guest failure diagnostics", async () => {
+  const { store, submit, completed, stop } = await fixture();
+  vi.mocked(executeGuest)
+    .mockResolvedValueOnce({ exitCode: 0, stdout: "", stderr: "", truncated: false })
+    .mockResolvedValue({
+      exitCode: 7,
+      stderr: "download failed",
+      stdout: "vectis-provision: download",
+      truncated: false,
+    });
+  stop.mockRejectedValue(new Error("Synthetic cleanup failure"));
+  const operation = await submit();
+  expect(await completed(operation.id)).toMatchObject({
+    status: "action_required",
+    result: {
+      code: "provision_cleanup_required",
+      exitCode: 7,
+      diagnostics: "== stderr\ndownload failed\n== stdout\nvectis-provision: download",
+    },
+  });
+  const instance = store.snapshot().instances.find((item) => item.id === operation.id);
+  if (!instance) throw new Error("Missing instance reservation");
+  store.put("instance", instance.id, { ...instance, status: "stopped" });
+  await recoverProvisions(store);
+  expect(await completed(operation.id)).toMatchObject({
+    status: "failed",
+    result: {
+      stage: "cleaned",
+      code: "provision_interrupted",
+      exitCode: 7,
+      diagnostics: "== stderr\ndownload failed\n== stdout\nvectis-provision: download",
+    },
+  });
+});
+
+test("lost provisioning connections retain redacted connection diagnostics", async () => {
+  const { submit, completed } = await fixture();
+  vi.mocked(executeGuest).mockRejectedValue(
+    new GuestUnavailableError("exit 255: token=HiddenConnectionCanary Connection reset"),
+  );
+  const operation = await submit();
+  expect(await completed(operation.id)).toMatchObject({
+    status: "failed",
+    result: {
+      code: "guest_unavailable",
+      diagnostics: "== stderr\nexit 255: token=[redacted] Connection reset\n== stdout\n",
+    },
+  });
+});
+test.each(["linux", "windows"] as const)(
+  "%s uses hypervisor shutdown without a privileged guest shutdown command",
+  async (os) => {
+    const { parent, store, submit, completed, shutdown, stop } = await fixture();
+    store.put("environment", parent.id, { ...parent, os });
+    const operation = await submit();
+    expect(await completed(operation.id)).toMatchObject({
+      status: "succeeded",
+      result: { environment: { os, image: { runnerVersion } } },
+    });
+    expect(
+      vi
+        .mocked(executeGuest)
+        .mock.calls.every(
+          (call) =>
+            call[2].shell ===
+            (os === "windows" ? (call[1].startsWith("reg.exe ") ? "cmd" : "powershell") : "bash"),
+        ),
+    ).toBe(true);
+    expect(shutdown).toHaveBeenCalledWith(operation.id);
+    expect(stop).not.toHaveBeenCalled();
+    const scripts = vi.mocked(executeGuest).mock.calls.map((call) => call[1]);
+    expect(scripts.join("\n")).not.toMatch(/poweroff|shutdown/);
+    if (os !== "linux") expect(scripts.join("\n")).not.toContain("sudo");
+  },
+);
+
+test("Windows runs isolated Defender commands in order before toolchain provisioning", async () => {
+  const { parent, store, submit, completed } = await fixture();
+  store.put("environment", parent.id, { ...parent, os: "windows" });
+  const commands = windowsDefenderCommands();
+  vi.mocked(executeGuest).mockImplementation(async (_connection, script) => ({
+    exitCode: commands.some((command) => command.allowFailure && command.script === script) ? 1 : 0,
+    stdout: "",
+    stderr: "optional change blocked by Tamper Protection",
+    truncated: false,
+  }));
+  const operation = await submit();
+  expect(await completed(operation.id)).toMatchObject({ status: "succeeded" });
+  const calls = vi.mocked(executeGuest).mock.calls;
+  expect(
+    calls.slice(0, commands.length).map((call) => ({ script: call[1], shell: call[2].shell })),
+  ).toEqual(commands.map(({ script, shell }) => ({ script, shell })));
+  expect(calls.slice(0, commands.length).every((call) => call[2].shell === "cmd")).toBe(true);
+  expect(calls.map((call) => call[1]).join("\n")).not.toMatch(/(?:Add|Set|Get)-Mp/);
+  expect(calls[commands.length]?.[1]).toContain(windowsToolchainScript());
+  expect(calls[commands.length]?.[1]).not.toMatch(/(?:Add|Set|Get)-Mp/);
+});
+
+test.each(["exclusion-policy", "exclusion-path", "transport"])(
+  "Windows %s failure prevents toolchain execution",
+  async (failure) => {
+    const { parent, store, submit, completed, stop } = await fixture();
+    store.put("environment", parent.id, { ...parent, os: "windows" });
+    const commands = windowsDefenderCommands();
+    const failed = commands[failure === "exclusion-policy" ? 0 : 1]?.script;
+    vi.mocked(executeGuest).mockImplementation(async (_connection, script) => {
+      if (script === failed && failure === "transport")
+        throw new GuestUnavailableError("connection lost");
+      return {
+        exitCode: script === failed ? 1 : 0,
+        stdout: "",
+        stderr: "actual Defender failure",
+        truncated: false,
+      };
+    });
+    const operation = await submit();
+    expect(await completed(operation.id)).toMatchObject({
+      status: "failed",
+      result: {
+        code: failure === "transport" ? "guest_unavailable" : "provision_script_failed",
+        diagnostics: expect.stringContaining(
+          failure === "transport" ? "connection lost" : "actual Defender failure",
+        ),
+      },
+    });
+    expect(
+      vi.mocked(executeGuest).mock.calls.some((call) => call[1].includes("toolchain-admin-check")),
+    ).toBe(false);
+    expect(stop).toHaveBeenCalledOnce();
+  },
+);
+
+test("--no-runner does not advertise an inherited runner installation", async () => {
+  const { parent, command, store, submit, completed } = await fixture();
+  store.put("environment", parent.id, {
+    ...parent,
+    image: { revision: "old", runnerVersion, provisionedAt: "2026-10-16T00:00:00Z" },
+  });
+  const operation = await submit({ ...command, runner: false });
+  expect(await completed(operation.id)).toMatchObject({ status: "succeeded" });
+  expect(
+    store.snapshot().environments.find((item) => item.id === command.id)?.image?.runnerVersion,
+  ).toBeUndefined();
+  expect(
+    vi
+      .mocked(executeGuest)
+      .mock.calls.map((call) => call[1])
+      .join("\n"),
+  ).not.toMatch(/curl|Invoke-WebRequest/);
+});
+
+test.each(["operation.cancel", "instance.stop"] as const)(
+  "%s during cloning deletes partial files without starting a VM",
+  async (type) => {
+    const { command, service, submit, completed, start, stop } = await fixture();
+    vi.mocked(cloneProvisionImage).mockImplementation(
+      async (_parent, _id, directory, _options, signal) => {
+        await writeFile(join(directory, "partial"), "unfinished clone");
+        return new Promise((_resolve, reject) => {
+          signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+          if (signal.aborted) reject(signal.reason);
+        });
+      },
+    );
+    const operation = await submit();
+    await vi.waitFor(async () =>
+      expect(await readFile(join(command.imageDirectory, "partial"), "utf8")).toBe(
+        "unfinished clone",
+      ),
+    );
+    const cancellation = service.submit("cancel-clone", { type, id: operation.id });
+    await service.drain();
+    expect(await completed(operation.id)).toMatchObject({ status: "cancelled" });
+    expect(await completed(cancellation.id)).toMatchObject({ status: "succeeded" });
+    expect(start).not.toHaveBeenCalled();
+    expect(stop).not.toHaveBeenCalled();
+    await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+  },
+);
+
+test("registration failure rolls back the environment before removing its disk", async () => {
+  const { command, store, submit, completed } = await fixture();
+  const put = store.put.bind(store);
+  vi.spyOn(store, "put").mockImplementation((kind, id, value) => {
+    if (
+      kind === "operation" &&
+      typeof value === "object" &&
+      value &&
+      "status" in value &&
+      value.status === "succeeded" &&
+      "command" in value &&
+      value.command === "environment.provision"
+    )
+      throw new Error("Synthetic registration failure");
+    put(kind, id, value);
+  });
+  const operation = await submit();
+  expect(await completed(operation.id)).toMatchObject({ status: "failed" });
+  expect(store.snapshot().environments).toHaveLength(1);
+  await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+test("operation cancellation remains available, reserves preparation capacity and removes owned output", async () => {
+  const { command, service, store, submit, completed, stop } = await fixture();
+  vi.mocked(executeGuest).mockImplementation(
+    async (_connection, _script, { signal }) =>
+      new Promise((_resolve, reject) => {
+        signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+        if (signal.aborted) reject(signal.reason);
+      }),
+  );
+  const operation = await submit();
+  await vi.waitFor(() => expect(executeGuest).toHaveBeenCalled());
+  expect(service.snapshot().preparationBusy).toBe(true);
+  expect(service.snapshot().runnerCapacity?.available).toBe(0);
+  const remove = service.submit("remove-active", { type: "environment.remove", id: "parent" });
+  service.submit("cancel-provision", { type: "operation.cancel", id: operation.id });
+  await service.drain();
+  expect(await completed(operation.id)).toMatchObject({ status: "cancelled" });
+  expect(stop).toHaveBeenCalledWith(operation.id);
+  expect(store.snapshot().operations.find((item) => item.id === remove.id)?.result).toMatchObject({
+    code: "preparation_active",
+  });
+  expect(store.snapshot().environments).toHaveLength(1);
+  await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+test.each(["linux", "windows"] as const)(
+  "%s shutdown timeout forces cleanup and never freezes a dirty image",
+  async (os) => {
+    const { parent, command, store, runtime, completed, stop, shutdown } = await fixture();
+    store.put("environment", parent.id, { ...parent, os });
+    shutdown.mockResolvedValue(true);
+    vi.mocked(executeGuest)
+      .mockResolvedValueOnce({ exitCode: 0, stdout: "", stderr: "", truncated: false })
+      .mockResolvedValue({
+        exitCode: 0,
+        stdout: "",
+        stderr: "",
+        truncated: false,
+      });
+    const { operation } = store.accept("timeout", "timeout", command.type);
+    const active = await startProvision(store, runtime, operation, command, {
+      shutdownTimeoutMs: 10,
+    });
+    await active.done;
+    expect(await completed(operation.id)).toMatchObject({
+      status: "failed",
+      result: { code: "guest_shutdown_timeout" },
+    });
+    expect(stop).toHaveBeenCalledOnce();
+    await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+  },
+);
+
+test.each(["linux", "macos", "windows"] as const)(
+  "%s rejects a failed VM exit after shutdown",
+  async (os) => {
+    const { parent, command, store, submit, completed, shutdown } = await fixture({ exitCode: 17 });
+    store.put("environment", parent.id, { ...parent, os });
+    const operation = await submit();
+    expect(await completed(operation.id)).toMatchObject({
+      status: "failed",
+      result: { code: "guest_shutdown_failed" },
+    });
+    if (os === "macos") expect(shutdown).not.toHaveBeenCalled();
+    else expect(shutdown).toHaveBeenCalledWith(operation.id);
+    expect(store.snapshot().environments).toHaveLength(1);
+    await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+  },
+);
+
+test("an accepted shutdown still waits for VM exit and remains cancellable", async () => {
+  const { parent, command, store, service, submit, completed, shutdown, stop } = await fixture();
+  store.put("environment", parent.id, { ...parent, os: "linux" });
+  let requested = () => {};
+  const ready = new Promise<void>((resolve) => {
+    requested = resolve;
+  });
+  shutdown.mockImplementation(async () => {
+    requested();
+    return true;
+  });
+  const operation = await submit();
+  await ready;
+  expect(store.snapshot().operations.find((item) => item.id === operation.id)).toMatchObject({
+    status: "running",
+    result: { stage: "shutting_down" },
+  });
+  expect(store.snapshot().environments).toHaveLength(1);
+  expect(stop).not.toHaveBeenCalled();
+  service.submit("cancel-shutdown", { type: "operation.cancel", id: operation.id });
+  await service.drain();
+  expect(await completed(operation.id)).toMatchObject({ status: "cancelled" });
+  expect(stop).toHaveBeenCalledWith(operation.id);
+  await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+test("stopping the provisioning instance cancels the operation rather than freezing a forced stop", async () => {
+  const { command, service, store, submit, completed } = await fixture();
+  vi.mocked(executeGuest).mockImplementation(
+    async (_connection, _script, { signal }) =>
+      new Promise((_resolve, reject) => {
+        signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+        if (signal.aborted) reject(signal.reason);
+      }),
+  );
+  const operation = await submit();
+  await vi.waitFor(() => expect(executeGuest).toHaveBeenCalled());
+  service.submit("stop-instance", { type: "instance.stop", id: operation.id });
+  await service.drain();
+  expect(await completed(operation.id)).toMatchObject({ status: "cancelled" });
+  expect(store.snapshot().environments).toHaveLength(1);
+  await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+test.each([
+  "id",
+  "reserved",
+  "not-ready",
+  "relative",
+  "existing",
+  "busy",
+  "paused",
+  "large-script",
+])("rejects %s before cloning and preserves existing files", async (reason) => {
+  const { parent, command, store, service, submit, completed, start } = await fixture();
+  let input = command;
+  if (reason === "id") input = { ...command, id: "parent" };
+  if (reason === "reserved")
+    store.put("preparation", "reserved", {
+      id: "reserved",
+      phase: "interrupted",
+      configuration: {
+        id: "derived",
+        name: "Reserved",
+        imageDirectory: "/isolated/images",
+        storagePath: "/isolated/vms",
+        cpu: 1,
+        memoryMiB: 512,
+        diskGiB: 32,
+      },
+    });
+  if (reason === "not-ready")
+    store.put("environment", "parent", { ...parent, state: "action_required" });
+  if (reason === "relative") input = { ...command, imageDirectory: "relative/path" };
+  if (reason === "existing") {
+    await mkdir(command.imageDirectory);
+    await writeFile(join(command.imageDirectory, "keep"), "existing data");
+  }
+  if (reason === "busy")
+    store.put("instance", "other", {
+      id: "other",
+      environmentId: "parent",
+      status: "running",
+      pid: 0,
+      createdAt: new Date().toISOString(),
+    });
+  if (reason === "paused") {
+    service.submit("pause", { type: "machine.pause", paused: true });
+    await service.drain();
+  }
+  if (reason === "large-script") input = { ...command, setupScript: "é".repeat(32769) };
+  const operation = await submit(input);
+  expect(await completed(operation.id)).toMatchObject({
+    status: expect.stringMatching(/failed|action_required/),
+  });
+  expect(start).not.toHaveBeenCalled();
+  expect(cloneProvisionImage).not.toHaveBeenCalled();
+  if (reason === "existing")
+    expect(await readFile(join(command.imageDirectory, "keep"), "utf8")).toBe("existing data");
+});
+
+test("remove refuses parents and preserves their backing file until the child is removed", async () => {
+  const { parent, store, service } = await fixture();
+  store.put("environment", "child", {
+    ...parent,
+    id: "child",
+    image: { parentId: "parent", revision: "revision", provisionedAt: new Date().toISOString() },
+  });
+  const refused = service.submit("remove-parent", { type: "environment.remove", id: "parent" });
+  await service.drain();
+  expect(store.snapshot().operations.find((item) => item.id === refused.id)).toMatchObject({
+    status: "failed",
+    result: { code: "environment_has_children" },
+  });
+  service.submit("remove-child", { type: "environment.remove", id: "child" });
+  service.submit("remove-parent-again", { type: "environment.remove", id: "parent" });
+  await service.drain();
+  expect(store.snapshot().environments).toHaveLength(0);
+  expect(await readFile(parent.basePath, "utf8")).toBe("parent remains immutable");
+});
+
+test("failed startup cleanup preserves output and blocks admission until exit is reconciled", async () => {
+  const { command, store, service, submit, completed, start } = await fixture();
+  start.mockRejectedValue(new VectisError("vm_start_failed", "Synthetic startup failure"));
+  vi.spyOn(service.runtime, "hasWorkDirectory").mockResolvedValue(true);
+  const operation = await submit();
+  expect(await completed(operation.id)).toMatchObject({
+    status: "action_required",
+    result: { code: "provision_cleanup_required" },
+  });
+  expect(service.snapshot().preparationBusy).toBe(true);
+  expect((await stat(command.imageDirectory)).isDirectory()).toBe(true);
+  await recoverProvisions(store);
+  expect(store.list("provision")).toHaveLength(1);
+  const instance = store.snapshot().instances[0];
+  if (!instance) throw new Error("Missing instance reservation");
+  store.put("instance", instance.id, { ...instance, status: "stopped" });
+  await recoverProvisions(store);
+  await expect(stat(command.imageDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+  expect(store.list("provision")).toHaveLength(0);
+});
+
+test.each([false, true])(
+  "crash recovery preserves a completed registration=%s and otherwise removes verified owned output",
+  async (registered) => {
+    const { command, parent, store } = await fixture();
+    const { operation } = store.accept("crashed", "crashed", command.type);
+    const record = {
+      id: operation.id,
+      environmentId: command.id,
+      directory: command.imageDirectory,
+    };
+    await mkdir(record.directory);
+    await writeFile(join(record.directory, ".vectis-provision.json"), JSON.stringify(record));
+    await writeFile(join(record.directory, "disk.img"), "owned output");
+    store.put("provision", record.id, record);
+    store.update(operation, { result: { stage: "freezing", shutdown: "forced_stop_after_sync" } });
+    if (registered)
+      store.put("environment", command.id, {
+        ...parent,
+        id: command.id,
+        basePath: join(record.directory, "disk.img"),
+        image: {
+          parentId: parent.id,
+          revision: operation.id,
+          provisionedAt: new Date().toISOString(),
+        },
+      });
+    await recoverProvisions(store);
+    expect(store.list("provision")).toHaveLength(0);
+    expect(store.snapshot().operations.find((item) => item.id === operation.id)?.status).toBe(
+      registered ? "succeeded" : "failed",
+    );
+    if (registered) {
+      expect(await readFile(join(record.directory, "disk.img"), "utf8")).toBe("owned output");
+      expect(
+        store.snapshot().operations.find((item) => item.id === operation.id)?.result,
+      ).toMatchObject({ shutdown: "forced_stop_after_sync" });
+    } else await expect(stat(record.directory)).rejects.toMatchObject({ code: "ENOENT" });
+  },
+);
+
+test("provisioning refuses to write output inside another registered macOS bundle", async () => {
+  const { home, parent, command, store, submit, completed } = await fixture();
+  const bundle = join(home, "other.bundle");
+  await mkdir(bundle);
+  store.put("environment", "other", { ...parent, id: "other", os: "macos", basePath: bundle });
+  const operation = await submit({ ...command, imageDirectory: join(bundle, "nested-output") });
+  expect(await completed(operation.id)).toMatchObject({
+    status: "failed",
+    result: { code: "invalid_path" },
+  });
+  expect(cloneProvisionImage).not.toHaveBeenCalled();
+});
diff --git a/apps/server/src/provision-task.ts b/apps/server/src/provision-task.ts
new file mode 100644
index 00000000..0b83e24e
--- /dev/null
+++ b/apps/server/src/provision-task.ts
@@ -0,0 +1,569 @@
+import { constants } from "node:fs";
+import { access, lstat, mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
+import { cpus, totalmem } from "node:os";
+import { setTimeout as delay } from "node:timers/promises";
+import { Schema } from "effect";
+import { VectisError, type Command, type Operation } from "../../../packages/protocol/src/index.js";
+import { readyGuest } from "../../../packages/runner/src/guest-ready.js";
+import { executeGuest, GuestUnavailableError } from "../../../packages/runner/src/guest.js";
+import { guestCommandDiagnostics } from "../../../packages/runner/src/guest-diagnostics.js";
+import { cloneProvisionImage } from "../../../packages/runner/src/provision-image.js";
+import {
+  provisionScript,
+  provisionLinuxIdentityResetScript,
+  provisionShutdownScript,
+  provisionMacosShutdownScript,
+  setupUploadScripts,
+} from "../../../packages/runner/src/provision-scripts.js";
+import { runnerVersion } from "../../../packages/runner/src/runner-release.js";
+import { windowsDefenderCommands } from "../../../packages/runner/src/windows-defender.js";
+import type { VmRuntime, OwnedInstance } from "../../../packages/runner/src/runtime.js";
+import { hasReservedEnvironment } from "./preparation-state.js";
+import { instanceAdmissionError } from "./runner-capacity.js";
+import type { Store } from "./store.js";
+
+const ProvisionRecord = Schema.Struct({
+  id: Schema.String,
+  environmentId: Schema.String,
+  directory: Schema.String,
+});
+type ProvisionRecord = typeof ProvisionRecord.Type;
+const ownerFile = ".vectis-provision.json";
+const ProvisionShutdown = Schema.Struct({
+  shutdown: Schema.Literals(["loginwindow", "sudo", "forced_stop_after_sync"]),
+});
+const GuestFailure = Schema.Struct({
+  diagnostics: Schema.String.check(Schema.isMaxLength(16384)),
+  exitCode: Schema.optional(Schema.Int),
+});
+
+async function removeOutput(record: ProvisionRecord) {
+  const directory = await lstat(record.directory).catch((error: unknown) => {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+    throw error;
+  });
+  if (!directory) return;
+  if (
+    !directory.isDirectory() ||
+    (await readFile(join(record.directory, ownerFile), "utf8")) !== JSON.stringify(record)
+  )
+    throw new VectisError(
+      "provision_cleanup_required",
+      "Cannot verify ownership of the partial provision directory.",
+    );
+  await rm(record.directory, { recursive: true, force: true, maxRetries: 3 });
+}
+
+export async function recoverProvisions(store: Store) {
+  for (const value of store.list("provision")) {
+    const record = Schema.decodeUnknownSync(ProvisionRecord)(value);
+    const operation = store.snapshot().operations.find((item) => item.id === record.id);
+    if (!operation) continue;
+    const guestFailure = Schema.is(GuestFailure)(operation.result)
+      ? {
+          diagnostics: operation.result.diagnostics,
+          ...(operation.result.exitCode !== undefined
+            ? { exitCode: operation.result.exitCode }
+            : {}),
+        }
+      : undefined;
+    const registered = store
+      .snapshot()
+      .environments.find(
+        (item) => item.id === record.environmentId && item.image?.revision === record.id,
+      );
+    const shutdown = Schema.is(ProvisionShutdown)(operation.result)
+      ? { shutdown: operation.result.shutdown }
+      : {};
+    if (registered) {
+      store.update(operation, {
+        status: "succeeded",
+        message: "Provisioned environment registration recovered.",
+        result: { stage: "finished", environment: registered, ...shutdown },
+      });
+      store.remove("provision", record.id);
+      continue;
+    }
+    const instance = store.snapshot().instances.find((item) => item.id === record.id);
+    if (instance && instance.status !== "stopped") continue;
+    try {
+      await removeOutput(record);
+      store.remove("provision", record.id);
+      store.update(operation, {
+        status: "failed",
+        message: "Interrupted provisioning was cleaned up. Retry with a new operation key.",
+        result: { stage: "cleaned", code: "provision_interrupted", ...guestFailure },
+      });
+    } catch {
+      store.update(operation, {
+        status: "action_required",
+        message: "Provisioning cleanup needs inspection of its owned output.",
+        result: {
+          stage: "cleaning",
+          directory: record.directory,
+          code: "provision_cleanup_required",
+          ...guestFailure,
+        },
+      });
+    }
+  }
+}
+
+async function waitForShutdown(instance: OwnedInstance, signal: AbortSignal, timeoutMs: number) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let cancel = () => {};
+  try {
+    await new Promise<void>((resolve, reject) => {
+      timer = setTimeout(
+        () =>
+          reject(
+            new VectisError(
+              "guest_shutdown_timeout",
+              "The guest did not shut down cleanly before the timeout.",
+            ),
+          ),
+        timeoutMs,
+      );
+      cancel = () => reject(signal.reason);
+      signal.addEventListener("abort", cancel, { once: true });
+      instance.settled.then(resolve, reject);
+      if (signal.aborted) cancel();
+    });
+  } finally {
+    clearTimeout(timer);
+    signal.removeEventListener("abort", cancel);
+  }
+}
+
+async function stopProvisionVm(
+  runtime: VmRuntime,
+  instance: OwnedInstance,
+  signal: AbortSignal,
+  timeoutMs: number,
+) {
+  const waiting = new AbortController();
+  try {
+    await Promise.race([
+      runtime.stop(instance.id).then(() => instance.settled),
+      waitForShutdown(instance, AbortSignal.any([signal, waiting.signal]), timeoutMs),
+    ]);
+  } finally {
+    waiting.abort();
+  }
+}
+
+export async function startProvision(
+  store: Store,
+  runtime: VmRuntime,
+  operation: Operation,
+  command: Extract<Command, { type: "environment.provision" }>,
+  options: {
+    shutdownTimeoutMs?: number;
+    shutdownCommandTimeoutMs?: number;
+    syncDelayMs?: number;
+  } = {},
+) {
+  const snapshot = store.snapshot();
+  if (
+    snapshot.preparationBusy ||
+    store.list("provision").length ||
+    snapshot.instances.some((item) => item.status !== "stopped") ||
+    snapshot.operations.some(
+      (item) =>
+        item.command === "runner.run" &&
+        ["accepted", "running", "action_required"].includes(item.status),
+    )
+  )
+    throw new VectisError(
+      "preparation_busy",
+      "Provisioning requires an idle machine with no unresolved preparations or runners.",
+    );
+  if (snapshot.machine.paused)
+    throw new VectisError("machine_paused", "Resume the machine before provisioning a guest.");
+  const parent = snapshot.environments.find((item) => item.id === command.from);
+  if (!parent)
+    throw new VectisError("environment_missing", "The parent environment was not found.");
+  if (parent.state !== "ready")
+    throw new VectisError("setup_required", "The parent environment must be ready.");
+  if (
+    snapshot.environments.some((item) => item.id === command.id) ||
+    hasReservedEnvironment(store, command.id)
+  )
+    throw new VectisError(
+      "environment_exists",
+      "This environment already exists or has a preparation to resume.",
+    );
+  if (command.setupScript !== undefined && Buffer.byteLength(command.setupScript, "utf8") > 65536)
+    throw new VectisError("guest_script_too_large", "Setup scripts cannot exceed 64 KiB UTF-8.");
+  if (!isAbsolute(command.imageDirectory))
+    throw new VectisError(
+      "invalid_path",
+      "The provision image directory must be an absolute host path.",
+    );
+  const directory = join(
+    await realpath(dirname(command.imageDirectory)),
+    basename(command.imageDirectory),
+  );
+  for (const environment of snapshot.environments.filter((item) => item.os === "macos")) {
+    const bundle = await realpath(environment.basePath).catch(() => undefined);
+    if (!bundle) continue;
+    const inside = relative(bundle, directory);
+    if (!inside || (!inside.startsWith("../") && !isAbsolute(inside)))
+      throw new VectisError(
+        "invalid_path",
+        "Provision output must be outside registered macOS bundles.",
+      );
+  }
+  if (
+    await lstat(directory).catch((error: unknown) => {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+      throw error;
+    })
+  )
+    throw new VectisError(
+      "image_directory_exists",
+      "Provisioning requires a new image directory; existing paths are preserved.",
+    );
+  await access(dirname(directory), constants.W_OK | constants.X_OK);
+  await runtime.validate(parent);
+  const admission = instanceAdmissionError(snapshot, parent, {
+    cpus: cpus().length,
+    memoryBytes: totalmem(),
+  });
+  if (admission) throw admission;
+  const record = { id: operation.id, environmentId: command.id, directory };
+  store.put("provision", operation.id, record);
+  const abort = new AbortController();
+  const signal = AbortSignal.any([abort.signal, AbortSignal.timeout(3600000)]);
+  let created = false;
+  let instance: OwnedInstance | undefined;
+  let stage = "cloning";
+  let guestFailure: typeof GuestFailure.Type | undefined;
+  let shutdown: typeof ProvisionShutdown.Type | undefined;
+  const progress = (value: string) => {
+    stage = value;
+    operation = store.update(operation, {
+      message: `Environment provisioning: ${stage}.`,
+      result: {
+        stage,
+        environmentId: command.id,
+        parentId: parent.id,
+        directory,
+        instanceId: operation.id,
+        ...guestFailure,
+        ...shutdown,
+      },
+    });
+  };
+  const done = (async () => {
+    signal.throwIfAborted();
+    progress("cloning");
+    await mkdir(directory, { mode: 0o700 });
+    created = true;
+    await writeFile(join(directory, ownerFile), JSON.stringify(record), {
+      flag: "wx",
+      mode: 0o600,
+    });
+    let environment = await cloneProvisionImage(
+      parent,
+      command.id,
+      directory,
+      runtime.options,
+      signal,
+    );
+    environment = { ...environment, name: command.name ?? command.id };
+    progress("booting");
+    const instanceRecord = {
+      id: operation.id,
+      environmentId: environment.id,
+      directory: runtime.directoryFor(operation.id, environment),
+      cpu: environment.cpu,
+      memoryMiB: environment.memoryMiB,
+      status: "starting" as const,
+      pid: 0,
+      createdAt: operation.createdAt,
+    };
+    store.put("instance", operation.id, instanceRecord);
+    instance = await runtime.start(
+      operation.id,
+      environment,
+      (cleaned) => {
+        const current =
+          store.snapshot().instances.find((item) => item.id === operation.id) ?? instanceRecord;
+        store.put("instance", operation.id, {
+          ...current,
+          status: cleaned ? "stopped" : "interrupted",
+        });
+      },
+      signal,
+      { diskInPlace: true },
+    );
+    const running = {
+      ...instanceRecord,
+      status: "running" as const,
+      pid: instance.process.pid ?? 0,
+      ...(instance.macAddress ? { macAddress: instance.macAddress } : {}),
+      ...(instance.sshHost ? { sshHost: instance.sshHost } : {}),
+      ...(instance.sshPort ? { sshPort: instance.sshPort } : {}),
+      ...(instance.knownHostsPath ? { knownHostsPath: instance.knownHostsPath } : {}),
+    };
+    store.put("instance", operation.id, running);
+    progress("waiting_for_guest");
+    const connection = await readyGuest(environment, running, signal);
+    const shell = environment.os === "windows" ? "powershell" : "bash";
+    const runGuest = async (
+      script: string,
+      options: {
+        signal?: AbortSignal;
+        shell?: "powershell" | "bash" | "cmd";
+        allowFailure?: boolean;
+      } = {},
+    ) => {
+      try {
+        const result = await executeGuest(connection, script, {
+          shell: options.shell ?? shell,
+          signal: options.signal ?? signal,
+        });
+        if (result.exitCode !== 0 && !options.allowFailure)
+          guestFailure = {
+            exitCode: result.exitCode,
+            diagnostics: guestCommandDiagnostics(result),
+          };
+        return result;
+      } catch (error) {
+        if (error instanceof GuestUnavailableError)
+          guestFailure = {
+            diagnostics: guestCommandDiagnostics({ stderr: error.detail, stdout: "" }),
+          };
+        throw error;
+      }
+    };
+    if (environment.os === "linux") {
+      progress("checking_guest_sudo");
+      if ((await runGuest("sudo -n true")).exitCode !== 0)
+        throw new VectisError(
+          "provision_requires_guest_sudo",
+          "Linux provisioning requires passwordless sudo to reset the derived image's machine identity.",
+          "Prepare a new Linux environment with this Vectis version, then provision from it.",
+        );
+    }
+    progress("provisioning");
+    if (environment.os === "windows") {
+      for (const command of windowsDefenderCommands()) {
+        const result = await runGuest(command.script, command);
+        if (result.exitCode !== 0 && !command.allowFailure)
+          throw new VectisError(
+            "provision_script_failed",
+            "Windows Defender guest configuration failed. No environment was registered.",
+          );
+      }
+    }
+    const scripts = [
+      ...(command.setupScript !== undefined
+        ? setupUploadScripts(environment.os, command.setupScript)
+        : []),
+      provisionScript(environment.os, {
+        runner: command.runner !== false,
+        setup: command.setupScript !== undefined,
+      }),
+    ];
+    for (const script of scripts) {
+      const result = await runGuest(script);
+      if (result.exitCode !== 0)
+        throw new VectisError(
+          "provision_script_failed",
+          "The guest provisioning script failed. No environment was registered.",
+        );
+    }
+    if (environment.os === "linux") {
+      progress("clearing_identity");
+      if ((await runGuest(provisionLinuxIdentityResetScript())).exitCode !== 0)
+        throw new VectisError(
+          "provision_identity_reset_failed",
+          "Linux identity cleanup failed. No environment was registered.",
+        );
+    }
+    progress("shutting_down");
+    if (environment.os === "macos") {
+      const provisioningInstance = instance;
+      const shutdownTimeoutMs = options.shutdownTimeoutMs ?? 60000;
+      const commandTimeoutMs = options.shutdownCommandTimeoutMs ?? 30000;
+      const wait = async () => {
+        try {
+          await waitForShutdown(provisioningInstance, signal, shutdownTimeoutMs);
+          return true;
+        } catch (error) {
+          if (error instanceof VectisError && error.code === "guest_shutdown_timeout") return false;
+          throw error;
+        }
+      };
+      const attempt = async (script: string) => {
+        signal.throwIfAborted();
+        const commandSignal = AbortSignal.any([signal, AbortSignal.timeout(commandTimeoutMs)]);
+        try {
+          return await runGuest(script, { signal: commandSignal, allowFailure: true });
+        } catch (error) {
+          signal.throwIfAborted();
+          if (!(error instanceof GuestUnavailableError) && !commandSignal.aborted) throw error;
+          return undefined;
+        }
+      };
+      await attempt(provisionMacosShutdownScript());
+      if (await wait()) {
+        shutdown = { shutdown: "loginwindow" };
+      } else {
+        const sudo = await attempt("sudo -n true");
+        if (sudo?.exitCode === 0) await attempt(provisionShutdownScript("macos"));
+        if (sudo?.exitCode === 0 && (await wait())) {
+          shutdown = { shutdown: "sudo" };
+        } else {
+          progress("syncing_before_forced_stop");
+          for (let count = 0; count < 2; count++) {
+            const synced = await runGuest("sync", {
+              signal: AbortSignal.any([signal, AbortSignal.timeout(commandTimeoutMs)]),
+            });
+            if (synced.exitCode !== 0)
+              throw new VectisError(
+                "provision_sync_failed",
+                "Guest sync failed. The provisioned image cannot be frozen after a forced stop.",
+              );
+          }
+          await delay(options.syncDelayMs ?? 5000, undefined, { signal });
+          signal.throwIfAborted();
+          if (instance.process.exitCode !== null || instance.process.signalCode !== null) {
+            await waitForShutdown(instance, signal, commandTimeoutMs);
+            shutdown = { shutdown: sudo?.exitCode === 0 ? "sudo" : "loginwindow" };
+          } else {
+            await stopProvisionVm(runtime, instance, signal, commandTimeoutMs);
+            shutdown = { shutdown: "forced_stop_after_sync" };
+          }
+        }
+      }
+      guestFailure = undefined;
+    } else {
+      if (!(await runtime.requestShutdown(instance.id))) {
+        try {
+          const shutdown = await runGuest(provisionShutdownScript(environment.os), {
+            signal: AbortSignal.any([signal, AbortSignal.timeout(30000)]),
+          });
+          if (shutdown.exitCode !== 0)
+            throw new VectisError(
+              "guest_shutdown_failed",
+              "Guest shutdown failed. Inspect the guest command diagnostics and passwordless sudo permissions.",
+            );
+        } catch (error) {
+          if (!(error instanceof GuestUnavailableError)) throw error;
+        }
+      }
+      await waitForShutdown(instance, signal, options.shutdownTimeoutMs ?? 120000);
+    }
+    if (instance.process.exitCode !== 0 || instance.process.signalCode !== null)
+      throw new VectisError(
+        "guest_shutdown_failed",
+        "The provisioning VM did not exit successfully.",
+      );
+    instance = undefined;
+    progress("freezing");
+    environment = {
+      ...environment,
+      image: {
+        parentId: parent.id,
+        revision: operation.id,
+        provisionedAt: new Date().toISOString(),
+        ...(command.runner !== false ? { runnerVersion } : {}),
+      },
+    };
+    await runtime.validate(environment);
+    await writeFile(join(directory, "image.json"), JSON.stringify(environment.image), {
+      flag: "wx",
+      mode: 0o600,
+    });
+    signal.throwIfAborted();
+    store.db.exec("BEGIN IMMEDIATE");
+    try {
+      store.put("environment", environment.id, environment);
+      store.remove("provision", operation.id);
+      store.update(operation, {
+        status: "succeeded",
+        message:
+          shutdown?.shutdown === "forced_stop_after_sync"
+            ? "Derived environment frozen after a forced stop following two guest syncs and registered. The parent image was preserved."
+            : "Derived environment provisioned and registered. The parent image was preserved.",
+        result: { stage: "finished", environment, ...shutdown },
+      });
+      store.db.exec("COMMIT");
+    } catch (error) {
+      store.db.exec("ROLLBACK");
+      throw error;
+    }
+  })().catch(async (error: unknown) => {
+    progress("cleaning");
+    try {
+      if (instance) {
+        if (instance.process.exitCode === null && instance.process.signalCode === null) {
+          if (parent.os === "macos")
+            await stopProvisionVm(
+              runtime,
+              instance,
+              new AbortController().signal,
+              options.shutdownCommandTimeoutMs ?? 30000,
+            );
+          else await runtime.stop(instance.id);
+        } else if (parent.os === "macos") {
+          await waitForShutdown(
+            instance,
+            new AbortController().signal,
+            options.shutdownCommandTimeoutMs ?? 30000,
+          );
+        } else await instance.settled;
+      }
+      const current = store.snapshot().instances.find((item) => item.id === operation.id);
+      if (current && current.status !== "stopped") {
+        if (await runtime.hasWorkDirectory(operation.id, current.directory)) {
+          store.put("instance", current.id, { ...current, status: "interrupted" });
+          throw new VectisError(
+            "provision_cleanup_required",
+            "Provisioning VM cleanup is unconfirmed.",
+          );
+        }
+        store.put("instance", current.id, { ...current, status: "stopped", pid: 0 });
+      }
+      if (created) await removeOutput(record);
+      store.remove("provision", operation.id);
+      store.update(operation, {
+        status: signal.aborted ? "cancelled" : "failed",
+        message: signal.aborted
+          ? "Provisioning cancelled and owned output removed."
+          : error instanceof VectisError
+            ? error.message
+            : "Environment provisioning failed and owned output was removed.",
+        result: {
+          stage: "cleaned",
+          ...guestFailure,
+          code: signal.aborted
+            ? "provision_cancelled"
+            : error instanceof VectisError
+              ? error.code
+              : "provision_failed",
+          ...(error instanceof VectisError && error.nextStep ? { nextStep: error.nextStep } : {}),
+        },
+      });
+    } catch {
+      store.update(operation, {
+        status: "action_required",
+        message: "Provisioning stopped, but VM exit or output cleanup needs verification.",
+        result: {
+          stage,
+          ...guestFailure,
+          directory,
+          instanceId: operation.id,
+          code: "provision_cleanup_required",
+          nextStep:
+            "Reconcile the interrupted instance, then restart the service to retry owned output cleanup.",
+        },
+      });
+    }
+  });
+  return { abort, done };
+}
diff --git a/apps/server/src/repository-readiness.test.ts b/apps/server/src/repository-readiness.test.ts
index 5434dd7d..956cf914 100644
--- a/apps/server/src/repository-readiness.test.ts
+++ b/apps/server/src/repository-readiness.test.ts
@@ -6,6 +6,7 @@ import { VectisError } from "../../../packages/protocol/src/index.js";
 import type { CloudRepositoryReadiness } from "../../../packages/protocol/src/readiness.js";
 import { startService } from "./http.js";
 import { VectisClient } from "../../../packages/client/src/index.js";
+import { recordCacheGuestPrivilege } from "./cache-guest-privilege.js";
 
 const cloud: CloudRepositoryReadiness = {
   environmentId: "linux",
@@ -23,6 +24,46 @@ const cloud: CloudRepositoryReadiness = {
     },
   ],
 };
+
+test("cache readiness reports persistent attention only for an enabled cache on the probed image", async () => {
+  const { server, close } = await fixture();
+  try {
+    const environment = server.store.snapshot().environments[0];
+    if (!environment) throw new Error("Missing synthetic environment");
+    const readCloud = async () => ({ ...cloud, cacheVolumeEnabled: true });
+    const readiness = () => server.service.repositoryReadiness({ bindingId: "binding" }, readCloud);
+    expect(
+      (await readiness()).checks.find((check) => check.id === "cache.guest_sudo")?.status,
+    ).toBe("unknown");
+    recordCacheGuestPrivilege(server.store, environment, false);
+    expect((await readiness()).checks).toContainEqual(
+      expect.objectContaining({
+        id: "cache.guest_sudo",
+        status: "attention",
+        code: "cache_volume_requires_guest_sudo",
+        nextStep: expect.any(String),
+      }),
+    );
+    const disabled = await server.service.repositoryReadiness(
+      { bindingId: "binding" },
+      async () => ({ ...cloud, cacheVolumeEnabled: false }),
+    );
+    expect(disabled.checks.some((check) => check.id === "cache.guest_sudo")).toBe(false);
+    recordCacheGuestPrivilege(server.store, environment, true);
+    expect(
+      (await readiness()).checks.find((check) => check.id === "cache.guest_sudo")?.status,
+    ).toBe("ok");
+    server.store.put("environment", environment.id, {
+      ...environment,
+      image: { revision: "replacement", provisionedAt: "now" },
+    });
+    expect(
+      (await readiness()).checks.find((check) => check.id === "cache.guest_sudo")?.status,
+    ).toBe("unknown");
+  } finally {
+    await close();
+  }
+});
 async function fixture() {
   const home = await mkdtemp(join(tmpdir(), "vectis-readiness-"));
   const server = await startService({ home });
diff --git a/apps/server/src/repository-readiness.ts b/apps/server/src/repository-readiness.ts
index c2a9fb08..648e539c 100644
--- a/apps/server/src/repository-readiness.ts
+++ b/apps/server/src/repository-readiness.ts
@@ -5,11 +5,13 @@ import type {
   RepositoryReadinessInput,
 } from "../../../packages/protocol/src/readiness.js";
 import { VectisError, type Environment } from "../../../packages/protocol/src/index.js";
+import { cachePrivilegeError } from "../../../packages/runner/src/cache-guest.js";
 
 export async function repositoryReadiness(
   input: RepositoryReadinessInput,
   environments: () => readonly Environment[],
   readCloud: (input: RepositoryReadinessInput) => Promise<CloudRepositoryReadiness>,
+  cachePrivilege: (environment: Environment) => boolean | undefined = () => undefined,
 ): Promise<RepositoryReadiness> {
   let cloud: CloudRepositoryReadiness | undefined;
   const checks: ReadinessCheck[] = [];
@@ -87,6 +89,27 @@ export async function repositoryReadiness(
         }),
   };
   checks.splice(checks.length - 1, 0, check);
+  if (cloud?.cacheVolumeEnabled && environment) {
+    const allowed = cachePrivilege(environment);
+    const error = cachePrivilegeError();
+    checks.splice(checks.length - 1, 0, {
+      id: "cache.guest_sudo",
+      status: allowed === false ? "attention" : allowed ? "ok" : "unknown",
+      message:
+        allowed === false
+          ? error.message
+          : allowed
+            ? "The guest has the privileges needed to mount cache volumes."
+            : "Cache mount privileges have not been checked for this environment image.",
+      ...(allowed === false
+        ? {
+            code: error.code,
+            nextStep: error.nextStep,
+            target: { area: "environments", section: environment.id } as const,
+          }
+        : {}),
+    });
+  }
   return {
     checks,
     ready: checks.every((check) => check.status === "ok" || check.status === "attention"),
diff --git a/apps/server/src/resource-probe.test.ts b/apps/server/src/resource-probe.test.ts
new file mode 100644
index 00000000..42dfa5d3
--- /dev/null
+++ b/apps/server/src/resource-probe.test.ts
@@ -0,0 +1,88 @@
+import { expect, test, vi } from "vitest";
+import type { Instance } from "../../../packages/protocol/src/index.js";
+import { createResourceProbe } from "./resource-probe.js";
+
+const instance: Instance = {
+  id: "owned",
+  environmentId: "linux",
+  status: "running",
+  pid: 123,
+  createdAt: "",
+};
+
+test("probes share in-flight work and cache results for five seconds", async () => {
+  let time = 0;
+  let rss = "3145728";
+  let pressure = "1";
+  const read = vi.fn(async (file: string) => (file === "/bin/ps" ? rss : pressure));
+  const probe = createResourceProbe(read, () => time);
+  expect(probe([instance])).toMatchObject({ pressure: "normal", pressureKnown: false });
+  probe([instance]);
+  expect(read).toHaveBeenCalledTimes(2);
+  await vi.waitFor(() => expect(probe([instance]).pressureKnown).toBe(true));
+  expect(probe([instance]).footprintsMiB.get(instance.id)).toBe(3072);
+  expect(read).toHaveBeenCalledWith("/bin/ps", ["-o", "rss=", "-p", "123"]);
+  expect(read).toHaveBeenCalledWith("/usr/sbin/sysctl", [
+    "-n",
+    "kern.memorystatus_vm_pressure_level",
+  ]);
+  time = 4999;
+  probe([instance]);
+  expect(read).toHaveBeenCalledTimes(2);
+  time = 5000;
+  rss = "4194304";
+  pressure = "2";
+  probe([instance]);
+  probe([instance]);
+  expect(read).toHaveBeenCalledTimes(4);
+  await vi.waitFor(() => expect(probe([instance]).pressure).toBe("warning"));
+  expect(probe([instance]).footprintsMiB.get(instance.id)).toBe(4096);
+});
+
+test("PID changes and stopped instances discard cached footprints", async () => {
+  const read = vi.fn(async (file: string) => (file === "/bin/ps" ? "1048576" : "4"));
+  const probe = createResourceProbe(read);
+  probe([instance, { ...instance, id: "stopped", status: "stopped", pid: 999 }]);
+  await vi.waitFor(() => expect(probe([instance]).pressureKnown).toBe(true));
+  expect(probe([instance]).pressure).toBe("critical");
+  const changed = { ...instance, pid: 456 };
+  expect(probe([changed]).footprintsMiB.size).toBe(0);
+  await vi.waitFor(() => expect(probe([changed]).footprintsMiB.get(instance.id)).toBe(1024));
+  expect(read).toHaveBeenCalledTimes(3);
+  expect(probe([{ ...changed, status: "stopped" }]).footprintsMiB.size).toBe(0);
+  expect(probe([changed]).footprintsMiB.size).toBe(0);
+  expect(read).toHaveBeenCalledTimes(4);
+});
+
+test.each(["", "garbage", "-10", "1.5", "Infinity"])(
+  "invalid probe output %j remains unknown",
+  async (output) => {
+    const read = vi.fn(async () => output);
+    const probe = createResourceProbe(read);
+    probe([instance, { ...instance, id: "new", pid: 0, status: "starting" }]);
+    await vi.waitFor(() => expect(read).toHaveResolvedTimes(2));
+    expect(probe([instance])).toEqual({
+      footprintsMiB: new Map(),
+      pressure: "normal",
+      pressureKnown: false,
+    });
+    expect(read).toHaveBeenCalledTimes(2);
+  },
+);
+
+test("failed probes are cached and replace stale data with unknown", async () => {
+  let time = 0;
+  const read = vi.fn(async (file: string) => (file === "/bin/ps" ? "1048576" : "2"));
+  const probe = createResourceProbe(read, () => time);
+  probe([instance]);
+  await vi.waitFor(() => expect(probe([instance]).pressure).toBe("warning"));
+  time = 5000;
+  read.mockRejectedValue(new Error("Probe timed out"));
+  probe([instance]);
+  await vi.waitFor(() => expect(probe([instance]).pressureKnown).toBe(false));
+  expect(probe([instance]).footprintsMiB.size).toBe(0);
+  expect(read).toHaveBeenCalledTimes(4);
+  time = 9999;
+  probe([instance]);
+  expect(read).toHaveBeenCalledTimes(4);
+});
diff --git a/apps/server/src/resource-probe.ts b/apps/server/src/resource-probe.ts
new file mode 100644
index 00000000..69b8f63b
--- /dev/null
+++ b/apps/server/src/resource-probe.ts
@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { Instance } from "../../../packages/protocol/src/index.js";
+
+type Pressure = "normal" | "warning" | "critical";
+export type ResourceUsage = {
+  footprintsMiB: ReadonlyMap<string, number>;
+  pressure: Pressure;
+  pressureKnown: boolean;
+};
+export type ResourceProbe = (instances: readonly Instance[]) => ResourceUsage;
+
+const execute = promisify(execFile);
+async function readResource(file: string, args: string[]): Promise<string> {
+  const { stdout } = await execute(file, args, { timeout: 1000, maxBuffer: 1024 });
+  return stdout;
+}
+
+type Measurement = { value?: string; expiresAt: number; pending: boolean };
+
+export function createResourceProbe(read = readResource, now = Date.now): ResourceProbe {
+  const footprints = new Map<string, Measurement>();
+  const pressure: Measurement = { expiresAt: 0, pending: false };
+  function cached(entry: Measurement, file: string, args: string[]) {
+    if (!entry.pending && now() >= entry.expiresAt) {
+      entry.pending = true;
+      void read(file, args)
+        .then((value) => {
+          entry.value = value.trim();
+        })
+        .catch(() => {
+          delete entry.value;
+        })
+        .finally(() => {
+          entry.expiresAt = now() + 5000;
+          entry.pending = false;
+        });
+    }
+    return entry.value;
+  }
+  return (instances) => {
+    const live = instances.filter(
+      (instance) =>
+        instance.status !== "stopped" && Number.isSafeInteger(instance.pid) && instance.pid > 0,
+    );
+    const keys = new Set(live.map((instance) => `${instance.id}:${instance.pid}`));
+    for (const key of footprints.keys()) if (!keys.has(key)) footprints.delete(key);
+    const footprintsMiB = new Map<string, number>();
+    for (const instance of live) {
+      const key = `${instance.id}:${instance.pid}`;
+      let entry = footprints.get(key);
+      if (!entry) {
+        entry = { expiresAt: 0, pending: false };
+        footprints.set(key, entry);
+      }
+      const value = cached(entry, "/bin/ps", ["-o", "rss=", "-p", String(instance.pid)]);
+      const rss = value && /^\d+$/.test(value) ? Number(value) : undefined;
+      if (rss !== undefined && Number.isSafeInteger(rss))
+        footprintsMiB.set(instance.id, rss / 1024);
+    }
+    const value = cached(pressure, "/usr/sbin/sysctl", [
+      "-n",
+      "kern.memorystatus_vm_pressure_level",
+    ]);
+    return {
+      footprintsMiB,
+      pressure: value === "2" ? "warning" : value === "4" ? "critical" : "normal",
+      pressureKnown: value === "1" || value === "2" || value === "4",
+    };
+  };
+}
+
+export const resourceProbe = createResourceProbe();
diff --git a/apps/server/src/runner-capacity.test.ts b/apps/server/src/runner-capacity.test.ts
index 93161595..4b06ae4b 100644
--- a/apps/server/src/runner-capacity.test.ts
+++ b/apps/server/src/runner-capacity.test.ts
@@ -1,6 +1,22 @@
-import { expect, test } from "vitest";
+import { expect, test, vi } from "vitest";
+import { Schema } from "effect";
+import { Snapshot as SnapshotSchema } from "../../../packages/protocol/src/index.js";
 import type { Environment, Snapshot, Operation } from "../../../packages/protocol/src/index.js";
-import { instanceAdmissionError, runnerCapacity } from "./runner-capacity.js";
+import { instanceAdmissionError as admit, runnerCapacity as capacity } from "./runner-capacity.js";
+import { estimatedVmMemoryMiB } from "../../../packages/runner/src/memory.js";
+import type { ResourceProbe } from "./resource-probe.js";
+
+const probe: ResourceProbe = (instances) => ({
+  footprintsMiB: new Map(
+    instances.map((instance) => [instance.id, Math.min(instance.memoryMiB ?? 2048, 2048)]),
+  ),
+  pressure: "normal",
+  pressureKnown: true,
+});
+const runnerCapacity = (state: Snapshot, machine: typeof host) =>
+  capacity(state, machine, { probe });
+const instanceAdmissionError = (state: Snapshot, env: Environment, machine: typeof host) =>
+  admit(state, env, machine, 1, probe);
 
 const host = { cpus: 14, memoryBytes: 48 * 1024 ** 3 };
 const environment: Environment = {
@@ -23,38 +39,145 @@ function snapshot(env = environment) {
   return { ...base, machine: { ...base.machine } };
 }
 function running(env = environment): Snapshot["instances"][number] {
-  return { id: "instance", environmentId: env.id, status: "running", pid: 0, createdAt: "" };
+  return {
+    id: "instance",
+    environmentId: env.id,
+    status: "running",
+    memoryMiB: env.memoryMiB,
+    pid: 0,
+    createdAt: "",
+  };
 }
 function operation(status: Operation["status"], command = "runner.run"): Operation {
   return { id: status, key: status, command, status, createdAt: "", updatedAt: "", message: "" };
 }
 
+test("warm VMs are reclaimable capacity while their actual memory remains visible", () => {
+  const state = snapshot({ ...environment, memoryMiB: 2048 });
+  state.machine.memoryBudgetMiB = 4096;
+  state.instances = [
+    { ...running(), memoryMiB: 2048, role: "warm" },
+    { ...running(), id: "booting", memoryMiB: 2048, status: "starting", role: "warming" },
+  ];
+  expect(runnerCapacity(state, host)).toMatchObject({
+    active: 0,
+    available: 2,
+    budget: { memoryCommittedMiB: 4096 },
+  });
+  state.instances = state.instances.map((instance) => ({ ...instance, status: "interrupted" }));
+  expect(runnerCapacity(state, host).available).toBe(0);
+});
+
 test("defaults to five runners and counts only unfinished runner operations", () => {
   const state = snapshot({ ...environment, cpu: 1, memoryMiB: 512 });
   state.operations = (
     ["accepted", "running", "action_required", "succeeded", "failed", "cancelled"] as const
   ).map((status) => operation(status));
-  expect(runnerCapacity(state, host)).toEqual({ max: 5, active: 3, available: 2 });
+  expect(runnerCapacity(state, host)).toMatchObject({ max: 5, active: 2, available: 3 });
   state.machine.maxRunners = 2;
-  expect(runnerCapacity(state, host)).toEqual({ max: 2, active: 3, available: 0 });
+  expect(runnerCapacity(state, host)).toMatchObject({ max: 2, active: 2, available: 0 });
 });
 
-test("CPU budget accounts for running instances and their resource overrides", () => {
+test("five VMs with ceilings above host RAM and CPU cores admit another when footprints fit", () => {
+  const env = { ...environment, cpu: 8 };
+  const state = snapshot(env);
+  state.instances = Array.from({ length: 5 }, (_, index) => ({
+    ...running(),
+    id: `vm${index}`,
+    cpu: 8,
+    pid: index + 1,
+  }));
+  expect(state.instances.length * environment.memoryMiB).toBeGreaterThan(
+    host.memoryBytes / 1024 ** 2,
+  );
+  expect(instanceAdmissionError(state, env, host)).toBeUndefined();
+  expect(runnerCapacity(state, host).budget).toEqual({
+    memoryBudgetMiB: 36864,
+    memoryCommittedMiB: 10240,
+    hostMemoryMiB: 49152,
+    pressure: "normal",
+    pressureKnown: true,
+  });
+  expect(instanceAdmissionError(state, { ...environment, cpu: 15 }, host)).toMatchObject({
+    code: "invalid_resources",
+  });
+});
+
+test("admission uses measured footprints, floors, overrides and configured fallback", () => {
   const state = snapshot();
+  state.machine.memoryBudgetMiB = 8192;
+  state.instances = [{ ...running(), memoryMiB: 4096 }];
+  const usage: ResourceProbe = () => ({
+    footprintsMiB: new Map([["instance", 7000]]),
+    pressure: "normal",
+    pressureKnown: true,
+  });
+  expect(admit(state, environment, host, 1, usage)).toMatchObject({
+    code: "memory_budget_exceeded",
+    nextStep: expect.any(String),
+  });
+  expect(runnerCapacity(state, host).available).toBe(3);
+  const missing: ResourceProbe = () => ({ ...probe([]), footprintsMiB: new Map() });
+  expect(capacity(state, host, { probe: missing }).budget?.memoryCommittedMiB).toBe(4096);
+  expect(capacity(state, host, { probe: missing }).available).toBe(2);
   state.instances = [running()];
-  expect(runnerCapacity(state, host).available).toBe(1);
-  state.instances = [{ ...running(), cpu: 10, memoryMiB: 512 }];
-  expect(runnerCapacity(state, host).available).toBe(0);
+  expect(admit(state, environment, host, 1, missing)).toMatchObject({
+    code: "memory_budget_exceeded",
+  });
+  expect(capacity(state, host, { probe: missing }).available).toBe(0);
 });
 
-test("memory budget allows at most 75 percent of host memory", () => {
-  const env = { ...environment, cpu: 1, memoryMiB: 18432 };
-  const state = snapshot(env);
-  expect(runnerCapacity(state, host).available).toBe(2);
-  state.instances = [running(env)];
-  expect(runnerCapacity(state, host).available).toBe(1);
-  state.instances = [{ ...running(env), memoryMiB: 18433 }];
-  expect(runnerCapacity(state, host).available).toBe(0);
+test.each(["warning", "critical"] as const)(
+  "%s memory pressure closes admission and slots",
+  (pressure) => {
+    const state = snapshot();
+    const pressured: ResourceProbe = () => ({ ...probe([]), pressure });
+    expect(admit(state, environment, host, 1, pressured)).toMatchObject({
+      code: "memory_pressure",
+      nextStep: expect.any(String),
+    });
+    expect(capacity(state, host, { probe: pressured })).toMatchObject({
+      available: 0,
+      budget: { pressure, pressureKnown: true },
+    });
+    const unknown: ResourceProbe = () => ({ ...probe([]), pressureKnown: false });
+    expect(capacity(state, host, { probe: unknown })).toMatchObject({
+      available: 5,
+      budget: { pressure: "normal", pressureKnown: false },
+    });
+  },
+);
+
+test("per-environment slots share measured memory with OS startup estimates and one probe", () => {
+  const state = snapshot();
+  state.machine.memoryBudgetMiB = 10240;
+  state.instances = [running()];
+  state.environments = [
+    environment,
+    { ...environment, id: "mac", os: "macos" },
+    { ...environment, id: "win", os: "windows" },
+  ];
+  const measured = vi.fn(probe);
+  expect(capacity(state, host, { probe: measured }).environments).toEqual([
+    { environmentId: "linux", available: 4 },
+    { environmentId: "mac", available: 2 },
+    { environmentId: "win", available: 2 },
+  ]);
+  expect(measured).toHaveBeenCalledOnce();
+});
+
+test("a footprint below the startup floor still holds the floor", () => {
+  const state = snapshot();
+  state.instances = [running()];
+  const low: ResourceProbe = () => ({ ...probe([]), footprintsMiB: new Map([["instance", 100]]) });
+  expect(capacity(state, host, { probe: low }).budget?.memoryCommittedMiB).toBe(2048);
+  state.instances = [{ ...running(), status: "starting", pid: 0 }];
+  const absent: ResourceProbe = () => ({ ...probe([]), footprintsMiB: new Map() });
+  expect(capacity(state, host, { probe: absent }).budget?.memoryCommittedMiB).toBe(2048);
+  state.instances = [{ ...running(), status: "interrupted", pid: 0 }];
+  expect(capacity(state, host, { probe: absent }).budget?.memoryCommittedMiB).toBe(
+    environment.memoryMiB,
+  );
 });
 
 test("macOS admits only two instances while stopped instances consume no capacity", () => {
@@ -84,7 +207,7 @@ test.each([
   }
   const state = snapshot();
   state.operations = [operation("action_required", command)];
-  expect(runnerCapacity(state, host).available).toBe(2);
+  expect(runnerCapacity(state, host).available).toBe(5);
 });
 
 test("preparation flag, pause and missing ready environments report no available slots", () => {
@@ -100,15 +223,23 @@ test("preparation flag, pause and missing ready environments report no available
   ).toBe(0);
 });
 
-test("largest ready environment is selected by CPU then memory", () => {
+test("scalar capacity is the maximum available across ready environments", () => {
   const state = snapshot();
+  state.machine.memoryBudgetMiB = 8192;
   state.environments = [
     { ...environment, id: "small", cpu: 1, memoryMiB: 512 },
     environment,
     { ...environment, id: "large", memoryMiB: 24576 },
     { ...environment, id: "unready", cpu: 100, state: "action_required" },
   ];
-  expect(runnerCapacity(state, host).available).toBe(1);
+  expect(runnerCapacity(state, host)).toMatchObject({
+    available: 5,
+    environments: [
+      { environmentId: "small", available: 5 },
+      { environmentId: "linux", available: 4 },
+      { environmentId: "large", available: 4 },
+    ],
+  });
 });
 
 test.each([
@@ -117,6 +248,7 @@ test.each([
   { ...environment, os: "macos" as const, cpu: 1, memoryMiB: 512 },
 ])("capacity agrees with successive admission for $os / $cpu CPU / $memoryMiB MiB", (env) => {
   const state = snapshot(env);
+  state.machine.memoryBudgetMiB = Math.max(2048, estimatedVmMemoryMiB(env) * 4);
   state.instances = [running(env)];
   const { available } = runnerCapacity(state, host);
   for (let index = 0; index < available; index++) {
@@ -128,6 +260,7 @@ test.each([
 
 test("accepted runners reserve their VM before it boots, so slots are not offered twice", () => {
   const state = snapshot();
+  state.machine.memoryBudgetMiB = 4096;
   state.operations = [operation("accepted")];
   expect(runnerCapacity(state, host).available).toBe(1);
   state.operations = [operation("accepted"), { ...operation("running"), id: "second" }];
@@ -136,9 +269,13 @@ test("accepted runners reserve their VM before it boots, so slots are not offere
   expect(runnerCapacity(state, host).available).toBe(0);
 });
 
-test("a starting VM holds its resources, and an interrupted one stops admission entirely", () => {
+test("starting and interrupted VMs hold only their own resources", () => {
   const state = snapshot();
-  state.operations = [operation("running")];
+  state.machine.memoryBudgetMiB = 4096;
+  state.operations = [
+    operation("running"),
+    { ...operation("succeeded", "environment.start"), id: "instance", key: "running:start" },
+  ];
   state.instances = [{ ...running(), status: "starting" }];
   expect(runnerCapacity(state, host).available).toBe(1);
   state.instances = [
@@ -146,9 +283,135 @@ test("a starting VM holds its resources, and an interrupted one stops admission
     { ...running(), id: "second" },
   ];
   expect(instanceAdmissionError(state, environment, host)).toMatchObject({
-    code: "capacity_exceeded",
+    code: "memory_budget_exceeded",
   });
   state.operations = [];
   state.instances = [{ ...running(), status: "interrupted" }];
-  expect(runnerCapacity(state, host).available).toBe(0);
+  expect(runnerCapacity(state, host).available).toBe(1);
+  state.instances = [{ ...running(), status: "interrupted", cpu: host.cpus }];
+  expect(runnerCapacity(state, host).available).toBe(1);
+});
+
+test("macOS limits apply across macOS environments without blocking Linux or Windows", () => {
+  const small = { ...environment, cpu: 1, memoryMiB: 512 };
+  const mac: Environment = { ...small, id: "mac", os: "macos" };
+  const state = snapshot(small);
+  state.environments = [small, mac, { ...mac, id: "mac2" }, { ...small, id: "win", os: "windows" }];
+  state.instances = [running(mac), { ...running(mac), id: "other", status: "interrupted" }];
+  const capacity = runnerCapacity(state, host);
+  expect(capacity.environments).toEqual([
+    { environmentId: "linux", available: 5 },
+    { environmentId: "mac", available: 0 },
+    { environmentId: "mac2", available: 0 },
+    { environmentId: "win", available: 5 },
+  ]);
+  expect(
+    Schema.decodeUnknownSync(SnapshotSchema)({ ...state, runnerCapacity: capacity }).runnerCapacity,
+  ).toEqual(capacity);
+});
+
+test.each(["starting", "running", "interrupted", "stopped"] as const)(
+  "an action-required runner with a %s child VM holds capacity only until verified stopped",
+  (status) => {
+    const state = snapshot({ ...environment, cpu: 1, memoryMiB: 512 });
+    state.operations = [
+      operation("action_required"),
+      {
+        ...operation("succeeded", "environment.start"),
+        id: "instance",
+        key: "action_required:start",
+      },
+    ];
+    state.instances = [{ ...running(), cpu: 1, memoryMiB: 512, status }];
+    expect(runnerCapacity(state, host)).toMatchObject({
+      active: status === "stopped" ? 0 : 1,
+      available: status === "stopped" ? 5 : 4,
+    });
+  },
+);
+
+test("missing instance evidence after a start still holds a runner slot", () => {
+  const state = snapshot({ ...environment, cpu: 1, memoryMiB: 512 });
+  state.operations = [
+    operation("action_required"),
+    { ...operation("succeeded", "environment.start"), key: "action_required:start" },
+  ];
+  expect(runnerCapacity(state, host).active).toBe(1);
+});
+
+test("runner progress identifies boot reservations and a stopped VM without a retained child", () => {
+  const mac: Environment = { ...environment, id: "mac", os: "macos", cpu: 1, memoryMiB: 512 };
+  const state = snapshot(mac);
+  state.environments = [mac, { ...environment, cpu: 1, memoryMiB: 512 }];
+  state.instances = [running(mac)];
+  state.operations = [
+    {
+      ...operation("running"),
+      result: {
+        bindingId: "binding",
+        environmentId: "mac",
+        leaseKey: "running",
+        stage: "starting",
+      },
+    },
+  ];
+  expect(runnerCapacity(state, host).environments).toEqual([
+    { environmentId: "mac", available: 0 },
+    { environmentId: "linux", available: 4 },
+  ]);
+  state.instances = [{ ...running(mac), status: "stopped" }];
+  state.operations = [
+    {
+      ...operation("action_required"),
+      result: {
+        bindingId: "binding",
+        environmentId: "mac",
+        leaseKey: "running",
+        instanceId: "instance",
+        stage: "cleaning",
+      },
+    },
+  ];
+  expect(runnerCapacity(state, host)).toMatchObject({ active: 0, available: 5 });
+});
+
+test("direct lookups release action-required slots when stopped children leave the status window", () => {
+  const state = snapshot();
+  const runner = operation("action_required");
+  state.operations = [runner];
+  const start = {
+    ...operation("succeeded", "environment.start"),
+    id: "old-instance",
+    key: `${runner.id}:start`,
+  };
+  const stopped = { ...running(), id: start.id, status: "stopped" as const };
+  const lookup = {
+    start: vi.fn(() => start),
+    instance: vi.fn(() => stopped),
+  };
+  const measured = vi.fn(probe);
+  expect(capacity(state, host, { lookup, probe: measured })).toMatchObject({
+    active: 0,
+    available: 5,
+    budget: { memoryCommittedMiB: 0, pressure: "normal" },
+  });
+  expect(lookup.start).toHaveBeenCalledWith(runner.id);
+  expect(lookup.instance).toHaveBeenCalledWith(start.id);
+  expect(measured).toHaveBeenCalledOnce();
+});
+
+test("a directly looked-up start keeps unresolved cleanup reserved alongside reclaimable warm VMs", () => {
+  const state = snapshot();
+  const runner = operation("action_required");
+  state.operations = [runner];
+  state.instances = [{ ...running(), role: "warm", memoryMiB: 2048 }];
+  const lookup = {
+    start: () => ({ ...operation("succeeded", "environment.start"), id: "missing-instance" }),
+    instance: () => undefined,
+  };
+  expect(capacity(state, host, { lookup, probe })).toMatchObject({
+    active: 1,
+    available: 4,
+    budget: { memoryCommittedMiB: 4096 },
+  });
 });
diff --git a/apps/server/src/runner-capacity.ts b/apps/server/src/runner-capacity.ts
index 8ca8d10e..72d984dd 100644
--- a/apps/server/src/runner-capacity.ts
+++ b/apps/server/src/runner-capacity.ts
@@ -3,48 +3,86 @@ import {
   VectisError,
   type Environment,
   type Snapshot,
+  type RunnerCapacity,
+  type Operation,
+  type Instance,
 } from "../../../packages/protocol/src/index.js";
+import { RunnerProgress } from "../../../packages/protocol/src/runners.js";
+import { Schema } from "effect";
+import { estimatedVmMemoryMiB } from "../../../packages/runner/src/memory.js";
+import { resourceProbe, type ResourceProbe } from "./resource-probe.js";
 
 type Host = { cpus: number; memoryBytes: number };
 
+function memoryBudget(snapshot: Snapshot, host: Host, probe: ResourceProbe) {
+  const usage = probe(snapshot.instances);
+  const hostMemoryMiB = host.memoryBytes / 1024 ** 2;
+  let memoryCommittedMiB = 0;
+  for (const instance of snapshot.instances) {
+    if (instance.status === "stopped") continue;
+    const environment = snapshot.environments.find((item) => item.id === instance.environmentId);
+    const memoryMiB = instance.memoryMiB ?? environment?.memoryMiB ?? hostMemoryMiB;
+    const floor = environment ? estimatedVmMemoryMiB({ os: environment.os, memoryMiB }) : memoryMiB;
+    const measured = usage.footprintsMiB.get(instance.id);
+    const footprint =
+      measured !== undefined && Number.isFinite(measured) && measured >= 0
+        ? measured
+        : instance.status === "starting" && instance.pid === 0
+          ? floor
+          : memoryMiB;
+    memoryCommittedMiB += Math.max(footprint, floor);
+  }
+  return {
+    memoryBudgetMiB: snapshot.machine.memoryBudgetMiB ?? Math.floor(hostMemoryMiB * 0.75),
+    memoryCommittedMiB,
+    hostMemoryMiB,
+    pressure: usage.pressure,
+    pressureKnown: usage.pressureKnown,
+  };
+}
+
 export function instanceAdmissionError(
   snapshot: Snapshot,
   environment: Environment,
   host: Host,
   count = 1,
+  probe: ResourceProbe = resourceProbe,
 ): VectisError | undefined {
-  const active = snapshot.instances.filter(
-    (instance) => instance.status === "starting" || instance.status === "running",
-  );
-  let cpu = environment.cpu * count;
-  let memory = environment.memoryMiB * count;
+  const active = snapshot.instances.filter((instance) => instance.status !== "stopped");
+  const budget = memoryBudget(snapshot, host, probe);
   let macos = environment.os === "macos" ? count : 0;
   for (const instance of active) {
     const defaults = snapshot.environments.find((item) => item.id === instance.environmentId);
-    cpu += instance.cpu ?? defaults?.cpu ?? 0;
-    memory += instance.memoryMiB ?? defaults?.memoryMiB ?? 0;
     if (defaults?.os === "macos") macos++;
   }
-  if (cpu > host.cpus)
-    return new VectisError("capacity_exceeded", "Requested VM CPUs exceed the host budget.");
-  if (memory * 1024 * 1024 > host.memoryBytes * 0.75)
-    return new VectisError("capacity_exceeded", "Requested VM memory exceeds the host budget.");
+  if (environment.cpu > host.cpus)
+    return new VectisError("invalid_resources", "Requested VM CPUs exceed the host's core count.");
+  if (budget.pressure !== "normal")
+    return new VectisError(
+      "memory_pressure",
+      `Host memory pressure is ${budget.pressure}; new VMs cannot start.`,
+      "Stop an idle VM or free host memory, then retry when memory pressure is normal.",
+    );
+  if (
+    budget.memoryCommittedMiB + estimatedVmMemoryMiB(environment) * count >
+    budget.memoryBudgetMiB
+  )
+    return new VectisError(
+      "memory_budget_exceeded",
+      "Starting this VM would exceed the shared VM memory budget.",
+      "Stop an idle VM or increase the budget with vectis machine configure --memory-budget-mib <N>.",
+    );
   if (environment.os === "macos" && macos > 2)
     return new VectisError("macos_limit", "The two-instance macOS limit has been reached.");
 }
 
-export function runnerCapacity(snapshot: Snapshot, host: Host) {
-  const max = snapshot.machine.maxRunners ?? defaultMaxRunners;
-  const active = snapshot.operations.filter(
-    (operation) =>
-      operation.command === "runner.run" &&
-      ["accepted", "running", "action_required"].includes(operation.status),
-  ).length;
-  const preparationBusy =
+export function preparationBusy(snapshot: Snapshot) {
+  return (
     snapshot.preparationBusy === true ||
     snapshot.operations.some(
       (operation) =>
         [
+          "environment.provision",
           "environment.prepare-linux",
           "environment.resume",
           "environment.install-macos",
@@ -53,26 +91,104 @@ export function runnerCapacity(snapshot: Snapshot, host: Host) {
           "environment.resume-macos",
           "environment.open-macos-setup",
         ].includes(operation.command) && ["accepted", "running"].includes(operation.status),
-    );
-  const environment = snapshot.environments
-    .filter((item) => item.state === "ready")
-    .sort((a, b) => b.cpu - a.cpu || b.memoryMiB - a.memoryMiB)[0];
-  // An accepted runner holds its slot before its VM starts, so its resources are reserved here too.
-  const booting = Math.max(
-    0,
-    active -
-      snapshot.instances.filter(
-        (instance) => instance.status === "starting" || instance.status === "running",
-      ).length,
+    )
   );
-  const interrupted = snapshot.instances.some((instance) => instance.status === "interrupted");
-  let available = 0;
-  if (environment && !snapshot.machine.paused && !preparationBusy && !interrupted) {
-    while (
-      available < max - active &&
-      !instanceAdmissionError(snapshot, environment, host, booting + available + 1)
+}
+
+export function runnerCapacity(
+  snapshot: Snapshot,
+  host: Host,
+  {
+    lookup,
+    probe = resourceProbe,
+  }: {
+    lookup?: {
+      start(id: string): Operation | undefined;
+      instance(id: string): Instance | undefined;
+    };
+    probe?: ResourceProbe;
+  } = {},
+): RunnerCapacity {
+  const usage = probe(snapshot.instances);
+  const measured: ResourceProbe = () => usage;
+  const max = snapshot.machine.maxRunners ?? defaultMaxRunners;
+  const runners = snapshot.operations
+    .filter(
+      (operation) =>
+        operation.command === "runner.run" &&
+        ["accepted", "running", "action_required"].includes(operation.status),
     )
-      available++;
-  }
-  return { max, active, available };
+    .map((operation) => {
+      const progress = Schema.is(RunnerProgress)(operation.result) ? operation.result : undefined;
+      const start =
+        lookup?.start(operation.id) ??
+        snapshot.operations.find((item) => item.key === `${operation.id}:start`);
+      const instanceId = progress?.instanceId ?? start?.id;
+      const instance =
+        instanceId === undefined
+          ? undefined
+          : (lookup?.instance(instanceId) ??
+            snapshot.instances.find((item) => item.id === instanceId));
+      return { operation, progress, start, instance };
+    })
+    .filter(({ operation, progress, start, instance }) => {
+      if (operation.status !== "action_required") return true;
+      if (instance) return instance.status !== "stopped";
+      // No start means no VM was created. Missing evidence after a start remains reserved.
+      return (
+        progress?.instanceId !== undefined ||
+        (start !== undefined &&
+          ["accepted", "running", "action_required", "succeeded"].includes(start.status))
+      );
+    });
+  const active = runners.length;
+  const ready = snapshot.environments.filter((item) => item.state === "ready");
+  const reservations = runners.flatMap(({ operation, progress, instance }) => {
+    if (instance) return [];
+    const environmentId =
+      progress?.environmentId ??
+      snapshot.activities?.find(
+        (activity) => activity.id === (operation.activityId ?? operation.id),
+      )?.environmentId;
+    const environment = ready.find((item) => item.id === environmentId);
+    // Before binding resolution, reserve the largest startup estimate and a macOS slot.
+    return [
+      {
+        id: operation.id,
+        environmentId: environment?.id ?? ready.find((item) => item.os === "macos")?.id ?? "",
+        cpu: environment?.cpu ?? Math.max(0, ...ready.map((item) => item.cpu)),
+        memoryMiB: environment
+          ? estimatedVmMemoryMiB(environment)
+          : Math.max(0, ...ready.map(estimatedVmMemoryMiB)),
+        status: "starting" as const,
+        pid: 0,
+        createdAt: operation.createdAt,
+      },
+    ];
+  });
+  const committed: Snapshot = { ...snapshot, instances: [...snapshot.instances, ...reservations] };
+  const reserved = {
+    ...committed,
+    instances: committed.instances.filter(
+      (instance) => !instance.role || !["starting", "running"].includes(instance.status),
+    ),
+  };
+  const environments = ready.map((environment) => {
+    let available = 0;
+    if (!snapshot.machine.paused && !preparationBusy(snapshot)) {
+      while (
+        available < max - active &&
+        !instanceAdmissionError(reserved, environment, host, available + 1, measured)
+      )
+        available++;
+    }
+    return { environmentId: environment.id, available };
+  });
+  return {
+    max,
+    active,
+    available: Math.max(0, ...environments.map((item) => item.available)),
+    environments,
+    budget: memoryBudget(committed, host, measured),
+  };
 }
diff --git a/apps/server/src/runner-job-observations.test.ts b/apps/server/src/runner-job-observations.test.ts
index 413f9971..950d0247 100644
--- a/apps/server/src/runner-job-observations.test.ts
+++ b/apps/server/src/runner-job-observations.test.ts
@@ -45,6 +45,46 @@ const job: Job = {
   updatedAt: 1,
 };
 
+test("job observation still follows a retained runner outside both status windows", async () => {
+  vi.useFakeTimers();
+  const home = await mkdtemp(join(tmpdir(), "vectis-old-job-observation-"));
+  const store = new Store(join(home, "state.sqlite"), {
+    snapshotLimits: { operations: 3, activities: 3, stoppedInstances: 2 },
+  });
+  const watch = vi.fn();
+  const service = new Service(
+    store,
+    new VmRuntime({ home }),
+    undefined,
+    undefined,
+    undefined,
+    watch,
+  );
+  try {
+    const runner = seed(store, "old-runner", "succeeded");
+    store.put("operation", runner.id, {
+      ...runner,
+      updatedAt: new Date(Date.now() - 60000).toISOString(),
+    });
+    for (let index = 0; index < 3; index++) {
+      const id = `newer-${index}`;
+      const command = { type: "job.scan", bindingId: "binding" } as const;
+      const operation = store.accept(id, id, command.type, activityFor(id, command), id).operation;
+      store.update(operation, { status: "succeeded" });
+    }
+    expect(store.snapshot().operations.some(({ id }) => id === runner.id)).toBe(false);
+    expect(store.snapshot().activities?.some(({ id }) => id === runner.id)).toBe(false);
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(watch).toHaveBeenLastCalledWith(["lease-old-runner"]);
+    service.observeJobs([{ leaseId: "lease-old-runner", job }]);
+    expect(store.activity(runner.id).activity.subject).toMatchObject({ actualJob: { jobId: 99 } });
+  } finally {
+    await service.close();
+    store.close();
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
 test.each([
   ["succeeded", "failure", 1],
   ["failed", "success", undefined],
diff --git a/apps/server/src/runner-job-observations.ts b/apps/server/src/runner-job-observations.ts
index 3e57628b..b5949eb8 100644
--- a/apps/server/src/runner-job-observations.ts
+++ b/apps/server/src/runner-job-observations.ts
@@ -8,17 +8,15 @@ import type { Store } from "./store.js";
 const observationLifetime = 48 * 60 * 60 * 1000;
 
 function runnerActivities(store: Store) {
-  const snapshot = store.snapshot();
-  const operations = new Map(snapshot.operations.map((operation) => [operation.id, operation]));
   const cutoff = Date.now() - observationLifetime;
-  return (snapshot.activities ?? []).flatMap((activity) => {
+  return store.activitySummaries().flatMap((activity) => {
     if (
       activity.subject.type !== "runner" ||
       activity.subject.actualJob?.status === "completed" ||
       !(Date.parse(activity.createdAt) > cutoff)
     )
       return [];
-    const operation = operations.get(activity.rootOperationId);
+    const operation = store.operation(activity.rootOperationId);
     if (operation?.command !== "runner.run") return [];
     const progress = Schema.decodeUnknownOption(RunnerProgress)(operation.result);
     return progress._tag === "Some" && progress.value.leaseId
diff --git a/apps/server/src/runner-recovery.test.ts b/apps/server/src/runner-recovery.test.ts
index efdfe012..9a5a213c 100644
--- a/apps/server/src/runner-recovery.test.ts
+++ b/apps/server/src/runner-recovery.test.ts
@@ -10,6 +10,7 @@ import { join } from "node:path";
 import { afterEach } from "vitest";
 
 const homes: string[] = [];
+const snapshotLimits = { operations: 3, activities: 3, stoppedInstances: 2 };
 afterEach(async () => {
   for (const home of homes) await rm(home, { recursive: true, force: true });
   homes.length = 0;
@@ -18,7 +19,7 @@ afterEach(async () => {
 async function fixture() {
   const home = await mkdtemp(join(tmpdir(), "vectis-runner-recovery-"));
   homes.push(home);
-  const store = new Store(":memory:");
+  const store = new Store(":memory:", { snapshotLimits });
   const broker = {
     connectRepository: vi.fn(async () => "binding"),
     disconnectRepository: async () => {},
@@ -84,7 +85,7 @@ async function fixture() {
     pid: 0,
     createdAt: "now",
   });
-  return { store, service, broker, interrupted };
+  return { store, service, broker, interrupted, runtime: service.runtime };
 }
 test("reconciles a lost registration response without preparing another runner", async () => {
   const { store, service, broker, interrupted } = await fixture();
@@ -184,10 +185,422 @@ test("cloud access failure leaves a stopped runner unresolved", async () => {
     service.submit("recover", { type: "runner.reconcile", id: interrupted.id });
     await service.drain();
     expect(store.get("operation", interrupted.id)).toMatchObject({ status: "action_required" });
-    expect(service.snapshot().runnerCapacity?.active).toBe(1);
+    expect(service.snapshot().runnerCapacity?.active).toBe(0);
+    expect(broker.releaseRunner).not.toHaveBeenCalled();
+  } finally {
+    await service.close();
+    store.close();
+  }
+});
+
+test.each(["stopped", "absent", "interrupted"] as const)(
+  "restart automatically reconciles a %s runner VM before releasing capacity",
+  async (state) => {
+    const { store, service, broker, interrupted, runtime } = await fixture();
+    await service.close();
+    store.update(interrupted, { status: "running" });
+    if (state === "absent") store.remove("instance", "instance");
+    else
+      store.put("instance", "instance", {
+        id: "instance",
+        environmentId: "test",
+        status: state,
+        pid: state === "stopped" ? 0 : 42,
+        createdAt: new Date().toISOString(),
+      });
+    const reconcile = vi.spyOn(runtime, "reconcile").mockResolvedValue(true);
+    const restarted = new Service(store, runtime, () => broker, undefined, undefined, undefined, {
+      connected: () => true,
+    });
+    try {
+      expect(store.get("operation", interrupted.id)).toMatchObject({
+        status: "action_required",
+        result: { code: "runner_recovery_pending" },
+      });
+      await restarted.initialize();
+      await restarted.drain();
+      expect(store.get("operation", interrupted.id)).toMatchObject({
+        status: "cancelled",
+        result: { code: "runner_interrupted", stage: "finished" },
+      });
+      expect(broker.reconcileRunner).toHaveBeenCalledOnce();
+      expect(broker.releaseRunner).toHaveBeenCalledOnce();
+      expect(broker.prepareRunner).not.toHaveBeenCalled();
+      expect(restarted.snapshot().runnerCapacity?.active).toBe(0);
+      if (state === "interrupted") expect(reconcile).toHaveBeenCalledWith("instance", undefined);
+    } finally {
+      await restarted.close();
+      store.close();
+    }
+  },
+);
+
+test("restart never settles a runner whose VM might still be running", async () => {
+  const { store, service, broker, interrupted, runtime } = await fixture();
+  await service.close();
+  store.update(interrupted, { status: "running" });
+  store.put("instance", "instance", {
+    id: "instance",
+    environmentId: "test",
+    status: "running",
+    pid: 42,
+    createdAt: new Date().toISOString(),
+  });
+  vi.spyOn(runtime, "reconcile").mockResolvedValue(false);
+  const restarted = new Service(store, runtime, () => broker, undefined, undefined, undefined, {
+    connected: () => true,
+  });
+  try {
+    await restarted.initialize();
+    await restarted.drain();
+    expect(store.get("instance", "instance")).toMatchObject({ status: "interrupted" });
+    expect(store.get("operation", interrupted.id)).toMatchObject({
+      status: "action_required",
+      result: { code: "runner_recovery_pending" },
+    });
+    expect(broker.reconcileRunner).not.toHaveBeenCalled();
     expect(broker.releaseRunner).not.toHaveBeenCalled();
+    expect(restarted.snapshot().runnerCapacity?.active).toBe(1);
   } finally {
+    await restarted.close();
+    store.close();
+  }
+});
+
+test.each([false, true])(
+  "restart leaves stopped runners pending outside status: %s",
+  async (outsideStatus) => {
+    const { store, service, broker, interrupted, runtime } = await fixture();
     await service.close();
+    store.update(interrupted, { status: "running" });
+    store.put("instance", "instance", {
+      ...store.instance("instance"),
+      stoppedAt: new Date(Date.now() - 1000).toISOString(),
+    });
+    if (outsideStatus)
+      for (let index = 0; index < snapshotLimits.stoppedInstances; index++)
+        store.put("instance", `recent-instance-${index}`, {
+          id: `recent-instance-${index}`,
+          environmentId: "test",
+          status: "stopped",
+          pid: 0,
+          createdAt: new Date().toISOString(),
+        });
+    broker.releaseRunner.mockRejectedValue(new Error("GitHub unavailable"));
+    const restarted = new Service(store, runtime, () => broker, undefined, undefined, undefined, {
+      connected: () => true,
+    });
+    try {
+      await restarted.initialize();
+      await restarted.drain();
+      expect(store.get("operation", interrupted.id)).toMatchObject({
+        status: "action_required",
+        result: { code: "runner_recovery_pending", recovery: { attempts: 1 } },
+      });
+      expect(store.snapshot().instances.some(({ id }) => id === "instance")).toBe(!outsideStatus);
+      expect(broker.releaseRunner).toHaveBeenCalledOnce();
+      expect(restarted.snapshot().runnerCapacity?.active).toBe(0);
+    } finally {
+      await restarted.close();
+      store.close();
+    }
+  },
+);
+
+test("restart closes a request interrupted before startup without registering a runner", async () => {
+  const { store, service, broker, runtime } = await fixture();
+  await service.close();
+  const request = store.accept(
+    "not-started",
+    "fingerprint",
+    "runner.run",
+    activityFor("not-started", { type: "runner.run", bindingId: "binding" }),
+    "not-started",
+  ).operation;
+  const restarted = new Service(store, runtime, () => broker, undefined, undefined, undefined, {
+    connected: () => true,
+  });
+  try {
+    await restarted.initialize();
+    await restarted.drain();
+    expect(store.get("operation", request.id)).toMatchObject({
+      status: "failed",
+      result: { code: "runner_interrupted" },
+    });
+    expect(broker.prepareRunner).not.toHaveBeenCalled();
+  } finally {
+    await restarted.close();
     store.close();
   }
 });
+
+function addRecentHistory(store: Store) {
+  for (let index = 0; index <= snapshotLimits.operations; index++) {
+    const { operation } = store.accept(`recent-${index}`, "history", "machine.pause");
+    store.update(operation, { status: "succeeded" });
+  }
+}
+
+test.each(["stopped", "interrupted"] as const)(
+  "restart recovers an old start child with a %s instance outside the terminal window",
+  async (status) => {
+    const { store, service, broker, interrupted, runtime } = await fixture();
+    await service.close();
+    const createdAt = "2026-01-01T00:00:00.000Z";
+    const { operation: start } = store.accept(
+      `${interrupted.id}:start`,
+      "start",
+      "environment.start",
+      { activityId: interrupted.id },
+    );
+    store.put("operation", start.id, {
+      ...start,
+      status: "succeeded",
+      updatedAt: createdAt,
+    });
+    store.update(interrupted, {
+      status: "running",
+      result: {
+        bindingId: "binding",
+        environmentId: "test",
+        leaseKey: interrupted.id,
+        stage: "registering",
+      },
+    });
+    store.put("instance", start.id, {
+      id: start.id,
+      environmentId: "test",
+      status,
+      pid: 0,
+      createdAt,
+      stoppedAt: new Date(Date.now() - 1000).toISOString(),
+    });
+    for (let index = 0; index < snapshotLimits.stoppedInstances; index++)
+      store.put("instance", `recent-instance-${index}`, {
+        id: `recent-instance-${index}`,
+        environmentId: "test",
+        status: "stopped",
+        pid: 0,
+        createdAt: new Date().toISOString(),
+      });
+    addRecentHistory(store);
+    const reconcile = vi
+      .spyOn(runtime, "reconcile")
+      .mockResolvedValueOnce(false)
+      .mockResolvedValue(true);
+    const restarted = new Service(store, runtime, () => broker, undefined, undefined, undefined, {
+      connected: () => true,
+    });
+    try {
+      expect(store.snapshot().operations.some(({ id }) => id === start.id)).toBe(false);
+      if (status === "stopped")
+        expect(store.snapshot().instances.some(({ id }) => id === start.id)).toBe(false);
+      expect(restarted.snapshot().runnerCapacity?.active).toBe(status === "stopped" ? 0 : 1);
+      await restarted.initialize();
+      await restarted.drain();
+      expect(store.instance(start.id)?.status).toBe("stopped");
+      expect(store.operation(interrupted.id)).toMatchObject({
+        status: "cancelled",
+        result: { code: "runner_interrupted" },
+      });
+      if (status === "interrupted") {
+        expect(reconcile).toHaveBeenCalledTimes(2);
+        expect(reconcile).toHaveBeenLastCalledWith(start.id, undefined);
+      }
+      expect(broker.releaseRunner).toHaveBeenCalledOnce();
+      expect(broker.prepareRunner).not.toHaveBeenCalled();
+      expect(restarted.snapshot().runnerCapacity?.active).toBe(0);
+    } finally {
+      await restarted.close();
+      store.close();
+    }
+  },
+);
+
+test("recovery without progress never mistakes an old start child for an unstarted runner", async () => {
+  const { store, service, broker, interrupted, runtime } = await fixture();
+  await service.close();
+  const { operation: start } = store.accept(
+    `${interrupted.id}:start`,
+    "start",
+    "environment.start",
+    { activityId: interrupted.id },
+  );
+  store.put("operation", start.id, {
+    ...start,
+    status: "succeeded",
+    updatedAt: "2026-01-01T00:00:00.000Z",
+  });
+  store.updateActivity(interrupted.id, (activity) => ({ ...activity, bindingId: "binding" }));
+  store.update(interrupted, { status: "running", result: undefined });
+  addRecentHistory(store);
+  const restarted = new Service(store, runtime, () => broker, undefined, undefined, undefined, {
+    connected: () => true,
+  });
+  try {
+    expect(store.snapshot().operations.some(({ id }) => id === start.id)).toBe(false);
+    await restarted.initialize();
+    await restarted.drain();
+    expect(store.operation(interrupted.id)).toMatchObject({
+      status: "action_required",
+      result: { code: "runner_recovery_pending", recovery: { attempts: 1 } },
+    });
+    expect(broker.reconcileRunner).not.toHaveBeenCalled();
+    expect(broker.releaseRunner).not.toHaveBeenCalled();
+  } finally {
+    await restarted.close();
+    store.close();
+  }
+});
+
+test("instance stop recognizes a retained stopped instance outside the status window", async () => {
+  const { store, service, runtime } = await fixture();
+  const stop = vi.spyOn(runtime, "stop").mockResolvedValue(undefined);
+  try {
+    store.put("instance", "instance", {
+      ...store.instance("instance"),
+      stoppedAt: new Date(Date.now() - 1000).toISOString(),
+    });
+    for (let index = 0; index < snapshotLimits.stoppedInstances; index++)
+      store.put("instance", `recent-instance-${index}`, {
+        id: `recent-instance-${index}`,
+        environmentId: "test",
+        status: "stopped",
+        pid: 0,
+        createdAt: new Date().toISOString(),
+      });
+    expect(store.snapshot().instances.some(({ id }) => id === "instance")).toBe(false);
+    const operation = service.submit("stop-old", { type: "instance.stop", id: "instance" });
+    await service.drain();
+    await vi.waitFor(() => expect(store.operation(operation.id).status).toBe("succeeded"));
+    expect(stop).not.toHaveBeenCalled();
+  } finally {
+    await service.close();
+    store.close();
+  }
+});
+
+test("reconciliation finds an old start child before releasing its runner lease", async () => {
+  const { store, service, broker, interrupted } = await fixture();
+  try {
+    const createdAt = "2026-01-01T00:00:00.000Z";
+    const { operation: start } = store.accept(
+      `${interrupted.id}:start`,
+      "start",
+      "environment.start",
+      { activityId: interrupted.id },
+    );
+    store.put("operation", start.id, {
+      ...start,
+      status: "succeeded",
+      createdAt,
+      updatedAt: createdAt,
+    });
+    store.put("operation", interrupted.id, {
+      ...store.operation(interrupted.id),
+      createdAt,
+      updatedAt: createdAt,
+      result: {
+        bindingId: "binding",
+        environmentId: "test",
+        leaseKey: interrupted.id,
+        stage: "registering",
+      },
+    });
+    store.put("instance", start.id, {
+      id: start.id,
+      environmentId: "test",
+      status: "interrupted",
+      pid: 0,
+      createdAt,
+    });
+    addRecentHistory(store);
+    expect(store.snapshot().operations.some(({ id }) => id === start.id)).toBe(false);
+    const blocked = service.submit("recover-blocked", {
+      type: "runner.reconcile",
+      id: interrupted.id,
+    });
+    await service.drain();
+    expect(store.operation(blocked.id)).toMatchObject({
+      status: "action_required",
+      result: { code: "reconciliation_required" },
+    });
+    expect(broker.reconcileRunner).not.toHaveBeenCalled();
+    expect(broker.releaseRunner).not.toHaveBeenCalled();
+
+    store.put("instance", start.id, {
+      id: start.id,
+      environmentId: "test",
+      status: "stopped",
+      pid: 0,
+      createdAt,
+      stoppedAt: createdAt,
+    });
+    for (let index = 0; index < snapshotLimits.stoppedInstances; index++)
+      store.put("instance", `recent-instance-${index}`, {
+        id: `recent-instance-${index}`,
+        environmentId: "test",
+        status: "stopped",
+        pid: 0,
+        createdAt: new Date().toISOString(),
+      });
+    expect(store.snapshot().instances.some(({ id }) => id === start.id)).toBe(false);
+    const stoppedInstance = service.submit("reconcile-stopped-instance", {
+      type: "instance.reconcile",
+      id: start.id,
+    });
+    await service.drain();
+    expect(store.operation(stoppedInstance.id)).toMatchObject({
+      status: "action_required",
+      result: { code: "reconciliation_required" },
+    });
+    const recovered = service.submit("recover-stopped", {
+      type: "runner.reconcile",
+      id: interrupted.id,
+    });
+    await service.drain();
+    expect(store.operation(recovered.id).status).toBe("succeeded");
+    expect(store.operation(interrupted.id).status).toBe("cancelled");
+    expect(broker.releaseRunner).toHaveBeenCalledOnce();
+  } finally {
+    await service.close();
+    store.close();
+  }
+});
+
+test.each(["succeeded", "failed", "cancelled"] as const)(
+  "waitForOperation reads old %s runner and start operations outside the status window",
+  async (status) => {
+    const { store, service, interrupted } = await fixture();
+    try {
+      const { operation: start } = store.accept(
+        `${interrupted.id}:start`,
+        "start",
+        "environment.start",
+        { activityId: interrupted.id },
+      );
+      for (const operation of [interrupted, start])
+        store.put("operation", operation.id, {
+          ...operation,
+          status,
+          message: "Retained control outcome.",
+          updatedAt: "2026-01-01T00:00:00.000Z",
+        });
+      addRecentHistory(store);
+      expect(store.snapshot().operations.some(({ id }) => id === interrupted.id)).toBe(false);
+      expect(store.snapshot().operations.some(({ id }) => id === start.id)).toBe(false);
+      for (const operation of [interrupted, start]) {
+        const waiting = service["waitForOperation"](operation.id);
+        if (status === "succeeded") await expect(waiting).resolves.toBeUndefined();
+        else
+          await expect(waiting).rejects.toMatchObject({
+            code: "runner_control_failed",
+            message: "Retained control outcome.",
+          });
+      }
+    } finally {
+      await service.close();
+      store.close();
+    }
+  },
+);
diff --git a/apps/server/src/runner-task.test.ts b/apps/server/src/runner-task.test.ts
index 4cf45bb6..bfde8007 100644
--- a/apps/server/src/runner-task.test.ts
+++ b/apps/server/src/runner-task.test.ts
@@ -1,10 +1,20 @@
 import { afterEach, expect, test, vi } from "vitest";
-import type { RunnerBroker } from "../../../packages/protocol/src/runners.js";
+import { RunnerProgress, type RunnerBroker } from "../../../packages/protocol/src/runners.js";
+import { Schema } from "effect";
 import { runRunnerTask } from "./runner-task.js";
 import { readyGuest } from "../../../packages/runner/src/guest-ready.js";
 import { executeGuest, GuestUnavailableError } from "../../../packages/runner/src/guest.js";
 import { collectRunnerDiagnostics } from "../../../packages/runner/src/guest-diagnostics.js";
 import { VectisError, type Environment } from "../../../packages/protocol/src/index.js";
+import { jobStartedMarker } from "../../../packages/runner/src/runner-access.js";
+import {
+  cachePrivilegeError,
+  cachePrivilegeScript,
+} from "../../../packages/runner/src/cache-guest.js";
+import {
+  preinstalledRunnerDirectory,
+  runnerVersion,
+} from "../../../packages/runner/src/runner-release.js";
 
 vi.mock("../../../packages/runner/src/guest-ready.js", () => ({ readyGuest: vi.fn() }));
 vi.mock("../../../packages/runner/src/guest.js", async (importOriginal) => ({
@@ -39,11 +49,12 @@ const environment = {
 function fixture(os: Environment["os"] = "linux") {
   const events: string[] = [];
   const broker = {
-    reconcileRunner: vi.fn(async () => {
+    reconcileRunner: vi.fn<RunnerBroker["reconcileRunner"]>(async () => {
       throw new Error("unused");
     }),
     prepareRunner: vi.fn(async () => ({
       state: "ready" as const,
+      cacheWrite: false,
       id: "lease",
       runnerId: 12,
       encodedConfig: "c2VjcmV0",
@@ -89,6 +100,302 @@ function fixture(os: Environment["os"] = "linux") {
   });
   return { controls, broker, events };
 }
+
+test.each(["linux", "macos", "windows"] as const)(
+  "%s cache privilege failure stops before installation and registration and discards the fork",
+  async (os) => {
+    const { controls, broker } = fixture(os);
+    const authorizeWrite = vi.fn();
+    const checked = vi.fn();
+    vi.mocked(executeGuest).mockResolvedValueOnce({
+      exitCode: 1,
+      stdout: "",
+      stderr: "sudo: a password is required",
+      truncated: false,
+    });
+    const result = await runRunnerTask(
+      "binding",
+      "key",
+      { ...environment, os },
+      {
+        ...controls,
+        cache: { sizeGiB: 1, outcome: () => ({ promoted: false }), authorizeWrite, checked },
+      },
+      new AbortController().signal,
+    );
+    const error = cachePrivilegeError();
+    expect(result).toMatchObject({
+      status: "failed",
+      code: error.code,
+      message: error.message,
+      nextStep: error.nextStep,
+    });
+    expect(executeGuest).toHaveBeenCalledExactlyOnceWith(
+      expect.anything(),
+      cachePrivilegeScript(os),
+      expect.objectContaining({ shell: os === "windows" ? "powershell" : "bash" }),
+    );
+    expect(readyGuest).toHaveBeenCalledOnce();
+    expect(checked).toHaveBeenCalledExactlyOnceWith(false);
+    expect(broker.prepareRunner).not.toHaveBeenCalled();
+    expect(broker.releaseRunner).not.toHaveBeenCalled();
+    expect(broker.reconcileRunner).not.toHaveBeenCalled();
+    expect(controls.stop).toHaveBeenCalledOnce();
+    expect(authorizeWrite).not.toHaveBeenCalled();
+  },
+);
+
+test("an unavailable privilege probe does not record missing sudo", async () => {
+  const { controls, broker } = fixture();
+  const checked = vi.fn();
+  vi.mocked(executeGuest).mockRejectedValueOnce(new GuestUnavailableError("connection lost"));
+  const result = await runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    {
+      ...controls,
+      cache: { sizeGiB: 1, outcome: () => ({ promoted: false }), authorizeWrite: vi.fn(), checked },
+    },
+    new AbortController().signal,
+  );
+  expect(result).toMatchObject({ status: "failed", code: "guest_unavailable" });
+  expect(checked).not.toHaveBeenCalled();
+  expect(broker.prepareRunner).not.toHaveBeenCalled();
+  expect(controls.stop).toHaveBeenCalledOnce();
+});
+
+test.each(
+  (["linux", "macos", "windows"] as const).flatMap((os) =>
+    [false, true].map((preinstalled) => ({ os, preinstalled })),
+  ),
+)(
+  "$os warm takeover with preinstalled=$preinstalled requests credentials only after guest verification",
+  async ({ os, preinstalled }) => {
+    const { controls, broker } = fixture(os);
+    const connection = {
+      host: "192.0.2.1",
+      port: 22,
+      user: "test",
+      identityFile: "/unused/key",
+      knownHostsFile: "/unused/hosts",
+      hostKeyAlias: "warm",
+    };
+    const claimWarm = vi.fn(() => ({
+      instance: {
+        id: "warm",
+        environmentId: environment.id,
+        status: "running" as const,
+        pid: 0,
+        createdAt: "",
+      },
+      connection,
+    }));
+    broker.prepareRunner.mockImplementationOnce(async () => {
+      expect(executeGuest).toHaveBeenCalledTimes(preinstalled ? 1 : 2);
+      expect(executeGuest).toHaveBeenNthCalledWith(
+        1,
+        connection,
+        "exit 0",
+        expect.objectContaining({ shell: os === "windows" ? "powershell" : "bash" }),
+      );
+      return {
+        state: "ready",
+        cacheWrite: false,
+        id: "lease",
+        runnerId: 12,
+        encodedConfig: "c2VjcmV0",
+        environmentId: "test",
+        access: { repositoryId: 2, actors: "any", approval: "automatic" },
+        os,
+      };
+    });
+    const result = await runRunnerTask(
+      "binding",
+      "key",
+      {
+        ...environment,
+        os,
+        ...(preinstalled
+          ? {
+              image: { revision: "revision", runnerVersion, provisionedAt: "2026-10-16T00:00:00Z" },
+            }
+          : {}),
+      },
+      { ...controls, claimWarm },
+      AbortSignal.timeout(1000),
+    );
+    expect(result.status).toBe("succeeded");
+    expect(
+      Schema.decodeUnknownSync(RunnerProgress)(result.progress).phases?.map((phase) => phase.name),
+    ).toEqual([
+      "queued_locally",
+      "warm_takeover",
+      "guest_ready",
+      preinstalled ? "runner_preinstalled" : "runner_install",
+      "registration",
+      "waiting_for_job",
+      "cleanup",
+    ]);
+    expect(result.progress.phases?.every((phase) => phase.endedAt !== undefined)).toBe(true);
+    expect(claimWarm).toHaveBeenCalledOnce();
+    expect(controls.start).not.toHaveBeenCalled();
+    expect(readyGuest).not.toHaveBeenCalled();
+    expect(controls.stop).toHaveBeenCalledOnce();
+  },
+);
+
+test("a failed warm health command stops the claim before a cold start", async () => {
+  const { controls, broker, events } = fixture();
+  const connection = {
+    host: "192.0.2.1",
+    port: 22,
+    user: "test",
+    identityFile: "/unused/key",
+    knownHostsFile: "/unused/hosts",
+    hostKeyAlias: "warm",
+  };
+  vi.mocked(executeGuest).mockResolvedValueOnce({
+    exitCode: 1,
+    stdout: "",
+    stderr: "",
+    truncated: false,
+  });
+  controls.start.mockImplementationOnce(async () => {
+    expect(events).toEqual(["stop"]);
+    expect(broker.prepareRunner).not.toHaveBeenCalled();
+    return { id: "cold", environmentId: "test", status: "running", pid: 0, createdAt: "" };
+  });
+  const result = await runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    {
+      ...controls,
+      claimWarm: () => ({
+        instance: { id: "warm", environmentId: "test", status: "running", pid: 0, createdAt: "" },
+        connection,
+      }),
+    },
+    AbortSignal.timeout(1000),
+  );
+  expect(result.status).toBe("succeeded");
+  expect(result.progress.instanceId).toBe("cold");
+  expect(result.progress.phases?.map((phase) => phase.name)).toEqual([
+    "queued_locally",
+    "warm_takeover",
+    "guest_ready",
+    "vm_start",
+    "guest_ready",
+    "runner_install",
+    "registration",
+    "waiting_for_job",
+    "cleanup",
+  ]);
+  expect(result.progress.phases?.every((phase) => phase.endedAt !== undefined)).toBe(true);
+  expect(readyGuest).toHaveBeenCalledOnce();
+  expect(controls.stop).toHaveBeenCalledTimes(2);
+});
+
+test("unconfirmed warm cleanup prevents cold fallback and JIT registration", async () => {
+  const { controls, broker } = fixture();
+  const connection = {
+    host: "192.0.2.1",
+    port: 22,
+    user: "test",
+    identityFile: "/unused/key",
+    knownHostsFile: "/unused/hosts",
+    hostKeyAlias: "warm",
+  };
+  vi.mocked(executeGuest).mockRejectedValueOnce(new GuestUnavailableError("SSH lost"));
+  controls.stop.mockRejectedValue(new Error("unconfirmed"));
+  const result = await runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    {
+      ...controls,
+      claimWarm: () => ({
+        instance: { id: "warm", environmentId: "test", status: "running", pid: 0, createdAt: "" },
+        connection,
+      }),
+    },
+    AbortSignal.timeout(1000),
+  );
+  expect(result).toMatchObject({
+    status: "action_required",
+    code: "runner_cleanup_required",
+    progress: { instanceId: "warm" },
+  });
+  expect(controls.start).not.toHaveBeenCalled();
+  expect(broker.prepareRunner).not.toHaveBeenCalled();
+});
+test.each(["linux", "macos", "windows"] as const)(
+  "%s starts the baked runner without an install when the manifest matches",
+  async (os) => {
+    const { controls } = fixture(os);
+    const result = await runRunnerTask(
+      "binding",
+      "key",
+      {
+        ...environment,
+        os,
+        image: { revision: "revision", runnerVersion, provisionedAt: "2026-10-16T00:00:00Z" },
+      },
+      controls,
+      new AbortController().signal,
+    );
+    expect(result.status).toBe("succeeded");
+    expect(result.progress.phases?.map((phase) => phase.name)).toEqual([
+      "queued_locally",
+      "vm_start",
+      "guest_ready",
+      "runner_preinstalled",
+      "registration",
+      "waiting_for_job",
+      "cleanup",
+    ]);
+    expect(result.progress.phases?.every((phase) => phase.endedAt !== undefined)).toBe(true);
+    const scripts = vi.mocked(executeGuest).mock.calls.map((call) => call[1]);
+    expect(scripts.some((script) => script.includes(preinstalledRunnerDirectory(os)))).toBe(true);
+    expect(scripts.join("\n")).not.toMatch(/Invoke-WebRequest|curl --fail/);
+    expect(scripts.join("\n")).toContain("--jitconfig");
+    expect(controls.stop).toHaveBeenCalledOnce();
+  },
+);
+test.each([undefined, "old-version"])(
+  "a %s runner manifest uses the existing verified install path with a 600 s timeout",
+  async (version) => {
+    const { controls } = fixture();
+    const timeout = vi.spyOn(AbortSignal, "timeout");
+    const result = await runRunnerTask(
+      "binding",
+      "key",
+      {
+        ...environment,
+        ...(version
+          ? {
+              image: {
+                revision: "revision",
+                runnerVersion: version,
+                provisionedAt: "2026-10-16T00:00:00Z",
+              },
+            }
+          : {}),
+      },
+      controls,
+      new AbortController().signal,
+    );
+    expect(result.status).toBe("succeeded");
+    expect(executeGuest).toHaveBeenNthCalledWith(
+      1,
+      expect.anything(),
+      expect.stringContaining("curl --fail"),
+      expect.objectContaining({ shell: "bash" }),
+    );
+    expect(timeout).toHaveBeenCalledWith(600000);
+  },
+);
 test("a failed pinned guest identity never allocates JIT credentials or sends runner scripts", async () => {
   const { controls, broker } = fixture();
   vi.mocked(readyGuest).mockRejectedValue(
@@ -120,6 +427,163 @@ test("stops the VM before removing registration and never persists JIT configura
   expect(JSON.stringify(controls.progress.mock.calls)).not.toContain("c2VjcmV0");
   expect(result.message).toContain("Check GitHub");
 });
+
+test("phase history records ordered durations with the injected clock through job exit and cleanup", async () => {
+  vi.useFakeTimers();
+  const { controls, broker } = fixture();
+  const base = Date.parse("2026-10-16T00:00:00.000Z");
+  let clock = base + 5000;
+  const instance = await controls.start();
+  controls.start.mockClear();
+  controls.start.mockImplementation(async () => {
+    clock += 1200;
+    return instance;
+  });
+  const connection = await readyGuest(environment, instance, new AbortController().signal);
+  vi.mocked(readyGuest).mockClear();
+  vi.mocked(readyGuest).mockImplementation(async () => {
+    clock += 800;
+    return connection;
+  });
+  const grant = await broker.prepareRunner();
+  broker.prepareRunner.mockImplementation(async () => {
+    clock += 200;
+    return grant;
+  });
+  controls.stop.mockImplementation(async () => {
+    clock += 200;
+  });
+  broker.releaseRunner.mockImplementation(async () => {
+    clock += 300;
+  });
+  let finish = () => {};
+  vi.mocked(executeGuest)
+    .mockImplementationOnce(async () => {
+      clock += 900;
+      return { exitCode: 0, stdout: "", stderr: "", truncated: false };
+    })
+    .mockImplementationOnce(async () => {
+      await new Promise<void>((resolve) => {
+        finish = resolve;
+      });
+      return { exitCode: 0, stdout: "", stderr: "", truncated: false };
+    });
+  broker.runnerStatus.mockResolvedValue({ busy: true, status: "online" });
+  const result = runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    {
+      ...controls,
+      now: () => clock,
+      acceptedAt: new Date(base).toISOString(),
+      needed: async () => {
+        clock += 100;
+        return true;
+      },
+    },
+    new AbortController().signal,
+  );
+  await vi.advanceTimersByTimeAsync(0);
+  clock += 30000;
+  await vi.advanceTimersByTimeAsync(30000);
+  clock += 10000;
+  finish();
+  const completed = await result;
+  expect(completed.status).toBe("succeeded");
+  expect(
+    completed.progress.phases?.map((phase) => [
+      phase.name,
+      Date.parse(phase.endedAt ?? "") - Date.parse(phase.startedAt),
+    ]),
+  ).toEqual([
+    ["queued_locally", 5000],
+    ["job_check", 100],
+    ["vm_start", 1200],
+    ["guest_ready", 800],
+    ["runner_install", 900],
+    ["job_check", 100],
+    ["registration", 200],
+    ["waiting_for_job", 30000],
+    ["job", 10000],
+    ["cleanup", 500],
+  ]);
+  const snapshots = controls.progress.mock.calls.map(([value]) =>
+    Schema.decodeUnknownSync(RunnerProgress)(value),
+  );
+  expect(snapshots[0]?.phases).toHaveLength(1);
+  expect(snapshots.at(-1)).toEqual(completed.progress);
+  expect(
+    snapshots.some((snapshot) =>
+      snapshot.phases?.some((phase) => phase.name === "job" && !phase.endedAt),
+    ),
+  ).toBe(true);
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+test.each([undefined, "rosetta"] as const)(
+  "%s startup attributes readiness inside environment.start to its startup phase",
+  async (x64) => {
+    const { controls } = fixture();
+    const instance = await controls.start();
+    controls.start.mockImplementation(async () => {
+      clock += 6000;
+      return instance;
+    });
+    let clock = Date.parse("2026-10-16T00:00:00.000Z");
+    const result = await runRunnerTask(
+      "binding",
+      "key",
+      { ...environment, ...(x64 ? { x64 } : {}) },
+      { ...controls, now: () => clock },
+      new AbortController().signal,
+    );
+    expect(result.status).toBe("succeeded");
+    expect(result.progress.phases?.slice(1, 3)).toEqual([
+      {
+        name: x64 ? "vm_start_and_guest_ready" : "vm_start",
+        startedAt: "2026-10-16T00:00:00.000Z",
+        endedAt: "2026-10-16T00:00:06.000Z",
+      },
+      {
+        name: "guest_ready",
+        startedAt: "2026-10-16T00:00:06.000Z",
+        endedAt: "2026-10-16T00:00:06.000Z",
+      },
+    ]);
+  },
+);
+
+test("guest readiness failure closes the failed phase before timing cleanup", async () => {
+  const { controls } = fixture();
+  let clock = Date.parse("2026-10-16T00:00:00.000Z");
+  vi.mocked(readyGuest).mockImplementation(async () => {
+    clock += 8000;
+    throw new GuestUnavailableError("SSH timeout");
+  });
+  controls.stop.mockImplementation(async () => {
+    clock += 2000;
+  });
+  const result = await runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    { ...controls, now: () => clock },
+    new AbortController().signal,
+  );
+  expect(result).toMatchObject({ status: "failed", code: "guest_unavailable" });
+  expect(
+    result.progress.phases?.map((phase) => [
+      phase.name,
+      Date.parse(phase.endedAt ?? "") - Date.parse(phase.startedAt),
+    ]),
+  ).toEqual([
+    ["queued_locally", 0],
+    ["vm_start", 0],
+    ["guest_ready", 8000],
+    ["cleanup", 2000],
+  ]);
+});
 test("retains registration if VM termination is unconfirmed", async () => {
   const { controls, broker } = fixture();
   controls.stop.mockRejectedValue(new Error("exit unknown"));
@@ -131,6 +595,10 @@ test("retains registration if VM termination is unconfirmed", async () => {
     AbortSignal.timeout(1000),
   );
   expect(result.status).toBe("action_required");
+  expect(result.progress.phases?.at(-1)).toMatchObject({
+    name: "cleanup",
+    endedAt: expect.any(String),
+  });
   expect(broker.releaseRunner).not.toHaveBeenCalled();
 });
 test("a lost registration response requires reconciliation instead of a fresh retry", async () => {
@@ -281,7 +749,18 @@ test("successful and cancelled runners gather no diagnostics", async () => {
   expect(collectRunnerDiagnostics).not.toHaveBeenCalled();
 });
 
-async function listeningFixture(withJob = true) {
+async function listeningFixture(
+  withJob = true,
+  timings: Pick<
+    Parameters<typeof runRunnerTask>[3],
+    | "request"
+    | "now"
+    | "pollIntervalMs"
+    | "idleTimeoutMs"
+    | "offlineTimeoutMs"
+    | "statusFailureTimeoutMs"
+  > = {},
+) {
   vi.useFakeTimers();
   const { controls, broker, events } = fixture();
   const abort = new AbortController();
@@ -310,7 +789,7 @@ async function listeningFixture(withJob = true) {
     "binding",
     "key",
     environment,
-    { ...controls, ...(withJob ? { needed } : {}) },
+    { ...controls, ...timings, ...(withJob ? { needed } : {}) },
     abort.signal,
   );
   listeningTasks.push({ abort, done });
@@ -321,25 +800,32 @@ async function listeningFixture(withJob = true) {
   return { controls, broker, events, abort, needed, done, complete };
 }
 
-test.each([
-  { busy: false, status: "online" as const },
-  { busy: false, status: "offline" as const },
-  { missing: true as const },
-])(
-  "an idle runner with status %j drains only after ten minutes and releases capacity",
+test.each([{ busy: false, status: "online" as const }])(
+  "an idle runner with status %j drains only after five minutes and releases capacity",
   async (status) => {
-    const { broker, events, needed, done } = await listeningFixture();
+    let clock = Date.parse("2026-10-16T00:00:00.000Z");
+    const { broker, events, needed, done } = await listeningFixture(true, { now: () => clock });
     broker.runnerStatus.mockResolvedValue(status);
     needed.mockResolvedValue(false);
-    await vi.advanceTimersByTimeAsync(10 * 60 * 1000 - 1);
+    await vi.advanceTimersByTimeAsync(5 * 60 * 1000 - 1);
     expect(events).toEqual([]);
     expect(needed).toHaveBeenCalledTimes(2);
+    clock += 5 * 60 * 1000;
     await vi.advanceTimersByTimeAsync(1);
-    expect(await done).toMatchObject({
+    const completed = await done;
+    expect(completed).toMatchObject({
       status: "cancelled",
       code: "runner_idle",
       progress: { stage: "finished" },
     });
+    const phases = completed.progress.phases;
+    expect(phases?.find((phase) => phase.name === "waiting_for_job")).toEqual({
+      name: "waiting_for_job",
+      startedAt: "2026-10-16T00:00:00.000Z",
+      endedAt: "2026-10-16T00:05:00.000Z",
+    });
+    expect(phases?.some((phase) => phase.name === "job")).toBe(false);
+    expect(phases?.every((phase) => phase.endedAt)).toBe(true);
     expect(events).toEqual(["stop", "release"]);
     expect(broker.releaseRunner).toHaveBeenCalledWith("lease", expect.any(AbortSignal));
     expect(collectRunnerDiagnostics).not.toHaveBeenCalled();
@@ -350,7 +836,7 @@ test.each([
 test("a busy runner keeps its VM even after the requested job no longer needs capacity", async () => {
   const { broker, events, needed, done, complete } = await listeningFixture();
   needed.mockResolvedValue(false);
-  await vi.advanceTimersByTimeAsync(9 * 60 * 1000);
+  await vi.advanceTimersByTimeAsync(4 * 60 * 1000);
   broker.runnerStatus.mockResolvedValue({ busy: true, status: "online" });
   await vi.advanceTimersByTimeAsync(20 * 60 * 1000);
   expect(events).toEqual([]);
@@ -363,11 +849,11 @@ test("a busy runner keeps its VM even after the requested job no longer needs ca
 test("the idle window restarts after the runner was busy", async () => {
   const { broker, events, needed, done } = await listeningFixture();
   needed.mockResolvedValue(false);
-  await vi.advanceTimersByTimeAsync(9 * 60 * 1000);
+  await vi.advanceTimersByTimeAsync(4 * 60 * 1000);
   broker.runnerStatus.mockResolvedValue({ busy: true, status: "online" });
   await vi.advanceTimersByTimeAsync(30000);
   broker.runnerStatus.mockResolvedValue({ busy: false, status: "online" });
-  await vi.advanceTimersByTimeAsync(10 * 60 * 1000 - 1);
+  await vi.advanceTimersByTimeAsync(5 * 60 * 1000 - 1);
   expect(events).toEqual([]);
   await vi.advanceTimersByTimeAsync(1);
   expect(await done).toMatchObject({ status: "cancelled", code: "runner_idle" });
@@ -379,24 +865,40 @@ test("an idle runner whose requested job still needs queued capacity keeps liste
   expect(needed.mock.calls.length).toBeGreaterThan(2);
   expect(events).toEqual([]);
   complete();
-  expect(await done).toMatchObject({ status: "succeeded" });
+  const completed = await done;
+  expect(completed).toMatchObject({ status: "succeeded" });
+  const phases = completed.progress.phases;
+  expect(phases).toHaveLength(16);
+  expect(phases?.filter((phase) => phase.name === "job_check").length).toBeLessThan(
+    needed.mock.calls.length,
+  );
+  expect(phases?.map((phase) => phase.name)).toEqual(
+    expect.arrayContaining([
+      "queued_locally",
+      "vm_start",
+      "guest_ready",
+      "runner_install",
+      "registration",
+      "waiting_for_job",
+      "cleanup",
+    ]),
+  );
+  expect(phases?.every((phase) => phase.endedAt)).toBe(true);
 });
 
 test.each(["status", "job"] as const)(
-  "%s lookup errors keep listening and require a fresh idle window",
+  "%s lookup errors do not discard already observed idle time",
   async (lookup) => {
     const { broker, events, needed, done } = await listeningFixture();
     if (lookup === "status") {
       broker.runnerStatus.mockRejectedValue(new Error("GitHub unavailable"));
       needed.mockResolvedValue(false);
     } else needed.mockRejectedValue(new Error("Job unknown"));
-    await vi.advanceTimersByTimeAsync(20 * 60 * 1000);
+    await vi.advanceTimersByTimeAsync(6 * 60 * 1000);
     expect(events).toEqual([]);
     broker.runnerStatus.mockResolvedValue({ busy: false, status: "online" });
     needed.mockResolvedValue(false);
-    await vi.advanceTimersByTimeAsync(10 * 60 * 1000 - 1);
-    expect(events).toEqual([]);
-    await vi.advanceTimersByTimeAsync(1);
+    await vi.advanceTimersByTimeAsync(30000);
     expect(await done).toMatchObject({ status: "cancelled", code: "runner_idle" });
   },
 );
@@ -420,7 +922,7 @@ test.each(["stop", "release"] as const)(
     needed.mockResolvedValue(false);
     if (step === "stop") controls.stop.mockRejectedValue(new Error("VM exit unknown"));
     else broker.releaseRunner.mockRejectedValue(new Error("Registration unknown"));
-    await vi.advanceTimersByTimeAsync(10 * 60 * 1000);
+    await vi.advanceTimersByTimeAsync(5 * 60 * 1000);
     expect(await done).toMatchObject({
       status: "action_required",
       code: "runner_cleanup_required",
@@ -456,11 +958,67 @@ test("the six-hour listening timeout still cleans up without reporting idle drai
   expect(vi.getTimerCount()).toBe(0);
 });
 
-test("a manual runner without a requested job keeps listening beyond the idle window", async () => {
-  const { broker, events, done, complete } = await listeningFixture(false);
-  await vi.advanceTimersByTimeAsync(20 * 60 * 1000);
+test("a manual runner without a requested job drains after five idle minutes", async () => {
+  const { broker, events, done } = await listeningFixture(false);
+  await vi.advanceTimersByTimeAsync(5 * 60 * 1000 - 1);
+  expect(events).toEqual([]);
+  await vi.advanceTimersByTimeAsync(1);
+  expect(await done).toMatchObject({ status: "cancelled", code: "runner_idle" });
+  expect(broker.runnerStatus).toHaveBeenCalled();
+  expect(events).toEqual(["stop", "release"]);
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+test.each([{ busy: false, status: "offline" as const }, { missing: true as const }])(
+  "a runner reported as %j for two minutes stops even when its job is still needed",
+  async (status) => {
+    const { broker, events, done } = await listeningFixture();
+    broker.runnerStatus.mockResolvedValue(status);
+    await vi.advanceTimersByTimeAsync(30000 + 2 * 60000 - 1);
+    expect(events).toEqual([]);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(await done).toMatchObject({ status: "failed", code: "runner_offline" });
+    expect(events).toEqual(["stop", "release"]);
+    expect(vi.getTimerCount()).toBe(0);
+  },
+);
+
+test("offline observations must be consecutive and busy status prevents stopping", async () => {
+  const { broker, events, done, complete } = await listeningFixture();
+  broker.runnerStatus.mockResolvedValue({ busy: false, status: "offline" });
+  await vi.advanceTimersByTimeAsync(2 * 60000);
+  broker.runnerStatus.mockResolvedValue({ busy: false, status: "online" });
+  await vi.advanceTimersByTimeAsync(30000);
+  broker.runnerStatus.mockResolvedValue({ busy: false, status: "offline" });
+  await vi.advanceTimersByTimeAsync(2 * 60000);
+  expect(events).toEqual([]);
+  broker.runnerStatus.mockResolvedValue({ busy: true, status: "offline" });
+  await vi.advanceTimersByTimeAsync(5 * 60000);
+  expect(events).toEqual([]);
+  complete();
+  expect(await done).toMatchObject({ status: "succeeded" });
+});
+
+test("fifteen minutes of continuous status failures treats the runner as offline", async () => {
+  const { broker, events, done } = await listeningFixture();
+  broker.runnerStatus.mockRejectedValue(new Error("GitHub unavailable"));
+  await vi.advanceTimersByTimeAsync(30000 + 15 * 60000 - 1);
+  expect(events).toEqual([]);
+  await vi.advanceTimersByTimeAsync(1);
+  expect(await done).toMatchObject({ status: "failed", code: "runner_offline" });
+  expect(events).toEqual(["stop", "release"]);
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+test("successful status reads restart the continuous status failure window", async () => {
+  const { broker, events, done, complete } = await listeningFixture();
+  broker.runnerStatus.mockRejectedValue(new Error("GitHub unavailable"));
+  await vi.advanceTimersByTimeAsync(14 * 60000);
+  broker.runnerStatus.mockResolvedValue({ busy: false, status: "online" });
+  await vi.advanceTimersByTimeAsync(30000);
+  broker.runnerStatus.mockRejectedValue(new Error("GitHub unavailable"));
+  await vi.advanceTimersByTimeAsync(14 * 60000);
   expect(events).toEqual([]);
-  expect(broker.runnerStatus).not.toHaveBeenCalled();
   complete();
   expect(await done).toMatchObject({ status: "succeeded" });
 });
@@ -507,6 +1065,164 @@ function heldListener() {
   return state;
 }
 
+test.each([
+  {
+    name: "hook before any busy poll",
+    marker: "1234",
+    visibleAt: 0,
+    finishAt: 25000,
+    startAt: 1234,
+  },
+  {
+    name: "short job read at listener exit",
+    marker: "1234",
+    visibleAt: 0,
+    finishAt: 5000,
+    startAt: 1234,
+  },
+  {
+    name: "hook corrects an earlier busy observation",
+    marker: "1234",
+    visibleAt: 35000,
+    finishAt: 35000,
+    startAt: 1234,
+  },
+  {
+    name: "slow guest clock clamps to registration end",
+    marker: "-1000",
+    visibleAt: 0,
+    finishAt: 25000,
+    startAt: 0,
+  },
+  {
+    name: "fast guest clock clamps to observation time",
+    marker: "60000",
+    visibleAt: 0,
+    finishAt: 25000,
+    startAt: 10000,
+  },
+  ...[undefined, "invalid", "NaN", "Infinity", "1.5", "9007199254740992", "1234 trailing", ""].map(
+    (marker) => ({
+      name: `busy fallback for marker ${String(marker)}`,
+      marker,
+      visibleAt: 0,
+      finishAt: 35000,
+      startAt: 30000,
+    }),
+  ),
+])("job timing uses $name", async ({ marker, visibleAt, finishAt, startAt }) => {
+  vi.useFakeTimers();
+  const base = Date.parse("2026-10-16T00:00:00.000Z");
+  vi.setSystemTime(base);
+  const { controls, broker } = fixture();
+  const listener = heldListener();
+  broker.runnerStatus.mockResolvedValue({ busy: true, status: "online" });
+  const value =
+    marker !== undefined && /^-?\d+$/.test(marker) && Number.isSafeInteger(Number(marker))
+      ? String(base + Number(marker))
+      : marker;
+  vi.mocked(executeGuest).mockImplementation(async () => ({
+    exitCode: 0,
+    stdout:
+      Date.now() - base >= visibleAt && value !== undefined
+        ? `${jobStartedMarker}\r\n${value}\r\n`
+        : "",
+    stderr: "",
+    truncated: false,
+  }));
+  const abort = new AbortController();
+  const done = runRunnerTask("binding", "key", environment, controls, abort.signal);
+  listeningTasks.push({ abort, done });
+  await vi.advanceTimersByTimeAsync(finishAt);
+  listener.finish?.();
+  const result = await done;
+  expect(result.status).toBe("succeeded");
+  expect(
+    result.progress.phases?.filter((phase) => ["waiting_for_job", "job"].includes(phase.name)),
+  ).toEqual([
+    {
+      name: "waiting_for_job",
+      startedAt: new Date(base).toISOString(),
+      endedAt: new Date(base + startAt).toISOString(),
+    },
+    {
+      name: "job",
+      startedAt: new Date(base + startAt).toISOString(),
+      endedAt: new Date(base + finishAt).toISOString(),
+    },
+  ]);
+  expect(executeGuest).toHaveBeenCalledTimes(3 + Math.floor(finishAt / 10000));
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+test.each(["linux", "macos", "windows"] as const)(
+  "%s reads the job marker in the existing gate poll",
+  async (os) => {
+    vi.useFakeTimers();
+    const base = Date.parse("2026-10-16T00:00:00.000Z");
+    vi.setSystemTime(base);
+    const { controls, broker } = fixture(os);
+    const listener = heldListener();
+    vi.mocked(executeGuest).mockResolvedValue({
+      exitCode: 0,
+      stdout: `${jobStartedMarker}\n${base + 1500}\n`,
+      stderr: "",
+      truncated: false,
+    });
+    const abort = new AbortController();
+    const done = runRunnerTask("binding", "key", { ...environment, os }, controls, abort.signal);
+    listeningTasks.push({ abort, done });
+    await vi.advanceTimersByTimeAsync(10000);
+    expect(broker.runnerStatus).not.toHaveBeenCalled();
+    expect(executeGuest).toHaveBeenCalledTimes(3);
+    expect(executeGuest).toHaveBeenLastCalledWith(
+      expect.anything(),
+      expect.stringContaining("job-started"),
+      expect.objectContaining({ shell: os === "windows" ? "powershell" : "bash" }),
+    );
+    expect(controls.progress).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        phases: expect.arrayContaining([
+          { name: "job", startedAt: new Date(base + 1500).toISOString() },
+        ]),
+      }),
+    );
+    listener.finish?.();
+    expect(await done).toMatchObject({ status: "succeeded" });
+    expect(vi.getTimerCount()).toBe(0);
+  },
+);
+
+test("a slow final gate read preserves listener exit time and clamps the guest start to it", async () => {
+  vi.useFakeTimers();
+  const base = Date.parse("2026-10-16T00:00:00.000Z");
+  vi.setSystemTime(base);
+  const { controls } = fixture();
+  const listener = heldListener();
+  vi.mocked(executeGuest).mockImplementationOnce(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 4000));
+    return {
+      exitCode: 0,
+      stdout: `${jobStartedMarker}\n${base + 7000}\n`,
+      stderr: "",
+      truncated: false,
+    };
+  });
+  const abort = new AbortController();
+  const done = runRunnerTask("binding", "key", environment, controls, abort.signal);
+  listeningTasks.push({ abort, done });
+  await vi.advanceTimersByTimeAsync(5000);
+  listener.finish?.();
+  await vi.advanceTimersByTimeAsync(4000);
+  const result = await done;
+  expect(result.progress.phases?.find((phase) => phase.name === "job")).toEqual({
+    name: "job",
+    startedAt: new Date(base + 5000).toISOString(),
+    endedAt: new Date(base + 5000).toISOString(),
+  });
+  expect(vi.getTimerCount()).toBe(0);
+});
+
 test.each(["linux", "macos", "windows"] as const)(
   "%s marker backstop aborts listening and stops the VM before releasing the runner",
   async (os) => {
@@ -703,3 +1419,380 @@ test.each(["stop", "release"] as const)(
     if (step === "stop") expect(broker.releaseRunner).not.toHaveBeenCalled();
   },
 );
+
+test("a prepare failure before a lease claim is fenced and becomes retryable", async () => {
+  const { controls, broker } = fixture();
+  broker.prepareRunner.mockRejectedValue(new Error("Token request failed"));
+  broker.reconcileRunner.mockResolvedValue({
+    id: "fence",
+    bindingId: "binding",
+    environmentId: "test",
+    phase: "released",
+  });
+  const result = await runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    controls,
+    AbortSignal.timeout(1000),
+  );
+  expect(result).toMatchObject({ status: "failed", code: "runner_registration_failed" });
+  expect(controls.stop).toHaveBeenCalledOnce();
+  expect(broker.reconcileRunner).toHaveBeenCalledWith(
+    { bindingId: "binding", environmentId: "test", key: "key" },
+    expect.any(AbortSignal),
+  );
+  expect(broker.releaseRunner).not.toHaveBeenCalled();
+});
+
+test("a lost prepare response with a claimed lease waits for release confirmation", async () => {
+  const { controls, broker } = fixture();
+  broker.prepareRunner.mockRejectedValue(new Error("Response lost"));
+  broker.reconcileRunner.mockResolvedValue({
+    id: "lease",
+    bindingId: "binding",
+    environmentId: "test",
+    phase: "ready",
+  });
+  broker.releaseRunner.mockRejectedValue(new Error("Release unconfirmed"));
+  const result = await runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    controls,
+    AbortSignal.timeout(1000),
+  );
+  expect(result).toMatchObject({
+    status: "action_required",
+    code: "runner_registration_uncertain",
+    progress: { leaseId: "lease" },
+  });
+});
+
+test("a locally rejected prepare request is retryable without requiring cloud reconciliation", async () => {
+  const { controls, broker } = fixture();
+  broker.prepareRunner.mockRejectedValue(new VectisError("cloud_unavailable", "Disconnected"));
+  const result = await runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    controls,
+    AbortSignal.timeout(1000),
+  );
+  expect(result).toMatchObject({ status: "failed", code: "runner_registration_failed" });
+  expect(broker.reconcileRunner).not.toHaveBeenCalled();
+  expect(controls.stop).toHaveBeenCalledOnce();
+});
+
+test.each(["idle", "offline", "errors"] as const)(
+  "watchdog %s timings are injectable",
+  async (state) => {
+    const { broker, done } = await listeningFixture(false, {
+      pollIntervalMs: 10,
+      idleTimeoutMs: 40,
+      offlineTimeoutMs: 20,
+      statusFailureTimeoutMs: 30,
+      now: () => Date.now(),
+    });
+    if (state === "offline") broker.runnerStatus.mockResolvedValue({ missing: true });
+    if (state === "errors") broker.runnerStatus.mockRejectedValue(new Error("Unavailable"));
+    await vi.advanceTimersByTimeAsync(state === "offline" ? 30 : 40);
+    expect(await done).toMatchObject({
+      status: state === "idle" ? "cancelled" : "failed",
+      code: state === "idle" ? "runner_idle" : "runner_offline",
+    });
+    expect(vi.getTimerCount()).toBe(0);
+  },
+);
+
+test("offline failure survives unconfirmed VM cleanup", async () => {
+  const { controls, broker, done } = await listeningFixture(false, {
+    pollIntervalMs: 10,
+    offlineTimeoutMs: 20,
+  });
+  controls.stop.mockRejectedValue(new Error("Exit unconfirmed"));
+  broker.runnerStatus.mockResolvedValue({ missing: true });
+  await vi.advanceTimersByTimeAsync(30);
+  expect(await done).toMatchObject({
+    status: "action_required",
+    code: "runner_cleanup_required",
+    recoveryCause: { code: "runner_offline" },
+  });
+  expect(broker.releaseRunner).not.toHaveBeenCalled();
+});
+
+test.each([true, false])(
+  "cache promotion requires cacheWrite=%s and a clean unmount before VM stop",
+  async (cacheWrite) => {
+    const { controls, broker, events } = fixture();
+    const grant = await broker.prepareRunner();
+    const checked = vi.fn();
+    const prepareRunner = vi.fn(async () => {
+      expect(checked).toHaveBeenCalledExactlyOnceWith(true);
+      expect(vi.mocked(executeGuest).mock.calls[0]?.[1]).toBe("sudo -n true\n");
+      return {
+        ...grant,
+        cacheWrite,
+        access: {
+          ...grant.access,
+          ...(cacheWrite ? { cacheRun: { runId: 5, runAttempt: 1 } } : {}),
+        },
+      };
+    });
+    let promoted = false;
+    const authorizeWrite = vi.fn(() => {
+      events.push("authorize");
+      expect(promoted).toBe(false);
+    });
+    controls.stop.mockImplementation(async () => {
+      events.push("stop");
+      if (authorizeWrite.mock.calls.length) {
+        events.push("promote");
+        promoted = true;
+      }
+    });
+    vi.mocked(executeGuest).mockImplementation(async (_connection, script) => {
+      if (script.includes("sudo -n umount /vectis-cache")) events.push("unmount");
+      return { exitCode: 0, stdout: "", stderr: "", truncated: false };
+    });
+    const result = await runRunnerTask(
+      "binding",
+      "key",
+      environment,
+      {
+        ...controls,
+        broker: { ...broker, prepareRunner },
+        cache: { sizeGiB: 20, outcome: () => ({ promoted }), authorizeWrite, checked },
+      },
+      new AbortController().signal,
+    );
+    expect(result.status).toBe("succeeded");
+    expect(result.progress.cache).toEqual({
+      attached: true,
+      writeBack: cacheWrite ? "granted" : "denied",
+      promoted: cacheWrite,
+      reason: cacheWrite ? undefined : "policy_denied",
+    });
+    expect(events).toEqual(
+      cacheWrite
+        ? ["unmount", "authorize", "stop", "promote", "release"]
+        : ["unmount", "stop", "release"],
+    );
+  },
+);
+
+test("a failed cache unmount discards even a trusted writer", async () => {
+  const { controls, broker } = fixture();
+  const grant = await broker.prepareRunner();
+  const authorizeWrite = vi.fn();
+  vi.mocked(executeGuest).mockImplementation(async (_connection, script) => ({
+    exitCode: script.includes("sudo -n umount /vectis-cache") ? 1 : 0,
+    stdout: "",
+    stderr: "",
+    truncated: false,
+  }));
+  const result = await runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    {
+      ...controls,
+      broker: {
+        ...broker,
+        prepareRunner: async () => ({
+          ...grant,
+          cacheWrite: true,
+          access: { ...grant.access, cacheRun: { runId: 5, runAttempt: 1 } },
+        }),
+      },
+      cache: { sizeGiB: 20, outcome: () => ({ promoted: false }), authorizeWrite },
+    },
+    new AbortController().signal,
+  );
+  expect(result).toMatchObject({
+    status: "failed",
+    code: "cache_unmount_failed",
+    progress: {
+      cache: {
+        attached: true,
+        writeBack: "granted",
+        promoted: false,
+        reason: "cache_unmount_failed",
+      },
+    },
+  });
+  expect(authorizeWrite).not.toHaveBeenCalled();
+  expect(controls.stop).toHaveBeenCalledOnce();
+});
+
+test.each(["linux", "macos", "windows"] as const)(
+  "%s baked scale set runners attach caches without claiming warm VMs or checking demand",
+  async (os) => {
+    const { controls, broker } = fixture(os);
+    const claimWarm = vi.fn(() => {
+      throw new Error("A generic warm VM has no cache disk");
+    });
+    const needed = vi.fn(async () => false);
+    const request = { automatic: true, scaleSet: { generation: 3 } };
+    const signal = new AbortController().signal;
+    const result = await runRunnerTask(
+      "binding",
+      "cache-cold",
+      {
+        ...environment,
+        os,
+        image: { revision: "revision", runnerVersion, provisionedAt: "2026-10-16T00:00:00Z" },
+      },
+      {
+        ...controls,
+        claimWarm,
+        needed,
+        request,
+        cache: { sizeGiB: 1, outcome: () => ({ promoted: false }), authorizeWrite: vi.fn() },
+      },
+      signal,
+    );
+    expect(result.status).toBe("succeeded");
+    expect(broker.prepareRunner).toHaveBeenCalledWith("binding", "cache-cold", signal, request);
+    expect(claimWarm).not.toHaveBeenCalled();
+    expect(needed).not.toHaveBeenCalled();
+    expect(controls.start).toHaveBeenCalledOnce();
+    expect(readyGuest).toHaveBeenCalledOnce();
+    expect(result.progress.phases?.map((phase) => phase.name)).toEqual([
+      "queued_locally",
+      "vm_start",
+      "guest_ready",
+      "runner_preinstalled",
+      "registration",
+      "waiting_for_job",
+      "cleanup",
+    ]);
+    const scripts = vi.mocked(executeGuest).mock.calls.map((call) => call[1]);
+    const listener = scripts.find((script) => script.includes("--jitconfig"));
+    expect(listener).toContain(preinstalledRunnerDirectory(os));
+    expect(listener).toContain("VECTISCACHE");
+    expect(scripts.join("\n")).not.toMatch(/Invoke-WebRequest|curl --fail/);
+    expect(controls.stop).toHaveBeenCalledOnce();
+  },
+);
+
+test("cache jobs boot with their attached disk instead of claiming a generic warm VM", async () => {
+  const { controls } = fixture();
+  const claimWarm = vi.fn(() => {
+    throw new Error("A generic warm VM has no cache disk");
+  });
+  const result = await runRunnerTask(
+    "binding",
+    "cache-cold",
+    environment,
+    {
+      ...controls,
+      claimWarm,
+      cache: { sizeGiB: 1, outcome: () => ({ promoted: false }), authorizeWrite: vi.fn() },
+    },
+    new AbortController().signal,
+  );
+  expect(result.status).toBe("succeeded");
+  expect(claimWarm).not.toHaveBeenCalled();
+  expect(controls.start).toHaveBeenCalledOnce();
+  expect(readyGuest).toHaveBeenCalledOnce();
+  expect(result.progress.phases?.map((phase) => phase.name)).toContain("vm_start");
+  expect(result.progress.phases?.map((phase) => phase.name)).not.toContain("warm_takeover");
+});
+
+test.each(["linux", "macos", "windows"] as const)(
+  "%s scale set registration forwards its generation without per-job checks",
+  async (os) => {
+    const { controls, broker } = fixture(os);
+    const needed = vi.fn(async () => false);
+    const request = { automatic: true, scaleSet: { generation: 3 } };
+    const signal = new AbortController().signal;
+    const result = await runRunnerTask(
+      "binding",
+      "key",
+      { ...environment, os },
+      { ...controls, needed, request },
+      signal,
+    );
+    expect(broker.prepareRunner).toHaveBeenCalledWith("binding", "key", signal, request);
+    expect(needed).not.toHaveBeenCalled();
+    expect(result.status).toBe("succeeded");
+  },
+);
+
+test("a scale set runner drains after five idle minutes even if a supplied demand check says needed", async () => {
+  const { needed, done } = await listeningFixture(true, {
+    request: { automatic: true, scaleSet: { generation: 3 } },
+  });
+  await vi.advanceTimersByTimeAsync(5 * 60 * 1000);
+  expect(await done).toMatchObject({ status: "cancelled", code: "runner_idle" });
+  expect(needed).not.toHaveBeenCalled();
+});
+
+test("cache promotion failures remain visible when VM cleanup requires reconciliation", async () => {
+  const { controls, broker } = fixture();
+  const grant = await broker.prepareRunner();
+  controls.stop.mockRejectedValue(new Error("Synthetic promotion failure"));
+  const result = await runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    {
+      ...controls,
+      broker: {
+        ...broker,
+        prepareRunner: async () => ({
+          ...grant,
+          cacheWrite: true,
+          access: { ...grant.access, cacheRun: { runId: 5, runAttempt: 1 } },
+        }),
+      },
+      cache: {
+        sizeGiB: 1,
+        authorizeWrite: vi.fn(),
+        outcome: () => ({ promoted: false, reason: "promotion_failed" }),
+      },
+    },
+    new AbortController().signal,
+  );
+  expect(result).toMatchObject({
+    status: "action_required",
+    code: "runner_cleanup_required",
+    progress: {
+      cache: { attached: true, writeBack: "granted", promoted: false, reason: "promotion_failed" },
+    },
+  });
+  expect(broker.releaseRunner).not.toHaveBeenCalled();
+});
+
+test("cache denial reasons from the cloud survive a successful runner lifecycle", async () => {
+  const { controls, broker } = fixture();
+  const grant = await broker.prepareRunner();
+  const authorizeWrite = vi.fn();
+  const result = await runRunnerTask(
+    "binding",
+    "key",
+    environment,
+    {
+      ...controls,
+      broker: {
+        ...broker,
+        prepareRunner: async () => ({ ...grant, cacheWriteReason: "metadata_access_denied" }),
+      },
+      cache: { sizeGiB: 1, authorizeWrite, outcome: () => ({ promoted: false }) },
+    },
+    new AbortController().signal,
+  );
+  expect(result).toMatchObject({
+    status: "succeeded",
+    progress: {
+      cache: {
+        attached: true,
+        writeBack: "denied",
+        promoted: false,
+        reason: "metadata_access_denied",
+      },
+    },
+  });
+  expect(authorizeWrite).not.toHaveBeenCalled();
+});
diff --git a/apps/server/src/runner-task.ts b/apps/server/src/runner-task.ts
index 24ac0def..525482b1 100644
--- a/apps/server/src/runner-task.ts
+++ b/apps/server/src/runner-task.ts
@@ -3,7 +3,18 @@ import {
   type Environment,
   type Instance,
 } from "../../../packages/protocol/src/index.js";
-import type { RunnerBroker, RunnerProgress } from "../../../packages/protocol/src/runners.js";
+import type {
+  PhaseName,
+  RunnerBroker,
+  RunnerPhase,
+  RunnerProgress,
+} from "../../../packages/protocol/src/runners.js";
+import {
+  cachePrivilegeError,
+  cachePrivilegeScript,
+  cacheUnmountScript,
+} from "../../../packages/runner/src/cache-guest.js";
+import type { CacheOutcome } from "../../../packages/runner/src/cache-volume.js";
 import { readyGuest } from "../../../packages/runner/src/guest-ready.js";
 import { executeGuest, GuestUnavailableError } from "../../../packages/runner/src/guest.js";
 import type { GuestConnection } from "../../../packages/runner/src/guest.js";
@@ -11,24 +22,36 @@ import { collectRunnerDiagnostics } from "../../../packages/runner/src/guest-dia
 import {
   runnerInstallScript,
   runnerStartScript,
+  runnerVersion,
 } from "../../../packages/runner/src/runner-release.js";
 
 import {
   assignmentRejectedMarker,
-  assignmentRejectedScript,
+  jobStartedMarker,
+  runnerGateScript,
 } from "../../../packages/runner/src/runner-access.js";
 
-const idleTimeoutMs = 10 * 60 * 1000;
+const idleTimeoutMs = 5 * 60 * 1000;
 const pollIntervalMs = 30000;
 
 interface Controls {
+  cache?: {
+    sizeGiB: number;
+    authorizeWrite(): void;
+    outcome(): CacheOutcome;
+    checked?(allowed: boolean): void;
+  };
   broker: RunnerBroker;
-  needed?: (signal: AbortSignal) => Promise<boolean>;
-  request?: { jobId?: number; automatic?: boolean };
+  needed?: ((signal: AbortSignal) => Promise<boolean>) | undefined;
+  request?: Parameters<RunnerBroker["prepareRunner"]>[3];
   now?: () => number;
+  acceptedAt?: string;
   pollIntervalMs?: number;
   idleTimeoutMs?: number;
-  start(): Promise<Instance>;
+  offlineTimeoutMs?: number;
+  statusFailureTimeoutMs?: number;
+  start(onStarting?: (instanceId: string) => void): Promise<Instance>;
+  claimWarm?(): { instance: Instance; connection: GuestConnection } | undefined;
   stop(): Promise<void>;
   progress(value: RunnerProgress): void;
 }
@@ -40,11 +63,30 @@ export async function runRunnerTask(
   controls: Controls,
   signal: AbortSignal,
 ) {
+  const now = controls.now ?? Date.now;
+  const taskStartedAt = new Date(now()).toISOString();
   let progress: RunnerProgress = {
     bindingId,
     environmentId: environment.id,
     leaseKey: key,
     stage: "starting",
+    ...(controls.cache
+      ? {
+          cache: {
+            attached: false,
+            writeBack: "denied" as const,
+            reason: "grant_pending",
+            promoted: false,
+          },
+        }
+      : {}),
+    phases: [
+      {
+        name: "queued_locally",
+        startedAt: controls.acceptedAt ?? taskStartedAt,
+        endedAt: taskStartedAt,
+      },
+    ],
   };
   let started = false;
   let registrationUncertain = false;
@@ -56,41 +98,125 @@ export async function runRunnerTask(
     progress = { ...progress, ...patch };
     controls.progress(progress);
   };
+  const beginPhase = (name: PhaseName, at = now()) => {
+    const phase: RunnerPhase = { name, startedAt: new Date(at).toISOString() };
+    const phases = [...(progress.phases ?? [])];
+    if (phases.length >= 16) {
+      // Repeated idle-demand checks must not evict the startup timeline.
+      const oldestCheck = phases.findIndex((item) => item.name === "job_check" && item.endedAt);
+      if (oldestCheck < 0) throw new Error("Runner phase history is full.");
+      phases.splice(oldestCheck, 1);
+    }
+    update({ phases: [...phases, phase] });
+    return phase;
+  };
+  const endPhase = (phase: RunnerPhase, at = now()) => {
+    const endedAt = new Date(at).toISOString();
+    update({
+      phases: progress.phases?.map((item) => (item === phase ? { ...item, endedAt } : item)),
+    });
+  };
+  const timed = async <T>(name: PhaseName, work: () => Promise<T>) => {
+    const phase = beginPhase(name);
+    try {
+      return await work();
+    } finally {
+      endPhase(phase);
+    }
+  };
+  const needed = controls.request?.scaleSet ? undefined : controls.needed;
+  const watchedControls = {
+    ...controls,
+    needed: needed ? (signal: AbortSignal) => timed("job_check", () => needed(signal)) : undefined,
+  };
   update({});
   try {
     signal.throwIfAborted();
-    if (controls.needed && !(await controls.needed(signal)))
+    if (watchedControls.needed && !(await watchedControls.needed(signal)))
       throw new VectisError(
         "job_not_queued",
         "The GitHub job no longer needs queued runner capacity.",
       );
     signal.throwIfAborted();
     started = true;
-    const instance = await controls.start();
+    const takeoverAt = now();
+    const warm = controls.cache ? undefined : controls.claimWarm?.();
+    if (warm) endPhase(beginPhase("warm_takeover", takeoverAt));
+    const start = () =>
+      timed(environment.x64 === "rosetta" ? "vm_start_and_guest_ready" : "vm_start", () =>
+        controls.start((instanceId) => update({ instanceId })),
+      );
+    let instance = warm?.instance ?? (await start());
     update({ instanceId: instance.id, stage: "preparing_guest" });
     signal.throwIfAborted();
-    connection = await readyGuest(environment, instance, signal);
     const shell = environment.os === "windows" ? "powershell" : "bash";
-    const installed = await executeGuest(connection, runnerInstallScript(environment.os), {
-      shell,
-      signal: AbortSignal.any([signal, AbortSignal.timeout(600000)]),
-    });
-    if (installed.exitCode !== 0)
-      throw new VectisError(
-        "runner_install_failed",
-        "The verified runner installation failed.",
-        "Inspect the base image prerequisites before starting a fresh runner.",
+    if (warm) {
+      try {
+        await timed("guest_ready", async () => {
+          const health = await executeGuest(warm.connection, "exit 0", {
+            shell,
+            signal: AbortSignal.any([signal, AbortSignal.timeout(10000)]),
+          });
+          if (health.exitCode !== 0)
+            throw new VectisError("guest_unavailable", "The warm VM failed its SSH health check.");
+          connection = warm.connection;
+        });
+      } catch {
+        signal.throwIfAborted();
+        await controls.stop();
+        instance = await start();
+        update({ instanceId: instance.id });
+      }
+    }
+    if (progress.cache) update({ cache: { ...progress.cache, attached: true } });
+    connection ??= await timed("guest_ready", () => readyGuest(environment, instance, signal));
+    const guest = connection;
+    if (controls.cache) {
+      const privilege = await executeGuest(guest, cachePrivilegeScript(environment.os), {
+        shell,
+        signal: AbortSignal.any([signal, AbortSignal.timeout(10000)]),
+      });
+      signal.throwIfAborted();
+      controls.cache.checked?.(privilege.exitCode === 0);
+      if (privilege.exitCode !== 0) throw cachePrivilegeError();
+    }
+    const preinstalled = environment.image?.runnerVersion === runnerVersion;
+    if (preinstalled) endPhase(beginPhase("runner_preinstalled"));
+    else {
+      const installed = await timed("runner_install", () =>
+        executeGuest(guest, runnerInstallScript(environment.os), {
+          shell,
+          signal: AbortSignal.any([signal, AbortSignal.timeout(600000)]),
+        }),
       );
-    if (controls.needed && !(await controls.needed(signal)))
+      if (installed.exitCode !== 0)
+        throw new VectisError(
+          "runner_install_failed",
+          "The verified runner installation failed.",
+          "Inspect the base image prerequisites before starting a fresh runner.",
+        );
+    }
+    if (watchedControls.needed && !(await watchedControls.needed(signal)))
       throw new VectisError(
         "job_not_queued",
         "The GitHub job no longer needs queued runner capacity.",
       );
     update({ stage: "registering" });
+    const registration = beginPhase("registration");
     registrationUncertain = true;
     const grant = await controls.broker
       .prepareRunner(bindingId, key, signal, controls.request)
       .catch((error: unknown) => {
+        if (
+          error instanceof VectisError &&
+          ["cloud_unavailable", "cloud_unconfigured"].includes(error.code)
+        ) {
+          registrationUncertain = false;
+          throw new VectisError(
+            "runner_registration_failed",
+            "Runner registration could not start because the cloud connection is unavailable.",
+          );
+        }
         if (
           error instanceof VectisError &&
           [
@@ -115,6 +241,14 @@ export async function runRunnerTask(
         "runner_registration_incomplete",
         "Runner registration needs reconciliation.",
       );
+    if (progress.cache)
+      update({
+        cache: {
+          ...progress.cache,
+          writeBack: grant.cacheWrite ? "granted" : "denied",
+          reason: grant.cacheWrite ? undefined : (grant.cacheWriteReason ?? "policy_denied"),
+        },
+      });
     if (grant.environmentId !== environment.id || grant.os !== environment.os)
       throw new VectisError(
         "runner_identity_mismatch",
@@ -125,15 +259,67 @@ export async function runRunnerTask(
         "runner_policy_missing",
         "The runner grant has no repository assignment policy.",
       );
+    if (controls.cache && grant.cacheWrite && !grant.access.cacheRun)
+      throw new VectisError(
+        "runner_policy_missing",
+        "A writable cache grant must identify its workflow run attempt.",
+      );
+    const registeredAt = now();
+    endPhase(registration, registeredAt);
     update({ runnerId: grant.runnerId, stage: "listening" });
+    const waiting = beginPhase("waiting_for_job", registeredAt);
+    let job: RunnerPhase | undefined;
+    let listenerExitedAt: number | undefined;
+    let guestStartObserved = false;
+    const jobStarted = (reportedAt?: number) => {
+      if (
+        guestStartObserved ||
+        (reportedAt === undefined && (job || listenerExitedAt !== undefined))
+      )
+        return;
+      guestStartObserved = reportedAt !== undefined;
+      const at = Math.max(registeredAt, Math.min(reportedAt ?? now(), listenerExitedAt ?? now()));
+      const startedAt = new Date(at).toISOString();
+      update({
+        phases: progress.phases?.map((phase) =>
+          phase.name === "waiting_for_job" ? { ...phase, endedAt: startedAt } : phase,
+        ),
+      });
+      if (job) {
+        job = {
+          ...job,
+          startedAt,
+          ...(listenerExitedAt !== undefined
+            ? { endedAt: new Date(listenerExitedAt).toISOString() }
+            : {}),
+        };
+        const corrected = job;
+        update({
+          phases: progress.phases?.map((phase) => (phase.name === "job" ? corrected : phase)),
+        });
+      } else {
+        job = beginPhase("job", at);
+        if (listenerExitedAt !== undefined) endPhase(job, listenerExitedAt);
+      }
+    };
     const listening = new AbortController();
     const listeningSignal = AbortSignal.any([signal, listening.signal]);
-    const watcher = watchIdleRunner(grant.id, controls, listening, listeningSignal);
+    const watcher = watchIdleRunner(grant.id, watchedControls, listening, listeningSignal, () => {
+      jobStarted();
+    });
     const execution = await executeRunnerListener(
       connection,
       environment.os,
-      runnerStartScript(environment.os, grant.encodedConfig, grant.access),
+      runnerStartScript(environment.os, grant.encodedConfig, grant.access, {
+        ...(controls.cache ? { cacheSizeGiB: controls.cache.sizeGiB } : {}),
+        preinstalled,
+      }),
       listeningSignal,
+      jobStarted,
+      () => {
+        listenerExitedAt = now();
+        endPhase(job ?? waiting, listenerExitedAt);
+      },
     )
       .catch((error: unknown) => {
         if (!signal.aborted && listening.signal.reason instanceof VectisError)
@@ -145,6 +331,8 @@ export async function runRunnerTask(
         listening.abort();
         await watcher;
       });
+    if (!signal.aborted && listening.signal.reason instanceof VectisError)
+      throw listening.signal.reason;
     if (execution.exitCode !== 0) {
       listener = `exit ${execution.exitCode}\n${execution.stdout}\n${execution.stderr}`;
       throw new VectisError(
@@ -153,7 +341,21 @@ export async function runRunnerTask(
         "Inspect the GitHub Actions run and the base image prerequisites.",
       );
     }
+    if (controls.cache) {
+      const unmounted = await executeGuest(connection, cacheUnmountScript(environment.os), {
+        shell,
+        signal: AbortSignal.any([signal, AbortSignal.timeout(60000)]),
+      });
+      if (unmounted.exitCode !== 0)
+        throw new VectisError(
+          "cache_unmount_failed",
+          "The cache could not be cleanly unmounted; its changes were discarded.",
+        );
+      signal.throwIfAborted();
+      if (grant.cacheWrite) controls.cache.authorizeWrite();
+    }
   } catch (error) {
+    for (const phase of progress.phases ?? []) if (!phase.endedAt) endPhase(phase);
     failure = error;
   }
   if (
@@ -168,19 +370,33 @@ export async function runRunnerTask(
         os: environment.os,
         listener,
         secrets: [secret],
+        preinstalled: environment.image?.runnerVersion === runnerVersion,
       }).catch(() => undefined),
     });
-  {
+  const cleanupResult = await timed("cleanup", async () => {
     update({
       stage: "cleaning",
       ...(failure instanceof VectisError && failure.code === "runner_assignment_rejected"
         ? { cause: { code: failure.code, message: failure.message } }
         : {}),
     });
+    const updateCacheOutcome = () => {
+      if (!controls.cache || !progress.cache) return;
+      const outcome = controls.cache.outcome();
+      let reason = outcome.reason ?? progress.cache.reason;
+      if (!outcome.promoted && (!reason || reason === "grant_pending"))
+        reason = signal.aborted
+          ? "cancelled"
+          : failure instanceof VectisError
+            ? failure.code.slice(0, 256)
+            : "lifecycle_incomplete";
+      update({ cache: { ...progress.cache, promoted: outcome.promoted, reason } });
+    };
     if (started) {
       try {
         await controls.stop();
       } catch {
+        updateCacheOutcome();
         return {
           status: "action_required" as const,
           progress,
@@ -188,9 +404,13 @@ export async function runRunnerTask(
             ? "Vectis refused the assigned job. VM cleanup is unconfirmed and GitHub runner cleanup is waiting."
             : "VM cleanup is unconfirmed. The runner registration was retained.",
           code: "runner_cleanup_required",
+          ...(failure instanceof VectisError && failure.code === "runner_offline"
+            ? { recoveryCause: { code: failure.code, message: failure.message } }
+            : {}),
         };
       }
     }
+    updateCacheOutcome();
     if (progress.leaseId) {
       try {
         await controls.broker.releaseRunner(progress.leaseId, AbortSignal.timeout(60000));
@@ -202,29 +422,51 @@ export async function runRunnerTask(
             ? "Vectis refused the assigned job. The VM is stopped and cleanup is waiting for GitHub to release the runner."
             : "The VM is stopped, but GitHub runner cleanup is waiting for reconciliation.",
           code: "runner_cleanup_required",
+          ...(failure instanceof VectisError && failure.code === "runner_offline"
+            ? { recoveryCause: { code: failure.code, message: failure.message } }
+            : {}),
         };
       }
     }
-  }
-  if (registrationUncertain) {
-    if (
-      failure instanceof VectisError &&
-      ["public_runner_approval_required", "private_runner_approval_required"].includes(failure.code)
-    )
-      return {
-        status: "action_required" as const,
-        progress,
-        message: failure.message,
-        code: failure.code,
-        nextStep: `${failure.nextStep} Then run vectis runner reconcile with this operation ID to close the stopped runner attempt.`,
-      };
-    return {
-      status: "action_required" as const,
-      progress,
-      message: "The VM is stopped. Reconcile the registration request before retrying.",
-      code: "runner_registration_uncertain",
-    };
-  }
+    if (registrationUncertain) {
+      if (
+        failure instanceof VectisError &&
+        ["public_runner_approval_required", "private_runner_approval_required"].includes(
+          failure.code,
+        )
+      )
+        return {
+          status: "action_required" as const,
+          progress,
+          message: failure.message,
+          code: failure.code,
+          nextStep: `${failure.nextStep} Then run vectis runner reconcile with this operation ID to close the stopped runner attempt.`,
+        };
+      try {
+        const lease = await controls.broker.reconcileRunner(
+          { bindingId, environmentId: environment.id, key },
+          AbortSignal.timeout(10000),
+        );
+        if (lease.bindingId !== bindingId || lease.environmentId !== environment.id)
+          throw new Error("Runner lease identity mismatch.");
+        update({ leaseId: lease.id });
+        if (lease.phase !== "released")
+          await controls.broker.releaseRunner(lease.id, AbortSignal.timeout(60000));
+        failure = new VectisError(
+          "runner_registration_failed",
+          "Runner registration failed; cleanup is confirmed and the request can be retried.",
+        );
+      } catch {
+        return {
+          status: "action_required" as const,
+          progress,
+          message: "The VM is stopped. Reconcile the registration request before retrying.",
+          code: "runner_registration_uncertain",
+        };
+      }
+    }
+  });
+  if (cleanupResult) return { ...cleanupResult, progress };
   update({ stage: "finished" });
   if (failure instanceof VectisError && failure.code === "runner_idle")
     return { status: "cancelled" as const, progress, message: failure.message, code: failure.code };
@@ -232,7 +474,10 @@ export async function runRunnerTask(
     return { status: "cancelled" as const, progress, message: failure.message };
   if (
     signal.aborted &&
-    !(failure instanceof VectisError && failure.code === "runner_assignment_rejected")
+    !(
+      failure instanceof VectisError &&
+      ["runner_assignment_rejected", "runner_offline"].includes(failure.code)
+    )
   )
     return { status: "cancelled" as const, progress, message: "Runner cancelled and cleaned up." };
   if (
@@ -254,6 +499,7 @@ export async function runRunnerTask(
       progress,
       message: failure instanceof VectisError ? failure.message : "Runner execution failed.",
       code: failure instanceof VectisError ? failure.code : "runner_failed",
+      ...(failure instanceof VectisError ? { nextStep: failure.nextStep } : {}),
     };
   return {
     status: "succeeded" as const,
@@ -273,11 +519,22 @@ function assignmentRejection(output: string) {
   );
 }
 
+function guestJobStartedAt(output: string) {
+  const lines = output.split(/\r?\n/);
+  const marker = lines.indexOf(jobStartedMarker);
+  const value = marker === -1 ? undefined : lines[marker + 1]?.trim();
+  if (!value || !/^\d+$/.test(value)) return undefined;
+  const timestamp = Number(value);
+  return Number.isSafeInteger(timestamp) ? timestamp : undefined;
+}
+
 async function executeRunnerListener(
   connection: GuestConnection,
   os: Environment["os"],
   script: string,
   signal: AbortSignal,
+  onJobStarted: (at: number) => void,
+  onExit: () => void,
 ) {
   const listening = new AbortController();
   const monitoring = new AbortController();
@@ -286,12 +543,16 @@ async function executeRunnerListener(
   let checking: Promise<void> | undefined;
   const check = async (checkSignal: AbortSignal) => {
     try {
-      const result = await executeGuest(connection, assignmentRejectedScript(os), {
+      const result = await executeGuest(connection, runnerGateScript(os), {
         shell,
         signal: AbortSignal.any([checkSignal, AbortSignal.timeout(10000)]),
       });
       rejection ??= assignmentRejection(result.stdout);
       if (rejection) listening.abort();
+      else if (result.exitCode === 0) {
+        const startedAt = guestJobStartedAt(result.stdout);
+        if (startedAt !== undefined) onJobStarted(startedAt);
+      }
     } catch {
       // A transient guest connection failure is not evidence of policy rejection.
     }
@@ -311,6 +572,7 @@ async function executeRunnerListener(
       (error: unknown) => ({ error }),
     )
     .finally(async () => {
+      onExit();
       clearInterval(timer);
       monitoring.abort();
       await checking;
@@ -330,11 +592,36 @@ async function watchIdleRunner(
   controls: Controls,
   listening: AbortController,
   signal: AbortSignal,
+  onBusy: () => void,
 ) {
-  if (!controls.needed) return;
   const now = controls.now ?? Date.now;
   const timeoutMs = controls.idleTimeoutMs ?? idleTimeoutMs;
+  const offlineTimeout = controls.offlineTimeoutMs ?? 2 * 60 * 1000;
+  const failureTimeout = controls.statusFailureTimeoutMs ?? 15 * 60 * 1000;
   let idleSince = now();
+  let offlineSince: number | undefined;
+  let failureSince: number | undefined;
+  const offline = () =>
+    listening.abort(
+      new VectisError(
+        "runner_offline",
+        "The runner is offline or its GitHub status has been unavailable too long; the VM is being released.",
+      ),
+    );
+  const readStatus = async () => {
+    try {
+      const status = await controls.broker.runnerStatus(leaseId, signal);
+      failureSince = undefined;
+      return status;
+    } catch {
+      if (!signal.aborted) {
+        failureSince ??= now();
+        offlineSince = undefined;
+        if (now() - failureSince >= failureTimeout) offline();
+      }
+      return undefined;
+    }
+  };
   while (!signal.aborted) {
     await new Promise<void>((resolve) => {
       const done = () => {
@@ -347,30 +634,46 @@ async function watchIdleRunner(
       if (signal.aborted) done();
     });
     if (signal.aborted) return;
+    const status = await readStatus();
+    if (signal.aborted) return;
+    if (!status) continue;
+    if ("busy" in status && status.busy) {
+      onBusy();
+      idleSince = now();
+      offlineSince = undefined;
+      continue;
+    }
+    if ("missing" in status || status.status === "offline") {
+      offlineSince ??= now();
+      if (now() - offlineSince >= offlineTimeout) offline();
+      continue;
+    }
+    offlineSince = undefined;
+    if (now() - idleSince < timeoutMs) continue;
     try {
-      const status = await controls.broker.runnerStatus(leaseId, signal);
-      if (signal.aborted) return;
-      if ("busy" in status && status.busy) {
-        idleSince = now();
-        continue;
-      }
-      if (now() - idleSince < timeoutMs || (await controls.needed(signal))) continue;
-      if (signal.aborted) return;
-      // Refreshing the job may take long enough for GitHub to assign this runner work.
-      const confirmed = await controls.broker.runnerStatus(leaseId, signal);
-      if (signal.aborted) return;
-      if ("busy" in confirmed && confirmed.busy) {
-        idleSince = now();
-        continue;
-      }
-      listening.abort(
-        new VectisError(
-          "runner_idle",
-          "The runner was idle for 10 minutes and its job no longer needs capacity; the VM was released.",
-        ),
-      );
+      if (controls.needed && (await controls.needed(signal))) continue;
     } catch {
+      continue;
+    }
+    if (signal.aborted) return;
+    // Refreshing the job may take long enough for GitHub to assign this runner work.
+    const confirmed = await readStatus();
+    if (signal.aborted) return;
+    if (!confirmed) continue;
+    if ("busy" in confirmed && confirmed.busy) {
+      onBusy();
       idleSince = now();
+      continue;
+    }
+    if ("missing" in confirmed || confirmed.status === "offline") {
+      offlineSince ??= now();
+      continue;
     }
+    listening.abort(
+      new VectisError(
+        "runner_idle",
+        "The runner was idle for 5 minutes and no longer needs capacity; the VM is being released.",
+      ),
+    );
   }
 }
diff --git a/apps/server/src/scale-set-listener.test.ts b/apps/server/src/scale-set-listener.test.ts
new file mode 100644
index 00000000..20eed48c
--- /dev/null
+++ b/apps/server/src/scale-set-listener.test.ts
@@ -0,0 +1,500 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test, vi } from "vitest";
+import { runnerCapacity } from "./runner-capacity.js";
+import type { RunnerCapacity, Snapshot } from "../../../packages/protocol/src/index.js";
+import { ScaleSetListener } from "./scale-set-listener.js";
+import { Store } from "./store.js";
+import { ScaleSetHttpError, type Message } from "../../../packages/scaleset/src/index.js";
+import type { ScaleSetGrant } from "../../../packages/protocol/src/scale-sets.js";
+import { VectisError, type Command } from "../../../packages/protocol/src/index.js";
+import type { MachineRepositories } from "../../../packages/protocol/src/repositories.js";
+
+const grant: ScaleSetGrant = {
+  bindingId: "binding",
+  generation: 1,
+  scaleSetId: 42,
+  scaleSetName: "vectis-linux",
+  sessionId: "00000000-0000-4000-8000-000000000001",
+  messageQueueUrl: "https://queue.example.test/messages",
+  messageQueueAccessToken: "private-queue-token",
+};
+const cleanup: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const close of cleanup.reverse()) await close();
+  cleanup.length = 0;
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+function waitForAbort(signal: AbortSignal) {
+  return new Promise<null>((_resolve, reject) => {
+    signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+    if (signal.aborted) reject(signal.reason);
+  });
+}
+const message = (id: number, assigned: number): Message => ({
+  messageId: id,
+  statistics: { totalAssignedJobs: assigned },
+  jobs: [{ messageType: "JobAssigned" }],
+});
+async function fixture(
+  capacity = 4,
+  realTransport = false,
+  capacityFor?: (snapshot: Snapshot) => RunnerCapacity,
+) {
+  const home = await mkdtemp(join(tmpdir(), "vectis-scale-set-"));
+  cleanup.push(() => rm(home, { recursive: true, force: true }));
+  const store = new Store(join(home, "state.sqlite"));
+  cleanup.push(async () => store.close());
+  let bindings: MachineRepositories = [
+    {
+      id: "binding",
+      repositoryId: 1,
+      repositoryName: "test/repo",
+      environmentId: "linux",
+      automatic: true,
+      capacityMode: "scale_set",
+    },
+  ];
+  let connected = true;
+  const broker = {
+    openScaleSet: vi.fn(async () => grant),
+    refreshScaleSet: vi.fn(async () => ({ ...grant, messageQueueAccessToken: "renewed-token" })),
+    closeScaleSet: vi.fn(async () => {}),
+  };
+  const client = {
+    getMessage: vi.fn<
+      (last: number, capacity: number, signal: AbortSignal) => Promise<Message | null>
+    >(async (_last, _capacity, signal) => waitForAbort(signal)),
+    acknowledgeMessage: vi.fn(async (_id: number, _signal: AbortSignal) => {}),
+    acquireJobs: vi.fn(async (ids: readonly number[], _signal: AbortSignal, _url?: string) => ids),
+  };
+  const submit = vi.fn(
+    (key: string, command: Command) =>
+      store.accept(key, JSON.stringify(command), command.type).operation,
+  );
+  const create = () => {
+    const listener = new ScaleSetListener({
+      store,
+      broker: () => broker,
+      repositories: () => bindings,
+      connected: () => connected,
+      snapshot: () => {
+        const snapshot = store.snapshot();
+        const active = snapshot.operations.filter(
+          (op) => ["accepted", "running"].includes(op.status) && op.command === "runner.run",
+        ).length;
+        return {
+          ...snapshot,
+          runnerCapacity: capacityFor?.(snapshot) ?? {
+            max: capacity,
+            active,
+            available: capacity - active,
+            environments: [{ environmentId: "linux", available: Math.max(0, capacity - active) }],
+          },
+        };
+      },
+      submit,
+      ...(realTransport
+        ? {}
+        : {
+            sessionClient: (value: ScaleSetGrant) => {
+              grants.push(value);
+              return client;
+            },
+          }),
+      random: () => 0,
+    });
+    cleanup.push(() => listener.close());
+    return listener;
+  };
+  const grants: ScaleSetGrant[] = [];
+  const listener = create();
+  return {
+    store,
+    broker,
+    client,
+    listener,
+    submit,
+    grants,
+    create,
+    setBindings: (value: MachineRepositories) => {
+      bindings = value;
+      store.touch();
+    },
+    disconnect: () => {
+      connected = false;
+      store.touch();
+    },
+    pause: () => {
+      store.put("machine", "self", { ...store.snapshot().machine, paused: true });
+    },
+  };
+}
+
+test("opens one session, accepts exactly the missing capacity and acknowledges after durable acceptance", async () => {
+  const f = await fixture(3);
+  f.client.getMessage
+    .mockResolvedValueOnce(message(1, 5))
+    .mockResolvedValueOnce(message(1, 5))
+    .mockResolvedValueOnce(message(2, 5));
+  f.client.acknowledgeMessage.mockImplementation(async () => {
+    expect(f.store.snapshot().operations).toHaveLength(3);
+    expect(
+      f.store.snapshot().operations.every((operation) => operation.status === "accepted"),
+    ).toBe(true);
+  });
+  f.listener.start();
+  await vi.waitFor(() => expect(f.client.acknowledgeMessage).toHaveBeenCalledTimes(3));
+  expect(f.broker.openScaleSet).toHaveBeenCalledOnce();
+  expect(f.submit).toHaveBeenCalledTimes(3);
+  expect(f.submit.mock.calls.map((call) => call[0])).toEqual(
+    expect.arrayContaining([
+      expect.stringMatching(/:1:1$/),
+      expect.stringMatching(/:1:2$/),
+      expect.stringMatching(/:1:3$/),
+    ]),
+  );
+  expect(
+    f.submit.mock.calls.every(
+      (call) =>
+        JSON.stringify(call[1]) ===
+        JSON.stringify({
+          type: "runner.run",
+          bindingId: "binding",
+          automatic: true,
+          scaleSet: { generation: 1 },
+        }),
+    ),
+  ).toBe(true);
+  expect(f.listener.states()).toMatchObject([
+    { state: "listening", assignedJobs: 5, reservedRunners: 3 },
+  ]);
+  expect(JSON.stringify(f.listener.states())).not.toContain("private-queue-token");
+  expect(f.client.getMessage.mock.calls[1]?.slice(0, 2)).toEqual([1, 3]);
+});
+
+test("an acknowledged level can fill slots that become free on an empty poll", async () => {
+  const f = await fixture(2);
+  const other = f.store.accept("other", "other", "runner.run").operation;
+  f.client.getMessage.mockResolvedValueOnce(message(1, 2)).mockImplementationOnce(async () => {
+    f.store.update(other, { status: "succeeded" });
+    return null;
+  });
+  f.listener.start();
+  await vi.waitFor(() => expect(f.submit).toHaveBeenCalledTimes(2));
+  expect(f.listener.states()).toMatchObject([{ reservedRunners: 2 }]);
+});
+
+test("replays a persisted partial plan with the original keys without duplicating accepted operations", async () => {
+  const f = await fixture(3);
+  const submit = f.submit.getMockImplementation();
+  if (!submit) throw new Error("Missing fixture submit.");
+  let accepted = 0;
+  f.submit.mockImplementation((key, command) => {
+    if (++accepted === 2) throw new Error("simulated interruption");
+    return submit(key, command);
+  });
+  f.client.getMessage.mockResolvedValueOnce(message(1, 3));
+  f.listener.start();
+  await vi.waitFor(() => expect(f.listener.states()[0]?.state).toBe("action_required"));
+  expect(f.client.acknowledgeMessage).not.toHaveBeenCalled();
+  expect(f.store.snapshot().operations).toHaveLength(1);
+  await f.listener.close();
+  f.submit.mockImplementation(submit);
+  const restarted = f.create();
+  f.client.getMessage.mockResolvedValueOnce(message(1, 3));
+  restarted.start();
+  await vi.waitFor(() => expect(f.client.acknowledgeMessage).toHaveBeenCalledOnce());
+  expect(f.store.snapshot().operations).toHaveLength(3);
+  expect(new Set(f.store.snapshot().operations.map((operation) => operation.key)).size).toBe(3);
+});
+
+test("401 refreshes the queue grant once and replays the poll with the same cursor", async () => {
+  const f = await fixture();
+  f.client.getMessage
+    .mockRejectedValueOnce(new ScaleSetHttpError(401, null, true))
+    .mockResolvedValueOnce(message(1, 1));
+  f.listener.start();
+  await vi.waitFor(() => expect(f.client.acknowledgeMessage).toHaveBeenCalledOnce());
+  expect(f.broker.refreshScaleSet).toHaveBeenCalledExactlyOnceWith(
+    "binding",
+    1,
+    expect.any(AbortSignal),
+  );
+  expect(f.grants.map((grant) => grant.messageQueueAccessToken)).toEqual([
+    "private-queue-token",
+    "renewed-token",
+  ]);
+  expect(f.client.getMessage.mock.calls.slice(0, 2).map((call) => call[0])).toEqual([0, 0]);
+});
+
+test("a second 401 on the same request stops with an honest auth error", async () => {
+  const f = await fixture();
+  f.client.getMessage.mockRejectedValue(new ScaleSetHttpError(401, null, true));
+  f.listener.start();
+  await vi.waitFor(() =>
+    expect(f.listener.states()).toMatchObject([
+      { state: "action_required", code: "scale_set_auth_failed" },
+    ]),
+  );
+  expect(f.broker.refreshScaleSet).toHaveBeenCalledOnce();
+  expect(f.broker.closeScaleSet).toHaveBeenCalledOnce();
+});
+
+test("JobAvailable retries acquisition with the same positive IDs, while JobAssigned needs none", async () => {
+  const f = await fixture();
+  f.client.getMessage.mockResolvedValueOnce({
+    ...message(1, 1),
+    jobs: [
+      {
+        messageType: "JobAvailable",
+        runnerRequestId: 7,
+        acquireJobUrl: "https://actions.test/_apis/runtime/runnerscalesets/42/acquirejobs",
+      },
+      { messageType: "JobAssigned" },
+    ],
+  });
+  f.client.acquireJobs.mockRejectedValueOnce(new ScaleSetHttpError(401, null, true));
+  f.listener.start();
+  await vi.waitFor(() => expect(f.client.acknowledgeMessage).toHaveBeenCalledOnce());
+  expect(f.client.acquireJobs.mock.calls.map((call) => call[0])).toEqual([[7], [7]]);
+  expect(f.broker.refreshScaleSet).toHaveBeenCalledOnce();
+  expect(f.submit).toHaveBeenCalledOnce();
+});
+
+test("409 exposes session conflict without opening another session or accepting work", async () => {
+  const f = await fixture();
+  f.broker.openScaleSet.mockRejectedValue(new ScaleSetHttpError(409, null, false));
+  f.listener.start();
+  await vi.waitFor(() =>
+    expect(f.listener.states()).toMatchObject([
+      { state: "action_required", code: "scale_set_session_conflict" },
+    ]),
+  );
+  f.store.touch();
+  await Promise.resolve();
+  expect(f.broker.openScaleSet).toHaveBeenCalledOnce();
+  expect(f.submit).not.toHaveBeenCalled();
+});
+
+test.each(["pause", "disable", "mode", "disconnect", "shutdown"] as const)(
+  "%s aborts the outstanding poll and closes the owned session",
+  async (action) => {
+    const f = await fixture();
+    f.listener.start();
+    await vi.waitFor(() => expect(f.client.getMessage).toHaveBeenCalledOnce());
+    const signal = f.client.getMessage.mock.calls[0]?.[2];
+    if (action === "pause") f.pause();
+    else if (action === "disconnect") f.disconnect();
+    else if (action === "shutdown") await f.listener.close();
+    else
+      f.setBindings([
+        {
+          id: "binding",
+          repositoryId: 1,
+          repositoryName: "test/repo",
+          environmentId: "linux",
+          automatic: action !== "disable",
+          capacityMode: action === "mode" ? "demand" : "scale_set",
+        },
+      ]);
+    await vi.waitFor(() =>
+      expect(f.broker.closeScaleSet).toHaveBeenCalledExactlyOnceWith(
+        "binding",
+        1,
+        expect.any(AbortSignal),
+      ),
+    );
+    expect(signal?.aborted).toBe(true);
+    expect(f.broker.openScaleSet).toHaveBeenCalledOnce();
+  },
+);
+
+test("restrictive policy fails closed before session opening and retries only after a binding change", async () => {
+  const f = await fixture();
+  const binding = {
+    id: "binding",
+    repositoryId: 1,
+    repositoryName: "test/repo",
+    environmentId: "linux",
+    automatic: true,
+    capacityMode: "scale_set" as const,
+  };
+  f.setBindings([{ ...binding, access: { actors: "any", approval: "required" } }]);
+  f.listener.start();
+  await vi.waitFor(() =>
+    expect(f.listener.states()).toMatchObject([
+      { state: "action_required", code: "scale_set_policy_unsupported" },
+    ]),
+  );
+  expect(f.broker.openScaleSet).not.toHaveBeenCalled();
+  f.setBindings([binding]);
+  await vi.waitFor(() => expect(f.client.getMessage).toHaveBeenCalledOnce());
+});
+
+test("Retry-After and backoff are abortable and do not create overlapping polls", async () => {
+  vi.useFakeTimers();
+  const f = await fixture();
+  f.client.getMessage.mockRejectedValueOnce(new ScaleSetHttpError(429, "5", true));
+  f.listener.start();
+  await vi.advanceTimersByTimeAsync(0);
+  expect(f.client.getMessage).toHaveBeenCalledOnce();
+  await vi.advanceTimersByTimeAsync(4999);
+  expect(f.client.getMessage).toHaveBeenCalledOnce();
+  await vi.advanceTimersByTimeAsync(1);
+  expect(f.client.getMessage).toHaveBeenCalledTimes(2);
+  await f.listener.close();
+  expect(f.broker.closeScaleSet).toHaveBeenCalledOnce();
+});
+
+test("cloud authorization errors retain their code without exposing credentials", async () => {
+  const f = await fixture();
+  f.broker.openScaleSet.mockRejectedValue(new VectisError("machine_revoked", "revoked"));
+  f.listener.start();
+  await vi.waitFor(() =>
+    expect(f.listener.states()).toMatchObject([
+      { state: "action_required", code: "machine_revoked" },
+    ]),
+  );
+});
+
+test.each([false, true])(
+  "the real queue transport decodes zero-ID assignment and uses only the queue token (acquire=%s)",
+  async (acquire) => {
+    const f = await fixture(2, true);
+    let polls = 0;
+    const requests: Array<{ url: URL; input: RequestInit }> = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: URL, input: RequestInit) => {
+        requests.push({ url, input });
+        if (input.method === "GET") {
+          if (++polls > 1) {
+            const signal = input.signal;
+            if (!signal) throw new Error("Missing poll signal.");
+            await waitForAbort(signal);
+            throw new Error("Poll aborted.");
+          }
+          return Response.json({
+            messageId: 1,
+            messageType: "RunnerScaleSetJobMessages",
+            statistics: { totalAssignedJobs: 2 },
+            body: JSON.stringify([
+              { messageType: "JobAssigned", runnerRequestId: 0 },
+              ...(acquire
+                ? [
+                    {
+                      messageType: "JobAvailable",
+                      runnerRequestId: 7,
+                      acquireJobUrl:
+                        "https://queue.example.test/_apis/runtime/runnerScaleSets/42/acquirejobs",
+                    },
+                  ]
+                : []),
+            ]),
+          });
+        }
+        if (input.method === "POST") return Response.json({ count: 1, value: [7] });
+        expect(input.method).toBe("DELETE");
+        expect(f.store.snapshot().operations).toHaveLength(2);
+        return new Response(null, { status: 204 });
+      }),
+    );
+    f.listener.start();
+    await vi.waitFor(() =>
+      expect(requests.filter((request) => request.input.method === "DELETE")).toHaveLength(1),
+    );
+    expect(f.submit).toHaveBeenCalledTimes(2);
+    expect(
+      requests.every(
+        (request) =>
+          new Headers(request.input.headers).get("Authorization") === "Bearer private-queue-token",
+      ),
+    ).toBe(true);
+    const acquired = requests.filter((request) => request.input.method === "POST");
+    expect(acquired).toHaveLength(acquire ? 1 : 0);
+    if (acquire) {
+      expect(acquired[0]?.url.pathname).toBe("/_apis/runtime/runnerscalesets/42/acquirejobs");
+      expect(acquired[0]?.input.body).toBe("[7]");
+    }
+  },
+);
+
+test("snapshot reservation counts stay current while a long poll is outstanding", async () => {
+  const f = await fixture();
+  f.client.getMessage.mockResolvedValueOnce(message(1, 2));
+  f.listener.start();
+  await vi.waitFor(() => expect(f.client.acknowledgeMessage).toHaveBeenCalledOnce());
+  const operation = f.store.snapshot().operations[0];
+  if (!operation) throw new Error("Missing accepted runner.");
+  f.store.update(operation, { status: "succeeded" });
+  const revision = f.store.snapshot().revision;
+  expect(f.listener.states()).toMatchObject([{ reservedRunners: 1 }]);
+  expect(f.store.snapshot().revision).toBe(revision);
+});
+
+test.each([
+  { pressure: "normal", warm: false, slots: 2 },
+  { pressure: "warning", warm: false, slots: 0 },
+  { pressure: "critical", warm: true, slots: 0 },
+  { pressure: "normal", warm: true, slots: 2 },
+] as const)(
+  "scale set reservations respect shared memory and pressure: %j",
+  async ({ pressure, warm, slots }) => {
+    const f = await fixture(5, false, (snapshot) =>
+      runnerCapacity(
+        snapshot,
+        { cpus: 8, memoryBytes: 16 * 1024 ** 3 },
+        {
+          probe: () => ({
+            footprintsMiB: new Map([["warm", 2048]]),
+            pressure,
+            pressureKnown: true,
+          }),
+        },
+      ),
+    );
+    f.store.put("machine", "self", {
+      ...f.store.snapshot().machine,
+      maxRunners: 5,
+      memoryBudgetMiB: 4096,
+    });
+    f.store.put("environment", "linux", {
+      id: "linux",
+      name: "Linux",
+      os: "linux",
+      state: "ready",
+      basePath: "/unused/base",
+      cpu: 1,
+      memoryMiB: 4096,
+    });
+    f.store.put("environment", "small", {
+      id: "small",
+      name: "Small",
+      os: "linux",
+      state: "ready",
+      basePath: "/unused/small",
+      cpu: 1,
+      memoryMiB: 512,
+    });
+    if (warm)
+      f.store.put("instance", "warm", {
+        id: "warm",
+        environmentId: "linux",
+        status: "running",
+        role: "warm",
+        memoryMiB: 4096,
+        pid: 0,
+        createdAt: new Date().toISOString(),
+      });
+    f.client.getMessage.mockResolvedValueOnce(message(1, 5));
+    f.listener.start();
+    await vi.waitFor(() => expect(f.client.acknowledgeMessage).toHaveBeenCalledOnce());
+    expect(f.submit).toHaveBeenCalledTimes(slots);
+    expect(f.client.getMessage.mock.calls[0]?.[1]).toBe(slots);
+    expect(f.client.getMessage.mock.calls[1]?.[1]).toBe(slots);
+    expect(f.listener.states()).toMatchObject([{ assignedJobs: 5, reservedRunners: slots }]);
+  },
+);
diff --git a/apps/server/src/scale-set-listener.ts b/apps/server/src/scale-set-listener.ts
new file mode 100644
index 00000000..b83eaede
--- /dev/null
+++ b/apps/server/src/scale-set-listener.ts
@@ -0,0 +1,498 @@
+import { createHash } from "node:crypto";
+import { Schema } from "effect";
+import {
+  VectisError,
+  type Command,
+  type Operation,
+  type Snapshot,
+} from "../../../packages/protocol/src/index.js";
+import type { MachineRepositories } from "../../../packages/protocol/src/repositories.js";
+import type {
+  ScaleSetBroker,
+  ScaleSetGrant,
+  ScaleSetState,
+} from "../../../packages/protocol/src/scale-sets.js";
+import {
+  ScaleSetSessionClient,
+  ScaleSetHttpError,
+  ScaleSetProtocolError,
+  type Message,
+} from "../../../packages/scaleset/src/index.js";
+import { restrictiveAccess } from "../../../packages/github/src/access-policy.js";
+import type { Store } from "./store.js";
+
+interface SessionClient {
+  getMessage(
+    lastMessageId: number,
+    maxCapacity: number,
+    signal: AbortSignal,
+  ): Promise<Message | null>;
+  acknowledgeMessage(messageId: number, signal: AbortSignal): Promise<unknown>;
+  acquireJobs(
+    ids: readonly number[],
+    signal: AbortSignal,
+    acquireJobUrl?: string,
+  ): Promise<readonly number[]>;
+}
+
+const Pending = Schema.Struct({
+  messageId: Schema.Int,
+  assignedJobs: Schema.Int,
+  keys: Schema.Array(Schema.String),
+});
+const Cursor = Schema.Struct({
+  generation: Schema.Int,
+  sequence: Schema.Int,
+  lastMessageId: Schema.Int,
+  assignedJobs: Schema.Int,
+  pending: Schema.optional(Pending),
+});
+type Cursor = typeof Cursor.Type;
+const Reservation = Schema.Struct({ bindingId: Schema.String, key: Schema.String });
+
+function sessionClient(grant: ScaleSetGrant): SessionClient {
+  const session = {
+    sessionId: grant.sessionId,
+    messageQueueUrl: grant.messageQueueUrl,
+    messageQueueAccessToken: grant.messageQueueAccessToken,
+    statistics: { totalAssignedJobs: grant.statistics?.totalAssignedJobs ?? 0 },
+  };
+  const client = new ScaleSetSessionClient(
+    new URL(grant.messageQueueUrl).origin,
+    grant.scaleSetId,
+    session,
+    fetch,
+  );
+  return {
+    getMessage: (last, capacity, signal) => client.getMessage(last, capacity, signal),
+    acknowledgeMessage: (id, signal) => client.acknowledgeMessage(id, signal),
+    acquireJobs: (ids, signal, acquireJobUrl) => {
+      let url: URL | undefined;
+      try {
+        url = acquireJobUrl === undefined ? undefined : new URL(acquireJobUrl);
+      } catch {
+        throw new VectisError(
+          "scale_set_acquire_url_missing",
+          "GitHub did not supply a valid scale set acquisition endpoint.",
+        );
+      }
+      const suffix = `/_apis/runtime/runnerscalesets/${grant.scaleSetId}/acquirejobs`;
+      if (
+        !url ||
+        url.protocol !== "https:" ||
+        url.username ||
+        url.password ||
+        url.hash ||
+        !url.pathname.toLowerCase().endsWith(suffix)
+      )
+        throw new VectisError(
+          "scale_set_acquire_url_missing",
+          "GitHub did not supply a supported scale set acquisition endpoint.",
+        );
+      url.pathname = url.pathname.slice(0, -suffix.length);
+      url.search = "";
+      return new ScaleSetSessionClient(url.href, grant.scaleSetId, session, fetch).acquireJobs(
+        ids,
+        signal,
+      );
+    },
+  };
+}
+
+function wait(ms: number, signal: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    const aborted = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", aborted);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", aborted);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", aborted, { once: true });
+    if (signal.aborted) aborted();
+  });
+}
+
+function retryAfter(error: unknown) {
+  if (!(error instanceof ScaleSetHttpError) || error.retryAfter === null) return 0;
+  const seconds = Number(error.retryAfter);
+  return (
+    Math.max(
+      0,
+      Number.isFinite(seconds) ? seconds * 1000 : Date.parse(error.retryAfter) - Date.now(),
+    ) || 0
+  );
+}
+
+function actionCode(error: unknown) {
+  if (error instanceof ScaleSetProtocolError) return "scale_set_protocol_invalid";
+  if (error instanceof ScaleSetHttpError) {
+    if (error.status === 409) return "scale_set_session_conflict";
+    if (error.status === 401 || error.status === 403) return "scale_set_auth_failed";
+    if (error.status >= 400 && error.status < 500 && ![408, 429].includes(error.status))
+      return "scale_set_request_refused";
+  }
+  if (
+    error instanceof VectisError &&
+    ![
+      "cloud_unavailable",
+      "cloud_unconfigured",
+      "github_unavailable",
+      "github_rate_limited",
+      "scale_set_unavailable",
+      "scale_set_pending",
+      "scale_set_cleanup_pending",
+    ].includes(error.code)
+  )
+    return error.code;
+}
+
+type ListenerTask = {
+  finished: boolean;
+  bindingRevision: string;
+  abort: AbortController;
+  done: Promise<void>;
+  state: ScaleSetState;
+};
+
+export class ScaleSetListener {
+  private readonly tasks = new Map<string, ListenerTask>();
+  private readonly stopped = new Map<string, ScaleSetState>();
+  private unsubscribe?: () => void;
+  private scheduled = false;
+  private closing = false;
+  private suspended = false;
+  constructor(
+    private readonly options: {
+      store: Store;
+      snapshot(): Snapshot;
+      repositories(): MachineRepositories | undefined;
+      connected(): boolean;
+      broker(): ScaleSetBroker;
+      submit(key: string, command: Command): Operation;
+      sessionClient?: (grant: ScaleSetGrant) => SessionClient;
+      random?: () => number;
+    },
+  ) {}
+
+  start() {
+    if (this.unsubscribe || this.closing) return;
+    this.unsubscribe = this.options.store.onChange(() => this.schedule());
+    this.reconcile();
+  }
+  states(): ScaleSetState[] {
+    return [
+      ...this.stopped.values(),
+      ...[...this.tasks.values()].map((task) => ({
+        ...task.state,
+        state: task.abort.signal.aborted ? ("stopped" as const) : task.state.state,
+      })),
+    ].map((state) => ({ ...state, reservedRunners: this.reservations(state.bindingId, false) }));
+  }
+  private schedule() {
+    if (this.scheduled || this.closing) return;
+    this.scheduled = true;
+    queueMicrotask(() => {
+      this.scheduled = false;
+      if (!this.closing) this.reconcile();
+    });
+  }
+  private reconcile() {
+    const bindings = this.options.repositories() ?? [];
+    const snapshot = this.options.snapshot();
+    const enabled = new Set(
+      bindings
+        .filter(
+          (binding) =>
+            binding.capacityMode === "scale_set" &&
+            binding.automatic &&
+            !this.suspended &&
+            !snapshot.machine.paused &&
+            this.options.connected(),
+        )
+        .map((binding) => binding.id),
+    );
+    for (const [id, task] of this.tasks) {
+      const binding = bindings.find((binding) => binding.id === id);
+      if (!enabled.has(id) || task.bindingRevision !== JSON.stringify(binding)) task.abort.abort();
+      if (task.abort.signal.aborted && task.finished) this.tasks.delete(id);
+    }
+    for (const id of this.stopped.keys())
+      if (!bindings.some((binding) => binding.id === id)) this.stopped.delete(id);
+    for (const binding of bindings) {
+      if (!enabled.has(binding.id)) {
+        if (binding.capacityMode === "scale_set" && !this.tasks.has(binding.id))
+          this.stopped.set(binding.id, { bindingId: binding.id, state: "stopped" });
+        continue;
+      }
+      if (this.tasks.has(binding.id)) continue;
+      this.stopped.delete(binding.id);
+      const task: ListenerTask = {
+        finished: false,
+        bindingRevision: JSON.stringify(binding),
+        abort: new AbortController(),
+        done: Promise.resolve(),
+        state: { bindingId: binding.id, state: "connecting" },
+      };
+      this.tasks.set(binding.id, task);
+      task.done = this.listen(binding.id, task).finally(() => {
+        task.finished = true;
+        if (task.abort.signal.aborted) {
+          this.stopped.set(binding.id, { bindingId: binding.id, state: "stopped" });
+          this.tasks.delete(binding.id);
+          this.schedule();
+        }
+        this.options.store.touch();
+      });
+    }
+  }
+  private state(task: ListenerTask, patch: Partial<ScaleSetState>) {
+    task.state = { ...task.state, ...patch };
+    this.options.store.touch();
+  }
+  private reservations(bindingId: string, prune = true) {
+    let active = 0;
+    for (const value of this.options.store.list("scale-set-reservation")) {
+      const reservation = Schema.decodeUnknownSync(Reservation)(value);
+      try {
+        const operation = this.options.store.operationByKey(reservation.key);
+        if (operation.status === "accepted" || operation.status === "running") {
+          if (reservation.bindingId === bindingId) active++;
+        } else if (prune) this.options.store.remove("scale-set-reservation", reservation.key);
+      } catch (error) {
+        if (!(error instanceof VectisError) || error.code !== "operation_missing") throw error;
+        if (!prune) continue;
+        const cursor = this.options.store.get("scale-set-cursor", reservation.bindingId);
+        if (
+          cursor === undefined ||
+          !Schema.decodeUnknownSync(Cursor)(cursor).pending?.keys.includes(reservation.key)
+        )
+          this.options.store.remove("scale-set-reservation", reservation.key);
+      }
+    }
+    return active;
+  }
+  private slots(bindingId: string) {
+    const binding = this.options.repositories()?.find((binding) => binding.id === bindingId);
+    return (
+      this.options
+        .snapshot()
+        .runnerCapacity?.environments?.find(
+          (environment) => environment.environmentId === binding?.environmentId,
+        )?.available ?? 0
+    );
+  }
+  private async listen(bindingId: string, task: ListenerTask) {
+    const signal = task.abort.signal;
+    let grant: ScaleSetGrant | undefined;
+    let failures = 0;
+    let broker: ScaleSetBroker | undefined;
+    try {
+      const binding = this.options.repositories()?.find((binding) => binding.id === bindingId);
+      if (restrictiveAccess(binding?.access))
+        throw new VectisError(
+          "scale_set_policy_unsupported",
+          "Scale set preview requires any actor and automatic approval. Use demand mode for restrictive policies.",
+        );
+      const sessionBroker = this.options.broker();
+      broker = sessionBroker;
+      for (;;) {
+        signal.throwIfAborted();
+        try {
+          grant = await sessionBroker.openScaleSet(bindingId, signal);
+          if (grant.bindingId !== bindingId)
+            throw new VectisError(
+              "scale_set_binding_mismatch",
+              "The scale set grant belongs to another binding.",
+            );
+          break;
+        } catch (error) {
+          if (signal.aborted || actionCode(error)) throw error;
+          await this.backoff(error, failures++, signal);
+        }
+      }
+      let current = grant;
+      const saved = this.options.store.get("scale-set-cursor", bindingId);
+      let cursor: Cursor =
+        saved === undefined
+          ? {
+              generation: current.generation,
+              sequence: 0,
+              lastMessageId: 0,
+              assignedJobs: current.statistics?.totalAssignedJobs ?? 0,
+            }
+          : Schema.decodeUnknownSync(Cursor)(saved);
+      if (cursor.generation !== current.generation)
+        cursor = {
+          generation: current.generation,
+          sequence: 0,
+          lastMessageId: 0,
+          assignedJobs: current.statistics?.totalAssignedJobs ?? 0,
+        };
+      const save = () => this.options.store.put("scale-set-cursor", bindingId, cursor);
+      save();
+      let client = (this.options.sessionClient ?? sessionClient)(current);
+      const request = async <T>(work: (client: SessionClient) => Promise<T>): Promise<T> => {
+        let refreshed = false;
+        for (;;) {
+          signal.throwIfAborted();
+          try {
+            const value = await work(client);
+            failures = 0;
+            return value;
+          } catch (error) {
+            if (signal.aborted) throw error;
+            if (error instanceof ScaleSetHttpError && error.queueTokenExpired && !refreshed) {
+              refreshed = true;
+              for (;;) {
+                try {
+                  current = await sessionBroker.refreshScaleSet(
+                    bindingId,
+                    current.generation,
+                    signal,
+                  );
+                  break;
+                } catch (refreshError) {
+                  if (signal.aborted || actionCode(refreshError)) throw refreshError;
+                  await this.backoff(refreshError, failures++, signal);
+                }
+              }
+              if (current.bindingId !== bindingId || current.generation !== grant?.generation)
+                throw new VectisError(
+                  "scale_set_superseded",
+                  "The scale set session was superseded.",
+                );
+              client = (this.options.sessionClient ?? sessionClient)(current);
+              continue;
+            }
+            if (actionCode(error)) throw error;
+            await this.backoff(error, failures++, signal);
+          }
+        }
+      };
+      const accept = () => {
+        const pending = cursor.pending;
+        if (!pending) return;
+        for (const key of pending.keys) {
+          signal.throwIfAborted();
+          this.options.store.put("scale-set-reservation", key, { bindingId, key });
+          this.options.submit(key, {
+            type: "runner.run",
+            bindingId,
+            automatic: true,
+            scaleSet: { generation: current.generation },
+          });
+        }
+        cursor = {
+          ...cursor,
+          lastMessageId: pending.messageId,
+          assignedJobs: pending.assignedJobs,
+          pending: undefined,
+        };
+        save();
+      };
+      const reserve = (messageId: number, assignedJobs: number) => {
+        const reserved = this.reservations(bindingId);
+        // runnerCapacity reports free slots; include this binding's reservations in its ceiling.
+        const envSlots = this.slots(bindingId) + reserved;
+        const additional = Math.max(0, Math.min(assignedJobs, envSlots) - reserved);
+        const keys = Array.from(
+          { length: additional },
+          (_, index) =>
+            `scale-set:${createHash("sha256").update(bindingId).digest("hex").slice(0, 32)}:${current.generation}:${cursor.sequence + index + 1}`,
+        );
+        cursor = {
+          ...cursor,
+          sequence: cursor.sequence + additional,
+          pending: { messageId, assignedJobs, keys },
+        };
+        save();
+        accept();
+      };
+      // A persisted plan is replayed with exactly the same request keys after a crash.
+      accept();
+      reserve(cursor.lastMessageId, cursor.assignedJobs);
+      this.state(task, {
+        state: "listening",
+        scaleSetName: current.scaleSetName,
+        assignedJobs: cursor.assignedJobs,
+        reservedRunners: this.reservations(bindingId),
+      });
+      while (!signal.aborted) {
+        const active = this.reservations(bindingId);
+        const message = await request((client) =>
+          client.getMessage(cursor.lastMessageId, this.slots(bindingId) + active, signal),
+        );
+        signal.throwIfAborted();
+        if (!message) {
+          reserve(cursor.lastMessageId, cursor.assignedJobs);
+          this.state(task, { reservedRunners: this.reservations(bindingId) });
+          await wait(250, signal);
+          continue;
+        }
+        if (message.messageId > cursor.lastMessageId) {
+          const available = message.jobs.filter(
+            (job) => job.messageType === "JobAvailable" && job.runnerRequestId !== undefined,
+          );
+          for (const job of available) {
+            if (job.messageType === "JobAvailable" && job.runnerRequestId !== undefined) {
+              const requestId = job.runnerRequestId;
+              await request((client) => client.acquireJobs([requestId], signal, job.acquireJobUrl));
+            }
+          }
+          reserve(message.messageId, message.statistics.totalAssignedJobs);
+        }
+        await request((client) => client.acknowledgeMessage(message.messageId, signal));
+        this.state(task, {
+          assignedJobs: cursor.assignedJobs,
+          reservedRunners: this.reservations(bindingId),
+          lastMessageAt: new Date().toISOString(),
+        });
+      }
+    } catch (error) {
+      if (!signal.aborted)
+        this.state(task, {
+          state: "action_required",
+          code: actionCode(error) ?? "scale_set_listener_failed",
+          message:
+            "Scale set listening stopped. Check the binding, policy and cloud authorization before retrying.",
+        });
+    } finally {
+      if (grant && broker) {
+        const closing = new AbortController();
+        const timer = setTimeout(() => closing.abort(), 10000);
+        try {
+          await Promise.race([
+            broker.closeScaleSet(bindingId, grant.generation, closing.signal).catch(() => {}),
+            wait(10000, closing.signal).catch(() => {}),
+          ]);
+        } finally {
+          clearTimeout(timer);
+          closing.abort();
+        }
+      }
+    }
+  }
+  private async backoff(error: unknown, failures: number, signal: AbortSignal) {
+    const exponential = Math.min(30000, 500 * 2 ** Math.min(failures, 6));
+    const jitter = exponential * (0.5 + (this.options.random ?? Math.random)());
+    await wait(Math.min(2147483647, Math.max(retryAfter(error), jitter)), signal);
+  }
+  async suspend() {
+    this.suspended = true;
+    for (const task of this.tasks.values()) task.abort.abort();
+    await Promise.all([...this.tasks.values()].map((task) => task.done));
+  }
+  resume() {
+    this.suspended = false;
+    this.schedule();
+  }
+  async close() {
+    this.closing = true;
+    this.unsubscribe?.();
+    for (const task of this.tasks.values()) task.abort.abort();
+    await Promise.all([...this.tasks.values()].map((task) => task.done));
+  }
+}
diff --git a/apps/server/src/scale-set-service.test.ts b/apps/server/src/scale-set-service.test.ts
new file mode 100644
index 00000000..712b4bae
--- /dev/null
+++ b/apps/server/src/scale-set-service.test.ts
@@ -0,0 +1,139 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test, vi } from "vitest";
+import { Service } from "./service.js";
+import { Store } from "./store.js";
+import { VmRuntime } from "../../../packages/runner/src/runtime.js";
+import type { MachineRepositories } from "../../../packages/protocol/src/repositories.js";
+import type { ScaleSetGrant } from "../../../packages/protocol/src/scale-sets.js";
+import { runRunnerTask } from "./runner-task.js";
+vi.mock("./runner-task.js", () => ({ runRunnerTask: vi.fn() }));
+
+test("the service owns the listener lifecycle, exposes its state and submits scale set runners without demand checks", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-scale-set-service-"));
+  const store = new Store(join(home, "state.sqlite"));
+  let bindings: MachineRepositories = [
+    {
+      id: "binding",
+      repositoryId: 1,
+      repositoryName: "owner/repo",
+      environmentId: "linux",
+      automatic: true,
+      capacityMode: "demand",
+    },
+  ];
+  const unused = async () => {
+    throw new Error("Unexpected broker call.");
+  };
+  const grant: ScaleSetGrant = {
+    bindingId: "binding",
+    generation: 3,
+    scaleSetId: 42,
+    scaleSetName: "vectis-linux",
+    sessionId: "00000000-0000-4000-8000-000000000001",
+    messageQueueUrl: "https://queue.test/messages",
+    messageQueueAccessToken: "queue-canary",
+  };
+  const broker = {
+    repositories: async () => bindings,
+    prepareRunner: vi.fn(unused),
+    reconcileRunner: unused,
+    releaseRunner: unused,
+    runnerStatus: unused,
+    connectRepository: unused,
+    disconnectRepository: unused,
+    setAutomatic: unused,
+    setAccess: unused,
+    controlRun: unused,
+    analyzeMigration: unused,
+    publishMigration: unused,
+    scanJobs: unused,
+    refreshJob: vi.fn(unused),
+    jobLogs: unused,
+    setCapacityMode: vi.fn(async (_bindingId: string, mode: "demand" | "scale_set") => {
+      bindings = bindings.map((binding) => ({ ...binding, capacityMode: mode }));
+      store.touch();
+    }),
+    openScaleSet: vi.fn(async () => grant),
+    refreshScaleSet: unused,
+    closeScaleSet: vi.fn(async () => {}),
+  };
+  const fetch = vi.fn(
+    async (_url: URL, input: RequestInit) =>
+      new Promise<Response>((_resolve, reject) => {
+        input.signal?.addEventListener("abort", () => reject(input.signal?.reason), { once: true });
+      }),
+  );
+  vi.stubGlobal("fetch", fetch);
+  const service = new Service(
+    store,
+    new VmRuntime({ home }),
+    () => broker,
+    undefined,
+    () => bindings,
+    undefined,
+    { connected: () => true },
+  );
+  const environment = {
+    id: "linux",
+    name: "Linux",
+    os: "linux" as const,
+    state: "ready" as const,
+    cpu: 1,
+    memoryMiB: 512,
+    basePath: join(home, "synthetic.img"),
+  };
+  store.put("environment", environment.id, environment);
+  vi.mocked(runRunnerTask).mockImplementation(async (_bindingId, _key, _environment) => ({
+    status: "succeeded",
+    message: "Synthetic lifecycle completed.",
+    progress: { bindingId: "binding", environmentId: "linux", leaseKey: "key", stage: "finished" },
+  }));
+  try {
+    await service.initialize();
+    expect(broker.openScaleSet).not.toHaveBeenCalled();
+    service.submit("mode", {
+      type: "repository.capacity-mode",
+      bindingId: "binding",
+      mode: "scale_set",
+    });
+    await service.drain();
+    await vi.waitFor(() => expect(fetch).toHaveBeenCalledOnce());
+    expect(service.snapshot().scaleSets).toMatchObject([
+      { bindingId: "binding", state: "listening", scaleSetName: "vectis-linux" },
+    ]);
+    expect(JSON.stringify(service.snapshot())).not.toContain("queue-canary");
+    service.submit("scale-runner", {
+      type: "runner.run",
+      bindingId: "binding",
+      automatic: true,
+      scaleSet: { generation: 3 },
+    });
+    await service.drain();
+    await vi.waitFor(() => expect(runRunnerTask).toHaveBeenCalledOnce());
+    const controls = vi.mocked(runRunnerTask).mock.calls[0]?.[3];
+    expect(controls?.request).toEqual({ automatic: true, scaleSet: { generation: 3 } });
+    expect(controls?.needed).toBeUndefined();
+    expect(broker.refreshJob).not.toHaveBeenCalled();
+    service.submit("pause", { type: "machine.pause", paused: true });
+    await service.drain();
+    await vi.waitFor(() =>
+      expect(broker.closeScaleSet).toHaveBeenCalledExactlyOnceWith(
+        "binding",
+        3,
+        expect.any(AbortSignal),
+      ),
+    );
+    expect(fetch.mock.calls[0]?.[1].signal?.aborted).toBe(true);
+    expect(service.snapshot().scaleSets).toMatchObject([
+      { bindingId: "binding", state: "stopped" },
+    ]);
+  } finally {
+    await service.close();
+    store.close();
+    vi.unstubAllGlobals();
+    vi.resetAllMocks();
+    await rm(home, { recursive: true, force: true });
+  }
+});
diff --git a/apps/server/src/service-cache.test.ts b/apps/server/src/service-cache.test.ts
new file mode 100644
index 00000000..68475ac8
--- /dev/null
+++ b/apps/server/src/service-cache.test.ts
@@ -0,0 +1,420 @@
+import { mkdtemp, mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test, vi } from "vitest";
+import { Service } from "./service.js";
+import { Store } from "./store.js";
+import { VmRuntime } from "../../../packages/runner/src/runtime.js";
+import { CacheVolumes } from "../../../packages/runner/src/cache-volume.js";
+import type { MachineRepositories } from "../../../packages/protocol/src/repositories.js";
+import { executeGuest } from "../../../packages/runner/src/guest.js";
+import { readyGuest } from "../../../packages/runner/src/guest-ready.js";
+
+vi.mock("../../../packages/runner/src/guest-ready.js", () => ({ readyGuest: vi.fn() }));
+vi.mock("../../../packages/runner/src/guest.js", async (original) => ({
+  ...(await original<typeof import("../../../packages/runner/src/guest.js")>()),
+  executeGuest: vi.fn(),
+}));
+vi.mock("../../../packages/runner/src/memory.js", async (original) => ({
+  ...(await original<typeof import("../../../packages/runner/src/memory.js")>()),
+  availableHostMemory: async () => 8 * 1024 ** 3,
+}));
+const cleanups: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const cleanup of cleanups.reverse()) await cleanup();
+  cleanups.length = 0;
+  vi.resetAllMocks();
+});
+async function fixture() {
+  const home = await mkdtemp(join(tmpdir(), "vectis-service-cache-"));
+  const store = new Store(join(home, "state.sqlite"));
+  const helper = join(home, "helper");
+  await writeFile(
+    helper,
+    `#!${process.execPath}\nprocess.stdout.write('{"event":"vm.running"}\\n'); setInterval(() => {}, 1000);`,
+    { mode: 0o700 },
+  );
+  const basePath = join(home, "base.img");
+  await writeFile(basePath, "boot");
+  const environment = {
+    id: "linux",
+    name: "Linux",
+    os: "linux",
+    state: "ready",
+    basePath,
+    cpu: 1,
+    memoryMiB: 512,
+  } as const;
+  store.put("environment", environment.id, environment);
+  const binding = {
+    id: "binding",
+    installationId: 1,
+    repositoryId: 2,
+    repositoryName: "owner/repo",
+    environmentId: "linux",
+    cacheVolume: { enabled: true, sizeGiB: 1 },
+  };
+  let repositories: MachineRepositories = [binding];
+  let cloudSnapshot: MachineRepositories | undefined;
+  const unused = async () => {
+    throw new Error("Unexpected broker call");
+  };
+  const broker = {
+    repositories: vi.fn(async () => repositories),
+    disconnectRepository: vi.fn(async () => {
+      repositories = [];
+    }),
+    setCacheVolume: vi.fn(async (_id: string, settings: { enabled: boolean; sizeGiB?: number }) => {
+      binding.cacheVolume = {
+        enabled: settings.enabled,
+        sizeGiB: settings.sizeGiB ?? binding.cacheVolume.sizeGiB,
+      };
+    }),
+    setAccess: unused,
+    setAutomatic: unused,
+    analyzeMigration: unused,
+    publishMigration: unused,
+    connectRepository: unused,
+    jobLogs: unused,
+    scanJobs: unused,
+    refreshJob: unused,
+    controlRun: unused,
+    reconcileRunner: unused,
+    prepareRunner: vi.fn(
+      async () =>
+        ({
+          state: "ready",
+          id: "lease",
+          runnerId: 3,
+          encodedConfig: "c2VjcmV0",
+          environmentId: "linux",
+          os: "linux",
+          cacheWrite: true,
+          access: {
+            repositoryId: 2,
+            actors: "any",
+            approval: "automatic",
+            cacheRun: { runId: 5, runAttempt: 1 },
+          },
+        }) as const,
+    ),
+    releaseRunner: vi.fn(async () => {}),
+    runnerStatus: unused,
+  };
+  const runtime = new VmRuntime({ home, appleHelper: helper });
+  const service = new Service(
+    store,
+    runtime,
+    () => broker,
+    undefined,
+    () => cloudSnapshot,
+  );
+  cleanups.push(async () => {
+    await service.close();
+    store.close();
+    await rm(home, { recursive: true, force: true });
+  });
+  const cacheDirectory = new CacheVolumes(home).directory(environment, binding);
+  vi.mocked(readyGuest).mockResolvedValue({
+    host: "192.168.64.2",
+    port: 22,
+    user: "vectis",
+    identityFile: "/fake/key",
+    knownHostsFile: "/fake/hosts",
+    hostKeyAlias: "test",
+  });
+  vi.mocked(executeGuest).mockResolvedValue({
+    exitCode: 0,
+    stdout: "",
+    stderr: "",
+    truncated: false,
+  });
+  return {
+    home,
+    service,
+    store,
+    broker,
+    binding,
+    runtime,
+    cacheDirectory,
+    setSnapshot: (value: MachineRepositories | undefined) => {
+      cloudSnapshot = value;
+    },
+  };
+}
+
+test("cache settings use the cloud binding and clear deletes generations", async () => {
+  const { service, broker, cacheDirectory } = await fixture();
+  const enabled = service.submit("enable", {
+    type: "repository.cache",
+    bindingId: "binding",
+    enabled: true,
+    sizeGiB: 2,
+  });
+  await service.drain();
+  expect(broker.setCacheVolume).toHaveBeenCalledWith("binding", { enabled: true, sizeGiB: 2 });
+  expect(service.snapshot().operations.find((item) => item.id === enabled.id)?.status).toBe(
+    "succeeded",
+  );
+  await mkdir(cacheDirectory, { recursive: true });
+  await writeFile(join(cacheDirectory, "cache.img"), "cache");
+  await writeFile(join(cacheDirectory, "cache.previous.img"), "previous");
+  const cleared = service.submit("clear", { type: "cache.clear", bindingId: "binding" });
+  await service.drain();
+  expect(service.snapshot().operations.find((item) => item.id === cleared.id)?.status).toBe(
+    "succeeded",
+  );
+  await expect(stat(cacheDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+test("disconnect removes cache disks and retries work after the cloud binding disappears", async () => {
+  const { service, broker, cacheDirectory } = await fixture();
+  await mkdir(cacheDirectory, { recursive: true });
+  await writeFile(join(cacheDirectory, "cache.img"), "cache");
+  service.submit("disconnect", { type: "repository.disconnect", bindingId: "binding" });
+  await service.drain();
+  expect(broker.disconnectRepository).toHaveBeenCalledWith("binding");
+  await expect(stat(cacheDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+  service.submit("disconnect-retry", { type: "repository.disconnect", bindingId: "binding" });
+  await service.drain();
+  expect(service.snapshot().operations[0]?.status).toBe("succeeded");
+});
+
+test("an authoritative cloud disconnect cleans retained volumes; unknown cloud state preserves them", async () => {
+  const { service, cacheDirectory, setSnapshot } = await fixture();
+  service.submit("remember", { type: "repository.cache", bindingId: "binding", enabled: false });
+  await service.drain();
+  await mkdir(cacheDirectory, { recursive: true });
+  await writeFile(join(cacheDirectory, "cache.img"), "cache");
+  service.repositoriesChanged();
+  await service.drain();
+  expect(await readFile(join(cacheDirectory, "cache.img"), "utf8")).toBe("cache");
+  setSnapshot([]);
+  service.repositoriesChanged();
+  await service.drain();
+  await expect(stat(cacheDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+test("clear refuses an interrupted cache instance until reconciliation", async () => {
+  const { service, store } = await fixture();
+  store.put("cacheUse", "interrupted", { bindingId: "binding", instanceId: "interrupted" });
+  store.put("instance", "interrupted", {
+    id: "interrupted",
+    environmentId: "linux",
+    status: "interrupted",
+    pid: 0,
+    createdAt: new Date().toISOString(),
+  });
+  const clear = service.submit("clear-interrupted", { type: "cache.clear", bindingId: "binding" });
+  await service.drain();
+  expect(service.snapshot().operations.find((item) => item.id === clear.id)).toMatchObject({
+    status: "failed",
+    result: { code: "cache_in_use" },
+  });
+});
+
+test.skipIf(process.platform !== "darwin" || process.arch !== "arm64")(
+  "a running cache fork blocks clear and promotes only after listener, unmount and VM exit",
+  async () => {
+    const { service, store, cacheDirectory } = await fixture();
+    let release = () => {};
+    const pending = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    let listening = false;
+    vi.mocked(executeGuest).mockImplementation(async (_connection, script) => {
+      if (script.includes("--jitconfig")) {
+        const instance = store.snapshot().instances.find((item) => item.status === "running");
+        if (!instance?.directory) throw new Error("Missing private instance directory");
+        const file = await open(join(instance.directory, "cache.img"), "r+");
+        try {
+          await file.write("job-cache", 0, "utf8");
+        } finally {
+          await file.close();
+        }
+        listening = true;
+        await pending;
+      }
+      return { exitCode: 0, stdout: "", stderr: "", truncated: false };
+    });
+    try {
+      const run = service.submit("run", { type: "runner.run", bindingId: "binding" });
+      await service.drain();
+      await vi.waitFor(() => expect(listening).toBe(true));
+      const clear = service.submit("clear-running", { type: "cache.clear", bindingId: "binding" });
+      await service.drain();
+      expect(service.snapshot().operations.find((item) => item.id === clear.id)).toMatchObject({
+        status: "failed",
+        result: { code: "cache_in_use" },
+      });
+      release();
+      await vi.waitFor(() =>
+        expect(service.snapshot().operations.find((item) => item.id === run.id)?.status).toBe(
+          "succeeded",
+        ),
+      );
+      expect(store.operation(run.id).result).toMatchObject({
+        cache: { attached: true, writeBack: "granted", promoted: true },
+      });
+      const instance = store.snapshot().instances.find((item) => item.status === "stopped");
+      if (!instance?.directory) throw new Error("Missing stopped instance directory");
+      await expect(stat(instance.directory)).rejects.toMatchObject({ code: "ENOENT" });
+      const file = await open(join(cacheDirectory, "cache.img"), "r");
+      const data = Buffer.alloc(9);
+      try {
+        await file.read(data, 0, 9, 0);
+      } finally {
+        await file.close();
+      }
+      expect(data.toString()).toBe("job-cache");
+      let reused = "";
+      vi.mocked(executeGuest).mockImplementation(async (_connection, script) => {
+        if (script.includes("--jitconfig")) {
+          const current = store.snapshot().instances.find((item) => item.status === "running");
+          if (!current?.directory) throw new Error("Missing second instance directory");
+          const fork = await open(join(current.directory, "cache.img"), "r");
+          try {
+            const data = Buffer.alloc(9);
+            await fork.read(data, 0, data.length, 0);
+            reused = data.toString();
+          } finally {
+            await fork.close();
+          }
+        }
+        return { exitCode: 0, stdout: "", stderr: "", truncated: false };
+      });
+      const second = service.submit("run-again", { type: "runner.run", bindingId: "binding" });
+      await vi.waitFor(() => expect(store.operation(second.id).status).toBe("succeeded"));
+      expect(reused).toBe("job-cache");
+      expect(store.operation(second.id).result).toMatchObject({
+        cache: { attached: true, writeBack: "granted", promoted: true },
+      });
+      expect(store.list("cacheUse")).toEqual([]);
+    } finally {
+      release();
+    }
+  },
+);
+
+test("cache acquisition leaves commands responsive and cancellation releases the acquired handle", async () => {
+  const f = await fixture();
+  type Volume = Awaited<ReturnType<CacheVolumes["acquire"]>>;
+  let completeAcquisition = (_volume: Volume) => {};
+  const pending = new Promise<Volume>((resolve) => {
+    completeAcquisition = resolve;
+  });
+  const handle = {
+    directory: f.cacheDirectory,
+    authorizeWrite: vi.fn(),
+    outcome: () => ({ promoted: false }),
+    release: vi.fn(),
+    disk: { sourcePath: join(f.cacheDirectory, "cache.img"), stopped: vi.fn(async () => {}) },
+  };
+  const acquire = vi.spyOn(CacheVolumes.prototype, "acquire").mockReturnValueOnce(pending);
+  try {
+    const run = f.service.submit("pending-cache", { type: "runner.run", bindingId: "binding" });
+    await f.service.drain();
+    expect(acquire).toHaveBeenCalledOnce();
+    const pause = f.service.submit("pause-pending-cache", { type: "machine.pause", paused: true });
+    f.service.submit("cancel-pending-cache", { type: "operation.cancel", id: run.id });
+    await f.service.drain();
+    expect(f.store.operation(pause.id).status).toBe("succeeded");
+    completeAcquisition(handle);
+    await vi.waitFor(() => expect(f.store.operation(run.id).status).toBe("cancelled"));
+    expect(handle.release).toHaveBeenCalledOnce();
+    expect(f.broker.prepareRunner).not.toHaveBeenCalled();
+    expect(f.store.snapshot().instances).toEqual([]);
+  } finally {
+    completeAcquisition(handle);
+    acquire.mockRestore();
+  }
+});
+
+test.skipIf(process.platform !== "darwin" || process.arch !== "arm64")(
+  "missing guest sudo preserves the cache generation and prevents another VM start",
+  async () => {
+    const { service, store, broker, cacheDirectory, runtime } = await fixture();
+    const environment = store.snapshot().environments[0];
+    if (!environment) throw new Error("Missing synthetic environment");
+    const acquired = await new CacheVolumes(runtime.options.home).acquire(
+      environment,
+      { installationId: 1, repositoryId: 2 },
+      1,
+    );
+    acquired.release();
+    const generation = await open(join(cacheDirectory, "cache.img"), "r+");
+    try {
+      await generation.write("saved-cache");
+    } finally {
+      await generation.close();
+    }
+    vi.mocked(executeGuest).mockResolvedValue({
+      exitCode: 1,
+      stdout: "",
+      stderr: "sudo: a password is required",
+      truncated: false,
+    });
+    const start = vi.spyOn(runtime, "start");
+    try {
+      const run = service.submit("no-sudo", { type: "runner.run", bindingId: "binding" });
+      await vi.waitFor(() => expect(store.operation(run.id).status).toBe("failed"));
+      expect(store.operation(run.id)).toMatchObject({
+        message:
+          "This environment cannot mount cache volumes: the guest user has no passwordless sudo.",
+        result: {
+          code: "cache_volume_requires_guest_sudo",
+          nextStep:
+            "Prepare or provision a new environment with this Vectis version, or disable the repository cache.",
+        },
+      });
+      expect(broker.prepareRunner).not.toHaveBeenCalled();
+      expect(store.snapshot().instances.every((instance) => instance.status === "stopped")).toBe(
+        true,
+      );
+      const file = await open(join(cacheDirectory, "cache.img"), "r");
+      try {
+        const data = Buffer.alloc(11);
+        await file.read(data, 0, data.length, 0);
+        expect(data.toString()).toBe("saved-cache");
+      } finally {
+        await file.close();
+      }
+      await expect(stat(join(cacheDirectory, "cache.previous.img"))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+      const instance = store.snapshot().instances[0];
+      if (!instance?.directory) throw new Error("Missing stopped synthetic instance");
+      await expect(stat(join(instance.directory, "cache.img"))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+      const retry = service.submit("no-sudo-retry", { type: "runner.run", bindingId: "binding" });
+      await vi.waitFor(() => expect(store.operation(retry.id).status).toBe("failed"));
+      expect(store.operation(retry.id).result).toMatchObject({
+        code: "cache_volume_requires_guest_sudo",
+      });
+      expect(start).toHaveBeenCalledOnce();
+      expect(executeGuest).toHaveBeenCalledOnce();
+      service.submit("disable-no-sudo-cache", {
+        type: "repository.cache",
+        bindingId: "binding",
+        enabled: false,
+      });
+      await service.drain();
+      vi.mocked(executeGuest).mockResolvedValue({
+        exitCode: 0,
+        stdout: "",
+        stderr: "",
+        truncated: false,
+      });
+      const withoutCache = service.submit("no-sudo-without-cache", {
+        type: "runner.run",
+        bindingId: "binding",
+      });
+      await vi.waitFor(() => expect(store.operation(withoutCache.id).status).toBe("succeeded"));
+      expect(broker.prepareRunner).toHaveBeenCalledOnce();
+      expect(start).toHaveBeenCalledTimes(2);
+    } finally {
+      start.mockRestore();
+    }
+  },
+);
diff --git a/apps/server/src/service-runner.test.ts b/apps/server/src/service-runner.test.ts
index b7eb2d23..30510223 100644
--- a/apps/server/src/service-runner.test.ts
+++ b/apps/server/src/service-runner.test.ts
@@ -78,6 +78,7 @@ test.skipIf(process.platform !== "darwin" || process.arch !== "arm64").each([
         environmentId: "test",
         os: "linux" as const,
         encodedConfig: "c2VjcmV0",
+        cacheWrite: false,
         access: { repositoryId: 2, actors: "any" as const, approval: "automatic" as const },
       })),
       runnerStatus: async () => ({ busy: false, status: "online" as const }),
@@ -159,7 +160,7 @@ test.skipIf(process.platform !== "darwin" || process.arch !== "arm64").each([
           status: "queued",
           conclusion: null,
         }));
-        await vi.advanceTimersByTimeAsync(10 * 60 * 1000);
+        await vi.advanceTimersByTimeAsync(5 * 60 * 1000);
         vi.useRealTimers();
       } else service.submit("cancel", { type: cancelType, id: run.id });
       if (phase === "starting") {
@@ -183,6 +184,17 @@ test.skipIf(process.platform !== "darwin" || process.arch !== "arm64").each([
       expect(broker.releaseRunner).toHaveBeenCalledTimes(phase === "starting" ? 0 : 1);
       expect(store.snapshot().instances).toHaveLength(1);
       const snapshot = store.snapshot();
+      expect(snapshot.operations.find((item) => item.id === run.id)?.result).toMatchObject({
+        phases: expect.arrayContaining([
+          expect.objectContaining({
+            name: "queued_locally",
+            startedAt: run.createdAt,
+            endedAt: expect.any(String),
+          }),
+          expect.objectContaining({ name: "vm_start", endedAt: expect.any(String) }),
+          expect.objectContaining({ name: "cleanup", endedAt: expect.any(String) }),
+        ]),
+      });
       expect(snapshot.activities).toHaveLength(1);
       expect(snapshot.activities?.[0]?.subject).not.toHaveProperty("actualJob");
       expect(snapshot.activities?.[0]).toMatchObject({
@@ -325,10 +337,12 @@ async function cleanupFixture(intervalMs = 60000) {
     connectRepository: unused,
     disconnectRepository: unused,
     setAutomatic: unused,
+    setCapacityMode: vi.fn(async (_bindingId: string, _mode: "demand" | "scale_set") => {}),
     setAccess: unused,
     scanJobs: unused,
     refreshJob: unused,
   };
+  vi.spyOn(runtime, "reconcile").mockResolvedValue(false);
   const cloud = { connected: true };
   const service = new Service(store, runtime, () => broker, undefined, undefined, undefined, {
     intervalMs,
@@ -366,6 +380,7 @@ async function cleanupFixture(intervalMs = 60000) {
   return {
     store,
     service,
+    runtime,
     broker,
     cloud,
     operation,
@@ -396,11 +411,45 @@ describe("automatic runner cleanup", () => {
     vi.restoreAllMocks();
   });
 
+  test("capacity mode is a settled setting that calls the authorized broker without an activity", async () => {
+    const { service, broker, store } = fixture;
+    const operation = service.submit("capacity-mode", {
+      type: "repository.capacity-mode",
+      bindingId: "binding",
+      mode: "scale_set",
+    });
+    await service.drain();
+    expect(broker.setCapacityMode).toHaveBeenCalledExactlyOnceWith("binding", "scale_set");
+    expect(store.operation(operation.id)).toMatchObject({
+      status: "succeeded",
+      result: { bindingId: "binding", capacityMode: "scale_set" },
+    });
+    expect(store.snapshot().activities?.some((activity) => activity.id === operation.id)).toBe(
+      false,
+    );
+    broker.setCapacityMode.mockRejectedValueOnce(
+      new VectisError("scale_set_policy_unsupported", "Use demand for this policy."),
+    );
+    const refused = service.submit("refused-mode", {
+      type: "repository.capacity-mode",
+      bindingId: "binding",
+      mode: "scale_set",
+    });
+    await service.drain();
+    expect(store.operation(refused.id)).toMatchObject({
+      status: "failed",
+      result: { code: "scale_set_policy_unsupported" },
+    });
+  });
+
   test("busy cleanup retries the existing operation and activity until GitHub releases it", async () => {
     const { broker, read, tick, store, operation } = fixture;
     broker.releaseRunner.mockRejectedValueOnce(new VectisError("runner_busy", "Runner is busy."));
     await tick();
-    expect(read()).toEqual(operation);
+    expect(read()).toMatchObject({
+      status: "action_required",
+      result: { code: "runner_cleanup_required" },
+    });
     await tick();
     expect(read()).toMatchObject({
       status: "cancelled",
@@ -413,17 +462,72 @@ describe("automatic runner cleanup", () => {
     expect(broker.releaseRunner).toHaveBeenCalledTimes(2);
   });
 
+  test("cleanup retries back off from one minute to thirty minutes", async () => {
+    const { broker, tick, read } = fixture;
+    broker.releaseRunner.mockRejectedValue(new Error("GitHub unavailable"));
+    for (const [attempt, minutes] of [1, 1, 2, 4, 8, 16, 30, 30].entries()) {
+      await tick(minutes * 60000 - 1);
+      expect(broker.releaseRunner).toHaveBeenCalledTimes(attempt);
+      await tick(1);
+      expect(broker.releaseRunner).toHaveBeenCalledTimes(attempt + 1);
+      expect(read()).toMatchObject({
+        status: "action_required",
+        result: {
+          recovery: {
+            attempts: attempt + 1,
+            nextAttemptAt: Date.now() + Math.min(60000 * 2 ** attempt, 30 * 60000),
+          },
+        },
+      });
+    }
+  });
+
+  test("cleanup preserves retry scheduling across service restarts", async () => {
+    const { broker, tick, service, store, runtime } = fixture;
+    broker.releaseRunner.mockRejectedValue(new Error("GitHub unavailable"));
+    await tick(2 * 60000);
+    await service.close();
+    const restarted = new Service(store, runtime, () => broker, undefined, undefined, undefined, {
+      connected: () => true,
+    });
+    try {
+      await restarted.initialize();
+      await restarted.drain();
+      expect(broker.releaseRunner).toHaveBeenCalledTimes(2);
+      await vi.advanceTimersByTimeAsync(2 * 60000 - 1);
+      expect(broker.releaseRunner).toHaveBeenCalledTimes(2);
+      await vi.advanceTimersByTimeAsync(1);
+      await restarted.drain();
+      expect(broker.releaseRunner).toHaveBeenCalledTimes(3);
+    } finally {
+      await restarted.close();
+    }
+  });
+
   test.each([new VectisError("runner_busy", "Runner is busy."), new Error("GitHub unavailable")])(
-    "failed cleanup stops retrying after 30 minutes without claiming success: %s",
+    "failed cleanup backs off and stops retrying after 24 hours without claiming success: %s",
     async (error) => {
       const { broker, tick, read, operation } = fixture;
       broker.releaseRunner.mockRejectedValue(error);
       await tick(29 * 60000);
-      expect(broker.releaseRunner).toHaveBeenCalledTimes(29);
-      expect(read()).toEqual(operation);
-      await tick(10 * 60000);
-      expect(broker.releaseRunner).toHaveBeenCalledTimes(29);
-      expect(read()).toEqual(operation);
+      expect(broker.releaseRunner).toHaveBeenCalledTimes(5);
+      expect(read()).toMatchObject({
+        status: "action_required",
+        result: { code: "runner_cleanup_required" },
+      });
+      await tick(24 * 60 * 60000);
+      const attempts = broker.releaseRunner.mock.calls.length;
+      expect(read()).toMatchObject({
+        status: "action_required",
+        message: expect.stringContaining("expired after 24 hours"),
+        result: { nextStep: expect.stringContaining("runner reconcile") },
+      });
+      await tick(60 * 60000);
+      expect(broker.releaseRunner).toHaveBeenCalledTimes(attempts);
+      expect(read()).toMatchObject({
+        status: "action_required",
+        result: { code: "runner_cleanup_required" },
+      });
       broker.releaseRunner.mockResolvedValue();
       fixture.service.submit("manual", { type: "runner.reconcile", id: operation.id });
       await fixture.service.drain();
@@ -455,6 +559,40 @@ describe("automatic runner cleanup", () => {
     },
   );
 
+  test("offline recovery ends as retryable failure after delayed cleanup", async () => {
+    fixture.store.update(fixture.operation, {
+      result: {
+        ...fixture.progress,
+        code: "runner_cleanup_required",
+        recoveryCause: { code: "runner_offline", message: "Runner went offline." },
+      },
+    });
+    await fixture.tick();
+    expect(fixture.read()).toMatchObject({
+      status: "failed",
+      message: "Runner went offline.",
+      result: { code: "runner_offline" },
+    });
+  });
+
+  test("legacy interrupted runner results without a code also recover automatically", async () => {
+    fixture.store.update(fixture.operation, { result: fixture.progress });
+    await fixture.tick();
+    expect(fixture.read()).toMatchObject({
+      status: "cancelled",
+      result: { code: "runner_interrupted" },
+    });
+  });
+
+  test("approval requirements remain actionable until manually reconciled", async () => {
+    fixture.store.update(fixture.operation, {
+      result: { ...fixture.progress, code: "public_runner_approval_required" },
+    });
+    await fixture.tick();
+    expect(fixture.read()?.status).toBe("action_required");
+    expect(fixture.broker.reconcileRunner).not.toHaveBeenCalled();
+  });
+
   test("disconnected cleanup waits for the cloud connection", async () => {
     fixture.cloud.connected = false;
     await fixture.tick();
@@ -470,17 +608,20 @@ describe("automatic runner cleanup", () => {
       fixture.store.put("instance", fixture.instance.id, { ...fixture.instance, status, pid: 42 });
       await fixture.tick();
       expect(fixture.broker.reconcileRunner).not.toHaveBeenCalled();
-      expect(fixture.read()).toEqual(fixture.operation);
+      expect(fixture.read()).toMatchObject({
+        status: "action_required",
+        result: { code: "runner_cleanup_required" },
+      });
     },
   );
 
-  test("other actionable runner results are left for manual reconciliation", async () => {
+  test("registration uncertainty is automatically reconciled after VM cleanup", async () => {
     fixture.store.update(fixture.operation, {
       result: { ...fixture.progress, code: "runner_registration_uncertain" },
     });
     await fixture.tick();
-    expect(fixture.broker.reconcileRunner).not.toHaveBeenCalled();
-    expect(fixture.read()?.status).toBe("action_required");
+    expect(fixture.broker.reconcileRunner).toHaveBeenCalledOnce();
+    expect(fixture.read()?.status).toBe("cancelled");
   });
 
   test("a mismatched lease is never released or reported cleaned up", async () => {
@@ -492,7 +633,10 @@ describe("automatic runner cleanup", () => {
     });
     await fixture.tick();
     expect(fixture.broker.releaseRunner).not.toHaveBeenCalled();
-    expect(fixture.read()).toEqual(fixture.operation);
+    expect(fixture.read()).toMatchObject({
+      status: "action_required",
+      result: { code: "runner_cleanup_required" },
+    });
   });
 
   test("close clears the timer and aborts an in-flight cleanup without completing it", async () => {
@@ -516,7 +660,10 @@ describe("automatic runner cleanup", () => {
     expect(fixture.broker.reconcileRunner).toHaveBeenCalledOnce();
     expect(() => fixture.service.beginShutdown(true)).toThrow("The service still has active work");
     await fixture.service.close();
-    expect(fixture.read()).toEqual(fixture.operation);
+    expect(fixture.read()).toMatchObject({
+      status: "action_required",
+      result: { code: "runner_cleanup_required" },
+    });
     expect(vi.getTimerCount()).toBe(0);
     await vi.advanceTimersByTimeAsync(60000);
     expect(fixture.broker.releaseRunner).toHaveBeenCalledOnce();
@@ -541,3 +688,117 @@ test("the cleanup interval is injectable and repeated initialization owns one ti
     vi.useRealTimers();
   }
 });
+
+test("a slow instance stop does not block other submissions and duplicate stops share cleanup", async () => {
+  const fixture = await cleanupFixture();
+  let finish = () => {};
+  const waiting = new Promise<void>((resolve) => {
+    finish = resolve;
+  });
+  const stop = vi.spyOn(fixture.runtime, "stop").mockImplementation(async () => {
+    await waiting;
+  });
+  fixture.store.put("instance", "slow", {
+    id: "slow",
+    environmentId: "test",
+    status: "running",
+    pid: 42,
+    createdAt: new Date().toISOString(),
+  });
+  try {
+    const first = fixture.service.submit("stop", { type: "instance.stop", id: "slow" });
+    expect(fixture.service.submit("stop", { type: "instance.stop", id: "slow" }).id).toBe(first.id);
+    const second = fixture.service.submit("another-stop", { type: "instance.stop", id: "slow" });
+    const pause = fixture.service.submit("pause", { type: "machine.pause", paused: true });
+    await fixture.service.drain();
+    expect(fixture.store.get("operation", pause.id)).toMatchObject({ status: "succeeded" });
+    expect(fixture.store.get("operation", first.id)).toMatchObject({ status: "running" });
+    expect(stop).toHaveBeenCalledOnce();
+    finish();
+    await vi.waitFor(() =>
+      expect(fixture.store.get("operation", second.id)).toMatchObject({ status: "succeeded" }),
+    );
+    expect(fixture.store.get("operation", first.id)).toMatchObject({ status: "succeeded" });
+  } finally {
+    finish();
+    await fixture.close();
+    vi.restoreAllMocks();
+  }
+});
+
+test("a stop waits for its own startup cleanup while other commands advance", async () => {
+  const fixture = await cleanupFixture();
+  let finish = () => {};
+  const waiting = new Promise<void>((resolve) => {
+    finish = resolve;
+  });
+  const events: string[] = [];
+  vi.spyOn(fixture.runtime, "start").mockImplementation(
+    async (_id, _environment, _exited, signal) => {
+      signal?.addEventListener("abort", () => events.push("start-aborted"), { once: true });
+      await waiting;
+      events.push("start-settled");
+      throw new Error("Cancelled startup");
+    },
+  );
+  vi.spyOn(fixture.runtime, "hasWorkDirectory").mockResolvedValue(true);
+  vi.spyOn(fixture.runtime, "stop").mockImplementation(async () => {
+    events.push("stop");
+  });
+  fixture.store.put("environment", "test", {
+    id: "test",
+    name: "Test",
+    os: "linux",
+    state: "ready",
+    basePath: "/test/base",
+    cpu: 1,
+    memoryMiB: 512,
+  });
+  try {
+    const start = fixture.service.submit("start", { type: "environment.start", id: "test" });
+    const stop = fixture.service.submit("stop-start", { type: "instance.stop", id: start.id });
+    const pause = fixture.service.submit("pause", { type: "machine.pause", paused: true });
+    await fixture.service.drain();
+    expect(fixture.store.get("operation", pause.id)).toMatchObject({ status: "succeeded" });
+    expect(events).toEqual(["start-aborted"]);
+    finish();
+    await vi.waitFor(() =>
+      expect(fixture.store.get("operation", stop.id)).toMatchObject({ status: "succeeded" }),
+    );
+    expect(events).toEqual(["start-aborted", "start-settled", "stop"]);
+  } finally {
+    finish();
+    await fixture.close();
+    vi.restoreAllMocks();
+  }
+});
+
+test("a runner repository lookup does not hold the command queue", async () => {
+  const fixture = await cleanupFixture();
+  let finish = () => {};
+  const waiting = new Promise<void>((resolve) => {
+    finish = resolve;
+  });
+  vi.spyOn(fixture.broker, "repositories").mockImplementation(async () => {
+    await waiting;
+    throw new VectisError("repository_access_unavailable", "Unavailable");
+  });
+  try {
+    const runner = fixture.service.submit("lookup", { type: "runner.run", bindingId: "binding" });
+    const pause = fixture.service.submit("pause", { type: "machine.pause", paused: true });
+    await fixture.service.drain();
+    expect(fixture.store.get("operation", runner.id)).toMatchObject({ status: "running" });
+    expect(fixture.store.get("operation", pause.id)).toMatchObject({ status: "succeeded" });
+    finish();
+    await vi.waitFor(() =>
+      expect(fixture.store.get("operation", runner.id)).toMatchObject({
+        status: "failed",
+        result: { code: "repository_access_unavailable" },
+      }),
+    );
+  } finally {
+    finish();
+    await fixture.close();
+    vi.restoreAllMocks();
+  }
+});
diff --git a/apps/server/src/service-warm-pool.test.ts b/apps/server/src/service-warm-pool.test.ts
new file mode 100644
index 00000000..a9fa6de8
--- /dev/null
+++ b/apps/server/src/service-warm-pool.test.ts
@@ -0,0 +1,360 @@
+import { ChildProcess } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test, vi } from "vitest";
+import type { Environment, Instance } from "../../../packages/protocol/src/index.js";
+import { readyGuest } from "../../../packages/runner/src/guest-ready.js";
+import { executeGuest, GuestUnavailableError } from "../../../packages/runner/src/guest.js";
+import { VmRuntime } from "../../../packages/runner/src/runtime.js";
+import { Service } from "./service.js";
+import { Store } from "./store.js";
+
+vi.mock("../../../packages/runner/src/guest-ready.js", () => ({ readyGuest: vi.fn() }));
+vi.mock("../../../packages/runner/src/guest.js", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../packages/runner/src/guest.js")>()),
+  executeGuest: vi.fn(),
+}));
+vi.mock("./resource-probe.js", () => ({
+  resourceProbe: () => ({ footprintsMiB: new Map(), pressure: "normal", pressureKnown: true }),
+}));
+const cleanups: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  vi.useRealTimers();
+  for (const cleanup of cleanups.splice(0).reverse()) await cleanup();
+  vi.restoreAllMocks();
+  vi.resetAllMocks();
+});
+const ok = { exitCode: 0, stdout: "", stderr: "", truncated: false };
+
+async function fixture(
+  options: {
+    native?: boolean;
+    recover?: Instance;
+    reconciled?: boolean;
+    pendingStart?: boolean;
+    cache?: boolean;
+    scaleSet?: boolean;
+  } = {},
+) {
+  const home = await mkdtemp(join(tmpdir(), "vectis-service-warm-"));
+  const store = new Store(join(home, "state.sqlite"));
+  const basePath = join(home, "base.img");
+  await writeFile(basePath, "isolated test image");
+  const helper = join(home, "helper");
+  await writeFile(
+    helper,
+    `#!${process.execPath}\nprocess.stdout.write('{"event":"vm.running"}\\n'); setInterval(() => {}, 1000);`,
+    { mode: 0o700 },
+  );
+  const environment: Environment = {
+    id: "linux",
+    name: "Linux",
+    os: "linux",
+    state: "ready",
+    cpu: 1,
+    memoryMiB: 512,
+    basePath,
+    warmPool: options.recover ? 0 : 1,
+  };
+  store.put("environment", environment.id, environment);
+  store.put("machine", "self", {
+    id: "self",
+    name: "Test",
+    paused: false,
+    maxRunners: 2,
+    memoryBudgetMiB: 2048,
+  });
+  if (options.recover) store.put("instance", options.recover.id, options.recover);
+  const exits = new Map<string, (cleaned: boolean) => void>();
+  const runtime = new VmRuntime({ home, appleHelper: helper });
+  const start = vi.spyOn(runtime, "start");
+  const stop = vi.spyOn(runtime, "stop");
+  if (!options.native) {
+    start.mockImplementation(async (id, env, onExit, signal) => {
+      signal?.throwIfAborted();
+      if (options.pendingStart) {
+        await new Promise<void>((resolve) =>
+          signal?.addEventListener("abort", () => resolve(), { once: true }),
+        );
+        signal?.throwIfAborted();
+      }
+      exits.set(id, onExit);
+      return {
+        id,
+        process: new ChildProcess(),
+        directory: runtime.directoryFor(id, env),
+        settled: Promise.resolve(),
+      };
+    });
+    stop.mockImplementation(async (id) => {
+      exits.get(id)?.(true);
+      exits.delete(id);
+    });
+    vi.spyOn(runtime, "close").mockImplementation(async () => {
+      for (const id of exits.keys()) await runtime.stop(id);
+    });
+  }
+  const reconcile = vi.spyOn(runtime, "reconcile").mockResolvedValue(options.reconciled ?? true);
+  const broker = {
+    repositories: vi.fn(async () => [
+      {
+        id: "binding",
+        environmentId: "linux",
+        ...(options.scaleSet ? { capacityMode: "scale_set" as const, automatic: true } : {}),
+        installationId: 1,
+        repositoryId: 1,
+        repositoryName: "test/repo",
+        ...(options.cache ? { cacheVolume: { enabled: true, sizeGiB: 1 } } : {}),
+      },
+    ]),
+    prepareRunner: vi.fn(async () => ({
+      state: "ready" as const,
+      cacheWrite: false,
+      id: "lease",
+      runnerId: 1,
+      environmentId: "linux",
+      os: "linux" as const,
+      encodedConfig: "c2VjcmV0",
+      access: { repositoryId: 1, actors: "any" as const, approval: "automatic" as const },
+    })),
+    releaseRunner: vi.fn(async () => {}),
+    reconcileRunner: vi.fn(async () => {
+      throw new Error("unused");
+    }),
+    runnerStatus: vi.fn(async () => ({ busy: false, status: "online" as const })),
+    analyzeMigration: async () => {
+      throw new Error("unused");
+    },
+    publishMigration: async () => {
+      throw new Error("unused");
+    },
+    connectRepository: async () => "binding",
+    disconnectRepository: async () => {},
+    setAutomatic: async () => {},
+    setAccess: async () => {},
+    jobLogs: async () => {
+      throw new Error("unused");
+    },
+    scanJobs: async () => ({ runs: 0, jobs: 0, complete: true }),
+    refreshJob: async () => {
+      throw new Error("unused");
+    },
+    controlRun: async () => {
+      throw new Error("unused");
+    },
+  };
+  const service = new Service(store, runtime, () => broker);
+  cleanups.push(async () => {
+    await service.close();
+    store.close();
+    await rm(home, { recursive: true, force: true });
+  });
+  vi.mocked(readyGuest).mockResolvedValue({
+    host: "192.0.2.1",
+    port: 22,
+    user: "test",
+    identityFile: join(home, "key"),
+    knownHostsFile: join(home, "hosts"),
+    hostKeyAlias: "test",
+  });
+  vi.mocked(executeGuest).mockResolvedValue(ok);
+  await service.initialize();
+  const warm = () =>
+    store.snapshot().instances.filter((item) => item.role === "warm" && item.status === "running");
+  const listening = () =>
+    vi.mocked(executeGuest).mockImplementationOnce(async (_connection, _script, { signal }) => {
+      await new Promise<void>((resolve) => {
+        signal.addEventListener("abort", () => resolve(), { once: true });
+        if (signal.aborted) resolve();
+      });
+      throw new GuestUnavailableError("cancelled test listener");
+    });
+  return { home, store, runtime, service, broker, start, stop, reconcile, warm, listening };
+}
+
+test.each([false, true])(
+  "runner takeover (scaleSet=%s) skips boot and readiness, then cancellation stops the claimed VM",
+  async (scaleSet) => {
+    const f = await fixture({ scaleSet });
+    await vi.waitFor(() => expect(f.warm()).toHaveLength(1));
+    const id = f.warm()[0]!.id;
+    vi.mocked(executeGuest).mockResolvedValueOnce(ok).mockResolvedValueOnce(ok);
+    f.listening();
+    const run = f.service.submit("takeover", {
+      type: "runner.run",
+      bindingId: "binding",
+      ...(scaleSet ? { automatic: true, scaleSet: { generation: 3 } } : {}),
+    });
+    await vi.waitFor(() => expect(f.broker.prepareRunner).toHaveBeenCalledOnce());
+    expect(f.broker.prepareRunner).toHaveBeenCalledWith(
+      "binding",
+      run.id,
+      expect.any(AbortSignal),
+      scaleSet ? { automatic: true, scaleSet: { generation: 3 } } : {},
+    );
+    expect(f.start).toHaveBeenCalledOnce();
+    expect(readyGuest).toHaveBeenCalledOnce();
+    expect(f.store.snapshot().operations.find((op) => op.id === run.id)?.result).toMatchObject({
+      instanceId: id,
+      stage: "listening",
+    });
+    expect(f.store.snapshot().instances.find((item) => item.id === id)?.role).toBeUndefined();
+    f.service.submit("cancel", { type: "operation.cancel", id: run.id });
+    await vi.waitFor(() => expect(f.broker.releaseRunner).toHaveBeenCalledOnce());
+    expect(f.stop).toHaveBeenCalledWith(id);
+  },
+);
+
+test("unhealthy warm SSH stops that VM before cold startup and JIT registration", async () => {
+  const f = await fixture();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(1));
+  const warmId = f.warm()[0]!.id;
+  vi.mocked(executeGuest)
+    .mockRejectedValueOnce(new GuestUnavailableError("stale SSH"))
+    .mockResolvedValueOnce(ok);
+  f.listening();
+  f.start.mockImplementationOnce(async (id, env, onExit) => {
+    expect(f.stop).toHaveBeenCalledWith(warmId);
+    expect(f.broker.prepareRunner).not.toHaveBeenCalled();
+    const child = new ChildProcess();
+    f.stop.mockImplementation(async (stoppedId) => {
+      if (stoppedId === id) onExit(true);
+    });
+    return {
+      id,
+      process: child,
+      directory: f.runtime.directoryFor(id, env),
+      settled: Promise.resolve(),
+    };
+  });
+  const run = f.service.submit("fallback", { type: "runner.run", bindingId: "binding" });
+  await vi.waitFor(() => expect(f.broker.prepareRunner).toHaveBeenCalledOnce());
+  expect(f.start).toHaveBeenCalledTimes(2);
+  expect(readyGuest).toHaveBeenCalledTimes(2);
+  const start = f.store.snapshot().operations.find((op) => op.key === `${run.id}:start`);
+  expect(f.store.snapshot().operations.find((op) => op.id === run.id)?.result).toMatchObject({
+    instanceId: start?.id,
+  });
+});
+
+test("configure zero and pause drain the pool through the shared service contract", async () => {
+  const f = await fixture();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(1));
+  const disabled = f.service.submit("disable", {
+    type: "environment.configure",
+    id: "linux",
+    warmPool: 0,
+  });
+  await f.service.drain();
+  expect(f.store.snapshot().operations.find((op) => op.id === disabled.id)?.status).toBe(
+    "succeeded",
+  );
+  expect(f.warm()).toHaveLength(0);
+  expect(f.store.snapshot().environments[0]?.warmPool).toBe(0);
+  f.service.submit("enable", { type: "environment.configure", id: "linux", warmPool: 1 });
+  await f.service.drain();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(1));
+  f.service.submit("pause", { type: "machine.pause", paused: true });
+  await f.service.drain();
+  expect(f.warm()).toHaveLength(0);
+});
+
+test.each(["windowsInstallation", "provision"])(
+  "pool disabling remains available while %s is busy",
+  async (kind) => {
+    const f = await fixture();
+    await vi.waitFor(() => expect(f.warm()).toHaveLength(1));
+    f.store.put(kind, "synthetic-preparation", {
+      phase: "installing",
+      id: "synthetic-preparation",
+      environmentId: "derived",
+      directory: join(f.home, "derived"),
+    });
+    const operation = f.service.submit("disable-busy", {
+      type: "environment.configure",
+      id: "linux",
+      warmPool: 0,
+    });
+    await f.service.drain();
+    expect(f.store.snapshot().operations.find((item) => item.id === operation.id)?.status).toBe(
+      "succeeded",
+    );
+    expect(f.warm()).toHaveLength(0);
+    expect(f.store.snapshot().environments[0]?.warmPool).toBe(0);
+  },
+);
+
+test("a timed-out warm startup aborts and awaits its owned task", async () => {
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  const f = await fixture({ pendingStart: true });
+  await vi.waitFor(() => expect(f.start).toHaveBeenCalledOnce());
+  const signal = f.start.mock.calls[0]?.[3];
+  vi.useFakeTimers({ toFake: ["Date"] });
+  vi.setSystemTime(Date.now() + 11 * 60 * 1000);
+  await vi.waitFor(() => expect(signal?.aborted).toBe(true));
+  await vi.waitFor(() => expect(error).toHaveBeenCalledOnce());
+  expect(f.store.snapshot().instances.every((item) => item.status === "stopped")).toBe(true);
+  expect(readyGuest).not.toHaveBeenCalled();
+});
+
+test.each([false, true])(
+  "restart reconciles interrupted warm VMs, confirmed stopped: %s",
+  async (reconciled) => {
+    const instance: Instance = {
+      id: "old-warm",
+      environmentId: "linux",
+      status: "running",
+      role: "warm",
+      memoryMiB: 512,
+      pid: 123,
+      directory: "/synthetic/old",
+      createdAt: new Date().toISOString(),
+    };
+    const f = await fixture({ recover: instance, reconciled });
+    expect(f.reconcile).toHaveBeenCalledWith(instance.id, instance.directory);
+    expect(f.store.snapshot().instances[0]?.status).toBe(reconciled ? "stopped" : "interrupted");
+    expect(f.warm()).toHaveLength(0);
+    expect(f.start).not.toHaveBeenCalled();
+    expect(f.stop).not.toHaveBeenCalled();
+  },
+);
+
+test.skipIf(process.platform !== "darwin" || process.arch !== "arm64")(
+  "the pool starts and cleans a fake executable through the existing VM lifecycle",
+  async () => {
+    const f = await fixture({ native: true });
+    await vi.waitFor(() => expect(f.warm()).toHaveLength(1));
+    const id = f.warm()[0]!.id;
+    expect(f.warm()[0]?.pid).toBeGreaterThan(0);
+    await f.service.close();
+    expect(f.stop).toHaveBeenCalledWith(id);
+    expect(f.store.snapshot().instances.find((item) => item.id === id)?.status).toBe("stopped");
+  },
+);
+
+test("a cache runner boots with its private disk while a generic warm VM remains unclaimed", async () => {
+  const f = await fixture({ cache: true });
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(1));
+  const warmId = f.warm()[0]!.id;
+  vi.mocked(executeGuest).mockResolvedValueOnce(ok).mockResolvedValueOnce(ok);
+  f.listening();
+  const run = f.service.submit("cache-cold", { type: "runner.run", bindingId: "binding" });
+  await vi.waitFor(() => expect(f.broker.prepareRunner).toHaveBeenCalledOnce());
+  expect(f.start).toHaveBeenCalledTimes(2);
+  const coldId = f.start.mock.calls[1]?.[0];
+  expect(coldId).not.toBe(warmId);
+  expect(f.start.mock.calls[1]?.[4]).toMatchObject({
+    cacheDisk: { sourcePath: join(f.home, "instances", "cache", "linux", "1-1", "cache.img") },
+  });
+  expect(f.store.operation(run.id).result).toMatchObject({
+    instanceId: coldId,
+    stage: "listening",
+  });
+  expect(f.warm().map((instance) => instance.id)).toEqual([warmId]);
+  f.service.submit("cancel-cache", { type: "operation.cancel", id: run.id });
+  await vi.waitFor(() => expect(f.broker.releaseRunner).toHaveBeenCalledOnce());
+  expect(f.stop).toHaveBeenCalledWith(coldId);
+  expect(f.stop).not.toHaveBeenCalledWith(warmId);
+  expect(f.store.list("cacheUse")).toEqual([]);
+});
diff --git a/apps/server/src/service.ts b/apps/server/src/service.ts
index 85d16eab..a748682c 100644
--- a/apps/server/src/service.ts
+++ b/apps/server/src/service.ts
@@ -1,6 +1,11 @@
+import { ScaleSetListener } from "./scale-set-listener.js";
+import type { ScaleSetBroker, CapacityMode } from "../../../packages/protocol/src/scale-sets.js";
+import { startProvision, recoverProvisions } from "./provision-task.js";
 import type { RunControlBroker } from "../../../packages/protocol/src/runs.js";
 import { unconfirmedRunCommand } from "../../../packages/github/src/run-control.js";
 import { repositoryReadiness } from "./repository-readiness.js";
+import { cacheGuestPrivilege, recordCacheGuestPrivilege } from "./cache-guest-privilege.js";
+import { cachePrivilegeError } from "../../../packages/runner/src/cache-guest.js";
 import type {
   CloudRepositoryReadiness,
   RepositoryReadiness,
@@ -51,26 +56,37 @@ import { Schema } from "effect";
 import {
   Command,
   ActivityJob,
+  ActivityBase,
   Environment,
   Preparation,
   VectisError,
-  type Operation,
+  Operation,
   type Snapshot,
+  type Instance,
 } from "../../../packages/protocol/src/index.js";
 import { previewMigration } from "../../../packages/migration/src/index.js";
+import { CacheVolumes, type CacheDisk } from "../../../packages/runner/src/cache-volume.js";
+import { defaultCacheSizeGiB } from "../../../packages/protocol/src/cache-volume.js";
 import { VmRuntime } from "../../../packages/runner/src/runtime.js";
 import { Store } from "./store.js";
 import { activityFor, decidingMember, type ActivityLink } from "./activities.js";
 import { retainActivities } from "./activity-retention.js";
 import { observeRunnerJobs, watchRunnerJobs } from "./runner-job-observations.js";
 import { instanceAdmissionError, runnerCapacity } from "./runner-capacity.js";
+import { WarmPool } from "./warm-pool.js";
 
 import type { RepositoryAccess } from "../../../packages/protocol/src/repository-access.js";
 import { jobAccess, restrictiveAccess } from "../../../packages/github/src/access-policy.js";
 
+const CacheRecord = Schema.Struct({ bindingId: Schema.String, directory: Schema.String });
+const CacheUse = Schema.Struct({ bindingId: Schema.String, instanceId: Schema.String });
+
 export class Service {
+  private readonly cacheVolumes: CacheVolumes;
+  private readonly cacheDisks = new Map<string, CacheDisk>();
   private queue: Promise<void> = Promise.resolve();
   private closing = false;
+  private instanceStops = new Map<string, Promise<void>>();
   private preparing: string | undefined;
   private tasks = new Map<string, { abort: AbortController; done: Promise<void> }>();
   private cleanupTimer: ReturnType<typeof setInterval> | undefined;
@@ -78,10 +94,14 @@ export class Service {
   private cleanupAbort = new AbortController();
   private retentionTimer: ReturnType<typeof setInterval> | undefined;
   private stopWatchingJobs: () => void;
+  private readonly warmPool: WarmPool;
+  private warmStarts = new Map<string, AbortSignal>();
+  private readonly scaleSetListener: ScaleSetListener;
   constructor(
     readonly store: Store,
     readonly runtime: VmRuntime,
     readonly runnerConnection: () => RunnerBroker &
+      Partial<ScaleSetBroker> &
       RunControlBroker & {
         analyzeMigration(bindingId: string, signal: AbortSignal): Promise<MigrationAnalysis>;
         publishMigration(previewId: string, signal: AbortSignal): Promise<MigrationPublication>;
@@ -89,6 +109,11 @@ export class Service {
         connectRepository(input: RepositoryConnection, signal: AbortSignal): Promise<string>;
         disconnectRepository(bindingId: string): Promise<void>;
         setAutomatic(bindingId: string, enabled: boolean): Promise<void>;
+        setCacheVolume?(
+          bindingId: string,
+          settings: { enabled: boolean; sizeGiB?: number },
+        ): Promise<void>;
+        setCapacityMode?(bindingId: string, mode: CapacityMode): Promise<void>;
         jobLogs(input: JobLogRequest, signal?: AbortSignal): Promise<JobLogs>;
         setAccess(bindingId: string, access: RepositoryAccess): Promise<void>;
         scanJobs(bindingId: string, signal: AbortSignal): Promise<JobScan>;
@@ -103,8 +128,119 @@ export class Service {
       connected: () => false,
     },
   ) {
+    this.cacheVolumes = new CacheVolumes(runtime.options.home);
     store.recover();
     this.stopWatchingJobs = watchRunnerJobs(store, watchLeases);
+    const host = { cpus: cpus().length, memoryBytes: totalmem() };
+    this.warmPool = new WarmPool(store, {
+      start: (environment, key, signal) => this.startWarm(environment, key, signal),
+      stop: async (instance) => {
+        const current = this.store.snapshot().instances.find((item) => item.id === instance.id);
+        if (!current || current.status === "stopped") return;
+        await this.runtime.stop(instance.id);
+        if (
+          this.store.snapshot().instances.find((item) => item.id === instance.id)?.status !==
+          "stopped"
+        )
+          throw new VectisError("reconciliation_required", "Warm VM cleanup is unconfirmed.");
+      },
+      admission: (snapshot, environment, count) =>
+        instanceAdmissionError(snapshot, environment, host, count),
+      capacity: (snapshot) =>
+        runnerCapacity(snapshot, host, {
+          lookup: {
+            start: (id) => this.runnerStart(id),
+            instance: (id) => this.store.instance(id),
+          },
+        }),
+      onError: (error) => console.error("Warm pool maintenance failed:", redact(inspect(error))),
+    });
+    this.scaleSetListener = new ScaleSetListener({
+      store,
+      snapshot: () => this.snapshot(),
+      repositories: repositorySnapshot,
+      connected: runnerCleanup.connected,
+      broker: () => {
+        const broker = runnerConnection();
+        if (!broker.openScaleSet || !broker.refreshScaleSet || !broker.closeScaleSet)
+          throw new VectisError(
+            "scale_set_unsupported",
+            "This cloud connection does not support scale sets.",
+          );
+        return {
+          openScaleSet: broker.openScaleSet,
+          refreshScaleSet: broker.refreshScaleSet,
+          closeScaleSet: broker.closeScaleSet,
+        };
+      },
+      submit: (key, command) => this.submit(key, command),
+    });
+  }
+  private async startWarm(
+    environment: Environment,
+    key: string,
+    signal: AbortSignal,
+  ): Promise<Instance> {
+    signal.throwIfAborted();
+    const operation = this.submit(key, { type: "environment.start", id: environment.id });
+    this.warmStarts.set(operation.id, signal);
+    const cancel = () => this.tasks.get(operation.id)?.abort.abort();
+    signal.addEventListener("abort", cancel, { once: true });
+    try {
+      await this.waitForOperation(operation.id);
+      const instance = this.store.snapshot().instances.find((item) => item.id === operation.id);
+      if (!instance || instance.status !== "running")
+        throw new VectisError("warm_vm_missing", "The warm VM did not start.");
+      return instance;
+    } catch (error) {
+      const task = this.tasks.get(operation.id);
+      task?.abort.abort();
+      try {
+        await task?.done;
+        const instance = this.store.snapshot().instances.find((item) => item.id === operation.id);
+        if (instance?.status === "running") await this.runtime.stop(instance.id);
+      } finally {
+        const remaining = this.store.snapshot().instances.find((item) => item.id === operation.id);
+        if (remaining && remaining.status !== "stopped")
+          this.store.put("instance", remaining.id, { ...remaining, role: undefined });
+      }
+      throw error;
+    } finally {
+      signal.removeEventListener("abort", cancel);
+      this.warmStarts.delete(operation.id);
+    }
+  }
+  private rememberCache(binding: MachineRepositories[number]) {
+    const environment = this.store
+      .snapshot()
+      .environments.find((item) => item.id === binding.environmentId);
+    if (!environment || binding.installationId === undefined) return;
+    const directory = this.cacheVolumes.directory(environment, binding);
+    const id = createHash("sha256").update(directory).digest("hex");
+    this.store.put("cacheVolume", id, { bindingId: binding.id, directory });
+  }
+  private cacheDirectories(bindingId: string) {
+    return this.store
+      .list("cacheVolume")
+      .map((value) => Schema.decodeUnknownSync(CacheRecord)(value))
+      .filter((record) => record.bindingId === bindingId)
+      .map((record) => record.directory);
+  }
+  repositoriesChanged() {
+    this.queue = this.queue
+      .then(async () => {
+        if (this.closing) return;
+        const repositories = this.repositorySnapshot();
+        if (repositories === undefined) return;
+        const ids = new Set(repositories.map((binding) => binding.id));
+        for (const value of this.store.list("cacheVolume")) {
+          const record = Schema.decodeUnknownSync(CacheRecord)(value);
+          if (!ids.has(record.bindingId)) await this.cacheVolumes.disconnect(record.directory);
+        }
+      })
+      .catch((error: unknown) => {
+        console.error("Repository cache cleanup failed:", redact(inspect(error)));
+      });
   }
   async jobLogs(input: JobLogRequest, signal?: AbortSignal) {
     return this.runnerConnection().jobLogs(input, signal);
@@ -112,24 +248,51 @@ export class Service {
   observeJobs(observations: JobObservations) {
     observeRunnerJobs(this.store, observations);
   }
+  private state(): Snapshot {
+    const current = this.store.snapshot();
+    return {
+      ...current,
+      preparationBusy:
+        current.preparationBusy === true ||
+        this.preparing !== undefined ||
+        this.store.list("provision").length > 0,
+    };
+  }
   snapshot(): Snapshot {
     const repositories = this.repositorySnapshot();
-    const snapshot = this.store.snapshot();
+    const snapshot = this.state();
     return {
       ...snapshot,
       environments: snapshot.environments.map((environment) => ({
         ...environment,
         network: environmentNetwork(environment),
       })),
-      runnerCapacity: runnerCapacity(snapshot, { cpus: cpus().length, memoryBytes: totalmem() }),
+      runnerCapacity: runnerCapacity(
+        snapshot,
+        { cpus: cpus().length, memoryBytes: totalmem() },
+        {
+          lookup: {
+            start: (id) => this.runnerStart(id),
+            instance: (id) => this.store.instance(id),
+          },
+        },
+      ),
       ...(repositories === undefined ? {} : { repositories }),
+      ...(this.scaleSetListener.states().length
+        ? { scaleSets: this.scaleSetListener.states() }
+        : {}),
     };
   }
   repositoryReadiness(
     input: RepositoryReadinessInput,
     readCloud: (input: RepositoryReadinessInput) => Promise<CloudRepositoryReadiness>,
   ): Promise<RepositoryReadiness> {
-    return repositoryReadiness(input, () => this.store.snapshot().environments, readCloud);
+    return repositoryReadiness(
+      input,
+      () => this.store.snapshot().environments,
+      readCloud,
+      (environment) => cacheGuestPrivilege(this.store, environment),
+    );
   }
   async initialize() {
     await recoverWindowsInstallations(this.store);
@@ -158,6 +321,7 @@ export class Service {
       )
         this.store.put("instance", instance.id, { ...instance, status: "stopped", pid: 0 });
     }
+    await recoverProvisions(this.store);
     if (!this.closing && !this.retentionTimer) {
       const sweep = () => retainActivities(this.store, (id) => this.tasks.has(id));
       sweep();
@@ -174,6 +338,13 @@ export class Service {
       this.retentionTimer.unref();
     }
     if (!this.closing && !this.cleanupTimer) {
+      this.cleanupSweep = this.retryRunnerCleanup(true)
+        .catch((error: unknown) => {
+          console.error("Runner recovery failed:", redact(inspect(error)));
+        })
+        .finally(() => {
+          this.cleanupSweep = undefined;
+        });
       this.cleanupTimer = setInterval(() => {
         if (this.closing || this.cleanupSweep || !this.runnerCleanup.connected()) return;
         this.cleanupSweep = this.retryRunnerCleanup()
@@ -186,24 +357,90 @@ export class Service {
       }, this.runnerCleanup.intervalMs ?? 60000);
       this.cleanupTimer.unref();
     }
+    if (!this.closing) this.warmPool.start();
+    if (!this.closing) this.scaleSetListener.start();
   }
-  private async retryRunnerCleanup() {
+  private async retryRunnerCleanup(restarted = false) {
+    const metadata = Schema.Struct({
+      recovery: Schema.Struct({
+        startedAt: Schema.Number,
+        attempts: Schema.Number,
+        nextAttemptAt: Schema.Number,
+      }),
+    });
     for (const operation of this.store.snapshot().operations) {
       if (this.closing || !this.runnerCleanup.connected()) break;
       if (
         operation.command !== "runner.run" ||
         operation.status !== "action_required" ||
-        this.tasks.has(operation.id) ||
-        !(Date.now() - Date.parse(operation.updatedAt) < 30 * 60 * 1000) ||
-        !Schema.is(Schema.Struct({ code: Schema.Literal("runner_cleanup_required") }))(
-          operation.result,
+        this.tasks.has(operation.id)
+      )
+        continue;
+      const result = operation.result;
+      if (!Schema.is(Schema.Struct({ code: Schema.optional(Schema.String) }))(result)) continue;
+      if (
+        ![
+          "runner_cleanup_required",
+          "runner_recovery_pending",
+          "runner_registration_uncertain",
+        ].includes(result.code ?? "runner_recovery_pending")
+      )
+        continue;
+      const recovery = Schema.is(metadata)(result)
+        ? result.recovery
+        : {
+            startedAt: Date.parse(operation.updatedAt),
+            attempts: 0,
+            nextAttemptAt:
+              Date.parse(operation.updatedAt) + (this.runnerCleanup.intervalMs ?? 60000),
+          };
+      const now = Date.now();
+      if (now - recovery.startedAt >= 24 * 60 * 60 * 1000) {
+        if (
+          operation.message !==
+          "Automatic runner recovery expired after 24 hours; cleanup is still unconfirmed."
         )
+          this.store.update(operation, {
+            message:
+              "Automatic runner recovery expired after 24 hours; cleanup is still unconfirmed.",
+            result: {
+              ...result,
+              recovery,
+              nextStep:
+                "Confirm the owned VM stopped, then run vectis runner reconcile with this operation ID.",
+            },
+          });
+        continue;
+      }
+      if (
+        now < recovery.nextAttemptAt &&
+        !(restarted && result.code === "runner_recovery_pending" && !Schema.is(metadata)(result))
       )
         continue;
       try {
+        const progress = Schema.is(RunnerProgress)(result) ? result : undefined;
+        const start = this.runnerStart(operation.id);
+        const instanceId = progress?.instanceId ?? start?.id;
+        const instance = instanceId === undefined ? undefined : this.store.instance(instanceId);
+        if (
+          instance?.status === "interrupted" &&
+          (await this.runtime.reconcile(instance.id, instance.directory))
+        )
+          this.store.put("instance", instance.id, { ...instance, status: "stopped", pid: 0 });
         await this.reconcileRunner(operation.id);
       } catch {
-        // Keep the original update time so failures cannot extend the retry window.
+        const current = this.store.operation(operation.id);
+        if (current?.status === "action_required")
+          this.store.update(current, {
+            result: {
+              ...result,
+              recovery: {
+                ...recovery,
+                attempts: recovery.attempts + 1,
+                nextAttemptAt: Date.now() + Math.min(60000 * 2 ** recovery.attempts, 30 * 60000),
+              },
+            },
+          });
       }
     }
   }
@@ -225,6 +462,8 @@ export class Service {
     if (key.length > 200) throw new VectisError("invalid_request", "The request key is too long.");
     const fingerprint = createHash("sha256").update(JSON.stringify(command)).digest("hex");
     const accepted = this.store.accept(key, fingerprint, command.type, link, operationId);
+    if (accepted.fresh && command.type === "runner.run" && command.scaleSet)
+      this.store.put("scale-set-reservation", key, { bindingId: command.bindingId, key });
     if (accepted.fresh)
       this.queue = this.queue.then(() => this.execute(accepted.operation, command));
     return accepted.operation;
@@ -235,6 +474,12 @@ export class Service {
         "operation_not_cancellable",
         "No active cancellable task has this operation ID.",
       );
+    if (waiting.command === "environment.provision" && this.store.get("provision", waiting.id))
+      throw new VectisError(
+        "operation_not_cancellable",
+        "This provisioning attempt still owns output requiring cleanup.",
+        "Reconcile its interrupted instance, then restart the service to retry owned output cleanup.",
+      );
     if (waiting.command === "runner.run")
       throw new VectisError(
         "operation_not_cancellable",
@@ -253,10 +498,18 @@ export class Service {
     });
     return { operationId: waiting.id, closed: true };
   }
+  private runnerStart(id: string) {
+    try {
+      return this.store.operationByKey(`${id}:start`);
+    } catch (error) {
+      if (!(error instanceof VectisError) || error.code !== "operation_missing") throw error;
+    }
+  }
   private async reconcileRunner(id: string) {
     this.cleanupAbort.signal.throwIfAborted();
-    const snapshot = this.store.snapshot();
-    const interrupted = snapshot.operations.find((item) => item.id === id);
+    const value = this.store.get("operation", id);
+    const interrupted =
+      value === undefined ? undefined : Schema.decodeUnknownSync(Operation)(value);
     if (
       !interrupted ||
       interrupted.command !== "runner.run" ||
@@ -267,11 +520,41 @@ export class Service {
         "reconciliation_required",
         "Only an interrupted runner operation can be reconciled.",
       );
+    const start = this.runnerStart(interrupted.id);
+    if (!Schema.is(RunnerProgress)(interrupted.result)) {
+      const value = this.store.get("activity", interrupted.activityId ?? interrupted.id);
+      const activity =
+        value === undefined ? undefined : Schema.decodeUnknownSync(ActivityBase)(value);
+      if (
+        !start &&
+        activity?.bindingId &&
+        activity.rootOperationId === interrupted.id &&
+        Schema.is(Schema.Struct({ code: Schema.Literal("runner_recovery_pending") }))(
+          interrupted.result,
+        )
+      ) {
+        this.store.update(interrupted, {
+          status: "failed",
+          message: "The service restarted before runner startup or registration began.",
+          result: { code: "runner_interrupted" },
+        });
+        return { operationId: interrupted.id };
+      }
+    }
     const progress = Schema.decodeUnknownSync(RunnerProgress)(interrupted.result);
-    const start = snapshot.operations.find((item) => item.key === `${interrupted.id}:start`);
-    const instance = snapshot.instances.find(
-      (item) => item.id === (progress.instanceId ?? start?.id),
-    );
+    const recoveryCause = Schema.is(
+      Schema.Struct({
+        recoveryCause: Schema.Struct({
+          code: Schema.Literal("runner_offline"),
+          message: Schema.String,
+        }),
+      }),
+    )(interrupted.result)
+      ? interrupted.result.recoveryCause
+      : undefined;
+    const cause = progress.cause ?? recoveryCause;
+    const instanceId = progress.instanceId ?? start?.id;
+    const instance = instanceId === undefined ? undefined : this.store.instance(instanceId);
     if (instance && instance.status !== "stopped")
       throw new VectisError(
         "reconciliation_required",
@@ -304,15 +587,14 @@ export class Service {
         await broker.releaseRunner(lease.id, AbortSignal.any([signal, AbortSignal.timeout(60000)]));
       signal.throwIfAborted();
       this.store.update(interrupted, {
-        status: progress.cause ? "failed" : "cancelled",
+        status: cause ? "failed" : "cancelled",
         message:
-          progress.cause?.message ??
-          "Interrupted runner cleaned up. Check GitHub for the job result.",
+          cause?.message ?? "Interrupted runner cleaned up. Check GitHub for the job result.",
         result: {
           ...progress,
           leaseId: lease.id,
           stage: "finished",
-          ...(progress.cause ? { code: progress.cause.code } : {}),
+          code: cause?.code ?? "runner_interrupted",
         },
       });
       return { operationId: interrupted.id, leaseId: lease.id };
@@ -333,9 +615,18 @@ export class Service {
     operation = this.store.update(operation, { status: "running", message: "Running." });
     try {
       let result: unknown;
-      const snapshot = this.store.snapshot();
+      const snapshot = this.state();
+      const poolOnly =
+        command.type === "environment.configure" &&
+        command.warmPool !== undefined &&
+        command.cpu === undefined &&
+        command.memoryMiB === undefined &&
+        command.storagePath === undefined &&
+        command.x64 === undefined &&
+        command.egress === undefined;
       if (
         (this.preparing || snapshot.preparationBusy) &&
+        !poolOnly &&
         [
           "environment.register",
           "environment.configure",
@@ -348,10 +639,36 @@ export class Service {
           "Finish or cancel the active image preparation before changing environments or starting VMs.",
         );
       switch (command.type) {
+        case "environment.provision": {
+          if (this.closing) throw new VectisError("service_stopping", "The service is stopping.");
+          if (this.preparing || snapshot.preparationBusy)
+            throw new VectisError("preparation_busy", "An image preparation is already active.");
+          if (
+            hasUnconfirmedMacInstallation(this.store) ||
+            hasUnconfirmedWindowsInstallation(this.store) ||
+            this.store
+              .list("preparation")
+              .some((value) => Schema.decodeUnknownSync(Preparation)(value).phase === "booting")
+          )
+            throw new VectisError(
+              "reconciliation_required",
+              "A guest installer needs exit verification.",
+            );
+          const active = await startProvision(this.store, this.runtime, operation, command);
+          this.preparing = operation.id;
+          const done = active.done.finally(() => {
+            this.preparing = undefined;
+            this.tasks.delete(operation.id);
+            this.store.touch();
+          });
+          this.tasks.set(operation.id, { abort: active.abort, done });
+          return;
+        }
+
         case "environment.install-windows":
         case "environment.resume-windows": {
           if (this.closing) throw new VectisError("service_stopping", "The service is stopping.");
-          if (this.preparing)
+          if (this.preparing || this.store.list("provision").length)
             throw new VectisError("preparation_busy", "An image preparation is already active.");
           const active = await startWindowsInstallation(
             this.store,
@@ -364,6 +681,7 @@ export class Service {
           const done = active.done.finally(() => {
             this.preparing = undefined;
             this.tasks.delete(operation.id);
+            this.store.touch();
           });
           this.tasks.set(operation.id, { abort: active.abort, done });
           return;
@@ -409,13 +727,14 @@ export class Service {
               "A Windows installer needs exit verification.",
             );
           if (this.closing) throw new VectisError("service_stopping", "The service is stopping.");
-          if (this.preparing)
+          if (this.preparing || this.store.list("provision").length)
             throw new VectisError("preparation_busy", "An image preparation is already active.");
           const active = await startMacInstallation(this.store, this.runtime, operation, command);
           this.preparing = operation.id;
           const done = active.done.finally(() => {
             this.preparing = undefined;
             this.tasks.delete(operation.id);
+            this.store.touch();
           });
           this.tasks.set(operation.id, { abort: active.abort, done });
           return;
@@ -431,13 +750,14 @@ export class Service {
               "A guest installer needs exit verification.",
             );
           if (this.closing) throw new VectisError("service_stopping", "The service is stopping.");
-          if (this.preparing)
+          if (this.preparing || this.store.list("provision").length)
             throw new VectisError("preparation_busy", "An image preparation is already active.");
           const active = await startPreparation(this.store, this.runtime, operation, command);
           this.preparing = active.setupId;
           const done = active.done.finally(() => {
             this.preparing = undefined;
             this.tasks.delete(operation.id);
+            this.store.touch();
           });
           this.tasks.set(operation.id, { abort: active.abort, done });
           return;
@@ -546,10 +866,68 @@ export class Service {
           return;
         }
         case "repository.disconnect": {
-          await this.runnerConnection().disconnectRepository(command.bindingId);
+          const broker = this.runnerConnection();
+          const binding = (await broker.repositories()).find(
+            (item) => item.id === command.bindingId,
+          );
+          if (binding) this.rememberCache(binding);
+          await broker.disconnectRepository(command.bindingId);
+          for (const directory of this.cacheDirectories(command.bindingId))
+            await this.cacheVolumes.disconnect(directory);
           result = { bindingId: command.bindingId, connected: false };
           break;
         }
+        case "repository.cache":
+        case "cache.clear": {
+          const broker = this.runnerConnection();
+          const binding = (await broker.repositories()).find(
+            (item) => item.id === command.bindingId,
+          );
+          if (!binding)
+            throw new VectisError("repository_missing", "This repository binding is unavailable.");
+          this.rememberCache(binding);
+          if (command.type === "cache.clear") {
+            const uses = this.store
+              .list("cacheUse")
+              .map((value) => Schema.decodeUnknownSync(CacheUse)(value));
+            const instances = this.store.snapshot().instances;
+            if (
+              uses.some(
+                (use) =>
+                  use.bindingId === binding.id &&
+                  instances.some(
+                    (instance) => instance.id === use.instanceId && instance.status !== "stopped",
+                  ),
+              )
+            )
+              throw new VectisError(
+                "cache_in_use",
+                "Stop or reconcile this binding's cache jobs before clearing its volume.",
+              );
+            for (const directory of this.cacheDirectories(binding.id))
+              await this.cacheVolumes.clear(directory);
+            result = { bindingId: binding.id, cleared: true };
+          } else {
+            if (!broker.setCacheVolume)
+              throw new VectisError(
+                "unsupported",
+                "The cloud connection does not support cache settings.",
+              );
+            const settings = {
+              enabled: command.enabled,
+              ...(command.sizeGiB === undefined ? {} : { sizeGiB: command.sizeGiB }),
+            };
+            await broker.setCacheVolume(binding.id, settings);
+            result = {
+              bindingId: binding.id,
+              cacheVolume: {
+                enabled: command.enabled,
+                sizeGiB: command.sizeGiB ?? binding.cacheVolume?.sizeGiB ?? defaultCacheSizeGiB,
+              },
+            };
+          }
+          break;
+        }
         case "repository.access": {
           const access = {
             actors:
@@ -562,6 +940,17 @@ export class Service {
           result = { bindingId: command.bindingId, access };
           break;
         }
+        case "repository.capacity-mode": {
+          const broker = this.runnerConnection();
+          if (!broker.setCapacityMode)
+            throw new VectisError(
+              "scale_set_unsupported",
+              "This cloud connection cannot change capacity modes.",
+            );
+          await broker.setCapacityMode(command.bindingId, command.mode);
+          result = { bindingId: command.bindingId, capacityMode: command.mode };
+          break;
+        }
         case "repository.automatic": {
           await this.runnerConnection().setAutomatic(command.bindingId, command.enabled);
           result = { bindingId: command.bindingId, automatic: command.enabled };
@@ -623,7 +1012,12 @@ export class Service {
                 result,
               });
             })
-            .catch(() => {
+            .catch((error: unknown) => {
+              const githubFailure =
+                error instanceof VectisError &&
+                ["github_unavailable", "github_rate_limited"].includes(error.code)
+                  ? error
+                  : undefined;
               this.store.update(operation, {
                 status: abort.signal.aborted ? "cancelled" : "failed",
                 message: abort.signal.aborted
@@ -632,8 +1026,11 @@ export class Service {
                 result: {
                   bindingId: command.bindingId,
                   ...(command.type === "job.refresh" ? { jobId: command.jobId } : {}),
-                  code: abort.signal.aborted ? "refresh_cancelled" : "job_refresh_failed",
+                  code: abort.signal.aborted
+                    ? "refresh_cancelled"
+                    : (githubFailure?.code ?? "job_refresh_failed"),
                   nextStep:
+                    githubFailure?.nextStep ??
                     "Check repository access and retry the read; for large queues, refresh a known job ID directly.",
                 },
               });
@@ -647,145 +1044,216 @@ export class Service {
         case "runner.run": {
           if (this.closing) throw new VectisError("service_stopping", "The service is stopping.");
           const broker = this.runnerConnection();
-          const binding = (await broker.repositories()).find(
-            (item) => item.id === command.bindingId,
-          );
-          if (!binding)
-            throw new VectisError("repository_missing", "This repository binding is unavailable.");
-          this.store.updateActivity(operation.id, (base) => ({
-            ...base,
-            bindingId: binding.id,
-            environmentId: binding.environmentId,
-            repository: { id: binding.repositoryId, name: binding.repositoryName },
-          }));
-          const environment = snapshot.environments.find(
-            (item) => item.id === binding.environmentId,
-          );
-          if (!environment || environment.state !== "ready")
-            throw new VectisError("setup_required", "Prepare this repository's environment first.");
           const abort = new AbortController();
+          let lifecycleStarted = false;
           let startId: string | undefined;
-          const demandJobId = command.jobId;
-          if (demandJobId === undefined && restrictiveAccess(binding.access))
-            throw new VectisError(
-              "job_required",
-              "Start a specific job under this repository access policy.",
+          let cache: Awaited<ReturnType<CacheVolumes["acquire"]>> | undefined;
+          const revokeCacheWrite = () => cache?.authorizeWrite(false);
+          abort.signal.addEventListener("abort", revokeCacheWrite, { once: true });
+          const done = (async () => {
+            const binding = (await broker.repositories()).find(
+              (item) => item.id === command.bindingId,
             );
-          const done = runRunnerTask(
-            command.bindingId,
-            operation.id,
-            environment,
-            {
-              broker,
-              request: {
-                ...(demandJobId === undefined ? {} : { jobId: demandJobId }),
-                ...(command.automatic ? { automatic: true } : {}),
-              },
-              ...(demandJobId === undefined
-                ? {}
-                : {
-                    needed: async (signal) => {
-                      if (
-                        command.automatic &&
-                        !(await broker.repositories()).some(
-                          (item) => item.id === command.bindingId && item.automatic,
+            if (!binding)
+              throw new VectisError(
+                "repository_missing",
+                "This repository binding is unavailable.",
+              );
+            abort.signal.throwIfAborted();
+            this.store.updateActivity(operation.id, (base) => ({
+              ...base,
+              bindingId: binding.id,
+              environmentId: binding.environmentId,
+              repository: { id: binding.repositoryId, name: binding.repositoryName },
+            }));
+            const environment = this.store
+              .snapshot()
+              .environments.find((item) => item.id === binding.environmentId);
+            if (!environment || environment.state !== "ready")
+              throw new VectisError(
+                "setup_required",
+                "Prepare this repository's environment first.",
+              );
+            let warmStartId: string | undefined;
+            if (command.scaleSet && restrictiveAccess(binding.access))
+              throw new VectisError(
+                "scale_set_policy_unsupported",
+                "Scale set preview requires any actor and automatic approval.",
+              );
+            if (command.scaleSet && (binding.capacityMode !== "scale_set" || !binding.automatic))
+              throw new VectisError(
+                "automatic_disabled",
+                "Scale set capacity is no longer enabled for this binding.",
+              );
+            const demandJobId = command.scaleSet ? undefined : command.jobId;
+            if (demandJobId === undefined && restrictiveAccess(binding.access))
+              throw new VectisError(
+                "job_required",
+                "Start a specific job under this repository access policy.",
+              );
+            if (
+              binding.cacheVolume?.enabled &&
+              cacheGuestPrivilege(this.store, environment) === false
+            )
+              throw cachePrivilegeError();
+            cache = binding.cacheVolume?.enabled
+              ? await this.cacheVolumes.acquire(environment, binding, binding.cacheVolume.sizeGiB)
+              : undefined;
+            if (cache) this.rememberCache(binding);
+            abort.signal.throwIfAborted();
+            lifecycleStarted = true;
+            return runRunnerTask(
+              command.bindingId,
+              operation.id,
+              environment,
+              {
+                broker,
+                ...(cache
+                  ? {
+                      cache: {
+                        sizeGiB: binding.cacheVolume?.sizeGiB ?? defaultCacheSizeGiB,
+                        authorizeWrite: cache.authorizeWrite,
+                        outcome: cache.outcome,
+                        checked: (allowed: boolean) =>
+                          recordCacheGuestPrivilege(this.store, environment, allowed),
+                      },
+                    }
+                  : {}),
+                acceptedAt: operation.createdAt,
+                request: {
+                  ...(demandJobId === undefined ? {} : { jobId: demandJobId }),
+                  ...(command.automatic ? { automatic: true } : {}),
+                  ...(command.scaleSet ? { scaleSet: command.scaleSet } : {}),
+                },
+                ...(demandJobId === undefined
+                  ? {}
+                  : {
+                      needed: async (signal) => {
+                        if (
+                          command.automatic &&
+                          !(await broker.repositories()).some(
+                            (item) => item.id === command.bindingId && item.automatic,
+                          )
                         )
-                      )
-                        return false;
-                      const job = await broker.refreshJob(command.bindingId, demandJobId, signal);
-                      this.store.updateActivity(operation.id, (base) => ({
-                        ...base,
-                        subject: {
-                          ...base.subject,
-                          type: "runner",
-                          requestedJob: Schema.decodeUnknownSync(ActivityJob)(job),
-                        },
-                      }));
-                      // GitHub reports runner ID 0 for a queued job that no runner has taken.
-                      if (job.status !== "queued" || job.runnerId) return false;
-                      if (!matchesRunnerLabels(job.labels, environment.os, environment.id))
-                        throw new VectisError(
-                          "runner_labels_mismatch",
-                          "The GitHub job requires different runner capabilities.",
-                        );
-                      const current = (await broker.repositories()).find(
-                        (item) => item.id === command.bindingId,
-                      );
-                      if (!current)
-                        throw new VectisError(
-                          "repository_missing",
-                          "This repository binding is unavailable.",
-                        );
-                      const access = jobAccess(current.access, job);
-                      if (access && (access !== "approval_required" || command.automatic))
-                        throw new VectisError(
-                          access,
-                          "This job is refused by the repository access policy.",
+                          return false;
+                        const job = await broker.refreshJob(command.bindingId, demandJobId, signal);
+                        this.store.updateActivity(operation.id, (base) => ({
+                          ...base,
+                          subject: {
+                            ...base.subject,
+                            type: "runner",
+                            requestedJob: Schema.decodeUnknownSync(ActivityJob)(job),
+                          },
+                        }));
+                        // GitHub reports runner ID 0 for a queued job that no runner has taken.
+                        if (job.status !== "queued" || job.runnerId) return false;
+                        if (!matchesRunnerLabels(job.labels, environment.os, environment.id))
+                          throw new VectisError(
+                            "runner_labels_mismatch",
+                            "The GitHub job requires different runner capabilities.",
+                          );
+                        const current = (await broker.repositories()).find(
+                          (item) => item.id === command.bindingId,
                         );
-                      return true;
-                    },
-                  }),
-              start: async () => {
-                const started = this.submitChild(operation.id, `${operation.id}:start`, {
-                  type: "environment.start",
-                  id: environment.id,
-                });
-                startId = started.id;
-                const cancelStart = () => {
-                  if (this.closing) this.tasks.get(started.id)?.abort.abort();
-                  else
-                    this.submitChild(operation.id, `${operation.id}:cancel-start`, {
-                      type: "operation.cancel",
-                      id: started.id,
+                        if (!current)
+                          throw new VectisError(
+                            "repository_missing",
+                            "This repository binding is unavailable.",
+                          );
+                        const access = jobAccess(current.access, job);
+                        if (access && (access !== "approval_required" || command.automatic))
+                          throw new VectisError(
+                            access,
+                            "This job is refused by the repository access policy.",
+                          );
+                        return true;
+                      },
+                    }),
+                start: async (onStarting) => {
+                  await this.warmPool.yieldForJob(environment);
+                  abort.signal.throwIfAborted();
+                  const started = this.submitChild(operation.id, `${operation.id}:start`, {
+                    type: "environment.start",
+                    id: environment.id,
+                  });
+                  startId = started.id;
+                  onStarting?.(started.id);
+                  if (cache) {
+                    const volume = cache;
+                    this.cacheDisks.set(started.id, {
+                      sourcePath: volume.disk.sourcePath,
+                      stopped: async (path) => {
+                        if (abort.signal.aborted || this.closing) volume.authorizeWrite(false);
+                        await volume.disk.stopped(path);
+                      },
                     });
-                };
-                abort.signal.addEventListener("abort", cancelStart, { once: true });
-                if (abort.signal.aborted) cancelStart();
-                try {
-                  await this.waitForOperation(started.id);
-                } finally {
-                  abort.signal.removeEventListener("abort", cancelStart);
-                }
-                const instance = this.store
-                  .snapshot()
-                  .instances.find((item) => item.id === started.id);
-                if (!instance || instance.status !== "running")
-                  throw new VectisError("runner_vm_missing", "The runner VM did not start.");
-                return instance;
-              },
-              stop: async () => {
-                if (!startId) return;
-                const current = this.store.snapshot().instances.find((item) => item.id === startId);
-                if (!current || current.status === "stopped") return;
-                const stopped = this.submitChild(operation.id, `${operation.id}:stop`, {
-                  type: "instance.stop",
-                  id: startId,
-                });
-                await this.waitForOperation(stopped.id);
-                const instance = this.store
-                  .snapshot()
-                  .instances.find((item) => item.id === startId);
-                if (instance && instance.status !== "stopped")
-                  throw new VectisError(
-                    "runner_cleanup_required",
-                    "Owned VM termination is unconfirmed.",
-                  );
-              },
-              progress: (result) => {
-                operation = this.store.update(operation, {
-                  result,
-                  message: `Runner: ${result.stage}.`,
-                });
+                    this.store.put("cacheUse", started.id, {
+                      bindingId: binding.id,
+                      instanceId: started.id,
+                    });
+                  }
+                  const cancelStart = () => {
+                    if (this.closing) this.tasks.get(started.id)?.abort.abort();
+                    else
+                      this.submitChild(operation.id, `${operation.id}:cancel-start`, {
+                        type: "operation.cancel",
+                        id: started.id,
+                      });
+                  };
+                  abort.signal.addEventListener("abort", cancelStart, { once: true });
+                  if (abort.signal.aborted) cancelStart();
+                  try {
+                    await this.waitForOperation(started.id);
+                  } finally {
+                    abort.signal.removeEventListener("abort", cancelStart);
+                  }
+                  const instance = this.store.instance(started.id);
+                  if (!instance || instance.status !== "running")
+                    throw new VectisError("runner_vm_missing", "The runner VM did not start.");
+                  return instance;
+                },
+                claimWarm: () => {
+                  const claimed = this.warmPool.claim(environment.id, operation);
+                  if (claimed) startId = warmStartId = claimed.instance.id;
+                  return claimed;
+                },
+                stop: async () => {
+                  if (!startId) return;
+                  const current = this.store.instance(startId);
+                  if (!current || current.status === "stopped") return;
+                  const stopKey =
+                    startId === warmStartId ? `${operation.id}:stop:warm` : `${operation.id}:stop`;
+                  const stopped = this.submitChild(operation.id, stopKey, {
+                    type: "instance.stop",
+                    id: startId,
+                  });
+                  await this.waitForOperation(stopped.id);
+                  const instance = this.store.instance(startId);
+                  if (instance && instance.status !== "stopped")
+                    throw new VectisError(
+                      "runner_cleanup_required",
+                      "Owned VM termination is unconfirmed.",
+                    );
+                },
+                progress: (result) => {
+                  operation = this.store.update(operation, {
+                    result,
+                    message: `Runner: ${result.stage}.`,
+                  });
+                },
               },
-            },
-            abort.signal,
-          )
+              abort.signal,
+            );
+          })()
             .then((completed) => {
               this.store.update(operation, {
                 status: completed.status,
                 message: completed.message,
                 result: {
                   ...completed.progress,
+                  ...("recoveryCause" in completed
+                    ? { recoveryCause: completed.recoveryCause }
+                    : {}),
                   ...("code" in completed
                     ? {
                         code: completed.code,
@@ -797,7 +1265,7 @@ export class Service {
                                   ? completed.nextStep
                                   : completed.status === "action_required"
                                     ? completed.code === "runner_cleanup_required"
-                                      ? "Confirm the owned VM is stopped. While connected, Vectis retries GitHub cleanup automatically for up to 30 minutes. Use vectis runner reconcile with this operation ID if cleanup remains unresolved."
+                                      ? "Confirm the owned VM is stopped. While connected, Vectis retries GitHub cleanup automatically with exponential backoff for up to 24 hours. Use vectis runner reconcile with this operation ID if cleanup remains unresolved."
                                       : "Inspect the owned instance, then run vectis runner reconcile with this operation ID."
                                     : "Inspect the environment prerequisites and GitHub run before requesting a fresh runner.",
                             }),
@@ -806,13 +1274,29 @@ export class Service {
                 },
               });
             })
-            .catch(() => {
-              this.store.update(operation, {
-                status: "action_required",
-                message: "Runner recovery requires inspection.",
-              });
+            .catch((error: unknown) => {
+              if (lifecycleStarted)
+                this.store.update(operation, {
+                  status: "action_required",
+                  message: "Runner recovery requires inspection.",
+                  result: {
+                    ...(typeof operation.result === "object" && operation.result !== null
+                      ? operation.result
+                      : {}),
+                    code: "runner_recovery_pending",
+                  },
+                });
+              else if (abort.signal.aborted)
+                this.store.update(operation, {
+                  status: "cancelled",
+                  message: "Runner request cancelled before startup.",
+                });
+              else this.failOperation(operation, error);
             })
             .finally(() => {
+              abort.signal.removeEventListener("abort", revokeCacheWrite);
+              cache?.release();
+              if (startId) this.cacheDisks.delete(startId);
               this.tasks.delete(operation.id);
             });
           this.tasks.set(operation.id, { abort, done });
@@ -859,13 +1343,30 @@ export class Service {
           break;
         }
         case "machine.configure":
+          if (command.maxRunners === undefined && command.memoryBudgetMiB === undefined)
+            throw new VectisError("invalid_resources", "Specify a runner limit or memory budget.");
+          if (
+            command.memoryBudgetMiB !== undefined &&
+            (!Number.isSafeInteger(command.memoryBudgetMiB) ||
+              command.memoryBudgetMiB < 2048 ||
+              command.memoryBudgetMiB * 1024 ** 2 > totalmem())
+          )
+            throw new VectisError(
+              "invalid_resources",
+              "The VM memory budget must be a whole number between 2048 MiB and total host memory.",
+              "Choose a memory budget between 2048 MiB and total host memory.",
+            );
           this.store.put("machine", "self", {
             ...snapshot.machine,
-            maxRunners: command.maxRunners,
+            ...(command.maxRunners !== undefined ? { maxRunners: command.maxRunners } : {}),
+            ...(command.memoryBudgetMiB !== undefined
+              ? { memoryBudgetMiB: command.memoryBudgetMiB }
+              : {}),
           });
           break;
         case "machine.pause":
           this.store.put("machine", "self", { ...snapshot.machine, paused: command.paused });
+          if (command.paused) await this.warmPool.drainEnvironment();
           break;
         case "environment.register":
           await this.runtime.validate(command.environment);
@@ -900,11 +1401,20 @@ export class Service {
             command.memoryMiB === undefined &&
             command.storagePath === undefined &&
             command.x64 === undefined &&
-            command.egress === undefined
+            command.egress === undefined &&
+            command.warmPool === undefined
           )
             throw new VectisError(
               "invalid_request",
-              "Provide CPU, memory, a storage path, x64 or egress.",
+              "Provide CPU, memory, a storage path, x64, egress or a warm pool size.",
+            );
+          if (
+            command.warmPool !== undefined &&
+            (!Number.isInteger(command.warmPool) || command.warmPool < 0 || command.warmPool > 4)
+          )
+            throw new VectisError(
+              "invalid_request",
+              "Warm pool size must be a whole number from 0 to 4.",
             );
           if (command.x64 === "rosetta" && current.os !== "linux")
             throw new VectisError(
@@ -932,13 +1442,22 @@ export class Service {
             ...(command.cpu !== undefined ? { cpu: command.cpu } : {}),
             ...(command.memoryMiB !== undefined ? { memoryMiB: command.memoryMiB } : {}),
             ...(command.storagePath !== undefined ? { storagePath: command.storagePath } : {}),
+            ...(command.warmPool !== undefined ? { warmPool: command.warmPool } : {}),
           };
           await this.runtime.validate(environment);
           this.store.put("environment", command.id, environment);
+          await this.warmPool.drainEnvironment(command.id);
           result = { environment, appliesTo: "future_instances" };
           break;
         }
         case "environment.remove":
+          if (
+            snapshot.environments.some((environment) => environment.image?.parentId === command.id)
+          )
+            throw new VectisError(
+              "environment_has_children",
+              "Remove derived environments before removing their parent environment. Windows images may depend on its backing disk.",
+            );
           if (
             snapshot.instances.some(
               (instance) => instance.environmentId === command.id && instance.status !== "stopped",
@@ -949,9 +1468,12 @@ export class Service {
               "The environment has running or interrupted instances.",
             );
           this.store.remove("environment", command.id);
+          this.store.remove("cacheGuestPrivilege", command.id);
           break;
         case "environment.start": {
           if (this.closing) throw new VectisError("service_stopping", "The service is stopping.");
+          const warmSignal = this.warmStarts.get(operation.id);
+          warmSignal?.throwIfAborted();
           if (
             this.store
               .list("preparation")
@@ -963,11 +1485,6 @@ export class Service {
             );
           if (snapshot.machine.paused)
             throw new VectisError("machine_paused", "The machine is paused.", "Run vectis resume.");
-          if (snapshot.instances.some((instance) => instance.status === "interrupted"))
-            throw new VectisError(
-              "reconciliation_required",
-              "An interrupted instance needs inspection before new work can start.",
-            );
           const defaults = Schema.decodeUnknownSync(Environment)(
             this.store.get("environment", command.id),
           );
@@ -977,6 +1494,8 @@ export class Service {
             ...(command.memoryMiB !== undefined ? { memoryMiB: command.memoryMiB } : {}),
             ...(command.storagePath !== undefined ? { storagePath: command.storagePath } : {}),
           };
+          if (warmSignal && !this.warmPool.canFill(environment))
+            throw new VectisError("warm_pool_yielded", "Warm pool startup yielded to real work.");
           this.runtime.validateResources(environment);
           const admissionError = instanceAdmissionError(snapshot, environment, {
             cpus: cpus().length,
@@ -993,9 +1512,13 @@ export class Service {
             status: "starting" as const,
             pid: 0,
             createdAt: operation.createdAt,
+            ...(warmSignal ? { role: "warming" as const } : {}),
           };
           this.store.put("instance", id, record);
           const abort = new AbortController();
+          const cancelWarm = () => abort.abort();
+          warmSignal?.addEventListener("abort", cancelWarm, { once: true });
+          if (warmSignal?.aborted) cancelWarm();
           const done = (async () => {
             try {
               const instance = await this.runtime.start(
@@ -1007,8 +1530,10 @@ export class Service {
                     status: cleaned ? "stopped" : "interrupted",
                     pid: 0,
                   });
+                  if (cleaned) this.store.remove("cacheUse", id);
                 },
                 abort.signal,
+                { cacheDisk: this.cacheDisks.get(id) },
               );
               this.store.put("instance", id, {
                 ...record,
@@ -1047,6 +1572,7 @@ export class Service {
               else this.failOperation(operation, error);
             }
           })().finally(() => {
+            warmSignal?.removeEventListener("abort", cancelWarm);
             this.tasks.delete(operation.id);
           });
           this.tasks.set(operation.id, { abort, done });
@@ -1059,7 +1585,7 @@ export class Service {
               "The instance startup task has not finished.",
               "Cancel the startup operation and wait for cleanup before reconciling.",
             );
-          const instance = snapshot.instances.find((item) => item.id === command.id);
+          const instance = this.store.instance(command.id);
           if (!instance) throw new VectisError("instance_missing", "Instance not found.");
           if (
             instance.status !== "interrupted" ||
@@ -1073,9 +1599,42 @@ export class Service {
           this.store.put("instance", command.id, { ...instance, status: "stopped", pid: 0 });
           break;
         }
-        case "instance.stop":
-          await this.runtime.stop(command.id);
-          break;
+        case "instance.stop": {
+          const provision =
+            this.tasks.has(command.id) &&
+            snapshot.operations.some(
+              (item) => item.id === command.id && item.command === "environment.provision",
+            );
+          const abort = new AbortController();
+          let stopping = this.instanceStops.get(command.id);
+          if (!stopping) {
+            const startup = this.tasks.get(command.id);
+            stopping = (async () => {
+              if (startup) {
+                startup.abort.abort();
+                await startup.done;
+                if (provision) return;
+              }
+              const instance = this.store.instance(command.id);
+              if (instance?.status !== "stopped") await this.runtime.stop(command.id);
+            })().finally(() => this.instanceStops.delete(command.id));
+            this.instanceStops.set(command.id, stopping);
+          }
+          const done = stopping
+            .then(() => {
+              this.store.update(operation, {
+                status: "succeeded",
+                message: "Completed.",
+                ...(provision
+                  ? { result: { operationId: command.id, cancellationRequested: true } }
+                  : {}),
+              });
+            })
+            .catch((error: unknown) => this.failOperation(operation, error))
+            .finally(() => this.tasks.delete(operation.id));
+          this.tasks.set(operation.id, { abort, done });
+          return;
+        }
         case "migration.preview":
           result = previewMigration(command.source, command.targets);
           break;
@@ -1115,9 +1674,7 @@ export class Service {
   private async waitForOperation(id: string) {
     const deadline = Date.now() + 600000;
     while (Date.now() < deadline) {
-      const operation = this.store.snapshot().operations.find((item) => item.id === id);
-      if (!operation)
-        throw new VectisError("operation_missing", "Runner control operation is missing.");
+      const operation = this.store.operation(id);
       if (operation.status === "succeeded") return;
       if (operation.status !== "accepted" && operation.status !== "running") {
         const result = operation.result;
@@ -1148,7 +1705,7 @@ export class Service {
     await this.cleanupSweep;
   }
   beginShutdown(ifIdle: boolean) {
-    const snapshot = this.store.snapshot();
+    const snapshot = this.state();
     if (
       ifIdle &&
       (snapshot.preparationBusy ||
@@ -1166,15 +1723,25 @@ export class Service {
       );
     this.closing = true;
   }
+  async suspendScaleSets() {
+    await this.scaleSetListener.suspend();
+  }
+  resumeScaleSets() {
+    this.scaleSetListener.resume();
+  }
   async close() {
     this.closing = true;
+    const poolClosed = this.warmPool.close().catch((error: unknown) => ({ error }));
     this.stopWatchingJobs();
+    await this.scaleSetListener.close();
     if (this.retentionTimer) clearInterval(this.retentionTimer);
     if (this.cleanupTimer) clearInterval(this.cleanupTimer);
     this.cleanupAbort.abort();
     for (const task of this.tasks.values()) task.abort.abort();
     await Promise.all([this.queue, this.cleanupSweep]);
     await Promise.all([...this.tasks.values()].map((task) => task.done));
+    const poolResult = await poolClosed;
     await this.runtime.close();
+    if (poolResult) throw poolResult.error;
   }
 }
diff --git a/apps/server/src/store.test.ts b/apps/server/src/store.test.ts
index 9f397e51..4bf92a26 100644
--- a/apps/server/src/store.test.ts
+++ b/apps/server/src/store.test.ts
@@ -2,9 +2,9 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, expect, test, vi } from "vitest";
-import { Store } from "./store.js";
+import { Store, type StoreOptions } from "./store.js";
 import { activityFor } from "./activities.js";
-import { Snapshot } from "../../../packages/protocol/src/index.js";
+import { Snapshot, type Operation } from "../../../packages/protocol/src/index.js";
 import { Schema } from "effect";
 
 const cleanup: Array<() => Promise<void>> = [];
@@ -12,11 +12,11 @@ afterEach(async () => {
   for (const close of cleanup.reverse()) await close();
   cleanup.length = 0;
 });
-async function fixture() {
+async function fixture(options: StoreOptions = {}) {
   const home = await mkdtemp(join(tmpdir(), "vectis-store-"));
   cleanup.push(() => rm(home, { recursive: true, force: true }));
   const path = join(home, "state.sqlite");
-  return { path, store: new Store(path) };
+  return { path, store: new Store(path, options) };
 }
 
 test("recovery never silently retries an uncertain side effect", async () => {
@@ -250,3 +250,107 @@ test("result text is redacted recursively without changing identity or typed dia
     store.close();
   }
 });
+
+test("restart marks runner recovery pending without losing its durable lease identity", async () => {
+  const { store } = await fixture();
+  try {
+    const { operation } = store.accept("runner", "fingerprint", "runner.run");
+    const progress = {
+      bindingId: "binding",
+      environmentId: "test",
+      leaseKey: operation.id,
+      instanceId: "instance",
+      stage: "registering",
+    };
+    store.update(operation, { status: "running", result: progress });
+    store.put("instance", "instance", {
+      id: "instance",
+      environmentId: "test",
+      status: "running",
+      pid: 42,
+      createdAt: new Date().toISOString(),
+    });
+    store.recover();
+    expect(store.get("operation", operation.id)).toMatchObject({
+      status: "action_required",
+      result: { ...progress, code: "runner_recovery_pending" },
+    });
+    expect(store.get("instance", "instance")).toMatchObject({ status: "interrupted" });
+    expect(store.accept("runner", "fingerprint", "runner.run").fresh).toBe(false);
+    store.recover();
+    expect(store.get("operation", operation.id)).toMatchObject({
+      result: { code: "runner_recovery_pending" },
+    });
+  } finally {
+    store.close();
+  }
+});
+
+test("snapshot bounds only terminal history, by completion time, independently of activity members", async () => {
+  const { store } = await fixture({
+    snapshotLimits: { operations: 2, activities: 1, stoppedInstances: 1 },
+  });
+  try {
+    const add = (id: string, status: Operation["status"], updatedAt: string) => {
+      const command = { type: "job.scan", bindingId: "binding" } as const;
+      const operation = store.accept(id, id, command.type, activityFor(id, command), id).operation;
+      store.put("operation", id, { ...operation, status, updatedAt });
+    };
+    for (const status of ["accepted", "running", "action_required"] as const)
+      add(status, status, "2020-01-01T00:00:00Z");
+    add("recent-completion", "succeeded", "2026-10-16T12:00:00Z");
+    add("older-completion", "failed", "2026-10-15T12:00:00Z");
+    add("oldest-completion", "cancelled", "2026-10-14T12:00:00Z");
+    for (const [id, status, createdAt] of [
+      ["running-instance", "running", "2020-01-01T00:00:00Z"],
+      ["starting-instance", "starting", "2020-01-01T00:00:00Z"],
+      ["interrupted-instance", "interrupted", "2020-01-01T00:00:00Z"],
+      ["new-stopped", "stopped", "2026-10-16T12:00:00Z"],
+      ["old-stopped", "stopped", "2026-10-15T12:00:00Z"],
+    ] as const)
+      store.put("instance", id, { id, status, createdAt, environmentId: "env", pid: 0 });
+
+    const snapshot = store.snapshot();
+    expect(snapshot.operations.map(({ id }) => id).sort()).toEqual([
+      "accepted",
+      "action_required",
+      "older-completion",
+      "recent-completion",
+      "running",
+    ]);
+    expect(snapshot.activities?.map(({ id }) => id).sort()).toEqual([
+      "accepted",
+      "action_required",
+      "recent-completion",
+      "running",
+    ]);
+    expect(snapshot.instances.map(({ id }) => id).sort()).toEqual([
+      "interrupted-instance",
+      "new-stopped",
+      "running-instance",
+      "starting-instance",
+    ]);
+    const revision = snapshot.revision;
+    const withoutTerminalOperations = store.snapshot({
+      operations: 0,
+      activities: 1,
+      stoppedInstances: 0,
+    });
+    expect(withoutTerminalOperations.activities).toEqual(snapshot.activities);
+    expect(withoutTerminalOperations.revision).toBe(revision);
+    expect(store.operation("oldest-completion").status).toBe("cancelled");
+    expect(store.activity("oldest-completion").operations).toHaveLength(1);
+    store.put("operation", "oldest-completion", {
+      ...store.operation("oldest-completion"),
+      updatedAt: "2026-10-17T12:00:00Z",
+    });
+    const next = store.snapshot({ operations: 1, activities: 1, stoppedInstances: 0 });
+    expect(next.revision).not.toBe(revision);
+    expect(next.activities?.find(({ status }) => status === "cancelled")?.id).toBe(
+      "oldest-completion",
+    );
+    expect(next.operations.some(({ id }) => id === "recent-completion")).toBe(false);
+  } finally {
+    store.close();
+  }
+});
diff --git a/apps/server/src/store.ts b/apps/server/src/store.ts
index 65b60b2c..210d4c97 100644
--- a/apps/server/src/store.ts
+++ b/apps/server/src/store.ts
@@ -33,6 +33,9 @@ function redactOperation(operation: Operation): Operation {
 }
 
 const decodeOperation = Schema.decodeUnknownSync(Operation);
+export const snapshotLimits = { operations: 100, activities: 100, stoppedInstances: 20 };
+export type StoreOptions = { snapshotLimits?: typeof snapshotLimits };
+const terminalStatuses = "('succeeded','failed','cancelled')";
 function readOperation(body: unknown): Operation[] {
   if (typeof body !== "string") return [];
   try {
@@ -47,7 +50,9 @@ export class Store {
   readonly startId = randomUUID();
   private changes = 0;
   private listeners = new Set<() => void>();
-  constructor(path: string) {
+  private readonly snapshotLimits: typeof snapshotLimits;
+  constructor(path: string, options: StoreOptions = {}) {
+    this.snapshotLimits = options.snapshotLimits ?? snapshotLimits;
     if (path !== ":memory:") {
       privateFile(path, true);
       privateFile(`${path}-wal`);
@@ -81,6 +86,17 @@ export class Store {
       .map((row) => (typeof row.body === "string" ? JSON.parse(row.body) : null));
   }
   put(kind: string, id: string, body: unknown) {
+    if (kind === "instance") {
+      const instance = Schema.decodeUnknownSync(Instance)(body);
+      if (instance.status === "stopped" && instance.stoppedAt === undefined) {
+        const previous = this.get(kind, id);
+        const stoppedAt =
+          previous === undefined
+            ? instance.createdAt
+            : (Schema.decodeUnknownSync(Instance)(previous).stoppedAt ?? new Date().toISOString());
+        body = { ...instance, stoppedAt };
+      }
+    }
     this.db
       .prepare(
         "INSERT INTO records(kind,id,body) VALUES(?,?,?) ON CONFLICT(kind,id) DO UPDATE SET body=excluded.body",
@@ -114,52 +130,118 @@ export class Store {
       .all(activityId)
       .flatMap((row) => readOperation(row.body));
   }
-  private activities(operations: readonly Operation[]) {
-    const groups = new Map<string, Operation[]>();
-    for (const operation of operations) {
-      if (operation.activityId === undefined) continue;
-      const members = groups.get(operation.activityId);
-      if (members) members.push(operation);
-      else groups.set(operation.activityId, [operation]);
-    }
-    return this.list("activity")
-      .flatMap((value) => {
-        const base = Schema.decodeUnknownSync(ActivityBase)(value);
-        // Operations are read newest row first; preparation outcomes follow insertion order.
-        const activity = deriveActivity(base, (groups.get(base.id) ?? []).toReversed());
-        return activity ? [activity] : [];
-      })
-      .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  operation(id: string) {
+    const value = this.get("operation", id);
+    if (value === undefined)
+      throw new VectisError("operation_missing", "The operation was not found.");
+    return decodeOperation(value);
+  }
+  instance(id: string) {
+    const value = this.get("instance", id);
+    return value === undefined ? undefined : Schema.decodeUnknownSync(Instance)(value);
+  }
+  operationByKey(key: string) {
+    const row = this.db.prepare("SELECT operation_id FROM requests WHERE key=?").get(key);
+    if (!row) throw new VectisError("operation_missing", "The operation was not found.");
+    return this.operation(String(row.operation_id));
+  }
+  activity(id: string) {
+    const value = this.get("activity", id);
+    const operations = this.activityMembers(id);
+    const activity =
+      value === undefined
+        ? undefined
+        : deriveActivity(Schema.decodeUnknownSync(ActivityBase)(value), operations);
+    if (!activity) throw new VectisError("activity_missing", "The activity was not found.");
+    return { activity, operations };
+  }
+  // Retention and job observation need retained history, independently of the status window.
+  activitySummaries(terminalLimit?: number) {
+    return this.db
+      .prepare(`
+      WITH summaries AS MATERIALIZED (
+        SELECT a.body,
+          (SELECT json_remove(o.body,'$.result') FROM records o
+            WHERE o.kind='operation' AND json_valid(o.body)
+              AND json_extract(o.body,'$.activityId')=json_extract(a.body,'$.id')
+              AND (json_extract(a.body,'$.subject.type')='preparation'
+                OR o.id=json_extract(a.body,'$.rootOperationId'))
+            ORDER BY o.rowid DESC LIMIT 1) AS deciding,
+          (SELECT MAX(json_extract(o.body,'$.updatedAt')) FROM records o
+            WHERE o.kind='operation' AND json_valid(o.body)
+              AND json_extract(o.body,'$.activityId')=json_extract(a.body,'$.id')) AS updatedAt
+        FROM records a WHERE a.kind='activity'
+      ), ranked AS (
+        SELECT *, ROW_NUMBER() OVER (
+          PARTITION BY json_extract(deciding,'$.status') IN ${terminalStatuses}
+          ORDER BY json_extract(deciding,'$.updatedAt') DESC, json_extract(body,'$.createdAt') DESC
+        ) AS terminalRank FROM summaries WHERE deciding IS NOT NULL
+      )
+      SELECT body, deciding, updatedAt FROM ranked
+        WHERE json_extract(deciding,'$.status') NOT IN ${terminalStatuses} OR terminalRank<=?
+        ORDER BY json_extract(body,'$.createdAt') DESC
+    `)
+      .all(terminalLimit ?? Number.MAX_SAFE_INTEGER)
+      .flatMap((row) => {
+        if (typeof row.body !== "string") return [];
+        const base = Schema.decodeUnknownSync(ActivityBase)(JSON.parse(row.body));
+        const activity = deriveActivity(base, readOperation(row.deciding));
+        return activity && typeof row.updatedAt === "string"
+          ? [{ ...activity, updatedAt: row.updatedAt }]
+          : [];
+      });
+  }
+  operations(terminalLimit?: number) {
+    return this.db
+      .prepare(`SELECT body FROM records WHERE kind='operation' AND json_valid(body)
+      AND (json_extract(body,'$.status') NOT IN ${terminalStatuses}
+        OR id IN (SELECT id FROM records WHERE kind='operation' AND json_valid(body)
+          AND json_extract(body,'$.status') IN ${terminalStatuses}
+          ORDER BY json_extract(body,'$.updatedAt') DESC, rowid DESC LIMIT ?))
+      ORDER BY rowid DESC`)
+      .all(terminalLimit ?? Number.MAX_SAFE_INTEGER)
+      .flatMap((row) => readOperation(row.body));
+  }
+  instances(stoppedLimit: number) {
+    return this.db
+      .prepare(`SELECT body FROM records WHERE kind='instance'
+      AND (json_extract(body,'$.status')!='stopped'
+        OR id IN (SELECT id FROM records WHERE kind='instance'
+          AND json_extract(body,'$.status')='stopped'
+          ORDER BY COALESCE(json_extract(body,'$.stoppedAt'),json_extract(body,'$.createdAt')) DESC,
+            rowid DESC LIMIT ?)) ORDER BY rowid DESC`)
+      .all(stoppedLimit)
+      .map((row) => Schema.decodeUnknownSync(Instance)(JSON.parse(String(row.body))));
   }
   updateActivity(id: string, update: (base: ActivityBase) => ActivityBase) {
     const current = this.get("activity", id);
     if (current !== undefined)
       this.put("activity", id, update(Schema.decodeUnknownSync(ActivityBase)(current)));
   }
-  snapshot(): Snapshot {
+  snapshot(limits = this.snapshotLimits): Snapshot {
     const machine = Schema.decodeUnknownSync(Machine)(this.get("machine", "self"));
-    const operations = this.db
-      .prepare("SELECT body FROM records WHERE kind='operation' ORDER BY rowid DESC")
-      .all()
-      .flatMap((row) => readOperation(row.body));
     return {
       revision: `${this.startId}:${this.changes}`,
-      preparationBusy: [
-        ...this.list("preparation"),
-        ...this.list("macInstallation"),
-        ...this.list("windowsInstallation"),
-      ].some((value) => {
-        const { phase } = Schema.decodeUnknownSync(Schema.Struct({ phase: Schema.String }))(value);
-        return ["downloading", "booting", "installing", "setup_running"].includes(phase);
-      }),
+      preparationBusy:
+        this.list("provision").length > 0 ||
+        [
+          ...this.list("preparation"),
+          ...this.list("macInstallation"),
+          ...this.list("windowsInstallation"),
+        ].some((value) => {
+          const { phase } = Schema.decodeUnknownSync(Schema.Struct({ phase: Schema.String }))(
+            value,
+          );
+          return ["downloading", "booting", "installing", "setup_running"].includes(phase);
+        }),
       protocolVersion: 1,
       machine,
       environments: this.list("environment").map((value) =>
         Schema.decodeUnknownSync(Environment)(value),
       ),
-      instances: this.list("instance").map((value) => Schema.decodeUnknownSync(Instance)(value)),
-      operations,
-      activities: this.activities(operations),
+      instances: this.instances(limits.stoppedInstances),
+      operations: this.operations(limits.operations),
+      activities: this.activitySummaries(limits.activities),
     };
   }
   accept(
@@ -234,6 +316,18 @@ export class Store {
           status: "action_required",
           message:
             "The service restarted before completion was confirmed. Inspect the operation before retrying.",
+          ...(operation.command === "runner.run"
+            ? {
+                result: {
+                  ...(typeof operation.result === "object" && operation.result !== null
+                    ? operation.result
+                    : {}),
+                  code: "runner_recovery_pending",
+                  nextStep:
+                    "Vectis retries recovery automatically while connected. Confirm the owned VM stopped before manually running vectis runner reconcile with this operation ID.",
+                },
+              }
+            : {}),
         });
     for (const instance of this.snapshot().instances)
       if (instance.status === "starting" || instance.status === "running")
diff --git a/apps/server/src/warm-pool.test.ts b/apps/server/src/warm-pool.test.ts
new file mode 100644
index 00000000..2e7b9750
--- /dev/null
+++ b/apps/server/src/warm-pool.test.ts
@@ -0,0 +1,419 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test, vi } from "vitest";
+import type { Environment, Instance } from "../../../packages/protocol/src/index.js";
+import { readyGuest } from "../../../packages/runner/src/guest-ready.js";
+import { runnerCapacity, instanceAdmissionError } from "./runner-capacity.js";
+import { Store, type StoreOptions } from "./store.js";
+import { WarmPool } from "./warm-pool.js";
+
+vi.mock("../../../packages/runner/src/guest-ready.js", () => ({ readyGuest: vi.fn() }));
+const cleanups: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0).reverse()) await cleanup();
+  vi.resetAllMocks();
+});
+const environment: Environment = {
+  id: "linux",
+  name: "Linux",
+  os: "linux",
+  state: "ready",
+  basePath: "/unused/base",
+  cpu: 1,
+  memoryMiB: 512,
+  warmPool: 2,
+};
+const connection = {
+  host: "192.0.2.1",
+  port: 22,
+  user: "test",
+  identityFile: "/unused/key",
+  knownHostsFile: "/unused/hosts",
+  hostKeyAlias: "test",
+};
+const host = { cpus: 8, memoryBytes: 8 * 1024 ** 3 };
+const probe = () => ({
+  footprintsMiB: new Map<string, number>(),
+  pressure: "normal" as const,
+  pressureKnown: true,
+});
+
+async function fixture(
+  options: StoreOptions & { max?: number; budget?: number; memory?: number } = {},
+) {
+  const home = await mkdtemp(join(tmpdir(), "vectis-warm-pool-"));
+  const store = new Store(join(home, "state.sqlite"), options);
+  store.put("machine", "self", {
+    id: "self",
+    name: "Test",
+    paused: false,
+    maxRunners: options.max ?? 5,
+    memoryBudgetMiB: options.budget ?? 4096,
+  });
+  store.put("environment", environment.id, { ...environment, memoryMiB: options.memory ?? 512 });
+  let now = Date.now();
+  let pressure: "normal" | "warning" | "critical" = "normal";
+  const footprintsMiB = new Map<string, number>();
+  const resources = () => ({ ...probe(), footprintsMiB, pressure });
+  const start = vi.fn(
+    async (env: Environment, key: string, signal: AbortSignal): Promise<Instance> => {
+      signal.throwIfAborted();
+      const operation = store.accept(key, key, "environment.start").operation;
+      const instance: Instance = {
+        id: operation.id,
+        environmentId: env.id,
+        status: "running",
+        role: "warming",
+        memoryMiB: env.memoryMiB,
+        pid: 0,
+        createdAt: new Date(now).toISOString(),
+      };
+      store.put("instance", instance.id, instance);
+      store.update(operation, { status: "succeeded" });
+      return instance;
+    },
+  );
+  const stop = vi.fn(async (instance: Instance) => {
+    const current = store.snapshot().instances.find((item) => item.id === instance.id);
+    store.put("instance", instance.id, { ...current, status: "stopped", pid: 0 });
+  });
+  vi.mocked(readyGuest).mockResolvedValue(connection);
+  const error = vi.fn();
+  const pool = new WarmPool(store, {
+    start,
+    stop,
+    now: () => now,
+    admission: (snapshot, env, count) =>
+      instanceAdmissionError(snapshot, env, host, count, resources),
+    capacity: (snapshot) => runnerCapacity(snapshot, host, { probe: resources }),
+    onError: error,
+  });
+  cleanups.push(async () => {
+    await pool.close();
+    store.close();
+    await rm(home, { recursive: true, force: true });
+  });
+  const warm = () =>
+    store.snapshot().instances.filter((item) => item.status === "running" && item.role === "warm");
+  const runner = (key: string) => {
+    const operation = store.accept(key, key, "runner.run").operation;
+    return store.update(operation, {
+      status: "running",
+      result: {
+        bindingId: "binding",
+        environmentId: environment.id,
+        leaseKey: key,
+        stage: "starting",
+      },
+    });
+  };
+  return {
+    store,
+    pool,
+    start,
+    stop,
+    warm,
+    runner,
+    error,
+    setNow: (value: number) => {
+      now = value;
+    },
+    now: () => now,
+    setFootprint: (id: string, memoryMiB: number) => footprintsMiB.set(id, memoryMiB),
+    setPressure: (value: typeof pressure) => {
+      pressure = value;
+    },
+  };
+}
+
+test("pressure prevents pool filling until normal pressure returns", async () => {
+  const f = await fixture();
+  f.setPressure("critical");
+  f.pool.start();
+  expect(f.pool.canFill(environment)).toBe(false);
+  expect(f.start).not.toHaveBeenCalled();
+  f.setPressure("normal");
+  f.pool.refresh();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(2));
+});
+
+test("failed ownership persistence rolls the claim back without losing the warm VM", async () => {
+  const f = await fixture();
+  f.pool.start();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(2));
+  const operation = f.runner("claim");
+  const update = vi.spyOn(f.store, "update").mockImplementationOnce(() => {
+    throw new Error("write failed");
+  });
+  expect(() => f.pool.claim(environment.id, operation)).toThrow("write failed");
+  update.mockRestore();
+  expect(f.warm()).toHaveLength(2);
+  expect(f.pool.claim(environment.id, operation)?.instance).toBeDefined();
+});
+
+test("fills to N with SSH-ready, runner-less children and stops owned VMs on shutdown", async () => {
+  const f = await fixture();
+  f.pool.start();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(2));
+  expect(f.start).toHaveBeenCalledTimes(2);
+  expect(
+    f.store
+      .snapshot()
+      .operations.every(
+        (op) => op.key.startsWith("warm:linux:") && op.command === "environment.start",
+      ),
+  ).toBe(true);
+  expect(runnerCapacity(f.store.snapshot(), host, { probe })).toMatchObject({
+    active: 0,
+    available: 5,
+    budget: { memoryCommittedMiB: 1024 },
+  });
+  await f.pool.close();
+  expect(f.stop).toHaveBeenCalledTimes(2);
+  expect(f.warm()).toHaveLength(0);
+});
+
+test.each([{ max: 2 }, { budget: 2048, memory: 1024 }])(
+  "leaves the last slot and startup estimate free: %j",
+  async (options) => {
+    const f = await fixture(options);
+    f.pool.start();
+    await vi.waitFor(() => expect(f.warm()).toHaveLength(1));
+    expect(f.pool.canFill(f.store.snapshot().environments[0]!)).toBe(false);
+  },
+);
+
+test("queued runners prevent pool admission and preparation or pause prevents filling", async () => {
+  const f = await fixture();
+  const operation = f.store.accept("queued", "queued", "runner.run").operation;
+  f.pool.start();
+  expect(f.pool.canFill(environment)).toBe(false);
+  f.store.update(operation, { status: "cancelled" });
+  const machine = f.store.snapshot().machine;
+  f.store.put("machine", "self", { ...machine, paused: true });
+  expect(f.pool.canFill(environment)).toBe(false);
+  f.store.put("machine", "self", machine);
+  f.store.accept("prepare", "prepare", "environment.prepare-linux");
+  expect(f.pool.canFill(environment)).toBe(false);
+  expect(f.start).not.toHaveBeenCalled();
+});
+
+test("does not mark a VM warm before readiness and cancels readiness for queued work", async () => {
+  const f = await fixture();
+  vi.mocked(readyGuest).mockImplementation(async (_env, _instance, signal) => {
+    await new Promise<void>((resolve) => {
+      signal.addEventListener("abort", () => resolve(), { once: true });
+    });
+    signal.throwIfAborted();
+    return connection;
+  });
+  f.pool.start();
+  await vi.waitFor(() => expect(readyGuest).toHaveBeenCalledOnce());
+  expect(f.warm()).toHaveLength(0);
+  f.runner("queued");
+  await vi.waitFor(() => expect(f.stop).toHaveBeenCalledOnce());
+  expect(f.store.snapshot().instances.every((item) => item.status === "stopped")).toBe(true);
+});
+
+test("concurrent runners claim a VM exactly once and persist ownership with the claim", async () => {
+  const f = await fixture();
+  f.store.put("environment", environment.id, { ...environment, warmPool: 1 });
+  f.pool.start();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(1));
+  const id = f.warm()[0]!.id;
+  const operations = [f.runner("one"), f.runner("two")];
+  const claims = await Promise.all(
+    operations.map(async (operation) => f.pool.claim(environment.id, operation)),
+  );
+  expect(claims.filter(Boolean)).toHaveLength(1);
+  expect(claims[0]?.instance).toMatchObject({ id, role: undefined });
+  expect(claims[0]?.connection).toBe(connection);
+  expect(
+    f.store.snapshot().operations.find((op) => op.id === operations[0]!.id)?.result,
+  ).toMatchObject({ instanceId: id });
+  await f.pool.close();
+  expect(f.stop).not.toHaveBeenCalled();
+});
+
+test("recycles at 30 minutes and refuses an aged or backwards-clock claim", async () => {
+  const f = await fixture();
+  f.pool.start();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(2));
+  const ids = f.warm().map((item) => item.id);
+  const now = f.now();
+  f.setNow(now - 1);
+  const runner = f.runner("clock");
+  expect(f.pool.claim(environment.id, runner)).toBeUndefined();
+  f.store.update(runner, { status: "cancelled" });
+  f.setNow(now + 30 * 60 * 1000);
+  f.pool.refresh();
+  await vi.waitFor(() => expect(f.start).toHaveBeenCalledTimes(4));
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(2));
+  expect(f.warm().every((item) => !ids.includes(item.id))).toBe(true);
+  expect(f.stop).toHaveBeenCalledTimes(2);
+});
+
+test("yields other environments' warm VMs when a real job needs memory", async () => {
+  const f = await fixture({ budget: 2048 });
+  f.pool.start();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(2));
+  const other = { ...environment, id: "other", memoryMiB: 1536, warmPool: 0 };
+  f.store.put("environment", other.id, other);
+  f.runner("real");
+  expect(instanceAdmissionError(f.store.snapshot(), other, host, 1, probe)?.code).toBe(
+    "memory_budget_exceeded",
+  );
+  await f.pool.yieldForJob(other);
+  expect(f.stop).toHaveBeenCalledOnce();
+  expect(instanceAdmissionError(f.store.snapshot(), other, host, 1, probe)).toBeUndefined();
+});
+
+test.each(["disabled", "paused", "configuration"])("drains the pool when %s", async (change) => {
+  const f = await fixture();
+  f.pool.start();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(2));
+  if (change === "paused")
+    f.store.put("machine", "self", { ...f.store.snapshot().machine, paused: true });
+  else
+    f.store.put("environment", environment.id, {
+      ...environment,
+      warmPool: change === "disabled" ? 0 : 2,
+      cpu: change === "configuration" ? 2 : 1,
+    });
+  await vi.waitFor(() => expect(f.stop).toHaveBeenCalledTimes(2));
+  if (change !== "configuration") expect(f.warm()).toHaveLength(0);
+});
+
+test("failed warm cleanup retains resource reservations and does not spin retries", async () => {
+  const f = await fixture();
+  f.pool.start();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(2));
+  f.stop.mockRejectedValueOnce(new Error("unconfirmed"));
+  f.store.put("environment", environment.id, { ...environment, warmPool: 0 });
+  await vi.waitFor(() => expect(f.error).toHaveBeenCalledOnce());
+  expect(
+    f.store
+      .snapshot()
+      .instances.some((item) => item.status === "running" && item.role === undefined),
+  ).toBe(true);
+  expect(
+    runnerCapacity(f.store.snapshot(), host, { probe }).budget?.memoryCommittedMiB,
+  ).toBeGreaterThanOrEqual(512);
+});
+
+test("pressure and the shared macOS limit block warm admission", async () => {
+  const f = await fixture();
+  const mac = { ...environment, os: "macos" as const };
+  f.store.put("environment", environment.id, mac);
+  f.pool.start();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(1));
+  expect(f.pool.canFill(mac)).toBe(false);
+  const state = f.store.snapshot();
+  const pressured = () => ({ ...probe(), pressure: "critical" as const });
+  expect(instanceAdmissionError(state, mac, host, 1, pressured)?.code).toBe("memory_pressure");
+});
+
+test("disabled pools stay dormant and still react to later configuration changes", async () => {
+  const f = await fixture();
+  f.store.put("environment", environment.id, { ...environment, warmPool: 0 });
+  vi.useFakeTimers();
+  try {
+    f.pool.start();
+    await vi.advanceTimersByTimeAsync(24 * 60 * 60 * 1000);
+    expect(f.start).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+    f.store.put("environment", environment.id, { ...environment, warmPool: 1 });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(f.warm()).toHaveLength(1);
+    f.store.put("environment", environment.id, { ...environment, warmPool: 0 });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(f.warm()).toHaveLength(0);
+    expect(vi.getTimerCount()).toBe(0);
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("cold jobs can reclaim their own environment's warm VMs when measured memory no longer fits", async () => {
+  const f = await fixture({ budget: 2048 });
+  f.pool.start();
+  await vi.waitFor(() => expect(f.warm()).toHaveLength(2));
+  for (const instance of f.warm()) f.setFootprint(instance.id, 900);
+  f.runner("cache-cold");
+  await f.pool.yieldForJob(environment);
+  expect(f.stop).toHaveBeenCalledOnce();
+  expect(f.warm()).toHaveLength(1);
+});
+
+test("a disabled pool does not rebuild status on each retained history write", async () => {
+  const f = await fixture();
+  f.store.put("environment", environment.id, { ...environment, warmPool: 0 });
+  const snapshot = vi.spyOn(f.store, "snapshot");
+  try {
+    f.pool.start();
+    for (let index = 0; index < 20; index++) {
+      f.store.put("operation", `history-${index}`, {
+        id: `history-${index}`,
+        key: `history-${index}`,
+        command: "job.scan",
+        status: "succeeded",
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        message: "Completed.",
+      });
+    }
+    expect(snapshot).not.toHaveBeenCalled();
+    expect(f.start).not.toHaveBeenCalled();
+  } finally {
+    snapshot.mockRestore();
+  }
+});
+
+test("a running legacy runner does not block pool filling when its start leaves the status window", async () => {
+  const snapshotLimits = { operations: 3, activities: 3, stoppedInstances: 2 };
+  const f = await fixture({ snapshotLimits });
+  const runner = f.runner("legacy");
+  const start = f.store.accept(`${runner.id}:start`, "start", "environment.start").operation;
+  f.store.update(start, { status: "succeeded" });
+  f.store.put("instance", start.id, {
+    id: start.id,
+    environmentId: environment.id,
+    status: "running",
+    memoryMiB: 512,
+    pid: 0,
+    createdAt: new Date().toISOString(),
+  });
+  for (let index = 0; index < snapshotLimits.operations; index++) {
+    const operation = f.store.accept(`later-${index}`, `later-${index}`, "job.scan").operation;
+    f.store.update(operation, { status: "succeeded" });
+  }
+  const snapshot = f.store.snapshot();
+  expect(snapshot.operations).toHaveLength(snapshotLimits.operations + 1);
+  expect(snapshot.operations).toContainEqual(expect.objectContaining({ id: runner.id }));
+  expect(snapshot.operations.some((operation) => operation.id === start.id)).toBe(false);
+  expect(f.store.operationByKey(`${runner.id}:start`)).toMatchObject({ id: start.id });
+  expect(f.pool.canFill(environment)).toBe(true);
+});
+
+test.each(["accepted", "running", "action_required"] as const)(
+  "%s provisioning reserves capacity and prevents warm pool startup",
+  async (status) => {
+    const f = await fixture();
+    const operation = f.store.accept("provision", "provision", "environment.provision").operation;
+    f.store.update(operation, { status });
+    if (status === "action_required")
+      f.store.put("provision", operation.id, {
+        id: operation.id,
+        environmentId: "derived",
+        directory: "/unused/derived",
+      });
+    f.pool.start();
+    expect(f.pool.canFill(environment)).toBe(false);
+    expect(runnerCapacity(f.store.snapshot(), host, { probe }).available).toBe(0);
+    expect(f.start).not.toHaveBeenCalled();
+    f.store.remove("provision", operation.id);
+    f.store.update(operation, { status: "failed" });
+    await vi.waitFor(() => expect(f.warm()).toHaveLength(2));
+  },
+);
diff --git a/apps/server/src/warm-pool.ts b/apps/server/src/warm-pool.ts
new file mode 100644
index 00000000..83e640c2
--- /dev/null
+++ b/apps/server/src/warm-pool.ts
@@ -0,0 +1,287 @@
+import { randomUUID } from "node:crypto";
+import { Schema } from "effect";
+import {
+  Environment,
+  type Instance,
+  type Operation,
+  type RunnerCapacity,
+  type Snapshot,
+  VectisError,
+} from "../../../packages/protocol/src/index.js";
+import { RunnerProgress } from "../../../packages/protocol/src/runners.js";
+import { readyGuest } from "../../../packages/runner/src/guest-ready.js";
+import type { GuestConnection } from "../../../packages/runner/src/guest.js";
+import { Store } from "./store.js";
+import { preparationBusy } from "./runner-capacity.js";
+
+const maxAgeMs = 30 * 60 * 1000;
+
+interface Controls {
+  start(environment: Environment, key: string, signal: AbortSignal): Promise<Instance>;
+  stop(instance: Instance): Promise<void>;
+  admission(snapshot: Snapshot, environment: Environment, count?: number): VectisError | undefined;
+  capacity(snapshot: Snapshot): RunnerCapacity;
+  now?: () => number;
+  onError(error: unknown): void;
+}
+
+export class WarmPool {
+  private ready = new Map<string, { connection: GuestConnection; configuration: string }>();
+  private stopping = new Map<string, Promise<void>>();
+  private pending: { environment: Environment; abort: AbortController } | undefined;
+  private sweep: Promise<void> | undefined;
+  private dirty = false;
+  private closed = false;
+  private retryAt = 0;
+  private unsubscribe: (() => void) | undefined;
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private readonly now: () => number;
+
+  constructor(
+    private readonly store: Store,
+    private readonly controls: Controls,
+  ) {
+    this.now = controls.now ?? Date.now;
+  }
+
+  start() {
+    if (this.unsubscribe || this.closed) return;
+    this.unsubscribe = this.store.onChange(() => this.refresh());
+    this.refresh();
+  }
+
+  private waiting(snapshot: Snapshot) {
+    return snapshot.operations.some((operation) => {
+      if (operation.command !== "runner.run" || !["accepted", "running"].includes(operation.status))
+        return false;
+      const progress = Schema.is(RunnerProgress)(operation.result) ? operation.result : undefined;
+      let instanceId = progress?.instanceId;
+      if (instanceId === undefined) {
+        try {
+          instanceId = this.store.operationByKey(`${operation.id}:start`).id;
+        } catch (error) {
+          if (!(error instanceof VectisError) || error.code !== "operation_missing") throw error;
+        }
+      }
+      const instance = instanceId === undefined ? undefined : this.store.instance(instanceId);
+      return !instance || instance.status === "stopped";
+    });
+  }
+
+  private enabled(snapshot: Snapshot, environment: Environment) {
+    return (
+      !this.closed &&
+      !snapshot.machine.paused &&
+      !preparationBusy(snapshot) &&
+      (environment.warmPool ?? 0) > 0 &&
+      environment.state === "ready"
+    );
+  }
+
+  canFill(environment: Environment) {
+    const snapshot = this.store.snapshot();
+    const physical = {
+      ...snapshot,
+      instances: snapshot.instances.map((instance) => ({ ...instance, role: undefined })),
+    };
+    const capacity = this.controls.capacity(physical);
+    const pooled = snapshot.instances.filter(
+      (instance) => instance.role && ["starting", "running"].includes(instance.status),
+    );
+    return (
+      this.enabled(snapshot, environment) &&
+      !this.waiting(snapshot) &&
+      capacity.active + pooled.length + 1 < capacity.max &&
+      pooled.filter((instance) => instance.environmentId === environment.id).length <
+        (environment.warmPool ?? 0) &&
+      (capacity.environments?.find((item) => item.environmentId === environment.id)?.available ??
+        0) > 1 &&
+      !this.controls.admission(snapshot, environment, 2)
+    );
+  }
+
+  refresh() {
+    if (this.closed) return;
+    const configured = this.store
+      .list("environment")
+      .some((value) => (Schema.decodeUnknownSync(Environment)(value).warmPool ?? 0) > 0);
+    if (configured) {
+      if (!this.timer) {
+        this.timer = setInterval(() => this.refresh(), 5000);
+        this.timer.unref();
+      }
+    } else if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    if (!configured && this.ready.size === 0 && !this.pending) return;
+    const snapshot = this.store.snapshot();
+    if (this.pending) {
+      const current = snapshot.environments.find(
+        (item) => item.id === this.pending?.environment.id,
+      );
+      if (
+        !current ||
+        JSON.stringify(current) !== JSON.stringify(this.pending.environment) ||
+        !this.enabled(snapshot, current) ||
+        this.waiting(snapshot)
+      )
+        this.pending.abort.abort();
+    }
+    this.dirty = true;
+    if (this.sweep) return;
+    // Defer work until the current store transaction or service command has finished.
+    this.sweep = Promise.resolve()
+      .then(() => this.replenish())
+      .catch((error: unknown) => {
+        this.retryAt = this.now() + 30000;
+        this.controls.onError(error);
+      })
+      .finally(() => {
+        this.sweep = undefined;
+        if (this.dirty && !this.closed) this.refresh();
+      });
+  }
+
+  private async replenish() {
+    this.dirty = false;
+    for (const [id, entry] of this.ready) {
+      const snapshot = this.store.snapshot();
+      const instance = snapshot.instances.find((item) => item.id === id);
+      const environment = snapshot.environments.find((item) => item.id === instance?.environmentId);
+      if (!instance || instance.status !== "running" || instance.role !== "warm") {
+        this.ready.delete(id);
+        continue;
+      }
+      const age = this.now() - Date.parse(instance.createdAt);
+      const siblings = snapshot.instances.filter(
+        (item) =>
+          item.environmentId === instance.environmentId &&
+          item.role === "warm" &&
+          item.status === "running",
+      );
+      if (
+        !environment ||
+        !this.enabled(snapshot, environment) ||
+        JSON.stringify(environment) !== entry.configuration ||
+        siblings.length > (environment.warmPool ?? 0) ||
+        !Number.isFinite(age) ||
+        age < 0 ||
+        age >= maxAgeMs
+      )
+        await this.stop(instance);
+    }
+    if (this.closed || this.now() < this.retryAt) return;
+    const environment = this.store.snapshot().environments.find((item) => this.canFill(item));
+    if (!environment) return;
+    const abort = new AbortController();
+    this.pending = { environment, abort };
+    let instance: Instance | undefined;
+    try {
+      instance = await this.controls.start(
+        environment,
+        `warm:${environment.id}:${randomUUID()}`,
+        abort.signal,
+      );
+      const connection = await readyGuest(environment, instance, abort.signal);
+      abort.signal.throwIfAborted();
+      const current = this.store.snapshot().instances.find((item) => item.id === instance?.id);
+      if (!current || current.status !== "running")
+        throw new Error("Warm VM stopped before readiness.");
+      this.ready.set(current.id, { connection, configuration: JSON.stringify(environment) });
+      this.store.put("instance", current.id, { ...current, role: "warm" });
+    } catch (error) {
+      if (instance) await this.stop(instance);
+      if (!abort.signal.aborted) throw error;
+    } finally {
+      this.pending = undefined;
+    }
+    this.dirty = true;
+  }
+
+  claim(environmentId: string, operation: Operation) {
+    if (this.closed || this.store.snapshot().machine.paused) return undefined;
+    for (const [id, entry] of this.ready) {
+      const snapshot = this.store.snapshot();
+      const instance = snapshot.instances.find((item) => item.id === id);
+      const environment = snapshot.environments.find((item) => item.id === environmentId);
+      const age = instance ? this.now() - Date.parse(instance.createdAt) : NaN;
+      if (
+        !instance ||
+        instance.environmentId !== environmentId ||
+        instance.status !== "running" ||
+        instance.role !== "warm" ||
+        this.stopping.has(id) ||
+        !environment ||
+        !(environment.warmPool ?? 0) ||
+        JSON.stringify(environment) !== entry.configuration ||
+        !Number.isFinite(age) ||
+        age < 0 ||
+        age >= maxAgeMs
+      )
+        continue;
+      const current = snapshot.operations.find((item) => item.id === operation.id);
+      const progress = Schema.decodeUnknownSync(RunnerProgress)(current?.result);
+      const claimed = { ...instance, role: undefined };
+      this.store.db.exec("BEGIN IMMEDIATE");
+      try {
+        this.store.put("instance", id, claimed);
+        this.store.update(operation, { result: { ...progress, instanceId: id } });
+        this.store.db.exec("COMMIT");
+      } catch (error) {
+        this.store.db.exec("ROLLBACK");
+        throw error;
+      }
+      this.ready.delete(id);
+      return { instance: claimed, connection: entry.connection };
+    }
+    return undefined;
+  }
+
+  async yieldForJob(environment: Environment) {
+    this.pending?.abort.abort();
+    await this.sweep;
+    for (const instance of this.store.snapshot().instances) {
+      if (!this.controls.admission(this.store.snapshot(), environment)) break;
+      if (this.ready.has(instance.id) || this.stopping.has(instance.id)) await this.stop(instance);
+    }
+  }
+
+  async drainEnvironment(environmentId?: string) {
+    if (!environmentId || this.pending?.environment.id === environmentId)
+      this.pending?.abort.abort();
+    for (const instance of this.store.snapshot().instances)
+      if (
+        (!environmentId || instance.environmentId === environmentId) &&
+        (this.ready.has(instance.id) || this.stopping.has(instance.id))
+      )
+        await this.stop(instance);
+  }
+
+  private stop(instance: Instance): Promise<void> {
+    const pending = this.stopping.get(instance.id);
+    if (pending) return pending;
+    this.ready.delete(instance.id);
+    const done = this.controls
+      .stop(instance)
+      .catch((error: unknown) => {
+        const current = this.store.snapshot().instances.find((item) => item.id === instance.id);
+        if (current && current.status !== "stopped")
+          this.store.put("instance", current.id, { ...current, role: undefined });
+        throw error;
+      })
+      .finally(() => this.stopping.delete(instance.id));
+    this.stopping.set(instance.id, done);
+    return done;
+  }
+
+  async close() {
+    this.closed = true;
+    this.unsubscribe?.();
+    if (this.timer) clearInterval(this.timer);
+    this.pending?.abort.abort();
+    await this.sweep;
+    await this.drainEnvironment();
+    await Promise.all(this.stopping.values());
+  }
+}
diff --git a/convex/_generated/api.d.ts b/convex/_generated/api.d.ts
index 6486965c..7a6f1fb3 100644
--- a/convex/_generated/api.d.ts
+++ b/convex/_generated/api.d.ts
@@ -28,10 +28,13 @@ import type * as githubIdentity from "../githubIdentity.js";
 import type * as githubJobs from "../githubJobs.js";
 import type * as githubMigrations from "../githubMigrations.js";
 import type * as githubOAuth from "../githubOAuth.js";
+import type * as githubRedelivery from "../githubRedelivery.js";
+import type * as githubRedeliveryState from "../githubRedeliveryState.js";
 import type * as githubRepositories from "../githubRepositories.js";
 import type * as githubRunnerProbe from "../githubRunnerProbe.js";
 import type * as githubRunners from "../githubRunners.js";
 import type * as githubRuns from "../githubRuns.js";
+import type * as githubScaleSets from "../githubScaleSets.js";
 import type * as githubValidators from "../githubValidators.js";
 import type * as githubWebhook from "../githubWebhook.js";
 import type * as http from "../http.js";
@@ -52,6 +55,8 @@ import type * as runCommands from "../runCommands.js";
 import type * as runReceipts from "../runReceipts.js";
 import type * as runnerDemand from "../runnerDemand.js";
 import type * as runnerLeases from "../runnerLeases.js";
+import type * as runnerScaleSets from "../runnerScaleSets.js";
+import type * as scaleSetPolicy from "../scaleSetPolicy.js";
 import type * as site from "../site.js";
 
 /**
@@ -78,10 +83,13 @@ declare const fullApi: ApiFromModules<{
   githubJobs: typeof githubJobs;
   githubMigrations: typeof githubMigrations;
   githubOAuth: typeof githubOAuth;
+  githubRedelivery: typeof githubRedelivery;
+  githubRedeliveryState: typeof githubRedeliveryState;
   githubRepositories: typeof githubRepositories;
   githubRunnerProbe: typeof githubRunnerProbe;
   githubRunners: typeof githubRunners;
   githubRuns: typeof githubRuns;
+  githubScaleSets: typeof githubScaleSets;
   githubValidators: typeof githubValidators;
   githubWebhook: typeof githubWebhook;
   http: typeof http;
@@ -102,6 +110,8 @@ declare const fullApi: ApiFromModules<{
   runReceipts: typeof runReceipts;
   runnerDemand: typeof runnerDemand;
   runnerLeases: typeof runnerLeases;
+  runnerScaleSets: typeof runnerScaleSets;
+  scaleSetPolicy: typeof scaleSetPolicy;
   site: typeof site;
 }>;
 export declare const api: FilterApi<
diff --git a/convex/crons.ts b/convex/crons.ts
index 4dfe5baf..48cc0251 100644
--- a/convex/crons.ts
+++ b/convex/crons.ts
@@ -2,5 +2,6 @@ import { cronJobs } from "convex/server";
 import { internal } from "./_generated/api.js";
 
 const crons = cronJobs();
+crons.interval("GitHub webhook redelivery", { minutes: 2 }, internal.githubRedelivery.scan, {});
 crons.daily("retention sweep", { hourUTC: 3, minuteUTC: 0 }, internal.retention.sweep, {});
 export default crons;
diff --git a/convex/githubAccess.ts b/convex/githubAccess.ts
index c1acf689..47b42a73 100644
--- a/convex/githubAccess.ts
+++ b/convex/githubAccess.ts
@@ -7,6 +7,8 @@ import {
   GitHubInstallationError,
   GitHubPermissionError,
   GitHubAccessError,
+  GitHubUnavailableError,
+  GitHubRateLimitError,
 } from "../packages/github/src/app-client.js";
 
 export async function repositoryAccess(
@@ -14,7 +16,7 @@ export async function repositoryAccess(
   input: Parameters<GitHubAppClient["repositoryToken"]>[0],
 ) {
   try {
-    return await client.repositoryToken(input);
+    return await githubErrors(() => client.repositoryToken(input));
   } catch (error) {
     if (
       error instanceof GitHubApprovalError ||
@@ -27,3 +29,21 @@ export async function repositoryAccess(
     throw error;
   }
 }
+
+export async function githubErrors<T>(operation: () => Promise<T>): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof GitHubUnavailableError || error instanceof GitHubRateLimitError)
+      throw new ConvexError({
+        code: error.code,
+        status: error.status,
+        message: error.message,
+        nextStep: error.nextStep,
+        ...(error instanceof GitHubRateLimitError && error.resetAt !== undefined
+          ? { resetAt: error.resetAt }
+          : {}),
+      });
+    throw error;
+  }
+}
diff --git a/convex/githubJobs.ts b/convex/githubJobs.ts
index 94f1eeea..0a718844 100644
--- a/convex/githubJobs.ts
+++ b/convex/githubJobs.ts
@@ -8,221 +8,225 @@ import { internal } from "./_generated/api.js";
 import { GitHubAppClient, GitHubApiError } from "../packages/github/src/app-client.js";
 import { scanRepositoryJobs } from "../packages/github/src/job-scan.js";
 import { GitHubJob } from "../packages/github/src/job.js";
-import { repositoryAccess } from "./githubAccess.js";
+import { githubErrors, repositoryAccess } from "./githubAccess.js";
 import { pageJobLog } from "../packages/github/src/job-logs.js";
 import { JobLogRequest, type JobLogs, type Job } from "../packages/protocol/src/jobs.js";
 
 export const refresh = action({
   args: { bindingId: v.string(), jobId: v.number() },
-  handler: async (ctx, args): Promise<Job> => {
-    if (!Number.isSafeInteger(args.jobId) || args.jobId <= 0)
-      throw new ConvexError({ code: "invalid_job_id" });
-    const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
-      bindingId: args.bindingId,
-      preparing: false,
-    });
-    if (!authority.binding.enabled) throw new ConvexError({ code: "repository_access_denied" });
-    const client = new GitHubAppClient(authority.app);
-    const access = await client.repositoryToken({
-      owner: authority.binding.repositoryOwner ?? authority.account.login,
-      repo: authority.binding.repositoryName,
-      repositoryId: authority.binding.repositoryId,
-      githubUserId: authority.account.githubId,
-      githubLogin: authority.account.login,
-      purpose: "jobs",
-    });
-    if (access.installationId !== authority.binding.installationId)
-      throw new ConvexError({ code: "installation_changed" });
-    const job = Schema.decodeUnknownSync(GitHubJob)(
-      await client
-        .request(access.token, `${access.path}/actions/jobs/${args.jobId}`)
-        .catch((error: unknown) => {
-          if (error instanceof GitHubApiError && error.status === 404)
-            throw new ConvexError({
-              code: "job_not_found",
-              message: "GitHub has no job with this ID in the repository.",
-              nextStep: "Check the job ID with vectis job list, then retry.",
-            });
-          throw error;
-        }),
-    );
-    if (job.id !== args.jobId) throw new ConvexError({ code: "job_identity_mismatch" });
-    const restrictive = await ctx.runQuery(internal.jobs.restrictiveAuthority, {
-      installationId: access.installationId,
-      repositoryId: access.repositoryId,
-    });
-    const enriched = restrictive
-      ? withRunActors(
-          job,
-          await readRunActors(
-            (path) => client.request(access.token, access.path + path),
-            access.repositoryId,
-            job.run_id,
-          ),
-        )
-      : job;
-    return ctx.runMutation(internal.jobs.save, {
-      bindingId: args.bindingId,
-      installationId: access.installationId,
-      repositoryId: access.repositoryId,
-      job: { ...enriched, labels: [...enriched.labels] },
-    });
-  },
+  handler: async (ctx, args): Promise<Job> =>
+    githubErrors(async () => {
+      if (!Number.isSafeInteger(args.jobId) || args.jobId <= 0)
+        throw new ConvexError({ code: "invalid_job_id" });
+      const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
+        bindingId: args.bindingId,
+        preparing: false,
+      });
+      if (!authority.binding.enabled) throw new ConvexError({ code: "repository_access_denied" });
+      const client = new GitHubAppClient(authority.app);
+      const access = await repositoryAccess(client, {
+        owner: authority.binding.repositoryOwner ?? authority.account.login,
+        repo: authority.binding.repositoryName,
+        repositoryId: authority.binding.repositoryId,
+        githubUserId: authority.account.githubId,
+        githubLogin: authority.account.login,
+        purpose: "jobs",
+      });
+      if (access.installationId !== authority.binding.installationId)
+        throw new ConvexError({ code: "installation_changed" });
+      const job = Schema.decodeUnknownSync(GitHubJob)(
+        await client
+          .request(access.token, `${access.path}/actions/jobs/${args.jobId}`)
+          .catch((error: unknown) => {
+            if (error instanceof GitHubApiError && error.status === 404)
+              throw new ConvexError({
+                code: "job_not_found",
+                message: "GitHub has no job with this ID in the repository.",
+                nextStep: "Check the job ID with vectis job list, then retry.",
+              });
+            throw error;
+          }),
+      );
+      if (job.id !== args.jobId) throw new ConvexError({ code: "job_identity_mismatch" });
+      const restrictive = await ctx.runQuery(internal.jobs.restrictiveAuthority, {
+        installationId: access.installationId,
+        repositoryId: access.repositoryId,
+      });
+      const enriched = restrictive
+        ? withRunActors(
+            job,
+            await readRunActors(
+              (path) => client.request(access.token, access.path + path),
+              access.repositoryId,
+              job.run_id,
+            ),
+          )
+        : job;
+      return ctx.runMutation(internal.jobs.save, {
+        bindingId: args.bindingId,
+        installationId: access.installationId,
+        repositoryId: access.repositoryId,
+        job: { ...enriched, labels: [...enriched.labels] },
+      });
+    }),
 });
 
 export const scan = action({
   args: { bindingId: v.string() },
-  handler: async (ctx, args): Promise<{ runs: number; jobs: number; complete: boolean }> => {
-    const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
-      bindingId: args.bindingId,
-      preparing: false,
-    });
-    if (!authority.binding.enabled) throw new ConvexError({ code: "repository_access_denied" });
-    const client = new GitHubAppClient(authority.app);
-    const access = await client.repositoryToken({
-      owner: authority.binding.repositoryOwner ?? authority.account.login,
-      repo: authority.binding.repositoryName,
-      repositoryId: authority.binding.repositoryId,
-      githubUserId: authority.account.githubId,
-      githubLogin: authority.account.login,
-      purpose: "jobs",
-    });
-    if (access.installationId !== authority.binding.installationId)
-      throw new ConvexError({ code: "installation_changed" });
-    const restrictive = await ctx.runQuery(internal.jobs.restrictiveAuthority, {
-      installationId: access.installationId,
-      repositoryId: access.repositoryId,
-    });
-    const known = await ctx.runQuery(internal.jobs.pendingRuns, args);
-    const result = await scanRepositoryJobs(
-      (path) => client.request(access.token, access.path + path),
-      async (jobs) => {
-        await ctx.runMutation(internal.jobs.savePage, {
-          ...args,
-          installationId: access.installationId,
-          repositoryId: access.repositoryId,
-          jobs: jobs.map((job) => ({ ...job, labels: [...job.labels] })),
-        });
-      },
-      known.runIds,
-      80,
-      restrictive ? access.repositoryId : undefined,
-    );
-    await ctx.runQuery(internal.jobs.pendingRuns, args);
-    return { ...result, complete: result.complete && known.complete };
-  },
+  handler: async (ctx, args): Promise<{ runs: number; jobs: number; complete: boolean }> =>
+    githubErrors(async () => {
+      const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
+        bindingId: args.bindingId,
+        preparing: false,
+      });
+      if (!authority.binding.enabled) throw new ConvexError({ code: "repository_access_denied" });
+      const client = new GitHubAppClient(authority.app);
+      const access = await repositoryAccess(client, {
+        owner: authority.binding.repositoryOwner ?? authority.account.login,
+        repo: authority.binding.repositoryName,
+        repositoryId: authority.binding.repositoryId,
+        githubUserId: authority.account.githubId,
+        githubLogin: authority.account.login,
+        purpose: "jobs",
+      });
+      if (access.installationId !== authority.binding.installationId)
+        throw new ConvexError({ code: "installation_changed" });
+      const restrictive = await ctx.runQuery(internal.jobs.restrictiveAuthority, {
+        installationId: access.installationId,
+        repositoryId: access.repositoryId,
+      });
+      const known = await ctx.runQuery(internal.jobs.pendingRuns, args);
+      const result = await scanRepositoryJobs(
+        (path) => client.request(access.token, access.path + path),
+        async (jobs) => {
+          await ctx.runMutation(internal.jobs.savePage, {
+            ...args,
+            installationId: access.installationId,
+            repositoryId: access.repositoryId,
+            jobs: jobs.map((job) => ({ ...job, labels: [...job.labels] })),
+          });
+        },
+        known.runIds,
+        80,
+        restrictive ? access.repositoryId : undefined,
+      );
+      await ctx.runQuery(internal.jobs.pendingRuns, args);
+      return { ...result, complete: result.complete && known.complete };
+    }),
 });
 
 export const enrichWebhook = internalAction({
   args: { installationId: v.number(), repositoryId: v.number(), job: githubJob },
-  handler: async (ctx, args) => {
-    const authority = await ctx.runQuery(internal.jobs.restrictiveAuthority, {
-      installationId: args.installationId,
-      repositoryId: args.repositoryId,
-    });
-    if (!authority) return;
-    const client = new GitHubAppClient(authority.app);
-    const access = await client.repositoryToken({
-      owner: authority.binding.repositoryOwner ?? authority.account.login,
-      repo: authority.binding.repositoryName,
-      repositoryId: args.repositoryId,
-      githubUserId: authority.account.githubId,
-      githubLogin: authority.account.login,
-      purpose: "jobs",
-    });
-    if (access.installationId !== args.installationId)
-      throw new ConvexError({ code: "installation_changed" });
-    const actors = await readRunActors(
-      (path) => client.request(access.token, access.path + path),
-      args.repositoryId,
-      args.job.run_id,
-    );
-    const job = withRunActors(args.job, actors);
-    await ctx.runMutation(internal.jobs.saveWebhookActors, {
-      ...args,
-      job: { ...job, labels: [...job.labels] },
-    });
-  },
+  handler: async (ctx, args) =>
+    githubErrors(async () => {
+      const authority = await ctx.runQuery(internal.jobs.restrictiveAuthority, {
+        installationId: args.installationId,
+        repositoryId: args.repositoryId,
+      });
+      if (!authority) return;
+      const client = new GitHubAppClient(authority.app);
+      const access = await repositoryAccess(client, {
+        owner: authority.binding.repositoryOwner ?? authority.account.login,
+        repo: authority.binding.repositoryName,
+        repositoryId: args.repositoryId,
+        githubUserId: authority.account.githubId,
+        githubLogin: authority.account.login,
+        purpose: "jobs",
+      });
+      if (access.installationId !== args.installationId)
+        throw new ConvexError({ code: "installation_changed" });
+      const actors = await readRunActors(
+        (path) => client.request(access.token, access.path + path),
+        args.repositoryId,
+        args.job.run_id,
+      );
+      const job = withRunActors(args.job, actors);
+      await ctx.runMutation(internal.jobs.saveWebhookActors, {
+        ...args,
+        job: { ...job, labels: [...job.labels] },
+      });
+    }),
 });
 
 export const logs = action({
   args: { bindingId: v.string(), jobId: v.number(), after: v.optional(v.number()) },
-  handler: async (ctx, args): Promise<JobLogs> => {
-    if (!Schema.is(JobLogRequest)(args))
-      throw new ConvexError({
-        code: "invalid_job_log_request",
-        message: "Provide a positive job ID and a nonnegative safe integer byte cursor.",
-        nextStep: "Pass the previous next cursor as after.",
-      });
-    const authorize = async () => {
-      const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
-        bindingId: args.bindingId,
-        preparing: false,
-      });
-      if (!authority.binding.enabled)
+  handler: async (ctx, args): Promise<JobLogs> =>
+    githubErrors(async () => {
+      if (!Schema.is(JobLogRequest)(args))
         throw new ConvexError({
-          code: "repository_access_denied",
-          message: "Repository access is disabled.",
-          nextStep: "Check the repository binding.",
+          code: "invalid_job_log_request",
+          message: "Provide a positive job ID and a nonnegative safe integer byte cursor.",
+          nextStep: "Pass the previous next cursor as after.",
         });
-      return authority;
-    };
-    const authority = await authorize();
-    const client = new GitHubAppClient(authority.app);
-    const access = await repositoryAccess(client, {
-      owner: authority.binding.repositoryOwner ?? authority.account.login,
-      repo: authority.binding.repositoryName,
-      repositoryId: authority.binding.repositoryId,
-      githubUserId: authority.account.githubId,
-      githubLogin: authority.account.login,
-      purpose: "jobs",
-    });
-    if (access.installationId !== authority.binding.installationId)
-      throw new ConvexError({
-        code: "installation_changed",
-        message: "The repository installation changed.",
-        nextStep: "Reconnect the repository binding.",
-      });
-    const job = Schema.decodeUnknownSync(GitHubJob)(
-      await client.request(access.token, `${access.path}/actions/jobs/${args.jobId}`),
-    );
-    if (job.id !== args.jobId) throw new ConvexError({ code: "job_identity_mismatch" });
-    const run = Schema.decodeUnknownSync(
-      Schema.Struct({ id: Schema.Int, repository: Schema.Struct({ id: Schema.Int }) }),
-    )(await client.request(access.token, `${access.path}/actions/runs/${job.run_id}`));
-    if (run.id !== job.run_id || run.repository.id !== access.repositoryId)
-      throw new ConvexError({
-        code: "repository_access_denied",
-        message: "The job belongs to another repository.",
-        nextStep: "Use the binding for this job's repository.",
+      const authorize = async () => {
+        const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
+          bindingId: args.bindingId,
+          preparing: false,
+        });
+        if (!authority.binding.enabled)
+          throw new ConvexError({
+            code: "repository_access_denied",
+            message: "Repository access is disabled.",
+            nextStep: "Check the repository binding.",
+          });
+        return authority;
+      };
+      const authority = await authorize();
+      const client = new GitHubAppClient(authority.app);
+      const access = await repositoryAccess(client, {
+        owner: authority.binding.repositoryOwner ?? authority.account.login,
+        repo: authority.binding.repositoryName,
+        repositoryId: authority.binding.repositoryId,
+        githubUserId: authority.account.githubId,
+        githubLogin: authority.account.login,
+        purpose: "jobs",
       });
-    const status = job.status === "requested" || job.status === "pending" ? "queued" : job.status;
-    let result: JobLogs;
-    try {
-      const log = await client.downloadJobLog(
-        access.token,
-        `${access.path}/actions/jobs/${args.jobId}/logs`,
-        args.after,
+      if (access.installationId !== authority.binding.installationId)
+        throw new ConvexError({
+          code: "installation_changed",
+          message: "The repository installation changed.",
+          nextStep: "Reconnect the repository binding.",
+        });
+      const job = Schema.decodeUnknownSync(GitHubJob)(
+        await client.request(access.token, `${access.path}/actions/jobs/${args.jobId}`),
       );
-      result = pageJobLog(log, status, args.after);
-    } catch (error) {
-      if (error instanceof GitHubApiError && error.status === 404 && status !== "completed")
-        result = { text: "", next: args.after ?? 0, status, complete: false, truncated: false };
-      else
+      if (job.id !== args.jobId) throw new ConvexError({ code: "job_identity_mismatch" });
+      const run = Schema.decodeUnknownSync(
+        Schema.Struct({ id: Schema.Int, repository: Schema.Struct({ id: Schema.Int }) }),
+      )(await client.request(access.token, `${access.path}/actions/runs/${job.run_id}`));
+      if (run.id !== job.run_id || run.repository.id !== access.repositoryId)
         throw new ConvexError({
-          code: "job_logs_unavailable",
-          message: "GitHub job logs could not be downloaded.",
-          nextStep:
-            "Retry when GitHub makes the log available; logs may have expired or exceeded the 64 MiB download limit.",
+          code: "repository_access_denied",
+          message: "The job belongs to another repository.",
+          nextStep: "Use the binding for this job's repository.",
         });
-    }
-    const current = await authorize();
-    if (
-      current.binding.repositoryId !== access.repositoryId ||
-      current.binding.installationId !== access.installationId ||
-      current.binding.accountId !== authority.binding.accountId
-    )
-      throw new ConvexError({ code: "repository_access_denied" });
-    return result;
-  },
+      const status = job.status === "requested" || job.status === "pending" ? "queued" : job.status;
+      let result: JobLogs;
+      try {
+        const log = await client.downloadJobLog(
+          access.token,
+          `${access.path}/actions/jobs/${args.jobId}/logs`,
+          args.after,
+        );
+        result = pageJobLog(log, status, args.after);
+      } catch (error) {
+        if (error instanceof GitHubApiError && error.status === 404 && status !== "completed")
+          result = { text: "", next: args.after ?? 0, status, complete: false, truncated: false };
+        else
+          throw new ConvexError({
+            code: "job_logs_unavailable",
+            message: "GitHub job logs could not be downloaded.",
+            nextStep:
+              "Retry when GitHub makes the log available; logs may have expired or exceeded the 64 MiB download limit.",
+          });
+      }
+      const current = await authorize();
+      if (
+        current.binding.repositoryId !== access.repositoryId ||
+        current.binding.installationId !== access.installationId ||
+        current.binding.accountId !== authority.binding.accountId
+      )
+        throw new ConvexError({ code: "repository_access_denied" });
+      return result;
+    }),
 });
diff --git a/convex/githubMigrations.ts b/convex/githubMigrations.ts
index 168a92bd..3afc94e4 100644
--- a/convex/githubMigrations.ts
+++ b/convex/githubMigrations.ts
@@ -1,5 +1,5 @@
 "use node";
-import { repositoryAccess } from "./githubAccess.js";
+import { githubErrors, repositoryAccess } from "./githubAccess.js";
 import { ConvexError, v } from "convex/values";
 import { Schema } from "effect";
 import { action } from "./_generated/server.js";
@@ -16,58 +16,59 @@ import {
 
 export const analyze = action({
   args: { bindingId: v.string() },
-  handler: async (ctx, args): Promise<MigrationAnalysis> => {
-    const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
-      ...args,
-      preparing: true,
-    });
-    if (!authority.environment) throw new ConvexError({ code: "environment_unavailable" });
-    const environment = authority.environment;
-    const client = new GitHubAppClient(authority.app);
-    const access = await repositoryAccess(client, {
-      owner: authority.binding.repositoryOwner ?? authority.account.login,
-      repo: authority.binding.repositoryName,
-      repositoryId: authority.binding.repositoryId,
-      githubUserId: authority.account.githubId,
-      githubLogin: authority.account.login,
-      purpose: "migration-read",
-    });
-    if (access.installationId !== authority.binding.installationId)
-      throw new ConvexError({ code: "installation_changed" });
-    const source = await readRepositoryWorkflows(
-      (path) => client.request(access.token, access.path + path),
-      access.repositoryId,
-    );
-    const labels =
-      environment.os === "linux"
-        ? ["ubuntu-24.04-arm", "ubuntu-24.04", "ubuntu-latest"]
-        : environment.os === "windows"
-          ? ["windows-11-arm", "windows-latest", "windows-2025", "windows-2022"]
-          : ["macos-26", "macos-latest"];
-    const targets = labels.map((from) => ({ from, to: `vectis-${environment.id}` }));
-    const report = {
-      baseBranch: source.baseBranch,
-      baseCommit: source.baseCommit,
-      files: source.files.map((file) => {
-        const preview = previewMigration(file.source, targets);
-        return {
-          path: file.path,
-          mode: file.mode,
-          before: file.source,
-          after: preview.source,
-          changed: preview.changed,
-          findings: [...preview.findings],
-          ...(preview.jobs ? { jobs: [...preview.jobs] } : {}),
-        };
-      }),
-    };
-    const verified = await ctx.runQuery(internal.migrationPreviews.verified, args);
-    const previewId = await ctx.runMutation(internal.migrationPreviews.save, {
-      ...args,
-      reportJson: JSON.stringify(report),
-    });
-    return { previewId, verified, ...report };
-  },
+  handler: async (ctx, args): Promise<MigrationAnalysis> =>
+    githubErrors(async () => {
+      const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
+        ...args,
+        preparing: true,
+      });
+      if (!authority.environment) throw new ConvexError({ code: "environment_unavailable" });
+      const environment = authority.environment;
+      const client = new GitHubAppClient(authority.app);
+      const access = await repositoryAccess(client, {
+        owner: authority.binding.repositoryOwner ?? authority.account.login,
+        repo: authority.binding.repositoryName,
+        repositoryId: authority.binding.repositoryId,
+        githubUserId: authority.account.githubId,
+        githubLogin: authority.account.login,
+        purpose: "migration-read",
+      });
+      if (access.installationId !== authority.binding.installationId)
+        throw new ConvexError({ code: "installation_changed" });
+      const source = await readRepositoryWorkflows(
+        (path) => client.request(access.token, access.path + path),
+        access.repositoryId,
+      );
+      const labels =
+        environment.os === "linux"
+          ? ["ubuntu-24.04-arm", "ubuntu-24.04", "ubuntu-latest"]
+          : environment.os === "windows"
+            ? ["windows-11-arm", "windows-latest", "windows-2025", "windows-2022"]
+            : ["macos-26", "macos-latest"];
+      const targets = labels.map((from) => ({ from, to: `vectis-${environment.id}` }));
+      const report = {
+        baseBranch: source.baseBranch,
+        baseCommit: source.baseCommit,
+        files: source.files.map((file) => {
+          const preview = previewMigration(file.source, targets);
+          return {
+            path: file.path,
+            mode: file.mode,
+            before: file.source,
+            after: preview.source,
+            changed: preview.changed,
+            findings: [...preview.findings],
+            ...(preview.jobs ? { jobs: [...preview.jobs] } : {}),
+          };
+        }),
+      };
+      const verified = await ctx.runQuery(internal.migrationPreviews.verified, args);
+      const previewId = await ctx.runMutation(internal.migrationPreviews.save, {
+        ...args,
+        reportJson: JSON.stringify(report),
+      });
+      return { previewId, verified, ...report };
+    }),
 });
 export const publish = action({
   args: { previewId: v.string() },
diff --git a/convex/githubRedelivery.ts b/convex/githubRedelivery.ts
new file mode 100644
index 00000000..8b4ba49d
--- /dev/null
+++ b/convex/githubRedelivery.ts
@@ -0,0 +1,144 @@
+"use node";
+import { Schema } from "effect";
+import { createGitHubAppJwt, GitHubApiError } from "../packages/github/src/app-client.js";
+import { internal } from "./_generated/api.js";
+import { internalAction } from "./_generated/server.js";
+
+const minute = 60_000;
+const maxAge = 3 * 24 * 60 * minute;
+const events = new Set(["workflow_job", "installation", "installation_repositories", "repository"]);
+const deliveries = Schema.Array(
+  Schema.Struct({
+    id: Schema.String.check(Schema.isPattern(/^\d{1,30}$/)),
+    guid: Schema.NonEmptyString,
+    delivered_at: Schema.String,
+    status_code: Schema.NullOr(Schema.Int),
+    event: Schema.String,
+  }),
+);
+
+function nextCursor(link: string | null) {
+  if (!link) return null;
+  for (const part of link.split(",")) {
+    const match = part.match(/<([^>]+)>;\s*rel="next"/);
+    const url = match?.[1];
+    if (url) {
+      const cursor = new URL(url).searchParams.get("cursor");
+      if (!cursor) throw new Error("GitHub delivery pagination is missing its cursor.");
+      return cursor;
+    }
+  }
+  return null;
+}
+
+export const scan = internalAction({
+  args: {},
+  handler: async (ctx): Promise<void> => {
+    const state = await ctx.runQuery(internal.githubRedeliveryState.load, {});
+    if (!state) return;
+    const now = Date.now();
+    const since = Math.max(state.checkpoint?.deliveredAt ?? now - 60 * minute, now - maxAge);
+    const through = now - minute;
+    const deadline = now + 90_000;
+    const signal = AbortSignal.timeout(90_000);
+    const headers = {
+      Authorization: `Bearer ${createGitHubAppJwt(state.app)}`,
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2026-03-10",
+    };
+    const request = async (path: string, method: "GET" | "POST") => {
+      const response = await fetch(`https://api.github.com${path}`, {
+        method,
+        headers,
+        redirect: "error",
+        signal: AbortSignal.any([signal, AbortSignal.timeout(10_000)]),
+      });
+      if (!response.ok) {
+        await response.body?.cancel();
+        throw new GitHubApiError(response.status);
+      }
+      return response;
+    };
+
+    const attempts = new Map<string, { id: string; deliveredAt: number; successful: boolean }>();
+    let complete = false;
+    let cursor: string | null = null;
+    try {
+      for (let page = 0; page < 10; page++) {
+        const params = new URLSearchParams({ per_page: "100" });
+        if (cursor) params.set("cursor", cursor);
+        const response = await request(`/app/hook/deliveries?${params}`, "GET");
+        // Delivery IDs exceed Number.MAX_SAFE_INTEGER, so they must stay strings.
+        const text = (await response.text()).replace(/"id":\s*(\d+)/g, '"id":"$1"');
+        const rows = Schema.decodeUnknownSync(deliveries)(JSON.parse(text));
+        if (rows.length > 100) throw new Error("GitHub exceeded the delivery page limit.");
+        for (const row of rows) {
+          const deliveredAt = Date.parse(row.delivered_at);
+          if (!Number.isFinite(deliveredAt)) throw new Error("Invalid GitHub delivery timestamp.");
+          if (deliveredAt < since) {
+            complete = true;
+            break;
+          }
+          if (!events.has(row.event)) continue;
+          const successful =
+            row.status_code !== null && row.status_code >= 200 && row.status_code < 300;
+          const existing = attempts.get(row.guid);
+          if (!existing || deliveredAt > existing.deliveredAt)
+            attempts.set(row.guid, {
+              id: row.id,
+              deliveredAt,
+              successful: successful || existing?.successful === true,
+            });
+          else existing.successful ||= successful;
+        }
+        cursor = nextCursor(response.headers.get("link"));
+        if (complete || !cursor || rows.length === 0) {
+          complete = true;
+          break;
+        }
+      }
+    } catch (error) {
+      console.warn("GitHub webhook delivery listing failed; checkpoint unchanged.", String(error));
+      return;
+    }
+    if (!complete) {
+      console.warn("GitHub webhook delivery page limit reached; checkpoint unchanged.");
+      return;
+    }
+
+    const candidates = [...attempts.entries()]
+      .filter(([, attempt]) => !attempt.successful && attempt.deliveredAt <= through)
+      .sort((a, b) => a[1].deliveredAt - b[1].deliveredAt);
+    let requested = 0;
+    for (const [guid, attempt] of candidates) {
+      if (requested >= 20 || Date.now() >= deadline || signal.aborted) {
+        complete = false;
+        break;
+      }
+      if (!(await ctx.runMutation(internal.githubRedeliveryState.claim, { guid }))) continue;
+      requested++;
+      try {
+        const response = await request(`/app/hook/deliveries/${attempt.id}/attempts`, "POST");
+        await response.body?.cancel();
+      } catch (error) {
+        console.warn("GitHub webhook redelivery request failed; it will not be repeated.", {
+          guid,
+          deliveryId: attempt.id,
+          error,
+        });
+        complete = false;
+        break;
+      }
+    }
+    if (!complete) {
+      console.warn("GitHub webhook redelivery scan incomplete; checkpoint unchanged.");
+      return;
+    }
+    // Fresh attempts remain in the next scan, even when this run saw newer successful deliveries.
+    await ctx.runMutation(internal.githubRedeliveryState.advance, {
+      id: state.checkpoint?._id ?? null,
+      deliveredAt: through,
+      scannedAt: now,
+    });
+  },
+});
diff --git a/convex/githubRedeliveryState.ts b/convex/githubRedeliveryState.ts
new file mode 100644
index 00000000..9b49d15a
--- /dev/null
+++ b/convex/githubRedeliveryState.ts
@@ -0,0 +1,47 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery } from "./_generated/server.js";
+
+export const load = internalQuery({
+  args: {},
+  handler: async (ctx) => {
+    const app = await ctx.db.query("githubApps").first();
+    if (!app) return null;
+    return {
+      app: { clientId: app.clientId, privateKey: app.privateKey },
+      checkpoint: await ctx.db.query("githubRedeliveryCheckpoint").first(),
+    };
+  },
+});
+
+export const advance = internalMutation({
+  args: {
+    id: v.union(v.id("githubRedeliveryCheckpoint"), v.null()),
+    deliveredAt: v.number(),
+    scannedAt: v.number(),
+  },
+  handler: async (ctx, { id, ...checkpoint }) => {
+    if (id) {
+      await ctx.db.patch("githubRedeliveryCheckpoint", id, checkpoint);
+      return;
+    }
+    const existing = await ctx.db.query("githubRedeliveryCheckpoint").first();
+    if (existing) {
+      if (existing.deliveredAt < checkpoint.deliveredAt)
+        await ctx.db.patch("githubRedeliveryCheckpoint", existing._id, checkpoint);
+    } else await ctx.db.insert("githubRedeliveryCheckpoint", checkpoint);
+  },
+});
+
+export const claim = internalMutation({
+  args: { guid: v.string() },
+  handler: async (ctx, { guid }) => {
+    const existing = await ctx.db
+      .query("githubRedeliveryRequests")
+      .withIndex("by_guid", (q) => q.eq("guid", guid))
+      .unique();
+    if (existing) return false;
+    // Reserve before POST: a timeout may still mean GitHub accepted the request.
+    await ctx.db.insert("githubRedeliveryRequests", { guid, requestedAt: Date.now() });
+    return true;
+  },
+});
diff --git a/convex/githubRepositories.ts b/convex/githubRepositories.ts
index 7bb8b598..cb629288 100644
--- a/convex/githubRepositories.ts
+++ b/convex/githubRepositories.ts
@@ -195,6 +195,7 @@ export const readiness = action({
       };
     return {
       checks,
+      cacheVolumeEnabled: binding?.enabled === true && binding.cacheVolumeEnabled,
       ...(authority.environmentId ? { environmentId: authority.environmentId } : {}),
     };
   },
diff --git a/convex/githubRunners.ts b/convex/githubRunners.ts
index b60ca508..51c83298 100644
--- a/convex/githubRunners.ts
+++ b/convex/githubRunners.ts
@@ -1,6 +1,8 @@
 "use node";
+import { readCacheWrite } from "../packages/github/src/cache-write.js";
+import { generateScaleSetJit } from "./githubScaleSets.js";
 import { runnerRequest } from "./runnerLeases.js";
-import { repositoryAccess } from "./githubAccess.js";
+import { githubErrors, repositoryAccess } from "./githubAccess.js";
 import { runnerLabels } from "../packages/github/src/runner-labels.js";
 import { ConvexError, v } from "convex/values";
 import { Schema } from "effect";
@@ -28,6 +30,7 @@ export const prepare = action({
       preparing: true,
       ...(args.jobId === undefined ? {} : { jobId: args.jobId }),
       ...(args.automatic === undefined ? {} : { automatic: args.automatic }),
+      ...(args.scaleSet ? { scaleSet: args.scaleSet } : {}),
     });
     const client = new GitHubAppClient(authority.app);
     const access = await repositoryAccess(client, {
@@ -55,9 +58,18 @@ export const prepare = action({
           id: lease._id,
           runnerId: lease.runnerId,
           encodedConfig: lease.encodedConfig,
+          cacheWrite: lease.cacheWrite ?? false,
+          ...(lease.cacheWriteReason ? { cacheWriteReason: lease.cacheWriteReason } : {}),
           environmentId: lease.environmentId,
           os: lease.os,
-          ...(lease.access ? { access: lease.access } : {}),
+          ...(lease.access
+            ? {
+                access: {
+                  ...lease.access,
+                  ...(lease.cacheRun ? { cacheRun: lease.cacheRun } : {}),
+                },
+              }
+            : {}),
         };
       if (lease.phase === "released") return { state: "released", id: lease._id };
       if (lease.phase === "preparing" && Date.now() - lease.updatedAt < 60000)
@@ -65,32 +77,98 @@ export const prepare = action({
       await ctx.runMutation(internal.runnerLeases.attention, { id: lease._id });
       return { state: "action_required", id: lease._id };
     }
+    const cacheJob = authority.cacheJob;
+    const cache =
+      !args.scaleSet && cacheJob
+        ? await (async () => {
+            try {
+              const jobs = await repositoryAccess(client, {
+                owner: authority.binding.repositoryOwner ?? authority.account.login,
+                repo: authority.binding.repositoryName,
+                repositoryId: authority.binding.repositoryId,
+                githubUserId: authority.account.githubId,
+                githubLogin: authority.account.login,
+                purpose: "jobs",
+              });
+              if (jobs.installationId !== access.installationId)
+                return { cacheWrite: false, cacheWriteReason: "installation_changed" };
+              return await readCacheWrite(
+                (path) => client.request(jobs.token, jobs.path + path),
+                authority.binding.repositoryId,
+                cacheJob.runId,
+                cacheJob.runAttempt,
+              );
+            } catch {
+              return { cacheWrite: false, cacheWriteReason: "metadata_unavailable" };
+            }
+          })()
+        : {
+            cacheWrite: false,
+            cacheWriteReason: args.scaleSet
+              ? "scale_set_run_unknown"
+              : authority.binding.cacheVolume?.enabled
+                ? "job_unknown"
+                : "cache_disabled",
+          };
     let runnerId: number | undefined;
     try {
-      const registration = Schema.decodeUnknownSync(Registration)(
-        await client.request(access.token, `${access.path}/actions/runners/generate-jitconfig`, {
-          name: `vectis-${lease._id}`,
-          runner_group_id: 1,
-          labels: runnerLabels(lease.os, lease.environmentId),
-          work_folder: "_work",
-        }),
-      );
+      const scaleSetRegistration = args.scaleSet
+        ? await generateScaleSetJit(
+            ctx,
+            {
+              bindingId: args.bindingId,
+              generation: args.scaleSet.generation,
+              runnerName: `vectis-${lease._id}`,
+            },
+            authority,
+            access,
+          )
+        : undefined;
+      const registration = scaleSetRegistration
+        ? {
+            runner: scaleSetRegistration.runner,
+            encoded_jit_config: scaleSetRegistration.encodedJITConfig,
+          }
+        : Schema.decodeUnknownSync(Registration)(
+            await client.request(
+              access.token,
+              `${access.path}/actions/runners/generate-jitconfig`,
+              {
+                name: `vectis-${lease._id}`,
+                runner_group_id: 1,
+                labels: runnerLabels(lease.os, lease.environmentId),
+                work_folder: "_work",
+              },
+            ),
+          );
       runnerId = registration.runner.id;
       if (registration.runner.name !== `vectis-${lease._id}`)
         throw new Error("Runner identity mismatch.");
+      if (args.scaleSet) {
+        const registered = Schema.decodeUnknownSync(Runner)(
+          await client.request(access.token, `${access.path}/actions/runners/${runnerId}`),
+        );
+        if (registered.id !== runnerId || registered.name !== `vectis-${lease._id}`)
+          throw new Error("Runner identity mismatch.");
+      }
       await ctx.runMutation(internal.runnerLeases.ready, {
         id: lease._id,
         runnerId,
         encodedConfig: registration.encoded_jit_config,
+        ...cache,
       });
       return {
         state: "ready",
         id: lease._id,
         runnerId,
         encodedConfig: registration.encoded_jit_config,
+        cacheWrite: cache.cacheWrite,
+        ...(cache.cacheWriteReason ? { cacheWriteReason: cache.cacheWriteReason } : {}),
         environmentId: lease.environmentId,
         os: lease.os,
-        ...(lease.access ? { access: lease.access } : {}),
+        ...(lease.access
+          ? { access: { ...lease.access, ...(cache.cacheRun ? { cacheRun: cache.cacheRun } : {}) } }
+          : {}),
       };
     } catch {
       await ctx.runMutation(internal.runnerLeases.attention, {
@@ -104,113 +182,115 @@ export const prepare = action({
 
 export const release = action({
   args: { id: v.string() },
-  handler: async (ctx, args): Promise<{ state: "released"; id: string }> => {
-    const lease = await ctx.runQuery(internal.runnerLeases.owned, args);
-    if (lease.phase === "released") return { state: "released", id: lease._id };
-    if (lease.phase === "preparing" && Date.now() - lease.updatedAt < 60000)
-      throw new ConvexError({
-        code: "runner_lease_pending",
-        nextStep: "Wait for registration to finish before reconciling this lease.",
+  handler: async (ctx, args): Promise<{ state: "released"; id: string }> =>
+    githubErrors(async () => {
+      const lease = await ctx.runQuery(internal.runnerLeases.owned, args);
+      if (lease.phase === "released") return { state: "released", id: lease._id };
+      if (lease.phase === "preparing" && Date.now() - lease.updatedAt < 60000)
+        throw new ConvexError({
+          code: "runner_lease_pending",
+          nextStep: "Wait for registration to finish before reconciling this lease.",
+        });
+      const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
+        bindingId: lease.bindingId,
+        preparing: false,
       });
-    const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
-      bindingId: lease.bindingId,
-      preparing: false,
-    });
-    const client = new GitHubAppClient(authority.app);
-    const access = await repositoryAccess(client, {
-      owner: authority.binding.repositoryOwner ?? authority.account.login,
-      repo: authority.binding.repositoryName,
-      repositoryId: authority.binding.repositoryId,
-      githubUserId: authority.account.githubId,
-      githubLogin: authority.account.login,
-      purpose: "cleanup",
-    });
-    const expectedName = `vectis-${lease._id}`;
-    let runnerId = lease.runnerId;
-    if (runnerId === undefined) {
-      let searched = false;
-      for (let page = 1; page <= 10; page++) {
-        const pool = Schema.decodeUnknownSync(Pool)(
-          await client.request(
-            access.token,
-            `${access.path}/actions/runners?per_page=100&page=${page}`,
-          ),
-        );
-        const matches = pool.runners.filter((runner) => runner.name === expectedName);
-        if (matches.length > 1) throw new ConvexError({ code: "runner_identity_conflict" });
-        if (matches[0]) {
-          runnerId = matches[0].id;
-          searched = true;
-          break;
-        }
-        if (page * 100 >= pool.total_count) {
-          searched = true;
-          break;
+      const client = new GitHubAppClient(authority.app);
+      const access = await repositoryAccess(client, {
+        owner: authority.binding.repositoryOwner ?? authority.account.login,
+        repo: authority.binding.repositoryName,
+        repositoryId: authority.binding.repositoryId,
+        githubUserId: authority.account.githubId,
+        githubLogin: authority.account.login,
+        purpose: "cleanup",
+      });
+      const expectedName = `vectis-${lease._id}`;
+      let runnerId = lease.runnerId;
+      if (runnerId === undefined) {
+        let searched = false;
+        for (let page = 1; page <= 10; page++) {
+          const pool = Schema.decodeUnknownSync(Pool)(
+            await client.request(
+              access.token,
+              `${access.path}/actions/runners?per_page=100&page=${page}`,
+            ),
+          );
+          const matches = pool.runners.filter((runner) => runner.name === expectedName);
+          if (matches.length > 1) throw new ConvexError({ code: "runner_identity_conflict" });
+          if (matches[0]) {
+            runnerId = matches[0].id;
+            searched = true;
+            break;
+          }
+          if (page * 100 >= pool.total_count) {
+            searched = true;
+            break;
+          }
         }
+        if (!searched)
+          throw new ConvexError({
+            code: "runner_reconciliation_limit",
+            nextStep: "Inspect the repository runner pool before retrying cleanup.",
+          });
       }
-      if (!searched)
-        throw new ConvexError({
-          code: "runner_reconciliation_limit",
-          nextStep: "Inspect the repository runner pool before retrying cleanup.",
-        });
-    }
-    if (runnerId !== undefined) {
-      const path = `${access.path}/actions/runners/${runnerId}`;
-      try {
-        const runner = Schema.decodeUnknownSync(Runner)(await client.request(access.token, path));
-        if (runner.id !== runnerId || runner.name !== expectedName)
-          throw new ConvexError({ code: "runner_identity_conflict" });
+      if (runnerId !== undefined) {
+        const path = `${access.path}/actions/runners/${runnerId}`;
         try {
-          await client.delete(access.token, path);
+          const runner = Schema.decodeUnknownSync(Runner)(await client.request(access.token, path));
+          if (runner.id !== runnerId || runner.name !== expectedName)
+            throw new ConvexError({ code: "runner_identity_conflict" });
+          try {
+            await client.delete(access.token, path);
+          } catch (error) {
+            if (error instanceof GitHubApiError && error.status === 422)
+              throw new ConvexError({
+                code: "runner_busy",
+                message: "GitHub still shows this runner on a job.",
+                nextStep:
+                  "Vectis retries cleanup automatically after GitHub releases the job, usually within 15 minutes.",
+              });
+            throw error;
+          }
         } catch (error) {
-          if (error instanceof GitHubApiError && error.status === 422)
-            throw new ConvexError({
-              code: "runner_busy",
-              message: "GitHub still shows this runner on a job.",
-              nextStep:
-                "Vectis retries cleanup automatically after GitHub releases the job, usually within 15 minutes.",
-            });
-          throw error;
+          if (!(error instanceof GitHubApiError && error.status === 404)) throw error;
         }
-      } catch (error) {
-        if (!(error instanceof GitHubApiError && error.status === 404)) throw error;
       }
-    }
-    await ctx.runMutation(internal.runnerLeases.released, { id: lease._id });
-    return { state: "released", id: lease._id };
-  },
+      await ctx.runMutation(internal.runnerLeases.released, { id: lease._id });
+      return { state: "released", id: lease._id };
+    }),
 });
 
 export const status = action({
   args: { id: v.string() },
-  handler: async (ctx, args): Promise<RunnerStatus> => {
-    const lease = await ctx.runQuery(internal.runnerLeases.owned, args);
-    const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
-      bindingId: lease.bindingId,
-      preparing: false,
-    });
-    if (lease.phase === "released") return { missing: true };
-    if (lease.runnerId === undefined)
-      throw new ConvexError({ code: "runner_registration_incomplete" });
-    const client = new GitHubAppClient(authority.app);
-    const access = await repositoryAccess(client, {
-      owner: authority.binding.repositoryOwner ?? authority.account.login,
-      repo: authority.binding.repositoryName,
-      repositoryId: authority.binding.repositoryId,
-      githubUserId: authority.account.githubId,
-      githubLogin: authority.account.login,
-      purpose: "cleanup",
-    });
-    try {
-      const runner = Schema.decodeUnknownSync(RunnerState)(
-        await client.request(access.token, `${access.path}/actions/runners/${lease.runnerId}`),
-      );
-      if (runner.id !== lease.runnerId || runner.name !== `vectis-${lease._id}`)
-        throw new ConvexError({ code: "runner_identity_conflict" });
-      return { busy: runner.busy, status: runner.status };
-    } catch (error) {
-      if (error instanceof GitHubApiError && error.status === 404) return { missing: true };
-      throw error;
-    }
-  },
+  handler: async (ctx, args): Promise<RunnerStatus> =>
+    githubErrors(async () => {
+      const lease = await ctx.runQuery(internal.runnerLeases.owned, args);
+      const authority = await ctx.runQuery(internal.runnerLeases.authorize, {
+        bindingId: lease.bindingId,
+        preparing: false,
+      });
+      if (lease.phase === "released") return { missing: true };
+      if (lease.runnerId === undefined)
+        throw new ConvexError({ code: "runner_registration_incomplete" });
+      const client = new GitHubAppClient(authority.app);
+      const access = await repositoryAccess(client, {
+        owner: authority.binding.repositoryOwner ?? authority.account.login,
+        repo: authority.binding.repositoryName,
+        repositoryId: authority.binding.repositoryId,
+        githubUserId: authority.account.githubId,
+        githubLogin: authority.account.login,
+        purpose: "cleanup",
+      });
+      try {
+        const runner = Schema.decodeUnknownSync(RunnerState)(
+          await client.request(access.token, `${access.path}/actions/runners/${lease.runnerId}`),
+        );
+        if (runner.id !== lease.runnerId || runner.name !== `vectis-${lease._id}`)
+          throw new ConvexError({ code: "runner_identity_conflict" });
+        return { busy: runner.busy, status: runner.status };
+      } catch (error) {
+        if (error instanceof GitHubApiError && error.status === 404) return { missing: true };
+        throw error;
+      }
+    }),
 });
diff --git a/convex/githubRuns.ts b/convex/githubRuns.ts
index f0c9b579..f0b864ef 100644
--- a/convex/githubRuns.ts
+++ b/convex/githubRuns.ts
@@ -10,6 +10,9 @@ import {
   GitHubAppClient,
   GitHubApiError,
   GitHubPermissionError,
+  GitHubUnavailableError,
+  GitHubRateLimitError,
+  GitHubUncertainError,
 } from "../packages/github/src/app-client.js";
 import { RunControlCommand, RunControlOutcome } from "../packages/protocol/src/runs.js";
 
@@ -281,6 +284,9 @@ export const control = action({
     } catch (error) {
       if (acceptedOutcome) outcome = acceptedOutcome;
       else if (responseReceived) outcome = unconfirmedRunCommand(command);
+      else if (error instanceof GitHubUncertainError) outcome = unconfirmedRunCommand(command);
+      else if (error instanceof GitHubUnavailableError || error instanceof GitHubRateLimitError)
+        outcome = rejected(error.code, error.message, error.nextStep);
       else if (error instanceof GitHubPermissionError)
         outcome = rejected(error.code, error.message, error.nextStep);
       else if (
diff --git a/convex/githubScaleSets.ts b/convex/githubScaleSets.ts
new file mode 100644
index 00000000..efd28160
--- /dev/null
+++ b/convex/githubScaleSets.ts
@@ -0,0 +1,310 @@
+"use node";
+import { ConvexError, v } from "convex/values";
+import { action, internalAction, type ActionCtx } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import type { Doc } from "./_generated/dataModel.js";
+import type { ScaleSetGrant } from "../packages/protocol/src/scale-sets.js";
+import { GitHubAppClient } from "../packages/github/src/app-client.js";
+import { runnerLabels } from "../packages/github/src/runner-labels.js";
+import {
+  bootstrapAdmin,
+  ScaleSetBootstrapHttpError,
+  tokenExpiration,
+} from "../packages/scaleset/src/bootstrap.js";
+import { ScaleSetAdminClient, ScaleSetHttpError } from "../packages/scaleset/src/client.js";
+import type { Session } from "../packages/scaleset/src/messages.js";
+import { repositoryAccess } from "./githubAccess.js";
+
+type Authority = {
+  binding: Doc<"repositoryBindings">;
+  account: Doc<"githubAccounts">;
+};
+type Access = { token: string };
+
+// Admin credentials are short lived and stay inside this action invocation.
+async function admin(authority: Authority, access: Access, signal: AbortSignal) {
+  const connection = await bootstrapAdmin(
+    {
+      owner: authority.binding.repositoryOwner ?? authority.account.login,
+      repo: authority.binding.repositoryName,
+      installationToken: access.token,
+    },
+    (url, init) => fetch(url, init),
+    signal,
+  );
+  return new ScaleSetAdminClient(connection.serviceUrl, connection.adminToken, (url, init) =>
+    fetch(url, init),
+  );
+}
+
+async function connection(
+  ctx: ActionCtx,
+  bindingId: string,
+  preparing: boolean,
+  signal: AbortSignal,
+) {
+  const authority = await ctx.runQuery(internal.runnerScaleSets.authorize, {
+    bindingId,
+    preparing,
+  });
+  const access = await repositoryAccess(new GitHubAppClient(authority.app), {
+    owner: authority.binding.repositoryOwner ?? authority.account.login,
+    repo: authority.binding.repositoryName,
+    repositoryId: authority.binding.repositoryId,
+    installationId: authority.binding.installationId,
+    githubUserId: authority.account.githubId,
+    githubLogin: authority.account.login,
+    ...(preparing ? {} : { purpose: "cleanup" as const }),
+  });
+  return { authority, admin: await admin(authority, access, signal) };
+}
+
+function grant(row: Doc<"runnerScaleSets">, scaleSetId: number, session: Session): ScaleSetGrant {
+  const exp = tokenExpiration(session.messageQueueAccessToken);
+  return {
+    bindingId: row.bindingId,
+    scaleSetId,
+    scaleSetName: row.name,
+    generation: row.generation,
+    sessionId: session.sessionId,
+    messageQueueUrl: session.messageQueueUrl,
+    messageQueueAccessToken: session.messageQueueAccessToken,
+    ...(exp === null ? {} : { queueTokenExpiresAt: exp * 1000 }),
+    statistics: session.statistics,
+  };
+}
+
+function scaleSetError(error: unknown): never {
+  if (error instanceof ConvexError) throw error;
+  throw new ConvexError({
+    code: "scale_set_unavailable",
+    message: "The GitHub scale set service could not complete the request.",
+    ...(error instanceof ScaleSetHttpError || error instanceof ScaleSetBootstrapHttpError
+      ? { status: error.status }
+      : {}),
+  });
+}
+
+async function ignoreMissing(operation: () => Promise<void>) {
+  try {
+    await operation();
+  } catch (error) {
+    if (!(error instanceof ScaleSetHttpError && error.status === 404)) throw error;
+  }
+}
+
+function verifyLabels(actual: readonly { name: string }[], labels: readonly string[]) {
+  const actualLabels = new Set(actual.map((label) => label.name.toLowerCase()));
+  if (
+    actualLabels.size !== labels.length ||
+    !labels.every((label) => actualLabels.has(label.toLowerCase()))
+  )
+    throw new ConvexError({
+      code: "scale_set_labels_unsupported",
+      message: "GitHub did not retain the scale set's custom runner labels.",
+      nextStep: "Use demand capacity for this repository.",
+    });
+}
+
+export const open = action({
+  args: { bindingId: v.string() },
+  handler: async (ctx, args): Promise<ScaleSetGrant> => {
+    const signal = AbortSignal.timeout(90000);
+    const row = await ctx.runMutation(internal.runnerScaleSets.begin, {
+      ...args,
+      operation: "open",
+    });
+    const identity = { id: row._id, generation: row.generation };
+    let created: { admin: ScaleSetAdminClient; scaleSetId: number; sessionId: string } | undefined;
+    try {
+      const { authority, admin } = await connection(ctx, args.bindingId, true, signal);
+      const environment = authority.environment;
+      if (!environment) throw new ConvexError({ code: "environment_unavailable" });
+      const group = await admin.defaultRunnerGroup(signal);
+      const labels = [...runnerLabels(environment.os, environment.id), row.name];
+      const found = await admin.findScaleSet(group.id, row.name, signal);
+      if (found && row.scaleSetId !== undefined && found.id !== row.scaleSetId)
+        throw new ConvexError({ code: "scale_set_identity_conflict" });
+      const set = found ?? (await admin.createScaleSet(group.id, row.name, labels, signal));
+      await ctx.runMutation(internal.runnerScaleSets.checkpoint, {
+        ...identity,
+        scaleSetId: set.id,
+        phase: "opening",
+      });
+      const effective = await admin.getScaleSet(set.id, signal);
+      if (effective.name !== row.name || effective.runnerGroupId !== group.id)
+        throw new ConvexError({ code: "scale_set_identity_conflict" });
+      verifyLabels(effective.labels, labels);
+      const oldSessionId = row.sessionId;
+      if (oldSessionId)
+        await ignoreMissing(() => admin.deleteSession(set.id, oldSessionId, signal));
+      const session = await admin
+        .createSession(set.id, `${row.machineId}:${row.generation}`, signal)
+        .catch((error: unknown) => {
+          if (error instanceof ScaleSetHttpError && error.status === 409)
+            throw new ConvexError({
+              code: "scale_set_session_conflict",
+              message: "GitHub already has a session whose identity Vectis cannot reconcile.",
+              nextStep:
+                "Close the other scale set listener or wait for its session to expire, then retry.",
+            });
+          throw error;
+        });
+      created = { admin, scaleSetId: set.id, sessionId: session.sessionId };
+      await ctx.runMutation(internal.runnerScaleSets.checkpoint, {
+        ...identity,
+        scaleSetId: set.id,
+        sessionId: session.sessionId,
+        phase: "active",
+      });
+      return grant(row, set.id, session);
+    } catch (error) {
+      if (created) {
+        const session = created;
+        await ignoreMissing(() =>
+          session.admin.deleteSession(session.scaleSetId, session.sessionId),
+        ).catch(() => undefined);
+      }
+      await ctx.runMutation(internal.runnerScaleSets.failed, identity);
+      return scaleSetError(error);
+    }
+  },
+});
+
+export const refresh = action({
+  args: { bindingId: v.string(), generation: v.number() },
+  handler: async (ctx, args): Promise<ScaleSetGrant> => {
+    const row = await ctx.runMutation(internal.runnerScaleSets.begin, {
+      ...args,
+      operation: "refresh",
+    });
+    const identity = { id: row._id, generation: row.generation };
+    try {
+      if (row.scaleSetId === undefined || !row.sessionId)
+        throw new ConvexError({ code: "scale_set_session_missing" });
+      const signal = AbortSignal.timeout(90000);
+      const { authority, admin } = await connection(ctx, args.bindingId, true, signal);
+      const environment = authority.environment;
+      if (!environment) throw new ConvexError({ code: "environment_unavailable" });
+      const set = await admin.getScaleSet(row.scaleSetId, signal);
+      if (set.name !== row.name) throw new ConvexError({ code: "scale_set_identity_conflict" });
+      verifyLabels(set.labels, [...runnerLabels(environment.os, environment.id), row.name]);
+      const session = await admin.refreshSession(row.scaleSetId, row.sessionId, signal);
+      if (session.sessionId !== row.sessionId)
+        throw new ConvexError({ code: "scale_set_identity_conflict" });
+      await ctx.runMutation(internal.runnerScaleSets.checkpoint, {
+        ...identity,
+        sessionId: row.sessionId,
+        phase: "active",
+      });
+      return grant(row, row.scaleSetId, session);
+    } catch (error) {
+      await ctx.runMutation(internal.runnerScaleSets.failed, identity);
+      return scaleSetError(error);
+    }
+  },
+});
+
+export const close = action({
+  args: { bindingId: v.string(), generation: v.number() },
+  handler: async (ctx, args): Promise<null> => {
+    const row = await ctx.runMutation(internal.runnerScaleSets.begin, {
+      ...args,
+      operation: "close",
+    });
+    if (row.phase === "closed") return null;
+    const identity = { id: row._id, generation: row.generation };
+    try {
+      const { scaleSetId, sessionId } = row;
+      if (scaleSetId !== undefined && sessionId) {
+        const signal = AbortSignal.timeout(90000);
+        const { admin } = await connection(ctx, args.bindingId, false, signal);
+        await ignoreMissing(() => admin.deleteSession(scaleSetId, sessionId, signal));
+      }
+      await ctx.runMutation(internal.runnerScaleSets.checkpoint, { ...identity, phase: "closed" });
+      return null;
+    } catch (error) {
+      await ctx.runMutation(internal.runnerScaleSets.failed, identity);
+      return scaleSetError(error);
+    }
+  },
+});
+
+export async function generateScaleSetJit(
+  ctx: ActionCtx,
+  input: { bindingId: string; generation: number; runnerName: string },
+  authority: Authority,
+  access: Access,
+) {
+  const row = await ctx.runQuery(internal.runnerScaleSets.forJit, {
+    bindingId: input.bindingId,
+    generation: input.generation,
+  });
+  const signal = AbortSignal.timeout(90000);
+  const client = await admin(authority, access, signal);
+  const set = await client.getScaleSet(row.scaleSetId, signal);
+  if (set.name !== row.name) throw new ConvexError({ code: "scale_set_identity_conflict" });
+  verifyLabels(set.labels, row.labels);
+  return client.generateJitConfig(row.scaleSetId, input.runnerName, signal);
+}
+
+export const cleanup = internalAction({
+  args: { id: v.id("runnerScaleSets"), generation: v.number(), attempt: v.number() },
+  handler: async (ctx, args): Promise<null> => {
+    try {
+      const authority = await ctx.runQuery(internal.runnerScaleSets.cleanupAuthority, {
+        id: args.id,
+        generation: args.generation,
+      });
+      if (!authority) return null;
+      const { row } = authority;
+      const signal = AbortSignal.timeout(90000);
+      const access = await repositoryAccess(new GitHubAppClient(authority.app), {
+        owner: row.repositoryOwner,
+        repo: row.repositoryName,
+        repositoryId: row.repositoryId,
+        installationId: row.installationId,
+        githubUserId: row.githubUserId,
+        githubLogin: row.githubLogin,
+        purpose: "cleanup",
+      });
+      const connection = await bootstrapAdmin(
+        { owner: row.repositoryOwner, repo: row.repositoryName, installationToken: access.token },
+        (url, init) => fetch(url, init),
+        signal,
+      );
+      const admin = new ScaleSetAdminClient(
+        connection.serviceUrl,
+        connection.adminToken,
+        (url, init) => fetch(url, init),
+      );
+      const group = await admin.defaultRunnerGroup(signal);
+      const set = await admin.findScaleSet(group.id, row.name, signal);
+      if (set) {
+        if (row.scaleSetId !== undefined && row.scaleSetId !== set.id)
+          throw new ConvexError({ code: "scale_set_identity_conflict" });
+        const oldSessionId = row.sessionId;
+        if (oldSessionId)
+          await ignoreMissing(() => admin.deleteSession(set.id, oldSessionId, signal));
+        await ignoreMissing(() => admin.deleteScaleSet(set.id, signal));
+      }
+      await ctx.runMutation(internal.runnerScaleSets.cleaned, {
+        id: row._id,
+        generation: row.generation,
+      });
+    } catch {
+      if (args.attempt < 7)
+        await ctx.scheduler.runAfter(
+          Math.min(900000, 1000 * 5 ** args.attempt),
+          internal.githubScaleSets.cleanup,
+          { ...args, attempt: args.attempt + 1 },
+        );
+      else
+        await ctx.runMutation(internal.runnerScaleSets.cleanupFailed, {
+          id: args.id,
+          generation: args.generation,
+        });
+    }
+    return null;
+  },
+});
diff --git a/convex/githubValidators.ts b/convex/githubValidators.ts
index 323c97e0..427e5e84 100644
--- a/convex/githubValidators.ts
+++ b/convex/githubValidators.ts
@@ -13,6 +13,7 @@ export const repositoryAccess = v.object({
 export const runnerAccess = v.object({
   repositoryId: v.number(),
   ...repositoryAccess.fields,
+  cacheRun: v.optional(v.object({ runId: v.number(), runAttempt: v.number() })),
   approvedRun: v.optional(v.object({ runId: v.number(), runAttempt: v.number() })),
 });
 
diff --git a/convex/machineTokens.ts b/convex/machineTokens.ts
index 95768c7f..87b54671 100644
--- a/convex/machineTokens.ts
+++ b/convex/machineTokens.ts
@@ -1,5 +1,12 @@
 "use node";
-import { createHash, createPrivateKey, createPublicKey, randomBytes, sign } from "node:crypto";
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  randomBytes,
+  randomUUID,
+  sign,
+} from "node:crypto";
 import { v } from "convex/values";
 import { action, internalAction } from "./_generated/server.js";
 import { internal } from "./_generated/api.js";
@@ -53,6 +60,7 @@ export const signToken = internalAction({
       aud: "vectis-machine",
       sub: args.machineId,
       credentialVersion: args.credentialVersion,
+      jti: randomUUID(),
       iat: now - 5,
       exp: now + 300,
     });
diff --git a/convex/machines.ts b/convex/machines.ts
index f3a88098..677c2978 100644
--- a/convex/machines.ts
+++ b/convex/machines.ts
@@ -68,10 +68,23 @@ export const heartbeat = mutation({
     paused: v.optional(v.boolean()),
     runnerIdle: v.optional(v.boolean()),
     runnerSlots: v.optional(v.number()),
+    environmentSlots: v.optional(
+      v.array(v.object({ environmentId: v.string(), available: v.number() })),
+    ),
   },
   handler: async (ctx, args) => {
     const record = await machine(ctx);
     const environments = args.environments;
+    const validSlots = (value: number) => Number.isInteger(value) && value >= 0 && value <= 16;
+    if (
+      (args.runnerSlots !== undefined && !validSlots(args.runnerSlots)) ||
+      (args.environmentSlots !== undefined &&
+        (args.environmentSlots.length > 100 ||
+          new Set(args.environmentSlots.map((item) => item.environmentId)).size !==
+            args.environmentSlots.length ||
+          args.environmentSlots.some((item) => !validSlots(item.available))))
+    )
+      throw new ConvexError({ code: "invalid_runner_capacity" });
     if (
       environments &&
       (environments.length > 100 ||
@@ -104,9 +117,14 @@ export const heartbeat = mutation({
       lastSeenAt: Date.now(),
       ...(args.runnerIdle === undefined ? {} : { runnerIdle: args.runnerIdle }),
       ...(args.runnerSlots === undefined ? {} : { runnerSlots: args.runnerSlots }),
+      ...(args.environmentSlots === undefined ? {} : { environmentSlots: args.environmentSlots }),
     };
     const current = await presence(ctx, record._id);
-    if (current) await ctx.db.patch("machinePresence", current._id, liveness);
+    if (current)
+      await ctx.db.patch("machinePresence", current._id, {
+        ...liveness,
+        environmentSlots: args.environmentSlots,
+      });
     else await ctx.db.insert("machinePresence", { machineId: record._id, ...liveness });
     const target = { ...record, ...changes };
     const bindings = target.paused === false ? await automaticBindings(ctx, record._id) : [];
diff --git a/convex/purge.ts b/convex/purge.ts
index 0e2020ee..c4b9a67f 100644
--- a/convex/purge.ts
+++ b/convex/purge.ts
@@ -1,3 +1,4 @@
+import { scheduleScaleSetCleanup } from "./runnerScaleSets.js";
 import { v } from "convex/values";
 import { internal } from "./_generated/api.js";
 import { internalMutation, type MutationCtx } from "./_generated/server.js";
@@ -18,6 +19,7 @@ async function deleteBinding(ctx: MutationCtx, id: Id<"repositoryBindings">) {
     .withIndex("by_binding", (q) => q.eq("bindingId", id))
     .take(batch))
     await ctx.db.delete("jobScans", scan._id);
+  await scheduleScaleSetCleanup(ctx, id);
   await ctx.db.delete("repositoryBindings", id);
   return demands.length;
 }
diff --git a/convex/repositoryBindings.ts b/convex/repositoryBindings.ts
index 6bd761f8..4c7a4324 100644
--- a/convex/repositoryBindings.ts
+++ b/convex/repositoryBindings.ts
@@ -3,9 +3,12 @@ import { internalMutation, internalQuery, mutation, query } from "./_generated/s
 import type { QueryCtx, MutationCtx } from "./_generated/server.js";
 import type { Doc, Id } from "./_generated/dataModel.js";
 import { Schema } from "effect";
+import { CacheVolume, defaultCacheSizeGiB } from "../packages/protocol/src/cache-volume.js";
 import { RepositoryAccess } from "../packages/protocol/src/repository-access.js";
 import { repositoryAccess } from "./githubValidators.js";
 import { human, machine } from "./auth.js";
+import { scheduleScaleSetCleanup } from "./runnerScaleSets.js";
+import { assertScaleSetPolicy } from "./scaleSetPolicy.js";
 import { workflowLabel } from "../packages/github/src/runner-labels.js";
 
 const authority = {
@@ -70,6 +73,8 @@ async function saveBinding(ctx: MutationCtx, args: ObjectType<typeof bindingFiel
   const record = { ...args, enabled: true, verifiedAt: Date.now() };
   if (existing) {
     if (existing.owner !== args.owner) throw new ConvexError({ code: "repository_access_denied" });
+    if (existing.installationId !== args.installationId || existing.accountId !== args.accountId)
+      await scheduleScaleSetCleanup(ctx, existing._id);
     await ctx.db.patch("repositoryBindings", existing._id, record);
     return existing._id;
   }
@@ -111,10 +116,13 @@ export const forMachine = query({
         visible.push({
           id: binding._id,
           repositoryId: binding.repositoryId,
+          installationId: binding.installationId,
+          ...(binding.cacheVolume ? { cacheVolume: binding.cacheVolume } : {}),
           repositoryName: `${binding.repositoryOwner ?? account.login}/${binding.repositoryName}`,
           environmentId: binding.environmentId,
           runsOn: workflowLabel(binding.environmentId),
           automatic: binding.automatic ?? false,
+          capacityMode: binding.capacityMode ?? "demand",
           ...(binding.access ? { access: binding.access } : {}),
         });
     }
@@ -128,6 +136,7 @@ export const disable = mutation({
     const record = await ctx.db.get("repositoryBindings", args.id);
     if (!record || record.owner !== owner) throw new ConvexError({ code: "binding_missing" });
     await ctx.db.patch("repositoryBindings", args.id, { enabled: false, automatic: false });
+    await scheduleScaleSetCleanup(ctx, record._id);
   },
 });
 
@@ -151,6 +160,32 @@ export const setAutomatic = mutation({
   },
 });
 
+export const setCacheVolume = mutation({
+  args: { bindingId: v.string(), enabled: v.boolean(), sizeGiB: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    const target = await machine(ctx);
+    const id = ctx.db.normalizeId("repositoryBindings", args.bindingId);
+    const binding = id ? await ctx.db.get("repositoryBindings", id) : null;
+    if (
+      !binding ||
+      !binding.enabled ||
+      binding.machineId !== target._id ||
+      binding.owner !== target.owner
+    )
+      throw new ConvexError({ code: "repository_access_denied" });
+    const account = await ctx.db.get("githubAccounts", binding.accountId);
+    if (account?.owner !== target.owner)
+      throw new ConvexError({ code: "repository_access_denied" });
+    const cacheVolume = {
+      enabled: args.enabled,
+      sizeGiB: args.sizeGiB ?? binding.cacheVolume?.sizeGiB ?? defaultCacheSizeGiB,
+    };
+    if (!Schema.is(CacheVolume)(cacheVolume))
+      throw new ConvexError({ code: "invalid_cache_volume" });
+    await ctx.db.patch("repositoryBindings", binding._id, { cacheVolume });
+  },
+});
+
 export const setAccess = mutation({
   args: { bindingId: v.string(), ...repositoryAccess.fields },
   handler: async (ctx, args) => {
@@ -179,6 +214,7 @@ export const setAccess = mutation({
           ? ("any" as const)
           : { ids: [...new Set(policy.value.actors.ids)] },
     };
+    if (binding.capacityMode === "scale_set") assertScaleSetPolicy(access);
     await ctx.db.patch("repositoryBindings", binding._id, { access });
   },
 });
@@ -236,6 +272,7 @@ export const disconnectForMachine = mutation({
     if (!binding || binding.machineId !== target._id || binding.owner !== target.owner)
       throw new ConvexError({ code: "repository_access_denied" });
     await ctx.db.patch("repositoryBindings", binding._id, { enabled: false, automatic: false });
+    await scheduleScaleSetCleanup(ctx, binding._id);
   },
 });
 
@@ -304,6 +341,7 @@ export const readinessAuthority = internalQuery({
             automatic: binding.automatic ?? false,
             repositoryId: binding.repositoryId,
             installationId: binding.installationId,
+            cacheVolumeEnabled: binding.cacheVolume?.enabled ?? false,
           }
         : null,
       accounts: (binding ? (bindingAccount ? [bindingAccount] : []) : accounts).map(
@@ -316,3 +354,28 @@ export const readinessAuthority = internalQuery({
     };
   },
 });
+
+export const setCapacityModeForMachine = mutation({
+  args: {
+    bindingId: v.string(),
+    capacityMode: v.union(v.literal("demand"), v.literal("scale_set")),
+  },
+  handler: async (ctx, args) => {
+    const target = await machine(ctx);
+    const id = ctx.db.normalizeId("repositoryBindings", args.bindingId);
+    const binding = id ? await ctx.db.get("repositoryBindings", id) : null;
+    if (
+      !binding ||
+      !binding.enabled ||
+      binding.machineId !== target._id ||
+      binding.owner !== target.owner
+    )
+      throw new ConvexError({ code: "repository_access_denied" });
+    const account = await ctx.db.get("githubAccounts", binding.accountId);
+    if (account?.owner !== target.owner)
+      throw new ConvexError({ code: "repository_access_denied" });
+    if (args.capacityMode === "scale_set") assertScaleSetPolicy(binding.access);
+    await ctx.db.patch("repositoryBindings", binding._id, { capacityMode: args.capacityMode });
+    if (args.capacityMode === "demand") await scheduleScaleSetCleanup(ctx, binding._id);
+  },
+});
diff --git a/convex/retention.ts b/convex/retention.ts
index 62af13e1..38ecca56 100644
--- a/convex/retention.ts
+++ b/convex/retention.ts
@@ -6,6 +6,7 @@ import { internalMutation, type MutationCtx } from "./_generated/server.js";
 const day = 24 * 60 * 60 * 1000;
 export const windows = {
   deliveries: 30 * day,
+  redeliveryRequests: 3 * day,
   jobs: 90 * day,
   operations: 90 * day,
   leases: 30 * day,
@@ -32,6 +33,14 @@ async function sweepTable<T extends { _id: { __tableName: string } }>(
 
 export async function sweepOnce(ctx: MutationCtx, now: number) {
   let deleted = 0;
+  deleted += await sweepTable(
+    await ctx.db
+      .query("githubRedeliveryRequests")
+      .withIndex("by_requested", (q) => q.lt("requestedAt", now - windows.redeliveryRequests))
+      .take(limit),
+    () => false,
+    async (row) => ctx.db.delete("githubRedeliveryRequests", row._id),
+  );
   deleted += await sweepTable(
     await ctx.db
       .query("githubDeliveries")
diff --git a/convex/runnerDemand.ts b/convex/runnerDemand.ts
index ebaeefed..7a97c826 100644
--- a/convex/runnerDemand.ts
+++ b/convex/runnerDemand.ts
@@ -21,7 +21,11 @@ export const forRepository = internalMutation({
       )
       .take(100);
     // Each machine's bounded scan gets its own transaction, including after batched job imports.
-    for (const machineId of new Set(bindings.map((binding) => binding.machineId)))
+    for (const machineId of new Set(
+      bindings
+        .filter((binding) => binding.capacityMode !== "scale_set")
+        .map((binding) => binding.machineId),
+    ))
       await ctx.scheduler.runAfter(0, internal.runnerDemand.forMachine, { machineId });
   },
 });
@@ -44,6 +48,9 @@ export function automaticBindings(ctx: MutationCtx, machineId: Id<"machines">) {
 }
 
 const failureRetryDelay = 60000;
+const actionRequiredRetryDelay = 600000;
+const maxAttempts = 10;
+const maxFailures = 3;
 // Unclaimed runner requests get two minutes for delivery, with a ten-minute cap for online hosts.
 const claimTimeoutMs = 120000;
 const claimDeadlineMs = 600000;
@@ -97,6 +104,21 @@ function expiredBeforeClaim(operation: Doc<"operations">) {
   }
 }
 
+function cachePrivilegeFailure(operation: Doc<"operations">) {
+  if (operation.phase !== "failed" || !operation.resultJson) return false;
+  try {
+    const result: unknown = JSON.parse(operation.resultJson);
+    return (
+      result !== null &&
+      typeof result === "object" &&
+      "code" in result &&
+      result.code === "cache_volume_requires_guest_sudo"
+    );
+  } catch {
+    return false;
+  }
+}
+
 // Runs on every heartbeat, so the reads an idle machine needs come first. Every return before the
 // scheduling loop is free of side effects, so this order schedules exactly what any other would.
 // Convex bills repeated reads within a transaction, so a heartbeat passes the bindings it already read.
@@ -108,12 +130,22 @@ export async function scheduleRunnerDemand(
   const machineId = target._id;
   const liveness = await presence(ctx, machineId);
   if (!liveness || target.paused !== false || liveness.lastSeenAt < Date.now() - 60000) return;
-  const legacy = liveness.runnerSlots === undefined;
-  let free = liveness.runnerSlots ?? (liveness.runnerIdle === true ? 1 : 0);
+  const environmentSlots =
+    liveness.environmentSlots === undefined
+      ? undefined
+      : new Map(liveness.environmentSlots.map((item) => [item.environmentId, item.available]));
+  const legacy = liveness.runnerSlots === undefined && environmentSlots === undefined;
+  let free =
+    liveness.runnerSlots ??
+    (environmentSlots
+      ? Math.max(0, ...environmentSlots.values())
+      : liveness.runnerIdle === true
+        ? 1
+        : 0);
   if (free <= 0) return;
   const queues: Array<{ binding: Doc<"repositoryBindings">; jobs: Doc<"githubJobs">[] }> = [];
   for (const binding of bindings ?? (await automaticBindings(ctx, machineId))) {
-    if (binding.owner !== target.owner) continue;
+    if (binding.owner !== target.owner || binding.capacityMode === "scale_set") continue;
     const environment = target.environments?.find(
       (item) => item.id === binding.environmentId && item.state === "ready",
     );
@@ -149,8 +181,21 @@ export async function scheduleRunnerDemand(
       if (command.type !== "runner.run") continue;
       if (legacy) return;
       // Claim precedes local submission; running can precede the next capacity heartbeat.
-      if (command.automatic && (phase !== "running" || operation.updatedAt >= liveness.lastSeenAt))
+      if (
+        command.automatic &&
+        (phase !== "running" || operation.updatedAt >= liveness.lastSeenAt)
+      ) {
         free--;
+        if (environmentSlots) {
+          const bindingId = ctx.db.normalizeId("repositoryBindings", command.bindingId);
+          const binding = bindingId ? await ctx.db.get("repositoryBindings", bindingId) : null;
+          if (binding?.machineId === machineId && binding.owner === target.owner)
+            environmentSlots.set(
+              binding.environmentId,
+              (environmentSlots.get(binding.environmentId) ?? 0) - 1,
+            );
+        }
+      }
     }
     if (free <= 0) return;
   }
@@ -169,6 +214,7 @@ export async function scheduleRunnerDemand(
     let scheduled = false;
     for (const { binding, jobs } of queues) {
       if (free <= 0) break;
+      if (environmentSlots && (environmentSlots.get(binding.environmentId) ?? 0) <= 0) continue;
       while (jobs.length > 0) {
         const job = jobs.shift();
         if (!job) break;
@@ -181,25 +227,26 @@ export async function scheduleRunnerDemand(
               .eq("jobId", job.jobId),
           )
           .unique();
+        let failures = demand?.failures ?? 0;
         if (demand) {
-          if (demand.owner !== target.owner || demand.attempt >= 3) continue;
-          // A runner that succeeded served another job with the same labels; one that failed never
-          // took this job, because the job is still queued. Both leave the job needing a runner.
-          // A failure waits a minute, so a passing condition does not use up every attempt at once.
-          // Expiry before claim can retry unchanged jobs on another machine. A person's cancellation
-          // stays final unless the job changed after the attempt, as when approval queues it again.
+          if (demand.owner !== target.owner || demand.attempt >= maxAttempts) continue;
           const previous = await ctx.db.get("operations", demand.operationId);
-          if (
-            previous?.phase !== "succeeded" &&
-            !(
-              previous?.phase === "failed" && previous.updatedAt <= Date.now() - failureRetryDelay
-            ) &&
-            !(
-              previous?.phase === "cancelled" &&
-              (expiredBeforeClaim(previous) || job.updatedAt > previous.createdAt)
-            )
-          )
-            continue;
+          if (previous && cachePrivilegeFailure(previous)) continue;
+          const now = Date.now();
+          if (!previous) {
+            if (demand.updatedAt > now - actionRequiredRetryDelay) continue;
+          } else if (previous.phase === "failed" || previous.phase === "action_required") {
+            const delay =
+              previous.phase === "action_required" ? actionRequiredRetryDelay : failureRetryDelay;
+            if (previous.updatedAt > now - delay) continue;
+            failures++;
+          } else if (previous.phase === "cancelled") {
+            if (expiredBeforeClaim(previous)) {
+              if (previous.updatedAt > now - failureRetryDelay) continue;
+              failures++;
+            } else if (job.updatedAt <= previous.createdAt) continue;
+          } else if (previous.phase !== "succeeded") continue;
+          if (failures >= maxFailures) continue;
         }
         const attempt = (demand?.attempt ?? 0) + 1;
         const now = Date.now();
@@ -225,6 +272,7 @@ export async function scheduleRunnerDemand(
           bindingId: binding._id,
           operationId,
           attempt,
+          failures,
           updatedAt: now,
         };
         if (demand) await ctx.db.patch("runnerDemands", demand._id, record);
@@ -233,6 +281,11 @@ export async function scheduleRunnerDemand(
           operationId,
         });
         free--;
+        if (environmentSlots)
+          environmentSlots.set(
+            binding.environmentId,
+            (environmentSlots.get(binding.environmentId) ?? 0) - 1,
+          );
         scheduled = true;
         break;
       }
diff --git a/convex/runnerLeases.ts b/convex/runnerLeases.ts
index 83cd3ce7..82d477ba 100644
--- a/convex/runnerLeases.ts
+++ b/convex/runnerLeases.ts
@@ -5,6 +5,8 @@ import {
   sameRunnerAccess,
 } from "../packages/github/src/access-policy.js";
 import { matchesRunnerLabels } from "../packages/github/src/runner-labels.js";
+import { currentScaleSet } from "./runnerScaleSets.js";
+import { assertScaleSetBinding } from "./scaleSetPolicy.js";
 import { scheduleRunnerDemand } from "./runnerDemand.js";
 import { ConvexError, v } from "convex/values";
 import { internalMutation, internalQuery, mutation, query } from "./_generated/server.js";
@@ -12,7 +14,11 @@ import type { QueryCtx } from "./_generated/server.js";
 import { machine } from "./auth.js";
 import { internal } from "./_generated/api.js";
 
-export const runnerRequest = { jobId: v.optional(v.number()), automatic: v.optional(v.boolean()) };
+export const runnerRequest = {
+  jobId: v.optional(v.number()),
+  automatic: v.optional(v.boolean()),
+  scaleSet: v.optional(v.object({ generation: v.number() })),
+};
 
 const configLifetime = 15 * 60 * 1000;
 
@@ -41,13 +47,27 @@ export async function bindingAuthority(ctx: QueryCtx, bindingId: string, prepari
 export async function runnerAdmission(
   ctx: QueryCtx,
   bindingId: string,
-  request: { jobId?: number; automatic?: boolean },
+  request: { jobId?: number; automatic?: boolean; scaleSet?: { generation: number } },
 ): Promise<NonNullable<Doc<"runnerLeases">["access"]>> {
   const { binding, environment } = await bindingAuthority(ctx, bindingId, true);
   if (request.automatic && !binding.automatic)
     throw new ConvexError({ code: "automatic_disabled" });
   const policy = binding.access ?? { actors: "any" as const, approval: "automatic" as const };
   const base = { repositoryId: binding.repositoryId, ...policy };
+  if (request.scaleSet) {
+    assertScaleSetBinding(binding);
+    if (request.jobId !== undefined) throw new ConvexError({ code: "invalid_runner_request" });
+    const row = await currentScaleSet(ctx, binding, request.scaleSet.generation);
+    if (
+      !["active", "refreshing"].includes(row.phase) ||
+      !row.sessionId ||
+      row.scaleSetId === undefined
+    )
+      throw new ConvexError({ code: "scale_set_session_missing" });
+    return base;
+  }
+  if (request.automatic && binding.capacityMode === "scale_set")
+    throw new ConvexError({ code: "scale_set_generation_required" });
   if (request.jobId === undefined) {
     if (restrictiveAccess(policy)) throw new ConvexError({ code: "job_required" });
     return base;
@@ -82,8 +102,22 @@ export const authorize = internalQuery({
     const authority = await bindingAuthority(ctx, args.bindingId, args.preparing);
     const app = await ctx.db.query("githubApps").first();
     if (!app) throw new ConvexError({ code: "github_app_unavailable" });
+    const requestedJobId = args.jobId;
+    const cacheJob =
+      args.preparing && requestedJobId !== undefined && authority.binding.cacheVolume?.enabled
+        ? await ctx.db
+            .query("githubJobs")
+            .withIndex("by_job", (q) =>
+              q
+                .eq("installationId", authority.binding.installationId)
+                .eq("repositoryId", authority.binding.repositoryId)
+                .eq("jobId", requestedJobId),
+            )
+            .unique()
+        : null;
     return {
       ...authority,
+      cacheJob: cacheJob ? { runId: cacheJob.runId, runAttempt: cacheJob.runAttempt } : null,
       ...(args.preparing ? { access: await runnerAdmission(ctx, args.bindingId, args) } : {}),
       app: { appId: app.appId, clientId: app.clientId, privateKey: app.privateKey },
     };
@@ -108,6 +142,7 @@ export const claim = internalMutation({
         // Reconciliation fences an unclaimed request with a released lease that records no request details.
         (existing.phase !== "released" &&
           (existing.jobId !== args.jobId ||
+            existing.scaleSet?.generation !== args.scaleSet?.generation ||
             (existing.automatic ?? false) !== (args.automatic ?? false) ||
             !sameRunnerAccess(existing.access, access)))
       )
@@ -136,6 +171,7 @@ export const claim = internalMutation({
       os: environment.os,
       ...(environment.revision ? { environmentRevision: environment.revision } : {}),
       key: args.key,
+      ...(args.scaleSet ? { scaleSet: args.scaleSet } : {}),
       access,
       ...(args.jobId === undefined ? {} : { jobId: args.jobId }),
       ...(args.automatic === undefined ? {} : { automatic: args.automatic }),
@@ -149,7 +185,14 @@ export const claim = internalMutation({
   },
 });
 export const ready = internalMutation({
-  args: { id: v.id("runnerLeases"), runnerId: v.number(), encodedConfig: v.string() },
+  args: {
+    id: v.id("runnerLeases"),
+    runnerId: v.number(),
+    encodedConfig: v.string(),
+    cacheWrite: v.optional(v.boolean()),
+    cacheWriteReason: v.optional(v.string()),
+    cacheRun: v.optional(v.object({ runId: v.number(), runAttempt: v.number() })),
+  },
   handler: async (ctx, args) => {
     const target = await machine(ctx);
     const lease = await ctx.db.get("runnerLeases", args.id);
@@ -162,6 +205,7 @@ export const ready = internalMutation({
       throw new ConvexError({ code: "runner_lease_conflict" });
     const authority = await bindingAuthority(ctx, lease.bindingId, true);
     const access = await runnerAdmission(ctx, lease.bindingId, {
+      ...(lease.scaleSet ? { scaleSet: lease.scaleSet } : {}),
       ...(lease.jobId === undefined ? {} : { jobId: lease.jobId }),
       ...(lease.automatic === undefined ? {} : { automatic: lease.automatic }),
     });
@@ -179,6 +223,9 @@ export const ready = internalMutation({
       phase: "ready",
       runnerId: args.runnerId,
       encodedConfig: args.encodedConfig,
+      cacheWrite: args.cacheWrite === true && args.cacheRun !== undefined,
+      ...(args.cacheWriteReason ? { cacheWriteReason: args.cacheWriteReason.slice(0, 256) } : {}),
+      ...(args.cacheRun ? { cacheRun: args.cacheRun } : {}),
       configExpiresAt: Date.now() + configLifetime,
       updatedAt: Date.now(),
     });
diff --git a/convex/runnerScaleSets.ts b/convex/runnerScaleSets.ts
new file mode 100644
index 00000000..6e561428
--- /dev/null
+++ b/convex/runnerScaleSets.ts
@@ -0,0 +1,285 @@
+import { ConvexError, v } from "convex/values";
+import { internal } from "./_generated/api.js";
+import type { Doc, Id } from "./_generated/dataModel.js";
+import {
+  internalMutation,
+  internalQuery,
+  type MutationCtx,
+  type QueryCtx,
+} from "./_generated/server.js";
+import { runnerLabels } from "../packages/github/src/runner-labels.js";
+import { machine } from "./auth.js";
+import { bindingAuthority } from "./runnerLeases.js";
+import { assertScaleSetBinding } from "./scaleSetPolicy.js";
+
+// A durable intent serializes session effects, including a retry after an action process dies.
+const effectWindow = 120000;
+const identity = { id: v.id("runnerScaleSets"), generation: v.number() };
+
+export async function findScaleSet(
+  ctx: Pick<QueryCtx, "db">,
+  bindingId: Id<"repositoryBindings">,
+  machineId: Id<"machines">,
+) {
+  return ctx.db
+    .query("runnerScaleSets")
+    .withIndex("by_binding_machine", (q) => q.eq("bindingId", bindingId).eq("machineId", machineId))
+    .unique();
+}
+
+export async function currentScaleSet(
+  ctx: Pick<QueryCtx, "db">,
+  binding: Doc<"repositoryBindings">,
+  generation: number,
+) {
+  const row = await findScaleSet(ctx, binding._id, binding.machineId);
+  if (
+    !Number.isSafeInteger(generation) ||
+    generation <= 0 ||
+    !row ||
+    row.generation !== generation ||
+    row.owner !== binding.owner ||
+    row.installationId !== binding.installationId ||
+    row.repositoryId !== binding.repositoryId
+  )
+    throw new ConvexError({ code: "scale_set_superseded" });
+  return row;
+}
+
+function busy(row: Doc<"runnerScaleSets">) {
+  return (
+    ["opening", "refreshing", "closing"].includes(row.phase) &&
+    row.updatedAt > Date.now() - effectWindow
+  );
+}
+
+export const authorize = internalQuery({
+  args: { bindingId: v.string(), preparing: v.boolean() },
+  handler: async (ctx, args) => {
+    const authority = await bindingAuthority(ctx, args.bindingId, args.preparing);
+    if (args.preparing) assertScaleSetBinding(authority.binding);
+    const app = await ctx.db.query("githubApps").first();
+    if (!app) throw new ConvexError({ code: "github_app_unavailable" });
+    return {
+      ...authority,
+      app: { appId: app.appId, clientId: app.clientId, privateKey: app.privateKey },
+    };
+  },
+});
+
+export const begin = internalMutation({
+  args: {
+    bindingId: v.string(),
+    operation: v.union(v.literal("open"), v.literal("refresh"), v.literal("close")),
+    generation: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<Doc<"runnerScaleSets">> => {
+    const { target, binding, account } = await bindingAuthority(
+      ctx,
+      args.bindingId,
+      args.operation === "open",
+    );
+    const existing = await findScaleSet(ctx, binding._id, target._id);
+    if (args.operation !== "open") {
+      if (args.generation === undefined) throw new ConvexError({ code: "scale_set_superseded" });
+      const row = await currentScaleSet(ctx, binding, args.generation);
+      if (row.phase === "deleting") throw new ConvexError({ code: "scale_set_superseded" });
+      if (args.operation === "refresh") {
+        await bindingAuthority(ctx, args.bindingId, true);
+        assertScaleSetBinding(binding);
+      }
+      if (args.operation === "close" && row.phase === "closed") return row;
+      if (busy(row)) throw new ConvexError({ code: "scale_set_pending" });
+      if (
+        args.operation === "refresh" &&
+        (!["active", "action_required"].includes(row.phase) ||
+          !row.sessionId ||
+          row.scaleSetId === undefined)
+      )
+        throw new ConvexError({ code: "scale_set_session_missing" });
+      const patch = {
+        phase: args.operation === "refresh" ? ("refreshing" as const) : ("closing" as const),
+        updatedAt: Date.now(),
+      };
+      await ctx.db.patch("runnerScaleSets", row._id, patch);
+      return { ...row, ...patch };
+    }
+    assertScaleSetBinding(binding);
+    if (existing?.phase === "deleting")
+      throw new ConvexError({ code: "scale_set_cleanup_pending" });
+    if (existing && busy(existing)) throw new ConvexError({ code: "scale_set_pending" });
+    if (
+      existing?.scaleSetId !== undefined &&
+      (existing.installationId !== binding.installationId ||
+        existing.repositoryId !== binding.repositoryId ||
+        existing.owner !== binding.owner)
+    )
+      throw new ConvexError({ code: "installation_changed" });
+    const record = {
+      owner: target.owner,
+      installationId: binding.installationId,
+      repositoryId: binding.repositoryId,
+      bindingId: binding._id,
+      machineId: target._id,
+      repositoryOwner: binding.repositoryOwner ?? account.login,
+      repositoryName: binding.repositoryName,
+      githubUserId: account.githubId,
+      githubLogin: account.login,
+      name: `vectis-${binding.environmentId}-${target._id.slice(0, 8)}`,
+      generation: (existing?.generation ?? 0) + 1,
+      phase: "opening" as const,
+      updatedAt: Date.now(),
+    };
+    if (existing) {
+      await ctx.db.patch("runnerScaleSets", existing._id, record);
+      return { ...existing, ...record };
+    }
+    const id = await ctx.db.insert("runnerScaleSets", record);
+    const row = await ctx.db.get("runnerScaleSets", id);
+    if (!row) throw new Error("Scale set persistence failed.");
+    return row;
+  },
+});
+
+export const checkpoint = internalMutation({
+  args: {
+    ...identity,
+    scaleSetId: v.optional(v.number()),
+    sessionId: v.optional(v.string()),
+    phase: v.union(v.literal("opening"), v.literal("active"), v.literal("closed")),
+  },
+  handler: async (ctx, args) => {
+    const target = await machine(ctx);
+    const row = await ctx.db.get("runnerScaleSets", args.id);
+    if (
+      !row ||
+      row.generation !== args.generation ||
+      row.machineId !== target._id ||
+      row.owner !== target.owner ||
+      row.phase === "deleting"
+    )
+      throw new ConvexError({ code: "scale_set_superseded" });
+    const expectedPhase =
+      args.phase === "closed"
+        ? ["closing"]
+        : args.phase === "opening"
+          ? ["opening"]
+          : ["opening", "refreshing"];
+    if (!expectedPhase.includes(row.phase)) throw new ConvexError({ code: "scale_set_superseded" });
+    const { binding } = await bindingAuthority(ctx, row.bindingId, args.phase !== "closed");
+    if (args.phase !== "closed") assertScaleSetBinding(binding);
+    await currentScaleSet(ctx, binding, args.generation);
+    await ctx.db.patch("runnerScaleSets", row._id, {
+      ...(args.scaleSetId === undefined ? {} : { scaleSetId: args.scaleSetId }),
+      ...(args.phase === "opening" && args.sessionId === undefined
+        ? {}
+        : { sessionId: args.sessionId }),
+      phase: args.phase,
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+export const failed = internalMutation({
+  args: identity,
+  handler: async (ctx, args) => {
+    const row = await ctx.db.get("runnerScaleSets", args.id);
+    if (
+      row?.generation === args.generation &&
+      ["opening", "refreshing", "closing"].includes(row.phase)
+    )
+      await ctx.db.patch("runnerScaleSets", row._id, {
+        phase: "action_required",
+        updatedAt: Date.now(),
+      });
+  },
+});
+
+export async function scheduleScaleSetCleanup(
+  ctx: MutationCtx,
+  bindingId: Id<"repositoryBindings">,
+) {
+  const rows = await ctx.db
+    .query("runnerScaleSets")
+    .withIndex("by_binding_machine", (q) => q.eq("bindingId", bindingId))
+    .take(100);
+  for (const row of rows) {
+    if (row.phase === "deleting") continue;
+    const generation = row.generation + 1;
+    await ctx.db.patch("runnerScaleSets", row._id, {
+      generation,
+      phase: "deleting",
+      updatedAt: Date.now(),
+    });
+    // Let an already issued request settle before discovering and deleting its remote effects.
+    await ctx.scheduler.runAfter(busy(row) ? effectWindow : 0, internal.githubScaleSets.cleanup, {
+      id: row._id,
+      generation,
+      attempt: 0,
+    });
+  }
+}
+
+export const cleanupAuthority = internalQuery({
+  args: identity,
+  handler: async (ctx, args) => {
+    const row = await ctx.db.get("runnerScaleSets", args.id);
+    if (!row || row.generation !== args.generation || row.phase !== "deleting") return null;
+    const app = await ctx.db.query("githubApps").first();
+    if (!app) throw new ConvexError({ code: "github_app_unavailable" });
+    return { row, app: { appId: app.appId, clientId: app.clientId, privateKey: app.privateKey } };
+  },
+});
+
+export const cleaned = internalMutation({
+  args: identity,
+  handler: async (ctx, args) => {
+    const row = await ctx.db.get("runnerScaleSets", args.id);
+    if (!row || row.generation !== args.generation || row.phase !== "deleting") return;
+    const binding = await ctx.db.get("repositoryBindings", row.bindingId);
+    if (!binding) {
+      await ctx.db.delete("runnerScaleSets", row._id);
+      return;
+    }
+    // Keep the generation tombstone across a later switch back to scale set capacity.
+    await ctx.db.patch("runnerScaleSets", row._id, {
+      phase: "closed",
+      scaleSetId: undefined,
+      sessionId: undefined,
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+export const forJit = internalQuery({
+  args: { bindingId: v.string(), generation: v.number() },
+  handler: async (ctx, args) => {
+    const { binding, environment } = await bindingAuthority(ctx, args.bindingId, true);
+    assertScaleSetBinding(binding);
+    const row = await currentScaleSet(ctx, binding, args.generation);
+    if (
+      !["active", "refreshing"].includes(row.phase) ||
+      !row.sessionId ||
+      row.scaleSetId === undefined ||
+      !environment
+    )
+      throw new ConvexError({ code: "scale_set_session_missing" });
+    return {
+      scaleSetId: row.scaleSetId,
+      name: row.name,
+      labels: [...runnerLabels(environment.os, environment.id), row.name],
+    };
+  },
+});
+
+export const cleanupFailed = internalMutation({
+  args: identity,
+  handler: async (ctx, args) => {
+    const row = await ctx.db.get("runnerScaleSets", args.id);
+    if (row?.generation === args.generation && row.phase === "deleting")
+      await ctx.db.patch("runnerScaleSets", row._id, {
+        phase: "action_required",
+        updatedAt: Date.now(),
+      });
+  },
+});
diff --git a/convex/scaleSetPolicy.ts b/convex/scaleSetPolicy.ts
new file mode 100644
index 00000000..82700601
--- /dev/null
+++ b/convex/scaleSetPolicy.ts
@@ -0,0 +1,19 @@
+import { ConvexError } from "convex/values";
+import { restrictiveAccess } from "../packages/github/src/access-policy.js";
+import type { Doc } from "./_generated/dataModel.js";
+
+export function assertScaleSetPolicy(access: Doc<"repositoryBindings">["access"]) {
+  if (restrictiveAccess(access))
+    throw new ConvexError({
+      code: "scale_set_policy_unsupported",
+      message: "Scale set messages do not identify the workflow actor or approval status.",
+      nextStep: "Use demand capacity for actor restrictions or required approval.",
+    });
+}
+
+export function assertScaleSetBinding(binding: Doc<"repositoryBindings">) {
+  if (binding.capacityMode !== "scale_set") throw new ConvexError({ code: "scale_set_disabled" });
+  if (!binding.enabled) throw new ConvexError({ code: "repository_access_denied" });
+  if (!binding.automatic) throw new ConvexError({ code: "automatic_disabled" });
+  assertScaleSetPolicy(binding.access);
+}
diff --git a/convex/schema.ts b/convex/schema.ts
index c997db5a..896ff2cf 100644
--- a/convex/schema.ts
+++ b/convex/schema.ts
@@ -112,7 +112,9 @@ export default defineSchema({
     environmentId: v.string(),
     enabled: v.boolean(),
     automatic: v.optional(v.boolean()),
+    capacityMode: v.optional(v.union(v.literal("demand"), v.literal("scale_set"))),
     access: v.optional(repositoryAccess),
+    cacheVolume: v.optional(v.object({ enabled: v.boolean(), sizeGiB: v.number() })),
     // Legacy; jobScans holds scan times so scans do not rewrite the binding.
     lastJobScanAt: v.optional(v.number()),
     verifiedAt: v.number(),
@@ -127,6 +129,32 @@ export default defineSchema({
     bindingId: v.id("repositoryBindings"),
     scannedAt: v.number(),
   }).index("by_binding", ["bindingId"]),
+  runnerScaleSets: defineTable({
+    owner: v.string(),
+    installationId: v.number(),
+    repositoryId: v.number(),
+    bindingId: v.id("repositoryBindings"),
+    machineId: v.id("machines"),
+    repositoryOwner: v.string(),
+    repositoryName: v.string(),
+    githubUserId: v.number(),
+    githubLogin: v.string(),
+    // Persist intent before creating the remote set; no credentials belong in this table.
+    scaleSetId: v.optional(v.number()),
+    name: v.string(),
+    generation: v.number(),
+    sessionId: v.optional(v.string()),
+    phase: v.union(
+      v.literal("opening"),
+      v.literal("active"),
+      v.literal("refreshing"),
+      v.literal("closing"),
+      v.literal("closed"),
+      v.literal("action_required"),
+      v.literal("deleting"),
+    ),
+    updatedAt: v.number(),
+  }).index("by_binding_machine", ["bindingId", "machineId"]),
   runnerLeases: defineTable({
     owner: v.string(),
     machineId: v.id("machines"),
@@ -145,8 +173,12 @@ export default defineSchema({
     updatedAt: v.number(),
     runnerId: v.optional(v.number()),
     encodedConfig: v.optional(v.string()),
+    cacheWrite: v.optional(v.boolean()),
+    cacheWriteReason: v.optional(v.string()),
+    cacheRun: v.optional(v.object({ runId: v.number(), runAttempt: v.number() })),
     configExpiresAt: v.optional(v.number()),
     access: v.optional(runnerAccess),
+    scaleSet: v.optional(v.object({ generation: v.number() })),
     jobId: v.optional(v.number()),
     automatic: v.optional(v.boolean()),
   })
@@ -176,6 +208,9 @@ export default defineSchema({
     lastSeenAt: v.number(),
     runnerIdle: v.optional(v.boolean()),
     runnerSlots: v.optional(v.number()),
+    environmentSlots: v.optional(
+      v.array(v.object({ environmentId: v.string(), available: v.number() })),
+    ),
   }).index("by_machine", ["machineId"]),
   runnerDemands: defineTable({
     installationId: v.number(),
@@ -185,6 +220,7 @@ export default defineSchema({
     bindingId: v.id("repositoryBindings"),
     operationId: v.id("operations"),
     attempt: v.number(),
+    failures: v.optional(v.number()),
     updatedAt: v.number(),
   })
     .index("by_job", ["installationId", "repositoryId", "jobId"])
@@ -229,6 +265,16 @@ export default defineSchema({
   })
     .index("by_delivery", ["deliveryId"])
     .index("by_received", ["receivedAt"]),
+  githubRedeliveryCheckpoint: defineTable({
+    deliveredAt: v.number(),
+    scannedAt: v.number(),
+  }),
+  githubRedeliveryRequests: defineTable({
+    guid: v.string(),
+    requestedAt: v.number(),
+  })
+    .index("by_guid", ["guid"])
+    .index("by_requested", ["requestedAt"]),
   githubAppSetups: defineTable({
     stateDigest: v.string(),
     ownerId: v.number(),
diff --git a/native/apple/Sources/VectisVM/main.swift b/native/apple/Sources/VectisVM/main.swift
index b45a7204..61feae5b 100644
--- a/native/apple/Sources/VectisVM/main.swift
+++ b/native/apple/Sources/VectisVM/main.swift
@@ -28,14 +28,28 @@ final class Controller: NSObject, VZVirtualMachineDelegate, NSWindowDelegate {
     var machine: VZVirtualMachine?
     var signals: [DispatchSourceSignal] = []
     var stopping = false
+    var input = Data()
 
     func start(arguments: [String]) async throws {
-        let rosetta = arguments.dropFirst(7).contains("--rosetta")
-        let arguments = Array(arguments.prefix(7)) + arguments.dropFirst(7).filter { $0 != "--rosetta" }
+        var positional = Array(arguments.prefix(7))
+        var rosetta = false
+        var cachePath: String?
+        var extra = Array(arguments.dropFirst(7))[...]
+        while let option = extra.popFirst() {
+            if option == "--rosetta" && !rosetta { rosetta = true }
+            else if option == "--cache-disk" && cachePath == nil {
+                guard let path = extra.popFirst(), path.hasPrefix("/") else {
+                    throw HelperError(message: "--cache-disk requires an absolute disk image path.")
+                }
+                cachePath = path
+            } else if !option.hasPrefix("--") || option == "--console" { positional.append(option) }
+            else { throw HelperError(message: "Unknown or duplicate VM option: \(option)") }
+        }
+        let arguments = positional
         guard (7...8).contains(arguments.count), arguments[1] == "run",
               let cpu = Int(arguments[4]), let memory = UInt64(arguments[5]),
               cpu > 0, memory >= 512, memory <= UInt64.max / 1048576 else {
-            throw HelperError(message: "Usage: vectis-vm run linux|macos image cpu memoryMiB efiPath [seedPath|--console] [--rosetta]")
+            throw HelperError(message: "Usage: vectis-vm run linux|macos image cpu memoryMiB efiPath [seedPath|--console] [--rosetta] [--cache-disk path]")
         }
         let os = arguments[2]
         if rosetta && os != "linux" {
@@ -99,6 +113,14 @@ final class Controller: NSObject, VZVirtualMachineDelegate, NSWindowDelegate {
             let seed = try VZDiskImageStorageDeviceAttachment(url: URL(fileURLWithPath: arguments[7]), readOnly: true)
             configuration.storageDevices.append(VZVirtioBlockDeviceConfiguration(attachment: seed))
         }
+        if let cachePath {
+            let cacheURL = URL(fileURLWithPath: cachePath).standardizedFileURL
+            guard cacheURL != disk.standardizedFileURL else { throw HelperError(message: "The cache disk must differ from the boot disk.") }
+            let cacheAttachment = try VZDiskImageStorageDeviceAttachment(url: cacheURL, readOnly: false)
+            let cache = VZVirtioBlockDeviceConfiguration(attachment: cacheAttachment)
+            cache.blockDeviceIdentifier = "VECTISCACHE"
+            configuration.storageDevices.append(cache)
+        }
         let network = VZVirtioNetworkDeviceConfiguration()
         network.macAddress = VZMACAddress.randomLocallyAdministered()
         network.attachment = VZNATNetworkDeviceAttachment()
@@ -115,9 +137,12 @@ final class Controller: NSObject, VZVirtualMachineDelegate, NSWindowDelegate {
             signals.append(source)
         }
         FileHandle.standardInput.readabilityHandler = { handle in
-            if handle.availableData.isEmpty {
+            let data = handle.availableData
+            if data.isEmpty {
                 handle.readabilityHandler = nil
                 Task { @MainActor in await self.stop() }
+            } else {
+                Task { @MainActor in self.receive(data) }
             }
         }
         try await vm.start()
@@ -142,6 +167,30 @@ final class Controller: NSObject, VZVirtualMachineDelegate, NSWindowDelegate {
         Task { @MainActor in await self.stop() }
     }
 
+    func receive(_ data: Data) {
+        input.append(data)
+        guard input.count <= 1024 else {
+            input.removeAll()
+            emit("vm.shutdown_unavailable")
+            return
+        }
+        while let newline = input.firstIndex(of: 10) {
+            let command = String(decoding: input[..<newline], as: UTF8.self)
+            input.removeSubrange(...newline)
+            guard command == "shutdown" else { continue }
+            guard let machine, machine.canRequestStop, !stopping else {
+                emit("vm.shutdown_unavailable")
+                continue
+            }
+            do {
+                try machine.requestStop()
+                emit("vm.shutdown_requested")
+            } catch {
+                emit("vm.shutdown_unavailable")
+            }
+        }
+    }
+
     func stop() async {
         guard !stopping else { return }
         stopping = true
@@ -169,7 +218,7 @@ final class Controller: NSObject, VZVirtualMachineDelegate, NSWindowDelegate {
     }
 }
 
-let showConsole = CommandLine.arguments.last == "--console"
+let showConsole = CommandLine.arguments.dropFirst(7).contains("--console")
 if showConsole { NSApplication.shared.setActivationPolicy(.regular) }
 let controller = Controller()
 Task { @MainActor in
diff --git a/packages/client/src/cloud-relay.test.ts b/packages/client/src/cloud-relay.test.ts
index 3dda402f..d4eae265 100644
--- a/packages/client/src/cloud-relay.test.ts
+++ b/packages/client/src/cloud-relay.test.ts
@@ -1,7 +1,8 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
+import type { AuthTokenFetcher } from "convex/browser";
 import { getFunctionName, type FunctionReference } from "convex/server";
 import { ConvexError } from "convex/values";
 import { afterEach, expect, test, vi } from "vitest";
@@ -9,7 +10,7 @@ import { api } from "../../../convex/_generated/api.js";
 import { Store } from "../../../apps/server/src/store.js";
 import { VectisClient } from "./index.js";
 import { startCloudRelay } from "./cloud-relay.js";
-import { VectisError } from "../../protocol/src/index.js";
+import { VectisError, type Environment } from "../../protocol/src/index.js";
 
 type Subscription = {
   name: string;
@@ -20,7 +21,7 @@ type Subscription = {
 };
 const transport = vi.hoisted(() => {
   const subscriptions: Subscription[] = [];
-  const auth: { changed?: (authenticated: boolean) => void } = {};
+  const auth: { changed?: (authenticated: boolean) => void; fetchToken?: AuthTokenFetcher } = {};
   return {
     subscriptions,
     auth,
@@ -63,7 +64,8 @@ vi.mock("convex/browser", () => ({
       connectionState: transport.connectionState,
       subscribeToConnectionState: () => transport.disconnect,
     };
-    setAuth(_fetchToken: unknown, changed: (authenticated: boolean) => void) {
+    setAuth(fetchToken: AuthTokenFetcher, changed: (authenticated: boolean) => void) {
+      transport.auth.fetchToken = fetchToken;
       transport.auth.changed = changed;
     }
   },
@@ -75,12 +77,14 @@ afterEach(async () => {
   cleanup.length = 0;
   vi.useRealTimers();
   vi.restoreAllMocks();
+  vi.unstubAllGlobals();
   vi.clearAllMocks();
   transport.subscriptions.length = 0;
   delete transport.auth.changed;
+  delete transport.auth.fetchToken;
 });
 
-async function fixture() {
+async function fixture(get = async (): Promise<string | null> => null) {
   const home = await mkdtemp(join(tmpdir(), "vectis-relay-"));
   cleanup.push(() => rm(home, { recursive: true, force: true }));
   const store = new Store(join(home, "state.sqlite"));
@@ -100,7 +104,7 @@ async function fixture() {
       localId: store.snapshot().machine.id,
     },
     local,
-    { get: async () => null },
+    { get },
     vi.fn(),
     () => store.touch(),
     onJobObservations,
@@ -114,6 +118,7 @@ async function fixture() {
     return found;
   };
   return {
+    home,
     relay,
     local,
     onJobObservations,
@@ -123,6 +128,38 @@ async function fixture() {
   };
 }
 
+async function heartbeatFixture() {
+  const context = await fixture();
+  const { home, store, local } = context;
+  const environment: Environment = {
+    id: "linux",
+    name: "Linux",
+    os: "linux",
+    basePath: join(home, "base.img"),
+    cpu: 2,
+    memoryMiB: 2048,
+    state: "ready",
+  };
+  await writeFile(environment.basePath, "synthetic image");
+  store.put("environment", environment.id, environment);
+  vi.spyOn(local, "status").mockImplementation(async () => store.snapshot());
+  transport.query.mockImplementation(async (query) =>
+    getFunctionName(query) === "machines:self"
+      ? { id: "machine1", localId: store.snapshot().machine.id }
+      : [],
+  );
+  return { ...context, environment };
+}
+
+async function nextRelayTick() {
+  const reconciliations = () =>
+    transport.query.mock.calls.filter(([query]) => getFunctionName(query) === "operations:pending")
+      .length;
+  const previous = reconciliations();
+  await vi.advanceTimersByTimeAsync(2000);
+  await vi.waitFor(() => expect(reconciliations()).toBeGreaterThan(previous));
+}
+
 const binding = (id: string) => ({
   id,
   repositoryId: 1,
@@ -142,6 +179,24 @@ const job = {
   updatedAt: 1,
 };
 
+test("relay auth callback returns a distinct token on immediate forced refresh", async () => {
+  vi.useFakeTimers();
+  await fixture(async () => "secret");
+  const request = vi
+    .fn()
+    .mockResolvedValueOnce(Response.json({ token: "original", expiresAt: Date.now() + 300000 }))
+    .mockResolvedValueOnce(Response.json({ token: "original", expiresAt: Date.now() + 300000 }))
+    .mockResolvedValueOnce(Response.json({ token: "fresh", expiresAt: Date.now() + 300000 }));
+  vi.stubGlobal("fetch", request);
+  const fetchToken = transport.auth.fetchToken;
+  if (!fetchToken) throw new Error("Missing auth callback.");
+  expect(await fetchToken({ forceRefreshToken: false })).toBe("original");
+  const refreshed = fetchToken({ forceRefreshToken: true });
+  await vi.advanceTimersByTimeAsync(1100);
+  expect(await refreshed).toBe("fresh");
+  expect(request).toHaveBeenCalledTimes(3);
+});
+
 test("repository and job changes invalidate snapshots without repeating identical updates", async () => {
   const { relay, store, repositories, subscription } = await fixture();
   const initial = store.snapshot().revision;
@@ -320,13 +375,242 @@ test("lease observations use one subscription per set and release stale callback
   expect(transport.subscriptions.filter((item) => item.name === "jobs:forLeases")).toHaveLength(3);
 });
 
+test("environment registration sends a heartbeat on the next tick without waiting for the cadence", async () => {
+  vi.useFakeTimers();
+  const { store, environment } = await heartbeatFixture();
+  transport.auth.changed?.(true);
+  await vi.waitFor(() => expect(transport.mutation).toHaveBeenCalledTimes(1));
+  store.put("environment", "new", { ...environment, id: "new" });
+  await vi.advanceTimersByTimeAsync(2000);
+  await vi.waitFor(() => expect(transport.mutation).toHaveBeenCalledTimes(2));
+  expect(transport.mutation.mock.calls.at(-1)?.[1]).toMatchObject({
+    environments: [
+      expect.objectContaining({ id: "linux" }),
+      expect.objectContaining({ id: "new" }),
+    ],
+  });
+});
+
+test("connecting a new environment reports it before invoking the cloud action", async () => {
+  vi.useFakeTimers();
+  const { relay, store, environment } = await heartbeatFixture();
+  transport.auth.changed?.(true);
+  await vi.waitFor(() => expect(transport.mutation).toHaveBeenCalledTimes(1));
+  store.put("environment", "new", { ...environment, id: "new" });
+  transport.action.mockImplementation(async () => {
+    expect(transport.mutation.mock.calls.at(-1)?.[1]).toMatchObject({
+      environments: expect.arrayContaining([expect.objectContaining({ id: "new" })]),
+    });
+    return "binding";
+  });
+  await expect(
+    relay.connectRepository(
+      { accountId: "account", repositoryName: "repo", environmentId: "new" },
+      new AbortController().signal,
+    ),
+  ).resolves.toBe("binding");
+  expect(transport.mutation).toHaveBeenCalledTimes(2);
+});
+
+test.each<Partial<Environment>>([
+  { name: "Renamed" },
+  { os: "windows" },
+  { cpu: 4 },
+  { memoryMiB: 4096 },
+  { state: "action_required" },
+])("reported environment changes send an early heartbeat: %j", async (change) => {
+  vi.useFakeTimers();
+  const { store, environment } = await heartbeatFixture();
+  transport.auth.changed?.(true);
+  await nextRelayTick();
+  expect(transport.mutation).toHaveBeenCalledTimes(1);
+  store.put("environment", environment.id, { ...environment, ...change });
+  await nextRelayTick();
+  expect(transport.mutation).toHaveBeenCalledTimes(2);
+  expect(transport.mutation.mock.calls.at(-1)?.[1]).toMatchObject({
+    environments: [expect.objectContaining({ id: environment.id, ...change })],
+  });
+  await nextRelayTick();
+  expect(transport.mutation).toHaveBeenCalledTimes(2);
+});
+
+test("image revisions, missing images and environment removal send early heartbeats", async () => {
+  vi.useFakeTimers();
+  const { store, environment } = await heartbeatFixture();
+  transport.auth.changed?.(true);
+  await nextRelayTick();
+  const first = transport.mutation.mock.calls.at(-1)?.[1];
+  await writeFile(environment.basePath, "replacement image with a different size");
+  await nextRelayTick();
+  expect(transport.mutation).toHaveBeenCalledTimes(2);
+  expect(transport.mutation.mock.calls.at(-1)?.[1]).not.toEqual(first);
+  expect(transport.mutation.mock.calls.at(-1)?.[1]).toMatchObject({
+    environments: [expect.objectContaining({ state: "ready", revision: expect.any(String) })],
+  });
+  await rm(environment.basePath);
+  await nextRelayTick();
+  expect(transport.mutation).toHaveBeenCalledTimes(3);
+  expect(transport.mutation.mock.calls.at(-1)?.[1]).toMatchObject({
+    environments: [expect.objectContaining({ state: "action_required" })],
+  });
+  expect(transport.mutation.mock.calls.at(-1)?.[1]).not.toHaveProperty("environments.0.revision");
+  store.remove("environment", environment.id);
+  await nextRelayTick();
+  expect(transport.mutation).toHaveBeenCalledTimes(4);
+  expect(transport.mutation.mock.calls.at(-1)?.[1]).toMatchObject({ environments: [] });
+});
+
+test("unchanged inventories, ordering and known connections add no heartbeat before the cadence", async () => {
+  vi.useFakeTimers();
+  const { relay, store, local, environment } = await heartbeatFixture();
+  store.put("environment", "second", { ...environment, id: "second" });
+  transport.auth.changed?.(true);
+  await nextRelayTick();
+  vi.mocked(local.status).mockImplementation(async () => {
+    const snapshot = store.snapshot();
+    return { ...snapshot, environments: [...snapshot.environments].reverse() };
+  });
+  await nextRelayTick();
+  await relay.connectRepository(
+    { accountId: "account", repositoryName: "repo", environmentId: "linux" },
+    new AbortController().signal,
+  );
+  await vi.advanceTimersByTimeAsync(20000);
+  await nextRelayTick();
+  expect(transport.mutation).toHaveBeenCalledTimes(1);
+  await vi.advanceTimersByTimeAsync(6000);
+  await vi.waitFor(() => expect(transport.mutation).toHaveBeenCalledTimes(2));
+});
+
+test("concurrent connections wait for the same acknowledged inventory heartbeat", async () => {
+  vi.useFakeTimers();
+  const { relay } = await heartbeatFixture();
+  let finishHeartbeat: () => void = () => {};
+  const heartbeat = new Promise<void>((resolve) => {
+    finishHeartbeat = resolve;
+  });
+  transport.mutation.mockReturnValueOnce(heartbeat);
+  transport.auth.changed?.(true);
+  await vi.waitFor(() => expect(transport.mutation).toHaveBeenCalledTimes(1));
+  const connect = () =>
+    relay.connectRepository(
+      { accountId: "account", repositoryName: "repo", environmentId: "linux" },
+      new AbortController().signal,
+    );
+  const first = connect();
+  const second = connect();
+  await vi.advanceTimersByTimeAsync(2000);
+  expect(transport.action).not.toHaveBeenCalled();
+  expect(transport.mutation).toHaveBeenCalledTimes(1);
+  finishHeartbeat();
+  await expect(Promise.all([first, second])).resolves.toEqual(["binding", "binding"]);
+  expect(transport.mutation).toHaveBeenCalledTimes(1);
+});
+
+test("a connection refreshes once after an in-flight heartbeat with an older inventory", async () => {
+  vi.useFakeTimers();
+  const { relay, store, environment } = await heartbeatFixture();
+  let finishHeartbeat: () => void = () => {};
+  const heartbeat = new Promise<void>((resolve) => {
+    finishHeartbeat = resolve;
+  });
+  transport.mutation.mockReturnValueOnce(heartbeat);
+  transport.auth.changed?.(true);
+  await vi.waitFor(() => expect(transport.mutation).toHaveBeenCalledTimes(1));
+  store.put("environment", "new", { ...environment, id: "new" });
+  const connection = relay.connectRepository(
+    { accountId: "account", repositoryName: "repo", environmentId: "new" },
+    new AbortController().signal,
+  );
+  expect(transport.action).not.toHaveBeenCalled();
+  finishHeartbeat();
+  await expect(connection).resolves.toBe("binding");
+  expect(transport.mutation).toHaveBeenCalledTimes(2);
+  expect(transport.mutation.mock.calls.at(-1)?.[1]).toMatchObject({
+    environments: expect.arrayContaining([expect.objectContaining({ id: "new" })]),
+  });
+});
+
+test("failed inventory heartbeats prevent connect and are retried without marking inventory sent", async () => {
+  vi.useFakeTimers();
+  const { relay, store, environment } = await heartbeatFixture();
+  transport.auth.changed?.(true);
+  await nextRelayTick();
+  store.put("environment", "new", { ...environment, id: "new" });
+  const failure = new Error("Heartbeat unavailable");
+  transport.mutation.mockRejectedValueOnce(failure);
+  const connect = () =>
+    relay.connectRepository(
+      { accountId: "account", repositoryName: "repo", environmentId: "new" },
+      new AbortController().signal,
+    );
+  await expect(connect()).rejects.toBe(failure);
+  expect(transport.action).not.toHaveBeenCalled();
+  await expect(connect()).resolves.toBe("binding");
+  expect(transport.mutation).toHaveBeenCalledTimes(3);
+  await nextRelayTick();
+  expect(transport.mutation).toHaveBeenCalledTimes(3);
+});
+
+test("an unknown environment gets one bounded inventory check without duplicate heartbeats", async () => {
+  vi.useFakeTimers();
+  const { relay, local } = await heartbeatFixture();
+  transport.auth.changed?.(true);
+  await nextRelayTick();
+  const reads = vi.mocked(local.status).mock.calls.length;
+  transport.action.mockRejectedValueOnce(new ConvexError({ code: "environment_unavailable" }));
+  await expect(
+    relay.connectRepository(
+      { accountId: "account", repositoryName: "repo", environmentId: "missing" },
+      new AbortController().signal,
+    ),
+  ).rejects.toMatchObject({ code: "environment_unavailable" });
+  expect(local.status).toHaveBeenCalledTimes(reads + 1);
+  expect(transport.mutation).toHaveBeenCalledTimes(1);
+  expect(transport.action).toHaveBeenCalledOnce();
+});
+
+test.each(["cancel", "close", "timeout"])(
+  "a pending heartbeat releases the connect wait on %s without invoking the action",
+  async (reason) => {
+    vi.useFakeTimers();
+    const { relay } = await heartbeatFixture();
+    transport.mutation.mockImplementationOnce(async () => new Promise(() => {}));
+    transport.auth.changed?.(true);
+    await vi.waitFor(() => expect(transport.mutation).toHaveBeenCalledTimes(1));
+    const abort = new AbortController();
+    const timeout = new AbortController();
+    if (reason === "timeout") vi.spyOn(AbortSignal, "timeout").mockReturnValueOnce(timeout.signal);
+    const connection = relay.connectRepository(
+      { accountId: "account", repositoryName: "repo", environmentId: "linux" },
+      abort.signal,
+    );
+    const rejection = expect(connection).rejects.toThrow();
+    if (reason === "cancel") abort.abort(new Error("Stop connecting"));
+    else if (reason === "close") await relay.close();
+    else {
+      expect(AbortSignal.timeout).toHaveBeenCalledWith(10000);
+      timeout.abort(new DOMException("Heartbeat timed out", "TimeoutError"));
+    }
+    await rejection;
+    expect(transport.action).not.toHaveBeenCalled();
+    expect(transport.mutation).toHaveBeenCalledTimes(1);
+  },
+);
+
 test("slot changes send a heartbeat on the next tick without waiting for the cadence", async () => {
   vi.useFakeTimers();
   const { store, local } = await fixture();
   let available = 2;
+  let macSlots = 1;
   vi.spyOn(local, "status").mockImplementation(async () => ({
     ...store.snapshot(),
-    runnerCapacity: { max: 5, active: 1, available },
+    runnerCapacity: {
+      max: 5,
+      active: 1,
+      available,
+      environments: [{ environmentId: "mac", available: macSlots }],
+    },
   }));
   transport.query.mockImplementation(async (query) =>
     getFunctionName(query) === "machines:self"
@@ -336,19 +620,31 @@ test("slot changes send a heartbeat on the next tick without waiting for the cad
   transport.auth.changed?.(true);
   await vi.advanceTimersByTimeAsync(0);
   expect(transport.mutation).toHaveBeenCalledTimes(1);
-  expect(transport.mutation.mock.calls[0]?.[1]).toMatchObject({ runnerSlots: 2, runnerIdle: true });
+  expect(transport.mutation.mock.calls[0]?.[1]).toMatchObject({
+    runnerSlots: 2,
+    runnerIdle: true,
+    environmentSlots: [{ environmentId: "mac", available: 1 }],
+  });
   await vi.advanceTimersByTimeAsync(2000);
   expect(transport.mutation).toHaveBeenCalledTimes(1);
   available = 0;
   await vi.advanceTimersByTimeAsync(2000);
   expect(transport.mutation).toHaveBeenCalledTimes(2);
   expect(transport.mutation.mock.calls[1]?.[1]).toMatchObject({ runnerSlots: 0, runnerIdle: true });
-  vi.mocked(local.status).mockImplementation(async () => store.snapshot());
+  macSlots = 0;
   await vi.advanceTimersByTimeAsync(2000);
   expect(transport.mutation).toHaveBeenCalledTimes(3);
-  expect(transport.mutation.mock.calls[2]?.[1]).not.toHaveProperty("runnerSlots");
+  expect(transport.mutation.mock.calls[2]?.[1]).toMatchObject({
+    runnerSlots: 0,
+    environmentSlots: [{ environmentId: "mac", available: 0 }],
+  });
+  vi.mocked(local.status).mockImplementation(async () => store.snapshot());
   await vi.advanceTimersByTimeAsync(2000);
-  expect(transport.mutation).toHaveBeenCalledTimes(3);
+  expect(transport.mutation).toHaveBeenCalledTimes(4);
+  expect(transport.mutation.mock.calls[3]?.[1]).not.toHaveProperty("runnerSlots");
+  expect(transport.mutation.mock.calls[3]?.[1]).not.toHaveProperty("environmentSlots");
+  await vi.advanceTimersByTimeAsync(2000);
+  expect(transport.mutation).toHaveBeenCalledTimes(4);
 });
 
 test("identity is verified once per authentication, not on every tick", async () => {
@@ -502,6 +798,42 @@ test("relay shutdown interrupts runner status polling", async () => {
   await rejected;
 });
 
+test.each([
+  { type: "machine.configure", maxRunners: 8, memoryBudgetMiB: 24576 },
+  { type: "environment.configure", id: "linux", warmPool: 2 },
+])("remote $type configuration replays settings unchanged", async (command) => {
+  vi.useFakeTimers();
+  const { store, local } = await fixture();
+  const submit = vi.spyOn(local, "submit").mockResolvedValue({
+    id: "local-settings",
+    key: "remote:settings",
+    command: command.type,
+    status: "succeeded",
+    message: "Applied",
+    createdAt: "",
+    updatedAt: "",
+  });
+  vi.spyOn(local, "status").mockImplementation(async () => store.snapshot());
+  transport.query.mockImplementation(async (query) => {
+    if (getFunctionName(query) === "machines:self")
+      return { id: "machine1", localId: store.snapshot().machine.id };
+    if (getFunctionName(query) === "operations:pending")
+      return [{ _id: "settings", phase: "running", commandJson: JSON.stringify(command) }];
+    return [];
+  });
+  transport.auth.changed?.(true);
+  await vi.advanceTimersByTimeAsync(0);
+  expect(submit).toHaveBeenCalledWith(command, "remote:settings", expect.any(AbortSignal));
+  expect(
+    transport.mutation.mock.calls.some(
+      ([mutation, args]) =>
+        getFunctionName(mutation) === "operations:acknowledge" &&
+        args.id === "settings" &&
+        args.phase === "succeeded",
+    ),
+  ).toBe(true);
+});
+
 test("remote acknowledgements redact older hosts' task errors before truncating or sending", async () => {
   vi.useFakeTimers();
   const { store, local } = await fixture();
@@ -551,6 +883,47 @@ test("remote acknowledgements redact older hosts' task errors before truncating
   expect(JSON.stringify(acknowledgement)).not.toContain("private local details");
 });
 
+test("remote runner failures forward the cache privilege code without private result details", async () => {
+  vi.useFakeTimers();
+  const { store, local } = await fixture();
+  vi.spyOn(local, "status").mockImplementation(async () => store.snapshot());
+  vi.spyOn(local, "submit").mockResolvedValue({
+    id: "local-cache",
+    key: "remote:cache",
+    command: "runner.run",
+    status: "failed",
+    message:
+      "This environment cannot mount cache volumes: the guest user has no passwordless sudo.",
+    createdAt: "",
+    updatedAt: "",
+    result: { code: "cache_volume_requires_guest_sudo", diagnostics: "private guest details" },
+  });
+  transport.query.mockImplementation(async (query) => {
+    if (getFunctionName(query) === "machines:self")
+      return { id: "machine1", localId: store.snapshot().machine.id };
+    if (getFunctionName(query) === "operations:pending")
+      return [
+        {
+          _id: "cache",
+          phase: "running",
+          commandJson: JSON.stringify({ type: "runner.run", bindingId: "binding" }),
+        },
+      ];
+    return [];
+  });
+  transport.auth.changed?.(true);
+  await vi.advanceTimersByTimeAsync(0);
+  const acknowledgement = transport.mutation.mock.calls.find(
+    ([mutation]) => getFunctionName(mutation) === "operations:acknowledge",
+  )?.[1];
+  expect(acknowledgement).toMatchObject({ phase: "failed", resultJson: expect.any(String) });
+  if (typeof acknowledgement?.resultJson !== "string") throw new Error("Missing acknowledgement");
+  expect(JSON.parse(acknowledgement.resultJson)).toMatchObject({
+    code: "cache_volume_requires_guest_sudo",
+  });
+  expect(JSON.stringify(acknowledgement)).not.toContain("private guest details");
+});
+
 test("job log relay forwards cursors to the action, decodes results and preserves coded failures", async () => {
   const { relay } = await fixture();
   const input = { bindingId: "binding1", jobId: 4, after: 10 };
@@ -590,7 +963,7 @@ test.each([
   "cloud_unconfigured",
   "cloud_unavailable",
 ])("connection relay preserves the coded %s refusal even without cloud prose", async (code) => {
-  const { relay } = await fixture();
+  const { relay } = await heartbeatFixture();
   transport.auth.changed?.(true);
   transport.action.mockRejectedValueOnce(new ConvexError({ code }));
   await expect(
@@ -614,7 +987,7 @@ test.each([
   new Error("Connection lost after submit"),
   new ConvexError({ code: "unexpected_failure" }),
 ])("an uncertain connection outcome remains unconfirmed", async (error) => {
-  const { relay } = await fixture();
+  const { relay } = await heartbeatFixture();
   transport.auth.changed?.(true);
   transport.action.mockRejectedValueOnce(error);
   await expect(
@@ -725,3 +1098,191 @@ test("runner release preserves the busy code and guidance as a VectisError", asy
   await expect(failure).rejects.toBeInstanceOf(VectisError);
   await expect(failure).rejects.toMatchObject(data);
 });
+
+test("cache settings use the authenticated binding mutation and discovery preserves the setting", async () => {
+  const { relay, repositories } = await fixture();
+  transport.auth.changed?.(true);
+  const value = {
+    ...binding("binding1"),
+    installationId: 12,
+    cacheVolume: { enabled: true, sizeGiB: 30 },
+  };
+  repositories.deliver([value]);
+  expect(relay.repositorySnapshot).toEqual([value]);
+  await relay.setCacheVolume("binding1", { enabled: true, sizeGiB: 30 });
+  expect(
+    transport.mutation.mock.calls.some(
+      ([mutation, args]) =>
+        getFunctionName(mutation) === "repositoryBindings:setCacheVolume" &&
+        isDeepStrictEqual(args, { bindingId: "binding1", enabled: true, sizeGiB: 30 }),
+    ),
+  ).toBe(true);
+});
+
+test("scale set relay decodes grants, forwards generation and keeps credentials out of results on close", async () => {
+  const { relay } = await fixture();
+  transport.auth.changed?.(true);
+  const grant = {
+    bindingId: "binding1",
+    generation: 3,
+    scaleSetId: 42,
+    scaleSetName: "vectis-linux",
+    sessionId: "00000000-0000-4000-8000-000000000001",
+    messageQueueUrl: "https://queue.test/messages",
+    messageQueueAccessToken: "queue-token",
+  };
+  const signal = new AbortController().signal;
+  transport.action
+    .mockResolvedValueOnce(grant)
+    .mockResolvedValueOnce({ ...grant, messageQueueAccessToken: "refreshed" })
+    .mockResolvedValueOnce(null);
+  expect(await relay.openScaleSet("binding1", signal)).toEqual(grant);
+  expect(await relay.refreshScaleSet("binding1", 3, signal)).toMatchObject({
+    messageQueueAccessToken: "refreshed",
+  });
+  expect(await relay.closeScaleSet("binding1", 3, signal)).toBeUndefined();
+  expect(
+    transport.action.mock.calls.map(([action, args]) => [getFunctionName(action), args]),
+  ).toEqual([
+    ["githubScaleSets:open", { bindingId: "binding1" }],
+    ["githubScaleSets:refresh", { bindingId: "binding1", generation: 3 }],
+    ["githubScaleSets:close", { bindingId: "binding1", generation: 3 }],
+  ]);
+  transport.action.mockResolvedValueOnce({ ...grant, generation: "invalid" });
+  await expect(relay.openScaleSet("binding1", signal)).rejects.toThrow();
+});
+
+test.each([
+  "scale_set_session_conflict",
+  "scale_set_policy_unsupported",
+  "scale_set_superseded",
+  "scale_set_identity_conflict",
+])("scale set relay maps code-only %s errors", async (code) => {
+  const { relay } = await fixture();
+  transport.auth.changed?.(true);
+  transport.action.mockRejectedValueOnce(new ConvexError({ code }));
+  await expect(relay.openScaleSet("binding1", new AbortController().signal)).rejects.toBeInstanceOf(
+    VectisError,
+  );
+  transport.action.mockRejectedValueOnce(new ConvexError({ code }));
+  await expect(
+    relay.refreshScaleSet("binding1", 1, new AbortController().signal),
+  ).rejects.toMatchObject({ code });
+});
+
+test("scale set relay distinguishes cloud authorization failures and bounds interrupted waits", async () => {
+  const { relay } = await fixture();
+  await expect(relay.openScaleSet("binding1", new AbortController().signal)).rejects.toMatchObject({
+    code: "cloud_unavailable",
+  });
+  transport.auth.changed?.(true);
+  transport.action.mockRejectedValueOnce(
+    new ConvexError({ code: "scale_set_unavailable", status: 401 }),
+  );
+  await expect(relay.openScaleSet("binding1", new AbortController().signal)).rejects.toMatchObject({
+    code: "scale_set_auth_failed",
+  });
+  transport.action.mockImplementationOnce(async () => new Promise(() => {}));
+  const abort = new AbortController();
+  const rejected = expect(relay.openScaleSet("binding1", abort.signal)).rejects.toThrow(
+    "Stop scale set open",
+  );
+  abort.abort(new Error("Stop scale set open"));
+  await rejected;
+});
+
+test("capacity mode relay uses the machine-authorized mutation and runner registration forwards scaleSet", async () => {
+  const { relay } = await fixture();
+  transport.auth.changed?.(true);
+  await relay.setCapacityMode("binding1", "scale_set");
+  expect(transport.mutation.mock.calls.map(([ref, args]) => [getFunctionName(ref), args])).toEqual([
+    [
+      "repositoryBindings:setCapacityModeForMachine",
+      { bindingId: "binding1", capacityMode: "scale_set" },
+    ],
+  ]);
+  const grant = { state: "pending", id: "lease1" };
+  transport.action.mockResolvedValueOnce(grant);
+  expect(
+    await relay.prepareRunner("binding1", "runner-key", new AbortController().signal, {
+      automatic: true,
+      scaleSet: { generation: 3 },
+    }),
+  ).toEqual(grant);
+  expect(transport.action.mock.calls.map(([ref, args]) => [getFunctionName(ref), args])).toEqual([
+    [
+      "githubRunners:prepare",
+      { bindingId: "binding1", key: "runner-key", automatic: true, scaleSet: { generation: 3 } },
+    ],
+  ]);
+});
+
+test("remote replay carries capacity mode through the same idempotent local command path", async () => {
+  vi.useFakeTimers();
+  const { store, local } = await fixture();
+  vi.spyOn(local, "status").mockImplementation(async () => store.snapshot());
+  const command = {
+    type: "repository.capacity-mode",
+    bindingId: "binding1",
+    mode: "scale_set",
+  } as const;
+  const submit = vi.spyOn(local, "submit").mockResolvedValue({
+    id: "local-operation",
+    key: "remote:remote-operation",
+    command: command.type,
+    status: "succeeded",
+    message: "Changed.",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  });
+  transport.query.mockImplementation(async (query) => {
+    if (getFunctionName(query) === "machines:self")
+      return { id: "machine1", localId: store.snapshot().machine.id };
+    if (getFunctionName(query) === "operations:pending")
+      return [{ _id: "remote-operation", phase: "running", commandJson: JSON.stringify(command) }];
+    return [];
+  });
+  transport.auth.changed?.(true);
+  await vi.advanceTimersByTimeAsync(0);
+  expect(submit).toHaveBeenCalledWith(command, "remote:remote-operation", expect.any(AbortSignal));
+  expect(
+    transport.mutation.mock.calls
+      .filter(([ref]) => getFunctionName(ref) === "operations:acknowledge")
+      .map((call) => call[1]),
+  ).toMatchObject([{ id: "remote-operation", phase: "succeeded" }]);
+});
+
+test.each([true, false])(
+  "runner grants preserve cache authority and denial reasons: %s",
+  async (cacheWrite) => {
+    const { relay } = await fixture();
+    transport.auth.changed?.(true);
+    const grant = {
+      state: "ready",
+      id: "lease1",
+      runnerId: 3,
+      encodedConfig: "c2VjcmV0",
+      environmentId: "linux",
+      os: "linux",
+      cacheWrite,
+      ...(cacheWrite ? {} : { cacheWriteReason: "metadata_access_denied" }),
+      access: {
+        repositoryId: 1,
+        actors: "any",
+        approval: "automatic",
+        ...(cacheWrite ? { cacheRun: { runId: 5, runAttempt: 1 } } : {}),
+      },
+    };
+    transport.action.mockResolvedValueOnce(grant);
+    expect(
+      await relay.prepareRunner("binding1", "cache-job", new AbortController().signal, {
+        jobId: 9,
+      }),
+    ).toEqual(grant);
+    expect(transport.action.mock.calls.at(-1)?.[1]).toEqual({
+      bindingId: "binding1",
+      key: "cache-job",
+      jobId: 9,
+    });
+  },
+);
diff --git a/packages/client/src/cloud-relay.ts b/packages/client/src/cloud-relay.ts
index 4e22edeb..39fb2dc5 100644
--- a/packages/client/src/cloud-relay.ts
+++ b/packages/client/src/cloud-relay.ts
@@ -1,6 +1,7 @@
+import { ScaleSetGrant, type CapacityMode } from "../../protocol/src/scale-sets.js";
 import { RunControlOutcome, type RunControlCommand } from "../../protocol/src/runs.js";
 import { ConvexError } from "convex/values";
-import type { FunctionReturnType } from "convex/server";
+import type { FunctionArgs, FunctionReturnType } from "convex/server";
 import { isDeepStrictEqual } from "node:util";
 import { environmentRevision } from "./environment-revision.js";
 import {
@@ -40,6 +41,30 @@ function interruptible<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>
     promise
       .then(resolve, (error: unknown) => {
         if (
+          error instanceof ConvexError &&
+          Schema.is(
+            Schema.Struct({
+              code: Schema.String,
+              message: Schema.optional(Schema.String),
+              nextStep: Schema.optional(Schema.String),
+              status: Schema.optional(Schema.Number),
+            }),
+          )(error.data) &&
+          error.data.code.startsWith("scale_set_")
+        ) {
+          const code =
+            error.data.code === "scale_set_unavailable" &&
+            [401, 403].includes(error.data.status ?? 0)
+              ? "scale_set_auth_failed"
+              : error.data.code;
+          reject(
+            new VectisError(
+              code,
+              error.data.message ?? "Scale set control was refused.",
+              error.data.nextStep,
+            ),
+          );
+        } else if (
           error instanceof ConvexError &&
           Schema.is(
             Schema.Struct({
@@ -48,6 +73,8 @@ function interruptible<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>
                 "private_runner_approval_required",
                 "repository_admin_required",
                 "github_app_not_installed",
+                "github_unavailable",
+                "github_rate_limited",
                 "machine_revoked",
                 "cloud_unconfigured",
                 "cloud_unavailable",
@@ -123,6 +150,17 @@ function interruptible<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>
   });
 }
 
+function decodeScaleSetGrant(value: unknown) {
+  try {
+    return Schema.decodeUnknownSync(ScaleSetGrant)(value);
+  } catch {
+    throw new VectisError(
+      "scale_set_protocol_invalid",
+      "The cloud returned an invalid scale set grant.",
+    );
+  }
+}
+
 const removalCodes = ["machine_rejected", "machine_revoked"];
 type JobMarker = { value: FunctionReturnType<typeof api.jobs.latest> };
 
@@ -146,6 +184,10 @@ export function startCloudRelay(
   let tokenRequest: Promise<string | null> | undefined;
   let lastHeartbeat = 0;
   let lastRunnerSlots: number | undefined;
+  let lastEnvironmentSlots: string | undefined;
+  let lastEnvironments: FunctionArgs<typeof api.machines.heartbeat>["environments"];
+  let lastEnvironmentInventory: string | undefined;
+  let pendingHeartbeat: Promise<void> | undefined;
   let rerun = false;
   let removed = false;
   let interval: ReturnType<typeof setInterval> | undefined;
@@ -201,7 +243,8 @@ export function startCloudRelay(
       },
     );
   };
-  async function reconcile() {
+  async function sendHeartbeat() {
+    requireConnection();
     if (!verified) {
       const identity = await interruptible(cloud.query(api.machines.self, {}), abort.signal);
       verified = identity.id === connection.machineId && identity.localId === connection.localId;
@@ -213,11 +256,37 @@ export function startCloudRelay(
         "This credential belongs to another local machine.",
       );
     const runnerSlots = snapshot.runnerCapacity?.available;
-    if (Date.now() - lastHeartbeat >= 30000 || runnerSlots !== lastRunnerSlots) {
+    const environmentSlots = snapshot.runnerCapacity?.environments?.slice(0, 100);
+    const environmentSlotsKey = JSON.stringify(environmentSlots);
+    const environments = await Promise.all(
+      snapshot.environments.slice(0, 100).map(async (environment) => {
+        const { id, name, os, cpu, memoryMiB, state } = environment;
+        const revision = await environmentRevision(environment);
+        return {
+          id,
+          name,
+          os,
+          cpu,
+          memoryMiB,
+          state: revision ? state : ("action_required" as const),
+          ...(revision ? { revision } : {}),
+        };
+      }),
+    );
+    environments.sort((left, right) => left.id.localeCompare(right.id));
+    const environmentInventoryKey = JSON.stringify(environments);
+    requireConnection();
+    if (
+      Date.now() - lastHeartbeat >= 30000 ||
+      runnerSlots !== lastRunnerSlots ||
+      environmentSlotsKey !== lastEnvironmentSlots ||
+      environmentInventoryKey !== lastEnvironmentInventory
+    ) {
       await interruptible(
         cloud.mutation(api.machines.heartbeat, {
           paused: snapshot.machine.paused,
           ...(runnerSlots === undefined ? {} : { runnerSlots }),
+          ...(environmentSlots === undefined ? {} : { environmentSlots }),
           runnerIdle:
             snapshot.preparationBusy !== true &&
             snapshot.instances.every((instance) => instance.status === "stopped") &&
@@ -235,27 +304,25 @@ export function startCloudRelay(
                   ].includes(operation.command) &&
                   ["accepted", "running"].includes(operation.status),
             ),
-          environments: await Promise.all(
-            snapshot.environments.slice(0, 100).map(async (environment) => {
-              const { id, name, os, cpu, memoryMiB, state } = environment;
-              const revision = await environmentRevision(environment);
-              return {
-                id,
-                name,
-                os,
-                cpu,
-                memoryMiB,
-                state: revision ? state : ("action_required" as const),
-                ...(revision ? { revision } : {}),
-              };
-            }),
-          ),
+          environments,
         }),
         abort.signal,
       );
       lastHeartbeat = Date.now();
       lastRunnerSlots = runnerSlots;
+      lastEnvironmentSlots = environmentSlotsKey;
+      lastEnvironments = environments;
+      lastEnvironmentInventory = environmentInventoryKey;
     }
+  }
+  function refreshHeartbeat() {
+    pendingHeartbeat ??= sendHeartbeat().finally(() => {
+      pendingHeartbeat = undefined;
+    });
+    return pendingHeartbeat;
+  }
+  async function reconcile() {
+    await refreshHeartbeat();
     const operations = await interruptible(cloud.query(api.operations.pending, {}), abort.signal);
     for (const operation of operations)
       await advanceRemoteOperation(
@@ -367,7 +434,7 @@ export function startCloudRelay(
   interval = setInterval(tick, 2000);
   authenticate();
   function requireConnection() {
-    if (!authenticated || abort.signal.aborted)
+    if (!authenticated || abort.signal.aborted || removed)
       throw new VectisError(
         "cloud_unavailable",
         "The machine cloud connection is unavailable.",
@@ -428,7 +495,7 @@ export function startCloudRelay(
       return Schema.decodeUnknownSync(CloudRepositoryReadiness)(
         await interruptible(
           cloud.action(api.githubRepositories.readiness, { input }),
-          AbortSignal.any([abort.signal, AbortSignal.timeout(30000)]),
+          AbortSignal.any([abort.signal, AbortSignal.timeout(180000)]),
         ),
       );
     },
@@ -442,6 +509,15 @@ export function startCloudRelay(
     async connectRepository(input: RepositoryConnection, signal: AbortSignal) {
       signal.throwIfAborted();
       requireConnection();
+      const heartbeatSignal = AbortSignal.any([signal, abort.signal, AbortSignal.timeout(10000)]);
+      const reported = () => lastEnvironments?.some(({ id }) => id === input.environmentId);
+      if (!reported()) {
+        if (pendingHeartbeat) await interruptible(pendingHeartbeat, heartbeatSignal);
+        heartbeatSignal.throwIfAborted();
+        if (!reported()) await interruptible(refreshHeartbeat(), heartbeatSignal);
+      }
+      heartbeatSignal.throwIfAborted();
+      requireConnection();
       return interruptible(
         cloud.action(api.githubRepositories.connectMachine, {
           accountId: input.accountId,
@@ -451,7 +527,7 @@ export function startCloudRelay(
             ? {}
             : { repositoryOwner: input.repositoryOwner }),
         }),
-        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(60000)]),
+        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(180000)]),
       ).catch((error: unknown) => {
         if (error instanceof VectisError) throw error;
         throw new VectisError(
@@ -475,6 +551,44 @@ export function startCloudRelay(
         AbortSignal.any([abort.signal, AbortSignal.timeout(10000)]),
       );
     },
+    async setCapacityMode(bindingId: string, capacityMode: CapacityMode) {
+      requireConnection();
+      await interruptible(
+        cloud.mutation(api.repositoryBindings.setCapacityModeForMachine, {
+          bindingId,
+          capacityMode,
+        }),
+        AbortSignal.any([abort.signal, AbortSignal.timeout(10000)]),
+      );
+    },
+    async openScaleSet(bindingId: string, signal: AbortSignal) {
+      signal.throwIfAborted();
+      requireConnection();
+      return decodeScaleSetGrant(
+        await interruptible(
+          cloud.action(api.githubScaleSets.open, { bindingId }),
+          AbortSignal.any([signal, abort.signal, AbortSignal.timeout(180000)]),
+        ),
+      );
+    },
+    async refreshScaleSet(bindingId: string, generation: number, signal: AbortSignal) {
+      signal.throwIfAborted();
+      requireConnection();
+      return decodeScaleSetGrant(
+        await interruptible(
+          cloud.action(api.githubScaleSets.refresh, { bindingId, generation }),
+          AbortSignal.any([signal, abort.signal, AbortSignal.timeout(180000)]),
+        ),
+      );
+    },
+    async closeScaleSet(bindingId: string, generation: number, signal: AbortSignal) {
+      signal.throwIfAborted();
+      requireConnection();
+      await interruptible(
+        cloud.action(api.githubScaleSets.close, { bindingId, generation }),
+        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(10000)]),
+      );
+    },
     async controlRun(command: RunControlCommand, key: string, signal: AbortSignal) {
       signal.throwIfAborted();
       requireConnection();
@@ -484,6 +598,13 @@ export function startCloudRelay(
       );
       return Schema.decodeUnknownSync(RunControlOutcome)(result);
     },
+    async setCacheVolume(bindingId: string, cacheVolume: { enabled: boolean; sizeGiB?: number }) {
+      requireConnection();
+      await interruptible(
+        cloud.mutation(api.repositoryBindings.setCacheVolume, { bindingId, ...cacheVolume }),
+        AbortSignal.any([abort.signal, AbortSignal.timeout(10000)]),
+      );
+    },
     async setAccess(bindingId: string, access: RepositoryAccess) {
       requireConnection();
       await interruptible(
@@ -509,7 +630,7 @@ export function startCloudRelay(
       requireConnection();
       const result = await interruptible(
         cloud.action(api.githubJobs.refresh, { bindingId, jobId }),
-        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(60000)]),
+        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(180000)]),
       );
       return Schema.decodeUnknownSync(JobRefresh)(result);
     },
@@ -592,13 +713,13 @@ export function startCloudRelay(
       bindingId: string,
       key: string,
       signal: AbortSignal,
-      request?: { jobId?: number; automatic?: boolean },
+      request?: Parameters<RunnerBroker["prepareRunner"]>[3],
     ) {
       signal.throwIfAborted();
       requireConnection();
       const value = await interruptible(
         cloud.action(api.githubRunners.prepare, { bindingId, key, ...request }),
-        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(60000)]),
+        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(180000)]),
       );
       return Schema.decodeUnknownSync(RunnerGrant)(value);
     },
@@ -607,7 +728,7 @@ export function startCloudRelay(
       requireConnection();
       const value = await interruptible(
         cloud.action(api.githubRunners.status, { id: leaseId }),
-        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(10000)]),
+        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(180000)]),
       );
       return Schema.decodeUnknownSync(RunnerStatus)(value);
     },
@@ -616,7 +737,7 @@ export function startCloudRelay(
       requireConnection();
       await interruptible(
         cloud.action(api.githubRunners.release, { id }),
-        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(60000)]),
+        AbortSignal.any([signal, abort.signal, AbortSignal.timeout(180000)]),
       );
     },
     async repositories() {
@@ -641,6 +762,7 @@ export function startCloudRelay(
     },
     async close() {
       const pendingToken = tokenRequest;
+      const heartbeat = pendingHeartbeat;
       abort.abort();
       if (interval) clearInterval(interval);
       unsubscribe();
@@ -655,6 +777,7 @@ export function startCloudRelay(
       await cloud.close();
       await pendingToken?.catch(() => {});
       await active;
+      await heartbeat?.catch(() => {});
     },
   };
 }
diff --git a/packages/client/src/index.test.ts b/packages/client/src/index.test.ts
index fe34e672..96faf6f2 100644
--- a/packages/client/src/index.test.ts
+++ b/packages/client/src/index.test.ts
@@ -79,3 +79,37 @@ test("cancelling an operation wait aborts its in-flight HTTP request", async ()
     await new Promise<void>((resolve) => server.close(() => resolve()));
   }
 });
+
+test("wait polls only its operation endpoint and returns the observed terminal result", async () => {
+  const paths: Array<string | undefined> = [];
+  const statuses = ["accepted", "running", "succeeded"];
+  const server = createServer((request, response) => {
+    paths.push(request.url);
+    response.setHeader("Content-Type", "application/json");
+    response.end(
+      JSON.stringify({
+        id: "one-operation",
+        key: "one",
+        command: "machine.pause",
+        status: statuses.shift() ?? "succeeded",
+        message: "Observed",
+        createdAt: "2026-10-16T00:00:00Z",
+        updatedAt: "2026-10-16T00:00:00Z",
+        result: { verified: true },
+      }),
+    );
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Missing server address");
+  const client = new VectisClient({ url: `http://127.0.0.1:${address.port}`, token: "synthetic" });
+  try {
+    expect(await client.wait("one-operation")).toMatchObject({
+      status: "succeeded",
+      result: { verified: true },
+    });
+    expect(paths).toEqual(Array(3).fill("/v1/operations/one-operation"));
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+});
diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
index 075dbb39..e51cc2a8 100644
--- a/packages/client/src/index.ts
+++ b/packages/client/src/index.ts
@@ -7,6 +7,8 @@ import { StorageReport } from "../../protocol/src/storage.js";
 import { ServiceLog } from "../../protocol/src/logs.js";
 import {
   ApiError,
+  Activity,
+  ActivityDetail,
   Operation,
   Snapshot,
   VectisError,
@@ -15,20 +17,6 @@ import {
   type ShutdownOptions,
 } from "../../protocol/src/index.js";
 
-// An activity and its operations both come from the snapshot, so every surface reads them the
-// same way, locally and through remote control.
-export function activitiesOf(snapshot: Snapshot) {
-  return snapshot.activities ?? [];
-}
-export function activityOf(snapshot: Snapshot, id: string) {
-  const activity = activitiesOf(snapshot).find((item) => item.id === id);
-  if (!activity) throw new VectisError("activity_missing", "The activity was not found.");
-  return {
-    activity,
-    operations: snapshot.operations.filter((operation) => operation.activityId === id),
-  };
-}
-
 export class VectisClient {
   constructor(readonly connection: Pick<Connection, "url" | "token">) {
     const url = new URL(connection.url);
@@ -127,15 +115,24 @@ export class VectisClient {
     );
   }
   async operation(id: string, signal?: AbortSignal) {
-    const operation = (await this.status(signal)).operations.find((item) => item.id === id);
-    if (!operation) throw new VectisError("operation_missing", "The operation was not found.");
-    return operation;
+    return Schema.decodeUnknownSync(Operation)(
+      await this.request(`/v1/operations/${encodeURIComponent(id)}`, undefined, signal),
+    );
+  }
+  async operationByKey(key: string, signal?: AbortSignal) {
+    return Schema.decodeUnknownSync(Operation)(
+      await this.request(`/v1/operations?${new URLSearchParams({ key })}`, undefined, signal),
+    );
   }
   async activities(signal?: AbortSignal) {
-    return activitiesOf(await this.status(signal));
+    return Schema.decodeUnknownSync(Schema.Array(Activity))(
+      await this.request("/v1/activities", undefined, signal),
+    );
   }
   async activity(id: string, signal?: AbortSignal) {
-    return activityOf(await this.status(signal), id);
+    return Schema.decodeUnknownSync(ActivityDetail)(
+      await this.request(`/v1/activities/${encodeURIComponent(id)}`, undefined, signal),
+    );
   }
   async settle(command: Command, key: string, signal?: AbortSignal): Promise<Operation> {
     const operation = await this.submit(command, key, signal);
@@ -144,7 +141,7 @@ export class VectisClient {
   }
   async wait(id: string, signal: AbortSignal = AbortSignal.timeout(120000)): Promise<Operation> {
     while (!signal.aborted) {
-      const snapshot = await this.status(signal).catch((error) => {
+      const operation = await this.operation(id, signal).catch((error) => {
         if (signal.aborted)
           throw new VectisError(
             "wait_cancelled",
@@ -152,8 +149,6 @@ export class VectisClient {
           );
         throw error;
       });
-      const operation = snapshot.operations.find((item) => item.id === id);
-      if (!operation) throw new VectisError("operation_missing", "The operation was not found.");
       if (operation.status !== "accepted" && operation.status !== "running") return operation;
       await new Promise<void>((resolve, reject) => {
         const onAbort = () => {
diff --git a/packages/client/src/inspection.test.ts b/packages/client/src/inspection.test.ts
index 06ddc8f6..386b78ff 100644
--- a/packages/client/src/inspection.test.ts
+++ b/packages/client/src/inspection.test.ts
@@ -6,6 +6,7 @@ import { startService } from "../../../apps/server/src/http.js";
 import { VectisClient } from "./index.js";
 import { VectisError } from "../../protocol/src/index.js";
 import { answerInspection } from "./inspection.js";
+import { activityFor } from "../../../apps/server/src/activities.js";
 
 test("inspection uses the authenticated local contract and reports unavailable cloud prerequisites", async () => {
   const home = await mkdtemp(join(tmpdir(), "vectis-inspection-"));
@@ -76,9 +77,10 @@ test("job log inspections use the authenticated HTTP contract and fit the encode
   const server = await startService({ home });
   try {
     const local = new VectisClient(server.connection);
+    const maxResponseBytes = 1024;
     const log = {
-      text: "\u0000".repeat(32768),
-      next: 32768,
+      text: "\u0000".repeat(128),
+      next: 128,
       status: "in_progress" as const,
       complete: false,
       truncated: true,
@@ -89,20 +91,26 @@ test("job log inspections use the authenticated HTTP contract and fit the encode
       JSON.stringify({ name: "job.logs", bindingId: "binding", jobId: 4, after: 0 }),
       local,
       signal,
+      maxResponseBytes,
     );
-    expect(Buffer.byteLength(encoded)).toBeLessThan(262144);
+    expect(Buffer.byteLength(encoded)).toBeLessThan(maxResponseBytes);
     expect(JSON.parse(encoded)).toEqual({ ok: true, result: log });
     expect(read).toHaveBeenCalledWith(
       { bindingId: "binding", jobId: 4, after: 0 },
       expect.any(AbortSignal),
     );
-    read.mockResolvedValue({ ...log, text: "\u00e9".repeat(140000) });
+    const oversized = { ...log, text: "\u00e9".repeat(600) };
+    const oversizedJson = JSON.stringify({ ok: true, result: oversized });
+    expect(oversizedJson.length).toBeLessThan(maxResponseBytes);
+    expect(Buffer.byteLength(oversizedJson)).toBeGreaterThan(maxResponseBytes);
+    read.mockResolvedValue(oversized);
     expect(
       JSON.parse(
         await answerInspection(
           '{"name":"job.logs","bindingId":"binding","jobId":4}',
           local,
           signal,
+          maxResponseBytes,
         ),
       ),
     ).toMatchObject({ ok: false, code: "query_result_too_large" });
@@ -119,3 +127,73 @@ test("job log inspections use the authenticated HTTP contract and fit the encode
     await rm(home, { recursive: true, force: true });
   }
 });
+
+test("operation and activity inspections bypass a status snapshot larger than the remote cap", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-targeted-inspection-"));
+  const server = await startService({ home });
+  try {
+    const local = new VectisClient(server.connection);
+    const maxResponseBytes = 2 * 1024;
+    const command = { type: "job.scan", bindingId: "binding" } as const;
+    const operation = server.store.accept(
+      "target",
+      "target",
+      command.type,
+      activityFor("target", command),
+      "target",
+    ).operation;
+    for (let index = 0; index < 3; index++) {
+      const other = server.store.accept(`other-${index}`, "other", "machine.pause").operation;
+      server.store.update(other, { status: "succeeded", result: { text: "x".repeat(512) } });
+    }
+    const signal = new AbortController().signal;
+    const snapshot = await local.status(signal);
+    expect(Buffer.byteLength(JSON.stringify({ ok: true, result: snapshot }))).toBeGreaterThan(
+      maxResponseBytes,
+    );
+    expect(
+      JSON.parse(await answerInspection('{"name":"status"}', local, signal, maxResponseBytes)),
+    ).toMatchObject({
+      ok: false,
+      code: "query_result_too_large",
+    });
+    const status = vi.spyOn(local, "status").mockRejectedValue(new Error("Unexpected full status"));
+    for (const query of [
+      { name: "operation", id: operation.id },
+      { name: "operation.key", key: "target" },
+    ]) {
+      const encoded = await answerInspection(
+        JSON.stringify(query),
+        local,
+        signal,
+        maxResponseBytes,
+      );
+      expect(Buffer.byteLength(encoded)).toBeLessThan(maxResponseBytes);
+      expect(JSON.parse(encoded)).toEqual({ ok: true, result: operation });
+    }
+    expect(
+      JSON.parse(
+        await answerInspection(
+          '{"name":"activity","id":"target"}',
+          local,
+          signal,
+          maxResponseBytes,
+        ),
+      ),
+    ).toMatchObject({
+      ok: true,
+      result: { activity: { id: "target" }, operations: [operation] },
+    });
+    expect(
+      JSON.parse(await answerInspection('{"name":"activities"}', local, signal, maxResponseBytes)),
+    ).toMatchObject({
+      ok: true,
+      result: [{ id: "target" }],
+    });
+    expect(status).not.toHaveBeenCalled();
+    status.mockRestore();
+  } finally {
+    await server.close();
+    await rm(home, { recursive: true, force: true });
+  }
+});
diff --git a/packages/client/src/inspection.ts b/packages/client/src/inspection.ts
index 21966ee5..c9c8df92 100644
--- a/packages/client/src/inspection.ts
+++ b/packages/client/src/inspection.ts
@@ -8,6 +8,7 @@ export async function answerInspection(
   queryJson: string,
   local: VectisClient,
   signal: AbortSignal,
+  maxResponseBytes = 256 * 1024,
 ) {
   try {
     signal.throwIfAborted();
@@ -38,13 +39,19 @@ export async function answerInspection(
         }
         case "operation":
           return local.operation(query.id, signal);
+        case "operation.key":
+          return local.operationByKey(query.key, signal);
+        case "activities":
+          return local.activities(signal);
+        case "activity":
+          return local.activity(query.id, signal);
         case "logs":
           return local.logs(query.lines);
       }
     })();
     signal.throwIfAborted();
     const encoded = JSON.stringify({ ok: true, result });
-    if (new TextEncoder().encode(encoded).byteLength > 262144)
+    if (new TextEncoder().encode(encoded).byteLength > maxResponseBytes)
       throw new VectisError(
         "query_result_too_large",
         "The inspection exceeds the remote response limit.",
diff --git a/packages/client/src/machine-auth.test.ts b/packages/client/src/machine-auth.test.ts
index 83774787..d3e895df 100644
--- a/packages/client/src/machine-auth.test.ts
+++ b/packages/client/src/machine-auth.test.ts
@@ -1,7 +1,10 @@
 import { afterEach, expect, test, vi } from "vitest";
 import { credentialAccount, machineEndpoint, machineTokenFetcher } from "./machine-auth.js";
 
-afterEach(() => vi.unstubAllGlobals());
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
 const connection = {
   deploymentUrl: "https://example-123.convex.cloud",
   machineId: "machine",
@@ -43,3 +46,80 @@ test("token reuse, forced refresh and removal do not leak a stale token", async
   expect(get).toHaveBeenCalledWith(credentialAccount(connection), expect.any(AbortSignal));
   expect(request.mock.calls[0]?.[1]).toMatchObject({ redirect: "error" });
 });
+
+test.each(["fresh", "original"])(
+  "forced refresh retries an identical token once and returns %s",
+  async (retriedToken) => {
+    vi.useFakeTimers();
+    const request = vi
+      .fn()
+      .mockResolvedValueOnce(Response.json({ token: "original", expiresAt: Date.now() + 300000 }))
+      .mockResolvedValueOnce(Response.json({ token: "original", expiresAt: Date.now() + 300000 }))
+      .mockResolvedValueOnce(
+        Response.json({ token: retriedToken, expiresAt: Date.now() + 300000 }),
+      );
+    vi.stubGlobal("fetch", request);
+    const fetchToken = machineTokenFetcher(
+      connection,
+      { get: async () => "secret" },
+      new AbortController().signal,
+    );
+    expect(await fetchToken({ forceRefreshToken: false })).toBe("original");
+    const refreshed = fetchToken({ forceRefreshToken: true });
+    const resolved = vi.fn();
+    void refreshed.then(resolved);
+    await vi.advanceTimersByTimeAsync(1099);
+    expect(request).toHaveBeenCalledTimes(2);
+    expect(resolved).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(resolved).toHaveBeenCalledWith(retriedToken);
+    expect(await refreshed).toBe(retriedToken);
+    expect(request).toHaveBeenCalledTimes(3);
+    expect(await fetchToken({ forceRefreshToken: false })).toBe(retriedToken);
+    expect(request).toHaveBeenCalledTimes(3);
+    expect(vi.getTimerCount()).toBe(0);
+  },
+);
+
+test("cancelling an identical-token retry releases its timer without another request", async () => {
+  vi.useFakeTimers();
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => Response.json({ token: "original", expiresAt: Date.now() + 300000 })),
+  );
+  const abort = new AbortController();
+  const fetchToken = machineTokenFetcher(connection, { get: async () => "secret" }, abort.signal);
+  await fetchToken({ forceRefreshToken: false });
+  const refreshed = fetchToken({ forceRefreshToken: true });
+  const rejected = expect(refreshed).rejects.toMatchObject({ name: "AbortError" });
+  await vi.advanceTimersByTimeAsync(500);
+  abort.abort();
+  await rejected;
+  expect(fetch).toHaveBeenCalledTimes(2);
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+test("a rejected retry clears the cached token and preserves the removal error", async () => {
+  vi.useFakeTimers();
+  const request = vi
+    .fn()
+    .mockResolvedValueOnce(Response.json({ token: "original", expiresAt: Date.now() + 300000 }))
+    .mockResolvedValueOnce(Response.json({ token: "original", expiresAt: Date.now() + 300000 }))
+    .mockResolvedValue(new Response(null, { status: 401 }));
+  vi.stubGlobal("fetch", request);
+  const fetchToken = machineTokenFetcher(
+    connection,
+    { get: async () => "secret" },
+    new AbortController().signal,
+  );
+  await fetchToken({ forceRefreshToken: false });
+  const rejected = expect(fetchToken({ forceRefreshToken: true })).rejects.toMatchObject({
+    code: "machine_rejected",
+  });
+  await vi.advanceTimersByTimeAsync(1100);
+  await rejected;
+  await expect(fetchToken({ forceRefreshToken: false })).rejects.toMatchObject({
+    code: "machine_rejected",
+  });
+  expect(request).toHaveBeenCalledTimes(4);
+});
diff --git a/packages/client/src/machine-auth.ts b/packages/client/src/machine-auth.ts
index 476e43da..7738a778 100644
--- a/packages/client/src/machine-auth.ts
+++ b/packages/client/src/machine-auth.ts
@@ -34,36 +34,60 @@ export function machineTokenFetcher(
   const endpoint = machineEndpoint(connection.deploymentUrl);
   const account = credentialAccount(connection);
   let cached: typeof Token.Type | undefined;
+  let previousToken: string | undefined;
   return async ({ forceRefreshToken }: { forceRefreshToken: boolean }) => {
     signal.throwIfAborted();
     if (!forceRefreshToken && cached && cached.expiresAt > Date.now() + 30000) return cached.token;
     cached = undefined;
     const secret = await credentials.get(account, signal);
     if (!secret) return null;
-    const response = await fetch(endpoint, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ machineId: connection.machineId, secret }),
-      redirect: "error",
-      signal: AbortSignal.any([signal, AbortSignal.timeout(15000)]),
-    });
-    if (response.status === 401)
-      throw new VectisError(
-        "machine_rejected",
-        "This machine is no longer connected to the account.",
-        "Run vectis cloud disconnect on this Mac, then pair it again.",
-      );
-    if (!response.ok)
-      throw new VectisError(
-        "cloud_unavailable",
-        "Machine authentication is temporarily unavailable.",
-      );
-    cached = Schema.decodeUnknownSync(Token)(await response.json());
-    if (cached.expiresAt <= Date.now())
-      throw new VectisError(
-        "invalid_machine_token",
-        "Machine authentication returned an expired token.",
-      );
+    const request = async () => {
+      signal.throwIfAborted();
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ machineId: connection.machineId, secret }),
+        redirect: "error",
+        signal: AbortSignal.any([signal, AbortSignal.timeout(15000)]),
+      });
+      if (response.status === 401)
+        throw new VectisError(
+          "machine_rejected",
+          "This machine is no longer connected to the account.",
+          "Run vectis cloud disconnect on this Mac, then pair it again.",
+        );
+      if (!response.ok)
+        throw new VectisError(
+          "cloud_unavailable",
+          "Machine authentication is temporarily unavailable.",
+        );
+      const token = Schema.decodeUnknownSync(Token)(await response.json());
+      if (token.expiresAt <= Date.now())
+        throw new VectisError(
+          "invalid_machine_token",
+          "Machine authentication returned an expired token.",
+        );
+      return token;
+    };
+    let token = await request();
+    if (forceRefreshToken && token.token === previousToken) {
+      // Convex stops scheduling refreshes when it receives the same token again.
+      await new Promise<void>((resolve, reject) => {
+        signal.throwIfAborted();
+        const onAbort = () => {
+          clearTimeout(timer);
+          reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+          signal.removeEventListener("abort", onAbort);
+          resolve();
+        }, 1100);
+        signal.addEventListener("abort", onAbort, { once: true });
+      });
+      token = await request();
+    }
+    cached = token;
+    previousToken = token.token;
     return cached.token;
   };
 }
diff --git a/packages/client/src/remote-operation.ts b/packages/client/src/remote-operation.ts
index c3e8a427..fcd97ce2 100644
--- a/packages/client/src/remote-operation.ts
+++ b/packages/client/src/remote-operation.ts
@@ -3,7 +3,7 @@ import { Schema } from "effect";
 import { redact } from "./redact.js";
 import type { FunctionArgs, FunctionReturnType } from "convex/server";
 import type { api } from "../../../convex/_generated/api.js";
-import { decodeCommand } from "../../protocol/src/index.js";
+import { decodeCommand, VectisError } from "../../protocol/src/index.js";
 import type { VectisClient } from "./index.js";
 
 export type RemoteOperation = FunctionReturnType<typeof api.operations.pending>[number];
@@ -11,7 +11,7 @@ export type Acknowledgement = FunctionArgs<typeof api.operations.acknowledge>;
 
 export async function advanceRemoteOperation(
   remote: RemoteOperation,
-  local: Pick<VectisClient, "submit" | "status">,
+  local: Pick<VectisClient, "submit" | "operationByKey">,
   acknowledge: (args: Acknowledgement) => Promise<unknown>,
   signal: AbortSignal,
 ) {
@@ -32,9 +32,10 @@ export async function advanceRemoteOperation(
   }
   if (remote.phase !== "claimed" && remote.phase !== "running") return;
   if (remote.cancelRequested) {
-    const operation = (await local.status(signal)).operations.find(
-      (item) => item.key === `remote:${remote._id}`,
-    );
+    const operation = await local.operationByKey(`remote:${remote._id}`, signal).catch((error) => {
+      if (error instanceof VectisError && error.code === "operation_missing") return undefined;
+      throw error;
+    });
     if (!operation) {
       if (remote.phase === "claimed") await acknowledge({ id: remote._id, phase: "cancelled" });
       else
@@ -80,6 +81,12 @@ export async function advanceRemoteOperation(
       operationId: operation.id,
       status: operation.status,
       message: redact(operation.message).slice(0, 1000),
+      ...(typeof operation.result === "object" &&
+      operation.result !== null &&
+      "code" in operation.result &&
+      operation.result.code === "cache_volume_requires_guest_sudo"
+        ? { code: operation.result.code }
+        : {}),
       resultAvailableLocally: operation.result !== undefined,
     }),
   });
diff --git a/packages/client/src/remote.test.ts b/packages/client/src/remote.test.ts
index 45fd372a..0a68fe46 100644
--- a/packages/client/src/remote.test.ts
+++ b/packages/client/src/remote.test.ts
@@ -1,6 +1,8 @@
 import { expect, test, vi } from "vitest";
 import { ControllerClient } from "./controller.js";
 import { RemoteClient } from "./remote.js";
+import type { ActivityDetail } from "../../protocol/src/index.js";
+import type { RunnerProgress } from "../../protocol/src/runners.js";
 
 function fixture() {
   const controller = new ControllerClient(
@@ -25,6 +27,94 @@ const record = {
   createdAt: 1000,
   updatedAt: 1000,
 };
+
+test("remote detail and activity-list reads submit targeted inspections instead of status", async () => {
+  const { request, client } = fixture();
+  const result: RunnerProgress = {
+    bindingId: "binding",
+    environmentId: "linux",
+    leaseKey: "local-operation",
+    stage: "finished",
+    cache: { attached: true, writeBack: "granted", promoted: true },
+    phases: [{ name: "vm_start", startedAt: "2026-01-01", endedAt: "2026-01-01" }],
+  };
+  const detail: ActivityDetail = {
+    activity: {
+      id: "activity",
+      kind: "vectis",
+      subject: { type: "command", command: "runner.run" },
+      rootOperationId: "local-operation",
+      createdAt: "2026-01-01",
+      updatedAt: "2026-01-01",
+      status: "succeeded",
+      message: "Done",
+    },
+    operations: [
+      {
+        id: "local-operation",
+        key: "local-key",
+        command: "runner.run",
+        result,
+        activityId: "activity",
+        status: "succeeded",
+        message: "Done",
+        createdAt: "2026-01-01",
+        updatedAt: "2026-01-01",
+      },
+    ],
+  };
+  const cases = [
+    {
+      query: { name: "activity", id: "activity" },
+      result: detail,
+      read: () => client.activity("activity"),
+    },
+    { query: { name: "activities" }, result: [detail.activity], read: () => client.activities() },
+    {
+      query: { name: "operation", id: "local-operation" },
+      result: detail.operations[0],
+      read: () => client.localOperation("local-operation"),
+    },
+    {
+      query: { name: "operation.key", key: "local-key" },
+      result: detail.operations[0],
+      read: () => client.operationByKey("local-key"),
+    },
+  ];
+  for (const { query, result, read } of cases) {
+    request.mockClear();
+    request.mockResolvedValueOnce({ queryId: "query" }).mockResolvedValueOnce({
+      pending: false,
+      responseJson: JSON.stringify({ ok: true, result }),
+    });
+    expect(await read()).toEqual(result);
+    expect(request.mock.calls[0]?.[0]).toMatchObject({ type: "query.submit", query });
+  }
+});
+test("remote provisioning carries host paths and inline setup data through the shared command", async () => {
+  const { request, client } = fixture();
+  const command = {
+    type: "environment.provision",
+    id: "derived",
+    from: "parent",
+    imageDirectory: "/selected-host/images/derived",
+    setupScript: "printf 'guest setup'",
+    runner: false,
+  } as const;
+  request
+    .mockResolvedValueOnce({ operationId: "remote1" })
+    .mockResolvedValueOnce({ ...record, commandJson: JSON.stringify(command) });
+  expect(await client.submit(command, "derive")).toMatchObject({
+    status: "accepted",
+    command: "environment.provision",
+  });
+  expect(request.mock.calls[0]?.[0]).toEqual({
+    type: "operation.submit",
+    machineId: "machine1",
+    key: "derive",
+    command,
+  });
+});
 test("activity cancellation is replayed on the machine with the local activity identity", async () => {
   const { request, client } = fixture();
   const command = { type: "activity.cancel", id: "local-activity" } as const;
@@ -418,3 +508,27 @@ test("remote readiness preserves the original failure when capability discovery
     message: "The original inspection failed.",
   });
 });
+
+test.each([
+  { type: "repository.cache", bindingId: "binding", enabled: true, sizeGiB: 30 },
+  { type: "repository.cache", bindingId: "binding", enabled: false },
+  { type: "cache.clear", bindingId: "binding" },
+] as const)(
+  "remote $type preserves the binding settings and local operation contract",
+  async (command) => {
+    const { request, client } = fixture();
+    request
+      .mockResolvedValueOnce({ operationId: "remote1" })
+      .mockResolvedValueOnce({ ...record, commandJson: JSON.stringify(command) });
+    expect(await client.submit(command, "cache")).toMatchObject({
+      status: "accepted",
+      command: command.type,
+    });
+    expect(request.mock.calls[0]?.[0]).toEqual({
+      type: "operation.submit",
+      machineId: "machine1",
+      key: "cache",
+      command,
+    });
+  },
+);
diff --git a/packages/client/src/remote.ts b/packages/client/src/remote.ts
index df98be85..37b249c4 100644
--- a/packages/client/src/remote.ts
+++ b/packages/client/src/remote.ts
@@ -1,7 +1,12 @@
 import { RepositoryReadiness, RepositoryReadinessInput } from "../../protocol/src/readiness.js";
 import { randomUUID } from "node:crypto";
 import { ServiceLog } from "../../protocol/src/logs.js";
-import { Snapshot, Operation as OperationSchema } from "../../protocol/src/index.js";
+import {
+  Activity,
+  ActivityDetail,
+  Snapshot,
+  Operation as OperationSchema,
+} from "../../protocol/src/index.js";
 import { LocalQuery } from "../../protocol/src/controller.js";
 import { Diagnostics } from "../../protocol/src/diagnostics.js";
 import { StorageReport } from "../../protocol/src/storage.js";
@@ -17,7 +22,6 @@ import {
   type Operation,
 } from "../../protocol/src/index.js";
 import { ControllerClient } from "./controller.js";
-import { activitiesOf, activityOf } from "./index.js";
 
 const Record = Schema.Struct({
   _id: Identifier,
@@ -176,10 +180,19 @@ export class RemoteClient {
     return Schema.decodeUnknownSync(Snapshot)(await this.inspect({ name: "status" }, signal));
   }
   async activities(signal?: AbortSignal) {
-    return activitiesOf(await this.status(signal));
+    return Schema.decodeUnknownSync(Schema.Array(Activity))(
+      await this.inspect({ name: "activities" }, signal),
+    );
   }
   async activity(id: string, signal?: AbortSignal) {
-    return activityOf(await this.status(signal), id);
+    return Schema.decodeUnknownSync(ActivityDetail)(
+      await this.inspect({ name: "activity", id }, signal),
+    );
+  }
+  async operationByKey(key: string, signal?: AbortSignal) {
+    return Schema.decodeUnknownSync(OperationSchema)(
+      await this.inspect({ name: "operation.key", key }, signal),
+    );
   }
   async storage() {
     return Schema.decodeUnknownSync(StorageReport)(await this.inspect({ name: "storage" }));
diff --git a/packages/github/src/api-request.ts b/packages/github/src/api-request.ts
new file mode 100644
index 00000000..889f6769
--- /dev/null
+++ b/packages/github/src/api-request.ts
@@ -0,0 +1,190 @@
+export class GitHubApiError extends Error {
+  constructor(readonly status: number) {
+    super(`GitHub API request failed (${status}).`);
+  }
+}
+
+export class GitHubUnavailableError extends GitHubApiError {
+  readonly code = "github_unavailable";
+  readonly nextStep = "Check GitHub availability and retry.";
+  constructor(status = 0) {
+    super(status);
+    this.message = "GitHub is temporarily unavailable.";
+  }
+}
+
+export class GitHubRateLimitError extends GitHubApiError {
+  readonly code = "github_rate_limited";
+  readonly nextStep = "Wait for the GitHub rate limit to reset, then retry.";
+  constructor(
+    status: number,
+    readonly resetAt?: number,
+  ) {
+    super(status);
+    this.message = "GitHub API rate limit exceeded.";
+  }
+}
+
+export class GitHubUncertainError extends GitHubApiError {
+  constructor(status = 0) {
+    super(status);
+    this.message = "The GitHub request outcome could not be confirmed.";
+  }
+}
+
+export class GitHubPermissionError extends GitHubApiError {
+  readonly code = "github_app_permission_required";
+  readonly nextStep =
+    "Approve the updated Vectis GitHub App permissions on GitHub (Settings -> Applications), then retry.";
+  constructor(status = 403) {
+    super(status);
+    this.message = "The Vectis GitHub App needs updated Actions write permission.";
+  }
+}
+
+type Method = "GET" | "HEAD" | "DELETE" | "PUT" | "POST";
+type Result = { status: number; body: unknown };
+
+function wait(delay: number, signal?: AbortSignal) {
+  signal?.throwIfAborted();
+  return new Promise<void>((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }, delay);
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
+
+async function readText(response: Response) {
+  const reader = response.body?.getReader();
+  if (!reader) return "";
+  let size = 0;
+  const chunks: Uint8Array[] = [];
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      size += value.length;
+      if (size > 1024 * 1024) throw new Error("GitHub response exceeded its limit.");
+      chunks.push(value);
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function headerTime(headers: Headers, name: string, multiplier: number) {
+  const value = headers.get(name);
+  if (value === null || value.trim() === "") return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number * multiplier : undefined;
+}
+
+export async function githubRequest(input: {
+  token: string;
+  path: string;
+  method: Method;
+  body?: unknown;
+  signal?: AbortSignal | undefined;
+  responseBody: "json" | "discard";
+  budgetMs: number;
+  invalidate: () => void;
+}): Promise<Result> {
+  const { token, path, method, body, signal, responseBody } = input;
+  if (!path.startsWith("/") || path.startsWith("//") || path.includes(".."))
+    throw new Error("Invalid GitHub API path.");
+  const safe = method !== "POST" || /^\/app\/installations\/\d+\/access_tokens$/.test(path);
+  const deadline = Date.now() + input.budgetMs;
+  let failure: GitHubUnavailableError | GitHubRateLimitError = new GitHubUnavailableError();
+  for (let attempt = 0; attempt < 4; attempt++) {
+    signal?.throwIfAborted();
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw failure;
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(), Math.min(15000, remaining));
+    let response: Response | undefined;
+    let text = "";
+    let read = false;
+    try {
+      response = await fetch(`https://api.github.com${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: "application/vnd.github+json",
+          "X-GitHub-Api-Version": "2026-03-10",
+          "Content-Type": "application/json",
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        redirect: "error",
+        signal: signal ? AbortSignal.any([signal, abort.signal]) : abort.signal,
+      });
+      if (response.status === 401) input.invalidate();
+      if (response.ok && (responseBody === "discard" || method === "HEAD")) {
+        await response.body?.cancel().catch(() => {});
+        return { status: response.status, body: null };
+      }
+      text = await readText(response);
+      read = true;
+    } catch (error) {
+      signal?.throwIfAborted();
+      if (!safe) throw new GitHubUncertainError(response?.status);
+      if (
+        response &&
+        !response.ok &&
+        response.status < 500 &&
+        ![403, 429].includes(response.status)
+      )
+        throw new GitHubApiError(response.status);
+      if (
+        response?.ok &&
+        error instanceof Error &&
+        error.message === "GitHub response exceeded its limit."
+      )
+        throw error;
+      failure = new GitHubUnavailableError(response?.status);
+    } finally {
+      clearTimeout(timer);
+    }
+    let requiredWait = 0;
+    if (response && !response.ok) {
+      const rateLimited =
+        response.status === 429 ||
+        (response.status === 403 &&
+          (response.headers.get("x-ratelimit-remaining") === "0" ||
+            /secondary rate limit/i.test(text)));
+      const retryAfter = headerTime(response.headers, "retry-after", 1000);
+      const reset = headerTime(response.headers, "x-ratelimit-reset", 1000);
+      const resetAt = Math.max(retryAfter === undefined ? 0 : Date.now() + retryAfter, reset ?? 0);
+      requiredWait = Math.max(retryAfter ?? 0, (reset ?? 0) - Date.now());
+      if (rateLimited) {
+        failure = new GitHubRateLimitError(response.status, resetAt || undefined);
+        if (retryAfter === undefined && reset === undefined) requiredWait = 60000 * 2 ** attempt;
+      } else if (response.status >= 500) {
+        if (!safe) throw new GitHubUncertainError(response.status);
+        failure = new GitHubUnavailableError(response.status);
+        if (![500, 502, 503, 504].includes(response.status)) throw failure;
+      } else if (
+        response.status === 403 &&
+        text.includes("Resource not accessible by integration")
+      ) {
+        throw new GitHubPermissionError();
+      } else throw new GitHubApiError(response.status);
+    } else if (response?.ok && read) {
+      if (!response.body && ![201, 202, 204].includes(response.status))
+        throw new Error("GitHub returned no response body.");
+      return { status: response.status, body: text ? JSON.parse(text) : null };
+    }
+    if (!safe || attempt === 3) throw failure;
+    const delay = Math.max(requiredWait, Math.random() * 500 * 2 ** attempt);
+    if (delay >= deadline - Date.now()) throw failure;
+    await wait(delay, signal);
+  }
+  throw failure;
+}
diff --git a/packages/github/src/app-client-retry.test.ts b/packages/github/src/app-client-retry.test.ts
new file mode 100644
index 00000000..ec9e35ae
--- /dev/null
+++ b/packages/github/src/app-client-retry.test.ts
@@ -0,0 +1,328 @@
+import { generateKeyPairSync } from "node:crypto";
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+import { GitHubAppClient, GitHubUncertainError } from "./app-client.js";
+
+const privateKey = generateKeyPairSync("rsa", { modulusLength: 2048 })
+  .privateKey.export({ format: "pem", type: "pkcs8" })
+  .toString();
+function client(budgetMs = 45000) {
+  return new GitHubAppClient(
+    { appId: 42, clientId: expect.getState().currentTestName ?? "test", privateKey },
+    { budgetMs },
+  );
+}
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date("2026-10-16T12:00:00Z"));
+  vi.spyOn(Math, "random").mockReturnValue(0.5);
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => {
+      throw new Error("Unexpected fetch");
+    }),
+  );
+});
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+async function complete<T>(request: Promise<T>): Promise<T> {
+  const settled = request.then(
+    (value) => ({ value }),
+    (error: unknown) => ({ error }),
+  );
+  await vi.runAllTimersAsync();
+  const result = await settled;
+  if ("error" in result) throw result.error;
+  return result.value;
+}
+
+test.each([500, 502, 503, 504])("retries %s with jitter then succeeds", async (status) => {
+  const start = Date.now();
+  const fetch = vi
+    .fn()
+    .mockResolvedValueOnce(new Response(null, { status }))
+    .mockResolvedValueOnce(Response.json({ ok: true }));
+  vi.stubGlobal("fetch", fetch);
+  await expect(complete(client().request("token", "/test"))).resolves.toEqual({ ok: true });
+  expect(fetch).toHaveBeenCalledTimes(2);
+  expect(Date.now() - start).toBe(250);
+});
+
+test("honors retry-after on 429", async () => {
+  const start = Date.now();
+  const times: number[] = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => {
+      times.push(Date.now());
+      return times.length === 1
+        ? new Response(null, { status: 429, headers: { "retry-after": "2" } })
+        : Response.json({ ok: true });
+    }),
+  );
+  await expect(complete(client().request("token", "/test"))).resolves.toEqual({ ok: true });
+  expect(times).toEqual([start, start + 2000]);
+});
+
+test("honors the later of rate-limit reset and retry-after on 403", async () => {
+  const start = Date.now();
+  const times: number[] = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => {
+      times.push(Date.now());
+      return times.length === 1
+        ? Response.json(
+            { message: "API rate limit exceeded" },
+            {
+              status: 403,
+              headers: {
+                "x-ratelimit-remaining": "0",
+                "x-ratelimit-reset": String(start / 1000 + 3),
+                "retry-after": "1",
+              },
+            },
+          )
+        : Response.json({ ok: true });
+    }),
+  );
+  await complete(client().request("token", "/test"));
+  expect(times).toEqual([start, start + 3000]);
+});
+
+test("fails immediately when a rate-limit wait would exhaust the budget", async () => {
+  const start = Date.now();
+  const fetch = vi.fn(async () =>
+    Response.json(
+      { message: "Resource not accessible by integration" },
+      {
+        status: 403,
+        headers: {
+          "x-ratelimit-remaining": "0",
+          "x-ratelimit-reset": String(start / 1000 + 90),
+        },
+      },
+    ),
+  );
+  vi.stubGlobal("fetch", fetch);
+  await expect(complete(client().request("token", "/test"))).rejects.toMatchObject({
+    code: "github_rate_limited",
+    status: 403,
+    resetAt: start + 90000,
+  });
+  expect(Date.now()).toBe(start);
+  expect(fetch).toHaveBeenCalledTimes(1);
+});
+
+test("secondary limits without timing headers require at least a minute", async () => {
+  const fetch = vi.fn(async () =>
+    Response.json({ message: "You have exceeded a secondary rate limit." }, { status: 403 }),
+  );
+  vi.stubGlobal("fetch", fetch);
+  await expect(complete(client().request("token", "/test"))).rejects.toMatchObject({
+    code: "github_rate_limited",
+    status: 403,
+  });
+  expect(fetch).toHaveBeenCalledTimes(1);
+});
+
+test.each(["network", "timeout", 502] as const)(
+  "jitconfig POST is uncertain after %s and is never retried",
+  async (failure) => {
+    const fetch = vi.fn(async (_url: string, init?: RequestInit) => {
+      if (failure === "network") throw new TypeError("connection lost, private token");
+      if (failure === "timeout")
+        return new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener("abort", () => reject(init.signal?.reason), {
+            once: true,
+          });
+        });
+      return new Response(null, { status: failure });
+    });
+    vi.stubGlobal("fetch", fetch);
+    await expect(
+      complete(
+        client().request("token", "/repos/owner/repo/actions/runners/generate-jitconfig", {}),
+      ),
+    ).rejects.toBeInstanceOf(GitHubUncertainError);
+    expect(fetch).toHaveBeenCalledTimes(1);
+  },
+);
+
+test.each(["cancel", "rerun", "dispatches"])(
+  "does not retry the %s POST on rate limit",
+  async (endpoint) => {
+    const fetch = vi.fn(
+      async () => new Response(null, { status: 429, headers: { "retry-after": "1" } }),
+    );
+    vi.stubGlobal("fetch", fetch);
+    await expect(
+      complete(client().post("token", `/repos/owner/repo/actions/${endpoint}`, {})),
+    ).rejects.toMatchObject({ code: "github_rate_limited", status: 429 });
+    expect(fetch).toHaveBeenCalledTimes(1);
+  },
+);
+
+test("retries network errors with exponential full jitter and stops at four attempts", async () => {
+  const start = Date.now();
+  const times: number[] = [];
+  const fetch = vi.fn(async () => {
+    times.push(Date.now());
+    throw new TypeError("private network diagnostic");
+  });
+  vi.stubGlobal("fetch", fetch);
+  await expect(complete(client().request("token", "/test"))).rejects.toMatchObject({
+    code: "github_unavailable",
+    status: 0,
+    message: "GitHub is temporarily unavailable.",
+  });
+  expect(times.map((time) => time - start)).toEqual([0, 250, 750, 1750]);
+});
+
+test("a network failure can recover", async () => {
+  const fetch = vi
+    .fn()
+    .mockRejectedValueOnce(new TypeError("connection reset"))
+    .mockResolvedValueOnce(Response.json({ ok: true }));
+  vi.stubGlobal("fetch", fetch);
+  await expect(complete(client().request("token", "/test"))).resolves.toEqual({ ok: true });
+  expect(fetch).toHaveBeenCalledTimes(2);
+});
+
+test("request timeouts remain 15 seconds and the last attempt cannot exceed the total budget", async () => {
+  const start = Date.now();
+  const fetch = vi.fn(
+    async (_url: string, init?: RequestInit) =>
+      new Promise<Response>((_resolve, reject) => {
+        init?.signal?.addEventListener("abort", () => reject(init.signal?.reason), { once: true });
+      }),
+  );
+  vi.stubGlobal("fetch", fetch);
+  await expect(complete(client(20000).request("token", "/test"))).rejects.toMatchObject({
+    code: "github_unavailable",
+    status: 0,
+  });
+  expect(Date.now() - start).toBe(20000);
+  expect(fetch).toHaveBeenCalledTimes(2);
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+test("an abort during backoff stops retries and releases its timer", async () => {
+  const fetch = vi.fn(async () => new Response(null, { status: 502 }));
+  vi.stubGlobal("fetch", fetch);
+  const abort = new AbortController();
+  const assertion = expect(
+    client().request("token", "/test", undefined, abort.signal),
+  ).rejects.toThrow("cancelled");
+  await vi.advanceTimersByTimeAsync(100);
+  abort.abort(new Error("cancelled"));
+  await assertion;
+  expect(fetch).toHaveBeenCalledTimes(1);
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+test("DELETE and installation token POST are safe to retry", async () => {
+  const fetch = vi
+    .fn()
+    .mockResolvedValueOnce(new Response(null, { status: 502 }))
+    .mockResolvedValueOnce(new Response(null, { status: 204 }))
+    .mockResolvedValueOnce(new Response(null, { status: 502 }))
+    .mockResolvedValueOnce(Response.json({ token: "new" }));
+  vi.stubGlobal("fetch", fetch);
+  await complete(client().delete("token", "/repos/owner/repo/actions/runners/1"));
+  await expect(
+    complete(client().request("jwt", "/app/installations/1/access_tokens", {})),
+  ).resolves.toEqual({ token: "new" });
+  expect(fetch).toHaveBeenCalledTimes(4);
+});
+
+function tokenFixture() {
+  let count = 0;
+  const fetch = vi.fn(async (url: string) => {
+    if (url.endsWith("/installation"))
+      return Response.json({
+        id: 10,
+        app_id: 42,
+        account: { id: 7, type: "User" },
+        suspended_at: null,
+      });
+    if (url.endsWith("/access_tokens"))
+      return Response.json({
+        token: `token-${++count}`,
+        expires_at: new Date(Date.now() + 3600000).toISOString(),
+      });
+    return Response.json({ id: 123, private: true, owner: { id: 7 } });
+  });
+  vi.stubGlobal("fetch", fetch);
+  const input = {
+    owner: "owner",
+    repo: "repo",
+    repositoryId: 123,
+    installationId: 10,
+    githubUserId: 7,
+    purpose: "jobs" as const,
+  };
+  return { fetch, input, count: () => count };
+}
+
+test("installation tokens and lookup are reused across clients until five minutes before expiry", async () => {
+  const { fetch, input, count } = tokenFixture();
+  expect((await client().repositoryToken(input)).token).toBe("token-1");
+  await vi.advanceTimersByTimeAsync(3299999);
+  expect((await client().repositoryToken(input)).token).toBe("token-1");
+  expect(count()).toBe(1);
+  expect(fetch.mock.calls.filter(([url]) => url.endsWith("/installation"))).toHaveLength(1);
+  await vi.advanceTimersByTimeAsync(1);
+  expect((await client().repositoryToken(input)).token).toBe("token-2");
+  expect(fetch.mock.calls.filter(([url]) => url.endsWith("/installation"))).toHaveLength(2);
+});
+
+test("cached access never crosses repository, permission or App boundaries", async () => {
+  const { input, count } = tokenFixture();
+  await client().repositoryToken(input);
+  await client().repositoryToken({ ...input, purpose: "cleanup" });
+  await expect(client().repositoryToken({ ...input, repositoryId: 999 })).rejects.toMatchObject({
+    code: "repository_access_denied",
+  });
+  await new GitHubAppClient({ appId: 42, clientId: "other-app", privateKey }).repositoryToken(
+    input,
+  );
+  expect(count()).toBe(4);
+  await expect(client().repositoryToken({ ...input, githubUserId: 8 })).rejects.toMatchObject({
+    code: "github_app_not_installed",
+  });
+});
+
+test.each(["request", "logs"])(
+  "401 from %s invalidates a reused token and its installation lookup",
+  async (source) => {
+    const { fetch, input, count } = tokenFixture();
+    const access = await client().repositoryToken(input);
+    fetch.mockResolvedValueOnce(new Response(null, { status: 401 }));
+    await expect(
+      source === "request"
+        ? client().request(access.token, "/test")
+        : client().downloadJobLog(access.token, "/repos/owner/repo/actions/jobs/4/logs"),
+    ).rejects.toMatchObject({ status: 401 });
+    expect((await client().repositoryToken(input)).token).toBe("token-2");
+    expect(count()).toBe(2);
+    expect(fetch.mock.calls.filter(([url]) => url.endsWith("/installation"))).toHaveLength(2);
+  },
+);
+
+test("rate-limit 403 during token minting is not reported as a permission failure", async () => {
+  const { fetch, input } = tokenFixture();
+  fetch.mockImplementation(async (url: string) =>
+    url.endsWith("/installation")
+      ? Response.json({ id: 10, app_id: 42, account: { id: 7, type: "User" }, suspended_at: null })
+      : new Response(null, {
+          status: 403,
+          headers: { "x-ratelimit-remaining": "0", "retry-after": "60" },
+        }),
+  );
+  await expect(
+    complete(client().repositoryToken({ ...input, purpose: "actions-write" })),
+  ).rejects.toMatchObject({ code: "github_rate_limited", status: 403 });
+});
diff --git a/packages/github/src/app-client.test.ts b/packages/github/src/app-client.test.ts
index c94aee31..ab2e552f 100644
--- a/packages/github/src/app-client.test.ts
+++ b/packages/github/src/app-client.test.ts
@@ -8,7 +8,10 @@ const app = {
   privateKey: keys.privateKey.export({ format: "pem", type: "pkcs8" }).toString(),
 };
 const input = { owner: "test-owner", repo: "sandbox", repositoryId: 123, githubUserId: 7 };
-afterEach(() => vi.unstubAllGlobals());
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
 test("App authentication signs a short JWT and narrows runner access to the verified repository", async () => {
   const fetch = vi.fn(async (url: string, init?: RequestInit) => {
     const authorization = new Headers(init?.headers).get("Authorization") ?? "";
@@ -369,6 +372,7 @@ test("private fork policy is required and rechecked for runner admission", async
 });
 
 test("readiness reports transient admin lookup failures as unknown while still evaluating public policy", async () => {
+  vi.useFakeTimers();
   vi.stubGlobal("fetch", async (url: string) => {
     if (url.endsWith("/installation"))
       return Response.json({
@@ -384,7 +388,9 @@ test("readiness reports transient admin lookup failures as unknown while still e
     return Response.json({ id: 123, private: false, owner: { id: 99 } });
   });
   const client = new GitHubAppClient(app);
-  const checks = await client.repositoryReadiness({ ...input, githubLogin: "test-owner" });
+  const pending = client.repositoryReadiness({ ...input, githubLogin: "test-owner" });
+  await vi.runAllTimersAsync();
+  const checks = await pending;
   expect(checks).toContainEqual(
     expect.objectContaining({
       id: "github.admin",
diff --git a/packages/github/src/app-client.ts b/packages/github/src/app-client.ts
index afd4bd03..47266f44 100644
--- a/packages/github/src/app-client.ts
+++ b/packages/github/src/app-client.ts
@@ -1,5 +1,18 @@
-import { createPrivateKey, sign } from "node:crypto";
+import { createHash, createPrivateKey, sign } from "node:crypto";
 import { Schema } from "effect";
+import {
+  githubRequest,
+  GitHubApiError,
+  GitHubPermissionError,
+  GitHubRateLimitError,
+} from "./api-request.js";
+export {
+  GitHubApiError,
+  GitHubPermissionError,
+  GitHubRateLimitError,
+  GitHubUnavailableError,
+  GitHubUncertainError,
+} from "./api-request.js";
 import { downloadJobLog } from "./job-logs.js";
 
 import type { ReadinessCheck } from "../../protocol/src/readiness.js";
@@ -10,7 +23,24 @@ const Installation = Schema.Struct({
   account: Schema.Struct({ id: Schema.Int, type: Schema.String }),
   suspended_at: Schema.NullOr(Schema.String),
 });
-const AccessToken = Schema.Struct({ token: Schema.NonEmptyString });
+const AccessToken = Schema.Struct({
+  token: Schema.NonEmptyString,
+  expires_at: Schema.optionalKey(Schema.String),
+});
+const tokens = new Map<string, { token: string; expiresAt: number }>();
+const installations = new Map<
+  string,
+  { installation: typeof Installation.Type; expiresAt: number }
+>();
+const cacheLimit = 256;
+function pruneCache<T extends { expiresAt: number }>(cache: Map<string, T>) {
+  for (const [key, entry] of cache) if (entry.expiresAt <= Date.now()) cache.delete(key);
+  while (cache.size >= cacheLimit) {
+    const key = cache.keys().next().value;
+    if (key === undefined) break;
+    cache.delete(key);
+  }
+}
 export class GitHubApprovalError extends Error {
   readonly code;
   readonly nextStep;
@@ -71,34 +101,34 @@ function githubReadinessFailure(id: string, error: unknown): ReadinessCheck {
   return {
     id,
     status: "unknown",
-    code: "github_unavailable",
+    code: error instanceof GitHubRateLimitError ? error.code : "github_unavailable",
     message: "GitHub access could not be verified.",
     nextStep: "Check GitHub availability and retry readiness.",
     target: { area: "github" },
   };
 }
 
-export class GitHubApiError extends Error {
-  constructor(readonly status: number) {
-    super(`GitHub API request failed (${status}).`);
-  }
-}
-export class GitHubPermissionError extends GitHubApiError {
-  readonly code = "github_app_permission_required";
-  readonly nextStep =
-    "Approve the updated Vectis GitHub App permissions on GitHub (Settings -> Applications), then retry.";
-  constructor(status = 403) {
-    super(status);
-    this.message = "The Vectis GitHub App needs updated Actions write permission.";
-  }
+export function createGitHubAppJwt(app: { clientId: string; privateKey: string }) {
+  const now = Math.floor(Date.now() / 1000);
+  const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString("base64url");
+  const data = `${encode({ alg: "RS256", typ: "JWT" })}.${encode({ iss: app.clientId, iat: now - 60, exp: now + 300 })}`;
+  return `${data}.${sign("RSA-SHA256", Buffer.from(data), createPrivateKey(app.privateKey)).toString("base64url")}`;
 }
 export class GitHubAppClient {
-  constructor(private readonly app: { appId: number; clientId: string; privateKey: string }) {}
+  private readonly cacheScope: string;
+  constructor(
+    private readonly app: { appId: number; clientId: string; privateKey: string },
+    private readonly options: { budgetMs?: number } = {},
+  ) {
+    if (
+      options.budgetMs !== undefined &&
+      (!Number.isFinite(options.budgetMs) || options.budgetMs <= 0)
+    )
+      throw new Error("GitHub request budget must be positive and finite.");
+    this.cacheScope = createHash("sha256").update(JSON.stringify(app)).digest("hex");
+  }
   private jwt() {
-    const now = Math.floor(Date.now() / 1000);
-    const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString("base64url");
-    const data = `${encode({ alg: "RS256", typ: "JWT" })}.${encode({ iss: this.app.clientId, iat: now - 60, exp: now + 300 })}`;
-    return `${data}.${sign("RSA-SHA256", Buffer.from(data), createPrivateKey(this.app.privateKey)).toString("base64url")}`;
+    return createGitHubAppJwt(this.app);
   }
   async request(
     token: string,
@@ -117,7 +147,17 @@ export class GitHubAppClient {
     return this.send(token, path, "POST", body, undefined, responseBody);
   }
   async downloadJobLog(token: string, path: string, after?: number) {
-    return downloadJobLog(token, path, after);
+    try {
+      return await downloadJobLog(token, path, after);
+    } catch (error) {
+      if (error instanceof GitHubApiError && error.status === 401) this.invalidateToken(token);
+      throw error;
+    }
+  }
+  private invalidateToken(token: string) {
+    for (const [key, entry] of tokens) if (entry.token === token) tokens.delete(key);
+    for (const key of installations.keys())
+      if (key.startsWith(this.cacheScope + ":")) installations.delete(key);
   }
   async delete(token: string, path: string): Promise<void> {
     await this.send(token, path, "DELETE");
@@ -130,57 +170,40 @@ export class GitHubAppClient {
     signal?: AbortSignal,
     responseBody: "json" | "discard" = "json",
   ): Promise<{ status: number; body: unknown }> {
-    if (!path.startsWith("/") || path.startsWith("//") || path.includes(".."))
-      throw new Error("Invalid GitHub API path.");
-    const response = await fetch(`https://api.github.com${path}`, {
+    return githubRequest({
+      token,
+      path,
       method,
-      headers: {
-        Authorization: `Bearer ${token}`,
-        Accept: "application/vnd.github+json",
-        "X-GitHub-Api-Version": "2026-03-10",
-        "Content-Type": "application/json",
-      },
-      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-      redirect: "error",
-      signal: signal
-        ? AbortSignal.any([signal, AbortSignal.timeout(15000)])
-        : AbortSignal.timeout(15000),
+      body,
+      signal,
+      responseBody,
+      budgetMs: this.options.budgetMs ?? 45000,
+      invalidate: () => this.invalidateToken(token),
     });
-    if (response.ok && responseBody === "discard") {
-      await response.body?.cancel().catch(() => {});
-      return { status: response.status, body: null };
-    }
-    if (response.status === 204) return { status: response.status, body: null };
-    const reader = response.body?.getReader();
-    if (!reader) {
-      if (!response.ok) throw new GitHubApiError(response.status);
-      if (response.status === 202 || response.status === 201)
-        return { status: response.status, body: null };
-      throw new Error("GitHub returned no response body.");
-    }
-    let size = 0;
-    const chunks: Uint8Array[] = [];
-    try {
-      while (true) {
-        const { value, done } = await reader.read();
-        if (done) break;
-        size += value.length;
-        if (size > 1024 * 1024) {
-          await reader.cancel();
-          throw new Error("GitHub response exceeded its limit.");
-        }
-        chunks.push(value);
-      }
-    } finally {
-      reader.releaseLock();
-    }
-    const text = Buffer.concat(chunks).toString("utf8");
-    if (!response.ok) {
-      if (response.status === 403 && text.includes("Resource not accessible by integration"))
-        throw new GitHubPermissionError();
-      throw new GitHubApiError(response.status);
-    }
-    return { status: response.status, body: text ? JSON.parse(text) : null };
+  }
+  private async installationToken(
+    installationId: number,
+    repository: { repositoryId: number } | { owner: string; repo: string },
+    permissions: Record<string, "read" | "write">,
+  ) {
+    pruneCache(tokens);
+    const key = JSON.stringify([this.cacheScope, installationId, repository, permissions]);
+    const cached = tokens.get(key);
+    if (cached) return cached;
+    const access = Schema.decodeUnknownSync(AccessToken)(
+      await this.request(this.jwt(), `/app/installations/${installationId}/access_tokens`, {
+        ...("repositoryId" in repository
+          ? { repository_ids: [repository.repositoryId] }
+          : { repositories: [repository.repo] }),
+        permissions,
+      }),
+    );
+    const entry = {
+      token: access.token,
+      expiresAt: access.expires_at ? Date.parse(access.expires_at) - 300000 : 0,
+    };
+    if (entry.expiresAt > Date.now()) tokens.set(key, entry);
+    return entry;
   }
   private async repositoryContext(input: {
     owner: string;
@@ -207,16 +230,19 @@ export class GitHubAppClient {
     )
       throw new Error("Invalid repository name.");
     const path = `/repos/${input.owner}/${input.repo}`;
-    const jwt = this.jwt();
-    const installation = Schema.decodeUnknownSync(Installation)(
-      await this.request(jwt, `${path}/installation`).catch((error: unknown) => {
-        // GitHub answers 404 both for a repository the App cannot see and for one that does not
-        // exist, so the message has to cover the installation without claiming the repository.
-        if (error instanceof GitHubApiError && error.status === 404)
-          throw new GitHubInstallationError(input.owner, input.repo);
-        throw error;
-      }),
-    );
+    pruneCache(installations);
+    const lookupKey = `${this.cacheScope}:${path.toLowerCase()}`;
+    const installation =
+      installations.get(lookupKey)?.installation ??
+      Schema.decodeUnknownSync(Installation)(
+        await this.request(this.jwt(), `${path}/installation`).catch((error: unknown) => {
+          // GitHub answers 404 both for a repository the App cannot see and for one that does not
+          // exist, so the message has to cover the installation without claiming the repository.
+          if (error instanceof GitHubApiError && error.status === 404)
+            throw new GitHubInstallationError(input.owner, input.repo);
+          throw error;
+        }),
+      );
     if (
       installation.app_id !== this.app.appId ||
       !["User", "Organization"].includes(installation.account.type) ||
@@ -226,41 +252,40 @@ export class GitHubAppClient {
       throw new GitHubInstallationError(input.owner, input.repo);
     if (input.installationId !== undefined && input.installationId !== installation.id)
       throw new GitHubAccessError("installation_changed");
-    const { token } = Schema.decodeUnknownSync(AccessToken)(
-      await this.request(jwt, `/app/installations/${installation.id}/access_tokens`, {
-        ...(input.repositoryId === undefined
-          ? { repositories: [input.repo] }
-          : { repository_ids: [input.repositoryId] }),
-        permissions:
-          input.purpose === "actions-write"
-            ? { actions: "write", metadata: "read" }
-            : input.purpose === "jobs"
-              ? { actions: "read", metadata: "read" }
-              : input.purpose === "migration-read"
-                ? { contents: "read", metadata: "read" }
-                : input.purpose === "migration-write"
-                  ? {
-                      contents: "write",
-                      workflows: "write",
-                      pull_requests: "write",
-                      metadata: "read",
-                    }
-                  : {
-                      administration: input.purpose === "readiness" ? "read" : "write",
-                      metadata: "read",
-                    },
-      }).catch((error: unknown) => {
-        if (
-          input.purpose === "actions-write" &&
-          error instanceof GitHubApiError &&
-          (error.status === 403 || error.status === 422)
-        )
-          throw new GitHubPermissionError(error.status);
-        if (error instanceof GitHubApiError && [403, 404, 422].includes(error.status))
-          throw new GitHubAccessError("repository_access_denied");
-        throw error;
-      }),
-    );
+    const { token, expiresAt } = await this.installationToken(
+      installation.id,
+      input.repositoryId === undefined
+        ? { owner: input.owner, repo: input.repo }
+        : { repositoryId: input.repositoryId },
+      input.purpose === "actions-write"
+        ? { actions: "write", metadata: "read" }
+        : input.purpose === "jobs"
+          ? { actions: "read", metadata: "read" }
+          : input.purpose === "migration-read"
+            ? { contents: "read", metadata: "read" }
+            : input.purpose === "migration-write"
+              ? {
+                  contents: "write",
+                  workflows: "write",
+                  pull_requests: "write",
+                  metadata: "read",
+                }
+              : {
+                  administration: input.purpose === "readiness" ? "read" : "write",
+                  metadata: "read",
+                },
+    ).catch((error: unknown) => {
+      if (error instanceof GitHubRateLimitError) throw error;
+      if (
+        input.purpose === "actions-write" &&
+        error instanceof GitHubApiError &&
+        (error.status === 403 || error.status === 422)
+      )
+        throw new GitHubPermissionError(error.status);
+      if (error instanceof GitHubApiError && [403, 404, 422].includes(error.status))
+        throw new GitHubAccessError("repository_access_denied");
+      throw error;
+    });
     const repository = Schema.decodeUnknownSync(
       Schema.Struct({
         id: Schema.Int,
@@ -269,6 +294,7 @@ export class GitHubAppClient {
       }),
     )(
       await this.request(token, path).catch((error: unknown) => {
+        if (error instanceof GitHubRateLimitError) throw error;
         if (error instanceof GitHubApiError && [403, 404].includes(error.status))
           throw new GitHubAccessError("repository_access_denied");
         throw error;
@@ -279,6 +305,7 @@ export class GitHubAppClient {
       repository.owner.id !== installation.account.id
     )
       throw new GitHubAccessError("repository_access_denied");
+    if (expiresAt > Date.now()) installations.set(lookupKey, { installation, expiresAt });
     return { token, path, installation, repository };
   }
   private async checkAdmin(
@@ -294,6 +321,7 @@ export class GitHubAppClient {
       )(
         await this.request(token, `${path}/collaborators/${input.githubLogin}/permission`).catch(
           (error: unknown) => {
+            if (error instanceof GitHubRateLimitError) throw error;
             if (error instanceof GitHubApiError && [403, 404].includes(error.status))
               throw new GitHubAdminError();
             throw error;
@@ -337,15 +365,10 @@ export class GitHubAppClient {
       let policyContext = context;
       // Starting runs consumes host capacity; cancellation never needs the fork approval policy.
       if (input.purpose === "migration-write" || input.purpose === "actions-write") {
-        const { token } = Schema.decodeUnknownSync(AccessToken)(
-          await this.request(
-            this.jwt(),
-            `/app/installations/${context.installation.id}/access_tokens`,
-            {
-              repository_ids: [context.repository.id],
-              permissions: { administration: "read", metadata: "read" },
-            },
-          ),
+        const { token } = await this.installationToken(
+          context.installation.id,
+          { repositoryId: context.repository.id },
+          { administration: "read", metadata: "read" },
         );
         policyContext = { ...context, token };
       }
diff --git a/packages/github/src/cache-write.test.ts b/packages/github/src/cache-write.test.ts
new file mode 100644
index 00000000..8a2e7348
--- /dev/null
+++ b/packages/github/src/cache-write.test.ts
@@ -0,0 +1,47 @@
+import { expect, test, vi } from "vitest";
+import { readCacheWrite } from "./cache-write.js";
+
+const run = {
+  id: 10,
+  run_attempt: 1,
+  event: "push",
+  head_branch: "main",
+  repository: { id: 2 },
+  head_repository: { id: 2 },
+};
+test.each([
+  ["default push", {}, true],
+  ["schedule", { event: "schedule" }, true],
+  ["dispatch", { event: "workflow_dispatch" }, true],
+  ["PR", { event: "pull_request" }, false],
+  ["PR target", { event: "pull_request_target" }, false],
+  ["fork", { head_repository: { id: 3 } }, false],
+  ["branch", { head_branch: "feature" }, false],
+  ["repository", { repository: { id: 3 } }, false],
+  ["run", { id: 11 }, false],
+  ["attempt", { run_attempt: 2 }, false],
+  ["missing fork identity", { head_repository: null }, false],
+] as const)("cache write: %s", async (_name, patch, expected) => {
+  const read = vi.fn(async (path: string) =>
+    path === "" ? { id: 2, default_branch: "main" } : { ...run, ...patch },
+  );
+  const result = await readCacheWrite(read, 2, 10, 1);
+  expect(result.cacheWrite).toBe(expected);
+  expect(result.cacheRun).toEqual(expected ? { runId: 10, runAttempt: 1 } : undefined);
+  expect(read).toHaveBeenCalledWith("/actions/runs/10");
+});
+test("unreadable run and unknown default branch fail closed", async () => {
+  expect(
+    await readCacheWrite(
+      async () => {
+        throw new Error("unreadable");
+      },
+      2,
+      10,
+    ),
+  ).toMatchObject({ cacheWrite: false, cacheWriteReason: "metadata_unavailable" });
+  expect(await readCacheWrite(async (path) => (path ? run : { id: 2 }), 2, 10)).toEqual({
+    cacheWrite: false,
+    cacheWriteReason: "metadata_unavailable",
+  });
+});
diff --git a/packages/github/src/cache-write.ts b/packages/github/src/cache-write.ts
new file mode 100644
index 00000000..08a76c19
--- /dev/null
+++ b/packages/github/src/cache-write.ts
@@ -0,0 +1,48 @@
+import { Schema } from "effect";
+import { GitHubApiError } from "./api-request.js";
+import { GitHubId } from "../../protocol/src/repository-access.js";
+
+const Repository = Schema.Struct({ id: GitHubId, default_branch: Schema.NonEmptyString });
+const Run = Schema.Struct({
+  id: GitHubId,
+  run_attempt: GitHubId,
+  event: Schema.String,
+  head_branch: Schema.String,
+  repository: Schema.Struct({ id: GitHubId }),
+  head_repository: Schema.Struct({ id: GitHubId }),
+});
+
+export async function readCacheWrite(
+  read: (path: string) => Promise<unknown>,
+  repositoryId: number,
+  runId: number,
+  runAttempt?: number,
+) {
+  try {
+    const [repositoryValue, runValue] = await Promise.all([
+      read(""),
+      read(`/actions/runs/${runId}`),
+    ]);
+    const repository = Schema.decodeUnknownSync(Repository)(repositoryValue);
+    const run = Schema.decodeUnknownSync(Run)(runValue);
+    if (repository.id !== repositoryId || run.repository.id !== repositoryId)
+      return { cacheWrite: false, cacheWriteReason: "repository_mismatch" };
+    if (run.id !== runId || (runAttempt !== undefined && run.run_attempt !== runAttempt))
+      return { cacheWrite: false, cacheWriteReason: "run_attempt_mismatch" };
+    if (run.head_repository.id !== repositoryId)
+      return { cacheWrite: false, cacheWriteReason: "fork" };
+    if (run.head_branch !== repository.default_branch)
+      return { cacheWrite: false, cacheWriteReason: "non_default_branch" };
+    if (!["push", "schedule", "workflow_dispatch"].includes(run.event))
+      return { cacheWrite: false, cacheWriteReason: "event_not_allowed" };
+    return { cacheWrite: true, cacheRun: { runId, runAttempt: run.run_attempt } };
+  } catch (error) {
+    return {
+      cacheWrite: false,
+      cacheWriteReason:
+        error instanceof GitHubApiError && error.status === 403
+          ? "metadata_access_denied"
+          : "metadata_unavailable",
+    };
+  }
+}
diff --git a/packages/github/src/job-logs.ts b/packages/github/src/job-logs.ts
index 6496196e..1d2c6e4d 100644
--- a/packages/github/src/job-logs.ts
+++ b/packages/github/src/job-logs.ts
@@ -1,4 +1,4 @@
-import { GitHubApiError } from "./app-client.js";
+import { GitHubApiError } from "./api-request.js";
 import type { JobLogs } from "../../protocol/src/jobs.js";
 
 export const jobLogWindowBytes = 4 * 1024 * 1024;
diff --git a/packages/github/src/job.test.ts b/packages/github/src/job.test.ts
index 686ad696..bebe2759 100644
--- a/packages/github/src/job.test.ts
+++ b/packages/github/src/job.test.ts
@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 import { expect, test } from "vitest";
-import { GitHubJob } from "./job.js";
+import { GitHubJob, unmatchableLabels } from "./job.js";
 
 const job = { id: 1, run_id: 2, name: "Build", status: "queued", conclusion: null, labels: [] };
 
@@ -18,5 +18,43 @@ test.each([
 ] as const)("%s is bounded", (field, limit) => {
   const decode = Schema.decodeUnknownSync(GitHubJob);
   expect(decode({ ...job, [field]: "a".repeat(limit) })).toHaveProperty(field, "a".repeat(limit));
-  expect(() => decode({ ...job, [field]: "a".repeat(limit + 1) })).toThrow();
+  const bounded = decode({ ...job, [field]: "a".repeat(limit + 1) });
+  if (field === "html_url") expect(bounded).not.toHaveProperty(field);
+  else expect(bounded).toHaveProperty(field, "a".repeat(limit));
+});
+
+test("unknown status waits for the next API scan without becoming runner demand", () => {
+  expect(Schema.decodeUnknownSync(GitHubJob)({ ...job, status: "future_status" }).status).toBe(
+    "waiting",
+  );
+});
+
+test.each([
+  { labels: Array.from({ length: 101 }, () => "vectis-linux") },
+  { labels: ["a".repeat(101), "vectis-linux"] },
+])("lossy label lists carry an unmatchable marker", ({ labels }) => {
+  const decoded = Schema.decodeUnknownSync(GitHubJob)({ ...job, labels });
+  expect(decoded.labels).toContain(unmatchableLabels);
+  expect(decoded.labels.length).toBeLessThanOrEqual(100);
+  expect(decoded.labels.every((label) => label.length <= 100)).toBe(true);
+  expect(Schema.decodeUnknownSync(GitHubJob)(decoded)).toEqual(decoded);
+});
+
+test("bounds display strings while preserving job and runner identity", () => {
+  expect(
+    Schema.decodeUnknownSync(GitHubJob)({
+      ...job,
+      name: "n".repeat(300),
+      runner_id: 5,
+      runner_name: "r".repeat(300),
+      conclusion: "c".repeat(100),
+    }),
+  ).toMatchObject({
+    id: 1,
+    run_id: 2,
+    name: "n".repeat(200),
+    runner_id: 5,
+    runner_name: "r".repeat(200),
+    conclusion: "c".repeat(80),
+  });
 });
diff --git a/packages/github/src/job.ts b/packages/github/src/job.ts
index 9e8b3b99..eb650bd4 100644
--- a/packages/github/src/job.ts
+++ b/packages/github/src/job.ts
@@ -1,6 +1,6 @@
-import { Schema } from "effect";
+import { Schema, SchemaGetter } from "effect";
 
-export const GitHubJob = Schema.Struct({
+const StoredJob = Schema.Struct({
   id: Schema.Int,
   run_id: Schema.Int,
   run_attempt: Schema.optionalKey(Schema.Int),
@@ -22,4 +22,39 @@ export const GitHubJob = Schema.Struct({
   runner_id: Schema.optionalKey(Schema.NullOr(Schema.Int)),
   runner_name: Schema.optionalKey(Schema.NullOr(Schema.String.check(Schema.isMaxLength(200)))),
 });
+const IncomingJob = Schema.Struct({
+  ...StoredJob.fields,
+  name: Schema.String,
+  html_url: Schema.optionalKey(Schema.String),
+  workflow_name: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  status: Schema.String,
+  conclusion: Schema.NullOr(Schema.String),
+  labels: Schema.Array(Schema.String),
+  runner_name: Schema.optionalKey(Schema.NullOr(Schema.String)),
+});
+
+// This label cannot belong to a Vectis runner. Never turn a lossy label list into runnable demand.
+export const unmatchableLabels = "vectis:unmatchable-labels";
+export const GitHubJob = IncomingJob.pipe(
+  Schema.decodeTo(StoredJob, {
+    decode: SchemaGetter.transform((job) => {
+      const { html_url, ...metadata } = job;
+      const invalidLabels =
+        job.labels.length > 100 || job.labels.some((label) => label.length > 100);
+      return {
+        ...metadata,
+        name: job.name.slice(0, 200),
+        ...(html_url !== undefined && html_url.length <= 500 ? { html_url } : {}),
+        ...(job.workflow_name == null ? {} : { workflow_name: job.workflow_name.slice(0, 200) }),
+        status: Schema.is(StoredJob.fields.status)(job.status) ? job.status : "waiting",
+        conclusion: job.conclusion?.slice(0, 80) ?? null,
+        labels: invalidLabels
+          ? [...job.labels.slice(0, 99).map((label) => label.slice(0, 100)), unmatchableLabels]
+          : job.labels,
+        ...(job.runner_name == null ? {} : { runner_name: job.runner_name.slice(0, 200) }),
+      };
+    }),
+    encode: SchemaGetter.transform((job) => job),
+  }),
+);
 export type GitHubJob = typeof GitHubJob.Type;
diff --git a/packages/protocol/src/cache-volume.ts b/packages/protocol/src/cache-volume.ts
new file mode 100644
index 00000000..7be5fd17
--- /dev/null
+++ b/packages/protocol/src/cache-volume.ts
@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+
+export const CacheSizeGiB = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 1024 }));
+export const CacheVolume = Schema.Struct({ enabled: Schema.Boolean, sizeGiB: CacheSizeGiB });
+export type CacheVolume = typeof CacheVolume.Type;
+export const defaultCacheSizeGiB = 20;
diff --git a/packages/protocol/src/controller.ts b/packages/protocol/src/controller.ts
index d867568f..02c0cb75 100644
--- a/packages/protocol/src/controller.ts
+++ b/packages/protocol/src/controller.ts
@@ -22,12 +22,15 @@ export const LocalQuery = Schema.Union([
       "repositories",
       "github.accounts",
       "capabilities",
+      "activities",
     ]),
   }),
   Schema.Struct({ name: Schema.Literal("repository.readiness"), input: RepositoryReadinessInput }),
   Schema.Struct({ name: Schema.Literal("jobs"), bindingId: Identifier }),
   Schema.Struct({ name: Schema.Literal("job.logs"), ...JobLogRequest.fields }),
   Schema.Struct({ name: Schema.Literal("operation"), id: Identifier }),
+  Schema.Struct({ name: Schema.Literal("operation.key"), key: Schema.NonEmptyString }),
+  Schema.Struct({ name: Schema.Literal("activity"), id: Identifier }),
   Schema.Struct({ name: Schema.Literal("logs"), ...LogRequest.fields }),
 ]);
 export type LocalQuery = typeof LocalQuery.Type;
diff --git a/packages/protocol/src/index.ts b/packages/protocol/src/index.ts
index 339cb45c..4da0c4a4 100644
--- a/packages/protocol/src/index.ts
+++ b/packages/protocol/src/index.ts
@@ -1,7 +1,9 @@
 import { Schema } from "effect";
 import { RerunFailed, CancelRun, DispatchWorkflow } from "./runs.js";
+import { CacheSizeGiB } from "./cache-volume.js";
 import { RepositoryAccess } from "./repository-access.js";
 import { Identifier } from "./identifier.js";
+import { CapacityMode, ScaleSetState } from "./scale-sets.js";
 import { MachineRepositories, RepositoryConnection } from "./repositories.js";
 
 export { Identifier } from "./identifier.js";
@@ -63,6 +65,13 @@ export const Preparation = Schema.Struct({
   ]),
 });
 export type Preparation = typeof Preparation.Type;
+const WarmPoolSize = Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 4 }));
+export const EnvironmentImage = Schema.Struct({
+  parentId: Schema.optional(Identifier),
+  revision: Schema.NonEmptyString,
+  runnerVersion: Schema.optional(Schema.NonEmptyString),
+  provisionedAt: Schema.String,
+});
 export const Environment = Schema.Struct({
   id: Identifier,
   name: Schema.NonEmptyString,
@@ -71,6 +80,7 @@ export const Environment = Schema.Struct({
   storagePath: Schema.optional(Schema.NonEmptyString),
   cpu: Schema.Int,
   memoryMiB: Schema.Int,
+  warmPool: Schema.optional(WarmPoolSize),
   state: Schema.Literals(["ready", "action_required"]),
   sshHost: Schema.optional(Schema.String),
   sshPort: Schema.optional(Schema.Int),
@@ -84,6 +94,7 @@ export const Environment = Schema.Struct({
   firmwarePath: Schema.optional(Schema.String),
   firmwareVarsPath: Schema.optional(Schema.String),
   tpmStatePath: Schema.optional(Schema.String),
+  image: Schema.optional(EnvironmentImage),
 });
 export type Environment = typeof Environment.Type;
 export const OperationStatus = Schema.Literals([
@@ -145,13 +156,20 @@ export const Operation = Schema.Struct({
   result: Schema.optional(Schema.Unknown),
 });
 export type Operation = typeof Operation.Type;
+export const ActivityDetail = Schema.Struct({
+  activity: Activity,
+  operations: Schema.Array(Operation),
+});
+export type ActivityDetail = typeof ActivityDetail.Type;
 export const defaultMaxRunners = 5;
 const MaxRunners = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 16 }));
+const MemoryBudgetMiB = Schema.Int.check(Schema.isGreaterThanOrEqualTo(2048));
 export const Machine = Schema.Struct({
   id: Schema.String,
   name: Schema.String,
   paused: Schema.Boolean,
   maxRunners: Schema.optional(MaxRunners),
+  memoryBudgetMiB: Schema.optional(MemoryBudgetMiB),
 });
 export const Instance = Schema.Struct({
   id: Identifier,
@@ -160,11 +178,13 @@ export const Instance = Schema.Struct({
   cpu: Schema.optional(Schema.Int),
   memoryMiB: Schema.optional(Schema.Int),
   status: Schema.Literals(["starting", "running", "stopped", "interrupted"]),
+  role: Schema.optional(Schema.Literals(["warming", "warm"])),
   pid: Schema.Int,
   macAddress: Schema.optional(Schema.String),
   sshHost: Schema.optional(Schema.String),
   sshPort: Schema.optional(Schema.Int),
   createdAt: Schema.String,
+  stoppedAt: Schema.optional(Schema.String),
   knownHostsPath: Schema.optional(Schema.String),
 });
 export type Instance = typeof Instance.Type;
@@ -173,12 +193,31 @@ export const CloudStatus = Schema.Struct({
   message: Schema.optional(Schema.String),
 });
 export type CloudStatus = typeof CloudStatus.Type;
+export const EnvironmentSlots = Schema.Struct({
+  environmentId: Identifier,
+  available: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+});
+export type EnvironmentSlots = typeof EnvironmentSlots.Type;
+export const RunnerCapacity = Schema.Struct({
+  max: Schema.Int,
+  active: Schema.Int,
+  available: Schema.Int,
+  environments: Schema.optional(Schema.Array(EnvironmentSlots)),
+  budget: Schema.optional(
+    Schema.Struct({
+      memoryBudgetMiB: Schema.Number,
+      memoryCommittedMiB: Schema.Number,
+      hostMemoryMiB: Schema.Number,
+      pressure: Schema.Literals(["normal", "warning", "critical"]),
+      pressureKnown: Schema.optional(Schema.Boolean),
+    }),
+  ),
+});
+export type RunnerCapacity = typeof RunnerCapacity.Type;
 export const Snapshot = Schema.Struct({
   revision: Schema.optional(Schema.String),
   preparationBusy: Schema.optional(Schema.Boolean),
-  runnerCapacity: Schema.optional(
-    Schema.Struct({ max: Schema.Int, active: Schema.Int, available: Schema.Int }),
-  ),
+  runnerCapacity: Schema.optional(RunnerCapacity),
   protocolVersion: Schema.Literal(1),
   version: Schema.optional(Schema.String),
   machine: Machine,
@@ -193,6 +232,7 @@ export const Snapshot = Schema.Struct({
   activities: Schema.optional(Schema.Array(Activity)),
   cloud: Schema.optional(CloudStatus),
   repositories: Schema.optional(MachineRepositories),
+  scaleSets: Schema.optional(Schema.Array(ScaleSetState)),
 });
 export type Snapshot = typeof Snapshot.Type;
 export const Command = Schema.Union([
@@ -212,6 +252,20 @@ export const Command = Schema.Union([
   Schema.Struct({ type: Schema.Literal("repository.disconnect"), bindingId: Identifier }),
   Schema.Struct({ type: Schema.Literal("environment.install-macos"), ...MacInstallation.fields }),
   Schema.Struct({ type: Schema.Literal("environment.prepare-linux"), ...LinuxPreparation.fields }),
+  Schema.Struct({
+    type: Schema.Literal("environment.provision"),
+    id: Identifier,
+    from: Identifier,
+    name: Schema.optional(Schema.NonEmptyString),
+    imageDirectory: Schema.NonEmptyString,
+    setupScript: Schema.optional(
+      Schema.String.check(
+        Schema.isMaxLength(65536),
+        Schema.makeFilter((script) => new TextEncoder().encode(script).length <= 65536),
+      ),
+    ),
+    runner: Schema.optional(Schema.Boolean),
+  }),
   Schema.Struct({ type: Schema.Literal("environment.resume"), id: Identifier }),
   Schema.Struct({ type: Schema.Literal("environment.resume-macos"), id: Identifier }),
   Schema.Struct({ type: Schema.Literal("environment.open-macos-setup"), id: Identifier }),
@@ -235,6 +289,13 @@ export const Command = Schema.Union([
     bindingId: Identifier,
     ...RepositoryAccess.fields,
   }),
+  Schema.Struct({
+    type: Schema.Literal("repository.cache"),
+    bindingId: Identifier,
+    enabled: Schema.Boolean,
+    sizeGiB: Schema.optional(CacheSizeGiB),
+  }),
+  Schema.Struct({ type: Schema.Literal("cache.clear"), bindingId: Identifier }),
   Schema.Struct({
     type: Schema.Literal("repository.automatic"),
     bindingId: Identifier,
@@ -251,16 +312,29 @@ export const Command = Schema.Union([
     bindingId: Identifier,
     automatic: Schema.optional(Schema.Literal(true)),
     jobId: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
+    // Present when a scale set listener requested this runner; the JIT config then comes from that
+    // scale set and GitHub assigns the job.
+    scaleSet: Schema.optional(Schema.Struct({ generation: Schema.Int })),
+  }),
+  Schema.Struct({
+    type: Schema.Literal("repository.capacity-mode"),
+    bindingId: Identifier,
+    mode: CapacityMode,
   }),
   Schema.Struct({ type: Schema.Literal("operation.cancel"), id: Identifier }),
   Schema.Struct({ type: Schema.Literal("activity.cancel"), id: Identifier }),
   Schema.Struct({ type: Schema.Literal("machine.pause"), paused: Schema.Boolean }),
-  Schema.Struct({ type: Schema.Literal("machine.configure"), maxRunners: MaxRunners }),
+  Schema.Struct({
+    type: Schema.Literal("machine.configure"),
+    maxRunners: Schema.optional(MaxRunners),
+    memoryBudgetMiB: Schema.optional(MemoryBudgetMiB),
+  }),
   Schema.Struct({ type: Schema.Literal("environment.register"), environment: Environment }),
   Schema.Struct({ type: Schema.Literal("environment.remove"), id: Identifier }),
   Schema.Struct({
     type: Schema.Literal("environment.configure"),
     id: Identifier,
+    warmPool: Schema.optional(WarmPoolSize),
     x64: Schema.optional(Schema.Literals(["rosetta", "off"])),
     egress: Schema.optional(Egress),
     cpu: Schema.optional(Schema.Int),
@@ -395,6 +469,13 @@ export const capabilities = [
     description:
       "Download and verify Ubuntu 24.04 ARM64, prepare guest SSH and Docker, and register the environment. Requires an idle Apple Silicon host and the Apple helper.",
   },
+  {
+    name: "environment.provision",
+    kind: "command",
+    activity: "intent",
+    description:
+      "Clone a ready environment into a new absolute host image directory, preinstall the pinned runner by default, and optionally run a guest setup script. Requires an idle host. The parent stays immutable; cancellation removes owned partial output.",
+  },
   {
     name: "environment.resume",
     kind: "command",
@@ -435,6 +516,24 @@ export const capabilities = [
     description:
       "Set which numeric GitHub actor IDs may use this binding and whether manual host approval is required.",
   },
+  {
+    name: "repository.cache",
+    kind: "command",
+    activity: "setting",
+    description: "Enable or disable a repository cache block device and set its size cap.",
+  },
+  {
+    name: "cache.clear",
+    kind: "command",
+    activity: "setting",
+    description: "Delete a repository cache volume when no job uses it.",
+  },
+  {
+    name: "repository.capacity-mode",
+    kind: "command",
+    activity: "setting",
+    description: "Choose demand scheduling or preview scale set capacity for a repository binding.",
+  },
   {
     name: "repository.automatic",
     kind: "command",
@@ -521,7 +620,7 @@ export const capabilities = [
     name: "machine.configure",
     kind: "command",
     activity: "setting",
-    description: "Set the maximum number of concurrent runners on this machine (1-16, default 5).",
+    description: "Set concurrent runners (1-16, default 5) and the shared VM memory budget in MiB.",
   },
   {
     name: "machine.pause",
@@ -546,7 +645,7 @@ export const capabilities = [
     kind: "command",
     activity: "setting",
     description:
-      "Set CPU, memory, an absolute VM storage directory, egress or opt-in Rosetta x86_64 support for future instances. Internet-only egress is supported only on Windows; open allows host and local network access. Rosetta is Linux-only and does not change ARM64 runner labels.",
+      "Set CPU, memory, an absolute VM storage directory, egress, opt-in Rosetta x86_64 support or an opt-in warm pool (0-4 SSH-ready VMs, default 0). Warm VMs use RAM but hold no job credentials. Internet-only egress is supported only on Windows; open allows host and local network access. Rosetta is Linux-only and does not change ARM64 runner labels.",
   },
   {
     name: "environment.start",
diff --git a/packages/protocol/src/machine.test.ts b/packages/protocol/src/machine.test.ts
new file mode 100644
index 00000000..235ba467
--- /dev/null
+++ b/packages/protocol/src/machine.test.ts
@@ -0,0 +1,42 @@
+import { expect, test } from "vitest";
+import { Schema } from "effect";
+import { decodeCommand, Machine, Request, RunnerCapacity } from "./index.js";
+import { ControllerRequest } from "./controller.js";
+
+test.each([
+  { memoryBudgetMiB: 2048 },
+  { memoryBudgetMiB: 36864 },
+  { memoryBudgetMiB: 8192, maxRunners: 16 },
+  { maxRunners: 5 },
+])("machine settings cross local and controller command boundaries: %j", (settings) => {
+  const command = { type: "machine.configure", ...settings };
+  expect(decodeCommand(command)).toEqual(command);
+  expect(Schema.decodeUnknownSync(Request)({ key: "settings", command }).command).toEqual(command);
+  expect(
+    Schema.decodeUnknownSync(ControllerRequest)({
+      type: "operation.submit",
+      machineId: "host",
+      key: "settings",
+      command,
+    }),
+  ).toMatchObject({ command });
+});
+
+test.each([0, 2047, -1, 2048.5, "2048", Infinity, NaN])(
+  "invalid memory budget %s is rejected",
+  (memoryBudgetMiB) => {
+    expect(() => decodeCommand({ type: "machine.configure", memoryBudgetMiB })).toThrow();
+  },
+);
+
+test("old machine and capacity snapshots remain valid and command JSON schema includes the budget", () => {
+  expect(
+    Schema.decodeUnknownSync(Machine)({ id: "host", name: "Test", paused: false }),
+  ).not.toHaveProperty("memoryBudgetMiB");
+  expect(
+    Schema.decodeUnknownSync(RunnerCapacity)({ max: 5, active: 0, available: 0 }),
+  ).not.toHaveProperty("budget");
+  const schema = JSON.stringify(Schema.toJsonSchemaDocument(Request));
+  expect(schema).toContain('"memoryBudgetMiB"');
+  expect(schema).toContain('"minimum":2048');
+});
diff --git a/packages/protocol/src/provision.test.ts b/packages/protocol/src/provision.test.ts
new file mode 100644
index 00000000..ea265eb2
--- /dev/null
+++ b/packages/protocol/src/provision.test.ts
@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+import { expect, test } from "vitest";
+import { Command, Snapshot, capabilities, commandActivity, decodeCommand } from "./index.js";
+
+const command = {
+  type: "environment.provision",
+  id: "derived",
+  from: "parent",
+  imageDirectory: "/isolated/new-image",
+};
+
+test("provisioning decodes optional inputs, bounds UTF-8 script bytes and derives the MCP schema", () => {
+  expect(decodeCommand(command)).toEqual(command);
+  expect(
+    decodeCommand({ ...command, runner: false, setupScript: "x".repeat(65536) }),
+  ).toMatchObject({ runner: false });
+  expect(() => decodeCommand({ ...command, setupScript: "x".repeat(65537) })).toThrow();
+  expect(() => decodeCommand({ ...command, setupScript: "é".repeat(32769) })).toThrow();
+  expect(() => decodeCommand({ ...command, id: "../parent" })).toThrow();
+  expect(commandActivity["environment.provision"]).toBe("intent");
+  expect(capabilities).toContainEqual(
+    expect.objectContaining({ name: command.type, kind: "command" }),
+  );
+  expect(JSON.stringify(Schema.toJsonSchemaDocument(Command))).toContain('"environment.provision"');
+});
+
+test("snapshots accept legacy environments and retain optional image manifests", () => {
+  const environment = {
+    id: "parent",
+    name: "Parent",
+    os: "linux",
+    basePath: "/isolated/base.img",
+    cpu: 1,
+    memoryMiB: 512,
+    state: "ready",
+  };
+  const image = {
+    parentId: "parent",
+    revision: "revision",
+    runnerVersion: "2.337.0",
+    provisionedAt: "2026-10-16T00:00:00.000Z",
+  };
+  const snapshot = Schema.decodeUnknownSync(Snapshot)({
+    protocolVersion: 1,
+    machine: { id: "host", name: "Host", paused: false },
+    environments: [environment, { ...environment, id: "derived", image }],
+    instances: [],
+    operations: [],
+  });
+  expect(snapshot.environments[0]?.image).toBeUndefined();
+  expect(snapshot.environments[1]?.image).toEqual(image);
+});
diff --git a/packages/protocol/src/readiness.ts b/packages/protocol/src/readiness.ts
index dd635df2..421cc16f 100644
--- a/packages/protocol/src/readiness.ts
+++ b/packages/protocol/src/readiness.ts
@@ -40,5 +40,6 @@ export type RepositoryReadiness = typeof RepositoryReadiness.Type;
 export const CloudRepositoryReadiness = Schema.Struct({
   checks: Schema.Array(ReadinessCheck),
   environmentId: Schema.optionalKey(Identifier),
+  cacheVolumeEnabled: Schema.optionalKey(Schema.Boolean),
 });
 export type CloudRepositoryReadiness = typeof CloudRepositoryReadiness.Type;
diff --git a/packages/protocol/src/repositories.ts b/packages/protocol/src/repositories.ts
index e5bd3d82..4fc59070 100644
--- a/packages/protocol/src/repositories.ts
+++ b/packages/protocol/src/repositories.ts
@@ -1,15 +1,19 @@
 import { Schema } from "effect";
 import { RepositoryAccess } from "./repository-access.js";
+import { CacheVolume } from "./cache-volume.js";
 import { Identifier } from "./identifier.js";
 export const MachineRepositories = Schema.Array(
   Schema.Struct({
     id: Schema.NonEmptyString,
     repositoryId: Schema.Int,
+    installationId: Schema.optional(Schema.Int),
+    cacheVolume: Schema.optional(CacheVolume),
     repositoryName: Schema.NonEmptyString,
     environmentId: Identifier,
     runsOn: Schema.optional(Schema.String),
     automatic: Schema.optional(Schema.Boolean),
     access: Schema.optional(RepositoryAccess),
+    capacityMode: Schema.optional(Schema.Literals(["demand", "scale_set"])),
   }),
 );
 export type MachineRepositories = typeof MachineRepositories.Type;
diff --git a/packages/protocol/src/repository-access.ts b/packages/protocol/src/repository-access.ts
index 1b18747e..d6134420 100644
--- a/packages/protocol/src/repository-access.ts
+++ b/packages/protocol/src/repository-access.ts
@@ -16,6 +16,7 @@ export type RepositoryAccess = typeof RepositoryAccess.Type;
 export const RunnerAccess = Schema.Struct({
   repositoryId: GitHubId,
   ...RepositoryAccess.fields,
+  cacheRun: Schema.optional(Schema.Struct({ runId: GitHubId, runAttempt: GitHubId })),
   approvedRun: Schema.optional(Schema.Struct({ runId: GitHubId, runAttempt: GitHubId })),
 });
 export type RunnerAccess = typeof RunnerAccess.Type;
diff --git a/packages/protocol/src/runners.test.ts b/packages/protocol/src/runners.test.ts
new file mode 100644
index 00000000..166423ce
--- /dev/null
+++ b/packages/protocol/src/runners.test.ts
@@ -0,0 +1,50 @@
+import { Schema } from "effect";
+import { expect, test } from "vitest";
+import { RunnerProgress } from "./runners.js";
+
+const legacy = {
+  bindingId: "binding",
+  environmentId: "linux",
+  leaseKey: "operation",
+  stage: "listening",
+};
+const phase = {
+  name: "vm_start",
+  startedAt: "2026-10-16T00:00:00.000Z",
+  endedAt: "2026-10-16T00:00:12.300Z",
+};
+const decode = Schema.decodeUnknownSync(RunnerProgress, { onExcessProperty: "error" });
+
+test("runner progress decodes older snapshots without phases", () => {
+  expect(decode(legacy)).toEqual(legacy);
+});
+
+test("runner progress retains completed, active and preinstalled phases", () => {
+  const progress = {
+    ...legacy,
+    phases: [
+      phase,
+      { name: "runner_preinstalled", startedAt: phase.endedAt },
+      { ...phase, name: "vm_start_and_guest_ready" },
+    ],
+  };
+  expect(decode(progress)).toEqual(progress);
+});
+
+test("runner phase history is bounded and rejects unknown phase names", () => {
+  expect(
+    decode({ ...legacy, phases: Array.from({ length: 16 }, () => phase) }).phases,
+  ).toHaveLength(16);
+  expect(() => decode({ ...legacy, phases: Array.from({ length: 17 }, () => phase) })).toThrow();
+  expect(() => decode({ ...legacy, phases: [{ ...phase, name: "unknown" }] })).toThrow();
+});
+
+test("runner cache outcomes survive decoding and reject unbounded reasons", () => {
+  const cache = { attached: true, writeBack: "granted", promoted: true };
+  expect(decode({ ...legacy, cache }).cache).toEqual(cache);
+  expect(
+    decode({ ...legacy, cache: { ...cache, reason: "x".repeat(256) } }).cache?.reason,
+  ).toHaveLength(256);
+  expect(() => decode({ ...legacy, cache: { ...cache, reason: "x".repeat(257) } })).toThrow();
+  expect(() => decode({ ...legacy, cache: { ...cache, writeBack: "maybe" } })).toThrow();
+});
diff --git a/packages/protocol/src/runners.ts b/packages/protocol/src/runners.ts
index 905f34ec..a12b5caf 100644
--- a/packages/protocol/src/runners.ts
+++ b/packages/protocol/src/runners.ts
@@ -2,12 +2,16 @@ import { Schema } from "effect";
 import { RunnerAccess } from "./repository-access.js";
 import { GuestOS, Identifier } from "./index.js";
 
+const CacheReason = Schema.String.check(Schema.isMaxLength(256));
+
 export const RunnerGrant = Schema.Union([
   Schema.Struct({
     state: Schema.Literal("ready"),
     id: Schema.NonEmptyString,
     runnerId: Schema.Int,
     encodedConfig: Schema.NonEmptyString,
+    cacheWrite: Schema.Boolean,
+    cacheWriteReason: Schema.optional(CacheReason),
     environmentId: Identifier,
     os: GuestOS,
     access: Schema.optional(RunnerAccess),
@@ -33,12 +37,34 @@ export interface RunnerBroker {
     bindingId: string,
     key: string,
     signal: AbortSignal,
-    request?: { jobId?: number; automatic?: boolean },
+    request?: { jobId?: number; automatic?: boolean; scaleSet?: { generation: number } },
   ): Promise<RunnerGrant>;
   releaseRunner(id: string, signal: AbortSignal): Promise<void>;
   runnerStatus(leaseId: string, signal: AbortSignal): Promise<RunnerStatus>;
 }
 
+export const PhaseName = Schema.Literals([
+  "queued_locally",
+  "vm_start",
+  "warm_takeover",
+  "vm_start_and_guest_ready",
+  "guest_ready",
+  "runner_install",
+  "runner_preinstalled",
+  "job_check",
+  "registration",
+  "waiting_for_job",
+  "job",
+  "cleanup",
+]);
+export type PhaseName = typeof PhaseName.Type;
+export const RunnerPhase = Schema.Struct({
+  name: PhaseName,
+  startedAt: Schema.String,
+  endedAt: Schema.optional(Schema.String),
+});
+export type RunnerPhase = typeof RunnerPhase.Type;
+
 export const RunnerProgress = Schema.Struct({
   bindingId: Identifier,
   environmentId: Identifier,
@@ -46,6 +72,15 @@ export const RunnerProgress = Schema.Struct({
   instanceId: Schema.optional(Identifier),
   leaseId: Schema.optional(Identifier),
   runnerId: Schema.optional(Schema.Int),
+  phases: Schema.optional(Schema.Array(RunnerPhase).check(Schema.isMaxLength(16))),
+  cache: Schema.optional(
+    Schema.Struct({
+      attached: Schema.Boolean,
+      writeBack: Schema.Literals(["granted", "denied"]),
+      reason: Schema.optional(CacheReason),
+      promoted: Schema.optional(Schema.Boolean),
+    }),
+  ),
   diagnostics: Schema.optional(Schema.String.check(Schema.isMaxLength(16384))),
   cause: Schema.optional(
     Schema.Struct({
diff --git a/packages/protocol/src/scale-sets.ts b/packages/protocol/src/scale-sets.ts
new file mode 100644
index 00000000..6ac770fc
--- /dev/null
+++ b/packages/protocol/src/scale-sets.ts
@@ -0,0 +1,59 @@
+import { Schema } from "effect";
+import { Identifier } from "./identifier.js";
+
+// How a binding gets runner capacity. "demand" is the per-job webhook scheduler; "scale_set" is a
+// GitHub runner scale set that this machine long-polls for assigned job levels.
+export const CapacityMode = Schema.Literals(["demand", "scale_set"]);
+export type CapacityMode = typeof CapacityMode.Type;
+
+export const ScaleSetStatistics = Schema.Struct({
+  totalAssignedJobs: Schema.Int,
+  totalAvailableJobs: Schema.optional(Schema.Int),
+  totalAcquiredJobs: Schema.optional(Schema.Int),
+  totalRunningJobs: Schema.optional(Schema.Int),
+  totalRegisteredRunners: Schema.optional(Schema.Int),
+  totalBusyRunners: Schema.optional(Schema.Int),
+  totalIdleRunners: Schema.optional(Schema.Int),
+});
+export type ScaleSetStatistics = typeof ScaleSetStatistics.Type;
+
+// Issued by the cloud to the one machine that owns the binding. The queue token only reads and
+// acknowledges this scale set's message queue and acquires its jobs; it never appears in snapshots,
+// operation results, logs or guests.
+export const ScaleSetGrant = Schema.Struct({
+  bindingId: Identifier,
+  scaleSetId: Schema.Int,
+  scaleSetName: Schema.NonEmptyString,
+  generation: Schema.Int,
+  sessionId: Schema.NonEmptyString,
+  messageQueueUrl: Schema.NonEmptyString,
+  messageQueueAccessToken: Schema.NonEmptyString,
+  queueTokenExpiresAt: Schema.optional(Schema.Number),
+  statistics: Schema.optional(ScaleSetStatistics),
+});
+export type ScaleSetGrant = typeof ScaleSetGrant.Type;
+
+// Visible state of a scale set listener, safe for snapshots and every surface.
+export const ScaleSetState = Schema.Struct({
+  bindingId: Identifier,
+  state: Schema.Literals(["connecting", "listening", "action_required", "stopped"]),
+  scaleSetName: Schema.optional(Schema.String),
+  assignedJobs: Schema.optional(Schema.Int),
+  reservedRunners: Schema.optional(Schema.Int),
+  lastMessageAt: Schema.optional(Schema.String),
+  code: Schema.optional(Schema.String),
+  message: Schema.optional(Schema.String),
+});
+export type ScaleSetState = typeof ScaleSetState.Type;
+
+export interface ScaleSetBroker {
+  // Gets or creates this machine's scale set for the binding and opens a session. A newer generation
+  // fences every older one; refresh and close with an old generation fail with scale_set_superseded.
+  openScaleSet(bindingId: string, signal: AbortSignal): Promise<ScaleSetGrant>;
+  refreshScaleSet(
+    bindingId: string,
+    generation: number,
+    signal: AbortSignal,
+  ): Promise<ScaleSetGrant>;
+  closeScaleSet(bindingId: string, generation: number, signal: AbortSignal): Promise<void>;
+}
diff --git a/packages/protocol/src/warm-pool.test.ts b/packages/protocol/src/warm-pool.test.ts
new file mode 100644
index 00000000..7c40b2e8
--- /dev/null
+++ b/packages/protocol/src/warm-pool.test.ts
@@ -0,0 +1,50 @@
+import { expect, test } from "vitest";
+import { Schema } from "effect";
+import { decodeCommand, Environment, Instance, Request } from "./index.js";
+import { ControllerRequest } from "./controller.js";
+
+test.each([0, 1, 4])(
+  "warm pool size %s crosses local, MCP and controller boundaries",
+  (warmPool) => {
+    const command = { type: "environment.configure", id: "linux", warmPool };
+    expect(decodeCommand(command)).toEqual(command);
+    expect(Schema.decodeUnknownSync(Request)({ key: "pool", command }).command).toEqual(command);
+    expect(
+      Schema.decodeUnknownSync(ControllerRequest)({
+        type: "operation.submit",
+        machineId: "host",
+        key: "pool",
+        command,
+      }),
+    ).toMatchObject({ command });
+    expect(JSON.stringify(Schema.toJsonSchemaDocument(Request))).toContain('"warmPool"');
+  },
+);
+
+test.each([-1, 5, 0.5, "1", NaN, Infinity])("invalid warm pool size %s is rejected", (warmPool) => {
+  expect(() => decodeCommand({ type: "environment.configure", id: "linux", warmPool })).toThrow();
+});
+
+test("legacy snapshots remain valid while pool roles preserve lifecycle status", () => {
+  const environment = {
+    id: "linux",
+    name: "Linux",
+    os: "linux",
+    basePath: "/unused/base",
+    cpu: 1,
+    memoryMiB: 512,
+    state: "ready",
+  };
+  expect(Schema.decodeUnknownSync(Environment)(environment)).not.toHaveProperty("warmPool");
+  expect(Schema.decodeUnknownSync(Environment)({ ...environment, warmPool: 4 }).warmPool).toBe(4);
+  expect(() => Schema.decodeUnknownSync(Environment)({ ...environment, warmPool: 5 })).toThrow();
+  const instance = { id: "test", environmentId: "linux", status: "running", pid: 0, createdAt: "" };
+  expect(Schema.decodeUnknownSync(Instance)(instance)).not.toHaveProperty("role");
+  expect(Schema.decodeUnknownSync(Instance)({ ...instance, role: "warm" })).toMatchObject({
+    status: "running",
+    role: "warm",
+  });
+  expect(
+    Schema.decodeUnknownSync(Instance)({ ...instance, status: "starting", role: "warming" }),
+  ).toMatchObject({ status: "starting", role: "warming" });
+});
diff --git a/packages/runner/src/apple.test.ts b/packages/runner/src/apple.test.ts
index 29aab4ff..b0e18c80 100644
--- a/packages/runner/src/apple.test.ts
+++ b/packages/runner/src/apple.test.ts
@@ -1,7 +1,48 @@
 import { spawn } from "node:child_process";
 import { once } from "node:events";
 import { expect, test } from "vitest";
-import { waitForAppleVm } from "./apple.js";
+import { requestAppleVmShutdown, waitForAppleVm } from "./apple.js";
+
+test.each(["accepted", "unavailable", "old-helper", "invalid", "oversized", "error"])(
+  "Apple shutdown request handles %s and releases listeners",
+  async (mode) => {
+    const child = spawn(
+      process.execPath,
+      [
+        "-e",
+        `
+const readline = require('node:readline');
+console.log(JSON.stringify({event:'vm.running'}));
+readline.createInterface({input:process.stdin}).on('line', line => {
+  if (line !== 'shutdown') process.exit(97);
+  const mode = '${mode}';
+  if (mode === 'old-helper') return;
+  if (mode === 'invalid') return console.log('invalid');
+  if (mode === 'oversized') return console.log('x'.repeat(65537));
+  console.log(JSON.stringify({event: mode === 'accepted' ? 'vm.shutdown_requested' : mode === 'error' ? 'vm.error' : 'vm.shutdown_unavailable'}));
+});`,
+      ],
+      { stdio: ["pipe", "pipe", "ignore"] },
+    );
+    const closed = once(child, "close");
+    try {
+      await waitForAppleVm(child);
+      const errorListeners = child.listenerCount("error");
+      const dataListeners = child.stdout.listenerCount("data");
+      await expect(requestAppleVmShutdown(child, mode === "old-helper" ? 20 : 1000)).resolves.toBe(
+        mode === "accepted",
+      );
+      expect(child.exitCode).toBeNull();
+      expect(child.signalCode).toBeNull();
+      expect(child.stdout.listenerCount("data")).toBe(dataListeners);
+      expect(child.stdin.listenerCount("error")).toBe(0);
+      expect(child.listenerCount("error")).toBe(errorListeners);
+    } finally {
+      child.stdin.end();
+      await closed;
+    }
+  },
+);
 
 test("requires an explicit VM running event rather than process creation", async () => {
   const child = spawn(
diff --git a/packages/runner/src/apple.ts b/packages/runner/src/apple.ts
index b10eef2f..09d9237f 100644
--- a/packages/runner/src/apple.ts
+++ b/packages/runner/src/apple.ts
@@ -1,5 +1,20 @@
 import type { ChildProcess } from "node:child_process";
 import { VectisError } from "../../protocol/src/index.js";
+import { requestVmCommand } from "./vm-command.js";
+
+export function requestAppleVmShutdown(child: ChildProcess, timeoutMs = 5000) {
+  return requestVmCommand(
+    child,
+    "shutdown\n",
+    (message) => {
+      if (!("event" in message)) return undefined;
+      if (message.event === "vm.shutdown_requested") return true;
+      if (message.event === "vm.shutdown_unavailable" || message.event === "vm.error") return false;
+      return undefined;
+    },
+    timeoutMs,
+  );
+}
 
 export function waitForAppleVm(
   child: ChildProcess,
diff --git a/packages/runner/src/cache-guest.test.ts b/packages/runner/src/cache-guest.test.ts
new file mode 100644
index 00000000..d47d9337
--- /dev/null
+++ b/packages/runner/src/cache-guest.test.ts
@@ -0,0 +1,190 @@
+import { spawnSync } from "node:child_process";
+import { expect, test } from "vitest";
+import { cachePrivilegeScript, cacheSetupScript, cacheUnmountScript } from "./cache-guest.js";
+import { runnerStartScript } from "./runner-release.js";
+
+const access = { repositoryId: 2, actors: "any", approval: "automatic" } as const;
+test.each(["linux", "macos"] as const)("%s cache probe requires noninteractive sudo", (os) => {
+  for (const exitCode of [0, 1]) {
+    const result = spawnSync("bash", ["-s"], {
+      input: `sudo() { test "$*" = '-n true' || return 99; return ${exitCode}; }\n${cachePrivilegeScript(os)}`,
+      encoding: "utf8",
+    });
+    expect(result.status).toBe(exitCode);
+  }
+});
+
+test("Windows cache probe checks the effective administrator token", () => {
+  const script = cachePrivilegeScript("windows");
+  expect(script).toContain("WindowsIdentity]::GetCurrent()");
+  expect(script).toContain("IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)");
+  expect(script).toContain("exit 1");
+});
+test.each(["linux", "macos", "windows"] as const)(
+  "%s cache setup identifies the disk, formats first use and exports job caches",
+  (os) => {
+    const setup = cacheSetupScript(os, 20);
+    expect(setup).toContain("VECTISCACHE");
+    expect(setup).toContain(String(20 * 1024 ** 3));
+    for (const variable of [
+      "RUNNER_TOOL_CACHE",
+      "npm_config_cache",
+      "npm_config_store_dir",
+      "YARN_CACHE_FOLDER",
+      "PIP_CACHE_DIR",
+      "GOMODCACHE",
+      "GOCACHE",
+    ])
+      expect(setup).toContain(variable);
+    expect(setup).not.toContain("CARGO_HOME");
+    const start = runnerStartScript(os, "c2VjcmV0", access, { cacheSizeGiB: 20 });
+    expect(start.indexOf(setup)).toBeLessThan(start.indexOf("--jitconfig"));
+    expect(runnerStartScript(os, "c2VjcmV0", access)).not.toContain(setup);
+    if (os === "linux") {
+      expect(setup).toContain('if test -z "$filesystem"');
+      expect(setup).toContain("mkfs.ext4");
+      expect(setup).toContain("virtio-VECTISCACHE");
+      expect(setup).toContain("nodev,nosuid");
+    }
+    if (os === "macos") {
+      expect(setup).toContain('test "$candidate" != "$boot_disk"');
+      expect(setup).toContain("diskutil eraseDisk APFS VECTISCACHE");
+      expect(setup).toContain("PhysicalStores:1");
+    }
+    if (os === "windows") {
+      expect(setup).toContain("$disk.IsBoot -or $disk.IsSystem");
+      expect(setup).toContain("$disk.PartitionStyle -eq 'RAW'");
+      expect(setup).toContain("Initialize-Disk");
+      expect(setup).toContain("Format-Volume -FileSystem NTFS");
+    } else {
+      expect(spawnSync("bash", ["-n"], { input: start, encoding: "utf8" }).status).toBe(0);
+      expect(
+        spawnSync("bash", ["-n"], { input: cacheUnmountScript(os), encoding: "utf8" }).status,
+      ).toBe(0);
+    }
+  },
+);
+
+test.skipIf(process.platform !== "darwin")(
+  "macOS formats only a unique blank non-boot disk and rejects unsafe layouts",
+  async () => {
+    const { mkdtemp, mkdir, writeFile, readFile, rm } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const home = await mkdtemp(join(tmpdir(), "vectis-cache-diskutil-"));
+    const bin = join(home, "bin");
+    await mkdir(bin);
+    const trace = join(home, "trace");
+    const encode = (value: unknown): string => {
+      if (typeof value === "number") return `<integer>${value}</integer>`;
+      if (typeof value === "boolean") return value ? "<true/>" : "<false/>";
+      if (typeof value === "string") return `<string>${value}</string>`;
+      if (Array.isArray(value)) return `<array>${value.map(encode).join("")}</array>`;
+      if (value && typeof value === "object")
+        return `<dict>${Object.entries(value)
+          .map(([key, item]) => `<key>${key}</key>${encode(item)}`)
+          .join("")}</dict>`;
+      throw new Error("Unsupported fixture value");
+    };
+    await writeFile(
+      join(bin, "diskutil"),
+      `#!${process.execPath}
+const fs = require('node:fs');
+const args = process.argv.slice(2).join(' ');
+const fixtures = JSON.parse(fs.readFileSync(process.env.FIXTURES, 'utf8'));
+fs.appendFileSync(process.env.TRACE, args + '\\n');
+if (!(args in fixtures)) process.exit(1);
+process.stdout.write(fixtures[args]);
+`,
+      { mode: 0o700 },
+    );
+    await writeFile(
+      join(bin, "sudo"),
+      `#!${process.execPath}
+require('node:fs').appendFileSync(process.env.TRACE, 'sudo ' + process.argv.slice(2).join(' ') + '\\n');
+`,
+      { mode: 0o700 },
+    );
+    const script = cacheSetupScript("macos", 20).split("export RUNNER_TOOL_CACHE=")[0];
+    if (!script) throw new Error("Missing cache setup");
+    try {
+      for (const mode of [
+        "blank",
+        "multiple-boot-stores",
+        "ambiguous",
+        "wrong-size",
+        "unknown-content",
+      ] as const) {
+        await writeFile(trace, "");
+        const physical =
+          mode === "multiple-boot-stores"
+            ? [{ DeviceIdentifier: "disk0s2" }, { DeviceIdentifier: "disk2s2" }]
+            : [{ DeviceIdentifier: "disk0s2" }];
+        const fixtures = {
+          "info -plist /": { APFSContainerReference: "disk3" },
+          "apfs list -plist disk3": { Containers: [{ PhysicalStores: physical }] },
+          "info -plist disk0s2": { ParentWholeDisk: "disk0" },
+          "list -plist physical": {
+            AllDisksAndPartitions: [
+              { DeviceIdentifier: "disk0" },
+              { DeviceIdentifier: "disk1" },
+              ...(mode === "ambiguous" ? [{ DeviceIdentifier: "disk2" }] : []),
+            ],
+          },
+          "info -plist disk1": {
+            WholeDisk: true,
+            TotalSize: (mode === "wrong-size" ? 21 : 20) * 1024 ** 3,
+          },
+          "info -plist disk2": { WholeDisk: true, TotalSize: 20 * 1024 ** 3 },
+          "list -plist disk1": {
+            AllDisksAndPartitions: [{ Content: mode === "unknown-content" ? "unknown" : "" }],
+          },
+          "info -plist VECTISCACHE": {
+            APFSContainerReference: "disk4",
+            DeviceIdentifier: "disk4s1",
+          },
+          "apfs list -plist disk4": {
+            Containers: [{ PhysicalStores: [{ DeviceIdentifier: "disk1s2" }] }],
+          },
+          "info -plist disk1s2": { ParentWholeDisk: "disk1" },
+          "mount disk4s1": {},
+          "info -plist disk4s1": { MountPoint: "/Volumes/VECTISCACHE", VolumeName: "VECTISCACHE" },
+        };
+        const path = join(home, "fixtures.json");
+        await writeFile(
+          path,
+          JSON.stringify(
+            Object.fromEntries(
+              Object.entries(fixtures).map(([key, value]) => [
+                key,
+                `<?xml version="1.0"?><plist version="1.0">${encode(value)}</plist>`,
+              ]),
+            ),
+          ),
+        );
+        const result = spawnSync("/bin/bash", ["-s"], {
+          input: script,
+          encoding: "utf8",
+          env: {
+            ...process.env,
+            PATH: `${bin}:/usr/bin:/bin`,
+            TMPDIR: home,
+            FIXTURES: path,
+            TRACE: trace,
+          },
+        });
+        const calls = await readFile(trace, "utf8");
+        if (mode === "blank") {
+          expect(result.status, result.stderr).toBe(0);
+          expect(calls).toContain("sudo -n diskutil eraseDisk APFS VECTISCACHE disk1");
+        } else {
+          expect(result.status).not.toBe(0);
+          expect(calls).not.toContain("sudo ");
+        }
+        expect(calls).not.toContain("eraseDisk APFS VECTISCACHE disk0");
+      }
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
diff --git a/packages/runner/src/cache-guest.ts b/packages/runner/src/cache-guest.ts
new file mode 100644
index 00000000..488bdba9
--- /dev/null
+++ b/packages/runner/src/cache-guest.ts
@@ -0,0 +1,151 @@
+import { Schema } from "effect";
+import { CacheSizeGiB } from "../../protocol/src/cache-volume.js";
+import { VectisError, type Environment } from "../../protocol/src/index.js";
+
+const cacheVariables = {
+  RUNNER_TOOL_CACHE: "toolcache",
+  npm_config_cache: "npm",
+  npm_config_store_dir: "pnpm",
+  YARN_CACHE_FOLDER: "yarn",
+  PIP_CACHE_DIR: "pip",
+  GOMODCACHE: "gomod",
+  GOCACHE: "go-build",
+};
+
+export function cachePrivilegeScript(os: Environment["os"]) {
+  if (os === "windows")
+    return `$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+$principal = [Security.Principal.WindowsPrincipal]::new($identity)
+if (!$principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { exit 1 }
+`;
+  return "sudo -n true\n";
+}
+
+export function cachePrivilegeError() {
+  return new VectisError(
+    "cache_volume_requires_guest_sudo",
+    "This environment cannot mount cache volumes: the guest user has no passwordless sudo.",
+    "Prepare or provision a new environment with this Vectis version, or disable the repository cache.",
+  );
+}
+
+export function cacheSetupScript(os: Environment["os"], sizeGiB: number) {
+  if (!Schema.is(CacheSizeGiB)(sizeGiB))
+    throw new VectisError("invalid_cache_size", "Invalid cache disk size.");
+  const size = sizeGiB * 1024 ** 3;
+  if (os === "windows")
+    return `$ErrorActionPreference = 'Stop'
+$disks = @(Get-Disk | Where-Object { ([string]$_.SerialNumber).Trim() -ceq 'VECTISCACHE' })
+if ($disks.Count -ne 1) { throw 'Cannot uniquely identify the cache disk.' }
+$disk = $disks[0]
+if ($disk.IsBoot -or $disk.IsSystem -or $disk.Size -ne ${size}) { throw 'Unsafe cache disk identity or size.' }
+if ($disk.IsOffline) { $disk | Set-Disk -IsOffline $false }
+if ($disk.IsReadOnly) { $disk | Set-Disk -IsReadOnly $false }
+if ($disk.PartitionStyle -eq 'RAW') {
+  $disk | Initialize-Disk -PartitionStyle GPT -PassThru | New-Partition -UseMaximumSize -AssignDriveLetter | Format-Volume -FileSystem NTFS -NewFileSystemLabel VECTISCACHE -Confirm:$false | Out-Null
+}
+$volumes = @($disk | Get-Partition | Get-Volume | Where-Object { $_.FileSystemLabel -ceq 'VECTISCACHE' -and $_.FileSystem -eq 'NTFS' })
+if ($volumes.Count -ne 1) { throw 'Cache filesystem is missing or ambiguous.' }
+if (!$volumes[0].DriveLetter) {
+  $partition = $disk | Get-Partition | Where-Object { ($_ | Get-Volume).FileSystemLabel -ceq 'VECTISCACHE' }
+  $partition | Add-PartitionAccessPath -AssignDriveLetter
+  $volumes = @($partition | Get-Volume)
+}
+if (!$volumes[0].DriveLetter) { throw 'Cache drive letter is unavailable.' }
+$cache = "$($volumes[0].DriveLetter):\\"
+${Object.entries(cacheVariables)
+  .map(
+    ([key, folder]) =>
+      `$env:${key} = Join-Path $cache '${folder}'\nNew-Item -ItemType Directory -Path $env:${key} -Force | Out-Null`,
+  )
+  .join("\n")}
+`;
+  const mount = os === "linux" ? "/vectis-cache" : "/Volumes/VECTISCACHE";
+  const setup =
+    os === "linux"
+      ? `disk=/dev/disk/by-id/virtio-VECTISCACHE
+test -b "$disk"
+disk=$(readlink -f "$disk")
+test "$(lsblk -dn -o SERIAL "$disk" | tr -d '[:space:]')" = VECTISCACHE
+test "$(sudo -n blockdev --getsize64 "$disk")" = ${size}
+# Refuse any device containing a mounted filesystem before formatting or mounting it.
+test -z "$(lsblk -nr -o MOUNTPOINT "$disk" | tr -d '[:space:]')"
+filesystem=$(sudo -n blkid -p -s TYPE -o value "$disk" || true)
+if test -z "$filesystem"; then
+  test -z "$(sudo -n wipefs --no-act --noheadings --output TYPE "$disk")"
+  sudo -n mkfs.ext4 -F -L VECTISCACHE "$disk"
+fi
+test "$(sudo -n blkid -s TYPE -o value "$disk")" = ext4
+test "$(sudo -n blkid -s LABEL -o value "$disk")" = VECTISCACHE
+sudo -n mkdir -p ${mount}
+sudo -n mount -o nodev,nosuid "$disk" ${mount}
+sudo -n chown "$(id -u):$(id -g)" ${mount}`
+      : `work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+plist() { /usr/libexec/PlistBuddy -c "Print $2" "$1"; }
+diskutil info -plist / > "$work/root"
+container=$(plist "$work/root" :APFSContainerReference)
+[[ "$container" =~ ^disk[0-9]+$ ]]
+diskutil apfs list -plist "$container" > "$work/boot"
+boot_store=$(plist "$work/boot" :Containers:0:PhysicalStores:0:DeviceIdentifier)
+# Vectis macOS images use one boot physical store. Refuse a layout we cannot prove safe.
+if plist "$work/boot" :Containers:0:PhysicalStores:1 >/dev/null 2>&1; then
+  printf 'Multiple boot physical stores are unsupported.\\n' >&2; exit 1
+fi
+diskutil info -plist "$boot_store" > "$work/store"
+boot_disk=$(plist "$work/store" :ParentWholeDisk)
+[[ "$boot_disk" =~ ^disk[0-9]+$ ]]
+diskutil list -plist physical > "$work/disks"
+candidate=
+index=0
+while identifier=$(plist "$work/disks" ":AllDisksAndPartitions:$index:DeviceIdentifier" 2>/dev/null); do
+  if test "$identifier" != "$boot_disk"; then
+    [[ "$identifier" =~ ^disk[0-9]+$ ]]
+    diskutil info -plist "$identifier" > "$work/info"
+    test "$(plist "$work/info" :WholeDisk)" = true
+    test "$(plist "$work/info" :TotalSize)" = ${size}
+    test -z "$candidate"
+    candidate=$identifier
+  fi
+  index=$((index + 1))
+done
+test -n "$candidate" && test "$candidate" != "$boot_disk"
+diskutil list -plist "$candidate" > "$work/cache"
+if ! plist "$work/cache" :AllDisksAndPartitions:0:Partitions:0 >/dev/null 2>&1; then
+  # Only a blank second physical device may be initialized; never erase an unknown filesystem.
+  test -z "$(plist "$work/cache" :AllDisksAndPartitions:0:Content 2>/dev/null || true)"
+  sudo -n diskutil eraseDisk APFS VECTISCACHE "$candidate"
+fi
+# Resolve the named volume back to this physical store, rather than trusting a volume label alone.
+diskutil info -plist VECTISCACHE > "$work/volume"
+cache_container=$(plist "$work/volume" :APFSContainerReference)
+diskutil apfs list -plist "$cache_container" > "$work/apfs"
+cache_store=$(plist "$work/apfs" :Containers:0:PhysicalStores:0:DeviceIdentifier)
+if plist "$work/apfs" :Containers:0:PhysicalStores:1 >/dev/null 2>&1; then
+  printf 'Multiple cache physical stores are unsupported.\\n' >&2; exit 1
+fi
+diskutil info -plist "$cache_store" > "$work/cache-store"
+test "$(plist "$work/cache-store" :ParentWholeDisk)" = "$candidate"
+volume=$(plist "$work/volume" :DeviceIdentifier)
+sudo -n diskutil mount "$volume"
+diskutil info -plist "$volume" > "$work/mounted"
+test "$(plist "$work/mounted" :MountPoint)" = ${mount}
+test "$(plist "$work/mounted" :VolumeName)" = VECTISCACHE
+sudo -n chown "$(id -u):$(id -g)" ${mount}
+rm -rf "$work"
+trap - EXIT`;
+  return `set -eu\n${setup}\n${Object.entries(cacheVariables)
+    .map(([key, folder]) => `export ${key}='${mount}/${folder}'\nmkdir -p "$${key}"`)
+    .join("\n")}\n`;
+}
+
+export function cacheUnmountScript(os: Environment["os"]) {
+  if (os === "windows")
+    return `$ErrorActionPreference = 'Stop'
+$disks = @(Get-Disk | Where-Object { ([string]$_.SerialNumber).Trim() -ceq 'VECTISCACHE' })
+if ($disks.Count -ne 1 -or $disks[0].IsBoot -or $disks[0].IsSystem) { throw 'Unsafe cache disk identity.' }
+$disks[0] | Set-Disk -IsOffline $true
+`;
+  if (os === "macos") return "set -eu\nsync\nsudo -n diskutil unmount /Volumes/VECTISCACHE\n";
+  return "set -eu\nsync\nsudo -n umount /vectis-cache\n";
+}
diff --git a/packages/runner/src/cache-volume.test.ts b/packages/runner/src/cache-volume.test.ts
new file mode 100644
index 00000000..80f30f8e
--- /dev/null
+++ b/packages/runner/src/cache-volume.test.ts
@@ -0,0 +1,157 @@
+import { mkdtemp, writeFile, stat, rm, open, readdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test } from "vitest";
+import { CacheVolumes } from "./cache-volume.js";
+import { runProcess } from "./process.js";
+
+const homes: string[] = [];
+afterEach(async () => {
+  for (const home of homes.splice(0)) await rm(home, { recursive: true, force: true });
+});
+async function fixture() {
+  const home = await mkdtemp(join(tmpdir(), "vectis-cache-"));
+  homes.push(home);
+  const environment = {
+    id: "linux",
+    name: "Linux",
+    os: "linux",
+    state: "ready",
+    basePath: join(home, "base"),
+    cpu: 1,
+    memoryMiB: 512,
+  } as const;
+  const binding = { installationId: 1, repositoryId: 2 };
+  const volumes = new CacheVolumes(home);
+  const first = await volumes.acquire(environment, binding, 1);
+  return { home, environment, binding, volumes, first };
+}
+async function bytes(path: string) {
+  const file = await open(path, "r");
+  try {
+    const data = Buffer.alloc(8);
+    await file.read(data, 0, 8, 0);
+    return data.toString();
+  } finally {
+    await file.close();
+  }
+}
+async function fork(path: string, destination: string, content: string) {
+  await runProcess("/bin/cp", ["-c", path, destination]);
+  const file = await open(destination, "r+");
+  try {
+    await file.write(content, 0, "utf8");
+  } finally {
+    await file.close();
+  }
+}
+const hostTest = test.skipIf(process.platform !== "darwin");
+hostTest(
+  "parallel forks isolate writes, discard untrusted jobs and serialize atomic last-writer-wins promotion",
+  async () => {
+    const { home, first, volumes, environment, binding } = await fixture();
+    expect((await stat(first.disk.sourcePath)).size).toBe(1024 ** 3);
+    expect((await stat(first.disk.sourcePath)).blocks).toBeLessThan(2048);
+    const second = await volumes.acquire(environment, binding, 1);
+    const untrusted = await volumes.acquire(environment, binding, 1);
+    const a = join(home, "a.img"),
+      b = join(home, "b.img"),
+      c = join(home, "c.img");
+    await Promise.all([
+      fork(first.disk.sourcePath, a, "firstjob"),
+      fork(first.disk.sourcePath, b, "last-job"),
+      fork(first.disk.sourcePath, c, "PR-cache"),
+    ]);
+    expect(await bytes(first.disk.sourcePath)).toBe("\0".repeat(8));
+    await untrusted.disk.stopped(c);
+    expect(untrusted.outcome()).toEqual({ promoted: false });
+    expect(await bytes(first.disk.sourcePath)).toBe("\0".repeat(8));
+    first.authorizeWrite();
+    second.authorizeWrite();
+    await Promise.all([first.disk.stopped(a), second.disk.stopped(b)]);
+    expect(first.outcome()).toEqual({ promoted: true });
+    expect(second.outcome()).toEqual({ promoted: true });
+    expect(await bytes(first.disk.sourcePath)).toBe("last-job");
+    expect(await bytes(join(first.directory, "cache.previous.img"))).toBe("firstjob");
+    expect((await readdir(first.directory)).sort()).toEqual(["cache.img", "cache.previous.img"]);
+    first.release();
+    second.release();
+    untrusted.release();
+  },
+);
+test("clear refuses active users, then removes the volume and previous generation", async () => {
+  const { first, volumes } = await fixture();
+  await writeFile(join(first.directory, "cache.previous.img"), "previous");
+  await expect(volumes.clear(first.directory)).rejects.toMatchObject({ code: "cache_in_use" });
+  first.release();
+  await volumes.clear(first.directory);
+  await expect(stat(first.directory)).rejects.toMatchObject({ code: "ENOENT" });
+});
+hostTest(
+  "disconnect deletes generations and fences an already-authorized late writer",
+  async () => {
+    const { home, first, volumes } = await fixture();
+    const path = join(home, "cache-fork.img");
+    await fork(first.disk.sourcePath, path, "trusted!");
+    first.authorizeWrite();
+    await volumes.disconnect(first.directory);
+    await first.disk.stopped(path);
+    expect(first.outcome()).toEqual({ promoted: false, reason: "binding_disconnected" });
+    await expect(stat(first.disk.sourcePath)).rejects.toMatchObject({ code: "ENOENT" });
+    first.release();
+  },
+);
+test("cache identity uses numeric authority and isolates environments and installations", async () => {
+  const { home, first, volumes, environment, binding } = await fixture();
+  expect(first.directory).toBe(join(home, "instances/cache/linux/1-2"));
+  expect(volumes.directory(environment, { ...binding, installationId: 3 })).not.toBe(
+    first.directory,
+  );
+  expect(volumes.directory({ ...environment, id: "macos" }, binding)).not.toBe(first.directory);
+  expect(volumes.directory(environment, { ...binding, repositoryId: 3 })).not.toBe(first.directory);
+  expect(() => volumes.directory(environment, { repositoryId: 2 })).toThrow("numeric");
+  await expect(volumes.acquire(environment, binding, 2)).rejects.toMatchObject({
+    code: "cache_size_changed",
+  });
+  first.release();
+  await volumes.clear(first.directory);
+  const next = await volumes.acquire(environment, binding, 2);
+  expect((await stat(next.disk.sourcePath)).size).toBe(2 * 1024 ** 3);
+  next.release();
+});
+test("missing external storage is never recreated on the host", async () => {
+  const { home, first, volumes, environment, binding } = await fixture();
+  first.release();
+  const storagePath = join(home, "unmounted", "instances");
+  await expect(volumes.acquire({ ...environment, storagePath }, binding, 1)).rejects.toMatchObject({
+    code: "ENOENT",
+  });
+  await expect(stat(join(home, "unmounted"))).rejects.toMatchObject({ code: "ENOENT" });
+});
+
+hostTest(
+  "a missing current generation recovers the previous one without modifying it",
+  async () => {
+    const { first, environment, binding, volumes } = await fixture();
+    const previous = join(first.directory, "cache.previous.img");
+    await fork(first.disk.sourcePath, previous, "previous");
+    first.release();
+    await rm(first.disk.sourcePath);
+    const recovered = await volumes.acquire(environment, binding, 1);
+    expect(await bytes(recovered.disk.sourcePath)).toBe("previous");
+    expect(await bytes(previous)).toBe("previous");
+    recovered.release();
+  },
+);
+
+test("a rejected cache fork reports promotion failure without replacing the saved generation", async () => {
+  const { home, first } = await fixture();
+  const path = join(home, "invalid.img");
+  await writeFile(path, "wrong-size");
+  first.authorizeWrite();
+  await expect(first.disk.stopped(path)).rejects.toMatchObject({ code: "cache_size_changed" });
+  expect(first.outcome()).toEqual({ promoted: false, reason: "promotion_failed" });
+  expect((await stat(first.disk.sourcePath)).size).toBe(1024 ** 3);
+  expect(await bytes(first.disk.sourcePath)).toBe("\0".repeat(8));
+  first.release();
+});
diff --git a/packages/runner/src/cache-volume.ts b/packages/runner/src/cache-volume.ts
new file mode 100644
index 00000000..a7257b6e
--- /dev/null
+++ b/packages/runner/src/cache-volume.ts
@@ -0,0 +1,208 @@
+import { mkdir, open, rename, rm, stat, access, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { Schema } from "effect";
+import { CacheSizeGiB } from "../../protocol/src/cache-volume.js";
+import { VectisError, type Environment } from "../../protocol/src/index.js";
+import { runProcess } from "./process.js";
+
+export interface CacheOutcome {
+  promoted: boolean;
+  reason?: string;
+}
+
+export interface CacheDisk {
+  sourcePath: string;
+  stopped(path: string): Promise<void>;
+}
+
+export class CacheVolumes {
+  private readonly queues = new Map<string, Promise<unknown>>();
+  private readonly users = new Map<string, number>();
+  constructor(private readonly home: string) {}
+
+  directory(
+    environment: Environment,
+    binding: { installationId?: number | undefined; repositoryId: number },
+  ) {
+    if (
+      !Number.isSafeInteger(binding.installationId) ||
+      (binding.installationId ?? 0) <= 0 ||
+      !Number.isSafeInteger(binding.repositoryId) ||
+      binding.repositoryId <= 0
+    )
+      throw new VectisError(
+        "cache_identity_missing",
+        "Cache volumes require numeric installation and repository IDs.",
+      );
+    const root = environment.storagePath ?? join(this.home, "instances");
+    if (!isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,79}$/.test(environment.id))
+      throw new VectisError("invalid_path", "The cache storage path or environment ID is invalid.");
+    return join(root, "cache", environment.id, `${binding.installationId}-${binding.repositoryId}`);
+  }
+
+  private async serial<T>(directory: string, work: () => Promise<T>): Promise<T> {
+    const previous = this.queues.get(directory) ?? Promise.resolve();
+    const next = previous.catch(() => {}).then(work);
+    this.queues.set(directory, next);
+    try {
+      return await next;
+    } finally {
+      if (this.queues.get(directory) === next) this.queues.delete(directory);
+    }
+  }
+
+  async acquire(
+    environment: Environment,
+    binding: { installationId?: number | undefined; repositoryId: number },
+    sizeGiB: number,
+  ) {
+    if (!Schema.is(CacheSizeGiB)(sizeGiB))
+      throw new VectisError("invalid_cache_size", "Cache size must be 1 to 1024 GiB.");
+    const directory = this.directory(environment, binding);
+    const sourcePath = join(directory, "cache.img");
+    const sizeBytes = sizeGiB * 1024 ** 3;
+    const previousUsers = this.users.get(directory) ?? 0;
+    this.users.set(directory, previousUsers + 1);
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      const count = (this.users.get(directory) ?? 1) - 1;
+      if (count) this.users.set(directory, count);
+      else this.users.delete(directory);
+    };
+    try {
+      await this.serial(directory, async () => {
+        // A selected external volume must exist; never recreate its mount point on the host.
+        if (environment.storagePath) await access(environment.storagePath);
+        if (await stat(join(directory, "disconnected")).catch(() => undefined)) {
+          if (previousUsers)
+            throw new VectisError("cache_in_use", "The disconnected cache still has active jobs.");
+          await rm(directory, { recursive: true, force: true });
+        }
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await rm(join(directory, "cache.previous.tmp"), { force: true });
+        const current = await stat(sourcePath).catch((error: unknown) => {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+          throw error;
+        });
+        if (current) {
+          if (!current.isFile() || current.size !== sizeBytes)
+            throw new VectisError(
+              "cache_size_changed",
+              "Clear the cache before changing its size cap.",
+            );
+          return;
+        }
+        const temporary = join(directory, "cache.creating");
+        await rm(temporary, { force: true });
+        const previous = join(directory, "cache.previous.img");
+        const backup = await stat(previous).catch((error: unknown) => {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+          throw error;
+        });
+        if (backup) {
+          if (!backup.isFile() || backup.size !== sizeBytes)
+            throw new VectisError(
+              "cache_size_changed",
+              "Clear the cache before changing its size cap.",
+            );
+          await runProcess("/bin/cp", ["-c", previous, temporary]);
+        } else {
+          const file = await open(temporary, "wx", 0o600);
+          try {
+            await file.truncate(sizeBytes);
+            await file.sync();
+          } finally {
+            await file.close();
+          }
+        }
+        await rename(temporary, sourcePath);
+        const folder = await open(directory, "r");
+        try {
+          await folder.sync();
+        } finally {
+          await folder.close();
+        }
+      });
+    } catch (error) {
+      release();
+      throw error;
+    }
+    let write = false;
+    let outcome: CacheOutcome = { promoted: false };
+    return {
+      directory,
+      outcome: () => outcome,
+      authorizeWrite: (allowed = true) => {
+        write = allowed;
+      },
+      release,
+      disk: {
+        sourcePath,
+        stopped: (path: string) =>
+          this.serial(directory, async () => {
+            if (!write) return;
+            if (await stat(join(directory, "disconnected")).catch(() => undefined)) {
+              outcome = { promoted: false, reason: "binding_disconnected" };
+              return;
+            }
+            const fork = await stat(path);
+            if (!fork.isFile() || fork.size !== sizeBytes)
+              throw new VectisError(
+                "cache_size_changed",
+                "The cache fork no longer matches its size cap.",
+              );
+            const file = await open(path, "r+");
+            try {
+              await file.sync();
+            } finally {
+              await file.close();
+            }
+            const backup = join(directory, "cache.previous.tmp");
+            await rm(backup, { force: true });
+            try {
+              await runProcess("/bin/cp", ["-c", sourcePath, backup]);
+              await rename(backup, join(directory, "cache.previous.img"));
+              await rename(path, sourcePath);
+              outcome = { promoted: true };
+              const folder = await open(directory, "r");
+              try {
+                await folder.sync();
+              } finally {
+                await folder.close();
+              }
+            } finally {
+              await rm(backup, { force: true });
+            }
+          }).catch((error: unknown) => {
+            outcome = { ...outcome, reason: "promotion_failed" };
+            throw error;
+          }),
+      } satisfies CacheDisk,
+    };
+  }
+
+  async clear(directory: string) {
+    await this.serial(directory, async () => {
+      if (this.users.get(directory))
+        throw new VectisError(
+          "cache_in_use",
+          "Wait for cache jobs to stop before clearing the volume.",
+        );
+      await rm(directory, { recursive: true, force: true });
+    });
+  }
+
+  async disconnect(directory: string) {
+    await this.serial(directory, async () => {
+      if (!(await stat(directory).catch(() => undefined))) return;
+      await writeFile(join(directory, "disconnected"), "", { mode: 0o600 });
+      await rm(join(directory, "cache.img"), { force: true });
+      await rm(join(directory, "cache.previous.img"), { force: true });
+      if (!this.users.get(directory)) await rm(directory, { recursive: true, force: true });
+    });
+  }
+}
diff --git a/packages/runner/src/guest-diagnostics.test.ts b/packages/runner/src/guest-diagnostics.test.ts
index 39d5e671..970077b3 100644
--- a/packages/runner/src/guest-diagnostics.test.ts
+++ b/packages/runner/src/guest-diagnostics.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, expect, test, vi } from "vitest";
-import { collectRunnerDiagnostics } from "./guest-diagnostics.js";
+import { collectRunnerDiagnostics, guestCommandDiagnostics } from "./guest-diagnostics.js";
 import { executeGuest, GuestUnavailableError } from "./guest.js";
+import { preinstalledRunnerDirectory } from "./runner-release.js";
 
 vi.mock("./guest.js", async (importOriginal) => ({
   ...(await importOriginal<typeof import("./guest.js")>()),
@@ -16,6 +17,60 @@ const connection = {
   hostKeyAlias: "test",
 };
 
+test("guest command tails redact before truncating and retain stderr before stdout within 16 KiB", () => {
+  const diagnostics = guestCommandDiagnostics({
+    stderr: `discarded-prefix\nAuthorization: Bearer ${"a".repeat(12000)}\n${"é".repeat(5000)}\npermission denied token=ghp_DiagnosticCanary123456789`,
+    stdout: `discarded-prefix\n${"漢".repeat(5000)}\nvectis-provision: download`,
+  });
+  expect(Buffer.byteLength(diagnostics, "utf8")).toBeLessThan(16384);
+  const [stderr, stdout] = diagnostics.split("\n== stdout\n");
+  expect(Buffer.byteLength(stderr ?? "", "utf8")).toBeLessThanOrEqual(4106);
+  expect(Buffer.byteLength(stdout ?? "", "utf8")).toBeLessThanOrEqual(4096);
+  expect(diagnostics).not.toContain("discarded-prefix");
+  expect(diagnostics).not.toContain("a".repeat(100));
+  expect(diagnostics).not.toContain("DiagnosticCanary");
+  expect(diagnostics).not.toContain("\uFFFD");
+  expect(diagnostics).toContain("permission denied token=[redacted]");
+  expect(diagnostics).toContain("vectis-provision: download");
+  expect(diagnostics.indexOf("== stderr")).toBeLessThan(diagnostics.indexOf("== stdout"));
+});
+
+test("guest command diagnostics remove complete private keys and preserve short errors", () => {
+  expect(
+    guestCommandDiagnostics({
+      stderr: "sudo: a password is required",
+      stdout: `-----BEGIN OPENSSH PRIVATE KEY-----\n${"s".repeat(6000)}\n-----END OPENSSH PRIVATE KEY-----\nvectis-provision: directory`,
+    }),
+  ).toBe(
+    "== stderr\nsudo: a password is required\n== stdout\n[redacted]\nvectis-provision: directory",
+  );
+});
+test.each(["linux", "macos", "windows"] as const)(
+  "%s diagnostics read logs from the runner's baked installation",
+  async (os) => {
+    vi.mocked(executeGuest).mockResolvedValue({
+      exitCode: 0,
+      stdout: "runner diagnostic",
+      stderr: "",
+      truncated: false,
+    });
+    expect(
+      await collectRunnerDiagnostics({
+        connection,
+        os,
+        listener: "",
+        secrets: [],
+        preinstalled: true,
+      }),
+    ).toContain("runner diagnostic");
+    expect(executeGuest).toHaveBeenCalledWith(
+      connection,
+      expect.stringContaining(preinstalledRunnerDirectory(os)),
+      expect.objectContaining({ shell: os === "windows" ? "powershell" : "bash" }),
+    );
+  },
+);
+
 test("diagnostics are scrubbed of secrets and bounded", async () => {
   vi.mocked(executeGuest).mockResolvedValue({
     exitCode: 0,
diff --git a/packages/runner/src/guest-diagnostics.ts b/packages/runner/src/guest-diagnostics.ts
index 23dbbdd5..54f3b0be 100644
--- a/packages/runner/src/guest-diagnostics.ts
+++ b/packages/runner/src/guest-diagnostics.ts
@@ -1,3 +1,4 @@
+import { preinstalledRunnerDirectory } from "./runner-release.js";
 import { redact } from "../../client/src/redact.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -7,18 +8,18 @@ import { executeGuest, GuestUnavailableError, type GuestConnection } from "./gue
 const inspect = promisify(execFile);
 const probeTimeout = 20000;
 
-const bashProbe = `set +e
+const bashProbe = (directory: string) => `set +e
 echo "== uptime"; uptime
 echo "== memory"; free -m 2>/dev/null || vm_stat | head -8
 echo "== kernel"; (dmesg 2>/dev/null || sudo -n dmesg 2>/dev/null) | tail -n 40
 echo "== runner log"
-f=$(ls -t "$HOME"/vectis-actions-runner/_diag/Runner_*.log 2>/dev/null | head -1)
+f=$(ls -t "${directory}"/_diag/Runner_*.log 2>/dev/null | head -1)
 if [ -n "$f" ]; then tail -n 40 "$f"; fi
 `;
-const powershellProbe = `$ErrorActionPreference = 'Continue'
+const powershellProbe = (directory: string) => `$ErrorActionPreference = 'Continue'
 '== uptime'; (Get-Date) - (Get-CimInstance Win32_OperatingSystem).LastBootUpTime
 '== runner log'
-$f = Get-ChildItem (Join-Path $env:USERPROFILE 'vectis-actions-runner\\_diag\\Runner_*.log') | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+$f = Get-ChildItem (Join-Path ${directory} '_diag\\Runner_*.log') | Sort-Object LastWriteTime -Descending | Select-Object -First 1
 if ($f) { Get-Content $f -Tail 40 }
 `;
 
@@ -26,6 +27,17 @@ function tail(text: string, limit: number) {
   return text.length > limit ? `...${text.slice(-limit)}` : text;
 }
 
+export function guestCommandDiagnostics(output: { stderr: string; stdout: string }) {
+  const diagnosticTail = (value: string) => {
+    const bytes = Buffer.from(redact(value.trim()), "utf8");
+    if (bytes.length <= 4096) return bytes.toString("utf8");
+    let start = bytes.length - 4093;
+    while (((bytes[start] ?? 0) & 0xc0) === 0x80) start++;
+    return `...${bytes.subarray(start).toString("utf8")}`;
+  };
+  return `== stderr\n${diagnosticTail(output.stderr)}\n== stdout\n${diagnosticTail(output.stdout)}`;
+}
+
 async function hostNetwork(host: string) {
   if (host === "127.0.0.1") return "guest is forwarded through a loopback port";
   const [arp, interfaces] = await Promise.all([
@@ -39,9 +51,20 @@ async function hostNetwork(host: string) {
   ].join("\n");
 }
 
-async function guestState(connection: GuestConnection, os: Environment["os"]) {
+async function guestState(
+  connection: GuestConnection,
+  os: Environment["os"],
+  preinstalled = false,
+) {
   try {
-    const result = await executeGuest(connection, os === "windows" ? powershellProbe : bashProbe, {
+    const directory = preinstalled ? preinstalledRunnerDirectory(os) : undefined;
+    const script =
+      os === "windows"
+        ? powershellProbe(
+            directory ? `'${directory}'` : "(Join-Path $env:USERPROFILE 'vectis-actions-runner')",
+          )
+        : bashProbe(directory ?? "$HOME/vectis-actions-runner");
+    const result = await executeGuest(connection, script, {
       signal: AbortSignal.timeout(probeTimeout),
       shell: os === "windows" ? "powershell" : "bash",
     });
@@ -58,10 +81,11 @@ export async function collectRunnerDiagnostics(input: {
   os: Environment["os"];
   listener: string;
   secrets: readonly string[];
+  preinstalled?: boolean;
 }) {
   const [host, guest] = await Promise.all([
     hostNetwork(input.connection.host),
-    guestState(input.connection, input.os),
+    guestState(input.connection, input.os, input.preinstalled),
   ]);
   const text = [
     `collected: ${new Date().toISOString()}`,
diff --git a/packages/runner/src/guest.test.ts b/packages/runner/src/guest.test.ts
index bc9bad07..77771974 100644
--- a/packages/runner/src/guest.test.ts
+++ b/packages/runner/src/guest.test.ts
@@ -1,6 +1,7 @@
 import { expect, test, vi } from "vitest";
 import { PassThrough } from "node:stream";
 import { EventEmitter } from "node:events";
+import { guestCommandDiagnostics } from "./guest-diagnostics.js";
 import { guestArguments, executeGuest } from "./guest.js";
 
 const connection = {
@@ -12,7 +13,10 @@ const connection = {
   hostKeyAlias: "vectis-test-image",
 };
 const processMock = vi.hoisted(() => ({ spawn: vi.fn() }));
-vi.mock("node:child_process", () => processMock);
+vi.mock("node:child_process", async (original) => ({
+  ...(await original<typeof import("node:child_process")>()),
+  ...processMock,
+}));
 
 function child() {
   const process = Object.assign(new EventEmitter(), {
@@ -46,7 +50,7 @@ test("rejects SSH option injection and requires pinned guest host keys", () => {
   );
 });
 
-test.each(["bash", "powershell"] as const)(
+test.each(["bash", "powershell", "cmd"] as const)(
   "%s sends scripts through stdin and bounds retained guest output",
   async (shell) => {
     const process = child();
@@ -68,6 +72,58 @@ test.each(["bash", "powershell"] as const)(
   },
 );
 
+test("registry commands use cmd directly without a PowerShell script block", async () => {
+  const process = child();
+  const script = 'reg.exe add "HKLM\\SOFTWARE\\Policies\\Example" /v Test /t REG_DWORD /d 1 /f';
+  const result = executeGuest(connection, script, {
+    signal: AbortSignal.timeout(5000),
+    shell: "cmd",
+  });
+  expect(processMock.spawn.mock.lastCall?.[1].at(-1)).toBe("cmd.exe /d /q");
+  expect(process.stdin.read().toString()).toBe(script + "\n");
+  process.exitCode = 0;
+  process.emit("close");
+  expect((await result).exitCode).toBe(0);
+});
+
+const nativeProcess =
+  await vi.importActual<typeof import("node:child_process")>("node:child_process");
+const hasPowerShell =
+  nativeProcess.spawnSync("pwsh", ["-NoProfile", "-Command", "exit 0"]).status === 0;
+
+test.skipIf(!hasPowerShell).each([
+  {
+    name: "runtime error",
+    script: "throw 'Synthetic guest failure'",
+    cause: "Synthetic guest failure",
+  },
+  { name: "parser error", script: "if (", cause: "Missing condition" },
+  { name: "bounded record", script: "throw ('x' * 20000)", cause: "xxxx" },
+])("PowerShell wrapper preserves the $name on stderr", async ({ script, cause }) => {
+  processMock.spawn.mockImplementationOnce((_executable, args: string[]) => {
+    const command = args.at(-1) ?? "";
+    const prefix = 'powershell.exe -NoLogo -NonInteractive -NoProfile -Command "';
+    expect(command.startsWith(prefix)).toBe(true);
+    return nativeProcess.spawn(
+      "pwsh",
+      ["-NoLogo", "-NonInteractive", "-NoProfile", "-Command", command.slice(prefix.length, -1)],
+      {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...globalThis.process.env, NO_COLOR: "1" },
+      },
+    );
+  });
+  const result = await executeGuest(connection, script, {
+    signal: AbortSignal.timeout(10000),
+    shell: "powershell",
+  });
+  expect(result.exitCode).toBe(1);
+  expect(result.stderr).toContain(cause);
+  expect(result.stderr.length).toBeLessThanOrEqual(16385);
+  expect(guestCommandDiagnostics(result)).toContain(cause);
+  expect(result.stderr).not.toContain("Guest script failed.");
+});
+
 test("cancellation stops only the owned SSH process and does not report completion", async () => {
   const process = child();
   const controller = new AbortController();
diff --git a/packages/runner/src/guest.ts b/packages/runner/src/guest.ts
index 50198099..7eaf6ee1 100644
--- a/packages/runner/src/guest.ts
+++ b/packages/runner/src/guest.ts
@@ -86,7 +86,7 @@ export function guestArguments(connection: GuestConnection) {
 export async function executeGuest(
   connection: GuestConnection,
   script: string,
-  options: { signal: AbortSignal; shell?: "bash" | "powershell" },
+  options: { signal: AbortSignal; shell?: "bash" | "powershell" | "cmd" },
 ) {
   if (Buffer.byteLength(script) > 65536)
     throw new VectisError("guest_script_too_large", "Guest scripts cannot exceed 64 KiB.");
@@ -94,8 +94,10 @@ export async function executeGuest(
   const args = guestArguments(connection);
   const command =
     options.shell === "powershell"
-      ? `powershell.exe -NoLogo -NonInteractive -NoProfile -Command "$ErrorActionPreference = 'Stop'; try { & ([scriptblock]::Create([Console]::In.ReadToEnd())) } catch { [Console]::Error.WriteLine('Guest script failed.'); exit 1 }"`
-      : "bash -s";
+      ? `powershell.exe -NoLogo -NonInteractive -NoProfile -Command "$ErrorActionPreference = 'Stop'; try { & ([scriptblock]::Create([Console]::In.ReadToEnd())) } catch { $failure = ($_ | Out-String -Width 4096); [Console]::Error.WriteLine($failure.Substring(0, [Math]::Min($failure.Length, 16384))); exit 1 }"`
+      : options.shell === "cmd"
+        ? "cmd.exe /d /q"
+        : "bash -s";
   const child = spawn("/usr/bin/ssh", [...args, command], { stdio: ["pipe", "pipe", "pipe"] });
   let stdout = "";
   let stderr = "";
diff --git a/packages/runner/src/linux-preparation.ts b/packages/runner/src/linux-preparation.ts
index 26515157..7bbfe1bd 100644
--- a/packages/runner/src/linux-preparation.ts
+++ b/packages/runner/src/linux-preparation.ts
@@ -1,3 +1,4 @@
+import { runnerVersion } from "./runner-release.js";
 import type { RuntimeOptions } from "./runtime.js";
 import { Schema } from "effect";
 import { constants } from "node:fs";
@@ -108,7 +109,23 @@ export async function prepareLinux(
       );
     for (const name of ["disk.img", "guest-key"])
       await access(join(directory, name), constants.R_OK);
-    return preparedEnvironment(input, directory);
+    const manifest = Schema.decodeUnknownSync(
+      Schema.Struct({
+        runnerVersion: Schema.optional(Schema.String),
+        preparedAt: Schema.optional(Schema.String),
+      }),
+    )(image);
+    return preparedEnvironment(
+      input,
+      directory,
+      manifest.runnerVersion && manifest.preparedAt
+        ? {
+            revision: ubuntuImage.revision,
+            runnerVersion: manifest.runnerVersion,
+            provisionedAt: manifest.preparedAt,
+          }
+        : undefined,
+    );
   }
   if (preparation.phase === "booting" && !(await preparationStopped(directory, preparation.id)))
     throw new VectisError(
@@ -185,6 +202,7 @@ export async function prepareLinux(
         cpu: input.cpu,
         memoryMiB: input.memoryMiB,
         marker: seed.marker,
+        failureMarker: seed.failureMarker,
       },
       signal,
     );
@@ -192,12 +210,14 @@ export async function prepareLinux(
     progress("interrupted");
     throw error;
   }
+  const provisionedAt = new Date().toISOString();
   await writeFile(
     join(directory, "image.json"),
     JSON.stringify({
       revision: ubuntuImage.revision,
       sourceSha256: ubuntuImage.sha256,
-      preparedAt: new Date().toISOString(),
+      preparedAt: provisionedAt,
+      runnerVersion,
       toolchainManifest: "/etc/vectis/toolchain-versions.txt",
       sshHostKeyMode: "instance",
     }),
@@ -207,9 +227,17 @@ export async function prepareLinux(
     await rm(path, { force: true });
   await rm(seedDirectory, { recursive: true, force: true });
   progress("prepared");
-  return preparedEnvironment(input, directory);
+  return preparedEnvironment(input, directory, {
+    revision: ubuntuImage.revision,
+    runnerVersion,
+    provisionedAt,
+  });
 }
-function preparedEnvironment(input: LinuxPreparation, directory: string): Environment {
+function preparedEnvironment(
+  input: LinuxPreparation,
+  directory: string,
+  image?: Environment["image"],
+): Environment {
   return {
     id: input.id,
     name: input.name,
@@ -219,6 +247,7 @@ function preparedEnvironment(input: LinuxPreparation, directory: string): Enviro
     cpu: input.cpu,
     memoryMiB: input.memoryMiB,
     state: "ready",
+    ...(image ? { image } : {}),
     sshUser: "vectis",
     sshKeyPath: join(directory, "guest-key"),
     sshHostKeyMode: "instance",
diff --git a/packages/runner/src/linux-seed.test.ts b/packages/runner/src/linux-seed.test.ts
index 8f7a3ac5..3e97c49e 100644
--- a/packages/runner/src/linux-seed.test.ts
+++ b/packages/runner/src/linux-seed.test.ts
@@ -1,7 +1,12 @@
 import { spawnSync } from "node:child_process";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { Schema } from "effect";
 import { expect, test } from "vitest";
 import { linuxSeed } from "./linux-seed.js";
+import { runnerPreinstallScript } from "./provision-scripts.js";
+import { runnerVersion } from "./runner-release.js";
 
 const CloudConfig = Schema.Struct({
   write_files: Schema.Array(
@@ -27,6 +32,105 @@ function content(path: string) {
     ? Buffer.from(entry.content, "base64").toString("utf8")
     : entry.content;
 }
+test("fresh Linux images retain the same verified runner used by derived environments", () => {
+  const script = content("/opt/vectis/prepare.sh");
+  expect(script).toContain(runnerPreinstallScript("linux", { dependencies: false }));
+  expect(script).toContain("runuser -l vectis -c 'bash -s' <<'VECTIS_RUNNER'");
+  const [userScript, rootScript] = script.split("VECTIS_RUNNER\n");
+  expect(userScript).not.toContain("installdependencies.sh");
+  expect(rootScript).toContain('"$runner_target/bin/installdependencies.sh"');
+  expect(rootScript).toContain('chown -R vectis:vectis "$runner_target"');
+  expect(script).not.toContain("sudo -n");
+  expect(script).toContain("trap finish EXIT");
+  expect(script).toContain("VECTIS_PREPARATION_FAILED_test step=%s exit=%s");
+  expect(script).toMatch(/apt-get install -y --no-install-recommends [^\n]*\bzstd\b/);
+  expect(script).not.toContain("/opt/vectis-bootstrap");
+  expect(linuxSeed({ id: "test", publicKey: "ssh-ed25519 AAAA synthetic" }).userdata).toContain(
+    "ALL=(ALL) NOPASSWD:ALL",
+  );
+});
+
+test.each([
+  { name: "success", downloadExit: 0, dependenciesExit: 0, expected: 0 },
+  { name: "download failure", downloadExit: 22, dependenciesExit: 0, expected: 22 },
+  { name: "root dependency failure", downloadExit: 0, dependenciesExit: 23, expected: 23 },
+  {
+    name: "poweroff failure",
+    downloadExit: 0,
+    dependenciesExit: 0,
+    shutdownExit: 24,
+    expected: 24,
+  },
+])("Linux preparation shell: $name", async (scenario) => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-seed-shell-"));
+  const guestHome = join(home, "guest");
+  const serial = join(home, "serial.log");
+  try {
+    await mkdir(guestHome);
+    await writeFile(
+      join(home, "dependencies.sh"),
+      `#!/bin/bash\ntest "$USER" = root || exit 97\necho root-dependencies\nexit ${scenario.dependenciesExit}\n`,
+      { mode: 0o700 },
+    );
+    const script = content("/opt/vectis/prepare.sh")
+      .split("step=network\n")[0]
+      ?.replaceAll("> /dev/hvc0", `>> ${serial}`);
+    if (!script) throw new Error("Missing preparation script");
+    const result = spawnSync("/bin/bash", ["-s"], {
+      input: `
+uname() { echo aarch64; }
+apt-get() { :; }
+usermod() { :; }
+systemctl() { :; }
+poweroff() { echo powered-off; return ${scenario.shutdownExit ?? 0}; }
+getent() { printf 'vectis:x:1000:1000::%s:/bin/bash\\n' "$FIXTURE_GUEST_HOME"; }
+runuser() {
+  test "$1 $2 $3 $4" = '-l vectis -c bash -s' || return 98
+  HOME="$FIXTURE_GUEST_HOME" USER=vectis /bin/bash -c "$4"
+}
+curl() {
+  test "$USER" = vectis && test "$HOME" = "$FIXTURE_GUEST_HOME" || return 99
+  touch "$target/runner.tar.gz"
+  return ${scenario.downloadExit}
+}
+sha256sum() { cat >/dev/null; }
+tar() { mkdir -p "$target/bin"; cp "$FIXTURE_ROOT/dependencies.sh" "$target/bin/installdependencies.sh"; }
+chown() { printf '%s\\n' "$*" > "$FIXTURE_ROOT/ownership"; }
+export -f curl sha256sum tar
+${script}
+printf 'VECTIS_PREPARED_test\\n'
+completed=true
+`,
+      env: {
+        ...process.env,
+        HOME: home,
+        USER: "root",
+        FIXTURE_ROOT: home,
+        FIXTURE_GUEST_HOME: guestHome,
+      },
+      cwd: home,
+      encoding: "utf8",
+    });
+    expect(result.status, result.stderr).toBe(scenario.expected);
+    const output = await readFile(serial, "utf8");
+    expect(output).toContain("powered-off");
+    if (scenario.expected === 0) {
+      expect(output).toContain("root-dependencies");
+      expect(output).toContain("VECTIS_PREPARED_test");
+      expect(output).not.toContain("VECTIS_PREPARATION_FAILED");
+      expect(await readFile(join(home, "ownership"), "utf8")).toBe(
+        `-R vectis:vectis ${guestHome}/.vectis-runner/${runnerVersion}\n`,
+      );
+    } else {
+      expect(output).toContain(
+        `VECTIS_PREPARATION_FAILED_test step=${scenario.shutdownExit ? "poweroff" : scenario.downloadExit ? "runner-download" : "runner-dependencies"} exit=${scenario.expected}`,
+      );
+      if (!scenario.shutdownExit) expect(output).not.toContain("VECTIS_PREPARED_test");
+    }
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
 
 test("Rosetta boot setup checks the share tag and completes before SSH and Docker", () => {
   const unit = content("/opt/vectis/vectis-rosetta.service");
diff --git a/packages/runner/src/linux-seed.ts b/packages/runner/src/linux-seed.ts
index 4302bf8a..41e35aae 100644
--- a/packages/runner/src/linux-seed.ts
+++ b/packages/runner/src/linux-seed.ts
@@ -1,4 +1,5 @@
-import { runnerDistribution } from "./runner-release.js";
+import { runnerPreinstallScript } from "./provision-scripts.js";
+import { preinstalledRunnerDirectory } from "./runner-release.js";
 import { VectisError } from "../../protocol/src/index.js";
 
 export const ubuntuImage = {
@@ -14,7 +15,7 @@ export const ubuntuImage = {
 // download those at job time, and a disposable local VM should not carry them.
 const runnerPackages = [
   // vital_packages
-  "bzip2 curl g++ gcc make jq tar unzip wget",
+  "bzip2 curl g++ gcc make jq tar unzip wget zstd",
   // common_packages, without p7zip-rar, which is multiverse and non-free.
   "autoconf automake dbus dnsutils dpkg-dev fakeroot fonts-noto-color-emoji gnupg2 iproute2",
   "iputils-ping libyaml-dev libtool libssl-dev libicu-dev libgbm-dev libsqlite3-dev locales",
@@ -41,37 +42,57 @@ export function linuxSeed(input: { id: string; publicKey: string }) {
       "invalid_setup_identity",
       "Expected a generated setup identity and Ed25519 public keys.",
     );
-  const runner = runnerDistribution("linux");
   const marker = `VECTIS_PREPARED_${input.id}`;
+  const failureMarker = `VECTIS_PREPARATION_FAILED_${input.id}`;
   const network =
     'network: {version: 2, ethernets: {vectis: {match: {name: "e*"}, dhcp4: true, dhcp-identifier: mac}}}\n';
   const script = `#!/bin/bash
 set -euo pipefail
-trap 'poweroff' EXIT
+step=initialize
+completed=false
+finish() {
+  status=$?
+  trap - EXIT
+  if test "$status" -ne 0 || test "$completed" != true; then
+    printf '${failureMarker} step=%s exit=%s\\n' "$step" "$status" > /dev/hvc0
+  fi
+  poweroff || {
+    status=$?
+    printf '${failureMarker} step=poweroff exit=%s\\n' "$status" > /dev/hvc0
+  }
+  exit "$status"
+}
+trap finish EXIT
+exec > /dev/hvc0 2>&1
 test "$(uname -m)" = aarch64
 export DEBIAN_FRONTEND=noninteractive
+step=packages
 apt-get update
 apt-get install -y curl git openssh-server docker.io
 apt-get install -y --no-install-recommends ${runnerPackages}
 usermod -aG docker vectis
 systemctl enable ssh docker
 systemctl start docker
-mkdir -p /opt/vectis-bootstrap
-cd /opt/vectis-bootstrap
-curl --fail --location --retry 3 --connect-timeout 15 --max-time 300 -o runner.tgz '${runner.url}'
-printf '${runner.sha256}  runner.tgz\\n' | sha256sum -c -
-tar xzf runner.tgz
-./bin/installdependencies.sh
-cd /
-rm -rf /opt/vectis-bootstrap
+step=runner-download
+runuser -l vectis -c 'bash -s' <<'VECTIS_RUNNER'
+${runnerPreinstallScript("linux", { dependencies: false })}VECTIS_RUNNER
+step=runner-dependencies
+guest_home=$(getent passwd vectis | cut -d: -f6)
+test -n "$guest_home"
+runner_target="${preinstalledRunnerDirectory("linux").replace("$HOME", "$guest_home")}"
+"$runner_target/bin/installdependencies.sh"
+chown -R vectis:vectis "$runner_target"
+step=network
 netplan generate
 test "$(docker info --format '{{.OSType}}')" = linux
+step=image-metadata
 mkdir -p /etc/vectis
 dpkg-query -W -f='\${Package}\\t\${Version}\\n' > /etc/vectis/toolchain-versions.txt
 printf '${ubuntuImage.revision}\\n' > /etc/vectis/image-revision
 # The downloaded archives go, the package lists stay: a job that runs apt-get install should not
 # have to run apt-get update first.
 apt-get clean
+step=boot-services
 install -m 0644 /opt/vectis/vectis-rosetta.service /etc/systemd/system/vectis-rosetta.service
 systemctl enable vectis-rosetta.service
 install -m 0644 /opt/vectis/vectis-instance-identity.service /etc/systemd/system/vectis-instance-identity.service
@@ -79,13 +100,16 @@ for unit in ssh.service ssh.socket; do
   mkdir -p "/etc/systemd/system/$unit.d"
   install -m 0644 /opt/vectis/vectis-identity.conf "/etc/systemd/system/$unit.d/vectis-identity.conf"
 done
+step=identity-reset
 rm -f /etc/ssh/ssh_host_* /var/lib/cloud/instance/user-data.txt /var/lib/cloud/instance/user-data.txt.i
 touch /etc/cloud/cloud-init.disabled
 printf 'uninitialized\\n' > /etc/machine-id
 printf '${marker}\\n' > /dev/hvc0
+completed=true
 `;
   return {
     marker,
+    failureMarker,
     metadata: `instance-id: ${input.id}\nlocal-hostname: vectis-linux\n`,
     network: JSON.stringify({
       version: 2,
@@ -99,6 +123,7 @@ printf '${marker}\\n' > /dev/hvc0
             name: "vectis",
             lock_passwd: true,
             shell: "/bin/bash",
+            sudo: "ALL=(ALL) NOPASSWD:ALL",
             ssh_authorized_keys: [input.publicKey.trim()],
           },
         ],
diff --git a/packages/runner/src/memory.test.ts b/packages/runner/src/memory.test.ts
index 240f4311..9b0e61d1 100644
--- a/packages/runner/src/memory.test.ts
+++ b/packages/runner/src/memory.test.ts
@@ -1,5 +1,19 @@
 import { expect, test } from "vitest";
-import { parseAvailableMemory } from "./memory.js";
+import { estimatedVmMemoryMiB, parseAvailableMemory } from "./memory.js";
+
+test.each([
+  { os: "linux", memoryMiB: 12288, expected: 2048 },
+  { os: "macos", memoryMiB: 12288, expected: 4096 },
+  { os: "windows", memoryMiB: 16384, expected: 4096 },
+  { os: "linux", memoryMiB: 512, expected: 512 },
+  { os: "macos", memoryMiB: 2048, expected: 2048 },
+  { os: "windows", memoryMiB: 1024, expected: 1024 },
+] as const)(
+  "$os startup estimate respects its $memoryMiB MiB ceiling",
+  ({ os, memoryMiB, expected }) => {
+    expect(estimatedVmMemoryMiB({ os, memoryMiB })).toBe(expected);
+  },
+);
 
 test("includes reclaimable inactive pages without double-counting file-backed pages", () => {
   const statistics =
diff --git a/packages/runner/src/memory.ts b/packages/runner/src/memory.ts
index 66cad728..185423f8 100644
--- a/packages/runner/src/memory.ts
+++ b/packages/runner/src/memory.ts
@@ -1,5 +1,10 @@
 import { freemem, totalmem } from "node:os";
 import { runProcess } from "./process.js";
+import type { Environment } from "../../protocol/src/index.js";
+
+export function estimatedVmMemoryMiB(environment: Pick<Environment, "os" | "memoryMiB">): number {
+  return Math.min(environment.memoryMiB, environment.os === "linux" ? 2048 : 4096);
+}
 
 export function parseAvailableMemory(statistics: string): number | undefined {
   const size = /page size of (\d+) bytes/.exec(statistics)?.[1];
diff --git a/packages/runner/src/preparation-process.test.ts b/packages/runner/src/preparation-process.test.ts
index f2f90a35..db48157b 100644
--- a/packages/runner/src/preparation-process.test.ts
+++ b/packages/runner/src/preparation-process.test.ts
@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { expect, test } from "vitest";
 import {
+  PreparationProcessError,
   preparationStopped,
   runPreparationGuest,
   runPreparationProcess,
@@ -122,6 +123,30 @@ test("failure to persist a setup event closes its owned process", () =>
     },
   ));
 
+test("other installer processes preserve their original cancellation reason", () =>
+  fixture(
+    'process.stdin.resume();process.stdin.on("end",()=>process.exit(0));process.stdout.write(\'{"event":"vm.running","macAddress":"02:11:22:33:44:55"}\\n\');',
+    async (helper, directory) => {
+      const abort = new AbortController();
+      const reason = new Error("Installer cancelled");
+      await expect(
+        runPreparationProcess(
+          {
+            helper,
+            directory,
+            id: "installer",
+            args: [],
+            marker: '"vm.running"',
+            markerStream: "stdout",
+            onRunning: () => abort.abort(reason),
+          },
+          AbortSignal.any([abort.signal, AbortSignal.timeout(3000)]),
+        ),
+      ).rejects.toBe(reason);
+      expect(await preparationStopped(directory, "installer")).toBe(true);
+    },
+  ));
+
 test("preparation logs redact credentials split across stdout and stderr chunks", () =>
   fixture(
     'process.stdout.write("token=PreparationStdoutCanary123456789\\n");process.stderr.write("Authorization: Bearer Preparation");setTimeout(()=>process.stderr.write("StderrCanary123456789\\nVECTIS_READY\\n"),10);',
@@ -154,3 +179,85 @@ test("bounded preparation output discards credential fragments without their ide
       expect(log).toContain("VECTIS_READY");
     },
   ));
+
+test("a split serial failure marker stops a live helper and retains bounded redacted diagnostics", () =>
+  fixture(
+    `process.stdin.resume();
+process.stdin.on("end", () => process.exit(0));
+process.stderr.write("obsolete-output\\n" + "é".repeat(5000) + "\\ntoken=FailureCanary123456789\\nVECTIS_READY\\nVECTIS_PREPARATION_");
+setTimeout(() => process.stderr.write("FAILED_setup step=runner-dependencies exit=23\\n"), 10);`,
+    async (helper, directory) => {
+      const error = await runPreparationGuest(
+        {
+          helper,
+          directory,
+          id: "setup",
+          cpu: 2,
+          memoryMiB: 2048,
+          marker: "VECTIS_READY",
+          failureMarker: "VECTIS_PREPARATION_FAILED_setup",
+        },
+        AbortSignal.timeout(3000),
+      ).catch((error: unknown) => error);
+      expect(error).toMatchObject({
+        code: "guest_preparation_failed",
+        diagnostics: expect.stringContaining("step=runner-dependencies exit=23"),
+      });
+      if (!(error instanceof PreparationProcessError))
+        throw new Error("Missing preparation diagnostics");
+      expect(Buffer.byteLength(error.diagnostics)).toBeLessThanOrEqual(4096);
+      expect(error.diagnostics).toContain("token=[redacted]");
+      expect(error.diagnostics).not.toMatch(/FailureCanary|obsolete-output|\uFFFD/);
+      expect(await preparationStopped(directory, "setup")).toBe(true);
+    },
+  ));
+
+test("a split failure marker survives a large following serial chunk", () =>
+  fixture(
+    `process.stdin.resume();
+process.stdin.on("end", () => process.stderr.end(() => process.exit(0)));
+process.stderr.write("VECTIS_PREPARATION_");
+setTimeout(() => process.stderr.write("FAILED_setup step=packages exit=23\\n" + "output\\n".repeat(20000) + "after-failure\\n"), 10);`,
+    async (helper, directory) => {
+      await expect(
+        runPreparationGuest(
+          {
+            helper,
+            directory,
+            id: "setup",
+            cpu: 2,
+            memoryMiB: 2048,
+            marker: "VECTIS_READY",
+            failureMarker: "VECTIS_PREPARATION_FAILED_setup",
+          },
+          AbortSignal.timeout(3000),
+        ),
+      ).rejects.toMatchObject({
+        code: "guest_preparation_failed",
+        diagnostics: expect.stringContaining("after-failure"),
+      });
+      expect(await preparationStopped(directory, "setup")).toBe(true);
+    },
+  ));
+
+test("timeout retains the last serial tail and discards truncated credential fragments", () =>
+  fixture(
+    `process.stdin.resume();
+process.stdin.on("end", () => process.exit(0));
+process.stderr.write("token=" + "TimeoutFragmentCanary".repeat(5000) + "\\nAuthorization: Bearer TimeoutCanary123456789\\nvectis-provision: download stalled\\n");`,
+    async (helper, directory) => {
+      const error = await runPreparationGuest(
+        { helper, directory, id: "setup", cpu: 2, memoryMiB: 2048, marker: "VECTIS_READY" },
+        AbortSignal.timeout(1000),
+      ).catch((error: unknown) => error);
+      expect(error).toMatchObject({
+        code: "preparation_timeout",
+        diagnostics: "Authorization: Bearer [redacted]\nvectis-provision: download stalled\n",
+      });
+      expect(await preparationStopped(directory, "setup")).toBe(true);
+      const log = await readFile(join(directory, "preparation.log"), "utf8");
+      expect(log).toContain("vectis-provision: download stalled");
+      expect(log).not.toContain("TimeoutCanary");
+      expect(log).not.toContain("TimeoutFragmentCanary");
+    },
+  ));
diff --git a/packages/runner/src/preparation-process.ts b/packages/runner/src/preparation-process.ts
index 879e2e64..5dda7820 100644
--- a/packages/runner/src/preparation-process.ts
+++ b/packages/runner/src/preparation-process.ts
@@ -5,6 +5,31 @@ import { join } from "node:path";
 import { Schema } from "effect";
 import { VectisError } from "../../protocol/src/index.js";
 
+export class PreparationProcessError extends VectisError {
+  constructor(
+    code: string,
+    message: string,
+    readonly diagnostics: string,
+  ) {
+    super(
+      code,
+      message,
+      "Inspect the private preparation log and resume setup after fixing network or runtime prerequisites.",
+    );
+  }
+}
+
+function completeLines(text: string, truncated: boolean) {
+  return truncated ? (text.includes("\n") ? text.slice(text.indexOf("\n") + 1) : "") : text;
+}
+
+function serialDiagnostics(serial: string, truncated: boolean) {
+  const bytes = Buffer.from(redact(completeLines(serial, truncated)), "utf8");
+  let start = Math.max(0, bytes.length - 4096);
+  while (((bytes[start] ?? 0) & 0xc0) === 0x80) start++;
+  return bytes.subarray(start).toString("utf8");
+}
+
 export async function preparationStopped(directory: string, id: string) {
   try {
     const receipt = Schema.decodeUnknownSync(
@@ -29,6 +54,7 @@ export async function runPreparationGuest(
     cpu: number;
     memoryMiB: number;
     marker: string;
+    failureMarker?: string;
   },
   signal: AbortSignal,
 ) {
@@ -45,6 +71,7 @@ export async function runPreparationGuest(
         join(input.directory, "seed.iso"),
       ],
       markerStream: "stderr",
+      retainAbortDiagnostics: true,
     },
     signal,
   );
@@ -56,7 +83,9 @@ export async function runPreparationProcess(
     id: string;
     args: readonly string[];
     marker: string;
+    failureMarker?: string;
     markerStream: "stdout" | "stderr";
+    retainAbortDiagnostics?: boolean;
     onRunning?: (macAddress: string) => void;
   },
   signal: AbortSignal,
@@ -76,6 +105,7 @@ export async function runPreparationProcess(
   let serial = "";
   let serialTruncated = false;
   let prepared = false;
+  let guestFailed = false;
   let events = "";
   let eventsTruncated = false;
   let pendingEvents = "";
@@ -112,8 +142,13 @@ export async function runPreparationProcess(
   child.stderr.setEncoding("utf8");
   child.stderr.on("data", (chunk: string) => {
     serialTruncated ||= serial.length + chunk.length > 65536;
-    serial = (serial + chunk).slice(-65536);
+    serial += chunk;
+    if (input.failureMarker && serial.includes(input.failureMarker)) {
+      guestFailed = true;
+      stop();
+    }
     if (input.markerStream === "stderr" && serial.includes(input.marker)) prepared = true;
+    serial = serial.slice(-65536);
   });
   const closed = new Promise<void>((resolve) => child.once("close", () => resolve()));
   let force: ReturnType<typeof setTimeout> | undefined;
@@ -132,8 +167,6 @@ export async function runPreparationProcess(
     signal.removeEventListener("abort", stop);
     clearTimeout(force);
     child.stdin.destroy();
-    const completeLines = (text: string, truncated: boolean) =>
-      truncated ? (text.includes("\n") ? text.slice(text.indexOf("\n") + 1) : "") : text;
     await writeFile(
       join(directory, "preparation.log"),
       redact(completeLines(events, eventsTruncated)) +
@@ -146,11 +179,28 @@ export async function runPreparationProcess(
     if (child.pid)
       await writeFile(receipt, JSON.stringify({ instanceId: id, pid: child.pid }), { mode: 0o600 });
   }
-  signal.throwIfAborted();
+  const diagnostics = serialDiagnostics(serial, serialTruncated);
+  if (guestFailed)
+    throw new PreparationProcessError(
+      "guest_preparation_failed",
+      "The guest reported a preparation failure.",
+      diagnostics,
+    );
+  if (signal.aborted) {
+    if (!input.retainAbortDiagnostics) signal.throwIfAborted();
+    const timedOut = signal.reason instanceof Error && signal.reason.name === "TimeoutError";
+    throw new PreparationProcessError(
+      timedOut ? "preparation_timeout" : "preparation_cancelled",
+      timedOut
+        ? "Guest preparation exceeded its time limit and can be resumed."
+        : "Preparation stopped and can be resumed.",
+      diagnostics,
+    );
+  }
   if (failed || child.exitCode !== 0 || !prepared)
-    throw new VectisError(
+    throw new PreparationProcessError(
       "guest_preparation_failed",
       "The guest did not confirm successful preparation.",
-      "Inspect the private preparation log and resume setup after fixing network or runtime prerequisites.",
+      diagnostics,
     );
 }
diff --git a/packages/runner/src/provision-image.test.ts b/packages/runner/src/provision-image.test.ts
new file mode 100644
index 00000000..42e51f1b
--- /dev/null
+++ b/packages/runner/src/provision-image.test.ts
@@ -0,0 +1,132 @@
+import { mkdtemp, mkdir, readFile, realpath, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test } from "vitest";
+import { cloneProvisionImage } from "./provision-image.js";
+import { runProcess } from "./process.js";
+import type { Environment } from "../../protocol/src/index.js";
+
+test.skipIf(process.platform !== "darwin")(
+  "cloning a symlinked Linux source creates an independent disk",
+  async () => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-clone-source-"));
+    try {
+      const source = join(home, "source.img");
+      const basePath = join(home, "alias.img");
+      const sshKeyPath = join(home, "key");
+      const directory = join(home, "derived");
+      await writeFile(source, "parent");
+      await symlink(source, basePath);
+      await writeFile(sshKeyPath, "synthetic-key", { mode: 0o600 });
+      await mkdir(directory);
+      const parent: Environment = {
+        id: "parent",
+        name: "Parent",
+        os: "linux",
+        state: "ready",
+        cpu: 1,
+        memoryMiB: 512,
+        basePath,
+        sshUser: "vectis",
+        sshKeyPath,
+        sshHostKeyMode: "instance",
+      };
+      const derived = await cloneProvisionImage(
+        parent,
+        "derived",
+        directory,
+        {},
+        new AbortController().signal,
+      );
+      await writeFile(derived.basePath, "new-image");
+      expect(await readFile(source, "utf8")).toBe("parent");
+      expect(await readFile(derived.basePath, "utf8")).toBe("new-image");
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
+
+test("Windows overlays pin an absolute backing path and own their cloned firmware, TPM and SSH pins", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-provision-overlay-"));
+  try {
+    const source = join(home, "parent");
+    const directory = join(home, "derived");
+    await mkdir(source);
+    await mkdir(directory);
+    await mkdir(join(source, "tpm-data"));
+    await symlink(join(source, "tpm-data"), join(source, "tpm"));
+    for (const [name, value] of [
+      ["disk.qcow2", "parent-disk"],
+      ["uefi-vars.fd", "parent-vars"],
+      ["tpm/state", "parent-tpm"],
+      ["guest-key", "parent-key"],
+    ]) {
+      if (name) await writeFile(join(source, name), value ?? "", { mode: 0o600 });
+    }
+    await runProcess("/usr/bin/ssh-keygen", [
+      "-t",
+      "ed25519",
+      "-N",
+      "",
+      "-f",
+      join(source, "host-key"),
+    ]);
+    const publicKey = (await readFile(join(source, "host-key.pub"), "utf8")).trim();
+    await writeFile(join(source, "known_hosts"), `parent ${publicKey}\n`);
+    await runProcess("/usr/bin/ssh-keygen", ["-H", "-f", join(source, "known_hosts")]);
+    const qemuImg = join(home, "fake-qemu-img.cjs");
+    await writeFile(
+      qemuImg,
+      `#!${process.execPath}\nconst fs = require('node:fs'); const args = process.argv.slice(2); fs.writeFileSync(args.at(-1), JSON.stringify(args));`,
+      { mode: 0o700 },
+    );
+    const parent: Environment = {
+      id: "parent",
+      name: "Parent",
+      os: "windows",
+      state: "ready",
+      cpu: 1,
+      memoryMiB: 512,
+      basePath: join(source, "disk.qcow2"),
+      firmwarePath: join(source, "code.fd"),
+      firmwareVarsPath: join(source, "uefi-vars.fd"),
+      tpmStatePath: join(source, "tpm"),
+      sshUser: "vectis",
+      sshKeyPath: join(source, "guest-key"),
+      knownHostsPath: join(source, "known_hosts"),
+    };
+    const environment = await cloneProvisionImage(
+      parent,
+      "derived",
+      directory,
+      { qemuImg },
+      new AbortController().signal,
+    );
+    expect(JSON.parse(await readFile(environment.basePath, "utf8"))).toEqual([
+      "create",
+      "-f",
+      "qcow2",
+      "-F",
+      "qcow2",
+      "-b",
+      await realpath(parent.basePath),
+      join(directory, "disk.qcow2"),
+    ]);
+    expect(environment).toMatchObject({
+      firmwareVarsPath: join(directory, "uefi-vars.fd"),
+      tpmStatePath: join(directory, "tpm"),
+      sshKeyPath: join(directory, "guest-key"),
+      knownHostsPath: join(directory, "known_hosts"),
+    });
+    expect(await readFile(join(directory, "known_hosts"), "utf8")).toBe(`derived ${publicKey}\n`);
+    await writeFile(join(directory, "uefi-vars.fd"), "new-vars");
+    await writeFile(join(directory, "tpm/state"), "new-tpm");
+    expect(await readFile(parent.basePath, "utf8")).toBe("parent-disk");
+    expect(await readFile(parent.firmwareVarsPath ?? "", "utf8")).toBe("parent-vars");
+    expect(await readFile(join(source, "tpm/state"), "utf8")).toBe("parent-tpm");
+    expect((await stat(join(directory, "guest-key"))).mode & 0o777).toBe(0o600);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
diff --git a/packages/runner/src/provision-image.ts b/packages/runner/src/provision-image.ts
new file mode 100644
index 00000000..1ec6f48a
--- /dev/null
+++ b/packages/runner/src/provision-image.ts
@@ -0,0 +1,89 @@
+import { constants } from "node:fs";
+import { copyFile, cp, writeFile, mkdir, lstat, realpath, chmod } from "node:fs/promises";
+import { join } from "node:path";
+import { VectisError, type Environment } from "../../protocol/src/index.js";
+import type { RuntimeOptions } from "./runtime.js";
+import { runProcess } from "./process.js";
+
+export async function cloneProvisionImage(
+  parent: Environment,
+  id: string,
+  directory: string,
+  options: Pick<RuntimeOptions, "qemuImg">,
+  signal: AbortSignal,
+): Promise<Environment> {
+  const basePath = join(
+    directory,
+    parent.os === "macos" ? "base.bundle" : parent.os === "windows" ? "disk.qcow2" : "disk.img",
+  );
+  const { image: _image, seedPath: _seed, knownHostsPath: _hosts, ...configuration } = parent;
+  const source = await realpath(parent.basePath);
+  let environment: Environment = { ...configuration, id, basePath };
+  if (parent.os === "windows") {
+    if (!options.qemuImg || !parent.firmwareVarsPath)
+      throw new VectisError(
+        "setup_required",
+        "Windows provisioning requires qemu-img and UEFI variables.",
+      );
+    await runProcess(
+      options.qemuImg,
+      ["create", "-f", "qcow2", "-F", "qcow2", "-b", source, basePath],
+      signal,
+    );
+    const firmwareVarsPath = join(directory, "uefi-vars.fd");
+    await copyFile(parent.firmwareVarsPath, firmwareVarsPath, constants.COPYFILE_FICLONE);
+    const tpmStatePath = join(directory, "tpm");
+    if (parent.tpmStatePath)
+      await cp(await realpath(parent.tpmStatePath), tpmStatePath, {
+        recursive: true,
+        dereference: true,
+        mode: constants.COPYFILE_FICLONE,
+      });
+    else await mkdir(tpmStatePath, { mode: 0o700 });
+    environment = { ...environment, firmwareVarsPath, tpmStatePath };
+  } else {
+    if (parent.os === "macos") {
+      for (const file of [
+        "disk.img",
+        "hardware-model.bin",
+        "machine-identifier.bin",
+        "auxiliary-storage.bin",
+      ])
+        if (!(await lstat(join(source, file))).isFile())
+          throw new VectisError(
+            "invalid_image",
+            "macOS image components must be regular files, not symbolic links.",
+          );
+    }
+    await runProcess("/bin/cp", ["-cR", source, basePath], signal);
+  }
+  signal.throwIfAborted();
+  if (!parent.sshUser || !parent.sshKeyPath || (parent.os !== "linux" && !parent.knownHostsPath))
+    throw new VectisError(
+      "setup_required",
+      "The parent environment needs verified guest SSH access.",
+    );
+  const sshKeyPath = join(directory, "guest-key");
+  await copyFile(parent.sshKeyPath, sshKeyPath, constants.COPYFILE_FICLONE);
+  await chmod(sshKeyPath, 0o600);
+  environment = { ...environment, sshKeyPath };
+  if (parent.os !== "linux" && parent.knownHostsPath) {
+    const knownHostsPath = join(directory, "known_hosts");
+    // ssh-keygen also handles hashed enrollment entries; never trust a fresh network scan.
+    const pinned = await runProcess(
+      "/usr/bin/ssh-keygen",
+      ["-F", parent.id, "-f", parent.knownHostsPath],
+      signal,
+    );
+    const keys = pinned.split(/\r?\n/).filter((line) => line && !line.startsWith("#"));
+    if (!keys.length)
+      throw new VectisError("setup_required", "The parent has no pinned SSH host key for its ID.");
+    await writeFile(
+      knownHostsPath,
+      keys.map((line) => line.replace(/^\S+/, id)).join("\n") + "\n",
+      { mode: 0o600 },
+    );
+    environment = { ...environment, knownHostsPath };
+  }
+  return environment;
+}
diff --git a/packages/runner/src/provision-scripts.test.ts b/packages/runner/src/provision-scripts.test.ts
new file mode 100644
index 00000000..25f50a62
--- /dev/null
+++ b/packages/runner/src/provision-scripts.test.ts
@@ -0,0 +1,268 @@
+import { spawnSync } from "node:child_process";
+import { mkdtemp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test } from "vitest";
+import {
+  provisionScript,
+  provisionLinuxIdentityResetScript,
+  provisionShutdownScript,
+  provisionMacosShutdownScript,
+  runnerPreinstallScript,
+  setupUploadScripts,
+} from "./provision-scripts.js";
+import { windowsToolchainScript } from "./windows-toolchain.js";
+import { runnerDistribution, runnerVersion } from "./runner-release.js";
+
+test.each(["linux", "macos", "windows"] as const)(
+  "%s preinstallation pins the release, retries downloads and verifies before extraction",
+  (os) => {
+    const script = runnerPreinstallScript(os);
+    const distribution = runnerDistribution(os);
+    expect(script).toContain(distribution.url);
+    expect(script).toContain(distribution.sha256);
+    expect(script).toContain(runnerVersion);
+    expect(script).toContain(".vectis-installed");
+    expect(script.indexOf(distribution.sha256)).toBeLessThan(
+      script.indexOf(os === "windows" ? "Expand-Archive" : "tar xzf"),
+    );
+    if (os === "windows") {
+      expect(script).toContain("$attempt -le 4");
+      expect(script).toContain("Invoke-WebRequest -UseBasicParsing");
+      expect(provisionScript(os, { runner: true, setup: true })).toContain(
+        "powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File $setup",
+      );
+      expect(provisionScript(os, { runner: false, setup: true })).toContain(
+        windowsToolchainScript(),
+      );
+    } else {
+      expect(script).toContain("--retry 3");
+      if (os === "linux") {
+        expect(script).toContain('sudo -n "$target/bin/installdependencies.sh"');
+        expect(script).not.toMatch(/sudo -n (install|chown)/);
+      } else expect(script).not.toContain("sudo");
+      for (const shell of [
+        script,
+        provisionScript(os, { runner: true, setup: true }),
+        provisionShutdownScript(os),
+      ])
+        expect(spawnSync("/bin/bash", ["-n"], { input: shell, encoding: "utf8" }).status).toBe(0);
+    }
+  },
+);
+
+test.each([
+  { name: "prepared image without sudo", ready: true, expected: 0 },
+  { name: "missing linked library without sudo", mode: "linked", expected: 1 },
+  { name: "missing ICU without sudo", mode: "icu", expected: 1 },
+  { name: "failed ldd probe without sudo", mode: "ldd-error", expected: 1 },
+  { name: "missing libraries installed with sudo", mode: "linked", sudo: true, expected: 0 },
+  { name: "installer failure", mode: "linked", sudo: true, installExit: 42, expected: 42 },
+  {
+    name: "installer leaves missing libraries",
+    mode: "linked",
+    sudo: true,
+    unresolved: true,
+    expected: 1,
+  },
+  { name: "download failure", ready: true, downloadExit: 22, expected: 22 },
+])("Linux preinstallation: $name", async (scenario) => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-preinstall-"));
+  const target = join(home, ".vectis-runner", runnerVersion);
+  try {
+    if (scenario.ready) await writeFile(join(home, "dependencies-ready"), "");
+    const stubs = `
+curl() { touch "$target/runner.tar.gz"; return ${scenario.downloadExit ?? 0}; }
+sha256sum() { cat >/dev/null; }
+tar() {
+  mkdir -p "$target/bin"
+  touch "$target/bin/Runner.Listener"
+  chmod +x "$target/bin/Runner.Listener"
+}
+ldd() {
+  if ! test -f "$HOME/dependencies-ready"; then
+    case '${scenario.mode ?? ""}' in
+      linked) echo 'libmissing.so => not found'; return 0 ;;
+      ldd-error) echo 'ldd probe failed' >&2; return 2 ;;
+    esac
+  fi
+  echo 'libc.so => /lib/libc.so'
+}
+ldconfig() {
+  for library in libicuuc libssl libcrypto libkrb5 libz liblttng-ust; do
+    if test "$library" = libicuuc && test '${scenario.mode ?? ""}' = icu && ! test -f "$HOME/dependencies-ready"; then continue; fi
+    printf '  %s.so.1 => /lib/%s.so.1\\n' "$library" "$library"
+  done
+}
+sudo() {
+  echo "test-sudo: $*"
+  test "$1" = -n || return 97
+  shift
+  if test "$1" = true; then return ${scenario.sudo ? 0 : 1}; fi
+  test "$1" = "$target/bin/installdependencies.sh" || return 98
+  ${scenario.unresolved ? ":" : 'touch "$HOME/dependencies-ready"'}
+  return ${scenario.installExit ?? 0}
+}
+`;
+    const result = spawnSync("/bin/bash", ["-s"], {
+      input: stubs + runnerPreinstallScript("linux"),
+      env: { ...process.env, HOME: home },
+      cwd: home,
+      encoding: "utf8",
+    });
+    expect(result.status, result.stderr + result.stdout).toBe(scenario.expected);
+    if (scenario.expected === 0) {
+      expect(await readFile(join(target, ".vectis-installed"), "utf8")).toBe(`${runnerVersion}\n`);
+      expect(result.stdout).toContain("vectis-provision: installed");
+    } else {
+      await expect(stat(join(target, ".vectis-installed"))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+      expect(result.stdout).not.toContain("vectis-provision: installed");
+    }
+    if (scenario.ready && !scenario.downloadExit) {
+      expect(result.stdout).toContain("vectis-provision: dependencies-present");
+      expect(result.stdout).not.toContain("test-sudo:");
+    }
+    if (!scenario.ready && !scenario.sudo) {
+      expect(result.stderr).toContain(
+        "dependencies are missing and passwordless sudo is unavailable",
+      );
+      expect(result.stdout).not.toContain("test-sudo: -n /");
+    }
+    if (scenario.installExit) expect(result.stdout).not.toContain("dependencies-verify");
+    if (scenario.downloadExit) {
+      expect(result.stdout).toContain("vectis-provision: download");
+      expect(result.stdout).not.toContain("vectis-provision: checksum");
+    }
+    if (scenario.unresolved) expect(result.stderr).toContain("still missing after installation");
+    if (scenario.mode === "icu")
+      expect(result.stderr).toContain("Missing runner system library: libicuuc");
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test("setup text travels as bounded data chunks and executes only from its decoded guest file", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-setup-data-"));
+  try {
+    const setup =
+      "# Unicode: é漢\nprintf '%s' 'literal $(touch injected) `touch injected2`' > \"$HOME/result\"\n" +
+      "# padding\n".repeat(6000);
+    const scripts = setupUploadScripts("linux", setup);
+    expect(scripts.length).toBeGreaterThan(2);
+    expect(scripts.every((script) => Buffer.byteLength(script) <= 65536)).toBe(true);
+    expect(scripts.join("\n")).not.toContain("touch injected");
+    for (const script of [...scripts, provisionScript("linux", { runner: false, setup: true })]) {
+      const result = spawnSync("/bin/bash", ["-s"], {
+        input: script,
+        env: { ...process.env, HOME: home },
+        cwd: home,
+        encoding: "utf8",
+      });
+      expect(result.status, result.stderr).toBe(0);
+    }
+    expect(await readFile(join(home, "result"), "utf8")).toBe(
+      "literal $(touch injected) `touch injected2`",
+    );
+    await expect(readFile(join(home, "injected"))).rejects.toMatchObject({ code: "ENOENT" });
+    await expect(readFile(join(home, "injected2"))).rejects.toMatchObject({ code: "ENOENT" });
+    expect(() => setupUploadScripts("windows", "é".repeat(32769))).toThrow("64 KiB");
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test("Linux identity reset clears persistent identifiers without shutting down or removing boot units", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-identity-reset-"));
+  try {
+    const files = [
+      "etc/ssh/ssh_host_ed25519_key",
+      "etc/ssh/ssh_host_rsa_key",
+      "etc/vectis/instance-id",
+      "var/lib/dbus/machine-id",
+    ];
+    await Promise.all(
+      ["etc/ssh", "etc/vectis", "var/lib/dbus", "etc/systemd/system"].map((path) =>
+        mkdir(join(home, path), { recursive: true }),
+      ),
+    );
+    for (const path of [
+      ...files,
+      "etc/machine-id",
+      "etc/systemd/system/vectis-instance-identity.service",
+    ])
+      await writeFile(join(home, path), "provisioning-boot-identity");
+    const script = provisionLinuxIdentityResetScript()
+      .replaceAll("/etc/", `${home}/etc/`)
+      .replaceAll("/var/lib/", `${home}/var/lib/`);
+    const result = spawnSync("/bin/bash", ["-s"], {
+      input: `
+sudo() { test "$1" = -n || return 97; shift; "$@"; }
+sync() { echo 'synced'; }
+poweroff() { echo 'unexpected poweroff'; exit 98; }
+export -f sync poweroff
+${script}`,
+      encoding: "utf8",
+      cwd: home,
+    });
+    expect(result.status, result.stderr).toBe(0);
+    expect(result.stdout).toContain("synced");
+    expect(result.stdout).not.toContain("unexpected");
+    for (const path of files)
+      await expect(stat(join(home, path))).rejects.toMatchObject({ code: "ENOENT" });
+    expect(await readFile(join(home, "etc/machine-id"), "utf8")).toBe("uninitialized\n");
+    expect(
+      await readFile(join(home, "etc/systemd/system/vectis-instance-identity.service"), "utf8"),
+    ).toBe("provisioning-boot-identity");
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test("Linux identity reset stops at a failing privileged cleanup step", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-shutdown-"));
+  try {
+    const script = provisionLinuxIdentityResetScript()
+      .replaceAll("/etc/", `${home}/etc/`)
+      .replaceAll("/var/lib/", `${home}/var/lib/`);
+    const result = spawnSync("/bin/bash", ["-s"], {
+      input: `
+sudo() { test "$1" = -n || return 97; shift; "$@"; }
+rm() { echo 'synthetic identity cleanup failed' >&2; return 23; }
+sync() { echo 'unexpected sync'; }
+poweroff() { echo 'unexpected poweroff'; }
+export -f rm sync poweroff
+${script}`,
+      encoding: "utf8",
+      cwd: home,
+    });
+    expect(result.status).toBe(23);
+    expect(result.stderr).toContain("synthetic identity cleanup failed");
+    expect(result.stdout).toContain("vectis-provision: clear-identity");
+    expect(result.stdout).not.toContain("vectis-provision: sync");
+    expect(result.stdout).not.toContain("unexpected");
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test.each([0, 1])(
+  "macOS loginwindow shutdown runs without sudo and preserves exit %s",
+  (exitCode) => {
+    const result = spawnSync("/bin/bash", ["-s"], {
+      input: `
+osascript() {
+  test "$#" = 2 && test "$1" = -e || return 97
+  printf '%s\\n' "$2"
+  return ${exitCode}
+}
+sudo() { echo 'unexpected sudo' >&2; return 98; }
+${provisionMacosShutdownScript()}`,
+      encoding: "utf8",
+    });
+    expect(result.status, result.stderr).toBe(exitCode);
+    expect(result.stdout).toContain('tell application "loginwindow" to «event aevtshut»');
+    expect(result.stderr).not.toContain("unexpected sudo");
+  },
+);
diff --git a/packages/runner/src/provision-scripts.ts b/packages/runner/src/provision-scripts.ts
new file mode 100644
index 00000000..284673ae
--- /dev/null
+++ b/packages/runner/src/provision-scripts.ts
@@ -0,0 +1,182 @@
+import { windowsToolchainScript } from "./windows-toolchain.js";
+import type { Environment } from "../../protocol/src/index.js";
+import { VectisError } from "../../protocol/src/index.js";
+import {
+  runnerDistribution,
+  runnerVersion,
+  preinstalledRunnerDirectory,
+} from "./runner-release.js";
+
+export function runnerPreinstallScript(
+  os: Environment["os"],
+  options: { dependencies?: boolean } = {},
+) {
+  const { url, sha256 } = runnerDistribution(os);
+  const directory = preinstalledRunnerDirectory(os);
+  if (os === "windows")
+    return `$runnerTarget = '${directory}'
+$runnerMarker = Join-Path $runnerTarget '.vectis-installed'
+if (!(Test-Path -LiteralPath $runnerMarker) -or !(Test-Path -LiteralPath (Join-Path $runnerTarget 'bin\\Runner.Listener.exe'))) {
+  Write-Output 'vectis-provision: directory'
+  New-Item -ItemType Directory -Path $runnerTarget -Force | Out-Null
+  $runnerArchive = Join-Path $runnerTarget 'runner.zip'
+  Write-Output 'vectis-provision: download'
+  for ($attempt = 1; $attempt -le 4; $attempt++) {
+    try {
+      Invoke-WebRequest -UseBasicParsing -Uri '${url}' -OutFile $runnerArchive -TimeoutSec 300
+      break
+    } catch {
+      if ($attempt -eq 4) { throw }
+      Start-Sleep -Seconds (2 * $attempt)
+    }
+  }
+  Write-Output 'vectis-provision: checksum'
+  if ((Get-FileHash -Algorithm SHA256 -LiteralPath $runnerArchive).Hash.ToLowerInvariant() -ne '${sha256}') { throw 'Runner checksum mismatch.' }
+  Write-Output 'vectis-provision: extract'
+  Expand-Archive -LiteralPath $runnerArchive -DestinationPath $runnerTarget -Force
+  Write-Output 'vectis-provision: remove-archive'
+  Remove-Item -LiteralPath $runnerArchive -Force
+  Write-Output 'vectis-provision: installed'
+  '${runnerVersion}' | Set-Content -LiteralPath $runnerMarker -Encoding ascii
+}
+`;
+  return `set -euo pipefail
+target="${directory}"
+if ! test -f "$target/.vectis-installed" || ! test -x "$target/bin/Runner.Listener"; then
+  echo 'vectis-provision: directory'
+  mkdir -p "$target"
+  echo 'vectis-provision: download'
+  curl --fail --location --retry 3 --connect-timeout 15 --max-time 300 -o "$target/runner.tar.gz" '${url}'
+  echo 'vectis-provision: checksum'
+  (cd "$target"; printf '${sha256}  runner.tar.gz\\n' | ${os === "macos" ? "shasum -a 256" : "sha256sum"} -c -)
+  echo 'vectis-provision: extract'
+  tar xzf "$target/runner.tar.gz" -C "$target"
+  echo 'vectis-provision: remove-archive'
+  rm "$target/runner.tar.gz"
+  ${
+    os === "linux" && options.dependencies !== false
+      ? `runner_dependencies_present() {
+    local library linked libraries ldconfig_command
+    command -v ldd >/dev/null || { echo 'Runner dependency check requires ldd.' >&2; return 1; }
+    for library in libcoreclr.so libSystem.Security.Cryptography.Native.OpenSsl.so libSystem.IO.Compression.Native.so; do
+      linked=$(ldd "$target/bin/$library" 2>&1) || { printf '%s\\n' "$linked" >&2; return 1; }
+      if printf '%s\\n' "$linked" | grep -F 'not found' >&2; then return 1; fi
+    done
+    ldconfig_command=$(command -v ldconfig || printf '/sbin/ldconfig')
+    libraries=$("$ldconfig_command" -p) || return 1
+    for library in libicuuc libssl libcrypto libkrb5 libz liblttng-ust; do
+      if ! printf '%s\\n' "$libraries" | grep -E "^[[:space:]]*$library\\\\.so(\\\\.|[[:space:]])" >/dev/null; then
+        printf 'Missing runner system library: %s\\n' "$library" >&2
+        return 1
+      fi
+    done
+  }
+  echo 'vectis-provision: dependencies-check'
+  if runner_dependencies_present; then
+    echo 'vectis-provision: dependencies-present'
+  else
+    echo 'vectis-provision: dependencies-install'
+    if ! sudo -n true; then
+      echo 'Runner dependencies are missing and passwordless sudo is unavailable. Install the missing libraries in the guest before provisioning.' >&2
+      exit 1
+    fi
+    sudo -n "$target/bin/installdependencies.sh"
+    echo 'vectis-provision: dependencies-verify'
+    if ! runner_dependencies_present; then
+      echo 'Runner dependencies are still missing after installation.' >&2
+      exit 1
+    fi
+  fi`
+      : ""
+  }
+  echo 'vectis-provision: installed'
+  printf '${runnerVersion}\\n' > "$target/.vectis-installed"
+fi
+`;
+}
+
+export function setupUploadScripts(os: Environment["os"], script: string) {
+  if (Buffer.byteLength(script, "utf8") > 65536)
+    throw new VectisError("guest_script_too_large", "Setup scripts cannot exceed 64 KiB UTF-8.");
+  const encoded = Buffer.from(script, "utf8").toString("base64");
+  const windows = os === "windows";
+  const scripts = [
+    windows
+      ? "$ErrorActionPreference = 'Stop'\n$directory = Join-Path $env:USERPROFILE '.vectis-provision'\nNew-Item -ItemType Directory -Path $directory -Force | Out-Null\n[IO.File]::WriteAllText((Join-Path $directory 'setup.b64'), '')"
+      : 'set -eu\necho \'vectis-provision: setup-upload\'\numask 077\nmkdir -p "$HOME/.vectis-provision"\n: > "$HOME/.vectis-provision/setup.b64"',
+  ];
+  for (let offset = 0; offset < encoded.length; offset += 16384) {
+    const chunk = encoded.slice(offset, offset + 16384);
+    scripts.push(
+      windows
+        ? `$ErrorActionPreference = 'Stop'\n[IO.File]::AppendAllText((Join-Path $env:USERPROFILE '.vectis-provision\\setup.b64'), '${chunk}')`
+        : `set -eu\necho 'vectis-provision: setup-upload'\nprintf '%s' '${chunk}' >> "$HOME/.vectis-provision/setup.b64"`,
+    );
+  }
+  return scripts;
+}
+
+export function provisionScript(
+  os: Environment["os"],
+  options: { runner: boolean; setup: boolean },
+) {
+  const install = options.runner ? runnerPreinstallScript(os) : "";
+  if (os === "windows")
+    return `$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+${windowsToolchainScript()}${install}${
+      options.setup
+        ? `Write-Output 'vectis-provision: setup-decode'
+$setupRoot = Join-Path $env:USERPROFILE '.vectis-provision'
+$setup = Join-Path $setupRoot 'setup.ps1'
+$setupBytes = [Convert]::FromBase64String([IO.File]::ReadAllText((Join-Path $setupRoot 'setup.b64')))
+[IO.File]::WriteAllText($setup, [Text.Encoding]::UTF8.GetString($setupBytes), [Text.UTF8Encoding]::new($true))
+Write-Output 'vectis-provision: setup'
+& powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File $setup
+if ($LASTEXITCODE -ne 0) { throw 'Guest setup script failed.' }
+Write-Output 'vectis-provision: setup-cleanup'
+Remove-Item -LiteralPath $setupRoot -Recurse -Force
+`
+        : ""
+    }`;
+  return `set -euo pipefail
+${install}${
+    options.setup
+      ? `echo 'vectis-provision: setup-decode'
+base64 ${os === "macos" ? "-D" : "--decode"} < "$HOME/.vectis-provision/setup.b64" > "$HOME/.vectis-provision/setup.sh"
+echo 'vectis-provision: setup'
+bash "$HOME/.vectis-provision/setup.sh"
+echo 'vectis-provision: setup-cleanup'
+rm -rf "$HOME/.vectis-provision"
+`
+      : ""
+  }`;
+}
+
+export function provisionMacosShutdownScript() {
+  return `set -eu
+echo 'vectis-provision: loginwindow-shutdown'
+osascript -e 'tell application "loginwindow" to «event aevtshut»'
+`;
+}
+
+export function provisionShutdownScript(os: Environment["os"]) {
+  if (os === "windows")
+    return "$ErrorActionPreference = 'Stop'\nWrite-Output 'vectis-provision: shutdown'\n& shutdown.exe /s /t 0\nif ($LASTEXITCODE -ne 0) { throw 'Guest shutdown failed.' }\n";
+  if (os === "macos")
+    return "set -eu\necho 'vectis-provision: shutdown'\nsudo -n /sbin/shutdown -h now\n";
+  return "set -eu\necho 'vectis-provision: shutdown'\nsudo -n poweroff\n";
+}
+
+export function provisionLinuxIdentityResetScript() {
+  return `set -euo pipefail
+sudo -n bash -s <<'VECTIS_IDENTITY'
+set -euo pipefail
+echo 'vectis-provision: clear-identity'
+rm -f /etc/ssh/ssh_host_* /etc/vectis/instance-id /var/lib/dbus/machine-id
+printf 'uninitialized\\n' > /etc/machine-id
+echo 'vectis-provision: sync'
+sync
+VECTIS_IDENTITY
+`;
+}
diff --git a/packages/runner/src/qmp.test.ts b/packages/runner/src/qmp.test.ts
index 1de9de7d..b138834f 100644
--- a/packages/runner/src/qmp.test.ts
+++ b/packages/runner/src/qmp.test.ts
@@ -1,7 +1,54 @@
 import { spawn } from "node:child_process";
 import { once } from "node:events";
 import { expect, test } from "vitest";
-import { waitForQemu, qemuSshPort } from "./qmp.js";
+import { requestQemuShutdown, waitForQemu, qemuSshPort } from "./qmp.js";
+
+test.each(["accepted", "rejected", "timeout", "invalid", "oversized"])(
+  "QMP shutdown reuses the negotiated channel: %s",
+  async (mode) => {
+    const child = spawn(
+      process.execPath,
+      [
+        "-e",
+        `
+console.log(JSON.stringify({QMP:{}}));
+require('node:readline').createInterface({input:process.stdin}).on('line', line => {
+  const request = JSON.parse(line);
+  if (request.id === 'shutdown') {
+    if (request.execute !== 'system_powerdown') process.exit(97);
+    if ('${mode}' === 'timeout') return;
+    if ('${mode}' === 'invalid') return console.log('invalid');
+    if ('${mode}' === 'oversized') return console.log('x'.repeat(65537));
+    console.log(JSON.stringify({event:'POWERDOWN'}));
+    console.log(JSON.stringify({id:'unrelated', return:{}}));
+    const response = JSON.stringify({id:request.id, ...('${mode}' === 'rejected' ? {error:{class:'CommandNotFound'}} : {return:{}})});
+    process.stdout.write(response.slice(0, 5));
+    setImmediate(() => process.stdout.write(response.slice(5)+'\\n'));
+    return;
+  }
+  console.log(JSON.stringify({id:request.id, return: request.id === 'status' ? {running:true} : request.id === 'network' ? 'TCP[HOST_FORWARD] 1 127.0.0.1 54321 10.0.2.15 22 0 0' : {}}));
+});`,
+      ],
+      { stdio: ["pipe", "pipe", "ignore"] },
+    );
+    const closed = once(child, "close");
+    try {
+      await waitForQemu(child);
+      const errorListeners = child.listenerCount("error");
+      await expect(requestQemuShutdown(child, mode === "timeout" ? 20 : 1000)).resolves.toBe(
+        mode === "accepted",
+      );
+      expect(child.exitCode).toBeNull();
+      expect(child.signalCode).toBeNull();
+      expect(child.stdout.listenerCount("data")).toBe(0);
+      expect(child.stdin.listenerCount("error")).toBe(0);
+      expect(child.listenerCount("error")).toBe(errorListeners);
+    } finally {
+      child.stdin.end();
+      await closed;
+    }
+  },
+);
 
 for (const running of [true, false]) {
   test(`QMP readiness requires running=${running ? "true" : "true and rejects stopped"}`, async () => {
diff --git a/packages/runner/src/qmp.ts b/packages/runner/src/qmp.ts
index fcfbee41..ccdbbc7b 100644
--- a/packages/runner/src/qmp.ts
+++ b/packages/runner/src/qmp.ts
@@ -1,5 +1,19 @@
 import type { ChildProcess } from "node:child_process";
 import { VectisError } from "../../protocol/src/index.js";
+import { requestVmCommand } from "./vm-command.js";
+
+export function requestQemuShutdown(child: ChildProcess, timeoutMs = 5000) {
+  return requestVmCommand(
+    child,
+    JSON.stringify({ execute: "system_powerdown", id: "shutdown" }) + "\n",
+    (message) => {
+      if (!("id" in message) || message.id !== "shutdown") return undefined;
+      if ("error" in message) return false;
+      return "return" in message ? true : undefined;
+    },
+    timeoutMs,
+  );
+}
 
 export function qemuSshPort(report: string): number {
   if (report.length > 65536)
diff --git a/packages/runner/src/runner-access.test.ts b/packages/runner/src/runner-access.test.ts
index eea8eb3e..e17b44ee 100644
--- a/packages/runner/src/runner-access.test.ts
+++ b/packages/runner/src/runner-access.test.ts
@@ -9,7 +9,9 @@ import {
   powershellJobStartedHook,
   assignmentRejectedMarker,
   assignmentRejectedPath,
-  assignmentRejectedScript,
+  runnerGateScript,
+  jobStartedMarker,
+  jobStartedPath,
 } from "./runner-access.js";
 import type { RunnerAccess } from "../../protocol/src/repository-access.js";
 import { runnerStartScript } from "./runner-release.js";
@@ -101,12 +103,22 @@ for (const shell of ["bash", "pwsh"] as const) {
           GITHUB_EVENT_PATH: eventPath,
         });
         expect(result.status, result.stdout + result.stderr).toBe(allowed ? 0 : null);
-        if (!allowed) {
+        if (allowed) {
+          const timestamp = Number(await readFile(join(home, jobStartedPath), "utf8"));
+          expect(timestamp).toBeGreaterThan(Date.now() - 10000);
+          expect(timestamp).toBeLessThanOrEqual(Date.now());
+          await expect(readFile(join(home, `${jobStartedPath}.tmp`))).rejects.toMatchObject({
+            code: "ENOENT",
+          });
+        } else {
           expect(result.stdout).toContain("::error::Vectis refused this job:");
           expect(result.stdout).toContain(assignmentRejectedMarker);
           expect(await readFile(join(home, assignmentRejectedPath), "utf8")).toMatch(
             /mismatch|not allowed|unavailable/,
           );
+          await expect(readFile(join(home, jobStartedPath))).rejects.toMatchObject({
+            code: "ENOENT",
+          });
         }
       } finally {
         await rm(home, { recursive: true, force: true });
@@ -129,13 +141,79 @@ test("policy rendering validates integers, actor bounds and approval scope befor
   expect(() => renderRunnerPolicy({ ...restrictive, approval: "automatic" })).toThrow();
 });
 
+test.each(["1760572800123", "17605728003N"])(
+  "bash records epoch milliseconds atomically with date output %s",
+  async (dateOutput) => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-access-start-"));
+    try {
+      const gate = join(home, "vectis-actions-runner/_vectis");
+      await mkdir(gate, { recursive: true });
+      await writeFile(
+        join(gate, "policy"),
+        renderRunnerPolicy({ repositoryId: 2, actors: "any", approval: "automatic" }),
+      );
+      await writeFile(join(gate, "hook.sh"), bashJobStartedHook());
+      await writeFile(join(home, "date"), `#!/bin/sh\nprintf '%s\\n' '${dateOutput}'\n`, {
+        mode: 0o700,
+      });
+      await writeFile(join(home, "perl"), "#!/bin/sh\nprintf '1760572800456\\n'\n", {
+        mode: 0o700,
+      });
+      await writeFile(
+        join(home, "mv"),
+        `#!/bin/sh
+test ! -e "$3" || exit 1
+test -f "$2" || exit 1
+exec /bin/mv "$@"
+`,
+        { mode: 0o700 },
+      );
+      const result = await runHook("bash", join(gate, "hook.sh"), {
+        ...process.env,
+        HOME: home,
+        GITHUB_REPOSITORY_ID: "2",
+        PATH: `${home}:${process.env.PATH}`,
+      });
+      expect(result.status, result.stderr).toBe(0);
+      expect(await readFile(join(home, jobStartedPath), "utf8")).toBe(
+        `${dateOutput.endsWith("N") ? "1760572800456" : dateOutput}\n`,
+      );
+      await expect(readFile(join(home, `${jobStartedPath}.tmp`))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
+
+test("timestamp write failure does not refuse an allowed assignment", async () => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-access-start-failure-"));
+  try {
+    await writeFile(
+      join(home, "policy"),
+      renderRunnerPolicy({ repositoryId: 2, actors: "any", approval: "automatic" }),
+    );
+    await writeFile(join(home, "hook.sh"), bashJobStartedHook());
+    const result = await runHook("bash", join(home, "hook.sh"), {
+      ...process.env,
+      HOME: home,
+      GITHUB_REPOSITORY_ID: "2",
+    });
+    expect(result.status, result.stderr).toBe(0);
+    expect(result.stdout).not.toContain(assignmentRejectedMarker);
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
 test("the start wrapper installs the marker directory and a refused hook never returns", async () => {
   const home = await mkdtemp(join(tmpdir(), "vectis-access-wrapper-"));
   try {
-    await mkdir(join(home, "vectis-actions-runner"));
+    await mkdir(join(home, "vectis-actions-runner/bin"), { recursive: true });
     await writeFile(join(home, "event.json"), "{}");
     await writeFile(
-      join(home, "vectis-actions-runner/run.sh"),
+      join(home, "vectis-actions-runner/bin/Runner.Listener"),
       '#!/bin/bash\nbash "$ACTIONS_RUNNER_HOOK_JOB_STARTED"\nprintf step-ran\nexit 0\n',
       { mode: 0o700 },
     );
@@ -514,14 +592,14 @@ test.each(["ancestry", "marker", "policy"])(
 
 for (const os of ["linux", "macos", "windows"] as const) {
   test.skipIf(os === "windows" && !pwsh)(
-    `${os} host probe reads the fixed rejection reason`,
+    `${os} host probe reads job start and the fixed rejection reason`,
     async () => {
       const home = await mkdtemp(join(tmpdir(), "vectis-access-probe-"));
       try {
         const script = join(home, os === "windows" ? "probe.ps1" : "probe.sh");
         const executable = os === "windows" ? "pwsh" : "bash";
         const args = os === "windows" ? ["-NoProfile", "-File", script] : [script];
-        await writeFile(script, assignmentRejectedScript(os));
+        await writeFile(script, runnerGateScript(os));
         expect(
           spawnSync(executable, args, {
             env: { ...process.env, HOME: home, USERPROFILE: home },
@@ -536,9 +614,54 @@ for (const os of ["linux", "macos", "windows"] as const) {
             encoding: "utf8",
           }).stdout,
         ).toBe(`${assignmentRejectedMarker}\nactor not allowed\n`);
+        await writeFile(join(home, jobStartedPath), "1760572800123\n");
+        expect(
+          spawnSync(executable, args, {
+            env: { ...process.env, HOME: home, USERPROFILE: home },
+            encoding: "utf8",
+          }).stdout,
+        ).toBe(
+          `${jobStartedMarker}\n1760572800123\n${assignmentRejectedMarker}\nactor not allowed\n`,
+        );
       } finally {
         await rm(home, { recursive: true, force: true });
       }
     },
   );
 }
+
+test.each(["5", "6"])(
+  "automatic cache writer fences workflow run %s before any job step",
+  async (runId) => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-cache-hook-"));
+    try {
+      await mkdir(join(home, "vectis-actions-runner/_vectis"), { recursive: true });
+      const path = join(home, "job-started.sh");
+      await writeFile(
+        join(home, "policy"),
+        renderRunnerPolicy({
+          repositoryId: 2,
+          actors: "any",
+          approval: "automatic",
+          cacheRun: { runId: 5, runAttempt: 1 },
+        }),
+      );
+      await writeFile(path, bashJobStartedHook());
+      const result = await runHook("bash", path, {
+        ...process.env,
+        HOME: home,
+        ...env,
+        GITHUB_RUN_ID: runId,
+      });
+      if (runId === "5") expect(result.status).toBe(0);
+      else {
+        expect(result.stdout).toContain(assignmentRejectedMarker);
+        expect(await readFile(join(home, assignmentRejectedPath), "utf8")).toBe(
+          "cache run mismatch\n",
+        );
+      }
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
diff --git a/packages/runner/src/runner-access.ts b/packages/runner/src/runner-access.ts
index f360f293..23210dd9 100644
--- a/packages/runner/src/runner-access.ts
+++ b/packages/runner/src/runner-access.ts
@@ -4,16 +4,28 @@ import { VectisError, type Environment } from "../../protocol/src/index.js";
 
 export const assignmentRejectedMarker = "VECTIS_RUNNER_ASSIGNMENT_REJECTED";
 export const assignmentRejectedPath = "vectis-actions-runner/_vectis/assignment-rejected";
+export const jobStartedMarker = "VECTIS_RUNNER_JOB_STARTED";
+export const jobStartedPath = "vectis-actions-runner/_vectis/job-started";
 
-export function assignmentRejectedScript(os: Environment["os"]) {
+export function runnerGateScript(os: Environment["os"]) {
   if (os === "windows")
-    return `$marker = Join-Path $env:USERPROFILE '${assignmentRejectedPath}'
+    return `$started = Join-Path $env:USERPROFILE '${jobStartedPath}'
+if (Test-Path -LiteralPath $started -PathType Leaf) {
+  Write-Output '${jobStartedMarker}'
+  Get-Content -LiteralPath $started
+}
+$marker = Join-Path $env:USERPROFILE '${assignmentRejectedPath}'
 if (Test-Path -LiteralPath $marker -PathType Leaf) {
   Write-Output '${assignmentRejectedMarker}'
   Get-Content -LiteralPath $marker
 }
 `;
-  return `marker="$HOME/${assignmentRejectedPath}"
+  return `started="$HOME/${jobStartedPath}"
+if test -f "$started"; then
+  printf '${jobStartedMarker}\\n'
+  cat "$started"
+fi
+marker="$HOME/${assignmentRejectedPath}"
 if test -f "$marker"; then
   printf '${assignmentRejectedMarker}\\n'
   cat "$marker"
@@ -35,6 +47,8 @@ actors=${access.actors === "any" ? "any" : [...new Set(access.actors.ids)].join(
 approval=${access.approval}
 runId=${access.approvedRun?.runId ?? ""}
 runAttempt=${access.approvedRun?.runAttempt ?? ""}
+cacheRunId=${access.cacheRun?.runId ?? ""}
+cacheRunAttempt=${access.cacheRun?.runAttempt ?? ""}
 `;
 }
 
@@ -89,6 +103,9 @@ set -eu
 policy_dir="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
 source "$policy_dir/policy"
 [[ "\${GITHUB_REPOSITORY_ID:-}" == "$repositoryId" ]] || refuse "repository id mismatch"
+if [[ -n "$cacheRunId" ]]; then
+  [[ "\${GITHUB_RUN_ID:-}" == "$cacheRunId" && "\${GITHUB_RUN_ATTEMPT:-}" == "$cacheRunAttempt" ]] || refuse "cache run mismatch"
+fi
 if [[ "$approval" == required ]]; then
   [[ -n "$runId" && -n "$runAttempt" && "\${GITHUB_RUN_ID:-}" == "$runId" && "\${GITHUB_RUN_ATTEMPT:-}" == "$runAttempt" ]] || refuse "run approval mismatch"
 fi
@@ -119,7 +136,14 @@ VECTIS_PYTHON
   [[ "$sender" =~ ^[1-9][0-9]*$ ]] || refuse "triggering actor id unavailable"
   [[ ",$actors," == *",$sender,"* ]] || refuse "triggering actor not allowed"
 fi
-trap - EXIT
+trap - ERR EXIT
+started_at=$(date -u +%s%3N) || started_at=
+if [[ ! "$started_at" =~ ^[0-9]+$ ]]; then
+  started_at=$(perl -MTime::HiRes=time -e 'printf "%d\\n", time * 1000') || started_at=
+fi
+if [[ "$started_at" =~ ^[0-9]+$ ]]; then
+  (umask 077; printf '%s\\n' "$started_at" > "$HOME/${jobStartedPath}.tmp" && mv -f "$HOME/${jobStartedPath}.tmp" "$HOME/${jobStartedPath}") || :
+fi
 `;
 }
 
@@ -160,6 +184,9 @@ function Refuse([string]$reason) {
 try {
   $policy = ConvertFrom-StringData (Get-Content -LiteralPath (Join-Path $PSScriptRoot 'policy') -Raw)
   if ($env:GITHUB_REPOSITORY_ID -cne $policy.repositoryId) { Refuse 'repository id mismatch' }
+  if ($policy.cacheRunId) {
+    if ($env:GITHUB_RUN_ID -cne $policy.cacheRunId -or $env:GITHUB_RUN_ATTEMPT -cne $policy.cacheRunAttempt) { Refuse 'cache run mismatch' }
+  }
   if ($policy.approval -eq 'required') {
     if (!$policy.runId -or !$policy.runAttempt -or $env:GITHUB_RUN_ID -cne $policy.runId -or $env:GITHUB_RUN_ATTEMPT -cne $policy.runAttempt) { Refuse 'run approval mismatch' }
   }
@@ -175,5 +202,10 @@ try {
     if ($allowed -cnotcontains [string]$sender.id) { Refuse 'triggering actor not allowed' }
   }
 } catch { Refuse 'policy verification failed' }
+try {
+  $started = Join-Path $env:USERPROFILE '${jobStartedPath}'
+  [System.IO.File]::WriteAllText("$started.tmp", [string][DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds(), [System.Text.Encoding]::ASCII)
+  [System.IO.File]::Move("$started.tmp", $started)
+} catch {}
 `;
 }
diff --git a/packages/runner/src/runner-release.test.ts b/packages/runner/src/runner-release.test.ts
index 0bc3da0e..d30998e1 100644
--- a/packages/runner/src/runner-release.test.ts
+++ b/packages/runner/src/runner-release.test.ts
@@ -3,10 +3,39 @@ import { mkdir, mkdtemp, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { expect, test } from "vitest";
-import { runnerStartScript } from "./runner-release.js";
+import { runnerStartScript, runnerVersion } from "./runner-release.js";
 
 const access = { repositoryId: 2, actors: "any", approval: "automatic" } as const;
 
+test.each(["linux", "macos"] as const)(
+  "the baked %s runner runs in the guest home while the assignment gate retains its stable private path",
+  async (os) => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-baked-runner-"));
+    try {
+      const target = join(home, ".vectis-runner", runnerVersion);
+      await mkdir(join(target, "bin"), { recursive: true });
+      await writeFile(join(target, "bin/Runner.Listener"), '#!/bin/bash\nprintf "%s\\n" "$PWD"\n', {
+        mode: 0o700,
+      });
+      const result = spawnSync("bash", ["-s"], {
+        input: runnerStartScript(os, "c2VjcmV0", access, { preinstalled: true }),
+        env: { ...process.env, HOME: home },
+        encoding: "utf8",
+      });
+      expect(result.status, result.stderr).toBe(0);
+      expect(result.stdout.trim()).toBe(target);
+      expect((await stat(join(home, "vectis-actions-runner/_vectis/policy"))).mode & 0o777).toBe(
+        0o600,
+      );
+      await expect(stat(join(home, "vectis-actions-runner/run.sh"))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
+
 test("rejects malformed JIT configuration before generating guest shell commands", () => {
   for (const config of ["", "token'; command", "$(command)", "line\nbreak", "a".repeat(60001)])
     for (const os of ["linux", "macos", "windows"] as const)
@@ -16,10 +45,17 @@ test("rejects malformed JIT configuration before generating guest shell commands
 test("jobs keep the guest umask while the assignment gate stays private", async () => {
   const home = await mkdtemp(join(tmpdir(), "vectis-runner-umask-"));
   try {
-    await mkdir(join(home, "vectis-actions-runner"));
-    await writeFile(join(home, "vectis-actions-runner/run.sh"), "#!/bin/bash\numask\n", {
-      mode: 0o700,
-    });
+    await mkdir(join(home, "vectis-actions-runner/bin"), { recursive: true });
+    await mkdir(join(home, "vectis-actions-runner/_vectis"), { recursive: true });
+    await writeFile(join(home, "vectis-actions-runner/_vectis/job-started"), "1234\n");
+    await writeFile(join(home, "vectis-actions-runner/_vectis/job-started.tmp"), "1234\n");
+    await writeFile(
+      join(home, "vectis-actions-runner/bin/Runner.Listener"),
+      '#!/bin/bash\ntest ! -e "$HOME/vectis-actions-runner/_vectis/job-started" || exit 99\ntest ! -e "$HOME/vectis-actions-runner/_vectis/job-started.tmp" || exit 99\numask\n',
+      {
+        mode: 0o700,
+      },
+    );
     await writeFile(join(home, "start.sh"), runnerStartScript("linux", "c2VjcmV0", access));
     const result = spawnSync("bash", ["-c", 'umask 022; exec bash "$0"', join(home, "start.sh")], {
       env: { ...process.env, HOME: home },
@@ -34,3 +70,37 @@ test("jobs keep the guest umask while the assignment gate stays private", async
     await rm(home, { recursive: true, force: true });
   }
 });
+
+test.each(["linux", "macos"] as const)(
+  "%s exposes fatal and deprecated listener exit codes without run.sh rewriting them",
+  async (os) => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-runner-exit-"));
+    try {
+      const directory = join(home, "vectis-actions-runner");
+      await mkdir(join(directory, "bin"), { recursive: true });
+      await writeFile(join(directory, "run.sh"), "#!/bin/bash\nexit 0\n", { mode: 0o700 });
+      await writeFile(
+        join(directory, "bin/Runner.Listener"),
+        '#!/bin/bash\ntest "$ACTIONS_RUNNER_RETURN_VERSION_DEPRECATED_EXIT_CODE" = 1 || exit 99\nexit "$VECTIS_TEST_RUNNER_EXIT"\n',
+        { mode: 0o700 },
+      );
+      for (const code of [0, 1, 5]) {
+        const result = spawnSync("bash", ["-c", runnerStartScript(os, "c2VjcmV0", access)], {
+          env: { ...process.env, HOME: home, VECTIS_TEST_RUNNER_EXIT: String(code) },
+          encoding: "utf8",
+        });
+        expect(result.status, result.stderr).toBe(code);
+      }
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
+
+test("Windows enables deprecated-version errors and propagates the native listener exit", () => {
+  const script = runnerStartScript("windows", "c2VjcmV0", access);
+  expect(script).toContain("$env:ACTIONS_RUNNER_RETURN_VERSION_DEPRECATED_EXIT_CODE = '1'");
+  expect(script).toContain("Runner.Listener.exe run --jitconfig");
+  expect(script).toContain("$runnerExit = $LASTEXITCODE");
+  expect(script).toContain("exit $runnerExit");
+});
diff --git a/packages/runner/src/runner-release.ts b/packages/runner/src/runner-release.ts
index 9990ee02..b2779d2b 100644
--- a/packages/runner/src/runner-release.ts
+++ b/packages/runner/src/runner-release.ts
@@ -1,3 +1,4 @@
+import { cacheSetupScript } from "./cache-guest.js";
 import type { RunnerAccess } from "../../protocol/src/repository-access.js";
 import {
   assignmentRejectedMarker,
@@ -9,6 +10,11 @@ import type { Environment } from "../../protocol/src/index.js";
 import { VectisError } from "../../protocol/src/index.js";
 
 export const runnerVersion = "2.337.0";
+export function preinstalledRunnerDirectory(os: Environment["os"]) {
+  if (os === "windows") return `C:\\vectis\\runner\\${runnerVersion}`;
+  return `$HOME/.vectis-runner/${runnerVersion}`;
+}
+
 const distributions = {
   linux: {
     archive: "actions-runner-linux-arm64-2.337.0.tar.gz",
@@ -61,16 +67,24 @@ rm runner.tar.gz
 `;
 }
 
-export function runnerStartScript(os: Environment["os"], jitConfig: string, access: RunnerAccess) {
+export function runnerStartScript(
+  os: Environment["os"],
+  jitConfig: string,
+  access: RunnerAccess,
+  options: { cacheSizeGiB?: number; preinstalled?: boolean } = {},
+) {
   if (!/^[A-Za-z0-9+/=]{1,60000}$/.test(jitConfig))
     throw new VectisError(
       "invalid_runner_configuration",
       "The JIT runner configuration is invalid.",
     );
   const policy = renderRunnerPolicy(access);
+  const cache =
+    options.cacheSizeGiB === undefined ? "" : cacheSetupScript(os, options.cacheSizeGiB);
+  const target = options.preinstalled ? preinstalledRunnerDirectory(os) : undefined;
   if (os === "windows")
     return `$ErrorActionPreference = 'Stop'
-$gate = Join-Path $env:USERPROFILE 'vectis-actions-runner/_vectis'
+${cache}$gate = Join-Path $env:USERPROFILE 'vectis-actions-runner/_vectis'
 New-Item -ItemType Directory -Path $gate -Force | Out-Null
 @'
 ${policy}'@ | Set-Content -LiteralPath (Join-Path $gate 'policy') -Encoding utf8
@@ -78,15 +92,17 @@ ${policy}'@ | Set-Content -LiteralPath (Join-Path $gate 'policy') -Encoding utf8
 ${powershellJobStartedHook()}'@ | Set-Content -LiteralPath (Join-Path $gate 'job-started.ps1') -Encoding utf8
 $rejected = Join-Path $gate 'assignment-rejected'
 Remove-Item -LiteralPath $rejected -ErrorAction SilentlyContinue
+Remove-Item -LiteralPath (Join-Path $gate 'job-started'), (Join-Path $gate 'job-started.tmp') -ErrorAction SilentlyContinue
+$env:ACTIONS_RUNNER_RETURN_VERSION_DEPRECATED_EXIT_CODE = '1'
 $env:ACTIONS_RUNNER_HOOK_JOB_STARTED = Join-Path $gate 'job-started.ps1'
-Set-Location (Join-Path $env:USERPROFILE 'vectis-actions-runner')
+Set-Location ${target ? `'${target}'` : "(Join-Path $env:USERPROFILE 'vectis-actions-runner')"}
 & .\\bin\\Runner.Listener.exe run --jitconfig '${jitConfig}'
 $runnerExit = $LASTEXITCODE
 if (Test-Path -LiteralPath $rejected) { Write-Output '${assignmentRejectedMarker}'; Get-Content -LiteralPath $rejected; exit 1 }
 exit $runnerExit
 `;
   return `set -eu
-job_umask=$(umask)
+${cache}job_umask=$(umask)
 umask 077
 gate="$HOME/vectis-actions-runner/_vectis"
 mkdir -p "$gate"
@@ -95,12 +111,13 @@ ${policy}VECTIS_POLICY
 cat > "$gate/job-started.sh" <<'VECTIS_HOOK'
 ${bashJobStartedHook()}VECTIS_HOOK
 chmod 700 "$gate/job-started.sh"
-rm -f "$gate/assignment-rejected"
+rm -f "$gate/assignment-rejected" "$gate/job-started" "$gate/job-started.tmp"
+export ACTIONS_RUNNER_RETURN_VERSION_DEPRECATED_EXIT_CODE=1
 export ACTIONS_RUNNER_HOOK_JOB_STARTED="$gate/job-started.sh"
 umask "$job_umask"
-cd "$HOME/vectis-actions-runner"
+cd "${target ?? "$HOME/vectis-actions-runner"}"
 runner_exit=0
-./run.sh --jitconfig '${jitConfig}' || runner_exit=$?
+./bin/Runner.Listener run --jitconfig '${jitConfig}' || runner_exit=$?
 if test -f "$gate/assignment-rejected"; then printf '${assignmentRejectedMarker}\\n'; cat "$gate/assignment-rejected"; exit 1; fi
 exit "$runner_exit"
 `;
diff --git a/packages/runner/src/runtime.test.ts b/packages/runner/src/runtime.test.ts
index 747cbddb..0f9eb8fe 100644
--- a/packages/runner/src/runtime.test.ts
+++ b/packages/runner/src/runtime.test.ts
@@ -4,9 +4,13 @@ import { join } from "node:path";
 import { afterEach, expect, test, vi } from "vitest";
 import { VmRuntime } from "./runtime.js";
 import { readyGuest } from "./guest-ready.js";
+import { availableHostMemory } from "./memory.js";
 vi.mock("./guest-ready.js", () => ({ readyGuest: vi.fn() }));
 
-vi.mock("./memory.js", () => ({ availableHostMemory: async () => 8 * 1024 ** 3 }));
+vi.mock("./memory.js", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./memory.js")>()),
+  availableHostMemory: vi.fn(async () => 8 * 1024 ** 3),
+}));
 
 const failedRemovals = vi.hoisted(() => new Set<string>());
 vi.mock("node:fs/promises", async (importOriginal) => {
@@ -54,6 +58,25 @@ async function fixture(script: string) {
   };
   return { home, runtime, environment };
 }
+hostTest(
+  "startup checks the estimate instead of the ceiling and still refuses insufficient memory",
+  async () => {
+    const { runtime, environment } = await fixture(
+      'process.stdout.write(\'{"event":"vm.running"}\\n\'); setInterval(() => {}, 1000);',
+    );
+    vi.spyOn(runtime, "validate").mockResolvedValue();
+    const generous = { ...environment, memoryMiB: 12288 };
+    vi.mocked(availableHostMemory).mockResolvedValue(3 * 1024 ** 3);
+    const instance = await runtime.start("estimate", generous, () => {});
+    await runtime.stop(instance.id);
+    vi.mocked(availableHostMemory).mockResolvedValue(1024 ** 3);
+    await expect(runtime.start("insufficient", generous, () => {})).rejects.toMatchObject({
+      code: "insufficient_memory",
+    });
+    expect(await runtime.hasWorkDirectory("insufficient")).toBe(false);
+  },
+);
+
 hostTest("natural VM exit removes its disposable disk and preserves the base", async () => {
   const { home, runtime, environment } = await fixture(
     'process.stdout.write(\'{"event":"vm.running"}\\n\'); setTimeout(() => process.exit(0), 100);',
@@ -67,6 +90,91 @@ hostTest("natural VM exit removes its disposable disk and preserves the base", a
   await expect(stat(join(home, "instances", "natural"))).rejects.toMatchObject({ code: "ENOENT" });
   expect(await readFile(environment.basePath, "utf8")).toBe("untouched-base");
 });
+hostTest.each(["linux", "macos"] as const)(
+  "%s provisioning writes in place and cleans only its supervisory directory",
+  async (os) => {
+    const { home, runtime, environment } = await fixture(
+      `const fs = require('node:fs'); const path = require('node:path'); const image = process.argv[4]; const disk = process.argv[3] === 'macos' ? path.join(image, 'disk.img') : image; fs.writeFileSync(disk, 'provisioned'); process.stdout.write('{"event":"vm.running"}\\n'); setInterval(() => {}, 1000);`,
+    );
+    const basePath = os === "macos" ? join(home, "base.bundle") : environment.basePath;
+    if (os === "macos") {
+      await mkdir(basePath);
+      await writeFile(join(basePath, "disk.img"), "parent-clone");
+    }
+    const configured = { ...environment, os, basePath };
+    const instance = await runtime.start("in-place", configured, () => {}, undefined, {
+      diskInPlace: true,
+    });
+    await runtime.stop(instance.id);
+    expect(await readFile(os === "macos" ? join(basePath, "disk.img") : basePath, "utf8")).toBe(
+      "provisioned",
+    );
+    expect(await runtime.hasWorkDirectory(instance.id)).toBe(false);
+  },
+);
+hostTest(
+  "Windows in-place provisioning preserves guest writes to its disk, UEFI variables and TPM",
+  async () => {
+    const { home, runtime, environment } = await fixture("process.exit(99);");
+    const qemu = join(home, "fake-qemu.cjs");
+    const swtpm = join(home, "fake-swtpm.cjs");
+    await writeFile(
+      qemu,
+      `#!${process.execPath}
+if (process.argv.includes('-vectis-isolation-version')) { console.log('1'); process.exit(0); }
+const fs = require('node:fs');
+fs.writeFileSync('disk.qcow2', 'new-disk');
+fs.writeFileSync('uefi-vars.fd', 'new-vars');
+fs.writeFileSync('tpm/state', 'new-tpm');
+console.log(JSON.stringify({QMP:{}}));
+require('node:readline').createInterface({input:process.stdin}).on('line', line => {
+  const {id, execute} = JSON.parse(line);
+  if (execute === 'system_powerdown') {
+    console.log(JSON.stringify({id, return:{}}));
+    setTimeout(() => process.exit(0), 50);
+    return;
+  }
+  console.log(JSON.stringify({id, return: id === 'status' ? {running:true} : id === 'network' ? 'TCP[HOST_FORWARD] 1 127.0.0.1 12345 10.0.2.15 22 0 0' : {}}));
+});
+`,
+      { mode: 0o700 },
+    );
+    await writeFile(
+      swtpm,
+      `#!${process.execPath}\nrequire('node:net').createServer().listen('tpm.sock');`,
+      { mode: 0o700 },
+    );
+    const firmwareVarsPath = join(home, "uefi-vars.fd");
+    const tpmStatePath = join(home, "tpm");
+    await writeFile(firmwareVarsPath, "old-vars");
+    await mkdir(tpmStatePath);
+    await writeFile(join(tpmStatePath, "state"), "old-tpm");
+    const windows = new VmRuntime({ home, qemu, qemuImg: "/must-not-run-qemu-img", swtpm });
+    cleanups.push(() => windows.close());
+    const instance = await windows.start(
+      "windows-in-place",
+      {
+        ...environment,
+        os: "windows",
+        firmwarePath: join(home, "code.fd"),
+        firmwareVarsPath,
+        tpmStatePath,
+      },
+      () => {},
+      undefined,
+      { diskInPlace: true },
+    );
+    const kill = vi.spyOn(instance.process, "kill");
+    expect(await windows.requestShutdown(instance.id)).toBe(true);
+    await instance.settled;
+    expect(instance.process.exitCode).toBe(0);
+    expect(kill).not.toHaveBeenCalled();
+    expect(await readFile(environment.basePath, "utf8")).toBe("new-disk");
+    expect(await readFile(firmwareVarsPath, "utf8")).toBe("new-vars");
+    expect(await readFile(join(tpmStatePath, "state"), "utf8")).toBe("new-tpm");
+    expect(await runtime.hasWorkDirectory(instance.id)).toBe(false);
+  },
+);
 hostTest("failed startup reaps the helper and removes the work disk", async () => {
   const { runtime, environment } = await fixture(
     'process.stdout.write(\'{"event":"vm.error"}\\n\'); setInterval(() => {}, 1000);',
@@ -86,6 +194,39 @@ hostTest("explicit stop waits for process exit and cleanup", async () => {
   expect(await runtime.hasWorkDirectory(instance.id)).toBe(false);
 });
 
+hostTest.each(["linux", "macos"] as const)(
+  "%s graceful request waits for natural exit without forcing",
+  async (os) => {
+    const { runtime, environment } = await fixture(`
+console.log(JSON.stringify({event:'vm.running'}));
+require('node:readline').createInterface({input:process.stdin}).on('line', line => {
+  if (line !== 'shutdown') process.exit(97);
+  console.log(JSON.stringify({event:'vm.shutdown_requested'}));
+  setTimeout(() => process.exit(0), 50);
+});`);
+    const basePath = os === "macos" ? join(environment.basePath + ".bundle") : environment.basePath;
+    if (os === "macos") {
+      await mkdir(basePath);
+      await writeFile(join(basePath, "disk.img"), "synthetic disk");
+    }
+    const instance = await runtime.start(
+      "graceful",
+      { ...environment, os, basePath },
+      () => {},
+      undefined,
+      { diskInPlace: true },
+    );
+    const kill = vi.spyOn(instance.process, "kill");
+    expect(await runtime.requestShutdown(instance.id)).toBe(true);
+    expect(instance.process.exitCode).toBeNull();
+    await instance.settled;
+    expect(instance.process.exitCode).toBe(0);
+    expect(kill).not.toHaveBeenCalled();
+    expect(await runtime.hasWorkDirectory(instance.id)).toBe(false);
+    await expect(runtime.requestShutdown(instance.id)).rejects.toMatchObject({ code: "not_owned" });
+  },
+);
+
 hostTest(
   "partial cleanup preserves exit evidence so Finder residue can be reconciled",
   async () => {
@@ -291,3 +432,54 @@ hostTest(
     expect(await runtime.hasWorkDirectory("unprepared")).toBe(false);
   },
 );
+
+hostTest.each(["linux", "macos"] as const)(
+  "%s attaches a private writable cache fork and finalizes it before deleting the instance",
+  async (os) => {
+    const { home, runtime, environment } = await fixture(
+      `const fs = require("node:fs"); const path = require("node:path"); fs.writeFileSync(path.join(__dirname, "args.json"), JSON.stringify(process.argv.slice(2))); process.on("SIGTERM", () => { fs.writeFileSync(path.join(__dirname, "instances/cache/cache.img"), "flushed-cache"); process.exit(0); }); process.stdout.write('{"event":"vm.running"}\\n'); setInterval(() => {}, 1000);`,
+    );
+    let basePath = environment.basePath;
+    if (os === "macos") {
+      basePath = join(home, "base-bundle");
+      await mkdir(basePath);
+      await writeFile(join(basePath, "disk.img"), "boot");
+    }
+    const sourcePath = join(home, "cache.img");
+    await writeFile(sourcePath, "repository-cache");
+    const stopped = vi.fn(async (path: string) => {
+      expect(instance.process.exitCode !== null || instance.process.signalCode !== null).toBe(true);
+      expect(await readFile(path, "utf8")).toBe("flushed-cache");
+      expect(await runtime.hasWorkDirectory("cache")).toBe(true);
+    });
+    const instance = await runtime.start(
+      "cache",
+      { ...environment, os, basePath },
+      () => {},
+      undefined,
+      { cacheDisk: { sourcePath, stopped } },
+    );
+    const args: string[] = JSON.parse(await readFile(join(home, "args.json"), "utf8"));
+    expect(args.slice(-2)).toEqual(["--cache-disk", join(instance.directory, "cache.img")]);
+    expect(await readFile(join(instance.directory, "cache.img"), "utf8")).toBe("repository-cache");
+    await writeFile(join(instance.directory, "cache.img"), "job-cache");
+    await runtime.stop(instance.id);
+    expect(stopped).toHaveBeenCalledOnce();
+    expect(await readFile(sourcePath, "utf8")).toBe("repository-cache");
+    expect(await runtime.hasWorkDirectory(instance.id)).toBe(false);
+  },
+);
+
+test.each(["linux", "macos", "windows"] as const)(
+  "%s provisioning rejects cache disks before allocating an instance directory",
+  async (os) => {
+    const { runtime, environment } = await fixture("process.exit(99);");
+    await expect(
+      runtime.start("invalid-provision", { ...environment, os }, () => {}, undefined, {
+        diskInPlace: true,
+        cacheDisk: "/unused/cache.img",
+      }),
+    ).rejects.toMatchObject({ code: "invalid_configuration" });
+    expect(await runtime.hasWorkDirectory("invalid-provision")).toBe(false);
+  },
+);
diff --git a/packages/runner/src/runtime.ts b/packages/runner/src/runtime.ts
index 6401bd94..2d5f7207 100644
--- a/packages/runner/src/runtime.ts
+++ b/packages/runner/src/runtime.ts
@@ -1,17 +1,28 @@
+import type { CacheDisk } from "./cache-volume.js";
 import { validateEnvironmentEgress } from "./environment-network.js";
 import { windowsVmArguments } from "./windows-arguments.js";
 import { spawn, type ChildProcess } from "node:child_process";
 import { constants } from "node:fs";
-import { access, copyFile, cp, mkdir, rm, stat, writeFile, readFile } from "node:fs/promises";
+import {
+  access,
+  copyFile,
+  cp,
+  mkdir,
+  rm,
+  stat,
+  writeFile,
+  readFile,
+  symlink,
+} from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 import { Schema } from "effect";
 import { cpus, totalmem } from "node:os";
 import { fileURLToPath } from "node:url";
-import { waitForQemu } from "./qmp.js";
-import { availableHostMemory } from "./memory.js";
+import { requestQemuShutdown, waitForQemu } from "./qmp.js";
+import { availableHostMemory, estimatedVmMemoryMiB } from "./memory.js";
 import { runProcess } from "./process.js";
 import { probeStorage } from "./storage-probe.js";
-import { waitForAppleVm } from "./apple.js";
+import { requestAppleVmShutdown, waitForAppleVm } from "./apple.js";
 import { readyGuest } from "./guest-ready.js";
 import { VectisError, type Environment } from "../../protocol/src/index.js";
 import { instanceIdentity } from "./instance-identity.js";
@@ -52,7 +63,7 @@ async function removeInstanceDirectory(
 }
 
 export class VmRuntime {
-  private readonly owned = new Map<string, OwnedInstance>();
+  private readonly owned = new Map<string, OwnedInstance & { os: Environment["os"] }>();
   constructor(readonly options: RuntimeOptions) {}
   directoryFor(id: string, environment: Environment) {
     return join(environment.storagePath ?? join(this.options.home, "instances"), id);
@@ -114,17 +125,21 @@ export class VmRuntime {
     environment: Environment,
     onExit: (cleaned: boolean) => void,
     signal?: AbortSignal,
+    options: { cacheDisk?: CacheDisk | string | undefined; diskInPlace?: boolean } = {},
   ): Promise<OwnedInstance> {
     signal?.throwIfAborted();
+    const { cacheDisk } = options;
+    if (options.diskInPlace && cacheDisk)
+      throw new VectisError("invalid_configuration", "Provisioning VMs cannot attach cache disks.");
     await this.validate(environment);
     signal?.throwIfAborted();
     if (process.platform !== "darwin" || process.arch !== "arm64")
       throw new VectisError("unsupported_host", "This release requires an Apple Silicon Mac.");
-    if (environment.memoryMiB * 1024 * 1024 > (await availableHostMemory()))
+    if (estimatedVmMemoryMiB(environment) * 1024 * 1024 > (await availableHostMemory()))
       throw new VectisError(
         "insufficient_memory",
         "Not enough free host memory for this instance.",
-        "Stop an idle instance or lower the environment memory.",
+        "Stop an idle instance or free host memory, then retry.",
       );
     if (environment.state !== "ready")
       throw new VectisError(
@@ -165,6 +180,13 @@ export class VmRuntime {
     let launched = false;
     try {
       signal?.throwIfAborted();
+      const cachePath = cacheDisk ? join(directory, "cache.img") : undefined;
+      if (cacheDisk && cachePath)
+        await runProcess(
+          "/bin/cp",
+          ["-c", typeof cacheDisk === "string" ? cacheDisk : cacheDisk.sourcePath, cachePath],
+          signal,
+        );
       let args: string[];
       let knownHostsPath: string | undefined;
       if (environment.os === "windows") {
@@ -180,32 +202,44 @@ export class VmRuntime {
             "Configure the prepared Windows image, firmwarePath, firmwareVarsPath and VECTIS_SWTPM.",
           );
         await access(this.options.swtpm, constants.X_OK);
-        await copyFile(
-          resolve(environment.firmwareVarsPath),
-          join(directory, "uefi-vars.fd"),
-          constants.COPYFILE_FICLONE,
-        );
-        if (environment.tpmStatePath)
-          await cp(resolve(environment.tpmStatePath), join(directory, "tpm"), {
-            recursive: true,
-            mode: constants.COPYFILE_FICLONE,
-          });
-        else await mkdir(join(directory, "tpm"), { mode: 0o700 });
-        const disk = join(directory, "disk.qcow2");
-        await runProcess(
-          this.options.qemuImg,
-          ["create", "-f", "qcow2", "-F", "qcow2", "-b", resolve(environment.basePath), disk],
-          signal,
-        );
+        if (options.diskInPlace) {
+          await symlink(resolve(environment.basePath), join(directory, "disk.qcow2"));
+          await symlink(resolve(environment.firmwareVarsPath), join(directory, "uefi-vars.fd"));
+          if (!environment.tpmStatePath)
+            throw new VectisError("setup_required", "In-place Windows boot requires TPM state.");
+          await symlink(resolve(environment.tpmStatePath), join(directory, "tpm"));
+        } else {
+          await copyFile(
+            resolve(environment.firmwareVarsPath),
+            join(directory, "uefi-vars.fd"),
+            constants.COPYFILE_FICLONE,
+          );
+          if (environment.tpmStatePath)
+            await cp(resolve(environment.tpmStatePath), join(directory, "tpm"), {
+              recursive: true,
+              mode: constants.COPYFILE_FICLONE,
+            });
+          else await mkdir(join(directory, "tpm"), { mode: 0o700 });
+          const disk = join(directory, "disk.qcow2");
+          await runProcess(
+            this.options.qemuImg,
+            ["create", "-f", "qcow2", "-F", "qcow2", "-b", resolve(environment.basePath), disk],
+            signal,
+          );
+        }
         args = windowsVmArguments({
           firmwarePath: environment.firmwarePath,
+          ...(cachePath ? { cacheDiskPath: cachePath } : {}),
           ...(environment.egress !== undefined ? { egress: environment.egress } : {}),
           cpu: environment.cpu,
           memoryMiB: environment.memoryMiB,
         });
       } else {
-        const destination = join(directory, environment.os === "macos" ? "bundle" : "disk.img");
-        await runProcess("/bin/cp", ["-cR", resolve(environment.basePath), destination], signal);
+        const destination = options.diskInPlace
+          ? resolve(environment.basePath)
+          : join(directory, environment.os === "macos" ? "bundle" : "disk.img");
+        if (!options.diskInPlace)
+          await runProcess("/bin/cp", ["-cR", resolve(environment.basePath), destination], signal);
         let seedPath = environment.seedPath;
         if (environment.os === "linux" && environment.sshHostKeyMode === "instance") {
           const identity = await instanceIdentity(directory, id, signal);
@@ -221,6 +255,7 @@ export class VmRuntime {
           join(directory, "efi.bin"),
           ...(seedPath ? [resolve(seedPath)] : []),
           ...(environment.x64 === "rosetta" ? ["--rosetta"] : []),
+          ...(cachePath ? ["--cache-disk", cachePath] : []),
         ];
       }
       await writeFile(
@@ -259,6 +294,8 @@ export class VmRuntime {
       const settled = closed.then(async () => {
         let cleaned = false;
         try {
+          if (cachePath && cacheDisk && typeof cacheDisk !== "string")
+            await cacheDisk.stopped(cachePath);
           await removeInstanceDirectory(
             directory,
             child.pid ? { instanceId: id, pid: child.pid } : undefined,
@@ -272,6 +309,7 @@ export class VmRuntime {
       void settled.catch(() => {});
       const instance = {
         id,
+        os: environment.os,
         process: child,
         directory,
         settled,
@@ -354,6 +392,13 @@ export class VmRuntime {
       return false;
     }
   }
+  async requestShutdown(id: string): Promise<boolean> {
+    const instance = this.owned.get(id);
+    if (!instance) throw new VectisError("not_owned", "This service does not own this VM.");
+    return instance.os === "windows"
+      ? requestQemuShutdown(instance.process)
+      : requestAppleVmShutdown(instance.process);
+  }
   async stop(id: string) {
     const instance = this.owned.get(id);
     if (!instance)
diff --git a/packages/runner/src/supervisor.test.ts b/packages/runner/src/supervisor.test.ts
index 8726ca7d..01d3800f 100644
--- a/packages/runner/src/supervisor.test.ts
+++ b/packages/runner/src/supervisor.test.ts
@@ -6,6 +6,120 @@ import { mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
+test.each([0, 17])("natural VM exit preserves code %s through the supervisor", async (code) => {
+  const home = await mkdtemp(join(tmpdir(), "vectis-supervisor-exit-"));
+  const child = spawn(
+    process.execPath,
+    [
+      fileURLToPath(new URL("./supervisor.ts", import.meta.url)),
+      process.execPath,
+      "-e",
+      `process.stdin.resume(); process.stdin.once('data', () => process.exit(${code})); console.log('ready');`,
+    ],
+    {
+      cwd: home,
+      stdio: ["pipe", "pipe", "ignore"],
+      env: {
+        ...process.env,
+        VECTIS_VM_TPM_EXECUTABLE: "",
+        VECTIS_EXIT_RECEIPT: join(home, "receipt.json"),
+        VECTIS_INSTANCE_ID: "test",
+      },
+    },
+  );
+  const closed = once(child, "close");
+  try {
+    await once(child.stdout, "data");
+    child.stdin.write("shutdown\n");
+    await closed;
+    expect(child.exitCode).toBe(code);
+    expect(child.signalCode).toBeNull();
+  } finally {
+    if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+    await closed;
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test.each([
+  { name: "a clean VM exit", vmExitCode: 0, expectedCode: 0 },
+  { name: "a failed VM exit", vmExitCode: 17, expectedCode: 17 },
+  { name: "a VM that keeps running", vmExitCode: null, expectedCode: 1 },
+])(
+  "TPM exit before $name preserves the correct supervisor result",
+  async ({ vmExitCode, expectedCode }) => {
+    const home = await mkdtemp(join(tmpdir(), "vectis-tpm-exit-"));
+    const helper = join(home, "tpm-helper");
+    const receipt = join(home, "receipt.json");
+    await writeFile(
+      helper,
+      `#!${process.execPath}
+const net = require('node:net');
+require('node:fs').writeFileSync('tpm.pid', String(process.pid));
+net.createServer(socket => {
+  socket.resume();
+  socket.once('end', () => process.exit(0));
+}).listen('tpm.sock');
+`,
+      { mode: 0o700 },
+    );
+    const child = spawn(
+      process.execPath,
+      [
+        fileURLToPath(new URL("./supervisor.ts", import.meta.url)),
+        process.execPath,
+        "-e",
+        `const socket = require('node:net').connect('tpm.sock', () => console.log(process.pid));
+process.on('SIGTERM', () => {
+  require('node:fs').writeFileSync('vm-stopped', 'SIGTERM');
+  process.exit(0);
+});
+process.stdin.resume();
+process.stdin.once('data', () => socket.end());
+socket.once('close', () => {
+  if (${vmExitCode} !== null) setTimeout(() => process.exit(${vmExitCode}), 150);
+});`,
+      ],
+      {
+        cwd: home,
+        stdio: ["pipe", "pipe", "ignore"],
+        env: {
+          ...process.env,
+          VECTIS_VM_TPM_EXECUTABLE: helper,
+          VECTIS_EXIT_RECEIPT: receipt,
+          VECTIS_INSTANCE_ID: "test",
+        },
+      },
+    );
+    const closed = once(child, "close");
+    const deadline = setTimeout(() => child.kill("SIGTERM"), 6000);
+    try {
+      const [chunk] = await once(child.stdout, "data");
+      const vmPid = Number(String(chunk).trim());
+      const tpmPid = Number(await readFile(join(home, "tpm.pid"), "utf8"));
+      child.stdin.write("shutdown\n");
+      await closed;
+      expect(child.exitCode).toBe(expectedCode);
+      expect(child.signalCode).toBeNull();
+      expect(() => process.kill(vmPid, 0)).toThrow();
+      expect(() => process.kill(tpmPid, 0)).toThrow();
+      if (vmExitCode === null)
+        expect(await readFile(join(home, "vm-stopped"), "utf8")).toBe("SIGTERM");
+      else
+        await expect(readFile(join(home, "vm-stopped"))).rejects.toMatchObject({ code: "ENOENT" });
+      expect(JSON.parse(await readFile(receipt, "utf8"))).toEqual({
+        instanceId: "test",
+        pid: child.pid,
+      });
+    } finally {
+      clearTimeout(deadline);
+      if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+      await closed;
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
+
 test("owner pipe closure terminates a child that ignores SIGTERM", async () => {
   const supervisor = fileURLToPath(new URL("./supervisor.ts", import.meta.url));
   const child = spawn(
diff --git a/packages/runner/src/supervisor.ts b/packages/runner/src/supervisor.ts
index a616e026..3f56be05 100644
--- a/packages/runner/src/supervisor.ts
+++ b/packages/runner/src/supervisor.ts
@@ -10,7 +10,12 @@ if (!executable) {
 }
 const shutdown = new AbortController();
 const children: Array<{ process: ChildProcess; closed: Promise<void> }> = [];
-const stop = () => shutdown.abort();
+let primaryChild: ChildProcess | undefined;
+let secondaryExitTimer: ReturnType<typeof setTimeout> | undefined;
+const stop = () => {
+  clearTimeout(secondaryExitTimer);
+  shutdown.abort();
+};
 process.stdin.once("end", stop);
 process.stdin.once("error", stop);
 process.once("SIGTERM", stop);
@@ -22,12 +27,29 @@ function owned(command: string, arguments_: string[], primary: boolean) {
     stdio: primary ? ["pipe", "inherit", "inherit"] : ["ignore", "ignore", "inherit"],
   });
   const closed = new Promise<void>((resolve) =>
-    child.once("close", () => {
-      stop();
+    child.once("close", (code, signal) => {
+      if (primary) {
+        if (code !== 0 || signal !== null) process.exitCode = code ?? 1;
+        stop();
+      } else if (!shutdown.signal.aborted) {
+        if (primaryChild) {
+          // QEMU can close the TPM socket before its own close event arrives.
+          secondaryExitTimer ??= setTimeout(() => {
+            process.exitCode = 1;
+            stop();
+          }, 3000);
+        } else {
+          process.exitCode = 1;
+          stop();
+        }
+      }
       resolve();
     }),
   );
-  child.once("error", stop);
+  child.once("error", () => {
+    process.exitCode = 1;
+    stop();
+  });
   child.stdin?.on("error", stop);
   children.push({ process: child, closed });
   return child;
@@ -57,8 +79,8 @@ try {
     }
   }
   shutdown.signal.throwIfAborted();
-  const child = owned(executable, args, true);
-  if (child.stdin) process.stdin.pipe(child.stdin);
+  primaryChild = owned(executable, args, true);
+  if (primaryChild.stdin) process.stdin.pipe(primaryChild.stdin);
   await new Promise<void>((resolve) => {
     shutdown.signal.addEventListener("abort", () => resolve(), { once: true });
     if (shutdown.signal.aborted) resolve();
@@ -67,6 +89,7 @@ try {
   process.stderr.write("The supervised VM or TPM could not start.\n");
   process.exitCode = 1;
 } finally {
+  clearTimeout(secondaryExitTimer);
   for (const child of children)
     if (child.process.exitCode === null && child.process.signalCode === null)
       child.process.kill("SIGTERM");
diff --git a/packages/runner/src/vm-command.ts b/packages/runner/src/vm-command.ts
new file mode 100644
index 00000000..9e493813
--- /dev/null
+++ b/packages/runner/src/vm-command.ts
@@ -0,0 +1,50 @@
+import type { ChildProcess } from "node:child_process";
+
+export function requestVmCommand(
+  child: ChildProcess,
+  command: string,
+  response: (message: object) => boolean | undefined,
+  timeoutMs: number,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    let buffer = "";
+    const finish = (accepted: boolean) => {
+      clearTimeout(timer);
+      child.stdout?.off("data", data);
+      child.stdin?.off("error", unavailable);
+      child.off("close", closed);
+      child.off("error", unavailable);
+      resolve(accepted);
+    };
+    const unavailable = () => finish(false);
+    const closed = () => finish(child.exitCode === 0 && child.signalCode === null);
+    const data = (chunk: Buffer) => {
+      buffer += chunk.toString("utf8");
+      if (buffer.length > 65536) return unavailable();
+      let newline: number;
+      while ((newline = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        let message: unknown;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          return unavailable();
+        }
+        if (!message || typeof message !== "object") return unavailable();
+        const accepted = response(message);
+        if (accepted !== undefined) return finish(accepted);
+      }
+    };
+    const timer = setTimeout(unavailable, timeoutMs);
+    child.stdout?.on("data", data);
+    child.stdin?.once("error", unavailable);
+    child.once("close", closed);
+    child.once("error", unavailable);
+    if (child.exitCode !== null || child.signalCode !== null) return closed();
+    if (!child.stdout || !child.stdin?.writable) return unavailable();
+    child.stdin.write(command, (error) => {
+      if (error) unavailable();
+    });
+  });
+}
diff --git a/packages/runner/src/windows-arguments.test.ts b/packages/runner/src/windows-arguments.test.ts
index c3b77ec8..2ca488f7 100644
--- a/packages/runner/src/windows-arguments.test.ts
+++ b/packages/runner/src/windows-arguments.test.ts
@@ -16,3 +16,15 @@ test.each([
     `user,id=net0,ipv6=off,vectis-isolate=${isolation},hostfwd=tcp:127.0.0.1:0-:22`,
   );
 });
+
+test("cache uses a separate raw NVMe disk with a stable guest identity and escaped path", () => {
+  const args = windowsVmArguments({
+    firmwarePath: "/firmware.fd",
+    cpu: 2,
+    memoryMiB: 4096,
+    cacheDiskPath: "/instance,one/cache.img",
+  });
+  expect(args).toContain("file=/instance,,one/cache.img,if=none,id=cache,format=raw,cache=unsafe");
+  expect(args).toContain("nvme,drive=cache,serial=VECTISCACHE");
+  expect(args).toContain("nvme,drive=system,serial=vectis-system,bootindex=0");
+});
diff --git a/packages/runner/src/windows-arguments.ts b/packages/runner/src/windows-arguments.ts
index e8ce0f6b..3c3fd535 100644
--- a/packages/runner/src/windows-arguments.ts
+++ b/packages/runner/src/windows-arguments.ts
@@ -6,6 +6,7 @@ export function windowsVmArguments(input: {
   cpu: number;
   memoryMiB: number;
   egress?: Egress;
+  cacheDiskPath?: string;
 }) {
   return [
     "-machine",
@@ -26,6 +27,14 @@ export function windowsVmArguments(input: {
     "file=disk.qcow2,if=none,id=system,format=qcow2",
     "-device",
     "nvme,drive=system,serial=vectis-system,bootindex=0",
+    ...(input.cacheDiskPath
+      ? [
+          "-drive",
+          `file=${resolve(input.cacheDiskPath).replaceAll(",", ",,")},if=none,id=cache,format=raw,cache=unsafe`,
+          "-device",
+          "nvme,drive=cache,serial=VECTISCACHE",
+        ]
+      : []),
     "-device",
     "ramfb",
     "-device",
diff --git a/packages/runner/src/windows-bootstrap.test.ts b/packages/runner/src/windows-bootstrap.test.ts
index 88c4cdec..10f35d03 100644
--- a/packages/runner/src/windows-bootstrap.test.ts
+++ b/packages/runner/src/windows-bootstrap.test.ts
@@ -20,43 +20,46 @@ const connection = {
   hostKeyAlias: "windows-test",
 };
 
-test("bootstrap failures retain bounded private details and expose only a known stage", async () => {
-  const directory = await mkdtemp(join(tmpdir(), "vectis-bootstrap-diagnostic-"));
-  const diagnostic = {
-    stage: "git-verification",
-    message: "private error ".repeat(1000),
-    line: 99,
-  };
-  const signal = AbortSignal.timeout(1000);
-  vi.mocked(executeGuest).mockResolvedValue({
-    exitCode: 0,
-    stdout: JSON.stringify(diagnostic),
-    stderr: "",
-    truncated: false,
-  });
-  try {
-    const error = await windowsBootstrapFailure(connection, directory, signal);
-    expect(error).toMatchObject({ code: "guest_preparation_failed" });
-    expect(error.message).toContain("during git-verification");
-    expect(error.message).not.toContain("private error");
-    const path = join(directory, "bootstrap-diagnostic.json");
-    expect(JSON.parse(await readFile(path, "utf8"))).toEqual({
-      ...diagnostic,
-      message: diagnostic.message.slice(0, 4096),
+test.each(["git-verification", "runner-preinstall", "windows-defender"])(
+  "bootstrap failures retain bounded private details and expose known stage %s",
+  async (stage) => {
+    const directory = await mkdtemp(join(tmpdir(), "vectis-bootstrap-diagnostic-"));
+    const diagnostic = {
+      stage,
+      message: "private error ".repeat(1000),
+      line: 99,
+    };
+    const signal = AbortSignal.timeout(1000);
+    vi.mocked(executeGuest).mockResolvedValue({
+      exitCode: 0,
+      stdout: JSON.stringify(diagnostic),
+      stderr: "",
+      truncated: false,
     });
-    expect((await stat(path)).mode & 0o777).toBe(0o600);
-    expect(executeGuest).toHaveBeenCalledWith(
-      connection,
-      expect.stringContaining("diagnostic.json"),
-      {
-        signal,
-        shell: "powershell",
-      },
-    );
-  } finally {
-    await rm(directory, { recursive: true, force: true });
-  }
-});
+    try {
+      const error = await windowsBootstrapFailure(connection, directory, signal);
+      expect(error).toMatchObject({ code: "guest_preparation_failed" });
+      expect(error.message).toContain(`during ${stage}`);
+      expect(error.message).not.toContain("private error");
+      const path = join(directory, "bootstrap-diagnostic.json");
+      expect(JSON.parse(await readFile(path, "utf8"))).toEqual({
+        ...diagnostic,
+        message: diagnostic.message.slice(0, 4096),
+      });
+      expect((await stat(path)).mode & 0o777).toBe(0o600);
+      expect(executeGuest).toHaveBeenCalledWith(
+        connection,
+        expect.stringContaining("diagnostic.json"),
+        {
+          signal,
+          shell: "powershell",
+        },
+      );
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  },
+);
 
 test("missing, malformed or truncated diagnostics preserve the original failure", async () => {
   const directory = await mkdtemp(join(tmpdir(), "vectis-bootstrap-fallback-"));
diff --git a/packages/runner/src/windows-bootstrap.ts b/packages/runner/src/windows-bootstrap.ts
index 79dc47ec..01a4d921 100644
--- a/packages/runner/src/windows-bootstrap.ts
+++ b/packages/runner/src/windows-bootstrap.ts
@@ -11,10 +11,13 @@ const Diagnostic = Schema.Struct({
     "ssh-installation",
     "ssh-configuration",
     "ssh-access",
+    "windows-defender",
+    "windows-toolchain",
     "git-download",
     "git-checksum",
     "git-installation",
     "git-verification",
+    "runner-preinstall",
     "toolchain",
     "completion",
   ]),
diff --git a/packages/runner/src/windows-defender.test.ts b/packages/runner/src/windows-defender.test.ts
new file mode 100644
index 00000000..5a53d570
--- /dev/null
+++ b/packages/runner/src/windows-defender.test.ts
@@ -0,0 +1,30 @@
+import { expect, test } from "vitest";
+import { windowsDefenderCommands } from "./windows-defender.js";
+
+test("Defender exclusions require both policy writes through cmd without PowerShell cmdlets", () => {
+  const commands = windowsDefenderCommands();
+  expect(commands.slice(0, 2)).toEqual([
+    {
+      shell: "cmd",
+      script: String.raw`reg.exe add "HKLM\SOFTWARE\Policies\Microsoft\Windows Defender\Exclusions" /v Exclusions_Paths /t REG_DWORD /d 1 /f`,
+      allowFailure: false,
+    },
+    {
+      shell: "cmd",
+      script: String.raw`reg.exe add "HKLM\SOFTWARE\Policies\Microsoft\Windows Defender\Exclusions\Paths" /v "C:\\" /t REG_SZ /d 0 /f`,
+      allowFailure: false,
+    },
+  ]);
+  const policies = commands.slice(2);
+  expect(policies).toHaveLength(8);
+  for (const command of policies) {
+    expect(command).toMatchObject({ shell: "cmd", allowFailure: true });
+    expect(command.script).toMatch(
+      /^reg.exe add "HKLM\\SOFTWARE\\Policies\\Microsoft\\Windows Defender(?:\\[^"\r\n]+)?" \/v \w+ \/t REG_DWORD \/d [012] \/f$/,
+    );
+  }
+  for (const command of commands) {
+    expect(command.shell).toBe("cmd");
+    expect(command.script).not.toMatch(/powershell|(?:Add|Set|Get)-Mp/);
+  }
+});
diff --git a/packages/runner/src/windows-defender.ts b/packages/runner/src/windows-defender.ts
new file mode 100644
index 00000000..7a9ef543
--- /dev/null
+++ b/packages/runner/src/windows-defender.ts
@@ -0,0 +1,39 @@
+interface DefenderCommand {
+  readonly shell: "cmd";
+  readonly script: string;
+  readonly allowFailure: boolean;
+}
+
+// Defender-changing PowerShell cmdlets can be blocked by AMSI even in isolated commands.
+export function windowsDefenderCommands(): readonly DefenderCommand[] {
+  const policy = String.raw`HKLM\SOFTWARE\Policies\Microsoft\Windows Defender`;
+  const policies = [
+    [policy, "DisableAntiSpyware", 1],
+    ...[
+      "DisableRealtimeMonitoring",
+      "DisableBehaviorMonitoring",
+      "DisableIOAVProtection",
+      "DisableScriptScanning",
+      "DisableOnAccessProtection",
+    ].map((name) => [policy + "\\Real-Time Protection", name, 1] as const),
+    [policy + "\\Spynet", "SpynetReporting", 0],
+    [policy + "\\Spynet", "SubmitSamplesConsent", 2],
+  ];
+  return [
+    {
+      shell: "cmd",
+      script: `reg.exe add "${policy}\\Exclusions" /v Exclusions_Paths /t REG_DWORD /d 1 /f`,
+      allowFailure: false,
+    },
+    {
+      shell: "cmd",
+      script: String.raw`reg.exe add "${policy}\Exclusions\Paths" /v "C:\\" /t REG_SZ /d 0 /f`,
+      allowFailure: false,
+    },
+    ...policies.map(([key, name, value]) => ({
+      shell: "cmd" as const,
+      script: `reg.exe add "${key}" /v ${name} /t REG_DWORD /d ${value} /f`,
+      allowFailure: true,
+    })),
+  ];
+}
diff --git a/packages/runner/src/windows-installation.ts b/packages/runner/src/windows-installation.ts
index f9844b5f..40d63c63 100644
--- a/packages/runner/src/windows-installation.ts
+++ b/packages/runner/src/windows-installation.ts
@@ -1,3 +1,5 @@
+import { runnerPreinstallScript } from "./provision-scripts.js";
+import { runnerVersion } from "./runner-release.js";
 import { redact } from "../../client/src/redact.js";
 import { spawn } from "node:child_process";
 import { constants } from "node:fs";
@@ -125,6 +127,8 @@ export async function installWindowsGuest(
         revision: Schema.Literal("windows-11-arm64-v1"),
         setupId: Schema.String,
         imageName: Schema.String,
+        runnerVersion: Schema.optional(Schema.String),
+        provisionedAt: Schema.optional(Schema.String),
       }),
     )(JSON.parse(completed));
     if (receipt.setupId !== setupId || receipt.imageName !== input.imageName)
@@ -140,7 +144,17 @@ export async function installWindowsGuest(
         );
     if (!(await stat(join(directory, "tpm"))).isDirectory())
       throw new VectisError("invalid_prepared_image", "Windows TPM state is missing.");
-    return windowsEnvironment(input, directory);
+    return windowsEnvironment(
+      input,
+      directory,
+      receipt.runnerVersion && receipt.provisionedAt
+        ? {
+            revision: receipt.revision,
+            runnerVersion: receipt.runnerVersion,
+            provisionedAt: receipt.provisionedAt,
+          }
+        : undefined,
+    );
   }
   if (input.memoryMiB * 1024 ** 2 > (await availableHostMemory()))
     throw new VectisError(
@@ -296,6 +310,19 @@ export async function installWindowsGuest(
         }
         if (result.exitCode === 0 && lines.at(-1)?.trim() === setupId) {
           verifyGuestReadiness(lines[0] ?? "");
+          const installed = await executeGuest(
+            connection,
+            "$ErrorActionPreference = 'Stop'\n" + runnerPreinstallScript("windows"),
+            {
+              signal: AbortSignal.any([bounded, AbortSignal.timeout(600000)]),
+              shell: "powershell",
+            },
+          );
+          if (installed.exitCode !== 0)
+            throw new VectisError(
+              "runner_install_failed",
+              "The prepared Windows runner could not be installed.",
+            );
           const shutdown = await executeGuest(connection, "shutdown.exe /s /t 3", {
             signal: AbortSignal.any([bounded, AbortSignal.timeout(15000)]),
             shell: "powershell",
@@ -315,6 +342,7 @@ export async function installWindowsGuest(
             throw new VectisError("guest_shutdown_failed", "Windows did not finish shutting down.");
           await rm(join(directory, "setup-media"), { recursive: true });
           await rm(media.iso);
+          const provisionedAt = new Date().toISOString();
           await writeFile(
             join(directory, "image.json"),
             JSON.stringify({
@@ -322,10 +350,16 @@ export async function installWindowsGuest(
               setupId,
               imageName: input.imageName,
               credentialId: media.credentialId,
+              runnerVersion,
+              provisionedAt,
             }),
             { mode: 0o600 },
           );
-          return windowsEnvironment(input, directory);
+          return windowsEnvironment(input, directory, {
+            revision: "windows-11-arm64-v1",
+            runnerVersion,
+            provisionedAt,
+          });
         }
       } catch (error) {
         if (
@@ -365,12 +399,17 @@ export async function installWindowsGuest(
   }
 }
 
-function windowsEnvironment(input: WindowsInstallation, directory: string): Environment {
+function windowsEnvironment(
+  input: WindowsInstallation,
+  directory: string,
+  image?: Environment["image"],
+): Environment {
   return {
     id: input.id,
     name: input.name,
     os: "windows",
     state: "ready",
+    ...(image ? { image } : {}),
     cpu: input.cpu,
     memoryMiB: input.memoryMiB,
     basePath: join(directory, "disk.qcow2"),
diff --git a/packages/runner/src/windows-media.test.ts b/packages/runner/src/windows-media.test.ts
new file mode 100644
index 00000000..4b4313ec
--- /dev/null
+++ b/packages/runner/src/windows-media.test.ts
@@ -0,0 +1,70 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test, vi } from "vitest";
+import { runProcess } from "./process.js";
+import { prepareWindowsMedia } from "./windows-media.js";
+import { windowsSeed } from "./windows-seed.js";
+
+vi.mock("./process.js", () => ({ runProcess: vi.fn() }));
+afterEach(() => vi.resetAllMocks());
+
+test("setup media includes every isolated Defender script referenced by prepare.ps1", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "vectis-windows-media-"));
+  try {
+    for (const name of ["guest-key", "ssh_host_ed25519_key"])
+      for (const suffix of ["", ".pub"])
+        await writeFile(join(directory, name + suffix), "synthetic key");
+    vi.mocked(runProcess).mockImplementation(async () => {
+      await writeFile(join(directory, "setup.iso"), "synthetic iso");
+      return "";
+    });
+    const configuration = {
+      id: "windows",
+      name: "Windows",
+      cpu: 2,
+      memoryMiB: 4096,
+      diskGiB: 64,
+      imageDirectory: directory,
+      storagePath: directory,
+      isoPath: join(directory, "windows.iso"),
+      driversPath: join(directory, "drivers.iso"),
+      firmwarePath: join(directory, "code.fd"),
+      firmwareVarsPath: join(directory, "vars.fd"),
+      imageName: "Windows 11 Pro",
+      acceptLicense: true,
+    };
+    const password = "Generated-local-test-password-42!";
+    await prepareWindowsMedia(
+      configuration,
+      directory,
+      "setup-test",
+      {
+        get: vi.fn().mockResolvedValue(password),
+        set: vi.fn(),
+      },
+      AbortSignal.timeout(10000),
+    );
+    const seed = windowsSeed({
+      id: "setup-test",
+      password,
+      imageName: configuration.imageName,
+      acceptLicense: true,
+    });
+    const prepare = await readFile(join(directory, "setup-media", "prepare.ps1"), "utf8");
+    expect(prepare).toBe(seed.script);
+    expect(prepare).not.toMatch(/(?:Add|Set|Get)-Mp/);
+    for (const file of seed.defenderScripts) {
+      expect(prepare).toContain(file.name);
+      expect(await readFile(join(directory, "setup-media", file.name), "utf8")).toBe(file.contents);
+    }
+    expect(runProcess).toHaveBeenCalledOnce();
+    expect(runProcess).toHaveBeenCalledWith(
+      "/usr/bin/hdiutil",
+      expect.arrayContaining(["makehybrid", join(directory, "setup-media")]),
+      expect.anything(),
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
diff --git a/packages/runner/src/windows-media.ts b/packages/runner/src/windows-media.ts
index 3430222f..80a70971 100644
--- a/packages/runner/src/windows-media.ts
+++ b/packages/runner/src/windows-media.ts
@@ -50,6 +50,8 @@ export async function prepareWindowsMedia(
   });
   await writeFile(join(media, "Autounattend.xml"), seed.answer, { mode: 0o600 });
   await writeFile(join(media, "prepare.ps1"), seed.script, { mode: 0o600 });
+  for (const file of seed.defenderScripts)
+    await writeFile(join(media, file.name), file.contents, { mode: 0o600 });
   const iso = join(directory, "setup.iso");
   await runProcess(
     "/usr/bin/hdiutil",
diff --git a/packages/runner/src/windows-seed.test.ts b/packages/runner/src/windows-seed.test.ts
index 5599967a..e292d81f 100644
--- a/packages/runner/src/windows-seed.test.ts
+++ b/packages/runner/src/windows-seed.test.ts
@@ -4,7 +4,10 @@ import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
-import { windowsGit, windowsSeed } from "./windows-seed.js";
+import { windowsSeed } from "./windows-seed.js";
+import { runnerPreinstallScript } from "./provision-scripts.js";
+import { windowsGit, windowsToolchainScript } from "./windows-toolchain.js";
+import { windowsDefenderCommands } from "./windows-defender.js";
 
 const configuration = {
   id: "isolated-setup",
@@ -12,6 +15,34 @@ const configuration = {
   imageName: "Windows 11 Pro",
   acceptLicense: true,
 };
+test("fresh Windows images share toolchain provisioning and bootstrap the runner with Windows PowerShell", () => {
+  const { script } = windowsSeed(configuration);
+  expect(script).toContain(runnerPreinstallScript("windows"));
+  expect(script).toContain("$stage = 'runner-preinstall'");
+  expect(script).toContain(windowsToolchainScript());
+  expect(script).toContain("$stage = 'windows-toolchain'");
+});
+
+test("fresh installation starts separate Defender processes before the toolchain without embedding their cmdlets", () => {
+  const { script, defenderScripts } = windowsSeed(configuration);
+  const commands = windowsDefenderCommands();
+  expect(defenderScripts).toHaveLength(commands.length);
+  expect(script).not.toMatch(/(?:Add|Set|Get)-Mp/);
+  let previous = script.indexOf("$stage = 'windows-defender'");
+  expect(previous).toBeGreaterThan(-1);
+  for (const [index, command] of commands.entries()) {
+    const file = defenderScripts[index];
+    expect(file?.contents).toContain(command.script);
+    expect(command.shell).toBe("cmd");
+    const launch = `& cmd.exe /d /c ('"' + (Join-Path $PSScriptRoot '${file?.name}') + '"')`;
+    const position = script.indexOf(launch);
+    expect(position).toBeGreaterThan(previous);
+    const next = script.slice(position + launch.length).split("\n")[1];
+    expect(next).toContain(command.allowFailure ? "Write-Warning" : "throw");
+    previous = position;
+  }
+  expect(script.indexOf("$stage = 'windows-toolchain'")).toBeGreaterThan(previous);
+});
 
 test("Windows answer media requires explicit license acceptance and safe script identifiers", () => {
   expect(() => windowsSeed({ ...configuration, acceptLicense: false })).toThrow(/license terms/);
@@ -20,18 +51,18 @@ test("Windows answer media requires explicit license acceptance and safe script
   expect(() => windowsSeed({ ...configuration, imageName: "Windows\u0000Pro" })).toThrow();
 });
 
-test("guest git is checked against its pinned hash before anything uses it", () => {
+test("fresh Windows images verify the pinned Git download before launching its installer", () => {
   const { script } = windowsSeed(configuration);
   const download = script.indexOf(windowsGit.url);
   const verify = script.indexOf(windowsGit.sha256);
-  const use = script.indexOf("git.exe");
+  const use = script.indexOf("Start-Process -FilePath $installer");
   expect(download).toBeGreaterThan(-1);
   expect(verify).toBeGreaterThan(download);
   expect(use).toBeGreaterThan(verify);
-  expect(script).toContain("throw 'Git checksum mismatch'");
+  expect(script).toContain('throw "Tool checksum mismatch: $Url"');
   expect(script).toContain("Invoke-WebRequest -UseBasicParsing");
-  expect(script).toContain("$gitRoot = 'C:\\Program Files\\MinGit'");
-  expect(script).not.toContain("$gitRoot = 'C:\\Program Files\\Git'");
+  expect(script).toContain("$gitRoot = 'C:\\Program Files\\Git'");
+  expect(script).not.toContain("MinGit-2.");
 });
 
 test("answer-file values cannot inject XML or leak the password into the bootstrap script", () => {
@@ -52,6 +83,63 @@ test("answer-file values cannot inject XML or leak the password into the bootstr
 const hasPowerShell =
   spawnSync("pwsh", ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", "exit 0"]).status ===
   0;
+
+test.skipIf(!hasPowerShell).each(["none", "optional", "exclusion-policy", "exclusion-path"])(
+  "seed executes separate command files and handles %s failure",
+  async (failure) => {
+    const directory = await mkdtemp(join(tmpdir(), "vectis-seed-defender-"));
+    try {
+      const { script, defenderScripts } = windowsSeed(configuration);
+      for (const file of defenderScripts)
+        await writeFile(join(directory, file.name), file.contents);
+      const setup = script.slice(
+        script.indexOf("  $stage = 'windows-defender'"),
+        script.indexOf("  $stage = 'windows-toolchain'"),
+      );
+      const failedIndex =
+        failure === "exclusion-policy" ? 0 : failure === "exclusion-path" ? 1 : -1;
+      const wrapper = join(directory, "test.ps1");
+      await writeFile(
+        wrapper,
+        String.raw`$ErrorActionPreference = 'Stop'
+$script:count = 0
+function Invoke-TestCommand($File) {
+  $name = [IO.Path]::GetFileName($File.Trim('"'))
+  $index = [int]($name -replace '^defender-(\d+)\..*$', '$1')
+  if ($index -ne $script:count) { throw 'Commands ran out of order' }
+  $contents = Get-Content -LiteralPath (Join-Path $PSScriptRoot $name) -Raw
+  if ($name -like '*.cmd' -and $contents -notmatch 'reg.exe add') { throw 'Registry command missing' }
+  Write-Output "executed=$index"
+  $script:count++
+  $global:LASTEXITCODE = 0
+  if ($index -eq ${failedIndex} -or ('${failure}' -eq 'optional' -and $index -ge 2)) { $global:LASTEXITCODE = 1 }
+}
+function cmd.exe {
+  if ($args[0] -ne '/d' -or $args[1] -ne '/c') { throw 'Expected cmd shell' }
+  Invoke-TestCommand $args[-1]
+}
+${setup}
+Write-Output 'toolchain-next'
+`,
+      );
+      const result = spawnSync(
+        "pwsh",
+        ["-NoLogo", "-NoProfile", "-NonInteractive", "-File", wrapper],
+        { encoding: "utf8", timeout: 10000 },
+      );
+      const shouldFail = failedIndex >= 0;
+      expect(result.status, result.stderr).toBe(shouldFail ? 1 : 0);
+      expect(result.stdout.includes("toolchain-next")).toBe(!shouldFail);
+      const count = shouldFail ? failedIndex + 1 : defenderScripts.length;
+      expect(result.stdout.match(/executed=\d+/g)).toEqual(
+        Array.from({ length: count }, (_, index) => `executed=${index}`),
+      );
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  },
+);
+
 test.skipIf(!hasPowerShell).each([false, true])(
   "bootstrap records failure and clears stale completion even if diagnostics cannot be written: %s",
   async (failDiagnostics) => {
@@ -101,7 +189,10 @@ function Set-Content {
             timeout: 10000,
           },
         ),
-      ).rejects.toMatchObject({ code: 1 });
+      ).rejects.toMatchObject({
+        code: 1,
+        stderr: expect.stringContaining("Synthetic capability installation failure"),
+      });
       expect(await readFile(join(root, "failed"), "utf8")).toMatch(/^ssh-installation\s*$/);
       if (failDiagnostics) {
         await expect(readFile(join(root, "diagnostic.json"), "utf8")).rejects.toMatchObject({
diff --git a/packages/runner/src/windows-seed.ts b/packages/runner/src/windows-seed.ts
index 503170aa..d1fdf933 100644
--- a/packages/runner/src/windows-seed.ts
+++ b/packages/runner/src/windows-seed.ts
@@ -1,3 +1,6 @@
+import { runnerPreinstallScript } from "./provision-scripts.js";
+import { windowsToolchainScript } from "./windows-toolchain.js";
+import { windowsDefenderCommands } from "./windows-defender.js";
 import { VectisError } from "../../protocol/src/index.js";
 
 function xml(value: string) {
@@ -12,16 +15,6 @@ function component(name: string, contents: string) {
   return `<component name="${name}" processorArchitecture="arm64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">${contents}</component>`;
 }
 
-// Windows installation runs unattended from start to finish, so nobody is ever inside the guest to
-// add git, and actions/checkout needs it. MinGit is the portable build GitHub's own runner images
-// use; everything else a workflow needs comes from its own steps.
-export const windowsGit = {
-  version: "2.55.0.5",
-  url: "https://github.com/git-for-windows/git/releases/download/v2.55.0.windows.5/MinGit-2.55.0.5-arm64.zip",
-  sha256: "05843f9d6e60306c3ab886799e2c67200caab921571f10512df3493049179ddb",
-  bytes: 37650057,
-};
-
 const bootstrap = `$ErrorActionPreference='Stop'; $media=@(Get-Volume | Where-Object FileSystemLabel -eq 'VECTIS_SETUP'); if($media.Count -ne 1){throw 'Setup media unavailable'}; & ($media[0].DriveLetter + ':\\prepare.ps1')`;
 export const windowsBootstrapCommand = `powershell.exe -NoProfile -ExecutionPolicy Bypass -EncodedCommand ${Buffer.from(bootstrap, "utf16le").toString("base64")}`;
 
@@ -61,6 +54,22 @@ ${component("Microsoft-Windows-International-Core", language)}
 ${component("Microsoft-Windows-Shell-Setup", `<OOBE><HideEULAPage>true</HideEULAPage><HideOnlineAccountScreens>true</HideOnlineAccountScreens><HideWirelessSetupInOOBE>true</HideWirelessSetupInOOBE><ProtectYourPC>3</ProtectYourPC></OOBE><UserAccounts><LocalAccounts><LocalAccount wcm:action="add">${password}<Name>vectis</Name><DisplayName>Vectis CI</DisplayName><Group>Administrators</Group></LocalAccount></LocalAccounts></UserAccounts><AutoLogon>${password}<Enabled>true</Enabled><LogonCount>1</LogonCount><Username>vectis</Username></AutoLogon><FirstLogonCommands><SynchronousCommand wcm:action="add"><Order>1</Order><Description>Prepare the Vectis guest</Description><CommandLine>${windowsBootstrapCommand}</CommandLine></SynchronousCommand></FirstLogonCommands>`)}
 </settings></unattend>
 `;
+  const defenderCommands = windowsDefenderCommands();
+  const defenderScripts = defenderCommands.map((command, index) => ({
+    ...command,
+    name: `defender-${index}.cmd`,
+    contents: `@echo off\r\n${command.script}\r\n`,
+  }));
+  const defenderSetup = defenderScripts
+    .map((file, index) => {
+      const invoke = `& cmd.exe /d /c ('"' + (Join-Path $PSScriptRoot '${file.name}') + '"')`;
+      return `${invoke}\nif ($LASTEXITCODE -ne 0) { ${
+        file.allowFailure
+          ? `Write-Warning 'vectis-provision: optional Defender command ${index} failed'`
+          : `throw 'Defender command ${index} failed. Inspect the preceding guest error.'`
+      } }`;
+    })
+    .join("\n");
   const script = String.raw`$ErrorActionPreference = 'Stop'
 $ProgressPreference = 'SilentlyContinue'
 $root = 'C:\ProgramData\Vectis'
@@ -107,35 +116,20 @@ Subsystem sftp sftp-server.exe
   Start-Service sshd
   Set-ExecutionPolicy -Scope Process RemoteSigned -Force
   Set-ExecutionPolicy -Scope CurrentUser RemoteSigned -Force
-  $stage = 'git-download'
-  $gitArchive = Join-Path $env:TEMP 'vectis-mingit.zip'
-  Invoke-WebRequest -UseBasicParsing -Uri '${windowsGit.url}' -OutFile $gitArchive
-  $stage = 'git-checksum'
-  if ((Get-FileHash -Algorithm SHA256 $gitArchive).Hash.ToLowerInvariant() -ne '${windowsGit.sha256}') { throw 'Git checksum mismatch' }
-  $stage = 'git-installation'
-  $gitRoot = 'C:\Program Files\MinGit'
-  Expand-Archive -Path $gitArchive -DestinationPath $gitRoot -Force
-  Remove-Item $gitArchive -Force
-  $gitCommand = Join-Path $gitRoot 'cmd'
-  $machinePath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
-  if ($machinePath -notlike "*$gitCommand*") { [Environment]::SetEnvironmentVariable('Path', "$machinePath;$gitCommand", 'Machine') }
-  $stage = 'git-verification'
-  $gitVersion = & (Join-Path $gitCommand 'git.exe') --version 2>&1
-  if ($LASTEXITCODE -ne 0) { throw "Git is not usable: $($gitVersion -join ' ')" }
-  $stage = 'toolchain'
-  $system = Get-ComputerInfo -Property WindowsProductName,WindowsVersion,OsBuildNumber
-  [pscustomobject]@{
-    WindowsProductName = $system.WindowsProductName
-    WindowsVersion = $system.WindowsVersion
-    OsBuildNumber = $system.OsBuildNumber
-    Git = $gitVersion
-  } | ConvertTo-Json | Set-Content (Join-Path $root 'toolchain.json')
+  $stage = 'windows-defender'
+${defenderSetup}
+  $stage = 'windows-toolchain'
+${windowsToolchainScript()}
+  $stage = 'runner-preinstall'
+${runnerPreinstallScript("windows")}
   $stage = 'completion'
   Remove-Item C:\Windows\Panther\unattend.xml,C:\Windows\Panther\Unattend\unattend.xml,C:\Windows\System32\Sysprep\unattend.xml -Force -ErrorAction SilentlyContinue
   Remove-Item (Join-Path $root 'failed') -Force -ErrorAction SilentlyContinue
   'SETUP_ID' | Set-Content (Join-Path $root 'prepared') -Encoding ascii
 } catch {
   $failure = $_
+  $errorRecord = ($failure | Out-String -Width 4096)
+  [Console]::Error.WriteLine($errorRecord.Substring(0, [Math]::Min($errorRecord.Length, 16384)))
   $message = $failure.Exception.Message
   try {
     [pscustomobject]@{
@@ -148,5 +142,5 @@ Subsystem sftp sftp-server.exe
   exit 1
 }
 `;
-  return { answer, script: script.replace("SETUP_ID", input.id) };
+  return { answer, script: script.replace("SETUP_ID", input.id), defenderScripts };
 }
diff --git a/packages/runner/src/windows-toolchain.test.ts b/packages/runner/src/windows-toolchain.test.ts
new file mode 100644
index 00000000..c1752937
--- /dev/null
+++ b/packages/runner/src/windows-toolchain.test.ts
@@ -0,0 +1,252 @@
+import { spawnSync } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test } from "vitest";
+import { provisionScript } from "./provision-scripts.js";
+import { windowsSeed } from "./windows-seed.js";
+import {
+  windowsGit,
+  windowsPowerShell,
+  windowsToolchainScript,
+  windowsZstd,
+} from "./windows-toolchain.js";
+
+test("Windows tooling pins official ARM64 installers and the emulated x64 zstd release", () => {
+  expect([windowsGit, windowsZstd, windowsPowerShell]).toEqual([
+    {
+      version: "2.55.0.5",
+      url: "https://github.com/git-for-windows/git/releases/download/v2.55.0.windows.5/Git-2.55.0.5-arm64.exe",
+      sha256: "c955de342b1465bc637f0e71fddf4e28e8d0b829668ec1866ab32a839303e8e3",
+    },
+    {
+      version: "1.5.7",
+      url: "https://github.com/facebook/zstd/releases/download/v1.5.7/zstd-v1.5.7-win64.zip",
+      sha256: "acb4e8111511749dc7a3ebedca9b04190e37a17afeb73f55d4425dbf0b90fad9",
+    },
+    {
+      version: "7.6.6",
+      url: "https://github.com/PowerShell/PowerShell/releases/download/v7.6.6/PowerShell-7.6.6-win-arm64.msi",
+      sha256: "387d0af8e92ba97f73616c91fa8f29a284e8f82ee6c40fe12dade971bb05bac4",
+    },
+  ]);
+  const script = windowsToolchainScript();
+  for (const release of [windowsGit, windowsZstd, windowsPowerShell]) {
+    expect(script).toContain(`Get-VectisRelease '${release.url}' '${release.sha256}'`);
+    expect(release.sha256).toMatch(/^[a-f0-9]{64}$/);
+  }
+  expect(script).toContain("Get-FileHash -Algorithm SHA256 -LiteralPath $Destination");
+  expect(script).toContain('throw "Tool checksum mismatch: $Url"');
+  expect(script).toContain("Invoke-WebRequest -UseBasicParsing");
+  expect(script).toContain("$attempt -le 4");
+  expect(script).toContain("/VERYSILENT /NORESTART /NOCANCEL /SP- /SUPPRESSMSGBOXES");
+  expect(script).toContain('/COMPONENTS="gitlfs" /o:PathOption=BashOnly');
+  expect(script).toContain("$tarExe = Join-Path $gitRoot 'usr\\bin\\tar.exe'");
+  expect(script).toContain("$bashExe = Join-Path $gitRoot 'bin\\bash.exe'");
+  expect(script).toContain("ADD_PATH=1 USE_MU=0 ENABLE_MU=0");
+  expect(script).toContain("$process.ExitCode -notin @(0, 3010)");
+  expect(script).toContain("$toolPaths + $remainingPath");
+  expect(script).toContain("$zstdRoot, $pwshRoot, (Join-Path $gitRoot 'usr\\bin')");
+  expect(script).toContain("$toolPaths + $minGitPaths");
+  expect(script).toContain("$binaries.Count -ne 1");
+});
+
+test("Windows provisioning verifies effective security settings and records protected services", () => {
+  const script = windowsToolchainScript();
+  for (const step of [
+    "toolchain-admin-check",
+    "windows-update-policy",
+    "hvci",
+    "git-install",
+    "git-verify",
+    "zstd-install-x64-emulation",
+    "zstd-verify",
+    "pwsh-install",
+    "pwsh-verify",
+    "toolchain-path",
+    "toolchain-manifest",
+  ])
+    expect(script).toContain(`vectis-provision: ${step}`);
+  expect(script).not.toMatch(/(?:Add|Set|Get)-Mp/);
+  expect(script).toContain("@('wuauserv', 'UsoSvc', 'WaaSMedicSvc', 'WSearch', 'SysMain')");
+  expect(script).toContain("Set-Service -Name $serviceName -StartupType Disabled");
+  expect(script).toContain("Stop-Service -Name $serviceName -Force");
+  expect(script).toContain("$serviceName -notin @('UsoSvc', 'WaaSMedicSvc')");
+  expect(script).toContain("-Name NoAutoUpdate -Value 1 -Type DWord");
+  expect(script).toContain("Set-ItemProperty -Path $hvciPath -Name Enabled -Value 0 -Type DWord");
+  expect(script).toContain("SecurityServicesRunning) -contains 2");
+  expect(script).toContain("ConvertFrom-Json");
+  expect(script).toContain(
+    "Add-Member -NotePropertyName $name -NotePropertyValue $values[$name] -Force",
+  );
+});
+
+test("provisioning removes the obsolete security startup task and receipts", () => {
+  const script = windowsToolchainScript();
+  expect(script).toContain(
+    "Unregister-ScheduledTask -TaskName 'Vectis-VerifySecurity' -Confirm:$false",
+  );
+  expect(script).toContain("@('verify-security.ps1', 'security-boot.json', 'security-boot.log')");
+  expect(script).toContain("$manifest.PSObject.Properties.Remove('BootVerification')");
+  expect(script).not.toMatch(/Register-ScheduledTask|New-ScheduledTask|FromBase64String/);
+});
+
+const hasPowerShell =
+  spawnSync("pwsh", ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", "exit 0"]).status ===
+  0;
+
+test.skipIf(!hasPowerShell)(
+  "manifest replaces stale Defender observations with next-boot policy intent",
+  async () => {
+    const directory = await mkdtemp(join(tmpdir(), "vectis-toolchain-manifest-"));
+    const manifestPath = join(directory, "toolchain.json");
+    try {
+      await writeFile(
+        manifestPath,
+        JSON.stringify({
+          Custom: "preserved",
+          Defender: { Mode: "disabled", ExclusionPath: [], RealTimeProtectionEnabled: false },
+          BootVerification: "stale",
+        }),
+      );
+      const script = windowsToolchainScript();
+      const manifest = script.slice(
+        script.indexOf("$manifestPath ="),
+        script.indexOf("Write-Output 'vectis-provision: remove-security-startup-task'"),
+      );
+      const result = spawnSync(
+        "pwsh",
+        [
+          "-NoLogo",
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          "& ([scriptblock]::Create([Console]::In.ReadToEnd()))",
+        ],
+        {
+          input: String.raw`$ErrorActionPreference = 'Stop'
+$toolchainRoot = $env:VECTIS_TEST_ROOT
+function Get-ComputerInfo { [pscustomobject]@{ WindowsProductName = 'Windows 11'; WindowsVersion = 'test'; OsBuildNumber = 'test' } }
+function Get-ItemProperty { [pscustomobject]@{ NoAutoUpdate = 1 } }
+function Get-MpPreference { throw 'Defender preferences unavailable' }
+function Get-MpComputerStatus { throw 'Defender status unavailable' }
+${manifest}`,
+          env: { ...process.env, VECTIS_TEST_ROOT: directory },
+          encoding: "utf8",
+          timeout: 10000,
+        },
+      );
+      expect(result.status, result.stderr).toBe(0);
+      const saved = JSON.parse((await readFile(manifestPath, "utf8")).replace(/^\uFEFF/, ""));
+      expect(saved.Custom).toBe("preserved");
+      expect(saved.Defender).toEqual({
+        Mode: "policy-exclusion",
+        PolicyExclusionPath: ["C:\\"],
+        AppliesAt: "next-boot",
+      });
+      expect(saved).not.toHaveProperty("BootVerification");
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  },
+);
+
+test.skipIf(!hasPowerShell).each([
+  { firstGit: "bin", wrongTool: "" },
+  { firstGit: "cmd", wrongTool: "" },
+  ...["git.exe", "bash.exe", "tar.exe", "zstd.exe", "pwsh.exe"].map((wrongTool) => ({
+    firstGit: "bin",
+    wrongTool,
+  })),
+])(
+  "PATH accepts duplicate matches and validates the first tool: $firstGit / $wrongTool",
+  ({ firstGit, wrongTool }) => {
+    const script = windowsToolchainScript();
+    const check = script.slice(
+      script.indexOf("$expectedTools = @{"),
+      script.indexOf("Write-Output 'vectis-provision: toolchain-manifest'"),
+    );
+    const result = spawnSync(
+      "pwsh",
+      [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        "& ([scriptblock]::Create([Console]::In.ReadToEnd()))",
+      ],
+      {
+        input: String.raw`$ErrorActionPreference = 'Stop'
+function Join-Path($Path, $ChildPath) { "$Path\$ChildPath" }
+$gitRoot = 'C:\Program Files\Git'
+$gitExe = Join-Path $gitRoot 'cmd\git.exe'
+$bashExe = Join-Path $gitRoot 'bin\bash.exe'
+$tarExe = Join-Path $gitRoot 'usr\bin\tar.exe'
+$zstdExe = 'C:\Program Files\zstd\zstd.exe'
+$pwshExe = 'C:\Program Files\PowerShell\7\pwsh.exe'
+function Get-Command($Name, $CommandType, [switch]$All) {
+  if (!$All -or $CommandType -ne 'Application') { throw 'Expected all application matches' }
+  $paths = @{
+    'git.exe' = @((Join-Path $gitRoot '${firstGit}\git.exe'), $gitExe)
+    'bash.exe' = @($bashExe)
+    'tar.exe' = @($tarExe)
+    'zstd.exe' = @($zstdExe)
+    'pwsh.exe' = @($pwshExe)
+  }
+  if ($Name -eq '${wrongTool}') { [pscustomobject]@{ Source = "C:\unexpected\$Name" } }
+  foreach ($path in $paths[$Name]) { [pscustomobject]@{ Source = $path } }
+  [pscustomobject]@{ Source = "C:\later\$Name" }
+}
+${check}`,
+        encoding: "utf8",
+        timeout: 10000,
+      },
+    );
+    expect(result.status, result.stderr).toBe(wrongTool ? 1 : 0);
+    if (wrongTool) expect(result.stderr).toContain(`Unexpected tool on PATH: ${wrongTool}`);
+  },
+);
+
+const scripts = [
+  windowsToolchainScript(),
+  windowsSeed({
+    id: "parse-test",
+    password: "Generated-local-test-password-42!",
+    imageName: "Windows 11 Pro",
+    acceptLicense: true,
+  }).script,
+  ...[false, true].flatMap((runner) =>
+    [false, true].map((setup) => provisionScript("windows", { runner, setup })),
+  ),
+];
+
+test.each(scripts.map((script, index) => ({ script, index })))(
+  "Windows script $index avoids PowerShell 7-only syntax",
+  ({ script }) => {
+    expect(Buffer.byteLength(script, "utf8")).toBeLessThanOrEqual(65536);
+    expect(script).not.toMatch(/\?\?|\?\.|&&|\|\||ForEach-Object\s+-Parallel|\?\s*[^\r\n]+\s*:/);
+  },
+);
+
+test.skipIf(!hasPowerShell).each(scripts.map((script, index) => ({ script, index })))(
+  "Windows script $index parses on the host without executing guest commands",
+  ({ script }) => {
+    const result = spawnSync(
+      "pwsh",
+      [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        String.raw`
+$tokens = $null
+$errors = $null
+$null = [System.Management.Automation.Language.Parser]::ParseInput([Console]::In.ReadToEnd(), [ref]$tokens, [ref]$errors)
+if ($errors.Count) { $errors | ForEach-Object { [Console]::Error.WriteLine($_.ToString()) }; exit 1 }
+`,
+      ],
+      { input: script, encoding: "utf8", timeout: 10000 },
+    );
+    expect(result.status, result.stderr || result.error?.message).toBe(0);
+  },
+);
diff --git a/packages/runner/src/windows-toolchain.ts b/packages/runner/src/windows-toolchain.ts
new file mode 100644
index 00000000..ca3c711e
--- /dev/null
+++ b/packages/runner/src/windows-toolchain.ts
@@ -0,0 +1,198 @@
+export const windowsGit = {
+  version: "2.55.0.5",
+  url: "https://github.com/git-for-windows/git/releases/download/v2.55.0.windows.5/Git-2.55.0.5-arm64.exe",
+  sha256: "c955de342b1465bc637f0e71fddf4e28e8d0b829668ec1866ab32a839303e8e3",
+};
+
+export const windowsZstd = {
+  version: "1.5.7",
+  url: "https://github.com/facebook/zstd/releases/download/v1.5.7/zstd-v1.5.7-win64.zip",
+  sha256: "acb4e8111511749dc7a3ebedca9b04190e37a17afeb73f55d4425dbf0b90fad9",
+};
+
+export const windowsPowerShell = {
+  version: "7.6.6",
+  url: "https://github.com/PowerShell/PowerShell/releases/download/v7.6.6/PowerShell-7.6.6-win-arm64.msi",
+  sha256: "387d0af8e92ba97f73616c91fa8f29a284e8f82ee6c40fe12dade971bb05bac4",
+};
+
+export function windowsToolchainScript() {
+  return String.raw`$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+Write-Output 'vectis-provision: toolchain-admin-check'
+if ($env:PROCESSOR_ARCHITECTURE -ne 'ARM64') { throw 'ARM64 Windows is required.' }
+$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+$principal = New-Object Security.Principal.WindowsPrincipal($identity)
+if (!$principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { throw 'Windows toolchain provisioning requires an elevated administrator.' }
+$toolchainRoot = 'C:\ProgramData\Vectis'
+New-Item -ItemType Directory -Path $toolchainRoot -Force | Out-Null
+function Get-VectisToolVersion([string]$Executable, [string[]]$Arguments) {
+  if (!(Test-Path -LiteralPath $Executable)) { return '' }
+  $output = & $Executable @Arguments 2>&1
+  if ($LASTEXITCODE -ne 0) { throw "Tool verification failed: $Executable ($($output -join ' '))" }
+  return ($output -join [Environment]::NewLine).Trim()
+}
+function Get-VectisRelease([string]$Url, [string]$Sha256, [string]$Destination) {
+  Write-Output "vectis-provision: tool-download $Url"
+  for ($attempt = 1; $attempt -le 4; $attempt++) {
+    try {
+      Invoke-WebRequest -UseBasicParsing -Uri $Url -OutFile $Destination -TimeoutSec 300
+      break
+    } catch {
+      if ($attempt -eq 4) { throw }
+      Start-Sleep -Seconds (2 * $attempt)
+    }
+  }
+  Write-Output 'vectis-provision: tool-checksum'
+  if ((Get-FileHash -Algorithm SHA256 -LiteralPath $Destination).Hash.ToLowerInvariant() -ne $Sha256) { throw "Tool checksum mismatch: $Url" }
+}
+Write-Output 'vectis-provision: windows-update-policy'
+$updatePolicy = 'HKLM:\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdate\AU'
+New-Item -Path $updatePolicy -Force | Out-Null
+Set-ItemProperty -Path $updatePolicy -Name NoAutoUpdate -Value 1 -Type DWord
+if ((Get-ItemProperty -Path $updatePolicy).NoAutoUpdate -ne 1) { throw 'Windows Update policy did not persist.' }
+$serviceStates = @{}
+foreach ($serviceName in @('wuauserv', 'UsoSvc', 'WaaSMedicSvc', 'WSearch', 'SysMain')) {
+  Write-Output "vectis-provision: service-$serviceName"
+  $serviceErrors = @()
+  try {
+    Set-Service -Name $serviceName -StartupType Disabled
+  } catch {
+    $serviceErrors += $_.Exception.Message
+  }
+  try {
+    Stop-Service -Name $serviceName -Force
+  } catch {
+    $serviceErrors += $_.Exception.Message
+  }
+  $serviceError = $serviceErrors -join '; '
+  $service = Get-Service -Name $serviceName
+  $disabled = $service.StartType -eq 'Disabled' -and $service.Status -eq 'Stopped'
+  $serviceStates[$serviceName] = [pscustomobject]@{ StartType = [string]$service.StartType; Status = [string]$service.Status; Error = $serviceError }
+  if (!$disabled) {
+    if ($serviceName -notin @('UsoSvc', 'WaaSMedicSvc')) { throw "Service $serviceName is not disabled and stopped: $serviceError" }
+    Write-Warning "vectis-provision: service-$serviceName-protected start=$($service.StartType) status=$($service.Status): $serviceError"
+  } else {
+    Write-Output "vectis-provision: service-$serviceName-disabled"
+  }
+}
+Write-Output 'vectis-provision: hvci'
+$hvciPath = 'HKLM:\SYSTEM\CurrentControlSet\Control\DeviceGuard\Scenarios\HypervisorEnforcedCodeIntegrity'
+$hvciBefore = $null
+if (Test-Path -LiteralPath $hvciPath) { $hvciBefore = (Get-ItemProperty -Path $hvciPath).Enabled }
+$hvciEnabled = $hvciBefore
+if ($null -ne $hvciBefore) {
+  Set-ItemProperty -Path $hvciPath -Name Enabled -Value 0 -Type DWord
+  if ((Get-ItemProperty -Path $hvciPath).Enabled -ne 0) { throw 'HVCI configuration did not persist.' }
+  $hvciEnabled = 0
+}
+$deviceGuard = Get-CimInstance -Namespace 'root\Microsoft\Windows\DeviceGuard' -ClassName Win32_DeviceGuard
+$hvciRunning = @($deviceGuard.SecurityServicesRunning) -contains 2
+$hvciState = [pscustomobject]@{ PreviousEnabled = $hvciBefore; Enabled = $hvciEnabled; Running = $hvciRunning; RebootRequired = ($hvciRunning -or ($null -ne $hvciBefore -and $hvciBefore -ne 0)) }
+Write-Output "vectis-provision: hvci-configured enabled=$($hvciState.Enabled) reboot-required=$($hvciState.RebootRequired)"
+$downloads = Join-Path $env:TEMP ('vectis-toolchain-' + [Guid]::NewGuid().ToString('N'))
+New-Item -ItemType Directory -Path $downloads | Out-Null
+try {
+  Write-Output 'vectis-provision: git-install'
+  $gitRoot = 'C:\Program Files\Git'
+  $gitExe = Join-Path $gitRoot 'cmd\git.exe'
+  $bashExe = Join-Path $gitRoot 'bin\bash.exe'
+  $tarExe = Join-Path $gitRoot 'usr\bin\tar.exe'
+  if ((Get-VectisToolVersion $gitExe @('--version')) -ne 'git version 2.55.0.windows.5' -or !(Test-Path -LiteralPath $bashExe) -or !(Test-Path -LiteralPath $tarExe)) {
+    $installer = Join-Path $downloads 'git-arm64.exe'
+    Get-VectisRelease '${windowsGit.url}' '${windowsGit.sha256}' $installer
+    $process = Start-Process -FilePath $installer -ArgumentList '/VERYSILENT /NORESTART /NOCANCEL /SP- /SUPPRESSMSGBOXES /ALLUSERS /DIR="C:\Program Files\Git" /COMPONENTS="gitlfs" /o:PathOption=BashOnly' -Wait -PassThru
+    if ($process.ExitCode -ne 0) { throw "Git installer failed: $($process.ExitCode)" }
+  }
+  Write-Output 'vectis-provision: git-verify'
+  $gitVersion = Get-VectisToolVersion $gitExe @('--version')
+  $tarVersion = Get-VectisToolVersion $tarExe @('--version')
+  $bashVersion = Get-VectisToolVersion $bashExe @('--version')
+  if ($gitVersion -ne 'git version 2.55.0.windows.5' -or $tarVersion -notmatch 'GNU tar' -or $bashVersion -notmatch 'GNU bash') { throw 'Full Git, GNU tar or Bash verification failed.' }
+  Write-Output 'vectis-provision: zstd-install-x64-emulation'
+  $zstdRoot = 'C:\Program Files\zstd'
+  $zstdExe = Join-Path $zstdRoot 'zstd.exe'
+  if ((Get-VectisToolVersion $zstdExe @('--version')) -notmatch 'v1\.5\.7\b') {
+    $archive = Join-Path $downloads 'zstd.zip'
+    Get-VectisRelease '${windowsZstd.url}' '${windowsZstd.sha256}' $archive
+    $extracted = Join-Path $downloads 'zstd'
+    Expand-Archive -LiteralPath $archive -DestinationPath $extracted -Force
+    foreach ($nested in @(Get-ChildItem -LiteralPath $extracted -Recurse -Filter '*.zip' -File)) {
+      Expand-Archive -LiteralPath $nested.FullName -DestinationPath (Join-Path $extracted 'nested') -Force
+    }
+    $binaries = @(Get-ChildItem -LiteralPath $extracted -Recurse -Filter zstd.exe -File)
+    if ($binaries.Count -ne 1) { throw 'Expected exactly one zstd.exe in the verified release.' }
+    New-Item -ItemType Directory -Path $zstdRoot -Force | Out-Null
+    Copy-Item -Path (Join-Path $binaries[0].DirectoryName '*') -Destination $zstdRoot -Recurse -Force
+  }
+  Write-Output 'vectis-provision: zstd-verify'
+  $zstdVersion = Get-VectisToolVersion $zstdExe @('--version')
+  if ($zstdVersion -notmatch 'v1\.5\.7\b') { throw 'zstd x64 emulation verification failed.' }
+  Write-Output 'vectis-provision: pwsh-install'
+  $pwshRoot = 'C:\Program Files\PowerShell\7'
+  $pwshExe = Join-Path $pwshRoot 'pwsh.exe'
+  $pwshArguments = @('-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '$PSVersionTable.PSVersion.ToString()')
+  if ((Get-VectisToolVersion $pwshExe $pwshArguments) -ne '${windowsPowerShell.version}') {
+    $installer = Join-Path $downloads 'pwsh-arm64.msi'
+    Get-VectisRelease '${windowsPowerShell.url}' '${windowsPowerShell.sha256}' $installer
+    $msiArguments = '/i "' + $installer + '" /qn /norestart ADD_PATH=1 USE_MU=0 ENABLE_MU=0 ENABLE_PSREMOTING=0 DISABLE_TELEMETRY=1'
+    $process = Start-Process -FilePath msiexec.exe -ArgumentList $msiArguments -Wait -PassThru
+    if ($process.ExitCode -notin @(0, 3010)) { throw "PowerShell MSI failed: $($process.ExitCode)" }
+    if ($process.ExitCode -eq 3010) { Write-Output 'vectis-provision: pwsh-reboot-required' }
+  }
+  Write-Output 'vectis-provision: pwsh-verify'
+  $pwshVersion = Get-VectisToolVersion $pwshExe $pwshArguments
+  if ($pwshVersion -ne '${windowsPowerShell.version}') { throw 'PowerShell 7 verification failed.' }
+} finally {
+  Remove-Item -LiteralPath $downloads -Recurse -Force
+}
+Write-Output 'vectis-provision: toolchain-path'
+$toolPaths = @((Join-Path $gitRoot 'bin'), (Join-Path $gitRoot 'cmd'), $zstdRoot, $pwshRoot, (Join-Path $gitRoot 'usr\bin'))
+$minGitPaths = @('C:\Program Files\MinGit\cmd', 'C:\Program Files\MinGit\bin')
+$machinePath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
+$remainingPath = @($machinePath -split ';' | Where-Object { $_.Trim().Trim('"').TrimEnd('\') -notin ($toolPaths + $minGitPaths) })
+[Environment]::SetEnvironmentVariable('Path', (($toolPaths + $remainingPath) -join ';'), 'Machine')
+$env:Path = [Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' + [Environment]::GetEnvironmentVariable('Path', 'User')
+$expectedTools = @{
+  'git.exe' = @($gitExe, (Join-Path $gitRoot 'bin\git.exe'))
+  'bash.exe' = @($bashExe)
+  'tar.exe' = @($tarExe)
+  'zstd.exe' = @($zstdExe)
+  'pwsh.exe' = @($pwshExe)
+}
+foreach ($tool in $expectedTools.Keys) {
+  $resolved = @(Get-Command $tool -CommandType Application -All)[0].Source
+  if ($resolved -notin $expectedTools[$tool]) { throw "Unexpected tool on PATH: $tool at $resolved" }
+}
+Write-Output 'vectis-provision: toolchain-manifest'
+$manifestPath = Join-Path $toolchainRoot 'toolchain.json'
+$manifest = [pscustomobject]@{}
+if (Test-Path -LiteralPath $manifestPath) { $manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json }
+$system = Get-ComputerInfo -Property WindowsProductName,WindowsVersion,OsBuildNumber
+$values = @{
+  WindowsProductName = $system.WindowsProductName
+  WindowsVersion = $system.WindowsVersion
+  OsBuildNumber = $system.OsBuildNumber
+  Git = $gitVersion
+  GnuTar = ($tarVersion -split "\r?\n")[0]
+  Zstd = $zstdVersion
+  ZstdArchitecture = 'x64-emulated'
+  PowerShell = $pwshVersion
+  Defender = [pscustomobject]@{ Mode = 'policy-exclusion'; PolicyExclusionPath = @('C:\'); AppliesAt = 'next-boot' }
+  Services = $serviceStates
+  NoAutoUpdate = (Get-ItemProperty -Path $updatePolicy).NoAutoUpdate
+  HVCI = $hvciState
+}
+foreach ($name in $values.Keys) { $manifest | Add-Member -NotePropertyName $name -NotePropertyValue $values[$name] -Force }
+$manifest.PSObject.Properties.Remove('BootVerification')
+$manifest | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $manifestPath -Encoding utf8
+Write-Output 'vectis-provision: remove-security-startup-task'
+if (Get-ScheduledTask -TaskName 'Vectis-VerifySecurity' -ErrorAction SilentlyContinue) {
+  Unregister-ScheduledTask -TaskName 'Vectis-VerifySecurity' -Confirm:$false
+}
+foreach ($file in @('verify-security.ps1', 'security-boot.json', 'security-boot.log')) {
+  $path = Join-Path $toolchainRoot $file
+  if (Test-Path -LiteralPath $path) { Remove-Item -LiteralPath $path -Force }
+}
+`;
+}
diff --git a/packages/scaleset/src/bootstrap.test.ts b/packages/scaleset/src/bootstrap.test.ts
new file mode 100644
index 00000000..1328fbe2
--- /dev/null
+++ b/packages/scaleset/src/bootstrap.test.ts
@@ -0,0 +1,200 @@
+import { expect, test, vi } from "vitest";
+import { bootstrapAdmin, tokenExpiration } from "./bootstrap.js";
+import { ScaleSetAdminClient, type Fetch } from "./client.js";
+
+const input = {
+  owner: "kerdofficial",
+  repo: "vectis-dev-sandbox",
+  installationToken: "installation-secret",
+};
+const jwt = (payload: unknown) =>
+  `header.${Buffer.from(JSON.stringify(payload)).toString("base64url")}.signature`;
+const serviceUrl = "https://actions.example.test/tenant/repository/";
+const name = "vectis-probe-test";
+const labels = [name, "self-hosted", "Linux", "ARM64", "vectis-scaleset-probe"];
+const set = {
+  id: 17,
+  name,
+  runnerGroupId: 42,
+  labels: labels.map((name) => ({ name, type: "System" })),
+};
+
+test("exchanges a repository registration token with RemoteAuth and retains only the admin connection", async () => {
+  const token = jwt({ exp: 2000000000 });
+  const fetch = vi
+    .fn<Fetch>()
+    .mockResolvedValueOnce(Response.json({ token: "registration-secret" }, { status: 201 }))
+    .mockResolvedValueOnce(Response.json({ url: serviceUrl, token }));
+  expect(await bootstrapAdmin(input, fetch)).toEqual({
+    serviceUrl,
+    adminToken: token,
+    adminTokenExp: 2000000000,
+  });
+  expect(
+    fetch.mock.calls.map(([url, init]) => [
+      url.href,
+      init.method,
+      new Headers(init.headers).get("Authorization"),
+    ]),
+  ).toEqual([
+    [
+      "https://api.github.com/repos/kerdofficial/vectis-dev-sandbox/actions/runners/registration-token",
+      "POST",
+      "Bearer installation-secret",
+    ],
+    [
+      "https://api.github.com/actions/runner-registration",
+      "POST",
+      "RemoteAuth registration-secret",
+    ],
+  ]);
+  expect(JSON.parse(String(fetch.mock.calls[1]?.[1].body))).toEqual({
+    url: "https://github.com/kerdofficial/vectis-dev-sandbox",
+    runner_event: "register",
+  });
+  for (const [, init] of fetch.mock.calls) {
+    expect(init.redirect).toBe("error");
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  }
+});
+
+test.each([401, 403, 422, 429, 500])(
+  "bootstrap status %i is observable without leaking credentials or bodies",
+  async (status) => {
+    const fetch = vi.fn<Fetch>(
+      async () => new Response("registration-secret installation-secret", { status }),
+    );
+    await expect(bootstrapAdmin(input, fetch)).rejects.toMatchObject({
+      stage: "registration-token",
+      status,
+    });
+    expect(fetch).toHaveBeenCalledTimes(1);
+  },
+);
+
+test("exchange errors identify their stage and are not retried", async () => {
+  const fetch = vi
+    .fn<Fetch>()
+    .mockResolvedValueOnce(Response.json({ token: "registration-secret" }, { status: 201 }))
+    .mockResolvedValueOnce(new Response("secret body", { status: 401 }));
+  await expect(bootstrapAdmin(input, fetch)).rejects.toThrow(
+    "Scale set bootstrap runner-registration failed (401).",
+  );
+  expect(fetch).toHaveBeenCalledTimes(2);
+});
+
+test.each([
+  { url: "http://actions.example.test", token: "secret" },
+  { url: "https://user:secret@actions.example.test", token: "secret" },
+  { url: "https://actions.example.test/?token=secret", token: "secret" },
+  { url: "https://actions.example.test/#secret", token: "secret" },
+  { token: "secret" },
+  { url: serviceUrl, token: "" },
+])("malformed bootstrap data is rejected with a redacted error", async (connection) => {
+  const fetch = vi
+    .fn<Fetch>()
+    .mockResolvedValueOnce(Response.json({ token: "registration-secret" }, { status: 201 }))
+    .mockResolvedValueOnce(Response.json(connection));
+  await expect(bootstrapAdmin(input, fetch)).rejects.toThrow(
+    "Invalid or unsupported scale set response.",
+  );
+});
+
+test("bootstrap bounds response bodies and sanitizes fetch errors", async () => {
+  await expect(
+    bootstrapAdmin(input, async () => new Response("x".repeat(1024 * 1024 + 1), { status: 201 })),
+  ).rejects.toThrow("Invalid or unsupported scale set response.");
+  await expect(
+    bootstrapAdmin(input, async () => {
+      throw new Error("installation-secret");
+    }),
+  ).rejects.toThrow("Invalid or unsupported scale set response.");
+});
+
+test("bootstrap cancellation stops the exchange and unsafe repository paths never reach fetch", async () => {
+  const fetch = vi.fn<Fetch>();
+  const stop = new AbortController();
+  stop.abort(new Error("stop bootstrap"));
+  await expect(bootstrapAdmin(input, fetch, stop.signal)).rejects.toThrow("stop bootstrap");
+  await expect(bootstrapAdmin({ ...input, repo: ".." }, fetch)).rejects.toThrow(
+    "Invalid repository name.",
+  );
+  expect(fetch).not.toHaveBeenCalled();
+});
+
+test("expiry observation reads exp without claiming to authenticate a JWT", () => {
+  expect(tokenExpiration(jwt({ exp: 2000000000, iat: 1999990000 }))).toBe(2000000000);
+  for (const token of ["opaque", "a.bad-json.b", jwt({}), jwt({ exp: "2000" }), jwt({ exp: -1 })])
+    expect(tokenExpiration(token)).toBeNull();
+});
+
+test("admin discovers the default group, finds or creates a set, reads effective labels, generates JIT, and deletes", async () => {
+  const fetch = vi
+    .fn<Fetch>()
+    .mockResolvedValueOnce(
+      Response.json({ count: 1, value: [{ id: 42, name: "Default", isDefaultGroup: true }] }),
+    )
+    .mockResolvedValueOnce(Response.json({ count: 0, value: [] }))
+    .mockResolvedValueOnce(Response.json(set))
+    .mockResolvedValueOnce(Response.json({ ...set, labels: set.labels.slice(0, 1) }))
+    .mockResolvedValueOnce(
+      Response.json({ runner: { id: 81, name: `${name}-runner` }, encodedJITConfig: "jit-secret" }),
+    )
+    .mockResolvedValueOnce(new Response(null, { status: 204 }));
+  const admin = new ScaleSetAdminClient(serviceUrl, "admin-secret", fetch);
+  expect((await admin.defaultRunnerGroup()).id).toBe(42);
+  expect(await admin.findScaleSet(42, name)).toBeNull();
+  expect(await admin.createScaleSet(42, name, labels)).toEqual(set);
+  expect((await admin.getScaleSet(17)).labels).toEqual(set.labels.slice(0, 1));
+  expect((await admin.generateJitConfig(17, `${name}-runner`)).encodedJITConfig).toBe("jit-secret");
+  await admin.deleteScaleSet(17);
+  expect(fetch.mock.calls.map(([url]) => url.pathname)).toEqual([
+    "/tenant/repository/_apis/runtime/runnergroups/",
+    "/tenant/repository/_apis/runtime/runnerscalesets",
+    "/tenant/repository/_apis/runtime/runnerscalesets",
+    "/tenant/repository/_apis/runtime/runnerscalesets/17",
+    "/tenant/repository/_apis/runtime/runnerscalesets/17/generatejitconfig",
+    "/tenant/repository/_apis/runtime/runnerscalesets/17",
+  ]);
+  expect(fetch.mock.calls[0]?.[0].searchParams.get("groupName")).toBe("default");
+  expect(fetch.mock.calls[1]?.[0].searchParams.get("runnerGroupId")).toBe("42");
+  expect(fetch.mock.calls[1]?.[0].searchParams.get("name")).toBe(name);
+  expect(JSON.parse(String(fetch.mock.calls[2]?.[1].body))).toEqual({
+    name,
+    runnerGroupId: 42,
+    labels: set.labels,
+    RunnerSetting: { disableUpdate: true },
+  });
+  expect(JSON.parse(String(fetch.mock.calls[4]?.[1].body))).toEqual({
+    name: `${name}-runner`,
+    workFolder: "_work",
+  });
+  for (const [url, init] of fetch.mock.calls) {
+    expect(url.searchParams.get("api-version")).toBe("6.0-preview");
+    expect(new Headers(init.headers).get("Authorization")).toBe("Bearer admin-secret");
+  }
+});
+
+test("admin lookup rejects ambiguous, inconsistent and mismatched identities", async () => {
+  for (const result of [
+    { count: 2, value: [set, set] },
+    { count: 0, value: [set] },
+    { count: 1, value: [{ ...set, name: "other" }] },
+  ]) {
+    const admin = new ScaleSetAdminClient(serviceUrl, "admin", async () => Response.json(result));
+    await expect(admin.findScaleSet(42, name)).rejects.toThrow(
+      "Invalid or unsupported scale set response.",
+    );
+  }
+  const admin = new ScaleSetAdminClient(serviceUrl, "admin", async () =>
+    Response.json({ ...set, id: 18 }),
+  );
+  await expect(admin.getScaleSet(17)).rejects.toThrow("Invalid or unsupported scale set response.");
+  await expect(
+    new ScaleSetAdminClient(
+      serviceUrl,
+      "admin",
+      async () => new Response(null, { status: 202 }),
+    ).getScaleSet(17),
+  ).rejects.toMatchObject({ status: 202 });
+});
diff --git a/packages/scaleset/src/bootstrap.ts b/packages/scaleset/src/bootstrap.ts
new file mode 100644
index 00000000..dfb35494
--- /dev/null
+++ b/packages/scaleset/src/bootstrap.ts
@@ -0,0 +1,102 @@
+import { Schema } from "effect";
+import { readJson, type Fetch } from "./client.js";
+import { ScaleSetProtocolError } from "./messages.js";
+
+const Token = Schema.Struct({ token: Schema.NonEmptyString });
+const Connection = Schema.Struct({ url: Schema.NonEmptyString, token: Schema.NonEmptyString });
+const Exp = Schema.Struct({ exp: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)) });
+
+export function tokenExpiration(token: string): number | null {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload) return null;
+    const value: unknown = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    return Schema.decodeUnknownSync(Exp)(value).exp;
+  } catch {
+    return null;
+  }
+}
+
+export class ScaleSetBootstrapHttpError extends Error {
+  constructor(
+    readonly stage: "registration-token" | "runner-registration",
+    readonly status: number,
+  ) {
+    super(`Scale set bootstrap ${stage} failed (${status}).`);
+    this.name = "ScaleSetBootstrapHttpError";
+  }
+}
+
+export async function bootstrapAdmin(
+  input: { owner: string; repo: string; installationToken: string },
+  fetch: Fetch,
+  signal?: AbortSignal,
+) {
+  if (
+    !/^[A-Za-z0-9-]+$/.test(input.owner) ||
+    !/^[A-Za-z0-9_.-]+$/.test(input.repo) ||
+    [".", ".."].includes(input.repo)
+  )
+    throw new Error("Invalid repository name.");
+  async function post(
+    path: string,
+    authorization: string,
+    stage: "registration-token" | "runner-registration",
+    body?: unknown,
+  ) {
+    const boundedSignal = AbortSignal.any([
+      AbortSignal.timeout(15000),
+      ...(signal ? [signal] : []),
+    ]);
+    boundedSignal.throwIfAborted();
+    const response = await fetch(new URL(`https://api.github.com${path}`), {
+      method: "POST",
+      redirect: "error",
+      signal: boundedSignal,
+      headers: {
+        Authorization: authorization,
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2026-03-10",
+        "User-Agent": "vectis-scaleset-probe/0.1",
+        "Content-Type": "application/json",
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const expected = stage === "registration-token" ? 201 : 200;
+    if (response.status !== expected) {
+      await response.body?.cancel();
+      throw new ScaleSetBootstrapHttpError(stage, response.status);
+    }
+    return readJson(response);
+  }
+  try {
+    const registration = Schema.decodeUnknownSync(Token)(
+      await post(
+        `/repos/${input.owner}/${input.repo}/actions/runners/registration-token`,
+        `Bearer ${input.installationToken}`,
+        "registration-token",
+      ),
+    );
+    const connection = Schema.decodeUnknownSync(Connection)(
+      await post(
+        "/actions/runner-registration",
+        `RemoteAuth ${registration.token}`,
+        "runner-registration",
+        { url: `https://github.com/${input.owner}/${input.repo}`, runner_event: "register" },
+      ),
+    );
+    const url = new URL(connection.url);
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash)
+      throw new ScaleSetProtocolError();
+    return {
+      serviceUrl: url.href,
+      adminToken: connection.token,
+      adminTokenExp: tokenExpiration(connection.token),
+    };
+  } catch (error) {
+    signal?.throwIfAborted();
+    if (error instanceof ScaleSetBootstrapHttpError || error instanceof ScaleSetProtocolError)
+      throw error;
+    throw new ScaleSetProtocolError();
+  }
+}
diff --git a/packages/scaleset/src/client.test.ts b/packages/scaleset/src/client.test.ts
new file mode 100644
index 00000000..eb10be14
--- /dev/null
+++ b/packages/scaleset/src/client.test.ts
@@ -0,0 +1,301 @@
+import { afterEach, expect, test, vi } from "vitest";
+import {
+  ScaleSetAdminClient,
+  ScaleSetHttpError,
+  ScaleSetProtocolError,
+  ScaleSetSessionClient,
+  decodeMessage,
+  type Fetch,
+  type Session,
+} from "./index.js";
+
+const serviceUrl = "https://actions.example.test/tenant/repository/";
+const session: Session = {
+  sessionId: "c6400b58-622b-497d-9c97-d706d852570a",
+  ownerName: "machine-7",
+  messageQueueUrl: "https://queue.example.test/messages?session=opaque",
+  messageQueueAccessToken: "queue-secret",
+  statistics: { totalAssignedJobs: 3 },
+};
+const available = { messageType: "JobAvailable", runnerRequestId: 501 };
+function envelope(jobs: unknown = [available]) {
+  return {
+    messageId: 9,
+    messageType: "RunnerScaleSetJobMessages",
+    body: JSON.stringify(jobs),
+    statistics: { totalAssignedJobs: 83, totalRunningJobs: 2 },
+  };
+}
+function host(fetch: Fetch, grant = session) {
+  return new ScaleSetSessionClient(serviceUrl, 17, grant, fetch);
+}
+afterEach(() => vi.useRealTimers());
+
+test("admin session lifecycle preserves the tenant path and never uses the queue token", async () => {
+  const fetch = vi.fn<Fetch>(async (_url, init) =>
+    init.method === "DELETE" ? new Response(null, { status: 204 }) : Response.json(session),
+  );
+  const cloud = new ScaleSetAdminClient(serviceUrl, "admin-secret", fetch);
+  expect(await cloud.createSession(17, "machine-7")).toEqual(session);
+  expect(await cloud.refreshSession(17, session.sessionId)).toEqual(session);
+  await cloud.deleteSession(17, session.sessionId);
+  expect(fetch.mock.calls.map(([url, init]) => [url.href, init.method])).toEqual([
+    [`${serviceUrl}_apis/runtime/runnerscalesets/17/sessions?api-version=6.0-preview`, "POST"],
+    [
+      `${serviceUrl}_apis/runtime/runnerscalesets/17/sessions/${session.sessionId}?api-version=6.0-preview`,
+      "PATCH",
+    ],
+    [
+      `${serviceUrl}_apis/runtime/runnerscalesets/17/sessions/${session.sessionId}?api-version=6.0-preview`,
+      "DELETE",
+    ],
+  ]);
+  expect(fetch.mock.calls[0]?.[1].body).toBe(JSON.stringify({ ownerName: "machine-7" }));
+  expect(fetch.mock.calls[1]?.[1].body).toBeUndefined();
+  for (const [, init] of fetch.mock.calls) {
+    expect(new Headers(init.headers).get("Authorization")).toBe("Bearer admin-secret");
+    expect(init.redirect).toBe("error");
+  }
+});
+
+test("host polls, acquires and acknowledges using only its queue credential", async () => {
+  const fetch = vi.fn<Fetch>(async (_url, init) => {
+    if (init.method === "GET") return Response.json(envelope());
+    if (init.method === "POST") return Response.json({ count: 1, value: [501] });
+    return new Response(null, { status: 204 });
+  });
+  const client = host(fetch);
+  const message = await client.getMessage(8, 4);
+  expect(message?.statistics.totalAssignedJobs).toBe(83);
+  expect(message?.jobs).toEqual([available]);
+  expect(fetch).toHaveBeenCalledTimes(1);
+  expect(await client.acquireJobs([501, 502])).toEqual([501]);
+  await client.acknowledgeMessage(9);
+  expect(fetch.mock.calls.map(([url]) => url.href)).toEqual([
+    "https://queue.example.test/messages?session=opaque&lastMessageId=8",
+    `${serviceUrl}_apis/runtime/runnerscalesets/17/acquirejobs?api-version=6.0-preview`,
+    "https://queue.example.test/messages/9?session=opaque",
+  ]);
+  const headers = new Headers(fetch.mock.calls[0]?.[1].headers);
+  expect(headers.get("X-ScaleSetMaxCapacity")).toBe("4");
+  expect(headers.get("Accept")).toBe("application/json; api-version=6.0-preview");
+  expect(fetch.mock.calls[1]?.[1].body).toBe("[501,502]");
+  for (const [, init] of fetch.mock.calls)
+    expect(new Headers(init.headers).get("Authorization")).toBe("Bearer queue-secret");
+});
+
+test("202 means no new observation, permits zero capacity, and does not acknowledge", async () => {
+  const fetch = vi.fn<Fetch>(async () => new Response(null, { status: 202 }));
+  expect(await host(fetch).getMessage(0, 0)).toBeNull();
+  expect(fetch.mock.calls[0]?.[0].searchParams.has("lastMessageId")).toBe(false);
+  expect(new Headers(fetch.mock.calls[0]?.[1].headers).get("X-ScaleSetMaxCapacity")).toBe("0");
+  expect(fetch).toHaveBeenCalledTimes(1);
+});
+
+test("an unacknowledged message may be delivered twice without hidden acknowledgments", async () => {
+  const fetch = vi.fn<Fetch>(async () => Response.json(envelope()));
+  const client = host(fetch);
+  expect(await client.getMessage(0, 1)).toEqual(await client.getMessage(0, 1));
+  expect(fetch.mock.calls.every(([, init]) => init.method === "GET")).toBe(true);
+});
+
+test("an expired queue token requires an explicit cloud refresh, then polling uses the new grant", async () => {
+  const fetch = vi.fn<Fetch>(async (_url, init) => {
+    if (init.method === "PATCH")
+      return Response.json({ ...session, messageQueueAccessToken: "renewed-secret" });
+    return new Headers(init.headers).get("Authorization") === "Bearer renewed-secret"
+      ? Response.json(envelope())
+      : new Response("not logged", { status: 401 });
+  });
+  await expect(host(fetch).getMessage(0, 1)).rejects.toMatchObject({
+    status: 401,
+    queueTokenExpired: true,
+  });
+  expect(fetch).toHaveBeenCalledTimes(1);
+  const cloud = new ScaleSetAdminClient(serviceUrl, "admin-secret", fetch);
+  const refreshed = await cloud.refreshSession(17, session.sessionId);
+  expect(await host(fetch, refreshed).getMessage(0, 1)).toMatchObject({ messageId: 9 });
+  expect(fetch).toHaveBeenCalledTimes(3);
+});
+
+test.each(["acquire", "ack"])(
+  "%s also reports an expired queue token without admin access",
+  async (method) => {
+    const fetch = vi.fn<Fetch>(async () => new Response(null, { status: 401 }));
+    const client = host(fetch);
+    await expect(
+      method === "acquire" ? client.acquireJobs([501]) : client.acknowledgeMessage(9),
+    ).rejects.toMatchObject({ queueTokenExpired: true });
+    expect(fetch).toHaveBeenCalledTimes(1);
+  },
+);
+
+test.each([403, 404, 409, 429, 500, 503])(
+  "HTTP %i stays observable and is never blindly retried",
+  async (status) => {
+    const fetch = vi.fn<Fetch>(
+      async () =>
+        new Response("sensitive upstream body", { status, headers: { "Retry-After": "15" } }),
+    );
+    const cloud = new ScaleSetAdminClient(serviceUrl, "admin-secret", fetch);
+    await expect(cloud.createSession(17, "machine-7")).rejects.toMatchObject({
+      status,
+      retryAfter: "15",
+      queueTokenExpired: false,
+    });
+    expect(fetch).toHaveBeenCalledTimes(1);
+  },
+);
+
+test("errors omit endpoint tokens and response bodies", async () => {
+  const error = new ScaleSetHttpError(401, null, true);
+  expect(String(error)).toBe("ScaleSetHttpError: Scale set request failed (401).");
+  const fetch: Fetch = async () => Response.json({ messageQueueAccessToken: "secret" });
+  await expect(
+    new ScaleSetAdminClient(serviceUrl, "admin", fetch).createSession(17, "host"),
+  ).rejects.toThrow("Invalid or unsupported scale set response.");
+});
+
+test("caller cancellation aborts an outstanding long poll", async () => {
+  const fetch = vi.fn<Fetch>(async (_url, init) => {
+    const signal = init.signal;
+    if (!signal) throw new Error("Expected signal");
+    return new Promise<Response>((_resolve, reject) => {
+      signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+    });
+  });
+  const abort = new AbortController();
+  const result = host(fetch).getMessage(0, 1, abort.signal);
+  const assertion = expect(result).rejects.toThrow("stop poll");
+  abort.abort(new Error("stop poll"));
+  await assertion;
+  expect(fetch.mock.calls[0]?.[1].signal?.aborted).toBe(true);
+});
+
+test("an already aborted call sends no HTTP request", async () => {
+  const fetch = vi.fn<Fetch>();
+  const abort = new AbortController();
+  abort.abort(new Error("already stopped"));
+  await expect(host(fetch).getMessage(0, 1, abort.signal)).rejects.toThrow("already stopped");
+  expect(fetch).not.toHaveBeenCalled();
+});
+
+test("the poll has a finite deadline even without caller cancellation", async () => {
+  vi.useFakeTimers();
+  const fetch: Fetch = async (_url, init) =>
+    new Promise<Response>((_resolve, reject) => {
+      init.signal?.addEventListener("abort", () => reject(init.signal?.reason), { once: true });
+    });
+  const assertion = expect(host(fetch).getMessage(0, 1)).rejects.toMatchObject({
+    name: "TimeoutError",
+  });
+  await vi.advanceTimersByTimeAsync(70000);
+  await assertion;
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+test("completed and failed requests release their deadline timers", async () => {
+  vi.useFakeTimers();
+  const fetch: Fetch = async () => new Response(null, { status: 202 });
+  await host(fetch).getMessage(0, 1);
+  expect(vi.getTimerCount()).toBe(0);
+  const failure: Fetch = async () => new Response(null, { status: 503 });
+  await expect(host(failure).getMessage(0, 1)).rejects.toMatchObject({ status: 503 });
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+test("cancellation while reading a response remains cancellation", async () => {
+  const abort = new AbortController();
+  const fetch: Fetch = async (_url, init) =>
+    new Response(
+      new ReadableStream<Uint8Array>({
+        start(controller) {
+          init.signal?.addEventListener("abort", () => controller.error(init.signal?.reason), {
+            once: true,
+          });
+        },
+      }),
+    );
+  const result = host(fetch).getMessage(0, 1, abort.signal);
+  const assertion = expect(result).rejects.toThrow("stop body");
+  await Promise.resolve();
+  abort.abort(new Error("stop body"));
+  await assertion;
+});
+
+test("transport failure does not silently repeat an acquire with uncertain outcome", async () => {
+  const fetch = vi.fn<Fetch>(async () => {
+    throw new TypeError("connection lost");
+  });
+  await expect(host(fetch).acquireJobs([501])).rejects.toThrow("connection lost");
+  expect(fetch).toHaveBeenCalledTimes(1);
+});
+
+test("acquire accepts a partial or empty confirmed subset, including repeated calls", async () => {
+  const fetch = vi
+    .fn<Fetch>()
+    .mockResolvedValueOnce(Response.json({ count: 1, value: [501] }))
+    .mockResolvedValueOnce(Response.json({ count: 0, value: [] }));
+  const client = host(fetch);
+  expect(await client.acquireJobs([501, 502])).toEqual([501]);
+  expect(await client.acquireJobs([501, 502])).toEqual([]);
+});
+
+test.each([
+  { count: 1, value: [999] },
+  { count: 0, value: [501] },
+  { count: 2, value: [501, 501] },
+  { count: 1, value: [Number.MAX_SAFE_INTEGER + 1] },
+])("acquire rejects inconsistent confirmations: %j", async (response) => {
+  const fetch: Fetch = async () => Response.json(response);
+  await expect(host(fetch).acquireJobs([501])).rejects.toBeInstanceOf(ScaleSetProtocolError);
+});
+
+test("all four job messages decode without treating request IDs as REST job IDs", () => {
+  const jobs = [
+    available,
+    { messageType: "JobAssigned", runnerRequestId: 502, jobId: "opaque-job-id" },
+    { messageType: "JobStarted", runnerRequestId: 501, runnerId: 81, runnerName: "vm-81" },
+    { messageType: "JobCompleted", runnerRequestId: 502, result: "canceled", runnerId: 0 },
+  ];
+  expect(decodeMessage(envelope(jobs)).jobs).toEqual(jobs);
+  expect(decodeMessage({ ...envelope(), messageId: 0, body: "" }).jobs).toEqual([]);
+});
+
+test.each([
+  { ...envelope(), messageType: "UnknownEnvelope" },
+  { ...envelope(), body: "not json" },
+  { ...envelope(), statistics: null },
+  { ...envelope(), statistics: { totalAssignedJobs: -1 } },
+  { ...envelope(), statistics: { totalAssignedJobs: Number.MAX_SAFE_INTEGER + 1 } },
+  envelope([{ messageType: "JobStarted", runnerRequestId: 501 }]),
+  envelope(Array.from({ length: 51 }, () => available)),
+])("malformed or unsupported data is never acknowledged: %j", async (response) => {
+  const fetch = vi.fn<Fetch>(async () => Response.json(response));
+  await expect(host(fetch).getMessage(0, 1)).rejects.toBeInstanceOf(ScaleSetProtocolError);
+  expect(fetch).toHaveBeenCalledTimes(1);
+});
+
+test("response retention is bounded and malformed JSON fails decoding", async () => {
+  for (const body of ["{", "x".repeat(1024 * 1024 + 1)]) {
+    const fetch: Fetch = async () => new Response(body);
+    await expect(host(fetch).getMessage(0, 1)).rejects.toBeInstanceOf(ScaleSetProtocolError);
+  }
+});
+
+test("unsafe endpoint URLs, IDs and capacities fail before HTTP", async () => {
+  const fetch = vi.fn<Fetch>();
+  for (const url of [
+    "http://queue.example.test",
+    "https://user:secret@queue.example.test",
+    "https://queue.example.test/#fragment",
+  ]) {
+    expect(() => host(fetch, { ...session, messageQueueUrl: url })).toThrow();
+  }
+  const cloud = new ScaleSetAdminClient(serviceUrl, "admin", fetch);
+  await expect(cloud.refreshSession(17, "..")).rejects.toThrow();
+  await expect(cloud.createSession(0, "host")).rejects.toThrow();
+  await expect(host(fetch).getMessage(0, -1)).rejects.toThrow();
+  await expect(host(fetch).acquireJobs([Number.MAX_SAFE_INTEGER + 1])).rejects.toThrow();
+  expect(fetch).not.toHaveBeenCalled();
+});
diff --git a/packages/scaleset/src/client.ts b/packages/scaleset/src/client.ts
new file mode 100644
index 00000000..11d631fa
--- /dev/null
+++ b/packages/scaleset/src/client.ts
@@ -0,0 +1,421 @@
+import { Schema } from "effect";
+import {
+  Count,
+  Identifier,
+  ScaleSetProtocolError,
+  Session,
+  SessionId,
+  decodeMessage,
+} from "./messages.js";
+
+export type Fetch = (url: URL, init: RequestInit) => Promise<Response>;
+
+const endpoint = "_apis/runtime/runnerscalesets";
+const version = "6.0-preview";
+const maxResponseBytes = 1024 * 1024;
+const Acquired = Schema.Struct({ count: Count, value: Schema.Array(Identifier) });
+const Label = Schema.Struct({
+  name: Schema.NonEmptyString,
+  type: Schema.optionalKey(Schema.String),
+});
+const ScaleSet = Schema.Struct({
+  id: Identifier,
+  name: Schema.NonEmptyString,
+  runnerGroupId: Identifier,
+  labels: Schema.Array(Label),
+});
+const ScaleSets = Schema.Struct({ count: Count, value: Schema.Array(ScaleSet) });
+const Groups = Schema.Struct({
+  count: Count,
+  value: Schema.Array(
+    Schema.Struct({
+      id: Identifier,
+      name: Schema.NonEmptyString,
+      isDefaultGroup: Schema.Boolean,
+    }),
+  ),
+});
+const Jit = Schema.Struct({
+  runner: Schema.Struct({ id: Identifier, name: Schema.NonEmptyString }),
+  encodedJITConfig: Schema.NonEmptyString,
+});
+
+function decode<S extends Schema.ConstraintDecoder<unknown, never>>(
+  schema: S,
+  value: unknown,
+): S["Type"] {
+  try {
+    return Schema.decodeUnknownSync(schema)(value);
+  } catch {
+    throw new ScaleSetProtocolError();
+  }
+}
+
+export class ScaleSetHttpError extends Error {
+  readonly queueTokenExpired;
+  constructor(
+    readonly status: number,
+    readonly retryAfter: string | null,
+    queueRequest: boolean,
+  ) {
+    super(`Scale set request failed (${status}).`);
+    this.name = "ScaleSetHttpError";
+    this.queueTokenExpired = queueRequest && status === 401;
+  }
+}
+
+function secureUrl(value: string) {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.username || url.password || url.hash)
+    throw new Error(
+      "Scale set endpoints must use HTTPS without embedded credentials or fragments.",
+    );
+  return url;
+}
+
+function serviceUrl(base: string, path: string, resource = endpoint) {
+  const url = secureUrl(base);
+  if (url.search) throw new Error("Actions service URL must not contain a query.");
+  url.pathname = `${url.pathname.replace(/\/$/, "")}/${resource}${path ? `/${path}` : ""}`;
+  url.searchParams.set("api-version", version);
+  return url;
+}
+
+export async function readJson(response: Response): Promise<unknown> {
+  const reader = response.body?.getReader();
+  if (!reader) throw new ScaleSetProtocolError();
+  try {
+    const decoder = new TextDecoder();
+    let bytes = 0;
+    let text = "";
+    for (;;) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      if (bytes > maxResponseBytes) throw new ScaleSetProtocolError();
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+    return JSON.parse(text + decoder.decode());
+  } catch {
+    throw new ScaleSetProtocolError();
+  } finally {
+    try {
+      await reader.cancel();
+    } finally {
+      reader.releaseLock();
+    }
+  }
+}
+
+async function request(
+  fetch: Fetch,
+  url: URL,
+  token: string,
+  method: string,
+  expected: number,
+  signal: AbortSignal | undefined,
+  queueRequest: boolean,
+  body?: unknown,
+  extraHeaders?: Record<string, string>,
+) {
+  signal?.throwIfAborted();
+  const timeout = new AbortController();
+  const timer = setTimeout(
+    () => timeout.abort(new DOMException("Scale set request timed out.", "TimeoutError")),
+    70000,
+  );
+  const boundedSignal = AbortSignal.any([timeout.signal, ...(signal ? [signal] : [])]);
+  try {
+    const response = await fetch(url, {
+      method,
+      redirect: "error",
+      signal: boundedSignal,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+        "User-Agent": "vectis-scaleset-spike/0.1",
+        ...extraHeaders,
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    if (
+      response.status !== expected &&
+      !(queueRequest && method === "GET" && response.status === 202)
+    ) {
+      await response.body?.cancel();
+      throw new ScaleSetHttpError(
+        response.status,
+        response.headers.get("Retry-After"),
+        queueRequest,
+      );
+    }
+    if (response.status === 202 || response.status === 204) {
+      await response.body?.cancel();
+      return undefined;
+    }
+    return await readJson(response);
+  } catch (error) {
+    boundedSignal.throwIfAborted();
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function decodeSession(input: unknown) {
+  try {
+    const session = Schema.decodeUnknownSync(Session)(input);
+    secureUrl(session.messageQueueUrl);
+    return session;
+  } catch {
+    throw new ScaleSetProtocolError();
+  }
+}
+
+export class ScaleSetAdminClient {
+  constructor(
+    private readonly serviceBaseUrl: string,
+    private readonly adminToken: string,
+    private readonly fetch: Fetch,
+  ) {}
+
+  async defaultRunnerGroup(signal?: AbortSignal) {
+    const url = serviceUrl(this.serviceBaseUrl, "", "_apis/runtime/runnergroups/");
+    url.searchParams.set("groupName", "default");
+    const groups = decode(
+      Groups,
+      await request(this.fetch, url, this.adminToken, "GET", 200, signal, false),
+    );
+    const group = groups.value[0];
+    if (groups.count !== 1 || groups.value.length !== 1 || !group?.isDefaultGroup)
+      throw new ScaleSetProtocolError();
+    return group;
+  }
+
+  async findScaleSet(runnerGroupId: number, name: string, signal?: AbortSignal) {
+    decode(Identifier, runnerGroupId);
+    decode(Schema.NonEmptyString, name);
+    const url = serviceUrl(this.serviceBaseUrl, "");
+    url.searchParams.set("runnerGroupId", String(runnerGroupId));
+    url.searchParams.set("name", name);
+    const sets = decode(
+      ScaleSets,
+      await request(this.fetch, url, this.adminToken, "GET", 200, signal, false),
+    );
+    if (sets.count !== sets.value.length || sets.count > 1) throw new ScaleSetProtocolError();
+    const set = sets.value[0];
+    if (set && (set.name !== name || set.runnerGroupId !== runnerGroupId))
+      throw new ScaleSetProtocolError();
+    return set ?? null;
+  }
+
+  async getScaleSet(scaleSetId: number, signal?: AbortSignal) {
+    decode(Identifier, scaleSetId);
+    const set = decode(
+      ScaleSet,
+      await request(
+        this.fetch,
+        serviceUrl(this.serviceBaseUrl, String(scaleSetId)),
+        this.adminToken,
+        "GET",
+        200,
+        signal,
+        false,
+      ),
+    );
+    if (set.id !== scaleSetId) throw new ScaleSetProtocolError();
+    return set;
+  }
+
+  async createScaleSet(
+    runnerGroupId: number,
+    name: string,
+    labels: readonly string[],
+    signal?: AbortSignal,
+  ) {
+    decode(Identifier, runnerGroupId);
+    decode(Schema.NonEmptyString, name);
+    decode(Schema.Array(Schema.NonEmptyString), labels);
+    const set = decode(
+      ScaleSet,
+      await request(
+        this.fetch,
+        serviceUrl(this.serviceBaseUrl, ""),
+        this.adminToken,
+        "POST",
+        200,
+        signal,
+        false,
+        {
+          name,
+          runnerGroupId,
+          labels: labels.map((name) => ({ name, type: "System" })),
+          RunnerSetting: { disableUpdate: true },
+        },
+      ),
+    );
+    if (set.name !== name || set.runnerGroupId !== runnerGroupId) throw new ScaleSetProtocolError();
+    return set;
+  }
+
+  async deleteScaleSet(scaleSetId: number, signal?: AbortSignal) {
+    decode(Identifier, scaleSetId);
+    await request(
+      this.fetch,
+      serviceUrl(this.serviceBaseUrl, String(scaleSetId)),
+      this.adminToken,
+      "DELETE",
+      204,
+      signal,
+      false,
+    );
+  }
+
+  async generateJitConfig(scaleSetId: number, runnerName: string, signal?: AbortSignal) {
+    decode(Identifier, scaleSetId);
+    decode(Schema.NonEmptyString, runnerName);
+    const jit = decode(
+      Jit,
+      await request(
+        this.fetch,
+        serviceUrl(this.serviceBaseUrl, `${scaleSetId}/generatejitconfig`),
+        this.adminToken,
+        "POST",
+        200,
+        signal,
+        false,
+        { name: runnerName, workFolder: "_work" },
+      ),
+    );
+    if (jit.runner.name !== runnerName) throw new ScaleSetProtocolError();
+    return jit;
+  }
+
+  async createSession(scaleSetId: number, ownerName: string, signal?: AbortSignal) {
+    Schema.decodeUnknownSync(Identifier)(scaleSetId);
+    Schema.decodeUnknownSync(Schema.NonEmptyString)(ownerName);
+    return decodeSession(
+      await request(
+        this.fetch,
+        serviceUrl(this.serviceBaseUrl, `${scaleSetId}/sessions`),
+        this.adminToken,
+        "POST",
+        200,
+        signal,
+        false,
+        { ownerName },
+      ),
+    );
+  }
+
+  async refreshSession(scaleSetId: number, sessionId: string, signal?: AbortSignal) {
+    return decodeSession(
+      await request(
+        this.fetch,
+        this.sessionUrl(scaleSetId, sessionId),
+        this.adminToken,
+        "PATCH",
+        200,
+        signal,
+        false,
+      ),
+    );
+  }
+
+  async deleteSession(scaleSetId: number, sessionId: string, signal?: AbortSignal) {
+    await request(
+      this.fetch,
+      this.sessionUrl(scaleSetId, sessionId),
+      this.adminToken,
+      "DELETE",
+      204,
+      signal,
+      false,
+    );
+  }
+
+  private sessionUrl(scaleSetId: number, sessionId: string) {
+    Schema.decodeUnknownSync(Identifier)(scaleSetId);
+    Schema.decodeUnknownSync(SessionId)(sessionId);
+    return serviceUrl(
+      this.serviceBaseUrl,
+      `${scaleSetId}/sessions/${encodeURIComponent(sessionId)}`,
+    );
+  }
+}
+
+export class ScaleSetSessionClient {
+  private readonly session: Session;
+  constructor(
+    private readonly serviceBaseUrl: string,
+    private readonly scaleSetId: number,
+    session: Session,
+    private readonly fetch: Fetch,
+  ) {
+    Schema.decodeUnknownSync(Identifier)(scaleSetId);
+    this.session = decodeSession(session);
+  }
+
+  async getMessage(lastMessageId: number, maxCapacity: number, signal?: AbortSignal) {
+    Schema.decodeUnknownSync(Count)(lastMessageId);
+    Schema.decodeUnknownSync(Count)(maxCapacity);
+    const url = secureUrl(this.session.messageQueueUrl);
+    if (lastMessageId > 0) url.searchParams.set("lastMessageId", String(lastMessageId));
+    const result = await request(
+      this.fetch,
+      url,
+      this.session.messageQueueAccessToken,
+      "GET",
+      200,
+      signal,
+      true,
+      undefined,
+      {
+        Accept: `application/json; api-version=${version}`,
+        "X-ScaleSetMaxCapacity": String(maxCapacity),
+      },
+    );
+    return result === undefined ? null : decodeMessage(result);
+  }
+
+  async acknowledgeMessage(messageId: number, signal?: AbortSignal) {
+    Schema.decodeUnknownSync(Count)(messageId);
+    const url = secureUrl(this.session.messageQueueUrl);
+    url.pathname = `${url.pathname.replace(/\/$/, "")}/${messageId}`;
+    await request(
+      this.fetch,
+      url,
+      this.session.messageQueueAccessToken,
+      "DELETE",
+      204,
+      signal,
+      true,
+    );
+  }
+
+  async acquireJobs(requestIds: readonly number[], signal?: AbortSignal) {
+    Schema.decodeUnknownSync(Schema.Array(Identifier))(requestIds);
+    const result = await request(
+      this.fetch,
+      serviceUrl(this.serviceBaseUrl, `${this.scaleSetId}/acquirejobs`),
+      this.session.messageQueueAccessToken,
+      "POST",
+      200,
+      signal,
+      true,
+      requestIds,
+    );
+    try {
+      const acquired = Schema.decodeUnknownSync(Acquired)(result);
+      if (
+        acquired.count !== acquired.value.length ||
+        new Set(acquired.value).size !== acquired.value.length ||
+        acquired.value.some((id) => !requestIds.includes(id))
+      )
+        throw new ScaleSetProtocolError();
+      return acquired.value;
+    } catch {
+      throw new ScaleSetProtocolError();
+    }
+  }
+}
diff --git a/packages/scaleset/src/index.ts b/packages/scaleset/src/index.ts
new file mode 100644
index 00000000..cbab88b8
--- /dev/null
+++ b/packages/scaleset/src/index.ts
@@ -0,0 +1,10 @@
+export { ScaleSetAdminClient, ScaleSetSessionClient, ScaleSetHttpError } from "./client.js";
+export type { Fetch } from "./client.js";
+export {
+  Session,
+  Statistics,
+  JobMessage,
+  ScaleSetProtocolError,
+  decodeMessage,
+} from "./messages.js";
+export type { Message } from "./messages.js";
diff --git a/packages/scaleset/src/messages.ts b/packages/scaleset/src/messages.ts
new file mode 100644
index 00000000..a7eb4bb6
--- /dev/null
+++ b/packages/scaleset/src/messages.ts
@@ -0,0 +1,153 @@
+import { Option, Schema, SchemaIssue, SchemaTransformation } from "effect";
+
+export const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+export const Identifier = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export const SessionId = Schema.String.check(Schema.isUUID());
+
+export const Statistics = Schema.Struct({
+  totalAssignedJobs: Count,
+  totalAvailableJobs: Schema.optionalKey(Count),
+  totalAcquiredJobs: Schema.optionalKey(Count),
+  totalRunningJobs: Schema.optionalKey(Count),
+  totalRegisteredRunners: Schema.optionalKey(Count),
+  totalBusyRunners: Schema.optionalKey(Count),
+  totalIdleRunners: Schema.optionalKey(Count),
+});
+export type Statistics = typeof Statistics.Type;
+
+export const Session = Schema.Struct({
+  sessionId: SessionId,
+  ownerName: Schema.optionalKey(Schema.String),
+  messageQueueUrl: Schema.NonEmptyString,
+  messageQueueAccessToken: Schema.NonEmptyString,
+  statistics: Statistics,
+});
+export type Session = typeof Session.Type;
+
+const RequestId = Schema.optionalKey(Count).pipe(
+  Schema.decodeTo(
+    Schema.optionalKey(Identifier),
+    SchemaTransformation.transformOptional({
+      decode: Option.filter((id) => id !== 0),
+      encode: (id) => id,
+    }),
+  ),
+);
+const Timestamp = Schema.optionalKey(Schema.String).pipe(
+  Schema.decodeTo(
+    Schema.optionalKey(Schema.String),
+    SchemaTransformation.transformOptional({
+      decode: Option.filter((value) => !/^0001-01-01T00:00:00(?:\.0+)?Z$/.test(value)),
+      encode: (value) => value,
+    }),
+  ),
+);
+const job = {
+  runnerRequestId: RequestId,
+  repositoryName: Schema.optionalKey(Schema.String),
+  ownerName: Schema.optionalKey(Schema.String),
+  jobId: Schema.optionalKey(Schema.String),
+  jobWorkflowRef: Schema.optionalKey(Schema.String),
+  jobDisplayName: Schema.optionalKey(Schema.String),
+  workflowRunId: Schema.optionalKey(Identifier),
+  eventName: Schema.optionalKey(Schema.String),
+  requestLabels: Schema.optionalKey(Schema.Array(Schema.String)),
+  queueTime: Timestamp,
+  scaleSetAssignTime: Timestamp,
+  runnerAssignTime: Timestamp,
+  finishTime: Timestamp,
+};
+
+const KnownJobMessage = Schema.Union([
+  Schema.Struct({
+    ...job,
+    messageType: Schema.Literal("JobAvailable"),
+    acquireJobUrl: Schema.optionalKey(Schema.String),
+  }),
+  Schema.Struct({ ...job, messageType: Schema.Literal("JobAssigned") }),
+  Schema.Struct({
+    ...job,
+    messageType: Schema.Literal("JobStarted"),
+    runnerId: Identifier,
+    runnerName: Schema.NonEmptyString,
+  }),
+  Schema.Struct({
+    ...job,
+    messageType: Schema.Literal("JobCompleted"),
+    runnerId: Schema.optionalKey(Count),
+    runnerName: Schema.optionalKey(Schema.String),
+    result: Schema.NonEmptyString,
+  }),
+]);
+const UnknownJobMessage = Schema.Struct({
+  messageType: Schema.Literal("unknown"),
+  originalMessageType: Schema.String,
+});
+export const JobMessage = Schema.Union([KnownJobMessage, UnknownJobMessage]);
+export type JobMessage = typeof JobMessage.Type;
+const knownMessageTypes = new Set(["JobAvailable", "JobAssigned", "JobStarted", "JobCompleted"]);
+const MessageType = Schema.Struct({ messageType: Schema.String });
+
+const Envelope = Schema.Struct({
+  messageId: Count,
+  messageType: Schema.Literal("RunnerScaleSetJobMessages"),
+  body: Schema.String,
+  statistics: Statistics,
+});
+const Batch = Schema.Array(Schema.Unknown).check(Schema.isMaxLength(50));
+
+const formatIssue = SchemaIssue.makeFormatterStandardSchemaV1({
+  // Never include rejected values or upstream error text in credential-safe diagnostics.
+  leafHook: (issue) =>
+    issue._tag === "MissingKey" ? "Missing required field." : "Invalid field type or value.",
+  checkHook: () => "Value does not satisfy the field constraints.",
+});
+
+export class ScaleSetProtocolError extends Error {
+  constructor(
+    readonly issues: ReadonlyArray<{ path: string; message: string }> = [
+      { path: "$", message: "Invalid or unsupported scale set response." },
+    ],
+  ) {
+    super("Invalid or unsupported scale set response.");
+    this.name = "ScaleSetProtocolError";
+  }
+}
+
+function decode<S extends Schema.ConstraintDecoder<unknown, never>>(
+  schema: S,
+  input: unknown,
+  path = "$",
+): S["Type"] {
+  try {
+    return Schema.decodeUnknownSync(schema)(input);
+  } catch (error) {
+    if (Schema.isSchemaError(error))
+      throw new ScaleSetProtocolError(
+        formatIssue(error.issue).issues.map((issue) => ({
+          path: `${path}${(issue.path ?? []).map((key) => (typeof key === "number" ? `[${key}]` : `.${String(key)}`)).join("")}`,
+          message: issue.message,
+        })),
+      );
+    throw new ScaleSetProtocolError();
+  }
+}
+
+export function decodeMessage(input: unknown) {
+  const envelope = decode(Envelope, input);
+  let body: unknown;
+  try {
+    body = envelope.body === "" ? [] : JSON.parse(envelope.body);
+  } catch {
+    throw new ScaleSetProtocolError([{ path: "$.body", message: "Invalid JSON message batch." }]);
+  }
+  const jobs = decode(Batch, body, "$.body").map((input, index): JobMessage => {
+    const path = `$.body[${index}]`;
+    const { messageType } = decode(MessageType, input, path);
+    return knownMessageTypes.has(messageType)
+      ? decode(KnownJobMessage, input, path)
+      : { messageType: "unknown", originalMessageType: messageType };
+  });
+  return { messageId: envelope.messageId, statistics: envelope.statistics, jobs };
+}
+export type Message = ReturnType<typeof decodeMessage>;
diff --git a/skills/vectis/SKILL.md b/skills/vectis/SKILL.md
index 255f75f8..d66a47dd 100644
--- a/skills/vectis/SKILL.md
+++ b/skills/vectis/SKILL.md
@@ -34,6 +34,7 @@ Every change is an operation: `accepted`, `running`, `action_required`, `succeed
 - Commands with `activity: "setting"` in capabilities always wait in the CLI, including pause/resume, repository enable-auto/disable-auto, environment register/configure/remove, instance stop/reconcile, operation cancel and activity cancel. A timeout returns a `wait_cancelled` error with exit code 3; the operation may still be running. MCP command submission is unchanged.
 - An activity is what someone asked for; its operations are the steps that carried it out. `vectis activity list --json` (MCP `vectis_activities`, filters `--kind vectis|github`, `--status`, `--repository`, `--limit`) lists them newest first, and `vectis activity get <id> --json` (MCP `vectis_activity`) returns one with its operations. They also ride in `vectis status --json` as `activities`, and they never change operation IDs or request keys. Use `vectis activity cancel <activity-id>` or MCP `vectis_command` with `activity.cancel` to cancel its owned tasks or close a wait. Preparations with an owned setup must be resumed or discarded, and interrupted runners must be reconciled. Inspect the final status after requesting cancellation.
 - Completed activity history expires after 30 days, or beyond the newest 300 completions once older than 24 hours. Recent, unfinished and actively owned work stays; unlinked terminal maintenance expires after 24 hours. A pruned request key returns `operation_expired` and must not be replayed as new work. An older service may omit `activities` (treat as empty) and `revision` (change state is unknown).
+- Status windows include all unfinished operations and activities (including `action_required`) plus the newest 100 terminal records of each kind, and all non-stopped instances plus the newest 20 stopped ones. Absence from status does not mean a record was deleted. Operation/activity detail reads and operation waits query individual records, including older retained IDs, locally and remotely. Activity lists read summaries directly. Stopped instance records older than 24 hours are pruned beyond the newest 20, using stop time when available and creation time for legacy records; non-stopped records and request-key receipts are preserved.
 - The same command closes an `action_required` operation that nothing is working on any more, after you reported it to the user. An interrupted runner and an image preparation refuse it: they have their own recovery commands.
 - Output is always JSON. Exit codes: 0 success, 1 failed or cancelled, 3 action required or still pending. Errors look like `{"error":{"code","message","nextStep"}}`; follow `nextStep`.
 - Displayed logs, stored operation details and retained runner and preparation diagnostics redact recognized credentials.
@@ -41,10 +42,10 @@ Every change is an operation: `accepted`, `running`, `action_required`, `succeed
 
 ## Service
 
-- `vectis status --json` shows the machine, environments, VMs, recent operations, cloud connection and service version. MCP: `vectis_status`.
+- `vectis status --json` shows the bounded machine snapshot, environments, VMs, operations, activities, cloud connection and service version. MCP `vectis_status` returns a compact summary with runner capacity, non-stopped instances, counts within that window and the newest 20 slim operations/activities, without full results. Use `vectis_activities`, `vectis_activity` and `vectis_operation` for details. MCP returns tool data once in `structuredContent` with an empty `content` array.
 - Status includes a `revision` for detecting changes and cached `repositories` when paired. Repository and job updates change the revision; job data stays available through `job list`.
 - `vectis service install|start|stop [--if-idle]|status|uninstall`. MCP: `vectis_service`. `--if-idle` refuses to interrupt VMs or operations.
-- `vectis machine configure --max-runners N` sets the concurrent runner limit (1-16, default 5); status includes `runnerCapacity` with max, active and available slots.
+- `vectis machine configure [--max-runners N] [--memory-budget-mib N]` sets the concurrent runner limit (1-16, default 5) and shared VM memory admission budget independently or together. The budget accepts 2048 MiB to host RAM and defaults to 75% of host RAM when unset. Status includes `runnerCapacity` with max, active, available, per-environment slots and `budget: { memoryBudgetMiB, memoryCommittedMiB, hostMemoryMiB, pressure, pressureKnown }`.
 - `vectis pause` stops new VMs; running work continues. `vectis resume` allows them again.
 - `cloud.state` in `status` is `unconfigured`, `connecting`, `connected`, `unavailable` or `removed`. `removed` means the account deleted this Mac: report it, and only disconnect when the user asks.
 - The default home is `~/.vectis` (`~/.vectis-dev` for development builds). Pass `--home` only to work with an isolated state directory.
@@ -62,11 +63,23 @@ Remote control of another Mac: `vectis login`, user approval, `vectis login fini
 An environment is a prepared guest image. Its ID becomes the runner label.
 
 - Ubuntu 24.04: `vectis environment prepare-linux <id> --image-directory <dir> --storage-path <dir> --wait --json`. Needs about 8 GiB free. Resume an interrupted preparation with `environment resume <setup-id>`. Images with a shared SSH host key need fresh preparation; current images provision a separate key for each instance.
+- Linux preparation downloads and extracts the runner in the `vectis` login environment, runs its dependency installer as root, and leaves the runner directory owned by `vectis`. Script failures emit a serial marker with the failing step and exit status, stop the guest and report `action_required` with `guest_preparation_failed`. Failures and the one-hour timeout retain up to 4 KiB of redacted serial output in operation `diagnostics`; timeouts use `preparation_timeout`. Inspect with `operation get --json` and the private `preparation.log` before resuming.
 - macOS 26: `environment install-macos <id> --image-directory <dir> --storage-path <dir>` downloads Apple's large restore image unless `--restore-path` points at a local one, and needs 40 to 60 GiB. It stops at `action_required`: the user completes Setup Assistant in `environment open-macos-setup`, then `connect-macos-guest`, `verify-macos-guest`, shuts the guest down and `finish-macos-setup`. `discard-macos` deletes an unregistered attempt only with the user's confirmation.
 - Windows 11 (experimental): `environment install-windows` needs the user's own ISO, VirtIO drivers ISO, ARM64 UEFI firmware and license acceptance, plus QEMU with both Vectis TPM and network isolation patches, qemu-img and swtpm that the user installs. Guests default to IPv4 internet-only access and cannot initiate connections to host or private network services unless explicitly configured with open egress.
 - Windows 11 (experimental): `environment install-windows` needs the user's own ISO, VirtIO drivers ISO, ARM64 UEFI firmware and license acceptance, plus QEMU with both Vectis TPM and network isolation patches, qemu-img and swtpm that the user installs. Guests have IPv4 internet access but cannot initiate connections to host or private network services.
 - Windows 11 (experimental): `environment install-windows` needs the user's own ISO, VirtIO drivers ISO, ARM64 UEFI firmware and license acceptance, plus QEMU, qemu-img and swtpm that the user installs.
 - Interrupted Windows setup preserves its disk and setup identity. Inspect the private `setup.ppm`, host `preparation.log` and `bootstrap-diagnostic.json` when available. The latter retains the guest bootstrap error; only its known stage is exposed in the operation message. Resume with `environment resume-windows <setup-id>` after confirmed VM exit. Resume regenerates setup media and retries a failed bootstrap once over SSH; unreachable SSH requires human recovery. Never share setup media, credentials or detailed diagnostics.
+- Derive a ready image: `environment provision <new-id> --from <parent-id> --image-directory <new-absolute-host-path> [--name <name>] [--setup-script <file>] [--no-runner] --wait --timeout 3600000 --json`. The output path must not exist; its parent must be writable. The parent image stays immutable. The optional setup file is read by the CLI and runs once as the guest SSH user (Bash on Linux/macOS, Windows PowerShell 5.1 on Windows). Scripts are UTF-8, at most 64 KiB, and must not contain credentials.
+- Provisioning reserves an idle host and is cancellable through `operation cancel`; failures and cancellation stop the owned VM and remove partial output. Unconfirmed cleanup reports `action_required`; reconcile the instance and restart the service before retrying. Shutdown uses Apple Virtualization `requestStop()` for Linux and QMP `system_powerdown` for Windows, then waits for successful VM process exit; guest shutdown is a fallback when that request is unavailable. macOS provisioning instead sends `osascript -e 'tell application "loginwindow" to «event aevtshut»'` as the SSH user without sudo and waits 60 seconds. `shut` is the immediate shutdown event; `rsdn` opens confirmation. SSH-session Automation/TCC consent on macOS 26 remains unverified. If still running, `sudo -n true` gates `sudo -n /sbin/shutdown -h now` and another 60-second wait. Otherwise two successful SSH `sync` commands and a 5-second delay precede a helper force-stop. Each SSH command and helper stop is bounded to 30 seconds. A failed sync prevents freezing. The operation result records `shutdown: loginwindow|sudo|forced_stop_after_sync`; the forced value means the derived image was frozen following sync and a forced stop, not a confirmed clean guest shutdown. This exception applies only to provisioning, never runner VMs or user data. No guest password goes through Vectis.
+- Fresh Linux/Windows preparations and provisioning retain the verified pinned Actions runner. `Environment.image` records revision, provisioning time, optional parent and runner version. Matching runner versions start in place; older or missing manifests use the verified download fallback. `--no-runner` omits the runner manifest.
+- Linux/macOS preinstall and start the baked runner in the guest user's `$HOME/.vectis-runner/<version>`. Linux skips dependency installation when linked and required system libraries are present; otherwise it requires `sudo -n true` before running the installer and verifies the libraries again. Linux identity cleanup still needs passwordless sudo: boot units replace SSH host keys and the instance ID but do not reset the machine ID persisted by a provisioning boot. Before uploads or downloads, Linux checks `sudo -n true`, including with `--no-runner`; failure returns `provision_requires_guest_sudo` with next step "Prepare a new Linux environment with this Vectis version, then provision from it." Older Linux images without sudo cannot be provisioned. macOS keeps the same per-bundle device and SSH identity as existing clones.
+- Failed provision guest commands retain `exitCode` and redacted `diagnostics` in the local operation result, with up to 4 KiB each of stderr then stdout. Step markers identify the failing step. Inspect with `operation get --json`; diagnostics survive cleanup and recovery but may still contain sensitive guest output.
+- Fresh Windows installs and every Windows `environment provision` install SHA-256-pinned full Git ARM64 (Bash and GNU tar), zstd x64 through Windows 11 ARM64 emulation, and PowerShell 7 ARM64. All are on the machine PATH; custom setup scripts still run in Windows PowerShell 5.1. Exact MinGit machine PATH entries are removed, its files and other PATH entries stay. Linux preparation includes zstd.
+- Disposable Windows guests configure a whole-drive Defender policy exclusion for `C:\`, applied at the next boot even with Tamper Protection on. Realtime protection may remain enabled. Host protection stays enabled; the VM is the host isolation boundary. Windows Update (`NoAutoUpdate` and `wuauserv`), WSearch and SysMain are disabled. UsoSvc and WaaSMedicSvc may remain protected; inspect warnings and actual states. HVCI is configured off when its registry value exists; active HVCI needs a reboot.
+- Defender configuration uses only individual `reg.exe` policy writes through `cmd.exe`, before the toolchain script in both fresh installation and provisioning. Both required exclusion writes enable `Exclusions_Paths=1` under the Defender `Exclusions` policy key and add the `C:\` path with `REG_SZ` value `0` under `Exclusions\Paths`. Realtime protection policies remain best effort. Never use `Add-MpPreference` or `Set-MpPreference`: AMSI can reject even an isolated command nondeterministically. Policy writes do not prove protection is off; modern Defender ignores `DisableAntiSpyware`. `C:\ProgramData\Vectis\toolchain.json` records `Defender.Mode=policy-exclusion`, `PolicyExclusionPath=["C:\\"]` and `AppliesAt=next-boot`, preserving unrelated manifest fields. Missing effective exclusions before reboot do not fail preparation; there are no mandatory Defender status queries.
+- Both provisioning and fresh installation confirm guest shutdown before finalizing the image. The next instance boot applies the exclusion; setup scripts in the preparation boot do not yet benefit from it. Provisioning removes the obsolete `Vectis-VerifySecurity` startup task and receipts. There is no automatic runner-start check or reapplication. After the lead boots an image/clone, inspect `(Get-MpPreference).ExclusionPath` for `C:\`, and `Get-MpComputerStatus | Select-Object RealTimeProtectionEnabled,IsTamperProtected`. These read-only checks do not configure Defender. Verify service states and running HVCI separately. Guest PowerShell command failures retain a bounded full error record on stderr. See the Windows setup guide for the lead's measured post-reboot dependency installation and archive compression timings.
+- Windows derived disks depend on the absolute parent backing path. Keep parent image files in place. `environment remove` refuses registered parents until descendants are removed and always preserves disks.
+- Remote provisioning uses host paths for images; `--setup-script` is read on the calling CLI machine. MCP gets `environment.provision` through `vectis_command`.
 - `environment configure <id> --cpu --memory-mib --storage-path` changes defaults for future VMs; a VM may use at most 75% of host memory. `vectis storage --json` separates image and VM disk usage.
 - Network egress: `environment configure <id> --egress internet_only|open` applies to future instances. Windows defaults to enforced `internet_only`; explicit `open` disables the filter and permits host and local network access. Linux and macOS NAT is `open` / `not_enforced` and rejects `internet_only` with `egress_unsupported`. `status`, `environment list` and MCP `vectis_status` report effective `network.egress` and `network.enforcement`; existing instances keep their original networking.
 - Linux x86_64 tools: `environment configure <id> --x64 rosetta` enables x86_64 binaries and `docker run --platform linux/amd64`; `--x64 off` disables it for future instances. Requires Rosetta installed on the Mac and a newly prepared Linux image. Missing guest support reports `rosetta_guest_unprepared`: prepare the environment again. The runner stays ARM64, X64 labels do not match, and setup actions still default to ARM64. Changing x64 changes the environment revision; preparing leases using the old revision need cleanup and a fresh attempt.
@@ -79,6 +92,11 @@ An environment is a prepared guest image. Its ID becomes the runner label.
 - `vectis repository connect <name> --account <id> --environment <id> [--owner <org>] --wait --json` connects a repository to this Mac. The linked GitHub account needs admin permission on organization repositories. Public repositories require the GitHub setting that makes all external contributors wait for approval. Private repositories must disable fork workflows or require approval for them.
 - `vectis repository list --json` (MCP `vectis_repositories`) shows each connection with its `runsOn` label.
 - A workflow reaches an environment with `runs-on: vectis-<environment-id>`. It may also list `self-hosted`, the OS label (`Linux`, `macOS` or `Windows`) and `ARM64`, and nothing else. Any other label keeps the job away from Vectis.
+- Capacity modes: `repository capacity-mode <binding-id> demand|scale-set` is a setting command and waits for confirmation. Default `demand` keeps per-job admission. Preview `scale_set` long-polls a single GitHub runner scale set session per binding when automatic runners are enabled and the host is unpaused. MCP/remote use `vectis_command` with `{key, command: {type: "repository.capacity-mode", bindingId, mode: "scale_set"}}` (underscore in the protocol).
+- Scale set preview requires actors `any` and approval `automatic`; restrictive policies report `scale_set_policy_unsupported` and need demand mode. Never relax an existing policy just to enable the preview. GitHub's maintainer approval of external pull requests remains required.
+- `status.scaleSets` and MCP `vectis_status` expose listener states `connecting|listening|action_required|stopped`, assigned-job levels, reserved runners and safe error codes. `totalAssignedJobs` is a level, not an event counter. The host uses persisted idempotent requests, then acknowledges queue messages after acceptance. The queue token stays on the host, outside snapshots, logs and guests; the App key stays in the cloud. A queue 401 refreshes once before retry, and session conflicts report `scale_set_session_conflict` without taking over another listener.
+- Scale set requests carry `scaleSet: {generation}` and no job ID; GitHub assigns work after scale set JIT registration. They skip demand queued checks and drain after five idle minutes. Linux, macOS and Windows use the existing runner lifecycle. Linux/macOS NAT cannot enforce egress filtering; Windows defaults to enforced internet-only access.
+- Pause, disable-auto, disconnect or switch to demand to stop polling and attempt a bounded session close; running jobs finish normally. Failed close is best effort and GitHub may retain the session until expiry. Resolve action-required causes, then disable/re-enable automatic runners to retry. Enabling automatic runners, changing capacity mode and live VM execution still require user authorization.
 - `repository enable-auto <binding-id>` starts runners automatically for matching queued jobs; `disable-auto` stops that. `repository disconnect <binding-id>` stops future runners and lets running jobs finish.
 
 - `vectis repository access <binding-id> --actors any|<id,id,...> --approval automatic|required` sets a per-binding capacity policy. IDs are positive numeric GitHub user IDs (up to 100, deduplicated), never logins: find one with `gh api users/<login> --jq .id`. Absent policy preserves `any` and `automatic`; enabling automatic runners is a separate setting.
@@ -88,29 +106,56 @@ An environment is a prepared guest image. Its ID becomes the runner label.
 - On rejection, the hook writes `vectis-actions-runner/_vectis/assignment-rejected` inside the guest home, then forcibly stops only its own Runner.Worker and Runner.Listener ancestors. Any failure blocks the hook instead of returning control to the Worker. The host checks that file every 10 seconds over a separate guest connection and stops the VM through normal cleanup. This relies on the public job-started hook and was verified with synthetic process trees, not a real runner.
 - Actor-restricted reruns fail closed: the original event sender does not attest the rerun's triggering actor ID. Missing event sender or JSON parser also refuses the assignment. Ubuntu includes `jq` and `python3`; macOS must provide one. Windows uses `ConvertFrom-Json`. Listening runners retain their granted policy; changes affect subsequent admission and registration.
 
+## Repository cache volumes
+
+- Cache disks are disabled by default. `vectis repository cache enable <binding-id> [--size-gib N]` enables a sparse raw block device (20 GiB by default, whole GiB from 1 to 1024). `repository list` exposes `cacheVolume` and numeric `installationId`. The host clones a private writable fork into each instance; it never mounts the filesystem or shares a host directory.
+- `repository cache disable <binding-id>` affects future jobs and retains the saved cache. Resize by disabling, waiting for jobs, clearing, then enabling at the new size. `repository cache clear <binding-id>` deletes saved generations and refuses active or unreconciled cache instances. `repository disconnect` deletes saved cache disks and fences late write-back; cloud disconnects take effect when the host receives the binding list.
+- Shared `vectis_command` operations are `repository.cache` (`bindingId`, `enabled`, optional `sizeGiB`) and `cache.clear` (`bindingId`). They use the same local and remote operation paths as other binding settings.
+- Linux mounts ext4 at `/vectis-cache`; macOS mounts APFS at `/Volumes/VECTISCACHE`; Windows identifies the separate NVMe disk by serial `VECTISCACHE`, formats RAW disks as NTFS and assigns a drive letter. Guest setup checks identity and size, excludes boot/system storage, and formats only first use. Unknown layouts fail closed. Linux/macOS require passwordless sudo; Windows requires an elevated runner account.
+- Immediately after guest readiness, cache-enabled runners probe `sudo -n true` on Linux/macOS or the effective administrator token on Windows, before installation or registration. Older Linux environments may lack sudo support. Failure is `failed` with code `cache_volume_requires_guest_sudo`; the private fork is discarded. Prepare or provision a new environment with this Vectis version, or disable the repository cache. The observed result persists per image and guest identity: readiness check `cache.guest_sudo` reports attention for a known failure while caching is enabled, and subsequent requests fail before VM startup. An unprobed image reports unknown. The cloud does not automatically retry the same GitHub job ID after this code; after fixing the environment or disabling cache, start a runner manually for the queued job or rerun it on GitHub.
+- The listener exports `RUNNER_TOOL_CACHE=toolcache`, `npm_config_cache=npm`, `npm_config_store_dir=pnpm`, `YARN_CACHE_FOLDER=yarn`, `PIP_CACHE_DIR=pip`, `GOMODCACHE=gomod`, and `GOCACHE=go-build`, each rooted at the guest cache mount. Cargo is unchanged because `CARGO_HOME` includes executables and configuration. Workflows can override these variables.
+- Cloud `cacheWrite` grants require a known job from `push`, `schedule` or `workflow_dispatch` on the repository's current default branch and the same numeric head repository ID. PRs (including `pull_request_target`), forks, other branches, unknown run metadata and runner requests without `--job-id` discard changes. The guest assignment hook binds writable grants to the verified run attempt.
+- Runner operation and activity results expose optional `cache: { attached, writeBack, reason?, promoted? }` through CLI, MCP and remote reads. `writeBack: "granted"` is permission, while `promoted: true` confirms replacement of the saved generation after VM exit. Inspect `reason` to distinguish policy or metadata denials from host promotion errors. Events outside the exact `push`, `schedule`, `workflow_dispatch` allowlist always discard changes.
+- Scale set runners always receive `cacheWrite: false`: the workflow run is unknown at prepare time. They can read the saved cache generation but discard changes. Cache-enabled runners cold-start with their private disk attached; scale set runners without cache volumes can claim warm pool VMs. Listener reservations use the shared per-environment capacity, including memory budget and pressure.
+- Promotion requires normal listener completion, a successful guest unmount/offline, and observed VM exit. Cancellation or uncertain cleanup discards changes. Serialized atomic promotions are last-completed-promotion wins, retain one previous image and do not merge parallel writers. A failed workflow can still populate cache if its runner lifecycle ends normally.
+- Numeric installation/repository IDs and the environment scope isolate caches. Each disk has a logical size cap; concurrent forks and the previous generation can consume more host storage. Treat all cached contents as visible to every admitted job. Never store secrets there, never inherit upstream cache capacity for a fork, and never bypass GitHub's fork approval policy. Real guest cache reuse must be verified separately from synthetic tests.
+
 ## Runners and jobs
 
+- Inspect phase timings with `vectis operation get <operation-id> --json` or `vectis activity get <activity-id> --json` (MCP `vectis_operation`, `vectis_activity`). These detail reads include retained operations outside the status window; compact MCP `vectis_status` omits operation results and phase timestamps. The runner operation's optional `result.phases` survives stage updates and contains up to 16 `{name, startedAt, endedAt?}` entries with ISO UTC timestamps. Duration is `endedAt - startedAt`; a missing end is active or interrupted, and a closed phase can have failed. Older records may omit phases. CLI output is always JSON, with compact output under `--json`.
+- Phases: `queued_locally` (local acceptance to lifecycle task start, excluding GitHub/cloud queues), `vm_start` (validate, clone and spawn through VM-running confirmation), `warm_takeover` (claim an idle VM, followed by a `guest_ready` SSH health check), `vm_start_and_guest_ready` (Rosetta startup, including address discovery, pinned SSH readiness, clock, architecture and Rosetta checks inside `environment.start`), `guest_ready` (guest/SSH readiness, or a recheck after Rosetta startup), `runner_install` (download, verify and extract), `job_check` (each requested-demand check), `registration` (prepare and validate JIT grant), `waiting_for_job` (registration end to job start or listener exit), `job` (job start to listener exit), and `cleanup` (stop and release, including immediate reconciliation). Later recovery retries are excluded. `runner_preinstalled` is reserved for a future installation-skip marker and is not emitted yet.
+- After policy verification, the guest job-started hook atomically writes epoch milliseconds to `vectis-actions-runner/_vectis/job-started`. The existing 10-second policy gate poll and final listener-exit check read it without extra guest connections; late markers correct earlier busy observations. Guest readiness checks the clock is within 60 seconds of the host. Start time is clamped to registration end through observation time, capped at listener exit if known. A missing, invalid or unreadable marker falls back to GitHub's busy poll, normally every 30 seconds, which can miss short jobs. Bash uses GNU `date` or Perl `Time::HiRes`; Windows uses PowerShell 5.1-compatible .NET APIs. Timing failures do not change policy decisions. These are hook-to-listener-exit timings, with possible guest clock skew and runner teardown; never infer actual job identity, success or exact GitHub queue time from phases. Repeated idle checks evict the oldest completed `job_check` entries to preserve startup and cleanup; these checks overlap waiting/job phases, so do not sum them into total time.
+- Warm pool is opt-in per environment: `vectis environment configure <id> --warm-pool <N> --wait` (0-4, default 0). It keeps unused, SSH-ready Linux, macOS or Windows VMs, using real host RAM and disk space. Shared memory admission, pressure and macOS limits apply; filling leaves one runner slot and a startup estimate free and yields to accepted runners. The size is an upper bound; a one-runner machine keeps no pool.
+- Idle pool instances have `role: "warming"` during startup and `role: "warm"` only after SSH readiness. They are not running jobs. Runner capacity treats owned pool VMs as reclaimable, but its memory budget still includes their actual commitment. A runner claims once, checks SSH and only then requests JIT configuration. Warm VMs never hold job credentials or runner registrations; unhealthy claims are stopped before a cold start, and used job VMs are destroyed rather than returned to the pool.
+- Pool VMs yield to other environments' real jobs when capacity is needed and recycle after 30 minutes. `--warm-pool 0`, pause and service shutdown drain the pool; changed environment defaults replace idle VMs. Crash recovery reconciles them as interrupted instances and never trusts a stale warm marker. The same `environment.configure` command works through CLI, MCP `vectis_command` and remote replay.
+
 - `vectis runner run <binding-id> --key <key> [--job-id <id>] --json` starts one disposable runner. Its success means the VM ran and was cleaned up, not that the job passed. Read job results with `vectis job list <binding-id> --json` or MCP `vectis_jobs`.
-- Automatic runner requests are checked after two minutes and expire before claim if the machine is offline, or after ten minutes even if it is online. The queued job becomes available to another eligible machine on the next demand pass, within the existing three-attempt limit.
-- A runner requested for a specific job is drained after 10 idle minutes when its job no longer needs queued capacity. The VM is released and the operation reports `cancelled` with result code `runner_idle`; busy runners keep running, and status errors keep the runner listening.
+- Demand-mode automatic runner requests are checked after two minutes and expire before claim if the machine is offline, or after ten minutes even if it is online. The queued job becomes available to another eligible machine on the next demand pass, after a 60-second retry delay. Expiry counts toward the three-failure budget; successful runners serving other jobs do not. Automatic admission has a separate cap of ten total attempts per job. Action-required or deleted previous operations can retry after ten minutes; only action-required operations count as failures.
+- Environment CPU and memory are per-VM ceilings. CPU overcommit is allowed; each VM must still fit host cores. Memory is allocated lazily, so generous ceilings can be useful: Linux 8 vCPUs / 12288 MiB, Windows 8 / 16384 MiB, macOS 6 / 12288 MiB when supported by the host. Preparation defaults are unchanged; touched memory may remain allocated until a disposable VM exits.
+- Memory admission counts each non-stopped VM at max(process RSS, startup floor). Floors are Linux 2048 MiB, macOS and Windows 4096 MiB, capped by the VM ceiling. Fresh VMs without a PID and accepted runners reserve estimates; a failed footprint measurement uses the configured ceiling. Footprint and pressure probes are cached for five seconds. New VMs need room for their estimate and normal host pressure; `memory_budget_exceeded` or `memory_pressure` gives next steps. Unknown pressure is treated as normal and reports `pressureKnown: false`. Startup also checks available host memory against the estimate. The budget gates new starts, not runtime growth; lowering it or rising pressure does not stop running VMs.
+- Capacity is reported per ready environment in `status.runnerCapacity.environments`; overall `available` is their maximum, not their sum. macOS has a shared two-VM limit. Interrupted instances reserve their own resources; an action-required runner releases its local slot only after its VM is verified stopped or no start occurred.
+- Every runner drains after 5 idle minutes when its requested job no longer needs queued capacity. Manual and scale set runners without a job ID use the same idle window. Vectis confirms not busy before stopping the VM and releasing the lease; the operation reports `cancelled` with `runner_idle`.
+- A locally listening runner reported offline or missing for 2 consecutive minutes stops with retryable `failed` code `runner_offline`. Continuous GitHub status errors for 15 minutes trigger the same recovery. Unconfirmed cleanup stays `action_required` until release is confirmed.
+- Prepare failures with confirmed cleanup end as retryable `failed` with `runner_registration_failed`. A lost response is reconciled and fenced before retrying; unresolved cloud state remains `runner_registration_uncertain`. Approval-required cases retain their manual next steps.
 - A runner activity's `subject.requestedJob` identifies the job that requested capacity; `subject.actualJob` identifies the job observed on its registered runner. Both are optional and can differ. Never infer the actual job from the requested job. Use their `name`, `workflowName` and `htmlUrl` only when present. The activity status still reports the runner lifecycle, including cleanup, independently of the GitHub job result.
 - Actual job observation survives runner completion and service restarts. It watches up to 20 of the newest eligible leases from activities created within the last 48 hours, until each actual job completes. Missing observations remain unknown; stored observations stay in activity history.
 - Read a GitHub job log with `vectis job logs <job-id> --binding <binding-id>`; `--follow` starts polling every 2 seconds, doubles the interval after empty chunks up to 30 seconds, resets to 2 seconds when text arrives, and stops when complete. `--json` prints one response per chunk. MCP `vectis_job_logs` takes `{bindingId, jobId, after?}`; pass `next` back as `after` (an absolute, nonnegative integer byte offset) to continue. Responses include `text`, `next`, `status`, `complete` and `truncated`. Logs are fetched on demand, without stored log archives, and preserve GitHub masking. Remote inspection responses expire after 60 seconds. Reads page through the last 4 MiB in UTF-8 chunks of at most 32 KiB; `truncated` means unread earlier bytes were skipped. Bounded Range requests download one chunk at a time when supported; fallback downloads are capped at 64 MiB. A running job may return empty text until GitHub publishes logs; only a completed job at EOF reports `complete: true`.
 - `job scan <binding-id>` finds queued or running jobs Vectis missed; `job refresh <binding-id> <job-id>` rereads one job from GitHub.
 - `run rerun-failed <binding-id> <run-id> --wait` reruns failed jobs of a completed run; `run cancel <binding-id> <run-id> --wait` requests cancellation of an active run. MCP uses `run.rerun-failed` and `run.cancel` through `vectis_command`.
 - `workflow dispatch <binding-id> <workflow-file-or-id> --ref <branch-or-tag> [--input key=value ...] --wait` dispatches a workflow with up to 25 string inputs and complete command JSON of at most 65,535 bytes. MCP uses `workflow.dispatch`. Report the run ID only when returned; 204 means accepted, run ID unknown. Dispatch acceptance is not job completion.
+- `github_unavailable` and `github_rate_limited` mean GitHub could not complete a request within bounded retries. Wait for availability or the rate limit reset before retrying. Never blindly retry an ambiguous side-effecting POST; inspect its existing outcome first.
 - Run control requires GitHub App `actions: write`. For `github_app_permission_required`, ask the user to approve the updated App permissions on GitHub (Settings -> Applications), then retry. Rerun and dispatch require the public-repository fork approval policy; cancel does not.
 - GitHub-accepted rerun and cancel requests finish as `succeeded` with `result.state: "accepted"`. Vectis rereads with backoff for up to 5 seconds for rerun or 20 seconds for cancel. `result.rerun` and `result.cancellation` are `"observed"` only after a newer attempt or stopped run is seen; otherwise they are `"requested"`, including when rereads fail. For requested cancellation, report "GitHub accepted the cancellation; the run is still stopping." Request success does not prove job completion.
 - Run control retains a cloud receipt keyed by machine and operation key before any POST. Remote `remote:<id>` keys use the same receipt. A replay reads its stored outcome and never submits twice while the receipt is retained. The daily sweep expires receipts 30 days after their last update; do not replay keys after that window because duplicate protection has expired. Only ambiguous POST responses (network errors, 5xx or missing status) leave rerun or cancel `action_required` with `run_command_unconfirmed`: check GitHub before retrying with a new key, never blindly retry. Stopping the Vectis wait does not undo a submitted GitHub request.
 - A failed runner whose guest connection was lost or whose runner process exited keeps `diagnostics` (runner output, SSH error, host network and guest state) in its operation `result`; read it with `vectis operation get <id> --json` before retrying.
-- For `runner_cleanup_required`, Vectis retries cleanup about every minute while connected to the cloud, for up to 30 minutes from the operation's last update. `runner_busy` means GitHub still holds the runner on a job, usually until it releases the job within 15 minutes. Failed retries keep `action_required` without extending the window. After that window, or for other interrupted runner states, use `runner reconcile <operation-id>`; an interrupted VM needs `instance reconcile <id>` first. Do not start new runners to hide uncertain cleanup.
-- Refused assignments retain `cause: { code: "runner_assignment_rejected", message }` while cleanup waits. Successful manual or automatic reconciliation ends them as `failed` with `runner_assignment_rejected` and the original refusal message. Other interrupted runners keep the `cancelled` outcome; check GitHub separately for the job result.
+- After restart, interrupted runners carry `runner_recovery_pending`. Startup and periodic recovery verify VM exit, reconcile the cloud lease and release the runner automatically once the instance is stopped or absent. Recovery also covers `runner_cleanup_required`, `runner_registration_uncertain` and legacy interrupted results without a code. Retries while connected back off from 1 minute, doubling to 30 minutes, for up to 24 hours; the schedule survives restarts. `runner_busy` means GitHub still holds the runner on a job, usually until it releases the job within 15 minutes. Unconfirmed VM exit or cloud release stays `action_required`. After 24 hours, the result includes a manual next step: `runner reconcile <operation-id>`, with `instance reconcile <id>` first if VM exit remains unconfirmed. Do not start new runners to hide uncertain cleanup.
+- Refused assignments retain `cause: { code: "runner_assignment_rejected", message }` while cleanup waits. Successful manual or automatic reconciliation ends them as `failed` with `runner_assignment_rejected` and the original refusal message. Offline failures retain `failed` with `runner_offline`. Other interrupted runners end as `cancelled` with `runner_interrupted`; requests interrupted before startup began end as `failed` with the same code. Check GitHub separately for the job result.
 - Runner reconciliation can close a request with no cloud lease only after confirming VM cleanup and recording the request as released in the cloud. An unavailable cloud remains unresolved; missing local lease metadata alone never proves cleanup.
 - Failed file cleanup after an owned VM exits retains an exit receipt for instance reconciliation. A leftover directory alone does not prove the VM is running or stopped.
 
 A job that stays queued usually has one of these causes. Check them in order:
 
-1. The machine is paused (`status`), offline (`cloud.state`), or at its concurrent VM limit (`vectis machine configure --max-runners`, default 5, bounded by host CPU and 75% of memory), or busy with a preparation.
+1. The machine is paused (`status`), offline (`cloud.state`), or at its concurrent VM limit (`vectis machine configure --max-runners`, default 5, bounded by the shared memory budget and normal host memory pressure), or busy with a preparation.
 2. Automatic runners are off for the repository, so nobody starts a runner.
 3. The workflow's `runs-on` labels do not match the connection's `runsOn` label.
 4. The environment is not ready, or it was removed.
@@ -126,3 +171,5 @@ An automatic runner request a Mac never claims expires as `machine_offline` (off
 - `vectis migration analyze <binding-id> --wait --json` prepares a preview for a connected repository; review every change and finding with the user. `migration publish <preview-id>` opens a pull request after a successful runner on the same environment, and never merges.
 - Migration changes only selected label scalars, preserving quoting and all surrounding source formatting. Unsafe scalar forms require manual review. Optional per-file `jobs` summaries report changed jobs, reasons for retained selections and static `needs` edges.
 - Migration only moves ARM64-compatible jobs. It leaves x64 labels, reusable workflows, dynamic matrices and privileged triggers alone.
+
+Repository cache jobs use a cold VM start so the private cache disk is attached before boot. They do not claim generic warm pool VMs; idle pool VMs yield when the job needs their capacity. Jobs without a cache volume can still use the warm pool.
diff --git a/tests/convex/control.test.ts b/tests/convex/control.test.ts
index e1122d4b..e8660f72 100644
--- a/tests/convex/control.test.ts
+++ b/tests/convex/control.test.ts
@@ -27,7 +27,10 @@ beforeEach(() => {
   vi.stubEnv("CLERK_JWT_ISSUER_DOMAIN", "https://clerk.test");
   vi.stubEnv("VECTIS_MACHINE_ISSUER", "https://machines.test");
 });
-afterEach(() => vi.unstubAllEnvs());
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.useRealTimers();
+});
 const identity = (subject: string) => ({
   issuer: "https://clerk.test",
   subject,
@@ -141,6 +144,54 @@ test("machine secrets are hashed and exchange for short-lived signed JWTs until
   expect((await exchange()).status).toBe(401);
 });
 
+test("machine tokens issued in the same second have unique signed JWT IDs", async () => {
+  vi.useFakeTimers();
+  const now = Math.floor(Date.now() / 1000);
+  vi.setSystemTime(now * 1000);
+  const { privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+  vi.stubEnv(
+    "VECTIS_MACHINE_PRIVATE_KEY",
+    privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+  );
+  const t = convexTest(schema, modules);
+  const owner = t.withIdentity(identity("owner"));
+  const machineId = await owner.mutation(api.machines.enroll, { localId: "host", name: "Host" });
+  const issue = () =>
+    t.action(internal.machineTokens.signToken, { machineId, credentialVersion: 1 });
+  const first = await issue();
+  const second = await issue();
+  expect(second.token).not.toBe(first.token);
+  const claims = [first, second].map(({ token, expiresAt }) => {
+    const [header, payload, signature] = token.split(".");
+    if (!header || !payload || !signature) throw new Error("Invalid token shape.");
+    expect(
+      verify(
+        "RSA-SHA256",
+        Buffer.from(`${header}.${payload}`),
+        createPublicKey(privateKey),
+        Buffer.from(signature, "base64url"),
+      ),
+    ).toBe(true);
+    const decoded: unknown = JSON.parse(Buffer.from(payload, "base64url").toString());
+    expect(decoded).toMatchObject({
+      iss: "https://machines.test",
+      aud: "vectis-machine",
+      sub: machineId,
+      credentialVersion: 1,
+      iat: now - 5,
+      exp: now + 300,
+      jti: expect.stringMatching(
+        /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+      ),
+    });
+    expect(expiresAt).toBe((now + 300) * 1000);
+    if (!decoded || typeof decoded !== "object" || !("jti" in decoded))
+      throw new Error("Missing JWT ID.");
+    return decoded;
+  });
+  expect(claims[0]?.jti).not.toBe(claims[1]?.jti);
+});
+
 test("lost local replies and relay restart reuse the durable local operation", async () => {
   const t = convexTest(schema, modules);
   const owner = t.withIdentity(identity("relay-owner"));
@@ -176,7 +227,7 @@ test("lost local replies and relay restart reuse the durable local operation", a
       advanceRemoteOperation(
         await pending(),
         {
-          status: (...args) => local.status(...args),
+          operationByKey: (...args) => local.operationByKey(...args),
           submit: async (...args) => {
             await local.submit(...args);
             throw new Error("Connection lost after the service accepted the command.");
@@ -339,8 +390,8 @@ test.each([
   }));
   const local = {
     submit,
-    status: async () => {
-      throw new Error("Unexpected status read");
+    operationByKey: async () => {
+      throw new Error("Unexpected operation lookup");
     },
   };
   const pending = async () => {
diff --git a/tests/convex/github.test.ts b/tests/convex/github.test.ts
index 4f9aeff8..5a80f269 100644
--- a/tests/convex/github.test.ts
+++ b/tests/convex/github.test.ts
@@ -172,14 +172,13 @@ test("job tracking ignores late state regressions and retains only bounded metad
   const jobs = await t.run(async (ctx) => ctx.db.query("githubJobs").collect());
   expect(jobs).toHaveLength(1);
   expect(jobs[0]).toMatchObject({ status: "completed", conclusion: "success", runnerId: 5 });
-  await expect(
-    t.mutation(internal.githubDeliveries.accept, {
-      ...common,
-      deliveryId: "oversized",
-      job: {
-        ...common.job,
-        labels: Array.from({ length: 101 }, () => "label"),
-      },
-    }),
-  ).rejects.toThrow();
+  await t.mutation(internal.githubDeliveries.accept, {
+    ...common,
+    deliveryId: "oversized",
+    job: {
+      ...common.job,
+      labels: Array.from({ length: 101 }, () => "label"),
+    },
+  });
+  expect(await t.run((ctx) => ctx.db.query("githubDeliveries").collect())).toHaveLength(3);
 });
diff --git a/tests/convex/githubRedelivery.test.ts b/tests/convex/githubRedelivery.test.ts
new file mode 100644
index 00000000..b777e3d4
--- /dev/null
+++ b/tests/convex/githubRedelivery.test.ts
@@ -0,0 +1,316 @@
+import { generateKeyPairSync } from "node:crypto";
+import { convexTest } from "convex-test";
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+import schema from "../../convex/schema.js";
+import { internal } from "../../convex/_generated/api.js";
+
+const modules = {
+  "../../convex/githubRedelivery.ts": () => import("../../convex/githubRedelivery.js"),
+  "../../convex/githubRedeliveryState.ts": () => import("../../convex/githubRedeliveryState.js"),
+  "../../convex/retention.ts": () => import("../../convex/retention.js"),
+  "../../convex/_generated/server.js": () => import("../../convex/_generated/server.js"),
+};
+const minute = 60_000;
+const day = 24 * 60 * minute;
+const now = Date.parse("2026-10-16T12:00:00Z");
+const privateKey = generateKeyPairSync("rsa", { modulusLength: 2048 })
+  .privateKey.export({ format: "pem", type: "pkcs8" })
+  .toString();
+const delivery = (
+  id: number,
+  guid = `guid-${id}`,
+  age = 2 * minute,
+  status = 500,
+  event = "workflow_job",
+) => ({
+  id,
+  guid,
+  delivered_at: new Date(Date.now() - age).toISOString(),
+  status_code: status,
+  status: status === 200 ? "OK" : "Internal Server Error",
+  event,
+  action: "queued",
+  redelivery: false,
+});
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(now);
+  vi.spyOn(console, "warn").mockImplementation(() => {});
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(() => {
+      throw new Error("Unexpected unstubbed GitHub request.");
+    }),
+  );
+});
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+async function fixture(rows: ReturnType<typeof delivery>[] = []) {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    await ctx.db.insert("githubApps", {
+      appId: 42,
+      slug: "test",
+      ownerId: 7,
+      clientId: "test-client",
+      privateKey,
+      clientSecret: "test",
+      webhookSecret: "test",
+    });
+  });
+  const fetch = vi.fn(async (_url: string, init?: RequestInit) =>
+    init?.method === "POST" ? new Response(null, { status: 202 }) : Response.json(rows),
+  );
+  vi.stubGlobal("fetch", fetch);
+  return {
+    t,
+    fetch,
+    scan: () => t.action(internal.githubRedelivery.scan, {}),
+    checkpoint: () => t.run((ctx) => ctx.db.query("githubRedeliveryCheckpoint").first()),
+    requests: () => t.run((ctx) => ctx.db.query("githubRedeliveryRequests").collect()),
+    posts: () => fetch.mock.calls.filter(([, init]) => init?.method === "POST"),
+  };
+}
+
+test("redelivers a failed guid once using the App JWT and advances the checkpoint", async () => {
+  const f = await fixture([delivery(2, "failed"), delivery(1, "failed", 3 * minute)]);
+  await f.scan();
+  expect(f.posts()).toHaveLength(1);
+  expect(f.posts()[0]?.[0]).toBe("https://api.github.com/app/hook/deliveries/2/attempts");
+  const headers = new Headers(f.fetch.mock.calls[0]?.[1]?.headers);
+  const token = headers.get("Authorization")?.split(" ")[1];
+  const payload = token?.split(".")[1];
+  expect(payload && JSON.parse(Buffer.from(payload, "base64url").toString())).toMatchObject({
+    iss: "test-client",
+    exp: now / 1000 + 300,
+  });
+  expect(await f.requests()).toMatchObject([{ guid: "failed", requestedAt: now }]);
+  expect(await f.checkpoint()).toMatchObject({ deliveredAt: now - minute, scannedAt: now });
+});
+
+test("a later successful attempt suppresses redelivery across cursor pages", async () => {
+  const f = await fixture();
+  f.fetch.mockImplementation(async (url) => {
+    const cursor = new URL(url).searchParams.get("cursor");
+    if (cursor === null)
+      return Response.json([delivery(2, "recovered", 2 * minute, 200)], {
+        headers: {
+          link: '<https://api.github.com/app/hook/deliveries?per_page=100&cursor=opaque%2Bnext>; rel="next"',
+        },
+      });
+    expect(cursor).toBe("opaque+next");
+    return Response.json([delivery(1, "recovered", 3 * minute)]);
+  });
+  await f.scan();
+  expect(f.fetch).toHaveBeenCalledTimes(2);
+  expect(f.posts()).toHaveLength(0);
+  expect(await f.requests()).toHaveLength(0);
+});
+
+test("any 2xx attempt suppresses redelivery, even when the newest attempt failed", async () => {
+  const f = await fixture([delivery(2, "recovered"), delivery(1, "recovered", 3 * minute, 204)]);
+  await f.scan();
+  expect(f.posts()).toHaveLength(0);
+});
+
+test("fresh failures stay eligible for the next scan", async () => {
+  const row = delivery(1, "fresh", 30_000);
+  const f = await fixture([row]);
+  await f.scan();
+  expect(f.posts()).toHaveLength(0);
+  expect(await f.checkpoint()).toMatchObject({ deliveredAt: now - minute });
+  vi.setSystemTime(now + 2 * minute);
+  await f.scan();
+  expect(f.posts()).toHaveLength(1);
+});
+
+test.each([403, 429, 500, 503])("listing failure %s preserves the checkpoint", async (status) => {
+  const f = await fixture();
+  await f.scan();
+  const checkpoint = await f.checkpoint();
+  vi.setSystemTime(now + 2 * minute);
+  f.fetch.mockResolvedValue(Response.json({ message: "Unavailable" }, { status }));
+  await f.scan();
+  expect(await f.checkpoint()).toEqual(checkpoint);
+  expect(f.posts()).toHaveLength(0);
+  expect(console.warn).toHaveBeenCalled();
+});
+
+test("a later page failure makes no requests and creates no checkpoint", async () => {
+  const f = await fixture();
+  f.fetch
+    .mockResolvedValueOnce(
+      Response.json([delivery(1)], {
+        headers: { link: '<https://api.github.com/app/hook/deliveries?cursor=next>; rel="next"' },
+      }),
+    )
+    .mockRejectedValueOnce(new Error("Network unavailable"));
+  await f.scan();
+  expect(await f.checkpoint()).toBeNull();
+  expect(await f.requests()).toHaveLength(0);
+});
+
+test("guid dedupe survives repeated scans and new failed delivery IDs", async () => {
+  const f = await fixture([delivery(1, "failed")]);
+  await f.scan();
+  vi.setSystemTime(now + 2 * minute);
+  f.fetch.mockImplementation(async (_url, init) =>
+    init?.method === "POST"
+      ? new Response(null, { status: 202 })
+      : Response.json([delivery(2, "failed")]),
+  );
+  await f.scan();
+  expect(f.posts()).toHaveLength(1);
+  expect(await f.requests()).toHaveLength(1);
+});
+
+test("concurrent claims cannot both request redelivery for one guid", async () => {
+  const f = await fixture();
+  const claims = await Promise.all([
+    f.t.mutation(internal.githubRedeliveryState.claim, { guid: "same" }),
+    f.t.mutation(internal.githubRedeliveryState.claim, { guid: "same" }),
+  ]);
+  expect(claims.sort()).toEqual([false, true]);
+  expect(await f.requests()).toHaveLength(1);
+});
+
+test("no configured App means no fetch and no checkpoint", async () => {
+  const t = convexTest(schema, modules);
+  await t.action(internal.githubRedelivery.scan, {});
+  expect(fetch).not.toHaveBeenCalled();
+  expect(await t.run((ctx) => ctx.db.query("githubRedeliveryCheckpoint").first())).toBeNull();
+  expect(console.warn).not.toHaveBeenCalled();
+});
+
+test("only Vectis events within the initial one-hour window are redelivered", async () => {
+  const f = await fixture([
+    delivery(6, "unsupported", minute, 500, "push"),
+    ...["workflow_job", "installation", "installation_repositories", "repository"].map(
+      (event, index) => delivery(5 - index, event, 2 * minute, 500, event),
+    ),
+    delivery(1, "too-old", 61 * minute),
+  ]);
+  await f.scan();
+  expect((await f.requests()).map((row) => row.guid).sort()).toEqual([
+    "installation",
+    "installation_repositories",
+    "repository",
+    "workflow_job",
+  ]);
+});
+
+test("stale checkpoints never extend eligibility beyond three days", async () => {
+  const f = await fixture([delivery(2, "eligible", 2 * day), delivery(1, "expired", 4 * day)]);
+  await f.t.run((ctx) =>
+    ctx.db.insert("githubRedeliveryCheckpoint", {
+      deliveredAt: now - 5 * day,
+      scannedAt: now - 5 * day,
+    }),
+  );
+  await f.scan();
+  expect(await f.requests()).toMatchObject([{ guid: "eligible" }]);
+});
+
+test("scanning stops at the checkpoint without fetching the next page", async () => {
+  const f = await fixture();
+  await f.t.run((ctx) =>
+    ctx.db.insert("githubRedeliveryCheckpoint", {
+      deliveredAt: now - 3 * minute,
+      scannedAt: now - 2 * minute,
+    }),
+  );
+  f.fetch.mockResolvedValue(
+    Response.json([delivery(1, "old", 4 * minute)], {
+      headers: { link: '<https://api.github.com/app/hook/deliveries?cursor=next>; rel="next"' },
+    }),
+  );
+  await f.scan();
+  expect(f.fetch).toHaveBeenCalledTimes(1);
+  expect(f.posts()).toHaveLength(0);
+});
+
+test("the redelivery limit drains remaining guids on a later run without skipping them", async () => {
+  const f = await fixture(Array.from({ length: 25 }, (_, index) => delivery(index + 1)));
+  await f.scan();
+  expect(f.posts()).toHaveLength(20);
+  expect(await f.checkpoint()).toBeNull();
+  await f.scan();
+  expect(f.posts()).toHaveLength(25);
+  expect(await f.requests()).toHaveLength(25);
+  expect(await f.checkpoint()).not.toBeNull();
+});
+
+test("the page limit preserves the checkpoint rather than skipping unseen attempts", async () => {
+  const f = await fixture();
+  f.fetch.mockImplementation(async () =>
+    Response.json([delivery(1)], {
+      headers: { link: '<https://api.github.com/app/hook/deliveries?cursor=next>; rel="next"' },
+    }),
+  );
+  await f.scan();
+  expect(f.fetch).toHaveBeenCalledTimes(10);
+  expect(await f.checkpoint()).toBeNull();
+  expect(f.posts()).toHaveLength(0);
+});
+
+test("a POST error is logged and never repeated, including after an uncertain timeout", async () => {
+  const f = await fixture([delivery(1)]);
+  f.fetch.mockImplementation(async (_url, init) => {
+    if (init?.method === "POST") throw new Error("Timed out after sending");
+    return Response.json([delivery(1)]);
+  });
+  await f.scan();
+  expect(await f.checkpoint()).toBeNull();
+  await f.scan();
+  expect(f.posts()).toHaveLength(1);
+  expect(await f.checkpoint()).not.toBeNull();
+  expect(console.warn).toHaveBeenCalled();
+});
+
+test("the action time budget leaves unrequested guids available for the next tick", async () => {
+  const f = await fixture([delivery(1)]);
+  f.fetch.mockImplementation(async () => {
+    vi.setSystemTime(now + 90_000);
+    return Response.json([delivery(1, "guid-1", 3 * minute)]);
+  });
+  await f.scan();
+  expect(await f.requests()).toHaveLength(0);
+  expect(await f.checkpoint()).toBeNull();
+});
+
+test("retention expires redelivery receipts after three days in bounded batches", async () => {
+  const f = await fixture();
+  await f.t.run(async (ctx) => {
+    for (let index = 0; index < 501; index++)
+      await ctx.db.insert("githubRedeliveryRequests", {
+        guid: `old-${index}`,
+        requestedAt: now - 3 * day - 1,
+      });
+    await ctx.db.insert("githubRedeliveryRequests", {
+      guid: "boundary",
+      requestedAt: now - 3 * day,
+    });
+    await ctx.db.insert("githubRedeliveryRequests", { guid: "recent", requestedAt: now });
+  });
+  await f.t.mutation(internal.retention.sweep, {});
+  expect(await f.requests()).toHaveLength(3);
+  await f.t.finishAllScheduledFunctions(vi.runAllTimers);
+  expect((await f.requests()).map((row) => row.guid).sort()).toEqual(["boundary", "recent"]);
+});
+
+test("delivery IDs beyond the safe integer range are redelivered exactly", async () => {
+  const f = await fixture();
+  const body = JSON.stringify([delivery(1)]).replace('"id":1', '"id":98765432109876543210');
+  f.fetch.mockImplementation(async (_url: string, init?: RequestInit) =>
+    init?.method === "POST" ? new Response(null, { status: 202 }) : new Response(body),
+  );
+  await f.scan();
+  expect(f.posts()[0]?.[0]).toBe(
+    "https://api.github.com/app/hook/deliveries/98765432109876543210/attempts",
+  );
+});
diff --git a/tests/convex/githubResilience.test.ts b/tests/convex/githubResilience.test.ts
new file mode 100644
index 00000000..8e5df6d3
--- /dev/null
+++ b/tests/convex/githubResilience.test.ts
@@ -0,0 +1,287 @@
+import { createHmac, generateKeyPairSync } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { convexTest } from "convex-test";
+import { getFunctionName, type FunctionReference } from "convex/server";
+import { afterEach, expect, test, vi } from "vitest";
+import schema from "../../convex/schema.js";
+import { api, internal } from "../../convex/_generated/api.js";
+import { unmatchableLabels } from "../../packages/github/src/job.js";
+import { Service } from "../../apps/server/src/service.js";
+import { Store } from "../../apps/server/src/store.js";
+import { VmRuntime } from "../../packages/runner/src/runtime.js";
+import { startCloudRelay } from "../../packages/client/src/cloud-relay.js";
+import { VectisClient } from "../../packages/client/src/index.js";
+
+const transport = vi.hoisted(() => ({
+  action:
+    vi.fn<
+      (reference: FunctionReference<"action">, args: Record<string, unknown>) => Promise<unknown>
+    >(),
+}));
+vi.mock("convex/browser", () => ({
+  ConvexClient: class {
+    action = transport.action;
+    query = async () => new Promise<never>(() => {});
+    onUpdate = () => () => {};
+    client = {
+      connectionState: () => ({ isWebSocketConnected: true }),
+      subscribeToConnectionState: () => () => {},
+    };
+    setAuth(_fetchToken: unknown, changed: (value: boolean) => void) {
+      changed(true);
+    }
+    async close() {}
+  },
+}));
+const modules = {
+  "../../convex/http.ts": () => import("../../convex/http.js"),
+  "../../convex/githubWebhook.ts": () => import("../../convex/githubWebhook.js"),
+  "../../convex/githubDeliveries.ts": () => import("../../convex/githubDeliveries.js"),
+  "../../convex/githubAppSetup.ts": () => import("../../convex/githubAppSetup.js"),
+  "../../convex/githubJobs.ts": () => import("../../convex/githubJobs.js"),
+  "../../convex/githubRuns.ts": () => import("../../convex/githubRuns.js"),
+  "../../convex/runReceipts.ts": () => import("../../convex/runReceipts.js"),
+  "../../convex/jobs.ts": () => import("../../convex/jobs.js"),
+  "../../convex/runnerLeases.ts": () => import("../../convex/runnerLeases.js"),
+  "../../convex/runnerDemand.ts": () => import("../../convex/runnerDemand.js"),
+  "../../convex/_generated/server.js": () => import("../../convex/_generated/server.js"),
+};
+const privateKey = generateKeyPairSync("rsa", { modulusLength: 2048 })
+  .privateKey.export({ format: "pem", type: "pkcs8" })
+  .toString();
+const job = {
+  id: 4,
+  run_id: 5,
+  name: "Build",
+  status: "queued",
+  conclusion: null,
+  labels: ["vectis-mac"],
+};
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+  transport.action.mockReset();
+});
+async function fixture() {
+  vi.useFakeTimers();
+  vi.stubEnv("VECTIS_MACHINE_ISSUER", "https://machine.test");
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => {
+      throw new Error("Unexpected fetch");
+    }),
+  );
+  const t = convexTest(schema, modules);
+  const { machineId, bindingId } = await t.run(async (ctx) => {
+    const machineId = await ctx.db.insert("machines", {
+      owner: "owner",
+      localId: "local",
+      name: "Mac",
+      createdAt: 1,
+      paused: false,
+      environments: [
+        { id: "mac", name: "Mac", os: "macos", cpu: 2, memoryMiB: 4096, state: "ready" },
+      ],
+    });
+    await ctx.db.insert("machinePresence", { machineId, lastSeenAt: Date.now(), runnerSlots: 1 });
+    const accountId = await ctx.db.insert("githubAccounts", {
+      owner: "owner",
+      githubId: 7,
+      login: "owner",
+      installations: [],
+      verifiedAt: 1,
+    });
+    const bindingId = await ctx.db.insert("repositoryBindings", {
+      owner: "owner",
+      machineId,
+      accountId,
+      repositoryId: 2,
+      repositoryName: "sandbox",
+      installationId: 3,
+      environmentId: "mac",
+      enabled: true,
+      automatic: true,
+      verifiedAt: 1,
+    });
+    await ctx.db.insert("githubApps", {
+      appId: 42,
+      slug: "test",
+      ownerId: 7,
+      clientId: "client",
+      privateKey,
+      clientSecret: "test",
+      webhookSecret: "test",
+    });
+    return { machineId, bindingId };
+  });
+  const device = t.withIdentity({
+    issuer: "https://machine.test",
+    subject: machineId,
+    credentialVersion: 0,
+  });
+  const webhook = async (input: Record<string, unknown>, delivery = "delivery") => {
+    const body = JSON.stringify({
+      action: "queued",
+      installation: { id: 3 },
+      repository: { id: 2 },
+      workflow_job: input,
+    });
+    return t.fetch("/github/webhook", {
+      method: "POST",
+      body,
+      headers: {
+        "x-github-event": "workflow_job",
+        "x-github-delivery": delivery,
+        "x-hub-signature-256": `sha256=${createHmac("sha256", "test").update(body).digest("hex")}`,
+      },
+    });
+  };
+  const stubApi = (read: (url: string) => Response) => {
+    const fetch = vi.fn(async (url: string) => {
+      if (url.endsWith("/installation"))
+        return Response.json({
+          id: 3,
+          app_id: 42,
+          account: { id: 7, type: "User" },
+          suspended_at: null,
+        });
+      if (url.endsWith("/access_tokens")) return Response.json({ token: "scoped-test-token" });
+      if (url === "https://api.github.com/repos/owner/sandbox")
+        return Response.json({ id: 2, private: true, owner: { id: 7 } });
+      return read(url);
+    });
+    vi.stubGlobal("fetch", fetch);
+    return fetch;
+  };
+  return { t, device, bindingId, machineId, webhook, stubApi };
+}
+
+test("a signed webhook truncates a 300-character job name and drops an overlong URL", async () => {
+  const { t, webhook } = await fixture();
+  expect(
+    (
+      await webhook({
+        ...job,
+        name: "a".repeat(300),
+        html_url: "https://github.com/" + "a".repeat(500),
+      })
+    ).status,
+  ).toBe(202);
+  const stored = await t.run((ctx) => ctx.db.query("githubJobs").unique());
+  expect(stored?.name).toBe("a".repeat(200));
+  expect(stored).not.toHaveProperty("htmlUrl");
+  expect(await t.run((ctx) => ctx.db.query("githubDeliveries").collect())).toHaveLength(1);
+});
+
+test("an unknown webhook status is recorded as waiting and the existing scan can repair it", async () => {
+  const { t, device, bindingId, webhook, stubApi } = await fixture();
+  expect((await webhook({ ...job, status: "future_status" })).status).toBe(202);
+  expect(await t.run((ctx) => ctx.db.query("githubDeliveries").collect())).toHaveLength(1);
+  expect(await t.run((ctx) => ctx.db.query("githubJobs").unique())).toMatchObject({
+    status: "waiting",
+  });
+  expect(await device.query(internal.jobs.pendingRuns, { bindingId })).toMatchObject({
+    runIds: [5],
+  });
+  stubApi((url) =>
+    url.includes("/actions/runs?")
+      ? Response.json({ total_count: 0, workflow_runs: [] })
+      : Response.json({ total_count: 1, jobs: [{ ...job, name: "n".repeat(300) }] }),
+  );
+  expect(await device.action(api.githubJobs.scan, { bindingId })).toEqual({
+    complete: true,
+    jobs: 1,
+    runs: 1,
+  });
+  expect(await t.run((ctx) => ctx.db.query("githubJobs").unique())).toMatchObject({
+    status: "queued",
+    name: "n".repeat(200),
+  });
+});
+
+test.each([
+  { labels: Array.from({ length: 101 }, () => "vectis-mac") },
+  { labels: ["vectis-mac", "x".repeat(101)] },
+])("oversized labels are stored but never reserve runner capacity", async ({ labels }) => {
+  const { t, webhook, machineId } = await fixture();
+  expect((await webhook({ ...job, labels })).status).toBe(202);
+  expect(await t.run((ctx) => ctx.db.query("githubJobs").unique())).toMatchObject({
+    status: "queued",
+    labels: expect.arrayContaining([unmatchableLabels]),
+  });
+  await t.mutation(internal.runnerDemand.forMachine, { machineId });
+  expect(await t.run((ctx) => ctx.db.query("runnerDemands").collect())).toHaveLength(0);
+  expect(await t.run((ctx) => ctx.db.query("operations").collect())).toHaveLength(0);
+  await webhook(job, "valid-labels");
+  await t.mutation(internal.runnerDemand.forMachine, { machineId });
+  expect(await t.run((ctx) => ctx.db.query("runnerDemands").collect())).toHaveLength(1);
+});
+
+test("API refresh applies the same bounds and unmatchable label marker", async () => {
+  const { t, device, bindingId, stubApi } = await fixture();
+  stubApi(() =>
+    Response.json({
+      ...job,
+      name: "a".repeat(300),
+      labels: Array.from({ length: 101 }, () => "vectis-mac"),
+    }),
+  );
+  const result = await device.action(api.githubJobs.refresh, { bindingId, jobId: 4 });
+  expect(result.name).toBe("a".repeat(200));
+  expect(result.labels).toContain(unmatchableLabels);
+  expect(await t.run((ctx) => ctx.db.query("githubJobs").collect())).toHaveLength(1);
+});
+
+test.each(["github_unavailable", "github_rate_limited"] as const)(
+  "%s survives a Convex action, relay and local operation storage",
+  async (code) => {
+    const f = await fixture();
+    vi.spyOn(Math, "random").mockReturnValue(0.5);
+    f.stubApi(() =>
+      code === "github_unavailable"
+        ? new Response(null, { status: 502 })
+        : new Response(null, { status: 429, headers: { "retry-after": "60" } }),
+    );
+    transport.action.mockImplementation(async (reference) => {
+      expect(getFunctionName(reference)).toBe("githubJobs:refresh");
+      return f.device.action(api.githubJobs.refresh, { bindingId: f.bindingId, jobId: 4 });
+    });
+    const home = await mkdtemp(join(tmpdir(), "vectis-github-errors-"));
+    const store = new Store(join(home, "state.sqlite"));
+    const relay = startCloudRelay(
+      {
+        deploymentUrl: "https://isolated-test.convex.cloud",
+        machineId: "machine",
+        localId: store.snapshot().machine.id,
+      },
+      new VectisClient({ url: "http://127.0.0.1:1", token: "unused" }),
+      { get: async () => null },
+      () => {},
+      () => {},
+      () => {},
+    );
+    const service = new Service(store, new VmRuntime({ home }), () => relay);
+    try {
+      const operation = service.submit("refresh", {
+        type: "job.refresh",
+        bindingId: f.bindingId,
+        jobId: 4,
+      });
+      await service.drain();
+      await vi.advanceTimersByTimeAsync(4000);
+      expect(store.snapshot().operations.find((entry) => entry.id === operation.id)).toMatchObject({
+        status: "failed",
+        result: { code },
+      });
+    } finally {
+      await service.close();
+      await relay.close();
+      store.close();
+      await rm(home, { recursive: true, force: true });
+    }
+  },
+);
diff --git a/tests/convex/repositories.test.ts b/tests/convex/repositories.test.ts
index a142e4f5..535fff46 100644
--- a/tests/convex/repositories.test.ts
+++ b/tests/convex/repositories.test.ts
@@ -3,6 +3,8 @@ import { afterEach, beforeEach, expect, test, vi } from "vitest";
 import schema from "../../convex/schema.js";
 import { api, internal } from "../../convex/_generated/api.js";
 const modules = {
+  "../../convex/githubRepositories.ts": () => import("../../convex/githubRepositories.js"),
+  "../../convex/purge.ts": () => import("../../convex/purge.js"),
   "../../convex/repositoryBindings.ts": () => import("../../convex/repositoryBindings.js"),
   "../../convex/machines.ts": () => import("../../convex/machines.js"),
   "../../convex/_generated/server.js": () => import("../../convex/_generated/server.js"),
@@ -32,6 +34,38 @@ async function setup() {
   );
   return { t, owner, machineId, accountId };
 }
+
+test("authorized readiness carries the current binding cache setting", async () => {
+  const { t, machineId, accountId } = await setup();
+  const bindingId = await t.mutation(internal.repositoryBindings.save, {
+    owner: identity.tokenIdentifier,
+    machineId,
+    accountId,
+    repositoryId: 42,
+    repositoryName: "sandbox",
+    installationId: 81,
+    environmentId: "linux",
+  });
+  const machine = t.withIdentity({
+    issuer: "https://machine.test",
+    subject: machineId,
+    credentialVersion: 0,
+  });
+  expect(
+    (await machine.action(api.githubRepositories.readiness, { input: { bindingId } }))
+      .cacheVolumeEnabled,
+  ).toBe(false);
+  await machine.mutation(api.repositoryBindings.setCacheVolume, { bindingId, enabled: true });
+  expect(
+    (await machine.action(api.githubRepositories.readiness, { input: { bindingId } }))
+      .cacheVolumeEnabled,
+  ).toBe(true);
+  await machine.mutation(api.repositoryBindings.setCacheVolume, { bindingId, enabled: false });
+  expect(
+    (await machine.action(api.githubRepositories.readiness, { input: { bindingId } }))
+      .cacheVolumeEnabled,
+  ).toBe(false);
+});
 test("bindings deduplicate and disappear from machine admission when disabled", async () => {
   const { t, owner, machineId, accountId } = await setup();
   const args = {
@@ -55,10 +89,12 @@ test("bindings deduplicate and disappear from machine admission when disabled",
     {
       id,
       repositoryId: 42,
+      installationId: 81,
       repositoryName: "owner/sandbox",
       environmentId: "linux",
       runsOn: "vectis-linux",
       automatic: false,
+      capacityMode: "demand",
     },
   ]);
   await machine.mutation(api.repositoryBindings.setAutomatic, { bindingId: id, enabled: true });
diff --git a/tests/convex/runControl.test.ts b/tests/convex/runControl.test.ts
index 6a25b1c9..70eefe6f 100644
--- a/tests/convex/runControl.test.ts
+++ b/tests/convex/runControl.test.ts
@@ -541,7 +541,7 @@ test("remote replay after a lost local response and lost local database still PO
   const local = {
     submit: async (command: Parameters<Service["submit"]>[1], key: string) =>
       service.submit(key, command),
-    status: async () => service.snapshot(),
+    operationByKey: async (key: string) => store.operationByKey(key),
   };
   const signal = new AbortController().signal;
   try {
diff --git a/tests/convex/runnerDemand.test.ts b/tests/convex/runnerDemand.test.ts
index f4ababba..89578e4d 100644
--- a/tests/convex/runnerDemand.test.ts
+++ b/tests/convex/runnerDemand.test.ts
@@ -77,6 +77,7 @@ async function fixture() {
     paused = false,
     runnerIdle = true,
     runnerSlots?: number,
+    environmentSlots?: Array<{ environmentId: string; available: number }>,
   ) => {
     const host = ids.hosts[index];
     if (!host) throw new Error("Missing test host");
@@ -90,6 +91,7 @@ async function fixture() {
         paused,
         runnerIdle,
         ...(runnerSlots === undefined ? {} : { runnerSlots }),
+        ...(environmentSlots === undefined ? {} : { environmentSlots }),
       });
   };
   const operations = () => t.run(async (ctx) => ctx.db.query("operations").collect());
@@ -155,16 +157,45 @@ test("unfinished, cancelled and action-required demand is not retried, and failu
   const retry = (await operations()).find((item) => item._id !== first._id);
   expect(retry?.key).toMatch(/:2$/);
 });
-test("failed and successful retries share the same three attempts", async () => {
+test("successful runners serving other jobs do not consume the three-failure budget", async () => {
   const { t, heartbeat, operations } = await fixture();
-  for (const phase of ["failed", "succeeded", "failed", "failed"] as const) {
+  for (const phase of ["succeeded", "succeeded", "failed", "failed", "failed"] as const) {
     await heartbeat(0);
-    await t.run(async (ctx) => {
-      for (const operation of await ctx.db.query("operations").collect())
-        await ctx.db.patch("operations", operation._id, { phase, updatedAt: Date.now() - 60000 });
-    });
+    const latest = (await operations()).at(-1);
+    if (!latest) throw new Error("Missing attempt");
+    await t.run((ctx) =>
+      ctx.db.patch("operations", latest._id, { phase, updatedAt: Date.now() - 60000 }),
+    );
   }
-  expect(await operations()).toHaveLength(3);
+  await heartbeat(0);
+  expect(await operations()).toHaveLength(5);
+  expect(await t.run((ctx) => ctx.db.query("runnerDemands").unique())).toMatchObject({
+    attempt: 5,
+    failures: 2,
+  });
+});
+
+test("missing cache privileges fail the job demand without spending another automatic attempt", async () => {
+  const { t, heartbeat, operations, jobId } = await fixture();
+  await heartbeat(0);
+  const first = (await operations())[0];
+  if (!first) throw new Error("Missing demand");
+  await t.run(async (ctx) =>
+    ctx.db.patch("operations", first._id, {
+      phase: "failed",
+      updatedAt: Date.now() - 600000,
+      resultJson: JSON.stringify({ status: "failed", code: "cache_volume_requires_guest_sudo" }),
+    }),
+  );
+  await heartbeat(0);
+  await heartbeat(1);
+  await t.run(async (ctx) => ctx.db.patch("githubJobs", jobId, { updatedAt: Date.now() }));
+  await heartbeat(0);
+  expect(await operations()).toHaveLength(1);
+  expect((await operations())[0]?.phase).toBe("failed");
+  expect(await t.run((ctx) => ctx.db.query("runnerDemands").unique())).toMatchObject({
+    attempt: 1,
+  });
 });
 
 test("repository scans are deduplicated across machines and retry on later heartbeats", async () => {
@@ -716,6 +747,9 @@ test("an offline unclaimed request expires and another machine reserves the unch
     resultAvailableLocally: false,
   });
   await heartbeat(1);
+  expect(await operations()).toHaveLength(1);
+  vi.advanceTimersByTime(60000);
+  await heartbeat(1);
   const retry = (await operations()).find((operation) => operation._id !== first._id);
   expect(retry).toMatchObject({ machineId: secondHost.machineId, phase: "accepted" });
   expect(decodeCommand(JSON.parse(retry?.commandJson ?? "{}"))).toMatchObject({
@@ -784,6 +818,7 @@ test("an online request expires at the ten-minute cap and can retry an unchanged
     resultAvailableLocally: false,
   });
   expect(first?.updatedAt).toBe((first?.createdAt ?? 0) + 600000);
+  vi.advanceTimersByTime(60000);
   await heartbeat(1);
   expect(await operations()).toHaveLength(2);
 });
@@ -892,3 +927,182 @@ test("an allowed actor and triggering actor receive automatic capacity", async (
   await heartbeat(0, false, true, 1);
   expect(await operations()).toHaveLength(1);
 });
+
+test("macOS environment slots admit two queued jobs and a freed slot admits the third without spending its attempts", async () => {
+  const { t, heartbeat, operations, hosts } = await fixture();
+  await addJobs(t, 2);
+  await heartbeat(0, false, false, 5, [{ environmentId: "mac", available: 2 }]);
+  expect(await operations()).toHaveLength(2);
+  await heartbeat(0, false, false, 5, [{ environmentId: "mac", available: 2 }]);
+  expect(await operations()).toHaveLength(2);
+  const initial = await t.run((ctx) => ctx.db.query("runnerDemands").collect());
+  expect(initial.map((demand) => demand.attempt)).toEqual([1, 1]);
+  await t.run(async (ctx) => {
+    for (const operation of await ctx.db.query("operations").collect())
+      await ctx.db.patch("operations", operation._id, {
+        phase: "running",
+        updatedAt: Date.now() - 1000,
+      });
+    const job = await ctx.db
+      .query("githubJobs")
+      .withIndex("by_job", (q) => q.eq("installationId", 3).eq("repositoryId", 2).eq("jobId", 4))
+      .unique();
+    if (!job) throw new Error("Missing job");
+    await ctx.db.patch("githubJobs", job._id, { status: "completed" });
+    const first = initial[0];
+    if (!first) throw new Error("Missing demand");
+    await ctx.db.patch("operations", first.operationId, { phase: "succeeded" });
+  });
+  await heartbeat(0, false, false, 5, [{ environmentId: "mac", available: 1 }]);
+  expect(await operations()).toHaveLength(3);
+  const demands = await t.run((ctx) => ctx.db.query("runnerDemands").collect());
+  expect(demands).toHaveLength(3);
+  expect(demands.every((demand) => demand.attempt === 1 && demand.failures === 0)).toBe(true);
+  expect(demands.every((demand) => demand.bindingId === hosts[0]?.bindingId)).toBe(true);
+});
+
+test.each(["accepted", "claimed", "running"] as const)(
+  "%s automatic runners reserve their binding's environment as well as total capacity",
+  async (phase) => {
+    vi.useFakeTimers({ toFake: ["Date"] });
+    const { t, heartbeat, operations } = await fixture();
+    await heartbeat(0, false, false, 5, [{ environmentId: "mac", available: 1 }]);
+    const first = (await operations())[0];
+    if (!first) throw new Error("Missing demand");
+    await addJobs(t, 2);
+    await t.run((ctx) => ctx.db.patch("operations", first._id, { phase, updatedAt: Date.now() }));
+    await heartbeat(0, false, false, 5, [{ environmentId: "mac", available: 1 }]);
+    expect(await operations()).toHaveLength(1);
+  },
+);
+
+test("missing or zero environment capacity blocks admission, while a legacy heartbeat restores scalar scheduling", async () => {
+  const { t, heartbeat, operations } = await fixture();
+  await addJobs(t, 2);
+  await heartbeat(0, false, false, 3, []);
+  await heartbeat(0, false, false, 3, [{ environmentId: "linux", available: 3 }]);
+  await heartbeat(0, false, false, 3, [{ environmentId: "mac", available: 0 }]);
+  expect(await operations()).toHaveLength(0);
+  await heartbeat(0, false, false, 3);
+  expect(await operations()).toHaveLength(3);
+});
+
+test("action-required demand retries on another eligible machine after ten minutes and counts as a failure", async () => {
+  vi.useFakeTimers({ toFake: ["Date"] });
+  const { t, heartbeat, operations, hosts } = await fixture();
+  await heartbeat(0);
+  const first = (await operations())[0];
+  if (!first) throw new Error("Missing demand");
+  await t.run((ctx) =>
+    ctx.db.patch("operations", first._id, { phase: "action_required", updatedAt: Date.now() }),
+  );
+  vi.setSystemTime(Date.now() + 599999);
+  await heartbeat(1);
+  expect(await operations()).toHaveLength(1);
+  vi.setSystemTime(Date.now() + 1);
+  await heartbeat(1);
+  expect(await operations()).toHaveLength(2);
+  expect(await t.run((ctx) => ctx.db.query("runnerDemands").unique())).toMatchObject({
+    attempt: 2,
+    failures: 1,
+    bindingId: hosts[1]?.bindingId,
+  });
+});
+
+test("retained demand whose operation was deleted retries after ten minutes without inventing a failure", async () => {
+  vi.useFakeTimers({ toFake: ["Date"] });
+  const { t, heartbeat, operations } = await fixture();
+  await heartbeat(0);
+  const first = (await operations())[0];
+  if (!first) throw new Error("Missing demand");
+  await t.run((ctx) => ctx.db.delete("operations", first._id));
+  await heartbeat(1);
+  expect(await operations()).toHaveLength(0);
+  vi.setSystemTime(Date.now() + 600000);
+  await heartbeat(1);
+  expect(await operations()).toHaveLength(1);
+  expect(await t.run((ctx) => ctx.db.query("runnerDemands").unique())).toMatchObject({
+    attempt: 2,
+    failures: 0,
+  });
+});
+
+test("successful mismatched jobs still stop after ten total runner attempts", async () => {
+  const { t, heartbeat, operations } = await fixture();
+  for (let attempt = 0; attempt < 11; attempt++) {
+    await heartbeat(0);
+    const latest = (await operations()).at(-1);
+    if (!latest) throw new Error("Missing demand");
+    await t.run((ctx) => ctx.db.patch("operations", latest._id, { phase: "succeeded" }));
+  }
+  expect(await operations()).toHaveLength(10);
+  expect(await t.run((ctx) => ctx.db.query("runnerDemands").unique())).toMatchObject({
+    attempt: 10,
+    failures: 0,
+  });
+});
+
+test("legacy demands without a failure counter keep successful attempts outside the failure budget", async () => {
+  const { t, heartbeat, operations } = await fixture();
+  await heartbeat(0);
+  await t.run(async (ctx) => {
+    const demand = await ctx.db.query("runnerDemands").unique();
+    if (!demand) throw new Error("Missing demand");
+    await ctx.db.patch("runnerDemands", demand._id, { attempt: 3, failures: undefined });
+    await ctx.db.patch("operations", demand.operationId, { phase: "succeeded" });
+  });
+  await heartbeat(0);
+  expect(await operations()).toHaveLength(2);
+  expect(await t.run((ctx) => ctx.db.query("runnerDemands").unique())).toMatchObject({
+    attempt: 4,
+    failures: 0,
+  });
+});
+
+test.each([-1, 17, 1.5, NaN, Infinity])(
+  "heartbeat rejects invalid scalar capacity %s",
+  async (slots) => {
+    const { heartbeat, operations } = await fixture();
+    await expect(heartbeat(0, false, true, slots)).rejects.toThrow("invalid_runner_capacity");
+    expect(await operations()).toHaveLength(0);
+  },
+);
+
+test.each([
+  [{ environmentId: "mac", available: -1 }],
+  [{ environmentId: "mac", available: 17 }],
+  [{ environmentId: "mac", available: 1.5 }],
+  [{ environmentId: "mac", available: NaN }],
+  [{ environmentId: "mac", available: Infinity }],
+  [
+    { environmentId: "mac", available: 1 },
+    { environmentId: "mac", available: 2 },
+  ],
+  Array.from({ length: 101 }, (_, index) => ({ environmentId: `env${index}`, available: 1 })),
+])("heartbeat rejects invalid environment slots %#", async (...slots) => {
+  const { heartbeat, operations } = await fixture();
+  await expect(heartbeat(0, false, true, 5, slots)).rejects.toThrow("invalid_runner_capacity");
+  expect(await operations()).toHaveLength(0);
+});
+
+test("scale set bindings leave queued jobs visible without creating demand operations", async () => {
+  const { t, hosts, heartbeat, operations, jobId } = await fixture();
+  const host = hosts[0];
+  if (!host) throw new Error("Missing host");
+  await t.run((ctx) =>
+    ctx.db.patch("repositoryBindings", host.bindingId, { capacityMode: "scale_set" }),
+  );
+  await heartbeat(0, false, true, 3);
+  expect(await operations()).toEqual([]);
+  expect(await t.run((ctx) => ctx.db.get("githubJobs", jobId))).toMatchObject({ status: "queued" });
+  const device = t.withIdentity({
+    issuer: "https://machine.test",
+    subject: host.machineId,
+    credentialVersion: 0,
+  });
+  expect(await device.query(api.jobs.list, { bindingId: host.bindingId })).toMatchObject([
+    { jobId: 4, status: "queued" },
+  ]);
+  await heartbeat(1, false, true, 1);
+  expect(await operations()).toHaveLength(1);
+});
diff --git a/tests/convex/runnerLeases.test.ts b/tests/convex/runnerLeases.test.ts
index 9859b36f..b0f4d073 100644
--- a/tests/convex/runnerLeases.test.ts
+++ b/tests/convex/runnerLeases.test.ts
@@ -550,3 +550,121 @@ test("a busy runner retains its lease until a later release succeeds", async ()
   });
   expect(await device.query(api.runnerLeases.list, {})).toEqual([]);
 });
+
+test.each([
+  ["push", "main", 600, true],
+  ["schedule", "main", 600, true],
+  ["workflow_dispatch", "main", 600, true],
+  ["pull_request", "main", 600, false],
+  ["pull_request_target", "main", 600, false],
+  ["push", "main", 601, false],
+  ["push", "feature", 600, false],
+  ["unreadable", "main", 600, false],
+  ["access_denied", "main", 600, false],
+  ["malformed", "main", 600, false],
+  ["default_unknown", "main", 600, false],
+] as const)(
+  "prepare cache grant: %s %s head repository %s",
+  async (event, branch, headRepository, expected) => {
+    const { t, device, bindingId, fetch } = await fixture();
+    await t.run(async (ctx) => {
+      await ctx.db.patch("repositoryBindings", bindingId, {
+        cacheVolume: { enabled: true, sizeGiB: 20 },
+      });
+      await ctx.db.insert("githubJobs", {
+        installationId: 81,
+        repositoryId: 600,
+        jobId: 900,
+        runId: 800,
+        runAttempt: 1,
+        name: "Cache job",
+        status: "queued",
+        conclusion: null,
+        labels: ["vectis-mac"],
+        runnerId: 0,
+        runnerName: null,
+        updatedAt: 1,
+      });
+    });
+    const original = fetch.getMockImplementation();
+    fetch.mockImplementation(async (url, init) => {
+      if (url.endsWith("/access_tokens")) {
+        const body = JSON.parse(String(init?.body));
+        return Response.json({
+          token: body.permissions.actions === "read" ? "jobs-token" : "runner-token",
+        });
+      }
+      if (url.endsWith("/generate-jitconfig"))
+        expect(init?.headers).toMatchObject({ Authorization: "Bearer runner-token" });
+      if (
+        url.endsWith("/actions/runs/800") &&
+        !JSON.stringify(init?.headers).includes("Bearer jobs-token")
+      )
+        return new Response(null, { status: 403 });
+      if (url.endsWith("/actions/runs/800"))
+        return event === "unreadable" || event === "access_denied"
+          ? new Response(null, { status: event === "access_denied" ? 403 : 404 })
+          : Response.json({
+              id: 800,
+              run_attempt: 1,
+              event,
+              head_branch: branch,
+              repository: { id: 600 },
+              head_repository: event === "malformed" ? null : { id: headRepository },
+            });
+      const response = await original?.(url, init);
+      if (!response) throw new Error("Missing test response");
+      if (url === "https://api.github.com/repos/owner/sandbox")
+        return Response.json({
+          ...(await response.json()),
+          ...(event === "default_unknown" ? {} : { default_branch: "main" }),
+        });
+      return response;
+    });
+    const grant = await device.action(api.githubRunners.prepare, {
+      bindingId,
+      key: "cache",
+      jobId: 900,
+    });
+    expect(grant).toMatchObject({ state: "ready", cacheWrite: expected });
+    if (grant.state !== "ready") throw new Error("Expected ready grant");
+    expect(grant.access?.cacheRun).toEqual(expected ? { runId: 800, runAttempt: 1 } : undefined);
+    const reason = expected
+      ? undefined
+      : event === "access_denied"
+        ? "metadata_access_denied"
+        : ["unreadable", "malformed", "default_unknown"].includes(event)
+          ? "metadata_unavailable"
+          : headRepository !== 600
+            ? "fork"
+            : branch !== "main"
+              ? "non_default_branch"
+              : "event_not_allowed";
+    expect(grant.cacheWriteReason).toBe(reason);
+    expect(
+      await device.action(api.githubRunners.prepare, { bindingId, key: "cache", jobId: 900 }),
+    ).toEqual(grant);
+  },
+);
+
+test("cache settings are machine owned, validated, and returned by binding discovery", async () => {
+  const { device, owner, bindingId } = await fixture();
+  await expect(
+    owner.mutation(api.repositoryBindings.setCacheVolume, { bindingId, enabled: true }),
+  ).rejects.toThrow();
+  await expect(
+    device.mutation(api.repositoryBindings.setCacheVolume, {
+      bindingId,
+      enabled: true,
+      sizeGiB: 0,
+    }),
+  ).rejects.toThrow();
+  await device.mutation(api.repositoryBindings.setCacheVolume, { bindingId, enabled: true });
+  expect(await device.query(api.repositoryBindings.forMachine, {})).toEqual([
+    expect.objectContaining({ installationId: 81, cacheVolume: { enabled: true, sizeGiB: 20 } }),
+  ]);
+  await device.mutation(api.repositoryBindings.setCacheVolume, { bindingId, enabled: false });
+  expect(await device.query(api.repositoryBindings.forMachine, {})).toEqual([
+    expect.objectContaining({ cacheVolume: { enabled: false, sizeGiB: 20 } }),
+  ]);
+});
diff --git a/tests/convex/scaleSets.test.ts b/tests/convex/scaleSets.test.ts
new file mode 100644
index 00000000..45ce1716
--- /dev/null
+++ b/tests/convex/scaleSets.test.ts
@@ -0,0 +1,736 @@
+import { generateKeyPairSync } from "node:crypto";
+import { convexTest } from "convex-test";
+import { afterEach, expect, test, vi } from "vitest";
+import schema from "../../convex/schema.js";
+import { api, internal } from "../../convex/_generated/api.js";
+import { runnerLabels } from "../../packages/github/src/runner-labels.js";
+import type { Doc } from "../../convex/_generated/dataModel.js";
+
+const modules = {
+  "../../convex/githubScaleSets.ts": () => import("../../convex/githubScaleSets.js"),
+  "../../convex/runnerScaleSets.ts": () => import("../../convex/runnerScaleSets.js"),
+  "../../convex/githubRunners.ts": () => import("../../convex/githubRunners.js"),
+  "../../convex/runnerLeases.ts": () => import("../../convex/runnerLeases.js"),
+  "../../convex/repositoryBindings.ts": () => import("../../convex/repositoryBindings.js"),
+  "../../convex/purge.ts": () => import("../../convex/purge.js"),
+  "../../convex/_generated/server.js": () => import("../../convex/_generated/server.js"),
+};
+const privateKey = generateKeyPairSync("rsa", { modulusLength: 2048 })
+  .privateKey.export({ format: "pem", type: "pkcs8" })
+  .toString();
+const serviceUrl = "https://actions.example.test/tenant/repository/";
+const jwt = (exp: number) =>
+  `header.${Buffer.from(JSON.stringify({ exp })).toString("base64url")}.signature`;
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+  vi.useRealTimers();
+});
+
+async function fixture() {
+  vi.stubEnv("VECTIS_MACHINE_ISSUER", "https://machine.test");
+  vi.stubEnv("CLERK_JWT_ISSUER_DOMAIN", "https://clerk.test");
+  const t = convexTest(schema, modules);
+  const ids = await t.run(async (ctx) => {
+    const accountId = await ctx.db.insert("githubAccounts", {
+      owner: "owner",
+      githubId: 71,
+      login: "owner",
+      installations: [],
+      verifiedAt: 1,
+    });
+    const machineId = await ctx.db.insert("machines", {
+      owner: "owner",
+      localId: "host",
+      name: "Host",
+      createdAt: 1,
+      environments: [
+        { id: "linux", name: "Linux", os: "linux", cpu: 2, memoryMiB: 4096, state: "ready" },
+      ],
+    });
+    const foreignId = await ctx.db.insert("machines", {
+      owner: "owner",
+      localId: "foreign",
+      name: "Foreign",
+      createdAt: 1,
+    });
+    const bindingId = await ctx.db.insert("repositoryBindings", {
+      owner: "owner",
+      accountId,
+      machineId,
+      repositoryId: 600,
+      repositoryName: "sandbox",
+      installationId: 81,
+      environmentId: "linux",
+      enabled: true,
+      automatic: true,
+      verifiedAt: 1,
+    });
+    await ctx.db.insert("githubApps", {
+      appId: 42,
+      slug: "test",
+      ownerId: 71,
+      clientId: "client",
+      privateKey,
+      clientSecret: "test",
+      webhookSecret: "test",
+    });
+    return { accountId, machineId, foreignId, bindingId };
+  });
+  let set:
+    | {
+        id: number;
+        name: string;
+        runnerGroupId: number;
+        labels: Array<{ name: string; type: string }>;
+      }
+    | undefined;
+  let sessionId: string | undefined;
+  let nextSession = 0;
+  let runnerName = "";
+  const queueToken = jwt(Math.floor(Date.now() / 1000) + 3600);
+  const adminToken = jwt(Math.floor(Date.now() / 1000) + 600);
+  const state = {
+    conflict: false,
+    dropLabels: false,
+    failDelete: 0,
+    installationId: 81,
+    repositoryId: 600,
+    onSession: undefined as (() => Promise<unknown>) | undefined,
+    onJit: undefined as (() => Promise<unknown>) | undefined,
+    mismatchedRunner: false,
+    wrongRepositoryRunner: false,
+    failRefresh: 0,
+  };
+  const session = () => ({
+    sessionId,
+    messageQueueUrl: "https://queue.example.test/messages",
+    messageQueueAccessToken: queueToken,
+    statistics: { totalAssignedJobs: 2 },
+  });
+  const fetchMock = vi.fn<typeof fetch>(async (input, init) => {
+    const url = new URL(input instanceof Request ? input.url : input);
+    const path = url.pathname;
+    if (url.hostname === "api.github.com") {
+      if (path.endsWith("/installation"))
+        return Response.json({
+          id: state.installationId,
+          app_id: 42,
+          account: { id: 71, type: "User" },
+          suspended_at: null,
+        });
+      if (path.endsWith("/access_tokens")) return Response.json({ token: "installation-secret" });
+      if (path.endsWith("/fork-pr-workflows-private-repos"))
+        return Response.json({
+          run_workflows_from_fork_pull_requests: false,
+          require_approval_for_fork_pr_workflows: false,
+        });
+      if (path.endsWith("/registration-token"))
+        return Response.json({ token: "registration-secret" }, { status: 201 });
+      if (path === "/actions/runner-registration") {
+        expect(new Headers(init?.headers).get("Authorization")).toBe(
+          "RemoteAuth registration-secret",
+        );
+        return Response.json({ url: serviceUrl, token: adminToken });
+      }
+      if (path.endsWith("/actions/runners/501"))
+        return init?.method === "DELETE"
+          ? new Response(null, { status: 204 })
+          : Response.json({
+              id: 501,
+              name: state.wrongRepositoryRunner ? "foreign" : runnerName,
+              status: "online",
+              busy: false,
+            });
+      if (path === "/repos/owner/sandbox")
+        return Response.json({ id: state.repositoryId, private: true, owner: { id: 71 } });
+    }
+    if (url.hostname !== "actions.example.test")
+      throw new Error(`Unexpected synthetic request ${url.href}`);
+    expect(new Headers(init?.headers).get("Authorization")).toBe(`Bearer ${adminToken}`);
+    expect(init?.redirect).toBe("error");
+    if (path.endsWith("/runnergroups/"))
+      return Response.json({
+        count: 1,
+        value: [{ id: 42, name: "Default", isDefaultGroup: true }],
+      });
+    if (path.endsWith("/runnerscalesets")) {
+      if (init?.method === "POST") {
+        const body: unknown = JSON.parse(String(init.body));
+        if (!body || typeof body !== "object" || !("name" in body) || !("labels" in body))
+          throw new Error("Invalid set request");
+        const labels = runnerLabels("linux", "linux");
+        expect(body.labels).toEqual(
+          [...labels, body.name].map((name) => ({ name, type: "System" })),
+        );
+        set = {
+          id: 17,
+          name: String(body.name),
+          runnerGroupId: 42,
+          labels: [...labels, String(body.name)].map((name) => ({ name, type: "System" })),
+        };
+        return Response.json(set);
+      }
+      return Response.json({ count: set ? 1 : 0, value: set ? [set] : [] });
+    }
+    if (path.endsWith("/runnerscalesets/17")) {
+      if (init?.method === "DELETE") {
+        if (state.failDelete-- > 0) return new Response(null, { status: 503 });
+        set = undefined;
+        sessionId = undefined;
+        return new Response(null, { status: 204 });
+      }
+      return Response.json({
+        ...set,
+        labels: state.dropLabels ? [{ name: set?.name, type: "System" }] : set?.labels,
+      });
+    }
+    if (path.endsWith("/sessions")) {
+      if (state.conflict || sessionId) return new Response(null, { status: 409 });
+      sessionId = `c6400b58-622b-497d-9c97-${String(++nextSession).padStart(12, "0")}`;
+      await state.onSession?.();
+      return Response.json(session());
+    }
+    if (path.includes("/sessions/")) {
+      if (path.split("/").at(-1) !== sessionId) return new Response(null, { status: 404 });
+      if (init?.method === "DELETE") {
+        sessionId = undefined;
+        return new Response(null, { status: 204 });
+      }
+      if (state.failRefresh-- > 0)
+        return new Response("queue-secret admin-secret", { status: 503 });
+      return Response.json(session());
+    }
+    if (path.endsWith("/generatejitconfig")) {
+      const body: { name: string; workFolder: string } = JSON.parse(String(init?.body));
+      runnerName = body.name;
+      expect(body.workFolder).toBe("_work");
+      await state.onJit?.();
+      return Response.json({
+        runner: { id: 501, name: state.mismatchedRunner ? "foreign" : runnerName },
+        encodedJITConfig: "c2VjcmV0",
+      });
+    }
+    throw new Error(`Unexpected synthetic request ${url.href}`);
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  const device = t.withIdentity({
+    issuer: "https://machine.test",
+    subject: ids.machineId,
+    credentialVersion: 0,
+  });
+  const foreign = t.withIdentity({
+    issuer: "https://machine.test",
+    subject: ids.foreignId,
+    credentialVersion: 0,
+  });
+  const owner = t.withIdentity({
+    issuer: "https://clerk.test",
+    subject: "owner",
+    tokenIdentifier: "owner",
+  });
+  const enable = () =>
+    device.mutation(api.repositoryBindings.setCapacityModeForMachine, {
+      bindingId: ids.bindingId,
+      capacityMode: "scale_set",
+    });
+  const open = () => device.action(api.githubScaleSets.open, { bindingId: ids.bindingId });
+  const rows = () => t.run((ctx) => ctx.db.query("runnerScaleSets").collect());
+  const requests = (suffix: string, method?: string) =>
+    fetchMock.mock.calls.filter(([input, init]) => {
+      const url = new URL(input instanceof Request ? input.url : input);
+      return url.pathname.endsWith(suffix) && (method === undefined || init?.method === method);
+    });
+  return {
+    t,
+    ...ids,
+    device,
+    foreign,
+    owner,
+    enable,
+    open,
+    rows,
+    requests,
+    fetchMock,
+    state,
+    queueToken,
+    adminToken,
+  };
+}
+
+test("capacity mode defaults to demand and only the binding's machine can change it", async () => {
+  const f = await fixture();
+  expect(await f.device.query(api.repositoryBindings.forMachine, {})).toMatchObject([
+    { capacityMode: "demand" },
+  ]);
+  const args = { bindingId: f.bindingId, capacityMode: "scale_set" as const };
+  await expect(
+    f.foreign.mutation(api.repositoryBindings.setCapacityModeForMachine, args),
+  ).rejects.toThrow("repository_access_denied");
+  await expect(
+    f.owner.mutation(api.repositoryBindings.setCapacityModeForMachine, args),
+  ).rejects.toThrow("machine_unauthorized");
+  await f.enable();
+  expect(await f.device.query(api.repositoryBindings.forMachine, {})).toMatchObject([
+    { capacityMode: "scale_set" },
+  ]);
+  await f.t.run((ctx) => ctx.db.patch("githubAccounts", f.accountId, { owner: "foreign" }));
+  await expect(f.enable()).rejects.toThrow("repository_access_denied");
+  expect(f.fetchMock).not.toHaveBeenCalled();
+});
+
+test("open verifies custom labels, returns only a queue grant and persists no credentials", async () => {
+  const f = await fixture();
+  await f.enable();
+  const grant = await f.open();
+  expect(grant).toMatchObject({
+    bindingId: f.bindingId,
+    scaleSetId: 17,
+    generation: 1,
+    sessionId: "c6400b58-622b-497d-9c97-000000000001",
+    messageQueueAccessToken: f.queueToken,
+    statistics: { totalAssignedJobs: 2 },
+  });
+  expect(grant.queueTokenExpiresAt).toBeGreaterThan(Date.now());
+  expect(grant.scaleSetName).toBe(`vectis-linux-${f.machineId.slice(0, 8)}`);
+  const rows = await f.rows();
+  expect(rows).toMatchObject([
+    {
+      phase: "active",
+      scaleSetId: 17,
+      generation: 1,
+      sessionId: "c6400b58-622b-497d-9c97-000000000001",
+    },
+  ]);
+  for (const secret of [f.queueToken, f.adminToken, "installation-secret", "registration-secret"])
+    expect(JSON.stringify(rows)).not.toContain(secret);
+  expect(JSON.stringify(grant)).not.toContain(f.adminToken);
+  expect(f.requests("/runnerscalesets", "POST")).toHaveLength(1);
+});
+
+test("second open deletes the stored session, reuses the set and fences old refresh and close", async () => {
+  const f = await fixture();
+  await f.enable();
+  const first = await f.open();
+  const second = await f.open();
+  expect(second).toMatchObject({
+    generation: 2,
+    sessionId: "c6400b58-622b-497d-9c97-000000000002",
+    scaleSetId: first.scaleSetId,
+  });
+  expect(f.requests("/sessions/c6400b58-622b-497d-9c97-000000000001", "DELETE")).toHaveLength(1);
+  expect(f.requests("/runnerscalesets", "POST")).toHaveLength(1);
+  const calls = f.fetchMock.mock.calls.length;
+  for (const action of [api.githubScaleSets.refresh, api.githubScaleSets.close])
+    await expect(
+      f.device.action(action, { bindingId: f.bindingId, generation: first.generation }),
+    ).rejects.toThrow("scale_set_superseded");
+  expect(f.fetchMock).toHaveBeenCalledTimes(calls);
+  expect(
+    await f.device.action(api.githubScaleSets.refresh, {
+      bindingId: f.bindingId,
+      generation: second.generation,
+    }),
+  ).toMatchObject({ generation: 2, sessionId: "c6400b58-622b-497d-9c97-000000000002" });
+  await f.device.action(api.githubScaleSets.close, {
+    bindingId: f.bindingId,
+    generation: second.generation,
+  });
+  await f.device.action(api.githubScaleSets.close, {
+    bindingId: f.bindingId,
+    generation: second.generation,
+  });
+  expect(f.requests("/sessions/c6400b58-622b-497d-9c97-000000000002", "DELETE")).toHaveLength(1);
+  expect(f.requests("/runnerscalesets/17", "DELETE")).toHaveLength(0);
+  expect(await f.rows()).toMatchObject([{ phase: "closed", generation: 2 }]);
+  expect((await f.rows())[0]?.sessionId).toBeUndefined();
+  expect(await f.open()).toMatchObject({ generation: 3 });
+});
+
+test("unknown session conflict is typed and never retried", async () => {
+  const f = await fixture();
+  await f.enable();
+  f.state.conflict = true;
+  await expect(f.open()).rejects.toThrow("scale_set_session_conflict");
+  expect(f.requests("/sessions", "POST")).toHaveLength(1);
+  expect(await f.rows()).toMatchObject([{ phase: "action_required", generation: 1 }]);
+});
+
+test("dropped labels fail honestly before creating a session", async () => {
+  const f = await fixture();
+  await f.enable();
+  f.state.dropLabels = true;
+  await expect(f.open()).rejects.toThrow("scale_set_labels_unsupported");
+  expect(f.requests("/sessions", "POST")).toHaveLength(0);
+});
+
+test("unauthorized, disabled, nonautomatic and demand bindings cannot open", async () => {
+  const f = await fixture();
+  await expect(f.open()).rejects.toThrow("scale_set_disabled");
+  await f.enable();
+  await expect(
+    f.foreign.action(api.githubScaleSets.open, { bindingId: f.bindingId }),
+  ).rejects.toThrow("repository_access_denied");
+  await expect(
+    f.owner.action(api.githubScaleSets.open, { bindingId: f.bindingId }),
+  ).rejects.toThrow("machine_unauthorized");
+  await f.t.run((ctx) => ctx.db.patch("repositoryBindings", f.bindingId, { automatic: false }));
+  await expect(f.open()).rejects.toThrow("automatic_disabled");
+  await f.t.run((ctx) =>
+    ctx.db.patch("repositoryBindings", f.bindingId, { automatic: true, enabled: false }),
+  );
+  await expect(f.open()).rejects.toThrow("repository_access_denied");
+  expect(f.fetchMock).not.toHaveBeenCalled();
+});
+
+test.each(["installationId", "repositoryId"] as const)(
+  "open verifies current %s before scale set effects",
+  async (field) => {
+    const f = await fixture();
+    await f.enable();
+    f.state[field]++;
+    await expect(f.open()).rejects.toThrow(
+      field === "installationId" ? "installation_changed" : "repository_access_denied",
+    );
+    expect(f.requests("/runnerscalesets", "POST")).toHaveLength(0);
+  },
+);
+
+const restricted: NonNullable<Doc<"repositoryBindings">["access"]>[] = [
+  { actors: { ids: [71] }, approval: "automatic" },
+  { actors: "any", approval: "required" },
+];
+test.each(restricted)("restricted policy refuses mode, open and prepare: %j", async (access) => {
+  const f = await fixture();
+  await f.t.run((ctx) => ctx.db.patch("repositoryBindings", f.bindingId, { access }));
+  await expect(f.enable()).rejects.toThrow("scale_set_policy_unsupported");
+  await f.t.run((ctx) =>
+    ctx.db.patch("repositoryBindings", f.bindingId, { capacityMode: "scale_set" }),
+  );
+  await expect(f.open()).rejects.toThrow("scale_set_policy_unsupported");
+  await expect(
+    f.device.action(api.githubRunners.prepare, {
+      bindingId: f.bindingId,
+      key: "restricted",
+      scaleSet: { generation: 1 },
+    }),
+  ).rejects.toThrow("scale_set_policy_unsupported");
+  expect(f.fetchMock).not.toHaveBeenCalled();
+});
+
+test("access cannot become restrictive while scale set mode is enabled", async () => {
+  const f = await fixture();
+  await f.enable();
+  await expect(
+    f.device.mutation(api.repositoryBindings.setAccess, {
+      bindingId: f.bindingId,
+      actors: "any",
+      approval: "required",
+    }),
+  ).rejects.toThrow("scale_set_policy_unsupported");
+});
+
+test.each([false, true])(
+  "scale set JIT (cacheEnabled=%s) preserves lease identity, denies cache writes and cleans up",
+  async (cacheEnabled) => {
+    const f = await fixture();
+    await f.t.run((ctx) =>
+      ctx.db.patch("repositoryBindings", f.bindingId, {
+        cacheVolume: { enabled: cacheEnabled, sizeGiB: 20 },
+      }),
+    );
+    await f.enable();
+    const session = await f.open();
+    const args = {
+      bindingId: f.bindingId,
+      key: "jit",
+      automatic: true,
+      scaleSet: { generation: session.generation },
+    };
+    const grant = await f.device.action(api.githubRunners.prepare, args);
+    expect(grant).toMatchObject({
+      state: "ready",
+      runnerId: 501,
+      encodedConfig: "c2VjcmV0",
+      cacheWrite: false,
+      os: "linux",
+      environmentId: "linux",
+    });
+    expect(await f.device.action(api.githubRunners.prepare, args)).toEqual(grant);
+    expect(f.requests("/generatejitconfig", "POST")).toHaveLength(1);
+    expect(f.requests("/generate-jitconfig", "POST")).toHaveLength(0);
+    expect(await f.t.run((ctx) => ctx.db.query("runnerLeases").unique())).toMatchObject({
+      phase: "ready",
+      runnerId: 501,
+      scaleSet: { generation: 1 },
+      cacheWrite: false,
+    });
+    const lease = await f.t.run((ctx) => ctx.db.query("runnerLeases").unique());
+    expect(lease?.jobId).toBeUndefined();
+    expect(lease?.cacheRun).toBeUndefined();
+    expect(grant).not.toHaveProperty("access.cacheRun");
+    expect(await f.device.action(api.githubRunners.status, { id: grant.id })).toEqual({
+      busy: false,
+      status: "online",
+    });
+    await f.device.action(api.githubRunners.release, { id: grant.id });
+    expect(f.requests("/actions/runners/501", "DELETE")).toHaveLength(1);
+  },
+);
+
+test("stale scale set JIT and job-specific requests are refused before registration", async () => {
+  const f = await fixture();
+  await f.enable();
+  await f.open();
+  await f.open();
+  await expect(
+    f.device.action(api.githubRunners.prepare, {
+      bindingId: f.bindingId,
+      key: "old",
+      scaleSet: { generation: 1 },
+    }),
+  ).rejects.toThrow("scale_set_superseded");
+  await expect(
+    f.device.action(api.githubRunners.prepare, {
+      bindingId: f.bindingId,
+      key: "job",
+      jobId: 4,
+      scaleSet: { generation: 2 },
+    }),
+  ).rejects.toThrow("invalid_runner_request");
+  await expect(
+    f.device.action(api.githubRunners.prepare, {
+      bindingId: f.bindingId,
+      key: "no-generation",
+      automatic: true,
+    }),
+  ).rejects.toThrow("scale_set_generation_required");
+  expect(f.requests("/generatejitconfig", "POST")).toHaveLength(0);
+  expect(await f.t.run((ctx) => ctx.db.query("runnerLeases").collect())).toHaveLength(0);
+});
+
+test("a newer session during JIT fences the grant but preserves runner cleanup", async () => {
+  const f = await fixture();
+  await f.enable();
+  await f.open();
+  f.state.onJit = () => f.open();
+  const grant = await f.device.action(api.githubRunners.prepare, {
+    bindingId: f.bindingId,
+    key: "raced",
+    scaleSet: { generation: 1 },
+  });
+  expect(grant.state).toBe("action_required");
+  expect(await f.t.run((ctx) => ctx.db.query("runnerLeases").unique())).toMatchObject({
+    runnerId: 501,
+    phase: "action_required",
+  });
+  expect(
+    (await f.t.run((ctx) => ctx.db.query("runnerLeases").unique()))?.encodedConfig,
+  ).toBeUndefined();
+  await f.device.action(api.githubRunners.release, { id: grant.id });
+  expect(f.requests("/actions/runners/501", "DELETE")).toHaveLength(1);
+});
+
+test.each(["demand", "disconnect", "disable"] as const)(
+  "%s fences the listener and schedules set cleanup with retries",
+  async (change) => {
+    vi.useFakeTimers();
+    const f = await fixture();
+    await f.enable();
+    const session = await f.open();
+    f.state.failDelete = 1;
+    if (change === "demand")
+      await f.device.mutation(api.repositoryBindings.setCapacityModeForMachine, {
+        bindingId: f.bindingId,
+        capacityMode: "demand",
+      });
+    if (change === "disconnect")
+      await f.device.mutation(api.repositoryBindings.disconnectForMachine, {
+        bindingId: f.bindingId,
+      });
+    if (change === "disable")
+      await f.owner.mutation(api.repositoryBindings.disable, { id: f.bindingId });
+    expect(await f.rows()).toMatchObject([{ phase: "deleting", generation: 2 }]);
+    await expect(
+      f.device.action(api.githubScaleSets.close, {
+        bindingId: f.bindingId,
+        generation: session.generation,
+      }),
+    ).rejects.toThrow("scale_set_superseded");
+    await f.t.finishAllScheduledFunctions(vi.runAllTimers);
+    expect(f.requests("/runnerscalesets/17", "DELETE")).toHaveLength(2);
+    expect(await f.rows()).toMatchObject([{ phase: "closed", generation: 2 }]);
+    expect((await f.rows())[0]?.sessionId).toBeUndefined();
+    expect((await f.rows())[0]?.scaleSetId).toBeUndefined();
+    if (change === "demand") {
+      await f.enable();
+      expect(await f.open()).toMatchObject({ generation: 3 });
+    }
+  },
+);
+
+test("mode change during session creation returns no grant and cleans up remote effects", async () => {
+  vi.useFakeTimers();
+  const f = await fixture();
+  await f.enable();
+  f.state.onSession = () =>
+    f.device.mutation(api.repositoryBindings.setCapacityModeForMachine, {
+      bindingId: f.bindingId,
+      capacityMode: "demand",
+    });
+  await expect(f.open()).rejects.toThrow("scale_set_superseded");
+  await f.t.finishAllScheduledFunctions(vi.runAllTimers);
+  expect(f.requests("/sessions/c6400b58-622b-497d-9c97-000000000001", "DELETE")).toHaveLength(1);
+  expect(f.requests("/runnerscalesets/17", "DELETE")).toHaveLength(1);
+});
+
+test("binding purge retains enough verified metadata to clean up after account removal", async () => {
+  vi.useFakeTimers();
+  const f = await fixture();
+  await f.enable();
+  await f.open();
+  await f.t.mutation(internal.purge.binding, { bindingId: f.bindingId });
+  await f.t.run((ctx) => ctx.db.delete("githubAccounts", f.accountId));
+  await f.t.finishAllScheduledFunctions(vi.runAllTimers);
+  expect(f.requests("/runnerscalesets/17", "DELETE")).toHaveLength(1);
+  expect(await f.rows()).toEqual([]);
+});
+
+test("an in-flight open serializes session effects instead of opening a competing session", async () => {
+  const f = await fixture();
+  await f.enable();
+  f.state.onSession = async () => {
+    await expect(f.open()).rejects.toThrow("scale_set_pending");
+  };
+  expect(await f.open()).toMatchObject({ generation: 1 });
+  expect(f.requests("/sessions", "POST")).toHaveLength(1);
+  expect(await f.rows()).toMatchObject([{ phase: "active", generation: 1 }]);
+});
+
+test("a failed refresh preserves the known session for a current-generation retry", async () => {
+  const f = await fixture();
+  await f.enable();
+  const first = await f.open();
+  f.state.failRefresh = 1;
+  const args = { bindingId: f.bindingId, generation: first.generation };
+  await expect(f.device.action(api.githubScaleSets.refresh, args)).rejects.toThrow(
+    "scale_set_unavailable",
+  );
+  expect(await f.rows()).toMatchObject([{ phase: "action_required", sessionId: first.sessionId }]);
+  expect(await f.device.action(api.githubScaleSets.refresh, args)).toMatchObject({
+    sessionId: first.sessionId,
+  });
+});
+
+test("the scale set runner id must resolve to the same lease in the repository runner API", async () => {
+  const f = await fixture();
+  await f.enable();
+  await f.open();
+  f.state.wrongRepositoryRunner = true;
+  const grant = await f.device.action(api.githubRunners.prepare, {
+    bindingId: f.bindingId,
+    key: "identity",
+    scaleSet: { generation: 1 },
+  });
+  expect(grant.state).toBe("action_required");
+  expect(
+    (await f.t.run((ctx) => ctx.db.query("runnerLeases").unique()))?.encodedConfig,
+  ).toBeUndefined();
+  await expect(f.device.action(api.githubRunners.release, { id: grant.id })).rejects.toThrow(
+    "runner_identity_conflict",
+  );
+  expect(f.requests("/actions/runners/501", "DELETE")).toHaveLength(0);
+});
+
+test("cleanup has a bounded retry budget and a later demand-mode request can retry it", async () => {
+  vi.useFakeTimers();
+  const f = await fixture();
+  await f.enable();
+  await f.open();
+  f.state.failDelete = 8;
+  const args = { bindingId: f.bindingId, capacityMode: "demand" as const };
+  await f.device.mutation(api.repositoryBindings.setCapacityModeForMachine, args);
+  await f.device.mutation(api.repositoryBindings.setCapacityModeForMachine, args);
+  expect(await f.rows()).toMatchObject([{ phase: "deleting", generation: 2 }]);
+  await f.t.finishAllScheduledFunctions(vi.runAllTimers);
+  expect(f.requests("/runnerscalesets/17", "DELETE")).toHaveLength(8);
+  expect(await f.rows()).toMatchObject([{ phase: "action_required", generation: 2 }]);
+  await f.device.mutation(api.repositoryBindings.setCapacityModeForMachine, args);
+  await f.t.finishAllScheduledFunctions(vi.runAllTimers);
+  expect(f.requests("/runnerscalesets/17", "DELETE")).toHaveLength(9);
+  expect(await f.rows()).toMatchObject([{ phase: "closed", generation: 3 }]);
+});
+
+test("JIT remains available while the current session is refreshing", async () => {
+  const f = await fixture();
+  await f.enable();
+  await f.open();
+  await f.device.mutation(internal.runnerScaleSets.begin, {
+    bindingId: f.bindingId,
+    generation: 1,
+    operation: "refresh",
+  });
+  expect(
+    await f.device.action(api.githubRunners.prepare, {
+      bindingId: f.bindingId,
+      key: "refreshing",
+      scaleSet: { generation: 1 },
+    }),
+  ).toMatchObject({ state: "ready" });
+});
+
+test("JIT refuses an existing set whose labels no longer match the binding environment", async () => {
+  const f = await fixture();
+  await f.enable();
+  await f.open();
+  f.state.dropLabels = true;
+  expect(
+    await f.device.action(api.githubRunners.prepare, {
+      bindingId: f.bindingId,
+      key: "labels",
+      scaleSet: { generation: 1 },
+    }),
+  ).toMatchObject({ state: "action_required" });
+  expect(f.requests("/generatejitconfig", "POST")).toHaveLength(0);
+});
+
+test("turning automatic capacity off refuses refresh but still lets the host close its session", async () => {
+  const f = await fixture();
+  await f.enable();
+  const grant = await f.open();
+  await f.device.mutation(api.repositoryBindings.setAutomatic, {
+    bindingId: f.bindingId,
+    enabled: false,
+  });
+  const args = { bindingId: f.bindingId, generation: grant.generation };
+  await expect(f.device.action(api.githubScaleSets.refresh, args)).rejects.toThrow(
+    "automatic_disabled",
+  );
+  await f.device.action(api.githubScaleSets.close, args);
+  expect(await f.rows()).toMatchObject([{ phase: "closed", scaleSetId: 17 }]);
+  expect(f.requests("/runnerscalesets/17", "DELETE")).toHaveLength(0);
+});
+
+test("a late session checkpoint or failure cannot resurrect a closed listener", async () => {
+  const f = await fixture();
+  await f.enable();
+  const grant = await f.open();
+  const row = (await f.rows())[0];
+  if (!row) throw new Error("Missing scale set");
+  const identity = { id: row._id, generation: grant.generation };
+  await f.device.action(api.githubScaleSets.close, {
+    bindingId: f.bindingId,
+    generation: grant.generation,
+  });
+  await expect(
+    f.device.mutation(internal.runnerScaleSets.checkpoint, {
+      ...identity,
+      sessionId: grant.sessionId,
+      phase: "active",
+    }),
+  ).rejects.toThrow("scale_set_superseded");
+  await f.t.mutation(internal.runnerScaleSets.failed, identity);
+  expect(await f.rows()).toMatchObject([{ phase: "closed", generation: grant.generation }]);
+  expect((await f.rows())[0]?.sessionId).toBeUndefined();
+});