vouchington-tooling 0.1.8 → 0.2.0

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
@@ -190,8 +199,16 @@ process-group probe and bounded-drain semantics outside a browser session.
 
 ## Workflow skills outside plugins
 
-The package ships the canonical Vouchington workflow skill tree at
-`skills/<skill>/SKILL.md`. This stable installed path supports agents that do not
-load Claude or Codex plugins. The Claude and Codex plugin manifests continue to reference the same
-canonical source tree under `plugins/vouchington-workflow/skills`; package build materializes that tree
-without hand-copying skill content.
+The package ships a flat union of canonical workflow, testing, and database skills at
+`skills/<skill>/SKILL.md`. This stable installed path supports agents that do not load Claude or
+Codex plugins. The package build materializes plugin source trees without hand-copying skill content
+and writes sorted schema-v1 provenance to `skills/manifest.json`.
+Each manifest entry may declare its ordered `prerequisites`; ordinary Markdown links remain
+cross-references and never cause additional skills to be linked.
+
+Use `readSkillManifest(skillsRoot)` to discover installed skills or
+`linkSkill({ name, sourceRoot, targetRoot })` to link one into an explicit consumer directory. The
+CLI equivalent is `vouchington link-skill <name> --source-root <skills-dir> --target-root <dir>`.
+It rejects unknown names, paths outside either root, and existing non-matching destinations.
+`targetRoot` must already exist as a physical directory path: symlinked target roots or ancestors are
+rejected.

package/dist/cli/commands/link-skill.d.mts

@@ -0,0 +1,5 @@
+export declare function runLinkSkill(options: {
+    name: string;
+    sourceRoot: string;
+    targetRoot: string;
+}): Promise<number>;

package/dist/cli/commands/link-skill.mjs

@@ -0,0 +1,6 @@
+import { linkSkill } from '../../skill-discovery/index.mjs';
+export async function runLinkSkill(options) {
+    const result = await linkSkill(options);
+    process.stdout.write(`${result.created ? 'linked' : 'already-linked'} ${result.path}\n`);
+    return 0;
+}

package/dist/cli/index.mjs

@@ -15,6 +15,7 @@ import { runStageReviewPayloadCommand } from './commands/stage-review-payload.mj
 import { runSwiftSemanticEqualCommand } from './commands/swift-semantic-equal.mjs';
 import { runVitestBlobManifestCommand } from './commands/vitest-blob-manifest.mjs';
 import { runRetrospectiveTranscriptCommand } from './commands/retrospective-transcript.mjs';
+import { runLinkSkill } from './commands/link-skill.mjs';
 import { runWithHostLock } from './commands/with-host-lock.mjs';
 import { parseCli } from './parse.mjs';
 import { packageScriptPath } from './script-path.mjs';
@@ -99,6 +100,8 @@ export function runCli(argv = process.argv) {
             return runGhaArtifactsCleanup(parsed);
         case 'retrospective-transcript':
             return runRetrospectiveTranscriptCommand(parsed.args);
+        case 'link-skill':
+            return runLinkSkill(parsed);
     }
 }
 function readInstalledVersion() {

package/dist/cli/parse.d.mts

@@ -43,6 +43,11 @@ export type ParsedCli = {
 } | {
     kind: 'retrospective-transcript';
     args: string[];
+} | {
+    kind: 'link-skill';
+    name: string;
+    sourceRoot: string;
+    targetRoot: string;
 } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup;
 export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention';
 export declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -50,6 +50,8 @@ export function parseCli(argv) {
         return parseHttpOrigin(rest);
     if (command === 'retrospective-transcript')
         return { kind: 'retrospective-transcript', args: rest };
+    if (command === 'link-skill')
+        return parseLinkSkill(rest);
     if (command === 'gha-artifacts-cleanup')
         return parseGhaArtifactsCleanup(rest);
     if (command !== undefined && SCRIPT_COMMANDS.has(command)) {
@@ -57,6 +59,29 @@ export function parseCli(argv) {
     }
     return { kind: 'error', message: `unknown command: ${command}` };
 }
+function parseLinkSkill(args) {
+    const [name, ...flags] = args;
+    if (name === undefined || name.startsWith('-'))
+        return { kind: 'error', message: 'link-skill requires a skill name' };
+    let sourceRoot;
+    let targetRoot;
+    for (let index = 0; index < flags.length; index += 1) {
+        const flag = flags[index];
+        const value = flags[index + 1];
+        if (flag !== '--source-root' && flag !== '--target-root')
+            return { kind: 'error', message: `unknown link-skill option: ${flag}` };
+        if (value === undefined)
+            return { kind: 'error', message: `${flag} requires a path` };
+        if (flag === '--source-root')
+            sourceRoot = value;
+        else
+            targetRoot = value;
+        index += 1;
+    }
+    if (sourceRoot === undefined || targetRoot === undefined)
+        return { kind: 'error', message: 'link-skill requires --source-root and --target-root' };
+    return { kind: 'link-skill', name, sourceRoot, targetRoot };
+}
 function parseRunnerPortPolicy(args) {
     let file;
     let reserved;

package/dist/cli/usage.d.mts

@@ -1,2 +1,2 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -32,6 +32,7 @@ Commands:
   post-review                   Post one COMMENT review from a staged payload file
   stage-review-payload          Validate a review payload file into a staging directory
   retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts
+  link-skill                    Link one packaged skill into an explicit consumer directory
 
 Options:
   -h, --help       Show this help
@@ -86,6 +87,7 @@ swift-semantic-equal <base> <head> <file.swift>
 post-review
 stage-review-payload optional|required <source> <destination>
 retrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]
+link-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

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

@@ -1,3 +1,5 @@
+export { linkSkill, readSkillManifest } from './skill-discovery/index.mts';
+export type { LinkSkillOptions, LinkSkillResult, SkillManifest, SkillManifestEntry, } from './skill-discovery/index.mts';
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mts';
 export type { ResolveOptions, TokenTotals, TranscriptFacts, } from './retrospective-transcript/index.mts';
 export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/index.mts';

package/dist/index.mjs

@@ -1,4 +1,5 @@
 /* eslint-disable max-lines -- package entry point enumerates the supported public API. */
+export { linkSkill, readSkillManifest } from './skill-discovery/index.mjs';
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mjs';
 export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/index.mjs';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mjs';

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 {};