[agent-137]

Implements the decision recorded in gominimal/inbox#584 for four ecosystems — follow-up to gominimal/inbox#559, whose npm half is #657: global installs redirect to ~/.local via each tool's narrowest honored knob, delivered at the package level. The failure modes below were observed in a live session.

What breaks today

Tool	Failure in a session
pnpm	refuses: global bin directory ".../pnpm/bin" is not in PATH (PATH is fixed; pnpm setup has nothing to edit)
bun	bun add -g succeeds into a cache-derived dir whose bin is off PATH — binaries never resolve
deno	deno install -g targets ~/.deno/bin, off PATH; deno's own hint ("Add ... to PATH") is impossible to follow
gem	auto-falls back to user install (good), but binstubs land in ~/.local/share/gem/ruby/<v>/bin, off PATH

The fixes

• pnpm — /usr/bin wrappers default PNPM_CONFIG_GLOBAL_BIN_DIR to $HOME/.local/bin. pnpm 12.5.1 reads it from the env (crates/config/src/env_overlay.rs) and uses it in place of <pnpm home>/bin (derive_layout.rs), so only the bin dir moves; the store and global package dir stay at pnpm's defaults. A caller's own PNPM_CONFIG_GLOBAL_BIN_DIR or PNPM_HOME wins.
• bun — wrappers default BUN_INSTALL_BIN=$HOME/.local/bin and BUN_INSTALL_GLOBAL_DIR=$HOME/.local/share/bun/global (bun 1.3.14 PackageManagerOptions.zig). Both are needed: without the second, the global dir falls back under $XDG_CACHE_HOME and clearing the cache leaves the ~/.local/bin links dangling. A caller's value of either, or a caller's BUN_INSTALL, wins.
• deno — wrapper defaults DENO_INSTALL_ROOT=$HOME/.local; deno installs into <root>/bin.
• All three wrappers leave the variables alone when HOME is unset, and exec the real entry point from /usr/libexec/<pkg>/.
• gem — no wrapper needed: RubyGems' system config path is /usr/etc/gemrc, inside the package, so the ruby package ships one with install:, update: and uninstall: keys each set to --bindir ~/.local/bin. Per-command keys rather than a gem: line because RubyGems merges config files key by key, so a user's own gem: --no-document would have dropped the bindir. GEMRC/~/.gemrc/CLI still override. Bundler ignores these keys, so bundle install executables stay off PATH (out of scope).
• Env overrides outrank config files for both pnpm and bun, so a globalBinDir in pnpm's config or globalBinDir/globalDir in bunfig is overridden by the wrapper default; setting the env var (or PNPM_HOME/BUN_INSTALL) is the way to choose another location.
• Every package gains a regression test that performs a real global install offline (see Verification); bun/deno libexec outputs carry allow_executable = true (a Data output matching a binary fails min check without it), and their standalone smoketests target the raw ELFs since standaloneTest runs without a shell.
• bun's bunx stays an argv0 symlink beside the real binary, preserving name-based multiplexing (verified live through an exec'd wrapper).

Not included, deliberately: go (finds GOROOT relative to its own executable, and half the catalog builds with it — needs its own PR and verification) and cargo (blocked on whether rust sessions should link at all — cc/ld are absent today). Both tracked in gominimal/inbox#584.

min task run sandboxes have no ~/.local/bin on PATH, so global installs made inside a task remain out of scope; gominimal/inbox#584 tracks that.

An earlier revision did the pnpm half as a stack-level build_env_vars entry; reverted in favor of package delivery (covers stack-less consumers, $HOME not a literal /home). History carries both steps; squash-merge collapses them.

Verification

The CI test blocks are the verification for the current revision. Each one installs something globally, offline, and asserts that PATH=/usr/bin:/bin:$HOME/.local/bin command -v <bin> resolves to ~/.local/bin/<bin> and runs:

• pnpm (global_install): pnpm add -g of a local file: package with a bin; also asserts pnpm store path is not under ~/.local/store, and that PNPM_CONFIG_GLOBAL_BIN_DIR and PNPM_HOME set by the caller still decide pnpm bin -g.
• bun (global_install): bun add -g of the same kind of package; also asserts the global dir is ~/.local/share/bun/global, and that a caller's BUN_INSTALL suppresses the defaults.
• deno (global_install): deno install -g -n gbin of a local script.
• ruby (gem_global_install): gem build + gem install --local of a minimal gem with an executable, with a user ~/.gemrc carrying gem: --no-document; then gem uninstall -x removes the stub.

Standalone tests run with the build-sandbox env (HOME=/state/home, no ~/.local/bin on PATH), so each test spells out a session-like PATH.

Outside CI: the pnpm, bun and deno test bodies were run locally against the upstream 12.5.1 / 1.3.14 / 2.9.5 release binaries behind the generated wrappers (pnpm and deno ship those exact tarballs; the bun package builds from source, so its binary differs), with a fresh HOME, and pass; the pnpm test fails against the previous PNPM_HOME wrapper. The ruby test has not been run outside CI.

Live Minimal session (2026-10-02, this revision): all four stacks pass on macOS 26.6.2 / Apple Silicon with min 0.6.0-dev.78 (minvmd backend, guest kernel 6.12.105 aarch64), in a session pinned to locked_commit = 7fb6d21d on this branch with packages base, pnpm, bun, deno, ruby, ruby-lsp, activated with --no-loadouts, a fresh HOME, and ~/.local/bin removed before each stack. The wrappers at /usr/bin/{pnpm,bun,deno} were byte-identical to this PR's heredocs and /usr/etc/gemrc carried the three --bindir lines.

• pnpm 12.5.1: pnpm add -g file:… → ~/.local/bin/gbin-pnpm, runs; pnpm bin -g → ~/.local/bin; store at ~/.local/share/pnpm/store/v11, nothing under ~/.local/store; PNPM_CONFIG_GLOBAL_BIN_DIR and PNPM_HOME from the caller each decide pnpm bin -g.
• bun 1.3.14: bun add -g → ~/.local/bin/gbin-bun (symlink into ~/.local/share/bun/global), runs; $XDG_CACHE_HOME/.bun/install/global not created; BUN_INSTALL moves both the global dir and the bin dir; bunx --version and an exec'd /usr/bin/bunx both answer.
• deno 2.9.5: deno install -g -n gbin → ~/.local/bin/gbin, runs; ~/.deno not created; DENO_INSTALL_ROOT from the caller wins.
• ruby 4.0.6 / RubyGems 4.0.16, ruby-lsp 0.26.10: gem env merges the system --bindir lines with a user ~/.gemrc of gem: --no-document; gem build + gem install --local → ~/.local/bin/gbin-gem, runs, no docs generated; gem uninstall -x leaves ~/.local/bin empty; a GEMRC override redirects the stub. ruby-lsp --version answers and a JSON-RPC initialize round-trip returns capabilities; its vendored bins stay under /usr/lib/ruby-lsp/gems/bin.

Observed and unrelated to this PR: bun's add banner reports 1.3.14-canary.1 while bun --version reports 1.3.14 (source-build version string); the ruby-lsp launcher composes a bundle on first start and self-updates to 0.26.11 from the network; pnpm prints its update nag. shellcheck: lines added to the build scripts and the generated wrappers are clean; pre-existing findings are untouched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JGTXbdK7hgDupktNZEkALY

Summary by CodeRabbit

• Features
  • Bun and Deno now use ~/.local for global installation locations when the relevant settings are unset.
  • pnpm now defaults global command-line executables to ~/.local/bin when PNPM_HOME is unset.
  • RubyGems now places installed command-line executables in ~/.local/bin by default.
  • Bun, Deno, and pnpm continue to forward command-line arguments.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: gominimal/pkgs/.coderabbit.yaml

Review profile: CHILL

Plan: Essentials

Run ID: 149e0684-68e2-49e2-b76c-a3a8c7e64594

📥 Commits

Reviewing files that changed from the base of the PR and between 6c0a814 and 7fb6d21.

📒 Files selected for processing (8)

• packages/bun/build.ncl
• packages/bun/build.sh
• packages/deno/build.ncl
• packages/deno/build.sh
• packages/pnpm/build.ncl
• packages/pnpm/build.sh
• packages/ruby/build.ncl
• packages/ruby/build.sh

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

---

📝 Walkthrough

Walkthrough

Bun, Deno, and pnpm now install executables under /usr/libexec and use /usr/bin wrappers to configure user-local paths and forward arguments. RubyGems configures executable installation under ~/.local/bin. Ruby LSP sets an explicit executable destination.

Changes

User-local Installation Defaults

Layer / File(s)	Summary
Bun and Deno wrappers packages/bun/build.sh, packages/bun/build.ncl, packages/deno/build.sh, packages/deno/build.ncl	The binaries are installed under /usr/libexec. The /usr/bin wrappers set the documented user-local environment defaults and forward arguments. Build outputs and standalone tests cover the binary paths and global installs.
pnpm wrappers packages/pnpm/build.sh, packages/pnpm/build.ncl	The /usr/bin symlinks are replaced with wrappers that execute the corresponding /usr/libexec commands and conditionally set PNPM_CONFIG_GLOBAL_BIN_DIR. Tests check the native binary path, global command location, store path, and configured bin directories.
RubyGems executable paths packages/ruby/build.sh, packages/ruby/build.ncl, packages/ruby-lsp/build.sh	Ruby adds gem configuration for ~/.local/bin and a test for executable installation and removal. Ruby LSP passes an explicit --bindir under the vendored gems directory.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Suggested reviewers: bryan-minimal

Merge Risk: ⚪ Minimal · up to 7fb6d

The user-local installation defaults have no identified merge-blocking issue. Merge after normal build and package checks pass.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 5…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: redirecting global installs for pnpm, Bun, Deno, and RubyGems to ~/.local.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}

[agent-137]

CI failure post-mortem (both failures were mine, both fixed in d5142f9):

1. minimal-check / missing runtime_deps (pnpm, bun, deno) — the new #!/bin/sh wrappers need a runtime provider for bin/sh; the checker caught that none was declared. bash (which ships the sh symlink) is now in each package's runtime_deps.
2. minimal-check / standalone tests (ruby-lsp) — the ruby package's new system gemrc leaked into ruby-lsp's vendored build: its gem install picked up the global --bindir ~/.local/bin default, wrote the binstub into the build sandbox home, and /usr/bin/ruby-lsp then exec'd a missing path. Fixed with an explicit --bindir "$GEMS/bin" (CLI beats gemrc). ruby-lsp is the only build-time gem install in the catalog, so no other package needs the same treatment.

@bryan thanks for the re-trigger — my fix is rebased on top of your no-op, so the new run includes both. The 2h bun-build hang looks unrelated to the diff content (the bun build.sh changes only touch the install step after bun run build:release); if it hangs again on this run it's worth a look independent of this PR.

[bryan-minimal]

Heads-up: this now conflicts with main (CONFLICTING / DIRTY) on all four files it touches, after three PRs landed today. The conflicts are mechanical, but one of them has a wrong resolution that would re-open a two-day outage, so it seemed worth writing down rather than letting it get resolved by reflex.

Also worth saying: the last CI run here completed 2026-08-28, so its red is stale and predates everything below.

The one that matters: don't restore node-lts in pnpm

packages/pnpm/build.ncl on main is now:

runtime_deps = [
  subsetOf node ["node"],   # NOT node-lts, and NOT the whole package
  coreutils,
],

This branch still has node-lts. Merging that back would undo #671.

Why it matters (pkgs#665/#670/#671): next and agent-browser both declare node themselves, so when pnpm also carried node-lts, two npm installs landed in one sandbox at the same paths. The sandbox hardlinks closure members first-writer-wins per file, so /usr/lib/node_modules/npm/ came out as a blend of both versions — minipass-flush/index.js from npm 11.17.0 (which imports minipass by its 7.x named export) beside a nested minipass@3.3.6 from npm 11.11.1 (default export only). class Flush extends undefined throws, and every npm install dies. Both packages were individually fine; only the merge was broken. It blocked next for two days and took four PRs down with it.

The subsetOf form means pnpm contributes only the node binary and can never contribute an npm tree at all, so the failure is structurally impossible rather than just currently-absent.

Suggested resolution: keep main's subsetOf node ["node"], then re-apply your bash addition and the global_bin_dir test on top. Your changes and #671 are orthogonal — nothing here depends on it being node-lts specifically.

The other three are additive

• packages/pnpm/build.sh — your PNPM_HOME wrapper; main is unchanged here apart from fix(pnpm): depend on node, not node-lts — two npms in one sandbox break each other #671's comment block.
• packages/bun/build.ncl — main added three OutputData globs for completions (bash_completion, fish_completion, zsh_completion) and OutputData to the minimal.ncl destructure. Your libexec glob and OutputData import sit alongside them; keep both sets.
• packages/bun/build.sh — main appends completion installs from the committed completions/bun.{bash,zsh,fish}. Those read from the extracted source, so they are independent of where the binary ends up.

Two things I noticed, offered as questions not objections

Your standaloneTest fix is a real find — "standaloneTest runs with no shell in the sandbox, so a #!/bin/sh wrapper would ENOENT there." That is the kind of thing that would otherwise show up as a baffling test failure much later.

Adding bash to runtime_deps of both pnpm and bun widens what they impose on every consumer. That is the same axis #671 just narrowed pnpm along, so it is worth a deliberate look rather than an accident. Concretely: bash and bash-bootstrap both ship /usr/bin/bash and /usr/bin/sh, and the two binaries genuinely differ (1,222,160 vs 1,133,600 bytes — --with-installed-readline vs --disable-readline). A fleet audit found only e2fsprogs and mtools currently hold both, so this is not firing today; the question is whether pushing bash into every pnpm/bun consumer's closure creates new pairs. If the wrapper only needs /bin/sh, a narrower dep would keep the surface small.

No action needed from me — flagging because the pnpm resolution is easy to get wrong and expensive when it is.

[mitodrummer]

Rebased onto main (9abf7d0c), now MERGEABLE. Thanks for writing the pnpm one down — it is exactly the resolution reflex would have gotten wrong.

Conflicts, as resolved

• packages/pnpm/build.ncl — kept main's subsetOf node ["node"] and the comment block explaining why, verbatim. node-lts is gone from this branch; fix(pnpm): depend on node, not node-lts — two npms in one sandbox break each other #671 stands. My two additions sit on top: bash in runtime_deps and the global_bin_dir test. Nothing here depended on it being node-lts — you were right that they are orthogonal.
• packages/bun/build.ncl — both sets of outputs kept: your three completion OutputData globs plus my libexec glob (with allow_executable = true). OutputData was already in the destructure from your side, so the import line needed no change.
• packages/bun/build.sh — both blocks kept. The libexec install + wrapper emission runs first, then the completions install from completions/bun.{bash,zsh,fish}. They are independent: the completion files are read from the extracted source, not from wherever the binary landed.
• packages/pnpm/build.sh — additive, no interaction with fix(pnpm): depend on node, not node-lts — two npms in one sandbox break each other #671's comment block.

min check passes on all nine touched files. The output-dependent checkers (enumerate bins, output types valid, missing runtime_deps, standalone tests) report Skip locally because nothing is built in this session — CI runs them for real.

On bash in runtime_deps

I went looking for the narrower dep you suggested, and it does not exist:

• subsetOf bash ["sh"] would ship a dangling symlink. packages/bash/build.sh:25 is ln -sf bash $OUTPUT_DIR/usr/bin/sh — sh is a relative symlink to bash, so a subset carrying the sh output without the bash output resolves to nothing.
• subsetOf bash ["sh", "bash"] would not narrow the axis you care about. It drops mans, includes and locales — real bytes, but not the ones in play. The bash/bash-bootstrap pairing you found is a collision on exactly /usr/bin/bash and /usr/bin/sh, and any subset that gives a working /bin/sh ships both of those paths by construction.
• Nothing else in the catalog provides /bin/sh. No dash, busybox, toybox or ash package exists; bash and bash-bootstrap are the only two providers, and bash-bootstrap is a toolchain-bootstrap package, not something to push into consumer closures.

So the choice is bash or no wrapper. For bun and deno there is no no-wrapper option — the thing that has to set the env var runs before an ELF starts, which means a shell. bash in runtime_deps is also the established idiom rather than a novel imposition: 28 packages already do it, including python, and subsetOf bash appears zero times in the repo.

Where I think your concern actually lands is the bash/bash-bootstrap pairing itself — it is a property of those two packages both owning /usr/bin/{bash,sh}, and it will keep being reachable through any of those 28 packages regardless of what this PR does. Happy to open a separate issue to track making that pair structurally impossible (an sh-only provider, or having bash-bootstrap stop claiming those paths once the real bash exists) if you think it is worth one — but it seems wrong to make this PR the place that gets solved.

CI

The red on this PR predates the rebase (last run 2026-08-28, as you noted). A fresh run should pick up the current tip.

[mitodrummer]

/review

[mitodrummer]

/review