@gjsify/cli 0.51.0 → 0.52.0

package/lib/utils/hang-watchdog.d.ts

@@ -0,0 +1,95 @@
+/** One line of the heartbeat file. */
+export interface Heartbeat {
+    /** Epoch ms the in-flight work is due by; `0` means the harness set no deadline. */
+    deadlineMs: number;
+    /** `<suite> › <test>`, or `<test run>` between tests. */
+    label: string;
+}
+/** Grace on top of the harness's own deadline before a late test is called a hung one. */
+export declare const DEFAULT_GRACE_MS = 30000;
+/** How often the file is read. A hang is a minutes-scale event; a second of latency is free. */
+export declare const DEFAULT_POLL_MS = 1000;
+/**
+ * Grace on top of the harness's own deadline, read from `GJSIFY_HANG_GRACE_MS`. `0` turns the
+ * watchdog off — the escape hatch for a debugger parked on a breakpoint, which looks exactly
+ * like a hang from out here.
+ *
+ * A BLANK value is the DEFAULT, not `0`. `Number('')` is `0`, so a matrix leg that sets the
+ * variable to an empty string (the shape every `${{ }}` expansion takes when its input is
+ * missing) would have switched the guard off without anyone writing a zero — a guard silently
+ * disarmed by an empty string is the failure mode this whole PR exists to stop.
+ */
+export declare function hangGraceMs(env: Record<string, string | undefined>): number;
+/**
+ * The child's environment with `GJSIFY_UNIT_HEARTBEAT` pointing at `path` — or REMOVED when
+ * there is none.
+ *
+ * Removing it is the load-bearing half. The variable is INHERITED, so a spawn that mints no
+ * file of its own (`GJSIFY_HANG_GRACE_MS=0`, or a `/tmp` that refused) used to hand the child
+ * an OUTER run's heartbeat path. The inner run then wrote its own per-test deadlines into the
+ * outer run's file, and the outer watchdog judged them against the outer child's pid: a short
+ * inner deadline kills a healthy outer child, and the inner run's closing `0\t<run finished>`
+ * disarms the outer guard outright. Measured before the fix — with the variable preset and the
+ * grace at 0, the child wrote `0\t<run finished>` into the inherited path.
+ */
+export declare function heartbeatEnv(base: Record<string, string | undefined>, path: string | undefined): Record<string, string | undefined>;
+/**
+ * Parse one heartbeat line. Returns `null` for anything that is not one — an absent file, a
+ * half-written line, a bundle that is not a test run — because every one of those means "no
+ * claim was made", and a watchdog that guesses when nobody claimed anything is a watchdog that
+ * kills healthy processes.
+ */
+export declare function parseHeartbeat(text: string | null | undefined): Heartbeat | null;
+/**
+ * The message a CI reader gets instead of 86 minutes of silence. Names the test, says why the
+ * run could not say so itself, and carries whatever the backtrace probe found — the native
+ * frame is the part that points at the actual wedge (a `gst_pad_*` call, a `pthread_cond_wait`)
+ * and is the one thing no amount of re-running recovers once the process is gone.
+ */
+export declare function formatHangReport(input: {
+    label: string;
+    overdueMs: number;
+    pid: number;
+    graceMs?: number;
+    backtrace?: string;
+}): string;
+/**
+ * Best-effort native backtrace of a wedged process, capped at `maxLines`.
+ *
+ * `eu-stack` (elfutils) needs no debuginfo to name the frames. It is NOT in the base image of
+ * every runner — `.docker/ci-fedora.Dockerfile` installs it on purpose, and macOS and Windows
+ * runners have no such tool at all, so this returning `undefined` is a normal outcome. On
+ * the measured webrtc shape it prints the answer outright — `g_main_loop_run` under
+ * `ffi_call`, i.e. a GI call that entered a loop it never left — which is what no amount of
+ * re-running recovers once the process is gone.
+ *
+ * WHATEVER it produced is kept, even on a non-zero exit: unwinding a live process is partial
+ * by nature (a thread that moves mid-walk fails the walk), and the frames it did get are
+ * exactly the ones worth having. Absent, unpermitted (`ptrace_scope`) or slow, this returns
+ * `undefined` and the report is printed without it — diagnostics must never be the reason a
+ * hang report fails to appear, and 5 s is the most this may add to a report someone is waiting
+ * for.
+ */
+export declare function captureNativeBacktrace(pid: number, maxLines?: number): string | undefined;
+export interface HangWatchdogDeps {
+    /** Read the heartbeat file; `null` when it is absent or unreadable. */
+    read: () => string | null;
+    /** Injected for the spec, which drives a fake clock rather than waiting 30 s. */
+    now?: () => number;
+    graceMs?: number;
+    /** Called once, with the in-flight breadcrumb and how far past its deadline it is. */
+    onHang: (heartbeat: Heartbeat, overdueMs: number) => void;
+}
+export interface HangWatchdog {
+    /** One poll. Exposed so the spec needs neither real timers nor real files. */
+    tick: () => void;
+    start: (pollMs?: number) => void;
+    stop: () => void;
+}
+/**
+ * Poll the heartbeat and fire `onHang` at most once.
+ *
+ * Latched deliberately: the child is still wedged on the next tick, and a second report would
+ * bury the first under repeats of itself.
+ */
+export declare function createHangWatchdog(deps: HangWatchdogDeps): HangWatchdog;

package/lib/utils/hang-watchdog.js

@@ -0,0 +1,194 @@
+// The parent half of `@gjsify/unit`'s hang breadcrumb: a deadline enforced from OUTSIDE the
+// process that missed it.
+//
+// A GJS test bundle that blocks its own main loop — a spin, a nested `GLib.MainLoop.run()`, a
+// blocking GI call into GStreamer — cannot fail itself. `@gjsify/unit`'s per-test, per-suite
+// and per-run timeouts are all `setTimeout` races, and both halves of a race need the loop, so
+// the run simply goes quiet and keeps the job's stdio open until CI's own cap kills it: run
+// 34945600666 burned 90 minutes that way and arrived as an unexplained red on an unrelated PR.
+// The full measurement is in `packages/gjs/unit/src/heartbeat.ts`.
+//
+// So the child writes `<deadline-epoch-ms>\t<label>` before each test, and this polls that
+// file. Past the deadline plus a grace margin this names the test, grabs a native backtrace
+// while the wedge is still standing, and kills the child.
+//
+// The grace is a POLICY, not an inference from the harness, and the difference is measured. A
+// body that blocks the loop past its own timeout and then RETURNS passes today: `withTimeout`
+// arms its timer before calling `fn()`, but the expired timer is cleared in `finally` before
+// the loop ever turns again, so the already-resolved body wins the race. A 12 s synchronous
+// body under a 5 s timeout exits 0 on `main`; with a 3 s grace this guard kills it. The grace
+// is therefore "how long a body may legitimately block the loop beyond its own budget" — at
+// the 30 s default, 7x the 5 s test timeout — which is why the report names
+// `GJSIFY_HANG_GRACE_MS`: a false positive has to be fixable by whoever hits it.
+//
+// Inert by construction: a bundle that is not an `@gjsify/unit` run writes no heartbeat, so
+// `parseHeartbeat` returns `null` forever and a GUI launched through `gjsify run` is never
+// touched. That is why this needs no flag to be safe.
+import { spawnSync } from 'node:child_process';
+/** Grace on top of the harness's own deadline before a late test is called a hung one. */
+export const DEFAULT_GRACE_MS = 30_000;
+/** How often the file is read. A hang is a minutes-scale event; a second of latency is free. */
+export const DEFAULT_POLL_MS = 1_000;
+/**
+ * Grace on top of the harness's own deadline, read from `GJSIFY_HANG_GRACE_MS`. `0` turns the
+ * watchdog off — the escape hatch for a debugger parked on a breakpoint, which looks exactly
+ * like a hang from out here.
+ *
+ * A BLANK value is the DEFAULT, not `0`. `Number('')` is `0`, so a matrix leg that sets the
+ * variable to an empty string (the shape every `${{ }}` expansion takes when its input is
+ * missing) would have switched the guard off without anyone writing a zero — a guard silently
+ * disarmed by an empty string is the failure mode this whole PR exists to stop.
+ */
+export function hangGraceMs(env) {
+    const raw = env.GJSIFY_HANG_GRACE_MS;
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_GRACE_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : DEFAULT_GRACE_MS;
+}
+/**
+ * The child's environment with `GJSIFY_UNIT_HEARTBEAT` pointing at `path` — or REMOVED when
+ * there is none.
+ *
+ * Removing it is the load-bearing half. The variable is INHERITED, so a spawn that mints no
+ * file of its own (`GJSIFY_HANG_GRACE_MS=0`, or a `/tmp` that refused) used to hand the child
+ * an OUTER run's heartbeat path. The inner run then wrote its own per-test deadlines into the
+ * outer run's file, and the outer watchdog judged them against the outer child's pid: a short
+ * inner deadline kills a healthy outer child, and the inner run's closing `0\t<run finished>`
+ * disarms the outer guard outright. Measured before the fix — with the variable preset and the
+ * grace at 0, the child wrote `0\t<run finished>` into the inherited path.
+ */
+export function heartbeatEnv(base, path) {
+    const env = { ...base };
+    if (path)
+        env.GJSIFY_UNIT_HEARTBEAT = path;
+    else
+        delete env.GJSIFY_UNIT_HEARTBEAT;
+    return env;
+}
+/**
+ * Parse one heartbeat line. Returns `null` for anything that is not one — an absent file, a
+ * half-written line, a bundle that is not a test run — because every one of those means "no
+ * claim was made", and a watchdog that guesses when nobody claimed anything is a watchdog that
+ * kills healthy processes.
+ */
+export function parseHeartbeat(text) {
+    if (!text)
+        return null;
+    const line = text.split('\n', 1)[0] ?? '';
+    const tab = line.indexOf('\t');
+    if (tab < 0)
+        return null;
+    const deadlineMs = Number(line.slice(0, tab));
+    if (!Number.isFinite(deadlineMs) || deadlineMs < 0)
+        return null;
+    const label = line.slice(tab + 1).trim();
+    if (label.length === 0)
+        return null;
+    return { deadlineMs, label };
+}
+/**
+ * The message a CI reader gets instead of 86 minutes of silence. Names the test, says why the
+ * run could not say so itself, and carries whatever the backtrace probe found — the native
+ * frame is the part that points at the actual wedge (a `gst_pad_*` call, a `pthread_cond_wait`)
+ * and is the one thing no amount of re-running recovers once the process is gone.
+ */
+export function formatHangReport(input) {
+    const lines = [
+        `⏱ hang: "${input.label}" is ${Math.round(input.overdueMs / 1000)}s past its own deadline`,
+        `  gjs pid ${input.pid} stopped turning its main loop, so @gjsify/unit's timeout cannot fire`,
+        `  (see packages/gjs/unit/src/heartbeat.ts). Killing it rather than holding the job open.`,
+    ];
+    if (input.backtrace) {
+        lines.push('  native backtrace at the moment of the hang:');
+        for (const l of input.backtrace.split('\n'))
+            lines.push(`    ${l}`);
+    }
+    else {
+        // Said out loud. Silence here reads as "the guard had nothing to add", when what it
+        // means is that the one artefact a dead process cannot be asked for again was missed.
+        lines.push('  no native backtrace: eu-stack (elfutils) absent, refused the attach, or found nothing');
+    }
+    if (input.graceMs !== undefined) {
+        // The knob travels WITH the accusation: whoever reads this is the one person who can
+        // tell a wedge from a body that legitimately blocks the loop this long.
+        lines.push(`  a test that legitimately blocks the loop this long: raise GJSIFY_HANG_GRACE_MS`);
+        lines.push(`  (now ${input.graceMs} ms, 0 disables this guard).`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Best-effort native backtrace of a wedged process, capped at `maxLines`.
+ *
+ * `eu-stack` (elfutils) needs no debuginfo to name the frames. It is NOT in the base image of
+ * every runner — `.docker/ci-fedora.Dockerfile` installs it on purpose, and macOS and Windows
+ * runners have no such tool at all, so this returning `undefined` is a normal outcome. On
+ * the measured webrtc shape it prints the answer outright — `g_main_loop_run` under
+ * `ffi_call`, i.e. a GI call that entered a loop it never left — which is what no amount of
+ * re-running recovers once the process is gone.
+ *
+ * WHATEVER it produced is kept, even on a non-zero exit: unwinding a live process is partial
+ * by nature (a thread that moves mid-walk fails the walk), and the frames it did get are
+ * exactly the ones worth having. Absent, unpermitted (`ptrace_scope`) or slow, this returns
+ * `undefined` and the report is printed without it — diagnostics must never be the reason a
+ * hang report fails to appear, and 5 s is the most this may add to a report someone is waiting
+ * for.
+ */
+export function captureNativeBacktrace(pid, maxLines = 40) {
+    try {
+        const r = spawnSync('eu-stack', ['-p', String(pid)], {
+            encoding: 'utf8',
+            timeout: 5_000,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        const out = typeof r.stdout === 'string' ? r.stdout.trim() : '';
+        if (out.length === 0)
+            return undefined;
+        return out.split('\n').slice(0, maxLines).join('\n');
+    }
+    catch (_e) {
+        /* no eu-stack, or no permission to attach — the report stands without it */
+        return undefined;
+    }
+}
+/**
+ * Poll the heartbeat and fire `onHang` at most once.
+ *
+ * Latched deliberately: the child is still wedged on the next tick, and a second report would
+ * bury the first under repeats of itself.
+ */
+export function createHangWatchdog(deps) {
+    const now = deps.now ?? Date.now;
+    const graceMs = deps.graceMs ?? DEFAULT_GRACE_MS;
+    let timer;
+    let fired = false;
+    const tick = () => {
+        if (fired)
+            return;
+        const hb = parseHeartbeat(deps.read());
+        // `deadlineMs === 0` is the harness saying "no deadline here" (`{ timeout: 0 }`, or
+        // the window after the run finished). Enforcing one it declined to set is exactly the
+        // false positive that would make this guard get turned off.
+        if (!hb || hb.deadlineMs <= 0)
+            return;
+        const overdueMs = now() - (hb.deadlineMs + graceMs);
+        if (overdueMs < 0)
+            return;
+        fired = true;
+        stop();
+        deps.onHang(hb, now() - hb.deadlineMs);
+    };
+    const stop = () => {
+        if (timer !== undefined)
+            clearInterval(timer);
+        timer = undefined;
+    };
+    return {
+        tick,
+        start: (pollMs = DEFAULT_POLL_MS) => {
+            if (timer === undefined)
+                timer = setInterval(tick, pollMs);
+        },
+        stop,
+    };
+}

package/lib/utils/install-backend-native.d.ts

@@ -88,6 +88,20 @@ export interface NativeInstallOptions extends InstallOptions {
      * required, the pre-platform-filter behaviour.
      */
     optionalSpecs?: Set<string>;
+    /**
+     * Names provided by a `gjsify link` development override (`utils/dev-link.ts`):
+     * `node_modules/<name>` is a symlink into a local checkout, so the registry copy
+     * must not be fetched over it — `assertNodeModulesDest` refuses that extract and
+     * aborts the whole install, correctly, since it would delete the checkout.
+     *
+     * DELIBERATELY NOT `workspaceNames`, the set it is otherwise shaped like. That
+     * one also reaches `resolveDeps` and removes the subtree from the RESOLVE — and
+     * the resolve is what writes `gjsify-lock.json`. A link is a local development
+     * decision that must leave the consumer's committed lockfile byte-identical, so
+     * these names are dropped only from what gets DOWNLOADED, after the lockfile has
+     * been written from the full resolved tree.
+     */
+    linkedNames?: Set<string>;
 }
 export declare function installPackagesNative(opts: NativeInstallOptions): Promise<InstalledTopLevel[]>;
 /**

package/lib/utils/install-backend-native.js

@@ -60,6 +60,9 @@ import { getCachedPackument, putCachedPackument } from './install-packument-cach
 import { assertNativeBackendNodeVersion } from './node-version.js';
 import { buildCmdShim, buildLauncherShims, buildNativeEnvPreamble, buildShLauncher, isGjsBundlePath, parseShebang, pickBinMap, } from './bin-shim.js';
 import { detectNativePackages } from './detect-native-packages.js';
+import { findExtraneous, formatExtraneousError } from './install-extraneous.js';
+import { devLinkPath, devLinkRoot } from './dev-link.js';
+import { scanPrefix } from './prune-prefix.js';
 import { badPlatformError, checkPlatform, declaresPlatform, describePlatformTarget, readPlatformForce, resolveHostPlatform, } from './platform-check.js';
 // 16-wide download pool, matched to the shared Soup.Session's lifted
 // `max-conns-per-host` (@gjsify/fetch `getSharedSession`) — without that lift
@@ -157,6 +160,14 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
         }
         log('install: --immutable, using lockfile (%d package(s))', Object.keys(existingLock.packages).length);
         nodes = lockfileToNodes(existingLock);
+        // ...and the tree must hold NOTHING ELSE. The installer only adds, so without
+        // this an undescribed package survives the install and exits 0 — the CI cache
+        // poisoning of gjsify#1683 (install-extraneous.ts carries the incident).
+        // Before the download so a wrong tree costs seconds, not the extract phase,
+        // and with the FULL lockfile set: the workspace filter below removes nodes
+        // that ARE described, and judging against the smaller set would call them
+        // strangers.
+        assertNoExtraneous(opts.prefix, nodes);
     }
     else if (!opts.refreshLockfile &&
         existingLock &&
@@ -209,6 +220,16 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
         writeLockfile(lockfilePath, opts.specs, nodes);
         log('install: wrote %s (%d entries)', LOCKFILE_NAME, nodes.length);
     }
+    // TWO NAMES FROM HERE ON, and the split is the fix for a measured defect.
+    // `nodes` stays the FULL resolved tree — what the lockfile describes and what
+    // `topLevelResolutions` answers from. `fetchable` is the subset that still has
+    // to come off the network. A package can be present without being fetched, and
+    // collapsing the two made the installer forget it existed: with a `gjsify link`
+    // active, `gjsify install is-odd` read the FILTERED array, found no `is-odd`
+    // resolution, and wrote `"is-odd": "latest"` into package.json and
+    // `is-odd@latest` into the lockfile's `requested` — over the `^3.0.1` the
+    // control run without the link produced. Never re-merge these two names.
+    let fetchable = nodes;
     // A package named after one of the monorepo's own workspaces is provided by a
     // workspace symlink (wired by `workspaceInstall`), NOT by a registry tarball —
     // even when the lockfile or a transitive edge pins a same-named published
@@ -217,26 +238,55 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     // `--immutable` robust against a committed lockfile that still carries such
     // entries, since that path never runs `resolveDeps`.
     if (opts.workspaceNames && opts.workspaceNames.size > 0) {
-        const before = nodes.length;
-        nodes = nodes.filter((n) => !opts.workspaceNames.has(n.name));
-        const dropped = before - nodes.length;
+        const before = fetchable.length;
+        fetchable = fetchable.filter((n) => !opts.workspaceNames.has(n.name));
+        const dropped = before - fetchable.length;
         if (dropped > 0) {
             log('install: %d workspace-provided package(s) symlinked, not fetched', dropped);
         }
     }
+    // Same exclusion, different reason and a different position in the pipeline: a
+    // `gjsify link` override provides these from a local checkout. It runs AFTER the
+    // lockfile write above on purpose — the consumer's committed lockfile must stay
+    // byte-identical whether or not a link is active (utils/dev-link.ts).
+    if (opts.linkedNames && opts.linkedNames.size > 0) {
+        const before = fetchable.length;
+        fetchable = fetchable.filter((n) => !opts.linkedNames.has(n.name));
+        const dropped = before - fetchable.length;
+        if (dropped > 0) {
+            log('install: %d dev-linked package(s) provided by a local checkout, not fetched', dropped);
+        }
+    }
     // os/cpu/libc: throws for an incompatible REQUIRED dep, marks incompatible
     // OPTIONAL ones inert. Runs on BOTH paths (fresh resolve and lockfile) —
     // that is what makes one committed lockfile install a per-host subset.
-    const installable = applyPlatformFilter(nodes, target, force, log);
+    const installable = applyPlatformFilter(fetchable, target, force, log);
     log('install: downloading %d tarball(s)', installable.length);
     await downloadAndExtractAll(installable, opts.prefix, npmrc, log, opts.signal, progress);
     await linkBins(installable, opts.prefix, log);
     warnMissingNativeBuilds(installable, opts.prefix, log);
     log('install: done');
     // Top-level requested packages only, so callers can write the resolved version
-    // back into package.json (`npm install --save`).
+    // back into package.json (`npm install --save`). From `nodes`, NEVER from
+    // `fetchable`: "what is installed at node_modules/<name>" is not "what was
+    // downloaded", and a provided package is installed.
     return topLevelResolutions(opts.specs, nodes);
 }
+/**
+ * `--immutable` only: refuse a `node_modules` holding packages the lockfile does not
+ * describe, naming every one of them.
+ *
+ * Deliberately NOT a prune — the reasoning, and the incident it comes from, are the
+ * header note of `install-extraneous.ts`. Scoped to the frozen path: a plain install
+ * resolves a NEW tree and may legitimately leave an older placement behind for its
+ * own prune pass to judge, so this rule would be wrong there.
+ */
+function assertNoExtraneous(prefix, nodes) {
+    const extraneous = findExtraneous({ prefix, installed: scanPrefix(prefix), expected: nodes });
+    if (extraneous.length === 0)
+        return;
+    throw new Error(formatExtraneousError(extraneous, prefix));
+}
 function errMsg(err) {
     if (err instanceof Error)
         return err.message;
@@ -1378,7 +1428,7 @@ async function extractOne(node, prefix, npmrc, log, signal) {
     // fail if a workspace package leaked into the fetch/extract queue (the root cause
     // fixed in `workspaceInstall`), and refusing here means a resolver regression can
     // never again `rmSync` a working-tree source dir.
-    assertNodeModulesDest(dest, node);
+    assertNodeModulesDest(dest, node, prefix);
     // Idempotent fast-path — skip the cache read + rm + re-extract for a node already
     // extracted at the resolved version. The npm/yarn/pnpm default (only added/changed
     // nodes are written) and the dominant cost on a warm re-install.
@@ -1387,14 +1437,15 @@ async function extractOne(node, prefix, npmrc, log, signal) {
         log('up-to-date: %s@%s (already extracted at %s)', node.name, node.version, node.installPath);
         return true;
     }
-    // Content-addressable cache before the network: tarballs are immutable per SRI
-    // integrity, so a hash hit is byte-identical to what the registry would return and
-    // needs no verifying re-download.
-    let bytes = getCachedTarball(node.integrity);
+    // Content-addressable cache before the network. Both readers RE-HASH the bytes
+    // against the integrity that named them, so a hit is byte-identical to what the
+    // registry would return because it was checked, not because the path says so —
+    // the store is a restorable CI artifact now, not just a local directory.
+    let bytes = await getCachedTarball(node.integrity);
     if (bytes) {
         log('cache-hit: %s@%s ← %s', node.name, node.version, node.integrity);
     }
-    else if ((bytes = getForeignCachedTarball(node.integrity))) {
+    else if ((bytes = await getForeignCachedTarball(node.integrity))) {
         // Second chance: npm's cacache content store, same SRI key — anyone who has run
         // `npm install` already has the tarball on disk. Written through to OUR store so
         // the next `gjsify install` hits first-class even if npm prunes its cache.
@@ -1514,7 +1565,7 @@ function abortError(signal) {
  *      a workspace source tree, where `rmSync(dest, { recursive: true })` deletes the
  *      link's target contents.
  */
-function assertNodeModulesDest(dest, node) {
+function assertNodeModulesDest(dest, node, prefix) {
     const segments = dest.split(path.sep);
     if (!segments.includes('node_modules')) {
         throw new Error(`gjsify install: refusing to extract ${node.name}@${node.version} into ${dest} — ` +
@@ -1533,9 +1584,36 @@ function assertNodeModulesDest(dest, node) {
     if (!realSegments.includes('node_modules')) {
         throw new Error(`gjsify install: refusing to extract ${node.name}@${node.version} — ${dest} resolves to ${real}, ` +
             `which is outside any node_modules/ directory (likely a symlink to a workspace source tree). ` +
-            `Extracting here would delete working-tree source files.`);
+            `Extracting here would delete working-tree source files.${devLinkRemedy(prefix, dest)}`);
     }
 }
+/**
+ * The extra sentence for the ONE cause this refusal has that a developer can undo
+ * with a command: a `gjsify link` development link.
+ *
+ * Measured: relinking with a narrower `--packages` left `node_modules/is-number`
+ * pointing into the checkout while the new override no longer named it, and every
+ * later `gjsify install` died on the refusal above — which spoke only of "a
+ * workspace source tree" and named no command at all. `gjsify unlink` did not
+ * rescue it either (it removed the override first, destroying the escape route),
+ * so the only way out was a hand-written `rm`. Both halves are fixed at the
+ * source; this message is what tells someone already wedged by an older CLI.
+ *
+ * The override file may be GONE by the time this fires, so its absence is not
+ * evidence: the remedy is named whenever a `node_modules` entry points outside,
+ * and it names the file only when it is actually there.
+ */
+function devLinkRemedy(prefix, dest) {
+    // Same walk the guard and the installer do, so the path this message tells
+    // someone to run `gjsify unlink` in is the one that holds the override.
+    const root = devLinkRoot(prefix);
+    const override = devLinkPath(root);
+    const active = fs.existsSync(override);
+    return (`\n  If a \`gjsify link\` development link put it there${active ? ` — ${override} is present` : ''}: ` +
+        `run \`gjsify unlink\` in ${root} to remove the links and restore the registry copies, ` +
+        `or \`gjsify link <checkout> --packages …\` to re-select. ` +
+        `If no override is left, delete ${dest} by hand and re-run.`);
+}
 function depth(installPath) {
     // `node_modules/foo` = 1, `node_modules/foo/node_modules/bar` = 2, …
     return installPath.split('/node_modules/').length;

package/lib/utils/install-extraneous.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The half of `--immutable` that was missing: every locked package is present AND
+ * NOTHING ELSE IS.
+ *
+ * The installer only ever ADDED. Handed a `node_modules` carrying a package the
+ * lockfile never mentions, `--immutable` extracted whatever was missing, left the
+ * stranger in place and exited 0 — a green install over a tree its own lockfile does
+ * not describe.
+ *
+ * THE INCIDENT (gjsify#1683, 2026-09-15). CI caches `node_modules` keyed on
+ * `hashFiles('gjsify-lock.json')` with a prefix fallback `restore-keys:
+ * node-modules-v1-`. An earlier run of a `@girs` bump genuinely nested
+ * `node_modules/@girs/gtk-4.0/node_modules/@girs/graphene-1.0` and saved that tree.
+ * The fix push changed the lockfile → new key → miss → the FALLBACK restored the
+ * nested tree. `--immutable` added what was missing, pruned nothing, and `tsc` then
+ * saw one type under two identities: TS2883. Worse, the still-nested tree was saved
+ * under the NEW key, so no plain re-run could go green — the failure reproduced
+ * itself until the caches were deleted by hand. Nothing about the PR's code was
+ * wrong, and any lockfile-changing PR could poison itself the same way.
+ *
+ * WHY NAMING, NOT DELETING. The peers split: `npm ci` removes `node_modules` first,
+ * yarn's `--immutable` fails on a mismatch. This follows yarn, for three reasons.
+ * The flag's own name promises not to mutate, and this repo already refuses
+ * automatic deletion under it ({@link automaticPruneRefusal} returns `'--immutable'`).
+ * A verifier that deletes can delete the wrong thing — a `link`ed dep, a package
+ * some other tool put there — while a verifier that reports cannot. And the failure
+ * mode is asymmetric: a wrong deletion loses work, a wrong refusal costs one red run
+ * carrying the exact paths and the fix.
+ *
+ * That choice has a price, paid in `.github/actions/gjsify-setup/action.yml`: with
+ * this check fatal, a restored FOREIGN tree stops being silent corruption and
+ * becomes a hard failure on every lockfile-changing PR. So the `restore-keys`
+ * fallback is gone — see the comment there. The two decisions are one decision.
+ */
+import type { InstalledPackage } from './prune-prefix.js';
+/** A package directory on disk that the lockfile does not describe. */
+export interface ExtraneousPackage {
+    /**
+     * Path relative to the install prefix, always `/`-separated — the exact shape of
+     * a `gjsify-lock.json` `packages` key, so "not in the lockfile" is checkable by
+     * grepping the reported string against the file.
+     */
+    installPath: string;
+    /** From the on-disk manifest; the directory path when it was unreadable. */
+    name: string;
+    version: string;
+}
+/**
+ * Package directories under `prefix` that no entry of `expected` accounts for.
+ *
+ * Pure: it takes the scan rows ({@link scanPrefix}) and the resolved set rather than
+ * reading either, so every branch — nested placements, symlinks, subtree collapsing —
+ * is decidable without a filesystem.
+ *
+ * Three things are deliberately NOT extraneous:
+ *   - a SYMLINK, which is a workspace source tree linked in by `workspaceInstall`
+ *     and by construction absent from the lockfile (`scanPrefix` does not descend
+ *     into one either, so the user's own sources are never walked);
+ *   - a dot-entry like `.bin` or `.cache`, already dropped by the scan;
+ *   - a package the lockfile describes but the PLATFORM filter skipped on this host.
+ *     It is described, so it is not a stranger; removing the foreign-platform residue
+ *     is `prune-prefix.ts`'s separate job under a separate rule.
+ *
+ * Descendants of an extraneous directory are collapsed away: reporting the parent
+ * says everything, and the nested `@girs` tree of the incident would otherwise list
+ * its whole subtree.
+ */
+export declare function findExtraneous(opts: {
+    prefix: string;
+    installed: readonly InstalledPackage[];
+    expected: readonly {
+        installPath: string;
+    }[];
+}): ExtraneousPackage[];
+/** How many paths the message names before it starts counting. */
+export declare const EXTRANEOUS_REPORT_LIMIT = 20;
+/**
+ * The refusal, built to be actionable from the CI log alone: what is wrong, which
+ * paths, and the one thing that fixes it. Truncated past
+ * {@link EXTRANEOUS_REPORT_LIMIT} so a wholly foreign tree does not bury the advice
+ * under a thousand lines.
+ *
+ * It says DELETE, and says so as the only remedy, because that is what was measured:
+ * a plain `gjsify install` — and an explicit `--prune` — leave both a top-level and a
+ * nested stranger exactly where they were. The installer only adds, and `prune-prefix`
+ * judges one thing, npm's `os`/`cpu`/`libc`, so a package that is merely UNDESCRIBED
+ * matches no rule either owns. Sending a developer to `gjsify install` instead would
+ * hand them a command that changes nothing and a refusal that repeats verbatim.
+ */
+export declare function formatExtraneousError(entries: readonly ExtraneousPackage[], prefix: string): string;