vouchington-tooling 0.1.7 → 0.1.9

package/README.md

@@ -47,6 +47,15 @@ vouchington post-review
 vouchington stage-review-payload optional|required <source> <destination>
 ```
 
+For persistent `pnpm-install`, v4 metadata tracks structural inputs separately from the
+`--install-scripts` policy. A warm scripts-enabled tree can therefore toggle
+`true → false → true` without forced reconciliation; a tree first installed with scripts disabled
+uses one script-suppressed verification install followed by `pnpm rebuild --pending --recursive`.
+When only newly pending dependency package IDs remain, it instead rebuilds those exact IDs without
+rerunning first-party workspace hooks.
+The command emits a structured non-secret provenance diagnostic identifying changed structural
+categories, the last script policy, script capability, and native-binary health.
+
 `download-optional-run-artifacts` uses the current Actions run and host. Pattern mode discovers
 non-expired artifacts across the run, keeps the first result for each name (matching `gh run
 download`), and extracts each selected name into its own directory. Ordinary absence is reported as

package/dist/gha-dependabot-automerge-action/index.test-helpers.d.mts

@@ -0,0 +1,22 @@
+export type DependencyUpdate = Record<'dependencyName' | 'directory' | 'newVersion' | 'packageEcosystem' | 'prevVersion' | 'updateType', string>;
+export interface ScriptResult {
+    failures: string[];
+    infos: string[];
+    mutationRequests: Array<{
+        body: string;
+        headers: Record<string, string>;
+        method: string;
+        url: string;
+    }>;
+    restGetCalls: Array<Record<string, unknown>>;
+    warnings: string[];
+}
+export declare function update(prevVersion: string, newVersion: string, updateType: string, dependencyName?: string): DependencyUpdate;
+export declare function runPolicy(metadata: DependencyUpdate[] | string | undefined, pullRequestOverrides?: Record<string, unknown>, freshPullRequestOverrides?: Record<string, unknown>, mergeToken?: string | undefined, mutationResult?: {
+    jsonError?: Error;
+    payload?: unknown;
+    status?: number;
+}, dependabot?: {
+    directory: string;
+    ecosystem: string;
+}, expectedBase?: string, expectedHead?: string, manualRules?: string, confirmedPullRequestOverrides?: Error | Record<string, unknown>, initialRefreshError?: Error): Promise<ScriptResult>;

package/dist/gha-dependabot-automerge-action/index.test-helpers.mjs

@@ -0,0 +1,113 @@
+import { readFileSync } from 'node:fs';
+import { parse as load } from 'yaml';
+const source = readFileSync('.github/actions/dependabot-automerge/action.yml', 'utf8');
+const action = load(source);
+const script = action.runs.steps.find((step) => step.uses?.startsWith('actions/github-script@'))
+    ?.with?.script;
+export function update(prevVersion, newVersion, updateType, dependencyName = 'example') {
+    return {
+        dependencyName,
+        directory: '/',
+        newVersion,
+        packageEcosystem: 'npm',
+        prevVersion,
+        updateType,
+    };
+}
+export async function runPolicy(metadata, pullRequestOverrides = {}, freshPullRequestOverrides = {}, mergeToken = 'merge-token', mutationResult = {}, dependabot = { directory: '/', ecosystem: 'npm' }, expectedBase, expectedHead, manualRules = '[]', confirmedPullRequestOverrides = freshPullRequestOverrides, initialRefreshError) {
+    if (!script)
+        throw new Error('Dependabot auto-merge script is missing');
+    const failures = [];
+    const infos = [];
+    const mutationRequests = [];
+    const restGetCalls = [];
+    const warnings = [];
+    const eventPullRequest = {
+        auto_merge: null,
+        base: { ref: 'main', sha: 'a'.repeat(40) },
+        draft: false,
+        head: {
+            ref: 'dependabot/npm_and_yarn/example-1.5.0',
+            repo: { full_name: 'example-owner/example-repo' },
+            sha: 'b'.repeat(40),
+        },
+        node_id: 'PR_node_id',
+        number: 123,
+        merged: false,
+        state: 'open',
+        title: 'Bump dependencies',
+        user: { login: 'dependabot[bot]' },
+        ...pullRequestOverrides,
+    };
+    const github = {
+        rest: {
+            pulls: {
+                async get(args) {
+                    restGetCalls.push(args);
+                    if (restGetCalls.length === 1 && initialRefreshError)
+                        throw initialRefreshError;
+                    if (restGetCalls.length > 1 && confirmedPullRequestOverrides instanceof Error)
+                        throw confirmedPullRequestOverrides;
+                    const overrides = restGetCalls.length === 1 || confirmedPullRequestOverrides instanceof Error
+                        ? freshPullRequestOverrides
+                        : confirmedPullRequestOverrides;
+                    return { data: { ...eventPullRequest, ...overrides } };
+                },
+            },
+        },
+    };
+    const context = {
+        payload: { pull_request: eventPullRequest, repository: { default_branch: 'main' } },
+        repo: { owner: 'example-owner', repo: 'example-repo' },
+    };
+    const core = {
+        setFailed(message) {
+            failures.push(message);
+        },
+        info(message) {
+            infos.push(message);
+        },
+        warning(message) {
+            warnings.push(message);
+        },
+    };
+    const environment = {
+        DEPENDABOT_DIRECTORY: dependabot.directory,
+        DEPENDABOT_ECOSYSTEM: dependabot.ecosystem,
+        EXPECTED_BASE_SHA: expectedBase ?? String(eventPullRequest.base.sha),
+        EXPECTED_HEAD_SHA: expectedHead ?? String(eventPullRequest.head.sha),
+        GRAPHQL_URL: 'https://github.example.test/api/graphql',
+        MANUAL_UPDATE_RULES: manualRules,
+    };
+    if (metadata !== undefined)
+        environment.UPDATED_DEPENDENCIES_JSON =
+            typeof metadata === 'string' ? metadata : JSON.stringify(metadata);
+    if (mergeToken !== undefined)
+        environment.AUTOMERGE_TOKEN = mergeToken;
+    const fetch = async (url, init) => {
+        if (typeof init.body !== 'string')
+            throw new TypeError('Dependabot auto-merge mutation body must be a string');
+        const body = init.body;
+        mutationRequests.push({
+            body,
+            headers: init.headers,
+            method: String(init.method),
+            url,
+        });
+        return {
+            async json() {
+                if (mutationResult.jsonError)
+                    throw mutationResult.jsonError;
+                return (mutationResult.payload ??
+                    (body.includes('disablePullRequestAutoMerge')
+                        ? { data: { disablePullRequestAutoMerge: { clientMutationId: null } } }
+                        : { data: { enablePullRequestAutoMerge: { clientMutationId: null } } }));
+            },
+            ok: (mutationResult.status ?? 200) < 400,
+            status: mutationResult.status ?? 200,
+        };
+    };
+    const AsyncFunction = Object.getPrototypeOf(async () => undefined).constructor;
+    await new AsyncFunction('github', 'context', 'core', 'process', 'fetch', script)(github, context, core, { env: environment }, fetch);
+    return { failures, infos, mutationRequests, restGetCalls, warnings };
+}

package/dist/gha-post-review/github.d.mts

@@ -14,6 +14,8 @@ export declare function createGhPostReviewIo(options: {
     payloadBytes: Buffer;
     token: string;
     exec: GhExec;
+    expectedHeadSha?: string;
+    expectedBaseSha?: string;
 }): PostReviewIo;
 export declare function postReviewFromEnv(env?: NodeJS.ProcessEnv, exec?: GhExec, claudeIo?: import("./claude-token.mts").ClaudeTokenIo): Promise<{
     posted: boolean;

package/dist/gha-post-review/github.mjs

@@ -33,8 +33,25 @@ export function writePostedOutput(posted, outputPath = process.env.GITHUB_OUTPUT
         return;
     appendFileSync(outputPath, `posted=${posted ? 'true' : 'false'}\n`);
 }
+function readPullRefs(repository, prNumber, exec) {
+    let lastError;
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+        try {
+            return exec([
+                'api',
+                `repos/${repository}/pulls/${prNumber}`,
+                '--jq',
+                '[.head.sha, .base.sha] | @tsv',
+            ]).split('\t');
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw lastError;
+}
 export function createGhPostReviewIo(options) {
-    const { repository, prNumber, payloadBytes, token, exec } = options;
+    const { repository, prNumber, payloadBytes, token, exec, expectedHeadSha, expectedBaseSha } = options;
     return {
         readFile() {
             return payloadBytes;
@@ -43,11 +60,34 @@ export function createGhPostReviewIo(options) {
             rmSync(path, { force: true });
         },
         getHeadSha() {
-            const sha = exec(['api', `repos/${repository}/pulls/${prNumber}`, '--jq', '.head.sha']);
-            if (!/^[0-9a-f]{40}$/u.test(sha)) {
-                throw new ReviewPayloadError(`Could not resolve PR head SHA (got "${sha}").`);
+            if (!/^[1-9][0-9]*$/u.test(prNumber)) {
+                throw new ReviewPayloadError('PR_NUMBER must be a positive integer.');
+            }
+            if (Boolean(expectedHeadSha) !== Boolean(expectedBaseSha)) {
+                throw new ReviewPayloadError('EXPECTED_HEAD_SHA and EXPECTED_BASE_SHA must be provided together.');
+            }
+            if (expectedHeadSha && !/^[0-9a-f]{40}$/u.test(expectedHeadSha)) {
+                throw new ReviewPayloadError('EXPECTED_HEAD_SHA must be a full lowercase commit SHA.');
+            }
+            if (expectedBaseSha && !/^[0-9a-f]{40}$/u.test(expectedBaseSha)) {
+                throw new ReviewPayloadError('EXPECTED_BASE_SHA must be a full lowercase commit SHA.');
+            }
+            const refs = readPullRefs(repository, prNumber, exec);
+            const [headSha = '', baseSha = ''] = refs;
+            if (!/^[0-9a-f]{40}$/u.test(headSha)) {
+                throw new ReviewPayloadError(`Could not resolve PR head SHA (got "${headSha}").`);
+            }
+            if (!/^[0-9a-f]{40}$/u.test(baseSha)) {
+                throw new ReviewPayloadError(`Could not resolve PR base SHA (got "${baseSha}").`);
+            }
+            if (expectedHeadSha && headSha !== expectedHeadSha) {
+                throw new ReviewPayloadError('PR head changed before posting the selected review.');
+            }
+            if (expectedBaseSha && baseSha !== expectedBaseSha) {
+                throw new ReviewPayloadError('PR base changed before posting the selected review.');
             }
-            return sha;
+            // Preserve the orchestrator-selected revision as the review commit_id after equality checks.
+            return expectedHeadSha || headSha;
         },
         listPullFiles() {
             return parseReviewFilesJson(exec(['api', '--paginate', `repos/${repository}/pulls/${prNumber}/files?per_page=100`]));
@@ -69,6 +109,8 @@ export async function postReviewFromEnv(env = process.env, exec = createGhExec()
         payloadBytes,
         token,
         exec,
+        expectedHeadSha: env.EXPECTED_HEAD_SHA ?? '',
+        expectedBaseSha: env.EXPECTED_BASE_SHA ?? '',
     }));
     const token = resolveReviewPostToken(env);
     if (token.source === 'github-token')

package/dist/gha-post-review/post.mjs

@@ -2,13 +2,18 @@ import { ReviewPayloadError, indexReviewFiles, parseReviewPayload, remapReviewCo
 export { MAX_REVIEW_COMMENTS as MAX_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES as MAX_PAYLOAD_BYTES, ReviewPayloadError as PostReviewError, } from '../gha-review-payload/index.mjs';
 export function runPostReview(payloadPath, io) {
     try {
-        let review = parseReviewPayload(io.readFile(payloadPath), io.getHeadSha());
+        const selectedHeadSha = io.getHeadSha();
+        let review = parseReviewPayload(io.readFile(payloadPath), selectedHeadSha);
         try {
             review = remapReviewComments(review, indexReviewFiles(io.listPullFiles()));
         }
         catch {
             // Keep the parsed review when the PR file list is unavailable.
         }
+        // The adapter also revalidates a pinned base; equality catches legacy live-head drift.
+        if (io.getHeadSha() !== selectedHeadSha) {
+            throw new ReviewPayloadError('PR head changed while preparing the selected review.');
+        }
         const first = io.postReview(review);
         if (first.ok)
             return { posted: true };

package/dist/pnpm-install/index.d.mts

@@ -6,4 +6,5 @@ export { formatReleaseAgeFailure, isReleaseAgeViolation, parseReleaseAgeViolatio
 export { flattenReleaseAgeSelectors, packageNameFromPnpmLockKey, pnpmLockPackageKeyMatchesSelector, validateReleaseAgeExemptionGroups, validateReleaseAgePolicy, } from './release-age-policy.mts';
 export type { ReleaseAgeExemptionGroup, ReleaseAgePermanentExemption, ReleaseAgePolicyConfig, ReleaseAgePolicySnapshot, } from './release-age-policy.mts';
 export { INSTALL_TERMINATION_FAILED, installExitCode, safeProcessGroup, startInstallHeartbeat, terminateProcessGroup, terminateSafeProcessGroup, } from './process.mts';
-export { persistentDependencyTreeIsCold, persistentMetadataFingerprint, persistentMetadataMatches, writePersistentMetadataStamp, } from './metadata.mts';
+export { persistentDependencyTreeIsCold } from './metadata.mts';
+export { persistentMetadataFingerprint, persistentMetadataMatches, writePersistentMetadataStamp, } from './metadata-legacy.mts';

package/dist/pnpm-install/index.mjs

@@ -4,4 +4,5 @@ export { baseInstallArgs, findWorkspaceLinkMismatches, listWorkspaces, logWorksp
 export { formatReleaseAgeFailure, isReleaseAgeViolation, parseReleaseAgeViolations, } from './release-age.mjs';
 export { flattenReleaseAgeSelectors, packageNameFromPnpmLockKey, pnpmLockPackageKeyMatchesSelector, validateReleaseAgeExemptionGroups, validateReleaseAgePolicy, } from './release-age-policy.mjs';
 export { INSTALL_TERMINATION_FAILED, installExitCode, safeProcessGroup, startInstallHeartbeat, terminateProcessGroup, terminateSafeProcessGroup, } from './process.mjs';
-export { persistentDependencyTreeIsCold, persistentMetadataFingerprint, persistentMetadataMatches, writePersistentMetadataStamp, } from './metadata.mjs';
+export { persistentDependencyTreeIsCold } from './metadata.mjs';
+export { persistentMetadataFingerprint, persistentMetadataMatches, writePersistentMetadataStamp, } from './metadata-legacy.mjs';

package/dist/pnpm-install/install-operations.d.mts

@@ -0,0 +1,4 @@
+import { type CommandResult, type InstallOptions } from './support.mts';
+export declare function withScriptPolicy(args: string[], installScripts: boolean): string[];
+export declare function install(args: string[], options: InstallOptions, label: string): Promise<void>;
+export declare function reconcileOrFail(options: InstallOptions, runCapture: (args: string[]) => Promise<CommandResult>): Promise<void>;

package/dist/pnpm-install/install-operations.mjs

@@ -0,0 +1,38 @@
+import { scheduler } from 'node:timers/promises';
+import { runPnpm } from './exec.mjs';
+import { INSTALL_TERMINATION_FAILED } from './process.mjs';
+import { formatReleaseAgeFailure, isReleaseAgeViolation } from './release-age.mjs';
+import { baseInstallArgs, findWorkspaceLinkMismatches, logWorkspaceLinkMismatches, } from './support.mjs';
+function fail(message) {
+    throw new Error(message);
+}
+export function withScriptPolicy(args, installScripts) {
+    return installScripts ? args : [...args, '--ignore-scripts'];
+}
+export async function install(args, options, label) {
+    for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
+        const result = await runPnpm(args, options);
+        if (result.code === 0)
+            return;
+        if (result.code === INSTALL_TERMINATION_FAILED)
+            fail(`${label} could not terminate safely`);
+        const output = `${result.output}\n${result.errorOutput ?? ''}`;
+        if (isReleaseAgeViolation(output))
+            fail(formatReleaseAgeFailure(label, output));
+        if (attempt < options.maxAttempts) {
+            console.warn(`${label} failed (attempt ${attempt}/${options.maxAttempts}); retrying`);
+            await scheduler.wait(5000);
+        }
+    }
+    fail(`${label} failed after ${options.maxAttempts} attempt${options.maxAttempts === 1 ? '' : 's'}`);
+}
+export async function reconcileOrFail(options, runCapture) {
+    const forced = ['install', '--frozen-lockfile', '--force', ...baseInstallArgs.slice(2)];
+    await install([...forced, '--ignore-scripts', '--ignore-pnpmfile'], options, 'script-free reconciliation');
+    await install(withScriptPolicy(forced, options.installScripts), options, 'strict persistent reconciliation');
+    const remaining = await findWorkspaceLinkMismatches(runCapture);
+    if (remaining.length > 0) {
+        logWorkspaceLinkMismatches(remaining);
+        fail('persistent reconciliation completed with invalid workspace links');
+    }
+}

package/dist/pnpm-install/metadata-legacy.d.mts

@@ -0,0 +1,4 @@
+import { type CaptureCommand } from './support.mts';
+export declare function persistentMetadataFingerprint(runCapture: CaptureCommand, installScripts: boolean): Promise<string>;
+export declare function persistentMetadataMatches(fingerprint: string): Promise<boolean>;
+export declare function writePersistentMetadataStamp(fingerprint: string): Promise<void>;

package/dist/pnpm-install/metadata-legacy.mjs

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { listWorkspaces, reportGlibcVersionRuntime } from './support.mjs';
+function persistentMetadataStampPath() {
+    return path.join(process.cwd(), 'node_modules', '.pnpm-install-metadata-health.v3.json');
+}
+function legacySharedStampPath() {
+    return path.join(process.cwd(), 'node_modules', '.pnpm-install-metadata-health.json');
+}
+function addFingerprintInput(hash, label, value) {
+    hash.update(`${label.length}:${label}${value.length}:${value}`);
+}
+async function optionalFile(pathname) {
+    try {
+        return await readFile(pathname, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+function runtimePlatformIdentity() {
+    const report = process.report?.getReport();
+    return JSON.stringify({
+        arch: process.arch,
+        glibc: reportGlibcVersionRuntime(report),
+        modules: process.versions.modules,
+        node: process.version,
+        npmConfigArch: process.env.npm_config_arch ?? '',
+        npmConfigLibc: process.env.npm_config_libc ?? '',
+        npmConfigPlatform: process.env.npm_config_platform ?? '',
+        platform: process.platform,
+    });
+}
+export async function persistentMetadataFingerprint(runCapture, installScripts) {
+    const workspaces = (await listWorkspaces(runCapture)).toSorted((left, right) => left.path.localeCompare(right.path));
+    const pnpmVersion = await runCapture(['--version']);
+    if (pnpmVersion.code !== 0)
+        throw new Error(`pnpm --version failed: ${pnpmVersion.errorOutput?.trim() || pnpmVersion.output.trim() || 'unknown error'}`);
+    const hash = createHash('sha256');
+    addFingerprintInput(hash, 'runtime', runtimePlatformIdentity());
+    addFingerprintInput(hash, 'pnpm', pnpmVersion.output.trim());
+    addFingerprintInput(hash, 'installScripts', String(installScripts));
+    for (const filename of [
+        'pnpm-lock.yaml',
+        'pnpm-workspace.yaml',
+        '.npmrc',
+        '.pnpmfile.cjs',
+        '.pnpmfile.mjs',
+    ])
+        addFingerprintInput(hash, filename, await optionalFile(path.join(process.cwd(), filename)));
+    for (const workspace of workspaces)
+        addFingerprintInput(hash, path.relative(process.cwd(), path.join(workspace.path, 'package.json')), await readFile(path.join(workspace.path, 'package.json'), 'utf8'));
+    return hash.digest('hex');
+}
+export async function persistentMetadataMatches(fingerprint) {
+    for (const filename of [persistentMetadataStampPath(), legacySharedStampPath()]) {
+        try {
+            const stamp = JSON.parse(await readFile(filename, 'utf8'));
+            if (stamp.version === 3 && stamp.fingerprint === fingerprint)
+                return true;
+        }
+        catch { }
+    }
+    return false;
+}
+export async function writePersistentMetadataStamp(fingerprint) {
+    const stampPath = persistentMetadataStampPath();
+    const directory = path.dirname(stampPath);
+    const temporary = `${stampPath}.${process.pid}.tmp`;
+    await mkdir(directory, { recursive: true });
+    try {
+        await writeFile(temporary, `${JSON.stringify({ fingerprint, version: 3 })}\n`);
+        await rename(temporary, stampPath);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/pnpm-install/metadata.d.mts

@@ -1,5 +1,18 @@
 import { type CaptureCommand } from './support.mts';
-export declare function persistentMetadataFingerprint(runCapture: CaptureCommand, installScripts: boolean): Promise<string>;
-export declare function persistentMetadataMatches(fingerprint: string): Promise<boolean>;
+import { type ProvenanceStatus } from './transition.mts';
+declare const componentNames: readonly ['lockfile', 'npm-config', 'pnpm', 'pnpmfiles', 'runtime', 'workspace-config', 'workspace-manifests'];
+type ComponentName = (typeof componentNames)[number];
+type StructuralProvenance = Record<ComponentName, string>;
+export declare function persistentMetadataFingerprintV4(runCapture: CaptureCommand): Promise<{
+    lockfile: string;
+    'npm-config': string;
+    pnpm: string;
+    pnpmfiles: string;
+    runtime: string;
+    'workspace-config': string;
+    'workspace-manifests': string;
+}>;
+export declare function persistentMetadataStatusV4(provenance: StructuralProvenance): Promise<ProvenanceStatus>;
+export declare function writePersistentMetadataStampV4(provenance: StructuralProvenance, installScripts: boolean, resetScriptsEnabledCapability: boolean, pendingDependencyBuilds?: string[]): Promise<void>;
 export declare function persistentDependencyTreeIsCold(): Promise<boolean>;
-export declare function writePersistentMetadataStamp(fingerprint: string): Promise<void>;
+export {};

package/dist/pnpm-install/metadata.mjs

@@ -2,15 +2,28 @@ import { createHash } from 'node:crypto';
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { listWorkspaces, reportGlibcVersionRuntime } from './support.mjs';
+import {} from './transition.mjs';
+const componentNames = [
+    'lockfile',
+    'npm-config',
+    'pnpm',
+    'pnpmfiles',
+    'runtime',
+    'workspace-config',
+    'workspace-manifests',
+];
 function persistentMetadataStampPath() {
     return path.join(process.cwd(), 'node_modules', '.pnpm-install-metadata-health.json');
 }
-function fail(message) {
-    throw new Error(message);
-}
 function addFingerprintInput(hash, label, value) {
     hash.update(`${label.length}:${label}${value.length}:${value}`);
 }
+function componentHash(inputs) {
+    const hash = createHash('sha256');
+    for (const [label, value] of inputs)
+        addFingerprintInput(hash, label, value);
+    return hash.digest('hex');
+}
 async function optionalFile(pathname) {
     try {
         return await readFile(pathname, 'utf8');
@@ -34,58 +47,112 @@ function runtimePlatformIdentity() {
         platform: process.platform,
     });
 }
-export async function persistentMetadataFingerprint(runCapture, installScripts) {
+export async function persistentMetadataFingerprintV4(runCapture) {
     const workspaces = (await listWorkspaces(runCapture)).toSorted((left, right) => left.path.localeCompare(right.path));
     const pnpmVersion = await runCapture(['--version']);
     if (pnpmVersion.code !== 0)
-        fail(`pnpm --version failed: ${pnpmVersion.errorOutput?.trim() || pnpmVersion.output.trim() || 'unknown error'}`);
-    const hash = createHash('sha256');
-    addFingerprintInput(hash, 'runtime', runtimePlatformIdentity());
-    addFingerprintInput(hash, 'pnpm', pnpmVersion.output.trim());
-    addFingerprintInput(hash, 'installScripts', String(installScripts));
-    for (const filename of [
-        'pnpm-lock.yaml',
-        'pnpm-workspace.yaml',
-        '.npmrc',
-        '.pnpmfile.cjs',
-        '.pnpmfile.mjs',
-    ])
-        addFingerprintInput(hash, filename, await optionalFile(path.join(process.cwd(), filename)));
-    for (const workspace of workspaces)
-        addFingerprintInput(hash, path.relative(process.cwd(), path.join(workspace.path, 'package.json')), await readFile(path.join(workspace.path, 'package.json'), 'utf8'));
-    return hash.digest('hex');
+        throw new Error(`pnpm --version failed: ${pnpmVersion.errorOutput?.trim() || pnpmVersion.output.trim() || 'unknown error'}`);
+    const files = new Map(await Promise.all(['pnpm-lock.yaml', 'pnpm-workspace.yaml', '.npmrc', '.pnpmfile.cjs', '.pnpmfile.mjs'].map(async (filename) => [filename, await optionalFile(path.join(process.cwd(), filename))])));
+    const manifests = await Promise.all(workspaces.map(async (workspace) => {
+        const filename = path.relative(process.cwd(), path.join(workspace.path, 'package.json'));
+        return [filename, await readFile(path.join(workspace.path, 'package.json'), 'utf8')];
+    }));
+    return {
+        lockfile: componentHash([['pnpm-lock.yaml', files.get('pnpm-lock.yaml')]]),
+        'npm-config': componentHash([['.npmrc', files.get('.npmrc')]]),
+        pnpm: componentHash([['version', pnpmVersion.output.trim()]]),
+        pnpmfiles: componentHash([
+            ['.pnpmfile.cjs', files.get('.pnpmfile.cjs')],
+            ['.pnpmfile.mjs', files.get('.pnpmfile.mjs')],
+        ]),
+        runtime: componentHash([['identity', runtimePlatformIdentity()]]),
+        'workspace-config': componentHash([['pnpm-workspace.yaml', files.get('pnpm-workspace.yaml')]]),
+        'workspace-manifests': componentHash(manifests),
+    };
 }
-export async function persistentMetadataMatches(fingerprint) {
-    try {
-        const stamp = JSON.parse(await readFile(persistentMetadataStampPath(), 'utf8'));
-        return stamp.version === 3 && stamp.fingerprint === fingerprint;
-    }
-    catch {
+function validStamp(value) {
+    if (typeof value !== 'object' || value === null)
         return false;
-    }
+    const stamp = value;
+    return (stamp.version === 4 &&
+        typeof stamp.lastInvocationInstallScripts === 'boolean' &&
+        typeof stamp.scriptsEnabledInstallSucceeded === 'boolean' &&
+        typeof stamp.provenance === 'object' &&
+        stamp.provenance !== null &&
+        componentNames.every((name) => typeof stamp.provenance?.[name] === 'string') &&
+        (stamp.pendingDependencyBuilds === undefined ||
+            (Array.isArray(stamp.pendingDependencyBuilds) &&
+                stamp.pendingDependencyBuilds.every((id) => typeof id === 'string'))));
 }
-export async function persistentDependencyTreeIsCold() {
+async function readPersistentMetadataState() {
     try {
-        await stat(path.dirname(persistentMetadataStampPath()));
-        return false;
+        const parsed = JSON.parse(await readFile(persistentMetadataStampPath(), 'utf8'));
+        return validStamp(parsed)
+            ? { kind: 'stamp', stamp: parsed }
+            : { kind: 'unsafe' };
     }
     catch (error) {
-        if (error.code === 'ENOENT')
-            return true;
-        /* v8 ignore next -- non-ENOENT stat failures are host-specific */
-        throw error;
+        return error.code === 'ENOENT'
+            ? { kind: 'missing' }
+            : { kind: 'unsafe' };
     }
 }
-export async function writePersistentMetadataStamp(fingerprint) {
+async function readPersistentMetadataStamp() {
+    const state = await readPersistentMetadataState();
+    return state.kind === 'stamp' ? state.stamp : undefined;
+}
+export async function persistentMetadataStatusV4(provenance) {
+    const state = await readPersistentMetadataState();
+    if (state.kind === 'missing')
+        return { kind: 'absent' };
+    if (state.kind === 'unsafe')
+        return { kind: 'unsafe' };
+    const { stamp } = state;
+    const changed = componentNames.filter((name) => stamp.provenance[name] !== provenance[name]);
+    return changed.length > 0
+        ? { kind: 'changed', components: changed }
+        : {
+            kind: 'matching',
+            lastInvocationInstallScripts: stamp.lastInvocationInstallScripts,
+            pendingDependencyBuilds: stamp.pendingDependencyBuilds ?? [],
+            scriptsEnabledInstallSucceeded: stamp.scriptsEnabledInstallSucceeded,
+        };
+}
+export async function writePersistentMetadataStampV4(provenance, installScripts, resetScriptsEnabledCapability, pendingDependencyBuilds) {
+    const existing = await readPersistentMetadataStamp();
+    const existingMatches = existing && componentNames.every((name) => existing.provenance[name] === provenance[name]);
+    const stamp = {
+        lastInvocationInstallScripts: installScripts,
+        pendingDependencyBuilds: (pendingDependencyBuilds ??
+            (existingMatches ? existing.pendingDependencyBuilds : undefined) ??
+            []).toSorted(),
+        provenance,
+        scriptsEnabledInstallSucceeded: installScripts ||
+            (!resetScriptsEnabledCapability &&
+                Boolean(existingMatches && existing.scriptsEnabledInstallSucceeded)),
+        version: 4,
+    };
     const stampPath = persistentMetadataStampPath();
     const directory = path.dirname(stampPath);
     const temporary = `${stampPath}.${process.pid}.tmp`;
     await mkdir(directory, { recursive: true });
     try {
-        await writeFile(temporary, `${JSON.stringify({ fingerprint, version: 3 })}\n`);
+        await writeFile(temporary, `${JSON.stringify(stamp)}\n`);
         await rename(temporary, stampPath);
     }
     finally {
         await rm(temporary, { force: true });
     }
 }
+export async function persistentDependencyTreeIsCold() {
+    try {
+        await stat(path.dirname(persistentMetadataStampPath()));
+        return false;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return true;
+        /* v8 ignore next -- non-ENOENT stat failures are host-specific */
+        throw error;
+    }
+}

package/dist/pnpm-install/pending-builds.d.mts

@@ -0,0 +1,17 @@
+export type PendingBuilds = {
+    kind: 'known';
+    ids: Set<string>;
+} | {
+    kind: 'unknown';
+};
+export type PendingBuildDelta = {
+    kind: 'unknown';
+} | {
+    kind: 'known';
+    dependencyIds: string[];
+    workspaceIds: string[];
+};
+export declare function pendingBuilds(): Promise<PendingBuilds>;
+export declare function validDependencyBuildIds(ids: [string, ...string[]]): Promise<[string, ...string[]] | undefined>;
+export declare function clearPendingDependencyBuilds(ids: string[]): Promise<boolean>;
+export declare function pendingBuildDelta(before: PendingBuilds, after: PendingBuilds): Promise<PendingBuildDelta>;

package/dist/pnpm-install/pending-builds.mjs

@@ -0,0 +1,87 @@
+import { readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse, stringify } from 'yaml';
+export async function pendingBuilds() {
+    try {
+        const value = parse(await readFile(path.join(process.cwd(), 'node_modules', '.modules.yaml'), 'utf8'));
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return { kind: 'unknown' };
+        const pending = value.pendingBuilds ?? [];
+        if (!Array.isArray(pending) || !pending.every((id) => typeof id === 'string'))
+            return { kind: 'unknown' };
+        return { kind: 'known', ids: new Set(pending) };
+    }
+    catch {
+        return { kind: 'unknown' };
+    }
+}
+async function lockfileDependencyIds() {
+    try {
+        const lockfile = parse(await readFile(path.join(process.cwd(), 'pnpm-lock.yaml'), 'utf8'));
+        if (typeof lockfile !== 'object' || lockfile === null || !('packages' in lockfile))
+            return undefined;
+        const packages = lockfile.packages;
+        if (typeof packages !== 'object' || packages === null || Array.isArray(packages))
+            return undefined;
+        return new Set(Object.keys(packages));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function validDependencyBuildIds(ids) {
+    const packages = await lockfileDependencyIds();
+    if (!packages || !ids.every((id) => packages.has(id)))
+        return undefined;
+    const [first, ...remaining] = ids.toSorted();
+    return [first, ...remaining];
+}
+export async function clearPendingDependencyBuilds(ids) {
+    const filename = path.join(process.cwd(), 'node_modules', '.modules.yaml');
+    try {
+        const value = parse(await readFile(filename, 'utf8'));
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return false;
+        const record = value;
+        if (!Array.isArray(record.pendingBuilds) ||
+            !record.pendingBuilds.every((id) => typeof id === 'string'))
+            return false;
+        const ignored = record.ignoredBuilds ?? [];
+        if (!Array.isArray(ignored) ||
+            !ignored.every((id) => typeof id === 'string') ||
+            ids.some((id) => ignored.includes(id)))
+            return false;
+        record.pendingBuilds = record.pendingBuilds.filter((id) => !ids.includes(id));
+        const temporary = `${filename}.${process.pid}.tmp`;
+        try {
+            await writeFile(temporary, stringify(record));
+            await rename(temporary, filename);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function pendingBuildDelta(before, after) {
+    if (before.kind !== 'known' || after.kind !== 'known')
+        return { kind: 'unknown' };
+    const packages = await lockfileDependencyIds();
+    if (!packages)
+        return { kind: 'unknown' };
+    const dependencyIds = [];
+    const workspaceIds = [];
+    for (const id of after.ids) {
+        if (before.ids.has(id))
+            continue;
+        (packages.has(id) ? dependencyIds : workspaceIds).push(id);
+    }
+    return {
+        kind: 'known',
+        dependencyIds: dependencyIds.toSorted(),
+        workspaceIds: workspaceIds.toSorted(),
+    };
+}

package/dist/pnpm-install/pnpm-install-fake-pnpm.test-helpers.d.mts

@@ -0,0 +1 @@
+export declare function fakePnpmScript(): string;

package/dist/pnpm-install/pnpm-install-fake-pnpm.test-helpers.mjs

@@ -0,0 +1,52 @@
+export function fakePnpmScript() {
+    return `#!/usr/bin/env bash
+set -euo pipefail
+if [ "\${1:-}" = m ]; then
+  if [ -n "\${PNPM_LIST_WARNING:-}" ]; then printf '%s\\n' "$PNPM_LIST_WARNING" >&2; fi
+  printf '%s\\n' "$PNPM_WORKSPACES_JSON"
+  exit 0
+fi
+if [ "\${1:-}" = --version ]; then
+  printf '%s\\n' "\${PNPM_VERSION:-11.0.0}"
+  exit 0
+fi
+printf '%s\\n' "$*" >> "$PNPM_LOG"
+calls=0
+if [ -f "$PNPM_CALLS" ]; then calls="$(cat "$PNPM_CALLS")"; fi
+calls=$((calls + 1))
+printf '%s' "$calls" > "$PNPM_CALLS"
+print_release_age_violation() {
+  printf '%s\\n' '✗ Lockfile failed supply-chain policy check (1 entries in 0.1s)'
+  printf '%s\\n' '[ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION] 1 lockfile entries failed verification:'
+  printf '%s\\n' '  undici@8.10.0 was published at 2026-08-03T15:06:33.000Z, within the minimumReleaseAge cutoff (2026-08-02T04:48:10.357Z)'
+}
+if [ "\${PNPM_FAIL_CALL:-0}" = "$calls" ]; then
+  if [ -n "\${PNPM_FAIL_RELEASE_AGE:-}" ]; then print_release_age_violation; fi
+  exit "\${PNPM_FAIL_CODE:-1}"
+fi
+if [ "\${PNPM_FAIL_RELEASE_AGE_CALL:-0}" = "$calls" ]; then
+  print_release_age_violation
+  exit 1
+fi
+if [ -n "\${PNPM_SLEEP_SECONDS:-}" ]; then sleep "$PNPM_SLEEP_SECONDS"; fi
+if [ -n "\${PNPM_PENDING_BUILDS:-}" ]; then
+  mkdir -p "$PNPM_NODE_MODULES"
+  printf 'pendingBuilds: [%s]\\n' "$PNPM_PENDING_BUILDS" > "$PNPM_NODE_MODULES/.modules.yaml"
+fi
+case " $* " in
+  *' rebuild '*)
+    if [ "\${PNPM_REBUILD_INVALID_LEDGER:-0}" = 1 ]; then
+      printf 'pendingBuilds: invalid\n' > "$PNPM_NODE_MODULES/.modules.yaml"
+    fi
+    if [ "\${PNPM_REBUILD_BREAK_LINK:-0}" = 1 ]; then rm -f "$PNPM_DEPENDENCY_LINK"; fi
+    ;;
+  *' --force '*)
+    if [ "\${PNPM_REPAIR_LINK:-0}" = 1 ]; then
+      mkdir -p "$(dirname "$PNPM_DEPENDENCY_LINK")"
+      rm -f "$PNPM_DEPENDENCY_LINK"
+      ln -s "$PNPM_DEPENDENCY" "$PNPM_DEPENDENCY_LINK"
+    fi
+    ;;
+esac
+`;
+}

package/dist/pnpm-install/pnpm-install-fixture.test-helpers.mjs

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 import { runPnpmInstallCli } from '../cli/commands/pnpm-install.mjs';
+import { fakePnpmScript } from './pnpm-install-fake-pnpm.test-helpers.mjs';
 const execFileAsync = promisify(execFile);
 async function writeJson(path, value) {
     await mkdir(dirname(path), { recursive: true });
@@ -20,6 +21,7 @@ export async function makeFixture() {
     await Promise.all([
         writeJson(join(root, 'package.json'), { name: 'fixture-root', private: true }),
         writeFile(join(root, 'pnpm-workspace.yaml'), 'packages:\n  - packages/*\nminimumReleaseAge: 2880\n'),
+        writeFile(join(root, 'pnpm-lock.yaml'), 'lockfileVersion: 9\npackages: {}\n'),
         writeJson(join(consumer, 'package.json'), {
             name: '@fixture/consumer',
             dependencies: { '@fixture/dependency': 'workspace:^' },
@@ -29,46 +31,7 @@ export async function makeFixture() {
         mkdir(pnpmBin),
     ]);
     await symlink(dependency, dependencyLink, 'dir');
-    await writeFile(join(pnpmBin, 'pnpm'), `#!/usr/bin/env bash
-set -euo pipefail
-if [ "\${1:-}" = m ]; then
-  if [ -n "\${PNPM_LIST_WARNING:-}" ]; then printf '%s\\n' "$PNPM_LIST_WARNING" >&2; fi
-  printf '%s\\n' "$PNPM_WORKSPACES_JSON"
-  exit 0
-fi
-if [ "\${1:-}" = --version ]; then
-  printf '%s\\n' "\${PNPM_VERSION:-11.0.0}"
-  exit 0
-fi
-printf '%s\\n' "$*" >> "$PNPM_LOG"
-calls=0
-if [ -f "$PNPM_CALLS" ]; then calls="$(cat "$PNPM_CALLS")"; fi
-calls=$((calls + 1))
-printf '%s' "$calls" > "$PNPM_CALLS"
-print_release_age_violation() {
-  printf '%s\\n' '✗ Lockfile failed supply-chain policy check (1 entries in 0.1s)'
-  printf '%s\\n' '[ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION] 1 lockfile entries failed verification:'
-  printf '%s\\n' '  undici@8.10.0 was published at 2026-08-03T15:06:33.000Z, within the minimumReleaseAge cutoff (2026-08-02T04:48:10.357Z)'
-}
-if [ "\${PNPM_FAIL_CALL:-0}" = "$calls" ]; then
-  if [ -n "\${PNPM_FAIL_RELEASE_AGE:-}" ]; then print_release_age_violation; fi
-  exit "\${PNPM_FAIL_CODE:-1}"
-fi
-if [ "\${PNPM_FAIL_RELEASE_AGE_CALL:-0}" = "$calls" ]; then
-  print_release_age_violation
-  exit 1
-fi
-if [ -n "\${PNPM_SLEEP_SECONDS:-}" ]; then sleep "$PNPM_SLEEP_SECONDS"; fi
-case " $* " in
-  *' --force '*)
-    if [ "\${PNPM_REPAIR_LINK:-0}" = 1 ]; then
-      mkdir -p "$(dirname "$PNPM_DEPENDENCY_LINK")"
-      rm -f "$PNPM_DEPENDENCY_LINK"
-      ln -s "$PNPM_DEPENDENCY" "$PNPM_DEPENDENCY_LINK"
-    fi
-    ;;
-esac
-`);
+    await writeFile(join(pnpmBin, 'pnpm'), fakePnpmScript());
     await execFileAsync('chmod', ['+x', join(pnpmBin, 'pnpm')]);
     const workspaces = [
         { name: 'fixture-root', path: root },
@@ -83,7 +46,10 @@ esac
         PNPM_DEPENDENCY: dependency,
         PNPM_DEPENDENCY_LINK: dependencyLink,
         PNPM_LOG: pnpmLog,
+        PNPM_NODE_MODULES: join(root, 'node_modules'),
+        PNPM_PENDING_BUILDS: '',
         PNPM_REPAIR_LINK: '0',
+        PNPM_REBUILD_BREAK_LINK: '0',
         PNPM_WORKSPACES_JSON: JSON.stringify(workspaces),
     };
     return {

package/dist/pnpm-install/runner.mjs

@@ -1,83 +1,99 @@
-import { scheduler } from 'node:timers/promises';
-import { persistentDependencyTreeIsCold, persistentMetadataFingerprint, persistentMetadataMatches, writePersistentMetadataStamp, } from './metadata.mjs';
-import { nativeBinariesMatchRuntime } from './native-health.mjs';
+import { persistentDependencyTreeIsCold, persistentMetadataFingerprintV4, persistentMetadataStatusV4, writePersistentMetadataStampV4, } from './metadata.mjs';
 import { runPnpm } from './exec.mjs';
-import { INSTALL_TERMINATION_FAILED } from './process.mjs';
-import { formatReleaseAgeFailure, isReleaseAgeViolation } from './release-age.mjs';
+import { nativeBinariesMatchRuntime } from './native-health.mjs';
+import { clearPendingDependencyBuilds, pendingBuildDelta, pendingBuilds, validDependencyBuildIds, } from './pending-builds.mjs';
+import { install, reconcileOrFail, withScriptPolicy } from './install-operations.mjs';
 import { baseInstallArgs, findWorkspaceLinkMismatches, logWorkspaceLinkMismatches, } from './support.mjs';
+import { persistentInstallTransition, persistentProvenanceDiagnostic } from './transition.mjs';
 // oxfmt-ignore
 const fail = (message) => { throw new Error(message); };
-async function install(args, options, label) {
-    for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
-        const attemptResult = await runPnpm(args, options);
-        if (attemptResult.code === 0)
-            return;
-        if (attemptResult.code === INSTALL_TERMINATION_FAILED)
-            fail(`${label} could not terminate safely`);
-        const combinedOutput = `${attemptResult.output}\n${attemptResult.errorOutput ?? ''}`;
-        if (isReleaseAgeViolation(combinedOutput))
-            fail(formatReleaseAgeFailure(label, combinedOutput));
-        if (attempt < options.maxAttempts) {
-            console.warn(`${label} failed (attempt ${attempt}/${options.maxAttempts}); retrying`);
-            await scheduler.wait(5000);
-        }
-    }
-    fail(`${label} failed after ${options.maxAttempts} attempt${options.maxAttempts === 1 ? '' : 's'}`);
-}
-function withScriptPolicy(args, installScripts) {
-    return installScripts ? args : [...args, '--ignore-scripts'];
-}
-async function reconcileAndFindMismatches(options, runCapture) {
-    const forced = ['install', '--frozen-lockfile', '--force', ...baseInstallArgs.slice(2)];
-    // oxfmt-ignore
-    await install([...forced, '--ignore-scripts', '--ignore-pnpmfile'], options, 'script-free reconciliation');
-    // oxfmt-ignore
-    await install(withScriptPolicy(forced, options.installScripts), options, 'strict persistent reconciliation');
-    return findWorkspaceLinkMismatches(runCapture);
-}
-async function reconcileOrFail(options, runCapture) {
-    const remaining = await reconcileAndFindMismatches(options, runCapture);
-    if (remaining.length > 0) {
-        logWorkspaceLinkMismatches(remaining);
-        fail('persistent reconciliation completed with invalid workspace links');
-    }
-}
 async function persistent(options) {
     if (options.ephemeralWorkspaces.trim())
         fail('ephemeral-workspaces is only valid for ephemeral runners');
     const runCapture = (args) => runPnpm(args, options, true);
-    const fingerprint = await persistentMetadataFingerprint(runCapture, options.installScripts);
-    const stamped = await persistentMetadataMatches(fingerprint);
+    const fingerprint = await persistentMetadataFingerprintV4(runCapture);
+    const provenance = await persistentMetadataStatusV4(fingerprint);
     const nativesMatch = await nativeBinariesMatchRuntime();
-    const provenanceOk = stamped && nativesMatch;
-    // An absent tree has nothing to repair, so one ordinary install below matches the
-    // reconciled end state. Check first: an install would otherwise make the tree non-cold.
+    const provisionalTransition = persistentInstallTransition(provenance, options.installScripts);
+    let transition = nativesMatch
+        ? provisionalTransition
+        : { action: 'reconcile', reason: 'native-health-mismatch' };
+    if (transition.action === 'upgrade-dependencies') {
+        const ids = await validDependencyBuildIds(transition.pendingDependencyBuilds);
+        if (!ids)
+            transition = { action: 'upgrade-scripts', reason: 'invalid-pending-dependency-builds' };
+        else
+            transition = { ...transition, pendingDependencyBuilds: ids };
+    }
+    const provenanceOk = provenance.kind === 'matching' && transition.action !== 'reconcile' && nativesMatch;
     const cold = !provenanceOk && (await persistentDependencyTreeIsCold());
     if (!provenanceOk && !cold) {
-        console.warn(stamped && !nativesMatch
+        const finalTransition = provenance.kind === 'absent'
+            ? { action: 'reconcile', reason: 'missing-stamp-populated-tree' }
+            : transition;
+        console.warn(persistentProvenanceDiagnostic(provenance, options.installScripts, nativesMatch, finalTransition));
+        console.warn(provenance.kind === 'matching' && !nativesMatch
             ? 'persistent optional native binaries do not match this runtime; reconciling'
             : 'persistent dependency metadata provenance is missing or changed; reconciling');
         await reconcileOrFail(options, runCapture);
-        await writePersistentMetadataStamp(fingerprint);
+        await writePersistentMetadataStampV4(fingerprint, options.installScripts, true, []);
         return 'persistent metadata reconciled';
     }
-    if (!stamped)
+    if (provenance.kind === 'absent')
         console.warn('persistent dependency tree is absent; installing cold');
-    await install(withScriptPolicy([...baseInstallArgs], options.installScripts), options, 'ordinary persistent install');
+    const pendingBefore = transition.action === 'ordinary' && !options.installScripts ? await pendingBuilds() : undefined;
+    await install(withScriptPolicy([...baseInstallArgs], transition.action.startsWith('upgrade-') ? false : options.installScripts), options, 'ordinary persistent install');
     const stale = await findWorkspaceLinkMismatches(runCapture);
     if (stale.length === 0) {
-        if (!stamped)
-            await writePersistentMetadataStamp(fingerprint);
-        return stamped ? 'persistent ordinary' : 'persistent cold';
+        if (transition.action.startsWith('upgrade-')) {
+            const pendingDependencyBuilds = transition.action === 'upgrade-dependencies'
+                ? transition.pendingDependencyBuilds
+                : undefined;
+            const rebuild = pendingDependencyBuilds === undefined
+                ? ['rebuild', '--pending', '--recursive']
+                : ['rebuild', '--recursive', '--', ...pendingDependencyBuilds];
+            await install(rebuild, options, 'pending scripts rebuild');
+            const rebuiltStale = await findWorkspaceLinkMismatches(runCapture);
+            if (rebuiltStale.length > 0) {
+                logWorkspaceLinkMismatches(rebuiltStale);
+                await reconcileOrFail(options, runCapture);
+                console.warn(persistentProvenanceDiagnostic(provenance, options.installScripts, nativesMatch, {
+                    action: 'reconcile',
+                    reason: 'workspace-links-stale-after-rebuild',
+                }));
+                await writePersistentMetadataStampV4(fingerprint, options.installScripts, true, []);
+                return 'persistent reconciled';
+            }
+            if (pendingDependencyBuilds !== undefined &&
+                !(await clearPendingDependencyBuilds(pendingDependencyBuilds)))
+                fail('dependency rebuild completed but pending build ledger could not be updated safely');
+        }
+        console.warn(persistentProvenanceDiagnostic(provenance, options.installScripts, nativesMatch, transition));
+        const pendingAfter = pendingBefore ? await pendingBuilds() : undefined;
+        const delta = pendingBefore && pendingAfter
+            ? await pendingBuildDelta(pendingBefore, pendingAfter)
+            : undefined;
+        const unsafePending = delta?.kind === 'unknown' || Boolean(delta?.workspaceIds.length);
+        const pendingDependencyBuilds = transition.action.startsWith('upgrade-') || unsafePending
+            ? []
+            : [
+                ...new Set([
+                    ...(provenance.kind === 'matching' ? provenance.pendingDependencyBuilds : []),
+                    ...(delta?.kind === 'known' ? delta.dependencyIds : []),
+                ]),
+            ].toSorted();
+        await writePersistentMetadataStampV4(fingerprint, options.installScripts, unsafePending, pendingDependencyBuilds);
+        return provenance.kind === 'absent' ? 'persistent cold' : 'persistent ordinary';
     }
     logWorkspaceLinkMismatches(stale);
+    console.warn(persistentProvenanceDiagnostic(provenance, options.installScripts, nativesMatch, {
+        action: 'reconcile',
+        reason: 'workspace-links-stale',
+    }));
     await reconcileOrFail(options, runCapture);
-    await writePersistentMetadataStamp(fingerprint);
+    await writePersistentMetadataStampV4(fingerprint, options.installScripts, true, []);
     return 'persistent reconciled';
 }
-// A path selector's `...` (dependency closure) suffix is silently ignored by pnpm unless the
-// path is brace-wrapped, e.g. `{./web}...` — `./web...` installs only `web` itself. Reject the
-// unbraced form outright rather than let it resolve to a smaller-than-intended scope.
 function isUnbracedPathClosureSelector(selector) {
     return /^\.{0,2}\//.test(selector) && selector.endsWith('...') && !selector.startsWith('{');
 }

package/dist/pnpm-install/transition.d.mts

@@ -0,0 +1,23 @@
+export type ProvenanceStatus = {
+    kind: 'absent';
+} | {
+    kind: 'changed';
+    components: string[];
+} | {
+    kind: 'matching';
+    lastInvocationInstallScripts: boolean;
+    pendingDependencyBuilds: string[];
+    scriptsEnabledInstallSucceeded: boolean;
+} | {
+    kind: 'unsafe';
+};
+export type PersistentInstallTransition = {
+    action: 'ordinary' | 'reconcile' | 'upgrade-scripts';
+    reason: string;
+} | {
+    action: 'upgrade-dependencies';
+    pendingDependencyBuilds: [string, ...string[]];
+    reason: string;
+};
+export declare function persistentInstallTransition(provenance: ProvenanceStatus, installScripts: boolean): PersistentInstallTransition;
+export declare function persistentProvenanceDiagnostic(provenance: ProvenanceStatus, installScripts: boolean, nativeBinariesMatchRuntime: boolean, transition: PersistentInstallTransition): string;

package/dist/pnpm-install/transition.mjs

@@ -0,0 +1,36 @@
+// The matching rows are deliberately explicit: a script-disabled invocation can never erase
+// evidence that this structural tree has already completed a scripts-enabled install.
+export function persistentInstallTransition(provenance, installScripts) {
+    if (provenance.kind === 'matching') {
+        if (installScripts && !provenance.scriptsEnabledInstallSucceeded)
+            return { action: 'upgrade-scripts', reason: 'pending-scripts-rebuild' };
+        const [firstPendingDependencyBuild, ...remainingPendingDependencyBuilds] = provenance.pendingDependencyBuilds;
+        if (installScripts && firstPendingDependencyBuild !== undefined)
+            return {
+                action: 'upgrade-dependencies',
+                pendingDependencyBuilds: [firstPendingDependencyBuild, ...remainingPendingDependencyBuilds],
+                reason: 'pending-dependency-rebuild',
+            };
+        return { action: 'ordinary', reason: 'matching-structural-provenance' };
+    }
+    if (provenance.kind === 'absent')
+        return { action: 'ordinary', reason: 'missing-stamp' };
+    return {
+        action: 'reconcile',
+        reason: provenance.kind === 'changed' ? 'structural-provenance-changed' : 'unsafe-stamp',
+    };
+}
+export function persistentProvenanceDiagnostic(provenance, installScripts, nativeBinariesMatchRuntime, transition) {
+    return JSON.stringify({
+        action: transition.action,
+        changedComponents: provenance.kind === 'changed' ? provenance.components : [],
+        event: 'pnpm-install-persistent-provenance',
+        installScripts,
+        scriptsEnabledInstallSucceeded: provenance.kind === 'matching' ? provenance.scriptsEnabledInstallSucceeded : false,
+        lastInvocationInstallScripts: provenance.kind === 'matching' ? provenance.lastInvocationInstallScripts : null,
+        pendingDependencyBuildCount: provenance.kind === 'matching' ? provenance.pendingDependencyBuilds.length : 0,
+        nativeBinariesMatchRuntime,
+        reason: transition.reason,
+        state: provenance.kind,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {