@vaultcompass/conductor 0.13.2 → 0.15.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
@@ -168,7 +168,7 @@ required.
168
168
  A commit with a staged credential in it prints the full report and exits 1:
169
169
 
170
170
  ```
171
- conductor 0.13.2
171
+ conductor 0.15.0
172
172
  verdict-token: blocked (1)
173
173
  conductor run: 2 gate(s), 1 finding(s)
174
174
 
@@ -786,7 +786,10 @@ merged by someone allowed to merge without this check passing. A `.guardrails.ya
786
786
  pull request never takes effect for that run, `command:` and `args:`
787
787
  included, so **a pull request cannot change the rules it is judged by, and
788
788
  cannot choose the program that judges it, as long as that program is
789
- self-contained** (see the directory rule below). The same ref is passed
789
+ self-contained** (see the directory rule below). "The program" includes a
790
+ script handed to an interpreter: with `command: /usr/bin/node` and
791
+ `args: [tools/gate/run.mjs]`, the script is what judges, and it is vetted
792
+ exactly as a `command:` inside the tree would be. The same ref is passed
790
793
  down to every gate that supports it, so their contracts, configs and
791
794
  baselines come from the base branch too.
792
795
 
@@ -863,6 +866,61 @@ the message says to give it a directory: at the root the containing directory
863
866
  is the whole repository, so the rule would mean "no pull request may change
864
867
  anything".
865
868
 
869
+ **In-tree script arguments are vetted too.** Since 0.15.0 every entry of a
870
+ gate's `args:` that names something inside the working tree goes through the
871
+ same rule as the program, because an interpreter `command:` (Node, Python, a
872
+ shell) takes the program it runs as an argument. Before that, a base policy
873
+ of `command: /usr/bin/node` with `args: [tools/gate/run.mjs, scan]` let a
874
+ pull request rewrite `tools/gate/run.mjs` and report itself clean. Exactly
875
+ what counts:
876
+
877
+ - An entry is resolved against the repository root. Everything an
878
+ interpreter could load for it is vetted: the entry as written, and every
879
+ `<entry>.js`, `.mjs`, `.cjs`, `.json` or `.node` beside it, with or
880
+ without a slash. Node loads `tools/gate.js` before the directory
881
+ `tools/gate/`, and runs `run.js` for a bare `run`, so a sibling file the
882
+ pull request adds is refused because the base does not have it.
883
+ - A file (or a symbolic link) must meet the two conditions above; a
884
+ directory must have the same tree object id at the base and the head; the
885
+ repository root itself (`.`) is refused, since conductor already hands
886
+ each gate the repository it scans. A directory's `package.json` `main`
887
+ that points outside the directory is not vetted.
888
+ - `--name=value` is read for the value, so `--config=tools/gate/rules.json`
889
+ and `--import=./tools/gate/hook.mjs` are vetted. An option with no `=` and
890
+ a word that names nothing on disk are not paths and are never refused.
891
+ - The gate's own subcommand words (`scan`, `git`, `source`, `check`) are not
892
+ read as paths only when `command:` is the gate itself (its file name is
893
+ the gate's name, such as a vendored `vault-guard`). For an interpreter
894
+ they are paths like any other word: `node scan` runs `scan/index.js`.
895
+ A renamed gate binary, or any wrapper whose name is not a gate name, is
896
+ treated as an interpreter, so its `scan` or `source` is vetted if a file
897
+ or directory of that name exists, and a pull request touching it is
898
+ refused.
899
+ - Not recognised as a path, and **not** vetted: a Python `-m` module name, a
900
+ bare package name an interpreter resolves for itself, code passed as a
901
+ string (`node -e`, `bash -c`), and a package runner such as `npx`, which
902
+ resolves the gate from the head's own `node_modules`. Name the script by
903
+ its path, and do not run a gate through a package runner on pull requests.
904
+ - The sibling extensions tried are Node's (`.js`, `.mjs`, `.cjs`, `.json`,
905
+ `.node`). A TypeScript runner such as `tsx`, `ts-node` or `bun` also
906
+ resolves `.ts`, `.mts` and `.cts`, which are not tried, so name a
907
+ TypeScript script with its extension (`tools/gate/run.ts`, not
908
+ `tools/gate/run`).
909
+ - A script outside the working tree is accepted, as a program there is.
910
+
911
+ The version probe asks the script, not the interpreter: the args up to the
912
+ first non-option entry, when that entry names something loadable, then
913
+ `--version`, so `node tools/gate/run.mjs scan` is asked `node
914
+ tools/gate/run.mjs --version` and `node tools/gate` is asked `node
915
+ tools/gate --version`. The version conductor reports and checks against an
916
+ expected-version pin is then the gate's own. When the first non-option
917
+ entry names nothing loadable, or the command is the gate itself, the probe
918
+ is the command's own. One shape still reports the interpreter's version: a
919
+ flag that takes a file as its own entry before the script (`node -r
920
+ ./setup.js tools/gate/run.mjs`) makes `./setup.js` the first entry, so the
921
+ probe is `node -r ./setup.js --version`; under an expected-version pin that
922
+ gate is could-not-run. Write `--require=./setup.js` instead.
923
+
866
924
  A symlink inside the repository is refused on **its own entry**, before its
867
925
  target is considered: it is either untracked, or its tree entry is a link
868
926
  rather than a regular file, and either refuses. (A symlink whose own path is
@@ -889,7 +947,11 @@ branch first, like any other rule change.
889
947
  **A change to the rules is not refused, it is proposed.** Rules legitimately
890
948
  change, and a gate that blocked every such pull request would train people to
891
949
  bypass it. So a policy file that differs from the base ref's is reported as
892
- one line, `policy changed in this pull request`, the run continues under the
950
+ one line per changed key, `policy: gates.<role>.<key> <old> -> <new>`, counted
951
+ as one proposal each; a head `.guardrails.yaml` that is absent or does not
952
+ parse gives one line saying its changes are not known, and when no effective
953
+ key differs (a default spelled out, or the YAML reordered) the old single line,
954
+ `policy changed in this pull request`, is kept. The run continues under the
893
955
  base ref's rules, and the change takes effect **after merge**, on the first
894
956
  run whose base branch carries it. The gates' own proposals are summed with it
895
957
  into one sentence, `N control change(s) proposed in this pull request`, on the
@@ -1124,6 +1186,58 @@ on the base; it shows up as a proposal line in the report instead. To preview
1124
1186
  a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
1125
1187
  conductor" above.
1126
1188
 
1189
+ Where the proposals appear under the Action: the job log gets a
1190
+ `conductor: N control change(s) proposed in this pull request.` line followed
1191
+ by one `conductor: proposed <product> <line>` line per proposal, and the step
1192
+ summary gets the same count and up to 50 proposed lines under `control
1193
+ changes:` in a text block, with a `(n more in the report)` line when there are
1194
+ more. This does not depend on `pr-comment`. A proposed line that holds a
1195
+ backtick or a character outside printable ASCII is replaced by a placeholder.
1196
+
1197
+ ### The preview under the proposed rules
1198
+
1199
+ A pull request that switches a gate on or off, or moves its `stage`, is judged
1200
+ under the base's rules, so the author would not otherwise see what the
1201
+ proposed rules say until after merge. With the preview, each role whose
1202
+ `enabled` or `stage` changed runs once more (a role the head switches off is skipped), after the verdict, under the base
1203
+ policy with only `enabled`, `stage` and `enforce` taken from the head. Every
1204
+ other head value, `command:`, `args:`, `options` and `timeout-seconds`
1205
+ included, never reaches it: the base's command and the base's limit are what
1206
+ run, and a base `command:` that resolves inside the working tree is refused
1207
+ there, as is a base `args:` entry that names a path inside it (an
1208
+ interpreter's script). A gate's own config is another matter: in the preview, dep-guard and
1209
+ vault-guard read their own `.dep-guard.json` and `.vault-guard.json` from the
1210
+ head, because previewing the proposed rules means their rules too, while
1211
+ gitleaks and osv-scanner keep the base's config. osv-scanner call analysis is
1212
+ refused in the preview, because it would build the head's code. The intent
1213
+ gate is deferred and not previewed.
1214
+
1215
+ **The preview decides nothing.** The exit code, the verdict token and the SARIF
1216
+ results are those of the run under the base rules, whatever the preview finds
1217
+ or however it fails. In the full report (`--verbose`, the form the Action
1218
+ reads) the first four lines are untouched; in the one-line clean form the
1219
+ primary report is a byte-for-byte prefix and the preview follows it. It prints after
1220
+ the verdict under `Preview under the proposed rules (does not affect the
1221
+ verdict)`, as `conductor: preview ...` lines in the job log, as note-level
1222
+ `conductor/preview-under-proposed-rules` notifications on the umbrella's SARIF
1223
+ run, and as one `preview: N gate(s), M finding(s), K could-not-run` line in
1224
+ the step summary. The whole preview has a hard deadline of 300 seconds; a
1225
+ gate reached with no budget left is listed as over budget, and one that starts and is killed at the deadline is could-not-run (timed-out). A gate section in the preview
1226
+ uses the same words as a primary section, so a finding may read `BLOCKING`
1227
+ there: it means the finding would block under the proposed rules, and it does
1228
+ not affect this run. A pull-request comment is cut at 60000 characters, the
1229
+ preview block first. Every character outside printable ASCII in the preview
1230
+ (in the report, the job log and the SARIF notes) is written as a `\uXXXX`
1231
+ escape, because a gate there can read text the head chose, a
1232
+ right-to-left override in a pattern name included. The primary text report
1233
+ escapes finding file paths the same way, since a pull request names its own
1234
+ files; other primary gate text, and every path in the SARIF log, is printed
1235
+ as the gate gave it.
1236
+
1237
+ Ask for it with `--preview` on `conductor run`, or with the Action's `preview`
1238
+ input, which defaults to `true`; any other value turns it off. There is no
1239
+ preview when the head `.guardrails.yaml` does not parse.
1240
+
1127
1241
  ## Intent at a pull request
1128
1242
 
1129
1243
  The intent gate is the only one of the five with any ceremony: its native
@@ -1420,7 +1534,7 @@ request being judged, and the version-pin protection described above
1420
1534
  "protects nothing" against a tree that controls its own judge (the
1421
1535
  validate step's own comment in `action.yml` says so in those words). A tag
1422
1536
  moves when someone pushes it. Name this action by owner and the full commit
1423
- SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.13.2.
1537
+ SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.15.0.
1424
1538
 
1425
1539
  ```yaml
1426
1540
  name: guardrails
@@ -1440,9 +1554,9 @@ jobs:
1440
1554
  fetch-depth: 0
1441
1555
  - uses: actions/setup-node@v7
1442
1556
  with:
1443
- node-version: '22.11.0'
1557
+ node-version: '22.23.4'
1444
1558
  - id: conductor
1445
- uses: vaultcompasshq/conductor@v0.13.2
1559
+ uses: vaultcompasshq/conductor@v0.15.0
1446
1560
  with:
1447
1561
  output: conductor.sarif
1448
1562
  - uses: github/codeql-action/upload-sarif@v3
@@ -1505,8 +1619,10 @@ jobs:
1505
1619
  # Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
1506
1620
  # refuses because that client reports a clean install as tampered
1507
1621
  # with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
1508
- # can verify.
1509
- node-version: '22.11.0'
1622
+ # can verify. 22.23.4 is the patched release this repository's own
1623
+ # release job pins after the 2026-10-21 Node security release; the
1624
+ # gates run over pull-request content under whatever Node you pick.
1625
+ node-version: '22.23.4'
1510
1626
  # NOTHING FROM THE PULL REQUEST RUNS BEFORE THE ACTION IN THIS JOB.
1511
1627
  # No `pnpm install`, `npm ci`, build or test step: an install runs the
1512
1628
  # repository's own lifecycle scripts (a root postinstall), and that code
@@ -1517,7 +1633,7 @@ jobs:
1517
1633
  # installs those itself, globally. Leave conductor-version unset so the
1518
1634
  # umbrella is the default in the pinned action.yml.
1519
1635
  - id: conductor
1520
- uses: vaultcompasshq/conductor@v0.13.2
1636
+ uses: vaultcompasshq/conductor@v0.15.0
1521
1637
  with:
1522
1638
  output: conductor.sarif
1523
1639
  # Exact versions, never a range and never "latest". These three
@@ -1528,9 +1644,9 @@ jobs:
1528
1644
  # request of their own. On a pull request the action refuses a pin
1529
1645
  # below what the pinned action.yml ships, and the three lines can
1530
1646
  # be left out entirely to take that action's own versions.
1531
- dep-guard-version: 0.16.1
1647
+ dep-guard-version: 0.17.0
1532
1648
  vault-guard-version: 1.12.1
1533
- intent-guard-version: 1.10.1
1649
+ intent-guard-version: 1.10.2
1534
1650
  - uses: github/codeql-action/upload-sarif@v3
1535
1651
  # Always: the log is most worth having on the run that failed.
1536
1652
  if: always()
@@ -1554,7 +1670,7 @@ jobs:
1554
1670
  - uses: pnpm/action-setup@v4
1555
1671
  - uses: actions/setup-node@v7
1556
1672
  with:
1557
- node-version: '22.11.0'
1673
+ node-version: '22.23.4'
1558
1674
  cache: pnpm
1559
1675
  - run: pnpm install --frozen-lockfile
1560
1676
  - run: pnpm test
@@ -1698,7 +1814,12 @@ caused that; `continue-on-error` is the thing that let it happen, so the two
1698
1814
  do not belong in the same recipe. Set a step `timeout-minutes` as well: the
1699
1815
  Action already caps each gate's own subprocess at 120 seconds and reports one
1700
1816
  that exceeds it as could-not-run, so the timeout is an outer bound around the
1701
- whole run rather than the primary control.
1817
+ whole run rather than the primary control. Make it at least what the primary
1818
+ run needs plus 300 seconds (5 minutes), because the preview under the
1819
+ proposed rules can use up to that much on a pull request that changes a
1820
+ gate's `enabled` or `stage`; a step killed mid-preview has no verdict. Check
1821
+ out with `persist-credentials: false` so the gates never run with a token
1822
+ left in the checkout's git config.
1702
1823
 
1703
1824
  A complete copy-paste job, rather than the one step above in isolation:
1704
1825
 
@@ -1718,12 +1839,14 @@ jobs:
1718
1839
  # From 0.8.0 a shallow checkout on a pull-request run is
1719
1840
  # could-not-run for the history gate.
1720
1841
  fetch-depth: 0
1842
+ persist-credentials: false
1721
1843
  - uses: actions/setup-node@v7
1722
1844
  with:
1723
- node-version: '22.11.0'
1845
+ node-version: '22.23.4'
1724
1846
  - id: conductor
1725
- timeout-minutes: 5
1726
- uses: vaultcompasshq/conductor@v0.13.2
1847
+ # The primary run's need (here 5 minutes) plus 300 seconds.
1848
+ timeout-minutes: 10
1849
+ uses: vaultcompasshq/conductor@v0.15.0
1727
1850
  with:
1728
1851
  pr-comment: true
1729
1852
  advisory: true
@@ -1859,7 +1982,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1859
1982
  # the pull request runs before the action in this job: no install, build
1860
1983
  # or test step here; those belong in a separate job. ...
1861
1984
  - id: conductor
1862
- uses: vaultcompasshq/conductor@v0.13.2
1985
+ uses: vaultcompasshq/conductor@v0.15.0
1863
1986
  with:
1864
1987
  output: conductor.sarif
1865
1988
  pr-comment: true
@@ -1938,12 +2061,12 @@ per pull request.
1938
2061
 
1939
2062
  ```yaml
1940
2063
  - id: conductor-package-a
1941
- uses: vaultcompasshq/conductor@v0.13.2
2064
+ uses: vaultcompasshq/conductor@v0.15.0
1942
2065
  with:
1943
2066
  pr-comment: true
1944
2067
  pr-comment-marker: 'package-a'
1945
2068
  - id: conductor-package-b
1946
- uses: vaultcompasshq/conductor@v0.13.2
2069
+ uses: vaultcompasshq/conductor@v0.15.0
1947
2070
  with:
1948
2071
  pr-comment: true
1949
2072
  pr-comment-marker: 'package-b'
@@ -2064,7 +2187,7 @@ an explicit pin is unaffected, which is how a stale pin can sit unnoticed
2064
2187
  until the first pull request after the upgrade.
2065
2188
 
2066
2189
  **Pin the action ref to a full commit SHA** with the tag as a comment, for
2067
- example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.13.2`. To
2190
+ example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.15.0`. To
2068
2191
  find the SHA for a tag, run
2069
2192
  `gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
2070
2193
  the Releases page.
@@ -2087,6 +2210,8 @@ tag with no row here has an entry that does not state its defaults; read
2087
2210
 
2088
2211
  | Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
2089
2212
  | --- | --- | --- | --- |
2213
+ | v0.15.0 | package | 0.15.0 | dep-guard 0.17.0 (from 0.16.1), intent-guard 1.10.2 (from 1.10.1) |
2214
+ | v0.14.0 | package | 0.14.0 | none (gate defaults unchanged) |
2090
2215
  | v0.13.2 | package | 0.13.2 | none (gate defaults unchanged) |
2091
2216
  | v0.13.1 | action-only | 0.13.0 | dep-guard 0.16.1 (from 0.15.0) |
2092
2217
  | v0.13.0 | package | 0.13.0 | none (gate defaults unchanged) |
package/dist/cli.d.ts CHANGED
@@ -1,9 +1,47 @@
1
1
  #!/usr/bin/env node
2
2
  import { Command } from 'commander';
3
+ import type { CliOverrides, Policy } from './policy.js';
4
+ import type { RunTrustBase } from './run.js';
3
5
  /**
4
6
  * Whether the text report is rendered for a terminal: only when it goes to
5
7
  * stdout (no --output) and stdout is a TTY. A file, a pipe and the
6
8
  * --text-report copy never are, so they stay byte for byte as before.
7
9
  */
8
10
  export declare function rendersToTerminal(output: string | undefined, stdoutIsTTY: boolean | undefined): boolean;
11
+ /**
12
+ * The policy for one run, and where it came from.
13
+ *
14
+ * Two shapes rather than one, because a run that could not use its trust base
15
+ * is not a run with a different policy: it is a run with NO policy, and it
16
+ * has to report every enabled gate as could-not-run rather than fall back to
17
+ * the head's file.
18
+ */
19
+ type PolicyForRun = {
20
+ kind: 'policy';
21
+ policy: Policy;
22
+ trustBase?: RunTrustBase;
23
+ /**
24
+ * The policy of the preview under the proposed rules, built here from
25
+ * the parsed head, which itself is never returned. Null without a trust
26
+ * base, when the head does not parse, and when no role's `enabled` or
27
+ * `stage` changed.
28
+ */
29
+ previewPolicy: Policy | null;
30
+ }
31
+ /** The trust base could not be judged against. `inventory` only names gates. */
32
+ | {
33
+ kind: 'refused';
34
+ ref: string;
35
+ detail: string;
36
+ inventory: Policy;
37
+ notGiven?: boolean;
38
+ };
39
+ /**
40
+ * Exported so a test can see that no preview policy is built unless one was
41
+ * asked for (`preview`): a run without --preview never reaches that code.
42
+ */
43
+ export declare function policyForRun(root: string, trustBase: string | undefined, overrides: CliOverrides, githubBaseRef: string | undefined, githubActions: string | undefined,
44
+ /** Whether this run asked for the preview under the proposed rules. */
45
+ preview?: boolean): PolicyForRun;
9
46
  export declare function buildProgram(): Command;
47
+ export {};
package/dist/cli.js CHANGED
@@ -14,8 +14,9 @@ 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, versionSkewAnnotations, versionSkewSummaryLines, versionSkewWarnings, } from './output-text.js';
17
+ import { gateLogLines, jobLogSummary, previewLogLines, proposalLogLines, 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
+ import { diffPolicies, previewPolicy, previewRoles } from './policy-diff.js';
19
20
  import { refusedTrustBase, runAll } from './run.js';
20
21
  import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
21
22
  const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
@@ -244,7 +245,13 @@ function inventoryFromHead(root, overrides) {
244
245
  return { version: 1, gates: {}, report: { format: 'text' } };
245
246
  }
246
247
  }
247
- function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions) {
248
+ /**
249
+ * Exported so a test can see that no preview policy is built unless one was
250
+ * asked for (`preview`): a run without --preview never reaches that code.
251
+ */
252
+ export function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions,
253
+ /** Whether this run asked for the preview under the proposed rules. */
254
+ preview = false) {
248
255
  if (trustBase === undefined) {
249
256
  // A PULL-REQUEST JOB WITH NO TRUST BASE would take its rules from the
250
257
  // tree being judged. In Actions (GITHUB_ACTIONS and GITHUB_BASE_REF both
@@ -269,7 +276,11 @@ function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions)
269
276
  process.stderr.write(`conductor: ${why} Outside GitHub Actions the run goes on with the working tree policy; ` +
270
277
  'in Actions it is refused. Pass --trust-base for pull-request mode.\n');
271
278
  }
272
- return { kind: 'policy', policy: applyCliOverrides(loadPolicy(root), overrides) };
279
+ return {
280
+ kind: 'policy',
281
+ policy: applyCliOverrides(loadPolicy(root), overrides),
282
+ previewPolicy: null,
283
+ };
273
284
  }
274
285
  // DEFENCE IN DEPTH, ISSUE #58. action.yml's validate step already refuses
275
286
  // an explicit trust-base input outright on a pull_request event; this is
@@ -351,15 +362,42 @@ function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions)
351
362
  inventory: inventoryFromHead(root, overrides),
352
363
  };
353
364
  }
365
+ // Parsed once, before applyCliOverrides, so a --gate override never shows up
366
+ // as a policy change. The parsed head is never handed to a run: the
367
+ // comparison reads it, and the preview policy below takes only enabled,
368
+ // stage and enforce from it.
369
+ const baseParsed = parsePolicy(baseText, `${trustBase}:${POLICY_FILE_NAME}`);
370
+ const policyChanged = headRead.kind === 'error' ? true : policyDiffers(baseText, headText);
371
+ let headPolicy = null;
372
+ if (headText !== null) {
373
+ try {
374
+ headPolicy = parsePolicy(headText, `HEAD:${POLICY_FILE_NAME}`);
375
+ }
376
+ catch (error) {
377
+ if (!(error instanceof PolicyError))
378
+ throw error;
379
+ }
380
+ }
381
+ // The preview under the proposed rules: only the roles whose enabled or
382
+ // stage the head changes, and only enabled, stage and enforce from the
383
+ // head (previewPolicy). A head that does not parse gets none (spec 5.2,
384
+ // finding 8). The same --gate overrides, restricted to the roles the
385
+ // preview holds: a --gate role it does not hold leaves its roles excluded.
386
+ // Built only when the run asked for a preview, so nothing here can fail a
387
+ // run that did not.
388
+ const roles = !preview || headPolicy === null ? [] : previewRoles(diffPolicies(baseParsed, headPolicy));
389
+ const proposed = headPolicy === null || roles.length === 0 ? null : previewPolicy(baseParsed, headPolicy, roles);
354
390
  return {
355
391
  kind: 'policy',
356
- policy: applyCliOverrides(parsePolicy(baseText, `${trustBase}:${POLICY_FILE_NAME}`), overrides),
392
+ policy: applyCliOverrides(baseParsed, overrides),
393
+ previewPolicy: proposed === null ? null : previewWithOverrides(proposed, overrides),
357
394
  trustBase: {
358
395
  ref: trustBase,
359
396
  // A head file git could not read is reported as a change, the
360
397
  // fail-closed direction: it is never taken to match the base.
361
- policyChanged: headRead.kind === 'error' ? true : policyDiffers(baseText, headText),
398
+ policyChanged,
362
399
  refusal: null,
400
+ ...(policyChanged ? { policyChanges: diffPolicies(baseParsed, headPolicy) } : {}),
363
401
  // Computed AFTER refuseTrustBaseRef has already returned null, on the
364
402
  // one shape that check accepts despite an identical tree: a merge
365
403
  // commit whose first parent is this ref (issue #69). runAll reads this
@@ -369,6 +407,27 @@ function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions)
369
407
  },
370
408
  };
371
409
  }
410
+ /**
411
+ * The --gate overrides on the preview policy. Restricted to the roles it
412
+ * holds, so a --gate role it does not hold leaves its roles excluded rather
413
+ * than throwing. And a role the head switched off stays off: applyCliOverrides
414
+ * turns a named role on, and the preview of a role switched off is not a run
415
+ * of it, so runPreview lists it as disabled.
416
+ */
417
+ function previewWithOverrides(preview, overrides) {
418
+ if (overrides.gates === undefined) {
419
+ return preview;
420
+ }
421
+ const applied = applyCliOverrides(preview, {
422
+ ...overrides,
423
+ gates: overrides.gates.filter((role) => preview.gates[role] !== undefined),
424
+ });
425
+ const gates = {};
426
+ for (const [role, gate] of Object.entries(applied.gates)) {
427
+ gates[role] = preview.gates[role]?.enabled === false ? { ...gate, enabled: false, excludedByCli: false } : gate;
428
+ }
429
+ return { ...applied, gates };
430
+ }
372
431
  /**
373
432
  * On a run with a trust base: removes every PATH entry that resolves against
374
433
  * the working directory, for this process and for every child it starts,
@@ -569,6 +628,7 @@ export function buildProgram() {
569
628
  .command('run')
570
629
  .description('Run every enabled gate and print one combined report.')
571
630
  .option('--staged', 'gate the git index against HEAD, the way the pre-commit hook does')
631
+ .option('--preview', 'pull-request mode only: when the pull request changes a gate\'s enabled or stage, run those gates once more under the proposed values, as a preview that never changes the exit code or the verdict. Every other policy key still comes from the base ref, and so do the gitleaks and osv-scanner configs; dep-guard and vault-guard read their own config files from the head. Not on --staged.')
572
632
  .option('--format <format>', 'output format: text or sarif')
573
633
  .option('--stage <stage>', `which stopping point this run is: ${GATE_STAGES.join(', ')}. Stages are cumulative, so a gate runs at its own stage and every later one. Omit it to run every enabled gate.`)
574
634
  .option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base branch (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
@@ -613,7 +673,7 @@ export function buildProgram() {
613
673
  : { gates: parseRoles(options.gate) }),
614
674
  };
615
675
  const stage = parseStage(options.stage);
616
- const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF, process.env.GITHUB_ACTIONS);
676
+ const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF, process.env.GITHUB_ACTIONS, options.preview === true && options.staged !== true);
617
677
  const policy = source.kind === 'policy' ? source.policy : source.inventory;
618
678
  const format = parseFormat(options.format ?? policy.report.format);
619
679
  // BEFORE ANY GATE RUNS. With --format text the text report already is
@@ -638,6 +698,15 @@ export function buildProgram() {
638
698
  ...(options.base === undefined ? {} : { base: options.base }),
639
699
  ...(options.spec === undefined ? {} : { spec: options.spec }),
640
700
  ...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
701
+ // Only on request, never on --staged, and only with a trust
702
+ // base and a preview policy: a head that parsed and changed
703
+ // at least one role's enabled or stage.
704
+ ...(options.preview === true &&
705
+ options.staged !== true &&
706
+ source.trustBase !== undefined &&
707
+ source.previewPolicy !== null
708
+ ? { preview: { policy: source.previewPolicy } }
709
+ : {}),
641
710
  });
642
711
  const advisory = Boolean(options.advisory);
643
712
  // SARIF carries no verdict line, so --advisory has nothing to say
@@ -703,6 +772,8 @@ export function buildProgram() {
703
772
  // for an unwritable file.
704
773
  const logLines = [
705
774
  ...gateLogLines(result, process.stderr.isTTY === true ? { terminal: true } : {}),
775
+ ...proposalLogLines(result),
776
+ ...previewLogLines(result),
706
777
  ...versionSkewWarnings(result),
707
778
  ];
708
779
  if (logLines.length > 0) {
@@ -87,8 +87,12 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
87
87
  * run whose stderr carries no package count (a lowered verbosity).
88
88
  */
89
89
  | 'lockfile-emptied-unverified';
90
- /** Where a gate's time limit came from: the test hook, the policy, or the product default. */
91
- export type TimeLimitSource = 'override' | 'policy' | 'default';
90
+ /**
91
+ * Where a gate's time limit came from: the test hook, the policy, the product
92
+ * default, or, in the preview under the proposed rules, what was left of the
93
+ * preview's own budget when that was the smaller limit.
94
+ */
95
+ export type TimeLimitSource = 'override' | 'policy' | 'default' | 'preview-budget';
92
96
  export interface TimeLimit {
93
97
  ms: number;
94
98
  source: TimeLimitSource;
@@ -285,6 +289,12 @@ export interface GateTrustBase {
285
289
  /** The control-input changes this gate reported as proposed. */
286
290
  proposals: string[];
287
291
  }
292
+ /**
293
+ * Why dep-guard and vault-guard are not handed `--trust-base` in the preview
294
+ * under the proposed rules: the preview shows what the head's rules would do,
295
+ * and their own control files are part of those rules.
296
+ */
297
+ export declare const PREVIEW_WITHHELD = "preview under the proposed rules: this gate read its own control files from the head";
288
298
  /**
289
299
  * Whether this gate can be handed `--trust-base`, and why not when it cannot.
290
300
  *
@@ -299,7 +309,14 @@ export interface GateTrustBase {
299
309
  * was working a moment ago would report could-not-run. So the flag goes only
300
310
  * where `--project` is the repository itself.
301
311
  */
302
- export declare function decideTrustBase(gate: GatePolicy, intent: IntentPreparation | undefined, trustBase: string | undefined, productVersion: string | null): GateTrustBase | undefined;
312
+ export declare function decideTrustBase(gate: GatePolicy, intent: IntentPreparation | undefined, trustBase: string | undefined, productVersion: string | null,
313
+ /**
314
+ * The preview under the proposed rules. dep-guard and vault-guard then read
315
+ * their own control files from the head, so the flag is withheld from them;
316
+ * the trust base itself stays set on the run, and every other product is
317
+ * decided exactly as without it.
318
+ */
319
+ preview?: boolean): GateTrustBase | undefined;
303
320
  export interface GateOutcome {
304
321
  role: GateRole;
305
322
  product: Product;
@@ -441,7 +458,34 @@ export interface RunGateOptions {
441
458
  * inject one so they can see that nothing is left behind.
442
459
  */
443
460
  tempRoot?: string;
461
+ /**
462
+ * Set only in the preview under the proposed rules. Every spawn of this
463
+ * gate then takes its timeout, kill signal and environment from
464
+ * `previewSpawnOptions`, and two refusals run before any spawn.
465
+ */
466
+ preview?: PreviewSpawn;
444
467
  }
468
+ /** The preview's hard deadline, its clock, and its private cache directory. */
469
+ export interface PreviewSpawn {
470
+ /** In the clock's own units (milliseconds): the whole preview ends here. */
471
+ deadline: number;
472
+ clock: () => number;
473
+ /** XDG_CACHE_HOME for every preview spawn, removed when the preview ends. */
474
+ cacheDir: string;
475
+ }
476
+ /** The smaller of a spawn's own limit and what is left of the preview budget, never negative. */
477
+ export declare function previewSpawnTimeout(limitMs: number, preview: PreviewSpawn): number;
478
+ /**
479
+ * The spawn options of every preview spawn: the timeout above, SIGKILL, so a
480
+ * child that traps SIGTERM cannot outlive the budget, and the spawn's own
481
+ * environment with XDG_CACHE_HOME pointed at the preview's private cache, so
482
+ * nothing the head's rules fetched persists on a shared runner.
483
+ */
484
+ export declare function previewSpawnOptions(limitMs: number, preview: PreviewSpawn, env: NodeJS.ProcessEnv): {
485
+ timeout: number;
486
+ killSignal: 'SIGKILL';
487
+ env: NodeJS.ProcessEnv;
488
+ };
445
489
  /**
446
490
  * A gate that never got as far as being spawned.
447
491
  *
@@ -475,6 +519,13 @@ export declare function preparationTimedOut(gate: GatePolicy, stopped: {
475
519
  * only the first left the probe free to spawn whatever the head put at the
476
520
  * second, and a probe RUNS a program as thoroughly as a scan does.
477
521
  *
522
+ * And every path the policy's `args:` name (`binary.argumentPaths`), because
523
+ * an interpreter `command:` takes the program as an argument: with `command:
524
+ * /usr/bin/node` and `args: [tools/gate/run.mjs]` the script judges, and
525
+ * vetting Node alone let a pull request rewrite the script (audit 2026-10-27,
526
+ * B1). The version probe's argv is a prefix of those same args, so it is
527
+ * covered by the same loop.
528
+ *
478
529
  * The first refusal wins and the rest is not consulted. The verdict is the
479
530
  * same either way, and the sentence a reader has to act on should name one
480
531
  * file rather than two.
@@ -554,7 +605,22 @@ external?: ExternalArgs,
554
605
  * For the intent gate on a prepared run: hand it this base with its own
555
606
  * `--base` in place of `--paths`. Decided by `intentChangeChannel`.
556
607
  */
557
- intentBase?: string): string[];
608
+ intentBase?: string,
609
+ /**
610
+ * dep-guard's `--base` when `trustBase` is withheld from it in the preview
611
+ * under the proposed rules: the change is still measured against the base
612
+ * ref, only the rules are the head's. Ignored when `trustBase` is set, and
613
+ * by every other product.
614
+ */
615
+ changeBase?: string,
616
+ /**
617
+ * True for a spawn of the preview under the proposed rules. osv-scanner
618
+ * then gets `--no-call-analysis=all` appended after the base's own options,
619
+ * whatever they say: call analysis builds the project it scans, which in
620
+ * the preview is the head's code, and osv-scanner applies its disables
621
+ * after its enables, so the appended flag wins.
622
+ */
623
+ preview?: boolean): string[];
558
624
  /**
559
625
  * The expected-version decision for the intent gate, made BEFORE its
560
626
  * preparation (residual 3, 2026-10-20).
@@ -596,3 +662,16 @@ export declare function runGate(gate: GatePolicy, options: RunGateOptions): Gate
596
662
  */
597
663
  /** The oldest git a history gate runs under on a pull-request run. */
598
664
  export declare const HISTORY_GIT_FLOOR = "2.31.0";
665
+ /**
666
+ * cleanOutputLine, then every remaining character outside printable ASCII
667
+ * escaped as \uXXXX (escapeNonAscii). For every preview line: there a gate
668
+ * reads the head's own control files, so a rule id or a message can be
669
+ * head-chosen text, a right-to-left override included (audit 2026-10-27,
670
+ * N3). cleanOutputLine alone breaks a workflow command and keeps the
671
+ * override. The primary run is NOT safe by the same argument: its rule ids
672
+ * come from base-approved config, but its file paths are the head's own
673
+ * names. So the primary text report escapes finding paths (subjectLabel,
674
+ * src/output-text.ts), and only those; a primary gate message or stderr
675
+ * excerpt that quotes a path keeps its characters, a known limit.
676
+ */
677
+ export declare function cleanPreviewLine(raw: string): string;