|
| 1 | +# Cloud handoff acceptance |
| 2 | + |
| 3 | +`python3 scripts/test_cloud_acceptance.py --binary PATH --repeat 2` is the |
| 4 | +Linux acceptance entry point. It runs the CLI, agent, credentials and TUI layers |
| 5 | +against the supplied executable, twice with fresh fixture directories. It is a |
| 6 | +regression gate, not evidence that a managed cloud service or live login works. |
| 7 | +A workflow definition or successful build alone is not an acceptance result. |
| 8 | + |
| 9 | +## What runs |
| 10 | + |
| 11 | +| Layer | Mechanism and assertions | |
| 12 | +| --- | --- | |
| 13 | +| `cli` | `scripts/test_cloud_move_e2e.sh`: real cloud move/return commands and daemons, with a local transport script into a **bubblewrap** filesystem sandbox instead of SSH. Exercises dry run, repository/index/untracked state, session and todo transfer, ownership fencing, round-trip merge and conflict handling. | |
| 14 | +| `agent` | `scripts/test_cloud_move_agent_e2e.sh`: real agent turns before move, in the bubblewrap destination and after return. Checks conversation continuity, cloud notice in provider context and refusal to run the away local copy. Transport is local, not SSH. | |
| 15 | +| `credentials` | `tests/test_cloud_credentials.py`: synthetic OpenAI/Claude OAuth and router credentials over local pipes. Checks round trips, all-account transfer, permissions, secret-free archives/diagnostics, stale and expired tokens, dry run, identity/refresh conflicts, ownership rollback, one-way router transfer and failure before transfer with an incompatible remote. No production authentication or refresh endpoint is used. | |
| 16 | +| `tui` | `scripts/cloud_acceptance_tui.py`: the **actual interactive TUI in tmux**, a real loopback OpenSSH server and client, isolated local/cloud homes, real daemons, and a user/mount namespace providing separate repository contents at the same absolute path. No cloud-transport override is used in this layer. | |
| 17 | + |
| 18 | +The agent and TUI use `scripts/fake_openai_server.py`, a deterministic local |
| 19 | +OpenAI-compatible provider. It records requests and can hold/release turns. |
| 20 | +Provider context assertions test the handoff protocol, not model intelligence. |
| 21 | + |
| 22 | +The TUI scenarios are: |
| 23 | + |
| 24 | +- `idle_round_trip`: two cloud/local cycles, cloud and concurrent local files, |
| 25 | + migration epochs and original conversation context. |
| 26 | +- `midturn_auto_poke`: prepare while a provider turn is held, retain local |
| 27 | + ownership until it completes, automatically continue on cloud and transfer todos. |
| 28 | +- `cancel_prepared`: cancel a prepared move and continue locally without migration. |
| 29 | +- `draft_preserved`: an unsent composer draft prevents automatic migration and can |
| 30 | + still be submitted locally. |
| 31 | +- `prepare_outage_retry`: an injected SSH failure during preparation leaves local |
| 32 | + ownership intact, then a retry moves successfully. |
| 33 | +- `transfer_outage_retry`: an SSH failure after preparation preserves local |
| 34 | + ownership and epoch, then a retry moves successfully. |
| 35 | + |
| 36 | +With the current six TUI scenarios, a full `--repeat 2` invocation records 18 |
| 37 | +stage results. Credential test cases are grouped into one stage per repetition. |
| 38 | +The runner continues after a failed stage and returns nonzero if any stage fails. |
| 39 | +Missing tools or failed namespace/bubblewrap probes are **failures, never skips**. |
| 40 | + |
| 41 | +## Linux prerequisites and isolation |
| 42 | + |
| 43 | +Install Python 3, Bash, Git, tmux, OpenSSH client/server, bubblewrap and util-linux |
| 44 | +(`unshare`, `mount`, `timeout`). The TUI fixture invokes `/usr/bin/sshd`; where the |
| 45 | +package installs `/usr/sbin/sshd`, provide the corresponding symlink. OpenSSH also |
| 46 | +needs `/run/sshd`. Package installation and this host setup may need administrator |
| 47 | +privileges. **Do not run the acceptance runner with sudo or as root.** |
| 48 | + |
| 49 | +Unprivileged user and mount namespaces must work. Ubuntu's AppArmor user-namespace |
| 50 | +restriction can block them. The workflow conditionally disables |
| 51 | +`kernel.apparmor_restrict_unprivileged_userns` and enables |
| 52 | +`kernel.unprivileged_userns_clone` only on its disposable GitHub-hosted runner. |
| 53 | +Do not copy that system-wide policy change onto a shared workstation or production |
| 54 | +host. Use a disposable Linux VM with suitable namespace policy instead. |
| 55 | + |
| 56 | +Fixtures allowlist process environments, generate their own SSH keys, use only |
| 57 | +synthetic credentials and keep separate runtime/home directories. They are not |
| 58 | +intended to access your real accounts, shared daemon or managed VM. Never add |
| 59 | +production tokens, account files or SSH keys to the fixtures or workflow. |
| 60 | + |
| 61 | +## Manual use and focused diagnosis |
| 62 | + |
| 63 | +Use an already-built executable, with an absolute path recommended: |
| 64 | + |
| 65 | +```bash |
| 66 | +python3 scripts/test_cloud_acceptance.py \ |
| 67 | + --binary /absolute/path/to/jcode --repeat 2 \ |
| 68 | + --artifacts "$PWD/cloud-acceptance-results" |
| 69 | +``` |
| 70 | + |
| 71 | +`--artifacts` must name a **new** directory. Without it, the runner creates one |
| 72 | +under `JCODE_SCRATCH_DIR`, or the system temporary directory, and prints its path. |
| 73 | +Run a single TUI case or a single lower layer when diagnosing a failure: |
| 74 | + |
| 75 | +```bash |
| 76 | +python3 scripts/test_cloud_acceptance.py --binary /absolute/path/to/jcode \ |
| 77 | + --layers tui --scenario transfer_outage_retry --repeat 1 |
| 78 | +python3 scripts/test_cloud_acceptance.py --binary /absolute/path/to/jcode \ |
| 79 | + --layers credentials --repeat 1 |
| 80 | +``` |
| 81 | + |
| 82 | +Other `--scenario` values are listed above. `--scenario` filters only TUI scenarios, |
| 83 | +so pair it with `--layers tui` for a one-case run. The underlying credential suite |
| 84 | +also supports unittest's individual test selection: |
| 85 | + |
| 86 | +```bash |
| 87 | +python3 tests/test_cloud_credentials.py /absolute/path/to/jcode \ |
| 88 | + CloudCredentials.test_return_conflict_restores_cloud_ownership |
| 89 | +``` |
| 90 | + |
| 91 | +`--timeout` defaults to 240 seconds per CLI, agent or credential stage. TUI waits |
| 92 | +have their own bounded deadlines and are not controlled by that flag. If a run is |
| 93 | +externally killed, inspect the last saved evidence rather than assuming a complete |
| 94 | +report or successful cleanup. |
| 95 | + |
| 96 | +## CI and evidence |
| 97 | + |
| 98 | +`.github/workflows/cloud-acceptance.yml` runs daily at 09:23 UTC, on manual dispatch, |
| 99 | +and on relevant PRs/pushes targeting `main` or `master`. Its intentionally broad |
| 100 | +`src/**`, `crates/**`, `scripts/**` and `tests/**` filters include TUI input/remote |
| 101 | +handling, cloud CLI, transport, credential code and harness changes. Cargo/build |
| 102 | +configuration and this documentation also trigger it. |
| 103 | + |
| 104 | +The workflow follows existing CI conventions: recursive checkout, stable Rust |
| 105 | +with `rust-src`, Rust cache, wrapper disabled and clang/mold linking. It installs |
| 106 | +the repository-pinned justrust client and uses its local CI build path without a |
| 107 | +hosted account, building the locked release `jcode` binary for Linux x86_64. It |
| 108 | +checks module declarations before building. Existing quality CI remains responsible |
| 109 | +for the code-size/test-size and other ratchet budgets, this gate does not replace |
| 110 | +them. Build, acceptance and whole-job limits are 75, 40 and 120 minutes respectively. |
| 111 | + |
| 112 | +The artifact upload runs with `always()`, retaining available evidence for seven |
| 113 | +days, including hidden files. A failure before the runner starts may leave no |
| 114 | +artifact. The bundle includes `report.json`, `junit.xml`, per-stage output logs, |
| 115 | +provider requests, SSH logs, captured TUI `frame*.txt`, and retained fixture homes |
| 116 | +and workspaces. The root evidence directory is mode 0700 locally. Credential-suite |
| 117 | +temporary homes are normally cleaned by unittest, while other fixture homes remain. |
| 118 | +Those homes can contain **synthetic-only credentials and disposable private SSH |
| 119 | +keys**. Artifact retention is deliberate for diagnosis, not an invitation to use |
| 120 | +real secrets. An externally timed-out run may have only partial reports/frames. |
| 121 | + |
| 122 | +## Explicit non-coverage |
| 123 | + |
| 124 | +This gate does not provision, suspend, resume or delete actual managed cloud VMs. |
| 125 | +It does not validate provider availability, production OAuth login/refresh, real |
| 126 | +account authorization, public-network SSH behavior or nondeterministic live model |
| 127 | +responses. Passing it would establish only the isolated layers and assertions |
| 128 | +above. Record actual run results separately, with the tested binary/version and |
| 129 | +retained evidence, before claiming acceptance success. |
0 commit comments