@gjsify/cli 0.25.1 → 0.26.1

package/lib/cli-app.js

@@ -10,7 +10,7 @@
 // build`, and `gjsify run build:types → gjsify tsc → gjs tsc.gjs.mjs`), so on
 // CI's few cores the multiplier oversubscribes and the build thrashes. Letting
 // `gjsify run` dispatch the inner `gjsify <cmd>` in-process collapses two gjs
-// into one. See STATUS.md.
+// into one. See status/open-todos.md.
 //
 // This module MUST NOT execute anything at load time (no top-level
 // `parseAsync`) — `run.ts` imports it, and a top-level run would re-dispatch
@@ -28,15 +28,12 @@ import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
 // GJS's @gjsify/process shim — fake `process.versions.node` for npm
 // compatibility, so a plain Node probe is a false positive on either.
 function runtimeLabel() {
-    try {
-        const sysVersion = gjsSystemVersion();
-        if (sysVersion !== undefined) {
-            const v = Number(sysVersion);
-            return `GJS ${Math.floor(v / 10000)}.${Math.floor((v % 10000) / 100)}.${v % 100} (SpiderMonkey)`;
-        }
-    }
-    catch {
-        /* not GJS */
+    // Off GJS `gjsSystemVersion()` RETURNS undefined (an optional-chained
+    // `globalThis.imports` read, same probe as `isGjs()`) — it never throws.
+    const sysVersion = gjsSystemVersion();
+    if (sysVersion !== undefined) {
+        const v = Number(sysVersion);
+        return `GJS ${Math.floor(v / 10000)}.${Math.floor((v % 10000) / 100)}.${v % 100} (SpiderMonkey)`;
     }
     if (isBun()) {
         const version = globalThis.Bun?.version ?? process.versions.bun;

package/lib/commands/affected.js

@@ -7,15 +7,30 @@
 // up running the touched workspace + its downstream consumers instead of
 // the whole monorepo.
 //
+// EVERY VERDICT THIS FILE EMITS IS SCOPED TO ONE WORKFLOW: `main.yml`. That
+// scoping is the single most misread thing here, so it is stated before the
+// tables rather than after. The classifier is booted only by `main.yml`'s
+// `changes` job, and `main.yml` is the only workflow whose jobs consume its
+// outputs. So "ignored" NEVER means "irrelevant to the repository" — it means
+// "cannot change what `main.yml` builds or tests". Sibling workflows
+// (`prebuilds.yml`, `audit-runtimes.yml`, `node-gi.yml`, `napi.yml`,
+// `deploy-docs.yml`, …) gate themselves with their OWN `paths:` filters and are
+// unaffected by anything decided here. `IGNORE` has always worked this way —
+// `packages/node-gi/**` and `packages/napi/**` are load-bearing build inputs to
+// their own workflows and ignored here — but the table read as a global claim,
+// which is how a directory that is genuinely irrelevant to `main.yml` still
+// looks like something that must not be ignored.
+//
 // Classifier table (first-match wins) handles the cases that aren't a
 // straightforward "file lives in workspace X":
 //
-//   1. IGNORE  — pure-docs / *.md / website / refs/ submodule / unrelated
-//      workflow files / LICENSE / .gitignore. Discarded FIRST, before every
-//      other rule: an ignored file is never build-relevant, not even inside
-//      a GLOBAL_TRIGGERS directory (e.g. `packages/infra/cli/README.md` must
-//      not force a full run just because `packages/infra/cli/` is a global
-//      trigger). Ignore wins over global.
+//   1. IGNORE  — cannot change what `main.yml` builds or tests: pure-docs /
+//      *.md / website / refs/ submodule / other workflows' files and their
+//      inputs / LICENSE / .gitignore. Discarded FIRST, before every other
+//      rule: an ignored file is never build-relevant to this workflow, not
+//      even inside a GLOBAL_TRIGGERS directory (e.g.
+//      `packages/infra/cli/README.md` must not force a full run just because
+//      `packages/infra/cli/` is a global trigger). Ignore wins over global.
 //
 //   2. GLOBAL_TRIGGERS  — a non-ignored change touching infra the classifier
 //      itself depends on (`@gjsify/workspace`, `@gjsify/cli`, the bundler
@@ -24,12 +39,17 @@
 //      can't trust the closure when the algorithm that computes it just
 //      changed.
 //
-//   3. TEST_ONLY  — every changed file under ONE workspace is a spec
+//   3. SCRIPT_COUPLINGS  — a build input that reaches its consumer through a
+//      BUILD SCRIPT instead of a dependency, so the closure walk has no edge
+//      to follow. Contributes EXTRA seeds (and may force a test tier). See
+//      the table for why this cannot be inferred and must be declared.
+//
+//   4. TEST_ONLY  — every changed file under ONE workspace is a spec
 //      file, e2e fixture, or integration test. Seed = that workspace
 //      but SKIP the closure expansion (downstream consumers don't care
 //      about test code changes).
 //
-//   4. CODE (default)  — `workspacesForChangedFiles` maps file → ws,
+//   5. CODE (default)  — `workspacesForChangedFiles` maps file → ws,
 //      then `affectedClosure` walks reverse-dep edges.
 //
 // Integration tests are gated separately: they run when any workspace
@@ -162,13 +182,55 @@ const GLOBAL_TRIGGERS = [
     /^\.github\/workflows\/main\.yml$/,
     /^scripts\/audit-runtimes\.mjs$/,
 ];
+/**
+ * Inputs OWNED BY ANOTHER WORKFLOW — build-relevant, just not to `main.yml`.
+ *
+ * This is the sub-table where the workflow scoping stated at the top of the
+ * file is load-bearing, so each entry NAMES the workflow that does gate it.
+ * The test for membership is not "is this file unimportant" (none of these
+ * are) but "can `main.yml` build or test differently because of it" — and for
+ * every entry the answer is no, while the owning workflow has the path in its
+ * own `paths:` filter and would go red on a break.
+ *
+ * Adding a regex here is therefore a claim with two halves, and BOTH must
+ * hold: `main.yml` must not read the path, and some other workflow must.
+ */
+const OTHER_WORKFLOW_INPUTS = [
+    // Each sibling workflow's own definition. `main.yml` is deliberately
+    // absent — it is a GLOBAL_TRIGGER, since a job-shape change there is
+    // invisible until the workflow re-runs.
+    /^\.github\/workflows\/(deploy-docs|commitlint|release|release-cut|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image)\.yml$/,
+    // `prebuilds.yml`'s toolchain (#838): the QEMU-emulated build script and
+    // the `changed-packages` classifier that decides which native packages a
+    // prebuild run rebuilds. `prebuilds.yml` lists `.github/prebuild-toolchain/**`
+    // in BOTH its `push` and `pull_request` `paths:` filters, so a break here
+    // reds that workflow on the same PR. `main.yml` never executes any of it —
+    // it builds no prebuild and runs no emulated leg.
+    /^\.github\/prebuild-toolchain\//,
+    // The REPO-SCOPED manifest-conformance rules (#847) — `tier`, `refs-pin`,
+    // `platforms-ci` plus the `unchecked-fields` ledger. Their gate is
+    // `audit-runtimes.yml`, which runs `node scripts/audit-runtimes.mjs
+    // --check --strict` on EVERY pull_request with no `paths:` filter at all,
+    // so this content is verified on every PR regardless of what is ignored
+    // here; `prebuilds.yml` additionally declares it a shared input (#843) and
+    // rebuilds every native package when it changes.
+    //
+    // The distinction that makes this safe is a real one, not a technicality:
+    // `main.yml` DOES run manifest-conformance code, but it reaches it through
+    // `scripts/verify-package-outputs.mjs` importing
+    // `packages/infra/manifest-conformance/lib/**` — the PACKAGE, a normal
+    // workspace under the `packages/infra/*` glob that maps and seeds like any
+    // other. Only the `scripts/`-side repo-scoped half is ignored, and that
+    // half is precisely the half `main.yml` does not load.
+    /^scripts\/manifest-conformance\//,
+];
 /** Patterns that contribute no seed and don't force a full run. */
 const IGNORE = [
     /\.md$/i,
     /^refs\//,
     /^website\//,
     /^docs\//,
-    /^\.github\/workflows\/(deploy-docs|commitlint|release|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image)\.yml$/,
+    ...OTHER_WORKFLOW_INPUTS,
     /^\.githooks\//,
     // @gjsify/node-gi (the Node-native GObject-Introspection engine, Axis 5) is
     // NOT a gjsify workspace member — the GJS-first install/foreach tooling can't
@@ -200,6 +262,31 @@ const IGNORE = [
 ];
 /** Patterns that suggest a test-only change. */
 const TEST_PATHS = [/\.spec\.[mc]?[tj]sx?$/, /^tests\/(e2e|integration)\//];
+const SCRIPT_COUPLINGS = [
+    {
+        // `templates/*` ARE workspaces (root `package.json#workspaces` carries
+        // a `templates/*` glob), so a template change already seeds its own
+        // `@gjsify/template-<name>`. That is not the consumer that matters.
+        //
+        // The consumer is `@gjsify/create-app`, and it is unreachable twice
+        // over: it lives at `packages/infra/create-gjsify/`, so no
+        // directory-name search finds it, and it takes the templates in
+        // through `node scripts/process-template.mjs` in its `build` script
+        // (which resolves each template's `workspace:^` specifiers and copies
+        // the result into `dist-templates/`), so there is no dependency edge
+        // either. `dist-templates/` is a build-output cache candidate, so once
+        // it is stale it stays stale.
+        match: /^templates\//,
+        seeds: ['@gjsify/create-app'],
+        // …and `tests/e2e/create-app` is the ONLY thing that would notice: it
+        // scaffolds a project out of `dist-templates/` and builds it. Without
+        // this a templates-only PR got neither the regenerated templates nor
+        // the suite that exercises them. PR #853 passed only by accident of
+        // also touching root `package.json` and tripping a global trigger.
+        runE2E: true,
+        why: '@gjsify/create-app build → node scripts/process-template.mjs reads templates/',
+    },
+];
 function classifyAndExpand(workspaces, changedFiles) {
     const files = changedFiles.map((f) => f.replace(/\\/g, '/')).filter((f) => f.length > 0);
     if (files.length === 0) {
@@ -250,23 +337,64 @@ function classifyAndExpand(workspaces, changedFiles) {
     }
     // Map files → workspaces. Files outside any workspace stay in `unmatched`.
     const { matched, unmatched } = workspacesForChangedFiles(workspaces, remaining);
+    // SCRIPT_COUPLINGS: add the seeds no graph edge can reach. Applied BEFORE
+    // the `unmatched` bail-out so the table works for a coupled directory that
+    // is NOT itself a workspace — such a file would otherwise force a full run
+    // and the declared seeds would never be consulted.
+    const knownNames = new Set(workspaces.map((w) => w.name));
+    const couplingSeeds = new Set();
+    const couplingAccounted = new Set();
+    let couplingRunE2E = false;
+    for (const c of SCRIPT_COUPLINGS) {
+        const hits = remaining.filter((f) => c.match.test(f));
+        if (hits.length === 0)
+            continue;
+        for (const h of hits)
+            couplingAccounted.add(h);
+        for (const s of c.seeds) {
+            // A declared seed that is not a workspace means the table has
+            // drifted from the tree (package renamed, moved, removed). Fail
+            // towards the full run and SAY SO — the whole point of this table
+            // is that a missing rebuild here is otherwise invisible, so it must
+            // never degrade quietly back into the bug it exists to prevent.
+            if (!knownNames.has(s)) {
+                return {
+                    global: true,
+                    reason: `script-coupling seed ${s} is not a workspace (${c.match.source} → ${c.why}); ` +
+                        `SCRIPT_COUPLINGS in commands/affected.ts is stale`,
+                    workspaces: workspaces.map((w) => w.name),
+                    runE2E: true,
+                    runIntegration: true,
+                    skipAll: false,
+                };
+            }
+            couplingSeeds.add(s);
+        }
+        if (c.runE2E)
+            couplingRunE2E = true;
+    }
     // Unmatched-but-not-ignored files are suspicious enough to fall back to
     // the conservative "full run" path. Examples: a new top-level dotfile,
     // a script in `scripts/` we haven't carved out, a refs/-adjacent file.
-    if (unmatched.length > 0) {
+    // A file a coupling claimed is accounted for and does not count here.
+    const stillUnmatched = unmatched.filter((f) => !couplingAccounted.has(f));
+    if (stillUnmatched.length > 0) {
         return {
             global: true,
-            reason: `unmatched files (${unmatched.length}): ${unmatched.slice(0, 3).join(', ')}${unmatched.length > 3 ? '…' : ''}`,
+            reason: `unmatched files (${stillUnmatched.length}): ${stillUnmatched.slice(0, 3).join(', ')}${stillUnmatched.length > 3 ? '…' : ''}`,
             workspaces: workspaces.map((w) => w.name),
             runE2E: true,
             runIntegration: true,
             skipAll: false,
         };
     }
+    for (const s of couplingSeeds)
+        matched.add(s);
     // TEST_ONLY shortcut: every remaining file is a spec / e2e / integration
     // path, all under ONE workspace. Skip the closure expansion — test code
-    // has no downstream consumers.
-    const testOnly = remaining.every((f) => TEST_PATHS.some((re) => re.test(f)));
+    // has no downstream consumers. A coupling deliberately disables it: the
+    // extra seeds exist precisely because a downstream consumer DOES care.
+    const testOnly = couplingSeeds.size === 0 && remaining.every((f) => TEST_PATHS.some((re) => re.test(f)));
     if (testOnly && matched.size === 1) {
         const only = [...matched][0];
         // E2E or integration test-only changes still need their own job.
@@ -317,10 +445,13 @@ function classifyAndExpand(workspaces, changedFiles) {
             }
         }
     }
-    const runE2E = remaining.some((f) => f.startsWith('tests/e2e/'));
+    // A `tests/e2e/**` touch turns the tier on, and so does any coupling that
+    // declares e2e as its only real coverage (see SCRIPT_COUPLINGS).
+    const runE2E = remaining.some((f) => f.startsWith('tests/e2e/')) || couplingRunE2E;
     return {
         global: false,
-        reason: `closure (${closure.size} ws from ${matched.size} seed(s))`,
+        reason: `closure (${closure.size} ws from ${matched.size} seed(s))` +
+            (couplingSeeds.size > 0 ? `, ${couplingSeeds.size} via script-coupling` : ''),
         workspaces: [...closure].sort(),
         runE2E,
         runIntegration,
@@ -343,7 +474,16 @@ function runGitDiff(cwd, base, head) {
         // Surface a clear error — caller (CI) will fall back to full run
         // via `continue-on-error: true` on the classify step.
         process.stderr.write(`gjsify affected: git diff failed (${r.status}): ${r.stderr.trim()}\n`);
+        // Under GJS `process.exit()` is DEFERRED (no atexit — the call
+        // returns), so in this synchronous, value-returning helper a bare
+        // exit fell through to the `return` below and handed the caller a
+        // diff parsed from a failed git run. `return process.exit(…)` cannot
+        // help here either — it would hand the caller the pending exit
+        // promise as a `string[]`. The throw is what actually stops the
+        // caller; on Node the exit(2) halts first and the throw is dead.
+        // oxlint-disable-next-line gjsify/deferred-process-exit -- the throw below IS the halt for the GJS path; see the comment above.
         process.exit(2);
+        throw new Error(`gjsify affected: git diff failed (${r.status})`);
     }
     return r.stdout.split('\n').filter(Boolean);
 }
@@ -409,8 +549,11 @@ function assertShellSafeWorkspaceName(name) {
         `  \`include-args\` token (the value is consumed by an UNQUOTED $INCLUDE_ARGS expansion — see the\n` +
         `  contract at the top of commands/affected.ts). Rename the workspace, or teach this command a\n` +
         `  transport the consumers can unquote. Refusing to emit a filter that would silently mis-match.\n`);
+    // NOT unreachable under GJS: `process.exit()` is DEFERRED there (no atexit
+    // — the call returns), so the throw below is what actually stops an unsafe
+    // name from reaching the emit site; the exit code rides the scheduled
+    // teardown. On Node the exit(2) halts first and the throw is dead code.
+    // oxlint-disable-next-line gjsify/deferred-process-exit -- the throw below IS the halt for the GJS path; see the comment above.
     process.exit(2);
-    // Unreachable — `process.exit` terminates. Present so this function has no
-    // fall-through path that could ever return an unsafe name.
     throw new Error(`gjsify affected: unsafe workspace name ${name}`);
 }

package/lib/commands/check.js

@@ -112,7 +112,10 @@ export const checkCommand = {
                     console.log(`[check] cwd=${cwd}  → npm run check`);
                 }
                 const r = spawnSync('npm', ['run', 'check'], { cwd, stdio: 'inherit' });
-                process.exit(r.status ?? 1);
+                // `return` — a bare `process.exit()` is deferred under GJS (no
+                // atexit), so execution fell through into workspace mode and
+                // re-checked the whole monorepo after the single-package run.
+                return process.exit(r.status ?? 1);
             }
             // Fall through to workspace mode when the local package has no
             // check script (cd'd into a non-package dir under the root).
@@ -120,7 +123,9 @@ export const checkCommand = {
         // ---- Workspace mode ----
         if (!workspaceRoot) {
             console.error('gjsify check: no workspace root found from cwd. Run inside a workspace (or a package within one) with `npm run check` defined.');
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise ran discoverWorkspaces
+            // on a null root.
+            return process.exit(1);
         }
         const allWorkspaces = discoverWorkspaces(workspaceRoot);
         // Always exclude @girs/* (type-only packages, no own tsc check).
@@ -137,7 +142,7 @@ export const checkCommand = {
         });
         if (targets.length === 0) {
             console.error('gjsify check: no workspaces with a `check` script found.');
-            process.exit(1);
+            return process.exit(1);
         }
         if (args.verbose) {
             console.log(`[check] root=${workspaceRoot}  workspaces=${targets.length}  parallel=${args.parallel ? 'yes' : 'no'}`);
@@ -145,16 +150,26 @@ export const checkCommand = {
         // ---- Sequential mode ----
         if (!args.parallel) {
             let firstFail = 0;
+            let failCount = 0;
             for (const ws of targets) {
                 if (args.verbose)
                     console.log(`[check] → ${ws.name}`);
                 const code = await runCheck(ws, null);
-                if (code !== 0 && firstFail === 0)
-                    firstFail = code;
+                if (code !== 0) {
+                    failCount++;
+                    if (firstFail === 0)
+                        firstFail = code;
+                }
             }
+            // Count failures from the loop above — the previous
+            // `targets.filter(async …)` spelling RE-SPAWNED every workspace's
+            // check (fire-and-forget) just to print a count, and its async
+            // predicate is always truthy, so it counted ALL targets.
             if (firstFail !== 0)
-                console.error(`gjsify check: failures in ${targets.filter(async (ws) => (await runCheck(ws, null)) !== 0).length}+ workspaces`);
-            process.exit(firstFail);
+                console.error(`gjsify check: failures in ${failCount} workspace(s)`);
+            // `return` — a bare exit is deferred under GJS and fell through
+            // into parallel mode, re-running every check.
+            return process.exit(firstFail);
         }
         // ---- Parallel mode (default) ----
         const concurrency = args.jobs ?? Math.max(1, cpus().length);
@@ -179,7 +194,9 @@ export const checkCommand = {
             console.error(`\ngjsify check: ${failures.length} of ${targets.length} workspace(s) failed:`);
             for (const f of failures)
                 console.error(`  ✗ ${f.name} (exit ${f.code})`);
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise fell through to the
+            // success `process.exit(0)` below, clobbering the failure code.
+            return process.exit(1);
         }
         if (args.verbose)
             console.log(`\ngjsify check: ${targets.length} workspace(s) green.`);

package/lib/commands/create.js

@@ -37,7 +37,9 @@ export const createCommand = {
             if (!process.stdin.isTTY) {
                 const list = templates.map((t) => t.name).join(', ');
                 console.error(`Error: --template is required in non-interactive mode. Available templates: ${list || '(none)'}`);
-                process.exit(1);
+                // `return` — the deferred GJS exit otherwise fell through into
+                // the interactive template prompt on a non-TTY.
+                return process.exit(1);
             }
             const picked = await promptTemplate(templates);
             template = picked.name;

package/lib/commands/debug.js

@@ -122,7 +122,9 @@ export const debugCommand = {
                     : undefined);
         if (!busNameBase) {
             console.error('gjsify debug: no bus name — set package.json#gjsify.devtools.busNameBase or pass --bus-name <org.example.App>');
-            process.exit(1);
+            // `return` — a bare `process.exit()` is deferred under GJS and the
+            // handler would continue without a bus name.
+            return process.exit(1);
         }
         const globals = args.globals ?? config.globals ?? 'auto';
         const name = pkg.name ? `${pkg.name}-devtools` : 'gjsify-devtools';

package/lib/commands/flatpak/check.js

@@ -73,8 +73,7 @@ export const flatpakCheckCommand = {
         if (args.builderLint !== false) {
             if (!existsSync(manifestPath)) {
                 console.error(`[gjsify flatpak check] manifest not found: ${manifestPath}`);
-                process.exit(1);
-                return;
+                return process.exit(1);
             }
             const ok = await runLinter('flatpak-builder-lint', ['manifest', manifestPath], args.verbose ?? false);
             if (!ok)
@@ -88,7 +87,9 @@ export const flatpakCheckCommand = {
         }
         if (failures > 0) {
             console.error(`\n[gjsify flatpak check] ${failures} check(s) failed.`);
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise fell through and ALSO
+            // printed "all checks passed" after reporting failures.
+            return process.exit(1);
         }
         console.log('[gjsify flatpak check] all checks passed.');
     },

package/lib/commands/flatpak/diff.js

@@ -87,7 +87,9 @@ export const flatpakDiffCommand = {
         }
         if (!remoteTag) {
             console.warn('[gjsify flatpak diff] flathub manifest has no `tag` field on the inspected source.');
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise compared an undefined
+            // tag below and could report "in sync" on a broken manifest.
+            return process.exit(1);
         }
         if (remoteTag === localVersion) {
             console.log(`✅ in sync (${localVersion})`);

package/lib/commands/flatpak/sources.js

@@ -31,13 +31,10 @@ function parseSri(integrity) {
         return null;
     const algorithm = integrity.slice(0, dash);
     const b64 = integrity.slice(dash + 1).replace(/=+$/, '');
-    let hex;
-    try {
-        hex = Buffer.from(b64, 'base64').toString('hex');
-    }
-    catch {
-        return null;
-    }
+    // Base64 decoding is lenient on every runtime (Node skips invalid chars,
+    // @gjsify/buffer's table decode maps them to 0): malformed input yields
+    // short/garbage output — caught by the length check below — never a throw.
+    const hex = Buffer.from(b64, 'base64').toString('hex');
     if (hex.length < 4)
         return null;
     return { algorithm, hex };

package/lib/commands/foreach.js

@@ -141,7 +141,9 @@ function signalTree(child, descendants, signal) {
         child.kill(signal);
     }
     catch {
-        // already gone — fine
+        // NOT the already-dead case — `ChildProcess.kill()` swallows ESRCH
+        // itself and returns false. This guards Node's residual throw paths
+        // (EPERM surfacing via an unhandled 'error' emit, unknown signal).
     }
 }
 function killActiveChildren() {
@@ -292,7 +294,9 @@ export const foreachCommand = {
             }
             if (!cmd) {
                 console.error('gjsify foreach --exec: missing command. Pass it after `--`, e.g. `gjsify foreach --exec -- npm publish --tag latest`.');
-                process.exit(1);
+                // `return` — a bare `process.exit()` is deferred under GJS and
+                // the handler would keep running without a command.
+                return process.exit(1);
             }
         }
         assertEveryIncludeMatches(allWorkspaces, args.include);
@@ -309,7 +313,8 @@ export const foreachCommand = {
         if (!exec) {
             if (!cmd) {
                 console.error('gjsify foreach: missing <script> positional. Pass --exec to run an arbitrary command instead.');
-                process.exit(1);
+                // `return` — see the deferred-exit note on the --exec guard.
+                return process.exit(1);
             }
             const scriptName = cmd;
             selected = selected.filter((ws) => {
@@ -330,13 +335,16 @@ export const foreachCommand = {
             const m = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(args.shard);
             if (!m) {
                 console.error(`gjsify foreach: invalid --shard "${args.shard}" — expected "<index>/<total>" (1-based), e.g. 2/4.`);
-                process.exit(1);
+                // `return` — the deferred GJS exit otherwise ran the whole
+                // unsharded set.
+                return process.exit(1);
             }
             const index = Number(m[1]);
             const total = Number(m[2]);
             if (total < 1 || index < 1 || index > total) {
                 console.error(`gjsify foreach: invalid --shard "${args.shard}" — need 1 <= index <= total and total >= 1.`);
-                process.exit(1);
+                // `return` — see the deferred-exit note on the shard guard above.
+                return process.exit(1);
             }
             if (total > 1) {
                 const byName = [...selected].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
@@ -376,7 +384,8 @@ export const foreachCommand = {
             // default covers whole script chains (CI sets it once for the
             // build job) where an --exec invocation is simply not cacheable.
             console.error('gjsify foreach: --cached only applies to script mode, not --exec.');
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise ran the --exec anyway.
+            return process.exit(1);
         }
         const cache = cached && !exec
             ? new BuildCacheRunner({
@@ -409,7 +418,9 @@ export const foreachCommand = {
             // leave orphans holding the CI step's stdio open.
             killActiveChildren();
             console.error(err.message);
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise fell through to the
+            // success `process.exit(0)` below, clobbering the failure code.
+            return process.exit(1);
         }
         // ensureMainLoop() (called inside spawn) keeps GJS alive after every
         // child exits — without an explicit process.exit() the success path
@@ -472,7 +483,14 @@ function assertEveryIncludeMatches(allWorkspaces, include) {
     }
     lines.push(`  ${allWorkspaces.length} workspace(s) discovered. Refusing to run: a filter that selects nothing would`, `  otherwise exit 0 and look exactly like a successful run over the whole set.`);
     console.error(lines.join('\n'));
+    // Under GJS `process.exit()` is DEFERRED (no atexit — the call returns), so
+    // a bare exit here RETURNED to the handler, which kept going and could
+    // spawn children for the patterns that DID match before the scheduled exit
+    // fired. The throw is what actually stops the run on GJS; on Node the
+    // exit(1) halts first and the throw is dead code.
+    // oxlint-disable-next-line gjsify/deferred-process-exit -- the throw below IS the halt for the GJS path; see the comment above.
     process.exit(1);
+    throw new Error('gjsify foreach: --include matched no workspace');
 }
 /** Drop ONE matching pair of surrounding `'` or `"` — the quoting-bug probe. */
 function stripSurroundingQuotes(s) {

package/lib/commands/generate-installer.js

@@ -60,8 +60,7 @@ export const generateInstallerCommand = {
         const outputPath = resolve(process.cwd(), args.output);
         if (existsSync(outputPath) && !args.force) {
             console.error(`${args.output} already exists. Re-run with --force to overwrite.`);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         const pkgJsonPath = resolve(process.cwd(), 'package.json');
         let pkgJson = null;
@@ -76,8 +75,7 @@ export const generateInstallerCommand = {
         const target = args.target ?? pkgJson?.name;
         if (!target) {
             console.error('No target package: pass `gjsify generate-installer <pkg>` or run inside a directory with a package.json.');
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         const binName = args['bin-name'] ?? pickDefaultBinName(pkgJson, target);
         const bootstrapUrl = args['bootstrap-url'] ?? DEFAULT_BOOTSTRAP_URL;

package/lib/commands/install.js

@@ -17,7 +17,7 @@
 // `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.md), but since
+// (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.
@@ -133,22 +133,27 @@ export const installCommand = {
             if (args.packages && args.packages.length > 0) {
                 console.error('gjsify install --immutable does not accept package arguments. ' +
                     'Remove the package names or drop --immutable.');
-                process.exit(1);
+                // `return` — a bare `process.exit()` is deferred under GJS and
+                // the install would proceed past a refused flag combination.
+                return process.exit(1);
             }
             if (args.global) {
                 console.error('gjsify install --immutable is incompatible with --global.');
-                process.exit(1);
+                // `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.');
-                process.exit(1);
+                // `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.');
-                process.exit(1);
+                // `return` — see the deferred-exit note above.
+                return process.exit(1);
             }
             for (const flag of ['save-dev', 'save-peer', 'save-optional']) {
                 if (args[flag]) {
@@ -241,7 +246,10 @@ 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).`);
-                process.exit(1);
+                // `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 process.exit(1);
             }
             throw err;
         }
@@ -536,7 +544,7 @@ function syncLockfileRequested(cwd, specs) {
  *
  * 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.md.
+ * Phase D.8 follow-up tracked in status/open-todos.md.
  */
 async function workspaceInstall(cwd, args, signal) {
     // Hold the root-prefix lock for the WHOLE workspace flow: bin shims,

package/lib/commands/login.js

@@ -63,7 +63,9 @@ export const loginCommand = {
         catch (err) {
             if (err instanceof LoginError) {
                 console.error(err.message);
-                process.exit(1);
+                // `return` — the deferred GJS exit otherwise fell through into
+                // the rethrow below and reported the login error twice.
+                return process.exit(1);
             }
             throw err;
         }