vouchington-tooling 0.78.2 → 0.80.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/README.md +58 -3
  2. package/dist/agent-blackboard/feedback-journal-sandbox.d.mts +1 -1
  3. package/dist/agent-blackboard/feedback-journal-sandbox.mjs +11 -2
  4. package/dist/audit-journal/audit-block.d.mts +8 -2
  5. package/dist/audit-journal/audit-block.mjs +35 -5
  6. package/dist/audit-journal/ci-failures.mjs +11 -1
  7. package/dist/cli/index.mjs +3 -0
  8. package/dist/cli/parse-forwarded-commands.d.mts +1 -1
  9. package/dist/cli/parse-forwarded-commands.mjs +1 -0
  10. package/dist/cli/parse.d.mts +3 -0
  11. package/dist/cli/usage-text.d.mts +1 -1
  12. package/dist/cli/usage-text.mjs +2 -0
  13. package/dist/mcp-server/dispatch.d.mts +3 -0
  14. package/dist/mcp-server/dispatch.mjs +7 -1
  15. package/dist/mcp-server/install-info.d.mts +11 -0
  16. package/dist/mcp-server/install-info.mjs +45 -0
  17. package/dist/mcp-server/retrospective-facts-input.d.mts +2 -0
  18. package/dist/mcp-server/retrospective-facts-input.mjs +8 -2
  19. package/dist/mcp-server/retrospective-input.mjs +6 -2
  20. package/dist/mcp-server/run.mjs +2 -0
  21. package/dist/retrospective-transcript/codex-segment.d.mts +7 -0
  22. package/dist/retrospective-transcript/codex-segment.mjs +14 -10
  23. package/dist/retrospective-transcript/index.mjs +16 -11
  24. package/dist/runner-policy/cli.d.mts +6 -0
  25. package/dist/runner-policy/cli.mjs +45 -0
  26. package/dist/runner-policy/config.d.mts +3 -0
  27. package/dist/runner-policy/config.mjs +97 -0
  28. package/dist/runner-policy/discover.d.mts +9 -0
  29. package/dist/runner-policy/discover.mjs +34 -0
  30. package/dist/runner-policy/evaluate.d.mts +7 -0
  31. package/dist/runner-policy/evaluate.mjs +61 -0
  32. package/dist/runner-policy/index.d.mts +6 -0
  33. package/dist/runner-policy/index.mjs +4 -0
  34. package/dist/runner-policy/matrix.d.mts +13 -0
  35. package/dist/runner-policy/matrix.mjs +45 -0
  36. package/dist/runner-policy/rules.d.mts +6 -0
  37. package/dist/runner-policy/rules.mjs +87 -0
  38. package/dist/runner-policy/types.d.mts +38 -0
  39. package/dist/runner-policy/types.mjs +1 -0
  40. package/dist/runner-policy/workflow.d.mts +24 -0
  41. package/dist/runner-policy/workflow.mjs +37 -0
  42. package/dist/sql-ast/no-mistakes-peer.d.mts +54 -49
  43. package/package.json +7 -2
  44. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
package/README.md CHANGED
@@ -86,6 +86,7 @@ vouchington harness-assert-gates HARNESS_DISPATCH_ENABLED HARNESS_SHEPHERD_ENABL
86
86
  echo '[{"login":"octocat","type":"User"}]' | vouchington gha-collaborator-trust owner/repo --allow-bot github-actions[bot]
87
87
  vouchington nuget-central-version trusted.props candidate.props metadata.json out.props
88
88
  vouchington verify-workflow-secrets --repo owner/name --inventory .github/workflows/workflow-secrets-inventory.mts
89
+ vouchington runner-policy --config .github/runner-policy.json --root .github/workflows
89
90
  vouchington tmux up --config tmux.json --no-attach
90
91
  vouchington tmux name my-topic
91
92
  vouchington tmux read-title
@@ -704,6 +705,7 @@ import { runAstGrepExamples } from 'vouchington-tooling/ast-grep-examples'
704
705
  import { astGrepPackPaths } from 'vouchington-tooling/ast-grep-pack'
705
706
  import { validateNugetUpdate } from 'vouchington-tooling/nuget-central-version'
706
707
  import { runVerifyWorkflowSecretsCli } from 'vouchington-tooling/workflow-secrets-drift'
708
+ import { evaluateRunnerPolicy } from 'vouchington-tooling/runner-policy'
707
709
  import { launchSession, loadTmuxConfig } from 'vouchington-tooling/tmux'
708
710
  import { runDeadCodeGate } from 'vouchington-tooling/dead-code'
709
711
  import { normalizeSwiftSource } from 'vouchington-tooling/swift-semantic-equal'
@@ -1163,9 +1165,14 @@ await composeRetrospective({ ...input, journal: { journalLoader } })
1163
1165
  `journalLoader` is a `JournalLoader`; `JournalLoader`, `JournalLoadResult`,
1164
1166
  `JournalEntry`, and `JournalAuditOptions` are exported as types from
1165
1167
  `vouchington-tooling/agent-blackboard`. The `## CI Failures` block grammar has three status
1166
- lines (`failures observed`, `none observed`, `unavailable (<reason>)`).
1167
- Journal-only sandbox and permission entries are journal Markdown entries that hold exactly one
1168
- block, escaped and length-bounded like CI failures, and other entries are ignored:
1168
+ lines (`failures observed`, `none observed`, `unavailable (<reason>)`). An entry may hold several
1169
+ CI-failure blocks, and each top-level block line (`` - ` ``) starts one. A block that names
1170
+ `recurring` or `one-off` with `GitHub Actions` but does not match the grammar is reported as one
1171
+ `unparsed` note counting such blocks, never silently dropped.
1172
+ Journal-only sandbox and permission entries are journal Markdown entries that hold one or more
1173
+ blocks, split the same way, escaped and length-bounded like CI failures. A block that names
1174
+ `sandbox-escalation`, `sandbox-failure`, or `ambiguous-failure` but does not match the grammar is
1175
+ reported as an `unparsed` note; other text is ignored:
1169
1176
 
1170
1177
  ```markdown
1171
1178
  - `sandbox-escalation` — git push — network write blocked
@@ -1439,3 +1446,51 @@ const { result, error } = await withPostgresQueryFailureForTest(
1439
1446
  The package's own tests start a throwaway cluster with `initdb`/`pg_ctl` found through
1440
1447
  `POSTGRES_BIN_DIR`, `PATH` or a standard install location. They skip where no server can run and
1441
1448
  fail under `CI`.
1449
+
1450
+ ## Runner policy
1451
+
1452
+ `vouchington runner-policy [--config <file>] [--root <directory>]` checks GitHub Actions runner
1453
+ policy for a consumer's workflows. `--config` defaults to `.github/runner-policy.json` and `--root`
1454
+ to `.github/workflows` (only `*.yml` / `*.yaml` files directly under the root are read). It prints
1455
+ each violation and exits 1 on any violation, 0 when clean, and 2 on a usage error. The library
1456
+ subpath `vouchington-tooling/runner-policy` exports the pure
1457
+ `evaluateRunnerPolicy(inputs: {path, text}[], config)` plus `parseRunnerPolicyConfig`,
1458
+ `discoverWorkflows` and `loadRunnerPolicyConfig`. A workflow is identified by its path relative to
1459
+ the root (for example `checks.yml`).
1460
+
1461
+ ```json
1462
+ {
1463
+ "allowedLabels": ["runner-small", "runner-large"],
1464
+ "requiredJobs": [{ "workflow": "ci.yml", "job": "gate", "runsOn": "runner-large" }],
1465
+ "exactLabelJobs": [{ "label": "runner-arm", "jobs": ["ci.yml#build", "ci.yml#test"] }],
1466
+ "restrictedLabels": [
1467
+ {
1468
+ "label": "runner-small",
1469
+ "forbidServices": true,
1470
+ "forbiddenActions": {
1471
+ "prefixes": ["docker/"],
1472
+ "contains": ["/docker/"],
1473
+ "exact": ["./.github/actions/setup-db"]
1474
+ }
1475
+ }
1476
+ ]
1477
+ }
1478
+ ```
1479
+
1480
+ Only `allowedLabels` (non-empty) is required; unknown keys are rejected and every config problem is
1481
+ reported at once. Policies:
1482
+
1483
+ - `allowedLabels`: every non-delegate job's `runs-on` must be a literal string in the set, or
1484
+ `${{ matrix.<field> }}` resolving from `strategy.matrix.<field>` plus `strategy.matrix.include[].<field>`
1485
+ to a non-empty candidate list whose members are all in the set. Missing `runs-on`, unresolved or
1486
+ expression matrices, other computed expressions, array label sets and object forms are rejected.
1487
+ - Jobs with `uses:` (reusable-workflow delegates) must not set `runs-on`.
1488
+ - `requiredJobs`: each job must exist in its workflow and use exactly the literal `runsOn`.
1489
+ - `exactLabelJobs`: the `workflow#job` entries running on `label` (literally or through any matrix
1490
+ candidate) must equal `jobs`; missing and extra entries are both reported.
1491
+ - `restrictedLabels`: jobs using `label` literally must not declare non-empty `services`
1492
+ (`forbidServices`, default `true`) nor use a step `uses` value matching `forbiddenActions`
1493
+ `prefixes`, `contains` substrings or `exact` values.
1494
+
1495
+ The check fails closed: no discovered workflows, a missing root, an unreadable config or workflow,
1496
+ a YAML parse error, or a config entry naming an undiscovered workflow is a failure, never a pass.
@@ -1,6 +1,6 @@
1
1
  import type { AuditRedactor } from '../audit-journal/text.mts';
2
2
  import type { JournalEntry } from '../audit-journal/types.mts';
3
- /** Journal entries that hold exactly one sandbox or permission block, made paste-safe. */
3
+ /** Journal entries that hold sandbox or permission blocks (several per entry), made paste-safe. */
4
4
  export declare function getConformingSandboxBlocks(entries: Iterable<JournalEntry>, redact?: AuditRedactor, maxBytes?: number): string[];
5
5
  export declare function unavailableSandboxSection(reason: string, blocks?: string[]): string;
6
6
  export declare function journalSandboxSection(blocks: string[]): string;
@@ -44,9 +44,18 @@ function omissionBlock(count) {
44
44
  ' - Disposition: see journal for the omitted blocks',
45
45
  ].join('\n');
46
46
  }
47
- /** Journal entries that hold exactly one sandbox or permission block, made paste-safe. */
47
+ /** Journal text that names a sandbox block type but does not match its grammar. */
48
+ const UNPARSED = {
49
+ marker: /`(?:sandbox-escalation|sandbox-failure|ambiguous-failure)`/,
50
+ note: (count) => [
51
+ `- \`ambiguous-failure\` — unparsed — ${count} journal blocks named a sandbox event but did not match the block grammar; see journal`,
52
+ ' - Evidence: unparsed blocks remain in the session journal',
53
+ ' - Disposition: see journal for the unparsed sandbox blocks',
54
+ ].join('\n'),
55
+ };
56
+ /** Journal entries that hold sandbox or permission blocks (several per entry), made paste-safe. */
48
57
  export function getConformingSandboxBlocks(entries, redact, maxBytes = SANDBOX_BLOCKS_MAX_BYTES) {
49
- return conformingBlocks(entries, matchBlock, Math.min(maxBytes, SANDBOX_BLOCKS_MAX_BYTES), redact, omissionBlock);
58
+ return conformingBlocks(entries, matchBlock, Math.min(maxBytes, SANDBOX_BLOCKS_MAX_BYTES), redact, omissionBlock, UNPARSED);
50
59
  }
51
60
  export function unavailableSandboxSection(reason, blocks = []) {
52
61
  return [`${SANDBOX_SECTION_HEADER}\nStatus: unavailable (${reason})`, ...blocks].join('\n\n');
@@ -5,9 +5,15 @@ import { type AuditRedactor } from './text.mts';
5
5
  export declare function matchAuditBlock(markdown: string, patterns: readonly RegExp[], prefixes: readonly string[], render: AuditRender & {
6
6
  shrinkOrder: readonly number[];
7
7
  }): string | null;
8
+ /** What counts as an audit block that failed to parse, and how to report that many of them. */
9
+ export type UnparsedReport = {
10
+ marker: RegExp;
11
+ note: (count: number) => string;
12
+ };
8
13
  /**
9
14
  * Matches every journal block whole while together they fit `totalBudgetBytes`. Otherwise it keeps
10
15
  * the leading blocks that fit an equal share of the total and appends `omission(count)` — itself a
11
- * conforming block — so dropped groups are always reported, never silent.
16
+ * conforming block — so dropped groups are always reported, never silent. Blocks that name an
17
+ * audit type but do not match the grammar are counted and reported by `unparsed`, never ignored.
12
18
  */
13
- export declare function conformingBlocks(entries: Iterable<JournalEntry>, match: (markdown: string, render: AuditRender) => string | null, totalBudgetBytes: number, redact: AuditRedactor | undefined, omission: (count: number) => string): string[];
19
+ export declare function conformingBlocks(entries: Iterable<JournalEntry>, match: (markdown: string, render: AuditRender) => string | null, totalBudgetBytes: number, redact: AuditRedactor | undefined, omission: (count: number) => string, unparsed?: UnparsedReport): string[];
@@ -43,18 +43,48 @@ export function matchAuditBlock(markdown, patterns, prefixes, render) {
43
43
  const contents = fitFields(safe.map(({ units }) => units), overhead, render.budgetBytes ?? Infinity, render.shrinkOrder);
44
44
  return safe.map(({ prefix }, index) => `${prefix}${contents[index]}`).join('\n');
45
45
  }
46
+ const BLOCK_START = '- `';
47
+ /**
48
+ * One entry may hold several blocks: each top-level block line starts one. Text that does not
49
+ * open with a block is returned whole, so it either matches as a single block or is reported.
50
+ */
51
+ function splitBlocks(markdown) {
52
+ const lines = markdown.replace(/\r\n?/g, '\n').split('\n');
53
+ const first = lines.find((line) => !BLANK.test(line));
54
+ if (first === undefined || !first.startsWith(BLOCK_START))
55
+ return [markdown];
56
+ const chunks = [];
57
+ for (const line of lines.slice(lines.indexOf(first))) {
58
+ if (line.startsWith(BLOCK_START))
59
+ chunks.push([line]);
60
+ else
61
+ chunks.at(-1).push(line);
62
+ }
63
+ return chunks.map((chunk) => chunk.join('\n'));
64
+ }
46
65
  /**
47
66
  * Matches every journal block whole while together they fit `totalBudgetBytes`. Otherwise it keeps
48
67
  * the leading blocks that fit an equal share of the total and appends `omission(count)` — itself a
49
- * conforming block — so dropped groups are always reported, never silent.
68
+ * conforming block — so dropped groups are always reported, never silent. Blocks that name an
69
+ * audit type but do not match the grammar are counted and reported by `unparsed`, never ignored.
50
70
  */
51
- export function conformingBlocks(entries, match, totalBudgetBytes, redact, omission) {
71
+ export function conformingBlocks(entries, match, totalBudgetBytes, redact, omission, unparsed) {
72
+ let unparsedCount = 0;
52
73
  const markdowns = [...entries]
53
74
  .flatMap((entry) => {
54
75
  const data = entry?.data;
55
- return data?.type === 'journal' && typeof data.markdown === 'string' ? [data.markdown] : [];
76
+ return data?.type === 'journal' && typeof data.markdown === 'string'
77
+ ? splitBlocks(data.markdown)
78
+ : [];
56
79
  })
57
- .filter((markdown) => match(markdown, { redact }) !== null);
80
+ .filter((markdown) => {
81
+ if (match(markdown, { redact }) !== null)
82
+ return true;
83
+ if (unparsed?.marker.test(markdown))
84
+ unparsedCount++;
85
+ return false;
86
+ });
58
87
  const { rendered, omitted } = selectWithin(markdowns, totalBudgetBytes, byteLength(omission(markdowns.length)) + 2, 2, MIN_BLOCK_SHARE_BYTES, (markdown, budgetBytes) => match(markdown, { redact, budgetBytes }));
59
- return omitted ? [...rendered, omission(omitted)] : rendered;
88
+ const blocks = omitted ? [...rendered, omission(omitted)] : rendered;
89
+ return unparsed && unparsedCount ? [...blocks, unparsed.note(unparsedCount)] : blocks;
60
90
  }
@@ -28,6 +28,16 @@ function omissionGroup(count) {
28
28
  ' - Disposition: see journal for the omitted failure groups',
29
29
  ].join('\n');
30
30
  }
31
+ /** Journal text that names a CI failure group but does not match the block grammar. */
32
+ const UNPARSED = {
33
+ marker: /`(?:recurring|one-off)` — `GitHub Actions`/,
34
+ note: (count) => [
35
+ `- \`one-off\` — \`GitHub Actions\` — ${count} journal blocks named a CI failure but did not match the block grammar; see journal`,
36
+ ' - Evidence: unparsed blocks remain in the session journal',
37
+ ' - Root diagnostic: not parsed; the journal text did not match the documented block grammar',
38
+ ' - Disposition: see journal for the unparsed failure blocks',
39
+ ].join('\n'),
40
+ };
31
41
  export function isConformingCiFailureBlock(markdown) {
32
42
  if (markdown.length > CI_FAILURE_BLOCK_MAX_BYTES ||
33
43
  Buffer.byteLength(markdown) > CI_FAILURE_BLOCK_MAX_BYTES)
@@ -35,7 +45,7 @@ export function isConformingCiFailureBlock(markdown) {
35
45
  return matchBlock(markdown) !== null;
36
46
  }
37
47
  export function getConformingGroups(entries, redact, maxBytes = CI_SECTION_MAX_BYTES) {
38
- return conformingBlocks(entries, matchBlock, Math.min(maxBytes, CI_SECTION_MAX_BYTES), redact, omissionGroup);
48
+ return conformingBlocks(entries, matchBlock, Math.min(maxBytes, CI_SECTION_MAX_BYTES), redact, omissionGroup, UNPARSED);
39
49
  }
40
50
  export function incompleteCiSection(markdownBlocks) {
41
51
  return [
@@ -16,6 +16,7 @@ import { runScript } from "./commands/spawn-script.mjs";
16
16
  import { runNugetCentralVersionCommand } from "./commands/nuget-central-version.mjs";
17
17
  import { runDeadCodeCli } from "../dead-code/cli.mjs";
18
18
  import { runVerifyWorkflowSecretsCli } from "../workflow-secrets-drift/cli.mjs";
19
+ import { runRunnerPolicyCli } from "../runner-policy/cli.mjs";
19
20
  import { runVitestBlobManifestCommand } from "./commands/vitest-blob-manifest.mjs";
20
21
  import { runVitestReportAttemptCommand } from "./commands/vitest-report-attempt.mjs";
21
22
  import { runPrepareVitestReportsCommand } from "./commands/prepare-vitest-reports.mjs";
@@ -83,6 +84,8 @@ export function runCli(argv = process.argv) {
83
84
  return runNugetCentralVersionCommand(parsed.args);
84
85
  case 'verify-workflow-secrets':
85
86
  return runVerifyWorkflowSecretsCli(parsed.args);
87
+ case 'runner-policy':
88
+ return runRunnerPolicyCli(parsed.args);
86
89
  case 'dead-code':
87
90
  return runDeadCodeCli(parsed.args);
88
91
  case 'swift-semantic-equal':
@@ -1,4 +1,4 @@
1
- declare const FORWARDED: readonly ["with-host-lock", "host-storage", "pnpm-install", "vitest-blob-manifest", "vitest-report-attempt", "prepare-vitest-reports", "nuget-central-version", "verify-workflow-secrets", "dead-code", "swift-semantic-equal", "post-review", "stage-review-payload", "retrospective-transcript", "retrospective-facts", "agent-blackboard", "mcp", "hook", "worktree", "transient-retry", "sandbox-command-audit", "cloc", "coverage-scope-check", "trivy-policy", "docker-image-mirror", "workspace-registry-check", "storybook-browser-runner", "tmux"];
1
+ declare const FORWARDED: readonly ["with-host-lock", "host-storage", "pnpm-install", "vitest-blob-manifest", "vitest-report-attempt", "prepare-vitest-reports", "nuget-central-version", "verify-workflow-secrets", "runner-policy", "dead-code", "swift-semantic-equal", "post-review", "stage-review-payload", "retrospective-transcript", "retrospective-facts", "agent-blackboard", "mcp", "hook", "worktree", "transient-retry", "sandbox-command-audit", "cloc", "coverage-scope-check", "trivy-policy", "docker-image-mirror", "workspace-registry-check", "storybook-browser-runner", "tmux"];
2
2
  type Name = (typeof FORWARDED)[number];
3
3
  type ForwardedCommand = {
4
4
  [K in Name]: {
@@ -7,6 +7,7 @@ const FORWARDED = [
7
7
  'prepare-vitest-reports',
8
8
  'nuget-central-version',
9
9
  'verify-workflow-secrets',
10
+ 'runner-policy',
10
11
  'dead-code',
11
12
  'swift-semantic-equal',
12
13
  'post-review',
@@ -44,6 +44,9 @@ export type ParsedCli = {
44
44
  } | {
45
45
  kind: 'verify-workflow-secrets';
46
46
  args: string[];
47
+ } | {
48
+ kind: 'runner-policy';
49
+ args: string[];
47
50
  } | {
48
51
  kind: 'dead-code';
49
52
  args: string[];
@@ -1 +1 @@
1
- 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 host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base 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 agent-issue-labels Map changed paths to labels; create missing repository labels\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 (KEEP_MIN or --main-history)\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 gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n dead-code Gate unused code against a committed jscpd baseline\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 an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\n cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n workspace-registry-check Check syncpack, pnpm workspace and CI path-filter registries against tracked manifests\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\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\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\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>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\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]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\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 [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\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 session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\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]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update,\n snapshot_export, snapshot_partition, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\n\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI run block (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>] [--allow-registry <prefix>]... [--require-digest]\n [--allow-ref-expression <text>]...\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use. --allow-registry (repeatable) instead requires every image,\n including FROM and COPY --from, to start with one of the prefixes; a reference that expands a\n variable passes only when its literal text before the variable starts with a prefix. --require-digest\n requires @sha256: plus 64 lowercase hex characters. Stage aliases and scratch stay exempt.\n --allow-ref-expression (repeatable) is an audited escape hatch for dynamic job outputs: a reference\n whose raw text exactly equals the value is accepted. Images the same file builds locally are exempt.\n\nworkspace-registry-check [--root <dir>] [--syncpack-config <path>] [--workspace-file <path>]\n [--path-filters <path>] [--tooling-group <name>] [--trigger-only-glob <glob>] [--runtime-prefix <prefix>]\n Reconciles git-tracked package.json manifests with the syncpack \"source\" globs (default\n .syncpackrc.json), the pnpm \"packages\" globs (pnpm-workspace.yaml) and the dorny/paths-filter groups\n (.github/ci-path-filters.yml) and prints one line per violation (exit 1). The --tooling-group group\n (default tooling) must reach every manifest and wildcard workspace glob, and its --trigger-only-glob\n (default **/package.json) does not count as registering a manifest. Each group named with\n --runtime-prefix (default runtime-) must mirror the primary group of the same name.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
1
+ 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 host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base 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 agent-issue-labels Map changed paths to labels; create missing repository labels\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 (KEEP_MIN or --main-history)\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 gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n runner-policy Check workflow runner labels and jobs against a config\n dead-code Gate unused code against a committed jscpd baseline\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 an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\n cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n workspace-registry-check Check syncpack, pnpm workspace and CI path-filter registries against tracked manifests\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\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\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\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>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\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]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\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 [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\nrunner-policy [--config FILE] [--root DIR]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\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 session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\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]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update,\n snapshot_export, snapshot_partition, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\n\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI run block (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>] [--allow-registry <prefix>]... [--require-digest]\n [--allow-ref-expression <text>]...\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use. --allow-registry (repeatable) instead requires every image,\n including FROM and COPY --from, to start with one of the prefixes; a reference that expands a\n variable passes only when its literal text before the variable starts with a prefix. --require-digest\n requires @sha256: plus 64 lowercase hex characters. Stage aliases and scratch stay exempt.\n --allow-ref-expression (repeatable) is an audited escape hatch for dynamic job outputs: a reference\n whose raw text exactly equals the value is accepted. Images the same file builds locally are exempt.\n\nworkspace-registry-check [--root <dir>] [--syncpack-config <path>] [--workspace-file <path>]\n [--path-filters <path>] [--tooling-group <name>] [--trigger-only-glob <glob>] [--runtime-prefix <prefix>]\n Reconciles git-tracked package.json manifests with the syncpack \"source\" globs (default\n .syncpackrc.json), the pnpm \"packages\" globs (pnpm-workspace.yaml) and the dorny/paths-filter groups\n (.github/ci-path-filters.yml) and prints one line per violation (exit 1). The --tooling-group group\n (default tooling) must reach every manifest and wildcard workspace glob, and its --trigger-only-glob\n (default **/package.json) does not count as registering a manifest. Each group named with\n --runtime-prefix (default runtime-) must mirror the primary group of the same name.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
@@ -43,6 +43,7 @@ Commands:
43
43
  gha-collaborator-trust Classify authors as write-access collaborators or not
44
44
  nuget-central-version Validate a Directory.Packages.props PackageVersion delta
45
45
  verify-workflow-secrets Check a secret inventory against live repository and environment secrets
46
+ runner-policy Check workflow runner labels and jobs against a config
46
47
  dead-code Gate unused code against a committed jscpd baseline
47
48
  swift-semantic-equal Compare Swift sources ignoring comments and whitespace
48
49
  post-review Post one COMMENT review from a staged payload file
@@ -129,6 +130,7 @@ harness-assert-gates <gate>...
129
130
  gha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json
130
131
  nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>
131
132
  verify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]
133
+ runner-policy [--config FILE] [--root DIR]
132
134
  dead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...
133
135
  swift-semantic-equal <base> <head> <file.swift>
134
136
  post-review
@@ -3,6 +3,7 @@ import type { RunTextCommand } from '../gh-cli/exec.mts';
3
3
  import type { GhRunner } from './pr-gh.mts';
4
4
  import type { PolicySpawner } from './policy-spawn.mts';
5
5
  import { type SnapshotRegistry } from './snapshot-registry.mts';
6
+ import { type InstallInfo } from './install-info.mts';
6
7
  export type ServerEnvironment = {
7
8
  /** The launch directory's worktree top level, or undefined when it is not inside one. */
8
9
  launchRoot: string | undefined;
@@ -25,6 +26,8 @@ export type ServerEnvironment = {
25
26
  };
26
27
  /** Test seam: a fresh registry stands in for a server restart. Defaults to the process's own. */
27
28
  snapshots?: SnapshotRegistry;
29
+ /** The server's own version and install location, captured at startup. */
30
+ install?: InstallInfo;
28
31
  };
29
32
  export type ToolCallResult = {
30
33
  content: Array<{
@@ -10,9 +10,11 @@ import { snapshotPartition } from "./handlers-snapshot-partition.mjs";
10
10
  import { sessionArchive, sessionEnsure, snapshotExport } from "./handlers-session.mjs";
11
11
  import { handlePrCreate, handlePrUpdate, handlePrValidate } from "./handlers-pr.mjs";
12
12
  import { createSnapshotRegistry } from "./snapshot-registry.mjs";
13
+ import { captureInstall, installSuffix } from "./install-info.mjs";
13
14
  import { TOOLS } from "./tools.mjs";
14
15
  import { resolveWorktree } from "./worktree.mjs";
15
16
  const PROCESS_SNAPSHOTS = createSnapshotRegistry();
17
+ const PROCESS_INSTALL = captureInstall();
16
18
  const HANDLERS = {
17
19
  journal_append: journalAppend,
18
20
  journal_entries: journalEntries,
@@ -81,6 +83,10 @@ export async function callTool(name, rawArguments, environment) {
81
83
  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
82
84
  }
83
85
  catch (error) {
84
- return { isError: true, content: [{ type: 'text', text: describeError(error) }] };
86
+ const install = environment.install ?? PROCESS_INSTALL;
87
+ return {
88
+ isError: true,
89
+ content: [{ type: 'text', text: describeError(error) + installSuffix(error, install) }],
90
+ };
85
91
  }
86
92
  }
@@ -0,0 +1,11 @@
1
+ /** What the running server knows about its own install, captured once at startup. */
2
+ export type InstallInfo = {
3
+ name: string;
4
+ version: string;
5
+ /** Absolute path of the package directory this server was loaded from. */
6
+ location: string;
7
+ };
8
+ export declare function captureInstall(version?: string): InstallInfo;
9
+ export declare function describeInstall(install: InstallInfo): string;
10
+ /** The suffix appended to every tool error so a stale or swapped install is obvious. */
11
+ export declare function installSuffix(error: unknown, install: InstallInfo): string;
@@ -0,0 +1,45 @@
1
+ import { isAbsolute, relative, sep } from 'node:path';
2
+ import { fileURLToPath } from 'node:url';
3
+ import { readInstalledVersion } from "../cli/installed-version.mjs";
4
+ const PACKAGE_NAME = 'vouchington-tooling';
5
+ export function captureInstall(version = readInstalledVersion()) {
6
+ return {
7
+ name: PACKAGE_NAME,
8
+ version,
9
+ location: fileURLToPath(new URL('../../', import.meta.url)).replace(/\/$/, ''),
10
+ };
11
+ }
12
+ export function describeInstall(install) {
13
+ return `${install.name} ${install.version} (${install.location})`;
14
+ }
15
+ const MISSING_FILE = /ERR_MODULE_NOT_FOUND|Cannot find module|ENOENT|no such file/i;
16
+ /**
17
+ * The missing target only: the ENOENT `path`, else the first quoted specifier in the message
18
+ * (`Cannot find module '<x>'`, `Cannot find package '<x>'`), never the "imported from" importer.
19
+ */
20
+ function missingTarget(error, message) {
21
+ const path = error?.path;
22
+ if (typeof path === 'string')
23
+ return path;
24
+ return /'([^']+)'/.exec(message)?.[1];
25
+ }
26
+ /** True only for a missing-file failure whose missing target is inside the server's own install. */
27
+ function isInstallSwapped(error, install) {
28
+ const code = error?.code;
29
+ const message = error instanceof Error ? error.message : String(error);
30
+ const text = `${typeof code === 'string' ? code : ''} ${message}`;
31
+ if (!MISSING_FILE.test(text))
32
+ return false;
33
+ const target = missingTarget(error, message);
34
+ if (target === undefined || !isAbsolute(target))
35
+ return false;
36
+ const rel = relative(install.location, target);
37
+ return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
38
+ }
39
+ /** The suffix appended to every tool error so a stale or swapped install is obvious. */
40
+ export function installSuffix(error, install) {
41
+ const swapped = isInstallSwapped(error, install)
42
+ ? ' The server install changed underneath it: reconnect the server (`/mcp` in Claude Code, or restart Codex).'
43
+ : '';
44
+ return `${swapped}\n[${describeInstall(install)}]`;
45
+ }
@@ -1,4 +1,6 @@
1
1
  import type { Args } from './args.mts';
2
+ /** A pull request number as digits, from a digit string or a positive safe integer. */
3
+ export declare function prNumber(value: unknown): string | undefined;
2
4
  /**
3
5
  * Checks `compose.facts`: either `{ status, reason }` (unassessed) or a live collection selector,
4
6
  * never both. Returns whether live collection was requested.
@@ -1,5 +1,11 @@
1
1
  /** A plain branch name: no scheme or colon, no leading dash, no `..`. */
2
2
  const BRANCH = /^(?!-)(?!.*\.\.)[A-Za-z0-9._/-]+$/;
3
+ /** A pull request number as digits, from a digit string or a positive safe integer. */
4
+ export function prNumber(value) {
5
+ if (typeof value === 'number')
6
+ return Number.isSafeInteger(value) && value > 0 ? String(value) : undefined;
7
+ return typeof value === 'string' && /^\d+$/.test(value) ? value : undefined;
8
+ }
3
9
  /**
4
10
  * Checks `compose.facts`: either `{ status, reason }` (unassessed) or a live collection selector,
5
11
  * never both. Returns whether live collection was requested.
@@ -15,8 +21,8 @@ export function checkFactsInput(facts) {
15
21
  throw new Error('compose.facts.reason requires a status');
16
22
  // The collector trusts these types; a string "false" must not read as noPr: true.
17
23
  // gh accepts a pull request URL for either, which would reach another repository.
18
- if ('pr' in facts && (typeof facts.pr !== 'string' || !/^\d+$/.test(facts.pr)))
19
- throw new Error('compose.facts.pr must be a pull request number string');
24
+ if ('pr' in facts && prNumber(facts.pr) === undefined)
25
+ throw new Error('compose.facts.pr must be a pull request number (positive integer or string)');
20
26
  if ('branch' in facts && (typeof facts.branch !== 'string' || !BRANCH.test(facts.branch)))
21
27
  throw new Error('compose.facts.branch must be a branch name');
22
28
  if ('noPr' in facts && typeof facts.noPr !== 'boolean')
@@ -3,7 +3,7 @@ import { rejectUnknown } from "./args.mjs";
3
3
  import { inspectHarnessEnvironment, selectHarnessSession, } from "../agent-harness-identity/index.mjs";
4
4
  import { SESSION_ID } from "../retrospective-transcript/resolve-transcript-file.mjs";
5
5
  import { serverJournalLoader } from "./journal-read.mjs";
6
- import { checkFactsInput } from "./retrospective-facts-input.mjs";
6
+ import { checkFactsInput, prNumber } from "./retrospective-facts-input.mjs";
7
7
  import { spawnPolicy } from "./policy-spawn.mjs";
8
8
  const HARNESSES = ['codex', 'claude', 'cursor', 'grok'];
9
9
  const COMPOSE_KEYS = [
@@ -117,7 +117,11 @@ function transcriptInput(transcript, base) {
117
117
  }
118
118
  function factsInput(facts, base) {
119
119
  return checkFactsInput(facts)
120
- ? { ...facts, execute: worktreeExecutor(base.worktree, base.env) }
120
+ ? {
121
+ ...facts,
122
+ ...('pr' in facts ? { pr: prNumber(facts.pr) } : {}),
123
+ execute: worktreeExecutor(base.worktree, base.env),
124
+ }
121
125
  : facts;
122
126
  }
123
127
  /** Builds the retrospective markdown with `composeRetrospective`, rejecting unknown input keys. */
@@ -1,4 +1,5 @@
1
1
  import { assertBlackboardInstalled, loadMcpSdk } from "./sdk.mjs";
2
+ import { captureInstall } from "./install-info.mjs";
2
3
  import { createMcpServer } from "./server.mjs";
3
4
  import { launchWorktreeRoot, runIsolatedGit } from "./worktree.mjs";
4
5
  /**
@@ -15,6 +16,7 @@ export async function runMcpServer(options) {
15
16
  launchRoot,
16
17
  env: options.env,
17
18
  runGit,
19
+ install: captureInstall(options.version),
18
20
  ...(options.resolveFrom === undefined ? {} : { resolveFrom: options.resolveFrom }),
19
21
  ...(options.blackboard === undefined ? {} : { blackboard: options.blackboard }),
20
22
  };
@@ -1,2 +1,9 @@
1
1
  import { type CodexSegment } from './shared.mts';
2
+ export type CodexSegmentOutcome = {
3
+ segment: CodexSegment;
4
+ } | {
5
+ reason: string;
6
+ };
7
+ /** Segments a Codex rollout, or says why its owned boundary cannot be established. */
8
+ export declare function explainCodexSegment(lines: string[]): CodexSegmentOutcome;
2
9
  export declare function segmentCodex(lines: string[]): CodexSegment | undefined;
@@ -42,17 +42,18 @@ function retainHighWater(previous, current) {
42
42
  cacheCreation: 0,
43
43
  };
44
44
  }
45
- export function segmentCodex(lines) {
45
+ /** Segments a Codex rollout, or says why its owned boundary cannot be established. */
46
+ export function explainCodexSegment(lines) {
46
47
  const content = lines.filter(Boolean);
47
48
  const sessionMeta = parseLines(content.slice(0, 1))[0];
48
49
  if (sessionMeta?.type !== 'session_meta')
49
- return { lines: content, baseline: emptyTokens() };
50
+ return { segment: { lines: content, baseline: emptyTokens() } };
50
51
  if (!hasInheritedParent(sessionMeta))
51
- return { lines: content.slice(1), baseline: emptyTokens() };
52
+ return { segment: { lines: content.slice(1), baseline: emptyTokens() } };
52
53
  const timestamp = asRecord(sessionMeta.payload)?.timestamp;
53
54
  const timestampMs = typeof timestamp === 'string' ? Date.parse(timestamp) : Number.NaN;
54
55
  if (!Number.isFinite(timestampMs))
55
- return undefined;
56
+ return { reason: 'the inherited child session_meta has no valid timestamp' };
56
57
  const ownedIndex = content.findIndex((line, index) => {
57
58
  if (index === 0)
58
59
  return false;
@@ -60,14 +61,17 @@ export function segmentCodex(lines) {
60
61
  return record ? isOwnedTaskStart(record, timestampMs) : false;
61
62
  });
62
63
  if (ownedIndex === -1)
63
- return undefined;
64
- let baseline;
64
+ return { reason: 'no task_started at or after the child session start was recorded' };
65
+ // A child that inherited no token totals starts from zero, as a fresh subagent does.
66
+ let baseline = emptyTokens();
65
67
  for (const record of parseLines(content.slice(1, ownedIndex))) {
66
68
  const current = usage(record);
67
69
  if (current)
68
- baseline = retainHighWater(baseline ?? emptyTokens(), current);
70
+ baseline = retainHighWater(baseline, current);
69
71
  }
70
- if (!baseline)
71
- return undefined;
72
- return { lines: content.slice(ownedIndex), baseline };
72
+ return { segment: { lines: content.slice(ownedIndex), baseline } };
73
+ }
74
+ export function segmentCodex(lines) {
75
+ const outcome = explainCodexSegment(lines);
76
+ return 'segment' in outcome ? outcome.segment : undefined;
73
77
  }