packages/forkhorse-gatekeeper/test/local/README.md

1# Local acceptance fixtures
2
3These helpers use only synthetic accounts, credentials and model responses. The Git
4repository and HTTP Git protocol are real. Nothing contacts a live Core, Artifacts
5account or model provider. Never deploy `offline-worker.js`.
6
7## Kernel S7 and CAS race
8
9From the repository root:
10
11```sh
12pnpm --filter forkhorse-gatekeeper build
13pnpm --filter forkhorse-gatekeeper test:local
14```
15
16The runner creates a disposable bare repository and local Git HTTP server, builds
17required upstream generated modules outside the checkout, executes the native
18workerd test and removes its temporary files. The native test verifies the exact
19remote commit/file after approval and rejection of a real receive-pack CAS race.
20
21## Full pinned OS S7/S9
22
23Run the following from the repository root after frozen installs in both workspaces:
24
25```sh
26pnpm --filter forkhorse-gatekeeper build
27pnpm --filter forkhorse-gatekeeper exec vite build --config vite.run-local.config.ts --mode full-os
28pnpm --filter forkhorse-gatekeeper exec node test/local/prepare-full-os.ts
29```
30
31The last command prints a disposable directory containing an archive of the exact
32reviewed upstream pin and a new fixture extension. None of the archived upstream
33source is changed. In that directory run the unchanged upstream entrypoint with an
34empty HOME and environment; substitute the printed directory for `FIXTURE_DIR`:
35
36```sh
37env -i PATH="$PATH" HOME="FIXTURE_DIR/empty-home" CI=1 WRANGLER_SEND_METRICS=false pnpm run-local --port 4180
38```
39
40This bootstrap downloads registry dependencies. It uses the fixture HOME for local
41OS state and does not load an owner's deployment config or Cloudflare credentials.
42Use separate terminals for the loopback fixture and API driver:
43
44```sh
45pnpm --filter forkhorse-gatekeeper exec node test/local/run.ts --serve
46node packages/forkhorse-gatekeeper/test/local/full-os-client.ts
47```
48
49The server listens only on `127.0.0.1:4181`. The test Worker forwards only its two
50fixed fictional Core/Git origins there. The OS model uses a deterministic local
51Anthropic-protocol endpoint that emits a fixed tool sequence; this is a protocol
52fixture, not inference or an evaluation of model quality. The real OS executes
53`getHead`, `createWorktree`, edits, commit and push submission. The driver asserts
54that Git has not moved before approving the native OS action, then verifies the
55exact remote head and file. It prints `FULL OS ACCEPTANCE` on success.
56
57Restart the fixture server for each full S7 run to obtain fresh Git and model
58sequence state. Stop with SIGTERM or Ctrl-C; the runner cleans its temporary Git
59repository. Stop the OS process and its watcher children after browser checks.
60Do not delete another task's listeners or an owner's data to free these ports.
61
62For S9, sign into `http://localhost:4180` using the synthetic username printed by
63the driver and password `local-fixture-only`. Open the branded app. Its explicitly
64labeled Core snapshots advance every quarter second through the real account and
65OS host limiter. Check section links, wait over one minute, then use Ask an agent:
66the Home composer should contain the project prompt, without sending a message.
67The resource picker should list only `fork-alpha` and enable Add connection after
68selection. No external model is needed for these browser checks.
69
70The API driver validates the actual OS connection/handoff contract. It does not
71claim the entire popup UX was browser-automated. Browser automation could not adopt
72the disowned popup; manual form submission and API redemption were checked
73separately. The popup path remains a manual acceptance item.
74