@gjsify/cli 0.51.1 → 0.53.0

package/lib/utils/gjsify-shim.d.ts

@@ -8,6 +8,16 @@
  * undoing the repair one level down.
  */
 export declare function usingSelfShim(): boolean;
+/**
+ * `PATH` as the user's shell sees it: `process.env.PATH` without the self-shim dir.
+ *
+ * The shim is this PROCESS TREE's `gjsify`, never the one the user's next command
+ * runs. `self-update` asked `resolveBinOnPath` who wins PATH and got its own shim
+ * back, the temp copy of the version it had just replaced, so a successful update
+ * inside a workspace reported "`gjsify` on PATH resolves to /tmp/gjsify-shim-…
+ * (v0.51.1)" and exited 1.
+ */
+export declare function pathWithoutSelfShim(pathValue?: string, shimDir?: string | undefined, sep?: string): string;
 /**
  * Does this invocation need its own `gjsify` on PATH, rather than the workspace's
  * npm bin?
@@ -31,6 +41,43 @@ export declare function needsSelfShim(opts: {
  * reuse it instead of creating their own.
  */
 export declare function ensureGjsifyShimOnPath(): void;
+/**
+ * The tree whose `node_modules` holds the running CLI and its prebuilds: the
+ * install prefix above the first `node_modules` segment, or the workspace root
+ * for an in-repo CLI (`packages/infra/cli/dist/cli.gjs.mjs`).
+ */
+export declare function selfShimScanRoot(selfEntry: string): string;
+/**
+ * The env preamble for a shim re-invoking `selfEntry` — {@link buildNativeEnvPreamble}
+ * with the inputs `gjsify install -g` gives it: the prefix to glob at launch, and
+ * the prebuild dirs the walk finds above it (a hoisted ancestor's `node_modules`).
+ */
+export declare function selfShimPreamble(selfEntry: string): string;
+/**
+ * The POSIX `sh` body of the self-shim: re-invoke `target` under `interpreter`.
+ *
+ * On darwin it RE-EXPORTS the running CLI's `DYLD_*` values first. SIP strips every
+ * `DYLD_*` variable when a protected binary is exec'd, and `/bin/sh` — this shim —
+ * is one, so the child `gjs` otherwise starts without the loader path the install
+ * launcher gave the parent (see `buildNativeEnvPreamble`). `GI_TYPELIB_PATH` is not a
+ * `DYLD_*` name and survives, so the child finds a prebuild's typelib and then fails
+ * the bare-leaf `dlopen` it names: `gjsify workspace <pkg> build` died with
+ * `Failed to load shared library 'libgjsifyterminal.dylib'` while the same script run
+ * through the tree's own launcher worked.
+ *
+ * Baking the values is not the snapshot `buildNativeEnvPreamble` warns about: this
+ * shim lives in a temp dir for ONE process tree and carries exactly the environment
+ * that tree's root was started with.
+ */
+export declare function buildSelfShimScript(opts: {
+    interpreter: string;
+    interpreterArgs: readonly string[];
+    target: string;
+    platform?: string;
+    env?: Record<string, string | undefined>;
+}): string;
+/** `export` lines restoring each set `DYLD_*` variable on darwin; `''` elsewhere. */
+export declare function dyldCarryPreamble(platform: string, env: Record<string, string | undefined>): string;
 /**
  * Directory carrying a `node` that runs the file through
  * `gjsify run --node-script`, or null when this host needs none.

package/lib/utils/gjsify-shim.js

@@ -41,10 +41,11 @@
 // nested builds off the GJS bundle.
 import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, delimiter, relative, isAbsolute } from 'node:path';
+import { join, delimiter, relative, isAbsolute, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
-import { buildLauncherShims } from './bin-shim.js';
+import { buildLauncherShims, buildNativeEnvPreamble, buildShLauncher, shQuoteArg } from './bin-shim.js';
+import { detectNativePackages } from './detect-native-packages.js';
 import { resolveBinOnPath } from './install-global.js';
 import { findWorkspaceRoot } from './workspace-root.js';
 let _ensured = false;
@@ -61,6 +62,23 @@ let _selfShimActive = false;
 export function usingSelfShim() {
     return _selfShimActive;
 }
+/**
+ * `PATH` as the user's shell sees it: `process.env.PATH` without the self-shim dir.
+ *
+ * The shim is this PROCESS TREE's `gjsify`, never the one the user's next command
+ * runs. `self-update` asked `resolveBinOnPath` who wins PATH and got its own shim
+ * back, the temp copy of the version it had just replaced, so a successful update
+ * inside a workspace reported "`gjsify` on PATH resolves to /tmp/gjsify-shim-…
+ * (v0.51.1)" and exited 1.
+ */
+export function pathWithoutSelfShim(pathValue = process.env.PATH ?? '', shimDir = process.env.GJSIFY_SHIM_DIR, sep = delimiter) {
+    if (!shimDir)
+        return pathValue;
+    return pathValue
+        .split(sep)
+        .filter((entry) => entry !== shimDir)
+        .join(sep);
+}
 /**
  * Does this invocation need its own `gjsify` on PATH, rather than the workspace's
  * npm bin?
@@ -117,23 +135,90 @@ export function ensureGjsifyShimOnPath() {
     // `process.execPath`: the batch member cannot quote an interpreter argument
     // (`<interpreter> "<target>" %*`), so `C:\Program Files\nodejs\node.exe` splits.
     const interpreter = gjs ? process.env.GJS_CONSOLE || 'gjs' : 'node';
-    const interpreterArgs = gjs ? ['-m'] : [];
-    const argv = interpreterArgs.length > 0 ? `${interpreterArgs.join(' ')} ` : '';
-    writeFileSync(shim, `#!/bin/sh\nexec "${interpreter}" ${argv}"${selfEntry}" "$@"\n`, { mode: 0o755 });
+    // Under GJS the shim is the SAME launcher `gjsify install` writes, preamble
+    // included (`selfShimPreamble`). A bare `exec gjs -m` is not enough on a Mac:
+    // it runs behind `/bin/sh`, and SIP strips every `DYLD_*` from a protected
+    // binary's environment, so a nested `gjsify` found its typelibs through the
+    // surviving GI_TYPELIB_PATH and none of their libraries. Reported by the
+    // beifahrer consumer on macOS: `gjsify workspace <pkg> build` died in
+    // `get columns` with "Unsupported type void".
+    const envPreamble = gjs ? selfShimPreamble(selfEntry) : '';
+    writeFileSync(shim, gjs
+        ? buildShLauncher(selfEntry, { isGjsBundle: true, envPreamble, gjs: interpreter })
+        : `#!/bin/sh\nexec "${interpreter}" "${selfEntry}" "$@"\n`, { mode: 0o755 });
     chmodSync(shim, 0o755);
     // cmd.exe and pwsh cannot run the extension-less member: not on PATHEXT, and
     // Windows has no shebang handling. `buildLauncherShims` ports npm's
     // three-sibling answer, including the IF/ELSE ERRORLEVEL handling that
     // `&&`/`||` chaining gets wrong.
     if (!gjs && process.platform === 'win32') {
-        const { cmd, ps1 } = buildLauncherShims({ interpreter, interpreterArgs, target: selfEntry });
+        const { cmd, ps1 } = buildLauncherShims({ interpreter, interpreterArgs: [], target: selfEntry });
         writeFileSync(`${shim}.cmd`, cmd);
         writeFileSync(`${shim}.ps1`, ps1);
     }
     _selfShimActive = true;
     process.env.GJSIFY_SHIM_DIR = dir;
     process.env.PATH = dir + delimiter + (process.env.PATH ?? '');
-    writeNodeShim(dir, gjs, selfEntry);
+    writeNodeShim(dir, gjs, selfEntry, envPreamble);
+}
+/**
+ * The tree whose `node_modules` holds the running CLI and its prebuilds: the
+ * install prefix above the first `node_modules` segment, or the workspace root
+ * for an in-repo CLI (`packages/infra/cli/dist/cli.gjs.mjs`).
+ */
+export function selfShimScanRoot(selfEntry) {
+    // Both separators: the entry is a HOST path, and win32 spells it with a backslash.
+    const at = selfEntry.search(/[\\/]node_modules[\\/]/);
+    if (at > 0)
+        return selfEntry.slice(0, at);
+    return findWorkspaceRoot(dirname(selfEntry)) ?? dirname(selfEntry);
+}
+/**
+ * The env preamble for a shim re-invoking `selfEntry` — {@link buildNativeEnvPreamble}
+ * with the inputs `gjsify install -g` gives it: the prefix to glob at launch, and
+ * the prebuild dirs the walk finds above it (a hoisted ancestor's `node_modules`).
+ */
+export function selfShimPreamble(selfEntry) {
+    let baked = [];
+    try {
+        baked = detectNativePackages(dirname(selfEntry)).map((p) => p.prebuildsDir);
+    }
+    catch {
+        // The walk is filesystem I/O (EACCES on an unreadable node_modules). The
+        // launch-time glob of the scan root still runs; only ancestors go unseen.
+    }
+    return buildNativeEnvPreamble(selfShimScanRoot(selfEntry), baked);
+}
+/**
+ * The POSIX `sh` body of the self-shim: re-invoke `target` under `interpreter`.
+ *
+ * On darwin it RE-EXPORTS the running CLI's `DYLD_*` values first. SIP strips every
+ * `DYLD_*` variable when a protected binary is exec'd, and `/bin/sh` — this shim —
+ * is one, so the child `gjs` otherwise starts without the loader path the install
+ * launcher gave the parent (see `buildNativeEnvPreamble`). `GI_TYPELIB_PATH` is not a
+ * `DYLD_*` name and survives, so the child finds a prebuild's typelib and then fails
+ * the bare-leaf `dlopen` it names: `gjsify workspace <pkg> build` died with
+ * `Failed to load shared library 'libgjsifyterminal.dylib'` while the same script run
+ * through the tree's own launcher worked.
+ *
+ * Baking the values is not the snapshot `buildNativeEnvPreamble` warns about: this
+ * shim lives in a temp dir for ONE process tree and carries exactly the environment
+ * that tree's root was started with.
+ */
+export function buildSelfShimScript(opts) {
+    const argv = opts.interpreterArgs.length > 0 ? `${opts.interpreterArgs.join(' ')} ` : '';
+    const preamble = dyldCarryPreamble(opts.platform ?? process.platform, opts.env ?? process.env);
+    return `#!/bin/sh\n${preamble}exec "${opts.interpreter}" ${argv}"${opts.target}" "$@"\n`;
+}
+/** `export` lines restoring each set `DYLD_*` variable on darwin; `''` elsewhere. */
+export function dyldCarryPreamble(platform, env) {
+    if (platform !== 'darwin')
+        return '';
+    return Object.keys(env)
+        .filter((name) => /^DYLD_[A-Z_]+$/.test(name) && env[name])
+        .sort()
+        .map((name) => `${name}=${shQuoteArg(env[name])}\nexport ${name}\n`)
+        .join('');
 }
 /** Deliberately NOT the shim dir itself — see {@link nodeShimDir}. */
 const NODE_SHIM_SUBDIR = 'node-shim';
@@ -183,7 +268,7 @@ export function nodeShimDir() {
  * resolves NOWHERE, and it is reachable only from a package script's PATH (see
  * {@link nodeShimDir}).
  */
-function writeNodeShim(dir, gjs, selfEntry) {
+function writeNodeShim(dir, gjs, selfEntry, envPreamble) {
     if (!gjs)
         return;
     const sub = join(dir, NODE_SHIM_SUBDIR);
@@ -199,11 +284,15 @@ function writeNodeShim(dir, gjs, selfEntry) {
     // `--node-script` can honour, and yargs would take `--test` FOR the script
     // path (`unknown-options-as-args` turns an unknown flag into a positional).
     writeFileSync(shim, '#!/bin/sh\n' +
+        // Same SIP hop as the self-shim — see `buildSelfShimScript`.
+        dyldCarryPreamble(process.platform, process.env) +
         'case "$1" in\n' +
         '  -*) echo "gjsify: this host has no node; the gjsify shim runs a SCRIPT FILE only" >&2\n' +
         '      echo "gjsify: got: node $*" >&2\n' +
         '      exit 127 ;;\n' +
         'esac\n' +
+        // The same hop as the `gjsify` shim, so the same preamble.
+        envPreamble +
         `exec "${interpreter}" -m "${selfEntry}" run --node-script "$@"\n`, { mode: 0o755 });
     chmodSync(shim, 0o755);
 }

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

@@ -22,6 +22,12 @@ export interface ResolvedNode {
     /** Ranges keyed by name, as published. */
     dependencies: Record<string, string>;
     optionalDependencies: Record<string, string>;
+    /** As published; absent when the version declares none. Read through {@link requiredPeerEntries}. */
+    peerDependencies?: Record<string, string>;
+    /** As published — `optional: true` here is what keeps a peer from being installed. */
+    peerDependenciesMeta?: Record<string, {
+        optional?: boolean;
+    }>;
     bin?: string | Record<string, string>;
     /**
      * The version's `os`/`cpu`/`libc` declaration, as published. Recorded here
@@ -88,6 +94,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[]>;
 /**
@@ -142,6 +162,17 @@ export declare function warnMissingNativeBuilds(nodes: ResolvedNode[], prefix: s
  * `dependencies` entry to override), covered by {@link resolveDeps}'s second queue loop.
  */
 export declare function requiredDepEntries(node: Pick<ResolvedNode, 'dependencies' | 'optionalDependencies'>): [string, string][];
+/**
+ * A node's REQUIRED peer edges: its `peerDependencies` minus those
+ * `peerDependenciesMeta` marks `optional` (npm ≥ 7 installs the rest and skips
+ * these) and minus any name it also lists as a dependency — that edge is walked
+ * from the node itself by {@link requiredDepEntries}, or is optional because the
+ * publisher said so in `optionalDependencies`.
+ *
+ * Shared by the resolve walk and the optionality fixpoint, for the reason
+ * {@link requiredDepEntries} is: two readings of one manifest are two answers.
+ */
+export declare function requiredPeerEntries(node: Pick<ResolvedNode, 'dependencies' | 'optionalDependencies' | 'peerDependencies' | 'peerDependenciesMeta'>): [string, string][];
 /**
  * Recompute every node's `optional` flag as a FIXPOINT over the placed graph. The
  * only writer of the final flag; whatever the nodes arrive carrying is an input
@@ -149,7 +180,8 @@ export declare function requiredDepEntries(node: Pick<ResolvedNode, 'dependencie
  * file on the lockfile path) and is overwritten unconditionally.
  *
  * DEFINITION: a node is REQUIRED iff reachable from `requiredNames` through
- * REQUIRED edges alone ({@link requiredDepEntries}); every other node is optional.
+ * REQUIRED edges alone ({@link requiredDepEntries} plus {@link requiredPeerEntries} —
+ * a peer npm installs is as mandatory as a dependency); every other node is optional.
  * Optionality is therefore INHERITED — a plain dependency OF an optional package is
  * still optional, which is what npm's `optionalSet` computes.
  *