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
@@ -0,0 +1,258 @@
1
+ /**
2
+ * Where `ProjectStateSync` is allowed to run a generator — and everywhere it
3
+ * is not (#1001).
4
+ *
5
+ * ## The defect this exists to close
6
+ *
7
+ * The hook took a `project-state.json` path out of a tool call, stripped the
8
+ * filename, and ran `scripts/update-project-state.ts` from whatever was left:
9
+ *
10
+ * const projectRoot = filePath.replace(/\/project-state\.json$/, "");
11
+ * const script = join(projectRoot, "scripts", "update-project-state.ts");
12
+ * if (!existsSync(script)) …decline…
13
+ * execFileSync("bun", [script, "--skip-tests"], { cwd: projectRoot });
14
+ *
15
+ * `projectRoot` is wherever the tool call pointed. Anything able to write two
16
+ * files — `<anywhere>/project-state.json` and
17
+ * `<anywhere>/scripts/update-project-state.ts` — got code execution as the
18
+ * user, on the next `Write` or `Edit`, in every session on this machine.
19
+ *
20
+ * **It is a permission-gate bypass, and that is the part that matters.**
21
+ * `Bash` is gated far more tightly than `Write`. The agent never runs a
22
+ * command; the hook runs it on the agent's behalf, with the agent's choice of
23
+ * directory. #971/#999 converted the spawn from a shell string to an argv,
24
+ * which closed metacharacter injection and left this untouched — the hook's
25
+ * own header says so: *"`existsSync(script)` above is a bar, not a wall — it
26
+ * only requires the payload to be a real directory, and /tmp is writable."*
27
+ *
28
+ * ## The cheapest wrong fix, named so it cannot be mistaken for this one
29
+ *
30
+ * *"Allow anything under `$HOME/Projects`."* It satisfies the symptom, it is
31
+ * a prefix test, and it is **a new list of trusted paths** — a fourth
32
+ * position declaring something this repo already decides elsewhere. It also
33
+ * does not work: a planted root inside the prefix passes it. `AC-4` is that
34
+ * input, and it is red against that fix.
35
+ *
36
+ * The cheapest wrong fix for the SECOND round is different and more
37
+ * tempting: *"also `realpath` the leaf."* It closes the symlinked-directory
38
+ * hole completely, reads like a security fix in a diff, and leaves the
39
+ * forged repository exactly as open as it was — a forgery's generator is a
40
+ * perfectly ordinary file. `AC-14` is the input it does not survive.
41
+ *
42
+ * ## What is checked instead, and why it delegates
43
+ *
44
+ * **The generator may only run at the root of a real git repository, and it
45
+ * must be a TRACKED file of that repository.** Neither is a list; both are
46
+ * questions something else already answers — `lib/paths.ts:repoRootFrom`
47
+ * resolves `--git-common-dir` and `realpathSync`es the result so callers can
48
+ * compare stable strings, and `git ls-files --error-unmatch` decides
49
+ * membership. No second definition of "trusted root" is declared here.
50
+ *
51
+ * ### Why the repo-root test alone was not enough
52
+ *
53
+ * The first version of this module shipped with only the root test, and its
54
+ * limits note claimed an attacker needed "to create a directory AND run
55
+ * `git init`". That is false, and measured false on this machine:
56
+ *
57
+ * mkdir -p $D/.git/objects $D/.git/refs/heads $D/scripts
58
+ * printf 'ref: refs/heads/main\n' > $D/.git/HEAD
59
+ * git -C $D rev-parse --show-toplevel → $D
60
+ * git -C $D rev-parse --git-common-dir → .git
61
+ *
62
+ * Three `mkdir`s and a 24-byte file, every one of them reachable with
63
+ * `Write` — the exact primitive this issue exists to contain. "Any writable
64
+ * directory" became "any writable directory plus three mkdirs", which is not
65
+ * a narrowing, and saying it was is worse than the gap: a reader checking
66
+ * the limits would have stopped there.
67
+ *
68
+ * The tracked test refuses it, because **the barrier is `.git/index`** — a
69
+ * binary file with a trailing checksum, not something a text write produces.
70
+ * It also asks the better question: *is this generator part of a project*
71
+ * rather than *is there a `.git` directory here*. `AC-14` is the forgery and
72
+ * `AC-15` is an untracked file dropped into a REAL repository, which is what
73
+ * an attacker gets from any checkout on the machine.
74
+ *
75
+ * ### Both sides must be resolved, and this machine is why
76
+ *
77
+ * The obvious spelling of the anchor is wrong:
78
+ *
79
+ * if (claimedRoot !== repoRootFrom(claimedRoot)) decline // WRONG
80
+ *
81
+ * `repoRootFrom` realpaths its answer and the claimed path has not been
82
+ * realpathed, so the two can never agree through a symlink. Measured:
83
+ * `/Users/jhorn/Projects/pai-harness` is a symlink to
84
+ * `/Users/jhorn/Projects/rungate`, and the live `project-state.json` is
85
+ * written through the former. That spelling **refuses the only real caller
86
+ * there is**, silently, as a security improvement. `AC-3` is that input.
87
+ *
88
+ * ### The whole path is resolved, not the leaf
89
+ *
90
+ * `lstat` on the last component sees a link AT the leaf and is blind to one
91
+ * above it: a `scripts` directory symlinked anywhere, with an ordinary file
92
+ * at the end of it, reports no link at all. `projectRoot` is already
93
+ * resolved, so comparing `realpathSync(script)` against the expected path
94
+ * catches a link at ANY depth. `AC-16` is that input, and it asserts the
95
+ * leaf-level `lstat` reads false on it so the arm cannot quietly become a
96
+ * duplicate of `AC-7`.
97
+ *
98
+ * ### A linked worktree is NOT the root of its repository
99
+ *
100
+ * `repoRootFrom` resolves `--git-common-dir`, so from a linked worktree it
101
+ * returns the MAIN checkout. A worktree therefore reads as `not-repo-root`
102
+ * and the generator does not run there. That is a behaviour change and it is
103
+ * deliberate: `PROJECT-STATE.md` is DA-owned and an agent in a worktree must
104
+ * never write it (#296), which #910's SC-3 raised as an open question while
105
+ * the hook was registered on `Write` **and** `Edit` and taking the other
106
+ * answer by default. The outcome is recorded distinctly so the decision is
107
+ * visible in the evidence rather than buried in a refusal count.
108
+ *
109
+ * ## WHAT THIS DOES NOT COVER
110
+ *
111
+ * - **A repository whose CONFIG is hostile.** `repoRootFrom` shells out to
112
+ * `git` in the candidate directory before the tracked-file test can run,
113
+ * and that call is not isolated. `rev-parse --git-common-dir` neither
114
+ * refreshes the index nor fires a hook, so `core.fsmonitor` and
115
+ * `core.hooksPath` do not execute on it — but that is a property of the
116
+ * subcommand, not a boundary. Isolating `repoRootFrom` itself is the right
117
+ * fix and is not done here: `test/harness-root.test.ts` stages
118
+ * `lib/paths.ts` into a scratch directory, so an import added to it fails
119
+ * to load there (`.claude/rules/self-referential-tests.md`, Tier 1).
120
+ * - **A real project someone else controls.** Tracked means part of a
121
+ * project, not part of YOUR project. An attacker who can commit to a
122
+ * repository on this machine can change what the generator does, which is
123
+ * the next item and not a smaller problem.
124
+ * - **A generator that is a regular file with hostile contents.** Confining
125
+ * WHERE is not reviewing WHAT.
126
+ * - **A race between the checks and the spawn.** Everything here resolves
127
+ * paths once; a component swapped for a symlink afterwards is not seen.
128
+ *
129
+ * Issue: #1001. Refs #971, #999, #910, #296.
130
+ */
131
+
132
+ import { spawnSync } from "child_process";
133
+ import { realpathSync, statSync } from "fs";
134
+ import { isAbsolute, join } from "path";
135
+ import { repoRootFrom } from "./paths";
136
+ import { gitIsolatedArgs, gitIsolatedEnv } from "./git-isolation";
137
+
138
+ /** The generator this hook runs, relative to a project root. */
139
+ export const GENERATOR_RELPATH = join("scripts", "update-project-state.ts");
140
+
141
+ export type ProjectStateTarget =
142
+ | { ok: true; projectRoot: string; script: string }
143
+ /**
144
+ * `outcome` is the string the hook records. Every refusal has one: a
145
+ * decline and a hook that never ran are otherwise the same observation,
146
+ * which is #910.
147
+ */
148
+ | { ok: false; outcome: string; detail: Record<string, unknown> };
149
+
150
+ /**
151
+ * Resolve a `project-state.json` path to the generator that may run for it.
152
+ *
153
+ * Pure apart from the filesystem reads it is about, and separate from the
154
+ * hook so every refusal has an input that reaches it — a guard that only the
155
+ * hook can exercise is a guard whose ordering nothing can test.
156
+ */
157
+ export function projectStateTarget(filePath: string): ProjectStateTarget {
158
+ const claimed = filePath.replace(/\/project-state\.json$/, "");
159
+ const detail: Record<string, unknown> = { filePath, claimedRoot: claimed };
160
+
161
+ // Resolve the CLAIMED side too. Without this the comparison below is a
162
+ // string match between a resolved and an unresolved path, which disagrees
163
+ // through any symlink — including the one the real caller arrives through.
164
+ let projectRoot: string;
165
+ try {
166
+ projectRoot = realpathSync(claimed);
167
+ } catch (e) {
168
+ return { ok: false, outcome: "declined-unresolvable-root", detail: { ...detail, error: (e as Error).message } };
169
+ }
170
+ detail.projectRoot = projectRoot;
171
+
172
+ const repoRoot = repoRootFrom(projectRoot);
173
+ if (repoRoot === null) {
174
+ // No repository at all: the planted-directory case this issue is about.
175
+ return { ok: false, outcome: "declined-outside-repo", detail };
176
+ }
177
+ if (repoRoot !== projectRoot) {
178
+ // A subdirectory, or a LINKED WORKTREE — `--git-common-dir` resolves to
179
+ // the main checkout from inside one. Recorded distinctly because of the
180
+ // #296 interaction; `repoRoot` in the detail tells the two apart.
181
+ return { ok: false, outcome: "declined-not-repo-root", detail: { ...detail, repoRoot } };
182
+ }
183
+
184
+ const script = join(projectRoot, GENERATOR_RELPATH);
185
+ // INVARIANT, not a guard. `realpathSync` returns an absolute path and
186
+ // `join` keeps it absolute, so `script` can never be read as a flag by the
187
+ // spawned `bun`. Stated because the pre-fix code had no such guarantee —
188
+ // a `file_path` of `-rf/project-state.json` built the argv
189
+ // `-rf/scripts/update-project-state.ts`, which `bun` parses as options.
190
+ // Asserted rather than branched on: a condition no input can satisfy is
191
+ // not a check (`.claude/rules/checks-must-be-able-to-fail.md`), and
192
+ // pretending otherwise would hide which mechanism actually closes this.
193
+ if (!isAbsolute(script)) {
194
+ throw new Error(`projectStateTarget produced a relative generator path: ${script}`);
195
+ }
196
+
197
+ // Resolve the WHOLE path, not the leaf. `lstat` on the last component is
198
+ // blind to a symlinked INTERMEDIATE: `scripts` may be a link to anywhere
199
+ // with a perfectly ordinary file at the end of it, and `lstat` reports no
200
+ // link. `projectRoot` is already resolved, so any disagreement here is a
201
+ // link at some depth below it.
202
+ let realScript: string;
203
+ try {
204
+ realScript = realpathSync(script);
205
+ } catch {
206
+ return { ok: false, outcome: "declined-no-generator", detail: { ...detail, script } };
207
+ }
208
+ if (realScript !== script) {
209
+ return {
210
+ ok: false,
211
+ outcome: "declined-symlinked-generator",
212
+ detail: { ...detail, script, resolved: realScript },
213
+ };
214
+ }
215
+ if (!statSync(realScript).isFile()) {
216
+ return { ok: false, outcome: "declined-no-generator", detail: { ...detail, script } };
217
+ }
218
+
219
+ if (!trackedInRepo(projectRoot, GENERATOR_RELPATH)) {
220
+ // THE ANCHOR. A `.git` directory is three `mkdir`s and a 24-byte `HEAD`
221
+ // away from any `Write`; a TRACKED file is not.
222
+ //
223
+ // LAST, so that every check above it stays reachable. Tracking is the
224
+ // strongest test here, and putting it first would make the symlink
225
+ // branches unreachable — git does not descend a symlinked directory, so
226
+ // a link would be refused as untracked and the branch that exists to
227
+ // name it could never be taken (`.claude/rules/checks-must-be-able-to-fail.md`).
228
+ // Order changes which refusal is RECORDED, never whether one happens:
229
+ // nothing is spawned until all of them pass.
230
+ return { ok: false, outcome: "declined-untracked-generator", detail: { ...detail, script } };
231
+ }
232
+
233
+ return { ok: true, projectRoot, script };
234
+ }
235
+
236
+ /**
237
+ * Is `relPath` a tracked file of the repository at `root`?
238
+ *
239
+ * `ls-files --error-unmatch` rather than a filesystem test, because the
240
+ * question is *is this part of a project* and only git can answer it. The
241
+ * barrier is the INDEX: `.git/index` is a binary file carrying a trailing
242
+ * checksum, so the three-`mkdir`s forgery that satisfies `rev-parse` has no
243
+ * index at all and this refuses it. Committed content raises the bar again,
244
+ * but the index alone is already past what writing text files can reach.
245
+ *
246
+ * ISOLATED, because this runs `git` in a directory the caller chose and git
247
+ * executes that repository's config — `lib/git-isolation.ts`. `--` so a
248
+ * relative path can never be read as a revision or a flag.
249
+ */
250
+ function trackedInRepo(root: string, relPath: string): boolean {
251
+ const r = spawnSync("git", gitIsolatedArgs(["-C", root, "ls-files", "--error-unmatch", "--", relPath]), {
252
+ encoding: "utf-8",
253
+ timeout: 5000,
254
+ stdio: ["ignore", "ignore", "ignore"],
255
+ env: gitIsolatedEnv(),
256
+ });
257
+ return r.status === 0;
258
+ }