From 71f4264242d736229342b5d95dadc1193b4febdb Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Mon, 31 Aug 2026 23:02:52 +0000
Subject: [PATCH 1/2] perf(test): serve packed-pool installs from the npm cache
 with --prefer-offline

Every pack-and-install fixture in the packed pool revalidated registry
metadata on each `npm install`, even though the only artifact under test is
a local tarball. `--prefer-offline` joins the canonical install flag list in
tests/support/shared-pack.ts, so cached packuments are served as-is while
uncached dependencies still download. The two remaining scattered copies of
the flag list (cli.test.ts's packed consumer, the Windows packed native
smoke) now consume that one list instead of repeating it.

The release audit keeps its own flags and stays on live registry metadata:
its install is the tree `npm audit`, `npm audit signatures`, and `npm sbom`
report on, and it serves `audit:release` at the publish boundary. The
scaffolder's own `packageManager install` is product behavior, not a test
install, so it is untouched.

Packed-pool census unchanged: 8 files, 21 tests (20 passed / 1 skipped),
name-identical to main. Wall-clock effect is below this machine's noise
floor with a warm cache (controlled same-worktree A/B on the most
install-dense file: 17.96s vs 18.00s over six alternating pairs); the win
lands when packuments are stale, where forcing revalidation costs 222
registry requests and ~1.46s per install.
---
 packages/agent-bundle/tests/cli.test.ts              |  3 ++-
 .../tests/support/packed-native-smoke.ts             |  6 +++---
 packages/agent-bundle/tests/support/shared-pack.ts   | 12 ++++++++++--
 scripts/audit-packed-release.mjs                     |  4 ++++
 4 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/packages/agent-bundle/tests/cli.test.ts b/packages/agent-bundle/tests/cli.test.ts
index 0d3b36410..3fe8d96bc 100644
--- a/packages/agent-bundle/tests/cli.test.ts
+++ b/packages/agent-bundle/tests/cli.test.ts
@@ -7,6 +7,7 @@ import { promisify } from 'node:util';
 import { expect, it } from '@rstest/core';
 
 import { runCli as runSourceCli } from '../src/cli.ts';
+import { npmInstallArguments } from './support/shared-pack.ts';
 
 const execFile = promisify(executeFile);
 const workspaceRoot = process.cwd();
@@ -128,7 +129,7 @@ const createPackedConsumer = async (): Promise<{ readonly cli: string; readonly
   const [packed] = JSON.parse(stdout) as Array<{ readonly filename: string }>;
   await writeFile(join(root, 'package.json'), '{"type":"module"}\n');
   await execFile(
-    'npm', ['install', '--ignore-scripts', '--no-audit', '--no-fund', join(root, packed.filename)],
+    'npm', ['install', ...npmInstallArguments, join(root, packed.filename)],
     { cwd: root },
   );
   return { cli: join(root, 'node_modules', '.bin', 'agent-bundle'), root };
diff --git a/packages/agent-bundle/tests/support/packed-native-smoke.ts b/packages/agent-bundle/tests/support/packed-native-smoke.ts
index 99f38793c..aa50b0255 100644
--- a/packages/agent-bundle/tests/support/packed-native-smoke.ts
+++ b/packages/agent-bundle/tests/support/packed-native-smoke.ts
@@ -15,6 +15,8 @@ import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 
+import { npmInstallArguments } from './shared-pack.ts';
+
 const execFile = promisify(executeFile);
 const workspaceRoot = process.cwd();
 const packageRoot = join(workspaceRoot, 'packages', 'agent-bundle');
@@ -236,9 +238,7 @@ export const runPackedNativeSmoke = async (options: {
     const installed = await runNodeEntrypoint(npmEntrypoint, [
       'install',
       '--omit=dev',
-      '--ignore-scripts',
-      '--no-audit',
-      '--no-fund',
+      ...npmInstallArguments,
       join(tarballs, listing[0].filename),
     ], { cwd: consumer, environment });
     if (installed.exitCode !== 0) throw new Error('Packed native smoke could not install the release tarball.');
diff --git a/packages/agent-bundle/tests/support/shared-pack.ts b/packages/agent-bundle/tests/support/shared-pack.ts
index 124584daf..c5abce217 100644
--- a/packages/agent-bundle/tests/support/shared-pack.ts
+++ b/packages/agent-bundle/tests/support/shared-pack.ts
@@ -26,8 +26,16 @@ export const installedEnvironment = (): NodeJS.ProcessEnv => {
   return environment;
 };
 
-/** Canonical flags for installing a packed tarball into a consumer fixture. */
-export const npmInstallArguments = ['--ignore-scripts', '--no-audit', '--no-fund'] as const;
+/**
+ * Canonical flags for installing a packed tarball into a consumer fixture.
+ * `--prefer-offline` serves cached registry metadata without revalidating it:
+ * the tarball under test is always read from disk, and uncached dependencies
+ * are still fetched, so only the staleness round-trips are skipped. The
+ * release audit (scripts/audit-packed-release.mjs) deliberately does not use
+ * these flags — its install feeds `npm audit`/`npm audit signatures`, which
+ * must resolve against live registry metadata.
+ */
+export const npmInstallArguments = ['--ignore-scripts', '--no-audit', '--no-fund', '--prefer-offline'] as const;
 
 const packs = new Map<SharedPackPackage, Promise<SharedPack>>();
 let fallbackBuild: Promise<void> | undefined;
diff --git a/scripts/audit-packed-release.mjs b/scripts/audit-packed-release.mjs
index 744bd8eeb..34d5aeffb 100644
--- a/scripts/audit-packed-release.mjs
+++ b/scripts/audit-packed-release.mjs
@@ -157,6 +157,10 @@ const auditPackedRelease = async () => {
       '--pack-destination', tarballs,
     ], { cwd: packageRoot, env: productionEnvironment })).stdout);
     const tarball = join(tarballs, asString(filename, 'npm pack did not produce a tarball filename'));
+    // No `--prefer-offline` here (unlike the packed test pool's shared install
+    // flags): the tree this install produces is what `npm audit`, `npm audit
+    // signatures`, and `npm sbom` below report on, so it has to resolve against
+    // live registry metadata rather than whatever the cache last saw.
     await execNpm([
       'install',
       '--omit=dev',

From e2d4e6132bf1b5ff747d81907188ed87e794c7b2 Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Mon, 31 Aug 2026 23:56:39 +0000
Subject: [PATCH 2/2] perf(test): keep release-boundary installs on current
 registry metadata
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codex review on #109: exact direct pins do not fix the installed tree, since
transitive dependencies still carry ranges. Serving cached metadata to every
consumer install meant a newly published transitive version could be absent
from the proofs whose job is to stand in for a consumer installing today —
and scripts/audit-packed-release.mjs audits that tree without exercising it.

The flag list splits in the one helper instead. `npmInstallArguments` keeps
npm's default staleness checks and stays the default a new test inherits;
release-audit's production entrypoint walk, the scaffolder template matrix,
and the native host smoke use it. `cachedNpmInstallArguments` adds
`--prefer-offline` for the suites where the dependency tree is a means rather
than the subject: the packed consumer hermeticity proof, public-api-packed,
dev-workbench-packaging, rsc-runtime-optional-packaging, the packed Workbench
release e2e, the scaffolder-tarball fixture install, and cli.test.ts's packed
consumer.
---
 packages/agent-bundle/tests/cli.test.ts       |  4 +--
 .../tests/dev-workbench-packaging.test.ts     |  6 ++---
 .../tests/packed-consumer.test.ts             |  6 ++---
 .../tests/public-api-packed.test.ts           |  8 +++---
 .../rsc-runtime-optional-packaging.test.ts    |  4 +--
 .../tests/support/packed-native-smoke.ts      |  2 ++
 .../agent-bundle/tests/support/shared-pack.ts | 25 +++++++++++++------
 .../tests/support/scaffold-fixture.ts         |  4 +--
 .../tests/packed-release.e2e.test.ts          |  4 +--
 scripts/audit-packed-release.mjs              |  9 ++++---
 10 files changed, 43 insertions(+), 29 deletions(-)

diff --git a/packages/agent-bundle/tests/cli.test.ts b/packages/agent-bundle/tests/cli.test.ts
index 3fe8d96bc..1e828be26 100644
--- a/packages/agent-bundle/tests/cli.test.ts
+++ b/packages/agent-bundle/tests/cli.test.ts
@@ -7,7 +7,7 @@ import { promisify } from 'node:util';
 import { expect, it } from '@rstest/core';
 
 import { runCli as runSourceCli } from '../src/cli.ts';
-import { npmInstallArguments } from './support/shared-pack.ts';
+import { cachedNpmInstallArguments } from './support/shared-pack.ts';
 
 const execFile = promisify(executeFile);
 const workspaceRoot = process.cwd();
@@ -129,7 +129,7 @@ const createPackedConsumer = async (): Promise<{ readonly cli: string; readonly
   const [packed] = JSON.parse(stdout) as Array<{ readonly filename: string }>;
   await writeFile(join(root, 'package.json'), '{"type":"module"}\n');
   await execFile(
-    'npm', ['install', ...npmInstallArguments, join(root, packed.filename)],
+    'npm', ['install', ...cachedNpmInstallArguments, join(root, packed.filename)],
     { cwd: root },
   );
   return { cli: join(root, 'node_modules', '.bin', 'agent-bundle'), root };
diff --git a/packages/agent-bundle/tests/dev-workbench-packaging.test.ts b/packages/agent-bundle/tests/dev-workbench-packaging.test.ts
index 326ffde08..6d12f3b70 100644
--- a/packages/agent-bundle/tests/dev-workbench-packaging.test.ts
+++ b/packages/agent-bundle/tests/dev-workbench-packaging.test.ts
@@ -7,7 +7,7 @@ import { promisify } from 'node:util';
 
 import { describe, expect, it } from '@rstest/core';
 
-import { installedEnvironment, npmInstallArguments, sharedPackedTarball } from './support/shared-pack.ts';
+import { cachedNpmInstallArguments, installedEnvironment, sharedPackedTarball } from './support/shared-pack.ts';
 
 const execFile = promisify(executeFile);
 const workspaceRoot = process.cwd();
@@ -83,7 +83,7 @@ it('serves prebuilt workbench assets from an installed tarball without the repos
     expect(listing.stdout).not.toMatch(/package\/dist\/workbench\/.*-[a-f0-9]{8,}/iu);
 
     await writeFile(join(consumer, 'package.json'), '{"type":"module"}\n');
-    await execFile('npm', ['install', ...npmInstallArguments, tarball], { cwd: consumer });
+    await execFile('npm', ['install', ...cachedNpmInstallArguments, tarball], { cwd: consumer });
     await mkdir(join(project, 'skills', 'review'), { recursive: true });
     await Promise.all([
       writeFile(join(project, 'package.json'), '{"type":"module"}\n'),
@@ -115,7 +115,7 @@ it('runs the Agent API from an omit-dev installed tarball with its runtime MCP d
   const project = join(consumer, 'project');
   try {
     await writeFile(join(consumer, 'package.json'), '{"type":"module"}\n');
-    await execFile('npm', ['install', '--omit=dev', ...npmInstallArguments, tarball], { cwd: consumer });
+    await execFile('npm', ['install', '--omit=dev', ...cachedNpmInstallArguments, tarball], { cwd: consumer });
     await mkdir(join(project, 'skills', 'review'), { recursive: true });
     await Promise.all([
       writeFile(join(project, 'package.json'), '{"type":"module"}\n'),
diff --git a/packages/agent-bundle/tests/packed-consumer.test.ts b/packages/agent-bundle/tests/packed-consumer.test.ts
index 10b639724..aec4d5f95 100644
--- a/packages/agent-bundle/tests/packed-consumer.test.ts
+++ b/packages/agent-bundle/tests/packed-consumer.test.ts
@@ -20,7 +20,7 @@ import { promisify } from 'node:util';
 import { expect, it } from '@rstest/core';
 
 import { sha256Hex } from '../src/core/digest.ts';
-import { installedEnvironment, npmInstallArguments } from './support/shared-pack.ts';
+import { cachedNpmInstallArguments, installedEnvironment } from './support/shared-pack.ts';
 
 const execFile = promisify(executeFile);
 const workspaceRoot = process.cwd();
@@ -110,7 +110,7 @@ it('uses only an installed tarball after source deletion', async () => {
     // The two consumers are disjoint directories; npm's cache handles the
     // concurrent installs (the scaffolder e2e relies on the same property).
     await Promise.all([projectRoot, scriptProjectRoot].map(async (consumer) =>
-      execFile('npm', ['install', ...npmInstallArguments, tarball], {
+      execFile('npm', ['install', ...cachedNpmInstallArguments, tarball], {
         cwd: consumer,
         env: installedEnvironment(),
       })));
@@ -331,7 +331,7 @@ it('uses only an installed tarball after source deletion', async () => {
         '',
       ].join('\n')),
     ]);
-    await execFile('npm', ['install', ...npmInstallArguments, tarball], {
+    await execFile('npm', ['install', ...cachedNpmInstallArguments, tarball], {
       cwd: frameworkRoot,
       env: installedEnvironment(),
     });
diff --git a/packages/agent-bundle/tests/public-api-packed.test.ts b/packages/agent-bundle/tests/public-api-packed.test.ts
index 5db4ae6bf..b8a68b99f 100644
--- a/packages/agent-bundle/tests/public-api-packed.test.ts
+++ b/packages/agent-bundle/tests/public-api-packed.test.ts
@@ -7,7 +7,7 @@ import { promisify } from 'node:util';
 import { expect, it } from '@rstest/core';
 
 import { writeFixtureManifest } from './support/manifest.ts';
-import { npmInstallArguments, sharedPackedTarball } from './support/shared-pack.ts';
+import { cachedNpmInstallArguments, sharedPackedTarball } from './support/shared-pack.ts';
 
 interface PackageManifest {
   bin: {
@@ -58,7 +58,7 @@ it('writes the package version as the producer of a packed CLI manifest', async
   try {
     await writeFile(join(consumerRoot, 'package.json'), '{"type":"module"}\n');
     await execFile(
-      'npm', ['install', ...npmInstallArguments, tarball],
+      'npm', ['install', ...cachedNpmInstallArguments, tarball],
       { cwd: consumerRoot },
     );
 
@@ -90,7 +90,7 @@ it('imports the externalized config entry from a packed npm consumer', async ()
     await writeFile(join(consumerRoot, 'package.json'), '{"type":"module"}\n');
     await execFile(
       'npm',
-      ['install', ...npmInstallArguments, tarball],
+      ['install', ...cachedNpmInstallArguments, tarball],
       { cwd: consumerRoot },
     );
 
@@ -198,7 +198,7 @@ it('invokes a prebuilt MCP server from a clean packed consumer', async () => {
     await writeFile(join(consumerRoot, 'package.json'), '{"type":"module"}\n');
     await execFile(
       'npm',
-      ['install', ...npmInstallArguments, tarball],
+      ['install', ...cachedNpmInstallArguments, tarball],
       { cwd: consumerRoot },
     );
     const { stdout } = await execFile(process.execPath, [
diff --git a/packages/agent-bundle/tests/rsc-runtime-optional-packaging.test.ts b/packages/agent-bundle/tests/rsc-runtime-optional-packaging.test.ts
index ee8477592..d0a996933 100644
--- a/packages/agent-bundle/tests/rsc-runtime-optional-packaging.test.ts
+++ b/packages/agent-bundle/tests/rsc-runtime-optional-packaging.test.ts
@@ -6,7 +6,7 @@ import { promisify } from 'node:util';
 
 import { describe, expect, it } from '@rstest/core';
 
-import { npmInstallArguments, sharedPackedTarball } from './support/shared-pack.ts';
+import { cachedNpmInstallArguments, sharedPackedTarball } from './support/shared-pack.ts';
 
 const execFile = promisify(executeFile);
 const workspaceRoot = process.cwd();
@@ -45,7 +45,7 @@ describe.sequential('optional RSC runtime package boundary', () => {
       const tarListing = (await execFile('tar', ['-tf', tarball])).stdout;
       expect(tarListing).not.toMatch(/examples\/rsc-agent-runtime|react-server-dom-rspack|rsbuild-plugin-rsc/u);
 
-      await execFile('npm', ['install', ...npmInstallArguments, tarball], { cwd: consumer });
+      await execFile('npm', ['install', ...cachedNpmInstallArguments, tarball], { cwd: consumer });
       const dependencyTree = JSON.parse((await execFile('npm', ['ls', '--all', '--json'], { cwd: consumer })).stdout) as InstalledDependencyTree;
       const installedNames = installedDependencyNames(dependencyTree);
       for (const name of ['react', 'react-dom', 'react-server-dom-rspack', 'rsbuild-plugin-rsc']) {
diff --git a/packages/agent-bundle/tests/support/packed-native-smoke.ts b/packages/agent-bundle/tests/support/packed-native-smoke.ts
index aa50b0255..00e244612 100644
--- a/packages/agent-bundle/tests/support/packed-native-smoke.ts
+++ b/packages/agent-bundle/tests/support/packed-native-smoke.ts
@@ -15,6 +15,8 @@ import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 
+// The native smoke installs the production closure a real consumer would get,
+// so it stays on npm's default metadata staleness checks.
 import { npmInstallArguments } from './shared-pack.ts';
 
 const execFile = promisify(executeFile);
diff --git a/packages/agent-bundle/tests/support/shared-pack.ts b/packages/agent-bundle/tests/support/shared-pack.ts
index c5abce217..131a1959f 100644
--- a/packages/agent-bundle/tests/support/shared-pack.ts
+++ b/packages/agent-bundle/tests/support/shared-pack.ts
@@ -28,14 +28,25 @@ export const installedEnvironment = (): NodeJS.ProcessEnv => {
 
 /**
  * Canonical flags for installing a packed tarball into a consumer fixture.
- * `--prefer-offline` serves cached registry metadata without revalidating it:
- * the tarball under test is always read from disk, and uncached dependencies
- * are still fetched, so only the staleness round-trips are skipped. The
- * release audit (scripts/audit-packed-release.mjs) deliberately does not use
- * these flags — its install feeds `npm audit`/`npm audit signatures`, which
- * must resolve against live registry metadata.
+ * They keep npm's default metadata staleness checks, so the install resolves
+ * the tree a consumer would get today. That is the point of the proofs that
+ * stand in for a real consumer — release-audit's production entrypoint walk,
+ * the scaffolder template matrix, the native host smoke — and exact direct
+ * pins do not make it free: transitive ranges still move underneath them, and
+ * scripts/audit-packed-release.mjs audits the installed tree without ever
+ * exercising it.
  */
-export const npmInstallArguments = ['--ignore-scripts', '--no-audit', '--no-fund', '--prefer-offline'] as const;
+export const npmInstallArguments = ['--ignore-scripts', '--no-audit', '--no-fund'] as const;
+
+/**
+ * The same flags for suites that only prove the packed tarball resolves,
+ * imports, and runs, where the dependency tree is a means rather than the
+ * subject. `--prefer-offline` serves cached registry metadata without
+ * revalidating it: the tarball under test is always read from disk and
+ * uncached dependencies are still fetched, so only the staleness round-trips
+ * are skipped.
+ */
+export const cachedNpmInstallArguments = [...npmInstallArguments, '--prefer-offline'] as const;
 
 const packs = new Map<SharedPackPackage, Promise<SharedPack>>();
 let fallbackBuild: Promise<void> | undefined;
diff --git a/packages/create-agent-bundle/tests/support/scaffold-fixture.ts b/packages/create-agent-bundle/tests/support/scaffold-fixture.ts
index e321895a1..0ebcce5a8 100644
--- a/packages/create-agent-bundle/tests/support/scaffold-fixture.ts
+++ b/packages/create-agent-bundle/tests/support/scaffold-fixture.ts
@@ -6,7 +6,7 @@ import { promisify } from 'node:util';
 
 import { expect } from '@rstest/core';
 
-import { installedEnvironment, npmInstallArguments, sharedPackedTarball } from '../../../agent-bundle/tests/support/shared-pack.ts';
+import { cachedNpmInstallArguments, installedEnvironment, sharedPackedTarball } from '../../../agent-bundle/tests/support/shared-pack.ts';
 
 const execFile = promisify(executeFile);
 
@@ -36,7 +36,7 @@ const packFixture = async (): Promise<PackedFixture> => {
   const runnerRoot = join(root, 'runner');
   await mkdir(runnerRoot, { recursive: true });
   await writeFile(join(runnerRoot, 'package.json'), '{"name":"scaffold-runner","type":"module","private":true}\n');
-  await execFile('npm', ['install', ...npmInstallArguments, scaffolderTarball], {
+  await execFile('npm', ['install', ...cachedNpmInstallArguments, scaffolderTarball], {
     cwd: runnerRoot,
     env: installedEnvironment(),
   });
diff --git a/packages/workbench/tests/packed-release.e2e.test.ts b/packages/workbench/tests/packed-release.e2e.test.ts
index dfe352f39..83e0c8840 100644
--- a/packages/workbench/tests/packed-release.e2e.test.ts
+++ b/packages/workbench/tests/packed-release.e2e.test.ts
@@ -14,7 +14,7 @@ import {
   validateOutageLedger,
   type ConsoleErrorRecord,
 } from './support/packed-outage-ledger.ts';
-import { npmInstallArguments, sharedPackedTarball } from '../../agent-bundle/tests/support/shared-pack.ts';
+import { cachedNpmInstallArguments, sharedPackedTarball } from '../../agent-bundle/tests/support/shared-pack.ts';
 import { timeScale } from '../../agent-bundle/tests/support/time-scale.ts';
 import {
   availablePort,
@@ -83,7 +83,7 @@ e2e('runs every Agent API tool from the installed tarball', { timeout: 360_000 *
   let primaryFailure: Error | undefined;
   try {
     await writeFile(join(consumer, 'package.json'), '{"type":"module"}\n');
-    await execFile('npm', ['install', '--omit=dev', ...npmInstallArguments, tarball], {
+    await execFile('npm', ['install', '--omit=dev', ...cachedNpmInstallArguments, tarball], {
       cwd: consumer,
       env: installedEnvironment(),
     });
diff --git a/scripts/audit-packed-release.mjs b/scripts/audit-packed-release.mjs
index 34d5aeffb..4ae1ea5a9 100644
--- a/scripts/audit-packed-release.mjs
+++ b/scripts/audit-packed-release.mjs
@@ -157,10 +157,11 @@ const auditPackedRelease = async () => {
       '--pack-destination', tarballs,
     ], { cwd: packageRoot, env: productionEnvironment })).stdout);
     const tarball = join(tarballs, asString(filename, 'npm pack did not produce a tarball filename'));
-    // No `--prefer-offline` here (unlike the packed test pool's shared install
-    // flags): the tree this install produces is what `npm audit`, `npm audit
-    // signatures`, and `npm sbom` below report on, so it has to resolve against
-    // live registry metadata rather than whatever the cache last saw.
+    // No `--prefer-offline` here (unlike the packed pool's
+    // cachedNpmInstallArguments): the tree this install produces is what
+    // `npm audit`, `npm audit signatures`, and `npm sbom` below report on, so
+    // it has to resolve against live registry metadata rather than whatever
+    // the cache last saw.
     await execNpm([
       'install',
       '--omit=dev',