@vaultcompass/conductor 0.9.0 → 0.10.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
@@ -142,10 +142,9 @@ required.
142
142
 
143
143
  **`.guardrails/manifest.json` records the absolute path on the machine
144
144
  that ran `init`**, for the hook, when there is one, and for the policy
145
- file alike, and
146
- conductor does not add a `.gitignore` entry for it. That path is specific
147
- to your checkout, so do not commit the file: add
148
- `.guardrails/manifest.json` to your own `.gitignore` today. The file
145
+ file alike. That path is specific to your checkout, so do not commit the
146
+ file: init appends `.guardrails/` to `.gitignore` when git does not already
147
+ ignore it, and prints the line instead when it cannot append safely. The file
149
148
  lives inside your working tree so `--revert` can find it later, and
150
149
  recording repo-relative paths there instead of absolute ones is a known
151
150
  gap, not a design; it has not been fixed yet.
@@ -167,7 +166,7 @@ required.
167
166
  A commit with a staged credential in it prints the full report and exits 1:
168
167
 
169
168
  ```
170
- conductor 0.9.0
169
+ conductor 0.10.0
171
170
  verdict-token: blocked (1)
172
171
  conductor run: 2 gate(s), 1 finding(s)
173
172
 
@@ -435,6 +434,10 @@ that scans a requirements file always gets `--no-resolve`, and a
435
434
  `no-resolve` key here is dropped from that run with a note; and a
436
435
  pull-request run gets `--no-call-analysis=all` unless this block names
437
436
  `call-analysis` or `no-call-analysis`, in which case that value is used.
437
+ `timeout-seconds` is refused under `options` on every gate, and `timeout`
438
+ on every gate but gitleaks, where it is gitleaks' own `--timeout` flag and
439
+ is passed through (see `timeout-seconds` below and "What a history scan
440
+ costs").
438
441
 
439
442
  **`present-on-base`** (the `vulnerabilities` gate only, beside `enforce`,
440
443
  never under `options`) is `block` or `report`. On a pull-request run whose
@@ -450,6 +453,27 @@ local run, a push) has no labels, and every finding blocks. The key on any
450
453
  other gate is an error, and an older conductor rejects it, so move the
451
454
  Action first.
452
455
 
456
+ **`timeout-seconds`** (any gate, beside `enforce`, never under `options`)
457
+ is how long conductor lets that gate run before stopping it: a whole number
458
+ of seconds from 10 to 21600. The floor is there because the same limit
459
+ bounds the gate's version probe, and a limit of a second or two can stop the
460
+ probe of a gate that starts slowly before it ever scans. The ceiling is the
461
+ six hours after which a GitHub-hosted job is cancelled; a larger limit could
462
+ never fire there. Without the key each gate keeps the default for its
463
+ product: 120 seconds for dep-guard, vault-guard and intent-guard, 600 for
464
+ gitleaks, 300 for osv-scanner. There is no policy-wide default, for the same
465
+ reason there is no shared severity threshold: the five gates differ in cost
466
+ by orders of magnitude. Every spawn of the gate gets the full limit (the
467
+ version probe, the scan, the intent gate's preparation steps, osv-scanner's
468
+ base run on a pull request). A gate stopped at its limit could not run, with
469
+ the reason `timed-out` and what to do about it, and an enforced one makes
470
+ the run exit 2. On a pull request the key is read from the base branch's
471
+ policy like every other key, so a pull request cannot raise, lower or
472
+ remove its own limit; an invalid value on the base fails every pull request
473
+ with exit 2 until the base is fixed, and an invalid value only on the head
474
+ is a policy proposal there and fails the push run after merge. An older
475
+ conductor rejects the key, so move the Action first.
476
+
453
477
  **There is no shared severity threshold, on purpose.** One top-level
454
478
  `failOn` would read as one decision and mean five different things, so
455
479
  setting one is an error rather than a knob that half works. Each gate keeps
@@ -457,7 +481,11 @@ its own threshold in its own `options` block, spelled the way that gate
457
481
  spells it.
458
482
 
459
483
  **`command`** takes an absolute path and overrides binary resolution for
460
- that gate, for pointing at a build that is not installed anywhere.
484
+ that gate, for pointing at a build that is not installed anywhere. `args`
485
+ beside it sets the argument prefix. conductor's history gate assumes
486
+ gitleaks' `git` mode; an `args` that switches it to `dir` mode changes what
487
+ gitleaks' own `--timeout` does (in `dir` mode it exits 0 after a partial
488
+ scan, with no warning).
461
489
 
462
490
  **`report.format`** is `text` or `sarif`, and `--format` overrides it.
463
491
 
@@ -466,7 +494,14 @@ that gate, for pointing at a build that is not installed anywhere.
466
494
  `conductor init` writes the policy file and `.guardrails/manifest.json`, the
467
495
  record `--revert` reads back later. The manifest currently records absolute
468
496
  machine paths rather than repo-relative ones (see "Adopting conductor"
469
- above); do not commit it.
497
+ above); do not commit it. When git does not already ignore it, init appends
498
+ `.guardrails/` to `.gitignore` (or creates one) and says so; a `.gitignore`
499
+ that is a symbolic link or not a regular file is left alone and the line is
500
+ printed for you to add. On a policy file that already exists, init lists the
501
+ gate roles it has no entry for, with the two lines that add each. An external
502
+ gate (gitleaks, osv-scanner) is written enabled only when its binary is found
503
+ on the machine running init, with a comment under it that CI must install it;
504
+ a CI job without it gets `conductor/gate-missing` and exit 2.
470
505
 
471
506
  - `--hook` also writes one pre-commit hook running every enabled gate whose
472
507
  stage is `commit`. Without it, init writes only the policy file and the
@@ -478,7 +513,9 @@ above); do not commit it.
478
513
  `--hook` itself.
479
514
  - `--dry-run` prints every file it would write or change and writes nothing.
480
515
  - `--revert` removes exactly what a previous init wrote, and nothing else.
481
- A file changed since init is reported and left alone.
516
+ A file changed since init is reported and left alone. The one exception is
517
+ the `.guardrails/` line init appends to `.gitignore`: `--revert` does not
518
+ remove it.
482
519
  - `--adopt` replaces one gate's own pre-commit hook with the umbrella hook.
483
520
  Without it, init reports the collision and stops rather than stacking a
484
521
  second invocation of a gate that is already hooked. A hook the umbrella
@@ -505,7 +542,14 @@ and none of it can block the policy file from being written, on a plain
505
542
 
506
543
  Init recognises the hook manager already wired into the repository. husky is
507
544
  redirected to the tracked hook it maintains rather than the generated
508
- dispatcher git runs. lefthook and the pre-commit framework are refused, with
545
+ dispatcher git runs. On a fresh clone, where husky's install has not set
546
+ `core.hooksPath` yet, husky is recognised from `package.json` (a `husky`
547
+ dependency or devDependency, or a `prepare` script that runs husky) or a
548
+ tracked `.husky/` directory, and init writes `.husky/pre-commit` and says the
549
+ install still has to run, rather than writing `.git/hooks/pre-commit`, which
550
+ husky's install would bypass. This applies only when `core.hooksPath` is not
551
+ set at all: one set by hand, even to `.git/hooks`, is left alone. A prepare
552
+ script counts only when it runs husky as a command. lefthook and the pre-commit framework are refused, with
509
553
  the stanza to add to their own config file. simple-git-hooks and yorkie are
510
554
  refused too, and recognised from the declaration as well as from the hook
511
555
  file, because the declaration is there on a fresh clone where the generated
@@ -562,7 +606,13 @@ proceeds normally without mentioning them.
562
606
  copy in a file would only duplicate it. A path that cannot be written is
563
607
  exit 2, like `--output`. See "The verdict token" below.
564
608
  - `--verbose` prints the full per-gate report even when the run is clean.
565
- Text output only; the SARIF log never changes shape with it.
609
+ Text output only; the SARIF log never changes shape with it. Without it a
610
+ gate prints its first 20 findings, blocking first, and one line saying how
611
+ many more there are; every count, the verdict and SARIF include all of
612
+ them. `--verbose` also lists the lockfiles behind an osv-scanner line
613
+ that groups one advisory across several ("lodash@4.17.20 2 lockfiles
614
+ fix 4.17.21"). A gitleaks finding shows its short commit and the
615
+ fingerprint `.gitleaksignore` takes.
566
616
  - `--compact-on-refusal` shrinks the report to the version, the verdict and
567
617
  the refusal reason when the trust base was refused and no gate ran,
568
618
  instead of the full per-gate report. Built for the pull-request-comment
@@ -595,9 +645,10 @@ proceeds normally without mentioning them.
595
645
  - **0** every enabled gate ran and none blocked.
596
646
  - **1** every enabled gate ran and at least one blocked.
597
647
  - **2** an enabled gate could not run: its binary is missing, it exited with
598
- its own could-not-run code, or it exited 1 with nothing parseable on
648
+ its own could-not-run code, it exited 1 with nothing parseable on
599
649
  stdout, which is what a rejected config file looks like from two of the
600
- three family gates.
650
+ three family gates, or conductor stopped it at its time limit
651
+ (`timed-out`, see `timeout-seconds` in the policy file).
601
652
 
602
653
  The external gates' exits are read per tool. gitleaks exits 1 for an error
603
654
  as well as for a leak, so the umbrella hands it `--exit-code 3`: 3 is a leak
@@ -1307,7 +1358,7 @@ request being judged, and the version-pin protection described above
1307
1358
  "protects nothing" against a tree that controls its own judge (the
1308
1359
  validate step's own comment in `action.yml` says so in those words). A tag
1309
1360
  moves when someone pushes it. Name this action by owner and the full commit
1310
- SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.9.0.
1361
+ SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.10.0.
1311
1362
 
1312
1363
  ```yaml
1313
1364
  name: guardrails
@@ -1329,7 +1380,7 @@ jobs:
1329
1380
  with:
1330
1381
  node-version: '22.11.0'
1331
1382
  - id: conductor
1332
- uses: vaultcompasshq/conductor@v0.9.0
1383
+ uses: vaultcompasshq/conductor@v0.10.0
1333
1384
  with:
1334
1385
  output: conductor.sarif
1335
1386
  - uses: github/codeql-action/upload-sarif@v3
@@ -1404,7 +1455,7 @@ jobs:
1404
1455
  # installs those itself, globally. Leave conductor-version unset so the
1405
1456
  # umbrella is the default in the pinned action.yml.
1406
1457
  - id: conductor
1407
- uses: vaultcompasshq/conductor@v0.9.0
1458
+ uses: vaultcompasshq/conductor@v0.10.0
1408
1459
  with:
1409
1460
  output: conductor.sarif
1410
1461
  # Exact versions, never a range and never "latest". These three
@@ -1415,8 +1466,8 @@ jobs:
1415
1466
  # request of their own. On a pull request the action refuses a pin
1416
1467
  # below what the pinned action.yml ships, and the three lines can
1417
1468
  # be left out entirely to take that action's own versions.
1418
- dep-guard-version: 0.11.1
1419
- vault-guard-version: 1.10.0
1469
+ dep-guard-version: 0.13.0
1470
+ vault-guard-version: 1.11.0
1420
1471
  intent-guard-version: 1.8.1
1421
1472
  - uses: github/codeql-action/upload-sarif@v3
1422
1473
  # Always: the log is most worth having on the run that failed.
@@ -1513,6 +1564,61 @@ runs whatever its author pushes to it next. Pin every third-party action by
1513
1564
  commit digest in a workflow you actually run, the way this repository's own
1514
1565
  workflows do.
1515
1566
 
1567
+ ### What a history scan costs
1568
+
1569
+ What the history gate reads depends on the event. On a pull request it is
1570
+ `<base>..HEAD`, with first-parent diffs for merge commits; on a push, a
1571
+ schedule or a local run it is every commit reachable from HEAD. So a pull
1572
+ request's cost follows its own range, and a full run's cost follows the
1573
+ whole history and the size of every blob ever committed. Separately,
1574
+ `fetch-depth: 0` means the checkout fetches the whole history on every run,
1575
+ whatever the scan range.
1576
+
1577
+ The time limit is per gate. The defaults are 120 seconds for the three
1578
+ family gates, 600 for gitleaks and 300 for osv-scanner, and you change one
1579
+ with `timeout-seconds` beside `enforce`; on a pull request it comes from the
1580
+ base branch. Every spawn of a gate gets the full limit (the version probe,
1581
+ the scan, the intent gate's preparation steps, osv-scanner's base run), so
1582
+ a gate's wall time can be a multiple of it. A gate stopped at its limit is
1583
+ could-not-run (`timed-out`), never a pass.
1584
+
1585
+ - The limit is a SIGTERM deadline. A gate that ignores SIGTERM keeps the run
1586
+ waiting until it exits on its own; conductor does not escalate to SIGKILL.
1587
+ - A gate's own child processes are not stopped with it. A gate behind a
1588
+ shell-wrapper `command` can keep running after the report says
1589
+ `timed-out`.
1590
+ - On a hosted runner the six-hour job limit includes checkout, setup and
1591
+ every other gate, so a limit near the 21600 ceiling is cancelled with the
1592
+ job before it can fire. Keep it well under.
1593
+
1594
+ Measure your own full scan once, on the runner it will run on, and set the
1595
+ limit with headroom. The recommended split: every pull request scans its own
1596
+ range, and the full history is scanned on a schedule with a limit sized for
1597
+ it. Two existing ways to make it: by stage, since `secrets-history` defaults
1598
+ to stage `ci` and a push workflow run with the Action's `stage: push` input
1599
+ (or `conductor run --stage push`) leaves ci-stage gates out; or by trigger,
1600
+ running the workflow on pull requests and a schedule and not on push. With
1601
+ the CLI, `--gate secrets-history` on the scheduled job also works.
1602
+
1603
+ `max-target-megabytes`, passed under `options`, skips every file larger
1604
+ than the cap. Measured with gitleaks 8.30.1 in the mode conductor runs, at
1605
+ the log level conductor runs it at: a secret inside a file over the cap was
1606
+ not reported, no line in gitleaks' log named the skipped file, and the scan
1607
+ summary still reported the full byte count. It is a coverage decision, made
1608
+ in the policy file where a reviewer can see it, and conductor never applies
1609
+ it by default.
1610
+
1611
+ `options.timeout` on the secrets-history gate is gitleaks' own deadline,
1612
+ not conductor's. A `conductor/option-is-gate-own` note says so: always in
1613
+ the SARIF log, and in the text report under the gate header whenever the
1614
+ full report is printed (with `--verbose`, or on any run that is not fully
1615
+ clean; a clean run without `--verbose` prints only its one-line summary).
1616
+ When it fires
1617
+ gitleaks exits 1, whether or not it had found a leak, and the gate is
1618
+ could-not-run. Leaks it found before the deadline are not listed as
1619
+ findings; the echoed gitleaks log line ("N leaks found in partial scan") is
1620
+ the only mention of them.
1621
+
1516
1622
  ### Running the gates as an advisory check
1517
1623
 
1518
1624
  To run the gates without blocking a merge, set `advisory: true` on the
@@ -1555,7 +1661,7 @@ jobs:
1555
1661
  node-version: '22.11.0'
1556
1662
  - id: conductor
1557
1663
  timeout-minutes: 5
1558
- uses: vaultcompasshq/conductor@v0.9.0
1664
+ uses: vaultcompasshq/conductor@v0.10.0
1559
1665
  with:
1560
1666
  pr-comment: true
1561
1667
  advisory: true
@@ -1691,7 +1797,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1691
1797
  # the pull request runs before the action in this job: no install, build
1692
1798
  # or test step here; those belong in a separate job. ...
1693
1799
  - id: conductor
1694
- uses: vaultcompasshq/conductor@v0.9.0
1800
+ uses: vaultcompasshq/conductor@v0.10.0
1695
1801
  with:
1696
1802
  output: conductor.sarif
1697
1803
  pr-comment: true
@@ -1770,12 +1876,12 @@ per pull request.
1770
1876
 
1771
1877
  ```yaml
1772
1878
  - id: conductor-package-a
1773
- uses: vaultcompasshq/conductor@v0.9.0
1879
+ uses: vaultcompasshq/conductor@v0.10.0
1774
1880
  with:
1775
1881
  pr-comment: true
1776
1882
  pr-comment-marker: 'package-a'
1777
1883
  - id: conductor-package-b
1778
- uses: vaultcompasshq/conductor@v0.9.0
1884
+ uses: vaultcompasshq/conductor@v0.10.0
1779
1885
  with:
1780
1886
  pr-comment: true
1781
1887
  pr-comment-marker: 'package-b'
package/dist/cli.d.ts CHANGED
@@ -1,3 +1,9 @@
1
1
  #!/usr/bin/env node
2
2
  import { Command } from 'commander';
3
+ /**
4
+ * Whether the text report is rendered for a terminal: only when it goes to
5
+ * stdout (no --output) and stdout is a TTY. A file, a pipe and the
6
+ * --text-report copy never are, so they stay byte for byte as before.
7
+ */
8
+ export declare function rendersToTerminal(output: string | undefined, stdoutIsTTY: boolean | undefined): boolean;
3
9
  export declare function buildProgram(): Command;
package/dist/cli.js CHANGED
@@ -195,6 +195,14 @@ const PROJECT_OPTION_HELP = 'run against this directory instead of the current o
195
195
  function applyAdvisory(exitCode, advisory) {
196
196
  return advisory && exitCode === EXIT_BLOCKED ? EXIT_OK : exitCode;
197
197
  }
198
+ /**
199
+ * Whether the text report is rendered for a terminal: only when it goes to
200
+ * stdout (no --output) and stdout is a TTY. A file, a pipe and the
201
+ * --text-report copy never are, so they stay byte for byte as before.
202
+ */
203
+ export function rendersToTerminal(output, stdoutIsTTY) {
204
+ return output === undefined && stdoutIsTTY === true;
205
+ }
198
206
  /**
199
207
  * Reads the policy for one run, from the base ref in pull-request mode.
200
208
  *
@@ -636,16 +644,20 @@ export function buildProgram() {
636
644
  // there: each finding's `properties.blocking` is the gate's own
637
645
  // decision (see output-sarif.ts) and is unaffected by this flag,
638
646
  // exactly as the text report's per-finding BLOCKING marker is.
639
- const renderTextReport = () => renderText(result, {
647
+ const renderTextReport = (terminal) => renderText(result, {
640
648
  verbose: Boolean(options.verbose),
641
649
  version: pkg.version,
642
650
  compact: Boolean(options.compactOnRefusal),
643
651
  advisory,
652
+ ...(terminal ? { terminal: true } : {}),
644
653
  });
645
- const rendered = format === 'sarif' ? `${renderSarif(result, pkg.version)}\n` : renderTextReport();
654
+ // Only a report printed straight to a terminal is told so; a file,
655
+ // a pipe and the --text-report copy render exactly as before.
656
+ const toTerminal = rendersToTerminal(options.output, process.stdout.isTTY);
657
+ const rendered = format === 'sarif' ? `${renderSarif(result, pkg.version)}\n` : renderTextReport(toTerminal);
646
658
  // The SAME result, rendered a second time, never a second run: the
647
659
  // token in this file is for the run that set the exit code below.
648
- const textReport = options.textReport === undefined ? undefined : renderTextReport();
660
+ const textReport = options.textReport === undefined ? undefined : renderTextReport(false);
649
661
  if (options.output === undefined) {
650
662
  process.stdout.write(rendered);
651
663
  }
@@ -689,7 +701,10 @@ export function buildProgram() {
689
701
  // Written after the report file, so a failure above still takes the
690
702
  // catch below and these lines never describe a run that then exits 2
691
703
  // for an unwritable file.
692
- const logLines = [...gateLogLines(result), ...versionSkewWarnings(result)];
704
+ const logLines = [
705
+ ...gateLogLines(result, process.stderr.isTTY === true ? { terminal: true } : {}),
706
+ ...versionSkewWarnings(result),
707
+ ];
693
708
  if (logLines.length > 0) {
694
709
  process.stderr.write(`${logLines.join('\n')}\n`);
695
710
  }
@@ -49,10 +49,37 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
49
49
  * inside the pull request is never seen). Never unshallowed automatically:
50
50
  * the remedy is a checkout setting, fetch-depth: 0.
51
51
  */
52
- | 'history-shallow';
52
+ | 'history-shallow'
53
+ /**
54
+ * conductor stopped the gate at its time limit (`timeout-seconds` in the
55
+ * policy, else the product's default). Decided by the spawn error code
56
+ * ETIMEDOUT alone, never by the signal or the status: a child that handled
57
+ * SIGTERM can return status 0, or its blocked code, with a clean report.
58
+ * Raised for the version probe, the scan, and the intent gate's
59
+ * preparation steps; `timedOut.step` says which spawn was stopped.
60
+ */
61
+ | 'timed-out';
62
+ /** Where a gate's time limit came from: the test hook, the policy, or the product default. */
63
+ export type TimeLimitSource = 'override' | 'policy' | 'default';
64
+ export interface TimeLimit {
65
+ ms: number;
66
+ source: TimeLimitSource;
67
+ }
68
+ /** 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';
70
+ export interface TimedOut {
71
+ step: TimedOutStep;
72
+ limitSeconds: number;
73
+ elapsedSeconds: number;
74
+ limitSource: TimeLimitSource;
75
+ /** What spawnSync reported; null when the child handled SIGTERM and exited itself. Never used to classify. */
76
+ signal: string | null;
77
+ }
53
78
  export interface CouldNotRun {
54
79
  reason: CouldNotRunReason;
55
80
  detail: string;
81
+ /** Present only for `timed-out`. */
82
+ timedOut?: TimedOut;
56
83
  /**
57
84
  * What the gate itself said about why it could not run: a short, bounded,
58
85
  * sanitised excerpt of its own stderr (first line) or, failing that, of a
@@ -74,10 +101,41 @@ export declare const GATE_SAID_MAX_CHARS = 160;
74
101
  export declare function breakWorkflowMarkers(text: string): string;
75
102
  /**
76
103
  * The could-not-run reasons that are conductor's OWN decision, made before
77
- * the gate was spawned (or instead of spawning it), as opposed to something
78
- * the gate itself said or did.
104
+ * the gate was spawned (or instead of spawning it), or the umbrella stopping
105
+ * it, as opposed to something the gate itself said or did.
79
106
  */
80
107
  export declare const CONDUCTOR_OWN_REASONS: ReadonlySet<CouldNotRunReason>;
108
+ /**
109
+ * A gate's time limit, and where it came from. THE ONE PLACE the precedence
110
+ * is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
111
+ * sets), then the policy's `timeout-seconds`, then the product's default.
112
+ * runGate and the intent gate's preparation in run.ts both call this, so the
113
+ * two cannot disagree about a gate's limit.
114
+ */
115
+ export declare function resolveTimeLimit(gate: GatePolicy, override: number | undefined): TimeLimit;
116
+ /** What a spawn error was: the umbrella's deadline, or anything else. */
117
+ export type SpawnFailure = {
118
+ reason: 'timed-out';
119
+ signal: string | null;
120
+ } | {
121
+ reason: 'spawn-failed';
122
+ message: string;
123
+ };
124
+ /**
125
+ * Classifies a spawnSync result that carries an error. PURE, so it is tested
126
+ * on hand-built results.
127
+ *
128
+ * THE ERROR CODE ALONE decides it. ETIMEDOUT is timed-out and nothing else
129
+ * is. No status or signal condition belongs here: a child that traps SIGTERM,
130
+ * or ignores it and exits on its own, comes back with status 0 (or its
131
+ * blocked code) and signal null, and ENOBUFS arrives with the same SIGTERM a
132
+ * timeout does. The signal is recorded for the report and never classifies.
133
+ */
134
+ export declare function spawnFailure(child: {
135
+ error?: Error | undefined;
136
+ status?: number | null;
137
+ signal?: NodeJS.Signals | string | null;
138
+ }): SpawnFailure | null;
81
139
  /**
82
140
  * conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
83
141
  * one line, capped and with double quotes replaced, exactly like a gate's
@@ -94,12 +152,15 @@ export declare function cleanOutputLine(raw: string): string;
94
152
  * What a gate that exited with a non-verdict code said about why.
95
153
  *
96
154
  * TOTAL, and never a decision: the caller has already settled that this is a
97
- * could-not-run, and nothing here can change that. The first non-empty stderr
98
- * line is preferred, since that is where every gate in the family prints its
99
- * reason on exit 2 (dep-guard, intent-guard and vault-guard all do). Failing
100
- * that, stdout is parsed only for a gate whose output is JSON on stdout, and
101
- * only a string `reason` field (top level, or on `run`) is read; anything else,
102
- * including output that does not parse, is simply no excerpt.
155
+ * could-not-run, and nothing here can change that. stderr is preferred, since
156
+ * that is where every gate in the family prints its reason on exit 2
157
+ * (dep-guard, intent-guard and vault-guard all do), read by the rule in
158
+ * `statedReasonFromStderr`: the line the gate marks as the failure, never an
159
+ * informational line. Failing that, stdout is parsed only for a gate whose
160
+ * output is JSON on stdout, and only a string `reason` field (top level, or
161
+ * on `run`) is read; anything else, including output that does not parse, is
162
+ * simply no excerpt. An absent excerpt is better than quoting a warning as
163
+ * the cause; the full stderr is still printed in the text report.
103
164
  */
104
165
  export declare function gateStatedReason(stderr: string, stdout: string | null | undefined, stdoutIsJson: boolean): string | null;
105
166
  /**
@@ -267,6 +328,21 @@ export interface GateOutcome {
267
328
  * decision (gateExitBlocks) never need the policy file.
268
329
  */
269
330
  baseComparison?: BaseComparison;
331
+ /**
332
+ * The time limit this gate ran under and where it came from, carried like
333
+ * `enforce` so the report and the timed-out message never need the policy
334
+ * file. Set on every outcome runGate builds once the limit is resolved.
335
+ */
336
+ timeLimit?: TimeLimit;
337
+ /**
338
+ * The `conductor/option-is-gate-own` note: set when the secrets-history
339
+ * gate's options carry `timeout`, which is gitleaks' own --timeout and not
340
+ * conductor's limit. On the OUTCOME rather than in `run.diagnostics`,
341
+ * because every could-not-run outcome carries an empty run, and the
342
+ * gate-error that gitleaks' own deadline produces is exactly the outcome
343
+ * that needs the note. Information only; nothing decides on it.
344
+ */
345
+ gateOwnOption?: string;
270
346
  }
271
347
  export interface RunGateOptions {
272
348
  /**
@@ -279,7 +355,10 @@ export interface RunGateOptions {
279
355
  staged: boolean;
280
356
  /** PATH to search. Injected so tests never depend on the machine. */
281
357
  pathValue: string;
282
- /** Wall-clock limit per gate. */
358
+ /**
359
+ * A test hook: the time limit for every spawn of this gate, outranking the
360
+ * policy's timeout-seconds. No CLI path sets it. See `resolveTimeLimit`.
361
+ */
283
362
  timeoutMs?: number;
284
363
  /** The contract and change set prepared for the intent gate, when there is one. */
285
364
  intent?: IntentPreparation;
@@ -317,6 +396,19 @@ export interface RunGateOptions {
317
396
  * would have to learn about.
318
397
  */
319
398
  export declare function preparationFailed(gate: GatePolicy, detail: string): GateOutcome;
399
+ /**
400
+ * The intent gate whose preparation step (import-spec or freeze) was stopped
401
+ * at the gate's time limit. Shaped like `preparationFailed`, with the
402
+ * timed-out reason, so it composes the same way; the caller decides
403
+ * `enforce` under the same rule it applies to a failed preparation.
404
+ */
405
+ export declare function preparationTimedOut(gate: GatePolicy, stopped: {
406
+ step: 'import-spec' | 'freeze';
407
+ elapsedMs: number;
408
+ signal: string | null;
409
+ limit: TimeLimit;
410
+ trustBase?: string;
411
+ }): GateOutcome;
320
412
  /**
321
413
  * EVERY program this binary would spawn, vetted against the trust base.
322
414
  *