rungate 0.5.0 → 0.7.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.
Files changed (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -26,6 +26,7 @@ import {
26
26
  mkdirSync,
27
27
  openSync,
28
28
  readFileSync,
29
+ realpathSync,
29
30
  renameSync,
30
31
  statSync,
31
32
  unlinkSync,
@@ -36,6 +37,7 @@ import { execFileSync } from "child_process";
36
37
  import { createHash } from "crypto";
37
38
  import { tmpdir } from "os";
38
39
  import { join } from "path";
40
+ import { readProcessTable, type ProcessRow } from "./process-table";
39
41
 
40
42
  /**
41
43
  * Suites allowed to run AT ONCE. Measured, not chosen: one full suite peaks at
@@ -537,27 +539,169 @@ function segmentIsFullSuite(segment: string, depth = 0): boolean {
537
539
  */
538
540
  const LIVENESS_GRACE_SECONDS = 25;
539
541
 
542
+ /** The spelling of a suite that the command line itself carries. */
543
+ const SPELLED_BUN = /(^|\/|\s)bun\s+(run\s+)?test(\s|$)/;
544
+
545
+ /** `test` or `run test` as the first arguments after argv[0]. */
546
+ const SUITE_ARGUMENTS = /^\s+(run\s+)?test(\s|$)/;
547
+
548
+ /** What one `ps` command line is. `unknown` is a reading, not a default. */
549
+ export type PsLineReading = "suite" | "not-suite" | "unknown";
550
+
551
+ /** How argv[0] is resolved to the file it actually names. Injected for tests. */
552
+ export type ExecutableResolver = (path: string) => string;
553
+
554
+ /**
555
+ * The one place a `ps` line is judged to be a running suite (#707).
556
+ *
557
+ * Exported so there is exactly one binding to mutate and one thing for a
558
+ * case to drive over a table of real command lines. `suiteLiveness` reads
559
+ * the process table; this decides what a line means, and the two questions
560
+ * are separable only because they are separate functions. **The orphan
561
+ * reaper in `lib/orphan-reaper.ts` asks this same binding**, so the thing
562
+ * that decides what keeps a slot and the thing that decides what may be
563
+ * killed cannot drift apart — which is the whole of the #690/#707 pairing.
564
+ *
565
+ * ## Widening the leading boundary buys nothing, and that is still true
566
+ *
567
+ * `/tmp/brun test` is the documented workaround for #690, and `brun` is
568
+ * b-r-u-n: it **does not contain `bun` at all**, so no loosening of a
569
+ * pattern written over the string `bun` can ever match it. Measured:
570
+ * `"brun".includes("bun")` is `false`. #727 established this and reverted
571
+ * the widening, and nothing below re-litigates it — `SPELLED_BUN` is
572
+ * unchanged.
573
+ *
574
+ * ## What is new: ask the filesystem what the executable IS
575
+ *
576
+ * The workaround is a SYMLINK — measured on this machine, 2026-10-21:
577
+ * `/tmp/brun -> /opt/homebrew/bin/bun`, which `realpath`s to
578
+ * `/opt/homebrew/Cellar/bun/<version>/bin/bun`. So the name is an evasion
579
+ * and the identity is not. When a line's ARGUMENTS are a suite invocation
580
+ * (`<exe> test …` or `<exe> run test …`) but argv[0] is not spelled `bun`,
581
+ * this resolves argv[0] on disk and reads the basename of what it points
582
+ * at. A renamed or symlinked launcher is a `suite`; a resolution that
583
+ * cannot be taken is `unknown`.
584
+ *
585
+ * This is the liveness signal "that is not the process name at all" which
586
+ * the previous revision of this comment asked for, arriving as the
587
+ * executable's identity rather than as a heartbeat. A heartbeat was the
588
+ * other candidate and it is not available at this layer: the slot is taken
589
+ * by a PreToolUse hook that exits immediately, and a session running a
590
+ * foreground suite makes no tool calls while it waits, so nothing exists
591
+ * that could refresh the file.
592
+ *
593
+ * ## The two directions, and why they are not symmetric
594
+ *
595
+ * A resolution that fails, or an argv[0] that is not an absolute path, is
596
+ * `unknown` — and so is a binary whose resolved basename is something else,
597
+ * because a *copy* of bun under another name resolves to itself and no
598
+ * cheap reading can tell it from an unrelated program called with a `test`
599
+ * argument. The two consumers read that third state in OPPOSITE directions,
600
+ * deliberately:
601
+ *
602
+ * - **Keeping a slot** needs "not positively idle", so `unknown` keeps it.
603
+ * Over-detection costs at most one wedged slot for a TTL. Missing a suite
604
+ * that IS there reclaims a live slot and lets two real suites run against
605
+ * a cap of one, which is the OOM condition this whole mechanism prevents.
606
+ * - **Killing a process** needs "positively a suite", so `unknown` is never
607
+ * reaped. Over-detection there costs somebody else's work.
608
+ *
609
+ * The cost of the conservative reading is bounded and worth naming: one
610
+ * long-lived unrelated `/usr/bin/foo test` process makes the machine read
611
+ * `unknown`, which switches the early liveness reclaim off and leaves the
612
+ * 420-second TTL as the only staleness rule. That is the pre-#74 behaviour,
613
+ * not a new failure mode.
614
+ */
615
+ export function classifyPsLine(
616
+ line: string,
617
+ options: { resolveExecutable?: ExecutableResolver } = {},
618
+ ): PsLineReading {
619
+ if (SPELLED_BUN.test(line)) return "suite";
620
+
621
+ const space = line.indexOf(" ");
622
+ if (space <= 0) return "not-suite";
623
+ const argv0 = line.slice(0, space);
624
+ if (!SUITE_ARGUMENTS.test(line.slice(space))) return "not-suite";
625
+
626
+ // The arguments say "suite" and the name does not. Everything from here is
627
+ // a question about the file on disk, which is the thing a rename cannot
628
+ // change.
629
+ if (!argv0.startsWith("/")) return "unknown";
630
+ let resolved: string;
631
+ try {
632
+ resolved = (options.resolveExecutable ?? realpathSync)(argv0);
633
+ } catch {
634
+ return "unknown";
635
+ }
636
+ return resolved.slice(resolved.lastIndexOf("/") + 1) === "bun" ? "suite" : "unknown";
637
+ }
638
+
639
+ /**
640
+ * `psLineIsSuite` as it has always behaved: a projection of the reading
641
+ * above, kept because callers and cases already name it.
642
+ *
643
+ * It is a PROJECTION and not a second decider — there is one `classifyPsLine`
644
+ * and this restates its answer — so a mutation of the classifier moves this
645
+ * too, which is the property that makes the battery able to see either.
646
+ */
647
+ export function psLineIsSuite(
648
+ line: string,
649
+ options: { resolveExecutable?: ExecutableResolver } = {},
650
+ ): boolean {
651
+ return classifyPsLine(line, options) === "suite";
652
+ }
653
+
654
+ /** What the machine as a whole is doing. `unknown` is a reading. */
655
+ export type SuiteLiveness = "running" | "idle" | "unknown";
656
+
657
+ export interface LivenessOptions {
658
+ rows?: ProcessRow[];
659
+ readRows?: () => ProcessRow[];
660
+ resolveExecutable?: ExecutableResolver;
661
+ }
662
+
540
663
  /**
541
- * True when at least one full suite is running anywhere on this machine.
664
+ * Whether any full suite is running anywhere on this machine.
542
665
  *
543
- * ONLY THE ZERO CASE IS USED, deliberately. #67 established that attributing
544
- * bun processes to sessions is unreliable — the agentgrit suite leaks ~31
545
- * dangling bun processes per run, which is why slots are files rather than a
546
- * process count. This does not attribute anything: a slot means a running
547
- * suite, so if NO suite is running at all, every slot is provably false.
666
+ * ONLY THE `idle` CASE IS ACTED ON, deliberately. #67 established that
667
+ * attributing bun processes to sessions is unreliable — the agentgrit suite
668
+ * leaks ~31 dangling bun processes per run, which is why slots are files
669
+ * rather than a process count. This does not attribute anything: a slot
670
+ * means a running suite, so if NO suite is running at all, every slot is
671
+ * provably false.
548
672
  *
549
- * Matches on the command line rather than the executable name. `pgrep -f bun`
550
- * is useless here — it matches powerd's bundle paths, mdbulkimport and any
551
- * other command containing "bun" as a substring.
673
+ * `idle` is therefore a POSITIVE claim and it is made only when the whole
674
+ * table was read and every row was classified. One unclassifiable row makes
675
+ * the reading `unknown`, because `idle` is the only reading that lets a live
676
+ * slot be taken away from somebody.
677
+ */
678
+ export function suiteLiveness(options: LivenessOptions = {}): SuiteLiveness {
679
+ let rows: ProcessRow[];
680
+ try {
681
+ rows = options.rows ?? (options.readRows ?? readProcessTable)();
682
+ } catch {
683
+ return "unknown";
684
+ }
685
+ let sawUnknown = false;
686
+ for (const row of rows) {
687
+ const reading = classifyPsLine(row.command, options);
688
+ if (reading === "suite") return "running";
689
+ if (reading === "unknown") sawUnknown = true;
690
+ }
691
+ return sawUnknown ? "unknown" : "idle";
692
+ }
693
+
694
+ /**
695
+ * True when the machine is NOT positively idle.
552
696
  *
553
- * Throws rather than guessing when the process table cannot be read; the
554
- * caller treats that as "cannot determine" and keeps the slot.
697
+ * The collapse is one-sided on purpose: `unknown` reads as `true` here, so a
698
+ * caller that only wants "may I take this slot away" gets the safe answer
699
+ * without having to remember which way round the third state goes. A caller
700
+ * that needs to tell `unknown` from `running` asks `suiteLiveness` — and the
701
+ * reaper does, because the opposite collapse would kill on a guess.
555
702
  */
556
- export function anySuiteRunning(): boolean {
557
- const out = execFileSync("ps", ["-axo", "command"], { encoding: "utf-8" });
558
- return out
559
- .split("\n")
560
- .some(line => /(^|\/|\s)bun\s+(run\s+)?test(\s|$)/.test(line));
703
+ export function anySuiteRunning(options: LivenessOptions = {}): boolean {
704
+ return suiteLiveness(options) !== "idle";
561
705
  }
562
706
 
563
707
  /**
@@ -708,6 +852,13 @@ export function acquireFullSuiteSlot(
708
852
 
709
853
  export interface GateDecision {
710
854
  allow: boolean;
855
+ /**
856
+ * Present when the run was allowed because it is not a run of THIS
857
+ * repository (#510). Allowed-and-quiet would make an exemption
858
+ * indistinguishable from a budget that was never spent, so it is named
859
+ * here and recorded on disk.
860
+ */
861
+ exempt?: string;
711
862
  /** Present when refused — shown verbatim to the caller. Never silent. */
712
863
  reason?: string;
713
864
  /**
@@ -860,6 +1011,117 @@ export interface GateOptions extends LockOptions {
860
1011
  runId?: string;
861
1012
  /** Overrides the per-run ceiling. Tests only; there is no environment path. */
862
1013
  maxRunsPerPipeline?: number;
1014
+ /**
1015
+ * The working directory the command will run in (#510). Used to decide
1016
+ * whether this is a run of the guarded repository or of a scratch tree
1017
+ * somewhere else. Absent means UNKNOWN, which is charged — the budget
1018
+ * fails closed, as the rest of this module does.
1019
+ */
1020
+ cwd?: string;
1021
+ /** Injected scope, so a test need not build a git repository to drive it. */
1022
+ scope?: RunScope;
1023
+ }
1024
+
1025
+ /**
1026
+ * Whose suite this is.
1027
+ *
1028
+ * - `project` — a tree of the repository this guard belongs to, including
1029
+ * every one of its worktrees. Charged.
1030
+ * - `scratch` — a directory that EXISTS and is not part of it: a `git
1031
+ * archive` export under /tmp, a fixture repo a test just created, another
1032
+ * checkout entirely. Not charged.
1033
+ * - `unknown` — the question could not be answered: no cwd, a path that is
1034
+ * not there, a git that would not run. Charged, because a guard that opens
1035
+ * on an error is the shape this repo keeps finding.
1036
+ *
1037
+ * The line between the last two is "I looked and it is not this repository"
1038
+ * against "I could not look". A `git archive` export has no `.git` and is
1039
+ * the case that filed #510, so a git-less directory must be scratch — but
1040
+ * only once something has confirmed the directory is really there.
1041
+ */
1042
+ export type RunScope = "project" | "scratch" | "unknown";
1043
+
1044
+ /** The guarded repository's shared git directory, resolved once. */
1045
+ function projectCommonDir(): string | null {
1046
+ try {
1047
+ const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
1048
+ cwd: join(import.meta.dir, ".."),
1049
+ encoding: "utf-8",
1050
+ timeout: 10_000,
1051
+ stdio: ["ignore", "pipe", "pipe"],
1052
+ });
1053
+ return realpathSync(out.trim());
1054
+ } catch {
1055
+ return null;
1056
+ }
1057
+ }
1058
+
1059
+ /**
1060
+ * Is this working directory part of the repository the guard is installed in?
1061
+ *
1062
+ * The comparison is the **shared git directory**, not the path: all 110
1063
+ * worktrees of this repository answer with one `.git`, and they are all real
1064
+ * runs that must be charged. A `git archive` export has no `.git` at all, and
1065
+ * a fixture built by `git init` has its own — both scratch.
1066
+ *
1067
+ * ## Why this is not a /tmp denylist
1068
+ *
1069
+ * A path prefix is a detector narrower than what it detects: a reviewer's
1070
+ * probe under `~/scratch` would be charged, and a real checkout under /tmp
1071
+ * would be exempt. The question is "whose suite is this", and git already
1072
+ * answers it exactly.
1073
+ */
1074
+ export function runScope(cwd: string | undefined, projectDir?: string | null): RunScope {
1075
+ if (!cwd) return "unknown";
1076
+ try {
1077
+ if (!statSync(cwd).isDirectory()) return "unknown";
1078
+ } catch {
1079
+ return "unknown";
1080
+ }
1081
+ const project = projectDir === undefined ? projectCommonDir() : projectDir;
1082
+ if (project === null) return "unknown";
1083
+ try {
1084
+ const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
1085
+ cwd,
1086
+ encoding: "utf-8",
1087
+ timeout: 10_000,
1088
+ stdio: ["ignore", "pipe", "pipe"],
1089
+ });
1090
+ return realpathSync(out.trim()) === project ? "project" : "scratch";
1091
+ } catch {
1092
+ // The directory is there and git will not claim it: not a repository at
1093
+ // all, which is what a `git archive` export is. Not a run of the guarded
1094
+ // project, and charging it is the thing #510 is about.
1095
+ return "scratch";
1096
+ }
1097
+ }
1098
+
1099
+ /** Where exempted runs are recorded, so the exemption is auditable. */
1100
+ export function scratchRunsPath(lockDir: string): string {
1101
+ return join(lockDir, "full-suite.scratch-runs.json");
1102
+ }
1103
+
1104
+ /**
1105
+ * Record an exempted run. Best-effort, like the budget counter — but it is
1106
+ * the only trace an exemption leaves, so losing it costs visibility rather
1107
+ * than enforcement.
1108
+ */
1109
+ function recordScratchRun(lockDir: string, now: number, cwd: string | undefined): void {
1110
+ try {
1111
+ const path = scratchRunsPath(lockDir);
1112
+ let runs: Array<{ at: number; cwd: string }> = [];
1113
+ try {
1114
+ const parsed = JSON.parse(readFileSync(path, "utf-8"));
1115
+ if (Array.isArray(parsed?.runs)) runs = parsed.runs;
1116
+ } catch {
1117
+ // An unreadable or absent log starts a new one. This file is a record,
1118
+ // never an input to a decision, so a lost entry cannot open a gate.
1119
+ }
1120
+ runs.push({ at: now, cwd: cwd ?? "" });
1121
+ writeFileSync(path, JSON.stringify({ runs: runs.slice(-200) }));
1122
+ } catch {
1123
+ // Recording must never be able to block a run it is not guarding.
1124
+ }
863
1125
  }
864
1126
 
865
1127
  interface BudgetView {
@@ -1045,19 +1307,53 @@ export function evaluateFullSuiteRequest(
1045
1307
  command: string,
1046
1308
  options: GateOptions = {},
1047
1309
  ): GateDecision {
1048
- const predicted = wouldAllowFullSuite(sessionId, command, options);
1049
- if (!predicted.allow) return predicted;
1050
- // Targeted runs are neither capped nor counted, so there is nothing to spend.
1310
+ // Targeted runs are neither capped nor counted, so there is nothing to
1311
+ // spend. Asked FIRST, because the scope question below costs a subprocess
1312
+ // and the overwhelming majority of Bash commands are not suites at all.
1051
1313
  if (!isFullSuiteCommand(command)) return { allow: true };
1052
1314
 
1053
1315
  const lockDir = options.lockDir ?? defaultLockDir();
1054
1316
  const now = options.now ?? Date.now();
1055
1317
 
1318
+ // A full suite of somebody else's tree is not this repository's suite
1319
+ // (#510). A reviewer's mutation probe on a `git archive` export is twenty
1320
+ // tests and under a second, and charging it against a budget sized for a
1321
+ // 400-second 12,000-test run made careful review the thing the guard
1322
+ // rationed. Scope is decided here and only here: `wouldAllowFullSuite`
1323
+ // below must not answer the same question, or there would be two deciders
1324
+ // and no behavioural test could tell them apart.
1325
+ //
1326
+ // It exempts the BUDGET and not the concurrency slot, and the distinction
1327
+ // is the whole of the design. The budget is a rate — the wrong unit for a
1328
+ // one-second probe. The slot is simultaneity, which is what rebooted the
1329
+ // machine in #67, and a scratch tree can be a full clone. Two further
1330
+ // reasons it must not skip the slot: `TestSuiteRelease` releases on the
1331
+ // same `isFullSuiteCommand` predicate with no notion of scope, so an
1332
+ // acquire this side skipped would free a slot somebody else is holding;
1333
+ // and "cd into /tmp to escape the cap" would be a bypass anyone could
1334
+ // reach for.
1335
+ const scope = options.scope ?? runScope(options.cwd);
1336
+
1337
+ const predicted = scope === "scratch" ? { allow: true } : wouldAllowFullSuite(sessionId, command, options);
1338
+ if (!predicted.allow) return predicted;
1339
+
1056
1340
  // The prediction above is advisory; this is the atomic claim. Another session
1057
1341
  // can take the last slot in between, and then the acquirer's answer wins.
1058
1342
  const slot = acquireFullSuiteSlot(sessionId, options);
1059
1343
  if (!slot.ok) return concurrencyRefusal(sessionId, slot.holders ?? []);
1060
1344
 
1345
+ if (scope === "scratch") {
1346
+ recordScratchRun(lockDir, now, options.cwd);
1347
+ return {
1348
+ allow: true,
1349
+ exempt:
1350
+ `not a run of this repository (${options.cwd ?? "unknown cwd"}), so it is not charged ` +
1351
+ `against DIR-L29 — recorded in ${scratchRunsPath(lockDir)}. It still holds a ` +
1352
+ `concurrency slot, which is what the cap is actually for.`,
1353
+ ...(slot.degraded ? { warning: degradedWarning(lockDir) } : {}),
1354
+ };
1355
+ }
1356
+
1061
1357
  try {
1062
1358
  // Only the in-window runs are carried forward, and never more than the
1063
1359
  // tracked maximum, so neither a long session nor a poisoned file can leave
@@ -1078,17 +1374,20 @@ export function evaluateFullSuiteRequest(
1078
1374
  }
1079
1375
 
1080
1376
  if (slot.degraded) {
1081
- return {
1082
- allow: true,
1083
- warning:
1084
- `Concurrency guard DEGRADED — lock directory ${lockDir} is unusable, so this run ` +
1085
- `was allowed without taking a slot. The cap is not being enforced right now. ` +
1086
- `Check with other sessions before starting a full suite.`,
1087
- };
1377
+ return { allow: true, warning: degradedWarning(lockDir) };
1088
1378
  }
1089
1379
  return { allow: true };
1090
1380
  }
1091
1381
 
1382
+ /** One wording for the degraded case, so the two exits cannot drift apart. */
1383
+ function degradedWarning(lockDir: string): string {
1384
+ return (
1385
+ `Concurrency guard DEGRADED — lock directory ${lockDir} is unusable, so this run ` +
1386
+ `was allowed without taking a slot. The cap is not being enforced right now. ` +
1387
+ `Check with other sessions before starting a full suite.`
1388
+ );
1389
+ }
1390
+
1092
1391
  /**
1093
1392
  * Give up ONE slot for a finished suite. Releasing one you do not hold is a no-op.
1094
1393
  *
@@ -0,0 +1,142 @@
1
+ /**
2
+ * Asking whether an external tool is there, with three answers instead of one
3
+ * (#626 AC-10, #597).
4
+ *
5
+ * `lib/compliance.ts` asked it with a boolean:
6
+ *
7
+ * function checkToolAvailable(command, args): boolean {
8
+ * try {
9
+ * const result = Bun.spawnSync([command, ...args], { timeout: 5_000 });
10
+ * return result.exitCode === 0 || result.stdout.toString().length > 0;
11
+ * } catch { return false; }
12
+ * }
13
+ *
14
+ * `false` meant "the tool is not installed", "the tool is installed and the
15
+ * probe failed", and "npx went to the registry and the registry was slow"
16
+ * alike. That is the fail-open shape `.claude/rules/checks-must-be-able-to-fail.md`
17
+ * opens with, in the place it costs the most: three Layer 1 compliance tests
18
+ * go red or green in CI depending on whether `npx @reporails/cli version`
19
+ * reaches the network, and the verdict cannot say which of the three happened
20
+ * — proven on #597 by re-running an identical SHA red to green with no code
21
+ * change.
22
+ *
23
+ * So the probe has three outcomes and a `reason`, and the boolean every
24
+ * existing caller wants is derived from the outcome rather than being the
25
+ * whole reading. A consumer that only needs "can I run this" keeps working;
26
+ * a consumer that needs to report UNMEASURED now has something to report it
27
+ * from.
28
+ *
29
+ * ## Why `absent` is decided by the spawn failing, not by an exit code
30
+ *
31
+ * A tool that is not on `PATH` makes `Bun.spawnSync` throw before any process
32
+ * exists; a tool that is there and unhappy exits non-zero. Those are the two
33
+ * facts, and they arrive by two different routes, which is what makes the
34
+ * distinction honest rather than a reading of an exit code nobody standardised.
35
+ *
36
+ * `npx <pkg> version` is the awkward case and is deliberately NOT special-cased:
37
+ * `npx` is always present, so an uninstalled package surfaces as `errored`, not
38
+ * `absent`. That is the truth about what was observed — the probe ran and did
39
+ * not succeed — and inventing `absent` from a parse of npx's stderr would be a
40
+ * detector narrower than what it detects.
41
+ */
42
+
43
+ /** The three things a probe can find. Ordered as they are reported. */
44
+ export const TOOL_PROBE_OUTCOMES = ["available", "absent", "errored"] as const;
45
+
46
+ export type ToolProbeOutcome = (typeof TOOL_PROBE_OUTCOMES)[number];
47
+
48
+ export interface ToolProbe {
49
+ outcome: ToolProbeOutcome;
50
+ /**
51
+ * The old boolean, derived. Present so a caller that genuinely only needs
52
+ * "can I run this" does not have to re-derive it — and so the collapse is
53
+ * visible as a projection of the reading rather than as the reading itself.
54
+ */
55
+ available: boolean;
56
+ /** The command probed, as it was asked for. */
57
+ tool: string;
58
+ /** The exit code, or null when no process ever existed. */
59
+ exitCode: number | null;
60
+ /** One line a log reader can act on. */
61
+ reason: string;
62
+ }
63
+
64
+ export interface ToolProbeOptions {
65
+ timeoutMs?: number;
66
+ }
67
+
68
+ /**
69
+ * The one place that decides `available` from `outcome`.
70
+ *
71
+ * Every return below goes through it, and so does every caller that needs to
72
+ * state a reading it did not spawn — a test forcing a tool absent, a consumer
73
+ * replaying a recorded probe. Without it `available` is a field anyone can set,
74
+ * and a probe reporting `{ outcome: "absent", available: true }` would be a
75
+ * contradiction nothing could refuse. It is a projection of the reading, and
76
+ * the projection has an owner.
77
+ */
78
+ export function toolProbe(fields: {
79
+ outcome: ToolProbeOutcome;
80
+ tool: string;
81
+ exitCode?: number | null;
82
+ reason: string;
83
+ }): ToolProbe {
84
+ return {
85
+ outcome: fields.outcome,
86
+ available: fields.outcome === "available",
87
+ tool: fields.tool,
88
+ exitCode: fields.exitCode ?? null,
89
+ reason: fields.reason,
90
+ };
91
+ }
92
+
93
+ /** The probe's own budget. A tool that cannot answer in five seconds is not ready to be used in a gate. */
94
+ export const TOOL_PROBE_TIMEOUT_MS = 5_000;
95
+
96
+ export function probeExternalTool(command: string, args: string[] = [], opts?: ToolProbeOptions): ToolProbe {
97
+ const tool = [command, ...args].join(" ");
98
+ let exitCode: number | null = null;
99
+ let stdout = "";
100
+ let stderr = "";
101
+
102
+ try {
103
+ const result = Bun.spawnSync([command, ...args], {
104
+ timeout: opts?.timeoutMs ?? TOOL_PROBE_TIMEOUT_MS,
105
+ stdout: "pipe",
106
+ stderr: "pipe",
107
+ });
108
+ exitCode = typeof result.exitCode === "number" ? result.exitCode : null;
109
+ stdout = result.stdout?.toString() ?? "";
110
+ stderr = result.stderr?.toString() ?? "";
111
+ } catch (e) {
112
+ // No process was created at all. That is the one condition that means the
113
+ // tool is not here, and it is why this branch is not merged with a
114
+ // non-zero exit below.
115
+ const message = e instanceof Error ? e.message : String(e);
116
+ return toolProbe({
117
+ outcome: "absent",
118
+ tool,
119
+ exitCode: null,
120
+ reason: `${command} is not on PATH: ${message.split("\n")[0]}`,
121
+ });
122
+ }
123
+
124
+ if (exitCode === 0 || stdout.trim().length > 0) {
125
+ return toolProbe({
126
+ outcome: "available",
127
+ tool,
128
+ exitCode,
129
+ reason: `${tool} ran and answered (exit ${exitCode})`,
130
+ });
131
+ }
132
+
133
+ return toolProbe({
134
+ outcome: "errored",
135
+ tool,
136
+ exitCode,
137
+ reason:
138
+ `${tool} ran and did not succeed (exit ${exitCode})` +
139
+ (stderr.trim() ? `: ${stderr.trim().split("\n")[0].slice(0, 200)}` : "") +
140
+ ` — the tool was reachable, so this is not the same as it being absent`,
141
+ });
142
+ }