ci: route approved master cloud builds to AWS (#13243)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Cloud deploys images built from master commits.
> - Cloud image builds share GitHub-hosted capacity with other
workflows.
> - The organization already operates AWS runners through RunsOn Fleet.
> - This pull request allows approved master builds to use a dedicated
cloud Fleet.
> - The benefit is separate build capacity with a quick operator
rollback.

## Linked Issues or Issue Description

Refs #13189, #13192.

**What existing behavior does this improve?**

Placement of the Docker cloud build after a master merge.

**Current behavior**

Every Docker cloud build uses a GitHub-hosted runner. Busy periods delay
the job.

**Proposed behavior**

An operator variable enables the approved cloud Fleet for canonical
master pushes and manual master builds. Other events, refs, and
repositories use GitHub-hosted runners.

## What Changed

- Add a guarded AWS runner selector to the Docker cloud job.
- Keep the existing image cache, verification, and publication steps.
- Test the selector against master, branch, tag, PR, fork, and disabled
contexts.
- Document provisioning requirements, placement checks, and rollback.

## Verification

- 29 focused Node tests pass for routing, readiness, and disk handling.
- The full workflow-script Node suite passes.
- `pnpm -r typecheck` passes locally.
- The pinned PR routing regression suite passes. The first live PR run
assigned 21 jobs to the approved AWS PR group. AWS then reclaimed 16
Spot instances. The failed run is being repeated on GitHub-hosted
runners while the Fleet moves to On-Demand.
- Actionlint passes with existing shellcheck findings excluded (SC2012,
SC2016, SC2129).
- `git diff --check` passes.
- Greptile reports 5/5 on commit
`764d505a41dd2023751c3f361906fa9ea35bf0c6`, with no review threads.
- All 30 current-head CI checks pass, including typecheck, build, all
server/workspace test shards, Runner verification, and browser tests.
Two Storybook checks are intentionally skipped for this change. Run:
https://github.com/paperclipai/paperclip/actions/runs/34630550799
- The broader local test/build sequence is still running. This Mac has
reported failures in unchanged application suites; their complete Linux
CI shards pass. Local targeted workflow tests and typecheck pass.
- Both On-Demand Fleets are deployed and healthy. Live master
cloud-build verification follows the merge.

## Risks

- Missing Fleet capacity or runner-group authorization can leave an AWS
job queued. Disable `AWS_CLOUD_BUILDS_ENABLED` and rerun the workflow to
use GitHub-hosted capacity.
- The runner group must restrict access to this repository and the
master version of `docker-cloud.yml`.
- Docker needs more disk space than the PR Fleet. Provision 120 GiB
disks and retain the free-space check.
- This changes image build placement only. Source verification and
migrator publication remain separate prerequisites.

## Model Used

OpenAI GPT-6 through Codex, with reasoning, tool use, and code
execution. The exact serving model identifier and context-window size
are not exposed by this environment.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

.github/scripts/tests/cloud-runner-routing.test.mjs

@@ -0,0 +1,35 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { runInNewContext } from "node:vm";
+
+const workflow = readFileSync(new URL("../../workflows/docker-cloud.yml", import.meta.url), "utf8");
+// Exercise the workflow's actual boolean expression. Its string comparisons and
+// boolean operators have the same results in JS for these canonical contexts.
+const expression = workflow.match(/^    runs-on: \$\{\{ (.+) \}\}$/m)?.[1];
+assert.ok(expression, "cloud routing must remain an explicit job expression");
+const timeoutExpression = workflow.match(/^    timeout-minutes: \$\{\{ (.+) \}\}$/m)?.[1];
+assert.ok(timeoutExpression, "AWS jobs must finish before the Fleet instance lifetime");
+const fleet = "runs-on/fleet=paperclip-cloud-build-x64/env=public-ci";
+const base = { repository: "paperclipai/paperclip", repository_id: "1170821064", ref: "refs/heads/master", event_name: "push" };
+for (const { name, github = {}, enabled = "true", expected = "ubuntu-latest" } of [
+  { name: "canonical master push", expected: fleet },
+  { name: "manual master build", github: { event_name: "workflow_dispatch" }, expected: fleet },
+  { name: "disabled switch", enabled: "false" },
+  { name: "missing switch", enabled: "" },
+  { name: "invalid switch", enabled: "yes" },
+  { name: "fork", github: { repository: "someone/paperclip", repository_id: "123" } },
+  { name: "wrong repository identity", github: { repository_id: "123" } },
+  { name: "pull request", github: { event_name: "pull_request", ref: "refs/pull/123/merge" } },
+  { name: "privileged PR event", github: { event_name: "pull_request_target" } },
+  { name: "release tag", github: { ref: "refs/tags/v2026.911.0" } },
+  { name: "branch push", github: { ref: "refs/heads/feature" } },
+  { name: "manual branch build", github: { event_name: "workflow_dispatch", ref: "refs/heads/feature" } },
+  { name: "workflow completion event", github: { event_name: "workflow_run" } },
+]) {
+  test(`cloud runner routing: ${name}`, () => {
+    const context = { github: { ...base, ...github }, vars: { AWS_CLOUD_BUILDS_ENABLED: enabled } };
+    assert.equal(runInNewContext(expression, context), expected);
+    assert.equal(runInNewContext(timeoutExpression, context), expected === fleet ? 40 : 60);
+  });
+}

.github/workflows/docker-cloud.yml

@@ -6,7 +6,7 @@ on:
 
 permissions: {}
 
-# Independent SHAs can build immediately on separate existing hosted runners.
+# Independent SHAs can build immediately on separate runners.
 # Repeated requests for the same source serialize without cancelling a build.
 # No mutable canary channel is promoted here; docker.yml owns that operation.
 concurrency:
@@ -15,8 +15,12 @@ concurrency:
 
 jobs:
   build-and-push-cloud:
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
+    # Only canonical master builds can consume the release Fleet. The runner
+    # group must also allow this workflow only at refs/heads/master.
+    # Keep an operator switch for a full-run retry on GitHub-hosted runners.
+    runs-on: ${{ vars.AWS_CLOUD_BUILDS_ENABLED == 'true' && github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && 'runs-on/fleet=paperclip-cloud-build-x64/env=public-ci' || 'ubuntu-latest' }}
+    # Fleet instances expire after 45 minutes, including bootstrap and cleanup.
+    timeout-minutes: ${{ vars.AWS_CLOUD_BUILDS_ENABLED == 'true' && github.repository == 'paperclipai/paperclip' && github.repository_id == '1170821064' && github.ref == 'refs/heads/master' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && 40 || 60 }}
     permissions:
       contents: read
       packages: write

doc/cloud-build-readiness.md

@@ -122,3 +122,26 @@ registry checks can be rerun without deploying or changing mutable npm channels.
 
 When reverting this workflow, restore the master push trigger in
 `docker-cloud.yml` in the same change so master images continue to build.
+
+## AWS cloud build routing
+
+`AWS_CLOUD_BUILDS_ENABLED=true` routes the Docker cloud job to the
+`paperclip-cloud-build-x64` RunsOn Fleet for canonical `paperclipai/paperclip`
+master pushes and manual master runs. Forks, pull requests, and release tags
+retain GitHub-hosted runners. The separate `AWS_CI_ENABLED` and
+`AWS_CI_TRUSTED_USER_IDS` variables control PR routing.
+
+The cloud Fleet uses a separate runner group, `paperclip-cloud-build`, restricted
+to this repository and `.github/workflows/docker-cloud.yml@refs/heads/master`.
+Provision that group and Fleet before enabling the variable. The cloud runners
+need at least 64 GiB free for Docker and the workspace; the initial configuration
+uses 120 GiB disks with the existing 4-vCPU, 16-GiB machine size. AWS jobs have
+a 40-minute workflow timeout so they finish before the 45-minute instance
+lifetime; GitHub-hosted jobs retain their 60-minute timeout. Keep the registry
+cache and all pushed-image verification steps enabled.
+
+To roll back routing, set `AWS_CLOUD_BUILDS_ENABLED=false`, then rerun the cloud
+workflow. Changing the variable does not migrate an already assigned job.
+Check the Actions job's runner name and runner group to verify placement. Record
+queue time, image verification completion, and `Cloud deployable v1` separately;
+source verification and the migrator still run on GitHub-hosted runners.