🧪 composability: clean-checkout battery intermittently fails CH7 — Node resolves acpx without its exports map

[taras]

main went red at 0b73cbb (#437, a Markdown-only change) with a single failing job: composability → "The chain holds from a clean checkout" → test:node (exit 1 after 685.5s) → one subtest:

not ok 7 - CH7: xmd targets --help describes the command rather than failing

The spawned CLI died in module resolution, not in the command under test:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module
 '/tmp/xmd-verify-clean-MVL1Pa/packages/acp/node_modules/acpx/runtime'
 imported from /tmp/xmd-verify-clean-MVL1Pa/packages/acp/mod.ts
Did you mean to import "acpx/dist/runtime.js"?

Run: https://github.com/taras/executable.md/actions/runs/31517357203 (attempt 1). Re-running the failed jobs passed (attempt 2), which restored main and closed #438.

Why this reads as a race, not a regression

• The pin is correct: acpx@0.12.0 ships "./runtime": "./dist/runtime.js" in its exports. Node prints the Did you mean to import "acpx/dist/runtime.js"? hint only on the no-exports fallback path — it found the acpx package directory but could not read its package.json at that moment. Had the manifest been readable, a missing subpath would have been ERR_PACKAGE_PATH_NOT_EXPORTED instead.
• packages/acp/node_modules/acpx in the clone is a symlink into node_modules/.deno/acpx@0.12.0/…, created by deno task setup. dist/runtime.js was visible (the hint found it) while package.json was not — the store entry was readable but incomplete at resolution time.
• The same commit's regular test-node job passed the same suite, and the eight sibling CH subtests — identical runCli spawns in the same failing process — all passed.
• 0b73cbb changed only Markdown (.agents/*.md, AGENTS.md, README.md).

Where the window could come from (unconfirmed)

scripts/lib/verify.ts runs the whole battery — eleven commands — concurrently in the clone, several of them deno task … invocations, and the Deno task runner inspects (and when it judges state stale, relinks) node_modules before acting. A battery command opening that window while a test:node child resolves through the .deno store would produce exactly this signature. Which command was the writer is not established; there is one occurrence so far, under full battery load.

If it recurs

A composability-only red where a spawned CLI fails ERR_MODULE_NOT_FOUND on a store-symlinked npm subpath (with a Did you mean …/dist/….js? hint) is this issue — re-run the failed jobs and add the occurrence here rather than debugging the PR in front of it.

[taras]

Root-caused. The "writer" hypothesis in the issue body is eliminated; the mechanism needs no writer at all.

What was ruled out. In a settled tree, deno startups are no-ops — probed a prepared checkout around deno run …/deno.ts --version: .setup-cache.bin, the store entry's package.json, and the packages/acp/node_modules/acpx symlink keep their inodes and mtimes. A fixture directory with a package.json and a node_modules symlink into a real tree also syncs nothing through the link. And had only the packages/acp/node_modules/acpx symlink been momentarily absent, resolution would have fallen through to the root node_modules/acpx link and succeeded — the error names the nested path, so the resolver found the package and read it as export-less.

The mechanism. Three links, each independently checkable:

1. Node treats a package.json read that fails for any reason as the file being absent — src/node_modules.cc (v22.x): if (ReadFileSync(&package_config.raw_json, path.data()) < 0) { return nullptr; }. EMFILE reads the same as ENOENT, the package resolves without its exports map, and a subpath import produces exactly the observed error, Did you mean "acpx/dist/runtime.js"? hint included (Node does not determine that a file is an ES module when the package.json is in a long path nodejs/node#54304 is the same swallow surfacing from a different trigger).
2. The runner starts every step with a soft descriptor limit of 1024 (hard 65536) — CRITICAL BUG // DefaultLimitNOFILESoft=1024  actions/runner-images#5953.
3. The composability job oversubscribes a four-core runner by design. Node loads module graphs with parallel reads, and the slower each read, the more are open together — the spawned CLI needs well under 200 descriptors on an idle machine, but the peak scales with I/O latency until one open() fails against the limit.

This also fits the lane: Deno and Bun manage their own limits and never showed the signature; the Node lane is where a 1024 ceiling meets a resolver that hides hitting it.

Fix: #440 raises the step's soft limit to the hard one before deno task verify:clean. The upstream half — Node converting transient read failures into silent misresolution instead of an error naming the errno — is worth reporting to nodejs/node separately if wanted.

[taras]

Narrowing this to what is verified. #440 is closed — its premise (descriptor exhaustion specifically) did not survive measurement.

Verified by demonstration. A package.json read failure with a controlled errno reproduces the CH7 signature deterministically. Against a project with acpx@0.12.0 installed:

$ node -e 'import("acpx/runtime").then(m => console.log("ok:", typeof m.DEFAULT_AGENT_NAME))'
ok: string

$ chmod 000 node_modules/.deno/acpx@0.12.0/node_modules/acpx/package.json
$ node -e 'import("acpx/runtime").catch(e => console.log(e.code, "—", e.message.split("\n")[0]))'
ERR_MODULE_NOT_FOUND — Cannot find module '/…/node_modules/acpx/runtime' imported from …

$ chmod 644 node_modules/.deno/acpx@0.12.0/node_modules/acpx/package.json # resolves again

Node treats the failed read as "no package.json" (src/node_modules.cc: if (ReadFileSync(…) < 0) return nullptr; — same code in v22.x, demonstrated on v26.5.1), resolves the package without its exports map, and the subpath import dies as a module-not-found. Any errno lands here — EACCES in the demo; whatever transient error the runner hit in run 31517357203.

Measured. The spawned CLI's true descriptor peak is 185 (1 ms self-sampling via /dev/fd, three runs identical; the tsx wrapper holds 18). Nothing in the lane watches anything. So the process does not need many descriptors, and EMFILE against the runner's 1024 soft limit is not established — which is why #440 was a fix for a non-issue.

Not recoverable. The errno of the one failed read in run 31517357203. Node hides it by design; no log can surface it after the fact.

How a recurrence becomes verifiable. The failed openat is observable in-kernel at the moment it happens. Armed on the runner before deno task verify:clean, this logs every non-ENOENT open failure system-wide with process, path, and errno (to validate on a runner when first armed; not yet exercised there):

sudo bpftrace -e '
tracepoint:syscalls:sys_enter_openat { @p[tid] = str(args->filename); }
tracepoint:syscalls:sys_exit_openat /args->ret < 0 && args->ret != -2/ {
 printf("%s pid=%d errno=%d file=%s\n", comm, pid, -args->ret, @p[tid]);
}
tracepoint:syscalls:sys_exit_openat { delete(@p[tid]); }'

A red with this signature plus that capture names the errno directly. Green runs establish the base rate (expected: zero non-ENOENT failures).

[taras]

Closing as verified-transient.

Resolved: the mechanism is demonstrated (a failed package.json read of any errno makes Node resolve the package without its exports map — repro above), the incident's specific errno is unrecoverable because Node discards it, and the class fix is now filed upstream with a self-contained repro that also shows the silent wrong-file case: nodejs/node#65220.

No repository change ships: the descriptor-limit fix (#440) was closed — the CLI spawn's measured peak is 185 of 1024, so it addressed an unproven cause.

On recurrence: re-run the failed jobs (the signature is a module-not-found on a subpath the installed package does export), then arm the bpftrace failed-openat capture from the comment above so the occurrence names its errno.