@gjsify/cli 0.36.0 → 0.37.0

package/lib/commands/install.js

@@ -1,32 +1,21 @@
-// `gjsify install [pkg...]` — install packages with gjsify-aware post-checks.
+// `gjsify install [pkg...]` — project install, `<pkg>` add, or `-g` user-global
+// install (XDG prefix + GJS-runnable bin), plus gjsify-aware post-checks.
 //
-// Modes:
-//   gjsify install                    → project install (native, reads pkg.json)
-//   gjsify install <pkg> [<pkg>...]   → add package(s) to project (native)
-//   gjsify install -g <pkg> [...]     → user-global install (XDG, GJS-runnable bin)
+// All three modes route through `installPackagesNative`
+// (`@gjsify/{semver,npm-registry,tar}`) — no Node/npm at runtime.
+// `--backend=npm` / `GJSIFY_INSTALL_BACKEND=npm` is the escape hatch for what
+// the native backend does not model (Yarn PnP, lifecycle scripts).
 //
-// All three modes route through `@gjsify/{semver,npm-registry,tar}` via
-// `installPackagesNative` — no Node/npm required at runtime. Pass
-// `--backend=npm` (or set the legacy `GJSIFY_INSTALL_BACKEND=npm` env var)
-// to opt back into the `npm install` subprocess flow — useful as an
-// escape hatch for projects that hit a missing native-backend feature
-// (Yarn PnP repos, lifecycle scripts, npm's `overrides` quirks).
+// A workspace install hoists every member's externals into the root
+// `node_modules/` and symlinks `workspace:` refs to their source. Members with
+// conflicting ranges of the same external still share ONE hoisted copy; the
+// resolver warns naming both ranges, both requesters and the winner (per-member
+// dedup is the open Phase D.8 item in status/open-todos.md).
 //
-// Workspace install (`gjsify install` in a monorepo root with a
-// `"workspaces"` field) hoists every workspace's externals into the root
-// `node_modules/` and symlinks `workspace:*` / `workspace:^` / `workspace:~`
-// refs to their target source. Conflicting version ranges of the same
-// external dep from different workspaces still share ONE hoisted root copy
-// (a real per-workspace dedup pass is Phase D.8, see status/open-todos.md), but since
-// ADR 0001 step 3 the resolver surfaces every such conflict loudly —
-// `[gjsify] warning: version conflict for <pkg> …` names both ranges, the
-// workspaces that requested them, and the version that actually won.
-//
-// Concurrency (ADR 0001 step 2): every mutation of an install prefix —
-// project node_modules/, gjsify-lock.json, the user-global prefix — runs
-// under a per-prefix cross-process lock (utils/install-lock.ts). Installs
-// into different prefixes stay parallel; the shared XDG tarball/packument
-// caches need no lock because their writes are atomic tmp+rename.
+// Concurrency (ADR 0001): every prefix mutation runs under a per-prefix
+// cross-process lock (utils/install-lock.ts), so installs into different
+// prefixes stay parallel. The shared XDG tarball/packument caches need no lock
+// because their writes are atomic tmp+rename.
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -47,30 +36,25 @@ import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFro
 /**
  * Link type for the workspace↔workspace directory links.
  *
- * Windows cannot create a *directory symlink* without elevation or Developer
- * Mode (`EPERM`), but any user can create an NTFS **junction** — which is why
- * npm and yarn both use junctions for workspace links. These two call sites had
- * no try/catch, so a non-elevated Windows workspace install hard-failed here.
+ * Windows cannot create a directory *symlink* without elevation or Developer
+ * Mode (`EPERM`), but any user can create an NTFS junction — which is why npm
+ * and yarn both use junctions for workspace links.
  */
 const WORKSPACE_LINK_TYPE = process.platform === 'win32' ? 'junction' : undefined;
 /**
  * The `target` argument for a workspace link.
  *
- * Node normalises a `'junction'` target with `path.resolve()` — i.e. against
- * the process CWD, NOT the link's own directory — so a junction MUST be given
- * an absolute path. POSIX symlinks stay relative so the tree survives being
- * moved.
+ * Node normalises a `'junction'` target with `path.resolve()` — against the
+ * process CWD, not the link's own directory — so a junction must be given an
+ * absolute path. POSIX symlinks stay relative so the tree survives a move.
  */
 function workspaceLinkTarget(linkPath, absTarget) {
     return WORKSPACE_LINK_TYPE === 'junction' ? resolve(absTarget) : relative(dirname(linkPath), absTarget);
 }
-// Default 30min wall-clock budget for the full install. Big workspaces
-// (212+ sub-packages × 600+ external deps in the gjsify monorepo itself)
-// can legitimately take 10-20 min on a fresh CI install when the npm CDN
-// is slow — a 5-min default would false-positive on those legitimate
-// flows. Per-fetch timeout (30s, retried) catches the truly stuck case
-// inside this budget. Set --timeout 0 to disable the wall-clock guard
-// entirely.
+// 30 min, not minutes: this monorepo (212+ members × 600+ externals) legitimately
+// takes 10-20 min on a fresh CI install behind a slow npm CDN, so a tighter
+// default would false-positive. The per-fetch timeout (30s, retried) catches the
+// truly stuck case inside this budget.
 const DEFAULT_INSTALL_TIMEOUT_MS = 1_800_000;
 export const installCommand = {
     command: 'install [packages..]',
@@ -143,37 +127,33 @@ export const installCommand = {
         default: false,
     }),
     handler: async (args) => {
-        // Publish `--os/--cpu/--libc/--force` as npm CONFIG KEYS before anything
-        // resolves — see applyPlatformConfigFromFlags for why the environment is
-        // the right channel for them rather than a parameter.
+        // Must run before anything resolves — `--os/--cpu/--libc/--force` are npm
+        // config keys, see applyPlatformConfigFromFlags for why via the environment.
         applyPlatformConfigFromFlags(args);
-        // --immutable is incompatible with explicit `<pkg>` adds and with
-        // `--global` (which has no lockfile concept). Matches yarn's
-        // behavior: `yarn add --immutable` is a hard error.
+        // --immutable rejects `<pkg>` adds and `--global` (no lockfile concept),
+        // matching yarn, where `yarn add --immutable` is a hard error.
         if (args.immutable) {
             if (args.packages && args.packages.length > 0) {
                 console.error('gjsify install --immutable does not accept package arguments. ' +
                     'Remove the package names or drop --immutable.');
-                // `return` — a bare `process.exit()` is deferred under GJS and
-                // the install would proceed past a refused flag combination.
+                // `return` — a bare `process.exit()` is deferred under GJS, and the
+                // install would proceed past a refused flag combination. Same for
+                // every `return process.exit()` below.
                 return process.exit(1);
             }
             if (args.global) {
                 console.error('gjsify install --immutable is incompatible with --global.');
-                // `return` — see the deferred-exit note above.
                 return process.exit(1);
             }
             if (args['refresh-lockfile']) {
                 console.error('gjsify install --immutable is incompatible with --refresh-lockfile ' +
                     '(--immutable forbids rewriting the lockfile). Drop one.');
-                // `return` — see the deferred-exit note above.
                 return process.exit(1);
             }
         }
         if (args.global) {
             if (!args.packages || args.packages.length === 0) {
                 console.error('gjsify install --global requires at least one <pkg> argument.');
-                // `return` — see the deferred-exit note above.
                 return process.exit(1);
             }
             for (const flag of ['save-dev', 'save-peer', 'save-optional']) {
@@ -184,68 +164,43 @@ export const installCommand = {
             await installGlobalAndLink(args.packages, { verbose: args.verbose });
             return;
         }
-        // Surface a CLI/workspace version skew BEFORE the heavy install, so
-        // it's visible even if a later phase is slow. A gjsify CLI that is out
-        // of step with the @gjsify/cli the workspace pins is the root cause of
-        // both the mysterious install stall (a mismatched CLI resolves a
-        // differently-shaped lock → full fresh resolve → a wedge-prone extract)
-        // and silent-wrong-builds (the stale CLI builds with stale semantics).
+        // Before the heavy install, so the skew is visible even if a later phase
+        // is slow — it is the root cause the slow phase would otherwise mask.
         warnOnCliVersionSkew(process.cwd());
-        // Backend selection (in precedence order):
-        //   1. --backend flag (explicit user choice)
-        //   2. GJSIFY_INSTALL_BACKEND env (back-compat shape from pre-flag era)
-        //   3. native (default)
         const backend = args.backend ?? process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
         if (backend === 'npm') {
             await projectInstallViaNpm(args);
             await runPostInstallChecks(args);
             return;
         }
-        // Overall wall-clock budget for the install (default 30 min — big
-        // workspaces on slow networks legitimately take a while). On timeout
-        // we abort every in-flight registry fetch via this controller so a
-        // signal-aware await rejects and the process exits cleanly with an
-        // actionable message. Per-request timeouts inside @gjsify/npm-registry
-        // (default 30s, retried) still apply within this budget.
+        // On timeout this controller aborts every in-flight registry fetch, so a
+        // signal-aware await rejects and the process exits with an actionable
+        // message.
         //
-        // The abort only rescues awaits that OBSERVE the signal. Some awaits on
-        // the fresh-resolve path do not — most notably tarball extraction (a
-        // Gio-backed decompress whose stream close-event can be dropped under
-        // GJS) and the workspace symlink fs-pool — so an aborted controller
-        // alone cannot guarantee the process ever stops. `hardExitTimerId`
-        // below is the backstop: a grace period after the abort, if the install
-        // STILL hasn't returned, force a non-zero exit. This converts any
-        // residual never-settling await into a clean failure instead of a
-        // silent 0%-CPU hang (the observed "it never completed; I killed it"
-        // pathology). `extractOne` additionally caps each extract with its own
-        // stall timeout so the common case fails fast, long before this.
+        // But the abort only rescues awaits that OBSERVE the signal, and some on
+        // the fresh-resolve path do not — notably tarball extraction (a Gio-backed
+        // decompress whose stream close-event can be dropped under GJS) and the
+        // workspace symlink fs-pool. `hardExitTimerId` below is the backstop that
+        // turns any residual never-settling await into a non-zero exit instead of a
+        // silent 0%-CPU hang. `extractOne` also caps each extract with its own
+        // stall timeout, so the common case fails long before either.
         const overallTimeoutMs = args.timeout > 0 ? args.timeout : 0;
         const overallController = overallTimeoutMs > 0 ? new AbortController() : null;
         const overallTimerId = overallController !== null
             ? setTimeout(() => overallController.abort(new Error('install-overall-timeout')), overallTimeoutMs)
             : null;
-        // Grace after the abort before we pull the plug. Long enough for a
-        // signal-aware reject to propagate through the catch (the clean path),
-        // short enough that a genuinely-wedged await doesn't hang for minutes.
+        // Long enough for a signal-aware reject to propagate through the catch (the
+        // clean path), short enough that a wedged await does not hang for minutes.
         const HARD_EXIT_GRACE_MS = 10_000;
         const hardExitTimerId = overallTimeoutMs > 0
             ? setTimeout(() => {
                 const secs = Math.round(overallTimeoutMs / 100) / 10;
-                // Do NOT assert a cause here — this timer cannot tell the
-                // two shapes apart, and claiming the rarer one sends the
-                // next reader after a bug that isn't there. Measured on a
-                // cold tree of this workspace WHEN THIS TIMER WAS WRITTEN:
-                // 1597 packages / ~4.8 GB extracted, of which ~3.4 GB were
-                // foreign-platform optional deps (`os`/`cpu` excluding the
-                // host) that npm would never place. Those are no longer
-                // downloaded — the resolver now records `os`/`cpu`/`libc`
-                // and marks incompatible optional nodes inert
-                // (`utils/platform-check.ts` + `applyPlatformFilter`), which
-                // leaves ~1.4 GB of that same tree to extract. The budget
-                // still exists for the same reason: extraction has
-                // multi-second SYNCHRONOUS stretches (tar parse + file
-                // writes) and 16 run concurrently, so the clean abort path
-                // can easily miss the grace window with nothing wedged.
+                // Do NOT assert a cause here: this timer cannot tell the two
+                // shapes apart, and naming the rarer one sends the next reader
+                // after a bug that is not there. Extraction has multi-second
+                // SYNCHRONOUS stretches (tar parse + file writes) and 16 run
+                // concurrently, so a healthy install can miss the grace window
+                // with nothing wedged — measured: ~1.4 GB on a cold tree here.
                 console.error(`gjsify install: the ${secs}s budget elapsed and the abort did not unwind within ` +
                     `${Math.round(HARD_EXIT_GRACE_MS / 1000)}s — forcing exit. That means one of two ` +
                     `things, and this timer cannot distinguish them: the install was still WORKING ` +
@@ -257,9 +212,8 @@ export const installCommand = {
                 forceExit(1);
             }, overallTimeoutMs + HARD_EXIT_GRACE_MS)
             : null;
-        // Don't let the backstop timer keep an otherwise-finished process alive
-        // (Node keeps the loop up while a timer is armed). `unref` lets the
-        // process end the instant the install returns; `finally` clears it too.
+        // Node keeps the loop up while a timer is armed, so `unref` lets the process
+        // end the instant the install returns.
         hardExitTimerId?.unref?.();
         try {
             await projectInstallNative(args, overallController?.signal);
@@ -270,9 +224,8 @@ export const installCommand = {
                 const secs = Math.round(overallTimeoutMs / 100) / 10;
                 console.error(`gjsify install: timed out after ${secs}s — likely a registry slowdown or a wedged extract.\n` +
                     `Re-run, or override with --timeout <ms> (set --timeout 0 to disable the overall budget).`);
-                // `return` — the deferred GJS exit otherwise fell through into
-                // the rethrow below and reported the timeout twice. The
-                // `finally` still runs on the way out and clears the timers.
+                // `return` — the deferred GJS exit otherwise fell through into the
+                // rethrow below and reported the timeout twice.
                 return process.exit(1);
             }
             throw err;
@@ -288,20 +241,16 @@ export const installCommand = {
 /**
  * Hand the platform target + force bypass to the install backend.
  *
- * `os`, `cpu`, `libc` and `force` are npm CONFIG KEYS, and npm's own transport
- * for a config key is the environment: `--libc=musl` and `npm_config_libc=musl`
- * are the same input, which is why supporting the flags gives users the env
- * spelling for free. That is also why this is not threaded through as a
- * parameter: the config channel is already what this installer reads
- * (`loadNpmrc` honours `npm_config_registry` exactly so), one write reaches
- * EVERY prefix an invocation may install into (project, workspace root, `-g`,
- * the `dlx` cache) instead of one call site each, and a child process inherits
- * it — so a nested install can't quietly resolve for a different machine than
- * the run that spawned it.
+ * `os`, `cpu`, `libc` and `force` are npm CONFIG KEYS, and npm's transport for a
+ * config key is the environment (`--libc=musl` ≡ `npm_config_libc=musl`), so the
+ * flags come with the env spelling for free. Not threaded as a parameter because
+ * one env write reaches EVERY prefix an invocation may install into (project,
+ * workspace root, `-g`, the `dlx` cache) and is inherited by children, so a
+ * nested install cannot quietly resolve for a different machine than its parent.
  *
- * Empty/whitespace values are ignored rather than written as the empty string:
- * `--os=` must not mean "the nameless platform" (`readPlatformOverrides` drops
- * them on the read side too, so the two ends agree).
+ * Empty/whitespace values are ignored rather than written as the empty string —
+ * `--os=` must not mean "the nameless platform", and `readPlatformOverrides`
+ * drops them on the read side too.
  */
 function applyPlatformConfigFromFlags(args) {
     const keys = [
@@ -323,12 +272,10 @@ function applyPlatformConfigFromFlags(args) {
         process.env.npm_config_force = 'true';
 }
 /**
- * Heuristic: was this error raised because the overall-install AbortSignal
- * fired? The signal's `reason` is the sentinel `Error('install-overall-timeout')`
- * we installed above; the abort surfaces either as that exact reason or as
- * any AbortError thrown by a downstream fetch / setTimeout-on-abort path.
- * We match permissively because intermediate layers (fetch, GJS Soup, our
- * own delay()) re-wrap the reason in their own AbortError instances.
+ * Was this error raised because the overall-install AbortSignal fired? Matched
+ * permissively on purpose: intermediate layers (fetch, GJS Soup, our own
+ * `delay()`) re-wrap the `install-overall-timeout` reason in their own
+ * AbortError instances.
  */
 function isAbortedFromOverallTimeout(err) {
     if (!err || typeof err !== 'object')
@@ -361,9 +308,9 @@ function readCliVersionFrom(pkgJsonPath) {
     return null;
 }
 /**
- * Version of the @gjsify/cli that is ACTUALLY running (this bundle / lib entry).
- * Walks up from `import.meta.url` to the nearest `@gjsify/cli` package.json —
- * same discovery as `self-update`'s `readCurrentVersion`.
+ * Version of the `@gjsify/cli` that is ACTUALLY running: walks up from
+ * `import.meta.url` to the nearest `@gjsify/cli` package.json, the same
+ * discovery as `self-update`'s `readCurrentVersion`.
  */
 function readRunningCliVersion() {
     try {
@@ -381,24 +328,20 @@ function readRunningCliVersion() {
     return null;
 }
 /**
- * Version of the @gjsify/cli the workspace at `cwd` pins/ships. Prefers the
- * resolved install (`node_modules/@gjsify/cli`, a hoisted symlink in the
- * gjsify monorepo or a real install in a consumer), falling back to the
- * in-repo source so the check also fires on a fresh, not-yet-installed
- * checkout of the gjsify monorepo itself.
+ * Version of the `@gjsify/cli` the workspace at `cwd` pins. Prefers the resolved
+ * install, falling back to the in-repo source so the check also fires on a fresh,
+ * not-yet-installed checkout of the gjsify monorepo itself.
  */
 function readWorkspaceCliVersion(cwd) {
     return (readCliVersionFrom(join(cwd, 'node_modules', CLI_PACKAGE_NAME, 'package.json')) ??
         readCliVersionFrom(join(cwd, 'packages', 'infra', 'cli', 'package.json')));
 }
 /**
- * Warn (never block) when the running gjsify CLI is a different version than
- * the @gjsify/cli the workspace pins. Running a mismatched CLI is the root of
- * two hard-to-diagnose failures documented on real sessions: install stalls (a
- * mismatched CLI discards the lock → full fresh resolve → a wedge-prone
- * extract) and silent-wrong-builds (stale CLI, stale bundle semantics). A
- * single actionable line pointing at `gjsify self-update` beats both silently.
- * Suppress with GJSIFY_NO_VERSION_SKEW_WARNING=1.
+ * Warn (never block) when the running gjsify CLI differs from the `@gjsify/cli`
+ * the workspace pins. A mismatched CLI is the measured root of two
+ * hard-to-diagnose failures: install stalls (the lock is discarded → full fresh
+ * resolve → wedge-prone extract) and silent-wrong-builds (stale bundle
+ * semantics). Suppress with `GJSIFY_NO_VERSION_SKEW_WARNING=1`.
  */
 function warnOnCliVersionSkew(cwd) {
     if (process.env.GJSIFY_NO_VERSION_SKEW_WARNING === '1')
@@ -425,26 +368,23 @@ function isWorkspaceRoot(cwd) {
 /**
  * Which dependency NAMES are optional across the given manifests.
  *
- * The specs handed to the install backend are flat `"<name>@<range>"` strings —
- * `projectSpecsFromPackageJson` merges the three dependency blocks — so the kind
- * has to travel beside them. It matters for exactly one decision: an
- * incompatible `os`/`cpu`/`libc` skips an OPTIONAL dependency and fails a
- * REQUIRED one (see `NativeInstallOptions.optionalSpecs`).
+ * The specs handed to the backend are flat `"<name>@<range>"` strings, so the
+ * kind has to travel beside them. It decides exactly one thing: an incompatible
+ * `os`/`cpu`/`libc` skips an OPTIONAL dependency and fails a REQUIRED one (see
+ * `NativeInstallOptions.optionalSpecs`).
  *
- * REQUIRED WINS ACROSS MANIFESTS, OPTIONAL WINS WITHIN ONE — and the two halves
- * are different rules for different reasons, so neither is a special case of the
- * other:
- *   - Across manifests: in a workspace the same package can be a plain dependency
- *     of one member and an optionalDependency of another. Those are two real
- *     edges; if one of them is not allowed to be missing, the install is not
- *     allowed to silently miss it. Subtracting rather than "last block seen" also
- *     makes the answer independent of manifest iteration order.
- *   - Within one manifest: a name in BOTH blocks is OPTIONAL, because npm says so
- *     ("entries in optionalDependencies will override entries of the same name in
- *     dependencies") — there is only ONE edge and the optional block names its
- *     kind. Treating it as required is the root-edge twin of the transitive defect
- *     `requiredDepEntries` fixes: `optionalDependencies: { fsevents }` alongside a
- *     `dependencies: { fsevents }` line would fail every Linux install with
+ * REQUIRED WINS ACROSS MANIFESTS, OPTIONAL WINS WITHIN ONE — two rules with two
+ * reasons, neither a special case of the other:
+ *   - Across manifests: one package can be a plain dependency of one member and
+ *     an optionalDependency of another. Those are two real edges, and an edge
+ *     that may not be missing must not be silently missed. Subtracting rather
+ *     than "last block seen" also makes the answer order-independent.
+ *   - Within one manifest: a name in BOTH blocks is OPTIONAL because npm says so
+ *     ("entries in optionalDependencies will override entries of the same name
+ *     in dependencies") — one edge, and the optional block names its kind.
+ *     Treating it as required is the root-edge twin of the defect
+ *     `requiredDepEntries` fixes: `optionalDependencies: { fsevents }` beside a
+ *     `dependencies: { fsevents }` line failed every Linux install with
  *     EBADPLATFORM over a package npm never installs there.
  */
 export function optionalDependencyNames(manifests) {
@@ -456,9 +396,8 @@ export function optionalDependencyNames(manifests) {
             optional.add(name);
         for (const kind of ['dependencies', 'devDependencies']) {
             for (const name of Object.keys(manifest[kind] ?? {})) {
-                // Overridden by THIS manifest's own optional block — not a
-                // required edge, so it must not veto another manifest's optional
-                // declaration either.
+                // Overridden by THIS manifest's own optional block — not a required
+                // edge, so it must not veto another manifest's optional declaration.
                 if (optionalHere.has(name))
                     continue;
                 required.add(name);
@@ -481,23 +420,18 @@ function depKindFromArgs(args) {
 async function projectInstallNative(args, signal) {
     const cwd = process.cwd();
     const pkgPath = join(cwd, 'package.json');
-    // gjsify install is a node_modules-linker installer (like `npm install`
-    // or `yarn --nodeLinker node-modules`): it materialises a node_modules/
-    // tree + gjsify-lock.json. It deliberately does NOT produce a Yarn PnP
-    // install, and the two resolution strategies cannot coexist — a leftover
-    // `.pnp.cjs` makes Node ignore the node_modules/ tree we write, leaving a
-    // silently broken project.
+    // This is a node_modules-linker installer, and the two resolution strategies
+    // cannot coexist: a leftover `.pnp.cjs` makes Node ignore the node_modules/
+    // tree we write, leaving a silently broken project.
     //
-    // Native PnP *generation* (a byte-identical `.pnp.cjs` + `.yarn/cache/*.zip`
-    // that yarn itself would accept) is intentionally out of scope: it would
-    // mean replicating yarn's libzip-deterministic archives, SHA-512 cache
-    // keys, cache-version tracking and virtual-locator synthesis, and would
-    // only ever match a single yarn release. So we stop here with actionable
-    // guidance instead of half-doing it.
+    // Native PnP *generation* is out of scope on purpose — it would mean
+    // replicating yarn's libzip-deterministic archives, SHA-512 cache keys,
+    // cache-version tracking and virtual-locator synthesis, and would only ever
+    // match one yarn release. Better to stop with actionable guidance.
     //
-    // We do NOT point users at `GJSIFY_INSTALL_BACKEND=npm` from this error:
-    // that backend chokes on `workspace:` specs (`EUNSUPPORTEDPROTOCOL`),
-    // which is exactly what the workspace repos that reach this branch have.
+    // The error deliberately does NOT point at `GJSIFY_INSTALL_BACKEND=npm`: that
+    // backend rejects `workspace:` specs (`EUNSUPPORTEDPROTOCOL`), which is exactly
+    // what the repos reaching this branch have.
     const pnpResidue = ['.pnp.cjs', '.pnp.loader.mjs'].filter((f) => existsSync(join(cwd, f)));
     if (pnpResidue.length > 0) {
         throw new Error(`gjsify install uses the node_modules linker and cannot run in a Yarn PnP ` +
@@ -509,14 +443,10 @@ async function projectInstallNative(args, signal) {
             `• If instead you want Yarn to manage dependencies, set \`nodeLinker: node-modules\` ` +
             `in .yarnrc.yml and run \`yarn install\` (not \`gjsify install\`).`);
     }
-    // Workspace install (no args). Runs from the root, OR from any workspace
-    // child — npm/yarn/pnpm resolve the monorepo root when you `install`
-    // inside a member, so `findWorkspaceRoot` walks up from cwd (sanity-checked
-    // that cwd is actually one of that root's workspaces) and installs the whole
-    // workspace there. Without this, a child install treats the child as the
-    // root and tries to resolve its `workspace:`/sibling deps from the registry.
-    // Project-local `gjsify install <pkg>` inside a child still adds the dep to
-    // that child via the single-package path below (this branch is no-args only).
+    // Workspace install (no args), from the root OR from any member — npm/yarn/pnpm
+    // all resolve the monorepo root when you `install` inside a member. Without the
+    // walk up, a child install treats the child as the root and tries to resolve
+    // its `workspace:`/sibling deps from the registry.
     if (!args.packages || args.packages.length === 0) {
         const wsRoot = isWorkspaceRoot(cwd) ? cwd : findWorkspaceRoot(cwd);
         if (wsRoot) {
@@ -531,10 +461,9 @@ async function projectInstallNative(args, signal) {
     const pkg = readPackageJson(pkgPath);
     const existingSpecs = pkg ? projectSpecsFromPackageJson(pkg) : [];
     if (args.packages && args.packages.length > 0) {
-        // Combine new specs with existing manifest deps so a single
-        // `gjsify install <new>` doesn't churn the lockfile (would drop
-        // every previously-pinned entry otherwise). New specs with the
-        // same name as an existing dep override.
+        // Combine new specs with the existing manifest deps: resolving the new ones
+        // alone would drop every previously-pinned lockfile entry. A new spec
+        // overrides an existing dep of the same name.
         const newNames = new Set(args.packages.map((s) => parseSpec(s).name));
         const carryover = existingSpecs.filter((s) => !newNames.has(parseSpec(s).name));
         specs = [...carryover, ...args.packages];
@@ -550,28 +479,24 @@ async function projectInstallNative(args, signal) {
         }
     }
     mkdirSync(cwd, { recursive: true });
-    // Progress bar is auto-enabled when stderr is a TTY (and `--verbose` /
-    // `--quiet` / `--no-progress` aren't set). When piped to a log file the
-    // reporter falls back to one line per phase begin/end.
     const progress = makeProgressReporter({
         enabled: !args.verbose && !args.quiet && args.progress !== false,
     });
-    // Hold the per-prefix lock across the install AND the manifest/lockfile
-    // sync that follows, so a concurrent `gjsify install <pkg>` in the same
-    // project can't interleave its package.json / gjsify-lock.json writes
-    // with ours. `installPackages` re-acquires the same lock re-entrantly.
+    // Held across the install AND the manifest/lockfile sync that follows, so a
+    // concurrent `gjsify install <pkg>` in the same project cannot interleave its
+    // package.json / gjsify-lock.json writes with ours. `installPackages`
+    // re-acquires the same lock re-entrantly.
     const lock = await acquireInstallLock(cwd, { signal });
     try {
-        // Typed as NativeInstallOptions so the native-backend-only
-        // `optionalSpecs` is CHECKED at this call site instead of being smuggled
-        // past an object-literal excess-property check; `installPackages`
-        // forwards the object to that backend unchanged.
+        // Typed as NativeInstallOptions so the native-backend-only `optionalSpecs`
+        // is CHECKED here instead of smuggled past an excess-property check;
+        // `installPackages` forwards the object to that backend unchanged.
         const nativeOpts = {
             prefix: cwd,
             specs,
             verbose: args.verbose,
-            // --immutable consumes the lockfile verbatim and must NOT rewrite
-            // it (the whole point is byte-stability under CI).
+            // --immutable consumes the lockfile verbatim and must NOT rewrite it:
+            // byte-stability under CI is the point.
             lockfile: !args.immutable,
             frozen: args.immutable,
             refreshLockfile: args['refresh-lockfile'],
@@ -586,9 +511,8 @@ async function projectInstallNative(args, signal) {
             ]),
         };
         const result = await installPackages(nativeOpts);
-        // Update package.json only when the user passed explicit packages
-        // (the `gjsify install <pkg>...` add-a-dep flow). The no-args refresh
-        // flow doesn't mutate manifest entries.
+        // Only the `gjsify install <pkg>...` add-a-dep flow mutates the manifest;
+        // the no-args refresh must not.
         if (args.packages && args.packages.length > 0 && pkg) {
             const kind = depKindFromArgs(args);
             for (const spec of args.packages) {
@@ -598,12 +522,10 @@ async function projectInstallNative(args, signal) {
                 addDependencyEntry(pkg, name, finalRange, kind);
             }
             writePackageJson(pkgPath, pkg);
-            // Re-sync the lockfile's `requested` field with what
-            // `projectSpecsFromPackageJson()` will return on the next
-            // invocation. Without this, a `gjsify install foo` (bare name,
-            // lockfile records `"foo"`) followed by `gjsify install
-            // --immutable` (reads package.json → spec `"foo@^1.2.3"`) would
-            // surface a spurious drift error.
+            // Re-sync `requested` with what `projectSpecsFromPackageJson()` returns
+            // next time. Without this, `gjsify install foo` (bare name, lockfile
+            // records `"foo"`) followed by `gjsify install --immutable` (reads
+            // package.json → `"foo@^1.2.3"`) reports a spurious drift error.
             if (!args.immutable) {
                 syncLockfileRequested(cwd, projectSpecsFromPackageJson(pkg));
             }
@@ -625,40 +547,31 @@ function syncLockfileRequested(cwd, specs) {
             return; // Already in sync; preserve byte-stability.
         }
         lock.requested = specs;
-        // Atomic tmp+rename — same rationale as the backend's lockfile
-        // writer: a torn gjsify-lock.json breaks the next `--immutable`.
+        // Atomic tmp+rename: a torn gjsify-lock.json breaks the next `--immutable`.
         atomicWriteStrict(lockPath, JSON.stringify(lock, null, 2) + '\n');
     }
     catch {
-        // Best-effort sync; if the lockfile is malformed, the next
-        // non-immutable install will rewrite it from scratch.
+        // Best-effort; a malformed lockfile is rewritten from scratch by the next
+        // non-immutable install.
     }
 }
 /**
- * Workspace-aware install. Mirrors what `yarn install` does at a monorepo root:
- *   1. Discover every workspace under the root.
- *   2. Aggregate the union of their external (non-`workspace:`) deps.
- *   3. Run the native install backend ONCE at the root prefix so all
- *      externals land in a single `node_modules/` (poor-man's hoisting —
- *      workspaces with conflicting ranges of the same dep share one hoisted
- *      copy; the resolver emits a loud `[gjsify] warning: version conflict`
- *      naming both sides and the version that won).
- *   4. For every `workspace:` reference, symlink the target workspace's
- *      directory into the requesting workspace's `node_modules/<dep>`
- *      so `import '@gjsify/utils'` resolves to the local source.
+ * Workspace-aware install, mirroring `yarn install` at a monorepo root: discover
+ * the members, aggregate their external (non-`workspace:`) deps, install them
+ * ONCE at the root prefix, and symlink every workspace-named dep to the local
+ * source so `import '@gjsify/utils'` resolves there.
  *
- * Hoisting strategy is intentionally minimal — per-workspace dedup +
- * nested `node_modules/` for cross-workspace version conflicts are the
- * Phase D.8 follow-up tracked in status/open-todos.md.
+ * Hoisting is deliberately minimal — members with conflicting ranges of the same
+ * dep share one hoisted copy and the resolver warns. Per-member dedup and nested
+ * `node_modules/` are the open Phase D.8 item in status/open-todos.md.
  */
 async function workspaceInstall(cwd, args, signal) {
-    // Hold the root-prefix lock for the WHOLE workspace flow: bin shims,
-    // workspace symlinks and the external install all mutate the root
-    // node_modules/, and a second concurrent workspace install interleaving
-    // its rm+symlink/extract steps with ours corrupts both. The inner
-    // `installPackages` calls re-acquire the same lock re-entrantly (root
-    // prefix) or take the child-workspace lock (scoped overrides) — always
-    // in root→child order, so there is no lock-ordering cycle.
+    // Held for the WHOLE flow: bin shims, workspace symlinks and the external
+    // install all mutate the root node_modules/, and a second concurrent workspace
+    // install interleaving its rm+symlink/extract steps corrupts both. The inner
+    // `installPackages` calls re-acquire this lock re-entrantly, or take the
+    // child-workspace lock for scoped overrides — always root→child, so there is
+    // no lock-ordering cycle.
     const lock = await acquireInstallLock(cwd, { signal });
     try {
         await workspaceInstallLocked(cwd, args, signal);
@@ -675,9 +588,8 @@ async function workspaceInstallLocked(cwd, args, signal) {
     }
     const byName = new Map(workspaces.map((w) => [w.name, w]));
     const externalSpecs = new Set();
-    // Which workspace(s) declared each external spec — `"<name>@<range>"` →
-    // workspace names. Feeds the resolver's version-conflict warning so it
-    // can attribute both sides of a cross-workspace range conflict.
+    // `"<name>@<range>"` → the members that declared it. Feeds the resolver's
+    // version-conflict warning so it can attribute both sides of a conflict.
     const specOrigins = new Map();
     const symlinks = [];
     for (const ws of workspaces) {
@@ -689,23 +601,16 @@ async function workspaceInstallLocked(cwd, args, signal) {
             for (const [depName, spec] of Object.entries(block)) {
                 if (typeof spec !== 'string')
                     continue;
-                // A dependency whose NAME matches a local workspace is always
-                // satisfied by that workspace — never by a same-named package on
-                // npm. This holds regardless of the spec form: an explicit
-                // `workspace:` protocol, a plain semver range (`^1.2.3`), or even
-                // a dist-tag. Yarn/npm resolve a workspace-named dep to the local
-                // package first; we MUST do the same. Routing such a dep into the
-                // native fetch/extract queue is the data-loss bug this guards
-                // against — `extractOne` would `rmSync` + drop the published
-                // tarball over the workspace's OWN source tree (the published
-                // tarball ships only `files`, so `src/**` gets wiped). Symlink
-                // it instead, exactly like a `workspace:` ref.
+                // A dep whose NAME matches a local workspace is always satisfied by
+                // that workspace, never by a same-named package on npm — whatever
+                // the spec form (`workspace:`, `^1.2.3`, a dist-tag), because that
+                // is what yarn/npm do. Routing one into the fetch/extract queue is a
+                // DATA-LOSS bug: `extractOne` would `rmSync` the workspace's own
+                // source tree and unpack the published tarball over it, and that
+                // tarball ships only `files`, so `src/**` is wiped.
                 const localWorkspace = byName.get(depName);
                 if (localWorkspace) {
-                    // Only an EXPLICIT out-of-workspace protocol (link:/file:/
-                    // portal:/git+/http(s):) opts out of the local workspace. Any
-                    // other shape — `workspace:` or a plain semver range/dist-tag
-                    // (`^1.2.3`, `*`, `latest`) — resolves to the local package.
+                    // Only an EXPLICIT out-of-workspace protocol opts out.
                     const explicitOverride = /^(link|file|portal|git\+|https?):/.test(spec);
                     if (!explicitOverride) {
                         symlinks.push({
@@ -715,11 +620,10 @@ async function workspaceInstallLocked(cwd, args, signal) {
                         });
                         continue;
                     }
-                    // explicit override → fall through to the existing handling.
                 }
                 if (spec.startsWith('workspace:')) {
-                    // `workspace:` against a name that is NOT a discovered
-                    // workspace is a hard error (typo / missing package).
+                    // `workspace:` against a name that is not a discovered workspace
+                    // is a hard error (typo / missing package).
                     throw new Error(`gjsify install: ${ws.name} declares "${depName}: ${spec}" but ` +
                         `no workspace with that name exists`);
                 }
@@ -737,31 +641,21 @@ async function workspaceInstallLocked(cwd, args, signal) {
         }
     }
     console.log(`gjsify install: ${workspaces.length} workspace(s), ${externalSpecs.size} external dep spec(s), ${symlinks.length} workspace symlink(s)`);
-    // Write workspace bin shims EARLY — before the download/extract phase.
-    // The shims are cheap derived artifacts (workspace manifests only), and
-    // the heavy phase that follows can fail or die mid-way (network errors,
-    // timeouts, runtime crashes). Writing them up-front guarantees the
-    // workspace never loses its runner shim (`node_modules/.bin/gjsify`) to
-    // a failed install, and an in-place re-install on an already-materialized
-    // tree refreshes a stale shim even when a later phase aborts. The same
-    // shims are re-written at the end of this function so the GJS-preamble
-    // (GI_TYPELIB_PATH for native prebuilds) reflects the freshly installed
-    // tree — see the final `writeWorkspaceBinShims` call below.
+    // EARLY, before the download/extract phase: the shims derive from workspace
+    // manifests alone, while the heavy phase that follows can die mid-way (network,
+    // timeout, crash). Writing them up front means a failed install can never leave
+    // the workspace without its runner shim (`node_modules/.bin/gjsify`), and a
+    // stale shim is refreshed even when a later phase aborts. Rewritten at the end
+    // of this function so the GJS preamble reflects the installed tree.
     writeWorkspaceBinShims(cwd, workspaces);
-    // Materialise the workspace↔workspace symlinks: per-requester links
-    // (`<requester>/node_modules/<dep>`) plus a root hoist of every workspace
-    // into `node_modules/<name>` so transitive workspace deps resolve via
-    // Node's parent-walk from any descendant. Idempotent (rm + symlink, and
-    // the hoist skips entries that already exist), so it's safe to run more
-    // than once.
+    // Per-requester links (`<requester>/node_modules/<dep>`) plus a root hoist of
+    // every workspace into `node_modules/<name>`, so transitive workspace deps
+    // resolve by Node's parent-walk from any descendant. Idempotent, hence callable
+    // more than once.
     const wireWorkspaceSymlinks = async () => {
-        // Per-requester symlinks — pre-dedup the parent-dir mkdirs (every
-        // symlink for the same workspace shares a single `node_modules`
-        // parent), then run the per-link rm + symlink steps with bounded
-        // concurrency. Pure sync loops here used to dominate the tail of large
-        // installs (~793 symlinks × ~10ms each for mkdir+rm+symlink = ~24s of
-        // serial syscalls). With async + a 32-wide pool the same set lands in
-        // 1-2s.
+        // Bounded-concurrency async, because the sync version dominated the tail of
+        // large installs: ~793 symlinks × ~10 ms of mkdir+rm+symlink is ~24 s of
+        // serial syscalls, versus 1-2 s with a 32-wide pool.
         if (symlinks.length > 0) {
             const fsp = await import('node:fs/promises');
             const parentDirs = new Set();
@@ -775,25 +669,20 @@ async function workspaceInstallLocked(cwd, args, signal) {
                 const relTarget = workspaceLinkTarget(linkPath, link.targetLocation);
                 plans.push({ linkPath, relTarget });
             }
-            // Phase 1: one mkdir per unique parent (max ~213 instead of ~793).
+            // One mkdir per unique parent — ~213 instead of ~793.
             await Promise.all([...parentDirs].map((dir) => fsp.mkdir(dir, { recursive: true })));
-            // Phase 2: per-link rm + symlink, pooled. A semaphore-style cursor
-            // keeps the concurrent in-flight count bounded so we don't blow up
-            // the file-descriptor table on huge monorepos.
+            // Bounded so a huge monorepo cannot blow up the fd table.
             const SYMLINK_CONCURRENCY = 32;
             let cursor = 0;
             const workers = [];
             const wireOne = async (linkPath, relTarget) => {
-                // Remove any prior entry — regular dir, broken symlink, file,
-                // or a normal symlink left over from a previous install.
-                // `{ recursive: true, force: true }` handles every shape (rm
-                // no-ops on missing paths under force; recursive covers dirs).
+                // Clear any prior entry of any shape — dir, file, broken or live
+                // symlink; `{ recursive, force }` covers all of them.
                 try {
                     await fsp.rm(linkPath, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
                 }
                 catch {
-                    /* unexpected; symlink call below will surface the real
-                       cause if it persists. */
+                    /* the symlink call below surfaces the real cause if it persists */
                 }
                 await fsp.symlink(relTarget, linkPath, WORKSPACE_LINK_TYPE);
             };
@@ -813,37 +702,27 @@ async function workspaceInstallLocked(cwd, args, signal) {
             await Promise.all(workers);
             console.log(`gjsify install: wired ${symlinks.length} workspace symlink(s)`);
         }
-        // Hoist EVERY workspace package to the repo root's `node_modules/` so
-        // transitive workspace deps are reachable from any descendant via
-        // standard Node parent-walk resolution. yarn's `nodeLinker:
-        // node-modules` does the same thing — the entire workspace graph is
-        // materialised at the root, which is how rolldown's resolver finds
-        // e.g. `@gjsify/abort-controller/register` injected from a
-        // deeply-nested package's `node_modules/.cache/gjsify/` cache file
-        // when the consumer didn't declare a direct dep on it (auto-globals
-        // injection at build time).
-        //
-        // Without this hoist, each workspace's `node_modules/` only contains
-        // its direct declared deps, and any auto-injected register import for
-        // a workspace package the consumer didn't list as a dep externalises
-        // and the bundle fails at runtime with `Module not found`.
+        // Hoist EVERY workspace package to the root `node_modules/`, like yarn's
+        // `nodeLinker: node-modules`, so the whole graph is reachable from any
+        // descendant by parent-walk. Without it a member's `node_modules/` holds
+        // only its declared deps, and an auto-injected register import for an
+        // undeclared workspace package (auto-globals injection at build time, e.g.
+        // `@gjsify/abort-controller/register`) externalises and the bundle fails at
+        // runtime with `Module not found`.
         const rootBinDir = join(cwd, 'node_modules');
         let rootHoisted = 0;
         for (const ws of workspaces) {
-            // Skip the root workspace itself (its location IS cwd; it can't
-            // symlink itself into its own node_modules).
+            // The root workspace cannot symlink itself into its own node_modules.
             if (ws.location === cwd)
                 continue;
             if (!ws.name)
                 continue;
             const linkPath = join(rootBinDir, ws.name);
-            // If a symlink already exists here (from the per-requester loop
-            // above when the root workspace declared this dep directly), it
-            // already points at the right place — skip. We don't try to
-            // remove + recreate because under GJS's Gio-backed fs polyfill,
-            // `rmSync` on a symlink can race with `symlinkSync` and surface
-            // EEXIST. A real directory at this path is also left alone —
-            // someone else (npm, yarn) seeded it and we shouldn't clobber.
+            // An existing symlink here (from the per-requester loop above) already
+            // points at the right place. Deliberately not remove+recreate: under
+            // GJS's Gio-backed fs polyfill `rmSync` on a symlink can race
+            // `symlinkSync` and surface EEXIST. A real directory is left alone too —
+            // npm or yarn seeded it and clobbering it is not ours to do.
             let existsHere = false;
             try {
                 lstatSync(linkPath);
@@ -862,35 +741,23 @@ async function workspaceInstallLocked(cwd, args, signal) {
             console.log(`gjsify install: hoisted ${rootHoisted} workspace(s) to root node_modules/`);
         }
     };
-    // Wire workspace↔workspace symlinks EARLY too — same rationale as the bin
-    // shims. These symlinks point at local workspace source trees and never
-    // depend on the external download, yet they USED to run only at the tail
-    // of the install. An interrupted/timed-out external fetch then left the
-    // tree with NO workspace symlinks at all, so cross-package imports
-    // (`@gjsify/native-fs-bridge` → `@gjsify/native-platform`) failed to
-    // resolve even though every package was on disk. Materialising them here
-    // makes workspace resolution survive a failed external phase. Safe to run
-    // before `installPackages`: that phase only fetches NON-workspace names
-    // (workspace-named deps are routed to symlinks and excluded from
-    // `externalSpecs`), and `extractOne` only `rm`s the individual external
-    // package dest it is about to write — never a workspace symlink.
+    // EARLY too, for the same reason as the bin shims: these links point at local
+    // source and never depend on the external download, but when they ran only at
+    // the tail, an interrupted external fetch left the tree with NO workspace
+    // symlinks, so cross-package imports failed to resolve even with every package
+    // on disk. Safe here because `installPackages` only fetches NON-workspace names
+    // (workspace-named deps are excluded from `externalSpecs`), and `extractOne`
+    // only `rm`s the one external dest it is about to write.
     await wireWorkspaceSymlinks();
-    // Read top-level package.json's `overrides` (npm-native) or `resolutions`
-    // (yarn-native, kept as the existing field name in pre-Phase-D.8 repos).
-    // Flat `name → range` entries become global overrides applied to every
-    // workspace; nested `<workspace> → {dep → range}` entries become
-    // workspace-local installs that place the overridden dep inside that
-    // workspace's own `node_modules/`. Lets a monorepo pin one workspace to
-    // an older `typescript` (e.g. a downstream integration test) without
-    // forcing the rest of the tree to the same version.
+    // `overrides` (npm) / `resolutions` (yarn). Flat `name → range` entries apply to
+    // every member; nested `<workspace> → {dep → range}` entries become
+    // workspace-local installs, so a monorepo can pin one member to an older
+    // `typescript` without dragging the rest of the tree along.
     const rootManifest = workspaces.find((w) => w.location === cwd)?.manifest;
     const extracted = extractOverrides(rootManifest);
     const overrides = extracted?.global;
-    // Second pass: pluck specs that have a workspace-scoped override out of
-    // `externalSpecs` and re-collect them into a per-workspace map. Those
-    // specs will be installed into the workspace's own `node_modules/` after
-    // the root install completes, so the resolver in the root pass does NOT
-    // see the conflicting versions.
+    // Move specs carrying a workspace-scoped override out of `externalSpecs` into a
+    // per-workspace map, so the root resolver never sees the conflicting versions.
     const wsLocalSpecs = new Map(); // wsLocation → name@range set
     const droppedFromExternal = new Set();
     if (extracted && extracted.scoped.size > 0) {
@@ -904,7 +771,6 @@ async function workspaceInstallLocked(cwd, args, signal) {
                     const override = scopedOverrideFor(ws, depName, extracted);
                     if (!override)
                         continue;
-                    // Re-route this dep to the workspace's own install
                     const targetRange = override;
                     const wsKey = ws.location;
                     let bucket = wsLocalSpecs.get(wsKey);
@@ -913,17 +779,14 @@ async function workspaceInstallLocked(cwd, args, signal) {
                         wsLocalSpecs.set(wsKey, bucket);
                     }
                     bucket.add(`${depName}@${targetRange}`);
-                    // Drop the un-overridden version from the root spec set:
-                    // the workspace will see its scoped version via parent-walk
-                    // resolution. Note we only drop the EXACT `name@spec` the
-                    // workspace declared; other workspaces' instances of the
-                    // same name+spec stay in the root set.
+                    // Only the EXACT `name@spec` this member declared is dropped from
+                    // the root set; other members' instances of the same pair stay.
                     droppedFromExternal.add(`${depName}@${spec}`);
                 }
             }
         }
-        // Apply the drops only when no OTHER workspace declared the same spec
-        // — otherwise it has legitimate root requesters and must stay.
+        // Only drop a spec no OTHER member declared — otherwise it still has
+        // legitimate root requesters.
         const stillNeeded = new Set();
         for (const ws of workspaces) {
             for (const kind of ['dependencies', 'devDependencies', 'optionalDependencies']) {
@@ -959,15 +822,14 @@ async function workspaceInstallLocked(cwd, args, signal) {
             overrides,
             signal,
             progress,
-            // Workspace-named packages are symlinked above — the native backend
-            // must never fetch a same-named published version over those
-            // symlinks (e.g. a `types-dev/<lib>` workspace that also exists on
-            // npm and is pinned transitively in the lockfile).
+            // Workspace-named packages are symlinked above; the backend must never
+            // fetch a same-named published version over those symlinks (e.g. a
+            // `types-dev/<lib>` workspace that also exists on npm and is pinned
+            // transitively in the lockfile).
             workspaceNames: new Set(byName.keys()),
             specOrigins: new Map([...specOrigins].map(([k, v]) => [k, [...v]])),
-            // Aggregated over EVERY member: the specs are aggregated the same
-            // way, so the optional-vs-required answer has to be too (a name that
-            // any member declares as a plain dependency stays required).
+            // Aggregated over EVERY member, because the specs are: a name any member
+            // declares as a plain dependency stays required.
             optionalSpecs: optionalDependencyNames(workspaces.map((w) => w.manifest)),
         };
         await installPackages(rootOpts);
@@ -975,10 +837,8 @@ async function workspaceInstallLocked(cwd, args, signal) {
     else if (args.verbose) {
         console.log('gjsify install: no external deps to fetch');
     }
-    // Workspace-local installs for scoped overrides. Each runs as its own
-    // `installPackages` call inside the workspace location — the resulting
-    // `node_modules/<dep>` shadows the root-hoisted version via standard
-    // Node parent-walk resolution.
+    // Scoped overrides, one `installPackages` per member: the resulting
+    // `node_modules/<dep>` shadows the root-hoisted version by parent-walk.
     for (const [wsLocation, specSet] of wsLocalSpecs) {
         if (specSet.size === 0)
             continue;
@@ -990,34 +850,26 @@ async function workspaceInstallLocked(cwd, args, signal) {
             prefix: wsLocation,
             specs: [...specSet],
             verbose: args.verbose,
-            // Per-workspace installs get a thin lockfile next to the workspace
-            // package.json. Same `--immutable` semantics as the root install.
+            // A thin lockfile next to the member's package.json, same `--immutable`
+            // semantics as the root install.
             lockfile: !args.immutable,
             frozen: args.immutable,
             signal,
             workspaceNames: new Set(byName.keys()),
-            // Same aggregated answer as the root install: these specs are a
-            // SUBSET of the root's, so classifying them differently here would
-            // make one dep optional at the root and required in a member.
+            // Same aggregated answer as the root install: these specs are a SUBSET of
+            // the root's, so classifying them differently would make one dep optional
+            // at the root and required in a member.
             optionalSpecs: optionalDependencyNames(workspaces.map((w) => w.manifest)),
         };
         await installPackages(scopedOpts);
     }
-    // Re-wire workspace symlinks once more now that the external + scoped
-    // installs are done. The EARLY pass above already created them so workspace
-    // resolution survives a failed external phase; this final idempotent pass
-    // is a cheap safety net in case any later step disturbed one (the per-link
-    // rm+symlink re-establishes them, the root hoist skips entries that already
-    // exist — so it's a near no-op when nothing changed).
+    // A near no-op safety net in case a later step disturbed a link.
     await wireWorkspaceSymlinks();
-    // Re-write workspace bins into `node_modules/.bin/` now that the tree is
-    // fully materialized. The early pass at the top of this function already
-    // guaranteed the shims exist; this final pass refreshes their GJS-preamble
-    // with the native prebuild dirs that only became discoverable after the
-    // install (fresh checkout: `detectNativePackages` finds nothing before the
-    // packages are extracted). Running last also keeps workspace shims
-    // authoritative over any same-named external bin linked by the install
-    // backend (yarn semantics: workspace bins win).
+    // Now that the tree is materialised, refresh the shims' GJS preamble with the
+    // native prebuild dirs that only became discoverable after the install (on a
+    // fresh checkout `detectNativePackages` finds nothing before extraction).
+    // Running last also keeps workspace shims authoritative over any same-named
+    // external bin the backend linked — yarn semantics: workspace bins win.
     const wsBinsCreated = writeWorkspaceBinShims(cwd, workspaces);
     if (wsBinsCreated > 0) {
         console.log(`gjsify install: linked ${wsBinsCreated} workspace bin(s) into node_modules/.bin/`);
@@ -1025,47 +877,32 @@ async function workspaceInstallLocked(cwd, args, signal) {
 }
 /**
  * (Re)write the shell shims for every workspace-declared bin into the root
- * `node_modules/.bin/`. Without this, `npm run <script>` (or any
- * `node_modules/.bin`-PATH consumer) cannot find the `gjsify` binary on a
- * fresh checkout — yarn creates these shims at install time; we match.
+ * `node_modules/.bin/`. Without them `npm run <script>` — or any
+ * `node_modules/.bin`-on-PATH consumer — cannot find `gjsify` on a fresh
+ * checkout; yarn writes these at install time and we match.
  *
- * Each workspace's `bin` entry maps `<binName>` → `<relative-target>`.
- * For GJS-runnable bins, `gjsify.bin` is preferred — its target is the
- * committed `dist/cli.gjs.mjs` bundle that exists on a fresh checkout,
- * versus the `bin` field which typically points at `lib/index.js`
- * (a build artifact that may not yet exist). The shim wraps the
- * target in a shell script that picks the right interpreter (`gjs -m`
- * for `.mjs` bundles, `node` for `.js` files).
+ * `gjsify.bin` is preferred for the GJS target because it names the committed
+ * `dist/cli.gjs.mjs` bundle, which exists on a fresh checkout, while `bin`
+ * typically names `lib/index.js`, a build artifact that may not.
  *
- * IDEMPOTENT + UNCONDITIONAL: shims are derived artifacts and are always
- * regenerated — never skipped because a file already exists, never a
- * failure because one is missing. `workspaceInstall` calls this twice:
- * once BEFORE the download/extract phase (so a failed/aborted install can
- * never leave the workspace without its runner shim, and a stale shim is
- * refreshed even when a later phase dies) and once after (to pick up
- * native prebuild dirs that only exist post-extract).
+ * IDEMPOTENT + UNCONDITIONAL: shims are derived artifacts, always regenerated,
+ * never skipped for existing and never fatal for missing. `workspaceInstall`
+ * calls this before AND after the download/extract phase.
  */
 function writeWorkspaceBinShims(cwd, workspaces) {
     const wsBinDir = join(cwd, 'node_modules', '.bin');
-    // Discover native prebuilds reachable from the workspace cwd so the
-    // workspace-local `node_modules/.bin/gjsify` shim sets GI_TYPELIB_PATH /
-    // LD_LIBRARY_PATH for them. Same rationale as the global launcher in
-    // install-global.ts — the bin shim invokes the CLI bundle via `gjs -m`
-    // directly, with no chance to set env after the fact, so without this
-    // preamble `imports.gi.GjsifyTerminal` etc. fail and process.stdout
-    // collapses to no-color, 80-col defaults.
+    // The shim invokes the CLI bundle via `gjs -m` directly, with no chance to set
+    // env after the fact, so GI_TYPELIB_PATH / LD_LIBRARY_PATH have to be in its
+    // preamble — otherwise `imports.gi.GjsifyTerminal` and friends fail and
+    // process.stdout collapses to no-color, 80-col defaults.
     const nativePrebuildDirs = detectNativePackages(cwd).map((p) => p.prebuildsDir);
     let wsBinsCreated = 0;
     for (const ws of workspaces) {
         const m = ws.manifest;
         const gjsifyBin = m.gjsify?.bin;
         const nodeBin = m.bin;
-        // For each bin name, collect both the Node-target and GJS-target
-        // when they exist. The shim prefers Node at invocation time
-        // because Node's child_process is more reliable than GJS's
-        // Gio.Subprocess polyfill (parallel-spawn close-event delivery
-        // races under heavy concurrency); GJS is the fallback for fresh
-        // checkouts where the Node target hasn't been built yet.
+        // Collect both the Node and GJS target per bin name when they exist; which
+        // one the shim tries first is `buildBinShim`'s per-platform decision.
         const merged = mergeWorkspaceBins(ws.name, gjsifyBin, nodeBin);
         if (merged.size === 0)
             continue;
@@ -1082,10 +919,10 @@ function writeWorkspaceBinShims(cwd, workspaces) {
             }
             writeFileSync(linkPath, buildBinShim(ws.location, nodeTarget, gjsTarget, nativePrebuildDirs, process.platform, cwd), { mode: 0o755 });
             chmodSync(linkPath, 0o755);
-            // Windows executes neither an extension-less file nor a `#!` line —
-            // the sh shim above is only reachable from git-bash/MSYS/WSL. Write
-            // the `.cmd`/`.ps1` companions cmd.exe and pwsh need, mirroring what
-            // npm's cmd-shim lays down next to every linked bin.
+            // Windows executes neither an extension-less file nor a `#!` line, so the
+            // sh shim above is reachable only from git-bash/MSYS/WSL. The
+            // `.cmd`/`.ps1` companions are what cmd.exe and pwsh need, mirroring
+            // npm's cmd-shim.
             if (process.platform === 'win32') {
                 for (const [suffix, contents] of Object.entries(buildWorkspaceBinShimsForWindows(ws.location, nodeTarget, gjsTarget, nativePrebuildDirs))) {
                     writeFileSync(`${linkPath}.${suffix}`, contents, { mode: 0o755 });
@@ -1096,6 +933,19 @@ function writeWorkspaceBinShims(cwd, workspaces) {
     }
     return wsBinsCreated;
 }
+/**
+ * Flatten npm `overrides` / yarn `resolutions` into a bare name → range map,
+ * accepting both `{ "typescript": "~5.9.2" }` and yarn's pattern form
+ * `{ "typescript@*": "~5.9.2" }`.
+ *
+ * Pattern keys with a version glob are normalised to the bare name because the
+ * resolver has no per-incoming-range scoping. npm's per-parent nested shape
+ * (`"foo": { ".": "1.0", "bar": "2.0" }`) is warned about rather than
+ * half-applied, since without per-parent support it would misbehave silently.
+ *
+ * Keys beginning with `_` are skipped — the in-the-wild convention for
+ * documentation entries like `"_comment_typescript"`.
+ */
 function extractOverrides(rootManifest) {
     if (!rootManifest)
         return undefined;
@@ -1108,9 +958,8 @@ function extractOverrides(rootManifest) {
             if (key.startsWith('_'))
                 continue;
             if (typeof value === 'string') {
-                // Flat `name → range` entry. Normalise pattern keys (`name@*`,
-                // `name@^range`) → bare name. For scoped packages preserve the
-                // leading `@`.
+                // Normalise pattern keys (`name@*`, `name@^range`) to the bare name,
+                // preserving the leading `@` of a scoped package.
                 let name = key;
                 const atIdx = key.startsWith('@') ? key.indexOf('@', 1) : key.indexOf('@');
                 if (atIdx > 0)
@@ -1119,9 +968,8 @@ function extractOverrides(rootManifest) {
                 continue;
             }
             if (value && typeof value === 'object' && !Array.isArray(value)) {
-                // Scoped entry — `<workspace> → {dep → range}`. This is the
-                // npm-overrides nested shape and yarn's resolutions
-                // selectors collapsed to per-workspace level.
+                // `<workspace> → {dep → range}`: npm's nested overrides shape and
+                // yarn's resolutions selectors, collapsed to per-workspace level.
                 const sub = {};
                 for (const [depKey, depValue] of Object.entries(value)) {
                     if (depKey.startsWith('_'))
@@ -1151,10 +999,7 @@ function extractOverrides(rootManifest) {
         return undefined;
     return { global, scoped };
 }
-/**
- * Look up the scoped override for a given workspace + dep. Matches by
- * workspace name OR relative location (both accepted for readability).
- */
+/** Scoped override for a workspace + dep, matched by name OR relative location. */
 function scopedOverrideFor(ws, depName, extracted) {
     if (!extracted || extracted.scoped.size === 0)
         return undefined;
@@ -1166,66 +1011,45 @@ function scopedOverrideFor(ws, depName, extracted) {
     }
     return undefined;
 }
+/**
+ * Build the `sh` shim for one bin. Which interpreter it tries first is decided
+ * per platform below; the probe is per-INVOCATION, not per-install, so the same
+ * shim works before and after the workspace's `lib/` has been built.
+ *
+ * Both targets are absolute so the shim survives the different cwds consumers
+ * (`yarn run`, `npm run`, a direct PATH invocation) call it from.
+ */
 export function buildBinShim(wsLocation, nodeTarget, gjsTarget, nativePrebuildDirs = [], platform = process.platform, scanRoot = wsLocation) {
     const nodeAbs = nodeTarget ? join(wsLocation, nodeTarget) : null;
     const gjsAbs = gjsTarget ? join(wsLocation, gjsTarget) : null;
-    // GJS-only env preamble — Node ignores GI_TYPELIB_PATH so we scope the
-    // export to the gjs branch, keeping the shim minimal when no native pkgs
-    // exist or only the Node bin is in play.
+    // Scoped to the gjs branch because Node ignores GI_TYPELIB_PATH.
     //
-    // `scanRoot` is the INSTALL prefix (the tree holding `node_modules/.bin`),
-    // not the workspace package dir: the preamble globs its `node_modules` at
-    // launch time instead of embedding what was installed the day the shim was
-    // written, so `gjsify install <some>-native` afterwards is picked up without
-    // a re-link. See `buildNativeEnvPreamble`.
+    // `scanRoot` is the INSTALL prefix (the tree holding `node_modules/.bin`), not
+    // the workspace package dir: `buildNativeEnvPreamble` globs its `node_modules`
+    // at LAUNCH time rather than embedding what was installed the day the shim was
+    // written, so a later `gjsify install <x>-native` is picked up without a re-link.
     const gjsPreamble = buildNativeEnvPreamble(scanRoot, nativePrebuildDirs, { platform });
     if (nodeAbs && gjsAbs) {
-        // GJS-FIRST: prefer the committed Node-free GJS bundle when `gjs` is on
-        // PATH AND the bundle exists; fall back to the Node entry otherwise (a
-        // Node-only machine, or before the bundle is built). gjsify is
-        // GJS-first but stays fully runnable under Node.
+        // GJS-FIRST by default: gjsify is a GJS-first toolchain that stays fully
+        // runnable under Node. This is only safe because `gjsify run` dispatches a
+        // single `gjsify <cmd>` IN-PROCESS under GJS (see cli-app.ts) instead of
+        // spawning another gjs per script — the earlier gjs-first attempt chained ~5
+        // heavyweight gjs per package and turned a ~83s build into a multi-hour hang
+        // on CI's few cores.
         //
-        // Safe to default to GJS now that the blockers earlier flip attempts
-        // surfaced are all fixed: css-as-string file://-resolve, `foreach`
-        // fail-fast, the @gjsify/tsc lib-refresh race, native-rolldown
-        // node-target externals — and the make-or-break one, the nested-gjs
-        // build thrash: `gjsify run` now dispatches a single `gjsify <cmd>`
-        // script IN-PROCESS under GJS (see cli-app.ts) instead of spawning yet
-        // another gjs, so the build no longer chains ~5 heavyweight gjs per
-        // package and oversubscribes CI's few cores. Verified: the faithful
-        // `foreach build -tp --jobs 4` over @gjsify/* with a piped stdout
-        // completes in ~83s under GJS (was a multi-hour hang).
-        // …EXCEPT on macOS and Windows, where the order is inverted — and not
-        // as a preference but as a capability. GJS is a GNOME-desktop host: on
-        // those two platforms it is at best a Homebrew/MSYS afterthought, while
-        // Node is what a developer already has. The tooling agrees:
+        // macOS and Windows invert the order. Windows is a capability limit: there is
+        // no prebuilt `libgjs` at all (website/src/content/docs/platform-support.md),
+        // so the gjs probe can never succeed, and leading with Node also makes the
+        // `sh` shim agree with the Node-only `.cmd`/`.ps1` companions
+        // {@link buildLauncherShims} writes. macOS is NOT: `@gjsify/rolldown-native`
+        // now ships darwin-arm64 + darwin-x64 prebuilds, so the original reason (no
+        // bundler engine under GJS there, npm `rolldown` being a Rust napi crate GJS
+        // cannot load) has expired, and only the "Homebrew gjs is an afterthought"
+        // preference is left holding `darwin` in this branch.
         //
-        //   - macOS: the only bundler engine under GJS is
-        //     `@gjsify/rolldown-native` (npm `rolldown` is a Rust napi crate
-        //     GJS cannot load), and it declares `linux-x64`/`linux-arm64` only.
-        //     So the gjs branch cannot run `gjsify build`, nor any script that
-        //     ends in one — it dies with "no usable bundler engine under GJS",
-        //     whose own closing line is "Running the build under Node also
-        //     works". Preferring gjs routed the user into a dead end the error
-        //     message tells them to leave while the shim offered no way out.
-        //     Measured on a cold macOS tree: root `build:infra` fails at the
-        //     first `gjsify build --library` (`@gjsify/utils`) with the
-        //     gjs-first shim and completes with this one.
-        //   - Windows: there is no prebuilt `libgjs` at all (see
-        //     `website/src/content/docs/platform-support.md`), so the gjs probe
-        //     can never succeed. This also makes the `sh` shim — the git-bash /
-        //     MSYS entry point — agree with the `.cmd`/`.ps1` companions
-        //     {@link buildLauncherShims} already writes as Node-only, instead
-        //     of leading with a branch that is dead by construction.
-        //
-        // The probe stays symmetric with the gjs one — `command -v node`, not a
-        // bare file test — so a host carrying the bundle but no Node still
-        // falls through to gjs and keeps every non-build command working. That
-        // is what keeps GJS on these platforms supported-and-tested rather than
-        // merely absent. Revert a platform to the shared gjs-first form once it
-        // has a working engine (macOS: status/open-todos.md,
-        // "@gjsify/rolldown-native's darwin-arm64 leg is PROVEN but not
-        // promoted").
+        // The Node probe stays symmetric with the gjs one — `command -v node`, not a
+        // bare file test — so a host carrying the bundle but no Node still falls
+        // through to gjs and keeps every non-build command working.
         const nodeFirstPlatform = platform === 'darwin' || platform === 'win32';
         const gjsFirst = `if command -v gjs >/dev/null 2>&1 && [ -f "${gjsAbs}" ]; then\n` +
             `${gjsPreamble}exec gjs -m "${gjsAbs}" "$@"\n` +
@@ -1246,10 +1070,9 @@ export function buildBinShim(wsLocation, nodeTarget, gjsTarget, nativePrebuildDi
 /**
  * `.cmd` / `.ps1` companions for {@link buildBinShim}.
  *
- * The `sh` shim's gjs-first / node-fallback probe has no Windows counterpart to
- * express: there is no GJS host on Windows at all (no prebuilt `libgjs` — see
- * `website/src/content/docs/platform-support.md`), so a workspace that ships
- * both targets resolves to Node here, and a GJS-only workspace gets an honest
+ * There is no GJS host on Windows at all (no prebuilt `libgjs` — see
+ * `website/src/content/docs/platform-support.md`), so a workspace shipping both
+ * targets resolves to Node here, and a GJS-only workspace gets an honest
  * `gjs`-invoking shim that fails exactly the way the `sh` one does.
  *
  * Exported + platform-free so it is unit-tested from Linux.
@@ -1260,10 +1083,9 @@ export function buildWorkspaceBinShimsForWindows(wsLocation, nodeTarget, gjsTarg
     if (nodeAbs)
         return buildLauncherShims({ interpreter: 'node', target: nodeAbs });
     if (gjsAbs) {
-        // Windows has no dedicated library-path variable — LoadLibrary searches
-        // PATH — so the prebuild dirs go there, `;`-separated (which is also
-        // GLib's G_SEARCHPATH_SEPARATOR on Windows, hence the same join for
-        // GI_TYPELIB_PATH).
+        // Windows has no dedicated library-path variable — LoadLibrary searches PATH
+        // — so the prebuild dirs go there, `;`-separated, which is also GLib's
+        // G_SEARCHPATH_SEPARATOR on Windows, hence the same join for GI_TYPELIB_PATH.
         const joined = nativePrebuildDirs.join(';');
         return buildLauncherShims({
             interpreter: 'gjs',
@@ -1275,10 +1097,8 @@ export function buildWorkspaceBinShimsForWindows(wsLocation, nodeTarget, gjsTarg
     throw new Error('buildWorkspaceBinShimsForWindows: either nodeTarget or gjsTarget must be provided');
 }
 /**
- * Walk a workspace's `bin` (Node) + `gjsify.bin` (GJS) declarations
- * into a unified `<binName> → {nodeTarget?, gjsTarget?}` map. The
- * shim built from this picks Node at runtime when its target exists,
- * GJS otherwise.
+ * Merge a workspace's `bin` (Node) and `gjsify.bin` (GJS) declarations into one
+ * `<binName> → {nodeTarget?, gjsTarget?}` map for {@link buildBinShim}.
  */
 function mergeWorkspaceBins(pkgName, gjsifyBin, nodeBin) {
     const out = new Map();
@@ -1327,11 +1147,10 @@ async function projectInstallViaNpm(args) {
     await spawnNpm(npmArgs);
 }
 async function spawnNpm(npmArgs) {
-    // `completion: 'return'` — the `--backend npm` branch of the handler
-    // RETURNS after `runPostInstallChecks()` instead of exiting, so under GJS
-    // this must not leave the main loop `spawn()` arms parked (see
-    // utils/spawn.ts). The npm backend needs a Node host anyway, so the
-    // blocking path costs nothing in practice.
+    // `completion: 'return'` — the `--backend npm` branch RETURNS after
+    // `runPostInstallChecks()` instead of exiting, so under GJS it must not leave the
+    // main loop arms `spawn()` parks (see utils/spawn.ts). The npm backend needs a
+    // Node host anyway, so the blocking path costs nothing here.
     return spawnToCompletion('npm', npmArgs, {
         completion: 'return',
         notFound: () => new Error('npm not found on PATH — install Node.js first.'),
@@ -1341,9 +1160,8 @@ async function spawnNpm(npmArgs) {
             throw new Error(`npm install exited with code ${code}`);
     })
         .catch((err) => {
-        // A raw spawn failure still carries an errno `code`; the mapped
-        // not-found hint and the non-zero-exit error do not, and already
-        // read as finished sentences.
+        // A raw spawn failure still carries an errno `code`; the mapped not-found
+        // hint and the non-zero-exit error do not, and already read as sentences.
         const errno = err.code;
         console.error(errno === undefined ? err.message : `npm install failed: ${err.message}`);
         process.exit(1);
@@ -1354,11 +1172,10 @@ async function installGlobalAndLink(specs, opts) {
     mkdirSync(layout.prefix, { recursive: true });
     console.log(`gjsify install --global  → ${layout.prefix}`);
     console.log(`                  bins → ${layout.binDir}`);
-    // The global prefix is SHARED user-wide state — two concurrent
-    // `gjsify install -g` runs (e.g. parallel agent sessions bootstrapping
-    // tooling) used to interleave rm+extract on the same package dirs and
-    // race the launcher writes in ~/.local/bin. Hold the prefix lock across
-    // the install, the engine-package top-up AND the bin linking (ADR 0001).
+    // The global prefix is SHARED user-wide state: two concurrent `gjsify install -g`
+    // runs interleaved rm+extract on the same package dirs and raced the launcher
+    // writes in ~/.local/bin. The lock spans the install, the engine top-up AND the
+    // bin linking (ADR 0001).
     const lock = await acquireInstallLock(layout.prefix, {});
     try {
         const result = await installPackages({
@@ -1367,17 +1184,16 @@ async function installGlobalAndLink(specs, opts) {
             verbose: opts.verbose,
         });
         const packageNames = specs.map(specToPackageName);
-        // A global GJS install of `@gjsify/cli` must also lay down the GJS-native
-        // bundler engine (`@gjsify/rolldown-native`) + the sibling format/CSS
-        // bridges. They are declared OPTIONAL peers of `@gjsify/cli` (so plain
-        // `npm install @gjsify/cli` on Node doesn't force a linux prebuild), and
-        // the native backend doesn't resolve peerDependencies at all — so without
-        // this they'd never be installed, and `gjsify build` would hard-fail under
-        // GJS ("no usable bundler engine"). Installed best-effort at the cli's
-        // resolved version so they move in lockstep with the bundle; a platform
-        // with no published prebuild degrades to a warning. Must run BEFORE
-        // linkGlobalBins so the launcher's detectNativePackages() bakes the
-        // engine's prebuild dirs into the wrapper's GI_TYPELIB_PATH/LD_LIBRARY_PATH.
+        // A global install of `@gjsify/cli` must also lay down the GJS bundler engine
+        // + the sibling format/CSS bridges. They are OPTIONAL PEERS of the CLI (so a
+        // plain `npm install @gjsify/cli` on Node does not force a prebuild) and the
+        // native backend does not resolve peerDependencies at all, so without this
+        // they never arrive and `gjsify build` hard-fails under GJS with "no usable
+        // bundler engine". Pinned to the CLI's resolved version so they move in
+        // lockstep with the bundle; a platform with no published prebuild warns.
+        //
+        // Must run BEFORE linkGlobalBins, so the launcher's detectNativePackages()
+        // bakes the engine's prebuild dirs into GI_TYPELIB_PATH/LD_LIBRARY_PATH.
         if (packageNames.includes('@gjsify/cli')) {
             const cliVersion = result.installed.find((r) => r.name === '@gjsify/cli')?.version ?? 'latest';
             await installGjsEnginePackages(layout.prefix, cliVersion, { verbose: opts.verbose });
@@ -1404,6 +1220,42 @@ function reportLinkedBins(created, binDir) {
             `Add it to your shell rc file:\n  export PATH="${binDir}:$PATH"`);
     }
 }
+/**
+ * Lay the GJS bundler engine down after a PROJECT install, when the host will need
+ * it and does not have it (#1005).
+ *
+ * The engine is an OPTIONAL PEER of `@gjsify/cli` on purpose — a plain
+ * `npm install @gjsify/cli` on Node must not fetch prebuilds — but nobody resolves
+ * it for a project: npm 7+ skips optional peers and the native backend does not
+ * resolve `peerDependencies` at all. Under GJS there is no npm `rolldown`
+ * fallback, so `gjsify build` had nothing to load.
+ *
+ * Four conditions, and (b) is the one worth reading:
+ *
+ *   (a) `@gjsify/cli` is in this tree — otherwise the engine has no caller.
+ *   (b) THE HOST CAN RUN GJS, which is NOT the `isGjs()` question. `isGjs()` asks
+ *       which runtime is executing the installer, but the launcher prefers the GJS
+ *       bundle whenever `command -v gjs` succeeds, so a tree installed BY NODE is
+ *       routinely built BY GJS. Gating on the interpreter reproduces #1005 for
+ *       every contributor who installs on Node and builds through the shim.
+ *       `runMinimalChecks()` already probed for gjs, so this costs no extra spawn.
+ *   (c) No engine is already reachable — asked with the same walk the BUILD uses.
+ *   (d) Not `--immutable`: a frozen install cannot acquire what its lockfile does
+ *       not name, so that case warns and installs nothing.
+ *
+ * NOT gated on `gjsify.app` or on "declares a build script": neither failing
+ * consumer declares the former, and the latter means pattern-matching script
+ * bodies, the drifting hand-maintained judgement ADR 0017 rejects by name.
+ * ADR 0020 records the simpler `optionalDependencies` shape that would retire
+ * this policy entirely.
+ *
+ * NOT recorded in the lockfile — `installPackages` writes one only when both
+ * `resolved` and `opts.lockfile` hold — so a consumer's `gjsify-lock.json` is
+ * never rewritten by this; an e2e row pins it. Ordering is free here, unlike the
+ * global path: `buildNativeEnvPreamble` scans the prefix at LAUNCH time, so a shim
+ * written before the engine arrives still exports its dir
+ * (`tests/e2e/global-install-engine/`).
+ */
 export async function ensureProjectGjsEngine(args, gjsFound, deps = {}) {
     const cwd = deps.cwd ?? process.cwd();
     const hasEngine = deps.hasEngineFn ?? hasBundlerEngineInstalled;
@@ -1414,9 +1266,8 @@ export async function ensureProjectGjsEngine(args, gjsFound, deps = {}) {
     if (hasEngine(cwd))
         return;
     if (args.immutable) {
-        // Name the DURABLE fix, not a transient one: a frozen CI install cannot
-        // be repaired by anything that happens at this moment, so the answer is
-        // to put the engine in the lockfile.
+        // Name the DURABLE fix: a frozen CI install cannot be repaired by anything
+        // happening now, so the answer is to put the engine in the lockfile.
         console.warn(`\nWarning: \`gjsify build\` will fail under GJS — ${BUNDLER_ENGINE_PACKAGE} is not installed, and\n` +
             '  --immutable cannot add it (the lockfile does not name it). Declare it so the lockfile carries it:\n' +
             `    gjsify install ${BUNDLER_ENGINE_PACKAGE}\n` +
@@ -1432,7 +1283,6 @@ export async function ensureProjectGjsEngine(args, gjsFound, deps = {}) {
 }
 async function runPostInstallChecks(args) {
     console.log('\n--- gjsify post-install checks ---');
-    // 1. System deps that GJS apps typically need.
     const results = runMinimalChecks();
     const missing = results.filter((r) => !r.found && r.severity === 'required');
     if (missing.length > 0) {
@@ -1448,14 +1298,9 @@ async function runPostInstallChecks(args) {
     else {
         console.log('System dependencies OK.');
     }
-    // 2. Close #1005 before reporting the prebuild set, so the report reflects
-    //    what the tree ACTUALLY has rather than what it had a moment ago.
+    // Before the prebuild report, so the report reflects what the tree ACTUALLY has:
+    // an engine installed a moment ago belongs in the "Detected N …" list.
     await ensureProjectGjsEngine(args, results.find((r) => r.id === 'gjs')?.found ?? false);
-    // 3. Surface @gjsify/* packages with native prebuilds — `gjsify run`
-    //    will set LD_LIBRARY_PATH / GI_TYPELIB_PATH for these automatically.
-    //    Runs AFTER step 2 on purpose: an engine installed a moment ago belongs
-    //    in this list, and a consumer reading "Detected N …" needs it to be the
-    //    tree's current state rather than its state on entry.
     const native = detectNativePackages(process.cwd());
     if (native.length > 0) {
         console.log(`\nDetected ${native.length} @gjsify/* package(s) with native prebuilds:`);
@@ -1464,37 +1309,28 @@ async function runPostInstallChecks(args) {
         }
         console.log('\nUse `gjsify run <bundle>` to launch with LD_LIBRARY_PATH/GI_TYPELIB_PATH set.');
     }
-    // 3. Install workspace git hooks (only fires inside the gjsify monorepo
-    //    itself, NOT in consumer projects that depend on @gjsify/cli — gated
-    //    by the presence of `scripts/install-git-hooks.mjs` + a `.git`
-    //    checkout). Idempotent; safe to re-run on every install.
     maybeInstallGitHooks();
 }
 /**
- * Wire `core.hooksPath = .githooks` when running `gjsify install` inside a
- * git checkout that ships `scripts/install-git-hooks.mjs` (i.e. the gjsify
- * monorepo). Consumer projects that don't ship the script are skipped
- * silently — they wouldn't have hooks to install.
- *
- * The script itself handles its own no-op cases (extracted tarball, already
- * configured, SKIP_GJSIFY_HOOKS=1).
+ * Wire `core.hooksPath = .githooks` when `gjsify install` runs inside a git
+ * checkout that ships `scripts/install-git-hooks.mjs` — i.e. the gjsify monorepo
+ * and not a consumer project, which has no hooks to install. Idempotent; the
+ * script handles its own no-op cases (extracted tarball, already configured,
+ * `SKIP_GJSIFY_HOOKS=1`).
  */
 function maybeInstallGitHooks() {
     const cwd = process.cwd();
     const scriptPath = join(cwd, 'scripts', 'install-git-hooks.mjs');
     if (!existsSync(scriptPath))
         return;
-    // Need a git checkout — the script also checks, but skipping here
-    // avoids spawning a process when we know the answer.
+    // The script also checks, but skipping here avoids a spawn.
     if (!existsSync(join(cwd, '.git')))
         return;
     try {
         // `nodeBinary()`, NOT `process.execPath`: under the committed GJS bundle
-        // `process.execPath` is `gjs`, so `spawnSync(process.execPath, [script])`
-        // ran `gjs cli.gjs.mjs install-git-hooks.mjs` (wrong argv). The hook
-        // installer is a plain Node ESM script; run it with a real node binary
-        // (PATH `node` under GJS, the current node otherwise). Best-effort —
-        // wrapped in try/catch, so a missing node just warns and continues.
+        // `process.execPath` is `gjs`, so `spawnSync(process.execPath, [script])` ran
+        // `gjs cli.gjs.mjs install-git-hooks.mjs` — wrong argv. The hook installer is
+        // a plain Node ESM script and needs a real node binary.
         const result = spawnSync(nodeBinary(), [scriptPath, '--quiet'], {
             cwd,
             stdio: 'inherit',
@@ -1505,8 +1341,8 @@ function maybeInstallGitHooks() {
         }
     }
     catch (err) {
-        // Hook installation is a quality-of-life touchup, not a hard install
-        // requirement. Never let it abort the surrounding install.
+        // A quality-of-life touchup, not an install requirement — never let it abort
+        // the surrounding install.
         console.warn(`[gjsify install] git hook installation skipped: ${err instanceof Error ? err.message : String(err)}`);
     }
 }