fix(ci): bake the managed runtime identity into cloud images (#13210)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Managed deployments start from the image built by the Cloud
workflow.
> - The managed runtime requests user and group 1001.
> - The image currently builds the node user as 1000.
> - Startup must remap that user, which can walk a large mounted home
directory.
> - This pull request uses the existing Docker build arguments to bake
user and group 1001 into Cloud images.
> - Matching the runtime identity removes that startup work and helps
avoid health-check retries.

## Linked Issues or Issue Description

Refs #13208, #1923, and #7861. Searched open and closed PRs for the
Cloud UID change. The older #7861 addresses build context and volume
ownership repair. This change uses the existing identity arguments in
the Cloud workflow and preserves ownership repair.

**What happened?**

A measured rollout had a container log `Updating node UID to 1001` after
startup. The container stayed at this step for at least 2 minutes 55
seconds before rollback stopped it. The baked node identity was 1000,
while the managed runtime requested 1001. A health check timed out and
the target required a second deployment attempt.

**Expected behavior**

Cloud images should already have the managed runtime identity. A
matching image should skip user and group remapping. Fresh or mismatched
volumes must still receive ownership repair.

**Steps to reproduce**

1. Build the current Cloud image with its default build arguments.
2. Start it with `USER_UID=1001`, `USER_GID=1001`, and a populated home
volume.
3. Observe the startup user remap before the application starts.

**Paperclip version or commit**

`fc06f7f05f42c675be71ff0927b6334405d520ed`

**Deployment mode**

Docker on managed hosts.

## What Changed

- Pass `USER_UID=1001` and `USER_GID=1001` to the Cloud image build.
- Check the pushed digest's baked identity before the entrypoint can
repair it. Then check the normal entrypoint's effective identity and
writable home before publishing the verified full-SHA tag.
- Add a workflow regression and two entrypoint cases for a matching
Cloud identity, including a mismatched volume.
- Document the runtime identity and the first-build cache cost.

## Verification

- Focused workflow and artifact tests: 27 passed.
- Entrypoint tests: 11 passed. Actionlint passed. Full local `pnpm -r
typecheck` passed. Full local `pnpm build` passed. The manual [Cloud
image
build](https://github.com/paperclipai/paperclip/actions/runs/34575473213)
passed on the exact PR head. It checked Sentry, baked and effective
identity, writable home, orphan reaping, and full-SHA publication. The
new identity check took one second. All 30 PR checks passed; the
Storybook workflow was intentionally skipped. Greptile reviewed commit
`114d408f637a0b53e2e2b1339c263779b1e4ae54` at 5/5 with no findings or
open threads.
- The full local suite for the same application source was already run
in #13205. Its macOS general-server phase had 10,471 passes and 70
failures in seven unchanged files. Those failures included missing
Runner fixtures, filesystem errors, timeouts, a port conflict, and a
load-count mismatch. After configuring Cargo and rebuilding fixtures, 37
of 38 native tests passed; one unchanged native-resume assertion still
failed. Linux PR CI passed. This change adds entrypoint tests and does
not change application code.

## Risks

- The first build must rebuild layers that depend on the base image
identity. Later builds can reuse them.
- A future managed runtime identity change must update these build
arguments and checks together.
- The Dockerfile's self-hosted defaults remain 1000. Runtime overrides
and mounted-volume ownership repair remain supported.
- The observed startup delay supports this change, but fleet timing also
includes provider startup, image pull, canary order, and retries. No
fixed end-to-end gain is claimed before a live rollout.

## Model Used

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

## 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 (focused workflow tests;
full-suite limitations are listed above)
- [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/workflows/docker-cloud.yml

@@ -205,6 +205,8 @@ jobs:
           # variant installs from server/package.json's declared version;
           # add another name there when a managed tenant needs it.
           build-args: |
+            USER_UID=1001
+            USER_GID=1001
             CLOUD_BUNDLED_PLUGINS=daytona
             CLOUD_BUNDLED_SERVER_DEPS=@sentry/node
             PAPERCLIP_BUILD_VERSION=${{ steps.build-version.outputs.version }}
@@ -251,6 +253,26 @@ jobs:
           fi
           echo "The pushed image resolves the declared @sentry/node version."
 
+      # Managed hosts run node as 1001:1001. Bake that identity into the image
+      # so usermod does not walk the mounted home on every container start.
+      # Check before the entrypoint can repair a wrongly built identity.
+      - name: Verify cloud runtime user
+        env:
+          IMAGE: ghcr.io/${{ github.repository }}@${{ steps.build-cloud.outputs.digest }}
+        run: |
+          set -euo pipefail
+          docker run --rm --entrypoint sh "$IMAGE" -ec '
+            test "$(id -u node)" = 1001
+            test "$(id -g node)" = 1001
+            test "$USER_UID" = 1001
+            test "$USER_GID" = 1001
+          '
+          docker run --rm -e USER_UID=1001 -e USER_GID=1001 "$IMAGE" sh -ec '
+            test "$(id -u)" = 1001
+            test "$(id -g)" = 1001
+            test -w "$PAPERCLIP_HOME"
+          '
+
       # Verify the independently published cloud image without waiting for
       # the self-hosted manifest job. The Sentry check already pulled it.
       - name: Verify cloud PID 1 reaps orphaned processes

doc/cloud-build-readiness.md

@@ -15,6 +15,16 @@ The `Cloud readiness` workflow starts for every master push. Its versioned
   Registry metadata must match the full commit, and the database package must
   pin the matching shared package.
 
+The Cloud workflow builds the image with `USER_UID=1001` and `USER_GID=1001`,
+matching the managed runtime. This avoids a startup user remap, which can walk
+the mounted home and delay health checks. Before publishing the full-SHA tag,
+the workflow checks the baked identity without running the entrypoint, then
+checks the normal entrypoint's effective user and writable home. Volume ownership
+repair still runs when needed. The Dockerfile defaults remain `1000:1000` for
+self-hosted builds, and runtime identity overrides remain supported. The first
+build with the new identity must rebuild layers that depend on the base image;
+later builds can reuse those layers.
+
 Verification and image building run concurrently, outside the full npm release's
 concurrency group. Different commits have independent groups. Source verification
 is initially duplicated with the normal npm release: this spends existing hosted

scripts/preview-artifacts.test.mjs

@@ -197,6 +197,24 @@ test("cloud builds start per commit and preserve tag promotion dependencies", ()
   assert.ok(reaping < cloud.indexOf("      - name: Publish verified full-SHA cloud tag"));
 });
 
+test("cloud builds bake the managed runtime identity and verify it before publication", () => {
+  const workflow = readFileSync(new URL("../.github/workflows/docker-cloud.yml", import.meta.url), "utf8");
+  const build = workflow.split("      - name: Build and push (cloud)")[1].split("      - name:")[0];
+  assert.match(build, /build-args: \|\n\s+USER_UID=1001\n\s+USER_GID=1001\n/);
+  const verify = workflow.indexOf("      - name: Verify cloud runtime user");
+  assert.ok(verify > workflow.indexOf("      - name: Verify the pushed image resolves the declared Sentry version"));
+  assert.ok(verify < workflow.indexOf("      - name: Publish verified full-SHA cloud tag"));
+  const step = workflow.slice(verify).split("\n      - name:")[0];
+  assert.match(step, /IMAGE: ghcr.io\/\$\{\{ github.repository \}\}@\$\{\{ steps.build-cloud.outputs.digest \}\}/);
+  assert.doesNotMatch(step, /continue-on-error:|if:/);
+  assert.ok(step.indexOf('--entrypoint sh "$IMAGE"') < step.indexOf('-e USER_UID=1001 -e USER_GID=1001'));
+  for (const flag of ["u", "g"]) {
+    assert.ok(step.includes(`test "$(id -${flag} node)" = 1001`));
+    assert.ok(step.includes(`test "$(id -${flag})" = 1001`));
+  }
+  assert.ok(step.includes('test -w "$PAPERCLIP_HOME"'));
+});
+
 test("cloud cache imports are bounded, follow master ancestry, and retain the legacy fallback", () => {
   const workflow = readFileSync(new URL("../.github/workflows/docker-cloud.yml", import.meta.url), "utf8");
   const step = workflow.split("      - name: Select cloud cache ancestry")[1].split("      - name: Setup pnpm")[0];

server/src/__tests__/docker-entrypoint.test.ts

@@ -98,6 +98,18 @@ describe("docker-entrypoint.sh", () => {
     expect(calls).toContain("gosu node echo ENTRYPOINT-CMD-RAN");
   });
 
+  it.each([false, true])("skips remapping a cloud identity while preserving volume repair (mismatch: %s)", async (homeMismatch) => {
+    installStubs({ uid: 0, gid: 0, nodeUid: 1001, nodeGid: 1001, homeMismatch });
+
+    const { stdout, calls } = await runEntrypoint({ USER_UID: "1001", USER_GID: "1001", PAPERCLIP_HOME: stubDir });
+
+    expect(stdout).toContain("ENTRYPOINT-CMD-RAN");
+    expect(calls).not.toContain("usermod");
+    expect(calls).not.toContain("groupmod");
+    expect(calls.includes(`chown -R node:node ${stubDir}`)).toBe(homeMismatch);
+    expect(calls).toContain("gosu node echo ENTRYPOINT-CMD-RAN");
+  });
+
   it("chowns a root-owned home before gosu even with the default UID/GID (fresh volume mount)", async () => {
     // A freshly mounted volume arrives root-owned and shadows the image's
     // build-time chown; with no remap requested the old entrypoint dropped