Skip to content

Commit ea1d274

Browse files
committed
ci: add repeatable Linux cloud acceptance gate
1 parent cd8f8c8 commit ea1d274

2 files changed

Lines changed: 262 additions & 0 deletions

File tree

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
name: Cloud Acceptance
2+
3+
on:
4+
schedule:
5+
- cron: '23 9 * * *'
6+
workflow_dispatch:
7+
push:
8+
branches: [main, master]
9+
paths:
10+
- '.github/workflows/cloud-acceptance.yml'
11+
- '.github/workflows/ci.yml'
12+
- '.cargo/**'
13+
- 'Cargo.toml'
14+
- 'Cargo.lock'
15+
- 'build.rs'
16+
- 'src/**'
17+
- 'crates/**'
18+
- 'scripts/**'
19+
- 'tests/**'
20+
- 'docs/cloud-acceptance.md'
21+
pull_request:
22+
branches: [main, master]
23+
paths:
24+
- '.github/workflows/cloud-acceptance.yml'
25+
- '.github/workflows/ci.yml'
26+
- '.cargo/**'
27+
- 'Cargo.toml'
28+
- 'Cargo.lock'
29+
- 'build.rs'
30+
- 'src/**'
31+
- 'crates/**'
32+
- 'scripts/**'
33+
- 'tests/**'
34+
- 'docs/cloud-acceptance.md'
35+
36+
permissions:
37+
contents: read
38+
39+
concurrency:
40+
group: cloud-acceptance-${{ github.ref }}
41+
cancel-in-progress: true
42+
43+
env:
44+
JCODE_CI: '1'
45+
CARGO_BUILD_RUSTC_WRAPPER: ''
46+
CARGO_TERM_COLOR: always
47+
RUSTUP_TOOLCHAIN: stable
48+
JUSTRUST_TOOLCHAIN: system
49+
JUSTRUST_SLOTS: '0'
50+
JUSTRUST_NO_TELEMETRY: '1'
51+
52+
jobs:
53+
acceptance:
54+
name: Linux cloud handoff acceptance
55+
runs-on: ubuntu-24.04
56+
timeout-minutes: 120
57+
steps:
58+
- uses: actions/checkout@v4
59+
with:
60+
submodules: recursive
61+
62+
- uses: dtolnay/rust-toolchain@stable
63+
with:
64+
targets: x86_64-unknown-linux-gnu
65+
components: rust-src
66+
67+
- uses: Swatinem/rust-cache@v2
68+
with:
69+
key: cloud-acceptance-linux-stable
70+
71+
- name: Install build and acceptance prerequisites
72+
shell: bash
73+
run: |
74+
set -euo pipefail
75+
sudo apt-get update -qq
76+
sudo apt-get install -y -qq clang mold tmux openssh-server bubblewrap util-linux python3
77+
# The fixture runs its own unprivileged loopback-only sshd, not the service.
78+
sudo install -d -m 0755 /run/sshd
79+
# cloud_acceptance_tui.py deliberately invokes this exact absolute path.
80+
if [[ ! -e /usr/bin/sshd ]]; then
81+
sudo ln -s /usr/sbin/sshd /usr/bin/sshd
82+
fi
83+
# Ubuntu's AppArmor userns restriction blocks the fixture's unshare/mount.
84+
# Change only this ephemeral hosted runner, never a developer's host.
85+
if [[ -e /proc/sys/kernel/apparmor_restrict_unprivileged_userns ]]; then
86+
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
87+
fi
88+
if [[ -e /proc/sys/kernel/unprivileged_userns_clone ]]; then
89+
sudo sysctl -w kernel.unprivileged_userns_clone=1
90+
fi
91+
92+
- name: Check module declarations resolve
93+
run: python3 scripts/check_module_files.py
94+
95+
- name: Install pinned justrust
96+
run: bash scripts/install_justrust_ci.sh
97+
98+
- name: Build acceptance binary
99+
timeout-minutes: 75
100+
shell: bash
101+
run: |
102+
set -euo pipefail
103+
# Match Linux CI's stable toolchain and clang/mold release build.
104+
cat > .cargo/config.toml <<'EOF'
105+
[target.x86_64-unknown-linux-gnu]
106+
linker = "clang"
107+
rustflags = ["-C", "link-arg=-fuse-ld=mold"]
108+
EOF
109+
RUSTC="$(rustup which rustc)"
110+
export RUSTC
111+
# Hosted CI has no justrust account. Use its supported local CI path.
112+
justrust build --local --locked --release --target x86_64-unknown-linux-gnu -p jcode --bin jcode
113+
114+
- name: Run all acceptance layers twice
115+
timeout-minutes: 40
116+
shell: bash
117+
run: |
118+
set -euo pipefail
119+
test "$(id -u)" -ne 0
120+
python3 scripts/test_cloud_acceptance.py \
121+
--binary "$GITHUB_WORKSPACE/target/x86_64-unknown-linux-gnu/release/jcode" \
122+
--repeat 2 \
123+
--artifacts "$RUNNER_TEMP/cloud-acceptance"
124+
125+
- name: Retain acceptance evidence even on failure
126+
if: always()
127+
uses: actions/upload-artifact@v4
128+
with:
129+
name: cloud-acceptance-${{ github.run_id }}-${{ github.run_attempt }}
130+
path: ${{ runner.temp }}/cloud-acceptance/
131+
include-hidden-files: true
132+
if-no-files-found: warn
133+
retention-days: 7

‎docs/cloud-acceptance.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
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

Comments
 (0)