vouchington-tooling 0.19.2 → 0.21.0

package/README.md

@@ -326,19 +326,24 @@ policy out of this package.
 dependency declared by a non-fixture package manifest. Assert dependency membership or placement,
 or derive a configuration or documentation package spec from that manifest instead.
 
-`dependency-license-policy` keeps legal policy in the consumer. `collectPnpmLicenseReport` creates
-an isolated, script-free temporary workspace and store, expands pnpm's supported architectures to
-every `os`, `cpu`, and `libc` selector represented in the lockfile, drops every `engines` constraint
-from the audit copy of the lockfile, and validates the JSON report. Dropping `engines` keeps
-`pnpm fetch` from skipping optional packages that exclude the running Node.js; pnpm 12's `fetch`
-ignores `force`, so their licenses would otherwise report as Unknown.
+`dependency-license-policy` keeps legal policy in the consumer. `collectPnpmLicenseReport` returns
+a promise. It creates an isolated, script-free temporary workspace, expands pnpm's supported
+architectures to every `os`, `cpu`, and `libc` selector represented in the lockfile, drops every
+`engines` constraint from the audit copy of the lockfile, and validates the JSON report. Dropping
+`engines` keeps `pnpm fetch` from skipping optional packages that exclude the running Node.js;
+pnpm 12's `fetch` ignores `force`, so their licenses would otherwise report as Unknown.
+Packages are fetched into a dedicated owner-only store under the pnpm cache
+(`dependency-license-audit-store`) so a later audit reuses content-addressed packages instead of
+downloading every platform again, without writing those packages into the developer store.
 Pass explicit denied SPDX IDs and prefixes, exact aliases, and justified allowlist scopes to
 `evaluatePnpmLicenseReport`. Unknown, malformed, and custom SPDX references fail closed. Allowlist
 scopes are either intentionally global or an exact package-name set; the library returns structured
 violations and does not format CI-provider diagnostics.
-When present, the repository `.npmrc` is copied into the owner-private temporary directory so pnpm
-can authenticate to the same registries; normal cleanup removes the copy, and the caller remains
-responsible for terminating the process normally rather than abandoning temporary audit state.
+When present, the repository `.npmrc` is copied into the owner-private temporary workspace so pnpm
+can authenticate to the same registries. The workspace is removed when the audit finishes, when the
+process receives SIGINT, SIGTERM, or SIGHUP, and on the next audit if the previous process died
+first, including SIGKILL. Each workspace records its owner's PID so a later audit can delete
+directories whose owner is gone.
 
 `session-friction` is an opt-in capture and reporting library. Callers supply the session id,
 absolute log directory, host-independent observation, and journal loader; it does not inspect host

package/dist/cli/commands/gha-runtime-audit.mjs

@@ -17,6 +17,12 @@ export async function runGhaRuntimeAudit(parsed, execute = defaultGhApiExecutor(
         repository,
         workflows: parsed.workflows,
         ...(parsed.branch === undefined ? {} : { branch: parsed.branch }),
+        ...(parsed.medianFloorSeconds === undefined
+            ? {}
+            : { medianFloorSeconds: parsed.medianFloorSeconds }),
+        ...(parsed.medianThresholdSeconds === undefined
+            ? {}
+            : { medianThresholdSeconds: parsed.medianThresholdSeconds }),
     });
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     return 0;

package/dist/cli/commands/retrospective-facts.mjs

@@ -6,24 +6,34 @@ export async function runRetrospectiveFactsCommand(args) {
             args,
             strict: true,
             options: {
-                pr: { type: 'string' },
+                pr: { type: 'string', multiple: true },
                 branch: { type: 'string' },
                 'no-pr': { type: 'boolean' },
                 repo: { type: 'string' },
                 raw: { type: 'boolean' },
             },
         });
-        const options = {
-            ...(values.pr === undefined ? {} : { pr: values.pr }),
+        const prs = values.pr ?? [];
+        const shared = {
             ...(values.branch === undefined ? {} : { branch: values.branch }),
             ...(values['no-pr'] === undefined ? {} : { noPr: values['no-pr'] }),
             ...(values.repo === undefined ? {} : { repo: values.repo }),
             ...(values.raw ? { raw: true } : {}),
         };
-        process.stdout.write(await runRetrospectiveFacts({
-            ...options,
-            onWarning: (message) => process.stderr.write(`${message}\n`),
-        }));
+        const selectors = prs.length === 0 ? [undefined] : prs;
+        const blocks = [];
+        for (const pr of selectors) {
+            blocks.push(await runRetrospectiveFacts({
+                ...shared,
+                ...(pr === undefined ? {} : { pr }),
+                onWarning: (message) => process.stderr.write(`${message}\n`),
+            }));
+        }
+        if (blocks.length === 1) {
+            process.stdout.write(blocks[0]);
+            return 0;
+        }
+        process.stdout.write(`${joinFactBlocks(blocks)}\n`);
         return 0;
     }
     catch (error) {
@@ -31,3 +41,6 @@ export async function runRetrospectiveFactsCommand(args) {
         return 2;
     }
 }
+function joinFactBlocks(blocks) {
+    return blocks.map((block) => block.replace(/\n+$/, '')).join('\n\n');
+}

package/dist/cli/index.mjs

@@ -28,7 +28,7 @@ import { runAstGrepPackCommand } from './commands/ast-grep-pack.mjs';
 import { runGhaWorkspacePolicy } from './commands/gha-workspace-policy.mjs';
 import { parseCli } from './parse.mjs';
 import { packageScriptPath } from './script-path.mjs';
-import { printUsage } from './usage.mjs';
+import { commandUsage, printUsage } from './usage.mjs';
 const SCRIPT_PATHS = {
     'gha-output': { command: 'bash', path: 'scripts/gha/write-github-multiline-output.sh' },
     'gha-needs-results': { command: 'bash', path: 'scripts/gha/check-needs-results.sh' },
@@ -79,6 +79,9 @@ export function runCli(argv = process.argv) {
         case 'help':
             printUsage();
             return 0;
+        case 'command-help':
+            process.stdout.write(commandUsage(parsed.command));
+            return 0;
         case 'version':
             process.stdout.write(`${readInstalledVersion()}\n`);
             return 0;

package/dist/cli/parse-gha-runtime-audit.d.mts

@@ -4,6 +4,8 @@ export type ParsedGhaRuntimeAudit = {
     repository?: string;
     branch?: string;
     workflows: RuntimeAuditWorkflowFilter[];
+    medianFloorSeconds?: number;
+    medianThresholdSeconds?: number;
 };
 export declare function parseGhaRuntimeAudit(args: readonly string[]): ParsedGhaRuntimeAudit | {
     kind: 'help';

package/dist/cli/parse-gha-runtime-audit.mjs

@@ -2,6 +2,8 @@ import { parseWorkflowNameMatch, } from '../gha-runtime-audit/scope.mjs';
 export function parseGhaRuntimeAudit(args) {
     let repository;
     let branch;
+    let medianFloorSeconds;
+    let medianThresholdSeconds;
     const workflows = [];
     for (let index = 0; index < args.length; index += 1) {
         const flag = args[index];
@@ -10,7 +12,9 @@ export function parseGhaRuntimeAudit(args) {
         if (flag === '--repository' ||
             flag === '--pr-workflow' ||
             flag === '--push-workflow' ||
-            flag === '--branch') {
+            flag === '--branch' ||
+            flag === '--median-threshold-floor' ||
+            flag === '--median-threshold-ceiling') {
             const value = args[index + 1];
             if (value === undefined)
                 return { kind: 'error', message: `${flag} requires a value` };
@@ -19,6 +23,15 @@ export function parseGhaRuntimeAudit(args) {
                 repository = value;
             else if (flag === '--branch')
                 branch = value;
+            else if (flag === '--median-threshold-floor' || flag === '--median-threshold-ceiling') {
+                const seconds = parsePositiveSeconds(flag, value);
+                if (typeof seconds !== 'number')
+                    return seconds;
+                if (flag === '--median-threshold-floor')
+                    medianFloorSeconds = seconds;
+                else
+                    medianThresholdSeconds = seconds;
+            }
             else {
                 workflows.push({
                     name: parseWorkflowNameMatch(value),
@@ -35,10 +48,29 @@ export function parseGhaRuntimeAudit(args) {
             message: 'gha-runtime-audit requires --pr-workflow or --push-workflow',
         };
     }
+    const ceiling = medianThresholdSeconds ?? 360;
+    if (medianFloorSeconds !== undefined && medianFloorSeconds >= ceiling) {
+        return {
+            kind: 'error',
+            message: '--median-threshold-floor must be below the median ceiling',
+        };
+    }
     return {
         kind: 'gha-runtime-audit',
         workflows,
         ...(repository === undefined ? {} : { repository }),
         ...(branch === undefined ? {} : { branch }),
+        ...(medianFloorSeconds === undefined ? {} : { medianFloorSeconds }),
+        ...(medianThresholdSeconds === undefined ? {} : { medianThresholdSeconds }),
     };
 }
+function parsePositiveSeconds(flag, value) {
+    if (!/^[1-9]\d*$/.test(value)) {
+        return { kind: 'error', message: `${flag} requires a positive integer` };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { kind: 'error', message: `${flag} requires a positive integer` };
+    }
+    return parsed;
+}

package/dist/cli/parse.d.mts

@@ -2,6 +2,9 @@ import { type ParsedGhaArtifactsCleanup } from './parse-gha-artifacts-cleanup.mt
 import { type ParsedGhaRuntimeAudit } from './parse-gha-runtime-audit.mts';
 export type ParsedCli = {
     kind: 'help';
+} | {
+    kind: 'command-help';
+    command: string;
 } | {
     kind: 'version';
 } | {
@@ -85,3 +88,7 @@ export type ParsedCli = {
 } | 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' | 'harness-admission-lane' | 'harness-assert-gates';
 export declare function parseCli(argv: readonly string[]): ParsedCli;
+export declare function parseCommandHelp(command: string | undefined, rest: readonly string[]): {
+    kind: 'command-help';
+    command: string;
+} | undefined;

package/dist/cli/parse.mjs

@@ -1,5 +1,6 @@
 import { parseGhaArtifactsCleanup, } from './parse-gha-artifacts-cleanup.mjs';
 import { parseGhaRuntimeAudit } from './parse-gha-runtime-audit.mjs';
+import { commandNames } from './usage.mjs';
 import { parseAstGrepExamples, parseAstGrepPack, parseGhaWorkspacePolicy, parseGitleaksDirectoryScan, parseHttpOrigin, parseLinkSkill, parseRequireUpToDate, parseRunnerPortPolicy, } from './parse-options.mjs';
 const SCRIPT_COMMANDS = new Set([
     'gha-output',
@@ -31,6 +32,9 @@ export function parseCli(argv) {
     if (args[0] === '--version' || args[0] === '-v')
         return { kind: 'version' };
     const [command, ...rest] = args;
+    const help = parseCommandHelp(command, rest);
+    if (help)
+        return help;
     if (command === 'runner-port-policy')
         return parseRunnerPortPolicy(rest);
     if (command === 'with-host-lock')
@@ -82,3 +86,14 @@ export function parseCli(argv) {
     }
     return { kind: 'error', message: `unknown command: ${command}` };
 }
+export function parseCommandHelp(command, rest) {
+    if (command === undefined || !commandNames().includes(command) || !helpBeforeSeparator(rest)) {
+        return undefined;
+    }
+    return { kind: 'command-help', command };
+}
+function helpBeforeSeparator(args) {
+    const separator = args.indexOf('--');
+    const options = separator === -1 ? args : args.slice(0, separator);
+    return options.includes('--help') || options.includes('-h');
+}

package/dist/cli/usage.d.mts

@@ -1,2 +1,4 @@
-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  agent-harness-config          Apply classifier-auto + sandbox keys to agent harnesses\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\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  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\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  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\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  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\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\nagent-harness-config dump\nagent-harness-config check|apply [--global] [--repo PATH]... [--harness claude|codex|grok|cursor]...\n  [--home PATH]\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\nrequire-up-to-date --remote <name> --branch <name>\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\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]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-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>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\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>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\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  agent-harness-config          Apply classifier-auto + sandbox keys to agent harnesses\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\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  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\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  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\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  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\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\nagent-harness-config dump\nagent-harness-config check|apply [--global] [--repo PATH]... [--harness claude|codex|grok|cursor]...\n  [--home PATH]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\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]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-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>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\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>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;
+export declare function commandNames(usage?: string): string[];
+export declare function commandUsage(command: string, usage?: string): string;

package/dist/cli/usage.mjs

@@ -71,6 +71,8 @@ agent-harness-config check|apply [--global] [--repo PATH]... [--harness claude|c
 gha-runtime-audit
   [--repository owner/name]   Default GITHUB_REPOSITORY
   [--branch main]
+  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling
+  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this
   --pr-workflow <name|/regex/>     Repeatable
   --push-workflow <name|/regex/>   Repeatable
 
@@ -85,7 +87,7 @@ gha-needs-results [label]
 download-with-diagnostics <url> <destination> [-- curl-args...]
 download-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>
 host-pressure-diagnostics
-allocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]
+allocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]
 diagnose-port-collision [--ports "2200 2216"] [--output-dir PATH]
 prepare-trivy-db
 gha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]
@@ -124,3 +126,44 @@ agent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);
 }
+export function commandNames(usage = USAGE) {
+    const names = [];
+    let inCommands = false;
+    for (const line of usage.split('\n')) {
+        if (line === 'Commands:') {
+            inCommands = true;
+            continue;
+        }
+        if (!inCommands)
+            continue;
+        if (line === '')
+            break;
+        const name = line.trim().split(/\s+/)[0];
+        if (name)
+            names.push(name);
+    }
+    return names;
+}
+export function commandUsage(command, usage = USAGE) {
+    const names = new Set(commandNames(usage));
+    if (!names.has(command))
+        throw new Error(`unknown command: ${command}`);
+    const lines = usage.split('\n');
+    const detailStart = lines.indexOf('Options:');
+    const selected = [];
+    let capturing = false;
+    for (const line of lines.slice(detailStart + 1)) {
+        if (line === '') {
+            if (capturing)
+                break;
+            continue;
+        }
+        if (!line.startsWith(' '))
+            capturing = line.trim().split(/\s+/)[0] === command;
+        if (capturing)
+            selected.push(line);
+    }
+    if (selected.length === 0)
+        throw new Error(`no usage for ${command}`);
+    return `${selected.join('\n')}\n`;
+}

package/dist/dependency-license-policy/audit-directory.d.mts

@@ -0,0 +1,28 @@
+export declare const LICENSE_AUDIT_DIRECTORY_PREFIX = "dependency-license-audit-";
+export interface LicenseAuditReclaimOptions {
+    readonly graceMs?: number;
+    readonly isOwnerAlive?: (pid: number, directoryMtimeMs: number) => boolean;
+    readonly now?: number;
+}
+export interface LicenseAuditWorkspaceOptions extends LicenseAuditReclaimOptions {
+    readonly directory?: string;
+    readonly pid?: number;
+}
+interface OwnerAliveDependencies {
+    readonly isProcessAlive?: (pid: number) => boolean;
+    readonly readProcessStartMs?: (pid: number) => number | undefined;
+}
+/** Parses `ps -o lstart=` output. Exported for tests of unparseable dates. */
+export declare function parseProcessStart(stdout: string): number | undefined;
+export declare function readProcessStartMs(pid: number): number | undefined;
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * A directory still belongs to its creator when that PID is alive and the process started
+ * before the directory. A recycled PID belongs to a newer process and is not the owner.
+ */
+export declare function isAuditOwnerAlive(pid: number, directoryMtimeMs: number, dependencies?: OwnerAliveDependencies): boolean;
+export declare function writeAuditPid(directory: string, pid?: number): void;
+export declare function removeAuditDirectory(directory: string): void;
+/** Deletes leftover audit directories whose owner process is gone, including after SIGKILL. */
+export declare function reclaimStaleLicenseAuditDirectories(directory: string, options?: LicenseAuditReclaimOptions): void;
+export {};

package/dist/dependency-license-policy/audit-directory.mjs

@@ -0,0 +1,115 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, lstatSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+export const LICENSE_AUDIT_DIRECTORY_PREFIX = 'dependency-license-audit-';
+const LICENSE_AUDIT_PID_FILE = 'audit.pid';
+const STALE_AUDIT_GRACE_MS = 60_000;
+const OWNER_START_SLACK_MS = 1_000;
+const MAX_PID = 2_147_483_647;
+function hasCode(error, code) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === code);
+}
+/** Parses `ps -o lstart=` output. Exported for tests of unparseable dates. */
+export function parseProcessStart(stdout) {
+    const parsed = Date.parse(stdout.trim());
+    if (Number.isNaN(parsed))
+        return undefined;
+    return parsed;
+}
+export function readProcessStartMs(pid) {
+    const result = spawnSync('ps', ['-p', String(pid), '-o', 'lstart='], { encoding: 'utf8' });
+    if (result.status !== 0)
+        return undefined;
+    return parseProcessStart(result.stdout);
+}
+export function isProcessAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0 || pid > MAX_PID)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !hasCode(error, 'ESRCH');
+    }
+}
+/**
+ * A directory still belongs to its creator when that PID is alive and the process started
+ * before the directory. A recycled PID belongs to a newer process and is not the owner.
+ */
+export function isAuditOwnerAlive(pid, directoryMtimeMs, dependencies = {}) {
+    if (!(dependencies.isProcessAlive ?? isProcessAlive)(pid))
+        return false;
+    const started = (dependencies.readProcessStartMs ?? readProcessStartMs)(pid);
+    if (started === undefined)
+        return true;
+    return started <= directoryMtimeMs + OWNER_START_SLACK_MS;
+}
+export function writeAuditPid(directory, pid = process.pid) {
+    const path = join(directory, LICENSE_AUDIT_PID_FILE);
+    writeFileSync(path, `${String(pid)}\n`, { encoding: 'utf8', mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+function readAuditPid(directory) {
+    try {
+        const text = readFileSync(join(directory, LICENSE_AUDIT_PID_FILE), 'utf8').trim();
+        if (!/^[1-9]\d*$/.test(text))
+            return undefined;
+        const pid = Number.parseInt(text, 10);
+        return Number.isSafeInteger(pid) && pid <= MAX_PID ? pid : undefined;
+    }
+    catch (error) {
+        if (hasCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+}
+export function removeAuditDirectory(directory) {
+    const stat = lstatSync(directory, { throwIfNoEntry: false });
+    if (!stat)
+        return;
+    if (stat.isSymbolicLink()) {
+        unlinkSync(directory);
+        return;
+    }
+    if (!stat.isDirectory())
+        return;
+    rmSync(directory, { force: true, recursive: true });
+}
+function reclaimNames(directory) {
+    try {
+        return readdirSync(directory, { encoding: 'utf8' });
+    }
+    catch (error) {
+        if (hasCode(error, 'ENOENT'))
+            return [];
+        throw error;
+    }
+}
+function shouldRemoveAuditDirectory(directory, mtimeMs, now, graceMs, isOwnerAlive) {
+    const pid = readAuditPid(directory);
+    if (pid === undefined)
+        return now - mtimeMs >= graceMs;
+    return !isOwnerAlive(pid, mtimeMs);
+}
+/** Deletes leftover audit directories whose owner process is gone, including after SIGKILL. */
+export function reclaimStaleLicenseAuditDirectories(directory, options = {}) {
+    const now = options.now ?? Date.now();
+    const graceMs = options.graceMs ?? STALE_AUDIT_GRACE_MS;
+    const isOwnerAlive = options.isOwnerAlive ?? isAuditOwnerAlive;
+    for (const name of reclaimNames(directory)) {
+        if (!name.startsWith(LICENSE_AUDIT_DIRECTORY_PREFIX))
+            continue;
+        const path = join(directory, name);
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink()) {
+            unlinkSync(path);
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        if (shouldRemoveAuditDirectory(path, stat.mtimeMs, now, graceMs, isOwnerAlive)) {
+            rmSync(path, { force: true, recursive: true });
+        }
+    }
+}

package/dist/dependency-license-policy/audit-signals.d.mts

@@ -0,0 +1,12 @@
+type SignalListener = () => void;
+export interface AuditSignalDependencies {
+    readonly raiseSignal?: (signal: NodeJS.Signals) => void;
+    readonly subscribe?: (signal: NodeJS.Signals, listener: SignalListener) => void;
+    readonly unsubscribe?: (signal: NodeJS.Signals, listener: SignalListener) => void;
+}
+/**
+ * Runs an audit while SIGINT, SIGTERM, and SIGHUP abort it, remove its workspace, and are raised
+ * again so the process still exits from that signal.
+ */
+export declare function withAuditSignalCleanup<T>(cleanup: () => void, run: (signal: AbortSignal) => Promise<T>, dependencies?: AuditSignalDependencies): Promise<T>;
+export {};

package/dist/dependency-license-policy/audit-signals.mjs

@@ -0,0 +1,44 @@
+const AUDIT_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/**
+ * Runs an audit while SIGINT, SIGTERM, and SIGHUP abort it, remove its workspace, and are raised
+ * again so the process still exits from that signal.
+ */
+export async function withAuditSignalCleanup(cleanup, run, dependencies = {}) {
+    const controller = new AbortController();
+    let raised;
+    const handlers = AUDIT_SIGNALS.map((signal) => {
+        const listener = () => {
+            if (raised !== undefined)
+                return;
+            raised = signal;
+            controller.abort(signal);
+        };
+        if (dependencies.subscribe)
+            dependencies.subscribe(signal, listener);
+        else
+            process.on(signal, listener);
+        return { listener, signal };
+    });
+    try {
+        return await run(controller.signal);
+    }
+    finally {
+        for (const { listener, signal } of handlers) {
+            if (dependencies.unsubscribe)
+                dependencies.unsubscribe(signal, listener);
+            else
+                process.removeListener(signal, listener);
+        }
+        try {
+            cleanup();
+        }
+        finally {
+            if (raised !== undefined) {
+                if (dependencies.raiseSignal)
+                    dependencies.raiseSignal(raised);
+                else
+                    process.kill(process.pid, raised);
+            }
+        }
+    }
+}

package/dist/dependency-license-policy/audit-store.d.mts

@@ -0,0 +1,12 @@
+export interface DirectoryIdentity {
+    readonly isDirectory: () => boolean;
+    readonly isSymbolicLink: () => boolean;
+    readonly mode: number;
+    readonly uid: number;
+}
+/** pnpm's cache directory. The audit store stays beside it so it is not the developer store. */
+export declare function pnpmCacheDirectory(env?: NodeJS.ProcessEnv, home?: string, hostPlatform?: NodeJS.Platform): string;
+export declare function licenseAuditStoreDirectory(env?: NodeJS.ProcessEnv, home?: string, hostPlatform?: NodeJS.Platform): string;
+export declare function assertOwnedDirectory(stat: DirectoryIdentity, uid: number | undefined, directory: string): void;
+/** Creates the dedicated content-addressed store used by repeat license audits. */
+export declare function ensurePrivateLicenseAuditStore(directory: string): void;

package/dist/dependency-license-policy/audit-store.mjs

@@ -0,0 +1,32 @@
+import { chmodSync, lstatSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const STORE_DIRECTORY_NAME = 'dependency-license-audit-store';
+/** pnpm's cache directory. The audit store stays beside it so it is not the developer store. */
+export function pnpmCacheDirectory(env = process.env, home = homedir(), hostPlatform = process.platform) {
+    if (hostPlatform === 'darwin')
+        return join(home, 'Library', 'Caches', 'pnpm');
+    if (hostPlatform === 'win32') {
+        return join(env.LOCALAPPDATA ?? join(home, 'AppData', 'Local'), 'pnpm-cache');
+    }
+    return join(env.XDG_CACHE_HOME ?? join(home, '.cache'), 'pnpm');
+}
+export function licenseAuditStoreDirectory(env = process.env, home = homedir(), hostPlatform = process.platform) {
+    return join(pnpmCacheDirectory(env, home, hostPlatform), STORE_DIRECTORY_NAME);
+}
+export function assertOwnedDirectory(stat, uid, directory) {
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`dependency license audit store is not a real directory: ${directory}`);
+    }
+    if (uid !== undefined && stat.uid !== uid) {
+        throw new Error(`dependency license audit store is not owned by the current user: ${directory}`);
+    }
+}
+/** Creates the dedicated content-addressed store used by repeat license audits. */
+export function ensurePrivateLicenseAuditStore(directory) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(directory);
+    assertOwnedDirectory(stat, process.getuid?.(), directory);
+    if ((stat.mode & 0o077) !== 0)
+        chmodSync(directory, 0o700);
+}

package/dist/dependency-license-policy/collect.d.mts

@@ -1,9 +1,11 @@
 import type { PnpmExecutor, PnpmLicenseReport } from './types.mts';
 import { type PnpmLicenseAuditWorkspace } from './workspace.mts';
 export interface CollectPnpmLicenseReportOptions {
+    readonly ensureStore?: (directory: string) => void;
     readonly execute?: PnpmExecutor;
     readonly prepareWorkspace?: (repoRoot: string, lockfileSource: string, workspaceSource: string) => PnpmLicenseAuditWorkspace;
     readonly readFile?: (path: string, encoding: 'utf8') => string;
+    readonly storeDir?: string;
 }
 /** Collects licenses for every platform represented in a pnpm lockfile. */
-export declare function collectPnpmLicenseReport(repoRoot: string, options?: CollectPnpmLicenseReportOptions): PnpmLicenseReport;
+export declare function collectPnpmLicenseReport(repoRoot: string, options?: CollectPnpmLicenseReportOptions): Promise<PnpmLicenseReport>;