@gjsify/cli 0.51.1 → 0.52.0

package/lib/utils/publish-readback.js

@@ -105,29 +105,71 @@ export function probeTimeoutFor(configuredMs, remainingMs) {
     return Math.min(configuredMs, Math.max(remainingMs, MIN_PROBE_TIMEOUT_MS));
 }
 /**
- * Default polling budget: 300 s.
+ * Default polling budget: 600 s.
  *
- * The measured maximum lag between a 2xx and the registry recording the version
- * was 251.7 s (@gjsify/child_process, v0.46.0), so a budget below ~4.2 minutes
- * turns npm's normal queueing into a false red — and a false red at release time
- * costs a manual re-run of a workflow that did its job. 300 s clears that
- * maximum and is still short enough that a genuinely lost write is reported by
- * the job that lost it rather than by a later sweep.
+ * The lag between a 2xx and the registry recording the version has been measured
+ * on two releases, and the second broke the first's ceiling. v0.46.0 (199
+ * packages): 19 late writes, maximum 251.7 s (@gjsify/child_process). ts-for-gir
+ * v5.1.0 (12 packages, run 34899018849, PUT lines against `time["5.1.0"]`):
+ * four recorded ~0.7 s BEFORE the 2xx, eight after it — +74, +74, +75, +75,
+ * +96, +248, +248 and +368 s (@ts-for-gir/reporter) — the last past the 300 s
+ * this constant used to be, so "above the measured maximum" had quietly
+ * stopped being true of it. A budget below the lag turns npm's normal queueing into a false
+ * red, and a false red at release time costs a manual re-run of a workflow that
+ * did its job. A budget above it costs nothing on the nine in ten that confirm
+ * on the first probe; all it delays is the report of a genuinely LOST write —
+ * one in 199, measured — by the difference. 600 s is ~1.6x the larger maximum.
  *
- * THAT MAXIMUM IS A SAMPLE MAXIMUM, and the sample does not look truncated by
- * nature. The 19 lags fall in buckets ~20-30 s apart — 56(2), 76(3), 96(3),
+ * BOTH MAXIMA ARE SAMPLE MAXIMA, and neither sample looks truncated by nature.
+ * The v0.46.0 lags fall in buckets ~20-30 s apart — 56(2), 76(3), 96(3),
  * 127(4), 157(3), 189(1), 251(3) — and the TOP bucket is as populated as the
  * middle ones, which is the shape of a distribution cut off by the observation
- * rather than one decaying to zero. One release is one sample, so a lag past
- * 300 s is not ruled out; what makes 300 s affordable anyway is that the
- * remediation is verified rather than assumed. The re-run this reports lands on
- * the 409 path, and that path READS BACK too (see the conflict branch in
- * `commands/publish.ts`), so a window that turns out to be too short costs one
- * re-run that confirms — it does not hand back an unverified success.
+ * rather than one decaying to zero; the next release then produced a value past
+ * it. So a lag past 600 s is not ruled out either. What makes any finite window
+ * affordable is that the remediation is verified rather than assumed: the
+ * re-run this reports lands on the 409 path, and that path READS BACK too (see
+ * the conflict branch in `commands/publish.ts`), so a window that turns out too
+ * short costs one re-run that confirms — never an unverified success.
+ *
+ * `time[version]` is when the registry RECORDED the write, a lower bound on
+ * when the document npm installs from SERVES it: the reporter above was
+ * recorded at +368 s and a cache-busted read of its install document still
+ * lacked 5.1.0 ~40 min later. No budget waits that out, and none should — that
+ * state is what the `recorded-not-served` verdict names.
  */
-export const DEFAULT_VERIFY_BUDGET_MS = 300_000;
+export const DEFAULT_VERIFY_BUDGET_MS = 600_000;
 /**
- * Poll the registry until `name@version` resolves, or the budget runs out.
+ * Make one probe's URL uncacheable, by giving it a key no cache holds.
+ *
+ * THE REQUEST HEADER DOES NOT WORK, and this file used to say it did. Measured
+ * against registry.npmjs.org, twice, on two packages, one request apart:
+ *
+ *   cache-control: no-cache                → cf-cache-status: HIT, age: 192
+ *   cache-control: no-cache + pragma       → cf-cache-status: HIT, age: 193
+ *   cache-control: max-age=0               → cf-cache-status: HIT, age: 193
+ *   cache-control: no-store                → cf-cache-status: HIT, age: 193
+ *   ?<unique>                              → cf-cache-status: MISS
+ *
+ * The packument is served `cache-control: public, max-age=300`, so an edge may
+ * answer with a document up to 300 s old — the sweep's whole 5 s budget sixty
+ * times over, and half the fatal default. A read-back polling one such edge
+ * re-reads ONE document minted before the PUT for up to 300 s of its window and
+ * a short budget then reports the publish unconfirmed: a
+ * manufacturable false red on a publish that worked, and a verifier that cries
+ * wolf is one somebody turns off. It cannot produce the opposite error, because
+ * a document minted before the write cannot carry the version.
+ *
+ * The header is still sent: it costs nothing and a cache that DOES honour it
+ * (a corporate proxy, a Verdaccio) should. The parameter is namespaced so it
+ * cannot collide with a registry's own query vocabulary, and {@link probeOnce}
+ * falls back to the bare URL if a registry answers a non-404 4xx to it.
+ */
+function cacheBustedUrl(url, nonce) {
+    return `${url}${url.includes('?') ? '&' : '?'}__gjsify_readback=${encodeURIComponent(nonce)}`;
+}
+/**
+ * Poll the registry until `name@version` resolves, or the budget runs out, then
+ * say WHICH of the three states it found (see {@link ReadbackVerdict}).
  *
  * No side effects, no exits, no printing beyond the injected `log` — the caller
  * owns presentation, same contract as {@link import('./publish-diagnose.js')}.
@@ -151,6 +193,7 @@ export async function verifyPublishedVersion(input) {
             doFetch,
             probeTimeoutMs: probeTimeoutFor(probeTimeoutMs, budgetMs - (now() - started)),
             authorization: input.authorization,
+            nonce: `${started}-${attempts}`,
         });
         input.log?.(`gjsify publish: read-back probe ${attempts} of ${name}@${version} → ${last.state}` +
             (last.state === 'present' ? '' : ` (${last.detail})`));
@@ -161,24 +204,92 @@ export async function verifyPublishedVersion(input) {
             break;
         await sleep(Math.min(backoffFor(round), remaining));
     }
-    return { confirmed: last.state === 'present', attempts, elapsedMs: now() - started, url, last };
+    const base = { attempts, elapsedMs: now() - started, url, last };
+    if (last.state === 'present') {
+        return {
+            ...base,
+            confirmed: true,
+            verdict: 'confirmed',
+            verdictDetail: `${url} serves ${version} with a tarball`,
+        };
+    }
+    if (last.state === 'error') {
+        // NOTHING was established, so nothing may be concluded — least of all
+        // "published". This branch is the whole reason `error` exists next to
+        // `absent`, and it sends no corroboration request: a read that failed
+        // is not evidence to corroborate.
+        return {
+            ...base,
+            confirmed: false,
+            verdict: 'unknown',
+            verdictDetail: `the read-back could not reach a verdict — ${last.detail}`,
+        };
+    }
+    // ABSENT, which is one observation and two facts. Ask the registry's own
+    // record — `time[version]` on the FULL packument, the one field that
+    // separates them — ONE extra request, on the failure path only.
+    const record = await probeRegistryRecord({
+        url,
+        version,
+        doFetch,
+        // The configured per-probe timeout, NOT the budget-derived clamp: the
+        // budget is spent by now, and the clamp's floor is sized for the
+        // abbreviated document. The FULL packument is a different size class —
+        // measured, `typescript`'s is 15.7 MB and took 2.86 s to read, over the
+        // 2 s floor — so a corroboration on the floor would have answered
+        // `unknown` for exactly the packages whose failure most needs a verdict.
+        probeTimeoutMs,
+        authorization: input.authorization,
+        nonce: `${started}-record`,
+    });
+    input.log?.(`gjsify publish: read-back record probe of ${name}@${version} → ${record.state} (${record.detail})`);
+    if (record.state === 'recorded') {
+        return {
+            ...base,
+            confirmed: false,
+            verdict: 'recorded-not-served',
+            verdictDetail: record.detail,
+            recordedAt: record.recordedAt,
+        };
+    }
+    if (record.state === 'no-record') {
+        return {
+            ...base,
+            confirmed: false,
+            verdict: 'not-published',
+            verdictDetail: record.detail,
+        };
+    }
+    // The corroboration itself failed. The `absent` observation still stands —
+    // it is in `last` — but the two verdicts it was meant to separate are BOTH
+    // unearned now: no record was read, and neither was its absence. Naming
+    // `not-published` here would tell the operator to re-publish on the strength
+    // of a request that never answered, on the one line written so a tool never
+    // claims what it has not established.
+    return {
+        ...base,
+        confirmed: false,
+        verdict: 'unknown',
+        verdictDetail: record.detail,
+    };
 }
-async function probeOnce(input) {
+/**
+ * Read `time[version]` from the FULL packument.
+ *
+ * The abbreviated document the polling probe reads is what npm INSTALLS from and
+ * carries no `time` map, so this is a different document and deliberately a
+ * different request — the full packument for a long-lived package is large, which
+ * is exactly why it is asked once, only when the answer is about to be a failure.
+ */
+async function probeRegistryRecord(input) {
     const { url, version, doFetch, probeTimeoutMs } = input;
-    // `AbortController` + a timer rather than `AbortSignal.timeout`, which the
-    // CLI does not use anywhere and which this file must not be the first to
-    // require of a GJS host.
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), probeTimeoutMs);
     let res;
     try {
-        res = await doFetch(url, {
+        res = await doFetch(cacheBustedUrl(url, input.nonce), {
+            // No `accept` override: the FULL document, for its `time` map.
             headers: {
-                // Abbreviated packument: version keys + `dist`, a fraction of the
-                // bytes of the full document. `no-cache` because a CDN edge will
-                // otherwise answer with a document minted BEFORE the publish we
-                // are asking about — which is the whole question here.
-                accept: 'application/vnd.npm.install-v1+json',
                 'cache-control': 'no-cache',
                 ...(input.authorization ? { authorization: input.authorization } : {}),
             },
@@ -186,13 +297,105 @@ async function probeOnce(input) {
         });
     }
     catch (err) {
-        // A real throw path: network failure, DNS, or our own abort above.
         const msg = err instanceof Error ? err.message : String(err);
-        return { state: 'error', detail: `request failed (${msg})` };
+        return {
+            state: 'unknown',
+            detail: `the registry serves no ${version} and its own record was unreadable (${msg})`,
+        };
     }
     finally {
         clearTimeout(timer);
     }
+    if (res.status === 404) {
+        return { state: 'no-record', detail: 'the registry has no packument for this name at all (404)' };
+    }
+    if (!res.ok) {
+        return {
+            state: 'unknown',
+            detail: `the registry serves no ${version} and its own record answered ${res.status} ${res.statusText}`,
+        };
+    }
+    let doc;
+    try {
+        doc = await res.json();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            state: 'unknown',
+            detail: `the registry serves no ${version} and its own record is not JSON (${msg})`,
+        };
+    }
+    const time = doc?.time;
+    const recordedAt = time && typeof time === 'object' ? time[version] : undefined;
+    if (typeof recordedAt === 'string' && recordedAt.length > 0) {
+        return {
+            state: 'recorded',
+            recordedAt,
+            detail: `the registry RECORDS ${version} at ${recordedAt} and its install document does not serve it`,
+        };
+    }
+    return {
+        state: 'no-record',
+        detail: `the registry has no record of ${version} — neither in its install document nor in its own \`time\` map`,
+    };
+}
+/**
+ * One abbreviated-packument GET: cache-busted, with the non-404 4xx fallback.
+ *
+ * Extracted so the version read-back and {@link probePackageName} cannot drift
+ * into asking the registry two different questions — the same reason the
+ * read-back and `verify-published-closure.mjs` read the same document.
+ */
+async function sendPackumentRequest(input) {
+    const { url, doFetch, probeTimeoutMs } = input;
+    const headers = {
+        // Abbreviated packument: version keys + `dist`, a fraction of the bytes
+        // of the full document, and the document npm itself installs from.
+        // `cache-control` is sent for the caches that honour it; the edge in
+        // front of registry.npmjs.org measurably does not, which is what the
+        // query parameter is for.
+        accept: 'application/vnd.npm.install-v1+json',
+        'cache-control': 'no-cache',
+        ...(input.authorization ? { authorization: input.authorization } : {}),
+    };
+    // `AbortController` + a timer rather than `AbortSignal.timeout`, which the
+    // CLI does not use anywhere and which this file must not be the first to
+    // require of a GJS host.
+    const send = async (target) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), probeTimeoutMs);
+        try {
+            return await doFetch(target, { headers, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    let res;
+    try {
+        res = await send(cacheBustedUrl(url, input.nonce));
+        // A registry that does not know the parameter must not be reported as a
+        // failed publish because of it. 404 is excluded: that is a real answer
+        // about the NAME, and re-asking it bare would only re-ask a cache.
+        if (!res.ok && res.status !== 404 && res.status >= 400 && res.status < 500) {
+            res = await send(url);
+        }
+    }
+    catch (err) {
+        // A real throw path: network failure, DNS, or our own abort above.
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `request failed (${msg})` };
+    }
+    return res;
+}
+async function probeOnce(input) {
+    const { version } = input;
+    const sent = await sendPackumentRequest(input);
+    if ('error' in sent) {
+        return { state: 'error', detail: sent.error };
+    }
+    const res = sent;
     if (res.status === 404) {
         return { state: 'absent', status: 404, detail: '404 — the registry serves no packument for this name' };
     }
@@ -211,7 +414,7 @@ async function probeOnce(input) {
     }
     const versions = doc?.versions;
     const known = versions && typeof versions === 'object' ? Object.keys(versions) : [];
-    const entry = versions && typeof versions === 'object' ? versions[version] : undefined;
+    const entry = versions && typeof versions === 'object' && Object.hasOwn(versions, version) ? versions[version] : undefined;
     if (!entry) {
         const newest = known.length > 0 ? known[known.length - 1] : '(none)';
         return {
@@ -245,29 +448,105 @@ export function formatUnconfirmedPublish(opts) {
     // Only ever called on an UNCONFIRMED read-back, so `last` is `absent` or
     // `error` — both carry a `detail`; `present` has nothing to explain.
     const answered = readback.last.state === 'present' ? 'served' : readback.last.detail;
-    const headline = claim === 'already-published'
-        ? `npm says ${version} is ALREADY PUBLISHED but the registry does not serve it.`
-        : 'npm ACCEPTED the upload but the registry does not serve it.';
-    const remedy = claim === 'already-published'
+    const claimed = claim === 'already-published' ? `npm says ${version} is ALREADY PUBLISHED` : 'npm ACCEPTED the upload';
+    // THE HEADLINE IS THE VERDICT, not the claim. It used to assert "the registry
+    // does not serve it" for every unconfirmed read-back, including one whose
+    // last probe was a 5xx — a statement the probe had not earned, on the very
+    // line written to stop a tool claiming what it had not established.
+    const headline = readback.verdict === 'unknown'
+        ? readback.last.state === 'absent'
+            ? `${claimed}; its install document does not serve ${version} and the registry's own record could NOT be read.`
+            : `${claimed} and the read-back could NOT establish whether the registry serves it.`
+        : readback.verdict === 'recorded-not-served'
+            ? `${claimed}; the registry RECORDS ${version} and its install document does not serve it.`
+            : `${claimed} and the registry has no record of ${version}.`;
+    const remedy = readback.verdict === 'unknown'
         ? [
-            '  A 409 is npm refusing to overwrite a version it holds, which is not the same as serving it: in',
-            '  the v0.46.0 recovery @gjsify/node-runtime-darwin-arm64 was answered 409 at 09:48:49 and the',
-            '  registry recorded 0.46.0 at 09:49:07, 18s later. Re-running answers the same 409, so it cannot',
-            '  fix this — wait and re-read (`npm view <name>@<version>`), or check https://status.npmjs.org/.',
+            '  This is NOT a report that the publish failed, and it is not one that it worked. The read-back',
+            '  reached no answer it could act on, so the version may or may not be installable — confirm it',
+            '  before releasing anything that depends on it (`npm view <name>@<version> dist.tarball`).',
         ]
-        : [
-            '  A 2xx from npm is an ACCEPTED write, not a durable one. In the v0.46.0 release 19 of 199',
-            '  packages were recorded by the registry 56-252s after their 2xx, and ONE was never recorded',
-            '  at all while its job stayed green — that is the failure this check exists to name.',
-            `  Re-run this publish (\`--tolerate-republish\` no-ops if it landed meanwhile). If it keeps`,
-            '  failing, the write was rejected downstream of the 2xx: check https://status.npmjs.org/.',
-        ];
+        : readback.verdict === 'recorded-not-served'
+            ? [
+                '  Do NOT re-publish: the registry holds the write, so a re-run is answered 409 and changes',
+                "  nothing. The document npm installs from is behind the registry's own record — measured on",
+                '  the ts-for-gir v5.1.0 release, @ts-for-gir/reporter was recorded at 21:43:00.983Z and a',
+                '  cache-busted read of its install document still did not carry 5.1.0 ~40 min later. Wait and',
+                '  re-read; if it persists, check https://status.npmjs.org/.',
+            ]
+            : claim === 'already-published'
+                ? [
+                    '  A 409 is npm refusing to overwrite a version it holds, which is not the same as serving it:',
+                    '  in the v0.46.0 recovery @gjsify/node-runtime-darwin-arm64 was answered 409 at 09:48:49 and',
+                    '  the registry recorded 0.46.0 at 09:49:07, 18s later. Re-running answers the same 409, so it',
+                    '  cannot fix this — wait and re-read (`npm view <name>@<version>`), or check',
+                    '  https://status.npmjs.org/.',
+                ]
+                : [
+                    '  A 2xx from npm is an ACCEPTED write, not a durable one. In the v0.46.0 release 19 of 199',
+                    '  packages were recorded by the registry 56-252s after their 2xx, and ONE was never recorded',
+                    '  at all while its job stayed green — that is the failure this check exists to name.',
+                    `  Re-run this publish (\`--tolerate-republish\` no-ops if it landed meanwhile). If it keeps`,
+                    '  failing, the write was rejected downstream of the 2xx: check https://status.npmjs.org/.',
+                ];
     return [
         `gjsify publish: ${name}@${version} — ${headline}`,
         `  PUT       ${putUrl} (${payloadBytes} bytes) → ${putStatus} ${putStatusText}`,
-        `  read-back GET ${readback.url} (accept: application/vnd.npm.install-v1+json, cache-control: no-cache)`,
+        `  read-back GET ${readback.url} (accept: application/vnd.npm.install-v1+json, per-probe cache buster)`,
         `  answered  ${readback.last.state}: ${answered}`,
         `            after ${readback.attempts} probe(s) over ${seconds}s`,
+        `  verdict   ${readback.verdict} — ${readback.verdictDetail}`,
         ...remedy,
     ].join('\n');
 }
+let nameProbeSeq = 0;
+/**
+ * Ask ONE question: does this NAME exist on the registry at all.
+ *
+ * Deliberately not a version question, and that is what makes it safe to gate a
+ * publish on. A version is eventually consistent — measured on v0.46.0, 19 of
+ * 199 packages were recorded 56-252 s AFTER their own 2xx — so "is name@version
+ * there" answers "not yet" for minutes and a gate built on it would manufacture
+ * a red on a publish that worked. Presence of the NAME does not move once the
+ * first version lands, which is the same reason
+ * `verify-published-closure.mjs --phase pre-release` asks it rather than the
+ * version: an answer that does not move when the train moves.
+ */
+export async function probePackageName(input) {
+    const doFetch = input.fetchImpl ?? ((...args) => globalThis.fetch(...args));
+    const registryClean = input.registry.endsWith('/') ? input.registry.slice(0, -1) : input.registry;
+    const sent = await sendPackumentRequest({
+        url: `${registryClean}/${escapePackageName(input.name)}`,
+        doFetch,
+        probeTimeoutMs: input.probeTimeoutMs ?? 30_000,
+        authorization: input.authorization,
+        nonce: `name-${Date.now()}-${++nameProbeSeq}`,
+    });
+    if ('error' in sent) {
+        return { state: 'unknown', detail: sent.error };
+    }
+    if (sent.status === 404) {
+        return { state: 'absent', status: 404, detail: '404 — the registry serves no packument for this name' };
+    }
+    if (!sent.ok) {
+        return { state: 'unknown', status: sent.status, detail: `${sent.status} ${sent.statusText}` };
+    }
+    let doc;
+    try {
+        doc = await sent.json();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { state: 'unknown', status: sent.status, detail: `packument is not JSON (${msg})` };
+    }
+    const versions = doc?.versions;
+    const count = versions && typeof versions === 'object' ? Object.keys(versions).length : 0;
+    if (count === 0) {
+        // A 200 that carries no version is not a name that exists: every
+        // published name has at least one, and an unpublished-then-emptied
+        // packument is precisely the state npm serves for a name whose only
+        // version was unpublished.
+        return { state: 'unknown', status: sent.status, detail: 'a 200 carrying no versions establishes nothing' };
+    }
+    return { state: 'present', status: sent.status, versions: count };
+}

package/lib/utils/run-gjs.js

@@ -9,9 +9,12 @@
 //
 // Env composition is split out as the pure `computeNativeEnvForBundle()` so the e2e tests can
 // assert the env without spawning gjs.
-import { dirname, resolve } from 'node:path';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
 import { detectNativePackages, buildNativeEnv } from './detect-native-packages.js';
 import { describeExit, spawnToCompletion } from './spawn.js';
+import { captureNativeBacktrace, createHangWatchdog, formatHangReport, hangGraceMs, heartbeatEnv, } from './hang-watchdog.js';
 /**
  * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
  * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
@@ -40,12 +43,33 @@ export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inher
         .join(' ');
     return { env, envPrefix };
 }
+/**
+ * A private directory for the heartbeat file. Returns `undefined` when `/tmp` refuses —
+ * a read-only or full temp dir is a reason to run without the watchdog, never to fail the run
+ * the watchdog only watches.
+ */
+function safeMkdtemp() {
+    try {
+        return mkdtempSync(join(tmpdir(), 'gjsify-hb-'));
+    }
+    catch (_e) {
+        /* no writable temp dir — run unwatched rather than not at all */
+        return undefined;
+    }
+}
 export async function runGjsBundle(bundlePath, extraArgs = [], options) {
     const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath);
-    const env = {
-        ...process.env,
-        ...nativeEnv,
-    };
+    // The breadcrumb `@gjsify/unit` writes what it is running into, and this process polls —
+    // the only way a bundle that has stopped turning its main loop can still say which test it
+    // died in. Anything that is not a unit run never writes the file, so the watchdog stays
+    // inert; see `utils/hang-watchdog.ts`. The path is fresh per spawn, and `heartbeatEnv`
+    // REMOVES an inherited one when this spawn mints none, so two runs can never write into
+    // one file — but a bundle that spawns a unit run without going through this function still
+    // hands it whatever it inherited, so route such a spawn here.
+    const graceMs = hangGraceMs(process.env);
+    const heartbeatDir = graceMs > 0 ? safeMkdtemp() : undefined;
+    const heartbeatPath = heartbeatDir ? join(heartbeatDir, 'unit.heartbeat') : undefined;
+    const env = heartbeatEnv({ ...process.env, ...nativeEnv }, heartbeatPath);
     const gjsArgs = ['-m', bundlePath, ...extraArgs];
     // Echo the exact command so users can copy-paste it and run gjs without the wrapper.
     // stderr, so children speaking a protocol on stdout (an MCP stdio server) keep a clean one.
@@ -64,14 +88,66 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options) {
         process.exitCode = code;
         return process.exit(code);
     };
+    let child;
+    let hung = false;
+    const watchdog = heartbeatPath
+        ? createHangWatchdog({
+            read: () => {
+                try {
+                    return readFileSync(heartbeatPath, 'utf8');
+                }
+                catch (_e) {
+                    /* not written yet, or caught mid-rename — both mean "no claim yet" */
+                    return null;
+                }
+            },
+            graceMs,
+            onHang: (heartbeat, overdueMs) => {
+                const pid = child?.pid;
+                if (pid === undefined)
+                    return;
+                hung = true;
+                // The backtrace is taken BEFORE the kill: it is the only artefact that
+                // survives to say WHERE the wedge was, and a dead process has none.
+                console.error(formatHangReport({
+                    label: heartbeat.label,
+                    overdueMs,
+                    pid,
+                    graceMs,
+                    backtrace: captureNativeBacktrace(pid),
+                }));
+                // SIGABRT first so a GJS built with a fatal-signal handler still gets to
+                // dump what it knows; SIGKILL behind it because a process blocked in a
+                // native call may never run a handler at all.
+                child?.kill('SIGABRT');
+                setTimeout(() => child?.kill('SIGKILL'), 2_000);
+            },
+        })
+        : undefined;
     let result;
     try {
-        result = await spawnToCompletion('gjs', gjsArgs, { completion: options.completion, env });
+        result = await spawnToCompletion('gjs', gjsArgs, {
+            completion: options.completion,
+            env,
+            onSpawn: (c) => {
+                child = c;
+                watchdog?.start();
+            },
+        });
     }
     catch (err) {
         console.error(err.message);
         return failed(1);
     }
+    finally {
+        watchdog?.stop();
+        if (heartbeatDir)
+            rmSync(heartbeatDir, { recursive: true, force: true });
+    }
+    // A killed child reports only its signal; without this the hang report above would be
+    // followed by a bare "gjs exited with signal SIGABRT" and read as a crash.
+    if (hung)
+        return failed(result.code ?? 1);
     if (result.code !== 0) {
         console.error(`gjs exited with ${describeExit(result)}`);
         return failed(result.code ?? 1);

package/lib/utils/ship/icns.d.ts

@@ -0,0 +1,14 @@
+import type { AppIconRasters } from './icons.js';
+/** One element of the container: Apple's type code and the pixel size of the PNG it holds. */
+export interface IcnsElement {
+    readonly type: string;
+    readonly size: number;
+    /** The `.iconset` filename `iconutil` gives this element — the reader's spelling, for messages. */
+    readonly iconset: string;
+}
+/** The ten PNG-backed element types of a modern application icon, in `iconutil`'s order. */
+export declare const ICNS_ELEMENTS: readonly IcnsElement[];
+/** The distinct pixel sizes the ten elements need — what the layout asks the raster step for. */
+export declare const ICNS_SIZES: readonly number[];
+/** The `.icns` file, `TOC ` first, then the ten elements in {@link ICNS_ELEMENTS} order. */
+export declare function buildIcns(icon: AppIconRasters): Uint8Array;