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,373 @@
1
+ /**
2
+ * The decision behind `hooks/BashWriteGuard.hook.ts` (#473 on
3
+ * `hornjason/pai-config`, tuned there in #474, reworked in #1120).
4
+ *
5
+ * Extracted from the hook so the population it refuses can be MEASURED
6
+ * rather than argued about: 5,060 real commands from this machine's
7
+ * transcripts were run through it, which is not something you can do with a
8
+ * decision that only exists inside a subprocess. Same shape as
9
+ * `lib/gate-result-protection.ts`, which #1137 extracted for the same reason.
10
+ *
11
+ * ## The thing this module exists to get right
12
+ *
13
+ * One mechanism was failing in BOTH directions at once.
14
+ *
15
+ * It UNDER-blocked, because a read-only prefix allowlist was consulted before
16
+ * anything looked at what the command wrote, so `gh --version; echo x >
17
+ * .gate-salt` exited clean. A prefix says nothing about what follows a `;`.
18
+ *
19
+ * It OVER-blocked, because the remaining checks matched protected names
20
+ * anywhere in the command STRING, so a read-only `git show … | grep -nE
21
+ * "chmod|chflags"` was refused for quoting the words it was searching for.
22
+ * That happened four times in real work — twice to the session coordinating
23
+ * this fix, twice to a peer staging a comparison copy — and a guard that
24
+ * makes reading its own source awkward is a guard people route around.
25
+ *
26
+ * Both directions are the same root cause: a substring test over a whole
27
+ * command line cannot tell CODE from DATA. So nothing here tests the whole
28
+ * string. The command is split into segments at top-level separators, and
29
+ * each check asks a structural question of a segment:
30
+ *
31
+ * - what does this segment WRITE? → redirects, tee, cp/mv
32
+ * - what does this segment MUTATE in place? → sed -i, dd of=, rm, …
33
+ * - is this segment OPAQUE? → an interpreter body, find -exec
34
+ * - is this segment's COMMAND WORD chmod? → not "does it contain chmod"
35
+ *
36
+ * Quotes are handled two different ways on purpose, and the distinction is
37
+ * the whole fix:
38
+ *
39
+ * `stripQuoted` deletes quoted spans INCLUDING their contents. Used to
40
+ * find a VERB, because text inside quotes is an argument,
41
+ * never the command the shell runs. This is what stops a
42
+ * grep PATTERN from reading as a chmod invocation.
43
+ * `dequote` removes quote characters and KEEPS the contents. Used to
44
+ * find a TARGET, because `chmod 777 "x.hook.ts"` really does
45
+ * name a hook file.
46
+ *
47
+ * Using `stripQuoted` for both would let an attacker quote the path; using
48
+ * `dequote` for both reinstates all four false positives. Each test below
49
+ * names which one it uses and why.
50
+ */
51
+
52
+ /** Gate artifacts. A write to any of these must come from the gate runner. */
53
+ export const PROTECTED_FILES = ['workflow-state.json', '.gate-salt', '/witnesses/'];
54
+
55
+ /** Hook sources. Integrity matters because hooks are what enforce everything else. */
56
+ export const PROTECTED_HOOKS = ['.hook.ts', '.hook.sh'];
57
+
58
+ export interface BashWriteDecision {
59
+ blocked: boolean;
60
+ reason?: string;
61
+ }
62
+
63
+ const ALLOW: BashWriteDecision = { blocked: false };
64
+
65
+ /**
66
+ * Split a command at top-level `;`, `&&`, `||`, `|` and newline, leaving
67
+ * separators inside quotes alone.
68
+ *
69
+ * Deliberately NOT a shell parser. It does not expand anything, does not
70
+ * track `$(…)` nesting and does not care about redirection grammar. It
71
+ * answers one question — where might a new command begin — and the failure
72
+ * mode of getting that slightly wrong is MORE segments, each of which is
73
+ * then inspected. Over-splitting costs precision in the allow direction and
74
+ * never opens a hole, which is the direction a guard should err in.
75
+ */
76
+ export function segments(cmd: string): string[] {
77
+ // Heredoc bodies go FIRST, before anything looks for a separator. A
78
+ // heredoc is not a quote, so a `|` or `;` inside an issue body, a commit
79
+ // message or a PR description used to tear the document into fragments
80
+ // and each fragment was then read as a command — which is how a sentence
81
+ // about `workflow-state.json` came to be refused as a write to it.
82
+ cmd = stripHeredocs(cmd);
83
+ const out: string[] = [];
84
+ let cur = '';
85
+ let quote: string | null = null;
86
+ for (let i = 0; i < cmd.length; i++) {
87
+ const c = cmd[i];
88
+ if (quote) {
89
+ cur += c;
90
+ if (c === quote && cmd[i - 1] !== '\\') quote = null;
91
+ continue;
92
+ }
93
+ if (c === '"' || c === "'") {
94
+ quote = c;
95
+ cur += c;
96
+ continue;
97
+ }
98
+ if (c === ';' || c === '\n' || c === '|' || c === '&') {
99
+ if (cmd[i + 1] === c) i++; // `&&`, `||` are one separator, not two
100
+ out.push(cur);
101
+ cur = '';
102
+ continue;
103
+ }
104
+ cur += c;
105
+ }
106
+ out.push(cur);
107
+ return out.map(s => s.trim()).filter(Boolean);
108
+ }
109
+
110
+ /**
111
+ * Delete heredoc bodies, then quoted spans and their contents. Use when
112
+ * looking for a VERB.
113
+ *
114
+ * A heredoc body is the single largest source of over-blocking measured on
115
+ * this machine's history: an issue body, a commit message or a PR
116
+ * description written with `cat > f <<'EOF'` routinely QUOTES a protected
117
+ * filename, a `>` redirect or the word `chflags`, because the thing being
118
+ * written about is this guard. 1,860 real commands were newly refused before
119
+ * this stripping existed and the large majority were that shape.
120
+ */
121
+ export function stripQuoted(s: string): string {
122
+ return stripHeredocs(s).replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, ' ');
123
+ }
124
+
125
+ /**
126
+ * Delete heredoc bodies only, keeping ordinary quoting intact. Separate from
127
+ * `stripQuoted` because a quoted PATH is a real argument while a heredoc
128
+ * body never is — it is the document being written, not a word of the
129
+ * command writing it.
130
+ */
131
+ export function stripHeredocs(s: string): string {
132
+ return s.replace(/<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[\s\S]*?^\s*\2\s*$/gm, ' ');
133
+ }
134
+
135
+ /** Remove quote characters, keep the contents. Use when looking for a TARGET. */
136
+ export function dequote(s: string): string {
137
+ return s.replace(/['"]/g, '');
138
+ }
139
+
140
+ /** Wrappers that delegate to the real command word rather than being one. */
141
+ const WRAPPERS = /^(?:sudo|env|nohup|time|command|xargs)$/;
142
+
143
+ /**
144
+ * The command word of a segment — the first token that is not a wrapper, an
145
+ * assignment or an option. Read off `stripQuoted`, because a quoted token is
146
+ * an argument.
147
+ */
148
+ export function commandWord(segment: string): string {
149
+ for (const raw of stripQuoted(segment).trim().split(/\s+/)) {
150
+ const tok = raw.replace(/^.*\//, ''); // `/usr/bin/python3` -> `python3`
151
+ if (!tok || tok.includes('=') || tok.startsWith('-')) continue;
152
+ if (WRAPPERS.test(tok)) continue;
153
+ return tok;
154
+ }
155
+ return '';
156
+ }
157
+
158
+ /**
159
+ * Paths a segment writes through shell redirection or a copying verb.
160
+ *
161
+ * Redirections are read off the heredoc-stripped text, because a `>` inside
162
+ * a heredoc body is prose about a redirect, not one. The TARGET itself is
163
+ * then dequoted, because `> "x/.gate-salt"` writes the same file as `>
164
+ * x/.gate-salt`.
165
+ */
166
+ export function writeTargets(segment: string): string[] {
167
+ const targets: string[] = [];
168
+ const code = stripQuoted(segment);
169
+ // `> file` and `>> file`, but not `2>` or `&>` — those are stderr plumbing.
170
+ for (const m of code.matchAll(/(?<![2&])\s*>{1,2}\s*(\S+)/g)) {
171
+ if (m[1] && m[1] !== '/dev/null') targets.push(dequote(m[1]));
172
+ }
173
+ // A quoted redirect target survives quote-stripping as nothing at all, so
174
+ // it is recovered separately rather than lost.
175
+ for (const m of segment.matchAll(/(?<![2&])\s*>{1,2}\s*(['"])([^'"]+)\1/g)) targets.push(m[2]);
176
+ const tee = code.match(/\btee\s+(?:-a\s+)?(\S+)/);
177
+ if (tee) targets.push(dequote(tee[1]));
178
+ // `cp`/`mv` take the LAST non-option argument as the destination. Reading
179
+ // the second token instead — which this did until #1120 — mis-parses every
180
+ // invocation carrying a flag: `cp -p src /x/workflow-state.json` read the
181
+ // destination as `src` and never examined the real one.
182
+ //
183
+ // Arguments are DEQUOTED rather than stripped. Stripping them was measured
184
+ // to lose the destination entirely for `cp "a/X.hook.ts" "b/X.hook.ts"`,
185
+ // which is a real hook write that then read as having no target.
186
+ const word = commandWord(segment);
187
+ if (word === 'cp' || word === 'mv' || word === 'install' || word === 'rsync') {
188
+ const args = dequote(segment)
189
+ .trim()
190
+ .split(/\s+/)
191
+ .slice(1)
192
+ .filter(a => !a.startsWith('-'));
193
+ if (args.length >= 2) targets.push(args[args.length - 1]);
194
+ }
195
+ return targets;
196
+ }
197
+
198
+ /**
199
+ * Non-option arguments of a segment, dequoted. This is what an in-place verb
200
+ * actually operates on — as opposed to its script, which is an argument too
201
+ * but names files only as text.
202
+ */
203
+ export function argumentsOf(segment: string): string[] {
204
+ const out: string[] = [];
205
+ // Tokens that survive heredoc and quote stripping are bare words; quoted
206
+ // tokens are recovered individually so a quoted PATH still counts while a
207
+ // quoted sed SCRIPT does not reach the protected-name test as a path.
208
+ for (const t of stripQuoted(segment).trim().split(/\s+/)) {
209
+ if (t && !t.startsWith('-')) out.push(t);
210
+ }
211
+ // Heredoc bodies are stripped FIRST: a quoted path inside the document
212
+ // being written is not an argument to the command writing it.
213
+ for (const m of stripHeredocs(segment).matchAll(/(['"])([^'"\s]*[/.][^'"\s]*)\1/g)) out.push(m[2]);
214
+ return out;
215
+ }
216
+
217
+ /**
218
+ * Does a protected name sit NEAR a declared write verb in an interpreter
219
+ * body? Proximity, not parsing — the arm needs to tell
220
+ * `open('…/.gate-salt','w')` from a program that writes a `.md` and happens
221
+ * to mention a hook in its data. Associating a call with its argument
222
+ * properly means parsing the language, which this module will not do.
223
+ */
224
+ function writesNear(body: string, protectedName: string): boolean {
225
+ const WINDOW = 80;
226
+ for (const m of body.matchAll(new RegExp(protectedName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'))) {
227
+ const from = Math.max(0, (m.index ?? 0) - WINDOW);
228
+ const slice = body.slice(from, (m.index ?? 0) + protectedName.length + WINDOW);
229
+ if (WRITE_INTENT.test(slice)) return true;
230
+ }
231
+ return false;
232
+ }
233
+
234
+ /**
235
+ * Verbs that modify a named file in place, with no redirect for
236
+ * `writeTargets` to see. `sed -i` is the ordinary way to edit a file from a
237
+ * shell, so its absence was a plain hole rather than an exotic one.
238
+ */
239
+ const IN_PLACE = [
240
+ /\bsed\b[^\n]*\s-i\b/,
241
+ /\bperl\b[^\n]*\s-[a-z]*i\b/,
242
+ /\bdd\b[^\n]*\bof=/,
243
+ /\btruncate\b/,
244
+ /\brm\b/,
245
+ /\bln\b/,
246
+ /\bgit\s+(?:checkout|restore)\b/,
247
+ ];
248
+
249
+ /** Interpreters whose argument is a program this module cannot read. */
250
+ const INTERPRETERS = /^(?:python[23]?|perl|ruby|node|bun|deno|osascript|sh|bash|zsh|php)$/;
251
+
252
+ /**
253
+ * Declared write intent inside an interpreter body.
254
+ *
255
+ * The honest version of this arm would refuse any interpreter naming a
256
+ * protected artifact, since a program is opaque. That was implemented and
257
+ * MEASURED: it newly refused 1,760 of 5,060 real commands — 35% — and
258
+ * triage found them to be reads. `bun -e '…readFileSync(…workflow-state
259
+ * .json…)…'` and `python3 -I -c 'json.load(open(…))'` are how every agent
260
+ * on this machine inspects gate state, and a guard that refuses the normal
261
+ * way of looking at a thing is a guard that gets switched off.
262
+ *
263
+ * So the arm fires on a declared write VERB instead. The limit that buys is
264
+ * real and is stated rather than hidden: an interpreter can always evade
265
+ * this — build the name from pieces, `eval` it, call through a variable, or
266
+ * put the program in a file instead of `-c`. This arm raises the cost of an
267
+ * accidental write and of the obvious deliberate one. It is not a boundary,
268
+ * and `.claude/rules/checks-must-be-able-to-fail.md` would call it a
269
+ * detector narrower than what it detects. It is the widest setting the
270
+ * measured false-positive rate allows.
271
+ */
272
+ const WRITE_INTENT =
273
+ /\b(?:writeFileSync|appendFileSync|createWriteStream|copyFileSync|renameSync|unlinkSync|rmSync|truncateSync|write_text|json\.dump|os\.remove|os\.rename|os\.replace|os\.unlink|shutil\.(?:copy|move|rmtree))\b|(?<!stdout)(?<!stderr)\.write\s*\(|\bopen\s*\([^)]*['"][wax]\+?['"]/;
274
+
275
+ /** `find` actions that run or delete rather than print. */
276
+ const FIND_MUTATING = /\s-(?:delete|exec|execdir|ok|okdir)\b/;
277
+
278
+ /** Does this text name a protected artifact? Pass a DEQUOTED segment. */
279
+ function names(text: string, list: string[]): string | null {
280
+ for (const p of list) if (text.includes(p)) return p;
281
+ return null;
282
+ }
283
+
284
+ const ALL_PROTECTED = [...PROTECTED_FILES, ...PROTECTED_HOOKS];
285
+
286
+ /**
287
+ * Decide a Bash tool call.
288
+ *
289
+ * Returns `{ blocked: false }` for anything this module cannot show is a
290
+ * write to a protected artifact. That default is deliberate and is the
291
+ * reason the checks above are structural: a guard tuned so wide that people
292
+ * work around it protects nothing, and four real refusals of read-only work
293
+ * is already a pattern.
294
+ */
295
+ export function decideBashWrite(cmd: string): BashWriteDecision {
296
+ if (!cmd) return ALLOW;
297
+
298
+ for (const seg of segments(cmd)) {
299
+ const bare = dequote(seg); // TARGET view: contents kept
300
+ const code = stripQuoted(seg); // VERB view: quoted spans gone
301
+ const word = commandWord(seg);
302
+
303
+ // 1. Shell redirection and copying verbs. Never exempted by anything:
304
+ // this is the arm the old allowlist sat above, which is #1120.
305
+ for (const target of writeTargets(seg)) {
306
+ const pf = names(target, PROTECTED_FILES);
307
+ if (pf) {
308
+ return {
309
+ blocked: true,
310
+ reason: `Bash write to protected file "${pf}" blocked. Use gate-runner.ts for gate results.`,
311
+ };
312
+ }
313
+ if (names(target, PROTECTED_HOOKS)) {
314
+ return { blocked: true, reason: 'Bash write to hook file blocked. Hook integrity is protected.' };
315
+ }
316
+ }
317
+
318
+ // 2. In-place mutation. The verb is read off `code`, and the target must
319
+ // be an ARGUMENT — not any text in the segment. `sed -i '' "s/|
320
+ // X.hook.ts |/…/" NOTES.md` edits a markdown file and merely mentions
321
+ // a hook in its script; matching the whole segment refused it.
322
+ if (IN_PLACE.some(p => p.test(code))) {
323
+ const pf = names(argumentsOf(seg).join(' '), ALL_PROTECTED);
324
+ if (pf) {
325
+ return {
326
+ blocked: true,
327
+ reason: `Bash command modifies "${pf}" in place. Use gate-runner.ts for gate results.`,
328
+ };
329
+ }
330
+ }
331
+
332
+ // 3. Interpreter bodies and mutating `find`. These write with no shell
333
+ // redirect, so arm 1 sees nothing at all. See WRITE_INTENT for why
334
+ // this asks for a declared write verb rather than refusing every
335
+ // interpreter that names a protected artifact, and for what that
336
+ // concession costs.
337
+ const isInterpreter = INTERPRETERS.test(word) && /\s-[a-z]*[ce]\b/.test(code);
338
+ const isMutatingFind = word === 'find' && FIND_MUTATING.test(code);
339
+ if (isInterpreter || isMutatingFind) {
340
+ const pf = isMutatingFind
341
+ ? names(bare, ALL_PROTECTED)
342
+ : (ALL_PROTECTED.find(p => bare.includes(p) && writesNear(bare, p)) ?? null);
343
+ if (pf) {
344
+ return {
345
+ blocked: true,
346
+ reason:
347
+ `Bash command runs an interpreter or a mutating \`find\` naming "${pf}". ` +
348
+ `What it writes cannot be read off the command line, so it is refused.`,
349
+ };
350
+ }
351
+ }
352
+
353
+ // 4. Permission changes on a hook file. The COMMAND WORD must be the
354
+ // verb — not merely a `chmod` somewhere in the string, which is what
355
+ // refused four read-only commands. The target is read off `bare`, so
356
+ // quoting the path does not hide it.
357
+ if ((word === 'chmod' || word === 'chflags') && names(bare, PROTECTED_HOOKS)) {
358
+ return { blocked: true, reason: 'Permission change on hook file blocked. Hook integrity is protected.' };
359
+ }
360
+ }
361
+
362
+ // 5. The gate salt in the Keychain. Exempted by nothing — unlike `chmod`,
363
+ // which turns up innocently in docs and greps, `pai-gate-salt` beside
364
+ // `security` has no benign INVOCATION. It has a benign MENTION though,
365
+ // and two real commands hit it: issue comments quoting the very command
366
+ // they were proposing to guard. So it reads the code, not the prose.
367
+ const codeOnly = stripQuoted(cmd);
368
+ if (codeOnly.includes('pai-gate-salt') && codeOnly.includes('security')) {
369
+ return { blocked: true, reason: 'Access to gate salt Keychain entry blocked.' };
370
+ }
371
+
372
+ return ALLOW;
373
+ }
@@ -10,7 +10,7 @@
10
10
  */
11
11
 
12
12
  import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
13
- import { dirname } from "path";
13
+ import { dirname, join } from "path";
14
14
 
15
15
  // ── Types ───────────────────────────────────────────────
16
16
 
@@ -28,6 +28,20 @@ const STALE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
28
28
 
29
29
  // ── Public API ──────────────────────────────────────────
30
30
 
31
+ /**
32
+ * Where the behavioral results cache lives, for a given project root.
33
+ *
34
+ * One binding, because this path had three. `lib/agent-audit.ts` and
35
+ * `scripts/test-brief.ts` WRITE it and `scripts/sync-sc-status.ts` READS it,
36
+ * and each one assembled `join(root, ".rungate", "behavioral-results.json")`
37
+ * for itself with nothing comparing the three. A drift in any one of them
38
+ * writes where nobody reads — and the symptom, an empty cache, is
39
+ * indistinguishable from "no behavioral results recorded yet" (#328).
40
+ */
41
+ export function behavioralCachePath(projectRoot: string): string {
42
+ return join(projectRoot, ".rungate", "behavioral-results.json");
43
+ }
44
+
31
45
  /**
32
46
  * Read the behavioral results cache from disk.
33
47
  * Returns empty object if file doesn't exist or is malformed.
@@ -65,14 +79,148 @@ export function isStale(timestamp: string): boolean {
65
79
 
66
80
  /**
67
81
  * Read cache and filter out stale entries (older than 7 days).
82
+ *
83
+ * Projected off `behavioralReading` rather than asking `isStale` a second
84
+ * time. The census below answers "has this criterion been measured" and so
85
+ * does this function; two deciders that agree are behaviourally one, and a
86
+ * mutation of either would leave the other holding every case up
87
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
68
88
  */
69
89
  export function readFreshCache(path: string): BehavioralCache {
70
90
  const cache = readCache(path);
71
91
  const fresh: BehavioralCache = {};
72
92
  for (const [id, entry] of Object.entries(cache)) {
73
- if (!isStale(entry.timestamp)) {
93
+ if (behavioralReading(entry).startsWith("fresh")) {
74
94
  fresh[id] = entry;
75
95
  }
76
96
  }
77
97
  return fresh;
78
98
  }
99
+
100
+ // ── The unmeasured census (#758) ────────────────────────
101
+
102
+ /**
103
+ * What the cache says about one criterion.
104
+ *
105
+ * Four states, not two. `stale` and `absent` are both "nobody has measured
106
+ * this", but they are different facts about why and a reader can act on only
107
+ * one of them, so they are counted apart.
108
+ */
109
+ export type BehavioralReadingKind = "fresh-pass" | "fresh-fail" | "stale" | "absent";
110
+
111
+ /**
112
+ * Whether the cache file could be read at all.
113
+ *
114
+ * `readCache` returns `{}` for a file that is missing AND for one that is
115
+ * corrupt, which is the conflation this census exists to undo — a corrupt
116
+ * cache is never a missing cache (`.claude/rules/config-access.md`). Nothing
117
+ * here goes through `readCache`.
118
+ */
119
+ export type BehavioralCacheState = "absent" | "unreadable" | "present";
120
+
121
+ export interface BehavioralCensus {
122
+ /** The one discriminator. Everything else is a projection of the lists. */
123
+ reading: "MEASURED" | "UNMEASURED";
124
+ unmeasuredReasons: string[];
125
+ cacheState: BehavioralCacheState;
126
+ counts: Record<BehavioralReadingKind, number>;
127
+ /** Every criterion with no fresh reading, named — a count sends nobody anywhere. */
128
+ unmeasured: string[];
129
+ total: number;
130
+ }
131
+
132
+ /**
133
+ * What the cache says about one criterion — the ONE decider.
134
+ *
135
+ * `readFreshCache`, `behavioralPattern` and the census all route through
136
+ * this. An entry with no parseable timestamp is `absent` rather than fresh:
137
+ * a reading whose date cannot be read is a reading nobody can date, and
138
+ * `new Date("")` is `NaN`, which makes every arithmetic comparison false and
139
+ * would otherwise read as brand new.
140
+ */
141
+ export function behavioralReading(entry: CacheEntry | undefined): BehavioralReadingKind {
142
+ if (!entry || typeof entry.timestamp !== "string") return "absent";
143
+ if (Number.isNaN(new Date(entry.timestamp).getTime())) return "absent";
144
+ if (isStale(entry.timestamp)) return "stale";
145
+ return entry.passed ? "fresh-pass" : "fresh-fail";
146
+ }
147
+
148
+ /** Absent, corrupt, or readable — three facts, never folded into two. */
149
+ export function behavioralCacheState(path: string): BehavioralCacheState {
150
+ if (!existsSync(path)) return "absent";
151
+ try {
152
+ const parsed = JSON.parse(readFileSync(path, "utf-8"));
153
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return "unreadable";
154
+ return "present";
155
+ } catch {
156
+ return "unreadable";
157
+ }
158
+ }
159
+
160
+ /**
161
+ * How many ticked `(behavioral)` criteria actually have a reading (#758).
162
+ *
163
+ * #328 connected the consumption half: a fresh `passed: false` entry now
164
+ * fails the suite. Nothing guarantees an entry is ever WRITTEN — the two
165
+ * writers run during a ship run or a brief test, never during an ordinary
166
+ * `bun test` — so the live state for all 35 ticked behavioral criteria is
167
+ * "no reading", which routed to `behavioral`: reported, ratcheted, and not
168
+ * checked.
169
+ *
170
+ * A criterion nobody has measured and a criterion that passed are different
171
+ * states and only one is reportable, but both were green and a reader could
172
+ * not tell which they had. This is the supply end of *Silent Default
173
+ * Substitution*, and the fix is #597's: not to make the measurement happen,
174
+ * but to make the report say it did not.
175
+ */
176
+ export function behavioralCensus(ids: string[], path: string): BehavioralCensus {
177
+ const state = behavioralCacheState(path);
178
+ const cache: BehavioralCache = state === "present"
179
+ ? JSON.parse(readFileSync(path, "utf-8"))
180
+ : {};
181
+
182
+ const counts: Record<BehavioralReadingKind, number> = {
183
+ "fresh-pass": 0, "fresh-fail": 0, stale: 0, absent: 0,
184
+ };
185
+ const unmeasured: string[] = [];
186
+
187
+ for (const id of ids) {
188
+ const kind = behavioralReading(cache[id]);
189
+ counts[kind]++;
190
+ if (kind === "stale" || kind === "absent") unmeasured.push(id);
191
+ }
192
+
193
+ const reasons: string[] = [];
194
+ // An empty population agrees with every bound. Said first, because the two
195
+ // counts below are both 0 for a census that collected nothing and for one
196
+ // in which everything was measured.
197
+ if (ids.length === 0) reasons.push("no ticked (behavioral) criteria were collected — the scan read nothing");
198
+ if (state === "absent") reasons.push("the behavioral results cache does not exist, so no criterion has a reading");
199
+ if (state === "unreadable") reasons.push("the behavioral results cache exists and could not be parsed");
200
+ if (counts.stale > 0) reasons.push(`${counts.stale} criterion(s) have only a stale reading, older than the 7-day threshold`);
201
+ if (counts.absent > 0 && state === "present") reasons.push(`${counts.absent} criterion(s) have no entry in the cache`);
202
+
203
+ return {
204
+ reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
205
+ unmeasuredReasons: reasons,
206
+ cacheState: state,
207
+ counts,
208
+ unmeasured,
209
+ total: ids.length,
210
+ };
211
+ }
212
+
213
+ /**
214
+ * The census as one line for the suite output (#758 SC-1).
215
+ *
216
+ * A figure, not a line per criterion: 35 log lines is something a reader
217
+ * scrolls past, and the number is the thing that moves.
218
+ */
219
+ export function behavioralCensusLine(c: BehavioralCensus): string {
220
+ const m = c.counts["fresh-pass"] + c.counts["fresh-fail"];
221
+ return (
222
+ `BEHAVIORAL: ${c.reading} — ${m}/${c.total} criteria have a fresh reading ` +
223
+ `(pass ${c.counts["fresh-pass"]}, fail ${c.counts["fresh-fail"]}, ` +
224
+ `stale ${c.counts.stale}, no entry ${c.counts.absent}; cache ${c.cacheState})`
225
+ );
226
+ }