@vaultcompass/conductor 0.13.0 → 0.13.2

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.0
171
+ conductor 0.13.2
172
172
  verdict-token: blocked (1)
173
173
  conductor run: 2 gate(s), 1 finding(s)
174
174
 
@@ -1420,7 +1420,7 @@ request being judged, and the version-pin protection described above
1420
1420
  "protects nothing" against a tree that controls its own judge (the
1421
1421
  validate step's own comment in `action.yml` says so in those words). A tag
1422
1422
  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.0.
1423
+ SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.13.2.
1424
1424
 
1425
1425
  ```yaml
1426
1426
  name: guardrails
@@ -1442,7 +1442,7 @@ jobs:
1442
1442
  with:
1443
1443
  node-version: '22.11.0'
1444
1444
  - id: conductor
1445
- uses: vaultcompasshq/conductor@v0.13.0
1445
+ uses: vaultcompasshq/conductor@v0.13.2
1446
1446
  with:
1447
1447
  output: conductor.sarif
1448
1448
  - uses: github/codeql-action/upload-sarif@v3
@@ -1517,7 +1517,7 @@ jobs:
1517
1517
  # installs those itself, globally. Leave conductor-version unset so the
1518
1518
  # umbrella is the default in the pinned action.yml.
1519
1519
  - id: conductor
1520
- uses: vaultcompasshq/conductor@v0.13.0
1520
+ uses: vaultcompasshq/conductor@v0.13.2
1521
1521
  with:
1522
1522
  output: conductor.sarif
1523
1523
  # Exact versions, never a range and never "latest". These three
@@ -1528,7 +1528,7 @@ jobs:
1528
1528
  # request of their own. On a pull request the action refuses a pin
1529
1529
  # below what the pinned action.yml ships, and the three lines can
1530
1530
  # be left out entirely to take that action's own versions.
1531
- dep-guard-version: 0.15.0
1531
+ dep-guard-version: 0.16.1
1532
1532
  vault-guard-version: 1.12.1
1533
1533
  intent-guard-version: 1.10.1
1534
1534
  - uses: github/codeql-action/upload-sarif@v3
@@ -1723,7 +1723,7 @@ jobs:
1723
1723
  node-version: '22.11.0'
1724
1724
  - id: conductor
1725
1725
  timeout-minutes: 5
1726
- uses: vaultcompasshq/conductor@v0.13.0
1726
+ uses: vaultcompasshq/conductor@v0.13.2
1727
1727
  with:
1728
1728
  pr-comment: true
1729
1729
  advisory: true
@@ -1859,7 +1859,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1859
1859
  # the pull request runs before the action in this job: no install, build
1860
1860
  # or test step here; those belong in a separate job. ...
1861
1861
  - id: conductor
1862
- uses: vaultcompasshq/conductor@v0.13.0
1862
+ uses: vaultcompasshq/conductor@v0.13.2
1863
1863
  with:
1864
1864
  output: conductor.sarif
1865
1865
  pr-comment: true
@@ -1938,12 +1938,12 @@ per pull request.
1938
1938
 
1939
1939
  ```yaml
1940
1940
  - id: conductor-package-a
1941
- uses: vaultcompasshq/conductor@v0.13.0
1941
+ uses: vaultcompasshq/conductor@v0.13.2
1942
1942
  with:
1943
1943
  pr-comment: true
1944
1944
  pr-comment-marker: 'package-a'
1945
1945
  - id: conductor-package-b
1946
- uses: vaultcompasshq/conductor@v0.13.0
1946
+ uses: vaultcompasshq/conductor@v0.13.2
1947
1947
  with:
1948
1948
  pr-comment: true
1949
1949
  pr-comment-marker: 'package-b'
@@ -2064,7 +2064,7 @@ an explicit pin is unaffected, which is how a stale pin can sit unnoticed
2064
2064
  until the first pull request after the upgrade.
2065
2065
 
2066
2066
  **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.0`. To
2067
+ example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.13.2`. To
2068
2068
  find the SHA for a tag, run
2069
2069
  `gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
2070
2070
  the Releases page.
@@ -2087,6 +2087,8 @@ tag with no row here has an entry that does not state its defaults; read
2087
2087
 
2088
2088
  | Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
2089
2089
  | --- | --- | --- | --- |
2090
+ | v0.13.2 | package | 0.13.2 | none (gate defaults unchanged) |
2091
+ | v0.13.1 | action-only | 0.13.0 | dep-guard 0.16.1 (from 0.15.0) |
2090
2092
  | v0.13.0 | package | 0.13.0 | none (gate defaults unchanged) |
2091
2093
  | 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) |
2092
2094
  | 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) |
@@ -555,6 +555,29 @@ external?: ExternalArgs,
555
555
  * `--base` in place of `--paths`. Decided by `intentChangeChannel`.
556
556
  */
557
557
  intentBase?: string): string[];
558
+ /**
559
+ * The expected-version decision for the intent gate, made BEFORE its
560
+ * preparation (residual 3, 2026-10-20).
561
+ *
562
+ * The preparation spawns the resolved binary for import-spec and freeze, and
563
+ * a failed or timed-out preparation ends the gate there, so without this the
564
+ * version check in runGate was never reached: an off-pin build whose
565
+ * preparation failed on a run with no trust base and `enforce: false` read
566
+ * preparation-failed, not enforced, exit 0, where runGate would have said
567
+ * version-skew, exit 2. Here the same probe and the same builder as runGate's
568
+ * decide first, and only the probe is spawned.
569
+ *
570
+ * Null when the version is the expected one: the preparation and runGate then
571
+ * go on as before, and runGate probes again (one cheap spawn) and reaches the
572
+ * same answer. The caller only calls this when an expectation is set; a run
573
+ * without one never reaches it, and nothing about it changes.
574
+ */
575
+ export declare function expectedVersionBeforePreparation(gate: GatePolicy, binary: ResolvedBinary, options: {
576
+ repoRoot: string;
577
+ expectedVersion: string;
578
+ timeoutMs?: number;
579
+ trustBase?: string;
580
+ }): GateOutcome | null;
558
581
  /**
559
582
  * Runs one gate. TOTAL: this never throws.
560
583
  *
@@ -865,6 +865,119 @@ function probeVersion(binary, product, repoRoot, timeoutMs) {
865
865
  const match = spec.pattern.exec(first);
866
866
  return match === null ? { kind: 'unreadable' } : { kind: 'version', value: (match[1] ?? match[0]).replace(/^v/, '') };
867
867
  }
868
+ /**
869
+ * The could-not-run for a gate whose version is not the expected one
870
+ * (`version-skew`) or cannot be read (`version-unverified`).
871
+ *
872
+ * ONE BUILDER, TWO CALLERS, like gateProgramRefused: runGate reaches it right
873
+ * after its version probe, and runAll reaches it earlier, through
874
+ * `expectedVersionBeforePreparation`, before the intent gate's preparation
875
+ * spawns the same binary. Two copies of the sentence would be two chances for
876
+ * the reason, the detail or the enforce override to drift apart.
877
+ *
878
+ * ENFORCED whatever the policy says: the gate produced no verdict for
879
+ * `enforce: false` to be a decision about.
880
+ */
881
+ function versionNotExpected(gate, binary, version, expected, repoRoot) {
882
+ const relative = path.relative(repoRoot, binary.program);
883
+ const inside = relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
884
+ // Repository-relative inside the repository; outside it, words only,
885
+ // because this detail reaches the reports and a published log.
886
+ const place = binary.source === 'node_modules' && inside ? relative : resolutionPlace(binary.source);
887
+ const remedy = versionSkewRemedy(gate.product, binary.source, expected);
888
+ const pinned = `${expected} (the version the action pinned)`;
889
+ const detail = version === null
890
+ ? `${gate.product} did not run: the version of the build resolved from ${place} could not be read, ` +
891
+ `so it is not known to be ${pinned}. ${remedy}`
892
+ : `${gate.product} did not run: the build resolved from ${place} reports version ` +
893
+ `${versionCharacters(version)}, but this run expects ${pinned}. ${remedy}`;
894
+ return {
895
+ role: gate.role,
896
+ product: gate.product,
897
+ stage: gate.stage,
898
+ argv: [],
899
+ exitCode: null,
900
+ durationMs: 0,
901
+ stderr: '',
902
+ ...(version === null
903
+ ? {}
904
+ : {
905
+ // Kept for the job-log line, the annotation, the step summary,
906
+ // the text report line and the SARIF note that 0.12.0 printed.
907
+ versionSkew: {
908
+ expected,
909
+ found: version,
910
+ source: binary.source,
911
+ path: inside ? relative : binary.program,
912
+ },
913
+ }),
914
+ productVersion: version,
915
+ binary,
916
+ enforce: true,
917
+ couldNotRun: { reason: version === null ? 'version-unverified' : 'version-skew', detail },
918
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
919
+ run: EMPTY_RUN,
920
+ diagnostics: [],
921
+ };
922
+ }
923
+ /**
924
+ * The expected-version decision for the intent gate, made BEFORE its
925
+ * preparation (residual 3, 2026-10-20).
926
+ *
927
+ * The preparation spawns the resolved binary for import-spec and freeze, and
928
+ * a failed or timed-out preparation ends the gate there, so without this the
929
+ * version check in runGate was never reached: an off-pin build whose
930
+ * preparation failed on a run with no trust base and `enforce: false` read
931
+ * preparation-failed, not enforced, exit 0, where runGate would have said
932
+ * version-skew, exit 2. Here the same probe and the same builder as runGate's
933
+ * decide first, and only the probe is spawned.
934
+ *
935
+ * Null when the version is the expected one: the preparation and runGate then
936
+ * go on as before, and runGate probes again (one cheap spawn) and reaches the
937
+ * same answer. The caller only calls this when an expectation is set; a run
938
+ * without one never reaches it, and nothing about it changes.
939
+ */
940
+ export function expectedVersionBeforePreparation(gate, binary, options) {
941
+ const timeLimit = resolveTimeLimit(gate, options.timeoutMs);
942
+ // What runGate's outcome carries on the same path, so the two report alike.
943
+ const skipped = options.trustBase === undefined ? null : nodeModulesCandidate(gate, options.repoRoot);
944
+ const carried = { timeLimit, ...(skipped === null ? {} : { nodeModulesSkipped: skipped }) };
945
+ const started = Date.now();
946
+ const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit.ms);
947
+ if (probed.kind === 'timed-out') {
948
+ // The same outcome runGate builds for a stopped probe under the
949
+ // expectation: enforced, because the run cannot show this is the pinned
950
+ // build.
951
+ const detail = timedOutDetail(gate, 'version-probe', timeLimit, probed.elapsedMs, options.trustBase);
952
+ const timedOut = timedOutRecord('version-probe', timeLimit, probed.elapsedMs, probed.signal);
953
+ return {
954
+ role: gate.role,
955
+ product: gate.product,
956
+ stage: gate.stage,
957
+ enforce: true,
958
+ productVersion: null,
959
+ argv: [],
960
+ binary,
961
+ exitCode: null,
962
+ durationMs: Date.now() - started,
963
+ stderr: '',
964
+ ...carried,
965
+ couldNotRun: { reason: 'timed-out', detail, timedOut },
966
+ findings: [timedOutFinding(gate, detail, timedOut)],
967
+ run: EMPTY_RUN,
968
+ diagnostics: [],
969
+ };
970
+ }
971
+ const version = probed.kind === 'version' ? probed.value : null;
972
+ if (version === options.expectedVersion) {
973
+ return null;
974
+ }
975
+ return {
976
+ ...versionNotExpected(gate, binary, version, options.expectedVersion, options.repoRoot),
977
+ ...carried,
978
+ durationMs: Date.now() - started,
979
+ };
980
+ }
868
981
  /**
869
982
  * `context.blocked` is whether the gate's exit said it blocked. The npm gates
870
983
  * carry that in their own JSON and ignore it; the external tools' reports do
@@ -1226,41 +1339,10 @@ function runGateInner(gate, options, started, progress) {
1226
1339
  // `enforce: false` to be a decision about. No expectation (every plain run)
1227
1340
  // skips all of this.
1228
1341
  if (options.expectedVersion !== undefined && version !== options.expectedVersion) {
1229
- const expected = options.expectedVersion;
1230
- const relative = path.relative(options.repoRoot, binary.program);
1231
- const inside = relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
1232
- // Repository-relative inside the repository; outside it, words only,
1233
- // because this detail reaches the reports and a published log.
1234
- const place = binary.source === 'node_modules' && inside ? relative : resolutionPlace(binary.source);
1235
- const remedy = versionSkewRemedy(gate.product, binary.source, expected);
1236
- const pinned = `${expected} (the version the action pinned)`;
1237
- const detail = version === null
1238
- ? `${gate.product} did not run: the version of the build resolved from ${place} could not be read, ` +
1239
- `so it is not known to be ${pinned}. ${remedy}`
1240
- : `${gate.product} did not run: the build resolved from ${place} reports version ` +
1241
- `${versionCharacters(version)}, but this run expects ${pinned}. ${remedy}`;
1242
1342
  return {
1243
1343
  ...base,
1244
- ...(version === null
1245
- ? {}
1246
- : {
1247
- // Kept for the job-log line, the annotation, the step summary,
1248
- // the text report line and the SARIF note that 0.12.0 printed.
1249
- versionSkew: {
1250
- expected,
1251
- found: version,
1252
- source: binary.source,
1253
- path: inside ? relative : binary.program,
1254
- },
1255
- }),
1256
- productVersion: version,
1257
- binary,
1258
- enforce: true,
1344
+ ...versionNotExpected(gate, binary, version, options.expectedVersion, options.repoRoot),
1259
1345
  durationMs: Date.now() - started,
1260
- couldNotRun: { reason: version === null ? 'version-unverified' : 'version-skew', detail },
1261
- findings: [normalizeFailedGate(gate.role, gate.product, detail)],
1262
- run: EMPTY_RUN,
1263
- diagnostics: [],
1264
1346
  };
1265
1347
  }
1266
1348
  // The command-line floor. Only the external tools have one: the umbrella
package/dist/run.js CHANGED
@@ -1,7 +1,7 @@
1
1
  // One run across every enabled gate.
2
2
  import { compareFindings } from './envelope.js';
3
3
  import { EXIT_COULD_NOT_RUN, composeExitCode, gateExitBlocks } from './exit-codes.js';
4
- import { gateProgramRefused, preparationFailed, preparationTimedOut, refuseHeadControlledBinary, resolveTimeLimit, runGate, } from './gate-runner.js';
4
+ import { expectedVersionBeforePreparation, gateProgramRefused, preparationFailed, preparationTimedOut, refuseHeadControlledBinary, resolveTimeLimit, runGate, } from './gate-runner.js';
5
5
  import { resolveBaseRef } from './intent-base.js';
6
6
  import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
7
7
  import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
@@ -227,7 +227,8 @@ function splitOnTreeUnchanged(gates, trustBase) {
227
227
  * The environment variables the Action sets to say which version of each
228
228
  * family gate it pinned. Since 0.13.0 a control input, in ONE DIRECTION
229
229
  * ONLY: a gate that reports another version, or none, is could-not-run
230
- * (runGate), and nothing else reads them. They can add a could-not-run and
230
+ * (runGate, and for the intent gate also before its preparation, below), and
231
+ * nothing else reads them. They can add a could-not-run and
231
232
  * never clear a gate or drop a finding, so a run that sets them wrongly fails
232
233
  * closed and a run without them is the plain run it always was. Resolution
233
234
  * is unchanged.
@@ -283,6 +284,26 @@ export function runAll(policy, options) {
283
284
  continue;
284
285
  }
285
286
  }
287
+ // THEN THE EXPECTED VERSION, still before the preparation spawns
288
+ // anything (residual 3, 2026-10-20). A failed or timed-out
289
+ // preparation ends this gate below, before runGate's own version
290
+ // check, so an off-pin build whose import-spec failed on a run with
291
+ // no trust base and enforce: false read as an unenforced
292
+ // preparation-failed, exit 0, instead of version-skew, exit 2. Same
293
+ // probe and same builder as runGate's. No expectation, no change.
294
+ const expected = expectedVersionOption(gate.product, env).expectedVersion;
295
+ if (expected !== undefined) {
296
+ const notExpected = expectedVersionBeforePreparation(gate, binary, {
297
+ repoRoot: options.repoRoot,
298
+ expectedVersion: expected,
299
+ ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
300
+ ...(trustBaseRef === undefined ? {} : { trustBase: trustBaseRef }),
301
+ });
302
+ if (notExpected !== null) {
303
+ outcomes.push(notExpected);
304
+ continue;
305
+ }
306
+ }
286
307
  const intentLimit = resolveTimeLimit(gate, options.timeoutMs);
287
308
  const prepared = prepareIntent({
288
309
  repoRoot: options.repoRoot,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.13.0",
3
+ "version": "0.13.2",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [