V1 host acceptance

Each supported host is accepted separately. A result on one operating system is never taken as evidence for another. Items not yet run are listed as unresolved, not as supported. Both V1 hosts, macOS and Windows, are accepted. Linux was accepted post-V1, with real OBS capture unverified (see Linux).

How to run acceptance on a host

npm install
npm run typecheck
npm run lint
npm test                                   # normal suite; needs no OBS, Godot, or FFmpeg
CAPPY_REAL_TOOLS=1 npm test                # adds real FFmpeg/ffprobe and headless Godot 4.x
CAPPY_OBS_SMOKE=1 CAPPY_OBS_SCENE=Capture npm test   # adds real OBS capture (OBS running, WebSocket on)
npm run model:check                        # Graphviz (WebAssembly) model validation

On Windows, also run pwsh -NoProfile -File scripts/acceptance/windows-ctrl-c.ps1 from an interactive console.

Then follow getting-started.md end to end with the Godot demo, including step 7 (captures with OBS).

macOS: accepted

Host: macOS 27.0 (arm64), Node.js 24.18.0, Godot 4.7.2, FFmpeg/ffprobe 9.0.1, OBS Studio 32.2.2 (WebSocket 5.7.4). Run 2026-09-25 (America/Chicago).

Windows: accepted

Host: Windows 11 (NT 10.0.26200, x64), Node.js 24.18.0, Godot 4.7.2, FFmpeg/ffprobe 6.0, OBS Studio 32.2.2 (WebSocket 5.7.4). Run 2026-09-25 (America/Chicago).

The OBS run used a separate portable OBS (--portable, WebSocket port 4456) with a color-source test scene, so the host's own OBS configuration was not touched.

Found and fixed during the Windows run: npm on Windows does not create the cappy command shim when the bin target does not exist at install time, so npx cappy failed after npm install followed by npm run build. The bin is now a committed launcher (packages/cli/bin/cappy.js) that loads the build and explains when it is missing.

Post-V1 increments (CAP-011 to CAP-015)

These cover whole-token flag shorthands, cappy clean with retired takes, event-anchored derivatives, and cappy compare. Each host is accepted separately, as for V1. Both hosts ran the Godot demo with real Godot 4.7.2, real FFmpeg, and a real OBS whose Capture scene is a color test source. The masters therefore prove the capture, anchoring, comparison, and cleanup pipeline, not the game's pixels. Cappy never changes OBS scenes.

Run the same flow on a host with a project configured like the one below, then run the commands in order:

"presets": {
  "accept": { "derivatives": [
    { "kind": "mp4", "role": "delivery" },
    { "kind": "clip", "role": "second-bounce", "options": { "start": { "event": "BOUNCE", "offset": -0.5, "where": { "bounce": 2 } }, "end": { "event": "SETTLED", "offset": 0.5 } } },
    { "kind": "still", "role": "settled", "required": false, "options": { "at": { "event": "SETTLED" } } },
    { "kind": "thumbnail", "role": "launch", "options": { "at": { "event": "LAUNCH" } } } ] },
  "replay": { "derivatives": [ { "kind": "thumbnail", "role": "thumb", "options": { "at": { "event": "REPLAY_STARTED" } } } ] },
  "broken": { "derivatives": [ { "kind": "clip", "role": "finale", "options": { "start": { "event": "BOSS_DEFEATED" }, "duration": 1 } } ] }
}

cappy run orb_launch -pa power=4 -p accept   # anchored clip, still, and thumbnail
cappy record -d 3
cappy replay <session> -p replay             # twice
cappy compare <capture-1> <capture-2> -ms 0.95
cappy run orb_launch -p broken               # fails: its anchor never happens
cappy clean --failed -dr                     # then without -dr
cappy clean <comparison> <capture-1> -dr     # then without -dr
cappy replay <session> -p replay -t 1        # refused: take 1 is retired

macOS: accepted

Host: macOS 27.0 (arm64), Node.js 24.18.0, Godot 4.7.2 (windowed), FFmpeg/ffprobe 9.0.1, OBS Studio 32.2.2 (WebSocket 5.7.4). Run 2026-09-25 (America/Chicago) with the final code, after every fix listed on this page.

Found and fixed during this run: an anchored still at SETTLED got no frame. The OBS master reported 2333 ms, but its last decodable frame was at 2267 ms, and seeking past it yields nothing. Stills, thumbnails, and comparison worst-frame stills now read the second of video that ends at the requested time and keep its last frame, the frame at or before that time. A real-FFmpeg regression test with a master whose audio outlasts its video covers this.

Found and fixed after an independent review of CAP-011 to CAP-015, before the final runs on both hosts:

• clean could walk into an item directory, or a whole storage area, that was a link or junction, and remove empty directories outside the managed root. Such items are now refused as symlink and never walked. Only folders named like Cappy IDs count as items.
• Registry updates from concurrent commands could overwrite each other. Every update now holds an exclusive lock file, and a stale lock is broken after 10 s. A test with four concurrent writers keeps all 40 entries and every retired take.
• Option values starting with - (--config -c) were rejected by strict parsing. They now pass as values.
• clean --dry-run could create .cappy/ or a missing storage area. It now opens the workspace read-only.
• Any live command now protects every active session from clean, as SPEC 11.7 says.
• The V1 "OBS disconnects during the scenario" test fired on a fixed 400 ms timer, which made it fragile under Windows' heavier parallel load. It now disconnects just after OBS receives StartRecord.
• The real-FFmpeg "identical masters" comparison test failed once on macOS right after a restart. Its test pattern moves, and the two captures' aligned starts differ by a few milliseconds. When they land on either side of a frame boundary, the frames compare one apart, which scored 0.9984 against the test's 0.999. The test now uses a static pattern, which scores 0.99997 in the same case. Product behavior is unchanged: that one-frame capture jitter is why the gate uses mean SSIM (ADR-015).

Windows: accepted

Host: Windows 11 (NT 10.0.26200, x64), Node.js 24.18.0, Godot 4.7.2 (headless), FFmpeg/ffprobe 6.0, portable OBS Studio 32.2.2 (WebSocket 5.7.4, port 4456, color test scene). Run 2026-09-25 (America/Chicago) over SSH, with the tree synced from macOS.

Found and fixed during the Windows runs:

• An adapter-server connect timeout that fired after the server closed threw an uncaught TypeError while reading the closed socket's address. This was a V1 latent bug that the heavier parallel load exposed. The endpoint is now fixed when the server starts listening.
• Four workspaces opened at once on a fresh root could fail with "not writable": Windows refuses to rename over a file another handle is reading. Creating a missing registry now takes the registry lock too, and registry reads and renames retry briefly on Windows' transient EPERM, EACCES, and EBUSY.
• Under the full parallel real-tool load, several V1 integration tests exceeded Vitest's 5 s default. The suite timeout is now 30 s.
• The real OBS took more than 10 s to identify under that load, so the smoke test's own config now allows obsMs 30 s.

Second post-V1 batch (CAP-017 to CAP-022)

This batch covers every-match derivatives, comparison gates, named builds and compare-builds, timeline export, and presentation for replays. Both hosts ran the Godot demo with a bounces preset (an "every" clip over BOUNCE), the demo's variant as build b, and normal and slowmo (timeScale 0.5, close camera) presets.

macOS: accepted, including a real visual difference

Host: macOS 27.0 (arm64), Node.js 24.18.0, Godot 4.7.2 (windowed), FFmpeg 9.0.1, OBS Studio 32.2.2. Run 2026-09-25 (America/Chicago).

The owner granted OBS Screen Recording permission and approved a separate OBS scene, "Cappy Game", so these captures show the game's own pixels. The existing "Capture" scene was not changed. Cappy switched scenes with obs.switchScene, and the program scene was set back to "Capture" afterwards.

"Cappy Game" holds a macOS Screen Capture source of the main display, cropped to the demo window's content. The game is launched with --position 240,240 --always-on-top, so the window is always in the same place. Application capture of org.godotengine.godot produced no frames of the demo window on this host, which is why display capture is used.

Found during this run: querying the capture source's display list over OBS WebSocket (GetInputPropertiesListPropertyItems for display_uuid) crashed OBS 32.2.2 on macOS. The display UUID was read from macOS instead, and OBS was restarted.

Windows: accepted (pipeline; color-source scene)

Host: Windows 11 (NT 10.0.26200), Node.js 24.18.0, Godot 4.7.2 (headless), FFmpeg 6.0, portable OBS 32.2.2 on port 4456 with its color-source "Capture" scene. Run 2026-09-25 (America/Chicago).

Linux: accepted, OBS unverified

Linux became a supported host post-V1 (ADR-021, amending ADR-003). It is accepted in a throwaway container, rerun with scripts/acceptance/linux-container.sh. The script copies the repository into the container, installs FFmpeg and Godot there, and runs the full validation, so it needs only Docker or OrbStack on the host.

Host: Debian GNU/Linux 12 (bookworm), aarch64 (OrbStack on the owner's Mac, kernel 7.0.11), Node.js 24.21.0, npm 11.19.0, FFmpeg 5.1.9 (Debian), Godot 4.7.2 (official linux.arm64, headless). Run 2026-09-25 (America/Chicago) at CAP-021's code.

No Linux-specific fix was needed.

Uppercut Labs npm distribution preparation (2026-09-28)

This verifies the installed distribution separately from the historical capture acceptance above. No npm package, GitHub release, or tag was published by this migration. The repository was transferred intact to uppercut-labs/cappy and made public after reviewing tracked contents and scanning all prior commits.

The tested @uppercut-labs/cappy@0.1.0 archive contains four files: manifest, README, MIT license, and the executable. Its only runtime dependencies are registry packages ws and zod; no implementation/fixture workspaces ship as dependencies. SHA-256:

276e64cd7a4b6cc1072229f079aba69363103ffa816e2297a4783a70ab25f237

npm run package:check packs the public workspace, installs outside the checkout, and exercises these cases. It can also check a specific artifact with -- --tarball <path>. The Windows cancellation helper allocates a fresh console and enables Ctrl+C handling before launching the installed executable, avoiding SSH's inherited ignore flag. It verifies exit 130, persisted cancelled metadata, and simulator-child cleanup. This is an automated native console-event check; the local/global .cmd launchers are separately verified for normal commands.

The first Windows full suite hit a transient fake-OBS stop timeout under the default parallel load. Running with four workers passed; vitest.config.ts now sets that bound on Windows, without changing product timeouts. No real OBS, Godot, or FFmpeg capture acceptance was rerun for this packaging change. The historical real-tool evidence and Linux OBS limitation remain as recorded above.

GitHub CI on revision 50b5eb1 passed on all three hosted runners. Release preparation retained the tested artifact and skipped publication. The first hosted Windows package check exposed GNU tar's drive-letter parsing under Git Bash; using the archive basename with its directory as the working directory fixed the check.

Remaining limitations

• Real OBS capture on Linux is unverified (see above).
• The visual-regression check with real OBS was verified on macOS only. Windows ran the same flow against a color-source scene.
• The acceptance OBS scenes are color test sources on both hosts, so the comparisons prove the pipeline, not visual differences in the game. Visual scoring against real changes is covered by the real-FFmpeg tests: a changed region lowers SSIM, and the worst frame falls inside it.
• On Windows, compare cannot use an FFmpeg wrapper script (.cmd) when the managed root is on a network share (UNC path), because cmd.exe refuses a UNC working directory. Point tools.ffmpeg at ffmpeg.exe in that case. This is untested on a share.
• The Windows Ctrl+C check is a script, not part of npm test: it must run in an interactive console, because processes started over SSH inherit an "ignore Ctrl+C" attribute that Node does not clear.

Read Markdown