vouchington-tooling 0.1.8 → 0.2.0

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/dist/skill-discovery/index.d.mts

@@ -0,0 +1,12 @@
+export { readSkillManifest, type SkillManifest, type SkillManifestEntry } from './manifest.mts';
+export type LinkSkillOptions = {
+    name: string;
+    sourceRoot: string;
+    targetRoot: string;
+};
+export type LinkSkillResult = {
+    created: boolean;
+    path: string;
+    source: string;
+};
+export declare function linkSkill(options: LinkSkillOptions): Promise<LinkSkillResult>;