rungate 0.6.0 → 0.8.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 (164) hide show
  1. package/hooks/ActionVerificationGate.hook.ts +96 -0
  2. package/hooks/AgentBriefGuard.hook.ts +38 -0
  3. package/hooks/AgentVerdictCapture.hook.ts +87 -0
  4. package/hooks/AutoVerifyGate.hook.ts +79 -0
  5. package/hooks/BashToolGuard.hook.ts +65 -0
  6. package/hooks/BashWriteGuard.hook.ts +60 -0
  7. package/hooks/CommitEnforcement.hook.ts +130 -0
  8. package/hooks/DocHygiene.hook.ts +148 -0
  9. package/hooks/GateEnforcement.hook.ts +58 -0
  10. package/hooks/GateResultProtection.hook.ts +69 -0
  11. package/hooks/HarnessAFKGate.hook.ts +85 -0
  12. package/hooks/HookCurrency.hook.ts +99 -0
  13. package/hooks/IssueCloseGuard.hook.ts +149 -0
  14. package/hooks/MergeGuard.hook.ts +58 -0
  15. package/hooks/PostCompact.hook.ts +60 -0
  16. package/hooks/ProjectStateSync.hook.ts +103 -0
  17. package/hooks/SkillGuard.hook.ts +69 -0
  18. package/hooks/SpecConformityTrigger.hook.ts +43 -0
  19. package/hooks/SpecSCGuard.hook.ts +123 -0
  20. package/hooks/StaleTTLCleanup.hook.ts +141 -0
  21. package/hooks/TaskCompleted.hook.ts +51 -0
  22. package/hooks/TeamInit.hook.ts +85 -0
  23. package/hooks/TestSuiteGuard.hook.ts +70 -0
  24. package/hooks/TestSuiteRelease.hook.ts +85 -0
  25. package/hooks/TopLevelCdGuard.hook.ts +108 -0
  26. package/hooks/VerifyPhaseLock.hook.ts +84 -0
  27. package/hooks/WorkflowStateGuard.hook.ts +40 -0
  28. package/hooks/lib/agent-config.json +9 -0
  29. package/hooks/lib/agentDetection.ts +201 -0
  30. package/hooks/lib/comment-template.ts +86 -0
  31. package/hooks/lib/findWorkflow.ts +101 -0
  32. package/hooks/lib/parseStdin.ts +37 -0
  33. package/hooks/lib/paths.ts +111 -0
  34. package/hooks/lib/utils.ts +338 -0
  35. package/lib/affected-tests.ts +427 -0
  36. package/lib/agent-audit.ts +2 -3
  37. package/lib/agent-worktree.ts +287 -0
  38. package/lib/agents-md-sections.ts +81 -16
  39. package/lib/bash-write-guard.ts +373 -0
  40. package/lib/behavioral-cache.ts +150 -2
  41. package/lib/branch-cleanup.ts +279 -7
  42. package/lib/branch-protection.ts +790 -0
  43. package/lib/brief-ac-alignment.ts +104 -0
  44. package/lib/brief-references.ts +205 -0
  45. package/lib/bun-version.ts +93 -14
  46. package/lib/check-remedy.ts +140 -0
  47. package/lib/ci-checkout.ts +17 -0
  48. package/lib/ci-history-depth.ts +159 -0
  49. package/lib/ci-setup-step.ts +96 -0
  50. package/lib/claude-code-action.ts +85 -0
  51. package/lib/claude-tool-vocabulary.ts +188 -0
  52. package/lib/cli-commands.ts +15 -0
  53. package/lib/commit-sha.ts +42 -0
  54. package/lib/commit-subject.ts +90 -0
  55. package/lib/compliance-report.ts +377 -45
  56. package/lib/compliance.ts +191 -17
  57. package/lib/config-loader.ts +39 -1
  58. package/lib/config-trackable.ts +400 -0
  59. package/lib/conformity.ts +1087 -100
  60. package/lib/containment.ts +238 -0
  61. package/lib/content-hash.ts +24 -0
  62. package/lib/create-sc.ts +249 -16
  63. package/lib/dev-liveness.ts +180 -0
  64. package/lib/discovery-branch-points.ts +432 -0
  65. package/lib/discovery-stability.ts +481 -0
  66. package/lib/distribution-currency.ts +236 -0
  67. package/lib/doc-routing.ts +157 -0
  68. package/lib/evidence-prevalidator.ts +224 -2
  69. package/lib/evidence-satisfiability.ts +534 -12
  70. package/lib/failure-intake.ts +323 -0
  71. package/lib/fallow-availability.ts +157 -0
  72. package/lib/fs-write-capabilities.ts +232 -0
  73. package/lib/gate-enforcement.ts +222 -28
  74. package/lib/gate-names.ts +72 -0
  75. package/lib/gate-result-protection.ts +427 -0
  76. package/lib/gate-run-split.ts +147 -0
  77. package/lib/generators/agents-md.ts +140 -32
  78. package/lib/git-isolation.ts +140 -0
  79. package/lib/github.ts +15 -0
  80. package/lib/google-auth-action.ts +93 -0
  81. package/lib/harness-project.ts +48 -0
  82. package/lib/harness-provenance.ts +255 -0
  83. package/lib/hook-evidence.ts +235 -0
  84. package/lib/hook-scopes.ts +386 -0
  85. package/lib/hook-target-tree.ts +398 -0
  86. package/lib/hook-trees.ts +447 -0
  87. package/lib/intake-sources.ts +380 -0
  88. package/lib/js-top-level-code.ts +78 -10
  89. package/lib/junit-checks.ts +52 -0
  90. package/lib/late-env-spawn.ts +331 -0
  91. package/lib/launch-base.ts +376 -0
  92. package/lib/line-citation.ts +372 -0
  93. package/lib/orphan-reaper.ts +468 -0
  94. package/lib/parity-binding.ts +205 -0
  95. package/lib/paths.ts +96 -3
  96. package/lib/per-test-timeouts.ts +219 -0
  97. package/lib/phase2-decomposition.ts +1 -1
  98. package/lib/plan-coverage.ts +151 -0
  99. package/lib/prior-branch.ts +201 -8
  100. package/lib/process-table.ts +146 -0
  101. package/lib/project-state-derivation.ts +219 -0
  102. package/lib/project-state-root.ts +258 -0
  103. package/lib/published-artifact.ts +669 -0
  104. package/lib/readdir-sorted.ts +45 -0
  105. package/lib/review-execution-reading.ts +206 -0
  106. package/lib/review-tool-agreement.ts +433 -0
  107. package/lib/rule-promotion.ts +234 -0
  108. package/lib/rule-retirement.ts +525 -0
  109. package/lib/run-branch.ts +612 -0
  110. package/lib/rungate-schema.ts +19 -0
  111. package/lib/runner-home.ts +274 -0
  112. package/lib/sc-id-cross-tree.ts +103 -15
  113. package/lib/sc-ids.ts +121 -13
  114. package/lib/sc-reservations.ts +289 -0
  115. package/lib/scaffold/ai-review-findings.ts +409 -0
  116. package/lib/scaffold/ai-review-step.ts +5406 -64
  117. package/lib/scaffold/defaults.ts +82 -1
  118. package/lib/scaffold/managed-workflow.ts +587 -192
  119. package/lib/scaffold/owned-files.ts +152 -45
  120. package/lib/scaffold/pre-push-hook.ts +49 -5
  121. package/lib/scaffold/steps.ts +1836 -275
  122. package/lib/scaffold/workflow-census.ts +217 -0
  123. package/lib/scaffold/workflow-drift.ts +217 -0
  124. package/lib/scaffold/write-steps.ts +4 -0
  125. package/lib/scan-budget.ts +247 -0
  126. package/lib/scanner.ts +43 -51
  127. package/lib/scratch-roots.ts +50 -5
  128. package/lib/screenshot-discovery.ts +121 -0
  129. package/lib/screenshot-upload.ts +41 -1
  130. package/lib/secret-patterns.ts +511 -8
  131. package/lib/security-verdict.ts +1 -1
  132. package/lib/shell-path-interpolation.ts +594 -0
  133. package/lib/ship-mode.ts +219 -0
  134. package/lib/source-slice.ts +294 -0
  135. package/lib/stale-cleanup.ts +37 -3
  136. package/lib/suite-flake.ts +278 -0
  137. package/lib/suite-measurement.ts +23 -4
  138. package/lib/suite-run-reading.ts +241 -1
  139. package/lib/suite-timeout-margin.ts +193 -0
  140. package/lib/test-case-bodies.ts +883 -0
  141. package/lib/test-case-deletion.ts +653 -0
  142. package/lib/test-census.ts +97 -29
  143. package/lib/test-command-positions.ts +274 -0
  144. package/lib/test-suite-lock.ts +159 -16
  145. package/lib/text-dependents.ts +875 -0
  146. package/lib/tool-probe.ts +31 -9
  147. package/lib/top-level-cd.ts +393 -0
  148. package/lib/tree-entries.ts +89 -0
  149. package/lib/ts-ast.ts +200 -0
  150. package/lib/walk-test-files.ts +97 -0
  151. package/lib/workflow-actions.ts +263 -0
  152. package/lib/workflow-security.ts +29 -0
  153. package/lib/workflow-taint.ts +732 -0
  154. package/lib/worktree-cleanup.ts +65 -38
  155. package/lib/worktree-collect.ts +177 -5
  156. package/lib/worktree-repo.ts +68 -3
  157. package/package.json +4 -1
  158. package/scripts/ai-review-findings.ts +45 -0
  159. package/scripts/check-installed-hook-currency.ts +825 -0
  160. package/scripts/create-sc.ts +21 -1
  161. package/scripts/extract-constraints.ts +107 -7
  162. package/scripts/generate-code-map.ts +23 -30
  163. package/scripts/scaffold-project.ts +8 -1
  164. package/scripts/sync-sc-status.ts +77 -16
package/lib/paths.ts CHANGED
@@ -33,6 +33,56 @@ const FIXES =
33
33
  "Either set HARNESS_ROOT to the root of the run, " +
34
34
  "or pass the root you mean explicitly: harnessRootFor(root).";
35
35
 
36
+ /**
37
+ * One spelling of a root, with symlinks followed (#1129).
38
+ *
39
+ * `resolve()` normalises `..` and relative segments and stops there — it does
40
+ * NOT follow symlinks, so two names for one directory survive it as two
41
+ * strings. That is only a cosmetic difference until something compares roots
42
+ * by `startsWith`, and `collectDestination` in `workflows/ship.js` does
43
+ * exactly that. It has no choice: `workflows/*.js` runs in a sandbox with no
44
+ * module loading and no `process` or `Bun` (#69, enforced by
45
+ * `scripts/validate-workflow.ts`), so `realpathSync` is unreachable from that
46
+ * file. A string compare and a realpath compare agree on every already-
47
+ * canonical path and disagree the moment one side is reached through a link.
48
+ *
49
+ * This repository is the live instance: it is reachable under both its
50
+ * canonical name and a symlink named after the repo, and the symlinked one is
51
+ * the name a person types. A run launched with it would compare an unresolved
52
+ * root against a resolved worktree path and refuse a directory that is in
53
+ * fact inside it.
54
+ *
55
+ * So the resolution happens HERE, at the one producer, rather than at the
56
+ * hundreds of sites that consume a root. Every consumer then gets one
57
+ * spelling and the sandboxed comparison is left with nothing to disagree
58
+ * about.
59
+ *
60
+ * An unresolvable root THROWS rather than falling back to `resolve()`. The
61
+ * fallback is the tempting line and it is the bug: a root that resolves to
62
+ * nothing would be compared against happily, and the run would refuse its own
63
+ * worktrees for a reason naming neither the root nor the fact that it was
64
+ * never checked. Unknown is not canonical.
65
+ */
66
+ export function canonicalRoot(root: string): string {
67
+ if (!root || !root.trim()) {
68
+ throw new Error(
69
+ `canonicalRoot() was given an empty root at ${callSite()}. ` +
70
+ "An explicit root is the caller naming the tree it means; there is no tree to fall back to.",
71
+ );
72
+ }
73
+ const normalised = resolve(root);
74
+ try {
75
+ return realpathSync(normalised);
76
+ } catch (e: any) {
77
+ throw new Error(
78
+ `canonicalRoot() cannot be resolved for ${normalised} (from ${callSite()}): ${e?.message || e}. ` +
79
+ "A root that does not resolve is unmeasured, not canonical — it is refused here rather than " +
80
+ "passed through unresolved, because a comparison against it would silently disagree with every " +
81
+ "path git reports (#1129).",
82
+ );
83
+ }
84
+ }
85
+
36
86
  /**
37
87
  * The harness root the CALLER means, stated rather than inferred (#105).
38
88
  *
@@ -41,6 +91,24 @@ const FIXES =
41
91
  * tree it is pointed at. For those, "whichever tree this module happens to sit
42
92
  * in" is not a default, it is a coin flip between the run's root and the
43
93
  * worktree the agent is editing, and the losing side gets written to.
94
+ *
95
+ * Canonical since #1129, and that is a behaviour change worth stating: this
96
+ * used to return `resolve(root)`, which left a symlinked spelling intact for
97
+ * every downstream comparison.
98
+ *
99
+ * A root that does not EXIST is still returned normalised, and that
100
+ * asymmetry with `canonicalRoot()` is deliberate rather than an oversight.
101
+ * This is a path helper, not a gate: its callers name a tree, and naming one
102
+ * that is not on this disk is legitimate — `scripts/sync-spec-tests.ts`
103
+ * takes a root from `argv[2]` and `gates/run-gate.ts` takes one from
104
+ * `HARNESS_ROOT`, and both are exercised with trees that do not exist.
105
+ * Throwing here would turn "you named a tree I cannot see" into a crash in
106
+ * the middle of unrelated work.
107
+ *
108
+ * The refusal the acceptance asks for lives where the DECISION is made
109
+ * instead: `launchBaseReading` reads an unresolvable root as UNMEASURED and
110
+ * refuses the launch. That is the one place a root being unreadable should
111
+ * stop something, and it is reached before any agent is spawned.
44
112
  */
45
113
  export function harnessRootFor(root: string): string {
46
114
  if (!root || !root.trim()) {
@@ -49,7 +117,11 @@ export function harnessRootFor(root: string): string {
49
117
  "An explicit root is the caller naming the tree it means; there is no tree to fall back to.",
50
118
  );
51
119
  }
52
- return resolve(root);
120
+ try {
121
+ return canonicalRoot(root);
122
+ } catch {
123
+ return resolve(root);
124
+ }
53
125
  }
54
126
 
55
127
  export interface ImplicitRootOptions {
@@ -175,10 +247,31 @@ export function paiRoot(): string {
175
247
  return process.env.PAI_ROOT || paiHomeDir();
176
248
  }
177
249
 
250
+ /**
251
+ * The run store's root — every run's `workflow-state.json` lives one level
252
+ * under this.
253
+ *
254
+ * Extracted from `workDir` rather than written beside it (#545). The
255
+ * expression was about to have a second author: `lib/intake-sources.ts` mines
256
+ * gate refusals out of the store and needs the ROOT, not a per-slug path, and
257
+ * `lib/gap-scanner.ts` already assembles its own copy. Two places spelling one
258
+ * location is the shape `paiHomeDir`'s own docstring above records going
259
+ * wrong — same anonymous expression, two meanings, nothing in the output
260
+ * saying which.
261
+ *
262
+ * `process.env.HOME || ""` is kept exactly as it was. It is not what I would
263
+ * write — it degrades to a relative `.rungate` when HOME is unset, which is
264
+ * the defect `paiHomeDir` was fixed for — but changing it here would alter
265
+ * `workDir`'s behaviour under an empty HOME, which is the configuration the
266
+ * intake tests deliberately run in. Noted rather than silently repaired.
267
+ */
268
+ export function workStoreRoot(): string {
269
+ return process.env.RUNGATE_WORK_DIR || join(process.env.HOME || "", ".rungate");
270
+ }
271
+
178
272
  export function workDir(slug: string): string {
179
273
  if (slug.includes('..') || slug.startsWith('/')) throw new Error(`Invalid slug: ${slug}`);
180
- const base = process.env.RUNGATE_WORK_DIR || join(process.env.HOME || "", ".rungate");
181
- return join(base, slug);
274
+ return join(workStoreRoot(), slug);
182
275
  }
183
276
 
184
277
  export function gateSaltPath(): string {
@@ -0,0 +1,219 @@
1
+ /**
2
+ * Every construct in a test file that raises the per-test budget above the
3
+ * one `bunfig.toml` declares (#968, from #804/#621).
4
+ *
5
+ * ## The subject, and why it is wider than one spelling
6
+ *
7
+ * `timeoutProximityViolations` in `lib/junit-checks.ts` compares each case's
8
+ * measured duration against ONE number — the budget in force. A case that
9
+ * carries a budget of its own leaves that reading two ways: it is never
10
+ * killed at the global budget, so the `was KILLED` row cannot fire; and once
11
+ * it runs past the global budget the proximity row cannot fire either, since
12
+ * that row requires `ms < timeoutMs`. That is the mechanism by which #802's
13
+ * `}, 60_000)` took the SC-6 scan out of the one instrument that would have
14
+ * warned before the kill — the headline finding of #804.
15
+ *
16
+ * The detector this replaces, in `test/scan-budget.test.ts`, was
17
+ * `/\}\s*,\s*([0-9_]+)\s*\)\s*;/g`. MEASURED on bun 1.3.14 against a
18
+ * `--timeout 300` budget, with a case that sleeps 600ms: the no-override
19
+ * control is killed at 300ms, and all five of these run to completion.
20
+ *
21
+ * | form | raises the budget | old regex |
22
+ * |---|---|---|
23
+ * | `}, 60_000);` | yes | matched |
24
+ * | `}, TIMEOUT);` | yes | **missed** |
25
+ * | `}, 60 * 1000);` | yes | **missed** |
26
+ * | `}, 60_000)` no `;` | yes | **missed** |
27
+ * | `}, { timeout: 5000 });` | yes | **missed** |
28
+ * | `setDefaultTimeout(…)` | yes | **missed** |
29
+ *
30
+ * So the guard against reintroducing #802's override was walked around by
31
+ * extracting the number into a constant. Four of the five ways to write the
32
+ * exact defect it was written for went unseen.
33
+ *
34
+ * ## What it reports, and what it deliberately does not
35
+ *
36
+ * It reports DECLARATIONS, not values. `}, TIMEOUT)` is reported as the text
37
+ * `TIMEOUT`, with no attempt to resolve it — resolving constants would be a
38
+ * second interpreter, and the question here is "does this case have a budget
39
+ * of its own", which the declaration answers on its own. A declaration that
40
+ * happens to equal the global budget is still a declaration, and still takes
41
+ * the case out of the `was KILLED` row.
42
+ *
43
+ * `null` means the source did not parse. That is a REFUSAL, distinct from
44
+ * `[]`, and the caller must keep them distinct — a parser that stopped
45
+ * parsing reports exactly as clean as a file with no overrides, which is the
46
+ * defect class #968 exists to close.
47
+ *
48
+ * ## Import aliases are resolved, because matching the local name was a hole
49
+ *
50
+ * The review of this PR found the defect class reproduced in its own fix:
51
+ * `CASE_ROOTS` matched the LOCAL identifier, so
52
+ * `import { test as t } from "bun:test"` silently defeated the detector —
53
+ * MEASURED at 0 declarations for `t("slow", () => {}, 60_000)`, and the same
54
+ * for `setDefaultTimeout as sdt` and `beforeAll as bA`. Callees are now
55
+ * resolved through the module's import bindings to the name bun:test
56
+ * exports, so the alias, the namespace form (`import * as bt`, `bt.test(…)`)
57
+ * and the injected global are one question.
58
+ *
59
+ * ## WHAT THIS DOES NOT COVER (stated rather than implied)
60
+ *
61
+ * MEASURED to return `[]`:
62
+ *
63
+ * - **An indirection through a variable.** `const t = test; t("a", fn, 1000)`.
64
+ * Only import bindings are resolved, not assignments.
65
+ * - **Computed member access.** `bt["test"](…)` on a namespace import.
66
+ * - **A wrapper that declares the budget for you.** A local
67
+ * `slowTest(name, fn)` that calls `test(name, fn, 60_000)` internally IS
68
+ * reported, at the call inside the wrapper — but only because that call
69
+ * is in the same module. A wrapper imported from elsewhere is not.
70
+ *
71
+ * None of these appear in this repo: the 594-file census in the PR found no
72
+ * aliased, namespaced or indirected case declaration.
73
+ */
74
+
75
+ import {
76
+ type AstNode,
77
+ calleeRoot,
78
+ importBindings,
79
+ parseTsModule,
80
+ rootProperty,
81
+ walkNodes,
82
+ } from "./ts-ast";
83
+
84
+ /** The callees that declare a test case and accept a per-test budget. */
85
+ const CASE_ROOTS = new Set(["test", "it"]);
86
+
87
+ /**
88
+ * The hooks that accept a budget of their own.
89
+ *
90
+ * Included because a hook that is killed is reported as `(unnamed)` in
91
+ * bun's JUnit output — MEASURED on 1.3.14 — so work moved into a hook with
92
+ * a budget of its own is as far out of `timeoutProximityViolations`'s reach
93
+ * as a case with one. Same AST rule, different root set; leaving them out
94
+ * would be a gap for the sake of a shorter list.
95
+ */
96
+ const HOOK_ROOTS = new Set(["beforeAll", "beforeEach", "afterAll", "afterEach"]);
97
+
98
+ /** The bun:test call that raises the default budget for a whole file. */
99
+ const DEFAULT_TIMEOUT_FN = "setDefaultTimeout";
100
+
101
+ /** How a budget was raised. */
102
+ export type TimeoutKind =
103
+ /** A third argument to a `test`/`it` call: `}, 60_000)`, `}, { timeout: 60_000 })`. */
104
+ | "per-test"
105
+ /** A second argument to a `beforeAll`/`afterEach`/… call. */
106
+ | "hook"
107
+ /** A `setDefaultTimeout(…)` call, which raises it for every case in the file. */
108
+ | "file-default";
109
+
110
+ /** One construct that gives a case a budget other than the declared one. */
111
+ export interface TimeoutDeclaration {
112
+ kind: TimeoutKind;
113
+ /**
114
+ * The source text of the declaration, as it appears in the TRANSPILED
115
+ * module. Reported rather than evaluated — see the module comment.
116
+ */
117
+ expression: string;
118
+ /** The case name when it is a string literal, else `null`. */
119
+ caseName: string | null;
120
+ }
121
+
122
+ function literalString(node: unknown): string | null {
123
+ const n = node as AstNode | undefined;
124
+ if (n?.type === "Literal" && typeof n.value === "string") return n.value;
125
+ return null;
126
+ }
127
+
128
+ /**
129
+ * Every per-test and file-default budget declaration in `source`, in document
130
+ * order. `null` when the source does not parse.
131
+ */
132
+ export function perTestTimeoutDeclarations(source: string): TimeoutDeclaration[] | null {
133
+ const parsed = parseTsModule(source);
134
+ if (parsed === null) return null;
135
+ const bindings = importBindings(parsed.tree);
136
+
137
+ /**
138
+ * The bun:test name a callee resolves to, following import aliases.
139
+ *
140
+ * Matching the LOCAL identifier was the alias hole this closes:
141
+ * `import { test as t } from "bun:test"` made the detector report clean on
142
+ * its own subject (MEASURED: 0 declarations for `t("slow", () => {}, 60_000)`).
143
+ *
144
+ * Three cases, in order:
145
+ * - the local name is bound by a bun:test import → its EXPORTED name,
146
+ * so `t` resolves to `test`;
147
+ * - the local name is a bun:test NAMESPACE binding → the property called
148
+ * on it, so `bt.test(…)` resolves to `test`;
149
+ * - the local name is bound by some OTHER import → `null`, because
150
+ * `import { test } from "./helpers"` is not bun:test's;
151
+ * - otherwise the bare name, which is how bun's injected globals work in
152
+ * a file that imports nothing from bun:test.
153
+ */
154
+ function resolved(callee: unknown): string | null {
155
+ const root = calleeRoot(callee);
156
+ if (root === null) return null;
157
+ const binding = bindings.get(root);
158
+ if (binding === undefined) return root;
159
+ if (binding.module !== "bun:test") return null;
160
+ if (binding.imported === "*") return rootProperty(callee);
161
+ return binding.imported;
162
+ }
163
+
164
+ const out: TimeoutDeclaration[] = [];
165
+ for (const node of walkNodes(parsed.tree)) {
166
+ if (node.type !== "CallExpression") continue;
167
+ const args = node.arguments as AstNode[] | undefined;
168
+ if (!Array.isArray(args)) continue;
169
+ const root = resolved(node.callee);
170
+
171
+ if (root === DEFAULT_TIMEOUT_FN && args.length >= 1) {
172
+ out.push({
173
+ kind: "file-default",
174
+ expression: parsed.js.slice(args[0]!.start, args[0]!.end),
175
+ caseName: null,
176
+ });
177
+ continue;
178
+ }
179
+
180
+ // A per-test budget is the THIRD argument of a call rooted at test/it.
181
+ // Rooted, so `test.only`, `test.skip`, `test.if(x)` and
182
+ // `test.each([…])(…)` are all the same question rather than a list of
183
+ // spellings. `test.each([1])` on its own has one argument and is not a
184
+ // case declaration, so the arity check excludes it without naming it.
185
+ if (root !== null && CASE_ROOTS.has(root) && args.length >= 3) {
186
+ const arg = args[2]!;
187
+ out.push({
188
+ kind: "per-test",
189
+ expression: parsed.js.slice(arg.start, arg.end),
190
+ caseName: literalString(args[0]),
191
+ });
192
+ continue;
193
+ }
194
+
195
+ // A hook takes its budget as the SECOND argument, there being no name.
196
+ if (root !== null && HOOK_ROOTS.has(root) && args.length >= 2) {
197
+ const arg = args[1]!;
198
+ out.push({
199
+ kind: "hook",
200
+ expression: parsed.js.slice(arg.start, arg.end),
201
+ caseName: root,
202
+ });
203
+ }
204
+ }
205
+ return out;
206
+ }
207
+
208
+ /** One line per declaration, for a failure message that names the repair. */
209
+ export function describeTimeoutDeclarations(found: TimeoutDeclaration[]): string {
210
+ return found
211
+ .map(d =>
212
+ d.kind === "file-default"
213
+ ? `setDefaultTimeout(${d.expression}) raises the budget for every case in the file`
214
+ : d.kind === "hook"
215
+ ? `a ${d.caseName} hook declares a budget of ${d.expression}, and a killed hook is reported as \`(unnamed)\``
216
+ : `${d.caseName === null ? "a case" : `"${d.caseName}"`} declares a per-test budget of ${d.expression}`,
217
+ )
218
+ .join("\n");
219
+ }
@@ -184,7 +184,7 @@ export function acListBlock(acs: readonly DecomposedAc[]): string {
184
184
  export function phase2AcsCommand(harnessRoot: string, workDir: string, acs: readonly DecomposedAc[]): string {
185
185
  const payload = JSON.stringify(acs.map(a => ({ id: a.id, statement: a.statement, specElement: a.specElement })));
186
186
  return (
187
- `cd ${harnessRoot} && bun -e 'require("fs").writeFileSync(process.argv[1], process.argv[2])' ` +
187
+ `bun --cwd ${shellSingleQuote(harnessRoot)} -e 'require("fs").writeFileSync(process.argv[1], process.argv[2])' ` +
188
188
  `${workDir}/phase2-acs.json ${shellSingleQuote(payload)}`
189
189
  );
190
190
  }
@@ -0,0 +1,151 @@
1
+ /**
2
+ * Does a decomposition's plan allocate every file discovery said the issue
3
+ * touches? (#751)
4
+ *
5
+ * `workflows/ship.js` interpolates `discovery.filesToModify` into the
6
+ * to-issues prompt as "Files to modify" and then validates the answer two
7
+ * ways: no sub-issue may claim an out-of-scope file, and no two sub-issues
8
+ * may claim the same one. **Nothing compared the UNION of the sub-issues'
9
+ * `filesToModify` against the list it had just asked about.** The prompt
10
+ * asks; nothing checked that the answer covers it — the same gap the comment
11
+ * beside `denylistViolations` names for the deny-list and was never extended
12
+ * past.
13
+ *
14
+ * On the consumer run that motivated #751, the file the issue was *about* was
15
+ * claimed by no sub-issue, edited by two worktrees, and the run reached
16
+ * Commit before SC-413 refused with *"no worktree claimed that file"* —
17
+ * 2h06m and 2.03M subagent tokens of correct work ending `SHIP_FAILED` /
18
+ * `NO_PR`. The run is named on the issue; naming a consumer repository in
19
+ * harness source is what `test/anti.test.ts` SC-A1 refuses, and it is right
20
+ * to — this module ships to every project rungate scaffolds. That
21
+ * refusal is correct and is not loosened here; widening it is the documented
22
+ * cheapest wrong fix for this family (`.claude/rules/checks-must-be-able-to-fail.md`,
23
+ * the #627 section). This moves the detection to plan time, where it costs
24
+ * nothing.
25
+ *
26
+ * ## The decision #751 asked to be made out loud
27
+ *
28
+ * Three candidates, all precedented in `ship.js`. **Option 1: refuse the
29
+ * parallel plan and fall back to single-agent implement** — the same branch
30
+ * `hasOverlap` already takes, one line away.
31
+ *
32
+ * - **Not auto-claim (option 2).** The decomposer had the file list and chose
33
+ * not to allocate it. Assigning the file by a heuristic — same directory,
34
+ * first sub-issue, largest — hands work to an agent whose brief never
35
+ * mentions it, and whose claim audit then PASSES while the allocation is
36
+ * wrong. It converts a loud, early, correct refusal into a quiet
37
+ * misallocation, which is strictly worse than the state being fixed.
38
+ * - **Not warn-and-proceed (option 3).** That is the status quo, and the
39
+ * status quo is a run spending its whole agent budget to discover at Commit
40
+ * what was knowable before the first agent spawned.
41
+ * - **Option 1 loses nothing.** The single-agent path may modify every file,
42
+ * so the work still ships; what is given up is parallelism, which is an
43
+ * optimisation and not a requirement. The failure is moved from the end of
44
+ * the run to the start of it.
45
+ *
46
+ * ## An empty discovery list is UNMEASURED, not "fully covered"
47
+ *
48
+ * The union of nothing covers nothing perfectly — the third shape, and #751
49
+ * names it as the cheapest wrong fix for this check specifically: *treat an
50
+ * absent or empty `discovery.filesToModify` as satisfied*. It silences every
51
+ * synthetic fixture and leaves exactly the #1585 case uncaught, because the
52
+ * thing that needs covering is a list nobody is obliged to produce.
53
+ *
54
+ * **That branch is unreachable from today's call site, and saying so is the
55
+ * point** (#492). `ship.js` only decomposes when
56
+ * `discovery.sizing === 'M' && (discovery.filesToModify || []).length >= 3`,
57
+ * so every live plan arrives with at least three files and the empty reading
58
+ * cannot occur. It is reported anyway, because the precondition is one `if`
59
+ * in another function that nothing holds still, and a branch that only exists
60
+ * while an unrelated guard keeps its shape is a branch that goes silently
61
+ * wrong the day that guard moves.
62
+ */
63
+
64
+ import { normalisePath } from "./scope-denylist";
65
+
66
+ export interface PlanSubIssue {
67
+ title?: string;
68
+ filesToModify?: string[];
69
+ }
70
+
71
+ export interface PlanCoverageReading {
72
+ reading: "MEASURED" | "UNMEASURED";
73
+ unmeasuredReasons: string[];
74
+ /** Discovered files no sub-issue claims, in the spelling discovery used. */
75
+ uncovered: string[];
76
+ /** How many files were compared, so a PASS can report its own coverage. */
77
+ discovered: number;
78
+ /** How many distinct files the plan allocates, including any not discovered. */
79
+ claimed: number;
80
+ }
81
+
82
+ /**
83
+ * Compare the plan's union against what discovery found.
84
+ *
85
+ * Path equality goes through `normalisePath`, the same binding the deny-list
86
+ * uses, so `./lib/a.ts` and `lib/a.ts` are one file here exactly as they are
87
+ * there. A second notion of "same path" in the same workflow would agree on
88
+ * every input anyone has and diverge on the one that matters.
89
+ */
90
+ export function planCoverage(
91
+ discoveryFiles: string[] | undefined | null,
92
+ subIssues: PlanSubIssue[] | undefined | null,
93
+ ): PlanCoverageReading {
94
+ const discovered = (discoveryFiles || []).map(f => String(f)).filter(f => f.trim() !== "");
95
+ const subs = subIssues || [];
96
+
97
+ const claimedSet = new Set<string>();
98
+ for (const s of subs) {
99
+ for (const f of s.filesToModify || []) {
100
+ const n = normalisePath(f);
101
+ if (n !== "") claimedSet.add(n);
102
+ }
103
+ }
104
+
105
+ const reasons: string[] = [];
106
+ if (discovered.length === 0) {
107
+ reasons.push(
108
+ "discovery named no files to modify, so there is nothing to compare the plan against. " +
109
+ 'The union of an empty list is covered by any plan at all, which is not "the plan is ' +
110
+ 'complete" — it is "nobody looked" (#751).',
111
+ );
112
+ }
113
+ if (subs.length === 0) {
114
+ reasons.push(
115
+ "the decomposition produced no sub-issues, so there is no plan to compare. An empty " +
116
+ "plan agrees with every discovery.",
117
+ );
118
+ }
119
+
120
+ return {
121
+ reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
122
+ unmeasuredReasons: reasons,
123
+ uncovered:
124
+ reasons.length === 0 ? discovered.filter(f => !claimedSet.has(normalisePath(f))) : [],
125
+ discovered: discovered.length,
126
+ claimed: claimedSet.size,
127
+ };
128
+ }
129
+
130
+ /**
131
+ * The sentence `ship.js` logs when the plan must not be used, or `null`.
132
+ *
133
+ * One binding so there is one thing to mutate, and so the refusal and the
134
+ * reading cannot disagree about whether a plan is usable. An UNMEASURED
135
+ * reading refuses too: a plan nobody could check is not a plan that passed.
136
+ */
137
+ export function planCoverageRefusal(r: PlanCoverageReading): string | null {
138
+ if (r.reading === "UNMEASURED") {
139
+ return (
140
+ `PLAN COVERAGE UNMEASURED: ${r.unmeasuredReasons.join(" ")} ` +
141
+ `Falling back to single-agent implement, which may touch any file.`
142
+ );
143
+ }
144
+ if (r.uncovered.length === 0) return null;
145
+ return (
146
+ `PLAN COVERAGE: ${r.uncovered.length} of ${r.discovered} discovered file(s) are claimed by ` +
147
+ `no sub-issue — ${r.uncovered.join(", ")}. A file nobody claims is a file two worktrees ` +
148
+ `may both edit, and the SC-413 claim audit refuses it at Commit after the whole agent ` +
149
+ `budget is spent (#751). Falling back to single-agent implement.`
150
+ );
151
+ }