@vaultcompass/conductor 0.13.0 → 0.14.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.
@@ -21,7 +21,7 @@ import { spawnSync } from 'node:child_process';
21
21
  import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
22
22
  import { tmpdir } from 'node:os';
23
23
  import path from 'node:path';
24
- import { runGit } from './git.js';
24
+ import { realPathInside, runGit } from './git.js';
25
25
  import { NormalizeError } from './envelope.js';
26
26
  import { describeLockfiles, normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
27
27
  import { renderOptionFlags } from './policy.js';
@@ -158,6 +158,9 @@ function limitSourcePhrase(gate, source, trustBase) {
158
158
  ? `gates.${gate.role}.timeout-seconds`
159
159
  : `gates.${gate.role}.timeout-seconds on ${trustBase}`;
160
160
  }
161
+ if (source === 'preview-budget') {
162
+ return 'what was left of the 300 s preview budget';
163
+ }
161
164
  return source === 'default' ? 'the default for this gate' : 'set by the caller';
162
165
  }
163
166
  /**
@@ -178,7 +181,17 @@ function timedOutDetail(gate, step, limit, elapsedMs, trustBase) {
178
181
  const elapsedSeconds = Math.round(elapsedMs / 1000);
179
182
  const where = limitSourcePhrase(gate, limit.source, trustBase);
180
183
  const own = gateOwnTimeoutNote(gate, limit, trustBase);
181
- const remedies = profileFor(gate.product).timeoutRemedies(gate.role);
184
+ // A preview stopped by its own budget has no limit to raise: the budget is
185
+ // fixed, and the gate's own limit was not what stopped it.
186
+ const remedies = limit.source === 'preview-budget'
187
+ ? 'The preview under the proposed rules has 300 s in all, whatever each gate\'s own limit.'
188
+ : profileFor(gate.product).timeoutRemedies(gate.role);
189
+ // A preview spawn with no budget left was never started (spawnLimits):
190
+ // there is no elapsed time or limit to report.
191
+ if (limit.source === 'preview-budget' && limit.ms === 0) {
192
+ const what = step === 'version-probe' ? `the version probe of ${gate.product}` : gate.product;
193
+ return `${what} was not started: the preview budget was spent, so nothing was checked by it. ${remedies}`;
194
+ }
182
195
  if (step === 'version-probe') {
183
196
  return (`the version probe of ${gate.product} was stopped at ${limitSeconds} s (${where}), so the gate ` +
184
197
  'was not run and nothing was checked by it.');
@@ -436,6 +449,12 @@ function intentChangeChannel(gate, intent, version) {
436
449
  }
437
450
  return { kind: 'paths' };
438
451
  }
452
+ /**
453
+ * Why dep-guard and vault-guard are not handed `--trust-base` in the preview
454
+ * under the proposed rules: the preview shows what the head's rules would do,
455
+ * and their own control files are part of those rules.
456
+ */
457
+ export const PREVIEW_WITHHELD = 'preview under the proposed rules: this gate read its own control files from the head';
439
458
  /**
440
459
  * Whether this gate can be handed `--trust-base`, and why not when it cannot.
441
460
  *
@@ -450,7 +469,14 @@ function intentChangeChannel(gate, intent, version) {
450
469
  * was working a moment ago would report could-not-run. So the flag goes only
451
470
  * where `--project` is the repository itself.
452
471
  */
453
- export function decideTrustBase(gate, intent, trustBase, productVersion) {
472
+ export function decideTrustBase(gate, intent, trustBase, productVersion,
473
+ /**
474
+ * The preview under the proposed rules. dep-guard and vault-guard then read
475
+ * their own control files from the head, so the flag is withheld from them;
476
+ * the trust base itself stays set on the run, and every other product is
477
+ * decided exactly as without it.
478
+ */
479
+ preview = false) {
454
480
  if (trustBase === undefined) {
455
481
  return undefined;
456
482
  }
@@ -493,6 +519,15 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
493
519
  `was checked by it. Fix: install ${gate.product} ${minimum} or newer, or remove an ` +
494
520
  'explicit older version pin.');
495
521
  }
522
+ // AFTER both version refusals, so a gate refused in the primary run is
523
+ // refused in the preview too. Only the --trust-base flag is withheld: the
524
+ // run keeps its trust base, and with it the node_modules skip, the program
525
+ // refusal and the forced enforce, and dep-guard keeps --base (gateArgs'
526
+ // changeBase). gitleaks and osv-scanner never reach this: the umbrella
527
+ // itself is their pull-request mode, and it stays the base's.
528
+ if (preview && (gate.product === 'dep-guard' || gate.product === 'vault-guard')) {
529
+ return withheld(PREVIEW_WITHHELD);
530
+ }
496
531
  // AFTER the version checks, so an imported contract cannot let an older
497
532
  // gate run: this withholding is about where --project points, not about
498
533
  // what the gate understands, and the contract itself came from the base.
@@ -506,6 +541,47 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
506
541
  }
507
542
  return { ref: trustBase, withheld: null, refused: null, proposals: [] };
508
543
  }
544
+ /** The smaller of a spawn's own limit and what is left of the preview budget, never negative. */
545
+ export function previewSpawnTimeout(limitMs, preview) {
546
+ return Math.max(0, Math.min(limitMs, preview.deadline - preview.clock()));
547
+ }
548
+ /**
549
+ * The spawn options of every preview spawn: the timeout above, SIGKILL, so a
550
+ * child that traps SIGTERM cannot outlive the budget, and the spawn's own
551
+ * environment with XDG_CACHE_HOME pointed at the preview's private cache, so
552
+ * nothing the head's rules fetched persists on a shared runner.
553
+ */
554
+ export function previewSpawnOptions(limitMs, preview, env) {
555
+ return {
556
+ timeout: previewSpawnTimeout(limitMs, preview),
557
+ killSignal: 'SIGKILL',
558
+ env: { ...env, XDG_CACHE_HOME: preview.cacheDir },
559
+ };
560
+ }
561
+ /**
562
+ * The options one spawn passes to spawnSync beside its own, and the limit it
563
+ * ran under. Outside the preview: the full limit and nothing else, exactly as
564
+ * before. In the preview: `previewSpawnOptions`, and the limit's source is
565
+ * `preview-budget` when the budget left was the smaller. `start` false means
566
+ * no budget is left, and the spawn must not be started: a spawnSync timeout
567
+ * of 0 is no timeout at all.
568
+ */
569
+ function spawnLimits(limit, preview, env) {
570
+ if (preview === undefined) {
571
+ return { start: true, limit, options: { timeout: limit.ms, ...(env === undefined ? {} : { env }) } };
572
+ }
573
+ const options = previewSpawnOptions(limit.ms, preview, env ?? process.env);
574
+ return {
575
+ start: options.timeout > 0,
576
+ limit: options.timeout < limit.ms ? { ms: options.timeout, source: 'preview-budget' } : limit,
577
+ options,
578
+ };
579
+ }
580
+ /** A spawnSync-shaped result for a preview spawn that was never started: no budget left. */
581
+ function notStartedResult() {
582
+ const error = Object.assign(new Error('spawnSync ETIMEDOUT: the preview budget was spent'), { code: 'ETIMEDOUT' });
583
+ return { pid: 0, output: [], stdout: '', stderr: '', status: null, signal: null, error };
584
+ }
509
585
  /**
510
586
  * A gate that never got as far as being spawned.
511
587
  *
@@ -655,7 +731,22 @@ external = {},
655
731
  * For the intent gate on a prepared run: hand it this base with its own
656
732
  * `--base` in place of `--paths`. Decided by `intentChangeChannel`.
657
733
  */
658
- intentBase) {
734
+ intentBase,
735
+ /**
736
+ * dep-guard's `--base` when `trustBase` is withheld from it in the preview
737
+ * under the proposed rules: the change is still measured against the base
738
+ * ref, only the rules are the head's. Ignored when `trustBase` is set, and
739
+ * by every other product.
740
+ */
741
+ changeBase,
742
+ /**
743
+ * True for a spawn of the preview under the proposed rules. osv-scanner
744
+ * then gets `--no-call-analysis=all` appended after the base's own options,
745
+ * whatever they say: call analysis builds the project it scans, which in
746
+ * the preview is the head's code, and osv-scanner applies its disables
747
+ * after its enables, so the appended flag wins.
748
+ */
749
+ preview = false) {
659
750
  const passthrough = renderOptionFlags(gate.options);
660
751
  const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
661
752
  const config = external.configPath === undefined ? [] : ['--config', external.configPath];
@@ -680,7 +771,8 @@ intentBase) {
680
771
  // name incompatible comparisons -- the git index versus an arbitrary
681
772
  // ref. A staged run already has its own comparison and --trust-base
682
773
  // is unaffected, since it answers a different question.
683
- const base = trustBase !== undefined && !staged ? ['--base', trustBase] : [];
774
+ const baseRef = trustBase ?? changeBase;
775
+ const base = baseRef !== undefined && !staged ? ['--base', baseRef] : [];
684
776
  return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...base, ...passthrough];
685
777
  }
686
778
  case 'vault-guard':
@@ -832,26 +924,30 @@ intentBase) {
832
924
  ...(noResolve ? ['--no-resolve'] : []),
833
925
  ...callAnalysis,
834
926
  ...renderOptionFlags(options),
927
+ ...(preview ? ['--no-call-analysis=all'] : []),
835
928
  ];
836
929
  }
837
930
  }
838
931
  }
839
- function probeVersion(binary, product, repoRoot, timeoutMs) {
932
+ function probeVersion(binary, product, repoRoot, timeLimit, preview) {
840
933
  const spec = profileFor(product).versionProbe;
841
934
  if (binary.versionProbe === null || spec === null) {
842
935
  return { kind: 'unreadable' };
843
936
  }
937
+ const limits = spawnLimits(timeLimit, preview, undefined);
844
938
  const probeStarted = Date.now();
845
- const probe = spawnSync(binary.versionProbe.command, binary.versionProbe.argv, {
846
- cwd: repoRoot,
847
- encoding: 'utf8',
848
- timeout: timeoutMs,
849
- });
939
+ const probe = limits.start
940
+ ? spawnSync(binary.versionProbe.command, binary.versionProbe.argv, {
941
+ cwd: repoRoot,
942
+ encoding: 'utf8',
943
+ ...limits.options,
944
+ })
945
+ : notStartedResult();
850
946
  // FIRST, before the status: a probe that handled SIGTERM can exit 0 with a
851
947
  // version on stdout, and it was still stopped at the limit.
852
948
  const failure = spawnFailure(probe);
853
949
  if (failure !== null && failure.reason === 'timed-out') {
854
- return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal };
950
+ return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal, limit: limits.limit };
855
951
  }
856
952
  if (probe.status !== 0 || typeof probe.stdout !== 'string') {
857
953
  return { kind: 'unreadable' };
@@ -865,6 +961,119 @@ function probeVersion(binary, product, repoRoot, timeoutMs) {
865
961
  const match = spec.pattern.exec(first);
866
962
  return match === null ? { kind: 'unreadable' } : { kind: 'version', value: (match[1] ?? match[0]).replace(/^v/, '') };
867
963
  }
964
+ /**
965
+ * The could-not-run for a gate whose version is not the expected one
966
+ * (`version-skew`) or cannot be read (`version-unverified`).
967
+ *
968
+ * ONE BUILDER, TWO CALLERS, like gateProgramRefused: runGate reaches it right
969
+ * after its version probe, and runAll reaches it earlier, through
970
+ * `expectedVersionBeforePreparation`, before the intent gate's preparation
971
+ * spawns the same binary. Two copies of the sentence would be two chances for
972
+ * the reason, the detail or the enforce override to drift apart.
973
+ *
974
+ * ENFORCED whatever the policy says: the gate produced no verdict for
975
+ * `enforce: false` to be a decision about.
976
+ */
977
+ function versionNotExpected(gate, binary, version, expected, repoRoot) {
978
+ const relative = path.relative(repoRoot, binary.program);
979
+ const inside = relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
980
+ // Repository-relative inside the repository; outside it, words only,
981
+ // because this detail reaches the reports and a published log.
982
+ const place = binary.source === 'node_modules' && inside ? relative : resolutionPlace(binary.source);
983
+ const remedy = versionSkewRemedy(gate.product, binary.source, expected);
984
+ const pinned = `${expected} (the version the action pinned)`;
985
+ const detail = version === null
986
+ ? `${gate.product} did not run: the version of the build resolved from ${place} could not be read, ` +
987
+ `so it is not known to be ${pinned}. ${remedy}`
988
+ : `${gate.product} did not run: the build resolved from ${place} reports version ` +
989
+ `${versionCharacters(version)}, but this run expects ${pinned}. ${remedy}`;
990
+ return {
991
+ role: gate.role,
992
+ product: gate.product,
993
+ stage: gate.stage,
994
+ argv: [],
995
+ exitCode: null,
996
+ durationMs: 0,
997
+ stderr: '',
998
+ ...(version === null
999
+ ? {}
1000
+ : {
1001
+ // Kept for the job-log line, the annotation, the step summary,
1002
+ // the text report line and the SARIF note that 0.12.0 printed.
1003
+ versionSkew: {
1004
+ expected,
1005
+ found: version,
1006
+ source: binary.source,
1007
+ path: inside ? relative : binary.program,
1008
+ },
1009
+ }),
1010
+ productVersion: version,
1011
+ binary,
1012
+ enforce: true,
1013
+ couldNotRun: { reason: version === null ? 'version-unverified' : 'version-skew', detail },
1014
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
1015
+ run: EMPTY_RUN,
1016
+ diagnostics: [],
1017
+ };
1018
+ }
1019
+ /**
1020
+ * The expected-version decision for the intent gate, made BEFORE its
1021
+ * preparation (residual 3, 2026-10-20).
1022
+ *
1023
+ * The preparation spawns the resolved binary for import-spec and freeze, and
1024
+ * a failed or timed-out preparation ends the gate there, so without this the
1025
+ * version check in runGate was never reached: an off-pin build whose
1026
+ * preparation failed on a run with no trust base and `enforce: false` read
1027
+ * preparation-failed, not enforced, exit 0, where runGate would have said
1028
+ * version-skew, exit 2. Here the same probe and the same builder as runGate's
1029
+ * decide first, and only the probe is spawned.
1030
+ *
1031
+ * Null when the version is the expected one: the preparation and runGate then
1032
+ * go on as before, and runGate probes again (one cheap spawn) and reaches the
1033
+ * same answer. The caller only calls this when an expectation is set; a run
1034
+ * without one never reaches it, and nothing about it changes.
1035
+ */
1036
+ export function expectedVersionBeforePreparation(gate, binary, options) {
1037
+ const timeLimit = resolveTimeLimit(gate, options.timeoutMs);
1038
+ // What runGate's outcome carries on the same path, so the two report alike.
1039
+ const skipped = options.trustBase === undefined ? null : nodeModulesCandidate(gate, options.repoRoot);
1040
+ const carried = { timeLimit, ...(skipped === null ? {} : { nodeModulesSkipped: skipped }) };
1041
+ const started = Date.now();
1042
+ const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit);
1043
+ if (probed.kind === 'timed-out') {
1044
+ // The same outcome runGate builds for a stopped probe under the
1045
+ // expectation: enforced, because the run cannot show this is the pinned
1046
+ // build.
1047
+ const detail = timedOutDetail(gate, 'version-probe', timeLimit, probed.elapsedMs, options.trustBase);
1048
+ const timedOut = timedOutRecord('version-probe', timeLimit, probed.elapsedMs, probed.signal);
1049
+ return {
1050
+ role: gate.role,
1051
+ product: gate.product,
1052
+ stage: gate.stage,
1053
+ enforce: true,
1054
+ productVersion: null,
1055
+ argv: [],
1056
+ binary,
1057
+ exitCode: null,
1058
+ durationMs: Date.now() - started,
1059
+ stderr: '',
1060
+ ...carried,
1061
+ couldNotRun: { reason: 'timed-out', detail, timedOut },
1062
+ findings: [timedOutFinding(gate, detail, timedOut)],
1063
+ run: EMPTY_RUN,
1064
+ diagnostics: [],
1065
+ };
1066
+ }
1067
+ const version = probed.kind === 'version' ? probed.value : null;
1068
+ if (version === options.expectedVersion) {
1069
+ return null;
1070
+ }
1071
+ return {
1072
+ ...versionNotExpected(gate, binary, version, options.expectedVersion, options.repoRoot),
1073
+ ...carried,
1074
+ durationMs: Date.now() - started,
1075
+ };
1076
+ }
868
1077
  /**
869
1078
  * `context.blocked` is whether the gate's exit said it blocked. The npm gates
870
1079
  * carry that in their own JSON and ignore it; the external tools' reports do
@@ -1023,6 +1232,63 @@ export function runGate(gate, options) {
1023
1232
  };
1024
1233
  }
1025
1234
  }
1235
+ function callAnalysisOff(options) {
1236
+ const asList = (value) => (Array.isArray(value) ? value : [value]);
1237
+ for (const key of Object.keys(options)) {
1238
+ if (!key.includes('call-analysis'))
1239
+ continue;
1240
+ const value = options[key];
1241
+ if (key === 'no-call-analysis' && (value === true || asList(value).some((item) => item === 'all')))
1242
+ continue;
1243
+ return false;
1244
+ }
1245
+ return true;
1246
+ }
1247
+ /**
1248
+ * The three refusals only the preview under the proposed rules makes.
1249
+ *
1250
+ * An option value starting with "-" would render as a flag of its own
1251
+ * (renderOptionFlags), so a value the base never ran with could add an output
1252
+ * path or a second --log-opts. A base `command:` inside the working tree is
1253
+ * checked by refuseHeadControlledProgram for its own blob only, while what it
1254
+ * imports comes from the head, and the preview can reach a role the base has
1255
+ * switched off, whose command nobody has exercised (spec 5.2, finding 7).
1256
+ * osv-scanner call analysis builds the project it scans, here the head's
1257
+ * code, so only the all-off form of it is allowed (callAnalysisOff), and
1258
+ * gateArgs forces it off on every preview spawn besides.
1259
+ */
1260
+ function previewRefusal(gate, repoRoot) {
1261
+ for (const name of Object.keys(gate.options).sort()) {
1262
+ const value = gate.options[name];
1263
+ const values = Array.isArray(value) ? value : [value];
1264
+ if (values.some((item) => typeof item === 'string' && item.startsWith('-'))) {
1265
+ return {
1266
+ reason: 'preparation-failed',
1267
+ detail: `preview under the proposed rules: option ${name} has a value starting with "-", so this gate was not run`,
1268
+ };
1269
+ }
1270
+ }
1271
+ // osv-scanner's call analysis builds the project it scans, and in the
1272
+ // preview that is the head's code (a Rust build.rs, for one).
1273
+ // Every option key is rendered as a flag, so the check is by key match:
1274
+ // any key containing "call-analysis" is refused unless it is the one
1275
+ // unambiguous all-off form, `no-call-analysis: true` or `all`. An absent
1276
+ // key is fine. Belt and braces: gateArgs appends --no-call-analysis=all
1277
+ // to every osv-scanner preview spawn as well.
1278
+ if (gate.product === 'osv-scanner' && !callAnalysisOff(gate.options)) {
1279
+ return {
1280
+ reason: 'preparation-failed',
1281
+ detail: "the preview does not run call analysis, because it would build the head's code",
1282
+ };
1283
+ }
1284
+ if (gate.command !== undefined && realPathInside(repoRoot, gate.command)) {
1285
+ return {
1286
+ reason: 'gate-program-refused',
1287
+ detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
1288
+ };
1289
+ }
1290
+ return null;
1291
+ }
1026
1292
  /**
1027
1293
  * Whether git says the repository at `repoRoot` is shallow. Anything other
1028
1294
  * than a clear "true" (no git, an old git that does not know the flag) is
@@ -1046,9 +1312,10 @@ function isShallowRepository(repoRoot) {
1046
1312
  function runGateInner(gate, options, started, progress) {
1047
1313
  // Every spawn of this gate gets the FULL limit, not a share of it: the
1048
1314
  // version probe, the scan and, on a compared pull request, osv-scanner's
1049
- // base run. Onto `progress` so every outcome from here on carries it.
1315
+ // base run. Onto `progress` so every outcome from here on carries it. In
1316
+ // the preview each spawn gets the smaller of this and what is left of the
1317
+ // preview's budget (spawnLimits), and the outcome says which it was.
1050
1318
  const timeLimit = resolveTimeLimit(gate, options.timeoutMs);
1051
- const timeoutMs = timeLimit.ms;
1052
1319
  Object.assign(progress, { timeLimit });
1053
1320
  const ownOption = gateOwnTimeoutNote(gate, timeLimit, options.trustBase);
1054
1321
  if (ownOption !== null) {
@@ -1068,6 +1335,24 @@ function runGateInner(gate, options, started, progress) {
1068
1335
  Object.assign(progress, { nodeModulesSkipped: skipped });
1069
1336
  }
1070
1337
  const base = progress;
1338
+ // THE PREVIEW'S OWN REFUSALS, before resolution and before any spawn, the
1339
+ // version probe included. The primary run needs neither.
1340
+ if (options.preview !== undefined) {
1341
+ const refused = previewRefusal(gate, options.repoRoot);
1342
+ if (refused !== null) {
1343
+ return {
1344
+ ...base,
1345
+ // Enforced under a trust base, like every refusal there; the preview
1346
+ // never reaches the exit code either way.
1347
+ enforce: options.trustBase !== undefined ? true : gate.enforce,
1348
+ durationMs: Date.now() - started,
1349
+ couldNotRun: refused,
1350
+ findings: [normalizeFailedGate(gate.role, gate.product, refused.detail)],
1351
+ run: EMPTY_RUN,
1352
+ diagnostics: [],
1353
+ };
1354
+ }
1355
+ }
1071
1356
  let binary;
1072
1357
  try {
1073
1358
  binary = resolveGateBinary(gate, options.repoRoot, options.pathValue, { skipNodeModules });
@@ -1189,8 +1474,11 @@ function runGateInner(gate, options, started, progress) {
1189
1474
  diagnostics: [],
1190
1475
  };
1191
1476
  }
1192
- const probed = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
1477
+ const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit, options.preview);
1193
1478
  if (probed.kind === 'timed-out') {
1479
+ // The limit the probe ran under, which in the preview can be what was
1480
+ // left of the budget; onto `progress` so the outcome says so.
1481
+ Object.assign(progress, { timeLimit: probed.limit });
1194
1482
  // Stopped here, before the version floor and before decideTrustBase: a
1195
1483
  // timed-out probe is not an unreadable version (which on a pull request
1196
1484
  // would read as trust-base-unverified, a packaging problem that does not
@@ -1199,8 +1487,8 @@ function runGateInner(gate, options, started, progress) {
1199
1487
  // gate could not be placed inside the boundary. Enforced under the
1200
1488
  // Action's expected-version signal too, like version-unverified: the run
1201
1489
  // cannot show this is the pinned build.
1202
- const detail = timedOutDetail(gate, 'version-probe', timeLimit, probed.elapsedMs, options.trustBase);
1203
- const timedOut = timedOutRecord('version-probe', timeLimit, probed.elapsedMs, probed.signal);
1490
+ const detail = timedOutDetail(gate, 'version-probe', probed.limit, probed.elapsedMs, options.trustBase);
1491
+ const timedOut = timedOutRecord('version-probe', probed.limit, probed.elapsedMs, probed.signal);
1204
1492
  return {
1205
1493
  ...base,
1206
1494
  binary,
@@ -1226,41 +1514,10 @@ function runGateInner(gate, options, started, progress) {
1226
1514
  // `enforce: false` to be a decision about. No expectation (every plain run)
1227
1515
  // skips all of this.
1228
1516
  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
1517
  return {
1243
1518
  ...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,
1519
+ ...versionNotExpected(gate, binary, version, options.expectedVersion, options.repoRoot),
1259
1520
  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
1521
  };
1265
1522
  }
1266
1523
  // The command-line floor. Only the external tools have one: the umbrella
@@ -1291,7 +1548,7 @@ function runGateInner(gate, options, started, progress) {
1291
1548
  // decision reads the version. That ordering is the whole capability gate:
1292
1549
  // a gate IN the table whose version is below its minimum, or could not be
1293
1550
  // read, is refused rather than run outside the boundary.
1294
- const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
1551
+ const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version, options.preview !== undefined);
1295
1552
  if (trustBase !== undefined && trustBase.refused !== null) {
1296
1553
  return {
1297
1554
  ...base,
@@ -1417,7 +1674,7 @@ function spawnAndRead(ctx) {
1417
1674
  }
1418
1675
  const baseArgv = (copies) => [
1419
1676
  ...binary.argvPrefix,
1420
- ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }),
1677
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }, undefined, undefined, options.preview !== undefined),
1421
1678
  ];
1422
1679
  const checked = removed === null
1423
1680
  ? { kind: 'unverified', detail: `the base tree at ${decidedRef} could not be listed` }
@@ -1434,12 +1691,15 @@ function spawnAndRead(ctx) {
1434
1691
  baseArgv,
1435
1692
  budgetMs: input.budgetMs,
1436
1693
  spawn: (argv, cwd, budget) => {
1437
- const baseChild = spawnSync(binary.command, [...argv], {
1438
- cwd,
1439
- encoding: 'utf8',
1440
- timeout: budget,
1441
- maxBuffer: 64 * 1024 * 1024,
1442
- });
1694
+ const limits = spawnLimits({ ...timeLimit, ms: budget }, options.preview, undefined);
1695
+ const baseChild = limits.start
1696
+ ? spawnSync(binary.command, [...argv], {
1697
+ cwd,
1698
+ encoding: 'utf8',
1699
+ maxBuffer: 64 * 1024 * 1024,
1700
+ ...limits.options,
1701
+ })
1702
+ : notStartedResult();
1443
1703
  return {
1444
1704
  status: baseChild.status,
1445
1705
  stderr: stripAnsi(baseChild.stderr ?? ''),
@@ -1681,24 +1941,33 @@ function spawnAndRead(ctx) {
1681
1941
  // intentChangeChannel is pure, and runGateInner already returned on the one
1682
1942
  // outcome that does not spawn.
1683
1943
  const channel = intentChangeChannel(gate, options.intent, version);
1944
+ // In the preview, dep-guard and vault-guard are not handed --trust-base
1945
+ // (decideTrustBase), and dep-guard still measures the change against the
1946
+ // base ref: --base comes from the run's trust base, which stays set.
1947
+ const changeBase = options.preview !== undefined && trustBase?.withheld === PREVIEW_WITHHELD ? options.trustBase : undefined;
1684
1948
  const argv = [
1685
1949
  ...binary.argvPrefix,
1686
- ...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined),
1950
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined, changeBase, options.preview !== undefined),
1687
1951
  ];
1952
+ // A history gate reads git history, and replace refs or grafts can cut
1953
+ // that history without making the repository shallow. Ignoring replace
1954
+ // objects makes it read the real commits. Other gates keep the inherited
1955
+ // environment untouched, outside the preview.
1956
+ const scanLimits = spawnLimits(timeLimit, options.preview, profile.readsHistory ? { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } : undefined);
1957
+ if (scanLimits.limit !== timeLimit) {
1958
+ Object.assign(progress, { timeLimit: scanLimits.limit });
1959
+ }
1688
1960
  // Taken just before the call, so a timed-out message's elapsed time is the
1689
1961
  // scan's own and not resolution plus the version probe.
1690
1962
  const spawnStarted = Date.now();
1691
- const child = spawnSync(binary.command, argv, {
1692
- cwd: spawnCwd,
1693
- encoding: 'utf8',
1694
- timeout: timeoutMs,
1695
- maxBuffer: 64 * 1024 * 1024,
1696
- // A history gate reads git history, and replace refs or grafts can cut
1697
- // that history without making the repository shallow. Ignoring replace
1698
- // objects makes it read the real commits. Other gates keep the
1699
- // inherited environment untouched.
1700
- ...(profile.readsHistory ? { env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } } : {}),
1701
- });
1963
+ const child = scanLimits.start
1964
+ ? spawnSync(binary.command, argv, {
1965
+ cwd: spawnCwd,
1966
+ encoding: 'utf8',
1967
+ maxBuffer: 64 * 1024 * 1024,
1968
+ ...scanLimits.options,
1969
+ })
1970
+ : notStartedResult();
1702
1971
  const withRun = {
1703
1972
  ...base,
1704
1973
  productVersion: version,
@@ -1740,8 +2009,8 @@ function spawnAndRead(ctx) {
1740
2009
  if (failure !== null) {
1741
2010
  if (failure.reason === 'timed-out') {
1742
2011
  const elapsedMs = Date.now() - spawnStarted;
1743
- const detail = timedOutDetail(gate, 'scan', timeLimit, elapsedMs, options.trustBase);
1744
- const timedOut = timedOutRecord('scan', timeLimit, elapsedMs, failure.signal);
2012
+ const detail = timedOutDetail(gate, 'scan', scanLimits.limit, elapsedMs, options.trustBase);
2013
+ const timedOut = timedOutRecord('scan', scanLimits.limit, elapsedMs, failure.signal);
1745
2014
  return {
1746
2015
  ...withRun,
1747
2016
  exitCode: null,
@@ -1989,15 +2258,18 @@ function spawnAndRead(ctx) {
1989
2258
  headArgv: argv,
1990
2259
  baseArgv: (copies) => [
1991
2260
  ...binary.argvPrefix,
1992
- ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }),
2261
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }, undefined, undefined, options.preview !== undefined),
1993
2262
  ],
1994
2263
  spawn: (baseArgv, cwd) => {
1995
- const baseChild = spawnSync(binary.command, [...baseArgv], {
1996
- cwd,
1997
- encoding: 'utf8',
1998
- timeout: timeoutMs,
1999
- maxBuffer: 64 * 1024 * 1024,
2000
- });
2264
+ const limits = spawnLimits(timeLimit, options.preview, undefined);
2265
+ const baseChild = limits.start
2266
+ ? spawnSync(binary.command, [...baseArgv], {
2267
+ cwd,
2268
+ encoding: 'utf8',
2269
+ maxBuffer: 64 * 1024 * 1024,
2270
+ ...limits.options,
2271
+ })
2272
+ : notStartedResult();
2001
2273
  return { status: baseChild.status, stdout: baseChild.stdout ?? '', error: baseChild.error };
2002
2274
  },
2003
2275
  rootSpellings,
@@ -1,5 +1,5 @@
1
- import type { GateOutcome } from './gate-runner.js';
2
- import type { RunResult } from './run.js';
1
+ import { type GateOutcome } from './gate-runner.js';
2
+ import { type RunResult } from './run.js';
3
3
  export declare const UMBRELLA_DRIVER_NAME = "conductor";
4
4
  /** The partialFingerprints key for a product's own fingerprint. */
5
5
  export declare function fingerprintKey(scope: string): string;