Bringup

BottleShip Bring-up

The harness turns bring-up from "poke dbg.* by hand, grep logs, guess from screenshots" into fluent, self-judging automation. It is headless (CLI/CDP) and in-page (window.__BS__.harness). Logic lives in the worker HarnessService; the page facade and CLI are thin transports over one harness_rpc {id,cmd,args}→{id,ok,result|error} contract.

1. Preconditions — harness up

bun tools/harness.ts up

Launches/attaches Chrome with --autoplay-policy=no-user-gesture-required (so audio unlocks with no gesture — no canvas click needed in automation), opens http://localhost:5174/?game=dev, arms log streaming, and probes Vite(:5174 /health) + dev-sidecar(:3001 /health) + Chrome(:9333). Bring the dev servers up first: bun run dev and bun run dev:sidecar (dev:logs still works; start the server BEFORE streaming). bun tools/harness.ts health re-probes.

Parallel bring-up — one tab per agent

Set BS_TAB=<name> (once, for every harness command you run) when another agent is already using the emulator:

BS_TAB=alpha bun tools/harness.ts up     # opens/claims ?game=dev&bs=alpha
BS_TAB=alpha bun tools/harness.ts run my.harness.ts
BS_TAB=alpha bun tools/harness.ts report

The name picks that tab and ONLY that tab, and re-roots this run's evidence under logs/alpha/ — screenshots, run-N.harness.ts journals, dumpSurface/shot({save}) PNGs, and the sidecar's log archive. Never read logs/ at the top level while a session is set; that is somebody else's guest.

Rules: pick a name nobody else is using; never close a tab you did not open; and do not measure — parallel guests share the CPU, so trace refuses to run while a second guest tab is open, and A/B timing needs a single tab. With BS_TAB unset everything behaves exactly as it always has.

2. Drive

A fluent chain (bun tools/harness.ts run <script.harness.ts>, or in the browser console await window.__BS__.harness.chain()....run()):

import { harness } from "../harness";
await harness()
  .streamLogs(["SYSTEM","DDRAW"])
  .openWgb(process.env.WGB ?? "/apps/external-wgb/<id>.wgb") // abs path (streamed off disk) or drop-folder URL — take it from env, don't hardcode local paths
  .waitForEvent("dialogShow")              // event-driven wait (HarnessEventBus)
  .click("Play Game")                      // faithful click by label (global coords)
  .tickFrames(120)                         // wait N presents after the click
  .waitUntil(() => read32(0x6b7bf8) === 0) // predicate evaluated IN the worker (spin-loop games)
  .expectSurfaceNonBlack("primary")        // assertion → aborts + auto fault snapshot on fail
  .state(["surfaces","threads"])
  .run();                                  // → one POJO (also written to logs/harness/)

Skip intros with the bundle's skipVideo. audioGesture() exists only for a manually-opened browser; automation uses the autoplay flag.

Touch/mobile runs the same way — .device('phone-landscape'|'tablet-landscape'|'desktop') then .tap(x,y) / .touchDrag(x0,y0,x1,y1,ms) / .longPress(x,y,ms) / .twoFingerTap(x,y) / .pinch(x,y,scale), all in GUEST px. These execute CDP-side, so keep .device() and its gestures in ONE chain: the emulation override is owned by the CDP session and a separate CLI invocation reconnects without it.

3. Observe

• state([...]) — windows/surfaces/memory/threads/rings/audio/video/modules/cpu/screen as one POJO.
• shot({save}) — PNG of the SCREEN: the frame that reached the canvas, every overlay (video plane, live GDI dialog rects, stats) composited, read from the mirror the present path keeps. shot({source:'layer'}) asks for the presenter's pre-composite game layer instead — the split between "which layer holds the pixels" and "does the composite show it" — and is always labelled composited:false. A capture that cannot see the screen errors out; it never returns a plausible substitute.
• bun tools/harness.ts shot [file] --verify — the browser's own capture of the canvas, plus a cross-check of every worker-side route against it (with the screen's own churn as the noise floor). Run it when a screenshot and the tab seem to disagree.
• screenPixels({x,y,w,h,legend}) — a rect as one string per row, colours quantised to legend; anything outside it reads ? and is tallied, so a chrome-geometry assertion (is the etched line present HERE and absent THERE) cannot pass on pixels it did not recognise.
• screenMark() … screenChangeSince({allow}) — WHICH pixels a transition touched. Mark from a REPAIRED screen: a mark taken over an already-damaged one reports "nothing changed" and the scope assertion then passes on the very bug it exists to catch. outside.changed answers "what repainted that had no business repainting" (an over-wide invalidate, a stamp with nothing erased under it); each allow rect's own count is the positive control, so a run where the click missed fails instead of passing. Both sides are ours, so it is exact — no reference image, nothing to tune.
• textures() + dumpSurface(ptr|'primary') — gallery + per-surface PNG to logs/debug/.
• surfacePixels(sel) / expectSurfaceNonBlack(sel) — cheap liveness from a subsampled readback.
• Dump PNGs preserve ALPHA: an area that looks WHITE in a viewer but BLACK on the canvas is transparent (a=0), not white — sample the RGBA (readSurfaceRGBA) before concluding a color.
• A Win32 FRONT-END presents nothing — its dialogs run before the render device does. Gate on waitForControl("New Game"), never tickFrames, or you wait on presents that never come and it reads exactly like a hang.
• DEAD control (the click does nothing) → hitTest(x,y) before anything else. It prints the window a mouse message is ADDRESSED to next to the control the container hit-test finds, and agrees:false is a routing bug the pixels cannot show: every control we drive ourselves keeps working off the container hit-test, while one the guest SUBCLASSED needs the address and gets nothing. wmTrace then confirms it on the wire (the hwnd on WM_LBUTTONDOWN).
• BLANK control / unpainted dialog → paintTrace("start") … paintTrace("read"). The chain has many links (posted → pump filter → dispatched → BeginPaint/EndPaint+flush → owner-draw chain with its task counts → per-flush child-window exclusions) and the pixels look identical whichever one dropped it; the trace names the link and its reason.