What Problem This Solves

Starting a repository session in the cloud currently requires a Gateway clone and local managed worktree. This change prepares the checkout on the selected cloud or paired node. The Gateway creates a local worktree only when the user chooses Move to Gateway.

Related: #138724. Implements the accepted storage design.

Why This Change Was Made

One repository workspace owns the immutable source baseline and cumulative accepted changes for both OpenClaw and Codex. Editor saves, file/diff reads, publication, Stop, restart, fork, reset, deletion, and Move use that owner. Recovery files remain distinct from Git publication membership, including ignored files, intent-to-add additions, and cached removals.

There is no feature-owned SQLite schema-version bump and no older-cloud runtime compatibility path. The accepted additive tables and nullable source column initialize on first use. Main independently advanced to schema 16 in Workshop #135528; this PR preserves 16. Existing local-worktree data and general database safety remain covered.

Publication binds to the admitted session lifecycle and current account authority; reset or disconnected authority cannot authorize another GitHub effect. Receipt bindings commit atomically, and unbound pending receipts fail closed. Move verifies remote identity/ancestry, restores accepted bytes, and aligns the fresh local HEAD/index with the recorded publication tip. The next local edit can extend the same PR, repairing a reproduced non-fast-forward handoff without adding stored fields. Workspace reconciliation and teardown wait for physical operations to drain.

User Impact

New Session accepts a repository, optional ref, and remote destination; selection survives retry/reload and the initial prompt waits for active placement. Existing Gateway-folder sessions keep their managed-worktree behavior. Creation avoids local clone work; cold machine bootstrap remains expensive, and no baseline-backed end-to-end speedup is claimed.

Update paired node hosts or reprovision cloud nodes alongside worker bundles: hosts without drain acknowledgement remain fenced. Managed node connections are required; SSH-only carriers are rejected. Checkpoints retain changed contents/manifests, not full Git history, merge stages, or partial staging. Review conflict-marker bytes after recovery. A pinned commit must remain fetchable or available in a verified seed. Unaccepted changes can be lost with a machine; back up retained artifacts with the database. Private fetch uses shared GitHub identity; personal publication credentials stay on the Gateway. Repository setup requires administrator authorization.

Docs: Cloud Sessions, Cloud Workers.

Post-merge main validation

Feature #138900 merged as 140d9e705ea30fc86a4865cf8e38eca31a74b9dd; the UI test teardown repair #140026 merged as fc6345f214b9227131af4e34dcd6d3f543e8d11b. Live main validation then exposed a native-worker packaging regression from #139919: its installed WebSocket loader could not resolve ws/package.json inside a transferred worker. #140071 repairs all three worker transport loaders at the build owner and merged as 8319778f3eb5601bbde4486c645051be0e5c4d7a. Installed Bun transport behavior is preserved; no schema or protocol change was added.

Final main 8319778f3eb5601bbde4486c645051be0e5c4d7a: passed. Full build completed in 3m7.9s. The real paired-Mac native flow created a repository-only session in 52ms, dispatched in 7.867s, completed a write/read turn in 9.203s, accepted an editor save, stopped with retained readback, restored on a new environment in 1.402s, and completed an exact restored read in 8.470s before final Stop. Both canonical environments are destroyed with empty attachments, stopped editor bytes match, pairing is removed, and all owned processes are absent with the port closed. No additional Gateway checkout was created. The Gateway exited naturally with code 0 in 14.406s. This uses separate node HOME/state/workspace on a paired Mac with colocated filesystems.

Managed AWS on preceding post-merge main b72a36a77d1b9fe5b7acb4e94042fddf827d7e40: passed. A new cold worker restored three retained files, completed a real Codex read/write turn, advanced the accepted checkpoint from revision 5 to 6 with a fourth note, and preserved all four files after Stop. Exact transferred node archive/build and the separate worker bundle were verified. Dispatch took 303.997s, the turn 52.616s, and Stop 151.134s. Provider status confirms released/cleanup complete, the canonical environment is destroyed with empty attachments, all task processes are gone, and prior owners are preserved. This result is not relabeled as the final main commit above.

The managed Gateway exited naturally with code 0 in 81.091s. Its original 60-second observation overrun is retained; tracing attributes 78.272s to worker-placement sidecar shutdown, but the exact internal pending owner remains unproven. The original terminal verifier selected the wrong per-agent database; its failed result is preserved beside a corrected terminal receipt using the source-produced shared database path and the original successful provider read. No runtime timeout or database state was changed to make this proof pass. An initial native harness attempt also treated pairing's transient uncertain state as terminal; the same setup subsequently confirmed. The corrected observer requires confirmed delivery, retains intermediate outcomes, and limits any cleanup to that exact task device.

#140071 has a before/after executable relocated-bundle regression with real WebSocket and lazy-transcription traffic, 10 passing focused cases, a clean independent review, and a passing full build/live candidate. Its first CI exposed missing declaration fixture inputs; a three-line correction passed 61 affected tests (two platform-specific skips) and all required CI on exact head 707d1e9e4f5221463dab47dedf022f28b3c97c6e, with 76 jobs passing and no reruns. All three PRs were landed through the native workflow. npm audit remained non-blocking as requested.

Evidence

Candidate f2800e9e5bd0265e35001991c8ddd679163287f2 is a documentation-only child of 3a23b22b93dca0128436c34b4037638b1deb6c1a; all code and tests are unchanged. The final commit moves the cloud-storage section within the database-layout guide to resolve a same-position insertion conflict with main. Its 2,294 bytes, all other document bytes, 48 anchors and 41 links are preserved. Independent P0–P2 review was clean; the configured full anchor audit passed 8,597 links with none broken.

The code parent passed CI run 34021886653, attempt 2, including all native jobs, after one diagnostic retry of the Discord job described below. The documentation child passed required CI run 34025225692, attempt 2: 133 jobs passed, with no failing or pending PR checks. Native preparation supports immutable parent proof for this docs-only child; GitHub’s required head gate remains authoritative.

The current integration preserves main's watched PR-cache ownership: repository sources release prior local Git pins while retaining the current GitHub cache lifetime. Its actual-source regression failed with three listeners retained instead of one, then passed with no local Git probes and complete release on abort. Main's broader browser isolation and line-independent inventory fixes are preserved alongside the additional hash/multiplicity/location assertions. The typography repair is now redundant with main #139663 and was dropped. npm audit is explicitly non-blocking at the maintainer's request; other checks remain required.

Real personal GitHub authority — passed. Normal device authorization, real GitHub writes and independent final ref/tree/PR observations on build c3b47adbaf8ab670530dd06b163abc09248aa5aa:

allowed personal publication                 published, exact accepted tree
wrong-profile publication                   rejected, 0 mutation attempts
interruption + restart + owner confirmation  published, exact accepted tree
wrong-profile confirmation                  rejected, 0 mutation attempts
session reset + stale publication/confirm   session_changed, 0 mutation attempts
local My GitHub disconnect                  rejected, 0 mutation attempts
restart after disconnect                    rejected, 0 mutation attempts
all final-effect audits                     complete

Allowed publication and confirmation each created the expected draft PR through six observed GitHub mutation attempts. Reset preserved the session/checkpoint and rotated lifecycle authority. The test observed the existing 60-second exclusion expiry after forced termination; an earlier premature confirmation correctly returned busy. Another intermediate run lacked the test owner's admin scope; the final run used explicitly configured owner admin and other-profile read/write scopes. Both failed harness runs are retained. This proves the supported isolated trusted-proxy configuration and local connection revocation, not an upstream identity provider or remote OAuth-app revocation. The task connection was disconnected and all test Gateways stopped; the global app grant was retained.

Both runtime handoffs — passed on the same C3 build. Each restored retained A/B files, verified no Gateway project checkout before Move, performed real read/edit turns, published shared commit B, saved an editor checkpoint, moved to Gateway preserving HEAD=B, then published local C with sole parent B to the same draft PR. Actual local/remote trees and bytes matched; ignored recovery files remained available but excluded from publication.

These runs used a paired Mac with separate node HOME/state/workspace and colocated filesystems. Source environments were destroyed, pairings removed, processes joined, and prior test sessions/OAuth history preserved. The local Git argv observer did not intercept the OS Git selected after PATH hardening; ancestry/tree/same-PR effects were verified, but no local argv/force-flag observation is claimed. Repository publication's non-force compare-and-swap was observed separately.

Managed AWS continuation — passed on C3. A fresh cold lease restored two retained files, completed a real Codex read/write turn, accepted a three-file checkpoint, then preserved all three files through normal Stop. Dispatch took 265.725s, the turn 56.955s, and Stop 65.004s. The actual lease's bootstrap descriptor matched one newly created archive and its complete C3 build identity; node-host and worker-bundle identities were verified separately. No additional Gateway checkout or source binding was created; the existing clone from the earlier explicit Move remained unchanged. Provider status confirms released/cleanup complete, the canonical environment is destroyed with no attachments, all owned processes are absent, the port is closed, and preexisting owners/four original children are preserved. No publication or new warm snapshot was requested.

The harness returned exit 1 when its 60s Gateway-exit wait expired. The Gateway subsequently logged clean completion in 86.394s without forced termination; that terminal observation is recorded separately, preserving the failed harness report. Its exact process exit code was not retained after the wait expired. A preceding attempt reached active but its scanner looked in the wrong temp root; the scanner was corrected and rehearsed against the actual producer. Earlier coordinator HTTP 500/Cloudflare 1101 and slow-fork failures remain unexplained. The old 900s deadline belonged to a test driver, not the Gateway; no production timeout increase is included.

Earlier candidate 9298121 additionally completed real creation without any Gateway checkout (146ms), cold dispatch, two Codex turns, cumulative shared publication with exact trees/non-force compare-and-swap, Stop, checkpoint forks, and retained reads after restart.

Database and upgrade: nine independent processes exercised main 16 → feature 16 → main 16 reader → feature reopen, fresh databases, and populated schema 15 through main's actual Workshop migration. All 106 canonical projections, lifecycle/receipt bytes, lazy first use, four forced rollbacks, scoped deletion, integrity and foreign-key checks passed (7755c7d / 94123ce; later feature changes do not alter stored representations). Workshop proof covers empty-table DDL, not skill relocation. An actual pre-feature node rejected Stop while preserving ownership; updating that same device enabled Stop → redispatch → Stop. One empty watchdog needed explicit post-proof cleanup.

Source and automated checks: initial validation covered 901 tests plus 198 publication tests; later overlapping suites cover lifecycle, cumulative checkpoints, restoration, publication membership and Move. Earlier rebases passed 128 and 46 focused cases. The cache integration at 9495c5323d2 passed 124 tests, production and gateway-test types, lint and formatting on main’s updated dependency graph; independent P0–P2 review was clean. The final rebase retained 19 patch-identical commits and dropped only the redundant typography change, whose file is now identical to main; 13 targeted typography/composer cases passed. The reviewed cache files are byte-identical between those two heads. The preceding full build at 3d7fcc1 passed with startup JS 342856B gzip under 350953B; this is not relabeled as a build of the current head. Independent scoped reviews have no accepted actionable code findings. All 85 selected C3 preparation/checkpoint, publication/authority/lease, Move/materialization and repository-lifecycle owner modules are byte-identical through this rebase. Surrounding main changes include stale-worker retirement, resumable provisioning, unknown-conflict preservation, media withdrawal and targeted session reads; C3 is not claimed to be a run of those newer integrations.

CI repair includes canonical checkpoint fixtures; owner-derived history projection defaults; a suppression inventory that tolerates line shifts while independently checking fixture line numbers; a net−1-line startup factory simplification; and an isolated browser hash fixture that explicitly covers absent/present skill mounts. The last fixture reproduced its faulty shared-directory assumption and passed 22 affected/sibling cases; original CI collision timing was not retained. Intermittent UI/macOS timing failures passed unchanged on the next run; no unproven root cause is claimed.

The current CI attempt timed out in two Discord voice-backlog tests introduced on main (#139658). The exact tested merge 706707afc26 passed all 3,587 Discord tests unchanged locally and on Linux with CI’s Node 24.19.0, two-worker setting and compiled worker generation. Host resource and scheduling conditions differ, so no cause or fix is claimed. One exact failed-job rerun passed, and the original failure evidence is retained. No production or test patch was made, and the intermittent cause remains unproven.

Direct Codex remote cwd ownership, pinned fs-safe physical completion, and upstream Git exact-OID fetch contracts were inspected. No Codex protocol change. The offline-seed review concern was rejected using an actual offline-origin regression and Git 2.55 source.

ClawSweeper 07:07 UTC re-review accepts the real personal-authority and both-runtime handoff proof, with no actionable code/security findings. Its remaining rank-up request, the managed continuation result, is now complete above with the original harness-exit limitation retained. Database safety and coordinated node update are covered; conflicts were reconciled against the stated baseline. Sanitized candidate-identified observations above address the requested proof without exposing credentials, private endpoints or personal data. Post-merge main validation is recorded below.

The synthetic UI fixture comparison covers selection/request flow; authenticated lifecycle evidence is separate:

Before: Gateway worktree required	After: checkout on selected runner

Exact baseline accounting: production +9,827/−2,512 (net +7,315); tests/support +7,596/−599 (net +6,997); docs +109/−50; generated/ratchets +148/−4; no lockfile changes. Net counts already cancel moved lines. Growth implements remote preparation, cumulative checkpoint/publication ownership, guarded editor access, and explicit local materialization using existing SQLite, placement, reservation, transfer and worktree owners. File/dispatch/session-store extractions consolidate existing paths.

Named follow-ups: intermittent global-state journal locking with unproven cause; archived publication status offering a confirmation the action rejects; pre-admission plans unable to attest cleanup of an unknown lease ID; partial file-link scanning inside malformed Markdown; managed coordinator failures and the unexplained 86s Gateway-close duration described above. Supporting repairs #139222 and #139286 are merged.

The first documentation-child CI attempt passed all 5,501 UI assertions but reported a late-import environment-teardown error. One unchanged-source UI-job retry passed. The separately reviewed fixture cleanup merged in #140026 (fc6345f214b9227131af4e34dcd6d3f543e8d11b); its exact-head CI passed without retries. Its controlled cleanup probe demonstrated red/green behavior, while the exact intermittent CI exception was not reproduced locally.