@gjsify/cli 0.46.0 → 0.48.0

package/lib/commands/affected-classify.js

@@ -146,6 +146,27 @@ const SCRIPT_COUPLINGS = [
         runE2E: true,
         why: '@gjsify/create-app build → node scripts/process-template.mjs reads templates/',
     },
+    {
+        // THE SAME SHAPE AS `.githooks/` ABOVE, one layer up: the guard's trigger names
+        // the TEST's path instead of the thing under test. `AppRegistry.runApplication`
+        // holds three lines observable only by RUNNING the loop —
+        // `registerBuiltinWidgets()`, the `toShellOptions` passthrough and
+        // `provideWindowChrome()` — and their one external observer is
+        // `tests/e2e/react-native-devtools`, which main.yml's `e2e` job now runs under
+        // xvfb + a session bus (#1550). Without this entry a change confined to
+        // `packages/framework/react-native/**` seeds its own workspace, the e2e tier
+        // stays OFF (it turns on for a `tests/e2e/**` touch), and the suite is silent
+        // for exactly the PRs it exists to catch. Measured on #1540: deleting
+        // `provideWindowChrome()` left format, lint, tsc and all in-process assertions
+        // green while the application drew two header bars.
+        //
+        // No extra seeds — the package is a workspace and already seeds itself. The
+        // TIER is the point, as for `.githooks/`.
+        match: /^packages\/framework\/react-native\//,
+        seeds: [],
+        runE2E: true,
+        why: 'tests/e2e/react-native-devtools is the only external observer of AppRegistry.runApplication',
+    },
 ];
 export function classifyAndExpand(workspaces, changedFiles) {
     const files = changedFiles.map((f) => f.replace(/\\/g, '/')).filter((f) => f.length > 0);
@@ -255,7 +276,15 @@ export function classifyAndExpand(workspaces, changedFiles) {
             global: false,
             reason: `test-only (${remaining.length} file(s) in ${only})`,
             workspaces: [only],
-            runE2E: touchedE2E,
+            // `|| couplingRunE2E`: this shortcut skips CLOSURE EXPANSION, and a
+            // declared tier is not part of the closure. Dropping it here made a
+            // coupling's reach depend on the SHAPE of the changed path — the
+            // `.githooks/` entry survived only because a hook is not a spec file,
+            // while `packages/framework/react-native/src/widgets.spec.ts` fell
+            // through and turned the e2e tier back off. Measured by the vector
+            // "a react-native spec file ALSO turns the e2e tier on", which was RED
+            // when it was written (#1550).
+            runE2E: touchedE2E || couplingRunE2E,
             runIntegration: touchedIntegration || isIntegrationWorkspace(only),
             skipAll: false,
         };

package/lib/commands/dlx.js

@@ -13,6 +13,7 @@
 import { runGjsBundle } from '../utils/run-gjs.js';
 import { parseSpec } from '../utils/parse-spec.js';
 import { resolveGjsEntry } from '../utils/resolve-gjs-entry.js';
+import { doubleDashArgs } from '../utils/double-dash-args.js';
 import { cacheDirFor, createCacheKey, getValidCachedPkg, makePrepareDir, resolveInstalledPkgDir, symlinkSwap, } from '../utils/dlx-cache.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 export const dlxCommand = {
@@ -25,7 +26,11 @@ export const dlxCommand = {
         // --help` shows ts-for-gir's --help instead of gjsify dlx's.
         // Without `populate--`, the trailing `--help` is consumed at
         // the gjsify level and the bundle never sees it.
-        .parserConfiguration({ 'populate--': true })
+        // `parse-positional-numbers: false` alongside it: the `--` tail and the
+        // `[extraArgs..]` positional are the caller's argv, not numbers, and yargs
+        // otherwise retypes a bare `5` (#1531). `--cache-max-age` declares
+        // `type: 'number'` and is unaffected.
+        .parserConfiguration({ 'populate--': true, 'parse-positional-numbers': false })
         .positional('spec', {
         description: 'Package spec (`name`, `name@version`, `@scope/name@spec`, or local path).',
         type: 'string',
@@ -84,8 +89,7 @@ export const dlxCommand = {
         // number)[]`), so flags like `--help` reach the bundle untouched.
         // Merge those into the positional extraArgs the splitter sees so
         // both call shapes share one downstream path.
-        const passthroughDoubleDash = (args['--'] ?? []).map((v) => String(v));
-        const extraArgsCombined = [...(args.extraArgs ?? []), ...passthroughDoubleDash];
+        const extraArgsCombined = [...(args.extraArgs ?? []), ...doubleDashArgs(args)];
         const { binName, extraArgs } = splitBinAndArgs(pkgDir, args.binOrArg, extraArgsCombined);
         const entry = resolveGjsEntry(pkgDir, binName);
         if (entry.fromFallback) {

package/lib/commands/foreach.js

@@ -15,6 +15,7 @@ import { affectedClosure, buildDependencyGraph, discoverWorkspaces, filterWorksp
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { cliRuntimeClosure } from '../utils/cli-runtime-closure.js';
 import { prefixLines } from '../utils/prefixed-output.js';
+import { doubleDashArgs } from '../utils/double-dash-args.js';
 import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 // The ONE runner-selection rule, shared rather than re-derived. This file used to
 // carry its own copy; `workspace.ts` grew the bootstrap-CLI branch and the copy
@@ -267,6 +268,12 @@ export const foreachCommand = {
         //   gjsify foreach --exec -- npm publish --tag latest
         // without yargs grabbing --tag/--access/etc.
         'populate--': true,
+        // …and keep that tail as the TEXT the caller typed. Without
+        // this yargs types a bare number in the array as a `number`,
+        // which is how `--verify-timeout 5 --tag latest` reached 209
+        // npm publishes as `--verify-timeout --tag latest` (#1531).
+        // Declared `type: 'number'` options (`--jobs`) are unaffected.
+        'parse-positional-numbers': false,
     }),
     handler: async (args) => {
         // Walk up to the monorepo root — foreach is sometimes invoked
@@ -286,7 +293,7 @@ export const foreachCommand = {
             // Script mode silently DROPPED everything after `--` (only --exec
             // consumed args['--']). Forward them to each child invocation,
             // matching `yarn workspaces foreach run <script> -- <flags>`.
-            const fromDoubleDash = (args['--'] ?? []).filter((v) => typeof v === 'string');
+            const fromDoubleDash = doubleDashArgs(args);
             if (fromDoubleDash.length > 0)
                 cmdArgs = [...cmdArgs, ...fromDoubleDash];
         }
@@ -294,7 +301,7 @@ export const foreachCommand = {
             // With populate--:true, anything after the literal `--`
             // separator lands in top-level args['--']. yargs DOES NOT
             // attach it to args._ — it's a sibling array.
-            const fromDoubleDash = (args['--'] ?? []).filter((v) => typeof v === 'string');
+            const fromDoubleDash = doubleDashArgs(args);
             if (fromDoubleDash.length > 0) {
                 if (!cmd) {
                     cmd = fromDoubleDash[0];

package/lib/commands/onboard.js

@@ -660,6 +660,17 @@ function describePublishFailure(pub) {
             return 'OIDC/token auth failed';
         case 'diagnostic':
             return `HTTP 404 (${pub.diag.reason})`;
+        case 'publish-unconfirmed':
+            // npm claimed the version and the registry does not serve it. Counted
+            // as a FAILURE here on purpose: onboard's next step is `configureTrust`
+            // on a package it just decided exists. `onboard` passes `tolerate:
+            // true`, so `already-published` is the claim it meets on a RE-RUN —
+            // and #1407 is exactly a re-run that counted a half-stored publish
+            // as done.
+            return (`npm ${pub.claim === 'already-published' ? 'reported it already published' : 'accepted the upload'} ` +
+                `(HTTP ${pub.putStatus}) but ${pub.name}@${pub.version} did not ` +
+                `resolve on ${pub.registry} after ${pub.readback.attempts} probe(s) over ` +
+                `${(pub.readback.elapsedMs / 1000).toFixed(1)}s`);
         case 'error':
             return `HTTP ${pub.status} ${pub.statusText}`;
         default:

package/lib/commands/publish.d.ts

@@ -1,5 +1,6 @@
 import type { Command } from '../types/index.js';
 import { type Diagnose404Result } from '../utils/publish-diagnose.js';
+import { type ReadbackResult } from '../utils/publish-readback.js';
 import { OtpProvider } from '../utils/npm-otp.js';
 interface PublishOptions {
     path?: string;
@@ -8,6 +9,8 @@ interface PublishOptions {
     otp?: string;
     'tolerate-republish'?: boolean;
     'tolerate-untrusted-new'?: boolean;
+    'verify-timeout'?: number;
+    'verify-defer'?: boolean;
     provenance?: boolean;
     'dry-run'?: boolean;
     json?: boolean;
@@ -37,6 +40,13 @@ export interface PublishWorkspaceInput {
     otpProvider: OtpProvider;
     /** Send the cached code on the first PUT (publish `--otp`). */
     seedOtpFirst: boolean;
+    /**
+     * Polling budget for the post-PUT read-back, in ms. Default
+     * {@link DEFAULT_VERIFY_BUDGET_MS}; `0` skips the read-back entirely and the
+     * returned `published` outcome then carries no `readback` — an UNVERIFIED
+     * success, which is the pre-v0.46.0 behaviour and why this defaults on.
+     */
+    verifyBudgetMs?: number;
 }
 /** Discriminated result of {@link publishWorkspace}; the caller owns presentation. */
 export type PublishOutcome = {
@@ -49,12 +59,43 @@ export type PublishOutcome = {
     integrity: string;
     tag: string;
     registry: string;
+    /** The read-back that CONFIRMED it. `undefined` only when disabled. */
+    readback?: ReadbackResult;
+}
+/**
+ * npm returned 2xx and the registry does not serve the version. Its own
+ * outcome on purpose: not `published` (nothing is installable), not
+ * `republish-tolerated` (npm never claimed it existed), not `error` (the
+ * HTTP exchange succeeded). The v0.46.0 incident had no name at all — it
+ * came out as `+ name@version`, exit 0.
+ */
+ | {
+    ok: false;
+    action: 'publish-unconfirmed';
+    /**
+     * What npm claimed before the read-back disagreed: a 2xx (`accepted`)
+     * or a tolerated 409 (`already-published`). It selects the remediation
+     * sentence, which is the OPPOSITE one for a conflict — re-running
+     * answers the same 409.
+     */
+    claim: 'accepted' | 'already-published';
+    name: string;
+    version: string;
+    registry: string;
+    /** The PUT that was accepted. */
+    putStatus: number;
+    putStatusText: string;
+    putUrl: string;
+    payloadBytes: number;
+    readback: ReadbackResult;
 } | {
     ok: true;
     action: 'republish-tolerated';
     name: string;
     version: string;
     status: number;
+    /** The read-back that CONFIRMED the conflicting version. */
+    readback?: ReadbackResult;
 } | {
     ok: true;
     action: 'skipped-untrusted-new';

package/lib/commands/publish.js

@@ -19,6 +19,12 @@
 //     a sigstore signer that gjsify doesn't ship; we record the flag in the
 //     publish manifest but don't sign yet. Surface a warning so callers know.
 //   - --dry-run: pack only, no PUT.
+//   - --verify-timeout / --verify-defer: the post-PUT READ-BACK. npm's 2xx is an
+//     accepted write, not a durable one, so a successful PUT is confirmed by
+//     asking the registry for that exact version before `+ name@version` is
+//     printed. The incident, the measured lag distribution and the choice of
+//     window live in `utils/publish-readback.ts`; WHERE the read-back runs and
+//     what it costs is argued at its call site below.
 //
 // The request body matches npm's "publish" payload shape:
 //   {
@@ -36,11 +42,13 @@
 import { readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { base64Encode } from '../utils/base64.js';
 import { DEFAULT_REGISTRY, registryFor } from '@gjsify/npm-registry';
 import { buildPublishHeaders, escapePackageName } from '../utils/publish-headers.js';
 import { packWorkspace } from './pack.js';
 import { getNpmTrustedToken, hasGithubOidcEnv, OidcExchangeError, OidcUnavailableError } from '../utils/npm-oidc.js';
 import { diagnose404, is404DiagnosticCandidate } from '../utils/publish-diagnose.js';
+import { DEFAULT_VERIFY_BUDGET_MS, formatUnconfirmedPublish, verifyPublishedVersion, } from '../utils/publish-readback.js';
 import { loadNpmrc } from '../utils/load-npmrc.js';
 import { OtpProvider, withOtpRetry, isOtpChallenge } from '../utils/npm-otp.js';
 import { promptLine } from '../utils/prompt.js';
@@ -71,6 +79,16 @@ export const publishCommand = {
         description: 'Skip (exit 0) when OIDC token exchange returns `package not found` AND no fallback token is configured — i.e. a never-before-published `@scope/<name>` whose Trusted Publisher entry hasn\'t been set up on npmjs.com yet. Without this flag, one un-bootstrapped new package breaks the entire serialized `gjsify foreach publish` loop. Pair with `--tolerate-republish` in CI release workflows so a fresh-merged package gracefully skips its first CI publish, leaving the manual-bootstrap step to a maintainer (see AGENTS.md "New @gjsify/* package: first-publish + Trusted Publisher bootstrap").',
         type: 'boolean',
         default: false,
+    })
+        .option('verify-timeout', {
+        description: 'Seconds to keep asking the registry for the just-published version before giving up. npm answers 2xx to a write it has only ACCEPTED: in the v0.46.0 release 19 of 199 packages were recorded 56-252s after their 2xx and one was never recorded at all, so a shorter window turns normal queueing into a false red. `0` disables the read-back — for a registry with no packument read path.',
+        type: 'number',
+        default: DEFAULT_VERIFY_BUDGET_MS / 1000,
+    })
+        .option('verify-defer', {
+        description: 'Report an unconfirmed read-back and exit 0 instead of 1. ONLY for a caller that re-checks the same set afterwards — `gjsify run npm:publish` passes it because `scripts/verify-published-closure.mjs` sweeps the whole roster at the end of release.yml. Everywhere else an unconfirmed publish must fail the job that made it.',
+        type: 'boolean',
+        default: false,
     })
         .option('provenance', {
         description: "Pass-through flag — recorded in the payload but no signing happens (gjsify doesn't ship a sigstore signer yet).",
@@ -107,6 +125,17 @@ export const publishCommand = {
         const otp = args.otp;
         const tolerate = args['tolerate-republish'] === true;
         const tolerateUntrustedNew = args['tolerate-untrusted-new'] === true;
+        const verifySeconds = args['verify-timeout'] ?? DEFAULT_VERIFY_BUDGET_MS / 1000;
+        // A non-number reaches here as NaN (yargs coerces `--verify-timeout abc`
+        // silently), and NaN would fall through every `> 0` test and turn the
+        // read-back OFF without saying so — the failure mode this whole change
+        // exists to remove. Refuse it instead.
+        if (!Number.isFinite(verifySeconds) || verifySeconds < 0) {
+            console.error(`gjsify publish: --verify-timeout must be a non-negative number of seconds, got ${JSON.stringify(args['verify-timeout'])}`);
+            return process.exit(2);
+        }
+        const verifyBudgetMs = Math.round(verifySeconds * 1000);
+        const deferUnconfirmed = args['verify-defer'] === true;
         const provenance = args.provenance === true;
         const dryRun = args['dry-run'] === true;
         const checkTrustedOnly = args['check-trusted'] === true;
@@ -219,8 +248,9 @@ export const publishCommand = {
             json: args.json === true,
             otpProvider,
             seedOtpFirst: otp !== undefined,
+            verifyBudgetMs,
         });
-        reportPublishOutcome(outcome, args.json === true);
+        reportPublishOutcome(outcome, args.json === true, deferUnconfirmed);
     },
 };
 /**
@@ -329,12 +359,128 @@ export async function publishWorkspace(input) {
         return fetch(url, { method: 'PUT', headers: reqHeaders, body: bodyStr });
     };
     const res = await withOtpRetry(doPut, otpProvider, { seedFirstAttempt: input.seedOtpFirst });
+    if (verbose) {
+        // The debug output used to print the request and then the `+` success
+        // line, so a 200 and a 201 were indistinguishable and no body was ever
+        // recorded — which is why reconstructing the v0.46.0 incident needed the
+        // registry rather than the log it already had. Print what npm answered.
+        // `clone()` because the error path below reads `res.text()` itself.
+        console.error(`  response:      ${res.status} ${res.statusText}`);
+        const peek = await res
+            .clone()
+            .text()
+            .catch(() => '');
+        if (peek)
+            console.error(`  body:          ${peek.slice(0, 300)}`);
+    }
+    /**
+     * Ask the registry for what we just PUT. `undefined` when the read-back is
+     * off (`--verify-timeout 0`).
+     *
+     * The PUT's own `authorization` goes with it: a registry that requires a
+     * credential to READ answers 401/403 to an anonymous packument GET, which is
+     * an `error` probe, so an intact publish to GitHub Packages or an
+     * authenticated Verdaccio would spend the whole budget and then report
+     * `publish-unconfirmed`. Same origin, same credential, one request later.
+     */
+    const readBack = async () => {
+        const budgetMs = input.verifyBudgetMs ?? DEFAULT_VERIFY_BUDGET_MS;
+        if (budgetMs <= 0)
+            return undefined;
+        return verifyPublishedVersion({
+            registry: registryClean,
+            name: packed.name,
+            version: packed.version,
+            budgetMs,
+            authorization: headers['authorization'],
+            log: verbose ? (m) => console.error(m) : undefined,
+        });
+    };
     // A surviving OTP challenge means the provider gave up (no code entered /
     // non-interactive). Surface it so the caller can point at --otp.
     if (await isOtpChallenge(res)) {
         return { ok: false, action: 'otp-required', name: packed.name, version: packed.version, status: res.status };
     }
     if (res.ok) {
+        // WHERE THE READ-BACK BELONGS — per package, here, immediately.
+        //
+        // This path runs ~209 times per release (199 in the serial
+        // `foreach --exec` sweep behind `npm:publish`, plus the per-bundle
+        // single-package jobs), so its cost is measured rather than assumed:
+        //
+        //   CONFIRMED ON THE FIRST PROBE — 180 of 199 packages in v0.46.0. One
+        //   abbreviated-packument GET, 0.59 s against registry.npmjs.org, so
+        //   ~2 min across the whole sweep against a publish job that ran 33 min.
+        //
+        //   NOT CONFIRMED YET — the other 19. Here the read-back waits out
+        //   npm's own write queue, and those residual lags SUM TO 2554 s: a
+        //   sweep that waited them all out with the 300 s default would have
+        //   added ~43 min to that 33 min job. That single number decides the
+        //   shape below.
+        //
+        // A BATCHED END-OF-SWEEP CHECK CANNOT LIVE IN THIS FILE. `npm:publish`
+        // is `gjsify foreach --exec -- gjsify publish`, one CHILD PROCESS per
+        // package: there is no in-process hook after the last one to collect a
+        // pending set in. So the batched half already sits where it can —
+        // `scripts/verify-published-closure.mjs`, its own job at the end of
+        // `release.yml`, rounds and retries over the whole roster. It is what
+        // named the missing package in the incident.
+        //
+        // AND A FATAL READ-BACK INSIDE THAT SWEEP WOULD ABORT THE RELEASE, which
+        // is the argument the 2554 s only quantifies. `foreach --exec` THROWS on
+        // a non-zero child (`foreach.ts`: `exited with code ${result.code}`),
+        // and pack time has already rewritten every `workspace:*` to the exact
+        // released version — so one lagging package would stop the sweep
+        // mid-roster and leave a PARTIAL publish, the state
+        // `verify-published-closure.mjs` exists because it is worse than no
+        // publish at all. A deferral here is not leniency; it is the only shape
+        // that does not trade this incident for that one.
+        //
+        // Hence BOTH, split along that cost. The read-back runs per package
+        // everywhere and is FATAL by default — that is what turns the
+        // incident's green single-package job red, for up to 300 s of
+        // patience on a job that otherwise ran 59 s. The
+        // 199-package sweep passes `--verify-defer --verify-timeout 5`: it
+        // still CONFIRMS nine packages in ten and still names the suspect
+        // against the package that PUT it, but the minutes-long tail is left to
+        // the closure job that re-asks the same question over the same set —
+        // which had to be MADE able to answer it (`dist.tarball`, and a
+        // propagation retry that never fired for a roster-only name).
+        //
+        // What the deferred annotation is NOT is the ledger. At a 5 s budget
+        // every one of a release's ~19 lagging packages emits one, and GitHub
+        // renders only the first few annotations per step (documented as 10 per
+        // level; not verified from a run here). The closure job is the fatal
+        // half; the annotation points a human at the name.
+        const readback = await readBack();
+        if (readback?.confirmed && verbose) {
+            // The CONFIRMED half of the read-back is printed too, and it is not
+            // decoration: it is the only client-side measurement of when a
+            // version became RESOLVABLE, as against `time[version]`, which is
+            // when the registry recorded the write. The two are assumed equal by
+            // the 4.2-minute figure and the 300 s window, and nothing had ever
+            // measured the gap. The pre-registered comparison — and what each
+            // outcome would change — is in #1509's description; this line, under
+            // GJSIFY_PUBLISH_DEBUG (which release.yml sets), is its input. Note
+            // the value is quantised by the backoff grid, so it is the UPPER end
+            // of a bracket whose lower end is the previous probe.
+            console.error(`  read-back:     confirmed after ${readback.attempts} probe(s) in ${readback.elapsedMs} ms`);
+        }
+        if (readback && !readback.confirmed) {
+            return {
+                ok: false,
+                action: 'publish-unconfirmed',
+                claim: 'accepted',
+                name: packed.name,
+                version: packed.version,
+                registry: registryClean,
+                putStatus: res.status,
+                putStatusText: res.statusText,
+                putUrl: url,
+                payloadBytes: bodyStr.length,
+                readback,
+            };
+        }
         return {
             ok: true,
             action: 'published',
@@ -345,18 +491,50 @@ export async function publishWorkspace(input) {
             integrity: packed.integrity,
             tag,
             registry: registryClean,
+            readback,
         };
     }
     const text = await res.text().catch(() => '<no body>');
     // "version already published" — 409 Conflict, or 403 + "previously published".
+    //
+    // READ BACK HERE TOO, and the reason it was first written the other way is
+    // worth keeping: a 2xx is npm accepting a write it has not necessarily
+    // durably applied, whereas a 409 is npm ASSERTING the version exists and
+    // refusing to overwrite it — sounding like a positive statement about the
+    // registry's own state rather than a promise about a queued one. The
+    // incident's own recovery says otherwise. Attempt 3 re-PUT
+    // @gjsify/node-runtime-darwin-arm64 and was answered `409 already
+    // published` at 09:48:49.19, while that packument's `time["0.46.0"]` is
+    // 09:49:07.419 — 18 s LATER — and the closure job had found the name absent
+    // at 09:44:28. So the assertion can precede the version being served, and
+    // this is the path a `publish-unconfirmed` re-run always lands on: exempting
+    // it would leave the documented remediation reporting a success nothing
+    // checked. Cost is one GET, on a path that only runs on a re-publish.
     const isRepublishConflict = res.status === 409 || (res.status === 403 && /previously published/i.test(text));
     if (isRepublishConflict && tolerate) {
+        const readback = await readBack();
+        if (readback && !readback.confirmed) {
+            return {
+                ok: false,
+                action: 'publish-unconfirmed',
+                claim: 'already-published',
+                name: packed.name,
+                version: packed.version,
+                registry: registryClean,
+                putStatus: res.status,
+                putStatusText: res.statusText,
+                putUrl: url,
+                payloadBytes: bodyStr.length,
+                readback,
+            };
+        }
         return {
             ok: true,
             action: 'republish-tolerated',
             name: packed.name,
             version: packed.version,
             status: res.status,
+            readback,
         };
     }
     // 404 diagnostic (token-auth): disambiguate dead-token vs missing-package.
@@ -384,8 +562,13 @@ export async function publishWorkspace(input) {
 /**
  * Present a {@link PublishOutcome} on stdout/stderr and exit non-zero on
  * failure — the single-command `gjsify publish` behaviour, reproduced exactly.
+ *
+ * `deferUnconfirmed` (`--verify-defer`) affects exactly one outcome: it downgrades
+ * `publish-unconfirmed` from exit 1 to a printed warning, for a caller that
+ * re-checks the same set afterwards. It is policy, so it lives here and not in
+ * {@link publishWorkspace}, which stays a pure fact-finder.
  */
-function reportPublishOutcome(outcome, asJson) {
+function reportPublishOutcome(outcome, asJson, deferUnconfirmed = false) {
     switch (outcome.action) {
         case 'published': {
             const out = {
@@ -404,6 +587,44 @@ function reportPublishOutcome(outcome, asJson) {
                 process.stdout.write(`+ ${outcome.name}@${outcome.version}\n`);
             return;
         }
+        case 'publish-unconfirmed': {
+            const message = formatUnconfirmedPublish(outcome);
+            if (asJson) {
+                process.stdout.write(`${JSON.stringify({
+                    ok: false,
+                    action: 'publish-unconfirmed',
+                    name: outcome.name,
+                    version: outcome.version,
+                    registry: outcome.registry,
+                    claim: outcome.claim,
+                    putStatus: outcome.putStatus,
+                    probes: outcome.readback.attempts,
+                    elapsedMs: outcome.readback.elapsedMs,
+                    readbackUrl: outcome.readback.url,
+                    readbackState: outcome.readback.last.state,
+                    deferred: deferUnconfirmed,
+                }, null, 2)}\n`);
+            }
+            else {
+                process.stderr.write(`${message}\n`);
+            }
+            // Under `--verify-defer` the multi-line message is one entry in a
+            // serial log carrying a line per package, i.e. exactly the channel
+            // the incident's `+` line hid in. An annotation renders beside the
+            // job's own check and needs no writable file, the same reason
+            // `verify-published-closure.mjs` emits its notes as `::warning::`.
+            // On STDERR, because `--json` owns stdout.
+            if (deferUnconfirmed) {
+                if (process.env.GITHUB_ACTIONS) {
+                    const claimed = outcome.claim === 'already-published' ? 'was reported already published' : 'was accepted';
+                    process.stderr.write(`::warning title=Publish unconfirmed::${outcome.name}@${outcome.version} ${claimed} ` +
+                        `(HTTP ${outcome.putStatus}) but did not resolve on ${outcome.registry} within ` +
+                        `${(outcome.readback.elapsedMs / 1000).toFixed(1)}s — the release-closure job must confirm it\n`);
+                }
+                return;
+            }
+            return process.exit(1);
+        }
         case 'republish-tolerated': {
             const out = {
                 ok: true,
@@ -569,14 +790,6 @@ function buildPublishPayload(opts) {
         payload.access = access;
     return payload;
 }
-function base64Encode(bytes) {
-    let str = '';
-    const chunk = 0x8000;
-    for (let i = 0; i < bytes.length; i += chunk) {
-        str += String.fromCharCode(...bytes.subarray(i, i + chunk));
-    }
-    return btoa(str);
-}
 function handleOidcFailure(err, packageName, asJson) {
     if (err instanceof OidcUnavailableError) {
         const msg = `gjsify publish: OIDC not available — ${err.message}`;

package/lib/commands/run.js

@@ -15,6 +15,7 @@
 // to disambiguate can pass `./<file>` explicitly.
 import { readFileSync, statSync } from 'node:fs';
 import { basename, delimiter, join, resolve } from 'node:path';
+import { doubleDashArgs } from '../utils/double-dash-args.js';
 import { describeExit, spawnToCompletion } from '../utils/spawn.js';
 import { runGjsBundle } from '../utils/run-gjs.js';
 import { runRuntimeBundle } from '../utils/run-node.js';
@@ -93,6 +94,11 @@ export const runCommand = {
         // Without this, anything after `--` lands in args._ and is
         // silently dropped by the handler.
         'populate--': true,
+        // …and hand that tail on as the TEXT the caller typed. Without
+        // this yargs types a bare number in the array — and in the
+        // `[args..]` positional — as a `number`, which the reader below
+        // used to drop outright (#1531).
+        'parse-positional-numbers': false,
         // Forward UNKNOWN flags to the target without requiring `--`:
         //   gjsify run dist/app.gjs.mjs serve --port 8080 --year 2025
         // Without this, the top-level `.strict()` (cli-app.ts) rejects
@@ -111,8 +117,7 @@ export const runCommand = {
         // than silently discarding them (without it they land in args._ and
         // are never forwarded to the child).
         const positionalArgs = args.args ?? [];
-        const doubleDashArgs = (args['--'] ?? []).filter((v) => typeof v === 'string');
-        const extraArgs = [...positionalArgs, ...doubleDashArgs];
+        const extraArgs = [...positionalArgs, ...doubleDashArgs(args)];
         // `--node-script` (explicit) → run an UNBUNDLED Node-style script on the
         // host runtime; under GJS it is bundled `--app gjs` on the fly first.
         // Checked before `--runtime` and `--workspace`: it is a file mode, and

package/lib/commands/ship.js

@@ -42,13 +42,14 @@ import { isUnder, SHARE } from '../utils/ship/share-dirs.js';
 import { compileSchemasForStage } from '../utils/ship/schemas.js';
 import { buildMsi, MSI_PAYLOAD_DIR } from '../utils/ship/msi.js';
 import { buildZip, zipEntriesFromPayload } from '../utils/ship/zip.js';
+import { assertEntryRunsUnder } from '../utils/ship/entry-interpreter.js';
 import { scanGiNamespaces } from '../utils/ship/gi-namespaces.js';
 import { assertLauncherMatchesInterpreter, assertPayloadMatchesArch, buildTimestamp, isArchIndependent, linuxInstallDependent, readPayloadFacts, } from '../utils/ship/payload.js';
 import { assertOverlayIsLicensed, planOverlay, planStage } from '../utils/ship/plan.js';
 import { assertHostCanSign, notarizeArtifact, stapleArtifact, resolveNotaryPlan, resolveSignPlan, signPayload, } from '../utils/ship/signing.js';
 import { renderLauncher } from '../utils/ship/launcher.js';
 import { buildRpm } from '../utils/ship/rpm.js';
-import { declaredBundlePath, resolveShipApp, resolveShipSettings, } from '../utils/ship/settings.js';
+import { resolveShipApp, resolveShipBundle, resolveShipSettings, } from '../utils/ship/settings.js';
 import { assertExpectedTarget, assertFormatsStaged, formatTarget, overlayFiles, readStageManifest, resolveStageMtime, warnOnToolSkew, writeStageManifest, STAGE_MANIFEST_FILE, } from '../utils/ship/stage-manifest.js';
 import { directorySize, readStage, writePayload, writeStage } from '../utils/ship/stage-writer.js';
 const LOG = '[gjsify ship]';
@@ -280,12 +281,22 @@ async function assemble(args) {
             assertCanPack(format);
     if (!args['skip-build'])
         await runProjectBuild(projectDir);
+    // THE OTHER HALF of the resolution above, and they are one decision: the
+    // runtime a target execs and the entry it hands that runtime (#1545). Two
+    // keys, resolved by two twin functions, compared by `assertEntryRunsUnder`
+    // as soon as both answers and the file exist.
+    const resolvedBundle = resolveShipBundle({ pkg, ship, layoutOs: layout.os });
+    if (resolvedBundle.overridden) {
+        console.log(`${LOG} entry for ${layout.name}: ${resolvedBundle.declared} — \`${resolvedBundle.key}\` ` +
+            'overrides `gjsify.main`.');
+    }
     const discovered = discoverPayload({
         projectDir,
         pkg,
         ship,
         flatpakIcon: flatpak.icon,
-        declaredBundle: declaredBundlePath(pkg, ship),
+        declaredBundle: resolvedBundle.declared,
+        foreignBundles: resolvedBundle.foreign,
     });
     const { settings, metadata, warnings } = resolveShipSettings({
         projectDir,
@@ -308,6 +319,21 @@ async function assemble(args) {
     // the packing host.
     for (const format of formats)
         assertFormatCanRunInterpreter(format, settings.app);
+    // The entry, read ONCE: the pair check below and the namespace scan further
+    // down both ask what this file imports, and a bundle is the biggest file in
+    // the project.
+    const bundleSource = readFileSync(settings.bundlePath, 'utf-8');
+    // BEFORE anything is staged, for the reason above and one more: this is the
+    // refusal that says the artifact could never have started, and the run that
+    // reports it must not also print a stage path.
+    assertEntryRunsUnder({
+        interpreter: settings.app,
+        source: bundleSource,
+        entry: relative(projectDir, settings.bundlePath) || settings.bundlePath,
+        appKey: resolvedApp.key,
+        bundleKey: resolvedBundle.key,
+        layoutOs: layout.os,
+    });
     const mtime = buildTimestamp(settings.bundlePath);
     const metadataInputs = {
         appId: settings.appId,
@@ -354,6 +380,8 @@ async function assemble(args) {
         metainfo: translated.metainfo,
         desktopEntry: translated.desktopEntry,
         licenseText: settings.licenseFile === undefined ? undefined : readFileSync(settings.licenseFile, 'utf-8'),
+        changelogText: settings.changelogFile === undefined ? undefined : readFileSync(settings.changelogFile, 'utf-8'),
+        mtime,
     };
     const outRoot = resolve(projectDir, settings.outDir);
     const stageDir = join(outRoot, 'stage');
@@ -466,7 +494,7 @@ async function assemble(args) {
     // `gi://` specifiers are what the emitted `Depends:` is derived from
     // (ADR 0024 § 6), and the packing host has the staged copy but no way to
     // tell which staged file is the entry.
-    const namespaces = scanGiNamespaces(readFileSync(settings.bundlePath, 'utf-8'));
+    const namespaces = scanGiNamespaces(bundleSource);
     if (args.verbose)
         console.log(`${LOG} gi namespaces: ${namespaces.join(', ') || '(none)'}`);
     // PLACED, like the payload, and through the same map. `planOverlay` answers a
@@ -481,7 +509,7 @@ async function assemble(args) {
     // overlay reaches it by the same route.
     const overlay = new Map();
     for (const format of formats) {
-        overlay.set(format.id, planOverlay(settings, format, stageInputs).map((file) => ({
+        overlay.set(format.id, (await planOverlay(settings, format, stageInputs)).map((file) => ({
             ...file,
             path: place(layout, settings, file.path),
         })));