choiyounggi · choiyounggi · Sep 28, 2026
@@ -19,7 +19,7 @@ follow the cross-pointers in their index or take the next matching seeded domain
 | [qa](wiki/qa/index.md) | **seeded** | Release-quality process: release gates, regression scoping, bug reports, severity/priority triage, evidence for completion claims, the agent-tool parity gate for a web UI release, acting on code-review feedback, adversarial review of high-risk diffs, exploratory testing (guarded-path coverage, override matrices), scope-purity gates, sourcing deliverable documents from generated artifacts, verifying the quantitative claims in a document before publishing it, a documented claim about a third-party tool's side effects, an obligation row in a tier/policy table that another contract also pins, rationale prose left behind by a config-value change, automated verification of document deliverables (spec/RFC gates), an aging detector for model-coupled agent guidance, capturing an app's own screen content without Screen Recording permission (writing automated test code → testing) |
 | [debugging](wiki/debugging/index.md) | **seeded** | Diagnosing a failure — finding what is wrong and why: reproducing, bisection, hypothesis testing, traces/logs, intermittent failures (fixing the diagnosed fault → its owning domain) |
 | [security](wiki/security/index.md) | **seeded** | Trust-boundary decisions: input validation, session-vs-token auth choice, per-resource authorization (IDOR), secrets hygiene (including ciphertext orphaned by a regenerated encryption key), dependency trust, PII handling, in-session agent tool exposure (prompt-injection blast radius), the author identity a commit publishes to a public repository, host-compromise triage / incident response (verifying assumed security agents, identifying masquerading processes) (XSS rendering → frontend; CI secrets → infrastructure; JWT implementation → backend/frontend auth) |
-| [platforms](wiki/platforms/index.md) | **seeded** | OS-level differences breaking code across macOS/Linux/Windows: shell portability, BSD-vs-GNU CLI, filesystem case/line endings, Unicode normalization in text/file-name matching, commands inspected before execution, permission deny rules for bypass-mode agent workers, background services/cron, invoking prompt-capable CLIs non-interactively, toolchain version pinning |
+| [platforms](wiki/platforms/index.md) | **seeded** | OS-level differences breaking code across macOS/Linux/Windows: shell portability, BSD-vs-GNU CLI, filesystem case/line endings, Unicode normalization in text/file-name matching, commands inspected before execution, permission deny rules for bypass-mode agent workers, background services/cron, invoking prompt-capable CLIs non-interactively, toolchain version pinning, a native addon left without its `.node` binary after a bun install (blocked vs failed lifecycle script) |
 | [mobile](wiki/mobile/index.md) | **seeded** | App-side iOS/Android/cross-platform: process death/state survival, offline-first sync, mobile-network calls, store rollout/hotfix strategy, startup time, modal presentation (several sheets/covers on one host, screen-level error sheets) |
 
 All ten domains are seeded. New categories grow via `skills/wiki-ingest/SKILL.md`.
@@ -208,3 +208,5 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
 ## [2026-09-28] ingest | testing-strategy-agent-tool-shared-handler-tests — a UI action that is also a registered tool is tested once at the shared function plus two entry-point tests per tool (Registration incl. AbortSignal teardown, Wiring via spy) against a `document.modelContext` stub; a bug fix that changes the handler's contract changes the `inputSchema` assertion in the same commit; one DevTools Run-tool pass per release.
 
 ## [2026-09-28] revise | WebMCP adopted as the development standard (owner decision 2026-09-28): frontend/agent-interfaces/agent-facing-tool-surfaces trigger widened to any new or changed user action in a web UI + bug-fix and exclusion-list edge cases; AGENTS.md routing step 7 gains a web-UI-action row → frontend agent-interfaces then qa parity gate; INDEX.md frontend/qa/testing route lines and the frontend/qa/testing domain indexes updated; related links added both ways (release-gates, cross-layer-effect-tests, in-session-tool-exposure). The standard keeps the human UI primary and the tool layer additive (CG draft; Chrome origin trial + ChatGPT desktop runtimes).
+
+## [2026-09-28] ingest | platforms-toolchains-native-addon-binary-missing-after-bun-install — a native dependency has no `.node` after `bun install`: read bun's notice (`Blocked N postinstall` = script skipped → `bun pm trust`; `error: install script from "<pkg>" exited with 1` = script ran and failed → fix the node-gyp prerequisite and rebuild under the runtime the launcher uses); `bun pm untrusted` distinguishes the two after the fact; a set `trustedDependencies` replaces the default allowlist, so list default-listed packages too.
@@ -12,7 +12,7 @@ sources:
   - https://www.sudo.ws/docs/man/sudoers.man/
   - https://docs.brew.sh/FAQ
 last_verified: 2026-09-03
-related: [platforms-toolchains-version-management, platforms-processes-background-services, platforms-shells-env-var-off-switches, platforms-toolchains-compiler-sysroot-on-macos, infrastructure-agent-orchestration-verify-command-in-a-worker-brief, infrastructure-agent-orchestration-gate-evidence-exit-code-class]
+related: [platforms-toolchains-version-management, platforms-processes-background-services, platforms-shells-env-var-off-switches, platforms-toolchains-compiler-sysroot-on-macos, infrastructure-agent-orchestration-verify-command-in-a-worker-brief, infrastructure-agent-orchestration-gate-evidence-exit-code-class, platforms-toolchains-native-addon-binary-missing-after-bun-install]
 ---
 
 # The Wrong Binary (or None) Resolving From PATH

@@ -76,6 +76,7 @@ Match your situation to a "load when" line; load only matching pages.
 | [environment-resync-removes-undeclared-packages](toolchains/environment-resync-removes-undeclared-packages.md) | A package that was working (pytest, ruff, a scratch library) vanished after an unrelated dependency change and imports fail across unrelated test files; adding or dropping a dependency while a long job/test run/experiment is in flight; deciding whether dev-only tools belong in a dependency group or an ad-hoc `pip install`; deciding whether a manager's command prunes packages absent from the lockfile (`uv add` vs `uv remove` vs `uv sync` vs `uv run` exactness) |
 | [regeneration-silently-drops-hand-edited-state](toolchains/regeneration-silently-drops-hand-edited-state.md) | A generator-owned file (XcodeGen's `.xcodeproj` regenerated from `project.yml`, or a similar codegen-plus-hand-edit setup) is about to be regenerated to make one small change; deciding whether to trust regenerated output before committing it; a GUI-added target, a shared scheme, or another hand-edit is missing after regeneration even though the build still succeeds |
 | [uv-state-directories-under-a-relocated-home](toolchains/uv-state-directories-under-a-relocated-home.md) | A test suite, sandbox, or hook points `HOME` (or `XDG_CACHE_HOME`/`XDG_DATA_HOME`) at a scratch directory and then runs `uv run`/`uv tool run`, especially `--offline`; uv reports a package "not found in the cache" that resolves from your shell, or picks a different Python than it does interactively; uv-dependent test cases report `skip` on a machine where uv works; choosing between `UV_CACHE_DIR`, `UV_PYTHON_INSTALL_DIR`, `UV_TOOL_DIR` |
+| [native-addon-binary-missing-after-bun-install](toolchains/native-addon-binary-missing-after-bun-install.md) | A CLI, MCP stdio server, or app installed with `bun install`/`bun install -g` dies with `Could not locate the bindings file` or another missing-`.node` error for a native dependency (better-sqlite3, sharp, tree-sitter); `build/Release/` holds `obj` directories and no `.node`; deciding between `bun pm trust`, `--trust`, and a hand rebuild with `prebuild-install`/`node-gyp` under the runtime the launcher uses; adding `trustedDependencies` to a package.json that relied on bun's default allowlist |
 
 ## Planned (unseeded categories)
 

@@ -11,7 +11,7 @@ sources:
   - https://clang.llvm.org/docs/DiagnosticsReference.html
   - https://discourse.llvm.org/t/stdio-h-not-found-on-mac-how-to-add-system-headers-includes-into-clang/77604
 last_verified: 2026-08-29
-related: [platforms-toolchains-version-management, platforms-environment-path-resolution, debugging-signals-reading-error-messages, infrastructure-agent-orchestration-verify-command-in-a-worker-brief]
+related: [platforms-toolchains-version-management, platforms-environment-path-resolution, debugging-signals-reading-error-messages, infrastructure-agent-orchestration-verify-command-in-a-worker-brief, platforms-toolchains-native-addon-binary-missing-after-bun-install]
 ---
 
 # A Non-Apple Compiler Resolving the macOS SDK

@@ -0,0 +1,90 @@
+---
+id: platforms-toolchains-native-addon-binary-missing-after-bun-install
+domain: platforms
+category: toolchains
+applies_to: [node, general]
+confidence: verified
+sources:
+  - https://bun.com/docs/pm/lifecycle
+  - https://bun.com/docs/pm/cli/pm
+  - https://bun.com/docs/guides/install/trusted
+  - https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt
+  - https://github.com/nodejs/node-gyp#installation
+  - https://github.com/WiseLibs/better-sqlite3/blob/master/package.json
+last_verified: 2026-09-28
+related: [platforms-toolchains-version-management, platforms-toolchains-compiler-sysroot-on-macos, platforms-environment-path-resolution, security-dependencies-supply-chain, platforms-tools-plugin-mcp-server-registration]
+---
+
+# A Native Addon Has No `.node` Binary After `bun install`
+
+## When this applies
+
+A CLI, MCP stdio server, or app installed with `bun install` or `bun install -g`
+dies at startup with `Could not locate the bindings file` (or another missing
+`.node` error) for a native dependency such as better-sqlite3, sqlite3, sharp or a
+tree-sitter grammar; the dependency's `build/Release/` holds `obj*` directories and
+no `.node`; deciding between `bun pm trust`, `--trust`, and rebuilding by hand.
+
+## Do this
+
+1. **Read bun's own install notice before choosing a remedy.** bun reports a
+   skipped script and a failed script differently, and only one of them is a
+   trust problem:
+
+| `bun install` printed | What happened | Do |
+|-----------------------|---------------|----|
+| `Blocked N postinstall. Run \`bun pm untrusted\` for details.` and exit 0 | The package is not on the allowlist, so its script never ran | `bun pm trust <name>` in the install root: it runs the blocked script now and appends the name to `trustedDependencies` |
+| `error: install script from "<pkg>" exited with 1` and exit 1 | The script ran and failed; a partial build dir stays behind and no lockfile is written | Fix the build prerequisite (step 3), then re-run `bun install` |
+
+2. **When the install output is gone**, run `bun pm untrusted` in the install
+   root (`~/.bun/install/global` for a `-g` install):
+
+| `bun pm untrusted` says | Then |
+|-------------------------|------|
+| Lists the package and its script | It was blocked: `bun pm trust <name>` |
+| Does not list it and `bun pm default-trusted` contains it | Its script ran and produced no usable binary: step 3 |
+| `error: Lockfile not found` | The install itself failed: re-run `bun install` and read its error |
+
+3. **Rebuild under the runtime that will load the binary.** The launcher decides:
+   a `#!/usr/bin/env node` or `#!/bin/sh` bin runs under the `node` on PATH, a
+   `#!/usr/bin/env bun` bin under bun. In the dependency's directory run
+   `npx prebuild-install` (downloads a prebuilt for that runtime's ABI; exits
+   non-zero when none is published for it), then
+   `npx node-gyp rebuild --release --python=<supported Python>`. node-gyp needs
+   Xcode Command Line Tools on macOS and a supported Python (`--python`,
+   `npm_config_python`, or `PYTHON`). Confirm with `ls build/Release/*.node`, then
+   re-run the CLI itself.
+4. **When you add `trustedDependencies` to a package.json, also list every
+   default-allowlisted package you rely on** (`bun pm default-trusted` prints the
+   list): the field replaces bun's default allowlist instead of extending it, and
+   the default list applies only to packages installed from npm, never to
+   `file:`, `link:`, `git:` or `github:` sources.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The package is on the default list but the project's `trustedDependencies` omits it | It is blocked from now on; add it to the field |
+| Node was upgraded after the install (Homebrew major bump) | The compiled addon targets the old ABI; rebuild with step 3 under the new `node` |
+| The CLI's bin is a `#!/bin/sh` script and you test it with `bun <bin>` | bun parses the shell script as JavaScript and reports `Syntax Error`; run the bin directly |
+| `--ignore-scripts` is set (flag, `bunfig.toml`, `.npmrc`) | It skips the project's own scripts; dependency scripts are governed by the allowlist alone, so it does not explain a blocked dependency |
+| The symptom is an MCP server that reports `CONNECTION_CLOSED` at connect | Run the server command by hand; the bindings error is on its stderr, which the client does not surface |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Reinstall with `--trust` for a package already on `bun pm default-trusted` | Run `bun pm untrusted`, then step 3 | The script already ran; `--trust` re-runs the same failing compile and, by writing `trustedDependencies`, drops every other default-list package |
+| Delete `node_modules` and reinstall to reset the failure | Read the install error and fix the prerequisite it names | The compile prerequisite is unchanged, so the same script fails again |
+| Conclude from the missing `.node` that bun blocked the script | Distinguish blocked from failed with the notices in step 1 | A failed script also leaves no `.node`, but it leaves `obj` directories and an exit 1 |
+
+## Sources
+
+- https://bun.com/docs/pm/lifecycle — bun runs lifecycle scripts only for allowlisted packages; the default list applies to npm sources only; `--ignore-scripts`
+- https://bun.com/docs/pm/cli/pm — `bun pm untrusted`, `bun pm trust`, `bun pm default-trusted`, `bun pm ls --trusted`; a set `trustedDependencies` replaces the default list
+- https://bun.com/docs/guides/install/trusted — default allowlist note and the replace-not-extend rule
+- https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt — better-sqlite3 and sqlite3 are on the default list
+- https://github.com/nodejs/node-gyp#installation — Xcode CLT and supported Python requirements; `--python`, `npm_config_python`, `PYTHON`; `rebuild` = clean + configure + build
+- https://github.com/WiseLibs/better-sqlite3/blob/master/package.json — install script `prebuild-install || node-gyp rebuild --release`
+- Reproduction, bun 1.3.11, 2026-09-28: a trusted `file:` dependency whose install script exits 1 makes `bun install` exit 1 with `error: install script from "failing-dep" exited with 1`, leaves `build/Release/obj`, and writes no lockfile (`bun pm untrusted` then reports `Lockfile not found`); an unlisted dependency yields `Blocked 1 postinstall` with exit 0, and `bun pm trust` runs its script and writes `trustedDependencies`
+- Field case, 2026-09-28: a globally bun-installed MCP server depending on better-sqlite3 12.8.0 launched under Node 26 with only `obj` directories in `build/Release`; better-sqlite3 was on the default list and absent from `bun pm untrusted`; `prebuild-install` had no binary for that ABI and `node-gyp rebuild --release --python=<3.11>` produced `better_sqlite3.node`, after which the server connected
@@ -10,7 +10,7 @@ sources:
   - https://mise.jdx.dev/configuration.html
   - https://docs.npmjs.com/cli/v11/configuring-npm/package-json
 last_verified: 2026-07-10
-related: [platforms-processes-background-services, platforms-shells-portable-shell-scripts, platforms-toolchains-compiler-sysroot-on-macos, platforms-toolchains-environment-resync-removes-undeclared-packages, infrastructure-agent-orchestration-verify-command-in-a-worker-brief, platforms-toolchains-regeneration-silently-drops-hand-edited-state]
+related: [platforms-processes-background-services, platforms-shells-portable-shell-scripts, platforms-toolchains-compiler-sysroot-on-macos, platforms-toolchains-environment-resync-removes-undeclared-packages, infrastructure-agent-orchestration-verify-command-in-a-worker-brief, platforms-toolchains-regeneration-silently-drops-hand-edited-state, platforms-toolchains-native-addon-binary-missing-after-bun-install]
 ---
 
 # Pinning Tool Versions So Every Machine Runs the Same Toolchain

@@ -9,7 +9,7 @@ sources:
   - https://code.claude.com/docs/en/mcp
   - https://github.com/modelcontextprotocol/typescript-sdk/issues/216
 last_verified: 2026-08-12
-related: [platforms-tools-version-keyed-artifact-cache, platforms-tools-harness-mediated-tool-results, infrastructure-config-environment-config, infrastructure-agent-orchestration-gate-evidence-exit-code-class]
+related: [platforms-tools-version-keyed-artifact-cache, platforms-tools-harness-mediated-tool-results, infrastructure-config-environment-config, infrastructure-agent-orchestration-gate-evidence-exit-code-class, platforms-toolchains-native-addon-binary-missing-after-bun-install]
 ---
 
 # A Plugin-Bundled MCP Server That Does Not Appear in the Harness

@@ -11,7 +11,7 @@ sources:
   - https://owasp.org/Top10/A06_2021-Vulnerable_and_Outdated_Components/
   - https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates
 last_verified: 2026-07-10
-related: [security-secrets-secrets-in-code, security-dependencies-agent-skill-supply-chain]
+related: [security-secrets-secrets-in-code, security-dependencies-agent-skill-supply-chain, platforms-toolchains-native-addon-binary-missing-after-bun-install]
 ---
 
 # Trusting and Maintaining Third-Party Dependencies
Original file line number	Diff line number	Diff line change
Expand Up		@@ -208,3 +208,5 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest\|revise\|lint\|gap\|contradiction\|drif
		## [2026-09-28] ingest \| testing-strategy-agent-tool-shared-handler-tests — a UI action that is also a registered tool is tested once at the shared function plus two entry-point tests per tool (Registration incl. AbortSignal teardown, Wiring via spy) against a `document.modelContext` stub; a bug fix that changes the handler's contract changes the `inputSchema` assertion in the same commit; one DevTools Run-tool pass per release.

		## [2026-09-28] revise \| WebMCP adopted as the development standard (owner decision 2026-09-28): frontend/agent-interfaces/agent-facing-tool-surfaces trigger widened to any new or changed user action in a web UI + bug-fix and exclusion-list edge cases; AGENTS.md routing step 7 gains a web-UI-action row → frontend agent-interfaces then qa parity gate; INDEX.md frontend/qa/testing route lines and the frontend/qa/testing domain indexes updated; related links added both ways (release-gates, cross-layer-effect-tests, in-session-tool-exposure). The standard keeps the human UI primary and the tool layer additive (CG draft; Chrome origin trial + ChatGPT desktop runtimes).

		## [2026-09-28] ingest \| platforms-toolchains-native-addon-binary-missing-after-bun-install — a native dependency has no `.node` after `bun install`: read bun's notice (`Blocked N postinstall` = script skipped → `bun pm trust`; `error: install script from "<pkg>" exited with 1` = script ran and failed → fix the node-gyp prerequisite and rebuild under the runtime the launcher uses); `bun pm untrusted` distinguishes the two after the fact; a set `trustedDependencies` replaces the default allowlist, so list default-listed packages too.