@vaultcompass/conductor 0.10.0 → 0.12.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.
package/README.md CHANGED
@@ -166,7 +166,7 @@ required.
166
166
  A commit with a staged credential in it prints the full report and exits 1:
167
167
 
168
168
  ```
169
- conductor 0.10.0
169
+ conductor 0.12.0
170
170
  verdict-token: blocked (1)
171
171
  conductor run: 2 gate(s), 1 finding(s)
172
172
 
@@ -359,11 +359,17 @@ gates:
359
359
  secrets-history:
360
360
  product: gitleaks
361
361
  enabled: true
362
+ # Enabled because gitleaks was found on the machine that ran init. CI must
363
+ # install gitleaks itself (conductor does not); without it this gate
364
+ # reports conductor/gate-missing and the run exits 2.
362
365
  stage: ci
363
366
  enforce: true
364
367
  vulnerabilities:
365
368
  product: osv-scanner
366
369
  enabled: true
370
+ # Enabled because osv-scanner was found on the machine that ran init. CI must
371
+ # install osv-scanner itself (conductor does not); without it this gate
372
+ # reports conductor/gate-missing and the run exits 2.
367
373
  stage: ci
368
374
  enforce: true
369
375
  present-on-base: report
@@ -721,7 +727,12 @@ code and the `enforce` flags the run already had.
721
727
  vulnerabilities already on the base branch, reported and not blocking;
722
728
  the report's third line then says `present-on-base: N reported, not
723
729
  blocking`, the verdict sentence says the same, and the Action copies that
724
- line to the job summary under the token.
730
+ line to the job summary under the token. When the intent gate's spec was
731
+ chosen weakly, differently than before 0.11.0, or not at all because of a
732
+ tie or a branch 0.10.0 bound, the line after the token (after the
733
+ present-on-base line, when there is one) is one of four fixed
734
+ `intent-spec:` lines naming no branch or file, and the Action copies that
735
+ one too.
725
736
  - `nothing-checked`: exit 0, but nothing was checked. Either no gate ran at
726
737
  all (none is enabled, or every enabled one was deferred to a later stage,
727
738
  had nothing to judge, or was skipped), or every gate that ran examined
@@ -1088,6 +1099,29 @@ gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
1088
1099
  which arrived in git 2.31. Only that gate checks: an older git makes it
1089
1100
  could-not-run, naming the version, and the other gates run.
1090
1101
 
1102
+ ### Trying pull-request mode locally
1103
+
1104
+ To see roughly what CI would say about a branch, check it out and name the
1105
+ base as the trust base:
1106
+
1107
+ ```
1108
+ conductor run --trust-base refs/remotes/origin/main --verbose
1109
+ ```
1110
+
1111
+ `--trust-base` takes any ref git resolves in your clone, so use a clone with
1112
+ the base branch present (the CI recipes use `fetch-depth: 0` for the same
1113
+ reason). With no `GITHUB_BASE_REF` set, as on a laptop, the change set for the
1114
+ intent gate is measured from the trust base, so `--base` is optional; add
1115
+ `--base <ref>` to measure from a different ref. Add `--stage ci` to run at
1116
+ the stage the Action runs at.
1117
+
1118
+ The gotcha is the same locally as in CI: the policy and the other control
1119
+ files are read from the base ref, not from your working tree. A local edit to
1120
+ `.guardrails.yaml` has no effect on a `--trust-base` run until the change is
1121
+ on the base; it shows up as a proposal line in the report instead. To preview
1122
+ a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
1123
+ conductor" above.
1124
+
1091
1125
  ## Intent at a pull request
1092
1126
 
1093
1127
  The intent gate is the only one of the five with any ceremony: its native
@@ -1180,12 +1214,24 @@ itself and needs an administrator to merge it.
1180
1214
  token is exact and lowercase, a frozen contract at rule 2 still wins over
1181
1215
  it, and `--spec` at rule 1 still overrides it.
1182
1216
  4. A markdown file **directly under** `docs/superpowers/specs` whose name
1183
- relates to the branch. The branch slug is the branch name with its first
1184
- segment (`feat/`, `fix/`) removed; a filename is reduced by stripping a
1185
- `YYYY-MM-DD-` prefix and a trailing `-design`; the two are candidates when
1186
- either contains the other. Several candidates are ranked: a stem **equal**
1187
- to the slug first, then the **longest** stem, and only then the newest
1188
- name, which is a lexical tie-break, so **date every spec**.
1217
+ matches the branch on **whole words**. The branch slug is the branch name
1218
+ with its first segment (`feat/`, `fix/`) removed; a filename is reduced by
1219
+ stripping a `YYYY-MM-DD-` prefix and a trailing `-design`. Both have their
1220
+ ASCII letters lower-cased and are split into words on `-`, `_`, `/` and
1221
+ spaces. A spec is a candidate when one name's words appear, in order and
1222
+ together, inside the other's, and at least one shared word is three or
1223
+ more characters, contains a letter, and is not a common branch word
1224
+ (`fix`, `feat`, `wip`, `docs`, and the rest of the list in
1225
+ `src/intent-spec.ts`). Candidates are ranked by an equal name first, then
1226
+ the most shared words, then the longest shared word, then the lexically
1227
+ greatest filename among files with the same name (the newest date when
1228
+ every spec is dated `YYYY-MM-DD-`, so **date every spec** in that form).
1229
+ Two different specs that tie are **not** guessed between: the gate is
1230
+ skipped as `intent-guard/spec-ambiguous`, naming both. A spec chosen on
1231
+ one shared word, or on word length alone, is used and the report says the
1232
+ match is weak. Branch names like `pr` or `fix/wip` choose nothing. When
1233
+ the choice matters, say it: a `Spec:` line in the pull request body, or a
1234
+ branch named after the spec.
1189
1235
 
1190
1236
  **A branch with neither** is a third state beside deferred and could-not-run:
1191
1237
  the gate is switched on, it ran, and it had nothing to check. It gets one
@@ -1197,7 +1243,9 @@ repository. A waived pull request lands in the same state and is reported
1197
1243
  under its own `intent-guard/contract-waived` id, with its own wording on the
1198
1244
  skipped line, in the verdict and on the one-line summary of a clean run, so a
1199
1245
  reader can tell "nobody has written one" from "somebody decided against one"
1200
- wherever they meet it.
1246
+ wherever they meet it. An ambiguous branch, one two specs match equally,
1247
+ lands in the same advisory state under its own `intent-guard/spec-ambiguous`
1248
+ id, and never reaches the exit code either.
1201
1249
 
1202
1250
  **A repository with no contract yet is not a repository this gate can act
1203
1251
  on**, and the no-contract skip line names `docs/superpowers/specs`, which is
@@ -1222,7 +1270,8 @@ gate does not run at all on that pull request, and budget breaches are the
1222
1270
  thing this gate blocks on. The one thing a waiver cannot override is a frozen
1223
1271
  native contract, under either of the two paths above, which is checked first:
1224
1272
  a repository that wants the gate to be non-waivable freezes a native contract
1225
- and keeps it committed.
1273
+ and keeps it committed. The branch-name convention is not a control either:
1274
+ whoever names the branch chooses among the base's specs.
1226
1275
 
1227
1276
  **What blocks is unchanged.** Blocking stays where intent-guard puts it:
1228
1277
  budget breaches block, subject to `enforce`. Drift on its own is reported and
@@ -1268,7 +1317,11 @@ runs `npm install -g --ignore-scripts` under the runner temp, never into the
1268
1317
  workspace, and prepends that bin directory to `PATH`, so the run step invokes
1269
1318
  `conductor` off `PATH` and each gate resolves by name the same way. The install
1270
1319
  is **unconditional**, on push and `pull_request` alike, so there is one code
1271
- path rather than one that matters and one that nobody exercises.
1320
+ path rather than one that matters and one that nobody exercises. On a push
1321
+ run, though, a repository's own devDependency on a gate in
1322
+ `node_modules/.bin` outranks that install and shadows the action's pin; when
1323
+ its version differs from the pin, conductor now warns in the job log, as a
1324
+ `::warning::` annotation and in the step summary, and still runs it.
1272
1325
 
1273
1326
  **On a pull request those four inputs may not pin backward.** The shape check
1274
1327
  asks whether an input is an exact version; it says nothing about which one, and
@@ -1358,7 +1411,7 @@ request being judged, and the version-pin protection described above
1358
1411
  "protects nothing" against a tree that controls its own judge (the
1359
1412
  validate step's own comment in `action.yml` says so in those words). A tag
1360
1413
  moves when someone pushes it. Name this action by owner and the full commit
1361
- SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.10.0.
1414
+ SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.12.0.
1362
1415
 
1363
1416
  ```yaml
1364
1417
  name: guardrails
@@ -1380,7 +1433,7 @@ jobs:
1380
1433
  with:
1381
1434
  node-version: '22.11.0'
1382
1435
  - id: conductor
1383
- uses: vaultcompasshq/conductor@v0.10.0
1436
+ uses: vaultcompasshq/conductor@v0.12.0
1384
1437
  with:
1385
1438
  output: conductor.sarif
1386
1439
  - uses: github/codeql-action/upload-sarif@v3
@@ -1455,7 +1508,7 @@ jobs:
1455
1508
  # installs those itself, globally. Leave conductor-version unset so the
1456
1509
  # umbrella is the default in the pinned action.yml.
1457
1510
  - id: conductor
1458
- uses: vaultcompasshq/conductor@v0.10.0
1511
+ uses: vaultcompasshq/conductor@v0.12.0
1459
1512
  with:
1460
1513
  output: conductor.sarif
1461
1514
  # Exact versions, never a range and never "latest". These three
@@ -1466,9 +1519,9 @@ jobs:
1466
1519
  # request of their own. On a pull request the action refuses a pin
1467
1520
  # below what the pinned action.yml ships, and the three lines can
1468
1521
  # be left out entirely to take that action's own versions.
1469
- dep-guard-version: 0.13.0
1470
- vault-guard-version: 1.11.0
1471
- intent-guard-version: 1.8.1
1522
+ dep-guard-version: 0.15.0
1523
+ vault-guard-version: 1.12.1
1524
+ intent-guard-version: 1.10.1
1472
1525
  - uses: github/codeql-action/upload-sarif@v3
1473
1526
  # Always: the log is most worth having on the run that failed.
1474
1527
  if: always()
@@ -1661,7 +1714,7 @@ jobs:
1661
1714
  node-version: '22.11.0'
1662
1715
  - id: conductor
1663
1716
  timeout-minutes: 5
1664
- uses: vaultcompasshq/conductor@v0.10.0
1717
+ uses: vaultcompasshq/conductor@v0.12.0
1665
1718
  with:
1666
1719
  pr-comment: true
1667
1720
  advisory: true
@@ -1797,7 +1850,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1797
1850
  # the pull request runs before the action in this job: no install, build
1798
1851
  # or test step here; those belong in a separate job. ...
1799
1852
  - id: conductor
1800
- uses: vaultcompasshq/conductor@v0.10.0
1853
+ uses: vaultcompasshq/conductor@v0.12.0
1801
1854
  with:
1802
1855
  output: conductor.sarif
1803
1856
  pr-comment: true
@@ -1876,12 +1929,12 @@ per pull request.
1876
1929
 
1877
1930
  ```yaml
1878
1931
  - id: conductor-package-a
1879
- uses: vaultcompasshq/conductor@v0.10.0
1932
+ uses: vaultcompasshq/conductor@v0.12.0
1880
1933
  with:
1881
1934
  pr-comment: true
1882
1935
  pr-comment-marker: 'package-a'
1883
1936
  - id: conductor-package-b
1884
- uses: vaultcompasshq/conductor@v0.10.0
1937
+ uses: vaultcompasshq/conductor@v0.12.0
1885
1938
  with:
1886
1939
  pr-comment: true
1887
1940
  pr-comment-marker: 'package-b'
@@ -1981,6 +2034,63 @@ is one snapshot of one run: no per-finding state, nothing to dismiss, no
1981
2034
  history between runs, and a new comment every time rather than an alert that
1982
2035
  closes when the finding goes away.
1983
2036
 
2037
+ ## Upgrading
2038
+
2039
+ An adopter pins two numbers, and they control different things.
2040
+
2041
+ - **The action ref**, `uses: vaultcompasshq/conductor@<tag or SHA>`, picks
2042
+ which `action.yml` runs. That file carries the defaults for the four
2043
+ version inputs and the constants the pull-request backward-pin rule
2044
+ measures a pin against.
2045
+ - **The `conductor-version` input** picks which `@vaultcompass/conductor`
2046
+ the install step installs. The same step installs the three gates at
2047
+ `dep-guard-version`, `vault-guard-version` and `intent-guard-version`.
2048
+ Each input defaults to the version the tag shipped.
2049
+
2050
+ **The recommended shape is to leave all four version inputs unset** and move
2051
+ only the action ref. On a pull request, the validate step refuses an input
2052
+ naming a version below the one the tag ships, so an explicit old pin breaks
2053
+ the day you upgrade the ref (see "The Action" above). Outside a pull request
2054
+ an explicit pin is unaffected, which is how a stale pin can sit unnoticed
2055
+ until the first pull request after the upgrade.
2056
+
2057
+ **Pin the action ref to a full commit SHA** with the tag as a comment, for
2058
+ example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.12.0`. To
2059
+ find the SHA for a tag, run
2060
+ `gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
2061
+ the Releases page.
2062
+
2063
+ **Dependabot or Renovate bumping that SHA changes the action ref only.** It
2064
+ does not touch a `dep-guard-version`, `vault-guard-version`,
2065
+ `intent-guard-version` or `conductor-version` you set by hand, so such a pin
2066
+ must be raised or removed by hand in the same pull request, or that pull
2067
+ request is refused by the rule above.
2068
+
2069
+ **An action-only tag moves the tag while the npm package stays.** The
2070
+ CHANGELOG marks these as "An action-only release" and says which
2071
+ `conductor-version` default stays. `@vaultcompass/conductor` does not change
2072
+ on those, so `conductor-version` need not change either; the gate defaults
2073
+ may.
2074
+
2075
+ Defaults per tag, taken only from CHANGELOG.md entries that state them. A
2076
+ tag with no row here has an entry that does not state its defaults; read
2077
+ `action.yml` at that tag.
2078
+
2079
+ | Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
2080
+ | --- | --- | --- | --- |
2081
+ | v0.12.0 | package | 0.12.0 | vault-guard 1.12.1 (from 1.12.0), intent-guard 1.10.1 (from 1.10.0) |
2082
+ | v0.11.1 | action-only | 0.11.0 | dep-guard 0.15.0 (from 0.14.0), vault-guard 1.12.0 (from 1.11.0) |
2083
+ | v0.11.0 | package | 0.11.0 | dep-guard 0.14.0, intent-guard 1.10.0 |
2084
+ | v0.10.0 | package | 0.10.0 | dep-guard 0.13.0, vault-guard 1.11.0 |
2085
+ | v0.8.2 | action-only | 0.8.1 | dep-guard 0.11.1 (from 0.10.1) |
2086
+ | v0.8.1 | package | 0.8.1 | dep-guard 0.10.1, vault-guard 1.9.1, intent-guard 1.8.1 |
2087
+ | v0.8.0 | package | 0.8.0 | dep-guard 0.10.0, vault-guard 1.9.0, intent-guard 1.8.0 |
2088
+ | v0.7.0 | package | 0.7.0 | none |
2089
+ | v0.6.0 | package | 0.6.0 | dep-guard 0.9.0 (from 0.8.0), intent-guard 1.7.0 (from 1.6.0) |
2090
+ | v0.5.1 | action-only | 0.5.0 | dep-guard 0.8.0 (from 0.7.0), intent-guard 1.6.0 (from 1.5.2) |
2091
+ | v0.4.4 | action-only | 0.4.0 | dep-guard 0.7.0 (from 0.6.0), vault-guard 1.8.0 (from 1.7.0) |
2092
+ | v0.4.3 | action-only | 0.4.0 | intent-guard 1.5.2 (from 1.4.0) |
2093
+
1984
2094
  ## What is in and what is out
1985
2095
 
1986
2096
  In: the policy file and its schema, `init` with dry-run, revert, and adopt,
package/dist/cli.js CHANGED
@@ -6,7 +6,7 @@
6
6
  // parses arguments and prints. That split is what lets every one of those
7
7
  // decisions be tested without a subprocess.
8
8
  import { Command, CommanderError } from 'commander';
9
- import { closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
9
+ import { appendFileSync, closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
10
10
  import os from 'node:os';
11
11
  import path from 'node:path';
12
12
  import { fileURLToPath } from 'node:url';
@@ -14,7 +14,7 @@ import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
14
14
  import { absolutePathEntries, createGitShim, pinGitOutside, pinnedGitInside, realPathInside, removeGitShim, runGit, tempInsideTreeMessage, workTreeAbove, } from './git.js';
15
15
  import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
16
16
  import { renderSarif } from './output-sarif.js';
17
- import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewWarnings, } from './output-text.js';
17
+ import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewAnnotations, versionSkewSummaryLines, versionSkewWarnings, } from './output-text.js';
18
18
  import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
19
19
  import { refusedTrustBase, runAll } from './run.js';
20
20
  import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
@@ -708,6 +708,31 @@ export function buildProgram() {
708
708
  if (logLines.length > 0) {
709
709
  process.stderr.write(`${logLines.join('\n')}\n`);
710
710
  }
711
+ // IN GITHUB ACTIONS, A VERSION SKEW IS ALSO AN ANNOTATION AND A
712
+ // STEP-SUMMARY LINE, so a run on a stale gate is visible on the run's
713
+ // page without anybody opening the log (audit 2026-10-18: every guard
714
+ // repository's own push runs used a stale devDependency for weeks and
715
+ // only the log said which version ran). Reporting only. The
716
+ // annotation goes to stdout when stdout is not the report (--output
717
+ // given, which is how the Action runs), and to stderr otherwise. A
718
+ // summary that cannot be written is skipped: it never changes the
719
+ // exit code.
720
+ if (process.env.GITHUB_ACTIONS === 'true') {
721
+ const annotations = versionSkewAnnotations(result);
722
+ if (annotations.length > 0) {
723
+ (options.output !== undefined ? process.stdout : process.stderr).write(`${annotations.join('\n')}\n`);
724
+ }
725
+ const summaryFile = process.env.GITHUB_STEP_SUMMARY;
726
+ const summaryLines = versionSkewSummaryLines(result);
727
+ if (summaryFile !== undefined && summaryFile !== '' && summaryLines.length > 0) {
728
+ try {
729
+ appendFileSync(summaryFile, summaryLines.map((line) => `${line}\n\n`).join(''));
730
+ }
731
+ catch {
732
+ // The annotation and the log line above already say it.
733
+ }
734
+ }
735
+ }
711
736
  process.exitCode = applyAdvisory(result.exitCode, advisory);
712
737
  }
713
738
  catch (err) {
@@ -21,7 +21,13 @@ export type Subject = {
21
21
  manifest: string;
22
22
  lockfile?: string;
23
23
  }
24
- /** `column` and `endColumn` are 1-based here even where the source is 0-based. */
24
+ /**
25
+ * `column` and `endColumn` are 1-based here even where the source is
26
+ * 0-based (SARIF 2.1.0 sets a minimum of 1 on both). The gitleaks
27
+ * normalizer enforces it: a column below 1 becomes 1, and an `endColumn`
28
+ * is kept only when it is at least `column` and on the same line.
29
+ * vault-guard's is its 0-based column plus one, with no `endColumn`.
30
+ */
25
31
  | {
26
32
  kind: 'location';
27
33
  file: string;
@@ -2,7 +2,7 @@ import type { Diagnostic, Finding, RunSummary } from './envelope.js';
2
2
  import type { ContractSource, IntentPreparation } from './intent-prepare.js';
3
3
  import type { GatePolicy, GateRole, GateStage, Product } from './policy.js';
4
4
  import { type BaseComparison } from './osv-baseline.js';
5
- import type { ResolvedBinary } from './resolve.js';
5
+ import type { ResolutionSource, ResolvedBinary } from './resolve.js';
6
6
  export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing' | 'spawn-failed' | 'gate-error' | 'unparseable-output'
7
7
  /**
8
8
  * The gate was never spawned because the run could not be set up for it:
@@ -58,7 +58,22 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
58
58
  * Raised for the version probe, the scan, and the intent gate's
59
59
  * preparation steps; `timedOut.step` says which spawn was stopped.
60
60
  */
61
- | 'timed-out';
61
+ | 'timed-out'
62
+ /**
63
+ * The vulnerabilities gate on a decided trust base: a handed lockfile read
64
+ * no packages at the head, or a base lockfile is gone from the head with
65
+ * no populated replacement in its directory, and the base copy had
66
+ * packages, so the dependency set the head removed cannot be judged.
67
+ * Fail closed by design
68
+ * (docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md).
69
+ */
70
+ | 'lockfile-emptied'
71
+ /**
72
+ * The same check could not clear the head: a base copy unreadable, a base
73
+ * run that failed or printed no count, a command-line mismatch, or a head
74
+ * run whose stderr carries no package count (a lowered verbosity).
75
+ */
76
+ | 'lockfile-emptied-unverified';
62
77
  /** Where a gate's time limit came from: the test hook, the policy, or the product default. */
63
78
  export type TimeLimitSource = 'override' | 'policy' | 'default';
64
79
  export interface TimeLimit {
@@ -66,7 +81,7 @@ export interface TimeLimit {
66
81
  source: TimeLimitSource;
67
82
  }
68
83
  /** Which of a gate's spawns was stopped at the limit. The intent gate's check is `scan`. */
69
- export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze';
84
+ export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze' | 'base-check';
70
85
  export interface TimedOut {
71
86
  step: TimedOutStep;
72
87
  limitSeconds: number;
@@ -308,15 +323,25 @@ export interface GateOutcome {
308
323
  */
309
324
  nodeModulesSkipped?: string;
310
325
  /**
311
- * Present only when this gate was resolved from PATH, the version it
312
- * reported differs from the one the run was told to expect (the Action's
313
- * pin, handed over as an environment variable), and both are known. A
314
- * statement for a warning, never an input to a decision: resolution,
315
- * trust-base handling and the exit code are all settled without it.
326
+ * Present only when the version this gate reported differs from the one
327
+ * the run was told to expect (the Action's pin, handed over as an
328
+ * environment variable), and both are known, WHEREVER the binary was
329
+ * resolved from. A statement for a warning, never an input to a decision:
330
+ * resolution, trust-base handling and the exit code are all settled
331
+ * without it.
332
+ *
333
+ * Every location, not only PATH (audit 2026-10-18, the intent-guard
334
+ * audit's MB3). Outside a pull request a repository's own devDependency in
335
+ * node_modules/.bin outranks the Action's global install by design, and
336
+ * recording PATH alone left every guard repository's own push runs on
337
+ * stale gates with the pins set and nothing said. `path` is
338
+ * repository-relative when the binary is inside the repository (it
339
+ * reaches a published log through the reports), and absolute otherwise.
316
340
  */
317
341
  versionSkew?: {
318
342
  expected: string;
319
343
  found: string;
344
+ source: ResolutionSource;
320
345
  path: string;
321
346
  };
322
347
  /**
@@ -347,8 +372,9 @@ export interface GateOutcome {
347
372
  export interface RunGateOptions {
348
373
  /**
349
374
  * The version this run expects of the gate, when something says so (the
350
- * Action passes its pin). Compared with what the PATH binary reports, for a
351
- * warning only. Absent means no expectation, which is every local run.
375
+ * Action passes its pin). Compared with what the resolved binary reports,
376
+ * wherever it was found, for a warning only. Absent means no expectation,
377
+ * which is every local run.
352
378
  */
353
379
  expectedVersion?: string;
354
380
  repoRoot: string;