[Bug] Fresh Windows checkout: bun test fails 94 of 957; the Bun pin and the ACS_OPA_PATH step it needs are declared only in CI and a source comment #110

What is broken

README "Install" says "You need bun" with a link that installs latest, and "Verify" says bun test passes with exactly one skip. On Windows 11 with the Bun that link installs today (1.4.2), the first run fails 94 of 957. 26 of those need an environment variable the README never names, 48 are the Bun version, 3 are line endings, and 17 are Windows path and cleanup defects inside the test suite. None of it is mentioned anywhere a contributor reads while installing.

Where

reference-implementations/agt/README.md (Install, Verify); .github/workflows/reference-implementation.yml:46-53; packages/agt-bridge/src/opa-path.ts:40-45,54-60; test/helpers/config-bundle.ts; test/invariants.test.ts; hosts/opencode/test/acs-plugin.test.ts; packages/guardian/test/server.test.ts; packages/inspector/test/tail-*.test.ts; packages/agt-bridge/test/opa-path.test.ts; test/readme-captures.test.ts; reference-implementations/agt/.gitignore

What the specification says, and what happens instead

Repo @ 7d2dd3c (integration, version.txt 0.1.2). Host: Windows 11 Home 10.0.26200, x64, Git Bash 5.2.37, Git for Windows 2.53.0 with its default core.autocrlf=true. jq 1.8.2, trash-cli 7.2.0 installed via bun add -g as the workflow does. git status --porcelain empty on every run below.

README, "Verify":

bun test              # the whole suite; exactly one test skips, the byte-identity
                      # check, which needs UPSTREAM_BUNDLE

Four runs, same commit:

Run A reproduced exactly on a second invocation. The one skip is test/pin.test.ts, as documented. bun run typecheck exits 0 on every run.

26 failures and the 1 error: the bridge cannot publish the OPA path on win32, and the fix is undocumented. 45 occurrences of this, across 20 files:

error: agt-bridge: found opa at ...\agent-control-specification-opa-win32-x64\bin\opa.exe but could not open the C library (tried libc.so.6, libSystem.B.dylib, libc.musl-x86_64.so.1, libc.musl-aarch64.so.1, libc.so) to publish it to the process environment -- under Bun, process.env writes never reach the native core that spawns opa. Launch this process with ACS_OPA_PATH=... set in its real environment.
      at publishOpaPath (packages\agt-bridge\src\opa-path.ts:83:15)
      at createBridge (packages\agt-bridge\src\index.ts:155:3)

bun install fetched the right binary (agent-control-specification-opa-win32-x64@0.3.1-beta.0; opa.exe version prints 0.70.0). LIBC_CANDIDATES at opa-path.ts:54-60 lists glibc, macOS and two musl spellings and no Windows C runtime, so openLibc() returns undefined and construction throws. The file's own header, lines 40 to 45, names the way through: "ACS_OPA_PATH=<binary> bun test is the escape hatch for such a platform." The README mentions ACS_OPA_PATH once, in a test description under "Failure handling", not under "Install" or "Verify". Setting it in the real environment (the backslash path form works from Git Bash) is run B: 94 becomes 68, the error goes away, and 154 tests that never ran in A now run, because beforeAll hooks that threw now succeed. With it set the Guardian starts, prints the README's four banner lines and answers POST /acs; starting it without the variable was not tried.

3 failures: line endings. No .gitattributes in the tree, so Git for Windows checks out CRLF by default and \r reaches text assertions in test/readme-captures.test.ts and hosts/opencode/test/acs-plugin.test.ts. Run C, an LF checkout at the same commit: 68 becomes 65.

48 failures: the Bun version. The workflow pins 1.3.11 and says why:

      # Pinned to an exact version rather than a moving major. The bridge in
      # packages/agt-bridge/src/opa-path.ts works around a Bun defect measured on a
      # specific version, so the runtime version is part of this tree's contract
      # rather than an implementation detail.

The README says "You need bun". package.json has no engines and no packageManager; there is no .bun-version or .tool-versions. Under 1.4.2 the Claude Code shim exits 0 with empty stdout on every input, which is 48 failures in hosts/claude-code/test/ (Unexpected EOF on the spawned shim's stdout, after exitCode: 0, stderr: "" passes). Under 1.3.11, same clone, bun install reporting no changes, those 48 are 0. That behavior is its own report, #111; here it counts as a cause.

17 failures remain on 1.3.11, all Windows, all in tests, group for group identical between runs C and D.

R2, 8, test/dispositions.test.ts (6) and packages/agt-bridge/test/bridge.test.ts (2). test/helpers/config-bundle.ts writes the fixture manifest as bundle: "${bundleDir}", line 7, quote at column 13. On Windows bundleDir starts C:\Users, and \U inside a YAML double-quoted scalar is the 8-digit Unicode escape:

error: runtime_error:manifest_invalid: failed to parse manifest '\\?\C:\Users\...\acs-config-bundle-2AqP4h\manifest.yaml' as YAML: did not find expected hexadecimal number at line 7 column 18, while parsing a quoted scalar at line 7 column 13

Shipped manifests write bundle: lib unquoted and are not affected. The helper's comment says the absolute path is deliberate, to keep "." from resolving to an empty bundle that allows everything.

R3, 2, test/invariants.test.ts:301 and :382. Expected claude-code/acs-hook.ts, received claude-code\acs-hook.ts, and the filter meant to drop test/ files does not match test\, so 13 files are scanned where 3 are expected. The second is the same separator in a find for opencode/acs-plugin.ts. This is one of the README's "ten gates"; on this host it measures nothing.

R4, 3, packages/inspector/test/tail-audit-log.test.ts:282 and :321, tail-envelope-log.test.ts:54. Two tests put a directory where the log file should be and expect one reported fault; pollErrors stays empty. The third is ENOTEMPTY on rmdirSync of the temp dir at teardown.

R5, 1, test/readme-captures.test.ts:210. The test's capture of the Guardian banner is "". The Guardian's real banner on this host is the README's four lines exactly; the capture, not the banner, is what differs.

R6, 1, hosts/opencode/test/acs-plugin.test.ts:59. new URL("../opencode.hookmap.yaml", import.meta.url).pathname is /C:/Users/... on Windows, and the load-time gate rejects the shipped hookmap it exists to accept.

R7, 1, packages/guardian/test/server.test.ts:857. Expects specification/v0.1.0 in a client-facing error; receives specification\v0.1.0\. The behavior under test, stripping the absolute root, holds.

R8, 1, packages/agt-bridge/test/opa-path.test.ts:79. ENOTEMPTY on rmdirSync at teardown.

One more, not a test. README's install step mkdir -p .claude && cp hosts/claude-code/settings.json .claude/settings.json leaves ?? reference-implementations/agt/.claude/ in git status. .acs/ is in .gitignore; .claude/ is not.

Impact on implementers

Someone following the README on Windows sees 94 failures and no message naming the runtime or the variable. The 26 clear with one line; the 48 clear with the Bun CI already uses; both facts exist in the tree, in a source comment and a workflow comment. Of the 17 that remain, two touch shipped code: R4, where the Inspector does not report a directory sitting where a log file should be, and R7, where a client-facing error carries a backslash path. The rest are fixtures and assertions, the same class as the undeclared trash dependency the workflow already notes at lines 58 to 65.

Also filed: the shim's behavior under 1.4.2, #111.

Prem Methuku

Current Priority Scope

Feeds the runnable Guardian reference implementation