Skip to content

docs: retract the win32 launch note's unproven failure mechanism - #38

Merged
whitelonng merged 1 commit into
masterfrom
fix/win32-launch-note-mechanism-correction
Aug 19, 2026
Merged

docs: retract the win32 launch note's unproven failure mechanism#38
whitelonng merged 1 commit into
masterfrom
fix/win32-launch-note-mechanism-correction

Conversation

@whitelonng

Copy link
Copy Markdown
Owner

🤖 Automated. Opened by a DSH agent (deepseek-v4-pro) acting for @whitelonng. Every claim below was verified against this checkout; the Windows-only facts are marked as unverified.

Why

#37's Agent Note (now on master as f637d84a27) asserts a failure mechanism this repository contradicts. I wrote part of that text during the review, so this corrects it in place per .agents/notes/implemented/AGENTS.md ("Rewrite stale facts in place").

The note claimed that node --import tsx/esm <absolute .ts path> fails on Windows with ERR_UNSUPPORTED_ESM_URL_SCHEME, and named packages/sandbox/sandbox-local/src/index.ts:563 as a second, unfixed instance of the same bug.

The counter-evidence

packages/sandbox/sandbox-windows-acl/tests/runner.spec.ts spawns that exact argv:

const runnerEntry = fileURLToPath(new URL('../src/runner.ts', import.meta.url))   // absolute path
spawnSync(process.execPath, ['--import', 'tsx/esm', runnerEntry, ...args])        // same vector
describe.skipIf(!isWin32 || !pwshAvailable())                                     // win32 only

It runs only on Windows, sandbox-windows-acl is absent from vitest.config.ts's Windows exclusion list, and vitest.config.ts:62-68 relies on that suite as the Windows signal that lets src/runner.ts leave the per-file coverage gate — the repository treats that launch as working.

packages/test-support/loader-smoke/src/index.ts:116 launches an absolute path behind a resolved tsx loader in src mode (the default), from .spec.ts files Windows does not exclude.

So neither discriminator the note offered survives:

site loader argument entry Windows
dialog worker, pre-fix import.meta.resolve('tsx/esm')file:// URL absolute reported failure
sandbox-windows-acl/tests/runner.spec.ts:29 'tsx/esm' bare absolute win32-only, load-bearing
loader-smoke/src/index.ts:116 import.meta.resolve('tsx')file:// URL absolute Windows-included spec
sandbox-local/src/index.ts:563 'tsx/esm' bare absolute same form as the load-bearing one

Neither "ESM-only versus full tsx entry" nor "bare specifier versus file:// URL" separates the failing site from the others.

What this changes

  • ## Problem splits into what is established — the symptom, that koffi was never reached, that replacing the launch fixed the dialog on Windows — and the mechanism, now marked untested. The one factor unique to that call site is named: ELECTRON_RUN_AS_NODE=1 over a process.execPath a packaged host points at its own binary.
  • ## Related launch paths turns sandbox-local from a queued fix into counter-evidence. Adopting this launch there remains a reasonable simplification, one that would rewrite the --import tsx/esm assertion in packages/sandbox/sandbox-local/tests/local.spec.ts, but not a bug fix.
  • The first ## Consequences bullet no longer asserts the mechanism, only that the launch no longer depends on how a loader chain resolves the worker path.

The shipped fix is untouched and still justified: plain node over a package-local erasable graph needs no loader chain regardless of which mechanism broke it.

Settling it

pnpm vitest run packages/sandbox/sandbox-windows-acl on a Windows host decides between the two readings. Green means the vector is fine and ELECTRON_RUN_AS_NODE is the prime suspect; red means sandbox-local really does carry the same defect and wants its own fix.

Verification

Documentation only — no source or test changes. Three files: the two note languages and their pairing record.

  • pnpm run doc-sync — 28 passed, 0 failed
  • pre-commit — staged pairing record consistent, whitespace clean

The note asserted that `node --import tsx/esm <absolute .ts path>` fails on
Windows and named `sandbox-local`'s windows-acl runner as a second instance
of the same bug. Two repository sites contradict that.

`packages/sandbox/sandbox-windows-acl/tests/runner.spec.ts` spawns exactly
that argv — `--import tsx/esm` in front of an absolute path — under
`skipIf(!isWin32)`, so it runs only on Windows, and `vitest.config.ts:62-68`
relies on that suite as the Windows signal that lets `runner.ts` leave the
per-file coverage gate. `packages/test-support/loader-smoke/src/index.ts`
launches an absolute path behind a resolved tsx loader in src mode from a
spec the Windows exclusion list does not cover. Neither the ESM-only-versus-
full tsx entry nor the bare-versus-URL loader argument separates the failing
site from those, so both discriminators the note offered are wrong.

State what is established — the symptom, that koffi was never reached, and
that replacing the launch fixed the dialog on Windows — and mark the `e:`
scheme mechanism as untested, naming the one factor unique to the call site:
`ELECTRON_RUN_AS_NODE=1` over a `process.execPath` a packaged host points at
its own binary. The decision stands without it: plain node over a
package-local erasable graph needs no loader chain either way.

`sandbox-local` becomes counter-evidence rather than a queued fix. Adopting
this launch there is a simplification that would rewrite its
`--import tsx/esm` assertion, not a bug fix. Running
`pnpm vitest run packages/sandbox/sandbox-windows-acl` on Windows settles
which reading is right.
@whitelonng
whitelonng merged commit fec48bd into master Aug 19, 2026
1 check passed
@whitelonng
whitelonng deleted the fix/win32-launch-note-mechanism-correction branch August 19, 2026 13:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant